keystone-cli 0.8.0 → 1.0.0

package/src/runner/debug-repl.ts

@@ -47,6 +47,21 @@ export class DebugRepl {
     rl.prompt();
 
     return new Promise((resolve) => {
+      let resolved = false;
+      const resolveOnce = (action: DebugAction) => {
+        if (resolved) return;
+        resolved = true;
+        resolve(action);
+      };
+
+      rl.on('close', () => {
+        resolveOnce({ type: 'continue_failure' });
+      });
+
+      rl.on('SIGINT', () => {
+        rl.close();
+      });
+
       rl.on('line', (line) => {
         const trimmed = line.trim();
         const [cmd, ...args] = trimmed.split(' ');
@@ -59,19 +74,19 @@ export class DebugRepl {
             break;
 
           case 'retry':
+            resolveOnce({ type: 'retry', modifiedStep: this.step });
             rl.close();
-            resolve({ type: 'retry', modifiedStep: this.step });
             break;
 
           case 'skip':
+            resolveOnce({ type: 'skip' });
             rl.close();
-            resolve({ type: 'skip' });
             break;
 
           case 'exit':
           case 'quit':
+            resolveOnce({ type: 'continue_failure' });
             rl.close();
-            resolve({ type: 'continue_failure' });
             break;
 
           case 'edit': {

package/src/runner/durable-timers.test.ts

@@ -0,0 +1,200 @@
+import { afterAll, beforeAll, describe, expect, it, mock } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { WorkflowDb } from '../db/workflow-db';
+import type { Workflow } from '../parser/schema';
+import { StepStatus, WorkflowStatus } from '../types/status';
+import { WorkflowSuspendedError, WorkflowWaitingError } from './step-executor';
+import { WorkflowRunner } from './workflow-runner';
+
+describe('Durable Timers Integration', () => {
+  const dbPath = 'test-timers.db';
+  let db: WorkflowDb;
+
+  beforeAll(() => {
+    db = new WorkflowDb(dbPath);
+  });
+
+  afterAll(() => {
+    db.close();
+    try {
+      const { rmSync } = require('node:fs');
+      rmSync(dbPath);
+    } catch {}
+  });
+
+  const sleepWorkflow: Workflow = {
+    name: 'sleep-test',
+    steps: [
+      {
+        id: 'wait',
+        type: 'sleep',
+        duration: 120000, // 2 minutes
+        durable: true,
+        needs: [],
+      },
+    ],
+  };
+
+  const humanWorkflow: Workflow = {
+    name: 'human-test',
+    steps: [
+      {
+        id: 'approve',
+        type: 'human',
+        message: 'Approve?',
+        needs: [],
+      },
+    ],
+  };
+
+  it('should suspend a durable sleep step and create a timer', async () => {
+    const runner = new WorkflowRunner(sleepWorkflow, { dbPath });
+    const runId = runner.runId;
+
+    try {
+      await runner.run();
+    } catch (error) {
+      if (!(error instanceof WorkflowWaitingError)) {
+        throw error;
+      }
+      expect(error.stepId).toBe('wait');
+    }
+
+    const run = await db.getRun(runId);
+    expect(run?.status).toBe(WorkflowStatus.PAUSED);
+
+    const steps = await db.getStepsByRun(runId);
+    expect(steps[0].status).toBe(StepStatus.WAITING);
+
+    const timer = await db.getTimerByStep(runId, 'wait');
+    expect(timer).toBeDefined();
+    expect(timer?.timer_type).toBe('sleep');
+    expect(timer?.wake_at).not.toBeNull();
+
+    if (!timer?.wake_at) {
+      throw new Error('Expected timer wake_at to be set');
+    }
+    const wakeAt = new Date(timer.wake_at);
+    expect(wakeAt.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  it('should persist human waits without scheduling', async () => {
+    const originalIsTTY = process.stdin.isTTY;
+    process.stdin.isTTY = false; // Ensure human step suspends instead of waiting for input
+
+    const runner = new WorkflowRunner(humanWorkflow, { dbPath });
+    const runId = runner.runId;
+
+    try {
+      await runner.run();
+    } catch (error) {
+      if (!(error instanceof WorkflowSuspendedError)) {
+        throw error;
+      }
+      expect(error.stepId).toBe('approve');
+    } finally {
+      process.stdin.isTTY = originalIsTTY;
+    }
+
+    const run = await db.getRun(runId);
+    expect(run?.status).toBe(WorkflowStatus.PAUSED);
+
+    const steps = await db.getStepsByRun(runId);
+    expect(steps[0].status).toBe(StepStatus.SUSPENDED);
+
+    const timer = await db.getTimerByStep(runId, 'approve');
+    expect(timer).toBeDefined();
+    expect(timer?.timer_type).toBe('human');
+    expect(timer?.wake_at).toBeNull();
+
+    const pending = await db.getPendingTimers();
+    expect(pending.find((t) => t.step_id === 'approve')).toBeUndefined();
+  });
+
+  it('should resume a waiting run if the timer has NOT elapsed', async () => {
+    const runner = new WorkflowRunner(sleepWorkflow, { dbPath });
+    const runId = runner.runId;
+
+    // Start it once to get it waiting
+    try {
+      await runner.run();
+    } catch {}
+
+    // Now try to resume with a new runner instance
+    const resumeRunner = new WorkflowRunner(sleepWorkflow, {
+      dbPath,
+      resumeRunId: runId,
+    });
+
+    try {
+      await resumeRunner.run();
+    } catch (error) {
+      if (!(error instanceof WorkflowWaitingError)) {
+        throw error;
+      }
+      expect(error.stepId).toBe('wait');
+    }
+
+    const steps = await db.getStepsByRun(runId);
+    expect(steps[0].status).toBe(StepStatus.WAITING);
+  });
+
+  it('should NOT create duplicate timers on resume', async () => {
+    const runner = new WorkflowRunner(sleepWorkflow, { dbPath });
+    const runId = runner.runId;
+    try {
+      await runner.run();
+    } catch {}
+
+    const timersBefore = await db.listTimers(runId);
+    expect(timersBefore).toHaveLength(1);
+
+    const resumeRunner = new WorkflowRunner(sleepWorkflow, { dbPath, resumeRunId: runId });
+    try {
+      await resumeRunner.run();
+    } catch {}
+
+    const timersAfter = await db.listTimers(runId);
+    // After fix, it should NOT create a new timer if one is already pending
+    expect(timersAfter).toHaveLength(1);
+  });
+
+  it('should resume and COMPLETE a waiting run if the timer has elapsed', async () => {
+    const runner = new WorkflowRunner(sleepWorkflow, { dbPath });
+    const runId = runner.runId;
+
+    try {
+      await runner.run();
+    } catch {}
+
+    const timer = await db.getTimerByStep(runId, 'wait');
+    expect(timer).toBeDefined();
+    if (!timer) {
+      throw new Error('Expected timer to be created');
+    }
+
+    // Manually backdate the timer in the DB to simulate elapsed time
+    const pastDate = new Date(Date.now() - 1000).toISOString();
+    const { Database } = require('bun:sqlite');
+    const sqlite = new Database(dbPath);
+    sqlite.prepare('UPDATE durable_timers SET wake_at = ? WHERE id = ?').run(pastDate, timer.id);
+    sqlite.close();
+
+    const resumeRunner = new WorkflowRunner(sleepWorkflow, {
+      dbPath,
+      resumeRunId: runId,
+    });
+
+    const outputs = await resumeRunner.run();
+    expect(outputs).toBeDefined();
+
+    const run = await db.getRun(runId);
+    expect(run?.status).toBe(WorkflowStatus.SUCCESS);
+
+    const steps = await db.getStepsByRun(runId);
+    expect(steps[0].status).toBe(StepStatus.SUCCESS);
+
+    const finalTimer = await db.getTimer(timer.id);
+    expect(finalTimer?.completed_at).not.toBeNull();
+  });
+});

package/src/runner/engine-executor.test.ts

@@ -0,0 +1,464 @@
+import { afterEach, describe, expect, it, mock, spyOn } from 'bun:test';
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { EngineStep } from '../parser/schema';
+import { executeEngineStep } from './engine-executor';
+
+// Helper to create a minimal valid EngineStep for testing
+const createStep = (overrides: Partial<EngineStep>): EngineStep =>
+  ({
+    id: 'test',
+    type: 'engine',
+    command: 'echo',
+    args: [],
+    cwd: '/tmp',
+    env: { PATH: '/usr/bin' },
+    needs: [],
+    ...overrides,
+  }) as EngineStep;
+
+describe('engine-executor', () => {
+  const tempDir = join(tmpdir(), `engine-test-${Date.now()}`);
+
+  afterEach(() => {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('executeEngineStep', () => {
+    it('should reject if aborted before execution', async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const step = createStep({
+        cwd: '.',
+        env: { PATH: '/usr/bin' },
+      });
+
+      await expect(
+        executeEngineStep(
+          step,
+          { inputs: {}, secrets: {}, env: {}, steps: {} },
+          {
+            abortSignal: controller.signal,
+          }
+        )
+      ).rejects.toThrow('Step canceled');
+    });
+
+    it('should reject if cwd is not provided', async () => {
+      const step = createStep({
+        cwd: '',
+        env: { PATH: '/usr/bin' },
+      });
+
+      await expect(
+        executeEngineStep(step, { inputs: {}, secrets: {}, env: {}, steps: {} })
+      ).rejects.toThrow('requires an explicit cwd');
+    });
+
+    it('should reject if env is not provided', async () => {
+      const step = createStep({
+        cwd: '/tmp',
+        env: undefined as unknown as Record<string, string>,
+      });
+
+      await expect(
+        executeEngineStep(step, { inputs: {}, secrets: {}, env: {}, steps: {} })
+      ).rejects.toThrow('requires an explicit env');
+    });
+
+    it('should reject if PATH is not in env for non-absolute command', async () => {
+      const step = createStep({
+        cwd: '/tmp',
+        env: { HOME: '/home' },
+      });
+
+      await expect(
+        executeEngineStep(step, { inputs: {}, secrets: {}, env: {}, steps: {} })
+      ).rejects.toThrow('requires env.PATH');
+    });
+
+    it('should reject if command is denied', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: ['rm', 'dd'],
+          allowlist: {},
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        const step = createStep({
+          command: 'rm',
+          args: ['-rf', '/'],
+          cwd: '/tmp',
+          env: { PATH: '/usr/bin' },
+        });
+
+        await expect(
+          executeEngineStep(step, { inputs: {}, secrets: {}, env: {}, steps: {} })
+        ).rejects.toThrow('denied by engines.denylist');
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should reject if command is not in allowlist', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            python: { command: 'python3', version: '3.11', versionArgs: [], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        const step = createStep({
+          command: 'node',
+          cwd: '/tmp',
+          env: { PATH: '/usr/bin' },
+        });
+
+        await expect(
+          executeEngineStep(step, { inputs: {}, secrets: {}, env: {}, steps: {} })
+        ).rejects.toThrow('not in the allowlist');
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should match allowlist by basename', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            echo: { command: 'echo', version: '', versionArgs: [], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        mkdirSync(tempDir, { recursive: true });
+        const step = createStep({
+          command: '/bin/echo',
+          args: ['hello'],
+          cwd: tempDir,
+          env: { PATH: '/bin:/usr/bin' },
+        });
+
+        const result = await executeEngineStep(
+          step,
+          { inputs: {}, secrets: {}, env: {}, steps: {} },
+          { artifactRoot: tempDir }
+        );
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain('hello');
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should reject on version mismatch', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            echo: { command: 'echo', version: '999.0.0', versionArgs: [], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        mkdirSync(tempDir, { recursive: true });
+        const step = createStep({
+          command: '/bin/echo',
+          args: ['hello'],
+          cwd: tempDir,
+          env: { PATH: '/bin:/usr/bin' },
+        });
+
+        await expect(
+          executeEngineStep(
+            step,
+            { inputs: {}, secrets: {}, env: {}, steps: {} },
+            { artifactRoot: tempDir }
+          )
+        ).rejects.toThrow('version mismatch');
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should parse JSON summary from stdout', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            echo: { command: 'echo', version: '', versionArgs: [], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        mkdirSync(tempDir, { recursive: true });
+        const step = createStep({
+          command: '/bin/echo',
+          args: ['{"result": "success"}'],
+          cwd: tempDir,
+          env: { PATH: '/bin:/usr/bin' },
+        });
+
+        const result = await executeEngineStep(
+          step,
+          { inputs: {}, secrets: {}, env: {}, steps: {} },
+          { artifactRoot: tempDir }
+        );
+
+        expect(result.summary).toEqual({ result: 'success' });
+        expect(result.summarySource).toBe('stdout');
+        expect(result.summaryFormat).toBe('json');
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should parse YAML summary from stdout', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            sh: { command: 'sh', version: '', versionArgs: [], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        mkdirSync(tempDir, { recursive: true });
+        const step = createStep({
+          command: '/bin/sh',
+          args: ['-c', 'echo "result: success"; echo "count: 42"'],
+          cwd: tempDir,
+          env: { PATH: '/bin:/usr/bin' },
+        });
+
+        const result = await executeEngineStep(
+          step,
+          { inputs: {}, secrets: {}, env: {}, steps: {} },
+          { artifactRoot: tempDir }
+        );
+
+        expect(result.summary).toEqual({ result: 'success', count: 42 });
+        expect(result.summaryFormat).toBe('yaml');
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should handle summary file over stdout', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            sh: { command: 'sh', version: '', versionArgs: [], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        mkdirSync(tempDir, { recursive: true });
+        const step = createStep({
+          command: '/bin/sh',
+          args: [
+            '-c',
+            'echo \'{"from": "file"}\' > $KEYSTONE_ENGINE_SUMMARY_PATH && echo \'{"from": "stdout"}\'',
+          ],
+          cwd: tempDir,
+          env: { PATH: '/bin:/usr/bin' },
+        });
+
+        const result = await executeEngineStep(
+          step,
+          { inputs: {}, secrets: {}, env: {}, steps: {} },
+          { artifactRoot: tempDir }
+        );
+
+        expect(result.summary).toEqual({ from: 'file' });
+        expect(result.summarySource).toBe('file');
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should handle invalid summary gracefully', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            echo: { command: 'echo', version: '', versionArgs: [], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        mkdirSync(tempDir, { recursive: true });
+        const step = createStep({
+          command: '/bin/echo',
+          args: ['not valid json or yaml :: %%'],
+          cwd: tempDir,
+          env: { PATH: '/bin:/usr/bin' },
+        });
+
+        const result = await executeEngineStep(
+          step,
+          { inputs: {}, secrets: {}, env: {}, steps: {} },
+          { artifactRoot: tempDir }
+        );
+
+        expect(result.summary).toBeNull();
+        expect(result.summaryError).toBeDefined();
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should apply redactForStorage to summary', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            echo: { command: 'echo', version: '', versionArgs: [], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        mkdirSync(tempDir, { recursive: true });
+        const step = createStep({
+          command: '/bin/echo',
+          args: ['{"secret": "password123"}'],
+          cwd: tempDir,
+          env: { PATH: '/bin:/usr/bin' },
+        });
+
+        const redactForStorage = mock((value: unknown) => {
+          if (typeof value === 'object' && value !== null) {
+            return { ...(value as object), secret: '[REDACTED]' };
+          }
+          return value;
+        });
+
+        await executeEngineStep(
+          step,
+          { inputs: {}, secrets: {}, env: {}, steps: {} },
+          { artifactRoot: tempDir, redactForStorage }
+        );
+
+        expect(redactForStorage).toHaveBeenCalled();
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should evaluate expressions in command args', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            echo: { command: 'echo', version: '', versionArgs: [], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        mkdirSync(tempDir, { recursive: true });
+        const step = createStep({
+          command: '/bin/echo',
+          args: ['${{ inputs.message }}'],
+          cwd: tempDir,
+          env: { PATH: '/bin:/usr/bin' },
+        });
+
+        const result = await executeEngineStep(
+          step,
+          { inputs: { message: 'Hello, World!' }, secrets: {}, env: {}, steps: {} },
+          { artifactRoot: tempDir }
+        );
+
+        expect(result.stdout).toContain('Hello, World!');
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should use custom versionArgs from allowlist', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: [],
+          allowlist: {
+            echo: { command: 'echo', version: 'test', versionArgs: ['test'], args: [] },
+          },
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        mkdirSync(tempDir, { recursive: true });
+        const step = createStep({
+          command: '/bin/echo',
+          args: ['hello'],
+          cwd: tempDir,
+          env: { PATH: '/bin:/usr/bin' },
+        });
+
+        const result = await executeEngineStep(
+          step,
+          { inputs: {}, secrets: {}, env: {}, steps: {} },
+          { artifactRoot: tempDir }
+        );
+
+        expect(result.exitCode).toBe(0);
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+
+    it('should handle wildcard patterns in denylist', async () => {
+      const ConfigLoader = await import('../utils/config-loader');
+      const loadSpy = spyOn(ConfigLoader.ConfigLoader, 'load').mockReturnValue({
+        engines: {
+          denylist: ['rm*', '*/rm'],
+          allowlist: {},
+        },
+      } as ReturnType<typeof ConfigLoader.ConfigLoader.load>);
+
+      try {
+        const step = createStep({
+          command: 'rmdir',
+          cwd: '/tmp',
+          env: { PATH: '/usr/bin' },
+        });
+
+        await expect(
+          executeEngineStep(step, { inputs: {}, secrets: {}, env: {}, steps: {} })
+        ).rejects.toThrow('denied by engines.denylist');
+      } finally {
+        loadSpy.mockRestore();
+      }
+    });
+  });
+});