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
@@ -169,6 +169,8 @@ const {
169
169
  } = require("../lib/upload-throttle");
170
170
  const { compactPendingQueue, iterateQueueLines, sessionSnapshotMs } = require("../lib/upload-queue");
171
171
  const { sanitizeBucketForUpload } = require("../lib/ingest-sanitize");
172
+ const { normalizeQueueRow } = require("../lib/queue-row-normalize");
173
+ const { UsageError, unknownOptionError } = require("../lib/cli-errors");
172
174
  const AUTO_UPLOAD_CONFIG = {
173
175
  intervalMs: 15 * 60_000,
174
176
  batchSize: 200,
@@ -450,8 +452,10 @@ function sleep(ms) {
450
452
  // run owns a real terminal; piped hook consumers (stdio ignored) stay quiet.
451
453
  // Auto-flavored runs ALSO append to the rolling <trackerDir>/logs/sync.log
452
454
  // (0.2.0): the scheduled task registration no longer depends on a `>>`
453
- // redirect, and TTY-less runs keep a durable trail. Rotation keeps one
454
- // 1 MiB generation (sync.log.1) plus the live file.
455
+ // redirect, and TTY-less runs keep a durable trail. The file is JSONL
456
+ // (`{ts,msg,...fields}` one per line) so a support request can be diffed, grepped
457
+ // by field or fed to a log viewer; the TTY line stays human-readable. Rotation
458
+ // keeps one 1 MiB generation (sync.log.1) plus the live file.
455
459
  const AUTO_LOG_MAX_BYTES = 1_048_576;
456
460
  let autoLogSinkPath = null;
457
461
 
@@ -459,10 +463,11 @@ function setAutoLogSink(filePath) {
459
463
  autoLogSinkPath = filePath;
460
464
  }
461
465
 
462
- function autoLog(message) {
463
- const stamp = new Date().toISOString().replace("T", " ").slice(0, 19);
464
- const line = `[${stamp}] ${message}\n`;
465
- if (process.stdout.isTTY) process.stdout.write(line);
466
+ function autoLog(message, fields = null) {
467
+ const stamp = new Date().toISOString();
468
+ if (process.stdout.isTTY) {
469
+ process.stdout.write(`[${stamp.replace("T", " ").slice(0, 19)}] ${message}\n`);
470
+ }
466
471
  if (autoLogSinkPath) {
467
472
  try {
468
473
  try {
@@ -472,7 +477,8 @@ function autoLog(message) {
472
477
  }
473
478
  } catch { /* no live file yet */ }
474
479
  fssync.mkdirSync(path.dirname(autoLogSinkPath), { recursive: true });
475
- fssync.appendFileSync(autoLogSinkPath, line);
480
+ const record = { ts: stamp, msg: message, ...(fields || {}) };
481
+ fssync.appendFileSync(autoLogSinkPath, `${JSON.stringify(record)}\n`);
476
482
  } catch { /* logging must never break a sync */ }
477
483
  }
478
484
  }
@@ -3781,7 +3787,11 @@ async function cmdSync(argv, context = {}) {
3781
3787
  if (!opts.auto) {
3782
3788
  process.stderr.write(`Upload error: ${e?.message || e}\n`);
3783
3789
  } else {
3784
- autoLog(`Upload error: ${e?.message || e}`);
3790
+ autoLog(`Upload error: ${e?.message || e}`, {
3791
+ phase: "upload",
3792
+ error: String(e?.message || e),
3793
+ status: Number.isInteger(e?.status) ? e.status : null,
3794
+ });
3785
3795
  }
3786
3796
  // `sync --drain` is the readiness boundary for first-time cloud view:
3787
3797
  // callers must not treat a swallowed upload failure as a completed
@@ -3795,7 +3805,7 @@ async function cmdSync(argv, context = {}) {
3795
3805
  // semantics). A failed upload reports the run as partial — data stays
3796
3806
  // queued locally for the next pass.
3797
3807
  if (syncRun && uploadAttempted) {
3798
- syncRun.noteUpload({ inserted: uploadResult.inserted, tokens: uploadResult.tokens || 0 });
3808
+ syncRun.noteUpload({ inserted: uploadResult.inserted, tokens: uploadResult.tokens || 0, credits: uploadResult.credits || 0 });
3799
3809
  if (uploadError) syncRun.setOutcome({ result: "partial", errorCode: "upload_failed" });
3800
3810
  }
3801
3811
 
@@ -3845,6 +3855,11 @@ async function cmdSync(argv, context = {}) {
3845
3855
  `Session upload error (hourly buckets are unaffected): ${
3846
3856
  sessionError?.message || sessionError
3847
3857
  }`,
3858
+ {
3859
+ phase: "session-upload",
3860
+ error: String(sessionError?.message || sessionError),
3861
+ status: Number.isInteger(sessionError?.status) ? sessionError.status : null,
3862
+ },
3848
3863
  );
3849
3864
  }
3850
3865
  if (opts.drain) throw sessionError;
@@ -3908,6 +3923,15 @@ async function cmdSync(argv, context = {}) {
3908
3923
  ? `uploaded ${uploadResult.inserted}, skipped ${uploadResult.skipped}` +
3909
3924
  (pendingBytes > 0 ? `, pending ${formatBytes(pendingBytes)}` : ", queue drained")
3910
3925
  : "upload skipped (no device token)"),
3926
+ {
3927
+ phase: "finished",
3928
+ parsed_files: totalParsed,
3929
+ buckets: totalBuckets,
3930
+ inserted: uploadResult.inserted,
3931
+ skipped: uploadResult.skipped,
3932
+ pending_bytes: pendingBytes,
3933
+ uploaded: Boolean(runtime.deviceToken),
3934
+ },
3911
3935
  );
3912
3936
  }
3913
3937
 
@@ -3964,17 +3988,17 @@ function parseArgs(argv) {
3964
3988
  else if (a === "--from-openclaw") out.fromOpenclaw = true;
3965
3989
  else if (a === "--from-scheduled") out.fromScheduled = true;
3966
3990
  else if (a === "--source") {
3967
- out.source = normalizeSyncSource(argv[i + 1]);
3991
+ out.source = parseSyncSourceArg(argv[i + 1], "--source");
3968
3992
  i += 1;
3969
3993
  }
3970
- else if (a.startsWith("--source=")) out.source = normalizeSyncSource(a.slice("--source=".length));
3994
+ else if (a.startsWith("--source=")) out.source = parseSyncSourceArg(a.slice("--source=".length), "--source=");
3971
3995
  else if (a === "--drain") out.drain = true;
3972
3996
  else if (a === "--wait-for-lock") out.waitForLock = true;
3973
3997
  else if (a === "--background" || a === "--lightweight") out.background = true;
3974
3998
  else if (a === "--publish-account") out.publishAccount = true;
3975
3999
  else if (a === "--all-local-sources") out.allLocalSources = true;
3976
4000
  else if (a === "--repair-grok") out.repairGrok = true;
3977
- else throw new Error(`Unknown option: ${a}`);
4001
+ else throw unknownOptionError(a, "sync");
3978
4002
  }
3979
4003
  return out;
3980
4004
  }
@@ -3995,6 +4019,33 @@ function normalizeSyncSource(value) {
3995
4019
  return AUTO_SYNC_SOURCES.has(aliased) ? aliased : null;
3996
4020
  }
3997
4021
 
4022
+ // Help/list text for `--source`, generated from the registries above so the
4023
+ // documented ids cannot drift from what sync actually scans.
4024
+ function formatSyncSourceList() {
4025
+ return Array.from(AUTO_SYNC_SOURCES).sort().join(", ");
4026
+ }
4027
+
4028
+ // CLI-facing `--source`: a typo used to fall back to null, which quietly
4029
+ // degraded to a full 46-source scan — the opposite of "only scan this one".
4030
+ // Failing loudly is the only safe behavior; the error lists valid ids.
4031
+ function parseSyncSourceArg(value, flag = "--source") {
4032
+ const raw = typeof value === "string" ? value.trim() : "";
4033
+ if (!raw) {
4034
+ throw new UsageError(`${flag} requires a provider id`, {
4035
+ code: "SOURCE_MISSING",
4036
+ hint: `Available ids: ${formatSyncSourceList()}`,
4037
+ });
4038
+ }
4039
+ const resolved = normalizeSyncSource(raw);
4040
+ if (!resolved) {
4041
+ throw new UsageError(`Unknown --source value: ${raw}`, {
4042
+ code: "SOURCE_UNKNOWN",
4043
+ hint: `Available ids: ${formatSyncSourceList()}`,
4044
+ });
4045
+ }
4046
+ return resolved;
4047
+ }
4048
+
3998
4049
  function isCodexColdScanAuditDue(
3999
4050
  cursors,
4000
4051
  nowMs = Date.now(),
@@ -4058,6 +4109,9 @@ module.exports = {
4058
4109
  acquireSyncLock,
4059
4110
  readQueueBatch,
4060
4111
  drainQueueToCloud,
4112
+ normalizeSyncSource,
4113
+ parseSyncSourceArg,
4114
+ formatSyncSourceList,
4061
4115
  zcodeRowTotals,
4062
4116
  buildZcodeRestorationRow,
4063
4117
  migrateCursorUnknownBuckets,
@@ -4596,12 +4650,13 @@ async function drainQueueToCloud({ baseUrl, anonKey, deviceToken, queuePath, que
4596
4650
  let skipped = 0;
4597
4651
  let batches = 0;
4598
4652
  let tokensIngested = 0;
4653
+ let creditsIngested = 0;
4599
4654
  let cloudAccess = null;
4600
4655
  const uploadId = crypto.randomUUID();
4601
4656
  const deadline = Date.now() + maxDurationMs;
4602
4657
  let batchBudget = Math.min(maxBatches, 100);
4603
4658
  let requestSignal = null;
4604
- const resultSoFar = () => ({ inserted, skipped, batches, tokens: tokensIngested, ...(cloudAccess?.next_allowed_at ? { cloudAccess } : {}) });
4659
+ const resultSoFar = () => ({ inserted, skipped, batches, tokens: tokensIngested, credits: creditsIngested, ...(cloudAccess?.next_allowed_at ? { cloudAccess } : {}) });
4605
4660
 
4606
4661
  const queueSize = await safeStatSize(queuePath);
4607
4662
  const limit = Math.min(Math.max(1, Math.floor(Number(batchSize || 200))), MAX_INGEST_BUCKETS);
@@ -4672,9 +4727,13 @@ async function drainQueueToCloud({ baseUrl, anonKey, deviceToken, queuePath, que
4672
4727
  skipped += Number(data?.skipped || 0);
4673
4728
  // Client-side §2.11 telemetry: the total_tokens of the buckets this
4674
4729
  // request carried (a larger replay may last-wins-override them later;
4675
- // this figure never participates in reconciliation).
4730
+ // this figure never participates in reconciliation). Credits sum the
4731
+ // same way — the display-only dimension (docs/sources-capture-audit.md
4732
+ // §2) — rounded to 6 decimals to keep float noise out of the ledger.
4676
4733
  for (const bucketRow of result.buckets) {
4677
4734
  tokensIngested += Number(bucketRow?.total_tokens) || 0;
4735
+ creditsIngested =
4736
+ Math.round((creditsIngested + (Number(bucketRow?.credits) || 0)) * 1e6) / 1e6;
4678
4737
  }
4679
4738
  batches += 1;
4680
4739
 
@@ -4792,12 +4851,12 @@ async function readQueueBatch(queuePath, startOffset, maxBuckets) {
4792
4851
  const model = (typeof bucket?.model === "string" ? bucket.model.trim() : "") || "unknown";
4793
4852
  bucket.source = source;
4794
4853
  bucket.model = model;
4795
- // Apply the same legacy-row corrections every local reader applies
4796
- // (local-api readQueueData / project queue / wrapped aggregator). Without
4854
+ // Apply the same legacy-row corrections every local reader applies (the
4855
+ // project queue and the wrapped aggregator use this module too). Without
4797
4856
  // this the cloud permanently kept the RAW legacy values — e.g. old Codex
4798
4857
  // rows whose input_tokens still include cached tokens (6-7x inflated) —
4799
- // while the local dashboard showed corrected numbers.
4800
- bucket = require("../lib/local-api").normalizeQueueRow(bucket);
4858
+ // while local readers showed corrected numbers.
4859
+ bucket = normalizeQueueRow(bucket);
4801
4860
  // Contract-shape coercion, poison-row drop (see lib/ingest-sanitize.js):
4802
4861
  // a fractional Grok counter or a negative OpenCode repair delta would
4803
4862
  // otherwise 400 the whole ingest batch and stall the queue.
@@ -29,7 +29,7 @@ const { removeOpenclawSessionPluginConfig } = require("../lib/openclaw-session-p
29
29
  const { removeGrokHook } = require("../lib/grok-hook");
30
30
  const { removeOmpHook } = require("../lib/omp-hook");
31
31
  const { resolveTrackerPaths } = require("../lib/tracker-paths");
32
- const { deleteWindowsScheduledTask, TASK_NAME } = require("../lib/scheduled-task");
32
+ const { deleteAutoSyncSchedule, formatScheduleDelete } = require("../lib/scheduled-task");
33
33
 
34
34
  async function cmdUninstall(argv) {
35
35
  const opts = parseArgs(argv);
@@ -137,11 +137,10 @@ async function cmdUninstall(argv) {
137
137
  // Remove installed notify handler.
138
138
  await fs.unlink(notifyPath).catch(() => {});
139
139
 
140
- // Remove the hidden-runner wrapper and the hourly scheduled task init
141
- // registered (0.2.0). Both best-effort: a machine that never registered
142
- // them simply reports no change.
143
- await fs.unlink(path.join(binDir, "run-sync-hidden.vbs")).catch(() => {});
144
- const taskDelete = deleteWindowsScheduledTask();
140
+ // Remove the generated hidden runner (VBS on Windows, /bin/sh launcher on
141
+ // macOS/Linux) and the registered hourly schedule init created (0.2.0).
142
+ // Both best-effort: a machine that never registered them reports no change.
143
+ const scheduleDelete = deleteAutoSyncSchedule({ home, binDir });
145
144
 
146
145
  // Remove local app runtime (installed by init for notify-driven sync) and any
147
146
  // staging directory left behind by an interrupted runtime copy.
@@ -249,9 +248,7 @@ async function cmdUninstall(argv) {
249
248
  ? `- Grok Build hook removed: ${grokHookRemove.hookPath}`
250
249
  : "- Grok Build hook: no change",
251
250
  formatOmpHookRemoveLine(ompHookRemove),
252
- taskDelete.deleted
253
- ? `- Scheduled task deleted: ${TASK_NAME}`
254
- : "- Scheduled task: none",
251
+ formatScheduleDelete(scheduleDelete),
255
252
  opts.purge ? `- Purged: ${path.join(home, ".tokenusage")}` : "- Purge: skipped (use --purge)",
256
253
  ...(machineIdSeedKept
257
254
  ? [`- Kept: ${machineIdSeedPath} (cloud device identity — a reinstall reuses the same device; delete it to fully reset)`]
@@ -0,0 +1,147 @@
1
+ "use strict";
2
+
3
+ // `tokenusage upload` — flush the local queue without scanning providers.
4
+ //
5
+ // Before this command the only way to push a backlog was `tokenusage sync`,
6
+ // which walks all 46 sources first (slow, and it re-parses session files for
7
+ // no reason when the data is already queued). `upload` reuses the exact same
8
+ // drain path as sync (`drainQueueToCloud`) under the same sync.lock, so the
9
+ // queue offset / throttle / last-wins semantics stay identical — it simply
10
+ // skips the scan phase.
11
+ //
12
+ // `--drain` (alias `--force`) raises the batch ceiling from 5 to 100 and
13
+ // ignores the local upload cooldown, matching `sync --drain`. Manual runs
14
+ // always ignore the cooldown (server access is still decided server-side).
15
+
16
+ const os = require("node:os");
17
+ const path = require("node:path");
18
+ const fs = require("node:fs/promises");
19
+
20
+ const { resolveTrackerPaths } = require("../lib/tracker-paths");
21
+ const { readJson } = require("../lib/fs");
22
+ const { cloudUsageResetBlocksUpload } = require("../lib/cloud-usage-reset");
23
+ const { compactPendingQueue } = require("../lib/upload-queue");
24
+ const { resolveRuntimeConfig } = require("../lib/runtime-config");
25
+ const { UsageError, unknownOptionError } = require("../lib/cli-errors");
26
+ const { acquireSyncLock, drainQueueToCloud } = require("./sync");
27
+
28
+ const BATCH_SIZE = 200;
29
+ const MAX_BATCHES = 5;
30
+ const MAX_BATCHES_DRAIN = 100;
31
+
32
+ function parseArgs(argv) {
33
+ const out = { drain: false, json: false };
34
+ for (let i = 0; i < argv.length; i++) {
35
+ const a = argv[i];
36
+ if (a === "--drain" || a === "--force") out.drain = true;
37
+ else if (a === "--json") out.json = true;
38
+ else throw unknownOptionError(a, "upload");
39
+ }
40
+ return out;
41
+ }
42
+
43
+ async function pendingBytes(queuePath, queueStatePath) {
44
+ const [size, state] = await Promise.all([
45
+ fs.stat(queuePath).then((st) => st.size).catch(() => 0),
46
+ readJson(queueStatePath),
47
+ ]);
48
+ return Math.max(0, size - Number(state?.offset || 0));
49
+ }
50
+
51
+ async function cmdUpload(argv, options = {}) {
52
+ const opts = parseArgs(argv);
53
+ const home = options.home || os.homedir();
54
+ const { trackerDir } = await resolveTrackerPaths({ home });
55
+ const configPath = path.join(trackerDir, "config.json");
56
+ const queuePath = path.join(trackerDir, "queue.jsonl");
57
+ const queueStatePath = path.join(trackerDir, "queue.state.json");
58
+ const lockPath = path.join(trackerDir, "sync.lock");
59
+
60
+ const config = (await readJson(configPath)) || {};
61
+ const runtime = resolveRuntimeConfig({ config, env: process.env });
62
+ if (!runtime.deviceToken) {
63
+ throw new UsageError("This machine is not paired with a dashboard yet.", {
64
+ code: "NO_DEVICE_TOKEN",
65
+ hint: "Run `tokenusage device-login` (or `tokenusage init`) first.",
66
+ });
67
+ }
68
+
69
+ const canUpload = () => !cloudUsageResetBlocksUpload(trackerDir, {
70
+ ownerId: process.env.TOKENUSAGE_CLOUD_OWNER_ID,
71
+ baseUrl: process.env.TOKENUSAGE_INSFORGE_BASE_URL,
72
+ deviceId: process.env.TOKENUSAGE_CLOUD_DEVICE_ID,
73
+ });
74
+ if (!canUpload()) {
75
+ throw new UsageError("Uploads are blocked by a pending cloud usage reset.", {
76
+ code: "CLOUD_USAGE_RESET_PENDING",
77
+ hint: "Finish the reset from the dashboard, then retry.",
78
+ });
79
+ }
80
+
81
+ const beforeBytes = await pendingBytes(queuePath, queueStatePath);
82
+
83
+ const lock = await acquireSyncLock(lockPath, { drain: true, waitForLock: true });
84
+ if (!lock) {
85
+ throw new UsageError("Another sync is still running; nothing was uploaded.", {
86
+ code: "SYNC_BUSY",
87
+ });
88
+ }
89
+
90
+ let result;
91
+ try {
92
+ await compactPendingQueue({ queuePath, offset: Number((await readJson(queueStatePath))?.offset || 0) });
93
+ result = await drainQueueToCloud({
94
+ baseUrl: runtime.baseUrl,
95
+ anonKey: runtime.anonKey,
96
+ deviceToken: runtime.deviceToken,
97
+ queuePath,
98
+ queueStatePath,
99
+ maxBatches: opts.drain ? MAX_BATCHES_DRAIN : MAX_BATCHES,
100
+ batchSize: BATCH_SIZE,
101
+ canUpload,
102
+ });
103
+ } finally {
104
+ await lock.release();
105
+ }
106
+
107
+ const afterBytes = await pendingBytes(queuePath, queueStatePath);
108
+ const summary = {
109
+ batches: result.batches,
110
+ inserted: result.inserted,
111
+ skipped: result.skipped,
112
+ tokens: result.tokens,
113
+ credits: result.credits,
114
+ pending_bytes_before: beforeBytes,
115
+ pending_bytes_after: afterBytes,
116
+ };
117
+
118
+ if (opts.json) {
119
+ process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
120
+ return;
121
+ }
122
+
123
+ if (result.batches === 0) {
124
+ process.stdout.write(
125
+ [
126
+ "Nothing pending — the local queue is fully uploaded.",
127
+ beforeBytes > 0 ? `(${beforeBytes} bytes were skipped as unuploadable control/invalid rows.)` : null,
128
+ "",
129
+ ].filter(Boolean).join("\n"),
130
+ );
131
+ return;
132
+ }
133
+
134
+ process.stdout.write(
135
+ [
136
+ "Upload complete.",
137
+ `- Requests: ${result.batches}`,
138
+ `- Rows inserted: ${result.inserted.toLocaleString("en-US")} (skipped ${result.skipped.toLocaleString("en-US")})`,
139
+ `- Tokens in this upload: ${result.tokens.toLocaleString("en-US")}`,
140
+ `- Pending bytes: ${beforeBytes} → ${afterBytes}`,
141
+ afterBytes > 0 ? "- Backlog remains; run `tokenusage upload --drain` or retry later." : null,
142
+ "",
143
+ ].filter(Boolean).join("\n"),
144
+ );
145
+ }
146
+
147
+ module.exports = { cmdUpload, parseArgs };
@@ -0,0 +1,33 @@
1
+ "use strict";
2
+
3
+ // Usage errors are the user's mistake (bad flag, unknown command, invalid
4
+ // value), not a crash: print the message (plus an optional hint) and exit 2
5
+ // without a stack trace. The bin entry prints full stacks only under --debug.
6
+ // Everything else keeps the plain message + "re-run with --debug" pointer.
7
+
8
+ class UsageError extends Error {
9
+ constructor(message, { hint = null, code = "USAGE_ERROR", exitCode = 2 } = {}) {
10
+ super(message);
11
+ this.name = "UsageError";
12
+ this.code = code;
13
+ this.hint = hint;
14
+ this.exitCode = exitCode;
15
+ }
16
+ }
17
+
18
+ function isUsageError(error) {
19
+ return Boolean(error && (error instanceof UsageError || error.name === "UsageError"));
20
+ }
21
+
22
+ // Build the "unknown option" error shared by every command's parser so the
23
+ // message and the discoverability hint never drift apart.
24
+ function unknownOptionError(option, command) {
25
+ return new UsageError(`Unknown option: ${option}`, {
26
+ code: "UNKNOWN_OPTION",
27
+ hint: command
28
+ ? `Run \`tokenusage ${command} --help\` to see supported options.`
29
+ : "Run `tokenusage --help` to see supported commands.",
30
+ });
31
+ }
32
+
33
+ module.exports = { UsageError, isUsageError, unknownOptionError };
package/src/lib/cli-ui.js CHANGED
@@ -125,6 +125,98 @@ async function promptMenu({ message, options, defaultIndex = 0 }) {
125
125
  });
126
126
  }
127
127
 
128
+ // Multi-select menu for `init --integrations` prompting. Space toggles the
129
+ // highlighted row, Enter confirms, `a` selects all and `n` clears — the same
130
+ // key vocabulary as the single-select menu so both feel like one component.
131
+ // Returns the selected ids; non-interactive callers get the defaults.
132
+ async function promptMultiSelect({ message, options, defaultSelected = [] }) {
133
+ const safeOptions = Array.isArray(options) ? options : [];
134
+ if (safeOptions.length === 0) return [];
135
+ if (!isInteractive()) {
136
+ const defaults = safeOptions.filter((option) => defaultSelected.includes(option.id));
137
+ return (defaults.length ? defaults : safeOptions).map((option) => option.id);
138
+ }
139
+
140
+ const selected = new Set(defaultSelected.filter((id) => safeOptions.some((option) => option.id === id)));
141
+ if (selected.size === 0) for (const option of safeOptions) selected.add(option.id);
142
+
143
+ const maxIndex = safeOptions.length - 1;
144
+ let currentIndex = 0;
145
+ const linesCount = safeOptions.length + 2;
146
+
147
+ const renderLines = () => {
148
+ const lines = [message];
149
+ safeOptions.forEach((option, idx) => {
150
+ const cursor = idx === currentIndex ? ">" : " ";
151
+ const mark = selected.has(option.id) ? "[x]" : "[ ]";
152
+ lines.push(`${cursor} ${mark} ${option.label}`);
153
+ });
154
+ lines.push(`${DIM}${selected.size}/${safeOptions.length} selected — space toggles, a=all, n=none${RESET}`);
155
+ process.stdout.write(lines.join("\n"));
156
+ };
157
+
158
+ const rerender = () => {
159
+ for (let i = 0; i < linesCount; i += 1) {
160
+ process.stdout.write("\x1b[2K");
161
+ if (i < linesCount - 1) process.stdout.write("\x1b[1A");
162
+ }
163
+ process.stdout.write("\r");
164
+ renderLines();
165
+ };
166
+
167
+ renderLines();
168
+
169
+ return await new Promise((resolve) => {
170
+ const cleanup = () => {
171
+ process.stdin.off("keypress", onKeypress);
172
+ if (process.stdin.isTTY) process.stdin.setRawMode(false);
173
+ process.stdin.pause();
174
+ process.stdout.write("\n");
175
+ };
176
+
177
+ const finish = () => {
178
+ cleanup();
179
+ resolve(safeOptions.filter((option) => selected.has(option.id)).map((option) => option.id));
180
+ };
181
+
182
+ const onKeypress = (str, key = {}) => {
183
+ if (key.ctrl && key.name === "c") return finish();
184
+ if (key.name === "up" || str === "k") {
185
+ currentIndex = currentIndex === 0 ? maxIndex : currentIndex - 1;
186
+ rerender();
187
+ return;
188
+ }
189
+ if (key.name === "down" || str === "j") {
190
+ currentIndex = currentIndex === maxIndex ? 0 : currentIndex + 1;
191
+ rerender();
192
+ return;
193
+ }
194
+ if (key.name === "space" || str === " ") {
195
+ const id = safeOptions[currentIndex].id;
196
+ if (selected.has(id)) selected.delete(id);
197
+ else selected.add(id);
198
+ rerender();
199
+ return;
200
+ }
201
+ if (key.name === "return") return finish();
202
+ if (str === "a") {
203
+ for (const option of safeOptions) selected.add(option.id);
204
+ rerender();
205
+ return;
206
+ }
207
+ if (str === "n") {
208
+ selected.clear();
209
+ rerender();
210
+ }
211
+ };
212
+
213
+ readline.emitKeypressEvents(process.stdin);
214
+ if (process.stdin.isTTY) process.stdin.setRawMode(true);
215
+ process.stdin.resume();
216
+ process.stdin.on("keypress", onKeypress);
217
+ });
218
+ }
219
+
128
220
  function createSpinner({ text, intervalMs = 80 }) {
129
221
  let frame = 0;
130
222
  let timer = null;
@@ -179,6 +271,7 @@ module.exports = {
179
271
  renderBox,
180
272
  isInteractive,
181
273
  promptMenu,
274
+ promptMultiSelect,
182
275
  promptEnter,
183
276
  createSpinner,
184
277
  formatSummaryLine,
@@ -35,6 +35,15 @@ function sanitizeBucketForUpload(bucket) {
35
35
  if (bucket.conversation_count !== undefined) sanitized.conversation_count = nonNegativeInteger(bucket.conversation_count);
36
36
  if (bucket.conversations !== undefined) sanitized.conversations = nonNegativeInteger(bucket.conversations);
37
37
  sanitized.total_cost_usd = bucket.total_cost_usd == null ? 0 : nonNegativeNumber(bucket.total_cost_usd);
38
+ // Credits (docs/cli-contract.md §2.4, 2026-10-31): optional float, dropped
39
+ // entirely when zero/invalid so rows without a credit-based provider keep
40
+ // their previous wire shape.
41
+ const credits = Number(bucket.credits);
42
+ if (Number.isFinite(credits) && credits > 0) {
43
+ sanitized.credits = Math.round(credits * 1e6) / 1e6;
44
+ } else {
45
+ delete sanitized.credits;
46
+ }
38
47
  return sanitized;
39
48
  }
40
49
 
@@ -0,0 +1,55 @@
1
+ "use strict";
2
+
3
+ // Queue-row read-time normalization, shared by every queue reader (the sync
4
+ // upload path today; the local dashboard used to read it too). Keeping it in
5
+ // its own module — instead of inside the retired local API — means a reader
6
+ // only pulls the two rules below, not a 3,000-line HTTP server.
7
+
8
+ function isLegacyInclusiveCodexRow(row) {
9
+ if (!row || (row.source !== "codex" && row.source !== "every-code")) return false;
10
+ const inputTokens = Number(row.input_tokens || 0);
11
+ const cachedInputTokens = Number(row.cached_input_tokens || 0);
12
+ const outputTokens = Number(row.output_tokens || 0);
13
+ const totalTokens = Number(row.total_tokens || 0);
14
+ if (!Number.isFinite(inputTokens) || !Number.isFinite(cachedInputTokens)) return false;
15
+ if (cachedInputTokens <= 0 || inputTokens < cachedInputTokens) return false;
16
+ // Legacy Codex queue rows stored input inclusive of cache reads, while
17
+ // total_tokens remained input + output. Canonical rows keep input as pure
18
+ // non-cached input, so cache-heavy legacy rows can be identified by this
19
+ // exact invariant.
20
+ return totalTokens === inputTokens + outputTokens;
21
+ }
22
+
23
+ function normalizeQueueRow(row) {
24
+ if (!row || typeof row !== "object") return row;
25
+ let normalized = row;
26
+ if (isLegacyInclusiveCodexRow(normalized)) {
27
+ normalized = {
28
+ ...normalized,
29
+ input_tokens:
30
+ Number(normalized.input_tokens || 0) - Number(normalized.cached_input_tokens || 0),
31
+ };
32
+ }
33
+ // Legacy Cursor rows from versions ≤ 0.26.5 wrote billable_total_tokens = 0
34
+ // for "Included in Pro" / "Enterprise" / "no charge" records (kind-based
35
+ // gating in cursor-config.js#normalizeCursorUsage). Billable and usage are
36
+ // orthogonal: bump billable up to total_tokens at read time so historical
37
+ // queue.jsonl entries stay correct without requiring a file rewrite.
38
+ // Antigravity had the same symptom (billable was dropped during a parser
39
+ // refactoring, leaving local rows with billable=0 until the parser fix), so
40
+ // the same read-time healing applies.
41
+ const sourceName = String(normalized.source || "").toLowerCase();
42
+ if (sourceName === "cursor" || sourceName === "antigravity") {
43
+ const totalTokens = Number(normalized.total_tokens || 0);
44
+ const billable = Number(normalized.billable_total_tokens || 0);
45
+ if (totalTokens > 0 && billable < totalTokens) {
46
+ normalized = { ...normalized, billable_total_tokens: totalTokens };
47
+ }
48
+ }
49
+ return normalized;
50
+ }
51
+
52
+ module.exports = {
53
+ isLegacyInclusiveCodexRow,
54
+ normalizeQueueRow,
55
+ };