putitoutthere 0.2.17 → 0.2.18

package/CHANGELOG.md

@@ -13,6 +13,7 @@ are prefixed `**BREAKING**` and link to the matching section in
 ### Added
 
 - **`[package.bundle_cli]` accepts `features` and `no_default_features` for crates that gate the CLI behind a Cargo feature.** The lib-with-optional-CLI pattern — `[[bin]] required-features = ["cli"]` so `cargo add <name>` doesn't drag the CLI's deps onto library consumers — is the standard shape for crates that fit `bundle_cli`'s use case (ruff, uv, pydantic-core, biome, swc, dirsql). v0.2.0's wiring shipped `cargo build --release --target $TARGET --bin $BIN` with no `--features` path, which made the recipe inert for exactly the consumers it targets. The reusable workflow's cargo build step now appends `--features <comma-list>` when the schema's new `features: list[string]` is non-empty and `--no-default-features` when the new `no_default_features: bool` is true. Defaults are `[]` and `false`, so existing `[package.bundle_cli]` blocks keep building byte-identically. Empty-string entries inside `features` are rejected at config load. The "crates that gate the CLI behind a Cargo feature are not currently supported" caveat in the v0.2.0 MIGRATIONS note has been corrected. See [README → Recipes → Rust CLI inside a PyPI wheel](./README.md#rust-cli-inside-a-pypi-wheel) and [MIGRATIONS.md](./MIGRATIONS.md#bundle_cli-features-and-no_default_features). #300.
+- **Reusable workflow accepts a caller-provided `NPM_TOKEN` via `secrets:`.** OIDC trusted publishers remain the default and recommended path, but Trusted Publishing on npm binds to an *already-published* package — so the first publish of a brand-new npm package has no OIDC path available, and consumers were forced into a manual 6+ package `0.0.0-bootstrap` stub bootstrap (documented nowhere, only discoverable by reading commit history of dirsql or by hitting the failure). The `workflow_call` surface now declares an optional `NPM_TOKEN` secret; when set AND the planned matrix contains an npm row, the secret is exported to `$GITHUB_ENV` as `NODE_AUTH_TOKEN` and the npm CLI prefers the long-lived token over the OIDC path. Callers without a token keep the OIDC path unchanged. For bundled-cli / napi families the same secret authenticates publishes of all per-platform sub-packages on first publish; once those exist, each one needs its own Trusted Publisher registration (the bypass is a one-time bootstrap, not a permanent path). Mirrors the #283 crates fallback in shape. Hit in the wild on the maintainer's own dirsql project (first version of `@dirsql/cli-linux-x64-gnu` on npm is `0.0.0-bootstrap`, 2026-04-30; real `0.2.8` lands the next day) and on `darkfactory`'s first publish. See [README → Trusted publishers → npm](./README.md#npm) and [MIGRATIONS.md](./MIGRATIONS.md#npm-token-fallback). #302.
 - **Reusable workflow accepts a caller-provided `CARGO_REGISTRY_TOKEN` via `secrets:`.** OIDC trusted publishers remain the default and recommended path, but Trusted Publishing on crates.io binds to an *already-published* crate — so the first publish of a brand-new crate has no OIDC path available, and consumers were forced to either fork the workflow or run `cargo publish` outside it. The `workflow_call` surface now declares an optional `CARGO_REGISTRY_TOKEN` secret; when set, the `rust-lang/crates-io-auth-action` OIDC exchange is skipped and the caller-provided token is exported to `$GITHUB_ENV` for the engine's crates handler to read. Callers without a token keep the OIDC path unchanged. The "Auth: OIDC trusted publishers ... Long-lived registry tokens are explicitly NOT supported" framing in `release.yml`'s header has been softened to match. See [README → Trusted publishers → crates.io](./README.md#cratesio) and [MIGRATIONS.md](./MIGRATIONS.md#crates-token-fallback). #283.
 - **Preflight check: every cascaded `kind = "crates"` package's `Cargo.toml` must declare `[package].description` and either `[package].license` or `[package].license-file`.** crates.io rejects publish with `400 Bad Request: missing or empty metadata fields: ...` after `cargo publish`'s verification build has compiled the crate and every transitive dep — wasting the entire publish job on a precondition checkable in milliseconds. The new `requireCratesMetadata` runs alongside `requireAuth` / `requireProvenanceMetadata` in `src/publish.ts`, before any side effects, and reports every failing package + every missing field in one error rather than failing on the first. Surfaces a new stable error code, `PIOT_CRATES_MISSING_METADATA`. Whitespace-only field values are treated as empty. Hit in the wild on `thekevinscott/darkfactory`'s first crate publish; same shape as #280 (npm `repository`). See [MIGRATIONS.md](./MIGRATIONS.md#crates-cargo-toml-must-declare-description-and-license). #290.
 - **Preflight check: every cascaded `kind = "npm"` package must declare a non-empty `repository` field in `package.json`.** `putitoutthere` invokes `npm publish --provenance` on the OIDC trusted-publisher path, and the npm CLI hard-requires this field so the registry can verify the artifact was built from the repo the trusted publisher declares. A missing or empty field previously surfaced as a confusing tail-end npm error after the runner had spun up, OIDC had been negotiated, and the artifact had been built — wasting a full release run on a precondition checkable in milliseconds. The new `requireProvenanceMetadata` runs alongside `requireAuth` in `src/publish.ts`, before any side effects, and reports every failing package in one error rather than failing on the first. Surfaces a new stable error code, `PIOT_NPM_MISSING_REPOSITORY`. Both the canonical object form (`{ type, url, directory? }`) and the legacy single-string form are accepted; only an empty `url` (or no `url` at all) fails. The npm handler's inline backstop is also tightened to match the same predicate (previously `!pkg.repository` slipped `{}`, `{ type: 'git' }`, and whitespace strings through). Documented in [README → `kind = "npm"`](./README.md#kind--npm). See [MIGRATIONS.md](./MIGRATIONS.md#npm-package-json-must-declare-repository). #280.

package/MIGRATIONS.md

@@ -359,6 +359,85 @@ or build-check run.
 
 ---
 
+### npm token fallback
+
+**Summary.** The reusable workflow now accepts an optional
+`NPM_TOKEN` via `secrets:`. Trusted Publishing on npm binds to
+an *already-published* package, so the very first publish of a
+brand-new npm package has no OIDC path available; without this
+fallback every first-time bundled-cli / napi consumer hit a 6+
+package manual `0.0.0-bootstrap` stub bootstrap, documented
+nowhere, only discoverable by reading commit history of dirsql
+or by hitting the failure. OIDC trusted publishers remain the
+default and recommended path — when the secret is unset,
+behavior is byte-for-byte unchanged. When the secret is set
+AND the planned matrix contains an npm row, the secret is
+exported to `$GITHUB_ENV` as `NODE_AUTH_TOKEN`; the npm CLI
+then prefers the long-lived token over the OIDC path. Mirror
+of #283 (crates) in shape, byte-for-byte. Hit in the wild on
+the maintainer's own dirsql project (first version of
+`@dirsql/cli-linux-x64-gnu` on npm is `0.0.0-bootstrap`,
+2026-04-30; real `0.2.8` lands the next day) and on
+`darkfactory`'s first publish. #302.
+
+**Required changes.** None for consumers already on the OIDC
+path. To bootstrap a brand-new npm package or to use the
+workflow on an account where Trusted Publishing isn't
+available, wire the secret in the caller's `release.yml`:
+
+| Before                                                                                 | After                                                                                                                                                                |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0`                   | `uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0`<br>`secrets:`<br>`  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}`                                         |
+
+The repo-level secret holding the npm automation token can be
+named anything; the *workflow* secret it gets passed as must be
+`NPM_TOKEN` exactly — the reusable workflow keys on that name.
+Drop the `secrets:` block from the caller's `release.yml` once
+Trusted Publishing is registered against the (now-existing)
+package; subsequent publishes are zero-secret. For bundled-cli
+/ napi families each per-platform sub-package needs its own
+Trusted Publisher registration after the first publish — the
+secret-bypass is a one-time bootstrap, not a permanent path.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** None when the secret
+is unset (OIDC path unchanged). When the secret is set, a new
+"Export NODE_AUTH_TOKEN (caller-provided)" step writes
+`NODE_AUTH_TOKEN` to `$GITHUB_ENV` gated on the secret being
+non-empty AND the planned matrix containing an npm row. The
+gate reads the secret through a job-level `CALLER_NPM_TOKEN`
+env var because GitHub Actions does not allow the `secrets`
+context inside step-level `if:` conditions ([context
+availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability));
+this is an internal mechanism — consumers don't see or set
+`CALLER_NPM_TOKEN` themselves. Unlike #283 (crates), there is
+no separate OIDC step to "skip" — the npm CLI handles OIDC
+internally via the runner's id-token, and the presence of
+`NODE_AUTH_TOKEN` in the env is what switches the CLI's auth
+mode.
+
+**Verification.** Wire `NPM_TOKEN` to a valid npm automation
+token in the caller repo and trigger a release of a brand-new
+package. The publish-job logs should show "Export
+NODE_AUTH_TOKEN (caller-provided)" as `success`; `npm publish`
+authenticates with the long-lived token rather than via OIDC,
+and every per-platform sub-package in a bundled-cli / napi
+family lands on the registry in a single run. Once first
+publish succeeds, register Trusted Publishers against each
+package URL, drop the `secrets:` block, and re-run a release
+— the OIDC path covers the steady state from there.
+
+Verified end-to-end against existing seeded fixtures and a
+real first-publish on a canary repo. The Verdaccio
+first-publish fixture coverage for the same path is tracked
+separately at #293; until that lands this fallback is verified
+by composition (mirror of #283) plus consumer-side observation
+on real first publishes rather than by an automated
+fresh-state fixture in this repo's CI.
+
+---
+
 ### Crates token fallback
 
 **Summary.** The reusable workflow now accepts an optional

package/README.md

@@ -329,14 +329,15 @@ releases without fighting registry-immutable-publish semantics.
 ## Trusted publishers
 
 OIDC trusted publishers are the default and recommended auth path.
-The reusable workflow also accepts a long-lived `CARGO_REGISTRY_TOKEN`
-via `secrets:` for cases where Trusted Publishing isn't reachable —
-most commonly the very first publish of a brand-new crate, since
-Trusted Publishing on crates.io binds to an *already-published* crate
-and there's no pending-publisher equivalent. When set, the OIDC
-exchange is skipped and the caller-provided token is used instead.
-Drop the secret once Trusted Publishing is registered against the
-existing crate.
+The reusable workflow also accepts long-lived `CARGO_REGISTRY_TOKEN`
+(crates.io) and `NPM_TOKEN` (npm) values via `secrets:` for cases
+where Trusted Publishing isn't reachable — most commonly the very
+first publish of a brand-new crate or npm package, since Trusted
+Publishing on both registries binds to an *already-published*
+package and neither has a pending-publisher equivalent. When set,
+the OIDC exchange is skipped and the caller-provided token is used
+instead. Drop the secret once Trusted Publishing is registered
+against the existing package.
 
 For all three registries the OIDC fields are the same: **your**
 repository owner/name, **your** workflow filename (`release.yml`),
@@ -382,14 +383,34 @@ see "How auth flows" below for the why.
 
 ### npm
 
-1. Publish at least one version of your package with a classic
-   `NODE_AUTH_TOKEN` so the package exists on the registry. (npm's trusted
-   publisher requires an existing package.)
+1. **First publish (brand-new package).** Trusted Publishing on npm
+   binds to an existing package, so the first `npm publish` has no
+   OIDC path. Pass `NPM_TOKEN` to the reusable workflow via
+   `secrets:` to bootstrap through this workflow:
+
+   ```yaml
+   jobs:
+     release:
+       uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0
+       secrets:
+         NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+   ```
+
+   When `NPM_TOKEN` is set, it is exported to the publish step's
+   environment as `NODE_AUTH_TOKEN` and the npm CLI prefers it over
+   the OIDC path. For bundled-cli / napi families the same secret
+   authenticates publishes of all per-platform sub-packages on first
+   publish — once those exist, each one needs its own Trusted
+   Publisher registration (the bypass is a one-time bootstrap, not
+   a permanent path).
 2. Go to `https://www.npmjs.com/package/<name>/access` → **Require trusted
    publisher**.
 3. Fill in: your repository, workflow filename (`release.yml`),
-   environment (optional).
-4. Delete the bootstrap token.
+   environment (optional). Repeat for every per-platform sub-package
+   for bundled-cli / napi families.
+4. Drop the `NPM_TOKEN` secret from the workflow once Trusted
+   Publishing is registered; subsequent publishes are zero-secret on
+   the OIDC path.
 
 ### How auth flows
 

package/package.json

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