usagemax 0.3.3 → 0.3.7

package/README.md

@@ -1,200 +1,231 @@
 # UsageMax CLI
 
-Connect aggregate coding-agent usage from every computer to one private UsageMax workspace.
+Connect the AI usage history on a computer to one private UsageMax workspace.
+The CLI is deliberately short-lived: it scans locally, uploads bounded
+aggregates, and exits.
+
+[UsageMax](https://usagemax.com) · [Account](https://usagemax.com/account) ·
+[CLI documentation](https://usagemax.com/cli.md) ·
+[API contract](https://usagemax.com/openapi.json) ·
+[npm package](https://www.npmjs.com/package/usagemax) ·
+[source repository](https://github.com/SYMBaiEX/usagemax/tree/main/packages/cli)
+
+This package is the open-source `usagemax` command-line collector. It is not a
+JavaScript or Python SDK and does not expose an import API. For programmatic
+integrations, use the documented [OpenAPI contract](https://usagemax.com/openapi.json)
+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
+- Bun or npm
+- A UsageMax account and one link code per computer or WSL distribution
 
 ## 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 in each operating-system environment that contains usage history:
+```bash
+# Create a one-use code at https://usagemax.com/account.
+bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX
+
+# npm users can run the same one-shot command with npx.
+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:
 
 ```bash
-bunx usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
+set +x
+bunx usagemax doctor --deep --json | jq '{complete, sources: [.sources[] | {name, status}]}'
 ```
 
-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 JSON shape is intended for local automation; unsupported or unavailable
+sources remain explicitly reported rather than being inferred.
+
+The link code expires after ten minutes and is consumed once. The account-side
+computer name is retained. Pass `--name "Work laptop"` only when the current
+CLI should explicitly override it.
 
-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.
+Each installation gets a stable random ID and a new write-only collector key.
+Relinking or renaming that installation rotates the key without creating a
+second device. Do not link two installations to the same copied or
+network-mounted log tree; cross-installation duplicate history is ambiguous.
 
 ## Commands
 
+```text
+usagemax                         Sync changed local usage
+usagemax link <code> [options]   Link and sync a computer
+usagemax sync [options]          Reconcile local usage once
+usagemax status                  Show local link state
+usagemax doctor                  Check discovered sources
+usagemax report [ccusage args]   Run a local ccusage report
+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
+```
+
+Useful options:
+
 ```bash
-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 --revoke       # disable future uploads, then remove locally
+bunx usagemax sync --full                 # all retained local history
+bunx usagemax sync --archives             # one-time compressed-history recovery
+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
 ```
 
+## Sources and coverage
+
 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.
-
-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.
-
-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
-
-Interrupted uploads resume with `bunx usagemax sync`. Server upload runs expire
-after 30 idle days. If the server reports an expired run, use `sync --restart`:
-this preserves the last committed checkpoint and performs a fresh full scan.
-It never automatically replays an old authoritative deletion against newer data.
-
-- The sync payload contains 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.
-- A successful previous parse with a complete, unchanged metadata inventory skips
-  parsing and uploading again that day. Inventory stability is independent of
-  deletion authority; a no-change result retains the previous partial coverage
-  label. New sources, date rollover, explicit full/archive requests and weekly
-  reconciliation still trigger the appropriate scan.
-- Normal changed syncs parse today or today plus yesterday. A bounded weekly
-  full reconciliation catches restored files, parser changes, and older logs.
-- Full history scans retained local history from 2024 onward. Inventory success
-  does not prove every file parsed. Until the parser certifies source/day coverage,
-  uploads are marked partial and any row with a decreasing counter retains its
-  entire previous vector. This includes explicit zeros and missing sources.
-  Older checkpoints survive incremental windows. Authoritative corrections remain
-  supported by the planner but are not claimed by this parser integration.
-  Deleted or never-persisted usage requires a provider export.
-- 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. A local config lock prevents overlapping commands from
-  overwriting pending runs; server receipts make repeated uploads 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.
-
-## Optional automatic sync
-
-Automatic sync is **off by default**. Install a persistent CLI first (a bunx/npx
-cache can disappear), link the computer if needed, then opt in:
+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
+well.
+
+The collector follows the supported provider environment overrides and bounded
+home locations. It recognizes Claude Desktop sessions, `.cc-mirror`, renamed
+Claude/Codex backup folders, and supported Windows homes from WSL. In WSL, use
+one collector for the Windows provider homes it can read instead of linking the
+same history again from Windows.
+
+Full scans catalog retained history from 2024 onward. `sync --archives` safely
+extracts supported Claude JSONL members into a private temporary directory and
+removes them after reconciliation. Normal runs do not crawl the whole disk or
+unpack archives.
+
+Cursor, Windsurf, Aider, Continue, Cline, Roo Code, hosted agents, and direct
+provider API traffic may not leave a stable local token ledger. Use UsageMax's
+native or OTLP/HTTP JSON contract, or a provider billing export, when local
+evidence is unavailable. Unsupported usage is never guessed.
+
+## Safe collector diagnostics
+
+An advanced key from **Advanced · custom telemetry collector** is a
+`umx_` prefix followed by 64 lowercase hexadecimal characters. Pipe it through
+stdin; never pass it as an argument or put it in a URL:
+
+```bash
+set +x
+printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
+  | bunx usagemax token status \
+      --device-id "$USAGEMAX_INSTALLATION_ID" \
+      --json
+```
+
+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
+`mismatch`. It never returns the token, hash, or raw authorized UUID.
+
+For a numeric-only result suitable for a smoke check:
+
+```bash
+set +x
+printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
+  | bunx usagemax token status \
+      --device-id "$USAGEMAX_INSTALLATION_ID" --json \
+  | jq -r '[.httpStatus, (if .ingestAuthorized then 1 else 0 end)] | @tsv'
+```
+
+`200 1` is active and ingestion-authorized. `200 0` is recognized but blocked;
+inspect `status` and `scopeStatus` in the unfiltered JSON. `409 0` is a device
+binding mismatch. `401 0` means the format/key was rejected.
+
+New advanced keys are active immediately and need no activation or propagation.
+They bind on their first valid write. Linked CLI keys are bound during the link
+exchange. A `401` means the key format is invalid or the key is unknown,
+revoked, disabled, or from another deployment. A `409` means the supplied
+installation does not match. A recognized key missing `telemetry:write` has
+`status: scope_missing`, `scopeStatus: missing_telemetry_write`, and
+`ingestAuthorized: false`.
+
+For a write-path smoke check, the root README includes a `curl` request that
+sends one `agent_state` event with all token counters and `costMicros` set to
+zero. It is observability-only: `agent_state` does not update accounting, and
+the probe may bind an otherwise unbound advanced key.
+
+## Privacy and resource use
+
+The CLI uploads aggregate token counters, provider/model names, source names,
+dates, cost provenance, coverage state, and opaque SHA-256 session identities.
+It never uploads prompts, completions, source code, file contents, project
+paths, tool payloads, or provider credentials.
+
+Every sync is one-shot. A complete unchanged inventory can skip parsing and
+uploading; date rollover, new sources, a weekly reconciliation, `--full`, or
+`--archives` triggers the appropriate bounded scan. Decreases and deletions are
+protected while coverage is incomplete.
+
+Optional scheduling invokes the same process at low priority:
 
 ```bash
 bun install -g usagemax
 usagemax service install                 # approximately every 15 minutes
-usagemax service install --every 30      # change interval; 5–1440 minutes
-usagemax service status                  # scheduler reachability + last result
-usagemax service run                     # run now, respecting failure backoff
-usagemax service uninstall               # stop future jobs; retain account/data
+usagemax service install --every 30      # 5–1440 minutes
+usagemax service status
+usagemax service uninstall
 ```
 
-Uses a user LaunchAgent on macOS, a user systemd timer on Linux/WSL, and Task
-Scheduler on Windows. No admin/root access, resident daemon, file watcher,
-automatic package updates, or package downloads per run. Each job runs the normal
-incremental sync and exits. No-change runs skip parsing/uploading when the source
-inventory is complete and unchanged. The metadata inventory still costs disk I/O;
-an active or first/full-history scan costs more. This is periodic, not live telemetry.
-
-Schedules are spread by up to a minute. macOS/Linux jobs have reduced CPU/I/O
-priority. Windows jobs require a signed-in user and defer starting on battery.
-Jobs do not wake a sleeping computer. Linux needs a running systemd user manager;
-WSL must already be running with systemd enabled. UsageMax does not enable linger
-or keep a WSL distro alive. Missed intervals are not replayed as a backlog.
-
-The existing collector lock prevents overlapping uploads. Failures back off
-exponentially (up to six hours); manually running `usagemax sync` is available for
-diagnosis without waiting. `service-state.json` retains only the latest bounded
-status, timestamps, duration, and failure count, not raw logs or credentials.
-If a process was forcibly killed, inspect the PID reported by `sync` before
-removing its stale `collector.lock`; never delete `config.json` to retry.
-
-Re-run `service install` after upgrading/moving the CLI or changing source-path
-environment variables. Only an explicit allowlist of discovery settings is saved,
-not your shell's secrets. Jobs run from your home directory; repository-local
-`.ccusage/ccusage.json` configuration is not automatically used. Keep the runtime
-and global CLI installed. `service uninstall` leaves existing usage, link credentials,
-checkpoints, and last-run status intact; an in-flight sync may finish.
-
-## Interrupted uploads and protocol 0.3.1
-
-Before uploading, the CLI saves the exact run, ordered request payloads and next
-checkpoint in the private config. `sync` resumes this journal before scanning new
-data. Local snapshots advance only after completion is acknowledged. A resumed
-command finishes the saved scan; run `sync` again to collect subsequent changes.
-`sync --dry-run` reports pending work without uploading. Do not delete config.json
-to retry a failed upload. A successful relink or unlink replaces/removes the local
-journal along with its credential.
-
-Network failures, malformed success responses, HTTP 429 and 5xx get at most five
-attempts per request with exponential jitter. Retry-After seconds and HTTP dates
-are honored up to 60 seconds; longer waits stop with an instruction to retry later.
-Only completion's `snapshot_run_incomplete` HTTP 409 is retried, because server
-cleanup can still be pending. Authentication, validation and other conflicts fail
-with an actionable message and retain the journal. JSON `accepted` is null for
-uploads because lost responses/replays cannot reliably reconstruct that count;
-`changedRows` is the local planned count, not a server accounting receipt.
-
-Each sorted source/day is sent as ordered chunks of at most 100 rows. Each has a
-unique partitionId, zero-based chunkIndex and shared chunkCount. The payload hash
-covers `{source, day, complete, pricingVersion, chunkIndex, chunkCount, rows}` in
-that order. `partitionCount` counts transmitted chunks. The server must accept
-this protocol, receipt replays, and finish omitted-row cleanup before completing
-an authoritative run.
-
-An abrupt process kill can leave `collector.lock` in the config directory. The
-next command reports the owner PID and exact path. Confirm that process has exited
-before removing only that lock file, then rerun sync. Never remove an active lock
-or the saved config to recover. Normal completion and handled failures release it.
-
-See the [collector coverage audit](../../docs/collector-coverage-audit.md) for
-the full support matrix and known boundaries.
+The scheduler uses a user LaunchAgent on macOS, a user systemd timer on
+Linux/WSL, and Task Scheduler on Windows. It does not install a resident
+watcher, wake a sleeping computer, download packages per run, or replay missed
+intervals. Failures back off for up to six hours and the collector lock prevents
+overlapping syncs.
+
+## Recovery and checkpoints
+
+Uploads are idempotent and resumable. Before network I/O, the CLI saves a
+bounded journal containing the current run, ordered operations, and next
+checkpoint in the user-only config directory. If a process or network request
+fails, rerun:
+
+```bash
+usagemax sync
+```
+
+An expired run can be restarted with `sync --restart`; already accepted usage
+remains safe. Do not delete `config.json` to retry a failed upload. See the
+[operations runbook](https://github.com/SYMBaiEX/usagemax/blob/main/docs/operations-runbook.md)
+for recovery guidance.
+
+## Development
+
+From the repository root:
+
+```bash
+bun install
+bun run --cwd packages/cli test
+bun run --cwd packages/cli pack:check  # dry-run; lifecycle scripts disabled
+```
+
+`pack:check` only inspects the local archive shape. It does not publish, contact
+the npm registry, or establish that any registry tag contains this version.
+
+The package is MIT-licensed. See the included [LICENSE](LICENSE), the
+repository [LICENSE](https://github.com/SYMBaiEX/usagemax/blob/main/LICENSE),
+[security policy](https://github.com/SYMBaiEX/usagemax/blob/main/SECURITY.md),
+and [contributing guide](https://github.com/SYMBaiEX/usagemax/blob/main/CONTRIBUTING.md).

package/package.json

@@ -1,7 +1,21 @@
 {
   "name": "usagemax",
-  "version": "0.3.3",
+  "version": "0.3.7",
   "description": "Link local coding-agent usage to your UsageMax profile",
+  "keywords": [
+    "usagemax",
+    "ai-usage",
+    "usage-analytics",
+    "coding-agents",
+    "agent-usage",
+    "telemetry",
+    "observability",
+    "usage",
+    "ccusage",
+    "claude-code",
+    "codex",
+    "privacy"
+  ],
   "license": "MIT",
   "author": "UsageMax",
   "homepage": "https://usagemax.com",
@@ -24,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",
@@ -37,7 +53,7 @@
   },
   "scripts": {
     "test": "node --test src/*.test.js",
-    "pack:check": "npm pack --dry-run",
+    "pack:check": "npm pack --dry-run --ignore-scripts",
     "prepublishOnly": "npm test"
   },
   "dependencies": {