@caelo-cms/shared 0.10.22 → 0.10.23

package/src/genesis.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #163 — Site Genesis shared shapes.
+ *
+ * Design-time is divergent: the AI drafts complete freeform HTML pages
+ * (one per design direction) and the operator picks one; the CMS
+ * structure is derived FROM that choice (#164's compiler). These are
+ * the boundary schemas for the brief + the draft rows.
+ */
+
+import { z } from "zod";
+
+/**
+ * The structured Design Brief the discovery dialog produces. Every
+ * field optional — the AI fills what the conversation answered; the
+ * draft prompts degrade gracefully on gaps. Stored on
+ * `site_defaults.design_brief`.
+ */
+export const designBriefSchema = z
+  .object({
+    audience: z.string().min(1).max(500).optional(),
+    /** 3–5 adjectives the operator wants the design to feel like. */
+    moodWords: z.array(z.string().min(1).max(40)).max(12).optional(),
+    tone: z.string().min(1).max(300).optional(),
+    industry: z.string().min(1).max(200).optional(),
+    differentiators: z.string().min(1).max(1000).optional(),
+    imageryDirection: z.string().min(1).max(500).optional(),
+    avoid: z.string().min(1).max(500).optional(),
+  })
+  .strict();
+export type DesignBrief = z.infer<typeof designBriefSchema>;
+
+/** Complete single-file drafts stay well under this (inline CSS only). */
+export const GENESIS_DRAFT_MAX_HTML_BYTES = 300_000;
+
+export const genesisDraftStatus = z.enum(["candidate", "selected", "discarded"]);
+export type GenesisDraftStatus = z.infer<typeof genesisDraftStatus>;
+
+/** issue #199 — where a draft came from. */
+export const genesisDraftSourceKind = z.enum(["genesis", "byod_image", "byod_html"]);
+export type GenesisDraftSourceKind = z.infer<typeof genesisDraftSourceKind>;
+
+export const genesisAddDraftInput = z
+  .object({
+    /** Human-readable design direction ("bold editorial"). */
+    direction: z.string().min(3).max(120),
+    /** Why this direction fits the brief — shown beside the preview. */
+    rationale: z.string().max(1000).default(""),
+    /** Complete self-contained single-file HTML. */
+    html: z.string().min(200).max(GENESIS_DRAFT_MAX_HTML_BYTES),
+    /** issue #199 — 'byod_image' (AI reproduction of an operator
+     *  mockup) / 'byod_html' (operator HTML, sanitised at the op). */
+    sourceKind: genesisDraftSourceKind.default("genesis"),
+    /** issue #199 — byod_image only: the uploaded mockup's media
+     *  asset. The parity gate uses THIS image as the reference. */
+    referenceAssetId: z.string().uuid().optional(),
+  })
+  .strict();
+export type GenesisAddDraftInput = z.infer<typeof genesisAddDraftInput>;
+
+/**
+ * issue #199 — strip <script> blocks from operator-provided draft
+ * HTML. Defense in depth: drafts render inside sandbox="" iframes
+ * (scripts never execute there), but stored HTML flows onward into
+ * materialisation, so the boundary removes them outright. Linear
+ * scan per the #113 discipline; case-insensitive; unterminated
+ * script blocks drop everything to EOF (never leak half a script).
+ */
+export function sanitizeDraftHtml(html: string): string {
+  const lower = html.toLowerCase();
+  let out = "";
+  let from = 0;
+  while (true) {
+    const open = lower.indexOf("<script", from);
+    if (open === -1) {
+      out += html.slice(from);
+      return out;
+    }
+    out += html.slice(from, open);
+    const close = lower.indexOf("</script", open);
+    if (close === -1) return out;
+    const closeEnd = lower.indexOf(">", close);
+    if (closeEnd === -1) return out;
+    from = closeEnd + 1;
+  }
+}

package/src/i18n.test.ts

@@ -0,0 +1,274 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  buildHreflangLinks,
+  computeContentHash,
+  isHomeSlug,
+  type LocaleConfig,
+  lintLocaleConfig,
+  pageIsLocaleHome,
+  resolveLocaleUrl,
+} from "./i18n.js";
+
+const ENG: LocaleConfig = {
+  code: "en",
+  displayName: "English",
+  urlStrategy: "none",
+  urlHost: null,
+  isDefault: true,
+};
+
+const DE_SUBDIR: LocaleConfig = {
+  code: "de",
+  displayName: "Deutsch",
+  urlStrategy: "subdirectory",
+  urlHost: null,
+  isDefault: false,
+};
+
+const DE_SUBDOMAIN: LocaleConfig = {
+  code: "de",
+  displayName: "Deutsch",
+  urlStrategy: "subdomain",
+  urlHost: "de.example.com",
+  isDefault: false,
+};
+
+const DE_DOMAIN: LocaleConfig = {
+  code: "de",
+  displayName: "Deutsch",
+  urlStrategy: "domain",
+  urlHost: "example.de",
+  isDefault: false,
+};
+
+describe("resolveLocaleUrl", () => {
+  it("strategy=none yields bare slug under siteBaseUrl with trailing slash", () => {
+    expect(resolveLocaleUrl(ENG, "about", "https://example.com")).toBe(
+      "https://example.com/about/",
+    );
+  });
+
+  it("strategy=subdirectory prefixes the locale code", () => {
+    expect(resolveLocaleUrl(DE_SUBDIR, "about", "https://example.com")).toBe(
+      "https://example.com/de/about/",
+    );
+  });
+
+  it("strategy=subdomain uses urlHost", () => {
+    expect(resolveLocaleUrl(DE_SUBDOMAIN, "about", "https://example.com")).toBe(
+      "https://de.example.com/about/",
+    );
+  });
+
+  it("strategy=domain uses urlHost", () => {
+    expect(resolveLocaleUrl(DE_DOMAIN, "about", "https://example.com")).toBe(
+      "https://example.de/about/",
+    );
+  });
+
+  it("strategy=subdomain throws when urlHost missing", () => {
+    expect(() =>
+      resolveLocaleUrl({ ...DE_SUBDOMAIN, urlHost: null }, "about", "https://example.com"),
+    ).toThrow(/url_host/);
+  });
+
+  it("trailing slashes on baseUrl are normalised", () => {
+    expect(resolveLocaleUrl(ENG, "about", "https://example.com//")).toBe(
+      "https://example.com/about/",
+    );
+  });
+
+  it("leading slashes on slug are stripped", () => {
+    expect(resolveLocaleUrl(ENG, "/about", "https://example.com")).toBe(
+      "https://example.com/about/",
+    );
+  });
+
+  it("home slug renders as the locale root (no extra path segment)", () => {
+    expect(resolveLocaleUrl(ENG, "home", "https://example.com")).toBe("https://example.com/");
+    expect(resolveLocaleUrl(DE_SUBDIR, "home", "https://example.com")).toBe(
+      "https://example.com/de/",
+    );
+    expect(resolveLocaleUrl(DE_SUBDOMAIN, "home", "https://example.com")).toBe(
+      "https://de.example.com/",
+    );
+  });
+
+  it("explicit isHomePage collapses a NON-magic slug to the locale root (0184)", () => {
+    // slug "en" is a normal nested page without the designation...
+    expect(resolveLocaleUrl(ENG, "en", "https://example.com")).toBe("https://example.com/en/");
+    // ...and the locale root once designated, per url strategy.
+    expect(resolveLocaleUrl(ENG, "en", "https://example.com", "directory", true)).toBe(
+      "https://example.com/",
+    );
+    expect(resolveLocaleUrl(DE_SUBDIR, "en", "https://example.com", "directory", true)).toBe(
+      "https://example.com/de/",
+    );
+    expect(resolveLocaleUrl(DE_SUBDOMAIN, "en", "https://example.com", "directory", true)).toBe(
+      "https://de.example.com/",
+    );
+  });
+});
+
+describe("isHomeSlug", () => {
+  it("recognises the magic-slug sentinels regardless of surrounding slashes", () => {
+    for (const s of ["", "home", "index", "/", "/home/", "/index"]) {
+      expect(isHomeSlug(s)).toBe(true);
+    }
+  });
+
+  it("treats any other slug as non-home", () => {
+    for (const s of ["about", "en", "blog/post", "homepage"]) {
+      expect(isHomeSlug(s)).toBe(false);
+    }
+  });
+});
+
+describe("pageIsLocaleHome (0184 shared predicate)", () => {
+  const PAGE = "11111111-1111-4111-8111-111111111111";
+  const OTHER = "22222222-2222-4222-8222-222222222222";
+
+  it("is true when the page IS the locale's designated home_page_id", () => {
+    expect(pageIsLocaleHome(PAGE, "en", PAGE)).toBe(true);
+  });
+
+  it("is true for a magic slug even with no designation", () => {
+    expect(pageIsLocaleHome(PAGE, "home", null)).toBe(true);
+    expect(pageIsLocaleHome(PAGE, "index", undefined)).toBe(true);
+  });
+
+  it("is false for a non-magic slug that isn't the designated page", () => {
+    expect(pageIsLocaleHome(PAGE, "en", OTHER)).toBe(false);
+    expect(pageIsLocaleHome(PAGE, "about", null)).toBe(false);
+  });
+});
+
+// renderLanguageSelector lives in structured-sets.ts but exercises the
+// same i18n primitives (resolveLocaleUrl produces hrefs the test feeds
+// in pre-resolved). Cover the three paths: vanilla render, override
+// relabel, hidden locale.
+import { renderLanguageSelector } from "./structured-sets.js";
+
+describe("renderLanguageSelector", () => {
+  const ENGLISH = {
+    code: "en",
+    displayName: "English",
+    href: "https://example.com/about/",
+    isCurrent: true,
+  };
+  const GERMAN = {
+    code: "de",
+    displayName: "Deutsch",
+    href: "https://example.com/de/about/",
+    isCurrent: false,
+  };
+
+  it("emits one anchor per locale + aria-current on the current page", () => {
+    const html = renderLanguageSelector({ availableLocales: [ENGLISH, GERMAN] });
+    expect(html).toContain('hreflang="en"');
+    expect(html).toContain('hreflang="de"');
+    expect(html).toContain('aria-current="true"');
+    expect(html).toContain("English");
+    expect(html).toContain("Deutsch");
+  });
+
+  it("override relabels a locale", () => {
+    const html = renderLanguageSelector({
+      availableLocales: [ENGLISH, GERMAN],
+      overrides: [{ locale: "de", label: "DE 🇩🇪" }],
+    });
+    expect(html).toContain("DE 🇩🇪");
+    expect(html).not.toContain("Deutsch");
+  });
+
+  it("hidden override drops the locale entirely", () => {
+    const html = renderLanguageSelector({
+      availableLocales: [ENGLISH, GERMAN],
+      overrides: [{ locale: "de", hidden: true }],
+    });
+    expect(html).toContain('hreflang="en"');
+    expect(html).not.toContain('hreflang="de"');
+  });
+
+  it("empty available list returns empty string", () => {
+    expect(renderLanguageSelector({ availableLocales: [] })).toBe("");
+  });
+
+  it("escapes attribute special chars", () => {
+    const html = renderLanguageSelector({
+      availableLocales: [{ code: "en", displayName: "EN&Co", href: "/?a=1&b=2", isCurrent: false }],
+    });
+    expect(html).toContain("a=1&b=2");
+    expect(html).toContain("EN&Co");
+  });
+});
+
+describe("buildHreflangLinks", () => {
+  it("emits one link per locale + x-default for the default", () => {
+    const html = buildHreflangLinks([
+      { localeCode: "en", url: "https://example.com/about", isDefault: true },
+      { localeCode: "de", url: "https://example.com/de/about", isDefault: false },
+    ]);
+    expect(html).toContain('hreflang="en"');
+    expect(html).toContain('hreflang="de"');
+    expect(html).toContain('hreflang="x-default"');
+    expect(html).toContain('href="https://example.com/about"');
+  });
+
+  it("returns empty string when no entries", () => {
+    expect(buildHreflangLinks([])).toBe("");
+  });
+
+  it("escapes attribute special characters", () => {
+    const html = buildHreflangLinks([
+      { localeCode: "en", url: "https://example.com/?a=1&b=2", isDefault: true },
+    ]);
+    expect(html).toContain("a=1&b=2");
+  });
+});
+
+describe("computeContentHash", () => {
+  it("is stable across runs for the same input", async () => {
+    const a = await computeContentHash({ x: 1, y: [1, 2] });
+    const b = await computeContentHash({ x: 1, y: [1, 2] });
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("is order-independent for object keys", async () => {
+    const a = await computeContentHash({ x: 1, y: 2 });
+    const b = await computeContentHash({ y: 2, x: 1 });
+    expect(a).toBe(b);
+  });
+
+  it("is order-dependent for arrays", async () => {
+    const a = await computeContentHash({ x: [1, 2] });
+    const b = await computeContentHash({ x: [2, 1] });
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("lintLocaleConfig", () => {
+  it("warns when subdomain/domain used while advanced toggle is off", () => {
+    const warnings = lintLocaleConfig([ENG, DE_SUBDOMAIN], false);
+    expect(warnings.find((w) => w.code === "advanced-routing-disabled")).toBeTruthy();
+  });
+
+  it("does not warn when toggle matches usage", () => {
+    const warnings = lintLocaleConfig([ENG, DE_SUBDOMAIN], true);
+    expect(warnings.find((w) => w.code === "advanced-routing-disabled")).toBeFalsy();
+  });
+
+  it("warns when subdomain locale lacks urlHost", () => {
+    const broken: LocaleConfig = { ...DE_SUBDOMAIN, urlHost: null };
+    const warnings = lintLocaleConfig([ENG, broken], true);
+    expect(warnings.find((w) => w.code === "missing-url-host")).toBeTruthy();
+  });
+
+  it("warns about mixed default-none + subdir-sibling configs", () => {
+    const warnings = lintLocaleConfig([ENG, DE_SUBDIR], true);
+    expect(warnings.find((w) => w.code === "mixed-default-none-subdir")).toBeTruthy();
+  });
+});

package/src/i18n.ts

@@ -0,0 +1,269 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P9 — i18n primitives shared between the static generator, the
+ * preview op, and the admin UI:
+ *
+ *   computeContentHash(page, modules) — sha256 of canonical-JSON
+ *     content. Drives `pages.content_hash` + the translation_status
+ *     recompute path.
+ *
+ *   resolveLocaleUrl(locale, slug, siteBaseUrl, pageUrlStyle?, isHomePage?) —
+ *     builds the public URL for a (locale, slug) tuple given the
+ *     locale's url_strategy + url_host. `isHomePage` forces the locale
+ *     root (0184 explicit designation). Used by:
+ *       - hreflang emitter
+ *       - sitemap.xml emitter (when extended for i18n)
+ *       - language-selector module
+ *
+ *   buildHreflangLinks(currentLocale, perLocaleUrls, defaultLocaleCode) —
+ *     emits the `<link rel="alternate" hreflang=...>` markup.
+ *
+ *   lintLocaleConfig(locales, advancedUrlRouting) — surfaces config
+ *     warnings (mixed strategies, missing url_host for subdomain/
+ *     domain, default locale using `none` alongside subdirectory
+ *     siblings, advanced strategy chosen while toggle is off).
+ */
+
+const TEXT_ENCODER = new TextEncoder();
+
+/**
+ * Strip leading and trailing `/` characters with a single linear scan.
+ *
+ * Replaces the regex `/^\/+|\/+$/g`, whose trailing-slash branch
+ * backtracks O(n²) on a long run of slashes that is not at end-of-string
+ * (CodeQL js/polynomial-redos). This char-index walk is unconditionally
+ * linear and produces byte-identical output for every input.
+ */
+export function trimSlashes(s: string): string {
+  let start = 0;
+  let end = s.length;
+  while (start < end && s.charCodeAt(start) === 47 /* '/' */) start += 1;
+  while (end > start && s.charCodeAt(end - 1) === 47 /* '/' */) end -= 1;
+  return s.slice(start, end);
+}
+
+/**
+ * Strip only trailing `/` characters with a single linear scan — the
+ * non-backtracking replacement for `/\/+$/` (same ReDoS class as above).
+ * Used for base URLs, which carry a scheme and must keep their leading
+ * characters.
+ */
+export function trimTrailingSlashes(s: string): string {
+  let end = s.length;
+  while (end > 0 && s.charCodeAt(end - 1) === 47 /* '/' */) end -= 1;
+  return s.slice(0, end);
+}
+
+export interface LocaleConfig {
+  code: string;
+  displayName: string;
+  urlStrategy: "none" | "subdirectory" | "subdomain" | "domain";
+  urlHost: string | null;
+  isDefault: boolean;
+}
+
+/**
+ * The "magic slug" sentinel test: a page whose slug is empty, `home`,
+ * or `index` is the locale root by convention even without an explicit
+ * `locales.home_page_id` designation. Leading/trailing slashes are
+ * ignored so `/home/` reads the same as `home`.
+ */
+export function isHomeSlug(slug: string): boolean {
+  const s = trimSlashes(slug);
+  return s === "" || s === "home" || s === "index";
+}
+
+/**
+ * The single home-decision predicate every URL/output-path site must
+ * use so canonical, hreflang, redirects, and the emitted file agree
+ * (0184 explicit-homepage feature). A page is the locale root when it
+ * IS the locale's designated `home_page_id` OR carries a magic slug.
+ *
+ * @param pageId            The page being resolved.
+ * @param slug              That page's slug.
+ * @param localeHomePageId  `locales.home_page_id` for the page's locale
+ *                          (null/undefined when no page is designated).
+ */
+export function pageIsLocaleHome(
+  pageId: string,
+  slug: string,
+  localeHomePageId: string | null | undefined,
+): boolean {
+  return (localeHomePageId != null && pageId === localeHomePageId) || isHomeSlug(slug);
+}
+
+/**
+ * Build a public-facing URL for a (locale, slug) tuple. Pure function —
+ * no DB access — so the static generator can call it for every page
+ * without round-trips.
+ *
+ * @param locale       The target locale's full config row.
+ * @param slug         Path component (e.g. "about", "blog/post-1"). No leading slash.
+ * @param siteBaseUrl  Default base URL when the strategy is `none` or
+ *                     `subdirectory` (e.g. "https://example.com").
+ * @param pageUrlStyle Page emission style (see below).
+ * @param isHomePage   Explicit homepage designation (0184 —
+ *                     `locales.home_page_id`). When true this page IS the
+ *                     locale root and resolves to `<base>/` regardless of
+ *                     its own slug. The explicit flag WINS over the slug
+ *                     sentinel below; the sentinel stays as a back-compat
+ *                     fallback for callers that can't cheaply surface the
+ *                     designation.
+ * @returns Absolute URL, including scheme + host.
+ */
+export function resolveLocaleUrl(
+  locale: LocaleConfig,
+  slug: string,
+  siteBaseUrl: string,
+  // v0.2.85 — page emission style. 'directory' (default) builds
+  // URLs ending in `/<slug>/`; 'no-extension' builds URLs ending
+  // in `/<slug>` (no trailing slash) to match what the bucket
+  // actually serves when pages are emitted as bare slugs. Home
+  // page is always `<base>/` regardless of style.
+  pageUrlStyle: "directory" | "no-extension" = "directory",
+  isHomePage?: boolean,
+): string {
+  const stripped = trimSlashes(slug);
+  // 0184 — the explicit designation wins; the slug sentinel
+  // (""/`home`/`index`) survives as a back-compat fallback so a page the
+  // AI never ran set_home_page on still resolves to the root. Shared
+  // `isHomeSlug` keeps this test identical across every home-decision site.
+  const isHome = isHomePage === true || isHomeSlug(stripped);
+  // tail: the path component appended after `<base>/` or `<base>/<locale>/`.
+  // 'directory' style: trailing slash for non-home so the URL points at
+  // the directory the bucket serves index.html from.
+  // 'no-extension' style: no trailing slash, no extension — the URL
+  // points at the bare-slug object the bucket serves directly.
+  const tail = isHome ? "" : pageUrlStyle === "no-extension" ? stripped : `${stripped}/`;
+  const base = trimTrailingSlashes(siteBaseUrl);
+  switch (locale.urlStrategy) {
+    case "none":
+      return tail ? `${base}/${tail}` : `${base}/`;
+    case "subdirectory":
+      // Default locale with strategy `subdirectory` still gets the prefix
+      // unless the migration set strategy=none for it. The decision is
+      // explicit per locale row, not implicit on isDefault.
+      return tail ? `${base}/${locale.code}/${tail}` : `${base}/${locale.code}/`;
+    case "subdomain": {
+      if (!locale.urlHost) {
+        throw new Error(
+          `locale '${locale.code}' uses url_strategy='subdomain' without url_host — config invalid`,
+        );
+      }
+      const protocol = base.startsWith("http://") ? "http://" : "https://";
+      return tail ? `${protocol}${locale.urlHost}/${tail}` : `${protocol}${locale.urlHost}/`;
+    }
+    case "domain": {
+      if (!locale.urlHost) {
+        throw new Error(
+          `locale '${locale.code}' uses url_strategy='domain' without url_host — config invalid`,
+        );
+      }
+      const protocol = base.startsWith("http://") ? "http://" : "https://";
+      return tail ? `${protocol}${locale.urlHost}/${tail}` : `${protocol}${locale.urlHost}/`;
+    }
+  }
+}
+
+/**
+ * Emit `<link rel="alternate" hreflang="…">` tags for every locale
+ * that has a published variant of this page. The default locale also
+ * gets an `x-default` entry per Google's i18n guidance.
+ *
+ * Returned as a single string suitable for splicing into <head>.
+ */
+export function buildHreflangLinks(
+  perLocaleUrls: ReadonlyArray<{ localeCode: string; url: string; isDefault: boolean }>,
+): string {
+  if (perLocaleUrls.length === 0) return "";
+  const lines: string[] = [];
+  for (const v of perLocaleUrls) {
+    lines.push(
+      `<link rel="alternate" hreflang="${escapeAttr(v.localeCode)}" href="${escapeAttr(v.url)}" />`,
+    );
+  }
+  const def = perLocaleUrls.find((v) => v.isDefault);
+  if (def) {
+    lines.push(`<link rel="alternate" hreflang="x-default" href="${escapeAttr(def.url)}" />`);
+  }
+  return lines.join("\n");
+}
+
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Canonical-JSON serializer + sha256 → hex. Stable across runs because
+ * keys are sorted. The output is used for `pages.content_hash` so that
+ * a Mode-2 translation can detect whether its source has changed.
+ */
+export async function computeContentHash(value: unknown): Promise<string> {
+  const canonical = JSON.stringify(value, (_key, val) => {
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      const sorted: Record<string, unknown> = {};
+      for (const k of Object.keys(val).sort()) sorted[k] = (val as Record<string, unknown>)[k];
+      return sorted;
+    }
+    return val;
+  });
+  const digest = await crypto.subtle.digest("SHA-256", TEXT_ENCODER.encode(canonical));
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export interface LocaleLintWarning {
+  code: string;
+  message: string;
+}
+
+/**
+ * Cross-row config sanity checks. Run at:
+ *   - propose-time (warnings stored on the proposal preview)
+ *   - render-time (no fail-loudly per CLAUDE.md §2 since the renderer
+ *     can still emit; surfaced in admin UI as banners)
+ */
+export function lintLocaleConfig(
+  locales: ReadonlyArray<LocaleConfig>,
+  advancedUrlRouting: boolean,
+): LocaleLintWarning[] {
+  const warnings: LocaleLintWarning[] = [];
+  const usingAdvanced = locales.some(
+    (l) => l.urlStrategy === "subdomain" || l.urlStrategy === "domain",
+  );
+  if (usingAdvanced && !advancedUrlRouting) {
+    warnings.push({
+      code: "advanced-routing-disabled",
+      message:
+        "one or more locales use 'subdomain' or 'domain' strategy but Advanced URL Routing is disabled — enable it under /security/locales",
+    });
+  }
+  for (const l of locales) {
+    if ((l.urlStrategy === "subdomain" || l.urlStrategy === "domain") && !l.urlHost) {
+      warnings.push({
+        code: "missing-url-host",
+        message: `locale '${l.code}' uses url_strategy='${l.urlStrategy}' without url_host`,
+      });
+    }
+  }
+  // Default-locale 'none' alongside subdirectory siblings is a common
+  // mixed config; surface it so users know the default's URL stays bare
+  // while siblings get prefixed.
+  const def = locales.find((l) => l.isDefault);
+  const subdirSiblings = locales.filter((l) => !l.isDefault && l.urlStrategy === "subdirectory");
+  if (def && def.urlStrategy === "none" && subdirSiblings.length > 0) {
+    warnings.push({
+      code: "mixed-default-none-subdir",
+      message: `default locale '${def.code}' uses 'none' while ${subdirSiblings
+        .map((l) => l.code)
+        .join(
+          ", ",
+        )} use 'subdirectory' — this is valid but unusual; verify hreflang renders correctly`,
+    });
+  }
+  return warnings;
+}

package/src/index.test.ts

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { PROJECT_NAME } from "./index.js";
+
+describe("shared scaffold", () => {
+  it("exports the project name", () => {
+    expect(PROJECT_NAME).toBe("caelo-cms");
+  });
+});