zozul-cli 0.1.0

package/src/parser/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Types representing the JSONL session file format that Claude Code writes to:
+ * ~/.claude/projects/<encoded-path>/sessions/<session-uuid>.jsonl
+ *
+ * Each line is one JSON object. The first line is typically a summary.
+ * Subsequent lines are user/assistant messages with full content.
+ */
+
+export interface ContentBlock {
+  type: string;
+  text?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  tool_use_id?: string;
+  content?: string | ContentBlock[];
+}
+
+export interface UsageInfo {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+}
+
+export interface MessagePayload {
+  role: string;
+  content: string | ContentBlock[];
+  model?: string;
+  usage?: UsageInfo;
+}
+
+export interface SessionEntry {
+  type: string;
+  uuid?: string;
+  parentUuid?: string;
+  timestamp?: string;
+  sessionId?: string;
+  cwd?: string;
+  version?: string;
+  message?: MessagePayload;
+  requestId?: string;
+  costUSD?: number;
+  durationMs?: number;
+  isSidechain?: boolean;
+  sourceToolAssistantUUID?: string;
+
+  // Summary-specific fields
+  summary?: string;
+  leafUuid?: string;
+  numLeaves?: number;
+}
+
+export interface ParsedSession {
+  sessionId: string;
+  projectPath: string | null;
+  startedAt: string;
+  endedAt: string | null;
+  model: string | null;
+  turns: ParsedTurn[];
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCacheReadTokens: number;
+  totalCacheCreationTokens: number;
+  totalCostUsd: number;
+  totalDurationMs: number;
+}
+
+export interface ParsedTurn {
+  turnIndex: number;
+  role: string;
+  timestamp: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  costUsd: number;
+  durationMs: number;
+  model: string | null;
+  contentText: string;
+  toolCalls: ToolCallInfo[];
+  isRealUser: boolean;
+}
+
+export interface ToolCallInfo {
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  toolResult?: string;
+}

package/src/parser/watcher.ts

@@ -0,0 +1,116 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { SessionRepo } from "../storage/repo.js";
+import { ingestSessionFile } from "./ingest.js";
+import { discoverSessionFiles } from "./jsonl.js";
+
+const PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
+const DEBOUNCE_MS = 500;
+
+export interface WatcherOptions {
+  repo: SessionRepo;
+  verbose?: boolean;
+  /** Re-ingest all existing JSONL files on startup to catch up on missed sessions. Default true. */
+  catchUp?: boolean;
+}
+
+/**
+ * Watch ~/.claude/projects for JSONL session file changes and ingest them
+ * into the database as they are written. Returns a stop function.
+ *
+ * On startup, performs an initial catch-up pass so that sessions written
+ * while zozul was not running are immediately available.
+ */
+export async function watchSessionFiles(opts: WatcherOptions): Promise<() => void> {
+  const { repo, verbose } = opts;
+  const catchUp = opts.catchUp ?? true;
+
+  // ── Initial catch-up pass ──
+  if (catchUp) {
+    const files = discoverSessionFiles();
+    let caught = 0;
+    for (const { filePath, projectPath } of files) {
+      try {
+        await ingestSessionFile(repo, filePath, projectPath);
+        caught++;
+      } catch {
+        // Ignore parse errors on individual files
+      }
+    }
+    if (verbose && caught > 0) {
+      process.stderr.write(`[watcher] catch-up: ingested ${caught} session file(s)\n`);
+    }
+  }
+
+  if (!fs.existsSync(PROJECTS_DIR)) {
+    if (verbose) {
+      process.stderr.write(`[watcher] ${PROJECTS_DIR} not found, watching skipped\n`);
+    }
+    return () => {};
+  }
+
+  // ── Per-file debounce ──
+  const timers = new Map<string, NodeJS.Timeout>();
+
+  function scheduleIngest(filePath: string) {
+    const existing = timers.get(filePath);
+    if (existing) clearTimeout(existing);
+
+    timers.set(filePath, setTimeout(async () => {
+      timers.delete(filePath);
+      try {
+        const projectPath = decodeProjectPath(filePath);
+        await ingestSessionFile(repo, filePath, projectPath ?? undefined);
+        if (verbose) {
+          process.stderr.write(`[watcher] ingested: ${filePath}\n`);
+        }
+      } catch (err) {
+        if (verbose) {
+          process.stderr.write(`[watcher] ingest failed (${filePath}): ${err}\n`);
+        }
+      }
+    }, DEBOUNCE_MS));
+  }
+
+  // ── fs.watch with recursive ──
+  // recursive: true uses FSEvents on macOS and ReadDirectoryChangesW on Windows.
+  const watcher = fs.watch(PROJECTS_DIR, { recursive: true }, (_event, filename) => {
+    if (!filename) return;
+    if (!filename.endsWith(".jsonl")) return;
+
+    // filename is relative to PROJECTS_DIR on macOS/Windows
+    const filePath = path.join(PROJECTS_DIR, filename);
+
+    // Only act if the file actually exists (ignore delete events)
+    if (!fs.existsSync(filePath)) return;
+
+    scheduleIngest(filePath);
+  });
+
+  watcher.on("error", (err) => {
+    if (verbose) process.stderr.write(`[watcher] error: ${err}\n`);
+  });
+
+  if (verbose) {
+    process.stderr.write(`[watcher] watching ${PROJECTS_DIR}\n`);
+  }
+
+  return () => {
+    watcher.close();
+    for (const t of timers.values()) clearTimeout(t);
+    timers.clear();
+  };
+}
+
+/**
+ * Extract the decoded project path from an absolute JSONL file path.
+ * ~/.claude/projects/<encoded>/<uuid>.jsonl
+ * where <encoded> has "/" replaced with "-".
+ */
+function decodeProjectPath(filePath: string): string | null {
+  // Match project dir directly containing the UUID file
+  const match = filePath.match(/projects\/([^/]+)\/[0-9a-f-]{36}\.jsonl$/i);
+  if (!match) return null;
+  return match[1].replace(/-/g, "/");
+}

package/src/pricing/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Claude model pricing per million tokens.
+ * Cache creation uses 5-minute TTL pricing (the default for Claude Code).
+ */
+interface ModelPricing {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheCreation: number;
+}
+
+// Prices per million tokens
+const PRICING: Record<string, ModelPricing> = {
+  "claude-opus-4-6":           { input: 5.00,  output: 25.00, cacheRead: 0.50, cacheCreation: 6.25 },
+  "claude-sonnet-4-6":         { input: 3.00,  output: 15.00, cacheRead: 0.30, cacheCreation: 3.75 },
+  "claude-sonnet-4-5-20250514":{ input: 3.00,  output: 15.00, cacheRead: 0.30, cacheCreation: 3.75 },
+  "claude-haiku-4-5-20251001": { input: 1.00,  output: 5.00,  cacheRead: 0.10, cacheCreation: 1.25 },
+  "claude-3-5-haiku-20241022": { input: 0.80,  output: 4.00,  cacheRead: 0.08, cacheCreation: 1.00 },
+};
+
+function findPricing(model: string): ModelPricing | null {
+  if (PRICING[model]) return PRICING[model];
+  // Fuzzy match: try prefix matching for versioned model names
+  for (const [key, pricing] of Object.entries(PRICING)) {
+    if (model.startsWith(key) || key.startsWith(model)) return pricing;
+  }
+  // Match by family name
+  if (model.includes("opus")) return PRICING["claude-opus-4-6"];
+  if (model.includes("sonnet")) return PRICING["claude-sonnet-4-6"];
+  if (model.includes("haiku")) return PRICING["claude-haiku-4-5-20251001"];
+  return null;
+}
+
+export function computeTurnCost(
+  model: string | null,
+  inputTokens: number,
+  outputTokens: number,
+  cacheReadTokens: number,
+  cacheCreationTokens: number,
+): number {
+  if (!model) return 0;
+  const pricing = findPricing(model);
+  if (!pricing) return 0;
+
+  return (
+    (inputTokens * pricing.input) / 1_000_000 +
+    (outputTokens * pricing.output) / 1_000_000 +
+    (cacheReadTokens * pricing.cacheRead) / 1_000_000 +
+    (cacheCreationTokens * pricing.cacheCreation) / 1_000_000
+  );
+}

package/src/service/index.ts

@@ -0,0 +1,272 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execSync } from "node:child_process";
+
+const LABEL = "com.zozul.serve";
+const PLIST_PATH = path.join(os.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+const SYSTEMD_DIR = path.join(os.homedir(), ".config", "systemd", "user");
+const SYSTEMD_PATH = path.join(SYSTEMD_DIR, "zozul.service");
+const LOG_PATH = path.join(os.homedir(), ".zozul", "zozul.log");
+
+export interface ServiceInstallOptions {
+  port: number;
+  dbPath?: string;
+}
+
+export interface ServiceResult {
+  platform: "macos" | "linux" | "unsupported";
+  servicePath: string;
+  alreadyRunning: boolean;
+}
+
+/**
+ * Install and immediately start zozul as a background service.
+ * Uses launchd on macOS, systemd --user on Linux.
+ */
+export function installService(opts: ServiceInstallOptions): ServiceResult {
+  const platform = detectPlatform();
+  if (platform === "unsupported") {
+    throw new Error(`Service install is not supported on ${process.platform}. Run 'zozul serve' manually.`);
+  }
+
+  // Build env vars to bake into the service so it doesn't depend on .env
+  const env: Record<string, string> = {
+    ZOZUL_PORT: String(opts.port),
+  };
+  if (opts.dbPath) env.ZOZUL_DB_PATH = opts.dbPath;
+  if (process.env.ZOZUL_API_URL) env.ZOZUL_API_URL = process.env.ZOZUL_API_URL;
+  if (process.env.ZOZUL_API_KEY) env.ZOZUL_API_KEY = process.env.ZOZUL_API_KEY;
+  if (process.env.ZOZUL_VERBOSE) env.ZOZUL_VERBOSE = process.env.ZOZUL_VERBOSE;
+
+  if (platform === "macos") {
+    return installLaunchd(env);
+  } else {
+    return installSystemd(env);
+  }
+}
+
+/**
+ * Stop and remove the zozul background service.
+ */
+export function uninstallService(): { removed: boolean; platform: "macos" | "linux" | "unsupported" } {
+  const platform = detectPlatform();
+
+  if (platform === "macos") {
+    let removed = false;
+    if (fs.existsSync(PLIST_PATH)) {
+      try {
+        const uid = os.userInfo().uid;
+        execSync(`launchctl bootout gui/${uid}/${LABEL}`, { stdio: "ignore" });
+      } catch {
+        // Not loaded — that's fine
+      }
+      fs.unlinkSync(PLIST_PATH);
+      removed = true;
+    }
+    return { removed, platform };
+  }
+
+  if (platform === "linux") {
+    let removed = false;
+    if (fs.existsSync(SYSTEMD_PATH)) {
+      try {
+        execSync("systemctl --user disable --now zozul", { stdio: "ignore" });
+      } catch {
+        // Not enabled — that's fine
+      }
+      fs.unlinkSync(SYSTEMD_PATH);
+      try {
+        execSync("systemctl --user daemon-reload", { stdio: "ignore" });
+      } catch { /* ignore */ }
+      removed = true;
+    }
+    return { removed, platform };
+  }
+
+  return { removed: false, platform: "unsupported" };
+}
+
+/**
+ * Restart the running service in-place (kills and relaunches the current process).
+ * Throws if the service is not installed.
+ */
+export function restartService(): void {
+  const platform = detectPlatform();
+
+  if (platform === "macos") {
+    if (!fs.existsSync(PLIST_PATH)) throw new Error("Service is not installed. Run 'zozul install --service' first.");
+    const uid = os.userInfo().uid;
+    execSync(`launchctl kickstart -k gui/${uid}/${LABEL}`, { stdio: "ignore" });
+    return;
+  }
+
+  if (platform === "linux") {
+    if (!fs.existsSync(SYSTEMD_PATH)) throw new Error("Service is not installed. Run 'zozul install --service' first.");
+    execSync("systemctl --user restart zozul", { stdio: "ignore" });
+    return;
+  }
+
+  throw new Error("Service restart is not supported on this platform.");
+}
+
+/**
+ * Returns a human-readable status string for the running service.
+ */
+export function serviceStatus(): string {
+  const platform = detectPlatform();
+
+  if (platform === "macos") {
+    if (!fs.existsSync(PLIST_PATH)) return "not installed";
+    try {
+      const uid = os.userInfo().uid;
+      const out = execSync(`launchctl print gui/${uid}/${LABEL} 2>&1`, { encoding: "utf-8" });
+      const stateMatch = out.match(/state = (.+)/);
+      const state = stateMatch?.[1]?.trim() ?? "unknown";
+      const pidMatch = out.match(/pid = (\d+)/);
+      if (pidMatch) return `running (pid ${pidMatch[1]})`;
+      if (state === "running") return "running";
+      if (state === "spawn scheduled") return "installed (starting…)";
+      return `installed (${state})`;
+    } catch {
+      return "installed (not running)";
+    }
+  }
+
+  if (platform === "linux") {
+    if (!fs.existsSync(SYSTEMD_PATH)) return "not installed";
+    try {
+      execSync("systemctl --user is-active zozul", { stdio: "ignore" });
+      return "running";
+    } catch {
+      return "installed (not running)";
+    }
+  }
+
+  return "unsupported platform";
+}
+
+// ── macOS launchd ──
+
+function installLaunchd(env: Record<string, string>): ServiceResult {
+  const nodeBin = process.execPath;
+  const scriptPath = path.resolve(process.argv[1]);
+
+  fs.mkdirSync(path.dirname(PLIST_PATH), { recursive: true });
+  fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+
+  const envEntries = Object.entries(env)
+    .map(([k, v]) => `\t\t<key>${k}</key>\n\t\t<string>${v}</string>`)
+    .join("\n");
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t<string>${LABEL}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+\t\t<string>${nodeBin}</string>
+\t\t<string>${scriptPath}</string>
+\t\t<string>serve</string>
+\t</array>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+${envEntries}
+\t</dict>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>KeepAlive</key>
+\t<dict>
+\t\t<key>SuccessfulExit</key>
+\t\t<false/>
+\t</dict>
+\t<key>StandardOutPath</key>
+\t<string>${LOG_PATH}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${LOG_PATH}</string>
+\t<key>WorkingDirectory</key>
+\t<string>${path.dirname(LOG_PATH)}</string>
+</dict>
+</plist>
+`;
+
+  fs.writeFileSync(PLIST_PATH, plist, "utf-8");
+
+  // Unload any previous version first, then bootstrap
+  let alreadyRunning = false;
+  const uid = os.userInfo().uid;
+  try {
+    execSync(`launchctl bootout gui/${uid}/${LABEL}`, { stdio: "ignore" });
+  } catch {
+    // Wasn't loaded — fine
+  }
+  try {
+    execSync(`launchctl bootstrap gui/${uid} "${PLIST_PATH}"`, { stdio: "pipe" });
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("already")) {
+      alreadyRunning = true;
+    } else {
+      throw new Error(`launchctl bootstrap failed: ${msg}`);
+    }
+  }
+
+  return { platform: "macos", servicePath: PLIST_PATH, alreadyRunning };
+}
+
+// ── Linux systemd ──
+
+function installSystemd(env: Record<string, string>): ServiceResult {
+  const nodeBin = process.execPath;
+  const scriptPath = path.resolve(process.argv[1]);
+
+  fs.mkdirSync(SYSTEMD_DIR, { recursive: true });
+  fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+
+  const envLines = Object.entries(env)
+    .map(([k, v]) => `Environment="${k}=${v}"`)
+    .join("\n");
+
+  const unit = `[Unit]
+Description=zozul — Agent Observability
+After=network.target
+
+[Service]
+ExecStart=${nodeBin} ${scriptPath} serve
+${envLines}
+WorkingDirectory=${path.dirname(LOG_PATH)}
+Restart=on-failure
+RestartSec=5
+StandardOutput=append:${LOG_PATH}
+StandardError=append:${LOG_PATH}
+
+[Install]
+WantedBy=default.target
+`;
+
+  fs.writeFileSync(SYSTEMD_PATH, unit, "utf-8");
+
+  execSync("systemctl --user daemon-reload", { stdio: "ignore" });
+
+  let alreadyRunning = false;
+  try {
+    execSync("systemctl --user enable --now zozul", { stdio: "pipe" });
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("already")) {
+      alreadyRunning = true;
+    } else {
+      throw new Error(`systemctl enable failed: ${msg}`);
+    }
+  }
+
+  return { platform: "linux", servicePath: SYSTEMD_PATH, alreadyRunning };
+}
+
+function detectPlatform(): "macos" | "linux" | "unsupported" {
+  if (process.platform === "darwin") return "macos";
+  if (process.platform === "linux") return "linux";
+  return "unsupported";
+}