@butlerw/vellum 0.1.0

package/src/tui/config/defaults.ts

@@ -0,0 +1,134 @@
+/**
+ * Sandbox Configuration Defaults
+ *
+ * Centralized configuration constants for sandbox execution.
+ * All values can be overridden via function parameters or environment variables.
+ *
+ * @module cli/tui/config/defaults
+ */
+
+// =============================================================================
+// Environment Variable Helpers
+// =============================================================================
+
+/**
+ * Parse numeric environment variable with fallback.
+ */
+function parseEnvNumber(key: string, fallback: number): number {
+  const value = process.env[key];
+  if (value === undefined) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+
+/**
+ * Parse boolean environment variable with fallback.
+ */
+function parseEnvBoolean(key: string, fallback: boolean): boolean {
+  const value = process.env[key];
+  if (value === undefined) return fallback;
+  return value === "true" || value === "1";
+}
+
+// =============================================================================
+// Size Constants (in bytes)
+// =============================================================================
+
+/** 1 Megabyte in bytes */
+const MB = 1024 * 1024;
+
+// =============================================================================
+// Sandbox Resource Defaults
+// =============================================================================
+
+/**
+ * Default sandbox resource limits.
+ */
+export const SANDBOX_RESOURCES = {
+  /** Default execution timeout in milliseconds (30s) */
+  TIMEOUT_MS: parseEnvNumber("VELLUM_SANDBOX_TIMEOUT_MS", 30_000),
+
+  /** Additional wall time buffer beyond CPU timeout (5s) */
+  WALL_TIME_BUFFER_MS: parseEnvNumber("VELLUM_SANDBOX_WALL_TIME_BUFFER_MS", 5_000),
+
+  /** Maximum memory limit in bytes (512MB) */
+  MEMORY_BYTES: parseEnvNumber("VELLUM_SANDBOX_MEMORY_BYTES", 512 * MB),
+
+  /** Maximum output size in bytes (1MB) */
+  MAX_OUTPUT_BYTES: parseEnvNumber("VELLUM_SANDBOX_MAX_OUTPUT_BYTES", 1 * MB),
+
+  /** Maximum single file size in bytes (50MB) */
+  MAX_FILE_SIZE_BYTES: parseEnvNumber("VELLUM_SANDBOX_MAX_FILE_SIZE_BYTES", 50 * MB),
+
+  /** Maximum disk usage in bytes (100MB) */
+  MAX_DISK_USAGE_BYTES: parseEnvNumber("VELLUM_SANDBOX_MAX_DISK_USAGE_BYTES", 100 * MB),
+
+  /** Maximum number of file descriptors */
+  MAX_FILE_DESCRIPTORS: parseEnvNumber("VELLUM_SANDBOX_MAX_FILE_DESCRIPTORS", 100),
+
+  /** Maximum number of spawned processes */
+  MAX_PROCESSES: parseEnvNumber("VELLUM_SANDBOX_MAX_PROCESSES", 10),
+} as const;
+
+/**
+ * Default sandbox permission settings.
+ */
+export const SANDBOX_PERMISSIONS = {
+  /** Allow network access by default */
+  ALLOW_NETWORK: parseEnvBoolean("VELLUM_SANDBOX_ALLOW_NETWORK", false),
+
+  /** Allow file system access by default */
+  ALLOW_FILE_SYSTEM: parseEnvBoolean("VELLUM_SANDBOX_ALLOW_FILE_SYSTEM", true),
+
+  /** Use overlay filesystem */
+  USE_OVERLAY: parseEnvBoolean("VELLUM_SANDBOX_USE_OVERLAY", false),
+
+  /** Enable audit logging */
+  ENABLE_AUDIT: parseEnvBoolean("VELLUM_SANDBOX_ENABLE_AUDIT", false),
+} as const;
+
+/**
+ * Default security paths to deny access.
+ * These paths are blocked for security reasons.
+ */
+export const SANDBOX_DENIED_PATHS = ["/etc/passwd", "/etc/shadow"] as const;
+
+// =============================================================================
+// Aggregated Defaults
+// =============================================================================
+
+/**
+ * Complete sandbox defaults configuration.
+ * Import and spread to apply all defaults with optional overrides.
+ *
+ * @example
+ * ```typescript
+ * import { SANDBOX_DEFAULTS } from './config/defaults';
+ *
+ * const config = {
+ *   ...SANDBOX_DEFAULTS.resources,
+ *   timeoutMs: 60_000, // Override timeout
+ * };
+ * ```
+ */
+export const SANDBOX_DEFAULTS = {
+  /** Resource limits */
+  resources: SANDBOX_RESOURCES,
+  /** Permission settings */
+  permissions: SANDBOX_PERMISSIONS,
+  /** Denied filesystem paths */
+  deniedPaths: SANDBOX_DENIED_PATHS,
+} as const;
+
+// =============================================================================
+// Type Exports
+// =============================================================================
+
+/** Type for sandbox resource configuration */
+export type SandboxResourceConfig = typeof SANDBOX_RESOURCES;
+
+/** Type for sandbox permission configuration */
+export type SandboxPermissionConfig = typeof SANDBOX_PERMISSIONS;
+
+/** Type for complete sandbox defaults */
+export type SandboxDefaultsConfig = typeof SANDBOX_DEFAULTS;

package/src/tui/config/index.ts

@@ -0,0 +1,17 @@
+/**
+ * TUI Configuration Module
+ *
+ * Re-exports all configuration constants and types.
+ *
+ * @module cli/tui/config
+ */
+
+export {
+  SANDBOX_DEFAULTS,
+  SANDBOX_DENIED_PATHS,
+  SANDBOX_PERMISSIONS,
+  SANDBOX_RESOURCES,
+  type SandboxDefaultsConfig,
+  type SandboxPermissionConfig,
+  type SandboxResourceConfig,
+} from "./defaults.js";

package/src/tui/context/AnimationContext.tsx

@@ -0,0 +1,284 @@
+/**
+ * Animation Context
+ *
+ * Global animation context that provides:
+ * 1. A centralized animation frame counter
+ * 2. FPS limiting to prevent excessive re-renders (60 FPS max)
+ * 3. VS Code terminal detection for adaptive timing
+ *
+ * All animated components should subscribe to this instead of individual timers
+ * to reduce flickering and improve performance.
+ *
+ * @module tui/context/AnimationContext
+ */
+
+import type React from "react";
+import type { ReactNode } from "react";
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from "react";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Minimum frame interval (~60 FPS) to prevent excessive re-renders */
+const MIN_FRAME_INTERVAL_MS = 16;
+
+/** Base animation tick interval */
+const BASE_ANIMATION_TICK_MS = 120;
+
+/** Extended animation tick for VS Code terminal (more conservative) */
+const VSCODE_ANIMATION_TICK_MS = 200;
+
+// =============================================================================
+// Environment Detection
+// =============================================================================
+
+/**
+ * Detects if running inside VS Code integrated terminal.
+ * VS Code terminals benefit from slightly longer intervals to reduce flickering.
+ */
+function isVSCodeTerminal(): boolean {
+  return (
+    process.env.TERM_PROGRAM === "vscode" ||
+    process.env.VSCODE_INJECTION === "1" ||
+    !!process.env.VSCODE_GIT_IPC_HANDLE
+  );
+}
+
+/**
+ * Gets the optimal animation tick interval based on terminal environment.
+ * VS Code terminals use a longer interval to reduce flickering.
+ */
+function getAnimationTick(): number {
+  // Allow environment override for debugging
+  const envTick = Number(process.env.VELLUM_ANIMATION_TICK);
+  if (Number.isFinite(envTick) && envTick > 0) {
+    return envTick;
+  }
+
+  return isVSCodeTerminal() ? VSCODE_ANIMATION_TICK_MS : BASE_ANIMATION_TICK_MS;
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Animation context state
+ */
+export interface AnimationState {
+  /** Current animation frame counter (monotonically increasing) */
+  readonly frame: number;
+  /** Current timestamp in milliseconds */
+  readonly timestamp: number;
+}
+
+/**
+ * Animation context value
+ */
+export interface AnimationContextValue extends AnimationState {
+  /** Whether running in VS Code terminal */
+  readonly isVSCode: boolean;
+  /** Current animation tick interval in ms */
+  readonly tickInterval: number;
+  /** Whether animations are currently paused */
+  readonly isPaused: boolean;
+  /** Pause all animations (useful during text input to reduce flickering) */
+  readonly pauseAnimations: () => void;
+  /** Resume animations after pausing */
+  readonly resumeAnimations: () => void;
+}
+
+/**
+ * Props for the AnimationProvider component
+ */
+export interface AnimationProviderProps {
+  /** Children to render */
+  readonly children: ReactNode;
+  /** Override the animation tick interval (for testing) */
+  readonly tickInterval?: number;
+}
+
+// =============================================================================
+// Context
+// =============================================================================
+
+const initialState: AnimationContextValue = {
+  frame: 0,
+  timestamp: Date.now(),
+  isVSCode: isVSCodeTerminal(),
+  tickInterval: getAnimationTick(),
+  isPaused: false,
+  pauseAnimations: () => {},
+  resumeAnimations: () => {},
+};
+
+/**
+ * Animation context - provides global animation frame and timing
+ */
+export const AnimationContext = createContext<AnimationContextValue>(initialState);
+
+// =============================================================================
+// Provider Component
+// =============================================================================
+
+/**
+ * Animation provider that manages a global animation loop.
+ *
+ * Features:
+ * - Single timer for all animated components
+ * - FPS limiting to prevent excessive renders
+ * - VS Code terminal detection for adaptive timing
+ * - Environment variable override for debugging
+ *
+ * @example
+ * ```tsx
+ * // In root provider
+ * <AnimationProvider>
+ *   <App />
+ * </AnimationProvider>
+ *
+ * // Override tick for testing
+ * <AnimationProvider tickInterval={200}>
+ *   <SlowAnimatedComponent />
+ * </AnimationProvider>
+ * ```
+ */
+export function AnimationProvider({
+  children,
+  tickInterval: tickOverride,
+}: AnimationProviderProps): React.JSX.Element {
+  const tickInterval = tickOverride ?? getAnimationTick();
+  const isVSCode = isVSCodeTerminal();
+
+  const [state, setState] = useState<AnimationState>({
+    frame: 0,
+    timestamp: Date.now(),
+  });
+
+  const [isPaused, setIsPaused] = useState(false);
+  const isPausedRef = useRef(false);
+  const lastRenderRef = useRef(Date.now());
+
+  // Stable pause/resume callbacks
+  const pauseAnimations = useCallback(() => {
+    isPausedRef.current = true;
+    setIsPaused(true);
+  }, []);
+
+  const resumeAnimations = useCallback(() => {
+    isPausedRef.current = false;
+    setIsPaused(false);
+  }, []);
+
+  useEffect(() => {
+    // Don't start timer when paused - completely stops animation overhead
+    if (isPaused) return;
+
+    let mounted = true;
+
+    const tick = () => {
+      if (!mounted) return;
+
+      const now = Date.now();
+      const sinceLastRender = now - lastRenderRef.current;
+
+      // FPS limiter: ensure minimum interval since last render
+      if (sinceLastRender >= MIN_FRAME_INTERVAL_MS) {
+        lastRenderRef.current = now;
+        setState((prev) => ({
+          frame: prev.frame + 1,
+          timestamp: now,
+        }));
+      }
+    };
+
+    // Use setInterval for consistent timing in terminal environments
+    // requestAnimationFrame is designed for visual rendering, not terminal output
+    const timer = setInterval(tick, tickInterval);
+
+    return () => {
+      mounted = false;
+      clearInterval(timer);
+    };
+  }, [tickInterval, isPaused]);
+
+  const contextValue: AnimationContextValue = {
+    ...state,
+    isVSCode,
+    tickInterval,
+    isPaused,
+    pauseAnimations,
+    resumeAnimations,
+  };
+
+  return <AnimationContext.Provider value={contextValue}>{children}</AnimationContext.Provider>;
+}
+
+// =============================================================================
+// Hooks
+// =============================================================================
+
+/**
+ * Hook to access the full animation context.
+ *
+ * Returns safe defaults if context is not available (e.g., when rendered
+ * outside AnimationProvider). This prevents "Rendered more hooks than
+ * during the previous render" errors.
+ *
+ * @returns Animation context value with frame, timestamp, and metadata
+ *
+ * @example
+ * ```tsx
+ * function AnimatedComponent() {
+ *   const { frame, timestamp, isVSCode } = useAnimation();
+ *   // Use frame/timestamp for animations
+ * }
+ * ```
+ */
+export function useAnimation(): AnimationContextValue {
+  const context = useContext(AnimationContext);
+  // Return safe defaults if context is not available
+  // This prevents hook count errors when rendered outside AnimationProvider
+  if (!context) {
+    return initialState;
+  }
+  return context;
+}
+
+/**
+ * Hook to get the current animation frame index for a set of frames.
+ *
+ * This is the recommended way to animate through a sequence of frames
+ * (like spinner characters) without managing your own state or timer.
+ *
+ * @param frames - Array of frames or number of total frames
+ * @returns Current frame index (0 to frames.length-1 or 0 to frames-1)
+ *
+ * @example
+ * ```tsx
+ * // With array of frames
+ * const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+ * function Spinner() {
+ *   const frameIndex = useAnimationFrame(SPINNER_FRAMES);
+ *   return <Text>{SPINNER_FRAMES[frameIndex]}</Text>;
+ * }
+ *
+ * // With frame count
+ * function FourPhaseAnimation() {
+ *   const phase = useAnimationFrame(4);
+ *   return <Text>Phase {phase + 1}</Text>;
+ * }
+ * ```
+ */
+export function useAnimationFrame(frames: readonly unknown[] | number): number {
+  const { frame } = useAnimation();
+  const frameCount = typeof frames === "number" ? frames : frames.length;
+  return frameCount > 0 ? frame % frameCount : 0;
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export default AnimationProvider;