@butlerw/vellum 0.1.0

package/src/tui/hooks/useDesktopNotification.ts

@@ -0,0 +1,414 @@
+/**
+ * useDesktopNotification Hook (T059)
+ *
+ * React hook for sending desktop notifications from the TUI.
+ * Detects node-notifier availability and provides graceful fallback.
+ *
+ * @module @vellum/cli
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { ICONS } from "../../utils/icons.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Notification priority levels.
+ */
+export type NotificationPriority = "low" | "normal" | "high" | "urgent";
+
+/**
+ * Notification type categorization.
+ */
+export type NotificationType =
+  | "task-complete"
+  | "permission-request"
+  | "error"
+  | "warning"
+  | "info";
+
+/**
+ * Options for a notification.
+ */
+export interface NotificationOptions {
+  /** Title of the notification */
+  readonly title: string;
+  /** Body message */
+  readonly message: string;
+  /** Optional subtitle (macOS) */
+  readonly subtitle?: string;
+  /** Notification type for categorization */
+  readonly type?: NotificationType;
+  /** Priority level */
+  readonly priority?: NotificationPriority;
+  /** Whether the notification should make a sound */
+  readonly sound?: boolean;
+  /** Time in ms after which to auto-dismiss (0 = no auto-dismiss) */
+  readonly timeout?: number;
+  /** Optional icon path */
+  readonly icon?: string;
+  /** Optional click action callback */
+  readonly onClick?: () => void;
+  /** Optional close action callback */
+  readonly onClose?: () => void;
+}
+
+/**
+ * Configuration for the notification hook.
+ */
+export interface UseDesktopNotificationOptions {
+  /** Whether notifications are enabled (default: true) */
+  readonly enabled?: boolean;
+  /** Default sound setting (default: true) */
+  readonly defaultSound?: boolean;
+  /** Minimum time between notifications in ms (default: 1000) */
+  readonly throttleMs?: number;
+  /** Application name for notifications */
+  readonly appName?: string;
+  /** Whether to show notifications only when terminal is not focused */
+  readonly onlyWhenUnfocused?: boolean;
+}
+
+/**
+ * Return value of useDesktopNotification hook.
+ */
+export interface UseDesktopNotificationReturn {
+  /** Whether notifications are available (node-notifier detected) */
+  readonly isAvailable: boolean;
+  /** Whether notifications are currently enabled */
+  readonly isEnabled: boolean;
+  /** Send a notification */
+  readonly notify: (options: NotificationOptions) => void;
+  /** Notify when a long task completes */
+  readonly notifyTaskComplete: (taskName: string, duration?: number) => void;
+  /** Notify for a permission request */
+  readonly notifyPermissionRequest: (permission: string) => void;
+  /** Notify for an error */
+  readonly notifyError: (message: string) => void;
+  /** Toggle notifications on/off */
+  readonly toggle: () => void;
+  /** Enable notifications */
+  readonly enable: () => void;
+  /** Disable notifications */
+  readonly disable: () => void;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default throttle time between notifications */
+const DEFAULT_THROTTLE_MS = 1000;
+
+/** Default app name */
+const DEFAULT_APP_NAME = "Vellum";
+
+/** Icons for different notification types */
+const TYPE_ICONS: Record<NotificationType, string> = {
+  "task-complete": ICONS.success,
+  "permission-request": "[Auth]",
+  error: ICONS.error,
+  warning: ICONS.warning,
+  info: ICONS.info,
+};
+
+// =============================================================================
+// Node-Notifier Detection & Wrapper
+// =============================================================================
+
+/**
+ * Lazy-loaded notifier module.
+ */
+let notifierModule: NotifierModule | null = null;
+let notifierChecked = false;
+
+interface NotifierModule {
+  notify(
+    options: {
+      title?: string;
+      message?: string;
+      subtitle?: string;
+      sound?: boolean;
+      icon?: string;
+      timeout?: number;
+      appID?: string;
+    },
+    callback?: (err: Error | null, response: string) => void
+  ): void;
+}
+
+/**
+ * Attempt to load node-notifier dynamically.
+ */
+async function loadNotifier(): Promise<NotifierModule | null> {
+  if (notifierChecked) {
+    return notifierModule;
+  }
+
+  notifierChecked = true;
+
+  try {
+    // Dynamic import to avoid hard dependency
+    // Using a variable to prevent TypeScript from resolving the module at compile time
+    const moduleName = "node-notifier";
+    const module = await import(moduleName);
+    notifierModule = module.default ?? module;
+    return notifierModule;
+  } catch {
+    // node-notifier not available - that's fine
+    return null;
+  }
+}
+
+/**
+ * Check if we're running in a focused terminal.
+ * This is a heuristic check - not 100% reliable.
+ */
+function isTerminalFocused(): boolean {
+  // Check if running interactively
+  if (!process.stdin.isTTY) {
+    return false;
+  }
+
+  // In most cases, if we're running in a TTY and stdout is a TTY,
+  // the terminal is likely focused. This is imperfect but reasonable.
+  return process.stdout.isTTY ?? false;
+}
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook for sending desktop notifications.
+ *
+ * Automatically detects if node-notifier is available and provides
+ * a graceful fallback when it's not. Useful for notifying users
+ * when long-running tasks complete or when permission is needed.
+ *
+ * @example
+ * ```tsx
+ * function LongTaskRunner() {
+ *   const { notify, notifyTaskComplete, isAvailable } = useDesktopNotification({
+ *     appName: 'Vellum',
+ *   });
+ *
+ *   const runTask = async () => {
+ *     const start = Date.now();
+ *     await performLongTask();
+ *     notifyTaskComplete('Build', Date.now() - start);
+ *   };
+ *
+ *   return (
+ *     <Box>
+ *       <Text>Notifications: {isAvailable ? 'Available' : 'Not available'}</Text>
+ *     </Box>
+ *   );
+ * }
+ * ```
+ */
+export function useDesktopNotification(
+  options: UseDesktopNotificationOptions = {}
+): UseDesktopNotificationReturn {
+  const {
+    enabled: initialEnabled = true,
+    defaultSound = true,
+    throttleMs = DEFAULT_THROTTLE_MS,
+    appName = DEFAULT_APP_NAME,
+    onlyWhenUnfocused = true,
+  } = options;
+
+  const [isAvailable, setIsAvailable] = useState(false);
+  const [isEnabled, setIsEnabled] = useState(initialEnabled);
+  const lastNotificationTime = useRef(0);
+  const notifierRef = useRef<NotifierModule | null>(null);
+
+  // Load notifier on mount
+  useEffect(() => {
+    let mounted = true;
+
+    loadNotifier().then((notifier) => {
+      if (mounted && notifier) {
+        notifierRef.current = notifier;
+        setIsAvailable(true);
+      }
+    });
+
+    return () => {
+      mounted = false;
+    };
+  }, []);
+
+  // Core notification function
+  const notify = useCallback(
+    (notifOptions: NotificationOptions) => {
+      // Check if we should notify
+      if (!isEnabled || !isAvailable || !notifierRef.current) {
+        return;
+      }
+
+      // Check focus state
+      if (onlyWhenUnfocused && isTerminalFocused()) {
+        return;
+      }
+
+      // Throttle notifications
+      const now = Date.now();
+      if (now - lastNotificationTime.current < throttleMs) {
+        return;
+      }
+      lastNotificationTime.current = now;
+
+      const {
+        title,
+        message,
+        subtitle,
+        type,
+        sound = defaultSound,
+        timeout,
+        icon,
+        onClick,
+        onClose,
+      } = notifOptions;
+
+      // Build notification title with type icon
+      const typeIcon = type ? TYPE_ICONS[type] : "";
+      const fullTitle = typeIcon ? `${typeIcon} ${title}` : title;
+
+      // Send notification
+      notifierRef.current.notify(
+        {
+          title: fullTitle,
+          message,
+          subtitle,
+          sound,
+          icon,
+          timeout,
+          appID: appName,
+        },
+        (err, response) => {
+          if (err) {
+            // Silently handle errors - notifications are non-critical
+            return;
+          }
+
+          // Handle click/close callbacks based on response
+          if (response === "activate" || response === "clicked") {
+            onClick?.();
+          } else if (response === "dismissed" || response === "timeout") {
+            onClose?.();
+          }
+        }
+      );
+    },
+    [isEnabled, isAvailable, onlyWhenUnfocused, throttleMs, defaultSound, appName]
+  );
+
+  // Convenience: Notify task completion
+  const notifyTaskComplete = useCallback(
+    (taskName: string, duration?: number) => {
+      const durationText = duration ? ` (${formatDuration(duration)})` : "";
+      notify({
+        title: "Task Complete",
+        message: `${taskName} finished${durationText}`,
+        type: "task-complete",
+        priority: "normal",
+      });
+    },
+    [notify]
+  );
+
+  // Convenience: Notify permission request
+  const notifyPermissionRequest = useCallback(
+    (permission: string) => {
+      notify({
+        title: "Permission Required",
+        message: `${permission} - please review and approve`,
+        type: "permission-request",
+        priority: "high",
+        sound: true,
+      });
+    },
+    [notify]
+  );
+
+  // Convenience: Notify error
+  const notifyError = useCallback(
+    (message: string) => {
+      notify({
+        title: "Error",
+        message,
+        type: "error",
+        priority: "urgent",
+        sound: true,
+      });
+    },
+    [notify]
+  );
+
+  // Toggle/enable/disable
+  const toggle = useCallback(() => {
+    setIsEnabled((prev) => !prev);
+  }, []);
+
+  const enable = useCallback(() => {
+    setIsEnabled(true);
+  }, []);
+
+  const disable = useCallback(() => {
+    setIsEnabled(false);
+  }, []);
+
+  return useMemo(
+    () => ({
+      isAvailable,
+      isEnabled,
+      notify,
+      notifyTaskComplete,
+      notifyPermissionRequest,
+      notifyError,
+      toggle,
+      enable,
+      disable,
+    }),
+    [
+      isAvailable,
+      isEnabled,
+      notify,
+      notifyTaskComplete,
+      notifyPermissionRequest,
+      notifyError,
+      toggle,
+      enable,
+      disable,
+    ]
+  );
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Format duration in milliseconds to human-readable string.
+ */
+function formatDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) {
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+  }
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours}h ${remainingMinutes}m`;
+}

package/src/tui/hooks/useDiffMode.ts

@@ -0,0 +1,44 @@
+/**
+ * useDiffMode Hook
+ *
+ * React hook for subscribing to diff view mode changes.
+ * Connects DiffView components to the global diff mode state.
+ *
+ * @module tui/hooks/useDiffMode
+ */
+
+import { useEffect, useState } from "react";
+import { getDiffMode, subscribeDiffMode } from "../../commands/diff-mode.js";
+import type { DiffViewMode } from "../i18n/index.js";
+
+/**
+ * Hook return type for diff mode state.
+ */
+export interface UseDiffModeReturn {
+  /** Current diff view mode */
+  readonly mode: DiffViewMode;
+}
+
+/**
+ * React hook for subscribing to diff view mode changes.
+ *
+ * @returns Current diff view mode that updates on change
+ *
+ * @example
+ * ```tsx
+ * function MyDiffComponent({ diff }: { diff: string }) {
+ *   const { mode } = useDiffMode();
+ *   return <DiffView diff={diff} mode={mode} />;
+ * }
+ * ```
+ */
+export function useDiffMode(): UseDiffModeReturn {
+  const [mode, setMode] = useState<DiffViewMode>(getDiffMode());
+
+  useEffect(() => {
+    // Subscribe to mode changes and return unsubscribe function
+    return subscribeDiffMode(setMode);
+  }, []);
+
+  return { mode };
+}

package/src/tui/hooks/useFileChangeStats.ts

@@ -0,0 +1,110 @@
+/**
+ * File Change Statistics Hook
+ *
+ * Aggregates diff metadata from tool executions to provide
+ * cumulative statistics about file changes in the current session.
+ *
+ * @module tui/hooks/useFileChangeStats
+ */
+
+import { useMemo } from "react";
+import { useTools } from "../context/ToolsContext.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Diff metadata from tool results (matches @vellum/core DiffMetadata)
+ */
+interface DiffMetadata {
+  /** Unified diff string */
+  diff: string;
+  /** Number of lines added */
+  additions: number;
+  /** Number of lines deleted */
+  deletions: number;
+}
+
+/**
+ * Aggregated file change statistics
+ */
+export interface FileChangeStats {
+  /** Total number of lines added across all files */
+  readonly additions: number;
+  /** Total number of lines deleted across all files */
+  readonly deletions: number;
+  /** Number of unique files modified */
+  readonly filesModified: number;
+}
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Type guard for DiffMetadata
+ */
+function isDiffMetadata(value: unknown): value is DiffMetadata {
+  if (!value || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.additions === "number" &&
+    typeof obj.deletions === "number" &&
+    typeof obj.diff === "string"
+  );
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Aggregates file change statistics from completed tool executions.
+ *
+ * Extracts `diffMeta` from tool results and accumulates additions/deletions.
+ * Also tracks unique file paths modified.
+ *
+ * @example
+ * ```tsx
+ * const { additions, deletions, filesModified } = useFileChangeStats();
+ * // additions: 42, deletions: 15, filesModified: 3
+ * ```
+ */
+export function useFileChangeStats(): FileChangeStats {
+  const { executions } = useTools();
+
+  return useMemo(() => {
+    let additions = 0;
+    let deletions = 0;
+    const paths = new Set<string>();
+
+    for (const exec of executions) {
+      // Only count completed executions
+      if (exec.status !== "complete") continue;
+
+      // Tool results may have diffMeta
+      const result = exec.result as Record<string, unknown> | undefined;
+      if (!result) continue;
+
+      // Extract diff metadata if present
+      const diffMeta = result.diffMeta;
+      if (isDiffMetadata(diffMeta)) {
+        additions += diffMeta.additions;
+        deletions += diffMeta.deletions;
+      }
+
+      // Track unique file paths
+      const path = result.path;
+      if (typeof path === "string" && path.length > 0) {
+        paths.add(path);
+      }
+    }
+
+    return {
+      additions,
+      deletions,
+      filesModified: paths.size,
+    };
+  }, [executions]);
+}