keystone-cli 0.5.0 → 0.6.0

package/src/runner/auto-heal.test.ts

@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, jest, test } from 'bun:test';
+import type { Step, Workflow } from '../parser/schema';
+import * as StepExecutor from './step-executor';
+import { WorkflowRunner } from './workflow-runner';
+
+describe('WorkflowRunner Auto-Heal', () => {
+  beforeEach(() => {
+    jest.fn();
+  });
+
+  test('should attempt to auto-heal a failing step', async () => {
+    const workflow: Workflow = {
+      name: 'auto-heal-test',
+      steps: [
+        {
+          id: 'fail-step',
+          type: 'shell',
+          run: 'exit 1',
+          auto_heal: {
+            agent: 'fixer-agent',
+            maxAttempts: 1,
+          },
+        } as Step,
+      ],
+    };
+
+    const runner = new WorkflowRunner(workflow, {
+      logger: { log: () => {}, error: () => {}, warn: () => {} },
+      dbPath: ':memory:',
+    });
+
+    // biome-ignore lint/suspicious/noExplicitAny: Accessing private property for testing
+    const db = (runner as any).db;
+    await db.createRun(runner.getRunId(), workflow.name, {});
+
+    const spy = jest.spyOn(StepExecutor, 'executeStep');
+
+    spy.mockImplementation(async (step, _context) => {
+      if (step.id === 'fail-step-healer') {
+        return {
+          status: 'success',
+          output: { run: 'echo "fixed"' },
+        };
+      }
+
+      if (step.id === 'fail-step') {
+        // biome-ignore lint/suspicious/noExplicitAny: Accessing run property dynamically
+        if ((step as any).run === 'echo "fixed"') {
+          return { status: 'success', output: 'fixed' };
+        }
+        return { status: 'failed', output: null, error: 'Command failed' };
+      }
+
+      return { status: 'failed', output: null, error: 'Unknown step' };
+    });
+
+    // biome-ignore lint/suspicious/noExplicitAny: Accessing private property for testing
+    await (runner as any).executeStepWithForeach(workflow.steps[0]);
+
+    expect(spy).toHaveBeenCalledTimes(3);
+
+    spy.mockRestore();
+  });
+});

package/src/runner/debug-repl.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import { PassThrough } from 'node:stream';
+import type { ExpressionContext } from '../expression/evaluator.ts';
+import type { Step } from '../parser/schema.ts';
+import { DebugRepl } from './debug-repl.ts';
+
+describe('DebugRepl', () => {
+  const mockContext: ExpressionContext = { inputs: { foo: 'bar' } };
+  // biome-ignore lint/suspicious/noExplicitAny: mock step typing
+  const mockStep: Step = { id: 'test-step', type: 'shell', run: 'echo "fail"' } as any;
+  const mockError = new Error('Test Error');
+
+  test('should resolve with "skip" when user types "skip"', async () => {
+    const input = new PassThrough();
+    const output = new PassThrough();
+    const mockLogger = { log: () => {}, error: () => {}, warn: () => {} };
+    const repl = new DebugRepl(mockContext, mockStep, mockError, mockLogger, input, output);
+
+    const promise = repl.start();
+
+    // Wait a tick for prompt
+    await new Promise((r) => setTimeout(r, 10));
+
+    input.write('skip\n');
+
+    const result = await promise;
+    expect(result).toEqual({ type: 'skip' });
+  });
+
+  test('should resolve with "retry" when user types "retry"', async () => {
+    const input = new PassThrough();
+    const output = new PassThrough();
+    const mockLogger = { log: () => {}, error: () => {}, warn: () => {} };
+    const repl = new DebugRepl(mockContext, mockStep, mockError, mockLogger, input, output);
+
+    const promise = repl.start();
+
+    await new Promise((r) => setTimeout(r, 10));
+    input.write('retry\n');
+
+    const result = await promise;
+    expect(result.type).toBe('retry');
+    if (result.type === 'retry') {
+      expect(result.modifiedStep).toBe(mockStep);
+    }
+  });
+
+  test('should resolve with "continue_failure" when user types "exit"', async () => {
+    const input = new PassThrough();
+    const output = new PassThrough();
+    const mockLogger = { log: () => {}, error: () => {}, warn: () => {} };
+    const repl = new DebugRepl(mockContext, mockStep, mockError, mockLogger, input, output);
+
+    const promise = repl.start();
+
+    await new Promise((r) => setTimeout(r, 10));
+    input.write('exit\n');
+
+    const result = await promise;
+    expect(result).toEqual({ type: 'continue_failure' });
+  });
+
+  test('should parse shell commands correctly', () => {
+    // We import the function dynamically to test it, or we assume it's exported
+    const { parseShellCommand } = require('./debug-repl.ts');
+
+    expect(parseShellCommand('code')).toEqual(['code']);
+    expect(parseShellCommand('code --wait')).toEqual(['code', '--wait']);
+    expect(parseShellCommand('code --wait "some file"')).toEqual(['code', '--wait', 'some file']);
+    expect(parseShellCommand("vim 'my file'")).toEqual(['vim', 'my file']);
+    expect(parseShellCommand('editor -a -b -c')).toEqual(['editor', '-a', '-b', '-c']);
+    expect(parseShellCommand('  spaced   command  ')).toEqual(['spaced', 'command']);
+  });
+});

package/src/runner/debug-repl.ts

@@ -0,0 +1,225 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+import { stripVTControlCharacters } from 'node:util';
+import { type ExpressionContext, ExpressionEvaluator } from '../expression/evaluator.ts';
+import type { Step } from '../parser/schema.ts';
+import { extractJson } from '../utils/json-parser.ts';
+
+import { ConsoleLogger, type Logger } from '../utils/logger.ts';
+
+export type DebugAction =
+  | { type: 'retry'; modifiedStep?: Step }
+  | { type: 'skip' }
+  | { type: 'continue_failure' }; // Default behavior (exit debug mode, let it fail)
+
+export class DebugRepl {
+  constructor(
+    private context: ExpressionContext,
+    private step: Step,
+    private error: unknown,
+    private logger: Logger = new ConsoleLogger(),
+    private inputStream: NodeJS.ReadableStream = process.stdin,
+    private outputStream: NodeJS.WritableStream = process.stdout
+  ) {}
+
+  public async start(): Promise<DebugAction> {
+    this.logger.error(`\n❌ Step '${this.step.id}' failed.`);
+    this.logger.error(
+      `   Error: ${this.error instanceof Error ? this.error.message : String(this.error)}`
+    );
+    this.logger.log('\nEntering Debug Mode. Available commands:');
+    this.logger.log('  > context      (view current inputs/outputs involved in this step)');
+    this.logger.log('  > retry        (re-run step, optionally with edited definition)');
+    this.logger.log('  > edit         (edit the step definition in your $EDITOR)');
+    this.logger.log('  > skip         (skip this step and proceed)');
+    this.logger.log('  > eval <code>  (run JS expression against context)');
+    this.logger.log('  > exit         (resume failure/exit)');
+
+    const rl = readline.createInterface({
+      input: this.inputStream,
+      output: this.outputStream,
+      prompt: 'debug> ',
+    });
+
+    rl.prompt();
+
+    return new Promise((resolve) => {
+      rl.on('line', (line) => {
+        const trimmed = line.trim();
+        const [cmd, ...args] = trimmed.split(' ');
+        const argStr = args.join(' ');
+
+        switch (cmd) {
+          case 'context':
+            // Show meaningful context context
+            this.logger.log(JSON.stringify(this.context, null, 2));
+            break;
+
+          case 'retry':
+            rl.close();
+            resolve({ type: 'retry', modifiedStep: this.step });
+            break;
+
+          case 'skip':
+            rl.close();
+            resolve({ type: 'skip' });
+            break;
+
+          case 'exit':
+          case 'quit':
+            rl.close();
+            resolve({ type: 'continue_failure' });
+            break;
+
+          case 'edit': {
+            try {
+              const newStep = this.editStep(this.step);
+              if (newStep) {
+                this.step = newStep;
+                this.logger.log('✓ Step definition updated in memory. Type "retry" to run it.');
+              } else {
+                this.logger.log('No changes made.');
+              }
+            } catch (e) {
+              this.logger.error(`Error editing step: ${e}`);
+            }
+            break;
+          }
+
+          case 'eval':
+            try {
+              if (!argStr) {
+                this.logger.log('Usage: eval <expression>');
+              } else {
+                const result = ExpressionEvaluator.evaluateExpression(argStr, this.context);
+                this.logger.log(String(result));
+              }
+            } catch (e) {
+              this.logger.error(`Eval error: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            break;
+
+          case '':
+            break;
+
+          default:
+            this.logger.log(`Unknown command: ${cmd}`);
+            break;
+        }
+
+        if (cmd !== 'retry' && cmd !== 'skip' && cmd !== 'exit' && cmd !== 'quit') {
+          rl.prompt();
+        }
+      });
+    });
+  }
+
+  private editStep(step: Step): Step | null {
+    const editorEnv = process.env.EDITOR || 'vim'; // Default to vim if not set
+    // Validate editor name to prevent shell injection (allow alphanumeric, dash, underscore, slash, and spaces for args)
+    // We strictly block semicolon, pipe, ampersand, backtick, $ to prevent command injection
+    const safeEditor = /^[\w./\s-]+$/.test(editorEnv) ? editorEnv : 'vi';
+    if (safeEditor !== editorEnv) {
+      this.logger.warn(
+        `Warning: $EDITOR value "${editorEnv}" contains unsafe characters. Falling back to "vi".`
+      );
+    }
+    // Sanitize step ID to prevent path traversal
+    const sanitizedId = step.id.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const tempFile = path.join(os.tmpdir(), `keystone-step-${sanitizedId}-${Date.now()}.json`);
+
+    // Write step to temp file
+    fs.writeFileSync(tempFile, JSON.stringify(step, null, 2));
+
+    // Spawn editor
+    try {
+      // Parse editor string into command and args (e.g. "code --wait", "subl -w")
+      const [editorCmd, ...editorArgs] = parseShellCommand(safeEditor);
+
+      // Use stdio: 'inherit' to let the editor take over the terminal
+      // Note: shell: false for security - prevents injection via $EDITOR
+      const result = spawnSync(editorCmd, [...editorArgs, tempFile], {
+        stdio: 'inherit',
+      });
+
+      if (result.error) {
+        throw result.error;
+      }
+
+      // Read back
+      const content = fs.readFileSync(tempFile, 'utf-8');
+
+      // Parse JSON
+      // We use our safe extractor helper or just JSON.parse
+      try {
+        const newStep = JSON.parse(content);
+        // Basic validation: must have id and type
+        if (!newStep.id || !newStep.type) {
+          this.logger.error('Invalid step definition: missing id or type');
+          return null;
+        }
+        return newStep as Step;
+      } catch (e) {
+        this.logger.error('Failed to parse JSON from editor. Changes discarded.');
+        return null;
+      }
+    } finally {
+      if (fs.existsSync(tempFile)) {
+        fs.unlinkSync(tempFile);
+      }
+    }
+  }
+}
+
+/**
+ * Parses a shell command string into arguments, respecting quotes.
+ * Handles single quotes and double quotes.
+ * Example: 'code --wait' -> ['code', '--wait']
+ * Example: 'my-editor "some arg"' -> ['my-editor', 'some arg']
+ */
+export function parseShellCommand(command: string): string[] {
+  const args: string[] = [];
+  let currentArg = '';
+  let inDoubleQuote = false;
+  let inSingleQuote = false;
+
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i];
+
+    if (inDoubleQuote) {
+      if (char === '"') {
+        inDoubleQuote = false;
+      } else {
+        currentArg += char;
+      }
+    } else if (inSingleQuote) {
+      if (char === "'") {
+        inSingleQuote = false;
+      } else {
+        currentArg += char;
+      }
+    } else {
+      if (char === '"') {
+        inDoubleQuote = true;
+      } else if (char === "'") {
+        inSingleQuote = true;
+      } else if (char === ' ') {
+        if (currentArg.length > 0) {
+          args.push(currentArg);
+          currentArg = '';
+        }
+      } else {
+        currentArg += char;
+      }
+    }
+  }
+
+  if (currentArg.length > 0) {
+    args.push(currentArg);
+  }
+
+  return args;
+}

package/src/runner/foreach-executor.ts

@@ -0,0 +1,327 @@
+import { randomUUID } from 'node:crypto';
+import type { WorkflowDb } from '../db/workflow-db.ts';
+import { type ExpressionContext, ExpressionEvaluator } from '../expression/evaluator.ts';
+import type { Step } from '../parser/schema.ts';
+import { StepStatus, WorkflowStatus } from '../types/status.ts';
+import type { Logger } from '../utils/logger.ts';
+import { WorkflowSuspendedError } from './step-executor.ts';
+import type { ForeachStepContext, StepContext } from './workflow-runner.ts';
+
+export type ExecuteStepCallback = (
+  step: Step,
+  context: ExpressionContext,
+  stepExecId: string
+) => Promise<StepContext>;
+
+export class ForeachExecutor {
+  private static readonly MEMORY_WARNING_THRESHOLD = 1000;
+  private hasWarnedMemory = false;
+
+  constructor(
+    private db: WorkflowDb,
+    private logger: Logger,
+    private executeStepFn: ExecuteStepCallback
+  ) {}
+
+  /**
+   * Aggregate outputs from multiple iterations of a foreach step
+   */
+  public static aggregateOutputs(outputs: unknown[]): Record<string, unknown> {
+    const parentOutputs: Record<string, unknown> = {};
+
+    const validOutputs = outputs.filter((o) => o !== undefined);
+    if (validOutputs.length === 0) return parentOutputs;
+
+    // We can only aggregate objects, and we assume all outputs have similar shape
+    const firstOutput = validOutputs[0];
+    if (typeof firstOutput !== 'object' || firstOutput === null) {
+      return parentOutputs;
+    }
+
+    // Collect all keys from all outputs
+    const keys = new Set<string>();
+    for (const output of validOutputs) {
+      if (typeof output === 'object' && output !== null) {
+        for (const key of Object.keys(output)) {
+          keys.add(key);
+        }
+      }
+    }
+
+    // For each key, create an array of values
+    for (const key of keys) {
+      parentOutputs[key] = outputs.map((output) => {
+        if (typeof output === 'object' && output !== null) {
+          return (output as Record<string, unknown>)[key];
+        }
+        return undefined;
+      });
+    }
+
+    return parentOutputs;
+  }
+
+  /**
+   * Execute a step with foreach logic
+   */
+  async execute(
+    step: Step,
+    baseContext: ExpressionContext,
+    runId: string,
+    existingContext?: ForeachStepContext
+  ): Promise<ForeachStepContext> {
+    if (!step.foreach) {
+      throw new Error('Step is not a foreach step');
+    }
+
+    const items = ExpressionEvaluator.evaluate(step.foreach, baseContext);
+    if (!Array.isArray(items)) {
+      throw new Error(`foreach expression must evaluate to an array: ${step.foreach}`);
+    }
+
+    this.logger.log(`  ⤷ Executing step ${step.id} for ${items.length} items`);
+
+    if (items.length > ForeachExecutor.MEMORY_WARNING_THRESHOLD && !this.hasWarnedMemory) {
+      this.logger.warn(
+        `  ⚠️  Warning: Large foreach loop detected (${items.length} items). This may consume significant memory and lead to instability.`
+      );
+      this.hasWarnedMemory = true;
+    }
+
+    // Evaluate concurrency
+    let concurrencyLimit = items.length;
+    if (step.concurrency !== undefined) {
+      if (typeof step.concurrency === 'string') {
+        concurrencyLimit = Number(ExpressionEvaluator.evaluate(step.concurrency, baseContext));
+        if (!Number.isInteger(concurrencyLimit) || concurrencyLimit <= 0) {
+          throw new Error(
+            `concurrency must evaluate to a positive integer, got: ${concurrencyLimit}`
+          );
+        }
+      } else {
+        concurrencyLimit = step.concurrency;
+        if (!Number.isInteger(concurrencyLimit) || concurrencyLimit <= 0) {
+          throw new Error(`concurrency must be a positive integer, got: ${concurrencyLimit}`);
+        }
+      }
+    }
+
+    // Create parent step record in DB
+    const parentStepExecId = randomUUID();
+    await this.db.createStep(parentStepExecId, runId, step.id);
+    await this.db.startStep(parentStepExecId);
+
+    // Persist the foreach items
+    await this.db.completeStep(parentStepExecId, StepStatus.PENDING, { __foreachItems: items });
+
+    try {
+      // Initialize results array
+      const itemResults: StepContext[] = existingContext?.items || new Array(items.length);
+      const shouldCheckDb = !!existingContext;
+
+      // Ensure array is correct length
+      if (itemResults.length !== items.length) {
+        itemResults.length = items.length;
+      }
+
+      // Worker pool implementation
+      let currentIndex = 0;
+      let aborted = false;
+      const workers = new Array(Math.min(concurrencyLimit, items.length))
+        .fill(null)
+        .map(async () => {
+          const nextIndex = () => {
+            if (aborted) return null;
+            if (currentIndex >= items.length) return null;
+            const i = currentIndex;
+            currentIndex += 1;
+            return i;
+          };
+
+          while (true) {
+            const i = nextIndex();
+            if (i === null) break;
+
+            if (aborted) break;
+
+            const item = items[i];
+
+            // Skip if already successful or skipped
+            if (
+              itemResults[i] &&
+              (itemResults[i].status === StepStatus.SUCCESS ||
+                itemResults[i].status === StepStatus.SKIPPED)
+            ) {
+              continue;
+            }
+
+            // Build item-specific context
+            const itemContext = {
+              ...baseContext,
+              item,
+              index: i,
+            };
+
+            // Check DB again for robustness (resume flows only)
+            const existingExec = shouldCheckDb
+              ? await this.db.getStepByIteration(runId, step.id, i)
+              : undefined;
+            if (
+              existingExec &&
+              (existingExec.status === StepStatus.SUCCESS ||
+                existingExec.status === StepStatus.SKIPPED)
+            ) {
+              let output: unknown = null;
+              let itemStatus = existingExec.status as
+                | typeof StepStatus.SUCCESS
+                | typeof StepStatus.SKIPPED
+                | typeof StepStatus.FAILED;
+
+              try {
+                output = existingExec.output ? JSON.parse(existingExec.output) : null;
+              } catch (error) {
+                this.logger.warn(
+                  `Failed to parse output for step ${step.id} iteration ${i}: ${error}`
+                );
+                output = { error: 'Failed to parse output' };
+                itemStatus = StepStatus.FAILED;
+                aborted = true; // Fail fast if we find corrupted data
+                try {
+                  await this.db.completeStep(
+                    existingExec.id,
+                    StepStatus.FAILED,
+                    output,
+                    'Failed to parse output'
+                  );
+                } catch (dbError) {
+                  this.logger.warn(
+                    `Failed to update DB for corrupted output on step ${step.id} iteration ${i}: ${dbError}`
+                  );
+                }
+              }
+              itemResults[i] = {
+                output,
+                outputs:
+                  typeof output === 'object' && output !== null && !Array.isArray(output)
+                    ? (output as Record<string, unknown>)
+                    : {},
+                status: itemStatus,
+              } as StepContext;
+              continue;
+            }
+
+            if (aborted) break;
+
+            const stepExecId = randomUUID();
+            await this.db.createStep(stepExecId, runId, step.id, i);
+
+            // Execute and store result
+            try {
+              if (aborted) break;
+              this.logger.log(`  ⤷ [${i + 1}/${items.length}] Executing iteration...`);
+              itemResults[i] = await this.executeStepFn(step, itemContext, stepExecId);
+              if (
+                itemResults[i].status === StepStatus.FAILED ||
+                itemResults[i].status === StepStatus.SUSPENDED
+              ) {
+                aborted = true;
+              }
+            } catch (error) {
+              aborted = true;
+              throw error;
+            }
+          }
+        });
+
+      const workerResults = await Promise.allSettled(workers);
+
+      // Check if any worker rejected (this would be due to an unexpected throw)
+      const firstError = workerResults.find((r) => r.status === 'rejected') as
+        | PromiseRejectedResult
+        | undefined;
+      if (firstError) {
+        throw firstError.reason;
+      }
+
+      // Aggregate results
+      const outputs = itemResults.map((r) => r?.output);
+      const allSuccess = itemResults.every((r) => r?.status === StepStatus.SUCCESS);
+      const anyFailed = itemResults.some((r) => r?.status === StepStatus.FAILED);
+      const anySuspended = itemResults.some((r) => r?.status === StepStatus.SUSPENDED);
+
+      // Aggregate usage
+      const aggregatedUsage = itemResults.reduce(
+        (acc, r) => {
+          if (r?.usage) {
+            acc.prompt_tokens += r.usage.prompt_tokens;
+            acc.completion_tokens += r.usage.completion_tokens;
+            acc.total_tokens += r.usage.total_tokens;
+          }
+          return acc;
+        },
+        { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
+      );
+
+      // Map child properties
+      const mappedOutputs = ForeachExecutor.aggregateOutputs(outputs);
+
+      // Determine final status
+      let finalStatus: (typeof StepStatus)[keyof typeof StepStatus] = StepStatus.FAILED;
+      if (allSuccess) {
+        finalStatus = StepStatus.SUCCESS;
+      } else if (anyFailed) {
+        finalStatus = StepStatus.FAILED;
+      } else if (anySuspended) {
+        finalStatus = StepStatus.SUSPENDED;
+      }
+
+      const aggregatedContext: ForeachStepContext = {
+        output: outputs,
+        outputs: mappedOutputs,
+        status: finalStatus,
+        items: itemResults,
+        usage: aggregatedUsage,
+      };
+
+      const persistedContext = {
+        ...aggregatedContext,
+        __foreachItems: items,
+      };
+
+      // Update parent step record
+      await this.db.completeStep(
+        parentStepExecId,
+        finalStatus,
+        persistedContext,
+        finalStatus === StepStatus.FAILED ? 'One or more iterations failed' : undefined
+      );
+
+      if (finalStatus === StepStatus.SUSPENDED) {
+        const suspendedItem = itemResults.find((r) => r.status === StepStatus.SUSPENDED);
+        throw new WorkflowSuspendedError(
+          suspendedItem?.error || 'Iteration suspended',
+          step.id,
+          'text'
+        );
+      }
+
+      if (finalStatus === StepStatus.FAILED) {
+        throw new Error(`Step ${step.id} failed: one or more iterations failed`);
+      }
+
+      return aggregatedContext;
+    } catch (error) {
+      if (error instanceof WorkflowSuspendedError) {
+        throw error;
+      }
+      // Mark parent step as failed (if not already handled)
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      try {
+        await this.db.completeStep(parentStepExecId, StepStatus.FAILED, null, errorMsg);
+      } catch (dbError) {
+        this.logger.error(`Failed to update DB on foreach error: ${dbError}`);
+      }
+      throw error;
+    }
+  }
+}