@junejs/server 0.0.24 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -30,8 +30,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@junejs/core": "0.0.24",
-    "@junejs/db": "0.0.24",
+    "@junejs/core": "0.0.25",
+    "@junejs/db": "0.0.25",
     "marked": "^18.0.5",
     "rolldown": "^1.1.0",
     "lightningcss": "^1.27.0"

package/src/build.ts

@@ -29,7 +29,7 @@ import { buildLinkHeader } from "@junejs/core/discovery";
 import { routeFromModule, type BrandedRoute } from "@junejs/core/route";
 import { workers, type JuneAdapter, type ResourcePlan } from "./adapter";
 import type { DocumentConfig } from "@junejs/core/document";
-import { collection } from "./content";
+import { generateContentModule } from "./content";
 import { createWorker, type WorkerManifest } from "./worker";
 import { findMiddlewareFile } from "./router";
 import { resolveBoundary } from "./segment";
@@ -113,29 +113,11 @@ export async function scanRoutes(
 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);
+  // Emission (incl. the per-locale layout) lives in ./content so it's pure and
+  // unit-testable; this stays the thin fs wrapper.
+  const { code, names } = generateContentModule(contentDir);
+  if (names.length === 0) return [];
+  await writeFile(join(appRoot, "app", "_content.ts"), code);
   return names;
 }
 

package/src/content.ts

@@ -9,7 +9,7 @@
 // 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 { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { marked } from "marked";
 
@@ -24,6 +24,9 @@ export type ContentEntry = {
   original: string;
   /** The body rendered to HTML (marked). */
   html: string;
+  /** The locale this entry was authored in — set for files under a `<locale>/`
+   *  subdir, undefined for the flat (default-locale) files. */
+  locale?: string;
 };
 
 // Minimal frontmatter: `key: value` lines between --- fences; `[a, b]` lists
@@ -56,7 +59,7 @@ function parseFrontmatter(raw: string): { data: ContentEntry["data"]; body: stri
 // 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 {
+function loadEntry(file: string, slug: string, locale?: string): ContentEntry {
   const mtime = statSync(file).mtimeMs;
   const hit = memo.get(file);
   if (hit && hit.mtime === mtime) return hit.entry;
@@ -69,34 +72,164 @@ function loadEntry(file: string, slug: string): ContentEntry {
     body,
     original,
     html: marked.parse(body, { async: false }) as string,
+    ...(locale ? { locale } : {}),
   };
   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);
-  });
+const isMd = (f: string) => f.endsWith(".md") || f.endsWith(".mdx");
+const slugOf = (f: string) => f.replace(/\.(md|mdx)$/, "");
+const byDate = (a: ContentEntry, b: ContentEntry) =>
+  String(b.data.date ?? "").localeCompare(String(a.data.date ?? "")) ||
+  a.slug.localeCompare(b.slug);
+
+// Per-locale content layout: flat `<dir>/*.md` are the DEFAULT-locale entries
+// (today's behavior, zero migration); each `<dir>/<locale>/*.md` subdir holds
+// that locale's variants. Isomorphic to the routing default (unprefixed) vs
+// locale (prefixed) split. A single-locale collection has no subdirs → `byLocale`
+// is empty and everything below collapses to the flat path.
+export type ScannedCollection = {
+  default: ContentEntry[];
+  byLocale: Record<string, ContentEntry[]>;
+};
+
+// BCP-47-shaped tag (language + optional script/region/variant subtags). Used to
+// decide whether a subdir is a locale bucket WITHOUT the i18n config: it accepts
+// `de`, `fr`, `zh-TW`, `pt-BR` and rejects `images`, `drafts`, `assets` — so a
+// stray folder can't become a phantom locale. Pass `knownLocales` for exact,
+// config-driven validation (the stronger check once the locale set is threaded in).
+const LOCALE_DIR = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+function isLocaleDir(name: string, known?: readonly string[]): boolean {
+  return known ? known.includes(name) : LOCALE_DIR.test(name);
 }
 
-/** 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;
+export function scanCollection(dir: string, knownLocales?: readonly string[]): ScannedCollection {
+  const def: ContentEntry[] = [];
+  const byLocale: Record<string, ContentEntry[]> = {};
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    if (ent.isDirectory()) {
+      // Only a configured locale (or, without a list, a BCP-47-shaped name) is a
+      // locale bucket — a stray content/<col>/images/ is NOT a phantom "images".
+      if (!isLocaleDir(ent.name, knownLocales)) continue;
+      const locale = ent.name;
+      const sub = join(dir, locale);
+      byLocale[locale] = readdirSync(sub)
+        .filter(isMd)
+        .map((f) => loadEntry(join(sub, f), slugOf(f), locale))
+        .sort(byDate);
+    } else if (isMd(ent.name)) {
+      def.push(loadEntry(join(dir, ent.name), slugOf(ent.name)));
+    }
+  }
+  def.sort(byDate);
+  return { default: def, byLocale };
+}
+
+/** All entries in a content directory, newest-first by `date` (then slug). With
+ *  a `locale`, each entry is its locale variant when present, else the default
+ *  (so a reader sees the whole collection, localized where available). */
+export function collection(dir: string, locale?: string): ContentEntry[] {
+  const { default: def, byLocale } = scanCollection(dir);
+  if (!locale || !byLocale[locale]) return def;
+  const variants = new Map(byLocale[locale].map((e) => [e.slug, e]));
+  return def.map((e) => variants.get(e.slug) ?? e).sort(byDate);
+}
+
+// Probe `<dir>/<slug>.{md,mdx}`, tagging the result with `locale`. null if absent.
+function probe(dir: string, slug: string, locale?: string): ContentEntry | null {
   for (const ext of [".md", ".mdx"]) {
-    const file = join(dir, slug + ext);
     try {
-      return loadEntry(file, slug);
+      return loadEntry(join(dir, slug + ext), slug, locale);
     } catch {
       /* try next ext */
     }
   }
   return null;
 }
+
+/** One entry by slug, or null. With a `locale`, prefer `<dir>/<locale>/<slug>`,
+ *  falling back to the flat default (a dev-warn flags a partial translation).
+ *  `fallback: false` is STRICT — a missing variant returns null (so a route can
+ *  404 rather than serve default-language content). */
+export function entry(
+  dir: string,
+  slug: string,
+  locale?: string,
+  opts?: { fallback?: boolean },
+): ContentEntry | null {
+  // Guard the slug — it comes from the URL.
+  if (!/^[A-Za-z0-9._-]+$/.test(slug)) return null;
+  if (!locale) return probe(dir, slug);
+  const variant = probe(join(dir, locale), slug, locale);
+  if (variant) return variant;
+  if (opts?.fallback === false) return null; // strict — no default-language bleed
+  const fallback = probe(dir, slug);
+  // The locale is otherwise translated here, but not this slug → a gap worth a
+  // dev signal (silent in production builds, where NODE_ENV is baked).
+  if (fallback && existsSync(join(dir, locale))) {
+    console.warn(`[june content] ${slug}: no "${locale}" variant — served default`);
+  }
+  return fallback;
+}
+
+// Generate the frozen `app/_content.ts` module text from `content/<collection>/`.
+// The FREEZE that removes node:fs from the worker graph: routes import frozen
+// entries + finders instead of reading the filesystem at request time.
+//
+// Off by absence: a collection with no `<locale>/` subdirs emits EXACTLY today's
+// shape (`POSTS` array + `post(slug)` finder) — single-locale apps are unchanged.
+// A collection WITH locale subdirs additionally emits a slug→locale→entry map, a
+// locale-aware `post(slug, locale?)` finder (variant → flat default, dev-warn on a
+// partial-translation miss, tree-shaken in production), and a locale-merged
+// `posts(locale?)` lister.
+export function generateContentModule(
+  contentDir: string,
+  knownLocales?: readonly string[],
+): { code: string; names: string[] } {
+  const strip = (e: ContentEntry) => ({
+    slug: e.slug,
+    data: e.data,
+    body: e.body,
+    original: e.original,
+    html: e.html,
+    ...(e.locale ? { locale: e.locale } : {}),
+  });
+  const dirs = readdirSync(contentDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+  const names: string[] = [];
+  let anyLocale = false;
+  let body = "";
+  for (const d of dirs) {
+    const { default: def, byLocale } = scanCollection(join(contentDir, d.name), knownLocales);
+    const CONST = 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`;
+    body += `export const ${CONST}: ContentEntry[] = ${JSON.stringify(def.map(strip), null, 2)};\n`;
+    if (Object.keys(byLocale).length === 0) {
+      body += `export const ${finder} = (slug: string): ContentEntry | null => ${CONST}.find((p) => p.slug === slug) ?? null;\n`;
+    } else {
+      anyLocale = true;
+      const map: Record<string, Record<string, unknown>> = {};
+      for (const [loc, entries] of Object.entries(byLocale)) {
+        for (const e of entries) (map[loc] ??= {})[e.slug] = strip(e);
+      }
+      body += `const ${CONST}_L: Record<string, Record<string, ContentEntry>> = ${JSON.stringify(map, null, 2)};\n`;
+      body +=
+        `export const ${finder} = (slug: string, locale?: string, opts?: { fallback?: boolean }): ContentEntry | null => {\n` +
+        `  const v = locale ? ${CONST}_L[locale]?.[slug] : undefined;\n` +
+        `  if (v) return v;\n` +
+        `  if (opts?.fallback === false) return null;\n` +
+        `  const d = ${CONST}.find((p) => p.slug === slug) ?? null;\n` +
+        `  if (process.env.NODE_ENV !== "production" && locale && ${CONST}_L[locale] && d) console.warn(\`[june content] ${d.name}/\${slug}: no "\${locale}" variant — served default\`);\n` +
+        `  return d;\n};\n`;
+      body += `export const ${d.name} = (locale?: string): ContentEntry[] => locale && ${CONST}_L[locale] ? ${CONST}.map((p) => ${CONST}_L[locale]![p.slug] ?? p) : ${CONST};\n`;
+    }
+    names.push(d.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";
+  const code =
+    "// AUTO-GENERATED by `june build` — edit content/**/*.md, not this file.\n" + entryType + body;
+  return { code, names };
+}

package/src/pipeline.ts

@@ -39,10 +39,12 @@ import { ensureScope, runInScope } from "@junejs/db";
 import type { AgentConfig } from "@junejs/core/config";
 import {
   LOCALE_COOKIE,
+  localeAlternates,
   localeDir,
   matchPinnedLocale,
   negotiateLocale,
   type I18nConfig,
+  type LocaleAlternate,
 } from "@junejs/core/i18n";
 import type { Resources } from "@junejs/core/resources";
 
@@ -214,6 +216,20 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     return { lang, dir: localeDir(lang, cfg.i18n) };
   }
 
+  // rel="alternate" hreflang links for this page's locale variants. Built from the
+  // locale-STRIPPED route path (so every locale's URL is generated correctly) and
+  // the current host (cross-origin locales come back absolute). undefined when
+  // i18n is off → single-locale pages emit no hreflang.
+  function alternatesFor(ctx: RouteContext): LocaleAlternate[] | undefined {
+    if (!cfg.i18n) return undefined;
+    const pinned = matchPinnedLocale(cfg.i18n, ctx.url.host, ctx.url.pathname);
+    const routePath = pinned ? pinned.pathname : ctx.url.pathname;
+    return localeAlternates(cfg.i18n, routePath, {
+      currentHost: ctx.url.host,
+      protocol: ctx.url.protocol.replace(":", ""),
+    });
+  }
+
   async function renderDocument(
     node: React.ReactNode,
     metadata: Metadata | undefined,
@@ -221,6 +237,7 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     chain: LayoutComponent[],
     locale?: string,
     boundaryKey?: string | null,
+    alternates?: LocaleAlternate[],
   ): Promise<Response> {
     // Wrap root→leaf: chain[0] is outermost.
     const wrapped = chain.reduceRight<React.ReactNode>(
@@ -233,6 +250,7 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         metadata,
         children: wrapped,
         shellKey: boundaryKey, // stamps data-june-shell on [data-june-root]
+        alternates,
         ...langDir(locale),
       }),
     );
@@ -317,6 +335,7 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         metadata,
         children: wrapped,
         shellKey: boundaryKey, // stamps data-june-shell on [data-june-root]
+        alternates: alternatesFor(ctx),
         ...langDir(ctx.locale),
       }),
       { onError: (e: unknown) => console.error("[june] streaming render error:", e) },
@@ -409,7 +428,7 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     // renders the whole chain (a hard load of the URL is never segment-scoped) —
     // but it stamps the shell key so the client knows which shell is mounted.
     if (target === "fragment") return renderFragment(node, meta, chain, boundaryIndex, boundaryKey);
-    return renderDocument(node, meta, 200, chain, ctx.locale, boundaryKey);
+    return renderDocument(node, meta, 200, chain, ctx.locale, boundaryKey, alternatesFor(ctx));
   }
 
   async function discovery(url: URL): Promise<Response | null> {
@@ -422,7 +441,10 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
       case "/robots.txt":
         return text(robotsTxt(url.origin), "text/plain; charset=utf-8");
       case "/sitemap.xml":
-        return text(sitemapXml(url.origin, await cfg.routeList()), "application/xml; charset=utf-8");
+        return text(
+          sitemapXml(url.origin, await cfg.routeList(), cfg.i18n),
+          "application/xml; charset=utf-8",
+        );
       case "/.well-known/api-catalog":
         return text(JSON.stringify(apiCatalog(url.origin, agent)), "application/linkset+json");
       case "/.well-known/mcp/server-card.json":