@monte3l/groundwork 1.0.0-rc.4 → 1.0.0-rc.6
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/customize-paths.d.ts +51 -15
- package/dist/customize-paths.js +32 -13
- package/dist/fs-guard.d.ts +2 -2
- package/dist/harness/rules.d.ts +2 -1
- package/dist/harness/rules.js +3 -1
- package/dist/inventory.d.ts +1 -1
- package/dist/inventory.js +5 -2
- package/dist/plugin.d.ts +12 -12
- package/dist/plugin.js +34 -26
- 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 +73 -408
- package/plugin/skills/customize/step-0-reconcile.md +265 -0
- package/plugin/skills/customize/step-3-round-1.md +171 -0
- package/plugin/src/domain-map.ts +2 -2
- package/plugin/src/kind-facet-map.ts +39 -9
- package/plugin/src/pack-map.ts +5 -3
- package/plugin/src/plugin-map.ts +154 -11
- package/templates/core/.claude/agents/Explore.md +1 -1
- package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
- package/templates/core/.claude/hooks/guard-no-commonjs.mjs +3 -2
- package/templates/core/.claude/hooks/inject-decision-gate.mjs +7 -7
- 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/skills/triaging-ci/SKILL.md +2 -2
- package/templates/core/.claude/skills/writing-commits/SKILL.md +4 -4
- package/templates/core/.prettierignore +1 -0
- package/templates/core/CLAUDE.md +28 -15
- package/templates/core/README.md +15 -3
- package/templates/core/_gitignore +1 -0
- package/templates/core/bin/check-exports.mjs +5 -3
- package/templates/core/bin/lib/harness-rules.mjs +3 -1
- package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
- package/templates/core/bin/lint-commit.mjs +215 -10
- package/templates/core/tsconfig.base.json +10 -6
- package/templates/packs/README.md +25 -13
- package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +3 -4
- package/templates/packs/github/files/.github/workflows/claude.yml +5 -8
- 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/files/.claude/hooks/subagent-statusline.mjs +29 -14
- package/templates/packs/harness-extras/pack.json +1 -1
- package/templates/packs/publishing/files/.github/workflows/release.yml +4 -7
- package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +4 -14
- package/templates/packs/publishing/pack.json +1 -1
- package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
- package/templates/packs/quality/pack.json +1 -1
- 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
|
@@ -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");
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/tsconfig",
|
|
3
3
|
"compilerOptions": {
|
|
4
|
-
"target": "
|
|
5
|
-
"lib": ["
|
|
4
|
+
"target": "es2025",
|
|
5
|
+
"lib": ["es2025"],
|
|
6
6
|
"types": ["node"],
|
|
7
7
|
"module": "nodenext",
|
|
8
8
|
"moduleResolution": "nodenext",
|
|
@@ -12,20 +12,24 @@
|
|
|
12
12
|
"noFallthroughCasesInSwitch": true,
|
|
13
13
|
"exactOptionalPropertyTypes": true,
|
|
14
14
|
"verbatimModuleSyntax": true,
|
|
15
|
+
"erasableSyntaxOnly": true,
|
|
15
16
|
"isolatedModules": true,
|
|
16
17
|
"noUncheckedSideEffectImports": true,
|
|
17
18
|
"noPropertyAccessFromIndexSignature": true,
|
|
18
19
|
"noImplicitReturns": true,
|
|
19
20
|
"allowUnreachableCode": false,
|
|
20
21
|
// isolatedDeclarations stays out of the base config deliberately: the
|
|
21
|
-
// build
|
|
22
|
-
//
|
|
23
|
-
//
|
|
22
|
+
// per-package build projects set it individually, but a tooling project
|
|
23
|
+
// that includes tests/ can't tolerate it (a test file re-exporting a
|
|
24
|
+
// fixture without an explicit return type is normal and fine). Promoting
|
|
25
|
+
// it here would fail typecheck on every test file rather than catch a
|
|
26
|
+
// real declaration-emit gap.
|
|
24
27
|
//
|
|
25
28
|
// noUnusedLocals / noUnusedParameters are deliberately NOT set:
|
|
26
29
|
// @typescript-eslint/no-unused-vars already covers both at error level
|
|
27
30
|
// (eslint.config.js) with an `^_`-prefix escape hatch this codebase
|
|
28
|
-
// relies on; tsc's flags honor no such pattern for locals
|
|
31
|
+
// relies on; tsc's flags honor no such pattern for locals, so adding
|
|
32
|
+
// them would duplicate an existing gate while breaking that convention.
|
|
29
33
|
"declaration": true,
|
|
30
34
|
"declarationMap": true,
|
|
31
35
|
"sourceMap": true,
|
|
@@ -11,11 +11,17 @@ 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
|
```
|
|
18
18
|
|
|
19
|
+
A pack has no release of its own: it ships inside the CLI tarball, so a change
|
|
20
|
+
to one that is user-visible takes a CLI changeset whose summary starts with
|
|
21
|
+
`pack(<name>):`. The checklist for working on a pack lives in the source
|
|
22
|
+
repository's own `.claude/rules/pack-<name>.md` (m3l-groundwork, not shipped),
|
|
23
|
+
not in the pack, since a pack cannot ship a rule (see below).
|
|
24
|
+
|
|
19
25
|
## The wiring contract
|
|
20
26
|
|
|
21
27
|
**A pack never edits YAML or JavaScript.** It may add files under `files/`.
|
|
@@ -39,15 +45,19 @@ already enumerate groups rather than individual steps.
|
|
|
39
45
|
`pack.json` fields:
|
|
40
46
|
|
|
41
47
|
- `schemaVersion` — currently `1`.
|
|
42
|
-
- `modes` — `["fresh"]` and/or `["fresh", "adopt"]`.
|
|
43
|
-
an artifact has no dependency on the baseline's exact
|
|
44
|
-
agent, most hooks), so it
|
|
45
|
-
project
|
|
46
|
-
|
|
47
|
-
|
|
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.
|
|
48
57
|
- `budget` — the pack's cap deltas (`agents`/`skills`/`hooks`/`workflows`/
|
|
49
|
-
`scripts`), checked
|
|
50
|
-
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.
|
|
51
61
|
- `requires.paths` — baseline files a pack artifact imports (e.g.
|
|
52
62
|
`bin/lib/agent-roster.mjs`). Checked at install time in fresh mode; a
|
|
53
63
|
missing requirement is a hard install error, not a silent partial install.
|
|
@@ -57,8 +67,10 @@ already enumerate groups rather than individual steps.
|
|
|
57
67
|
- `wiring.settingsTopLevel` — top-level `.claude/settings.json` keys that
|
|
58
68
|
aren't hook registrations (`statusLine`, `subagentStatusLine`, …), planted
|
|
59
69
|
whole. A key the project already defines with a different value is a hard
|
|
60
|
-
install error, never an overwrite; `hooks` is refused
|
|
61
|
-
|
|
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.
|
|
62
74
|
- `wiring.packageScripts` — `package.json` script additions. Most packs need
|
|
63
75
|
none: a gate registers directly as `["node", "bin/check-x.mjs"]` in
|
|
64
76
|
`wiring.verifySteps`, not as a `pnpm` script.
|
|
@@ -96,6 +108,6 @@ already enumerate groups rather than individual steps.
|
|
|
96
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`). |
|
|
97
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. |
|
|
98
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`. |
|
|
99
|
-
| `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
|
|
100
|
-
| `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. |
|
|
101
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]
|
|
@@ -87,7 +86,7 @@ jobs:
|
|
|
87
86
|
fetch-depth: 0
|
|
88
87
|
|
|
89
88
|
- id: claude
|
|
90
|
-
uses: anthropics/claude-code-action@
|
|
89
|
+
uses: anthropics/claude-code-action@6fed3ca145920b639991cb756090506e1bcaf515 # v1.0.245
|
|
91
90
|
with:
|
|
92
91
|
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
93
92
|
# Swap in CLAUDE_CODE_OAUTH_TOKEN or the Workload Identity
|
|
@@ -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)) ||
|
|
@@ -70,7 +67,7 @@ jobs:
|
|
|
70
67
|
fetch-depth: 1
|
|
71
68
|
|
|
72
69
|
- name: Run Claude Code
|
|
73
|
-
uses: anthropics/claude-code-action@
|
|
70
|
+
uses: anthropics/claude-code-action@6fed3ca145920b639991cb756090506e1bcaf515 # v1.0.245
|
|
74
71
|
with:
|
|
75
72
|
# Option 1 (active default): a stored API key. Install the Claude
|
|
76
73
|
# GitHub App (https://github.com/apps/claude) and add
|
|
@@ -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
|
|
@@ -5,17 +5,19 @@
|
|
|
5
5
|
*
|
|
6
6
|
* The command receives one JSON object on stdin per refresh tick: the base
|
|
7
7
|
* hook fields, a `columns` field (usable row width), and a `tasks` array.
|
|
8
|
-
* Each task may carry `id`, `name`, `type`, `
|
|
9
|
-
* `startTime`, `model`, `effort`, `contextWindowSize`,
|
|
10
|
-
* `tokenSamples`, `cwd` -- `model`/`contextWindowSize` require
|
|
11
|
-
* v2.1.205+ and `
|
|
12
|
-
* simply absent and the row omits them.
|
|
8
|
+
* Each task may carry `id`, `name`, `type`, `agentType`, `status`,
|
|
9
|
+
* `description`, `label`, `startTime`, `model`, `effort`, `contextWindowSize`,
|
|
10
|
+
* `tokenCount`, `tokenSamples`, `cwd` -- `model`/`contextWindowSize` require
|
|
11
|
+
* Claude Code v2.1.205+, `effort` v2.1.214+ and `agentType` v2.1.293+. On an
|
|
12
|
+
* older version those fields are simply absent and the row omits them.
|
|
13
13
|
*
|
|
14
14
|
* Output is one JSON line per row to override: `{"id": "<task id>", "content":
|
|
15
15
|
* "<row body>"}`. A task is left with Claude Code's own default rendering
|
|
16
16
|
* (name · description · token count) by omitting it from the output entirely
|
|
17
|
-
* -- this happens whenever `id`
|
|
18
|
-
* guessing at a row.
|
|
17
|
+
* -- this happens whenever `id` is missing/unusable, or both `name` and
|
|
18
|
+
* `agentType` are, rather than guessing at a row. `name` is the row's label
|
|
19
|
+
* when present; `agentType` (the same value hooks receive as `agent_type`)
|
|
20
|
+
* stands in for a task that has no name.
|
|
19
21
|
*
|
|
20
22
|
* The elapsed-time color thresholds (15/30 minutes) mark a subagent worth a
|
|
21
23
|
* glance and one that has probably stalled.
|
|
@@ -46,9 +48,9 @@ export const ELAPSED_WARN_THRESHOLD_SEC = 15 * 60;
|
|
|
46
48
|
export const ELAPSED_HIGH_THRESHOLD_SEC = 30 * 60;
|
|
47
49
|
|
|
48
50
|
/**
|
|
49
|
-
* @param {unknown} value a task's `startTime` field. The
|
|
50
|
-
*
|
|
51
|
-
*
|
|
51
|
+
* @param {unknown} value a task's `startTime` field. The statusline docs
|
|
52
|
+
* document it as a number of milliseconds since the Unix epoch; an ISO 8601
|
|
53
|
+
* string is still accepted leniently.
|
|
52
54
|
* @returns {number | null} epoch milliseconds, or null when unparseable.
|
|
53
55
|
*/
|
|
54
56
|
export function parseStartTime(value) {
|
|
@@ -124,12 +126,25 @@ export function formatEffort(effort) {
|
|
|
124
126
|
*/
|
|
125
127
|
export function formatSubagentRow(task, env) {
|
|
126
128
|
if (typeof task !== "object" || task === null) return null;
|
|
127
|
-
const {
|
|
128
|
-
|
|
129
|
+
const {
|
|
130
|
+
id,
|
|
131
|
+
name,
|
|
132
|
+
agentType,
|
|
133
|
+
effort,
|
|
134
|
+
startTime,
|
|
135
|
+
tokenCount,
|
|
136
|
+
contextWindowSize,
|
|
137
|
+
} = /** @type {Record<string, unknown>} */ (task);
|
|
129
138
|
if (typeof id !== "string" || id.length === 0) return null;
|
|
130
|
-
|
|
139
|
+
const label =
|
|
140
|
+
typeof name === "string" && name.length > 0
|
|
141
|
+
? name
|
|
142
|
+
: typeof agentType === "string" && agentType.length > 0
|
|
143
|
+
? agentType
|
|
144
|
+
: null;
|
|
145
|
+
if (label === null) return null;
|
|
131
146
|
|
|
132
|
-
const segments = [
|
|
147
|
+
const segments = [label];
|
|
133
148
|
|
|
134
149
|
const effortText = formatEffort(effort);
|
|
135
150
|
if (effortText !== null) segments.push(`${MAGENTA}${effortText}${RESET}`);
|
|
@@ -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
|
}
|
|
@@ -199,13 +199,10 @@ jobs:
|
|
|
199
199
|
- run: npm ci --ignore-scripts --prefix .github/release-tools
|
|
200
200
|
- run: echo "$GITHUB_WORKSPACE/.github/release-tools/node_modules/.bin" >> "$GITHUB_PATH"
|
|
201
201
|
# changesets publishes through `pnpm publish` in a pnpm-managed
|
|
202
|
-
# project
|
|
203
|
-
#
|
|
204
|
-
#
|
|
205
|
-
#
|
|
206
|
-
# trusted publisher only allows staged publishing, npm's own default
|
|
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.
|
|
202
|
+
# project. This puts a `pnpm` ahead of the real one that forwards
|
|
203
|
+
# everything except `publish`, which goes to `npm stage publish`
|
|
204
|
+
# instead (see bin/pnpm-publish-shim.mjs -- the trusted publisher only
|
|
205
|
+
# allows staged publishing, npm's own default since 2026-09-03).
|
|
209
206
|
- name: Route publish through the npm CLI
|
|
210
207
|
run: |
|
|
211
208
|
shim_dir="$RUNNER_TEMP/pnpm-shim"
|
|
@@ -9,18 +9,10 @@
|
|
|
9
9
|
*
|
|
10
10
|
* ## Why it exists
|
|
11
11
|
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
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-managed project publishes through
|
|
13
|
+
* `pnpm publish`. A trusted publisher created since 2026-09-03 defaults to
|
|
14
|
+
* `npm stage publish` only, npm's own explicit recommendation (see this
|
|
15
|
+
* pack's adoptNotes), so the publish is rerouted to `npm stage publish`.
|
|
24
16
|
*
|
|
25
17
|
* ## What it translates
|
|
26
18
|
*
|
|
@@ -42,8 +34,6 @@
|
|
|
42
34
|
*
|
|
43
35
|
* `PNPM_SHIM_DIR` names this shim's own directory so it can be dropped from
|
|
44
36
|
* PATH when looking for the real pnpm (otherwise it would find itself).
|
|
45
|
-
* Delete this, and the workflow step that installs it, once pnpm's publish
|
|
46
|
-
* authenticates against npmjs.com.
|
|
47
37
|
*/
|
|
48
38
|
import process from "node:process";
|
|
49
39
|
import { spawnSync } from "node:child_process";
|