jamdesk 1.0.0

package/vendored/lib/build/error-parser.ts

@@ -0,0 +1,690 @@
+import type { ErrorDetails } from '../../shared/types.js';
+import { DEPRECATED_COMPONENTS } from '../deprecated-components.js';
+
+/** Format: ERR-XXXXXXXX (first 8 chars of buildId, uppercase) */
+export function generateErrorRef(buildId: string): string {
+  return `ERR-${buildId.substring(0, 8).toUpperCase()}`;
+}
+
+/**
+ * Extract file path from error output using various patterns.
+ * @param pageToFileMap - Optional mapping of URL paths to MDX files
+ */
+export function extractErrorSource(
+  output: string,
+  pageToFileMap?: Record<string, string>
+): {
+  file?: string;
+  line?: number;
+  component?: string;
+} {
+  const result: { file?: string; line?: number; component?: string } = {};
+
+  // Pattern 1: "Error occurred prerendering page "/path""
+  const prerenderMatch = output.match(/Error occurred prerendering page "([^"]+)"/);
+  if (prerenderMatch) {
+    const urlPath = prerenderMatch[1];
+    // Try to map URL path to actual file
+    if (pageToFileMap && pageToFileMap[urlPath]) {
+      result.file = pageToFileMap[urlPath];
+    } else {
+      result.file = urlPath;
+    }
+  }
+
+  // Pattern 2: "Expected component `ComponentName` to be defined"
+  const missingComponentMatch = output.match(/Expected component `(\w+)` to be defined/);
+  if (missingComponentMatch) {
+    result.component = missingComponentMatch[1];
+  }
+
+  // Pattern 2: File path with line number (e.g., "./content/docs/intro.mdx:15:10")
+  const fileLineMatch = output.match(
+    /(?:\.\/|\/)?(?:content\/)?([^\s:]+\.(?:mdx?|tsx?|jsx?)):(\d+)/
+  );
+  if (fileLineMatch) {
+    result.file = result.file || fileLineMatch[1];
+    result.line = parseInt(fileLineMatch[2], 10);
+  }
+
+  // Pattern 3: "in /path/to/file" or "at /path/to/file"
+  const inFileMatch = output.match(
+    /(?:in|at)\s+(?:\.\/|\/)?([^\s:\n]+\.(?:mdx?|tsx?|jsx?))/i
+  );
+  if (inFileMatch && !result.file) {
+    result.file = inFileMatch[1];
+  }
+
+  // Pattern 4: MDX component from build output "components/mdx/ComponentName.tsx"
+  const componentMatch = output.match(/components\/mdx\/(\w+)\.tsx/);
+  if (componentMatch) {
+    result.component = componentMatch[1];
+  }
+
+  // Pattern 5: "Compiling /path/to/page..." followed by error
+  const compilingMatch = output.match(/Compiling\s+([^\s]+\.(?:mdx?|tsx?|jsx?))/);
+  if (compilingMatch && !result.file) {
+    result.file = compilingMatch[1];
+  }
+
+  // Pattern 6: MDX content file from docs directory
+  const docsFileMatch = output.match(/\/docs\/([^\s:\n]+\.mdx?)/);
+  if (docsFileMatch && !result.file) {
+    result.file = docsFileMatch[1];
+  }
+
+  return result;
+}
+
+export function formatErrorLocation(source: {
+  file?: string;
+  line?: number;
+  component?: string;
+}): string {
+  const parts: string[] = [];
+
+  if (source.file) {
+    parts.push(`File: ${source.file}${source.line ? `:${source.line}` : ''}`);
+  }
+  if (source.component) {
+    parts.push(`Component: <${source.component}>`);
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Parse build error output into user-friendly error information.
+ * @param pageToFileMap - Optional mapping of URL paths to MDX files
+ */
+export function parseErrorDetails(
+  output: string,
+  message: string,
+  phase: string,
+  pageToFileMap?: Record<string, string>
+): ErrorDetails {
+  const lowerOutput = output.toLowerCase();
+
+  // Extract error source information upfront - used by multiple error types
+  const errorSource = extractErrorSource(output, pageToFileMap);
+
+  // Configuration validation errors (from validate phase)
+  if (message.includes('Missing docs.json') || message.includes('Invalid docs.json')) {
+    return {
+      type: 'config_error',
+      message: message.split('. ')[0] + '.', // Get first sentence with period
+      details: message,
+      suggestion:
+        'Check your repository has a valid docs.json file in the root directory.\n\n' +
+        'Required fields:\n' +
+        '• "name": Your site name\n' +
+        '• "theme": One of "jam", "nebula", or "pulsar"\n' +
+        '• "colors": { "primary": "#hexcolor" }\n' +
+        '• "navigation": { "anchors": [...] } or { "groups": [...] }\n\n' +
+        'Tip: Use JSON5 format to add comments to your docs.json.\n' +
+        'See https://www.jamdesk.com/docs/configuration for examples.',
+    };
+  }
+
+  // Array navigation format error
+  if (message.includes('Array of groups is not supported')) {
+    return {
+      type: 'config_error',
+      message: 'Array of groups is not supported',
+      details: message,
+      suggestion:
+        'Your docs.json uses an array for navigation.\n\n' +
+        'Please use the hierarchical object format:\n\n' +
+        '// Not supported:\n' +
+        '"navigation": [{ "group": "...", "pages": [...] }]\n\n' +
+        '// Correct format:\n' +
+        '"navigation": {\n' +
+        '  "groups": [{ "group": "Getting Started", "pages": ["intro"] }]\n' +
+        '}\n\n' +
+        'See https://www.jamdesk.com/docs/navigation for details.',
+    };
+  }
+
+  // Navigation configuration error
+  if (
+    output.includes('navigation.map is not a function') ||
+    (output.includes('navigation') && output.includes('is not iterable'))
+  ) {
+    const fileMatch = output.match(/Error occurred prerendering page "([^"]+)"/);
+    const file = fileMatch ? fileMatch[1] : 'unknown page';
+    return {
+      type: 'navigation_config',
+      message: 'Invalid navigation configuration',
+      details:
+        `The navigation structure in your configuration file is malformed. ` +
+        `Error occurred while building: ${file}`,
+      suggestion:
+        'Check your docs.json configuration file. The "navigation" field ' +
+        'must be an object with "anchors", "tabs", or "groups".\n\n' +
+        'Example:\n' +
+        '"navigation": {\n' +
+        '  "anchors": [{ "anchor": "Docs", "groups": [...] }]\n' +
+        '}\n\n' +
+        'See https://www.jamdesk.com/docs/navigation for details.',
+    };
+  }
+
+  // Icon-related errors (LucideIcon casting issues)
+  if (
+    output.includes("Property 'Icon' is incompatible") ||
+    output.includes('LucideIcon') ||
+    (output.includes('lucide-react') && lowerOutput.includes('type error'))
+  ) {
+    // Try to find which icon name caused the issue
+    const iconMatch = output.match(/Property '(\w+)' is incompatible/);
+    const iconName = iconMatch?.[1];
+    const file = errorSource.file;
+    const line = errorSource.line;
+
+    let details = iconName
+      ? `The icon "${iconName}" doesn't exist or is not supported.`
+      : 'One of the icons used in your content is not available.';
+
+    if (file) {
+      const lineInfo = line ? `:${line}` : '';
+      details += `\n\nLocation: ${file}${lineInfo}`;
+    }
+
+    let suggestion = '';
+    if (file) {
+      suggestion = `Check this file: ${file}${line ? `:${line}` : ''}\n\n`;
+    }
+    suggestion +=
+      "Check that you're using a valid icon name.\n\n" +
+      'Icons should be specified in kebab-case, like:\n' +
+      '• icon="arrow-right"\n' +
+      '• icon="check-circle"\n' +
+      '• icon="book-open"\n\n' +
+      'See https://www.jamdesk.com/docs/icons for the full list of available icons.';
+
+    return {
+      type: 'icon_error',
+      message: iconName ? `Icon "${iconName}" is not available` : 'Invalid icon specified',
+      details: details,
+      suggestion: suggestion,
+    };
+  }
+
+  // Component/prop errors (from Next.js build)
+  if (lowerOutput.includes('type error') || output.includes('Type error')) {
+    // Check for missing/invalid props
+    const propertyMatch = output.match(
+      /Property '(\w+)' is missing|Property '(\w+)' does not exist/i
+    );
+
+    const property = propertyMatch?.[1] || propertyMatch?.[2];
+    const component = errorSource.component;
+    const file = errorSource.file;
+    const line = errorSource.line;
+
+    // Determine the user-friendly message
+    let userMessage = 'Build failed due to a configuration issue';
+    let details = "There's an issue with one of the components in your documentation.";
+
+    if (property && component) {
+      userMessage = `Invalid configuration for <${component}> component`;
+      details = `The "${property}" prop is missing or incorrect.`;
+    } else if (property) {
+      userMessage = `Missing or invalid prop: "${property}"`;
+      details = 'A required prop is missing or has an invalid value.';
+    } else if (component) {
+      userMessage = `Issue with <${component}> component`;
+      details = "There's a configuration problem with this component.";
+    }
+
+    // Always include file location if available
+    if (file) {
+      const lineInfo = line ? `:${line}` : '';
+      details += `\n\nLocation: ${file}${lineInfo}`;
+    }
+
+    // Build a helpful suggestion based on what we know
+    let suggestion =
+      'Check your documentation files for:\n' +
+      '• Missing required props on components\n' +
+      '• Typos in component names or props\n' +
+      "• Using components that aren't available\n\n";
+
+    if (file) {
+      suggestion += `Start by checking: ${file}\n\n`;
+    }
+
+    suggestion +=
+      'See https://www.jamdesk.com/docs/components for available components and their usage.';
+
+    return {
+      type: 'component_error',
+      message: userMessage,
+      details: details,
+      suggestion: suggestion,
+    };
+  }
+
+  // Module not found
+  if (lowerOutput.includes('module not found') || lowerOutput.includes('cannot find module')) {
+    const moduleMatch = output.match(
+      /(?:Module not found|Cannot find module)[:\s]+['"]?([^'">\n]+)/i
+    );
+    const moduleName = moduleMatch ? moduleMatch[1] : 'unknown module';
+    return {
+      type: 'module_not_found',
+      message: `Missing dependency: ${moduleName}`,
+      details: `A required module "${moduleName}" could not be found during the build.`,
+      suggestion:
+        'Make sure all dependencies are listed in your package.json. ' +
+        'If using a local import, check that the file path is correct and the file exists.',
+    };
+  }
+
+  // Syntax error in MDX/JSX
+  if (
+    lowerOutput.includes('syntax error') ||
+    lowerOutput.includes('unexpected token') ||
+    lowerOutput.includes('parsing error')
+  ) {
+    const file = errorSource.file || 'your content files';
+    const line = errorSource.line;
+    const lineInfo = line ? ` at line ${line}` : '';
+
+    let suggestion =
+      'Check your MDX files for:\n' +
+      '• Unclosed JSX tags (every <Tag> needs </Tag> or be self-closing)\n' +
+      '• Invalid frontmatter YAML (must be between --- markers)\n' +
+      '• Special characters that need escaping (< > { })';
+
+    if (errorSource.file) {
+      suggestion =
+        `Start by checking: ${errorSource.file}${line ? `:${line}` : ''}\n\n` + suggestion;
+    }
+
+    return {
+      type: 'syntax_error',
+      message: `Syntax error in ${errorSource.file ? errorSource.file : 'content'}`,
+      details:
+        `There's a syntax error${lineInfo} in ${file}. This could be invalid MDX, ` +
+        'unclosed tags, or malformed frontmatter.',
+      suggestion: suggestion,
+    };
+  }
+
+  // MDX compilation error from next-mdx-remote (must be early, before frontmatter check)
+  // Pattern: "[next-mdx-remote] error compiling MDX:" followed by specific error
+  // Examples:
+  //   "Expected a closing tag for `<Blah>` (11:1-11:7)"
+  //   "Expected the closing tag `</Card>`"
+  if (output.includes('[next-mdx-remote]') || output.includes('error compiling MDX')) {
+    // Pattern 1: "Expected a closing tag for `<ComponentName>` (line:col-line:col)"
+    const closingTagForMatch = output.match(
+      /Expected a closing tag for `<(\w+)>`\s*\((\d+):(\d+)/
+    );
+    if (closingTagForMatch) {
+      const tagName = closingTagForMatch[1];
+      const lineNum = parseInt(closingTagForMatch[2], 10);
+      const file = errorSource.file;
+
+      let details = `The <${tagName}> component is missing a closing tag.`;
+      if (file) {
+        details += `\n\nLocation: ${file}:${lineNum}`;
+      } else {
+        details += `\n\nLine: ${lineNum}`;
+      }
+
+      let suggestion = `Add a closing </${tagName}> tag after your content, or make it self-closing <${tagName} />.\n\n`;
+      if (file) {
+        suggestion += `Check: ${file}:${lineNum}\n\n`;
+      }
+      suggestion +=
+        'Common fixes:\n' +
+        `• Add </${tagName}> after the component content\n` +
+        `• Or change <${tagName}> to <${tagName} /> if it has no children\n\n` +
+        'Example:\n' +
+        `  <${tagName}>\n` +
+        '    Your content here\n' +
+        `  </${tagName}>`;
+
+      return {
+        type: 'mdx_syntax_error',
+        message: `Unclosed tag <${tagName}> on line ${lineNum}`,
+        details: details,
+        suggestion: suggestion,
+      };
+    }
+
+    // Pattern 2: Generic MDX error - extract what we can
+    const mdxErrorMatch = output.match(/\[next-mdx-remote\][^:]*:\s*([^\n]+)/);
+    if (mdxErrorMatch) {
+      const errorText = mdxErrorMatch[1].trim();
+      const lineMatch = errorText.match(/\((\d+):\d+/);
+      const lineNum = lineMatch ? parseInt(lineMatch[1], 10) : errorSource.line;
+      const file = errorSource.file;
+
+      let details = errorText;
+      if (file) {
+        const lineInfo = lineNum ? `:${lineNum}` : '';
+        details += `\n\nLocation: ${file}${lineInfo}`;
+      } else if (lineNum) {
+        details += `\n\nLine: ${lineNum}`;
+      }
+
+      let suggestion =
+        'Check your MDX syntax:\n' +
+        '• Every opening tag needs a closing tag (e.g., <Note>...</Note>)\n' +
+        '• Self-closing tags need a slash (e.g., <Icon name="star" />)\n' +
+        '• Curly braces { } must be properly closed';
+      if (file) {
+        suggestion = `Check: ${file}${lineNum ? `:${lineNum}` : ''}\n\n` + suggestion;
+      }
+
+      return {
+        type: 'mdx_syntax_error',
+        message: lineNum ? `MDX syntax error on line ${lineNum}` : 'MDX syntax error',
+        details: details,
+        suggestion: suggestion,
+      };
+    }
+  }
+
+  // Unclosed JSX tag error (alternative pattern)
+  // Pattern: "Expected the closing tag `</ComponentName>`"
+  const unclosedTagMatch = output.match(/Expected the closing tag `<\/(\w+)>`/);
+  if (unclosedTagMatch) {
+    const tagName = unclosedTagMatch[1];
+    const file = errorSource.file;
+    const line = errorSource.line;
+
+    let details = `The <${tagName}> component is not properly closed.`;
+    if (file) {
+      const lineInfo = line ? `:${line}` : '';
+      details += `\n\nLocation: ${file}${lineInfo}`;
+    }
+
+    let suggestion = `Add a closing </${tagName}> tag or make it self-closing <${tagName} />.\n\n`;
+    if (file) {
+      suggestion += `Check this file: ${file}${line ? `:${line}` : ''}\n\n`;
+    }
+    suggestion +=
+      'Common causes:\n' +
+      '• Missing closing tag\n' +
+      '• Markdown lists inside JSX components can break parsing\n' +
+      '• Mismatched opening and closing tags';
+
+    return {
+      type: 'mdx_syntax_error',
+      message: `Unclosed tag: <${tagName}>`,
+      details: details,
+      suggestion: suggestion,
+    };
+  }
+
+  // React hook error in inline components
+  // Pattern: "useState is not defined" or similar for any React hook
+  // These errors occur when someone tries to use hooks in inline MDX components
+  const hookErrorMatch = output.match(
+    /\b(useState|useEffect|useContext|useReducer|useCallback|useMemo|useRef|useImperativeHandle|useLayoutEffect|useDebugValue|useDeferredValue|useTransition|useId|useSyncExternalStore|useInsertionEffect)\b[^a-zA-Z0-9_]*is not defined/i
+  );
+  if (hookErrorMatch) {
+    const hookName = hookErrorMatch[1];
+    const file = errorSource.file;
+    const line = errorSource.line;
+
+    let details =
+      `The React hook "${hookName}" cannot be used in inline MDX components. ` +
+      `Inline components are server-rendered during build, and React hooks only work client-side.`;
+    if (file) {
+      const lineInfo = line ? `:${line}` : '';
+      details += `\n\nLocation: ${file}${lineInfo}`;
+    }
+
+    let suggestion =
+      'Inline MDX components (export const MyComponent = ...) cannot use React hooks.\n\n' +
+      '**Solution: Convert to a snippet file**\n\n' +
+      '1. Create a file in /snippets directory (e.g., /snippets/my-component.tsx)\n' +
+      '2. Add \'use client\'; at the top of the file\n' +
+      '3. Import and use the component in your MDX\n\n' +
+      'Example snippet file:\n' +
+      '```tsx\n' +
+      '\'use client\';\n' +
+      `import { ${hookName} } from 'react';\n\n` +
+      'export const MyComponent = () => {\n' +
+      `  const [...] = ${hookName}(...);\n` +
+      '  return <div>...</div>;\n' +
+      '};\n' +
+      '```\n\n' +
+      'Then import in your MDX:\n' +
+      '```mdx\n' +
+      'import { MyComponent } from \'/snippets/my-component\';\n' +
+      '```\n\n' +
+      '**Automatic fix:** Run `jamdesk migrate` to automatically convert hook-using components to snippets.\n\n' +
+      'See https://jamdesk.com/docs/content/react-components for details.';
+
+    if (file) {
+      suggestion = `Check this file: ${file}${line ? `:${line}` : ''}\n\n` + suggestion;
+    }
+
+    return {
+      type: 'react_hook_error',
+      message: `React hook "${hookName}" not allowed in inline components`,
+      details: details,
+      suggestion: suggestion,
+    };
+  }
+
+  // Deprecated components (uses shared DEPRECATED_COMPONENTS map)
+  // Pattern: "Expected component `ComponentName` to be defined"
+  for (const [componentName, info] of Object.entries(DEPRECATED_COMPONENTS)) {
+    if (output.includes(`Expected component \`${componentName}\` to be defined`)) {
+      const file = errorSource.file;
+      const line = errorSource.line;
+
+      let details = `The <${componentName}> component has been removed.`;
+      if (file) {
+        const lineInfo = line ? `:${line}` : '';
+        details += `\n\nLocation: ${file}${lineInfo}`;
+      }
+
+      let suggestion = `${info.migrationHint}\n\n`;
+      suggestion += 'Run `jamdesk migrate` to fix your source files, or use "Fix & Rebuild" in the dashboard to deploy immediately.';
+      if (file) {
+        suggestion = `Check this file: ${file}${line ? `:${line}` : ''}\n\n` + suggestion;
+      }
+
+      return {
+        type: 'deprecated_component',
+        message: `<${componentName}> has been removed — use <${info.replacement}> instead`,
+        details,
+        suggestion,
+      };
+    }
+  }
+
+  // Missing MDX component error (must be before frontmatter check)
+  // Pattern: "Expected component `ComponentName` to be defined"
+  const missingComponentMatch2 = output.match(/Expected component `(\w+)` to be defined/);
+  if (missingComponentMatch2) {
+    const componentName = missingComponentMatch2[1];
+    const file = errorSource.file;
+    const line = errorSource.line;
+
+    // Built-in component names that are known to Jamdesk
+    const builtInComponents = [
+      'Note',
+      'Tip',
+      'Info',
+      'Warning',
+      'Check',
+      'Danger',
+      'Card',
+      'Columns',
+      'Tabs',
+      'Tab',
+      'Steps',
+      'Step',
+      'CodeGroup',
+      'ParamField',
+      'ResponseField',
+      'Expandable',
+      'Frame',
+      'Icon',
+      'Accordion',
+      'AccordionGroup',
+      'Badge',
+    ];
+
+    // Check if this might be an inline component (PascalCase but not a built-in)
+    const isPascalCase = /^[A-Z][a-zA-Z0-9]*$/.test(componentName);
+    const isBuiltIn = builtInComponents.includes(componentName);
+    const isLikelyInlineComponent = isPascalCase && !isBuiltIn;
+
+    let details = `The component <${componentName}> is not available.`;
+    if (file) {
+      const lineInfo = line ? `:${line}` : '';
+      details += `\n\nLocation: ${file}${lineInfo}`;
+    }
+
+    let suggestion = '';
+    if (isLikelyInlineComponent) {
+      // Suggest inline component syntax for custom components
+      suggestion =
+        `If you're defining <${componentName}> as an inline component, add this to the top of your MDX file:\n\n` +
+        `\`\`\`jsx\n` +
+        `export const ${componentName} = ({ /* props */ }) => (\n` +
+        `  <div>Your component content</div>\n` +
+        `);\n` +
+        `\`\`\`\n\n` +
+        'Check that:\n' +
+        '• The export syntax is correct: `export const ComponentName = ({ props }) => ...`\n' +
+        '• The component uses valid JSX\n' +
+        '• There are no syntax errors in the component code\n\n';
+      if (file) {
+        suggestion += `Check this file: ${file}${line ? `:${line}` : ''}\n\n`;
+      }
+      suggestion += 'See https://www.jamdesk.com/docs/react-components for inline component documentation.';
+    } else {
+      // Standard suggestion for built-in components
+      suggestion = `The <${componentName}> component is not available in Jamdesk.\n\n`;
+      if (file) {
+        suggestion += `Check this file: ${file}${line ? `:${line}` : ''}\n\n`;
+      }
+      suggestion +=
+        'Supported components include:\n' +
+        '• Callouts: <Note>, <Tip>, <Info>, <Warning>, <Check>, <Danger>\n' +
+        '• Layout: <Card>, <Columns>, <Tabs>, <Tab>, <Steps>, <Step>\n' +
+        '• Code: <CodeGroup>\n' +
+        '• API docs: <ParamField>, <ResponseField>, <Expandable>\n' +
+        '• Media: <Frame>, <Icon>\n\n' +
+        'See https://www.jamdesk.com/docs/components for the full list of available components.';
+    }
+
+    return {
+      type: 'missing_component',
+      message: `Unsupported component: <${componentName}>`,
+      details: details,
+      suggestion: suggestion,
+    };
+  }
+
+  // Frontmatter/YAML error
+  if (
+    lowerOutput.includes('yaml') ||
+    lowerOutput.includes('frontmatter') ||
+    lowerOutput.includes('unexpected end of file')
+  ) {
+    const file = errorSource.file;
+    const line = errorSource.line;
+
+    let details =
+      'One or more of your MDX files has a syntax error in the metadata section at the top of the file.';
+    if (file) {
+      const lineInfo = line ? ` on line ${line}` : '';
+      details = `The file ${file} has a syntax error in the metadata section${lineInfo}.`;
+    }
+
+    let suggestion = '';
+    if (file) {
+      suggestion = `Check this file: ${file}${line ? `:${line}` : ''}\n\n`;
+    }
+    suggestion +=
+      'Check the metadata at the top of your MDX file (the section between --- markers). ' +
+      'Common issues:\n' +
+      '• Missing closing --- marker\n' +
+      '• Incorrect formatting (check indentation, colons, quotes)\n' +
+      '• Special characters that need to be quoted';
+
+    return {
+      type: 'frontmatter_error',
+      message: file ? `Metadata error in ${file}` : 'File metadata error',
+      details: details,
+      suggestion: suggestion,
+    };
+  }
+
+  // Build timeout
+  if (lowerOutput.includes('timeout') || lowerOutput.includes('timed out')) {
+    return {
+      type: 'timeout',
+      message: 'Build timed out',
+      details: 'The build process took too long and was terminated.',
+      suggestion:
+        'This can happen with very large documentation sites. ' +
+        'Try reducing the number of pages or simplifying complex MDX components.',
+    };
+  }
+
+  // Out of memory
+  if (
+    lowerOutput.includes('out of memory') ||
+    lowerOutput.includes('heap') ||
+    lowerOutput.includes('allocation failed')
+  ) {
+    return {
+      type: 'out_of_memory',
+      message: 'Build ran out of memory',
+      details: 'The build process exceeded available memory.',
+      suggestion:
+        'This can happen with very large documentation sites or complex builds. ' +
+        'Try reducing the number of pages or optimizing images.',
+    };
+  }
+
+  // Clone failure
+  if (phase === 'clone' || lowerOutput.includes('clone')) {
+    return {
+      type: 'clone_failed',
+      message: 'Failed to clone repository',
+      details: 'Could not clone your GitHub repository.',
+      suggestion:
+        'Check that:\n' +
+        '• The repository exists and is accessible\n' +
+        '• The Jamdesk GitHub App has access to the repository\n' +
+        '• The branch name is correct',
+    };
+  }
+
+  // Default error - still include file location if we found one
+  let details = message || 'An error occurred during the build process.';
+  if (errorSource.file) {
+    const lineInfo = errorSource.line ? `:${errorSource.line}` : '';
+    details += `\n\nLocation: ${errorSource.file}${lineInfo}`;
+  }
+
+  let suggestion =
+    'Please review the error details and try again. ' +
+    'If the problem persists, check your repository configuration.';
+  if (errorSource.file) {
+    suggestion =
+      `Check this file: ${errorSource.file}${errorSource.line ? `:${errorSource.line}` : ''}\n\n` +
+      suggestion;
+  }
+
+  return {
+    type: 'build_error',
+    message: 'Build failed',
+    details: details,
+    suggestion: suggestion,
+  };
+}