Weftos Build Deploy

WeftOS Build & Deploy Skill

You are the WeftOS release engineer. You handle builds, tagging, publishing, and deployment across all distribution channels.

Project Identity

• Repo: weave-logic-ai/weftos (GitHub)
• Binaries: weft (CLI), weaver (operator), weftos (kernel daemon)
• Naming: clawft-* = framework crates, weftos = product facade
• Workspace version: single version in [workspace.package] in root Cargo.toml

Distribution Channels

Secrets & Auth

NEVER commit .env or expose tokens in logs.

Common Tasks

Full Release (new version)

This is the most common operation. It publishes everywhere.

1. Bump version:

   • Edit [workspace.package] version in root Cargo.toml
   • Run cargo check --workspace to verify
   • Commit: git add Cargo.toml Cargo.lock && git commit -m "chore: bump workspace version to X.Y.Z"
   • Push: git push origin master

2. Tag (triggers cargo-dist automatically):

   git tag vX.Y.Z
   git push origin vX.Y.Z
   

3. Monitor (~12-14 min for all platforms):

   gh run list --repo weave-logic-ai/weftos --limit 2
   gh run view <RUN_ID> --repo weave-logic-ai/weftos
   

4. Verify release:

   gh release view vX.Y.Z --repo weave-logic-ai/weftos
   

5. Publish to crates.io (manual, not automated by CI):

   source .env && cargo login "$CRATES_API_TOKEN"
   

   Publish in dependency order with ~10 min gaps (crates.io rate limit for new crates):

   1. clawft-types        (leaf)
   2. clawft-platform     (-> types)
   3. clawft-plugin       (leaf)
   4. clawft-llm          (-> types)
   5. exo-resource-tree   (leaf)
   6. clawft-core         (-> types, platform, llm, plugin)
   7. clawft-kernel       (-> core, types, platform, plugin, exo-resource-tree)
   8. weftos              (-> all above)
   

   Command: cargo publish -p <crate-name>

   Rate limit: ~1 new crate per 10 min window. Existing crate version bumps are not rate-limited.

6. Publish to npm (manual):

   source .env
   echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
   wasm-pack build crates/clawft-wasm --scope weftos --target web --features browser
   

   Fix package.json in crates/clawft-wasm/pkg/:

   • Ensure name is @weftos/core
   • Ensure repository.url is https://github.com/weave-logic-ai/weftos
   • Ensure version matches the release

   cd crates/clawft-wasm/pkg && npm publish --access public
   

Patch Release (hotfix)

Same as full release but only bump patch version (e.g., 0.1.1 -> 0.1.2).

Re-tag (if a release fails mid-pipeline)

git tag -d vX.Y.Z                    # delete local tag
git push origin :refs/tags/vX.Y.Z    # delete remote tag
# fix the issue, commit, push to master
git tag vX.Y.Z                       # re-create tag on new HEAD
git push origin vX.Y.Z               # triggers fresh release

Publish Only crates.io (no binary release)

If you only changed library code and need to update crates.io without a binary release:

source .env && cargo login "$CRATES_API_TOKEN"
cargo publish -p <crate-name>

No tag needed. Version in Cargo.toml must be bumped and not already published.

Publish Only npm (WASM update)

source .env
echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
wasm-pack build crates/clawft-wasm --scope weftos --target web --features browser
# Edit pkg/package.json: name=@weftos/core, version, repo URL
cd crates/clawft-wasm/pkg && npm publish --access public

Verify Installation

# Binary (download from release)
gh release download vX.Y.Z --repo weave-logic-ai/weftos \
  --pattern 'clawft-cli-aarch64-unknown-linux-gnu.tar.gz' --dir /tmp/test
tar xzf /tmp/test/clawft-cli-*.tar.gz -C /tmp/test
/tmp/test/clawft-cli-*/weft --version
/tmp/test/clawft-cli-*/weft status
/tmp/test/clawft-cli-*/weft tools list

# Homebrew
brew install weave-logic-ai/tap/clawft-cli
weft --version

# Docker
docker pull ghcr.io/weave-logic-ai/weftos:X.Y.Z
docker run --rm ghcr.io/weave-logic-ai/weftos:X.Y.Z --version

# crates.io
cargo install weftos
weftos --version

# npm
npm info @weftos/core version

What cargo-dist Does Automatically (on tag push)

1. Plan — reads [workspace.metadata.dist], resolves targets
2. Build — compiles 3 binaries on 5 platforms:
   • x86_64-unknown-linux-gnu (~5 min)
   • aarch64-unknown-linux-gnu (~5 min, cross-compiled)
   • x86_64-apple-darwin (~14 min, slowest)
   • aarch64-apple-darwin (~7 min)
   • x86_64-pc-windows-msvc (~10 min)
3. Global artifacts — SHA256 checksums, shell + PowerShell installers
4. Host — creates GitHub Release with all artifacts
5. Homebrew — pushes .rb formulae to weave-logic-ai/homebrew-tap
6. Announce — marks release as published

Docker runs in parallel via release-docker.yml (~2h for multi-arch QEMU build).

crates.io Dependency Graph

weftos-rvf-crypto 0.3.0  (our ML-DSA fork — depends on rvf-types)
weftos-rvf-wire 0.2.0    (our fork — depends on rvf-types 0.2)
rvf-types 0.2.0           (upstream ruvnet)
rvf-runtime 0.2.0         (upstream ruvnet)
ruvector-cluster 2.0.6    (upstream ruvnet)
ruvector-raft 2.0.6       (upstream ruvnet)
ruvector-replication 2.0.6 (upstream ruvnet)
cognitum-gate-tilezero 0.1.1 (upstream ruvnet)

clawft-types 0.1.x       (leaf)
clawft-platform 0.1.x    (-> clawft-types)
clawft-plugin 0.1.x      (leaf)
clawft-llm 0.1.x         (-> clawft-types)
exo-resource-tree 0.1.x  (leaf)
clawft-core 0.1.x        (-> types, platform, llm, plugin)
clawft-kernel 0.1.x      (-> core, platform, types, plugin, exo-resource-tree,
                           weftos-rvf-crypto, weftos-rvf-wire, rvf-types,
                           rvf-runtime, ruvector-*, cognitum-gate-tilezero)
weftos 0.1.x             (facade -> kernel, core, types, platform, exo-resource-tree)

Cargo.toml Key Sections

Workspace version (must match tag)

[workspace.package]
version = "X.Y.Z"
repository = "https://github.com/weave-logic-ai/weftos"

Workspace deps (version + path for publishability)

clawft-types = { version = "X.Y.Z", path = "crates/clawft-types", default-features = false }

cargo-dist config

[profile.dist]
inherits = "release"

[workspace.metadata.dist]
cargo-dist-version = "0.31.0"
ci = "github"
targets = [
    "x86_64-unknown-linux-gnu",
    "aarch64-unknown-linux-gnu",
    "x86_64-apple-darwin",
    "aarch64-apple-darwin",
    "x86_64-pc-windows-msvc",
]
installers = ["shell", "powershell", "homebrew"]
tap = "weave-logic-ai/homebrew-tap"
publish-jobs = ["homebrew"]
github-attestations = true

Gotchas & Hard-Won Knowledge

1. Tag must match workspace version — v0.1.1 tag requires version = "0.1.1" in Cargo.toml. cargo-dist errors with "nothing to Release" otherwise.

2. [profile.dist] must exist — cargo-dist uses this profile, not release. Missing = "profile dist is not defined" error.

3. repository URL in Cargo.toml — cargo-dist bakes this into installer shell scripts as the download URL. Wrong URL = installer downloads from nonexistent repo. Always verify after repo renames.

4. Windows builds — clawft-weave (weaver) daemon uses Unix sockets and nix signals. All gated behind #[cfg(unix)]. Windows gets stub DaemonClient::connect() that returns None (query commands fall through to ephemeral kernel). The nix crate is under [target.'cfg(unix)'.dependencies].

5. LICENSE file — must exist at repo root with exact name LICENSE. The glob LICENSE* in cargo-dist include config fails because cargo-dist treats it literally.

6. crates.io rate limit — max ~1 new crate per 10-minute window. Version bumps of existing crates are not limited. Plan publish order accordingly.

7. npm 2FA — requires granular access token with "Bypass 2FA on publish" enabled for the @weftos scope. Regular tokens get 403.

8. Docker multi-arch — takes 30-60 min (arm64 via QEMU emulation). Runs in parallel with cargo-dist, doesn't block the binary release.

9. weftos-rvf-crypto / weftos-rvf-wire — our forks of upstream rvf-crypto / rvf-wire published under new names because we don't own the upstream crate names on crates.io. If upstream catches up with ML-DSA support, we can switch back to their names.

10. Workspace deps need version + path — { version = "X.Y.Z", path = "crates/..." } for crates.io publishability. Path alone works locally but cargo publish rejects it.

Docker

• Base image: gcr.io/distroless/cc-debian12 (no shell, minimal attack surface)
• Multi-stage build: cargo-chef for dep caching -> builder -> distroless runtime
• Platforms: linux/amd64, linux/arm64
• Tags: X.Y.Z, X.Y, X, latest
• Health check: weft status (exec form, no shell)
• Registry: ghcr.io/weave-logic-ai/weftos

Platform Support

Source: weave-logic-ai/weftos — distributed by TomeVault.