@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.98

package/src/server/port-resolution.ts

@@ -0,0 +1,215 @@
+/**
+ * Port resolution for the dev server, Vite preview, and the Node
+ * production preview server.
+ *
+ * Behavior (see TIM-842):
+ *
+ *   1. Default port is **3000** for both dev and prod.
+ *   2. If the user did NOT set an explicit port, auto-bump from 3000
+ *      until a free port is found (3000 → 3001 → 3002 → …).
+ *   3. If the user DID set an explicit port (via `--port`, `PORT` env
+ *      var, or `vite.config.ts` `server.port`), use it as-is and let
+ *      the bind fail loudly on conflict (`strictPort: true`).
+ *
+ * The port-bump probe is performed by binding the **actual** server
+ * (e.g. the dev holding server) — not a throwaway probe — so there is
+ * no time-of-check / time-of-use race between probing and listening.
+ *
+ * Design doc: 21-dev-server.md §"Default Port and Auto-Bump".
+ */
+
+/** Default port used by `timber dev` and `timber preview`. */
+export const DEFAULT_PORT = 3000;
+
+/**
+ * A function that attempts to bind to a given port.
+ *
+ * Resolves with the bound port on success. Rejects with an error
+ * (typically with `code === 'EADDRINUSE'`) on failure.
+ */
+export type ListenFn = (port: number) => Promise<number>;
+
+// ── Pure resolution ────────────────────────────────────────────────────
+
+export interface ResolvePortInput {
+  /**
+   * Port read from `vite.config.ts` `server.port` or the `--port` CLI
+   * flag (Vite merges `--port` into `userConfig.server.port` before
+   * plugins see it).
+   */
+  configPort?: number | undefined;
+  /** Raw value of `process.env.PORT`. */
+  envPort?: string | undefined;
+  /** Default port to use when neither `configPort` nor `envPort` is set. */
+  defaultPort?: number;
+}
+
+export interface ResolvedPortInput {
+  /** Port to start binding from. */
+  port: number;
+  /**
+   * `true` if the port came from an explicit user override (config or
+   * env). When `true`, callers must NOT auto-bump and must surface
+   * `EADDRINUSE` to the user.
+   */
+  explicit: boolean;
+}
+
+/**
+ * Pure: compute the starting port from config / env / defaults.
+ *
+ * Performs no I/O — pair with {@link bindWithBump} to actually listen.
+ */
+export function resolveStartPort(input: ResolvePortInput): ResolvedPortInput {
+  const defaultPort = input.defaultPort ?? DEFAULT_PORT;
+
+  // `configPort` wins over `envPort`. This matches Vite's behavior:
+  // `vite --port 4000` overrides `PORT=5000` in the environment.
+  if (typeof input.configPort === 'number' && Number.isFinite(input.configPort)) {
+    return { port: input.configPort, explicit: true };
+  }
+
+  if (input.envPort != null && input.envPort !== '') {
+    const parsed = Number(input.envPort);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return { port: parsed, explicit: true };
+    }
+  }
+
+  return { port: defaultPort, explicit: false };
+}
+
+// ── Bind with auto-bump ────────────────────────────────────────────────
+
+export interface BindWithBumpOptions {
+  /** First port to attempt. */
+  startPort: number;
+  /**
+   * If `true`, increment the port and retry on `EADDRINUSE`. If
+   * `false`, attempt once and let the error propagate.
+   */
+  autoBump: boolean;
+  /** Maximum number of port attempts when `autoBump` is `true`. */
+  maxAttempts?: number;
+}
+
+export interface BindWithBumpResult {
+  /** Port that was actually bound. */
+  port: number;
+  /** `true` if the bound port differs from `startPort`. */
+  bumped: boolean;
+}
+
+/**
+ * Bind a server starting at `startPort`, optionally bumping the port
+ * on `EADDRINUSE` until a free one is found.
+ *
+ * Use this with the actual server you intend to keep listening (e.g.
+ * the dev holding server). Pairing the probe with the real listen
+ * eliminates the TOCTOU race that a throwaway probe would introduce.
+ */
+export async function bindWithBump(
+  listen: ListenFn,
+  options: BindWithBumpOptions
+): Promise<BindWithBumpResult> {
+  const maxAttempts = options.autoBump ? (options.maxAttempts ?? 100) : 1;
+  let lastErr: unknown = null;
+
+  for (let i = 0; i < maxAttempts; i++) {
+    const port = options.startPort + i;
+    try {
+      const bound = await listen(port);
+      return { port: bound, bumped: i > 0 };
+    } catch (err) {
+      lastErr = err;
+      // Only retry on EADDRINUSE — other errors (EACCES, etc.) are
+      // permanent and must surface immediately.
+      if (!isAddrInUse(err)) throw err;
+    }
+  }
+
+  throw lastErr ?? new Error(`Could not bind to a free port starting at ${options.startPort}`);
+}
+
+/** True if `err` is a Node `EADDRINUSE` error from `server.listen()`. */
+export function isAddrInUse(err: unknown): boolean {
+  return (
+    typeof err === 'object' && err !== null && (err as { code?: string }).code === 'EADDRINUSE'
+  );
+}
+
+// ── High-level helper used by the rootSync plugin ────────────────────
+
+export interface StartDevServerPortInput {
+  /** Resolved port from `userConfig.server?.port` (or `--port`), or undefined. */
+  configPort: number | undefined;
+  /** Raw `process.env.PORT` value. */
+  envPort: string | undefined;
+  /** ListenFn for the holding server (or any pre-bind probe target). */
+  listen: ListenFn;
+  /** Logger — defaults to `console`. Injected for tests. */
+  log?: (msg: string) => void;
+  warn?: (msg: string) => void;
+}
+
+export interface StartDevServerPortResult {
+  /** Port chosen for both the holding server and Vite's dev server. */
+  port: number;
+  /** True if the user explicitly set the port (=> Vite must `strictPort: true`). */
+  explicit: boolean;
+  /** True if the holding server actually bound the port. */
+  bound: boolean;
+}
+
+/**
+ * Run the full dev-server port resolution + holding-server bind sequence.
+ *
+ * Resolves the port from config / env / default, attempts to bind the
+ * holding server (auto-bumping when the port came from the default),
+ * and logs the chosen URL. On a clean failure for an explicit port, it
+ * warns and falls back to the requested port so Vite can surface the
+ * conflict via `strictPort: true`.
+ *
+ * Extracted from `index.ts` so the rootSync `config()` hook stays
+ * focused on plugin assembly.
+ */
+export async function startDevServerPort(
+  input: StartDevServerPortInput
+): Promise<StartDevServerPortResult> {
+  const log = input.log ?? ((msg: string) => console.log(msg));
+  const warn = input.warn ?? ((msg: string) => console.warn(msg));
+
+  const start = resolveStartPort({
+    configPort: input.configPort,
+    envPort: input.envPort,
+    defaultPort: DEFAULT_PORT,
+  });
+
+  try {
+    const result = await bindWithBump(input.listen, {
+      startPort: start.port,
+      autoBump: !start.explicit,
+    });
+    if (result.bumped) {
+      log(`\n  \x1b[33m[timber]\x1b[0m Port ${start.port} in use, using ${result.port}\n`);
+    }
+    log(
+      `\n  \x1b[2m\u{1FAB5} timber.js dev server starting at\x1b[0m ` +
+        `\x1b[36mhttp://localhost:${result.port}\x1b[0m\n`
+    );
+    return { port: result.port, explicit: start.explicit, bound: true };
+  } catch (err) {
+    // Holding server failed to bind. For explicit ports we leave the
+    // bound state false and let Vite fail loudly via strictPort: true.
+    // For implicit ports this is essentially unreachable (auto-bump
+    // tries 100 ports), but if we hit it we still want Vite to surface
+    // the error.
+    if (start.explicit && isAddrInUse(err)) {
+      warn(
+        `\n  \x1b[33m[timber]\x1b[0m Port ${start.port} is already in use. ` +
+          `Set PORT (or remove the override) to pick another port.\n`
+      );
+    }
+    return { port: start.port, explicit: start.explicit, bound: false };
+  }
+}

package/src/server/route-element-builder.ts

@@ -213,7 +213,7 @@ export async function buildRouteElement(
   interception?: InterceptionContext,
   clientStateTree?: Set<string> | null
 ): Promise<RouteElementResult> {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
+  const segments = match.segments;
 
   // Load all modules along the segment chain
   const metadataEntries: Array<{ metadata: Metadata; isPage: boolean }> = [];

package/src/server/route-matcher.ts

@@ -10,6 +10,7 @@
 
 import type { RouteMatch } from './pipeline.js';
 import type { MiddlewareFn } from './middleware-runner.js';
+import type { SegmentNode, RouteTree } from '../routing/types.js';
 import {
   METADATA_ROUTE_CONVENTIONS,
   isStaticMetadataExtension,
@@ -18,71 +19,40 @@ import {
 } from './metadata-routes.js';
 
 // ─── Manifest Types ───────────────────────────────────────────────────────
-// The virtual module manifest has a slightly different shape than SegmentNode:
-// file references are { load, filePath } instead of RouteFile.
+//
+// TIM-848: the runtime route manifest re-uses the same `SegmentNode<TFile>`
+// / `RouteTree<TFile>` interfaces from `routing/types.ts`. The only
+// difference between build-time and runtime is the file reference payload
+// — build-time has `{ filePath, extension }`, runtime has `{ filePath, load }`.
+// Walkers parameterized over `TFile` work on either; there is no separate
+// "manifest" tree shape.
 
 /** A file reference in the manifest (lazy import + path). */
-interface ManifestFile {
+export interface ManifestFile {
   load: () => Promise<unknown>;
   filePath: string;
 }
 
-/** A segment node as it appears in the virtual:timber-route-manifest module. */
-export interface ManifestSegmentNode {
-  segmentName: string;
-  segmentType:
-    | 'static'
-    | 'dynamic'
-    | 'catch-all'
-    | 'optional-catch-all'
-    | 'group'
-    | 'slot'
-    | 'intercepting';
-  urlPath: string;
-  paramName?: string;
-  /** For intercepting segments: the marker used, e.g. "(.)". */
-  interceptionMarker?: '(.)' | '(..)' | '(...)' | '(..)(..)';
-  /** For intercepting segments: the segment name after stripping the marker. */
-  interceptedSegmentName?: string;
-
-  page?: ManifestFile;
-  layout?: ManifestFile;
-  middleware?: ManifestFile;
-  access?: ManifestFile;
-  route?: ManifestFile;
-  /** params.ts — isomorphic convention file for segmentParams + searchParams definitions. */
-  params?: ManifestFile;
-  error?: ManifestFile;
-  default?: ManifestFile;
-  denied?: ManifestFile;
-  statusFiles?: Record<string, ManifestFile>;
-  jsonStatusFiles?: Record<string, ManifestFile>;
-  legacyStatusFiles?: Record<string, ManifestFile>;
-  /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
-  metadataRoutes?: Record<string, ManifestFile>;
-
-  children: ManifestSegmentNode[];
-  slots: Record<string, ManifestSegmentNode>;
-}
+/**
+ * A segment node as it appears in the virtual:timber-route-manifest module.
+ *
+ * Type alias for `SegmentNode<ManifestFile>` — the same shape used by the
+ * scanner, only with lazy `load` functions instead of build-time extension
+ * metadata.
+ */
+export type ManifestSegmentNode = SegmentNode<ManifestFile>;
 
-/** The manifest shape from virtual:timber-route-manifest. */
-export interface ManifestRoot {
-  root: ManifestSegmentNode;
-  /**
-   * Absolute path to the Vite project root, captured at build/load time.
-   * Used by dev-only features (e.g., dev error page frame classification)
-   * that need a correct project root even when CWD differs (e.g., monorepo
-   * custom root). See TIM-807 / TIM-808.
-   */
+/**
+ * The manifest shape from virtual:timber-route-manifest.
+ *
+ * Extends `RouteTree<ManifestFile>` with `viteRoot`, the absolute path
+ * to the Vite project root captured at build/load time. Used by dev-only
+ * features (e.g., dev error page frame classification) that need a
+ * correct project root even when CWD differs (e.g., monorepo custom root).
+ * See TIM-807 / TIM-808.
+ */
+export interface ManifestRoot extends RouteTree<ManifestFile> {
   viteRoot: string;
-  proxy?: ManifestFile;
-  /**
-   * Global error page: app/global-error.{tsx,ts,jsx,js}
-   * Tier 2 — standalone full-page replacement (no layouts) when no
-   * segment-level error file is found. SSR-only render.
-   * See design/10-error-handling.md §"Tier 2"
-   */
-  globalError?: ManifestFile;
 }
 
 // ─── Matcher ──────────────────────────────────────────────────────────────
@@ -132,9 +102,7 @@ function matchPathname(root: ManifestSegmentNode, pathname: string): RouteMatch
   }
 
   return {
-    // The pipeline uses segments as opaque objects passed to the renderer.
-    // Cast is safe — the renderer receives what the manifest provides.
-    segments: segments as unknown as RouteMatch['segments'],
+    segments,
     segmentParams: params,
     middlewareChain,
   };

package/src/server/rsc-entry/api-handler.ts

@@ -89,9 +89,9 @@ async function renderApiDeny(
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response> {
-  const { resolveManifestStatusFile } = await import('../manifest-status-resolver.js');
+  const { resolveStatusFile } = await import('../status-code-resolver.js');
 
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
+  const resolution = resolveStatusFile(deny.status, segments, 'json');
   if (resolution) {
     const mod = await loadModule(resolution.file);
     const jsonContent = mod.default ?? mod;

package/src/server/rsc-entry/error-renderer.ts

@@ -377,7 +377,7 @@ export async function renderNoMatchPage(
   }
 
   const deny = new DenySignal(404);
-  const match: RouteMatch = { segments: segments as never, segmentParams: {}, middlewareChain: [] };
+  const match: RouteMatch = { segments, segmentParams: {}, middlewareChain: [] };
 
   return renderDenyPage(
     deny,

package/src/server/rsc-entry/index.ts

@@ -31,8 +31,7 @@ import loadUserInstrumentation from 'virtual:timber-instrumentation';
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import loadCacheHandler from 'virtual:timber-cache-handler';
 
-import type { FormRerender } from '../action-handler.js';
-import { handleActionRequest, isActionRequest } from '../action-handler.js';
+import { wrapPipelineWithActionDispatch } from './wrap-action-dispatch.js';
 import type { BodyLimitsConfig } from '../body-limits.js';
 import type { BuildManifest } from '../build-manifest.js';
 import {
@@ -46,7 +45,6 @@ import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
 import { resolveLogMode } from '../dev-logger.js';
 import { sendEarlyHints103 } from '../early-hints-sender.js';
 import { collectEarlyHintHeaders } from '../early-hints.js';
-import { runWithFormFlash } from '../form-flash.js';
 import type { ClientBootstrapConfig } from '../html-injectors.js';
 import { buildClientScripts } from '../html-injectors.js';
 import type { InterceptionContext, PipelineConfig, RouteMatch } from '../pipeline.js';
@@ -239,8 +237,15 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
 
   const typedBuildManifest = buildManifest as BuildManifest;
 
+  // The routing plugin emits `manifest.proxy = { load, filePath }` only when
+  // the app has an `app/proxy.ts`. Convert that to the pipeline's lazy variant
+  // so HMR re-imports per request; leave it undefined when there's no proxy.
+  const proxyConfig: PipelineConfig['proxy'] = manifest.proxy?.load
+    ? { kind: 'lazy', loader: manifest.proxy.load }
+    : undefined;
+
   const pipelineConfig: PipelineConfig = {
-    proxyLoader: manifest.proxy?.load,
+    proxy: proxyConfig,
     matchRoute,
     matchMetadataRoute,
     // 103 Early Hints — fires after route match, before middleware.
@@ -248,11 +253,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     // so the browser starts fetching critical resources while the server renders.
     // In dev mode the manifest is empty — no hints are sent.
     earlyHints: (match: RouteMatch, _req: Request, responseHeaders: Headers) => {
-      const segments = match.segments as unknown as Array<{
-        layout?: { filePath: string };
-        page?: { filePath: string };
-      }>;
-      const headers = collectEarlyHintHeaders(segments, typedBuildManifest, {
+      const headers = collectEarlyHintHeaders(match.segments, typedBuildManifest, {
         skipJs: clientJsDisabled,
       });
       for (const h of headers) {
@@ -358,10 +359,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       // route's `401.json` are picked up. Fall back to the root chain when no
       // match is available (e.g. proxy-stage deny before route matching).
       // See TIM-822, design/04-authorization.md, design/10-error-handling.md.
-      type SegNode = import('../route-matcher.js').ManifestSegmentNode;
-      const chain = matchedRoute
-        ? (matchedRoute.segments as unknown as SegNode[])
-        : ([manifest.root] as unknown as SegNode[]);
+      const chain: ManifestSegmentNode[] = matchedRoute ? matchedRoute.segments : [manifest.root];
       const layoutComponents: LayoutEntry[] = [];
       try {
         for (const segment of chain) {
@@ -382,8 +380,8 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       // Reuse the matched route's params/middleware metadata when present so
       // downstream rendering sees the real route shape. Otherwise synthesise
       // a root-only stub (no params, no middleware).
-      const match = matchedRoute ?? {
-        segments: chain as never,
+      const match: RouteMatch = matchedRoute ?? {
+        segments: chain,
         segmentParams: {},
         middlewareChain: [],
       };
@@ -421,9 +419,13 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
 
   const pipeline = createPipeline(pipelineConfig);
 
-  // Wrap the pipeline to intercept server action requests before rendering.
-  // Actions bypass the normal pipeline (no route matching, no middleware)
-  // per design/08-forms-and-actions.md §"Middleware for Server Actions".
+  // Wrap the pipeline to enforce CSRF at the request boundary and intercept
+  // server action requests before rendering. Actions bypass the normal
+  // pipeline (no route matching, no middleware) per
+  // design/08-forms-and-actions.md §"Middleware for Server Actions".
+  //
+  // CSRF validation lives in the wrapper (not inside the action handler) so
+  // it covers route.ts API handlers as well as server actions. See LOCAL-773.
   const csrfConfig = {
     csrf: runtimeConfig.csrf,
     allowedOrigins: (runtimeConfig as Record<string, unknown>).allowedOrigins as
@@ -431,87 +433,39 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       | undefined,
   };
 
-  return async (req: Request): Promise<Response> => {
-    if (isActionRequest(req)) {
-      const actionResponse = await handleActionRequest(req, {
-        csrf: csrfConfig,
-        bodyLimits: {
-          limits: (runtimeConfig as Record<string, unknown>).limits as BodyLimitsConfig['limits'],
-        },
-        sensitiveFields: formsConfig?.stripSensitiveFields,
-        revalidateRenderer: async (path: string) => {
-          // Build the React element tree for the route at `path`.
-          // Returns the element tree (not serialized) so the action handler can
-          // combine it with the action result in a single renderToReadableStream call.
-          // Forward original request headers (cookies, session IDs, etc.).
-          const revalidateHeaders = new Headers(req.headers);
-          revalidateHeaders.set('Accept', 'text/x-component');
-          const revalidateReq = new Request(new URL(path, req.url), {
-            headers: revalidateHeaders,
-          });
-          const revalidateMatch = matchRoute(new URL(revalidateReq.url).pathname);
-          if (!revalidateMatch) {
-            throw new Error(`revalidatePath('${path}') — no matching route`);
-          }
-          // Coerce segment params (params.ts) before building the element tree.
-          // Without this, components receive raw strings instead of typed values.
-          await coerceSegmentParams(revalidateMatch);
-          // Set coerced params in ALS so getSegmentParams() works during
-          // the revalidation render (AccessGate reads params via ALS).
-          // Without this, AccessGate → getSegmentParams() throws because
-          // segmentParamsPromise is never set. See TIM-667.
-          setSegmentParams(revalidateMatch.segmentParams);
-          const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
-          return {
-            element: routeResult.element,
-            headElements: routeResult.headElements,
-          };
-        },
+  return wrapPipelineWithActionDispatch(pipeline, {
+    csrfConfig,
+    bodyLimits: (runtimeConfig as Record<string, unknown>).limits as BodyLimitsConfig['limits'],
+    sensitiveFields: formsConfig?.stripSensitiveFields,
+    buildRevalidateRenderer: (req) => async (path: string) => {
+      // Build the React element tree for the route at `path`.
+      // Returns the element tree (not serialized) so the action handler can
+      // combine it with the action result in a single renderToReadableStream call.
+      // Forward original request headers (cookies, session IDs, etc.).
+      const revalidateHeaders = new Headers(req.headers);
+      revalidateHeaders.set('Accept', 'text/x-component');
+      const revalidateReq = new Request(new URL(path, req.url), {
+        headers: revalidateHeaders,
       });
-      if (actionResponse) {
-        // Check if this is a re-render signal (no-JS validation failure)
-        if ('rerender' in actionResponse) {
-          const formRerender = actionResponse as FormRerender;
-          // Re-render the page with the action result as flash data.
-          // Server components read it via getFormFlash() and pass it to
-          // client form components as the initial useActionState value.
-          //
-          // Build a synthetic GET request for the rerender pipeline:
-          //   - Same URL (so route matching lands on the same page)
-          //   - Cookie header replaced with the post-action RYW snapshot
-          //     so server components see the action's writes (TIM-837)
-          //   - Method GET because the rerender is conceptually a page
-          //     render, not a re-POST. The pipeline doesn't branch on
-          //     method for page rendering, and constructing a POST without
-          //     a body is awkward across Request implementations.
-          const rerenderHeaders = new Headers(req.headers);
-          if (formRerender.cookieHeader) {
-            rerenderHeaders.set('cookie', formRerender.cookieHeader);
-          } else {
-            rerenderHeaders.delete('cookie');
-          }
-          const rerenderReq = new Request(req.url, {
-            method: 'GET',
-            headers: rerenderHeaders,
-          });
-          const response = await runWithFormFlash(formRerender.rerender, () =>
-            pipeline(rerenderReq)
-          );
-          // Apply Set-Cookie headers snapshotted from the action's ALS scope.
-          // The pipeline above runs in its own request context with a fresh
-          // cookie jar, so cookies set inside the action would otherwise be
-          // silently dropped on the no-JS rerender path. See TIM-836
-          // (LOCAL-740).
-          for (const value of formRerender.setCookieHeaders) {
-            response.headers.append('Set-Cookie', value);
-          }
-          return response;
-        }
-        return actionResponse;
+      const revalidateMatch = matchRoute(new URL(revalidateReq.url).pathname);
+      if (!revalidateMatch) {
+        throw new Error(`revalidatePath('${path}') — no matching route`);
       }
-    }
-    return pipeline(req);
-  };
+      // Coerce segment params (params.ts) before building the element tree.
+      // Without this, components receive raw strings instead of typed values.
+      await coerceSegmentParams(revalidateMatch);
+      // Set coerced params in ALS so getSegmentParams() works during the
+      // revalidation render (AccessGate reads params via ALS). Without this,
+      // AccessGate → getSegmentParams() throws because segmentParamsPromise
+      // is never set. See TIM-667.
+      setSegmentParams(revalidateMatch.segmentParams);
+      const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
+      return {
+        element: routeResult.element,
+        headElements: routeResult.headElements,
+      };
+    },
+  });
 }
 
 /**
@@ -534,7 +488,7 @@ async function renderRoute(
   rootSegment?: ManifestSegmentNode,
   globalError?: { load: () => Promise<unknown>; filePath: string }
 ): Promise<Response> {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
+  const segments = match.segments;
   const leaf = segments[segments.length - 1];
 
   // API routes (route.ts) — run access.ts standalone then dispatch to handler.