@monte3l/groundwork 1.0.0-rc.4 → 1.0.0-rc.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -5
- package/dist/customize-paths.d.ts +51 -15
- package/dist/customize-paths.js +32 -13
- package/dist/fs-guard.d.ts +2 -2
- package/dist/harness/rules.d.ts +2 -1
- package/dist/harness/rules.js +3 -1
- package/dist/inventory.d.ts +1 -1
- package/dist/inventory.js +5 -2
- package/dist/plugin.d.ts +12 -12
- package/dist/plugin.js +34 -26
- package/dist/report.js +74 -10
- package/dist/survey/survey-harness.d.ts +10 -2
- package/dist/survey/survey-harness.js +90 -4
- package/dist/survey/survey-shape.js +6 -3
- package/dist/survey/survey-toolchain.js +7 -9
- package/dist/survey/types.d.ts +33 -0
- package/dist/toolchain/grade.js +6 -7
- package/dist/toolchain/rules.d.ts +5 -3
- package/dist/toolchain/rules.js +6 -4
- package/package.json +1 -1
- package/plugin/skills/customize/SKILL.md +73 -408
- package/plugin/skills/customize/step-0-reconcile.md +265 -0
- package/plugin/skills/customize/step-3-round-1.md +171 -0
- package/plugin/src/domain-map.ts +2 -2
- package/plugin/src/kind-facet-map.ts +39 -9
- package/plugin/src/pack-map.ts +5 -3
- package/plugin/src/plugin-map.ts +154 -11
- package/templates/core/.claude/agents/Explore.md +1 -1
- package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
- package/templates/core/.claude/hooks/guard-no-commonjs.mjs +3 -2
- package/templates/core/.claude/hooks/inject-decision-gate.mjs +7 -7
- package/templates/core/.claude/rules/agent-dispatch.md +12 -7
- package/templates/core/.claude/rules/src.md +7 -4
- package/templates/core/.claude/rules/tests.md +2 -2
- package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
- package/templates/core/.claude/skills/triaging-ci/SKILL.md +2 -2
- package/templates/core/.claude/skills/writing-commits/SKILL.md +4 -4
- package/templates/core/.prettierignore +1 -0
- package/templates/core/CLAUDE.md +28 -15
- package/templates/core/README.md +15 -3
- package/templates/core/_gitignore +1 -0
- package/templates/core/bin/check-exports.mjs +5 -3
- package/templates/core/bin/lib/harness-rules.mjs +3 -1
- package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
- package/templates/core/bin/lint-commit.mjs +215 -10
- package/templates/core/tsconfig.base.json +10 -6
- package/templates/packs/README.md +25 -13
- package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +3 -4
- package/templates/packs/github/files/.github/workflows/claude.yml +5 -8
- package/templates/packs/github/pack.json +1 -1
- package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
- package/templates/packs/harness-extras/files/.claude/hooks/subagent-statusline.mjs +29 -14
- package/templates/packs/harness-extras/pack.json +1 -1
- package/templates/packs/publishing/files/.github/workflows/release.yml +4 -7
- package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +4 -14
- package/templates/packs/publishing/pack.json +1 -1
- package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
- package/templates/packs/quality/pack.json +1 -1
- package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
- package/templates/packs/supply-chain/pack.json +2 -2
- package/templates/packs/worktrees/pack.json +1 -1
|
@@ -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.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",
|