@timber-js/app 0.2.0-alpha.84 → 0.2.0-alpha.85

package/src/plugins/dev-terminal-error.ts

@@ -0,0 +1,217 @@
+/**
+ * Terminal error formatting — boxed, color-coded error output for dev mode.
+ *
+ * Produces a visually scannable error block with:
+ * - Unicode box-drawing border around the error
+ * - Phase badge and error message
+ * - First app frame highlighted as the primary action item
+ * - OSC 8 clickable file:line links (VSCode terminal, iTerm2, etc.)
+ * - Internal/framework frames collapsed with a count
+ * - Component stack (for React render errors)
+ *
+ * Dev-only: this module is only imported by dev-error-overlay.ts.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import { pathToFileURL } from 'node:url';
+import {
+  classifyFrame,
+  extractComponentStack,
+  parseFirstAppFrame,
+  PHASE_LABELS,
+  type ErrorPhase,
+  type FrameType,
+} from './dev-error-overlay.js';
+
+// ─── ANSI Codes ─────────────────────────────────────────────────────────────
+
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const UNDERLINE = '\x1b[4m';
+
+// ─── OSC 8 Hyperlinks ──────────────────────────────────────────────────────
+
+/**
+ * Wrap text in an OSC 8 hyperlink escape sequence.
+ *
+ * Terminals that support OSC 8 (VSCode, iTerm2, Windows Terminal, etc.)
+ * render this as a clickable link. Others ignore the escape sequences
+ * and show the text normally.
+ *
+ * Format: \x1b]8;;URL\x07TEXT\x1b]8;;\x07
+ */
+function hyperlink(text: string, url: string): string {
+  return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+
+/**
+ * Format a file:line:col reference as a clickable terminal link.
+ *
+ * Uses file:// URLs so terminals open the file in the configured editor.
+ * The link text is styled with cyan + underline for visibility.
+ */
+function fileLink(filePath: string, line?: number, col?: number): string {
+  const display = line ? `${filePath}:${line}${col ? `:${col}` : ''}` : filePath;
+  // Use pathToFileURL for proper encoding of spaces, #, ?, and Windows
+  // drive letters (TIM-792). Append :line:col after the URL.
+  const base = pathToFileURL(filePath).href;
+  const url = line ? `${base}:${line}${col ? `:${col}` : ''}` : base;
+  return `${CYAN}${UNDERLINE}${hyperlink(display, url)}${RESET}`;
+}
+
+// ─── Box Drawing ────────────────────────────────────────────────────────────
+
+const BOX = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '─',
+  vertical: '│',
+};
+
+/**
+ * Wrap lines of text in a Unicode box with a colored left border.
+ *
+ * @param lines - Content lines (no ANSI length calculation — keeps it simple)
+ * @param width - Box width (characters). Lines longer than this are not truncated.
+ */
+function box(lines: string[], borderColor: string, width = 80): string {
+  const bar = BOX.horizontal.repeat(width - 2);
+  const output: string[] = [];
+
+  output.push(`${borderColor}${BOX.topLeft}${bar}${BOX.topRight}${RESET}`);
+  for (const line of lines) {
+    output.push(`${borderColor}${BOX.vertical}${RESET} ${line}`);
+  }
+  output.push(`${borderColor}${BOX.bottomLeft}${bar}${BOX.bottomRight}${RESET}`);
+
+  return output.join('\n');
+}
+
+// ─── Frame Extraction ───────────────────────────────────────────────────────
+
+interface ClassifiedFrame {
+  raw: string;
+  type: FrameType;
+  file?: string;
+  line?: number;
+  col?: number;
+}
+
+/** Parse file/line/col from a stack frame line. */
+function parseFrame(frameLine: string): { file?: string; line?: number; col?: number } {
+  const parenMatch = /\(([^)]+):(\d+):(\d+)\)/.exec(frameLine);
+  if (parenMatch) {
+    return { file: parenMatch[1], line: Number(parenMatch[2]), col: Number(parenMatch[3]) };
+  }
+  const bareMatch = /at (\/[^:]+):(\d+):(\d+)/.exec(frameLine);
+  if (bareMatch) {
+    return { file: bareMatch[1], line: Number(bareMatch[2]), col: Number(bareMatch[3]) };
+  }
+  return {};
+}
+
+function classifyFrames(stack: string, projectRoot: string): ClassifiedFrame[] {
+  return stack
+    .split('\n')
+    .slice(1)
+    .filter((l) => l.trim().startsWith('at '))
+    .map((raw) => {
+      const type = classifyFrame(raw, projectRoot);
+      const { file, line, col } = parseFrame(raw);
+      return { raw, type, file, line, col };
+    });
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Format an error for terminal output with a boxed layout.
+ *
+ * The output is designed to be scannable at a glance:
+ * 1. Red box with phase badge and error message
+ * 2. First app frame as a clickable link (the primary action item)
+ * 3. App frames listed normally
+ * 4. Internal/framework frames collapsed with count
+ * 5. Component stack (if present)
+ */
+export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string {
+  const sections: string[] = [];
+  const componentStack = extractComponentStack(error);
+  const loc = parseFirstAppFrame(error.stack ?? '', projectRoot);
+  const frames = error.stack ? classifyFrames(error.stack, projectRoot) : [];
+  const appFrames = frames.filter((f) => f.type === 'app');
+  const internalCount = frames.filter((f) => f.type !== 'app').length;
+
+  // ── Box: Phase + Message ──────────────────────────────────────────
+  const boxLines: string[] = [];
+  boxLines.push(`${RED}${BOLD}${PHASE_LABELS[phase]} Error${RESET}`);
+  boxLines.push('');
+
+  // Error message — may be multi-line
+  for (const msgLine of error.message.split('\n')) {
+    boxLines.push(`${RED}${msgLine}${RESET}`);
+  }
+
+  // Primary file location (clickable)
+  if (loc) {
+    boxLines.push('');
+    const relPath = loc.file.startsWith(projectRoot)
+      ? loc.file.slice(projectRoot.length + 1)
+      : loc.file;
+    boxLines.push(
+      `${BOLD}→${RESET} ${fileLink(loc.file, loc.line, loc.column)} ${DIM}(${relPath})${RESET}`
+    );
+  }
+
+  sections.push(box(boxLines, RED));
+
+  // ── Component Stack ───────────────────────────────────────────────
+  if (componentStack) {
+    sections.push('');
+    sections.push(`  ${BOLD}Component Stack:${RESET}`);
+    for (const csLine of componentStack.trim().split('\n')) {
+      sections.push(`  ${DIM}${csLine.trim()}${RESET}`);
+    }
+  }
+
+  // ── App Frames ────────────────────────────────────────────────────
+  if (appFrames.length > 0) {
+    sections.push('');
+    sections.push(`  ${BOLD}Application Frames:${RESET}`);
+    for (let i = 0; i < appFrames.length; i++) {
+      const f = appFrames[i]!;
+      if (f.file && f.line) {
+        const prefix = i === 0 ? `${BOLD}▸${RESET}` : ' ';
+        sections.push(
+          `  ${prefix} ${fileLink(f.file, f.line, f.col)} ${DIM}${extractFnName(f.raw)}${RESET}`
+        );
+      } else {
+        sections.push(`  ${f.raw}`);
+      }
+    }
+  }
+
+  // ── Internal Frames (collapsed) ───────────────────────────────────
+  if (internalCount > 0) {
+    sections.push(
+      `  ${DIM}… ${internalCount} internal frame${internalCount !== 1 ? 's' : ''} hidden${RESET}`
+    );
+  }
+
+  sections.push('');
+  return sections.join('\n');
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Extract the function name from a stack frame line like "    at fnName (/path:1:2)". */
+function extractFnName(frameLine: string): string {
+  const match = /at\s+(\S+)\s+\(/.exec(frameLine.trim());
+  return match ? match[1]! : '';
+}

package/src/plugins/entries.ts

@@ -117,6 +117,9 @@ function generateConfigModule(ctx: PluginContext): string {
     // Per-build deployment ID for version skew detection (TIM-446).
     // Null in dev mode — HMR handles code updates without full reloads.
     deploymentId: ctx.deploymentId ?? null,
+    // Note: project root is NOT included here — it was leaking server
+    // filesystem paths to client bundles (TIM-787). Dev error pages get
+    // the root through the dev server, not the runtime config.
   };
 
   return [

package/src/plugins/fonts.ts

@@ -84,11 +84,12 @@ function familyToClassName(family: string): string {
 /**
  * Generate a unique font ID from family + config hash.
  */
-function generateFontId(family: string, config: GoogleFontConfig): string {
+export function generateFontId(family: string, config: GoogleFontConfig): string {
   const weights = normalizeToArray(config.weight);
   const styles = normalizeToArray(config.style);
   const subsets = config.subsets ?? ['latin'];
-  return `${family.toLowerCase()}-${weights.join(',')}-${styles.join(',')}-${subsets.join(',')}`;
+  const display = config.display ?? 'swap';
+  return `${family.toLowerCase()}-${weights.join(',')}-${styles.join(',')}-${subsets.join(',')}-${display}`;
 }
 
 /**

package/src/plugins/routing.ts

@@ -18,6 +18,11 @@ import {
   lintStatusFileDirectives,
   formatStatusFileLintWarnings,
 } from '../routing/status-file-lint.js';
+import {
+  lintConventions,
+  checkAppDirExists,
+  formatConventionWarnings,
+} from '../routing/convention-lint.js';
 import type { RouteTree, SegmentNode, RouteFile } from '../routing/types.js';
 import type { PluginContext } from '../plugin-context.js';
 
@@ -83,6 +88,24 @@ export function timberRouting(ctx: PluginContext): Plugin {
   const warnedFiles = new Set<string>();
 
   function rescan(): void {
+    // Check app/ directory exists before scanning
+    const appDirWarning = checkAppDirExists(ctx.appDir);
+    if (appDirWarning) {
+      const formatted = formatConventionWarnings([appDirWarning]);
+      if (formatted) process.stderr.write(`${formatted}\n`);
+      // Still create an empty tree so the rest of the pipeline doesn't crash
+      ctx.routeTree = {
+        root: {
+          segmentName: '',
+          segmentType: 'static',
+          urlPath: '/',
+          children: [],
+          slots: new Map(),
+        },
+      };
+      return;
+    }
+
     ctx.timer.start('route-scan');
     ctx.routeTree = scanRoutes(ctx.appDir, {
       pageExtensions: ctx.config.pageExtensions,
@@ -91,11 +114,20 @@ export function timberRouting(ctx: PluginContext): Plugin {
     writeCodegen(ctx);
 
     // Lint status files for missing 'use client' directive
-    const warnings = lintStatusFileDirectives(ctx.routeTree);
-    const newWarnings = warnings.filter((w) => !warnedFiles.has(w.filePath));
-    if (newWarnings.length > 0) {
-      for (const w of newWarnings) warnedFiles.add(w.filePath);
-      console.warn(formatStatusFileLintWarnings(newWarnings));
+    const statusWarnings = lintStatusFileDirectives(ctx.routeTree);
+    const newStatusWarnings = statusWarnings.filter((w) => !warnedFiles.has(w.filePath));
+    if (newStatusWarnings.length > 0) {
+      for (const w of newStatusWarnings) warnedFiles.add(w.filePath);
+      console.warn(formatStatusFileLintWarnings(newStatusWarnings));
+    }
+
+    // Lint conventions (empty app, missing methods, missing root layout)
+    const conventionWarnings = lintConventions(ctx.routeTree, ctx.appDir);
+    const newConventionWarnings = conventionWarnings.filter((w) => !warnedFiles.has(w.id));
+    if (newConventionWarnings.length > 0) {
+      for (const w of newConventionWarnings) warnedFiles.add(w.id);
+      const formatted = formatConventionWarnings(newConventionWarnings);
+      if (formatted) process.stderr.write(`${formatted}\n`);
     }
   }
 

package/src/routing/convention-lint.ts

@@ -0,0 +1,356 @@
+/**
+ * Convention linter — validates common misconfigurations in the route tree.
+ *
+ * Runs at scan time (build and dev startup). Each check produces a warning
+ * with the file path, what's wrong, and what to do about it.
+ *
+ * These are warnings, not errors — they don't block the build. The goal is
+ * to catch issues that would otherwise produce cryptic runtime behavior
+ * (silent 404s, empty pages, confusing React errors).
+ *
+ * Design doc: 07-routing.md, 10-error-handling.md
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import type { RouteTree, SegmentNode } from './types.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ConventionWarning {
+  /** Warning ID for deduplication and filtering. */
+  id: string;
+  /** Human-readable single-line summary. */
+  summary: string;
+  /** Multi-line details with file path and fix suggestion. */
+  details: string;
+  /** Severity: 'warn' for potential issues, 'error' for definite misconfigurations. */
+  level: 'warn' | 'error';
+}
+
+// ─── Lint Rules ─────────────────────────────────────────────────────────────
+
+/**
+ * Run all convention lint checks on a route tree.
+ *
+ * Returns an array of warnings. Empty array means everything looks good.
+ */
+export function lintConventions(tree: RouteTree, appDir: string): ConventionWarning[] {
+  const warnings: ConventionWarning[] = [];
+
+  // Check 1: app/ directory exists (caller should check before scanning,
+  // but we validate the root has at least one routable file)
+  checkEmptyApp(tree.root, appDir, warnings);
+
+  // Check 2: route.ts without recognized HTTP method exports
+  checkRouteExports(tree.root, warnings);
+
+  // Check 3: Segments with layout but no page/route anywhere in subtree
+  // (not a misconfiguration per se — layouts without pages are valid for
+  // route groups. Skip this check.)
+
+  // Check 4: Root segment has no layout.tsx (no HTML shell)
+  checkRootLayout(tree.root, warnings);
+
+  // Check 5: page.tsx / layout.tsx without default export
+  checkDefaultExports(tree.root, warnings);
+
+  return warnings;
+}
+
+// ─── Check: Empty App ───────────────────────────────────────────────────────
+
+/**
+ * Warn when the app/ directory has no routable files at all.
+ *
+ * This catches the "I created app/ but didn't add any pages" case where
+ * every request silently 404s with no guidance.
+ */
+function checkEmptyApp(root: SegmentNode, appDir: string, warnings: ConventionWarning[]): void {
+  if (hasAnyRoutable(root)) return;
+
+  warnings.push({
+    id: 'EMPTY_APP',
+    summary: 'No pages or route handlers found in app/',
+    details:
+      `  Directory: ${appDir}\n\n` +
+      '  Your app/ directory has no page.tsx or route.ts files.\n' +
+      '  Every request will return 404.\n\n' +
+      '  To fix: Create app/page.tsx with a default export:\n\n' +
+      '    export default function Home() {\n      return <h1>Hello</h1>;\n    }\n',
+    level: 'warn',
+  });
+}
+
+/**
+ * Check if a segment tree has any routable files (page or route) anywhere.
+ */
+function hasAnyRoutable(node: SegmentNode): boolean {
+  if (node.page || node.route) return true;
+  for (const child of node.children) {
+    if (hasAnyRoutable(child)) return true;
+  }
+  for (const [, slot] of node.slots) {
+    if (hasAnyRoutable(slot)) return true;
+  }
+  return false;
+}
+
+/**
+ * Check if a segment tree has any page files (not just route handlers).
+ * Used by checkRootLayout to avoid false positives for API-only apps (TIM-794).
+ * API-only apps (just route.ts handlers) don't need a root layout.
+ */
+function hasAnyPage(node: SegmentNode): boolean {
+  if (node.page) return true;
+  for (const child of node.children) {
+    if (hasAnyPage(child)) return true;
+  }
+  for (const [, slot] of node.slots) {
+    if (hasAnyPage(slot)) return true;
+  }
+  return false;
+}
+
+// ─── Check: Route Exports ───────────────────────────────────────────────────
+
+/** HTTP methods that route.ts can export. */
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+
+/**
+ * Pattern to detect named exports that look like HTTP method handlers.
+ * Matches: export function GET, export const GET, export async function POST, etc.
+ * Also matches: export { GET } or re-exports like export { GET } from './handler'.
+ *
+ * The re-export branch uses word boundaries (\b) around method names to avoid
+ * matching substrings (e.g. TARGET should not match GET). See TIM-795.
+ */
+const EXPORT_PATTERN = new RegExp(
+  `export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+(${HTTP_METHODS.join('|')})\\b` +
+    `|export\\s*\\{[^}]*\\b(${HTTP_METHODS.join('|')})\\b[^}]*\\}`
+);
+
+/**
+ * Warn when a route.ts file doesn't appear to export any recognized HTTP methods.
+ *
+ * Uses static analysis (regex on source text) — not module loading.
+ * This is intentionally conservative: it may miss complex re-exports but
+ * catches the common case of an empty route.ts or one with wrong export names.
+ */
+function checkRouteExports(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.route) {
+    const filePath = node.route.filePath;
+    try {
+      const source = readFileSync(filePath, 'utf-8');
+      if (!EXPORT_PATTERN.test(source)) {
+        // Check if there's a default export (common mistake)
+        const hasDefaultExport = /export\s+default\b/.test(source);
+        const hint = hasDefaultExport
+          ? '  It looks like you have a default export. route.ts uses named exports\n' +
+            '  for HTTP methods (GET, POST, etc.), not a default export.\n'
+          : '';
+
+        warnings.push({
+          id: 'ROUTE_NO_METHODS',
+          summary: `route.ts has no HTTP method exports: ${filePath}`,
+          details:
+            `  File: ${filePath}\n\n` +
+            '  route.ts files must export named HTTP method handlers.\n' +
+            '  Without them, the route matches but returns 405 Method Not Allowed.\n\n' +
+            hint +
+            '  Example:\n\n' +
+            '    export function GET(ctx: RouteContext) {\n' +
+            "      return Response.json({ hello: 'world' });\n" +
+            '    }\n',
+          level: 'warn',
+        });
+      }
+    } catch {
+      // Can't read the file — skip silently
+    }
+  }
+
+  // Recurse
+  for (const child of node.children) {
+    checkRouteExports(child, warnings);
+  }
+  for (const [, slot] of node.slots) {
+    checkRouteExports(slot, warnings);
+  }
+}
+
+// ─── Check: Root Layout ─────────────────────────────────────────────────────
+
+/**
+ * Warn when the root segment has no layout.tsx.
+ *
+ * Without a root layout, there's no HTML shell (<html>, <body>).
+ * The page will render but may have hydration issues or no proper document structure.
+ */
+function checkRootLayout(root: SegmentNode, warnings: ConventionWarning[]): void {
+  if (root.layout) return;
+
+  // Only warn if there are pages — API-only apps (just route.ts handlers)
+  // don't need a root layout (TIM-794).
+  if (!hasAnyPage(root)) return;
+
+  warnings.push({
+    id: 'NO_ROOT_LAYOUT',
+    summary: 'No root layout.tsx found',
+    details:
+      '  Your app has pages but no root layout.\n' +
+      '  Without app/layout.tsx, pages have no <html> or <body> wrapper.\n\n' +
+      '  To fix: Create app/layout.tsx:\n\n' +
+      '    export default function RootLayout({ children }: { children: React.ReactNode }) {\n' +
+      '      return (\n' +
+      '        <html lang="en">\n' +
+      '          <body>{children}</body>\n' +
+      '        </html>\n' +
+      '      );\n' +
+      '    }\n',
+    level: 'warn',
+  });
+}
+
+// ─── Check: Default Exports ───────────────────────────────────────────
+
+/**
+ * Pattern to detect a default export in source code.
+ * Matches: export default function, export default class, export default
+ * Also matches: export { X as default }, export { default } from './Impl'
+ *
+ * The third alternative catches bare `default` re-exports (TIM-790).
+ * The negative lookahead (?!\s+as\b) prevents matching `export { default as X }`
+ * which is a named export, not a default export (TIM-806).
+ */
+const DEFAULT_EXPORT_PATTERN =
+  /export\s+default\b|export\s*\{[^}]*\bas\s+default\b|export\s*\{[^}]*\bdefault\b(?!\s+as\b)[^}]*\}/;
+
+/**
+ * Warn when page.tsx or layout.tsx files don't have a default export.
+ *
+ * Without a default export:
+ * - page.tsx: the page renders nothing (empty content)
+ * - layout.tsx: the layout module loads but has no component to render
+ *
+ * Uses static analysis (regex on source text) — intentionally conservative.
+ */
+function checkDefaultExports(node: SegmentNode, warnings: ConventionWarning[]): void {
+  // Check page files (tsx/ts/jsx/js only — not mdx, which is default-exported by the mdx compiler)
+  if (node.page && isScriptExtension(node.page.extension)) {
+    checkFileDefaultExport(node.page.filePath, 'page', warnings);
+  }
+
+  // Check layout files
+  if (node.layout && isScriptExtension(node.layout.extension)) {
+    checkFileDefaultExport(node.layout.filePath, 'layout', warnings);
+  }
+
+  // Recurse
+  for (const child of node.children) {
+    checkDefaultExports(child, warnings);
+  }
+  for (const [, slot] of node.slots) {
+    checkDefaultExports(slot, warnings);
+  }
+}
+
+function isScriptExtension(ext: string): boolean {
+  return ext === 'tsx' || ext === 'ts' || ext === 'jsx' || ext === 'js';
+}
+
+function checkFileDefaultExport(
+  filePath: string,
+  fileType: string,
+  warnings: ConventionWarning[]
+): void {
+  try {
+    const source = readFileSync(filePath, 'utf-8');
+    if (!DEFAULT_EXPORT_PATTERN.test(source)) {
+      warnings.push({
+        id: `NO_DEFAULT_EXPORT:${filePath}`,
+        summary: `${fileType}.tsx has no default export: ${filePath}`,
+        details:
+          `  File: ${filePath}\n\n` +
+          `  ${fileType}.tsx files must export a default React component.\n` +
+          `  Without a default export, the ${fileType === 'page' ? 'page renders nothing' : 'layout has no component to wrap children'}.\n\n` +
+          `  To fix: Add a default export:\n\n` +
+          `    export default function My${fileType === 'page' ? 'Page' : 'Layout'}(${fileType === 'layout' ? '{ children }' : ''}) {\n` +
+          `      return ${fileType === 'layout' ? '<div>{children}</div>' : '<h1>Hello</h1>'};\n` +
+          `    }\n`,
+        level: 'warn',
+      });
+    }
+  } catch {
+    // Can't read file — skip silently
+  }
+}
+
+// ─── Check: App Directory Exists ────────────────────────────────────────────
+
+/**
+ * Check if the app/ directory exists. Called before scanning.
+ * Returns a warning if missing, or null if the directory exists.
+ */
+export function checkAppDirExists(appDir: string): ConventionWarning | null {
+  if (existsSync(appDir)) return null;
+
+  return {
+    id: 'NO_APP_DIR',
+    summary: 'No app/ directory found',
+    details:
+      `  Expected: ${appDir}\n\n` +
+      '  timber.js requires an app/ directory for file-system routing.\n' +
+      '  Every request will return 404 until you create it.\n\n' +
+      '  To fix: Create the app/ directory with a page:\n\n' +
+      '    mkdir -p app\n' +
+      '    # Create app/layout.tsx and app/page.tsx\n',
+    level: 'error',
+  };
+}
+
+// ─── Formatting ─────────────────────────────────────────────────────────────
+
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * Format warnings for terminal output.
+ *
+ * Groups by severity, uses colors, and includes fix suggestions.
+ */
+export function formatConventionWarnings(warnings: ConventionWarning[]): string {
+  if (warnings.length === 0) return '';
+
+  const errors = warnings.filter((w) => w.level === 'error');
+  const warns = warnings.filter((w) => w.level === 'warn');
+
+  const lines: string[] = [];
+
+  if (errors.length > 0) {
+    lines.push(
+      `${RED}${BOLD}[timber]${RESET} ${RED}${errors.length} configuration error${errors.length !== 1 ? 's' : ''}:${RESET}`
+    );
+    for (const e of errors) {
+      lines.push('');
+      lines.push(`  ${RED}✗${RESET} ${e.summary}`);
+      lines.push(`${DIM}${e.details}${RESET}`);
+    }
+  }
+
+  if (warns.length > 0) {
+    if (errors.length > 0) lines.push('');
+    lines.push(
+      `${YELLOW}${BOLD}[timber]${RESET} ${YELLOW}${warns.length} configuration warning${warns.length !== 1 ? 's' : ''}:${RESET}`
+    );
+    for (const w of warns) {
+      lines.push('');
+      lines.push(`  ${YELLOW}⚠${RESET} ${w.summary}`);
+      lines.push(`${DIM}${w.details}${RESET}`);
+    }
+  }
+
+  return lines.join('\n');
+}