@butlerw/vellum 0.1.0

package/src/tui/__tests__/mode-components.test.tsx

@@ -0,0 +1,395 @@
+/**
+ * Mode Components Tests (T048)
+ *
+ * Tests for TUI mode components:
+ * - ModeIndicator: Mode display with icons and colors
+ * - ModeSelector: Interactive mode selection
+ * - PhaseProgressIndicator: Spec phase progress display
+ *
+ * @module tui/__tests__/mode-components.test
+ */
+
+import type { CodingMode } from "@vellum/core";
+import { getIcons, type IconSet } from "@vellum/shared";
+import { render } from "ink-testing-library";
+import type React from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ModeIndicator } from "../components/ModeIndicator.js";
+import { ModeSelector } from "../components/ModeSelector.js";
+import { PhaseProgressIndicator } from "../components/PhaseProgressIndicator.js";
+import { ThemeProvider } from "../theme/index.js";
+
+// Icons are fetched in beforeEach to ensure setup has run first
+let icons: IconSet;
+
+beforeEach(() => {
+  // Get icons after setup has configured Unicode mode
+  icons = getIcons();
+});
+
+// =============================================================================
+// Test Helpers
+// =============================================================================
+
+/**
+ * Wrapper to provide theme context for tests
+ */
+function renderWithTheme(element: React.ReactElement) {
+  return render(<ThemeProvider>{element}</ThemeProvider>);
+}
+
+// =============================================================================
+// ModeIndicator Tests
+// =============================================================================
+
+describe("ModeIndicator", () => {
+  describe("Mode Icons", () => {
+    it("should render vibe mode with icon", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="vibe" />);
+      const frame = lastFrame() ?? "";
+      expect(frame).toContain(icons.vibe);
+      expect(frame).toContain("vibe");
+    });
+
+    it("should render plan mode with icon", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="plan" />);
+      const frame = lastFrame() ?? "";
+      expect(frame).toContain(icons.plan);
+      expect(frame).toContain("plan");
+    });
+
+    it("should render spec mode with icon", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="spec" />);
+      const frame = lastFrame() ?? "";
+      expect(frame).toContain(icons.spec);
+      expect(frame).toContain("spec");
+    });
+  });
+
+  describe("Spec Phase Display", () => {
+    it("should show phase progress when in spec mode", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="spec" specPhase={3} />);
+      const frame = lastFrame() ?? "";
+      expect(frame).toContain(icons.spec);
+      expect(frame).toContain("spec");
+      expect(frame).toContain("(3/6");
+      expect(frame).toContain("Design");
+    });
+
+    it("should show phase 1 (Research) correctly", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="spec" specPhase={1} />);
+      const frame = lastFrame() ?? "";
+      expect(frame).toContain("(1/6");
+      expect(frame).toContain("Research");
+    });
+
+    it("should show phase 6 (Validation) correctly", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="spec" specPhase={6} />);
+      const frame = lastFrame() ?? "";
+      expect(frame).toContain("(6/6");
+      expect(frame).toContain("Validation");
+    });
+
+    it("should not show phase for non-spec modes", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="vibe" specPhase={3} />);
+      const frame = lastFrame() ?? "";
+      expect(frame).not.toContain("(3/6)");
+    });
+
+    it("should clamp invalid phase numbers", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="spec" specPhase={10} />);
+      const frame = lastFrame() ?? "";
+      expect(frame).toContain("(6/6");
+    });
+  });
+
+  describe("Compact Mode", () => {
+    it("should show only icon in compact mode", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="vibe" compact />);
+      const frame = lastFrame() ?? "";
+      expect(frame).toContain(icons.vibe);
+      expect(frame).not.toContain("vibe ");
+    });
+
+    it("should show phase numbers in compact spec mode", () => {
+      const { lastFrame } = renderWithTheme(<ModeIndicator mode="spec" specPhase={4} compact />);
+      const frame = lastFrame() ?? "";
+      expect(frame).toContain(icons.spec);
+      expect(frame).toContain("(4/6)");
+      // Should NOT show the phase name in compact mode
+      expect(frame).not.toContain("Tasks");
+    });
+  });
+});
+
+// =============================================================================
+// ModeSelector Tests
+// =============================================================================
+
+describe("ModeSelector", () => {
+  describe("Rendering", () => {
+    it("should render all three modes", () => {
+      const onSelect = vi.fn();
+      const { lastFrame } = renderWithTheme(
+        <ModeSelector currentMode="vibe" onSelect={onSelect} isActive={false} />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain(icons.vibe);
+      expect(frame).toContain("vibe");
+      expect(frame).toContain(icons.plan);
+      expect(frame).toContain("plan");
+      expect(frame).toContain(icons.spec);
+      expect(frame).toContain("spec");
+    });
+
+    it("should show shortcut keys", () => {
+      const onSelect = vi.fn();
+      const { lastFrame } = renderWithTheme(
+        <ModeSelector currentMode="vibe" onSelect={onSelect} isActive={false} />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain("[1]");
+      expect(frame).toContain("[2]");
+      expect(frame).toContain("[3]");
+    });
+
+    it("should indicate current mode", () => {
+      const onSelect = vi.fn();
+      const { lastFrame } = renderWithTheme(
+        <ModeSelector currentMode="plan" onSelect={onSelect} isActive={false} />
+      );
+      const frame = lastFrame() ?? "";
+
+      // Translation key is used in tests - checks correct key is applied
+      expect(frame).toContain("modeSelector.current");
+    });
+
+    it("should show mode descriptions by default", () => {
+      const onSelect = vi.fn();
+      const { lastFrame } = renderWithTheme(
+        <ModeSelector currentMode="vibe" onSelect={onSelect} isActive={false} />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain("Fast autonomous coding");
+    });
+
+    it("should hide descriptions when showDescriptions is false", () => {
+      const onSelect = vi.fn();
+      const { lastFrame } = renderWithTheme(
+        <ModeSelector
+          currentMode="vibe"
+          onSelect={onSelect}
+          isActive={false}
+          showDescriptions={false}
+        />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).not.toContain("Fast autonomous coding");
+    });
+  });
+
+  describe("Keyboard Navigation", () => {
+    it("should show help text", () => {
+      const onSelect = vi.fn();
+      const { lastFrame } = renderWithTheme(
+        <ModeSelector currentMode="vibe" onSelect={onSelect} isActive />
+      );
+      const frame = lastFrame() ?? "";
+
+      // Translation key is used in tests - checks correct key is applied
+      expect(frame).toContain("modeSelector.keybindings");
+    });
+
+    // Note: Testing stdin/keyboard input with ink-testing-library is complex
+    // because useInput handlers are called asynchronously. The keyboard
+    // shortcuts (1, 2, 3) are tested implicitly through the component
+    // implementation and manual testing. The rendering tests above
+    // verify the UI elements are present.
+
+    it("should show focus indicator when active", () => {
+      const onSelect = vi.fn();
+      const { lastFrame } = renderWithTheme(
+        <ModeSelector currentMode="vibe" onSelect={onSelect} isActive />
+      );
+      const frame = lastFrame() ?? "";
+
+      // Focus indicator should be present
+      expect(frame).toContain("❯");
+    });
+
+    it("should not call onSelect when inactive", () => {
+      const onSelect = vi.fn();
+      renderWithTheme(<ModeSelector currentMode="vibe" onSelect={onSelect} isActive={false} />);
+
+      // With isActive=false, the selector should not process input
+      expect(onSelect).not.toHaveBeenCalled();
+    });
+  });
+});
+
+// =============================================================================
+// PhaseProgressIndicator Tests
+// =============================================================================
+
+describe("PhaseProgressIndicator", () => {
+  describe("Horizontal Progress Bar", () => {
+    it("should render progress segments", () => {
+      const { lastFrame } = renderWithTheme(<PhaseProgressIndicator currentPhase={3} />);
+      const frame = lastFrame() ?? "";
+
+      // Should contain progress bar characters
+      expect(frame).toContain("█"); // Completed
+      expect(frame).toContain("▓"); // Current
+      expect(frame).toContain("░"); // Pending
+    });
+
+    it("should show first phase correctly", () => {
+      const { lastFrame } = renderWithTheme(<PhaseProgressIndicator currentPhase={1} showLabels />);
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain("Research");
+      expect(frame).toContain("(1/6)");
+    });
+
+    it("should show last phase correctly", () => {
+      const { lastFrame } = renderWithTheme(<PhaseProgressIndicator currentPhase={6} showLabels />);
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain("Validation");
+      expect(frame).toContain("(6/6)");
+    });
+
+    it("should show percentage when enabled", () => {
+      const { lastFrame } = renderWithTheme(
+        <PhaseProgressIndicator currentPhase={4} showPercentage />
+      );
+      const frame = lastFrame() ?? "";
+
+      // Phase 4 = 3 completed = 50%
+      expect(frame).toContain("50%");
+    });
+
+    it("should show 0% for phase 1", () => {
+      const { lastFrame } = renderWithTheme(
+        <PhaseProgressIndicator currentPhase={1} showPercentage />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain("0%");
+    });
+
+    it("should clamp phase to valid range", () => {
+      const { lastFrame } = renderWithTheme(
+        <PhaseProgressIndicator currentPhase={10} showLabels />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain("Validation");
+      expect(frame).toContain("(6/6)");
+    });
+  });
+
+  describe("Vertical Progress List", () => {
+    it("should render all phases in vertical mode", () => {
+      const { lastFrame } = renderWithTheme(
+        <PhaseProgressIndicator currentPhase={3} orientation="vertical" />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain("1. Research");
+      expect(frame).toContain("2. Requirements");
+      expect(frame).toContain("3. Design");
+      expect(frame).toContain("4. Tasks");
+      expect(frame).toContain("5. Implementation");
+      expect(frame).toContain("6. Validation");
+    });
+
+    it("should show completed phases with checkmark", () => {
+      const { lastFrame } = renderWithTheme(
+        <PhaseProgressIndicator currentPhase={3} orientation="vertical" />
+      );
+      const frame = lastFrame() ?? "";
+
+      // Phases 1 and 2 should be completed
+      expect(frame).toContain(icons.check);
+    });
+
+    it("should show current phase with bullet", () => {
+      const { lastFrame } = renderWithTheme(
+        <PhaseProgressIndicator currentPhase={3} orientation="vertical" />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain(icons.bullet);
+    });
+
+    it("should show pending phases with circle", () => {
+      const { lastFrame } = renderWithTheme(
+        <PhaseProgressIndicator currentPhase={3} orientation="vertical" />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain(icons.pending);
+    });
+
+    it("should show progress summary with percentage", () => {
+      const { lastFrame } = renderWithTheme(
+        <PhaseProgressIndicator currentPhase={4} orientation="vertical" showPercentage />
+      );
+      const frame = lastFrame() ?? "";
+
+      expect(frame).toContain("Progress:");
+      expect(frame).toContain("50%");
+      expect(frame).toContain("3/6 completed");
+    });
+  });
+
+  describe("Custom Width", () => {
+    it("should respect custom width", () => {
+      const { lastFrame } = renderWithTheme(<PhaseProgressIndicator currentPhase={3} width={12} />);
+      const frame = lastFrame() ?? "";
+
+      // Width 12 / 6 phases = 2 chars per segment
+      // Just verify it renders without errors
+      expect(frame).toBeTruthy();
+    });
+  });
+});
+
+// =============================================================================
+// Accessibility Tests
+// =============================================================================
+
+describe("Accessibility", () => {
+  describe("ModeIndicator", () => {
+    it("should use semantic colors for modes", () => {
+      // Each mode should have a distinct color
+      const modes: CodingMode[] = ["vibe", "plan", "spec"];
+
+      for (const mode of modes) {
+        const { lastFrame } = renderWithTheme(<ModeIndicator mode={mode} />);
+        const frame = lastFrame() ?? "";
+        // Just verify it renders without errors
+        expect(frame).toBeTruthy();
+      }
+    });
+  });
+
+  describe("PhaseProgressIndicator", () => {
+    it("should provide textual alternatives in vertical mode", () => {
+      const { lastFrame } = renderWithTheme(
+        <PhaseProgressIndicator currentPhase={3} orientation="vertical" showPercentage />
+      );
+      const frame = lastFrame() ?? "";
+
+      // Should have textual descriptions
+      expect(frame).toContain("Research");
+      expect(frame).toContain("Requirements");
+      expect(frame).toContain("Design");
+    });
+  });
+});

package/src/tui/__tests__/permission-ask-flow.test.tsx

@@ -0,0 +1,138 @@
+/**
+ * Permission Ask Flow Integration Tests
+ *
+ * Verifies that the core permission "ask" flow can be driven by the TUI layer:
+ * - A permission prompt creates a pending tool execution in ToolsContext
+ * - PermissionDialog can approve (once/always) or reject
+ * - Approving resolves the underlying ask promise (allowing execution to resume)
+ */
+
+import type { AskContext, PermissionInfo } from "@vellum/core";
+import { Text } from "ink";
+import { render } from "ink-testing-library";
+import { act, useEffect, useRef, useState } from "react";
+import { describe, expect, it } from "vitest";
+import { PermissionDialog, RootProvider, useTools } from "../index.js";
+
+describe("Permission ask flow", () => {
+  it("shows PermissionDialog for an ask decision and resumes execution on approve", async () => {
+    function TestComponent() {
+      const { pendingApproval, permissionAskHandler, respondToPermissionRequest } = useTools();
+
+      const [response, setResponse] = useState<string | null>(null);
+      const startedRef = useRef(false);
+      const approvedRef = useRef(false);
+
+      useEffect(() => {
+        let cancelled = false;
+
+        if (startedRef.current) {
+          return;
+        }
+        startedRef.current = true;
+
+        void (async () => {
+          const abortController = new AbortController();
+
+          const createdAt = Date.now();
+
+          const info: PermissionInfo = {
+            id: "perm-1",
+            type: "tool",
+            sessionId: "sess-1",
+            messageId: "msg-1",
+            title: "Allow shell?",
+            callId: "call-1",
+            metadata: {
+              toolName: "shell",
+              params: {
+                command: "echo hi",
+              },
+            },
+            time: {
+              created: createdAt,
+            },
+          };
+
+          const ctx: AskContext = {
+            timeoutMs: 5_000,
+            signal: abortController.signal,
+          };
+
+          const result = await permissionAskHandler(info, ctx);
+
+          if (cancelled) {
+            return;
+          }
+
+          setResponse(result ?? null);
+        })();
+
+        return () => {
+          cancelled = true;
+        };
+      }, [permissionAskHandler]);
+
+      const pending = pendingApproval[0];
+
+      useEffect(() => {
+        if (!pending) {
+          return;
+        }
+
+        if (approvedRef.current) {
+          return;
+        }
+
+        approvedRef.current = true;
+
+        // Delay approval so the dialog has time to render and be asserted against.
+        const timer = setTimeout(() => {
+          respondToPermissionRequest(pending.id, "once");
+        }, 100);
+
+        return () => {
+          clearTimeout(timer);
+        };
+      }, [pending, respondToPermissionRequest]);
+
+      if (pending) {
+        return (
+          <PermissionDialog
+            execution={pending}
+            riskLevel="high"
+            onApprove={() => respondToPermissionRequest(pending.id, "once")}
+            onApproveAlways={() => respondToPermissionRequest(pending.id, "always")}
+            onReject={() => respondToPermissionRequest(pending.id, "reject")}
+          />
+        );
+      }
+
+      return <Text>{response ? `response: ${response}` : "waiting"}</Text>;
+    }
+
+    const { lastFrame } = render(
+      <RootProvider theme="dark">
+        <TestComponent />
+      </RootProvider>
+    );
+
+    // Let the permission prompt surface (before auto-approve fires).
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    });
+
+    const before = lastFrame() ?? "";
+    expect(before).toContain("shell");
+    expect(before).toContain("High Risk");
+    expect(before).toContain("echo hi");
+
+    // Let approval + ask resolution complete.
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    });
+
+    const after = lastFrame() ?? "";
+    expect(after).toContain("response: once");
+  }, 10_000);
+});

package/src/tui/__tests__/sidebar-panel-data.test.tsx

@@ -0,0 +1,148 @@
+/**
+ * Sidebar panel data refresh tests
+ *
+ * Verifies the data loader hook that backs MemoryPanel and TodoPanel:
+ * - initial load
+ * - refresh on panel open
+ * - refresh after relevant tool execution completion
+ */
+
+import type { MemoryEntry } from "@vellum/core";
+import { Text } from "ink";
+import { render } from "ink-testing-library";
+import type React from "react";
+import { describe, expect, it, vi } from "vitest";
+import type { TodoItemData } from "../components/TodoItem.js";
+import type { ToolExecution } from "../context/ToolsContext.js";
+import {
+  getLastCompletedToolExecutionId,
+  shouldRefreshFromToolExecution,
+  useSidebarPanelData,
+} from "../hooks/useSidebarPanelData.js";
+
+function Harness(props: {
+  readonly sidebarVisible: boolean;
+  readonly sidebarContent: "todo" | "memory" | "tools" | "mcp";
+  readonly executions: readonly ToolExecution[];
+  readonly loadTodos: () => Promise<readonly TodoItemData[]>;
+  readonly loadMemories: () => Promise<readonly MemoryEntry[]>;
+}): React.JSX.Element {
+  const { todoItems, memoryEntries } = useSidebarPanelData({
+    sidebarVisible: props.sidebarVisible,
+    sidebarContent: props.sidebarContent,
+    executions: props.executions,
+    loadTodos: props.loadTodos,
+    loadMemories: props.loadMemories,
+  });
+
+  return <Text>{`todos:${todoItems.length} memories:${memoryEntries.length}`}</Text>;
+}
+
+describe("sidebar panel data", () => {
+  it("should identify the last completed tool execution id", () => {
+    const executions: ToolExecution[] = [
+      { id: "1", toolName: "read_file", params: {}, status: "running" },
+      { id: "2", toolName: "todo_manage", params: {}, status: "complete" },
+      { id: "3", toolName: "save_memory", params: {}, status: "pending" },
+      { id: "4", toolName: "todo_manage", params: {}, status: "complete" },
+    ];
+
+    expect(getLastCompletedToolExecutionId(executions)).toBe("4");
+  });
+
+  it("should decide which panels to refresh from a tool execution", () => {
+    const todoExec: ToolExecution = {
+      id: "1",
+      toolName: "todo_manage",
+      params: {},
+      status: "complete",
+    };
+
+    const memoryExec: ToolExecution = {
+      id: "2",
+      toolName: "save_memory",
+      params: {},
+      status: "complete",
+    };
+
+    expect(shouldRefreshFromToolExecution(todoExec)).toEqual({
+      refreshTodos: true,
+      refreshMemories: false,
+    });
+
+    expect(shouldRefreshFromToolExecution(memoryExec)).toEqual({
+      refreshTodos: false,
+      refreshMemories: true,
+    });
+  });
+
+  it("should refresh on panel open and after relevant tool completion", async () => {
+    const loadTodos = vi.fn<() => Promise<readonly TodoItemData[]>>().mockResolvedValue([
+      {
+        id: 1,
+        title: "Task A",
+        status: "pending",
+        createdAt: new Date().toISOString(),
+      },
+    ]);
+
+    const loadMemories = vi.fn<() => Promise<readonly MemoryEntry[]>>().mockResolvedValue([
+      {
+        key: "k1",
+        type: "context",
+        content: "c1",
+        createdAt: new Date("2024-01-01T00:00:00.000Z"),
+        updatedAt: new Date("2024-01-01T00:00:00.000Z"),
+        metadata: { tags: [], importance: 0.5 },
+      },
+    ]);
+
+    const { lastFrame, rerender } = render(
+      <Harness
+        sidebarVisible={false}
+        sidebarContent="tools"
+        executions={[]}
+        loadTodos={loadTodos}
+        loadMemories={loadMemories}
+      />
+    );
+
+    // Initial load is best-effort; allow microtasks to flush.
+    await Promise.resolve();
+
+    expect(loadTodos).toHaveBeenCalledTimes(1);
+    expect(loadMemories).toHaveBeenCalledTimes(1);
+
+    // Opening the todo panel should trigger a refresh.
+    rerender(
+      <Harness
+        sidebarVisible={true}
+        sidebarContent="todo"
+        executions={[]}
+        loadTodos={loadTodos}
+        loadMemories={loadMemories}
+      />
+    );
+    await Promise.resolve();
+    expect(loadTodos).toHaveBeenCalledTimes(2);
+
+    // Completing todo_manage should trigger a refresh.
+    rerender(
+      <Harness
+        sidebarVisible={true}
+        sidebarContent="todo"
+        executions={[{ id: "e1", toolName: "todo_manage", params: {}, status: "complete" }]}
+        loadTodos={loadTodos}
+        loadMemories={loadMemories}
+      />
+    );
+    await Promise.resolve();
+
+    expect(loadTodos).toHaveBeenCalledTimes(3);
+
+    // Should have rendered counts at least once.
+    const frame = lastFrame() ?? "";
+    expect(frame).toContain("todos:");
+    expect(frame).toContain("memories:");
+  });
+});