reqon-dsl 0.2.0 → 0.4.0

package/dist/debug/cli-debugger.js

@@ -0,0 +1,185 @@
+/**
+ * CLI Debugger - Interactive readline-based debugger for terminal use
+ */
+import * as readline from 'node:readline';
+import { BaseDebugController } from './controller.js';
+export class CLIDebugger extends BaseDebugController {
+    rl;
+    closed = false;
+    constructor() {
+        super();
+        this.rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+    }
+    async pause(snapshot) {
+        if (this.closed) {
+            return { type: 'abort' };
+        }
+        this.printSnapshot(snapshot);
+        return this.promptCommand();
+    }
+    printSnapshot(s) {
+        console.log('');
+        console.log(`─── Debug: ${s.action} step ${s.stepIndex} (${s.stepType}) ───`);
+        // Print pause reason
+        if (s.pauseReason.type === 'loop-iteration') {
+            console.log(`  Loop: ${s.pauseReason.variable} [${s.pauseReason.index + 1}/${s.pauseReason.total}]`);
+        }
+        else if (s.pauseReason.type === 'match-arm') {
+            console.log(`  Matched: ${s.pauseReason.schema}`);
+        }
+        else if (s.pauseReason.type === 'breakpoint') {
+            console.log(`  Breakpoint: ${s.pauseReason.location}`);
+        }
+        // Print variables summary
+        const varKeys = Object.keys(s.variables);
+        if (varKeys.length > 0) {
+            const preview = varKeys
+                .slice(0, 3)
+                .map((k) => `${k}: ${this.formatValue(s.variables[k])}`)
+                .join(', ');
+            const more = varKeys.length > 3 ? ` (+${varKeys.length - 3} more)` : '';
+            console.log(`  Variables: { ${preview}${more} }`);
+        }
+        // Print stores summary
+        const storeEntries = Object.entries(s.stores);
+        if (storeEntries.length > 0) {
+            const storeInfo = storeEntries
+                .map(([name, info]) => {
+                const count = info.count >= 0 ? ` (${info.count} items)` : '';
+                return `${name}: ${info.type}${count}`;
+            })
+                .join(', ');
+            console.log(`  Stores: { ${storeInfo} }`);
+        }
+        // Print response summary
+        if (s.response !== undefined) {
+            console.log(`  Response: ${this.formatValue(s.response)}`);
+        }
+        console.log('');
+    }
+    formatValue(value) {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        if (Array.isArray(value))
+            return `[Array] (${value.length} items)`;
+        if (typeof value === 'object') {
+            const keys = Object.keys(value);
+            return `{Object} (${keys.length} keys)`;
+        }
+        if (typeof value === 'string') {
+            return value.length > 30 ? `"${value.slice(0, 30)}..."` : `"${value}"`;
+        }
+        return String(value);
+    }
+    promptCommand() {
+        return new Promise((resolve) => {
+            const ask = () => {
+                this.rl.question('debug> ', (input) => {
+                    const result = this.parseCommand(input.trim());
+                    if (result) {
+                        resolve(result);
+                    }
+                    else {
+                        ask(); // Invalid command, ask again
+                    }
+                });
+            };
+            ask();
+        });
+    }
+    parseCommand(input) {
+        const parts = input.split(/\s+/);
+        const cmd = parts[0]?.toLowerCase() ?? '';
+        switch (cmd) {
+            case 'c':
+            case 'continue':
+                return { type: 'continue' };
+            case 's':
+            case 'step':
+                return { type: 'step' };
+            case 'si':
+            case 'step-into':
+                return { type: 'step-into' };
+            case 'so':
+            case 'step-over':
+                return { type: 'step-over' };
+            case 'q':
+            case 'quit':
+            case 'abort':
+                return { type: 'abort' };
+            case 'vars':
+            case 'variables':
+                console.log('Use "vars" during pause to see variables in snapshot output above.');
+                return null;
+            case 'stores':
+                console.log('Use "stores" during pause to see stores in snapshot output above.');
+                return null;
+            case 'response':
+                console.log('Use "response" during pause to see response in snapshot output above.');
+                return null;
+            case 'bp':
+            case 'breakpoint':
+                if (parts[1]) {
+                    if (parts[1].startsWith('-')) {
+                        this.removeBreakpoint(parts[1].slice(1));
+                        console.log(`Removed breakpoint: ${parts[1].slice(1)}`);
+                    }
+                    else {
+                        this.addBreakpoint(parts[1]);
+                        console.log(`Added breakpoint: ${parts[1]}`);
+                    }
+                }
+                else {
+                    if (this.breakpoints.size === 0) {
+                        console.log('No breakpoints set.');
+                    }
+                    else {
+                        console.log('Breakpoints:');
+                        for (const bp of this.breakpoints) {
+                            console.log(`  - ${bp}`);
+                        }
+                    }
+                }
+                return null;
+            case 'help':
+            case 'h':
+            case '?':
+                this.printHelp();
+                return null;
+            case '':
+                // Empty input - repeat last command (default to step)
+                return { type: 'step' };
+            default:
+                console.log(`Unknown command: ${cmd}. Type "help" for available commands.`);
+                return null;
+        }
+    }
+    printHelp() {
+        console.log(`
+Debug Commands:
+  c, continue     Continue execution until next breakpoint
+  s, step         Execute next step and pause
+  si, step-into   Pause inside loops and match arms
+  so, step-over   Skip loop/match internals, pause at next step
+  q, quit, abort  Stop execution
+
+  bp <loc>        Add breakpoint (e.g., "bp FetchUsers:2" or "bp FetchUsers:*")
+  bp -<loc>       Remove breakpoint
+  bp              List all breakpoints
+
+  help, h, ?      Show this help message
+  <Enter>         Repeat last command (default: step)
+`);
+    }
+    close() {
+        if (!this.closed) {
+            this.closed = true;
+            this.rl.close();
+        }
+    }
+}

package/dist/debug/controller.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Debug Controller - Types and interface for step-through debugging
+ *
+ * Provides a programmatic API for debugging Reqon missions.
+ * Can be used by CLI debugger or external tools (VS Code, web UI).
+ */
+/** Execution mode for the debugger */
+export type DebugMode = 'run' | 'step' | 'step-into' | 'step-over';
+/** Reason why execution paused */
+export type DebugPauseReason = {
+    type: 'step';
+} | {
+    type: 'loop-iteration';
+    variable: string;
+    index: number;
+    total: number;
+} | {
+    type: 'match-arm';
+    schema: string;
+} | {
+    type: 'breakpoint';
+    location: string;
+};
+/** Snapshot of execution state at a pause point */
+export interface DebugSnapshot {
+    mission: string;
+    action: string;
+    stepIndex: number;
+    stepType: string;
+    pauseReason: DebugPauseReason;
+    variables: Record<string, unknown>;
+    stores: Record<string, {
+        type: string;
+        count: number;
+    }>;
+    response: unknown;
+}
+/** Command from debugger to control execution */
+export type DebugCommand = {
+    type: 'continue';
+} | {
+    type: 'step';
+} | {
+    type: 'step-into';
+} | {
+    type: 'step-over';
+} | {
+    type: 'abort';
+};
+/** Location in execution for pause/breakpoint checking */
+export interface DebugLocation {
+    action: string;
+    stepIndex: number;
+    stepType: string;
+    isLoopIteration?: boolean;
+    isMatchArm?: boolean;
+    loopInfo?: {
+        variable: string;
+        index: number;
+        total: number;
+    };
+    matchInfo?: {
+        schema: string;
+    };
+}
+/** Debug controller interface for step-through execution */
+export interface DebugController {
+    /** Current execution mode */
+    mode: DebugMode;
+    /** Active breakpoints (format: "ActionName:stepIndex" or "ActionName:*") */
+    breakpoints: Set<string>;
+    /** Check if we should pause at this location */
+    shouldPause(location: DebugLocation): boolean;
+    /** Pause execution and wait for user command */
+    pause(snapshot: DebugSnapshot): Promise<DebugCommand>;
+    /** Add a breakpoint */
+    addBreakpoint(location: string): void;
+    /** Remove a breakpoint */
+    removeBreakpoint(location: string): void;
+    /** Cleanup resources (e.g., close readline) */
+    close?(): void;
+}
+/**
+ * Base debug controller with common logic.
+ * Extend this class to create custom debuggers.
+ */
+export declare abstract class BaseDebugController implements DebugController {
+    mode: DebugMode;
+    breakpoints: Set<string>;
+    shouldPause(location: DebugLocation): boolean;
+    abstract pause(snapshot: DebugSnapshot): Promise<DebugCommand>;
+    addBreakpoint(location: string): void;
+    removeBreakpoint(location: string): void;
+}

package/dist/debug/controller.js

@@ -0,0 +1,45 @@
+/**
+ * Debug Controller - Types and interface for step-through debugging
+ *
+ * Provides a programmatic API for debugging Reqon missions.
+ * Can be used by CLI debugger or external tools (VS Code, web UI).
+ */
+/**
+ * Base debug controller with common logic.
+ * Extend this class to create custom debuggers.
+ */
+export class BaseDebugController {
+    mode = 'step';
+    breakpoints = new Set();
+    shouldPause(location) {
+        // Always pause at breakpoints
+        const exactMatch = `${location.action}:${location.stepIndex}`;
+        const wildcardMatch = `${location.action}:*`;
+        if (this.breakpoints.has(exactMatch) || this.breakpoints.has(wildcardMatch)) {
+            return true;
+        }
+        // In 'run' mode, only pause at breakpoints
+        if (this.mode === 'run') {
+            return false;
+        }
+        // In 'step' mode, pause at every step (but not loop iterations or match arms)
+        if (this.mode === 'step') {
+            return !location.isLoopIteration && !location.isMatchArm;
+        }
+        // In 'step-into' mode, pause at everything including loop iterations and match arms
+        if (this.mode === 'step-into') {
+            return true;
+        }
+        // In 'step-over' mode, pause at steps but skip loop iterations and match arms
+        if (this.mode === 'step-over') {
+            return !location.isLoopIteration && !location.isMatchArm;
+        }
+        return false;
+    }
+    addBreakpoint(location) {
+        this.breakpoints.add(location);
+    }
+    removeBreakpoint(location) {
+        this.breakpoints.delete(location);
+    }
+}

package/dist/debug/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Debug module exports
+ */
+export type { DebugMode, DebugPauseReason, DebugSnapshot, DebugCommand, DebugLocation, DebugController, } from './controller.js';
+export { BaseDebugController } from './controller.js';
+export { CLIDebugger } from './cli-debugger.js';

package/dist/debug/index.js

@@ -0,0 +1,5 @@
+/**
+ * Debug module exports
+ */
+export { BaseDebugController } from './controller.js';
+export { CLIDebugger } from './cli-debugger.js';

package/dist/errors/index.d.ts

@@ -1,3 +1,15 @@
+/**
+ * ---
+ * purpose: Structured error classes with source location tracking
+ * exports:
+ *   - ReqonError - base class with location and format()
+ *   - ParseError, LexerError, RuntimeError, ValidationError - specific types
+ *   - formatErrors, getSourceLine, getSourceContext - display helpers
+ * related:
+ *   - ../parser/parser.ts - throws ParseError
+ *   - ../interpreter/executor.ts - throws RuntimeError
+ * ---
+ */
 export interface SourceLocation {
     line: number;
     column: number;
@@ -63,6 +75,61 @@ export declare class ValidationError extends ReqonError {
         severity?: 'error' | 'warning';
     });
 }
+/**
+ * Error during step execution
+ */
+export declare class StepError extends Error {
+    readonly stepType: string;
+    readonly action?: string;
+    readonly cause?: Error;
+    constructor(message: string, stepType: string, options?: {
+        action?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Error during HTTP fetch operations
+ */
+export declare class FetchError extends Error {
+    readonly url?: string;
+    readonly method?: string;
+    readonly statusCode?: number;
+    readonly cause?: Error;
+    constructor(message: string, options?: {
+        url?: string;
+        method?: string;
+        statusCode?: number;
+        cause?: Error;
+    });
+}
+/**
+ * Error during store operations
+ */
+export declare class StoreError extends Error {
+    readonly storeName: string;
+    readonly operation: 'get' | 'set' | 'delete' | 'query' | 'init';
+    readonly cause?: Error;
+    constructor(message: string, storeName: string, operation: 'get' | 'set' | 'delete' | 'query' | 'init', cause?: Error);
+}
+/**
+ * Error during expression evaluation
+ */
+export declare class EvaluatorError extends Error {
+    readonly expression?: string;
+    readonly cause?: Error;
+    constructor(message: string, options?: {
+        expression?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Error for unsupported operations
+ */
+export declare class UnsupportedOperationError extends Error {
+    readonly operation: string;
+    readonly context?: string;
+    constructor(operation: string, context?: string);
+}
 /**
  * Format multiple errors for display
  */

package/dist/errors/index.js

@@ -1,3 +1,15 @@
+/**
+ * ---
+ * purpose: Structured error classes with source location tracking
+ * exports:
+ *   - ReqonError - base class with location and format()
+ *   - ParseError, LexerError, RuntimeError, ValidationError - specific types
+ *   - formatErrors, getSourceLine, getSourceContext - display helpers
+ * related:
+ *   - ../parser/parser.ts - throws ParseError
+ *   - ../interpreter/executor.ts - throws RuntimeError
+ * ---
+ */
 /**
  * Base class for Reqon errors with source location info
  */
@@ -128,11 +140,87 @@ export class ValidationError extends ReqonError {
         this.severity = options?.severity ?? 'error';
     }
 }
+// ============================================
+// Runtime Error Types (no source location required)
+// ============================================
+/**
+ * Error during step execution
+ */
+export class StepError extends Error {
+    stepType;
+    action;
+    cause;
+    constructor(message, stepType, options) {
+        super(message);
+        this.name = 'StepError';
+        this.stepType = stepType;
+        this.action = options?.action;
+        this.cause = options?.cause;
+    }
+}
+/**
+ * Error during HTTP fetch operations
+ */
+export class FetchError extends Error {
+    url;
+    method;
+    statusCode;
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.name = 'FetchError';
+        this.url = options?.url;
+        this.method = options?.method;
+        this.statusCode = options?.statusCode;
+        this.cause = options?.cause;
+    }
+}
+/**
+ * Error during store operations
+ */
+export class StoreError extends Error {
+    storeName;
+    operation;
+    cause;
+    constructor(message, storeName, operation, cause) {
+        super(message);
+        this.name = 'StoreError';
+        this.storeName = storeName;
+        this.operation = operation;
+        this.cause = cause;
+    }
+}
+/**
+ * Error during expression evaluation
+ */
+export class EvaluatorError extends Error {
+    expression;
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.name = 'EvaluatorError';
+        this.expression = options?.expression;
+        this.cause = options?.cause;
+    }
+}
+/**
+ * Error for unsupported operations
+ */
+export class UnsupportedOperationError extends Error {
+    operation;
+    context;
+    constructor(operation, context) {
+        super(`Unsupported operation: ${operation}${context ? ` (${context})` : ''}`);
+        this.name = 'UnsupportedOperationError';
+        this.operation = operation;
+        this.context = context;
+    }
+}
 /**
  * Format multiple errors for display
  */
 export function formatErrors(errors) {
-    return errors.map(e => e.format()).join('\n\n');
+    return errors.map((e) => e.format()).join('\n\n');
 }
 /**
  * Get the source line at a given line number

package/dist/execution/index.d.ts

@@ -1,4 +1,4 @@
-export type { ExecutionState, ExecutionStatus, StageState, StageStatus, Checkpoint, ExecutionStateError, CreateExecutionOptions, } from './state.js';
+export type { ExecutionState, ExecutionStatus, StageState, StageStatus, Checkpoint, ExecutionStateError, CreateExecutionOptions, LiveProgress, } 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/dist/execution/state.d.ts

@@ -98,6 +98,30 @@ export interface ExecutionStateError {
     timestamp: Date;
     attempt: number;
 }
+/**
+ * Live progress information for real-time status queries
+ */
+export interface LiveProgress {
+    /** Current stage index */
+    currentStage: number;
+    /** Current action name */
+    currentAction: string;
+    /** Current step type (if executing a step) */
+    currentStep?: string;
+    /** Loop progress (for for-in steps) */
+    loopProgress?: {
+        current: number;
+        total: number;
+        variable: string;
+    };
+    /** Pagination progress (for paginated fetches) */
+    paginationProgress?: {
+        pagesProcessed: number;
+        itemsFetched: number;
+    };
+    /** Timestamp of last heartbeat */
+    lastHeartbeat: Date;
+}
 /**
  * Options for creating a new execution
  */

package/dist/execution/store.js

@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { safeJoin } from '../utils/path.js';
 import { ensureDirectory, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, restoreDatesInArray, } from '../utils/file.js';
 /**
  * File-based execution state store
@@ -12,7 +12,7 @@ export class FileExecutionStore {
         this.initialized = ensureDirectory(this.baseDir);
     }
     getFilePath(id) {
-        return join(this.baseDir, `${id}.json`);
+        return safeJoin(this.baseDir, `${id}.json`);
     }
     deserialize(parsed) {
         // Restore Date objects