@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.160

package/src/cli.ts

@@ -11,12 +11,14 @@
 //   timber preview  — Serve the production build
 //   timber check    — Validate types + routes without building
 
-const COMMANDS = ['dev', 'build', 'preview', 'check'] as const;
+const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema', 'init'] as const;
 type Command = (typeof COMMANDS)[number];
 
 export interface ParsedArgs {
   command: Command;
   config: string | undefined;
+  /** Positional arguments after the command (used by `timber schema sync`). */
+  rest: string[];
 }
 
 export interface CommandOptions {
@@ -26,11 +28,16 @@ export interface CommandOptions {
 /**
  * Parse CLI arguments into a structured command + options.
  * Accepts: timber <command> [--config|-c <path>]
+ *
+ * Unknown flags are an error, not silently ignored — `timber dev --port 4000`
+ * starting on the default port would contradict fail-loudly. The CLI surface
+ * is intentionally --config-only (design/11-platform.md §CLI); port selection
+ * goes through the PORT env var or server.port in vite.config.ts.
  */
 export function parseArgs(args: string[]): ParsedArgs {
   if (args.length === 0) {
     throw new Error(
-      'No command provided. Usage: timber <dev|build|preview|check> [--config <path>]'
+      'No command provided. Usage: timber <dev|build|preview|check|schema|init> [--config <path>]'
     );
   }
 
@@ -40,16 +47,31 @@ export function parseArgs(args: string[]): ParsedArgs {
   }
 
   let config: string | undefined;
+  const rest: string[] = [];
   for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--config' || args[i] === '-c') {
+    const arg = args[i];
+    if (arg === '--config' || arg === '-c') {
       config = args[++i];
       if (!config) {
         throw new Error('--config requires a path argument');
       }
+    } else if (arg.startsWith('-')) {
+      const portHint =
+        arg === '--port' || arg === '-p'
+          ? ' To change the port, set the PORT environment variable (PORT=4000 timber dev) ' +
+            'or server.port in vite.config.ts.'
+          : '';
+      throw new Error(
+        `Unknown option: ${arg}. The timber CLI only accepts --config <path>.${portHint}`
+      );
+    } else if (command === 'schema' || command === 'init') {
+      rest.push(arg);
+    } else {
+      throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);
     }
   }
 
-  return { command: command as Command, config };
+  return { command: command as Command, config, rest };
 }
 
 // ─── Command Implementations ─────────────────────────────────────────────────
@@ -63,7 +85,12 @@ export interface ViteDeps {
 
 /**
  * Start the Vite dev server.
- * Middleware re-runs on file change via HMR wiring in timber-routing.
+ *
+ * The timber plugin binds the port immediately with a holding page
+ * (in rootSync's config hook) so browsers see a "starting..." page
+ * instead of ERR_CONNECTION_REFUSED during initialization.
+ *
+ * See design/21-dev-server.md, TIM-665.
  */
 export async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
   const createServer = _deps?.createServer ?? (await import('vite')).createServer;
@@ -100,46 +127,25 @@ export function resolvePreviewStrategy(
   return 'vite';
 }
 
-/**
- * Load timber.config.ts from the project root.
- * Returns the config object with adapter, output, etc.
- * Returns null if no config file is found.
- */
-async function loadTimberConfig(
-  root: string
-): Promise<{ adapter?: import('./adapters/types').TimberPlatformAdapter; output?: string } | null> {
-  const { existsSync } = await import('node:fs');
-  const { join } = await import('node:path');
-  const { pathToFileURL } = await import('node:url');
-
-  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
-
-  for (const name of configNames) {
-    const configPath = join(root, name);
-    if (existsSync(configPath)) {
-      // Use Vite's built-in config loading to handle TypeScript
-      const mod = await import(pathToFileURL(configPath).href);
-      return mod.default ?? mod;
-    }
-  }
-  return null;
-}
-
 /**
  * Serve the production build for local testing.
  * If the adapter provides a preview() method, it takes priority.
  * Otherwise falls back to Vite's built-in preview server.
+ *
+ * Uses the same loadTimberConfigFile loader as dev/build — one loader,
+ * one set of module semantics. A config file that exists but fails to
+ * load throws (naming the file) instead of silently degrading to plain
+ * Vite preview. See TIM-1066.
  */
 export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
-  const { join } = await import('node:path');
+  const { loadTimberConfigFile, resolveBuildDir } = await import('./plugin-context.js');
 
-  // Try to load timber config for adapter-specific preview
   const root = process.cwd();
-  const config = await loadTimberConfig(root).catch(() => null);
+  const config = loadTimberConfigFile(root);
   const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;
 
   if (resolvePreviewStrategy(adapter) === 'adapter') {
-    const buildDir = join(root, 'dist');
+    const buildDir = resolveBuildDir(root, config?.buildDir);
     const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };
     await adapter!.preview!(timberConfig, buildDir);
     return;
@@ -174,6 +180,117 @@ export async function runCheck(options: CommandOptions): Promise<void> {
   });
 }
 
+// ─── Schema Subcommand ───────────────────────────────────────────────────────
+
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, diff against
+ * app/schema.ts, and append missing entries with type-appropriate codec defaults.
+ *
+ * See design/41-global-params.md §Auto-Scaffolding
+ */
+export async function runSchema(args: string[]): Promise<void> {
+  const subcommand = args[0];
+
+  if (subcommand !== 'sync') {
+    throw new Error(
+      `Unknown schema subcommand: ${subcommand ?? '(none)'}. Usage: timber schema sync`
+    );
+  }
+
+  const { runSchemaSync, defaultCodecForSegment } = await import('./cli-schema-sync.js');
+  const result = runSchemaSync(process.cwd());
+
+  if (result.filesystemSegments.length === 0) {
+    console.log('[timber] No dynamic segments found in app/.');
+    return;
+  }
+
+  if (result.created) {
+    console.log(`[timber] Created app/schema.ts with ${result.addedSegments.length} segment(s):`);
+    for (const seg of result.addedSegments) {
+      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+    }
+    return;
+  }
+
+  if (result.addedSegments.length === 0 && result.removedSegments.length === 0) {
+    console.log('[timber] Schema is up to date — all segments are registered.');
+    return;
+  }
+
+  if (result.addedSegments.length > 0) {
+    console.log(`[timber] Added ${result.addedSegments.length} segment(s) to app/schema.ts:`);
+    for (const seg of result.addedSegments) {
+      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+    }
+  }
+
+  if (result.removedSegments.length > 0) {
+    console.log(
+      `[timber] Removed ${result.removedSegments.length} stale segment(s) from app/schema.ts:`
+    );
+    for (const seg of result.removedSegments) {
+      console.log(`  - ${seg}`);
+    }
+  }
+}
+
+// ─── Init Subcommand ─────────────────────────────────────────────────────────
+
+/**
+ * `timber init` — write AGENTS.md (and CLAUDE.md pointer) to the project root
+ * so AI coding agents can discover timber.js documentation and conventions.
+ *
+ * The content is read from the installed @timber-js/app package itself, so it
+ * stays in sync with the installed version.
+ */
+export async function runInit(): Promise<void> {
+  const { readFileSync, writeFileSync, existsSync } = await import('node:fs');
+  const { resolve, dirname } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+
+  const root = process.cwd();
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+  const agentSkillPath = resolve(packageRoot, 'agent-skill.md');
+  if (!existsSync(agentSkillPath)) {
+    throw new Error(
+      'agent-skill.md not found in @timber-js/app package. ' +
+        'This may be a development install — try reinstalling.'
+    );
+  }
+
+  const agentSkill = readFileSync(agentSkillPath, 'utf-8');
+
+  const agentsPath = resolve(root, 'AGENTS.md');
+  const claudePath = resolve(root, 'CLAUDE.md');
+
+  const wrote: string[] = [];
+
+  if (existsSync(agentsPath)) {
+    console.log('[timber] AGENTS.md already exists — skipping (delete it first to regenerate)');
+  } else {
+    writeFileSync(agentsPath, agentSkill);
+    wrote.push('AGENTS.md');
+  }
+
+  if (existsSync(claudePath)) {
+    console.log('[timber] CLAUDE.md already exists — skipping (delete it first to regenerate)');
+  } else {
+    writeFileSync(claudePath, 'Read AGENTS.md for project context and conventions.\n');
+    wrote.push('CLAUDE.md');
+  }
+
+  if (wrote.length > 0) {
+    console.log(
+      `[timber] Created ${wrote.join(' and ')} — AI agents can now discover timber.js docs.`
+    );
+    console.log('[timber] Full documentation: node_modules/@timber-js/app/docs/');
+  } else {
+    console.log('[timber] Nothing to do — both files already exist.');
+  }
+}
+
 // ─── Main Entry Point ────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
@@ -193,6 +310,12 @@ async function main(): Promise<void> {
     case 'check':
       await runCheck(options);
       break;
+    case 'schema':
+      await runSchema(parsed.rest);
+      break;
+    case 'init':
+      await runInit();
+      break;
   }
 }
 

package/src/client/browser-dev.ts

@@ -1,5 +1,6 @@
 /**
- * Dev-only browser helpers — server log replay and client error forwarding.
+ * Dev-only browser helpers — server log replay, client error forwarding,
+ * and compiling overlay.
  *
  * These are only active when import.meta.hot is available (Vite dev mode).
  * Extracted from browser-entry.ts to keep files under 500 lines.
@@ -100,6 +101,132 @@ export function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): void {
   });
 }
 
+// ─── Compiling Overlay ──────────────────────────────────────────
+
+/**
+ * Compiling overlay state.
+ *
+ * A small non-blocking indicator in the bottom-left corner that shows
+ * "Compiling..." during HMR/module updates. Uses a 200ms debounce so
+ * near-instant updates never flash the indicator.
+ *
+ * The overlay is lazily created on first show and reused thereafter.
+ * All styles are inline — no external CSS dependency.
+ */
+
+let overlayEl: HTMLDivElement | null = null;
+let showTimeoutId: ReturnType<typeof setTimeout> | null = null;
+let pendingUpdates = 0;
+
+/** Debounce delay before showing the overlay (ms). */
+const SHOW_DELAY_MS = 200;
+
+/**
+ * Get the effective debounce delay.
+ * Checks for a test override on `window.__timber_compiling_debounce`
+ * (number) to allow E2E tests to bypass the debounce.
+ */
+function getShowDelay(): number {
+  const win = window as unknown as { __timber_compiling_debounce?: number };
+  return typeof win.__timber_compiling_debounce === 'number'
+    ? win.__timber_compiling_debounce
+    : SHOW_DELAY_MS;
+}
+
+/**
+ * Lazily create the overlay DOM element.
+ * Appended to document.body with fixed positioning in the bottom-left.
+ */
+function getOrCreateOverlay(): HTMLDivElement {
+  if (overlayEl) return overlayEl;
+
+  const el = document.createElement('div');
+  el.setAttribute('data-timber-compiling-overlay', '');
+  Object.assign(el.style, {
+    position: 'fixed',
+    bottom: '16px',
+    left: '16px',
+    padding: '6px 12px',
+    background: 'rgba(0, 0, 0, 0.85)',
+    color: '#fff',
+    fontSize: '13px',
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+    fontWeight: '500',
+    borderRadius: '6px',
+    zIndex: '2147483647',
+    pointerEvents: 'none',
+    opacity: '0',
+    transition: 'opacity 150ms ease',
+    boxShadow: '0 2px 8px rgba(0, 0, 0, 0.3)',
+    lineHeight: '1',
+  });
+  el.textContent = 'Compiling…';
+  document.body.appendChild(el);
+  overlayEl = el;
+  return el;
+}
+
+/**
+ * Signal that an HMR/module update has started.
+ *
+ * If an update is already tracked, this increments the counter.
+ * The overlay is shown after SHOW_DELAY_MS to avoid flashing
+ * for fast updates.
+ *
+ * When the delay is 0 (E2E test override), the overlay is shown
+ * synchronously to eliminate the race where hideCompilingOverlay()
+ * clears the show timeout before it fires.
+ */
+export function showCompilingOverlay(): void {
+  pendingUpdates++;
+  if (pendingUpdates === 1) {
+    const delay = getShowDelay();
+    if (delay <= 0) {
+      // Synchronous show — no setTimeout race with hideCompilingOverlay().
+      // Used by E2E tests to guarantee the overlay is visible before
+      // the async HMR refresh begins its network roundtrip.
+      const el = getOrCreateOverlay();
+      el.style.opacity = '1';
+    } else {
+      // Production path — debounce to avoid flashing for fast updates
+      showTimeoutId = setTimeout(() => {
+        showTimeoutId = null;
+        const el = getOrCreateOverlay();
+        el.style.opacity = '1';
+      }, delay);
+    }
+  }
+}
+
+/**
+ * Signal that an HMR/module update has completed.
+ *
+ * When all pending updates are resolved, the overlay is hidden.
+ * If the overlay was never shown (update completed within the
+ * debounce window), the timeout is cleared — no visual flash.
+ *
+ * Test hook: if `window.__timber_hold_compiling_overlay` is true,
+ * the overlay stays visible. E2E tests use this to avoid a race
+ * where the RSC refresh completes between polling intervals,
+ * making the overlay impossible to observe.
+ */
+export function hideCompilingOverlay(): void {
+  const win = window as unknown as { __timber_hold_compiling_overlay?: boolean };
+  if (win.__timber_hold_compiling_overlay) return;
+
+  pendingUpdates = Math.max(0, pendingUpdates - 1);
+  if (pendingUpdates === 0) {
+    if (showTimeoutId !== null) {
+      clearTimeout(showTimeoutId);
+      showTimeoutId = null;
+    }
+    if (overlayEl) {
+      overlayEl.style.opacity = '0';
+    }
+  }
+}
+
 // ─── Client Error Forwarding ────────────────────────────────────────
 
 /**
@@ -115,6 +242,10 @@ export function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): voi
     if (!event.error && !event.message) return;
     // Skip errors during page unload — these are abort-related, not application errors
     if (isPageUnloading()) return;
+    // Skip framework signal digests (redirect/deny) — these are control-flow
+    // signals, not application errors. They should never surface as dev
+    // overlays even if they escape an error boundary. See TIM-838.
+    if (isFrameworkSignalError(event.error)) return;
 
     const error = event.error;
     hot.send('timber:client-error', {
@@ -129,6 +260,8 @@ export function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): voi
     if (!reason) return;
     // Skip rejections during page unload — aborted fetches/streams cause these
     if (isPageUnloading()) return;
+    // Skip framework signal digests (redirect/deny). See TIM-838.
+    if (isFrameworkSignalError(reason)) return;
 
     const message = reason instanceof Error ? reason.message : String(reason);
     const stack = reason instanceof Error ? (reason.stack ?? '') : '';
@@ -140,3 +273,25 @@ export function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): voi
     });
   });
 }
+
+/**
+ * Detect errors whose `digest` marks them as a framework control-flow signal
+ * (RedirectSignal, DenySignal). These must never surface as dev overlays —
+ * they are expected during navigation and are handled by the error boundary
+ * and router. Exported for tests.
+ *
+ * See also: isControlFlowSignal() in server/primitives.ts (server-side,
+ * handles both instanceof and digest detection).
+ */
+export function isFrameworkSignalError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const digest = (error as { digest?: unknown }).digest;
+  if (typeof digest !== 'string') return false;
+  try {
+    const parsed = JSON.parse(digest) as { type?: unknown } | null;
+    if (!parsed || typeof parsed !== 'object') return false;
+    return parsed.type === 'redirect' || parsed.type === 'deny';
+  } catch {
+    return false;
+  }
+}

package/src/client/browser-entry/action-dispatch.ts

@@ -0,0 +1,124 @@
+/**
+ * Server Action Dispatch — registers the callServer callback.
+ *
+ * When React encounters a server reference (from `'use server'` modules),
+ * it calls `callServer(id, args)` to dispatch the action to the server.
+ * The RSC plugin delegates to `globalThis.__viteRscCallServer` which is
+ * set by `setServerCallback`.
+ *
+ * The callback:
+ * 1. Serializes args via `encodeReply` (RSC wire format)
+ * 2. POSTs to the current URL with `Accept: text/x-component`
+ * 3. Decodes the RSC response stream
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ */
+
+import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runtime/browser.js';
+import { getRouter, getRouterOrNull } from '#client-internal';
+import { setHardNavigating } from '../navigation-root.js';
+import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.js';
+export function setupServerActions(): void {
+  setServerCallback(async (id: string, args: unknown[]) => {
+    const body = await encodeReply(args);
+
+    // Track the X-Timber-Revalidation header from the response.
+    // We intercept the fetch promise to read headers before createFromFetch
+    // consumes the body stream.
+    let hasRevalidation = false;
+    let hasRedirect = false;
+
+    // Build action request headers. Include deployment ID for version
+    // skew detection (TIM-446) — the server rejects stale actions gracefully.
+    const actionHeaders: Record<string, string> = {
+      'Accept': 'text/x-component',
+      'x-rsc-action': id,
+    };
+    const actionDeploymentId = getClientDeploymentId();
+    if (actionDeploymentId) {
+      actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
+    }
+
+    const response = fetch(window.location.href, {
+      method: 'POST',
+      headers: actionHeaders,
+      body,
+    }).then((res) => {
+      // Version skew detection (TIM-446): if the server signals a reload,
+      // trigger a full page load to pick up the new deployment.
+      if (res.headers.get(RELOAD_HEADER) === '1') {
+        window.location.reload();
+        throw new Error('Version skew detected — reloading page');
+      }
+      hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
+      hasRedirect = res.headers.get('X-Timber-Redirect') != null;
+      return res;
+    });
+
+    const decoded = await createFromFetch(response);
+
+    // Handle redirect — server encoded the redirect location in the RSC stream
+    // instead of returning HTTP 302. Perform a client-side SPA navigation.
+    if (hasRedirect) {
+      const wrapper = decoded as { _redirect: string; _status: number };
+
+      // External redirects (e.g., OAuth flows via redirectExternal()) must
+      // use a full page navigation — the RSC router can only fetch same-origin
+      // payloads. On browsers with the Navigation API, navigation.navigate()
+      // happens to perform a real cross-origin navigation, but browsers
+      // without it (iPad Safari) would attempt an RSC fetch that fails on CORS.
+      const isExternal =
+        wrapper._redirect.startsWith('https://') || wrapper._redirect.startsWith('http://');
+      if (isExternal) {
+        setHardNavigating(true);
+        window.location.href = wrapper._redirect;
+        return undefined;
+      }
+
+      try {
+        const router = getRouter();
+        void router.navigate(wrapper._redirect);
+      } catch (e) {
+        // Router not yet initialized — fall back to full navigation.
+        // Set hard-navigating flag to prevent Navigation API interception
+        // and React from rendering during page teardown. See TIM-626.
+        console.debug(
+          '[timber] action redirect: router not ready, using full navigation',
+          e instanceof Error ? e.message : e
+        );
+        setHardNavigating(true);
+        window.location.href = wrapper._redirect;
+      }
+      return undefined;
+    }
+
+    if (hasRevalidation) {
+      // Piggybacked response: wrapper object { _action, _tree }
+      // Apply the revalidated tree directly — no separate router.refresh() needed.
+      const wrapper = decoded as { _action: unknown; _tree: unknown };
+      const router = getRouterOrNull();
+      if (router) {
+        try {
+          router.applyRevalidation(wrapper._tree);
+        } catch (e) {
+          console.error('[timber] applyRevalidation failed after server action', e);
+        }
+      }
+      return wrapper._action;
+    }
+
+    // No piggybacked revalidation — refresh to pick up any mutations.
+    // This covers actions that don't call revalidatePath().
+    try {
+      const router = getRouter();
+      void router.refresh();
+    } catch (e) {
+      console.debug(
+        '[timber] action refresh: router not ready',
+        e instanceof Error ? e.message : e
+      );
+    }
+
+    return decoded;
+  });
+}

package/src/client/browser-entry/hmr.ts

@@ -0,0 +1,70 @@
+/**
+ * HMR & Dev Tooling — dev-only wiring for hot module replacement.
+ *
+ * Handles:
+ * - RSC module invalidation (rsc:update → router.refresh())
+ * - Dev warnings forwarded from server via WebSocket
+ * - Server console log replay in browser
+ * - Client error forwarding to Vite error overlay
+ *
+ * See design/21-dev-server.md §"HMR Wiring"
+ */
+
+import type { RouterInstance } from '#client-internal';
+import {
+  setupServerLogReplay,
+  setupClientErrorForwarding,
+  showCompilingOverlay,
+  hideCompilingOverlay,
+} from '../browser-dev.js';
+
+type HotApi = {
+  on(event: string, cb: (...args: unknown[]) => void): void;
+  send(event: string, data: unknown): void;
+};
+
+/**
+ * Set up HMR and dev tool integration.
+ *
+ * Reads `import.meta.hot` to register dev-only event listeners.
+ * In production builds, `import.meta.hot` is undefined and this
+ * function is a no-op.
+ */
+export function setupHmr(router: RouterInstance): void {
+  // Vite injects import.meta.hot in dev mode. Cast to access it without
+  // requiring vite/client types in the package tsconfig.
+  const hot = (import.meta as unknown as { hot?: HotApi }).hot;
+  if (!hot) return;
+
+  // ─── Compiling overlay: Vite client HMR updates ──────────────
+  // vite:beforeUpdate fires when Vite begins applying client-side
+  // module updates (React Fast Refresh, CSS hot update, etc.).
+  // vite:afterUpdate fires once all updates are applied.
+  hot.on('vite:beforeUpdate', () => {
+    showCompilingOverlay();
+  });
+  hot.on('vite:afterUpdate', () => {
+    hideCompilingOverlay();
+  });
+
+  // ─── RSC module invalidation ─────────────────────────────────
+  // rsc:update fires when a server component is edited.
+  // Show the compiling overlay while the RSC refresh is in flight.
+  hot.on('rsc:update', () => {
+    showCompilingOverlay();
+    void router.refresh().finally(() => {
+      hideCompilingOverlay();
+    });
+  });
+
+  // Listen for server console logs forwarded via WebSocket.
+  // Replays them in the browser console with a [SERVER] prefix
+  // so developers can see server output without switching to the terminal.
+  // See plugins/dev-logs.ts.
+  setupServerLogReplay(hot);
+
+  // Forward uncaught client errors to the server for the dev overlay.
+  // The server source-maps the stack and sends it back via Vite's
+  // error overlay protocol. See dev-server.ts §client error listener.
+  setupClientErrorForwarding(hot);
+}