@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 514 lines 17.7 KB
Raw
1 import type { ServerProviderSkill } from "@t3tools/contracts";
2 import * as Effect from "effect/Effect";
3 import * as FileSystem from "effect/FileSystem";
4 import * as Path from "effect/Path";
5 import type * as PlatformError from "effect/PlatformError";
6 import * as Schema from "effect/Schema";
7 import * as Stream from "effect/Stream";
8 import { parse as parseYamlDocument } from "yaml";
9
10 /** Match Python os.path.expanduser: USERPROFILE, then HOMEDRIVE+HOMEPATH on Windows; HOME elsewhere. */
11 export function resolveAntigravityUserHome(
12 platform: NodeJS.Platform,
13 environment: NodeJS.ProcessEnv,
14 home: string,
15 ): string {
16 if (platform === "win32") {
17 if (environment.USERPROFILE) return environment.USERPROFILE;
18 if (environment.HOMEDRIVE && environment.HOMEPATH) {
19 return `${environment.HOMEDRIVE}${environment.HOMEPATH}`;
20 }
21 return home;
22 }
23 return environment.HOME || home;
24 }
25
26 /** Link private GEMINI_HOME skills to ~/.gemini; ~/.agents/skills is ignored because .agents/skills is project-only. */
27 export function antigravityUserSkillDirectories(
28 path: Path.Path,
29 geminiHome: string,
30 ): readonly [configSkills: string, cliSkills: string] {
31 return [
32 path.join(geminiHome, "config", "skills"),
33 path.join(geminiHome, "antigravity-cli", "skills"),
34 ];
35 }
36
37 const MAX_SKILL_BYTES = 1_000_000;
38 const MAX_SCAN_BYTES = 8_000_000;
39 const MAX_SCAN_ENTRIES = 10_000;
40 const MAX_INHERIT_DEPTH = 10;
41 // Typical frontmatter fits in one chunk, so most skills cost about this much of the scan budget.
42 const SKILL_READ_CHUNK_BYTES = 1024;
43
44 const SkillFrontmatter = Schema.Struct({
45 name: Schema.optional(Schema.NullOr(Schema.String)),
46 description: Schema.optional(Schema.NullOr(Schema.String)),
47 });
48 const decodeSkillFrontmatter = Schema.decodeUnknownSync(SkillFrontmatter);
49 const SkillConfigEntry = Schema.Struct({
50 path: Schema.String,
51 include_only: Schema.optional(Schema.Array(Schema.String)),
52 exclude: Schema.optional(Schema.Array(Schema.String)),
53 });
54 const decodeSkillsConfig = Schema.decodeUnknownOption(
55 Schema.fromJsonString(
56 Schema.Struct({
57 inherits: Schema.optional(Schema.Array(SkillConfigEntry)),
58 entries: Schema.optional(Schema.Array(SkillConfigEntry)),
59 }),
60 ),
61 );
62 const decodePluginPreferences = Schema.decodeUnknownOption(
63 Schema.fromJsonString(
64 Schema.Struct({
65 plugins: Schema.optional(
66 Schema.Record(Schema.String, Schema.Struct({ enabled: Schema.optional(Schema.Boolean) })),
67 ),
68 }),
69 ),
70 );
71
72 export class AntigravitySkillsProbeError extends Schema.TaggedError<AntigravitySkillsProbeError>()(
73 "AntigravitySkillsProbeError",
74 {
75 reason: Schema.Literals(["scan-budget-exhausted", "filesystem-error"]),
76 path: Schema.String,
77 cause: Schema.optional(Schema.Defect()),
78 },
79 ) {
80 override get message(): string {
81 return this.reason === "scan-budget-exhausted"
82 ? `Antigravity skill discovery exceeded its scan limit at '${this.path}'.`
83 : `Antigravity could not read skills at '${this.path}'.`;
84 }
85 }
86
87 interface ScanBudget {
88 remainingBytes: number;
89 remainingEntries: number;
90 }
91
92 const readIfPresent = <A, R>(
93 effect: Effect.Effect<A, PlatformError.PlatformError, R>,
94 path: string,
95 ) =>
96 effect.pipe(
97 Effect.catchTags({
98 PlatformError: (cause) =>
99 cause.reason._tag === "NotFound"
100 ? Effect.undefined
101 : Effect.fail(
102 new AntigravitySkillsProbeError({ reason: "filesystem-error", path, cause }),
103 ),
104 }),
105 );
106
107 function parseSkillFrontmatter(contents: string, fileName: string) {
108 const start = contents.indexOf("---");
109 if (start === -1) return undefined;
110 const end = contents.indexOf("---", start + 3);
111 if (end === -1) return undefined;
112 try {
113 const frontmatter = decodeSkillFrontmatter(
114 parseYamlDocument(contents.slice(start + 3, end).trim()) ?? {},
115 );
116 const name = frontmatter.name || fileName.slice(0, -3);
117 const description = frontmatter.description?.trim();
118 // Native names are not trimmed. Do not rename one to fit the picker contract.
119 if (!name || name !== name.trim()) return undefined;
120 return { name, ...(description ? { description } : {}) };
121 } catch {
122 return undefined;
123 }
124 }
125
126 /** The native loader orders child paths with Go's URL.EscapedPath encoding. */
127 function skillPathSortKey(entry: string) {
128 return encodeURI(entry).replace(
129 /[!'()*?#]/g,
130 (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
131 );
132 }
133
134 const DASH = 0x2d;
135
136 /** Finds the byte offset after the second `---`, as parseSkillFrontmatter's indexOf calls do. */
137 function makeFrontmatterEndFinder() {
138 let bytesSeen = 0;
139 let dashes = 0;
140 let markers = 0;
141 return (chunk: Uint8Array) => {
142 for (const byte of chunk) {
143 bytesSeen += 1;
144 dashes = byte === DASH ? dashes + 1 : 0;
145 if (dashes === 3) {
146 dashes = 0;
147 markers += 1;
148 if (markers === 2) return bytesSeen;
149 }
150 }
151 return undefined;
152 };
153 }
154
155 /** Reads through the frontmatter only, so skill bodies do not spend the scan budget. */
156 const readSkillFrontmatter = Effect.fn("readAntigravitySkill")(function* (
157 skillPath: string,
158 budget: ScanBudget,
159 ) {
160 const fileSystem = yield* FileSystem.FileSystem;
161 const info = yield* readIfPresent(fileSystem.stat(skillPath), skillPath);
162 if (info?.type !== "File") return undefined;
163
164 const byteLimit = Math.min(MAX_SKILL_BYTES, budget.remainingBytes);
165 const findFrontmatterEnd = makeFrontmatterEndFinder();
166 let frontmatterEnd: number | undefined;
167 const chunks = yield* readIfPresent(
168 fileSystem
169 .stream(skillPath, { bytesToRead: byteLimit + 1, chunkSize: SKILL_READ_CHUNK_BYTES })
170 .pipe(
171 Stream.takeUntil((chunk) => (frontmatterEnd = findFrontmatterEnd(chunk)) !== undefined),
172 Stream.runCollect,
173 ),
174 skillPath,
175 );
176 if (chunks === undefined) return undefined;
177 const bytes = Buffer.concat(chunks);
178 budget.remainingBytes -= bytes.byteLength;
179 if ((frontmatterEnd ?? bytes.byteLength) > byteLimit) {
180 return yield* new AntigravitySkillsProbeError({
181 reason: "scan-budget-exhausted",
182 path: skillPath,
183 });
184 }
185 return bytes.toString("utf8", 0, frontmatterEnd);
186 });
187
188 type SkillPatternMatcher = (entry: string) => boolean;
189
190 interface SkillEntryFilter {
191 readonly includeGroups: ReadonlyArray<ReadonlyArray<SkillPatternMatcher>>;
192 readonly excludePatterns: ReadonlyArray<SkillPatternMatcher>;
193 }
194
195 const EMPTY_SKILL_FILTER: SkillEntryFilter = {
196 includeGroups: [],
197 excludePatterns: [],
198 };
199
200 interface SkillPatternToken {
201 readonly test: (character: string) => boolean;
202 readonly optional: boolean;
203 readonly repeats: boolean;
204 }
205
206 /** Undefined for syntax outside literals, escapes, `.`, `[...]` and `* + ?`; such patterns match literally. */
207 function parseSkillPattern(pattern: string): ReadonlyArray<SkillPatternToken> | undefined {
208 const characters = Array.from(pattern);
209 const tokens: Array<SkillPatternToken> = [];
210 let index = 0;
211 while (index < characters.length) {
212 const character = characters[index]!;
213 let test: (candidate: string) => boolean;
214 if (character === "\\") {
215 const escaped = characters[index + 1];
216 if (escaped === undefined) return undefined;
217 if (/[dDwWsS]/.test(escaped)) {
218 const characterClass = new RegExp(`^\\${escaped}$`, "u");
219 test = (candidate) => characterClass.test(candidate);
220 } else {
221 test = (candidate) => candidate === escaped;
222 }
223 index += 2;
224 } else if (character === "[") {
225 const close = characters.indexOf("]", index + 2);
226 if (close === -1) return undefined;
227 let characterClass: RegExp;
228 try {
229 characterClass = new RegExp(`^[${characters.slice(index + 1, close).join("")}]$`, "u");
230 } catch {
231 return undefined;
232 }
233 test = (candidate) => characterClass.test(candidate);
234 index = close + 1;
235 } else if (character === ".") {
236 test = () => true;
237 index += 1;
238 } else if ("()|{}^$*+?".includes(character)) {
239 return undefined;
240 } else {
241 test = (candidate) => candidate === character;
242 index += 1;
243 }
244 const quantifier = characters[index];
245 const optional = quantifier === "*" || quantifier === "?";
246 const repeats = quantifier === "*" || quantifier === "+";
247 if (optional || repeats) {
248 index += 1;
249 if (characters[index] === "?") index += 1;
250 }
251 tokens.push({ test, optional, repeats });
252 }
253 return tokens;
254 }
255
256 /** Manifests can come from an opened workspace, so matching runs as an NFA in linear time instead of RegExp. */
257 function compileSkillPattern(pattern: string): SkillPatternMatcher {
258 const tokens = parseSkillPattern(pattern);
259 if (tokens === undefined) return (entry) => entry === pattern;
260 const close = (states: Set<number>) => {
261 for (const state of states) {
262 if (state < tokens.length && tokens[state]!.optional) states.add(state + 1);
263 }
264 return states;
265 };
266 return (entry) => {
267 let states = close(new Set([0]));
268 for (const character of entry) {
269 const next = new Set<number>();
270 for (const state of states) {
271 const token = tokens[state];
272 if (!token?.test(character)) continue;
273 next.add(state + 1);
274 if (token.repeats) next.add(state);
275 }
276 if (next.size === 0) return false;
277 states = close(next);
278 }
279 return states.has(tokens.length);
280 };
281 }
282
283 function matchesSkillFilter(entry: string, filter: SkillEntryFilter): boolean {
284 for (const group of filter.includeGroups) {
285 if (!group.some((matches) => matches(entry))) return false;
286 }
287 return !filter.excludePatterns.some((matches) => matches(entry));
288 }
289
290 function narrowSkillFilter(
291 parent: SkillEntryFilter,
292 entry: {
293 readonly include_only?: ReadonlyArray<string> | undefined;
294 readonly exclude?: ReadonlyArray<string> | undefined;
295 },
296 ): SkillEntryFilter {
297 const includeGroups =
298 entry.include_only && entry.include_only.length > 0
299 ? [...parent.includeGroups, entry.include_only.map(compileSkillPattern)]
300 : parent.includeGroups;
301 const excludePatterns =
302 entry.exclude && entry.exclude.length > 0
303 ? [...parent.excludePatterns, ...entry.exclude.map(compileSkillPattern)]
304 : parent.excludePatterns;
305 return { includeGroups, excludePatterns };
306 }
307
308 function resolveSkillsConfigPath(
309 path: Path.Path,
310 rawPath: string,
311 baseDir: string,
312 userHome: string,
313 ): string {
314 if (rawPath === "~") return userHome;
315 if (rawPath.startsWith("~/") || rawPath.startsWith("~\\")) {
316 return path.join(userHome, rawPath.slice(2));
317 }
318 return path.isAbsolute(rawPath) ? path.resolve(rawPath) : path.resolve(baseDir, rawPath);
319 }
320
321 /** Keep read errors typed so workspace snapshots cannot cache partial results. */
322 export const discoverAntigravitySkills = Effect.fn("discoverAntigravitySkills")(function* (input: {
323 readonly cwd: string;
324 readonly userHome: string;
325 /** The instance's GEMINI_HOME, where agy loads plugins from. */
326 readonly profileDirectory: string;
327 }): Effect.fn.Return<
328 ReadonlyArray<ServerProviderSkill>,
329 AntigravitySkillsProbeError,
330 FileSystem.FileSystem | Path.Path
331 > {
332 const fileSystem = yield* FileSystem.FileSystem;
333 const path = yield* Path.Path;
334 const [configSkills, cliSkills] = antigravityUserSkillDirectories(
335 path,
336 path.join(input.userHome, ".gemini"),
337 );
338 const roots = [
339 { directory: configSkills, scope: "user" },
340 { directory: path.resolve(input.cwd, ".gemini", "skills"), scope: "project" },
341 { directory: cliSkills, scope: "user" },
342 { directory: path.resolve(input.cwd, ".agents", "skills"), scope: "project" },
343 { directory: path.resolve(input.cwd, ".agent", "skills"), scope: "project" },
344 ];
345 const budget: ScanBudget = {
346 remainingBytes: MAX_SCAN_BYTES,
347 remainingEntries: MAX_SCAN_ENTRIES,
348 };
349 const skillsByName = new Map<string, ServerProviderSkill>();
350
351 const scanDirectory = Effect.fn("scanAntigravitySkillDirectory")(function* (
352 directory: string,
353 scope: string,
354 scanChildren: boolean,
355 filter: SkillEntryFilter = EMPTY_SKILL_FILTER,
356 ): Effect.fn.Return<void, AntigravitySkillsProbeError, FileSystem.FileSystem> {
357 const info = yield* readIfPresent(fileSystem.stat(directory), directory);
358 if (info?.type !== "Directory") return;
359 const entries = yield* readIfPresent(fileSystem.readDirectory(directory), directory);
360 if (entries === undefined) return;
361 if (entries.length > budget.remainingEntries) {
362 return yield* new AntigravitySkillsProbeError({
363 reason: "scan-budget-exhausted",
364 path: directory,
365 });
366 }
367 budget.remainingEntries -= entries.length;
368
369 const sortedEntries = entries.toSorted();
370 const skillFileName = sortedEntries.find((entry) => entry.toLowerCase() === "skill.md");
371 if (skillFileName !== undefined) {
372 if (!skillFileName.endsWith(".md")) return;
373 const skillPath = path.join(directory, skillFileName);
374 const contents = yield* readSkillFrontmatter(skillPath, budget);
375 if (contents === undefined) return;
376 const skill = parseSkillFrontmatter(contents, skillFileName);
377 if (!skill || skillsByName.has(skill.name)) return;
378 skillsByName.set(skill.name, {
379 ...skill,
380 path: skillPath,
381 scope,
382 enabled: true,
383 });
384 return;
385 }
386 if (scanChildren) {
387 const children = sortedEntries
388 .filter((entry) => matchesSkillFilter(entry, filter))
389 .map((entry) => ({ entry, sortKey: skillPathSortKey(entry) }))
390 .sort((left, right) =>
391 left.sortKey < right.sortKey ? -1 : left.sortKey > right.sortKey ? 1 : 0,
392 );
393 for (const { entry } of children) {
394 yield* scanDirectory(path.join(directory, entry), scope, false);
395 }
396 }
397 });
398
399 const scanSkillsConfig = Effect.fn("scanAntigravitySkillsConfig")(function* (
400 configPath: string,
401 baseDir: string,
402 scope: string,
403 filter: SkillEntryFilter,
404 visitedConfigs: ReadonlySet<string>,
405 depth: number,
406 ): Effect.fn.Return<void, AntigravitySkillsProbeError, FileSystem.FileSystem> {
407 if (depth > MAX_INHERIT_DEPTH) return;
408 const resolvedConfigPath = path.resolve(configPath);
409 if (visitedConfigs.has(resolvedConfigPath)) return;
410 const configInfo = yield* readIfPresent(
411 fileSystem.stat(resolvedConfigPath),
412 resolvedConfigPath,
413 );
414 if (configInfo?.type !== "File") return;
415 const byteLimit = Math.min(MAX_SKILL_BYTES, budget.remainingBytes);
416 if (configInfo.size > BigInt(byteLimit)) {
417 return yield* new AntigravitySkillsProbeError({
418 reason: "scan-budget-exhausted",
419 path: resolvedConfigPath,
420 });
421 }
422 const raw = yield* readIfPresent(
423 fileSystem.readFileString(resolvedConfigPath),
424 resolvedConfigPath,
425 );
426 if (raw === undefined) return;
427 budget.remainingBytes -= Buffer.byteLength(raw, "utf8");
428 const parsed = decodeSkillsConfig(raw);
429 if (parsed._tag === "None") return;
430
431 const nextVisited = new Set(visitedConfigs);
432 nextVisited.add(resolvedConfigPath);
433 for (const inherited of parsed.value.inherits ?? []) {
434 const inheritedPath = resolveSkillsConfigPath(path, inherited.path, baseDir, input.userHome);
435 yield* scanSkillsConfig(
436 inheritedPath,
437 path.dirname(inheritedPath),
438 scope,
439 narrowSkillFilter(filter, inherited),
440 nextVisited,
441 depth + 1,
442 );
443 }
444 for (const entry of parsed.value.entries ?? []) {
445 const entryDirectory = resolveSkillsConfigPath(path, entry.path, baseDir, input.userHome);
446 yield* scanDirectory(entryDirectory, scope, true, narrowSkillFilter(filter, entry));
447 }
448 });
449
450 for (const root of roots) {
451 yield* scanDirectory(root.directory, root.scope, true);
452 }
453
454 for (const config of [
455 {
456 configPath: path.resolve(input.cwd, ".agents", "skills.json"),
457 baseDir: input.cwd,
458 scope: "project",
459 },
460 {
461 configPath: path.resolve(input.cwd, ".agent", "skills.json"),
462 baseDir: input.cwd,
463 scope: "project",
464 },
465 {
466 configPath: path.join(input.userHome, ".gemini", "config", "skills.json"),
467 baseDir: path.join(input.userHome, ".gemini", "config"),
468 scope: "user",
469 },
470 ]) {
471 yield* scanSkillsConfig(
472 config.configPath,
473 config.baseDir,
474 config.scope,
475 EMPTY_SKILL_FILTER,
476 new Set(),
477 0,
478 );
479 }
480
481 const pluginsDirectory = path.join(input.profileDirectory, "config", "plugins");
482 const plugins = yield* readIfPresent(
483 fileSystem.readDirectory(pluginsDirectory),
484 pluginsDirectory,
485 );
486 if (plugins !== undefined && plugins.length > 0) {
487 const configPath = path.join(input.profileDirectory, "config", "config.json");
488 const configInfo = yield* readIfPresent(fileSystem.stat(configPath), configPath);
489 if (configInfo?.type === "File" && configInfo.size > BigInt(MAX_SKILL_BYTES)) {
490 return yield* new AntigravitySkillsProbeError({
491 reason: "scan-budget-exhausted",
492 path: configPath,
493 });
494 }
495 const config =
496 configInfo?.type === "File"
497 ? yield* readIfPresent(fileSystem.readFileString(configPath), configPath)
498 : undefined;
499 const preferences = config === undefined ? undefined : decodePluginPreferences(config);
500 const disabled = new Set(
501 Object.entries(
502 (preferences?._tag === "Some" ? preferences.value.plugins : undefined) ?? {},
503 ).flatMap(([name, plugin]) => (plugin.enabled === false ? [name] : [])),
504 );
505 for (const plugin of plugins.toSorted()) {
506 if (disabled.has(plugin)) continue;
507 const pluginDirectory = path.join(pluginsDirectory, plugin);
508 const info = yield* readIfPresent(fileSystem.stat(pluginDirectory), pluginDirectory);
509 if (info?.type !== "Directory") continue;
510 yield* scanDirectory(path.join(pluginDirectory, "skills"), "user", true);
511 }
512 }
513 return [...skillsByName.values()].sort((left, right) => left.name.localeCompare(right.name));
514 });