tokelytics 0.3.0 → 0.3.1

package/README.md

@@ -12,6 +12,9 @@ npx tokelytics@latest login    # opens your browser to approve — no setup, no
 npx tokelytics@latest watch     # watches locally; cloud snapshot up to every 30m
 ```
 
+Keep `@latest` in install and onboarding commands. Agents older than 0.3.1
+cannot write to the hardened Firestore schema.
+
 Other commands: `sync` (one pass), `status`, `logout`.
 
 ### How login works (and why there's no API key)

package/bin/tokelytics.mjs

@@ -70,6 +70,7 @@ var TIMELINE_RETENTION_MS = 8 * 24 * 60 * 60 * 1e3;
 var SNAPSHOT_RECENT_TURNS = 32;
 var SNAPSHOT_SESSIONS = 100;
 var SNAPSHOT_RETENTION_DAYS = 120;
+var SNAPSHOT_TARGET_BYTES = 7e5;
 function emptyDashboardSnapshot(now = /* @__PURE__ */ new Date()) {
   return {
     version: 2,
@@ -96,12 +97,65 @@ function mergeDashboardSnapshot(previous, turns, limits, device, now = /* @__PUR
     next.updatedAt = now.toISOString();
   return next;
 }
+function prepareDashboardSnapshotForCloud(snapshot2, targetBytes = SNAPSHOT_TARGET_BYTES) {
+  const next = structuredClone(snapshot2);
+  next.recentTurns = next.recentTurns.map(sanitizeTurn);
+  next.sessions = next.sessions.map((session) => ({
+    ...session,
+    project: safeLabel(session.project),
+    gitBranch: safeLabel(session.gitBranch, 120)
+  }));
+  if (next.device)
+    next.device.name = safeLabel(next.device.name, 120);
+  while (snapshotBytes(next) > targetBytes && next.sessions.length > 20)
+    next.sessions.pop();
+  while (snapshotBytes(next) > targetBytes && next.rollups.length > 30)
+    next.rollups.shift();
+  while (snapshotBytes(next) > targetBytes && next.recentTurns.length > 8)
+    next.recentTurns.shift();
+  if (snapshotBytes(next) > targetBytes) {
+    next.recentTurns = next.recentTurns.map((turn) => ({ ...turn, fileReads: void 0 }));
+  }
+  if (snapshotBytes(next) > targetBytes) {
+    throw new Error(`Dashboard snapshot exceeds the ${targetBytes} byte safety limit after pruning.`);
+  }
+  return next;
+}
+function snapshotBytes(snapshot2) {
+  return new TextEncoder().encode(JSON.stringify(snapshot2)).byteLength;
+}
 function mergeRecentTurns(existing, incoming) {
   const byId = new Map(existing.map((turn) => [turn.turnId, turn]));
   for (const turn of incoming)
     byId.set(turn.turnId, turn);
   return [...byId.values()].sort((a, b) => a.ts.localeCompare(b.ts)).slice(-SNAPSHOT_RECENT_TURNS);
 }
+function sanitizeTurn(turn) {
+  return {
+    ...turn,
+    cwd: void 0,
+    project: safeLabel(turn.project),
+    gitBranch: safeLabel(turn.gitBranch, 120),
+    toolName: safeLabel(turn.toolName ?? void 0, 80) || void 0,
+    fileReads: turn.fileReads?.slice(0, 20).map((read) => ({
+      ...read,
+      path: safePath(read.path)
+    }))
+  };
+}
+function safeLabel(value, max = 160) {
+  if (!value)
+    return "";
+  return [...value].filter((character) => {
+    const code = character.charCodeAt(0);
+    return code > 31 && code !== 127;
+  }).join("").trim().slice(0, max);
+}
+function safePath(value) {
+  const normalized = value.replaceAll("\\", "/");
+  const parts = normalized.split("/").filter((part) => part && part !== "." && part !== ".." && !/^[A-Za-z]:$/.test(part));
+  return parts.slice(-3).join("/").slice(-200);
+}
 function mergeSessions(existing, turns) {
   const byId = new Map(existing.map((session) => [session.sessionId, { ...session }]));
   for (const turn of turns) {
@@ -327,12 +381,12 @@ function fileReadFromPath(rawPath, cwd, limitLines) {
     bytes = Math.min(bytes, limitLines * APPROX_BYTES_PER_LINE);
   }
   const normalizedRaw = rawPath.replace(/\\/g, "/").replace(/^\.\//, "");
-  const safePath = !rawIsAbsolute && !normalizedRaw.startsWith("../") ? normalizedRaw : displayPath(absolutePath, cwd);
+  const safePath2 = !rawIsAbsolute && !normalizedRaw.startsWith("../") ? normalizedRaw : displayPath(absolutePath, cwd);
   return {
-    path: safePath,
+    path: safePath2,
     bytes,
     estimatedTokens: bytes > 0 ? Math.ceil(bytes / BYTES_PER_TOKEN) : 0,
-    generated: isGeneratedPath(safePath)
+    generated: isGeneratedPath(safePath2)
   };
 }
 function parseJsonObject(value) {
@@ -898,7 +952,10 @@ function configDir() {
   return process.env.TOKELYTICS_HOME ?? path5.join(os3.homedir(), ".tokelytics");
 }
 var statePath = () => path5.join(configDir(), "state.json");
+var stateBackupPath = () => path5.join(configDir(), "state.backup.json");
 var credsPath = () => path5.join(configDir(), "credentials.json");
+var updatePath = () => path5.join(configDir(), "update.json");
+var watchLockPath = () => path5.join(configDir(), "watch.lock");
 async function ensureDir() {
   await fs3.mkdir(configDir(), { recursive: true });
 }
@@ -909,19 +966,31 @@ async function readJson(file) {
     return null;
   }
 }
-async function writeJson(file, value) {
+async function writeJson(file, value, backup) {
   await ensureDir();
-  await fs3.writeFile(file, JSON.stringify(value, null, 2), "utf-8");
+  const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  await fs3.writeFile(temp, JSON.stringify(value, null, 2), "utf-8");
+  try {
+    if (backup) {
+      try {
+        await fs3.copyFile(file, backup);
+      } catch {
+      }
+    }
+    await fs3.rename(temp, file);
+  } finally {
+    await fs3.rm(temp, { force: true }).catch(() => void 0);
+  }
 }
 async function loadState() {
-  const s = await readJson(statePath());
+  const s = await readJson(statePath()) ?? await readJson(stateBackupPath());
   if (s && s.deviceId && s.scan) return s;
   const fresh = { deviceId: randomUUID(), scan: emptyScanState(), publication: {} };
   await writeJson(statePath(), fresh);
   return fresh;
 }
 async function saveState(state) {
-  await writeJson(statePath(), state);
+  await writeJson(statePath(), state, stateBackupPath());
 }
 async function loadCredentials() {
   return readJson(credsPath());
@@ -939,6 +1008,49 @@ async function clearCredentials() {
   } catch {
   }
 }
+async function loadUpdateState() {
+  return await readJson(updatePath()) ?? {};
+}
+async function saveUpdateState(state) {
+  await writeJson(updatePath(), state);
+}
+async function acquireWatchLock() {
+  await ensureDir();
+  const file = watchLockPath();
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const handle = await fs3.open(file, "wx");
+      await handle.writeFile(JSON.stringify({ pid: process.pid, startedAt: (/* @__PURE__ */ new Date()).toISOString() }), "utf-8");
+      await handle.close();
+      let released = false;
+      return {
+        async release() {
+          if (released) return;
+          released = true;
+          const lock = await readJson(file);
+          if (lock?.pid === process.pid) await fs3.rm(file, { force: true });
+        }
+      };
+    } catch (error) {
+      const code = error.code;
+      if (code !== "EEXIST") throw error;
+      const lock = await readJson(file);
+      if (lock?.pid && processIsAlive(lock.pid)) {
+        throw new Error(`Tokelytics is already running (PID ${lock.pid}).`, { cause: error });
+      }
+      await fs3.rm(file, { force: true });
+    }
+  }
+  throw new Error("Could not acquire the Tokelytics watcher lock.");
+}
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
 
 // src/config.ts
 var DEFAULT_FIREBASE = {
@@ -1658,15 +1770,19 @@ var FirestoreSink = class {
   }
   async writeDashboardSnapshot(snapshot2) {
     if (!snapshot2.device?.deviceId) throw new Error("Dashboard snapshot is missing its device id.");
+    const cloudSnapshot = prepareDashboardSnapshotForCloud(snapshot2);
     await this.fs.upsert([
       {
         name: this.fs.docName("users", this.uid, "machines", snapshot2.device.deviceId),
-        fields: { ...snapshot2 }
+        fields: { ...cloudSnapshot }
       }
     ]);
   }
 };
 
+// src/version.ts
+var AGENT_VERSION = "0.3.1";
+
 // src/sync.ts
 async function runSync(connectors, sink, state, device, limitCollectors = [], options = {}) {
   const now = options.now ?? /* @__PURE__ */ new Date();
@@ -1731,6 +1847,7 @@ async function runSync(connectors, sink, state, device, limitCollectors = [], op
     publication.lastDeviceAt = now.toISOString();
   }
   const changed = turns.length > 0 || changedLimits.length > 0 || updateDevice;
+  if (changed) publication.lastLocalEventAt = now.toISOString();
   publication.dashboardDirty = Boolean(publication.dashboardDirty || changed);
   resetDailyBudget(publication, now);
   const lastCloudWrite = Date.parse(publication.lastCloudWriteAt ?? "");
@@ -1738,14 +1855,29 @@ async function runSync(connectors, sink, state, device, limitCollectors = [], op
   const hasBudget = (publication.cloudWritesToday ?? 0) < maxCloudWritesPerDay;
   let published = false;
   let publicationError;
+  dashboard.sync = {
+    agentVersion: AGENT_VERSION,
+    cloudWritesToday: publication.cloudWritesToday ?? 0,
+    maxCloudWritesPerDay,
+    localChangesPending: Boolean(publication.dashboardDirty),
+    lastLocalEventAt: publication.lastLocalEventAt,
+    lastCloudWriteAt: publication.lastCloudWriteAt
+  };
   if (publication.dashboardDirty && cloudWriteDue && hasBudget) {
     try {
+      dashboard.sync = {
+        ...dashboard.sync,
+        cloudWritesToday: (publication.cloudWritesToday ?? 0) + 1,
+        localChangesPending: false,
+        lastCloudWriteAt: now.toISOString()
+      };
       await sink.writeDashboardSnapshot(dashboard);
       publication.cloudWritesToday = (publication.cloudWritesToday ?? 0) + 1;
       publication.lastCloudWriteAt = now.toISOString();
       publication.dashboardDirty = false;
       published = true;
     } catch (error) {
+      dashboard.sync.localChangesPending = true;
       publicationError = error;
     }
   }
@@ -3705,6 +3837,40 @@ function isUsageFile(filePath) {
   return filePath.endsWith(".jsonl") || filePath.endsWith(".sqlite") || filePath.endsWith(".sqlite-wal");
 }
 
+// src/update-check.ts
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var REGISTRY_URL = "https://registry.npmjs.org/tokelytics/latest";
+async function agentUpdateMessage(force = false) {
+  try {
+    const state = await loadUpdateState();
+    const checkedAt = Date.parse(state.checkedAt ?? "");
+    let latest = state.latestVersion;
+    if (force || !Number.isFinite(checkedAt) || Date.now() - checkedAt >= CHECK_INTERVAL_MS) {
+      const response = await fetch(REGISTRY_URL, { signal: AbortSignal.timeout(5e3) });
+      if (!response.ok) return void 0;
+      const body = await response.json();
+      latest = body.version;
+      await saveUpdateState({
+        checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        latestVersion: latest
+      });
+    }
+    if (latest && compareVersions(latest, AGENT_VERSION) > 0) {
+      return `Tokelytics ${latest} is available. Update with: npm install -g tokelytics@latest`;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function compareVersions(left, right) {
+  const a = left.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const b = right.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0) ? 1 : -1;
+  }
+  return 0;
+}
+
 // src/cli.ts
 var USAGE = `Tokelytics agent
 
@@ -3727,24 +3893,39 @@ async function main(argv) {
       } catch (err) {
         console.warn(`(Couldn't register device yet \u2014 will retry on first sync: ${err.message})`);
       }
-      console.log('Done. Now run "tokelytics watch" to stream your usage.');
+      console.log('Done. Now run "npx tokelytics@latest watch" to keep your dashboard updated.');
       return 0;
     }
     case "sync": {
-      const runner = await createRunner();
-      const { processedTurns, processedLimits, byProvider } = await runner.syncOnce();
-      const detail = Object.entries(byProvider).map(([p, n]) => `${p}:${n}`).join(" ") || "none";
-      console.log(`Processed ${processedTurns} turn(s) (${detail}); refreshed ${processedLimits} usage provider(s).`);
+      const update = await agentUpdateMessage();
+      if (update) console.warn(update);
+      const lock = await acquireWatchLock();
+      try {
+        const runner = await createRunner();
+        const { processedTurns, processedLimits, byProvider } = await runner.syncOnce();
+        const detail = Object.entries(byProvider).map(([p, n]) => `${p}:${n}`).join(" ") || "none";
+        console.log(`Processed ${processedTurns} turn(s) (${detail}); refreshed ${processedLimits} usage provider(s).`);
+      } finally {
+        await lock.release();
+      }
       return 0;
     }
     case "watch": {
-      const runner = await createRunner();
-      await watch2(runner);
+      const lock = await acquireWatchLock();
+      try {
+        const update = await agentUpdateMessage();
+        if (update) console.warn(update);
+        const runner = await createRunner();
+        await watch2(runner);
+      } finally {
+        await lock.release();
+      }
       return 0;
     }
     case "status": {
       const creds = await loadCredentials();
       const state = await loadState();
+      console.log(`Agent version: ${AGENT_VERSION}`);
       if (!creds) {
         console.log('Not signed in. Run "tokelytics login".');
       } else {
@@ -3760,6 +3941,8 @@ async function main(argv) {
       } catch (err) {
         console.log(`Session needs refresh: ${err.message}`);
       }
+      const update = await agentUpdateMessage(true);
+      if (update) console.log(update);
       return 0;
     }
     case "logout": {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "tokelytics",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Tokelytics sync agent — streams local AI CLI usage logs (Claude Code, Codex) to your Tokelytics dashboard.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "tokelytics": "./bin/tokelytics.mjs"
+    "tokelytics": "bin/tokelytics.mjs"
   },
   "files": [
     "bin",