@smbcloud / cli
Code Commits Issues Pulls Cloud Agent CI/CD
feature/cicd
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
md 302 lines 9.24 KB
Rendered Raw
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 - npm release workflow: `.github/workflows/release-npm.yml`
23 - PyPI release workflow: `.github/workflows/release-pypi.yml`
24 - npm platform package generator: `npm/scripts/render-platform-package.cjs`
25 - npm wrapper package generator: `npm/scripts/render-main-package.cjs`
26 - npm wrapper launcher: `npm/smbcloud-cli/src/index.ts`
27 - PyPI package metadata: `pypi/pyproject.toml`
28 - PyPI package README: `pypi/README.md`
29
30 ## Release model
31
32 There are two public distribution channels.
33
34 ### 1. npm
35
36 npm has two package layers. Publish them in order.
37
38 Platform binary packages:
39
40 - `@smbcloud/cli-darwin-arm64`
41 - `@smbcloud/cli-darwin-x64`
42 - `@smbcloud/cli-linux-x64`
43 - `@smbcloud/cli-windows-arm64`
44 - `@smbcloud/cli-windows-x64`
45
46 Wrapper package:
47
48 - `@smbcloud/cli`
49
50 The wrapper package resolves the right platform package with `require.resolve(...)`.
51 Do not publish `@smbcloud/cli` before the required platform packages for that version exist.
52
53 ### 2. PyPI
54
55 PyPI uses one package:
56
57 - `smbcloud-cli`
58
59 It is built from `pypi/pyproject.toml` with `maturin` and `bindings = "bin"`, so the published wheel installs the native `smb` executable directly.
60
61 ## Local npm release workflow
62
63 ### Preflight
64
65 1. Confirm npm auth with `npm whoami`.
66 2. Confirm the crate version in `crates/cli/Cargo.toml`.
67 3. Use the same version string for every npm package in that release.
68
69 ### Build platform binaries
70
71 Build each target first:
72
73 - `cargo build --release --locked --target aarch64-apple-darwin`
74 - `cargo build --release --locked --target x86_64-apple-darwin`
75 - or the matching Linux or Windows target in CI
76
77 ### Generate platform package
78
79 From `npm/`:
80
81 - run `node ./scripts/render-platform-package.cjs <pkg> <version> <os> <arch>`
82 - create `<pkg>/bin`
83 - copy the built `smb` binary into `bin/`
84 - on Windows, use `smb.exe`
85
86 Example:
87
88 - `node ./scripts/render-platform-package.cjs cli-darwin-arm64 0.3.33 darwin arm64`
89
90 ### Publish order
91
92 1. Publish each platform package with `npm publish --access public`
93 2. Generate `npm/smbcloud-cli/package.json` with `render-main-package.cjs`
94 3. Run `npm install`
95 4. Run `npm run build`
96 5. Publish `@smbcloud/cli`
97
98 ## Local PyPI release workflow
99
100 ### Tooling
101
102 Use `uv` for local `maturin` installation in this repo.
103
104 Install:
105
106 - `uv tool install maturin`
107
108 Upgrade later if needed:
109
110 - `uv tool upgrade maturin`
111
112 If the shell cannot find `maturin`, use:
113
114 - `uv tool run maturin --version`
115
116 ### Preflight
117
118 1. Confirm the crate version in `crates/cli/Cargo.toml`.
119 2. Make sure `.env` exists with `CLI_CLIENT_SECRET=...` because the Rust build reads it at compile time.
120 3. If publishing from a local machine, use a PyPI API token. Trusted publishing is for CI.
121
122 ### Build and upload
123
124 From `pypi/`:
125
126 - `maturin build --release --locked --compatibility pypi --out dist`
127 - `maturin upload dist/*`
128
129 Or publish in one step:
130
131 - `maturin publish --release --locked --compatibility pypi`
132
133 For local uploads, export `MATURIN_PYPI_TOKEN` before running `maturin upload` or `maturin publish`.
134
135 ### Publishing the smb stub (one-time)
136
137 The stub lives in `pypi/smb-stub/` and is built with `hatchling`, not `maturin`. It only needs to be published once — it never changes.
138
139 ```sh
140 cd pypi/smb-stub
141 pip install hatchling build twine
142 python -m build
143 twine upload dist/*
144 ```
145
146 Or with uv:
147
148 ```sh
149 cd pypi/smb-stub
150 uv run --with build python -m build
151 uv run --with twine twine upload dist/*
152 ```
153
154 Use a PyPI API token with upload scope for `smb`. Trusted publishing is not required for a static stub.
155
156 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.
157
158 ### Local publishing constraint
159
160 A local publish normally builds only for the current platform.
161
162 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.
163
164 ## npm 2FA
165
166 Publishing may fail with `EOTP`.
167
168 When that happens, retry the exact `npm publish` command with:
169
170 - `--otp=<code>`
171
172 Do not assume the first publish failed before the package upload step. Check the exit result or npm registry state before retrying repeatedly.
173
174 ## Trusted publishing
175
176 ### npm
177
178 Prefer npm trusted publishers for CI over `NPM_TOKEN`.
179
180 Official references:
181
182 - https://docs.npmjs.com/trusted-publishers/
183 - https://docs.npmjs.com/cli/v11/commands/npm-trust/
184
185 ### npm-side constraints
186
187 Trusted publishing can only be configured for packages that already exist on npm.
188
189 That means:
190
191 - publish a package once manually if it does not exist yet
192 - then configure trust for that package
193 - each package can have only one trusted publisher configuration at a time
194
195 For `smbcloud-cli`, configure trust per package, not only for `@smbcloud/cli`.
196
197 Example packages:
198
199 - `@smbcloud/cli`
200 - `@smbcloud/cli-darwin-arm64`
201 - later, each additional published `@smbcloud/cli-*` package
202
203 ### GitHub Actions setup
204
205 The workflow must include:
206
207 - `permissions:`
208 - `id-token: write`
209 - `contents: read`
210
211 Do not pass `NODE_AUTH_TOKEN` to `npm publish` when using trusted publishing.
212
213 The npm CLI detects the GitHub OIDC environment automatically and exchanges it for a short-lived publish credential.
214
215 ### Trusted publisher command
216
217 For this repo, the trust relationship should point at:
218
219 - repository: `smbcloudXYZ/smbcloud-cli`
220 - workflow file: `release-npm.yml`
221
222 Example:
223
224 - `npm trust github @smbcloud/cli --repo smbcloudXYZ/smbcloud-cli --file release-npm.yml --yes`
225 - `npm trust github @smbcloud/cli-darwin-arm64 --repo smbcloudXYZ/smbcloud-cli --file release-npm.yml --yes`
226
227 These commands may require npm 2FA and support `--otp=<code>`.
228
229 ### Migration guidance
230
231 Recommended order:
232
233 1. enable trusted publishing for existing packages
234 2. verify a CI publish works through OIDC
235 3. then remove or stop using `NPM_TOKEN`
236 4. after the migration is proven, tighten npm package publishing access if desired
237
238 Do not remove the manual publish path for brand-new package names, because npm trust cannot be configured before the first publish.
239
240 ### PyPI
241
242 Use trusted publishing in GitHub Actions through `pypa/gh-action-pypi-publish@release/v1`.
243 Do not use trusted publishing as the default local-machine publish path.
244
245 ## CI/CD workflow rules
246
247 ### Shared rules
248
249 For both release workflows:
250
251 - `runs-on` must use `matrix.build.OS` when the matrix uses upper-case keys
252 - derive `RELEASE_VERSION` from the git tag when `GITHUB_REF_TYPE=tag`
253 - for `workflow_dispatch`, fall back to the version in `crates/cli/Cargo.toml`
254 - read the Rust toolchain from `rust-toolchain.toml`
255 - pass that exact toolchain into `dtolnay/rust-toolchain`
256 - run `rustup target add <target> --toolchain ${{ env.RUST_TOOLCHAIN }}` before cross-target builds
257
258 ### npm workflow
259
260 The npm workflow lives in `.github/workflows/release-npm.yml`.
261
262 Important rules:
263
264 - avoid `envsubst` for package generation across runners
265 - use the Node generator scripts instead
266 - use `npm install` and `npm run build` for the wrapper package job
267
268 ### PyPI workflow
269
270 The PyPI workflow lives in `.github/workflows/release-pypi.yml`.
271
272 Important rules:
273
274 - build wheels with `PyO3/maturin-action@v1`
275 - use `working-directory: pypi`
276 - pass `target: ${{ matrix.build.TARGET }}`
277 - use `manylinux: ${{ matrix.build.MANYLINUX || 'off' }}`
278 - build the sdist in a separate job
279 - publish only after wheel and sdist artifacts are downloaded into one directory
280
281 ## Rust toolchain consistency
282
283 When cross-compiling in CI, the Rust toolchain used for `rustup target add` must match the toolchain used by `cargo build` or `maturin`.
284
285 For this repo, `rust-toolchain.toml` is the only Rust version source of truth.
286
287 If the workflow installs a target for one toolchain but builds with another, CI can fail with:
288
289 - `error[E0463]: can't find crate for core`
290
291 ## macOS cross-build constraint
292
293 On an Apple Silicon host, `x86_64-apple-darwin` may fail due to `openssl-sys` if only arm64 Homebrew OpenSSL exists under `/opt/homebrew`.
294
295 If that happens:
296
297 - do not claim the x64 package is releasable from that machine
298 - either build on an Intel Mac
299 - or use a Rosetta or x86 Homebrew toolchain with Intel OpenSSL under `/usr/local/opt/openssl@3`
300 - or publish only the arm64 platform package and explicitly avoid calling the release complete
301
302 Do not publish `@smbcloud/cli` for a version unless you accept that missing platform packages for that version can break installs on those platforms.