@butlerw/vellum 0.1.0

package/src/tui/sandbox-integration.ts

@@ -0,0 +1,317 @@
+/**
+ * Sandbox Integration
+ *
+ * Wires the @vellum/sandbox package to shell tool execution,
+ * providing secure command execution with platform-specific sandboxing.
+ *
+ * @module cli/tui/sandbox-integration
+ */
+
+import {
+  detectSandboxBackend,
+  type SandboxConfig,
+  type SandboxExecutionOptions,
+  SandboxExecutor,
+  type SandboxResult,
+} from "@vellum/sandbox";
+
+import { SANDBOX_DENIED_PATHS, SANDBOX_PERMISSIONS, SANDBOX_RESOURCES } from "./config/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface SandboxIntegrationOptions {
+  /** Working directory for command execution */
+  workingDirectory?: string;
+  /** Allow network access in sandbox */
+  allowNetwork?: boolean;
+  /** Allow file system access */
+  allowFileSystem?: boolean;
+  /** Maximum execution time in milliseconds */
+  timeoutMs?: number;
+  /** Maximum output size in bytes */
+  maxOutputBytes?: number;
+  /** Environment variables */
+  environment?: Record<string, string>;
+}
+
+export interface SandboxedExecutionResult {
+  /** Whether execution succeeded */
+  success: boolean;
+  /** Exit code (null if terminated) */
+  exitCode: number | null;
+  /** Standard output */
+  stdout: string;
+  /** Standard error */
+  stderr: string;
+  /** Execution duration in milliseconds */
+  durationMs: number;
+  /** Whether the command was terminated */
+  terminated: boolean;
+  /** Reason for termination if terminated */
+  terminationReason?: string;
+}
+
+// =============================================================================
+// Sandbox Integration
+// =============================================================================
+
+/**
+ * Global sandbox executor instance
+ */
+let sandboxExecutor: SandboxExecutor | null = null;
+
+/**
+ * Initialize the sandbox executor with the given options.
+ *
+ * @param options - Sandbox configuration options
+ * @returns The initialized sandbox executor
+ *
+ * @example
+ * ```typescript
+ * const executor = initializeSandbox({
+ *   workingDirectory: process.cwd(),
+ *   allowNetwork: false,
+ *   allowFileSystem: true,
+ * });
+ * ```
+ */
+export function initializeSandbox(options: SandboxIntegrationOptions = {}): SandboxExecutor {
+  const {
+    workingDirectory = process.cwd(),
+    allowNetwork = SANDBOX_PERMISSIONS.ALLOW_NETWORK,
+    allowFileSystem = SANDBOX_PERMISSIONS.ALLOW_FILE_SYSTEM,
+    timeoutMs = SANDBOX_RESOURCES.TIMEOUT_MS,
+    maxOutputBytes = SANDBOX_RESOURCES.MAX_OUTPUT_BYTES,
+    environment = {},
+  } = options;
+
+  const config: SandboxConfig = {
+    id: `sandbox-${Date.now()}`,
+    strategy: "subprocess",
+    workingDir: workingDirectory,
+    environment,
+    enableAudit: SANDBOX_PERMISSIONS.ENABLE_AUDIT,
+    resources: {
+      cpuTimeMs: timeoutMs,
+      wallTimeMs: timeoutMs + SANDBOX_RESOURCES.WALL_TIME_BUFFER_MS,
+      memoryBytes: SANDBOX_RESOURCES.MEMORY_BYTES,
+      maxFileDescriptors: SANDBOX_RESOURCES.MAX_FILE_DESCRIPTORS,
+      maxProcesses: SANDBOX_RESOURCES.MAX_PROCESSES,
+      maxOutputBytes,
+      maxFileSizeBytes: SANDBOX_RESOURCES.MAX_FILE_SIZE_BYTES,
+    },
+    network: {
+      allowNetwork,
+      allowedHosts: [],
+      allowedPorts: [],
+      blockDns: !allowNetwork,
+    },
+    filesystem: {
+      rootDir: workingDirectory,
+      readOnlyPaths: [],
+      readWritePaths: allowFileSystem ? [workingDirectory] : [],
+      deniedPaths: [...SANDBOX_DENIED_PATHS],
+      useOverlay: SANDBOX_PERMISSIONS.USE_OVERLAY,
+      maxDiskUsageBytes: SANDBOX_RESOURCES.MAX_DISK_USAGE_BYTES,
+    },
+  };
+
+  const backend = detectSandboxBackend();
+  sandboxExecutor = new SandboxExecutor(config, backend);
+
+  return sandboxExecutor;
+}
+
+/**
+ * Get the current sandbox executor, initializing if needed.
+ *
+ * @returns The sandbox executor instance
+ */
+export function getSandboxExecutor(): SandboxExecutor {
+  if (!sandboxExecutor) {
+    sandboxExecutor = initializeSandbox();
+  }
+  return sandboxExecutor;
+}
+
+/**
+ * Execute a command in the sandbox.
+ *
+ * @param command - The command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns The execution result
+ *
+ * @example
+ * ```typescript
+ * const result = await executeSandboxed("ls", ["-la"], {
+ *   cwd: "/project",
+ *   timeoutMs: 5000,
+ * });
+ * if (result.success) {
+ *   console.log(result.stdout);
+ * }
+ * ```
+ */
+export async function executeSandboxed(
+  command: string,
+  args: string[] = [],
+  options: SandboxExecutionOptions = {}
+): Promise<SandboxedExecutionResult> {
+  const executor = getSandboxExecutor();
+
+  const result: SandboxResult = await executor.execute(command, args, options);
+
+  return {
+    success: result.exitCode === 0 && !result.terminated,
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    durationMs: result.durationMs,
+    terminated: result.terminated,
+    terminationReason: result.terminationReason,
+  };
+}
+
+/**
+ * Execute a shell command string in the sandbox.
+ *
+ * @param shellCommand - The shell command string to execute
+ * @param options - Execution options
+ * @returns The execution result
+ *
+ * @example
+ * ```typescript
+ * const result = await executeShellCommand("echo $HOME && pwd", {
+ *   timeoutMs: 10000,
+ * });
+ * ```
+ */
+export async function executeShellCommand(
+  shellCommand: string,
+  options: SandboxExecutionOptions = {}
+): Promise<SandboxedExecutionResult> {
+  const shell = process.platform === "win32" ? "cmd.exe" : "/bin/sh";
+  const shellArgs = process.platform === "win32" ? ["/c", shellCommand] : ["-c", shellCommand];
+
+  return executeSandboxed(shell, shellArgs, options);
+}
+
+/**
+ * Cleanup the sandbox executor.
+ * Should be called on application shutdown.
+ */
+export async function cleanupSandbox(): Promise<void> {
+  if (sandboxExecutor) {
+    await sandboxExecutor.cleanup();
+    sandboxExecutor = null;
+  }
+}
+
+/**
+ * Create a sandboxed executor bound to a specific working directory.
+ *
+ * @param workingDirectory - The working directory
+ * @param options - Additional sandbox options
+ * @returns An object with bound execute functions
+ *
+ * @example
+ * ```typescript
+ * const sandbox = createBoundSandbox("/project/dir");
+ * await sandbox.execute("npm", ["install"]);
+ * await sandbox.shell("npm run build && npm test");
+ * ```
+ */
+export function createBoundSandbox(
+  workingDirectory: string,
+  options: Omit<SandboxIntegrationOptions, "workingDirectory"> = {}
+): {
+  execute: (
+    command: string,
+    args?: string[],
+    execOptions?: Omit<SandboxExecutionOptions, "cwd">
+  ) => Promise<SandboxedExecutionResult>;
+  shell: (
+    shellCommand: string,
+    execOptions?: Omit<SandboxExecutionOptions, "cwd">
+  ) => Promise<SandboxedExecutionResult>;
+  cleanup: () => Promise<void>;
+} {
+  const timeoutMs = options.timeoutMs ?? SANDBOX_RESOURCES.TIMEOUT_MS;
+  const allowNetwork = options.allowNetwork ?? SANDBOX_PERMISSIONS.ALLOW_NETWORK;
+  const allowFileSystem = options.allowFileSystem ?? SANDBOX_PERMISSIONS.ALLOW_FILE_SYSTEM;
+  const maxOutputBytes = options.maxOutputBytes ?? SANDBOX_RESOURCES.MAX_OUTPUT_BYTES;
+
+  // Create a dedicated executor for this directory
+  const config: SandboxConfig = {
+    id: `sandbox-bound-${Date.now()}`,
+    strategy: "subprocess",
+    workingDir: workingDirectory,
+    environment: options.environment ?? {},
+    enableAudit: SANDBOX_PERMISSIONS.ENABLE_AUDIT,
+    resources: {
+      cpuTimeMs: timeoutMs,
+      wallTimeMs: timeoutMs + SANDBOX_RESOURCES.WALL_TIME_BUFFER_MS,
+      memoryBytes: SANDBOX_RESOURCES.MEMORY_BYTES,
+      maxFileDescriptors: SANDBOX_RESOURCES.MAX_FILE_DESCRIPTORS,
+      maxProcesses: SANDBOX_RESOURCES.MAX_PROCESSES,
+      maxOutputBytes,
+      maxFileSizeBytes: SANDBOX_RESOURCES.MAX_FILE_SIZE_BYTES,
+    },
+    network: {
+      allowNetwork,
+      allowedHosts: [],
+      allowedPorts: [],
+      blockDns: !allowNetwork,
+    },
+    filesystem: {
+      rootDir: workingDirectory,
+      readOnlyPaths: [],
+      readWritePaths: allowFileSystem ? [workingDirectory] : [],
+      deniedPaths: [],
+      useOverlay: SANDBOX_PERMISSIONS.USE_OVERLAY,
+      maxDiskUsageBytes: SANDBOX_RESOURCES.MAX_DISK_USAGE_BYTES,
+    },
+  };
+
+  const backend = detectSandboxBackend();
+  const executor = new SandboxExecutor(config, backend);
+
+  return {
+    execute: async (command, args = [], execOptions = {}) => {
+      const result = await executor.execute(command, args, {
+        ...execOptions,
+        cwd: workingDirectory,
+      });
+      return {
+        success: result.exitCode === 0 && !result.terminated,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        durationMs: result.durationMs,
+        terminated: result.terminated,
+        terminationReason: result.terminationReason,
+      };
+    },
+    shell: async (shellCommand, execOptions = {}) => {
+      const shell = process.platform === "win32" ? "cmd.exe" : "/bin/sh";
+      const shellArgs = process.platform === "win32" ? ["/c", shellCommand] : ["-c", shellCommand];
+      const result = await executor.execute(shell, shellArgs, {
+        ...execOptions,
+        cwd: workingDirectory,
+      });
+      return {
+        success: result.exitCode === 0 && !result.terminated,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        durationMs: result.durationMs,
+        terminated: result.terminated,
+        terminationReason: result.terminationReason,
+      };
+    },
+    cleanup: () => executor.cleanup(),
+  };
+}

package/src/tui/services/clipboard.ts

@@ -0,0 +1,348 @@
+/**
+ * Clipboard Service
+ *
+ * Provides cross-platform clipboard access with error handling
+ * for environments that don't support clipboard operations
+ * (e.g., WSL, SSH sessions, headless servers).
+ *
+ * @module tui/services/clipboard
+ */
+
+import clipboard from "clipboardy";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Clipboard history entry
+ */
+export interface ClipboardHistoryEntry {
+  /** The copied text content */
+  readonly text: string;
+  /** Timestamp when the copy occurred */
+  readonly timestamp: number;
+  /** Optional label describing the content */
+  readonly label?: string;
+}
+
+/**
+ * Result of a clipboard operation
+ */
+export type ClipboardResult<T = void> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+/** Maximum number of history entries to keep */
+const MAX_HISTORY_SIZE = 10;
+
+// =============================================================================
+// Module State
+// =============================================================================
+
+/** Clipboard history storage */
+const history: ClipboardHistoryEntry[] = [];
+
+/** Cached support status (null = not yet checked) */
+let supportedCache: boolean | null = null;
+
+// =============================================================================
+// Support Detection
+// =============================================================================
+
+/**
+ * Check if clipboard operations are supported in the current environment.
+ *
+ * Clipboard may not be available in:
+ * - WSL without X server or clipboard integration
+ * - SSH sessions without forwarding
+ * - Headless servers
+ * - Docker containers without display
+ *
+ * @returns true if clipboard operations are likely to work
+ */
+export function isSupported(): boolean {
+  if (supportedCache !== null) {
+    return supportedCache;
+  }
+
+  // Check environment variables that indicate lack of display
+  const noDisplay =
+    !process.env.DISPLAY &&
+    !process.env.WAYLAND_DISPLAY &&
+    process.platform !== "win32" &&
+    process.platform !== "darwin";
+
+  // Check for WSL without Windows clipboard access
+  const isWsl =
+    process.platform === "linux" &&
+    (process.env.WSL_DISTRO_NAME !== undefined || process.env.WSL_INTEROP !== undefined);
+
+  // WSL usually has access to clip.exe/powershell.exe for clipboard
+  // so we'll optimistically allow it
+  if (isWsl) {
+    supportedCache = true;
+    return true;
+  }
+
+  // No display on Linux = likely no clipboard
+  if (noDisplay) {
+    supportedCache = false;
+    return false;
+  }
+
+  // Windows and macOS generally support clipboard
+  supportedCache = true;
+  return true;
+}
+
+/**
+ * Reset the cached support status.
+ * Useful for testing or when environment changes.
+ */
+export function resetSupportCache(): void {
+  supportedCache = null;
+}
+
+// =============================================================================
+// Core Operations
+// =============================================================================
+
+/**
+ * Copy text to the system clipboard.
+ *
+ * @param text - The text to copy
+ * @param label - Optional label for history (e.g., "code block", "file content")
+ * @returns Result indicating success or failure with error message
+ *
+ * @example
+ * ```typescript
+ * const result = await copy("Hello, World!", "greeting");
+ * if (result.success) {
+ *   console.log("Copied successfully");
+ * } else {
+ *   console.error("Copy failed:", result.error);
+ * }
+ * ```
+ */
+export async function copy(text: string, label?: string): Promise<ClipboardResult> {
+  if (!text) {
+    return { success: false, error: "Nothing to copy" };
+  }
+
+  if (!isSupported()) {
+    return {
+      success: false,
+      error: "Clipboard not supported in this environment",
+    };
+  }
+
+  try {
+    await clipboard.write(text);
+
+    // Add to history
+    addToHistory(text, label);
+
+    return { success: true, data: undefined };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    // Provide helpful error messages for common issues
+    if (message.includes("xsel") || message.includes("xclip")) {
+      return {
+        success: false,
+        error: "Clipboard requires xsel or xclip on Linux. Install with: sudo apt install xclip",
+      };
+    }
+
+    return { success: false, error: `Copy failed: ${message}` };
+  }
+}
+
+/**
+ * Synchronous copy operation (best-effort).
+ * Falls back gracefully if async fails.
+ *
+ * @param text - The text to copy
+ * @param label - Optional label for history
+ * @returns true if copy likely succeeded
+ */
+export function copySync(text: string, label?: string): boolean {
+  if (!text || !isSupported()) {
+    return false;
+  }
+
+  try {
+    clipboard.writeSync(text);
+    addToHistory(text, label);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read text from the system clipboard.
+ *
+ * @returns Result with clipboard content or error
+ *
+ * @example
+ * ```typescript
+ * const result = await paste();
+ * if (result.success) {
+ *   console.log("Clipboard content:", result.data);
+ * }
+ * ```
+ */
+export async function paste(): Promise<ClipboardResult<string>> {
+  if (!isSupported()) {
+    return {
+      success: false,
+      error: "Clipboard not supported in this environment",
+    };
+  }
+
+  try {
+    const text = await clipboard.read();
+    return { success: true, data: text };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { success: false, error: `Paste failed: ${message}` };
+  }
+}
+
+/**
+ * Synchronous paste operation.
+ *
+ * @returns Clipboard content or empty string on failure
+ */
+export function pasteSync(): string {
+  if (!isSupported()) {
+    return "";
+  }
+
+  try {
+    return clipboard.readSync();
+  } catch {
+    return "";
+  }
+}
+
+// =============================================================================
+// History Management
+// =============================================================================
+
+/**
+ * Add an entry to the clipboard history.
+ *
+ * @param text - The copied text
+ * @param label - Optional descriptive label
+ */
+function addToHistory(text: string, label?: string): void {
+  const entry: ClipboardHistoryEntry = {
+    text,
+    timestamp: Date.now(),
+    label,
+  };
+
+  // Add to front (most recent first)
+  history.unshift(entry);
+
+  // Trim to max size
+  if (history.length > MAX_HISTORY_SIZE) {
+    history.length = MAX_HISTORY_SIZE;
+  }
+}
+
+/**
+ * Get the clipboard history.
+ *
+ * @param limit - Maximum entries to return (default: all)
+ * @returns Array of history entries, most recent first
+ */
+export function getHistory(limit?: number): readonly ClipboardHistoryEntry[] {
+  if (limit !== undefined && limit > 0) {
+    return history.slice(0, limit);
+  }
+  return [...history];
+}
+
+/**
+ * Get the most recent clipboard entry.
+ *
+ * @returns The most recent entry or undefined if history is empty
+ */
+export function getLastEntry(): ClipboardHistoryEntry | undefined {
+  return history[0];
+}
+
+/**
+ * Clear the clipboard history.
+ */
+export function clearHistory(): void {
+  history.length = 0;
+}
+
+/**
+ * Get the number of entries in history.
+ */
+export function getHistorySize(): number {
+  return history.length;
+}
+
+// =============================================================================
+// Convenience Functions
+// =============================================================================
+
+/**
+ * Copy text and return a user-friendly status message.
+ *
+ * @param text - Text to copy
+ * @param description - What was copied (for the message)
+ * @returns Status message suitable for display
+ */
+export async function copyWithMessage(
+  text: string,
+  description: string
+): Promise<{ success: boolean; message: string }> {
+  const result = await copy(text, description);
+
+  if (result.success) {
+    return {
+      success: true,
+      message: `📋 Copied ${description} (${text.length} chars)`,
+    };
+  }
+
+  return {
+    success: false,
+    message: `❌ ${result.error}`,
+  };
+}
+
+// =============================================================================
+// Default Export
+// =============================================================================
+
+/**
+ * Clipboard service object for convenient access
+ */
+export const clipboardService = {
+  copy,
+  copySync,
+  paste,
+  pasteSync,
+  isSupported,
+  getHistory,
+  getLastEntry,
+  clearHistory,
+  getHistorySize,
+  copyWithMessage,
+  resetSupportCache,
+} as const;
+
+export default clipboardService;