reqon-dsl 0.2.0

package/src/execution/execution.test.ts

@@ -0,0 +1,307 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { rmSync, existsSync } from 'node:fs';
+import {
+  createExecutionState,
+  findResumePoint,
+  canResume,
+  getProgress,
+  getExecutionSummary,
+  type ExecutionState,
+} from './state.js';
+import { FileExecutionStore, MemoryExecutionStore } from './store.js';
+
+const TEST_DIR = '.reqon-test-executions';
+
+describe('ExecutionState', () => {
+  describe('createExecutionState', () => {
+    it('creates initial state with pending stages', () => {
+      const state = createExecutionState({
+        mission: 'TestMission',
+        stages: ['FetchData', 'ProcessData', 'StoreResults'],
+      });
+
+      expect(state.mission).toBe('TestMission');
+      expect(state.status).toBe('pending');
+      expect(state.stages).toHaveLength(3);
+      expect(state.stages[0].action).toBe('FetchData');
+      expect(state.stages[0].status).toBe('pending');
+      expect(state.id).toMatch(/^exec_/);
+    });
+
+    it('includes metadata', () => {
+      const state = createExecutionState({
+        mission: 'Test',
+        stages: ['A'],
+        metadata: { tenant: 'acme', userId: '123' },
+      });
+
+      expect(state.metadata).toEqual({ tenant: 'acme', userId: '123' });
+    });
+  });
+
+  describe('findResumePoint', () => {
+    it('returns 0 for fresh execution', () => {
+      const state = createExecutionState({
+        mission: 'Test',
+        stages: ['A', 'B', 'C'],
+      });
+
+      expect(findResumePoint(state)).toBe(0);
+    });
+
+    it('returns index of first non-completed stage', () => {
+      const state = createExecutionState({
+        mission: 'Test',
+        stages: ['A', 'B', 'C'],
+      });
+      state.stages[0].status = 'completed';
+      state.stages[1].status = 'failed';
+
+      expect(findResumePoint(state)).toBe(1);
+    });
+
+    it('returns -1 when all stages complete', () => {
+      const state = createExecutionState({
+        mission: 'Test',
+        stages: ['A', 'B'],
+      });
+      state.stages[0].status = 'completed';
+      state.stages[1].status = 'completed';
+
+      expect(findResumePoint(state)).toBe(-1);
+    });
+
+    it('skips over skipped stages', () => {
+      const state = createExecutionState({
+        mission: 'Test',
+        stages: ['A', 'B', 'C'],
+      });
+      state.stages[0].status = 'completed';
+      state.stages[1].status = 'skipped';
+
+      expect(findResumePoint(state)).toBe(2);
+    });
+  });
+
+  describe('canResume', () => {
+    it('returns true for failed executions', () => {
+      const state = createExecutionState({ mission: 'Test', stages: ['A'] });
+      state.status = 'failed';
+      expect(canResume(state)).toBe(true);
+    });
+
+    it('returns true for paused executions', () => {
+      const state = createExecutionState({ mission: 'Test', stages: ['A'] });
+      state.status = 'paused';
+      expect(canResume(state)).toBe(true);
+    });
+
+    it('returns false for completed executions', () => {
+      const state = createExecutionState({ mission: 'Test', stages: ['A'] });
+      state.status = 'completed';
+      expect(canResume(state)).toBe(false);
+    });
+
+    it('returns false for running executions', () => {
+      const state = createExecutionState({ mission: 'Test', stages: ['A'] });
+      state.status = 'running';
+      expect(canResume(state)).toBe(false);
+    });
+  });
+
+  describe('getProgress', () => {
+    it('returns 0 for no completed stages', () => {
+      const state = createExecutionState({
+        mission: 'Test',
+        stages: ['A', 'B', 'C', 'D'],
+      });
+      expect(getProgress(state)).toBe(0);
+    });
+
+    it('returns 50 for half completed', () => {
+      const state = createExecutionState({
+        mission: 'Test',
+        stages: ['A', 'B', 'C', 'D'],
+      });
+      state.stages[0].status = 'completed';
+      state.stages[1].status = 'completed';
+      expect(getProgress(state)).toBe(50);
+    });
+
+    it('returns 100 for all completed', () => {
+      const state = createExecutionState({
+        mission: 'Test',
+        stages: ['A', 'B'],
+      });
+      state.stages[0].status = 'completed';
+      state.stages[1].status = 'completed';
+      expect(getProgress(state)).toBe(100);
+    });
+
+    it('counts skipped as progress', () => {
+      const state = createExecutionState({
+        mission: 'Test',
+        stages: ['A', 'B'],
+      });
+      state.stages[0].status = 'completed';
+      state.stages[1].status = 'skipped';
+      expect(getProgress(state)).toBe(100);
+    });
+  });
+
+  describe('getExecutionSummary', () => {
+    it('generates readable summary', () => {
+      const state = createExecutionState({
+        mission: 'SyncInvoices',
+        stages: ['Fetch', 'Process', 'Store'],
+      });
+      state.stages[0].status = 'completed';
+      state.stages[1].status = 'failed';
+      state.status = 'failed';
+
+      const summary = getExecutionSummary(state);
+      expect(summary).toContain('SyncInvoices');
+      expect(summary).toContain('failed');
+      expect(summary).toContain('1 completed');
+      expect(summary).toContain('1 failed');
+      expect(summary).toContain('1 pending');
+    });
+  });
+});
+
+describe('MemoryExecutionStore', () => {
+  let store: MemoryExecutionStore;
+
+  beforeEach(() => {
+    store = new MemoryExecutionStore();
+  });
+
+  it('saves and loads execution state', async () => {
+    const state = createExecutionState({
+      mission: 'Test',
+      stages: ['A', 'B'],
+    });
+
+    await store.save(state);
+    const loaded = await store.load(state.id);
+
+    expect(loaded).not.toBeNull();
+    expect(loaded!.id).toBe(state.id);
+    expect(loaded!.mission).toBe('Test');
+  });
+
+  it('returns null for unknown ID', async () => {
+    const loaded = await store.load('nonexistent');
+    expect(loaded).toBeNull();
+  });
+
+  it('lists by mission', async () => {
+    const state1 = createExecutionState({ mission: 'A', stages: ['X'] });
+    const state2 = createExecutionState({ mission: 'B', stages: ['X'] });
+    const state3 = createExecutionState({ mission: 'A', stages: ['X'] });
+
+    await store.save(state1);
+    await store.save(state2);
+    await store.save(state3);
+
+    const aExecutions = await store.listByMission('A');
+    expect(aExecutions).toHaveLength(2);
+  });
+
+  it('finds resumable executions', async () => {
+    const completed = createExecutionState({ mission: 'Test', stages: ['A'] });
+    completed.status = 'completed';
+
+    const failed = createExecutionState({ mission: 'Test', stages: ['A'] });
+    failed.status = 'failed';
+
+    const paused = createExecutionState({ mission: 'Test', stages: ['A'] });
+    paused.status = 'paused';
+
+    await store.save(completed);
+    await store.save(failed);
+    await store.save(paused);
+
+    const resumable = await store.findResumable('Test');
+    expect(resumable).toHaveLength(2);
+  });
+
+  it('deletes execution state', async () => {
+    const state = createExecutionState({ mission: 'Test', stages: ['A'] });
+    await store.save(state);
+    await store.delete(state.id);
+
+    const loaded = await store.load(state.id);
+    expect(loaded).toBeNull();
+  });
+});
+
+describe('FileExecutionStore', () => {
+  let store: FileExecutionStore;
+
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+    store = new FileExecutionStore(TEST_DIR);
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  it('creates directory if not exists', async () => {
+    // Trigger initialization by calling any async method
+    await store.listRecent();
+    expect(existsSync(TEST_DIR)).toBe(true);
+  });
+
+  it('persists state to disk', async () => {
+    const state = createExecutionState({
+      mission: 'Persistent',
+      stages: ['A', 'B'],
+    });
+    state.stages[0].status = 'completed';
+
+    await store.save(state);
+
+    // Create new store instance
+    const newStore = new FileExecutionStore(TEST_DIR);
+    const loaded = await newStore.load(state.id);
+
+    expect(loaded).not.toBeNull();
+    expect(loaded!.stages[0].status).toBe('completed');
+  });
+
+  it('preserves Date objects', async () => {
+    const state = createExecutionState({
+      mission: 'Test',
+      stages: ['A'],
+    });
+    state.stages[0].startedAt = new Date();
+    state.stages[0].completedAt = new Date();
+
+    await store.save(state);
+    const loaded = await store.load(state.id);
+
+    expect(loaded!.startedAt).toBeInstanceOf(Date);
+    expect(loaded!.stages[0].startedAt).toBeInstanceOf(Date);
+    expect(loaded!.stages[0].completedAt).toBeInstanceOf(Date);
+  });
+
+  it('finds latest execution for mission', async () => {
+    const older = createExecutionState({ mission: 'Test', stages: ['A'] });
+    older.startedAt = new Date(Date.now() - 10000);
+
+    const newer = createExecutionState({ mission: 'Test', stages: ['A'] });
+    newer.startedAt = new Date();
+
+    await store.save(older);
+    await store.save(newer);
+
+    const latest = await store.findLatest('Test');
+    expect(latest!.id).toBe(newer.id);
+  });
+});

package/src/execution/index.ts

@@ -0,0 +1,21 @@
+export type {
+  ExecutionState,
+  ExecutionStatus,
+  StageState,
+  StageStatus,
+  Checkpoint,
+  ExecutionStateError,
+  CreateExecutionOptions,
+} from './state.js';
+
+export {
+  generateExecutionId,
+  createExecutionState,
+  findResumePoint,
+  canResume,
+  getProgress,
+  getExecutionSummary,
+} from './state.js';
+
+export type { ExecutionStore } from './store.js';
+export { FileExecutionStore, MemoryExecutionStore } from './store.js';

package/src/execution/state.ts

@@ -0,0 +1,207 @@
+/**
+ * Execution State - Durable state for resumable missions
+ *
+ * Tracks progress through pipeline stages, enabling:
+ * - Resume from last successful step after failures
+ * - Idempotent re-execution
+ * - Progress visibility
+ */
+
+export type ExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'paused';
+
+export type StageStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+
+/**
+ * State for a single pipeline stage (action execution)
+ */
+export interface StageState {
+  /** Action name */
+  action: string;
+  /** Current status */
+  status: StageStatus;
+  /** When this stage started */
+  startedAt?: Date;
+  /** When this stage completed/failed */
+  completedAt?: Date;
+  /** Error message if failed */
+  error?: string;
+  /** Number of items processed (for actions with loops) */
+  itemsProcessed?: number;
+  /** Total items to process */
+  itemsTotal?: number;
+  /** Retry attempt number (0 = first attempt) */
+  attempt: number;
+}
+
+/**
+ * Checkpoint within an action (for resuming mid-action)
+ */
+export interface Checkpoint {
+  /** Stage index in pipeline */
+  stageIndex: number;
+  /** Step index within action */
+  stepIndex: number;
+  /** For loops: current item index */
+  itemIndex?: number;
+  /** Saved context variables */
+  variables?: Record<string, unknown>;
+  /** Timestamp */
+  createdAt: Date;
+  /** Webhook wait state (for resuming webhook waits) */
+  webhookWait?: WebhookWaitState;
+}
+
+/**
+ * State for waiting on webhook callbacks
+ */
+export interface WebhookWaitState {
+  /** Webhook registration ID */
+  registrationId: string;
+  /** Path for the webhook endpoint */
+  path: string;
+  /** Full webhook URL */
+  webhookUrl: string;
+  /** Number of expected events */
+  expectedEvents: number;
+  /** Number of events received so far */
+  receivedEvents: number;
+  /** When the wait started */
+  waitStartedAt: Date;
+  /** When the wait expires */
+  expiresAt: Date;
+}
+
+/**
+ * Complete execution state for a mission run
+ */
+export interface ExecutionState {
+  /** Unique execution ID */
+  id: string;
+  /** Mission name */
+  mission: string;
+  /** Overall status */
+  status: ExecutionStatus;
+  /** When execution started */
+  startedAt: Date;
+  /** When execution completed/failed */
+  completedAt?: Date;
+  /** Total duration in ms */
+  duration?: number;
+  /** State of each pipeline stage */
+  stages: StageState[];
+  /** Latest checkpoint for resume */
+  checkpoint?: Checkpoint;
+  /** Execution errors */
+  errors: ExecutionStateError[];
+  /** Metadata (user-provided context) */
+  metadata?: Record<string, unknown>;
+}
+
+export interface ExecutionStateError {
+  stageIndex: number;
+  action: string;
+  step: string;
+  message: string;
+  timestamp: Date;
+  attempt: number;
+}
+
+/**
+ * Options for creating a new execution
+ */
+export interface CreateExecutionOptions {
+  /** Mission name */
+  mission: string;
+  /** Pipeline stage names (actions) */
+  stages: string[];
+  /** Optional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Generate a unique execution ID
+ */
+export function generateExecutionId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 8);
+  return `exec_${timestamp}_${random}`;
+}
+
+/**
+ * Create initial execution state
+ */
+export function createExecutionState(options: CreateExecutionOptions): ExecutionState {
+  return {
+    id: generateExecutionId(),
+    mission: options.mission,
+    status: 'pending',
+    startedAt: new Date(),
+    stages: options.stages.map((action) => ({
+      action,
+      status: 'pending',
+      attempt: 0,
+    })),
+    errors: [],
+    metadata: options.metadata,
+  };
+}
+
+/**
+ * Find the stage to resume from
+ * Returns the index of the first non-completed stage, or -1 if all complete
+ */
+export function findResumePoint(state: ExecutionState): number {
+  // If there's a checkpoint, use it
+  if (state.checkpoint) {
+    return state.checkpoint.stageIndex;
+  }
+
+  // Otherwise, find first non-completed stage
+  for (let i = 0; i < state.stages.length; i++) {
+    const stage = state.stages[i];
+    if (stage.status !== 'completed' && stage.status !== 'skipped') {
+      return i;
+    }
+  }
+
+  return -1; // All stages complete
+}
+
+/**
+ * Check if execution can be resumed
+ */
+export function canResume(state: ExecutionState): boolean {
+  return state.status === 'failed' || state.status === 'paused';
+}
+
+/**
+ * Calculate execution progress as percentage
+ */
+export function getProgress(state: ExecutionState): number {
+  if (state.stages.length === 0) return 100;
+
+  const completed = state.stages.filter(
+    (s) => s.status === 'completed' || s.status === 'skipped'
+  ).length;
+
+  return Math.round((completed / state.stages.length) * 100);
+}
+
+/**
+ * Get a summary of the execution state
+ */
+export function getExecutionSummary(state: ExecutionState): string {
+  const progress = getProgress(state);
+  const completed = state.stages.filter((s) => s.status === 'completed').length;
+  const failed = state.stages.filter((s) => s.status === 'failed').length;
+  const pending = state.stages.filter((s) => s.status === 'pending').length;
+
+  let summary = `${state.mission} [${state.id}]: ${state.status} (${progress}%)`;
+  summary += ` - ${completed} completed, ${failed} failed, ${pending} pending`;
+
+  if (state.duration) {
+    summary += ` - ${Math.round(state.duration / 1000)}s`;
+  }
+
+  return summary;
+}