@junejs/server 0.0.2

package/src/build.ts

@@ -0,0 +1,367 @@
+// `june build` — produce a Workers-ready bundle from a June app.
+//
+// What the dev server discovers at REQUEST time (filesystem routes,
+// june.config.ts, content/ markdown), the build discovers ONCE and FREEZES into
+// a static manifest fed to createWorker(). The built worker renders through the
+// SAME pipeline as dev (pipeline.ts), so its surfaces are byte-equivalent —
+// proven by test/parity.test.ts, not hoped for.
+//
+// Two entry points:
+//   buildManifest(appRoot) → an in-process WorkerManifest (freeze only; used by
+//     the parity test and by prerender — same render path as the bundle).
+//   juneBuild(appRoot)     → the full build: content freeze + generated entry +
+//     Rolldown bundle (workerd conditions, binary externals) +
+//     prerender-through-the-worker + wrangler config.
+//
+// REMINDER #4: nothing in the worker graph may statically import node:*. The
+// content freeze (content/*.md → app/_content.ts) is what removes fs from the
+// dynamic route's graph; the worker reads frozen data, never the filesystem.
+
+import { existsSync } from "node:fs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { loadJuneConfig } from "./config-loader";
+import { resolveAgent, resolveSpeculationRules } from "@junejs/core/config";
+import { isRouteDefinition, type BrandedRoute } from "@junejs/core/route";
+import type { DocumentConfig } from "@junejs/core/document";
+import { collection } from "./content";
+import { createWorker, type WorkerManifest } from "./worker";
+import { findExtraFile } from "./router";
+import type { ExtraHandler, LayoutComponent } from "./pipeline";
+import { findClientEntry, bundleClientToFile, CLIENT_SCRIPT_URL } from "./client-bundle";
+
+export type BuildResult = {
+  outFile: string;
+  routes: string[];
+  dynamicRoutes: string[];
+  contentCollections: string[];
+  prerendered: string[];
+};
+
+// The segment layout CHAIN root→leaf: every directory level (route groups
+// included) may contribute a layout.* that wraps routes below it.
+type RouteEntry = { path: string; file: string; dynamic: boolean; layouts: string[] };
+
+const PAGE_BASENAMES = new Set(["page", "index"]);
+const ROUTE_EXTS = [".tsx", ".jsx", ".ts", ".js"];
+
+const isRouteGroup = (name: string) => /^\(.+\)$/.test(name);
+
+function segmentFile(dir: string, base: string): string | undefined {
+  return ROUTE_EXTS.map((e) => join(dir, `${base}${e}`)).find(existsSync);
+}
+
+// Walk app/ for page.* files → route paths (mirrors router.ts conventions:
+// route groups vanish from URLs, `_`-prefixed entries are private), carrying the
+// layout chain accumulated from each directory level.
+export async function scanRoutes(
+  appDir: string,
+  dir = appDir,
+  layouts: string[] = [],
+  out: RouteEntry[] = [],
+): Promise<RouteEntry[]> {
+  const ownLayout = segmentFile(dir, "layout");
+  const chain = ownLayout ? [...layouts, ownLayout] : layouts;
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const e of entries) {
+    if (e.name.startsWith("_") || e.name.startsWith(".")) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      await scanRoutes(appDir, full, chain, out);
+      continue;
+    }
+    const ext = e.name.match(/\.[^.]+$/)?.[0] ?? "";
+    if (!ROUTE_EXTS.includes(ext)) continue;
+    if (!PAGE_BASENAMES.has(basename(e.name, ext))) continue;
+    const relDir = relative(appDir, dir);
+    const segments = relDir === "" ? [] : relDir.split(sep).filter((s) => !isRouteGroup(s));
+    const path = "/" + segments.join("/");
+    out.push({ path: path === "/" ? "/" : path, file: full, dynamic: /\[.+\]/.test(path), layouts: chain });
+  }
+  return out;
+}
+
+// content/<collection>/*.md → app/_content.ts (the build-time content manifest).
+// This is the FREEZE that removes node:fs from the worker graph: routes import
+// frozen entries from ./_content instead of reading the filesystem at request.
+export async function generateContent(appRoot: string): Promise<string[]> {
+  const contentDir = join(appRoot, "content");
+  if (!existsSync(contentDir)) return [];
+  const dirs = (await readdir(contentDir, { withFileTypes: true })).filter((e) => e.isDirectory());
+  if (dirs.length === 0) return [];
+
+  let out =
+    "// AUTO-GENERATED by `june build` — edit content/**/*.md, not this file.\n" +
+    "export type ContentEntry = { slug: string; data: Record<string, string | string[]>; body: string; original: string; html: string };\n";
+  const names: string[] = [];
+  for (const d of dirs) {
+    const entries = collection(join(contentDir, d.name)).map(({ slug, data, body, original, html }) => ({
+      slug,
+      data,
+      body,
+      original,
+      html,
+    }));
+    const constName = d.name.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+    // Singular finder name: posts → post, otherwise <name>Entry.
+    const finder = d.name.endsWith("s") ? d.name.slice(0, -1) : `${d.name}Entry`;
+    out += `export const ${constName}: ContentEntry[] = ${JSON.stringify(entries, null, 2)};\n`;
+    out += `export const ${finder} = (slug: string): ContentEntry | null => ${constName}.find((p) => p.slug === slug) ?? null;\n`;
+    names.push(d.name);
+  }
+  await writeFile(join(appRoot, "app", "_content.ts"), out);
+  return names;
+}
+
+// Freeze june.config.ts → the serializable bits the worker inlines.
+export async function freezeConfig(appRoot: string): Promise<{
+  document: DocumentConfig;
+  agent: WorkerManifest["agent"];
+  earlyHints: string[];
+  buildExternal: string[];
+}> {
+  const cfg = await loadJuneConfig(appRoot);
+  // An app with a client entry gets the islands runtime URL frozen into its
+  // document. Detected HERE (not just in juneBuild) so the prerender path —
+  // which re-freezes through buildManifest — sets the SAME clientScript, keeping
+  // prerendered pages byte-equivalent to the live worker (parity).
+  const hasClient = findClientEntry(join(appRoot, "app")) !== undefined;
+  return {
+    document: {
+      site: cfg.site ?? {},
+      speculationRules: resolveSpeculationRules(cfg.speculation ?? undefined),
+      speculationDelivery: "inline",
+      viewTransitions: cfg.viewTransitions ?? true,
+      clientScript: hasClient ? CLIENT_SCRIPT_URL : null,
+    },
+    agent: resolveAgent(cfg.agent),
+    earlyHints: cfg.earlyHints ?? [],
+    buildExternal: cfg.build?.external ?? [],
+  };
+}
+
+async function importLayout(file: string): Promise<LayoutComponent | null> {
+  const mod = (await import(pathToFileURL(file).href)) as { default?: LayoutComponent };
+  return typeof mod.default === "function" ? mod.default : null;
+}
+
+// The FREEZE, in-process: import route modules + layouts, build the manifest a
+// createWorker() can run immediately. Used by prerender and by the parity test
+// (its render path is identical to the Rolldown-bundled worker).
+export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
+  const appDir = join(appRoot, "app");
+  const frozen = await freezeConfig(appRoot);
+  const scanned = (await scanRoutes(appDir)).sort((a, b) => a.path.localeCompare(b.path));
+
+  const layoutCache = new Map<string, LayoutComponent | null>();
+  const componentsFor = async (files: string[]): Promise<LayoutComponent[]> => {
+    const chain: LayoutComponent[] = [];
+    for (const f of files) {
+      if (!layoutCache.has(f)) layoutCache.set(f, await importLayout(f));
+      const c = layoutCache.get(f) ?? null;
+      if (c) chain.push(c);
+    }
+    return chain;
+  };
+
+  const routes: Record<string, BrandedRoute> = {};
+  const dynamicRoutes: Array<{ pattern: string; def: BrandedRoute }> = [];
+  const layoutChains: Record<string, LayoutComponent[]> = {};
+
+  for (const r of scanned) {
+    const mod = (await import(pathToFileURL(r.file).href)) as { default?: unknown };
+    if (!isRouteDefinition(mod.default)) continue;
+    const chain = await componentsFor(r.layouts);
+    if (r.dynamic) {
+      dynamicRoutes.push({ pattern: r.path, def: mod.default });
+      layoutChains[r.path] = chain;
+    } else {
+      routes[r.path] = mod.default;
+      layoutChains[r.path] = chain;
+    }
+  }
+
+  let extra: ExtraHandler | undefined;
+  const extraFile = findExtraFile(appDir);
+  if (extraFile) {
+    const mod = (await import(pathToFileURL(extraFile).href)) as { default?: unknown };
+    if (typeof mod.default === "function") extra = mod.default as ExtraHandler;
+  }
+
+  return {
+    routes,
+    dynamicRoutes,
+    layoutChains,
+    document: frozen.document,
+    agent: frozen.agent,
+    earlyHints: frozen.earlyHints,
+    extra,
+  };
+}
+
+function importPath(fromDir: string, file: string): string {
+  const p = relative(fromDir, file).split(sep).join("/").replace(/\.[^.]+$/, "");
+  return p.startsWith(".") ? p : `./${p}`;
+}
+
+export async function juneBuild(
+  appRoot: string,
+  options: { outDir?: string; external?: string[] } = {},
+): Promise<BuildResult> {
+  const appDir = join(appRoot, "app");
+  if (!existsSync(appDir)) throw new Error(`no app/ directory in ${appRoot} — is this a June app?`);
+  const genDir = join(appRoot, ".june");
+  const outDir = options.outDir ?? join(appRoot, "dist");
+  await mkdir(genDir, { recursive: true });
+  await rm(outDir, { recursive: true, force: true }); // stale chunks must not ship
+
+  const contentCollections = await generateContent(appRoot);
+  const routes = (await scanRoutes(appDir)).sort((a, b) => a.path.localeCompare(b.path));
+  if (routes.length === 0) throw new Error(`no page.* routes found under ${appDir}`);
+
+  const frozen = await freezeConfig(appRoot);
+
+  // ---- generated entry -----------------------------------------------------
+  const imports: string[] = [`import { createWorker } from "@junejs/server/worker";`];
+  const statics: string[] = [];
+  const dynamics: string[] = [];
+  const layoutIds = new Map<string, string>();
+  const layoutId = (file: string) => {
+    let id = layoutIds.get(file);
+    if (!id) {
+      id = `L${layoutIds.size}`;
+      layoutIds.set(file, id);
+      imports.push(`import ${id} from ${JSON.stringify(importPath(genDir, file))};`);
+    }
+    return id;
+  };
+  const chains: string[] = [];
+  routes.forEach((r, i) => {
+    imports.push(`import r${i} from ${JSON.stringify(importPath(genDir, r.file))};`);
+    if (r.dynamic) dynamics.push(`    { pattern: ${JSON.stringify(r.path)}, def: r${i} },`);
+    else statics.push(`    ${JSON.stringify(r.path)}: r${i},`);
+    chains.push(`    ${JSON.stringify(r.path)}: [${r.layouts.map(layoutId).join(", ")}],`);
+  });
+
+  const builtExtraFile = findExtraFile(appDir);
+  if (builtExtraFile) {
+    imports.push(`import extra from ${JSON.stringify(importPath(genDir, builtExtraFile))};`);
+  }
+
+  const entry = `// AUTO-GENERATED by \`june build\` — do not edit. Regenerate: june build .
+${imports.join("\n")}
+
+export default createWorker({
+  routes: {
+${statics.join("\n")}
+  },
+  dynamicRoutes: [
+${dynamics.join("\n")}
+  ],
+  layoutChains: {
+${chains.join("\n")}
+  },
+  document: ${JSON.stringify(frozen.document, null, 2).replace(/\n/g, "\n  ")},
+  agent: ${JSON.stringify(frozen.agent)},
+  earlyHints: ${JSON.stringify(frozen.earlyHints)},${builtExtraFile ? "\n  extra," : ""}
+});
+`;
+  const entryFile = join(genDir, "worker-entry.tsx");
+  await writeFile(entryFile, entry);
+
+  // ---- bundle (Rolldown; self-contained ESM for workerd) -------------------
+  const { rolldown } = await import("rolldown");
+  const bundle = await rolldown({
+    input: entryFile,
+    cwd: appRoot,
+    platform: "browser", // workerd's surface is web-standard; no node:* in the graph
+    external: (id: string) => {
+      // Binary assets stay external — wrangler's CompiledWasm/Data rules own them.
+      if (/\.(wasm|ttf|otf|woff2?|png|jpe?g|avif|webp)$/.test(id)) return true;
+      // config build.external: packages wrangler must bundle itself (its own
+      // esbuild owns their .wasm/asset rules — e.g. workers-og).
+      const list = options.external ?? frozen.buildExternal;
+      return list.some((e) => id === e || id.startsWith(`${e}/`));
+    },
+    resolve: {
+      // Conditions BAKED at build (workerd has no runtime conditions, reminder #3).
+      conditionNames: ["workerd", "edge", "import", "default"],
+    },
+  });
+  const result = await bundle.write({ dir: outDir, format: "esm", entryFileNames: "worker.js" });
+  await bundle.close();
+  const outFile = join(
+    outDir,
+    result.output.find((o) => o.type === "chunk" && o.isEntry)?.fileName ?? "worker.js",
+  );
+
+  // ---- prerender: opted-in static routes render THROUGH the worker ---------
+  // Same render path as the bundle (createWorker over the frozen manifest), so
+  // what ships is what the parity test verified.
+  const prerendered: string[] = [];
+  const manifest = await buildManifest(appRoot);
+  const worker = createWorker(manifest);
+  const assetsDir = join(outDir, "assets");
+  let hasAssets = false;
+
+  for (const r of routes.filter((x) => !x.dynamic)) {
+    const def = manifest.routes[r.path];
+    if (!def || !def.prerender) continue;
+    const stem = r.path === "/" ? "index" : r.path.slice(1);
+    const targets: Array<[string, string]> = [[r.path, `${stem}.html`]];
+    if (r.path !== "/") {
+      targets.push([`${r.path}.md`, `${stem}.md`]);
+      if (typeof def.json === "function") targets.push([`${r.path}.json`, `${stem}.json`]);
+    }
+    for (const [reqPath, file] of targets) {
+      const res = await worker.fetch(new Request(`https://prerender.june${reqPath}`));
+      if (!res.ok) throw new Error(`prerender ${reqPath} → ${res.status}`);
+      const dest = join(assetsDir, file);
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, Buffer.from(await res.arrayBuffer()));
+    }
+    prerendered.push(r.path);
+    hasAssets = true;
+  }
+
+  // ---- client islands bundle: app/_client.* → assets/client.js -------------
+  // Served at /client.js by the assets binding; the frozen document (freezeConfig)
+  // already points <script src> at it. No entry → no bundle, page ships zero JS.
+  const clientEntry = findClientEntry(appDir);
+  if (clientEntry) {
+    await bundleClientToFile(clientEntry, appRoot, assetsDir);
+    hasAssets = true;
+  }
+
+  // ---- wrangler config (only when the app doesn't manage its own) ----------
+  if (!existsSync(join(appRoot, "wrangler.toml")) && !existsSync(join(appRoot, "wrangler.jsonc"))) {
+    const pkgPath = join(appRoot, "package.json");
+    const pkg = existsSync(pkgPath)
+      ? (JSON.parse(await Bun.file(pkgPath).text()) as { name?: string })
+      : {};
+    await writeFile(
+      join(outDir, "wrangler.jsonc"),
+      JSON.stringify(
+        {
+          name: (pkg.name ?? basename(appRoot)).replace(/[^a-z0-9-]/gi, "-").toLowerCase(),
+          main: "./worker.js",
+          compatibility_date: "2025-01-01",
+          compatibility_flags: ["nodejs_compat"],
+          ...(hasAssets ? { assets: { directory: "./assets" } } : {}),
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+  }
+
+  return {
+    outFile,
+    routes: routes.filter((r) => !r.dynamic).map((r) => r.path),
+    dynamicRoutes: routes.filter((r) => r.dynamic).map((r) => r.path),
+    contentCollections,
+    prerendered,
+  };
+}

package/src/client-bundle.ts

@@ -0,0 +1,71 @@
+// The client bundle — the host half of v0.1 islands.
+//
+// The contract layer renders `<june-island>` markers (server) and exposes
+// `hydrateIslands` (client). This module is the BUILD/DEV glue that turns an
+// app's client entry into the `/client.js` the document loads.
+//
+// Convention: `app/_client.{tsx,ts,jsx,js}` (the `_` prefix marks it private, so
+// the route scanner already ignores it — same convention as `_content.ts`). The
+// author registers islands and calls `hydrateIslands` there:
+//
+//   // app/_client.tsx
+//   import { hydrateIslands } from "@junejs/core/islands-client";
+//   import { Counter } from "./Counter";
+//   hydrateIslands({ Counter });
+//
+// Absent entry → no `/client.js`, no `clientScript`, the page ships zero JS.
+//
+// Host-coupled (node:fs + Rolldown), so it lives in @junejs/server, never the pure
+// contract layer.
+
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+// The URL the document loads + the asset path the bundle is written to. Single
+// source of truth so build (freeze) and dev (live) agree.
+export const CLIENT_SCRIPT_URL = "/client.js";
+const CLIENT_BASENAME = "_client";
+const CLIENT_EXTS = [".tsx", ".ts", ".jsx", ".js"];
+
+// Find the app's client entry, if it has one. `appDir` is the `app/` directory.
+export function findClientEntry(appDir: string): string | undefined {
+  for (const ext of CLIENT_EXTS) {
+    const file = join(appDir, CLIENT_BASENAME + ext);
+    if (existsSync(file)) return file;
+  }
+  return undefined;
+}
+
+type BundleMode = "development" | "production";
+
+async function bundleClient(entryFile: string, cwd: string, mode: BundleMode) {
+  const { rolldown } = await import("rolldown");
+  const bundle = await rolldown({
+    input: entryFile,
+    cwd,
+    // The client graph is plain web — browser conditions, and React's dev/prod
+    // branch resolved at build (no `process` in the browser to read it at runtime).
+    platform: "browser",
+    transform: { define: { "process.env.NODE_ENV": JSON.stringify(mode) } },
+    resolve: { conditionNames: ["browser", "import", "default"] },
+  });
+  return bundle;
+}
+
+// Build the client entry to a single `client.js` string (dev serves this live).
+export async function bundleClientToString(entryFile: string, cwd: string): Promise<string> {
+  const bundle = await bundleClient(entryFile, cwd, "development");
+  const { output } = await bundle.generate({ format: "esm", entryFileNames: "client.js" });
+  await bundle.close();
+  const entry = output.find((o) => o.type === "chunk" && o.isEntry);
+  return entry && entry.type === "chunk" ? entry.code : "";
+}
+
+// Build the client entry to `<destDir>/client.js` (build freezes it as an asset).
+export async function bundleClientToFile(entryFile: string, cwd: string, destDir: string): Promise<void> {
+  const bundle = await bundleClient(entryFile, cwd, "production");
+  await mkdir(destDir, { recursive: true });
+  await bundle.write({ dir: destDir, format: "esm", entryFileNames: "client.js" });
+  await bundle.close();
+}

package/src/config-loader.ts

@@ -0,0 +1,30 @@
+// The fs side of config: load the user's june.config.{ts,js} from the app root.
+// @junejs/core/config owns the SCHEMA and the pure resolvers (defineJune,
+// resolveAgent, resolveSpeculationRules); this host module is the only place
+// that touches the filesystem — keeping node:* out of the pure layer.
+//
+// Reminder (rebuild-plan Phase 2): "the dev server never reading june.config.ts
+// went unnoticed for days." A config value MUST change observable output — the
+// dev server's config-changes-output test guards exactly this.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { JuneConfig } from "@junejs/core/config";
+
+// Probe the given dir AND its parent: callers pass either the app root
+// (build/deploy) or the routes dir `app/` (serve) — the config file lives at
+// the app root in both layouts.
+export async function loadJuneConfig(appDir: string): Promise<JuneConfig> {
+  for (const dir of [appDir, join(appDir, "..")]) {
+    for (const name of ["june.config.ts", "june.config.js"]) {
+      const path = join(dir, name);
+      if (existsSync(path)) {
+        const mod = (await import(pathToFileURL(path).href)) as { default?: JuneConfig };
+        return mod.default ?? {};
+      }
+    }
+  }
+  return {};
+}

package/src/content.ts

@@ -0,0 +1,102 @@
+// june content — the content pipeline: markdown files as content collections,
+// dual-audience by construction.
+//
+//   content/posts/2026-06-10-hello.md
+//     ├─ frontmatter  → entry.data (title/date/description/tags…) → metadata
+//     ├─ body         → entry.html (rendered) for the view projection
+//     └─ THE FILE     → entry.original — served VERBATIM as the .md projection.
+//
+// The last line is the differentiator: other frameworks' "markdown output" is
+// a lossy HTML→md conversion; June's .md projection IS the authored source.
+// Agents read exactly what the author wrote (frontmatter included).
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { marked } from "marked";
+
+export type ContentEntry = {
+  slug: string;
+  file: string;
+  /** Parsed frontmatter (string values; `tags`-style lists become string[]). */
+  data: Record<string, string | string[]>;
+  /** The markdown body (frontmatter stripped). */
+  body: string;
+  /** The authored file, verbatim — the agent-facing .md projection. */
+  original: string;
+  /** The body rendered to HTML (marked). */
+  html: string;
+};
+
+// Minimal frontmatter: `key: value` lines between --- fences; `[a, b]` lists
+// supported, nested YAML is not — keep frontmatter flat and simple. (A full
+// YAML parser is a later, deliberate dependency.)
+function parseFrontmatter(raw: string): { data: ContentEntry["data"]; body: string } {
+  if (!raw.startsWith("---")) return { data: {}, body: raw };
+  const end = raw.indexOf("\n---", 3);
+  if (end === -1) return { data: {}, body: raw };
+  const data: ContentEntry["data"] = {};
+  for (const line of raw.slice(3, end).split("\n")) {
+    const i = line.indexOf(":");
+    if (i === -1) continue;
+    const key = line.slice(0, i).trim();
+    const value = line.slice(i + 1).trim();
+    if (!key) continue;
+    if (value.startsWith("[") && value.endsWith("]")) {
+      data[key] = value
+        .slice(1, -1)
+        .split(",")
+        .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+        .filter(Boolean);
+    } else {
+      data[key] = value.replace(/^["']|["']$/g, "");
+    }
+  }
+  return { data, body: raw.slice(end + 4).replace(/^\n+/, "") };
+}
+
+// mtime-keyed memo: correct under dev edits, free in production.
+const memo = new Map<string, { mtime: number; entry: ContentEntry }>();
+
+function loadEntry(file: string, slug: string): ContentEntry {
+  const mtime = statSync(file).mtimeMs;
+  const hit = memo.get(file);
+  if (hit && hit.mtime === mtime) return hit.entry;
+  const original = readFileSync(file, "utf8");
+  const { data, body } = parseFrontmatter(original);
+  const entry: ContentEntry = {
+    slug,
+    file,
+    data,
+    body,
+    original,
+    html: marked.parse(body, { async: false }) as string,
+  };
+  memo.set(file, { mtime, entry });
+  return entry;
+}
+
+/** All entries in a content directory, newest-first by `date` (then slug). */
+export function collection(dir: string): ContentEntry[] {
+  const entries = readdirSync(dir)
+    .filter((f) => f.endsWith(".md") || f.endsWith(".mdx"))
+    .map((f) => loadEntry(join(dir, f), f.replace(/\.(md|mdx)$/, "")));
+  return entries.sort((a, b) => {
+    const da = String(a.data.date ?? "");
+    const db = String(b.data.date ?? "");
+    return db.localeCompare(da) || a.slug.localeCompare(b.slug);
+  });
+}
+
+/** One entry by slug, or null. */
+export function entry(dir: string, slug: string): ContentEntry | null {
+  // Guard the slug — it comes from the URL.
+  if (!/^[A-Za-z0-9._-]+$/.test(slug)) return null;
+  for (const ext of [".md", ".mdx"]) {
+    const file = join(dir, slug + ext);
+    try {
+      return loadEntry(file, slug);
+    } catch {
+      /* try next ext */
+    }
+  }
+  return null;
+}

package/src/db.ts

@@ -0,0 +1,61 @@
+// `db` resource adapters — implementations of the @junejs/core JuneDb contract.
+// Declared in june.config.ts (`resources.db: sqlite(...)` / `d1(...)`), opened
+// by the host, injected onto RouteContext as `ctx.db`. The framework depends on
+// the JuneDb contract; these adapters (and Juno on top) are swappable.
+
+import type { DbFactory, JuneDb, RunResult } from "@junejs/core/resources";
+
+import { host } from "./host";
+
+// Local SQLite — the zero-config dev default (embedded file or :memory:). Built
+// on the demoted host.openDb primitive (the sync bun:/node: driver wrapped async).
+export function sqlite(opts: { path?: string } = {}): DbFactory {
+  const path = opts.path ?? ":memory:";
+  return { kind: "sqlite", open: () => host.openDb(path) };
+}
+
+// --- D1 (Cloudflare) — the third openDb impl (rebuild-plan Phase 5) ----------
+// The binding comes from the worker's env at request time, so d1() takes the
+// already-bound D1Database. Adapts D1's prepare().bind().all()/first()/run() to
+// the JuneDb contract.
+
+type D1Result<T> = { results: T[] };
+type D1Meta = { changes?: number; last_row_id?: number };
+interface D1PreparedStatement {
+  bind(...values: unknown[]): D1PreparedStatement;
+  all<T = unknown>(): Promise<D1Result<T>>;
+  first<T = unknown>(): Promise<T | null>;
+  run(): Promise<{ meta: D1Meta }>;
+}
+export interface D1Database {
+  prepare(sql: string): D1PreparedStatement;
+  exec(sql: string): Promise<unknown>;
+}
+
+export function d1(binding: D1Database): DbFactory {
+  const db: JuneDb = {
+    async query<T>(sql: string, params: unknown[] = []) {
+      return (await binding.prepare(sql).bind(...params).all<T>()).results;
+    },
+    async get<T>(sql: string, params: unknown[] = []) {
+      return (await binding.prepare(sql).bind(...params).first<T>()) ?? undefined;
+    },
+    async run(sql: string, params: unknown[] = []): Promise<RunResult> {
+      const { meta } = await binding.prepare(sql).bind(...params).run();
+      return { changes: meta.changes ?? 0, lastInsertRowid: meta.last_row_id ?? 0 };
+    },
+    async exec(sql: string) {
+      await binding.exec(sql);
+    },
+    // D1 has no INTERACTIVE transactions (only batch()); run the fn inline. For
+    // true atomicity, group writes through batch() at the call site. Documented
+    // limitation of the edge backend — the contract stays uniform.
+    async transaction<T>(fn: (tx: JuneDb) => Promise<T>) {
+      return fn(db);
+    },
+    async close() {
+      /* the binding outlives the request; nothing to close */
+    },
+  };
+  return { kind: "d1", open: async () => db };
+}