tokenusage-cli 0.2.6 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/README.md +52 -11
  3. package/bin/tokenusage.js +14 -2
  4. package/package.json +1 -2
  5. package/src/cli.js +325 -78
  6. package/src/commands/device-login.js +3 -3
  7. package/src/commands/init.js +343 -153
  8. package/src/commands/pause.js +11 -23
  9. package/src/commands/reconcile.js +485 -0
  10. package/src/commands/sessions.js +57 -14
  11. package/src/commands/status.js +5 -2
  12. package/src/commands/sync.js +77 -18
  13. package/src/commands/uninstall.js +6 -9
  14. package/src/commands/upload.js +147 -0
  15. package/src/lib/cli-errors.js +33 -0
  16. package/src/lib/cli-ui.js +93 -0
  17. package/src/lib/ingest-sanitize.js +9 -0
  18. package/src/lib/queue-row-normalize.js +55 -0
  19. package/src/lib/rollout.js +39 -2
  20. package/src/lib/scheduled-task.js +597 -75
  21. package/src/lib/session-analytics.js +171 -3
  22. package/src/lib/session-upload.js +6 -0
  23. package/src/lib/sync-report.js +8 -2
  24. package/src/lib/trae-db.js +6 -1
  25. package/src/lib/antigravity-paths.js +0 -48
  26. package/src/lib/async-queue-reader.js +0 -138
  27. package/src/lib/atomic-json.js +0 -27
  28. package/src/lib/bearer-token.js +0 -11
  29. package/src/lib/cloud-account.js +0 -541
  30. package/src/lib/codex-context-breakdown.js +0 -806
  31. package/src/lib/context-health.js +0 -124
  32. package/src/lib/grok-context-breakdown.js +0 -890
  33. package/src/lib/heatmap-compact.js +0 -114
  34. package/src/lib/local-api.js +0 -3574
  35. package/src/lib/outcomes-engine.js +0 -253
  36. package/src/lib/pet-packages.js +0 -722
  37. package/src/lib/skill-usage.js +0 -267
  38. package/src/lib/skills-manager.js +0 -1591
  39. package/src/lib/source-metadata.js +0 -48
  40. package/src/lib/subscription-manager.js +0 -293
  41. package/src/lib/wrapped-aggregator.js +0 -236
  42. package/test/audit-fixes.test.js +0 -249
  43. package/test/branding.test.js +0 -24
  44. package/test/cli-options.test.js +0 -43
  45. package/test/cli-smoke.test.js +0 -53
  46. package/test/cli-ui.test.js +0 -47
  47. package/test/collection-controls.test.js +0 -255
  48. package/test/ingest-sanitize.test.js +0 -162
  49. package/test/packaging.test.js +0 -107
  50. package/test/quiet-warnings.test.js +0 -53
  51. package/test/runtime-copy.test.js +0 -111
  52. package/test/session-upload.test.js +0 -427
  53. package/test/zstd-native.test.js +0 -36
@@ -1,1591 +0,0 @@
1
- const fs = require("node:fs");
2
- const os = require("node:os");
3
- const path = require("node:path");
4
- const crypto = require("node:crypto");
5
- const { resolveGrokHome } = require("./grok-hook");
6
- const { resolveAntigravitySkillDirs } = require("./antigravity-paths");
7
-
8
- const DEFAULT_REPOS = [
9
- { owner: "anthropics", name: "skills", branch: "main", enabled: true },
10
- { owner: "ComposioHQ", name: "awesome-claude-skills", branch: "master", enabled: true },
11
- { owner: "cexll", name: "myclaude", branch: "master", enabled: true },
12
- { owner: "JimLiu", name: "baoyu-skills", branch: "main", enabled: true },
13
- ];
14
-
15
- const TARGETS = {
16
- claude: { id: "claude", label: "Claude", dir: () => path.join(os.homedir(), ".claude", "skills") },
17
- codex: { id: "codex", label: "Codex", dir: () => path.join(resolveCodexHome(), "skills") },
18
- acode: { id: "acode", label: "AStudio", dir: () => path.join(resolveAcodeHome(), "skills") },
19
- grok: { id: "grok", label: "Grok", dir: () => path.join(resolveGrokHome(process.env), "skills") },
20
- antigravity: { id: "antigravity", label: "Antigravity", dirs: () => resolveAntigravitySkillDirs(process.env) },
21
- gemini: { id: "gemini", label: "Gemini", dir: () => path.join(os.homedir(), ".gemini", "skills") },
22
- opencode: { id: "opencode", label: "OpenCode", dir: () => path.join(os.homedir(), ".config", "opencode", "skills") },
23
- openclaw: { id: "openclaw", label: "OpenClaw", dir: resolveOpenClawSkillsDir },
24
- hermes: { id: "hermes", label: "Hermes", dir: () => path.join(os.homedir(), ".hermes", "skills") },
25
- // ZCode currently exposes skills through its plugin cache rather than a
26
- // documented user-writable skills directory. Surface it in the inventory
27
- // and filters, but never offer sync/delete operations against the cache.
28
- zcode: { id: "zcode", label: "ZCode", manageable: false },
29
- agents: { id: "agents", label: "Agents", visible: false, dir: () => path.join(os.homedir(), ".agents", "skills") },
30
- };
31
-
32
- function resolveCodexHome() {
33
- return String(process.env.CODEX_HOME || "").trim() || path.join(os.homedir(), ".codex");
34
- }
35
-
36
- function resolveAcodeHome() {
37
- return String(process.env.TOKENUSAGE_ACODE_HOME || "").trim() || path.join(os.homedir(), ".acode");
38
- }
39
-
40
- function resolveZcodeHome() {
41
- return String(process.env.ZCODE_HOME || "").trim() || path.join(os.homedir(), ".zcode");
42
- }
43
-
44
- function resolveOpenClawHome() {
45
- return String(process.env.TOKENUSAGE_OPENCLAW_HOME || "").trim() || path.join(os.homedir(), ".openclaw");
46
- }
47
-
48
- // OpenClaw can point at an arbitrary active workspace. Only scan that one
49
- // explicit workspace; recursively scanning ~/.openclaw would incorrectly
50
- // import backup/config snapshots belonging to other devices.
51
- function resolveOpenClawSkillsDir() {
52
- const home = resolveOpenClawHome();
53
- const override = String(process.env.TOKENUSAGE_OPENCLAW_WORKSPACE || "").trim();
54
- let workspace = override;
55
- if (!workspace) {
56
- const config = readJson(path.join(home, "openclaw.json"), null);
57
- workspace = String(config?.agents?.defaults?.workspace || "").trim();
58
- }
59
- if (!workspace) workspace = path.join(home, "workspace");
60
- if (!path.isAbsolute(workspace)) workspace = path.resolve(home, workspace);
61
- return path.join(workspace, "skills");
62
- }
63
-
64
- // Dual contract: a target exposes either dir() → string (single path) or
65
- // dirs() → string[] (parallel-write to multiple paths, e.g. Antigravity which
66
- // has separate user-skills dirs for the main app and the IDE). Consumers must
67
- // route through these helpers so the single-path targets stay zero-overhead.
68
- function targetDirs(target) {
69
- if (!target || target.manageable === false) return [];
70
- if (typeof target.dirs === "function") return target.dirs();
71
- if (typeof target.dir === "function") return [target.dir()];
72
- return [];
73
- }
74
-
75
- // Used for surfacing one path in UI/local-api responses. For multi-dir targets
76
- // this is the canonical "first" entry by convention (main app before IDE).
77
- function targetPrimaryDir(target) {
78
- return targetDirs(target)[0] || null;
79
- }
80
-
81
- const FETCH_TIMEOUT_MS = 20_000;
82
- const DISCOVER_CONCURRENCY = 4;
83
- const DISCOVER_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
84
- const OWNER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
85
-
86
- class RateLimitError extends Error {
87
- constructor(message) {
88
- super(message);
89
- this.name = "RateLimitError";
90
- this.code = "RATE_LIMITED";
91
- this.status = 429;
92
- }
93
- }
94
-
95
- async function mapWithConcurrency(items, limit, worker) {
96
- const results = new Array(items.length);
97
- let cursor = 0;
98
- async function runNext() {
99
- while (true) {
100
- const index = cursor++;
101
- if (index >= items.length) return;
102
- results[index] = await worker(items[index], index);
103
- }
104
- }
105
- const pool = new Array(Math.min(limit, items.length)).fill(0).map(runNext);
106
- await Promise.all(pool);
107
- return results;
108
- }
109
-
110
- function dataDir() {
111
- return path.join(os.homedir(), ".tokenusage", "skills");
112
- }
113
-
114
- function registryPath() {
115
- return path.join(dataDir(), "registry.json");
116
- }
117
-
118
- function ssotDir() {
119
- return path.join(dataDir(), "managed");
120
- }
121
-
122
- function trashDir() {
123
- return path.join(dataDir(), ".trash");
124
- }
125
-
126
- const TRASH_TTL_MS = 5 * 60 * 1000; // 5 minutes
127
-
128
- function discoverCachePath() {
129
- return path.join(dataDir(), "discover-cache.json");
130
- }
131
-
132
- function activityPath() {
133
- return path.join(dataDir(), "activity.jsonl");
134
- }
135
-
136
- const ACTIVITY_MAX = 500;
137
-
138
- // Append-only skill activity log, mirroring the queue.jsonl culture: best-effort,
139
- // auto-capped, latest-wins on read. Privacy: verbs + skill name + targets only —
140
- // never prompts or file contents. Never throws (logging must not block a mutation).
141
- function appendActivity(event) {
142
- try {
143
- ensureDir(dataDir());
144
- const record = JSON.stringify({ ts: Date.now(), ...event });
145
- fs.appendFileSync(activityPath(), `${record}\n`, { mode: 0o600 });
146
- const stat = fs.statSync(activityPath());
147
- if (stat.size > 256 * 1024) {
148
- const lines = fs.readFileSync(activityPath(), "utf8").split("\n").filter(Boolean).slice(-ACTIVITY_MAX);
149
- fs.writeFileSync(activityPath(), `${lines.join("\n")}\n`, { mode: 0o600 });
150
- }
151
- } catch (_e) {
152
- // best-effort
153
- }
154
- }
155
-
156
- function readActivity(limit = 100) {
157
- try {
158
- const raw = fs.readFileSync(activityPath(), "utf8");
159
- const lines = raw.split("\n").filter(Boolean);
160
- const want = Math.max(1, Math.min(ACTIVITY_MAX, Number(limit) || 100));
161
- return lines
162
- .slice(-want)
163
- .map((line) => {
164
- try {
165
- return JSON.parse(line);
166
- } catch (_e) {
167
- return null;
168
- }
169
- })
170
- .filter(Boolean)
171
- .reverse();
172
- } catch (_e) {
173
- return [];
174
- }
175
- }
176
-
177
- function ensureDir(dir) {
178
- fs.mkdirSync(dir, { recursive: true });
179
- }
180
-
181
- function readJson(file, fallback) {
182
- try {
183
- return JSON.parse(fs.readFileSync(file, "utf8"));
184
- } catch (_e) {
185
- return fallback;
186
- }
187
- }
188
-
189
- function writeJson(file, value) {
190
- ensureDir(path.dirname(file));
191
- fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
192
- }
193
-
194
- function readRegistry() {
195
- const registry = readJson(registryPath(), null);
196
- if (registry && typeof registry === "object") {
197
- return {
198
- repos: Array.isArray(registry.repos) ? registry.repos : DEFAULT_REPOS,
199
- skills: Array.isArray(registry.skills) ? registry.skills : [],
200
- };
201
- }
202
- return { repos: DEFAULT_REPOS, skills: [] };
203
- }
204
-
205
- function saveRegistry(registry) {
206
- writeJson(registryPath(), registry);
207
- }
208
-
209
- function sanitizePathSegment(value) {
210
- const segment = String(value || "").trim();
211
- if (!segment || segment === "." || segment === "..") return null;
212
- if (segment.includes("/") || segment.includes("\\") || segment.includes("\0")) return null;
213
- return segment;
214
- }
215
-
216
- function sanitizeRelativePath(value) {
217
- const input = String(value || "").trim();
218
- const raw = input.replace(/\\/g, "/");
219
- if (!raw || raw.includes("\0")) return null;
220
- if (path.posix.isAbsolute(raw) || path.win32.isAbsolute(input) || path.win32.isAbsolute(raw)) return null;
221
- const parts = raw.split("/").filter(Boolean);
222
- if (!parts.length || parts.some((part) => part === "." || part === ".." || part.includes(":"))) return null;
223
- return parts.join("/");
224
- }
225
-
226
- function sanitizeLocalSkillPath(value) {
227
- const safe = sanitizeRelativePath(value);
228
- if (!safe) return null;
229
- if (safe.split("/").some((part) => part.startsWith("."))) return null;
230
- return safe;
231
- }
232
-
233
- function installNameFromDirectory(directory) {
234
- const safe = sanitizeRelativePath(directory);
235
- if (!safe) return null;
236
- return sanitizePathSegment(safe.split("/").pop());
237
- }
238
-
239
- function targetList() {
240
- return Object.values(TARGETS)
241
- .filter((target) => target.visible !== false)
242
- .map((target) => ({
243
- id: target.id,
244
- label: target.label,
245
- path: targetPrimaryDir(target),
246
- manageable: target.manageable !== false,
247
- }));
248
- }
249
-
250
- // Read a single scalar field from YAML frontmatter. Handles inline values
251
- // (`key: value`, optionally quoted) AND block scalars (`key: >` / `key: |`, with
252
- // optional chomping `+`/`-`), where the value lives on the following indented
253
- // lines. Without block-scalar support, `description: >` skills surfaced their
254
- // description as a bare ">" or "|" (the block indicator itself).
255
- function readYamlField(yaml, key) {
256
- const lines = String(yaml).split("\n");
257
- const header = new RegExp(`^(\\s*)${key}:[ \\t]*(.*)$`);
258
- for (let i = 0; i < lines.length; i += 1) {
259
- const match = lines[i].match(header);
260
- if (!match) continue;
261
- const indent = match[1].length;
262
- const inline = match[2].trim();
263
- if (/^[>|][+-]?$/.test(inline)) {
264
- const collected = [];
265
- for (let j = i + 1; j < lines.length; j += 1) {
266
- if (lines[j].trim() === "") {
267
- collected.push("");
268
- continue;
269
- }
270
- const lineIndent = lines[j].match(/^(\s*)/)[1].length;
271
- if (lineIndent <= indent) break; // dedent ends the block
272
- collected.push(lines[j].trim());
273
- }
274
- return collected.join(" ");
275
- }
276
- return inline.replace(/^["']/, "").replace(/["']$/, "");
277
- }
278
- return "";
279
- }
280
-
281
- function readSkillMetadata(markdown, fallbackName) {
282
- const raw = String(markdown || "");
283
- const frontmatter = raw.match(/^---\s*\n([\s\S]*?)\n---/);
284
- const source = frontmatter ? frontmatter[1] : raw;
285
- const name = readYamlField(source, "name") || fallbackName || "Skill";
286
- const description = readYamlField(source, "description");
287
- return {
288
- name: name.trim(),
289
- description: description.replace(/\s+/g, " ").trim(),
290
- };
291
- }
292
-
293
- // Skills are marked by SKILL.md (canonical) or skill.md (legacy). Discovery uses
294
- // a case-insensitive regex, so detection/adoption MUST accept both spellings —
295
- // otherwise a lowercase skill.md installs but is invisible to the unmanaged scan
296
- // and to local-skill adoption. Returns the marker's absolute path, or null.
297
- function findSkillMarker(dir) {
298
- for (const name of ["SKILL.md", "skill.md"]) {
299
- const candidate = path.join(dir, name);
300
- try {
301
- if (fs.statSync(candidate).isFile()) return candidate;
302
- } catch (_e) {
303
- // not present under this spelling
304
- }
305
- }
306
- return null;
307
- }
308
-
309
- const MAX_LOCAL_SKILL_SCAN_DEPTH = 3;
310
-
311
- function scanSkillDirectories(rootDir, { maxDepth = MAX_LOCAL_SKILL_SCAN_DEPTH } = {}) {
312
- const found = [];
313
- const walk = (dir, relDir = "", depth = 0) => {
314
- let entries = [];
315
- try {
316
- entries = fs.readdirSync(dir, { withFileTypes: true });
317
- } catch (_e) {
318
- return;
319
- }
320
- entries.sort((a, b) => a.name.localeCompare(b.name));
321
- for (const entry of entries) {
322
- if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
323
- if (!entry.name || entry.name.startsWith(".")) continue;
324
- const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
325
- const full = path.join(dir, entry.name);
326
- if (findSkillMarker(full)) {
327
- found.push(rel);
328
- continue;
329
- }
330
- // Direct symlinked skills are accepted above, but symlinked group folders
331
- // are not traversed so the scan stays within the target skills tree.
332
- if (entry.isDirectory() && depth + 1 < maxDepth) walk(full, rel, depth + 1);
333
- }
334
- };
335
- walk(rootDir);
336
- return found;
337
- }
338
-
339
- const INVENTORY_PLUGIN_SCAN_DEPTH = 6;
340
-
341
- function completeTargetStates(activeTargetId) {
342
- return Object.fromEntries(
343
- Object.keys(TARGETS).map((id) => [id, id === activeTargetId ? "synced" : "off"]),
344
- );
345
- }
346
-
347
- function inventorySkillFromMarker({
348
- marker,
349
- directory,
350
- id,
351
- targetId,
352
- scope,
353
- sourceName = null,
354
- }) {
355
- try {
356
- const metadata = readSkillMetadata(
357
- fs.readFileSync(marker, "utf8"),
358
- installNameFromDirectory(directory) || directory,
359
- );
360
- return {
361
- id,
362
- key: id,
363
- name: metadata.name,
364
- description: metadata.description,
365
- directory,
366
- readmeUrl: null,
367
- repoOwner: null,
368
- repoName: null,
369
- repoBranch: null,
370
- installedAt: null,
371
- managed: false,
372
- readOnly: true,
373
- inventoryOnly: true,
374
- scope,
375
- sourceName,
376
- targets: [targetId],
377
- targetStates: completeTargetStates(targetId),
378
- };
379
- } catch (_e) {
380
- return null;
381
- }
382
- }
383
-
384
- // Plugin caches use <publisher>/<plugin>/<version>/skills/<skill>/SKILL.md.
385
- // Walk only far enough to find a directory literally named "skills", then use
386
- // the bounded skill scanner below it. We never traverse node_modules, hidden
387
- // metadata directories, or symlinked group directories.
388
- function scanPluginInventoryRoot({ root, targetId }) {
389
- const found = [];
390
- const walk = (dir, depth = 0) => {
391
- let entries = [];
392
- try {
393
- entries = fs.readdirSync(dir, { withFileTypes: true });
394
- } catch (_e) {
395
- return;
396
- }
397
- entries.sort((a, b) => a.name.localeCompare(b.name));
398
- for (const entry of entries) {
399
- if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
400
- if (!entry.name || entry.name.startsWith(".") || entry.name === "node_modules") continue;
401
- const full = path.join(dir, entry.name);
402
- if (entry.name.toLowerCase() === "skills") {
403
- const container = path.relative(root, full).replace(/\\/g, "/");
404
- const beforeSkills = container.split("/").filter(Boolean).slice(0, -1);
405
- // Drop the cache version from the identity so installing a newer plugin
406
- // version updates one inventory row instead of creating a duplicate.
407
- const looksLikeVersion = (value) => /^v?\d+(?:\.\d+)*$/.test(String(value || ""));
408
- const packageParts =
409
- beforeSkills.length > 1 && looksLikeVersion(beforeSkills[beforeSkills.length - 1])
410
- ? beforeSkills.slice(0, -1)
411
- : beforeSkills;
412
- const sourceName = packageParts.join("/") || beforeSkills.join("/") || null;
413
- for (const directory of scanSkillDirectories(full, { maxDepth: 5 })) {
414
- const marker = findSkillMarker(path.join(full, directory));
415
- if (!marker) continue;
416
- const sourceKey = sourceName || "plugin";
417
- const id = `inventory:${targetId}:plugin:${sourceKey}:${directory}`;
418
- const skill = inventorySkillFromMarker({
419
- marker,
420
- directory,
421
- id,
422
- targetId,
423
- scope: "plugin",
424
- sourceName,
425
- });
426
- if (skill) found.push(skill);
427
- }
428
- continue;
429
- }
430
- if (depth + 1 < INVENTORY_PLUGIN_SCAN_DEPTH) walk(full, depth + 1);
431
- }
432
- };
433
- walk(root);
434
- return found;
435
- }
436
-
437
- function listInventorySkills() {
438
- const sources = [
439
- {
440
- root: path.join(resolveCodexHome(), "plugins", "cache"),
441
- targetId: "codex",
442
- },
443
- {
444
- root: path.join(os.homedir(), ".claude", "plugins", "cache"),
445
- targetId: "claude",
446
- },
447
- {
448
- root: path.join(resolveZcodeHome(), "cli", "plugins", "cache"),
449
- targetId: "zcode",
450
- },
451
- ];
452
- const byId = new Map();
453
- for (const source of sources) {
454
- const skills = scanPluginInventoryRoot(source);
455
- // Later (normally newer, lexically sorted cache version) copies replace an
456
- // older version with the same stable plugin+skill identity.
457
- for (const skill of skills) byId.set(skill.id.toLowerCase(), skill);
458
- }
459
- return Array.from(byId.values());
460
- }
461
-
462
- const HASH_IGNORE = new Set([".git", ".DS_Store", "Thumbs.db", ".gitignore"]);
463
-
464
- // Stable content fingerprint of a skill directory: walk files in sorted order,
465
- // hashing each relative path + exec bit + bytes. Normalization-tolerant
466
- // (ignores VCS/OS noise) so it answers "did this skill change?" cheaply. Used to
467
- // record what was installed so checkUpdates() can detect upstream drift.
468
- function hashDirectory(dir) {
469
- const hash = crypto.createHash("sha256");
470
- const walk = (relDir) => {
471
- const absDir = relDir ? path.join(dir, relDir) : dir;
472
- let entries;
473
- try {
474
- entries = fs.readdirSync(absDir, { withFileTypes: true });
475
- } catch (_e) {
476
- return;
477
- }
478
- entries.sort((a, b) => a.name.localeCompare(b.name));
479
- for (const entry of entries) {
480
- if (HASH_IGNORE.has(entry.name)) continue;
481
- const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
482
- if (entry.isDirectory()) {
483
- walk(rel);
484
- } else if (entry.isFile()) {
485
- const abs = path.join(dir, rel);
486
- let stat;
487
- try {
488
- stat = fs.statSync(abs);
489
- } catch (_e) {
490
- continue;
491
- }
492
- const execBit = process.platform === "win32" ? 0 : stat.mode & 0o111 ? 1 : 0;
493
- hash.update(`${rel}\u0000${execBit}\u0000`);
494
- try {
495
- hash.update(fs.readFileSync(abs));
496
- } catch (_e) {
497
- // unreadable file — fold its absence in deterministically
498
- }
499
- hash.update("\u0000");
500
- }
501
- }
502
- };
503
- walk("");
504
- return hash.digest("hex");
505
- }
506
-
507
- function pathStrictlyWithin(parent, child) {
508
- const rel = path.relative(parent, child);
509
- return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
510
- }
511
-
512
- // Guard against copying a directory into a DESCENDANT of itself, which makes
513
- // cpSync recurse infinitely (dst/dst/dst…; issue #61 in the reference manager).
514
- // Uses literal resolved paths, not realpath: a target that is a symlink pointing
515
- // back at the SSOT source is a legitimate idempotent re-link (we removePath it
516
- // before re-creating), not recursion — resolving symlinks here would wrongly
517
- // reject every re-sync.
518
- function assertNotNested(source, dest) {
519
- const a = path.resolve(source);
520
- const b = path.resolve(dest);
521
- if (a === b) return; // same literal path = idempotent overwrite, not nesting
522
- if (pathStrictlyWithin(a, b) || pathStrictlyWithin(b, a)) {
523
- throw new Error("Refusing to sync a skill into its own directory tree");
524
- }
525
- }
526
-
527
- async function fetchJson(url) {
528
- const controller = new AbortController();
529
- const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
530
- try {
531
- const response = await fetch(url, {
532
- headers: {
533
- Accept: "application/vnd.github+json",
534
- "User-Agent": "tokenusage-skills",
535
- },
536
- signal: controller.signal,
537
- });
538
- if (response.status === 429 || response.status === 403) {
539
- throw new RateLimitError(`GitHub rate-limited this request (HTTP ${response.status}). Try again later.`);
540
- }
541
- if (!response.ok) throw new Error(`HTTP ${response.status}`);
542
- return response.json();
543
- } finally {
544
- clearTimeout(timeout);
545
- }
546
- }
547
-
548
- async function fetchText(url) {
549
- const controller = new AbortController();
550
- const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
551
- try {
552
- const response = await fetch(url, {
553
- headers: { Accept: "text/plain", "User-Agent": "tokenusage-skills" },
554
- signal: controller.signal,
555
- });
556
- if (response.status === 429 || response.status === 403) {
557
- throw new RateLimitError(`GitHub rate-limited this request (HTTP ${response.status}). Try again later.`);
558
- }
559
- if (!response.ok) throw new Error(`HTTP ${response.status}`);
560
- return response.text();
561
- } finally {
562
- clearTimeout(timeout);
563
- }
564
- }
565
-
566
- function githubRawUrl(owner, name, branch, filePath) {
567
- return `https://raw.githubusercontent.com/${owner}/${name}/${branch}/${filePath
568
- .split("/")
569
- .map(encodeURIComponent)
570
- .join("/")}`;
571
- }
572
-
573
- function githubDocUrl(owner, name, branch, filePath) {
574
- return `https://github.com/${owner}/${name}/blob/${branch}/${filePath
575
- .split("/")
576
- .map(encodeURIComponent)
577
- .join("/")}`;
578
- }
579
-
580
- async function getRepoTree(repo) {
581
- const branches = [];
582
- if (repo.branch && !String(repo.branch).match(/^head$/i)) branches.push(repo.branch);
583
- if (!branches.includes("main")) branches.push("main");
584
- if (!branches.includes("master")) branches.push("master");
585
-
586
- let lastError = null;
587
- for (const branch of branches) {
588
- try {
589
- const data = await fetchJson(
590
- `https://api.github.com/repos/${repo.owner}/${repo.name}/git/trees/${encodeURIComponent(branch)}?recursive=1`,
591
- );
592
- if (Array.isArray(data?.tree)) return { branch, tree: data.tree };
593
- } catch (error) {
594
- lastError = error;
595
- }
596
- }
597
- throw lastError || new Error(`Unable to read ${repo.owner}/${repo.name}`);
598
- }
599
-
600
- // Upstream signature for one skill subtree: hash the sorted "path:blobSha" pairs
601
- // of every file under `sourceDir`. Git blob SHAs change iff content changes, so
602
- // comparing a stored signature against a freshly fetched tree detects an
603
- // "update available" using a SINGLE tree API call per repo — no per-file fetch.
604
- function sourceSignatureFromTree(tree, sourceDir) {
605
- if (!Array.isArray(tree) || !sourceDir) return null;
606
- const prefix = `${sourceDir}/`;
607
- const rels = tree
608
- .filter(
609
- (entry) =>
610
- entry?.type === "blob" &&
611
- entry.sha &&
612
- (entry.path === sourceDir || String(entry.path || "").startsWith(prefix)),
613
- )
614
- .map((entry) => `${entry.path}:${entry.sha}`)
615
- .sort();
616
- if (!rels.length) return null;
617
- return crypto.createHash("sha256").update(rels.join("\n")).digest("hex");
618
- }
619
-
620
- function buildSkillKey(skill) {
621
- return `${skill.repoOwner}/${skill.repoName}:${skill.directory}`;
622
- }
623
-
624
- function normalizeRepo(repo) {
625
- return {
626
- owner: String(repo?.owner || "").trim(),
627
- name: String(repo?.name || "").trim(),
628
- branch: String(repo?.branch || "main").trim() || "main",
629
- enabled: repo?.enabled !== false,
630
- };
631
- }
632
-
633
- async function discoverRepoSkills(repoInput) {
634
- const repo = normalizeRepo(repoInput);
635
- if (!repo.owner || !repo.name || !repo.enabled) return [];
636
- const { branch, tree } = await getRepoTree(repo);
637
- const skillFiles = tree
638
- .filter((entry) => entry?.type === "blob" && /(^|\/)SKILL\.md$/i.test(entry.path || ""))
639
- .slice(0, 200);
640
-
641
- const skills = await mapWithConcurrency(skillFiles, DISCOVER_CONCURRENCY, async (entry) => {
642
- const docPath = entry.path.replace(/\\/g, "/");
643
- // Strip the marker case-insensitively (SKILL.md or legacy skill.md) so a
644
- // lowercase-marker repo derives the right directory instead of falling
645
- // through to repo.name — mirrors findSkillMarker() on the local side.
646
- const directory = docPath.replace(/(^|\/)(?:SKILL|skill)\.md$/i, "") || repo.name;
647
- const installName = installNameFromDirectory(directory || repo.name);
648
- if (!installName) return null;
649
- let metadata = { name: installName, description: "" };
650
- try {
651
- metadata = readSkillMetadata(await fetchText(githubRawUrl(repo.owner, repo.name, branch, docPath)), installName);
652
- } catch (error) {
653
- if (error instanceof RateLimitError) throw error;
654
- // Keep the skill discoverable even if metadata fetch fails.
655
- }
656
- return {
657
- key: `${repo.owner}/${repo.name}:${directory || repo.name}`,
658
- name: metadata.name,
659
- description: metadata.description,
660
- directory: directory || repo.name,
661
- readmeUrl: githubDocUrl(repo.owner, repo.name, branch, docPath),
662
- repoOwner: repo.owner,
663
- repoName: repo.name,
664
- repoBranch: branch,
665
- };
666
- });
667
- return skills.filter(Boolean);
668
- }
669
-
670
- function dedupeSkills(skills) {
671
- const byKey = new Map();
672
- for (const skill of skills) byKey.set(buildSkillKey(skill).toLowerCase(), skill);
673
- return Array.from(byKey.values()).sort((a, b) => a.name.localeCompare(b.name));
674
- }
675
-
676
- function readDiscoverCache(fingerprint) {
677
- const data = readJson(discoverCachePath(), null);
678
- if (!data || typeof data !== "object" || !Array.isArray(data.skills)) return null;
679
- if (data.fingerprint !== fingerprint) return null;
680
- if (!Number.isFinite(data.generatedAt)) return null;
681
- if (Date.now() - data.generatedAt > DISCOVER_CACHE_TTL_MS) return null;
682
- return data;
683
- }
684
-
685
- function writeDiscoverCache(fingerprint, skills) {
686
- writeJson(discoverCachePath(), { fingerprint, generatedAt: Date.now(), skills });
687
- }
688
-
689
- function invalidateDiscoverCache() {
690
- try {
691
- fs.rmSync(discoverCachePath(), { force: true });
692
- } catch (_e) {
693
- // ignore
694
- }
695
- }
696
-
697
- async function discoverSkills({ force = false } = {}) {
698
- const registry = readRegistry();
699
- const enabled = registry.repos.map(normalizeRepo).filter((repo) => repo.enabled);
700
- if (!enabled.length) return { skills: [], cached: false, generatedAt: Date.now() };
701
-
702
- const fingerprint = enabled
703
- .map((repo) => `${repo.owner}/${repo.name}@${repo.branch}`)
704
- .sort()
705
- .join("|");
706
-
707
- if (!force) {
708
- const cached = readDiscoverCache(fingerprint);
709
- if (cached) return { skills: cached.skills, cached: true, generatedAt: cached.generatedAt };
710
- }
711
-
712
- const settled = await Promise.allSettled(enabled.map(discoverRepoSkills));
713
- const merged = dedupeSkills(settled.flatMap((result) => (result.status === "fulfilled" ? result.value : [])));
714
- if (!merged.length) {
715
- const rateLimited = settled.find(
716
- (result) => result.status === "rejected" && result.reason instanceof RateLimitError,
717
- );
718
- if (rateLimited) throw rateLimited.reason;
719
- }
720
- writeDiscoverCache(fingerprint, merged);
721
- return { skills: merged, cached: false, generatedAt: Date.now() };
722
- }
723
-
724
- function removePath(targetPath) {
725
- if (!fs.existsSync(targetPath) && !isSymlink(targetPath)) return;
726
- fs.rmSync(targetPath, { recursive: true, force: true });
727
- }
728
-
729
- function isSymlink(targetPath) {
730
- try {
731
- return fs.lstatSync(targetPath).isSymbolicLink();
732
- } catch (_e) {
733
- return false;
734
- }
735
- }
736
-
737
- function targetSkillPath(baseDir, directory) {
738
- const safe = sanitizeRelativePath(directory);
739
- if (!safe) return null;
740
- const root = path.resolve(baseDir);
741
- const targetPath = path.resolve(root, safe);
742
- if (!pathStrictlyWithin(root, targetPath)) return null;
743
- try {
744
- const rootStat = fs.statSync(root);
745
- if (!rootStat.isDirectory()) return null;
746
- } catch (e) {
747
- if (e?.code !== "ENOENT") return null;
748
- }
749
- const parts = safe.split("/");
750
- let current = root;
751
- for (let i = 0; i < parts.length - 1; i += 1) {
752
- current = path.join(current, parts[i]);
753
- let stat;
754
- try {
755
- stat = fs.lstatSync(current);
756
- } catch (e) {
757
- if (e?.code === "ENOENT") continue;
758
- return null;
759
- }
760
- if (stat.isSymbolicLink() || !stat.isDirectory()) return null;
761
- }
762
- return targetPath;
763
- }
764
-
765
- function managedSkillPath(directory) {
766
- const skillPath = targetSkillPath(ssotDir(), directory);
767
- if (!skillPath) throw new Error(`Invalid skill directory: ${directory}`);
768
- return skillPath;
769
- }
770
-
771
- function copyDir(source, dest) {
772
- assertNotNested(source, dest);
773
- removePath(dest);
774
- // Node22's native recursive copy can terminate the process on Windows
775
- // Unicode paths (nodejs/node#59636). A filter preserves every entry while
776
- // selecting Node's JS directory walker; keep the synchronous safety guards.
777
- fs.cpSync(source, dest, {
778
- recursive: true,
779
- force: true,
780
- ...(process.platform === "win32" ? { filter: () => true } : {}),
781
- });
782
- }
783
-
784
- function removeEmptyAncestors(startDir, stopDir) {
785
- let current = path.resolve(startDir);
786
- const stop = path.resolve(stopDir);
787
- while (pathStrictlyWithin(stop, current)) {
788
- try {
789
- fs.rmdirSync(current);
790
- } catch (_e) {
791
- return;
792
- }
793
- current = path.dirname(current);
794
- }
795
- }
796
-
797
- function syncSkillToTarget(directory, targetId) {
798
- const target = TARGETS[targetId];
799
- if (!target || target.manageable === false) throw new Error(`Unsupported target: ${targetId}`);
800
- const source = managedSkillPath(directory);
801
- if (!fs.existsSync(source)) throw new Error(`Managed skill not found: ${directory}`);
802
- for (const baseDir of targetDirs(target)) {
803
- const dest = targetSkillPath(baseDir, directory);
804
- if (!dest) throw new Error(`Invalid skill directory: ${directory}`);
805
- assertNotNested(source, dest);
806
- ensureDir(path.dirname(dest));
807
- removePath(dest);
808
- try {
809
- fs.symlinkSync(source, dest, "dir");
810
- } catch (_e) {
811
- copyDir(source, dest);
812
- }
813
- }
814
- }
815
-
816
- function removeSkillFromTarget(directory, targetId) {
817
- const target = TARGETS[targetId];
818
- if (!target) return;
819
- for (const baseDir of targetDirs(target)) {
820
- const targetPath = targetSkillPath(baseDir, directory);
821
- if (!targetPath) continue;
822
- removePath(targetPath);
823
- removeEmptyAncestors(path.dirname(targetPath), baseDir);
824
- }
825
- }
826
-
827
- function scanTargetSkill(directory, targetId) {
828
- const target = TARGETS[targetId];
829
- if (!target) return false;
830
- for (const baseDir of targetDirs(target)) {
831
- const candidate = targetSkillPath(baseDir, directory);
832
- if (!candidate) continue;
833
- if (fs.existsSync(candidate) || isSymlink(candidate)) return true;
834
- }
835
- return false;
836
- }
837
-
838
- // Disk truth for one (skill, target): "synced" (present + resolvable),
839
- // "orphan" (a dangling symlink whose SSOT source was deleted), or "off".
840
- // Powers the tri-state agent dots so the UI never claims a skill is synced when
841
- // its link is broken. For multi-dir targets, the healthiest state wins.
842
- function classifyTargetSkill(directory, targetId) {
843
- const target = TARGETS[targetId];
844
- if (!target) return "off";
845
- let state = "off";
846
- for (const baseDir of targetDirs(target)) {
847
- const candidate = targetSkillPath(baseDir, directory);
848
- if (!candidate) continue;
849
- if (fs.existsSync(candidate)) return "synced";
850
- if (isSymlink(candidate)) state = "orphan";
851
- }
852
- return state;
853
- }
854
-
855
- function listInstalledSkills() {
856
- purgeExpiredTrash();
857
- const registry = readRegistry();
858
- const managed = registry.skills
859
- .filter((skill) => !skill.trashedAt)
860
- .map((skill) => {
861
- const intended = new Set(skill.targets || []);
862
- const targetStates = {};
863
- const targets = [];
864
- for (const id of Object.keys(TARGETS)) {
865
- let state = classifyTargetSkill(skill.directory, id);
866
- // Registry says it should be synced here, but disk lost it → orphan.
867
- if (state === "off" && intended.has(id)) state = "orphan";
868
- targetStates[id] = state;
869
- if (state === "synced") targets.push(id);
870
- }
871
- return { ...skill, managed: true, targets, targetStates };
872
- });
873
-
874
- const managedDirs = new Set(managed.map((skill) => skill.directory.toLowerCase()));
875
- const unmanaged = new Map();
876
- for (const target of Object.values(TARGETS)) {
877
- for (const dir of targetDirs(target)) {
878
- for (const directory of scanSkillDirectories(dir)) {
879
- if (!directory || managedDirs.has(directory.toLowerCase())) continue;
880
- const skillPath = findSkillMarker(path.join(dir, directory));
881
- if (!skillPath) continue;
882
- const metadata = readSkillMetadata(fs.readFileSync(skillPath, "utf8"), installNameFromDirectory(directory) || directory);
883
- const key = directory.toLowerCase();
884
- if (!unmanaged.has(key)) {
885
- unmanaged.set(key, {
886
- id: `local:${directory}`,
887
- key: `local:${directory}`,
888
- name: metadata.name,
889
- description: metadata.description,
890
- directory,
891
- readmeUrl: null,
892
- repoOwner: null,
893
- repoName: null,
894
- repoBranch: null,
895
- installedAt: null,
896
- managed: false,
897
- targets: [],
898
- // Complete map (all agents default "off") so the frontend can trust
899
- // targetStates as the single source of truth — same shape as managed.
900
- targetStates: Object.fromEntries(Object.keys(TARGETS).map((id) => [id, "off"])),
901
- targetPaths: {},
902
- });
903
- }
904
- const skill = unmanaged.get(key);
905
- if (!skill.targets.includes(target.id)) skill.targets.push(target.id);
906
- skill.targetStates[target.id] = "synced";
907
- if (!skill.targetPaths[target.id]) skill.targetPaths[target.id] = path.join(dir, directory);
908
- }
909
- }
910
- }
911
-
912
- return [...managed, ...unmanaged.values(), ...listInventorySkills()].sort((a, b) => {
913
- const byName = a.name.localeCompare(b.name);
914
- if (byName !== 0) return byName;
915
- return String(a.id || a.key || "").localeCompare(String(b.id || b.key || ""));
916
- });
917
- }
918
-
919
- async function installSkill(
920
- skillInput,
921
- targetIds = ["claude", "codex"],
922
- prefetchedTree = null,
923
- { expectExistingId = null } = {},
924
- ) {
925
- const skill = {
926
- key: String(skillInput?.key || ""),
927
- name: String(skillInput?.name || ""),
928
- description: String(skillInput?.description || ""),
929
- directory: String(skillInput?.directory || ""),
930
- readmeUrl: skillInput?.readmeUrl || null,
931
- repoOwner: String(skillInput?.repoOwner || ""),
932
- repoName: String(skillInput?.repoName || ""),
933
- repoBranch: String(skillInput?.repoBranch || "main") || "main",
934
- };
935
- if (!skill.repoOwner || !skill.repoName) throw new Error("Missing GitHub repository information");
936
- const sourceDir = sanitizeRelativePath(skill.directory);
937
- // GitHub-sourced skills keep the historical flat install name even when
938
- // sourceDirectory is nested; local nested-skill support uses importLocalSkill().
939
- const installName = installNameFromDirectory(sourceDir);
940
- if (!sourceDir || !installName) throw new Error("Invalid skill directory");
941
-
942
- const registry = readRegistry();
943
- const existingConflict = registry.skills.find(
944
- (entry) =>
945
- entry.directory.toLowerCase() === installName.toLowerCase() &&
946
- `${entry.repoOwner}/${entry.repoName}`.toLowerCase() !== `${skill.repoOwner}/${skill.repoName}`.toLowerCase(),
947
- );
948
- if (existingConflict) {
949
- throw new Error(
950
- `Skill directory "${installName}" is already managed by ${existingConflict.repoOwner}/${existingConflict.repoName}`,
951
- );
952
- }
953
-
954
- // Bulk update hands in the repo tree it already fetched, so N skills from one
955
- // repo cost one GitHub call instead of N.
956
- const { branch, tree } = prefetchedTree || await getRepoTree({
957
- owner: skill.repoOwner,
958
- name: skill.repoName,
959
- branch: skill.repoBranch,
960
- });
961
- const files = tree.filter(
962
- (entry) => entry?.type === "blob" && (entry.path === sourceDir || String(entry.path || "").startsWith(`${sourceDir}/`)),
963
- );
964
- if (!files.some((entry) => /(^|\/)SKILL\.md$/i.test(entry.path))) throw new Error("SKILL.md not found in selected directory");
965
-
966
- const dest = managedSkillPath(installName);
967
- let selectedTargets = targetIds.filter((id) => TARGETS[id]);
968
- const tempRoot = path.join(dataDir(), "tmp");
969
- ensureDir(tempRoot);
970
- const temp = fs.mkdtempSync(path.join(tempRoot, `${installName}-`));
971
- try {
972
- for (const entry of files) {
973
- const relative = entry.path === sourceDir ? path.basename(entry.path) : entry.path.slice(sourceDir.length + 1);
974
- const safeRelative = sanitizeRelativePath(relative);
975
- if (!safeRelative) continue;
976
- const out = path.join(temp, safeRelative);
977
- ensureDir(path.dirname(out));
978
- fs.writeFileSync(out, await fetchText(githubRawUrl(skill.repoOwner, skill.repoName, branch, entry.path)));
979
- }
980
- // An update must not recreate a skill that was uninstalled while we were
981
- // downloading, nor overwrite whatever took its install directory in the
982
- // meantime. Checked here because everything from this point to
983
- // saveRegistry() is synchronous — no await can interleave a change we would
984
- // then clobber.
985
- if (expectExistingId) {
986
- const current = readRegistry().skills.find((entry) => !entry.trashedAt && entry.id === expectExistingId);
987
- if (!current) throw new Error("Skill is no longer installed");
988
- // Another page or API caller may have changed target intent during a download.
989
- selectedTargets = (current.targets || []).filter((id) => TARGETS[id]);
990
- }
991
- removePath(dest);
992
- ensureDir(path.dirname(dest));
993
- fs.renameSync(temp, dest);
994
- } catch (error) {
995
- removePath(temp);
996
- throw error;
997
- }
998
-
999
- const skillMarker = findSkillMarker(dest);
1000
- const skillMd = skillMarker ? fs.readFileSync(skillMarker, "utf8") : "";
1001
- const metadata = readSkillMetadata(skillMd, skill.name || installName);
1002
- const installed = {
1003
- id: `${skill.repoOwner}/${skill.repoName}:${sourceDir}`,
1004
- key: `${skill.repoOwner}/${skill.repoName}:${sourceDir}`,
1005
- name: metadata.name,
1006
- description: metadata.description || skill.description,
1007
- directory: installName,
1008
- sourceDirectory: sourceDir,
1009
- readmeUrl: githubDocUrl(skill.repoOwner, skill.repoName, branch, `${sourceDir}/SKILL.md`),
1010
- repoOwner: skill.repoOwner,
1011
- repoName: skill.repoName,
1012
- repoBranch: branch,
1013
- installedAt: Date.now(),
1014
- // Fingerprints power idempotent reinstall + the "update available" badge.
1015
- contentHash: hashDirectory(dest),
1016
- sourceSignature: sourceSignatureFromTree(tree, sourceDir),
1017
- targets: selectedTargets,
1018
- };
1019
-
1020
- // Re-read: the downloads above can take minutes and the registry is shared
1021
- // with every other mutation path, so the copy fetched before them is stale by
1022
- // now. Reading here keeps the read/modify/write window down to this block.
1023
- const latest = readRegistry();
1024
- latest.skills = latest.skills.filter((entry) => entry.id !== installed.id && entry.directory.toLowerCase() !== installName.toLowerCase());
1025
- latest.skills.push(installed);
1026
- saveRegistry(latest);
1027
-
1028
- for (const id of selectedTargets) syncSkillToTarget(installName, id);
1029
- appendActivity({ action: "install", name: installed.name, directory: installName, targets: selectedTargets, source: `${skill.repoOwner}/${skill.repoName}` });
1030
- return { ...installed, managed: true, targets: selectedTargets };
1031
- }
1032
-
1033
- function uninstallSkill(id) {
1034
- const registry = readRegistry();
1035
- const skill = registry.skills.find((entry) => entry.id === id || entry.key === id);
1036
- if (!skill) throw new Error("Managed skill not found");
1037
- const ssotPath = managedSkillPath(skill.directory);
1038
- for (const targetId of Object.keys(TARGETS)) removeSkillFromTarget(skill.directory, targetId);
1039
- // Move SSOT copy into a trash bucket so it can be restored briefly. The
1040
- // registry entry is retained but flagged so restoreSkill can re-link it.
1041
- if (fs.existsSync(ssotPath)) {
1042
- ensureDir(trashDir());
1043
- const stamp = Date.now();
1044
- const trashName = `${Buffer.from(String(skill.directory || ""), "utf8").toString("base64url")}-${stamp}`;
1045
- const trashPath = path.join(trashDir(), trashName);
1046
- try {
1047
- fs.renameSync(ssotPath, trashPath);
1048
- removeEmptyAncestors(path.dirname(ssotPath), ssotDir());
1049
- skill.trashedAt = stamp;
1050
- skill.trashedDirectory = path.basename(trashPath);
1051
- skill.previousTargets = skill.targets || [];
1052
- skill.targets = [];
1053
- const others = registry.skills.filter((entry) => entry.id !== skill.id);
1054
- registry.skills = [...others, skill];
1055
- saveRegistry(registry);
1056
- purgeExpiredTrash();
1057
- appendActivity({ action: "uninstall", name: skill.name, directory: skill.directory });
1058
- return { ok: true, trashed: true, restoreId: skill.id, ttlMs: TRASH_TTL_MS };
1059
- } catch (_e) {
1060
- removePath(ssotPath);
1061
- removeEmptyAncestors(path.dirname(ssotPath), ssotDir());
1062
- }
1063
- }
1064
- registry.skills = registry.skills.filter((entry) => entry.id !== skill.id);
1065
- saveRegistry(registry);
1066
- appendActivity({ action: "uninstall", name: skill.name, directory: skill.directory });
1067
- return { ok: true, trashed: false };
1068
- }
1069
-
1070
- function purgeExpiredTrash() {
1071
- try {
1072
- const registry = readRegistry();
1073
- const now = Date.now();
1074
- let dirty = false;
1075
- registry.skills = registry.skills.filter((skill) => {
1076
- if (!skill.trashedAt) return true;
1077
- if (now - skill.trashedAt < TRASH_TTL_MS) return true;
1078
- const trashPath = skill.trashedDirectory ? path.join(trashDir(), skill.trashedDirectory) : null;
1079
- if (trashPath) removePath(trashPath);
1080
- dirty = true;
1081
- return false;
1082
- });
1083
- if (dirty) saveRegistry(registry);
1084
- } catch (_e) {
1085
- // best-effort
1086
- }
1087
- }
1088
-
1089
- function restoreSkill(id) {
1090
- const registry = readRegistry();
1091
- const skill = registry.skills.find((entry) => entry.id === id || entry.key === id);
1092
- if (!skill || !skill.trashedAt) throw new Error("Nothing to restore");
1093
- if (Date.now() - skill.trashedAt > TRASH_TTL_MS) {
1094
- throw new Error("Restore window expired");
1095
- }
1096
- const trashPath = path.join(trashDir(), skill.trashedDirectory || "");
1097
- const ssotPath = managedSkillPath(skill.directory);
1098
- if (!fs.existsSync(trashPath)) throw new Error("Trashed copy is missing");
1099
- ensureDir(path.dirname(ssotPath));
1100
- removePath(ssotPath);
1101
- fs.renameSync(trashPath, ssotPath);
1102
- const targets = Array.isArray(skill.previousTargets) ? skill.previousTargets : [];
1103
- skill.targets = targets;
1104
- delete skill.trashedAt;
1105
- delete skill.trashedDirectory;
1106
- delete skill.previousTargets;
1107
- saveRegistry(registry);
1108
- for (const targetId of targets) syncSkillToTarget(skill.directory, targetId);
1109
- appendActivity({ action: "restore", name: skill.name, directory: skill.directory, targets });
1110
- return { ...skill, managed: true, targets };
1111
- }
1112
-
1113
- function setSkillTargets(id, targetIds) {
1114
- const registry = readRegistry();
1115
- const skill = registry.skills.find((entry) => entry.id === id || entry.key === id);
1116
- if (!skill) throw new Error("Managed skill not found");
1117
- const selectedTargets = targetIds.filter((targetId) => TARGETS[targetId]);
1118
- for (const targetId of Object.keys(TARGETS)) {
1119
- if (selectedTargets.includes(targetId)) syncSkillToTarget(skill.directory, targetId);
1120
- else removeSkillFromTarget(skill.directory, targetId);
1121
- }
1122
- skill.targets = selectedTargets;
1123
- saveRegistry(registry);
1124
- appendActivity({ action: "set_targets", name: skill.name, directory: skill.directory, targets: selectedTargets });
1125
- return { ...skill, managed: true, targets: selectedTargets };
1126
- }
1127
-
1128
- function findLocalSkillSource(directory) {
1129
- const sourceDir = sanitizeLocalSkillPath(directory);
1130
- if (!sourceDir) return null;
1131
- for (const target of Object.values(TARGETS)) {
1132
- for (const baseDir of targetDirs(target)) {
1133
- const skillPath = targetSkillPath(baseDir, sourceDir);
1134
- if (!skillPath) continue;
1135
- if (findSkillMarker(skillPath)) {
1136
- return { path: skillPath, targetId: target.id };
1137
- }
1138
- }
1139
- }
1140
- return null;
1141
- }
1142
-
1143
- function importLocalSkill(directory, targetIds = []) {
1144
- const sourceDir = sanitizeLocalSkillPath(directory);
1145
- if (!sourceDir) throw new Error("Invalid skill directory");
1146
- const registry = readRegistry();
1147
- const existing = registry.skills.find((entry) => String(entry.directory || "").toLowerCase() === sourceDir.toLowerCase());
1148
- if (existing) {
1149
- if (!String(existing.id || existing.key || "").startsWith("local:")) {
1150
- throw new Error(`Skill directory "${sourceDir}" is already managed by another installed skill`);
1151
- }
1152
- if (!targetIds || !targetIds.length) {
1153
- return { ...existing, managed: true, targets: existing.targets || [] };
1154
- }
1155
- return setSkillTargets(existing.id, targetIds);
1156
- }
1157
-
1158
- const source = findLocalSkillSource(sourceDir);
1159
- if (!source) throw new Error("Local skill not found");
1160
-
1161
- const dest = managedSkillPath(sourceDir);
1162
- copyDir(source.path, dest);
1163
- const skillMarker = findSkillMarker(dest);
1164
- const metadata = readSkillMetadata(skillMarker ? fs.readFileSync(skillMarker, "utf8") : "", installNameFromDirectory(sourceDir));
1165
- const discoveredTargets = Object.keys(TARGETS).filter((targetId) => scanTargetSkill(sourceDir, targetId));
1166
- const selectedTargets = (targetIds.length ? targetIds : discoveredTargets).filter((targetId) => TARGETS[targetId]);
1167
- const skill = {
1168
- id: `local:${sourceDir}`,
1169
- key: `local:${sourceDir}`,
1170
- name: metadata.name,
1171
- description: metadata.description,
1172
- directory: sourceDir,
1173
- sourceDirectory: sourceDir,
1174
- readmeUrl: null,
1175
- repoOwner: null,
1176
- repoName: null,
1177
- repoBranch: null,
1178
- installedAt: Date.now(),
1179
- contentHash: hashDirectory(dest),
1180
- targets: selectedTargets,
1181
- };
1182
-
1183
- registry.skills.push(skill);
1184
- saveRegistry(registry);
1185
- for (const targetId of Object.keys(TARGETS)) {
1186
- if (selectedTargets.includes(targetId)) syncSkillToTarget(sourceDir, targetId);
1187
- else removeSkillFromTarget(sourceDir, targetId);
1188
- }
1189
- appendActivity({ action: "import", name: skill.name, directory: sourceDir, targets: selectedTargets });
1190
- return { ...skill, managed: true, targets: selectedTargets };
1191
- }
1192
-
1193
- function deleteLocalSkill(directory, targetIds = []) {
1194
- const installName = sanitizeLocalSkillPath(directory);
1195
- if (!installName) throw new Error("Invalid skill directory");
1196
- const selectedTargets = targetIds.length ? targetIds : Object.keys(TARGETS);
1197
- for (const targetId of selectedTargets) removeSkillFromTarget(installName, targetId);
1198
- appendActivity({ action: "delete_local", directory: installName, targets: selectedTargets });
1199
- return { ok: true };
1200
- }
1201
-
1202
- function listRepos() {
1203
- return readRegistry().repos.map(normalizeRepo);
1204
- }
1205
-
1206
- function addRepo(repoInput) {
1207
- const repo = normalizeRepo(repoInput);
1208
- if (!repo.owner || !repo.name) throw new Error("Repository owner and name are required");
1209
- if (!OWNER_NAME_PATTERN.test(repo.owner) || !OWNER_NAME_PATTERN.test(repo.name)) {
1210
- throw new Error("Repository owner and name may only contain letters, digits, '.', '_', or '-'");
1211
- }
1212
- if (!OWNER_NAME_PATTERN.test(repo.branch)) {
1213
- throw new Error("Repository branch contains unsupported characters");
1214
- }
1215
- const registry = readRegistry();
1216
- registry.repos = registry.repos.filter(
1217
- (entry) => `${entry.owner}/${entry.name}`.toLowerCase() !== `${repo.owner}/${repo.name}`.toLowerCase(),
1218
- );
1219
- registry.repos.push(repo);
1220
- saveRegistry(registry);
1221
- invalidateDiscoverCache();
1222
- return repo;
1223
- }
1224
-
1225
- function removeRepo(owner, name) {
1226
- const registry = readRegistry();
1227
- registry.repos = registry.repos.filter(
1228
- (entry) => `${entry.owner}/${entry.name}`.toLowerCase() !== `${owner}/${name}`.toLowerCase(),
1229
- );
1230
- saveRegistry(registry);
1231
- invalidateDiscoverCache();
1232
- return { ok: true };
1233
- }
1234
-
1235
- async function searchSkillsSh(query, limit = 20, offset = 0) {
1236
- const q = String(query || "").trim();
1237
- if (q.length < 2) return { query: q, totalCount: 0, skills: [] };
1238
- const url = new URL("https://skills.sh/api/search");
1239
- url.searchParams.set("q", q);
1240
- url.searchParams.set("limit", String(Math.max(1, Math.min(50, Number(limit) || 20))));
1241
- url.searchParams.set("offset", String(Math.max(0, Number(offset) || 0)));
1242
- const data = await fetchJson(url.toString());
1243
- const skills = Array.isArray(data?.skills)
1244
- ? data.skills
1245
- .map((entry) => {
1246
- const [owner, repoName] = String(entry?.source || "").split("/", 2);
1247
- if (!owner || !repoName || owner.includes(".") || repoName.includes(".")) return null;
1248
- return {
1249
- key: String(entry.id || `${owner}/${repoName}:${entry.skillId || entry.name}`),
1250
- name: String(entry.name || entry.skillId || "Skill"),
1251
- description: "",
1252
- directory: String(entry.skillId || entry.name || ""),
1253
- repoOwner: owner,
1254
- repoName,
1255
- repoBranch: "main",
1256
- readmeUrl: `https://github.com/${owner}/${repoName}`,
1257
- installs: Number(entry.installs || 0),
1258
- };
1259
- })
1260
- .filter(Boolean)
1261
- : [];
1262
- return {
1263
- query: String(data?.query || q),
1264
- totalCount: Number(data?.count || skills.length),
1265
- skills,
1266
- };
1267
- }
1268
-
1269
- const UPDATE_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour — bounds GitHub tree calls
1270
- const UPDATE_CHECK_CONCURRENCY = 2;
1271
-
1272
- function updateCachePath() {
1273
- return path.join(dataDir(), "updates-cache.json");
1274
- }
1275
-
1276
- // checkUpdates() and updateSkills() have to agree on three things: which skills
1277
- // are candidates, how a cached verdict is keyed, and which tree a skill's
1278
- // signature comes from. They share these so the badge and the update can never
1279
- // disagree about the same skill.
1280
- function managedUpdateCandidates(registry) {
1281
- return registry.skills.filter(
1282
- (skill) => !skill.trashedAt && skill.repoOwner && skill.repoName && skill.sourceSignature,
1283
- );
1284
- }
1285
-
1286
- function updateFingerprint(managed) {
1287
- return managed
1288
- .map((skill) => `${skill.id}@${skill.sourceSignature}`)
1289
- .sort()
1290
- .join("|");
1291
- }
1292
-
1293
- // Write the verdicts a round derived, carrying forward the previous map for
1294
- // anything it could not derive — a repo whose tree failed, everything past a
1295
- // rate-limited stop. "We could not check" must not render as "nothing is
1296
- // stale": that clears every badge and with it the way to retry. Returns the
1297
- // merged map. Entries for skills that are no longer installed are dropped.
1298
- //
1299
- // `full` says the round attempted the whole library, which only checkUpdates()
1300
- // does. An update attempts the ids it was handed, so it may only publish an
1301
- // entry when the carried map fills in the rest — see the guard below.
1302
- function writeUpdateCache(verdicts, { full = false } = {}) {
1303
- const managed = managedUpdateCandidates(readRegistry());
1304
- const live = new Set(managed.map((skill) => skill.id));
1305
- const cached = readJson(updateCachePath(), null);
1306
- const carriedFresh = Boolean(
1307
- cached &&
1308
- cached.updates &&
1309
- typeof cached.updates === "object" &&
1310
- Number.isFinite(cached.checkedAt) &&
1311
- Date.now() - cached.checkedAt < UPDATE_CACHE_TTL_MS,
1312
- );
1313
- const updates = {};
1314
- if (carriedFresh) {
1315
- for (const [id, stale] of Object.entries(cached.updates)) if (live.has(id)) updates[id] = Boolean(stale);
1316
- }
1317
- for (const [id, stale] of Object.entries(verdicts)) if (live.has(id)) updates[id] = Boolean(stale);
1318
-
1319
- // The entry is read back as a verdict for the entire library, and a missing
1320
- // key reads as "not stale". A partial round that stamped the library
1321
- // fingerprint would therefore publish silence about skills nobody looked at,
1322
- // and the next check would hit it. Leave the cache alone instead and let that
1323
- // check do the work.
1324
- if (!full && !managed.every((skill) => Object.prototype.hasOwnProperty.call(updates, skill.id))) {
1325
- return updates;
1326
- }
1327
-
1328
- writeJson(updateCachePath(), {
1329
- fingerprint: updateFingerprint(managed),
1330
- // A prime inherits the window of the check it built on: it re-derived some
1331
- // ids, not the library, so it must not restart the hour for the rest.
1332
- checkedAt: full || !carriedFresh ? Date.now() : cached.checkedAt,
1333
- updates,
1334
- });
1335
- return updates;
1336
- }
1337
-
1338
- function groupSkillsByRepo(skills) {
1339
- const byRepo = new Map();
1340
- for (const skill of skills) {
1341
- const branch = skill.repoBranch || "main";
1342
- const key = `${skill.repoOwner}/${skill.repoName}@${branch}`.toLowerCase();
1343
- if (!byRepo.has(key)) {
1344
- byRepo.set(key, { owner: skill.repoOwner, name: skill.repoName, branch, skills: [] });
1345
- }
1346
- byRepo.get(key).skills.push(skill);
1347
- }
1348
- return Array.from(byRepo.values());
1349
- }
1350
-
1351
- // Compare each managed GitHub/skills.sh skill's stored source signature against a
1352
- // freshly fetched repo tree. One tree call per repo (skills from the same repo
1353
- // share it), concurrency-limited and cached for an hour so a background check
1354
- // can't trip GitHub's unauthenticated rate limit. Returns { updates: {id:bool} }.
1355
- // Read-only: never mutates the registry or the on-disk skills.
1356
- async function checkUpdates({ force = false } = {}) {
1357
- const managed = managedUpdateCandidates(readRegistry());
1358
- const fingerprint = updateFingerprint(managed);
1359
-
1360
- if (!force) {
1361
- const cached = readJson(updateCachePath(), null);
1362
- if (
1363
- cached &&
1364
- cached.fingerprint === fingerprint &&
1365
- Number.isFinite(cached.checkedAt) &&
1366
- Date.now() - cached.checkedAt < UPDATE_CACHE_TTL_MS &&
1367
- cached.updates &&
1368
- typeof cached.updates === "object"
1369
- ) {
1370
- return { updates: cached.updates, checkedAt: cached.checkedAt, cached: true };
1371
- }
1372
- }
1373
-
1374
- const updates = {};
1375
- await mapWithConcurrency(groupSkillsByRepo(managed), UPDATE_CHECK_CONCURRENCY, async (repo) => {
1376
- let tree;
1377
- try {
1378
- ({ tree } = await getRepoTree(repo));
1379
- } catch (error) {
1380
- if (error instanceof RateLimitError) throw error;
1381
- return; // leave this repo's skills as unknown (omitted)
1382
- }
1383
- for (const skill of repo.skills) {
1384
- const signature = sourceSignatureFromTree(tree, skill.sourceDirectory || skill.directory);
1385
- if (signature) updates[skill.id] = signature !== skill.sourceSignature;
1386
- }
1387
- });
1388
-
1389
- const checkedAt = Date.now();
1390
- return { updates: writeUpdateCache(updates, { full: true }), checkedAt, cached: false };
1391
- }
1392
-
1393
- // Re-install managed skills from upstream, grouped by repo like checkUpdates()
1394
- // so N skills from one repo cost one tree call. Sequential by necessity:
1395
- // installSkill() read/modify/writes the registry, so parallel installs would
1396
- // drop each other's entries. Every requested id gets a result row — including
1397
- // ones that are no longer installed — so updated + skipped + failed always
1398
- // reconciles with what the caller asked for.
1399
- async function updateSkills(ids = []) {
1400
- // An empty or malformed list means "nothing was asked for", never "every
1401
- // managed skill" — the permissive reading turned one bad request field into a
1402
- // full re-install of the library.
1403
- const wanted = new Set(
1404
- (Array.isArray(ids) ? ids : []).map((id) => String(id || "")).filter(Boolean),
1405
- );
1406
- if (!wanted.size) return { results: [], updated: 0, skipped: 0, failed: 0, rateLimited: null };
1407
- const managed = readRegistry().skills.filter(
1408
- (skill) => !skill.trashedAt && skill.repoOwner && skill.repoName && wanted.has(skill.id),
1409
- );
1410
-
1411
- const results = [];
1412
- const verdicts = {};
1413
- let rateLimited = null;
1414
-
1415
- const known = new Set(managed.map((skill) => skill.id));
1416
- for (const id of wanted) {
1417
- if (!known.has(id)) results.push({ id, name: null, ok: false, error: "Skill is no longer installed" });
1418
- }
1419
-
1420
- for (const repo of groupSkillsByRepo(managed)) {
1421
- let branch;
1422
- let tree;
1423
- try {
1424
- ({ branch, tree } = await getRepoTree(repo));
1425
- } catch (error) {
1426
- if (error instanceof RateLimitError) {
1427
- rateLimited = error;
1428
- break;
1429
- }
1430
- for (const skill of repo.skills) {
1431
- results.push({ id: skill.id, name: skill.name, ok: false, error: error?.message || "Unable to read repository" });
1432
- }
1433
- continue;
1434
- }
1435
-
1436
- for (const skill of repo.skills) {
1437
- const sourceDir = skill.sourceDirectory || skill.directory;
1438
- const fresh = sourceSignatureFromTree(tree, sourceDir);
1439
- if (skill.sourceSignature && fresh === skill.sourceSignature) {
1440
- results.push({ id: skill.id, name: skill.name, ok: true, skipped: true });
1441
- verdicts[skill.id] = false;
1442
- continue;
1443
- }
1444
- // This loop runs for as long as the downloads take, and the registry is
1445
- // shared with every other mutation path — re-check rather than write back
1446
- // a skill that was uninstalled while we were working.
1447
- if (!readRegistry().skills.some((entry) => !entry.trashedAt && entry.id === skill.id)) {
1448
- results.push({ id: skill.id, name: skill.name, ok: false, error: "Skill is no longer installed" });
1449
- continue;
1450
- }
1451
- try {
1452
- await installSkill(
1453
- {
1454
- key: skill.key,
1455
- name: skill.name,
1456
- description: skill.description,
1457
- // installSkill() wants the repo path, not the flat install name.
1458
- directory: sourceDir,
1459
- readmeUrl: skill.readmeUrl,
1460
- repoOwner: skill.repoOwner,
1461
- repoName: skill.repoName,
1462
- repoBranch: branch,
1463
- },
1464
- skill.targets || [],
1465
- { branch, tree },
1466
- { expectExistingId: skill.id },
1467
- );
1468
- results.push({ id: skill.id, name: skill.name, ok: true, skipped: false });
1469
- if (fresh) verdicts[skill.id] = false;
1470
- } catch (error) {
1471
- if (error instanceof RateLimitError) {
1472
- rateLimited = error;
1473
- break;
1474
- }
1475
- results.push({ id: skill.id, name: skill.name, ok: false, error: error?.message || "Update failed" });
1476
- if (fresh) verdicts[skill.id] = true;
1477
- }
1478
- }
1479
- if (rateLimited) break;
1480
- }
1481
-
1482
- // A rate-limited stop breaks out of both loops, leaving the skill it happened
1483
- // on and everything after it unreported. Backfill so every requested id comes
1484
- // back with a row and the counts still reconcile with what was asked for.
1485
- if (rateLimited) {
1486
- const reported = new Set(results.map((row) => row.id));
1487
- const nameById = new Map(managed.map((skill) => [skill.id, skill.name]));
1488
- for (const id of wanted) {
1489
- if (reported.has(id)) continue;
1490
- results.push({ id, name: nameById.get(id) || null, ok: false, error: rateLimited.message });
1491
- }
1492
- }
1493
-
1494
- // Prime the cache from the trees this run already holds, so the refresh that
1495
- // follows is a cache hit rather than a second tree call per repo. Skipped when
1496
- // the run derived nothing — there is no fresh verdict to record.
1497
- if (Object.keys(verdicts).length) writeUpdateCache(verdicts);
1498
-
1499
- return {
1500
- results,
1501
- updated: results.filter((entry) => entry.ok && !entry.skipped).length,
1502
- skipped: results.filter((entry) => entry.skipped).length,
1503
- failed: results.filter((entry) => !entry.ok).length,
1504
- rateLimited: rateLimited ? rateLimited.message : null,
1505
- };
1506
- }
1507
-
1508
- // skills.sh exposes only /api/search (no leaderboard endpoint), so "Popular" is
1509
- // built honestly on top of it: fan a handful of broad seed queries, merge by
1510
- // skill key keeping the highest install count, sort by installs. Cached for 6h.
1511
- const POPULAR_SEED_QUERIES = [
1512
- "agent",
1513
- "code",
1514
- "test",
1515
- "review",
1516
- "git",
1517
- "web",
1518
- "design",
1519
- "data",
1520
- "docs",
1521
- "python",
1522
- "api",
1523
- "deploy",
1524
- ];
1525
- const POPULAR_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
1526
-
1527
- function popularCachePath() {
1528
- return path.join(dataDir(), "popular-cache.json");
1529
- }
1530
-
1531
- async function fetchPopularSkillsSh({ force = false, limit = 60 } = {}) {
1532
- const cap = Math.max(1, Math.min(200, Number(limit) || 60));
1533
- if (!force) {
1534
- const cached = readJson(popularCachePath(), null);
1535
- if (
1536
- cached &&
1537
- Array.isArray(cached.skills) &&
1538
- Number.isFinite(cached.generatedAt) &&
1539
- Date.now() - cached.generatedAt < POPULAR_CACHE_TTL_MS
1540
- ) {
1541
- return { skills: cached.skills.slice(0, cap), cached: true, generatedAt: cached.generatedAt };
1542
- }
1543
- }
1544
-
1545
- const lists = await mapWithConcurrency(POPULAR_SEED_QUERIES, DISCOVER_CONCURRENCY, async (q) => {
1546
- try {
1547
- return (await searchSkillsSh(q, 30, 0)).skills;
1548
- } catch (error) {
1549
- if (error instanceof RateLimitError) throw error;
1550
- return [];
1551
- }
1552
- });
1553
-
1554
- const byKey = new Map();
1555
- for (const list of lists) {
1556
- for (const skill of list) {
1557
- const key = String(skill.key || `${skill.repoOwner}/${skill.repoName}:${skill.directory}`).toLowerCase();
1558
- const prev = byKey.get(key);
1559
- if (!prev || (skill.installs || 0) > (prev.installs || 0)) byKey.set(key, skill);
1560
- }
1561
- }
1562
- const skills = Array.from(byKey.values())
1563
- .sort((a, b) => (b.installs || 0) - (a.installs || 0))
1564
- .slice(0, 200);
1565
- writeJson(popularCachePath(), { generatedAt: Date.now(), skills });
1566
- return { skills: skills.slice(0, cap), cached: false, generatedAt: Date.now() };
1567
- }
1568
-
1569
- module.exports = {
1570
- addRepo,
1571
- assertNotNested,
1572
- checkUpdates,
1573
- discoverSkills,
1574
- deleteLocalSkill,
1575
- fetchPopularSkillsSh,
1576
- findSkillMarker,
1577
- hashDirectory,
1578
- importLocalSkill,
1579
- installSkill,
1580
- listInstalledSkills,
1581
- listRepos,
1582
- readActivity,
1583
- removeRepo,
1584
- restoreSkill,
1585
- searchSkillsSh,
1586
- setSkillTargets,
1587
- sourceSignatureFromTree,
1588
- targetList,
1589
- uninstallSkill,
1590
- updateSkills,
1591
- };