@junejs/server 0.1.3 → 0.2.0

package/src/route-scan.ts

@@ -0,0 +1,161 @@
+// 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";
+
+import { parseSegment } from "./route-rank";
+
+// 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
+  generated?: boolean; // scanned from .june/routes/ — ranks after every app/ route, as in dev
+  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 problems = routeProblems([appRoutes, frameworkRoutes], appRoot);
+  if (problems) throw new Error(problems);
+  const appPaths = new Set(appRoutes.map((r) => r.path));
+  const generated = frameworkRoutes
+    .filter((r) => !appPaths.has(r.path))
+    .map((r) => ({ ...r, generated: true }));
+  return [...appRoutes, ...generated].sort((a, b) =>
+    a.path.localeCompare(b.path),
+  );
+}
+
+// Two route files in ONE tree that resolve to the same URL: `(a)/about/page.tsx`
+// and `(b)/about/page.tsx` (groups vanish from the URL), or `page.tsx` next to
+// `index.tsx`. Pages and resource routes are counted apart — a page and a
+// route.ts at the same path are allowed, in one dir or across groups (the page
+// wins). No winner is defined for the rest: dev
+// would pick by group order and the worker by scan order, so the build refuses
+// them and dev reports them (#316).
+export function routeConflicts(routes: RouteEntry[]): Array<{ path: string; files: string[] }> {
+  const byKey = new Map<string, { path: string; files: string[] }>();
+  for (const r of routes) {
+    const key = `${r.resource ? "route" : "page"} ${r.path}`;
+    const hit = byKey.get(key);
+    if (hit) hit.files.push(r.file);
+    else byKey.set(key, { path: r.path, files: [r.file] });
+  }
+  return [...byKey.values()]
+    .filter((c) => c.files.length > 1)
+    .map((c) => ({ path: c.path, files: c.files.sort() }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// An optional or catch-all segment ([[x]], [...x], [[...x]]) must END the route
+// path (#315, the Next.js rule, opinionated). Mid-path there is no behavior to
+// keep: dev never matched past a catch-all nor skipped a mid-path [[x]], while
+// the worker's regex did both. A (group) after it is not a URL segment, so it's
+// fine. Returns the offending routes, path-sorted.
+const ENDS_PATH = new Set(["optional", "catchAll", "optionalCatchAll"]);
+const beforeLast = (path: string) => path.split("/").filter(Boolean).slice(0, -1).map((s) => parseSegment(s).kind);
+
+export function misplacedSegments(routes: RouteEntry[]): RouteEntry[] {
+  return routes
+    .filter((r) => beforeLast(r.path).some((k) => ENDS_PATH.has(k)))
+    .sort((a, b) => a.path.localeCompare(b.path) || a.file.localeCompare(b.file));
+}
+
+// Every route-table problem the build refuses and dev reports, as one message
+// (null when there are none). Each tree (app/, .june/routes/) is checked on its
+// own: the same path in both is not a conflict — app/ wins.
+export function routeProblems(trees: RouteEntry[][], appRoot: string): string | null {
+  const rel = (f: string) => relative(appRoot, f).split(sep).join("/");
+  const sections: string[] = [];
+
+  const conflicts = trees.flatMap(routeConflicts);
+  if (conflicts.length) {
+    sections.push(
+      "[june] more than one route file resolves to the same path — keep one per path:\n" +
+        conflicts.map((c) => `  ${c.path}: ${c.files.map(rel).join(", ")}`).join("\n"),
+    );
+  }
+
+  const misplaced = trees.flatMap(misplacedSegments);
+  if (misplaced.length) {
+    const lines = misplaced.map((r) => `  ${r.path}: ${rel(r.file)}`);
+    // Developers (and models) read [[x]] the SvelteKit way, skippable anywhere;
+    // say so when a single optional is the culprit, and point at the real tool.
+    if (misplaced.some((r) => beforeLast(r.path).includes("optional"))) {
+      lines.push(
+        "  Unlike SvelteKit, June does not skip a [[param]] mid-path. For a locale prefix, set i18n.locales in june.config.ts instead of a [[lang]] directory.",
+      );
+    }
+    sections.push(
+      "[june] an optional or catch-all segment must be the last segment of a route path — nothing may follow it:\n" +
+        lines.join("\n"),
+    );
+  }
+
+  return sections.length ? sections.join("\n") : null;
+}

package/src/router.ts

@@ -151,8 +151,10 @@ function routePath(appDir: string, file: string) {
 // Recursive-descent matcher over the app directory. Priority at every level:
 // exact static segment > [param] > [...catchAll], required before optional, ties
 // by name (route-rank.ts — the built worker sorts its route table by the same
-// ranking); route groups `(name)` descend without consuming a URL segment;
-// `_`-prefixed entries never participate.
+// ranking); `_`-prefixed entries never participate. Route groups `(name)` are
+// invisible in the URL, so they are invisible to ranking too: a group's children
+// compete as siblings of the level the group sits in (a grouped `[slug]` never
+// shadows a static sibling), while the group still contributes its layout.
 // Returns the page file, accumulated params (catch-all joins with "/"), and the
 // chain of segments (with their special files) from the app root to the page.
 export async function matchRouteTree(
@@ -162,86 +164,96 @@ export async function matchRouteTree(
 ): Promise<RouteTreeMatch | null> {
   const urlSegments = pathname.split("/").filter(Boolean).map(decodeURIComponent);
 
+  // One URL level = this dir plus every route group under it (groups nest), each
+  // with the segment chain down to it: the dir first, then groups in name order.
+  type Level = { dir: string; entries: DirEntry[]; segments: SegmentMatch[] };
+  async function levelAt(dir: string, chain: SegmentMatch[]): Promise<Level[]> {
+    // Ranked, not readdir order, so the pick is the same on every filesystem.
+    const entries = (await listDir(dir)).sort((a, b) => compareSegments(a.name, b.name));
+    const segments = [...chain, segmentAt(dir, entries)];
+    const levels: Level[] = [{ dir, entries, segments }];
+    for (const e of entries) {
+      if (e.dir && isRouteGroup(e.name)) levels.push(...(await levelAt(join(dir, e.name), segments)));
+    }
+    return levels;
+  }
+
+  // A URL level can span several real dirs: `(a)/blog` and `(b)/blog` are both
+  // `/blog`, so they descend TOGETHER — otherwise (a)/blog/[slug] would answer
+  // /blog/about before (b)/blog/about was ever seen.
+  type Node = { dir: string; chain: SegmentMatch[] };
+
   async function descend(
-    dir: string,
+    nodes: Node[],
     rest: string[],
     params: Record<string, string>,
-    chain: SegmentMatch[],
   ): Promise<RouteTreeMatch | null> {
-    // Ranked, not readdir order, so the pick is the same on every filesystem.
-    const entries = (await listDir(dir)).sort((a, b) => compareSegments(a.name, b.name));
-    const segments = [...chain, segmentAt(dir, entries)];
+    const levels = (await Promise.all(nodes.map((n) => levelAt(n.dir, n.chain)))).flat();
 
-    // Terminal: URL consumed → find the page (or resource route) in this dir.
+    // Terminal: URL consumed → find the page at this level, groups included,
+    // and only then a resource route: a page beats a route.ts at the same path
+    // even when the two sit in different groups (the worker ranks them so).
     if (rest.length === 0) {
-      const page =
-        fileFor(entries, dir, "page") ??
-        fileFor(entries, dir, "index") ??
-        fileFor(entries, dir, "route");
-      if (page) return { file: page, params, segments };
-    } else if (!options.pageConvention) {
+      for (const base of [["page", "index"], ["route"]]) {
+        for (const { dir: d, entries, segments } of levels) {
+          const file = base.map((b) => fileFor(entries, d, b)).find(Boolean);
+          if (file) return { file, params, segments };
+        }
+      }
+    } else if (!options.pageConvention && rest.length === 1) {
       // Legacy flat convention: a non-special leaf FILE names the final segment
       // (examples/rsc: about.tsx → /about). Only valid for the last segment.
-      if (rest.length === 1) {
-        const leaf = fileFor(entries, dir, rest[0]!);
-        if (leaf && !isSpecialFile(leaf) && !isPageFile(leaf)) {
-          return { file: leaf, params, segments };
-        }
+      for (const { dir: d, entries, segments } of levels) {
+        const leaf = fileFor(entries, d, rest[0]!);
+        if (leaf && !isSpecialFile(leaf) && !isPageFile(leaf)) return { file: leaf, params, segments };
       }
     }
 
-    // Route groups: try descending into every (group) without consuming URL.
-    for (const e of entries) {
-      if (!e.dir || !isRouteGroup(e.name)) continue;
-      const hit = await descend(join(dir, e.name), rest, params, segments);
-      if (hit) return hit;
+    // Every child dir at this level, groups flattened and same names merged, in
+    // rank order.
+    const children = new Map<string, Node[]>();
+    for (const lv of levels) {
+      for (const e of lv.entries) {
+        if (!e.dir || isRouteGroup(e.name)) continue;
+        const node = { dir: join(lv.dir, e.name), chain: lv.segments };
+        const same = children.get(e.name);
+        if (same) same.push(node);
+        else children.set(e.name, [node]);
+      }
     }
+    const names = [...children.keys()].sort(compareSegments);
 
     if (rest.length === 0) {
       // Optional segments match ABSENCE too: descend without consuming and
       // without setting the param.
-      for (const e of entries) {
-        if (!e.dir || !(isOptionalDir(e.name) || isOptionalCatchAllDir(e.name))) continue;
-        const hit = await descend(join(dir, e.name), [], params, segments);
+      for (const name of names) {
+        if (!(isOptionalDir(name) || isOptionalCatchAllDir(name))) continue;
+        const hit = await descend(children.get(name)!, [], params);
         if (hit) return hit;
       }
       return null;
     }
     const [head, ...tail] = rest as [string, ...string[]];
 
-    // 1) exact static dir
-    const exact = entries.find((e) => e.dir && e.name === head);
-    if (exact) {
-      const hit = await descend(join(dir, head), tail, params, segments);
-      if (hit) return hit;
-    }
-    // 2) [param] and [[param]] dirs consume one segment
-    for (const e of entries) {
-      if (!e.dir || !(isParamDir(e.name) || isOptionalDir(e.name))) continue;
-      const hit = await descend(
-        join(dir, e.name),
-        tail,
-        { ...params, [paramName(e.name)]: head },
-        segments,
-      );
-      if (hit) return hit;
-    }
-    // 3) [...catchAll] and [[...catchAll]] dirs consume everything remaining
-    for (const e of entries) {
-      if (!e.dir || !(isCatchAllDir(e.name) || isOptionalCatchAllDir(e.name))) continue;
-      const hit = await descend(
-        join(dir, e.name),
-        [],
-        { ...params, [paramName(e.name)]: rest.join("/") },
-        segments,
-      );
+    for (const name of names) {
+      const into = children.get(name)!;
+      let hit: RouteTreeMatch | null = null;
+      if (isParamDir(name) || isOptionalDir(name)) {
+        // [param] and [[param]] consume one segment
+        hit = await descend(into, tail, { ...params, [paramName(name)]: head });
+      } else if (isCatchAllDir(name) || isOptionalCatchAllDir(name)) {
+        // [...catchAll] and [[...catchAll]] consume everything remaining
+        hit = await descend(into, [], { ...params, [paramName(name)]: rest.join("/") });
+      } else if (name === head) {
+        hit = await descend(into, tail, params); // exact static dir
+      }
       if (hit) return hit;
     }
 
     return null;
   }
 
-  return descend(appDir, urlSegments, {}, []);
+  return descend([{ dir: appDir, chain: [] }], urlSegments, {});
 }
 
 // 404 path: walk the longest matchable STATIC prefix of the URL collecting

package/src/rsc-runtime/rsc-worker.tsx

@@ -36,7 +36,8 @@ async function streamToString(stream: ReadableStream<Uint8Array>): Promise<strin
   return out;
 }
 
-async function renderDocument(path: string): Promise<string | null> {
+async function renderDocument(url: URL): Promise<string | null> {
+  const path = url.pathname;
   // Non-literal specifier → rolldown leaves it as a runtime import, so the
   // react-server server bundle is loaded (not re-bundled) from beside this file.
   const serverUrl = new URL("./server.js", import.meta.url).href;
@@ -50,7 +51,8 @@ async function renderDocument(path: string): Promise<string | null> {
   }) as unknown as Promise<React.ReactNode>;
 
   const html = await renderToReadableStream(
-    <Document config={DOC_CONFIG}>
+    // RSC routes are exact paths (no locale prefix), so the home route IS "/".
+    <Document config={DOC_CONFIG} pageUrl={url.href} isHome={path === "/"}>
       <Root tree={tree} />
     </Document>,
   );
@@ -62,8 +64,7 @@ async function renderDocument(path: string): Promise<string | null> {
 
 export default {
   async fetch(request: Request): Promise<Response> {
-    const path = new URL(request.url).pathname;
-    const body = await renderDocument(path);
+    const body = await renderDocument(new URL(request.url));
     if (body === null) return new Response("Not Found", { status: 404 });
     return new Response(body, { headers: { "content-type": "text/html; charset=utf-8" } });
   },

package/src/sqlite-driver.ts

@@ -135,6 +135,33 @@ export function makeWarningFilter(original: EmitWarning): EmitWarning {
 // runtime, which is exactly what the typeof guard checks.
 declare const Bun: unknown;
 
+// A file database commits durably: WAL, fsynced on every commit. SQLite's default
+// rollback journal (DELETE mode) commits by unlinking the journal, and at
+// synchronous=FULL it does not fsync the directory after that unlink — so a power
+// cut right after a commit can bring the journal back, and the next open rolls the
+// committed transaction back. On a VM power cut that lost the last committed agent
+// turn 5 times out of 5; with WAL + FULL, 0 of 5. FULL is set explicitly: it is a
+// build-time default, and WAL at synchronous=NORMAL skips the per-commit fsync.
+// journal_mode=WAL persists in the file; `:memory:` has no journal to change.
+// A PRAGMA that throws (a locked file mid-switch) closes the handle it was handed,
+// so a retry is not blocked by a descriptor nobody can reach; the original error
+// is what surfaces. Exported for the unit test of that path.
+export function useDurableJournal(db: SyncSqlite, path: string): SyncSqlite {
+  if (path === ":memory:" || path === "") return db;
+  try {
+    db.exec("PRAGMA journal_mode=WAL");
+    db.exec("PRAGMA synchronous=FULL");
+  } catch (err) {
+    try {
+      db.close();
+    } catch {
+      // the setup error is the one worth reporting
+    }
+    throw err;
+  }
+  return db;
+}
+
 // Open a LOCAL *synchronous* sqlite handle on whichever runtime we're under —
 // bun:sqlite under Bun, node:sqlite under Node. This is the raw synchronous
 // surface: asyncSqlite() wraps it as the edge-safe async JuneDb (below), while
@@ -148,7 +175,7 @@ export async function openLocalSqliteSync(path: string): Promise<SyncSqlite> {
     const { Database } = (await import(specifier)) as {
       Database: new (p: string, o?: { create?: boolean }) => SyncSqlite;
     };
-    return new Database(path, { create: true });
+    return useDurableJournal(new Database(path, { create: true }), path);
   }
 
   // Node: node:sqlite is a builtin, but only flag-free on a recent-enough
@@ -172,11 +199,14 @@ export async function openLocalSqliteSync(path: string): Promise<SyncSqlite> {
   }
   const db = new mod.DatabaseSync(path);
   // Adapt node:sqlite (prepare()) to the query()-shaped SyncSqlite surface.
-  return {
-    query: (sql) => db.prepare(sql),
-    exec: (sql) => db.exec(sql),
-    close: () => db.close(),
-  };
+  return useDurableJournal(
+    {
+      query: (sql) => db.prepare(sql),
+      exec: (sql) => db.exec(sql),
+      close: () => db.close(),
+    },
+    path,
+  );
 }
 
 // Open a LOCAL sqlite file (or ":memory:") as the async JuneDb — the single seam

package/src/tsconfig-jsx.ts

@@ -9,8 +9,8 @@ import { join } from "node:path";
 // tsconfig.json is JSONC by convention (comments + trailing commas are idiomatic), and a strict
 // JSON.parse failure here silently degrades to "not declared" → the conflict warning reappears.
 // Strip comments (`//` only at line-start/after-whitespace so "https://…" in strings survives)
-// and trailing commas before parsing.
-const stripJsonc = (s: string): string =>
+// and trailing commas before parsing. Shared: agent-compile's tsconfig sniff parses the same way.
+export const stripJsonc = (s: string): string =>
   s
     .replace(/\/\*[\s\S]*?\*\//g, "")
     .replace(/(^|\s)\/\/.*$/gm, "$1")

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 };
+        },
+      };
+    },
+  };
+}

package/src/web-manifest.ts

@@ -0,0 +1,38 @@
+// The generated web app manifest (/manifest.webmanifest) — Android's "Add to
+// Home Screen" name, icons, and colours, built from the same config the
+// document renders with. Worker-safe (no node:*): the pipeline serves it like
+// the SVG favicon, so dev, the worker, and the static build all agree.
+import { siteShortName } from "@junejs/core/config";
+import { resolveThemeColor, type DocumentConfig } from "@junejs/core/document";
+
+// The home-screen label: site.shortName, else the site name's leading segment
+// ("June — build agents into real apps" → "June"). Launchers truncate past
+// ~12 characters, and a tagline is never the label anyone wants.
+export const shortName = (site: DocumentConfig["site"]): string | undefined => siteShortName(site);
+
+export function webManifest(config: DocumentConfig): string {
+  const base = config.basePath ?? "";
+  const theme = resolveThemeColor(config);
+  // A manifest has ONE theme colour; a { light, dark } pair has no honest single
+  // value, so both colour fields are left to the browser then.
+  const color = typeof theme === "string" ? theme : undefined;
+  const manifest = {
+    name: config.site.name,
+    short_name: shortName(config.site),
+    description: config.site.description,
+    start_url: `${base}/`,
+    scope: `${base}/`,
+    // "browser": a home-screen shortcut that opens a normal tab. standalone
+    // (app-like, no URL bar) changes how a site behaves, so it stays opt-in via
+    // your own public/manifest.webmanifest.
+    display: "browser",
+    ...(color ? { theme_color: color, background_color: color } : {}),
+    icons: [
+      { src: `${base}/icon-192.png`, sizes: "192x192", type: "image/png" },
+      { src: `${base}/icon-512.png`, sizes: "512x512", type: "image/png" },
+      // The same full-bleed art: its glyph sits inside the maskable safe zone.
+      { src: `${base}/icon-512.png`, sizes: "512x512", type: "image/png", purpose: "maskable" },
+    ],
+  };
+  return JSON.stringify(manifest, null, 2) + "\n";
+}