@butlerw/vellum 0.1.0

package/src/tui/components/StatusBar/AgentModeIndicator.tsx

@@ -0,0 +1,257 @@
+/**
+ * AgentModeIndicator Component (T057)
+ *
+ * Displays the current agent mode for multi-agent orchestration.
+ * Shows agent name, level depth, and agent-specific icons.
+ *
+ * @module tui/components/StatusBar/AgentModeIndicator
+ */
+
+import { getIcons } from "@vellum/shared";
+import { Box, Text } from "ink";
+import { useMemo } from "react";
+import { useTheme } from "../../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Agent level depth in the orchestration hierarchy.
+ * - 0: Master orchestrator (ouroboros)
+ * - 1: Sub-orchestrators (init, spec, implement, archive)
+ * - 2: Workers (coder, qa, writer, analyst, etc.)
+ */
+export type AgentLevel = 0 | 1 | 2;
+
+/**
+ * Known agent types in the multi-agent system.
+ */
+export type AgentType =
+  | "orchestrator"
+  | "coder"
+  | "qa"
+  | "writer"
+  | "analyst"
+  | "devops"
+  | "security"
+  | "architect"
+  | "researcher"
+  | "requirements"
+  | "tasks"
+  | "validator"
+  | "init"
+  | "spec"
+  | "implement"
+  | "archive";
+
+/**
+ * Props for the AgentModeIndicator component.
+ */
+export interface AgentModeIndicatorProps {
+  /** Current agent name (e.g., 'orchestrator', 'coder', 'qa') */
+  readonly agentName: string;
+  /** Agent level depth (0=orchestrator, 1=sub-orchestrator, 2=worker) */
+  readonly level?: AgentLevel;
+  /** Compact display mode (icon only) */
+  readonly compact?: boolean;
+  /** Whether delegation is currently active (T059) */
+  readonly isDelegating?: boolean;
+  /** Agent being delegated to (T059) */
+  readonly delegatingTo?: string;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Get agent icons mapping.
+ * Uses centralized icon system for consistent terminal display.
+ */
+function getAgentIcons(): Record<string, string> {
+  const icons = getIcons();
+  return {
+    orchestrator: icons.assistant, // Robot/AI icon
+    coder: "⌨", // Keyboard (Unicode)
+    qa: "⚗", // Test tube (Unicode)
+    writer: "✎", // Pencil (Unicode)
+    analyst: "⊙", // Search/target (Unicode)
+    devops: icons.tool, // Tool icon
+    security: "⊗", // Lock-like (Unicode)
+    architect: "⦿", // Diagram-like (Unicode)
+    researcher: "⊞", // Book-like (Unicode)
+    requirements: icons.plan, // Plan icon
+    tasks: icons.note, // Note icon
+    validator: icons.check, // Check icon
+    init: "▶", // Play (Unicode)
+    spec: icons.spec, // Spec icon
+    implement: icons.gear, // Gear icon
+    archive: "⊟", // Box-like (Unicode)
+    default: icons.assistant, // Default robot
+  };
+}
+
+/**
+ * Agent display names mapping.
+ */
+const AGENT_NAMES: Record<string, string> = {
+  orchestrator: "Orchestrator",
+  coder: "Coder",
+  qa: "QA",
+  writer: "Writer",
+  analyst: "Analyst",
+  devops: "DevOps",
+  security: "Security",
+  architect: "Architect",
+  researcher: "Researcher",
+  requirements: "Requirements",
+  tasks: "Tasks",
+  validator: "Validator",
+  init: "Init",
+  spec: "Spec",
+  implement: "Implement",
+  archive: "Archive",
+};
+
+/**
+ * Level indicator labels.
+ */
+const LEVEL_LABELS: Record<AgentLevel, string> = {
+  0: "L0",
+  1: "L1",
+  2: "L2",
+};
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Gets the icon for an agent type.
+ * Falls back to default robot icon for unknown agents.
+ */
+function getAgentIcon(agentName: string): string {
+  const agentIcons = getAgentIcons();
+  const normalizedName = agentName.toLowerCase();
+  return agentIcons[normalizedName] ?? agentIcons.default ?? getIcons().assistant;
+}
+
+/**
+ * Gets the display name for an agent.
+ * Falls back to capitalized agent name for unknown agents.
+ */
+function getAgentDisplayName(agentName: string): string {
+  const normalizedName = agentName.toLowerCase();
+  return AGENT_NAMES[normalizedName] ?? agentName.charAt(0).toUpperCase() + agentName.slice(1);
+}
+
+/**
+ * Gets the color for an agent level.
+ * - L0: Primary (orchestrator level)
+ * - L1: Info (sub-orchestrator level)
+ * - L2: Secondary (worker level)
+ */
+function getLevelColor(level: AgentLevel, theme: ReturnType<typeof useTheme>["theme"]): string {
+  switch (level) {
+    case 0:
+      return theme.colors.primary;
+    case 1:
+      return theme.colors.info;
+    case 2:
+      return theme.semantic.text.secondary;
+    default:
+      return theme.semantic.text.muted;
+  }
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * AgentModeIndicator displays the current agent in the multi-agent system.
+ *
+ * Features:
+ * - Agent-specific icon (emoji)
+ * - Agent name display
+ * - Level indicator (L0/L1/L2)
+ * - Compact mode for space-constrained layouts
+ * - Themed styling based on agent level
+ *
+ * Agent Levels:
+ * - L0: Master orchestrator (ouroboros)
+ * - L1: Sub-orchestrators (init, spec, implement, archive)
+ * - L2: Workers (coder, qa, writer, analyst, devops, security, etc.)
+ *
+ * @example
+ * ```tsx
+ * // Master orchestrator
+ * <AgentModeIndicator agentName="orchestrator" level={0} />
+ *
+ * // Coder worker
+ * <AgentModeIndicator agentName="coder" level={2} />
+ *
+ * // Compact mode (icon only)
+ * <AgentModeIndicator agentName="qa" level={2} compact />
+ * ```
+ */
+export function AgentModeIndicator({
+  agentName,
+  level = 2,
+  compact = false,
+  isDelegating = false,
+  delegatingTo,
+}: AgentModeIndicatorProps): React.JSX.Element {
+  const { theme } = useTheme();
+
+  const icon = useMemo(() => getAgentIcon(agentName), [agentName]);
+  const displayName = useMemo(() => getAgentDisplayName(agentName), [agentName]);
+  const levelColor = useMemo(() => getLevelColor(level, theme), [level, theme]);
+  const levelLabel = LEVEL_LABELS[level];
+
+  // Show delegation indicator when active (GAP 3 fix - T059)
+  if (isDelegating && delegatingTo) {
+    const delegateIcon = getAgentIcon(delegatingTo);
+    const delegateName = getAgentDisplayName(delegatingTo);
+
+    if (compact) {
+      return (
+        <Box>
+          <Text color={theme.colors.warning}>⋯</Text>
+          <Text color={theme.semantic.text.muted}> </Text>
+          <Text>{delegateIcon}</Text>
+        </Box>
+      );
+    }
+
+    return (
+      <Box>
+        <Text color={theme.colors.warning}>⋯ Delegating to </Text>
+        <Text>{delegateIcon}</Text>
+        <Text color={theme.semantic.text.muted}> </Text>
+        <Text color={theme.colors.info}>{delegateName}</Text>
+      </Box>
+    );
+  }
+
+  if (compact) {
+    return (
+      <Box>
+        <Text>{icon}</Text>
+        <Text color={theme.semantic.text.muted}> </Text>
+        <Text color={levelColor}>{levelLabel}</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box>
+      <Text>{icon}</Text>
+      <Text color={theme.semantic.text.muted}> </Text>
+      <Text color={theme.semantic.text.primary}>{displayName}</Text>
+      <Text color={theme.semantic.text.muted}> </Text>
+      <Text color={levelColor}>[{levelLabel}]</Text>
+    </Box>
+  );
+}

package/src/tui/components/StatusBar/ContextProgress.tsx

@@ -0,0 +1,167 @@
+/**
+ * ContextProgress Component
+ *
+ * Visual context window usage indicator with progress bar.
+ * Shows token usage with color-coded thresholds:
+ * - Green (0-50%): Plenty of context
+ * - Yellow (50-80%): Moderate usage
+ * - Red (80%+): Critical usage
+ *
+ * @module tui/components/StatusBar/ContextProgress
+ */
+
+import { Box, Text } from "ink";
+import { useMemo } from "react";
+import { useTheme } from "../../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the ContextProgress component.
+ */
+export interface ContextProgressProps {
+  /** Current token count */
+  readonly current: number;
+  /** Maximum token limit */
+  readonly max: number;
+  /** Whether to show the label "Context:" (default: true) */
+  readonly showLabel?: boolean;
+  /** Width of progress bar in characters (default: 10) */
+  readonly barWidth?: number;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Progress bar characters - using half-filled block for visual progress */
+const BAR_FILLED = "▓";
+const BAR_EMPTY = "░";
+
+/** Color thresholds for context usage warning */
+const THRESHOLDS = {
+  LOW: 50, // 0-50%: green (plenty of context)
+  MEDIUM: 80, // 50-80%: yellow (moderate usage)
+  // 80%+: red (critical usage)
+} as const;
+
+/** Default bar width - compact for status bar usage */
+const DEFAULT_BAR_WIDTH = 10;
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Formats a number with K/M suffix for compact display.
+ */
+function formatTokenCount(count: number): string {
+  if (count < 1000) {
+    return count.toString();
+  }
+  if (count < 1000000) {
+    const k = count / 1000;
+    return k >= 10 ? `${Math.round(k)}K` : `${k.toFixed(1)}K`;
+  }
+  const m = count / 1000000;
+  return m >= 10 ? `${Math.round(m)}M` : `${m.toFixed(1)}M`;
+}
+
+/**
+ * Calculates the percentage of tokens used.
+ */
+function calculatePercentage(current: number, max: number): number {
+  if (max <= 0) return 0;
+  return Math.min(Math.round((current / max) * 100), 100);
+}
+
+/**
+ * Get the color based on usage percentage.
+ * Uses semantic status colors:
+ * - 0-50%: success (green) - plenty of context
+ * - 50-80%: warning (yellow) - moderate usage
+ * - 80-100%: error (red) - critical usage
+ */
+function getProgressColor(percentage: number, theme: ReturnType<typeof useTheme>["theme"]): string {
+  if (percentage >= THRESHOLDS.MEDIUM) {
+    return theme.colors.error; // Red for 80%+
+  }
+  if (percentage >= THRESHOLDS.LOW) {
+    return theme.colors.warning; // Yellow for 50-80%
+  }
+  return theme.colors.success; // Green for 0-50%
+}
+
+/**
+ * Generates the progress bar string.
+ */
+function generateProgressBar(percentage: number, width: number): { filled: string; empty: string } {
+  const filledCount = Math.round((percentage / 100) * width);
+  const emptyCount = width - filledCount;
+  return {
+    filled: BAR_FILLED.repeat(filledCount),
+    empty: BAR_EMPTY.repeat(emptyCount),
+  };
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * ContextProgress displays context window usage with a visual progress bar.
+ *
+ * Features:
+ * - Visual progress bar using Unicode block characters
+ * - Color-coded based on usage thresholds
+ * - Compact token count display (K/M suffixes)
+ * - Optional label display
+ *
+ * @example
+ * ```tsx
+ * // Full display with label
+ * <ContextProgress current={32000} max={40000} />
+ * // Output: Context: ████████░░ 80% (32K/40K)
+ *
+ * // Compact without label
+ * <ContextProgress current={5000} max={100000} showLabel={false} />
+ * // Output: █░░░░░░░░░ 5% (5K/100K)
+ * ```
+ */
+export function ContextProgress({
+  current,
+  max,
+  showLabel = true,
+  barWidth = DEFAULT_BAR_WIDTH,
+}: ContextProgressProps): React.JSX.Element {
+  const { theme } = useTheme();
+
+  const percentage = useMemo(() => calculatePercentage(current, max), [current, max]);
+
+  const progressBar = useMemo(
+    () => generateProgressBar(percentage, barWidth),
+    [percentage, barWidth]
+  );
+
+  const progressColor = useMemo(() => getProgressColor(percentage, theme), [percentage, theme]);
+
+  const formattedCurrent = useMemo(() => formatTokenCount(current), [current]);
+  const formattedMax = useMemo(() => formatTokenCount(max), [max]);
+
+  return (
+    <Box>
+      {showLabel && <Text color={theme.semantic.text.muted}>Context: </Text>}
+      <Text color={progressColor}>{progressBar.filled}</Text>
+      <Text color={theme.semantic.text.muted}>{progressBar.empty}</Text>
+      <Text color={theme.semantic.text.muted}> </Text>
+      <Text color={progressColor}>{percentage}%</Text>
+      <Text color={theme.semantic.text.muted}> (</Text>
+      <Text color={theme.semantic.text.secondary}>{formattedCurrent}</Text>
+      <Text color={theme.semantic.text.muted}>/</Text>
+      <Text color={theme.semantic.text.secondary}>{formattedMax}</Text>
+      <Text color={theme.semantic.text.muted}>)</Text>
+    </Box>
+  );
+}

package/src/tui/components/StatusBar/FileChangesIndicator.tsx

@@ -0,0 +1,62 @@
+/**
+ * FileChangesIndicator Component
+ *
+ * Displays file change statistics (+additions -deletions) in the header bar.
+ * Uses success color for additions and error color for deletions.
+ *
+ * @module tui/components/StatusBar/FileChangesIndicator
+ */
+
+import { Box, Text } from "ink";
+import type React from "react";
+import { useTheme } from "../../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the FileChangesIndicator component.
+ */
+export interface FileChangesIndicatorProps {
+  /** Number of lines added */
+  readonly additions: number;
+  /** Number of lines deleted */
+  readonly deletions: number;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * FileChangesIndicator displays cumulative file change statistics.
+ *
+ * Format: +{additions} -{deletions}
+ * Returns null if no changes (additions and deletions both 0).
+ *
+ * @example
+ * ```tsx
+ * <FileChangesIndicator additions={42} deletions={15} />
+ * // Output: +42 -15
+ * ```
+ */
+export function FileChangesIndicator({
+  additions,
+  deletions,
+}: FileChangesIndicatorProps): React.JSX.Element | null {
+  const { theme } = useTheme();
+
+  // Don't show if no changes
+  if (additions === 0 && deletions === 0) {
+    return null;
+  }
+
+  return (
+    <Box>
+      <Text color={theme.colors.success}>+{additions}</Text>
+      <Text> </Text>
+      <Text color={theme.colors.error}>-{deletions}</Text>
+    </Box>
+  );
+}

package/src/tui/components/StatusBar/GitIndicator.tsx

@@ -0,0 +1,89 @@
+/**
+ * GitIndicator Component
+ *
+ * Displays the current git branch and dirty status.
+ * Uses dim styling to avoid competing with main content.
+ *
+ * @module tui/components/StatusBar/GitIndicator
+ */
+
+import { getIcons } from "@vellum/shared";
+import { Text } from "ink";
+import type React from "react";
+import { useMemo } from "react";
+import { useGitStatus } from "../../hooks/useGitStatus.js";
+import { useTheme } from "../../theme/index.js";
+import { truncateToDisplayWidth } from "../../utils/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the GitIndicator component.
+ */
+export interface GitIndicatorProps {
+  /** Maximum width for the branch name (truncates if exceeded) */
+  readonly maxWidth?: number;
+  /** Whether to show the dirty indicator (default: true) */
+  readonly showDirty?: boolean;
+  /** Whether to show the changed files count (default: false) */
+  readonly showChangedCount?: boolean;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * GitIndicator displays the current git branch and status.
+ *
+ * Uses Nerd Font  icon or Unicode/ASCII fallback.
+ * Shows dirty indicator when there are uncommitted changes.
+ *
+ * Returns null if not in a git repository.
+ *
+ * @example
+ * ```tsx
+ * <GitIndicator maxWidth={15} />
+ * // Output:  main (clean)
+ * // Output:  main * (dirty)
+ * // Output:  feature/long… * (truncated + dirty)
+ * ```
+ */
+export function GitIndicator({
+  maxWidth = 15,
+  showDirty = true,
+  showChangedCount = false,
+}: GitIndicatorProps): React.JSX.Element | null {
+  const { theme } = useTheme();
+  const { branch, isDirty, changedFiles, isLoading, isGitRepo } = useGitStatus();
+  const icons = getIcons();
+
+  const displayBranch = useMemo(() => {
+    if (!branch) return null;
+    // Truncate with ellipsis using string-width for CJK/Emoji handling
+    return truncateToDisplayWidth(branch, maxWidth);
+  }, [branch, maxWidth]);
+
+  // Don't render if not in a git repo or still loading
+  if (!isGitRepo || isLoading || !displayBranch) {
+    return null;
+  }
+
+  // Build the dirty suffix
+  const dirtySuffix = showDirty && isDirty ? ` ${icons.dirty}` : "";
+  const countSuffix = showChangedCount && changedFiles > 0 ? ` (${changedFiles})` : "";
+
+  return (
+    <Text color={theme.semantic.text.muted}>
+      {icons.branch} {displayBranch}
+      {isDirty && (
+        <Text color={theme.colors.warning}>
+          {dirtySuffix}
+          {countSuffix}
+        </Text>
+      )}
+    </Text>
+  );
+}

package/src/tui/components/StatusBar/HeaderBar.tsx

@@ -0,0 +1,126 @@
+/**
+ * HeaderBar Component
+ *
+ * Embedded header bar showing workspace and git status indicators.
+ * Designed to be placed at the top of the AppHeader without adding extra lines.
+ *
+ * Features:
+ * - Workspace directory name with folder icon
+ * - Git branch with dirty indicator
+ * - Responsive: adapts to terminal width
+ * - Dim styling to not compete with main content
+ *
+ * @module tui/components/StatusBar/HeaderBar
+ */
+
+import { Box, Text } from "ink";
+import type React from "react";
+import { useFileChangeStats } from "../../hooks/useFileChangeStats.js";
+import { useTerminalDimensions } from "../../hooks/useTerminalSize.js";
+import { useTheme } from "../../theme/index.js";
+import { FileChangesIndicator } from "./FileChangesIndicator.js";
+import { GitIndicator } from "./GitIndicator.js";
+import { WorkspaceIndicator } from "./WorkspaceIndicator.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Separator between header bar items */
+const SEPARATOR = " │ ";
+
+/** Minimum terminal width to show git indicator */
+const MIN_WIDTH_FOR_GIT = 60;
+
+/** Minimum terminal width to show both indicators with full width */
+const COMPACT_THRESHOLD = 80;
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the HeaderBar component.
+ */
+export interface HeaderBarProps {
+  /** Optional session snapshot count to display */
+  readonly snapshotCount?: number;
+  /** Whether sandbox boundaries are active */
+  readonly sandboxActive?: boolean;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * HeaderBar displays workspace and git status in a compact horizontal bar.
+ *
+ * Layout:
+ * - Wide (≥80 cols):  vellum │  main *
+ * - Medium (60-79):   vellum │  main
+ * - Narrow (<60):     vellum (no git)
+ *
+ * Uses dim colors to stay unobtrusive while providing useful context.
+ *
+ * @example
+ * ```tsx
+ * <HeaderBar />
+ * // Output:  vellum │  main *
+ * ```
+ */
+export function HeaderBar({ snapshotCount, sandboxActive }: HeaderBarProps): React.JSX.Element {
+  const { theme } = useTheme();
+  const { width: columns } = useTerminalDimensions();
+  const fileStats = useFileChangeStats();
+
+  // Responsive width calculations
+  const isCompact = columns < COMPACT_THRESHOLD;
+  const showGit = columns >= MIN_WIDTH_FOR_GIT;
+
+  // Calculate max widths based on available space
+  const workspaceMaxWidth = isCompact ? 15 : 20;
+  const gitMaxWidth = isCompact ? 10 : 15;
+
+  // Show file changes if there are any
+  const hasFileChanges = fileStats.additions > 0 || fileStats.deletions > 0;
+
+  return (
+    <Box flexDirection="row" justifyContent="flex-start">
+      {/* Workspace indicator */}
+      <WorkspaceIndicator maxWidth={workspaceMaxWidth} />
+
+      {/* Git indicator (if visible and space allows) */}
+      {showGit && (
+        <>
+          <Text color={theme.semantic.text.muted}>{SEPARATOR}</Text>
+          <GitIndicator maxWidth={gitMaxWidth} showDirty showChangedCount={!isCompact} />
+        </>
+      )}
+
+      {/* File changes indicator */}
+      {hasFileChanges && (
+        <>
+          <Text color={theme.semantic.text.muted}>{SEPARATOR}</Text>
+          <FileChangesIndicator additions={fileStats.additions} deletions={fileStats.deletions} />
+        </>
+      )}
+
+      {/* Optional snapshot count */}
+      {snapshotCount !== undefined && snapshotCount > 0 && (
+        <>
+          <Text color={theme.semantic.text.muted}>{SEPARATOR}</Text>
+          <Text color={theme.semantic.text.muted}>◉ {snapshotCount}</Text>
+        </>
+      )}
+
+      {/* Optional sandbox indicator */}
+      {sandboxActive && (
+        <>
+          <Text color={theme.semantic.text.muted}>{SEPARATOR}</Text>
+          <Text color={theme.colors.warning}>⊘ sandbox</Text>
+        </>
+      )}
+    </Box>
+  );
+}