usagemax 0.3.3 → 0.3.7

package/src/cli.js

@@ -13,18 +13,27 @@ import { fileURLToPath } from "node:url";
 import { prepareArchiveRecovery } from "./archives.js";
 import { buildSessionPlan, buildSnapshotPlan, normalizeLinkCode, reportDateArgs, scanPolicy, sourceSummary, validHttpsUrl } from "./core.js";
 import { stableInstallationId } from "./installation.js";
+import { createProgress } from "./progress.js";
 import { intervalMinutes, manageService, runScheduledSync } from "./service.js";
-import { requestSnapshot } from "./transport.js";
+import { collectorStatusView, requestCollectorStatus, requestSnapshot } from "./transport.js";
 import { resumeUpload, restartExpiredUpload, withConfigLock } from "./resume.js";
 import { CCUSAGE_VERSION, ccusageEnvironment, ccusageHome, discoverProviderArchives, SOURCE_INVENTORY_VERSION, sourceInventory, SUPPORTED_SOURCES } from "./sources.js";
+import { checkForUpdate, runLatest } from "./updates.js";
+
+// Make the short-lived collector recognizable in Activity Monitor and `ps`.
+// Windows may still display the underlying node.exe image name in Task Manager.
+process.title = "UsageMax";
 
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.3.3";
+const VERSION = "0.3.7";
 const PUBLIC_API_ORIGIN = "https://usagemax.com/api";
 const DEFAULT_LINK_ENDPOINT = `${PUBLIC_API_ORIGIN}/v1/devices/link`;
+const DEFAULT_STATUS_ENDPOINT = `${PUBLIC_API_ORIGIN}/v1/devices/status`;
 const CONFIG_FILE = "config.json";
 const MAX_REPORT_BYTES = 100 * 1024 * 1024;
+const TOKEN_PATTERN = /^umx_[a-f0-9]{64}$/;
+const DEVICE_PATTERN = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
 
 function configDirectory() {
   if (process.env.USAGEMAX_CONFIG_DIR) return process.env.USAGEMAX_CONFIG_DIR;
@@ -51,18 +60,21 @@ function isLegacyDirectApi(config) {
 async function readConfig() {
   try {
     const parsed = JSON.parse(await readFile(configPath(), "utf8"));
-    if (!parsed || parsed.version !== 1 || !/^umx_[a-f0-9]{64}$/.test(parsed.token || "")) return null;
+    if (!parsed || parsed.version !== 1 || !TOKEN_PATTERN.test(parsed.token || "")) return null;
     if (!validHttpsUrl(parsed.ingestUrl, { allowLocalhost: true })) return null;
     if (typeof parsed.deviceId !== "string" || !parsed.deviceId) return null;
     parsed.snapshots = parsed.snapshots && typeof parsed.snapshots === "object" ? parsed.snapshots : {};
     if (isLegacyDirectApi(parsed)) {
       parsed.ingestUrl = `${PUBLIC_API_ORIGIN}/v1/telemetry/llm`;
       parsed.snapshotUrl = `${PUBLIC_API_ORIGIN}/v2/usage/snapshots`;
+      parsed.statusUrl = `${PUBLIC_API_ORIGIN}/v1/devices/status`;
       parsed.revokeUrl = `${PUBLIC_API_ORIGIN}/v1/devices/revoke`;
       await writeConfig(parsed);
     }
     parsed.snapshotUrl = validHttpsUrl(parsed.snapshotUrl, { allowLocalhost: true })
       || parsed.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v2/usage/snapshots");
+    parsed.statusUrl = validHttpsUrl(parsed.statusUrl, { allowLocalhost: true })
+      || parsed.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/status");
     parsed.revokeUrl = validHttpsUrl(parsed.revokeUrl, { allowLocalhost: true })
       || parsed.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/revoke");
     return parsed;
@@ -108,12 +120,18 @@ function help() {
   process.stdout.write("           [--no-sync] [--name <name>]\n");
   process.stdout.write("  usagemax sync [--full] [--archives] [--restart] [--dry-run] [--explain] [--json]\n");
   process.stdout.write("                                  Reconcile once; --archives performs one-time recovery\n");
+  process.stdout.write("           [--quiet|--no-progress] [--check-updates|--no-update-check]  Control progress and the cached release check\n");
   process.stdout.write("  usagemax status                  Show local link status\n");
+  process.stdout.write("           --remote [--json]        Verify the stored collector credential without printing it\n");
+  process.stdout.write("           [--quiet|--no-progress]  Disable interactive progress output\n");
+  process.stdout.write("  usagemax token status [--device-id <uuid>] [--json]\n");
+  process.stdout.write("                                  Diagnose a key piped on stdin; never pass it as an argument\n");
   process.stdout.write("  usagemax service install [--every 15]\n");
   process.stdout.write("                                  Opt into lightweight OS-scheduled sync\n");
   process.stdout.write("  usagemax service status|run|uninstall\n");
-  process.stdout.write("  usagemax doctor [--deep] [--json]\n");
+  process.stdout.write("  usagemax doctor [--deep] [--json] [--quiet|--no-progress]\n");
   process.stdout.write("                                  Check source coverage; --deep parses full history\n");
+  process.stdout.write("  usagemax update [command args]  Check npm and optionally run the latest CLI\n");
   process.stdout.write("  usagemax report [...args]        Run a local ccusage report\n");
   process.stdout.write("  usagemax unlink [--revoke]       Remove locally; --revoke also disables uploads\n");
 }
@@ -157,7 +175,7 @@ function newerVersion(recommended) {
 
 function warnVersion(body) {
   if (newerVersion(body?.recommendedCliVersion)) {
-    process.stderr.write(`UsageMax ${body.recommendedCliVersion} is available. Run \`bunx usagemax@latest\` for current coverage fixes.\n`);
+    process.stderr.write(`UsageMax ${body.recommendedCliVersion} is available. Run \`usagemax update sync\` or set USAGEMAX_AUTO_UPDATE=1.\n`);
   }
 }
 
@@ -167,7 +185,8 @@ async function link(args) {
   const configuredEndpoint = process.env.USAGEMAX_LINK_ENDPOINT || DEFAULT_LINK_ENDPOINT;
   const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
   if (!endpoint) throw new Error("USAGEMAX_LINK_ENDPOINT must use HTTPS, except for localhost development.");
-  const name = (option(args, "--name") || deviceLabel()).trim().slice(0, 80);
+  const requestedName = option(args, "--name");
+  const name = requestedName?.trim().slice(0, 80) || undefined;
   const previous = await readConfig();
   const deviceId = await stableInstallationId(configDirectory(), previous?.deviceId);
   const headers = { "content-type": "application/json" };
@@ -175,33 +194,36 @@ async function link(args) {
   const response = await fetch(endpoint, {
     method: "POST",
     headers,
-    body: JSON.stringify({ code, name, platform: platform(), cliVersion: VERSION, deviceId }),
+    body: JSON.stringify({ code, ...(name ? { name, nameExplicit: true } : {}), platform: platform(), cliVersion: VERSION, deviceId }),
     signal: AbortSignal.timeout(15_000),
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) throw new Error(body?.error === "invalid_or_expired_link_code" ? "That link code is invalid, expired, or already used." : "UsageMax could not link this computer.");
   const ingestUrl = validHttpsUrl(body.ingestUrl, { allowLocalhost: true });
   const snapshotUrl = validHttpsUrl(body.snapshotUrl, { allowLocalhost: true }) || ingestUrl?.replace(/\/v1\/telemetry\/llm$/, "/v2/usage/snapshots");
+  const statusUrl = validHttpsUrl(body.statusUrl, { allowLocalhost: true }) || ingestUrl?.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/status");
   const revokeUrl = validHttpsUrl(body.revokeUrl, { allowLocalhost: true }) || ingestUrl?.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/revoke");
-  if (!/^umx_[a-f0-9]{64}$/.test(body.token || "") || !ingestUrl || !snapshotUrl || !revokeUrl) throw new Error("UsageMax returned an invalid link response.");
+  if (!TOKEN_PATTERN.test(body.token || "") || !ingestUrl || !snapshotUrl || !statusUrl || !revokeUrl) throw new Error("UsageMax returned an invalid link response.");
   const profileHandle = typeof body.profileHandle === "string" ? body.profileHandle : undefined;
+  const savedName = typeof body.deviceName === "string" && body.deviceName.trim() ? body.deviceName.trim().slice(0, 80) : (name || deviceLabel());
   const sameAccount = Boolean(previous && previous.profileHandle && previous.profileHandle === profileHandle);
   const config = {
     version: 1,
     token: body.token,
     ingestUrl,
     snapshotUrl,
+    statusUrl,
     revokeUrl,
     profileUrl: validHttpsUrl(body.profileUrl) || "https://usagemax.com/account",
     profileHandle,
     deviceId,
-    deviceName: name,
+    deviceName: savedName,
     linkedAt: new Date().toISOString(),
     snapshots: sameAccount ? previous.snapshots : {},
   };
   await writeConfig(config);
   warnVersion(body);
-  process.stdout.write(`Linked ${name} to ${config.profileHandle ? `@${config.profileHandle}` : "UsageMax"}.\n`);
+  process.stdout.write(`Linked ${savedName} to ${config.profileHandle ? `@${config.profileHandle}` : "UsageMax"}.\n`);
   if (args.includes("--no-sync")) {
     process.stdout.write("No usage was uploaded. Run `bunx usagemax sync --full` when you are ready.\n");
     return;
@@ -211,18 +233,27 @@ async function link(args) {
 }
 
 async function sync(args, suppliedConfig) {
-  const baseEnv = await ccusageEnvironment();
-  const recovery = args.includes("--archives")
-    ? await prepareArchiveRecovery(baseEnv)
-    : { archives: 0, cleanup: async () => undefined, env: baseEnv, unsupported: 0 };
+  const progress = createProgress({ json: args.includes("--json"), quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
+  progress.start("Preparing local usage sync…");
+  let recovery;
   try {
-    return await syncPrepared(args, suppliedConfig, recovery);
+    const baseEnv = await ccusageEnvironment();
+    recovery = args.includes("--archives")
+      ? await prepareArchiveRecovery(baseEnv)
+      : { archives: 0, cleanup: async () => undefined, env: baseEnv, unsupported: 0 };
+    return await syncPrepared(args, suppliedConfig, recovery, progress);
+  } catch (error) {
+    // Clear the transient line; the shared top-level handler prints one
+    // stable error message so failures are not duplicated.
+    progress.stop();
+    throw error;
   } finally {
-    await recovery.cleanup();
+    await recovery?.cleanup();
+    progress.stop();
   }
 }
 
-async function syncPrepared(args, suppliedConfig, recovery) {
+async function syncPrepared(args, suppliedConfig, recovery, progress = createProgress({ noProgress: true })) {
   const config = suppliedConfig || await readConfig();
   if (!config) throw new Error("This computer is not linked. Open https://usagemax.com/account and create a link code.");
   config.deviceId = await stableInstallationId(configDirectory(), config.deviceId);
@@ -236,16 +267,25 @@ async function syncPrepared(args, suppliedConfig, recovery) {
     await writeConfig(config);
   }
   if (config.pendingSync) {
+    progress.update("Resuming the saved upload checkpoint…");
     if (dryRun) {
       const result = { ...config.pendingSync.result, dryRun: true, pendingRunId: config.pendingSync.runId };
       process.stdout.write(json ? `${JSON.stringify(result)}\n` : `Dry run: saved run ${config.pendingSync.runId} awaits resume; no upload.\n`);
+      progress.succeed("Dry run complete; saved upload remains untouched.");
       return result;
     }
-    const result = await resumeUpload(config, { save: writeConfig, request: snapshotRequest, warn: warnVersion });
+    const result = await resumeUpload(config, {
+      save: writeConfig,
+      request: snapshotRequest,
+      warn: warnVersion,
+      onProgress: ({ index, total, operation, acknowledged }) => progress.update(`${acknowledged ? "Uploaded" : "Uploading"} ${index}/${total} · ${operation}`),
+    });
+    progress.succeed("Resumed and completed the saved sync.");
     process.stdout.write(json ? `${JSON.stringify(result)}\n` : "Resumed and completed the saved sync. Run sync again to scan newer local changes.\n");
     return result;
   }
   const inventory = await sourceInventory({ env: recovery.env, home: ccusageHome(recovery.env) });
+  progress.update(`Found ${inventory.sources.length} source${inventory.sources.length === 1 ? "" : "s"} and ${inventory.files}${inventory.truncated ? "+" : ""} local data file${inventory.files === 1 ? "" : "s"}.`);
   const today = new Date().toISOString().slice(0, 10);
   const knownSources = Array.isArray(config.knownSources) ? config.knownSources : [];
   const { bootstrap, full, skip, inventoryStable } = scanPolicy(config, inventory, {
@@ -255,8 +295,10 @@ async function syncPrepared(args, suppliedConfig, recovery) {
     const result = { accepted: 0, changedRows: 0, sessions: 0, sources: inventory.sources, corrections: 0, scanned: false, full: false, coverage: config.lastCoverage || "partial" };
     if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
     else process.stdout.write("Already up to date. Local usage files have not changed; no logs were parsed or uploaded.\n");
+    progress.succeed("No local changes; upload skipped.");
     return;
   }
+  progress.update(`Parsing ${full ? "retained history" : "changed history"} with ccusage…`);
   const report = await ccusageJson(config, { env: recovery.env, full });
   // ccusage v20 exposes aggregates, not proof that every discovered file was
   // parsed. Inventory success alone cannot authorize destructive corrections.
@@ -293,6 +335,7 @@ async function syncPrepared(args, suppliedConfig, recovery) {
     coverageReason: "Parser does not certify complete source/day coverage; decreases and deletions are protected.",
     range: { from: days[0], to: days.at(-1) },
   };
+  progress.update(`Prepared ${partitions.length} usage chunk${partitions.length === 1 ? "" : "s"} and ${sessions.length} session identifier${sessions.length === 1 ? "" : "s"}.`);
   if (requestedArchives) {
     result.archives = recovery.archives;
     result.unsupportedArchives = recovery.unsupported;
@@ -303,6 +346,7 @@ async function syncPrepared(args, suppliedConfig, recovery) {
       process.stdout.write(`Dry run: ${partitions.length} partition(s), ${result.changedRows} changed row(s), ${sessions.length} private session identifiers, no upload.\n`);
       if (explain) process.stdout.write(`Coverage ${result.coverage}; ${sources.length} source(s); ${days[0] || "unknown"} to ${days.at(-1) || "unknown"}; ${regressions.length} protected regression(s). ${result.coverageReason}\n`);
     }
+    progress.succeed("Dry run complete; nothing uploaded.");
     return result;
   }
   const requests = [{ operation: "begin", payload: {
@@ -339,7 +383,13 @@ async function syncPrepared(args, suppliedConfig, recovery) {
   };
   config.lastSyncComplete = false;
   await writeConfig(config);
-  await resumeUpload(config, { save: writeConfig, request: snapshotRequest, warn: warnVersion });
+  await resumeUpload(config, {
+    save: writeConfig,
+    request: snapshotRequest,
+    warn: warnVersion,
+    onProgress: ({ index, total, operation, acknowledged }) => progress.update(`${acknowledged ? "Uploaded" : "Uploading"} ${index}/${total} · ${operation}`),
+  });
+  progress.succeed(`Sync complete · ${partitions.length} chunk${partitions.length === 1 ? "" : "s"}, ${sessions.length} session identifier${sessions.length === 1 ? "" : "s"}.`);
   if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
   else {
     process.stdout.write(partitions.length || sessions.length
@@ -352,9 +402,38 @@ async function syncPrepared(args, suppliedConfig, recovery) {
   return result;
 }
 
-async function status() {
+function collectorStatusEndpoint(config) {
+  return validHttpsUrl(process.env.USAGEMAX_STATUS_ENDPOINT, { allowLocalhost: true })
+    || validHttpsUrl(config.statusUrl, { allowLocalhost: true })
+    || config.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/status");
+}
+
+function printRemoteStatus(view) {
+  process.stdout.write(`Remote credential: ${view.status || "unavailable"}${view.httpStatus ? ` (HTTP ${view.httpStatus})` : ""}\n`);
+  if (view.reason) process.stdout.write(`${view.reason}\n`);
+  if (view.credentialType) process.stdout.write(`Type: ${view.credentialType}${view.writeOnly ? "; write-only" : ""}\n`);
+  if (view.scopes?.length) process.stdout.write(`Scopes: ${view.scopes.join(", ")}\n`);
+  if (view.scopeStatus) process.stdout.write(`Ingest scope: ${view.scopeStatus === "valid" ? "authorized" : "missing telemetry:write"}\n`);
+  if (view.deviceBinding) process.stdout.write(`Device binding: ${view.deviceBinding}\n`);
+  if (view.profileHandle) process.stdout.write(`Profile: @${view.profileHandle}\n`);
+  if (view.deviceName) process.stdout.write(`Computer: ${view.deviceName}\n`);
+  if (view.platform || view.cliVersion) process.stdout.write(`Runtime: ${view.platform || "unknown"}${view.cliVersion ? ` · CLI ${view.cliVersion}` : ""}\n`);
+  if (view.activation) process.stdout.write(`Activation: ${view.activation}\n`);
+  if (view.expiresAt === null) process.stdout.write("Expiration: none\n");
+  if (view.lastSuccessAt) process.stdout.write(`Last accepted write: ${new Date(view.lastSuccessAt).toISOString()}\n`);
+  if (view.lastFailureAt) process.stdout.write(`Last rejected write: ${new Date(view.lastFailureAt).toISOString()}${view.lastFailureCode ? ` · ${view.lastFailureCode}` : ""}\n`);
+}
+
+async function status(args = []) {
   const config = await readConfig();
+  const remote = args.includes("--remote");
+  const json = args.includes("--json");
+  const progress = createProgress({ json, quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
   if (!config) {
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ linked: false, remote: remote ? { status: "not_linked" } : undefined })}\n`);
+      return;
+    }
     process.stdout.write("Not linked. Open https://usagemax.com/account to connect this computer.\n");
     return;
   }
@@ -363,52 +442,140 @@ async function status() {
     config.deviceId = stableId;
     await writeConfig(config);
   }
+  const local = {
+    linked: true,
+    deviceName: config.deviceName || deviceLabel(),
+    profileHandle: config.profileHandle || null,
+    deviceIdConfigured: Boolean(config.deviceId),
+    lastSyncAt: config.lastSyncAt || null,
+    lastFullSyncAt: config.lastFullSyncAt || null,
+    pendingSync: config.pendingSync?.runId || null,
+    profileUrl: config.profileUrl || "https://usagemax.com/account",
+  };
+  let remoteView;
+  if (remote) {
+    progress.start("Checking the stored collector credential…");
+    try {
+      const result = await requestCollectorStatus(collectorStatusEndpoint(config), config);
+      remoteView = collectorStatusView(result.httpStatus, result.body, config.token);
+      progress.succeed("Remote credential checked.");
+    } catch (error) {
+      progress.stop();
+      remoteView = { tokenFormat: "valid", status: "unavailable", reason: error instanceof Error ? error.message : "Collector status unavailable." };
+    }
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ ...local, remote: remoteView })}\n`);
+      return;
+    }
+  }
+  if (json) {
+    process.stdout.write(`${JSON.stringify(local)}\n`);
+    return;
+  }
   process.stdout.write(`Linked: ${config.deviceName || deviceLabel()}${config.profileHandle ? ` → @${config.profileHandle}` : ""}\n`);
   process.stdout.write(`Last sync: ${config.lastSyncAt || "never"}\n`);
   process.stdout.write(`Last full reconciliation: ${config.lastFullSyncAt || "never"}\n`);
   if (config.pendingSync) process.stdout.write(`Pending sync: ${config.pendingSync.runId}; rerun sync to resume\n`);
   process.stdout.write(`Profile: ${config.profileUrl || "https://usagemax.com/account"}\n`);
+  if (remote) printRemoteStatus(remoteView);
 }
 
-async function doctor(args = []) {
-  const config = await readConfig();
-  const env = await ccusageEnvironment();
-  const inventory = await sourceInventory({ env, home: ccusageHome(env) });
-  const archives = await discoverProviderArchives({ env, home: ccusageHome(env) });
-  const homes = String(env.USAGEMAX_DISCOVERED_HOMES || ccusageHome(env)).split(",").filter(Boolean);
-  const result = {
-    linked: Boolean(config),
-    homes,
-    detectedSources: inventory.sources,
-    files: inventory.files,
-    inventoryComplete: inventory.complete,
-    inventoryErrors: inventory.errors,
-    inventoryTruncated: inventory.truncated,
-    supportedSources: SUPPORTED_SOURCES,
-    archives: archives.length,
-    environment: platform() === "linux" && process.env.WSL_DISTRO_NAME ? `WSL ${process.env.WSL_DISTRO_NAME}` : platform(),
-    mode: args.includes("--deep") ? "deep" : "metadata-only",
-  };
-  if (args.includes("--deep")) {
-    const report = await ccusageJson(config, { env, full: true });
-    result.parsedSources = sourceSummary(report);
-    result.sessions = buildSessionPlan(report, config?.deviceId || "unlinked").length;
+async function readTokenFromStdin() {
+  if (process.stdin.isTTY) throw new Error("Pipe the collector token on stdin; never pass it as a command-line argument.");
+  // fs.promises.readFile does not consistently accept file descriptor 0
+  // across the Node versions supported by the CLI. Read the pipe as a stream
+  // instead, and bound it so an accidental large stdin cannot be buffered.
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += String(chunk);
+    if (input.length > 256) throw new Error("stdin did not contain a valid UsageMax collector token.");
   }
-  if (args.includes("--json")) {
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-    return;
+  const token = input.trim();
+  if (!TOKEN_PATTERN.test(token)) throw new Error("stdin did not contain a valid UsageMax collector token (expected umx_ plus 64 lowercase hexadecimal characters).");
+  return token;
+}
+
+async function tokenStatus(args = []) {
+  const requestedDeviceId = option(args, "--device-id");
+  if (requestedDeviceId && !DEVICE_PATTERN.test(requestedDeviceId)) throw new Error("--device-id must be a UUID.");
+  const json = args.includes("--json");
+  const progress = createProgress({ json, quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
+  progress.start("Checking the collector credential…");
+  let token;
+  try {
+    token = await readTokenFromStdin();
+  } catch (error) {
+    progress.stop();
+    throw error;
+  }
+  const configuredEndpoint = process.env.USAGEMAX_STATUS_ENDPOINT || DEFAULT_STATUS_ENDPOINT;
+  const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
+  try {
+    if (!endpoint) throw new Error("USAGEMAX_STATUS_ENDPOINT must use HTTPS, except for localhost development.");
+    const result = await requestCollectorStatus(endpoint, { token, deviceId: requestedDeviceId });
+    const view = collectorStatusView(result.httpStatus, result.body, token);
+    progress.succeed("Collector credential checked.");
+    if (json) process.stdout.write(`${JSON.stringify(view)}\n`);
+    else {
+      process.stdout.write("Credential format: valid (umx_ + 64 lowercase hexadecimal characters)\n");
+      printRemoteStatus(view);
+    }
+  } catch (error) {
+    progress.stop();
+    throw error;
   }
-  process.stdout.write(`Collector: ${config ? "linked" : "not linked"}\n`);
-  process.stdout.write(`Discovered homes: ${homes.length} (${homes.join(", ")})\n`);
-  process.stdout.write(`Detected sources: ${inventory.sources.join(", ") || "none"} (${inventory.files}${inventory.truncated ? "+" : ""} data files)\n`);
-  process.stdout.write(`Supported sources: ${SUPPORTED_SOURCES.join(", ")} (+ named pi-format stores)\n`);
-  if (platform() === "linux" && process.env.WSL_DISTRO_NAME) {
-    process.stdout.write(`Environment: WSL ${process.env.WSL_DISTRO_NAME}; readable Windows provider homes are included automatically\n`);
+}
+
+async function doctor(args = []) {
+  const json = args.includes("--json");
+  const progress = createProgress({ json, quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
+  progress.start(args.includes("--deep") ? "Auditing retained source history…" : "Inspecting local source coverage…");
+  try {
+    const config = await readConfig();
+    const env = await ccusageEnvironment();
+    const inventory = await sourceInventory({ env, home: ccusageHome(env) });
+    progress.update(`Found ${inventory.sources.length} source${inventory.sources.length === 1 ? "" : "s"} and ${inventory.files}${inventory.truncated ? "+" : ""} local data file${inventory.files === 1 ? "" : "s"}.`);
+    const archives = await discoverProviderArchives({ env, home: ccusageHome(env) });
+    const homes = String(env.USAGEMAX_DISCOVERED_HOMES || ccusageHome(env)).split(",").filter(Boolean);
+    const result = {
+      linked: Boolean(config),
+      homes,
+      detectedSources: inventory.sources,
+      files: inventory.files,
+      inventoryComplete: inventory.complete,
+      inventoryErrors: inventory.errors,
+      inventoryTruncated: inventory.truncated,
+      supportedSources: SUPPORTED_SOURCES,
+      archives: archives.length,
+      environment: platform() === "linux" && process.env.WSL_DISTRO_NAME ? `WSL ${process.env.WSL_DISTRO_NAME}` : platform(),
+      mode: args.includes("--deep") ? "deep" : "metadata-only",
+    };
+    if (args.includes("--deep")) {
+      progress.update("Parsing retained history with ccusage…");
+      const report = await ccusageJson(config, { env, full: true });
+      result.parsedSources = sourceSummary(report);
+      result.sessions = buildSessionPlan(report, config?.deviceId || "unlinked").length;
+    }
+    progress.succeed("Coverage check complete.");
+    if (json) {
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+      return;
+    }
+    process.stdout.write(`Collector: ${config ? "linked" : "not linked"}\n`);
+    process.stdout.write(`Discovered homes: ${homes.length} (${homes.join(", ")})\n`);
+    process.stdout.write(`Detected sources: ${inventory.sources.join(", ") || "none"} (${inventory.files}${inventory.truncated ? "+" : ""} data files)\n`);
+    process.stdout.write(`Supported sources: ${SUPPORTED_SOURCES.join(", ")} (+ named pi-format stores)\n`);
+    if (platform() === "linux" && process.env.WSL_DISTRO_NAME) {
+      process.stdout.write(`Environment: WSL ${process.env.WSL_DISTRO_NAME}; readable Windows provider homes are included automatically\n`);
+    }
+    if (archives.length) process.stdout.write(`Recovery: ${archives.length} compressed provider archive(s) detected; run \`bunx usagemax sync --archives\` once to reconcile them\n`);
+    if (!inventory.complete) process.stdout.write(`Inventory: incomplete (${inventory.errors} read error(s)${inventory.truncated ? ", file limit reached" : ""}); no-change shortcut disabled\n`);
+    if (result.parsedSources) process.stdout.write(`Parsed sources: ${result.parsedSources.join(", ") || "none"}; ${result.sessions} private session identifiers\n`);
+    process.stdout.write(`Mode: one-shot, metadata no-op check, ${args.includes("--deep") ? "deep local parse" : "no log parsing"}\n`);
+  } catch (error) {
+    progress.stop();
+    throw error;
   }
-  if (archives.length) process.stdout.write(`Recovery: ${archives.length} compressed provider archive(s) detected; run \`bunx usagemax sync --archives\` once to reconcile them\n`);
-  if (!inventory.complete) process.stdout.write(`Inventory: incomplete (${inventory.errors} read error(s)${inventory.truncated ? ", file limit reached" : ""}); no-change shortcut disabled\n`);
-  if (result.parsedSources) process.stdout.write(`Parsed sources: ${result.parsedSources.join(", ") || "none"}; ${result.sessions} private session identifiers\n`);
-  process.stdout.write(`Mode: one-shot, metadata no-op check, ${args.includes("--deep") ? "deep local parse" : "no log parsing"}\n`);
 }
 
 async function report(args) {
@@ -424,6 +591,41 @@ async function report(args) {
   if (code !== 0) process.exitCode = code;
 }
 
+async function update(args = []) {
+  const check = await checkForUpdate(configDirectory(), VERSION, { force: true });
+  if (!check.latest) {
+    process.stdout.write(`UsageMax CLI ${VERSION} · update check unavailable.\n`);
+    return;
+  }
+  if (!check.newer) {
+    process.stdout.write(`UsageMax CLI ${VERSION} is current.\n`);
+    return;
+  }
+  process.stdout.write(`UsageMax CLI ${check.latest} is available (current ${VERSION}).\n`);
+  const commandArgs = args.filter((arg) => arg !== "--check");
+  if (!commandArgs.length || args.includes("--check")) {
+    process.stdout.write("Run `usagemax update sync` to hand off the next command to the latest npm release.\n");
+    return;
+  }
+  process.stdout.write(`Launching UsageMax ${check.latest}…\n`);
+  return runLatest(commandArgs);
+}
+
+async function maybeUpdate(command, args) {
+  if (process.env.USAGEMAX_UPDATE_HANDOFF === "1" || process.env.USAGEMAX_DISABLE_UPDATE_CHECK === "1" || args.includes("--no-update-check")) return false;
+  if (!["sync", "link", "doctor"].includes(command)) return false;
+  const explicitCheck = args.includes("--check-updates");
+  if (!explicitCheck && args.includes("--json")) return false;
+  const check = await checkForUpdate(configDirectory(), VERSION, { force: explicitCheck });
+  if (!check.newer) return false;
+  if (process.env.USAGEMAX_AUTO_UPDATE === "1") {
+    await runLatest([command, ...args.filter((arg) => !["--check-updates", "--no-update-check"].includes(arg))]);
+    return true;
+  }
+  process.stderr.write(`UsageMax ${check.latest} is available. Run \`usagemax update ${command}\` or set USAGEMAX_AUTO_UPDATE=1.\n`);
+  return false;
+}
+
 async function removeLink(args = []) {
   const path = configPath();
   const config = await readConfig();
@@ -436,8 +638,10 @@ async function removeLink(args = []) {
     if (!endpoint) throw new Error("This collector does not have a valid revoke endpoint. Revoke it at https://usagemax.com/account.");
     const response = await fetch(endpoint, {
       method: "POST",
-      headers: { authorization: `Bearer ${config.token}`, "content-type": "application/json" },
-      body: JSON.stringify({ deviceId: config.deviceId }),
+      headers: {
+        authorization: `Bearer ${config.token}`,
+        "x-usagemax-device-id": config.deviceId,
+      },
       signal: AbortSignal.timeout(15_000),
     });
     if (!response.ok) throw new Error("UsageMax could not revoke this collector. It remains linked locally.");
@@ -453,6 +657,8 @@ async function main() {
   const command = args[0] || "sync";
   if (["--help", "-h", "help"].includes(command)) return help();
   if (["--version", "-v"].includes(command)) return process.stdout.write(`${VERSION}\n`);
+  if (command === "update") return update(args.slice(1));
+  if (await maybeUpdate(command, args)) return;
   if (command === "service") {
     const action = args[1] || "status";
     const directory = option(args, "--config-dir") || configDirectory();
@@ -474,11 +680,12 @@ async function main() {
     return;
   }
   if (command === "report") return report(args.slice(1));
+  if (command === "token" && args[1] === "status") return tokenStatus(args.slice(2));
   if (["link", "sync", "status", "doctor", "unlink"].includes(command)) {
     return withConfigLock(configDirectory(), async () => {
       if (command === "link") return link(args.slice(1));
       if (command === "sync") return sync(args.slice(1));
-      if (command === "status") return status();
+      if (command === "status") return status(args.slice(1));
       if (command === "doctor") return doctor(args.slice(1));
       return removeLink(args.slice(1));
     });

package/src/progress.js

@@ -0,0 +1,73 @@
+const FRAMES = ["·", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function canAnimate({ json = false, quiet = false, noProgress = false } = {}) {
+  return Boolean(process.stderr.isTTY)
+    && !json
+    && !quiet
+    && !noProgress
+    && process.env.USAGEMAX_NO_PROGRESS !== "1"
+    && process.env.CI !== "true";
+}
+
+/**
+ * A tiny stderr-only progress reporter. JSON and scheduled runs stay silent so
+ * stdout remains machine-readable and background jobs do not write a stream.
+ */
+export function createProgress(options = {}) {
+  const enabled = canAnimate(options);
+  let timer;
+  let frame = 0;
+  let active = false;
+  let last = "";
+  let startedAt = 0;
+
+  const elapsed = () => {
+    const seconds = Math.max(0, (Date.now() - startedAt) / 1000);
+    return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+  };
+
+  const render = (text) => {
+    if (!enabled || !active) return;
+    const line = `${FRAMES[frame % FRAMES.length]} ${text} · ${elapsed()}`;
+    frame += 1;
+    last = line;
+    process.stderr.write(`\r\x1b[2K${line}`);
+  };
+
+  return {
+    enabled,
+    start(text) {
+      if (!enabled) return;
+      active = true;
+      startedAt = Date.now();
+      render(text);
+      timer = setInterval(() => render(last.replace(/^[^ ]+ /, "").replace(/ · \d+(?:\.\d+)?s$/, "")), 120);
+      timer.unref?.();
+    },
+    update(text) {
+      if (!enabled) return;
+      if (!active) this.start(text);
+      else render(text);
+    },
+    succeed(text) {
+      if (!enabled) return;
+      const duration = elapsed();
+      this.stop();
+      process.stderr.write(`\r\x1b[2K✓ ${text} (${duration})\n`);
+    },
+    fail(text) {
+      if (!enabled) return;
+      const duration = elapsed();
+      this.stop();
+      process.stderr.write(`\r\x1b[2K✗ ${text} (${duration})\n`);
+    },
+    stop() {
+      if (!enabled) return;
+      if (timer) clearInterval(timer);
+      timer = undefined;
+      if (active) process.stderr.write("\r\x1b[2K");
+      active = false;
+      startedAt = 0;
+    },
+  };
+}

package/src/resume.js

@@ -1,7 +1,7 @@
 // A pending run is saved before network I/O. Persisting the acknowledged cursor
 // after each request permits replays when the response or local write is lost.
 // The server must receipt begin, chunks, sessions and complete idempotently.
-export async function resumeUpload(config, { save, request, warn = () => {} }) {
+export async function resumeUpload(config, { save, request, warn = () => {}, onProgress = () => {} }) {
   const pending = config.pendingSync;
   if (!pending || pending.version !== 1 || !Array.isArray(pending.requests)) {
     throw new Error("Invalid saved sync; preserve the config for recovery.");
@@ -9,10 +9,12 @@ export async function resumeUpload(config, { save, request, warn = () => {} }) {
   try {
     for (let index = pending.cursor; index < pending.requests.length; index += 1) {
       const { operation, payload } = pending.requests[index];
+      onProgress({ index: index + 1, total: pending.requests.length, operation });
       const response = await request(config, operation, payload, operation === "partitions" ? 60_000 : 30_000);
       warn(response);
       pending.cursor = index + 1;
       await save(config);
+      onProgress({ index: index + 1, total: pending.requests.length, operation, acknowledged: true });
     }
     // Commit local baseline and remove the journal in the same atomic write.
     const next = { ...config, ...pending.checkpoint };