@hypercli/gen 0.1.1

package/dist/recipe-engine/recipe-engine.js

@@ -0,0 +1,1036 @@
+/**
+ * Recipe Engine - Main Orchestrator for Recipe Step System
+ *
+ * The RecipeEngine is the primary entry point for executing recipes in HyperDev.
+ * It provides recipe discovery, loading, validation, variable resolution, and execution
+ * coordination through the complete Recipe Step System.
+ */
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import { TemplateParser } from "@hypercli/core";
+import { ErrorCode, ErrorHandler, HypergenError } from "@hypercli/core";
+import { Logger } from "@hypercli/core";
+import createDebug from "debug";
+import yaml from "js-yaml";
+import { AiCollector } from "#ai/ai-collector";
+import { AiVariableResolver } from "#ai/ai-variable-resolver";
+import { resolveTransport } from "#ai/transports/resolve-transport";
+import { performInteractivePrompting } from "#prompts/interactive-prompts";
+import { renderTemplate as jigRenderTemplate } from "#template-engines/jig-engine";
+import { StepExecutor } from "./step-executor.js";
+import { registerDefaultTools } from "./tools/index.js";
+import { getToolRegistry } from "./tools/registry.js";
+import { RecipeDependencyError, RecipeValidationError } from "./types.js";
+/**
+ * Default recipe engine configuration
+ */
+const DEFAULT_CONFIG = {
+    stepExecutor: {
+        maxConcurrency: 10,
+        defaultTimeout: 30000,
+        defaultRetries: 3,
+        continueOnError: false,
+        enableParallelExecution: true,
+        collectMetrics: true,
+        enableProgressTracking: true,
+        memoryWarningThreshold: 1024,
+        timeoutSafetyFactor: 1.2,
+    },
+    workingDir: process.cwd(),
+    defaultTimeout: 60000,
+    enableDebugLogging: false,
+};
+/**
+ * Main Recipe Engine
+ *
+ * The RecipeEngine provides the primary API for executing recipes. It handles:
+ * - Recipe discovery and loading from various sources
+ * - Recipe validation and preprocessing
+ * - Variable resolution with user prompts
+ * - Step orchestration through StepExecutor
+ * - Result aggregation and reporting
+ * - Error handling and recovery
+ */
+export class RecipeEngine extends EventEmitter {
+    config;
+    logger;
+    debug;
+    stepExecutor;
+    toolRegistry;
+    // Execution state
+    activeExecutions = new Map();
+    executionCounter = 0;
+    // Caching (simple in-memory, no TTL)
+    recipeCache = new Map();
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.logger = new Logger(console.log);
+        this.debug = createDebug("hyper:recipe:engine");
+        // Initialize tool registry and register built-in tools
+        this.toolRegistry = getToolRegistry();
+        registerDefaultTools();
+        // Initialize step executor
+        this.stepExecutor = new StepExecutor(this.toolRegistry, this.config.stepExecutor);
+        this.debug("Recipe engine initialized with config: %o", {
+            workingDir: this.config.workingDir,
+        });
+        // Set up debug logging if enabled
+        if (this.config.enableDebugLogging) {
+            const existing = process.env.DEBUG || "";
+            const recipeDebug = "hyper:recipe:*";
+            process.env.DEBUG = existing ? `${existing},${recipeDebug}` : recipeDebug;
+        }
+        // Forward step executor events
+        this.stepExecutor.on("execution:started", (data) => this.emit("execution:started", data));
+        this.stepExecutor.on("execution:completed", (data) => this.emit("execution:completed", data));
+        this.stepExecutor.on("execution:failed", (data) => this.emit("execution:failed", data));
+        this.stepExecutor.on("step:started", (data) => this.emit("step:started", data));
+        this.stepExecutor.on("step:completed", (data) => this.emit("step:completed", data));
+        this.stepExecutor.on("step:failed", (data) => this.emit("step:failed", data));
+        this.stepExecutor.on("phase:started", (data) => this.emit("phase:started", data));
+        this.stepExecutor.on("phase:completed", (data) => this.emit("phase:completed", data));
+    }
+    /**
+     * Execute a recipe from various sources
+     *
+     * @param source Recipe source (file path, URL, package name, or content)
+     * @param options Execution options including variables and behavior settings
+     * @returns Promise resolving to execution result
+     */
+    async executeRecipe(source, options = {}) {
+        const executionId = this.generateExecutionId();
+        const startTime = Date.now();
+        this.debug("Starting recipe execution [%s] from source: %o", executionId, source);
+        this.emit("recipe:started", { executionId, source });
+        try {
+            // Normalize source
+            const normalizedSource = this.normalizeSource(source);
+            // Load and validate recipe
+            const loadResult = await this.loadRecipe(normalizedSource);
+            const { recipe, validation } = loadResult;
+            if (!validation.isValid) {
+                throw ErrorHandler.createError(ErrorCode.VALIDATION_ERROR, `Recipe validation failed: ${validation.errors.map((e) => e.message).join(", ")}`, { executionId, errors: validation.errors.map((e) => e.message) });
+            }
+            this.debug("Recipe loaded and validated: %s", recipe.name);
+            // Determine effective ask mode (skipPrompts is legacy compat for --ask=nobody)
+            const effectiveAskMode = options.askMode ?? (options.skipPrompts ? "nobody" : undefined);
+            // Resolve variables with user input if needed
+            const resolvedVariables = await this.resolveVariables(recipe, options.variables || {}, {
+                askMode: effectiveAskMode,
+                noDefaults: options.noDefaults || false,
+                aiConfig: options.aiConfig,
+                logger: options.logger,
+            });
+            this.debug("Variables resolved: %o", Object.keys(resolvedVariables));
+            // Create execution context
+            const context = await this.createExecutionContext(recipe, resolvedVariables, options, executionId, normalizedSource);
+            // Create step execution options
+            const stepOptions = {
+                timeout: options.stepOptions?.timeout || this.config.defaultTimeout,
+                continueOnError: options.continueOnError || this.config.stepExecutor.continueOnError,
+                dryRun: options.dryRun || false,
+                ...options.stepOptions,
+            };
+            // Execute steps through StepExecutor
+            this.debug("Starting step execution with %d steps", recipe.steps.length);
+            const stepResults = await this.stepExecutor.executeSteps(recipe.steps, context, stepOptions);
+            // Aggregate results
+            const result = this.aggregateResults(executionId, recipe, stepResults, resolvedVariables, startTime, context);
+            // Render and print onSuccess/onError messages
+            await this.renderLifecycleMessage(recipe, result, resolvedVariables, options);
+            this.debug("Recipe execution completed [%s] in %dms", executionId, result.duration);
+            this.emit("recipe:completed", { executionId, result });
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const normalizedSource = this.normalizeSource(source);
+            this.debug("Recipe execution failed [%s]: %s", executionId, error instanceof Error ? error.message : String(error));
+            this.emit("recipe:failed", {
+                executionId,
+                error,
+                duration,
+                source: normalizedSource,
+            });
+            if (error instanceof HypergenError) {
+                throw error;
+            }
+            throw ErrorHandler.createError(ErrorCode.INTERNAL_ERROR, `Recipe execution failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            this.activeExecutions.delete(executionId);
+        }
+    }
+    /**
+     * Load a recipe from a source without executing it
+     */
+    async loadRecipe(source) {
+        const normalizedSource = this.normalizeSource(source);
+        const cacheKey = this.getCacheKey(normalizedSource);
+        // Check cache first
+        const cached = this.recipeCache.get(cacheKey);
+        if (cached) {
+            this.debug("Recipe loaded from cache: %s", cacheKey);
+            // Still need to validate for dependencies
+            const validation = await this.validateRecipe(cached);
+            return {
+                recipe: cached,
+                source: normalizedSource,
+                validation,
+                dependencies: [],
+            };
+        }
+        this.debug("Loading recipe from source: %o", normalizedSource);
+        // Load recipe content
+        const content = await this.loadRecipeContent(normalizedSource);
+        // Parse recipe
+        const recipe = await this.parseRecipeContent(content, normalizedSource);
+        // Validate recipe
+        const validation = await this.validateRecipe(recipe);
+        // Load dependencies
+        const dependencies = await this.loadDependencies(recipe);
+        // Cache result
+        if (validation.isValid) {
+            this.recipeCache.set(cacheKey, recipe);
+        }
+        this.debug("Recipe loaded successfully: %s", recipe.name);
+        return {
+            recipe,
+            source: normalizedSource,
+            validation,
+            dependencies,
+        };
+    }
+    /**
+     * Validate a recipe configuration
+     */
+    async validateRecipe(recipe) {
+        const errors = [];
+        const warnings = [];
+        this.debug("Validating recipe: %s", recipe.name);
+        // Basic validation
+        if (!recipe.name || typeof recipe.name !== "string") {
+            errors.push(new RecipeValidationError("Recipe name is required and must be a string", "MISSING_NAME"));
+        }
+        if (!recipe.variables || typeof recipe.variables !== "object") {
+            errors.push(new RecipeValidationError("Recipe variables section is required", "MISSING_VARIABLES"));
+        }
+        else if (typeof recipe.variables === "object" && Object.keys(recipe.variables).length === 0) {
+            // Allow empty variables object, don't treat as error
+        }
+        if (!Array.isArray(recipe.steps) || recipe.steps.length === 0) {
+            errors.push(new RecipeValidationError("Recipe must have at least one step", "MISSING_STEPS"));
+        }
+        // Validate variables
+        if (recipe.variables) {
+            for (const [varName, varConfig] of Object.entries(recipe.variables)) {
+                const validation = this.validateVariable(varName, varConfig);
+                if (validation.error) {
+                    errors.push(new RecipeValidationError(validation.error, "INVALID_VARIABLE", {
+                        field: `variables.${varName}`,
+                    }));
+                }
+            }
+        }
+        // Validate steps
+        if (recipe.steps) {
+            const stepNames = new Set();
+            for (const [index, step] of recipe.steps.entries()) {
+                const stepErrors = this.validateStep(step, index, stepNames);
+                errors.push(...stepErrors);
+            }
+            // Validate dependencies
+            this.validateStepDependencies(recipe.steps, errors);
+        }
+        // Validate dependencies
+        if (recipe.dependencies) {
+            for (const dep of recipe.dependencies) {
+                const depValidation = await this.validateDependency(dep);
+                if (!depValidation.isValid) {
+                    errors.push(new RecipeValidationError(`Dependency validation failed: ${dep.name}`, "INVALID_DEPENDENCY"));
+                }
+            }
+        }
+        const result = {
+            isValid: errors.length === 0,
+            errors,
+            warnings: warnings.map((w) => ({
+                code: "WARNING",
+                message: w,
+                severity: "warning",
+                suggestion: undefined,
+            })),
+            recipe,
+            context: {
+                timestamp: new Date(),
+                validatorVersion: "8.0.0",
+                scope: "full",
+            },
+        };
+        this.debug("Recipe validation completed: %s (errors: %d, warnings: %d)", recipe.name, errors.length, warnings.length);
+        return result;
+    }
+    /**
+     * Get current execution status
+     */
+    getExecutions() {
+        return Array.from(this.activeExecutions.values());
+    }
+    /**
+     * Cancel a recipe execution
+     */
+    async cancelExecution(executionId) {
+        this.debug("Cancelling execution: %s", executionId);
+        const execution = this.activeExecutions.get(executionId);
+        if (!execution) {
+            throw ErrorHandler.createError(ErrorCode.ACTION_NOT_FOUND, `Execution not found: ${executionId}`);
+        }
+        // Cancel through step executor
+        await this.stepExecutor.cancelExecution(executionId);
+        // Update execution status
+        execution.status = "cancelled";
+        execution.endTime = new Date();
+        this.emit("recipe:cancelled", { executionId });
+    }
+    /**
+     * Cancel all active executions
+     */
+    async cancelAllExecutions() {
+        this.debug("Cancelling all executions");
+        const promises = Array.from(this.activeExecutions.keys()).map((id) => this.cancelExecution(id));
+        await Promise.allSettled(promises);
+    }
+    /**
+     * Clean up resources
+     */
+    async cleanup() {
+        this.debug("Cleaning up recipe engine");
+        // Cancel all executions
+        await this.cancelAllExecutions();
+        // Clear caches
+        this.recipeCache.clear();
+        // Clean up step executor
+        await this.stepExecutor.cancelAllExecutions();
+        this.emit("cleanup:completed");
+    }
+    // Private implementation methods
+    normalizeSource(source) {
+        if (typeof source === "string") {
+            // Auto-detect source type - only file paths supported
+            return { type: "file", path: source };
+        }
+        return source;
+    }
+    getCacheKey(source) {
+        switch (source.type) {
+            case "file":
+                return `file:${source.path}`;
+            case "content":
+                return `content:${source.name}`;
+            default:
+                return "unknown";
+        }
+    }
+    async loadRecipeContent(source) {
+        switch (source.type) {
+            case "file":
+                return this.loadFileContent(source.path);
+            case "content":
+                return source.content;
+            default:
+                throw ErrorHandler.createError(ErrorCode.VALIDATION_ERROR, `Unsupported source type: ${source.type}`);
+        }
+    }
+    async loadFileContent(filePath) {
+        try {
+            const fullPath = path.resolve(this.config.workingDir, filePath);
+            if (!fs.existsSync(fullPath)) {
+                throw ErrorHandler.createError(ErrorCode.ACTION_NOT_FOUND, `Recipe file not found: ${fullPath}`);
+            }
+            return fs.readFileSync(fullPath, "utf-8");
+        }
+        catch (error) {
+            if (error instanceof HypergenError) {
+                throw error;
+            }
+            throw ErrorHandler.createError(ErrorCode.INTERNAL_ERROR, `Failed to load recipe file: ${error instanceof Error ? error.message : String(error)}`, { filePath });
+        }
+    }
+    async parseRecipeContent(content, source) {
+        try {
+            const parsed = yaml.load(content);
+            if (!parsed || typeof parsed !== "object") {
+                throw new Error("Invalid YAML format or empty content");
+            }
+            // Convert from template.yml format if needed
+            const recipe = {
+                name: parsed.name || "", // Don't provide default to trigger validation
+                description: parsed.description,
+                version: parsed.version || "1.0.0",
+                author: parsed.author,
+                category: parsed.category || "general",
+                tags: parsed.tags || [],
+                variables: parsed.variables || {},
+                steps: this.normalizeSteps(parsed.steps || []),
+                provides: this.parseProvides(parsed.provides),
+                examples: parsed.examples || [],
+                dependencies: parsed.dependencies || [],
+                onSuccess: parsed.onSuccess,
+                onError: parsed.onError,
+                outputs: parsed.outputs || [],
+                engines: parsed.engines,
+                hooks: parsed.hooks,
+                settings: parsed.settings,
+                composition: parsed.composition,
+            };
+            return recipe;
+        }
+        catch (error) {
+            throw ErrorHandler.createError(ErrorCode.VALIDATION_ERROR, `Failed to parse recipe content: ${error instanceof Error ? error.message : String(error)}`, { source });
+        }
+    }
+    /**
+     * Parse the `provides` field from recipe YAML
+     */
+    parseProvides(raw) {
+        if (!raw || !Array.isArray(raw))
+            return undefined;
+        const provides = [];
+        for (const item of raw) {
+            if (typeof item === "string") {
+                provides.push({ name: item });
+            }
+            else if (typeof item === "object" && item !== null && typeof item.name === "string") {
+                const entry = { name: item.name };
+                if (item.type && typeof item.type === "string")
+                    entry.type = item.type;
+                if (item.description && typeof item.description === "string")
+                    entry.description = item.description;
+                provides.push(entry);
+            }
+        }
+        return provides.length > 0 ? provides : undefined;
+    }
+    /**
+     * Normalize steps to infer tool types from shorthands
+     */
+    normalizeSteps(steps) {
+        return steps.map((step) => {
+            if (!step.tool) {
+                if (step.command) {
+                    step.tool = "shell";
+                }
+                else if (step.recipe) {
+                    step.tool = "recipe";
+                }
+                else if (step.promptType) {
+                    // Inference for prompt
+                    step.tool = "prompt";
+                }
+                else if (step.sequence) {
+                    // Inference for sequence shorthand
+                    step.tool = "sequence";
+                    step.steps = step.sequence;
+                    step.sequence = undefined;
+                }
+                else if (step.parallel) {
+                    // Inference for parallel shorthand
+                    step.tool = "parallel";
+                    step.steps = step.parallel;
+                    step.parallel = undefined;
+                }
+                else if (step.steps) {
+                    // Default to sequence for generic steps property
+                    step.tool = "sequence";
+                }
+                else if (step.template) {
+                    step.tool = "template";
+                }
+                else if (step.action) {
+                    step.tool = "action";
+                }
+                else if (step.codemod) {
+                    step.tool = "codemod";
+                }
+                else if (step.packages) {
+                    step.tool = "install";
+                }
+            }
+            // Map args shorthand to variableOverrides for recipe steps
+            if (step.args && !step.variableOverrides) {
+                step.variableOverrides = step.args;
+                step.args = undefined;
+            }
+            // Recursively normalize nested steps in sequence/parallel
+            if (step.steps && Array.isArray(step.steps)) {
+                step.steps = this.normalizeSteps(step.steps);
+            }
+            return step;
+        });
+    }
+    async resolveVariables(recipe, providedVariables, opts) {
+        const { noDefaults = false, aiConfig, logger } = opts;
+        // Default: interactive in TTY, error in non-TTY (matches plan)
+        const askMode = opts.askMode ?? (process.stdout.isTTY ? "me" : "nobody");
+        const resolved = {};
+        const missingRequired = [];
+        const toAsk = [];
+        this.debug("Resolving variables for recipe: %s (askMode=%s, noDefaults=%s)", recipe.name, askMode, noDefaults);
+        // Phase 1: Apply provided values and defaults
+        for (const [varName, varConfig] of Object.entries(recipe.variables)) {
+            // Step 1: Check provided value
+            let value = providedVariables[varName];
+            // Step 2: Apply default (unless --no-defaults)
+            if (value === undefined && !noDefaults) {
+                value = varConfig.default;
+            }
+            // Step 3: If still unresolved, determine if we need to ask
+            if (value === undefined || value === null || value === "") {
+                const hint = varConfig.suggestion ?? (noDefaults ? varConfig.default : undefined);
+                const shouldAsk = varConfig.required || noDefaults;
+                if (shouldAsk) {
+                    toAsk.push({ varName, varConfig, hint });
+                    continue;
+                }
+                // Optional, not asked about — value stays undefined
+            }
+            // Step 4: If we have a value, validate it
+            if (value !== undefined) {
+                const validation = TemplateParser.validateVariableValue(varName, value, varConfig);
+                if (!validation.isValid) {
+                    throw ErrorHandler.createError(ErrorCode.VALIDATION_ERROR, validation.error || `Invalid value for variable: ${varName}`, { variable: varName, value, config: varConfig });
+                }
+            }
+            resolved[varName] =
+                value !== undefined ? value : TemplateParser.getResolvedValue(value, varConfig);
+        }
+        // Phase 2: Resolve unresolved variables based on ask mode
+        if (toAsk.length > 0) {
+            switch (askMode) {
+                case "me": {
+                    // Build all prompts and run them in a single session (one intro/outro)
+                    const promptConfigs = toAsk.map(({ varName, varConfig, hint }) => {
+                        const configWithHint = hint !== undefined ? { ...varConfig, default: hint } : varConfig;
+                        return {
+                            type: this.getPromptType(configWithHint),
+                            name: varName,
+                            message: configWithHint.description || `Enter value for ${varName}:`,
+                            default: configWithHint.default,
+                            choices: configWithHint.type === "enum" ? configWithHint.values : undefined,
+                            validate: (input) => {
+                                const validation = TemplateParser.validateVariableValue(varName, input, varConfig);
+                                return validation.isValid ? true : validation.error || false;
+                            },
+                        };
+                    });
+                    const loggerAdapter = logger ? { log: (msg) => logger.info(msg) } : undefined;
+                    const answers = await performInteractivePrompting(promptConfigs, loggerAdapter);
+                    for (const { varName, varConfig } of toAsk) {
+                        const value = answers[varName];
+                        const validation = TemplateParser.validateVariableValue(varName, value, varConfig);
+                        if (!validation.isValid) {
+                            throw ErrorHandler.createError(ErrorCode.VALIDATION_ERROR, validation.error || `Invalid value for variable: ${varName}`, { variable: varName, value });
+                        }
+                        resolved[varName] = value;
+                    }
+                    break;
+                }
+                case "ai": {
+                    // Check transport compatibility
+                    const transport = aiConfig ? resolveTransport(aiConfig) : null;
+                    const transportName = transport?.name;
+                    if (!transport || transportName === "stdout") {
+                        this.debug("AI mode requires api or command transport, falling back to interactive");
+                        console.warn("Warning: --ask=ai requires an API key or command transport configured. " +
+                            "Falling back to interactive prompts.");
+                        // Fall through to interactive (batch all prompts into one session)
+                        const fallbackConfigs = toAsk.map(({ varName, varConfig, hint }) => {
+                            const configWithHint = hint !== undefined ? { ...varConfig, default: hint } : varConfig;
+                            return {
+                                type: this.getPromptType(configWithHint),
+                                name: varName,
+                                message: configWithHint.description || `Enter value for ${varName}:`,
+                                default: configWithHint.default,
+                                choices: configWithHint.type === "enum" ? configWithHint.values : undefined,
+                            };
+                        });
+                        const fbLoggerAdapter = logger ? { log: (msg) => logger.info(msg) } : undefined;
+                        const fbAnswers = await performInteractivePrompting(fallbackConfigs, fbLoggerAdapter);
+                        for (const { varName } of toAsk) {
+                            resolved[varName] = fbAnswers[varName];
+                        }
+                        break;
+                    }
+                    // Batch-resolve via AI
+                    const unresolvedVars = toAsk.map(({ varName, varConfig, hint }) => ({
+                        name: varName,
+                        config: varConfig,
+                        defaultValue: noDefaults ? varConfig.default : undefined,
+                    }));
+                    const resolver = new AiVariableResolver(aiConfig);
+                    const aiAnswers = await resolver.resolveBatch(unresolvedVars, resolved, {
+                        name: recipe.name,
+                        description: recipe.description,
+                    });
+                    // Apply AI answers and validate
+                    for (const { varName, varConfig } of toAsk) {
+                        const value = aiAnswers[varName];
+                        if (value !== undefined) {
+                            const validation = TemplateParser.validateVariableValue(varName, value, varConfig);
+                            if (!validation.isValid) {
+                                this.debug("AI value for %s failed validation: %s", varName, validation.error);
+                                if (varConfig.required) {
+                                    missingRequired.push(varName);
+                                }
+                            }
+                            else {
+                                resolved[varName] = value;
+                            }
+                        }
+                        else if (varConfig.required) {
+                            missingRequired.push(varName);
+                        }
+                    }
+                    break;
+                }
+                case "nobody": {
+                    for (const { varName, varConfig } of toAsk) {
+                        if (varConfig.required) {
+                            missingRequired.push(varName);
+                        }
+                    }
+                    break;
+                }
+            }
+        }
+        if (missingRequired.length > 0) {
+            throw ErrorHandler.createError(ErrorCode.VALIDATION_ERROR, `Missing required variables: ${missingRequired.join(", ")}`, { missingVariables: missingRequired });
+        }
+        // Add any additional provided variables not defined in recipe
+        for (const [varName, value] of Object.entries(providedVariables)) {
+            if (!recipe.variables[varName]) {
+                resolved[varName] = value;
+            }
+        }
+        this.debug("Variables resolved successfully: %o", Object.keys(resolved));
+        return resolved;
+    }
+    getPromptType(varConfig) {
+        switch (varConfig.type) {
+            case "boolean":
+                return "confirm";
+            case "enum":
+                return "list";
+            case "number":
+                return "number";
+            case "file":
+                return "input"; // Could be enhanced with file picker
+            case "directory":
+                return "input"; // Could be enhanced with directory picker
+            default:
+                return "input";
+        }
+    }
+    async createExecutionContext(recipe, variables, options, executionId, source) {
+        // Determine collect mode: if no answers provided and AiCollector is in collect mode
+        const collectMode = !options.answers && AiCollector.getInstance().collectMode;
+        return {
+            step: {}, // Will be set by step executor
+            variables: { ...variables },
+            projectRoot: options.workingDir || this.config.workingDir,
+            recipeVariables: variables,
+            stepResults: new Map(),
+            recipe: {
+                id: executionId,
+                name: recipe.name,
+                version: recipe.version,
+                startTime: new Date(),
+            },
+            stepData: {},
+            evaluateCondition: this.createConditionEvaluator(variables),
+            answers: options.answers,
+            collectMode,
+            dryRun: options.dryRun,
+            force: options.force,
+            logger: options.logger || this.logger,
+            templatePath: source && typeof source === "object" && source.type === "file"
+                ? path.dirname(source.path)
+                : undefined,
+        };
+    }
+    createConditionEvaluator(variables) {
+        return (expression, ctx) => {
+            try {
+                // Built-in helper functions available in condition expressions
+                const projectRoot = ctx.projectRoot || this.config.workingDir || process.cwd();
+                const builtinFunctions = {
+                    fileExists: (filePath) => {
+                        const resolved = path.isAbsolute(filePath)
+                            ? filePath
+                            : path.resolve(projectRoot, filePath);
+                        return fs.existsSync(resolved);
+                    },
+                    dirExists: (dirPath) => {
+                        const resolved = path.isAbsolute(dirPath)
+                            ? dirPath
+                            : path.resolve(projectRoot, dirPath);
+                        try {
+                            return fs.statSync(resolved).isDirectory();
+                        }
+                        catch {
+                            return false;
+                        }
+                    },
+                };
+                // Flatten variables into scope for easier access in condition expressions
+                // ctx is the current context.variables dict (flat key-value), which includes
+                // both initial variables AND any exports from earlier steps.
+                const variableScope = {
+                    ...variables,
+                    ...ctx,
+                    variables: { ...variables, ...ctx },
+                };
+                const mergedContext = { ...builtinFunctions, ...variableScope };
+                // Use a set to ensure unique argument names for Function constructor
+                // Filter out reserved keywords to prevent SyntaxError
+                const reservedKeywords = new Set([
+                    "break",
+                    "case",
+                    "catch",
+                    "class",
+                    "const",
+                    "continue",
+                    "debugger",
+                    "default",
+                    "delete",
+                    "do",
+                    "else",
+                    "export",
+                    "extends",
+                    "finally",
+                    "for",
+                    "function",
+                    "if",
+                    "import",
+                    "in",
+                    "instanceof",
+                    "new",
+                    "return",
+                    "super",
+                    "switch",
+                    "this",
+                    "throw",
+                    "try",
+                    "typeof",
+                    "var",
+                    "void",
+                    "while",
+                    "with",
+                    "yield",
+                    "let",
+                    "static",
+                    "enum",
+                    "await",
+                    "implements",
+                    "interface",
+                    "package",
+                    "private",
+                    "protected",
+                    "public",
+                ]);
+                const argNames = Array.from(new Set(Object.keys(mergedContext))).filter((name) => !reservedKeywords.has(name) && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name));
+                const argValues = argNames.map((name) => mergedContext[name]);
+                const func = new Function(...argNames, `return ${expression}`);
+                return Boolean(func(...argValues));
+            }
+            catch (error) {
+                this.debug("Condition evaluation failed: %s - %s", expression, error instanceof Error ? error.message : String(error));
+                return false;
+            }
+        };
+    }
+    /**
+     * Recursively count steps including those nested in sequence/parallel tools
+     */
+    countNestedSteps(results, status, depth = 0) {
+        let count = 0;
+        for (const result of results) {
+            // For sequence/parallel tools, count only their nested steps (not the container itself)
+            // For all other tools, count the step if status matches or no filter
+            const isContainer = result.toolType === "sequence" || result.toolType === "parallel";
+            if (!isContainer && (!status || result.status === status)) {
+                count++;
+            }
+            // Recursively count nested steps in sequence/parallel tools
+            // Note: The toolResult is wrapped - it's result.toolResult.toolResult.steps, not result.toolResult.steps
+            // This is because the tool returns a StepResult with toolResult field, creating double nesting
+            if (isContainer && result.toolResult) {
+                const wrapped = result.toolResult;
+                const executionResult = wrapped.toolResult;
+                if (executionResult?.steps &&
+                    Array.isArray(executionResult.steps) &&
+                    executionResult.steps.length > 0) {
+                    const nestedCount = this.countNestedSteps(executionResult.steps, status, depth + 1);
+                    count += nestedCount;
+                }
+            }
+        }
+        return count;
+    }
+    aggregateResults(executionId, recipe, stepResults, variables, startTime, context) {
+        const duration = Date.now() - startTime;
+        // Count steps recursively including nested ones in sequences/parallel
+        const totalSteps = this.countNestedSteps(stepResults);
+        const completedSteps = this.countNestedSteps(stepResults, "completed");
+        const failedSteps = this.countNestedSteps(stepResults, "failed");
+        const skippedSteps = this.countNestedSteps(stepResults, "skipped");
+        // Aggregate file changes
+        const filesCreated = new Set();
+        const filesModified = new Set();
+        const filesDeleted = new Set();
+        const errors = [];
+        const warnings = [];
+        for (const result of stepResults) {
+            if (result.filesCreated) {
+                result.filesCreated.forEach((file) => filesCreated.add(file));
+            }
+            if (result.filesModified) {
+                result.filesModified.forEach((file) => filesModified.add(file));
+            }
+            if (result.filesDeleted) {
+                result.filesDeleted.forEach((file) => filesDeleted.add(file));
+            }
+            if (result.error) {
+                errors.push(`${result.stepName}: ${result.error.message}`);
+            }
+        }
+        // Collect providedValues from recipe.provides declarations
+        let providedValues;
+        if (recipe.provides && recipe.provides.length > 0) {
+            providedValues = {};
+            for (const p of recipe.provides) {
+                if (p.name in context.variables) {
+                    providedValues[p.name] = context.variables[p.name];
+                }
+            }
+            if (Object.keys(providedValues).length === 0) {
+                providedValues = undefined;
+            }
+        }
+        return {
+            executionId,
+            recipe,
+            success: failedSteps === 0,
+            stepResults,
+            duration,
+            filesCreated: Array.from(filesCreated),
+            filesModified: Array.from(filesModified),
+            filesDeleted: Array.from(filesDeleted),
+            errors,
+            warnings,
+            variables,
+            metadata: {
+                startTime: new Date(startTime),
+                endTime: new Date(),
+                workingDir: context.projectRoot,
+                totalSteps,
+                completedSteps,
+                failedSteps,
+                skippedSteps,
+                providedValues,
+            },
+        };
+    }
+    /**
+     * Render and print onSuccess or onError message after recipe execution
+     */
+    async renderLifecycleMessage(recipe, result, variables, options) {
+        // Don't print lifecycle messages during collect mode (Pass 1 of 2-pass AI generation)
+        // — only the AI prompt document should be printed to stdout
+        if (AiCollector.getInstance().collectMode)
+            return;
+        const template = result.success ? recipe.onSuccess : recipe.onError;
+        if (!template)
+            return;
+        try {
+            const renderContext = {
+                ...variables,
+                recipe: {
+                    name: recipe.name,
+                    description: recipe.description,
+                    version: recipe.version,
+                },
+                result: {
+                    success: result.success,
+                    filesCreated: result.filesCreated,
+                    filesModified: result.filesModified,
+                    errors: result.errors,
+                    duration: result.duration,
+                },
+            };
+            const rendered = await jigRenderTemplate(template, renderContext);
+            const trimmed = rendered.trim();
+            if (trimmed) {
+                const logger = options.logger || this.logger;
+                console.log(); // blank line before message
+                if (result.success) {
+                    logger.ok(trimmed);
+                }
+                else {
+                    logger.err(trimmed);
+                }
+            }
+        }
+        catch (error) {
+            this.debug("Failed to render %s message: %s", result.success ? "onSuccess" : "onError", error instanceof Error ? error.message : String(error));
+        }
+    }
+    async loadDependencies(recipe) {
+        const dependencies = [];
+        if (!recipe.dependencies) {
+            return dependencies;
+        }
+        for (const dep of recipe.dependencies) {
+            try {
+                const depSource = this.dependencyToSource(dep);
+                const depResult = await this.loadRecipe(depSource);
+                if (!depResult.validation.isValid && !dep.optional) {
+                    throw new RecipeDependencyError(`Required dependency validation failed: ${dep.name}`, dep.name, dep.version);
+                }
+                if (depResult.validation.isValid) {
+                    dependencies.push(depResult.recipe);
+                }
+            }
+            catch (error) {
+                if (dep.optional) {
+                    this.debug("Optional dependency failed to load: %s - %s", dep.name, error instanceof Error ? error.message : String(error));
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        return dependencies;
+    }
+    dependencyToSource(dependency) {
+        const name = typeof dependency === "string" ? dependency : dependency.name;
+        // Only local file dependencies supported
+        return { type: "file", path: name };
+    }
+    validateVariable(varName, varConfig) {
+        if (!varConfig || typeof varConfig !== "object") {
+            return { error: `Variable '${varName}' must be an object` };
+        }
+        if (!varConfig.type) {
+            return { error: `Variable '${varName}' must have a type` };
+        }
+        const validTypes = [
+            "string",
+            "number",
+            "boolean",
+            "enum",
+            "array",
+            "object",
+            "file",
+            "directory",
+        ];
+        if (!validTypes.includes(varConfig.type)) {
+            return {
+                error: `Variable '${varName}' has invalid type: ${varConfig.type}`,
+            };
+        }
+        return {};
+    }
+    validateStep(step, index, stepNames) {
+        const errors = [];
+        const stepAny = step; // Type assertion for validation context
+        if (!stepAny.name) {
+            errors.push(new RecipeValidationError(`Step ${index + 1} must have a name`, "MISSING_STEP_NAME", {
+                field: `steps[${index}].name`,
+            }));
+        }
+        else {
+            if (stepNames.has(stepAny.name)) {
+                errors.push(new RecipeValidationError(`Duplicate step name: ${stepAny.name}`, "DUPLICATE_STEP_NAME", {
+                    field: `steps[${index}].name`,
+                }));
+            }
+            stepNames.add(stepAny.name);
+        }
+        if (!stepAny.tool) {
+            errors.push(new RecipeValidationError(`Step ${stepAny.name || index + 1} must specify a tool`, "MISSING_TOOL", { field: `steps[${index}].tool` }));
+        }
+        const validTools = [
+            "template",
+            "action",
+            "codemod",
+            "recipe",
+            "shell",
+            "prompt",
+            "sequence",
+            "parallel",
+            "ai",
+            "install",
+            "query",
+            "patch",
+            "ensure-dirs",
+        ];
+        if (step.tool && !validTools.includes(step.tool)) {
+            errors.push(new RecipeValidationError(`Step ${step.name || index + 1} has invalid tool: ${step.tool}`, "INVALID_TOOL", { field: `steps[${index}].tool` }));
+        }
+        return errors;
+    }
+    validateStepDependencies(steps, errors) {
+        const stepNames = new Set(steps.map((s) => s.name));
+        for (const step of steps) {
+            if (step.dependsOn) {
+                for (const depName of step.dependsOn) {
+                    if (!stepNames.has(depName)) {
+                        errors.push(new RecipeValidationError(`Step ${step.name} depends on unknown step: ${depName}`, "UNKNOWN_DEPENDENCY", { step: step.name, field: "dependsOn" }));
+                    }
+                }
+            }
+        }
+    }
+    async validateDependency(dependency) {
+        const name = typeof dependency === "string" ? dependency : dependency.name;
+        if (!name) {
+            return { isValid: false, error: "Dependency must have a name" };
+        }
+        // Basic validation - in production you'd check if package/URL exists
+        return { isValid: true };
+    }
+    generateExecutionId() {
+        return `recipe_${Date.now()}_${++this.executionCounter}`;
+    }
+}
+/**
+ * Create a new recipe engine instance
+ */
+export function createRecipeEngine(config) {
+    return new RecipeEngine(config);
+}
+/**
+ * Execute a recipe with default configuration
+ */
+export async function executeRecipe(source, options) {
+    const engine = createRecipeEngine();
+    return await engine.executeRecipe(source, options);
+}
+/**
+ * Load and validate a recipe without executing
+ */
+export async function loadRecipe(source, config) {
+    const engine = createRecipeEngine(config);
+    return await engine.loadRecipe(source);
+}
+/**
+ * Validate a recipe configuration
+ */
+export async function validateRecipe(recipe, config) {
+    const engine = createRecipeEngine(config);
+    return await engine.validateRecipe(recipe);
+}
+//# sourceMappingURL=recipe-engine.js.map