@drakulavich/zapara 0.1.0

package/src/parse.ts

@@ -0,0 +1,105 @@
+import type { Event } from "./types.ts";
+
+// Markers compared against message text. The text itself is never kept.
+const INTERRUPT_PREFIX = "[Request interrupted by user";
+const REJECT_PREFIX = "The user doesn't want to proceed with this tool use";
+const QUESTION_TOOL = "AskUserQuestion";
+const PLAN_TOOL = "ExitPlanMode";
+// Inbound messages from subagents, other sessions and background tasks: the human
+// has to read and react to these, but did not type them, so they are `report`
+// events, never `prompt`. An interrupt marker is checked first and always wins.
+const AGENT_MARKERS = [
+  "Another Claude session sent a message:",
+  "<teammate-message",
+  "<cross-session-message",
+  "<task-notification>",
+  "[Cross-session",
+];
+
+type Rec = Record<string, unknown>;
+const isObj = (v: unknown): v is Rec => typeof v === "object" && v !== null;
+const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
+
+const firstText = (content: unknown): string | null => {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content) && isObj(content[0]) && content[0].type === "text") return str(content[0].text);
+  return null;
+};
+
+export function parseTranscript(text: string): Event[] {
+  const events: Event[] = [];
+  let lastTs: number | null = null;
+  let lastMode: string | null = null;
+  // Dedupes `output` events by requestId within this one file: Claude Code
+  // writes one record per content block of a response, repeating the same
+  // requestId and usage, so only the first qualifying record counts.
+  const seenRequestIds = new Set<string>();
+
+  for (const line of text.split("\n")) {
+    if (line.trim() === "") continue;
+    let rec: unknown;
+    try { rec = JSON.parse(line); } catch { continue; }
+    if (!isObj(rec)) continue;
+    const type = str(rec.type);
+    const sessionId = str(rec.sessionId);
+    if (type === null || sessionId === null) continue;
+    if (rec.isSidechain === true) continue;
+
+    if (type === "permission-mode") {
+      const m = str(rec.permissionMode);
+      if (m === null) continue;
+      // The baseline mode is tracked as soon as it is seen, even before any
+      // timestamp exists, so a later switch away from it can be detected. A
+      // switch is only ever emitted as an event once a timestamp is known;
+      // a switch that happens before any timestamp is known is dropped.
+      if (lastMode !== null && m !== lastMode && lastTs !== null) {
+        events.push({ ts: lastTs, sessionId, kind: "mode_change" });
+      }
+      lastMode = m;
+      continue;
+    }
+
+    if (type !== "user" && type !== "assistant") continue;
+    const ts = Date.parse(str(rec.timestamp) ?? "");
+    if (Number.isNaN(ts)) continue;
+    lastTs = ts;
+    events.push({ ts, sessionId, kind: "activity" });
+
+    const content = isObj(rec.message) ? rec.message.content : undefined;
+    if (type === "user") {
+      const blocks = Array.isArray(content) ? content : [];
+      for (const b of blocks) {
+        if (!isObj(b) || b.type !== "tool_result") continue;
+        const t = firstText(b.content);
+        if (t !== null && t.startsWith(REJECT_PREFIX)) events.push({ ts, sessionId, kind: "reject" });
+      }
+      const head = firstText(content);
+      if (head === null) continue;
+      if (head.startsWith(INTERRUPT_PREFIX)) events.push({ ts, sessionId, kind: "interrupt" });
+      else if (rec.isMeta !== true) {
+        if (AGENT_MARKERS.some((marker) => head.startsWith(marker))) events.push({ ts, sessionId, kind: "report" });
+        else events.push({ ts, sessionId, kind: "prompt" });
+      }
+    } else {
+      const blocks = Array.isArray(content) ? content : [];
+      for (const b of blocks) {
+        if (!isObj(b) || b.type !== "tool_use") continue;
+        if (b.name === QUESTION_TOOL) events.push({ ts, sessionId, kind: "question" });
+        else if (b.name === PLAN_TOOL) events.push({ ts, sessionId, kind: "plan_review" });
+      }
+      // `output`: one event per distinct requestId per file, the first record seen
+      // that has a string requestId, numeric usage.output_tokens and at least one
+      // text block. A response holding only tool_use blocks is not text the human
+      // reads, so it never triggers this, even on its first (and only) record.
+      const requestId = str(rec.requestId);
+      const usage = isObj(rec.message) ? rec.message.usage : undefined;
+      const outputTokens = isObj(usage) ? usage.output_tokens : undefined;
+      const hasText = blocks.some((b) => isObj(b) && b.type === "text");
+      if (requestId !== null && typeof outputTokens === "number" && hasText && !seenRequestIds.has(requestId)) {
+        seenRequestIds.add(requestId);
+        events.push({ ts, sessionId, kind: "output", tokens: outputTokens });
+      }
+    }
+  }
+  return events;
+}

package/src/render.ts

@@ -0,0 +1,110 @@
+import { formatCount, plural } from "./format.ts";
+import type { Day, HourBucket, Level } from "./types.ts";
+
+const GLYPH: Record<Level, string> = { Calm: "░", Warming: "▒", Heating: "▓", Fried: "█" };
+const ANSI: Record<Level, string> = { Calm: "32", Warming: "33", Heating: "35", Fried: "31" };
+const LEVEL_NAME: Record<Level, string> = { Calm: "calm", Warming: "warming", Heating: "heating", Fried: "fried" };
+const LEVELS: Level[] = ["Calm", "Warming", "Heating", "Fried"];
+const WEEKDAY = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+const paint = (s: string, level: Level, color: boolean) => (color ? `\x1b[${ANSI[level]}m${s}\x1b[0m` : s);
+const dim = (s: string, color: boolean) => (color ? `\x1b[2m${s}\x1b[0m` : s);
+const hm = (min: number) => `${Math.floor(min / 60)}h${String(min % 60).padStart(2, "0")}`;
+const label = (date: string) => {
+  const [y, m, d] = date.split("-").map(Number) as [number, number, number];
+  return `${WEEKDAY[new Date(y, m - 1, d).getDay()]} ${String(d).padStart(2, "0")}/${String(m).padStart(2, "0")}`;
+};
+
+export function renderWeek(days: Day[], color: boolean): string {
+  // Geometry: 12-char label, 24 cells of 3 chars (glyph in the middle), peak in 6, active in 8. Header hours are `HH ` so they sit over the cells.
+  const header = "            " + Array.from({ length: 24 }, (_, h) => `${String(h).padStart(2, "0")} `).join("") + "  peak  active";
+  const rows = days.map((d) => {
+    const cells = d.buckets.map((b) => ` ${b.score ? paint(GLYPH[b.score.level], b.score.level, color) : "·"} `).join("");
+    return `${label(d.date).padEnd(12)}${cells}${String(d.peak ?? "-").padStart(6)}${hm(d.activeMin).padStart(8)}`;
+  });
+  // A painted glyph's own \x1b[0m would cancel the line's outer dim, so in
+  // color mode re-emit \x1b[2m right after it to keep the label dim too.
+  const dimGlyph = (level: Level) => paint(GLYPH[level], level, color) + (color ? "\x1b[2m" : "");
+  const legend = dim("  " + LEVELS.map((l) => `${dimGlyph(l)} ${LEVEL_NAME[l]}`).join("   "), color);
+  const active = days.reduce((s, d) => s + d.activeMin, 0);
+  const prompts = days.reduce((s, d) => s + d.totals.prompts, 0);
+  const reports = days.reduce((s, d) => s + d.totals.reports, 0);
+  const decisions = days.reduce((s, d) => s + d.totals.decisions, 0);
+  const maxSessions = Math.max(0, ...days.map((d) => d.totals.maxSessions));
+  // Counts go through formatCount so a very active window (999 999 999 prompts) still
+  // fits inside the grid's 100 columns; hm(active) has no compact form, so it stays as is.
+  const totals = dim(`  ${hm(active)} active   ${plural(prompts, "prompt")}   ${plural(reports, "report")}   ${plural(decisions, "decision")}   ${plural(maxSessions, "session")} at once`, color);
+  return [header, ...rows, "", legend, totals].join("\n");
+}
+
+// Values at or above 1000 are shown as one decimal of a thousand (e.g. "41.2k"); smaller values print as-is.
+const fmtTokens = (n: number): string => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
+
+type Col = [string, number, (b: HourBucket) => string];
+
+// Widths reproduce the header the test pins: hour is left-aligned, level is left-aligned inside a 9-wide cell with two leading spaces, everything else right-aligned.
+const COLS: Col[] = [
+  ["hour", 5, (b) => `${String(b.hour).padStart(2, "0")}:00`],
+  ["index", 7, (b) => String(b.score?.index ?? "")],
+  ["level", 9, (b) => b.score?.level ?? ""],
+  ["sess", 6, (b) => String(b.sessions)],
+  ["prompts", 9, (b) => String(b.prompts)],
+  ["rep", 5, (b) => String(b.reports)],
+  ["intr", 6, (b) => String(b.interrupts)],
+  ["rej", 5, (b) => String(b.rejects)],
+  ["quest", 7, (b) => String(b.questions)],
+  ["plan", 6, (b) => String(b.plans)],
+  ["mode", 6, (b) => String(b.modeSwitches)],
+  ["ctx-sw", 8, (b) => String(b.contextSwitches)],
+  ["streak", 8, (b) => `${b.streakMin}m`],
+  ["out-tok", 9, (b) => fmtTokens(b.outputTokens)],
+];
+const EXPLAIN: Col[] = [
+  ["par", 5, (b) => String(b.score?.parts.parallel ?? "")],
+  ["pace", 6, (b) => String(b.score?.parts.pace ?? "")],
+  ["sup", 6, (b) => String(b.score?.parts.supervision ?? "")],
+  ["read", 6, (b) => String(b.score?.parts.reading ?? "")],
+  ["strk", 6, (b) => String(b.score?.parts.streak ?? "")],
+  ["late", 6, (b) => String(b.score?.parts.late ?? "")],
+];
+// Event columns: left out of the table for a day where every active bucket reads
+// zero (a quiet day is mostly zeros, and the eye hunts for the non-zero cell).
+// The skeleton columns (hour, index, level, sess, prompts, streak, out-tok, and
+// the six --explain parts) always show, so two days still line up.
+const EVENT_COLS = new Set(["rep", "intr", "rej", "quest", "plan", "mode", "ctx-sw"]);
+const FULL_NAME: Record<string, string> = {
+  rep: "reports", intr: "interrupts", rej: "rejects", quest: "questions",
+  plan: "plans", mode: "mode switches", "ctx-sw": "context switches",
+};
+
+export function renderDay(day: Day, opts: { explain: boolean; color: boolean }): string {
+  const cols = opts.explain ? [...COLS, ...EXPLAIN] : COLS;
+  const line = (columns: Col[], cells: string[]) =>
+    cells.map((c, i) => { const w = columns[i]![1]; if (i === 0) return c.padEnd(w); if (columns[i]![0] === "level") return `  ${c.padEnd(w - 2)}`; return c.padStart(w); }).join("").trimEnd();
+
+  const active = day.buckets.filter((b) => b.score !== null);
+  // No active bucket: today's plain behavior, the full header and nothing else.
+  if (active.length === 0) return line(cols, cols.map(([name]) => name));
+
+  const visible = cols.filter(([name, , f]) => !EVENT_COLS.has(name) || active.some((b) => f(b) !== "0"));
+  const leftOut = cols.filter((col) => EVENT_COLS.has(col[0]) && !visible.includes(col));
+
+  const header = line(visible, visible.map(([name]) => name));
+  const rows = active.map((b) => {
+    const cells = visible.map(([, , f]) => f(b));
+    const text = line(visible, cells);
+    // Safe only because no other column can contain a level word (Calm/Warming/Heating/Fried);
+    // if one ever could, this would need to target the level column's slice, not a string search.
+    return opts.color && b.score ? text.replace(b.score.level, paint(b.score.level, b.score.level, true)) : text;
+  });
+  const lines = [header, ...rows];
+  if (leftOut.length > 0) {
+    const note = `  no ${leftOut.map(([name]) => FULL_NAME[name]).join(", ")} today`;
+    lines.push(dim(note, opts.color));
+  }
+  return lines.join("\n");
+}
+
+export function renderJson(data: Day[] | Day): string {
+  return JSON.stringify(data, null, 2);
+}

package/src/report.ts

@@ -0,0 +1,18 @@
+import { readFile } from "node:fs/promises";
+import { analyze } from "./analyze.ts";
+import { windowBounds } from "./derive.ts";
+import { scan } from "./scan.ts";
+import type { Day, Transcript } from "./types.ts";
+
+export type ReportOptions = { projects: string; to: string; days: number };
+
+// The shell's seam: lists and reads files, then hands the text to the pure core.
+export async function report(o: ReportOptions): Promise<Day[]> {
+  const window = { to: o.to, days: o.days };
+  const paths = await scan(o.projects, windowBounds(window).cutoffMs);
+  const transcripts: Transcript[] = [];
+  for (const path of paths) {
+    try { transcripts.push({ path, text: await readFile(path, "utf8") }); } catch { /* vanished or unreadable: skip */ }
+  }
+  return analyze(transcripts, window);
+}

package/src/scan.ts

@@ -0,0 +1,40 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+// Lists transcript files worth reading. Subagent transcripts live under a `subagents`
+// directory and are the parent agent's conversation, not the human's; a file whose mtime
+// is before the cutoff cannot hold events the report needs.
+export async function scan(projects: string, cutoffMs: number): Promise<string[]> {
+  try {
+    if (!(await stat(projects)).isDirectory()) throw new Error("not a directory");
+  } catch {
+    // No path in the message: it may be a value the user typed, or the
+    // homedir-derived default, and the CLI must never print a filesystem path.
+    throw new Error("projects directory not found (pass --projects <dir>)");
+  }
+  const out: string[] = [];
+  await walk(projects, cutoffMs, out);
+  return out.sort();
+}
+
+// One directory at a time, so one unreadable directory or a symlink loop costs only
+// that directory. A symlink is not followed into: Claude Code never writes one, and
+// following it is how a loop or a stray link to $HOME would get in.
+async function walk(dir: string, cutoffMs: number, out: string[]): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== "subagents") await walk(full, cutoffMs, out);
+    } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+      try {
+        if ((await stat(full)).mtimeMs >= cutoffMs) out.push(full);
+      } catch {}
+    }
+  }
+}

package/src/score.ts

@@ -0,0 +1,58 @@
+import type { Level, Metrics, Parts, Score } from "./types.ts";
+
+// Calibration lives here and nowhere else. A change is one diff plus a CHANGELOG line.
+// Points of 100, kept as integers so 0.5 sums stay exact in floating point.
+// Norms are the p90 of two weeks of real data on two machines (see CHANGELOG).
+export const WEIGHTS = { parallel: 25, pace: 15, supervision: 30, reading: 10, streak: 10, late: 10 } as const;
+export const NORMS = { parallelSpan: 4, pacePerHour: 20, supervisionPerHour: 45, decisionWeight: 3, readingTokens: 80_000, streakMin: 120 } as const;
+export const LEVELS: readonly { max: number; level: Level }[] = [
+  { max: 29, level: "Calm" },
+  { max: 59, level: "Warming" },
+  { max: 84, level: "Heating" },
+  { max: 100, level: "Fried" },
+];
+
+const clamp01 = (x: number): number => Math.min(1, Math.max(0, x));
+
+export function levelOf(index: number): Level {
+  for (const l of LEVELS) if (index <= l.max) return l.level;
+  return "Fried";
+}
+
+export function score(m: Metrics): Score | null {
+  if (m.sessions === 0) return null;
+  const parallel = clamp01((m.sessions - 1) / NORMS.parallelSpan);
+  const pace = clamp01(m.prompts / NORMS.pacePerHour);
+  // Supervision is one load: an explicit decision costs `decisionWeight` times what
+  // reacting to one agent report or one session hop costs, and the three share a norm.
+  const supervision = clamp01(
+    (NORMS.decisionWeight * m.decisions + m.reports + m.contextSwitches) / NORMS.supervisionPerHour,
+  );
+  const reading = clamp01(m.outputTokens / NORMS.readingTokens);
+  const streak = clamp01(m.streakMin / NORMS.streakMin);
+  const late = m.lateNight ? 1 : 0;
+
+  const raw = {
+    parallel: WEIGHTS.parallel * parallel,
+    pace: WEIGHTS.pace * pace,
+    supervision: WEIGHTS.supervision * supervision,
+    reading: WEIGHTS.reading * reading,
+    streak: WEIGHTS.streak * streak,
+    late: WEIGHTS.late * late,
+  };
+  // parts are the same raw weighted points, rounded to one decimal for display only.
+  const parts: Parts = {
+    parallel: Math.round(raw.parallel * 10) / 10,
+    pace: Math.round(raw.pace * 10) / 10,
+    supervision: Math.round(raw.supervision * 10) / 10,
+    reading: Math.round(raw.reading * 10) / 10,
+    streak: Math.round(raw.streak * 10) / 10,
+    late: Math.round(raw.late * 10) / 10,
+  };
+  // index is rounded once, from the unrounded raw points, so per-component
+  // rounding (parts, above) can never tip it across a boundary raw didn't.
+  const index = Math.round(
+    raw.parallel + raw.pace + raw.supervision + raw.reading + raw.streak + raw.late,
+  );
+  return { index, level: levelOf(index), parts };
+}

package/src/types.ts

@@ -0,0 +1,15 @@
+export type EventKind = "prompt" | "report" | "output" | "interrupt" | "reject" | "question" | "plan_review" | "mode_change" | "activity";
+export type Event = { ts: number; sessionId: string; kind: EventKind; tokens?: number };
+export type Transcript = { path: string; text: string };
+export type Window = { to: string; days: number };            // to = "YYYY-MM-DD" local
+export type Metrics = {
+  sessions: number; prompts: number; reports: number; outputTokens: number; interrupts: number; rejects: number; questions: number;
+  plans: number; modeSwitches: number; decisions: number; contextSwitches: number;
+  activeMin: number; streakMin: number; lateNight: boolean;
+};
+export type Level = "Calm" | "Warming" | "Heating" | "Fried";
+export type Parts = { parallel: number; pace: number; supervision: number; reading: number; streak: number; late: number }; // weighted points, sum ≈ index
+export type Score = { index: number; level: Level; parts: Parts };
+export type HourBucket = Metrics & { hour: number; score: Score | null };
+export type Totals = { prompts: number; reports: number; outputTokens: number; interrupts: number; rejects: number; questions: number; plans: number; modeSwitches: number; decisions: number; contextSwitches: number; maxSessions: number };
+export type Day = { date: string; peak: number | null; mean: number | null; activeMin: number; totals: Totals; buckets: HourBucket[] };