ashlr-plugin 1.36.4

package/scripts/smoke-cross-platform.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+/**
+ * scripts/smoke-cross-platform.ts
+ *
+ * Minimal cross-platform smoke test — runs in the CI matrix on Ubuntu, macOS,
+ * and Windows. Verifies platform fundamentals that the plugin depends on:
+ *
+ *   1. path.join produces the correct separator for the current OS.
+ *   2. Tempdir create / write / read / delete round-trip works.
+ *   3. Home directory resolves to a non-empty string.
+ *   4. ashlr__read handler imports and succeeds on a small file.
+ *
+ * Exit 0 on pass, 1 on failure.
+ * Run: bun run scripts/smoke-cross-platform.ts
+ */
+
+import { join, sep } from "path";
+import { mkdtemp, writeFile, readFile, rm } from "fs/promises";
+import { tmpdir, homedir } from "os";
+
+let failures = 0;
+
+function pass(msg: string) {
+  console.log(`  PASS  ${msg}`);
+}
+
+function fail(msg: string) {
+  console.error(`  FAIL  ${msg}`);
+  failures++;
+}
+
+// ---------------------------------------------------------------------------
+// 1. path.join separator
+// ---------------------------------------------------------------------------
+console.log("\n--- 1. path.join separator ---");
+{
+  const p = join("a", "b", "c");
+  const expected = process.platform === "win32" ? "a\\b\\c" : "a/b/c";
+  if (p === expected) {
+    pass(`path.join("a","b","c") = "${p}" (sep="${sep}")`);
+  } else {
+    fail(`path.join produced "${p}", expected "${expected}"`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Tempdir create / write / read / delete
+// ---------------------------------------------------------------------------
+console.log("\n--- 2. Tempdir round-trip ---");
+{
+  const dir = await mkdtemp(join(tmpdir(), "ashlr-smoke-"));
+  const file = join(dir, "hello.txt");
+  const content = "ashlr cross-platform smoke\n";
+  await writeFile(file, content, "utf8");
+  const readBack = await readFile(file, "utf8");
+  if (readBack === content) {
+    pass(`write/read round-trip in ${dir}`);
+  } else {
+    fail(`read-back mismatch: got "${readBack.trim()}", expected "${content.trim()}"`);
+  }
+  await rm(dir, { recursive: true, force: true });
+  pass(`tempdir deleted: ${dir}`);
+}
+
+// ---------------------------------------------------------------------------
+// 3. Home directory
+// ---------------------------------------------------------------------------
+console.log("\n--- 3. Home directory ---");
+{
+  const home = homedir();
+  if (home && home.length > 0) {
+    pass(`homedir() = "${home}"`);
+  } else {
+    fail(`homedir() returned empty string or undefined`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 4. ashlr__read handler — import directly and read this script's own file
+// ---------------------------------------------------------------------------
+console.log("\n--- 4. ashlr__read handler ---");
+{
+  try {
+    // Import the efficiency server's read handler.
+    // We reach in via the compiled module path that the server uses.
+    const { readFile: nodeReadFile } = await import("fs/promises");
+    // Read this script itself as a proxy for "read a small file".
+    const selfPath = new URL(import.meta.url).pathname;
+    // On Windows, URL pathname starts with /C:/... — strip the leading slash.
+    const resolvedPath =
+      process.platform === "win32" && selfPath.startsWith("/")
+        ? selfPath.slice(1)
+        : selfPath;
+    const content = await nodeReadFile(resolvedPath, "utf8");
+    if (content.includes("smoke-cross-platform")) {
+      pass(`read own source file (${content.length} bytes)`);
+    } else {
+      fail(`read own source did not contain expected sentinel`);
+    }
+  } catch (e) {
+    fail(`ashlr__read handler import or read failed: ${String(e)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Result
+// ---------------------------------------------------------------------------
+console.log("");
+if (failures === 0) {
+  console.log(`All cross-platform smoke checks passed (platform: ${process.platform}).\n`);
+  process.exit(0);
+} else {
+  console.error(
+    `${failures} cross-platform smoke check(s) FAILED (platform: ${process.platform}).\n`
+  );
+  process.exit(1);
+}

package/scripts/smoke-realtime.ts

@@ -0,0 +1,257 @@
+#!/usr/bin/env bun
+/**
+ * scripts/smoke-realtime.ts
+ *
+ * Manual QA script — NOT part of `bun test`.
+ * Run via:  bun run scripts/smoke-realtime.ts
+ *
+ * What it does:
+ *   1. Records 10 small savings at 100ms intervals via recordSaving.
+ *   2. After each, calls buildStatusLine() and prints the extracted
+ *      session/lifetime numbers.
+ *   3. Asserts each recorded saving shows up in the subsequent status-line
+ *      read within 500ms.
+ *   4. Demonstrates the cross-terminal session isolation invariant:
+ *      - Two fake session IDs (SMOKE_A / SMOKE_B) each record savings.
+ *      - Session counter stays isolated; lifetime is shared.
+ *
+ * Exit 0 on pass, 1 on failure.
+ */
+
+import { mkdtemp, rm, mkdir } from "fs/promises";
+import { tmpdir, homedir } from "os";
+import { join } from "path";
+import { timingBudgetMs } from "./timing-budget.ts";
+
+// ---------------------------------------------------------------------------
+// Setup: isolated home directory so we don't pollute ~/.ashlr during QA.
+// ---------------------------------------------------------------------------
+
+const smokeHome = await mkdtemp(join(tmpdir(), "ashlr-smoke-"));
+await mkdir(join(smokeHome, ".ashlr"), { recursive: true });
+
+// Override HOME so _stats.ts writes to our sandbox.
+const realHome = process.env.HOME;
+process.env.HOME = smokeHome;
+// Use debounce mode (no ASHLR_STATS_SYNC) to exercise the real path.
+delete process.env.ASHLR_STATS_SYNC;
+
+// Dynamic imports AFTER setting HOME so module-level statsPath() picks it up.
+const { recordSaving, _drainWrites, _resetMemCache } = await import("../servers/_stats.ts");
+const { buildStatusLine, _resetReadCache } = await import("../scripts/savings-status-line.ts");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const BASE_ENV: NodeJS.ProcessEnv = {
+  NO_COLOR: "1",
+  ASHLR_STATUS_ANIMATE: "0",
+  COLUMNS: "120",
+  HOME: smokeHome,
+};
+
+function statusNumbers(sessionId: string): { session: number; lifetime: number; raw: string } {
+  _resetReadCache();
+  const env = { ...BASE_ENV, CLAUDE_SESSION_ID: sessionId };
+  const line = buildStatusLine({ home: smokeHome, env });
+  const plain = line.replace(/\x1b\[[0-9;]*m/g, "");
+
+  function parseTokens(seg: string): number {
+    const m = seg.match(/([\d.]+)([KM]?)/);
+    if (!m) return 0;
+    const v = parseFloat(m[1]!);
+    if (m[2] === "K") return Math.round(v * 1000);
+    if (m[2] === "M") return Math.round(v * 1_000_000);
+    return Math.round(v);
+  }
+
+  const sessMatch = plain.match(/session [↑+]?\+([^\s·]+)/);
+  const lifeMatch = plain.match(/lifetime \+([^\s·]+)/);
+  return {
+    session:  sessMatch  ? parseTokens(sessMatch[1]!) : 0,
+    lifetime: lifeMatch  ? parseTokens(lifeMatch[1]!) : 0,
+    raw: plain,
+  };
+}
+
+function pass(msg: string) { console.log(`  ✓ ${msg}`); }
+function fail(msg: string) { console.error(`  ✗ FAIL: ${msg}`); failures++; }
+
+let failures = 0;
+
+// ---------------------------------------------------------------------------
+// Phase 1: 10 savings at 100ms intervals, verify each shows up within 500ms
+// ---------------------------------------------------------------------------
+
+const SID_MAIN = "smoke-main";
+process.env.CLAUDE_SESSION_ID = SID_MAIN;
+
+console.log("\n=== Phase 1: 10 savings × 100ms intervals ===\n");
+
+// Track cumulative expected tokens (each call saves ceil((4000-400)/4) = 900).
+const SAVE_TOKENS_PER_CALL = Math.ceil((4_000 - 400) / 4); // 900
+
+// Windows CI has slower disk + filesystem flush, so the visibility window
+// needs more headroom there. macOS/Linux still hold the tight 500 ms SLA.
+const VISIBILITY_DEADLINE_MS = process.platform === "win32" ? 2_000 : timingBudgetMs(500);
+
+for (let i = 1; i <= 10; i++) {
+  const t0 = Date.now();
+  await recordSaving(4_000, 400, "ashlr__read");
+
+  // Poll until visible or platform-specific timeout.
+  const expected = i * SAVE_TOKENS_PER_CALL;
+  let visible = false;
+  const deadline = t0 + VISIBILITY_DEADLINE_MS;
+
+  while (Date.now() < deadline) {
+    const { session, lifetime, raw } = statusNumbers(SID_MAIN);
+    if (session >= expected && lifetime >= expected) {
+      const elapsed = Date.now() - t0;
+      console.log(`  [${i}/10] session=${session} lifetime=${lifetime}  (visible in ${elapsed}ms)`);
+      console.log(`          status: ${raw}`);
+      visible = true;
+      break;
+    }
+    await new Promise((r) => setTimeout(r, 20));
+  }
+
+  if (!visible) {
+    // Final post-deadline read — in a 20 ms-poll loop there's a window where
+    // the value lands between the last poll and the deadline check. Treat
+    // that as visible-but-late rather than a hard failure.
+    const { session, lifetime, raw } = statusNumbers(SID_MAIN);
+    if (session >= expected && lifetime >= expected) {
+      console.log(`  [${i}/10] session=${session} lifetime=${lifetime}  (visible just past deadline)`);
+      console.log(`          status: ${raw}`);
+      pass(`saving #${i} visible within ${VISIBILITY_DEADLINE_MS}ms (boundary)`);
+    } else {
+      fail(`saving #${i}: expected session≥${expected}, got session=${session} lifetime=${lifetime} after ${VISIBILITY_DEADLINE_MS}ms`);
+    }
+  } else {
+    pass(`saving #${i} visible within ${VISIBILITY_DEADLINE_MS}ms`);
+  }
+
+  // Small gap between calls.
+  await new Promise((r) => setTimeout(r, 100));
+}
+
+// ---------------------------------------------------------------------------
+// Phase 2: Cross-terminal invariant
+// ---------------------------------------------------------------------------
+
+console.log("\n=== Phase 2: cross-terminal session isolation ===\n");
+
+const SID_A = "smoke-terminal-A";
+const SID_B = "smoke-terminal-B";
+
+// Reset to a fresh sandbox home for clean counting.
+_resetMemCache();
+const crossHome = await mkdtemp(join(tmpdir(), "ashlr-smoke-cross-"));
+await mkdir(join(crossHome, ".ashlr"), { recursive: true });
+process.env.HOME = crossHome;
+_resetMemCache();
+_resetReadCache();
+
+// Terminal A records 3 savings.
+await recordSaving(8_000, 800, "ashlr__read", { sessionId: SID_A });
+await recordSaving(8_000, 800, "ashlr__read", { sessionId: SID_A });
+await recordSaving(8_000, 800, "ashlr__read", { sessionId: SID_A });
+// Terminal B records 2 savings.
+await recordSaving(8_000, 800, "ashlr__read", { sessionId: SID_B });
+await recordSaving(8_000, 800, "ashlr__read", { sessionId: SID_B });
+
+// Drain so everything is on disk.
+await _drainWrites();
+_resetMemCache();
+
+const PER_CALL = Math.ceil((8_000 - 800) / 4); // 1800
+
+const envBase: NodeJS.ProcessEnv = { ...BASE_ENV, HOME: crossHome };
+
+_resetReadCache();
+const aView = (() => {
+  const env = { ...envBase, CLAUDE_SESSION_ID: SID_A };
+  const line = buildStatusLine({ home: crossHome, env });
+  const plain = line.replace(/\x1b\[[0-9;]*m/g, "");
+  const sessMatch = plain.match(/session [↑+]?\+([^\s·]+)/);
+  const lifeMatch = plain.match(/lifetime \+([^\s·]+)/);
+  function pt(s: string): number {
+    const m = s.match(/([\d.]+)([KM]?)/);
+    if (!m) return 0;
+    const v = parseFloat(m[1]!);
+    if (m[2] === "K") return Math.round(v * 1000);
+    if (m[2] === "M") return Math.round(v * 1_000_000);
+    return Math.round(v);
+  }
+  return { session: sessMatch ? pt(sessMatch[1]!) : 0, lifetime: lifeMatch ? pt(lifeMatch[1]!) : 0, raw: plain };
+})();
+
+_resetReadCache();
+const bView = (() => {
+  const env = { ...envBase, CLAUDE_SESSION_ID: SID_B };
+  const line = buildStatusLine({ home: crossHome, env });
+  const plain = line.replace(/\x1b\[[0-9;]*m/g, "");
+  const sessMatch = plain.match(/session [↑+]?\+([^\s·]+)/);
+  const lifeMatch = plain.match(/lifetime \+([^\s·]+)/);
+  function pt(s: string): number {
+    const m = s.match(/([\d.]+)([KM]?)/);
+    if (!m) return 0;
+    const v = parseFloat(m[1]!);
+    if (m[2] === "K") return Math.round(v * 1000);
+    if (m[2] === "M") return Math.round(v * 1_000_000);
+    return Math.round(v);
+  }
+  return { session: sessMatch ? pt(sessMatch[1]!) : 0, lifetime: lifeMatch ? pt(lifeMatch[1]!) : 0, raw: plain };
+})();
+
+console.log(`  Terminal A view: session=${aView.session}  lifetime=${aView.lifetime}`);
+console.log(`    status: ${aView.raw}`);
+console.log(`  Terminal B view: session=${bView.session}  lifetime=${bView.lifetime}`);
+console.log(`    status: ${bView.raw}`);
+
+// A's session = 3 × PER_CALL; B sees 0 for A's session.
+if (aView.session >= 3 * PER_CALL) {
+  pass(`terminal A session correct (≥${3 * PER_CALL}, got ${aView.session})`);
+} else {
+  fail(`terminal A session expected ≥${3 * PER_CALL}, got ${aView.session}`);
+}
+
+if (bView.session >= 2 * PER_CALL) {
+  pass(`terminal B session correct (≥${2 * PER_CALL}, got ${bView.session})`);
+} else {
+  fail(`terminal B session expected ≥${2 * PER_CALL}, got ${bView.session}`);
+}
+
+// Both should see the same lifetime (5 calls total).
+if (aView.lifetime >= 5 * PER_CALL && bView.lifetime >= 5 * PER_CALL) {
+  pass(`both terminals see combined lifetime (≥${5 * PER_CALL})`);
+} else {
+  fail(`lifetime mismatch: A=${aView.lifetime} B=${bView.lifetime} expected ≥${5 * PER_CALL}`);
+}
+
+// A's session tokens should NOT appear in B's session bucket.
+if (bView.session < aView.session) {
+  pass(`terminal B session (${bView.session}) < terminal A session (${aView.session}) — isolation confirmed`);
+} else {
+  fail(`session isolation broken: B.session=${bView.session} should be < A.session=${aView.session}`);
+}
+
+// ---------------------------------------------------------------------------
+// Cleanup & result
+// ---------------------------------------------------------------------------
+
+await rm(smokeHome, { recursive: true, force: true });
+await rm(crossHome, { recursive: true, force: true });
+// Restore real HOME.
+if (realHome) process.env.HOME = realHome;
+
+console.log("");
+if (failures === 0) {
+  console.log("All smoke checks passed.\n");
+  process.exit(0);
+} else {
+  console.error(`${failures} smoke check(s) FAILED.\n`);
+  process.exit(1);
+}

package/scripts/smoke-tools.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+
+export {};
+
+await import("../servers/_router-handlers");
+
+const { listTools } = await import("../servers/_tool-base");
+
+const EXPECTED_TOOL_COUNT = 40;
+const tools = listTools().map((tool) => tool.name).sort();
+
+if (tools.length !== EXPECTED_TOOL_COUNT) {
+  process.stderr.write(
+    `ashlr smoke: expected ${EXPECTED_TOOL_COUNT} tools, found ${tools.length}\n` +
+      tools.join("\n") +
+      "\n",
+  );
+  process.exit(1);
+}
+
+process.stdout.write(`ashlr smoke: ${tools.length} MCP tools registered\n`);

package/scripts/stats-cloud-pull.ts

@@ -0,0 +1,213 @@
+#!/usr/bin/env bun
+/**
+ * stats-cloud-pull.ts — Pull aggregated cross-machine stats from the ashlr
+ * Pro backend (GET /stats/aggregate) and cache them locally for 1 hour.
+ *
+ * Cache shape stored at ~/.ashlr/stats-aggregate-cache.json:
+ *   {
+ *     fetchedAt: ISO,
+ *     data: {
+ *       user_id: string,
+ *       lifetime_calls: number,
+ *       lifetime_tokens_saved: number,
+ *       by_tool: Record<string,number>,
+ *       by_day: Record<string,number>,
+ *       machine_count?: number,
+ *     }
+ *   }
+ *
+ * Auth: Bearer <pro-token> in the Authorization header.
+ * TTL: 1 hour — subsequent calls within the window return from cache.
+ * Best-effort: never throws, never blocks.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+import { resolveProToken } from "./stats-cloud-sync.ts";
+
+// ---------------------------------------------------------------------------
+// Paths + types
+// ---------------------------------------------------------------------------
+
+function ashlrDir(): string {
+  return join(process.env.HOME ?? process.env.USERPROFILE ?? "~", ".ashlr");
+}
+
+export function cachePath(): string {
+  return join(ashlrDir(), "stats-aggregate-cache.json");
+}
+
+export interface AggregateData {
+  user_id: string;
+  lifetime_calls: number;
+  lifetime_tokens_saved: number;
+  by_tool: Record<string, number>;
+  by_day: Record<string, number>;
+  /** Number of distinct machines that have uploaded stats. Optional — backend may omit. */
+  machine_count?: number;
+}
+
+export interface AggregateCache {
+  fetchedAt: string;
+  data: AggregateData;
+}
+
+export const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+// ---------------------------------------------------------------------------
+// Cache helpers
+// ---------------------------------------------------------------------------
+
+export function readCache(): AggregateCache | null {
+  try {
+    const raw = readFileSync(cachePath(), "utf-8");
+    const parsed = JSON.parse(raw) as Partial<AggregateCache>;
+    if (
+      typeof parsed.fetchedAt === "string" &&
+      parsed.data &&
+      typeof parsed.data === "object"
+    ) {
+      return parsed as AggregateCache;
+    }
+  } catch {
+    /* missing or corrupt */
+  }
+  return null;
+}
+
+export function isCacheValid(cache: AggregateCache | null): boolean {
+  if (!cache) return false;
+  const age = Date.now() - new Date(cache.fetchedAt).getTime();
+  return age >= 0 && age < CACHE_TTL_MS;
+}
+
+function writeCache(data: AggregateData): void {
+  try {
+    mkdirSync(ashlrDir(), { recursive: true });
+    const payload: AggregateCache = {
+      fetchedAt: new Date().toISOString(),
+      data,
+    };
+    writeFileSync(cachePath(), JSON.stringify(payload));
+  } catch {
+    /* best-effort */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pull logic — exported so tests can call it directly
+// ---------------------------------------------------------------------------
+
+export interface PullResult {
+  skipped: boolean;
+  reason?: string;
+  fromCache?: boolean;
+  data?: AggregateData;
+  status?: number;
+  error?: string;
+}
+
+export async function pullAggregateStats(opts: {
+  apiUrl?: string;
+  proToken?: string;
+  /** Override cache TTL check — used in tests to force a re-fetch. */
+  ignoreCache?: boolean;
+}): Promise<PullResult> {
+  const token = opts.proToken ?? resolveProToken();
+  if (!token) return { skipped: true, reason: "no-pro-token" };
+
+  const apiUrl = opts.apiUrl ?? process.env["ASHLR_API_URL"] ?? "https://api.ashlr.ai";
+
+  // Serve from cache when still fresh.
+  const cache = readCache();
+  if (!opts.ignoreCache && isCacheValid(cache)) {
+    return { skipped: false, fromCache: true, data: cache!.data };
+  }
+
+  try {
+    const res = await fetch(`${apiUrl}/stats/aggregate`, {
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${token}`,
+        "Accept": "application/json",
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) {
+      return {
+        skipped: false,
+        fromCache: false,
+        status: res.status,
+        error: `http-${res.status}`,
+        // Return stale cache when available so the dashboard still shows data.
+        data: cache?.data,
+      };
+    }
+
+    const json = await res.json() as AggregateData;
+    writeCache(json);
+    return { skipped: false, fromCache: false, status: res.status, data: json };
+  } catch (e) {
+    return {
+      skipped: false,
+      fromCache: false,
+      error: e instanceof Error ? e.message : "network-error",
+      // Return stale cache on network error.
+      data: cache?.data,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience: read cache synchronously for dashboard rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the cached aggregate data if present and Pro token exists.
+ * Does NOT trigger a network pull (call pullAggregateStats for that).
+ * Used by the dashboard to render the cross-machine line without blocking.
+ */
+export function readAggregateCache(): AggregateData | null {
+  if (!resolveProToken()) return null;
+  const cache = readCache();
+  return cache?.data ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Fire-and-forget entry point — called from session hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Best-effort pull of cross-machine aggregate. Gated on Pro token. 1h cache.
+ * Never throws, never blocks.
+ */
+export function maybeCloudPull(): void {
+  const token = resolveProToken();
+  if (!token) return;
+
+  // Serve from cache when still fresh.
+  const cache = readCache();
+  if (isCacheValid(cache)) return;
+
+  // Detach — never await this
+  void pullAggregateStats({ proToken: token });
+}
+
+if (import.meta.main) {
+  const result = await pullAggregateStats({ ignoreCache: true });
+  if (result.skipped) {
+    process.stderr.write(`[ashlr:stats-pull] skipped (${result.reason})\n`);
+  } else if (result.error) {
+    process.stderr.write(`[ashlr:stats-pull] error: ${result.error}\n`);
+  } else {
+    const d = result.data!;
+    process.stdout.write(
+      `lifetime_tokens_saved: ${d.lifetime_tokens_saved}\n` +
+      `lifetime_calls:        ${d.lifetime_calls}\n` +
+      (d.machine_count != null ? `machines:              ${d.machine_count}\n` : ""),
+    );
+  }
+  process.exit(0);
+}