@monte3l/groundwork 1.0.0-rc.5 → 1.0.0-rc.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +20 -5
  2. package/dist/inventory.d.ts +1 -1
  3. package/dist/inventory.js +5 -2
  4. package/dist/report.js +74 -10
  5. package/dist/survey/survey-harness.d.ts +10 -2
  6. package/dist/survey/survey-harness.js +90 -4
  7. package/dist/survey/survey-shape.js +6 -3
  8. package/dist/survey/survey-toolchain.js +7 -9
  9. package/dist/survey/types.d.ts +33 -0
  10. package/dist/toolchain/grade.js +6 -7
  11. package/dist/toolchain/rules.d.ts +5 -3
  12. package/dist/toolchain/rules.js +6 -4
  13. package/package.json +1 -1
  14. package/plugin/skills/customize/SKILL.md +40 -5
  15. package/plugin/skills/customize/step-0-reconcile.md +10 -6
  16. package/plugin/skills/customize/step-3-round-1.md +12 -11
  17. package/plugin/src/domain-map.ts +3 -3
  18. package/plugin/src/kind-facet-map.ts +39 -9
  19. package/plugin/src/pack-map.ts +5 -3
  20. package/plugin/src/plugin-map.ts +29 -7
  21. package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
  22. package/templates/core/.claude/rules/agent-dispatch.md +12 -7
  23. package/templates/core/.claude/rules/src.md +7 -4
  24. package/templates/core/.claude/rules/tests.md +2 -2
  25. package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
  26. package/templates/core/CLAUDE.md +28 -15
  27. package/templates/core/README.md +15 -3
  28. package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
  29. package/templates/core/bin/lint-commit.mjs +215 -10
  30. package/templates/packs/README.md +19 -13
  31. package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +2 -3
  32. package/templates/packs/github/files/.github/workflows/claude.yml +4 -7
  33. package/templates/packs/github/pack.json +1 -1
  34. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
  35. package/templates/packs/harness-extras/pack.json +1 -1
  36. package/templates/packs/publishing/files/.github/workflows/release.yml +22 -36
  37. package/templates/packs/publishing/files/bin/lib/npm-publish-args.mjs +26 -18
  38. package/templates/packs/publishing/files/bin/lib/read-tarball-manifest.mjs +114 -0
  39. package/templates/packs/publishing/files/bin/npm-stage-publish.mjs +214 -0
  40. package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +22 -18
  41. package/templates/packs/publishing/files/tools/release/package.json +10 -0
  42. package/templates/packs/publishing/pack.json +2 -2
  43. package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
  44. package/templates/packs/supply-chain/pack.json +2 -2
  45. package/templates/packs/worktrees/pack.json +1 -1
  46. package/templates/packs/publishing/files/.github/release-tools/package.json +0 -9
@@ -0,0 +1,114 @@
1
+ // SPDX-FileCopyrightText: Copyright the __PROJECT_NAME__ contributors
2
+ // SPDX-License-Identifier: NOASSERTION
3
+
4
+ /**
5
+ * Reads `package/package.json` out of an npm tarball using Node built-ins only,
6
+ * for `npm-stage-publish.mjs`. A tarball reader library (pacote, tar) would drag
7
+ * node-gyp and an HTTP client into the pinned release-tools tree, which is the
8
+ * exact surface this repo moved away from the npm CLI to shrink.
9
+ *
10
+ * Handles what `pnpm pack`/`npm pack` emit: a gzipped ustar archive whose
11
+ * entries live under a top-level directory. It never throws on malformed
12
+ * input other than through the documented `Error`s below.
13
+ */
14
+ import { gunzipSync } from "node:zlib";
15
+
16
+ const BLOCK = 512;
17
+
18
+ /** NUL-terminated ASCII field of a ustar header. */
19
+ function field(buf, start, length) {
20
+ const end = buf.indexOf(0, start);
21
+ const stop = end === -1 || end > start + length ? start + length : end;
22
+ return buf.toString("utf8", start, stop);
23
+ }
24
+
25
+ /**
26
+ * @param {Buffer} tgz
27
+ * @returns {Buffer} the decompressed archive
28
+ */
29
+ function gunzip(tgz) {
30
+ try {
31
+ return gunzipSync(tgz);
32
+ } catch (error) {
33
+ throw new Error(
34
+ `tarball is not valid gzip: ${error instanceof Error ? error.message : String(error)}`,
35
+ { cause: error },
36
+ );
37
+ }
38
+ }
39
+
40
+ /**
41
+ * Walks the archive and returns the body of the first regular file whose
42
+ * path (under its top-level directory) satisfies `wanted`.
43
+ *
44
+ * @param {Buffer} tar
45
+ * @param {(relativeName: string) => boolean} wanted
46
+ * @returns {{ name: string, body: Buffer } | undefined}
47
+ */
48
+ function findEntry(tar, wanted) {
49
+ let offset = 0;
50
+ while (offset + BLOCK <= tar.length) {
51
+ const name = field(tar, offset, 100);
52
+ if (name === "") break; // end-of-archive padding
53
+ const size = parseInt(field(tar, offset + 124, 12).trim(), 8);
54
+ if (!Number.isSafeInteger(size) || size < 0) {
55
+ throw new Error(`corrupt tar header for ${name}: bad size`);
56
+ }
57
+ const prefix = field(tar, offset + 345, 155);
58
+ const type = String.fromCharCode(tar[offset + 156] ?? 0);
59
+ const body = offset + BLOCK;
60
+ const fullName = prefix === "" ? name : `${prefix}/${name}`;
61
+ const match = /^[^/]+\/([^/]+)$/.exec(fullName);
62
+ if (
63
+ (type === "0" || type === "\0") &&
64
+ match?.[1] !== undefined &&
65
+ wanted(match[1])
66
+ ) {
67
+ if (body + size > tar.length) {
68
+ throw new Error(`corrupt tarball: ${match[1]} is truncated`);
69
+ }
70
+ return { name: match[1], body: tar.subarray(body, body + size) };
71
+ }
72
+ offset = body + Math.ceil(size / BLOCK) * BLOCK;
73
+ }
74
+ return undefined;
75
+ }
76
+
77
+ /**
78
+ * @param {Buffer} tgz the gzipped tarball
79
+ * @returns {object} the parsed manifest
80
+ * @throws {Error} when the input is not a gzip, has no package.json, or the
81
+ * manifest is not valid JSON
82
+ */
83
+ export function readTarballManifest(tgz) {
84
+ const entry = findEntry(gunzip(tgz), (n) => n === "package.json");
85
+ if (entry === undefined)
86
+ throw new Error("tarball has no package/package.json");
87
+ try {
88
+ return JSON.parse(entry.body.toString("utf8"));
89
+ } catch (error) {
90
+ throw new Error(
91
+ `package.json in the tarball is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
92
+ { cause: error },
93
+ );
94
+ }
95
+ }
96
+
97
+ /**
98
+ * The README the registry shows for a version. npm's own publish reads it
99
+ * from the tarball and adds it to the version metadata; libnpmpublish does
100
+ * not, so without this the published page has no README.
101
+ *
102
+ * @param {Buffer} tgz the gzipped tarball
103
+ * @returns {{ filename: string, content: string } | undefined} undefined when
104
+ * the tarball ships no README
105
+ */
106
+ export function readTarballReadme(tgz) {
107
+ const tar = gunzip(tgz);
108
+ const entry =
109
+ findEntry(tar, (n) => /^readme\.md$/i.test(n)) ??
110
+ findEntry(tar, (n) => /^readme(\.[^/]+)?$/i.test(n));
111
+ return entry === undefined
112
+ ? undefined
113
+ : { filename: entry.name, content: entry.body.toString("utf8") };
114
+ }
@@ -0,0 +1,214 @@
1
+ #!/usr/bin/env node
2
+ // SPDX-FileCopyrightText: Copyright the __PROJECT_NAME__ contributors
3
+ // SPDX-License-Identifier: NOASSERTION
4
+
5
+ /**
6
+ * Stages a packed tarball on npm through trusted publishing (GitHub OIDC), for
7
+ * `pnpm-publish-shim.mjs`. Replaces `npm stage publish`.
8
+ *
9
+ * ## Why not the npm CLI
10
+ *
11
+ * The npm CLI bundles its own dependencies (undici, ip-address,
12
+ * brace-expansion, ...) inside its tarball, where neither `overrides` nor
13
+ * `npm audit fix` can reach them, so an advisory against one stays open until
14
+ * npm itself re-releases. npm's own publish library, `libnpmpublish`, is an
15
+ * ordinary dependency tree that audit tooling can fix, so the release job
16
+ * uses it instead of the CLI.
17
+ *
18
+ * ## What it does
19
+ *
20
+ * 1. Gets a GitHub OIDC id token for `npm:<registry host>`.
21
+ * 2. Exchanges it at `/-/npm/v1/oidc/token/exchange/package/<name>` for a
22
+ * short-lived npm token scoped to this package (ported from npm's
23
+ * `lib/utils/oidc.js`).
24
+ * 3. Calls `libnpmpublish.publish(..., { stage: true, provenance: true })`.
25
+ *
26
+ * Unlike the npm CLI, whose OIDC step silently falls back to "no auth" on any
27
+ * failure, every failure here exits non-zero with the reason. Tokens are never
28
+ * printed.
29
+ *
30
+ * ## Inputs
31
+ *
32
+ * `RELEASE_TOOLS_DIR` names the directory holding the `npm ci`-installed
33
+ * libnpmpublish and npm-registry-fetch (the release-tools lockfile).
34
+ * `NPM_CONFIG_REGISTRY` overrides the registry (as in npm; the tests point it at a
35
+ * local server; default npmjs.org).
36
+ */
37
+ import process from "node:process";
38
+ import { readFileSync, appendFileSync } from "node:fs";
39
+ import { createRequire } from "node:module";
40
+ import { join } from "node:path";
41
+ import { parsePublishArgs } from "./lib/npm-publish-args.mjs";
42
+ import {
43
+ readTarballManifest,
44
+ readTarballReadme,
45
+ } from "./lib/read-tarball-manifest.mjs";
46
+
47
+ /**
48
+ * @param {string} message
49
+ * @returns {never}
50
+ */
51
+ function fail(message) {
52
+ console.error(`npm-stage-publish: ${message}`);
53
+ process.exit(1);
54
+ }
55
+
56
+ /**
57
+ * @param {Record<string, string | undefined>} env
58
+ * @param {string} registry
59
+ * @returns {Promise<string>} the GitHub OIDC id token
60
+ */
61
+ async function githubIdToken(env, registry) {
62
+ if (env.NPM_ID_TOKEN) return env.NPM_ID_TOKEN;
63
+ const requestUrl = env.ACTIONS_ID_TOKEN_REQUEST_URL;
64
+ const requestToken = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
65
+ if (!requestUrl || !requestToken) {
66
+ fail(
67
+ "no GitHub OIDC token available: the job needs `permissions: id-token: write`",
68
+ );
69
+ }
70
+ let json;
71
+ try {
72
+ const url = new URL(requestUrl);
73
+ url.searchParams.append("audience", `npm:${new URL(registry).hostname}`);
74
+ const response = await fetch(url, {
75
+ headers: {
76
+ Accept: "application/json",
77
+ Authorization: `Bearer ${requestToken}`,
78
+ },
79
+ });
80
+ if (!response.ok) {
81
+ fail(`GitHub refused the OIDC token request (HTTP ${response.status})`);
82
+ }
83
+ json = await response.json();
84
+ } catch (error) {
85
+ fail(
86
+ `GitHub OIDC token request failed: ${error instanceof Error ? error.message : String(error)}`,
87
+ );
88
+ }
89
+ if (typeof json?.value !== "string" || json.value === "") {
90
+ fail("GitHub's OIDC response carried no token");
91
+ }
92
+ return json.value;
93
+ }
94
+
95
+ const args = process.argv.slice(2);
96
+ let parsed;
97
+ try {
98
+ parsed = parsePublishArgs(args);
99
+ } catch (error) {
100
+ fail(error instanceof Error ? error.message : String(error));
101
+ }
102
+
103
+ const toolsDir = process.env.RELEASE_TOOLS_DIR;
104
+ if (!toolsDir) fail("RELEASE_TOOLS_DIR is not set");
105
+ const requireTools = createRequire(join(toolsDir, "package.json"));
106
+ let publish;
107
+ let npmFetch;
108
+ try {
109
+ ({ publish } = requireTools("libnpmpublish"));
110
+ npmFetch = requireTools("npm-registry-fetch");
111
+ } catch (error) {
112
+ fail(
113
+ `cannot load libnpmpublish from ${toolsDir} (run npm ci --ignore-scripts --prefix there first): ${error instanceof Error ? error.message : String(error)}`,
114
+ );
115
+ }
116
+
117
+ const registry =
118
+ process.env.NPM_CONFIG_REGISTRY ?? "https://registry.npmjs.org/";
119
+ const registryUrl = new URL(registry);
120
+ const authKey = `//${registryUrl.host}${registryUrl.pathname}:_authToken`;
121
+
122
+ let manifest;
123
+ let tarball;
124
+ try {
125
+ tarball = readFileSync(parsed.tarball);
126
+ manifest = readTarballManifest(tarball);
127
+ // npm's own publish adds the README to the version metadata; libnpmpublish
128
+ // does not, so do it here or the package page shows none.
129
+ const readme = readTarballReadme(tarball);
130
+ if (readme !== undefined && manifest.readme === undefined) {
131
+ manifest.readme = readme.content;
132
+ manifest.readmeFilename = readme.filename;
133
+ }
134
+ } catch (error) {
135
+ fail(
136
+ `cannot read ${parsed.tarball}: ${error instanceof Error ? error.message : String(error)}`,
137
+ );
138
+ }
139
+ if (
140
+ typeof manifest?.name !== "string" ||
141
+ typeof manifest?.version !== "string"
142
+ ) {
143
+ fail(`${parsed.tarball}: package.json has no name and version`);
144
+ }
145
+
146
+ // npm refuses a prerelease published without an explicit dist-tag, because it
147
+ // would otherwise land on `latest`. Refuse here too, before any token is used.
148
+ if (/^\d+\.\d+\.\d+-/.test(manifest.version) && parsed.tag === undefined) {
149
+ fail(
150
+ `${manifest.name}@${manifest.version} is a prerelease: pass --tag so it does not land on latest`,
151
+ );
152
+ }
153
+
154
+ const idToken = await githubIdToken(process.env, registry);
155
+
156
+ let npmToken;
157
+ try {
158
+ const exchange = await npmFetch.json(
159
+ new URL(
160
+ `/-/npm/v1/oidc/token/exchange/package/${manifest.name.replace(/\//g, "%2f")}`,
161
+ registry,
162
+ ),
163
+ { registry, method: "POST", [authKey]: idToken },
164
+ );
165
+ npmToken = exchange?.token;
166
+ } catch (error) {
167
+ fail(
168
+ `npm refused the OIDC token exchange for ${manifest.name} (check the trusted publisher config): ${error?.body?.message ?? (error?.statusCode ? `HTTP ${error.statusCode}` : undefined) ?? (error instanceof Error ? error.message : String(error))}`,
169
+ );
170
+ }
171
+ if (typeof npmToken !== "string" || npmToken === "") {
172
+ fail("npm's token exchange response carried no token");
173
+ }
174
+
175
+ let result;
176
+ try {
177
+ result = await publish(manifest, tarball, {
178
+ registry,
179
+ [authKey]: npmToken,
180
+ stage: true,
181
+ provenance: true,
182
+ // publishConfig in the manifest is not merged as npm does: changesets
183
+ // passes --access/--tag explicitly and provenance is always on.
184
+ access: parsed.access ?? null,
185
+ defaultTag: parsed.tag ?? "latest",
186
+ ...(parsed.otp === undefined ? {} : { otp: parsed.otp }),
187
+ });
188
+ } catch (error) {
189
+ fail(
190
+ `staging ${manifest.name}@${manifest.version} failed (the registry may still hold a staged version -- run npm stage list before re-running): ${error instanceof Error ? error.message : String(error)}`,
191
+ );
192
+ }
193
+
194
+ const stageId = result?.stageId;
195
+ if (typeof stageId !== "string" || stageId === "") {
196
+ fail(`staging ${manifest.name}@${manifest.version} returned no stage id`);
197
+ }
198
+ const id = `${manifest.name}@${manifest.version}`;
199
+ console.log(`+ ${id} (staged with id ${stageId})`);
200
+ console.log(`approve with: npm stage approve ${stageId}`);
201
+ if (process.env.GITHUB_STEP_SUMMARY) {
202
+ // Best effort: the version is already staged, so a summary write failure
203
+ // must not turn this run red and leave changesets without its tag.
204
+ try {
205
+ appendFileSync(
206
+ process.env.GITHUB_STEP_SUMMARY,
207
+ `### Staged ${id}\n\nApprove with 2FA: \`npm stage approve ${stageId}\`\n`,
208
+ );
209
+ } catch (error) {
210
+ console.error(
211
+ `npm-stage-publish: staged ${id} (${stageId}) but could not write the step summary: ${error instanceof Error ? error.message : String(error)}`,
212
+ );
213
+ }
214
+ }
@@ -5,22 +5,17 @@
5
5
  /**
6
6
  * Put ahead of the real `pnpm` on PATH by the release workflow's `publish`
7
7
  * job. Everything passes straight through to pnpm except `publish`, which
8
- * this rewrites into `npm stage publish` instead.
8
+ * this rewrites into a staged publish (`npm-stage-publish.mjs`, libnpmpublish) instead.
9
9
  *
10
10
  * ## Why it exists
11
11
  *
12
- * Two independent reasons this can't be `pnpm publish`, stacked:
13
- * 1. `changeset publish` in a pnpm-managed project publishes through
14
- * `pnpm publish`, and pnpm 12's native publish does its own OIDC
15
- * exchange, which npmjs.com rejects (`403 OIDC permission denied`) even
16
- * for a correctly configured trusted publisher. The npm CLI's exchange
17
- * works.
18
- * 2. It can't be a direct `npm publish` either: a trusted publisher created
19
- * since 2026-09-03 defaults to `npm stage publish` only, npm's own
20
- * explicit recommendation (see this pack's adoptNotes). A direct
21
- * `npm publish` gets the exact same 403 "OIDC permission denied" as the
22
- * pnpm case, for an unrelated reason: the token exchange succeeds, but
23
- * the registry refuses the specific action.
12
+ * `changeset publish` in a pnpm workspace publishes through `pnpm publish`.
13
+ * This shim reroutes that call to a staged publish through libnpmpublish
14
+ * (not the npm CLI, whose bundled dependencies carry unfixable advisories --
15
+ * see `npm-stage-publish.mjs`), because
16
+ * the trusted publisher only allows staged publishing
17
+ * (npm's default for any trusted publisher created since 2026-09-03 -- see
18
+ * this pack's adoptNotes).
24
19
  *
25
20
  * ## What it translates
26
21
  *
@@ -30,13 +25,13 @@
30
25
  * everything else it does around it -- the publish plan, ordering, git tags,
31
26
  * GitHub Releases -- instead of reimplementing any of that. A consequence
32
27
  * worth knowing: those git tags and Releases are created the moment
33
- * `npm stage publish` succeeds, which is *before* the package is actually
28
+ * the staged publish succeeds, which is *before* the package is actually
34
29
  * live -- staging still needs a maintainer to run `npm stage approve <id>`
35
30
  * (2FA, never automatable).
36
31
  *
37
32
  * ## What it refuses
38
33
  *
39
- * `toNpmStagePublishArgs` (see `./lib/npm-publish-args.mjs`) accepts only the
34
+ * `parsePublishArgs` (see `./lib/npm-publish-args.mjs`) accepts only the
40
35
  * flag shape changesets actually passes and throws on anything it does not
41
36
  * recognise, rather than guessing a translation for an unfamiliar flag.
42
37
  *
@@ -48,7 +43,8 @@
48
43
  import process from "node:process";
49
44
  import { spawnSync } from "node:child_process";
50
45
  import { delimiter } from "node:path";
51
- import { pathWithout, toNpmStagePublishArgs } from "./lib/npm-publish-args.mjs";
46
+ import { fileURLToPath } from "node:url";
47
+ import { pathWithout, parsePublishArgs } from "./lib/npm-publish-args.mjs";
52
48
 
53
49
  const args = process.argv.slice(2);
54
50
 
@@ -56,8 +52,12 @@ let command;
56
52
  let commandArgs;
57
53
  if (args[0] === "publish") {
58
54
  try {
59
- command = "npm";
60
- commandArgs = toNpmStagePublishArgs(args.slice(1));
55
+ parsePublishArgs(args.slice(1)); // refuse an unfamiliar shape here, before spawning
56
+ command = process.execPath;
57
+ commandArgs = [
58
+ fileURLToPath(new URL("./npm-stage-publish.mjs", import.meta.url)),
59
+ ...args.slice(1),
60
+ ];
61
61
  } catch (error) {
62
62
  console.error(
63
63
  `pnpm-publish-shim: ${error instanceof Error ? error.message : String(error)}`,
@@ -83,4 +83,8 @@ if (result.error) {
83
83
  );
84
84
  process.exit(1);
85
85
  }
86
+ if (result.signal) {
87
+ console.error(`pnpm-publish-shim: ${command} was killed by ${result.signal}`);
88
+ process.exit(1);
89
+ }
86
90
  process.exit(result.status ?? 1);
@@ -0,0 +1,10 @@
1
+ {
2
+ "name": "release-tools",
3
+ "version": "0.0.0",
4
+ "private": true,
5
+ "description": "Pins the exact libnpmpublish (npm's own staged-publish library) and npm-registry-fetch versions the release workflow's publish job installs, so the pin is verified by a committed lockfile's integrity hash rather than a bare version string in YAML.",
6
+ "dependencies": {
7
+ "libnpmpublish": "12.0.1",
8
+ "npm-registry-fetch": "20.0.1"
9
+ }
10
+ }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "name": "publishing",
4
- "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.",
4
+ "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-staged-publish shim (libnpmpublish, not the npm CLI), 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.",
5
5
  "modes": ["fresh"],
6
6
  "budget": {
7
7
  "agents": 0,
@@ -37,5 +37,5 @@
37
37
  "node bin/check-license-headers.mjs --fix",
38
38
  "git add -A"
39
39
  ],
40
- "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) `git add -A`, then `node bin/check-license-headers.mjs --fix`, then `git add -A` again and commit the result (the gate only checks git-tracked files, so a fresh project with nothing staged passes it vacuously and fails on every file at its first push) -- 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-08: the npm pinned in the shipped `.github/release-tools/package-lock.json` (12.2.0) bundles undici 6.28.0, ip-address 10.5.0, brace-expansion 5.0.9, postcss-selector-parser 7.1.4 and http-cache-semantics 4.2.0, which carry open advisories; every npm release found (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), the minimatch callers on those commands (Arborist, and tuf-js under sigstore) take their patterns from your own lockfile and from signed registry metadata, postcss-selector-parser is called only by `npm query` and `npm sbom`, and http-cache-semantics sits behind make-fetch-happen's private (`shared: false`) cache, 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, brace-expansion >= 5.0.12 and postcss-selector-parser >= 7.1.6 exists; fixes are open upstream as npm/cli#10088 and #10089. http-cache-semantics has no fixed release (4.3.0 is outside the advisory's range, but upstream closed the report as not planned), so a bump past 4.2.0 only clears its alert. The secret-scanning and Scorecard workflows that used to ship here are now the separate `supply-chain` pack."
40
+ "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) `git add -A`, then `node bin/check-license-headers.mjs --fix`, then `git add -A` again and commit the result (the gate only checks git-tracked files, so a fresh project with nothing staged passes it vacuously and fails on every file at its first push) -- 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 publisher always requests provenance, which npm ties to a public source repository -- a private scoped package needs `access: restricted` and the `provenance: true` option removed from the libnpmpublish call in bin/npm-stage-publish.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 (staged publishing only, 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 `tools/release/` (the exact libnpmpublish and npm-registry-fetch versions the publish job installs; it stages through them, not the npm CLI, because the CLI's bundled dependencies cannot be patched by an override) 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: \"/tools/release\"` to the project's own .github/dependabot.yml. The publish step prints the staged id and writes the `npm stage approve <id>` command to the job summary. The secret-scanning and Scorecard workflows that used to ship here are now the separate `supply-chain` pack."
41
41
  }
@@ -5,8 +5,10 @@ name: Scorecard
5
5
  # signed releases, and similar checks) and can publish a badge from the
6
6
  # result. It runs weekly, on every push to the release branch, and on
7
7
  # manual dispatch -- not on every PR, since supply-chain posture doesn't
8
- # change per-commit the way tests do. Read-only: this workflow only
9
- # inspects the repo and uploads a report, it never writes to it.
8
+ # change per-commit the way tests do. It never writes to the repository's
9
+ # contents, but the analysis job holds security-events: write (to upload
10
+ # SARIF) and id-token: write (to publish results); the workflow-level
11
+ # default is read-all.
10
12
  on:
11
13
  push:
12
14
  branches: [main]
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "name": "supply-chain",
4
- "description": "Secret scanning and an OpenSSF Scorecard run for any project hosted on GitHub, published or not: gitleaks.yml (gitleaks/gitleaks-action on push, pull request, weekly and manual dispatch) with a .gitleaks.toml, and scorecard.yml (ossf/scorecard-action, weekly, results published as code-scanning alerts). Pure file drop: no hooks, no settings, no scripts, no verify step. Read-only workflows, not required checks by default.",
4
+ "description": "Secret scanning and an OpenSSF Scorecard run for any project hosted on GitHub, published or not: gitleaks.yml (gitleaks/gitleaks-action on push, pull request, weekly and manual dispatch) with a .gitleaks.toml, and scorecard.yml (ossf/scorecard-action, weekly, results published as code-scanning alerts). Pure file drop: no hooks, no settings, no scripts, no verify step. gitleaks.yml is read-only; scorecard.yml's analysis job holds security-events: write and id-token: write (the scorecard action's documented minimum). Neither is a required check by default.",
5
5
  "modes": ["fresh", "adopt"],
6
6
  "budget": {
7
7
  "agents": 0,
@@ -15,5 +15,5 @@
15
15
  "packageScripts": {},
16
16
  "verifySteps": []
17
17
  },
18
- "adoptNotes": "An adopted project that already has its own .github/workflows/gitleaks.yml or scorecard.yml surfaces as an ordinary file conflict -- keep the existing one if it already works, since this pack's version would just replace a configured setup with its generic defaults. gitleaks.yml needs a free GITLEAKS_LICENSE repo secret for an organization-owned repository (gitleaks-action's own requirement); scorecard.yml assumes a public repository (`publish_results: true` needs one) -- set it `false` for a private repo. Both are read-only and not required checks by default; add either to branch protection once it has a clean run. The SPDX/REUSE license-header gate is not part of this pack: it lives in the fresh-only `publishing` pack, because it fails an established project's `pnpm verify` until a one-time backfill touches every file. The two workflows ship without an SPDX header on purpose (a header would carry a project-name token that stays literal in an adopt-mode install); a project that also installs `publishing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill."
18
+ "adoptNotes": "An adopted project that already has its own .github/workflows/gitleaks.yml or scorecard.yml surfaces as an ordinary file conflict -- keep the existing one if it already works, since this pack's version would just replace a configured setup with its generic defaults. gitleaks.yml needs a free GITLEAKS_LICENSE repo secret for an organization-owned repository (gitleaks-action's own requirement); scorecard.yml assumes a public repository (`publish_results: true` needs one) -- set it `false` for a private repo. gitleaks.yml is read-only and scorecard.yml holds security-events: write and id-token: write in its analysis job; neither is a required check by default, so add either to branch protection once it has a clean run. The SPDX/REUSE license-header gate is not part of this pack: it lives in the fresh-only `publishing` pack, because it fails an established project's `pnpm verify` until a one-time backfill touches every file. The two workflows ship without an SPDX header on purpose (a header would carry a project-name token that stays literal in an adopt-mode install); a project that also installs `publishing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill."
19
19
  }
@@ -60,5 +60,5 @@
60
60
  "packageScripts": {},
61
61
  "verifySteps": []
62
62
  },
63
- "adoptNotes": "ensure-worktree-deps.mjs runs `pnpm install --frozen-lockfile --prefer-offline` automatically the first time a session starts inside a freshly created worktree with no node_modules yet -- this runs every dependency's lifecycle scripts the same way any `pnpm install` does, limited only by whatever `allowBuilds`/`onlyBuiltDependencies` policy the project's own pnpm config already sets (see typescript-guidance's pnpm supply-chain coverage if none is set). If the project sets `worktree.symlinkDirectories: [\"node_modules\"]` in .claude/settings.json, the hook detects the symlink and skips -- installing there would mutate the main checkout's own node_modules through the symlink. guard-worktree-only.mjs blocks every src/tests write outside a linked worktree under .claude/worktrees/, on any branch, for any caller (hub or writer spoke) -- this is stricter than guard-branch-isolation.mjs (which only blocks on main) and guard-hub-src-writes.mjs (which only blocks the hub); confirm the team actually wants every change routed through a worktree before installing this pack, since it changes the day-to-day workflow, not just adds a nicety. `.claude/worktrees/` should already be gitignored (the baseline's own .gitignore covers this); if adopting into a project with a hand-rolled .gitignore that doesn't, add it before installing. repair-core-bare.mjs resets `core.bare = true` to `false` in a non-bare repo's shared .git/config at session start and after EnterWorktree/ExitWorktree/Agent calls: Claude Code's worktree tools are documented to leave it set (anthropics/claude-code#58345, #69802), which breaks `git status` in the main checkout. It only acts on a provably non-bare repository (its common git dir is named .git and contains an index), never on a genuine bare repo -- including a bare clone stored in a directory called .git -- and reports a failed repair on stdout rather than silently."
63
+ "adoptNotes": "ensure-worktree-deps.mjs runs `pnpm install --frozen-lockfile --prefer-offline` automatically the first time a session starts inside a freshly created worktree with no node_modules yet -- this runs every dependency's lifecycle scripts the same way any `pnpm install` does, limited only by whatever `allowBuilds`/`onlyBuiltDependencies` policy the project's own pnpm config already sets (see typescript-guidance's pnpm supply-chain coverage if none is set). If node_modules in the worktree is a symlink (the usual result of `worktree.symlinkDirectories: [\"node_modules\"]` in .claude/settings.json, which this hook never reads), the hook detects the symlink and skips -- installing there would mutate the main checkout's own node_modules through the symlink. guard-worktree-only.mjs blocks every src/tests write outside a linked worktree under .claude/worktrees/, on any branch, for any caller (hub or writer spoke) -- this is stricter than guard-branch-isolation.mjs (which only blocks on main) and guard-hub-src-writes.mjs (which blocks the hub and any non-writer subagent); confirm the team actually wants every change routed through a worktree before installing this pack, since it changes the day-to-day workflow, not just adds a nicety. `.claude/worktrees/` should already be gitignored (the baseline's own .gitignore covers this); if adopting into a project with a hand-rolled .gitignore that doesn't, add it before installing. repair-core-bare.mjs resets `core.bare = true` to `false` in a non-bare repo's shared .git/config at session start and after EnterWorktree/ExitWorktree/Agent calls: Claude Code's worktree tools have been reported to leave it set (anthropics/claude-code#58345, #69802: user bug reports, both since closed as not planned, so whether it still reproduces is unconfirmed), which breaks `git status` in the main checkout. It only acts on a provably non-bare repository (its common git dir is named .git and contains an index), never on a genuine bare repo -- including a bare clone stored in a directory called .git -- and reports a failed repair on stdout rather than silently."
64
64
  }
@@ -1,9 +0,0 @@
1
- {
2
- "name": "release-tools",
3
- "version": "0.0.0",
4
- "private": true,
5
- "description": "Pins the exact npm version the release workflow's publish job installs, so the pin is verified by a committed lockfile's integrity hash rather than a bare version string in YAML.",
6
- "dependencies": {
7
- "npm": "12.2.0"
8
- }
9
- }