The best way to control Claude Code, Codex and more from any computer or phone

main
ts 373 lines 14.3 KB
Raw
1 /**
2 * Discovers fx skills for the `$` picker by scanning the SKILL.md folders fx
3 * reads (fx 0.0.13, src/builtins/skills.zig), so no `fx acp` session starts
4 * for a composer menu.
5 *
6 * @module provider-fx/server/skills
7 */
8 import type { ServerProviderSkill } from "@t3tools/contracts";
9 import * as Effect from "effect/Effect";
10 import * as FileSystem from "effect/FileSystem";
11 import * as Option from "effect/Option";
12 import * as Path from "effect/Path";
13 import type * as PlatformError from "effect/PlatformError";
14 import * as Stream from "effect/Stream";
15
16 /**
17 * fx's menu order: managed `~/.fx/skills`, then the workspace's `.fx/skills`
18 * and `skills/`, then every compatibility root (`skillGroupRank` in
19 * src/core/skills/skill_runtime.zig). Symlinked skill folders are followed
20 * everywhere except the managed root.
21 */
22 type SkillRoot = {
23 readonly relative: string;
24 readonly rank: 0 | 1 | 2;
25 readonly followsLinks?: false;
26 };
27
28 const FX_WORKSPACE_ROOTS: ReadonlyArray<SkillRoot> = [
29 { relative: ".fx/skills", rank: 1 },
30 { relative: "skills", rank: 1 },
31 { relative: ".opencode/skills", rank: 2 },
32 { relative: ".codex/skills", rank: 2 },
33 { relative: ".claude/skills", rank: 2 },
34 { relative: ".agents/skills", rank: 2 },
35 { relative: ".claw/skills", rank: 2 },
36 ];
37 const FX_HOME_ROOTS: ReadonlyArray<SkillRoot> = [
38 { relative: ".fx/skills", rank: 0, followsLinks: false },
39 { relative: ".config/opencode/skills", rank: 2 },
40 { relative: ".codex/skills", rank: 2 },
41 { relative: ".claude/skills", rank: 2 },
42 { relative: ".agents/skills", rank: 2 },
43 { relative: ".claw/skills", rank: 2 },
44 ];
45
46 const MAX_FRONTMATTER_BYTES = 64 * 1024;
47 const MAX_NAME_BYTES = 256;
48 const BLOCK_DESCRIPTION_STYLES = new Set([">", ">-", "|"]);
49 const encoder = new TextEncoder();
50 const strictDecoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
51 const lenientDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
52
53 /**
54 * fx reads bytes: a BOM means no frontmatter, and invalid UTF-8 in a value
55 * makes the skill invalid while a literal U+FFFD is fine. So the BOM is kept,
56 * and a line with invalid UTF-8 ends in a NUL, which the parser rejects.
57 */
58 function decodeSkillFile(bytes: Uint8Array): string {
59 const lines: Array<string> = [];
60 for (let start = 0; ;) {
61 const newline = bytes.indexOf(0x0a, start);
62 const line = bytes.subarray(start, newline === -1 ? bytes.length : newline);
63 try {
64 lines.push(strictDecoder.decode(line));
65 } catch {
66 lines.push(`${lenientDecoder.decode(line)}\u0000`);
67 }
68 if (newline === -1) return lines.join("\n");
69 start = newline + 1;
70 }
71 }
72
73 function concatBytes(chunks: Iterable<Uint8Array>): Uint8Array {
74 const parts = [...chunks];
75 const bytes = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
76 let offset = 0;
77 for (const part of parts) {
78 bytes.set(part, offset);
79 offset += part.length;
80 }
81 return bytes;
82 }
83 function compareUtf8(left: string, right: string): number {
84 const a = encoder.encode(left);
85 const b = encoder.encode(right);
86 for (let index = 0; index < Math.min(a.length, b.length); index++) {
87 if (a[index] !== b[index]) return (a[index] ?? 0) - (b[index] ?? 0);
88 }
89 return a.length - b.length;
90 }
91
92 /** fx trims only spaces and tabs. */
93 const trimSpaceTab = (value: string) => value.replace(/^[ \t]+|[ \t]+$/g, "");
94
95 /** fx's `invalidTextCause`: no ASCII control bytes (invalid UTF-8 shows up as one). */
96 const hasControlByte = (value: string) => [...value].some((char) => char < " " || char === "\x7f");
97
98 /** fx's `parseRecognizedValue`: one quoted or bare scalar, no YAML. */
99 function recognizedValue(raw: string): string | undefined {
100 if (raw.startsWith("|") || raw.startsWith(">")) return undefined;
101 const quoted = /^['"]/.test(raw) || /['"]$/.test(raw);
102 if (!quoted) return raw;
103 return raw.length >= 2 && raw[0] === raw.at(-1) ? raw.slice(1, -1) : undefined;
104 }
105
106 /**
107 * Reads SKILL.md the way fx 0.0.13 does (`parseSkillFile` in
108 * src/core/skills/skill_contract.zig): a line-based header, not YAML. No
109 * frontmatter names the skill by its folder; unreadable frontmatter (no
110 * closing `---`, missing or repeated `name`, a continued value) skips it.
111 */
112 function parseSkillMetadata(
113 contents: string,
114 folderName: string,
115 ): { readonly name: string; readonly description?: string } | undefined {
116 const opening = /^---(\r?\n|$)/.exec(contents);
117 if (opening === null) {
118 return validSkillName(folderName) ? { name: folderName } : undefined;
119 }
120 // fx drops a line's trailing `\r` only before a newline, and bounds the
121 // file up to the line after the closing `---`.
122 const lines = contents.slice(opening[0].length).split("\n");
123 const unterminated = (index: number) => index === lines.length - 1;
124 const closing = lines.findIndex(
125 (line, index) => (unterminated(index) ? line : line.replace(/\r$/, "")) === "---",
126 );
127 if (closing === -1) return undefined;
128 const throughClosing = opening[0] + lines.slice(0, closing + 1).join("\n");
129 const bodyStart = throughClosing.length + (unterminated(closing) ? 0 : 1);
130 if (encoder.encode(contents.slice(0, bodyStart)).length > MAX_FRONTMATTER_BYTES) {
131 return undefined;
132 }
133 const header = lines.slice(0, closing).map((line) => line.replace(/\r$/, ""));
134
135 let name: string | undefined;
136 let description: string | undefined;
137 let sawName = false;
138 let sawDescription = false;
139 let previousRecognized = false;
140 for (let index = 0; index < header.length; index++) {
141 const line = header[index] ?? "";
142 const trimmed = trimSpaceTab(line);
143 if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
144 if (previousRecognized && /^[ \t]/.test(line)) return undefined;
145 previousRecognized = false;
146 const colon = trimmed.indexOf(":");
147 if (colon === -1) continue;
148 const key = trimSpaceTab(trimmed.slice(0, colon));
149 const raw = trimSpaceTab(trimmed.slice(colon + 1));
150 if (key === "name") {
151 if (sawName) return undefined;
152 sawName = true;
153 name = recognizedValue(raw);
154 if (name === undefined) return undefined;
155 previousRecognized = true;
156 } else if (key === "description") {
157 if (sawDescription) return undefined;
158 sawDescription = true;
159 if (BLOCK_DESCRIPTION_STYLES.has(raw)) {
160 // A block description runs over the following space-indented lines;
161 // fx rejects a tab or a shrinking indent inside it.
162 // Blank lines stay part of the block (`undefined` below).
163 const block: Array<string | undefined> = [];
164 let baseIndent: number | undefined;
165 for (; index + 1 < header.length; index++) {
166 const next = header[index + 1] ?? "";
167 if (trimSpaceTab(next).length === 0) {
168 block.push(undefined);
169 continue;
170 }
171 const indent = /^ */.exec(next)?.[0].length ?? 0;
172 if (next[indent] === "\t") return undefined;
173 if (indent === 0) break;
174 if (baseIndent !== undefined && indent < baseIndent) return undefined;
175 baseIndent ??= indent;
176 const content = next.slice(baseIndent);
177 if (hasControlByte(content)) return undefined;
178 block.push(content);
179 }
180 description = decodeBlockDescription(block, raw);
181 } else {
182 description = recognizedValue(raw);
183 if (description === undefined || hasControlByte(description)) return undefined;
184 previousRecognized = true;
185 }
186 }
187 }
188 if (name === undefined || !validSkillName(name)) return undefined;
189 return { name, ...(description ? { description } : {}) };
190 }
191
192 /**
193 * fx's `decode_block_description`: `|` keeps line breaks; `>` and `>-` join
194 * neighbouring lines with a space and turn a blank line into a break. Only
195 * `>-` drops the final newline, which the menu trims anyway.
196 */
197 function decodeBlockDescription(lines: ReadonlyArray<string | undefined>, style: string): string {
198 const lastLine = lines.findLastIndex((line) => line !== undefined);
199 let text = "";
200 for (let index = 0; index <= lastLine; index++) {
201 const line = lines[index];
202 if (index > 0) {
203 text += style !== "|" && lines[index - 1] !== undefined && line !== undefined ? " " : "\n";
204 }
205 text += line ?? "";
206 }
207 return text.trim();
208 }
209
210 /** fx's `invalidSkillNameCause`. */
211 function validSkillName(name: string): boolean {
212 return (
213 name.length > 0 &&
214 encoder.encode(name).length <= MAX_NAME_BYTES &&
215 !hasControlByte(name) &&
216 name !== "." &&
217 name !== ".." &&
218 !name.includes("/") &&
219 !name.includes("\\")
220 );
221 }
222
223 /**
224 * fx scans the workspace roots of each directory from the workspace up to,
225 * not including, HOME, then its managed root, then the home roots.
226 */
227 function skillRoots(path: Path.Path, cwd: string, home: string) {
228 const roots: Array<{
229 readonly directory: string;
230 readonly scope: string;
231 readonly rank: number;
232 readonly followsLinks: boolean;
233 }> = [];
234 for (let current = cwd; current !== home;) {
235 for (const root of FX_WORKSPACE_ROOTS) {
236 roots.push({
237 directory: path.join(current, root.relative),
238 scope: "project",
239 rank: root.rank,
240 followsLinks: root.followsLinks ?? true,
241 });
242 }
243 const parent = path.dirname(current);
244 if (parent === current) break;
245 current = parent;
246 }
247 for (const root of FX_HOME_ROOTS) {
248 roots.push({
249 directory: path.join(home, root.relative),
250 scope: "user",
251 rank: root.rank,
252 followsLinks: root.followsLinks ?? true,
253 });
254 }
255 return roots;
256 }
257
258 const skipUnreadable = <A, R>(
259 path: string,
260 effect: Effect.Effect<A, PlatformError.PlatformError, R>,
261 ): Effect.Effect<A | undefined, never, R> =>
262 effect.pipe(
263 Effect.catchTags({
264 PlatformError: (error) =>
265 error.reason._tag === "NotFound"
266 ? Effect.void.pipe(Effect.as(undefined))
267 : Effect.logWarning("fx skill scan skipped an unreadable path.", {
268 path,
269 errorTag: error.reason._tag,
270 }).pipe(Effect.as(undefined)),
271 }),
272 );
273
274 const discoverSkillsInRoot = Effect.fn("discoverFxSkillsInRoot")(function* (input: {
275 readonly directory: string;
276 readonly scope: string;
277 readonly followsLinks: boolean;
278 }): Effect.fn.Return<
279 ReadonlyArray<{ readonly skill: ServerProviderSkill; readonly folder: string }>,
280 never,
281 FileSystem.FileSystem | Path.Path
282 > {
283 const fileSystem = yield* FileSystem.FileSystem;
284 const path = yield* Path.Path;
285 const isLink = (target: string) =>
286 Effect.option(fileSystem.readLink(target)).pipe(Effect.map(Option.isSome));
287 // fx gives its managed root no read authority: it loads nothing through a
288 // link to the root or to a folder or SKILL.md inside it (HOME is already
289 // a real path here, so a linked root changes its real path).
290 if (
291 !input.followsLinks &&
292 (yield* fileSystem.realPath(input.directory).pipe(Effect.option)).pipe(
293 Option.exists((real) => real !== input.directory),
294 )
295 ) {
296 return [];
297 }
298 const entries = yield* skipUnreadable(input.directory, fileSystem.readDirectory(input.directory));
299 const skills: Array<{ readonly skill: ServerProviderSkill; readonly folder: string }> = [];
300 // fx reads a root's folders in UTF-8 byte order; readDirectory promises none.
301 for (const entry of [...(entries ?? [])].sort(compareUtf8)) {
302 if (!input.followsLinks && (yield* isLink(path.join(input.directory, entry)))) continue;
303 // A stray file (`.DS_Store`, a README) is no skill folder.
304 const entryInfo = yield* Effect.option(fileSystem.stat(path.join(input.directory, entry)));
305 if (Option.isNone(entryInfo) || entryInfo.value.type !== "Directory") continue;
306 const skillPath = path.join(input.directory, entry, "SKILL.md");
307 if (!input.followsLinks && (yield* isLink(skillPath))) continue;
308 const skillInfo = yield* skipUnreadable(skillPath, fileSystem.stat(skillPath));
309 if (skillInfo?.type !== "File") continue;
310 // fx reads only the metadata prefix, so a long body never hides a skill.
311 const prefix = yield* skipUnreadable(
312 skillPath,
313 fileSystem
314 .stream(skillPath, { bytesToRead: MAX_FRONTMATTER_BYTES + 1 })
315 .pipe(Stream.runCollect, Effect.map(concatBytes)),
316 );
317 const metadata =
318 prefix === undefined ? undefined : parseSkillMetadata(decodeSkillFile(prefix), entry);
319 if (metadata === undefined) continue;
320 const folder = yield* skipUnreadable(
321 skillPath,
322 fileSystem.realPath(path.join(input.directory, entry)),
323 );
324 skills.push({
325 folder: folder ?? path.join(input.directory, entry),
326 skill: {
327 name: metadata.name,
328 path: skillPath,
329 scope: input.scope,
330 enabled: true,
331 ...(metadata.description === undefined ? {} : { description: metadata.description }),
332 },
333 });
334 }
335 return skills;
336 });
337
338 /**
339 * Skills in fx's menu order. Like fx, a folder reached twice (a symlinked
340 * root) counts once. When two different skills share a name, `$name` lets
341 * the model choose from fx's catalog, which lists them in scan order; it
342 * takes the first copy, so that is the one listed here.
343 */
344 export const discoverFxSkills = Effect.fn("discoverFxSkills")(function* (input: {
345 readonly cwd: string;
346 readonly environment: NodeJS.ProcessEnv;
347 }): Effect.fn.Return<ReadonlyArray<ServerProviderSkill>, never, FileSystem.FileSystem | Path.Path> {
348 // fx reads skills only under a set HOME, and compares HOME and the
349 // workspace by their real paths.
350 const configuredHome = input.environment.HOME?.trim();
351 if (!configuredHome) return [];
352 const fileSystem = yield* FileSystem.FileSystem;
353 const realPath = (target: string) =>
354 fileSystem.realPath(target).pipe(Effect.orElseSucceed(() => target));
355 const home = yield* realPath(configuredHome);
356 const cwd = yield* realPath(input.cwd);
357 const path = yield* Path.Path;
358 const seenFolders = new Set<string>();
359 // `$review` and `$Review` each load the skill whose name matches the typed
360 // case, so only an exact repeat of a name is dropped.
361 const seenNames = new Set<string>();
362 const found: Array<{ readonly skill: ServerProviderSkill; readonly rank: number }> = [];
363 for (const root of skillRoots(path, cwd, home)) {
364 for (const { skill, folder } of yield* discoverSkillsInRoot(root)) {
365 if (seenFolders.has(folder)) continue;
366 seenFolders.add(folder);
367 if (seenNames.has(skill.name)) continue;
368 seenNames.add(skill.name);
369 found.push({ skill, rank: root.rank });
370 }
371 }
372 return found.sort((left, right) => left.rank - right.rank).map(({ skill }) => skill);
373 });