@butlerw/vellum 0.1.0

package/src/tui/hooks/useModeController.ts

@@ -0,0 +1,167 @@
+/**
+ * useModeController Hook (T003)
+ *
+ * Manages render mode decisions for adaptive message list rendering.
+ * Dynamically switches between Static, Windowed, and Virtualized modes
+ * based on content height vs available viewport.
+ *
+ * @module tui/hooks/useModeController
+ */
+
+import { useMemo } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Available rendering modes for message list.
+ */
+export type RenderMode = "static" | "windowed" | "virtualized";
+
+/**
+ * Reason for the current mode selection.
+ */
+export type ModeReason =
+  | "content-fits" // Content fits in viewport
+  | "content-exceeds-viewport" // Content exceeds viewport but not virtual threshold
+  | "content-very-large" // Content exceeds virtual threshold
+  | "forced"; // Mode was forced via config
+
+/**
+ * Configuration for mode controller.
+ */
+export interface ModeControllerConfig {
+  /** Multiplier for static threshold (default: 1.2 = 120% of viewport) */
+  readonly staticMultiplier?: number;
+  /** Multiplier for virtual threshold (default: 5.0 = 500% of viewport) */
+  readonly virtualMultiplier?: number;
+  /** Force a specific mode, bypassing auto-detection */
+  readonly forceMode?: RenderMode;
+  /** Minimum window size in lines (default: 10) */
+  readonly minWindowSize?: number;
+  /** Maximum window size as ratio of available height (default: 0.8) */
+  readonly maxWindowSizeRatio?: number;
+}
+
+/**
+ * Input for useModeController hook.
+ */
+export interface UseModeControllerInput {
+  /** Available height in lines for content */
+  readonly availableHeight: number;
+  /** Total estimated height of all content in lines */
+  readonly totalContentHeight: number;
+  /** Configuration options */
+  readonly config?: ModeControllerConfig;
+}
+
+/**
+ * State returned by useModeController.
+ */
+export interface ModeControllerState {
+  /** Current render mode */
+  readonly mode: RenderMode;
+  /** Recommended window size for windowed mode */
+  readonly windowSize: number;
+  /** Reason for the current mode selection */
+  readonly modeReason: ModeReason;
+  /** Computed static threshold (content height below this = static mode) */
+  readonly staticThreshold: number;
+  /** Computed virtual threshold (content height above this = virtualized mode) */
+  readonly virtualThreshold: number;
+  /** Whether mode is auto-detected (true) or forced (false) */
+  readonly isAutoMode: boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_STATIC_MULTIPLIER = 1.2;
+const DEFAULT_VIRTUAL_MULTIPLIER = 5.0;
+const DEFAULT_MIN_WINDOW_SIZE = 10;
+const DEFAULT_MAX_WINDOW_SIZE_RATIO = 0.8;
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook for managing render mode decisions based on content vs viewport.
+ *
+ * Mode selection logic:
+ * - Static: totalContentHeight ≤ availableHeight × staticMultiplier
+ * - Windowed: staticThreshold < totalContentHeight ≤ virtualThreshold
+ * - Virtualized: totalContentHeight > virtualThreshold
+ *
+ * @param input - Input parameters including viewport and content heights
+ * @returns Mode controller state with recommended settings
+ */
+export function useModeController(input: UseModeControllerInput): ModeControllerState {
+  const { availableHeight, totalContentHeight, config = {} } = input;
+
+  const {
+    staticMultiplier = DEFAULT_STATIC_MULTIPLIER,
+    virtualMultiplier = DEFAULT_VIRTUAL_MULTIPLIER,
+    forceMode,
+    minWindowSize = DEFAULT_MIN_WINDOW_SIZE,
+    maxWindowSizeRatio = DEFAULT_MAX_WINDOW_SIZE_RATIO,
+  } = config;
+
+  return useMemo(() => {
+    // Compute thresholds from available height
+    const staticThreshold = Math.max(1, availableHeight * staticMultiplier);
+    const virtualThreshold = Math.max(1, availableHeight * virtualMultiplier);
+
+    // Calculate window size with min constraint and max ratio
+    const windowSize = Math.max(minWindowSize, Math.floor(availableHeight * maxWindowSizeRatio));
+
+    // Determine if auto mode (not forced)
+    const isAutoMode = !forceMode;
+
+    // Handle forced mode
+    if (forceMode) {
+      return {
+        mode: forceMode,
+        windowSize,
+        modeReason: "forced" as const,
+        staticThreshold,
+        virtualThreshold,
+        isAutoMode,
+      };
+    }
+
+    // Auto-detect mode based on content height vs thresholds
+    let mode: RenderMode;
+    let modeReason: ModeReason;
+
+    if (totalContentHeight <= staticThreshold) {
+      mode = "static";
+      modeReason = "content-fits";
+    } else if (totalContentHeight <= virtualThreshold) {
+      mode = "windowed";
+      modeReason = "content-exceeds-viewport";
+    } else {
+      mode = "virtualized";
+      modeReason = "content-very-large";
+    }
+
+    return {
+      mode,
+      windowSize,
+      modeReason,
+      staticThreshold,
+      virtualThreshold,
+      isAutoMode,
+    };
+  }, [
+    availableHeight,
+    totalContentHeight,
+    staticMultiplier,
+    virtualMultiplier,
+    forceMode,
+    minWindowSize,
+    maxWindowSizeRatio,
+  ]);
+}

package/src/tui/hooks/useModeShortcuts.ts

@@ -0,0 +1,196 @@
+/**
+ * useModeShortcuts Hook (T046)
+ *
+ * React hook for handling keyboard shortcuts to switch coding modes.
+ * Provides Alt+1/2/3 shortcuts for quick mode switching.
+ *
+ * @module tui/hooks/useModeShortcuts
+ */
+
+import type { CodingMode, ModeManager } from "@vellum/core";
+import { CODING_MODES } from "@vellum/core";
+import { useInput } from "ink";
+import { useCallback, useRef } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for the useModeShortcuts hook.
+ */
+export interface UseModeShortcutsOptions {
+  /** The ModeManager instance to use for switching */
+  readonly modeManager: ModeManager | null;
+  /** Whether shortcuts are enabled (default: true) */
+  readonly enabled?: boolean;
+  /** Callback when a mode switch is attempted */
+  readonly onModeSwitch?: (mode: CodingMode, success: boolean) => void;
+  /** Callback when a mode switch fails */
+  readonly onError?: (mode: CodingMode, error: string) => void;
+}
+
+/**
+ * Return value of useModeShortcuts hook.
+ */
+export interface UseModeShortcutsReturn {
+  /** Get the shortcut key for a mode */
+  readonly getShortcut: (mode: CodingMode) => string;
+  /** Manually trigger a mode switch */
+  readonly switchMode: (mode: CodingMode) => Promise<boolean>;
+  /** Whether shortcuts are currently active */
+  readonly isActive: boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Keyboard shortcut mapping for modes.
+ * Alt+1 = vibe, Alt+2 = plan, Alt+3 = spec
+ */
+const MODE_SHORTCUTS: Record<string, CodingMode> = {
+  "1": "vibe",
+  "2": "plan",
+  "3": "spec",
+} as const;
+
+/**
+ * Reverse mapping: mode to shortcut key.
+ */
+const SHORTCUT_FOR_MODE: Record<CodingMode, string> = {
+  vibe: "Alt+1",
+  plan: "Alt+2",
+  spec: "Alt+3",
+} as const;
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * useModeShortcuts - Hook for handling mode switching keyboard shortcuts.
+ *
+ * Provides Alt+1/2/3 shortcuts for quick mode switching:
+ * - Alt+1: Switch to vibe mode (fast autonomous)
+ * - Alt+2: Switch to plan mode (plan-then-execute)
+ * - Alt+3: Switch to spec mode (6-phase workflow)
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { modeManager } = useApp();
+ *
+ *   const { getShortcut, isActive } = useModeShortcuts({
+ *     modeManager,
+ *     onModeSwitch: (mode, success) => {
+ *       console.log(`Switched to ${mode}: ${success}`);
+ *     },
+ *   });
+ *
+ *   return (
+ *     <Text>
+ *       Press {getShortcut('vibe')} for vibe mode
+ *     </Text>
+ *   );
+ * }
+ * ```
+ */
+export function useModeShortcuts({
+  modeManager,
+  enabled = true,
+  onModeSwitch,
+  onError,
+}: UseModeShortcutsOptions): UseModeShortcutsReturn {
+  // Track whether we're currently processing a switch
+  const isSwitchingRef = useRef(false);
+
+  // Check if shortcuts are active
+  const isActive = enabled && modeManager !== null;
+
+  /**
+   * Attempt to switch to a mode.
+   */
+  const switchMode = useCallback(
+    async (mode: CodingMode): Promise<boolean> => {
+      if (!modeManager) {
+        onError?.(mode, "Mode manager not initialized");
+        return false;
+      }
+
+      // Prevent concurrent switches
+      if (isSwitchingRef.current) {
+        return false;
+      }
+
+      // Check if already in target mode
+      if (modeManager.getCurrentMode() === mode) {
+        return true;
+      }
+
+      isSwitchingRef.current = true;
+
+      try {
+        const result = await modeManager.switchMode(mode);
+
+        if (result.success) {
+          onModeSwitch?.(mode, true);
+          return true;
+        }
+
+        onError?.(mode, result.reason ?? "Unknown error");
+        onModeSwitch?.(mode, false);
+        return false;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        onError?.(mode, errorMessage);
+        onModeSwitch?.(mode, false);
+        return false;
+      } finally {
+        isSwitchingRef.current = false;
+      }
+    },
+    [modeManager, onModeSwitch, onError]
+  );
+
+  /**
+   * Handle keyboard input for mode shortcuts.
+   */
+  useInput(
+    useCallback(
+      (input: string, key) => {
+        // Only handle Alt+number combinations
+        if (!key.meta) return;
+
+        // Check if input matches a mode shortcut
+        const targetMode = MODE_SHORTCUTS[input];
+        if (targetMode && CODING_MODES.includes(targetMode)) {
+          // Fire and forget - don't await in input handler
+          void switchMode(targetMode);
+        }
+      },
+      [switchMode]
+    ),
+    { isActive }
+  );
+
+  /**
+   * Get the shortcut key combination for a mode.
+   */
+  const getShortcut = useCallback((mode: CodingMode): string => {
+    return SHORTCUT_FOR_MODE[mode];
+  }, []);
+
+  return {
+    getShortcut,
+    switchMode,
+    isActive,
+  };
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export type { CodingMode };

package/src/tui/hooks/usePermissionHandler.ts

@@ -0,0 +1,146 @@
+/**
+ * usePermissionHandler Hook (T037)
+ *
+ * React hook that creates a PermissionAskHandler for use with the permission system.
+ * This hook manages permission dialog state and provides a handler function
+ * that can be passed to createDefaultPermissionChecker.
+ *
+ * @module @vellum/cli
+ */
+
+import type {
+  AskContext,
+  PermissionAskHandler,
+  PermissionInfo,
+  PermissionResponse,
+} from "@vellum/core";
+import { useCallback, useRef, useState } from "react";
+
+/**
+ * Pending permission request waiting for user response.
+ */
+export interface PendingPermission {
+  /** Unique ID for this request */
+  id: string;
+  /** Permission info from the permission system */
+  info: PermissionInfo;
+  /** Context from the permission system */
+  context: AskContext;
+  /** Resolve function to return the user's response */
+  resolve: (result: PermissionResponse | undefined) => void;
+  /** Timestamp when the request was created */
+  timestamp: number;
+}
+
+/**
+ * Return value of usePermissionHandler hook.
+ */
+export interface UsePermissionHandlerReturn {
+  /** Current pending permission request (if any) */
+  pendingPermission: PendingPermission | null;
+  /** Whether a permission dialog should be shown */
+  isDialogVisible: boolean;
+  /** Handler function to pass to the permission system */
+  handler: PermissionAskHandler;
+  /** Respond to the current permission request */
+  respond: (response: PermissionResponse) => void;
+}
+
+let requestIdCounter = 0;
+
+/**
+ * Hook for managing permission prompts in the CLI.
+ *
+ * Creates a PermissionAskHandler that can be passed to the permission system.
+ * When a permission check returns "ask", this handler is called and the hook
+ * updates state to show a dialog.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { pendingPermission, isDialogVisible, handler, respond } = usePermissionHandler();
+ *
+ *   // Pass handler to permission system
+ *   useEffect(() => {
+ *     const checker = createDefaultPermissionChecker({ askHandler: handler });
+ *     // ... use checker with ToolExecutor
+ *   }, [handler]);
+ *
+ *   return (
+ *     <Box>
+ *       {isDialogVisible && pendingPermission && (
+ *         <PermissionDialog
+ *           toolName={pendingPermission.info.toolName}
+ *           onResponse={respond}
+ *           isActive={true}
+ *         />
+ *       )}
+ *     </Box>
+ *   );
+ * }
+ * ```
+ */
+export function usePermissionHandler(): UsePermissionHandlerReturn {
+  const [pendingPermission, setPendingPermission] = useState<PendingPermission | null>(null);
+  const pendingRef = useRef<PendingPermission | null>(null);
+
+  /**
+   * Handler function for the permission system.
+   * This is called when a permission check returns "ask".
+   */
+  const handler: PermissionAskHandler = useCallback(
+    async (info: PermissionInfo, context: AskContext): Promise<PermissionResponse | undefined> => {
+      return new Promise<PermissionResponse | undefined>((resolve) => {
+        const id = `perm-${++requestIdCounter}`;
+        const pending: PendingPermission = {
+          id,
+          info,
+          context,
+          resolve,
+          timestamp: Date.now(),
+        };
+
+        pendingRef.current = pending;
+        setPendingPermission(pending);
+
+        // Handle timeout from the context signal
+        context.signal.addEventListener("abort", () => {
+          if (pendingRef.current?.id === id) {
+            // Timeout - return undefined to let the service handle it
+            resolve(undefined);
+            pendingRef.current = null;
+            setPendingPermission(null);
+          }
+        });
+      });
+    },
+    []
+  );
+
+  /**
+   * Respond to the current permission request.
+   */
+  const respond = useCallback((response: PermissionResponse) => {
+    const pending = pendingRef.current;
+    if (!pending) {
+      console.warn("[usePermissionHandler] No pending permission to respond to");
+      return;
+    }
+
+    // Resolve the promise with the response directly
+    pending.resolve(response);
+
+    // Clear state
+    pendingRef.current = null;
+    setPendingPermission(null);
+  }, []);
+
+  return {
+    pendingPermission,
+    isDialogVisible: pendingPermission !== null,
+    handler,
+    respond,
+  };
+}
+
+export default usePermissionHandler;