@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
|
@@ -9,16 +9,35 @@
|
|
|
9
9
|
*
|
|
10
10
|
* Usage: `lint-commit.mjs --edit <path-to-commit-msg-file>` (lefthook's
|
|
11
11
|
* `commit-msg` hook contract) or `lint-commit.mjs <message>` directly.
|
|
12
|
+
* An empty message (direct mode with no arguments) is accepted by commitlint
|
|
13
|
+
* itself, so it passes here unless an enforced `trailer-exists` rule rejects
|
|
14
|
+
* it. git runs the `commit-msg` hook before it rejects an empty message, and
|
|
15
|
+
* `--allow-empty-message` lets one through, so `--edit` mode can see one too.
|
|
16
|
+
*
|
|
17
|
+
* When the config enables `trailer-exists` as an error (severity 2), the
|
|
18
|
+
* trailer, with a non-empty value, is also required on every message
|
|
19
|
+
* commitlint's default ignores skip (merge, revert, `fixup!`, `squash!`,
|
|
20
|
+
* `amend!`, semver release subjects): a local merge or revert needs
|
|
21
|
+
* `git merge --signoff` / `git revert --signoff` too. This wrapper
|
|
22
|
+
* deliberately does not honour commitlint's own `ignores`/`defaultIgnores`
|
|
23
|
+
* config keys: the first lint uses commitlint's built-in default ignores,
|
|
24
|
+
* and the trailer re-check always runs with them off.
|
|
25
|
+
*
|
|
26
|
+
* Every failure -- an unreadable or missing `--edit` file, a missing or
|
|
27
|
+
* unparseable `commitlint.config.js` or one that defines no rules, a
|
|
28
|
+
* forbidden trailer, a rule violation,
|
|
29
|
+
* a thrown error from commitlint, or a missing `git` (which `trailer-exists`
|
|
30
|
+
* shells out to) -- prints `✗`-prefixed line(s) to stderr (one per problem)
|
|
31
|
+
* and exits 1, never a stack trace.
|
|
12
32
|
*/
|
|
13
33
|
import process from "node:process";
|
|
34
|
+
import { spawnSync } from "node:child_process";
|
|
14
35
|
import { readFileSync } from "node:fs";
|
|
15
36
|
import load from "@commitlint/load";
|
|
16
37
|
import lint from "@commitlint/lint";
|
|
17
38
|
|
|
18
39
|
const args = process.argv.slice(2);
|
|
19
40
|
const editIndex = args.indexOf("--edit");
|
|
20
|
-
const message =
|
|
21
|
-
editIndex === -1 ? args.join(" ") : readFileSync(args[editIndex + 1], "utf8");
|
|
22
41
|
|
|
23
42
|
const FORBIDDEN_TRAILER = /^Claude-(?!Session:)[A-Za-z-]*:/m;
|
|
24
43
|
|
|
@@ -26,18 +45,166 @@ function validateForbiddenTrailers(text) {
|
|
|
26
45
|
return !FORBIDDEN_TRAILER.test(text) && !/^Claude-Session:/m.test(text);
|
|
27
46
|
}
|
|
28
47
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
);
|
|
48
|
+
/**
|
|
49
|
+
* Prints one `✗` line to stderr and exits 1.
|
|
50
|
+
*/
|
|
51
|
+
function fail(text) {
|
|
52
|
+
console.error(`✗ ${text}`);
|
|
53
|
+
process.exit(1);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* The first non-empty line of an error's message, so one failure prints as
|
|
58
|
+
* one `✗` line even when commitlint throws a multi-line message.
|
|
59
|
+
*/
|
|
60
|
+
function reason(error) {
|
|
61
|
+
const text = error instanceof Error ? error.message : String(error);
|
|
62
|
+
return (
|
|
63
|
+
text
|
|
64
|
+
.split(/\r?\n/)
|
|
65
|
+
.map((line) => line.trim())
|
|
66
|
+
.find((line) => line !== "") ?? text
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Whether a thrown error is a failure to run `git` (which commitlint's
|
|
72
|
+
* `trailer-exists` shells out to), as opposed to a config or rule error.
|
|
73
|
+
* commitlint does not check its spawn result, so a missing `git` surfaces as
|
|
74
|
+
* an unrelated `TypeError`; probing `git --version` settles it directly.
|
|
75
|
+
*/
|
|
76
|
+
function isGitFailure(error) {
|
|
77
|
+
const code =
|
|
78
|
+
typeof error === "object" && error !== null ? error.code : undefined;
|
|
79
|
+
if (code === "ENOENT") return true;
|
|
80
|
+
if (/\bgit\b/.test(error instanceof Error ? error.message : String(error))) {
|
|
81
|
+
return true;
|
|
82
|
+
}
|
|
83
|
+
const probe = spawnSync("git", ["--version"], { stdio: "ignore" });
|
|
84
|
+
return probe.error !== undefined || probe.status !== 0;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* The failure text for an error thrown by commitlint's `lint`: the git hint
|
|
89
|
+
* only when `git` itself could not run, else the plain reason.
|
|
90
|
+
*/
|
|
91
|
+
function lintFailureText(error, gitContext) {
|
|
92
|
+
return isGitFailure(error)
|
|
93
|
+
? `${gitContext}: ${reason(error)}`
|
|
94
|
+
: `could not lint the commit message: ${reason(error)}`;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* The commit message: the `--edit` file's content, else the joined args.
|
|
99
|
+
* A missing path or an unreadable file is reported through `fail`.
|
|
100
|
+
*/
|
|
101
|
+
function readMessage() {
|
|
102
|
+
if (editIndex === -1) return args.join(" ");
|
|
103
|
+
const path = args[editIndex + 1];
|
|
104
|
+
// fail() exits the process; it never returns.
|
|
105
|
+
if (path === undefined) fail("--edit needs a path");
|
|
106
|
+
try {
|
|
107
|
+
return readFileSync(path, "utf8");
|
|
108
|
+
} catch (error) {
|
|
109
|
+
fail(`could not read the commit message file ${path}: ${reason(error)}`);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
const message = readMessage();
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The loaded config's `trailer-exists` entry when it is an enforced
|
|
117
|
+
* requirement (severity 2, not `never`), else `undefined`. Severity 1 is a
|
|
118
|
+
* commitlint warning and never blocks a commit.
|
|
119
|
+
*/
|
|
120
|
+
function enforcedTrailerRule(rules) {
|
|
121
|
+
const entry = rules?.["trailer-exists"];
|
|
122
|
+
if (!Array.isArray(entry)) return undefined;
|
|
123
|
+
const [severity, applicable] = entry;
|
|
124
|
+
return severity === 2 && applicable !== "never" ? entry : undefined;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* The configured trailer name with any trailing `:` stripped, so
|
|
129
|
+
* `Signed-off-by` and `Signed-off-by:` mean the same trailer. Empty when the
|
|
130
|
+
* rule names no trailer.
|
|
131
|
+
*/
|
|
132
|
+
function trailerKey(value) {
|
|
133
|
+
return String(value ?? "")
|
|
134
|
+
.trim()
|
|
135
|
+
.replace(/:$/, "")
|
|
136
|
+
.trim();
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Whether the message's trailer block (as `git interpret-trailers --parse`
|
|
141
|
+
* reads it, the same parse commitlint's `trailer-exists` uses) holds a
|
|
142
|
+
* `key:` trailer with a non-empty value. commitlint only checks the prefix,
|
|
143
|
+
* so an empty `Signed-off-by:` would otherwise pass. Throws when `git` cannot
|
|
144
|
+
* be run or exits non-zero; the caller reports that and exits 1.
|
|
145
|
+
*/
|
|
146
|
+
function hasNonEmptyTrailer(text, key) {
|
|
147
|
+
const parsed = spawnSync("git", ["interpret-trailers", "--parse"], {
|
|
148
|
+
input: text,
|
|
149
|
+
encoding: "utf8",
|
|
150
|
+
});
|
|
151
|
+
if (parsed.error !== undefined) throw parsed.error;
|
|
152
|
+
if (parsed.status !== 0) {
|
|
153
|
+
throw new Error(
|
|
154
|
+
parsed.stderr.trim() || `exited with status ${String(parsed.status)}`,
|
|
155
|
+
);
|
|
156
|
+
}
|
|
157
|
+
const prefix = `${key}:`;
|
|
158
|
+
return parsed.stdout
|
|
159
|
+
.split(/\r?\n/)
|
|
160
|
+
.some(
|
|
161
|
+
(line) =>
|
|
162
|
+
line.startsWith(prefix) && line.slice(prefix.length).trim() !== "",
|
|
163
|
+
);
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
const IGNORED_KINDS =
|
|
167
|
+
"merge, revert, fixup!, squash!, amend!, semver release subjects";
|
|
168
|
+
|
|
169
|
+
function missingTrailerText(key, qualifier) {
|
|
170
|
+
const name = key === "" ? "a trailer" : `a ${qualifier}\`${key}:\` trailer`;
|
|
171
|
+
const hint = /^signed-off-by$/i.test(key) ? ": use `-s`/`--signoff`" : "";
|
|
172
|
+
return `message must have ${name}, including every message commitlint's default ignores skip (${IGNORED_KINDS})${hint}`;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
let config;
|
|
176
|
+
try {
|
|
177
|
+
config = await load({}, { file: "commitlint.config.js" });
|
|
178
|
+
} catch (error) {
|
|
179
|
+
fail(`could not load commitlint.config.js: ${reason(error)}`);
|
|
180
|
+
}
|
|
181
|
+
// @commitlint/cli rejects an empty rule set the same way: a config whose
|
|
182
|
+
// `extends` resolved to nothing would otherwise pass every message.
|
|
183
|
+
if (Object.keys(config.rules ?? {}).length === 0) {
|
|
184
|
+
fail(
|
|
185
|
+
"commitlint.config.js loaded but defines no rules (check its `extends`)",
|
|
186
|
+
);
|
|
187
|
+
}
|
|
188
|
+
const parserOptions = config.parserPreset
|
|
189
|
+
? { parserOpts: config.parserPreset.parserOpts }
|
|
190
|
+
: {};
|
|
191
|
+
|
|
192
|
+
let result;
|
|
193
|
+
try {
|
|
194
|
+
result = await lint(message, config.rules, parserOptions);
|
|
195
|
+
} catch (error) {
|
|
196
|
+
fail(
|
|
197
|
+
lintFailureText(
|
|
198
|
+
error,
|
|
199
|
+
"could not lint the commit message (commitlint's trailer-exists runs git interpret-trailers; is git on PATH?)",
|
|
200
|
+
),
|
|
201
|
+
);
|
|
202
|
+
}
|
|
35
203
|
|
|
36
204
|
if (!validateForbiddenTrailers(message)) {
|
|
37
|
-
|
|
205
|
+
fail(
|
|
38
206
|
"commit message carries a forbidden Claude-* trailer (only Co-Authored-By: is allowed)",
|
|
39
207
|
);
|
|
40
|
-
process.exit(1);
|
|
41
208
|
}
|
|
42
209
|
|
|
43
210
|
if (!result.valid) {
|
|
@@ -47,4 +214,42 @@ if (!result.valid) {
|
|
|
47
214
|
process.exit(1);
|
|
48
215
|
}
|
|
49
216
|
|
|
217
|
+
// commitlint's default ignores skip merge/revert/fixup!/squash!/amend! and
|
|
218
|
+
// semver release messages entirely, trailer-exists included. Re-run just that
|
|
219
|
+
// rule with the ignores off so an enforced trailer is required on every
|
|
220
|
+
// message. Only reached when the first lint passed, so a failure is never
|
|
221
|
+
// reported twice.
|
|
222
|
+
const trailerRule = enforcedTrailerRule(config.rules);
|
|
223
|
+
if (trailerRule !== undefined) {
|
|
224
|
+
const key = trailerKey(trailerRule[2]);
|
|
225
|
+
let trailerResult;
|
|
226
|
+
try {
|
|
227
|
+
trailerResult = await lint(
|
|
228
|
+
message,
|
|
229
|
+
{ "trailer-exists": trailerRule },
|
|
230
|
+
{ defaultIgnores: false, ...parserOptions },
|
|
231
|
+
);
|
|
232
|
+
} catch (error) {
|
|
233
|
+
fail(
|
|
234
|
+
lintFailureText(
|
|
235
|
+
error,
|
|
236
|
+
"could not read commit trailers (git interpret-trailers failed)",
|
|
237
|
+
),
|
|
238
|
+
);
|
|
239
|
+
}
|
|
240
|
+
if (!trailerResult.valid) fail(missingTrailerText(key, ""));
|
|
241
|
+
// An empty configured value leaves the decision to commitlint's own rule.
|
|
242
|
+
if (key !== "") {
|
|
243
|
+
let present;
|
|
244
|
+
try {
|
|
245
|
+
present = hasNonEmptyTrailer(message, key);
|
|
246
|
+
} catch (error) {
|
|
247
|
+
fail(
|
|
248
|
+
`could not read commit trailers (git interpret-trailers failed): ${reason(error)}`,
|
|
249
|
+
);
|
|
250
|
+
}
|
|
251
|
+
if (!present) fail(missingTrailerText(key, "non-empty "));
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
|
|
50
255
|
console.log("✓ commit message is a valid Conventional Commit");
|
|
@@ -11,7 +11,7 @@ kinds and shouldn't tax every bootstrap by default.
|
|
|
11
11
|
|
|
12
12
|
```
|
|
13
13
|
templates/packs/<name>/
|
|
14
|
-
├── pack.json # manifest:
|
|
14
|
+
├── pack.json # manifest: see "pack.json fields" below
|
|
15
15
|
└── files/ # the pack's own file tree, mirroring the project root
|
|
16
16
|
# exactly as templates/core/ does -- emitted the same way
|
|
17
17
|
```
|
|
@@ -45,15 +45,19 @@ already enumerate groups rather than individual steps.
|
|
|
45
45
|
`pack.json` fields:
|
|
46
46
|
|
|
47
47
|
- `schemaVersion` — currently `1`.
|
|
48
|
-
- `modes` — `["fresh"]` and/or `["fresh", "adopt"]`.
|
|
49
|
-
an artifact has no dependency on the baseline's exact
|
|
50
|
-
agent, most hooks), so it
|
|
51
|
-
project
|
|
52
|
-
|
|
53
|
-
|
|
48
|
+
- `modes` — `["fresh"]` and/or `["fresh", "adopt"]`. By convention,
|
|
49
|
+
"adopt-capable" means an artifact has no dependency on the baseline's exact
|
|
50
|
+
file layout (an agent, most hooks), so it is safe to install into an
|
|
51
|
+
existing project. Nothing enforces this: adopt mode stages every pack
|
|
52
|
+
whatever its `modes`, and fresh mode refuses a pack that does not list
|
|
53
|
+
`fresh`. A pack whose artifacts
|
|
54
|
+
assume a layout can still list `adopt` (`quality` does: its gate assumes a
|
|
55
|
+
flat `src/` and `tests/`); it must then say what to adjust in `adoptNotes`,
|
|
56
|
+
which `/customize` surfaces before installing.
|
|
54
57
|
- `budget` — the pack's cap deltas (`agents`/`skills`/`hooks`/`workflows`/
|
|
55
|
-
`scripts`), checked
|
|
56
|
-
test
|
|
58
|
+
`scripts`), checked by `caps.test.ts` against what the pack's own `files/` tree
|
|
59
|
+
contains. The test does not compare it to `templates/core`'s counts or to
|
|
60
|
+
the sum of any other packs.
|
|
57
61
|
- `requires.paths` — baseline files a pack artifact imports (e.g.
|
|
58
62
|
`bin/lib/agent-roster.mjs`). Checked at install time in fresh mode; a
|
|
59
63
|
missing requirement is a hard install error, not a silent partial install.
|
|
@@ -63,8 +67,10 @@ already enumerate groups rather than individual steps.
|
|
|
63
67
|
- `wiring.settingsTopLevel` — top-level `.claude/settings.json` keys that
|
|
64
68
|
aren't hook registrations (`statusLine`, `subagentStatusLine`, …), planted
|
|
65
69
|
whole. A key the project already defines with a different value is a hard
|
|
66
|
-
install error, never an overwrite; `hooks` is refused
|
|
67
|
-
|
|
70
|
+
install error, never an overwrite; a `hooks` key is refused when the fragment is
|
|
71
|
+
merged (`mergeSettingsTopLevel` in `merge-json.ts`; `loadPack` does not
|
|
72
|
+
check it), since hooks belong in `wiring.settings`. In adopt mode
|
|
73
|
+
`/customize` performs the merge by hand. Optional.
|
|
68
74
|
- `wiring.packageScripts` — `package.json` script additions. Most packs need
|
|
69
75
|
none: a gate registers directly as `["node", "bin/check-x.mjs"]` in
|
|
70
76
|
`wiring.verifySteps`, not as a `pnpm` script.
|
|
@@ -102,6 +108,6 @@ already enumerate groups rather than individual steps.
|
|
|
102
108
|
| `harness-extras` | Claude Code session ergonomics: the compaction-handoff hook pair, a read-only Bash guard, and a five-row status line (session, model, context, quota, work) plus a per-subagent row renderer. The only pack that sets top-level settings keys (`statusLine`, `subagentStatusLine`). |
|
|
103
109
|
| `quality` | Two language-level review aids: a per-file size ratchet gate (`check-file-budget.mjs`, a `build`-group verify step) and a read-only `type-design-analyzer` agent. No hooks, no settings. Adopt-capable and recommended for every project kind. |
|
|
104
110
|
| `github` | GitHub-hosted collaboration: Anthropic's official Claude Code GitHub Action wired for `@claude` mention-mode, a second Action that posts an automated Claude review comment on every PR, and three `gh`-CLI skills — `reviewing-dependabot-prs`, `triaging-scan-alerts`, `watching-pr-checks`. No hooks, no gate. The two workflows need an auth secret this pack cannot create; see its `adoptNotes`. |
|
|
105
|
-
| `publishing` | A release pipeline: `release.yml` (changesets version-PR / staged, provenance-attested npm publish via trusted publishing), `check-publish-version.mjs`, `check-dts-deps.mjs`, `check-license-headers.mjs` and a `REUSE.toml` template. Fresh mode only
|
|
106
|
-
| `supply-chain` | Secret scanning (`gitleaks.yml` with a `.gitleaks.toml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any project on GitHub, published or not. A pure file drop of two read-only
|
|
111
|
+
| `publishing` | A release pipeline: `release.yml` (changesets version-PR / staged, provenance-attested npm publish via trusted publishing), `check-publish-version.mjs`, `check-dts-deps.mjs`, `check-license-headers.mjs` and a `REUSE.toml` template. Fresh mode only; see "The wiring contract" above and its `adoptNotes`. |
|
|
112
|
+
| `supply-chain` | Secret scanning (`gitleaks.yml` with a `.gitleaks.toml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any project on GitHub, published or not. A pure file drop of two workflows (read-only apart from the Scorecard job's `security-events` and `id-token` write): no hooks, no settings, no scripts, no gate. Adopt-capable and recommended for every project kind. |
|
|
107
113
|
| `worktrees` | Enforces that all src/tests development happens inside an isolated git worktree, on any branch, for any caller: a `working-in-worktrees` skill (start/status/sync/finish/fan-out), a `SessionStart` hook that installs dependencies into a freshly created worktree, a `PreToolUse` guard stricter than the baseline's own `guard-branch-isolation.mjs`/`guard-hub-src-writes.mjs`, a `repair-core-bare.mjs` hook (`SessionStart`, and `PostToolUse` after `EnterWorktree`/`ExitWorktree`/`Agent`) that resets the `core.bare = true` Claude Code's worktree tools are reported to leave in a normal repo's shared config, and a `.worktreeinclude` copying `.env`/`.env.local`/`.env.*.local` into every worktree Claude Code creates. Changes the day-to-day workflow, not just a nicety — see its `adoptNotes`. |
|
|
@@ -46,9 +46,8 @@ name: Claude PR Review
|
|
|
46
46
|
# bot-authored and fork PRs explicitly below, rather than relying on
|
|
47
47
|
# anthropics/claude-code-action's own internal bot/permission checks
|
|
48
48
|
# (docs/security.md) -- that way a Dependabot or fork PR never starts a run
|
|
49
|
-
# that would just fail on missing secrets.
|
|
50
|
-
#
|
|
51
|
-
# by hand.
|
|
49
|
+
# that would just fail on missing secrets. This workflow needs one of the
|
|
50
|
+
# auth methods described in claude.yml's comments, set up by hand once.
|
|
52
51
|
on:
|
|
53
52
|
pull_request:
|
|
54
53
|
types: [opened, synchronize, ready_for_review, reopened]
|
|
@@ -12,8 +12,7 @@ name: Claude Code
|
|
|
12
12
|
# https://github.com/anthropics/claude-code-action/blob/main/examples/pr-review-comprehensive.yml
|
|
13
13
|
#
|
|
14
14
|
# This workflow needs one of the three auth methods below (Option 1 is
|
|
15
|
-
# active by default)
|
|
16
|
-
# @claude mention (an auth error, not a crash or a silent no-op).
|
|
15
|
+
# active by default).
|
|
17
16
|
on:
|
|
18
17
|
issue_comment:
|
|
19
18
|
types: [created]
|
|
@@ -33,11 +32,9 @@ jobs:
|
|
|
33
32
|
# `@claude` text match alone would let an outside commenter trigger a job
|
|
34
33
|
# holding `contents: write` and your auth secret. Each branch below also
|
|
35
34
|
# requires the `author_association` of the comment's, review's or
|
|
36
|
-
# issue's author to be OWNER, MEMBER or COLLABORATOR.
|
|
37
|
-
#
|
|
38
|
-
#
|
|
39
|
-
# on whoever assigned it, so assigning an outsider's issue does not start
|
|
40
|
-
# a run.
|
|
35
|
+
# issue's author to be OWNER, MEMBER or COLLABORATOR. On `issues` the
|
|
36
|
+
# check is on the issue's author, not on whoever assigned it, so
|
|
37
|
+
# assigning an outsider's issue does not start a run.
|
|
41
38
|
if: |
|
|
42
39
|
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)) ||
|
|
43
40
|
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)) ||
|
|
@@ -15,5 +15,5 @@
|
|
|
15
15
|
"packageScripts": {},
|
|
16
16
|
"verifySteps": []
|
|
17
17
|
},
|
|
18
|
-
"adoptNotes": "claude.yml only reacts to @claude mentions from a repository owner, member or collaborator (author_association), so an outside commenter on a public repository cannot start a job that holds contents: write and your auth secret
|
|
18
|
+
"adoptNotes": "claude.yml only reacts to @claude mentions from a repository owner, member or collaborator (author_association), so an outside commenter on a public repository cannot start a job that holds contents: write and your auth secret. It also commits through the GitHub API (use_commit_signing) so a signed-commits ruleset accepts its work. Both workflows need one thing this pack cannot verify or install: an ANTHROPIC_API_KEY repository secret (the active default), or a CLAUDE_CODE_OAUTH_TOKEN from a Claude subscription, or a Workload Identity Federation setup in the Anthropic Console -- see the comments in .github/workflows/claude.yml for all three. An adopted project that already has its own .github/workflows/claude.yml or claude-pr-review.yml surfaces as an ordinary file conflict -- keep the existing one if it's already configured for that project's own auth choice, since this pack's version would just overwrite a working setup with its own generic defaults. triaging-scan-alerts reads code-scanning alerts, and nothing in the baseline or this pack produces them: turn on GitHub's CodeQL default setup for the repository (Settings > Code security), or install the `supply-chain` pack, whose scorecard.yml uploads SARIF, otherwise the skill's first call returns \"code scanning is not enabled\" and reports nothing. The other two skills have no such dependency: they install anywhere a .claude/ directory exists and need only `gh` CLI auth (already required by every other gh-CLI-based skill this baseline ships). watching-pr-checks' handoff to /triaging-ci degrades gracefully if the project doesn't have that skill installed -- it still reports the real failure, just without the handoff."
|
|
19
19
|
}
|
|
@@ -21,11 +21,9 @@
|
|
|
21
21
|
*
|
|
22
22
|
* Scope: only tool calls made from inside one of those read-only subagents
|
|
23
23
|
* are checked -- identified via the hook payload's `agent_type` field
|
|
24
|
-
* (
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
* read-only restriction on a `--agent <read-only agent>` main session is
|
|
28
|
-
* fail-safe -- it only refuses more -- so no `agent_id` check is needed here.
|
|
24
|
+
* (a call with no `agent_type` is not restricted). Applying the read-only
|
|
25
|
+
* restriction whenever `agent_type` names a read-only agent is fail-safe --
|
|
26
|
+
* it only refuses more -- so no `agent_id` check is needed here.
|
|
29
27
|
*
|
|
30
28
|
* Design tradeoff, matching every sibling guard hook's fail-open
|
|
31
29
|
* philosophy: this is a DENYLIST of known-mutating patterns, not a strict
|
|
@@ -66,5 +66,5 @@
|
|
|
66
66
|
"packageScripts": {},
|
|
67
67
|
"verifySteps": []
|
|
68
68
|
},
|
|
69
|
-
"adoptNotes": "The statusline and compaction hooks install anywhere a .claude/ directory exists, but guard-readonly-bash.mjs imports ../../bin/lib/agent-roster.mjs (the baseline's list of writer spokes) -- copy that file alongside it in an adopted project, or skip that one hook. The PreCompact hook writes tmp/compact-handoff-<session_id>.json under the git worktree the session runs in (from the hook payload's cwd, since CLAUDE_PROJECT_DIR does not follow a session into a linked worktree) -- fresh mode's baseline .gitignore already lists tmp/ unconditionally, but an adopted project's own .gitignore was never touched by adopt mode, so add tmp/ there too before this pack's hooks run, or the handoff artifact can end up committed. The statusline scripts read only the stdin payload, .git/HEAD (via node:fs, never a git subprocess) and process.availableMemory()/os.totalmem(), so they install anywhere a .claude/ directory exists -- no dependency on the baseline's file layout. The one real adopt risk is the two top-level settings keys: a project that already defines statusLine or subagentStatusLine collides, and its existing value must be shown and decided on, never overwritten -- if either is already set, skip that key and the three statusline scripts, and install the rest of this pack (the hooks) normally rather than failing the whole install. A .claude/settings.local.json or the user's own ~/.claude/settings.json
|
|
69
|
+
"adoptNotes": "The statusline and compaction hooks install anywhere a .claude/ directory exists, but guard-readonly-bash.mjs imports ../../bin/lib/agent-roster.mjs (the baseline's list of writer spokes) -- copy that file alongside it in an adopted project, or skip that one hook. The PreCompact hook writes tmp/compact-handoff-<session_id>.json under the git worktree the session runs in (from the hook payload's cwd, since CLAUDE_PROJECT_DIR does not follow a session into a linked worktree) -- fresh mode's baseline .gitignore already lists tmp/ unconditionally, but an adopted project's own .gitignore was never touched by adopt mode, so add tmp/ there too before this pack's hooks run, or the handoff artifact can end up committed. The statusline scripts read only the stdin payload, .git/HEAD (via node:fs, never a git subprocess) and process.availableMemory()/os.totalmem(), so they install anywhere a .claude/ directory exists -- no dependency on the baseline's file layout. The one real adopt risk is the two top-level settings keys: a project that already defines statusLine or subagentStatusLine collides, and its existing value must be shown and decided on, never overwritten -- if either is already set, skip that key and the three statusline scripts, and install the rest of this pack (the hooks) normally rather than failing the whole install. A statusLine in .claude/settings.local.json (or one passed with --settings) also shadows the project one; the user's own ~/.claude/settings.json ranks lower and does not -- check those before concluding the pack is wired. rate_limits.spend_limit and prompt_cache need Claude Code v2.1.251+, and the per-subagent model/contextWindowSize/effort fields need v2.1.205+/v2.1.214+, and the agentType label a row falls back to when a subagent has no name needs v2.1.293+; each renders only when present, so an older Claude Code degrades to fewer segments rather than breaking. The scripts behave the same on macOS and Linux; the memory segment uses process.availableMemory() (Node 22+), and on macOS with an older Node it is hidden rather than shown from os.freemem(), which undercounts there. Below roughly 40 columns the layout drops segments by priority rather than wrapping. The size-ratchet gate and the type-design-analyzer agent that used to ship here are now the separate `quality` pack."
|
|
70
70
|
}
|
|
@@ -29,7 +29,7 @@ name: Release
|
|
|
29
29
|
# pnpm shim below, with `--ignore-scripts`. `pack` holds nothing beyond
|
|
30
30
|
# `contents: read`.
|
|
31
31
|
#
|
|
32
|
-
# "Staged" publish (vs. a "direct" one) means
|
|
32
|
+
# "Staged" publish (vs. a "direct" one) means a staged publish uploads the
|
|
33
33
|
# tarball and creates the version, but it isn't installable yet until a
|
|
34
34
|
# maintainer separately approves it with 2FA (`npm stage approve`) -- npm's
|
|
35
35
|
# own stronger default over a direct `npm publish`, which would make the
|
|
@@ -162,7 +162,7 @@ jobs:
|
|
|
162
162
|
needs: pack
|
|
163
163
|
runs-on: ubuntu-latest
|
|
164
164
|
timeout-minutes: 15
|
|
165
|
-
# Gates the git tag, the GitHub Release, and
|
|
165
|
+
# Gates the git tag, the GitHub Release, and the staged publish behind a
|
|
166
166
|
# required reviewer -- without this, all three already exist by the time
|
|
167
167
|
# a maintainer even sees there's a staged version to approve with
|
|
168
168
|
# `npm stage approve`. The environment (created once, by hand, via
|
|
@@ -185,28 +185,22 @@ jobs:
|
|
|
185
185
|
package-manager-cache: false
|
|
186
186
|
# Only the changesets CLI is needed here, not any package's lifecycle scripts.
|
|
187
187
|
- run: pnpm install --frozen-lockfile --ignore-scripts
|
|
188
|
-
#
|
|
189
|
-
#
|
|
190
|
-
#
|
|
191
|
-
#
|
|
192
|
-
#
|
|
193
|
-
#
|
|
194
|
-
#
|
|
195
|
-
#
|
|
196
|
-
#
|
|
197
|
-
|
|
198
|
-
# string.
|
|
199
|
-
- run: npm ci --ignore-scripts --prefix .github/release-tools
|
|
200
|
-
- run: echo "$GITHUB_WORKSPACE/.github/release-tools/node_modules/.bin" >> "$GITHUB_PATH"
|
|
188
|
+
# Staged publishing goes through libnpmpublish (npm's own publish
|
|
189
|
+
# library, bin/npm-stage-publish.mjs), not the npm CLI: the CLI bundles
|
|
190
|
+
# its own dependencies, which no override can patch. Pinned to exact
|
|
191
|
+
# versions, not a range or `latest`: this job holds the OIDC token, and
|
|
192
|
+
# an unpinned package install is exactly what OpenSSF Scorecard's
|
|
193
|
+
# Pinned-Dependencies check flags. `tools/release/` pins every tarball
|
|
194
|
+
# via its committed lockfile's integrity hash, and `npm ci` verifies the
|
|
195
|
+
# install against it -- bumping the pin is then a normal reviewed PR (a
|
|
196
|
+
# lockfile diff), not a hand-edited version string.
|
|
197
|
+
- run: npm ci --ignore-scripts --prefix tools/release
|
|
201
198
|
# changesets publishes through `pnpm publish` in a pnpm-managed
|
|
202
|
-
# project
|
|
203
|
-
#
|
|
204
|
-
#
|
|
205
|
-
#
|
|
206
|
-
|
|
207
|
-
# since 2026-09-03; a direct `npm publish` gets the same 403 for a
|
|
208
|
-
# different reason). Remove both once pnpm's own publish authenticates.
|
|
209
|
-
- name: Route publish through the npm CLI
|
|
199
|
+
# project. This puts a `pnpm` ahead of the real one that forwards
|
|
200
|
+
# everything except `publish`, which goes to a staged publish
|
|
201
|
+
# instead (see bin/pnpm-publish-shim.mjs -- the trusted publisher only
|
|
202
|
+
# allows staged publishing, npm's own default since 2026-09-03).
|
|
203
|
+
- name: Route publish through the staged publisher
|
|
210
204
|
run: |
|
|
211
205
|
shim_dir="$RUNNER_TEMP/pnpm-shim"
|
|
212
206
|
mkdir -p "$shim_dir"
|
|
@@ -216,6 +210,8 @@ jobs:
|
|
|
216
210
|
echo "$shim_dir" >> "$GITHUB_PATH"
|
|
217
211
|
- uses: changesets/action/publish@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2
|
|
218
212
|
id: publish
|
|
213
|
+
env:
|
|
214
|
+
RELEASE_TOOLS_DIR: ${{ github.workspace }}/tools/release
|
|
219
215
|
with:
|
|
220
216
|
pack-dir-artifact-id: ${{ needs.pack.outputs.pack-dir-artifact-id }}
|
|
221
217
|
# npm provenance alone already meets most supply-chain "signed
|
|
@@ -226,12 +222,12 @@ jobs:
|
|
|
226
222
|
# rebuilt), attested, and attached. `if:` guards all three on
|
|
227
223
|
# `publish` actually having published -- `select-mode` only decides
|
|
228
224
|
# the job should run, not that a version was new.
|
|
229
|
-
# `continue-on-error: true` on all three:
|
|
225
|
+
# `continue-on-error: true` on all three: the staged publish has
|
|
230
226
|
# already succeeded by this point, so a failure here (a transient
|
|
231
227
|
# download error, say) must never fail the whole job and leave a
|
|
232
228
|
# staged, tagged, unreleased version behind -- this block is
|
|
233
|
-
# best-effort supplementary evidence
|
|
234
|
-
#
|
|
229
|
+
# best-effort supplementary evidence. (The stage id to approve is
|
|
230
|
+
# printed, and added to the job summary, by the publish step itself.)
|
|
235
231
|
- name: Fetch the packed tarball back out of the pack job's artifact
|
|
236
232
|
if: steps.publish.outputs.published == 'true'
|
|
237
233
|
continue-on-error: true
|
|
@@ -283,13 +279,3 @@ jobs:
|
|
|
283
279
|
fi
|
|
284
280
|
gh release upload "$tag" \
|
|
285
281
|
"$tarball" --clobber --repo "${{ github.repository }}"
|
|
286
|
-
# Staging succeeds unattended; going live needs a maintainer's 2FA
|
|
287
|
-
# (`npm stage approve <id>`, on the CLI or npmjs.com -- never
|
|
288
|
-
# automatable, by design). Best-effort convenience only: this job
|
|
289
|
-
# never logs in with a token (it publishes purely via the OIDC
|
|
290
|
-
# exchange scoped to the publish call itself), so `npm stage list` may
|
|
291
|
-
# print nothing useful -- `|| true` means that possibility never fails
|
|
292
|
-
# the job.
|
|
293
|
-
- name: List pending stages (best effort)
|
|
294
|
-
if: always()
|
|
295
|
-
run: npm stage list --package "$(node -p "require('./package.json').name")" || true
|
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
// SPDX-License-Identifier: NOASSERTION
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
7
|
-
* tarball
|
|
6
|
+
* Parses the one `pnpm publish` invocation changesets makes for a packed
|
|
7
|
+
* tarball, for `pnpm-publish-shim.mjs` and `npm-stage-publish.mjs`.
|
|
8
8
|
*
|
|
9
9
|
* Changesets runs (see its `lib/pnpm.ts`):
|
|
10
10
|
* pnpm publish <tarball> [--json] --access <a> --tag <t> --no-git-checks [--otp <c>]
|
|
@@ -13,25 +13,24 @@
|
|
|
13
13
|
* is refused rather than guessed at: if changesets ever starts passing a flag
|
|
14
14
|
* this does not understand, publishing must stop, not silently do something else.
|
|
15
15
|
*
|
|
16
|
-
* Staged, not direct: a trusted publisher created since 2026-09-03
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
* automatable) before a staged version actually goes live. `npm stage publish`
|
|
20
|
-
* accepts the same `--access`/`--tag`/`--otp`/`--provenance` flags as
|
|
21
|
-
* `npm publish` ("parity with npm publish" per npm's own CLI reference); the
|
|
22
|
-
* command itself is `npm stage publish`, not a flag on `npm publish`.
|
|
16
|
+
* Staged, not direct: a trusted publisher created since 2026-09-03 only allows a
|
|
17
|
+
* staged publish -- a maintainer must separately run `npm stage approve <id>`
|
|
18
|
+
* (2FA, never automatable) before a staged version actually goes live.
|
|
23
19
|
*/
|
|
24
20
|
|
|
25
21
|
const DROPPED = new Set(["--json", "--no-git-checks"]);
|
|
26
22
|
const WITH_VALUE = new Set(["--access", "--tag", "--otp"]);
|
|
27
23
|
|
|
28
24
|
/**
|
|
25
|
+
* Splits the arguments after `pnpm publish` into the tarball and the
|
|
26
|
+
* `[flag, value]` pairs changesets passes, refusing anything else.
|
|
27
|
+
*
|
|
29
28
|
* @param {string[]} args the arguments following `pnpm publish`
|
|
30
|
-
* @returns {
|
|
29
|
+
* @returns {{ tarball: string, pairs: [string, string][] }}
|
|
31
30
|
*/
|
|
32
|
-
|
|
31
|
+
function scanPublishArgs(args) {
|
|
33
32
|
let tarball;
|
|
34
|
-
const
|
|
33
|
+
const pairs = [];
|
|
35
34
|
|
|
36
35
|
for (let i = 0; i < args.length; i += 1) {
|
|
37
36
|
const arg = args[i];
|
|
@@ -42,7 +41,7 @@ export function toNpmStagePublishArgs(args) {
|
|
|
42
41
|
if (value === undefined || value.startsWith("--")) {
|
|
43
42
|
throw new Error(`${arg} needs a value`);
|
|
44
43
|
}
|
|
45
|
-
|
|
44
|
+
pairs.push([arg, value]);
|
|
46
45
|
i += 1;
|
|
47
46
|
continue;
|
|
48
47
|
}
|
|
@@ -61,12 +60,21 @@ export function toNpmStagePublishArgs(args) {
|
|
|
61
60
|
"no tarball given: this shim only publishes packed tarballs (changesets' --from-pack-dir mode)",
|
|
62
61
|
);
|
|
63
62
|
}
|
|
63
|
+
return { tarball, pairs };
|
|
64
|
+
}
|
|
64
65
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
66
|
+
/**
|
|
67
|
+
* Parses the one `pnpm publish` invocation changesets makes, as named values
|
|
68
|
+
* for `npm-stage-publish.mjs` (which calls libnpmpublish instead of the npm CLI).
|
|
69
|
+
*
|
|
70
|
+
* @param {string[]} args the arguments following `pnpm publish`
|
|
71
|
+
* @returns {{ tarball: string, access?: string, tag?: string, otp?: string }}
|
|
72
|
+
*/
|
|
73
|
+
export function parsePublishArgs(args) {
|
|
74
|
+
const { tarball, pairs } = scanPublishArgs(args);
|
|
75
|
+
const out = { tarball };
|
|
76
|
+
for (const [flag, value] of pairs) out[flag.slice(2)] = value;
|
|
77
|
+
return out;
|
|
70
78
|
}
|
|
71
79
|
|
|
72
80
|
/**
|