feature/project-new-structure
claude/smbcloud-github-app-k9641p
development
feature/apps
feature/build-release
feature/ci-docs
feature/ci-ruby-gems
feature/cicd
feature/completion
feature/dist-nuget
feature/fix-ci-sdk-pypi-rubygem
feature/fix-clippy-on-stable-channel
feature/fix-deployment-script
feature/github-email
feature/gresiq-v1
feature/project-new-structure
feature/rsync-deploy
feature/ruby-runner
feature/sdk-npm
feature/sdk-workflows
feature/smbcloud-cli-release-npm
feature/smbcloud-deploy
feature/wasm
main
release/v0.7.4
| 1 | --- |
| 2 | name: smbcloud-cli-release |
| 3 | description: Use when building, packaging, or releasing smbCloud CLI binaries through npm, PyPI, or GitHub Actions CI/CD. Covers the Rust binary release source of truth, the npm wrapper and platform packages, the PyPI `maturin` package under `pypi/`, local publishing with `uv tool install maturin`, and fixes to `.github/workflows/release-npm.yml` or `.github/workflows/release-pypi.yml`. |
| 4 | --- |
| 5 | |
| 6 | # smbcloud CLI Release |
| 7 | |
| 8 | Use this skill when work touches any part of the smbCloud CLI distribution flow: |
| 9 | |
| 10 | - local npm release for `smbcloud-cli` |
| 11 | - local PyPI release for `smbcloud-cli` |
| 12 | - GitHub Actions npm release automation |
| 13 | - GitHub Actions PyPI release automation |
| 14 | - Rust binary packaging into npm platform packages or PyPI wheels |
| 15 | - release failures caused by macOS cross-compilation, missing package metadata, npm 2FA, or PyPI trusted publishing setup |
| 16 | |
| 17 | ## Source of truth |
| 18 | |
| 19 | Use these files as the release source of truth: |
| 20 | |
| 21 | - Rust crate version and binary name: `crates/cli/Cargo.toml` |
| 22 | - Workspace crate dependency versions: `Cargo.toml` under `[workspace.dependencies]` |
| 23 | - SDK WASM crate version: `crates/smbcloud-auth-sdk-wasm/Cargo.toml` |
| 24 | - SDK npm package version: `sdk/npm/smbcloud-auth/package.json` |
| 25 | - SDK npm build script: `sdk/npm/smbcloud-auth/prepare-package.mjs` |
| 26 | - npm release workflow: `.github/workflows/release-npm.yml` |
| 27 | - PyPI release workflow: `.github/workflows/release-pypi.yml` |
| 28 | - npm platform package generator: `npm/scripts/render-platform-package.cjs` |
| 29 | - npm wrapper package generator: `npm/scripts/render-main-package.cjs` |
| 30 | - npm wrapper launcher: `npm/smbcloud-cli/src/index.ts` |
| 31 | - npm wrapper committed package metadata: `npm/smbcloud-cli/package.json` |
| 32 | - npm wrapper committed lockfile: `npm/smbcloud-cli/package-lock.json` |
| 33 | - PyPI package metadata: `pypi/pyproject.toml` |
| 34 | - PyPI package README: `pypi/README.md` |
| 35 | - SDK PyPI package metadata: `sdk/python/pyproject.toml` |
| 36 | - SDK Ruby gem auth version: `sdk/gems/auth/lib/auth/version.rb` |
| 37 | - SDK Ruby gem auth native extension: `sdk/gems/auth/ext/auth/Cargo.toml` |
| 38 | - SDK Ruby gem model version: `sdk/gems/model/lib/model/version.rb` |
| 39 | - SDK Ruby gem model native extension: `sdk/gems/model/ext/model/Cargo.toml` |
| 40 | |
| 41 | ## Version sync rules |
| 42 | |
| 43 | The SDK npm package `@smbcloud/sdk-auth` must have its version in `sdk/npm/smbcloud-auth/package.json` match the version in `crates/smbcloud-auth-sdk-wasm/Cargo.toml` exactly. The `prepare-package.mjs` script enforces this at build time and will fail CI if they diverge. |
| 44 | |
| 45 | When bumping workspace crate versions for a release, also update the version constraints in the root `Cargo.toml` under `[workspace.dependencies]` so every `smbcloud-*` path dependency points at the same release version. |
| 46 | |
| 47 | When bumping workspace crate versions for a release, always update `sdk/npm/smbcloud-auth/package.json` in the same commit. |
| 48 | |
| 49 | The npm wrapper package is generated, but its checked-in files still need to match the release version before tagging: |
| 50 | |
| 51 | - rerender `npm/smbcloud-cli/package.json` with `node ../scripts/render-main-package.cjs ./package.json <version>` |
| 52 | - refresh `npm/smbcloud-cli/package-lock.json` with `npm install` |
| 53 | - commit both files so CI and local packaging agree on the wrapper version and optional dependency versions |
| 54 | |
| 55 | The same applies to the Ruby gems in `sdk/gems/`. For each gem (`auth`, `model`): |
| 56 | |
| 57 | - `lib/<gem>/version.rb` — the gem version constant |
| 58 | - `ext/<gem>/Cargo.toml` — the native extension crate version AND the `smbcloud-*` dependency version constraints (e.g. `"0.3"` → `"0.4"`) |
| 59 | - Regenerate `Cargo.lock` with `cargo generate-lockfile` and `Gemfile.lock` with `bundle lock` inside the gem directory |
| 60 | |
| 61 | ## Tagging discipline |
| 62 | |
| 63 | Always tag releases on the `development` branch (the mainline). Never tag on a feature branch. |
| 64 | |
| 65 | Reasoning: |
| 66 | |
| 67 | - The release commit history stays clean and linear on the default branch. |
| 68 | - `cargo workspaces publish --allow-branch "*"` accepts any branch, but downstream workflows dispatch from the tag ref, so the tagged commit must contain all intended changes. |
| 69 | - Tagging on a feature branch leaves `development` without the release commit and makes git history confusing. |
| 70 | |
| 71 | Workflow: |
| 72 | |
| 73 | 1. Merge the feature branch into `development` with `--no-ff`. |
| 74 | 2. Tag on `development`: `git tag v<version>`. |
| 75 | 3. Push both: `git push origin development && git push origin v<version>`. |
| 76 | |
| 77 | If a tag was placed on the wrong commit (e.g. before a last-minute fix), move it: |
| 78 | |
| 79 | 1. Merge the fix into `development`. |
| 80 | 2. Recreate the annotated tag on the correct commit: `git tag -fa v<version> -m "v<version>"`. |
| 81 | 3. Force-push the tag: `git push origin v<version> --force`. |
| 82 | |
| 83 | When verifying the remote tag, remember that annotated tags have two refs. `git ls-remote --tags origin refs/tags/v<version>*` should show: |
| 84 | |
| 85 | - `refs/tags/v<version>` — the tag object |
| 86 | - `refs/tags/v<version>^{}` — the peeled commit |
| 87 | |
| 88 | The peeled `^{}` ref is the one that must match the intended release commit. |
| 89 | |
| 90 | The `release-crate.yml` orchestrator triggers on `push.tags: "v*.*.*"`, so the force-push will re-trigger the full release chain. |
| 91 | |
| 92 | ## Release model |
| 93 | |
| 94 | There are two public distribution channels. |
| 95 | |
| 96 | ### 1. npm |
| 97 | |
| 98 | npm has two package layers. Publish them in order. |
| 99 | |
| 100 | Platform binary packages: |
| 101 | |
| 102 | - `@smbcloud/cli-darwin-arm64` |
| 103 | - `@smbcloud/cli-darwin-x64` |
| 104 | - `@smbcloud/cli-linux-x64` |
| 105 | - `@smbcloud/cli-windows-arm64` |
| 106 | - `@smbcloud/cli-windows-x64` |
| 107 | |
| 108 | Wrapper package: |
| 109 | |
| 110 | - `@smbcloud/cli` |
| 111 | |
| 112 | The wrapper package resolves the right platform package with `require.resolve(...)`. |
| 113 | Do not publish `@smbcloud/cli` before the required platform packages for that version exist. |
| 114 | |
| 115 | ### 2. PyPI |
| 116 | |
| 117 | PyPI uses one package: |
| 118 | |
| 119 | - `smbcloud-cli` |
| 120 | |
| 121 | It is built from `pypi/pyproject.toml` with `maturin` and `bindings = "bin"`, so the published wheel installs the native `smb` executable directly. |
| 122 | |
| 123 | ## Local npm release workflow |
| 124 | |
| 125 | ### Preflight |
| 126 | |
| 127 | 1. Confirm npm auth with `npm whoami`. |
| 128 | 2. Confirm the crate version in `crates/cli/Cargo.toml`. |
| 129 | 3. Use the same version string for every npm package in that release. |
| 130 | 4. Rerender `npm/smbcloud-cli/package.json` and refresh `npm/smbcloud-cli/package-lock.json` before tagging if the wrapper version changed. |
| 131 | |
| 132 | ### Build platform binaries |
| 133 | |
| 134 | Build each target first: |
| 135 | |
| 136 | - `cargo build --release --locked --target aarch64-apple-darwin` |
| 137 | - `cargo build --release --locked --target x86_64-apple-darwin` |
| 138 | - or the matching Linux or Windows target in CI |
| 139 | |
| 140 | ### Generate platform package |
| 141 | |
| 142 | From `npm/`: |
| 143 | |
| 144 | - run `node ./scripts/render-platform-package.cjs <pkg> <version> <os> <arch>` |
| 145 | - create `<pkg>/bin` |
| 146 | - copy the built `smb` binary into `bin/` |
| 147 | - on Windows, use `smb.exe` |
| 148 | |
| 149 | Example: |
| 150 | |
| 151 | - `node ./scripts/render-platform-package.cjs cli-darwin-arm64 0.3.39 darwin arm64` |
| 152 | |
| 153 | ### Publish order |
| 154 | |
| 155 | 1. Publish each platform package with `npm publish --access public` |
| 156 | 2. Generate `npm/smbcloud-cli/package.json` with `render-main-package.cjs` |
| 157 | 3. Run `npm install` |
| 158 | 4. Run `npm run build` |
| 159 | 5. Publish `@smbcloud/cli` |
| 160 | |
| 161 | ## Local PyPI release workflow |
| 162 | |
| 163 | ### Tooling |
| 164 | |
| 165 | Use `uv` for local `maturin` installation in this repo. |
| 166 | |
| 167 | Install: |
| 168 | |
| 169 | - `uv tool install maturin` |
| 170 | |
| 171 | Upgrade later if needed: |
| 172 | |
| 173 | - `uv tool upgrade maturin` |
| 174 | |
| 175 | If the shell cannot find `maturin`, use: |
| 176 | |
| 177 | - `uv tool run maturin --version` |
| 178 | |
| 179 | ### Preflight |
| 180 | |
| 181 | 1. Confirm the crate version in `crates/cli/Cargo.toml`. |
| 182 | 2. Make sure `.env` exists with `CLI_CLIENT_SECRET=...` because the Rust build reads it at compile time. |
| 183 | 3. If publishing from a local machine, use a PyPI API token. Trusted publishing is for CI. |
| 184 | |
| 185 | ### Build and upload |
| 186 | |
| 187 | From `pypi/`: |
| 188 | |
| 189 | - `maturin build --release --locked --compatibility pypi --out dist` |
| 190 | - `maturin upload dist/*` |
| 191 | |
| 192 | Or publish in one step: |
| 193 | |
| 194 | - `maturin publish --release --locked --compatibility pypi` |
| 195 | |
| 196 | For local uploads, export `MATURIN_PYPI_TOKEN` before running `maturin upload` or `maturin publish`. |
| 197 | |
| 198 | ### Publishing the smb stub (one-time) |
| 199 | |
| 200 | The stub lives in `pypi/smb-stub/` and is built with `hatchling`, not `maturin`. It only needs to be published once — it never changes. |
| 201 | |
| 202 | ```sh |
| 203 | cd pypi/smb-stub |
| 204 | pip install hatchling build twine |
| 205 | python -m build |
| 206 | twine upload dist/* |
| 207 | ``` |
| 208 | |
| 209 | Or with uv: |
| 210 | |
| 211 | ```sh |
| 212 | cd pypi/smb-stub |
| 213 | uv run --with build python -m build |
| 214 | uv run --with twine twine upload dist/* |
| 215 | ``` |
| 216 | |
| 217 | Use a PyPI API token with upload scope for `smb`. Trusted publishing is not required for a static stub. |
| 218 | |
| 219 | Do not republish the stub on every CLI release. It permanently depends on the unpinned `smbcloud-cli`, so uv always resolves the latest version when the tool environment is created or upgraded. |
| 220 | |
| 221 | ### Local publishing constraint |
| 222 | |
| 223 | A local publish normally builds only for the current platform. |
| 224 | |
| 225 | Do not claim a full PyPI release is complete from one machine unless you intentionally published only one platform or separately produced all required wheels. |
| 226 | |
| 227 | ## npm 2FA |
| 228 | |
| 229 | Publishing may fail with `EOTP`. |
| 230 | |
| 231 | When that happens, retry the exact `npm publish` command with: |
| 232 | |
| 233 | - `--otp=<code>` |
| 234 | |
| 235 | Do not assume the first publish failed before the package upload step. Check the exit result or npm registry state before retrying repeatedly. |
| 236 | |
| 237 | ## Trusted publishing |
| 238 | |
| 239 | ### npm |
| 240 | |
| 241 | Prefer npm trusted publishers for CI over `NPM_TOKEN`. |
| 242 | |
| 243 | Official references: |
| 244 | |
| 245 | - https://docs.npmjs.com/trusted-publishers/ |
| 246 | - https://docs.npmjs.com/cli/v11/commands/npm-trust/ |
| 247 | |
| 248 | ### npm-side constraints |
| 249 | |
| 250 | Trusted publishing can only be configured for packages that already exist on npm. |
| 251 | |
| 252 | That means: |
| 253 | |
| 254 | - publish a package once manually if it does not exist yet |
| 255 | - then configure trust for that package |
| 256 | - each package can have only one trusted publisher configuration at a time |
| 257 | |
| 258 | For `smbcloud-cli`, configure trust per package, not only for `@smbcloud/cli`. |
| 259 | |
| 260 | Example packages: |
| 261 | |
| 262 | - `@smbcloud/cli` |
| 263 | - `@smbcloud/cli-darwin-arm64` |
| 264 | - later, each additional published `@smbcloud/cli-*` package |
| 265 | |
| 266 | ### GitHub Actions setup |
| 267 | |
| 268 | The workflow must include: |
| 269 | |
| 270 | - `permissions:` |
| 271 | - `id-token: write` |
| 272 | - `contents: read` |
| 273 | |
| 274 | Do not pass `NODE_AUTH_TOKEN` to `npm publish` when using trusted publishing. |
| 275 | |
| 276 | The npm CLI detects the GitHub OIDC environment automatically and exchanges it for a short-lived publish credential. |
| 277 | |
| 278 | ### Trusted publisher command |
| 279 | |
| 280 | For this repo, the trust relationship should point at: |
| 281 | |
| 282 | - repository: `smbcloudXYZ/smbcloud-cli` |
| 283 | - workflow file: `release-npm.yml` |
| 284 | |
| 285 | Example: |
| 286 | |
| 287 | - `npm trust github @smbcloud/cli --repo smbcloudXYZ/smbcloud-cli --file release-npm.yml --yes` |
| 288 | - `npm trust github @smbcloud/cli-darwin-arm64 --repo smbcloudXYZ/smbcloud-cli --file release-npm.yml --yes` |
| 289 | |
| 290 | These commands may require npm 2FA and support `--otp=<code>`. |
| 291 | |
| 292 | ### Migration guidance |
| 293 | |
| 294 | Recommended order: |
| 295 | |
| 296 | 1. enable trusted publishing for existing packages |
| 297 | 2. verify a CI publish works through OIDC |
| 298 | 3. then remove or stop using `NPM_TOKEN` |
| 299 | 4. after the migration is proven, tighten npm package publishing access if desired |
| 300 | |
| 301 | Do not remove the manual publish path for brand-new package names, because npm trust cannot be configured before the first publish. |
| 302 | |
| 303 | ### PyPI |
| 304 | |
| 305 | Use trusted publishing in GitHub Actions through `pypa/gh-action-pypi-publish@release/v1`. |
| 306 | Do not use trusted publishing as the default local-machine publish path. |
| 307 | |
| 308 | ## CI/CD workflow rules |
| 309 | |
| 310 | ### Shared rules |
| 311 | |
| 312 | For both release workflows: |
| 313 | |
| 314 | - `runs-on` must use `matrix.build.OS` when the matrix uses upper-case keys |
| 315 | - derive `RELEASE_VERSION` from the git tag when `GITHUB_REF_TYPE=tag` |
| 316 | - for `workflow_dispatch`, fall back to the version in `crates/cli/Cargo.toml` |
| 317 | - read the Rust toolchain from `rust-toolchain.toml` |
| 318 | - pass that exact toolchain into `dtolnay/rust-toolchain` |
| 319 | - run `rustup target add <target> --toolchain ${{ env.RUST_TOOLCHAIN }}` before cross-target builds |
| 320 | |
| 321 | ### npm workflow |
| 322 | |
| 323 | The npm workflow lives in `.github/workflows/release-npm.yml`. |
| 324 | |
| 325 | Important rules: |
| 326 | |
| 327 | - avoid `envsubst` for package generation across runners |
| 328 | - use the Node generator scripts instead |
| 329 | - use `npm install` and `npm run build` for the wrapper package job |
| 330 | |
| 331 | ### PyPI workflow |
| 332 | |
| 333 | The PyPI workflow lives in `.github/workflows/release-pypi.yml`. |
| 334 | |
| 335 | Important rules: |
| 336 | |
| 337 | - build wheels with `PyO3/maturin-action@v1` |
| 338 | - use `working-directory: pypi` |
| 339 | - pass `target: ${{ matrix.build.TARGET }}` |
| 340 | - use `manylinux: ${{ matrix.build.MANYLINUX || 'off' }}` |
| 341 | - build the sdist in a separate job |
| 342 | - publish only after wheel and sdist artifacts are downloaded into one directory |
| 343 | |
| 344 | ## Rust toolchain consistency |
| 345 | |
| 346 | When cross-compiling in CI, the Rust toolchain used for `rustup target add` must match the toolchain used by `cargo build` or `maturin`. |
| 347 | |
| 348 | For this repo, `rust-toolchain.toml` is the only Rust version source of truth. |
| 349 | |
| 350 | If the workflow installs a target for one toolchain but builds with another, CI can fail with: |
| 351 | |
| 352 | - `error[E0463]: can't find crate for core` |
| 353 | |
| 354 | ## macOS cross-build constraint |
| 355 | |
| 356 | On an Apple Silicon host, `x86_64-apple-darwin` may fail due to `openssl-sys` if only arm64 Homebrew OpenSSL exists under `/opt/homebrew`. |
| 357 | |
| 358 | If that happens: |
| 359 | |
| 360 | - do not claim the x64 package is releasable from that machine |
| 361 | - either build on an Intel Mac |
| 362 | - or use a Rosetta or x86 Homebrew toolchain with Intel OpenSSL under `/usr/local/opt/openssl@3` |
| 363 | - or publish only the arm64 platform package and explicitly avoid calling the release complete |
| 364 | |
| 365 | Do not publish `@smbcloud/cli` for a version unless you accept that missing platform packages for that version can break installs on those platforms. |