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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +20 -5
  2. package/dist/inventory.d.ts +1 -1
  3. package/dist/inventory.js +5 -2
  4. package/dist/report.js +74 -10
  5. package/dist/survey/survey-harness.d.ts +10 -2
  6. package/dist/survey/survey-harness.js +90 -4
  7. package/dist/survey/survey-shape.js +6 -3
  8. package/dist/survey/survey-toolchain.js +7 -9
  9. package/dist/survey/types.d.ts +33 -0
  10. package/dist/toolchain/grade.js +6 -7
  11. package/dist/toolchain/rules.d.ts +5 -3
  12. package/dist/toolchain/rules.js +6 -4
  13. package/package.json +1 -1
  14. package/plugin/skills/customize/SKILL.md +40 -5
  15. package/plugin/skills/customize/step-0-reconcile.md +10 -6
  16. package/plugin/skills/customize/step-3-round-1.md +12 -11
  17. package/plugin/src/domain-map.ts +3 -3
  18. package/plugin/src/kind-facet-map.ts +39 -9
  19. package/plugin/src/pack-map.ts +5 -3
  20. package/plugin/src/plugin-map.ts +29 -7
  21. package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
  22. package/templates/core/.claude/rules/agent-dispatch.md +12 -7
  23. package/templates/core/.claude/rules/src.md +7 -4
  24. package/templates/core/.claude/rules/tests.md +2 -2
  25. package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
  26. package/templates/core/CLAUDE.md +28 -15
  27. package/templates/core/README.md +15 -3
  28. package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
  29. package/templates/core/bin/lint-commit.mjs +215 -10
  30. package/templates/packs/README.md +19 -13
  31. package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +2 -3
  32. package/templates/packs/github/files/.github/workflows/claude.yml +4 -7
  33. package/templates/packs/github/pack.json +1 -1
  34. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
  35. package/templates/packs/harness-extras/pack.json +1 -1
  36. package/templates/packs/publishing/files/.github/workflows/release.yml +22 -36
  37. package/templates/packs/publishing/files/bin/lib/npm-publish-args.mjs +26 -18
  38. package/templates/packs/publishing/files/bin/lib/read-tarball-manifest.mjs +114 -0
  39. package/templates/packs/publishing/files/bin/npm-stage-publish.mjs +214 -0
  40. package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +22 -18
  41. package/templates/packs/publishing/files/tools/release/package.json +10 -0
  42. package/templates/packs/publishing/pack.json +2 -2
  43. package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
  44. package/templates/packs/supply-chain/pack.json +2 -2
  45. package/templates/packs/worktrees/pack.json +1 -1
  46. package/templates/packs/publishing/files/.github/release-tools/package.json +0 -9
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 and writes
11
- only a report (**adopt mode**, which never touches a project file --
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
 
@@ -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 = 5;
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 = 5;
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
- /** Sums every listed pack's declared `budget` -- the "if every pack were installed" delta, not just the ones a user will choose. */
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 = Object.values(grade.rubric).reduce((sum, tally) => sum + tally.checked, 0);
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(`- **Wiring (structural):** ${grade.structural.checked - grade.structural.failed} of ${grade.structural.checked} checks pass.`, `- **Quality (rubric):** ${Math.round(grade.rubricScore * 100)}% over ${rubricChecked} checks -- advisory, never a blocker.`, `- **Drift from the baseline toolchain:** ${conformance.identical} identical, ${conformance.divergent} divergent, ${conformance.absent} absent. ` +
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 = Object.values(grade.rubric).reduce((sum, tally) => sum + tally.checked, 0);
155
- lines.push(`- **Wiring (structural):** ${grade.structural.checked - grade.structural.failed} of ${grade.structural.checked} checks pass.`, `- **Quality (rubric):** ${Math.round(grade.rubricScore * 100)}% over ${rubricChecked} checks -- advisory, never a blocker.`, `- **Drift from the baseline harness:** ${conformance.identical} identical, ${conformance.divergent} divergent, ${conformance.absent} absent. ` +
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 | + all packs | Post-merge (approx.) | Cap |"
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 "+ all packs"
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("", '"+ all packs" sums every pack listed below, not just the ones you choose ' +
218
- 'to install -- see "## Available packs" for per-pack numbers.');
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. Any other read failure throws, naming the path, with the
10
- * original failure as `cause`.
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. Any other read failure throws, naming the path, with the
117
- * original failure as `cause`.
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: packageJson?.["exports"] !== undefined,
160
- hasBinField: packageJson?.["bin"] !== undefined,
161
- hasMainField: packageJson?.["main"] !== undefined,
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 excerpted
8
- * here, never parsed -- see `needsReading` on each -- because this package
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
- const result = {};
185
- for (const [key, value] of Object.entries(scripts)) {
186
- if (typeof value === "string")
187
- result[key] = value;
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
@@ -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 {
@@ -122,14 +122,13 @@ function loadSnapshot(root) {
122
122
  const packageJson = packageRead.ok && isRecord(packageRead.value)
123
123
  ? packageRead.value
124
124
  : undefined;
125
- const scripts = {};
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
- if (isRecord(rawScripts)) {
128
- for (const [name, cmd] of Object.entries(rawScripts)) {
129
- if (typeof cmd === "string")
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
- * (`outFile` and `moduleResolution: classic` already went in 6.0).
111
- * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
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
  /**
@@ -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
- * (`outFile` and `moduleResolution: classic` already went in 6.0).
8
- * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
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[script] === undefined) {
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.5",
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. The
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 (see its own `types.ts`): the inference
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 6's report rather than silently skipping it.
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 — Report
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