putitoutthere 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -12,6 +12,7 @@ are prefixed `**BREAKING**` and link to the matching section in
 
 ### Added
 
+- **Reusable workflow `.github/workflows/build.yml` (`workflow_call`).** PR-time build verification: runs the same plan + build matrix that `release.yml` runs, calling a shared internal `_matrix.yml` reusable workflow so action pins, per-target build steps, and runner selection cannot drift between the two paths. `build.yml` declares only `permissions: contents: read` and contains no publish job, no `id-token: write`, no OIDC trusted-publisher exchange, and no registry auth — the bytes required to publish do not exist on this code path. Two optional inputs forwarded to `_matrix.yml`: `node_version` (default `24`), `python_version` (default `3.12`). Concurrency is keyed on `github.ref` with `cancel-in-progress: true` so PR pushes supersede stale runs (release.yml's repository-keyed group with `cancel-in-progress: false` is unchanged). An `actionlint`-job grep assertion rejects any future patch that adds `id-token: write` to `build.yml` or `_matrix.yml`. See [README → Build check](./README.md#1b-optional-drop-in-githubworkflowsbuild-checkyml) and [MIGRATIONS.md](./MIGRATIONS.md#new-buildyml-reusable-workflow-for-pr-time-build-verification).
 - **`PIOT_PUBLISH_EMPTY_PLAN` error code.** Surfaced when `publish` is invoked with an empty matrix. Joins `PIOT_AUTH_NO_TOKEN` in the stable error-code vocabulary; foreign agents debugging a failed publish can fingerprint on the code without parsing prose.
 - **`kind = "npm"` `build` accepts an array of entries with consumer-defined platform-package name templates.** For packages that ship both a napi-rs Node addon and a CLI binary from the same npm package (the `@swc/core` shape), declare `build = [{ mode = "napi", name = "@scope/lib-{triple}" }, { mode = "bundled-cli", name = "@scope/cli-{triple}" }]`. Each entry contributes its own per-platform package family; the main package's `optionalDependencies` spans both. Entries can be bare mode strings (`"napi"`, defaults to `{name}-{triple}` template) or `{ mode, name }` objects. Variables surfaced in `name` templates: `{name}`, `{scope}`, `{base}`, `{triple}`, `{mode}`. `{version}` is intentionally not surfaced. Single-mode string form (`build = "napi"`) preserved byte-for-byte — same artifact-name layout, same platform-package names, no migration pressure on existing consumers. See [README → Recipes → Multi-mode npm family](./README.md#multi-mode-npm-family) and [MIGRATIONS.md](./MIGRATIONS.md#npm-build-accepts-array-of-entries).
 

package/MIGRATIONS.md

@@ -21,6 +21,76 @@ Each section covers five things, in order:
 
 ## Unreleased
 
+### New `build.yml` reusable workflow for PR-time build verification
+
+**Summary.** A second consumer-facing reusable workflow,
+`.github/workflows/build.yml`, runs the same plan + build matrix that
+`release.yml` runs but stops there — no publish job, no
+`id-token: write`, no OIDC exchange, no registry auth. Both workflows
+delegate the matrix to a shared internal `_matrix.yml`, so action
+pins (`actions/checkout@v6`, `PyO3/maturin-action@v1`, etc.), per-row
+build steps, and runner selection cannot drift between PR-time
+verification and release-time publishing. The structural guarantee —
+publish-capable bytes do not exist on the build-check code path — is
+what makes this safe to run on untrusted PRs; a `dry_run: true` input
+on `release.yml` would have made it a runtime guarantee subject to
+GHA's expression evaluation quirks and any future `if:` bug. An
+`actionlint`-job grep assertion rejects any patch that adds
+`id-token: write` to `build.yml` or `_matrix.yml`.
+
+The new workflow runs at the same `@v0` floating tag as
+`release.yml`, pinned the same way the engine action already is —
+floating lightweight tag, no annotated-tag pitfall ([github/community
+discussion #48693](https://github.com/orgs/community/discussions/48693)).
+Pinning per-release annotated tags
+(e.g. `putitoutthere-v0.4.2`) is unsupported for the same reason it has
+always been unsupported for `release.yml`; the `@v0` form is canonical.
+
+**Required changes.** None for existing consumers. `release.yml` is
+unchanged in its public surface — same inputs, same `has_pypi`
+output, same concurrency group, same publish behavior. Internally
+its `plan` and `build` jobs moved into `_matrix.yml`, but that file
+is internal (the leading underscore + the absence of consumer-facing
+docs); pinning `release.yml@v0` keeps working byte-for-byte.
+
+To opt into PR-time build verification, add a new workflow to your
+repo:
+
+```yaml
+# .github/workflows/build-check.yml
+name: Build check
+on:
+  pull_request: {}
+jobs:
+  build-check:
+    uses: thekevinscott/putitoutthere/.github/workflows/build.yml@v0
+```
+
+No new permissions, no new inputs to set. `node_version` and
+`python_version` accept the same defaults / overrides as
+`release.yml`. PRs that break a target-specific build (a wheel that
+fails on `aarch64-apple-darwin`, an npm postinstall that fails on
+Windows) now surface in review.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** `release.yml`'s internal
+job graph collapsed from `plan → build → publish` to
+`build (uses: _matrix.yml) → publish`. The `publish` job now reads
+`needs.build.outputs.matrix` instead of `needs.plan.outputs.matrix`;
+the matrix payload is unchanged. Run logs show one nested-workflow
+group (`build / plan`, `build / build`) instead of two top-level
+jobs; existing log scrapers that fingerprint on the job name `plan`
+need to fingerprint on `build / plan` instead.
+
+**Verification.** On a repo that adds the build-check workflow, open
+a PR that touches a `[[package]].globs` glob. The PR's Checks tab
+shows a `build-check / build / build` matrix run. The job has no
+`id-token: write` permission (visible in the `Show all checks` tag
+on the run), and there is no `publish` job in the run's job graph.
+On `main`, the existing release flow is unaffected — a tag push +
+GitHub Release on the next workflow run.
+
 ### Crates dirty-check whitelists sibling package paths
 
 **Summary.** The engine's pre-publish dirty-workspace check

package/README.md

@@ -69,6 +69,31 @@ Optional inputs — `with:` block at the call site:
 | `node_version`   | `24`         | You need a specific Node version for `kind = "npm"` build steps.         |
 | `python_version` | `3.12`       | You need a specific Python version for `kind = "pypi"` build steps.      |
 
+### 1b. Optional: drop in `.github/workflows/build-check.yml`
+
+Run the same plan + build matrix on every PR, with the publish step
+structurally absent:
+
+```yaml
+name: Build check
+
+on:
+  pull_request: {}
+
+jobs:
+  build-check:
+    uses: thekevinscott/putitoutthere/.github/workflows/build.yml@v0
+```
+
+`build.yml` calls the same internal `_matrix.yml` reusable workflow that
+`release.yml` does — same action pins, same per-target build steps, same
+runners — so a PR that breaks `aarch64-apple-darwin` wheels surfaces
+in review instead of at release time. The publish job, the
+`id-token: write` permission, and the OIDC trusted-publisher exchanges
+do not exist on this code path; there is no flag, no input, no
+conditional that could ever cause it to publish. Same `node_version` /
+`python_version` inputs as `release.yml`; no new config to write.
+
 ### 2. Drop in `putitoutthere.toml`
 
 ```toml

package/package.json

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