putitoutthere 0.2.12 → 0.2.14

package/CHANGELOG.md

@@ -32,6 +32,8 @@ are prefixed `**BREAKING**` and link to the matching section in
 
 ### Fixed
 
+- **Bundled-CLI / napi npm consumers' `npm run build` step now sees `TARGET` and `BUILD` env vars on every matrix row.** The reusable workflow's `_matrix.yml` and `release.yml` previously ran the npm build step with no env block, so consumers' build scripts that read `process.env.TARGET` to know which triple to cross-compile saw `undefined` and either crashed or silently no-oped. Every per-platform matrix row then uploaded an empty `build/<triple>/` directory and `actions/upload-artifact@v7` flagged `No files were found with the provided path: ...`. The internal `e2e-fixture-job.yml` already passed `TARGET` / `BUILD` correctly — meaning the fixture suite passed but a real consumer's first publish still failed; an integration-tier divergence rather than a behavior bug per se. Both the build matrix step and the publish-job rebuild step in `release.yml` now set the env block. `_matrix.yml` exposes `TARGET=${{ matrix.target }}` / `BUILD=${{ matrix.build }}` per row; `release.yml`'s rebuild loop sets `TARGET=main BUILD=` per iteration (the publish-time rebuild only fires for the main package's row, since per-platform sub-packages stage from `artifacts/` via the engine's npm-platform handler). The README's [Bundled-CLI npm family](./README.md#bundled-cli-npm-family) recipe gained the consumer-side build-script contract that was previously missing — TARGET/BUILD vocabulary and a minimal `scripts/build.cjs` covering the simple single-workspace case. Hit in the wild on `thekevinscott/darkfactory`'s first release; tracked at #287. See [MIGRATIONS.md](./MIGRATIONS.md#npm-build-step-target-build-env-vars).
+
 - **pypi/maturin `[package.bundle_cli]` now actually ships the bundled binary inside published wheels.** The recipe was advertised as shipped in v0.2.0 (#217) — config parsing accepted `[package.bundle_cli]`, the planner attached it to per-target wheel rows, and `MIGRATIONS.md` named the two scaffolded build steps consumers should expect. None of those steps existed in `.github/workflows/_matrix.yml`. Consumers who declared the block (us, in `thekevinscott/dirsql`) shipped wheels missing the binary; `pip install <pkg> && <pkg> ...` failed at runtime with `FileNotFoundError`. The reusable workflow's build job now, for every per-target wheel row that carries `matrix.bundle_cli`: (1) `rustup target add ${{ matrix.target }}`, (2) `cargo build --release --target ${{ matrix.target }} --bin ${{ matrix.bundle_cli.bin }}` against `crate_path`, (3) copies the resulting binary into `${{ matrix.path }}/${{ matrix.bundle_cli.stage_to }}/` so maturin's `[tool.maturin].include` glob picks it up as wheel data, and (4) runs a permanent post-build wheel-content guard that opens the produced `.whl` and refuses to upload-artifact if `<stage_to>/<bin>` is missing. The guard is independent of staging — it catches any future regression where the cross-compile silently routes the binary to the wrong path. Consumers do not need to change their existing `[package.bundle_cli]` config or their `[tool.maturin].include` glob; the recipe just starts working. The cross-compile assumes the binary is buildable with a vanilla `cargo build --release --bin <bin>` (no `--features`, no env, no special flags); crates that gate the CLI behind a Cargo feature are not yet supported. The `.exe` suffix on Windows is handled. See [README → Recipes → Rust CLI inside a PyPI wheel](./README.md#rust-cli-inside-a-pypi-wheel) and [MIGRATIONS.md](./MIGRATIONS.md#bundle_cli-now-actually-stages-the-binary). #282.
 
 - **`putitoutthere.toml` validation now names common typos in the failure message.** A consumer integration shipped a config with `version` at the file root, `[[packages]]` (plural), `registry =` instead of `kind =`, and `files =` instead of `globs =`. The raw zod errors (`Invalid input: expected object, received undefined; ...; Unrecognized keys: "version", "packages"`) were opaque enough that the engine source had to be re-read to recover. A pre-pass in `parseConfig` now detects each of those four mistakes by name and emits a hint that pairs the wrong shape with the right one, e.g. `top-level table is \`[[packages]]\` (plural) but should be \`[[package]]\` (singular)`. README's [Drop in `putitoutthere.toml`](./README.md#2-drop-in-putitoutthere-toml) section grew a four-row "wrong → right" table covering the same four traps so the docs and the engine name them the same way; a new `[!IMPORTANT]` callout in [Drop in `.github/workflows/release.yml`](./README.md#1-drop-in-githubworkflowsreleaseyml) warns consumers off `push: branches: [main]` triggers on lane CI workflows (which fire duplicate runs against the merge commit and contend for runners with `release.yml`); `1b.` was promoted from "Optional" to "Recommended" since `build.yml` is the cheapest place to catch a malformed config before merge. See [MIGRATIONS.md](./MIGRATIONS.md#friendly-config-error-hints).

package/MIGRATIONS.md

@@ -21,6 +21,58 @@ Each section covers five things, in order:
 
 ## Unreleased
 
+### npm build step: TARGET / BUILD env vars
+
+**Summary.** The reusable workflow's `_matrix.yml` and `release.yml`
+now set `TARGET=${{ matrix.target }}` and `BUILD=${{ matrix.build }}`
+on the `matrix.kind == 'npm'` build step (and `TARGET=main BUILD=`
+on `release.yml`'s publish-job rebuild loop, which only ever runs
+for the main package's row). Bundled-CLI / napi consumers' build
+scripts read these env vars to know which triple to cross-compile
+and which build mode is active; without them, every per-platform
+matrix row produced an empty `build/<triple>/` directory and
+`actions/upload-artifact@v7` reported
+`No files were found with the provided path: ...`. The internal
+`e2e-fixture-job.yml` already passed `TARGET` / `BUILD` for the
+`js-bundled-cli` fixture, so the fixture suite was green while the
+shape it advertised was broken for real consumers. Tracked at #287;
+hit in the wild on `thekevinscott/darkfactory`'s first release.
+
+The README's [Bundled-CLI npm family](./README.md#bundled-cli-npm-family)
+recipe gained the consumer-side build-script contract that was
+previously missing: a documented `scripts/build.cjs` template
+that reads `TARGET`, runs `rustup target add` + `cargo build`
++ stage-into-`build/<triple>/`, and no-ops on
+`TARGET=main`. Without that section, consumers had to read the
+`js-bundled-cli` test fixture or experiment to discover the
+contract.
+
+**Required changes.** None for consumers whose existing build
+script either ignored `TARGET` or used a different env var name —
+those scripts now get the `TARGET` / `BUILD` exports too but
+nothing forces them to read. To start using the contract, mirror
+the README's `scripts/build.cjs` shape and reference it from
+`package.json`'s `scripts.build` field. Existing fixtures and
+the engine's contract are unchanged.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** The npm build step
+now runs with `TARGET` and `BUILD` set in its environment.
+Build scripts that previously saw `undefined` and either crashed
+or silently no-oped will now see a defined string. Vanilla npm
+consumers (no `build = "bundled-cli" | "napi"`) see
+`TARGET=main BUILD=` (or `BUILD=undefined` on rows that don't
+declare a build mode); their build scripts that don't read either
+var are unaffected.
+
+**Verification.** A bundled-cli consumer following the README
+recipe sees their per-platform matrix rows produce non-empty
+artifacts: each `<pkg>-npm-<triple>` upload contains
+`build/<triple>/<bin-name>`. The release run's `Upload artifact`
+step no longer logs `No files were found with the provided path`
+for any npm row.
+
 ### `[package.bundle_cli]` now actually stages the binary
 
 **Summary.** Wheels published from a maturin pypi package that

package/README.md

@@ -483,6 +483,65 @@ const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
 process.exit(result.status ?? 1);
 ```
 
+You also author a `build` script in `package.json` that does the
+cross-compile. The reusable workflow runs the build matrix once
+per `(target × main)` row, sets `TARGET=<triple>` /
+`BUILD=bundled-cli` on the build step, and expects the script to
+stage the compiled binary under `build/<triple>/<bin-name>` (with
+`.exe` suffix on Windows). For every per-target row the engine
+then packages `build/<triple>/` as the platform sub-package's
+artifact; the `main` row is a no-op for the build script (the
+launcher above is committed source). A minimal `package.json`:
+
+```json
+{
+  "name": "my-cli",
+  "scripts": {
+    "build": "node scripts/build.cjs"
+  },
+  "bin": { "my-cli": "bin/my-cli.js" }
+}
+```
+
+`scripts/build.cjs`:
+
+```js
+const { execFileSync, spawnSync } = require('node:child_process');
+const { mkdirSync, copyFileSync } = require('node:fs');
+const { join } = require('node:path');
+const pkg = require('../package.json');
+
+const target = process.env.TARGET;
+// `target === 'main'` is the top-level row: nothing to compile,
+// the launcher is committed source.
+if (!target || target === 'main' || target === 'noarch') process.exit(0);
+
+const binName = Object.keys(pkg.bin || {})[0] || pkg.name;
+const ext = target.includes('windows') ? '.exe' : '';
+
+execFileSync('rustup', ['target', 'add', target], { stdio: 'inherit' });
+execFileSync(
+  'cargo',
+  ['build', '--release', '--target', target, '--bin', binName],
+  { cwd: '../../crates/my-cli', stdio: 'inherit' },
+);
+
+const dir = join('build', target);
+mkdirSync(dir, { recursive: true });
+copyFileSync(
+  join('../../crates/my-cli/target', target, 'release', binName + ext),
+  join(dir, binName + ext),
+);
+```
+
+The build is consumer-owned because `cargo build` flags
+(`--features`, env vars, alternate manifests, Zig-cc cross
+toolchains) vary too much across crates to bake into the
+workflow. For the simple "single workspace member, default
+features" case the script above is the entire integration; tweak
+it as your crate demands. `TARGET` and `BUILD` are the only env
+vars the workflow guarantees.
+
 Each per-platform sub-package needs its own npm trusted-publisher
 registration (a policy on `my-cli` does not cover
 `my-cli-x86_64-unknown-linux-gnu`).

package/package.json

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