usagemax 0.3.2 → 0.3.3

package/README.md

@@ -124,6 +124,47 @@ It never automatically replays an old authoritative deletion against newer data.
 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:
+
+```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
+```
+
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagemax",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "license": "MIT",
   "author": "UsageMax",
@@ -25,6 +25,7 @@
     "src/sources.js",
     "src/transport.js",
     "src/resume.js",
+    "src/service.js",
     "README.md",
     "LICENSE"
   ],

package/src/cli.js

@@ -8,17 +8,19 @@ import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
+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 { intervalMinutes, manageService, runScheduledSync } from "./service.js";
 import { 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";
 
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.3.2";
+const VERSION = "0.3.3";
 const PUBLIC_API_ORIGIN = "https://usagemax.com/api";
 const DEFAULT_LINK_ENDPOINT = `${PUBLIC_API_ORIGIN}/v1/devices/link`;
 const CONFIG_FILE = "config.json";
@@ -107,6 +109,9 @@ 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("  usagemax status                  Show local link status\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("                                  Check source coverage; --deep parses full history\n");
   process.stdout.write("  usagemax report [...args]        Run a local ccusage report\n");
@@ -127,6 +132,8 @@ async function ccusageJson(config, { full = false, env } = {}) {
   const { stdout } = await executeFile(process.execPath, args, {
     encoding: "utf8",
     maxBuffer: MAX_REPORT_BYTES,
+    timeout: 10 * 60 * 1000,
+    killSignal: "SIGKILL",
     env: { ...(env || await ccusageEnvironment()), NO_COLOR: "1" },
   });
   return JSON.parse(stdout);
@@ -446,6 +453,26 @@ 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 === "service") {
+    const action = args[1] || "status";
+    const directory = option(args, "--config-dir") || configDirectory();
+    process.env.USAGEMAX_CONFIG_DIR = directory;
+    let result;
+    if (action === "run") {
+      result = await runScheduledSync(directory, () => withConfigLock(directory, () => sync(["--json"])));
+      if (result.status === "error") process.exitCode = 1;
+    } else if (action === "status") {
+      result = await manageService(action, { directory, cli: fileURLToPath(import.meta.url) });
+    } else {
+      result = await withConfigLock(directory, async () => {
+        if (action === "install" && !await readConfig()) throw new Error("Link this computer before enabling automatic sync.");
+        if (args.includes("--every") && option(args, "--every") === undefined) throw new Error("--every requires a number of minutes.");
+        return manageService(action, { directory, cli: fileURLToPath(import.meta.url), minutes: args.includes("--every") ? intervalMinutes(option(args, "--every")) : undefined });
+      });
+    }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
   if (command === "report") return report(args.slice(1));
   if (["link", "sync", "status", "doctor", "unlink"].includes(command)) {
     return withConfigLock(configDirectory(), async () => {

package/src/resume.js

@@ -48,7 +48,9 @@ export async function withConfigLock(directory, action) {
   } catch (error) {
     if (error.code !== "EEXIST") throw error;
     const owner = (await readFile(path, "utf8").catch(() => "unknown")).trim();
-    throw new Error(`Collector config is locked by PID ${/^\d+$/.test(owner) ? owner : "unknown"}. If that process has exited, remove only ${path} and rerun sync; keep config.json for resume.`);
+    const busy = new Error(`Collector config is locked by PID ${/^\d+$/.test(owner) ? owner : "unknown"}. If that process has exited, remove only ${path} and rerun sync; keep config.json for resume.`);
+    busy.code = "USAGEMAX_BUSY";
+    throw busy;
   }
   try {
     return await action();

package/src/service.js

@@ -0,0 +1,150 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { access, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const execute = promisify(execFile);
+const ENV_KEYS = ["PATH", "XDG_CONFIG_HOME", "APPDATA", "LOCALAPPDATA", "WSL_DISTRO_NAME", "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", "GEMINI_DATA_DIR", "GROK_HOME", "COPILOT_OTEL_FILE_EXPORTER_PATH", "USAGEMAX_ADDITIONAL_HOME", "USAGEMAX_WSL_USERS_DIR", "CCUSAGE_MODEL_ALIASES"];
+const xml = (value) => String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+const unitQuote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%").replaceAll("$", () => "$$")}"`;
+const windowsQuote = (value) => `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"`;
+
+export function intervalMinutes(value = 15) {
+  if (!/^\d+$/.test(String(value)) || Number(value) < 5 || Number(value) > 1440) throw new Error("--every must be an integer from 5 to 1440 minutes.");
+  return Number(value);
+}
+
+export function capturedEnvironment(env) {
+  // Never persist the whole shell environment: it can contain provider secrets.
+  return Object.fromEntries(ENV_KEYS.filter((key) => typeof env[key] === "string").map((key) => [key, env[key]]));
+}
+
+export function assertDurablePath(path) {
+  if (!isAbsolute(path) || /[\x00-\x1f]/.test(path) || /\/(?:_npx|cache|fnm_multishells)\//i.test(path.replaceAll("\\", "/"))) {
+    throw new Error("Automatic sync needs a persistent installation. Run `bun install -g usagemax`, then `usagemax service install`; do not install a scheduler from bunx/npx caches.");
+  }
+}
+
+export function servicePlan({ directory, executable, cli, minutes = 15, platform = process.platform, home = homedir(), uid = process.getuid?.(), configHome = join(home, ".config"), now = Date.now() }) {
+  minutes = intervalMinutes(minutes);
+  for (const path of [directory, executable, cli, home, configHome]) if (/[\x00-\x1f]/.test(path)) throw new Error("Scheduler paths cannot contain control characters.");
+  const id = createHash("sha256").update(directory).digest("hex").slice(0, 12);
+  const name = `com.usagemax.sync.${id}`;
+  const args = [cli, "service", "run", "--config-dir", directory];
+  const command = [executable, ...args];
+  if (platform === "darwin") {
+    const file = join(home, "Library", "LaunchAgents", `${name}.plist`);
+    const domain = `gui/${uid}`;
+    return { backend: "launchd", name, files: [[file, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict><key>Label</key><string>${name}</string>
+<key>ProgramArguments</key><array>${command.map((s) => `<string>${xml(s)}</string>`).join("")}</array>
+<key>WorkingDirectory</key><string>${xml(home)}</string>
+<key>StartInterval</key><integer>${minutes * 60 + parseInt(id.slice(0, 4), 16) % 60}</integer>
+<key>ProcessType</key><string>Background</string><key>Nice</key><integer>10</integer>
+<key>LowPriorityIO</key><true/><key>StandardOutPath</key><string>/dev/null</string>
+<key>StandardErrorPath</key><string>/dev/null</string></dict></plist>
+`]], probe: ["launchctl", ["print", `${domain}/${name}`]], install: [["launchctl", ["bootstrap", domain, file]], ["launchctl", ["enable", `${domain}/${name}`]]], uninstall: [["launchctl", ["bootout", `${domain}/${name}`]]] };
+  }
+  if (platform === "linux") {
+    const root = join(configHome, "systemd", "user");
+    return { backend: "systemd", name, files: [
+      [join(root, `${name}.service`), `[Unit]\nDescription=UsageMax incremental usage sync\n[Service]\nType=oneshot\nExecStart=${command.map(unitQuote).join(" ")}\nWorkingDirectory=${unitQuote(home)}\nNice=10\nIOSchedulingClass=idle\nTimeoutStartSec=infinity\nStandardOutput=null\nStandardError=null\n`],
+      [join(root, `${name}.timer`), `[Unit]\nDescription=UsageMax automatic sync\n[Timer]\nOnActiveSec=1m\nOnUnitInactiveSec=${minutes}m\nRandomizedDelaySec=60\nAccuracySec=30s\n[Install]\nWantedBy=timers.target\n`],
+    ], probe: ["systemctl", ["--user", "is-active", `${name}.timer`]], install: [["systemctl", ["--user", "daemon-reload"]], ["systemctl", ["--user", "enable", "--now", `${name}.timer`]]], uninstall: [["systemctl", ["--user", "disable", "--now", `${name}.timer`]]] };
+  }
+  if (platform === "win32") {
+    const file = join(directory, "service-task.xml");
+    return { backend: "task-scheduler", name, files: [[file, `<?xml version="1.0" encoding="UTF-8"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+<Triggers><TimeTrigger><Repetition><Interval>PT${minutes}M</Interval><StopAtDurationEnd>false</StopAtDurationEnd></Repetition><StartBoundary>${new Date(now + 60000).toISOString()}</StartBoundary><Enabled>true</Enabled><RandomDelay>PT1M</RandomDelay></TimeTrigger></Triggers>
+<Principals><Principal id="Author"><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
+<Settings><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy><DisallowStartIfOnBatteries>true</DisallowStartIfOnBatteries><StopIfGoingOnBatteries>false</StopIfGoingOnBatteries><StartWhenAvailable>true</StartWhenAvailable><Enabled>true</Enabled><WakeToRun>false</WakeToRun><ExecutionTimeLimit>PT0S</ExecutionTimeLimit><Priority>7</Priority></Settings>
+<Actions Context="Author"><Exec><Command>${xml(executable)}</Command><Arguments>${xml(args.map(windowsQuote).join(" "))}</Arguments><WorkingDirectory>${xml(home)}</WorkingDirectory></Exec></Actions></Task>
+`]], probe: ["schtasks.exe", ["/Query", "/TN", name, "/XML"]], install: [["schtasks.exe", ["/Create", "/TN", name, "/XML", file, "/F"]]], uninstall: [["schtasks.exe", ["/Delete", "/TN", name, "/F"]]] };
+  }
+  throw new Error("Automatic sync supports macOS, Windows, and Linux with a user systemd manager (including running WSL distributions).");
+}
+
+async function readJson(path) {
+  try { return JSON.parse(await readFile(path, "utf8")); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+async function atomicWrite(path, content) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temp, content, { mode: 0o600, flag: "wx" });
+    await rename(temp, path);
+  } finally { await unlink(temp).catch(() => {}); }
+}
+
+const runCommand = ([command, args]) => execute(command, args, { timeout: 15000, maxBuffer: 256 * 1024, windowsHide: true });
+
+export async function manageService(action, { directory, cli, minutes, env = process.env, executeCommand = runCommand, home = homedir(), platform = process.platform }) {
+  directory = resolve(directory);
+  const settingsPath = join(directory, "service.json");
+  const settings = await readJson(settingsPath);
+  const configHome = settings?.configHome || env.XDG_CONFIG_HOME || join(home, ".config");
+  const plan = servicePlan({ directory, cli, executable: process.execPath, minutes: minutes ?? settings?.minutes ?? 15, configHome, home, platform });
+  if (action === "status") {
+    let registered = false;
+    try { await executeCommand(plan.probe); registered = true; } catch { /* Not installed, inactive, or unavailable. */ }
+    return { installed: Boolean(settings), schedulerReachable: registered, backend: plan.backend, minutes: settings?.minutes ?? null, lastRun: await readJson(join(directory, "service-state.json")), hint: registered ? "Check lastRun for sync health. Windows task registration does not prove it is enabled." : "Scheduler is not active/reachable. On WSL, start the distro and enable its systemd user manager." };
+  }
+  if (action === "uninstall") {
+    if (!settings) return { installed: false };
+    // Failure is surfaced: do not claim removal while a scheduler might still run.
+    for (const command of plan.uninstall) await executeCommand(command);
+    for (const [file] of plan.files) await unlink(file).catch((error) => { if (error.code !== "ENOENT") throw error; });
+    await unlink(settingsPath);
+    if (plan.backend === "systemd") await executeCommand(["systemctl", ["--user", "daemon-reload"]]);
+    return { installed: false, retained: "Account link, usage checkpoints, and last-run status retained. An in-flight sync may finish." };
+  }
+  if (action !== "install") throw new Error("Use service install [--every 15], status, run, or uninstall.");
+  assertDurablePath(await realpath(cli));
+  assertDurablePath(await realpath(process.execPath));
+  await access(join(directory, "config.json"));
+  // Check the user manager before writing anything. WSL without systemd fails clearly.
+  if (plan.backend === "systemd") await executeCommand(["systemctl", ["--user", "show-environment"]]);
+  if (settings) {
+    let registered = false;
+    try { await executeCommand(plan.probe); registered = true; } catch { /* Missing registration can be repaired. */ }
+    if (registered) for (const command of plan.uninstall) await executeCommand(command);
+  }
+  const next = { version: 1, minutes: intervalMinutes(minutes ?? settings?.minutes ?? 15), configHome, env: capturedEnvironment(env), installedAt: new Date().toISOString() };
+  await atomicWrite(settingsPath, JSON.stringify(next));
+  for (const [file, content] of plan.files) await atomicWrite(file, content);
+  try {
+    for (const command of plan.install) await executeCommand(command);
+    await executeCommand(plan.probe);
+  } catch (error) {
+    throw new Error("Scheduler registration failed. Settings were retained for repair; rerun service install or check service status.", { cause: error });
+  }
+  return { installed: true, backend: plan.backend, minutes: next.minutes, note: "Opt-in one-shot jobs; no daemon, auto-updater, or wake-from-sleep. Reinstall after moving/upgrading the CLI or changing source paths." };
+}
+
+export async function runScheduledSync(directory, action, { now = () => Date.now(), env = process.env } = {}) {
+  const settings = await readJson(join(directory, "service.json"));
+  if (!settings) return { status: "disabled" };
+  const path = join(directory, "service-state.json");
+  const previous = await readJson(path) || {};
+  if (previous.nextAttemptAt > now()) return { status: "backoff", nextAttemptAt: previous.nextAttemptAt };
+  Object.assign(env, capturedEnvironment(settings.env || {}));
+  const start = now();
+  let state;
+  try {
+    await action();
+    state = { status: "ok", failures: 0, lastSuccessAt: new Date(now()).toISOString() };
+  } catch (error) {
+    if (error.code === "USAGEMAX_BUSY") return { status: "busy" };
+    const failures = Math.min((previous.failures || 0) + 1, 10);
+    // Save no command output, tokens, paths, or raw server error bodies.
+    state = { status: "error", failures, lastSuccessAt: previous.lastSuccessAt ?? null, nextAttemptAt: now() + Math.min(6 * 60, settings.minutes * 2 ** failures) * 60000, hint: "Run usagemax sync manually to diagnose; checkpoints are preserved." };
+  }
+  state = { ...state, attemptedAt: new Date(start).toISOString(), durationMs: now() - start };
+  await atomicWrite(path, JSON.stringify(state));
+  return state;
+}