@junejs/server 1.0.0-dev.19 → 1.0.0-dev.24

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/core-version.ts

@@ -15,7 +15,7 @@ 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 = 1;
+const EXPECTED_CORE_RUNTIME_API = 2;
 
 export function assertCoreRuntimeVersion(surface: string): void {
   checkCoreRuntimeVersion(surface, (coreRuntime as { RUNTIME_API_VERSION?: number }).RUNTIME_API_VERSION);

package/src/index.ts

@@ -81,6 +81,20 @@ export {
   type Resolved,
   type LayoutComponent,
 } from "./pipeline";
+// Connection auth helpers — turn an authenticated principal into a per-call
+// bearer token for an outbound connection (provider/mcp/openapi). The auth
+// INTEGRATION lives in the host layer by design, so these sit here (not in pure
+// @junejs/core). Generic + overridable; the Better Auth variant is structural
+// (adds no dependency).
+export {
+  linkedAccountAuth,
+  betterAuthAccessToken,
+  betterAuthAccountTokenStore,
+  type AccountTokenStore,
+  type LinkedAccountAuthOptions,
+  type ConnectionAuth,
+  type BetterAuthLike,
+} from "./connection-auth";
 export { createApp, type JuneApp, type CreateAppOptions } from "./app";
 export { createWorker, type WorkerManifest } from "./worker";
 export {

package/src/manifest.ts

@@ -0,0 +1,128 @@
+// The FREEZE, in-process: import route modules + layouts, build the manifest a
+// createWorker() can run immediately. Extracted from build.ts; used by
+// prerender and by the parity test (its render path is identical to the
+// Rolldown-bundled worker).
+
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { routeFromModule, type BrandedRoute } from "@junejs/core/route";
+import { freezeConfig } from "./config-freeze";
+import type { ExtraHandler, LayoutComponent, LoadingComponent, ResourceHandler } from "./pipeline";
+import { scanAppRoutes } from "./route-scan";
+import { findMiddlewareFile } from "./router";
+import { resolveBoundary } from "./segment";
+import type { WorkerManifest } from "./worker";
+
+export type ImportedLayout = { component: LayoutComponent; boundary: boolean };
+export async function importLayout(file: string): Promise<ImportedLayout | null> {
+  const mod = (await import(pathToFileURL(file).href)) as {
+    default?: LayoutComponent;
+    segmentBoundary?: unknown;
+  };
+  return typeof mod.default === "function"
+    ? { component: mod.default, boundary: mod.segmentBoundary === true }
+    : null;
+}
+
+export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
+  const appDir = join(appRoot, "app");
+  const frozen = await freezeConfig(appRoot);
+  const scanned = await scanAppRoutes(appRoot);
+
+  const layoutCache = new Map<string, ImportedLayout | null>();
+  const loadCached = async (f: string): Promise<ImportedLayout | null> => {
+    if (!layoutCache.has(f)) layoutCache.set(f, await importLayout(f));
+    return layoutCache.get(f) ?? null;
+  };
+  // The chain (root→leaf) + boundary index + shell key, via the SHARED resolver
+  // (the one place the deepest-wins rule lives), so the frozen manifest and the
+  // dev resolver can't drift — the parity contract.
+  const componentsFor = async (
+    files: string[],
+  ): Promise<{ chain: LayoutComponent[]; boundaryIndex: number | null; key: string | null }> => {
+    const items = [];
+    for (const f of files) {
+      const c = await loadCached(f);
+      items.push({ file: f, entry: c?.component ?? null, boundary: !!c?.boundary });
+    }
+    return resolveBoundary(items);
+  };
+
+  const loadingCache = new Map<string, LoadingComponent | null>();
+  const loadingFor = async (file?: string): Promise<LoadingComponent | undefined> => {
+    if (!file) return undefined;
+    if (!loadingCache.has(file)) {
+      const loaded = await importLayout(file);
+      loadingCache.set(file, loaded ? (loaded.component as LoadingComponent) : null);
+    }
+    return loadingCache.get(file) ?? undefined;
+  };
+
+  const routes: Record<string, BrandedRoute> = {};
+  const dynamicRoutes: Array<{ pattern: string; def: BrandedRoute }> = [];
+  const resourceRoutes: Array<{ pattern: string; handler: ResourceHandler }> = [];
+  const layoutChains: Record<string, LayoutComponent[]> = {};
+  const layoutBoundaries: Record<string, { index: number; key: string }> = {};
+  const loadings: Record<string, LoadingComponent> = {};
+
+  for (const r of scanned) {
+    const mod = await import(pathToFileURL(r.file).href);
+    // Resource route (route.*): the default export is the Response handler.
+    if (r.resource) {
+      const handler = (mod as { default?: unknown }).default;
+      if (typeof handler === "function") resourceRoutes.push({ pattern: r.path, handler: handler as ResourceHandler });
+      continue;
+    }
+    const def = routeFromModule(mod);
+    if (!def) continue;
+    const { chain, boundaryIndex, key } = await componentsFor(r.layouts);
+    const loading = await loadingFor(r.loading);
+    if (r.dynamic) {
+      dynamicRoutes.push({ pattern: r.path, def });
+      layoutChains[r.path] = chain;
+    } else {
+      routes[r.path] = def;
+      layoutChains[r.path] = chain;
+    }
+    if (boundaryIndex !== null && key !== null) layoutBoundaries[r.path] = { index: boundaryIndex, key };
+    if (loading) loadings[r.path] = loading;
+  }
+
+  let extra: ExtraHandler | undefined;
+  const extraFile = findMiddlewareFile(appDir);
+  if (extraFile) {
+    const mod = (await import(pathToFileURL(extraFile).href)) as { default?: unknown };
+    if (typeof mod.default === "function") extra = mod.default as ExtraHandler;
+  }
+
+  // The durable agent's DO address (createWorker routes the chat endpoint by
+  // it). Set whenever an agent/ directory exists — the surface is inert without
+  // an env.AGENT binding, so in-process consumers (prerender, the parity test)
+  // are unaffected.
+  let agentName: string | undefined;
+  const agentDir = join(appDir, frozen.agent.runtime.dir);
+  if (frozen.agent.runtime.enabled && existsSync(agentDir)) {
+    const cfgFile = join(agentDir, "agent.ts");
+    const cfg = existsSync(cfgFile)
+      ? ((await import(pathToFileURL(cfgFile).href)).default as { name?: string } | undefined)
+      : undefined;
+    agentName = cfg?.name ?? basename(agentDir);
+  }
+
+  return {
+    routes,
+    dynamicRoutes,
+    resourceRoutes,
+    layoutChains,
+    layoutBoundaries,
+    loadings,
+    document: frozen.document,
+    agent: frozen.agent,
+    agentName,
+    i18n: frozen.i18n,
+    earlyHints: frozen.earlyHints,
+    extra,
+  };
+}

package/src/route-scan.ts

@@ -0,0 +1,84 @@
+// Filesystem route discovery for the build: walk app/ for page.* files and
+// merge in the framework's .june/routes/ slot. Extracted from build.ts so the
+// scan/merge rules live beside each other, in one place — buildManifest and
+// juneBuild consume the SAME merged list via scanAppRoutes (they previously
+// each inlined the merge).
+
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+
+// The segment layout CHAIN root→leaf: every directory level (route groups
+// included) may contribute a layout.* that wraps routes below it.
+export type RouteEntry = {
+  path: string;
+  file: string;
+  dynamic: boolean;
+  resource?: boolean; // a route.* resource route (raw-Response handler), not a page
+  layouts: string[];
+  loading?: string; // nearest loading.tsx up the tree → streaming Suspense fallback
+};
+
+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[] = [],
+  loading?: string,
+): Promise<RouteEntry[]> {
+  const ownLayout = segmentFile(dir, "layout");
+  const chain = ownLayout ? [...layouts, ownLayout] : layouts;
+  const nearestLoading = segmentFile(dir, "loading") ?? loading;
+  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, nearestLoading);
+      continue;
+    }
+    const ext = e.name.match(/\.[^.]+$/)?.[0] ?? "";
+    if (!ROUTE_EXTS.includes(ext)) continue;
+    const base = basename(e.name, ext);
+    const resource = base === "route";
+    if (!PAGE_BASENAMES.has(base) && !resource) 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),
+      resource,
+      layouts: chain,
+      loading: nearestLoading,
+    });
+  }
+  return out;
+}
+
+// Merge routes: app/ takes priority over .june/routes/ (app/ is the escape hatch).
+// .june/routes/ is the convention slot for framework-generated routes (e.g. kura
+// writes its docs/search/og routes there so the user never manages boilerplate).
+export async function scanAppRoutes(appRoot: string): Promise<RouteEntry[]> {
+  const appDir = join(appRoot, "app");
+  const juneRoutesDir = join(appRoot, ".june", "routes");
+  const appRoutes = await scanRoutes(appDir);
+  const frameworkRoutes = existsSync(juneRoutesDir) ? await scanRoutes(juneRoutesDir) : [];
+  const appPaths = new Set(appRoutes.map((r) => r.path));
+  return [...appRoutes, ...frameworkRoutes.filter((r) => !appPaths.has(r.path))].sort((a, b) =>
+    a.path.localeCompare(b.path),
+  );
+}

package/src/turn-events.ts

@@ -0,0 +1,43 @@
+// turn-events.ts — one turn's live TurnEvents as an AsyncIterable, for a consumer in the
+// SAME process as the session: the Durable Object's delivered renders (agent-durable.ts)
+// and the native host's ChannelContext.runStream/resumeStream (agent-native.ts).
+
+import type { AgentSession, TurnEvent } from "@junejs/core/agent-runtime";
+
+// Subscribes eagerly at call time — not at first iteration — so the sseTurnStream timing
+// guarantee carries over (call this synchronously after start()/resume(), before any event
+// can emit); events landing before the consumer catches up are buffered. Ends after the
+// turn's terminal event (completed, failed, cancelled, or input.requested — a park ends
+// this stream; a later resume is a new one), and an early consumer exit (for-await
+// break/return) unsubscribes rather than buffering forever.
+export function observeTurnEvents(session: AgentSession, turnId: string): AsyncIterable<TurnEvent> {
+  const queue: TurnEvent[] = [];
+  let terminal = false;
+  let notify: (() => void) | undefined;
+  const unsub = session.observe((e) => {
+    queue.push(e);
+    if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "turn.cancelled" || e.type === "input.requested") terminal = true;
+    notify?.();
+  }, { turnId });
+  return {
+    [Symbol.asyncIterator]() {
+      return {
+        async next(): Promise<IteratorResult<TurnEvent>> {
+          for (;;) {
+            const e = queue.shift();
+            if (e) return { value: e, done: false };
+            if (terminal) { unsub(); return { value: undefined, done: true }; }
+            await new Promise<void>((resolve) => { notify = resolve; });
+            notify = undefined;
+          }
+        },
+        async return(): Promise<IteratorResult<TurnEvent>> {
+          unsub();
+          terminal = true;
+          queue.length = 0;
+          return { value: undefined, done: true };
+        },
+      };
+    },
+  };
+}