usagemax 0.3.6 → 0.3.7

package/README.md

@@ -16,6 +16,10 @@ integrations, use the documented [OpenAPI contract](https://usagemax.com/openapi
 or the public [agent surfaces](https://usagemax.com/?mode=agent); the package
 itself is intended to be invoked as a short-lived local process.
 
+See the repository's [SDK and integration surface](../../docs/sdk-ecosystem.md)
+for the supported client matrix. UsageMax does not advertise Python or Go
+packages until they are separately reviewed and published.
+
 ## Requirements
 
 - Node.js 20 or newer
@@ -26,16 +30,24 @@ itself is intended to be invoked as a short-lived local process.
 
 ```bash
 # Create a one-use code at https://usagemax.com/account.
-bunx usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
+bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX
 
 # npm users can run the same one-shot command with npx.
-npx --yes usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
+npx --yes usagemax link UMX-XXXX-XXXX-XXXX-XXXX
 
 # Preview, then upload changed local usage.
 bunx usagemax sync --dry-run --explain
 bunx usagemax sync
 ```
 
+The CLI checks npm's `latest` dist-tag at most twice per day and never replaces
+itself silently. Run `usagemax update sync` to hand a command to the current
+release without typing `@latest`, or set `USAGEMAX_AUTO_UPDATE=1` for an
+explicit automatic handoff. Use `--no-update-check` or set
+`USAGEMAX_DISABLE_UPDATE_CHECK=1` in offline environments. Interactive
+terminals show a small stderr progress line; JSON,
+quiet, CI, and scheduled runs remain machine-readable and quiet.
+
 Agent-friendly checks can request JSON and keep the secret out of arguments and
 logs. This example only inspects local source coverage:
 
@@ -115,14 +127,15 @@ stdin; never pass it as an argument or put it in a URL:
 ```bash
 set +x
 printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
-  | bunx usagemax@latest token status \
+  | bunx usagemax token status \
       --device-id "$USAGEMAX_INSTALLATION_ID" \
       --json
 ```
 
-The `token status` command is included in CLI `0.3.6`. If the public npm tag
-does not yet contain `0.3.6`, run `node packages/cli/src/cli.js token status`
-from the UsageMax repository until that release is published.
+The `token status` command is included in CLI `0.3.7`. If a fresh environment
+still has an older npm tag, run `usagemax update token status` or
+`node packages/cli/src/cli.js token status` from this repository until the new
+package is published.
 
 The response is read-only and contains only status, type, scopes, profile/name,
 activation state, and a binding result of `unbound`, `bound`, `matched`, or
@@ -133,7 +146,7 @@ For a numeric-only result suitable for a smoke check:
 ```bash
 set +x
 printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
-  | bunx usagemax@latest token status \
+  | bunx usagemax token status \
       --device-id "$USAGEMAX_INSTALLATION_ID" --json \
   | jq -r '[.httpStatus, (if .ingestAuthorized then 1 else 0 end)] | @tsv'
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagemax",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "keywords": [
     "usagemax",
@@ -38,6 +38,8 @@
     "src/installation.js",
     "src/sources.js",
     "src/transport.js",
+    "src/progress.js",
+    "src/updates.js",
     "src/resume.js",
     "src/service.js",
     "README.md",

package/src/cli.js

@@ -13,10 +13,12 @@ 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 { 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.
@@ -24,7 +26,7 @@ process.title = "UsageMax";
 
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.3.6";
+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`;
@@ -118,15 +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");
 }
@@ -170,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`);
   }
 }
 
@@ -228,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);
@@ -253,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, {
@@ -272,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.
@@ -310,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;
@@ -320,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: {
@@ -356,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
@@ -395,6 +428,7 @@ 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`);
@@ -420,10 +454,13 @@ async function status(args = []) {
   };
   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) {
@@ -461,58 +498,84 @@ async function readTokenFromStdin() {
 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 token = await readTokenFromStdin();
+  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 });
-  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);
-  if (args.includes("--json")) process.stdout.write(`${JSON.stringify(view)}\n`);
-  else {
-    process.stdout.write("Credential format: valid (umx_ + 64 lowercase hexadecimal characters)\n");
-    printRemoteStatus(view);
+  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;
   }
 }
 
 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;
-  }
-  if (args.includes("--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`);
+  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) {
@@ -528,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();
@@ -559,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();

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 };

package/src/updates.js

@@ -0,0 +1,99 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+
+export const REGISTRY_URL = "https://registry.npmjs.org/usagemax/latest";
+export const UPDATE_CHECK_TTL_MS = 12 * 60 * 60 * 1000;
+
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+export function compareVersions(left, right) {
+  const a = String(left || "").split(".").map(Number);
+  const b = String(right || "").split(".").map(Number);
+  if (a.length !== 3 || b.length !== 3 || a.some((part) => !Number.isInteger(part)) || b.some((part) => !Number.isInteger(part))) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] > b[index] ? 1 : -1;
+  }
+  return 0;
+}
+
+function cachePath(directory) {
+  return join(directory, "update-check.json");
+}
+
+async function readCache(directory) {
+  try {
+    const value = record(JSON.parse(await readFile(cachePath(directory), "utf8")));
+    if (!value || !Number.isFinite(value.checkedAt)) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(directory, value) {
+  await mkdir(dirname(cachePath(directory)), { recursive: true, mode: 0o700 });
+  const path = cachePath(directory);
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await rename(temporary, path);
+  } finally {
+    await unlink(temporary).catch(() => undefined);
+  }
+}
+
+export async function latestVersion({ fetchImpl = fetch, timeout = 1_500 } = {}) {
+  try {
+    const response = await fetchImpl(REGISTRY_URL, {
+      headers: { accept: "application/json" },
+      cache: "no-store",
+      signal: AbortSignal.timeout(timeout),
+    });
+    if (!response.ok) return null;
+    const body = record(await response.json());
+    return /^\d+\.\d+\.\d+$/.test(body?.version || "") ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check npm at most twice a day. A failed check is deliberately non-fatal.
+ * The result contains no account data and is safe to cache locally.
+ */
+export async function checkForUpdate(directory, currentVersion, { force = false, now = Date.now(), fetchImpl = fetch } = {}) {
+  const cached = await readCache(directory);
+  if (!force && cached && now - cached.checkedAt < UPDATE_CHECK_TTL_MS) {
+    return { ...cached, newer: compareVersions(cached.latest, currentVersion) > 0 };
+  }
+  const latest = await latestVersion({ fetchImpl });
+  const result = { checkedAt: now, latest: latest || cached?.latest || null };
+  await writeCache(directory, result).catch(() => undefined);
+  return { ...result, newer: compareVersions(result.latest, currentVersion) > 0 };
+}
+
+function runner() {
+  const override = process.env.USAGEMAX_PACKAGE_RUNNER?.trim();
+  if (override) return { command: override, prefix: [] };
+  if (process.env.npm_execpath) return { command: "npm", prefix: ["exec", "--yes"] };
+  return { command: "bunx", prefix: ["--bun"] };
+}
+
+/** Re-run a command through the current npm dist-tag without requiring @latest. */
+export async function runLatest(args, { spawnImpl = spawn } = {}) {
+  const selected = runner();
+  const child = spawnImpl(selected.command, [...selected.prefix, "usagemax@latest", "--", ...args], {
+    stdio: "inherit",
+    env: { ...process.env, USAGEMAX_UPDATE_HANDOFF: "1" },
+  });
+  const code = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (status) => resolve(status ?? 1));
+  });
+  process.exitCode = code;
+  return code;
+}