@flexiberry/berrycore 0.1.0

package/dist/interpreter/interpreter.js

@@ -0,0 +1,682 @@
+/**
+ * Berry Interpreter
+ *
+ * Walks the ProgramNode AST and executes the Berry program.
+ * Uses the Visitor pattern — one visit* method per AST node type.
+ *
+ * Architecture rules:
+ *   - Interpreter only walks AST — no parsing, no tokenizing
+ *   - Maintains environment for variable scoping
+ *   - Emits typed events for status reporting
+ *   - Uses IOAdapter for user input (CLI or UI)
+ */
+import { NodeType, } from "../parser/ast/ast.types.js";
+import { InterpreterEvent, ExecutionCommand, ExecutionState, ExecutionStatus, } from "./interpreter.types.js";
+import { Environment } from "./environment.js";
+import { RuntimeError, ApiNotFoundError } from "./errors.js";
+const DEFAULT_OPTIONS = {
+    apiTimeout: 30000,
+    continueOnError: true,
+    dryRun: false,
+};
+// ─── Interpreter ────────────────────────────────────────────────────────────
+export class Interpreter {
+    ast;
+    options;
+    globalEnv = new Environment();
+    apiRegistry = new Map();
+    listeners = new Map();
+    ioAdapter = null;
+    // ── Execution Control State ──────────────────────────────────────────────
+    state = ExecutionState.Idle;
+    pendingCommand = ExecutionCommand.Continue;
+    pauseResolver = null;
+    /** Check if killed — bypasses TS narrowing since state changes async */
+    isKilled() { return this.state === ExecutionState.Killed; }
+    constructor(ast, options = {}) {
+        this.ast = ast;
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    // ── Public API ──────────────────────────────────────────────────────────
+    /** Register an event listener */
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, []);
+        }
+        this.listeners.get(event).push(listener);
+        return this;
+    }
+    /** Set the IO adapter for user input, output, and execution control */
+    setIOAdapter(adapter) {
+        this.ioAdapter = adapter;
+        // Wire up command handler so adapter can send commands to interpreter
+        if (adapter.onCommand) {
+            adapter.onCommand((command) => {
+                this.sendCommand(command);
+            });
+        }
+        return this;
+    }
+    /**
+     * Send an execution command to the interpreter.
+     * Can be called externally (from adapter, UI, or programmatically).
+     */
+    sendCommand(command) {
+        this.pendingCommand = command;
+        switch (command) {
+            case ExecutionCommand.Pause:
+                if (this.state === ExecutionState.Running) {
+                    this.state = ExecutionState.Paused;
+                    this.pushLog("info", "⏸  Execution paused");
+                    this.emitStateChanged(ExecutionState.Paused, "User requested pause");
+                }
+                break;
+            case ExecutionCommand.Continue:
+                if (this.state === ExecutionState.Paused) {
+                    this.state = ExecutionState.Running;
+                    this.pushLog("info", "▶️  Execution resumed");
+                    this.emitStateChanged(ExecutionState.Running, "User requested continue");
+                    // Resolve the pause promise to unblock execution
+                    if (this.pauseResolver) {
+                        this.pauseResolver();
+                        this.pauseResolver = null;
+                    }
+                }
+                break;
+            case ExecutionCommand.Kill:
+                this.state = ExecutionState.Killed;
+                this.pushLog("error", "💀 Execution killed");
+                this.emitStateChanged(ExecutionState.Killed, "User requested kill");
+                // Unblock pause if paused
+                if (this.pauseResolver) {
+                    this.pauseResolver();
+                    this.pauseResolver = null;
+                }
+                this.cleanup();
+                break;
+            case ExecutionCommand.Skip:
+                this.pushLog("info", "⏭  Skipping current step");
+                // If paused, resume so the skip can take effect
+                if (this.state === ExecutionState.Paused) {
+                    this.state = ExecutionState.Running;
+                    if (this.pauseResolver) {
+                        this.pauseResolver();
+                        this.pauseResolver = null;
+                    }
+                }
+                break;
+            case ExecutionCommand.Stop:
+                this.pushLog("info", "⏹  Stopping current task");
+                // If paused, resume so the stop can take effect
+                if (this.state === ExecutionState.Paused) {
+                    this.state = ExecutionState.Running;
+                    if (this.pauseResolver) {
+                        this.pauseResolver();
+                        this.pauseResolver = null;
+                    }
+                }
+                break;
+        }
+    }
+    /** Get the current execution state */
+    getState() {
+        return this.state;
+    }
+    /** Kill execution and clean up all resources */
+    kill() {
+        this.sendCommand(ExecutionCommand.Kill);
+    }
+    /** Execute the entire program */
+    async execute() {
+        this.state = ExecutionState.Running;
+        this.pendingCommand = ExecutionCommand.Continue;
+        // Phase 1: Register all declarations (Vars, APIs) — no execution
+        const tasks = [];
+        for (const node of this.ast.body) {
+            switch (node.type) {
+                case NodeType.VarDeclaration:
+                    await this.visitVarDeclaration(node);
+                    break;
+                case NodeType.ApiBlock:
+                    this.visitApiBlock(node);
+                    break;
+                case NodeType.TaskBlock:
+                    tasks.push(node);
+                    break;
+                case NodeType.Comment:
+                    // skip comments
+                    break;
+                default:
+                    break;
+            }
+        }
+        const plan = tasks.map(t => ({
+            title: t.title ?? null,
+            steps: t.steps.map(s => ({ targetName: s.targetName }))
+        }));
+        // Emit start event
+        await this.emit(InterpreterEvent.Start, {
+            totalTasks: tasks.length,
+            totalApis: this.apiRegistry.size,
+            totalVars: this.globalEnv.getOwnEntries().size,
+            startTime: new Date(),
+            plan,
+        });
+        this.pushLog("info", `Starting execution: ${tasks.length} tasks, ${this.apiRegistry.size} APIs, ${this.globalEnv.getOwnEntries().size} vars`);
+        // Phase 2: Execute tasks sequentially
+        const taskResults = [];
+        for (let i = 0; i < tasks.length; i++) {
+            // Check for kill before each task
+            if (this.isKilled()) {
+                this.pushLog("warn", `Skipping remaining tasks (killed)`);
+                break;
+            }
+            // Wait if paused
+            await this.waitIfPaused();
+            if (this.isKilled())
+                break;
+            const result = await this.visitTask(tasks[i], i);
+            taskResults.push(result);
+        }
+        // Emit completed event
+        if (!this.isKilled()) {
+            this.state = ExecutionState.Completed;
+        }
+        await this.emit(InterpreterEvent.Completed, {
+            endTime: new Date(),
+            taskResults,
+        });
+        this.pushLog("info", `Execution ${this.isKilled() ? "killed" : "completed"}`);
+        return taskResults;
+    }
+    // ── Var Declaration Visitor ─────────────────────────────────────────────
+    async visitVarDeclaration(node) {
+        // Store each key-value entry as a global variable
+        for (const entry of node.entries) {
+            let value = entry.value;
+            // Handle Input mapping
+            if (value.startsWith("Input.")) {
+                const fieldName = value.substring(6);
+                if (this.options.inputRow && fieldName in this.options.inputRow) {
+                    value = this.options.inputRow[fieldName];
+                }
+            }
+            // Handle Decryption
+            if (entry.isEncrypted) {
+                const provider = this.options.decryptionProvider ?? this.defaultDecryptionProvider.bind(this);
+                value = await provider(value);
+            }
+            this.globalEnv.declare(entry.key, value);
+        }
+        // If the var has a pointer, store the pointer reference
+        if (node.pointer) {
+            this.globalEnv.declare(`@${node.pointer.target}`, node.title ?? null);
+        }
+        this.emitSync(InterpreterEvent.Log, {
+            level: "debug",
+            message: `Var declared: ${node.title ?? "(unnamed)"} with ${node.entries.length} entries`,
+        });
+    }
+    // ── API Block Visitor ───────────────────────────────────────────────────
+    visitApiBlock(node) {
+        const definition = {
+            method: node.method ?? "GET",
+            name: node.name,
+            title: node.title ?? null,
+            url: node.url?.value ?? null,
+            headers: node.headers?.entries ?? [],
+            bodyType: node.body?.bodyType ?? null,
+            bodyContent: node.body?.content ?? null,
+        };
+        this.apiRegistry.set(node.name, definition);
+        this.emitSync(InterpreterEvent.Log, {
+            level: "debug",
+            message: `API registered: ${definition.method} #${definition.name}`,
+        });
+    }
+    // ── Task Visitor ────────────────────────────────────────────────────────
+    async visitTask(node, taskIndex) {
+        const startTime = new Date();
+        await this.emit(InterpreterEvent.TaskBegin, {
+            title: node.title,
+            index: taskIndex,
+        });
+        this.pushLog("task", `Task ${taskIndex + 1}: "${node.title ?? "(unnamed)"}"`);
+        const stepResults = [];
+        const taskEnv = this.globalEnv.createChild();
+        let overallStatus = ExecutionStatus.Pass;
+        for (let i = 0; i < node.steps.length; i++) {
+            // Check kill
+            if (this.isKilled()) {
+                overallStatus = ExecutionStatus.Killed;
+                break;
+            }
+            // Wait if paused
+            await this.waitIfPaused();
+            if (this.isKilled()) {
+                overallStatus = ExecutionStatus.Killed;
+                break;
+            }
+            // Check stop (stop current task, skip remaining steps)
+            if (this.pendingCommand === ExecutionCommand.Stop) {
+                this.pushLog("info", `Stopping task — skipping step ${i + 1} and remaining`);
+                overallStatus = ExecutionStatus.Stopped;
+                this.pendingCommand = ExecutionCommand.Continue; // reset for next task
+                break;
+            }
+            // Check skip (skip this step, continue to next)
+            if (this.pendingCommand === ExecutionCommand.Skip) {
+                this.pushLog("info", `Skipping step ${i + 1}: ${node.steps[i].targetName}`);
+                stepResults.push({
+                    targetName: node.steps[i].targetName,
+                    status: ExecutionStatus.Skipped,
+                    startTime: new Date(),
+                    endTime: new Date(),
+                    error: null,
+                    response: null,
+                    checksPassed: null,
+                });
+                this.pendingCommand = ExecutionCommand.Continue; // reset after skip
+                continue;
+            }
+            const stepResult = await this.visitStep(node.steps[i], i, taskIndex, taskEnv);
+            stepResults.push(stepResult);
+            if (stepResult.status === ExecutionStatus.Failed) {
+                overallStatus = ExecutionStatus.Failed;
+                if (!this.options.continueOnError) {
+                    break;
+                }
+            }
+        }
+        const result = {
+            title: node.title,
+            status: overallStatus,
+            startTime,
+            endTime: new Date(),
+            steps: stepResults,
+        };
+        await this.emit(InterpreterEvent.TaskDone, result);
+        const taskIcon = overallStatus === ExecutionStatus.Pass ? "✅" : "❌";
+        this.pushLog("task", `${taskIcon} Task "${node.title ?? "(unnamed)"}" → ${overallStatus}`);
+        return result;
+    }
+    // ── Step Visitor ────────────────────────────────────────────────────────
+    async visitStep(node, stepIndex, taskIndex, taskEnv) {
+        const startTime = new Date();
+        await this.emit(InterpreterEvent.StepBegin, {
+            targetName: node.targetName,
+            index: stepIndex,
+            taskIndex,
+        });
+        this.pushLog("step", `Step ${stepIndex + 1}: Call ${node.targetType} ${node.targetName}`);
+        const stepEnv = taskEnv.createChild();
+        let status = ExecutionStatus.Pass;
+        let error = null;
+        let apiResponse = null;
+        let checksPassed = null;
+        try {
+            // Look up the API definition
+            const apiDef = this.apiRegistry.get(node.targetName);
+            if (!apiDef) {
+                throw new ApiNotFoundError(node.targetName, node.position.line, node.position.column);
+            }
+            // Resolve params into step environment
+            if (node.params) {
+                this.resolveParams(node.params.entries, stepEnv, taskEnv);
+            }
+            // Make the API call
+            const response = await this.callApi(apiDef, stepEnv, taskEnv);
+            apiResponse = {
+                status: response.status,
+                headers: response.headers,
+                body: response.data,
+            };
+            // Store response metadata in step environment
+            stepEnv.declare("$.status", response.status);
+            stepEnv.declare("$.body", response.data ?? null);
+            // Process capture
+            if (node.capture) {
+                this.processCapture(node.capture.entries, response, stepIndex, taskEnv);
+            }
+            // Process check
+            if (node.check) {
+                checksPassed = this.processCheck(node.check.conditions, stepEnv, taskEnv);
+                if (!checksPassed) {
+                    status = ExecutionStatus.Failed;
+                    error = "Check validation failed";
+                }
+            }
+        }
+        catch (err) {
+            status = ExecutionStatus.Failed;
+            if (err instanceof RuntimeError) {
+                error = err.message;
+            }
+            else {
+                error = err instanceof Error ? err.message : String(err);
+            }
+            await this.emit(InterpreterEvent.Error, {
+                message: error ?? "Unknown error",
+                line: node.position.line,
+                column: node.position.column,
+            });
+            this.pushLog("error", error ?? "Unknown error");
+        }
+        const result = {
+            targetName: node.targetName,
+            status,
+            startTime,
+            endTime: new Date(),
+            error,
+            response: apiResponse,
+            checksPassed,
+        };
+        await this.emit(InterpreterEvent.StepDone, { ...result, taskIndex, index: stepIndex });
+        const stepIcon = status === ExecutionStatus.Pass ? "✅" : "❌";
+        this.pushLog("step", `${stepIcon} ${node.targetName} → ${status}`);
+        return result;
+    }
+    // ── API Call ────────────────────────────────────────────────────────────
+    async callApi(apiDef, stepEnv, taskEnv) {
+        const allVars = taskEnv.getAllEntries();
+        // Merge step env on top
+        for (const [k, v] of stepEnv.getOwnEntries()) {
+            allVars.set(k, v);
+        }
+        // Resolve URL with interpolation
+        const url = this.interpolate(apiDef.url ?? "", allVars);
+        // Resolve headers
+        const headers = {};
+        for (const entry of apiDef.headers) {
+            headers[entry.key] = this.interpolate(entry.value, allVars);
+        }
+        // Resolve body
+        let data;
+        if (apiDef.bodyContent) {
+            data = this.interpolate(apiDef.bodyContent, allVars);
+        }
+        await this.emit(InterpreterEvent.ApiCallBegin, {
+            method: apiDef.method,
+            url,
+            apiName: apiDef.name,
+        });
+        this.pushLog("api", `${apiDef.method} ${url}`);
+        if (this.options.dryRun) {
+            await this.emit(InterpreterEvent.Log, {
+                level: "info",
+                message: `[DRY RUN] ${apiDef.method} ${url}`,
+            });
+            // Return a mock response for dry run
+            return {
+                status: 200,
+                data: { dryRun: true },
+                headers: {},
+            };
+        }
+        const callStart = Date.now();
+        // Create abort controller for the request timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.options.apiTimeout);
+        try {
+            const response = await fetch(url, {
+                method: apiDef.method.toUpperCase(),
+                headers,
+                body: data,
+                signal: controller.signal,
+            });
+            const responseHeaders = {};
+            response.headers.forEach((val, key) => {
+                responseHeaders[key] = val;
+            });
+            let responseData = null;
+            const text = await response.text();
+            const contentType = response.headers.get("content-type") || "";
+            if (contentType.includes("application/json")) {
+                try {
+                    responseData = JSON.parse(text);
+                }
+                catch {
+                    responseData = text;
+                }
+            }
+            else {
+                responseData = text;
+            }
+            const duration = Date.now() - callStart;
+            await this.emit(InterpreterEvent.ApiCallDone, {
+                apiName: apiDef.name,
+                status: response.status,
+                duration,
+            });
+            this.pushLog("api", `${apiDef.name} → ${response.status} (${duration}ms)`);
+            return {
+                status: response.status,
+                data: responseData,
+                headers: responseHeaders,
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    // ── Params Resolution ───────────────────────────────────────────────────
+    resolveParams(entries, stepEnv, taskEnv) {
+        for (const entry of entries) {
+            // Check if the value references another variable (e.g., "Step.1.id")
+            const resolved = taskEnv.tryLookup(entry.value);
+            stepEnv.declare(entry.key, resolved !== undefined ? resolved : entry.value);
+        }
+    }
+    // ── Capture Processing ──────────────────────────────────────────────────
+    processCapture(entries, response, stepIndex, taskEnv) {
+        for (const entry of entries) {
+            const value = this.resolveResponsePath(response.data, entry.value);
+            // Store as Step.<1-based index>.<key>
+            taskEnv.declare(`Step.${stepIndex + 1}.${entry.key}`, value);
+        }
+    }
+    // ── Check Processing ────────────────────────────────────────────────────
+    processCheck(conditions, stepEnv, taskEnv) {
+        for (const condition of conditions) {
+            const result = this.evaluateCondition(condition, stepEnv, taskEnv);
+            if (!result)
+                return false;
+        }
+        return true;
+    }
+    evaluateCondition(condition, stepEnv, taskEnv) {
+        const lhs = this.resolveValue(condition.lhs, stepEnv, taskEnv);
+        const rhs = this.resolveValue(condition.rhs, stepEnv, taskEnv);
+        let result = this.compareValues(lhs, condition.operator, rhs);
+        // Process OR chains — any one passing makes the condition pass
+        if (!result && condition.orConditions.length > 0) {
+            for (const orExpr of condition.orConditions) {
+                const orLhs = this.resolveValue(orExpr.lhs, stepEnv, taskEnv);
+                const orRhs = this.resolveValue(orExpr.rhs, stepEnv, taskEnv);
+                if (this.compareValues(orLhs, orExpr.operator, orRhs)) {
+                    result = true;
+                    break;
+                }
+            }
+        }
+        return result;
+    }
+    compareValues(lhs, operator, rhs) {
+        // Coerce to numbers if both are numeric
+        const numLhs = Number(lhs);
+        const numRhs = Number(rhs);
+        const useNumbers = !isNaN(numLhs) && !isNaN(numRhs);
+        switch (operator) {
+            case "==":
+                return useNumbers ? numLhs === numRhs : String(lhs) === String(rhs);
+            case "!=":
+                return useNumbers ? numLhs !== numRhs : String(lhs) !== String(rhs);
+            case ">":
+                return useNumbers ? numLhs > numRhs : String(lhs) > String(rhs);
+            case "<":
+                return useNumbers ? numLhs < numRhs : String(lhs) < String(rhs);
+            case ">=":
+                return useNumbers ? numLhs >= numRhs : String(lhs) >= String(rhs);
+            case "<=":
+                return useNumbers ? numLhs <= numRhs : String(lhs) <= String(rhs);
+            default:
+                return false;
+        }
+    }
+    // ── Value Resolution ────────────────────────────────────────────────────
+    resolveValue(raw, stepEnv, taskEnv) {
+        // Special keyword: null
+        if (raw === "null")
+            return null;
+        // Special keyword: true/false
+        if (raw === "true")
+            return true;
+        if (raw === "false")
+            return false;
+        // Try step env first (for $.status, $.body)
+        const stepVal = stepEnv.tryLookup(raw);
+        if (stepVal !== undefined)
+            return stepVal;
+        // Try task env (for Step.1.id etc.)
+        const taskVal = taskEnv.tryLookup(raw);
+        if (taskVal !== undefined)
+            return taskVal;
+        // Try global env
+        const globalVal = this.globalEnv.tryLookup(raw);
+        if (globalVal !== undefined)
+            return globalVal;
+        // If numeric, return as number
+        const num = Number(raw);
+        if (!isNaN(num))
+            return num;
+        // Return as raw string
+        return raw;
+    }
+    /**
+     * Resolve a dot-separated path from response data.
+     * e.g., "response.id" → data.id
+     */
+    resolveResponsePath(data, path) {
+        // Strip "response." prefix if present
+        const cleanPath = path.startsWith("response.")
+            ? path.substring("response.".length)
+            : path;
+        const parts = cleanPath.split(".");
+        let current = data;
+        for (const part of parts) {
+            if (current === null || current === undefined)
+                return null;
+            if (typeof current === "object") {
+                current = current[part];
+            }
+            else {
+                return null;
+            }
+        }
+        return current ?? null;
+    }
+    // ── Interpolation ──────────────────────────────────────────────────────
+    /**
+     * Replace {{varName}} placeholders with values from the variable map.
+     */
+    interpolate(template, vars) {
+        return template.replace(/\{\{(\w+(?:\.\w+)*)\}\}/g, (_match, varName) => {
+            const value = vars.get(varName);
+            if (value !== undefined && value !== null) {
+                return String(value);
+            }
+            // Try dot-path lookup
+            const parts = varName.split(".");
+            if (parts.length > 1) {
+                const rootVal = vars.get(parts[0]);
+                if (rootVal !== undefined && rootVal !== null) {
+                    return String(this.resolveResponsePath(rootVal, parts.slice(1).join(".")));
+                }
+            }
+            return `{{${varName}}}`; // leave unresolved
+        });
+    }
+    // ── Event Emission ─────────────────────────────────────────────────────
+    async emit(event, payload) {
+        const eventListeners = this.listeners.get(event);
+        if (!eventListeners)
+            return;
+        for (const listener of eventListeners) {
+            await listener(payload);
+        }
+    }
+    emitSync(event, payload) {
+        const eventListeners = this.listeners.get(event);
+        if (!eventListeners)
+            return;
+        for (const listener of eventListeners) {
+            listener(payload);
+        }
+    }
+    // ── Decryption Provider ──────────────────────────────────────────────────
+    defaultDecryptionProvider(encrypted) {
+        const isNode = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+        if (isNode) {
+            return Buffer.from(encrypted, "base64").toString("utf-8");
+        }
+        return atob(encrypted);
+    }
+    // ── Adapter Logging ─────────────────────────────────────────────────────
+    /** Push a log line through the IO adapter (if set and supports logging) */
+    pushLog(level, message) {
+        if (this.ioAdapter?.log) {
+            this.ioAdapter.log(level, message);
+        }
+    }
+    // ── Execution Control ───────────────────────────────────────────────────
+    /** Block execution while state is Paused */
+    waitIfPaused() {
+        if (this.state !== ExecutionState.Paused) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.pauseResolver = resolve;
+        });
+    }
+    /** Emit a state change event */
+    emitStateChanged(newState, reason) {
+        this.emit(InterpreterEvent.StateChanged, { state: newState, reason });
+    }
+    /**
+     * Clean up all resources.
+     * Called on kill — clears environment, registry, listeners, adapter.
+     */
+    cleanup() {
+        this.pushLog("info", "🧹 Cleaning up resources...");
+        // Clear environment
+        for (const [key] of this.globalEnv.getOwnEntries()) {
+            this.globalEnv.assign(key, null);
+        }
+        // Clear API registry
+        this.apiRegistry.clear();
+        // Clear event listeners
+        this.listeners.clear();
+        // Dispose adapter
+        if (this.ioAdapter?.dispose) {
+            this.ioAdapter.dispose();
+        }
+        this.pushLog("info", "✅ Cleanup complete");
+    }
+    // ── Public Accessors ───────────────────────────────────────────────────
+    /** Get the global environment (for inspection/testing) */
+    getEnvironment() {
+        return this.globalEnv;
+    }
+    /** Get the API registry (for inspection/testing) */
+    getApiRegistry() {
+        return this.apiRegistry;
+    }
+    /** Prompt the user for input via the IOAdapter */
+    async promptUser(message) {
+        if (!this.ioAdapter) {
+            throw new RuntimeError("No IO adapter set — cannot prompt user");
+        }
+        await this.emit(InterpreterEvent.InputRequired, { prompt: message });
+        return this.ioAdapter.prompt(message);
+    }
+}