@tschk/moonshine-compiler 0.3.1

package/README.md

@@ -0,0 +1,27 @@
+# `@tschk/moonshine-compiler`
+
+Filesystem route discovery, static analysis, bundling, and build manifest
+output.
+
+```ts
+import { buildProject, discoverRoutes } from "@tschk/moonshine-compiler";
+
+const manifest = await buildProject({
+  projectDir: process.cwd(),
+  runtime: "bun",
+});
+
+const routes = await discoverRoutes({
+  routesDir: "./src/routes",
+});
+```
+
+Features:
+
+- `discoverRoutes` maps `src/routes` files to route patterns.
+- `analyzeModule` reads source syntax to infer route facts.
+- `classifyRoute` picks `static`, `ssr`, `island`, `spa`, or `api`.
+- `buildProject` runs `Bun.build` and writes `.moonshine/manifest.json`.
+
+See [docs/ROUTING.md](../../docs/ROUTING.md) and
+[docs/MANIFEST.md](../../docs/MANIFEST.md).

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@tschk/moonshine-compiler",
+  "version": "0.3.1",
+  "license": "ISC",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "format": "bunx prettier --check .",
+    "lint": "bunx oxlint .",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@tschk/moonshine-framework": "^0.3.1",
+    "@tschk/moonshine-router": "^0.3.1"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "^5.8.2"
+  }
+}

package/src/analyze.ts

@@ -0,0 +1,150 @@
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+
+export type ModuleFacts = {
+  clientBoundary: boolean;
+  serverOnly: boolean;
+  exportsHandler: boolean;
+  exportsLoader: boolean;
+  exportsAction: boolean;
+  requestBound: boolean;
+  interactive: boolean;
+  unresolvedDynamicImport: boolean;
+};
+
+const HTTP_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "OPTIONS",
+  "HEAD",
+];
+
+function getSourceFile(file: string, program?: ts.Program): ts.SourceFile {
+  if (program) {
+    const source = program.getSourceFile(file);
+    if (source) return source;
+  }
+  const text = readFileSync(file, "utf8");
+  const scriptKind = file.endsWith(".tsx")
+    ? ts.ScriptKind.TSX
+    : ts.ScriptKind.TS;
+  return ts.createSourceFile(
+    file,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    scriptKind,
+  );
+}
+
+function isUseClientDirective(source: ts.SourceFile, node: ts.Node): boolean {
+  if (!ts.isExpressionStatement(node)) return false;
+  if (node.parent !== source) return false;
+  if (!ts.isStringLiteral(node.expression)) return false;
+  return node.expression.text === "use client";
+}
+
+function isExportedName(node: ts.Node, name: string): boolean {
+  const flags = ts.getCombinedModifierFlags(node as ts.Declaration);
+  if (!(flags & ts.ModifierFlags.Export)) return false;
+  if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) {
+    return node.name?.text === name;
+  }
+  if (ts.isVariableDeclaration(node)) {
+    if (ts.isIdentifier(node.name)) return node.name.text === name;
+  }
+  if (
+    ts.isExportDeclaration(node) &&
+    node.exportClause &&
+    ts.isNamedExports(node.exportClause)
+  ) {
+    for (const elem of node.exportClause.elements) {
+      if (elem.name.text === name) return true;
+    }
+  }
+  return false;
+}
+
+function isExportedHandler(node: ts.Node): boolean {
+  if (isExportedName(node, "handler")) return true;
+  for (const method of HTTP_METHODS) {
+    if (isExportedName(node, method)) return true;
+  }
+  return false;
+}
+
+function isRequestBoundImport(node: ts.Node): boolean {
+  if (!ts.isImportDeclaration(node)) return false;
+  if (!ts.isStringLiteral(node.moduleSpecifier)) return false;
+  const text = node.moduleSpecifier.text.toLowerCase();
+  return (
+    text.includes("cookies") ||
+    text.includes("headers") ||
+    text.includes("request")
+  );
+}
+
+function isNonLiteralDynamicImport(node: ts.Node): boolean {
+  if (!ts.isCallExpression(node)) return false;
+  if (node.expression.kind !== ts.SyntaxKind.ImportKeyword) return false;
+  const arg = node.arguments[0];
+  return arg !== undefined && !ts.isStringLiteral(arg);
+}
+
+function isJsxEventAttribute(node: ts.Node): boolean {
+  if (!ts.isJsxAttribute(node)) return false;
+  const name = ts.isIdentifier(node.name) ? node.name.text : undefined;
+  return !!name && /^on[A-Z]/.test(name);
+}
+
+function isIslandCall(node: ts.Node): boolean {
+  if (!ts.isCallExpression(node)) return false;
+  const expr = node.expression;
+  if (ts.isIdentifier(expr)) return expr.text === "island";
+  if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.name)) {
+    return expr.name.text === "island";
+  }
+  return false;
+}
+
+function getFileSuffix(file: string): "server" | "client" | undefined {
+  const lower = file.toLowerCase();
+  if (lower.endsWith(".server.ts") || lower.endsWith(".server.tsx"))
+    return "server";
+  if (lower.endsWith(".client.ts") || lower.endsWith(".client.tsx"))
+    return "client";
+  return undefined;
+}
+
+export function analyzeModule(file: string, program?: ts.Program): ModuleFacts {
+  const source = getSourceFile(file, program);
+  const suffix = getFileSuffix(file);
+  const facts: ModuleFacts = {
+    clientBoundary: suffix === "client",
+    serverOnly: suffix === "server",
+    exportsHandler: false,
+    exportsLoader: false,
+    exportsAction: false,
+    requestBound: false,
+    interactive: false,
+    unresolvedDynamicImport: false,
+  };
+
+  function visit(node: ts.Node) {
+    if (isUseClientDirective(source, node)) facts.clientBoundary = true;
+    if (isExportedHandler(node)) facts.exportsHandler = true;
+    if (isExportedName(node, "loader")) facts.exportsLoader = true;
+    if (isExportedName(node, "action")) facts.exportsAction = true;
+    if (isRequestBoundImport(node)) facts.requestBound = true;
+    if (isNonLiteralDynamicImport(node)) facts.unresolvedDynamicImport = true;
+    if (isJsxEventAttribute(node)) facts.interactive = true;
+    if (isIslandCall(node)) facts.interactive = true;
+    ts.forEachChild(node, visit);
+  }
+
+  visit(source);
+  return facts;
+}

package/src/build.ts

@@ -0,0 +1,183 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import type { RouteArtifact } from "@tschk/moonshine-framework";
+import { toPosix } from "./path.js";
+
+export type BundleAsset = {
+  file: string;
+  path: string;
+  integrity: string;
+};
+
+export type BundleOutput = {
+  server: BundleAsset[];
+  client: BundleAsset[];
+  entryFiles: {
+    server: string;
+    client?: string;
+  };
+};
+
+function importPath(from: string, to: string): string {
+  const rel = toPosix(relative(from, to));
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+function generateServerEntry(
+  buildDir: string,
+  routes: RouteArtifact[],
+): string {
+  const imports: string[] = [];
+  const bodies: string[] = [];
+  const moduleHelpers: string[] = [];
+  const moduleBodys: string[] = [];
+  for (let i = 0; i < routes.length; i++) {
+    const route = routes[i]!;
+    const modulePath = importPath(buildDir, route.file);
+    imports.push(`import * as route_${i} from "${modulePath}";`);
+    if (route.dataFile) {
+      const dataPath = importPath(buildDir, route.dataFile);
+      imports.push(`import * as data_${i} from "${dataPath}";`);
+    }
+    const dataRef = route.dataFile ? `data_${i}` : "undefined";
+    bodies.push(`  "${route.path}": { module: route_${i}, data: ${dataRef} }`);
+    moduleHelpers.push(`function makeModule_${i}(mod, data) {
+  const m = { ...mod, ...data };
+  if (!m.loader && typeof mod.GET === "function") {
+    m.loader = (ctx) => mod.GET(ctx.request);
+  }
+  if (!m.action && typeof mod.POST === "function") {
+    m.action = (ctx) => mod.POST(ctx.request);
+  }
+  if (!m.loader && !m.action && typeof mod.handler === "function") {
+    m.loader = (ctx) => mod.handler(ctx.request);
+  }
+  return m;
+}`);
+    const moduleVar = `module_${i}`;
+    moduleBodys.push(`  "${route.id}": ${moduleVar},
+  "${toPosix(route.file)}": ${moduleVar}${
+    route.dataFile
+      ? `,
+  "${toPosix(route.dataFile)}": ${moduleVar}`
+      : ""
+  }`);
+  }
+  return `${imports.join("\n")}\n\n${moduleHelpers.join("\n")}\n\nconst ${routes.map((_, i) => `module_${i} = makeModule_${i}(route_${i}, ${routes[i]!.dataFile ? `data_${i}` : "undefined"})`).join(";\nconst ")};\n\nexport const routes = {\n${bodies.join(",\n")}\n};\n\nexport const modules = {\n${moduleBodys.join(",\n")}\n};\n`;
+}
+
+function generateClientEntry(
+  buildDir: string,
+  routes: RouteArtifact[],
+): string | undefined {
+  const clientRoutes = routes.filter(
+    (r) => r.mode === "island" || r.mode === "spa",
+  );
+  if (clientRoutes.length === 0) return undefined;
+  const imports: string[] = [];
+  const body: string[] = [];
+  let index = 0;
+  for (const route of clientRoutes) {
+    const modulePath = importPath(buildDir, route.file);
+    imports.push(`import route_${index} from "${modulePath}";`);
+    body.push(`  "${route.path}": route_${index}`);
+    index++;
+  }
+  return `${imports.join("\n")}\n\nexport const islands = {\n${body.join(",\n")}\n};\n`;
+}
+
+async function hashFile(path: string): Promise<string> {
+  const file = Bun.file(path);
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(await file.bytes());
+  return `sha256-${hasher.digest("base64")}`;
+}
+
+async function runBuild(
+  entry: string,
+  outdir: string,
+  root: string,
+  target: "bun" | "browser",
+): Promise<string[]> {
+  const result = await Bun.build({
+    entrypoints: [entry],
+    outdir,
+    root,
+    target,
+    format: "esm",
+    naming: "[name].js",
+    splitting: false,
+    sourcemap: "none",
+  });
+  if (!result.success) {
+    const messages = result.logs.map((log) => log.message).join("\n");
+    throw new Error(`Bun build failed for ${target}: ${messages}`);
+  }
+  return result.outputs
+    .filter((output) => output.kind !== "sourcemap")
+    .map((output) => output.path);
+}
+
+function toOutRelative(outDir: string, outputPath: string): string {
+  return toPosix(relative(outDir, outputPath));
+}
+
+async function buildBundleAssets(
+  outDir: string,
+  outputPaths: string[],
+): Promise<BundleAsset[]> {
+  const assets: BundleAsset[] = [];
+  for (const outputPath of outputPaths) {
+    const file = toOutRelative(outDir, outputPath);
+    assets.push({
+      file,
+      path: `/${file}`,
+      integrity: await hashFile(outputPath),
+    });
+  }
+  return assets;
+}
+
+export async function buildBundles(options: {
+  root: string;
+  outDir: string;
+  routes: RouteArtifact[];
+}): Promise<BundleOutput> {
+  const buildDir = resolve(options.outDir, ".build");
+  await mkdir(buildDir, { recursive: true });
+
+  const serverEntry = join(buildDir, "server.ts");
+  await writeFile(serverEntry, generateServerEntry(buildDir, options.routes));
+
+  const clientCode = generateClientEntry(buildDir, options.routes);
+  let clientEntry: string | undefined;
+  if (clientCode) {
+    clientEntry = join(buildDir, "client.ts");
+    await writeFile(clientEntry, clientCode);
+  }
+
+  const distDir = resolve(options.outDir, "dist");
+  await mkdir(distDir, { recursive: true });
+
+  const serverOutputs = await runBuild(
+    serverEntry,
+    distDir,
+    options.root,
+    "bun",
+  );
+  const clientOutputs = clientEntry
+    ? await runBuild(clientEntry, distDir, options.root, "browser")
+    : [];
+
+  const serverAssets = await buildBundleAssets(options.outDir, serverOutputs);
+  const clientAssets = await buildBundleAssets(options.outDir, clientOutputs);
+
+  return {
+    server: serverAssets,
+    client: clientAssets,
+    entryFiles: {
+      server: serverAssets[0]?.file ?? "",
+      client: clientAssets[0]?.path,
+    },
+  };
+}

package/src/classify.ts

@@ -0,0 +1,37 @@
+import type { ModuleFacts } from "./analyze.js";
+
+export type { ModuleFacts } from "./analyze.js";
+
+export type ModeDecision = {
+  mode: "static" | "ssr" | "island" | "spa" | "api";
+  reason: string;
+};
+
+export type ClassificationInput = {
+  explicit?: "auto" | "static" | "ssr" | "island" | "spa" | "api";
+  facts: ModuleFacts;
+};
+
+export function classifyRoute(input: ClassificationInput): ModeDecision {
+  if (input.explicit && input.explicit !== "auto")
+    return { mode: input.explicit, reason: "explicit route configuration" };
+  if (input.facts.exportsHandler)
+    return { mode: "api", reason: "exports request handler" };
+  if (input.facts.clientBoundary)
+    return { mode: "spa", reason: "route root is a client boundary" };
+  if (
+    input.facts.requestBound ||
+    input.facts.serverOnly ||
+    input.facts.exportsLoader ||
+    input.facts.exportsAction
+  )
+    return { mode: "ssr", reason: "uses request-time server data" };
+  if (input.facts.interactive)
+    return { mode: "island", reason: "contains an interactive client subtree" };
+  if (!input.facts.unresolvedDynamicImport)
+    return { mode: "static", reason: "deterministic build-time route" };
+  return {
+    mode: "ssr",
+    reason: "dynamic behavior could not be resolved safely",
+  };
+}

package/src/discover.ts

@@ -0,0 +1,107 @@
+import { readdir } from "node:fs/promises";
+import { dirname, basename, join, relative, resolve } from "node:path";
+import type { RouteDefinition, RenderMode } from "@tschk/moonshine-framework";
+import { mergeRoutes } from "./inherit.js";
+import { toPosix } from "./path.js";
+
+export type DiscoverOptions = {
+  routesDir: string;
+  programmatic?: RouteDefinition[];
+};
+
+export function segmentToPattern(segment: string): string {
+  if (/^\[\.\.\.[^\]]*\]$/.test(segment)) return `*${segment.slice(4, -1)}`;
+  if (/^\[\[[^\]]+\]\]$/.test(segment)) return `:${segment.slice(2, -2)}?`;
+  if (/^\[[^\]]+\]$/.test(segment)) return `:${segment.slice(1, -1)}`;
+  return segment;
+}
+
+type FileSuffix = "server" | "client" | undefined;
+
+function parseRouteFile(
+  name: string,
+): { base: string; suffix: FileSuffix } | null {
+  const server = /^(.+)\.server\.(ts|tsx)$/.exec(name);
+  if (server) return { base: server[1]!, suffix: "server" };
+  const client = /^(.+)\.client\.(ts|tsx)$/.exec(name);
+  if (client) return { base: client[1]!, suffix: "client" };
+  const route = /^(.+)\.(ts|tsx)$/.exec(name);
+  if (route) return { base: route[1]!, suffix: undefined };
+  return null;
+}
+
+function isDataFile(name: string): boolean {
+  return /\.data\.(ts|tsx)$/.test(name);
+}
+
+async function* walkFiles(dir: string): AsyncGenerator<string> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walkFiles(full);
+    else if (entry.isFile()) yield full;
+  }
+}
+
+export async function discoverRoutes(
+  options: DiscoverOptions,
+): Promise<RouteDefinition[]> {
+  const routesDir = resolve(options.routesDir);
+  const files: string[] = [];
+  for await (const file of walkFiles(routesDir)) {
+    files.push(file);
+  }
+
+  const fileSet = new Set(files);
+  const raw: RouteDefinition[] = [];
+
+  for (const file of files) {
+    const rel = toPosix(relative(routesDir, file));
+    const dir = dirname(rel);
+    const name = basename(rel);
+
+    if (isDataFile(name)) continue;
+    if (name.startsWith("+")) continue;
+
+    const parsed = parseRouteFile(name);
+    if (!parsed) continue;
+
+    const { base, suffix } = parsed;
+    const id = dir === "." ? base : `${dir}/${base}`;
+    const dirParts = dir === "." ? [] : dir.split("/").filter(Boolean);
+    const dirPattern = dirParts.map(segmentToPattern).join("/");
+    const basePattern = base === "index" ? "" : segmentToPattern(base);
+    const routePath =
+      dirPattern || basePattern
+        ? `/${[dirPattern, basePattern].filter(Boolean).join("/")}`
+        : "/";
+
+    const dataFile = (() => {
+      const parent = dirname(file);
+      for (const ext of [".data.ts", ".data.tsx"]) {
+        const candidate = join(parent, `${base}${ext}`);
+        if (fileSet.has(candidate)) return candidate;
+      }
+      return undefined;
+    })();
+
+    const mode: RenderMode | undefined =
+      suffix === "server" ? "api" : undefined;
+
+    const route: RouteDefinition = {
+      id,
+      path: routePath,
+      file,
+      ...(dataFile && { dataFile }),
+      ...(mode && { mode }),
+    };
+
+    raw.push(route);
+  }
+
+  const merged = mergeRoutes(raw, options.programmatic ?? [], routesDir);
+  merged.sort(
+    (a, b) => a.path.localeCompare(b.path) || a.id.localeCompare(b.id),
+  );
+  return merged;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { analyzeModule, type ModuleFacts } from "./analyze.js";
+export {
+  classifyRoute,
+  type ClassificationInput,
+  type ModeDecision,
+} from "./classify.js";
+export {
+  discoverRoutes,
+  type DiscoverOptions,
+  segmentToPattern,
+} from "./discover.js";
+export { mergeRoutes } from "./inherit.js";
+export { buildProject, readManifest, type BuildOptions } from "./manifest.js";

package/src/inherit.ts

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import type { RouteDefinition } from "@tschk/moonshine-framework";
+import { createRouteGraph } from "@tschk/moonshine-router";
+import { toPosix } from "./path.js";
+
+type SpecialKind = "layout" | "error" | "middleware";
+
+function findSpecial(
+  routesDir: string,
+  dir: string,
+  kind: SpecialKind,
+): string | undefined {
+  const base = join(routesDir, dir, `+${kind}`);
+  for (const ext of [".tsx", ".ts"]) {
+    const candidate = `${base}${ext}`;
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function applyInheritance(routes: RouteDefinition[], routesDir: string): void {
+  const resolvedDir = resolve(routesDir);
+  for (const route of routes) {
+    if (!route.file) continue;
+    const rel = toPosix(relative(resolvedDir, resolve(route.file)));
+    const dir = dirname(rel);
+    const parts = dir === "." ? [] : dir.split("/").filter(Boolean);
+    const ancestors: string[] = [""];
+    let acc = "";
+    for (const part of parts) {
+      acc = acc ? `${acc}/${part}` : part;
+      ancestors.push(acc);
+    }
+
+    const layouts: string[] = [];
+    const middleware: string[] = [];
+    let errorBoundary: string | undefined;
+
+    for (const ancestor of ancestors) {
+      const layout = findSpecial(resolvedDir, ancestor, "layout");
+      if (layout) layouts.push(layout);
+      const mw = findSpecial(resolvedDir, ancestor, "middleware");
+      if (mw) middleware.push(mw);
+      const err = findSpecial(resolvedDir, ancestor, "error");
+      if (err) errorBoundary = err;
+    }
+
+    if (layouts.length) route.layouts = layouts;
+    if (middleware.length) route.middleware = middleware;
+    if (errorBoundary) route.errorBoundary = errorBoundary;
+  }
+}
+
+export function mergeRoutes(
+  filesystem: RouteDefinition[],
+  programmatic: RouteDefinition[] = [],
+  routesDir?: string,
+): RouteDefinition[] {
+  const map = new Map<string, RouteDefinition>();
+  for (const route of filesystem) {
+    map.set(route.id, route);
+  }
+  for (const route of programmatic) {
+    const existing = map.get(route.id);
+    if (existing) {
+      map.set(route.id, { ...existing, ...route });
+    } else {
+      map.set(route.id, route);
+    }
+  }
+  const merged = [...map.values()];
+  if (routesDir) applyInheritance(merged, routesDir);
+  createRouteGraph(merged);
+  return merged;
+}

package/src/manifest.ts

@@ -0,0 +1,174 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import type {
+  MoonshineManifest,
+  RouteArtifact,
+  RouteDefinition,
+  RuntimeTarget,
+} from "@tschk/moonshine-framework";
+import { MANIFEST_VERSION } from "@tschk/moonshine-framework";
+import { analyzeModule } from "./analyze.js";
+import { buildBundles } from "./build.js";
+import { classifyRoute } from "./classify.js";
+import { discoverRoutes } from "./discover.js";
+import { toPosix } from "./path.js";
+
+export type BuildOptions = {
+  projectDir: string;
+  routesDir?: string;
+  outDir?: string;
+  programmatic?: RouteDefinition[];
+  runtime?: RuntimeTarget;
+};
+
+function toProjectRelative(projectDir: string, p: string): string {
+  const rel = toPosix(relative(projectDir, resolve(p)));
+  return rel.startsWith("..") ? toPosix(p) : rel || ".";
+}
+
+async function resolveFrameworkVersion(): Promise<string> {
+  const url = import.meta.resolve("@tschk/moonshine-framework");
+  const entryPath = new URL(url).pathname;
+  const pkgPath = entryPath.split("/").slice(0, -2).join("/") + "/package.json";
+  const pkg = (await Bun.file(pkgPath).json()) as { version: string };
+  return pkg.version;
+}
+
+function sortedStringify(value: unknown): string {
+  const text = JSON.stringify(
+    value,
+    (_key, v) => {
+      if (v === undefined) return undefined;
+      if (v === null || typeof v !== "object" || Array.isArray(v)) return v;
+      const sorted: Record<string, unknown> = {};
+      for (const k of Object.keys(v as Record<string, unknown>).sort()) {
+        sorted[k] = (v as Record<string, unknown>)[k];
+      }
+      return sorted;
+    },
+    2,
+  );
+  return `${text}\n`;
+}
+
+function deriveCapabilities(
+  routes: RouteArtifact[],
+): MoonshineManifest["capabilities"] {
+  const capabilities: Set<MoonshineManifest["capabilities"][number]> =
+    new Set();
+  capabilities.add("streaming");
+  for (const route of routes) {
+    if (route.mode === "island" || route.mode === "spa") {
+      capabilities.add("islands");
+    }
+    if (route.runtime === "cloudflare" || route.runtime === "vercel-edge") {
+      capabilities.add("edge");
+    }
+    if (route.cache?.revalidate !== undefined) {
+      capabilities.add("revalidation");
+    }
+  }
+  return [...capabilities].sort();
+}
+
+function makeStaticOutput(route: RouteArtifact): string | undefined {
+  if (route.mode !== "static") return undefined;
+  if (route.path.includes("*")) return undefined;
+  const slug =
+    route.path === "/"
+      ? "index"
+      : route.path.replace(/^\/+/, "").replace(/\//g, "-");
+  return `static/${slug}.html`;
+}
+
+export async function buildProject(
+  options: BuildOptions,
+): Promise<MoonshineManifest> {
+  const projectDir = resolve(options.projectDir);
+  const routesDir = resolve(
+    options.routesDir ?? join(projectDir, "src", "routes"),
+  );
+  const outDir = resolve(options.outDir ?? join(projectDir, ".moonshine"));
+  const runtime = options.runtime ?? "bun";
+
+  const rawRoutes = await discoverRoutes({
+    routesDir,
+    programmatic: options.programmatic,
+  });
+
+  const buildRoutes: RouteArtifact[] = [];
+  for (const route of rawRoutes) {
+    const facts = analyzeModule(route.file);
+    const decision = classifyRoute({ explicit: route.mode, facts });
+    buildRoutes.push({
+      ...route,
+      mode: decision.mode,
+      runtime: route.runtime ?? runtime,
+      decision: decision.reason,
+      clientEntries: [],
+      serverEntry: undefined,
+      staticOutput: makeStaticOutput({
+        ...route,
+        mode: decision.mode,
+      } as RouteArtifact),
+    } as RouteArtifact);
+  }
+
+  await rm(outDir, { recursive: true, force: true });
+  await mkdir(outDir, { recursive: true });
+
+  const bundles = await buildBundles({
+    root: projectDir,
+    outDir,
+    routes: buildRoutes,
+  });
+  const clientFile = bundles.entryFiles.client;
+
+  for (const route of buildRoutes) {
+    if ((route.mode === "island" || route.mode === "spa") && clientFile) {
+      route.clientEntries = [clientFile];
+    }
+    route.serverEntry = bundles.entryFiles.server;
+  }
+
+  const allAssets = [...bundles.server, ...bundles.client].sort((a, b) =>
+    a.file.localeCompare(b.file),
+  );
+
+  const manifest: MoonshineManifest = {
+    version: MANIFEST_VERSION,
+    frameworkVersion: await resolveFrameworkVersion(),
+    routes: buildRoutes.map((route) => ({
+      ...route,
+      file: toProjectRelative(projectDir, route.file),
+      ...(route.dataFile && {
+        dataFile: toProjectRelative(projectDir, route.dataFile),
+      }),
+      ...(route.layouts && {
+        layouts: route.layouts.map((l) => toProjectRelative(projectDir, l)),
+      }),
+      ...(route.middleware && {
+        middleware: route.middleware.map((m) =>
+          toProjectRelative(projectDir, m),
+        ),
+      }),
+      ...(route.errorBoundary && {
+        errorBoundary: toProjectRelative(projectDir, route.errorBoundary),
+      }),
+    })) as RouteArtifact[],
+    assets: allAssets,
+    entries: {
+      ...(bundles.entryFiles.server && { server: bundles.entryFiles.server }),
+      ...(clientFile && { client: clientFile }),
+    },
+    capabilities: deriveCapabilities(buildRoutes),
+  };
+
+  await writeFile(join(outDir, "manifest.json"), sortedStringify(manifest));
+  return manifest;
+}
+
+export async function readManifest(path: string): Promise<MoonshineManifest> {
+  const text = await readFile(resolve(path), "utf8");
+  return JSON.parse(text) as MoonshineManifest;
+}

package/src/path.ts

@@ -0,0 +1,3 @@
+export function toPosix(p: string): string {
+  return p.replace(/\\/g, "/");
+}

package/test/classify.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { analyzeModule, classifyRoute } from "../src";
+
+const fixtureDir = join(import.meta.dir, "fixtures", "modes");
+
+function fixture(name: string): string {
+  return join(fixtureDir, name);
+}
+
+describe("classifyRoute", () => {
+  test("honors explicit override", () => {
+    const facts = analyzeModule(fixture("static.tsx"));
+    const decision = classifyRoute({ explicit: "island", facts });
+    expect(decision).toEqual({
+      mode: "island",
+      reason: "explicit route configuration",
+    });
+  });
+
+  test("selects api for handler export", () => {
+    const facts = analyzeModule(fixture("api.ts"));
+    expect(facts.exportsHandler).toBe(true);
+    expect(classifyRoute({ facts })).toEqual({
+      mode: "api",
+      reason: "exports request handler",
+    });
+  });
+
+  test("selects spa for root client boundary", () => {
+    const facts = analyzeModule(fixture("client.client.tsx"));
+    expect(facts.clientBoundary).toBe(true);
+    expect(classifyRoute({ facts })).toEqual({
+      mode: "spa",
+      reason: "route root is a client boundary",
+    });
+  });
+
+  test("selects ssr for request-bound loader", () => {
+    const facts = analyzeModule(fixture("loader.ts"));
+    expect(facts.requestBound).toBe(true);
+    expect(facts.exportsLoader).toBe(true);
+    expect(classifyRoute({ facts })).toEqual({
+      mode: "ssr",
+      reason: "uses request-time server data",
+    });
+  });
+
+  test("selects island for interactive child", () => {
+    const facts = analyzeModule(fixture("interactive.tsx"));
+    expect(facts.interactive).toBe(true);
+    expect(classifyRoute({ facts })).toEqual({
+      mode: "island",
+      reason: "contains an interactive client subtree",
+    });
+  });
+
+  test("selects static for deterministic module", () => {
+    const facts = analyzeModule(fixture("static.tsx"));
+    expect(classifyRoute({ facts })).toEqual({
+      mode: "static",
+      reason: "deterministic build-time route",
+    });
+  });
+
+  test("falls back to ssr for unresolved dynamic import", () => {
+    const facts = analyzeModule(fixture("unresolved.ts"));
+    expect(facts.unresolvedDynamicImport).toBe(true);
+    expect(classifyRoute({ facts })).toEqual({
+      mode: "ssr",
+      reason: "dynamic behavior could not be resolved safely",
+    });
+  });
+
+  test("produces deterministic output", () => {
+    const path = fixture("static.tsx");
+    const first = classifyRoute({ facts: analyzeModule(path) });
+    const second = classifyRoute({ facts: analyzeModule(path) });
+    expect(JSON.stringify(first)).toBe(JSON.stringify(second));
+  });
+});

package/test/discover.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { discoverRoutes } from "../src/discover";
+
+const fixtureDir = join(import.meta.dir, "fixtures", "routes");
+
+function layoutPath() {
+  return join(fixtureDir, "+layout.tsx");
+}
+
+function middlewarePath() {
+  return join(fixtureDir, "+middleware.ts");
+}
+
+function errorPath() {
+  return join(fixtureDir, "+error.tsx");
+}
+
+describe("discoverRoutes", () => {
+  test("discovers exact route IDs and paths", async () => {
+    const routes = await discoverRoutes({ routesDir: fixtureDir });
+    expect(routes.map((r) => r.id)).toEqual([
+      "index",
+      "about",
+      "account/[[tab]]",
+      "api/health",
+      "blog/[slug]",
+      "docs/[...path]",
+    ]);
+    expect(routes.map((r) => r.path)).toEqual([
+      "/",
+      "/about",
+      "/account/:tab?",
+      "/api/health",
+      "/blog/:slug",
+      "/docs/*path",
+    ]);
+  });
+
+  test("inherits layout, middleware, and nearest error boundary", async () => {
+    const routes = await discoverRoutes({ routesDir: fixtureDir });
+    for (const route of routes) {
+      expect(route.layouts).toEqual([layoutPath()]);
+      expect(route.middleware).toEqual([middlewarePath()]);
+      expect(route.errorBoundary).toBe(errorPath());
+    }
+  });
+
+  test("pairs a route with its data file", async () => {
+    const routes = await discoverRoutes({ routesDir: fixtureDir });
+    const blog = routes.find((r) => r.id === "blog/[slug]");
+    expect(blog).toBeDefined();
+    expect(blog!.dataFile).toBe(join(fixtureDir, "blog", "[slug].data.ts"));
+  });
+
+  test("marks server files as API mode", async () => {
+    const routes = await discoverRoutes({ routesDir: fixtureDir });
+    const api = routes.find((r) => r.id === "api/health");
+    expect(api).toBeDefined();
+    expect(api!.mode).toBe("api");
+  });
+
+  test("produces deterministic sorted output", async () => {
+    const first = await discoverRoutes({ routesDir: fixtureDir });
+    const second = await discoverRoutes({ routesDir: fixtureDir });
+    expect(JSON.stringify(first)).toBe(JSON.stringify(second));
+    expect(first.map((r) => r.path)).toEqual([
+      "/",
+      "/about",
+      "/account/:tab?",
+      "/api/health",
+      "/blog/:slug",
+      "/docs/*path",
+    ]);
+  });
+});

package/test/fixtures/modes/api.ts

@@ -0,0 +1,3 @@
+export function GET(_request: Request) {
+  return Response.json({ ok: true });
+}

package/test/fixtures/modes/client.client.tsx

@@ -0,0 +1,3 @@
+export default function ClientPage() {
+  return <h1>client</h1>;
+}

package/test/fixtures/modes/interactive.tsx

@@ -0,0 +1,3 @@
+export default function Counter() {
+  return <button onClick={() => {}}>+</button>;
+}

package/test/fixtures/modes/loader.ts

@@ -0,0 +1,5 @@
+import { request } from "./request";
+
+export function loader() {
+  return request.url;
+}

package/test/fixtures/modes/request.ts

@@ -0,0 +1 @@
+export const request = new Request("http://example.com");

package/test/fixtures/modes/static.tsx

@@ -0,0 +1,3 @@
+export default function Page() {
+  return <h1>static</h1>;
+}

package/test/fixtures/modes/unresolved.ts

@@ -0,0 +1,5 @@
+export default async function Page() {
+  const name = "x";
+  const mod = await import(`./${name}`);
+  return mod;
+}

package/test/fixtures/project/src/routes/+error.tsx

@@ -0,0 +1,3 @@
+export default function RootError() {
+  return <p>error</p>;
+}

package/test/fixtures/project/src/routes/+layout.tsx

@@ -0,0 +1,3 @@
+export default function RootLayout({ children }: { children: unknown }) {
+  return <>{children}</>;
+}

package/test/fixtures/project/src/routes/+middleware.ts

@@ -0,0 +1,3 @@
+export function middleware(_context: unknown, next: () => unknown): unknown {
+  return next();
+}

package/test/fixtures/project/src/routes/about.data.ts

@@ -0,0 +1,7 @@
+export function loader({ request }: { request: Request }) {
+  return new URL(request.url).pathname;
+}
+
+export function action({ request }: { request: Request }) {
+  return new URL(request.url).pathname;
+}

package/test/fixtures/project/src/routes/about.tsx

@@ -0,0 +1,7 @@
+export function loader() {
+  return { url: "/about" };
+}
+
+export default function AboutPage({ data }: { data: { url: string } }) {
+  return <h1>{data.url}</h1>;
+}

package/test/fixtures/project/src/routes/api/health.ts

@@ -0,0 +1,3 @@
+export function GET(_request: Request) {
+  return Response.json({ status: "ok" });
+}

package/test/fixtures/project/src/routes/client.client.tsx

@@ -0,0 +1,3 @@
+export default function ClientPage() {
+  return <h1>client</h1>;
+}

package/test/fixtures/project/src/routes/counter.tsx

@@ -0,0 +1,3 @@
+export default function Counter() {
+  return <button onClick={() => {}}>+</button>;
+}

package/test/fixtures/project/src/routes/docs/[...path].tsx

@@ -0,0 +1,3 @@
+export default function DocsCatchAllPage() {
+  return <h1>docs</h1>;
+}

package/test/fixtures/project/src/routes/index.tsx

@@ -0,0 +1,3 @@
+export default function IndexPage() {
+  return <h1>home</h1>;
+}

package/test/fixtures/routes/+error.tsx

@@ -0,0 +1,3 @@
+export default function RootError() {
+  return <p>error</p>;
+}

package/test/fixtures/routes/+layout.tsx

@@ -0,0 +1,3 @@
+export default function RootLayout({ children }: { children: unknown }) {
+  return <>{children}</>;
+}

package/test/fixtures/routes/+middleware.ts

@@ -0,0 +1,3 @@
+export function middleware(_context: unknown, next: () => unknown): unknown {
+  return next();
+}

package/test/fixtures/routes/about.tsx

@@ -0,0 +1,3 @@
+export default function AboutPage() {
+  return <h1>about</h1>;
+}

package/test/fixtures/routes/account/[[tab]].tsx

@@ -0,0 +1,3 @@
+export default function AccountPage() {
+  return <h1>account</h1>;
+}

package/test/fixtures/routes/api/health.server.ts

@@ -0,0 +1,7 @@
+export function GET(_request: Request) {
+  return Response.json({ status: "ok" });
+}
+
+export function POST(_request: Request) {
+  return Response.json({ status: "ok" });
+}

package/test/fixtures/routes/blog/[slug].data.ts

@@ -0,0 +1,7 @@
+export function loader({ request }: { request: Request }) {
+  return new URL(request.url).pathname;
+}
+
+export function action({ request }: { request: Request }) {
+  return new URL(request.url).pathname;
+}

package/test/fixtures/routes/blog/[slug].tsx

@@ -0,0 +1,3 @@
+export default function BlogPostPage({ data }: { data: unknown }) {
+  return <h1>{String(data)}</h1>;
+}

package/test/fixtures/routes/docs/[...path].tsx

@@ -0,0 +1,3 @@
+export default function DocsCatchAllPage() {
+  return <h1>docs</h1>;
+}

package/test/fixtures/routes/index.tsx

@@ -0,0 +1,3 @@
+export default function IndexPage() {
+  return <h1>home</h1>;
+}

package/test/manifest.test.ts

@@ -0,0 +1,91 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { existsSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { buildProject, readManifest } from "../src/manifest";
+
+const projectDir = resolve(import.meta.dir, "fixtures", "project");
+const outDir = join(projectDir, ".moonshine");
+
+function clean() {
+  if (existsSync(outDir)) {
+    rmSync(outDir, { recursive: true, force: true });
+  }
+}
+
+afterAll(clean);
+
+describe("buildProject", () => {
+  test("emits a versioned, deterministic manifest with relative paths", async () => {
+    const manifest = await buildProject({
+      projectDir,
+    });
+
+    expect(manifest.version).toBe(1);
+    expect(manifest.frameworkVersion).toMatch(/^\d+\.\d+\.\d+/);
+    expect(manifest.routes.map((r) => r.path)).toEqual([
+      "/",
+      "/about",
+      "/api/health",
+      "/client",
+      "/counter",
+      "/docs/*path",
+    ]);
+    expect(manifest.routes.map((r) => r.mode)).toEqual([
+      "static",
+      "ssr",
+      "api",
+      "spa",
+      "island",
+      "static",
+    ]);
+    expect(manifest.routes.map((r) => r.decision)).toEqual([
+      "deterministic build-time route",
+      "uses request-time server data",
+      "exports request handler",
+      "route root is a client boundary",
+      "contains an interactive client subtree",
+      "deterministic build-time route",
+    ]);
+    expect(manifest.routes.every((r) => r.runtime === "bun")).toBe(true);
+    expect(manifest.entries.server).toBe("dist/server.js");
+    expect(manifest.entries.client).toBe("/dist/client.js");
+    expect(manifest.capabilities).toEqual(["islands", "streaming"]);
+    expect(manifest.assets.map((a) => a.file)).toEqual([
+      "dist/client.js",
+      "dist/server.js",
+    ]);
+    for (const asset of manifest.assets) {
+      expect(asset.path).toBe(`/${asset.file}`);
+      expect(asset.integrity).toMatch(/^sha256-[A-Za-z0-9+/]+=?$/);
+    }
+
+    const fromDisk = await readManifest(join(outDir, "manifest.json"));
+    expect(fromDisk.version).toBe(1);
+    expect(fromDisk.routes.map((r) => r.path)).toEqual(
+      manifest.routes.map((r) => r.path),
+    );
+
+    const text = JSON.stringify(manifest);
+    expect(text).not.toMatch(/\\\\/);
+    expect(text).not.toMatch(/^\//);
+    expect(text).not.toMatch(/process\.env/);
+
+    for (const route of manifest.routes) {
+      expect(route.file.startsWith("src/")).toBe(true);
+      if (route.dataFile) expect(route.dataFile.startsWith("src/")).toBe(true);
+      if (route.layouts) {
+        for (const l of route.layouts) {
+          expect(l.startsWith("src/")).toBe(true);
+        }
+      }
+      if (route.middleware) {
+        for (const m of route.middleware) {
+          expect(m.startsWith("src/")).toBe(true);
+        }
+      }
+      if (route.errorBoundary) {
+        expect(route.errorBoundary.startsWith("src/")).toBe(true);
+      }
+    }
+  });
+});

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*", "test/**/*"]
+}