@butlerw/vellum 0.1.0

package/src/tui/hooks/useTerminalSize.ts

@@ -0,0 +1,206 @@
+/**
+ * Terminal Size Hook
+ *
+ * React hook for subscribing to terminal resize events.
+ * Provides reactive terminal dimensions with debouncing.
+ *
+ * @module tui/hooks/useTerminalSize
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { isNarrowWidth } from "../utils/isNarrowWidth.js";
+import { getMaxContentWidth, getTerminalHeight, getTerminalWidth } from "../utils/ui-sizing.js";
+
+/**
+ * Terminal size state returned by useTerminalSize hook.
+ */
+export interface TerminalSize {
+  /** Terminal width in columns */
+  width: number;
+  /** Terminal height in rows */
+  height: number;
+  /** Whether terminal is narrow (<= 80 columns) */
+  isNarrow: boolean;
+  /** Maximum content width for responsive layouts */
+  maxContentWidth: number;
+}
+
+/**
+ * Options for useTerminalSize hook.
+ */
+export interface UseTerminalSizeOptions {
+  /**
+   * Debounce delay in milliseconds for resize events.
+   * Set to 0 to disable debouncing.
+   * @default 100
+   */
+  debounceMs?: number;
+
+  /**
+   * Initial width to use before first measurement.
+   * @default 80
+   */
+  initialWidth?: number;
+
+  /**
+   * Initial height to use before first measurement.
+   * @default 24
+   */
+  initialHeight?: number;
+}
+
+/**
+ * Hook for subscribing to terminal resize events.
+ *
+ * Provides reactive terminal dimensions that update when the
+ * terminal is resized. Includes computed values for narrow
+ * width detection and responsive content width.
+ *
+ * @param options - Configuration options
+ * @returns Terminal size state
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { width, height, isNarrow, maxContentWidth } = useTerminalDimensions();
+ *
+ *   return (
+ *     <Box width={maxContentWidth}>
+ *       {isNarrow ? <CompactView /> : <FullView />}
+ *       <Text>Terminal: {width}x{height}</Text>
+ *     </Box>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom debounce
+ * const size = useTerminalDimensions({ debounceMs: 200 });
+ * ```
+ */
+export function useTerminalDimensions(options: UseTerminalSizeOptions = {}): TerminalSize {
+  const { debounceMs = 100, initialWidth = 80, initialHeight = 24 } = options;
+
+  // Get initial dimensions
+  const [dimensions, setDimensions] = useState(() => ({
+    width: getTerminalWidth(initialWidth),
+    height: getTerminalHeight(initialHeight),
+  }));
+
+  // Debounce timer ref
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Handler for resize events
+  const handleResize = useCallback(() => {
+    const newWidth = getTerminalWidth(initialWidth);
+    const newHeight = getTerminalHeight(initialHeight);
+
+    setDimensions((prev) => {
+      // Only update if dimensions actually changed
+      if (prev.width === newWidth && prev.height === newHeight) {
+        return prev;
+      }
+      return { width: newWidth, height: newHeight };
+    });
+  }, [initialWidth, initialHeight]);
+
+  // Debounced resize handler
+  const debouncedHandleResize = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+    }
+
+    if (debounceMs === 0) {
+      handleResize();
+    } else {
+      timerRef.current = setTimeout(handleResize, debounceMs);
+    }
+  }, [handleResize, debounceMs]);
+
+  // Subscribe to resize events
+  useEffect(() => {
+    // Initial measurement
+    handleResize();
+
+    // Subscribe to SIGWINCH (terminal resize signal)
+    process.stdout.on("resize", debouncedHandleResize);
+
+    return () => {
+      // Cleanup
+      process.stdout.off("resize", debouncedHandleResize);
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, [handleResize, debouncedHandleResize]);
+
+  // Compute derived values
+  const result = useMemo<TerminalSize>(
+    () => ({
+      width: dimensions.width,
+      height: dimensions.height,
+      isNarrow: isNarrowWidth(dimensions.width),
+      maxContentWidth: getMaxContentWidth(dimensions.width),
+    }),
+    [dimensions.width, dimensions.height]
+  );
+
+  return result;
+}
+
+/**
+ * Lightweight hook that only tracks narrow width state.
+ *
+ * Use this when you only need to know if the terminal is narrow,
+ * without the overhead of tracking full dimensions.
+ *
+ * @param debounceMs - Debounce delay for resize events
+ * @returns Whether terminal is narrow
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const isNarrow = useIsNarrowWidth();
+ *   return isNarrow ? <CompactView /> : <FullView />;
+ * }
+ * ```
+ */
+export function useIsNarrowWidth(debounceMs = 100): boolean {
+  const [narrow, setNarrow] = useState(() => isNarrowWidth(getTerminalWidth(80)));
+
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    const handleResize = () => {
+      const newNarrow = isNarrowWidth(getTerminalWidth(80));
+      setNarrow((prev) => (prev === newNarrow ? prev : newNarrow));
+    };
+
+    const debouncedHandleResize = () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+
+      if (debounceMs === 0) {
+        handleResize();
+      } else {
+        timerRef.current = setTimeout(handleResize, debounceMs);
+      }
+    };
+
+    // Initial check
+    handleResize();
+
+    process.stdout.on("resize", debouncedHandleResize);
+
+    return () => {
+      process.stdout.off("resize", debouncedHandleResize);
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, [debounceMs]);
+
+  return narrow;
+}

package/src/tui/hooks/useToolApprovalController.ts

@@ -0,0 +1,91 @@
+/**
+ * useToolApprovalController
+ *
+ * Bridges ToolsContext pending approvals to an optional AgentLoop instance.
+ *
+ * - Source of truth for UI is ToolsContext.
+ * - When a user approves/rejects, we update ToolsContext and (if provided)
+ *   signal the AgentLoop to resume via grantPermission/denyPermission.
+ */
+
+import { useCallback, useMemo } from "react";
+import type { RiskLevel } from "../components/Tools/PermissionDialog.js";
+import { useTools } from "../context/ToolsContext.js";
+
+export interface PermissionGate {
+  grantPermission: () => void;
+  denyPermission: () => void;
+}
+
+export interface UseToolApprovalControllerOptions {
+  readonly agentLoop?: PermissionGate;
+}
+
+export interface ToolApprovalViewModel {
+  readonly activeApproval: ReturnType<typeof useTools>["pendingApproval"][number] | null;
+  readonly activeRiskLevel: RiskLevel;
+  readonly approveActive: (mode?: "once" | "always") => void;
+  readonly rejectActive: () => void;
+}
+
+function inferRiskLevel(toolName: string): RiskLevel {
+  const normalized = toolName.toLowerCase();
+
+  // Conservative defaults: most tool calls are medium risk.
+  // Elevate for tools that can mutate the system or run commands.
+  if (
+    normalized.includes("bash") ||
+    normalized.includes("shell") ||
+    normalized.includes("exec") ||
+    normalized.includes("write") ||
+    normalized.includes("edit") ||
+    normalized.includes("delete")
+  ) {
+    return "high";
+  }
+
+  return "medium";
+}
+
+export function useToolApprovalController(
+  options: UseToolApprovalControllerOptions = {}
+): ToolApprovalViewModel {
+  const { agentLoop } = options;
+  const { pendingApproval, respondToPermissionRequest } = useTools();
+
+  const activeApproval = pendingApproval[0] ?? null;
+
+  const activeRiskLevel = useMemo<RiskLevel>(() => {
+    if (!activeApproval) return "medium";
+    return inferRiskLevel(activeApproval.toolName);
+  }, [activeApproval]);
+
+  const approveActive = useCallback(
+    (mode: "once" | "always" = "once") => {
+      if (!activeApproval) return;
+
+      // Resolve any core permission prompt associated with this execution.
+      // (No-op if none is pending.)
+      respondToPermissionRequest(activeApproval.id, mode);
+
+      // If an AgentLoop is driving tool execution, resume it.
+      // AgentLoop only supports a single pending permission at a time.
+      agentLoop?.grantPermission();
+    },
+    [activeApproval, respondToPermissionRequest, agentLoop]
+  );
+
+  const rejectActive = useCallback(() => {
+    if (!activeApproval) return;
+
+    respondToPermissionRequest(activeApproval.id, "reject");
+    agentLoop?.denyPermission();
+  }, [activeApproval, respondToPermissionRequest, agentLoop]);
+
+  return {
+    activeApproval,
+    activeRiskLevel,
+    approveActive,
+    rejectActive,
+  };
+}

package/src/tui/hooks/useVim.ts

@@ -0,0 +1,334 @@
+/**
+ * useVim Hook (T041)
+ *
+ * React hook for Vim editing mode in the TUI.
+ * Provides modal editing with NORMAL, INSERT, VISUAL, and COMMAND modes.
+ *
+ * @module @vellum/cli
+ */
+
+import { useCallback, useState } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Vim editing modes.
+ */
+export type VimMode = "NORMAL" | "INSERT" | "VISUAL" | "COMMAND";
+
+/**
+ * Motion actions for cursor movement.
+ */
+export interface VimMotionAction {
+  type: "motion";
+  direction: "h" | "j" | "k" | "l" | "w" | "b" | "e" | "0" | "$";
+}
+
+/**
+ * Mode change actions.
+ */
+export interface VimModeAction {
+  type: "mode";
+  target: VimMode;
+}
+
+/**
+ * Edit actions (delete, yank, paste).
+ */
+export interface VimEditAction {
+  type: "delete" | "yank" | "paste";
+}
+
+/**
+ * Union of all Vim actions.
+ */
+export type VimAction = VimMotionAction | VimModeAction | VimEditAction;
+
+/**
+ * Key modifiers for Vim key handling.
+ */
+export interface KeyModifiers {
+  ctrl?: boolean;
+  shift?: boolean;
+}
+
+/**
+ * Return value of useVim hook.
+ */
+export interface UseVimReturn {
+  /** Whether Vim mode is enabled */
+  enabled: boolean;
+  /** Current Vim mode */
+  mode: VimMode;
+  /** Toggle Vim mode on/off */
+  toggle: () => void;
+  /** Set the current Vim mode */
+  setMode: (mode: VimMode) => void;
+  /** Handle a key press and return the resulting action */
+  handleKey: (key: string, modifiers?: KeyModifiers) => VimAction | null;
+}
+
+// =============================================================================
+// Key Mappings
+// =============================================================================
+
+/**
+ * Motion keys in NORMAL and VISUAL modes.
+ */
+const MOTION_KEYS: Record<string, VimMotionAction["direction"]> = {
+  h: "h", // left
+  j: "j", // down
+  k: "k", // up
+  l: "l", // right
+  w: "w", // word forward
+  b: "b", // word backward
+  e: "e", // word end
+  "0": "0", // line start
+  $: "$", // line end
+};
+
+/**
+ * Keys that trigger mode transitions from NORMAL mode.
+ */
+const MODE_TRANSITION_KEYS: Record<string, VimMode> = {
+  i: "INSERT", // insert before cursor
+  a: "INSERT", // insert after cursor (append)
+  I: "INSERT", // insert at line start
+  A: "INSERT", // insert at line end
+  o: "INSERT", // open line below
+  O: "INSERT", // open line above
+  v: "VISUAL", // visual mode
+  V: "VISUAL", // visual line mode
+  ":": "COMMAND", // command mode
+};
+
+/**
+ * Edit action keys in NORMAL mode.
+ */
+const EDIT_KEYS: Record<string, VimEditAction["type"]> = {
+  x: "delete", // delete character
+  d: "delete", // delete (with motion)
+  y: "yank", // yank (copy)
+  p: "paste", // paste after
+  P: "paste", // paste before
+};
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * React hook for Vim editing mode.
+ *
+ * Provides modal editing with NORMAL, INSERT, VISUAL, and COMMAND modes.
+ * Handles key presses and returns appropriate actions for the calling component
+ * to execute.
+ *
+ * @returns UseVimReturn object with Vim state and control functions
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const vim = useVim();
+ *
+ *   const handleKeyPress = (key: string) => {
+ *     const action = vim.handleKey(key);
+ *     if (action?.type === 'motion') {
+ *       moveCursor(action.direction);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <Box>
+ *       <Text>Mode: {vim.mode}</Text>
+ *       <TextInput onKeyPress={handleKeyPress} />
+ *     </Box>
+ *   );
+ * }
+ * ```
+ */
+export function useVim(): UseVimReturn {
+  const [enabled, setEnabled] = useState(false);
+  const [mode, setModeState] = useState<VimMode>("NORMAL");
+
+  /**
+   * Toggle Vim mode on/off.
+   * When disabled, switches to INSERT mode.
+   * When enabled, switches to NORMAL mode.
+   */
+  const toggle = useCallback(() => {
+    setEnabled((prev) => {
+      const next = !prev;
+      // When enabling, start in NORMAL mode
+      // When disabling, mode doesn't matter but reset to NORMAL
+      setModeState("NORMAL");
+      return next;
+    });
+  }, []);
+
+  /**
+   * Set the current Vim mode.
+   */
+  const setMode = useCallback((newMode: VimMode) => {
+    setModeState(newMode);
+  }, []);
+
+  /**
+   * Handle a key press in NORMAL mode.
+   */
+  const handleNormalKey = useCallback((key: string, modifiers?: KeyModifiers): VimAction | null => {
+    // Check for Ctrl+c to exit to NORMAL (redundant but explicit)
+    if (modifiers?.ctrl && key === "c") {
+      return { type: "mode", target: "NORMAL" };
+    }
+
+    // In Vim mode we generally ignore Ctrl+<key> combos so global hotkeys can run.
+    // (Explicit Ctrl combos like Ctrl+C / Ctrl+[ are handled above or in other modes.)
+    if (modifiers?.ctrl) {
+      return null;
+    }
+
+    // Motion keys
+    if (key in MOTION_KEYS) {
+      const direction = MOTION_KEYS[key] as VimMotionAction["direction"];
+      return { type: "motion", direction };
+    }
+
+    // Mode transition keys
+    if (key in MODE_TRANSITION_KEYS) {
+      const target = MODE_TRANSITION_KEYS[key] as VimMode;
+      setModeState(target);
+      return { type: "mode", target };
+    }
+
+    // Edit keys
+    if (key in EDIT_KEYS) {
+      const editType = EDIT_KEYS[key] as VimEditAction["type"];
+      return { type: editType };
+    }
+
+    return null;
+  }, []);
+
+  /**
+   * Handle a key press in INSERT mode.
+   */
+  const handleInsertKey = useCallback((key: string, modifiers?: KeyModifiers): VimAction | null => {
+    // Escape or Ctrl+c returns to NORMAL mode
+    if (key === "escape" || (modifiers?.ctrl && key === "c")) {
+      setModeState("NORMAL");
+      return { type: "mode", target: "NORMAL" };
+    }
+
+    // Ctrl+[ is equivalent to Escape
+    if (modifiers?.ctrl && key === "[") {
+      setModeState("NORMAL");
+      return { type: "mode", target: "NORMAL" };
+    }
+
+    // All other keys pass through in INSERT mode
+    return null;
+  }, []);
+
+  /**
+   * Handle a key press in VISUAL mode.
+   */
+  const handleVisualKey = useCallback((key: string, modifiers?: KeyModifiers): VimAction | null => {
+    // Escape or Ctrl+c returns to NORMAL mode
+    if (key === "escape" || (modifiers?.ctrl && key === "c")) {
+      setModeState("NORMAL");
+      return { type: "mode", target: "NORMAL" };
+    }
+
+    // Ctrl+[ is equivalent to Escape
+    if (modifiers?.ctrl && key === "[") {
+      setModeState("NORMAL");
+      return { type: "mode", target: "NORMAL" };
+    }
+
+    // Ignore other Ctrl+<key> combos so global hotkeys can run.
+    if (modifiers?.ctrl) {
+      return null;
+    }
+
+    // Motion keys work in VISUAL mode
+    if (key in MOTION_KEYS) {
+      const direction = MOTION_KEYS[key] as VimMotionAction["direction"];
+      return { type: "motion", direction };
+    }
+
+    // v toggles back to NORMAL
+    if (key === "v") {
+      setModeState("NORMAL");
+      return { type: "mode", target: "NORMAL" };
+    }
+
+    // y yanks selection and returns to NORMAL
+    if (key === "y") {
+      setModeState("NORMAL");
+      return { type: "yank" };
+    }
+
+    // d deletes selection and returns to NORMAL
+    if (key === "d" || key === "x") {
+      setModeState("NORMAL");
+      return { type: "delete" };
+    }
+
+    return null;
+  }, []);
+
+  /**
+   * Handle a key press in COMMAND mode.
+   */
+  const handleCommandKey = useCallback(
+    (key: string, modifiers?: KeyModifiers): VimAction | null => {
+      // Escape or Ctrl+c returns to NORMAL mode
+      if (key === "escape" || (modifiers?.ctrl && key === "c")) {
+        setModeState("NORMAL");
+        return { type: "mode", target: "NORMAL" };
+      }
+
+      // Command mode passes through keys for command input
+      return null;
+    },
+    []
+  );
+
+  /**
+   * Handle a key press and return the resulting action.
+   * Returns null if the key should be passed through to the input.
+   */
+  const handleKey = useCallback(
+    (key: string, modifiers?: KeyModifiers): VimAction | null => {
+      // If Vim mode is disabled, pass through all keys
+      if (!enabled) {
+        return null;
+      }
+
+      switch (mode) {
+        case "NORMAL":
+          return handleNormalKey(key, modifiers);
+        case "INSERT":
+          return handleInsertKey(key, modifiers);
+        case "VISUAL":
+          return handleVisualKey(key, modifiers);
+        case "COMMAND":
+          return handleCommandKey(key, modifiers);
+        default:
+          return null;
+      }
+    },
+    [enabled, mode, handleNormalKey, handleInsertKey, handleVisualKey, handleCommandKey]
+  );
+
+  return {
+    enabled,
+    mode,
+    toggle,
+    setMode,
+    handleKey,
+  };
+}

package/src/tui/hooks/useWorkspace.ts

@@ -0,0 +1,56 @@
+/**
+ * useWorkspace Hook
+ *
+ * Provides current workspace (working directory) information.
+ * Returns the directory name and full path for display in the header bar.
+ *
+ * @module tui/hooks/useWorkspace
+ */
+
+import * as path from "node:path";
+import { useMemo } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Workspace information returned by the hook.
+ */
+export interface WorkspaceInfo {
+  /** Short name of the workspace directory */
+  readonly name: string;
+  /** Full absolute path to the workspace */
+  readonly path: string;
+}
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook to get current workspace information.
+ *
+ * Uses process.cwd() to determine the current working directory.
+ * Memoized to avoid recalculation on every render.
+ *
+ * @returns WorkspaceInfo with name and path
+ *
+ * @example
+ * ```tsx
+ * function Header() {
+ *   const { name, path } = useWorkspace();
+ *   return <Text>{ name}</Text>;
+ * }
+ * ```
+ */
+export function useWorkspace(): WorkspaceInfo {
+  return useMemo(() => {
+    const cwd = process.cwd();
+    const name = path.basename(cwd);
+    return {
+      name,
+      path: cwd,
+    };
+  }, []);
+}