@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
package/README.md
CHANGED
|
@@ -7,11 +7,23 @@ project compares to that setup.
|
|
|
7
7
|
The offline bootstrapper behind [m3l-groundwork](https://github.com/monte3l/m3l-groundwork):
|
|
8
8
|
one deterministic CLI that either writes a baseline TypeScript toolchain and
|
|
9
9
|
Claude Code **harness** (its agents, skills, hooks, and settings) into an
|
|
10
|
-
empty directory (**fresh** mode) or surveys an existing project
|
|
11
|
-
|
|
12
|
-
it's for a project that already exists and shouldn't be rewritten
|
|
10
|
+
empty directory (**fresh** mode) or surveys an existing project (**adopt
|
|
11
|
+
mode**, for a project that already exists and shouldn't be rewritten
|
|
13
12
|
automatically).
|
|
14
13
|
|
|
14
|
+
Fresh mode writes the baseline, installs any `--pack`, installs the
|
|
15
|
+
`/customize` skill, runs `git init`, then runs `pnpm install`. If `git init`
|
|
16
|
+
or `pnpm install` fails, the project is already written to disk and the error
|
|
17
|
+
says what to run yourself.
|
|
18
|
+
|
|
19
|
+
Adopt mode never overwrites or removes a project file. It writes a report
|
|
20
|
+
(`.groundwork/adoption-report.md`), an inventory (`.groundwork/inventory.json`),
|
|
21
|
+
and inert `.staged` copies of the baseline files your project lacks
|
|
22
|
+
(`.groundwork/baseline/`) and of the packs that apply
|
|
23
|
+
(`.groundwork/packs/`), all under `.groundwork/`. It also adds one guarded
|
|
24
|
+
copy of the `/customize` skill at `.claude/skills/customize/`, or at
|
|
25
|
+
`.groundwork/customize/` when something already there blocks it.
|
|
26
|
+
|
|
15
27
|
```bash
|
|
16
28
|
# currently a 1.0.0 release candidate, shipping on the `rc` dist-tag
|
|
17
29
|
npx @monte3l/groundwork@rc my-new-project
|
|
@@ -21,10 +33,13 @@ npx @monte3l/groundwork@rc ../existing-project
|
|
|
21
33
|
|
|
22
34
|
Requires Node 24+. No prompts, and no network call beyond the `pnpm install` a
|
|
23
35
|
fresh bootstrap ends with (`--skip-install` to skip it). Run with `--help` for
|
|
24
|
-
every flag, or `--list-packs` for the optional packs.
|
|
36
|
+
every flag, or `--list-packs` for the optional packs. Exit `0` is success, `1`
|
|
37
|
+
is a runtime failure, and `2` is a bad invocation.
|
|
25
38
|
|
|
26
39
|
The `/customize` skill it installs, the packs, and the design are documented in
|
|
27
|
-
the [repository README](https://github.com/monte3l/m3l-groundwork/blob/main/README.md)
|
|
40
|
+
the [repository README](https://github.com/monte3l/m3l-groundwork/blob/main/README.md),
|
|
41
|
+
whose [versioning policy](https://github.com/monte3l/m3l-groundwork/blob/main/README.md#versioning-policy)
|
|
42
|
+
also lists the stable surfaces, including the adoption report's section headings.
|
|
28
43
|
Unfamiliar terms (harness, adopt mode, pack, and the rest) are defined in the
|
|
29
44
|
[glossary](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md).
|
|
30
45
|
|
package/dist/inventory.d.ts
CHANGED
|
@@ -9,7 +9,7 @@ import type { PackWiring } from "./packs.js";
|
|
|
9
9
|
import type { ProjectSurvey } from "./survey/survey.js";
|
|
10
10
|
import type { ToolchainConformance } from "./toolchain/conformance.js";
|
|
11
11
|
import type { ToolchainGrade } from "./toolchain/types.js";
|
|
12
|
-
export declare const INVENTORY_SCHEMA_VERSION =
|
|
12
|
+
export declare const INVENTORY_SCHEMA_VERSION = 6;
|
|
13
13
|
/**
|
|
14
14
|
* Where adopt mode staged the baseline files the project lacks entirely
|
|
15
15
|
* (`baseline-stage.ts`), and how each staged copy is named.
|
package/dist/inventory.js
CHANGED
|
@@ -21,7 +21,10 @@
|
|
|
21
21
|
* (`pack-stage.ts`), its manifest included. No published release has
|
|
22
22
|
* written schema 5 yet; an inventory without `stagedPacks` came only from an
|
|
23
23
|
* unreleased development build, which staged packs unsuffixed at the same
|
|
24
|
-
* location.
|
|
24
|
+
* location. `schemaVersion` below 6 predates `survey.harness.pluginLayout`
|
|
25
|
+
* (`null`, or the `.claude-plugin/plugin.json` manifest plus which root
|
|
26
|
+
* plugin components exist) -- `/customize` then has no plugin-layout
|
|
27
|
+
* evidence and asks the project kind without pre-selecting one.
|
|
25
28
|
*/
|
|
26
29
|
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
|
|
27
30
|
import { dirname, join } from "node:path";
|
|
@@ -29,7 +32,7 @@ import { fileURLToPath } from "node:url";
|
|
|
29
32
|
import { toPosixPath } from "./assets.js";
|
|
30
33
|
import { summarizeHarnessConformance } from "./harness/conformance.js";
|
|
31
34
|
import { summarizeToolchainConformance } from "./toolchain/conformance.js";
|
|
32
|
-
export const INVENTORY_SCHEMA_VERSION =
|
|
35
|
+
export const INVENTORY_SCHEMA_VERSION = 6;
|
|
33
36
|
/** Resolves this CLI package's own `package.json`, relative to this module's runtime location. */
|
|
34
37
|
function defaultPackageJsonPath() {
|
|
35
38
|
const here = dirname(fileURLToPath(import.meta.url));
|
package/dist/report.js
CHANGED
|
@@ -25,7 +25,13 @@ function estimatePostMergeCaps(inventory) {
|
|
|
25
25
|
},
|
|
26
26
|
};
|
|
27
27
|
}
|
|
28
|
-
/**
|
|
28
|
+
/**
|
|
29
|
+
* Sums the declared `budget` of every listed pack adopt mode can install
|
|
30
|
+
* (`modes` includes `"adopt"`) -- the "if every adoptable pack were
|
|
31
|
+
* installed" delta, not just the ones a user will choose. A fresh-only pack
|
|
32
|
+
* (e.g. `publishing`) is left out: adopt mode cannot install it, so counting
|
|
33
|
+
* it would flag a cap no adopt run can reach.
|
|
34
|
+
*/
|
|
29
35
|
function sumPackBudgets(packs) {
|
|
30
36
|
const total = {
|
|
31
37
|
agents: 0,
|
|
@@ -35,6 +41,8 @@ function sumPackBudgets(packs) {
|
|
|
35
41
|
scripts: 0,
|
|
36
42
|
};
|
|
37
43
|
for (const pack of packs) {
|
|
44
|
+
if (!pack.modes.includes("adopt"))
|
|
45
|
+
continue;
|
|
38
46
|
total.agents += pack.budget.agents;
|
|
39
47
|
total.skills += pack.budget.skills;
|
|
40
48
|
total.hooks += pack.budget.hooks;
|
|
@@ -55,10 +63,23 @@ function renderShapeSection(inventory) {
|
|
|
55
63
|
`- Node pin: ${s.nodeVersionPin ? `${s.nodeVersionPin.value} (${s.nodeVersionPin.source})` : "none found"}`,
|
|
56
64
|
`- Source layout: ${s.sourceLayout}`,
|
|
57
65
|
`- Test placement: ${s.testPlacement}`,
|
|
58
|
-
`- Kind evidence: exports map=${s.kindEvidence.hasExportsMap}, bin=${s.kindEvidence.hasBinField}, main=${s.kindEvidence.hasMainField}, framework deps=${s.kindEvidence.frameworkDeps.join(", ") || "none"}`,
|
|
66
|
+
`- Kind evidence: exports map=${s.kindEvidence.hasExportsMap}, bin=${s.kindEvidence.hasBinField}, main=${s.kindEvidence.hasMainField}, framework deps=${s.kindEvidence.frameworkDeps.join(", ") || "none"}, claude plugin manifest=${pluginManifestEvidence(inventory)}`,
|
|
59
67
|
];
|
|
60
68
|
return lines.join("\n");
|
|
61
69
|
}
|
|
70
|
+
/**
|
|
71
|
+
* The kind-evidence `claude plugin manifest` value: `true` when a plugin
|
|
72
|
+
* layout was recorded, `unknown` when none was but some `undetermined` note
|
|
73
|
+
* names a `.claude-plugin` path (a probe that could not be made), else
|
|
74
|
+
* `false`.
|
|
75
|
+
*/
|
|
76
|
+
function pluginManifestEvidence(inventory) {
|
|
77
|
+
if (inventory.survey.harness.pluginLayout != null)
|
|
78
|
+
return "true";
|
|
79
|
+
return inventory.survey.undetermined.some((entry) => entry.includes(".claude-plugin"))
|
|
80
|
+
? "unknown (see Could not be determined)"
|
|
81
|
+
: "false";
|
|
82
|
+
}
|
|
62
83
|
function renderToolchainSection(inventory) {
|
|
63
84
|
const t = inventory.survey.toolchain;
|
|
64
85
|
const lines = [
|
|
@@ -75,6 +96,39 @@ function renderToolchainSection(inventory) {
|
|
|
75
96
|
];
|
|
76
97
|
return lines.join("\n");
|
|
77
98
|
}
|
|
99
|
+
/** The "- Plugin layout: ..." line for a plugin repository, or nothing. */
|
|
100
|
+
function pluginLayoutLines(layout) {
|
|
101
|
+
if (layout == null)
|
|
102
|
+
return [];
|
|
103
|
+
const components = layout.components.length > 0 ? layout.components.join(", ") : "none";
|
|
104
|
+
return [`- Plugin layout: ${layout.manifest}; components: ${components}`];
|
|
105
|
+
}
|
|
106
|
+
/** The harness grade's scope note for a plugin repository, or nothing. */
|
|
107
|
+
function pluginScopeLines(layout) {
|
|
108
|
+
if (layout == null)
|
|
109
|
+
return [];
|
|
110
|
+
return [
|
|
111
|
+
"Plugin components at the repository root are outside the harness grader's scope (it reads .claude/ and CLAUDE.md).",
|
|
112
|
+
];
|
|
113
|
+
}
|
|
114
|
+
/** Total checks across every rubric category of a grade. */
|
|
115
|
+
function rubricTotal(rubric) {
|
|
116
|
+
return Object.values(rubric).reduce((sum, tally) => sum + tally.checked, 0);
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* The wiring and quality lines of a grade section, each half rendered on its
|
|
120
|
+
* own: a half with no checks applied says so instead of printing a vacuous
|
|
121
|
+
* "0 of 0" or a 100% over nothing.
|
|
122
|
+
*/
|
|
123
|
+
function gradeHalvesLines(structural, rubricChecked, rubricScore) {
|
|
124
|
+
const wiring = structural.checked === 0
|
|
125
|
+
? "- **Wiring (structural):** no checks applied (nothing found, or nothing the grader could read)."
|
|
126
|
+
: `- **Wiring (structural):** ${structural.checked - structural.failed} of ${structural.checked} checks pass.`;
|
|
127
|
+
const quality = rubricChecked === 0
|
|
128
|
+
? "- **Quality (rubric):** no checks applied."
|
|
129
|
+
: `- **Quality (rubric):** ${Math.round(rubricScore * 100)}% over ${rubricChecked} checks -- advisory, never a blocker.`;
|
|
130
|
+
return [wiring, quality];
|
|
131
|
+
}
|
|
78
132
|
function renderHarnessSection(inventory) {
|
|
79
133
|
const h = inventory.survey.harness;
|
|
80
134
|
if (!h.present) {
|
|
@@ -82,6 +136,7 @@ function renderHarnessSection(inventory) {
|
|
|
82
136
|
"## Existing Claude Code harness",
|
|
83
137
|
"",
|
|
84
138
|
"No `.claude/` directory found -- the baseline harness would be entirely new.",
|
|
139
|
+
...pluginLayoutLines(h.pluginLayout),
|
|
85
140
|
].join("\n");
|
|
86
141
|
}
|
|
87
142
|
const lines = [
|
|
@@ -93,6 +148,7 @@ function renderHarnessSection(inventory) {
|
|
|
93
148
|
`- Rules: ${h.rules.length > 0 ? h.rules.map((r) => r.name).join(", ") : "none"}`,
|
|
94
149
|
`- Commands: ${h.commands.length > 0 ? h.commands.join(", ") : "none"}`,
|
|
95
150
|
`- settings.local.json present: ${h.hasSettingsLocal}`,
|
|
151
|
+
...pluginLayoutLines(h.pluginLayout),
|
|
96
152
|
];
|
|
97
153
|
return lines.join("\n");
|
|
98
154
|
}
|
|
@@ -113,12 +169,12 @@ function renderDocsSection(inventory) {
|
|
|
113
169
|
function renderToolchainGradeSection(inventory) {
|
|
114
170
|
const { toolchainGrade: grade, toolchainConformance: conformance } = inventory;
|
|
115
171
|
const lines = ["## Toolchain grade", ""];
|
|
116
|
-
const rubricChecked =
|
|
172
|
+
const rubricChecked = rubricTotal(grade.rubric);
|
|
117
173
|
if (grade.structural.checked === 0 && rubricChecked === 0) {
|
|
118
174
|
lines.push("No TypeScript toolchain files (tsconfig, ESLint or vitest config, verify steps) found -- nothing to grade.");
|
|
119
175
|
return lines.join("\n");
|
|
120
176
|
}
|
|
121
|
-
lines.push(
|
|
177
|
+
lines.push(...gradeHalvesLines(grade.structural, rubricChecked, grade.rubricScore), `- **Drift from the baseline toolchain:** ${conformance.identical} identical, ${conformance.divergent} divergent, ${conformance.absent} absent. ` +
|
|
122
178
|
"Informational only -- `/customize` rewrites the baseline on purpose, so divergence is not a defect.");
|
|
123
179
|
const structural = grade.findings.filter((f) => f.level === "structural");
|
|
124
180
|
const rubric = grade.findings.filter((f) => f.level === "rubric");
|
|
@@ -149,11 +205,17 @@ function renderHarnessGradeSection(inventory) {
|
|
|
149
205
|
const lines = ["## Harness grade", ""];
|
|
150
206
|
if (!harness.present && !harness.hasClaudeMd) {
|
|
151
207
|
lines.push("No `.claude/` directory or `CLAUDE.md` found -- nothing to grade.");
|
|
208
|
+
const scope = pluginScopeLines(harness.pluginLayout);
|
|
209
|
+
if (scope.length > 0)
|
|
210
|
+
lines.push("", ...scope);
|
|
152
211
|
return lines.join("\n");
|
|
153
212
|
}
|
|
154
|
-
const rubricChecked =
|
|
155
|
-
lines.push(
|
|
213
|
+
const rubricChecked = rubricTotal(grade.rubric);
|
|
214
|
+
lines.push(...gradeHalvesLines(grade.structural, rubricChecked, grade.rubricScore), `- **Drift from the baseline harness:** ${conformance.identical} identical, ${conformance.divergent} divergent, ${conformance.absent} absent. ` +
|
|
156
215
|
"Informational only -- `/customize` rewrites the baseline on purpose, so divergence is not a defect.");
|
|
216
|
+
const scope = pluginScopeLines(harness.pluginLayout);
|
|
217
|
+
if (scope.length > 0)
|
|
218
|
+
lines.push("", ...scope);
|
|
157
219
|
const structural = grade.findings.filter((f) => f.level === "structural");
|
|
158
220
|
const rubric = grade.findings.filter((f) => f.level === "rubric");
|
|
159
221
|
lines.push("", "### Wiring findings", "");
|
|
@@ -185,13 +247,13 @@ function renderCapsSection(inventory) {
|
|
|
185
247
|
const packBudget = sumPackBudgets(inventory.packs);
|
|
186
248
|
const overCap = (count, cap) => count > cap ? " ⚠ over cap" : "";
|
|
187
249
|
const header = hasPacks
|
|
188
|
-
? "| Artifact | Baseline | Existing project | +
|
|
250
|
+
? "| Artifact | Baseline | Existing project | + adopt packs | Post-merge (approx.) | Cap |"
|
|
189
251
|
: "| Artifact | Baseline | Existing project | Post-merge (approx.) | Cap |";
|
|
190
252
|
const divider = hasPacks
|
|
191
253
|
? "| --- | --- | --- | --- | --- | --- |"
|
|
192
254
|
: "| --- | --- | --- | --- | --- |";
|
|
193
255
|
const row = (label, key, existingCount, cap) => {
|
|
194
|
-
// The shown total (and its over-cap flag) includes the "+
|
|
256
|
+
// The shown total (and its over-cap flag) includes the "+ adopt packs"
|
|
195
257
|
// column, so a pack that tips a cap over is flagged, not just listed.
|
|
196
258
|
const total = postMerge[key] + (hasPacks ? packBudget[key] : 0);
|
|
197
259
|
const cells = [label, String(baseline[key]), String(existingCount)];
|
|
@@ -214,8 +276,10 @@ function renderCapsSection(inventory) {
|
|
|
214
276
|
"This is an approximate count assuming no name overlap; `/customize`'s Step 0 resolves it for real.",
|
|
215
277
|
];
|
|
216
278
|
if (hasPacks) {
|
|
217
|
-
lines.push("", '"+
|
|
218
|
-
|
|
279
|
+
lines.push("", '"+ adopt packs" sums every adopt-capable pack listed below, not just the ' +
|
|
280
|
+
"ones you choose to install; fresh-only packs (e.g. `publishing`) are " +
|
|
281
|
+
"excluded because adopt mode cannot install them -- see " +
|
|
282
|
+
'"## Available packs" for every pack\'s numbers.');
|
|
219
283
|
}
|
|
220
284
|
return lines.join("\n");
|
|
221
285
|
}
|
|
@@ -6,8 +6,16 @@ import type { HarnessSurvey } from "./types.js";
|
|
|
6
6
|
* `undetermined` -- an unreadable `CLAUDE.md` still counts as present, with
|
|
7
7
|
* no headings. A `.claude/` this process may not enter is still `present`,
|
|
8
8
|
* with every collection empty and the directory recorded in `undetermined`
|
|
9
|
-
* -- never reported as an empty harness.
|
|
10
|
-
*
|
|
9
|
+
* -- never reported as an empty harness. `pluginLayout` records a plugin
|
|
10
|
+
* repository's root layout (`.claude-plugin/plugin.json` and its root
|
|
11
|
+
* components), each probed by `lstat` of the path's final component, so a
|
|
12
|
+
* symlinked manifest or component is never counted (a symlinked parent
|
|
13
|
+
* directory is followed). A manifest that is not a regular file, or whose
|
|
14
|
+
* probe this process may not make, is recorded in `undetermined` and leaves
|
|
15
|
+
* it `null`; a symlinked component, or one whose probe fails with
|
|
16
|
+
* `EACCES`/`EPERM`/`ELOOP`, is recorded and omitted while the layout stays
|
|
17
|
+
* non-null. Any other read failure throws, naming the path, with the original
|
|
18
|
+
* failure as `cause`.
|
|
11
19
|
*
|
|
12
20
|
* @example
|
|
13
21
|
* ```ts
|
|
@@ -6,10 +6,10 @@
|
|
|
6
6
|
* outline -- so `/customize`'s harness sweep starts from what is actually
|
|
7
7
|
* there instead of assuming the m3l-groundwork baseline.
|
|
8
8
|
*/
|
|
9
|
-
import { readFileSync, readdirSync } from "node:fs";
|
|
9
|
+
import { lstatSync, readFileSync, readdirSync } from "node:fs";
|
|
10
10
|
import { join } from "node:path";
|
|
11
11
|
import { fieldText, parseFrontmatter } from "../harness/frontmatter.js";
|
|
12
|
-
import { guardedExists, guardedRead } from "./internal/read-guard.js";
|
|
12
|
+
import { SurveyReadError, guardedExists, guardedRead, isAbsentError, probeSubject, unreadableNote, unresolvableCode, } from "./internal/read-guard.js";
|
|
13
13
|
/**
|
|
14
14
|
* Reads one frontmatter field as text (a list is joined with `, `), or
|
|
15
15
|
* `undefined` when the file has no frontmatter, the field is absent, or its
|
|
@@ -106,6 +106,82 @@ function claudeMdHeadings(path, undetermined) {
|
|
|
106
106
|
const content = readText(path, undetermined);
|
|
107
107
|
return content === undefined ? [] : extractHeadings(content);
|
|
108
108
|
}
|
|
109
|
+
/** The plugin manifest's repository-relative path. */
|
|
110
|
+
const PLUGIN_MANIFEST = ".claude-plugin/plugin.json";
|
|
111
|
+
/**
|
|
112
|
+
* The root plugin components, in the fixed order `pluginLayout.components`
|
|
113
|
+
* reports them: each one's display name, its path segments, and the entry
|
|
114
|
+
* type it must be to count.
|
|
115
|
+
*/
|
|
116
|
+
const PLUGIN_COMPONENTS = [
|
|
117
|
+
{ name: "hooks/hooks.json", segments: ["hooks", "hooks.json"], kind: "file" },
|
|
118
|
+
{ name: "skills/", segments: ["skills"], kind: "dir" },
|
|
119
|
+
{ name: "agents/", segments: ["agents"], kind: "dir" },
|
|
120
|
+
{ name: "commands/", segments: ["commands"], kind: "dir" },
|
|
121
|
+
{ name: ".mcp.json", segments: [".mcp.json"], kind: "file" },
|
|
122
|
+
];
|
|
123
|
+
/**
|
|
124
|
+
* `lstat`s `path` -- the entry itself, never a symlink's target. Absent
|
|
125
|
+
* (`ENOENT`/`ENOTDIR`) answers `undefined` with nothing recorded; a
|
|
126
|
+
* permission failure or symlink loop is recorded in `undetermined` the way
|
|
127
|
+
* `guardedExists` records it, and answers `undefined`. Any other failure
|
|
128
|
+
* throws a {@link SurveyReadError} naming `path`, with the original as
|
|
129
|
+
* `cause`.
|
|
130
|
+
*/
|
|
131
|
+
function guardedLstat(path, undetermined) {
|
|
132
|
+
try {
|
|
133
|
+
return lstatSync(path);
|
|
134
|
+
}
|
|
135
|
+
catch (error) {
|
|
136
|
+
if (isAbsentError(error))
|
|
137
|
+
return undefined;
|
|
138
|
+
const code = unresolvableCode(error);
|
|
139
|
+
if (code === undefined) {
|
|
140
|
+
throw new SurveyReadError(`could not check whether ${path} exists`, {
|
|
141
|
+
cause: error,
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
undetermined.push(unreadableNote(probeSubject(path, code), code));
|
|
145
|
+
return undefined;
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* A Claude Code plugin repository's root layout, or `null` unless
|
|
150
|
+
* `.claude-plugin/plugin.json` is a regular file. Every probe is an `lstat`
|
|
151
|
+
* of the path's final component, so a symlinked manifest or component is
|
|
152
|
+
* never followed or counted; a symlinked parent directory (`.claude-plugin/`,
|
|
153
|
+
* `hooks/`) is resolved by the OS and followed. A manifest that exists but is
|
|
154
|
+
* not a regular file, or that this process may not probe, is recorded in
|
|
155
|
+
* `undetermined` and answers `null`. A symlinked component is recorded in
|
|
156
|
+
* `undetermined` and not counted; a component whose probe fails with
|
|
157
|
+
* `EACCES`/`EPERM`/`ELOOP` is recorded and omitted, the layout staying
|
|
158
|
+
* non-null; a component of the wrong non-symlink type is silently omitted.
|
|
159
|
+
*/
|
|
160
|
+
function surveyPluginLayout(dir, undetermined) {
|
|
161
|
+
const manifestPath = join(dir, PLUGIN_MANIFEST);
|
|
162
|
+
const manifest = guardedLstat(manifestPath, undetermined);
|
|
163
|
+
if (manifest === undefined)
|
|
164
|
+
return null;
|
|
165
|
+
if (!manifest.isFile()) {
|
|
166
|
+
const what = manifest.isSymbolicLink()
|
|
167
|
+
? "symlink, not followed"
|
|
168
|
+
: "directory or special file";
|
|
169
|
+
undetermined.push(`${manifestPath} exists but is not a regular file (${what}) -- plugin layout not surveyed`);
|
|
170
|
+
return null;
|
|
171
|
+
}
|
|
172
|
+
const components = PLUGIN_COMPONENTS.filter(({ segments, kind }) => {
|
|
173
|
+
const componentPath = join(dir, ...segments);
|
|
174
|
+
const stats = guardedLstat(componentPath, undetermined);
|
|
175
|
+
if (stats === undefined)
|
|
176
|
+
return false;
|
|
177
|
+
if (stats.isSymbolicLink()) {
|
|
178
|
+
undetermined.push(`${componentPath} is a symlink, not followed -- plugin component not counted`);
|
|
179
|
+
return false;
|
|
180
|
+
}
|
|
181
|
+
return kind === "file" ? stats.isFile() : stats.isDirectory();
|
|
182
|
+
}).map(({ name }) => name);
|
|
183
|
+
return { manifest: PLUGIN_MANIFEST, components };
|
|
184
|
+
}
|
|
109
185
|
/**
|
|
110
186
|
* Surveys the `.claude/` harness and `CLAUDE.md` at `dir`. Offline,
|
|
111
187
|
* read-only. A file or directory that exists but cannot be read
|
|
@@ -113,8 +189,16 @@ function claudeMdHeadings(path, undetermined) {
|
|
|
113
189
|
* `undetermined` -- an unreadable `CLAUDE.md` still counts as present, with
|
|
114
190
|
* no headings. A `.claude/` this process may not enter is still `present`,
|
|
115
191
|
* with every collection empty and the directory recorded in `undetermined`
|
|
116
|
-
* -- never reported as an empty harness.
|
|
117
|
-
*
|
|
192
|
+
* -- never reported as an empty harness. `pluginLayout` records a plugin
|
|
193
|
+
* repository's root layout (`.claude-plugin/plugin.json` and its root
|
|
194
|
+
* components), each probed by `lstat` of the path's final component, so a
|
|
195
|
+
* symlinked manifest or component is never counted (a symlinked parent
|
|
196
|
+
* directory is followed). A manifest that is not a regular file, or whose
|
|
197
|
+
* probe this process may not make, is recorded in `undetermined` and leaves
|
|
198
|
+
* it `null`; a symlinked component, or one whose probe fails with
|
|
199
|
+
* `EACCES`/`EPERM`/`ELOOP`, is recorded and omitted while the layout stays
|
|
200
|
+
* non-null. Any other read failure throws, naming the path, with the original
|
|
201
|
+
* failure as `cause`.
|
|
118
202
|
*
|
|
119
203
|
* @example
|
|
120
204
|
* ```ts
|
|
@@ -141,6 +225,7 @@ export function surveyHarness(dir, undetermined) {
|
|
|
141
225
|
hasSettingsLocal: false,
|
|
142
226
|
hasClaudeMd,
|
|
143
227
|
claudeMdHeadings: claudeMdHeadings(claudeMdPath, undetermined),
|
|
228
|
+
pluginLayout: surveyPluginLayout(dir, undetermined),
|
|
144
229
|
};
|
|
145
230
|
}
|
|
146
231
|
const settingsPath = join(claudeDir, "settings.json");
|
|
@@ -157,6 +242,7 @@ export function surveyHarness(dir, undetermined) {
|
|
|
157
242
|
hasSettingsLocal: guardedExists(join(claudeDir, "settings.local.json"), undetermined),
|
|
158
243
|
hasClaudeMd,
|
|
159
244
|
claudeMdHeadings: claudeMdHeadings(claudeMdPath, undetermined),
|
|
245
|
+
pluginLayout: surveyPluginLayout(dir, undetermined),
|
|
160
246
|
};
|
|
161
247
|
}
|
|
162
248
|
//# sourceMappingURL=survey-harness.js.map
|
|
@@ -155,10 +155,13 @@ function collectKindEvidence(packageJson) {
|
|
|
155
155
|
? Object.keys(devDeps)
|
|
156
156
|
: []),
|
|
157
157
|
]);
|
|
158
|
+
// Own fields only: an inherited member (e.g. under prototype pollution) is
|
|
159
|
+
// not evidence about this package.json.
|
|
160
|
+
const hasOwnField = (field) => packageJson !== undefined && Object.hasOwn(packageJson, field);
|
|
158
161
|
return {
|
|
159
|
-
hasExportsMap:
|
|
160
|
-
hasBinField:
|
|
161
|
-
hasMainField:
|
|
162
|
+
hasExportsMap: hasOwnField("exports"),
|
|
163
|
+
hasBinField: hasOwnField("bin"),
|
|
164
|
+
hasMainField: hasOwnField("main"),
|
|
162
165
|
frameworkDeps: FRAMEWORK_DEP_NAMES.filter((name) => allDepNames.has(name)),
|
|
163
166
|
};
|
|
164
167
|
}
|
|
@@ -4,9 +4,9 @@
|
|
|
4
4
|
* Collects toolchain-enforcement facts: the tsconfig `extends` chain and its
|
|
5
5
|
* effective strict-family flags, which eslint/test/formatter/git-hook tool
|
|
6
6
|
* is in play and its config file, workflow files, and the full `scripts`
|
|
7
|
-
* block. YAML-shaped config (git hooks, workflows) is indexed and
|
|
8
|
-
* here, never parsed
|
|
9
|
-
* carries no YAML dependency.
|
|
7
|
+
* block. YAML-shaped config (git hooks, workflows) is indexed by name and
|
|
8
|
+
* flagged `needsReading` here, never parsed or excerpted, because this
|
|
9
|
+
* package carries no YAML dependency.
|
|
10
10
|
*/
|
|
11
11
|
import { readFileSync, readdirSync } from "node:fs";
|
|
12
12
|
import { join } from "node:path";
|
|
@@ -181,12 +181,10 @@ function surveyScripts(packageJson) {
|
|
|
181
181
|
const scripts = packageJson?.["scripts"];
|
|
182
182
|
if (typeof scripts !== "object" || scripts === null)
|
|
183
183
|
return {};
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
}
|
|
189
|
-
return result;
|
|
184
|
+
// Object.fromEntries, not `result[key] = value` on a `{}`: assignment to
|
|
185
|
+
// `__proto__` hits the prototype setter and silently drops a script of that
|
|
186
|
+
// name, while fromEntries defines every key as an own data property.
|
|
187
|
+
return Object.fromEntries(Object.entries(scripts).filter((entry) => typeof entry[1] === "string"));
|
|
190
188
|
}
|
|
191
189
|
/**
|
|
192
190
|
* Surveys toolchain enforcement at `dir`. Appends anything it could not
|
package/dist/survey/types.d.ts
CHANGED
|
@@ -164,6 +164,39 @@ export interface HarnessSurvey {
|
|
|
164
164
|
hasClaudeMd: boolean;
|
|
165
165
|
/** `CLAUDE.md`'s level 1-3 headings in document order -- empty when there is no `CLAUDE.md`. */
|
|
166
166
|
claudeMdHeadings: string[];
|
|
167
|
+
/**
|
|
168
|
+
* A Claude Code plugin repository's root layout: `null` unless
|
|
169
|
+
* `.claude-plugin/plugin.json` is a regular file. Each probe is an `lstat`
|
|
170
|
+
* of the path's final component: a symlinked manifest or a directory is
|
|
171
|
+
* `null`, but a symlinked parent directory (`.claude-plugin/`, `hooks/`) is
|
|
172
|
+
* followed. A manifest that is not a regular file, or whose probe this
|
|
173
|
+
* process may not make, is recorded in `undetermined` and leaves this
|
|
174
|
+
* `null`. `components` lists, in this fixed order, which of
|
|
175
|
+
* `hooks/hooks.json`, `skills/`, `agents/`, `commands/` and `.mcp.json`
|
|
176
|
+
* exist at the root with the expected type; a symlinked component, or one
|
|
177
|
+
* whose probe fails with `EACCES`/`EPERM`/`ELOOP`, is recorded in
|
|
178
|
+
* `undetermined` and omitted while the layout stays non-null. An index,
|
|
179
|
+
* never a verdict: these sit outside `.claude/`, so the harness grader does
|
|
180
|
+
* not read them.
|
|
181
|
+
*/
|
|
182
|
+
pluginLayout: PluginLayout | null;
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* The root plugin layout {@link HarnessSurvey.pluginLayout} records.
|
|
186
|
+
*
|
|
187
|
+
* @example
|
|
188
|
+
* ```ts
|
|
189
|
+
* const layout: PluginLayout = {
|
|
190
|
+
* manifest: ".claude-plugin/plugin.json",
|
|
191
|
+
* components: ["hooks/hooks.json", "skills/"],
|
|
192
|
+
* };
|
|
193
|
+
* ```
|
|
194
|
+
*/
|
|
195
|
+
export interface PluginLayout {
|
|
196
|
+
/** The manifest's repository-relative path -- always the same literal. */
|
|
197
|
+
manifest: ".claude-plugin/plugin.json";
|
|
198
|
+
/** The root plugin components that exist, in the collector's fixed order. */
|
|
199
|
+
components: readonly string[];
|
|
167
200
|
}
|
|
168
201
|
/** One indexed human-facing doc: where it is and its outline, never its content. */
|
|
169
202
|
export interface DocFile {
|
package/dist/toolchain/grade.js
CHANGED
|
@@ -122,14 +122,13 @@ function loadSnapshot(root) {
|
|
|
122
122
|
const packageJson = packageRead.ok && isRecord(packageRead.value)
|
|
123
123
|
? packageRead.value
|
|
124
124
|
: undefined;
|
|
125
|
-
|
|
125
|
+
// Object.fromEntries, not `scripts[name] = cmd` on a `{}`: assignment to
|
|
126
|
+
// `__proto__` hits the prototype setter and silently drops a script of that
|
|
127
|
+
// name, while fromEntries defines every key as an own data property.
|
|
126
128
|
const rawScripts = packageJson?.["scripts"];
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
scripts[name] = cmd;
|
|
131
|
-
}
|
|
132
|
-
}
|
|
129
|
+
const scripts = isRecord(rawScripts)
|
|
130
|
+
? Object.fromEntries(Object.entries(rawScripts).filter((entry) => typeof entry[1] === "string"))
|
|
131
|
+
: {};
|
|
133
132
|
const tsconfigFiles = new Map();
|
|
134
133
|
const tsconfigLinks = [];
|
|
135
134
|
const chains = rootFiles
|
|
@@ -106,9 +106,11 @@ interface LegacyOption {
|
|
|
106
106
|
matches: (value: unknown) => boolean;
|
|
107
107
|
}
|
|
108
108
|
/**
|
|
109
|
-
* Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them
|
|
110
|
-
*
|
|
111
|
-
*
|
|
109
|
+
* Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them.
|
|
110
|
+
* `outFile` and `moduleResolution: classic` are `removedIn: 6` because the
|
|
111
|
+
* TypeScript 6.0 release notes call them removed; `tsc` 6.0.3 itself still
|
|
112
|
+
* accepts both behind `ignoreDeprecations: "6.0"` and warns that they stop
|
|
113
|
+
* functioning in 7.0.
|
|
112
114
|
*/
|
|
113
115
|
export declare const LEGACY_OPTIONS: readonly LegacyOption[];
|
|
114
116
|
/**
|
package/dist/toolchain/rules.js
CHANGED
|
@@ -3,9 +3,11 @@
|
|
|
3
3
|
const NONE = { checked: 0, failures: [] };
|
|
4
4
|
const lower = (value) => typeof value === "string" ? value.toLowerCase() : undefined;
|
|
5
5
|
/**
|
|
6
|
-
* Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them
|
|
7
|
-
*
|
|
8
|
-
*
|
|
6
|
+
* Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them.
|
|
7
|
+
* `outFile` and `moduleResolution: classic` are `removedIn: 6` because the
|
|
8
|
+
* TypeScript 6.0 release notes call them removed; `tsc` 6.0.3 itself still
|
|
9
|
+
* accepts both behind `ignoreDeprecations: "6.0"` and warns that they stop
|
|
10
|
+
* functioning in 7.0.
|
|
9
11
|
*/
|
|
10
12
|
export const LEGACY_OPTIONS = [
|
|
11
13
|
{
|
|
@@ -332,7 +334,7 @@ const gateWiring = {
|
|
|
332
334
|
const script = first === "run" ? second : first;
|
|
333
335
|
if (script !== undefined && !PNPM_BUILTINS.has(script)) {
|
|
334
336
|
checked += 1;
|
|
335
|
-
if (scripts
|
|
337
|
+
if (!Object.hasOwn(scripts, script)) {
|
|
336
338
|
failures.push({
|
|
337
339
|
subject: `${stepsFile ?? ""} step "${step.id}"`,
|
|
338
340
|
message: `runs \`pnpm ${script}\`, but package.json has no "${script}" script`,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@monte3l/groundwork",
|
|
3
|
-
"version": "1.0.0-rc.
|
|
3
|
+
"version": "1.0.0-rc.7",
|
|
4
4
|
"description": "CLI that writes a TypeScript toolchain and Claude Code setup into an empty directory, or -- against an existing project -- read-only surveys it and reports the differences. No prompts, and no network access beyond the package install.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"typescript",
|
|
@@ -82,7 +82,8 @@ default marked "(Recommended)":
|
|
|
82
82
|
|
|
83
83
|
Call one (four questions):
|
|
84
84
|
|
|
85
|
-
1. **Project kind** — library / CLI / frontend or web app / service
|
|
85
|
+
1. **Project kind** — library / CLI / frontend or web app / service /
|
|
86
|
+
Claude Code plugin.
|
|
86
87
|
2. **Runtime target** — Node / browser / both.
|
|
87
88
|
3. **Tests mandatory in the pre-push gate?** — yes (default; matches the
|
|
88
89
|
baseline) / warn only.
|
|
@@ -98,9 +99,13 @@ Call two (one question):
|
|
|
98
99
|
**Adopt mode:** ask the same five questions, but this becomes a
|
|
99
100
|
_confirmation_ round rather than a cold ask. Pre-select each answer from
|
|
100
101
|
Step 0's findings and **show the evidence alongside it** — "library — you
|
|
101
|
-
have an `exports` map and no `bin` field", not just a silent default.
|
|
102
|
+
have an `exports` map and no `bin` field", not just a silent default. When
|
|
103
|
+
`survey.harness.pluginLayout` is set, pre-select **Claude Code plugin** and
|
|
104
|
+
show the manifest and components as the evidence. With no `package.json`
|
|
105
|
+
evidence and no plugin manifest, do not pre-select a kind: ask it cold. The
|
|
102
106
|
user confirms or corrects each one. This is why the CLI's survey deliberately
|
|
103
|
-
never names a `ProjectKind` itself (
|
|
107
|
+
never names a `ProjectKind` itself (the type lives in this plugin's
|
|
108
|
+
`packages/plugin/src/kind-facet-map.ts`, not the CLI): the inference
|
|
104
109
|
happens once, here, visibly, with its reasoning attached — not buried in an
|
|
105
110
|
offline heuristic no one reviews.
|
|
106
111
|
|
|
@@ -138,6 +143,11 @@ user chose. Both modes then settle plugin recommendations. Run `pnpm verify`
|
|
|
138
143
|
(fresh) or the project's own equivalent (adopt) after Round 1's edits, before
|
|
139
144
|
moving to Round 2.
|
|
140
145
|
|
|
146
|
+
**Naming rule for `CLAUDE.md`, in Rounds 1 and 2.** Any text you add that
|
|
147
|
+
names a `.claude/` file uses its full path (`.claude/rules/tests.md`, never
|
|
148
|
+
`tests.md`): the harness grader's `claudemd-refs` check is a literal substring
|
|
149
|
+
match on that path, and fails every rule file `CLAUDE.md` does not name.
|
|
150
|
+
|
|
141
151
|
## Step 4 — Round 2: the guidance pass
|
|
142
152
|
|
|
143
153
|
Invoke both guidance skills in **refresh mode**, in parallel:
|
|
@@ -165,7 +175,7 @@ guard the emitted baseline — broadened to cover common non-baseline
|
|
|
165
175
|
equivalents like `.eslintrc.*`/`jest.config.*`/`.husky/**`). A config file
|
|
166
176
|
that classifies as `uncovered` is a **reportable coverage gap**, exactly the
|
|
167
177
|
adopt-mode analogue of the structural test that guards `templates/core` —
|
|
168
|
-
name it in Step
|
|
178
|
+
name it in Step 7's report rather than silently skipping it.
|
|
169
179
|
|
|
170
180
|
**Applying findings.** A Round 2 finding carrying an allowlisted source URL
|
|
171
181
|
outranks both the baseline and Round 1, and should be applied. Name in your
|
|
@@ -189,7 +199,32 @@ stamped with a `last-verified` date and no real sweep behind it is worse
|
|
|
189
199
|
than an honest `unset` — the next sweep would trust a lie. Report exactly
|
|
190
200
|
which round the customization stopped at.
|
|
191
201
|
|
|
192
|
-
## Step 6 —
|
|
202
|
+
## Step 6 — Final gate
|
|
203
|
+
|
|
204
|
+
After Round 2 (or after Round 1 if Step 5 skipped it), grade what you
|
|
205
|
+
changed. Round 1's check ran before Round 2 edited anything.
|
|
206
|
+
|
|
207
|
+
- **Fresh:** run `pnpm verify` again.
|
|
208
|
+
- **Adopt, the project has `bin/check-harness.mjs`:** run
|
|
209
|
+
`node bin/check-harness.mjs`.
|
|
210
|
+
- **Adopt, no such file, schema 5 or later:** only when **all four** of the
|
|
211
|
+
grader's files are in `stagedBaseline.files` (`bin/check-harness.mjs`,
|
|
212
|
+
`bin/lib/harness-rules.mjs`, `bin/lib/frontmatter.mjs`,
|
|
213
|
+
`bin/lib/report.mjs`; a file the project already has is a conflict and is
|
|
214
|
+
not staged) and `git rev-parse --show-toplevel` run in the project equals the
|
|
215
|
+
project root (the grader grades that git root, so a nested package or a
|
|
216
|
+
directory that is not a git repository would grade the wrong tree or fail).
|
|
217
|
+
The files were hash-checked in Step 0. Copy them without the `.staged`
|
|
218
|
+
suffix to `.groundwork/grade/bin/` (keeping `lib/`), run
|
|
219
|
+
`node .groundwork/grade/bin/check-harness.mjs` from the project root, then
|
|
220
|
+
delete `.groundwork/grade/`. Never write the grader into the project's own
|
|
221
|
+
`bin/`.
|
|
222
|
+
- **Otherwise:** state in Step 7 that the harness was not graded, and why.
|
|
223
|
+
|
|
224
|
+
Fix any structural failure this run introduced. Report one that was already
|
|
225
|
+
there without fixing it unasked.
|
|
226
|
+
|
|
227
|
+
## Step 7 — Report
|
|
193
228
|
|
|
194
229
|
One-line-per-item summary: the five interview answers, what Round 1 changed
|
|
195
230
|
deterministically, what Round 2's two sweeps found and applied (or "skipped
|