@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/adapters/raw-imports.d.ts

@@ -0,0 +1,5 @@
+// Vite ?raw import — embeds a file as a string at build time.
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

package/src/adapters/shared.ts

@@ -0,0 +1,283 @@
+// Shared adapter utilities — leaf module with zero deps on server/, client/,
+// or any Vite-dependent code.
+//
+// Adapters are loaded by Node at Vite startup time, before Vite's module
+// resolver is available. This module uses only Node built-ins and can be
+// imported by both adapters via a relative path.
+//
+// IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,
+// or any module that transitively depends on Vite. A test in
+// tests/adapters/shared-no-forbidden-imports.test.ts enforces this.
+// ../shared/ is exempt: it is dependency-free by the same rule.
+
+import { withBasePath } from '../shared/base-path.ts';
+
+/**
+ * The deployment base an adapter should write platform rules against.
+ *
+ * `config.base` is optional on `TimberConfig` because adapters can be invoked
+ * by callers that predate it (a hand-written adapter, a test harness). Falling
+ * back to `'/'` reproduces the pre-TIM-1274 output exactly, which is correct
+ * for the only deployments those callers can have: a build under a non-root
+ * base always goes through `plugins/post-build.ts`, which populates it.
+ *
+ * Typed structurally rather than as `TimberConfig` so this module keeps no
+ * import of `./types.js` at runtime.
+ */
+export function adapterBase(config: { base?: string }): string {
+  return config.base ?? '/';
+}
+
+// ─── Static asset cache headers ──────────────────────────────────────────
+
+/** Cache-Control value for hashed (immutable) assets. */
+export const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
+
+/** Cache-Control value for unhashed static assets. */
+export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
+
+/**
+ * Generate a `_headers` file for static asset cache control.
+ *
+ * The `_headers` file is a platform convention supported by Cloudflare Workers
+ * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
+ * HTTP response headers.
+ *
+ * The build's content-hashed directories (`immutableDirs`, recorded on
+ * `BuildArtifacts` by the phases that hashed them) get one wildcard rule
+ * each. When
+ * `unhashedPaths` is provided, per-file rules are appended for unhashed
+ * static assets (favicon.ico, robots.txt, etc.) so they get Cache-Control
+ * on platforms like Cloudflare Workers Static Assets where the server
+ * handler never sees static file requests.
+ *
+ * A `/*` catch-all is NOT used — it would be additive on Cloudflare,
+ * producing duplicate Cache-Control directives on hashed assets
+ * (invalid per RFC 9111).
+ *
+ * **Every rule path is written in deployed-URL space** (TIM-1274). The
+ * platform matches these patterns against the request path, which under a
+ * non-root `base` sits below the prefix: with `base: '/repo/'` the assets are
+ * at `/repo/assets/*`, so a rule saying `/assets/*` matches nothing. Silent
+ * for the cache rules (slower, still correct) and not silent for the
+ * Content-Type rules — an extensionless API route output is unreadable on
+ * Cloudflare Workers Static Assets without one.
+ *
+ * The prefix is applied at exactly one point, `rulePath()`, which every rule
+ * in this function goes through. Prefixing the wildcards and
+ * hand-checking that the per-file rules agree is how the next rule gets
+ * missed.
+ */
+// Cloudflare Workers Static Assets caps _headers at 100 rules. The wildcard
+// rules for the immutable directories come out of the same budget.
+const MAX_RULES = 100;
+
+export interface HeadersFileOptions {
+  /**
+   * The deployment base, already normalized by `normalizeBasePath()` —
+   * leading and trailing slash, `'/'` at the domain root.
+   *
+   * Required rather than defaulted: a caller that forgets it would emit
+   * root-relative rules that match nothing, which is the bug this closes.
+   */
+  base: string;
+  /**
+   * Content-hashed directories, from `BuildArtifacts.immutableDirs`. Each
+   * gets an immutable `Cache-Control` wildcard rule.
+   */
+  immutableDirs: readonly string[];
+  /** Unhashed static files (route-space paths) needing per-file cache rules. */
+  unhashedPaths?: string[];
+  /** Route-space path → Content-Type, for extensionless API route outputs. */
+  contentTypes?: Record<string, string>;
+  /**
+   * Verbatim contents of the user's `public/_headers`, appended after the
+   * generated rules. See `mergeUserHeaders` for why it goes last.
+   */
+  userRules?: string;
+}
+
+/**
+ * Count the rules in a `_headers` file — a rule is a path line, which is any
+ * line that is neither blank, a comment, nor an indented header.
+ *
+ * @internal Exported for testing.
+ */
+export function countHeaderRules(content: string): number {
+  return content
+    .split('\n')
+    .filter((line) => line.trim() !== '' && !line.startsWith('#') && !/^\s/.test(line)).length;
+}
+
+/** One `_headers` block: a path pattern and the headers it sets. */
+export interface HeaderRule {
+  pattern: string;
+  headers: Array<{ name: string; value: string }>;
+}
+
+/**
+ * Parse a `_headers` file. A non-indented, non-comment line opens a rule; the
+ * indented `Name: value` lines beneath it belong to that rule.
+ *
+ * @internal Exported for testing.
+ */
+export function parseHeaderRules(content: string): HeaderRule[] {
+  const rules: HeaderRule[] = [];
+  for (const raw of content.split('\n')) {
+    const line = raw.replace(/\r$/, '');
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue;
+    if (/^\s/.test(line)) {
+      const current = rules[rules.length - 1];
+      if (!current) continue; // header with no rule above it — not ours to fix
+      const colon = line.indexOf(':');
+      if (colon === -1) continue;
+      current.headers.push({
+        name: line.slice(0, colon).trim(),
+        value: line.slice(colon + 1).trim(),
+      });
+    } else {
+      rules.push({ pattern: line.trim(), headers: [] });
+    }
+  }
+  return rules;
+}
+
+/**
+ * Whether a user pattern can match paths a generated pattern also matches.
+ *
+ * Deliberately narrow: equality, or a prefix-glob (`/x/*`, `/*`) whose literal
+ * prefix contains the other's. Anything cleverer risks claiming an overlap
+ * that is not there, and the only thing this drives is a warning — a false
+ * positive is noise a developer cannot act on.
+ */
+function patternsOverlap(a: string, b: string): boolean {
+  if (a === b) return true;
+  const prefixOf = (p: string) => (p.endsWith('*') ? p.slice(0, -1) : null);
+  const [pa, pb] = [prefixOf(a), prefixOf(b)];
+  if (pa !== null && (b.startsWith(pa) || pa === '')) return true;
+  if (pb !== null && (a.startsWith(pb) || pb === '')) return true;
+  return false;
+}
+
+export function generateHeadersFile({
+  base,
+  immutableDirs,
+  unhashedPaths,
+  contentTypes,
+  userRules,
+}: HeadersFileOptions): string {
+  /** Route-space rule path → deployed-URL rule path. */
+  const rulePath = (path: string) => withBasePath(base, path);
+
+  // Cloudflare and Netlify apply *every* matching rule, so emitting a header
+  // the user also sets on the same path yields two definitions of it — a
+  // comma-joined `Cache-Control` that is invalid per RFC 9111, and neither
+  // side's intent. This module already refuses to emit a `/*` catch-all for
+  // that reason; appending the user's file verbatim reintroduced it through
+  // the back door (TIM-1326).
+  //
+  // An explicit app rule beats a framework default, so where the user names
+  // the same pattern and the same header, ours is dropped. Only exact pattern
+  // matches are resolved this way: silently dropping asset immutability
+  // because a `/*` rule *might* subsume it would be a worse surprise than the
+  // duplicate, so overlapping-but-different patterns warn instead.
+  const userRuleList = userRules ? parseHeaderRules(userRules) : [];
+  const overriddenExactly = new Set(
+    userRuleList.flatMap((rule) =>
+      rule.headers.map((h) => `${rule.pattern}\0${h.name.toLowerCase()}`)
+    )
+  );
+  const overridden = (pattern: string, header: string) =>
+    overriddenExactly.has(`${pattern}\0${header.toLowerCase()}`);
+
+  const warnedOverlaps = new Set<string>();
+  const emit = (pattern: string, header: string, value: string): string => {
+    if (overridden(pattern, header)) return '';
+    for (const rule of userRuleList) {
+      if (rule.pattern === pattern) continue;
+      if (!patternsOverlap(rule.pattern, pattern)) continue;
+      for (const h of rule.headers) {
+        if (h.name.toLowerCase() !== header.toLowerCase()) continue;
+        const key = `${rule.pattern}\0${pattern}\0${header.toLowerCase()}`;
+        if (warnedOverlaps.has(key)) continue;
+        warnedOverlaps.add(key);
+        console.warn(
+          `[timber] _headers: your rule "${rule.pattern}" sets ${header}, which ` +
+            `timber also sets on "${pattern}". Cloudflare and Netlify apply both, ` +
+            `so the response gets two ${header} values. Use the exact pattern ` +
+            `"${pattern}" to replace timber's rule, or narrow yours so they do ` +
+            `not overlap.`
+        );
+      }
+    }
+    return `\n${pattern}\n  ${header}: ${value}\n`;
+  };
+
+  let content = `# Auto-generated by @timber-js/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+`;
+  for (const dir of immutableDirs) {
+    content += emit(rulePath(`/${dir}/*`), 'Cache-Control', IMMUTABLE_CACHE);
+  }
+  const maxPerFileRules = MAX_RULES - immutableDirs.length;
+
+  // Content-Type rules are higher priority than cache headers for
+  // extensionless files — without them the file is unreadable.
+  const allCtEntries = contentTypes
+    ? Object.entries(contentTypes).sort(([a], [b]) => a.localeCompare(b))
+    : [];
+  const ctEntries = allCtEntries.slice(0, maxPerFileRules);
+  if (allCtEntries.length > maxPerFileRules) {
+    console.warn(
+      `[timber] _headers: ${allCtEntries.length} content-type rules exceed ` +
+        `Cloudflare's 100-rule limit. Only the first ${maxPerFileRules} ` +
+        `extensionless API routes will get Content-Type headers.`
+    );
+  }
+  const remainingBudget = maxPerFileRules - ctEntries.length;
+
+  if (unhashedPaths && unhashedPaths.length > 0) {
+    const capped = unhashedPaths.slice(0, Math.max(0, remainingBudget));
+    if (unhashedPaths.length > remainingBudget) {
+      console.warn(
+        `[timber] _headers: ${unhashedPaths.length} unhashed static files + ` +
+          `${ctEntries.length} content-type rules found, but Cloudflare limits ` +
+          `_headers to 100 rules. Only the first ${capped.length} unhashed ` +
+          `files will get Cache-Control headers.`
+      );
+    }
+    // Section bodies are built before their comment header so a section the
+    // user has overridden entirely does not leave a heading over nothing.
+    const body = capped.map((p) => emit(rulePath(p), 'Cache-Control', STATIC_CACHE)).join('');
+    if (body !== '') {
+      content += `\n# Unhashed static assets — short-lived cache with revalidation\n${body}`;
+    }
+  }
+
+  const ctBody = ctEntries
+    .map(([urlPath, ct]) => emit(rulePath(urlPath), 'Content-Type', ct))
+    .join('');
+  if (ctBody !== '') {
+    content += `\n# Content-Type for extensionless API routes\n${ctBody}`;
+  }
+
+  // User rules last, matching the `_redirects` merge. Their paths are left
+  // verbatim: `_redirects` prefixes the rules it generates because it wrote
+  // them in route space, but these are the user's own text, already authored
+  // against the URLs the site is deployed at.
+  if (userRules && userRules.trim() !== '') {
+    content += `\n# User-authored rules from public/_headers\n\n${userRules.trim()}\n`;
+
+    const total = countHeaderRules(content);
+    if (total > MAX_RULES) {
+      console.warn(
+        `[timber] _headers: ${total} rules after merging public/_headers, over ` +
+          `Cloudflare's ${MAX_RULES}-rule limit. Rules past the ` +
+          `limit are dropped by the platform — remove some, or move static ` +
+          `assets under a directory the wildcard rules already cover.`
+      );
+    }
+  }
+
+  return content;
+}

package/src/adapters/types.ts

@@ -7,24 +7,138 @@
 /**
  * Configuration passed to adapter lifecycle methods.
  * A subset of the resolved timber.config.ts relevant to adapters.
+ *
+ * Configuration only: nothing here is produced by a build phase. What the
+ * build produced — directories, the manifest initialization module, the
+ * static site — arrives separately as {@link BuildArtifacts}, and the output
+ * mode is the discriminant of that union rather than a field here, so an
+ * adapter cannot be handed a static mode with no static site (TIM-1524).
  */
 export interface TimberConfig {
-  output: 'server' | 'static';
+  /** Absolute path to the project root (Vite root). */
+  root?: string;
+  /**
+   * The resolved deployment base, normalized by `normalizeBasePath()` —
+   * leading and trailing slash, `'/'` at the domain root.
+   *
+   * Adapters write platform files (`_headers`, `_redirects`) whose rules the
+   * host matches against the *request* path, so those rules live in deployed-
+   * URL space rather than route space and need this prefix (TIM-1274).
+   *
+   * Populated by `plugins/post-build.ts` from `ctx.base`, the single copy
+   * lifted in TIM-1261. Adapters must not re-derive it from `config.base`.
+   */
+  base?: string;
   clientJavascriptDisabled?: boolean;
+}
+
+/** A directory a build phase wrote. */
+export interface DirectoryArtifact {
+  /** Absolute path. Adapters never join it against `outputDir` or `root`. */
+  readonly path: string;
+}
+
+interface BuildArtifactsBase {
+  /**
+   * The build output directory (`.timber/dist` by default) — where adapters
+   * write their own platform directory (`cloudflare/`, `nitro/`). Not the
+   * project root; that is `TimberConfig.root`.
+   */
+  readonly outputDir: string;
+  /**
+   * The browser bundle: client JS, CSS, fonts, and everything Vite copied
+   * out of `public/`. Always produced — with client JavaScript disabled it
+   * still carries the stylesheets and `public/`; adapters drop the `.js`.
+   */
+  readonly client: DirectoryArtifact;
+  /**
+   * Directories of the served tree whose every file name carries a content
+   * hash — `'assets'`, `'_timber/fonts'`, and in a static build whose RSC
+   * payloads were hashed, `'_rsc'`. Relative to the site root, `/`-separated,
+   * no leading or trailing slash, and in route space: an adapter writing
+   * platform rules adds the deployment `base` itself.
+   *
+   * Each entry is recorded by the phase that hashed the files — the client
+   * environment from its `build.assetsDir`, the font plugin when it emitted a
+   * binary, static generation when it hashed payloads — so adapters mark
+   * these immutable without knowing which plugin names or hashes what.
+   */
+  readonly immutableDirs: readonly string[];
+}
+
+/** Build products of an `output: 'server'` build. */
+export interface ServerBuildArtifacts extends BuildArtifactsBase {
+  readonly output: 'server';
+  /** The RSC server bundle. Its `index.js` is the request handler. */
+  readonly rsc: DirectoryArtifact;
+  /**
+   * The SSR bundle. The RSC bundle imports it by a path the RSC plugin
+   * computed between the two build directories — siblings named `rsc/` and
+   * `ssr/` — so adapters deploy them as siblings under those names.
+   */
+  readonly ssr: DirectoryArtifact;
   /**
-   * JS module source that sets globalThis.__TIMBER_BUILD_MANIFEST__.
-   * Written by adapters as _timber-manifest-init.js, imported before the RSC handler.
-   * Undefined when no build manifest was produced (e.g., dev mode or no client assets).
+   * `cache.component` flight payloads captured at build time (design/44).
+   * Present only when the capture pass wrote at least one payload.
    */
-  manifestInit?: string;
+  readonly prebuilt?: DirectoryArtifact;
+  /**
+   * Generated JS module source that sets `globalThis.__TIMBER_BUILD_MANIFEST__`.
+   * Must evaluate before the RSC handler; adapters
+   * write it as `_timber-manifest-init.js` or prepend it to the entry.
+   * Absent when no build manifest was produced.
+   */
+  readonly manifestInit?: string;
+}
+
+/** Build products of an `output: 'static'` build. */
+export interface StaticBuildArtifacts extends BuildArtifactsBase {
+  readonly output: 'static';
+  /**
+   * The pre-rendered site: `path/index.html`, RSC payloads under `_rsc/`
+   * (content-hashed unless client JavaScript is disabled), API route
+   * outputs, `404.html`, and a generated `_redirects` when any redirect was
+   * captured.
+   */
+  readonly pages: DirectoryArtifact;
+  /**
+   * Content-Type for each extensionless API route output, keyed by URL path
+   * (e.g. `/api/data` → `application/json`). Adapters write these as
+   * `_headers` rules; a static host cannot infer them from a file name.
+   * See TIM-1241.
+   */
+  readonly contentTypes: Readonly<Record<string, string>>;
+}
+
+/**
+ * Everything a `timber build` produced, as the adapter consumes it.
+ *
+ * Each field is recorded by the phase that wrote it. The two optional fields
+ * are the two products a build can legitimately lack — `prebuilt` (nothing
+ * captured) and `manifestInit` (no build manifest) — and adapters branch on
+ * their presence (`if (artifacts.prebuilt)`) rather than probing the
+ * filesystem.
+ */
+export type BuildArtifacts = ServerBuildArtifacts | StaticBuildArtifacts;
+
+/**
+ * What `timber preview` asks an adapter to serve. Preview runs in a later
+ * process with no build in memory, so it gets the output directory and the
+ * configured mode rather than {@link BuildArtifacts}; the mode is what tells
+ * an adapter whether a server entry exists to run at all.
+ */
+export interface PreviewTarget {
+  readonly output: 'server' | 'static';
+  /** The build output directory `buildOutput` wrote its platform directory into. */
+  readonly outputDir: string;
 }
 
 /**
  * The formal adapter interface. An adapter transforms the build output
  * into a deployable artifact for a specific platform.
  *
- * Adapters are small: they receive the build output directory and
- * transform or copy it into whatever shape the platform expects.
+ * Adapters are small: they receive a description of what the build
+ * produced and transform or copy it into whatever shape the platform expects.
  */
 export interface TimberPlatformAdapter {
   /** Unique adapter name (e.g. 'cloudflare', 'node', 'bun'). */
@@ -34,20 +148,16 @@ export interface TimberPlatformAdapter {
    * Transform the build output for the target platform.
    * Called at the end of `timber build`.
    */
-  buildOutput(config: TimberConfig, buildDir: string): Promise<void>;
+  buildOutput(config: TimberConfig, artifacts: BuildArtifacts): Promise<void>;
 
   /**
    * Start a local preview server for the built output.
-   * Falls back to the built-in Node.js preview server if not provided.
-   */
-  preview?(config: TimberConfig, buildDir: string): Promise<void>;
-
-  /**
-   * Register a promise to be kept alive after the response is sent.
-   * Maps to platform-specific lifecycle extension (e.g. ctx.waitUntil()
-   * on Cloudflare Workers). Undefined if the platform doesn't support it.
+   * Falls back to Vite's preview server if not provided.
+   *
+   * Runs in a later process than the build (`timber preview`); see
+   * {@link PreviewTarget}.
    */
-  waitUntil?(promise: Promise<unknown>): void;
+  preview?(config: TimberConfig, target: PreviewTarget): Promise<void>;
 
   /**
    * Send 103 Early Hints to the client before the final response.

package/src/adapters/wrangler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type stub for the optional `wrangler` peer dependency.
+ * Prevents TS2307 during declaration emit when wrangler is not installed.
+ */
+declare module 'wrangler' {
+  export function getPlatformProxy(opts?: any): Promise<any>;
+}