@hypercli/core 0.1.1

package/dist/errors/hypergen-errors.js

@@ -0,0 +1,944 @@
+/**
+ * Hypergen Error System
+ *
+ * Provides comprehensive error handling with user-friendly messages
+ * and actionable guidance for common issues
+ */
+import { renderMarkdown } from "@hypercli/ui/help";
+export var ErrorCode;
+(function (ErrorCode) {
+    // Configuration errors
+    ErrorCode["CONFIG_FILE_NOT_FOUND"] = "CONFIG_FILE_NOT_FOUND";
+    ErrorCode["CONFIG_INVALID_FORMAT"] = "CONFIG_INVALID_FORMAT";
+    ErrorCode["CONFIG_MISSING_REQUIRED"] = "CONFIG_MISSING_REQUIRED";
+    // Template errors
+    ErrorCode["TEMPLATE_NOT_FOUND"] = "TEMPLATE_NOT_FOUND";
+    ErrorCode["TEMPLATE_INVALID_SYNTAX"] = "TEMPLATE_INVALID_SYNTAX";
+    ErrorCode["TEMPLATE_MISSING_VARIABLES"] = "TEMPLATE_MISSING_VARIABLES";
+    ErrorCode["TEMPLATE_INVALID_FRONTMATTER"] = "TEMPLATE_INVALID_FRONTMATTER";
+    ErrorCode["TEMPLATE_PARSING_ERROR"] = "TEMPLATE_PARSING_ERROR";
+    ErrorCode["TEMPLATE_EXECUTION_ERROR"] = "TEMPLATE_EXECUTION_ERROR";
+    // Action errors
+    ErrorCode["ACTION_NOT_FOUND"] = "ACTION_NOT_FOUND";
+    ErrorCode["ACTION_EXECUTION_FAILED"] = "ACTION_EXECUTION_FAILED";
+    ErrorCode["ACTION_INVALID_PARAMETERS"] = "ACTION_INVALID_PARAMETERS";
+    ErrorCode["ACTION_MISSING_REQUIRED_PARAM"] = "ACTION_MISSING_REQUIRED_PARAM";
+    ErrorCode["ACTION_INVALID_PARAM_TYPE"] = "ACTION_INVALID_PARAM_TYPE";
+    ErrorCode["ACTION_INVALID_PARAM_VALUE"] = "ACTION_INVALID_PARAM_VALUE";
+    // CodeMod errors
+    ErrorCode["CODEMOD_NOT_FOUND"] = "CODEMOD_NOT_FOUND";
+    ErrorCode["CODEMOD_EXECUTION_FAILED"] = "CODEMOD_EXECUTION_FAILED";
+    ErrorCode["CODEMOD_INVALID_PARAMETERS"] = "CODEMOD_INVALID_PARAMETERS";
+    ErrorCode["CODEMOD_TRANSFORMATION_FAILED"] = "CODEMOD_TRANSFORMATION_FAILED";
+    ErrorCode["CODEMOD_SYNTAX_ERROR"] = "CODEMOD_SYNTAX_ERROR";
+    ErrorCode["CODEMOD_AST_PARSING_ERROR"] = "CODEMOD_AST_PARSING_ERROR";
+    ErrorCode["CODEMOD_BACKUP_FAILED"] = "CODEMOD_BACKUP_FAILED";
+    ErrorCode["CODEMOD_FILE_NOT_FOUND"] = "CODEMOD_FILE_NOT_FOUND";
+    // File system errors
+    ErrorCode["FILE_NOT_FOUND"] = "FILE_NOT_FOUND";
+    ErrorCode["FILE_PERMISSION_DENIED"] = "FILE_PERMISSION_DENIED";
+    ErrorCode["FILE_ALREADY_EXISTS"] = "FILE_ALREADY_EXISTS";
+    ErrorCode["DIRECTORY_NOT_FOUND"] = "DIRECTORY_NOT_FOUND";
+    ErrorCode["DIRECTORY_NOT_EMPTY"] = "DIRECTORY_NOT_EMPTY";
+    // Generator discovery errors
+    ErrorCode["GENERATOR_NOT_FOUND"] = "GENERATOR_NOT_FOUND";
+    ErrorCode["GENERATOR_INVALID_STRUCTURE"] = "GENERATOR_INVALID_STRUCTURE";
+    ErrorCode["GENERATOR_MISSING_METADATA"] = "GENERATOR_MISSING_METADATA";
+    // URL resolution errors
+    ErrorCode["URL_INVALID_FORMAT"] = "URL_INVALID_FORMAT";
+    ErrorCode["URL_RESOLUTION_FAILED"] = "URL_RESOLUTION_FAILED";
+    ErrorCode["URL_FETCH_FAILED"] = "URL_FETCH_FAILED";
+    // Network errors
+    ErrorCode["NETWORK_CONNECTION_FAILED"] = "NETWORK_CONNECTION_FAILED";
+    ErrorCode["NETWORK_TIMEOUT"] = "NETWORK_TIMEOUT";
+    ErrorCode["NETWORK_UNAUTHORIZED"] = "NETWORK_UNAUTHORIZED";
+    // AI errors
+    ErrorCode["AI_API_KEY_MISSING"] = "AI_API_KEY_MISSING";
+    ErrorCode["AI_PROVIDER_UNAVAILABLE"] = "AI_PROVIDER_UNAVAILABLE";
+    ErrorCode["AI_GENERATION_FAILED"] = "AI_GENERATION_FAILED";
+    ErrorCode["AI_BUDGET_EXCEEDED"] = "AI_BUDGET_EXCEEDED";
+    ErrorCode["AI_SCHEMA_VALIDATION_FAILED"] = "AI_SCHEMA_VALIDATION_FAILED";
+    ErrorCode["AI_SYNTAX_VALIDATION_FAILED"] = "AI_SYNTAX_VALIDATION_FAILED";
+    ErrorCode["AI_IMPORT_VALIDATION_FAILED"] = "AI_IMPORT_VALIDATION_FAILED";
+    ErrorCode["AI_RATE_LIMITED"] = "AI_RATE_LIMITED";
+    ErrorCode["AI_CONTEXT_TOO_LARGE"] = "AI_CONTEXT_TOO_LARGE";
+    ErrorCode["AI_TRANSPORT_FAILED"] = "AI_TRANSPORT_FAILED";
+    // General errors
+    ErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+export class HypergenError extends Error {
+    code;
+    context;
+    suggestions;
+    isUserError;
+    severity;
+    constructor(code, message, context = {}, suggestions = [], isUserError = true, severity = "medium") {
+        super(message);
+        this.name = "HypergenError";
+        this.code = code;
+        this.context = context;
+        this.suggestions = suggestions;
+        this.isUserError = isUserError;
+        this.severity = severity;
+    }
+}
+export class ErrorHandler {
+    static ERROR_MESSAGES = {
+        [ErrorCode.CONFIG_FILE_NOT_FOUND]: "Configuration file not found",
+        [ErrorCode.CONFIG_INVALID_FORMAT]: "Configuration file has invalid format",
+        [ErrorCode.CONFIG_MISSING_REQUIRED]: "Configuration is missing required fields",
+        [ErrorCode.TEMPLATE_NOT_FOUND]: "Template file not found",
+        [ErrorCode.TEMPLATE_INVALID_SYNTAX]: "Template has invalid syntax",
+        [ErrorCode.TEMPLATE_MISSING_VARIABLES]: "Template is missing required variables",
+        [ErrorCode.TEMPLATE_INVALID_FRONTMATTER]: "Template has invalid frontmatter",
+        [ErrorCode.TEMPLATE_PARSING_ERROR]: "Template parsing failed",
+        [ErrorCode.TEMPLATE_EXECUTION_ERROR]: "Template execution failed",
+        [ErrorCode.ACTION_NOT_FOUND]: "Action not found",
+        [ErrorCode.ACTION_EXECUTION_FAILED]: "Action execution failed",
+        [ErrorCode.ACTION_INVALID_PARAMETERS]: "Action has invalid parameters",
+        [ErrorCode.ACTION_MISSING_REQUIRED_PARAM]: "Action is missing required parameter",
+        [ErrorCode.ACTION_INVALID_PARAM_TYPE]: "Action parameter has invalid type",
+        [ErrorCode.ACTION_INVALID_PARAM_VALUE]: "Action parameter has invalid value",
+        [ErrorCode.CODEMOD_NOT_FOUND]: "CodeMod not found",
+        [ErrorCode.CODEMOD_EXECUTION_FAILED]: "CodeMod execution failed",
+        [ErrorCode.CODEMOD_INVALID_PARAMETERS]: "CodeMod has invalid parameters",
+        [ErrorCode.CODEMOD_TRANSFORMATION_FAILED]: "CodeMod transformation failed",
+        [ErrorCode.CODEMOD_SYNTAX_ERROR]: "CodeMod has syntax error",
+        [ErrorCode.CODEMOD_AST_PARSING_ERROR]: "CodeMod AST parsing failed",
+        [ErrorCode.CODEMOD_BACKUP_FAILED]: "CodeMod backup creation failed",
+        [ErrorCode.CODEMOD_FILE_NOT_FOUND]: "CodeMod file not found",
+        [ErrorCode.FILE_NOT_FOUND]: "File not found",
+        [ErrorCode.FILE_PERMISSION_DENIED]: "Permission denied",
+        [ErrorCode.FILE_ALREADY_EXISTS]: "File already exists",
+        [ErrorCode.DIRECTORY_NOT_FOUND]: "Directory not found",
+        [ErrorCode.DIRECTORY_NOT_EMPTY]: "Directory is not empty",
+        [ErrorCode.GENERATOR_NOT_FOUND]: "Generator not found",
+        [ErrorCode.GENERATOR_INVALID_STRUCTURE]: "Generator has invalid structure",
+        [ErrorCode.GENERATOR_MISSING_METADATA]: "Generator is missing metadata",
+        [ErrorCode.URL_INVALID_FORMAT]: "URL has invalid format",
+        [ErrorCode.URL_RESOLUTION_FAILED]: "URL resolution failed",
+        [ErrorCode.URL_FETCH_FAILED]: "Failed to fetch URL",
+        [ErrorCode.NETWORK_CONNECTION_FAILED]: "Network connection failed",
+        [ErrorCode.NETWORK_TIMEOUT]: "Network request timed out",
+        [ErrorCode.NETWORK_UNAUTHORIZED]: "Network request unauthorized",
+        [ErrorCode.AI_API_KEY_MISSING]: "AI provider API key is not configured",
+        [ErrorCode.AI_PROVIDER_UNAVAILABLE]: "AI provider is unavailable",
+        [ErrorCode.AI_GENERATION_FAILED]: "AI code generation failed",
+        [ErrorCode.AI_BUDGET_EXCEEDED]: "AI cost budget exceeded",
+        [ErrorCode.AI_SCHEMA_VALIDATION_FAILED]: "AI output failed schema validation",
+        [ErrorCode.AI_SYNTAX_VALIDATION_FAILED]: "AI output has syntax errors",
+        [ErrorCode.AI_IMPORT_VALIDATION_FAILED]: "AI output contains invalid imports",
+        [ErrorCode.AI_RATE_LIMITED]: "AI provider rate limit exceeded",
+        [ErrorCode.AI_CONTEXT_TOO_LARGE]: "AI context exceeds token budget",
+        [ErrorCode.AI_TRANSPORT_FAILED]: "AI transport resolution failed",
+        [ErrorCode.UNKNOWN_ERROR]: "Unknown error occurred",
+        [ErrorCode.INTERNAL_ERROR]: "Internal error occurred",
+        [ErrorCode.VALIDATION_ERROR]: "Validation error occurred",
+    };
+    static ERROR_SUGGESTIONS = {
+        [ErrorCode.CONFIG_FILE_NOT_FOUND]: [
+            {
+                title: "Create configuration file",
+                description: "Create a hypergen.config.js file in your project root",
+                command: "hypergen init workspace",
+            },
+            {
+                title: "Check file path",
+                description: "Verify the configuration file path is correct",
+            },
+        ],
+        [ErrorCode.CONFIG_INVALID_FORMAT]: [
+            {
+                title: "Check configuration syntax",
+                description: "Verify the configuration file has valid syntax",
+            },
+            {
+                title: "See configuration examples",
+                description: "Look at working configuration examples",
+                url: "https://hypergen.dev/docs/configuration",
+            },
+        ],
+        [ErrorCode.CONFIG_MISSING_REQUIRED]: [
+            {
+                title: "Add required fields",
+                description: "Ensure all required configuration fields are present",
+            },
+            {
+                title: "Check documentation",
+                description: "See required configuration fields",
+                url: "https://hypergen.dev/docs/configuration",
+            },
+        ],
+        [ErrorCode.TEMPLATE_INVALID_SYNTAX]: [
+            {
+                title: "Check template syntax",
+                description: "Verify the template file has valid syntax",
+            },
+            {
+                title: "Validate template",
+                description: "Use the template validator",
+                command: "hypergen template validate <path>",
+            },
+        ],
+        [ErrorCode.TEMPLATE_MISSING_VARIABLES]: [
+            {
+                title: "Add required variables",
+                description: "Ensure all required template variables are defined",
+            },
+            {
+                title: "Check template documentation",
+                description: "See template variable requirements",
+                url: "https://hypergen.dev/docs/templates",
+            },
+        ],
+        [ErrorCode.TEMPLATE_INVALID_FRONTMATTER]: [
+            {
+                title: "Check frontmatter syntax",
+                description: "Verify the template frontmatter has valid YAML syntax",
+            },
+            {
+                title: "See frontmatter examples",
+                description: "Look at working frontmatter examples",
+                url: "https://hypergen.dev/docs/frontmatter",
+            },
+        ],
+        [ErrorCode.ACTION_EXECUTION_FAILED]: [
+            {
+                title: "Check action parameters",
+                description: "Verify all required parameters are provided",
+            },
+            {
+                title: "Check file permissions",
+                description: "Ensure you have write permissions to the target directory",
+            },
+        ],
+        [ErrorCode.ACTION_INVALID_PARAMETERS]: [
+            {
+                title: "Check parameter format",
+                description: "Verify all parameters have correct format and types",
+            },
+            {
+                title: "View action details",
+                description: "See parameter requirements",
+                command: "hypergen info <action-name>",
+            },
+        ],
+        [ErrorCode.ACTION_INVALID_PARAM_TYPE]: [
+            {
+                title: "Check parameter type",
+                description: "Verify the parameter has the correct type",
+            },
+            {
+                title: "View action details",
+                description: "See parameter type requirements",
+                command: "hypergen info <action-name>",
+            },
+        ],
+        [ErrorCode.ACTION_INVALID_PARAM_VALUE]: [
+            {
+                title: "Check parameter value",
+                description: "Verify the parameter value is valid",
+            },
+            {
+                title: "View action examples",
+                description: "See example parameter values",
+                command: "hypergen info <action-name>",
+            },
+        ],
+        [ErrorCode.FILE_ALREADY_EXISTS]: [
+            {
+                title: "Use different name",
+                description: "Choose a different name for the file",
+            },
+            {
+                title: "Use force option",
+                description: "Use --force to overwrite existing files",
+            },
+        ],
+        [ErrorCode.DIRECTORY_NOT_FOUND]: [
+            {
+                title: "Create directory",
+                description: "Create the target directory first",
+            },
+            {
+                title: "Check directory path",
+                description: "Verify the directory path is correct",
+            },
+        ],
+        [ErrorCode.DIRECTORY_NOT_EMPTY]: [
+            {
+                title: "Use different directory",
+                description: "Choose an empty directory",
+            },
+            {
+                title: "Clean directory",
+                description: "Remove files from the directory first",
+            },
+        ],
+        [ErrorCode.GENERATOR_INVALID_STRUCTURE]: [
+            {
+                title: "Check generator structure",
+                description: "Verify the generator follows the correct structure",
+            },
+            {
+                title: "Create new generator",
+                description: "Create a new generator with proper structure",
+                command: "hypergen init generator --name=my-generator",
+            },
+        ],
+        [ErrorCode.GENERATOR_MISSING_METADATA]: [
+            {
+                title: "Add generator metadata",
+                description: "Ensure the generator has required metadata",
+            },
+            {
+                title: "Check generator documentation",
+                description: "See generator metadata requirements",
+                url: "https://hypergen.dev/docs/generators",
+            },
+        ],
+        [ErrorCode.URL_FETCH_FAILED]: [
+            {
+                title: "Check internet connection",
+                description: "Verify you have an active internet connection",
+            },
+            {
+                title: "Check URL format",
+                description: "Verify the URL is correct and accessible",
+            },
+        ],
+        [ErrorCode.NETWORK_TIMEOUT]: [
+            {
+                title: "Try again",
+                description: "The request may succeed on retry",
+            },
+            {
+                title: "Check network connection",
+                description: "Verify your internet connection is stable",
+            },
+        ],
+        [ErrorCode.NETWORK_UNAUTHORIZED]: [
+            {
+                title: "Check authentication",
+                description: "Verify your credentials are correct",
+            },
+            {
+                title: "Check permissions",
+                description: "Ensure you have access to the resource",
+            },
+        ],
+        [ErrorCode.UNKNOWN_ERROR]: [
+            {
+                title: "Try again",
+                description: "The operation might succeed on retry",
+            },
+            {
+                title: "Check error details",
+                description: "Review the error message for specific issues",
+            },
+        ],
+        [ErrorCode.INTERNAL_ERROR]: [
+            {
+                title: "Report this issue",
+                description: "This might be a bug in Hypergen",
+                url: "https://github.com/svallory/hypergen/issues",
+            },
+            {
+                title: "Try again",
+                description: "The operation might succeed on retry",
+            },
+        ],
+        [ErrorCode.VALIDATION_ERROR]: [
+            {
+                title: "Check input format",
+                description: "Verify your input follows the expected format",
+            },
+            {
+                title: "See documentation",
+                description: "Check the documentation for requirements",
+                url: "https://hypergen.dev/docs",
+            },
+        ],
+        [ErrorCode.TEMPLATE_NOT_FOUND]: [
+            {
+                title: "Check template path",
+                description: "Verify the template file exists at the specified path",
+            },
+            {
+                title: "Create template",
+                description: "Create a new template file",
+                command: "hypergen init generator --name=my-template",
+            },
+            {
+                title: "List available templates",
+                description: "See all available templates",
+                command: "hypergen template list",
+            },
+        ],
+        [ErrorCode.TEMPLATE_PARSING_ERROR]: [
+            {
+                title: "Check template syntax",
+                description: "Verify the template.yml file has valid YAML syntax",
+            },
+        ],
+        [ErrorCode.TEMPLATE_EXECUTION_ERROR]: [
+            {
+                title: "Check template variables",
+                description: "Verify all required variables are provided",
+            },
+        ],
+        [ErrorCode.FILE_NOT_FOUND]: [
+            {
+                title: "Check file path",
+                description: "Verify the file exists at the specified path",
+            },
+            {
+                title: "Create the file",
+                description: "Create the missing file",
+            },
+        ],
+        [ErrorCode.URL_RESOLUTION_FAILED]: [
+            {
+                title: "Check URL format",
+                description: "Verify the URL follows the correct format",
+            },
+            {
+                title: "Check internet connection",
+                description: "Verify you have an active internet connection",
+            },
+        ],
+        [ErrorCode.ACTION_NOT_FOUND]: [
+            {
+                title: "List available actions",
+                description: "See all available actions",
+                command: "hypergen list",
+            },
+            {
+                title: "Discover generators",
+                description: "Run discovery to find available generators",
+                command: "hypergen discover",
+            },
+            {
+                title: "Create new action",
+                description: "Create a new action generator",
+                command: "hypergen init generator --name=my-action",
+            },
+        ],
+        [ErrorCode.ACTION_MISSING_REQUIRED_PARAM]: [
+            {
+                title: "Check required parameters",
+                description: "View action details to see required parameters",
+                command: "hypergen info <action-name>",
+            },
+            {
+                title: "Use action examples",
+                description: "See example usage for this action",
+                command: "hypergen info <action-name>",
+            },
+        ],
+        [ErrorCode.FILE_PERMISSION_DENIED]: [
+            {
+                title: "Check file permissions",
+                description: "Ensure you have write permissions to the target directory",
+            },
+            {
+                title: "Run with sudo",
+                description: "Try running the command with elevated privileges (use caution)",
+            },
+        ],
+        [ErrorCode.GENERATOR_NOT_FOUND]: [
+            {
+                title: "Run discovery",
+                description: "Discover available generators",
+                command: "hypergen discover",
+            },
+            {
+                title: "Install generator",
+                description: "Install a generator package",
+                command: "npm install <generator-package>",
+            },
+            {
+                title: "Create generator",
+                description: "Create your own generator",
+                command: "hypergen init generator --name=my-generator",
+            },
+        ],
+        [ErrorCode.URL_INVALID_FORMAT]: [
+            {
+                title: "Check URL format",
+                description: "Ensure the URL follows the correct format (e.g., github:user/repo)",
+            },
+            {
+                title: "URL examples",
+                description: "Valid formats: github:user/repo, npm:package-name, file:./path",
+                url: "https://hypergen.dev/docs/url-templates",
+            },
+        ],
+        [ErrorCode.NETWORK_CONNECTION_FAILED]: [
+            {
+                title: "Check internet connection",
+                description: "Verify you have an active internet connection",
+            },
+            {
+                title: "Check proxy settings",
+                description: "Verify proxy configuration if behind a corporate firewall",
+            },
+            {
+                title: "Try again later",
+                description: "The remote server might be temporarily unavailable",
+            },
+        ],
+        [ErrorCode.CODEMOD_NOT_FOUND]: [
+            {
+                title: "Check CodeMod name",
+                description: "Verify the CodeMod identifier is correct and supported",
+            },
+            {
+                title: "View supported CodeMods",
+                description: "List of supported CodeMod types: add-import, add-export, modify-function, add-property, replace-text, custom",
+            },
+        ],
+        [ErrorCode.CODEMOD_EXECUTION_FAILED]: [
+            {
+                title: "Check file permissions",
+                description: "Ensure you have write permissions for the target files",
+            },
+            {
+                title: "Validate parameters",
+                description: "Check that all required parameters are provided and valid",
+            },
+            {
+                title: "Enable backup",
+                description: "Set backup: true to preserve original files before transformation",
+            },
+        ],
+        [ErrorCode.CODEMOD_INVALID_PARAMETERS]: [
+            {
+                title: "Check parameter requirements",
+                description: "Each CodeMod type has specific required parameters",
+            },
+            {
+                title: "See documentation",
+                description: "Review CodeMod parameter documentation",
+                url: "https://hypergen.dev/docs/codemods",
+            },
+        ],
+        [ErrorCode.CODEMOD_TRANSFORMATION_FAILED]: [
+            {
+                title: "Check file syntax",
+                description: "Ensure the target files have valid syntax",
+            },
+            {
+                title: "Simplify transformation",
+                description: "Try breaking complex transformations into smaller steps",
+            },
+            {
+                title: "Use text transformation",
+                description: "Consider using replace-text for simple changes instead of AST transformations",
+            },
+        ],
+        [ErrorCode.CODEMOD_SYNTAX_ERROR]: [
+            {
+                title: "Fix syntax errors",
+                description: "Resolve syntax errors in the target file before applying transformations",
+            },
+        ],
+        [ErrorCode.CODEMOD_AST_PARSING_ERROR]: [
+            {
+                title: "Use correct parser",
+                description: "Specify the correct parser for your file type (typescript, javascript, etc.)",
+            },
+            {
+                title: "Check file encoding",
+                description: "Ensure files are properly encoded (UTF-8)",
+            },
+        ],
+        [ErrorCode.CODEMOD_BACKUP_FAILED]: [
+            {
+                title: "Check disk space",
+                description: "Ensure sufficient disk space for backup files",
+            },
+            {
+                title: "Check permissions",
+                description: "Verify write permissions in the target directory",
+            },
+        ],
+        [ErrorCode.CODEMOD_FILE_NOT_FOUND]: [
+            {
+                title: "Check file patterns",
+                description: "Verify the file patterns match existing files",
+            },
+            {
+                title: "Use absolute paths",
+                description: "Consider using absolute paths or checking working directory",
+            },
+        ],
+        [ErrorCode.AI_API_KEY_MISSING]: [
+            {
+                title: "Add API key to .env file",
+                description: "Add the appropriate env var to your .env file (e.g., ANTHROPIC_API_KEY=sk-...)",
+            },
+            {
+                title: "Or set it as an environment variable",
+                description: "Export the env var in your shell (e.g., export ANTHROPIC_API_KEY=sk-...)",
+            },
+            {
+                title: "Custom env var name",
+                description: "Set ai.apiKeyEnvVar in hypergen.config.js to use a non-default env var name",
+            },
+        ],
+        [ErrorCode.AI_PROVIDER_UNAVAILABLE]: [
+            {
+                title: "Check internet connection",
+                description: "Verify you have an active internet connection",
+            },
+            {
+                title: "Install provider SDK",
+                description: "Install the provider SDK package (e.g., bun add @ai-sdk/anthropic)",
+                command: "bun add @ai-sdk/anthropic",
+            },
+            {
+                title: "Configure fallback models",
+                description: "Add fallbackModels in hypergen.config.js ai configuration",
+            },
+        ],
+        [ErrorCode.AI_GENERATION_FAILED]: [
+            {
+                title: "Check prompt",
+                description: "Review the prompt for clarity and completeness",
+            },
+            {
+                title: "Try a different model",
+                description: "Some models perform better for specific tasks",
+            },
+            {
+                title: "Increase temperature",
+                description: "Higher temperature may help with creative generation",
+            },
+        ],
+        [ErrorCode.AI_BUDGET_EXCEEDED]: [
+            {
+                title: "Increase budget",
+                description: "Raise maxTotalCostUsd in ai.budget configuration",
+            },
+            {
+                title: "Use a cheaper model",
+                description: "Switch to a more cost-effective model for bulk operations",
+            },
+            {
+                title: "Reduce context",
+                description: "Include fewer context files to reduce token usage",
+            },
+        ],
+        [ErrorCode.AI_SCHEMA_VALIDATION_FAILED]: [
+            {
+                title: "Check schema definition",
+                description: "Verify the output schema matches expected AI output format",
+            },
+            {
+                title: "Add examples",
+                description: "Provide few-shot examples to guide the model output format",
+            },
+        ],
+        [ErrorCode.AI_SYNTAX_VALIDATION_FAILED]: [
+            {
+                title: "Enable retry-with-feedback",
+                description: 'Set guardrails.onFailure to "retry-with-feedback" for automatic correction',
+            },
+            {
+                title: "Lower temperature",
+                description: "Lower temperature produces more deterministic, syntactically correct output",
+            },
+        ],
+        [ErrorCode.AI_IMPORT_VALIDATION_FAILED]: [
+            {
+                title: "Enable requireKnownImports",
+                description: "Set guardrails.requireKnownImports to validate imports against package.json",
+            },
+            {
+                title: "Specify allowedImports",
+                description: "Explicitly list allowed packages in guardrails.allowedImports",
+            },
+        ],
+        [ErrorCode.AI_RATE_LIMITED]: [
+            {
+                title: "Wait and retry",
+                description: "The rate limit will reset automatically. Hypergen retries with backoff.",
+            },
+            {
+                title: "Configure fallback provider",
+                description: "Add fallbackModels to switch providers when rate limited",
+            },
+        ],
+        [ErrorCode.AI_CONTEXT_TOO_LARGE]: [
+            {
+                title: "Reduce context files",
+                description: "Include fewer files in the context configuration",
+            },
+            {
+                title: "Set maxContextTokens",
+                description: "Configure context.maxContextTokens to limit context size",
+            },
+            {
+                title: "Use truncation",
+                description: 'Set context.overflow to "truncate" to automatically trim context',
+            },
+        ],
+        [ErrorCode.AI_TRANSPORT_FAILED]: [
+            {
+                title: "Check AI mode configuration",
+                description: "Verify ai.mode and related settings in hypergen.config.js",
+            },
+            {
+                title: "Use stdout mode",
+                description: "Fall back to --ai-mode stdout to print the prompt and resolve manually",
+            },
+            {
+                title: "Check command output",
+                description: "If using command mode, verify the command returns valid JSON",
+            },
+        ],
+    };
+    /**
+     * Create a user-friendly error with context and suggestions
+     */
+    static createError(code, customMessage, context = {}, customSuggestions = []) {
+        const baseMessage = ErrorHandler.ERROR_MESSAGES[code] || "Unknown error";
+        const message = customMessage || baseMessage;
+        const suggestions = customSuggestions.length > 0 ? customSuggestions : ErrorHandler.ERROR_SUGGESTIONS[code] || [];
+        return new HypergenError(code, message, context, suggestions);
+    }
+    /**
+     * Format error for display in CLI
+     */
+    static formatError(error) {
+        const lines = [];
+        // Error header
+        lines.push(`❌ ${error.message}`);
+        // Error code and severity
+        if (error.code !== ErrorCode.UNKNOWN_ERROR) {
+            lines.push(`   Code: ${error.code}`);
+        }
+        // Context information
+        if (error.context.file) {
+            let location = `   File: ${error.context.file}`;
+            if (error.context.line) {
+                location += `:${error.context.line}`;
+                if (error.context.column) {
+                    location += `:${error.context.column}`;
+                }
+            }
+            lines.push(location);
+        }
+        if (error.context.action) {
+            lines.push(`   Action: ${error.context.action}`);
+        }
+        if (error.context.parameter) {
+            lines.push(`   Parameter: ${error.context.parameter}`);
+        }
+        if (error.context.expected && error.context.received) {
+            lines.push(`   Expected: ${error.context.expected}`);
+            lines.push(`   Received: ${error.context.received}`);
+        }
+        // Suggestions — rendered as markdown for proper styling
+        if (error.suggestions.length > 0) {
+            const md = ["", "**Suggestions:**", ""];
+            for (const [index, suggestion] of error.suggestions.entries()) {
+                md.push(`${index + 1}. **${suggestion.title}**`);
+                md.push(`   ${suggestion.description}`);
+                if (suggestion.command) {
+                    md.push(`   \`\`\`sh\n   $ ${suggestion.command}\n   \`\`\``);
+                }
+                if (suggestion.url) {
+                    md.push(`   [Documentation](${suggestion.url})`);
+                }
+                if (index < error.suggestions.length - 1) {
+                    md.push("");
+                }
+            }
+            lines.push(renderMarkdown(md.join("\n")));
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Handle and format any error for CLI display
+     */
+    static handleError(error) {
+        if (error instanceof HypergenError) {
+            return ErrorHandler.formatError(error);
+        }
+        if (error instanceof Error) {
+            // Try to categorize common Node.js errors
+            if (error.message.includes("ENOENT")) {
+                const hypergenError = ErrorHandler.createError(ErrorCode.FILE_NOT_FOUND, error.message, {
+                    file: ErrorHandler.extractFileFromError(error.message),
+                });
+                return ErrorHandler.formatError(hypergenError);
+            }
+            if (error.message.includes("EACCES")) {
+                const hypergenError = ErrorHandler.createError(ErrorCode.FILE_PERMISSION_DENIED, error.message, { file: ErrorHandler.extractFileFromError(error.message) });
+                return ErrorHandler.formatError(hypergenError);
+            }
+            if (error.message.includes("EEXIST")) {
+                const hypergenError = ErrorHandler.createError(ErrorCode.FILE_ALREADY_EXISTS, error.message, { file: ErrorHandler.extractFileFromError(error.message) });
+                return ErrorHandler.formatError(hypergenError);
+            }
+            if (error.message.includes("ENOTDIR")) {
+                const hypergenError = ErrorHandler.createError(ErrorCode.DIRECTORY_NOT_FOUND, error.message, { file: ErrorHandler.extractFileFromError(error.message) });
+                return ErrorHandler.formatError(hypergenError);
+            }
+            // Generic error handling
+            const hypergenError = ErrorHandler.createError(ErrorCode.UNKNOWN_ERROR, error.message, {}, [
+                {
+                    title: "Check the error details",
+                    description: "Review the error message for specific issues",
+                },
+            ]);
+            return ErrorHandler.formatError(hypergenError);
+        }
+        // Unknown error type
+        const hypergenError = ErrorHandler.createError(ErrorCode.INTERNAL_ERROR, "An unexpected error occurred", {}, [
+            {
+                title: "Report this issue",
+                description: "This might be a bug in Hypergen",
+                url: "https://github.com/svallory/hypergen/issues",
+            },
+        ]);
+        return ErrorHandler.formatError(hypergenError);
+    }
+    /**
+     * Extract file path from error message
+     */
+    static extractFileFromError(message) {
+        const match = message.match(/(?:open|access|stat) '([^']+)'/);
+        return match ? match[1] : undefined;
+    }
+    /**
+     * Create parameter validation error
+     */
+    static createParameterError(parameter, value, expected, action) {
+        return ErrorHandler.createError(ErrorCode.ACTION_INVALID_PARAM_VALUE, `Invalid value for parameter '${parameter}'`, {
+            parameter,
+            value: String(value),
+            expected,
+            action,
+        }, [
+            {
+                title: "Check parameter format",
+                description: `Parameter '${parameter}' should be ${expected}`,
+            },
+            {
+                title: "View action details",
+                description: "See all parameters and their requirements",
+                command: action ? `hypergen info ${action}` : undefined,
+            },
+        ]);
+    }
+    /**
+     * Create template validation error
+     */
+    static createTemplateError(file, line, column, details) {
+        return ErrorHandler.createError(ErrorCode.TEMPLATE_INVALID_SYNTAX, `Template validation failed${details ? `: ${details}` : ""}`, { file, line, column }, [
+            {
+                title: "Check template syntax",
+                description: "Verify the template file has valid syntax",
+            },
+            {
+                title: "Validate template",
+                description: "Use the template validator",
+                command: `hypergen template validate ${file}`,
+            },
+        ]);
+    }
+    /**
+     * Create action not found error
+     */
+    static createActionNotFoundError(actionName) {
+        return ErrorHandler.createError(ErrorCode.ACTION_NOT_FOUND, `Action '${actionName}' not found`, { action: actionName }, [
+            {
+                title: "List available actions",
+                description: "See all available actions",
+                command: "hypergen list",
+            },
+            {
+                title: "Discover generators",
+                description: "Run discovery to find available generators",
+                command: "hypergen discover",
+            },
+            {
+                title: "Check spelling",
+                description: "Verify the action name is spelled correctly",
+            },
+        ]);
+    }
+    /**
+     * Create file operation error
+     */
+    static createFileError(operation, file, reason) {
+        let code = ErrorCode.FILE_NOT_FOUND;
+        if (reason.includes("permission")) {
+            code = ErrorCode.FILE_PERMISSION_DENIED;
+        }
+        else if (reason.includes("exists")) {
+            code = ErrorCode.FILE_ALREADY_EXISTS;
+        }
+        return ErrorHandler.createError(code, `Failed to ${operation} file '${file}': ${reason}`, {
+            file,
+        });
+    }
+}
+/**
+ * Utility function to wrap async operations with error handling
+ */
+export async function withErrorHandling(operation, errorContext = {}) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof HypergenError) {
+            // Add additional context to existing error
+            error.context = { ...error.context, ...errorContext };
+            throw error;
+        }
+        // Convert unknown errors to HypergenError
+        const hypergenError = ErrorHandler.createError(ErrorCode.UNKNOWN_ERROR, error instanceof Error ? error.message : String(error), errorContext);
+        throw hypergenError;
+    }
+}
+/**
+ * Utility function to validate parameters
+ */
+export function validateParameter(name, value, type, required = false, pattern, allowedValues) {
+    if (required && (value === undefined || value === null || value === "")) {
+        throw ErrorHandler.createError(ErrorCode.ACTION_MISSING_REQUIRED_PARAM, `Required parameter '${name}' is missing`, { parameter: name });
+    }
+    if (value !== undefined && value !== null && value !== "") {
+        // Type validation
+        if (type === "string" && typeof value !== "string") {
+            throw ErrorHandler.createParameterError(name, value, "string");
+        }
+        if (type === "number" && typeof value !== "number") {
+            throw ErrorHandler.createParameterError(name, value, "number");
+        }
+        if (type === "boolean" && typeof value !== "boolean") {
+            throw ErrorHandler.createParameterError(name, value, "boolean");
+        }
+        if (type === "array" && !Array.isArray(value)) {
+            throw ErrorHandler.createParameterError(name, value, "array");
+        }
+        // Pattern validation
+        if (pattern && typeof value === "string") {
+            const regex = new RegExp(pattern);
+            if (!regex.test(value)) {
+                throw ErrorHandler.createParameterError(name, value, `string matching pattern ${pattern}`);
+            }
+        }
+        // Allowed values validation
+        if (allowedValues && !allowedValues.includes(value)) {
+            throw ErrorHandler.createParameterError(name, value, `one of: ${allowedValues.join(", ")}`);
+        }
+    }
+}
+//# sourceMappingURL=hypergen-errors.js.map