@bounded-systems/mint 0.4.3

package/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: "22"
+      - run: npm ci --no-audit --no-fund
+      - run: npm test

package/.github/workflows/release-provenance.yml

@@ -0,0 +1,81 @@
+# Reusable release-provenance workflow (workflow_call). A consuming repo calls
+# this on a `v*` tag push (the tag `mint release` cut) with a ~10-line caller;
+# no install, no published package. mint is checked out here and run against the
+# caller's manifest + CHANGELOG, so fixing the tool once + bumping the pin
+# propagates mint's release flow to every repo.
+#
+#   # .github/workflows/release.yml in the consumer:
+#   name: release
+#   on:
+#     push:
+#       tags: ["v*"]
+#   permissions:
+#     contents: write
+#     id-token: write
+#   jobs:
+#     release:
+#       uses: bounded-systems/mint/.github/workflows/release-provenance.yml@<sha>
+#       with:
+#         ref: <sha>
+#
+# It emits the deterministic in-toto release Statement (tag → version plan →
+# commit) with `mint attest`, keyless-signs it with cosign (the workflow's OIDC
+# identity — no key material), and attaches the Statement + its Sigstore bundle
+# to the caller's GitHub release. Verify with `cosign verify-blob` (the same
+# bundle @bounded-systems/verify consumes).
+name: release-provenance (reusable)
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: "mint ref to run from (tag/sha for reproducibility)."
+        type: string
+        default: main
+      node-version:
+        description: "Node version for the mint runtime."
+        type: string
+        default: "22"
+
+permissions:
+  contents: write   # create / upload to the caller's GitHub release
+  id-token: write   # OIDC — cosign keyless signing
+
+jobs:
+  release-provenance:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout caller (at the tag)
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - name: Checkout mint
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          repository: bounded-systems/mint
+          ref: ${{ inputs.ref }}
+          path: .mint
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: ${{ inputs.node-version }}
+      - name: Install mint deps
+        working-directory: .mint
+        run: npm ci --no-audit --no-fund
+      # Run mint against the CALLER's repo (cwd = caller workspace), so it reads
+      # the caller's package.json + CHANGELOG.md + git HEAD.
+      - name: Emit the in-toto release Statement
+        env:
+          MINT_REF: ${{ inputs.ref }}
+        run: node .mint/mint.mjs attest --out mint-release.intoto.json
+      - name: Install cosign
+        uses: sigstore/cosign-installer@d7d6bc7722e3daa8354c50bcb52f4837da5e9b6a # v3.7.0
+      - name: Keyless-sign the release Statement (cosign, OIDC)
+        env:
+          COSIGN_EXPERIMENTAL: "1"
+        run: cosign sign-blob --yes --bundle mint-release.intoto.sigstore.json mint-release.intoto.json
+      - name: Attach provenance to the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          assets="mint-release.intoto.json mint-release.intoto.sigstore.json"
+          # Create the release from the tag annotation, or upload to it if it exists.
+          gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-from-tag $assets \
+            || gh release upload "$GITHUB_REF_NAME" $assets --clobber

package/.github/workflows/release.yml

@@ -0,0 +1,125 @@
+name: release
+
+# On a vX.Y.Z tag (pushed by `mint release`):
+#   release  — test, pack, SLSA-attest the tarball, emit + keyless-sign the
+#              in-toto release Statement (tag → version plan → commit), publish
+#              the GitHub release (notes from the tag annotation mint wrote) with
+#              the statement + its Sigstore bundle attached.
+#   publish  — stage on npm via OIDC trusted publishing (no tokens, ever) and
+#              publish to JSR. The npm package is staged, not live: a maintainer
+#              must approve it with 2FA before it appears on the registry.
+#              See job summary for the stage ID + approval instructions.
+#
+# This workflow covers: npm (staged) + JSR + GitHub release.
+# Out of scope here — triggered separately on the same tag:
+#   Nix flakes    — flake consumers pin a sha; update PRs are opened by the
+#                   flake-update bot when the tag lands on the default branch.
+#   GHCR images   — OCI builds run in their own repo/workflow and reference the
+#                   published npm tarball or the GitHub release asset.
+#   Other deploys — bounded-systems infra workflows consume the GH release event.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write      # create the GitHub release
+  id-token: write      # OIDC — SLSA attestation, cosign keyless, npm/JSR publishing
+  attestations: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: "22"
+      - run: npm ci --no-audit --no-fund
+      - run: npm test
+      - name: Pack the package
+        id: pack
+        run: echo "tgz=$(npm pack | tail -1)" >> "$GITHUB_OUTPUT"
+      - name: Attest build provenance (SLSA)
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2
+        with:
+          subject-path: ${{ steps.pack.outputs.tgz }}
+      # Release provenance: the deterministic in-toto Statement binding this tag to
+      # its version plan + commit. `mint attest` reproduces byte-for-byte what
+      # `mint release` wrote locally, now with the CI builder identity filled in.
+      - name: Emit the in-toto release Statement
+        run: node mint.mjs attest --out mint-release.intoto.json
+      - name: Install cosign
+        uses: sigstore/cosign-installer@d7d6bc7722e3daa8354c50bcb52f4837da5e9b6a # v3.7.0
+      # Keyless: no key material — the signature is bound to this workflow's OIDC
+      # identity via Fulcio + logged in Rekor. The self-contained --bundle is the
+      # same artifact @bounded-systems/verify consumes (cosign verify-blob).
+      - name: Keyless-sign the release Statement (cosign, OIDC)
+        env:
+          COSIGN_EXPERIMENTAL: "1"
+        run: cosign sign-blob --yes --bundle mint-release.intoto.sigstore.json mint-release.intoto.json
+      - name: Publish GitHub release (notes from the tag annotation)
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-from-tag \
+            "${{ steps.pack.outputs.tgz }}" \
+            mint-release.intoto.json \
+            mint-release.intoto.sigstore.json
+
+  publish:
+    needs: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: "24"                       # npm 11.15.0+ required for staged publishing
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci --no-audit --no-fund
+      - name: Publish or stage on npm (OIDC trusted publishing — no token)
+        id: stage
+        continue-on-error: true # JSR is the source of truth; npm failure must not block it
+        run: |
+          npm install -g npm@latest                # ensure npm 11.15.0+ for staged publishing
+          echo "npm version: $(npm --version)"
+          PKG=$(node -p "require('./package.json').name")
+          # npm stage publish requires the package to already exist on the registry.
+          # On first publish, fall back to npm publish to seed it; all subsequent
+          # releases go through the staged flow (human 2FA approval required).
+          if npm view "$PKG" version 2>/dev/null; then
+            echo "package exists — using npm stage publish"
+            npm stage publish --access public --provenance 2>&1 | tee /tmp/stage-out.txt || true
+          else
+            echo "first publish — seeding with npm publish (staged publishing requires existing package)"
+            npm publish --access public --provenance 2>&1 | tee /tmp/stage-out.txt || true
+          fi
+          STAGE_OUT=$(cat /tmp/stage-out.txt)
+          STAGE_ID=$(echo "$STAGE_OUT" | grep -oE '[A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}' | head -1 || true)
+          echo "stage_id=${STAGE_ID}" >> "$GITHUB_OUTPUT"
+      - name: Surface approval instructions
+        env:
+          STAGE_ID: ${{ steps.stage.outputs.stage_id }}
+          PKG: ${{ github.repository }}
+        run: |
+          {
+            echo "## npm package staged — human approval required"
+            echo ""
+            echo "The package is in the staging area, **not yet live on the registry**."
+            echo "A maintainer must approve it with 2FA before it becomes publicly available."
+            echo ""
+            if [ -n "$STAGE_ID" ]; then
+              echo "**Stage ID:** \`${STAGE_ID}\`"
+              echo ""
+              echo "**Approve via CLI (2FA required):**"
+              echo '```'
+              echo "npm stage approve ${STAGE_ID}"
+              echo '```'
+            else
+              echo "> Could not parse stage ID from npm output."
+              echo "> Run \`npm stage list @bounded-systems/mint\` to find it."
+            fi
+            echo ""
+            echo "**Or approve on npmjs.com:** open the [Staged Packages](https://www.npmjs.com/settings/~/packages/staged) tab."
+          } >> "$GITHUB_STEP_SUMMARY"
+      - name: Publish to JSR (OIDC — no token)
+        run: npx jsr publish --allow-slow-types

package/.github/workflows/version.yml

@@ -0,0 +1,48 @@
+# Reusable versioning check (workflow_call). A consuming repo calls this with a
+# ~6-line caller; no install, no published package. mint is checked out here and
+# run against the caller's .release/ intents, so fixing the tool once + bumping
+# the pin propagates to every repo.
+#
+#   jobs:
+#     version:
+#       uses: bounded-systems/mint/.github/workflows/version.yml@<sha>
+#
+# `mint plan` validates every intent (fails closed on a malformed one) and
+# previews the next version + changelog. It exits 0 when there are no intents.
+name: version (reusable)
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: "mint ref to run from (tag/sha for reproducibility)."
+        type: string
+        default: main
+      dir:
+        description: "Caller's intent directory."
+        type: string
+        default: .release
+
+permissions:
+  contents: read
+
+jobs:
+  version-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout caller
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - name: Checkout mint
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          repository: bounded-systems/mint
+          ref: ${{ inputs.ref }}
+          path: .mint
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: "22"
+      - name: Install mint deps
+        working-directory: .mint
+        run: npm ci --no-audit --no-fund
+      - name: mint plan (validate intents + preview next version)
+        run: node .mint/mint.mjs plan --dir "${{ github.workspace }}/${{ inputs.dir }}"

package/.release/README.md

@@ -0,0 +1,18 @@
+# Release intents
+
+One file per user-facing change, added in the PR that makes the change. `mint`
+collects every `*.md` here (except this README and `_`/`.`-prefixed files),
+resolves the strongest `bump`, and cuts the release deterministically.
+
+Format:
+
+```markdown
+---
+bump: minor   # patch | minor | major
+---
+scan: promote to a verb (CLI + MCP) + shared Zod type contracts
+```
+
+- `mint plan` — preview the next version + changelog entry (pure; pass `--date` to pin it).
+- `mint version` — apply: bump `package.json` + lockfile, prepend `CHANGELOG.md`, consume these intents.
+- `mint release` — cut the `v<version>` tag + emit the in-toto release provenance (keyless-signed in CI). `--dry-run` previews it.

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.4.3 — 2026-06-29
+
+### Patch
+
+- seed npm first publish — detect new package and fall back to `npm publish` before staging is available
+
+## 0.4.2 — 2026-06-29
+
+### Patch
+
+- retry staged npm publish — trusted publisher updated to allow staging
+
+## 0.4.1 — 2026-06-29
+
+### Patch
+
+- fix publish logging — stream npm stage output so errors are visible in CI (was silently swallowed by set -e)
+
+## 0.4.0 — 2026-06-29
+
+### Minor
+
+- staged npm publishing — `npm stage publish` replaces direct publish; human 2FA approval gate before the package goes live
+
+## 0.3.1 — 2026-06-29
+
+### Patch
+
+- release: JSR publish must not be blocked by the brand-new-npm-package step (continue-on-error)
+
+## 0.3.0 — 2026-06-29
+
+### Minor
+
+- mint release: cut the tag + emit a deterministic in-toto release Statement (tag → version plan → commit), keyless-signed in CI (cosign/Sigstore; anchored-chain-shaped); `mint attest` re-emits it; reusable release-provenance.yml workflow_call for consumers
+
+### Patch
+
+- publish-prep: make the package cleanly JSR-publishable — `jsr.json` gains the SPDX `license` + a `publish.include` allowlist (tarball = exports + mint.mjs + README + CHANGELOG); `@types/node` dev dependency so the JSR type-checker resolves the `node:` imports. `npx jsr publish --dry-run` and `deno publish --dry-run` both pass.
+
+## 0.2.0 — 2026-06-24
+
+### Minor
+
+- mint release verb (signed tag) + SLSA provenance release workflow
+
+## 0.1.0 — 2026-06-24
+
+### Minor
+
+- Deterministic plan core (pure intents+version→version+changelog) + Zod intent contract + CLI (plan/version)
+- Reusable version.yml workflow + org adoption scanner (--write rollout)
+

package/README.md

@@ -0,0 +1,176 @@
+# @bounded-systems/mint
+
+Deterministic versioning — **intent files in, signed release out**. A *seam over
+[`semver`](https://github.com/npm/node-semver)*: mint owns the flow (intent
+assembly, changelog, tagging, provenance) and delegates only the version
+arithmetic to the proven core.
+
+Built because tagging-by-hand drifts: a manifest left behind its release tags is
+a recurring bug ([string-audit#42](https://github.com/bounded-systems/string-audit/issues/42)).
+mint makes the version a per-PR declaration and the release a single atomic step.
+
+## Principles
+
+- **Opinionated** — one canonical release flow, no configurable branching.
+- **Strongly deterministic** — `plan()` is a *pure function* of `(currentVersion, intents, date)`. No commit-history ordering, no `Date.now()`, no randomness. Same intents in → same version + changelog out (sha in → sha out).
+- **Typed end-to-end** — intents and plan validated with Zod; a verbspec CLI/MCP surface mirrors the rest of the stack.
+- **Owned** — delegate only `semver` arithmetic; own assembly, rendering, tagging, and provenance.
+
+## Use
+
+Each PR drops an intent in `.release/` (see [`.release/README.md`](.release/README.md)):
+
+```markdown
+---
+bump: minor
+---
+scan: promote to a verb (CLI + MCP) + shared Zod type contracts
+```
+
+Then:
+
+```sh
+mint plan      # preview: 0.6.1 → 0.7.0 (minor) + the changelog entry
+mint version   # apply: bump package.json + lockfile, prepend CHANGELOG.md, consume intents
+mint release   # cut the v<version> tag + emit release provenance (CI keyless-signs it)
+```
+
+`mint plan --json` emits the machine-readable plan. `--date YYYY-MM-DD` pins the
+changelog date (the pure core never reads the clock; the CLI injects it).
+
+## Release provenance
+
+`mint release` cuts the annotated tag `v<version>` (signed when a git signing key
+is configured) **and** emits a release **provenance record** — an
+[in-toto Statement v1](https://in-toto.io/Statement/v1) binding the three things a
+release is:
+
+```
+tag  →  version plan  →  commit
+```
+
+The subject is the tag, anchored to its commit (in-toto `gitCommit` digest); the
+predicate carries the byte-exact changelog entry (the deterministic `plan()`
+output) and its `sha256`. Re-deriving the plan over the same intents reproduces
+that digest — the tag-to-plan link is machine-checkable, offline.
+
+The Statement is **deterministic** (`releaseStatement()` is pure, like `plan()`)
+and **keyless-signed in CI**: `release.yml` runs `mint attest`, then
+`cosign sign-blob` binds the signature to the workflow's OIDC identity (Fulcio +
+Rekor — no key material). Locally the Statement is emitted **unsigned**
+(`builder: null`) so the flow degrades gracefully off-CI. This is the same
+Statement / DSSE / keyless-Sigstore shape the bounded-systems sites and
+[`@bounded-systems/verify`](https://github.com/bounded-systems/verify) already
+produce and verify, so a mint release record verifies with the same tooling:
+
+```sh
+cosign verify-blob \
+  --bundle mint-release.intoto.sigstore.json \
+  --certificate-identity-regexp '^https://github.com/<org>/<repo>/' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  mint-release.intoto.json
+```
+
+> **anchored-chain:** mint deliberately mirrors
+> [`anchored-chain`](https://github.com/bounded-systems/anchored-chain)'s in-toto
+> constants + Statement/DSSE shape rather than depending on it: anchored-chain's
+> in-toto module is Phase-0 and not yet re-exported from its public surface, is
+> bun/TypeScript with a build step, and its predicate models a *derivation
+> chain*, not a release. mint stays a zero-build node ESM package and can adopt
+> anchored-chain's `Signer`/`Verifier` once that surface lands — the bytes
+> already match.
+
+### Adopt mint's release in CI
+
+A consumer repo calls the reusable
+[`release-provenance.yml`](.github/workflows/release-provenance.yml) on its tag
+push (a ~10-line caller — see the header of that workflow):
+
+```yaml
+# .github/workflows/release.yml
+name: release
+on: { push: { tags: ["v*"] } }
+permissions: { contents: write, id-token: write }
+jobs:
+  release:
+    uses: bounded-systems/mint/.github/workflows/release-provenance.yml@<sha>
+    with: { ref: <sha> }
+```
+
+`adoption.mjs --write` drops both this caller and the `version.yml` caller into
+every publishable repo — the path off hand-tagging.
+
+## Publish (npm + JSR)
+
+mint ships from `release.yml` on each `v*` tag via **OIDC trusted publishing** —
+no `NPM_TOKEN`, no JSR token, ever. The package manifests are kept in lockstep by
+`mint version` (it bumps `package.json`, `package-lock.json`, **and** `jsr.json`).
+
+**npm uses staged publishing** — `npm stage publish` submits the package to a
+staging area rather than making it live immediately. A maintainer must approve it
+with 2FA before it appears on the registry:
+
+```sh
+npm stage approve <stage-id>   # CLI, 2FA required
+# or: npmjs.com → Staged Packages tab → Approve
+```
+
+The stage ID is surfaced in the GitHub Actions job summary after each release run.
+
+**JSR publishes immediately** on the same tag (no staging concept on JSR).
+
+JSR-readiness is verified the same way CI publishes:
+
+```sh
+npx jsr publish --dry-run --allow-slow-types   # the path release.yml runs
+deno publish    --dry-run --allow-slow-types   # equivalent, Deno-native
+```
+
+`jsr.json` carries the SPDX `license` and a `publish.include` allowlist, so the
+published tarball is just the three exports + `mint.mjs`, `README`, `CHANGELOG`
+(no tests, lockfiles, or workflows). `@types/node` is a dev dependency so the
+JSR type-checker resolves mint's `node:` imports.
+
+> **One-time JSR link (manual, once):** before the first JSR publish, link the
+> package on [jsr.io](https://jsr.io) — create `@bounded-systems/mint` under the
+> `@bounded-systems` scope and connect it to the `bounded-systems/mint` GitHub
+> repo (Settings → "Link to a GitHub repository"). That GitHub link is what
+> authorizes the keyless OIDC publish; after it, every tagged release publishes
+> with no token.
+
+## Library
+
+```js
+import { plan } from "@bounded-systems/mint";
+import { releaseStatement } from "@bounded-systems/mint/release";
+
+plan({
+  currentVersion: "0.6.1",
+  intents: [{ bump: "minor", summary: "scan: promote to a verb" }],
+  date: "2026-06-23",
+}).nextVersion; // "0.7.0"
+
+releaseStatement({
+  version: "0.7.0",
+  tag: "v0.7.0",
+  commit: "0123456789abcdef0123456789abcdef01234567",
+  date: "2026-06-23",
+  changelog: "## 0.7.0 — 2026-06-23\n\n### Minor\n\n- scan: promote to a verb\n",
+  producer: "@bounded-systems/mint",
+})._type; // "https://in-toto.io/Statement/v1"
+```
+
+## Roadmap
+
+- [x] Deterministic `plan` core + Zod intent contract
+- [x] `mint plan` / `mint version`
+- [x] `mint release` — signed tag + in-toto release provenance, keyless-signed in CI (cosign/Sigstore; anchored-chain-shaped)
+- [ ] verbspec-typed CLI + MCP surface
+- [x] Reusable `workflow_call` Action (`version.yml` + `release-provenance.yml`)
+- [x] Publish to npm (staged, human 2FA approval gate) + JSR
+
+Tracking: [bounded-systems/string-audit#43](https://github.com/bounded-systems/string-audit/issues/43).
+
+## License
+
+PolyForm-Noncommercial-1.0.0