@bounded-systems/mint 0.4.3

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@bounded-systems/mint",
+  "version": "0.4.3",
+  "description": "Deterministic versioning capability — intent files in, signed release out. A seam over semver: own the flow, delegate the arithmetic.",
+  "type": "module",
+  "bin": {
+    "mint": "mint.mjs"
+  },
+  "exports": {
+    ".": "./plan.mjs",
+    "./intents": "./intents.mjs",
+    "./release": "./release.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "plan": "node mint.mjs plan"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "semver": "^7.6.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  }
+}

package/plan.mjs

@@ -0,0 +1,90 @@
+// The deterministic core of mint.
+//
+// plan() is a PURE function of (currentVersion, intents, date): no filesystem,
+// no Date.now(), no randomness. The same inputs always produce the same next
+// version and the same changelog entry — sha in → sha out. Version arithmetic is
+// delegated to `semver` (the proven core); mint owns the assembly + rendering.
+import semver from "semver";
+import { z } from "zod";
+
+// Bump precedence — the strongest intent wins. Opinionated and total: every
+// release resolves to exactly one bump kind, no configuration.
+const BUMP_RANK = { patch: 0, minor: 1, major: 2 };
+const RANK_BUMP = ["patch", "minor", "major"];
+
+export const Bump = z.enum(["patch", "minor", "major"]);
+export const Intent = z.object({
+  bump: Bump,
+  summary: z.string().trim().min(1, "intent summary must not be empty"),
+});
+
+const PlanInput = z.object({
+  currentVersion: z.string().refine((v) => semver.valid(v) != null, "currentVersion must be valid semver"),
+  intents: z.array(Intent),
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "date must be YYYY-MM-DD (injected, never wall-clock)"),
+});
+
+// Resolve the set of intents to a single bump kind (the max), deterministically.
+export function resolveBump(intents) {
+  let rank = -1;
+  for (const { bump } of intents) rank = Math.max(rank, BUMP_RANK[bump]);
+  return rank < 0 ? null : RANK_BUMP[rank];
+}
+
+// Render a deterministic changelog entry. Intents are grouped by kind (major →
+// minor → patch) and sorted alphabetically within each group, so file read order
+// never affects the output.
+export function renderEntry({ nextVersion, date, intents }) {
+  const SECTIONS = [
+    ["major", "Major"],
+    ["minor", "Minor"],
+    ["patch", "Patch"],
+  ];
+  const lines = [`## ${nextVersion} — ${date}`, ""];
+  for (const [kind, heading] of SECTIONS) {
+    const summaries = intents
+      .filter((i) => i.bump === kind)
+      .map((i) => i.summary.trim())
+      .sort();
+    if (!summaries.length) continue;
+    lines.push(`### ${heading}`, "");
+    for (const s of summaries) lines.push(`- ${s}`);
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+// Extract the changelog section for a version: the `## <version> …` heading and
+// everything up to the next `## ` heading (or EOF). Pure; returns null if absent.
+// Used by `mint release` to derive the signed tag's annotation from the changelog.
+export function changelogEntry(changelog, version) {
+  const lines = changelog.split("\n");
+  const esc = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const head = new RegExp(`^## ${esc}(\\s|$)`);
+  const start = lines.findIndex((l) => head.test(l));
+  if (start < 0) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) { end = i; break; }
+  }
+  return lines.slice(start, end).join("\n").trim() + "\n";
+}
+
+// Pure plan: (currentVersion, intents, date) → release plan. Throws (via Zod) on
+// malformed input; returns null bump when there are no intents (nothing to release).
+export function plan(input) {
+  const { currentVersion, intents, date } = PlanInput.parse(input);
+  const bump = resolveBump(intents);
+  if (bump == null) {
+    return { currentVersion, nextVersion: currentVersion, bump: null, date, entry: null, intents: [] };
+  }
+  const nextVersion = semver.inc(currentVersion, bump);
+  return {
+    currentVersion,
+    nextVersion,
+    bump,
+    date,
+    entry: renderEntry({ nextVersion, date, intents }),
+    intents,
+  };
+}

package/release.mjs

@@ -0,0 +1,130 @@
+// release.mjs — the pure provenance core of `mint release`.
+//
+// releaseStatement() is a PURE function of (version, tag, commit, date,
+// changelog, producer, builder): no filesystem, no clock, no randomness. The
+// same inputs always produce a byte-identical in-toto Statement — sha in → sha
+// out, like plan(). It binds three things into one signable record:
+//
+//     tag  →  version plan  →  commit
+//
+// i.e. "this annotated tag names exactly this version, whose changelog is the
+// byte-exact output mint's deterministic plan() rendered, cut at this commit."
+//
+// SHAPE: an in-toto Statement v1 + DSSE pre-authentication encoding — the SAME
+// Statement/DSSE/keyless-Sigstore shape the bounded-systems sites and
+// @bounded-systems/verify already produce and verify, so a mint release record
+// verifies with the SAME tooling (`cosign verify-blob`, sigstore-js). The
+// constants below are deliberately the ones @bounded-systems/anchored-chain's
+// in-toto module pins, so the artifacts are interoperable.
+//
+// WHY NOT depend on @bounded-systems/anchored-chain directly: it HAS an in-toto
+// module (src/in-toto.ts) but it is Phase-0 and deliberately NOT re-exported
+// from its public surface (pinned by import-surface.test.ts); it is bun/
+// TypeScript with a `tsc` build step and an @bounded-systems/cas dependency; and
+// its predicate models a *derivation chain*, not a release. mint stays a
+// zero-build node ESM package, so it mirrors the shape here and can adopt
+// anchored-chain's Signer/Verifier once that surface goes public — no churn at
+// the boundary, because the bytes already match.
+import { createHash } from "node:crypto";
+import { z } from "zod";
+
+/** Standard in-toto Statement v1 type URI (matches anchored-chain). */
+export const STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+/** mint's release predicate type URI. */
+export const RELEASE_PREDICATE_TYPE = "https://bounded.tools/mint/Release/v0.1";
+/** DSSE payload type for in-toto Statement JSON (matches anchored-chain). */
+export const DSSE_PAYLOAD_TYPE = "application/vnd.in-toto+json";
+
+const sha256hex = (s) => createHash("sha256").update(s, "utf8").digest("hex");
+
+// Canonical JSON: object keys sorted recursively, no insignificant whitespace —
+// the same value serialises to the same bytes regardless of key insertion order,
+// so the digest and the DSSE payload are stable. (Mirrors anchored-chain's
+// canonicalJson contract.)
+export function canonicalize(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+// v<semver> — the only tag shape mint cuts. Kept in lockstep with `v${version}`
+// in mint.mjs so a malformed version can never become a malformed tag silently.
+const Tag = z
+  .string()
+  .regex(/^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/, "tag must be v<semver>");
+// A git object id (sha1 today, sha256 under SHA-256 repos), or its short form.
+const GitObjectId = z.string().regex(/^[0-9a-f]{7,64}$/, "commit must be a hex git object id");
+
+// The CI signing identity (keyless OIDC). Present only in CI; null locally.
+// Mirrors the `builder` block the bounded-systems sites publish in provenance.json.
+export const Builder = z.object({
+  repository: z.string(),
+  commit: z.string(),
+  ref: z.string(),
+  runId: z.string(),
+  workflowRef: z.string(),
+  issuer: z.string(),
+});
+
+export const ReleaseInput = z.object({
+  version: z.string().min(1),
+  tag: Tag,
+  commit: GitObjectId,
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "date must be YYYY-MM-DD (injected, never wall-clock)"),
+  changelog: z.string().min(1, "changelog entry must not be empty (run `mint version` first)"),
+  producer: z.string().min(1),
+  builder: Builder.nullable().default(null),
+});
+
+/**
+ * Pure: build the in-toto Statement v1 binding tag → version plan → commit.
+ * Throws (via Zod) on any malformed input — a release record is fail-closed.
+ */
+export function releaseStatement(input) {
+  const { version, tag, commit, date, changelog, producer, builder } = ReleaseInput.parse(input);
+  return {
+    _type: STATEMENT_TYPE,
+    // The subject IS the tag, anchored to the commit it points at (in-toto's
+    // standard `gitCommit` digest algorithm).
+    subject: [{ name: tag, digest: { gitCommit: commit } }],
+    predicateType: RELEASE_PREDICATE_TYPE,
+    predicate: {
+      version,
+      tag,
+      commit,
+      date,
+      producer,
+      // The version plan, bound by the byte-exact changelog entry mint rendered.
+      // Re-deriving plan() over the same intents reproduces this digest — that is
+      // the "version plan → tag" link, machine-checkable offline.
+      plan: {
+        changelog,
+        digest: { sha256: sha256hex(changelog) },
+      },
+      // null ⇒ produced locally and UNSIGNED; signing is CI-only (keyless OIDC).
+      builder: builder ?? null,
+    },
+  };
+}
+
+/**
+ * DSSE pre-authentication encoding (PAE) over the canonical Statement — the exact
+ * bytes a DSSE/Sigstore signer signs. Same scheme as anchored-chain, so a mint
+ * release envelope is a well-formed DSSE envelope.
+ */
+export function dssePAE(statement) {
+  const payload = Buffer.from(canonicalize(statement), "utf8");
+  const t = DSSE_PAYLOAD_TYPE;
+  return Buffer.concat([
+    Buffer.from(`DSSEv1 ${t.length} ${t} ${payload.length} `, "utf8"),
+    payload,
+  ]);
+}
+
+/** sha256 (hex) of the canonical Statement — a stable id for the release record. */
+export function statementDigest(statement) {
+  return sha256hex(canonicalize(statement));
+}