@hypercli/gen 0.1.1

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

@@ -0,0 +1,397 @@
+/**
+ * Base Tool Framework
+ *
+ * Abstract base class and interfaces for all Recipe Step System tools.
+ * Provides common lifecycle management, error handling, and resource management.
+ */
+import { ErrorCode, ErrorHandler, HypergenError, withErrorHandling } from "@hypercli/core";
+import { Logger } from "@hypercli/core";
+import createDebug from "debug";
+/**
+ * Abstract base class for all Recipe Step System tools
+ *
+ * This class provides common functionality for Template, Action, CodeMod, and Recipe tools.
+ * Each tool type extends this class to implement specific execution logic.
+ */
+export class Tool {
+    toolType;
+    name;
+    options;
+    logger;
+    debug;
+    resources = new Map();
+    metrics;
+    _isInitialized = false;
+    _isExecuting = false;
+    _isCleanedUp = false;
+    constructor(toolType, name, options = {}) {
+        this.toolType = toolType;
+        this.name = name;
+        this.options = options;
+        this.logger = new Logger(console.log);
+        this.debug = createDebug(`hyper:recipe:tool:${toolType}:${name}`);
+        this.metrics = {
+            startTime: new Date(),
+            retryAttempts: 0,
+            cleanupCompleted: false,
+            events: [],
+        };
+        this.debug("Tool instance created: %s (%s)", name, toolType);
+    }
+    /**
+     * Get tool type
+     */
+    getToolType() {
+        return this.toolType;
+    }
+    /**
+     * Get tool name
+     */
+    getName() {
+        return this.name;
+    }
+    /**
+     * Check if tool is initialized
+     */
+    isInitialized() {
+        return this._isInitialized;
+    }
+    /**
+     * Check if tool is currently executing
+     */
+    isExecuting() {
+        return this._isExecuting;
+    }
+    /**
+     * Check if tool has been cleaned up
+     */
+    isCleanedUp() {
+        return this._isCleanedUp;
+    }
+    /**
+     * Get tool lifecycle metrics
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Initialize the tool with configuration
+     * Called once before any execution
+     */
+    async initialize() {
+        if (this._isInitialized) {
+            this.debug("Tool already initialized, skipping");
+            return;
+        }
+        this.debug("Initializing tool");
+        try {
+            await withErrorHandling(async () => {
+                await this.onInitialize();
+                this._isInitialized = true;
+                this.addLifecycleEvent("validate", true, { phase: "initialize" });
+                this.debug("Tool initialization completed");
+            }, { function: "initialize", action: this.name });
+        }
+        catch (error) {
+            this.addLifecycleEvent("validate", false, {
+                phase: "initialize",
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw this.wrapError(error, "Tool initialization failed");
+        }
+    }
+    /**
+     * Validate the step configuration and context
+     */
+    async validate(step, context) {
+        this.debug("Validating step configuration");
+        const startTime = Date.now();
+        try {
+            const result = await withErrorHandling(async () => {
+                return await this.onValidate(step, context);
+            }, { function: "validate", action: this.name });
+            const duration = Date.now() - startTime;
+            this.metrics.validationDuration = duration;
+            this.addLifecycleEvent("validate", result.isValid, {
+                duration,
+                errorsCount: result.errors.length,
+                warningsCount: result.warnings.length,
+            });
+            this.debug("Validation completed: %s (errors: %d, warnings: %d)", result.isValid ? "valid" : "invalid", result.errors.length, result.warnings.length);
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            this.metrics.validationDuration = duration;
+            this.addLifecycleEvent("validate", false, {
+                duration,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw this.wrapError(error, "Tool validation failed");
+        }
+    }
+    /**
+     * Execute the tool with the given step configuration and context
+     */
+    async execute(step, context, options) {
+        if (!this._isInitialized) {
+            await this.initialize();
+        }
+        if (this._isExecuting) {
+            throw ErrorHandler.createError(ErrorCode.INTERNAL_ERROR, "Tool is already executing", {
+                action: this.name,
+                phase: "execute",
+            });
+        }
+        this._isExecuting = true;
+        const startTime = Date.now();
+        this.debug("Starting tool execution");
+        try {
+            // Update metrics
+            this.metrics.startTime = new Date();
+            // Apply retry logic if specified
+            const maxRetries = options?.retries || step.retries || 0;
+            let lastError = null;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                if (attempt > 0) {
+                    this.debug("Retry attempt %d/%d", attempt, maxRetries);
+                    this.metrics.retryAttempts = attempt;
+                    // Add exponential backoff delay
+                    const delay = Math.min(1000 * 2 ** (attempt - 1), 30000);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+                try {
+                    const result = await withErrorHandling(async () => {
+                        return await this.onExecute(step, context, options);
+                    }, { function: "execute", action: this.name, phase: "execute" });
+                    const executionTime = Date.now() - startTime;
+                    this.metrics.executionDuration = executionTime;
+                    this.metrics.endTime = new Date();
+                    this.metrics.duration = executionTime;
+                    this.addLifecycleEvent("execute", result.status === "completed", {
+                        duration: executionTime,
+                        attempt,
+                        filesCreated: result.filesCreated?.length || 0,
+                        filesModified: result.filesModified?.length || 0,
+                        filesDeleted: result.filesDeleted?.length || 0,
+                    });
+                    this.debug("Tool execution completed: %s (duration: %dms, attempt: %d)", result.status, executionTime, attempt + 1);
+                    this._isExecuting = false;
+                    return result;
+                }
+                catch (error) {
+                    lastError = error;
+                    this.debug("Tool execution failed on attempt %d: %s", attempt + 1, error instanceof Error ? error.message : String(error));
+                    // If it's the last attempt, don't continue the retry loop
+                    if (attempt === maxRetries) {
+                        break;
+                    }
+                    // For certain errors, don't retry
+                    if (error instanceof HypergenError && !this.shouldRetry(error)) {
+                        break;
+                    }
+                }
+            }
+            // If we reach here, all attempts failed
+            const executionTime = Date.now() - startTime;
+            this.metrics.executionDuration = executionTime;
+            this.metrics.endTime = new Date();
+            this.metrics.duration = executionTime;
+            this.addLifecycleEvent("execute", false, {
+                duration: executionTime,
+                retryAttempts: this.metrics.retryAttempts,
+                error: lastError instanceof Error ? lastError.message : String(lastError),
+            });
+            throw this.wrapError(lastError, `Tool execution failed after ${maxRetries + 1} attempts`);
+        }
+        finally {
+            this._isExecuting = false;
+        }
+    }
+    /**
+     * Clean up resources used by the tool
+     */
+    async cleanup() {
+        if (this._isCleanedUp) {
+            this.debug("Tool already cleaned up, skipping");
+            return;
+        }
+        this.debug("Starting tool cleanup");
+        const startTime = Date.now();
+        const errors = [];
+        try {
+            // Clean up registered resources
+            for (const [id, resource] of this.resources) {
+                try {
+                    this.debug("Cleaning up resource: %s (%s)", id, resource.type);
+                    await resource.cleanup();
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    errors.push(`Failed to cleanup resource '${id}': ${errorMessage}`);
+                    this.debug("Resource cleanup failed: %s - %s", id, errorMessage);
+                }
+            }
+            // Call tool-specific cleanup
+            try {
+                await this.onCleanup();
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                errors.push(`Tool cleanup failed: ${errorMessage}`);
+                this.debug("Tool cleanup failed: %s", errorMessage);
+            }
+            const duration = Date.now() - startTime;
+            this.metrics.cleanupDuration = duration;
+            this.metrics.cleanupCompleted = errors.length === 0;
+            this._isCleanedUp = true;
+            this.addLifecycleEvent("cleanup", errors.length === 0, {
+                duration,
+                resourcesCleanedUp: this.resources.size,
+                errorsCount: errors.length,
+            });
+            if (errors.length > 0) {
+                this.logger.warn(`Tool cleanup completed with ${errors.length} errors`);
+                for (const error of errors) {
+                    this.logger.warn(`  ${error}`);
+                }
+            }
+            else {
+                this.debug("Tool cleanup completed successfully");
+            }
+            // Clear resources map
+            this.resources.clear();
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            this.metrics.cleanupDuration = duration;
+            this.addLifecycleEvent("cleanup", false, {
+                duration,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw this.wrapError(error, "Tool cleanup failed");
+        }
+    }
+    /**
+     * Register a resource for cleanup
+     */
+    registerResource(resource) {
+        if (this.resources.has(resource.id)) {
+            this.debug("Resource already registered, replacing: %s", resource.id);
+        }
+        this.resources.set(resource.id, resource);
+        this.debug("Resource registered: %s (%s)", resource.id, resource.type);
+    }
+    /**
+     * Unregister a resource (useful for early cleanup)
+     */
+    unregisterResource(resourceId) {
+        const resource = this.resources.get(resourceId);
+        if (resource) {
+            this.resources.delete(resourceId);
+            this.debug("Resource unregistered: %s", resourceId);
+        }
+    }
+    /**
+     * Get memory usage statistics
+     */
+    getMemoryUsage() {
+        const usage = process.memoryUsage();
+        return {
+            used: usage.heapUsed,
+            total: usage.heapTotal,
+        };
+    }
+    /**
+     * Add a lifecycle event to metrics
+     */
+    addLifecycleEvent(phase, success, metadata) {
+        this.metrics.events.push({
+            phase,
+            timestamp: new Date(),
+            success,
+            error: metadata?.error,
+            metadata,
+        });
+        // Track peak memory usage
+        const memUsage = this.getMemoryUsage();
+        if (!this.metrics.peakMemoryUsage || memUsage.used > this.metrics.peakMemoryUsage) {
+            this.metrics.peakMemoryUsage = memUsage.used;
+        }
+    }
+    /**
+     * Determine if an error should trigger a retry
+     */
+    shouldRetry(error) {
+        // Don't retry configuration or validation errors
+        const nonRetryableCodes = [
+            ErrorCode.CONFIG_INVALID_FORMAT,
+            ErrorCode.CONFIG_MISSING_REQUIRED,
+            ErrorCode.TEMPLATE_INVALID_SYNTAX,
+            ErrorCode.TEMPLATE_INVALID_FRONTMATTER,
+            ErrorCode.ACTION_INVALID_PARAMETERS,
+            ErrorCode.ACTION_INVALID_PARAM_TYPE,
+            ErrorCode.ACTION_INVALID_PARAM_VALUE,
+            ErrorCode.VALIDATION_ERROR,
+        ];
+        return !nonRetryableCodes.includes(error.code);
+    }
+    /**
+     * Wrap an error with tool context
+     */
+    wrapError(error, message) {
+        if (error instanceof HypergenError) {
+            // Add tool context to existing error
+            error.context = {
+                ...error.context,
+                toolType: this.toolType,
+                toolName: this.name,
+                phase: "execute",
+            };
+            return error;
+        }
+        return ErrorHandler.createError(ErrorCode.INTERNAL_ERROR, `${message}: ${error instanceof Error ? error.message : String(error)}`, {
+            toolType: this.toolType,
+            toolName: this.name,
+            phase: "execute",
+            cause: error,
+        });
+    }
+    // Abstract methods that must be implemented by concrete tool classes
+    /**
+     * Tool-specific initialization logic
+     * Override this method to perform any setup required before execution
+     */
+    async onInitialize() {
+        // Default implementation does nothing
+    }
+    /**
+     * Tool-specific cleanup logic
+     * Override this method to perform any cleanup required after execution
+     */
+    async onCleanup() {
+        // Default implementation does nothing
+    }
+}
+/**
+ * Abstract base class for tool factories
+ */
+export class BaseToolFactory {
+    toolType;
+    constructor(toolType) {
+        this.toolType = toolType;
+    }
+    getToolType() {
+        return this.toolType;
+    }
+    validateConfig(config) {
+        // Default validation - can be overridden by concrete factories
+        return {
+            isValid: true,
+            errors: [],
+            warnings: [],
+            suggestions: [],
+        };
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/recipe-engine/tools/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/recipe-engine/tools/base.ts"],"names":[],"mappings":"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"}

package/dist/recipe-engine/tools/codemod-tool.d.ts

@@ -0,0 +1,130 @@
+/**
+ * CodeMod Tool Implementation for Recipe Step System
+ *
+ * This tool provides AST-based code transformations and modifications using
+ * the TypeScript compiler API for TypeScript/JavaScript files, with fallback
+ * support for text-based transformations for other file types.
+ */
+import * as ts from "typescript";
+import { type CodeModStep, type StepContext, type StepExecutionOptions, type StepResult } from "#recipe-engine/types";
+import { Tool, type ToolValidationResult } from "./base.js";
+/**
+ * Supported CodeMod transformation types
+ */
+export type CodeModType = "add-import" | "add-export" | "modify-function" | "add-property" | "replace-text" | "custom";
+/**
+ * CodeMod transformation parameters
+ */
+export interface CodeModParameters {
+    import?: string;
+    from?: string;
+    importType?: "default" | "named" | "namespace" | "side-effect";
+    alias?: string;
+    export?: string;
+    exportType?: "default" | "named";
+    functionName?: string;
+    newSignature?: string;
+    newBody?: string;
+    className?: string;
+    objectName?: string;
+    propertyName?: string;
+    propertyValue?: string;
+    propertyType?: string;
+    find?: string | RegExp;
+    replace?: string;
+    global?: boolean;
+    transformFunction?: string | ((sourceFile: ts.SourceFile, context: CodeModContext) => ts.SourceFile);
+}
+/**
+ * CodeMod execution context
+ */
+export interface CodeModContext {
+    /** File path being transformed */
+    filePath: string;
+    /** Original source code */
+    sourceCode: string;
+    /** TypeScript source file (if applicable) */
+    sourceFile?: ts.SourceFile;
+    /** TypeScript program (if applicable) */
+    program?: ts.Program;
+    /** Step context */
+    stepContext: StepContext;
+    /** CodeMod parameters */
+    parameters: CodeModParameters;
+    /** Whether this is a dry run */
+    dryRun: boolean;
+    /** Whether to force overwrite */
+    force: boolean;
+}
+/**
+ * CodeMod Tool for AST transformations and code modifications
+ *
+ * Features:
+ * - TypeScript/JavaScript AST transformations using TypeScript compiler API
+ * - Text-based transformations for other file types
+ * - Built-in common transformations (add imports, exports, properties, etc.)
+ * - Custom transformation functions
+ * - Safe modification with backup and rollback
+ * - Batch processing with glob patterns
+ * - Comprehensive error handling and validation
+ */
+export declare class CodeModTool extends Tool<CodeModStep> {
+    private tsConfigCache;
+    private transformationCache;
+    private backupFiles;
+    constructor(name?: string, options?: Record<string, any>);
+    /**
+     * Initialize CodeMod tool
+     */
+    protected onInitialize(): Promise<void>;
+    /**
+     * Validate CodeMod step configuration
+     */
+    protected onValidate(step: CodeModStep, context: StepContext): Promise<ToolValidationResult>;
+    /**
+     * Execute the CodeMod tool
+     */
+    protected onExecute(step: CodeModStep, context: StepContext, options?: StepExecutionOptions): Promise<StepResult>;
+    /**
+     * Tool-specific cleanup logic
+     */
+    protected onCleanup(): Promise<void>;
+    /**
+     * Resolve file patterns to actual file paths
+     */
+    private resolveFiles;
+    /**
+     * Glob files with proper error handling
+     */
+    private globFiles;
+    /**
+     * Transform a single file
+     */
+    private transformFile;
+    /**
+     * Apply AST-based transformation for TypeScript/JavaScript files
+     */
+    private applyASTTransformation;
+    /**
+     * Apply text-based transformation for non-TypeScript files
+     */
+    private applyTextTransformation;
+    /**
+     * Determine parser to use for file
+     */
+    private determineParser;
+    /**
+     * Create backup of file before transformation
+     */
+    private createBackup;
+}
+/**
+ * CodeMod Tool Factory
+ */
+export declare class CodeModToolFactory {
+    create(name?: string, options?: Record<string, any>): CodeModTool;
+    getToolType(): "codemod";
+    validateConfig(config: Record<string, any>): ToolValidationResult;
+}
+export declare const codemodToolFactory: CodeModToolFactory;
+//# sourceMappingURL=codemod-tool.d.ts.map

package/dist/recipe-engine/tools/codemod-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codemod-tool.d.ts","sourceRoot":"","sources":["../../../src/recipe-engine/tools/codemod-tool.ts"],"names":[],"mappings":"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"}