alabjs 0.2.6 → 0.4.0

package/src/commands/build.ts

@@ -1,5 +1,6 @@
 import { build as viteBuild, type PluginOption } from "vite";
-import { resolve } from "node:path";
+import { resolve, relative, isAbsolute } from "node:path";
+import { pathToFileURL } from "node:url";
 import { spawn, execSync } from "node:child_process";
 import { existsSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
 import { loadUserConfig } from "../config.js";
@@ -94,12 +95,13 @@ async function buildSpa(cwd: string): Promise<void> {
 export async function build({ cwd, skipTypecheck = false, mode = "ssr", analyze = false }: BuildOptions) {
   if (mode === "spa") {
     console.log("  alab  building SPA (client-only)...\n");
-    const tasks: Promise<unknown>[] = [buildSpa(cwd)];
+    await buildSpa(cwd);
+    // SPA has no route manifest, but still type-check after the build so any
+    // generated types from the Vite plugin are available to tsc.
     if (!skipTypecheck) {
       console.log("  alab  type-checking...");
-      tasks.push(runTypecheck(cwd));
+      await runTypecheck(cwd);
     }
-    await Promise.all(tasks);
     return;
   }
 
@@ -143,35 +145,52 @@ export async function build({ cwd, skipTypecheck = false, mode = "ssr", analyze
     }
   }
 
-  const tasks: Promise<unknown>[] = [
-    viteBuild({
-      root: cwd,
-      plugins: [
-        (await import("alabjs-vite-plugin")).alabPlugin({ mode: "build" }),
-        ...(visualizerPlugin ? [visualizerPlugin] : []),
-      ],
-      build: {
-        outDir: resolve(cwd, ".alabjs/dist"),
-        ssrManifest: true,
-        rolldownOptions: {
-          // In SSR mode, we don't use an index.html as the entry point.
-          // Instead, we bundle the virtual client module as the main browser asset.
-          input: "/@alabjs/client",
-        },
+  await viteBuild({
+    root: cwd,
+    plugins: [
+      (await import("alabjs-vite-plugin")).alabPlugin({ mode: "build" }),
+      ...(visualizerPlugin ? [visualizerPlugin] : []),
+    ],
+    build: {
+      // Output client assets to .alabjs/dist/client/ so the production server's
+      // static handler (which serves from distDir/client/) can find them.
+      outDir: resolve(cwd, ".alabjs/dist/client"),
+      manifest: true,
+      ssrManifest: true,
+      rolldownOptions: {
+        // In SSR mode, we don't use an index.html as the entry point.
+        // Instead, we bundle the virtual client module as the main browser asset.
+        input: "/@alabjs/client",
       },
-    }),
-  ];
+    },
+  });
+
+  const distDir = resolve(cwd, ".alabjs/dist");
 
+  // Scan the app/ directory with the Rust router, normalize paths, and write
+  // route-manifest.json. Must run before writeBuildId (hash) and buildPPRShells.
+  // Also writes .alabjs/routes.d.ts — type-checking runs AFTER this so tsc can
+  // resolve the AlabRoutes union that routes.d.ts exports.
+  const manifest = await buildRouteManifest(cwd, distDir);
+
+  // Type-check after route types are written so `AlabRoutes` is resolvable.
   if (!skipTypecheck) {
     console.log("  alab  type-checking...");
-    tasks.push(runTypecheck(cwd));
+    await runTypecheck(cwd);
   }
 
-  await Promise.all(tasks);
+  // Validate all RouteLink/Link/navigate path references against the manifest.
+  // Runs after manifest generation but before the SSR bundle so type-safe route
+  // errors abort the build early with clear file + offset info.
+  await checkRouteReferences(cwd, manifest);
 
-  // Write a stable build ID for skew protection (must run after Vite so the
-  // route-manifest.json is in place for the content-hash fallback path).
-  const distDir = resolve(cwd, ".alabjs/dist");
+  // Compile all app pages, layouts, and server functions to .alabjs/dist/server/.
+  // Must run after buildRouteManifest so we have the entry list, and before
+  // buildPPRShells which imports the compiled modules.
+  await buildSsrBundle(cwd, distDir, manifest);
+
+  // Write a stable build ID for skew protection (must run after the route
+  // manifest is in place for the content-hash fallback path).
   await writeBuildId(distDir, cwd);
   await buildPPRShells(distDir, cwd);
 
@@ -242,52 +261,64 @@ async function buildPPRShells(distDir: string, cwd: string): Promise<void> {
   const pprCacheDir = resolve(cwd, PPR_CACHE_SUBDIR);
   let count = 0;
 
-  for (const route of pageRoutes) {
-    const modulePath = resolve(distDir, "server", route.file);
-    if (!existsSync(modulePath)) continue;
-
-    // Dynamic import — module is compiled ESM, importable by Node directly.
-    const mod = await import(modulePath) as {
-      default?: unknown;
-      ppr?: unknown;
-      metadata?: Record<string, unknown>;
-    };
+  // Signal to useServerData that it must not make network calls — return
+  // empty placeholders instead so components can render their static shell.
+  process.env["ALAB_PPR_PRERENDER"] = "1";
 
-    if (mod.ppr !== true) continue;
-    if (typeof mod.default !== "function") {
-      console.warn(`  alab  ppr: ${route.file} has no default export — skipping.`);
-      continue;
-    }
+  try {
+    for (const route of pageRoutes) {
+      // esbuild compiles .tsx/.ts → .js; use the compiled path.
+      const modulePath = resolve(distDir, "server", route.file.replace(/\.(tsx?)$/, ".js"));
+      if (!existsSync(modulePath)) continue;
+
+      // Dynamic import — on Windows absolute paths need a file:// URL.
+      const mod = await import(pathToFileURL(modulePath).href) as {
+        default?: unknown;
+        ppr?: unknown;
+        metadata?: Record<string, unknown>;
+      };
+
+      if (mod.ppr !== true) continue;
+      if (typeof mod.default !== "function") {
+        console.warn(`  alab  ppr: ${route.file} has no default export — skipping.`);
+        continue;
+      }
 
-    // Load layout modules (outermost → innermost).
-    const layoutPaths = findBuildLayoutFiles(route.file, distDir);
-    const layoutMods = await Promise.all(
-      layoutPaths.map((p) => import(resolve(distDir, "server", p))),
-    );
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const layouts = layoutMods.map((m: any) => m.default).filter((c: unknown) => typeof c === "function");
+      // Load layout modules (outermost → innermost).
+      const layoutPaths = findBuildLayoutFiles(route.file, distDir);
+      const layoutMods = await Promise.all(
+        layoutPaths.map((p) => import(pathToFileURL(resolve(distDir, "server", p)).href)),
+      );
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const layouts = layoutMods.map((m: any) => m.default).filter((c: unknown) => typeof c === "function");
 
-    try {
-      await preRenderPPRShell({
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        Page: mod.default as any,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        layouts: layouts as any[],
-        shellOpts: {
-          metadata: (mod.metadata as never) ?? {},
-          paramsJson: "{}",
-          searchParamsJson: "{}",
-          routeFile: route.file,
-          ssr: true,
-        },
-        pprCacheDir,
-        routePath: route.path,
-      });
-      count++;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.warn(`  alab  ppr: failed to pre-render ${route.path}: ${msg}`);
+      try {
+        await preRenderPPRShell({
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          Page: mod.default as any,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          layouts: layouts as any[],
+          shellOpts: {
+            metadata: (mod.metadata as never) ?? {},
+            paramsJson: "{}",
+            searchParamsJson: "{}",
+            routeFile: route.file,
+            // PPR shells are static snapshots — client mounts via CSR (createRoot)
+            // rather than hydration to avoid mismatches with the pre-rendered HTML.
+            ssr: false,
+            layoutsJson: JSON.stringify(layoutPaths.map(p => p.replace(/\.js$/, ".tsx"))),
+          },
+          pprCacheDir,
+          routePath: route.path,
+        });
+        count++;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`  alab  ppr: failed to pre-render ${route.path}: ${msg}`);
+      }
     }
+  } finally {
+    delete process.env["ALAB_PPR_PRERENDER"];
   }
 
   if (count > 0) {
@@ -443,6 +474,219 @@ async function buildFederationExposes(
   );
 }
 
+/**
+ * Validate all `<RouteLink to>`, `<Link href>`, and `navigate()` path
+ * references in `app/` against the compiled route manifest.
+ *
+ * Fails the build with a formatted error list when unknown paths or literal
+ * bracket segments are found. Gracefully skips when the napi binary is absent.
+ */
+async function checkRouteReferences(cwd: string, manifest: RouteManifest): Promise<void> {
+  const appDir = resolve(cwd, "app");
+
+  type NapiChecker = { checkRouteRefs(appDir: string, manifestJson: string): string };
+  let napi: NapiChecker;
+  try {
+    const mod = await import("@alabjs/compiler") as unknown as { default?: NapiChecker } & NapiChecker;
+    napi = (mod.default ?? mod) as NapiChecker;
+    if (typeof napi.checkRouteRefs !== "function") return; // napi binary predates route checker
+  } catch {
+    return; // napi binary not available — skip silently
+  }
+
+  const manifestJson = JSON.stringify(manifest);
+  const violationsJson = napi.checkRouteRefs(appDir, manifestJson);
+  const violations = JSON.parse(violationsJson) as Array<{
+    file: string;
+    offset: number;
+    kind: "unknown_path" | "literal_segment";
+    path: string;
+    suggestion?: string;
+  }>;
+
+  if (violations.length === 0) return;
+
+  const lines: string[] = [
+    `\n  alab  ${violations.length} route violation${violations.length === 1 ? "" : "s"} found:\n`,
+  ];
+
+  for (const v of violations) {
+    const relFile = relative(cwd, v.file);
+    const kindLabel =
+      v.kind === "unknown_path"
+        ? "unknown path"
+        : "literal bracket — use params prop";
+    lines.push(`  ✗ ${relFile}  "${v.path}"  (${kindLabel})`);
+    if (v.suggestion) {
+      lines.push(`    → suggestion: ${v.suggestion}`);
+    }
+  }
+
+  lines.push("");
+  console.error(lines.join("\n"));
+  throw new Error(`[alabjs] Build failed: ${violations.length} route violation(s). Fix the paths above.`);
+}
+
+/**
+ * Scan `app/` with the Rust router napi, normalize absolute file paths to
+ * cwd-relative, and write `route-manifest.json` to `distDir`.
+ *
+ * Returns the in-memory manifest so callers can use it immediately without
+ * reading the file back from disk.
+ */
+async function buildRouteManifest(cwd: string, distDir: string): Promise<RouteManifest> {
+  const appDir = resolve(cwd, "app");
+  let manifest: RouteManifest = { routes: [] };
+
+  try {
+    type NapiRoutes = { buildRoutes(appDir: string): string };
+    const mod = await import("@alabjs/compiler") as unknown as { default?: NapiRoutes } & NapiRoutes;
+    const napi = (mod.default ?? mod) as NapiRoutes;
+    const json = napi.buildRoutes(appDir);
+    manifest = JSON.parse(json) as RouteManifest;
+
+    // The Rust scanner stores absolute paths; normalize to cwd-relative so the
+    // production server can construct `distDir/server/<file>` paths correctly.
+    for (const route of manifest.routes) {
+      if (isAbsolute(route.file)) {
+        route.file = relative(cwd, route.file);
+      }
+    }
+  } catch {
+    console.warn(
+      "  alab  warning: Rust compiler unavailable — route manifest will be empty.\n" +
+      "         Run `cargo build --release -p alab-napi && bash scripts/copy-napi-binary.sh`.",
+    );
+  }
+
+  mkdirSync(distDir, { recursive: true });
+  writeFileSync(resolve(distDir, "route-manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
+
+  const pages = manifest.routes.filter((r) => r.kind === "page").length;
+  const apis  = manifest.routes.filter((r) => r.kind === "api").length;
+  console.log(`  alab  routes → ${pages} page(s), ${apis} api route(s)`);
+
+  // Emit auto-generated route types so <RouteLink to="..."> and navigate() are
+  // type-safe without any manual setup. Written to .alabjs/routes.d.ts.
+  writeRouteTypes(manifest, distDir);
+
+  return manifest;
+}
+
+/**
+ * Write `.alabjs/routes.d.ts` containing the `AlabRoutes` union type and
+ * a typed `navigate` overload, auto-derived from the route manifest.
+ *
+ * Example output:
+ * ```ts
+ * export type AlabRoutes = "/" | "/about" | `/users/${string}`;
+ * ```
+ *
+ * Add `".alabjs/routes.d.ts"` to `tsconfig.json` `include` to enable
+ * type-checking on `<RouteLink to>`, `<Link href>`, and `navigate()`.
+ */
+function writeRouteTypes(manifest: RouteManifest, distDir: string): void {
+  const pageRoutes = manifest.routes.filter((r) => r.kind === "page");
+
+  // Convert alab `[param]` syntax → TypeScript template literal `${string}`.
+  const routeTypes = pageRoutes.map((r) => {
+    const tsPath = r.path.replace(/\[([^\]]+)\]/g, "${string}");
+    // Static path → plain string literal; dynamic path → template literal.
+    return tsPath.includes("${") ? `\`${tsPath}\`` : JSON.stringify(tsPath);
+  });
+
+  const unionType = routeTypes.length > 0 ? routeTypes.join(" | ") : "string";
+
+  const content = [
+    "// AUTO-GENERATED by `alab build` — do not edit manually.",
+    "// Add \".alabjs/routes.d.ts\" to your tsconfig.json `include` array to enable",
+    "// type-checking on <RouteLink to>, <Link href>, and navigate().",
+    "",
+    `export type AlabRoutes = ${unionType};`,
+    "",
+    "declare module \"alabjs/router\" {",
+    "  export function navigate(path: AlabRoutes, opts?: { replace?: boolean }): void;",
+    "}",
+    "",
+    "declare module \"alabjs/components\" {",
+    "  import type { ComponentProps } from \"react\";",
+    "  interface RouteLinkProps extends Omit<ComponentProps<\"a\">, \"href\"> {",
+    "    to: AlabRoutes;",
+    "    replace?: boolean;",
+    "  }",
+    "  export function RouteLink(props: RouteLinkProps): JSX.Element;",
+    "  export function Link(props: RouteLinkProps): JSX.Element;",
+    "}",
+    "",
+  ].join("\n");
+
+  writeFileSync(resolve(distDir, "routes.d.ts"), content, "utf8");
+}
+
+/**
+ * Compile all SSR route files to `distDir/server/` using esbuild's per-file
+ * transpilation mode.
+ *
+ * We use esbuild directly (bundled with Vite) rather than a second viteBuild
+ * call because:
+ *  1. Preserves directory structure via `outbase` without needing
+ *     `preserveModules` (which hangs with some Rolldown versions).
+ *  2. `packages: "external"` externalizes all npm specifiers while inlining
+ *     local relative imports — avoids Node ESM extensionless-import failures.
+ *  3. Much faster: no second Vite startup overhead.
+ */
+async function buildSsrBundle(cwd: string, distDir: string, manifest: RouteManifest): Promise<void> {
+  const entryFiles = manifest.routes.map((r) => resolve(cwd, r.file));
+
+  // Include top-level middleware.ts if present.
+  const middlewarePath = resolve(cwd, "middleware.ts");
+  if (existsSync(middlewarePath)) entryFiles.push(middlewarePath);
+
+  if (entryFiles.length === 0) return;
+
+  // Build the import.meta.env replacement object for esbuild.
+  // Node.js never defines import.meta.env (it's a Vite-only concept), so if
+  // we leave it undefined the compiled server modules throw at runtime on any
+  // reference to import.meta.env.*. We mirror exactly what Vite inlines for
+  // the client build: standard constants + ALAB_PUBLIC_* / VITE_* vars.
+  const publicEnv: Record<string, string> = {};
+  for (const [key, val] of Object.entries(process.env)) {
+    if (key.startsWith("ALAB_PUBLIC_") || key.startsWith("VITE_")) {
+      publicEnv[key] = val ?? "";
+    }
+  }
+  const metaEnv = {
+    PROD: true,
+    DEV: false,
+    SSR: true,
+    MODE: "production",
+    BASE_URL: "/",
+    ...publicEnv,
+  };
+
+  const { build: esbuild } = await import("esbuild");
+  await esbuild({
+    entryPoints: entryFiles,
+    outbase: cwd,      // preserve directory structure: app/page.tsx → server/app/page.js
+    outdir: resolve(distDir, "server"),
+    format: "esm",
+    platform: "node",
+    target: "node22",
+    bundle: true,      // bundle local imports (resolves extensionless paths)
+    packages: "external", // keep all npm specifiers (react, alabjs/*…) as-is
+    jsx: "automatic",
+    jsxImportSource: "react",
+    logLevel: "warning",
+    define: {
+      // Replace the entire import.meta.env expression so property accesses,
+      // destructuring, and optional-chaining all resolve correctly at runtime.
+      "import.meta.env": JSON.stringify(metaEnv),
+    },
+  });
+
+  console.log("  alab  SSR bundle → .alabjs/dist/server");
+}
+
 /** Compile the offline service worker to a standalone iife bundle. */
 async function buildOfflineSw(cwd: string): Promise<void> {
   const swEntry = new URL("../client/offline-sw.js", import.meta.url).pathname;
@@ -461,7 +705,10 @@ async function buildOfflineSw(cwd: string): Promise<void> {
           fileName: () => "offline-sw.js",
         },
         minify: true,
-        rolldownOptions: { output: { inlineDynamicImports: true } },
+        // Note: do NOT set rolldownOptions.output.inlineDynamicImports here.
+        // iife format sets codeSplitting:false which already implies
+        // inlineDynamicImports:true in Rolldown. Setting it explicitly
+        // produces a warning that can cause the build to stall in Rolldown/Vite 8+.
       },
     });
   } catch (err) {