@butlerw/vellum 0.1.0

package/src/tui/enterprise-integration.ts

@@ -0,0 +1,282 @@
+/**
+ * Enterprise Integration
+ *
+ * Wires MCP enterprise features (audit logging, server validation,
+ * tool blocking) to the TUI application when enterprise config is present.
+ *
+ * @module cli/tui/enterprise-integration
+ */
+
+import {
+  // Audit logging
+  type AuditEvent,
+  type AuditEventType,
+  AuditLogger,
+  // Configuration
+  type FullEnterpriseConfig,
+  getAuditLogger,
+  getEnterpriseConfigPath,
+  getFullEnterpriseConfig,
+  initializeAuditLogger,
+  isEnterpriseMode,
+  loadFullEnterpriseConfig,
+  type ServerInfo,
+  type ServerValidationResult,
+  shutdownAuditLogger,
+  type ToolCallInfo,
+  type ToolValidationResult,
+  // Server validation
+  validateServer,
+  validateToolCall,
+} from "@vellum/mcp";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface EnterpriseIntegrationResult {
+  /** Whether enterprise mode is enabled */
+  enabled: boolean;
+  /** Path to enterprise config file */
+  configPath: string;
+  /** Loaded enterprise configuration */
+  config: FullEnterpriseConfig | null;
+  /** Audit logger instance */
+  auditLogger: AuditLogger | null;
+  /** Error message if initialization failed */
+  error?: string;
+}
+
+export interface EnterpriseHooks {
+  /** Hook called before tool execution for validation */
+  onBeforeToolCall: (tool: ToolCallInfo) => Promise<{ allowed: boolean; reason?: string }>;
+  /** Hook called after tool execution for audit logging */
+  onAfterToolCall: (tool: ToolCallInfo, result: unknown, durationMs: number) => Promise<void>;
+  /** Hook called to validate MCP server connection */
+  onServerConnect: (server: ServerInfo) => Promise<{ allowed: boolean; reason?: string }>;
+  /** Hook called on user authentication (if applicable) */
+  onUserAction: (action: string, metadata?: Record<string, unknown>) => Promise<void>;
+}
+
+// =============================================================================
+// Enterprise Integration
+// =============================================================================
+
+let enterpriseConfig: FullEnterpriseConfig | null = null;
+let enterpriseInitialized = false;
+
+/**
+ * Load and initialize enterprise configuration.
+ *
+ * @returns Enterprise integration result
+ *
+ * @example
+ * ```typescript
+ * const enterprise = await initializeEnterprise();
+ * if (enterprise.enabled) {
+ *   console.log("Enterprise mode active");
+ *   console.log("Audit logging:", enterprise.config?.audit?.enabled);
+ * }
+ * ```
+ */
+export async function initializeEnterprise(): Promise<EnterpriseIntegrationResult> {
+  const configPath = getEnterpriseConfigPath();
+
+  // Check if enterprise mode is available
+  if (!isEnterpriseMode()) {
+    return {
+      enabled: false,
+      configPath,
+      config: null,
+      auditLogger: null,
+    };
+  }
+
+  try {
+    // Load full enterprise configuration
+    const config = await loadFullEnterpriseConfig();
+    enterpriseConfig = config;
+
+    // Initialize audit logger if enabled
+    let auditLogger: AuditLogger | null = null;
+    if (config.audit?.enabled) {
+      auditLogger = await initializeAuditLogger({ config });
+    }
+
+    enterpriseInitialized = true;
+
+    return {
+      enabled: true,
+      configPath,
+      config,
+      auditLogger,
+    };
+  } catch (error) {
+    return {
+      enabled: false,
+      configPath,
+      config: null,
+      auditLogger: null,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Get the current enterprise configuration.
+ *
+ * @returns Enterprise configuration or null if not in enterprise mode
+ */
+export function getEnterpriseConfig(): FullEnterpriseConfig | null {
+  return enterpriseConfig ?? getFullEnterpriseConfig();
+}
+
+/**
+ * Check if enterprise mode is currently active.
+ *
+ * @returns Whether enterprise mode is active
+ */
+export function isEnterpriseActive(): boolean {
+  return enterpriseInitialized && enterpriseConfig !== null;
+}
+
+/**
+ * Create enterprise hooks for tool and server validation.
+ *
+ * @returns Enterprise hooks object
+ *
+ * @example
+ * ```typescript
+ * const hooks = createEnterpriseHooks();
+ *
+ * // Before tool execution
+ * const validation = await hooks.onBeforeToolCall({
+ *   serverName: "my-server",
+ *   toolName: "bash",
+ *   arguments: { command: "ls -la" },
+ * });
+ * if (!validation.allowed) {
+ *   console.error("Tool blocked:", validation.reason);
+ * }
+ * ```
+ */
+export function createEnterpriseHooks(): EnterpriseHooks {
+  return {
+    async onBeforeToolCall(tool: ToolCallInfo) {
+      if (!isEnterpriseActive() || !enterpriseConfig) {
+        return { allowed: true };
+      }
+
+      const result: ToolValidationResult = validateToolCall(tool, enterpriseConfig);
+      if (!result.allowed) {
+        // Audit log the blocked tool call
+        const logger = getAuditLogger();
+        if (logger) {
+          await logger.log({
+            eventType: "tool_blocked",
+            toolName: tool.toolName,
+            serverName: tool.serverName,
+            metadata: {
+              reason: result.reason ?? "Enterprise policy violation",
+              arguments: tool.arguments,
+            },
+          });
+        }
+      }
+
+      return { allowed: result.allowed, reason: result.reason };
+    },
+
+    async onAfterToolCall(tool: ToolCallInfo, result: unknown, durationMs: number) {
+      if (!isEnterpriseActive()) {
+        return;
+      }
+
+      const logger = getAuditLogger();
+      if (logger) {
+        await logger.log({
+          eventType: "tool_call",
+          toolName: tool.toolName,
+          serverName: tool.serverName,
+          metadata: {
+            durationMs,
+            arguments: tool.arguments,
+            resultSummary:
+              typeof result === "object" && result !== null
+                ? Object.keys(result).join(", ")
+                : typeof result,
+          },
+        });
+      }
+    },
+
+    async onServerConnect(server: ServerInfo) {
+      if (!isEnterpriseActive() || !enterpriseConfig) {
+        return { allowed: true };
+      }
+
+      const result: ServerValidationResult = validateServer(server, enterpriseConfig);
+      if (!result.allowed) {
+        // Audit log the blocked server connection
+        const logger = getAuditLogger();
+        if (logger) {
+          await logger.log({
+            eventType: "server_blocked",
+            serverName: server.name,
+            metadata: {
+              reason: result.reason ?? "Server not in allowlist",
+              url: server.url,
+            },
+          });
+        }
+      }
+
+      return { allowed: result.allowed, reason: result.reason };
+    },
+
+    async onUserAction(action: string, metadata?: Record<string, unknown>) {
+      if (!isEnterpriseActive()) {
+        return;
+      }
+
+      const logger = getAuditLogger();
+      if (logger) {
+        await logger.log({
+          eventType: "config_change",
+          metadata: {
+            action,
+            ...metadata,
+          },
+        });
+      }
+    },
+  };
+}
+
+/**
+ * Shutdown enterprise integration and flush audit logs.
+ */
+export async function shutdownEnterprise(): Promise<void> {
+  if (enterpriseInitialized) {
+    await shutdownAuditLogger();
+    enterpriseConfig = null;
+    enterpriseInitialized = false;
+  }
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export {
+  type AuditEvent,
+  type AuditEventType,
+  AuditLogger,
+  type FullEnterpriseConfig,
+  type ServerInfo,
+  isEnterpriseMode,
+};
+
+// Note: ToolCallInfo is intentionally not re-exported here to avoid name collision
+// with the ToolCallInfo type from ./context/MessagesContext.js
+// Import it directly from @vellum/mcp if needed for enterprise validation.

package/src/tui/hooks/__tests__/useBacktrack.test.tsx

@@ -0,0 +1,138 @@
+/**
+ * useBacktrack Hook Tests (T058)
+ *
+ * Verifies core backtrack/branching behavior:
+ * - initializes with a main branch
+ * - push/undo/redo update currentState
+ * - createBranch creates and switches to a new branch
+ * - switchBranch switches branches and restores that branch's latest snapshot
+ */
+
+import { render } from "ink-testing-library";
+import type React from "react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  type UseBacktrackOptions,
+  type UseBacktrackReturn,
+  useBacktrack,
+} from "../useBacktrack.js";
+
+// =============================================================================
+// Test Helper Component
+// =============================================================================
+
+type TestState = { value: number };
+
+interface TestHarnessProps {
+  options: UseBacktrackOptions<TestState>;
+  onHookReturn: (hookReturn: UseBacktrackReturn<TestState>) => void;
+}
+
+function TestHarness({ options, onHookReturn }: TestHarnessProps): React.ReactElement {
+  const hookReturn = useBacktrack(options);
+  onHookReturn(hookReturn);
+  return null as unknown as React.ReactElement;
+}
+
+function renderHook(options: UseBacktrackOptions<TestState>) {
+  let hookReturn: UseBacktrackReturn<TestState> | null = null;
+
+  const setHookReturn = (r: UseBacktrackReturn<TestState>) => {
+    hookReturn = r;
+  };
+
+  const { rerender, unmount } = render(
+    <TestHarness options={options} onHookReturn={setHookReturn} />
+  );
+
+  return {
+    get current() {
+      if (!hookReturn) throw new Error("Hook not initialized");
+      return hookReturn;
+    },
+    rerender: (newOptions?: UseBacktrackOptions<TestState>) => {
+      rerender(<TestHarness options={newOptions ?? options} onHookReturn={setHookReturn} />);
+    },
+    unmount,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("useBacktrack", () => {
+  it("initializes with main branch and initial state", () => {
+    const result = renderHook({ initialState: { value: 0 } });
+
+    expect(result.current.backtrackState.currentBranch).toBe("Main");
+    expect(result.current.backtrackState.historyLength).toBe(1);
+    expect(result.current.branches).toHaveLength(1);
+    expect(result.current.currentState).toEqual({ value: 0 });
+  });
+
+  it("push/undo/redo update currentState", () => {
+    const onStateChange = vi.fn();
+    const result = renderHook({ initialState: { value: 0 }, onStateChange });
+
+    result.current.push({ value: 1 }, "v1");
+    result.rerender();
+    expect(result.current.currentState).toEqual({ value: 1 });
+
+    result.current.undo();
+    result.rerender();
+    expect(result.current.currentState).toEqual({ value: 0 });
+
+    result.current.redo();
+    result.rerender();
+    expect(result.current.currentState).toEqual({ value: 1 });
+
+    // Callback is best-effort and may be called multiple times; assert at least once.
+    expect(onStateChange).toHaveBeenCalled();
+  });
+
+  it("createBranch creates and switches to the new branch", () => {
+    const result = renderHook({ initialState: { value: 0 } });
+
+    result.current.push({ value: 1 }, "v1");
+    result.rerender();
+
+    const branchId = result.current.createBranch("Alt");
+    result.rerender();
+
+    expect(typeof branchId).toBe("string");
+    expect(result.current.backtrackState.currentBranch).toBe("Alt");
+    expect(result.current.branches.length).toBe(2);
+  });
+
+  it("switchBranch switches branch and restores that branch's latest snapshot", () => {
+    const result = renderHook({ initialState: { value: 0 } });
+
+    // Main branch: 0 -> 1
+    result.current.push({ value: 1 }, "main-v1");
+    result.rerender();
+
+    // Create Alt branch from current point and diverge
+    const altId = result.current.createBranch("Alt");
+    result.rerender();
+    expect(result.current.backtrackState.currentBranch).toBe("Alt");
+
+    result.current.push({ value: 2 }, "alt-v2");
+    result.rerender();
+    expect(result.current.currentState).toEqual({ value: 2 });
+
+    // Switch back to main
+    result.current.switchBranch("main");
+    result.rerender();
+
+    expect(result.current.backtrackState.currentBranch).toBe("Main");
+    expect(result.current.currentState).toEqual({ value: 1 });
+
+    // Switch to Alt again
+    result.current.switchBranch(altId);
+    result.rerender();
+
+    expect(result.current.backtrackState.currentBranch).toBe("Alt");
+    expect(result.current.currentState).toEqual({ value: 2 });
+  });
+});

package/src/tui/hooks/__tests__/useBracketedPaste.test.tsx

@@ -0,0 +1,222 @@
+/**
+ * useBracketedPaste Hook Tests
+ *
+ * Tests for the useBracketedPaste hook which manages bracketed paste mode lifecycle.
+ *
+ * @module @vellum/cli
+ */
+
+import { render } from "ink-testing-library";
+import type React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { type UseBracketedPasteOptions, useBracketedPaste } from "../useBracketedPaste.js";
+
+// =============================================================================
+// Mocks
+// =============================================================================
+
+const originalWrite = process.stdout.write;
+let writtenData: string[] = [];
+
+// Track process event listeners
+const processListeners: Map<string, Set<(...args: unknown[]) => void>> = new Map();
+const originalOn = process.on.bind(process);
+const originalOff = process.off.bind(process);
+
+beforeEach(() => {
+  writtenData = [];
+  processListeners.clear();
+
+  // Mock stdout.write
+  process.stdout.write = vi.fn((data: string | Uint8Array) => {
+    writtenData.push(typeof data === "string" ? data : data.toString());
+    return true;
+  }) as typeof process.stdout.write;
+
+  // Mock process event listeners
+  process.on = vi.fn((event: string, listener: (...args: unknown[]) => void) => {
+    if (!processListeners.has(event)) {
+      processListeners.set(event, new Set());
+    }
+    processListeners.get(event)?.add(listener);
+    return process;
+  }) as typeof process.on;
+
+  process.off = vi.fn((event: string, listener: (...args: unknown[]) => void) => {
+    processListeners.get(event)?.delete(listener);
+    return process;
+  }) as typeof process.off;
+});
+
+afterEach(() => {
+  process.stdout.write = originalWrite;
+  process.on = originalOn;
+  process.off = originalOff;
+});
+
+// =============================================================================
+// Test Helper Component
+// =============================================================================
+
+interface TestHarnessProps {
+  options?: UseBracketedPasteOptions;
+}
+
+function TestHarness({ options }: TestHarnessProps): React.ReactElement {
+  useBracketedPaste(options);
+  return null as unknown as React.ReactElement;
+}
+
+/**
+ * Render the hook and return controls.
+ */
+function renderHook(options?: UseBracketedPasteOptions) {
+  const { rerender, unmount } = render(<TestHarness options={options} />);
+
+  return {
+    rerender: (newOptions?: UseBracketedPasteOptions) => {
+      rerender(<TestHarness options={newOptions} />);
+    },
+    unmount,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("useBracketedPaste", () => {
+  describe("enable on mount", () => {
+    it("enables bracketed paste mode on mount by default", () => {
+      renderHook();
+
+      expect(writtenData).toContain("\x1b[?2004h");
+    });
+
+    it("enables bracketed paste mode when enabled=true", () => {
+      renderHook({ enabled: true });
+
+      expect(writtenData).toContain("\x1b[?2004h");
+    });
+
+    it("does not enable bracketed paste mode when enabled=false", () => {
+      renderHook({ enabled: false });
+
+      expect(writtenData).not.toContain("\x1b[?2004h");
+    });
+  });
+
+  describe("disable on unmount", () => {
+    it("disables bracketed paste mode on unmount", () => {
+      const { unmount } = renderHook();
+      writtenData = []; // Clear mount writes
+
+      unmount();
+
+      expect(writtenData).toContain("\x1b[?2004l");
+    });
+
+    it("does not disable if never enabled", () => {
+      const { unmount } = renderHook({ enabled: false });
+      writtenData = [];
+
+      unmount();
+
+      expect(writtenData).not.toContain("\x1b[?2004l");
+    });
+  });
+
+  describe("process event handlers", () => {
+    it("registers SIGINT handler on mount", () => {
+      renderHook();
+
+      expect(processListeners.has("SIGINT")).toBe(true);
+      expect(processListeners.get("SIGINT")?.size).toBeGreaterThan(0);
+    });
+
+    it("registers SIGTERM handler on mount", () => {
+      renderHook();
+
+      expect(processListeners.has("SIGTERM")).toBe(true);
+      expect(processListeners.get("SIGTERM")?.size).toBeGreaterThan(0);
+    });
+
+    it("registers beforeExit handler on mount", () => {
+      renderHook();
+
+      expect(processListeners.has("beforeExit")).toBe(true);
+    });
+
+    it("registers exit handler on mount", () => {
+      renderHook();
+
+      expect(processListeners.has("exit")).toBe(true);
+    });
+
+    it("removes event handlers on unmount", () => {
+      const { unmount } = renderHook();
+
+      // Get initial listener counts
+      const sigintBefore = processListeners.get("SIGINT")?.size ?? 0;
+      const sigtermBefore = processListeners.get("SIGTERM")?.size ?? 0;
+
+      unmount();
+
+      // Listeners should be removed
+      const sigintAfter = processListeners.get("SIGINT")?.size ?? 0;
+      const sigtermAfter = processListeners.get("SIGTERM")?.size ?? 0;
+
+      expect(sigintAfter).toBeLessThan(sigintBefore);
+      expect(sigtermAfter).toBeLessThan(sigtermBefore);
+    });
+
+    it("does not register handlers when disabled", () => {
+      renderHook({ enabled: false });
+
+      // No handlers should be registered (or fewer than when enabled)
+      const sigintCount = processListeners.get("SIGINT")?.size ?? 0;
+      expect(sigintCount).toBe(0);
+    });
+  });
+
+  describe("enabled toggle", () => {
+    it("enables bracketed paste when enabled changes from false to true", () => {
+      const { rerender } = renderHook({ enabled: false });
+      expect(writtenData).not.toContain("\x1b[?2004h");
+
+      writtenData = [];
+      rerender({ enabled: true });
+
+      expect(writtenData).toContain("\x1b[?2004h");
+    });
+
+    it("disables bracketed paste when enabled changes from true to false", () => {
+      const { rerender } = renderHook({ enabled: true });
+      expect(writtenData).toContain("\x1b[?2004h");
+
+      writtenData = [];
+      rerender({ enabled: false });
+
+      expect(writtenData).toContain("\x1b[?2004l");
+    });
+  });
+
+  describe("signal handlers cleanup behavior", () => {
+    it("signal handler calls disable sequence", () => {
+      renderHook();
+
+      // Get the SIGINT handler
+      const sigintHandlers = processListeners.get("SIGINT");
+      expect(sigintHandlers).toBeDefined();
+      expect(sigintHandlers?.size).toBeGreaterThan(0);
+
+      // Simulate SIGINT
+      writtenData = [];
+      const handler = sigintHandlers ? Array.from(sigintHandlers)[0] : undefined;
+      handler?.();
+
+      // Should have written disable sequence
+      expect(writtenData).toContain("\x1b[?2004l");
+    });
+  });
+});