docks-kit 0.25.0 → 0.27.0

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/AGENTS.md +12 -10
  2. package/README.md +40 -30
  3. package/cli/dist/docks-kit.js +24701 -0
  4. package/cli/docs/command-guards.md +8 -5
  5. package/cli/docs/install.md +41 -32
  6. package/cli/docs/omp-context.md +1 -1
  7. package/cli/docs/omp-models.md +1 -1
  8. package/cli/docs/overview.md +3 -3
  9. package/cli/docs/platforms.md +8 -8
  10. package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
  11. package/cli/src/agentDocs/bridgeCheck.ts +226 -0
  12. package/cli/src/agentDocs/commands.ts +63 -0
  13. package/cli/src/agentDocs/prTemplate.ts +211 -0
  14. package/cli/src/agentDocs/services.ts +202 -0
  15. package/cli/src/agentDocs/shared.ts +730 -0
  16. package/cli/src/agentDocs/verifySkill.ts +136 -0
  17. package/cli/src/argv.ts +25 -1
  18. package/cli/src/commands/agentDocs.ts +29 -0
  19. package/cli/src/commands/plan.ts +29 -0
  20. package/cli/src/commands/skill.ts +29 -0
  21. package/cli/src/commands/update.ts +90 -66
  22. package/cli/src/engine-native/DESIGN.md +10 -9
  23. package/cli/src/engine-native/os/targets.ts +6 -19
  24. package/cli/src/engine.ts +0 -6
  25. package/cli/src/generated/sotPayload.ts +51 -79
  26. package/cli/src/kitHome.ts +7 -10
  27. package/cli/src/main.ts +12 -4
  28. package/cli/src/plan/bytes.ts +110 -0
  29. package/cli/src/plan/checkout.ts +379 -0
  30. package/cli/src/plan/commands.ts +1192 -0
  31. package/cli/src/plan/github.ts +816 -0
  32. package/cli/src/plan/records.ts +623 -0
  33. package/cli/src/plan/repository.ts +53 -0
  34. package/cli/src/plan/reviews.ts +292 -0
  35. package/cli/src/plan/services.ts +256 -0
  36. package/cli/src/plan/types.ts +164 -0
  37. package/cli/src/skills/commands.ts +142 -0
  38. package/cli/src/skills/config.json +30 -0
  39. package/cli/src/skills/files.ts +74 -0
  40. package/cli/src/skills/frontmatter.ts +148 -0
  41. package/cli/src/skills/guard.ts +366 -0
  42. package/cli/src/skills/kitGate.ts +406 -0
  43. package/cli/src/skills/rubric.ts +143 -0
  44. package/docks-kit +9 -40
  45. package/docks-kit.ps1 +10 -61
  46. package/package.json +10 -8
@@ -0,0 +1,730 @@
1
+ /**
2
+ * Shared parts of the agent-doc checks of agent-first-setup (`agent-first`) and claude-md-migration (`bridge-check`):
3
+ * the repository root, the file listing, the legacy `.claude/` entries, the routing rows of the root AGENTS.md, the
4
+ * nested AGENTS.md nodes, and the durable-doc scan.
5
+ *
6
+ * Each function ports one part of a shell block that the two skills ran before. A port keeps the semantics of that
7
+ * block: git pathspecs, POSIX `[[:space:]]`, the leftmost-longest matches of awk, and byte order where the block
8
+ * sorted with `sort` or a glob.
9
+ *
10
+ * A listing or a read that cannot finish fails with CheckError after it writes the cause to stderr; `guarded` turns
11
+ * that error into the ERROR line of the caller.
12
+ */
13
+ import path from "node:path";
14
+
15
+ import { Effect, Schema } from "effect";
16
+
17
+ import type { FileError, SpawnError } from "../plan/types";
18
+ import {
19
+ AgentDocsFiles,
20
+ AgentDocsGit,
21
+ errorDetail,
22
+ type FolderEntry,
23
+ writeStderr,
24
+ } from "./services";
25
+
26
+ // The folder names that each skill skips when it walks a folder outside git.
27
+ export const AGENT_FIRST_PRUNE: ReadonlyArray<string> = [".git", "node_modules", "vendor"];
28
+ export const BRIDGE_PRUNE: ReadonlyArray<string> = [
29
+ ".git",
30
+ "node_modules",
31
+ "vendor",
32
+ "dist",
33
+ "build",
34
+ "out",
35
+ "target",
36
+ ".next",
37
+ ];
38
+
39
+ // POSIX `[[:space:]]` in the C locale; JS `\s` would also match Unicode spaces.
40
+ export const SPACE = " \\t\\n\\v\\f\\r";
41
+ const ROOT_AGENTS = "AGENTS.md";
42
+ // A package under node_modules is not part of this repository.
43
+ export const EXCLUDE_NODE_MODULES = ":(exclude,glob)**/node_modules/**";
44
+ const LISTING_FAILED = "file listing failed (see the message above)";
45
+ // The errno codes that mean "no file is there", as `test -f` sees it. Any other code means that an entry is there,
46
+ // but the check cannot read it.
47
+ const MISSING_CODES: ReadonlySet<string | undefined> = new Set(["ENOENT", "ENOTDIR"]);
48
+ const FENCE = new RegExp(`^[${SPACE}]*\`\`\``, "u");
49
+ export const CODE_SPAN = /`[^`]*`/gu;
50
+
51
+ /**
52
+ * awk's tolower and grep -i in the C locale change only ASCII letters; String#toLowerCase alone would also fold
53
+ * letters such as the Kelvin sign into `k`.
54
+ */
55
+ export const asciiLower = (text: string): string =>
56
+ text.replace(/[A-Z]+/gu, (letters) => letters.toLowerCase());
57
+
58
+ /**
59
+ * A check that cannot finish. Its cause is already on stderr; `message` completes the ERROR line of the caller, for
60
+ * example `cannot read docs/AGENTS.md`.
61
+ */
62
+ export class CheckError extends Schema.TaggedError<CheckError, { readonly brand: unique symbol }>()(
63
+ "CheckError",
64
+ {
65
+ message: Schema.String,
66
+ },
67
+ ) {}
68
+
69
+ /** Arguments that a helper does not accept. The command edge prints `usage` on stderr and exits 1. */
70
+ export class UsageError extends Schema.TaggedError<UsageError, { readonly brand: unique symbol }>()(
71
+ "UsageError",
72
+ {
73
+ usage: Schema.String,
74
+ },
75
+ ) {}
76
+
77
+ /** The lines of a check that can fail. A SpawnError, the runtime refusing git's arguments, ends the command. */
78
+ export type CheckLines<R> = Effect.Effect<ReadonlyArray<string>, CheckError | SpawnError, R>;
79
+
80
+ /**
81
+ * The lines of one check, or one `ERROR <label> <message>` line in their place when the check fails with CheckError.
82
+ * A failed check is never a pass, so it must not print a partial result.
83
+ */
84
+ export const guarded = <R>(
85
+ label: string,
86
+ lines: CheckLines<R>,
87
+ ): Effect.Effect<ReadonlyArray<string>, SpawnError, R> =>
88
+ Effect.catchTag(lines, "CheckError", (error) =>
89
+ Effect.succeed([`ERROR ${label} ${error.message}`]),
90
+ );
91
+
92
+ /** The lines of `check` for each item; an item that cannot be read gives its ERROR line. */
93
+ export const eachGuarded = <A, R>(
94
+ check: string,
95
+ items: ReadonlyArray<A>,
96
+ lines: (item: A) => CheckLines<R>,
97
+ ): Effect.Effect<ReadonlyArray<string>, SpawnError, R> =>
98
+ Effect.map(
99
+ Effect.forEach(items, (item) => guarded(check, lines(item))),
100
+ (all) => all.flat(),
101
+ );
102
+
103
+ const listingError = Effect.fn("agentDocs.listingError")(function* (
104
+ folder: string,
105
+ error: FileError,
106
+ ) {
107
+ yield* writeStderr(
108
+ `agent-docs: cannot list the folder ${folder} (${errorDetail(error)}); make it readable and run the check again\n`,
109
+ );
110
+ return yield* new CheckError({ message: LISTING_FAILED });
111
+ });
112
+
113
+ /**
114
+ * `sort` and shell globs in the C locale compare bytes; String#localeCompare and the default sort compare UTF-16 code
115
+ * units, which differ above the Basic Multilingual Plane.
116
+ */
117
+ export const byteOrder = (a: string, b: string): number =>
118
+ Buffer.compare(Buffer.from(a), Buffer.from(b));
119
+
120
+ // stat follows symlinks, as `test -e`, `test -f`, and `test -d` do.
121
+ export const isFile = Effect.fn("agentDocs.isFile")(function* (file: string) {
122
+ const files = yield* AgentDocsFiles;
123
+ return (yield* files.stat(file)) === "file";
124
+ });
125
+
126
+ export const isFolder = Effect.fn("agentDocs.isFolder")(function* (file: string) {
127
+ const files = yield* AgentDocsFiles;
128
+ return (yield* files.stat(file)) === "directory";
129
+ });
130
+
131
+ /**
132
+ * The entries of `folder`, through a symlink too, as a glob sees them; none when no folder is there. A folder that is
133
+ * there but cannot be listed fails with CheckError.
134
+ */
135
+ export const readFolder = Effect.fn("agentDocs.readFolder")(function* (folder: string) {
136
+ const files = yield* AgentDocsFiles;
137
+ return yield* files
138
+ .readFolder(folder)
139
+ .pipe(
140
+ Effect.catchTag("FileError", (error) =>
141
+ MISSING_CODES.has(error.code)
142
+ ? Effect.succeed<ReadonlyArray<FolderEntry>>([])
143
+ : listingError(folder, error),
144
+ ),
145
+ );
146
+ });
147
+
148
+ /**
149
+ * The entries of `folder` as `find <folder> -mindepth 1 -maxdepth 1` lists them, dot names included, sorted by byte
150
+ * order of the name. None when `folder` is a symlink, because find does not follow a symlink given as its starting
151
+ * point.
152
+ */
153
+ export const findEntries = Effect.fn("agentDocs.findEntries")(function* (folder: string) {
154
+ const files = yield* AgentDocsFiles;
155
+ if (yield* files.isSymlink(folder)) return [];
156
+ return [...(yield* readFolder(folder))].sort((a, b) => byteOrder(a.name, b.name));
157
+ });
158
+
159
+ const CLAUDE_FOLDER = ".claude";
160
+ const CLAUDE_SKILLS = ".claude/skills";
161
+ const CLAUDE_AGENTS = ".claude/agents";
162
+ const CLAUDE_SETTINGS: ReadonlyArray<string> = [
163
+ ".claude/settings.json",
164
+ ".claude/settings.local.json",
165
+ ];
166
+ // The `.claude/` entries that have their own line; each other entry is a `legacy other:` entry.
167
+ const CLAUDE_OWN_LINES: ReadonlySet<string> = new Set([
168
+ "CLAUDE.md",
169
+ "skills",
170
+ "agents",
171
+ "settings.json",
172
+ "settings.local.json",
173
+ ]);
174
+
175
+ /** True when the absolute path `inner` is `outer` or below it. */
176
+ function isWithin(outer: string, inner: string): boolean {
177
+ const relative = path.relative(outer, inner);
178
+ return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
179
+ }
180
+
181
+ /**
182
+ * The link target of `file` as read, when `file` is a symlink whose real path is outside the current folder (the
183
+ * repository root); else null. A dangling link resolves its target from the real folder of the link. A link that
184
+ * cannot be read fails with CheckError.
185
+ */
186
+ const externalTarget = Effect.fn("agentDocs.externalTarget")(function* (file: string) {
187
+ const files = yield* AgentDocsFiles;
188
+ if (!(yield* files.isSymlink(file))) return null;
189
+ const resolved = Effect.gen(function* () {
190
+ const target = yield* files.readLink(file);
191
+ const real =
192
+ (yield* files.stat(file)) === undefined
193
+ ? path.resolve(yield* files.realPath(path.dirname(file)), target)
194
+ : yield* files.realPath(file);
195
+ return isWithin(yield* files.realPath("."), real) ? null : target;
196
+ });
197
+ return yield* resolved.pipe(Effect.catchTag("FileError", (error) => listingError(file, error)));
198
+ });
199
+
200
+ /**
201
+ * True when the `.claude/skills` folder of the root is no link to a place outside the repository, and no `.claude`
202
+ * link above it is either. The checks then may list its entries.
203
+ */
204
+ export const claudeSkillsInRepository = Effect.fn("agentDocs.claudeSkillsInRepository")(
205
+ function* () {
206
+ return (
207
+ (yield* externalTarget(CLAUDE_FOLDER)) === null &&
208
+ (yield* externalTarget(CLAUDE_SKILLS)) === null
209
+ );
210
+ },
211
+ );
212
+
213
+ export interface ExternalLink {
214
+ readonly path: string;
215
+ readonly target: string;
216
+ }
217
+
218
+ export interface LegacyClaudeEntries {
219
+ readonly external: ReadonlyArray<ExternalLink>;
220
+ readonly skills: string | null;
221
+ readonly agents: ReadonlyArray<string>;
222
+ readonly settings: ReadonlyArray<string>;
223
+ readonly others: ReadonlyArray<string>;
224
+ }
225
+
226
+ /**
227
+ * The legacy Claude Code entries of the `.claude/` folder in the current folder (the repository root): `external`,
228
+ * each of `.claude`, `.claude/skills`, and `.claude/agents` that is a symlink to a place outside the repository, as
229
+ * { path, target }, with no entry below it; the skills folder; each agent file that `.claude/agents/*.md` expands to
230
+ * (no dot names, in byte order); each settings file; and `others`, each other entry of `.claude/` (dot names too, in
231
+ * byte order). Fails with CheckError when `.claude` or `.claude/agents` is there but cannot be listed.
232
+ */
233
+ export const legacyClaudeEntries = Effect.fn("agentDocs.legacyClaudeEntries")(function* () {
234
+ const external: Array<ExternalLink> = [];
235
+ const outside = Effect.fn("agentDocs.legacyClaudeEntries.outside")(function* (folder: string) {
236
+ const target = yield* externalTarget(folder);
237
+ if (target !== null) external.push({ path: folder, target });
238
+ return target !== null;
239
+ });
240
+ if (yield* outside(CLAUDE_FOLDER)) {
241
+ const entries: LegacyClaudeEntries = {
242
+ external,
243
+ skills: null,
244
+ agents: [],
245
+ settings: [],
246
+ others: [],
247
+ };
248
+ return entries;
249
+ }
250
+ const skillsOutside = yield* outside(CLAUDE_SKILLS);
251
+ const agentsOutside = yield* outside(CLAUDE_AGENTS);
252
+ const others = (yield* readFolder(CLAUDE_FOLDER))
253
+ .map((entry) => entry.name)
254
+ .filter((name) => !CLAUDE_OWN_LINES.has(name))
255
+ .sort(byteOrder)
256
+ .map((name) => `${CLAUDE_FOLDER}/${name}`);
257
+ const agents = agentsOutside
258
+ ? []
259
+ : yield* Effect.filter(
260
+ (yield* readFolder(CLAUDE_AGENTS))
261
+ .map((entry) => entry.name)
262
+ .filter((name) => !name.startsWith(".") && name.endsWith(".md"))
263
+ .sort(byteOrder)
264
+ .map((name) => `${CLAUDE_AGENTS}/${name}`),
265
+ (file) => isFile(file),
266
+ );
267
+ const entries: LegacyClaudeEntries = {
268
+ external,
269
+ skills: !skillsOutside && (yield* isFolder(CLAUDE_SKILLS)) ? CLAUDE_SKILLS : null,
270
+ agents,
271
+ settings: yield* Effect.filter(CLAUDE_SETTINGS, (file) => isFile(file)),
272
+ others,
273
+ };
274
+ return entries;
275
+ });
276
+
277
+ /**
278
+ * The `legacy external:`, `legacy skills:`, `legacy agents:`, `legacy settings:`, and `legacy other:` lines of
279
+ * legacyClaudeEntries.
280
+ */
281
+ export const legacyClaudeLines = Effect.fn("agentDocs.legacyClaudeLines")(function* () {
282
+ const { external, skills, agents, settings, others } = yield* legacyClaudeEntries();
283
+ const lines: ReadonlyArray<string> = [
284
+ ...external.map((link) => `legacy external: ${link.path} -> ${link.target}`),
285
+ ...(skills === null ? [] : [`legacy skills: ${skills}`]),
286
+ ...agents.map((agent) => `legacy agents: ${agent}`),
287
+ ...settings.map((file) => `legacy settings: ${file}`),
288
+ ...others.map((entry) => `legacy other: ${entry}`),
289
+ ];
290
+ return lines;
291
+ });
292
+
293
+ // The root context files that omp can load, and the root personal file.
294
+ export const ROOT_CONTEXT_FILES: ReadonlyArray<string> = ["CLAUDE.md", ".claude/CLAUDE.md"];
295
+ export const ROOT_PERSONAL_FILES: ReadonlyArray<string> = ["CLAUDE.local.md"];
296
+
297
+ /**
298
+ * `files` and each of the root files `names` that is a file (a symlink to a file too), unique and in byte order. A
299
+ * git listing skips an ignored file, but omp still loads an ignored CLAUDE.md or .claude/CLAUDE.md. A `.claude` link
300
+ * to a place outside the repository adds no file. A `.claude` link that cannot be read fails with CheckError.
301
+ */
302
+ export const withRootFiles = Effect.fn("agentDocs.withRootFiles")(function* (
303
+ files: ReadonlyArray<string>,
304
+ names: ReadonlyArray<string>,
305
+ ) {
306
+ const claudeOutside = (yield* externalTarget(CLAUDE_FOLDER)) !== null;
307
+ const found = yield* Effect.filter(names, (name) =>
308
+ Effect.map(
309
+ isFile(name),
310
+ (file) => file && !(claudeOutside && name.startsWith(`${CLAUDE_FOLDER}/`)),
311
+ ),
312
+ );
313
+ return [...new Set([...files, ...found])].sort(byteOrder);
314
+ });
315
+
316
+ // The most symlinks that one chain follows; Linux stops after 40 too, so a longer chain or a loop resolves to no file.
317
+ const MAX_LINK_HOPS = 40;
318
+
319
+ /**
320
+ * `file` as an absolute path with the real path of its folder, so that two paths to one entry through folder
321
+ * symlinks compare equal; the last part stays as is, because it may be a symlink. Null when the folder cannot be
322
+ * resolved.
323
+ */
324
+ const canonical = Effect.fn("agentDocs.canonical")(function* (file: string) {
325
+ const files = yield* AgentDocsFiles;
326
+ return yield* files.realPath(path.dirname(path.resolve(file))).pipe(
327
+ Effect.map((folder) => path.join(folder, path.basename(file))),
328
+ Effect.catchTag("FileError", () => Effect.succeed(null)),
329
+ );
330
+ });
331
+
332
+ /**
333
+ * The canonical path that the symlink `link`, itself a canonical path, points to. The kernel walks the target part
334
+ * by part, so a `..` after a folder symlink leaves the target of that symlink: `alias/..` with `alias -> nested/sub`
335
+ * is nested. Thus the target joins the folder of the link as a string, and only its real parent folder gets the base
336
+ * name; path.resolve would drop `alias/..` before any symlink is read. Fails when a part cannot be resolved.
337
+ */
338
+ const linkTarget = Effect.fn("agentDocs.linkTarget")(function* (link: string) {
339
+ const files = yield* AgentDocsFiles;
340
+ const target = yield* files.readLink(link);
341
+ const joined = path.isAbsolute(target) ? target : `${path.dirname(link)}/${target}`;
342
+ const cut = joined.lastIndexOf("/");
343
+ return path.join(yield* files.realPathNative(joined.slice(0, cut) || "/"), joined.slice(cut + 1));
344
+ });
345
+
346
+ /**
347
+ * The canonical paths that the symlink chain of `file` reaches, hop by hop, as the kernel resolves them. The chain
348
+ * stops at an entry that is no symlink or cannot be read, or after MAX_LINK_HOPS.
349
+ */
350
+ const linkChain = Effect.fn("agentDocs.linkChain")(function* (file: string) {
351
+ const files = yield* AgentDocsFiles;
352
+ const chain: Array<string> = [];
353
+ let current = yield* canonical(file);
354
+ while (current !== null && chain.length < MAX_LINK_HOPS && (yield* files.isSymlink(current))) {
355
+ const next = yield* linkTarget(current).pipe(
356
+ Effect.catchTag("FileError", () => Effect.succeed(null)),
357
+ );
358
+ if (next === null) break;
359
+ current = next;
360
+ chain.push(current);
361
+ }
362
+ return chain;
363
+ });
364
+
365
+ /**
366
+ * True when `file`, a CLAUDE.md or a .claude/CLAUDE.md, is a symlink whose own chain reaches the AGENTS.md path of
367
+ * its folder (for a .claude/CLAUDE.md, of the folder above), and that AGENTS.md is a file. Such a link holds no text
368
+ * of its own, so there is nothing to migrate. A CLAUDE.md that the AGENTS.md links to is no such link: its removal
369
+ * would leave the AGENTS.md dangling. No separate test of the chain of the AGENTS.md is needed for that: each hop
370
+ * follows from its canonical path alone, so a chain from `file` through the AGENTS.md and a chain from the AGENTS.md
371
+ * back to `file` make a loop of symlinks, and then the AGENTS.md resolves to no file.
372
+ */
373
+ export const isAgentsLink = Effect.fn("agentDocs.isAgentsLink")(function* (file: string) {
374
+ const files = yield* AgentDocsFiles;
375
+ if (!(yield* files.isSymlink(file))) return false;
376
+ let folder = path.posix.dirname(file);
377
+ if (path.posix.basename(folder) === CLAUDE_FOLDER) folder = path.posix.dirname(folder);
378
+ const agents = yield* canonical(path.resolve(folder, ROOT_AGENTS));
379
+ return agents !== null && (yield* isFile(agents)) && (yield* linkChain(file)).includes(agents);
380
+ });
381
+
382
+ /**
383
+ * The text of a file, or null when no file is there; grep and awk then fail the same way. A file that is there but
384
+ * cannot be read fails with CheckError, because its text is unknown. `latin1` gives one character per byte, as awk
385
+ * and grep read in the C locale.
386
+ */
387
+ export const readText = Effect.fn("agentDocs.readText")(function* (
388
+ file: string,
389
+ encoding: "utf8" | "latin1" = "utf8",
390
+ ) {
391
+ const files = yield* AgentDocsFiles;
392
+ return yield* files.readFile(file, encoding).pipe(
393
+ Effect.catchTag("FileError", (error) => {
394
+ if (MISSING_CODES.has(error.code)) return Effect.succeed(null);
395
+ return writeStderr(
396
+ `agent-docs: cannot read ${file} (${errorDetail(error)}); make it readable and run the check again\n`,
397
+ ).pipe(Effect.andThen(new CheckError({ message: `cannot read ${file}` })));
398
+ }),
399
+ );
400
+ });
401
+
402
+ /** The records that awk and grep read: one per `\n`, and a last line without `\n` counts too. */
403
+ export function textLines(text: string): Array<string> {
404
+ const lines = text.split("\n");
405
+ if (lines.at(-1) === "") lines.pop();
406
+ return lines;
407
+ }
408
+
409
+ /**
410
+ * The lines outside fenced blocks as [lineNumber, line], numbered from 1 as awk's NR. A line that opens or closes a
411
+ * fence is no prose line.
412
+ */
413
+ export function proseLines(text: string): Array<readonly [number, string]> {
414
+ const prose: Array<readonly [number, string]> = [];
415
+ let inFence = false;
416
+ textLines(text).forEach((line, index) => {
417
+ if (FENCE.test(line)) inFence = !inFence;
418
+ else if (!inFence) prose.push([index + 1, line]);
419
+ });
420
+ return prose;
421
+ }
422
+
423
+ /**
424
+ * The output of `git rev-parse --show-toplevel`, or null outside git. The skill blocks sent git's message to
425
+ * /dev/null here, because outside git is an expected answer, not an error.
426
+ */
427
+ export const repositoryRoot = Effect.fn("agentDocs.repositoryRoot")(function* () {
428
+ const git = yield* AgentDocsGit;
429
+ const result = yield* git.run(["rev-parse", "--show-toplevel"]);
430
+ if (result.error !== undefined || result.status !== 0) return null;
431
+ return result.stdout.replace(/\n+$/u, "");
432
+ });
433
+
434
+ /**
435
+ * `git ls-files -co [--exclude-standard] -- <pathspecs>` in `root`. `-z` ends each path with a NUL and prints it raw;
436
+ * without it, git quotes a path with a byte above ASCII. A failed or cut-off listing fails with CheckError, because
437
+ * an empty listing would read as a pass.
438
+ */
439
+ const gitFiles = Effect.fn("agentDocs.gitFiles")(function* (
440
+ root: string,
441
+ pathspecs: ReadonlyArray<string>,
442
+ excludeStandard: boolean,
443
+ ) {
444
+ const git = yield* AgentDocsGit;
445
+ const args = ["-c", "core.quotePath=false", "ls-files", "-z", "-co"];
446
+ if (excludeStandard) args.push("--exclude-standard");
447
+ args.push("--", ...pathspecs);
448
+ const result = yield* git.run(args, root);
449
+ if (result.error !== undefined) {
450
+ yield* writeStderr(
451
+ `agent-docs: git ls-files failed (${result.error.message}); fix the cause and run the check again\n`,
452
+ );
453
+ return yield* new CheckError({ message: LISTING_FAILED });
454
+ }
455
+ yield* writeStderr(result.stderr);
456
+ if (result.status !== 0) {
457
+ const end =
458
+ result.status === null
459
+ ? `the signal ${String(result.signal)}`
460
+ : `the status ${String(result.status)}`;
461
+ yield* writeStderr(
462
+ `agent-docs: git ls-files stopped with ${end}; fix the cause and run the check again\n`,
463
+ );
464
+ return yield* new CheckError({ message: LISTING_FAILED });
465
+ }
466
+ const files = result.stdout.split("\0");
467
+ // The NUL after the last path leaves an empty string at the end, as an empty listing does.
468
+ files.pop();
469
+ return files;
470
+ });
471
+
472
+ /**
473
+ * A git glob pattern as a regular expression over the whole path. Supports `**\/`, `/**\/`, `/**`, `*`, and `?`,
474
+ * which are all the forms the two skills use; any other character matches itself.
475
+ */
476
+ function globPattern(glob: string): RegExp {
477
+ let source = "";
478
+ for (let i = 0; i < glob.length; i += 1) {
479
+ if (glob.startsWith("**/", i) && (i === 0 || glob[i - 1] === "/")) {
480
+ source += "(?:.*/)?";
481
+ i += 2;
482
+ } else if (glob.startsWith("/**", i) && i + 3 === glob.length) {
483
+ source += "/.*";
484
+ i += 2;
485
+ } else if (glob[i] === "*") source += "[^/]*";
486
+ else if (glob[i] === "?") source += "[^/]";
487
+ else source += (glob[i] ?? "").replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
488
+ }
489
+ return new RegExp(`^${source}$`, "u");
490
+ }
491
+
492
+ interface Pathspec {
493
+ readonly exclude: boolean;
494
+ readonly pattern: RegExp;
495
+ }
496
+
497
+ /** A `:(glob)` or `:(exclude,glob)` pathspec as { exclude, pattern }. */
498
+ function parsePathspec(pathspec: string): Pathspec {
499
+ const parts = /^:\(([^)]*)\)(.*)$/u.exec(pathspec);
500
+ const magic = new Set(parts?.[1]?.split(","));
501
+ if (
502
+ !parts ||
503
+ !magic.has("glob") ||
504
+ ![...magic].every((word) => word === "glob" || word === "exclude")
505
+ ) {
506
+ throw new Error(
507
+ `agent-docs: the tree walk supports only :(glob) and :(exclude,glob) pathspecs, not ${pathspec}`,
508
+ );
509
+ }
510
+ return { exclude: magic.has("exclude"), pattern: globPattern(parts[2] ?? "") };
511
+ }
512
+
513
+ interface WalkOptions {
514
+ readonly prune: ReadonlyArray<string>;
515
+ readonly filesOnly: boolean;
516
+ }
517
+
518
+ /**
519
+ * Every entry below `folder` that is no folder, as a path relative to `root`; with `filesOnly`, only the regular
520
+ * files, as `find -type f` lists them. A folder named in `prune` is skipped at any depth, as `find ... -prune` does; a
521
+ * symlink to a folder is not followed, as find does not follow it. A folder that cannot be listed fails with
522
+ * CheckError.
523
+ */
524
+ const walkEntries: (
525
+ root: string,
526
+ folder: string,
527
+ options: WalkOptions,
528
+ found: Array<string>,
529
+ ) => Effect.Effect<void, CheckError, AgentDocsFiles> = Effect.fn("agentDocs.walkEntries")(
530
+ function* (root: string, folder: string, options: WalkOptions, found: Array<string>) {
531
+ const files = yield* AgentDocsFiles;
532
+ const entries = yield* files
533
+ .readFolder(path.join(root, folder))
534
+ .pipe(Effect.catchTag("FileError", (error) => listingError(folder || ".", error)));
535
+ for (const entry of entries) {
536
+ const relative = folder === "" ? entry.name : `${folder}/${entry.name}`;
537
+ if (entry.kind === "directory") {
538
+ if (!options.prune.includes(entry.name)) yield* walkEntries(root, relative, options, found);
539
+ } else if (!options.filesOnly || entry.kind === "file") found.push(relative);
540
+ }
541
+ },
542
+ );
543
+
544
+ const walkFiles = Effect.fn("agentDocs.walkFiles")(function* (
545
+ root: string,
546
+ pathspecs: ReadonlyArray<string>,
547
+ options: WalkOptions,
548
+ ) {
549
+ const specs = pathspecs.map(parsePathspec);
550
+ const includes = specs.filter((spec) => !spec.exclude);
551
+ const excludes = specs.filter((spec) => spec.exclude);
552
+ const found: Array<string> = [];
553
+ yield* walkEntries(root, "", options, found);
554
+ return found
555
+ .filter((file) => includes.some((spec) => spec.pattern.test(file)))
556
+ .filter((file) => !excludes.some((spec) => spec.pattern.test(file)))
557
+ .sort(byteOrder);
558
+ });
559
+
560
+ /** The listing of one repository: its root, the folders the walk skips, and whether git answers for it. */
561
+ export interface Listing {
562
+ readonly root: string;
563
+ readonly prune: ReadonlyArray<string>;
564
+ readonly inGit: boolean;
565
+ }
566
+
567
+ export interface ListFilesOptions extends Listing {
568
+ readonly pathspecs: ReadonlyArray<string>;
569
+ readonly excludeStandard?: boolean;
570
+ readonly filesOnly?: boolean;
571
+ }
572
+
573
+ /** The paths of one listing; a listing that cannot finish fails with CheckError. */
574
+ export type FileListing = Effect.Effect<
575
+ ReadonlyArray<string>,
576
+ CheckError | SpawnError,
577
+ AgentDocsFiles | AgentDocsGit
578
+ >;
579
+
580
+ /**
581
+ * The files that match git `pathspecs`, as paths relative to `root`. Inside git, the lines of
582
+ * `git ls-files -co [--exclude-standard] -- <pathspecs>` run in `root`; outside git, a walk of `root` that skips each
583
+ * folder named in `prune`, sorted by byte order. `filesOnly` keeps only regular files in the walk. A listing that
584
+ * fails fails with CheckError.
585
+ */
586
+ export const listFiles = ({
587
+ root,
588
+ pathspecs,
589
+ excludeStandard = false,
590
+ prune,
591
+ inGit,
592
+ filesOnly = false,
593
+ }: ListFilesOptions): FileListing =>
594
+ inGit
595
+ ? gitFiles(root, pathspecs, excludeStandard)
596
+ : walkFiles(root, pathspecs, { prune, filesOnly });
597
+
598
+ /** Every AGENTS.md, the root one included. One under node_modules belongs to a package, not to this repository. */
599
+ export const agentsDocs = (listing: Listing): FileListing =>
600
+ listFiles({
601
+ ...listing,
602
+ pathspecs: [`:(glob)**/${ROOT_AGENTS}`, EXCLUDE_NODE_MODULES],
603
+ excludeStandard: true,
604
+ });
605
+
606
+ /** Every AGENTS.md below the root: the nodes that the root table must route. */
607
+ export const nestedNodes = (listing: Listing): FileListing =>
608
+ Effect.map(agentsDocs(listing), (files) => files.filter((file) => file !== ROOT_AGENTS));
609
+
610
+ const TABLE_LINE = new RegExp(`^[${SPACE}]*\\|`, "u");
611
+ const CELL_SPACE = new RegExp(`^[${SPACE}]+|[${SPACE}]+$`, "gu");
612
+ const ROUTE_CELL = /^`@?[^` ]*AGENTS\.md`$/u;
613
+
614
+ /**
615
+ * The routes of a root AGENTS.md: each table line whose first cell is `<dir>/AGENTS.md` in backticks, with a leading
616
+ * `@` and then a leading `./` stripped. Unique, in byte order.
617
+ */
618
+ export function routingRows(agentsMdText: string): Array<string> {
619
+ const routes = new Set<string>();
620
+ for (const line of textLines(agentsMdText)) {
621
+ if (!TABLE_LINE.test(line)) continue;
622
+ const cell = (line.split("|")[1] ?? "").replace(CELL_SPACE, "");
623
+ if (ROUTE_CELL.test(cell))
624
+ routes.add(cell.replaceAll("`", "").replace(/^@/u, "").replace(/^\.\//u, ""));
625
+ }
626
+ return [...routes].sort(byteOrder);
627
+ }
628
+
629
+ // Join without path.join, which would turn `a/../b` into `b`: the shell resolves each part, so `test -f a/../b`
630
+ // fails when `a` is missing.
631
+ const fromRoot = (root: string, file: string): string =>
632
+ path.isAbsolute(file) ? file : `${root}/${file}`;
633
+
634
+ /**
635
+ * The routing gaps of the repository at `listing.root`: each node that no row of the root AGENTS.md routes, and each
636
+ * route whose file does not exist.
637
+ */
638
+ /** The routing gaps of a repository. */
639
+ export interface RoutingGaps {
640
+ readonly unroutedNodes: ReadonlyArray<string>;
641
+ readonly deadRoutes: ReadonlyArray<string>;
642
+ }
643
+
644
+ export const routingGaps = Effect.fn("agentDocs.routingGaps")(function* (listing: Listing) {
645
+ const rootText = yield* readText(fromRoot(listing.root, ROOT_AGENTS));
646
+ const routes = rootText === null ? [] : routingRows(rootText);
647
+ const gaps: RoutingGaps = {
648
+ unroutedNodes: (yield* nestedNodes(listing)).filter((node) => !routes.includes(node)),
649
+ deadRoutes: yield* Effect.filter(routes, (route) =>
650
+ Effect.map(isFile(fromRoot(listing.root, route)), (file) => !file),
651
+ ),
652
+ };
653
+ return gaps;
654
+ });
655
+
656
+ // awk reads bytes, so a curly quote is three characters here, and `[^”]` excludes each of the three bytes of `”`,
657
+ // as it does in awk.
658
+ const latin1 = (text: string): string => Buffer.from(text, "utf8").toString("latin1");
659
+ const URL_TEXT = /https?:\/\/[^ )>]*/gu;
660
+ const QUOTED = new RegExp(`"[^"]*"|${latin1("“")}[^${latin1("”")}]*${latin1("”")}`, "gu");
661
+ const STEP_NUMBER = /(phase|step|tier)[ -]?[0-9]+/gu;
662
+ const LINE_ANCHOR = /[A-Za-z0-9_./-]+\.[A-Za-z]+:[0-9]+/u;
663
+ const TIME_RELATIVE = /(^|[^a-z])(currently|as of|now has|recently)([^a-z]|$)/u;
664
+ const BARE_COUNT =
665
+ /(^|[^0-9.])[0-9]+ (skills|nodes|files|tests|tables|tabs|commands|agents|plugins|rules)([^a-z]|$)/u;
666
+
667
+ /** The `path:line` anchors of one line, each without its `:line`. */
668
+ function lineAnchors(text: string): Array<string> {
669
+ const anchors: Array<string> = [];
670
+ let rest = text;
671
+ for (let match = LINE_ANCHOR.exec(rest); match !== null; match = LINE_ANCHOR.exec(rest)) {
672
+ anchors.push(match[0].replace(/:[0-9]+$/u, ""));
673
+ rest = rest.slice(match.index + match[0].length);
674
+ }
675
+ return anchors;
676
+ }
677
+
678
+ /**
679
+ * A line anchor counts only when its path exists from the repository root (the current folder) or from the folder of
680
+ * the file, so a fictional example path passes.
681
+ */
682
+ const anchorExists = Effect.fn("agentDocs.anchorExists")(function* (anchor: string, file: string) {
683
+ const files = yield* AgentDocsFiles;
684
+ return (
685
+ (yield* files.exists(anchor)) || (yield* files.exists(`${path.posix.dirname(file)}/${anchor}`))
686
+ );
687
+ });
688
+
689
+ const scanLine = Effect.fn("agentDocs.scanLine")(function* (
690
+ file: string,
691
+ number: number,
692
+ line: string,
693
+ label: string,
694
+ ) {
695
+ const withoutUrls = line.replace(URL_TEXT, "");
696
+ const prose = asciiLower(withoutUrls.replace(CODE_SPAN, "").replace(QUOTED, "")).replace(
697
+ STEP_NUMBER,
698
+ "",
699
+ );
700
+ const findings = (yield* Effect.filter(lineAnchors(withoutUrls), (anchor) =>
701
+ anchorExists(anchor, file),
702
+ )).map((anchor) => `${label} line-anchor ${file}:${number} (${anchor} exists)`);
703
+ if (TIME_RELATIVE.test(prose)) findings.push(`${label} time-relative ${file}:${number}`);
704
+ if (!prose.includes("verify:") && BARE_COUNT.test(prose))
705
+ findings.push(`${label} bare-count ${file}:${number}`);
706
+ return findings;
707
+ });
708
+
709
+ /**
710
+ * The durable-doc scan: time-relative phrases, bare counts, and line anchors whose path exists. Fenced blocks and
711
+ * URLs are skipped everywhere; code spans and quoted text are skipped for the time and count rules only, so a line
712
+ * anchor in backticks still counts. `findingLabel` starts each line: `FINDING C5` for agent-first-setup, `VOLATILE`
713
+ * for claude-md-migration. A file that cannot be read gives `ERROR <errorLabel> cannot read <file>` in place of its
714
+ * lines; a listed file that is gone gives no line, as awk prints none for it. Paths are relative to the current
715
+ * folder.
716
+ */
717
+ export const durableDocScan = (
718
+ files: ReadonlyArray<string>,
719
+ labels: { readonly findingLabel: string; readonly errorLabel: string },
720
+ ): Effect.Effect<ReadonlyArray<string>, SpawnError, AgentDocsFiles> =>
721
+ eachGuarded(labels.errorLabel, files, (file) =>
722
+ Effect.gen(function* () {
723
+ const text = yield* readText(file, "latin1");
724
+ if (text === null) return [];
725
+ const lines: Array<string> = [];
726
+ for (const [number, line] of proseLines(text))
727
+ lines.push(...(yield* scanLine(file, number, line, labels.findingLabel)));
728
+ return lines;
729
+ }),
730
+ );