usagemax 0.1.1 → 0.3.0

package/README.md

@@ -1,43 +1,117 @@
 # UsageMax CLI
 
-Connect aggregate coding-agent usage from your computer to a private UsageMax workspace.
+Connect aggregate coding-agent usage from every computer to one private UsageMax workspace.
 
 ## Quick start
 
 1. Sign in at [usagemax.com/account](https://usagemax.com/account).
 2. Choose **Link a computer** and copy the one-time command.
-3. Run it locally:
+3. Run it in each operating-system environment that contains usage history:
 
 ```bash
-bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX
+bunx usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
 ```
 
-The link code expires after ten minutes and can be used once. The CLI stores the resulting collector key in a user-only config file, then runs a one-shot sync.
+The link code expires after ten minutes and can be used once. Create a new code
+for each Mac, Windows PC, Linux computer, and WSL distribution. All linked
+collectors roll up into the same profile. When run inside WSL, UsageMax includes
+readable supported-provider homes under `/mnt/c/Users` automatically. Use the
+WSL collector as the single collector for that Windows PC instead of linking the
+same host history again from Windows.
+
+The CLI stores the resulting collector key in a user-only config file, then runs
+a one-shot full-history sync. Running it again, changing the display name, or
+relinking an installation does not create a second device: the private random
+installation identity remains stable.
 
 ## Commands
 
 ```bash
-bunx usagemax              # sync changed usage
-bunx usagemax sync         # same as above
-bunx usagemax sync --full  # inspect all available local history
-bunx usagemax link UMX-… --no-sync # link without uploading yet
-bunx usagemax status       # show link and last-sync state
-bunx usagemax doctor       # metadata-only source check; does not parse logs
-bunx usagemax doctor --deep # opt into a full local parser check
-bunx usagemax report       # open ccusage's local daily report
+bunx usagemax                       # sync changed usage
+bunx usagemax sync                  # same as above
+bunx usagemax sync --full           # reconcile all retained local history
+bunx usagemax sync --archives       # one-time compressed-history recovery
+bunx usagemax sync --dry-run --explain
+                                      # inspect the exact bounded plan; upload nothing
+bunx usagemax link UMX-… --no-sync  # link without uploading yet
+bunx usagemax status                # show link and last-sync state
+bunx usagemax doctor                # metadata-only source check
+bunx usagemax doctor --deep --json  # machine-readable retained-history audit
+bunx usagemax report                # open ccusage's local daily report
 bunx usagemax report session --breakdown
-bunx usagemax unlink       # remove the local collector key
+bunx usagemax unlink                # remove the local collector key
+bunx usagemax unlink --revoke       # disable future uploads, then remove locally
 ```
 
-UsageMax uses [ccusage](https://github.com/ccusage/ccusage) for local source detection, responsive reports, cached pricing, model breakdowns, date handling, and support for popular coding-agent CLIs. `report` passes its remaining arguments to ccusage.
+UsageMax pins [ccusage v20.0.20](https://github.com/ccusage/ccusage/releases/tag/v20.0.20)
+and supports all 16 adapters shipped in that release: 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 configured through ccusage are also discovered.
+
+The source inventory follows ccusage's environment overrides, including
+`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `OPENCODE_DATA_DIR`, `AMP_DATA_DIR`,
+`DROID_SESSIONS_DIR`, `CODEBUFF_DATA_DIR`, `HERMES_HOME`, `PI_AGENT_DIR`,
+`GOOSE_PATH_ROOT`, `OPENCLAW_DIR`, `KILO_DATA_DIR`, `KIMI_DATA_DIR`,
+`QWEN_DATA_DIR`, `COPILOT_OTEL_FILE_EXPORTER_PATH`, `GEMINI_DATA_DIR`, and
+`GROK_HOME`. It also follows XDG Claude configuration and Windows Goose storage.
+
+UsageMax also discovers Claude Desktop local-agent sessions, `.cc-mirror`,
+recognizable renamed Claude/Codex backup folders, and supported Windows homes
+from WSL. Discovery is bounded to known locations and immediate home entries;
+normal syncs do not crawl the whole disk.
+On a multi-user WSL host, automatic Windows-home discovery stays off unless
+there is exactly one provider-bearing profile; set `USAGEMAX_ADDITIONAL_HOME`
+to the intended mounted home explicitly.
 
-## Privacy and load
+If `doctor` reports compressed provider archives, run `sync --archives` once.
+Recovery extracts only safe Claude `projects/*.jsonl` members into a private
+temporary directory, performs one full deduplicated reconciliation, and removes
+the temporary files before exit. Weekly and incremental syncs never unpack
+archives.
 
-- The sync payload contains aggregate token counts, model/provider names, costs, source names, and dates.
-- It does not upload prompts, completions, source code, file contents, project paths, or provider credentials.
+Local files are only one coverage layer. Cursor, Windsurf, Aider, Continue,
+Cline, Roo Code, direct provider API traffic, hosted agents, and enterprise
+billing systems do not all expose a stable local token ledger. Capture those
+through UsageMax's native or OTLP endpoint, or through a future provider billing
+connector. UsageMax never invents usage that the source did not retain.
+
+## Privacy, correctness, and load
+
+- The sync payload contains authoritative aggregate token counts,
+  model/provider names, costs, source names, dates, coverage state, and opaque
+  SHA-256 session identities.
+- It does not upload prompts, completions, source code, file contents, project
+  paths, or provider credentials.
 - Sync is one-shot. There is no resident scanner or high-frequency polling loop.
-- After the first import, normal syncs inspect only the current and previous local day; use `sync --full` to reconcile older history.
-- The collector key is written with user-only permissions where the operating system supports them.
-- A separate private random installation ID survives collector rotation, relinking, and display-name changes. It is not a hardware fingerprint; the server stores only its SHA-256 hash. Concurrent or repeated syncs remain idempotent.
+- A metadata inventory exits without parsing logs or using the network when
+  nothing changed.
+- Normal changed syncs parse today or today plus yesterday. A bounded weekly
+  full reconciliation catches restored files, parser changes, and older logs.
+- Full history means all retained local history from 2024 onward. UsageMax
+  publishes complete source/day partitions, so decreased or removed local rows
+  correct the server-owned contribution instead of being silently retained.
+  Deleted or
+  never-persisted usage requires a provider export; no local tool can reconstruct it.
+- Source totals that cannot be assigned to a model are retained as
+  `unattributed` rather than silently discarded.
+- The collector key is written with user-only permissions where the operating
+  system supports them.
+- The package contains no shared service credential or private deployment URL.
+  It talks to the versioned `https://usagemax.com/api` contract. The random
+  per-installation write token is the only local secret; the service stores only
+  its hash and applies device binding, replay checks, payload caps, and quotas.
+- A private random installation ID survives collector rotation, relinking, and
+  display-name changes. It is not a hardware fingerprint; the server stores only
+  its SHA-256 hash. Concurrent and repeated syncs are idempotent.
+- The server, not the local checkpoint, owns the accounting baseline. A lost
+  response or interrupted run can be retried without adding the same partition twice.
+- Do not point two different installations at the same copied or network-mounted
+  log tree. Cross-installation copied-history deduplication is inherently
+  ambiguous and intentionally not guessed.
+
+Use `USAGEMAX_CONFIG_DIR` to select another config directory. Development and
+self-hosted installations may set `USAGEMAX_LINK_ENDPOINT` before linking.
 
-Use `USAGEMAX_CONFIG_DIR` to select another config directory. Development/self-hosted installations may set `USAGEMAX_LINK_ENDPOINT` before linking.
+See the [collector coverage audit](../../docs/collector-coverage-audit.md) for
+the full support matrix and known boundaries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagemax",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "license": "MIT",
   "author": "UsageMax",
@@ -18,9 +18,11 @@
     "usagemax": "src/cli.js"
   },
   "files": [
+    "src/archives.js",
     "src/cli.js",
     "src/core.js",
     "src/installation.js",
+    "src/sources.js",
     "README.md",
     "LICENSE"
   ],

package/src/archives.js

@@ -0,0 +1,86 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { ccusageHome, discoverProviderArchives } from "./sources.js";
+
+const executeFile = promisify(execFile);
+const MAX_ARCHIVE_LIST_BYTES = 100 * 1024 * 1024;
+
+function archiveFlags(filePath, mode) {
+  const compressed = /(?:\.tar\.gz|\.tgz)$/i.test(filePath);
+  return mode === "list" ? (compressed ? "-tzf" : "-tf") : (compressed ? "-xzf" : "-xf");
+}
+
+export function safeArchiveMember(value, source = "claude") {
+  const normalized = String(value || "").replaceAll("\\", "/");
+  const parts = normalized.split("/").filter((item) => item && item !== ".");
+  const providerDirectory = source === "codex"
+    ? parts.includes("sessions") || parts.includes("archived_sessions")
+    : parts.includes("projects");
+  return !normalized.startsWith("/") && !parts.includes("..") && providerDirectory && normalized.endsWith(".jsonl");
+}
+
+async function findProviderRoots(root, maxDirectories = 10_000) {
+  const claude = [];
+  const codex = [];
+  const stack = [root];
+  let visited = 0;
+  while (stack.length && visited < maxDirectories) {
+    const current = stack.pop();
+    visited += 1;
+    let children;
+    try {
+      children = await readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const child of children) {
+      if (!child.isDirectory()) continue;
+      const childPath = join(current, child.name);
+      if (child.name === "projects") claude.push(childPath);
+      else if (child.name === "sessions" || child.name === "archived_sessions") codex.push(current);
+      else stack.push(childPath);
+    }
+  }
+  return { claude, codex };
+}
+
+export async function prepareArchiveRecovery(baseEnv) {
+  const detected = await discoverProviderArchives({ env: baseEnv, home: ccusageHome(baseEnv) });
+  const archives = detected.filter((item) => /(?:\.tar(?:\.gz)?|\.tgz)$/i.test(item.path));
+  const unsupported = detected.length - archives.length;
+  if (!archives.length) return { archives: 0, cleanup: async () => undefined, env: baseEnv, unsupported };
+
+  const temporary = await mkdtemp(join(tmpdir(), "usagemax-recover-"));
+  try {
+    for (let index = 0; index < archives.length; index += 1) {
+      const archive = archives[index];
+      const destination = join(temporary, `archive-${index + 1}`);
+      await mkdir(destination, { recursive: true, mode: 0o700 });
+      const { stdout } = await executeFile("tar", [archiveFlags(archive.path, "list"), archive.path], { encoding: "utf8", maxBuffer: MAX_ARCHIVE_LIST_BYTES });
+      const members = stdout.split(/\r?\n/).filter((member) => safeArchiveMember(member, archive.source));
+      for (let offset = 0; offset < members.length; offset += 80) {
+        await executeFile("tar", [archiveFlags(archive.path, "extract"), archive.path, "-C", destination, "--", ...members.slice(offset, offset + 80)], { maxBuffer: 4 * 1024 * 1024 });
+      }
+    }
+    const roots = await findProviderRoots(temporary);
+    const existingClaude = String(baseEnv.CLAUDE_CONFIG_DIR || "").split(",").map((item) => item.trim()).filter(Boolean);
+    const existingCodex = String(baseEnv.CODEX_HOME || "").split(",").map((item) => item.trim()).filter(Boolean);
+    return {
+      archives: archives.length,
+      cleanup: async () => rm(temporary, { force: true, recursive: true }),
+      env: {
+        ...baseEnv,
+        CLAUDE_CONFIG_DIR: [...new Set([...existingClaude, ...roots.claude])].join(","),
+        CODEX_HOME: [...new Set([...existingCodex, ...roots.codex])].join(","),
+      },
+      unsupported,
+    };
+  } catch (error) {
+    await rm(temporary, { force: true, recursive: true });
+    throw error;
+  }
+}