docks-kit 0.25.0 → 0.26.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 (38) hide show
  1. package/AGENTS.md +6 -6
  2. package/README.md +29 -9
  3. package/cli/dist/docks-kit.js +24688 -0
  4. package/cli/docs/command-guards.md +1 -1
  5. package/cli/docs/install.md +26 -6
  6. package/cli/docs/omp-context.md +1 -1
  7. package/cli/docs/omp-models.md +1 -1
  8. package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
  9. package/cli/src/agentDocs/bridgeCheck.ts +226 -0
  10. package/cli/src/agentDocs/commands.ts +63 -0
  11. package/cli/src/agentDocs/prTemplate.ts +211 -0
  12. package/cli/src/agentDocs/services.ts +202 -0
  13. package/cli/src/agentDocs/shared.ts +730 -0
  14. package/cli/src/agentDocs/verifySkill.ts +136 -0
  15. package/cli/src/argv.ts +25 -1
  16. package/cli/src/commands/agentDocs.ts +29 -0
  17. package/cli/src/commands/plan.ts +29 -0
  18. package/cli/src/commands/skill.ts +29 -0
  19. package/cli/src/commands/update.ts +87 -28
  20. package/cli/src/generated/sotPayload.ts +50 -78
  21. package/cli/src/main.ts +12 -3
  22. package/cli/src/plan/bytes.ts +110 -0
  23. package/cli/src/plan/checkout.ts +341 -0
  24. package/cli/src/plan/commands.ts +1192 -0
  25. package/cli/src/plan/github.ts +816 -0
  26. package/cli/src/plan/records.ts +623 -0
  27. package/cli/src/plan/repository.ts +53 -0
  28. package/cli/src/plan/reviews.ts +292 -0
  29. package/cli/src/plan/services.ts +256 -0
  30. package/cli/src/plan/types.ts +164 -0
  31. package/cli/src/skills/commands.ts +142 -0
  32. package/cli/src/skills/config.json +30 -0
  33. package/cli/src/skills/files.ts +74 -0
  34. package/cli/src/skills/frontmatter.ts +148 -0
  35. package/cli/src/skills/guard.ts +366 -0
  36. package/cli/src/skills/kitGate.ts +406 -0
  37. package/cli/src/skills/rubric.ts +143 -0
  38. package/package.json +7 -4
@@ -0,0 +1,366 @@
1
+ /**
2
+ * The portable SKILL.md validator of `docks-kit skill guard`, ported from the former skill-guard script of
3
+ * write-skill: the frontmatter and structure rules, pure over the file text, and the walk that finds each SKILL.md
4
+ * below a skills root.
5
+ * The kit-only rules (report section, shared copies, transform guard, score floors) live in `kitGate.ts`.
6
+ */
7
+ import { basename, join } from "node:path";
8
+
9
+ import { Effect } from "effect";
10
+
11
+ import { SkillFiles } from "./files";
12
+ import {
13
+ ageDays,
14
+ anyLine,
15
+ bodyAfterFrontmatter,
16
+ dateSeconds,
17
+ FRESH_DAYS,
18
+ metadataUpdated,
19
+ slopCount,
20
+ upstreamCount,
21
+ } from "./rubric";
22
+
23
+ const MAX_NAME_LENGTH = 64;
24
+ const MAX_DESCRIPTION_LENGTH = 1024;
25
+ const LISTING_DESCRIPTION_LENGTH = 500;
26
+ const MAX_BODY_LINES = 500;
27
+ const MIN_TARGET_BODY_LINES = 80;
28
+ const MAX_TARGET_BODY_LINES = 310;
29
+
30
+ /** One validator message: a failure, or a warning that `--strict` turns into a failure. */
31
+ export interface Finding {
32
+ readonly level: "fail" | "warn";
33
+ readonly message: string;
34
+ }
35
+
36
+ const fail = (message: string): Finding => ({ level: "fail", message });
37
+ const warn = (message: string): Finding => ({ level: "warn", message });
38
+
39
+ // ---- the description value as a YAML parser reads it ----
40
+
41
+ const indentOf = (line: string): number => /^ */.exec(line)?.[0].length ?? 0;
42
+
43
+ const DOUBLE_QUOTE_ESCAPES: Readonly<Record<string, string>> = {
44
+ "0": "\0",
45
+ a: "\x07",
46
+ b: "\b",
47
+ t: "\t",
48
+ "\t": "\t",
49
+ n: "\n",
50
+ v: "\v",
51
+ f: "\f",
52
+ r: "\r",
53
+ e: "\x1b",
54
+ " ": " ",
55
+ '"': '"',
56
+ "/": "/",
57
+ "\\": "\\",
58
+ N: "\x85",
59
+ _: "\xa0",
60
+ L: "\u2028",
61
+ P: "\u2029",
62
+ };
63
+
64
+ /** True when the text ends with an odd run of backslashes, so its last one escapes the line break. */
65
+ const endsEscaped = (text: string): boolean => /(^|[^\\])(\\\\)*\\$/.test(text);
66
+
67
+ function unescapeDouble(text: string): string {
68
+ return text.replace(
69
+ /\\(x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8}|.)/g,
70
+ (match, escape: string) => {
71
+ if (escape.length === 1) return DOUBLE_QUOTE_ESCAPES[escape] ?? match;
72
+ const codePoint = Number.parseInt(escape.slice(1), 16);
73
+ return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : match;
74
+ },
75
+ );
76
+ }
77
+
78
+ /** The lines between the frontmatter fences (to the end when the closing fence is missing). */
79
+ function frontmatterLines(lines: ReadonlyArray<string>): ReadonlyArray<string> {
80
+ const start = lines[0] === "---" ? 1 : 0;
81
+ const end = lines.indexOf("---", start);
82
+ return lines.slice(start, end === -1 ? undefined : end);
83
+ }
84
+
85
+ /**
86
+ * `|` keeps line breaks, `>` folds them to spaces except around empty and more-indented lines; the content indentation
87
+ * (indicator or first text line) is stripped; chomping `-` drops the final line break, clip keeps one, `+` keeps it and
88
+ * the trailing empty lines.
89
+ */
90
+ function blockScalar(
91
+ folded: boolean,
92
+ indicator: string | undefined,
93
+ chomp: string | undefined,
94
+ rest: ReadonlyArray<string>,
95
+ ): string {
96
+ const first = rest.find((line) => line.trim() !== "");
97
+ const indent = indicator ? Number(indicator) : first === undefined ? 0 : indentOf(first);
98
+ const body: Array<string> = [];
99
+ for (const line of rest) {
100
+ if (line.trim() === "") body.push("");
101
+ else if (indent > 0 && indentOf(line) >= indent) body.push(line.slice(indent));
102
+ else break;
103
+ }
104
+ let end = body.length;
105
+ while (end > 0 && body[end - 1] === "") end -= 1;
106
+ const trailing = body.length - end;
107
+ let text = "";
108
+ let previous: string | null = null;
109
+ let empties = 0;
110
+ for (const line of body.slice(0, end)) {
111
+ if (line === "") {
112
+ empties += 1;
113
+ continue;
114
+ }
115
+ if (previous === null) text = "\n".repeat(empties) + line;
116
+ else if (!folded || /^[ \t]/.test(previous) || /^[ \t]/.test(line)) {
117
+ text += "\n".repeat(empties + 1) + line;
118
+ } else text += (empties === 0 ? " " : "\n".repeat(empties)) + line;
119
+ previous = line;
120
+ empties = 0;
121
+ }
122
+ if (previous === null) return chomp === "+" ? "\n".repeat(trailing) : "";
123
+ if (chomp === "-") return text;
124
+ return chomp === "+" ? `${text}\n${"\n".repeat(trailing)}` : `${text}\n`;
125
+ }
126
+
127
+ interface QuotedPart {
128
+ readonly text: string;
129
+ readonly joined: boolean;
130
+ }
131
+
132
+ /**
133
+ * A quoted value up to its closing quote: a line break folds to a space, empty lines become line breaks, and the space
134
+ * around a break is dropped; `"` reads escapes (`\` at the end of a line joins the next line), `'` reads `''` as one
135
+ * quote.
136
+ */
137
+ function quotedScalar(head: string, rest: ReadonlyArray<string>): string {
138
+ const quote = head[0];
139
+ const raw: Array<string> = [];
140
+ for (const [index, line] of [head.slice(1), ...rest].entries()) {
141
+ if (index > 0 && line.trim() !== "" && indentOf(line) === 0) break;
142
+ let close = -1;
143
+ for (let column = 0; column < line.length && close === -1; column += 1) {
144
+ if (quote === '"' && line[column] === "\\") column += 1;
145
+ else if (line[column] === quote && quote === "'" && line[column + 1] === "'") column += 1;
146
+ else if (line[column] === quote) close = column;
147
+ }
148
+ raw.push(close === -1 ? line : line.slice(0, close));
149
+ if (close !== -1) break;
150
+ }
151
+ const decode =
152
+ quote === '"' ? unescapeDouble : (text: string): string => text.replaceAll("''", "'");
153
+ const parts = raw.map((line, index): QuotedPart => {
154
+ let text = index === 0 ? line : line.replace(/^[ \t]+/, "");
155
+ if (index === raw.length - 1) return { text, joined: false };
156
+ if (quote === '"' && endsEscaped(text)) return { text: text.slice(0, -1), joined: true };
157
+ const trimmed = text.replace(/[ \t]+$/, "");
158
+ text = quote === '"' && endsEscaped(trimmed) ? text.slice(0, trimmed.length + 1) : trimmed;
159
+ return { text, joined: false };
160
+ });
161
+ const [first, ...later] = parts;
162
+ if (first === undefined) return "";
163
+ let value = decode(first.text);
164
+ let previous = first;
165
+ let empties = 0;
166
+ for (const [offset, part] of later.entries()) {
167
+ if (part.text === "" && offset + 1 < later.length) {
168
+ empties += 1;
169
+ continue;
170
+ }
171
+ value += (previous.joined || empties > 0 ? "" : " ") + "\n".repeat(empties) + decode(part.text);
172
+ previous = part;
173
+ empties = 0;
174
+ }
175
+ return value;
176
+ }
177
+
178
+ interface Description {
179
+ readonly value: string;
180
+ /** True when a plain value holds a ` #` comment. */
181
+ readonly comment: boolean;
182
+ /** True when the value starts with a YAML alias (`*`), anchor (`&`), or tag (`!`), which this reader does not resolve. */
183
+ readonly node: boolean;
184
+ }
185
+
186
+ /** A plain value: it ends at a ` #` comment or a less-indented line; lines fold as in quotes. */
187
+ function plainScalar(head: string, rest: ReadonlyArray<string>): Omit<Description, "node"> {
188
+ const texts: Array<string> = [];
189
+ let comment = false;
190
+ for (const [index, line] of [head, ...rest].entries()) {
191
+ if (index > 0 && line.trim() !== "" && indentOf(line) === 0) break;
192
+ const hash = /(^|[ \t])#/.exec(line);
193
+ texts.push((hash ? line.slice(0, hash.index) : line).trim());
194
+ if (hash) {
195
+ comment = true;
196
+ break;
197
+ }
198
+ }
199
+ let value = "";
200
+ let empties = 0;
201
+ for (const text of texts) {
202
+ if (text === "") {
203
+ empties += 1;
204
+ continue;
205
+ }
206
+ value += value === "" ? text : (empties === 0 ? " " : "\n".repeat(empties)) + text;
207
+ empties = 0;
208
+ }
209
+ return { value, comment };
210
+ }
211
+
212
+ /** The top-level description value of the frontmatter. */
213
+ function readDescription(lines: ReadonlyArray<string>): Description {
214
+ const frontmatter = frontmatterLines(lines);
215
+ const at = frontmatter.findIndex((line) => /^description:/.test(line));
216
+ const line = frontmatter[at];
217
+ if (line === undefined) return { value: "", comment: false, node: false };
218
+ const head = line.slice("description:".length).trim();
219
+ const rest = frontmatter.slice(at + 1);
220
+ const block = /^([|>])(?:([1-9])([+-])?|([+-])([1-9])?)?(?:[ \t]+#.*)?$/.exec(head);
221
+ if (block) {
222
+ const value = blockScalar(block[1] === ">", block[2] || block[5], block[3] || block[4], rest);
223
+ return { value, comment: false, node: false };
224
+ }
225
+ if (head.startsWith('"') || head.startsWith("'")) {
226
+ return { value: quotedScalar(head, rest), comment: false, node: false };
227
+ }
228
+ const plain = plainScalar(head, rest);
229
+ return { ...plain, node: /^[*&!]/.test(plain.value) };
230
+ }
231
+
232
+ // ---- the rules ----
233
+
234
+ /**
235
+ * The findings of one SKILL.md before its `references/` check: the frontmatter fence, the name, the description,
236
+ * `user-invocable`, `metadata.updated`, and the body length. `dir` is the skill folder as the command prints it.
237
+ */
238
+ export function frontFindings(
239
+ dir: string,
240
+ lines: ReadonlyArray<string>,
241
+ nowMillis: number,
242
+ ): Array<Finding> {
243
+ const findings: Array<Finding> = [];
244
+ if (lines[0] !== "---")
245
+ findings.push(fail("SKILL.md must start with YAML frontmatter fence ---"));
246
+ else if (!lines.slice(1).some((line) => line === "---")) {
247
+ findings.push(fail("frontmatter fence is not closed"));
248
+ }
249
+
250
+ const folder = basename(dir);
251
+ const name =
252
+ (lines.find((line) => /^name:/.test(line)) ?? "")
253
+ .replace(/^name:\s*/, "")
254
+ .replace(/^["']|["']$/g, "") || folder;
255
+ const nameLength = [...name].length;
256
+ if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
257
+ findings.push(fail(`name '${name}' must be lowercase hyphen-case`));
258
+ }
259
+ if (nameLength > MAX_NAME_LENGTH) findings.push(fail(`name exceeds 64 chars (${nameLength})`));
260
+ if (name !== folder) findings.push(fail(`name '${name}' must match directory '${folder}'`));
261
+
262
+ const description = readDescription(lines);
263
+ const vendored = upstreamCount(lines) > 0;
264
+ if (description.node) {
265
+ findings.push(
266
+ fail(
267
+ "description must be a plain, quoted, or block scalar string (no YAML alias, anchor, or tag)",
268
+ ),
269
+ );
270
+ } else if (description.value === "") findings.push(fail("description must be non-empty"));
271
+ else {
272
+ const length = [...description.value].length;
273
+ if (length > MAX_DESCRIPTION_LENGTH) {
274
+ findings.push(fail(`description exceeds 1024 chars (${length})`));
275
+ }
276
+ if (description.comment) {
277
+ findings.push(
278
+ fail(
279
+ "unquoted description contains '#' — quote it (YAML reads ' #' as the start of a comment)",
280
+ ),
281
+ );
282
+ }
283
+ if (length > LISTING_DESCRIPTION_LENGTH) {
284
+ findings.push(
285
+ warn(`description is ${length} chars (>500 crowds the aggregate listing budget)`),
286
+ );
287
+ }
288
+ if (vendored) {
289
+ if (!/use when/i.test(description.value)) {
290
+ findings.push(warn("description should contain 'Use when'"));
291
+ }
292
+ } else if (!/^use when/i.test(description.value)) {
293
+ findings.push(warn("description should start with 'Use when'"));
294
+ }
295
+ }
296
+ if (!anyLine(lines, /^user-invocable:\s*(true|false)/)) {
297
+ findings.push(warn("frontmatter 'user-invocable' missing"));
298
+ }
299
+ const updated = metadataUpdated(lines);
300
+ if (updated === "") {
301
+ if (!vendored) findings.push(warn("metadata.updated missing (YYYY-MM-DD)"));
302
+ } else {
303
+ const seconds = dateSeconds(updated);
304
+ if (seconds > 0) {
305
+ const age = ageDays(Math.floor(nowMillis / 1000), seconds);
306
+ if (age > FRESH_DAYS)
307
+ findings.push(warn(`metadata.updated is ${age}d old (>180d reads stale)`));
308
+ }
309
+ }
310
+
311
+ const bodyLines = bodyAfterFrontmatter(lines).length;
312
+ if (bodyLines > MAX_BODY_LINES) {
313
+ findings.push(
314
+ fail(`body is ${bodyLines} lines (hard cap 500) — extract detail into references/`),
315
+ );
316
+ }
317
+ if (bodyLines < MIN_TARGET_BODY_LINES || bodyLines > MAX_TARGET_BODY_LINES) {
318
+ findings.push(
319
+ warn(
320
+ `body is ${bodyLines} lines, outside the 80-310 target (agentskills.io: keep the body under 5000 tokens and 500 lines)`,
321
+ ),
322
+ );
323
+ }
324
+ return findings;
325
+ }
326
+
327
+ /** The finding of a `references/` folder that holds a folder. */
328
+ export const NESTED_REFERENCES: Finding = fail(
329
+ "references/ must stay one level deep (agentskills.io: avoid deep reference chains)",
330
+ );
331
+
332
+ /** The slop warning of one SKILL.md, after its `references/` check. */
333
+ export function slopFindings(lines: ReadonlyArray<string>): Array<Finding> {
334
+ const slop = slopCount(lines);
335
+ return slop > 0
336
+ ? [warn(`${slop} slop word(s) in prose (comprehensive/robust/elegant/seamless)`)]
337
+ : [];
338
+ }
339
+
340
+ /** The last line of one skill's report. */
341
+ export const scoreLine = (score: number): string =>
342
+ ` score: ${score}/16 (docks rubric; per-file floor set by the project's scoring.json; aim 14+)`;
343
+
344
+ // ---- the walk ----
345
+
346
+ /**
347
+ * Each SKILL.md below `root`, sorted. The walk skips `node_modules` and does not enter a symlink; a folder that it
348
+ * cannot read is skipped.
349
+ */
350
+ export const walkSkillFiles = Effect.fn("skills.walkSkillFiles")(function* (root: string) {
351
+ const files = yield* SkillFiles;
352
+ const out: Array<string> = [];
353
+ const walk: (folder: string) => Effect.Effect<void> = Effect.fnUntraced(function* (folder) {
354
+ const entries = yield* files
355
+ .readFolder(folder)
356
+ .pipe(Effect.catchTag("FileError", () => Effect.succeed([])));
357
+ for (const entry of entries) {
358
+ if (entry.name === "node_modules") continue;
359
+ const full = join(folder, entry.name);
360
+ if (entry.isDirectory) yield* walk(full);
361
+ else if (entry.name === "SKILL.md") out.push(full);
362
+ }
363
+ });
364
+ yield* walk(root);
365
+ return out.sort();
366
+ });