modelstat 0.0.27 → 0.0.29

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

@@ -43981,7 +43981,8 @@ var init_config2 = __esm({
         claimUrl: null,
         userEmail: null,
         defaultOrgId: null,
-        cursor: {}
+        cursor: {},
+        processingVersion: null
       }
     });
     cachedIdentity = (() => {
@@ -44073,6 +44074,19 @@ var init_config2 = __esm({
         map[path5] = v;
         store.set("cursor", map);
       },
+      /** Drop every per-file cursor so the next scan re-reads every
+       * JSONL from byte 0. Called when the local processing-pipeline
+       * version bumps (see processing-version.ts) or via the
+       * `modelstat rescan` CLI command. */
+      wipeCursors() {
+        store.set("cursor", {});
+      },
+      get processingVersion() {
+        return store.get("processingVersion");
+      },
+      setProcessingVersion(v) {
+        store.set("processingVersion", v);
+      },
       get storePath() {
         return store.path;
       }
@@ -45220,6 +45234,29 @@ var init_lock = __esm({
   }
 });
 
+// src/processing-version.ts
+var processing_version_exports = {};
+__export(processing_version_exports, {
+  PROCESSING_VERSION: () => PROCESSING_VERSION,
+  reconcileProcessingVersion: () => reconcileProcessingVersion
+});
+function reconcileProcessingVersion(state2) {
+  const stored = state2.processingVersion ?? 1;
+  if (stored >= PROCESSING_VERSION) {
+    return { changed: false, from: stored, to: PROCESSING_VERSION };
+  }
+  state2.wipeCursors();
+  state2.setProcessingVersion(PROCESSING_VERSION);
+  return { changed: true, from: stored, to: PROCESSING_VERSION };
+}
+var PROCESSING_VERSION;
+var init_processing_version = __esm({
+  "src/processing-version.ts"() {
+    "use strict";
+    PROCESSING_VERSION = 2;
+  }
+});
+
 // ../../node_modules/.pnpm/readdirp@4.1.2/node_modules/readdirp/esm/index.js
 import { stat as stat3, lstat, readdir as readdir2, realpath } from "fs/promises";
 import { Readable as Readable2 } from "stream";
@@ -47043,7 +47080,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,
@@ -47077,6 +47114,13 @@ async function runDaemon(opts = {}) {
     setPhase("error", `summariser preflight failed: ${err.message}`);
     throw err;
   }
+  const { reconcileProcessingVersion: reconcileProcessingVersion2 } = await Promise.resolve().then(() => (init_processing_version(), processing_version_exports));
+  const pv = reconcileProcessingVersion2(state);
+  if (pv.changed) {
+    console.log(
+      `[modelstat] processing pipeline v${pv.from} \u2192 v${pv.to} \u2014 wiped file cursors so every session is re-processed by the new pipeline`
+    );
+  }
   await runDiscovery();
   await runScanCycle("startup");
   const chokidar = (await Promise.resolve().then(() => (init_esm2(), esm_exports))).default;
@@ -47786,7 +47830,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();
@@ -47800,7 +47844,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();
@@ -47867,12 +47913,30 @@ async function cmdScan() {
   const { preflightSummariser: preflightSummariser2 } = await Promise.resolve().then(() => (init_pipeline2(), pipeline_exports));
   const sample = await preflightSummariser2();
   console.log(`[modelstat] summariser preflight ok: "${sample}"`);
+  const { reconcileProcessingVersion: reconcileProcessingVersion2 } = await Promise.resolve().then(() => (init_processing_version(), processing_version_exports));
+  const pv = reconcileProcessingVersion2(state);
+  if (pv.changed) {
+    console.log(
+      `[modelstat] processing pipeline v${pv.from} \u2192 v${pv.to} \u2014 wiped file cursors so every session is re-processed`
+    );
+  }
   const r = await scanAll();
   console.log();
   console.log(
     `Done: ${r.filesScanned} files scanned, ${r.filesUnchanged} unchanged, ${r.batchesUploaded} batches, ${r.eventsUploaded} events uploaded`
   );
 }
+async function cmdRescan() {
+  const { PROCESSING_VERSION: PROCESSING_VERSION2 } = await Promise.resolve().then(() => (init_processing_version(), processing_version_exports));
+  state.wipeCursors();
+  state.setProcessingVersion(PROCESSING_VERSION2);
+  console.log(
+    `[modelstat] cursors wiped \u2014 next \`modelstat scan\` (or daemon scan cycle) will re-read every JSONL from the start and re-summarise every session at processing version v${PROCESSING_VERSION2}.`
+  );
+  console.log(
+    "  If the daemon is running, kick it with: modelstat stop && modelstat start"
+  );
+}
 async function cmdWatch() {
   const { watchForever: watchForever2 } = await Promise.resolve().then(() => (init_watch(), watch_exports));
   await watchForever2();
@@ -48047,25 +48111,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 "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":
@@ -48075,25 +48133,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("  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);
   }
 }