@monte3l/groundwork 0.1.0-next.1 → 1.0.0-rc.3

package/templates/packs/publishing/files/bin/check-license-headers.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright the __PROJECT_NAME__ contributors
+// SPDX-License-Identifier: NOASSERTION
+
+/**
+ * Checks (and, with `--fix`, inserts) an SPDX copyright/license header on
+ * every tracked source file -- OpenSSF Best Practices' Gold-level
+ * `copyright_per_file`/`license_per_file` criteria.
+ *
+ * Two disjoint mechanisms cover every tracked file (`git ls-files`), never
+ * both for the same file:
+ *   - **An inline header** (`SPDX-FileCopyrightText` + `SPDX-License-Identifier`,
+ *     as a line comment) on every `.ts`/`.mjs`/`.js`/`.sh`/`.yml`/`.yaml`
+ *     file, except anything a `REUSE.toml` annotation already claims (a
+ *     generated file with that extension, such as a committed lockfile, has
+ *     nothing meaningful to carry a hand-written header in).
+ *   - **A `REUSE.toml` annotation** for everything else: data files and
+ *     dotfiles with no comment syntax of their own (JSON, Markdown,
+ *     `.gitignore`, `.npmrc`, `.node-version`, `.prettierignore`, `LICENSE`).
+ *
+ * `--check` (default, the `pnpm verify` gate's `license-headers` step):
+ * exits 1 and lists every header-eligible file missing the header, AND every
+ * tracked file that is neither header-eligible nor matched by a `REUSE.toml`
+ * glob (a gap in the REUSE annotation set itself, not just a missing
+ * header). `--fix`: inserts the header into every header-eligible file
+ * missing one, after a shebang line if present, and leaves every other line
+ * untouched.
+ */
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(fileURLToPath(import.meta.url), "..", "..");
+
+/** Extensions that carry an inline SPDX header via a `#`/`//` line comment. */
+const HEADER_EXTENSIONS = new Set([
+  ".ts",
+  ".mjs",
+  ".js",
+  ".sh",
+  ".yml",
+  ".yaml",
+]);
+
+const HASH_COMMENT_EXTENSIONS = new Set([".sh", ".yml", ".yaml"]);
+
+const COPYRIGHT_MARKER = "SPDX-FileCopyrightText:";
+const LICENSE_MARKER = "SPDX-License-Identifier:";
+
+function headerLines(ext) {
+  const prefix = HASH_COMMENT_EXTENSIONS.has(ext) ? "#" : "//";
+  return [
+    `${prefix} SPDX-FileCopyrightText: Copyright the __PROJECT_NAME__ contributors`,
+    `${prefix} SPDX-License-Identifier: NOASSERTION`,
+  ];
+}
+
+/**
+ * Every path git tracks, repo-root-relative, forward-slash-separated.
+ * `-z` NUL-delimits the output instead of newline-delimiting it, so a path
+ * containing a character `core.quotePath` would otherwise quote/escape
+ * (non-ASCII, a literal newline) comes back exactly as git stores it,
+ * matching what `readFileSync`/`writeFileSync` expect.
+ */
+function listTrackedFiles() {
+  return execFileSync("git", ["-C", repoRoot, "ls-files", "-z"], {
+    encoding: "utf8",
+  })
+    .split("\0")
+    .filter((line) => line.length > 0);
+}
+
+/**
+ * A tiny, deliberately non-general glob-to-regex translator: only `**`
+ * (any number of path segments, including zero) and `*` (anything but `/`)
+ * are supported, which is all `REUSE.toml`'s own patterns use. Every other
+ * character is treated literally.
+ */
+function globToRegExp(glob) {
+  let pattern = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*" && glob[i + 1] === "*") {
+      if (glob[i + 2] === "/") {
+        pattern += "(?:.*/)?";
+        i += 2;
+      } else {
+        pattern += ".*";
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === "*") {
+      pattern += "[^/]*";
+      continue;
+    }
+    if (/[.+^${}()|[\]\\?]/.test(ch)) {
+      pattern += `\\${ch}`;
+      continue;
+    }
+    pattern += ch;
+  }
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * Every `path = [...]` glob string across every `[[annotations]]` block in
+ * `REUSE.toml`. Only the array form (`path = ["a", "b"]`) is supported, not
+ * REUSE's single-string form (`path = "a"`) or single-quoted strings -- if
+ * that ever changes, a silently-dropped annotation would quietly shrink
+ * REUSE.toml's coverage, so this counts `[[annotations]]` blocks against
+ * blocks that actually yielded a `path` array and fails loudly on a
+ * mismatch rather than trusting an empty result.
+ */
+function readReuseGlobs() {
+  const content = readFileSync(join(repoRoot, "REUSE.toml"), "utf8");
+  const blockCount = (content.match(/^\[\[annotations]]/gm) ?? []).length;
+  const globs = [];
+  const blockPattern = /\[\[annotations]][\s\S]*?path\s*=\s*\[([\s\S]*?)]/g;
+  let parsedBlocks = 0;
+  for (const match of content.matchAll(blockPattern)) {
+    parsedBlocks += 1;
+    const arrayBody = match[1] ?? "";
+    for (const stringMatch of arrayBody.matchAll(/"([^"]*)"/g)) {
+      const glob = stringMatch[1];
+      if (glob !== undefined) globs.push(glob);
+    }
+  }
+  if (parsedBlocks !== blockCount) {
+    throw new Error(
+      `check-license-headers: REUSE.toml has ${blockCount} [[annotations]] block(s) but only ` +
+        `${parsedBlocks} had a parseable \`path = [...]\` array -- this parser only supports ` +
+        "that array form; check for a single-string or single-quoted `path` value.",
+    );
+  }
+  return globs;
+}
+
+function hasHeader(content) {
+  const firstLines = content.split("\n", 6).join("\n");
+  return (
+    firstLines.includes(COPYRIGHT_MARKER) && firstLines.includes(LICENSE_MARKER)
+  );
+}
+
+function withHeaderInserted(content, ext) {
+  const lines = content.split("\n");
+  const hasShebang = lines[0]?.startsWith("#!") ?? false;
+  const insertAt = hasShebang ? 1 : 0;
+  lines.splice(insertAt, 0, ...headerLines(ext), "");
+  return lines.join("\n");
+}
+
+function main() {
+  const fix = process.argv.includes("--fix");
+  const tracked = listTrackedFiles();
+  const reuseGlobs = readReuseGlobs().map(globToRegExp);
+  const isReuseExempt = (path) => reuseGlobs.some((re) => re.test(path));
+
+  const headerEligible = tracked.filter(
+    (path) => HEADER_EXTENSIONS.has(extname(path)) && !isReuseExempt(path),
+  );
+  const uncovered = tracked.filter(
+    (path) => !HEADER_EXTENSIONS.has(extname(path)) && !isReuseExempt(path),
+  );
+
+  if (uncovered.length > 0) {
+    console.error(
+      `check-license-headers: ${uncovered.length} tracked file(s) are neither header-eligible ` +
+        "nor matched by a REUSE.toml annotation -- add a glob to REUSE.toml or an extension to " +
+        "HEADER_EXTENSIONS:",
+    );
+    for (const path of uncovered) console.error(`  ${path}`);
+    process.exit(1);
+  }
+
+  let fixedCount = 0;
+  const missing = [];
+
+  for (const path of headerEligible) {
+    const absolute = join(repoRoot, path);
+    const content = readFileSync(absolute, "utf8");
+    if (hasHeader(content)) continue;
+    if (fix) {
+      writeFileSync(absolute, withHeaderInserted(content, extname(path)));
+      fixedCount += 1;
+    } else {
+      missing.push(path);
+    }
+  }
+
+  if (fix) {
+    console.log(`check-license-headers: fixed ${fixedCount} file(s)`);
+    return;
+  }
+
+  if (missing.length > 0) {
+    console.error(
+      `check-license-headers: ${missing.length} file(s) missing an SPDX header ` +
+        "(SPDX-FileCopyrightText + SPDX-License-Identifier):",
+    );
+    for (const path of missing) console.error(`  ${path}`);
+    console.error(
+      "Run `node bin/check-license-headers.mjs --fix` to insert them.",
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `check-license-headers: ok -- ${headerEligible.length} file(s) carry an SPDX header, ` +
+      `${tracked.length - headerEligible.length} covered by REUSE.toml`,
+  );
+}
+
+main();

package/templates/packs/publishing/files/bin/check-publish-version.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright the __PROJECT_NAME__ contributors
+// SPDX-License-Identifier: NOASSERTION
+
+/**
+ * Checks that the version this project's `package.json` currently declares
+ * has not already been published to npm -- catches a version bump that
+ * silently duplicates one already live (a stale manual edit, a rebase that
+ * dropped a changeset), surfaced here rather than as a cryptic registry
+ * rejection deep inside the release workflow's `publish` job.
+ *
+ * Deliberately NOT one of this pack's `pnpm verify` steps: with changesets,
+ * `package.json`'s version on the release branch is always the one just
+ * published between releases, so running this on every ordinary push would
+ * fail every single time until the next version PR lands. Invoke it
+ * directly, once, right before packing -- see `release.yml`'s `pack` job.
+ *
+ * A no-op (`checked: 0`, exit 0), not a failure, when:
+ * - `package.json` has `private: true` (the baseline's own default) -- there
+ *   is nothing to publish, so nothing to check.
+ * - The registry lookup fails for a reason other than "package not found"
+ *   (network error, timeout, registry outage, an unparseable body) -- this
+ *   is a best-effort due-diligence check, not a hard dependency on the
+ *   registry being reachable; a real duplicate-version publish still fails
+ *   at `npm stage publish` itself, which is the actual enforcement point.
+ *
+ * A package that has never been published at all (the registry 404s) is
+ * also fine: there is no prior version to collide with. A 404 can also mean
+ * a scoped/restricted package the anonymous registry lookup can't see --
+ * this check has no npm auth token to look further, so it reports that
+ * possibility rather than asserting the package has definitely never
+ * published.
+ *
+ * A non-private `package.json` missing `name` or `version` is a real
+ * misconfiguration, not something to wave through: the version and dts-deps
+ * gates only make sense once both fields say what's actually being shipped.
+ */
+import process from "node:process";
+import { readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(fileURLToPath(import.meta.url), "..", "..");
+const REGISTRY_TIMEOUT_MS = 10_000;
+
+/**
+ * @param {string} name
+ * @param {typeof fetch} fetchImpl
+ * @returns {Promise<{ ok: true, versions: string[] } | { ok: false, reason: string }>}
+ * `ok: false` means the lookup could not be completed (network error,
+ * timeout, a non-404 error status, an unparseable body) -- distinct from
+ * "the package has never been published" (a 404), which resolves
+ * `{ ok: true, versions: [] }`.
+ */
+export async function fetchPublishedVersions(name, fetchImpl) {
+  let response;
+  try {
+    response = await fetchImpl(
+      `https://registry.npmjs.org/${encodeURIComponent(name).replaceAll("%40", "@")}`,
+      { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) },
+    );
+  } catch (cause) {
+    return {
+      ok: false,
+      reason: `request failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+    };
+  }
+  if (response.status === 404) {
+    return { ok: true, versions: [] };
+  }
+  if (!response.ok) {
+    return {
+      ok: false,
+      reason: `registry responded with HTTP ${String(response.status)}`,
+    };
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return { ok: false, reason: "registry response body was not valid JSON" };
+  }
+  const versions = body?.versions;
+  if (versions === null || typeof versions !== "object") {
+    return {
+      ok: false,
+      reason: 'registry response had no usable "versions" field',
+    };
+  }
+  return { ok: true, versions: Object.keys(versions) };
+}
+
+async function main() {
+  const pkgPath = join(repoRoot, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+
+  if (pkg?.private === true) {
+    console.log("check-publish-version: package.json is private -- skipping");
+    return;
+  }
+  const name = pkg?.name;
+  const version = pkg?.version;
+  if (typeof name !== "string" || name.length === 0) {
+    console.error(
+      "check-publish-version: package.json has no name, but is not private -- " +
+        "either set private: true, or give it a real name",
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (typeof version !== "string" || version.length === 0) {
+    console.error("check-publish-version: package.json has no version");
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = await fetchPublishedVersions(name, fetch);
+  if (!result.ok) {
+    console.log(
+      `check-publish-version: could not check the npm registry for "${name}" -- skipping ` +
+        `(${result.reason}; best-effort check, a real duplicate version still fails at publish time)`,
+    );
+    return;
+  }
+  if (result.versions.includes(version)) {
+    console.error(
+      `check-publish-version: ${name}@${version} is already published -- bump the version ` +
+        "(or add a changeset, if this project uses one) before releasing again",
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (result.versions.length === 0) {
+    console.log(
+      `check-publish-version: ok -- ${name}@${version} (the registry has no published versions ` +
+        "for this name -- either it has never published, or it's a scoped/restricted package an " +
+        "anonymous lookup can't see)",
+    );
+    return;
+  }
+  console.log(`check-publish-version: ok -- ${name}@${version} is unpublished`);
+}
+
+if (
+  process.argv[1] !== undefined &&
+  fileURLToPath(import.meta.url) === realpathSync(process.argv[1])
+) {
+  await main();
+}

package/templates/packs/publishing/files/bin/lib/npm-publish-args.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright the __PROJECT_NAME__ contributors
+// SPDX-License-Identifier: NOASSERTION
+
+/**
+ * Translates the one `pnpm publish` invocation changesets makes for a packed
+ * tarball into the equivalent `npm stage publish`, for `pnpm-publish-shim.mjs`.
+ *
+ * Changesets runs (see its `lib/pnpm.ts`):
+ *   pnpm publish <tarball> [--json] --access <a> --tag <t> --no-git-checks [--otp <c>]
+ *
+ * `--json` and `--no-git-checks` are pnpm-only and dropped. Anything not listed
+ * is refused rather than guessed at: if changesets ever starts passing a flag
+ * this does not understand, publishing must stop, not silently do something else.
+ *
+ * Staged, not direct: a trusted publisher created since 2026-09-03 defaults to
+ * `npm stage publish` only, npm's own default (and explicit recommendation) --
+ * a maintainer must separately run `npm stage approve <id>` (2FA, never
+ * automatable) before a staged version actually goes live. `npm stage publish`
+ * accepts the same `--access`/`--tag`/`--otp`/`--provenance` flags as
+ * `npm publish` ("parity with npm publish" per npm's own CLI reference); the
+ * command itself is `npm stage publish`, not a flag on `npm publish`.
+ */
+
+const DROPPED = new Set(["--json", "--no-git-checks"]);
+const WITH_VALUE = new Set(["--access", "--tag", "--otp"]);
+
+/**
+ * @param {string[]} args the arguments following `pnpm publish`
+ * @returns {string[]} the argument vector for `npm stage publish`
+ */
+export function toNpmStagePublishArgs(args) {
+  let tarball;
+  const flags = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (DROPPED.has(arg)) continue;
+
+    if (WITH_VALUE.has(arg)) {
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new Error(`${arg} needs a value`);
+      }
+      flags.push(arg, value);
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new Error(`unsupported flag ${arg}`);
+    }
+    if (tarball !== undefined) {
+      throw new Error(`expected one tarball, got a second argument: ${arg}`);
+    }
+    tarball = arg;
+  }
+
+  if (tarball === undefined) {
+    throw new Error(
+      "no tarball given: this shim only publishes packed tarballs (changesets' --from-pack-dir mode)",
+    );
+  }
+
+  // Provenance is requested explicitly rather than relied on: npm's automatic
+  // attestation for trusted publishing has been reported not to engage without it.
+  // "stage", "publish" are two separate words (the npm-stage subcommand), not
+  // "stage-publish" or a flag -- see npm's own CLI reference for npm-stage.
+  return ["stage", "publish", tarball, ...flags, "--provenance"];
+}
+
+/**
+ * `PATH` with `dir` removed, so the shim can find the real `pnpm` behind it.
+ * @param {string | undefined} pathValue
+ * @param {string | undefined} dir
+ * @param {string} separator
+ */
+export function pathWithout(pathValue, dir, separator) {
+  if (pathValue === undefined || dir === undefined || dir === "") {
+    return pathValue ?? "";
+  }
+  return pathValue
+    .split(separator)
+    .filter((entry) => entry !== dir)
+    .join(separator);
+}

package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright the __PROJECT_NAME__ contributors
+// SPDX-License-Identifier: NOASSERTION
+
+/**
+ * Put ahead of the real `pnpm` on PATH by the release workflow's `publish`
+ * job. Everything passes straight through to pnpm except `publish`, which
+ * this rewrites into `npm stage publish` instead.
+ *
+ * ## Why it exists
+ *
+ * Two independent reasons this can't be `pnpm publish`, stacked:
+ * 1. `changeset publish` in a pnpm-managed project publishes through
+ *    `pnpm publish`, and pnpm 12's native publish does its own OIDC
+ *    exchange, which npmjs.com rejects (`403 OIDC permission denied`) even
+ *    for a correctly configured trusted publisher. The npm CLI's exchange
+ *    works.
+ * 2. It can't be a direct `npm publish` either: a trusted publisher created
+ *    since 2026-09-03 defaults to `npm stage publish` only, npm's own
+ *    explicit recommendation (see this pack's adoptNotes). A direct
+ *    `npm publish` gets the exact same 403 "OIDC permission denied" as the
+ *    pnpm case, for an unrelated reason: the token exchange succeeds, but
+ *    the registry refuses the specific action.
+ *
+ * ## What it translates
+ *
+ * Only the exact `pnpm publish` invocation changesets makes -- everything
+ * else (install, other pnpm subcommands) passes straight through to the real
+ * `pnpm` unmodified. Routing only the publish keeps changesets in charge of
+ * everything else it does around it -- the publish plan, ordering, git tags,
+ * GitHub Releases -- instead of reimplementing any of that. A consequence
+ * worth knowing: those git tags and Releases are created the moment
+ * `npm stage publish` succeeds, which is *before* the package is actually
+ * live -- staging still needs a maintainer to run `npm stage approve <id>`
+ * (2FA, never automatable).
+ *
+ * ## What it refuses
+ *
+ * `toNpmStagePublishArgs` (see `./lib/npm-publish-args.mjs`) accepts only the
+ * flag shape changesets actually passes and throws on anything it does not
+ * recognise, rather than guessing a translation for an unfamiliar flag.
+ *
+ * `PNPM_SHIM_DIR` names this shim's own directory so it can be dropped from
+ * PATH when looking for the real pnpm (otherwise it would find itself).
+ * Delete this, and the workflow step that installs it, once pnpm's publish
+ * authenticates against npmjs.com.
+ */
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { delimiter } from "node:path";
+import { pathWithout, toNpmStagePublishArgs } from "./lib/npm-publish-args.mjs";
+
+const args = process.argv.slice(2);
+
+let command;
+let commandArgs;
+if (args[0] === "publish") {
+  try {
+    command = "npm";
+    commandArgs = toNpmStagePublishArgs(args.slice(1));
+  } catch (error) {
+    console.error(
+      `pnpm-publish-shim: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exit(1);
+  }
+} else {
+  command = "pnpm";
+  commandArgs = args;
+}
+
+const result = spawnSync(command, commandArgs, {
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    PATH: pathWithout(process.env.PATH, process.env.PNPM_SHIM_DIR, delimiter),
+  },
+});
+
+if (result.error) {
+  console.error(
+    `pnpm-publish-shim: could not run ${command}: ${result.error.message}`,
+  );
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/templates/packs/publishing/pack.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 1,
+  "name": "publishing",
+  "description": "A release pipeline for a project that ships an npm package. Release half: release.yml (changesets version-PR / staged, provenance-attested npm publish via trusted publishing OIDC, including a direct check-publish-version.mjs call right before packing), .changeset/config.json + README.md, the pnpm-to-npm-stage-publish shim, and one build-group gate (check-dts-deps.mjs). Also ships check-license-headers.mjs and a REUSE.toml template as a lint-group gate (secret scanning and Scorecard are the separate `supply-chain` pack). Not adopt-capable: the release flow assumes decisions (registry access, npm trusted-publisher setup, a GitHub App for the version PR) too project-specific to install blind -- see adoptNotes.",
+  "modes": ["fresh"],
+  "budget": {
+    "agents": 0,
+    "skills": 0,
+    "hooks": 0,
+    "workflows": 1,
+    "scripts": 2
+  },
+  "wiring": {
+    "settings": {},
+    "packageScripts": {
+      "changeset": "changeset",
+      "version:packages": "changeset version && pnpm install --lockfile-only"
+    },
+    "verifySteps": [
+      {
+        "id": "dts-deps",
+        "group": "build",
+        "name": "Check .d.ts dependency declarations",
+        "cmd": ["node", "bin/check-dts-deps.mjs"]
+      },
+      {
+        "id": "license-headers",
+        "group": "lint",
+        "name": "Check SPDX license headers",
+        "cmd": ["node", "bin/check-license-headers.mjs"]
+      }
+    ]
+  },
+  "adoptNotes": "REQUIRED right after install, before the first pnpm verify -- two one-time steps, or pnpm verify fails immediately, not from a real regression but from two setup gaps this pack cannot close itself: (1) `pnpm add -D @changesets/cli` -- the wiring contract only extends package.json's scripts, never its dependencies (see templates/packs/README.md), so the wired `changeset`/`version:packages` scripts reference a binary knip's own unlisted-binaries check correctly flags as missing until this is installed; (2) `node bin/check-license-headers.mjs --fix`, then commit the result -- templates/core has never had a license-header gate before this pack, so every one of its own files (hooks, bin/ scripts, CI workflows, the placeholder src/tests, and the workflows of any other installed pack such as `github` or `supply-chain`) is missing the SPDX header this pack's own license-headers gate now requires, the same one-time cost this repo itself paid when it adopted the same gate (see CLAUDE.md's Definition of Done). In a hand-copied install the CLI does not substitute tokens, so replace every literal `__PROJECT_NAME__` in the copied files (REUSE.toml, the SPDX headers in bin/, the workflows) with the project's real name first. Fresh mode only: a release pipeline encodes decisions (whether the package is actually public, which registry, whether a GitHub App backs the version PR) this pack cannot survey or guess at safely, so it is staged like every other pack (at .groundwork/packs/publishing/) but never auto-installed in adopt mode -- if an adopted project wants it, copy .groundwork/packs/publishing/files/ by hand, dropping the `.staged` suffix from every name (or copy templates/packs/publishing/files/ from this repo directly) and work through the one-time setup below. check-publish-version.mjs is deliberately NOT one of this pack's wired verify steps: with changesets, package.json's version on the release branch is always the one just published between releases, so a version-already-published check running on every ordinary push (via pnpm verify / pre-push) would fail every single time until the next version PR lands -- it is instead invoked directly as a step inside release.yml's pack job, the one place \"is this version about to collide with an already-published one\" is actually the right question to ask. The two remaining verify-group gates (dts-deps, license-headers) install anywhere a bin/verify.mjs-shaped gate runner exists; wire them into the project's real one if it differs. Both check-publish-version.mjs and check-dts-deps.mjs no-op (checked: 0, not a failure) on a package.json with `private: true` (the baseline's own default) or (check-dts-deps.mjs only) with no dist/**/*.d.ts yet -- flip `private` to `false` (and set a real `name`) once the package is actually meant to publish. The pack assumes a public package: `.changeset/config.json` ships `access: public`, npm refuses `restricted` for an unscoped name, and the publish shim always passes `--provenance`, which npm ties to a public source repository -- a private scoped package needs `access: restricted` and provenance removed from bin/lib/npm-publish-args.mjs. `@changesets/changelog-github` (and its `repo` option) is a drop-in swap for `.changeset/config.json`'s plain default changelog generator, once this project's GitHub repository is known, for changelog entries that link back to the originating PR/commit -- see `.changeset/README.md`. One-time setup before release.yml's first real run (distinct from the two pnpm-verify prerequisites above), distilled from this repo's own .claude/rules/releases.md: (1) npm cannot configure a trusted publisher for a package that doesn't exist yet -- publish once by hand with a temporary token first; (2) the trusted publisher is bound to the exact workflow filename `release.yml` -- renaming or moving it breaks publishing until reconfigured on npmjs.com; (3) set the trusted publisher's allowed actions to staged-only (`npm stage publish`, npm's own default and recommendation since 2026-09-03) -- a maintainer runs `npm stage approve <id>` (2FA, never automatable) before a version actually installs; (4) create an `npm-publish` GitHub environment (via `gh api`, not committed as JSON) with a required reviewer, restricted to the release branch, so the `publish` job itself pauses before the git tag/Release/stage-publish exist; (5) if branch protection requires status checks on every PR with no bypass actor, the version-PR job needs a GitHub App installation token (`APP_CLIENT_ID`/`APP_PRIVATE_KEY` repo secrets), not the default GITHUB_TOKEN, or those checks never trigger and the PR can never merge -- if this project has no such rule, `github-token: ${{ secrets.GITHUB_TOKEN }}` is enough and the app-token step can be dropped. release.yml pins `.github/release-tools/` (the npm CLI version) but the baseline's dependabot.yml only covers the github-actions ecosystem, so that pin goes stale unless you add an `npm` entry with `directory: \"/.github/release-tools\"` to the project's own .github/dependabot.yml. Security note, as of 2026-10-01: the npm pinned in the shipped `.github/release-tools/package-lock.json` (11.20.0) bundles undici 6.28.0, ip-address 10.5.0 and brace-expansion 5.0.9, which carry open advisories; every npm release found that day (11.20.0, 11.21.0, 12.2.0) bundles the same versions, and overrides cannot change bundled dependencies. Reading the npm tarballs and lockfile, no reach was found from what the shipped workflow runs (`npm ci --ignore-scripts`, `npm stage publish <tarball>` and `npm stage list`; the tarball is packed earlier by pnpm, not npm, and the shipped workflow configures no proxy; if your runner sets one, for example HTTPS_PROXY on a self-hosted runner behind an egress proxy, the ip-address advisories may apply), and the minimatch callers on those commands (Arborist, and tuf-js under sigstore) take their patterns from your own lockfile and from signed registry metadata, but that is analysis, not a run of the code. Re-check on the day of each release and bump the pinned npm as soon as a release bundling undici >= 6.28.1, ip-address >= 10.7.1 and brace-expansion >= 5.0.12 exists. The secret-scanning and Scorecard workflows that used to ship here are now the separate `supply-chain` pack."
+}

package/templates/packs/{harness-extras → quality}/files/bin/check-file-budget.mjs

@@ -19,9 +19,11 @@
  * oversized file is asking its reviewer to accept that debt, not silently
  * evading the gate.
  *
- * `ROOTS` defaults to this baseline's flat `src/`/`tests/` layout. If
- * `/customize` or a later refactor moves to a `packages/*` monorepo shape,
- * update `ROOTS` to list each package's `src`/`tests` pair.
+ * `ROOTS` defaults to this project's flat `src/`/`tests/` layout (not to be
+ * confused with the "baseline" ratchet file above -- this is about where
+ * your source lives, not about recorded debt). If `/customize` or a later
+ * refactor moves to a `packages/*` monorepo shape, update `ROOTS` to list
+ * each package's `src`/`tests` pair.
  *
  * Usage:
  *   node bin/check-file-budget.mjs            # verify (fails on growth/new-over-ceiling)
@@ -338,7 +340,7 @@ if (isEntryPoint()) {
     reporter.fail(
       ref
         ? `Could not scan the tracked roots at ${ref}: ${message}`
-        : `Could not scan ${relative(root, root)}: ${message}`,
+        : `Could not scan the tracked roots: ${message}`,
     );
     reporter.finish();
     process.exit(1);

package/templates/packs/quality/pack.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "name": "quality",
+  "description": "Two language-level review aids for a TypeScript project: a per-file size ratchet gate over src/ and tests/ (check-file-budget.mjs plus its committed baseline, wired as a build-group verify step) and a type-design-analyzer review agent that rates the type design of changed exports on four dimensions. No hooks, no settings, no scripts.",
+  "modes": ["fresh", "adopt"],
+  "budget": {
+    "agents": 1,
+    "skills": 0,
+    "hooks": 0,
+    "workflows": 0,
+    "scripts": 0
+  },
+  "requires": {
+    "paths": ["bin/lib/report.mjs"]
+  },
+  "wiring": {
+    "settings": {},
+    "packageScripts": {},
+    "verifySteps": [
+      {
+        "id": "file-budget",
+        "group": "build",
+        "name": "Check file budget",
+        "cmd": ["node", "bin/check-file-budget.mjs"]
+      }
+    ]
+  },
+  "adoptNotes": "check-file-budget.mjs's ROOTS default assumes a flat src/+tests/ layout and its ceilings are this baseline's defaults -- in an adopted project, re-point ROOTS at the project's real source layout (or drop the gate) before wiring it. check-file-budget.mjs imports ./lib/report.mjs, a baseline file that an adopted project will not have -- copy bin/lib/report.mjs alongside the gate, or treat the gate as not installable. The verify step assumes a bin/verify.mjs-shaped gate runner; if the project has none, install the agent and report the gate as not installable rather than inventing one. The type-design-analyzer agent has no such dependency and installs anywhere a .claude/agents/ directory exists; it is a read-only review spoke (model claude-opus-5 at xhigh effort, more expensive than the baseline's reviewers, which run claude-opus-5-5 at medium effort), and nothing in the baseline's hub-and-spoke instructions dispatches it by name -- ask for it after changing exported types, or add it to the project's own CLAUDE.md review step."
+}