Runbook: SDK Publishing & Release to Public Registries (crates.io & npm)

This runbook documents the release and publishing workflow for the official vsms SDKs:

• Rust SDK: vsms-sdk-rust on crates.io

• Node.js SDK: @vaam-apps/vsms-node on npm

---

1. Release Architecture & Triggers

SDK publishing is automated via .github/workflows/release.yml.

Trigger	Workflow Behavior	Target
git tag v*.. (e.g. v0.1.0)	Full Release: builds and publishes container images, Helm charts, crates.io crate, and npm package	Production Registries
push to main	Continuous Integration / Staging images (no SDK publishing)	GHCR (:main, :sha-*)
workflow_dispatch	Manual smoke test: performs dry-runs of cargo publish --dry-run and pnpm publish --dry-run	None (Dry Run)

---

2. Secrets & Registry Authentication

The automated release workflow requires the following repository secrets configured in GitHub repository settings (Settings › Secrets and variables › Actions):

A. crates.io (vsms-sdk-rust)

• Secret Name: CRATES_IO_TOKEN

• Source: Generate an API token on crates.io/settings/tokens with publish-update / publish-new permissions for vsms-sdk-rust.

B. npm (@vaam-apps/vsms-node)

• Secret Name: NPM_TOKEN

• Source: Generate an Automation access token on npmjs.com with publish access to the @vymalo organization scope.

• Provenance: The workflow publishes with --provenance via GitHub Actions OpenID Connect (id-token: write permission).

---

3. Pre-Release Verification (Local Dry-Run)

Before cutting a release tag, run local verification checks:

1. Rust SDK (vsms-sdk-rust)

# Ensure vendored schema is up to date
cargo xtask sdk-schema-check

# Run crate checks and dry-run packaging
cd sdks/rust/vsms-sdk-rust
cargo check
cargo test
cargo publish --dry-run

2. Node.js SDK (@vaam-apps/vsms-node)

The package’s signed transport is sdks/rust/vsms-sdk-wasm compiled to WebAssembly and shipped inside it (wasm/), so the build needs Rust with the wasm32-unknown-unknown target and the wasm-bindgen command-line tool at exactly the version sdks/rust/Cargo.lock pins: just wasm-tools installs both (release.yml’s `publish-node-sdk job runs the same recipe).

cargo xtask sdk-parity-check
just wasm-tools
cd sdks/node/vsms-sdk-node
pnpm install
pnpm run build
pnpm run typecheck
pnpm run test
pnpm pack --dry-run
pnpm publish --dry-run --no-git-checks

---

4. Cutting a Release

To release a new version of the SDKs:

1. Bump versions in:

   • sdks/rust/vsms-sdk-rust/Cargo.toml (version = "x.y.z")

   • sdks/node/vsms-sdk-node/package.json ("version": "x.y.z")

2. Commit and merge changes to main.

3. Create and push a git tag:

   git tag v0.1.0
   git push upstream v0.1.0

4. Monitor GitHub Actions:

   • Check the release workflow execution under the Actions tab.

   • Verify publish-rust-sdk completes and crate is live on https://crates.io/crates/vsms-sdk-rust.

   • Verify publish-node-sdk completes and package is live on https://www.npmjs.com/package/@vaam-apps/vsms-node.