@orbytautomation/engine 0.1.0

package/dist/context/VariableResolver.js

@@ -0,0 +1,368 @@
+/**
+ * Variable Resolution Engine
+ *
+ * Resolves variables in workflow step inputs at runtime.
+ * Supports multiple variable sources aligned with workflow schema.
+ *
+ * Syntax: ${source.path.to.value}
+ *
+ * Supported sources:
+ * - env: Environment variables
+ * - steps: Step outputs
+ * - workflow: Workflow metadata
+ * - run: Execution metadata
+ * - context: Runtime context
+ * - inputs: Workflow inputs
+ * - secrets: Secret references (resolved externally)
+ * - metadata: Workflow metadata fields
+ *
+ * Future sources (placeholders):
+ * - telemetry: Telemetry data
+ * - resources: Resource information
+ * - compliance: Compliance metadata
+ *
+ * Advanced features:
+ * - Default values: ${env.token || "default"}
+ * - Built-in functions:
+ *   - Time: ${now()}, ${uuid()}, ${timestamp()}
+ *   - Context-aware: ${workflowId()}, ${workflowName()}, ${runId()}, ${attempt()}, ${triggeredBy()}
+ * - Type-aware: ${steps.count} returns number, not string
+ * - Math expressions: FUTURE (${steps.a + steps.b})
+ *
+ * @module context
+ */
+import { randomUUID } from 'crypto';
+/**
+ * Variable resolver engine
+ */
+export class VariableResolver {
+    /** Maximum recursion depth to prevent infinite loops */
+    maxDepth = 10;
+    /**
+     * Resolve all variables in the input value
+     *
+     * @param input - Input value (can be string, object, array, or primitive)
+     * @param ctx - Resolution context
+     * @param depth - Current recursion depth (internal)
+     * @returns Input with all variables resolved
+     */
+    resolve(input, ctx, depth = 0) {
+        // Prevent infinite recursion
+        if (depth > this.maxDepth) {
+            throw new Error(`Maximum variable resolution depth (${this.maxDepth}) exceeded. ` +
+                'Check for circular variable references.');
+        }
+        // Handle null/undefined
+        if (input === null || input === undefined) {
+            return input;
+        }
+        // Handle strings (may contain variables)
+        if (typeof input === 'string') {
+            return this.resolveString(input, ctx, depth);
+        }
+        // Handle arrays recursively
+        if (Array.isArray(input)) {
+            return input.map(v => this.resolve(v, ctx, depth + 1));
+        }
+        // Handle objects recursively
+        if (typeof input === 'object') {
+            const result = {};
+            for (const key in input) {
+                result[key] = this.resolve(input[key], ctx, depth + 1);
+            }
+            return result;
+        }
+        // Return primitives as-is
+        return input;
+    }
+    /**
+     * Resolve variables in a string
+     *
+     * Supports:
+     *   - Full replacement: "${env.apiKey}" -> actual value
+     *   - Inline replacement: "URL: ${env.baseUrl}/api" -> "URL: https://api.com/api"
+     *   - Default values: "${env.token || 'default'}" -> uses default if token undefined
+     *   - Built-in functions: "${now()}" -> current timestamp
+     *
+     * @param str - String potentially containing variables
+     * @param ctx - Resolution context
+     * @param depth - Current recursion depth
+     * @returns String with variables resolved
+     */
+    resolveString(str, ctx, depth) {
+        // Check if entire string is a single variable (type-aware resolution)
+        const singleVarMatch = str.match(/^\$\{([^}]+)\}$/);
+        if (singleVarMatch) {
+            // Return actual value (might not be string)
+            return this.evaluateExpression(singleVarMatch[1].trim(), ctx, depth);
+        }
+        // Replace all inline variables with string values
+        const regex = /\$\{([^}]+)\}/g;
+        return str.replace(regex, (_, expr) => {
+            const value = this.evaluateExpression(expr.trim(), ctx, depth);
+            return value !== undefined && value !== null ? String(value) : '';
+        });
+    }
+    /**
+     * Evaluate expression (supports default values and functions)
+     *
+     * Examples:
+     *   - env.apiKey -> lookup('env.apiKey')
+     *   - env.token || "default" -> lookup with fallback
+     *   - now() -> built-in function
+     *
+     * @param expression - Expression to evaluate
+     * @param ctx - Resolution context
+     * @param depth - Current recursion depth
+     * @returns Evaluated value
+     */
+    evaluateExpression(expression, ctx, depth) {
+        // Check for default value operator (||)
+        const defaultMatch = expression.match(/^(.+?)\|\|(.+)$/);
+        if (defaultMatch) {
+            const [, mainExpr, defaultExpr] = defaultMatch;
+            try {
+                const value = this.evaluateExpression(mainExpr.trim(), ctx, depth + 1);
+                if (value !== undefined && value !== null && value !== '') {
+                    return value;
+                }
+            }
+            catch (err) {
+                // If lookup fails, use default
+            }
+            // Parse default value (could be string literal or another expression)
+            const defaultVal = defaultExpr.trim();
+            // Handle string literals
+            if ((defaultVal.startsWith("'") && defaultVal.endsWith("'")) ||
+                (defaultVal.startsWith('"') && defaultVal.endsWith('"'))) {
+                return defaultVal.slice(1, -1);
+            }
+            // Handle number literals
+            if (!isNaN(Number(defaultVal))) {
+                return Number(defaultVal);
+            }
+            // Handle boolean literals
+            if (defaultVal === 'true')
+                return true;
+            if (defaultVal === 'false')
+                return false;
+            if (defaultVal === 'null')
+                return null;
+            // Otherwise evaluate as expression
+            return this.evaluateExpression(defaultVal, ctx, depth + 1);
+        }
+        // Check for built-in functions
+        if (expression.endsWith('()')) {
+            return this.callBuiltInFunction(expression.slice(0, -2), ctx);
+        }
+        // Standard variable lookup
+        return this.lookup(expression, ctx);
+    }
+    /**
+     * Call a built-in function
+     *
+     * Supported functions:
+     *   - now() -> current ISO timestamp
+     *   - uuid() -> random UUID v4
+     *   - timestamp() -> current Unix timestamp (milliseconds)
+     *   - workflowId() -> current workflow ID from context
+     *   - workflowName() -> current workflow name from context
+     *   - runId() -> current execution run ID from context
+     *   - attempt() -> current execution attempt number from context
+     *   - triggeredBy() -> who/what triggered the workflow from context
+     *
+     * @param funcName - Function name
+     * @param ctx - Resolution context for context-aware functions
+     * @returns Function result
+     */
+    callBuiltInFunction(funcName, ctx) {
+        switch (funcName) {
+            // Time-based functions (context-independent)
+            case 'now':
+                return new Date().toISOString();
+            case 'uuid':
+                return randomUUID();
+            case 'timestamp':
+                return Date.now();
+            // Context-aware workflow functions
+            case 'workflowId':
+                return ctx.workflow.id;
+            case 'workflowName':
+                return ctx.workflow.name;
+            // Context-aware run functions  
+            case 'runId':
+                return ctx.run.id;
+            case 'attempt':
+                return ctx.run.attempt;
+            case 'triggeredBy':
+                return ctx.run.triggeredBy || 'unknown';
+            // Future functions (placeholders)
+            case 'env':
+                throw new Error('env() function not yet supported. Use ${env.VAR_NAME} syntax instead.');
+            default:
+                throw new Error(`Unknown function: '${funcName}()'. ` +
+                    `Available functions: now(), uuid(), timestamp(), workflowId(), workflowName(), runId(), attempt(), triggeredBy()`);
+        }
+    }
+    /**
+     * Lookup variable value from context
+     *
+     * Supports:
+     *   - ${env.apiKey} -> ctx.env.apiKey
+     *   - ${steps.resize.output.url} -> ctx.steps.get('resize').output.url
+     *   - ${workflow.name} -> ctx.workflow.name
+     *   - ${run.id} -> ctx.run.id
+     *   - ${inputs.userId} -> ctx.inputs.userId
+     *   - ${secrets.apiKey} -> ctx.secrets.apiKey
+     *   - ${metadata.createdAt} -> ctx.metadata.createdAt
+     *   - ${context.customValue} -> ctx.context.customValue
+     *   - ${telemetry.*} -> Future placeholder
+     *   - ${resources.*} -> Future placeholder
+     *   - ${compliance.*} -> Future placeholder
+     *
+     * @param expression - Variable expression (without ${ })
+     * @param ctx - Resolution context
+     * @returns Resolved value or undefined
+     */
+    lookup(expression, ctx) {
+        const parts = expression.split('.');
+        const source = parts[0];
+        const path = parts.slice(1);
+        // Resolve source
+        let value;
+        switch (source) {
+            case 'env':
+                value = ctx.env;
+                break;
+            case 'steps': {
+                if (path.length === 0) {
+                    throw new Error('steps variable requires step ID: ${steps.stepId.output}');
+                }
+                const stepId = path[0];
+                const stepOutput = ctx.steps.get(stepId);
+                if (stepOutput === undefined) {
+                    throw new Error(`Step '${stepId}' not found or has not executed yet. ` +
+                        `Available steps: ${Array.from(ctx.steps.keys()).join(', ') || 'none'}`);
+                }
+                value = stepOutput;
+                // Remove stepId from path
+                path.shift();
+                break;
+            }
+            case 'workflow':
+                value = ctx.workflow;
+                break;
+            case 'run':
+                value = ctx.run;
+                break;
+            case 'inputs':
+                if (!ctx.inputs) {
+                    throw new Error('No inputs defined for this workflow execution');
+                }
+                value = ctx.inputs;
+                break;
+            case 'secrets':
+                if (!ctx.secrets) {
+                    throw new Error('No secrets available in this context. Secrets must be resolved before execution.');
+                }
+                value = ctx.secrets;
+                break;
+            case 'metadata':
+                if (!ctx.metadata) {
+                    throw new Error('No metadata available in this context');
+                }
+                value = ctx.metadata;
+                break;
+            case 'context':
+                value = ctx.context || {};
+                break;
+            // Future placeholders
+            case 'telemetry':
+                if (!ctx.telemetry) {
+                    throw new Error('Telemetry variables are not yet supported (future feature)');
+                }
+                value = ctx.telemetry;
+                break;
+            case 'resources':
+                if (!ctx.resources) {
+                    throw new Error('Resource variables are not yet supported (future feature)');
+                }
+                value = ctx.resources;
+                break;
+            case 'compliance':
+                if (!ctx.compliance) {
+                    throw new Error('Compliance variables are not yet supported (future feature)');
+                }
+                value = ctx.compliance;
+                break;
+            default:
+                throw new Error(`Unknown variable source: '${source}'. ` +
+                    `Valid sources are: env, steps, workflow, run, inputs, secrets, metadata, context. ` +
+                    `Future sources: telemetry, resources, compliance`);
+        }
+        // Navigate path
+        for (const key of path) {
+            if (value === undefined || value === null) {
+                return undefined;
+            }
+            value = value[key];
+        }
+        return value;
+    }
+    /**
+     * Check if a string contains variables
+     *
+     * @param str - String to check
+     * @returns True if string contains ${...} patterns
+     */
+    static hasVariables(str) {
+        return /\$\{[^}]+\}/.test(str);
+    }
+    /**
+     * Extract all variable expressions from a string
+     *
+     * @param str - String to analyze
+     * @returns Array of variable expressions (without ${ })
+     */
+    static extractVariables(str) {
+        const regex = /\$\{([^}]+)\}/g;
+        const matches = [];
+        let match;
+        while ((match = regex.exec(str)) !== null) {
+            matches.push(match[1].trim());
+        }
+        return matches;
+    }
+    /**
+     * Validate that all referenced steps exist
+     *
+     * @param input - Input to validate
+     * @param availableSteps - Set of available step IDs
+     * @throws {Error} If referenced step doesn't exist
+     */
+    static validateStepReferences(input, availableSteps) {
+        const checkValue = (value) => {
+            if (typeof value === 'string') {
+                const vars = this.extractVariables(value);
+                for (const varExpr of vars) {
+                    const parts = varExpr.split('.');
+                    if (parts[0] === 'steps' && parts.length > 1) {
+                        const stepId = parts[1];
+                        if (!availableSteps.has(stepId)) {
+                            throw new Error(`Variable references unknown step: '${stepId}'. ` +
+                                `Available steps: ${Array.from(availableSteps).join(', ')}`);
+                        }
+                    }
+                }
+            }
+            else if (Array.isArray(value)) {
+                value.forEach(checkValue);
+            }
+            else if (typeof value === 'object' && value !== null) {
+                Object.values(value).forEach(checkValue);
+            }
+        };
+        checkValue(input);
+    }
+}
+//# sourceMappingURL=VariableResolver.js.map

package/dist/context/VariableResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VariableResolver.js","sourceRoot":"","sources":["../../src/context/VariableResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AA0DpC;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAC3B,wDAAwD;IACvC,QAAQ,GAAG,EAAE,CAAC;IAE/B;;;;;;;OAOG;IACH,OAAO,CAAC,KAAU,EAAE,GAAsB,EAAE,QAAgB,CAAC;QAC3D,6BAA6B;QAC7B,IAAI,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,sCAAsC,IAAI,CAAC,QAAQ,cAAc;gBACjE,yCAAyC,CAC1C,CAAC;QACJ,CAAC;QACD,wBAAwB;QACxB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC1C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,yCAAyC;QACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAC/C,CAAC;QAED,4BAA4B;QAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,6BAA6B;QAC7B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAwB,EAAE,CAAC;YACvC,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;gBACxB,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YACzD,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,0BAA0B;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;;;;;;OAaG;IACK,aAAa,CAAC,GAAW,EAAE,GAAsB,EAAE,KAAa;QACtE,sEAAsE;QACtE,MAAM,cAAc,GAAG,GAAG,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACpD,IAAI,cAAc,EAAE,CAAC;YACnB,4CAA4C;YAC5C,OAAO,IAAI,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QACvE,CAAC;QAED,kDAAkD;QAClD,MAAM,KAAK,GAAG,gBAAgB,CAAC;QAC/B,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE;YACpC,MAAM,KAAK,GAAG,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YAC/D,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;OAYG;IACK,kBAAkB,CAAC,UAAkB,EAAE,GAAsB,EAAE,KAAa;QAClF,wCAAwC;QACxC,MAAM,YAAY,GAAG,UAAU,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACzD,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,GAAG,YAAY,CAAC;YAC/C,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;gBACvE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;oBAC1D,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,+BAA+B;YACjC,CAAC;YACD,sEAAsE;YACtE,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;YACtC,yBAAyB;YACzB,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;gBACxD,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBAC7D,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACjC,CAAC;YACD,yBAAyB;YACzB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;gBAC/B,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC;YAC5B,CAAC;YACD,0BAA0B;YAC1B,IAAI,UAAU,KAAK,MAAM;gBAAE,OAAO,IAAI,CAAC;YACvC,IAAI,UAAU,KAAK,OAAO;gBAAE,OAAO,KAAK,CAAC;YACzC,IAAI,UAAU,KAAK,MAAM;gBAAE,OAAO,IAAI,CAAC;YACvC,mCAAmC;YACnC,OAAO,IAAI,CAAC,kBAAkB,CAAC,UAAU,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC7D,CAAC;QAED,+BAA+B;QAC/B,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAChE,CAAC;QAED,2BAA2B;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACK,mBAAmB,CAAC,QAAgB,EAAE,GAAsB;QAClE,QAAQ,QAAQ,EAAE,CAAC;YACjB,6CAA6C;YAC7C,KAAK,KAAK;gBACR,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAElC,KAAK,MAAM;gBACT,OAAO,UAAU,EAAE,CAAC;YAEtB,KAAK,WAAW;gBACd,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;YAEpB,mCAAmC;YACnC,KAAK,YAAY;gBACf,OAAO,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAEzB,KAAK,cAAc;gBACjB,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;YAE3B,gCAAgC;YAChC,KAAK,OAAO;gBACV,OAAO,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAEpB,KAAK,SAAS;gBACZ,OAAO,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC;YAEzB,KAAK,aAAa;gBAChB,OAAO,GAAG,CAAC,GAAG,CAAC,WAAW,IAAI,SAAS,CAAC;YAE1C,kCAAkC;YAClC,KAAK,KAAK;gBACR,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;YAE3F;gBACE,MAAM,IAAI,KAAK,CACb,sBAAsB,QAAQ,OAAO;oBACrC,kHAAkH,CACnH,CAAC;QACN,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACK,MAAM,CAAC,UAAkB,EAAE,GAAsB;QACvD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAE5B,iBAAiB;QACjB,IAAI,KAAU,CAAC;QAEf,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,KAAK;gBACR,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC;gBAChB,MAAM;YAER,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACtB,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;gBAC7E,CAAC;gBACD,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;gBACvB,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACzC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;oBAC7B,MAAM,IAAI,KAAK,CACb,SAAS,MAAM,uCAAuC;wBACtD,oBAAoB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,EAAE,CACxE,CAAC;gBACJ,CAAC;gBACD,KAAK,GAAG,UAAU,CAAC;gBACnB,0BAA0B;gBAC1B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,MAAM;YACR,CAAC;YAED,KAAK,UAAU;gBACb,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC;gBACrB,MAAM;YAER,KAAK,KAAK;gBACR,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC;gBAChB,MAAM;YAER,KAAK,QAAQ;gBACX,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;oBAChB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;gBACnE,CAAC;gBACD,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC;gBACnB,MAAM;YAER,KAAK,SAAS;gBACZ,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;oBACjB,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC;gBACtG,CAAC;gBACD,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC;gBACpB,MAAM;YAER,KAAK,UAAU;gBACb,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;oBAClB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;gBAC3D,CAAC;gBACD,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC;gBACrB,MAAM;YAER,KAAK,SAAS;gBACZ,KAAK,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;gBAC1B,MAAM;YAER,sBAAsB;YACtB,KAAK,WAAW;gBACd,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;oBACnB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;gBAChF,CAAC;gBACD,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC;gBACtB,MAAM;YAER,KAAK,WAAW;gBACd,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;oBACnB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;gBAC/E,CAAC;gBACD,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC;gBACtB,MAAM;YAER,KAAK,YAAY;gBACf,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;oBACpB,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;gBACjF,CAAC;gBACD,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;gBACvB,MAAM;YAER;gBACE,MAAM,IAAI,KAAK,CACb,6BAA6B,MAAM,KAAK;oBACxC,oFAAoF;oBACpF,kDAAkD,CACnD,CAAC;QACN,CAAC;QAED,gBAAgB;QAChB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBAC1C,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,GAAW;QAC7B,OAAO,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAW;QACjC,MAAM,KAAK,GAAG,gBAAgB,CAAC;QAC/B,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC;QAEV,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAC1C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,sBAAsB,CAC3B,KAAU,EACV,cAA2B;QAE3B,MAAM,UAAU,GAAG,CAAC,KAAU,EAAQ,EAAE;YACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBAC1C,KAAK,MAAM,OAAO,IAAI,IAAI,EAAE,CAAC;oBAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;oBACjC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBAC7C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;wBACxB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;4BAChC,MAAM,IAAI,KAAK,CACb,sCAAsC,MAAM,KAAK;gCACjD,oBAAoB,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5D,CAAC;wBACJ,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YAC5B,CAAC;iBAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACvD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC,CAAC;QAEF,UAAU,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;CACF"}

package/dist/context/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Context Module
+ *
+ * Runtime context management and variable resolution.
+ *
+ * @module context
+ */
+/**
+ * Context Module
+ *
+ * Runtime context and variable resolution for workflow execution.
+ *
+ * @module context
+ */
+export * from './ContextStore.js';
+export * from './VariableResolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC"}

package/dist/context/index.js

@@ -0,0 +1,17 @@
+/**
+ * Context Module
+ *
+ * Runtime context management and variable resolution.
+ *
+ * @module context
+ */
+/**
+ * Context Module
+ *
+ * Runtime context and variable resolution for workflow execution.
+ *
+ * @module context
+ */
+export * from './ContextStore.js';
+export * from './VariableResolver.js';
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC"}

package/dist/core/EngineConfig.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Engine Configuration
+ *
+ * User-facing configuration for OrbytEngine.
+ * Provides sensible defaults and clear options for engine behavior.
+ *
+ * @module core
+ */
+import type { RetryPolicy } from '../automation/RetryPolicy.js';
+import type { TimeoutManager } from '../automation/TimeoutManager.js';
+import type { JobQueue } from '../queue/JobQueue.js';
+import type { LifecycleHook } from '../hooks/LifecycleHooks.js';
+import type { Adapter } from '@dev-ecosystem/core';
+/**
+ * Logging level for engine output
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Execution mode
+ */
+export type ExecutionMode = 'local' | 'distributed' | 'dry-run';
+/**
+ * Engine configuration options
+ *
+ * Provides a clean, user-friendly API for configuring OrbytEngine.
+ * All options are optional with sensible defaults.
+ *
+ * @example
+ * ```ts
+ * const config: OrbytEngineConfig = {
+ *   maxConcurrentWorkflows: 5,
+ *   logLevel: 'info',
+ *   enableScheduler: true,
+ *   adapters: [httpAdapter, shellAdapter],
+ *   hooks: [loggingHook, metricsHook]
+ * };
+ *
+ * const engine = new OrbytEngine(config);
+ * ```
+ */
+export interface OrbytEngineConfig {
+    /**
+     * Maximum number of workflows that can run concurrently
+     * @default 10
+     */
+    maxConcurrentWorkflows?: number;
+    /**
+     * Default timeout for workflows (milliseconds)
+     * @default 300000 (5 minutes)
+     */
+    defaultTimeout?: number;
+    /**
+     * Execution mode
+     * - 'local': Execute locally with full features
+     * - 'distributed': Execute in distributed mode (future)
+     * - 'dry-run': Validate and plan but don't execute
+     * @default 'local'
+     */
+    mode?: ExecutionMode;
+    /**
+     * Enable the internal scheduler for cron/scheduled workflows
+     * @default true
+     */
+    enableScheduler?: boolean;
+    /**
+     * Custom job queue implementation
+     * If not provided, uses InMemoryQueue
+     */
+    queue?: JobQueue;
+    /**
+     * Global retry policy for all steps
+     * Can be overridden per-step in workflow definition
+     */
+    retryPolicy?: RetryPolicy;
+    /**
+     * Global timeout manager
+     */
+    timeoutManager?: TimeoutManager;
+    /**
+     * Adapters to register with the engine
+     * These will be available for use in workflows
+     */
+    adapters?: Adapter[];
+    /**
+     * Lifecycle hooks for extending engine behavior
+     * Hooks are called at key execution moments
+     */
+    hooks?: LifecycleHook[];
+    /**
+     * Logging level
+     * @default 'info'
+     */
+    logLevel?: LogLevel;
+    /**
+     * Enable verbose output (equivalent to logLevel='debug')
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Enable metrics collection
+     * @default true
+     */
+    enableMetrics?: boolean;
+    /**
+     * Enable event emission
+     * @default true
+     */
+    enableEvents?: boolean;
+    /**
+     * Directory for storing execution state and logs
+     * @default '.orbyt/state'
+     */
+    stateDir?: string;
+    /**
+     * Directory for storing execution logs
+     * @default '.orbyt/logs'
+     */
+    logDir?: string;
+    /**
+     * Sandbox mode for step execution
+     * - 'none': No sandboxing
+     * - 'basic': Basic restrictions
+     * - 'strict': Strict isolation (future)
+     * @default 'basic'
+     */
+    sandboxMode?: 'none' | 'basic' | 'strict';
+    /**
+     * Working directory for workflow execution
+     * @default process.cwd()
+     */
+    workingDirectory?: string;
+    /**
+     * Enable experimental features
+     * @default false
+     */
+    experimental?: boolean;
+    /**
+     * Custom metadata to attach to all executions
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Apply default values to engine configuration
+ *
+ * @param config - User-provided configuration
+ * @returns Configuration with defaults applied
+ */
+export declare function applyConfigDefaults(config?: OrbytEngineConfig): Required<Omit<OrbytEngineConfig, 'queue' | 'retryPolicy' | 'timeoutManager' | 'adapters' | 'hooks' | 'metadata'>> & Pick<OrbytEngineConfig, 'queue' | 'retryPolicy' | 'timeoutManager' | 'adapters' | 'hooks' | 'metadata'>;
+/**
+ * Validate engine configuration
+ *
+ * @param config - Configuration to validate
+ * @throws Error if configuration is invalid
+ */
+export declare function validateConfig(config: OrbytEngineConfig): void;
+//# sourceMappingURL=EngineConfig.d.ts.map

package/dist/core/EngineConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EngineConfig.d.ts","sourceRoot":"","sources":["../../src/core/EngineConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,aAAa,GAAG,SAAS,CAAC;AAEhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IAIrB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAI1B;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;IAIjB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAIhC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAIrB;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IAIxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAIvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAIhB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAE1C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAI1B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,iBAAsB,GAAG,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,aAAa,GAAG,gBAAgB,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,aAAa,GAAG,gBAAgB,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC,CAsB/R;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAoB9D"}

package/dist/core/EngineConfig.js

@@ -0,0 +1,61 @@
+/**
+ * Engine Configuration
+ *
+ * User-facing configuration for OrbytEngine.
+ * Provides sensible defaults and clear options for engine behavior.
+ *
+ * @module core
+ */
+/**
+ * Apply default values to engine configuration
+ *
+ * @param config - User-provided configuration
+ * @returns Configuration with defaults applied
+ */
+export function applyConfigDefaults(config = {}) {
+    return {
+        maxConcurrentWorkflows: config.maxConcurrentWorkflows ?? 10,
+        defaultTimeout: config.defaultTimeout ?? 300000, // 5 minutes
+        mode: config.mode ?? 'local',
+        enableScheduler: config.enableScheduler ?? true,
+        queue: config.queue,
+        retryPolicy: config.retryPolicy,
+        timeoutManager: config.timeoutManager,
+        adapters: config.adapters,
+        hooks: config.hooks,
+        logLevel: config.verbose ? 'debug' : (config.logLevel ?? 'info'),
+        verbose: config.verbose ?? false,
+        enableMetrics: config.enableMetrics ?? true,
+        enableEvents: config.enableEvents ?? true,
+        stateDir: config.stateDir ?? '.orbyt/state',
+        logDir: config.logDir ?? '.orbyt/logs',
+        sandboxMode: config.sandboxMode ?? 'basic',
+        workingDirectory: config.workingDirectory ?? process.cwd(),
+        experimental: config.experimental ?? false,
+        metadata: config.metadata,
+    };
+}
+/**
+ * Validate engine configuration
+ *
+ * @param config - Configuration to validate
+ * @throws Error if configuration is invalid
+ */
+export function validateConfig(config) {
+    if (config.maxConcurrentWorkflows !== undefined && config.maxConcurrentWorkflows < 1) {
+        throw new Error('maxConcurrentWorkflows must be at least 1');
+    }
+    if (config.defaultTimeout !== undefined && config.defaultTimeout < 1) {
+        throw new Error('defaultTimeout must be positive');
+    }
+    if (config.mode && !['local', 'distributed', 'dry-run'].includes(config.mode)) {
+        throw new Error(`Invalid mode: ${config.mode}. Must be 'local', 'distributed', or 'dry-run'`);
+    }
+    if (config.logLevel && !['debug', 'info', 'warn', 'error', 'silent'].includes(config.logLevel)) {
+        throw new Error(`Invalid logLevel: ${config.logLevel}`);
+    }
+    if (config.sandboxMode && !['none', 'basic', 'strict'].includes(config.sandboxMode)) {
+        throw new Error(`Invalid sandboxMode: ${config.sandboxMode}`);
+    }
+}
+//# sourceMappingURL=EngineConfig.js.map

package/dist/core/EngineConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EngineConfig.js","sourceRoot":"","sources":["../../src/core/EngineConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiLH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAA4B,EAAE;IAChE,OAAO;QACL,sBAAsB,EAAE,MAAM,CAAC,sBAAsB,IAAI,EAAE;QAC3D,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,MAAM,EAAE,YAAY;QAC7D,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,OAAO;QAC5B,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;QAC/C,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC;QAChE,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK;QAChC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,IAAI;QAC3C,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;QACzC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,cAAc;QAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,aAAa;QACtC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,OAAO;QAC1C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,EAAE;QAC1D,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,KAAK;QAC1C,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAyB;IACtD,IAAI,MAAM,CAAC,sBAAsB,KAAK,SAAS,IAAI,MAAM,CAAC,sBAAsB,GAAG,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,IAAI,MAAM,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,CAAC,IAAI,gDAAgD,CAAC,CAAC;IAChG,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/F,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QACpF,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}