docks-kit 0.24.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 +21 -136
- package/README.md +54 -9
- package/cli/dist/docks-kit.js +24688 -0
- package/cli/docs/command-guards.md +1 -1
- package/cli/docs/install.md +30 -9
- package/cli/docs/omp-context.md +1 -1
- package/cli/docs/omp-models.md +5 -4
- package/cli/docs/sync-layers.md +46 -75
- package/cli/docs/toolchain.md +4 -5
- 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 +90 -31
- package/cli/src/engine-native/DESIGN.md +5 -6
- package/cli/src/engine-native/engineCtx.ts +0 -3
- package/cli/src/engine-native/failures.ts +2 -2
- package/cli/src/engine-native/ompChild.ts +1 -1
- package/cli/src/engine-native/ompKitPlugin.ts +7 -16
- package/cli/src/engine-native/ompPlugins.ts +205 -221
- package/cli/src/engine-native/ompSync.ts +5 -14
- package/cli/src/generated/sotPayload.ts +308 -12
- 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/cli/tsconfig.json +1 -0
- package/package.json +7 -4
- package/cli/src/engine-native/ompMarketplace.ts +0 -140
|
@@ -0,0 +1,786 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `docks-kit agent-docs agent-first detect | check | convert-agent <path>`: detect the agent-doc state of a
|
|
3
|
+
* repository (Step 0 of agent-first-setup), run the agent-first check C1 to C10 (Step 3), and convert one Claude Code
|
|
4
|
+
* agent file to the omp form (the .claude cleanup of Step 2a). Each command reads only; none writes a file. The
|
|
5
|
+
* meaning of each line and the reaction to it live in the SKILL.md of agent-first-setup. Run it from any folder inside
|
|
6
|
+
* the repository, or from the folder to check outside git.
|
|
7
|
+
*
|
|
8
|
+
* Output lines:
|
|
9
|
+
* detect the repository root (the current folder outside git); then `root AGENTS.md: present|missing`,
|
|
10
|
+
* `.agents/skills: present|missing`; the legacy `.claude` lines (see `legacyClaudeLines`); one
|
|
11
|
+
* `legacy: <path>` line for each CLAUDE.md and .claude/CLAUDE.md (the root ones also when git ignores
|
|
12
|
+
* them), one `personal: <path>` line for each CLAUDE.local.md, one `node: <path>` line for each AGENTS.md
|
|
13
|
+
* below the root (none under node_modules), one `not-a-symlink: <path>` line for each `.claude/skills`
|
|
14
|
+
* entry that is no symlink; then the lines of `pr-template detect` and `verify-skill detect`. A listing
|
|
15
|
+
* that fails prints `ERROR <label>: file listing failed (see the message above)` in place of the lines of
|
|
16
|
+
* that label; the label of the `.claude` entries is `legacy entries:`.
|
|
17
|
+
* check one `FAIL C<n> ...` (a contract break), `FINDING C<n> ...` (a risk or cleanup item a human judges), or
|
|
18
|
+
* `ERROR C<n> ...` (a check that could not run) line per problem, in the order C1 to C10. No output means
|
|
19
|
+
* every check passed.
|
|
20
|
+
* convert-agent
|
|
21
|
+
* the omp agent text of the Claude agent file at <path> (relative to the current folder): `name`,
|
|
22
|
+
* `description`, and `tools` with omp tool names, then the body. The dropped `model`, `color`, and
|
|
23
|
+
* `effort` fields are named on stderr. An agent that has no exact omp form gives one
|
|
24
|
+
* `ERROR convert-agent <path>: <reason>; port it by hand` line and no agent text.
|
|
25
|
+
* Paths are relative to the repository root, without a leading `./`. Outside git, the listings walk the folder and
|
|
26
|
+
* skip each .git, node_modules, and vendor folder.
|
|
27
|
+
*
|
|
28
|
+
* Exit status: 2 after an ERROR line (its cause is on stderr, or in the line for a refused agent), 1 for a usage
|
|
29
|
+
* error, otherwise 0.
|
|
30
|
+
*/
|
|
31
|
+
import path from "node:path";
|
|
32
|
+
|
|
33
|
+
import { Effect, Schema } from "effect";
|
|
34
|
+
|
|
35
|
+
import type { SpawnError } from "../plan/types";
|
|
36
|
+
import { prTemplateLines } from "./prTemplate";
|
|
37
|
+
import {
|
|
38
|
+
AgentDocsFiles,
|
|
39
|
+
type AgentDocsGit,
|
|
40
|
+
errorDetail,
|
|
41
|
+
printLines,
|
|
42
|
+
writeStderr,
|
|
43
|
+
writeStdout,
|
|
44
|
+
} from "./services";
|
|
45
|
+
import {
|
|
46
|
+
AGENT_FIRST_PRUNE,
|
|
47
|
+
agentsDocs,
|
|
48
|
+
asciiLower,
|
|
49
|
+
byteOrder,
|
|
50
|
+
CODE_SPAN,
|
|
51
|
+
type CheckError,
|
|
52
|
+
claudeSkillsInRepository,
|
|
53
|
+
durableDocScan,
|
|
54
|
+
eachGuarded,
|
|
55
|
+
type FileListing,
|
|
56
|
+
findEntries,
|
|
57
|
+
guarded,
|
|
58
|
+
isAgentsLink,
|
|
59
|
+
isFile,
|
|
60
|
+
isFolder,
|
|
61
|
+
legacyClaudeEntries,
|
|
62
|
+
legacyClaudeLines,
|
|
63
|
+
type Listing,
|
|
64
|
+
listFiles,
|
|
65
|
+
nestedNodes,
|
|
66
|
+
proseLines,
|
|
67
|
+
ROOT_CONTEXT_FILES,
|
|
68
|
+
ROOT_PERSONAL_FILES,
|
|
69
|
+
readFolder,
|
|
70
|
+
readText,
|
|
71
|
+
repositoryRoot,
|
|
72
|
+
type RoutingGaps,
|
|
73
|
+
routingGaps,
|
|
74
|
+
SPACE,
|
|
75
|
+
textLines,
|
|
76
|
+
UsageError,
|
|
77
|
+
withRootFiles,
|
|
78
|
+
} from "./shared";
|
|
79
|
+
import { verifySkillLines } from "./verifySkill";
|
|
80
|
+
|
|
81
|
+
const USAGE = "usage: docks-kit agent-docs agent-first detect | check | convert-agent <path>";
|
|
82
|
+
const ROOT_AGENTS = "AGENTS.md";
|
|
83
|
+
const CLAUDE_SKILLS = ".claude/skills";
|
|
84
|
+
const VERIFY_SKILL = ".agents/skills/verify/SKILL.md";
|
|
85
|
+
const PR_NONE_LINE = "pull-request template: none";
|
|
86
|
+
const PR_UNUSABLE_PREFIX = "pull-request template: unusable ";
|
|
87
|
+
const PR_ERROR_LINE = "ERROR pull-request template check failed (see the message above)";
|
|
88
|
+
const VERIFY_UNVERIFIED_PREFIX = "verify unverified: ";
|
|
89
|
+
const NODE_LINE_LIMIT = 500;
|
|
90
|
+
const STALE_TOLERANCE = /pointers (here )?name concepts/u;
|
|
91
|
+
const DESCRIPTION_BLOCK = new RegExp(`^description:[${SPACE}]*[>|][-+]?[${SPACE}]*$`, "u");
|
|
92
|
+
const DESCRIPTION_VALUE = new RegExp(`^description:[${SPACE}]*["']?`, "u");
|
|
93
|
+
// awk's NF counts fields split on spaces, tabs, and newlines only.
|
|
94
|
+
const AWK_FIELD = /[^ \t\n]/u;
|
|
95
|
+
const LEADING_SPACE = new RegExp(`^[${SPACE}]+`, "u");
|
|
96
|
+
const EAGER_IMPORT = new RegExp(
|
|
97
|
+
`(^|[${SPACE}(\\[])@[A-Za-z0-9._~/-]*[A-Za-z0-9_-]\\.[A-Za-z0-9]+`,
|
|
98
|
+
"u",
|
|
99
|
+
);
|
|
100
|
+
|
|
101
|
+
/** `grep -E pattern file`: true when a line of `text` matches. */
|
|
102
|
+
const anyLine = (text: string, pattern: RegExp): boolean =>
|
|
103
|
+
textLines(text).some((line) => pattern.test(line));
|
|
104
|
+
|
|
105
|
+
/** `wc -l`: the number of newline bytes, or null when no file is there. */
|
|
106
|
+
const lineCount = Effect.fn("agentFirst.lineCount")(function* (file: string) {
|
|
107
|
+
const text = yield* readText(file, "latin1");
|
|
108
|
+
return text === null ? null : text.split("\n").length - 1;
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
/** The repository: its root and whether git answers for it. */
|
|
112
|
+
interface Repository {
|
|
113
|
+
readonly root: string;
|
|
114
|
+
readonly inGit: boolean;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** The listings of one repository; each lists anew when it runs. */
|
|
118
|
+
interface Listings {
|
|
119
|
+
readonly tracked: (...pathspecs: ReadonlyArray<string>) => FileListing;
|
|
120
|
+
readonly legacy: () => FileListing;
|
|
121
|
+
readonly personal: () => FileListing;
|
|
122
|
+
readonly agentsDocs: () => FileListing;
|
|
123
|
+
readonly nodes: () => FileListing;
|
|
124
|
+
readonly routingGaps: () => Effect.Effect<
|
|
125
|
+
RoutingGaps,
|
|
126
|
+
CheckError | SpawnError,
|
|
127
|
+
AgentDocsFiles | AgentDocsGit
|
|
128
|
+
>;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
function repositoryListings(repo: Repository): Listings {
|
|
132
|
+
const listing: Listing = { root: repo.root, prune: AGENT_FIRST_PRUNE, inGit: repo.inGit };
|
|
133
|
+
return {
|
|
134
|
+
tracked: (...pathspecs) => listFiles({ ...listing, pathspecs, excludeStandard: true }),
|
|
135
|
+
// Each CLAUDE.md and .claude/CLAUDE.md; the root ones also when git ignores them, because omp loads them.
|
|
136
|
+
legacy: () =>
|
|
137
|
+
Effect.flatMap(
|
|
138
|
+
listFiles({ ...listing, pathspecs: [":(glob)**/CLAUDE.md"], excludeStandard: true }),
|
|
139
|
+
(files) => withRootFiles(files, ROOT_CONTEXT_FILES),
|
|
140
|
+
),
|
|
141
|
+
// CLAUDE.local.md is usually gitignored, so this listing keeps ignored files.
|
|
142
|
+
personal: () =>
|
|
143
|
+
Effect.flatMap(listFiles({ ...listing, pathspecs: [":(glob)**/CLAUDE.local.md"] }), (files) =>
|
|
144
|
+
withRootFiles(files, ROOT_PERSONAL_FILES),
|
|
145
|
+
),
|
|
146
|
+
agentsDocs: () => agentsDocs(listing),
|
|
147
|
+
nodes: () => nestedNodes(listing),
|
|
148
|
+
routingGaps: () => routingGaps(listing),
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
// --- detect (Step 0) ---
|
|
153
|
+
|
|
154
|
+
const presence = (label: string, present: boolean): string =>
|
|
155
|
+
`${label}: ${present ? "present" : "missing"}`;
|
|
156
|
+
|
|
157
|
+
const detectLines = Effect.fn("agentFirst.detectLines")(function* (repo: Repository) {
|
|
158
|
+
const list = repositoryListings(repo);
|
|
159
|
+
const pr = yield* prTemplateLines(repo.inGit ? repo.root : null);
|
|
160
|
+
return [
|
|
161
|
+
presence("root AGENTS.md", yield* isFile(ROOT_AGENTS)),
|
|
162
|
+
presence(".agents/skills", yield* isFolder(".agents/skills")),
|
|
163
|
+
...(yield* guarded("legacy entries:", legacyClaudeLines())),
|
|
164
|
+
...(yield* guarded(
|
|
165
|
+
"legacy:",
|
|
166
|
+
Effect.map(list.legacy(), (files) => files.map((file) => `legacy: ${file}`)),
|
|
167
|
+
)),
|
|
168
|
+
...(yield* guarded(
|
|
169
|
+
"personal:",
|
|
170
|
+
Effect.map(list.personal(), (files) => files.map((file) => `personal: ${file}`)),
|
|
171
|
+
)),
|
|
172
|
+
...(yield* guarded(
|
|
173
|
+
"node:",
|
|
174
|
+
Effect.map(list.nodes(), (nodes) => nodes.map((node) => `node: ${node}`)),
|
|
175
|
+
)),
|
|
176
|
+
...(yield* guarded(
|
|
177
|
+
"not-a-symlink:",
|
|
178
|
+
Effect.gen(function* () {
|
|
179
|
+
if (!(yield* claudeSkillsInRepository())) return [];
|
|
180
|
+
return (yield* findEntries(CLAUDE_SKILLS))
|
|
181
|
+
.filter((entry) => entry.kind !== "symlink")
|
|
182
|
+
.map((entry) => `not-a-symlink: ${CLAUDE_SKILLS}/${entry.name}`);
|
|
183
|
+
}),
|
|
184
|
+
)),
|
|
185
|
+
// The shell wrapper dropped the lines found before a failure and printed only its ERROR line.
|
|
186
|
+
...(pr.ok ? pr.lines : [PR_ERROR_LINE]),
|
|
187
|
+
...(yield* verifySkillLines()).lines,
|
|
188
|
+
];
|
|
189
|
+
});
|
|
190
|
+
|
|
191
|
+
// --- check (Step 3) ---
|
|
192
|
+
|
|
193
|
+
const rootCommandLines = Effect.fn("agentFirst.rootCommandLines")(function* () {
|
|
194
|
+
if (!(yield* isFile(ROOT_AGENTS))) return ["FAIL C1 root AGENTS.md missing"];
|
|
195
|
+
const text = asciiLower((yield* readText(ROOT_AGENTS)) ?? "");
|
|
196
|
+
// `grep -qiw <kind>`: the kind as a whole word, in any ASCII letter case.
|
|
197
|
+
const names = (kind: string): boolean =>
|
|
198
|
+
anyLine(text, new RegExp(`(^|[^a-z0-9_])${kind}([^a-z0-9_]|$)`, "u"));
|
|
199
|
+
return ["build", "test", "lint"]
|
|
200
|
+
.filter((kind) => !names(kind))
|
|
201
|
+
.map(
|
|
202
|
+
(kind) =>
|
|
203
|
+
`FINDING C1 root AGENTS.md names no ${kind} command (add it, or accept: the repo has none or one gate covers it)`,
|
|
204
|
+
);
|
|
205
|
+
});
|
|
206
|
+
|
|
207
|
+
const routingLines = Effect.fn("agentFirst.routingLines")(function* (list: Listings) {
|
|
208
|
+
const { unroutedNodes, deadRoutes } = yield* list.routingGaps();
|
|
209
|
+
return [
|
|
210
|
+
...unroutedNodes.map((node) => `FAIL C2 node not routed from root: ${node}`),
|
|
211
|
+
...deadRoutes.map((route) => `FAIL C2 dead route in root table: ${route}`),
|
|
212
|
+
];
|
|
213
|
+
});
|
|
214
|
+
|
|
215
|
+
const MIGRATE = "migrate it with claude-md-migration";
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* The C3 line for one CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md, as omp loads it: a link to the AGENTS.md of
|
|
219
|
+
* its folder holds no text to migrate, a .claude/CLAUDE.md wins over the AGENTS.md of the folder where a session
|
|
220
|
+
* starts, a CLAUDE.md next to an AGENTS.md is ignored, a CLAUDE.md alone at its depth loads, and omp does not load a
|
|
221
|
+
* CLAUDE.local.md.
|
|
222
|
+
*/
|
|
223
|
+
const claudeFileLine = Effect.fn("agentFirst.claudeFileLine")(function* (file: string) {
|
|
224
|
+
const folder = path.posix.dirname(file);
|
|
225
|
+
if (path.posix.basename(file) === "CLAUDE.local.md") {
|
|
226
|
+
return `FINDING C3 CLAUDE.local.md that omp does not load (personal file; the user decides: list it in contextFiles.extra, move it to ~/.omp/agent/AGENTS.md, or keep it): ${file}`;
|
|
227
|
+
}
|
|
228
|
+
if (yield* isAgentsLink(file)) {
|
|
229
|
+
return `FAIL C3 CLAUDE.md link to AGENTS.md (remove the link; there is nothing to migrate): ${file}`;
|
|
230
|
+
}
|
|
231
|
+
if (path.posix.basename(folder) === ".claude") {
|
|
232
|
+
return `FAIL C3 .claude/CLAUDE.md (omp loads it instead of the AGENTS.md of that folder when a session starts there; ${MIGRATE}): ${file}`;
|
|
233
|
+
}
|
|
234
|
+
if (yield* isFile(folder === "." ? ROOT_AGENTS : `${folder}/${ROOT_AGENTS}`)) {
|
|
235
|
+
return `FAIL C3 CLAUDE.md next to an AGENTS.md (omp ignores it; ${MIGRATE}): ${file}`;
|
|
236
|
+
}
|
|
237
|
+
return `FINDING C3 CLAUDE.md without an AGENTS.md next to it (it loads, but AGENTS.md is the convention; ${MIGRATE}): ${file}`;
|
|
238
|
+
});
|
|
239
|
+
|
|
240
|
+
const claudeFileLines = Effect.fn("agentFirst.claudeFileLines")(function* (list: Listings) {
|
|
241
|
+
const files = new Set([...(yield* list.legacy()), ...(yield* list.personal())]);
|
|
242
|
+
return yield* eachGuarded("C3", [...files].sort(byteOrder), (file) =>
|
|
243
|
+
Effect.map(claudeFileLine(file), (line) => [line]),
|
|
244
|
+
);
|
|
245
|
+
});
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* The names that `.claude/skills/*` expands to: no dot names, in byte order, through a symlinked `.claude/skills` too.
|
|
249
|
+
*/
|
|
250
|
+
const skillGlobNames = Effect.fn("agentFirst.skillGlobNames")(function* () {
|
|
251
|
+
return (yield* readFolder(CLAUDE_SKILLS))
|
|
252
|
+
.map((entry) => entry.name)
|
|
253
|
+
.filter((name) => !name.startsWith("."))
|
|
254
|
+
.sort(byteOrder);
|
|
255
|
+
});
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* C4: each `.claude/skills` entry, each Claude agent file, and each Claude settings file is a legacy entry that the
|
|
259
|
+
* cleanup of agent-first-setup handles. A `.claude` link to a place outside the repository and each other `.claude/`
|
|
260
|
+
* entry are only reported.
|
|
261
|
+
*/
|
|
262
|
+
const legacyEntryLines = Effect.fn("agentFirst.legacyEntryLines")(function* () {
|
|
263
|
+
const { external, skills, agents, settings, others } = yield* legacyClaudeEntries();
|
|
264
|
+
const skillEntries =
|
|
265
|
+
skills === null ? [] : (yield* skillGlobNames()).map((name) => `${CLAUDE_SKILLS}/${name}`);
|
|
266
|
+
return [
|
|
267
|
+
...external.map(
|
|
268
|
+
(link) =>
|
|
269
|
+
`FINDING C4 legacy .claude entry outside the repository (report it; never move or remove it): ${link.path}`,
|
|
270
|
+
),
|
|
271
|
+
...[...skillEntries, ...agents, ...settings].map(
|
|
272
|
+
(entry) => `FINDING C4 legacy .claude entry (agent-first-setup cleans it up): ${entry}`,
|
|
273
|
+
),
|
|
274
|
+
...others.map(
|
|
275
|
+
(entry) => `FINDING C4 legacy .claude entry (report only; the user decides): ${entry}`,
|
|
276
|
+
),
|
|
277
|
+
];
|
|
278
|
+
});
|
|
279
|
+
|
|
280
|
+
const durableDocLines = Effect.fn("agentFirst.durableDocLines")(function* (list: Listings) {
|
|
281
|
+
const docs = yield* list.tracked(
|
|
282
|
+
":(glob)**/AGENTS.md",
|
|
283
|
+
":(glob)**/SKILL.md",
|
|
284
|
+
":(glob)**/skills/**/references/*.md",
|
|
285
|
+
":(exclude,glob)**/node_modules/**/AGENTS.md",
|
|
286
|
+
);
|
|
287
|
+
const staleLines = yield* eachGuarded("C5", yield* list.agentsDocs(), (file) =>
|
|
288
|
+
Effect.map(readText(file), (text) =>
|
|
289
|
+
STALE_TOLERANCE.test(asciiLower(text ?? ""))
|
|
290
|
+
? []
|
|
291
|
+
: [`FINDING C5 no stale-tolerance line: ${file}`],
|
|
292
|
+
),
|
|
293
|
+
);
|
|
294
|
+
const scanLines = yield* durableDocScan(docs, { findingLabel: "FINDING C5", errorLabel: "C5" });
|
|
295
|
+
// A file that cannot be read gives one ERROR line, not one for each part of C5.
|
|
296
|
+
return [
|
|
297
|
+
...scanLines,
|
|
298
|
+
...staleLines.filter((line) => !(line.startsWith("ERROR") && scanLines.includes(line))),
|
|
299
|
+
];
|
|
300
|
+
});
|
|
301
|
+
|
|
302
|
+
/**
|
|
303
|
+
* The start of a skill description: the first indented line of a block scalar (`>`, `|`, `>-`, `|-`), else the value
|
|
304
|
+
* after `description:` without an opening quote; null when the file has no description or no file is there.
|
|
305
|
+
*/
|
|
306
|
+
function descriptionStart(text: string | null): string | null {
|
|
307
|
+
let inBlock = false;
|
|
308
|
+
for (const line of textLines(text ?? "")) {
|
|
309
|
+
if (DESCRIPTION_BLOCK.test(line)) inBlock = true;
|
|
310
|
+
else if (inBlock && AWK_FIELD.test(line)) return line.replace(LEADING_SPACE, "");
|
|
311
|
+
else if (line.startsWith("description:")) return line.replace(DESCRIPTION_VALUE, "");
|
|
312
|
+
}
|
|
313
|
+
return null;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
const descriptionLines = Effect.fn("agentFirst.descriptionLines")(function* (list: Listings) {
|
|
317
|
+
return yield* eachGuarded("C6", yield* list.tracked(":(glob)**/SKILL.md"), (skill) =>
|
|
318
|
+
Effect.map(readText(skill), (text) =>
|
|
319
|
+
descriptionStart(text)?.startsWith("Use when")
|
|
320
|
+
? []
|
|
321
|
+
: [`FAIL C6 description does not start with 'Use when': ${skill}`],
|
|
322
|
+
),
|
|
323
|
+
);
|
|
324
|
+
});
|
|
325
|
+
|
|
326
|
+
/** The bare `@path` imports of one line outside code spans, each without its `@`. */
|
|
327
|
+
function eagerImports(line: string): Array<string> {
|
|
328
|
+
const imports: Array<string> = [];
|
|
329
|
+
let rest = line.replace(CODE_SPAN, "");
|
|
330
|
+
for (let match = EAGER_IMPORT.exec(rest); match !== null; match = EAGER_IMPORT.exec(rest)) {
|
|
331
|
+
imports.push(match[0].replace(/^[^@]*@/u, ""));
|
|
332
|
+
rest = rest.slice(match.index + match[0].length);
|
|
333
|
+
}
|
|
334
|
+
return imports;
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/** Where an import points: absolute, from the home folder, or from the file's folder. */
|
|
338
|
+
const importTarget = Effect.fn("agentFirst.importTarget")(function* (
|
|
339
|
+
importPath: string,
|
|
340
|
+
file: string,
|
|
341
|
+
) {
|
|
342
|
+
if (importPath.startsWith("/")) return importPath;
|
|
343
|
+
if (importPath.startsWith("~/")) {
|
|
344
|
+
const files = yield* AgentDocsFiles;
|
|
345
|
+
return `${(yield* files.home) ?? ""}/${importPath.slice(2)}`;
|
|
346
|
+
}
|
|
347
|
+
return `${path.posix.dirname(file)}/${importPath}`;
|
|
348
|
+
});
|
|
349
|
+
|
|
350
|
+
const eagerImportLine = Effect.fn("agentFirst.eagerImportLine")(function* (
|
|
351
|
+
file: string,
|
|
352
|
+
number: number,
|
|
353
|
+
importPath: string,
|
|
354
|
+
) {
|
|
355
|
+
const target = yield* importTarget(importPath, file);
|
|
356
|
+
const at = `FINDING C7 eager import ${file}:${number}: @${importPath}`;
|
|
357
|
+
if (!(yield* isFile(target))) return `${at} (no file at ${target})`;
|
|
358
|
+
return `${at} (${target}, ${(yield* lineCount(target)) ?? ""} lines, omp expands it when this file loads)`;
|
|
359
|
+
});
|
|
360
|
+
|
|
361
|
+
/** omp expands each bare `@path` in an AGENTS.md into context every time that file loads. */
|
|
362
|
+
const eagerImportLines = Effect.fn("agentFirst.eagerImportLines")(function* (list: Listings) {
|
|
363
|
+
return yield* eachGuarded("C7", yield* list.agentsDocs(), (file) =>
|
|
364
|
+
Effect.gen(function* () {
|
|
365
|
+
const lines: Array<string> = [];
|
|
366
|
+
for (const [number, line] of proseLines((yield* readText(file)) ?? ""))
|
|
367
|
+
lines.push(
|
|
368
|
+
...(yield* eachGuarded("C7", eagerImports(line), (importPath) =>
|
|
369
|
+
Effect.map(eagerImportLine(file, number, importPath), (found) => [found]),
|
|
370
|
+
)),
|
|
371
|
+
);
|
|
372
|
+
return lines;
|
|
373
|
+
}),
|
|
374
|
+
);
|
|
375
|
+
});
|
|
376
|
+
|
|
377
|
+
const nodeSizeLines = Effect.fn("agentFirst.nodeSizeLines")(function* (list: Listings) {
|
|
378
|
+
return yield* eachGuarded("C8", yield* list.agentsDocs(), (file) =>
|
|
379
|
+
Effect.map(lineCount(file), (lines) =>
|
|
380
|
+
lines === null || lines <= NODE_LINE_LIMIT
|
|
381
|
+
? []
|
|
382
|
+
: [`FINDING C8 over the ${NODE_LINE_LIMIT}-line kit policy: ${file} (${lines} lines)`],
|
|
383
|
+
),
|
|
384
|
+
);
|
|
385
|
+
});
|
|
386
|
+
|
|
387
|
+
/** C9 from the verify Detect lines: the skill exists, and every command of it showed its expected result. */
|
|
388
|
+
const verifySkillCheckLines = Effect.fn("agentFirst.verifySkillCheckLines")(function* () {
|
|
389
|
+
const detect = yield* verifySkillLines();
|
|
390
|
+
if (detect.lines.includes("verify skill: missing")) {
|
|
391
|
+
return [
|
|
392
|
+
"FINDING C9 no .agents/skills/verify/SKILL.md (add it in Step 2b, or accept: the repo has no runnable surface)",
|
|
393
|
+
];
|
|
394
|
+
}
|
|
395
|
+
const lines: Array<string> = [];
|
|
396
|
+
for (const line of detect.lines.filter((l) => l.startsWith(VERIFY_UNVERIFIED_PREFIX))) {
|
|
397
|
+
const mark = line.slice(VERIFY_UNVERIFIED_PREFIX.length);
|
|
398
|
+
lines.push(
|
|
399
|
+
`FAIL C9 unverified command (rerun every command in Step 2b): ${VERIFY_SKILL}:${mark}`,
|
|
400
|
+
);
|
|
401
|
+
}
|
|
402
|
+
if (!detect.ok) lines.push(`ERROR C9 cannot read ${VERIFY_SKILL}`);
|
|
403
|
+
return lines;
|
|
404
|
+
});
|
|
405
|
+
|
|
406
|
+
/** An error is not a missing template, so it gets its own line. */
|
|
407
|
+
const prTemplateCheckLines = Effect.fn("agentFirst.prTemplateCheckLines")(function* (
|
|
408
|
+
repo: Repository,
|
|
409
|
+
) {
|
|
410
|
+
const pr = yield* prTemplateLines(repo.inGit ? repo.root : null);
|
|
411
|
+
if (!pr.ok) return ["ERROR C10 pull-request template check failed (see the message above)"];
|
|
412
|
+
const lines = pr.lines
|
|
413
|
+
.filter((line) => line.startsWith(PR_UNUSABLE_PREFIX))
|
|
414
|
+
.map(
|
|
415
|
+
(line) =>
|
|
416
|
+
`FINDING C10 unusable pull-request template: ${line.slice(PR_UNUSABLE_PREFIX.length)}`,
|
|
417
|
+
);
|
|
418
|
+
if (pr.lines.some((line) => line.includes(PR_NONE_LINE))) {
|
|
419
|
+
lines.push(
|
|
420
|
+
"FINDING C10 no usable pull-request template (add it in Step 2c, or accept: the repository wants none)",
|
|
421
|
+
);
|
|
422
|
+
}
|
|
423
|
+
return lines;
|
|
424
|
+
});
|
|
425
|
+
|
|
426
|
+
const checkLines = Effect.fn("agentFirst.checkLines")(function* (repo: Repository) {
|
|
427
|
+
const list = repositoryListings(repo);
|
|
428
|
+
return [
|
|
429
|
+
...(yield* guarded("C1", rootCommandLines())),
|
|
430
|
+
...(yield* guarded("C2", routingLines(list))),
|
|
431
|
+
...(yield* guarded("C3", claudeFileLines(list))),
|
|
432
|
+
...(yield* guarded("C4", legacyEntryLines())),
|
|
433
|
+
...(yield* guarded("C5", durableDocLines(list))),
|
|
434
|
+
...(yield* guarded("C6", descriptionLines(list))),
|
|
435
|
+
...(yield* guarded("C7", eagerImportLines(list))),
|
|
436
|
+
...(yield* guarded("C8", nodeSizeLines(list))),
|
|
437
|
+
...(yield* verifySkillCheckLines()),
|
|
438
|
+
...(yield* prTemplateCheckLines(repo)),
|
|
439
|
+
];
|
|
440
|
+
});
|
|
441
|
+
|
|
442
|
+
// --- convert-agent (the .claude cleanup of Step 2a) ---
|
|
443
|
+
|
|
444
|
+
const FRONTMATTER_FENCE = "---";
|
|
445
|
+
const AGENT_FIELD = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/u;
|
|
446
|
+
const CONTINUATION = /^([ \t]|-[ \t]|$)/u;
|
|
447
|
+
// The values that leave a `name` or a `description` empty: the YAML 1.2 core-schema null forms.
|
|
448
|
+
const EMPTY_VALUES: ReadonlySet<string> = new Set(["", "~", "null", "Null", "NULL"]);
|
|
449
|
+
// The plain values that a YAML 1.2 core-schema reader reads as a boolean or a number, not as a string. Only these
|
|
450
|
+
// spellings count, so `tRue`, `.iNf`, and `0X1F` stay strings.
|
|
451
|
+
const NON_STRING_PLAIN =
|
|
452
|
+
/^(true|True|TRUE|false|False|FALSE|0o[0-7]+|0x[0-9a-fA-F]+|[-+]?(\.[0-9]+|[0-9]+(\.[0-9]*)?)([eE][-+]?[0-9]+)?|[-+]?\.(inf|Inf|INF)|\.(nan|NaN|NAN))$/u;
|
|
453
|
+
// The start of a plain value that makes it a flow collection, an alias, a block sequence, a mapping key, or a
|
|
454
|
+
// reserved indicator, not a string.
|
|
455
|
+
const NON_STRING_START = /^([[\]{},*%@`]|[-?]([ \t]|$))/u;
|
|
456
|
+
// An anchor or a tag; the value may still be a string, but this command does not resolve it.
|
|
457
|
+
const ANCHOR_OR_TAG_START = /^[&!]/u;
|
|
458
|
+
// A quoted scalar is always a string.
|
|
459
|
+
const QUOTED_START = /^["']/u;
|
|
460
|
+
// A block scalar starts with `|` or `>`; its header may add an indentation indicator (1 to 9) and a chomping
|
|
461
|
+
// indicator (`+` or `-`) in either order, and nothing else but a comment.
|
|
462
|
+
const BLOCK_SCALAR_START = /^[|>]/u;
|
|
463
|
+
const BLOCK_SCALAR_HEADER = /^[|>]([1-9][-+]?|[-+][1-9]?)?$/u;
|
|
464
|
+
// omp reserves these agent names (omp://task-agent-discovery.md, agent definition shape).
|
|
465
|
+
const RESERVED_AGENT_NAMES: ReadonlySet<string> = new Set(["main", "sub"]);
|
|
466
|
+
// The setup writes `.omp/agents/<name>.md`, so a name must be one safe file name.
|
|
467
|
+
const SAFE_AGENT_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/u;
|
|
468
|
+
// The Claude agent fields that convert: the first three stay, the others are dropped, because omp would misread them
|
|
469
|
+
// (a Claude model alias fails in omp).
|
|
470
|
+
const KEPT_AGENT_FIELDS: ReadonlyArray<string> = ["name", "description", "tools"];
|
|
471
|
+
const DROPPED_AGENT_FIELDS: ReadonlyArray<string> = ["model", "color", "effort"];
|
|
472
|
+
// Each Claude Code tool that has one omp tool for the same work.
|
|
473
|
+
const OMP_TOOL_NAMES: ReadonlyMap<string, string> = new Map([
|
|
474
|
+
["Read", "read"],
|
|
475
|
+
["Grep", "grep"],
|
|
476
|
+
["Glob", "glob"],
|
|
477
|
+
["Bash", "bash"],
|
|
478
|
+
["Edit", "edit"],
|
|
479
|
+
["Write", "write"],
|
|
480
|
+
["WebSearch", "web_search"],
|
|
481
|
+
]);
|
|
482
|
+
|
|
483
|
+
/** A Claude agent that has no exact omp form; the user ports it by hand. The pure parser throws it. */
|
|
484
|
+
class Refusal extends Error {}
|
|
485
|
+
|
|
486
|
+
/** A refused agent. The command edge prints `ERROR convert-agent <file>: <reason>; port it by hand` and exits 2. */
|
|
487
|
+
export class AgentRefusal extends Schema.TaggedError<
|
|
488
|
+
AgentRefusal,
|
|
489
|
+
{ readonly brand: unique symbol }
|
|
490
|
+
>()("AgentRefusal", {
|
|
491
|
+
file: Schema.String,
|
|
492
|
+
reason: Schema.String,
|
|
493
|
+
}) {}
|
|
494
|
+
|
|
495
|
+
/**
|
|
496
|
+
* An agent file that cannot be read. The command edge names `detail` (the error code or message) on stderr, prints
|
|
497
|
+
* `ERROR convert-agent <file>: cannot read the file`, and exits 2.
|
|
498
|
+
*/
|
|
499
|
+
export class AgentUnreadable extends Schema.TaggedError<
|
|
500
|
+
AgentUnreadable,
|
|
501
|
+
{ readonly brand: unique symbol }
|
|
502
|
+
>()("AgentUnreadable", {
|
|
503
|
+
file: Schema.String,
|
|
504
|
+
detail: Schema.String,
|
|
505
|
+
}) {}
|
|
506
|
+
|
|
507
|
+
interface AgentParts {
|
|
508
|
+
readonly fields: Map<string, Array<string>>;
|
|
509
|
+
readonly body: string;
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
/**
|
|
513
|
+
* The frontmatter fields of an agent file, each as its field line and its continuation lines (indented lines, list
|
|
514
|
+
* items, and blank lines), and the body after the closing fence.
|
|
515
|
+
*/
|
|
516
|
+
function agentParts(text: string): AgentParts {
|
|
517
|
+
const lines = text.replace(/\r\n/gu, "\n").split("\n");
|
|
518
|
+
const close = lines.indexOf(FRONTMATTER_FENCE, 1);
|
|
519
|
+
if (lines[0] !== FRONTMATTER_FENCE || close === -1) throw new Refusal("no frontmatter");
|
|
520
|
+
const fields = new Map<string, Array<string>>();
|
|
521
|
+
let current: Array<string> | null = null;
|
|
522
|
+
for (const line of lines.slice(1, close)) {
|
|
523
|
+
const field = AGENT_FIELD.exec(line);
|
|
524
|
+
if (field !== null) {
|
|
525
|
+
const name = field[1] ?? "";
|
|
526
|
+
if (fields.has(name)) throw new Refusal(`field ${name} appears twice`);
|
|
527
|
+
current = [line];
|
|
528
|
+
fields.set(name, current);
|
|
529
|
+
} else if (current !== null && CONTINUATION.test(line)) current.push(line);
|
|
530
|
+
else if (!line.startsWith("#")) throw new Refusal(`frontmatter line "${line}" is no field`);
|
|
531
|
+
}
|
|
532
|
+
// A blank line between two fields belongs to neither.
|
|
533
|
+
for (const fieldLines of fields.values())
|
|
534
|
+
while (fieldLines.at(-1)?.trim() === "") fieldLines.pop();
|
|
535
|
+
return { fields, body: lines.slice(close + 1).join("\n") };
|
|
536
|
+
}
|
|
537
|
+
|
|
538
|
+
/** Split a tool list at each comma outside parentheses, so `Bash(a, b)` stays one tool. */
|
|
539
|
+
function splitTools(text: string): Array<string> {
|
|
540
|
+
const tools = [""];
|
|
541
|
+
let depth = 0;
|
|
542
|
+
for (const char of text) {
|
|
543
|
+
if (char === "(") depth += 1;
|
|
544
|
+
else if (char === ")") depth = Math.max(0, depth - 1);
|
|
545
|
+
if (char === "," && depth === 0) tools.push("");
|
|
546
|
+
else tools[tools.length - 1] += char;
|
|
547
|
+
}
|
|
548
|
+
return tools;
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
/**
|
|
552
|
+
* The index of the quote that closes the quoted scalar that opens at `start`, or -1. In double quotes a `\` escapes
|
|
553
|
+
* the next character; in single quotes `''` is one quote.
|
|
554
|
+
*/
|
|
555
|
+
function closingQuote(text: string, start: number): number {
|
|
556
|
+
const quote = text[start];
|
|
557
|
+
for (let i = start + 1; i < text.length; i += 1) {
|
|
558
|
+
if (quote === '"' && text[i] === "\\") i += 1;
|
|
559
|
+
else if (text[i] === quote) {
|
|
560
|
+
if (quote === "'" && text[i + 1] === "'") i += 1;
|
|
561
|
+
else return i;
|
|
562
|
+
}
|
|
563
|
+
}
|
|
564
|
+
return -1;
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
/** True when a quote at `i` opens a quoted scalar: at the start, or after a space, a tab, `[`, or `,`. */
|
|
568
|
+
const isValueStart = (line: string, i: number): boolean =>
|
|
569
|
+
i === 0 || /[ \t[,]/u.test(line[i - 1] ?? "");
|
|
570
|
+
|
|
571
|
+
/**
|
|
572
|
+
* One YAML line without a trailing comment: a `#` at the start or after a space or a tab, outside quotes. A quote
|
|
573
|
+
* opens a quoted scalar only where a value starts, so the apostrophe in `don't` opens none.
|
|
574
|
+
*/
|
|
575
|
+
function withoutComment(line: string): string {
|
|
576
|
+
for (let i = 0; i < line.length; i += 1) {
|
|
577
|
+
if (isValueStart(line, i) && (line[i] === '"' || line[i] === "'")) {
|
|
578
|
+
const end = closingQuote(line, i);
|
|
579
|
+
if (end === -1) break;
|
|
580
|
+
i = end;
|
|
581
|
+
} else if (line[i] === "#" && (i === 0 || line[i - 1] === " " || line[i - 1] === "\t")) {
|
|
582
|
+
return line.slice(0, i).trimEnd();
|
|
583
|
+
}
|
|
584
|
+
}
|
|
585
|
+
return line.trimEnd();
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
/** `text` trimmed, without one pair of outer quotes when they enclose one quoted scalar, so `"a", "b"` keeps its quotes. */
|
|
589
|
+
function unquoted(text: string): string {
|
|
590
|
+
const trimmed = text.trim();
|
|
591
|
+
const opensQuote = trimmed.startsWith('"') || trimmed.startsWith("'");
|
|
592
|
+
return opensQuote && closingQuote(trimmed, 0) === trimmed.length - 1
|
|
593
|
+
? trimmed.slice(1, -1)
|
|
594
|
+
: trimmed;
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
/**
|
|
598
|
+
* The value part of each line of a scalar field: the text after the field name, then each continuation line, without
|
|
599
|
+
* its comment and trimmed.
|
|
600
|
+
*/
|
|
601
|
+
function lineParts(fieldLines: ReadonlyArray<string>): Array<string> {
|
|
602
|
+
return [(fieldLines[0] ?? "").replace(AGENT_FIELD, "$2"), ...fieldLines.slice(1)].map((line) =>
|
|
603
|
+
withoutComment(line).trim(),
|
|
604
|
+
);
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
/** The value of a scalar field: its parts that are not empty in one line, without one pair of outer quotes. */
|
|
608
|
+
function fieldValue(fieldLines: ReadonlyArray<string>): string {
|
|
609
|
+
return unquoted(
|
|
610
|
+
lineParts(fieldLines)
|
|
611
|
+
.filter((part) => part !== "")
|
|
612
|
+
.join(" "),
|
|
613
|
+
);
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
/** True when a YAML 1.2 core-schema reader keeps `text`, a plain value, as a string. */
|
|
617
|
+
function isPlainString(text: string): boolean {
|
|
618
|
+
return !NON_STRING_PLAIN.test(text) && !NON_STRING_START.test(text);
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
/**
|
|
622
|
+
* True when `part`, one line of a value, has the `key:` form of a block mapping: a `:` before a space, a tab, or the
|
|
623
|
+
* line end, outside a quoted scalar. A quote opens a quoted scalar only where a value starts, as in withoutComment.
|
|
624
|
+
*/
|
|
625
|
+
function hasMappingKey(part: string): boolean {
|
|
626
|
+
for (let i = 0; i < part.length; i += 1) {
|
|
627
|
+
if (isValueStart(part, i) && (part[i] === '"' || part[i] === "'")) {
|
|
628
|
+
const end = closingQuote(part, i);
|
|
629
|
+
if (end === -1) return false;
|
|
630
|
+
i = end;
|
|
631
|
+
} else if (
|
|
632
|
+
part[i] === ":" &&
|
|
633
|
+
(i === part.length - 1 || part[i + 1] === " " || part[i + 1] === "\t")
|
|
634
|
+
) {
|
|
635
|
+
return true;
|
|
636
|
+
}
|
|
637
|
+
}
|
|
638
|
+
return false;
|
|
639
|
+
}
|
|
640
|
+
|
|
641
|
+
/**
|
|
642
|
+
* Refuse a `name` or a `description` that is empty, or that omp would not read as a string. A block scalar needs a
|
|
643
|
+
* valid header and one content line that is not blank; its body keeps each `#`, because in a block scalar it is text.
|
|
644
|
+
* Any other value is empty when it is a null form. An anchor or a tag is refused, as this command does not resolve
|
|
645
|
+
* them. One quoted scalar is a string. A continuation line in the `key:` form makes a block mapping, and a plain value
|
|
646
|
+
* must stay a string; a value that starts on a `- ` continuation line is a block sequence.
|
|
647
|
+
*/
|
|
648
|
+
function checkStringField(field: string, fieldLines: ReadonlyArray<string>): void {
|
|
649
|
+
const parts = lineParts(fieldLines);
|
|
650
|
+
const start = parts.findIndex((part) => part !== "");
|
|
651
|
+
const first = parts[start] ?? "";
|
|
652
|
+
if (BLOCK_SCALAR_START.test(first)) {
|
|
653
|
+
if (!BLOCK_SCALAR_HEADER.test(first)) throw new Refusal(`${field} is no YAML string`);
|
|
654
|
+
if (fieldLines.slice(start + 1).every((line) => line.trim() === ""))
|
|
655
|
+
throw new Refusal(`no ${field} field`);
|
|
656
|
+
return;
|
|
657
|
+
}
|
|
658
|
+
const value = parts.filter((part) => part !== "").join(" ");
|
|
659
|
+
if (EMPTY_VALUES.has(unquoted(value))) throw new Refusal(`no ${field} field`);
|
|
660
|
+
if (ANCHOR_OR_TAG_START.test(value)) throw new Refusal(`${field} uses a YAML anchor or tag`);
|
|
661
|
+
if (QUOTED_START.test(value) && closingQuote(value, 0) === value.length - 1) return;
|
|
662
|
+
if (parts.slice(1).some(hasMappingKey)) throw new Refusal(`${field} is no YAML string`);
|
|
663
|
+
if (!QUOTED_START.test(value) && !isPlainString(value))
|
|
664
|
+
throw new Refusal(`${field} is no YAML string`);
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
/**
|
|
668
|
+
* The tool names of a `tools` field: a comma list, a flow list `[a, b]`, or a block list of `- a` items. A trailing
|
|
669
|
+
* comment goes first, then one pair of outer quotes, of the value and of each item.
|
|
670
|
+
*/
|
|
671
|
+
function toolNames(fieldLines: ReadonlyArray<string>): Array<string> {
|
|
672
|
+
const value = withoutComment((fieldLines[0] ?? "").replace(AGENT_FIELD, "$2")).trim();
|
|
673
|
+
const rest = fieldLines
|
|
674
|
+
.slice(1)
|
|
675
|
+
.map((line) => withoutComment(line).trim())
|
|
676
|
+
.filter((line) => line !== "");
|
|
677
|
+
let tools: Array<string>;
|
|
678
|
+
if (value === "") tools = rest.map((line) => line.replace(/^-[ \t]*/u, ""));
|
|
679
|
+
else {
|
|
680
|
+
const list = unquoted([value, ...rest].join(" "));
|
|
681
|
+
tools = splitTools(list.startsWith("[") && list.endsWith("]") ? list.slice(1, -1) : list);
|
|
682
|
+
}
|
|
683
|
+
return tools.map(unquoted).filter((tool) => tool !== "");
|
|
684
|
+
}
|
|
685
|
+
|
|
686
|
+
/** The omp tool name of one Claude tool, or a Refusal. */
|
|
687
|
+
function ompToolName(tool: string): string {
|
|
688
|
+
if (tool.includes("(")) throw new Refusal(`tool ${tool} has a pattern`);
|
|
689
|
+
const name = OMP_TOOL_NAMES.get(tool);
|
|
690
|
+
if (name === undefined) throw new Refusal(`tool ${tool} has no omp name`);
|
|
691
|
+
return name;
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
interface OmpAgent {
|
|
695
|
+
readonly agent: string;
|
|
696
|
+
readonly dropped: ReadonlyArray<string>;
|
|
697
|
+
}
|
|
698
|
+
|
|
699
|
+
/**
|
|
700
|
+
* The omp agent text of one Claude agent, and the names of the dropped fields. Only the simple case converts, because
|
|
701
|
+
* omp adds its MCP, extension, and custom tools to every explicit tools list, and a Claude denial has no omp form.
|
|
702
|
+
* Throws a Refusal for an agent that has no exact omp form.
|
|
703
|
+
*/
|
|
704
|
+
function ompAgent(text: string): OmpAgent {
|
|
705
|
+
const { fields, body } = agentParts(text);
|
|
706
|
+
if (fields.has("disallowedTools")) throw new Refusal("disallowedTools has no omp form");
|
|
707
|
+
for (const name of fields.keys()) {
|
|
708
|
+
if (!KEPT_AGENT_FIELDS.includes(name) && !DROPPED_AGENT_FIELDS.includes(name)) {
|
|
709
|
+
throw new Refusal(`field ${name} has no omp form`);
|
|
710
|
+
}
|
|
711
|
+
}
|
|
712
|
+
for (const field of ["name", "description"]) {
|
|
713
|
+
const fieldLines = fields.get(field);
|
|
714
|
+
if (fieldLines === undefined) throw new Refusal(`no ${field} field`);
|
|
715
|
+
checkStringField(field, fieldLines);
|
|
716
|
+
}
|
|
717
|
+
const name = fieldValue(fields.get("name") ?? []);
|
|
718
|
+
if (RESERVED_AGENT_NAMES.has(asciiLower(name)))
|
|
719
|
+
throw new Refusal(`name ${name} is reserved in omp`);
|
|
720
|
+
if (!SAFE_AGENT_NAME.test(name)) throw new Refusal(`name ${name} is not a safe file name`);
|
|
721
|
+
const toolLines = fields.get("tools");
|
|
722
|
+
const tools = toolLines === undefined ? [] : toolNames(toolLines);
|
|
723
|
+
if (tools.length === 0) throw new Refusal("no tools list");
|
|
724
|
+
const header = [
|
|
725
|
+
FRONTMATTER_FENCE,
|
|
726
|
+
// The name goes out without its quotes; a safe name that would read as a number or a boolean goes out in double
|
|
727
|
+
// quotes, so that omp still reads a string.
|
|
728
|
+
`name: ${isPlainString(name) ? name : JSON.stringify(name)}`,
|
|
729
|
+
...(fields.get("description") ?? []),
|
|
730
|
+
`tools: ${tools.map(ompToolName).join(", ")}`,
|
|
731
|
+
FRONTMATTER_FENCE,
|
|
732
|
+
];
|
|
733
|
+
return {
|
|
734
|
+
agent: `${header.join("\n")}\n${body}`,
|
|
735
|
+
dropped: DROPPED_AGENT_FIELDS.filter((field) => fields.has(field)),
|
|
736
|
+
};
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
/** Print the omp agent text of one Claude agent file on stdout; write no file. */
|
|
740
|
+
const convertAgent = Effect.fn("agentFirst.convertAgent")(function* (file: string) {
|
|
741
|
+
const files = yield* AgentDocsFiles;
|
|
742
|
+
const text = yield* files
|
|
743
|
+
.readFile(file, "utf8")
|
|
744
|
+
.pipe(
|
|
745
|
+
Effect.catchTag("FileError", (error) =>
|
|
746
|
+
Effect.fail(new AgentUnreadable({ file, detail: errorDetail(error) })),
|
|
747
|
+
),
|
|
748
|
+
);
|
|
749
|
+
const result = yield* Effect.try({
|
|
750
|
+
try: () => ompAgent(text),
|
|
751
|
+
catch: (error) =>
|
|
752
|
+
new AgentRefusal({ file, reason: error instanceof Error ? error.message : String(error) }),
|
|
753
|
+
});
|
|
754
|
+
if (result.dropped.length > 0) {
|
|
755
|
+
yield* writeStderr(
|
|
756
|
+
`convert-agent: dropped ${result.dropped.join(", ")} of ${file}; omp does not read these Claude values (a Claude model alias fails in omp)\n`,
|
|
757
|
+
);
|
|
758
|
+
}
|
|
759
|
+
yield* writeStdout(result.agent);
|
|
760
|
+
return 0;
|
|
761
|
+
});
|
|
762
|
+
|
|
763
|
+
/**
|
|
764
|
+
* Run `agent-first <args>` and return its exit status. A usage error fails with UsageError; a refused or unreadable
|
|
765
|
+
* agent fails with AgentRefusal or AgentUnreadable.
|
|
766
|
+
*/
|
|
767
|
+
export const runAgentFirst = Effect.fn("agentFirst.run")(function* (args: ReadonlyArray<string>) {
|
|
768
|
+
const [command, ...rest] = args;
|
|
769
|
+
const [agentFile] = rest;
|
|
770
|
+
if (command === "convert-agent" && rest.length === 1 && agentFile !== undefined)
|
|
771
|
+
return yield* convertAgent(agentFile);
|
|
772
|
+
if ((command !== "detect" && command !== "check") || rest.length > 0)
|
|
773
|
+
return yield* new UsageError({ usage: USAGE });
|
|
774
|
+
const files = yield* AgentDocsFiles;
|
|
775
|
+
const gitRoot = yield* repositoryRoot();
|
|
776
|
+
const repo: Repository = {
|
|
777
|
+
root: gitRoot ?? (yield* files.workingFolder),
|
|
778
|
+
inGit: gitRoot !== null,
|
|
779
|
+
};
|
|
780
|
+
// Every check reads paths relative to the root, as the skill runs its blocks from there.
|
|
781
|
+
yield* files.changeFolder(repo.root);
|
|
782
|
+
const lines =
|
|
783
|
+
command === "detect" ? [repo.root, ...(yield* detectLines(repo))] : yield* checkLines(repo);
|
|
784
|
+
yield* printLines(lines);
|
|
785
|
+
return lines.some((line) => line.startsWith("ERROR")) ? 2 : 0;
|
|
786
|
+
});
|