usagemax 0.3.7 → 0.3.9

package/README.md

@@ -40,10 +40,12 @@ 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
+The CLI checks npm's `latest` dist-tag at most twice per day. Run
+`usagemax update` to update a global installation through the package manager
+that launched it (Bun or npm). Add `--check` for a read-only check, or
+`--json` for automation. A command suffix such as `usagemax update sync` hands
+that command to the newest release without typing `@latest`. 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.
@@ -53,7 +55,7 @@ logs. This example only inspects local source coverage:
 
 ```bash
 set +x
-bunx usagemax doctor --deep --json | jq '{complete, sources: [.sources[] | {name, status}]}'
+bunx usagemax doctor --deep --json | jq '{complete: .inventoryComplete, sources: .detectedSources}'
 ```
 
 The JSON shape is intended for local automation; unsupported or unavailable
@@ -81,6 +83,9 @@ usagemax token status            Diagnose a key piped on stdin
 usagemax service install        Opt into periodic OS checkpoints
 usagemax service status|run|uninstall
 usagemax unlink [--revoke]       Remove local credentials
+usagemax update                  Update the global CLI through Bun or npm
+usagemax update --check          Check without installing
+usagemax update sync             Run sync through the newest CLI release
 ```
 
 Useful options:
@@ -92,11 +97,15 @@ bunx usagemax sync --restart              # restart an expired saved upload
 bunx usagemax status --remote --json      # remote check; secret is never printed
 bunx usagemax doctor --deep --json        # parse and audit retained history
 bunx usagemax link UMX-… --no-sync        # link without uploading yet
+bunx usagemax --version --json             # print CLI and ccusage versions
+bunx usagemax update --json                # update and return machine-readable status
+bunx usagemax update --check --json        # check without installing
+bunx usagemax unlink --json                # safe automation result; no secret output
 ```
 
 ## Sources and coverage
 
-UsageMax pins [ccusage v20.0.20](https://github.com/ccusage/ccusage/releases/tag/v20.0.20)
+UsageMax pins [ccusage v20.0.23](https://github.com/ccusage/ccusage/releases/tag/v20.0.23)
 and supports its 16 adapters: Amp, Claude Code, Codebuff, Codex, GitHub Copilot
 CLI, Factory Droid, Gemini CLI, Goose, Grok Build, Hermes, Kilo Code, Kimi CLI,
 OpenClaw, OpenCode, Pi, and Qwen Code. Named Pi-format stores are discovered as
@@ -132,7 +141,7 @@ printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
       --json
 ```
 
-The `token status` command is included in CLI `0.3.7`. If a fresh environment
+The `token status` command is included in CLI `0.3.9`. 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagemax",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "keywords": [
     "usagemax",
@@ -57,6 +57,6 @@
     "prepublishOnly": "npm test"
   },
   "dependencies": {
-    "ccusage": "20.0.20"
+    "ccusage": "20.0.23"
   }
 }

package/src/cli.js

@@ -18,7 +18,7 @@ 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";
+import { checkForUpdate, packageManagerFor, runLatest, updateGlobal } 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.
@@ -26,7 +26,7 @@ process.title = "UsageMax";
 
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.3.7";
+const VERSION = "0.3.9";
 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`;
@@ -121,6 +121,7 @@ function help() {
   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("           [--json]                  Emit one JSON object per link/sync phase\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");
@@ -131,9 +132,12 @@ function help() {
   process.stdout.write("  usagemax service status|run|uninstall\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 update                  Update the global CLI through Bun or npm\n");
+  process.stdout.write("           [--check] [--json]       Check only or emit machine-readable status\n");
+  process.stdout.write("  usagemax update <command args>   Run a command through 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");
+  process.stdout.write("           [--json]                  Emit machine-readable unlink status\n");
 }
 
 function ccusageCliPath() {
@@ -182,6 +186,7 @@ function warnVersion(body) {
 async function link(args) {
   const code = normalizeLinkCode(args[0]);
   if (!code) throw new Error("Paste the one-use UMX link code shown at usagemax.com/account.");
+  const json = args.includes("--json");
   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.");
@@ -223,13 +228,17 @@ async function link(args) {
   };
   await writeConfig(config);
   warnVersion(body);
-  process.stdout.write(`Linked ${savedName} to ${config.profileHandle ? `@${config.profileHandle}` : "UsageMax"}.\n`);
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ linked: true, version: VERSION, deviceName: savedName, profileHandle: config.profileHandle || null, profileUrl: config.profileUrl, deviceIdConfigured: true, sync: args.includes("--no-sync") ? "skipped" : "started" })}\n`);
+  } else {
+    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");
+    if (!json) process.stdout.write("No usage was uploaded. Run `bunx usagemax sync --full` when you are ready.\n");
     return;
   }
-  process.stdout.write("Running the first one-shot sync…\n");
-  await sync(["--full"], config);
+  if (!json) process.stdout.write("Running the first one-shot sync…\n");
+  await sync(["--full", ...(json ? ["--json"] : [])], config);
 }
 
 async function sync(args, suppliedConfig) {
@@ -254,6 +263,7 @@ async function sync(args, suppliedConfig) {
 }
 
 async function syncPrepared(args, suppliedConfig, recovery, progress = createProgress({ noProgress: true })) {
+  const startedAt = Date.now();
   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);
@@ -269,7 +279,7 @@ async function syncPrepared(args, suppliedConfig, recovery, progress = createPro
   if (config.pendingSync) {
     progress.update("Resuming the saved upload checkpoint…");
     if (dryRun) {
-      const result = { ...config.pendingSync.result, dryRun: true, pendingRunId: config.pendingSync.runId };
+      const result = { ...config.pendingSync.result, dryRun: true, pendingRunId: config.pendingSync.runId, cliVersion: VERSION, ccusageVersion: CCUSAGE_VERSION, durationMs: Date.now() - startedAt };
       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;
@@ -280,9 +290,10 @@ async function syncPrepared(args, suppliedConfig, recovery, progress = createPro
       warn: warnVersion,
       onProgress: ({ index, total, operation, acknowledged }) => progress.update(`${acknowledged ? "Uploaded" : "Uploading"} ${index}/${total} · ${operation}`),
     });
+    const summary = { ...result, cliVersion: VERSION, ccusageVersion: CCUSAGE_VERSION, durationMs: Date.now() - startedAt };
     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;
+    process.stdout.write(json ? `${JSON.stringify(summary)}\n` : "Resumed and completed the saved sync. Run sync again to scan newer local changes.\n");
+    return summary;
   }
   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"}.`);
@@ -292,9 +303,12 @@ async function syncPrepared(args, suppliedConfig, recovery, progress = createPro
     today, now: Date.now(), inventoryVersion: SOURCE_INVENTORY_VERSION, requestedFull, requestedArchives,
   });
   if (skip) {
-    const result = { accepted: 0, changedRows: 0, sessions: 0, sources: inventory.sources, corrections: 0, scanned: false, full: false, coverage: config.lastCoverage || "partial" };
+    const result = { accepted: 0, changedRows: 0, sessions: 0, sources: inventory.sources, corrections: 0, scanned: false, full: false, coverage: config.lastCoverage || "partial", skipReason: "inventory_unchanged", cliVersion: VERSION, ccusageVersion: CCUSAGE_VERSION, durationMs: Date.now() - startedAt };
     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");
+    else {
+      process.stdout.write("Already up to date. Local usage files have not changed; no logs were parsed or uploaded.\n");
+      if (explain) process.stdout.write(`Skipped because the source inventory fingerprint is unchanged; coverage remains ${result.coverage}.\n`);
+    }
     progress.succeed("No local changes; upload skipped.");
     return;
   }
@@ -334,6 +348,8 @@ async function syncPrepared(args, suppliedConfig, recovery, progress = createPro
     coverage: authoritative ? "complete" : "partial",
     coverageReason: "Parser does not certify complete source/day coverage; decreases and deletions are protected.",
     range: { from: days[0], to: days.at(-1) },
+    cliVersion: VERSION,
+    ccusageVersion: CCUSAGE_VERSION,
   };
   progress.update(`Prepared ${partitions.length} usage chunk${partitions.length === 1 ? "" : "s"} and ${sessions.length} session identifier${sessions.length === 1 ? "" : "s"}.`);
   if (requestedArchives) {
@@ -341,6 +357,7 @@ async function syncPrepared(args, suppliedConfig, recovery, progress = createPro
     result.unsupportedArchives = recovery.unsupported;
   }
   if (dryRun) {
+    result.durationMs = Date.now() - startedAt;
     if (json) process.stdout.write(`${JSON.stringify({ ...result, dryRun: true })}\n`);
     else {
       process.stdout.write(`Dry run: ${partitions.length} partition(s), ${result.changedRows} changed row(s), ${sessions.length} private session identifiers, no upload.\n`);
@@ -389,6 +406,7 @@ async function syncPrepared(args, suppliedConfig, recovery, progress = createPro
     warn: warnVersion,
     onProgress: ({ index, total, operation, acknowledged }) => progress.update(`${acknowledged ? "Uploaded" : "Uploading"} ${index}/${total} · ${operation}`),
   });
+  result.durationMs = Date.now() - startedAt;
   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 {
@@ -431,7 +449,7 @@ async function status(args = []) {
   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`);
+      process.stdout.write(`${JSON.stringify({ linked: false, version: VERSION, ccusageVersion: CCUSAGE_VERSION, configPath: configPath(), remote: remote ? { status: "not_linked" } : undefined })}\n`);
       return;
     }
     process.stdout.write("Not linked. Open https://usagemax.com/account to connect this computer.\n");
@@ -444,12 +462,18 @@ async function status(args = []) {
   }
   const local = {
     linked: true,
+    version: VERSION,
+    ccusageVersion: CCUSAGE_VERSION,
+    configPath: configPath(),
     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,
+    coverage: config.lastCoverage || null,
+    knownSources: Array.isArray(config.knownSources) ? config.knownSources : [],
+    snapshotRows: Object.keys(config.snapshots || {}).length,
     profileUrl: config.profileUrl || "https://usagemax.com/account",
   };
   let remoteView;
@@ -473,8 +497,11 @@ async function status(args = []) {
     return;
   }
   process.stdout.write(`Linked: ${config.deviceName || deviceLabel()}${config.profileHandle ? ` → @${config.profileHandle}` : ""}\n`);
+  process.stdout.write(`CLI: ${VERSION} · ccusage ${CCUSAGE_VERSION}\n`);
   process.stdout.write(`Last sync: ${config.lastSyncAt || "never"}\n`);
   process.stdout.write(`Last full reconciliation: ${config.lastFullSyncAt || "never"}\n`);
+  process.stdout.write(`Coverage: ${config.lastCoverage || "unknown"} · ${Object.keys(config.snapshots || {}).length} checkpoint rows\n`);
+  if (Array.isArray(config.knownSources) && config.knownSources.length) process.stdout.write(`Known sources: ${config.knownSources.join(", ")}\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);
@@ -538,6 +565,9 @@ async function doctor(args = []) {
     const archives = await discoverProviderArchives({ env, home: ccusageHome(env) });
     const homes = String(env.USAGEMAX_DISCOVERED_HOMES || ccusageHome(env)).split(",").filter(Boolean);
     const result = {
+      cliVersion: VERSION,
+      ccusageVersion: CCUSAGE_VERSION,
+      configPath: configPath(),
       linked: Boolean(config),
       homes,
       detectedSources: inventory.sources,
@@ -592,23 +622,46 @@ async function report(args) {
 }
 
 async function update(args = []) {
+  const json = args.includes("--json");
+  const checkOnly = args.includes("--check") || args.includes("--no-install");
+  const commandArgs = args.filter((arg) => !["--check", "--no-install", "--json"].includes(arg));
+  const handoffArgs = commandArgs.length ? [...commandArgs, ...(json ? ["--json"] : [])] : [];
   const check = await checkForUpdate(configDirectory(), VERSION, { force: true });
   if (!check.latest) {
-    process.stdout.write(`UsageMax CLI ${VERSION} · update check unavailable.\n`);
+    const result = { version: VERSION, latest: null, newer: false, status: "unavailable" };
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${VERSION} · update check unavailable.\n`);
     return;
   }
   if (!check.newer) {
-    process.stdout.write(`UsageMax CLI ${VERSION} is current.\n`);
+    const result = { version: VERSION, latest: check.latest, newer: false, status: "current" };
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${VERSION} is current.\n`);
+    return;
+  }
+  if (handoffArgs.length) {
+    const result = { version: VERSION, latest: check.latest, newer: true, status: "available", command: `usagemax update ${commandArgs.join(" ")}` };
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${check.latest} is available (current ${VERSION}).\n`);
+    if (!json) process.stdout.write(`Launching UsageMax ${check.latest}…\n`);
+    return runLatest(handoffArgs);
+  }
+  const manager = packageManagerFor({ cliPath: process.argv[1], runtime: process.versions, env: process.env });
+  const installCommand = manager === "bun" ? "bun add --global usagemax@latest" : "npm install --global usagemax@latest";
+  const available = { version: VERSION, latest: check.latest, newer: true, status: "available", manager, installCommand };
+  if (checkOnly) {
+    process.stdout.write(json ? `${JSON.stringify(available)}\n` : `UsageMax CLI ${check.latest} is available (current ${VERSION}). Run \`${installCommand}\`.\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");
+  if (!json) process.stdout.write(`Updating UsageMax ${VERSION} → ${check.latest} via ${manager}…\n`);
+  try {
+    await updateGlobal({ latest: check.latest, manager, quiet: json });
+  } catch (error) {
+    const result = { ...available, status: "failed", error: error instanceof Error ? error.message : String(error) };
+    if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
+    else process.stderr.write(`UsageMax update failed: ${result.error}\n`);
+    process.exitCode = 1;
     return;
   }
-  process.stdout.write(`Launching UsageMax ${check.latest}…\n`);
-  return runLatest(commandArgs);
+  const result = { ...available, status: "updated", installedVersion: check.latest };
+  process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI is now ${check.latest}.\n`);
 }
 
 async function maybeUpdate(command, args) {
@@ -629,11 +682,13 @@ async function maybeUpdate(command, args) {
 async function removeLink(args = []) {
   const path = configPath();
   const config = await readConfig();
+  const json = args.includes("--json");
   if (!config) {
-    process.stdout.write("This computer is not linked.\n");
+    process.stdout.write(json ? `${JSON.stringify({ unlinked: false, reason: "not_linked" })}\n` : "This computer is not linked.\n");
     return;
   }
-  if (args.includes("--revoke")) {
+  const revoked = args.includes("--revoke");
+  if (revoked) {
     const endpoint = validHttpsUrl(config.revokeUrl, { allowLocalhost: true });
     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, {
@@ -647,16 +702,20 @@ async function removeLink(args = []) {
     if (!response.ok) throw new Error("UsageMax could not revoke this collector. It remains linked locally.");
   }
   await unlink(path);
-  process.stdout.write(args.includes("--revoke")
-    ? "Revoked this collector and removed its local key. Existing usage totals were retained.\n"
-    : "Removed the local UsageMax collector key. This computer's private installation identity was retained so relinking cannot duplicate its usage. Revoke the collector in your account if this computer is no longer trusted.\n");
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ unlinked: true, revoked, retainedInstallationIdentity: true })}\n`);
+  } else {
+    process.stdout.write(revoked
+      ? "Revoked this collector and removed its local key. Existing usage totals were retained.\n"
+      : "Removed the local UsageMax collector key. This computer's private installation identity was retained so relinking cannot duplicate its usage. Revoke the collector in your account if this computer is no longer trusted.\n");
+  }
 }
 
 async function main() {
   const args = process.argv.slice(2);
   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 (["--version", "-v"].includes(command)) return process.stdout.write(args.includes("--json") ? `${JSON.stringify({ version: VERSION, ccusageVersion: CCUSAGE_VERSION })}\n` : `${VERSION}\n`);
   if (command === "update") return update(args.slice(1));
   if (await maybeUpdate(command, args)) return;
   if (command === "service") {

package/src/sources.js

@@ -3,7 +3,7 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 
-export const CCUSAGE_VERSION = "20.0.20";
+export const CCUSAGE_VERSION = "20.0.23";
 export const SOURCE_INVENTORY_VERSION = 3;
 export const SUPPORTED_SOURCES = [
   "amp",

package/src/updates.js

@@ -83,6 +83,43 @@ function runner() {
   return { command: "bunx", prefix: ["--bun"] };
 }
 
+/**
+ * Pick the package manager that owns the current invocation. Bun's global and
+ * ephemeral package paths are explicit; npm remains the safe default for a
+ * normal Node installation. The override is useful for managed environments
+ * where the executable is wrapped by a fleet-specific package manager.
+ */
+export function packageManagerFor({ cliPath = process.argv[1], runtime = process.versions, env = process.env } = {}) {
+  const override = String(env.USAGEMAX_PACKAGE_MANAGER || "").trim().toLowerCase();
+  if (override === "bun" || override === "npm") return override;
+  const normalizedPath = String(cliPath || "").replaceAll("\\", "/");
+  if (normalizedPath.includes("/.bun/install/") || runtime?.bun) return "bun";
+  if (env.npm_execpath || String(env.npm_config_user_agent || "").startsWith("npm/")) return "npm";
+  return "npm";
+}
+
+/** Install the current public release into the user's global package scope. */
+export async function updateGlobal({ latest = "latest", manager = packageManagerFor(), spawnImpl = spawn, env = process.env, quiet = false, platform = process.platform } = {}) {
+  if (manager !== "bun" && manager !== "npm") throw new Error(`Unsupported package manager: ${manager}`);
+  if (!/^\d+\.\d+\.\d+$/.test(String(latest)) && latest !== "latest") throw new Error("Invalid UsageMax release version.");
+  const command = manager === "bun" ? (platform === "win32" ? "bun.exe" : "bun") : (platform === "win32" ? "npm.cmd" : "npm");
+  const args = manager === "bun"
+    ? ["add", "--global", `usagemax@${latest}`]
+    : ["install", "--global", `usagemax@${latest}`];
+  const child = spawnImpl(command, args, {
+    stdio: quiet ? ["ignore", "pipe", "pipe"] : "inherit",
+    env: { ...env, NPM_CONFIG_UPDATE_NOTIFIER: "false" },
+  });
+  return new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (status) => {
+      const code = status ?? 1;
+      if (code === 0) resolve({ manager, command, args });
+      else reject(Object.assign(new Error(`${command} ${args.join(" ")} exited with code ${code}.`), { code: "USAGEMAX_UPDATE_FAILED", exitCode: code }));
+    });
+  });
+}
+
 /** Re-run a command through the current npm dist-tag without requiring @latest. */
 export async function runLatest(args, { spawnImpl = spawn } = {}) {
   const selected = runner();