modelstat 0.0.28 → 0.0.30

package/README.md

@@ -6,47 +6,45 @@
 
 ## Install
 
-The fastest way:
+One command. Re-running it upgrades you to the newest published version (postinstall stops the running service, swaps the bundle, restarts it).
 
 ```bash
-curl -fsSL https://install.modelstat.ai | sh
+npx modelstat@latest
 ```
 
-Or via Homebrew:
+Same one-shot via Bun or pnpm:
 
 ```bash
-brew install modelstat/tap/modelstat
-modelstat connect
+bunx modelstat@latest
+pnpm dlx modelstat@latest
 ```
 
-Or via npm / pnpm / bun:
+The first run downloads the on-device summariser model (~2.7 GB Qwen3.5-4B GGUF to `~/.modelstat/models/`), pairs the device, and installs a **launchd user agent** on macOS (at `~/Library/LaunchAgents/ai.modelstat.agent.plist`) or a **systemd user unit** on Linux (at `~/.config/systemd/user/modelstat.service`). The daemon starts automatically on login and watches your AI-tool session logs in the background. The CLI exits cleanly — there's no foreground process to keep open.
 
-```bash
-npm install -g @modelstat/agent && modelstat connect
-pnpm add -g @modelstat/agent && modelstat connect
-bun add -g @modelstat/agent && modelstat connect
-```
-
-`modelstat connect` installs a **launchd user agent** on macOS (at `~/Library/LaunchAgents/ai.modelstat.agent.plist`) or a **systemd user unit** on Linux (at `~/.config/systemd/user/modelstat.service`). The daemon starts automatically on login.
-
-Requires Node 20+ (or skip Node entirely with the Homebrew route). macOS and Linux (x86_64, arm64) supported.
+Requires Node 20+. macOS and Linux (x86_64, arm64) supported.
 
 ## Commands
 
 ```bash
-modelstat connect              # pair + install background service, then exit
-modelstat status               # show pairing + service state
-modelstat paths [--json]       # print state file + log paths + API URL
-modelstat stop                 # stop and uninstall the service
-modelstat scan                 # one-shot parse + upload of local JSONL
-modelstat watch                # foreground watcher (no service install)
-modelstat discover             # report detected tool installs + identities
+npx modelstat@latest                    # install or upgrade. Default action.
+npx modelstat@latest remove             # stop and uninstall the background service
+npx modelstat@latest reinstall          # alias for the default — explicit form
+
+npx modelstat@latest status             # show pairing + service state
+npx modelstat@latest stats              # live device summary: sessions · tokens · cost
+npx modelstat@latest jobs               # pipeline queue + recent processing ledger
+npx modelstat@latest paths [--json]     # state file + log dir + API URL
+
+npx modelstat@latest scan               # one-shot parse + upload of local JSONL
+npx modelstat@latest rescan             # wipe file cursors so next scan re-reads & re-summarises everything
+npx modelstat@latest watch              # foreground watcher (no service install)
+npx modelstat@latest discover           # report detected tool installs + identities
 ```
 
 **Programmatic pairing** (used by harness skills for OpenClaw, NanoClaw, etc.):
 
 ```bash
-modelstat connect --json --no-browser
+npx modelstat@latest --json --no-browser
 ```
 
 Emits one NDJSON event per line. Schema documented at [integrations/harness-skills/modelstat-connect/README.md](https://github.com/modelstat/modelstat/tree/main/integrations/harness-skills/modelstat-connect).
@@ -72,7 +70,7 @@ To point the agent at your own modelstat API (not the hosted SaaS):
 
 ```bash
 export AGENT_API_URL=https://your-modelstat-api.example.com
-modelstat connect
+npx modelstat@latest
 ```
 
 `AGENT_API_URL` can also be set persistently via `.env` or in the systemd/launchd unit.

package/dist/cli.mjs

@@ -47031,6 +47031,26 @@ async function sendHeartbeat() {
     }
   } catch {
   }
+  writeLocalStatus(body).catch(() => void 0);
+}
+async function writeLocalStatus(snapshot) {
+  const { homedir: homedir9 } = await import("os");
+  const { join: join11 } = await import("path");
+  const { writeFile, mkdir: mkdir2, rename } = await import("fs/promises");
+  if (!lastStatusPath) {
+    const dir = join11(homedir9(), ".modelstat");
+    try {
+      await mkdir2(dir, { recursive: true });
+    } catch {
+    }
+    lastStatusPath = join11(dir, "last-status.json");
+  }
+  const tmp = `${lastStatusPath}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify({ ...snapshot, written_at: (/* @__PURE__ */ new Date()).toISOString() }));
+    await rename(tmp, lastStatusPath);
+  } catch {
+  }
 }
 async function runDiscovery() {
   const deviceId = state.deviceId;
@@ -47080,7 +47100,7 @@ function basename3(p) {
 }
 async function runDaemon(opts = {}) {
   if (!state.bearer || !state.deviceId) {
-    throw new Error("not enrolled \u2014 run `modelstat connect` first");
+    throw new Error("not enrolled \u2014 run `npx modelstat@latest` first");
   }
   const lock = acquireDaemonLock({
     agentVersion: AGENT_VERSION2,
@@ -47174,7 +47194,7 @@ async function runDaemon(opts = {}) {
   await new Promise(() => {
   });
 }
-var import_undici2, AGENT_VERSION2, HEARTBEAT_INTERVAL_MS, SCAN_INTERVAL_MS, status;
+var import_undici2, AGENT_VERSION2, HEARTBEAT_INTERVAL_MS, SCAN_INTERVAL_MS, status, lastStatusPath;
 var init_daemon = __esm({
   "src/daemon.ts"() {
     "use strict";
@@ -47214,6 +47234,7 @@ var init_daemon = __esm({
       stats: {},
       lastEventAt: null
     };
+    lastStatusPath = null;
   }
 });
 
@@ -47830,7 +47851,7 @@ async function cmdConnect(opts) {
       "the background service will retry the download on its first scan"
     );
   }
-  step("Installing background service so the agent survives reboots");
+  step("Installing/refreshing background service so the agent survives reboots");
   let serviceOk = false;
   try {
     const svc = installService();
@@ -47844,7 +47865,9 @@ async function cmdConnect(opts) {
   } catch (e) {
     emitEvent(opts, "service_install_failed", { error: e.message });
     warn(`couldn't install service: ${e.message}`);
-    warn("will run in the foreground instead \u2014 don't close this terminal");
+    warn(
+      "the agent will not run in the background \u2014 re-run after fixing the issue"
+    );
   }
   if (!opts.json) {
     const tray = trayStatus();
@@ -47987,15 +48010,34 @@ function fmtTokens(v) {
   if (n >= 1e3) return `${(n / 1e3).toFixed(0)}K`;
   return String(n);
 }
+async function readLocalStatus() {
+  try {
+    const { homedir: homedir9 } = await import("os");
+    const { join: join11 } = await import("path");
+    const { readFile } = await import("fs/promises");
+    const p = join11(homedir9(), ".modelstat", "last-status.json");
+    const txt = await readFile(p, "utf8");
+    return JSON.parse(txt);
+  } catch {
+    return null;
+  }
+}
 async function cmdStats(args) {
   const asJson = args.includes("--json");
   const claim = state.claimCode;
+  const local = await readLocalStatus();
   if (!claim) {
     if (asJson) {
-      process.stdout.write(`${JSON.stringify({ paired: false, reason: "no_claim_code" })}
-`);
+      process.stdout.write(
+        `${JSON.stringify({
+          paired: false,
+          reason: "no_claim_code",
+          local
+        })}
+`
+      );
     } else {
-      console.log("no claim code on record \u2014 run `modelstat connect` first");
+      console.log("no claim code on record \u2014 run `npx modelstat@latest` first");
     }
     return;
   }
@@ -48004,17 +48046,27 @@ async function cmdStats(args) {
     const dashboard = `${state.apiUrl.replace(/\/$/, "")}/dashboard`;
     if (asJson) {
       process.stdout.write(
-        `${JSON.stringify({ paired: true, claimed: true, dashboard })}
+        `${JSON.stringify({
+          paired: true,
+          claimed: true,
+          dashboard,
+          local
+        })}
 `
       );
     } else {
       console.log("device is claimed \u2014 live stats available at:");
       console.log(`  ${dashboard}`);
+      if (local) {
+        console.log(`local agent: ${local.status ?? "?"}${local.message ? ` \xB7 ${local.message}` : ""}`);
+        const stats = local.stats ?? {};
+        for (const [k, v] of Object.entries(stats)) console.log(`  ${k}: ${v}`);
+      }
     }
     return;
   }
   if (asJson) {
-    process.stdout.write(`${JSON.stringify(view)}
+    process.stdout.write(`${JSON.stringify({ ...view, local })}
 `);
     return;
   }
@@ -48109,27 +48161,19 @@ async function main() {
   const rest = process.argv.slice(3);
   switch (cmd) {
     case void 0:
-    case "start":
-      if (!state.bearer || !state.deviceId)
-        return cmdConnect(parseConnectOpts(rest));
-      return cmdStart(rest);
     case "connect":
       return cmdConnect(parseConnectOpts(rest));
-    case "self-register":
-      return cmdSelfRegister();
-    case "await-claim":
-      return cmdAwaitClaim();
-    case "discover":
-      return cmdDiscover();
-    case "scan":
-      return cmdScan();
-    case "rescan":
-      return cmdRescan();
-    case "watch":
-      return cmdWatch();
-    case "stop":
+    case "remove":
     case "uninstall":
+    case "stop":
       return cmdStop();
+    case "reinstall":
+      return cmdConnect(parseConnectOpts(rest));
+    // ── Internal / service entry point ─────────────────────────
+    case "_daemon":
+    case "start":
+      return cmdStart(rest);
+    // ── Diagnostics / dev one-shots ────────────────────────────
     case "status":
       return cmdStatus();
     case "stats":
@@ -48139,26 +48183,38 @@ async function main() {
     case "paths":
       cmdPaths(rest);
       return;
+    case "discover":
+      return cmdDiscover();
+    case "scan":
+      return cmdScan();
+    case "rescan":
+      return cmdRescan();
+    case "watch":
+      return cmdWatch();
+    case "self-register":
+      return cmdSelfRegister();
+    case "await-claim":
+      return cmdAwaitClaim();
     default:
-      console.log(
-        "usage: modelstat [connect|self-register|await-claim|status|stats|jobs|paths|stop|start|discover|scan|watch]"
-      );
+      console.log("usage:");
+      console.log("  npx modelstat@latest                \u2014 install or upgrade. Registers the device, installs the background service, exits.");
+      console.log("                                        flags: --json (NDJSON events on stdout), --no-browser, --fresh, -y");
+      console.log("  npx modelstat@latest remove         \u2014 stop and uninstall the background service. Keeps your identity.");
+      console.log("  npx modelstat@latest reinstall      \u2014 alias for the default. Useful when you want to be explicit.");
+      console.log();
+      console.log("Diagnostics:");
+      console.log("  npx modelstat@latest status         \u2014 show pairing + service state");
+      console.log("  npx modelstat@latest stats          \u2014 live device summary: sessions \xB7 tokens \xB7 cost (--json)");
+      console.log("  npx modelstat@latest jobs           \u2014 pipeline queue + recent processing ledger (--json)");
+      console.log("  npx modelstat@latest paths          \u2014 print state file + log dir + api URL (--json)");
+      console.log();
+      console.log("Dev / one-shots:");
+      console.log("  npx modelstat@latest scan           \u2014 one-shot parse + upload of local JSONL");
+      console.log("  npx modelstat@latest rescan         \u2014 wipe file cursors so the next scan re-reads & re-summarises everything");
+      console.log("  npx modelstat@latest watch          \u2014 continuous (chokidar) with periodic backstop");
+      console.log("  npx modelstat@latest discover       \u2014 one-shot report of installs/identities");
       console.log();
-      console.log("  (no args)       \u2014 pair if needed, then run the daemon in the foreground");
-      console.log("  connect         \u2014 self-register + install the background service; prints /d/:claim_code URL");
-      console.log("                    flags: --json (NDJSON events on stdout), --no-browser");
-      console.log("  self-register   \u2014 generate UUIDv7 + register; print claim URL and exit");
-      console.log("  await-claim     \u2014 block until a human claims this self-registered device");
-      console.log("  status          \u2014 show pairing + service state");
-      console.log("  stats           \u2014 live device summary: sessions, tokens, cost (use --json)");
-      console.log("  jobs            \u2014 pipeline queue + recent processing ledger (use --json)");
-      console.log("  paths           \u2014 print state file + log dir + api URL (use --json for machine-readable)");
-      console.log("  stop            \u2014 stop and uninstall the background service");
-      console.log("  start           \u2014 run the daemon (used by the installed service)");
-      console.log("  discover        \u2014 one-shot report of installs/identities");
-      console.log("  scan            \u2014 one-shot parse + upload of local JSONL");
-      console.log("  rescan          \u2014 wipe file cursors so next scan re-reads & re-summarises everything");
-      console.log("  watch           \u2014 continuous (chokidar) with periodic backstop");
+      console.log("Internal (called by launchd/systemd, not by humans): _daemon, start, self-register, await-claim");
       process.exit(1);
   }
 }