@nathapp/nax 0.18.1

package/src/tui/hooks/useLayout.ts

@@ -0,0 +1,137 @@
+/**
+ * useLayout hook — terminal width detection and breakpoint management.
+ *
+ * Provides responsive layout breakpoints for the TUI:
+ * - < 80 cols: single column (stacked)
+ * - 80-140 cols: 2-column layout
+ * - > 140 cols: 2-column with wider agent panel
+ */
+
+import { useEffect, useState } from "react";
+
+/**
+ * Layout mode based on terminal width.
+ */
+export type LayoutMode = "single" | "narrow" | "wide";
+
+/**
+ * Layout configuration for rendering.
+ */
+export interface LayoutConfig {
+  /** Current layout mode */
+  mode: LayoutMode;
+  /** Terminal width in columns */
+  width: number;
+  /** Terminal height in rows */
+  height: number;
+  /** Stories panel width (columns) */
+  storiesPanelWidth: number;
+}
+
+/**
+ * Hook for responsive terminal layout.
+ *
+ * Detects terminal size and provides breakpoint-based layout config.
+ * Handles SIGWINCH (terminal resize) events and cleans up listeners on unmount.
+ *
+ * Three breakpoints:
+ * - < 80 cols: single-column (stacked)
+ * - 80-140 cols: two-column (narrow)
+ * - > 140 cols: two-column (wide)
+ *
+ * @example
+ * ```tsx
+ * const layout = useLayout();
+ *
+ * return (
+ *   <Box flexDirection={layout.mode === "single" ? "column" : "row"}>
+ *     <StoriesPanel width={layout.storiesPanelWidth} compact={layout.mode === "single"} />
+ *     <AgentPanel />
+ *   </Box>
+ * );
+ * ```
+ */
+export function useLayout(): LayoutConfig {
+  const [layout, setLayout] = useState<LayoutConfig>(() => computeLayout());
+
+  useEffect(() => {
+    const handleResize = () => {
+      setLayout(computeLayout());
+    };
+
+    // Listen for terminal resize (SIGWINCH)
+    // Node.js/Bun emits 'resize' event on process.stdout when terminal size changes
+    process.stdout.on("resize", handleResize);
+
+    // Clean up listener on unmount to prevent memory leaks
+    return () => {
+      process.stdout.off("resize", handleResize);
+    };
+  }, []);
+
+  return layout;
+}
+
+/**
+ * Minimum terminal width for usable display.
+ */
+export const MIN_TERMINAL_WIDTH = 60;
+
+/**
+ * Breakpoint: below this width, use single-column layout.
+ */
+const BREAKPOINT_NARROW = 80;
+
+/**
+ * Breakpoint: above this width, use wide two-column layout.
+ */
+const BREAKPOINT_WIDE = 140;
+
+/**
+ * Stories panel width in narrow two-column mode.
+ */
+const PANEL_WIDTH_NARROW = 30;
+
+/**
+ * Stories panel width in wide two-column mode.
+ */
+const PANEL_WIDTH_WIDE = 35;
+
+/**
+ * Maximum stories to show in compact mode (single-column).
+ */
+export const COMPACT_MAX_VISIBLE_STORIES = 8;
+
+/**
+ * Maximum stories before scrolling kicks in (normal mode).
+ */
+export const MAX_VISIBLE_STORIES = 15;
+
+/**
+ * Compute layout configuration based on current terminal size.
+ *
+ * Breakpoints:
+ * - < 80 cols: single-column (stacked), compact mode
+ * - 80-140 cols: two-column, narrow stories panel (30 cols)
+ * - > 140 cols: two-column, wide stories panel (35 cols)
+ */
+function computeLayout(): LayoutConfig {
+  const width = process.stdout.columns ?? 80;
+  const height = process.stdout.rows ?? 24;
+
+  let mode: LayoutMode;
+  let storiesPanelWidth: number;
+
+  if (width < BREAKPOINT_NARROW) {
+    mode = "single";
+    storiesPanelWidth = width;
+  } else if (width < BREAKPOINT_WIDE) {
+    mode = "narrow";
+    storiesPanelWidth = PANEL_WIDTH_NARROW;
+  } else {
+    mode = "wide";
+    storiesPanelWidth = PANEL_WIDTH_WIDE;
+  }
+
+  return { mode, width, height, storiesPanelWidth };
+}

package/src/tui/hooks/usePipelineEvents.ts

@@ -0,0 +1,183 @@
+/**
+ * usePipelineEvents hook — subscribe to pipeline events and update TUI state.
+ *
+ * Listens to pipeline lifecycle events and updates story display states,
+ * cost accumulator, and current stage information.
+ */
+
+import { useEffect, useState } from "react";
+import type { PipelineEventEmitter, RunSummary } from "../../pipeline/events";
+import type { UserStory } from "../../prd/types";
+import type { StoryDisplayState } from "../types";
+
+/**
+ * Pipeline state managed by the hook.
+ */
+export interface PipelineState {
+  /** Story display states */
+  stories: StoryDisplayState[];
+  /** Current story being executed */
+  currentStory?: UserStory;
+  /** Current pipeline stage */
+  currentStage?: string;
+  /** Total cost accumulated */
+  totalCost: number;
+  /** Elapsed time in milliseconds */
+  elapsedMs: number;
+  /** Run completion summary (if run finished) */
+  summary?: RunSummary;
+}
+
+/**
+ * Hook for subscribing to pipeline events and managing TUI state.
+ *
+ * Subscribes to pipeline lifecycle events (story:start, story:complete,
+ * story:escalate, stage:enter, run:complete) and updates story display
+ * states, cost accumulator, elapsed time, and current stage in real-time.
+ *
+ * The elapsed timer only runs while a story is active to avoid unnecessary
+ * re-renders during idle periods.
+ *
+ * @param events - Pipeline event emitter (from pipeline runner)
+ * @param initialStories - Initial story list from PRD
+ * @returns Pipeline state: stories (with status/cost), totalCost, elapsedMs, currentStory, currentStage, summary
+ *
+ * @example
+ * ```tsx
+ * const emitter = new PipelineEventEmitter();
+ * const state = usePipelineEvents(emitter, prd.userStories);
+ *
+ * // State automatically updates as pipeline emits events
+ * return (
+ *   <>
+ *     <StoriesPanel stories={state.stories} totalCost={state.totalCost} />
+ *     <StatusBar currentStory={state.currentStory} currentStage={state.currentStage} />
+ *   </>
+ * );
+ * ```
+ */
+export function usePipelineEvents(events: PipelineEventEmitter, initialStories: UserStory[]): PipelineState {
+  const [state, setState] = useState<PipelineState>(() => ({
+    stories: initialStories.map((story) => ({
+      story,
+      status: story.passes ? "passed" : "pending",
+      routing: story.routing,
+      cost: 0,
+    })),
+    totalCost: 0,
+    elapsedMs: 0,
+  }));
+
+  const startTime = Date.now();
+
+  useEffect(() => {
+    // Elapsed timer — only runs when a story is active
+    let timer: ReturnType<typeof setInterval> | null = null;
+
+    const startTimer = () => {
+      if (!timer) {
+        timer = setInterval(() => {
+          setState((prev) => ({
+            ...prev,
+            elapsedMs: Date.now() - startTime,
+          }));
+        }, 1000);
+      }
+    };
+
+    const stopTimer = () => {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    };
+
+    // story:start — Mark story as running
+    const onStoryStart = (story: UserStory) => {
+      startTimer();
+      setState((prev) => ({
+        ...prev,
+        currentStory: story,
+        stories: prev.stories.map((s) => (s.story.id === story.id ? { ...s, status: "running" as const } : s)),
+      }));
+    };
+
+    // story:complete — Mark story as complete (passed/failed/skipped)
+    const onStoryComplete = (story: UserStory, result: { action: string; cost?: number }) => {
+      stopTimer();
+      setState((prev) => {
+        const newStories = prev.stories.map((s) => {
+          if (s.story.id === story.id) {
+            let status: StoryDisplayState["status"] = "pending";
+            if (result.action === "continue") {
+              status = "passed";
+            } else if (result.action === "fail") {
+              status = "failed";
+            } else if (result.action === "skip") {
+              status = "skipped";
+            } else if (result.action === "pause") {
+              status = "paused";
+            }
+
+            // Accumulate cost from result
+            const storyCost = (s.cost || 0) + (result.cost || 0);
+            return { ...s, status, cost: storyCost };
+          }
+          return s;
+        });
+
+        // Update total cost accumulator
+        const totalCost = newStories.reduce((sum, s) => sum + (s.cost || 0), 0);
+
+        return {
+          ...prev,
+          stories: newStories,
+          currentStory: undefined,
+          totalCost,
+        };
+      });
+    };
+
+    // story:escalate — Mark story as retrying
+    const onStoryEscalate = (story: UserStory) => {
+      setState((prev) => ({
+        ...prev,
+        stories: prev.stories.map((s) => (s.story.id === story.id ? { ...s, status: "retrying" as const } : s)),
+      }));
+    };
+
+    // stage:enter — Update current stage
+    const onStageEnter = (stage: string) => {
+      setState((prev) => ({
+        ...prev,
+        currentStage: stage,
+      }));
+    };
+
+    // run:complete — Update final summary
+    const onRunComplete = (summary: RunSummary) => {
+      setState((prev) => ({
+        ...prev,
+        totalCost: summary.totalCost,
+        summary,
+      }));
+    };
+
+    events.on("story:start", onStoryStart);
+    events.on("story:complete", onStoryComplete);
+    events.on("story:escalate", onStoryEscalate);
+    events.on("stage:enter", onStageEnter);
+    events.on("run:complete", onRunComplete);
+
+    return () => {
+      stopTimer();
+      events.off("story:start", onStoryStart);
+      events.off("story:complete", onStoryComplete);
+      events.off("story:escalate", onStoryEscalate);
+      events.off("stage:enter", onStageEnter);
+      events.off("run:complete", onRunComplete);
+    };
+  }, [events, startTime]);
+
+  return state;
+}

package/src/tui/hooks/usePty.ts

@@ -0,0 +1,194 @@
+/**
+ * usePty hook — manages node-pty lifecycle for agent PTY sessions.
+ *
+ * Spawns, buffers output, handles resize, and cleanup for PTY processes.
+ */
+
+import type * as pty from "node-pty";
+import { useCallback, useEffect, useState } from "react";
+import type { PtyHandle } from "../../agents/types";
+
+/**
+ * Options for spawning PTY process.
+ */
+export interface PtySpawnOptions {
+  /** Command to execute (e.g., "claude") */
+  command: string;
+  /** Command arguments */
+  args?: string[];
+  /** Working directory */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Terminal columns (default: 80) */
+  cols?: number;
+  /** Terminal rows (default: 24) */
+  rows?: number;
+}
+
+/**
+ * PTY state managed by the hook.
+ */
+export interface PtyState {
+  /** Output lines buffered from PTY */
+  outputLines: string[];
+  /** Whether PTY process is running */
+  isRunning: boolean;
+  /** Exit code (if process exited) */
+  exitCode?: number;
+}
+
+/**
+ * Maximum number of output lines to buffer.
+ *
+ * Prevents memory bloat from long-running PTY sessions.
+ */
+const MAX_PTY_BUFFER_LINES = 500;
+
+/**
+ * Maximum length per line in characters.
+ *
+ * Prevents memory exhaustion from single extremely long lines.
+ */
+const MAX_LINE_LENGTH = 10_000;
+
+/**
+ * Hook for managing PTY lifecycle.
+ *
+ * Spawns a PTY process, buffers output, and provides a handle for input/resize/kill.
+ *
+ * @param options - PTY spawn options (null to skip spawning)
+ * @returns PTY state and handle
+ *
+ * @example
+ * ```tsx
+ * const { outputLines, isRunning, handle } = usePty({
+ *   command: "claude",
+ *   args: ["--model", "claude-sonnet-4.5"],
+ *   cwd: "/project",
+ * });
+ *
+ * // Write input to PTY
+ * handle?.write("y\n");
+ *
+ * // Render output
+ * <AgentPanel outputLines={outputLines} />
+ * ```
+ */
+export function usePty(options: PtySpawnOptions | null): PtyState & { handle: PtyHandle | null } {
+  const [state, setState] = useState<PtyState>(() => ({
+    outputLines: [],
+    isRunning: false,
+  }));
+
+  const [handle, setHandle] = useState<PtyHandle | null>(null);
+  const [ptyProcess, setPtyProcess] = useState<pty.IPty | null>(null);
+
+  // Spawn PTY process
+  useEffect(() => {
+    if (!options) {
+      return;
+    }
+
+    // Lazy load node-pty (only when needed)
+    let nodePty: typeof pty;
+    try {
+      nodePty = require("node-pty");
+    } catch (error) {
+      console.error("[usePty] node-pty not available:", error);
+      return;
+    }
+
+    const ptyProc = nodePty.spawn(options.command, options.args || [], {
+      name: "xterm-256color",
+      cols: options.cols || 80,
+      rows: options.rows || 24,
+      cwd: options.cwd || process.cwd(),
+      env: {
+        ...process.env,
+        ...options.env,
+      },
+    });
+
+    setPtyProcess(ptyProc);
+    setState((prev) => ({ ...prev, isRunning: true }));
+
+    // Buffer output line-by-line
+    let currentLine = "";
+    ptyProc.onData((data) => {
+      const lines = (currentLine + data).split("\n");
+      currentLine = lines.pop() || "";
+
+      // Truncate incomplete line if too long
+      if (currentLine.length > MAX_LINE_LENGTH) {
+        currentLine = currentLine.slice(-MAX_LINE_LENGTH);
+      }
+
+      if (lines.length > 0) {
+        // Truncate each complete line
+        const truncatedLines = lines.map((line) =>
+          line.length > MAX_LINE_LENGTH ? `${line.slice(0, MAX_LINE_LENGTH)}…` : line,
+        );
+
+        setState((prev) => {
+          const newLines = [...prev.outputLines, ...truncatedLines];
+          // Keep only last N lines
+          const trimmed = newLines.length > MAX_PTY_BUFFER_LINES ? newLines.slice(-MAX_PTY_BUFFER_LINES) : newLines;
+          return { ...prev, outputLines: trimmed };
+        });
+      }
+    });
+
+    // Handle exit
+    ptyProc.onExit((event) => {
+      setState((prev) => ({
+        ...prev,
+        isRunning: false,
+        exitCode: event.exitCode,
+      }));
+    });
+
+    // Create handle
+    const ptyHandle: PtyHandle = {
+      write: (data: string) => ptyProc.write(data),
+      resize: (cols: number, rows: number) => ptyProc.resize(cols, rows),
+      kill: () => ptyProc.kill(),
+      pid: ptyProc.pid,
+    };
+
+    setHandle(ptyHandle);
+
+    // Cleanup on unmount
+    return () => {
+      if (ptyProc) {
+        ptyProc.kill();
+      }
+    };
+  }, [options]);
+
+  // Handle terminal resize
+  const handleResize = useCallback(
+    (cols: number, rows: number) => {
+      if (ptyProcess) {
+        ptyProcess.resize(cols, rows);
+      }
+    },
+    [ptyProcess],
+  );
+
+  useEffect(() => {
+    const onResize = () => {
+      const cols = process.stdout.columns ?? 80;
+      const rows = process.stdout.rows ?? 24;
+      handleResize(cols, rows);
+    };
+
+    process.stdout.on("resize", onResize);
+
+    return () => {
+      process.stdout.off("resize", onResize);
+    };
+  }, [handleResize]);
+
+  return { ...state, handle };
+}

package/src/tui/index.tsx

@@ -0,0 +1,38 @@
+/**
+ * TUI entry point — renders the Ink-based terminal user interface.
+ */
+
+import { render } from "ink";
+import { App } from "./App";
+import type { TuiProps } from "./types";
+
+/**
+ * Render the TUI.
+ *
+ * Initializes Ink and renders the root App component.
+ *
+ * @param props - TUI props (feature, stories, events)
+ * @returns Ink instance (for cleanup/unmounting)
+ *
+ * @example
+ * ```ts
+ * const emitter = new PipelineEventEmitter();
+ *
+ * const instance = renderTui({
+ *   feature: "auth-system",
+ *   stories: initialStories,
+ *   totalCost: 0,
+ *   elapsedMs: 0,
+ *   events: emitter,
+ * });
+ *
+ * // Later: cleanup
+ * instance.unmount();
+ * ```
+ */
+export function renderTui(props: TuiProps) {
+  return render(<App {...props} />);
+}
+
+export type { TuiProps, StoryDisplayState, PanelFocus, PtySpawnOptions } from "./types";
+export { PipelineEventEmitter } from "../pipeline/events";

package/src/tui/types.ts

@@ -0,0 +1,76 @@
+/**
+ * TUI-specific types for terminal user interface components.
+ */
+
+import type { PipelineEventEmitter } from "../pipeline/events";
+import type { StoryRouting, UserStory } from "../prd/types";
+
+/**
+ * Story display state for the TUI.
+ *
+ * Extends UserStory with runtime state for visual rendering.
+ */
+export interface StoryDisplayState {
+  /** Story data from PRD */
+  story: UserStory;
+  /** Current status for display */
+  status: "pending" | "running" | "passed" | "failed" | "skipped" | "retrying" | "paused";
+  /** Routing result (if classified) */
+  routing?: StoryRouting;
+  /** Cost incurred for this story */
+  cost?: number;
+}
+
+/**
+ * Panel focus state.
+ *
+ * Determines which panel receives keyboard input.
+ */
+export enum PanelFocus {
+  /** Stories panel is focused (default) */
+  Stories = "stories",
+  /** Agent panel is focused (input routed to PTY) */
+  Agent = "agent",
+}
+
+/**
+ * PTY spawn options for agent integration.
+ */
+export interface PtySpawnOptions {
+  /** Command to execute (e.g., "claude") */
+  command: string;
+  /** Command arguments */
+  args?: string[];
+  /** Working directory */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Terminal columns (default: 80) */
+  cols?: number;
+  /** Terminal rows (default: 24) */
+  rows?: number;
+}
+
+/**
+ * Props for the root TUI component.
+ */
+export interface TuiProps {
+  /** Feature name */
+  feature: string;
+  /** All stories to display */
+  stories: StoryDisplayState[];
+  /** Current story being executed */
+  currentStory?: UserStory;
+  /** Current pipeline stage */
+  currentStage?: string;
+  /** Total cost accumulated */
+  totalCost: number;
+  /** Elapsed time in milliseconds */
+  elapsedMs: number;
+  /** Pipeline event emitter for live updates */
+  events: PipelineEventEmitter;
+  /** Path to queue file for writing commands (optional) */
+  queueFilePath?: string;
+  /** PTY spawn options for agent session (optional) */
+  ptyOptions?: PtySpawnOptions | null;
+}

package/src/utils/git.ts

@@ -0,0 +1,83 @@
+/**
+ * Git utility functions
+ */
+
+import { spawn } from "bun";
+
+/**
+ * Capture current git HEAD ref.
+ *
+ * Returns the current HEAD commit hash, or undefined if git is not available
+ * or the command fails (e.g., not in a git repo).
+ *
+ * @param workdir - Working directory to run git command in
+ * @returns Git HEAD ref or undefined on failure
+ *
+ * @example
+ * ```typescript
+ * const ref = await captureGitRef("/path/to/repo");
+ * if (ref) {
+ *   console.log(`Current HEAD: ${ref}`);
+ * }
+ * ```
+ */
+export async function captureGitRef(workdir: string): Promise<string | undefined> {
+  try {
+    const proc = spawn({
+      cmd: ["git", "rev-parse", "HEAD"],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) return undefined;
+
+    const stdout = await new Response(proc.stdout).text();
+    return stdout.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Check if a story ID appears in recent git commit messages.
+ *
+ * Searches the last 20 commits for commit messages containing the story ID.
+ * Used for state reconciliation: if a failed story has commits in git history,
+ * it means the story was partially completed and should be marked as passed.
+ *
+ * @param workdir - Working directory to run git command in
+ * @param storyId - Story ID to search for (e.g., "US-001")
+ * @param maxCommits - Maximum number of commits to search (default: 20)
+ * @returns true if story ID found in commit messages, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const hasCommits = await hasCommitsForStory("/path/to/repo", "US-001");
+ * if (hasCommits) {
+ *   console.log("Story US-001 has commits in git history");
+ * }
+ * ```
+ */
+export async function hasCommitsForStory(workdir: string, storyId: string, maxCommits = 20): Promise<boolean> {
+  try {
+    const proc = spawn({
+      cmd: ["git", "log", `-${maxCommits}`, "--oneline", "--grep", storyId],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) return false;
+
+    const stdout = await new Response(proc.stdout).text();
+    const commits = stdout.trim();
+
+    // If any commits found, return true
+    return commits.length > 0;
+  } catch {
+    return false;
+  }
+}