tokenoscopy 0.0.0-stage → 0.3.0

package/dist/cli.js

@@ -0,0 +1,716 @@
+#!/usr/bin/env node
+import {
+  ALLOW_CACHE_MS,
+  GUARD_TIMEOUT_MS,
+  detectAuth,
+  detectAuthMode,
+  naturalDedupKey,
+  parseTranscript,
+  redactValue,
+  truncatePayload,
+  withRelPath
+} from "./chunk-L62TVAWB.js";
+
+// src/commands/doctor.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+
+// src/config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var DEFAULT_API_URL = "https://tokenoscopy.com";
+function configDir() {
+  return process.env.TOKENOSCOPY_CONFIG_DIR ?? join(homedir(), ".config", "tokenoscopy");
+}
+function configPath() {
+  return join(configDir(), "config.json");
+}
+function loadConfig() {
+  const envKey = process.env.TOKENOSCOPY_KEY;
+  const envUrl = process.env.TOKENOSCOPY_API_URL;
+  if (envKey) return { apiUrl: envUrl ?? DEFAULT_API_URL, key: envKey };
+  try {
+    const raw = readFileSync(configPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.key !== "string" || !parsed.key.startsWith("tok_")) return null;
+    return { apiUrl: parsed.apiUrl ?? DEFAULT_API_URL, key: parsed.key };
+  } catch {
+    return null;
+  }
+}
+function saveConfig(config) {
+  if (!existsSync(configDir())) mkdirSync(configDir(), { recursive: true, mode: 448 });
+  writeFileSync(configPath(), `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+}
+
+// src/commands/doctor.ts
+async function runDoctor() {
+  const out = (line) => process.stdout.write(`${line}
+`);
+  let failures = 0;
+  const config = loadConfig();
+  if (config) {
+    out(`\u2713 config found (${process.env.TOKENOSCOPY_KEY ? "env" : configPath()})`);
+    out(`  api: ${config.apiUrl} \xB7 key: ${config.key.slice(0, 12)}\u2026`);
+  } else {
+    out("\u2717 no config \u2014 run `npx tokenoscopy init`");
+    failures++;
+  }
+  const settingsPath = join2(homedir2(), ".claude", "settings.json");
+  if (existsSync2(settingsPath)) {
+    try {
+      const settings = JSON.parse(readFileSync2(settingsPath, "utf8"));
+      const raw = JSON.stringify(settings.hooks ?? {});
+      const hasHttp = raw.includes("/api/ingest/hook");
+      const hasFlush = raw.includes("tokenoscopy flush");
+      const hasGuard = raw.includes("tokenoscopy guard");
+      out(`${hasHttp ? "\u2713" : "\u2717"} live hooks ${hasHttp ? "installed" : "missing"}`);
+      out(`${hasFlush ? "\u2713" : "\u2717"} transcript flush ${hasFlush ? "installed" : "missing"}`);
+      out(`${hasGuard ? "\u2713" : "\u2717"} budget guard ${hasGuard ? "installed" : "missing"}`);
+      if (!hasHttp || !hasFlush) failures++;
+    } catch {
+      out(`\u2717 ${settingsPath} is not valid JSON`);
+      failures++;
+    }
+  } else {
+    out(`\u2717 no Claude Code settings at ${settingsPath}`);
+    failures++;
+  }
+  const auth = detectAuth();
+  const laneLabel = {
+    api_key: "API billing \u2014 figures are real money",
+    subscription: "Claude subscription \u2014 figures are not billed",
+    unknown: "unclassified \u2014 figures can't be called money or not"
+  }[auth.mode];
+  out(`${auth.mode === "unknown" ? "\u26A0" : "\u2713"} billing lane: ${laneLabel}`);
+  out(`  evidence: ${auth.evidence}`);
+  const projectsDir = join2(homedir2(), ".claude", "projects");
+  if (existsSync2(projectsDir)) {
+    out(`\u2713 transcript directory readable (${projectsDir})`);
+  } else {
+    out(`\u26A0 no transcript directory yet (${projectsDir}) \u2014 appears after the first session`);
+  }
+  if (config) {
+    try {
+      const res = await fetch(`${config.apiUrl}/api/health`, {
+        signal: AbortSignal.timeout(5e3)
+      });
+      out(res.ok ? "\u2713 API reachable" : `\u2717 API returned ${res.status}`);
+      if (!res.ok) failures++;
+    } catch {
+      out(`\u2717 cannot reach ${config.apiUrl}`);
+      failures++;
+    }
+    try {
+      const res = await fetch(`${config.apiUrl}/api/ingest/hook`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Tokenoscopy-Key": config.key
+        },
+        body: JSON.stringify({
+          hook_event_name: "DoctorPing",
+          session_id: "00000000-doctor-ping"
+        }),
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (res.status === 401) {
+        out("\u2717 ingest key rejected \u2014 rotate it in Settings \u2192 Ingest keys");
+        failures++;
+      } else {
+        out("\u2713 ingest key accepted");
+      }
+    } catch {
+      out("\u26A0 key check skipped (network)");
+    }
+  }
+  out(failures === 0 ? "\nAll clear \u2014 you're recording." : `
+${failures} problem(s) found.`);
+  return failures === 0 ? 0 : 1;
+}
+
+// src/commands/flush.ts
+import { readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
+
+// src/identity.ts
+import { execFileSync } from "child_process";
+import { hostname, userInfo } from "os";
+function git(args, cwd) {
+  try {
+    const out = execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: 2e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const value = out.trim();
+    return value.length > 0 ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function detectIdentity(cwd) {
+  const dir = cwd && cwd.length > 0 ? cwd : process.cwd();
+  const envEmail = process.env.TOKENOSCOPY_ACTOR_EMAIL?.trim();
+  const envName = process.env.TOKENOSCOPY_ACTOR_NAME?.trim();
+  const email = envEmail || git(["config", "--get", "user.email"], dir) || git(["config", "--global", "--get", "user.email"]);
+  let name = envName || git(["config", "--get", "user.name"], dir) || git(["config", "--global", "--get", "user.name"]);
+  if (!name) {
+    try {
+      name = userInfo().username;
+    } catch {
+      name = void 0;
+    }
+  }
+  return { email, name, machine: hostname() };
+}
+function detectRepoSlug(cwd) {
+  const dir = cwd && cwd.length > 0 ? cwd : process.cwd();
+  const remote = git(["config", "--get", "remote.origin.url"], dir);
+  if (!remote) return void 0;
+  const match = remote.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/);
+  return match?.[1];
+}
+function detectRepoRoot(cwd) {
+  const dir = cwd && cwd.length > 0 ? cwd : process.cwd();
+  return git(["rev-parse", "--show-toplevel"], dir);
+}
+function detectBranchDrift(cwd, expectedBranch) {
+  const dir = cwd && cwd.length > 0 ? cwd : process.cwd();
+  if (expectedBranch && git(["rev-parse", "--abbrev-ref", "HEAD"], dir) !== expectedBranch) {
+    return void 0;
+  }
+  const head = git(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], dir);
+  const candidates = [head, "origin/main", "origin/master"].filter(
+    (c) => typeof c === "string" && c.length > 0
+  );
+  for (const base of candidates) {
+    const counts = git(["rev-list", "--left-right", "--count", `${base}...HEAD`], dir);
+    if (!counts) continue;
+    const [behind, ahead] = counts.split(/\s+/).map(Number);
+    if (Number.isInteger(behind) && Number.isInteger(ahead)) {
+      return { base, behind, ahead };
+    }
+  }
+  return void 0;
+}
+
+// src/chunk.ts
+var CHUNK_MAX_BYTES = 35e5;
+var CHUNK_MAX_EVENTS = 5e3;
+var bytes = (v) => Buffer.byteLength(JSON.stringify(v), "utf8");
+function chunkUpload(upload, { maxBytes = CHUNK_MAX_BYTES, maxEvents = CHUNK_MAX_EVENTS } = {}) {
+  const events = upload.events.map((e) => ({
+    ...e,
+    payload: truncatePayload(e.payload)
+  }));
+  const groups = [];
+  const byKey = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    const key = naturalDedupKey(e);
+    const existing = key ? byKey.get(key) : void 0;
+    if (existing) {
+      existing.push(e);
+    } else {
+      const group = [e];
+      groups.push(group);
+      if (key) byKey.set(key, group);
+    }
+  }
+  const envelope = bytes({ ...upload, events: [] });
+  const chunks = [];
+  let current = [];
+  let size = envelope;
+  for (const group of groups) {
+    const groupBytes = group.reduce((n, e) => n + bytes(e) + 1, 0);
+    const wouldOverflow = current.length > 0 && (size + groupBytes > maxBytes || current.length + group.length > maxEvents);
+    if (wouldOverflow) {
+      chunks.push(current);
+      current = [];
+      size = envelope;
+    }
+    current.push(...group);
+    size += groupBytes;
+  }
+  if (current.length > 0 || chunks.length === 0) chunks.push(current);
+  return chunks.map((chunk) => ({ ...upload, events: chunk }));
+}
+
+// src/commands/flush.ts
+async function readStdin(timeoutMs = 3e3) {
+  if (process.stdin.isTTY) return "";
+  return await new Promise((resolve) => {
+    let data = "";
+    const timer = setTimeout(() => resolve(data), timeoutMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => data += c);
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+  });
+}
+async function runFlush(args) {
+  const config = loadConfig();
+  if (!config) {
+    process.stderr.write(
+      "tokenoscopy: not configured \u2014 run `npx tokenoscopy init`\n"
+    );
+    return 0;
+  }
+  let transcriptPath = "";
+  const flagIdx = args.indexOf("--transcript");
+  if (flagIdx >= 0) transcriptPath = args[flagIdx + 1] ?? "";
+  if (!transcriptPath) {
+    const stdin = await readStdin();
+    if (stdin) {
+      try {
+        const hook = JSON.parse(stdin);
+        transcriptPath = hook.transcript_path ?? "";
+      } catch {
+      }
+    }
+  }
+  if (!transcriptPath || !existsSync3(transcriptPath)) {
+    process.stderr.write("tokenoscopy flush: no transcript to flush\n");
+    return 0;
+  }
+  let upload;
+  try {
+    const { summary, events, warnings } = parseTranscript(
+      readFileSync3(transcriptPath, "utf8")
+    );
+    const identity = detectIdentity(summary.cwd);
+    summary.actor.machine_id = identity.machine;
+    summary.actor.email = identity.email;
+    summary.actor.name = identity.name;
+    summary.git_repo = detectRepoSlug(summary.cwd) ?? summary.git_repo;
+    summary.auth_mode = detectAuthMode();
+    const drift = detectBranchDrift(summary.cwd, summary.git_branch);
+    if (drift) {
+      summary.git_base = drift.base;
+      summary.git_behind = drift.behind;
+      summary.git_ahead = drift.ahead;
+    }
+    const root = detectRepoRoot(summary.cwd);
+    const redactedEvents = events.map((e) => {
+      const located = withRelPath(e, root);
+      return { ...located, payload: redactValue(located.payload) };
+    });
+    upload = { schema_version: 1, summary, events: redactedEvents };
+    if (warnings.length > 0) {
+      process.stderr.write(
+        `tokenoscopy: parser warnings: ${warnings.join(", ")}
+`
+      );
+    }
+  } catch (err) {
+    process.stderr.write(`tokenoscopy flush: parse failed (${String(err)})
+`);
+    return 0;
+  }
+  const chunks = chunkUpload(upload);
+  let sent = 0;
+  let inserted = 0;
+  for (const [i, chunk] of chunks.entries()) {
+    try {
+      const res = await fetch(`${config.apiUrl}/api/ingest/session`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Tokenoscopy-Key": config.key
+        },
+        body: JSON.stringify(chunk),
+        signal: AbortSignal.timeout(3e4)
+      });
+      if (!res.ok) {
+        process.stderr.write(
+          `tokenoscopy flush: upload ${i + 1}/${chunks.length} failed (${res.status})
+`
+        );
+        continue;
+      }
+      const body = await res.json();
+      sent += chunk.events.length;
+      inserted += body.inserted ?? 0;
+    } catch (err) {
+      process.stderr.write(
+        `tokenoscopy flush: network error on upload ${i + 1}/${chunks.length} (${String(err)})
+`
+      );
+    }
+  }
+  if (sent > 0) {
+    process.stderr.write(
+      `tokenoscopy: session flushed (${sent} events${chunks.length > 1 ? ` in ${chunks.length} uploads` : ""}, ${inserted} new) \xB7 $${upload.summary.estimated_cost_usd.toFixed(4)} est
+`
+    );
+  }
+  return 0;
+}
+
+// src/commands/guard.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { tmpdir } from "os";
+import { join as join3 } from "path";
+function cachePath(sessionId) {
+  const safe = sessionId.replace(/[^a-zA-Z0-9-]/g, "").slice(0, 64);
+  return join3(tmpdir(), `tokenoscopy-guard-${safe}.json`);
+}
+function readAllowCache(sessionId) {
+  try {
+    const raw = JSON.parse(readFileSync4(cachePath(sessionId), "utf8"));
+    return typeof raw.until === "number" && raw.until > Date.now();
+  } catch {
+    return false;
+  }
+}
+function writeAllowCache(sessionId) {
+  try {
+    writeFileSync2(
+      cachePath(sessionId),
+      JSON.stringify({ until: Date.now() + ALLOW_CACHE_MS })
+    );
+  } catch {
+  }
+}
+async function readStdin2(timeoutMs = 1e3) {
+  if (process.stdin.isTTY) return "";
+  return await new Promise((resolve) => {
+    let data = "";
+    const timer = setTimeout(() => resolve(data), timeoutMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => data += c);
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+  });
+}
+async function runGuard() {
+  const config = loadConfig();
+  if (!config) return 0;
+  let sessionId = "";
+  let toolName = "";
+  let cwd = "";
+  const stdin = await readStdin2();
+  if (stdin) {
+    try {
+      const hook = JSON.parse(stdin);
+      sessionId = hook.session_id ?? "";
+      toolName = hook.tool_name ?? "";
+      cwd = hook.cwd ?? "";
+    } catch {
+      return 0;
+    }
+  }
+  if (!sessionId) return 0;
+  if (readAllowCache(sessionId)) return 0;
+  const repo = cwd.split("/").filter(Boolean).pop();
+  try {
+    const res = await fetch(`${config.apiUrl}/api/guard/check`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Tokenoscopy-Key": config.key
+      },
+      body: JSON.stringify({
+        session_id: sessionId,
+        tool_name: toolName || "unknown",
+        git_repo: repo
+      }),
+      signal: AbortSignal.timeout(GUARD_TIMEOUT_MS)
+    });
+    if (!res.ok) return 0;
+    const body = await res.json();
+    if (body.decision === "allow" || !body.decision) {
+      writeAllowCache(sessionId);
+      return 0;
+    }
+    if (body.decision === "deny" || body.decision === "ask") {
+      process.stdout.write(
+        `${JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: body.decision,
+            permissionDecisionReason: body.reason ?? "Tokenoscopy budget policy"
+          }
+        })}
+`
+      );
+    }
+    return 0;
+  } catch {
+    return 0;
+  }
+}
+
+// src/commands/init.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { existsSync as existsSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync3, copyFileSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join4 } from "path";
+import { createInterface } from "readline/promises";
+var MARKER = "tokenoscopy";
+function isOurs(group) {
+  return JSON.stringify(group).toLowerCase().includes(MARKER);
+}
+function resolveInvocation() {
+  const override = process.env.TOKENOSCOPY_BIN?.trim();
+  if (override) return override;
+  try {
+    const found = execFileSync2("command", ["-v", "tokenoscopy"], {
+      encoding: "utf8",
+      shell: "/bin/sh",
+      timeout: 2e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (found) return "tokenoscopy";
+  } catch {
+  }
+  return "npx -y tokenoscopy";
+}
+function buildHookGroups(apiUrl, key) {
+  const bin = resolveInvocation();
+  const http = (name) => ({
+    hooks: [
+      {
+        type: "http",
+        url: `${apiUrl}/api/ingest/hook`,
+        headers: { "X-Tokenoscopy-Key": key },
+        async: true,
+        // marker for idempotent re-init
+        _tokenoscopy: true,
+        _event: name
+      }
+    ]
+  });
+  const cmd = (command, async, timeout) => ({
+    hooks: [
+      {
+        type: "command",
+        command,
+        ...async ? { async: true } : {},
+        ...timeout ? { timeout } : {},
+        _tokenoscopy: true
+      }
+    ]
+  });
+  return {
+    SessionStart: [http("SessionStart")],
+    UserPromptSubmit: [http("UserPromptSubmit")],
+    PostToolUse: [{ matcher: ".*", ...http("PostToolUse") }],
+    PostToolUseFailure: [http("PostToolUseFailure")],
+    SubagentStop: [http("SubagentStop")],
+    Stop: [cmd(`${bin} flush`, true)],
+    SessionEnd: [cmd(`${bin} flush`)],
+    PreToolUse: [{ matcher: "Bash|mcp__.*", ...cmd(`${bin} guard`, false, 10) }]
+  };
+}
+function mergeHooks(existing, ours) {
+  const merged = { ...existing ?? {} };
+  for (const [event, groups] of Object.entries(ours)) {
+    const kept = (merged[event] ?? []).filter((g) => !isOurs(g));
+    merged[event] = [...kept, ...groups];
+  }
+  return merged;
+}
+async function runInit(args) {
+  const flags = /* @__PURE__ */ new Map();
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--project" || a === "--print") flags.set(a, true);
+    else if (a.startsWith("--")) flags.set(a, args[++i] ?? "");
+  }
+  const apiUrl = flags.get("--url") || process.env.TOKENOSCOPY_API_URL || DEFAULT_API_URL;
+  let key = flags.get("--key") || process.env.TOKENOSCOPY_KEY || "";
+  if (!key) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    key = (await rl.question("Paste your ingest key (tok_\u2026): ")).trim();
+    rl.close();
+  }
+  if (!key.startsWith("tok_")) {
+    process.stderr.write("\u2717 That doesn't look like a Tokenoscopy ingest key (tok_\u2026).\n");
+    return 1;
+  }
+  try {
+    const res = await fetch(`${apiUrl}/api/ingest/hook`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Tokenoscopy-Key": key },
+      body: JSON.stringify({ hook_event_name: "DoctorPing", session_id: "00000000-doctor-ping" }),
+      signal: AbortSignal.timeout(8e3)
+    });
+    if (res.status === 401) {
+      process.stderr.write("\u2717 Key rejected by the API \u2014 check it in Settings \u2192 Ingest keys.\n");
+      return 1;
+    }
+  } catch {
+    process.stderr.write(`\u26A0 Could not reach ${apiUrl} \u2014 writing config anyway (doctor will re-check).
+`);
+  }
+  const config = { apiUrl, key };
+  saveConfig(config);
+  const settingsPath = flags.get("--project") ? join4(process.cwd(), ".claude", "settings.json") : join4(homedir3(), ".claude", "settings.json");
+  let settings = {};
+  if (existsSync4(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync5(settingsPath, "utf8"));
+      copyFileSync(settingsPath, `${settingsPath}.tokenoscopy-backup`);
+    } catch {
+      process.stderr.write(`\u2717 ${settingsPath} exists but isn't valid JSON \u2014 fix it first.
+`);
+      return 1;
+    }
+  }
+  settings.hooks = mergeHooks(
+    settings.hooks,
+    buildHookGroups(apiUrl, key)
+  );
+  if (flags.get("--print")) {
+    process.stdout.write(`${JSON.stringify({ hooks: settings.hooks }, null, 2)}
+`);
+    return 0;
+  }
+  const dir = join4(settingsPath, "..");
+  if (!existsSync4(dir)) {
+    const { mkdirSync: mkdirSync2 } = await import("fs");
+    mkdirSync2(dir, { recursive: true });
+  }
+  writeFileSync3(settingsPath, `${JSON.stringify(settings, null, 2)}
+`);
+  process.stderr.write(
+    [
+      "\u2713 config written",
+      `\u2713 hooks installed \u2192 ${settingsPath} (backup saved)`,
+      "\u2713 redaction on (secrets scrubbed before upload)",
+      "\u2713 recording \u2014 run any Claude Code session and watch it land in the dashboard",
+      ""
+    ].join("\n")
+  );
+  return 0;
+}
+
+// src/commands/tail.ts
+import { watch, existsSync as existsSync5, readdirSync, statSync } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join5 } from "path";
+var DEBOUNCE_MS = 3e3;
+async function runTail(args) {
+  const projectsDir = process.env.TOKENOSCOPY_PROJECTS_DIR ?? join5(homedir4(), ".claude", "projects");
+  if (!existsSync5(projectsDir)) {
+    process.stderr.write(`tokenoscopy tail: ${projectsDir} does not exist
+`);
+    return 1;
+  }
+  if (args.includes("--backfill")) {
+    const sinceIdx = args.indexOf("--since");
+    const sinceDays = sinceIdx >= 0 ? Number.parseInt(args[sinceIdx + 1] ?? "", 10) : 7;
+    const days = Number.isFinite(sinceDays) && sinceDays > 0 ? sinceDays : 7;
+    const cutoff = Date.now() - days * 24 * 3600 * 1e3;
+    let count = 0;
+    for (const dir of readdirSync(projectsDir)) {
+      const full = join5(projectsDir, dir);
+      let entries;
+      try {
+        entries = readdirSync(full);
+      } catch {
+        continue;
+      }
+      for (const f of entries) {
+        if (!f.endsWith(".jsonl")) continue;
+        const p = join5(full, f);
+        try {
+          if (statSync(p).mtimeMs >= cutoff) {
+            await runFlush(["--transcript", p]);
+            count++;
+          }
+        } catch {
+        }
+      }
+    }
+    process.stderr.write(`tokenoscopy tail: backfilled ${count} transcript(s)
+`);
+    if (!args.includes("--watch")) return 0;
+  }
+  process.stderr.write(`tokenoscopy tail: watching ${projectsDir}
+`);
+  const pending = /* @__PURE__ */ new Map();
+  watch(projectsDir, { recursive: true }, (_event, filename) => {
+    if (!filename || !filename.endsWith(".jsonl")) return;
+    const full = join5(projectsDir, filename);
+    const existing = pending.get(full);
+    if (existing) clearTimeout(existing);
+    pending.set(
+      full,
+      setTimeout(() => {
+        pending.delete(full);
+        if (existsSync5(full)) {
+          void runFlush(["--transcript", full]);
+        }
+      }, DEBOUNCE_MS)
+    );
+  });
+  await new Promise(() => {
+  });
+  return 0;
+}
+
+// src/cli.ts
+var HELP = `tokenoscopy \u2014 flight recorder & spend control for coding-agent fleets
+
+Usage: tokenoscopy <command> [options]
+
+Commands:
+  init      Wire Claude Code hooks + transcript flush to your workspace
+              --key tok_\u2026      ingest key (or TOKENOSCOPY_KEY)
+              --url https://\u2026  API base (default https://tokenoscopy.com)
+              --project        write hooks to ./.claude/settings.json (CI)
+              --print          print the hook config instead of writing
+  flush     Parse + upload the current session transcript (called by hooks)
+              --transcript <path>  flush a specific transcript file
+  guard     Budget check for PreToolUse (called by hooks; always fail-open)
+  tail      Watch ~/.claude/projects and flush transcripts as they change
+              --backfill       flush the last 7 days first
+              --since <days>   with --backfill: how far back (relabels lanes)
+              --watch          keep watching after backfill
+  doctor    Verify hook wiring, connectivity, key validity, and billing lane
+
+Docs: https://tokenoscopy.com
+`;
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  switch (command) {
+    case "init":
+      return runInit(args);
+    case "flush":
+      return runFlush(args);
+    case "guard":
+      return runGuard();
+    case "tail":
+      return runTail(args);
+    case "doctor":
+      return runDoctor();
+    case void 0:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(HELP);
+      return 0;
+    default:
+      process.stderr.write(`tokenoscopy: unknown command '${command}'
+
+${HELP}`);
+      return 1;
+  }
+}
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`tokenoscopy: ${String(err)}
+`);
+    process.exit(1);
+  }
+);