@timber-js/app 0.2.0-alpha.182 → 0.2.0-alpha.184

package/src/plugins/static-build.ts

@@ -3,13 +3,26 @@
  *
  * When `output: 'static'` is set in timber.config.ts, this plugin:
  * 1. Validates that no dynamic APIs (getCookies(), getHeaders()) are used
- * 2. Coordinates build-time rendering of all pages
+ * 2. After the build, renders all routes to static HTML + RSC flight files
  *
- * Design doc: design/15-future-prerendering.md
+ * Design doc: design/11-platform.md §"static output mode"
  */
 
 import type { Plugin } from 'vite';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, writeFile, rename, rm } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, extname, join, resolve, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import type { PluginContext } from '../plugin-context.js';
+import type {
+  StaticGenerationOptions,
+  StaticGenerationSummary,
+  StaticPageEntry,
+  StaticRedirectEntry,
+} from '../server/static-generator.js';
+import { mergeRscAssetsManifest } from './adapter-build.js';
+import { htmlEscapeJsonString } from '../server/flight-scripts.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -74,6 +87,362 @@ export function detectDynamicApis(code: string, fileId: string): StaticValidatio
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// Redirect rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a `_redirects` file from collected redirect entries.
+ * Uses the Cloudflare Pages / Netlify format: `/from /to statusCode`
+ *
+ * @internal Exported for testing.
+ */
+export function generateRedirectsFile(redirects: StaticRedirectEntry[]): string {
+  const lines = redirects.map((r) => `${r.from} ${r.to} ${r.status}`);
+  return lines.join('\n') + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// File output helpers
+// ---------------------------------------------------------------------------
+
+/** Write a file atomically: temp sibling + rename. */
+async function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void> {
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, data);
+  await rename(tmp, path);
+}
+
+/**
+ * Determine the output file path for a static page entry.
+ *
+ * Pages: /about → about/index.html, / → index.html
+ * RSC:   /about → _rsc/about.rsc, / → _rsc/index.rsc
+ * API:   /feed.xml → feed.xml, /api/data → api/data
+ */
+export function staticOutputPath(entry: StaticPageEntry): string {
+  const urlPath = entry.urlPath === '/' ? '' : entry.urlPath;
+
+  if (entry.kind === 'rsc') {
+    const rscPath = urlPath || '/index';
+    return `_rsc${rscPath}.rsc`;
+  }
+
+  if (entry.kind === 'api') {
+    // API routes use their URL path directly. If no extension, fall
+    // back to the path as-is (static host serves based on content type).
+    return urlPath.startsWith('/') ? urlPath.slice(1) : urlPath || 'index';
+  }
+
+  // HTML pages
+  if (!urlPath) return 'index.html';
+  // Synthetic 404 entry from static generation — must be 404.html at the
+  // root so static hosts (GitHub Pages, Cloudflare Pages, Netlify) serve
+  // it automatically for unmatched URLs. Uses an internal urlPath to avoid
+  // colliding with a real /404 page route.
+  if (urlPath === '/_timber_not_found') return '404.html';
+  return `${urlPath.startsWith('/') ? urlPath.slice(1) : urlPath}/index.html`;
+}
+
+// ---------------------------------------------------------------------------
+// Static generation orchestration (runs after Vite build)
+// ---------------------------------------------------------------------------
+
+interface StaticGenerateModule {
+  __timber_generateStaticSite?: (
+    options: StaticGenerationOptions
+  ) => Promise<StaticGenerationSummary>;
+}
+
+/**
+ * Load the built RSC entry and run the static generation pass.
+ *
+ * Unlike prebuilt capture, this needs the FULL pipeline handler, so
+ * __TIMBER_CAPTURE_MODE__ must be false.
+ */
+async function runStaticGeneration(ctx: PluginContext): Promise<StaticGenerationSummary> {
+  const entryPath = join(ctx.buildDir, 'rsc', 'index.js');
+  if (!existsSync(entryPath)) {
+    throw new Error(
+      `[timber] Static generation: built RSC entry not found at ${entryPath} — ` +
+        `the build output is missing`
+    );
+  }
+
+  const g = globalThis as Record<string, unknown>;
+
+  // Set up the build manifest (same as adapter-build and prebuilt-capture).
+  if (ctx.buildManifest) g.__TIMBER_BUILD_MANIFEST__ ??= ctx.buildManifest;
+  if (ctx.deploymentId) g.__TIMBER_DEPLOYMENT_ID__ ??= ctx.deploymentId;
+
+  // Ensure capture mode is off — we need the full handler.
+  g.__TIMBER_CAPTURE_MODE__ = false;
+
+  // Merge per-route CSS and modulepreload entries from the RSC assets
+  // manifest into the build manifest BEFORE rendering, so rendered HTML
+  // includes all <link> tags. This same merge normally runs in
+  // adapter-build, but static generation runs first.
+  if (ctx.buildManifest) {
+    await mergeRscAssetsManifest(ctx.buildDir, ctx.root, ctx.buildManifest, ctx.routeClientRefKeys);
+  }
+
+  console.log('[timber] Static generation: building site…');
+
+  let mod: StaticGenerateModule;
+  try {
+    const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
+    mod = (await import(/* @vite-ignore */ entryUrl)) as StaticGenerateModule;
+  } catch (error) {
+    throw new Error(
+      `[timber] Static generation: failed to load the built RSC entry (${entryPath}). ` +
+        `The full request handler must initialize for static rendering.`,
+      { cause: error }
+    );
+  }
+
+  const generate = mod.__timber_generateStaticSite;
+  if (typeof generate !== 'function') {
+    throw new Error(
+      `[timber] Static generation: built RSC entry does not export ` +
+        `__timber_generateStaticSite — rebuild from a clean build directory`
+    );
+  }
+
+  const staticDir = join(ctx.buildDir, 'static-pages');
+  // Clean stale RSC artifacts from previous builds before generating
+  // new ones. Without this, already-hashed files from a prior build
+  // would get re-hashed and accumulate in the output.
+  await rm(join(staticDir, '_rsc'), { recursive: true, force: true }).catch(() => {});
+  await mkdir(staticDir, { recursive: true });
+
+  const sitemapConfig = ctx.config.sitemap;
+  const autoSitemapEnabled = Boolean(sitemapConfig?.enabled && sitemapConfig?.baseUrl);
+
+  const contentTypes: Record<string, string> = {};
+
+  const summary = await generate({
+    autoSitemapEnabled,
+    renderTimeoutMs: ctx.config.renderTimeoutMs,
+    onEntry: async (entry: StaticPageEntry) => {
+      const relPath = staticOutputPath(entry);
+      const fullPath = resolve(staticDir, relPath);
+
+      // Reject path traversal: generated params with "../" could escape
+      // the output directory and overwrite build artifacts.
+      const rel = relative(staticDir, fullPath);
+      if (rel.startsWith('..') || resolve(staticDir, rel) !== fullPath) {
+        throw new Error(
+          `[timber] Static generation: output path "${relPath}" escapes the ` +
+            `static output directory — check generateStaticSegmentParams for ` +
+            `path traversal characters in ${entry.urlPath}`
+        );
+      }
+
+      await mkdir(dirname(fullPath), { recursive: true });
+      await writeFileAtomic(fullPath, entry.body);
+
+      // Write params sidecar for RSC entries with route params.
+      // Static .rsc files don't carry HTTP headers, so the client
+      // fetches this sidecar to populate useSegmentParams(). TIM-1246.
+      if (entry.kind === 'rsc' && entry.headers['x-timber-params']) {
+        const paramsPath = fullPath.replace(/\.rsc$/, '.params.json');
+        await writeFileAtomic(paramsPath, entry.headers['x-timber-params']);
+      }
+
+      // Track Content-Type for extensionless API routes so adapters
+      // can write per-path Content-Type rules in _headers. TIM-1241.
+      if (entry.kind === 'api' && !extname(relPath) && entry.contentType) {
+        contentTypes[entry.urlPath] = entry.contentType;
+      }
+    },
+  });
+
+  const totalUrls = summary.rendered + summary.errors.length;
+  console.log(
+    `[timber] Static generation: rendered ${summary.rendered}/${totalUrls} entries.` +
+      (summary.errors.length > 0 ? ` ${summary.errors.length} failed.` : '') +
+      (summary.redirects.length > 0 ? ` ${summary.redirects.length} redirect(s).` : '')
+  );
+
+  if (summary.errors.length > 0) {
+    const details = summary.errors.map((e) => `  - ${e.urlPath}: ${e.message}`).join('\n');
+    throw new Error(`[timber] Static generation failed:\n${details}`);
+  }
+
+  // Store content-type mappings on the plugin context so adapters
+  // can include them in the _headers file. TIM-1241.
+  if (Object.keys(contentTypes).length > 0) {
+    ctx.staticContentTypes = contentTypes;
+  }
+
+  // Hash RSC flight payloads for immutable caching (TIM-1254).
+  // Renames _rsc/*.rsc → _rsc/*-<hash>.rsc and injects a manifest
+  // into each HTML file so the client can resolve hashed URLs.
+  // Skip when client JS is disabled — no SPA navigation, no RSC fetches,
+  // and injecting a <script> tag would violate the no-JS contract.
+  if (!ctx.clientJavascript.disabled) {
+    const rscManifest = await hashRscPayloads(staticDir);
+    if (Object.keys(rscManifest).length > 0) {
+      await injectRscManifestIntoHtml(staticDir, rscManifest);
+      ctx.rscManifest = rscManifest;
+      console.log(
+        `[timber] Static generation: hashed ${Object.keys(rscManifest).length} RSC flight payloads`
+      );
+    }
+  }
+
+  // Write _redirects file for platform redirect rules (Cloudflare Pages,
+  // Netlify, etc.). Format: /from /to status. See TIM-1245.
+  if (summary.redirects.length > 0) {
+    const generated = generateRedirectsFile(summary.redirects);
+    const redirectsPath = join(staticDir, '_redirects');
+
+    // Merge with user-authored _redirects if present. TIM-1249.
+    const userRedirects = await readUserRedirects(ctx.root);
+    if (userRedirects !== null) {
+      await writeFileAtomic(redirectsPath, generated + '\n' + userRedirects);
+      console.log(
+        `[timber] Static generation: wrote _redirects with ${summary.redirects.length} ` +
+          `generated rule(s), merged with user-authored _redirects`
+      );
+    } else {
+      await writeFileAtomic(redirectsPath, generated);
+      console.log(
+        `[timber] Static generation: wrote _redirects with ${summary.redirects.length} rule(s)`
+      );
+    }
+  }
+
+  return summary;
+}
+
+// ---------------------------------------------------------------------------
+// RSC flight payload hashing (TIM-1254)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a short content hash for immutable caching.
+ * Uses 8 chars of base64url-encoded SHA-256, matching Vite's asset hash style.
+ */
+export function contentHash(data: Buffer | Uint8Array): string {
+  return createHash('sha256').update(data).digest('base64url').slice(0, 8);
+}
+
+/**
+ * Walk a directory recursively and return all file paths.
+ */
+async function walkDir(dir: string): Promise<string[]> {
+  const results: string[] = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...(await walkDir(full)));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Hash all RSC flight payloads and params sidecars in `_rsc/`, rename
+ * them with content hashes, and inject a manifest into each HTML file.
+ *
+ * Before: `_rsc/index.rsc`, `_rsc/about.rsc`
+ * After:  `_rsc/index-B7YxEKdN.rsc`, `_rsc/about-C8ZzFLfO.rsc`
+ *
+ * The manifest maps the original `_rsc/` URL to the hashed filename:
+ * `{"/_rsc/index.rsc":"/_rsc/index-B7YxEKdN.rsc", ...}`
+ *
+ * Injected into HTML as:
+ * `<script>window.__TIMBER_RSC_MANIFEST__={...}</script>`
+ *
+ * @internal Exported for testing.
+ */
+export async function hashRscPayloads(staticDir: string): Promise<Record<string, string>> {
+  const rscDir = join(staticDir, '_rsc');
+  const files = await walkDir(rscDir);
+  const manifest: Record<string, string> = {};
+
+  for (const filePath of files) {
+    if (!filePath.endsWith('.rsc') && !filePath.endsWith('.params.json')) continue;
+
+    const content = await readFile(filePath);
+    const hash = contentHash(content);
+    const rel = relative(staticDir, filePath).replace(/\\/g, '/');
+
+    // Compute hashed filename: index.rsc → index-B7YxEKdN.rsc
+    const ext = filePath.endsWith('.params.json') ? '.params.json' : '.rsc';
+    const base = filePath.slice(0, -ext.length);
+    const hashedPath = `${base}-${hash}${ext}`;
+
+    await rename(filePath, hashedPath);
+
+    const hashedRel = relative(staticDir, hashedPath).replace(/\\/g, '/');
+    manifest[`/${rel}`] = `/${hashedRel}`;
+  }
+
+  return manifest;
+}
+
+/**
+ * Inject the RSC manifest into all HTML files as a `<script>` tag
+ * before `</head>`. This lets the client resolve hashed RSC URLs
+ * without an extra network request.
+ *
+ * @internal Exported for testing.
+ */
+export async function injectRscManifestIntoHtml(
+  staticDir: string,
+  manifest: Record<string, string>
+): Promise<void> {
+  const allFiles = await walkDir(staticDir);
+  const htmlFiles = allFiles.filter((f) => f.endsWith('.html'));
+  const escapedJson = htmlEscapeJsonString(JSON.stringify(manifest));
+  const scriptTag = `<script>window.__TIMBER_RSC_MANIFEST__=${escapedJson}</script>`;
+
+  for (const htmlFile of htmlFiles) {
+    let html = await readFile(htmlFile, 'utf-8');
+    // Insert before </head> so it's available before any client JS runs
+    const headClose = html.indexOf('</head>');
+    if (headClose !== -1) {
+      html = html.slice(0, headClose) + scriptTag + html.slice(headClose);
+    } else {
+      // Fallback: prepend to body
+      html = scriptTag + html;
+    }
+    await writeFile(htmlFile, html);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// User-authored _redirects merge (TIM-1249)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a user-authored `_redirects` file from the project's `public/`
+ * directory. Returns `null` if no file exists.
+ *
+ * @internal Exported for testing.
+ */
+export async function readUserRedirects(root: string): Promise<string | null> {
+  const candidates = [join(root, 'public', '_redirects')];
+  for (const path of candidates) {
+    try {
+      return await readFile(path, 'utf-8');
+    } catch {
+      // File doesn't exist — try next
+    }
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Vite Plugin
 // ---------------------------------------------------------------------------
@@ -85,6 +454,7 @@ export function detectDynamicApis(code: string, fileId: string): StaticValidatio
  *
  * Hooks:
  * - transform: Validates source files for static mode violations
+ * - buildApp (post): Renders all routes to static HTML after the build
  */
 export function timberStaticBuild(ctx: PluginContext): Plugin {
   return {
@@ -128,5 +498,24 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
 
       return null;
     },
+
+    /**
+     * After all environments are built, render every route to static HTML.
+     *
+     * Runs with order: 'post' so the RSC plugin's buildApp completes first,
+     * producing the built entry we import. Must run BEFORE the adapter
+     * build copies output to its platform-specific directory.
+     */
+    buildApp: {
+      order: 'post' as const,
+      async handler() {
+        if (ctx.dev) return;
+
+        const isStatic = ctx.config.output === 'static';
+        if (!isStatic) return;
+
+        await runStaticGeneration(ctx);
+      },
+    },
   };
 }

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

@@ -69,6 +69,7 @@ import { capturePrebuiltPayloads } from '../prebuilt-builder.js';
 import { setPrebuiltPayloadSource } from '../prebuilt/payload-source.js';
 import { setRscFunctions, setComponentRefreshTimeout } from '../prebuilt-runtime.js';
 import { createAutoSitemapHandler } from '../sitemap-handler.js';
+import { generateStaticSite } from '../static-generator.js';
 
 /**
  * Resolve the Server-Timing mode from timber.config.ts.
@@ -461,6 +462,29 @@ export function __timber_capturePrebuilt(
   return capturePrebuiltPayloads(routeManifest, options);
 }
 
+/**
+ * Post-build static site generation entry point (TIM-1238). Renders every
+ * route in the manifest to HTML + RSC flight payloads. Must run inside the
+ * built RSC bundle — the handler, route manifest, and page module loaders
+ * are module instances in THIS bundle's graph.
+ *
+ * Unlike capture mode, this needs the full pipeline handler, so it must
+ * NOT run when __TIMBER_CAPTURE_MODE__ is set.
+ *
+ * See design/11-platform.md §"static output mode".
+ */
+export function __timber_generateStaticSite(
+  options: import('../static-generator.js').StaticGenerationOptions
+): Promise<import('../static-generator.js').StaticGenerationSummary> {
+  if (!_handler) {
+    throw new Error(
+      '[timber] __timber_generateStaticSite requires the full request handler. ' +
+        'Do not call in capture mode (__TIMBER_CAPTURE_MODE__).'
+    );
+  }
+  return generateStaticSite(routeManifest, _handler, options);
+}
+
 // Schema codecs are needed by both the capture path (param coercion) and
 // the request handler, so register them unconditionally.
 setGlobalSchemaCodecs(globalSchemaCodecs);

package/src/server/sitemap-generator.ts

@@ -339,7 +339,7 @@ export async function generateSitemap(
  * When a user-authored sitemap exists at the root, auto-generation is disabled
  * to avoid conflicts — the user takes full control.
  */
-export function hasUserSitemap(root: SegmentNode): boolean {
+export function hasUserSitemap(root: SegmentNode<unknown>): boolean {
   if (!root.metadataRoutes) return false;
   return 'sitemap' in root.metadataRoutes;
 }