@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/adapters/cloudflare.ts

@@ -3,15 +3,21 @@
 // Primary deployment target. Generates a Workers-compatible entry point
 // and wrangler.jsonc configuration. See design/11-platform.md §"Cloudflare Workers".
 
-import { writeFile, readFile, cp, rm, readdir, access } from 'node:fs/promises';
+import { writeFile, readFile, cp, rm, readdir, access, mkdtemp, rename } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { execFile } from 'node:child_process';
-import { join, relative } from 'node:path';
+import { join } from 'node:path';
 import { parse as parseJsonc } from 'jsonc-parser';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import type { TimberPlatformAdapter, TimberConfig } from './types.ts';
+import type {
+  BuildArtifacts,
+  PreviewTarget,
+  StaticBuildArtifacts,
+  TimberPlatformAdapter,
+  TimberConfig,
+} from './types.ts';
 import {
   runSharedBuildSteps,
-  findUnhashedStaticFiles,
   buildStaticDirectoryOutput,
   writeHeadersFile,
 } from './build-output-helper.ts';
@@ -245,14 +251,14 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
   return {
     name: 'cloudflare',
 
-    async buildOutput(config: TimberConfig, buildDir: string) {
-      const outDir = join(buildDir, 'cloudflare');
+    async buildOutput(config: TimberConfig, artifacts: BuildArtifacts) {
+      const outDir = join(artifacts.outputDir, 'cloudflare');
 
       // ── Static mode: Cloudflare Pages-compatible output ──────────────
       // No Workers entry — just HTML files + client assets in a flat
       // directory that Cloudflare Pages can serve directly.
-      if (config.output === 'static' && config.staticPagesDir) {
-        await buildStaticOutput(config, buildDir, outDir, options);
+      if (artifacts.output === 'static') {
+        await buildStaticOutput(config, artifacts, outDir, options);
         return;
       }
 
@@ -264,9 +270,11 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
 
       // Steps 1–5: shared across all adapters (mkdir, copy client/rsc/ssr,
       // write _headers, write manifest-init).
+      // Prebuilt payloads are inlined into the worker below rather than
+      // copied: Workers has no filesystem to read them from.
       await runSharedBuildSteps({
         config,
-        buildDir,
+        artifacts: { ...artifacts, prebuilt: undefined },
         outDir,
         publicDirName: 'static',
       });
@@ -298,15 +306,15 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
       }
 
       // Inline prebuilt flight payloads into the worker JS module (TIM-1162).
-      // Data is read from buildDir/prebuilt/ and embedded as literals —
-      // no external Text/Data module imports needed.
-      const prebuiltData = await readPrebuiltData(buildDir);
+      // Data is read from the build's prebuilt/ artifact and embedded as
+      // literals — no external Text/Data module imports needed.
+      const prebuiltData = artifacts.prebuilt
+        ? await readPrebuiltData(artifacts.prebuilt.path)
+        : null;
       await writeFile(
         join(outDir, '_timber-prebuilt-source.js'),
         generatePrebuiltSourceModule(prebuiltData)
       );
-      // Remove the copied prebuilt/ dir — data is inlined, files aren't needed.
-      await rm(join(outDir, 'prebuilt'), { recursive: true, force: true }).catch(() => {});
 
       // Write the runtime init module — sets process.env.TIMBER_RUNTIME
       // BEFORE the RSC entry evaluates (ESM import order). Without this,
@@ -315,8 +323,8 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
       await writeFile(join(outDir, '_timber-runtime-init.js'), generateRuntimeInitModule());
 
       // Generate the Workers entry point
-      const hasManifestInit = !!config.manifestInit;
-      const workerEntry = generateWorkerEntry(outDir, outDir, hasManifestInit, hasWorkerHandlers);
+      const hasManifestInit = !!artifacts.manifestInit;
+      const workerEntry = generateWorkerEntry(hasManifestInit, hasWorkerHandlers);
       await writeFile(join(outDir, '_worker.js'), workerEntry);
 
       // Generate wrangler.jsonc — merges user's wrangler config from disk if present
@@ -326,9 +334,23 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
       await writeFile(join(outDir, 'wrangler.jsonc'), JSON.stringify(wranglerConfig, null, 2));
     },
 
-    async preview(_config: TimberConfig, buildDir: string) {
-      const cmd = generatePreviewCommand(buildDir);
-      await spawnPreviewProcess(cmd.command, cmd.args, cmd.cwd);
+    async preview(config: TimberConfig, target: PreviewTarget) {
+      const base = adapterBase(config);
+      if (target.output !== 'static' || base === '/') {
+        const cmd = generatePreviewCommand(target);
+        await spawnPreviewProcess(cmd.command, cmd.args, cmd.cwd);
+        return;
+      }
+      // A static build under a base: serve a staged copy with the site
+      // mounted at the base, as the deployment is reached.
+      const stage = await mkdtemp(join(tmpdir(), 'timber-pages-preview-'));
+      try {
+        await stagePagesPreview(join(target.outputDir, 'cloudflare'), base, stage);
+        const cmd = generatePreviewCommand(target, stage);
+        await spawnPreviewProcess(cmd.command, cmd.args, cmd.cwd);
+      } finally {
+        await rm(stage, { recursive: true, force: true });
+      }
     },
 
     // No adapter-level waitUntil: on Workers there is no ambient
@@ -342,20 +364,7 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
 // ─── Exported helpers (used by tests and build) ─────────────────────────────
 
 /** @internal Exported for testing. */
-export function generateWorkerEntry(
-  buildDir: string,
-  outDir: string,
-  hasManifestInit = false,
-  hasWorkerHandlers = false
-): string {
-  // The RSC entry is the main request handler — it exports the fetch handler as default.
-  // The Vite RSC plugin outputs it to rsc/index.js.
-  let rscEntryRelative = relative(outDir, join(buildDir, 'rsc', 'index.js'));
-  // Ensure the import path starts with ./ for ESM compatibility
-  if (!rscEntryRelative.startsWith('.')) {
-    rscEntryRelative = './' + rscEntryRelative;
-  }
-
+export function generateWorkerEntry(hasManifestInit = false, hasWorkerHandlers = false): string {
   // Build manifest init must be imported before the RSC handler so that
   // globalThis.__TIMBER_BUILD_MANIFEST__ is set when the virtual module evaluates.
   // ESM guarantees imports are evaluated in order.
@@ -381,7 +390,7 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 // for cache.component payloads.
 import './_timber-runtime-init.js'
 import './_timber-prebuilt-source.js'
-${manifestImport}import handler, { runWithWaitUntil, runWithWorkersCachePurge, stripHeadBody } from '${rscEntryRelative}'
+${manifestImport}import handler, { runWithWaitUntil, runWithWorkersCachePurge, stripHeadBody } from './rsc/index.js'
 ${handlersImport}
 
 // Bind Cloudflare env to ALS so getCloudflareBindings() works at runtime.
@@ -560,35 +569,26 @@ export interface PrebuiltModuleData {
 }
 
 /**
- * Discover and read prebuilt flight payload files from the build directory.
- * Returns null when no prebuilt artifacts exist (no cache.component usage).
+ * Read the prebuilt flight payloads the capture pass wrote. Called only
+ * when the build produced a `prebuilt` artifact, which always carries its
+ * `manifest.json` — so a read failure here is a real error, not absence.
  *
  * @internal Exported for testing.
  */
-export async function readPrebuiltData(buildDir: string): Promise<PrebuiltModuleData | null> {
-  const prebuiltDir = join(buildDir, 'prebuilt');
-  let manifestJson: string;
-  try {
-    manifestJson = await readFile(join(prebuiltDir, 'manifest.json'), 'utf-8');
-  } catch {
-    return null;
-  }
+export async function readPrebuiltData(prebuiltDir: string): Promise<PrebuiltModuleData> {
+  const manifestJson = await readFile(join(prebuiltDir, 'manifest.json'), 'utf-8');
   const payloads: PrebuiltModuleData['payloads'] = [];
-  try {
-    const componentDirs = await readdir(prebuiltDir, { withFileTypes: true });
-    for (const dir of componentDirs) {
-      if (!dir.isDirectory()) continue;
-      const files = await readdir(join(prebuiltDir, dir.name));
-      for (const file of files) {
-        if (file.endsWith('.flight')) {
-          const filePath = `${dir.name}/${file}`;
-          const bytes = await readFile(join(prebuiltDir, filePath));
-          payloads.push({ file: filePath, bytes });
-        }
+  const componentDirs = await readdir(prebuiltDir, { withFileTypes: true });
+  for (const dir of componentDirs) {
+    if (!dir.isDirectory()) continue;
+    const files = await readdir(join(prebuiltDir, dir.name));
+    for (const file of files) {
+      if (file.endsWith('.flight')) {
+        const filePath = `${dir.name}/${file}`;
+        const bytes = await readFile(join(prebuiltDir, filePath));
+        payloads.push({ file: filePath, bytes });
       }
     }
-  } catch {
-    // No subdirectories — manifest exists but no payloads
   }
   return { manifestJson, payloads };
 }
@@ -883,16 +883,16 @@ export function generateWranglerConfig(
  */
 export async function buildStaticOutput(
   config: TimberConfig,
-  buildDir: string,
+  artifacts: StaticBuildArtifacts,
   outDir: string,
   _options: CloudflareAdapterOptions
 ): Promise<void> {
   // Cloudflare Pages serves from the outDir root directly (no subdirectory).
   // Use '.' as publicDirName so files land at outDir/ not outDir/static/.
-  await buildStaticDirectoryOutput(config, buildDir, outDir, '.');
+  await buildStaticDirectoryOutput(config, artifacts, outDir, '.');
 
   // Write _headers file for cache control + content-type rules.
-  await writeHeadersFile(outDir, config, await findUnhashedStaticFiles(outDir));
+  await writeHeadersFile(outDir, config, artifacts);
 }
 
 // ─── Preview ─────────────────────────────────────────────────────────────────
@@ -904,9 +904,22 @@ export interface PreviewCommand {
   cwd: string;
 }
 
-/** @internal Exported for testing. */
-export function generatePreviewCommand(buildDir: string): PreviewCommand {
-  const cfDir = join(buildDir, 'cloudflare');
+/**
+ * A server build runs its Worker under `wrangler dev` with the generated
+ * wrangler.jsonc. A static build writes no Worker and no wrangler.jsonc — its
+ * output is a Pages directory (`_headers`, `_redirects`, the site) — so it
+ * is served by `wrangler pages dev`, which applies those files as Pages does.
+ *
+ * @internal Exported for testing.
+ */
+export function generatePreviewCommand(
+  { output, outputDir }: PreviewTarget,
+  pagesRoot = join(outputDir, 'cloudflare')
+): PreviewCommand {
+  if (output === 'static') {
+    return { command: 'wrangler', args: ['pages', 'dev', pagesRoot], cwd: pagesRoot };
+  }
+  const cfDir = join(outputDir, 'cloudflare');
   return {
     command: 'wrangler',
     args: ['dev', '--local', '--config', join(cfDir, 'wrangler.jsonc')],
@@ -914,6 +927,35 @@ export function generatePreviewCommand(buildDir: string): PreviewCommand {
   };
 }
 
+/** Pages config files, read from the served root; their rules are in deployed-URL space. */
+const PAGES_ROOT_FILES = ['_headers', '_redirects'];
+
+/**
+ * Stage a static Cloudflare build for `wrangler pages dev` under a non-root
+ * base. The build writes the site at the directory root (a Pages project is
+ * served at its domain root, and the base path is supplied by whatever routes
+ * to it), but its HTML requests `/repo/...` and its `_headers`/`_redirects`
+ * rules are base-prefixed. Serving the directory as-is would 404 every page
+ * and asset, so the preview mounts the site at the base and keeps the rule
+ * files at the root, where Pages reads them and where their prefixed
+ * patterns match.
+ *
+ * @param base Normalized deployment base, not `/`.
+ * @internal Exported for testing.
+ */
+export async function stagePagesPreview(
+  siteDir: string,
+  base: string,
+  stageDir: string
+): Promise<void> {
+  const mount = join(stageDir, ...base.split('/').filter(Boolean));
+  await cp(siteDir, mount, { recursive: true });
+  const rootFiles = new Set(await readdir(mount));
+  for (const name of PAGES_ROOT_FILES) {
+    if (rootFiles.has(name)) await rename(join(mount, name), join(stageDir, name));
+  }
+}
+
 /**
  * Spawn a long-running preview process and pipe stdio to the parent.
  * Resolves when the process exits.

package/src/adapters/compress-module.ts

@@ -80,16 +80,27 @@ export function inlineCompressImports(code: string): string {
   for (const { pattern, replacement } of INLINED_IMPORTS) {
     out = out.replace(pattern, replacement);
   }
-  const surviving = MODULE_SPECIFIERS.map((pattern) => pattern.exec(out)).find(Boolean);
+  assertStandalone(out, 'server/compress.ts', '_compress.mjs');
+  return out;
+}
+
+/**
+ * Throw if type-stripped server source still imports anything but a Node
+ * builtin. Such a module is emitted alone into the build output, where no
+ * specifier has anything to resolve to.
+ *
+ * @internal Shared by the standalone-module generators.
+ */
+export function assertStandalone(code: string, source: string, emitted: string): void {
+  const surviving = MODULE_SPECIFIERS.map((pattern) => pattern.exec(code)).find(Boolean);
   if (surviving) {
     throw new Error(
-      `[timber] server/compress.ts is emitted as a standalone _compress.mjs (type-stripped, ` +
+      `[timber] ${source} is emitted as a standalone ${emitted} (type-stripped, ` +
         `not bundled), so it cannot import anything at runtime. Found: ${surviving[0].trim()}\n` +
-        `  Either inline the value in adapters/compress-module.ts (see INLINED_IMPORTS) or ` +
-        `keep the dependency out of server/compress.ts.`
+        `  Either inline the value in the generator in adapters/ or ` +
+        `keep the dependency out of ${source}.`
     );
   }
-  return out;
 }
 
 /**

package/src/adapters/fs-identity.ts

@@ -21,9 +21,8 @@
  * macOS and a case-insensitive mount on Linux are both ordinary, and the
  * answer that matters is the one for the directory being written.
  *
- * Leaf module — Node built-ins only. Deliberately not in `adapters/shared.ts`,
- * which `server/asset-headers.ts` re-exports from and which therefore must
- * stay free of `node:fs` for the Workers bundle.
+ * Leaf module — Node built-ins only. Kept apart from `adapters/shared.ts`,
+ * whose rule builders are pure string functions: this one touches the disk.
  */
 
 import { writeFile, stat, rm } from 'node:fs/promises';

package/src/adapters/nitro-presets.ts

@@ -26,12 +26,6 @@ export interface PresetConfig {
   nitroPreset: string;
   /** Output directory name within the build dir. */
   outputDir: string;
-  /**
-   * Path to the server bundle directory relative to outputDir.
-   * Nitro places the bundled server entry + _chunks/ here.
-   * Most presets use `server`; Vercel uses `functions/__server.func`.
-   */
-  serverBundleDir: string;
   /** Whether the runtime supports waitUntil. */
   supportsWaitUntil: boolean;
   /** Whether the runtime supports application-level 103 Early Hints. */
@@ -46,7 +40,6 @@ export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'vercel': {
     nitroPreset: 'vercel',
     outputDir: '.vercel/output',
-    serverBundleDir: 'functions/__server.func',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'vercel',
@@ -55,7 +48,6 @@ export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'vercel-edge': {
     nitroPreset: 'vercel-edge',
     outputDir: '.vercel/output',
-    serverBundleDir: 'functions/__server.func',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'vercel-edge',
@@ -63,7 +55,6 @@ export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'netlify': {
     nitroPreset: 'netlify',
     outputDir: '.netlify/functions-internal',
-    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'netlify',
@@ -71,7 +62,6 @@ export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'netlify-edge': {
     nitroPreset: 'netlify-edge',
     outputDir: '.netlify/edge-functions',
-    serverBundleDir: 'server',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'netlify-edge',
@@ -79,7 +69,6 @@ export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'aws-lambda': {
     nitroPreset: 'aws-lambda',
     outputDir: '.output',
-    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'aws-lambda',
@@ -87,7 +76,6 @@ export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'deno-deploy': {
     nitroPreset: 'deno-deploy',
     outputDir: '.output',
-    serverBundleDir: 'server',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'deno-deploy',
@@ -95,7 +83,6 @@ export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'azure-functions': {
     nitroPreset: 'azure-functions',
     outputDir: '.output',
-    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'azure-functions',
@@ -103,7 +90,6 @@ export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'node-server': {
     nitroPreset: 'node-server',
     outputDir: '.output',
-    serverBundleDir: 'server',
     supportsWaitUntil: true,
     // Disabled by default: most node-server deployments sit behind a
     // reverse proxy (nginx, caddy, traefik) that doesn't support 103
@@ -118,7 +104,6 @@ export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'bun': {
     nitroPreset: 'bun',
     outputDir: '.output',
-    serverBundleDir: 'server',
     supportsWaitUntil: true,
     // Disabled for same reason as node-server — reverse proxies choke on 103.
     // Link headers on the 200 response are converted to 103 by CDNs.