putitoutthere 0.1.47 → 0.1.49

package/CHANGELOG.md

@@ -12,12 +12,14 @@ are prefixed `**BREAKING**` and link to the matching section in
 
 ### Added
 
+- **`workflow_call` output `has_pypi`.** The reusable workflow now emits a string `'true'`/`'false'` indicating whether the planned matrix contains any `kind = "pypi"` rows. Consumers gate their caller-side `pypi-publish` job on this so non-PyPI repos paste the canonical template verbatim without paying any runtime cost. Computed in the `plan` job from the matrix output.
 - **Reusable workflow `.github/workflows/release.yml` (`workflow_call`).** The single user-facing surface. Consumer integration is one `uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0` line in their own `release.yml`; pinned action versions, plan/build/publish orchestration, and GitHub Release creation all live inside. Three optional inputs: `environment` (default `release`), `node_version` (default `24`), `python_version` (default `3.12`). No `dry_run`, `working_directory`, or `config` inputs — the plan job is already side-effect-free, the config file is `putitoutthere.toml` at the repo root, period. The engine is invoked via `uses: thekevinscott/putitoutthere@v0` so the workflow file and the engine always agree on a single git ref.
 
 - **`[package.bundle_cli]` recipe for maturin pypi packages** (#217). Opt-in declarative shape for libraries that ship a Rust CLI inside each wheel (the `ruff` / `uv` / `pydantic-core` pattern). Declare `bin`, `stage_to`, and optional `crate_path`; the reusable workflow cross-compiles the binary per target, stages it into the package source tree, and maturin picks it up via `[tool.maturin].include`. Requires `build = "maturin"` and non-empty `targets`. See [README → Recipes → Rust CLI inside a PyPI wheel](./README.md#rust-cli-inside-a-pypi-wheel). No behavior change for existing packages that don't declare the block.
 
 ### Changed
 
+- **BREAKING: PyPI uploads moved to a caller-side `pypi-publish` job.** PyPI's Trusted Publisher matching filters candidates by `repository_owner` + `repository_name` *before* checking `job_workflow_ref` ([Warehouse implementation](https://github.com/pypi/warehouse/blob/main/warehouse/oidc/models/github.py)); since the OIDC `repository` claim always reflects the caller's repo even inside a reusable workflow, a TP registered against `thekevinscott/putitoutthere` is filtered out before the workflow_ref is ever checked. PyPI explicitly documents this as unsupported ([troubleshooting](https://docs.pypi.org/trusted-publishers/troubleshooting/)). Tracked at [pypi/warehouse#11096](https://github.com/pypi/warehouse/issues/11096), no timeline. The engine still does plan + build + version-rewrite + git tag for PyPI; the actual upload (`pypa/gh-action-pypi-publish`) now runs in the consumer's workflow file as a second job, gated on `needs.release.outputs.has_pypi`. The canonical template grew from ~12 → ~30 lines but remains a single copy-paste — the `if:` skips the job for non-PyPI repos. See [MIGRATIONS.md](./MIGRATIONS.md#pypi-uploads-moved-to-caller-side-job) and [`notes/audits/2026-04-28-pypi-tp-reusable-workflow-constraint.md`](./notes/audits/2026-04-28-pypi-tp-reusable-workflow-constraint.md).
 - **Public consumer surface collapsed to the README + the reusable workflow.** The CLI, the JS action (`action.yml`), and the diagnostic subcommands (`doctor`, `preflight`) are internal seams the reusable workflow invokes; consumers do not call them. The entire `docs/` directory is removed — `README.md` is the single user-facing surface. See [MIGRATIONS.md](./MIGRATIONS.md#public-surface-collapsed-to-a-reusable-workflow) for the before/after.
 - **Auth is OIDC trusted publishers only.** The reusable workflow does not pass long-lived registry tokens (`NPM_TOKEN`, `PYPI_API_TOKEN`, `CARGO_REGISTRY_TOKEN`) as secrets. The engine's env-var fallback code paths still exist (in `src/auth.ts`); they're just not reachable through the reusable workflow.
 - **Repository renamed `put-it-out-there` → `putitoutthere`.** GitHub auto-redirects the old slug, but consumers with the old URL pinned in `package.json`, `Cargo.toml`, `pyproject.toml`, or workflow files should update them. See [MIGRATIONS.md](./MIGRATIONS.md#repository-renamed-put-it-out-there--putitoutthere).
@@ -45,6 +47,61 @@ are prefixed `**BREAKING**` and link to the matching section in
 
 ### Fixed
 
+- **PyPI artifact discovery now matches the documented `{name}-sdist` and `{name}-wheel-{target}` shapes exactly.** (#244)
+  Previously the handler used a bare prefix match (`entry.startsWith("{name}-")`), which silently picked up sibling packages whose names extended the same prefix (e.g. `foo`'s discovery matched `foo-extras-sdist`). The handler now matches the sdist directory exactly and the wheel directories by `{name}-wheel-` prefix only. Affects multi-package repos where one pypi package's name is a prefix of another's.
+
+- **Reusable workflow's maturin sdist row now uses `command: sdist`.** (#244)
+  `maturin build --sdist` builds a wheel AND an sdist; the sdist row's
+  artifact tarball ended up containing a manylinux wheel that collided
+  with the per-target wheel rows at upload time, causing twine to abort
+  with `400 File already exists`. Splitting the sdist invocation to use
+  `command: sdist` (sdist-only) eliminates the collision.
+
+- **Synthesized npm platform packages now inherit `repository`, `license`, and `homepage` from the main `package.json`.** (#244)
+  npm's provenance verifier rejected platform tarballs with `E422 Error verifying sigstore provenance bundle: Failed to validate repository information: package.json: "repository.url" is "", expected to match "https://github.com/<owner>/<repo>"`. The synthesizer used to write only `name`/`version`/`os`/`cpu`/`files`/`main`/`libc`; the empty repository URL didn't match the publishing repo baked into the sigstore bundle. Identity fields are now copied from the main package so per-target tarballs validate. Affects `build = "napi"` and `build = "bundled-cli"` packages.
+
+- **Reusable workflow's npm build step now forces `shell: bash`.** (#244)
+  The build matrix can target Windows runners, where GitHub Actions defaults
+  to `pwsh` for `run:` blocks. The npm build's `if [ -f package-lock.json ]`
+  branch is bash syntax, which PowerShell parsed as a malformed expression
+  and aborted with `ParserError`. Adding `shell: bash` makes the step
+  portable across Linux, macOS, and Windows runners. No config changes
+  required for consumers; pure JS-on-ubuntu setups were unaffected.
+
+- **Reusable workflow now exchanges OIDC ID-token for a `CARGO_REGISTRY_TOKEN`
+  before invoking the engine.** (#244) `cargo publish` was failing with
+  `error: no token found, please run cargo login` because the publish
+  job's env had no `CARGO_REGISTRY_TOKEN`. PyPI uploads (twine) and npm
+  publish both consume the OIDC ID-token directly via registry-side
+  acceptance; cargo doesn't — it needs a registry-issued bearer token,
+  which `rust-lang/crates-io-auth-action@v1` produces from the OIDC
+  ID-token. The workflow now runs that action conditionally (only when
+  the plan contains a `kind = "crates"` row) and exports the resulting
+  token to `$GITHUB_ENV` for the engine subprocess. No config or
+  workflow changes required for consumers.
+
+- **Crates publish's pre-cargo dirty-tree check now ignores the
+  reusable workflow's `artifacts/` scratch directory.** (#244)
+  The pre-publish guard scans `git status --porcelain` for stray edits
+  outside the managed `Cargo.toml` (the engine passes `--allow-dirty`
+  to cargo to permit the writeVersion bump, then re-imposes a narrower
+  check). Reusable workflow's `actions/download-artifact@v4` step
+  always creates `artifacts/` under cwd, even for crates-only
+  fixtures with nothing to download — the pre-check was rejecting
+  with `unexpected dirty files in the working tree outside ... -
+  artifacts/`. The scan now treats `${ctx.artifactsRoot}` (the dir
+  the engine itself populates) as engine-managed and skips it. No
+  config or workflow changes required.
+
+- **Crates publish no longer fails the completeness check.** (#244)
+  `cargo publish` packages and uploads from source on the registry
+  side, so the reusable workflow never produces a `<name>-crate/`
+  artifact directory. The pre-publish completeness check was demanding
+  a `.crate` file that nothing in the pipeline ever creates, which made
+  any consumer with a `kind = "crates"` package fail with
+  `missing artifact directory <name>-crate/` before cargo was ever
+  invoked. Crates rows now skip the completeness check (same reasoning
+  as vanilla npm rows). No config or workflow changes required.
 - **Scaffolded `release.yml` now forwards `GITHUB_TOKEN` to the publish
   step.** piot has cut GitHub Releases alongside tag pushes since #26, but
   Actions doesn't auto-mount the runner token as an env var, so the

package/MIGRATIONS.md

@@ -21,6 +21,303 @@ Each section covers five things, in order:
 
 ## Unreleased
 
+### PyPI uploads moved to caller-side job
+
+**Summary.** PyPI's Trusted Publisher matching filters candidates by
+`repository_owner` + `repository_name` *before* checking
+`job_workflow_ref`
+([Warehouse implementation](https://github.com/pypi/warehouse/blob/main/warehouse/oidc/models/github.py)).
+The OIDC `repository` claim always reflects the caller's repo —
+including inside a reusable workflow — so a TP registered against
+the reusable workflow's repo is filtered out before workflow_ref
+is even checked. PyPI documents this as unsupported
+([troubleshooting](https://docs.pypi.org/trusted-publishers/troubleshooting/)).
+Tracked at [pypi/warehouse#11096](https://github.com/pypi/warehouse/issues/11096),
+no timeline.
+
+To preserve OIDC trusted publishing for PyPI without setting
+`PYPI_API_TOKEN`, the upload step (`pypa/gh-action-pypi-publish`)
+now runs in the consumer's own workflow file as a second job,
+gated on the new `has_pypi` output. The engine still owns plan,
+build, version-rewrite, and git-tag creation for PyPI rows; only
+the actual upload moves. See
+[`notes/audits/2026-04-28-pypi-tp-reusable-workflow-constraint.md`](./notes/audits/2026-04-28-pypi-tp-reusable-workflow-constraint.md)
+for the full diagnosis.
+
+**Required changes.** Update `.github/workflows/release.yml`:
+
+Before (~12 lines):
+
+```yaml
+name: Release
+on:
+  push:
+    branches: [main]
+jobs:
+  release:
+    uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0
+    permissions:
+      contents: write
+      id-token: write
+```
+
+After (~30 lines, single copy-paste from README → Quickstart):
+
+```yaml
+name: Release
+on:
+  push:
+    branches: [main]
+jobs:
+  release:
+    uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0
+    permissions:
+      contents: write
+      id-token: write
+
+  pypi-publish:
+    needs: release
+    if: needs.release.outputs.has_pypi == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: '*-sdist'
+          path: dist/
+          merge-multiple: true
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: '*-wheel-*'
+          path: dist/
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+```
+
+The `pypi-publish` job's `if:` gate skips it for non-PyPI repos —
+paste verbatim regardless of what you publish. Crates.io and npm
+are unaffected; their TP claim semantics work fine inside the
+reusable workflow.
+
+**No PyPI TP re-registration required.** Your existing TP
+registration (against your repo, your `release.yml`, optional
+environment) was already correct for this pattern. If you'd
+attempted to register a TP against `thekevinscott/putitoutthere`
+to work around the prior failure, remove that entry — it would
+have never matched anyway.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** PyPI upload step now
+runs in the consumer's workflow context. The reusable workflow's
+publish job no longer installs `twine` or `setup-python`; engine
+log lines for PyPI rows now read "delegated to caller-side upload
+step" instead of "authenticating via OIDC".
+
+**Verification.** Push a release. The reusable workflow's
+`release` job creates and pushes the git tag for PyPI rows; the
+caller's `pypi-publish` job runs `pypa/gh-action-pypi-publish`
+and uploads to PyPI. Check `https://pypi.org/project/<name>/<version>/`
+to confirm.
+
+---
+
+### PyPI artifact discovery matches `{name}-sdist` and `{name}-wheel-` exactly
+
+**Summary.** `src/handlers/pypi.ts:collectArtifacts` used a bare prefix
+match (`entry.startsWith("{name}-")`) to find a package's artifact
+directories under `artifacts/`. Sibling packages whose names extended
+the same prefix (`foo` and `foo-extras`) collided: `foo`'s discovery
+also picked up `foo-extras-sdist`, and twine then uploaded the sibling's
+tarball under `foo`'s OIDC identity, failing PyPI's project-name check.
+The handler now matches the sdist directory exactly (`{name}-sdist`)
+and the wheel directories by `{name}-wheel-` prefix only — the two
+shapes the planner documents in §12.4.
+
+**Required changes.** None.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Repos with multiple pypi
+packages where one name is a prefix of another (e.g. `foo` and
+`foo-extras`) no longer cross-upload artifacts. Single-package repos
+and repos with non-overlapping names are unaffected.
+
+**Verification.** A repo declaring both `foo` and `foo-extras` as
+pypi packages publishes the correct tarballs to each project; neither
+job uploads the other's artifacts.
+
+---
+
+### Reusable workflow's maturin sdist row uses `command: sdist`
+
+**Summary.** The reusable workflow's pypi-maturin build step was a single
+`PyO3/maturin-action@v1` invocation with `command: build` and an
+`--sdist` flag conditional on the row being the sdist target. `maturin
+build --sdist` is documented as "build a wheel AND an sdist" — the
+sdist's artifact directory ended up containing both a `.tar.gz` and a
+manylinux wheel, which collided at upload time with the per-target
+wheel rows and aborted twine with `400 File already exists`. The build
+step is now split into two: `command: sdist` for the sdist row
+(sdist-only) and `command: build` with `--target` for wheel rows.
+
+**Required changes.** None.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Maturin packages with a
+`sdist` row in their plan now upload a single `.tar.gz` from that row,
+not a wheel-plus-sdist pair. Per-target wheel rows are unaffected.
+
+**Verification.** A maturin-built package with `sdist` in `targets`
+publishes to PyPI without `400 File already exists`. The sdist
+artifact directory contains `.tar.gz` only.
+
+---
+
+### Synthesized npm platform packages inherit `repository`/`license`/`homepage`
+
+**Summary.** npm's provenance verifier rejected platform-package tarballs
+with `E422 Error verifying sigstore provenance bundle: Failed to validate
+repository information: package.json: "repository.url" is ""`. The
+synthesizer in `src/handlers/npm-platform.ts` previously wrote only
+`name`/`version`/`os`/`cpu`/`files`/`main`/`libc` into the per-target
+`package.json`. The publishing GitHub repo URL is bound into the
+sigstore bundle by `npm publish --provenance`; npm cross-checks it
+against `package.json.repository.url` at upload time, so an empty value
+fails verification. Identity fields (`repository`, `license`, `homepage`)
+are now read from the main package's `package.json` and copied into each
+synthesized platform package. Affects `build = "napi"` and
+`build = "bundled-cli"` packages.
+
+**Required changes.** None — the fix is automatic. To benefit, ensure
+the main package's `package.json` declares a `repository.url` that
+matches the publishing repo (npm provenance has always required this for
+the main package; platform packages now share the same expectation).
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Per-target platform tarballs
+on the registry now carry the same `repository`/`license`/`homepage`
+values as the main package, instead of being absent.
+
+**Verification.** A `build = "napi"` or `build = "bundled-cli"` package
+publishes its platform tarballs to npm without `E422` provenance errors.
+`npm view <pkg>-<target>@<version> repository` returns the main
+package's repository URL.
+
+---
+
+### Reusable workflow's npm build step forces `shell: bash`
+
+**Summary.** The build matrix can target Windows runners. GitHub Actions
+defaults to `pwsh` for `run:` blocks on Windows, but the npm build's
+shape detection (`if [ -f package-lock.json ]; then npm ci; elif ... fi`)
+is bash syntax — PowerShell parsed it as a malformed expression and
+aborted with `ParserError` before any package manager ran. The step now
+sets `shell: bash` explicitly, which is portable across Linux, macOS,
+and Windows runners (Git Bash ships on `windows-latest`).
+
+**Required changes.** None.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Consumers whose plan includes
+an npm package targeting Windows runners (e.g. native node-addon shapes,
+`napi-rs` matrices) now succeed past the install step. Linux/macOS-only
+matrices are unaffected — bash was already the default there.
+
+**Verification.** An npm package with a Windows row in its plan
+completes the install + build step on `windows-latest`; the job log
+shows `Run if [ -f package-lock.json ]` executing under bash, not pwsh.
+
+---
+
+### Reusable workflow exchanges OIDC token for `CARGO_REGISTRY_TOKEN`
+
+**Summary.** Crates publishes were failing with `error: no token found,
+please run cargo login` — the reusable workflow was relying on cargo to
+find an OIDC token in env, but cargo only consumes
+`CARGO_REGISTRY_TOKEN` (a registry-issued bearer), not raw OIDC
+ID-tokens. The publish job now runs `rust-lang/crates-io-auth-action@v1`
+when the plan contains a crates row and exports its `outputs.token`
+as `CARGO_REGISTRY_TOKEN` for the engine subprocess.
+
+**Required changes.** None for consumers using the reusable workflow as
+documented. Repos publishing to crates.io must have a configured trusted
+publisher on crates.io pointing at their `release.yml` — same prerequisite
+as before, just now actually exercised.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Crates publish in the
+reusable workflow now reaches the registry; previously it failed at
+the cargo invocation. JS/Python-only repos are unaffected — the auth
+step is gated on `contains(needs.plan.outputs.matrix, '"kind":"crates"')`
+and skips entirely when no crates row is in the plan.
+
+**Verification.** A `kind = "crates"` package whose trusted publisher is
+configured on crates.io now publishes successfully through the reusable
+workflow. The publish job log shows the `Authenticate with crates.io
+(OIDC)` step running before `putitoutthere publish`.
+
+---
+
+### Crates publish's pre-cargo dirty-tree check ignores `artifacts/`
+
+**Summary.** The crates handler scans `git status --porcelain` before
+invoking `cargo publish --allow-dirty`, refusing to proceed if anything
+other than the managed `Cargo.toml` is dirty (the writeVersion bump
+runs in the same job and would otherwise be the only legitimate dirty
+file). The reusable workflow's `actions/download-artifact@v4` step
+always creates `artifacts/` at the repo root before publish runs —
+even for crates-only fixtures that have nothing to download — and the
+pre-check was rejecting on `?? artifacts/`. The scan now treats the
+engine's own `artifactsRoot` as managed scratch space and skips files
+under it.
+
+**Required changes.** None.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Crates publishes that
+previously errored with `unexpected dirty files in the working tree
+outside <Cargo.toml>: - artifacts/` now proceed to `cargo publish`.
+Stray edits anywhere else in the tree still fail the check.
+
+**Verification.** A `kind = "crates"` package in a repo whose only
+"dirty" file (alongside the managed `Cargo.toml`) is the engine's
+`artifacts/` directory now reaches cargo. `git status --porcelain`
+showing `?? artifacts/` is no longer fatal.
+
+---
+
+### Crates publish no longer fails the pre-publish completeness check
+
+**Summary.** Consumers with a `kind = "crates"` package previously hit
+`Artifact completeness check failed: missing artifact directory
+<name>-crate/` before cargo was ever invoked. The reusable workflow
+does not upload a `.crate` artifact (cargo packages and uploads from
+source on the registry side), so the file the check demanded never
+existed in the pipeline. The completeness check now skips crates
+rows. Same reasoning as vanilla npm rows, which were already skipped.
+
+**Required changes.** None.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Crates publishes that
+previously errored at the completeness gate now reach `cargo publish`.
+A crates row whose source tree is genuinely broken still fails — the
+failure just happens at the cargo step, not before.
+
+**Verification.** A `kind = "crates"` package in
+`putitoutthere.toml` no longer requires any artifact upload step in
+the consumer's workflow. Trigger a release with a `release: patch`
+trailer; the publish job's "Run putitoutthere publish" step should
+log `crates: cargo publish ...` instead of aborting on completeness.
+
 ### `[[package]].paths` renamed to `globs`
 
 **Summary.** The `path` / `paths` pair in `[[package]]` was confusing —

package/README.md

@@ -2,7 +2,7 @@
 
 A reusable GitHub Actions workflow that publishes packages to crates.io, PyPI,
 and npm from one repo. OIDC-first, cascade-aware, polyglot. The consumer
-surface is one config file plus ~10 lines of YAML calling
+surface is one config file plus one canonical YAML calling
 `uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0`.
 
 ## Quickstart
@@ -22,10 +22,41 @@ jobs:
     permissions:
       contents: write
       id-token: write
+
+  # PyPI upload runs in the caller's workflow context. Required because
+  # PyPI Trusted Publishers can't validate OIDC tokens minted from a
+  # cross-repo reusable workflow (pypi/warehouse#11096). The `if:`
+  # gate skips this job for non-PyPI repos — paste verbatim regardless
+  # of what you publish.
+  pypi-publish:
+    needs: release
+    if: needs.release.outputs.has_pypi == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: '*-sdist'
+          path: dist/
+          merge-multiple: true
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: '*-wheel-*'
+          path: dist/
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
 ```
 
 Pinned action versions, `plan → build → publish` orchestration, and GitHub
-Release creation all live inside the reusable workflow.
+Release creation all live inside the reusable workflow. The `pypi-publish`
+job is the one piece that has to live in your workflow file: PyPI's
+Trusted Publisher feature filters OIDC tokens by `repository_owner` /
+`repository_name` claims, which always reflect the caller's repo — so a
+TP registered against `thekevinscott/putitoutthere` is filtered out
+before `job_workflow_ref` is even checked. Running `pypa/gh-action-pypi-publish`
+in your workflow context aligns the claims with your TP registration.
+The job is skipped automatically for repos that don't publish to PyPI.
 
 Optional inputs — `with:` block at the call site:
 
@@ -216,11 +247,14 @@ releases without fighting registry-immutable-publish semantics.
 
 ## Trusted publishers
 
-OIDC trusted publishers — the only auth path supported by the reusable
-workflow. Long-lived registry tokens are not reachable through the workflow.
+OIDC trusted publishers — the only auth path supported. Long-lived
+registry tokens are not reachable through the workflow.
 
-The fields each registry needs are the same: repository owner/name, workflow
-filename (`release.yml`), and optionally a GitHub environment name.
+For all three registries the fields are the same: **your** repository
+owner/name, **your** workflow filename (`release.yml`), and optionally
+a GitHub environment name. Note: you register against your *own*
+repository, not against `thekevinscott/putitoutthere` — see "How
+auth flows" below for the why.
 
 ### crates.io
 
@@ -228,15 +262,15 @@ filename (`release.yml`), and optionally a GitHub environment name.
    exists. (Trusted publishing needs a crate owner record.)
 2. Go to `https://crates.io/crates/<crate>/settings` → **Trusted Publishing**
    → **Add**.
-3. Fill in: repository owner, repository name, workflow filename
+3. Fill in: your repo owner, your repo name, workflow filename
    (`release.yml`), environment (optional).
 
 ### PyPI
 
 1. Go to `https://pypi.org/manage/project/<name>/settings/publishing/` (or
    **Publishing** on the project page).
-2. Add a **GitHub** trusted publisher: owner, repo, workflow filename,
-   environment (optional).
+2. Add a **GitHub** trusted publisher: your repo owner, your repo name,
+   workflow filename (`release.yml`), environment (optional).
 3. Brand-new project? Use a [pending publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
    to skip the bootstrap token.
 
@@ -247,9 +281,33 @@ filename (`release.yml`), and optionally a GitHub environment name.
    publisher requires an existing package.)
 2. Go to `https://www.npmjs.com/package/<name>/access` → **Require trusted
    publisher**.
-3. Fill in: repository, workflow filename, environment (optional).
+3. Fill in: your repository, workflow filename (`release.yml`),
+   environment (optional).
 4. Delete the bootstrap token.
 
+### How auth flows
+
+`crates.io` and `npm` validate OIDC tokens that are minted by the
+reusable workflow's `publish` job. The reusable workflow already
+sits in your release path, so the OIDC `repository` and
+`job_workflow_ref` claims line up with your TP registration.
+
+PyPI is different. Its TP matching filters candidates by
+`repository_owner` + `repository_name` *before* checking
+`job_workflow_ref` ([Warehouse implementation](https://github.com/pypi/warehouse/blob/main/warehouse/oidc/models/github.py)).
+The `repository` claim always reflects the caller's repo — even
+inside a reusable workflow — so a TP registered against the
+reusable workflow's repo would be filtered out before
+`job_workflow_ref` is even checked. PyPI documents this:
+"[Reusable workflows cannot currently be used as the workflow in
+a Trusted Publisher.](https://docs.pypi.org/trusted-publishers/troubleshooting/)"
+Tracked at [pypi/warehouse#11096](https://github.com/pypi/warehouse/issues/11096).
+
+That's why the canonical template puts the PyPI upload step
+(`pypa/gh-action-pypi-publish`) directly in *your* workflow,
+gated on `needs.release.outputs.has_pypi`. In your workflow context
+both claims resolve to your repo, so your TP registration matches.
+
 ## Recipes
 
 ### Bundled-CLI npm family

package/action.yml

@@ -7,10 +7,14 @@ inputs:
     description: 'Which CLI subcommand to run. Canonical values are `plan` and `publish`.'
     required: false
     default: 'plan'
-  dry_run:
-    description: 'If true, resolve the plan but skip all destructive operations.'
+  working_directory:
+    description: >-
+      Path the CLI runs against (forwarded as `--cwd`). Defaults to the
+      runner working directory. Internal use; the reusable workflow
+      supplies this when invoked against a non-root tree (e.g. e2e
+      fixtures materialized into a subdir).
     required: false
-    default: 'false'
+    default: ''
   fail_on_error:
     description: 'If true, non-zero CLI exit codes fail the step.'
     required: false
@@ -21,5 +25,5 @@ outputs:
     description: "JSON matrix emitted by `plan`. Output key is omitted when the plan resolves to zero rows or when command is anything other than plan; downstream jobs should coalesce with `|| '[]'`."
 
 runs:
-  using: 'node24'
+  using: 'node20'
   main: 'dist-action/index.js'

package/dist/action.d.ts

@@ -1,9 +1,9 @@
 /**
  * GitHub Actions wrapper. Bundled to `dist-action/index.js` via ncc.
  *
- * ~50-line adapter: read `INPUT_COMMAND` / `INPUT_DRY_RUN` /
- * `INPUT_FAIL_ON_ERROR` → invoke the SDK's run() → surface the exit
- * code. No GHA-specific logic lives here beyond input parsing.
+ * ~50-line adapter: read `INPUT_COMMAND` / `INPUT_FAIL_ON_ERROR` →
+ * invoke the SDK's run() → surface the exit code. No GHA-specific
+ * logic lives here beyond input parsing.
  *
  * Issue #24. Plan: §5.2, §5.3.
  */

package/dist/action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAyB1C"}
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAwB1C"}

package/dist/action.js

@@ -1,25 +1,24 @@
 /**
  * GitHub Actions wrapper. Bundled to `dist-action/index.js` via ncc.
  *
- * ~50-line adapter: read `INPUT_COMMAND` / `INPUT_DRY_RUN` /
- * `INPUT_FAIL_ON_ERROR` → invoke the SDK's run() → surface the exit
- * code. No GHA-specific logic lives here beyond input parsing.
+ * ~50-line adapter: read `INPUT_COMMAND` / `INPUT_FAIL_ON_ERROR` →
+ * invoke the SDK's run() → surface the exit code. No GHA-specific
+ * logic lives here beyond input parsing.
  *
  * Issue #24. Plan: §5.2, §5.3.
  */
 import { run } from './cli.js';
 export async function main() {
     const command = process.env.INPUT_COMMAND ?? '';
-    const dryRun = (process.env.INPUT_DRY_RUN ?? 'false').toLowerCase() === 'true';
+    const workingDirectory = process.env.INPUT_WORKING_DIRECTORY ?? '';
     const failOnError = (process.env.INPUT_FAIL_ON_ERROR ?? 'true').toLowerCase() !== 'false';
     if (!command) {
         process.stderr.write('putitoutthere action: missing required input `command`\n');
         process.exit(1);
     }
-    const argv = ['node', 'putitoutthere', command];
-    if (dryRun)
-        argv.push('--dry-run');
-    argv.push('--json');
+    const argv = ['node', 'putitoutthere', command, '--json'];
+    if (workingDirectory)
+        argv.push('--cwd', workingDirectory);
     const code = await run(argv);
     if (code !== 0 && !failOnError) {
         process.stderr.write(`putitoutthere action: ignoring non-zero exit (fail_on_error=false): ${code}\n`);

package/dist/action.js.map

@@ -1 +1 @@
-{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;IAC/E,MAAM,WAAW,GACf,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC;IAExE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0DAA0D,CAC3D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IAChD,IAAI,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEpB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,uEAAuE,IAAI,IAAI,CAChF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,oFAAoF;AACpF,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACpD,KAAK,IAAI,EAAE,CAAC;AACd,CAAC"}
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC;IAChD,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,EAAE,CAAC;IACnE,MAAM,WAAW,GACf,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC;IAExE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0DAA0D,CAC3D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC1D,IAAI,gBAAgB;QAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IAE3D,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,uEAAuE,IAAI,IAAI,CAChF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,oFAAoF;AACpF,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACpD,KAAK,IAAI,EAAE,CAAC;AACd,CAAC"}

package/dist/cli.d.ts

@@ -12,8 +12,19 @@
  * Global flags:
  *   --cwd <path>      working directory (default: process.cwd())
  *   --config <path>   path to putitoutthere.toml
- *   --dry-run         for publish; no side effects
  *   --json            machine-readable output
+ *
+ * `--dry-run` was removed deliberately (#244). The library's job is
+ * publishing; a non-publishing mode of the publish command was a
+ * coverage hole pretending to be a feature. Passing `--dry-run` now
+ * errors out.
  */
+interface ParsedFlags {
+    cwd: string;
+    config?: string | undefined;
+    json: boolean;
+}
+export declare function parseFlags(argv: readonly string[]): ParsedFlags;
 export declare function run(argv: readonly string[]): Promise<number>;
+export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA2DH,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+FlE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAoCH,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CA4B/D;AAED,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8FlE"}