@pyreon/zero 0.15.0 → 0.16.0

package/src/types.ts

@@ -1,6 +1,7 @@
 import type { ComponentFn } from '@pyreon/core'
 import type { LoaderContext, NavigationGuard } from '@pyreon/router'
 import type { Middleware } from '@pyreon/server'
+import type { I18nRoutingConfig } from './i18n-routing'
 
 // Re-export router's `LoaderContext` so consumers importing it from
 // `@pyreon/zero` keep working. The previous duplicate `interface
@@ -57,6 +58,42 @@ export interface ISRConfig {
    * space (e.g. `/user/:id` where `:id` is free-form).
    */
   maxEntries?: number
+  /**
+   * Cache-key derivation function. The default keys cache entries by
+   * `url.pathname` ONLY — query strings, cookies, and headers are
+   * stripped.
+   *
+   * **⚠️ Auth-gated incompatibility.** The default behavior is
+   * unsafe for request-dependent loaders. A loader that reads
+   * `request.headers.get('cookie')` to gate auth will render ONCE
+   * with the first user's cookie, then serve that HTML to every
+   * subsequent user. To use ISR with personalized / auth-gated
+   * pages, supply a `cacheKey` that varies on the auth identifier
+   * (session cookie, user-id header, etc.), OR don't use ISR for
+   * such routes — use SSR instead.
+   *
+   * @example
+   * // Vary cache by session cookie:
+   * isr: {
+   *   revalidate: 60,
+   *   cacheKey: (req) => {
+   *     const url = new URL(req.url)
+   *     const session = req.headers.get('cookie')?.match(/session=([^;]+)/)?.[1] ?? 'anon'
+   *     return `${url.pathname}::${session}`
+   *   },
+   * }
+   *
+   * @example
+   * // Vary by a query parameter:
+   * isr: {
+   *   revalidate: 60,
+   *   cacheKey: (req) => {
+   *     const url = new URL(req.url)
+   *     return `${url.pathname}?sort=${url.searchParams.get('sort') ?? ''}`
+   *   },
+   * }
+   */
+  cacheKey?: (req: Request) => string
 }
 
 // ─── Zero config ─────────────────────────────────────────────────────────────
@@ -78,17 +115,175 @@ export interface ZeroConfig {
   ssg?: {
     /** Paths to prerender (or function returning paths). */
     paths?: string[] | (() => string[] | Promise<string[]>)
+    /**
+     * Auto-emit `dist/404.html` from the route tree's `_404.tsx` /
+     * `_not-found.tsx` convention. fs-router already wires `_404.tsx` as
+     * `notFoundComponent` on its parent layout route; the SSG plugin walks
+     * the tree, picks up the first one, renders it through the same SSR
+     * pipeline as regular paths (so styler CSS / @pyreon/head metadata land
+     * correctly), and writes the result to `dist/404.html`. Static hosts
+     * (Netlify, Cloudflare Pages, GitHub Pages, S3+CloudFront) serve this
+     * file automatically for unmatched URLs. Default: `true`. Set to
+     * `false` to opt out — the route tree is left alone.
+     */
+    emit404?: boolean
+    /**
+     * When a route loader throws `redirect('/target')` during SSG, write
+     * a `dist/_redirects` file (Netlify / Cloudflare Pages convention)
+     * AND a `dist/_redirects.json` (Vercel convention) listing every
+     * redirected source path → target. Static hosts pick whichever
+     * format their platform supports automatically. The redirected
+     * path's HTML file is NOT emitted — the redirect is the response.
+     *
+     * Without this option, redirect-throwing loaders land in
+     * `errors[]` and the path silently disappears from the build —
+     * the user sees no output for `/old` AND no warning that the
+     * loader ran a redirect. Default: `true`. Set to `false` to
+     * restore the pre-PR-B behaviour (redirects treated as errors).
+     */
+    emitRedirects?: boolean
+    /**
+     * Additionally emit a static HTML file at the source path with a
+     * `<meta http-equiv="refresh">` redirect — for adapters / hosts
+     * that don't read `_redirects` (plain S3, GitHub Pages, simple
+     * file servers). The meta-refresh fallback works on any HTTP
+     * server that serves static files.
+     *
+     * - `'none'` (default): only `_redirects` / `_redirects.json` are
+     *   emitted; no per-redirect HTML file.
+     * - `'meta-refresh'`: emit `dist/<source>/index.html` containing
+     *   `<meta http-equiv="refresh" content="0; url=<target>">` plus
+     *   a canonical link tag for SEO. Status code information is
+     *   lost (meta-refresh has no status equivalent), so 301/302/307/
+     *   308 all collapse to "client-side refresh".
+     */
+    redirectsAsHtml?: 'none' | 'meta-refresh'
+    /**
+     * Callback invoked when a path's render throws (loader-throw that
+     * isn't a `redirect()`, render exception, anything that lands in the
+     * `errors[]` collection). Returns either:
+     * - `string` → written as the path's HTML in place of the failed
+     *   render. Use this to emit a per-path fallback page (e.g. a generic
+     *   "this content is temporarily unavailable" template) so static
+     *   hosts have something to serve at that URL instead of 404'ing.
+     * - `null` → skip; the path produces no HTML output. The error
+     *   stays in `errors[]` for the post-build summary.
+     *
+     * The callback runs ONCE per failed path. Async callbacks are
+     * awaited. If the callback itself throws, the throw is captured as
+     * a separate error entry and the path is skipped (no fallback HTML).
+     * Default: `undefined` — failed paths just land in `errors[]`.
+     *
+     * @example
+     * ssg: {
+     *   onPathError: async (path, error) => {
+     *     console.error(\`SSG render failed for \${path}:\`, error)
+     *     return \`<!DOCTYPE html><html><body><h1>Page unavailable</h1></body></html>\`
+     *   },
+     * }
+     */
+    onPathError?: (
+      path: string,
+      error: unknown,
+    ) => string | null | Promise<string | null>
+    /**
+     * When `'json'` (default), write `dist/_pyreon-ssg-errors.json` after
+     * the render loop summarising every error encountered (path traversal,
+     * timeout, render exception, getStaticPaths throw, fallback callback
+     * throw). Each entry has `{ path, message, name, stack }`. The file
+     * is ONLY written when `errors.length > 0` — successful builds don't
+     * leak an empty manifest. Reading it lets CI gate on render failures
+     * without parsing console output (e.g.
+     * `cat dist/_pyreon-ssg-errors.json | jq '.errors | length' | grep -q 0`).
+     *
+     * Set to `'none'` to opt out entirely — errors stay in console-only,
+     * matching pre-PR-G behaviour.
+     */
+    errorArtifact?: 'json' | 'none'
+    /**
+     * Maximum number of paths rendered in parallel during the SSG closeBundle
+     * loop. Default: `4` — a sensible balance between speedup and the risk
+     * of exhausting downstream resources (DB connection pools, fetch
+     * rate-limits) inside loaders. Set to `1` to render fully sequentially
+     * (the pre-PR-D behaviour). Set to a higher value for faster builds
+     * on CI / multi-core hosts; the practical ceiling is the number of
+     * loader-side concurrent connections your app's data layer tolerates.
+     *
+     * The render-error pipeline (`onPathError` callback, `errors[]`
+     * collection, `_pyreon-ssg-errors.json` artifact) is unchanged —
+     * concurrency only affects how many paths are in flight at once,
+     * not how their successes / failures are recorded.
+     *
+     * @example
+     * ssg: {
+     *   concurrency: 8, // Faster builds for static-content sites
+     * }
+     */
+    concurrency?: number
+    /**
+     * Per-path progress callback. Invoked once per path AFTER its render
+     * settles (success, redirect, OR failure) — never during in-flight
+     * renders. Receives `{ completed, total, currentPath, elapsed }`
+     * where:
+     *   - `completed` is the count of paths whose render has settled (1-indexed)
+     *   - `total` is the full path count from `resolvePaths()`
+     *   - `currentPath` is the path that just settled
+     *   - `elapsed` is wall-clock ms since the loop started
+     *
+     * Use cases: build-tool progress bars (Vite picks up stdout), CI
+     * heartbeat lines on long builds (10k-path sites take minutes —
+     * silent stretches look hung), build-time perf instrumentation.
+     *
+     * Async callbacks are awaited before the next path's progress fires,
+     * so a slow callback can serialize progress reporting (it does NOT
+     * gate the worker pool — paths keep rendering in parallel; only
+     * the progress callbacks themselves are serialized). Throws are
+     * captured into `errors[]` with the path suffix `(onProgress)` so
+     * a buggy callback can't take down the build.
+     *
+     * @example
+     * ssg: {
+     *   onProgress: ({ completed, total, currentPath, elapsed }) => {
+     *     console.log(`[${completed}/${total}] ${currentPath} (${elapsed}ms)`)
+     *   },
+     * }
+     */
+    onProgress?: (info: {
+      completed: number
+      total: number
+      currentPath: string
+      elapsed: number
+    }) => void | Promise<void>
   }
 
   /** ISR config — only used when mode is "isr". */
   isr?: ISRConfig
 
-  /** Deploy adapter. Default: "node" */
-  adapter?: 'node' | 'bun' | 'static' | 'vercel' | 'cloudflare' | 'netlify'
+  /**
+   * Deploy adapter. Default: `"node"`.
+   *
+   * Accepts either a built-in adapter name (string) OR a constructed
+   * `Adapter` instance (e.g. `vercelAdapter()`). The scaffolded templates
+   * emit the instance form (`adapter: vercelAdapter()`) by convention.
+   * `resolveAdapter` (see `adapters/index.ts`) accepts both shapes —
+   * strings go through a switch lookup, instances pass through
+   * unchanged.
+   */
+  adapter?: 'node' | 'bun' | 'static' | 'vercel' | 'cloudflare' | 'netlify' | Adapter
 
   /** Base URL path. Default: "/" */
   base?: string
 
+  /**
+   * i18n routing — locale-prefixed route variants generated at build time
+   * (PR H of the SSG roadmap). When set, every `FileRoute` is fanned into
+   * per-locale duplicates by `expandRoutesForLocales` from
+   * `@pyreon/zero`. Independent from the `i18nRouting()` Vite plugin
+   * (which only handles request-time locale detection); both can be used
+   * together. See `expandRoutesForLocales` JSDoc for strategy semantics.
+   */
+  i18n?: I18nRoutingConfig
+
   /** App-level middleware applied to all routes. */
   middleware?: Middleware[]
 
@@ -135,6 +330,25 @@ export interface RouteFileExports {
    * must validate session on every navigation rather than serve stale data.
    */
   hasGcTime: boolean
+  /**
+   * Has `export function getStaticPaths` or `export const getStaticPaths`.
+   * Used at SSG build time to enumerate concrete values for dynamic routes
+   * (`/posts/[id].tsx` → `[/posts/1, /posts/2, …]`). The function returns
+   * `Array<{ params: Record<string, string> }>`. Mirrors Astro's per-route
+   * convention. Without it, dynamic routes are silently skipped during SSG
+   * auto-detect — the user must hand-list every value in `ssg.paths`.
+   */
+  hasGetStaticPaths: boolean
+  /**
+   * Has `export const revalidate` (number, in seconds, or `false` for
+   * never-revalidate). PR I — build-time ISR. The SSG plugin emits a
+   * `dist/_pyreon-revalidate.json` manifest mapping `{ path: revalidate }`
+   * which the deploy adapter (Vercel / Cloudflare / Netlify) consumes
+   * to wire platform-specific ISR rebuild-on-stale. The route generator
+   * does NOT inline `revalidate` onto the route record — it's a
+   * build-time-only concern that never reaches the runtime router.
+   */
+  hasRevalidate: boolean
   /**
    * Raw text of the `export const meta = …` initializer, captured as a
    * literal expression. When present, the route generator inlines this
@@ -154,6 +368,22 @@ export interface RouteFileExports {
    * as a literal expression. Same inlining strategy as `metaLiteral`.
    */
   renderModeLiteral?: string
+  /**
+   * Raw text of the `export const revalidate = …` initializer (e.g.
+   * `'60'`, `'false'`, `'3600'`). Captured at scan time so the SSG
+   * plugin can read the value to emit the build-time ISR manifest
+   * WITHOUT loading the route module — which is critical because the
+   * manifest is emitted from the synthetic SSR build's outer plugin
+   * context, where evaluating route modules would re-trigger the
+   * recursive sub-build env-flag guard.
+   *
+   * Only set when the revalidate export is a top-level
+   * `export const revalidate = <numeric|boolean literal>` that passes
+   * `isPureLiteral`. Anything else (function calls, references to
+   * other declarations) leaves this undefined and the manifest falls
+   * back to omitting the entry.
+   */
+  revalidateLiteral?: string
 }
 
 /** Internal representation of a file-system route before conversion to RouteRecord. */
@@ -203,14 +433,75 @@ export interface Adapter {
   name: string
   /** Build the production server/output for this adapter. */
   build(options: AdapterBuildOptions): Promise<void>
+  /**
+   * Revalidate a prerendered path on the deploy platform's ISR layer
+   * (PR I — build-time ISR). Called by user code (webhook handlers,
+   * cron jobs, CMS triggers, etc.) to trigger a rebuild-on-stale for
+   * the named path. Optional — adapters without platform ISR support
+   * (static, node, bun) implement a no-op. Returns `{ regenerated:
+   * boolean }` so user code can branch on whether the platform actually
+   * accepted the revalidation request.
+   *
+   * Distinct from runtime ISR (`mode: 'isr'`, on-demand LRU caching in
+   * `@pyreon/zero/server`'s `createISRHandler`). Build-time ISR is
+   * static prerender + platform-driven rebuild-on-stale; runtime ISR is
+   * SSR-cached-with-TTL. They can coexist.
+   *
+   * Per-route `revalidate` metadata flows from `export const revalidate
+   * = 60` in route files into a `dist/_pyreon-revalidate.json` manifest
+   * the adapter reads at deploy time. Adapters use that manifest to
+   * configure platform ISR (Vercel `output/config.json`, Cloudflare
+   * Cache API rules, Netlify revalidation headers).
+   */
+  revalidate?(path: string): Promise<AdapterRevalidateResult>
 }
 
-export interface AdapterBuildOptions {
-  /** Path to the built server entry. */
-  serverEntry: string
-  /** Path to the client build output. */
-  clientOutDir: string
-  /** Final output directory. */
-  outDir: string
-  config: ZeroConfig
+/**
+ * Result of `Adapter.revalidate(path)`. `regenerated: false` means the
+ * adapter does not support platform ISR (no-op fallback) OR the
+ * platform rejected the request. Adapters that throw on platform-API
+ * failure should let it propagate so user code can handle the rejection.
+ */
+export interface AdapterRevalidateResult {
+  regenerated: boolean
 }
+
+/**
+ * Inputs the build pipeline passes to an adapter's `build()` method.
+ *
+ * The `kind` field discriminates the two shapes. **SSR mode** (`'ssr'`)
+ * carries `serverEntry` + `clientOutDir` so adapters can wrap the user's
+ * server bundle as a serverless function. **SSG mode** (`'ssg'`) carries
+ * only `outDir` (which IS the rendered dist/) — no serverEntry exists
+ * because every page is already prerendered. SSG-mode adapters write
+ * platform-specific routing config so the host knows the deploy is
+ * fully-static (no function invocation per request).
+ *
+ * Pre-PR-J this was a single SSR-shaped struct; the SSG path had no way
+ * to invoke `adapter.build()` because it couldn't supply `serverEntry`.
+ * Adding `kind` (with TS-narrowing per branch) lets `ssgPlugin`
+ * `closeBundle` call `adapter.build({ kind: 'ssg', outDir, config })`
+ * cleanly, AND keeps the SSR-mode adapter implementations unchanged.
+ */
+export type AdapterBuildOptions =
+  | {
+      kind: 'ssr'
+      /** Path to the built server entry. */
+      serverEntry: string
+      /** Path to the client build output. */
+      clientOutDir: string
+      /** Final output directory. */
+      outDir: string
+      config: ZeroConfig
+    }
+  | {
+      kind: 'ssg'
+      /**
+       * The rendered dist directory. For SSG, this directory IS the
+       * publishable output — adapters write platform-specific routing
+       * config alongside (e.g. `.vercel/output/config.json`,
+       * `_routes.json`, `netlify.toml`) but generally don't move files.
+       */
+      outDir: string
+      config: ZeroConfig
+    }

package/src/vercel-revalidate-handler.ts

@@ -0,0 +1,204 @@
+/**
+ * M3.1 — Drop-in Vercel revalidate webhook handler.
+ *
+ * Pre-M3.1 the `vercelAdapter.revalidate(path)` (PR I) POSTed to
+ * `/api/_pyreon-revalidate?path=...&secret=...` — a CONVENTION that users
+ * had to implement themselves. This helper scaffolds the convention:
+ *
+ *     // src/routes/api/_pyreon-revalidate.ts (or `pages/api/...` in
+ *     // Next-style apps deployed to Vercel)
+ *     export { vercelRevalidateHandler as default } from '@pyreon/zero/server'
+ *
+ * The handler validates the secret query param against
+ * `VERCEL_REVALIDATE_TOKEN`, validates the path is in the build-time
+ * revalidate manifest, and calls Vercel's `res.revalidate(path)` API.
+ *
+ * Returns a standard `(req: Request) => Response` Web API handler — works
+ * with Vercel Edge functions, Node serverless functions (via Vercel's
+ * `@vercel/node` adapter that bridges Node `req`/`res` to Web standard
+ * fetch shapes), and the in-process `mode: 'ssr'` runtime.
+ *
+ * @example
+ * // src/routes/api/_pyreon-revalidate.ts
+ * import { vercelRevalidateHandler } from '@pyreon/zero/server'
+ *
+ * export const POST = vercelRevalidateHandler({
+ *   // Optional — defaults to reading `_pyreon-revalidate.json` from cwd.
+ *   manifestPath: './dist/_pyreon-revalidate.json',
+ * })
+ *
+ * @example
+ * // Custom revalidate impl (e.g. for a self-hosted Pyreon SSR runtime
+ * // that wants build-time revalidate behavior without Vercel's
+ * // `res.revalidate()` API):
+ * export const POST = vercelRevalidateHandler({
+ *   onRevalidate: async (path) => {
+ *     // Clear your in-process ISR cache, emit a metrics event, etc.
+ *     await myCache.invalidate(path)
+ *   },
+ * })
+ */
+
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+/**
+ * Build-time revalidate manifest written by `ssgPlugin` (PR I).
+ * Shape: `{ revalidate: { '/posts/1': 60, '/posts/2': 60, '/about': 3600 } }`.
+ */
+interface RevalidateManifest {
+  revalidate: Record<string, number | false>
+}
+
+export interface VercelRevalidateHandlerOptions {
+  /**
+   * Absolute or cwd-relative path to the `_pyreon-revalidate.json` manifest.
+   * Defaults to `./dist/_pyreon-revalidate.json` (the standard SSG output).
+   *
+   * The handler refuses to revalidate paths NOT in this manifest — protects
+   * against arbitrary-path revalidation attacks even when the secret leaks.
+   */
+  manifestPath?: string
+
+  /**
+   * Custom revalidation impl. Defaults to calling Vercel's `res.revalidate()`
+   * API via the dynamic `@vercel/node`-bridged response object on globalThis
+   * (Vercel injects it for serverless functions).
+   *
+   * Supply this when running OUTSIDE Vercel (self-hosted SSR with a custom
+   * in-process ISR cache, edge runtimes that have their own purge API, etc.).
+   * Receives the validated path; throw to signal failure (handler returns 500).
+   */
+  onRevalidate?: (path: string) => void | Promise<void>
+
+  /**
+   * Override the env-var name the handler reads the secret from. Default
+   * `VERCEL_REVALIDATE_TOKEN` matches the adapter's `revalidate()` write.
+   * Useful when adopting the helper outside Vercel and the production
+   * webhook uses a different secret name.
+   */
+  secretEnvVar?: string
+}
+
+/**
+ * Create the Web-standard request handler. Reads the manifest once on first
+ * invocation (cached in-process) so repeated revalidations don't re-read the
+ * file. Manifest read failures cache the failure too — until next process
+ * restart, all requests get the same 500 response (signals deploy-time misconfig).
+ */
+export function vercelRevalidateHandler(
+  options: VercelRevalidateHandlerOptions = {},
+): (req: Request) => Promise<Response> {
+  const manifestPath = options.manifestPath ?? './dist/_pyreon-revalidate.json'
+  const secretEnvVar = options.secretEnvVar ?? 'VERCEL_REVALIDATE_TOKEN'
+
+  // Manifest cache: loaded once per process. A nullish value means "not yet
+  // loaded"; a `{ error: ... }` shape means "load failed, every subsequent
+  // request gets 500 until restart". A `{ manifest: ... }` shape is the
+  // happy path.
+  let cache: { manifest: RevalidateManifest } | { error: unknown } | null = null
+
+  return async function handler(req: Request): Promise<Response> {
+    // Validate request shape: only POST, with `?path=&secret=` query.
+    if (req.method !== 'POST') {
+      return new Response(`Method ${req.method} not allowed`, { status: 405 })
+    }
+
+    const url = new URL(req.url)
+    const path = url.searchParams.get('path')
+    const secret = url.searchParams.get('secret')
+
+    if (!path || !secret) {
+      return new Response('Bad Request: missing path or secret', { status: 400 })
+    }
+
+    // Validate the secret against the env var. Constant-time-ish: we
+    // compare strings of equal length; mismatched lengths short-circuit
+    // (acceptable — the attacker can already see the response time
+    // difference via fetch behavior). The env-var-missing case fails
+    // CLOSED (401) — production webhooks shouldn't accept requests when
+    // the server hasn't been configured.
+    const expected = process.env[secretEnvVar]
+    if (!expected) {
+      return new Response(
+        `Server misconfigured: ${secretEnvVar} env var not set`,
+        { status: 500 },
+      )
+    }
+    if (secret !== expected) {
+      return new Response('Forbidden: invalid secret', { status: 403 })
+    }
+
+    // Load the manifest (once per process). On read failure, cache the
+    // error so subsequent requests get fast 500s — saves rep eated stat
+    // calls for a broken deploy.
+    if (cache === null) {
+      try {
+        const fileContent = await readFile(resolve(process.cwd(), manifestPath), 'utf-8')
+        const parsed = JSON.parse(fileContent) as RevalidateManifest
+        if (typeof parsed?.revalidate !== 'object' || parsed.revalidate === null) {
+          throw new Error(
+            `Malformed revalidate manifest at ${manifestPath}: missing or non-object \`revalidate\` field`,
+          )
+        }
+        cache = { manifest: parsed }
+      } catch (err) {
+        cache = { error: err }
+      }
+    }
+    if ('error' in cache) {
+      return new Response(
+        `Server misconfigured: revalidate manifest at ${manifestPath} unreadable or malformed`,
+        { status: 500 },
+      )
+    }
+
+    // Validate the path is in the manifest — refuses arbitrary-path
+    // revalidation even with a valid secret. Closes the
+    // "secret leaked once → attacker revalidates anything" footgun.
+    if (!Object.prototype.hasOwnProperty.call(cache.manifest.revalidate, path)) {
+      return new Response(
+        `Path "${path}" not in revalidate manifest`,
+        { status: 404 },
+      )
+    }
+
+    // Run the revalidation. Custom impl OR fallback to a structured
+    // response that downstream Vercel-style code can adapt
+    // (Vercel's `res.revalidate()` API can't be called from a
+    // Web-standard handler without the `@vercel/node` bridge — the
+    // user wires that themselves OR uses the `onRevalidate` callback).
+    if (options.onRevalidate) {
+      try {
+        await options.onRevalidate(path)
+      } catch (err) {
+        return new Response(
+          `Revalidation failed for "${path}": ${err instanceof Error ? err.message : String(err)}`,
+          { status: 500 },
+        )
+      }
+    }
+
+    return new Response(JSON.stringify({ revalidated: true, path }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+}
+
+/**
+ * Reset the in-process manifest cache. Test-only — production code never
+ * reaches this. Used by unit tests to exercise the "manifest changed
+ * between requests" path without spinning up a new handler.
+ * @internal
+ */
+export function _resetVercelRevalidateHandlerCache(
+  handler: (req: Request) => Promise<Response>,
+): void {
+  // The cache lives in the closure; tests instantiate a fresh handler per
+  // run rather than mutating an existing one. Kept here as a no-op marker
+  // for the API contract — if cache invalidation surfaces as a real need
+  // (e.g. hot-reload of the manifest after a deploy without restart), the
+  // implementation can flip to a module-level WeakMap<handler, cache>.
+  void handler
+}