@testspectra/cli 1.1.8-rc.2 → 1.1.8-rc.21

package/README.md

@@ -37,6 +37,53 @@ pnpm --filter @testspectra/cli dev
 
 ---
 
+## 🌍 Native Binary Distribution (Multiplatform Releases)
+
+`spectra run` shells out to `testspectra-runner`, a native Rust binary (`core/`) — it isn't
+portable JS, so one npm package can't ship a single binary that works on every OS/arch. Instead,
+`@testspectra/cli` follows the same pattern as esbuild/swc/turbo:
+
+- `@testspectra/cli` itself ships **no native binary** — only the JS launcher (`bin/spectra.js`).
+- The binary is published as four separate, platform-locked packages under `cli/npm/`:
+  - `@testspectra/cli-darwin-arm64`
+  - `@testspectra/cli-win32-x64`
+  - `@testspectra/cli-win32-arm64`
+  - `@testspectra/cli-linux-x64`
+
+  Each has `os`/`cpu` fields in its `package.json`, so npm/pnpm/yarn only ever download the one
+  matching the installing machine.
+- `@testspectra/cli` lists all four as `optionalDependencies`, pinned to an exact version (not
+  `^`) that always matches the `@testspectra/cli` release it ships with.
+- At runtime, `RustCoreBridge.resolveBinaryPath()` (`cli/src/runner/bridge.ts`) resolves the
+  binary from whichever platform package got installed (`require.resolve('@testspectra/cli-<platform>/package.json')`),
+  falling back to the monorepo's local build output (`core/target/release/...`) for local dev
+  where no optional package is installed.
+- If a user's platform/arch isn't one of the four above, install succeeds (optional deps just
+  get skipped) but `resolveBinaryPath()` throws a clear "not supported" error at run time.
+
+### Building & releasing all platforms
+
+`scripts/build-cross-platform-binaries.js` builds the binary for all four platforms from a
+single macOS machine and copies each into `cli/npm/<platform>/bin/`:
+
+- **macOS arm64** — native `cargo build` (this machine only builds arm64; there's no x64 macOS
+  package).
+- **Windows x64 / arm64** — cross-compiled via [`cargo-xwin`](https://github.com/rust-cross/cargo-xwin)
+  (`cargo install cargo-xwin`), which downloads the MSVC CRT/Windows SDK bits needed for linking.
+  reqwest's default `native-tls` backend uses Schannel on Windows, so no OpenSSL cross-compile
+  headaches here.
+- **Linux x64 (glibc)** — cross-compiled via [`cross`](https://github.com/cross-rs/cross)
+  (`cargo install cross --git https://github.com/cross-rs/cross`), which builds inside a Docker
+  container that already has a matching glibc + OpenSSL for the target — required because
+  `native-tls` needs OpenSSL on Linux and cross-compiling OpenSSL from macOS directly is painful.
+  Docker must be running for this step.
+
+`scripts/release-cli-local.sh` runs this automatically, then stamps every `cli/npm/*/package.json`
+and `cli/package.json`'s `optionalDependencies` with the target version, packs all five tarballs,
+and (with `--publish`) publishes the four platform packages before `@testspectra/cli` itself.
+
+---
+
 ## 💻 CLI Commands Summary
 
 | Command           | Usage                                       | Description                                                             |

package/bin/.testspectra-runner.hash

@@ -1 +1 @@
-ee8892a6b2c4c19bf5da415da3d29172023c383de2d12c0080b5dc61dc339af3
+2db95c618fc201b3c5e4b2f56e93c5e5fca36ba0d31250c65c98aabed5385361