toiljs 0.0.59 → 0.0.61

package/src/compiler/template-build.ts

@@ -14,6 +14,15 @@
  * `Slot` enum + `HASH`. A route (or layout) that throws under static markup
  * (e.g. it uses router hooks outside the supported subset) is skipped with a
  * warning and falls back to pure client rendering.
+ *
+ * The `Slot` enum + `HASH` is also what the SERVER `render` imports, so it must
+ * exist BEFORE the server compiles. The build therefore runs the render in two
+ * passes: a slots PRE-PASS (`extractServerSlots`, before the server build) emits
+ * the server-importable `<server>/_ssr/<name>.slots.ts` so toilscript can compile
+ * the `render`; the FINAL pass (`extractTemplates`, after the Vite client build)
+ * rewrites it against the real built shell so the `HASH` is authoritative, and
+ * reports whether it rotated so the caller can recompile the server once. This is
+ * what makes a clean build need ZERO hand-maintained slots.
  */
 
 import fs from 'node:fs';
@@ -146,46 +155,81 @@ export function writeTemplateArtifacts(ssrDir: string, art: TemplateArtifacts):
     fs.writeFileSync(path.join(ssrDir, `${art.name}.slots.ts`), art.slotsModule);
 }
 
-/** A file-safe, identifier-ish name for a route pattern (`/u/:name` -> `u_name`). */
-export function routeTemplateName(pattern: string): string {
-    const n = pattern.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
-    return n.length > 0 ? n : 'index';
+/**
+ * The server source dir (where toilscript-compiled modules live): the dir of the first toilconfig
+ * entry, else `<root>/server`. Mirrors the same resolution in `emails.ts` (`_emails.ts` lives here).
+ */
+function serverDir(root: string): string {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8')) as {
+            entries?: unknown;
+        };
+        const first = Array.isArray(cfg.entries)
+            ? cfg.entries.find((e): e is string => typeof e === 'string')
+            : undefined;
+        if (first) return path.dirname(path.resolve(root, first));
+    } catch {
+        // fall through to the default
+    }
+    return path.join(root, 'server');
 }
 
-/** Synthesize a sample param set for a pattern's dynamic segments. */
-function sampleParams(pattern: string): Record<string, string> {
-    const params: Record<string, string> = {};
-    for (const m of pattern.matchAll(/[:*]+([A-Za-z0-9_]+)/g)) {
-        params[m[1]] = 'sample';
+/**
+ * The build-owned dir that holds the GENERATED, server-importable `<name>.slots.ts` modules
+ * (the `Slot` enum + `HASH` the guest `render` imports). It sits inside the server source tree so
+ * toilscript compiles it, named `_ssr` to match the generated `_emails.ts` convention, and is
+ * gitignored + regenerated every build — never hand-edited. The server `render` imports
+ * `./_ssr/<name>.slots`.
+ */
+export function serverSlotsDir(root: string): string {
+    return path.join(serverDir(root), '_ssr');
+}
+
+/**
+ * (Re)write the generated `<server>/_ssr/<name>.slots.ts` module(s) the server `render` imports.
+ * Returns the map of `name -> module source` actually on disk afterwards, so the caller can detect
+ * whether a later authoritative extraction changed the `HASH` and a server recompile is needed.
+ * Only rewrites a file whose content actually changed (keeps mtimes stable for the dev watcher).
+ */
+export function writeServerSlotsModules(
+    root: string,
+    modules: { name: string; slotsModule: string }[],
+): Map<string, string> {
+    const dir = serverSlotsDir(root);
+    const written = new Map<string, string>();
+    if (modules.length === 0) return written;
+    fs.mkdirSync(dir, { recursive: true });
+    for (const m of modules) {
+        const file = path.join(dir, `${m.name}.slots.ts`);
+        let prev: string | null = null;
+        try {
+            prev = fs.readFileSync(file, 'utf8');
+        } catch {
+            // first build for this route: no prior module
+        }
+        if (prev !== m.slotsModule) fs.writeFileSync(file, m.slotsModule);
+        written.set(m.name, m.slotsModule);
     }
-    return params;
+    return written;
 }
 
-interface RouteModule {
-    default: ComponentType;
-    ssr?: boolean;
-    loader?: (args: { params: Record<string, string>; searchParams: URLSearchParams }) => unknown;
+/** A rendered SSR route plus the artifacts the build emits for it. */
+interface RenderedRoute {
+    pattern: string;
+    art: TemplateArtifacts;
 }
 
 /**
- * Render every `export const ssr = true` route to `<outDir>/_ssr/<name>.{tmpl,
- * slots,slots.ts}` + a `templates.json` index, and copy the `.tmpl`/`.slots`
- * into the edge host bundle at `hosts/<host>/_tmpl/`. Returns the patterns
- * generated. Skips (with a warning) any route that throws under static markup.
+ * Spin up a short-lived Vite SSR server, render every `export const ssr = true` route under its
+ * layout chain (with sample loader data, in sentinel mode) against `shell`, and return the
+ * per-route artifacts. Shared by the pre-pass (`extractServerSlots`, slots only) and the final
+ * `extractTemplates` (full artifacts). A route (or layout) that throws under static markup is
+ * skipped with a warning and omitted from the result, so it falls back to client rendering.
  */
-export async function extractTemplates(
-    cfg: ResolvedToilConfig,
-    hostName = 'edge',
-): Promise<string[]> {
+async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<RenderedRoute[]> {
     const routes = scanRoutes(cfg.routesAbsDir).filter((r) => r.slot === undefined && !r.intercept);
     if (routes.length === 0) return [];
 
-    const outDir = path.resolve(cfg.root, cfg.outDir);
-    const stashed = path.join(cfg.toilDir, 'shell.html');
-    const shellPath = fs.existsSync(stashed) ? stashed : path.join(outDir, 'index.html');
-    if (!fs.existsSync(shellPath)) return [];
-    const shell = fs.readFileSync(shellPath, 'utf8');
-
     const warn = (msg: string): void => {
         process.stderr.write(`  toil: SSR ${msg}\n`);
     };
@@ -223,11 +267,7 @@ export async function extractTemplates(
         renderToStaticMarkup: typeof renderToStaticMarkup;
     };
 
-    const ssrDir = path.join(outDir, '_ssr');
-    const hostsTmplDir = path.join(cfg.root, 'hosts', hostName, '_tmpl');
-    const generated: string[] = [];
-    const index: { route: string; name: string; hash: string }[] = [];
-
+    const rendered: RenderedRoute[] = [];
     try {
         for (const r of routes) {
             let mod: RouteModule;
@@ -270,18 +310,7 @@ export async function extractTemplates(
                     createElement: react.createElement,
                     renderToStaticMarkup: reactDomServer.renderToStaticMarkup,
                 });
-                writeTemplateArtifacts(ssrDir, art);
-                fs.mkdirSync(hostsTmplDir, { recursive: true });
-                fs.copyFileSync(
-                    path.join(ssrDir, `${name}.tmpl`),
-                    path.join(hostsTmplDir, `${name}.tmpl`),
-                );
-                fs.copyFileSync(
-                    path.join(ssrDir, `${name}.slots`),
-                    path.join(hostsTmplDir, `${name}.slots`),
-                );
-                index.push({ route: r.pattern, name, hash: art.hash.toString('hex') });
-                generated.push(r.pattern);
+                rendered.push({ pattern: r.pattern, art });
             } catch (err) {
                 warn(
                     `skipped ${r.pattern} (render failed: ${
@@ -293,6 +322,178 @@ export async function extractTemplates(
     } finally {
         await server.close();
     }
+    return rendered;
+}
+
+/**
+ * Resolve the HTML shell to splice routes into. The authoritative shell is the BUILT (post-Vite)
+ * `index.html`, whose hashed `<script>`/`<link>` tags are part of the template and therefore the
+ * coherence `HASH`. `preferBuilt` (the final extraction) demands it; the slots PRE-PASS (which runs
+ * before Vite) falls back to the previous build's shell when present (so an unchanged rebuild's
+ * pre-pass `HASH` already matches the final one and no server recompile is needed), and finally to
+ * the un-built `.toil/index.html` template on a first clean build. Returns `null` when no shell
+ * exists at all (no client build yet and no template), so the caller no-ops.
+ */
+function resolveShell(cfg: ResolvedToilConfig, preferBuilt: boolean): string | null {
+    const outDir = path.resolve(cfg.root, cfg.outDir);
+    const builtIndex = path.join(outDir, 'index.html');
+    const stashed = path.join(cfg.toilDir, 'shell.html');
+    const templateIndex = path.join(cfg.toilDir, 'index.html');
+    const order = preferBuilt
+        ? [stashed, builtIndex]
+        : // Pre-pass (before Vite): use a prior build's shell if it exists so the HASH is stable
+          // across rebuilds; otherwise the generated (un-built) template, which still yields the
+          // correct Slot ids (the final pass reconciles the HASH).
+          [builtIndex, stashed, templateIndex];
+    for (const p of order) {
+        if (fs.existsSync(p)) return fs.readFileSync(p, 'utf8');
+    }
+    return null;
+}
+
+/**
+ * SLOTS PRE-PASS (runs BEFORE the server build): render every `ssr = true` route to its `Slot`
+ * enum + `HASH` and write the server-importable `<server>/_ssr/<name>.slots.ts` module(s), so the
+ * server `render` can import them when toilscript compiles it. On a clean build no `.slots.ts`
+ * exists yet, so this is what bootstraps it; on a rebuild it refreshes them. The `Slot` ids are
+ * always correct (they depend only on the route's hole structure); the `HASH` is final only when a
+ * prior build's shell is reused, so the final `extractTemplates` reconciles it (and the caller
+ * recompiles the server if it rotated). Returns the modules written keyed by route name.
+ */
+export async function extractServerSlots(cfg: ResolvedToilConfig): Promise<Map<string, string>> {
+    const shell = resolveShell(cfg, false);
+    if (shell === null) return new Map();
+    const rendered = await renderSsrRoutes(cfg, shell);
+    return writeServerSlotsModules(
+        cfg.root,
+        rendered.map((r) => ({ name: r.art.name, slotsModule: r.art.slotsModule })),
+    );
+}
+
+/** One SSR route's in-memory dev template: the spliceable `.tmpl` plus its
+ * top-level slot insertion points (numeric id -> byte offset), parsed from the
+ * `.slots` manifest. Used by the dev server to serve SSR without a prod build. */
+export interface DevSsrTemplate {
+    pattern: string;
+    name: string;
+    tmpl: Buffer;
+    entries: { id: number; offset: number }[];
+}
+
+/**
+ * Render every `ssr = true` route against the given (live, Vite-transformed) dev
+ * `shell` into an in-memory template + slot offsets, for the dev server to splice
+ * the guest `render` values into. Unlike {@link extractTemplates} this has NO
+ * side effects (it writes nothing and does not touch `server/_ssr` or the host
+ * bundle); the dev server builds together with the guest, so there is no hash to
+ * reconcile. Returns `[]` when no route opts in.
+ */
+export async function extractDevSsrTemplates(
+    cfg: ResolvedToilConfig,
+    shell: string,
+): Promise<DevSsrTemplate[]> {
+    const rendered = await renderSsrRoutes(cfg, shell);
+    return rendered.map(({ pattern, art }) => {
+        // Parse the `.slots` manifest: 46-byte header (n_slots at offset 44),
+        // then 8-byte entries (u32 offset, u16 id, u8 kind, u8 reserved).
+        const bin = art.slotsBin;
+        const n = bin.readUInt16LE(44);
+        const entries: { id: number; offset: number }[] = [];
+        let o = 46;
+        for (let i = 0; i < n; i++) {
+            entries.push({ offset: bin.readUInt32LE(o), id: bin.readUInt16LE(o + 4) });
+            o += 8;
+        }
+        return { pattern, name: art.name, tmpl: art.tmpl, entries };
+    });
+}
+
+/** A file-safe, identifier-ish name for a route pattern (`/u/:name` -> `u_name`). */
+export function routeTemplateName(pattern: string): string {
+    const n = pattern.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return n.length > 0 ? n : 'index';
+}
+
+/** Synthesize a sample param set for a pattern's dynamic segments. */
+function sampleParams(pattern: string): Record<string, string> {
+    const params: Record<string, string> = {};
+    for (const m of pattern.matchAll(/[:*]+([A-Za-z0-9_]+)/g)) {
+        params[m[1]] = 'sample';
+    }
+    return params;
+}
+
+interface RouteModule {
+    default: ComponentType;
+    ssr?: boolean;
+    loader?: (args: { params: Record<string, string>; searchParams: URLSearchParams }) => unknown;
+}
+
+/** The outcome of the final {@link extractTemplates} pass. */
+export interface ExtractResult {
+    /** The route patterns that produced a template. */
+    readonly generated: string[];
+    /**
+     * Whether the AUTHORITATIVE `<server>/_ssr/<name>.slots.ts` module(s) just written differ from
+     * the ones the server was already compiled against (`priorServerSlots`). True means the `HASH`
+     * (or `Slot` ids) rotated after the server build, so the server must be recompiled to bake the
+     * correct `HASH` (otherwise the host rejects the guest's stale hash as a deploy skew).
+     */
+    readonly serverSlotsChanged: boolean;
+}
+
+/**
+ * FINAL pass (runs AFTER the client/Vite build): render every `export const ssr = true` route to
+ * `<outDir>/_ssr/<name>.{tmpl,slots,slots.ts}` + a `templates.json` index, copy the `.tmpl`/`.slots`
+ * into the edge host bundle at `hosts/<host>/_tmpl/`, AND (re)write the server-importable
+ * `<server>/_ssr/<name>.slots.ts` module(s) — now against the real built shell, so the `HASH` is
+ * authoritative. Skips (with a warning) any route that throws under static markup.
+ *
+ * `priorServerSlots` is the module map the slots PRE-PASS wrote (what the server was compiled
+ * against); compared against the authoritative modules here to report whether a server recompile is
+ * needed (see {@link ExtractResult.serverSlotsChanged}).
+ */
+export async function extractTemplates(
+    cfg: ResolvedToilConfig,
+    hostName = 'edge',
+    priorServerSlots: Map<string, string> = new Map(),
+): Promise<ExtractResult> {
+    const shell = resolveShell(cfg, true);
+    if (shell === null) return { generated: [], serverSlotsChanged: false };
+
+    const rendered = await renderSsrRoutes(cfg, shell);
+
+    const outDir = path.resolve(cfg.root, cfg.outDir);
+    const ssrDir = path.join(outDir, '_ssr');
+    const hostsTmplDir = path.join(cfg.root, 'hosts', hostName, '_tmpl');
+    const generated: string[] = [];
+    const index: { route: string; name: string; hash: string }[] = [];
+
+    for (const { pattern, art } of rendered) {
+        writeTemplateArtifacts(ssrDir, art);
+        fs.mkdirSync(hostsTmplDir, { recursive: true });
+        fs.copyFileSync(
+            path.join(ssrDir, `${art.name}.tmpl`),
+            path.join(hostsTmplDir, `${art.name}.tmpl`),
+        );
+        fs.copyFileSync(
+            path.join(ssrDir, `${art.name}.slots`),
+            path.join(hostsTmplDir, `${art.name}.slots`),
+        );
+        index.push({ route: pattern, name: art.name, hash: art.hash.toString('hex') });
+        generated.push(pattern);
+    }
+
+    // Write the AUTHORITATIVE server-importable slots module(s) (the real built-shell HASH) and
+    // detect whether they changed since the pre-pass the server was compiled against.
+    const authoritative = writeServerSlotsModules(
+        cfg.root,
+        rendered.map((r) => ({ name: r.art.name, slotsModule: r.art.slotsModule })),
+    );
+    let serverSlotsChanged = false;
+    for (const [name, mod] of authoritative) {
+        if (priorServerSlots.get(name) !== mod) serverSlotsChanged = true;
+    }
 
     if (generated.length > 0) {
         fs.mkdirSync(ssrDir, { recursive: true });
@@ -303,5 +504,5 @@ export async function extractTemplates(
             }\n`,
         );
     }
-    return generated;
+    return { generated, serverSlotsChanged };
 }