@butlerw/vellum 0.1.0

package/src/tui/components/session/CheckpointPanel.tsx

@@ -0,0 +1,323 @@
+/**
+ * CheckpointPanel Component
+ *
+ * Modal panel for managing session checkpoints.
+ * Allows viewing, creating, and rolling back to checkpoints.
+ *
+ * @module tui/components/session/CheckpointPanel
+ */
+
+import type { SessionCheckpoint } from "@vellum/core";
+import { Box, Text, useInput } from "ink";
+import type React from "react";
+import { useCallback, useState } from "react";
+import { useTUITranslation } from "../../i18n/index.js";
+import { useTheme } from "../../theme/index.js";
+import { truncateToDisplayWidth } from "../../utils/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the CheckpointPanel component
+ */
+export interface CheckpointPanelProps {
+  /** List of checkpoints to display */
+  readonly checkpoints: readonly SessionCheckpoint[];
+  /** Current message count (for calculating messages to lose) */
+  readonly currentMessageCount: number;
+  /** Whether the panel is open */
+  readonly isOpen: boolean;
+  /** Callback when a checkpoint is selected for rollback */
+  readonly onRollback: (checkpointId: string) => void;
+  /** Callback when a new checkpoint is requested */
+  readonly onCreateCheckpoint: (description?: string) => void;
+  /** Callback when a checkpoint is deleted */
+  readonly onDeleteCheckpoint: (checkpointId: string) => void;
+  /** Callback to close the panel */
+  readonly onClose: () => void;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Format a date for display.
+ */
+function formatDate(date: Date): string {
+  const now = new Date();
+  const isToday =
+    date.getDate() === now.getDate() &&
+    date.getMonth() === now.getMonth() &&
+    date.getFullYear() === now.getFullYear();
+
+  if (isToday) {
+    return date.toLocaleTimeString(undefined, {
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  }
+
+  return date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/**
+ * Truncate text with ellipsis.
+ * Uses string-width for accurate CJK/Emoji handling.
+ */
+function truncate(text: string, maxLength: number): string {
+  return truncateToDisplayWidth(text, maxLength);
+}
+
+// =============================================================================
+// CheckpointItem Sub-Component
+// =============================================================================
+
+interface CheckpointItemProps {
+  readonly checkpoint: SessionCheckpoint;
+  readonly isSelected: boolean;
+  readonly messagesToLose: number;
+  readonly primaryColor: string;
+  readonly warningColor: string;
+  readonly textColor: string;
+  readonly mutedColor: string;
+}
+
+function CheckpointItem({
+  checkpoint,
+  isSelected,
+  messagesToLose,
+  primaryColor,
+  warningColor,
+  textColor,
+  mutedColor,
+}: CheckpointItemProps): React.JSX.Element {
+  const indicator = isSelected ? "▶" : " ";
+  const description = checkpoint.description ?? "(no description)";
+  const idShort = checkpoint.id.slice(0, 8);
+  const dateStr = formatDate(new Date(checkpoint.createdAt));
+
+  return (
+    <Box flexDirection="row" paddingX={1}>
+      <Text color={isSelected ? primaryColor : mutedColor}>{indicator} </Text>
+      <Box flexDirection="row" justifyContent="space-between" flexGrow={1}>
+        <Box flexDirection="row" gap={1}>
+          <Text color={isSelected ? primaryColor : mutedColor} dimColor={!isSelected}>
+            [{idShort}]
+          </Text>
+          <Text color={isSelected ? primaryColor : textColor} bold={isSelected}>
+            {truncate(description, 30)}
+          </Text>
+        </Box>
+        <Box flexDirection="row" gap={1}>
+          <Text color={mutedColor}>{dateStr}</Text>
+          <Text color={mutedColor}>|</Text>
+          <Text color={mutedColor}>msg #{checkpoint.messageIndex}</Text>
+          {messagesToLose > 0 && <Text color={warningColor}>(-{messagesToLose})</Text>}
+        </Box>
+      </Box>
+    </Box>
+  );
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * CheckpointPanel displays and manages session checkpoints.
+ *
+ * Keybindings:
+ * - j/k or ↑/↓: Navigate checkpoints
+ * - Enter: Rollback to selected checkpoint
+ * - n: Create new checkpoint
+ * - d: Delete selected checkpoint
+ * - Escape/q: Close panel
+ *
+ * @example
+ * ```tsx
+ * <CheckpointPanel
+ *   checkpoints={checkpoints}
+ *   currentMessageCount={messages.length}
+ *   isOpen={showPanel}
+ *   onRollback={(id) => handleRollback(id)}
+ *   onCreateCheckpoint={(desc) => handleCreate(desc)}
+ *   onDeleteCheckpoint={(id) => handleDelete(id)}
+ *   onClose={() => setShowPanel(false)}
+ * />
+ * ```
+ */
+export function CheckpointPanel({
+  checkpoints,
+  currentMessageCount,
+  isOpen,
+  onRollback,
+  onCreateCheckpoint,
+  onDeleteCheckpoint,
+  onClose,
+}: CheckpointPanelProps): React.JSX.Element | null {
+  const { theme } = useTheme();
+  const { t } = useTUITranslation();
+
+  // Selection state
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  // Get colors from theme
+  const primaryColor = theme.brand.primary;
+  const warningColor = theme.colors.warning;
+  const textColor = theme.semantic.text.primary;
+  const mutedColor = theme.semantic.text.muted;
+  const borderColor = theme.semantic.border.default;
+
+  /**
+   * Calculate messages that would be lost for a checkpoint.
+   */
+  const getMessagesToLose = useCallback(
+    (checkpoint: SessionCheckpoint): number => {
+      return currentMessageCount - checkpoint.messageIndex;
+    },
+    [currentMessageCount]
+  );
+
+  /**
+   * Handle navigation keys (j/k, arrows)
+   */
+  const handleNavigation = useCallback(
+    (input: string, key: { downArrow: boolean; upArrow: boolean }): boolean => {
+      if (input === "j" || key.downArrow) {
+        setSelectedIndex((prev) => Math.min(prev + 1, checkpoints.length - 1));
+        return true;
+      }
+      if (input === "k" || key.upArrow) {
+        setSelectedIndex((prev) => Math.max(prev - 1, 0));
+        return true;
+      }
+      return false;
+    },
+    [checkpoints.length]
+  );
+
+  /**
+   * Handle action keys (Enter, n, d)
+   */
+  const handleAction = useCallback(
+    (input: string, key: { return: boolean }): boolean => {
+      if (key.return && checkpoints.length > 0) {
+        const checkpoint = checkpoints[selectedIndex];
+        if (checkpoint) {
+          onRollback(checkpoint.id);
+        }
+        return true;
+      }
+      if (input === "n") {
+        onCreateCheckpoint();
+        return true;
+      }
+      if (input === "d" && checkpoints.length > 0) {
+        const checkpoint = checkpoints[selectedIndex];
+        if (checkpoint) {
+          onDeleteCheckpoint(checkpoint.id);
+          if (selectedIndex >= checkpoints.length - 1) {
+            setSelectedIndex(Math.max(0, checkpoints.length - 2));
+          }
+        }
+        return true;
+      }
+      return false;
+    },
+    [checkpoints, selectedIndex, onRollback, onCreateCheckpoint, onDeleteCheckpoint]
+  );
+
+  /**
+   * Handle keyboard input.
+   */
+  useInput(
+    (input, key) => {
+      if (handleNavigation(input, key)) return;
+      if (handleAction(input, key)) return;
+      if (key.escape || input === "q") {
+        onClose();
+      }
+    },
+    { isActive: isOpen }
+  );
+
+  if (!isOpen) {
+    return null;
+  }
+
+  const isEmpty = checkpoints.length === 0;
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="double"
+      borderColor={borderColor}
+      paddingX={1}
+      paddingY={0}
+    >
+      {/* Header */}
+      <Box flexDirection="row" justifyContent="space-between" marginBottom={1}>
+        <Text bold color={primaryColor}>
+          📌 {t("persistence.checkpoint.title")}
+        </Text>
+        <Text dimColor>j/k navigate • Enter rollback • n new • d delete • Esc close</Text>
+      </Box>
+
+      {/* Checkpoint List */}
+      {isEmpty ? (
+        <Box paddingX={1} paddingY={1}>
+          <Text color={mutedColor}>{t("persistence.checkpoint.empty")}</Text>
+        </Box>
+      ) : (
+        <Box flexDirection="column">
+          {checkpoints.map((checkpoint, index) => (
+            <CheckpointItem
+              key={checkpoint.id}
+              checkpoint={checkpoint}
+              isSelected={index === selectedIndex}
+              messagesToLose={getMessagesToLose(checkpoint)}
+              primaryColor={primaryColor}
+              warningColor={warningColor}
+              textColor={textColor}
+              mutedColor={mutedColor}
+            />
+          ))}
+        </Box>
+      )}
+
+      {/* Footer - Warning for selected checkpoint */}
+      {!isEmpty &&
+        (() => {
+          const selectedCheckpoint = checkpoints[selectedIndex];
+          if (!selectedCheckpoint) return null;
+          const messagesToLose = getMessagesToLose(selectedCheckpoint);
+          return (
+            <Box marginTop={1} paddingX={1}>
+              {messagesToLose > 0 ? (
+                <Text color={warningColor}>
+                  ⚠ Rollback will remove {messagesToLose} message
+                  {messagesToLose === 1 ? "" : "s"}
+                </Text>
+              ) : (
+                <Text color={mutedColor}>Already at this checkpoint</Text>
+              )}
+            </Box>
+          );
+        })()}
+    </Box>
+  );
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export default CheckpointPanel;

package/src/tui/components/session/RollbackDialog.tsx

@@ -0,0 +1,169 @@
+/**
+ * RollbackDialog Component
+ *
+ * Modal confirmation dialog for session rollback operations.
+ * Displays a warning about data loss and requires user confirmation.
+ *
+ * @module tui/components/session/RollbackDialog
+ */
+
+import type { SessionCheckpoint } from "@vellum/core";
+import { Box, Text, useInput } from "ink";
+import type React from "react";
+import { useTUITranslation } from "../../i18n/index.js";
+import { useTheme } from "../../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the RollbackDialog component
+ */
+export interface RollbackDialogProps {
+  /** Checkpoint to rollback to */
+  readonly checkpoint: SessionCheckpoint | null;
+  /** Number of messages that will be lost */
+  readonly messagesToLose: number;
+  /** Whether the dialog is open */
+  readonly isOpen: boolean;
+  /** Callback when user confirms rollback */
+  readonly onConfirm: () => void;
+  /** Callback when user cancels */
+  readonly onCancel: () => void;
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * RollbackDialog displays a confirmation prompt for rollback operations.
+ *
+ * Features:
+ * - Shows checkpoint details
+ * - Displays warning about message loss
+ * - y/n confirmation
+ * - Red warning styling
+ *
+ * Keybindings:
+ * - y/Y/Enter: Confirm rollback
+ * - n/N/Escape: Cancel
+ *
+ * @example
+ * ```tsx
+ * <RollbackDialog
+ *   checkpoint={selectedCheckpoint}
+ *   messagesToLose={5}
+ *   isOpen={showDialog}
+ *   onConfirm={() => {
+ *     handleRollback();
+ *     setShowDialog(false);
+ *   }}
+ *   onCancel={() => setShowDialog(false)}
+ * />
+ * ```
+ */
+export function RollbackDialog({
+  checkpoint,
+  messagesToLose,
+  isOpen,
+  onConfirm,
+  onCancel,
+}: RollbackDialogProps): React.JSX.Element | null {
+  const { theme } = useTheme();
+  const { t } = useTUITranslation();
+
+  // Get colors from theme
+  const errorColor = theme.colors.error;
+  const warningColor = theme.colors.warning;
+  const successColor = theme.colors.success;
+  const textColor = theme.semantic.text.primary;
+  const mutedColor = theme.semantic.text.muted;
+  const borderColor = errorColor; // Use error color for border to emphasize danger
+
+  /**
+   * Handle keyboard input
+   */
+  useInput(
+    (input, key) => {
+      // Confirm: y, Y, or Enter
+      if (input === "y" || input === "Y" || key.return) {
+        onConfirm();
+        return;
+      }
+
+      // Cancel: n, N, or Escape
+      if (input === "n" || input === "N" || key.escape) {
+        onCancel();
+        return;
+      }
+    },
+    { isActive: isOpen }
+  );
+
+  if (!isOpen || !checkpoint) {
+    return null;
+  }
+
+  const checkpointDescription = checkpoint.description ?? "(no description)";
+  const checkpointIdShort = checkpoint.id.slice(0, 8);
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="double"
+      borderColor={borderColor}
+      paddingX={2}
+      paddingY={1}
+    >
+      {/* Title */}
+      <Box marginBottom={1}>
+        <Text bold color={errorColor}>
+          ⚠️ {t("persistence.rollback.confirm")}
+        </Text>
+      </Box>
+
+      {/* Checkpoint Info */}
+      <Box flexDirection="column" marginBottom={1}>
+        <Text color={textColor}>
+          Checkpoint: <Text color={mutedColor}>[{checkpointIdShort}]</Text>{" "}
+          <Text bold>{checkpointDescription}</Text>
+        </Text>
+        <Text color={mutedColor}>Message index: {checkpoint.messageIndex}</Text>
+      </Box>
+
+      {/* Warning Message */}
+      <Box marginBottom={1} paddingX={1}>
+        <Text color={warningColor} bold>
+          {t("persistence.rollback.warning", { count: messagesToLose })}
+        </Text>
+      </Box>
+
+      {/* Emphasis on irreversibility */}
+      <Box marginBottom={1}>
+        <Text color={errorColor} dimColor>
+          This action cannot be undone.
+        </Text>
+      </Box>
+
+      {/* Action Buttons */}
+      <Box flexDirection="row" gap={2}>
+        <Box>
+          <Text color={successColor}>[y]</Text>
+          <Text color={textColor}> Confirm</Text>
+        </Box>
+        <Box>
+          <Text color={errorColor}>[n]</Text>
+          <Text color={textColor}> Cancel</Text>
+        </Box>
+      </Box>
+    </Box>
+  );
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export default RollbackDialog;

package/src/tui/components/session/SessionItem.tsx

@@ -0,0 +1,136 @@
+/**
+ * SessionItem Component (T056)
+ *
+ * Displays a single session in the session list with title,
+ * last message preview, and timestamp.
+ *
+ * @module tui/components/session/SessionItem
+ */
+
+import { Box, Text } from "ink";
+import type React from "react";
+import { useTheme } from "../../theme/index.js";
+import { truncateToDisplayWidth } from "../../utils/index.js";
+import type { SessionItemProps } from "./types.js";
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Format a timestamp for display.
+ * Shows time if today, otherwise shows date.
+ */
+function formatTimestamp(date: Date): string {
+  const now = new Date();
+  const isToday =
+    date.getDate() === now.getDate() &&
+    date.getMonth() === now.getMonth() &&
+    date.getFullYear() === now.getFullYear();
+
+  if (isToday) {
+    return date.toLocaleTimeString(undefined, {
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  }
+
+  return date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+  });
+}
+
+/**
+ * Truncate text to a maximum display width with ellipsis.
+ * Uses string-width for accurate CJK/Emoji handling.
+ */
+function truncateText(text: string, maxLength: number): string {
+  return truncateToDisplayWidth(text, maxLength);
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * SessionItem displays a single session entry.
+ *
+ * Features:
+ * - Shows session title with truncation
+ * - Displays last message preview (muted)
+ * - Shows relative timestamp
+ * - Visual indicators for selected/active states
+ * - Message count badge
+ *
+ * @example
+ * ```tsx
+ * <SessionItem
+ *   session={{
+ *     id: "sess-1",
+ *     title: "Debug React app",
+ *     lastMessage: "I'll help you fix that...",
+ *     timestamp: new Date(),
+ *     messageCount: 12
+ *   }}
+ *   isSelected={true}
+ *   isActive={false}
+ *   onSelect={(id) => handleSelect(id)}
+ * />
+ * ```
+ */
+export function SessionItem({
+  session,
+  isSelected = false,
+  isActive = false,
+}: SessionItemProps): React.JSX.Element {
+  const { theme } = useTheme();
+
+  const textColor = theme.semantic.text.primary;
+  const mutedColor = theme.semantic.text.muted;
+  const primaryColor = theme.colors.primary;
+  const successColor = theme.colors.success;
+
+  // Determine background indicator
+  const indicator = isSelected ? "▶" : isActive ? "●" : " ";
+  const indicatorColor = isSelected ? primaryColor : isActive ? successColor : mutedColor;
+
+  // Truncate title and last message for display
+  const displayTitle = truncateText(session.title, 40);
+  const displayMessage = session.lastMessage ? truncateText(session.lastMessage, 50) : "";
+
+  return (
+    <Box
+      flexDirection="column"
+      paddingX={1}
+      paddingY={0}
+      borderStyle={isSelected ? "single" : undefined}
+      borderColor={isSelected ? primaryColor : undefined}
+    >
+      {/* Title row with indicator and timestamp */}
+      <Box flexDirection="row" justifyContent="space-between">
+        <Box flexDirection="row" gap={1}>
+          <Text color={indicatorColor}>{indicator}</Text>
+          <Text color={isSelected ? primaryColor : textColor} bold={isSelected || isActive}>
+            {displayTitle}
+          </Text>
+        </Box>
+        <Box flexDirection="row" gap={1}>
+          <Text dimColor>({session.messageCount})</Text>
+          <Text color={mutedColor}>{formatTimestamp(session.timestamp)}</Text>
+        </Box>
+      </Box>
+
+      {/* Last message preview */}
+      {displayMessage && (
+        <Box marginLeft={2}>
+          <Text color={mutedColor} wrap="truncate">
+            {displayMessage}
+          </Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+export default SessionItem;