@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.
- package/README.md +20 -5
- package/dist/inventory.d.ts +1 -1
- package/dist/inventory.js +5 -2
- package/dist/report.js +74 -10
- package/dist/survey/survey-harness.d.ts +10 -2
- package/dist/survey/survey-harness.js +90 -4
- package/dist/survey/survey-shape.js +6 -3
- package/dist/survey/survey-toolchain.js +7 -9
- package/dist/survey/types.d.ts +33 -0
- package/dist/toolchain/grade.js +6 -7
- package/dist/toolchain/rules.d.ts +5 -3
- package/dist/toolchain/rules.js +6 -4
- package/package.json +1 -1
- package/plugin/skills/customize/SKILL.md +40 -5
- package/plugin/skills/customize/step-0-reconcile.md +10 -6
- package/plugin/skills/customize/step-3-round-1.md +12 -11
- package/plugin/src/domain-map.ts +3 -3
- package/plugin/src/kind-facet-map.ts +39 -9
- package/plugin/src/pack-map.ts +5 -3
- package/plugin/src/plugin-map.ts +29 -7
- package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
- package/templates/core/.claude/rules/agent-dispatch.md +12 -7
- package/templates/core/.claude/rules/src.md +7 -4
- package/templates/core/.claude/rules/tests.md +2 -2
- package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
- package/templates/core/CLAUDE.md +28 -15
- package/templates/core/README.md +15 -3
- package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
- package/templates/core/bin/lint-commit.mjs +215 -10
- package/templates/packs/README.md +19 -13
- package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +2 -3
- package/templates/packs/github/files/.github/workflows/claude.yml +4 -7
- package/templates/packs/github/pack.json +1 -1
- package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
- package/templates/packs/harness-extras/pack.json +1 -1
- package/templates/packs/publishing/files/.github/workflows/release.yml +22 -36
- package/templates/packs/publishing/files/bin/lib/npm-publish-args.mjs +26 -18
- package/templates/packs/publishing/files/bin/lib/read-tarball-manifest.mjs +114 -0
- package/templates/packs/publishing/files/bin/npm-stage-publish.mjs +214 -0
- package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +22 -18
- package/templates/packs/publishing/files/tools/release/package.json +10 -0
- package/templates/packs/publishing/pack.json +2 -2
- package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
- package/templates/packs/supply-chain/pack.json +2 -2
- package/templates/packs/worktrees/pack.json +1 -1
- 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
|
|
8
|
+
* this rewrites into a staged publish (`npm-stage-publish.mjs`, libnpmpublish) instead.
|
|
9
9
|
*
|
|
10
10
|
* ## Why it exists
|
|
11
11
|
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
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
|
-
*
|
|
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
|
-
* `
|
|
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 {
|
|
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
|
-
|
|
60
|
-
|
|
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-
|
|
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
|
|
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.
|
|
9
|
-
#
|
|
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.
|
|
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.
|
|
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
|
|
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
|
-
}
|