keystone-cli 1.0.3 → 1.1.0

package/src/cli.ts

@@ -1,479 +1,305 @@
 #!/usr/bin/env bun
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readFileSync, watch, writeFileSync } from 'node:fs';
+import type { FSWatcher } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { Command } from 'commander';
 
-import exploreAgent from './templates/agents/explore.md' with { type: 'text' };
-import generalAgent from './templates/agents/general.md' with { type: 'text' };
-import architectAgent from './templates/agents/keystone-architect.md' with { type: 'text' };
-import softwareEngineerAgent from './templates/agents/software-engineer.md' with { type: 'text' };
-import summarizerAgent from './templates/agents/summarizer.md' with { type: 'text' };
-import testerAgent from './templates/agents/tester.md' with { type: 'text' };
-import decomposeImplementWorkflow from './templates/decompose-implement.yaml' with { type: 'text' };
-import decomposeWorkflow from './templates/decompose-problem.yaml' with { type: 'text' };
-import decomposeResearchWorkflow from './templates/decompose-research.yaml' with { type: 'text' };
-import decomposeReviewWorkflow from './templates/decompose-review.yaml' with { type: 'text' };
-import devWorkflow from './templates/dev.yaml' with { type: 'text' };
-// Default templates
-import scaffoldWorkflow from './templates/scaffold-feature.yaml' with { type: 'text' };
-import scaffoldGenerateWorkflow from './templates/scaffold-generate.yaml' with { type: 'text' };
-import scaffoldPlanWorkflow from './templates/scaffold-plan.yaml' with { type: 'text' };
-
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { MemoryDb } from './db/memory-db.ts';
 import { WorkflowDb, type WorkflowRun } from './db/workflow-db.ts';
+import { ExpressionEvaluator } from './expression/evaluator.ts';
+import type { Workflow } from './parser/schema.ts';
 import type { TestDefinition } from './parser/test-schema.ts';
 import { WorkflowParser } from './parser/workflow-parser.ts';
 import { WorkflowSuspendedError, WorkflowWaitingError } from './runner/step-executor.ts';
 import { TestHarness } from './runner/test-harness.ts';
 import { ConfigLoader } from './utils/config-loader.ts';
 import { LIMITS } from './utils/constants.ts';
-import { ConsoleLogger } from './utils/logger.ts';
-import { generateMermaidGraph, renderWorkflowAsAscii } from './utils/mermaid.ts';
+import { container } from './utils/container.ts';
+import { ConsoleLogger, SilentLogger } from './utils/logger.ts';
 import { WorkflowRegistry } from './utils/workflow-registry.ts';
 
+// Import modular commands
+import {
+  parseInputs,
+  registerDocCommand,
+  registerEventCommand,
+  registerGraphCommand,
+  registerInitCommand,
+  registerRunCommand,
+  registerSchemaCommand,
+  registerValidateCommand,
+} from './commands/index.ts';
+
 import pkg from '../package.json' with { type: 'json' };
 
+// Bootstrap DI container with default services
+container.factory('logger', () => new ConsoleLogger());
+container.factory('db', () => new WorkflowDb());
+container.factory('memoryDb', () => new MemoryDb());
+
 const program = new Command();
 const defaultRetentionDays = ConfigLoader.load().storage?.retention_days ?? 30;
-const MAX_INPUT_STRING_LENGTH = LIMITS.MAX_INPUT_STRING_LENGTH;
 
 program
   .name('keystone')
   .description('A local-first, declarative, agentic workflow orchestrator')
   .version(pkg.version);
 
-/**
- * Parse CLI input pairs (key=value) into a record.
- * Attempts JSON parsing for complex types, falls back to string for simple values.
- *
- * @param pairs Array of key=value strings
- * @returns Record of parsed inputs
- */
-const parseInputs = (pairs?: string[]): Record<string, unknown> => {
-  const inputs: Record<string, unknown> = Object.create(null);
-  const blockedKeys = new Set(['__proto__', 'prototype', 'constructor']);
-  if (!pairs) return inputs;
-  for (const pair of pairs) {
-    const index = pair.indexOf('=');
-    if (index <= 0) {
-      console.warn(`⚠️  Invalid input format: "${pair}" (expected key=value)`);
-      continue;
-    }
-    const key = pair.slice(0, index);
-    const value = pair.slice(index + 1);
+// Register modular commands
+registerInitCommand(program);
+registerValidateCommand(program);
+registerGraphCommand(program);
+registerDocCommand(program);
+registerSchemaCommand(program);
+registerEventCommand(program);
+registerRunCommand(program);
+
+// Helper function used by remaining commands (rerun)
+const collectDownstreamSteps = (workflow: Workflow, fromStepId: string): string[] => {
+  const stepIds = new Set(workflow.steps.map((step) => step.id));
+  if (!stepIds.has(fromStepId)) {
+    throw new Error(`Step not found in workflow: ${fromStepId}`);
+  }
 
-    // Validate key format (no special characters that could cause issues)
-    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
-      console.warn(`⚠️  Invalid input key: "${key}" (use alphanumeric and underscores only)`);
-      continue;
-    }
-    if (blockedKeys.has(key)) {
-      console.warn(`⚠️  Invalid input key: "${key}" (reserved keyword)`);
-      continue;
+  const dependents = new Map<string, Set<string>>();
+  for (const step of workflow.steps) {
+    for (const dep of step.needs) {
+      if (!dependents.has(dep)) {
+        dependents.set(dep, new Set());
+      }
+      dependents.get(dep)?.add(step.id);
     }
+  }
 
-    try {
-      // Attempt JSON parse for objects, arrays, booleans, numbers
-      const parsed = JSON.parse(value);
-      if (typeof parsed === 'string') {
-        if (parsed.length > MAX_INPUT_STRING_LENGTH) {
-          console.warn(
-            `⚠️  Input "${key}" exceeds maximum length of ${MAX_INPUT_STRING_LENGTH} characters`
-          );
-          continue;
-        }
-        if (parsed.includes('\u0000')) {
-          console.warn(`⚠️  Input "${key}" contains invalid null characters`);
-          continue;
-        }
+  const queue = [fromStepId];
+  const result = new Set<string>([fromStepId]);
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) continue;
+    for (const next of dependents.get(current) || []) {
+      if (!result.has(next)) {
+        result.add(next);
+        queue.push(next);
       }
-      inputs[key] = parsed;
-    } catch {
-      if (value.length > MAX_INPUT_STRING_LENGTH) {
-        console.warn(
-          `⚠️  Input "${key}" exceeds maximum length of ${MAX_INPUT_STRING_LENGTH} characters`
-        );
-        continue;
-      }
-      if (value.includes('\u0000')) {
-        console.warn(`⚠️  Input "${key}" contains invalid null characters`);
-        continue;
-      }
-      // Check if it looks like malformed JSON (starts with { or [)
-      if ((value.startsWith('{') || value.startsWith('[')) && value.length > 1) {
-        console.warn(
-          `⚠️  Input "${key}" looks like JSON but failed to parse. Check for syntax errors.`
-        );
-        console.warn(`   Value: ${value.slice(0, 50)}${value.length > 50 ? '...' : ''}`);
-      }
-      // Fall back to string value
-      inputs[key] = value;
     }
   }
-  return inputs;
+
+  return Array.from(result);
 };
 
-// ===== keystone init =====
+// ===== keystone watch =====
 program
-  .command('init')
-  .description('Initialize a new Keystone project')
-  .action(() => {
-    console.log('🏛️  Initializing Keystone project...\n');
-
-    // Create directories
-    const dirs = ['.keystone', '.keystone/workflows', '.keystone/workflows/agents'];
-    for (const dir of dirs) {
-      if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-        console.log(`✓ Created ${dir}/`);
-      } else {
-        console.log(`⊘ ${dir}/ already exists`);
-      }
-    }
+  .command('watch')
+  .description('Watch a workflow and re-run on changes')
+  .argument('<workflow>', 'Workflow name or path to workflow file')
+  .option('-i, --input <key=value...>', 'Input values')
+  .option('--debug', 'Enable interactive debug mode on failure')
+  .option('--events', 'Emit structured JSON events (NDJSON) to stdout')
+  .option('--debounce <ms>', 'Debounce delay in milliseconds', '200')
+  .action(async (workflowPathArg, options) => {
+    const inputs = parseInputs(options.input);
+    const eventsEnabled = !!options.events;
+    const logger = eventsEnabled ? new SilentLogger() : new ConsoleLogger();
+    const onEvent = eventsEnabled
+      ? (event: unknown) => {
+          process.stdout.write(`${JSON.stringify(event)}\n`);
+        }
+      : undefined;
+    const debounceMs = Number.parseInt(options.debounce, 10);
 
-    // Create default config
-    const configPath = '.keystone/config.yaml';
-    if (!existsSync(configPath)) {
-      const defaultConfig = `# Keystone Configuration
-default_provider: openai
-
-providers:
-  openai:
-    type: openai
-    base_url: https://api.openai.com/v1
-    api_key_env: OPENAI_API_KEY
-    default_model: gpt-4o
-  anthropic:
-    type: anthropic
-    base_url: https://api.anthropic.com/v1
-    api_key_env: ANTHROPIC_API_KEY
-    default_model: claude-3-5-sonnet-20240620
-  groq:
-    type: openai
-    base_url: https://api.groq.com/openai/v1
-    api_key_env: GROQ_API_KEY
-    default_model: llama-3.3-70b-versatile
-
-model_mappings:
-  "gpt-*": openai
-  "claude-*": anthropic
-  "o1-*": openai
-  "llama-*": groq
-
-# mcp_servers:
-#   filesystem:
-#     command: npx
-#     args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
-
-# engines:
-#   allowlist:
-#     codex:
-#       command: codex
-#       version: "1.2.3"
-#       versionArgs: ["--version"]
-
-storage:
-  retention_days: 30
-`;
-      writeFileSync(configPath, defaultConfig);
-      console.log(`✓ Created ${configPath}`);
-    } else {
-      console.log(`⊘ ${configPath} already exists`);
+    if (!Number.isFinite(debounceMs) || debounceMs < 0) {
+      console.error('✗ debounce must be a non-negative integer');
+      process.exit(1);
     }
 
-    // Create example .env
-    const envPath = '.env';
-    if (!existsSync(envPath)) {
-      const envTemplate = `# API Keys and Secrets
-# OPENAI_API_KEY=sk-...
-# ANTHROPIC_API_KEY=sk-ant-...
-`;
-      writeFileSync(envPath, envTemplate);
-      console.log(`✓ Created ${envPath}`);
-    } else {
-      console.log(`⊘ ${envPath} already exists`);
+    let resolvedPath: string;
+    try {
+      resolvedPath = WorkflowRegistry.resolvePath(workflowPathArg);
+    } catch (error) {
+      console.error(
+        '✗ Failed to resolve workflow:',
+        error instanceof Error ? error.message : error
+      );
+      process.exit(1);
     }
 
-    // Seed default workflows and agents
-    const seeds = [
-      {
-        path: '.keystone/workflows/scaffold-feature.yaml',
-        content: scaffoldWorkflow,
-      },
-      {
-        path: '.keystone/workflows/scaffold-plan.yaml',
-        content: scaffoldPlanWorkflow,
-      },
-      {
-        path: '.keystone/workflows/scaffold-generate.yaml',
-        content: scaffoldGenerateWorkflow,
-      },
-      {
-        path: '.keystone/workflows/decompose-problem.yaml',
-        content: decomposeWorkflow,
-      },
-      {
-        path: '.keystone/workflows/decompose-research.yaml',
-        content: decomposeResearchWorkflow,
-      },
-      {
-        path: '.keystone/workflows/decompose-implement.yaml',
-        content: decomposeImplementWorkflow,
-      },
-      {
-        path: '.keystone/workflows/decompose-review.yaml',
-        content: decomposeReviewWorkflow,
-      },
-      {
-        path: '.keystone/workflows/agents/keystone-architect.md',
-        content: architectAgent,
-      },
-      {
-        path: '.keystone/workflows/agents/general.md',
-        content: generalAgent,
-      },
-      {
-        path: '.keystone/workflows/agents/explore.md',
-        content: exploreAgent,
-      },
-      {
-        path: '.keystone/workflows/agents/software-engineer.md',
-        content: softwareEngineerAgent,
-      },
-      {
-        path: '.keystone/workflows/agents/summarizer.md',
-        content: summarizerAgent,
-      },
-      {
-        path: '.keystone/workflows/dev.yaml',
-        content: devWorkflow,
-      },
-      {
-        path: '.keystone/workflows/agents/tester.md',
-        content: testerAgent,
-      },
-    ];
+    const watchers = new Map<string, FSWatcher>();
+    const warned = new Set<string>();
+    let running = false;
+    let rerunQueued = false;
+    let debounceTimer: NodeJS.Timeout | undefined;
 
-    for (const seed of seeds) {
-      if (!existsSync(seed.path)) {
-        writeFileSync(seed.path, seed.content);
-        console.log(`✓ Seeded ${seed.path}`);
-      } else {
-        console.log(`⊘ ${seed.path} already exists`);
+    const logInfo = (message: string) => {
+      if (!eventsEnabled) {
+        console.log(message);
       }
-    }
+    };
 
-    console.log('\n✨ Keystone project initialized!');
-    console.log('\nNext steps:');
-    console.log('  1. Add your API keys to .env');
-    console.log('  2. Create a workflow in .keystone/workflows/');
-    console.log('  3. Run: keystone run <workflow>');
-  });
+    const logWarn = (message: string) => {
+      if (!eventsEnabled) {
+        console.warn(message);
+      }
+    };
 
-// ===== keystone validate =====
-program
-  .command('validate')
-  .description('Validate workflow files')
-  .argument('[path]', 'Workflow file or directory to validate (default: .keystone/workflows/)')
-  .option('--strict', 'Enable strict validation (schemas, enums)')
-  .option('--explain', 'Show detailed error context with suggestions')
-  .action(async (pathArg, options) => {
-    const path = pathArg || '.keystone/workflows/';
+    const normalizePath = (filePath: string) => resolve(filePath);
 
-    try {
-      let files: string[] = [];
-      if (existsSync(path) && (path.endsWith('.yaml') || path.endsWith('.yml'))) {
-        files = [path];
-      } else if (existsSync(path)) {
-        const glob = new Bun.Glob('**/*.{yaml,yml}');
-        for await (const file of glob.scan(path)) {
-          files.push(join(path, file));
+    const scheduleRun = (reason?: string) => {
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+      }
+      debounceTimer = setTimeout(() => {
+        debounceTimer = undefined;
+        if (reason && !eventsEnabled) {
+          console.log(`Change detected in ${reason}. Rerunning...`);
         }
-      } else {
-        try {
-          const resolved = WorkflowRegistry.resolvePath(path);
-          files = [resolved];
-        } catch {
-          console.error(`✗ Path not found: ${path}`);
-          process.exit(1);
+        void runWorkflow();
+      }, debounceMs);
+    };
+
+    const ensureWatcher = (filePath: string) => {
+      if (watchers.has(filePath)) return;
+      if (!existsSync(filePath)) {
+        if (!warned.has(filePath)) {
+          warned.add(filePath);
+          logWarn(`⚠️  Watch skipped (path not found): ${filePath}`);
+        }
+        return;
+      }
+      try {
+        const watcher = watch(filePath, () => scheduleRun(filePath));
+        watchers.set(filePath, watcher);
+      } catch (error) {
+        if (!warned.has(filePath)) {
+          warned.add(filePath);
+          logWarn(
+            `⚠️  Failed to watch ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+          );
         }
       }
+    };
 
-      if (files.length === 0) {
-        console.log('⊘ No workflow files found to validate.');
-        return;
+    const updateWatchers = (paths: Set<string>) => {
+      for (const existing of Array.from(watchers.keys())) {
+        if (!paths.has(existing)) {
+          watchers.get(existing)?.close();
+          watchers.delete(existing);
+        }
+      }
+
+      for (const filePath of paths) {
+        ensureWatcher(filePath);
       }
 
-      console.log(`🔍 Validating ${files.length} workflow(s)...\n`);
+      logInfo(`Watching ${paths.size} file(s).`);
+    };
 
-      let successCount = 0;
-      let failCount = 0;
+    const collectWatchPaths = (
+      workflowPath: string,
+      workflow: Workflow,
+      visited: Set<string> = new Set()
+    ): Set<string> => {
+      const normalizedPath = normalizePath(workflowPath);
+      if (visited.has(normalizedPath)) return new Set();
+      visited.add(normalizedPath);
+
+      const watchPaths = new Set<string>([normalizedPath]);
+      const baseDir = dirname(workflowPath);
+      const allSteps = [...workflow.steps, ...(workflow.errors || []), ...(workflow.finally || [])];
+
+      for (const step of allSteps) {
+        if (step.type === 'file' && step.op === 'read') {
+          if (ExpressionEvaluator.hasExpression(step.path)) {
+            const warningKey = `${workflowPath}:${step.id}:file`;
+            if (!warned.has(warningKey)) {
+              warned.add(warningKey);
+              logWarn(`⚠️  Watch skipped for dynamic file path in step "${step.id}".`);
+            }
+            continue;
+          }
+          watchPaths.add(normalizePath(resolve(baseDir, step.path)));
+        }
 
-      for (const file of files) {
-        try {
-          const workflow = WorkflowParser.loadWorkflow(file);
-          if (options.strict) {
-            const source = readFileSync(file, 'utf-8');
-            WorkflowParser.validateStrict(workflow, source);
+        if (step.type === 'workflow') {
+          if (ExpressionEvaluator.hasExpression(step.path)) {
+            const warningKey = `${workflowPath}:${step.id}:workflow`;
+            if (!warned.has(warningKey)) {
+              warned.add(warningKey);
+              logWarn(`⚠️  Watch skipped for dynamic workflow path in step "${step.id}".`);
+            }
+            continue;
           }
-          console.log(`  ✓ ${file.padEnd(40)} ${workflow.name} (${workflow.steps.length} steps)`);
-          successCount++;
-        } catch (error) {
-          if (options.explain) {
-            const { readFileSync } = await import('node:fs');
-            const { formatYamlError, renderError, formatError } = await import(
-              './utils/error-renderer.ts'
-            );
-            try {
-              const source = readFileSync(file, 'utf-8');
-              const formatted = formatYamlError(error as Error, source, file);
-              console.error(renderError({ message: formatted.summary, source, filePath: file }));
-            } catch {
-              console.error(
-                renderError({
-                  message: error instanceof Error ? error.message : String(error),
-                  filePath: file,
-                })
+          try {
+            const childPath = WorkflowRegistry.resolvePath(step.path, baseDir);
+            const childWorkflow = WorkflowParser.loadWorkflow(childPath);
+            for (const child of collectWatchPaths(childPath, childWorkflow, visited)) {
+              watchPaths.add(child);
+            }
+          } catch (error) {
+            const warningKey = `${workflowPath}:${step.id}:workflow-load`;
+            if (!warned.has(warningKey)) {
+              warned.add(warningKey);
+              logWarn(
+                `⚠️  Failed to load sub-workflow for step "${step.id}": ${
+                  error instanceof Error ? error.message : String(error)
+                }`
               );
             }
-          } else {
-            console.error(
-              `  ✗ ${file.padEnd(40)} ${error instanceof Error ? error.message : String(error)}`
-            );
           }
-          failCount++;
         }
       }
 
-      console.log(`\nSummary: ${successCount} passed, ${failCount} failed.`);
-      if (failCount > 0) {
-        process.exit(1);
-      }
-    } catch (error) {
-      console.error('✗ Validation failed:', error instanceof Error ? error.message : error);
-      process.exit(1);
-    }
-  });
+      return watchPaths;
+    };
 
-// ===== keystone graph =====
-program
-  .command('graph')
-  .description('Visualize a workflow as a Mermaid.js graph')
-  .argument('<workflow>', 'Workflow name or path to workflow file')
-  .action(async (workflowPath) => {
-    try {
-      const resolvedPath = WorkflowRegistry.resolvePath(workflowPath);
-      const workflow = WorkflowParser.loadWorkflow(resolvedPath);
-      const ascii = renderWorkflowAsAscii(workflow);
-      if (ascii) {
-        console.log(`\n${ascii}\n`);
-      } else {
-        const mermaid = generateMermaidGraph(workflow);
-        console.log('\n```mermaid');
-        console.log(mermaid);
-        console.log('```\n');
+    const runWorkflow = async () => {
+      if (running) {
+        rerunQueued = true;
+        return;
       }
-    } catch (error) {
-      console.error('✗ Failed to generate graph:', error instanceof Error ? error.message : error);
-      process.exit(1);
-    }
-  });
-
-// ===== keystone run =====
-program
-  .command('run')
-  .description('Execute a workflow')
-  .argument('<workflow>', 'Workflow name or path to workflow file')
-  .option('-i, --input <key=value...>', 'Input values')
-  .option('--dry-run', 'Show what would be executed without actually running it')
-  .option('--debug', 'Enable interactive debug mode on failure')
-  .option('--no-dedup', 'Disable idempotency/deduplication')
-  .option('--resume', 'Resume the last run of this workflow if it failed or was paused')
-  .option('--explain', 'Show detailed error context with suggestions on failure')
-  .action(async (workflowPathArg, options) => {
-    const inputs = parseInputs(options.input);
-    let resolvedPath: string | undefined;
+      running = true;
 
-    // Load and validate workflow
-    try {
-      resolvedPath = WorkflowRegistry.resolvePath(workflowPathArg);
-      const workflow = WorkflowParser.loadWorkflow(resolvedPath);
-
-      // Import WorkflowRunner dynamically
-      const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
-      const logger = new ConsoleLogger();
-
-      let resumeRunId: string | undefined;
-
-      // Handle auto-resume
-      if (options.resume) {
-        const db = new WorkflowDb();
-        const lastRun = await db.getLastRun(workflow.name);
-        db.close();
+      try {
+        const workflow = WorkflowParser.loadWorkflow(resolvedPath);
+        const watchPaths = collectWatchPaths(resolvedPath, workflow);
+        updateWatchers(watchPaths);
+
+        const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
+        const runner = new WorkflowRunner(workflow, {
+          inputs,
+          workflowDir: dirname(resolvedPath),
+          debug: !!options.debug,
+          logger,
+          onEvent,
+        });
 
-        if (lastRun) {
-          if (
-            lastRun.status === 'failed' ||
-            lastRun.status === 'paused' ||
-            lastRun.status === 'running'
-          ) {
-            resumeRunId = lastRun.id;
-            console.log(
-              `Resuming run ${lastRun.id} (status: ${lastRun.status}) from ${new Date(
-                lastRun.started_at
-              ).toLocaleString()}`
-            );
-          } else {
-            console.log(`Last run ${lastRun.id} completed successfully. Starting new run.`);
-          }
-        } else {
-          console.log('No previous run found. Starting new run.');
+        const outputs = await runner.run();
+        if (!eventsEnabled && Object.keys(outputs).length > 0) {
+          console.log('Outputs:');
+          console.log(JSON.stringify(runner.redact(outputs), null, 2));
+        }
+      } catch (error) {
+        console.error('✗ Watch run failed:', error instanceof Error ? error.message : error);
+      } finally {
+        running = false;
+        if (rerunQueued) {
+          rerunQueued = false;
+          scheduleRun();
         }
       }
+    };
 
-      const runner = new WorkflowRunner(workflow, {
-        inputs: resumeRunId ? undefined : inputs,
-        resumeInputs: resumeRunId ? inputs : undefined,
-        workflowDir: dirname(resolvedPath),
-        dryRun: !!options.dryRun,
-        debug: !!options.debug,
-        dedup: options.dedup,
-        resumeRunId,
-        logger,
-      });
-
-      const outputs = await runner.run();
+    updateWatchers(new Set([normalizePath(resolvedPath)]));
+    logInfo(`Watching workflow: ${resolvedPath}`);
+    scheduleRun('initial');
 
-      if (Object.keys(outputs).length > 0) {
-        console.log('Outputs:');
-        console.log(JSON.stringify(runner.redact(outputs), null, 2));
+    process.on('SIGINT', () => {
+      for (const watcher of watchers.values()) {
+        watcher.close();
       }
+      logInfo('\nStopping watch.');
       process.exit(0);
-    } catch (error) {
-      if (options.explain) {
-        const message = error instanceof Error ? error.message : String(error);
-        try {
-          const { readFileSync } = await import('node:fs');
-          const { renderError } = await import('./utils/error-renderer.ts');
-          const source = resolvedPath ? readFileSync(resolvedPath, 'utf-8') : undefined;
-          console.error(
-            renderError({
-              message,
-              source,
-              filePath: resolvedPath,
-            })
-          );
-        } catch {
-          console.error('✗ Failed to execute workflow:', message);
-        }
-      } else {
-        console.error(
-          '✗ Failed to execute workflow:',
-          error instanceof Error ? error.message : error
-        );
-      }
-      process.exit(1);
-    }
+    });
   });
 
 // ===== keystone test =====
@@ -516,7 +342,7 @@ program
           const workflowPath = WorkflowRegistry.resolvePath(testDef.workflow);
           const workflow = WorkflowParser.loadWorkflow(workflowPath);
 
-          const harness = new TestHarness(workflow, testDef.fixture);
+          const harness = new TestHarness(workflow, testDef.fixture, testDef.options);
           const result = await harness.run();
 
           if (!testDef.snapshot || options.update) {
@@ -622,9 +448,11 @@ program
   .argument('<run_id>', 'Run ID to resume')
   .option('-w, --workflow <path>', 'Path to workflow file (auto-detected if not specified)')
   .option('-i, --input <key=value...>', 'Input values for resume')
+  .option('--events', 'Emit structured JSON events (NDJSON) to stdout')
   .action(async (runId, options) => {
     try {
       const db = new WorkflowDb();
+      const eventsEnabled = !!options.events;
 
       // Load run from database to get workflow name
       const run = await db.getRun(runId);
@@ -635,7 +463,9 @@ program
         process.exit(1);
       }
 
-      console.log(`Found run: ${run.workflow_name} (status: ${run.status})`);
+      if (!eventsEnabled) {
+        console.log(`Found run: ${run.workflow_name} (status: ${run.status})`);
+      }
 
       // Determine workflow file path
       let workflowPath = options.workflow;
@@ -652,7 +482,9 @@ program
         }
       }
 
-      console.log(`Loading workflow from: ${workflowPath}\n`);
+      if (!eventsEnabled) {
+        console.log(`Loading workflow from: ${workflowPath}\n`);
+      }
 
       // Close DB before loading workflow (will be reopened by runner)
       db.close();
@@ -662,18 +494,24 @@ program
 
       // Import WorkflowRunner dynamically
       const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
-      const logger = new ConsoleLogger();
+      const logger = eventsEnabled ? new SilentLogger() : new ConsoleLogger();
+      const onEvent = eventsEnabled
+        ? (event: unknown) => {
+            process.stdout.write(`${JSON.stringify(event)}\n`);
+          }
+        : undefined;
       const inputs = parseInputs(options.input);
       const runner = new WorkflowRunner(workflow, {
         resumeRunId: runId,
         resumeInputs: inputs,
         workflowDir: dirname(workflowPath),
         logger,
+        onEvent,
       });
 
       const outputs = await runner.run();
 
-      if (Object.keys(outputs).length > 0) {
+      if (!eventsEnabled && Object.keys(outputs).length > 0) {
         console.log('Outputs:');
         console.log(JSON.stringify(runner.redact(outputs), null, 2));
       }
@@ -684,6 +522,94 @@ program
     }
   });
 
+// ===== keystone rerun =====
+program
+  .command('rerun')
+  .description('Rerun a workflow from a specific step (invalidates downstream steps)')
+  .argument('<workflow>', 'Workflow name or path to workflow file')
+  .requiredOption('--from <step_id>', 'Step ID to rerun (downstream steps will be invalidated)')
+  .option('-r, --run <run_id>', 'Run ID to rerun (defaults to last run of the workflow)')
+  .option('-i, --input <key=value...>', 'Input values for rerun')
+  .option('--events', 'Emit structured JSON events (NDJSON) to stdout')
+  .action(async (workflowPathArg, options) => {
+    let db: WorkflowDb | undefined;
+    try {
+      const resolvedPath = WorkflowRegistry.resolvePath(workflowPathArg);
+      const workflow = WorkflowParser.loadWorkflow(resolvedPath);
+      const inputs = parseInputs(options.input);
+      const eventsEnabled = !!options.events;
+
+      db = new WorkflowDb();
+      const runId =
+        options.run ||
+        (await db.getLastRun(workflow.name))?.id ||
+        ((): never => {
+          throw new Error(`No runs found for workflow "${workflow.name}"`);
+        })();
+
+      const run = await db.getRun(runId);
+      if (!run) {
+        throw new Error(`Run not found: ${runId}`);
+      }
+
+      if (run.workflow_name !== workflow.name) {
+        console.warn(
+          `⚠️  Run ${runId} is for workflow "${run.workflow_name}", but you provided "${workflow.name}".`
+        );
+      }
+
+      if (run.status === 'running') {
+        console.warn('⚠️  Rerunning a run marked as running. Ensure no other instances are active.');
+      }
+
+      const stepIds = collectDownstreamSteps(workflow, options.from);
+      const clearedSteps = await db.clearStepExecutions(runId, stepIds);
+      const clearedIdempotency = await db.clearIdempotencyRecordsForSteps(runId, stepIds);
+      const clearedTimers = await db.clearTimersForSteps(runId, stepIds);
+      const clearedCompensations = await db.clearCompensationsForSteps(runId, stepIds);
+
+      await db.updateRunStatus(runId, 'paused');
+      db.close();
+      db = undefined;
+
+      if (!eventsEnabled) {
+        console.log(
+          `Cleared ${clearedSteps} step execution(s), ${clearedIdempotency} idempotency record(s), ${clearedTimers} timer(s), ${clearedCompensations} compensation(s).`
+        );
+        console.log(`Resuming run ${runId} from step ${options.from}...\n`);
+      }
+
+      const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
+      const logger = eventsEnabled ? new SilentLogger() : new ConsoleLogger();
+      const onEvent = eventsEnabled
+        ? (event: unknown) => {
+            process.stdout.write(`${JSON.stringify(event)}\n`);
+          }
+        : undefined;
+      const runner = new WorkflowRunner(workflow, {
+        resumeRunId: runId,
+        resumeInputs: inputs,
+        workflowDir: dirname(resolvedPath),
+        logger,
+        allowSuccessResume: true,
+        onEvent,
+      });
+
+      const outputs = await runner.run();
+
+      if (!eventsEnabled && Object.keys(outputs).length > 0) {
+        console.log('Outputs:');
+        console.log(JSON.stringify(runner.redact(outputs), null, 2));
+      }
+      process.exit(0);
+    } catch (error) {
+      console.error('✗ Failed to rerun workflow:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    } finally {
+      db?.close();
+    }
+  });
+
 // ===== keystone history =====
 program
   .command('history')
@@ -1881,9 +1807,11 @@ _keystone() {
       commands=(
         'init:Initialize a new Keystone project'
         'validate:Validate workflow files'
+        'lint:Lint workflow files'
         'graph:Visualize a workflow as a Mermaid.js graph'
         'run:Execute a workflow'
         'resume:Resume a paused or failed workflow run'
+        'rerun:Rerun a workflow from a specific step'
         'workflows:List available workflows'
         'history:List recent workflow runs'
         'logs:Show logs for a workflow run'
@@ -1909,11 +1837,17 @@ _keystone() {
         validate)
           _arguments ':path:_files'
           ;;
+        lint)
+          _arguments ':path:_files'
+          ;;
         resume)
           _arguments \\
             '(-i --input)'{-i,--input}'[Input values]:key=value' \\
             ':run_id:__keystone_runs'
           ;;
+        rerun)
+          _arguments ':workflow:__keystone_workflows'
+          ;;
         logs)
           _arguments ':run_id:__keystone_runs'
           ;;
@@ -1949,10 +1883,10 @@ __keystone_runs() {
   COMPREPLY=()
   cur="\${COMP_WORDS[COMP_CWORD]}"
   prev="\${COMP_WORDS[COMP_CWORD - 1]}"
-  opts="init validate graph run resume workflows history logs prune ui mcp config auth completion"
+  opts="init validate lint graph run watch resume rerun workflows history logs prune ui mcp config auth completion"
 
   case "\${prev}" in
-    run|graph)
+    run|graph|rerun)
       local workflows=$(keystone _list-workflows 2>/dev/null)
       COMPREPLY=( $(compgen -W "\${workflows}" -- \${cur}) )
       return 0