@fnclaude/renderer 0.0.1 → 2.0.1

package/src/event-parser.test.ts

@@ -0,0 +1,271 @@
+/**
+ * Tests for the NDJSON event parser.
+ *
+ * Strategy: feed real fixtures (recorded from `claude --print --verbose
+ * --input-format stream-json --output-format stream-json`) through the parser
+ * and assert on the discriminated union shapes. No live claude invocation
+ * needed.
+ */
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseNdjsonStream } from "./event-parser.ts";
+import type {
+  AssistantEvent,
+  ContentBlock,
+  ResultEvent,
+  SystemEvent,
+  TextBlock,
+  ToolResultBlock,
+  ToolUseBlock,
+} from "./types/events.ts";
+
+const fixtureDir = join(import.meta.dir, "__fixtures__");
+
+function fixtureStream(name: string): ReadableStream<Uint8Array> {
+  const bytes = readFileSync(join(fixtureDir, name));
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(new Uint8Array(bytes));
+      controller.close();
+    },
+  });
+}
+
+describe("parseNdjsonStream — text turn", () => {
+  test("emits system/init, rate_limit_event, assistant, result in order", async () => {
+    const events = [];
+    for await (const ev of parseNdjsonStream(fixtureStream("text-turn.ndjson"))) {
+      events.push(ev);
+    }
+    const types = events.map((e) => e.type);
+    expect(types).toContain("system");
+    expect(types).toContain("assistant");
+    expect(types).toContain("result");
+  });
+
+  test("system event has subtype init and session_id", async () => {
+    for await (const ev of parseNdjsonStream(fixtureStream("text-turn.ndjson"))) {
+      if (ev.type === "system") {
+        const sys = ev as SystemEvent;
+        expect(sys.subtype).toBe("init");
+        expect(typeof sys.session_id).toBe("string");
+        expect(sys.session_id.length).toBeGreaterThan(0);
+        return;
+      }
+    }
+    throw new Error("no system event found");
+  });
+
+  test("assistant event has text content block", async () => {
+    for await (const ev of parseNdjsonStream(fixtureStream("text-turn.ndjson"))) {
+      if (ev.type === "assistant") {
+        const ast = ev as AssistantEvent;
+        const textBlock = ast.message.content.find((b: ContentBlock) => b.type === "text") as
+          | TextBlock
+          | undefined;
+        expect(textBlock).toBeDefined();
+        expect(typeof textBlock?.text).toBe("string");
+        return;
+      }
+    }
+    throw new Error("no assistant event found");
+  });
+
+  test("result event is success and carries num_turns", async () => {
+    for await (const ev of parseNdjsonStream(fixtureStream("text-turn.ndjson"))) {
+      if (ev.type === "result") {
+        const res = ev as ResultEvent;
+        expect(res.subtype).toBe("success");
+        expect(res.is_error).toBe(false);
+        expect(typeof res.num_turns).toBe("number");
+        expect(typeof res.duration_ms).toBe("number");
+        return;
+      }
+    }
+    throw new Error("no result event found");
+  });
+});
+
+describe("parseNdjsonStream — tool-use turn", () => {
+  test("assistant event contains tool_use block", async () => {
+    for await (const ev of parseNdjsonStream(fixtureStream("tool-use-turn.ndjson"))) {
+      if (ev.type === "assistant") {
+        const ast = ev as AssistantEvent;
+        const toolBlock = ast.message.content.find((b: ContentBlock) => b.type === "tool_use") as
+          | ToolUseBlock
+          | undefined;
+        if (toolBlock !== undefined) {
+          expect(toolBlock.id).toBeTruthy();
+          expect(typeof toolBlock.name).toBe("string");
+          expect(typeof toolBlock.input).toBe("object");
+          return;
+        }
+      }
+    }
+    throw new Error("no tool_use block found in assistant event");
+  });
+
+  test("user event contains tool_result block", async () => {
+    for await (const ev of parseNdjsonStream(fixtureStream("tool-use-turn.ndjson"))) {
+      if (ev.type === "user") {
+        const msg = ev.message;
+        const content = Array.isArray(msg.content) ? msg.content : [];
+        const resultBlock = content.find((b: ContentBlock) => b.type === "tool_result") as
+          | ToolResultBlock
+          | undefined;
+        if (resultBlock !== undefined) {
+          expect(typeof resultBlock.tool_use_id).toBe("string");
+          return;
+        }
+      }
+    }
+    throw new Error("no tool_result block found in user event");
+  });
+});
+
+describe("parseNdjsonStream — slash-command turn", () => {
+  test("assistant event has model <synthetic>", async () => {
+    for await (const ev of parseNdjsonStream(fixtureStream("slash-command-turn.ndjson"))) {
+      if (ev.type === "assistant") {
+        const ast = ev as AssistantEvent;
+        expect(ast.message.model).toBe("<synthetic>");
+        return;
+      }
+    }
+    throw new Error("no assistant event found");
+  });
+
+  test("result event is success", async () => {
+    for await (const ev of parseNdjsonStream(fixtureStream("slash-command-turn.ndjson"))) {
+      if (ev.type === "result") {
+        const res = ev as ResultEvent;
+        expect(res.subtype).toBe("success");
+        return;
+      }
+    }
+    throw new Error("no result event found");
+  });
+});
+
+describe("parseNdjsonStream — unknown slash command", () => {
+  test("no assistant event emitted", async () => {
+    let sawAssistant = false;
+    for await (const ev of parseNdjsonStream(fixtureStream("unknown-slash-command-turn.ndjson"))) {
+      if (ev.type === "assistant") {
+        sawAssistant = true;
+      }
+    }
+    expect(sawAssistant).toBe(false);
+  });
+
+  test("result.result contains Unknown command and is_error is false", async () => {
+    for await (const ev of parseNdjsonStream(fixtureStream("unknown-slash-command-turn.ndjson"))) {
+      if (ev.type === "result") {
+        const res = ev as ResultEvent;
+        expect(res.result).toContain("Unknown command");
+        expect(res.is_error).toBe(false);
+        return;
+      }
+    }
+    throw new Error("no result event found");
+  });
+});
+
+describe("parseNdjsonStream — multi-turn", () => {
+  test("all events share the same session_id", async () => {
+    const sessionIds = new Set<string>();
+    for await (const ev of parseNdjsonStream(fixtureStream("multi-turn.ndjson"))) {
+      if ("session_id" in ev && typeof ev.session_id === "string") {
+        sessionIds.add(ev.session_id);
+      }
+    }
+    expect(sessionIds.size).toBe(1);
+  });
+
+  test("result event carries num_turns reflecting both turns", async () => {
+    // When two user turns are piped back-to-back without waiting for a result
+    // between them, claude processes them as one session run and emits a single
+    // result with num_turns reflecting the combined work (observed: 4 turns due
+    // to internal tool calls). The important invariant is that num_turns >= 1.
+    for await (const ev of parseNdjsonStream(fixtureStream("multi-turn.ndjson"))) {
+      if (ev.type === "result") {
+        const res = ev as ResultEvent;
+        expect(res.num_turns).toBeGreaterThanOrEqual(1);
+        return;
+      }
+    }
+    throw new Error("no result event found");
+  });
+});
+
+describe("parseNdjsonStream — large-line tolerance", () => {
+  test("handles a line of 64KB without dropping it", async () => {
+    // Synthetic: a valid JSON object whose text field is 64KB long.
+    const bigText = "x".repeat(64 * 1024);
+    const payload = JSON.stringify({
+      type: "assistant",
+      session_id: "test-session",
+      uuid: "test-uuid",
+      message: {
+        id: "msg_test",
+        model: "test-model",
+        role: "assistant",
+        content: [{ type: "text", text: bigText }],
+        stop_reason: "end_turn",
+        stop_sequence: null,
+        usage: { input_tokens: 1, output_tokens: 1 },
+      },
+    });
+    const bytes = new TextEncoder().encode(`${payload}\n`);
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(bytes);
+        controller.close();
+      },
+    });
+    const events = [];
+    for await (const ev of parseNdjsonStream(stream)) {
+      events.push(ev);
+    }
+    expect(events.length).toBe(1);
+    const ast = events[0] as AssistantEvent;
+    expect(ast.type).toBe("assistant");
+    const textBlock = ast.message.content[0] as TextBlock;
+    expect(textBlock.text.length).toBe(64 * 1024);
+  });
+});
+
+describe("parseNdjsonStream — partial trailing data", () => {
+  test("discards incomplete trailing line without throwing", async () => {
+    // A complete line followed by partial (no trailing newline).
+    const complete = JSON.stringify({
+      type: "result",
+      subtype: "success",
+      is_error: false,
+      session_id: "s1",
+      uuid: "u1",
+      result: "ok",
+      num_turns: 1,
+      duration_ms: 100,
+      duration_api_ms: 100,
+      total_cost_usd: 0,
+    });
+    const partial = '{"type":"assistant","partial":true';
+    const text = `${complete}\n${partial}`;
+    const bytes = new TextEncoder().encode(text);
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(bytes);
+        controller.close();
+      },
+    });
+    const events = [];
+    for await (const ev of parseNdjsonStream(stream)) {
+      events.push(ev);
+    }
+    // Only the complete line should yield an event; partial is silently dropped.
+    expect(events.length).toBe(1);
+    expect(events[0]?.type).toBe("result");
+  });
+});

package/src/event-parser.ts

@@ -0,0 +1,89 @@
+/**
+ * Line-buffered NDJSON parser for claude's stream-json output.
+ *
+ * Reads a ReadableStream<Uint8Array> and yields parsed ClaudeEvent objects.
+ * Designed for Bun.spawn's stdout stream.
+ *
+ * Design notes:
+ * - Buffers bytes across chunks and splits on `\n`. Lines can be ~3KB+ in
+ *   practice (system/init lines embed all slash commands and tool names);
+ *   the 64KB default chunk size for the dynamic buffer is intentionally
+ *   generous. There is no per-line cap.
+ * - Partial trailing data (no terminating `\n` when the stream closes) is
+ *   silently dropped — this matches observed behaviour where the process
+ *   always terminates cleanly with a fully-written result line.
+ * - JSON.parse errors on individual lines are silently dropped so that
+ *   unexpected diagnostic output or future unknown event types do not break
+ *   callers. The parser is meant to be forward-compatible.
+ */
+import type { ClaudeEvent } from "./types/events.ts";
+
+const NEWLINE = 0x0a; // '\n'
+
+export async function* parseNdjsonStream(
+  stream: ReadableStream<Uint8Array>,
+): AsyncGenerator<ClaudeEvent> {
+  const reader = stream.getReader();
+
+  // Dynamic byte accumulator — grows on demand.
+  let buf = new Uint8Array(64 * 1024);
+  let bufLen = 0;
+
+  const decoder = new TextDecoder();
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (value !== undefined) {
+        // Grow buffer if needed.
+        while (bufLen + value.length > buf.length) {
+          const next = new Uint8Array(buf.length * 2);
+          next.set(buf.subarray(0, bufLen));
+          buf = next;
+        }
+        buf.set(value, bufLen);
+        bufLen += value.length;
+      }
+
+      // Drain all complete lines from the buffer.
+      let start = 0;
+      while (start < bufLen) {
+        const newlinePos = buf.subarray(start, bufLen).indexOf(NEWLINE);
+        if (newlinePos === -1) break;
+
+        const lineEnd = start + newlinePos;
+        const line = decoder.decode(buf.subarray(start, lineEnd)).trim();
+        start = lineEnd + 1;
+
+        if (line.length === 0) continue;
+
+        const event = tryParseLine(line);
+        if (event !== null) yield event;
+      }
+
+      // Compact: move remaining bytes to front.
+      if (start > 0) {
+        buf.copyWithin(0, start, bufLen);
+        bufLen -= start;
+      }
+
+      if (done) break;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  // Any bytes remaining in buf are a partial line — silently dropped.
+}
+
+function tryParseLine(line: string): ClaudeEvent | null {
+  try {
+    const obj = JSON.parse(line) as unknown;
+    if (obj !== null && typeof obj === "object" && "type" in obj) {
+      return obj as ClaudeEvent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/filter-state.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, test } from "bun:test";
+import { cyclePreset, defaultState, resolve, toggleElement } from "./filter-state.ts";
+import type { FilterState } from "./types/events.ts";
+
+describe("defaultState", () => {
+  test("starts on normal preset with no overrides", () => {
+    const state = defaultState();
+    expect(state.preset).toBe("normal");
+    expect(state.overrides).toEqual({});
+  });
+});
+
+describe("resolve — preset defaults", () => {
+  const presets = (overrides: FilterState["overrides"] = {}) => ({
+    quiet: { preset: "quiet", overrides } as FilterState,
+    normal: { preset: "normal", overrides } as FilterState,
+    verbose: { preset: "verbose", overrides } as FilterState,
+    debug: { preset: "debug", overrides } as FilterState,
+  });
+
+  test("thinking: hide / dim / dim / show", () => {
+    const p = presets();
+    expect(resolve("thinking", p.quiet)).toBe("hide");
+    expect(resolve("thinking", p.normal)).toBe("dim");
+    expect(resolve("thinking", p.verbose)).toBe("dim");
+    expect(resolve("thinking", p.debug)).toBe("show");
+  });
+
+  test("Bash.input: summary / show / show / show", () => {
+    const p = presets();
+    expect(resolve("Bash.input", p.quiet)).toBe("summary");
+    expect(resolve("Bash.input", p.normal)).toBe("show");
+    expect(resolve("Bash.input", p.verbose)).toBe("show");
+    expect(resolve("Bash.input", p.debug)).toBe("show");
+  });
+
+  test("Bash.output: hide / hide / show / show", () => {
+    const p = presets();
+    expect(resolve("Bash.output", p.quiet)).toBe("hide");
+    expect(resolve("Bash.output", p.normal)).toBe("hide");
+    expect(resolve("Bash.output", p.verbose)).toBe("show");
+    expect(resolve("Bash.output", p.debug)).toBe("show");
+  });
+
+  test("Edit.diff: summary / show / show / show", () => {
+    const p = presets();
+    expect(resolve("Edit.diff", p.quiet)).toBe("summary");
+    expect(resolve("Edit.diff", p.normal)).toBe("show");
+    expect(resolve("Edit.diff", p.verbose)).toBe("show");
+    expect(resolve("Edit.diff", p.debug)).toBe("show");
+  });
+
+  test("Read.content: hide / hide / summary / show", () => {
+    const p = presets();
+    expect(resolve("Read.content", p.quiet)).toBe("hide");
+    expect(resolve("Read.content", p.normal)).toBe("hide");
+    expect(resolve("Read.content", p.verbose)).toBe("summary");
+    expect(resolve("Read.content", p.debug)).toBe("show");
+  });
+
+  test("Write.content: summary / summary / show / show", () => {
+    const p = presets();
+    expect(resolve("Write.content", p.quiet)).toBe("summary");
+    expect(resolve("Write.content", p.normal)).toBe("summary");
+    expect(resolve("Write.content", p.verbose)).toBe("show");
+    expect(resolve("Write.content", p.debug)).toBe("show");
+  });
+
+  test("Task.nested: summary / summary / show / show", () => {
+    const p = presets();
+    expect(resolve("Task.nested", p.quiet)).toBe("summary");
+    expect(resolve("Task.nested", p.normal)).toBe("summary");
+    expect(resolve("Task.nested", p.verbose)).toBe("show");
+    expect(resolve("Task.nested", p.debug)).toBe("show");
+  });
+
+  test("errors: show across all presets", () => {
+    const p = presets();
+    expect(resolve("errors", p.quiet)).toBe("show");
+    expect(resolve("errors", p.normal)).toBe("show");
+    expect(resolve("errors", p.verbose)).toBe("show");
+    expect(resolve("errors", p.debug)).toBe("show");
+  });
+});
+
+describe("resolve — overrides take precedence", () => {
+  test("override beats preset default", () => {
+    const state: FilterState = {
+      preset: "normal",
+      overrides: { "Bash.output": "show" },
+    };
+    expect(resolve("Bash.output", state)).toBe("show");
+  });
+
+  test("non-overridden element still uses preset default", () => {
+    const state: FilterState = {
+      preset: "verbose",
+      overrides: { "Bash.output": "hide" },
+    };
+    expect(resolve("Read.content", state)).toBe("summary");
+  });
+});
+
+describe("toggleElement", () => {
+  test("no override on a normally-shown element → flips to opposite (hide)", () => {
+    const state = defaultState(); // normal
+    // Bash.input default in normal is "show"
+    const next = toggleElement(state, "Bash.input");
+    expect(next.overrides["Bash.input"]).toBe("hide");
+    expect(resolve("Bash.input", next)).toBe("hide");
+  });
+
+  test("no override on a hidden element → flips to opposite (show)", () => {
+    const state = defaultState(); // normal
+    // Bash.output default in normal is "hide"
+    const next = toggleElement(state, "Bash.output");
+    expect(next.overrides["Bash.output"]).toBe("show");
+    expect(resolve("Bash.output", next)).toBe("show");
+  });
+
+  test("dim default → flips to hide (opposite-of-shown)", () => {
+    // thinking default in normal is "dim" — dim is a shown variant,
+    // so toggling should flip to "hide".
+    const state = defaultState();
+    const next = toggleElement(state, "thinking");
+    expect(next.overrides.thinking).toBe("hide");
+  });
+
+  test("summary default → flips to hide", () => {
+    // Edit.diff default in normal is "show" actually — pick one that's summary.
+    // Task.nested in normal is "summary".
+    const state = defaultState();
+    const next = toggleElement(state, "Task.nested");
+    expect(next.overrides["Task.nested"]).toBe("hide");
+  });
+
+  test("existing override → clears (reverts to preset default)", () => {
+    const state: FilterState = {
+      preset: "normal",
+      overrides: { "Bash.output": "show" },
+    };
+    const next = toggleElement(state, "Bash.output");
+    expect(next.overrides["Bash.output"]).toBeUndefined();
+    expect(resolve("Bash.output", next)).toBe("hide");
+  });
+
+  test("does not mutate input state", () => {
+    const state = defaultState();
+    const before = JSON.stringify(state);
+    toggleElement(state, "Bash.output");
+    expect(JSON.stringify(state)).toBe(before);
+  });
+});
+
+describe("cyclePreset", () => {
+  test("forward: quiet → normal → verbose → debug → quiet", () => {
+    let s: FilterState = { preset: "quiet", overrides: {} };
+    s = cyclePreset(s, 1);
+    expect(s.preset).toBe("normal");
+    s = cyclePreset(s, 1);
+    expect(s.preset).toBe("verbose");
+    s = cyclePreset(s, 1);
+    expect(s.preset).toBe("debug");
+    s = cyclePreset(s, 1);
+    expect(s.preset).toBe("quiet");
+  });
+
+  test("backward: quiet → debug → verbose → normal → quiet", () => {
+    let s: FilterState = { preset: "quiet", overrides: {} };
+    s = cyclePreset(s, -1);
+    expect(s.preset).toBe("debug");
+    s = cyclePreset(s, -1);
+    expect(s.preset).toBe("verbose");
+    s = cyclePreset(s, -1);
+    expect(s.preset).toBe("normal");
+    s = cyclePreset(s, -1);
+    expect(s.preset).toBe("quiet");
+  });
+
+  test("clears all overrides", () => {
+    const state: FilterState = {
+      preset: "normal",
+      overrides: { "Bash.output": "show", thinking: "hide" },
+    };
+    const next = cyclePreset(state, 1);
+    expect(next.preset).toBe("verbose");
+    expect(next.overrides).toEqual({});
+  });
+});

package/src/filter-state.ts

@@ -0,0 +1,110 @@
+/**
+ * Filter state reducer + utilities.
+ *
+ * See docs/filter-state-spec.md for the table of preset defaults and the
+ * toggle semantics. Pure functions; no React. Callers in App.tsx hold the
+ * state in a useState/useReducer.
+ */
+
+import type { ElementId, FilterState, Preset, Visibility } from "./types/events.ts";
+
+/**
+ * Preset defaults table. Mirror of the table in docs/filter-state-spec.md.
+ * Source of truth for `resolve()` when no per-element override is set.
+ */
+const PRESET_DEFAULTS: Record<Preset, Record<ElementId, Visibility>> = {
+  quiet: {
+    thinking: "hide",
+    "Bash.input": "summary",
+    "Bash.output": "hide",
+    "Edit.diff": "summary",
+    "Read.content": "hide",
+    "Write.content": "summary",
+    "Task.nested": "summary",
+    errors: "show",
+  },
+  normal: {
+    thinking: "dim",
+    "Bash.input": "show",
+    "Bash.output": "hide",
+    "Edit.diff": "show",
+    "Read.content": "hide",
+    "Write.content": "summary",
+    "Task.nested": "summary",
+    errors: "show",
+  },
+  verbose: {
+    thinking: "dim",
+    "Bash.input": "show",
+    "Bash.output": "show",
+    "Edit.diff": "show",
+    "Read.content": "summary",
+    "Write.content": "show",
+    "Task.nested": "show",
+    errors: "show",
+  },
+  debug: {
+    thinking: "show",
+    "Bash.input": "show",
+    "Bash.output": "show",
+    "Edit.diff": "show",
+    "Read.content": "show",
+    "Write.content": "show",
+    "Task.nested": "show",
+    errors: "show",
+  },
+};
+
+const PRESET_CYCLE: Preset[] = ["quiet", "normal", "verbose", "debug"];
+
+export function defaultState(): FilterState {
+  return { preset: "normal", overrides: {} };
+}
+
+export function resolve(element: ElementId, state: FilterState): Visibility {
+  const override = state.overrides[element];
+  if (override !== undefined) return override;
+  return PRESET_DEFAULTS[state.preset][element];
+}
+
+/**
+ * Visibility "polarity": dim/show/summary are all "shown to the user in some
+ * form" — toggling away from any of them sets `hide`. Toggling from `hide`
+ * sets `show`. This is the "opposite of preset" rule from the spec.
+ */
+function oppositeOf(v: Visibility): Visibility {
+  return v === "hide" ? "show" : "hide";
+}
+
+export function toggleElement(state: FilterState, element: ElementId): FilterState {
+  const nextOverrides = { ...state.overrides };
+  if (state.overrides[element] !== undefined) {
+    // Existing override → clear it (revert to preset default).
+    delete nextOverrides[element];
+  } else {
+    // No override → set opposite-of-preset.
+    const presetDefault = PRESET_DEFAULTS[state.preset][element];
+    nextOverrides[element] = oppositeOf(presetDefault);
+  }
+  return { preset: state.preset, overrides: nextOverrides };
+}
+
+export function cyclePreset(state: FilterState, direction: 1 | -1): FilterState {
+  const i = PRESET_CYCLE.indexOf(state.preset);
+  const len = PRESET_CYCLE.length;
+  const nextIdx = (i + direction + len) % len;
+  const nextPreset = PRESET_CYCLE[nextIdx];
+  // Type-narrow: nextIdx is in [0, len-1], so PRESET_CYCLE[nextIdx] is defined.
+  // noUncheckedIndexedAccess requires the guard.
+  if (nextPreset === undefined) {
+    throw new Error(`cyclePreset: invalid index ${nextIdx}`);
+  }
+  return { preset: nextPreset, overrides: {} };
+}
+
+/**
+ * Count of currently-active overrides, for the status line.
+ */
+export function overrideCount(state: FilterState): number {
+  return Object.keys(state.overrides).length;
+}

package/src/index.tsx

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+/**
+ * Entry point: mounts the App into Ink and lets slice A's subscription
+ * stream events into it. Don't add behaviour here — keep this file thin
+ * so the App is the testable surface.
+ */
+
+import { render } from "ink";
+import { App } from "./App.tsx";
+
+render(<App />);