putitoutthere 0.2.36 → 0.2.37

package/CHANGELOG.md

@@ -16,6 +16,7 @@ are prefixed `**BREAKING**` and link to the matching section in
 
 ### Fixed
 
+- Fixed: `kind = "npm"` `build = "napi"` releases now bake the planned release version into the compiled `.node`. `_matrix.yml` (and its e2e mirror `e2e-fixture-job.yml`) run a `write-crate-version` step on each per-triple napi row before `npm run build`, so `napi build` compiles the addon with the right `CARGO_PKG_VERSION` — matching the maturin `write-version` (#276) and bundled-cli `write-crate-version` (#366) pre-build bumps. Previously napi had no pre-build bump: the synthesized per-platform `package.json` carried `matrix.version`, but the `.node` inside it embedded whatever literal sat in the crate's `Cargo.toml`, so a library re-exposing the Rust core's `version()` through napi reported a version diverging from the published npm package. The bump targets `matrix.path` and runs only when a `Cargo.toml` is colocated there (the napi-rs single-crate default — the shape template-lib and the `js-napi` fixture use), resolving `version.workspace = true` to the workspace root via #428. A multi-mode package (`build = ["napi", "bundled-cli"]`) or one whose napi crate lives elsewhere has no `Cargo.toml` at the package path and is skipped with a `::notice::` — there is no per-napi `crate_path` config to point at a non-colocated crate yet, so that `.node` still embeds its on-disk version. The noarch `main` row is excluded (it compiles no `.node`). See [MIGRATIONS.md](./MIGRATIONS.md#napi-node-embeds-the-release-version). #429. (verified by: unit/ubuntu-latest)
 - Fixed: `putitoutthere`'s pre-build version rewrite now follows Cargo **workspace version inheritance** — a crate that sources its version from `[workspace.package].version` via `version.workspace = true` (the idiomatic polyglot layout: one Rust core wrapped by a PyO3 wheel and a napi addon) is now bumped correctly instead of failing the release. The maturin `write-version` (#276) and npm/pypi bundled-cli `write-crate-version` (#366) steps both rewrote only a literal `[package].version` and threw `Cargo.toml: no [package].version field found` on an inheriting member, because the inherited version lives in a different file — the workspace root — that neither step read. So a release for that layout was blocked, not merely mis-versioned. The rewrite path now resolves the manifest first: a literal `[package].version` is bumped in place byte-for-byte as before, while an inheriting member walks up to the nearest ancestor `[workspace]` `Cargo.toml` and rewrites its `[workspace.package].version`. Unparseable or version-less manifests fall through to the prior literal-only path (`replaceCargoVersion`'s existing error), so single-crate layouts are byte-for-byte unchanged. New `src/find-workspace-root.ts`, `src/replace-workspace-package-version.ts`, and `src/write-resolved-cargo-version.ts`; `write-version.ts` / `write-crate-version.ts` now delegate to the resolver. See [MIGRATIONS.md](./MIGRATIONS.md#version-bump-follows-cargo-workspace-inheritance). #428. (verified by: unit/ubuntu-latest)
 - Fixed: `putitoutthere publish` now writes a package's git tag when that version is already live on the registry but untagged, instead of skipping it silently. The publish loop's already-published branch (`isPublished` → true) returned *before* the tag-creation step, so a version that reached the registry on a half-failed run (the run died after publishing but before tagging — e.g. a cancelled downstream job) was left published-but-untagged and never self-healed: piot derives "last released version" from git tags, so on every later run the package looked unreleased, fell back to `first_version` (already live), skipped again, and stayed stuck forever — while its dependents kept bumping and publishing, opening unflagged version skew. The skip branch now calls a shared, idempotent `ensureTag` (new `src/ensure-tag.ts`; a no-op when the tag already exists, and reused by the normal post-publish tag step), so a stuck package self-heals on its next release run. See [MIGRATIONS.md](./MIGRATIONS.md#publish-path-auto-heal-missing-tags). #407. (verified by: integration, unit/ubuntu-latest)
 - Fixed: a `kind = "pypi"` `build = "maturin"` package whose wheel is **Python-version-independent** — `[tool.maturin].bindings = "bin"` (a Rust-binary wheel tagged `py3-none`) or a pyo3 `abi3` / `abi3-pyXY` extension (a stable-ABI wheel tagged `cp3x-abi3`) — no longer fans its wheel build across every CPython version `requires-python` / `python_versions` resolves to. Such a wheel is byte-identical regardless of the interpreter that built it, so the fan produced N duplicate wheels: each fanned row uploaded under its own `-py<ver>` artifact, and the documented consumer `pypi-publish` recipe's `actions/download-artifact … merge-multiple: true` then extracted N copies of the same wheel filename onto one path concurrently — a torn write that failed `twine check` with `zipfile.BadZipFile` (observed on a `bindings = "bin"`, `requires-python = ">=3.9"` package: six identical wheels per platform, the x86_64-linux copy losing its extraction race while macOS/aarch64 won theirs). The planner (`src/plan.ts`) now collapses the fan to a single wheel row per target for these packages — built once on the newest resolved interpreter, keeping the historical unsuffixed `<pkg>-wheel-<triple>` artifact name — and the new `src/wheel-abi.ts` detects version independence from the package's real `pyproject.toml` (`[tool.maturin].bindings`, `[tool.maturin].features`) and `Cargo.toml` (an `abi3` / `abi3-pyXY` feature on the `pyo3` / `pyo3-ffi` dependency). Ordinary per-version extension modules (no abi3, no `bindings = "bin"`) still fan and keep their `-py<ver>` suffixes; the sdist row is unchanged. Also saves the redundant N−1 wheel builds. Detection is conservative — an unrecognized abi3 setup (workspace-inherited `pyo3`, a target-specific dependency table) falls back to fanning, never worse than before. See [README → `kind = "pypi"`](./README.md#kind--pypi) and [MIGRATIONS.md](./MIGRATIONS.md#pypi-version-independent-wheels-build-once). #401. (verified by: integration, unit/ubuntu-latest)

package/MIGRATIONS.md

@@ -21,6 +21,40 @@ Each section covers five things, in order:
 
 ## Unreleased
 
+### napi `.node` embeds the release version
+
+**Summary.** `kind = "npm"` `build = "napi"` releases now rewrite the napi
+crate's version to the planned release version before `napi build` compiles
+the `.node`, mirroring the maturin (#276) and bundled-cli (#366) pre-build
+bumps. Previously the compiled `.node` embedded whatever `[package].version`
+literal sat on disk, so a library re-exposing the Rust core's `version()`
+through napi reported a version diverging from the published npm package
+(whose `package.json` version was already correct).
+
+**Required changes.** None for the common case. The bump is a
+workflow-internal step; a consumer whose napi crate's `Cargo.toml` is
+colocated with `package.json` (the napi-rs single-crate default, including
+the `version.workspace = true` workspace shape via #428) needs no config
+change. A **multi-mode** package (`build = ["napi", "bundled-cli"]`) or one
+whose napi crate lives outside the package directory has no `Cargo.toml` at
+the package path — piot skips the bump there with a `::notice::` (no
+per-napi `crate_path` config exists yet), so such a `.node` still embeds
+its on-disk `CARGO_PKG_VERSION`. Until a `crate_path` field lands, bump that
+crate's version yourself or colocate its manifest with `package.json`.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** For a napi package, the
+per-platform `.node` now reports the released version from any API sourced
+on `CARGO_PKG_VERSION` (e.g. a Rust `version()` re-exported through napi).
+The synthesized per-platform `package.json` version is unchanged (it was
+already `matrix.version`). Non-napi npm packages are unaffected.
+
+**Verification.** Release a napi package and read its Rust-sourced
+`version()` from the installed addon (or inspect the crate manifest the
+build rewrote): it matches the published npm version, not the pre-release
+on-disk literal.
+
 ### Version bump follows Cargo workspace inheritance
 
 **Summary.** piot's pre-build version rewrite — the maturin `write-version`

package/README.md

@@ -310,7 +310,7 @@ version = 1   # required; only 1 is valid today
 | `npm`     | string                 | Override `name` → npm name (for scoped packages).    |
 | `access`  | enum                   | `public` \| `restricted`. Default `public`.          |
 | `tag`     | string                 | dist-tag. Default `latest`.                          |
-| `build`   | string \| array        | `"napi"` \| `"bundled-cli"` (single mode), or an array of entries (each: a bare mode string or `{ mode, name }` with a [name template](#multi-mode-npm-family)). Omitted = vanilla. See [Recipes → Bundled-CLI npm family](#bundled-cli-npm-family). |
+| `build`   | string \| array        | `"napi"` \| `"bundled-cli"` (single mode), or an array of entries (each: a bare mode string or `{ mode, name }` with a [name template](#multi-mode-npm-family)). Omitted = vanilla. See Recipes → [napi](#napi-npm-family) / [Bundled-CLI](#bundled-cli-npm-family) npm family. |
 | `targets` | (string \| object)[]   | Required when `build` is set.                        |
 | `[package.bundle_cli]` | sub-table | Declarative cross-compile for `build = "bundled-cli"` rows. Fields: `bin` (required), `crate_path` (default `"."`), `features` (default `[]`), `no_default_features` (default `false`). See [Recipes → Bundled-CLI npm family](#bundled-cli-npm-family). |
 
@@ -747,6 +747,86 @@ registration (a policy on `my-cli` does not cover
 > No consumer-side change is required; you can keep the lockfile
 > committed and the `optionalDependencies` declared.
 
+### napi npm family
+
+Ship a [napi-rs](https://napi.rs) Node addon (a `.node` native library) as
+an npm per-platform family — consumers `import` the package and Node loads
+the prebuilt binary for their platform. The `@node-rs/*` / `@swc/core`
+distribution shape.
+
+Config:
+
+```toml
+[[package]]
+name    = "my-addon"
+kind    = "npm"
+path    = "packages/node"
+build   = "napi"
+globs   = ["packages/node/**", "crates/core/**"]
+targets = [
+  "x86_64-unknown-linux-gnu",
+  "aarch64-unknown-linux-gnu",
+  "x86_64-apple-darwin",
+  "aarch64-apple-darwin",
+  "x86_64-pc-windows-msvc",
+]
+```
+
+The engine publishes a per-platform sub-package per target
+(`my-addon-<triple>`) plus a top-level package whose `optionalDependencies`
+pin them at the published version; napi-rs's loader resolves the matching
+one at runtime. The reusable workflow fans the build across your `targets`
+— one native runner per triple — so you never wire per-target steps
+yourself.
+
+**You own the build script.** Unlike `bundled-cli` — where the engine runs
+the cross-compile for you — the napi toolchain stays consumer-owned. For
+each per-target row the workflow runs your `package.json` `build` script
+with `TARGET` set to that triple (and `BUILD=napi`); your script runs
+`napi build` for it and stages the resulting `.node` under
+`build/<triple>/`, the directory the engine packages per-platform
+artifacts from:
+
+```js
+// scripts/build.cjs — invoked by your package.json "build" script
+const target = process.env.TARGET;
+// The noarch main row runs with TARGET=main (or unset) — nothing to build.
+if (!target || target === 'main' || target === 'noarch') process.exit(0);
+
+// napi-rs emits `<name>.<triple>.node`; stage it under build/<triple>/,
+// e.g.  napi build --release --target ${target} --output-dir build/${target}
+```
+
+The `main` (noarch) row carries no per-target binary — its build run is a
+no-op for the `.node` and compiles only your TypeScript / JS.
+
+> [!NOTE]
+> **Cross-compilation is yours to arrange.** Each target builds on a
+> native runner where one exists (`x86_64-linux` on `ubuntu-latest`,
+> `aarch64-linux` on `ubuntu-24.04-arm`, darwin on `macos-latest`,
+> windows on `windows-2022`), so the common triples need no cross
+> toolchain — `napi build --target <native triple>` just works. For a
+> target that isn't native to its runner (a `*-musl` triple, or an
+> x86_64 macOS build on the arm64 runner), your build script owns
+> `rustup target add <triple>` and any linker / C-toolchain setup. This
+> is the one place napi differs from `bundled-cli`, where the engine
+> performs the gnu→musl mapping and installs the musl toolchain for you.
+
+Each per-platform sub-package needs its own npm trusted-publisher
+registration (a policy on `my-addon` does not cover
+`my-addon-x86_64-unknown-linux-gnu`) — same as the bundled-cli family
+above.
+
+The **first-publish lockfile chicken-and-egg** note under
+[Bundled-CLI npm family](#bundled-cli-npm-family) applies identically to
+napi families: the reusable workflow's strict installs self-heal, so you
+can keep the lockfile committed and the `optionalDependencies` declared.
+
+> [!NOTE]
+> **Both modes at once.** A package that is *both* a `.node` addon and a
+> CLI declares `build` as an array — see
+> [Multi-mode npm family](#multi-mode-npm-family) below.
+
 ### Multi-mode npm family
 
 For a package that is both a napi-rs Node addon (a `.node` library) **and**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "putitoutthere",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "description": "Polyglot release orchestrator for crates.io, PyPI, and npm",
   "license": "MIT",
   "repository": {