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.
- package/AGENTS.md +6 -6
- package/README.md +29 -9
- package/cli/dist/docks-kit.js +24688 -0
- package/cli/docs/command-guards.md +1 -1
- package/cli/docs/install.md +26 -6
- package/cli/docs/omp-context.md +1 -1
- package/cli/docs/omp-models.md +1 -1
- package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
- package/cli/src/agentDocs/bridgeCheck.ts +226 -0
- package/cli/src/agentDocs/commands.ts +63 -0
- package/cli/src/agentDocs/prTemplate.ts +211 -0
- package/cli/src/agentDocs/services.ts +202 -0
- package/cli/src/agentDocs/shared.ts +730 -0
- package/cli/src/agentDocs/verifySkill.ts +136 -0
- package/cli/src/argv.ts +25 -1
- package/cli/src/commands/agentDocs.ts +29 -0
- package/cli/src/commands/plan.ts +29 -0
- package/cli/src/commands/skill.ts +29 -0
- package/cli/src/commands/update.ts +87 -28
- package/cli/src/generated/sotPayload.ts +50 -78
- package/cli/src/main.ts +12 -3
- package/cli/src/plan/bytes.ts +110 -0
- package/cli/src/plan/checkout.ts +341 -0
- package/cli/src/plan/commands.ts +1192 -0
- package/cli/src/plan/github.ts +816 -0
- package/cli/src/plan/records.ts +623 -0
- package/cli/src/plan/repository.ts +53 -0
- package/cli/src/plan/reviews.ts +292 -0
- package/cli/src/plan/services.ts +256 -0
- package/cli/src/plan/types.ts +164 -0
- package/cli/src/skills/commands.ts +142 -0
- package/cli/src/skills/config.json +30 -0
- package/cli/src/skills/files.ts +74 -0
- package/cli/src/skills/frontmatter.ts +148 -0
- package/cli/src/skills/guard.ts +366 -0
- package/cli/src/skills/kitGate.ts +406 -0
- package/cli/src/skills/rubric.ts +143 -0
- package/package.json +7 -4
|
@@ -0,0 +1,406 @@
|
|
|
1
|
+
import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
|
|
2
|
+
import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
|
|
3
|
+
import config from "./config.json" with { type: "json" };
|
|
4
|
+
import {
|
|
5
|
+
extractFrontmatter,
|
|
6
|
+
findSkillByName,
|
|
7
|
+
findSkillFiles,
|
|
8
|
+
frontmatterBlock,
|
|
9
|
+
frontmatterName,
|
|
10
|
+
type FrontmatterMapping,
|
|
11
|
+
mappingField,
|
|
12
|
+
parseFrontmatter,
|
|
13
|
+
skillCandidateDirs,
|
|
14
|
+
skillsDir,
|
|
15
|
+
} from "./frontmatter";
|
|
16
|
+
import { bodyAfterFrontmatter, scoreSkill, splitLines } from "./rubric";
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* The skill checks of the DocksDocks/docks gate, ported to the kit plugin:
|
|
20
|
+
* the layout and name check of `scripts/ci.mjs gateSkills`, the frontmatter
|
|
21
|
+
* rules of `scripts/lib/validate-skills.mjs`, the report section and shared
|
|
22
|
+
* copy checks of `scripts/skills/guard.mjs`, `scripts/skills/transform-guard.mjs`,
|
|
23
|
+
* and the score floor of `gateSkills`. Each check takes a repository root and
|
|
24
|
+
* returns one message per problem; a message names the file relative to the root.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
export interface ScoreRow {
|
|
28
|
+
readonly name: string;
|
|
29
|
+
readonly score: number;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface ScoreResult {
|
|
33
|
+
readonly rows: ReadonlyArray<ScoreRow>;
|
|
34
|
+
readonly failures: ReadonlyArray<string>;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const MAX_NAME_LENGTH = 64;
|
|
38
|
+
const MAX_DESCRIPTION_LENGTH = 1024;
|
|
39
|
+
const MAX_BODY_LINES = 500;
|
|
40
|
+
const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
|
|
41
|
+
const NAME_PATTERN = /^[a-z0-9-]+$/;
|
|
42
|
+
const HASH_PATTERN = /^[0-9a-f]{64}$/;
|
|
43
|
+
|
|
44
|
+
const shown = (repoRoot: string, file: string): string =>
|
|
45
|
+
relative(repoRoot, file).split(sep).join("/") || file;
|
|
46
|
+
|
|
47
|
+
/** Each skill sits at skills/<name>/SKILL.md, and its frontmatter name is <name>. */
|
|
48
|
+
export function checkSkillLayout(repoRoot: string): Array<string> {
|
|
49
|
+
const root = skillsDir(repoRoot);
|
|
50
|
+
const failures: Array<string> = [];
|
|
51
|
+
for (const file of findSkillFiles(root)) {
|
|
52
|
+
const [folder, ...rest] = relative(root, file).split(sep);
|
|
53
|
+
if (rest.length !== 1) {
|
|
54
|
+
failures.push(`${shown(repoRoot, file)} is not at skills/<name>/SKILL.md`);
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
const name = frontmatterName(frontmatterBlock(readFileSync(file, "utf8")) ?? "");
|
|
58
|
+
if (name !== folder) {
|
|
59
|
+
failures.push(
|
|
60
|
+
`${shown(repoRoot, file)} has the name '${String(name)}', not its folder name '${folder}'`,
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
return failures;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** A plain description with ` #` reads as a YAML comment from that point. */
|
|
68
|
+
function hasPlainCommentHazard(frontmatterText: string): boolean {
|
|
69
|
+
const line = frontmatterText.split(/\r?\n/).find((entry) => /^description:/.test(entry)) ?? "";
|
|
70
|
+
if (line === "") return false;
|
|
71
|
+
const raw = line.replace(/^description:\s*/, "");
|
|
72
|
+
if (raw === "" || /^["'|>]/.test(raw)) return false;
|
|
73
|
+
return /(^|[ \t])#/.test(raw);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function bodyLineCount(body: string): number {
|
|
77
|
+
if (body === "") return 0;
|
|
78
|
+
const trimmed = body.endsWith("\n") ? body.slice(0, -1) : body;
|
|
79
|
+
return trimmed === "" ? 0 : trimmed.split(/\r?\n/).length;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function commonErrors(
|
|
83
|
+
file: string,
|
|
84
|
+
frontmatterText: string,
|
|
85
|
+
frontmatter: FrontmatterMapping,
|
|
86
|
+
): Array<string> {
|
|
87
|
+
const errors: Array<string> = [];
|
|
88
|
+
const { name, description } = frontmatter;
|
|
89
|
+
if (typeof name !== "string" || name.trim() === "") {
|
|
90
|
+
errors.push("frontmatter `name` must be a non-empty string");
|
|
91
|
+
} else {
|
|
92
|
+
if (!NAME_PATTERN.test(name)) {
|
|
93
|
+
errors.push(`name ${JSON.stringify(name)} must be lowercase hyphen-case`);
|
|
94
|
+
}
|
|
95
|
+
if (name.startsWith("-") || name.endsWith("-") || name.includes("--")) {
|
|
96
|
+
errors.push(
|
|
97
|
+
`name ${JSON.stringify(name)} cannot start/end with hyphen or contain consecutive hyphens`,
|
|
98
|
+
);
|
|
99
|
+
}
|
|
100
|
+
if (name.length > MAX_NAME_LENGTH) {
|
|
101
|
+
errors.push(`name exceeds maximum length of ${MAX_NAME_LENGTH} characters (${name.length})`);
|
|
102
|
+
}
|
|
103
|
+
const folder = basename(dirname(file));
|
|
104
|
+
if (name !== folder) {
|
|
105
|
+
errors.push(`name ${JSON.stringify(name)} must match directory ${JSON.stringify(folder)}`);
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
if (typeof description !== "string" || description.trim() === "") {
|
|
109
|
+
errors.push("frontmatter `description` must be a non-empty string");
|
|
110
|
+
} else {
|
|
111
|
+
if (description.length > MAX_DESCRIPTION_LENGTH) {
|
|
112
|
+
errors.push(
|
|
113
|
+
`description exceeds maximum length of ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`,
|
|
114
|
+
);
|
|
115
|
+
}
|
|
116
|
+
if (hasPlainCommentHazard(frontmatterText)) {
|
|
117
|
+
errors.push(
|
|
118
|
+
"plain YAML description contains `#`; YAML reads ` #` as the start of a comment, so quote it",
|
|
119
|
+
);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
return errors;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** The agentskills.io rules: a body under 500 lines, and references one level deep. */
|
|
126
|
+
function structureErrors(file: string, body: string): Array<string> {
|
|
127
|
+
const errors: Array<string> = [];
|
|
128
|
+
const lines = bodyLineCount(body);
|
|
129
|
+
if (lines > MAX_BODY_LINES) {
|
|
130
|
+
errors.push(`body is ${lines} lines (cap: ${MAX_BODY_LINES}); extract detail into references/`);
|
|
131
|
+
}
|
|
132
|
+
const referencesDir = join(dirname(file), "references");
|
|
133
|
+
if (existsSync(referencesDir) && statSync(referencesDir).isDirectory()) {
|
|
134
|
+
for (const entry of readdirSync(referencesDir, { withFileTypes: true })) {
|
|
135
|
+
if (entry.isDirectory()) {
|
|
136
|
+
errors.push(
|
|
137
|
+
`references/ must stay one level deep; nested directory ${JSON.stringify(entry.name)} is not allowed (agentskills.io: avoid deep reference chains)`,
|
|
138
|
+
);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
return errors;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** The docks rules: `Use when`, `user-invocable`, `metadata.updated`, and the hash format. */
|
|
146
|
+
function docksErrors(frontmatter: FrontmatterMapping): Array<string> {
|
|
147
|
+
const errors: Array<string> = [];
|
|
148
|
+
const upstream = Boolean(frontmatter["upstream"]);
|
|
149
|
+
const description = frontmatter["description"];
|
|
150
|
+
const metadata = mappingField(frontmatter, "metadata");
|
|
151
|
+
if (!upstream && typeof description === "string" && !/^use when/i.test(description)) {
|
|
152
|
+
errors.push("description must start with `Use when` unless the skill has an `upstream:` block");
|
|
153
|
+
}
|
|
154
|
+
if (!upstream && typeof frontmatter["user-invocable"] !== "boolean") {
|
|
155
|
+
errors.push("frontmatter `user-invocable` must be present and boolean");
|
|
156
|
+
}
|
|
157
|
+
if (!upstream) {
|
|
158
|
+
const updated = metadata?.["updated"];
|
|
159
|
+
if (typeof updated !== "string" || !DATE_PATTERN.test(updated)) {
|
|
160
|
+
errors.push("metadata.updated must be present in YYYY-MM-DD format");
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
const contentHash = metadata?.["content_hash"];
|
|
164
|
+
if (
|
|
165
|
+
contentHash !== undefined &&
|
|
166
|
+
(typeof contentHash !== "string" || !HASH_PATTERN.test(contentHash))
|
|
167
|
+
) {
|
|
168
|
+
errors.push("metadata.content_hash must be a 64-character lowercase hex string when present");
|
|
169
|
+
}
|
|
170
|
+
return errors;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** The frontmatter rules of the skill validator, for each SKILL.md below the skills folder. */
|
|
174
|
+
export function checkSkillFrontmatter(repoRoot: string): Array<string> {
|
|
175
|
+
const root = skillsDir(repoRoot);
|
|
176
|
+
const files = findSkillFiles(root);
|
|
177
|
+
if (files.length === 0) return [`${shown(repoRoot, root)}: no SKILL.md files found`];
|
|
178
|
+
const failures: Array<string> = [];
|
|
179
|
+
for (const file of files) {
|
|
180
|
+
const extracted = extractFrontmatter(readFileSync(file, "utf8"));
|
|
181
|
+
const errors: Array<string> = [];
|
|
182
|
+
if (!extracted.ok) {
|
|
183
|
+
errors.push(extracted.error);
|
|
184
|
+
} else {
|
|
185
|
+
const parsed = parseFrontmatter(extracted.text);
|
|
186
|
+
if (!parsed.ok) {
|
|
187
|
+
errors.push(`invalid YAML frontmatter: ${parsed.error}`);
|
|
188
|
+
} else {
|
|
189
|
+
errors.push(
|
|
190
|
+
...commonErrors(file, extracted.text, parsed.value),
|
|
191
|
+
...structureErrors(file, extracted.body),
|
|
192
|
+
...docksErrors(parsed.value),
|
|
193
|
+
);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
for (const error of errors) failures.push(`${shown(repoRoot, file)}: ${error}`);
|
|
197
|
+
}
|
|
198
|
+
return failures;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/**
|
|
202
|
+
* Each skill ends with the canonical report section, byte for byte. The files
|
|
203
|
+
* are read as latin1 (one character per byte), so line endings and the final
|
|
204
|
+
* newline count. The last heading starts the section, because a skill can
|
|
205
|
+
* quote the heading in its body.
|
|
206
|
+
*/
|
|
207
|
+
export function checkReportSection(
|
|
208
|
+
repoRoot: string,
|
|
209
|
+
section: string = config.reportSection,
|
|
210
|
+
): Array<string> {
|
|
211
|
+
const canonical = Buffer.from(section, "utf8").toString("latin1");
|
|
212
|
+
const heading = canonical.split("\n", 1)[0] ?? "";
|
|
213
|
+
if (!heading.startsWith("## ")) {
|
|
214
|
+
return ["config.json reportSection: the first line must be the `## ` heading of the section"];
|
|
215
|
+
}
|
|
216
|
+
const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
217
|
+
const headingLine = new RegExp(`^${escaped}$`, "gm");
|
|
218
|
+
const failures: Array<string> = [];
|
|
219
|
+
for (const file of findSkillFiles(skillsDir(repoRoot))) {
|
|
220
|
+
const content = readFileSync(file, "latin1");
|
|
221
|
+
const start = [...content.matchAll(headingLine)].at(-1)?.index;
|
|
222
|
+
if (start === undefined) {
|
|
223
|
+
failures.push(
|
|
224
|
+
`${shown(repoRoot, file)}: missing the Report section; end the file with the reportSection text of config.json`,
|
|
225
|
+
);
|
|
226
|
+
} else if (content.slice(start) !== canonical) {
|
|
227
|
+
failures.push(
|
|
228
|
+
`${shown(repoRoot, file)}: the Report section differs from the reportSection text of config.json; copy that text over it`,
|
|
229
|
+
);
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
return failures;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
export interface SharedFileGroup {
|
|
236
|
+
readonly canonical: string;
|
|
237
|
+
readonly copies: ReadonlyArray<string>;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/** Each copy of a shared file equals its canonical file, byte for byte. */
|
|
241
|
+
export function checkSharedCopies(
|
|
242
|
+
repoRoot: string,
|
|
243
|
+
groups: ReadonlyArray<SharedFileGroup> = config.sharedFiles,
|
|
244
|
+
): Array<string> {
|
|
245
|
+
const failures: Array<string> = [];
|
|
246
|
+
const isPath = (value: string): boolean => value !== "" && !isAbsolute(value);
|
|
247
|
+
if (
|
|
248
|
+
!groups.every(
|
|
249
|
+
(group) => isPath(group.canonical) && group.copies.length > 0 && group.copies.every(isPath),
|
|
250
|
+
)
|
|
251
|
+
) {
|
|
252
|
+
return [
|
|
253
|
+
'config.json sharedFiles: must be a list of { "canonical": "<path>", "copies": ["<path>", ...] }, with relative paths',
|
|
254
|
+
];
|
|
255
|
+
}
|
|
256
|
+
const read = (path: string): Buffer | undefined => {
|
|
257
|
+
try {
|
|
258
|
+
return readFileSync(join(repoRoot, path));
|
|
259
|
+
} catch (error) {
|
|
260
|
+
failures.push(`${path}: cannot read the shared file (${String(error)})`);
|
|
261
|
+
return undefined;
|
|
262
|
+
}
|
|
263
|
+
};
|
|
264
|
+
for (const { canonical, copies } of groups) {
|
|
265
|
+
const canonicalBytes = read(canonical);
|
|
266
|
+
for (const copy of copies) {
|
|
267
|
+
const copyBytes = read(copy);
|
|
268
|
+
if (
|
|
269
|
+
canonicalBytes !== undefined &&
|
|
270
|
+
copyBytes !== undefined &&
|
|
271
|
+
!copyBytes.equals(canonicalBytes)
|
|
272
|
+
) {
|
|
273
|
+
failures.push(`${copy}: differs from ${canonical}; copy that file over it`);
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
return failures;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
const PRESERVATION_PATTERN =
|
|
281
|
+
/content loss|no content|preserv|verbatim|net.?shrink|byte.?delta|section presence|drop a section|relocate.{0,12}verbatim/i;
|
|
282
|
+
/**
|
|
283
|
+
* A heading, not prose: the block must be a section that a reader can find. The
|
|
284
|
+
* heading text is free, for example "## Verification" or "### Step 6 - Verify".
|
|
285
|
+
*/
|
|
286
|
+
const VERIFY_HEADING_PATTERN = /^#{2,3}[^\n]*\bverif(y|ication)\b/im;
|
|
287
|
+
|
|
288
|
+
/**
|
|
289
|
+
* Each curated content-transforming skill keeps a preservation `<constraint>`
|
|
290
|
+
* and a verification heading, so that an edit cannot strip its data-loss guard.
|
|
291
|
+
*/
|
|
292
|
+
export function checkTransformGuard(
|
|
293
|
+
repoRoot: string,
|
|
294
|
+
names: ReadonlyArray<string> = config.transformingSkills,
|
|
295
|
+
): Array<string> {
|
|
296
|
+
const root = skillsDir(repoRoot);
|
|
297
|
+
const failures: Array<string> = [];
|
|
298
|
+
for (const name of names) {
|
|
299
|
+
const file = findSkillByName(root, name);
|
|
300
|
+
if (file === null) {
|
|
301
|
+
failures.push(
|
|
302
|
+
`listed transforming skill '${name}' has no SKILL.md under ${shown(repoRoot, root)}`,
|
|
303
|
+
);
|
|
304
|
+
continue;
|
|
305
|
+
}
|
|
306
|
+
const body = bodyAfterFrontmatter(splitLines(readFileSync(file, "utf8"))).join("\n");
|
|
307
|
+
let missing = "";
|
|
308
|
+
if (!PRESERVATION_PATTERN.test(body)) missing += "preservation <constraint>; ";
|
|
309
|
+
if (!VERIFY_HEADING_PATTERN.test(body)) missing += "## Verification block; ";
|
|
310
|
+
if (missing !== "") {
|
|
311
|
+
failures.push(
|
|
312
|
+
`${shown(repoRoot, file)}: ${name} lacks: ${missing}(was hardened — regression?)`,
|
|
313
|
+
);
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
return failures;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
export interface ScoreFloorInput {
|
|
320
|
+
/** The kind in each message, such as `skill` or `agent`. */
|
|
321
|
+
readonly kind: string;
|
|
322
|
+
readonly rows: ReadonlyArray<ScoreRow>;
|
|
323
|
+
/** The names that the scorer must score, from the folder on disk. */
|
|
324
|
+
readonly onDisk: ReadonlyArray<string>;
|
|
325
|
+
readonly floor: number;
|
|
326
|
+
/** The names that the per-file floor skips. */
|
|
327
|
+
readonly exempt?: ReadonlySet<string>;
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/**
|
|
331
|
+
* The score floor of the docks gate. The score rows are the only input, so a
|
|
332
|
+
* scorer that skipped an item would pass both floors; the row set must
|
|
333
|
+
* therefore cover the names on disk, once each, before the floors apply. Then
|
|
334
|
+
* the total must reach `rows × floor`, and each row must reach the floor.
|
|
335
|
+
*/
|
|
336
|
+
export function scoreFloorFailures(input: ScoreFloorInput): Array<string> {
|
|
337
|
+
const { kind, rows, onDisk, floor } = input;
|
|
338
|
+
if (onDisk.length === 0) return [`no ${kind} on disk, so no ${kind} score set to check`];
|
|
339
|
+
const nonFinite = rows.filter((row) => !Number.isFinite(row.score));
|
|
340
|
+
if (nonFinite.length > 0) {
|
|
341
|
+
return [
|
|
342
|
+
`the ${kind} scorer gave non-finite scores: ${nonFinite.map((row) => row.name).join(", ")}`,
|
|
343
|
+
];
|
|
344
|
+
}
|
|
345
|
+
const counts = new Map<string, number>();
|
|
346
|
+
for (const row of rows) counts.set(row.name, (counts.get(row.name) ?? 0) + 1);
|
|
347
|
+
const disk = new Set(onDisk);
|
|
348
|
+
const unscored = onDisk.filter((name) => !counts.has(name));
|
|
349
|
+
const notOnDisk = [...counts.keys()].filter((name) => !disk.has(name));
|
|
350
|
+
const duplicates = [...counts].filter(([, count]) => count > 1).map(([name]) => name);
|
|
351
|
+
if (rows.length !== onDisk.length || unscored.length + notOnDisk.length + duplicates.length > 0) {
|
|
352
|
+
const details = [
|
|
353
|
+
unscored.length > 0 ? `unscored on disk: ${unscored.join(", ")}` : null,
|
|
354
|
+
notOnDisk.length > 0 ? `not on disk: ${notOnDisk.join(", ")}` : null,
|
|
355
|
+
duplicates.length > 0 ? `duplicate score rows: ${duplicates.join(", ")}` : null,
|
|
356
|
+
].filter((detail) => detail !== null);
|
|
357
|
+
return [
|
|
358
|
+
`the ${kind} score set does not cover the tree: expected ${onDisk.length} on disk, parsed ${rows.length} score rows` +
|
|
359
|
+
(details.length > 0 ? ` — ${details.join(" — ")}` : ""),
|
|
360
|
+
];
|
|
361
|
+
}
|
|
362
|
+
const failures: Array<string> = [];
|
|
363
|
+
const total = rows.reduce((sum, row) => sum + row.score, 0);
|
|
364
|
+
if (total < rows.length * floor) {
|
|
365
|
+
failures.push(
|
|
366
|
+
`${kind} score total ${total} below floor ${rows.length * floor} (${rows.length} × ${floor})`,
|
|
367
|
+
);
|
|
368
|
+
}
|
|
369
|
+
for (const row of rows) {
|
|
370
|
+
if (input.exempt?.has(row.name) !== true && row.score < floor) {
|
|
371
|
+
failures.push(`${kind} ${row.name} score ${row.score} below per-file floor ${floor}`);
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
return failures;
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
/**
|
|
378
|
+
* Score each skill folder with the rubric of `docks-kit skill score`, and apply
|
|
379
|
+
* the score floor. The rubric skips a folder without a SKILL.md, so the names
|
|
380
|
+
* on disk come from the folders. An upstream skill counts in the total but
|
|
381
|
+
* skips the per-file floor. `nowMillis` dates the freshness point.
|
|
382
|
+
*/
|
|
383
|
+
export function scoreSkills(
|
|
384
|
+
repoRoot: string,
|
|
385
|
+
floor: number = config.floors.skills,
|
|
386
|
+
nowMillis: number = Date.now(),
|
|
387
|
+
): ScoreResult {
|
|
388
|
+
const candidates = skillCandidateDirs(skillsDir(repoRoot));
|
|
389
|
+
const rows: Array<ScoreRow> = [];
|
|
390
|
+
const exempt = new Set<string>();
|
|
391
|
+
for (const { name, file } of candidates) {
|
|
392
|
+
if (!existsSync(file)) continue;
|
|
393
|
+
// Node's readFileSync with an encoding decodes the bytes as Buffer#toString does, a byte-order mark included.
|
|
394
|
+
const content = readFileSync(file).toString("utf8");
|
|
395
|
+
rows.push({ name, score: scoreSkill(content, nowMillis) });
|
|
396
|
+
if (/^upstream:/m.test(content)) exempt.add(name);
|
|
397
|
+
}
|
|
398
|
+
const failures = scoreFloorFailures({
|
|
399
|
+
kind: "skill",
|
|
400
|
+
rows,
|
|
401
|
+
onDisk: candidates.map(({ name }) => name),
|
|
402
|
+
floor,
|
|
403
|
+
exempt,
|
|
404
|
+
});
|
|
405
|
+
return { rows, failures };
|
|
406
|
+
}
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The 16-point docks skill rubric, the one source of the skill score: `docks-kit skill score`, the score line of
|
|
3
|
+
* `docks-kit skill guard`, and the score floor of the kit gate all call `scoreSkill`. It reads the raw text of a
|
|
4
|
+
* SKILL.md line by line, as the former skill-guard script of write-skill did, so the description is the raw first
|
|
5
|
+
* `description:` line, not the YAML value. The line readers below also serve the validator and the agent scorer.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
const SECONDS_PER_DAY = 86_400;
|
|
9
|
+
/** A dated field older than this many days earns no freshness point and draws a staleness warning. */
|
|
10
|
+
export const FRESH_DAYS = 180;
|
|
11
|
+
const MAX_SHORT_DESCRIPTION = 500;
|
|
12
|
+
const MAX_LONG_DESCRIPTION = 1000;
|
|
13
|
+
const MAX_CONSTRAINT_POINTS = 3;
|
|
14
|
+
const MAX_SLOP_POINTS = 2;
|
|
15
|
+
const MIN_TARGET_BODY_LINES = 80;
|
|
16
|
+
const MAX_TARGET_BODY_LINES = 310;
|
|
17
|
+
|
|
18
|
+
/** The lines of a file, without the empty item after a final newline. */
|
|
19
|
+
export function splitLines(content: string): Array<string> {
|
|
20
|
+
return (content.endsWith("\n") ? content.slice(0, -1) : content).split("\n");
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export const countLines = (lines: ReadonlyArray<string>, pattern: RegExp): number =>
|
|
24
|
+
lines.reduce((count, line) => (pattern.test(line) ? count + 1 : count), 0);
|
|
25
|
+
|
|
26
|
+
export const anyLine = (lines: ReadonlyArray<string>, pattern: RegExp): boolean =>
|
|
27
|
+
lines.some((line) => pattern.test(line));
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The lines after the second `---` line. Only the first two `---` lines are
|
|
31
|
+
* fences, so a `---` line in the body counts as body.
|
|
32
|
+
*/
|
|
33
|
+
export function bodyAfterFrontmatter(lines: ReadonlyArray<string>): Array<string> {
|
|
34
|
+
let fences = 0;
|
|
35
|
+
const out: Array<string> = [];
|
|
36
|
+
for (const line of lines) {
|
|
37
|
+
if (line === "---" && fences < 2) {
|
|
38
|
+
fences += 1;
|
|
39
|
+
continue;
|
|
40
|
+
}
|
|
41
|
+
if (fences === 2) out.push(line);
|
|
42
|
+
}
|
|
43
|
+
return out;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const SLOP_PATTERN = /\b(comprehensive|robust|elegant|seamless)\b/i;
|
|
47
|
+
|
|
48
|
+
/** The prose lines with a banned word. Fenced code and inline code do not count. */
|
|
49
|
+
export function slopCount(lines: ReadonlyArray<string>): number {
|
|
50
|
+
let inFence = false;
|
|
51
|
+
const prose: Array<string> = [];
|
|
52
|
+
for (const line of lines) {
|
|
53
|
+
if (/^```/.test(line)) {
|
|
54
|
+
inFence = !inFence;
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
if (!inFence) prose.push(line.replace(/`[^`]*`/g, ""));
|
|
58
|
+
}
|
|
59
|
+
return countLines(prose, SLOP_PATTERN);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** The seconds since the epoch of a `YYYY-MM-DD` date at midnight UTC, or 0 when it does not parse. */
|
|
63
|
+
export function dateSeconds(date: string): number {
|
|
64
|
+
const millis = Date.parse(`${date}T00:00:00Z`);
|
|
65
|
+
return Number.isNaN(millis) ? 0 : Math.floor(millis / 1000);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** The whole days from `date` to `nowSeconds`. */
|
|
69
|
+
export const ageDays = (nowSeconds: number, dateSecondsValue: number): number =>
|
|
70
|
+
Math.floor((nowSeconds - dateSecondsValue) / SECONDS_PER_DAY);
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The digits and hyphens after `<key>:` on the first line inside the top-level `<block>:` mapping that holds `key`,
|
|
74
|
+
* or `""`. The block ends at the next line that starts with a lowercase letter.
|
|
75
|
+
*/
|
|
76
|
+
function blockDate(lines: ReadonlyArray<string>, block: RegExp, key: string): string {
|
|
77
|
+
const keyPattern = new RegExp(`${key}:`);
|
|
78
|
+
const valuePattern = new RegExp(`${key}:\\s*"?([0-9-]*)"?`);
|
|
79
|
+
let inBlock = false;
|
|
80
|
+
for (const line of lines) {
|
|
81
|
+
if (block.test(line)) {
|
|
82
|
+
inBlock = true;
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
if (inBlock && /^[a-z]/.test(line)) inBlock = false;
|
|
86
|
+
if (inBlock && keyPattern.test(line)) return valuePattern.exec(line)?.[1] ?? "";
|
|
87
|
+
}
|
|
88
|
+
return "";
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** The `metadata.updated` date as the line reader sees it, or `""`. */
|
|
92
|
+
export const metadataUpdated = (lines: ReadonlyArray<string>): string =>
|
|
93
|
+
blockDate(lines, /^metadata:/, "updated");
|
|
94
|
+
|
|
95
|
+
/** The `upstream.vendored_at` date as the line reader sees it, or `""`. */
|
|
96
|
+
const upstreamVendored = (lines: ReadonlyArray<string>): string =>
|
|
97
|
+
blockDate(lines, /^upstream:/, "vendored_at");
|
|
98
|
+
|
|
99
|
+
/** The number of top-level `upstream:` lines; a vendored skill has one. */
|
|
100
|
+
export const upstreamCount = (lines: ReadonlyArray<string>): number =>
|
|
101
|
+
countLines(lines, /^upstream:/);
|
|
102
|
+
|
|
103
|
+
/** The raw first `description:` line without the key and one pair of outer quotes. */
|
|
104
|
+
function rawDescription(lines: ReadonlyArray<string>): string {
|
|
105
|
+
const line = lines.find((entry) => /^description:/.test(entry)) ?? "";
|
|
106
|
+
return line
|
|
107
|
+
.replace(/^description:\s*/, "")
|
|
108
|
+
.replace(/^"/, "")
|
|
109
|
+
.replace(/"$/, "")
|
|
110
|
+
.replace(/^'/, "")
|
|
111
|
+
.replace(/'$/, "");
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* The 16-point score of one SKILL.md text. `nowMillis` is the clock that dates `metadata.updated` (or, for a vendored
|
|
116
|
+
* skill, `upstream.vendored_at`) against the 180-day freshness window.
|
|
117
|
+
*/
|
|
118
|
+
export function scoreSkill(content: string, nowMillis: number): number {
|
|
119
|
+
const lines = splitLines(content);
|
|
120
|
+
const nowSeconds = Math.floor(nowMillis / 1000);
|
|
121
|
+
let points = 0;
|
|
122
|
+
const vendored = upstreamCount(lines) > 0;
|
|
123
|
+
const description = rawDescription(lines);
|
|
124
|
+
const descriptionLength = [...description].length;
|
|
125
|
+
if (vendored ? /use when/i.test(description) : /^use when/i.test(description)) points += 2;
|
|
126
|
+
if (descriptionLength > 0 && descriptionLength <= MAX_SHORT_DESCRIPTION) points += 2;
|
|
127
|
+
else if (descriptionLength > 0 && descriptionLength <= MAX_LONG_DESCRIPTION) points += 1;
|
|
128
|
+
const updated = metadataUpdated(lines) || (vendored ? upstreamVendored(lines) : "");
|
|
129
|
+
if (updated !== "") {
|
|
130
|
+
const seconds = dateSeconds(updated);
|
|
131
|
+
if (seconds > 0 && ageDays(nowSeconds, seconds) <= FRESH_DAYS) points += 1;
|
|
132
|
+
}
|
|
133
|
+
points += Math.min(MAX_CONSTRAINT_POINTS, countLines(lines, /<constraint>/));
|
|
134
|
+
const bad = anyLine(lines, /\bBAD\b|\/\/\s*BAD|#\s*BAD/);
|
|
135
|
+
const good = anyLine(lines, /\bGOOD\b|\/\/\s*GOOD|#\s*GOOD/);
|
|
136
|
+
if ((bad && good) || (anyLine(lines, /wrong fix/i) && anyLine(lines, /right fix/i))) points += 2;
|
|
137
|
+
points += Math.max(0, MAX_SLOP_POINTS - slopCount(lines));
|
|
138
|
+
if (anyLine(lines, /^\|.*\|/)) points += 1;
|
|
139
|
+
if (anyLine(lines, /^```[a-z]+/)) points += 1;
|
|
140
|
+
const bodyLines = bodyAfterFrontmatter(lines).length;
|
|
141
|
+
if (bodyLines >= MIN_TARGET_BODY_LINES && bodyLines <= MAX_TARGET_BODY_LINES) points += 2;
|
|
142
|
+
return points;
|
|
143
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "docks-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.26.0",
|
|
4
4
|
"description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Oh My Pi",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -11,13 +11,14 @@
|
|
|
11
11
|
],
|
|
12
12
|
"repository": {
|
|
13
13
|
"type": "git",
|
|
14
|
-
"url": "git+https://github.com/DocksDocks/
|
|
14
|
+
"url": "git+https://github.com/DocksDocks/docks-kit.git"
|
|
15
15
|
},
|
|
16
16
|
"bin": {
|
|
17
|
-
"docks-kit": "cli/
|
|
17
|
+
"docks-kit": "cli/dist/docks-kit.js"
|
|
18
18
|
},
|
|
19
19
|
"files": [
|
|
20
20
|
"cli/src",
|
|
21
|
+
"cli/dist/docks-kit.js",
|
|
21
22
|
"cli/docs",
|
|
22
23
|
"cli/tsconfig.json",
|
|
23
24
|
"docks-kit",
|
|
@@ -28,10 +29,11 @@
|
|
|
28
29
|
"scripts": {
|
|
29
30
|
"typecheck": "bun check --no-script -b -p cli",
|
|
30
31
|
"build:binaries": "bash cli/build-binaries.sh",
|
|
32
|
+
"build:bundle": "bun cli/scripts/build-bundle.ts",
|
|
31
33
|
"smoke:native": "bun cli/scripts/native-smoke.ts",
|
|
32
34
|
"smoke:package": "bun cli/scripts/package-smoke.ts",
|
|
33
35
|
"check:generated": "bun cli/scripts/generate-sot-payload.ts --check",
|
|
34
|
-
"prepack": "bun run check:generated",
|
|
36
|
+
"prepack": "bun run check:generated && bun run build:bundle",
|
|
35
37
|
"golden:dryrun": "bun cli/test/golden-dryrun.ts",
|
|
36
38
|
"golden:mutation": "bun cli/test/golden-mutation.ts",
|
|
37
39
|
"test:unit": "vitest run",
|
|
@@ -53,6 +55,7 @@
|
|
|
53
55
|
"devDependencies": {
|
|
54
56
|
"@effect/tsgo": "0.64.1",
|
|
55
57
|
"@types/bun": "1.4.4",
|
|
58
|
+
"fast-check": "4.10.2",
|
|
56
59
|
"oxlint": "1.91.0",
|
|
57
60
|
"typescript": "7.0.2",
|
|
58
61
|
"vitest": "5.1.0"
|