tokenusage-cli 0.3.0 → 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 (47) hide show
  1. package/CHANGELOG.md +50 -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/sync.js +69 -15
  12. package/src/commands/uninstall.js +6 -9
  13. package/src/commands/upload.js +147 -0
  14. package/src/lib/cli-errors.js +33 -0
  15. package/src/lib/cli-ui.js +93 -0
  16. package/src/lib/queue-row-normalize.js +55 -0
  17. package/src/lib/scheduled-task.js +597 -75
  18. package/src/lib/antigravity-paths.js +0 -48
  19. package/src/lib/async-queue-reader.js +0 -138
  20. package/src/lib/atomic-json.js +0 -27
  21. package/src/lib/bearer-token.js +0 -11
  22. package/src/lib/cloud-account.js +0 -541
  23. package/src/lib/codex-context-breakdown.js +0 -806
  24. package/src/lib/context-health.js +0 -124
  25. package/src/lib/grok-context-breakdown.js +0 -890
  26. package/src/lib/heatmap-compact.js +0 -114
  27. package/src/lib/local-api.js +0 -3574
  28. package/src/lib/outcomes-engine.js +0 -253
  29. package/src/lib/pet-packages.js +0 -722
  30. package/src/lib/skill-usage.js +0 -267
  31. package/src/lib/skills-manager.js +0 -1591
  32. package/src/lib/source-metadata.js +0 -48
  33. package/src/lib/subscription-manager.js +0 -293
  34. package/src/lib/wrapped-aggregator.js +0 -236
  35. package/test/audit-fixes.test.js +0 -249
  36. package/test/branding.test.js +0 -24
  37. package/test/cli-options.test.js +0 -43
  38. package/test/cli-smoke.test.js +0 -53
  39. package/test/cli-ui.test.js +0 -47
  40. package/test/collection-controls.test.js +0 -255
  41. package/test/ingest-sanitize.test.js +0 -162
  42. package/test/packaging.test.js +0 -107
  43. package/test/quiet-warnings.test.js +0 -53
  44. package/test/runtime-copy.test.js +0 -111
  45. package/test/session-upload.test.js +0 -427
  46. package/test/trae-db.test.js +0 -67
  47. package/test/zstd-native.test.js +0 -36
@@ -1,722 +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 yauzl = require("yauzl");
6
-
7
- const PET_MANIFEST = "pet.json";
8
- const PET_SPRITESHEET = "spritesheet.webp";
9
- const MAX_PACKAGE_BYTES = 12 * 1024 * 1024;
10
- const MAX_MANIFEST_BYTES = 16 * 1024;
11
- const MAX_SPRITESHEET_BYTES = 10 * 1024 * 1024;
12
- // `bot` joins clawd as a built-in with no sprite atlas: it is drawn from the
13
- // vector engine in dashboard/src/lib/bot/, so it costs no disk space and is
14
- // therefore not in REMOVABLE_BUILTIN_IDS — that list exists to reclaim the
15
- // space an atlas takes.
16
- const BUILTIN_IDS = new Set(["clawd", "bot", "sprout", "byte", "ember"]);
17
- const REMOVABLE_BUILTIN_IDS = new Set(["sprout", "byte", "ember"]);
18
- const HIDDEN_BUILTINS_FILE = ".hidden-builtins.json";
19
- // codex-pets.net added `kind` to pet.json long after launch, and its enum may keep
20
- // growing — packages published before that (and future kinds) must stay importable,
21
- // so kind is optional metadata validated only as a short slug.
22
- const KIND_RE = /^[a-z][a-z0-9-]{0,39}$/;
23
- const PET_ID_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
24
- const petDirectoryCache = new Map();
25
- let codexAsarCache = null;
26
-
27
- // Token Usage keeps its own pets under ~/.tokenusage/pets and never writes to the
28
- // Codex app: URL/zip imports stay here, and Codex is only ever read from (reverse
29
- // import). `~/.codex/pets` is reachable purely as an import source.
30
- const MIGRATION_MARKER = ".migrated-v1";
31
-
32
- function resolvePetsDir() {
33
- return path.resolve(
34
- process.env.TOKENUSAGE_PETS_DIR || path.join(os.homedir(), ".tokenusage", "pets"),
35
- );
36
- }
37
-
38
- function resolveCodexPetsDir() {
39
- return path.resolve(
40
- process.env.TOKENUSAGE_CODEX_PETS_DIR || path.join(os.homedir(), ".codex", "pets"),
41
- );
42
- }
43
-
44
- function readHiddenBuiltinIds() {
45
- const file = path.join(resolvePetsDir(), HIDDEN_BUILTINS_FILE);
46
- try {
47
- const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
48
- if (!Array.isArray(parsed)) return [];
49
- return [...new Set(parsed
50
- .map((id) => String(id || "").trim().toLowerCase())
51
- .filter((id) => REMOVABLE_BUILTIN_IDS.has(id)))].sort();
52
- } catch {
53
- return [];
54
- }
55
- }
56
-
57
- function hideBuiltinPet(id) {
58
- const normalized = String(id || "").trim().toLowerCase();
59
- if (normalized === "clawd") throw new Error("Clawd cannot be removed");
60
- if (!REMOVABLE_BUILTIN_IDS.has(normalized)) throw new Error("Invalid built-in pet id");
61
-
62
- const root = resolvePetsDir();
63
- fs.mkdirSync(root, { recursive: true, mode: 0o700 });
64
- const hidden = new Set(readHiddenBuiltinIds());
65
- hidden.add(normalized);
66
- const destination = path.join(root, HIDDEN_BUILTINS_FILE);
67
- const stage = path.join(root, `${HIDDEN_BUILTINS_FILE}.${process.pid}-${crypto.randomBytes(6).toString("hex")}`);
68
- const backup = `${stage}-backup`;
69
- try {
70
- fs.writeFileSync(stage, `${JSON.stringify([...hidden].sort(), null, 2)}\n`, { mode: 0o600 });
71
- if (fs.existsSync(destination)) fs.renameSync(destination, backup);
72
- fs.renameSync(stage, destination);
73
- } catch (error) {
74
- try { fs.rmSync(stage, { force: true }); } catch {}
75
- if (!fs.existsSync(destination) && fs.existsSync(backup)) fs.renameSync(backup, destination);
76
- throw error;
77
- }
78
- try { fs.rmSync(backup, { force: true }); } catch {}
79
- return { id: normalized, hidden: true };
80
- }
81
-
82
- function readUInt24LE(buffer, offset) {
83
- return buffer[offset] | (buffer[offset + 1] << 8) | (buffer[offset + 2] << 16);
84
- }
85
-
86
- function readWebpDimensions(buffer) {
87
- if (
88
- !Buffer.isBuffer(buffer)
89
- || buffer.length < 30
90
- || buffer.subarray(0, 4).toString("ascii") !== "RIFF"
91
- || buffer.subarray(8, 12).toString("ascii") !== "WEBP"
92
- ) {
93
- throw new Error("spritesheet.webp is not a valid WebP file");
94
- }
95
- if (buffer.readUInt32LE(4) + 8 !== buffer.length) {
96
- throw new Error("spritesheet.webp has an invalid RIFF size");
97
- }
98
-
99
- let offset = 12;
100
- while (offset + 8 <= buffer.length) {
101
- const type = buffer.subarray(offset, offset + 4).toString("ascii");
102
- const size = buffer.readUInt32LE(offset + 4);
103
- const data = offset + 8;
104
- if (data + size > buffer.length) throw new Error("spritesheet.webp is truncated");
105
- if (type === "VP8X" && size >= 10) {
106
- return {
107
- width: readUInt24LE(buffer, data + 4) + 1,
108
- height: readUInt24LE(buffer, data + 7) + 1,
109
- };
110
- }
111
- if (type === "VP8 " && size >= 10) {
112
- if (buffer[data + 3] !== 0x9d || buffer[data + 4] !== 0x01 || buffer[data + 5] !== 0x2a) {
113
- throw new Error("spritesheet.webp has an invalid VP8 frame header");
114
- }
115
- return {
116
- width: buffer.readUInt16LE(data + 6) & 0x3fff,
117
- height: buffer.readUInt16LE(data + 8) & 0x3fff,
118
- };
119
- }
120
- if (type === "VP8L" && size >= 5) {
121
- if (buffer[data] !== 0x2f) throw new Error("spritesheet.webp has an invalid VP8L header");
122
- const bits = buffer.readUInt32LE(data + 1);
123
- return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
124
- }
125
- offset = data + size + (size % 2);
126
- }
127
- throw new Error("spritesheet.webp has no decodable image frame");
128
- }
129
-
130
- function normalizeManifest(value) {
131
- if (!value || typeof value !== "object" || Array.isArray(value)) {
132
- throw new Error("pet.json must contain a JSON object");
133
- }
134
- const id = String(value.id || "").trim().toLowerCase();
135
- const displayName = String(value.displayName || "").trim();
136
- const description = String(value.description || "").trim();
137
- const spritesheetPath = String(value.spritesheetPath || "").trim();
138
- const kind = String(value.kind || "").trim().toLowerCase();
139
- const versionProvided = value.spriteVersionNumber !== undefined;
140
- const spriteVersionNumber = versionProvided ? value.spriteVersionNumber : 1;
141
-
142
- if (!PET_ID_RE.test(id)) throw new Error("pet.json id must be a lowercase URL-safe slug");
143
- if (BUILTIN_IDS.has(id)) throw new Error(`${id} is reserved by a built-in Token Usage pet`);
144
- if (!displayName || displayName.length > 80) throw new Error("pet.json displayName is required and must be at most 80 characters");
145
- if (!description || description.length > 280) throw new Error("pet.json description is required and must be at most 280 characters");
146
- if (spritesheetPath !== PET_SPRITESHEET) throw new Error("pet.json spritesheetPath must be spritesheet.webp");
147
- if (kind && !KIND_RE.test(kind)) throw new Error("pet.json kind must be a short lowercase label when provided");
148
- if (versionProvided && spriteVersionNumber !== 2) {
149
- throw new Error("pet.json spriteVersionNumber must be 2 when provided");
150
- }
151
-
152
- return {
153
- id,
154
- displayName,
155
- description,
156
- spritesheetPath: PET_SPRITESHEET,
157
- spriteVersionNumber,
158
- ...(kind ? { kind } : {}),
159
- };
160
- }
161
-
162
- function validatePackageFiles(manifestBuffer, spritesheetBuffer) {
163
- if (!Buffer.isBuffer(manifestBuffer) || manifestBuffer.length === 0 || manifestBuffer.length > MAX_MANIFEST_BYTES) {
164
- throw new Error("pet.json is missing or too large");
165
- }
166
- if (!Buffer.isBuffer(spritesheetBuffer) || spritesheetBuffer.length === 0 || spritesheetBuffer.length > MAX_SPRITESHEET_BYTES) {
167
- throw new Error("spritesheet.webp is missing or too large");
168
- }
169
-
170
- let parsed;
171
- try {
172
- parsed = JSON.parse(manifestBuffer.toString("utf8"));
173
- } catch {
174
- throw new Error("pet.json is not valid JSON");
175
- }
176
- const manifest = normalizeManifest(parsed);
177
- const dimensions = readWebpDimensions(spritesheetBuffer);
178
- const expectedHeight = manifest.spriteVersionNumber === 2 ? 2288 : 1872;
179
- if (dimensions.width !== 1536 || dimensions.height !== expectedHeight) {
180
- throw new Error(
181
- `spritesheet.webp must be 1536x${expectedHeight} for a v${manifest.spriteVersionNumber} pet`,
182
- );
183
- }
184
- return { manifest, dimensions };
185
- }
186
-
187
- function readZipEntries(zipBuffer) {
188
- if (!Buffer.isBuffer(zipBuffer) || zipBuffer.length === 0 || zipBuffer.length > MAX_PACKAGE_BYTES) {
189
- return Promise.reject(new Error("Pet package is empty or exceeds 12 MB"));
190
- }
191
- return new Promise((resolve, reject) => {
192
- yauzl.fromBuffer(zipBuffer, { lazyEntries: true, validateEntrySizes: true }, (openError, zipfile) => {
193
- if (openError) return reject(new Error(`Invalid pet package: ${openError.message}`));
194
- const entries = new Map();
195
- let settled = false;
196
- const fail = (error) => {
197
- if (settled) return;
198
- settled = true;
199
- try { zipfile.close(); } catch {}
200
- reject(error);
201
- };
202
- zipfile.on("error", (error) => fail(new Error(`Invalid pet package: ${error.message}`)));
203
- zipfile.on("entry", (entry) => {
204
- const name = String(entry.fileName || "");
205
- const unixMode = (entry.externalFileAttributes >>> 16) & 0xffff;
206
- if ((unixMode & 0xf000) === 0xa000) {
207
- fail(new Error("Pet package entries must not be symbolic links"));
208
- return;
209
- }
210
- if (name !== PET_MANIFEST && name !== PET_SPRITESHEET) {
211
- fail(new Error("A standard pet package must contain only pet.json and spritesheet.webp at its root"));
212
- return;
213
- }
214
- if (entries.has(name)) {
215
- fail(new Error(`Pet package contains duplicate ${name}`));
216
- return;
217
- }
218
- const limit = name === PET_MANIFEST ? MAX_MANIFEST_BYTES : MAX_SPRITESHEET_BYTES;
219
- if (entry.uncompressedSize <= 0 || entry.uncompressedSize > limit) {
220
- fail(new Error(`${name} is empty or too large`));
221
- return;
222
- }
223
- zipfile.openReadStream(entry, (streamError, stream) => {
224
- if (streamError) return fail(new Error(`Could not read ${name}: ${streamError.message}`));
225
- const chunks = [];
226
- let total = 0;
227
- stream.on("data", (chunk) => {
228
- total += chunk.length;
229
- if (total > limit) {
230
- stream.destroy(new Error(`${name} is too large`));
231
- return;
232
- }
233
- chunks.push(chunk);
234
- });
235
- stream.on("error", (error) => fail(error));
236
- stream.on("end", () => {
237
- if (settled) return;
238
- entries.set(name, Buffer.concat(chunks));
239
- zipfile.readEntry();
240
- });
241
- });
242
- });
243
- zipfile.on("end", () => {
244
- if (settled) return;
245
- settled = true;
246
- if (entries.size !== 2 || !entries.has(PET_MANIFEST) || !entries.has(PET_SPRITESHEET)) {
247
- reject(new Error("Pet package must contain pet.json and spritesheet.webp"));
248
- return;
249
- }
250
- resolve(entries);
251
- });
252
- zipfile.readEntry();
253
- });
254
- });
255
- }
256
-
257
- function publicPet(manifest, extra = {}) {
258
- const assetVersion = extra.assetVersion || "";
259
- return {
260
- ...manifest,
261
- custom: true,
262
- assetUrl: `/api/pets/local/${encodeURIComponent(manifest.id)}/${PET_SPRITESHEET}${assetVersion ? `?v=${encodeURIComponent(assetVersion)}` : ""}`,
263
- ...extra,
264
- };
265
- }
266
-
267
- function loadPetDirectory(directory, expectedId = null) {
268
- const stat = fs.lstatSync(directory);
269
- if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Pet path is not a directory");
270
- const manifestPath = path.join(directory, PET_MANIFEST);
271
- const spritesheetPath = path.join(directory, PET_SPRITESHEET);
272
- const manifestStat = fs.lstatSync(manifestPath);
273
- const spriteStat = fs.lstatSync(spritesheetPath);
274
- if (!manifestStat.isFile() || manifestStat.isSymbolicLink() || !spriteStat.isFile() || spriteStat.isSymbolicLink()) {
275
- throw new Error("Pet assets must be regular files");
276
- }
277
- if (manifestStat.size <= 0 || manifestStat.size > MAX_MANIFEST_BYTES) {
278
- throw new Error("pet.json is missing or too large");
279
- }
280
- if (spriteStat.size <= 0 || spriteStat.size > MAX_SPRITESHEET_BYTES) {
281
- throw new Error("spritesheet.webp is missing or too large");
282
- }
283
- const cacheKey = [
284
- manifestStat.mtimeMs,
285
- manifestStat.size,
286
- spriteStat.mtimeMs,
287
- spriteStat.size,
288
- ].join(":");
289
- const cacheId = directory;
290
- const cached = petDirectoryCache.get(cacheId);
291
- if (cached?.cacheKey === cacheKey) return cached.value;
292
- const result = validatePackageFiles(fs.readFileSync(manifestPath), fs.readFileSync(spritesheetPath));
293
- if (expectedId && result.manifest.id !== expectedId) throw new Error("Pet directory and manifest id do not match");
294
- const value = {
295
- ...result,
296
- directory,
297
- spritesheetPath,
298
- assetVersion: `${Math.trunc(spriteStat.mtimeMs)}-${spriteStat.size}`,
299
- };
300
- petDirectoryCache.set(cacheId, { cacheKey, value });
301
- return value;
302
- }
303
-
304
- /**
305
- * Move third-party packages out of directories whose id we have since reserved.
306
- *
307
- * `bot` became a built-in in 0.93.0. A user who had imported a package with that id
308
- * would otherwise lose it silently: BUILTIN_IDS skips it in every listing, and
309
- * removeInstalledPet routes it to hideBuiltinPet, which rejects a non-removable
310
- * built-in — so the directory became invisible AND undeletable, up to 10 MB of it.
311
- *
312
- * Renaming keeps the package usable instead of just deleting it. Idempotent by
313
- * construction: after the rename the reserved path no longer exists. If the manifest
314
- * rewrite fails mid-way the package is unusable but freely removable, which still
315
- * beats the state above.
316
- */
317
- function reclaimReservedPetDirectories(root) {
318
- for (const reserved of BUILTIN_IDS) {
319
- const source = path.join(root, reserved);
320
- if (!fs.existsSync(path.join(source, PET_MANIFEST))) continue;
321
- let target = `${reserved}-imported`;
322
- for (let suffix = 2; fs.existsSync(path.join(root, target)); suffix += 1) {
323
- target = `${reserved}-imported-${suffix}`;
324
- }
325
- try {
326
- fs.renameSync(source, path.join(root, target));
327
- } catch {
328
- continue;
329
- }
330
- // The manifest id must match the directory name or the package fails to load.
331
- const manifestPath = path.join(root, target, PET_MANIFEST);
332
- try {
333
- const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
334
- manifest.id = target;
335
- fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
336
- } catch {
337
- // Left unusable but removable; nothing else to do here.
338
- }
339
- }
340
- }
341
-
342
- function listInstalledPets() {
343
- migrateLegacyCodexPets();
344
- const root = resolvePetsDir();
345
- reclaimReservedPetDirectories(root);
346
- let names = [];
347
- try { names = fs.readdirSync(root); } catch (error) {
348
- if (error?.code === "ENOENT") return [];
349
- throw error;
350
- }
351
- const pets = [];
352
- for (const name of names) {
353
- if (!PET_ID_RE.test(name) || BUILTIN_IDS.has(name)) continue;
354
- try {
355
- const loaded = loadPetDirectory(path.join(root, name), name);
356
- pets.push(publicPet(loaded.manifest, { assetVersion: loaded.assetVersion }));
357
- } catch {
358
- // Invalid or partially copied directories are ignored until they become valid.
359
- }
360
- }
361
- return pets.sort((a, b) => a.displayName.localeCompare(b.displayName));
362
- }
363
-
364
- // Atomically writes one validated pet into `root` (staged dir → rename), optionally
365
- // dropping `markerName` inside the pet directory. Returns the loaded asset info.
366
- function writePetIntoDir(root, manifest, spritesheetBuffer, markerName = null) {
367
- fs.mkdirSync(root, { recursive: true, mode: 0o700 });
368
- const stage = path.join(root, `.tokenusage-pet-${process.pid}-${crypto.randomBytes(6).toString("hex")}`);
369
- const destination = path.join(root, manifest.id);
370
- const backup = `${stage}-backup`;
371
- fs.mkdirSync(stage, { mode: 0o700 });
372
- try {
373
- fs.writeFileSync(path.join(stage, PET_MANIFEST), `${JSON.stringify({
374
- id: manifest.id,
375
- displayName: manifest.displayName,
376
- description: manifest.description,
377
- spritesheetPath: PET_SPRITESHEET,
378
- ...(manifest.spriteVersionNumber === 2 ? { spriteVersionNumber: 2 } : {}),
379
- kind: manifest.kind,
380
- }, null, 2)}\n`, { mode: 0o600 });
381
- fs.writeFileSync(path.join(stage, PET_SPRITESHEET), spritesheetBuffer, { mode: 0o600 });
382
- if (markerName) fs.writeFileSync(path.join(stage, markerName), "", { mode: 0o600 });
383
- loadPetDirectory(stage, manifest.id);
384
- petDirectoryCache.delete(destination);
385
- if (fs.existsSync(destination)) fs.renameSync(destination, backup);
386
- fs.renameSync(stage, destination);
387
- petDirectoryCache.delete(stage);
388
- } catch (error) {
389
- petDirectoryCache.delete(stage);
390
- fs.rmSync(stage, { recursive: true, force: true });
391
- if (!fs.existsSync(destination) && fs.existsSync(backup)) fs.renameSync(backup, destination);
392
- throw error;
393
- }
394
- try { fs.rmSync(backup, { recursive: true, force: true }); } catch {}
395
- return loadPetDirectory(destination, manifest.id);
396
- }
397
-
398
- function installValidatedPackage(manifestBuffer, spritesheetBuffer) {
399
- const { manifest } = validatePackageFiles(manifestBuffer, spritesheetBuffer);
400
- const installed = writePetIntoDir(resolvePetsDir(), manifest, spritesheetBuffer);
401
- return publicPet(manifest, { assetVersion: installed.assetVersion });
402
- }
403
-
404
- async function importPetZip(zipBuffer) {
405
- const entries = await readZipEntries(zipBuffer);
406
- return installValidatedPackage(entries.get(PET_MANIFEST), entries.get(PET_SPRITESHEET));
407
- }
408
-
409
- function petIdFromCodexPetsUrl(input) {
410
- const raw = String(input || "").trim();
411
- if (PET_ID_RE.test(raw)) return raw;
412
- let parsed;
413
- try { parsed = new URL(raw); } catch { throw new Error("Enter a Codex Pets URL or pet id"); }
414
- if (parsed.protocol !== "https:" || parsed.hostname !== "codex-pets.net") {
415
- throw new Error("Only https://codex-pets.net pet URLs are supported");
416
- }
417
- const hashMatch = parsed.hash.match(/^#\/pets\/([a-z0-9-]+)\/?$/i);
418
- const pathMatch = parsed.pathname.match(/^\/api\/pets\/([a-z0-9-]+)(?:\/download)?\/?$/i);
419
- const id = String(hashMatch?.[1] || pathMatch?.[1] || "").toLowerCase();
420
- if (!PET_ID_RE.test(id)) throw new Error("The Codex Pets URL does not contain a valid pet id");
421
- return id;
422
- }
423
-
424
- async function installFromCodexPets(input, fetchImpl = fetch) {
425
- const id = petIdFromCodexPetsUrl(input);
426
- const controller = new AbortController();
427
- const timeout = setTimeout(() => controller.abort(), 30_000);
428
- timeout.unref?.();
429
- try {
430
- const response = await fetchImpl(`https://codex-pets.net/api/pets/${encodeURIComponent(id)}/download`, {
431
- redirect: "follow",
432
- signal: controller.signal,
433
- headers: { accept: "application/zip", "user-agent": "tokenusage-cli Pet Importer" },
434
- });
435
- if (!response.ok) throw new Error(`Codex Pets download failed with HTTP ${response.status}`);
436
- const length = Number(response.headers.get("content-length") || 0);
437
- if (length > MAX_PACKAGE_BYTES) throw new Error("Pet package exceeds 12 MB");
438
- const chunks = [];
439
- let total = 0;
440
- for await (const chunk of response.body || []) {
441
- total += chunk.length;
442
- if (total > MAX_PACKAGE_BYTES) throw new Error("Pet package exceeds 12 MB");
443
- chunks.push(Buffer.from(chunk));
444
- }
445
- const body = Buffer.concat(chunks);
446
- return await importPetZip(body);
447
- } finally {
448
- clearTimeout(timeout);
449
- }
450
- }
451
-
452
- function removeInstalledPet(id) {
453
- const normalized = String(id || "").trim().toLowerCase();
454
- if (!PET_ID_RE.test(normalized)) throw new Error("Invalid pet id");
455
- if (BUILTIN_IDS.has(normalized)) return hideBuiltinPet(normalized);
456
- const root = resolvePetsDir();
457
- const destination = path.join(root, normalized);
458
- if (!destination.startsWith(`${root}${path.sep}`)) throw new Error("Invalid pet path");
459
- fs.rmSync(destination, { recursive: true, force: true });
460
- petDirectoryCache.delete(destination);
461
- return { id: normalized };
462
- }
463
-
464
- function resolvePetAsset(id) {
465
- // Native hosts can ask for the persisted custom pet before the dashboard has
466
- // listed the catalog. Migrate first so an upgrade does not turn that first
467
- // request into a 404 and reset the user's selection.
468
- migrateLegacyCodexPets();
469
- const normalized = String(id || "").trim().toLowerCase();
470
- if (!PET_ID_RE.test(normalized) || BUILTIN_IDS.has(normalized)) return null;
471
- try { return loadPetDirectory(path.join(resolvePetsDir(), normalized), normalized); } catch { return null; }
472
- }
473
-
474
- // --- One-time migration: copy legacy pets out of the shared Codex dir into our own ---
475
-
476
- function migrateLegacyCodexPets() {
477
- const root = resolvePetsDir();
478
- const marker = path.join(root, MIGRATION_MARKER);
479
- try { if (fs.existsSync(marker)) return { migrated: 0 }; } catch { return { migrated: 0 }; }
480
- try { fs.mkdirSync(root, { recursive: true, mode: 0o700 }); } catch { return { migrated: 0 }; }
481
- let migrated = 0;
482
- let names = [];
483
- let scanComplete = false;
484
- try {
485
- names = fs.readdirSync(resolveCodexPetsDir());
486
- scanComplete = true;
487
- } catch (error) {
488
- // A missing legacy directory is a completed no-op. Permission and I/O
489
- // failures are not: leave the marker absent so the next launch can retry.
490
- if (error?.code === "ENOENT") scanComplete = true;
491
- }
492
- let copyFailed = false;
493
- for (const name of names) {
494
- if (!PET_ID_RE.test(name) || BUILTIN_IDS.has(name)) continue;
495
- if (fs.existsSync(path.join(root, name))) continue; // never clobber an existing local pet
496
- let loaded;
497
- try {
498
- loaded = loadPetDirectory(path.join(resolveCodexPetsDir(), name), name);
499
- } catch {
500
- // Invalid legacy packages are ignored just as they were by the old catalog.
501
- continue;
502
- }
503
- try {
504
- writePetIntoDir(root, loaded.manifest, fs.readFileSync(loaded.spritesheetPath));
505
- migrated += 1;
506
- } catch {
507
- copyFailed = true;
508
- }
509
- }
510
- if (scanComplete && !copyFailed) {
511
- try { fs.writeFileSync(marker, `${new Date().toISOString()}\n`, { mode: 0o600 }); } catch {}
512
- }
513
- return { migrated };
514
- }
515
-
516
- // --- Reverse import: pull Codex's own pets into Token Usage ---
517
-
518
- // Resolved per call (not frozen at load) so an env override applies at runtime.
519
- function resolveCodexAsarPath() {
520
- return process.env.TOKENUSAGE_CODEX_ASAR
521
- || "/Applications/Codex.app/Contents/Resources/app.asar";
522
- }
523
- // Codex ships these native companions bundled inside its app; the display names are
524
- // stable brand labels. Anything not listed falls back to a capitalized id.
525
- const CODEX_BUILTIN_NAMES = {
526
- rocky: "Rocky", seedy: "Seedy", hoots: "Hoots", dewey: "Dewey", fireball: "Fireball",
527
- stacky: "Stacky", codex: "Codex", bsod: "BSOD", "null-signal": "Null Signal",
528
- };
529
-
530
- // Parses the asar header (Chromium Pickle) and returns the file tree plus the byte
531
- // offset where file contents begin. Pure Node, no dependency — asar's layout is stable.
532
- function readAsarHeader(fd) {
533
- const head = Buffer.alloc(16);
534
- if (fs.readSync(fd, head, 0, 16, 0) < 16) throw new Error("asar too small");
535
- const headerPayloadSize = head.readUInt32LE(4);
536
- const jsonStrLen = head.readUInt32LE(12);
537
- if (jsonStrLen <= 0 || jsonStrLen > 64 * 1024 * 1024) throw new Error("asar header size out of range");
538
- const jsonBuf = Buffer.alloc(jsonStrLen);
539
- fs.readSync(fd, jsonBuf, 0, jsonStrLen, 16);
540
- const header = JSON.parse(jsonBuf.toString("utf8"));
541
- const base = 8 + headerPayloadSize;
542
- return { header, baseOffset: base % 4 ? base + 4 - (base % 4) : base };
543
- }
544
-
545
- // Reads Codex's bundled companion spritesheets out of the app's asar. Returns
546
- // [{ id, displayName, description, spriteVersionNumber, buffer }]. Degrades to [] if
547
- // Codex isn't installed or the bundle can't be read.
548
- function readCodexBuiltinPets(asarPath = resolveCodexAsarPath()) {
549
- const resolvedAsarPath = path.resolve(asarPath);
550
- let asarStat;
551
- try { asarStat = fs.statSync(resolvedAsarPath); } catch { return []; }
552
- const cacheKey = `${resolvedAsarPath}:${asarStat.mtimeMs}:${asarStat.size}`;
553
- if (codexAsarCache?.key === cacheKey) return codexAsarCache.pets;
554
-
555
- let fd;
556
- try { fd = fs.openSync(resolvedAsarPath, "r"); } catch { return []; }
557
- try {
558
- const { header, baseOffset } = readAsarHeader(fd);
559
- const entries = [];
560
- (function walk(node) {
561
- for (const [name, value] of Object.entries(node?.files || {})) {
562
- if (value?.files) walk(value);
563
- else if (/-spritesheet-.*\.webp$/i.test(name) && value?.offset != null) entries.push([name, value]);
564
- }
565
- })(header);
566
- const byId = new Map();
567
- for (const [name, entry] of entries) {
568
- const id = name.replace(/-spritesheet-.*$/i, "").toLowerCase();
569
- if (!PET_ID_RE.test(id) || BUILTIN_IDS.has(id) || byId.has(id)) continue;
570
- const size = Number(entry.size);
571
- if (!(size > 0) || size > MAX_SPRITESHEET_BYTES) continue;
572
- const buffer = Buffer.alloc(size);
573
- fs.readSync(fd, buffer, 0, size, baseOffset + Number(entry.offset));
574
- let dimensions;
575
- try { dimensions = readWebpDimensions(buffer); } catch { continue; }
576
- const spriteVersionNumber = dimensions.width === 1536 && dimensions.height === 2288 ? 2
577
- : dimensions.width === 1536 && dimensions.height === 1872 ? 1 : 0;
578
- if (!spriteVersionNumber) continue;
579
- byId.set(id, {
580
- id,
581
- displayName: CODEX_BUILTIN_NAMES[id] || (id.charAt(0).toUpperCase() + id.slice(1)),
582
- description: "Built-in Codex companion.",
583
- spriteVersionNumber,
584
- buffer,
585
- });
586
- }
587
- const pets = [...byId.values()];
588
- codexAsarCache = { key: cacheKey, pets };
589
- return pets;
590
- } catch {
591
- codexAsarCache = { key: cacheKey, pets: [] };
592
- return [];
593
- }
594
- finally { try { fs.closeSync(fd); } catch {} }
595
- }
596
-
597
- // Preview URL for an importable Codex pet (served before it lands in our own dir).
598
- function codexAssetUrl(id, version) {
599
- return `/api/pets/codex/${encodeURIComponent(id)}/${PET_SPRITESHEET}${version ? `?v=${encodeURIComponent(version)}` : ""}`;
600
- }
601
-
602
- // Lists Codex pets that could be imported but aren't in Token Usage yet: valid
603
- // packages in ~/.codex/pets plus Codex's app-bundled companions. Each carries an
604
- // assetUrl so the picker can preview sprites.
605
- function listCodexImportablePets() {
606
- const alreadyHere = new Set(listInstalledPets().map((pet) => pet.id));
607
- const result = new Map();
608
- const codexRoot = resolveCodexPetsDir();
609
- let names = [];
610
- try { names = fs.readdirSync(codexRoot); } catch { names = []; }
611
- for (const name of names) {
612
- if (!PET_ID_RE.test(name) || BUILTIN_IDS.has(name) || alreadyHere.has(name)) continue;
613
- try {
614
- const loaded = loadPetDirectory(path.join(codexRoot, name), name);
615
- result.set(name, {
616
- ...loaded.manifest,
617
- custom: true,
618
- assetUrl: codexAssetUrl(name, loaded.assetVersion),
619
- assetVersion: loaded.assetVersion,
620
- source: "codex-dir",
621
- });
622
- } catch {}
623
- }
624
- for (const pet of readCodexBuiltinPets()) {
625
- if (alreadyHere.has(pet.id) || result.has(pet.id)) continue;
626
- result.set(pet.id, {
627
- id: pet.id,
628
- displayName: pet.displayName,
629
- description: pet.description,
630
- spritesheetPath: PET_SPRITESHEET,
631
- spriteVersionNumber: pet.spriteVersionNumber,
632
- custom: true,
633
- assetUrl: codexAssetUrl(pet.id, `app${pet.spriteVersionNumber}`),
634
- source: "codex-app",
635
- });
636
- }
637
- return [...result.values()].sort((a, b) => a.displayName.localeCompare(b.displayName));
638
- }
639
-
640
- // Returns { buffer, contentLength } for an importable Codex pet's spritesheet — from
641
- // ~/.codex/pets first, then the app bundle. Powers the picker preview route.
642
- function readCodexImportableAsset(id) {
643
- const normalized = String(id || "").trim().toLowerCase();
644
- if (!PET_ID_RE.test(normalized) || BUILTIN_IDS.has(normalized)) return null;
645
- const codexDir = path.join(resolveCodexPetsDir(), normalized);
646
- try {
647
- const loaded = loadPetDirectory(codexDir, normalized);
648
- return { buffer: fs.readFileSync(loaded.spritesheetPath) };
649
- } catch {}
650
- for (const pet of readCodexBuiltinPets()) {
651
- if (pet.id === normalized) return { buffer: pet.buffer };
652
- }
653
- return null;
654
- }
655
-
656
- function importFromCodex(ids) {
657
- const requested = new Set(
658
- (Array.isArray(ids) ? ids : [])
659
- .map((id) => String(id || "").trim().toLowerCase())
660
- .filter((id) => PET_ID_RE.test(id) && !BUILTIN_IDS.has(id)),
661
- );
662
- if (requested.size === 0) throw new Error("No valid Codex pet ids to import");
663
- const root = resolvePetsDir();
664
- // The listing excludes already-installed ids, but enforce the same rule at
665
- // the write boundary so a handcrafted local API request cannot overwrite a
666
- // Token Usage-owned pet with Codex's copy.
667
- for (const id of [...requested]) {
668
- if (fs.existsSync(path.join(root, id))) requested.delete(id);
669
- }
670
- if (requested.size === 0) throw new Error("Requested Codex pets are already installed");
671
- const codexRoot = resolveCodexPetsDir();
672
- const imported = [];
673
- for (const id of [...requested]) {
674
- try {
675
- const loaded = loadPetDirectory(path.join(codexRoot, id), id);
676
- const installed = writePetIntoDir(root, loaded.manifest, fs.readFileSync(loaded.spritesheetPath));
677
- imported.push(publicPet(loaded.manifest, { assetVersion: installed.assetVersion }));
678
- requested.delete(id);
679
- } catch {}
680
- }
681
- if (requested.size > 0) {
682
- for (const pet of readCodexBuiltinPets()) {
683
- if (!requested.has(pet.id)) continue;
684
- const manifest = normalizeManifest({
685
- id: pet.id,
686
- displayName: pet.displayName,
687
- description: pet.description,
688
- spritesheetPath: PET_SPRITESHEET,
689
- ...(pet.spriteVersionNumber === 2 ? { spriteVersionNumber: 2 } : {}),
690
- });
691
- try {
692
- const installed = writePetIntoDir(root, manifest, pet.buffer);
693
- imported.push(publicPet(manifest, { assetVersion: installed.assetVersion }));
694
- requested.delete(pet.id);
695
- } catch {}
696
- }
697
- }
698
- if (imported.length === 0) throw new Error("None of the requested Codex pets could be imported");
699
- return { imported };
700
- }
701
-
702
- module.exports = {
703
- MAX_PACKAGE_BYTES,
704
- importFromCodex,
705
- importPetZip,
706
- installFromCodexPets,
707
- listCodexImportablePets,
708
- listInstalledPets,
709
- migrateLegacyCodexPets,
710
- normalizeManifest,
711
- petIdFromCodexPetsUrl,
712
- readCodexBuiltinPets,
713
- readCodexImportableAsset,
714
- readHiddenBuiltinIds,
715
- readWebpDimensions,
716
- reclaimReservedPetDirectories,
717
- removeInstalledPet,
718
- resolveCodexPetsDir,
719
- resolvePetAsset,
720
- resolvePetsDir,
721
- validatePackageFiles,
722
- };