@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/watch.ts

@@ -0,0 +1,895 @@
+/**
+ * Bootspring Watch Command
+ * Real-time file watching and sync for todos, tasks, and workflows
+ *
+ * @package bootspring
+ * @command watch
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { EventEmitter } from 'events';
+
+// Interfaces
+interface ConfigModule {
+  load: () => { _projectRoot: string };
+}
+
+interface UtilsModule {
+  parseArgs: (args: string[]) => ParsedArgs;
+}
+
+interface TelemetryModule {
+  emitEvent: (event: string, payload: Record<string, unknown>) => void;
+}
+
+interface CheckpointEngineModule {
+  getCheckpointStatus: (projectRoot: string) => CheckpointStatus;
+  syncCheckpoints: (projectRoot: string) => { success: boolean };
+}
+
+interface CheckpointUtilsModule {
+  pushCheckpointsToServer: (projectRoot: string, options: PushOptions) => Promise<{ success: boolean }>;
+}
+
+interface ParsedArgs {
+  _: string[];
+  help?: boolean;
+  h?: boolean;
+  todos?: boolean;
+  workflows?: boolean;
+  prd?: boolean;
+  checkpoints?: boolean;
+  verbose?: boolean;
+  debounce?: string;
+  [key: string]: string | boolean | string[] | undefined;
+}
+
+interface Todo {
+  id: string;
+  line: number;
+  completed: boolean;
+  text: string;
+}
+
+interface TodoChange {
+  type: 'completed' | 'added' | 'removed' | 'reopened';
+  todo: Todo;
+}
+
+interface TodoStats {
+  pending: number;
+  completed: number;
+  total: number;
+  progress: number;
+}
+
+interface WatcherOptions {
+  debounceMs?: number | undefined;
+  watchTodos?: boolean | undefined;
+  watchWorkflows?: boolean | undefined;
+  watchPRD?: boolean | undefined;
+  watchCheckpoints?: boolean | undefined;
+}
+
+interface WatcherState {
+  todos: Todo[];
+  workflows: Record<string, WorkflowState>;
+  prd: PRD | null;
+  checkpoints: CheckpointStatus | null;
+}
+
+interface WorkflowState {
+  status?: string | undefined;
+  phases?: Record<string, { status: string }> | undefined;
+}
+
+interface PRD {
+  name?: string | undefined;
+  stories?: Story[] | undefined;
+}
+
+interface Story {
+  id?: string | undefined;
+  title: string;
+  status: string;
+}
+
+interface CheckpointStatus {
+  exists: boolean;
+  percentage?: number | undefined;
+  completed?: number | undefined;
+  total?: number | undefined;
+  checkpoints?: Checkpoint[] | undefined;
+}
+
+interface Checkpoint {
+  id: string;
+  label: string;
+  completed: boolean;
+}
+
+interface PushOptions {
+  quiet?: boolean | undefined;
+  autoSync?: boolean | undefined;
+  skipMetrics?: boolean | undefined;
+}
+
+interface RunWatchOptions {
+  watchTodos?: boolean | undefined;
+  watchWorkflows?: boolean | undefined;
+  watchPRD?: boolean | undefined;
+  watchCheckpoints?: boolean | undefined;
+  verbose?: boolean | undefined;
+  debounceMs?: number | undefined;
+}
+
+// Lazy load modules
+const config = require('../core/config') as ConfigModule;
+const utils = require('../core/utils') as UtilsModule;
+const telemetry = require('../core/telemetry') as TelemetryModule;
+const checkpointEngine = require('../core/checkpoint-engine') as CheckpointEngineModule;
+
+// Colors
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m'
+};
+
+/**
+ * Parse todo.md content
+ */
+function parseTodoFile(content: string): Todo[] {
+  const todos: Todo[] = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const match = line.match(/^- \[([ xX])\] (.+)$/);
+    if (match) {
+      todos.push({
+        id: `todo-${i}`,
+        line: i + 1,
+        completed: match[1]?.toLowerCase() === 'x',
+        text: match[2]?.trim() || ''
+      });
+    }
+  }
+
+  return todos;
+}
+
+/**
+ * Compare todo states and find changes
+ */
+function diffTodos(oldTodos: Todo[], newTodos: Todo[]): TodoChange[] {
+  const changes: TodoChange[] = [];
+
+  // Map old todos by text for comparison
+  const oldMap = new Map(oldTodos.map(t => [t.text, t]));
+  const newMap = new Map(newTodos.map(t => [t.text, t]));
+
+  // Find completed todos
+  for (const newTodo of newTodos) {
+    const oldTodo = oldMap.get(newTodo.text);
+    if (oldTodo && !oldTodo.completed && newTodo.completed) {
+      changes.push({ type: 'completed', todo: newTodo });
+    }
+    if (oldTodo && oldTodo.completed && !newTodo.completed) {
+      changes.push({ type: 'reopened', todo: newTodo });
+    }
+  }
+
+  // Find added todos
+  for (const newTodo of newTodos) {
+    if (!oldMap.has(newTodo.text)) {
+      changes.push({ type: 'added', todo: newTodo });
+    }
+  }
+
+  // Find removed todos
+  for (const oldTodo of oldTodos) {
+    if (!newMap.has(oldTodo.text)) {
+      changes.push({ type: 'removed', todo: oldTodo });
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Get todo statistics
+ */
+function getTodoStats(todos: Todo[]): TodoStats {
+  const pending = todos.filter(t => !t.completed).length;
+  const completed = todos.filter(t => t.completed).length;
+  return {
+    pending,
+    completed,
+    total: todos.length,
+    progress: todos.length > 0 ? Math.round((completed / todos.length) * 100) : 0
+  };
+}
+
+/**
+ * File watcher class
+ */
+class FileWatcher extends EventEmitter {
+  private projectRoot: string;
+  private options: Required<WatcherOptions>;
+  private watchers: fs.FSWatcher[];
+  private state: WatcherState;
+  private debounceTimers: Map<string, NodeJS.Timeout>;
+
+  constructor(projectRoot: string, options: WatcherOptions = {}) {
+    super();
+    this.projectRoot = projectRoot;
+    this.options = {
+      debounceMs: options.debounceMs || 300,
+      watchTodos: options.watchTodos !== false,
+      watchWorkflows: options.watchWorkflows !== false,
+      watchPRD: options.watchPRD !== false,
+      watchCheckpoints: options.watchCheckpoints !== false
+    };
+
+    this.watchers = [];
+    this.state = {
+      todos: [],
+      workflows: {},
+      prd: null,
+      checkpoints: null
+    };
+    this.debounceTimers = new Map();
+  }
+
+  /**
+   * Start watching files
+   */
+  start(): void {
+    const todoPath = path.join(this.projectRoot, 'todo.md');
+    const bootspringDir = path.join(this.projectRoot, '.bootspring');
+    const prdPath = path.join(this.projectRoot, 'tasks', 'prd.json');
+
+    // Watch todo.md
+    if (this.options.watchTodos && fs.existsSync(todoPath)) {
+      this.watchFile(todoPath, 'todo');
+      this.loadTodoState(todoPath);
+    }
+
+    // Watch .bootspring directory for workflow changes
+    if (this.options.watchWorkflows && fs.existsSync(bootspringDir)) {
+      this.watchDirectory(bootspringDir, 'workflow');
+      this.loadWorkflowStates();
+    }
+
+    // Watch PRD
+    if (this.options.watchPRD && fs.existsSync(prdPath)) {
+      this.watchFile(prdPath, 'prd');
+      this.loadPRDState(prdPath);
+    }
+
+    // Watch planning directory for checkpoint-related files
+    const planningDir = path.join(this.projectRoot, 'planning');
+    if (this.options.watchCheckpoints && fs.existsSync(planningDir)) {
+      this.watchDirectory(planningDir, 'checkpoint');
+      this.loadCheckpointState();
+    }
+
+    this.emit('started');
+  }
+
+  /**
+   * Watch a single file
+   */
+  private watchFile(filePath: string, type: string): void {
+    try {
+      const watcher = fs.watch(filePath, (eventType) => {
+        if (eventType === 'change') {
+          this.debouncedHandle(filePath, type);
+        }
+      });
+
+      this.watchers.push(watcher);
+    } catch (err) {
+      this.emit('error', { type, error: err });
+    }
+  }
+
+  /**
+   * Watch a directory
+   */
+  private watchDirectory(dirPath: string, type: string): void {
+    try {
+      const watcher = fs.watch(dirPath, { recursive: true }, (eventType, filename) => {
+        if (!filename) return;
+
+        // For checkpoints, watch .md files; for workflows, watch .json files
+        const isRelevant = type === 'checkpoint'
+          ? filename.endsWith('.md') || filename.endsWith('.json')
+          : filename.endsWith('.json');
+
+        if (isRelevant) {
+          const fullPath = path.join(dirPath, filename);
+          this.debouncedHandle(fullPath, type);
+        }
+      });
+
+      this.watchers.push(watcher);
+    } catch (err) {
+      this.emit('error', { type, error: err });
+    }
+  }
+
+  /**
+   * Debounced change handler
+   */
+  private debouncedHandle(filePath: string, type: string): void {
+    const key = `${type}:${filePath}`;
+
+    const existingTimer = this.debounceTimers.get(key);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+
+    this.debounceTimers.set(key, setTimeout(() => {
+      this.handleChange(filePath, type);
+      this.debounceTimers.delete(key);
+    }, this.options.debounceMs));
+  }
+
+  /**
+   * Handle file change
+   */
+  private handleChange(filePath: string, type: string): void {
+    try {
+      switch (type) {
+        case 'todo':
+          this.handleTodoChange(filePath);
+          break;
+        case 'workflow':
+          this.handleWorkflowChange(filePath);
+          break;
+        case 'prd':
+          this.handlePRDChange(filePath);
+          break;
+        case 'checkpoint':
+          this.handleCheckpointChange(filePath);
+          break;
+      }
+    } catch (err) {
+      this.emit('error', { type, filePath, error: err });
+    }
+  }
+
+  /**
+   * Load initial todo state
+   */
+  private loadTodoState(filePath: string): void {
+    try {
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        this.state.todos = parseTodoFile(content);
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  /**
+   * Handle todo file changes
+   */
+  private handleTodoChange(filePath: string): void {
+    if (!fs.existsSync(filePath)) {
+      this.emit('todo:deleted');
+      this.state.todos = [];
+      return;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const newTodos = parseTodoFile(content);
+    const changes = diffTodos(this.state.todos, newTodos);
+    const stats = getTodoStats(newTodos);
+
+    this.state.todos = newTodos;
+
+    if (changes.length > 0) {
+      this.emit('todo:changed', { changes, stats, todos: newTodos });
+
+      // Emit specific events
+      for (const change of changes) {
+        this.emit(`todo:${change.type}`, change.todo);
+      }
+
+      // Track in telemetry
+      telemetry.emitEvent('watch:todo:change', {
+        changes: changes.map(c => ({ type: c.type, text: c.todo.text.slice(0, 50) })),
+        stats
+      });
+    }
+  }
+
+  /**
+   * Load initial workflow states
+   */
+  private loadWorkflowStates(): void {
+    const workflowNames = ['onboard', 'analyze', 'audit', 'preseed', 'seed', 'deploy', 'loop'];
+
+    for (const name of workflowNames) {
+      const stateFile = path.join(this.projectRoot, '.bootspring', name, 'workflow-state.json');
+      if (fs.existsSync(stateFile)) {
+        try {
+          this.state.workflows[name] = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+        } catch {
+          // Ignore errors
+        }
+      }
+    }
+  }
+
+  /**
+   * Handle workflow state changes
+   */
+  private handleWorkflowChange(filePath: string): void {
+    // Extract workflow name from path
+    const relativePath = path.relative(path.join(this.projectRoot, '.bootspring'), filePath);
+    const workflowName = relativePath.split(path.sep)[0];
+
+    if (!workflowName) return;
+
+    if (!fs.existsSync(filePath)) {
+      this.emit('workflow:deleted', { workflow: workflowName });
+      delete this.state.workflows[workflowName];
+      return;
+    }
+
+    try {
+      const newState = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as WorkflowState;
+      const oldState = this.state.workflows[workflowName];
+
+      this.state.workflows[workflowName] = newState;
+
+      // Detect phase changes
+      if (oldState && newState.phases) {
+        for (const [phaseName, phase] of Object.entries(newState.phases)) {
+          const oldPhase = oldState.phases?.[phaseName];
+          if (oldPhase && oldPhase.status !== phase.status) {
+            this.emit('workflow:phase', {
+              workflow: workflowName,
+              phase: phaseName,
+              oldStatus: oldPhase.status,
+              newStatus: phase.status
+            });
+          }
+        }
+      }
+
+      this.emit('workflow:changed', { workflow: workflowName, state: newState });
+
+      // Track in telemetry
+      telemetry.emitEvent('watch:workflow:change', {
+        workflow: workflowName,
+        status: newState.status
+      });
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  /**
+   * Load initial PRD state
+   */
+  private loadPRDState(filePath: string): void {
+    try {
+      if (fs.existsSync(filePath)) {
+        this.state.prd = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  /**
+   * Handle PRD changes
+   */
+  private handlePRDChange(filePath: string): void {
+    if (!fs.existsSync(filePath)) {
+      this.emit('prd:deleted');
+      this.state.prd = null;
+      return;
+    }
+
+    try {
+      const newPRD = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as PRD;
+      const oldPRD = this.state.prd;
+
+      // Detect story status changes
+      if (oldPRD && newPRD.stories) {
+        const oldStoryMap = new Map((oldPRD.stories || []).map(s => [s.id || s.title, s]));
+
+        for (const story of newPRD.stories) {
+          const oldStory = oldStoryMap.get(story.id || story.title);
+          if (oldStory && oldStory.status !== story.status) {
+            this.emit('prd:story', {
+              story,
+              oldStatus: oldStory.status,
+              newStatus: story.status
+            });
+          }
+        }
+      }
+
+      this.state.prd = newPRD;
+      this.emit('prd:changed', { prd: newPRD });
+
+      // Track in telemetry
+      const completed = newPRD.stories?.filter(s => s.status === 'complete').length || 0;
+      telemetry.emitEvent('watch:prd:change', {
+        name: newPRD.name,
+        stories: newPRD.stories?.length || 0,
+        completed
+      });
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  /**
+   * Load initial checkpoint state
+   */
+  private loadCheckpointState(): void {
+    try {
+      const status = checkpointEngine.getCheckpointStatus(this.projectRoot);
+      if (status.exists) {
+        this.state.checkpoints = status;
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  /**
+   * Handle checkpoint-related file changes
+   * Syncs checkpoints when planning files change and auto-pushes to server
+   */
+  private handleCheckpointChange(_filePath: string): void {
+    try {
+      // Sync checkpoints when any planning file changes
+      checkpointEngine.syncCheckpoints(this.projectRoot);
+      const newStatus = checkpointEngine.getCheckpointStatus(this.projectRoot);
+      const oldStatus = this.state.checkpoints;
+
+      if (newStatus.exists) {
+        // Check for newly completed checkpoints
+        if (oldStatus && oldStatus.checkpoints) {
+          for (const checkpoint of newStatus.checkpoints || []) {
+            const oldCheckpoint = oldStatus.checkpoints.find(c => c.id === checkpoint.id);
+            if (oldCheckpoint && !oldCheckpoint.completed && checkpoint.completed) {
+              this.emit('checkpoint:completed', {
+                checkpoint,
+                file: _filePath
+              });
+            }
+          }
+        }
+
+        // Check if percentage changed
+        if (!oldStatus || oldStatus.percentage !== newStatus.percentage) {
+          this.emit('checkpoint:progress', {
+            oldPercentage: oldStatus?.percentage || 0,
+            newPercentage: newStatus.percentage,
+            completed: newStatus.completed,
+            total: newStatus.total
+          });
+
+          // Auto-push to dashboard if authenticated
+          this.autoPushCheckpoints();
+        }
+
+        this.state.checkpoints = newStatus;
+        this.emit('checkpoint:changed', { status: newStatus });
+
+        // Track in telemetry
+        telemetry.emitEvent('watch:checkpoint:change', {
+          completed: newStatus.completed,
+          total: newStatus.total,
+          percentage: newStatus.percentage
+        });
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  /**
+   * Auto-push checkpoints to dashboard (non-blocking)
+   * Only pushes if authenticated and project is selected
+   */
+  private async autoPushCheckpoints(): Promise<void> {
+    try {
+      const checkpointUtils = require('./checkpoint-utils') as CheckpointUtilsModule;
+      const result = await checkpointUtils.pushCheckpointsToServer(this.projectRoot, {
+        quiet: true,
+        autoSync: true,
+        skipMetrics: true // Skip heavy metrics collection in watch mode
+      });
+
+      if (result.success) {
+        this.emit('checkpoint:synced', { success: true });
+      }
+    } catch {
+      // Silent fail - auto-push is best-effort
+    }
+  }
+
+  /**
+   * Stop watching
+   */
+  stop(): void {
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+    this.watchers = [];
+
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+
+    this.emit('stopped');
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): WatcherState {
+    return { ...this.state };
+  }
+}
+
+/**
+ * Create notification message
+ */
+function formatNotification(type: string, data: Record<string, unknown>): string {
+  const timestamp = new Date().toLocaleTimeString();
+
+  switch (type) {
+    case 'todo:completed':
+      return `${c.green}✓${c.reset} [${c.dim}${timestamp}${c.reset}] Todo completed: ${data.text}`;
+
+    case 'todo:added':
+      return `${c.blue}+${c.reset} [${c.dim}${timestamp}${c.reset}] Todo added: ${data.text}`;
+
+    case 'todo:removed':
+      return `${c.red}-${c.reset} [${c.dim}${timestamp}${c.reset}] Todo removed: ${data.text}`;
+
+    case 'todo:reopened':
+      return `${c.yellow}○${c.reset} [${c.dim}${timestamp}${c.reset}] Todo reopened: ${data.text}`;
+
+    case 'workflow:phase':
+      return `${c.cyan}◆${c.reset} [${c.dim}${timestamp}${c.reset}] ${data.workflow}/${data.phase}: ${data.oldStatus} → ${data.newStatus}`;
+
+    case 'workflow:changed':
+      return `${c.cyan}↻${c.reset} [${c.dim}${timestamp}${c.reset}] Workflow updated: ${data.workflow}`;
+
+    case 'prd:story': {
+      const story = data.story as Story;
+      return `${c.magenta}◇${c.reset} [${c.dim}${timestamp}${c.reset}] Story "${story.title}": ${data.oldStatus} → ${data.newStatus}`;
+    }
+
+    case 'prd:changed': {
+      const prd = data.prd as PRD;
+      return `${c.magenta}↻${c.reset} [${c.dim}${timestamp}${c.reset}] PRD updated: ${prd.name}`;
+    }
+
+    case 'checkpoint:completed': {
+      const checkpoint = data.checkpoint as Checkpoint;
+      return `${c.green}★${c.reset} [${c.dim}${timestamp}${c.reset}] Checkpoint completed: ${checkpoint.label}`;
+    }
+
+    case 'checkpoint:progress':
+      return `${c.cyan}▲${c.reset} [${c.dim}${timestamp}${c.reset}] Progress: ${data.oldPercentage}% → ${data.newPercentage}% (${data.completed}/${data.total})`;
+
+    case 'checkpoint:synced':
+      return `${c.green}↑${c.reset} [${c.dim}${timestamp}${c.reset}] Synced to dashboard`;
+
+    default:
+      return `${c.dim}[${timestamp}]${c.reset} ${type}: ${JSON.stringify(data)}`;
+  }
+}
+
+/**
+ * Draw status bar
+ */
+function drawStatusBar(state: WatcherState): string {
+  const todoStats = getTodoStats(state.todos);
+  const workflowCount = Object.keys(state.workflows).length;
+  const prdName = state.prd?.name || 'None';
+  const checkpointProgress = state.checkpoints?.percentage || 0;
+
+  const parts = [
+    `${c.cyan}Todos:${c.reset} ${todoStats.pending}/${todoStats.total}`,
+    `${c.cyan}Workflows:${c.reset} ${workflowCount}`,
+    `${c.cyan}Checkpoints:${c.reset} ${checkpointProgress}%`,
+    `${c.cyan}PRD:${c.reset} ${prdName}`
+  ];
+
+  return `${c.dim}${parts.join(' │ ')}${c.reset}`;
+}
+
+/**
+ * Run interactive watch mode
+ */
+async function runWatchMode(projectRoot: string, options: RunWatchOptions = {}): Promise<void> {
+  const watcher = new FileWatcher(projectRoot, options);
+
+  console.log(`
+${c.cyan}${c.bold}⚡ Bootspring Watch Mode${c.reset}
+${c.dim}Monitoring files for changes...${c.reset}
+${c.dim}Press Ctrl+C to exit${c.reset}
+`);
+
+  // Set up event handlers
+  watcher.on('started', () => {
+    console.log(drawStatusBar(watcher.getState()));
+    console.log();
+  });
+
+  watcher.on('todo:completed', (todo: Todo) => {
+    console.log(formatNotification('todo:completed', todo as unknown as Record<string, unknown>));
+  });
+
+  watcher.on('todo:added', (todo: Todo) => {
+    console.log(formatNotification('todo:added', todo as unknown as Record<string, unknown>));
+  });
+
+  watcher.on('todo:removed', (todo: Todo) => {
+    console.log(formatNotification('todo:removed', todo as unknown as Record<string, unknown>));
+  });
+
+  watcher.on('todo:reopened', (todo: Todo) => {
+    console.log(formatNotification('todo:reopened', todo as unknown as Record<string, unknown>));
+  });
+
+  watcher.on('workflow:phase', (data: Record<string, unknown>) => {
+    console.log(formatNotification('workflow:phase', data));
+  });
+
+  watcher.on('workflow:changed', (data: Record<string, unknown>) => {
+    if (options.verbose) {
+      console.log(formatNotification('workflow:changed', data));
+    }
+  });
+
+  watcher.on('prd:story', (data: Record<string, unknown>) => {
+    console.log(formatNotification('prd:story', data));
+  });
+
+  watcher.on('prd:changed', (data: Record<string, unknown>) => {
+    if (options.verbose) {
+      console.log(formatNotification('prd:changed', data));
+    }
+  });
+
+  watcher.on('checkpoint:completed', (data: Record<string, unknown>) => {
+    console.log(formatNotification('checkpoint:completed', data));
+  });
+
+  watcher.on('checkpoint:progress', (data: Record<string, unknown>) => {
+    console.log(formatNotification('checkpoint:progress', data));
+  });
+
+  watcher.on('checkpoint:synced', (data: Record<string, unknown>) => {
+    console.log(formatNotification('checkpoint:synced', data));
+  });
+
+  watcher.on('error', (err: { type: string; error?: Error }) => {
+    console.log(`${c.red}Error:${c.reset} ${err.type} - ${err.error?.message || 'Unknown error'}`);
+  });
+
+  // Start watching
+  watcher.start();
+
+  // Handle exit
+  process.on('SIGINT', () => {
+    console.log(`\n${c.dim}Stopping watch mode...${c.reset}`);
+    watcher.stop();
+    process.exit(0);
+  });
+
+  // Keep process alive
+  return new Promise(() => {});
+}
+
+/**
+ * Show help
+ */
+function showHelp(): void {
+  console.log(`
+${c.cyan}${c.bold}⚡ Bootspring Watch${c.reset}
+${c.dim}Real-time file watching and sync${c.reset}
+
+${c.bold}Usage:${c.reset}
+  bootspring watch [options]
+
+${c.bold}Options:${c.reset}
+  --todos           Watch only todo.md
+  --workflows       Watch only workflow states
+  --prd             Watch only PRD file
+  --checkpoints     Watch only checkpoints
+  --verbose         Show all change events
+  --debounce <ms>   Debounce interval (default: 300)
+
+${c.bold}Watched Files:${c.reset}
+  - todo.md                            Task changes
+  - .bootspring/*/workflow-state.json  Workflow phase changes
+  - tasks/prd.json                     Story status changes
+  - planning/*.md                      Checkpoint progress
+
+${c.bold}Events:${c.reset}
+  ${c.green}✓${c.reset} Todo completed
+  ${c.blue}+${c.reset} Todo added
+  ${c.red}-${c.reset} Todo removed
+  ${c.cyan}◆${c.reset} Workflow phase change
+  ${c.magenta}◇${c.reset} PRD story change
+  ${c.green}★${c.reset} Checkpoint completed
+  ${c.cyan}▲${c.reset} Checkpoint progress
+
+${c.bold}Examples:${c.reset}
+  bootspring watch                   # Watch all files
+  bootspring watch --todos           # Watch only todos
+  bootspring watch --verbose         # Show all events
+`);
+}
+
+/**
+ * Run watch command
+ */
+export async function run(args: string[]): Promise<void> {
+  const parsedArgs = utils.parseArgs(args);
+  const subcommand = parsedArgs._[0];
+
+  if (subcommand === 'help' || parsedArgs.help || parsedArgs.h) {
+    showHelp();
+    return;
+  }
+
+  const cfg = config.load();
+  const projectRoot = cfg._projectRoot;
+
+  const options: RunWatchOptions = {
+    watchTodos: !parsedArgs.workflows && !parsedArgs.prd,
+    watchWorkflows: !parsedArgs.todos && !parsedArgs.prd,
+    watchPRD: !parsedArgs.todos && !parsedArgs.workflows,
+    verbose: parsedArgs.verbose,
+    debounceMs: parseInt(parsedArgs.debounce as string, 10) || 300
+  };
+
+  // If specific flags are set, only watch those
+  if (parsedArgs.todos) {
+    options.watchTodos = true;
+    options.watchWorkflows = false;
+    options.watchPRD = false;
+  }
+  if (parsedArgs.workflows) {
+    options.watchTodos = false;
+    options.watchWorkflows = true;
+    options.watchPRD = false;
+  }
+  if (parsedArgs.prd) {
+    options.watchTodos = false;
+    options.watchWorkflows = false;
+    options.watchPRD = true;
+  }
+
+  await runWatchMode(projectRoot, options);
+}
+
+export { FileWatcher, parseTodoFile, diffTodos, getTodoStats };