@flexiberry/berrycore 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flexiberry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapter/cli-adapter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CLI Adapter
+ *
+ * Default IOAdapter implementation using Node readline + stdout.
+ * Handles input, output, and execution control for CLI execution.
+ */
+import { IOAdapter, LogLevel, ExecutionCommand } from "../interpreter/interpreter.types.js";
+export declare class CliAdapter implements IOAdapter {
+    private rl;
+    private commandHandler;
+    private readonly enableLogging;
+    private readonly logLevels;
+    private readonly enableCommands;
+    constructor(options?: {
+        /** Enable log output to stdout (default: true) */
+        enableLogging?: boolean;
+        /** Which log levels to show (default: all except debug) */
+        logLevels?: LogLevel[];
+        /** Enable keyboard commands during execution (default: false) */
+        enableCommands?: boolean;
+    });
+    private getReadline;
+    /** Prompt the user for input via stdin */
+    prompt(message: string): Promise<string>;
+    /** Ask a yes/no question */
+    confirm(message: string): Promise<boolean>;
+    /** Push a log line to stdout */
+    log(level: LogLevel, message: string): void;
+    /**
+     * Register a command handler.
+     * Called by the interpreter to wire up command sending.
+     */
+    onCommand(handler: (command: ExecutionCommand) => void): void;
+    /** Clean up readline interface */
+    dispose(): void;
+    private handleKeyboardInput;
+}

package/dist/adapter/cli-adapter.js

@@ -0,0 +1,119 @@
+/**
+ * CLI Adapter
+ *
+ * Default IOAdapter implementation using Node readline + stdout.
+ * Handles input, output, and execution control for CLI execution.
+ */
+import * as readline from "readline";
+import { ExecutionCommand } from "../interpreter/interpreter.types.js";
+// ─── Log Level Icons ────────────────────────────────────────────────────────
+const LEVEL_ICONS = {
+    info: "ℹ️ ",
+    warn: "⚠️ ",
+    error: "❌",
+    debug: "🔍",
+    step: "▶ ",
+    task: "📋",
+    api: "🌐",
+};
+// ─── CLI Adapter ────────────────────────────────────────────────────────────
+export class CliAdapter {
+    rl = null;
+    commandHandler = null;
+    enableLogging;
+    logLevels;
+    enableCommands;
+    constructor(options = {}) {
+        this.enableLogging = options.enableLogging ?? true;
+        this.logLevels = new Set(options.logLevels ?? ["info", "warn", "error", "step", "task", "api"]);
+        this.enableCommands = options.enableCommands ?? false;
+    }
+    getReadline() {
+        if (!this.rl) {
+            this.rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            // Listen for keyboard commands during execution
+            if (this.enableCommands) {
+                this.rl.on("line", (input) => {
+                    this.handleKeyboardInput(input.trim().toLowerCase());
+                });
+            }
+        }
+        return this.rl;
+    }
+    /** Prompt the user for input via stdin */
+    prompt(message) {
+        return new Promise((resolve) => {
+            this.getReadline().question(`🔹 ${message}: `, (answer) => {
+                resolve(answer.trim());
+            });
+        });
+    }
+    /** Ask a yes/no question */
+    async confirm(message) {
+        const answer = await this.prompt(`${message} (y/n)`);
+        return answer.toLowerCase() === "y" || answer.toLowerCase() === "yes";
+    }
+    /** Push a log line to stdout */
+    log(level, message) {
+        if (!this.enableLogging)
+            return;
+        if (!this.logLevels.has(level))
+            return;
+        const icon = LEVEL_ICONS[level];
+        console.log(`${icon} ${message}`);
+    }
+    /**
+     * Register a command handler.
+     * Called by the interpreter to wire up command sending.
+     */
+    onCommand(handler) {
+        this.commandHandler = handler;
+        // Initialize readline so keyboard listening starts
+        if (this.enableCommands) {
+            this.getReadline();
+            console.log("─── Commands: [p]ause  [c]ontinue  [s]kip  [t]stop  [k]ill ───");
+        }
+    }
+    /** Clean up readline interface */
+    dispose() {
+        if (this.rl) {
+            this.rl.close();
+            this.rl = null;
+        }
+        this.commandHandler = null;
+    }
+    // ── Keyboard Input Handling ─────────────────────────────────────────────
+    handleKeyboardInput(input) {
+        if (!this.commandHandler)
+            return;
+        switch (input) {
+            case "p":
+            case "pause":
+                this.commandHandler(ExecutionCommand.Pause);
+                break;
+            case "c":
+            case "continue":
+            case "resume":
+                this.commandHandler(ExecutionCommand.Continue);
+                break;
+            case "s":
+            case "skip":
+                this.commandHandler(ExecutionCommand.Skip);
+                break;
+            case "t":
+            case "stop":
+                this.commandHandler(ExecutionCommand.Stop);
+                break;
+            case "k":
+            case "kill":
+                this.commandHandler(ExecutionCommand.Kill);
+                break;
+            default:
+                // Ignore unknown input
+                break;
+        }
+    }
+}

package/dist/berry-core.d.ts

@@ -0,0 +1,108 @@
+/**
+ * BerryCore — Runtime Facade
+ *
+ * The single entry-point for running a .berry script programmatically.
+ *
+ * Responsibilities:
+ *   1. Tokenise the source code  (LexerEngine)
+ *   2. Build the AST            (AstEngine)
+ *   3. Execute the program      (Interpreter)
+ *   4. Relay every interpreter event to registered outside listeners
+ *
+ * Usage (CLI consumer):
+ *   const core = new BerryCore(source, { adapter: new CliAdapter() });
+ *   core.on(InterpreterEvent.Completed, payload => { ... });
+ *   await core.run();
+ *
+ * Usage (bare / no adapter):
+ *   const core = new BerryCore(source);
+ *   core.on(InterpreterEvent.Log, ({ message }) => console.log(message));
+ *   await core.run();
+ */
+import { InterpreterOptions } from "./interpreter/interpreter.js";
+import { InterpreterEvent, EventListener, ExecutionCommand, ExecutionState, IOAdapter, TaskResult } from "./interpreter/interpreter.types.js";
+export interface BerryCoreOptions {
+    /**
+     * IO adapter used for user-input prompts, log output, and keyboard commands.
+     * Pass a `CliAdapter` for terminal use, or a custom adapter for a UI/WS layer.
+     * When omitted, the interpreter runs silently (events are still emitted).
+     */
+    readonly adapter?: IOAdapter;
+    /**
+     * Fine-grained interpreter execution options forwarded as-is to the
+     * `Interpreter` constructor (timeout, continueOnError, dryRun, …).
+     */
+    readonly interpreterOptions?: Partial<InterpreterOptions>;
+    /**
+     * Optional base path used by the default link resolver to resolve relative local file paths.
+     * Typically the directory of the entry .berry file.
+     */
+    readonly basePath?: string;
+    /**
+     * Optional resolver for `Link` statements.
+     * Receives the path/url and should return the string content of that file.
+     * Required if the source code contains `Link` statements.
+     */
+    readonly linkResolver?: (path: string) => Promise<string>;
+    /**
+     * Optional decryption provider for `Decrypt` flagged `Var` entries.
+     * If omitted, base64 decryption is used by default.
+     */
+    readonly decryptionProvider?: (encrypted: string) => Promise<string> | string;
+}
+export declare class BerryCore {
+    private readonly source;
+    private readonly options;
+    /**
+     * The interpreter instance is created fresh on every `run()` call so that
+     * BerryCore remains reusable across multiple sequential runs.
+     */
+    private interpreter;
+    /**
+     * Listeners registered via `.on()` before `run()` is called.
+     * They are forwarded to the interpreter after it is created.
+     */
+    private readonly pendingListeners;
+    constructor(source: string, options?: BerryCoreOptions);
+    /**
+     * Register a listener for an interpreter lifecycle event.
+     *
+     * Listeners can be registered before or after calling `run()`.
+     * Listeners registered before `run()` are forwarded to the newly
+     * created Interpreter instance automatically.
+     */
+    on<E extends InterpreterEvent>(event: E, listener: EventListener<E>): this;
+    /**
+     * Send an execution command to the running interpreter.
+     * Has no effect if `run()` has not been called yet.
+     */
+    sendCommand(command: ExecutionCommand): void;
+    /**
+     * Immediately kill the running execution and clean up resources.
+     */
+    kill(): void;
+    /**
+     * Returns the current execution state, or `Idle` if not yet started.
+     */
+    getState(): ExecutionState;
+    private resolveLinks;
+    private defaultLinkResolver;
+    private parseData;
+    /**
+     * Execute the source code end-to-end.
+     *
+     * Pipeline:
+     *   source → LexerEngine.tokenize() → Token[]
+     *         → AstEngine.build()       → ProgramNode
+     *         → Interpreter.execute()   → TaskResult[]
+     *
+     * Throws:
+     *   - LexerError  — if the source contains illegal characters
+     *   - ParserError — if the source has a grammar error
+     *   - RuntimeError — if execution encounters an unrecoverable state
+     *
+     * @param inputRow Optional data row to inject into the execution for `Input` mappings
+     * @returns The array of `TaskResult`s produced by the interpreter.
+     */
+    run(inputRow?: Record<string, string>): Promise<TaskResult[]>;
+}

package/dist/berry-core.js

@@ -0,0 +1,258 @@
+/**
+ * BerryCore — Runtime Facade
+ *
+ * The single entry-point for running a .berry script programmatically.
+ *
+ * Responsibilities:
+ *   1. Tokenise the source code  (LexerEngine)
+ *   2. Build the AST            (AstEngine)
+ *   3. Execute the program      (Interpreter)
+ *   4. Relay every interpreter event to registered outside listeners
+ *
+ * Usage (CLI consumer):
+ *   const core = new BerryCore(source, { adapter: new CliAdapter() });
+ *   core.on(InterpreterEvent.Completed, payload => { ... });
+ *   await core.run();
+ *
+ * Usage (bare / no adapter):
+ *   const core = new BerryCore(source);
+ *   core.on(InterpreterEvent.Log, ({ message }) => console.log(message));
+ *   await core.run();
+ */
+import { LexerEngine } from "./parser/tokenizer/reader/lexer.engine.js";
+import { AstEngine } from "./parser/ast/ast.engine.js";
+import { NodeType } from "./parser/ast/ast.types.js";
+import { Interpreter } from "./interpreter/interpreter.js";
+import { InterpreterEvent, ExecutionState, } from "./interpreter/interpreter.types.js";
+// ─── BerryCore ───────────────────────────────────────────────────────────────
+export class BerryCore {
+    source;
+    options;
+    /**
+     * The interpreter instance is created fresh on every `run()` call so that
+     * BerryCore remains reusable across multiple sequential runs.
+     */
+    interpreter = null;
+    /**
+     * Listeners registered via `.on()` before `run()` is called.
+     * They are forwarded to the interpreter after it is created.
+     */
+    pendingListeners = [];
+    // ── Constructor ──────────────────────────────────────────────────────────
+    constructor(source, options = {}) {
+        this.source = source;
+        this.options = options;
+    }
+    // ── Public Event API ────────────────────────────────────────────────────
+    /**
+     * Register a listener for an interpreter lifecycle event.
+     *
+     * Listeners can be registered before or after calling `run()`.
+     * Listeners registered before `run()` are forwarded to the newly
+     * created Interpreter instance automatically.
+     */
+    on(event, listener) {
+        if (this.interpreter) {
+            // Already running — wire directly
+            this.interpreter.on(event, listener);
+        }
+        else {
+            // Queue for when run() creates the interpreter
+            this.pendingListeners.push({
+                event,
+                listener: listener,
+            });
+        }
+        return this;
+    }
+    // ── Execution Control API ───────────────────────────────────────────────
+    /**
+     * Send an execution command to the running interpreter.
+     * Has no effect if `run()` has not been called yet.
+     */
+    sendCommand(command) {
+        this.interpreter?.sendCommand(command);
+    }
+    /**
+     * Immediately kill the running execution and clean up resources.
+     */
+    kill() {
+        this.interpreter?.kill();
+    }
+    /**
+     * Returns the current execution state, or `Idle` if not yet started.
+     */
+    getState() {
+        return this.interpreter?.getState() ?? ExecutionState.Idle;
+    }
+    // ── Main Run ────────────────────────────────────────────────────────────
+    async resolveLinks(ast, visited = new Set()) {
+        const resolvedBody = [];
+        for (const stmt of ast.body) {
+            if (stmt.type === NodeType.LinkStatement) {
+                // Prevent infinite loops in circular links
+                if (visited.has(stmt.path)) {
+                    continue; // Already processed this link
+                }
+                visited.add(stmt.path);
+                let content;
+                if (this.options.linkResolver) {
+                    content = await this.options.linkResolver(stmt.path);
+                }
+                else {
+                    content = await this.defaultLinkResolver(stmt.path);
+                }
+                const subTokens = new LexerEngine(content).tokenize();
+                const subAst = new AstEngine(subTokens).build();
+                // Recursively resolve links in the sub-AST
+                const resolvedSubAst = await this.resolveLinks(subAst, visited);
+                // Add the resolved sub-body instead of the link statement
+                resolvedBody.push(...resolvedSubAst.body);
+            }
+            else {
+                resolvedBody.push(stmt);
+            }
+        }
+        return {
+            ...ast,
+            body: resolvedBody,
+        };
+    }
+    async defaultLinkResolver(path) {
+        // 1. Check if it's an HTTP URL
+        if (path.startsWith("http://") || path.startsWith("https://")) {
+            try {
+                const response = await fetch(path);
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch URL ${path}: ${response.statusText}`);
+                }
+                return await response.text();
+            }
+            catch (error) {
+                throw new Error(`Failed to fetch URL ${path}: ${error}`);
+            }
+        }
+        // 2. Check if we are in Node.js
+        const isNode = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+        if (isNode) {
+            try {
+                // Use dynamic import to avoid bundler issues in browser
+                const fs = await import("fs/promises");
+                const pathModule = await import("path");
+                const resolvedPath = this.options.basePath
+                    ? pathModule.resolve(this.options.basePath, path)
+                    : pathModule.resolve(process.cwd(), path);
+                return await fs.readFile(resolvedPath, "utf-8");
+            }
+            catch (e) {
+                throw new Error(`Failed to read local file ${path}: ${e}`);
+            }
+        }
+        // 3. Fallback for browser (relative URLs)
+        if (typeof window !== "undefined" && typeof fetch !== "undefined") {
+            try {
+                const response = await fetch(path);
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch relative URL ${path}: ${response.statusText}`);
+                }
+                return await response.text();
+            }
+            catch (e) {
+                throw new Error(`Failed to fetch relative URL ${path}: ${e}`);
+            }
+        }
+        throw new Error(`Cannot resolve link '${path}': Environment does not support file reading and path is not an absolute URL.`);
+    }
+    parseData(content, path) {
+        if (path.endsWith('.json')) {
+            return JSON.parse(content);
+        }
+        // Basic CSV parser
+        const lines = content.split(/\r?\n/).filter(line => line.trim().length > 0);
+        if (lines.length === 0)
+            return [];
+        const headers = lines[0].split(',').map(h => h.trim());
+        const rows = [];
+        for (let i = 1; i < lines.length; i++) {
+            const values = lines[i].split(',').map(v => v.trim());
+            const row = {};
+            for (let j = 0; j < headers.length; j++) {
+                row[headers[j]] = values[j] ?? "";
+            }
+            rows.push(row);
+        }
+        return rows;
+    }
+    /**
+     * Execute the source code end-to-end.
+     *
+     * Pipeline:
+     *   source → LexerEngine.tokenize() → Token[]
+     *         → AstEngine.build()       → ProgramNode
+     *         → Interpreter.execute()   → TaskResult[]
+     *
+     * Throws:
+     *   - LexerError  — if the source contains illegal characters
+     *   - ParserError — if the source has a grammar error
+     *   - RuntimeError — if execution encounters an unrecoverable state
+     *
+     * @param inputRow Optional data row to inject into the execution for `Input` mappings
+     * @returns The array of `TaskResult`s produced by the interpreter.
+     */
+    async run(inputRow) {
+        // ── Phase 1: Tokenise ──────────────────────────────────────────────
+        const tokens = new LexerEngine(this.source).tokenize();
+        // ── Phase 2: Build AST ────────────────────────────────────────────
+        let ast = new AstEngine(tokens).build();
+        // ── Phase 2.5: Resolve Links ──────────────────────────────────────
+        ast = await this.resolveLinks(ast);
+        // ── Phase 2.6: Handle Input ───────────────────────────────────────
+        if (!inputRow) {
+            const inputNode = ast.body.find(node => node.type === NodeType.InputStatement);
+            if (inputNode) {
+                let content;
+                if (this.options.linkResolver) {
+                    content = await this.options.linkResolver(inputNode.path);
+                }
+                else {
+                    content = await this.defaultLinkResolver(inputNode.path);
+                }
+                const rows = this.parseData(content, inputNode.path);
+                // Fire DataLoaded event to pending listeners
+                for (const { event, listener } of this.pendingListeners) {
+                    if (event === InterpreterEvent.DataLoaded) {
+                        await listener({ rows });
+                    }
+                }
+                // Return early, adapter is expected to loop and call run(row)
+                return [];
+            }
+        }
+        // ── Phase 3: Create Interpreter ───────────────────────────────────
+        this.interpreter = new Interpreter(ast, {
+            ...this.options.interpreterOptions,
+            inputRow,
+            decryptionProvider: this.options.decryptionProvider
+        });
+        // Wire the IO adapter (if provided)
+        if (this.options.adapter) {
+            this.interpreter.setIOAdapter(this.options.adapter);
+        }
+        // Forward any listeners that were registered before run() was called
+        for (const { event, listener } of this.pendingListeners) {
+            this.interpreter.on(event, listener);
+        }
+        // ── Phase 4: Execute ──────────────────────────────────────────────
+        try {
+            return await this.interpreter.execute();
+        }
+        finally {
+            // Only destroy if the interpreter actually finished
+            const state = this.interpreter?.getState();
+            const isFinished = state === ExecutionState.Completed || state === ExecutionState.Killed || state === ExecutionState.Stopped;
+            if (!this.options.interpreterOptions?.dryRun && isFinished) {
+                this.interpreter = null;
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { AstEngine, Ast, ParserError } from "./parser/ast/ast.engine.js";
+import { LexerEngine, LexerError } from "./parser/tokenizer/reader/lexer.engine.js";
+import { BerryFormatter } from "./parser/formatter/formatter.js";
+import { Interpreter } from "./interpreter/interpreter.js";
+import { CliAdapter } from "./adapter/cli-adapter.js";
+import { FormatUtil } from "./script/format-util.js";
+import { PostmanUtil } from "./script/postman.util.js";
+import { SwaggerUtil } from "./script/swagger.util.js";
+import { BerryCore } from "./berry-core.js";
+import { InterpreterEvent, type CompletedPayload, type TaskResult, type StepResult, type IOAdapter, ExecutionCommand, ExecutionState, ExecutionStatus } from "./interpreter/interpreter.types.js";
+import { type BerryCoreOptions } from "./berry-core.js";
+import { NodeType, type BaseNode, type TaskBlockNode, type StepBlockNode, type ParamsBlockNode, type CaptureBlockNode, type CheckBlockNode, type KeyValuePairNode, type ConditionNode, ProgramNode } from "./parser/ast/ast.types.js";
+export { BerryCore, type BerryCoreOptions, AstEngine, Ast, ParserError, LexerEngine, LexerError, BerryFormatter, Interpreter, CliAdapter, FormatUtil, PostmanUtil, SwaggerUtil, InterpreterEvent, ExecutionCommand, ExecutionState, ExecutionStatus, NodeType, type IOAdapter, type CompletedPayload, type TaskResult, type StepResult, type BaseNode, type TaskBlockNode, type StepBlockNode, type ParamsBlockNode, type CaptureBlockNode, type CheckBlockNode, type KeyValuePairNode, type ConditionNode, type ProgramNode };

package/dist/index.js

@@ -0,0 +1,18 @@
+import { AstEngine, Ast, ParserError } from "./parser/ast/ast.engine.js";
+import { LexerEngine, LexerError } from "./parser/tokenizer/reader/lexer.engine.js";
+import { BerryFormatter } from "./parser/formatter/formatter.js";
+import { Interpreter } from "./interpreter/interpreter.js";
+import { CliAdapter } from "./adapter/cli-adapter.js";
+import { FormatUtil } from "./script/format-util.js";
+import { PostmanUtil } from "./script/postman.util.js";
+import { SwaggerUtil } from "./script/swagger.util.js";
+import { BerryCore } from "./berry-core.js";
+import { InterpreterEvent, ExecutionCommand, ExecutionState, ExecutionStatus, } from "./interpreter/interpreter.types.js";
+import { NodeType } from "./parser/ast/ast.types.js";
+export { 
+// ── High-level facade (recommended entry-point) ──────────────────────
+BerryCore, 
+// ── Low-level building blocks (advanced consumers) ───────────────────
+AstEngine, Ast, ParserError, LexerEngine, LexerError, BerryFormatter, Interpreter, CliAdapter, FormatUtil, PostmanUtil, SwaggerUtil, 
+// ── Types / enums needed by consumers ────────────────────────────────
+InterpreterEvent, ExecutionCommand, ExecutionState, ExecutionStatus, NodeType };

package/dist/interpreter/environment.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Environment — Scoped Variable Store
+ *
+ * Maintains a chain of scopes: global → task → step.
+ * Each scope is a Map<string, RuntimeValue>.
+ * Lookup walks up the parent chain.
+ */
+import { RuntimeValue } from "./interpreter.types.js";
+export declare class Environment {
+    private readonly store;
+    private readonly parent;
+    constructor(parent?: Environment | null);
+    /**
+     * Declare a new variable in this scope.
+     * Overwrites if it already exists in this scope.
+     */
+    declare(name: string, value: RuntimeValue): void;
+    /**
+     * Look up a variable, walking up the scope chain.
+     * Throws VariableNotFoundError if not found in any scope.
+     */
+    lookup(name: string): RuntimeValue;
+    /**
+     * Try to look up a variable without throwing.
+     * Returns undefined if not found.
+     */
+    tryLookup(name: string): RuntimeValue | undefined;
+    /**
+     * Assign a value to an existing variable in the nearest scope.
+     * If not found, declares it in this scope.
+     */
+    assign(name: string, value: RuntimeValue): void;
+    /**
+     * Create a child scope inheriting from this environment.
+     */
+    createChild(): Environment;
+    /**
+     * Get all variables in this scope (not parents).
+     */
+    getOwnEntries(): ReadonlyMap<string, RuntimeValue>;
+    /**
+     * Get all variables including parent scopes (closest wins).
+     */
+    getAllEntries(): Map<string, RuntimeValue>;
+}