@smbcloud / cli
Code Commits Issues Pulls Cloud Agent CI/CD
feature/gresiq-v1
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 279 lines 8.56 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 ### Local publishing constraint
136
137 A local publish normally builds only for the current platform.
138
139 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.
140
141 ## npm 2FA
142
143 Publishing may fail with `EOTP`.
144
145 When that happens, retry the exact `npm publish` command with:
146
147 - `--otp=<code>`
148
149 Do not assume the first publish failed before the package upload step. Check the exit result or npm registry state before retrying repeatedly.
150
151 ## Trusted publishing
152
153 ### npm
154
155 Prefer npm trusted publishers for CI over `NPM_TOKEN`.
156
157 Official references:
158
159 - https://docs.npmjs.com/trusted-publishers/
160 - https://docs.npmjs.com/cli/v11/commands/npm-trust/
161
162 ### npm-side constraints
163
164 Trusted publishing can only be configured for packages that already exist on npm.
165
166 That means:
167
168 - publish a package once manually if it does not exist yet
169 - then configure trust for that package
170 - each package can have only one trusted publisher configuration at a time
171
172 For `smbcloud-cli`, configure trust per package, not only for `@smbcloud/cli`.
173
174 Example packages:
175
176 - `@smbcloud/cli`
177 - `@smbcloud/cli-darwin-arm64`
178 - later, each additional published `@smbcloud/cli-*` package
179
180 ### GitHub Actions setup
181
182 The workflow must include:
183
184 - `permissions:`
185 - `id-token: write`
186 - `contents: read`
187
188 Do not pass `NODE_AUTH_TOKEN` to `npm publish` when using trusted publishing.
189
190 The npm CLI detects the GitHub OIDC environment automatically and exchanges it for a short-lived publish credential.
191
192 ### Trusted publisher command
193
194 For this repo, the trust relationship should point at:
195
196 - repository: `smbcloudXYZ/smbcloud-cli`
197 - workflow file: `release-npm.yml`
198
199 Example:
200
201 - `npm trust github @smbcloud/cli --repo smbcloudXYZ/smbcloud-cli --file release-npm.yml --yes`
202 - `npm trust github @smbcloud/cli-darwin-arm64 --repo smbcloudXYZ/smbcloud-cli --file release-npm.yml --yes`
203
204 These commands may require npm 2FA and support `--otp=<code>`.
205
206 ### Migration guidance
207
208 Recommended order:
209
210 1. enable trusted publishing for existing packages
211 2. verify a CI publish works through OIDC
212 3. then remove or stop using `NPM_TOKEN`
213 4. after the migration is proven, tighten npm package publishing access if desired
214
215 Do not remove the manual publish path for brand-new package names, because npm trust cannot be configured before the first publish.
216
217 ### PyPI
218
219 Use trusted publishing in GitHub Actions through `pypa/gh-action-pypi-publish@release/v1`.
220 Do not use trusted publishing as the default local-machine publish path.
221
222 ## CI/CD workflow rules
223
224 ### Shared rules
225
226 For both release workflows:
227
228 - `runs-on` must use `matrix.build.OS` when the matrix uses upper-case keys
229 - derive `RELEASE_VERSION` from the git tag when `GITHUB_REF_TYPE=tag`
230 - for `workflow_dispatch`, fall back to the version in `crates/cli/Cargo.toml`
231 - read the Rust toolchain from `rust-toolchain.toml`
232 - pass that exact toolchain into `dtolnay/rust-toolchain`
233 - run `rustup target add <target> --toolchain ${{ env.RUST_TOOLCHAIN }}` before cross-target builds
234
235 ### npm workflow
236
237 The npm workflow lives in `.github/workflows/release-npm.yml`.
238
239 Important rules:
240
241 - avoid `envsubst` for package generation across runners
242 - use the Node generator scripts instead
243 - use `npm install` and `npm run build` for the wrapper package job
244
245 ### PyPI workflow
246
247 The PyPI workflow lives in `.github/workflows/release-pypi.yml`.
248
249 Important rules:
250
251 - build wheels with `PyO3/maturin-action@v1`
252 - use `working-directory: pypi`
253 - pass `target: ${{ matrix.build.TARGET }}`
254 - use `manylinux: ${{ matrix.build.MANYLINUX || 'off' }}`
255 - build the sdist in a separate job
256 - publish only after wheel and sdist artifacts are downloaded into one directory
257
258 ## Rust toolchain consistency
259
260 When cross-compiling in CI, the Rust toolchain used for `rustup target add` must match the toolchain used by `cargo build` or `maturin`.
261
262 For this repo, `rust-toolchain.toml` is the only Rust version source of truth.
263
264 If the workflow installs a target for one toolchain but builds with another, CI can fail with:
265
266 - `error[E0463]: can't find crate for core`
267
268 ## macOS cross-build constraint
269
270 On an Apple Silicon host, `x86_64-apple-darwin` may fail due to `openssl-sys` if only arm64 Homebrew OpenSSL exists under `/opt/homebrew`.
271
272 If that happens:
273
274 - do not claim the x64 package is releasable from that machine
275 - either build on an Intel Mac
276 - or use a Rosetta or x86 Homebrew toolchain with Intel OpenSSL under `/usr/local/opt/openssl@3`
277 - or publish only the arm64 platform package and explicitly avoid calling the release complete
278
279 Do not publish `@smbcloud/cli` for a version unless you accept that missing platform packages for that version can break installs on those platforms.