@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.150

package/src/dev-tools/404-page.ts

@@ -0,0 +1,286 @@
+/**
+ * Dev 404 page — self-contained HTML page for dev-mode route misses.
+ *
+ * When no route matches and the user has no 404.tsx, this page shows:
+ * - The requested path
+ * - All registered routes in the app
+ * - "Did you mean?" suggestions based on string similarity
+ * - Setup instructions for new projects with no routes
+ *
+ * Dev-only: this module is only imported in dev mode. It is never
+ * included in production builds.
+ *
+ * Design doc: 21-dev-server.md, 07-routing.md
+ */
+
+import type { SegmentNode } from '../routing/types.js';
+import { collectLeafRoutes } from '../routing/walkers.js';
+import { escapeHtml } from '../server/utils/escape-html.js';
+import { renderDevPageShell, type DevErrorHmrOptions } from './dev-page-shell.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface RouteInfo {
+  /** URL path pattern (e.g., "/dashboard/[id]") */
+  path: string;
+  /** Whether this is a page route or API route handler */
+  type: 'page' | 'route';
+}
+
+// ─── Route Collection ───────────────────────────────────────────────────────
+
+/**
+ * Collect all routable paths from a route tree (build-time scanner output
+ * or runtime route manifest).
+ *
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Includes parallel
+ * slots so the dev 404 page can list slot pages too — they aren't
+ * separately addressable, but they're still useful to know about when
+ * debugging a missing route.
+ */
+export function collectRoutes<TFile>(root: SegmentNode<TFile>): RouteInfo[] {
+  const leaves = collectLeafRoutes(root, { includeSlots: true });
+  const routes: RouteInfo[] = [];
+  for (const leaf of leaves) {
+    if (leaf.page) routes.push({ path: leaf.urlPath, type: 'page' });
+    if (leaf.route) routes.push({ path: leaf.urlPath, type: 'route' });
+  }
+  return routes;
+}
+
+// ─── String Similarity ──────────────────────────────────────────────────────
+
+/**
+ * Compute Levenshtein distance between two strings.
+ *
+ * Used for "did you mean?" suggestions. Simple O(n*m) implementation
+ * — fine for short URL paths.
+ */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+
+  // Optimization: use single-row DP
+  const row = Array.from({ length: n + 1 }, (_, i) => i);
+
+  for (let i = 1; i <= m; i++) {
+    let prev = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const val = Math.min(
+        row[j]! + 1, // deletion
+        prev + 1, // insertion
+        row[j - 1]! + cost // substitution
+      );
+      row[j - 1] = prev;
+      prev = val;
+    }
+    row[n] = prev;
+  }
+
+  return row[n]!;
+}
+
+/**
+ * Find routes similar to the requested path.
+ *
+ * Returns up to 3 suggestions, sorted by similarity.
+ * Only includes routes with distance ≤ 40% of the longer string.
+ */
+export function findSimilarRoutes(requestedPath: string, routes: RouteInfo[]): RouteInfo[] {
+  if (routes.length === 0) return [];
+
+  const scored = routes
+    .map((route) => ({
+      route,
+      distance: levenshtein(requestedPath.toLowerCase(), route.path.toLowerCase()),
+    }))
+    .filter((s) => {
+      const maxLen = Math.max(requestedPath.length, s.route.path.length);
+      return s.distance <= maxLen * 0.4;
+    })
+    .sort((a, b) => a.distance - b.distance);
+
+  return scored.slice(0, 3).map((s) => s.route);
+}
+
+// ─── HTML Escaping ──────────────────────────────────────────────────────────
+
+const esc = escapeHtml;
+
+// ─── HTML Generation ────────────────────────────────────────────────────────
+
+/**
+ * Generate a dev-mode 404 page with route listing and suggestions.
+ *
+ * Returns an HTML string for a self-contained error page. `hmrOptions`
+ * carries the resolved Vite HMR connection options (including the WS token
+ * Vite 8 requires on browser upgrades) so the auto-reload script can
+ * actually connect (TIM-1067, B33).
+ */
+export function generateDev404Page(
+  requestedPath: string,
+  routes: RouteInfo[],
+  hmrOptions?: DevErrorHmrOptions
+): string {
+  const suggestions = findSimilarRoutes(requestedPath, routes);
+  const isEmpty = routes.length === 0;
+
+  const bodyHtml = `<header class="header">
+      <div class="badge">404 Not Found</div>
+      <h1 class="message">No route matches <code>${esc(requestedPath)}</code></h1>
+    </header>
+
+    ${
+      isEmpty
+        ? `<div class="welcome">
+        <h2>Welcome to timber.js</h2>
+        <p>Your app has no pages yet. Create your first page to get started:</p>
+        <div class="code-block">
+          <div class="code-header">app/page.tsx</div>
+          <pre><code>export default function Home() {
+  return &lt;h1&gt;Hello, timber.js!&lt;/h1&gt;;
+}</code></pre>
+        </div>
+        <p class="hint">Save the file and this page will reload automatically.</p>
+      </div>`
+        : ''
+    }
+
+    ${
+      suggestions.length > 0
+        ? `<div class="section">
+        <div class="section-header">Did you mean?</div>
+        <ul class="route-list suggestions">
+          ${suggestions.map((r) => `<li><a href="${esc(r.path)}">${esc(r.path)}</a> <span class="route-type">${r.type}</span></li>`).join('\n          ')}
+        </ul>
+      </div>`
+        : ''
+    }
+
+    ${
+      routes.length > 0
+        ? `<div class="section">
+        <div class="section-header">Available Routes (${routes.length})</div>
+        <ul class="route-list">
+          ${routes.map((r) => `<li><a href="${esc(r.path)}">${esc(r.path)}</a> <span class="route-type">${r.type}</span></li>`).join('\n          ')}
+        </ul>
+      </div>`
+        : ''
+    }`;
+
+  return renderDevPageShell({
+    title: `404 — ${requestedPath} | timber.js`,
+    extraCss: NOT_FOUND_CSS,
+    bodyHtml,
+    footerHint: 'Add or edit routes and this page will reload automatically.',
+    hmrOptions,
+  });
+}
+
+// ─── Page-Specific CSS ──────────────────────────────────────────────────────
+
+const NOT_FOUND_CSS = `
+  :root {
+    --badge-bg: #fefce8;
+    --badge-fg: #854d0e;
+    --badge-border: #fde68a;
+    --route-type-bg: #e0f2fe;
+    --route-type-fg: #0369a1;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --badge-bg: #422006;
+      --badge-fg: #fde68a;
+      --badge-border: #854d0e;
+      --route-type-bg: #0c4a6e;
+      --route-type-fg: #bae6fd;
+    }
+  }
+
+  .message code {
+    font-family: var(--code-font);
+    background: var(--code-bg);
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    font-size: 1.125rem;
+  }
+
+  .welcome {
+    margin-bottom: 1.5rem;
+    padding: 1.5rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    background: var(--source-bg);
+  }
+
+  .welcome h2 {
+    font-size: 1.125rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .welcome p { color: var(--fg-dim); margin-bottom: 1rem; }
+
+  .code-block {
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+    margin-bottom: 1rem;
+  }
+
+  .code-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    padding: 0.5rem 0.75rem;
+    background: var(--code-bg);
+    border-bottom: 1px solid var(--border);
+    color: var(--fg-dim);
+    font-family: var(--code-font);
+  }
+
+  .code-block pre {
+    padding: 0.75rem;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    overflow-x: auto;
+    margin: 0;
+  }
+
+  .route-list {
+    list-style: none;
+    padding: 0.5rem 0;
+  }
+
+  .route-list li {
+    padding: 0.375rem 0.75rem;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  .route-list li:hover { background: var(--source-bg); }
+
+  .route-list a {
+    color: var(--link);
+    text-decoration: none;
+  }
+
+  .route-list a:hover { text-decoration: underline; }
+
+  .route-type {
+    font-size: 0.625rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    background: var(--route-type-bg);
+    color: var(--route-type-fg);
+  }
+
+  .suggestions { background: var(--source-bg); }
+`;

package/src/dev-tools/browser-logs.ts

@@ -0,0 +1,291 @@
+/**
+ * timber-dev-browser-logs — Forwards browser console output to the server terminal.
+ *
+ * Injects a small inline script in dev mode that intercepts browser
+ * `console.error`, `console.warn`, and `console.info`, then forwards
+ * messages to the server via Vite's HMR WebSocket.
+ *
+ * The server-side listener formats and prints the messages with color-coded
+ * prefixes: [browser:error], [browser:warn], [browser:info].
+ *
+ * Dev-only: this plugin only runs during `vite dev`.
+ * No runtime overhead in production.
+ *
+ * See TIM-513 for design context.
+ * See design/18-build-system.md §"Dev Server" for sub-plugin architecture.
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/** Log levels forwarded from the browser. */
+export type BrowserLogLevel = 'error' | 'warn' | 'info';
+
+/** Configuration value for devBrowserLogs in timber.config.ts. */
+export type DevBrowserLogsConfig = BrowserLogLevel | 'none' | undefined;
+
+/**
+ * Payload sent from browser to server via Vite's HMR WebSocket.
+ * Kept small — truncated before sending.
+ */
+export interface BrowserLogPayload {
+  level: BrowserLogLevel;
+  /** Serialized message string. */
+  message: string;
+  /** Error stack trace, if the first argument was an Error. */
+  stack: string | null;
+  /** Source URL and line number, if available. */
+  source: string | null;
+  /** Timestamp in ms (Date.now()) from the browser. */
+  timestamp: number;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────
+
+/** Max message size in bytes before truncation. */
+const MAX_MESSAGE_BYTES = 2048;
+
+/** HMR event name for browser→server log forwarding. */
+const HMR_EVENT = 'timber:browser-log';
+
+/** ANSI color codes for terminal output. */
+const COLORS = {
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  dim: '\x1b[2m',
+  reset: '\x1b[0m',
+} as const;
+
+/** Level severity ordering for threshold comparison. */
+const LEVEL_SEVERITY: Record<BrowserLogLevel | 'none', number> = {
+  none: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+// ─── Formatting ──────────────────────────────────────────────────────────
+
+/**
+ * Format a browser log payload for server terminal output.
+ *
+ * Produces color-coded output like:
+ *   [browser:error] Uncaught TypeError: x is not a function
+ *     at App (app.tsx:10:5)
+ *   [browser:warn] Deprecation warning (app/page.tsx:42:12)
+ */
+export function formatBrowserLog(payload: BrowserLogPayload): string {
+  const { level, message, stack, source } = payload;
+
+  // Color-coded prefix
+  const color = level === 'error' ? COLORS.red : level === 'warn' ? COLORS.yellow : COLORS.blue;
+  const prefix = `${color}[browser:${level}]${COLORS.reset}`;
+
+  // Source suffix
+  const sourceSuffix = source ? ` ${COLORS.dim}(${source})${COLORS.reset}` : '';
+
+  let output = `${prefix} ${message}${sourceSuffix}`;
+
+  // Append stack trace indented
+  if (stack) {
+    const indented = stack
+      .split('\n')
+      .map((line) => `  ${COLORS.dim}${line}${COLORS.reset}`)
+      .join('\n');
+    output += `\n${indented}`;
+  }
+
+  return output;
+}
+
+// ─── Level Filtering ─────────────────────────────────────────────────────
+
+/**
+ * Check if a log at `level` should be forwarded given the configured threshold.
+ *
+ * The threshold acts as a minimum severity:
+ * - 'error' → only errors
+ * - 'warn' → errors + warnings
+ * - 'info' → errors + warnings + info
+ * - 'none' → nothing
+ */
+export function shouldForwardLevel(
+  level: BrowserLogLevel,
+  threshold: BrowserLogLevel | 'none'
+): boolean {
+  if (threshold === 'none') return false;
+  return LEVEL_SEVERITY[level] >= LEVEL_SEVERITY[threshold];
+}
+
+// ─── Truncation ──────────────────────────────────────────────────────────
+
+/**
+ * Truncate a message to `maxBytes` to avoid flooding the terminal.
+ * Appends a suffix indicating how many bytes were dropped.
+ */
+export function truncateMessage(message: string, maxBytes: number): string {
+  if (message.length <= maxBytes) return message;
+
+  const truncated = message.slice(0, maxBytes);
+  const droppedBytes = message.length - maxBytes;
+  return `${truncated}… [truncated ${droppedBytes} bytes]`;
+}
+
+// ─── Client Injection Script ─────────────────────────────────────────────
+
+/**
+ * Generate the inline script injected into the browser in dev mode.
+ *
+ * This script:
+ * 1. Saves references to the original console methods
+ * 2. Wraps `console.error`, `console.warn`, `console.info`
+ * 3. Calls the original first (browser devtools still work)
+ * 4. Serializes and forwards via `import.meta.hot.send()`
+ * 5. Truncates messages to MAX_MESSAGE_BYTES
+ *
+ * The script is minimal and self-contained — no imports, no dependencies.
+ */
+export function generateClientScript(threshold: BrowserLogLevel | 'none'): string {
+  if (threshold === 'none') return '';
+
+  // Only intercept levels that meet the threshold
+  const levels: BrowserLogLevel[] = ['error', 'warn', 'info'].filter((l) =>
+    shouldForwardLevel(l as BrowserLogLevel, threshold)
+  ) as BrowserLogLevel[];
+
+  if (levels.length === 0) return '';
+
+  return `
+(function() {
+  if (!import.meta.hot) return;
+  var MAX_BYTES = ${MAX_MESSAGE_BYTES};
+  var levels = ${JSON.stringify(levels)};
+  var originals = {};
+
+  function serialize(arg) {
+    if (arg === null) return 'null';
+    if (arg === undefined) return 'undefined';
+    if (arg instanceof Error) return arg.stack || arg.message || String(arg);
+    if (typeof arg === 'object') {
+      try { return JSON.stringify(arg); } catch(e) { return String(arg); }
+    }
+    return String(arg);
+  }
+
+  function truncate(s) {
+    if (s.length <= MAX_BYTES) return s;
+    return s.slice(0, MAX_BYTES) + '... [truncated ' + (s.length - MAX_BYTES) + ' bytes]';
+  }
+
+  levels.forEach(function(level) {
+    originals[level] = console[level];
+    console[level] = function() {
+      originals[level].apply(console, arguments);
+      try {
+        var args = Array.prototype.slice.call(arguments);
+        var firstArg = args[0];
+        var stack = null;
+        var source = null;
+
+        if (firstArg instanceof Error) {
+          stack = firstArg.stack || null;
+          source = null;
+        }
+
+        var message = args.map(serialize).join(' ');
+        message = truncate(message);
+
+        import.meta.hot.send('${HMR_EVENT}', {
+          level: level,
+          message: message,
+          stack: stack,
+          source: source,
+          timestamp: Date.now()
+        });
+      } catch(e) {
+        // Never let log forwarding break the page
+      }
+    };
+  });
+})();
+`.trim();
+}
+
+// ─── Plugin ──────────────────────────────────────────────────────────────
+
+/**
+ * Create the timber-dev-browser-logs Vite plugin.
+ *
+ * - `configureServer`: Listens for HMR messages and prints them to the terminal
+ * - `transformIndexHtml`: Injects the client-side interception script
+ *
+ * Only active during `vite dev` (apply: 'serve').
+ */
+export function timberDevBrowserLogs(ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-dev-browser-logs',
+    apply: 'serve',
+
+    configureServer(server: ViteDevServer) {
+      const threshold = ctx.config.devBrowserLogs ?? 'warn';
+      if (threshold === 'none') {
+        // Clear any stale script from a prior server instance (e.g. HMR reconfigure)
+        delete (globalThis as Record<string, unknown>).__timber_dev_browser_log_script;
+        return;
+      }
+
+      // Register the client injection script on globalThis so the RSC entry
+      // can include it in headHtml for all Timber route responses.
+      // transformIndexHtml only runs for Vite's index.html fallback, not
+      // for responses served by createTimberMiddleware (TIM-575).
+      const script = generateClientScript(threshold);
+      if (script) {
+        (globalThis as Record<string, unknown>).__timber_dev_browser_log_script =
+          `<script type="module">${script}</script>`;
+      }
+
+      // Listen for browser log messages via HMR WebSocket
+      server.hot.on(HMR_EVENT, (payload: BrowserLogPayload) => {
+        try {
+          // Validate level
+          if (!shouldForwardLevel(payload.level, threshold)) return;
+
+          // Truncate server-side too (defense in depth)
+          payload.message = truncateMessage(payload.message, MAX_MESSAGE_BYTES);
+
+          const formatted = formatBrowserLog(payload);
+
+          // Use the correct console method for the log level
+          if (payload.level === 'error') {
+            process.stderr.write(formatted + '\n');
+          } else {
+            process.stdout.write(formatted + '\n');
+          }
+        } catch (e) {
+          // Use process.stderr directly to avoid re-entering patched console
+          process.stderr.write(
+            `[timber] log forwarding failed: ${e instanceof Error ? e.message : e}\n`
+          );
+        }
+      });
+    },
+
+    transformIndexHtml() {
+      const threshold = ctx.config.devBrowserLogs ?? 'warn';
+      const script = generateClientScript(threshold);
+      if (!script) return [];
+
+      return [
+        {
+          tag: 'script',
+          attrs: { type: 'module' },
+          children: script,
+          injectTo: 'head' as const,
+        },
+      ];
+    },
+  };
+}