@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.
Files changed (61) hide show
  1. package/README.md +20 -5
  2. package/dist/customize-paths.d.ts +51 -15
  3. package/dist/customize-paths.js +32 -13
  4. package/dist/fs-guard.d.ts +2 -2
  5. package/dist/harness/rules.d.ts +2 -1
  6. package/dist/harness/rules.js +3 -1
  7. package/dist/inventory.d.ts +1 -1
  8. package/dist/inventory.js +5 -2
  9. package/dist/plugin.d.ts +12 -12
  10. package/dist/plugin.js +34 -26
  11. package/dist/report.js +74 -10
  12. package/dist/survey/survey-harness.d.ts +10 -2
  13. package/dist/survey/survey-harness.js +90 -4
  14. package/dist/survey/survey-shape.js +6 -3
  15. package/dist/survey/survey-toolchain.js +7 -9
  16. package/dist/survey/types.d.ts +33 -0
  17. package/dist/toolchain/grade.js +6 -7
  18. package/dist/toolchain/rules.d.ts +5 -3
  19. package/dist/toolchain/rules.js +6 -4
  20. package/package.json +1 -1
  21. package/plugin/skills/customize/SKILL.md +73 -408
  22. package/plugin/skills/customize/step-0-reconcile.md +265 -0
  23. package/plugin/skills/customize/step-3-round-1.md +171 -0
  24. package/plugin/src/domain-map.ts +2 -2
  25. package/plugin/src/kind-facet-map.ts +39 -9
  26. package/plugin/src/pack-map.ts +5 -3
  27. package/plugin/src/plugin-map.ts +154 -11
  28. package/templates/core/.claude/agents/Explore.md +1 -1
  29. package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
  30. package/templates/core/.claude/hooks/guard-no-commonjs.mjs +3 -2
  31. package/templates/core/.claude/hooks/inject-decision-gate.mjs +7 -7
  32. package/templates/core/.claude/rules/agent-dispatch.md +12 -7
  33. package/templates/core/.claude/rules/src.md +7 -4
  34. package/templates/core/.claude/rules/tests.md +2 -2
  35. package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
  36. package/templates/core/.claude/skills/triaging-ci/SKILL.md +2 -2
  37. package/templates/core/.claude/skills/writing-commits/SKILL.md +4 -4
  38. package/templates/core/.prettierignore +1 -0
  39. package/templates/core/CLAUDE.md +28 -15
  40. package/templates/core/README.md +15 -3
  41. package/templates/core/_gitignore +1 -0
  42. package/templates/core/bin/check-exports.mjs +5 -3
  43. package/templates/core/bin/lib/harness-rules.mjs +3 -1
  44. package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
  45. package/templates/core/bin/lint-commit.mjs +215 -10
  46. package/templates/core/tsconfig.base.json +10 -6
  47. package/templates/packs/README.md +25 -13
  48. package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +3 -4
  49. package/templates/packs/github/files/.github/workflows/claude.yml +5 -8
  50. package/templates/packs/github/pack.json +1 -1
  51. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
  52. package/templates/packs/harness-extras/files/.claude/hooks/subagent-statusline.mjs +29 -14
  53. package/templates/packs/harness-extras/pack.json +1 -1
  54. package/templates/packs/publishing/files/.github/workflows/release.yml +4 -7
  55. package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +4 -14
  56. package/templates/packs/publishing/pack.json +1 -1
  57. package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
  58. package/templates/packs/quality/pack.json +1 -1
  59. package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
  60. package/templates/packs/supply-chain/pack.json +2 -2
  61. package/templates/packs/worktrees/pack.json +1 -1
@@ -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.4",
3
+ "version": "1.0.0-rc.6",
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",