@junejs/server 0.1.3 → 0.2.0

package/src/config-freeze.ts

@@ -0,0 +1,109 @@
+// Freeze june.config.ts → the serializable bits the worker inlines, plus the
+// small config-derived helpers (deploy adapter resolution, base path and worker
+// name normalization). Extracted from build.ts; consumed by buildManifest and
+// juneBuild so both freeze through the SAME code (the parity contract).
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { deployOrigin, resolveAgent, resolveClientRouter, resolveSpeculationRules } from "@junejs/core/config";
+import type { JuneConfig } from "@junejs/core/config";
+import type { DocumentConfig } from "@junejs/core/document";
+import { workers, vercel, deno, staticSite, type JuneAdapter } from "./adapter";
+import { findClientEntry, CLIENT_SCRIPT_URL } from "./client-bundle";
+import { loadJuneConfig } from "./config-loader";
+import { publicFileCheck, resolveIcons } from "./favicon";
+import { findGlobalCss, globalCssUsesTailwind, STYLES_URL } from "./css";
+import type { WorkerManifest } from "./worker";
+
+// Resolve the deploy adapter from config. An explicit `adapter` INSTANCE wins; otherwise the
+// `target` NAME selects the matching built-in — so a DECLARATIVE config (e.g. kura.toml, which
+// can't express a `vercel()` call) can pick any target by string, not just "static". "workers" is
+// the default. Kept in lockstep with deploy.ts's own target→deployer switch so a build for one
+// target is never deployed as another. vercel()/deno() take their opts (runtime/regions, org/app)
+// which JuneConfig.deploy doesn't carry yet, so they use defaults here.
+export function resolveDeployAdapter(deploy: JuneConfig["deploy"]): JuneAdapter {
+  if (deploy?.adapter) return deploy.adapter as JuneAdapter;
+  switch (deploy?.target) {
+    case "static":
+      return staticSite();
+    case "vercel":
+      return vercel();
+    case "deno":
+      return deno();
+    default:
+      return workers({ name: deploy?.name, domain: deploy?.domain });
+  }
+}
+
+// Freeze june.config.ts → the serializable bits the worker inlines.
+export async function freezeConfig(appRoot: string): Promise<{
+  document: DocumentConfig;
+  agent: WorkerManifest["agent"];
+  i18n: WorkerManifest["i18n"];
+  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).
+  // Client entry: app/_client.* wins; fall back to .june/routes/_client.* (framework slot).
+  const hasClient =
+    findClientEntry(join(appRoot, "app")) !== undefined ||
+    findClientEntry(join(appRoot, ".june", "routes")) !== undefined;
+  const hasCss = findGlobalCss(join(appRoot, "app")) !== null;
+  return {
+    document: {
+      site: cfg.site ?? {},
+      deployOrigin: deployOrigin(cfg),
+      speculationRules: resolveSpeculationRules(cfg.speculation ?? undefined),
+      speculationDelivery: "inline",
+      viewTransitions: cfg.viewTransitions ?? true,
+      // Default the baseline reset OFF when the app uses Tailwind (its Preflight is the reset).
+      cssReset: cfg.cssReset ?? !globalCssUsesTailwind(join(appRoot, "app")),
+      clientRouter: resolveClientRouter(cfg.clientRouter),
+      clientScript: hasClient ? CLIENT_SCRIPT_URL : null,
+      styles: hasCss ? STYLES_URL : null,
+      // Deploy subpath (JuneConfig.basePath). Frozen so the document prefixes its
+      // asset URLs; the prerender path re-freezes through buildManifest and gets the
+      // same value, keeping static pages' asset links correct under the subpath.
+      basePath: normalizeBase(cfg.basePath),
+      // PNG icon links: June's generated set unless public/ or site.icon brings one
+      // (juneBuild writes the files; resolveIcons makes the same call there).
+      icons: resolveIcons(cfg.site ?? {}, publicFileCheck(join(appRoot, "public"))).icons,
+    },
+    agent: resolveAgent(cfg.agent),
+    // Pass i18n through as-is: the in-process buildManifest keeps a resolveLocale
+    // hook (parity test), and the codegen JSON.stringify drops the function
+    // (worker hook support is the codegen pass — see the manifest field comment).
+    i18n: cfg.i18n,
+    earlyHints: cfg.earlyHints ?? [],
+    buildExternal: cfg.build?.external ?? [],
+  };
+}
+
+// A deploy basePath is stored with a leading slash and no trailing slash; empty
+// ("" — the default) means a root deploy. So "/openab/docs/" → "/openab/docs",
+// "openab" → "/openab", undefined → "".
+export function normalizeBase(base?: string): string {
+  if (!base) return "";
+  const b = base.startsWith("/") ? base : `/${base}`;
+  return b.endsWith("/") ? b.slice(0, -1) : b;
+}
+
+// A wrangler-valid worker name from a package name or directory name. Wrangler requires lowercase
+// [a-z0-9-] not starting/ending with a dash — so a SCOPED package name (`@scope/pkg`) must lose its
+// scope (else the `@` sanitizes to a leading dash and wrangler rejects the config). Drop the scope,
+// lowercase, collapse non-alphanumerics to single dashes, trim edge dashes; fall back to "app" if
+// nothing survives (e.g. an all-punctuation name). Exported for tests.
+export function workerName(raw: string): string {
+  return (
+    raw
+      .replace(/^@[^/]+\//, "")
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "app"
+  );
+}

package/src/connection-auth.ts

@@ -0,0 +1,101 @@
+// connection-auth.ts — turn an authenticated principal into a per-call bearer
+// token for an outbound connection (provider / mcp / openapi).
+//
+// A connection's `auth(ctx)` seam resolves the credential PER CALL, server-side,
+// so the token never reaches the model. The common, fiddly case is "use the
+// CALLER's linked OAuth account" — look up the principal's stored token for a
+// provider, fail closed when it isn't there. This module standardizes that:
+//
+//   • linkedAccountAuth — the generic core. You inject a `store` (where account
+//     tokens live); it handles the ctx→userId extraction and the fail-closed
+//     contract. Reusable across connections whose `auth` is resolved PER CALL
+//     with the caller's identity — i.e. PROVIDER connections (Google Drive), and
+//     MCP/OpenAPI remotes that don't authenticate discovery.
+//
+//     ⚠️ Not for MCP/OpenAPI connections that DO require auth for discovery:
+//     connectMcp/connectOpenapi call `auth(undefined)` at initialize/tools-list/
+//     schema-fetch time (before any turn), and this helper fails closed on a
+//     missing principal — so discovery would report zero tools. Those need a
+//     discovery-scoped credential, not a per-caller one.
+//   • betterAuthAccountTokenStore / betterAuthAccessToken — the blessed Better
+//     Auth convenience. Kept STRUCTURAL (no `better-auth` import), so wiring it
+//     adds no dependency and stays fully overridable — swap the store for a
+//     custom table, a secrets vault, or a Service Account minter.
+//
+// Pure logic (no node:*), tied only to the identity types in @junejs/core — the
+// auth INTEGRATION lives in the host layer by design (see docs/auth-integration.md),
+// which is why it is here and not in the pure contract layer.
+
+import type { ActionContext } from "@junejs/core/context";
+
+// Where a principal's OAuth account tokens live. Given the caller's principal id
+// and a provider, return a FRESH access token (the store refreshes if needed),
+// or null when the user hasn't linked that provider. Better Auth's account table
+// is the blessed implementation; anything satisfying this shape works.
+export type AccountTokenStore = (args: {
+  userId: string;
+  providerId: string;
+}) => Promise<{ accessToken: string } | null> | { accessToken: string } | null;
+
+export type LinkedAccountAuthOptions = {
+  // Which linked provider to mint a token for, e.g. "google".
+  providerId: string;
+  // The token source (injected — this is the overridable seam).
+  store: AccountTokenStore;
+};
+
+// The connection `auth(ctx)` shape: resolve a bearer token from the call's
+// identity, server-side. (Structurally identical to connections' internal Auth
+// and to GoogleDriveAuth.)
+export type ConnectionAuth = (ctx?: ActionContext) => Promise<{ token: string }>;
+
+// Build an `auth(ctx)` for ANY June connection that mints the CALLER's
+// linked-account token. FAIL CLOSED: a missing principal or an unlinked account
+// throws — so an authenticated-but-unlinked user gets a clear error, and
+// (together with the connection's `requiresPrincipal`, which hides the tools from
+// anonymous turns) the capability is never reachable without a real credential.
+export function linkedAccountAuth(opts: LinkedAccountAuthOptions): ConnectionAuth {
+  return async (ctx?: ActionContext): Promise<{ token: string }> => {
+    const userId = ctx?.user?.id;
+    if (!userId) {
+      throw new Error(`connection auth (${opts.providerId}): no authenticated principal — set requiresPrincipal and resolve identity on the surface`);
+    }
+    const record = await opts.store({ userId, providerId: opts.providerId });
+    if (!record?.accessToken) {
+      throw new Error(`connection auth (${opts.providerId}): user "${userId}" has no linked "${opts.providerId}" account`);
+    }
+    return { token: record.accessToken };
+  };
+}
+
+// The minimal Better-Auth surface this reads — STRUCTURAL, so importing the
+// helper doesn't drag in `better-auth`. A real Better Auth server instance
+// satisfies it: `auth.api.getAccessToken` takes an ENDPOINT INPUT shaped as
+// `{ body: { providerId, userId, accountId? }, headers? }` and refreshes the
+// stored token when expired. The reply key differs across versions (accessToken
+// vs token), so both are accepted.
+export type BetterAuthLike = {
+  api: {
+    getAccessToken: (input: {
+      body: { providerId: string; userId?: string; accountId?: string };
+      headers?: HeadersInit;
+    }) => Promise<{ accessToken?: string; token?: string } | null | undefined>;
+  };
+};
+
+// Adapt a Better-Auth-shaped instance into an AccountTokenStore. Passes `userId`
+// in the endpoint `body` (server-side lookup — no request session needed).
+export function betterAuthAccountTokenStore(auth: BetterAuthLike): AccountTokenStore {
+  return async ({ userId, providerId }) => {
+    const res = await auth.api.getAccessToken({ body: { providerId, userId } });
+    const accessToken = res?.accessToken ?? res?.token;
+    return accessToken ? { accessToken } : null;
+  };
+}
+
+// Sugar: a fail-closed `auth(ctx)` backed by Better Auth in one call.
+//
+//   googleDriveConnection({ requiresPrincipal: true, auth: betterAuthAccessToken(auth, { providerId: "google" }) })
+export function betterAuthAccessToken(auth: BetterAuthLike, opts: { providerId: string }): ConnectionAuth {
+  return linkedAccountAuth({ providerId: opts.providerId, store: betterAuthAccountTokenStore(auth) });
+}

package/src/content-freeze.ts

@@ -0,0 +1,151 @@
+// The content FREEZE: content/<collection>/*.md → app/_content.ts, the
+// build-time content manifest. Extracted from build.ts — this is the whole
+// "remove node:fs from the worker graph" step, including the self-healing
+// bootstrap for wrapper-generated configs that import app/_content.ts.
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { ContentSource, JuneConfig } from "@junejs/core/config";
+import { findJuneConfigPath, loadJuneConfig } from "./config-loader";
+import { generateContentModule } from "./content";
+
+// 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.
+//
+// Extra sources (config `content.sources`) merge dirs OUTSIDE `content/` into named
+// collections — the docs-as-code seam (a repo's own `docs/` feeds the site directly).
+// Their dirs resolve against the app root, so "../docs" reaches a sibling directory.
+//
+// Locale buckets are DECLARED, not guessed: only dirs named in config i18n
+// (defaultLocale + locales keys) split off as locale mirrors. Guessing by shape
+// (the old BCP-47 regex) silently swallowed any 2–3-letter folder — `cli/`,
+// `sdk/`, `api/`, `faq/` all read as locales and vanished from the default set.
+// No i18n config ⇒ NO buckets (an undeclared locale is not a locale). The regex
+// remains only as the fallback when the config itself cannot be loaded.
+export async function generateContent(appRoot: string): Promise<string[]> {
+  const contentDir = join(appRoot, "content");
+  // app/ is the output dir for _content.ts (and the seed). Ensure it exists so the now-always
+  // write can't throw an opaque ENOENT when called standalone (e.g. `june gen`); the full build's
+  // own "no app/ directory" check runs earlier, so this never masks that clearer error.
+  await mkdir(join(appRoot, "app"), { recursive: true });
+  const emit = async (sources: ContentSource[], knownLocales: readonly string[] | undefined): Promise<string[]> => {
+    // Emission (incl. the per-locale layout and source merging) lives in ./content so it's
+    // pure and unit-testable; this stays the thin fs wrapper.
+    const { code, names } = generateContentModule(contentDir, knownLocales, sources);
+    // Always write, even with zero collections: `code` still carries the canonical ContentEntry
+    // type, which is the single source of truth the bootstrap seed appends its stubs against (an
+    // app with no local content/ — docs-as-code — needs this valid empty module to exist).
+    await writeFile(join(appRoot, "app", "_content.ts"), code);
+    return names;
+  };
+  const resolveSources = (sources: ContentSource[]): ContentSource[] =>
+    sources.map((s) => ({ ...s, dir: resolve(appRoot, s.dir) }));
+  const declaredLocales = (config: JuneConfig): string[] =>
+    config.i18n ? [...new Set([config.i18n.defaultLocale, ...Object.keys(config.i18n.locales)])] : [];
+  // Learn sources + locales from june.config.ts — TOLERANTLY. A wrapper-generated config (e.g.
+  // Kura's) imports app/_content.ts, which does not exist before the FIRST freeze. So on a failed
+  // config load: generate a default scan to create that import's target, then re-probe the config
+  // and regenerate with the real sources/locales. Self-healing, no bootstrap flag. Content errors
+  // from emit() (slug collision, missing source dir) stay loud — only the CONFIG LOAD is tolerated.
+  let config: JuneConfig | null = null;
+  try {
+    config = await loadJuneConfig(appRoot);
+  } catch {
+    /* two-pass below */
+  }
+  if (config) return emit(resolveSources(config.content?.sources ?? []), declaredLocales(config));
+  // Pass 1 (throwaway when the probe succeeds): legacy regex locale detection, since the
+  // declared set is unknowable without the config. emit() writes app/_content.ts with the
+  // canonical ContentEntry type plus a `const` per collection FOUND — but a docs-as-code app
+  // keeps ALL content in external content.sources with NO local content/, so it finds zero
+  // collections and thus emits no EXPORTS (no `DOCS`). seedContentImports then appends stubs for
+  // the exact names the config imports (e.g. Kura's `import { DOCS }`), so the re-probe can load.
+  const names = await emit([], undefined);
+  await seedContentImports(appRoot);
+  const probed = probeConfigFresh(appRoot);
+  if (probed === null) {
+    console.warn("[june gen] june.config.ts failed to load — content.sources/i18n locales (if any) not applied");
+    return names;
+  }
+  return emit(resolveSources(probed.sources), probed.locales);
+}
+
+// Bootstrap seed: ensure app/_content.ts exports every name the config imports from it, so the
+// re-probe's config load resolves BEFORE the first real freeze. A docs-as-code app (content only
+// in external content.sources, no local content/) leaves Pass 1's default scan empty — nothing
+// seeds the collections — so here we append stubs for the EXACT named imports the config takes
+// from the app/_content module (a bare `import { DOCS }` of it → `export const DOCS = []`). The
+// caller's emit() already wrote the module's canonical ContentEntry type (even when empty), so the
+// stubs type against that single source of truth. Overwritten by the real freeze that follows a
+// successful probe; a no-op once content exists.
+async function seedContentImports(appRoot: string): Promise<void> {
+  const cfgPath = findJuneConfigPath(appRoot);
+  if (!cfgPath) return;
+  const contentFile = join(appRoot, "app", "_content.ts");
+  const current = existsSync(contentFile) ? await readFile(contentFile, "utf8") : "";
+  const cfgSrc = await readFile(cfgPath, "utf8");
+  // Only stub valid JS identifiers — a name carrying comments/other tokens (rare, but valid TS)
+  // must never reach `new RegExp(...)` (would throw) or the emitted stub (would be invalid TS).
+  const isIdent = (s: string): boolean => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s);
+  // A Set so a name matched more than once (e.g. a comment mentioning the import + the real one)
+  // yields ONE stub — a duplicate `export const <name>` would be invalid TS. Also skip names the
+  // module already exports.
+  const seen = new Set<string>();
+  const stubs: string[] = [];
+  // Each named `import { A, B as C }` the config takes from the app/_content module → stub each.
+  // The `(?:\.\w+)?` tolerates an explicit extension (`app/_content.ts`/`.js`/`.mjs`), which
+  // NodeNext / verbatimModuleSyntax configs require — else the import goes undetected and unstubbed.
+  for (const m of cfgSrc.matchAll(/import\s*(?:type\s+)?\{([^}]*)\}\s*from\s*["'][^"']*app\/_content(?:\.\w+)?["']/g)) {
+    // Strip block + line comments from the specifier list BEFORE splitting: a valid
+    // `{ DOCS /* keep */ }` must still yield the identifier `DOCS` (not be dropped), and a comment
+    // could otherwise carry a `,` that breaks the split. Then drop `type` markers per specifier.
+    const inner = (m[1] ?? "").replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+    for (const part of inner.split(",")) {
+      const name = part.replace(/\btype\b/g, "").split(/\s+as\s+/).pop()?.trim();
+      if (!name || !isIdent(name) || seen.has(name)) continue;
+      seen.add(name);
+      // Escape before interpolating: a valid identifier may contain `$`, a regex metachar (an
+      // anchor), which would corrupt the already-exported check. The stub below uses the raw name.
+      const reName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      if (!new RegExp(`export (?:const|function|type) ${reName}\\b`).test(current)) {
+        stubs.push(`export const ${name}: ContentEntry[] = [];`);
+      }
+    }
+  }
+  if (stubs.length) await writeFile(contentFile, current + stubs.join("\n") + "\n");
+}
+
+// Re-probe ONLY the content-relevant config (sources + declared i18n locales) in a FRESH
+// subprocess. The bootstrap retry can't re-import in-process: a failed ESM load is cached as
+// errored, and Bun also caches the failed RESOLUTION of the config's own imports — so a
+// same-process retry (even cache-busted) re-rejects after the missing app/_content.ts appears.
+// A child process has a clean module map, and both fields are plain JSON, so they survive the
+// pipe. Returns null when the config is genuinely broken.
+function probeConfigFresh(appRoot: string): { sources: ContentSource[]; locales: string[] } | null {
+  const path = findJuneConfigPath(appRoot);
+  if (!path) return { sources: [], locales: [] };
+  // Markers isolate the JSON from anything the config prints at import time. `.then` (not TLA)
+  // so the eval works as CJS under both `bun -e` and `node -e`; execArgv carries loader flags
+  // (e.g. --experimental-strip-types) so the child can read the same TS config the parent does.
+  const code =
+    `import(${JSON.stringify(pathToFileURL(path).href)}).then(` +
+    `(m) => { const c = m.default ?? {}; process.stdout.write("\\n__JUNE_CONTENT__" + JSON.stringify({ ` +
+    `sources: c.content?.sources ?? [], ` +
+    `locales: c.i18n ? [...new Set([c.i18n.defaultLocale, ...Object.keys(c.i18n.locales ?? {})])] : [] ` +
+    `}) + "__END__"); }, () => process.exit(42));`;
+  try {
+    const out = execFileSync(process.execPath, [...process.execArgv, "-e", code], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const m = out.match(/__JUNE_CONTENT__(.*?)__END__/s);
+    return m ? (JSON.parse(m[1]!) as { sources: ContentSource[]; locales: string[] }) : null;
+  } catch {
+    return null;
+  }
+}

package/src/content.ts

@@ -12,6 +12,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { toHtmlSync, initSync } from "@momiji-rs/sparkdown/gfm";
+import { createSlugger } from "@junejs/core/slug";
 
 import type { ContentSource } from "@junejs/core/config";
 
@@ -29,6 +30,48 @@ const ensureWasm = () => {
   }
 };
 
+export type Heading = { depth: number; text: string; id: string };
+
+// &-entities the renderer emits in heading text, decoded so the text (and so the
+// slug) is what a reader sees: "Q&A" slugs as "Q&A" → "qa", as on GitHub.
+const NAMED: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+const decodeEntities = (s: string) =>
+  s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e: string) =>
+    e[0] === "#"
+      ? String.fromCodePoint(e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : Number(e.slice(1)))
+      : (NAMED[e.toLowerCase()] ?? m),
+  );
+
+// Give every heading in rendered HTML a GitHub-compatible id — one slugger per
+// document, in order, so repeats de-duplicate exactly as GitHub's do — and collect
+// them. Markdown headings render bare (`<h2>…</h2>`) and get only an id. Raw HTML an
+// author wrote is preserved by CommonMark, so a heading may arrive with attributes:
+// its attributes are kept, an authored id is REUSED (the author's explicit anchor),
+// and a generated id never repeats any id already in the document — authored ones
+// included — so every heading's anchor is unique.
+const ID_ATTR = /\sid\s*=\s*(?:"([^"]*)"|'([^']*)')/i;
+export function headingIds(html: string): { html: string; headings: Heading[] } {
+  const slug = createSlugger();
+  const taken = new Set<string>();
+  for (const m of html.matchAll(new RegExp(ID_ATTR.source, "gi"))) taken.add((m[1] ?? m[2])!);
+  const headings: Heading[] = [];
+  const out = html.replace(/<h([1-6])(\s[^>]*)?>([\s\S]*?)<\/h\1>/gi, (_m, depth: string, attrs: string | undefined, inner: string) => {
+    const text = decodeEntities(inner.replace(/<[^>]*>/g, "")).trim();
+    const own = attrs ? ID_ATTR.exec(attrs) : null;
+    const authored = own ? (own[1] ?? own[2]) : undefined;
+    let id = authored;
+    if (!id) {
+      do id = slug(text);
+      while (taken.has(id)); // the slugger suffixes each repeat: -1, -2, …
+      taken.add(id);
+    }
+    headings.push({ depth: Number(depth), text, id });
+    // an authored-but-empty id="" is no anchor: drop it, so the heading carries exactly one id
+    return authored ? _m : `<h${depth}${(attrs ?? "").replace(ID_ATTR, "")} id="${id}">${inner}</h${depth}>`;
+  });
+  return { html: out, headings };
+}
+
 export type ContentEntry = {
   slug: string;
   file: string;
@@ -38,8 +81,13 @@ export type ContentEntry = {
   body: string;
   /** The authored file, verbatim — the agent-facing .md projection. */
   original: string;
-  /** The body rendered to HTML (CommonMark + GFM, via @momiji-rs/sparkdown/gfm wasm). */
+  /** The body rendered to HTML (CommonMark + GFM, via @momiji-rs/sparkdown/gfm wasm).
+   *  Every heading carries a GitHub-compatible `id` (see @junejs/core/slug) and nothing
+   *  else — no injected links or classes; how an anchor looks is the app's call. */
   html: string;
+  /** The headings of `html`, in document order: their depth (1–6), plain text, and the
+   *  `id` each carries in `html` — for a table of contents, or a structured projection. */
+  headings: Heading[];
   /** The locale this entry was authored in — set for files under a `<locale>/`
    *  subdir, undefined for the flat (default-locale) files. */
   locale?: string;
@@ -96,13 +144,15 @@ function loadEntry(file: string, slug: string, locale?: string): ContentEntry {
     if (h1?.[1]) data.title = h1[1];
   }
   ensureWasm(); // sync, idempotent — instantiate the renderer wasm on first use only
+  const { html, headings } = headingIds(toHtmlSync(body));
   const entry: ContentEntry = {
     slug,
     file,
     data,
     body,
     original,
-    html: toHtmlSync(body),
+    html,
+    headings,
     ...(locale ? { locale } : {}),
   };
   memo.set(key, { mtime, entry });
@@ -287,6 +337,7 @@ export function generateContentModule(
     body: e.body,
     original: e.original,
     html: e.html,
+    headings: e.headings,
     ...(e.locale ? { locale: e.locale } : {}),
   });
   // Default scan: each `content/<name>/` is a collection. Guarded — a sources-only app
@@ -340,8 +391,8 @@ export function generateContentModule(
     names.push(name);
   }
   const entryType = anyLocale
-    ? "export type ContentEntry = { slug: string; data: Record<string, string | string[]>; body: string; original: string; html: string; locale?: string };\n"
-    : "export type ContentEntry = { slug: string; data: Record<string, string | string[]>; body: string; original: string; html: string };\n";
+    ? "export type ContentEntry = { slug: string; data: Record<string, string | string[]>; body: string; original: string; html: string; headings: Array<{ depth: number; text: string; id: string }>; locale?: string };\n"
+    : "export type ContentEntry = { slug: string; data: Record<string, string | string[]>; body: string; original: string; html: string; headings: Array<{ depth: number; text: string; id: string }> };\n";
   const code =
     "// AUTO-GENERATED by `june build` — edit content/**/*.md, not this file.\n" + entryType + body;
   return { code, names };

package/src/core-version.ts

@@ -0,0 +1,34 @@
+// core-version.ts — the #94 belt-and-braces: fail at POWER-ON when the @junejs/core
+// copy this server resolved is not the one it was built for.
+//
+// The primary fix is @junejs/core being a peerDependency (the app's single resolution
+// always wins), but a nested second copy can still appear (npm legacy peer handling,
+// a stale lockfile, a transitive pin). When it does, the failure without this check
+// is far from the cause and mid-turn ("sink.emit is not a function", first seen in
+// crisp-agent production); with it, construction throws with both versions named.
+//
+// Namespace import + optional read on purpose: a PRE-#94 core has no
+// RUNTIME_API_VERSION export, and a named import of a missing export would die at
+// module link time with an unhelpful SyntaxError — exactly the confusion this
+// module exists to remove.
+import * as coreRuntime from "@junejs/core/agent-runtime";
+
+// The contract number this server tree is built against. Bump in lockstep with
+// core's RUNTIME_API_VERSION whenever the server↔core runtime contract changes.
+const EXPECTED_CORE_RUNTIME_API = 7;
+
+export function assertCoreRuntimeVersion(surface: string): void {
+  checkCoreRuntimeVersion(surface, (coreRuntime as { RUNTIME_API_VERSION?: number }).RUNTIME_API_VERSION);
+}
+
+// The pure check, split out so the mismatch paths are unit-testable (the ambient
+// read above can only ever see the workspace's own — matching — core).
+export function checkCoreRuntimeVersion(surface: string, actual: number | undefined, expected: number = EXPECTED_CORE_RUNTIME_API): void {
+  if (actual === expected) return;
+  throw new Error(
+    `${surface}: @junejs/server is built against @junejs/core runtime API v${expected}, ` +
+      `but the @junejs/core it resolved provides ${actual === undefined ? "no RUNTIME_API_VERSION (a pre-0.1.1-dev.16 core)" : `v${actual}`} — ` +
+      `two copies of @junejs/core are likely installed (one nested under @junejs/server). ` +
+      `Align the app's @junejs/core with @junejs/server's peer range, then reinstall/dedupe so one copy remains.`,
+  );
+}

package/src/dev.ts

@@ -19,20 +19,41 @@ import { findGlobalCss, processCssCached, invalidateCss } from "./css";
 export type DevServerOptions = {
   appDir: string;
   port?: number;
+  // The address to bind. Default 127.0.0.1: the dev server is reachable from this
+  // machine only (MCP: "when running locally, servers SHOULD bind only to
+  // localhost"). "0.0.0.0" opens it to the LAN — `june dev --host`.
+  hostname?: string;
   host?: JuneHost;
 };
 
-export type DevServer = ServeHandle & { url: string };
+// The Host names a dev server answers /mcp and /api for (#308): localhost and its
+// subdomains, plus IP literals (always allowed — rebinding needs a domain name),
+// plus a named --host and whatever the config allows.
+// The URL to print and return: localhost for loopback or a wildcard bind (it
+// answers there too), else the one address bound — nothing listens on loopback then.
+export function devUrl(hostname: string, port: number): string {
+  if (["127.0.0.1", "0.0.0.0", "::", "localhost"].includes(hostname)) return `http://localhost:${port}`;
+  return `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${port}`;
+}
+
+export function devAllowedHosts(configured: readonly string[] | undefined, hostname: string): string[] {
+  const hosts = new Set(["localhost", ".localhost", ...(configured ?? [])]);
+  if (!/^[\d.]+$|:/.test(hostname)) hosts.add(hostname.toLowerCase()); // a name, not 0.0.0.0 / an IP
+  return [...hosts];
+}
+
+// stop() also shuts the app down (its agent runtime, #317); await it to know that's done.
+export type DevServer = Omit<ServeHandle, "stop"> & { url: string; stop(force?: boolean): Promise<void> };
 
 // A taken default port must not be a dead end in dev — walk forward until a
 // port binds (the Vite convention). Probed with node:net, which both hosts
 // implement, so the host interface stays untouched.
-async function findFreePort(start: number, tries = 20): Promise<number> {
+async function findFreePort(start: number, hostname: string, tries = 20): Promise<number> {
   for (let p = start; p < start + tries; p++) {
     const free = await new Promise<boolean>((resolve) => {
       const probe = createNetServer();
       probe.once("error", () => resolve(false));
-      probe.listen(p, () => probe.close(() => resolve(true)));
+      probe.listen(p, hostname, () => probe.close(() => resolve(true)));
     });
     if (free) return p;
   }
@@ -42,10 +63,13 @@ async function findFreePort(start: number, tries = 20): Promise<number> {
 export async function startDevServer({
   appDir,
   port = 3000,
+  hostname = "127.0.0.1",
   host = defaultHost,
 }: DevServerOptions): Promise<DevServer> {
   await installAsyncContext();
-  const config = await loadJuneConfig(appDir);
+  const loaded = await loadJuneConfig(appDir);
+  // The DNS-rebinding check (#308): a local server is exactly what rebinding targets.
+  const config = { ...loaded, agent: { ...loaded.agent, allowedHosts: devAllowedHosts(loaded.agent?.allowedHosts, hostname) } };
 
   // Apply pending migrations before serving — dev auto-applies the SAFE ones; a
   // destructive one is reported and skipped (the server still starts, but the
@@ -57,7 +81,7 @@ export async function startDevServer({
   const app = createApp({ appDir, config });
   await app.warmup();
 
-  const freePort = await findFreePort(port);
+  const freePort = await findFreePort(port, hostname);
   if (freePort !== port) console.log(`[june] port ${port} is taken → using ${freePort}`);
   port = freePort;
 
@@ -65,6 +89,7 @@ export async function startDevServer({
   // dev/built parity) never sees it. See dev-reload.ts.
   const handle = host.serve(withLiveReload((req) => app.fetch(req)), {
     port,
+    hostname,
     earlyHints: () => app.earlyHints(),
   });
 
@@ -87,7 +112,15 @@ export async function startDevServer({
     void processCssCached(appDir).catch(() => {});
   }
 
-  const url = `http://localhost:${handle.port}`;
-  console.log(`june dev → ${url}  (host: ${host.name})`);
-  return { ...handle, url };
+  const url = devUrl(hostname, handle.port);
+  const lan = hostname === "127.0.0.1" ? "" : `  · listening on ${hostname}`;
+  console.log(`june dev → ${url}  (host: ${host.name})${lan}`);
+  return {
+    ...handle,
+    url,
+    async stop(force?: boolean) {
+      handle.stop(force);
+      await app.close();
+    },
+  };
 }