create-ailk 0.30.0 → 0.32.0

package/dist/mdx-braces.js

@@ -0,0 +1,285 @@
+/**
+ * Bare `{…}` braces on mdx-body pages (#10773, spec
+ * docs/specs/10773-update-never-refreshes-0-19-spec.md D3, D4).
+ *
+ * MDX reads every `{` in body text as the start of a JavaScript expression.
+ * Under the renderer's `next-mdx-remote` defaults (`blockJS`), an expression
+ * that does not parse fails the page, and one that parses is deleted — so on
+ * an mdx-body page every `{` in text other than a `{/* … *\/}` comment is a
+ * defect. This module is the one lexical rule for that brace:
+ *
+ * - `findBareBraces` names every bare brace in a body, by offset, line and
+ *   column, in one left-to-right pass;
+ * - `escapeBareBraces` inserts one `\` before each, and keeps the result only
+ *   when the site's own MDX parser reads it with no expression left but
+ *   comments — the lexer proposes, the parser disposes.
+ *
+ * Used by `create-ailk update` and, through a byte-identical copy in the
+ * scaffold's `tools/`, by `pnpm mdx-body:check`. Pure: no filesystem and no
+ * imports. It must never contain a double open brace, which the scaffold copy
+ * substitutes as a marker.
+ */
+const ESM_RE = /^(?:import|export)[ {*]/;
+// MDX has no indented code, so a fence opens at any indentation — and inside
+// a list item or a blockquote, after its markers.
+const FENCE_RE = /^[ \t]*(?:(?:>|[-*+]|\d{1,9}[.)])[ \t]*)*(`{3,}|~{3,})/;
+const COMMENT_CLOSE_RE = /\*\/\s*\}/g;
+const WHITESPACE_RE = /\s/;
+const TAG_START_RE = /[A-Za-z/>]/;
+const isBlank = (line) => line.trim() === "";
+/**
+ * Every bare `{` in an MDX body. Skips, in this order of precedence: fenced
+ * code, ESM blocks, backslash escapes, inline code, JSX tags (attribute
+ * expressions included) and `{/* … *\/}` comments. Linear in the body.
+ */
+export function findBareBraces(body) {
+    const found = [];
+    const lineEnd = (from) => {
+        const end = body.indexOf("\n", from);
+        return end === -1 ? body.length : end;
+    };
+    // A code span or a tag never crosses a blank line: true at a `\n` that ends
+    // the body or starts a blank line.
+    const paragraphBreak = (at) => {
+        let j = at + 1;
+        while (body[j] === " " || body[j] === "\t" || body[j] === "\r")
+            j += 1;
+        return j >= body.length || body[j] === "\n";
+    };
+    // Memo so a failed search is never repeated over the same text.
+    const spanFailedUntil = new Map();
+    let tagFailedUntil = -1;
+    let commentClose;
+    let i = 0;
+    while (i < body.length) {
+        if (i === 0 || body[i - 1] === "\n") {
+            const end = lineEnd(i);
+            const line = body.slice(i, end);
+            const fence = FENCE_RE.exec(line)?.[1];
+            if (fence !== undefined) {
+                // Skip to after the closing fence line, or to the end of the body.
+                let at = end;
+                while (at < body.length) {
+                    const next = lineEnd(at + 1);
+                    const candidate = body.slice(at + 1, next);
+                    const run = FENCE_RE.exec(candidate);
+                    at = next;
+                    if (run !== null &&
+                        run[1][0] === fence[0] &&
+                        run[1].length >= fence.length &&
+                        candidate.slice(run[0].length).trim() === "") {
+                        break;
+                    }
+                }
+                i = at + 1;
+                continue;
+            }
+            if (ESM_RE.test(line)) {
+                let at = end;
+                while (at < body.length) {
+                    const next = lineEnd(at + 1);
+                    if (isBlank(body.slice(at + 1, next)))
+                        break;
+                    at = next;
+                }
+                i = at + 1;
+                continue;
+            }
+        }
+        const char = body[i];
+        if (char === "\\") {
+            // A backslash before a line break is a hard break; the next line is read as a line.
+            i += body[i + 1] === "\n" ? 1 : 2;
+            continue;
+        }
+        if (char === "`") {
+            let run = 1;
+            while (body[i + run] === "`")
+                run += 1;
+            const close = spanFailedUntil.get(run) ?? -1;
+            let closed = -1;
+            if (close < i) {
+                let at = i + run;
+                for (; at < body.length; at += 1) {
+                    if (body[at] === "\n" && (paragraphBreak(at) || FENCE_RE.test(body.slice(at + 1, lineEnd(at + 1)))))
+                        break;
+                    if (body[at] !== "`")
+                        continue;
+                    let length = 1;
+                    while (body[at + length] === "`")
+                        length += 1;
+                    if (length === run) {
+                        closed = at + length;
+                        break;
+                    }
+                    at += length - 1;
+                }
+                if (closed === -1)
+                    spanFailedUntil.set(run, at);
+            }
+            i = closed === -1 ? i + run : closed;
+            continue;
+        }
+        if (char === "<" && TAG_START_RE.test(body[i + 1] ?? "") && i >= tagFailedUntil) {
+            let depth = 0;
+            let quote = "";
+            let closed = -1;
+            let at = i + 1;
+            for (; at < body.length; at += 1) {
+                const c = body[at];
+                if (c === "\n" && paragraphBreak(at))
+                    break;
+                if (quote !== "") {
+                    if (c === quote)
+                        quote = "";
+                }
+                else if (depth > 0) {
+                    if (c === "{")
+                        depth += 1;
+                    else if (c === "}")
+                        depth -= 1;
+                }
+                else if (c === '"' || c === "'") {
+                    quote = c;
+                }
+                else if (c === "{") {
+                    depth = 1;
+                }
+                else if (c === ">") {
+                    closed = at + 1;
+                    break;
+                }
+            }
+            if (closed !== -1) {
+                i = closed;
+                continue;
+            }
+            // An unclosed tag already breaks the page; no later `<` before `at` is
+            // read as a tag, which keeps the scan linear.
+            tagFailedUntil = at;
+            i += 1;
+            continue;
+        }
+        if (char === "{") {
+            let next = i + 1;
+            while (next < body.length && WHITESPACE_RE.test(body[next]))
+                next += 1;
+            if (body[next] === "/" && body[next + 1] === "*") {
+                if (commentClose === undefined || commentClose.from > i || (commentClose.at !== -1 && commentClose.at < i)) {
+                    COMMENT_CLOSE_RE.lastIndex = next + 2;
+                    const match = COMMENT_CLOSE_RE.exec(body);
+                    commentClose = { from: i, at: match === null ? -1 : match.index + match[0].length };
+                }
+                if (commentClose.at !== -1) {
+                    i = commentClose.at;
+                    continue;
+                }
+            }
+            found.push({ offset: i, kind: body[next] === "/" ? "comment-like" : "placeholder" });
+        }
+        i += 1;
+    }
+    // Offsets to 1-based line and column, in one pass.
+    const braces = [];
+    let line = 1;
+    let lineStart = 0;
+    let scanned = 0;
+    for (const brace of found) {
+        for (; scanned < brace.offset; scanned += 1) {
+            if (body[scanned] === "\n") {
+                line += 1;
+                lineStart = scanned + 1;
+            }
+        }
+        braces.push({ ...brace, line, column: brace.offset - lineStart + 1 });
+    }
+    return braces;
+}
+const COMMENT_VALUE_RE = /^\s*\/\*[\s\S]*\*\/\s*$/;
+/** The first expression node left in the tree that is not a comment. */
+export function firstExpression(node) {
+    if ((node.type === "mdxFlowExpression" || node.type === "mdxTextExpression") &&
+        !(typeof node.value === "string" && COMMENT_VALUE_RE.test(node.value))) {
+        return node;
+    }
+    for (const child of node.children ?? []) {
+        const hit = firstExpression(child);
+        if (hit !== undefined)
+            return hit;
+    }
+    return undefined;
+}
+/** The first `code` or `inlineCode` node whose span holds one of `offsets` (sorted). */
+function codeNodeHolding(node, offsets) {
+    if (node.type === "code" || node.type === "inlineCode") {
+        const start = node.position?.start?.offset;
+        const end = node.position?.end?.offset;
+        if (typeof start === "number" && typeof end === "number") {
+            let lo = 0;
+            let hi = offsets.length;
+            while (lo < hi) {
+                const mid = (lo + hi) >> 1;
+                if (offsets[mid] < start)
+                    lo = mid + 1;
+                else
+                    hi = mid;
+            }
+            if (lo < offsets.length && offsets[lo] < end)
+                return node;
+        }
+    }
+    for (const child of node.children ?? []) {
+        const hit = codeNodeHolding(child, offsets);
+        if (hit !== undefined)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * Escape every bare brace in `body`, all or nothing: `clean` when there is
+ * none (`parse` is not called), `refused` when a brace is a mangled comment,
+ * the escaped text does not parse, or an expression the escape did not reach
+ * remains; otherwise `escaped`.
+ */
+export function escapeBareBraces(body, parse) {
+    const braces = findBareBraces(body);
+    if (braces.length === 0)
+        return { kind: "clean" };
+    const mangled = braces.find((brace) => brace.kind === "comment-like");
+    if (mangled !== undefined) {
+        return { kind: "refused", reason: `{/ at line ${mangled.line} is not a {/* … */} comment` };
+    }
+    const parts = [];
+    let from = 0;
+    for (const { offset } of braces) {
+        parts.push(body.slice(from, offset), "\\");
+        from = offset;
+    }
+    parts.push(body.slice(from));
+    const text = parts.join("");
+    let tree;
+    try {
+        tree = parse(text);
+    }
+    catch (err) {
+        const { line, reason } = (err ?? {});
+        const why = typeof reason === "string" ? reason : err instanceof Error ? err.message : String(err);
+        return { kind: "refused", reason: `line ${typeof line === "number" ? line : "?"}: ${why}` };
+    }
+    const escapes = braces.map((brace, k) => brace.offset + k);
+    const inCode = codeNodeHolding(tree, escapes);
+    if (inCode !== undefined) {
+        return {
+            kind: "refused",
+            reason: `a brace at line ${inCode.position?.start?.line ?? "?"} is inside code the lexer did not see`,
+        };
+    }
+    const left = firstExpression(tree);
+    if (left !== undefined) {
+        return {
+            kind: "refused",
+            reason: `an expression at line ${left.position?.start?.line ?? "?"} the escape did not reach`,
+        };
+    }
+    return { kind: "escaped", text, count: braces.length };
+}

package/dist/migrate-content.d.ts

@@ -1,3 +1,4 @@
+import { type LanguageImportResult } from "./language-import.js";
 import { type ImportMdxResult, type MdxAdapterModule } from "./lib/import-mdx.js";
 /** A refusal the CLI exits 2 on, thrown before any request is sent. */
 export declare class MigrateContentRefusedError extends Error {
@@ -27,12 +28,15 @@ export interface MigrateContentOptions {
 /**
  * A fetch that sends `GET`s through `inner` and never sends a write: a `POST`
  * is answered `201` and a `PATCH` `200` locally, with the one member of a
- * write's answer `importMdx` reads (`data.locale`). Any other method throws.
+ * write's answer `importMdx` reads (`data.locale`), and the structure write's
+ * `PUT` (#10534) `200` as a layout unchanged (`data.written: false`). Any
+ * other method throws.
  */
 export declare function readOnlyFetch(inner: typeof globalThis.fetch, locale: string): typeof globalThis.fetch;
 export declare function migrateContent(opts: MigrateContentOptions): Promise<{
     result: ImportMdxResult;
     exitCode: 0 | 1;
+    language?: LanguageImportResult;
 }>;
 export interface MigrateContentArgs {
     target: string | undefined;
@@ -41,5 +45,5 @@ export interface MigrateContentArgs {
     workspaceId: string | undefined;
     help: boolean;
 }
-export declare const MIGRATE_CONTENT_HELP = "create-ailk migrate-content \u2014 import an existing site's pages into its workspace.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk migrate-content [<dir>] [--apply] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --apply                  Write the pages. Without it the command reads the\n                           workspace, prints what it would do, and writes\n                           nothing.\n  --api-url <origin>       The API origin that holds the workspace \u2014 on a\n                           spoke, its hub's. Else AILK_API_URL. https: only\n                           (http: on localhost or 127.0.0.1).\n  --workspace <wksp_id>    The workspace the pages are written to. Else\n                           AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nEach content/en/<Type>/<slug>.mdx page (and each legacy\ncontent/<Type>/<slug>.mdx) is written to the workspace as a draft through\nthe API's content routes, with the agent key, which is read from\nAILK_AGENT_KEY only and needs the content-edit grant. Nothing is published,\nso the live site does not change. The site needs no .ailk-site-manifest.json\nand may be a spoke; its dependencies must be installed.\n\nA dry run prints create, update, unchanged, skipped or failed per page. It\ncannot see a write the API would refuse at --apply (a conflict or a server\nerror), and a page whose content fails its page type is planned and saved\nwith errors the editor shows, not failed. --apply prints created, updated,\nunchanged, skipped or failed per page, so a re-run is safe. Exit 0 when no\npage failed, 1 when any did, 2 on a refusal (nothing is sent).\n";
+export declare const MIGRATE_CONTENT_HELP = "create-ailk migrate-content \u2014 import an existing site's pages into its workspace.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk migrate-content [<dir>] [--apply] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --apply                  Write the pages. Without it the command reads the\n                           workspace, prints what it would do, and writes\n                           nothing.\n  --api-url <origin>       The API origin that holds the workspace \u2014 on a\n                           spoke, its hub's. Else AILK_API_URL. https: only\n                           (http: on localhost or 127.0.0.1).\n  --workspace <wksp_id>    The workspace the pages are written to. Else\n                           AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nEach content/en/<Type>/<slug>.mdx page (and each legacy\ncontent/<Type>/<slug>.mdx) is written to the workspace as a draft through\nthe API's content routes, with the agent key, which is read from\nAILK_AGENT_KEY only and needs the content-edit grant. Nothing is published,\nso the live site does not change. The site needs no .ailk-site-manifest.json\nand may be a spoke; its dependencies must be installed. A page whose\nfrontmatter carries sections is converted: its words are written to the\npage's Markdown and its sections to its layout.\n\nEach FAQ item and glossary-index term becomes one Language item of its kind,\nset Live when the run creates it, and its section pins the items in the\norder the file lists them. A question on several pages is one item, with\nthe FAQ page's words (the glossary page's, for a term). Lines prefixed\nlanguage: report each item, and each page the database read will not show\nas its file does. An API with no Language collection leaves them inline.\n\nWhen the site has apps/web/content, each blog post and docs page in it is\nwritten too: apps/web/content/en/blog/<slug>.mdx (or <slug>/index.mdx) as a\nBlogPosting, or one series down, blog/<series>/<post>.mdx, as a BlogPosting\nwhose parent is the series; the same under docs as a DocsDetail, and each\ndirectory's own index.mdx as its BlogList or DocsList index. A file the walk\nskips is listed with the rule it failed. Their lines are prefixed\neditorial: \u2014 each outcome's root is content or editorial.\n\nA dry run prints create, update, unchanged, skipped or failed per page. It\ncannot see a write the API would refuse at --apply (a conflict or a server\nerror), nor a layout change on a page whose words did not change, and a\npage whose content fails its page type is planned and saved\nwith errors the editor shows, not failed. --apply prints created, updated,\nunchanged, skipped or failed per page, so a re-run is safe. Exit 0 when no\npage failed, 1 when any did, 2 on a refusal (nothing is sent).\n";
 export declare function parseMigrateContentArgs(argv: string[]): MigrateContentArgs;

package/dist/migrate-content.js

@@ -3,15 +3,16 @@
  * [--workspace <id>]` — import an existing site's MDX pages into its
  * workspace (#10207).
  *
- * The same import as `seed-workspace` — `importMdx` over `<dir>/content` with
+ * The same import as `seed-workspace` — `importMdx` over `<dir>/content`, and
+ * the docs-blog tree `<dir>/apps/web/content` when it exists (#10701), with
  * the site's own installed adapter — for the site `seed-workspace` refuses: one
  * with no `.ailk-site-manifest.json`, or a spoke, whose workspace lives on its
  * hub (D1). No manifest and no topology is read; the operator names the API
  * origin and the workspace, which is all the topology would decide.
  *
  * A dry run is the default (D3): the importer runs over `readOnlyFetch`, which
- * passes each `GET` through and answers a `POST` or `PATCH` locally without
- * sending it, so the plan — create · update · unchanged · skipped · failed — is
+ * passes each `GET` through and answers a `POST`, `PATCH` or `PUT` locally
+ * without sending it, so the plan — create · update · unchanged · skipped · failed — is
  * decided by the importer itself against the live workspace, and no write can
  * leave the process. `--apply` writes; a second `--apply` reports every page
  * `unchanged`.
@@ -27,7 +28,8 @@
  */
 import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { formatImportMdxReport, importMdx, loadSiteMdxAdapter, } from "./lib/import-mdx.js";
+import { languageLines, languageOffLine, withLanguage, } from "./language-import.js";
+import { formatImportMdxReport, importMdx, isDirectory, loadSiteMdxAdapter, outcomePath, } from "./lib/import-mdx.js";
 import { ParseError } from "./parse-args.js";
 import { AGENT_KEY_ENV_VAR, WORKSPACE_ID_ENV_VAR } from "./seed-workspace.js";
 import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, } from "./topology.js";
@@ -53,17 +55,20 @@ function given(value) {
 /**
  * A fetch that sends `GET`s through `inner` and never sends a write: a `POST`
  * is answered `201` and a `PATCH` `200` locally, with the one member of a
- * write's answer `importMdx` reads (`data.locale`). Any other method throws.
+ * write's answer `importMdx` reads (`data.locale`), and the structure write's
+ * `PUT` (#10534) `200` as a layout unchanged (`data.written: false`). Any
+ * other method throws.
  */
 export function readOnlyFetch(inner, locale) {
     return (async (input, init) => {
         const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
         if (method === "GET")
             return inner(input, init);
-        if (method !== "POST" && method !== "PATCH") {
+        if (method !== "POST" && method !== "PATCH" && method !== "PUT") {
             throw new Error(`a dry run sends no ${method} request`);
         }
-        return new Response(JSON.stringify({ ok: true, data: { locale } }), {
+        const data = method === "PUT" ? { locale, written: false } : { locale };
+        return new Response(JSON.stringify({ ok: true, data }), {
             status: method === "POST" ? 201 : 200,
             headers: { "content-type": "application/json" },
         });
@@ -81,8 +86,8 @@ const PLAN_VERB = {
 function planLine(outcome) {
     const verb = PLAN_VERB[outcome.result];
     return "reason" in outcome
-        ? `${outcome.path}: ${verb} — ${outcome.reason}`
-        : `${outcome.path}: ${verb}`;
+        ? `${outcomePath(outcome)}: ${verb} — ${outcome.reason}`
+        : `${outcomePath(outcome)}: ${verb}`;
 }
 // ── The command (D1–D4) ─────────────────────────────────────────────────────
 export async function migrateContent(opts) {
@@ -119,14 +124,29 @@ export async function migrateContent(opts) {
         : `Planning ${opts.targetDir} against ${at} Nothing is written without --apply.`);
     const adapters = opts.adapters ?? (await loadSiteMdxAdapter(targetDir));
     const fetch = opts.fetch ?? globalThis.fetch;
+    const transport = apply ? fetch : readOnlyFetch(fetch, LOCALE);
+    // #10735 D1 — the Language pass wraps the importer's read.
+    const pass = withLanguage(adapters, {
+        apiOrigin: origin,
+        workspaceId,
+        apiKey,
+        locale: LOCALE,
+        fetch: transport,
+        apply,
+        ...(opts.sleep !== undefined && { sleep: opts.sleep }),
+        onLine,
+    });
+    // #10701 D7 — the docs-blog tree, when the site has one.
+    const editorialRoot = join(targetDir, "apps", "web", "content");
     const result = await importMdx({
         contentRoot: join(targetDir, "content"),
-        adapters,
+        ...(isDirectory(editorialRoot) && { editorialRoot }),
+        adapters: pass.adapters,
         apiOrigin: origin,
         workspaceId,
         apiKey,
         defaultLocale: LOCALE,
-        fetch: apply ? fetch : readOnlyFetch(fetch, LOCALE),
+        fetch: transport,
         ...(opts.sleep !== undefined && { sleep: opts.sleep }),
         // A dry run's importer lines say `created`/`updated`, which nothing was.
         ...(apply && { onLine }),
@@ -148,7 +168,17 @@ export async function migrateContent(opts) {
             onLine(`${failed} page(s) would fail. Fix them before --apply.`);
         }
     }
-    return { result, exitCode: failed > 0 ? 1 : 0 };
+    // #10735 D7 — the Language lines come last.
+    const { result: language, off } = pass.report();
+    if (off !== undefined)
+        onLine(languageOffLine(off));
+    if (language !== undefined)
+        languageLines(language, apply).forEach(onLine);
+    return {
+        result,
+        exitCode: failed > 0 ? 1 : 0,
+        ...(language !== undefined && { language }),
+    };
 }
 export const MIGRATE_CONTENT_HELP = `create-ailk migrate-content — import an existing site's pages into its workspace.
 
@@ -174,11 +204,29 @@ content/<Type>/<slug>.mdx) is written to the workspace as a draft through
 the API's content routes, with the agent key, which is read from
 AILK_AGENT_KEY only and needs the content-edit grant. Nothing is published,
 so the live site does not change. The site needs no .ailk-site-manifest.json
-and may be a spoke; its dependencies must be installed.
+and may be a spoke; its dependencies must be installed. A page whose
+frontmatter carries sections is converted: its words are written to the
+page's Markdown and its sections to its layout.
+
+Each FAQ item and glossary-index term becomes one Language item of its kind,
+set Live when the run creates it, and its section pins the items in the
+order the file lists them. A question on several pages is one item, with
+the FAQ page's words (the glossary page's, for a term). Lines prefixed
+language: report each item, and each page the database read will not show
+as its file does. An API with no Language collection leaves them inline.
+
+When the site has apps/web/content, each blog post and docs page in it is
+written too: apps/web/content/en/blog/<slug>.mdx (or <slug>/index.mdx) as a
+BlogPosting, or one series down, blog/<series>/<post>.mdx, as a BlogPosting
+whose parent is the series; the same under docs as a DocsDetail, and each
+directory's own index.mdx as its BlogList or DocsList index. A file the walk
+skips is listed with the rule it failed. Their lines are prefixed
+editorial: — each outcome's root is content or editorial.
 
 A dry run prints create, update, unchanged, skipped or failed per page. It
 cannot see a write the API would refuse at --apply (a conflict or a server
-error), and a page whose content fails its page type is planned and saved
+error), nor a layout change on a page whose words did not change, and a
+page whose content fails its page type is planned and saved
 with errors the editor shows, not failed. --apply prints created, updated,
 unchanged, skipped or failed per page, so a re-run is safe. Exit 0 when no
 page failed, 1 when any did, 2 on a refusal (nothing is sent).

package/dist/programmatic.js

@@ -46,7 +46,7 @@ import { SITE_FONTS_PATH, renderSiteFonts } from "./site-fonts.js";
 import { planSiteManifest } from "./site-manifest.js";
 import { SITE_ROSTER_PATH, planHomeRecord, planSiteManifestDesign, readSiteRoster, withMeetPlaceholderSeeds, } from "./site-roster.js";
 import { SPOKE_CHECKOUT_TEMPLATE_PATHS, dropSpokeCheckoutDependency, spokeCheckoutSite, spokeEnvRowOptions, writeSpokeCheckoutSlice, } from "./spoke-checkout.js";
-import { GATEABLE_SURFACES, MODULE_SURFACES, NAV_CONFIG_PATH, excludedRoutePaths, isUnservedSurfaceContent, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
+import { GATEABLE_SURFACES, NAV_CONFIG_PATH, excludedRoutePaths, isUnservedSurfaceContent, renderNavConfig, resolveSurfaces, surfacesNamedByRoutes, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
 import { BASE_LAYER_DIR, SHAPE_STARTERS, isOwnTree, shippedManifestPath, TEMPLATE_MANIFESTS, TemplateError, mergeRoster, resolveTemplate, resolveTemplateLineage, rosterDeclares, templateDelivery, templateTreeDir, } from "./template-manifest.js";
 import { TEMPLATE_RECORD_PATH, isRecordable, planTemplateRecord, serializeTemplateRecord, sha256Hex, } from "./template-record.js";
@@ -1075,13 +1075,7 @@ function pruneUnrosteredSeeds(targetDir, roster, surfaces, ownership) {
  * path segment is the surface's top-level route directory.
  */
 function rosterSurfaces(template) {
-    const routeRoot = "apps/web/app/[locale]";
-    const moduleOwned = new Set(Object.values(MODULE_SURFACES).flat());
-    const topSegments = new Set(mergeRoster(template, template.requires)
-        .map((row) => row.route.split("/").filter(Boolean)[0])
-        .filter((segment) => segment !== undefined));
-    return GATEABLE_SURFACES.filter((surface) => !moduleOwned.has(surface.id) &&
-        surface.routes.some((dir) => topSegments.has(dir.slice(routeRoot.length + 1)))).map((surface) => surface.id);
+    return surfacesNamedByRoutes(mergeRoster(template, template.requires).map((row) => row.route));
 }
 // Re-exported so a consumer of the async `scaffold()` above can type its own
 // wrapper (e.g. the MCP scaffold-site tool) without reaching into `lib/`.

package/dist/seed-workspace.d.ts

@@ -4,6 +4,8 @@ import { type Topology } from "./topology.js";
 export declare const AGENT_KEY_ENV_VAR = "AILK_AGENT_KEY";
 /** The environment variable the workspace id is read from when no flag names one. */
 export declare const WORKSPACE_ID_ENV_VAR = "AILK_WORKSPACE_ID";
+/** The environment variable each app chooses its content source by (#10659). */
+export declare const CONTENT_ADAPTER_ENV_VAR = "CONTENT_ADAPTER";
 /** A refusal the CLI exits 2 on, thrown before any request is sent. */
 export declare class SeedWorkspaceRefusedError extends Error {
     readonly exitCode = 2;
@@ -67,5 +69,5 @@ export interface SeedWorkspaceArgs {
     workspaceId: string | undefined;
     help: boolean;
 }
-export declare const SEED_WORKSPACE_HELP = "create-ailk seed-workspace \u2014 import a starter's pages into its workspace.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --api-url <origin>       The site's API origin. Else AILK_API_URL. https:\n                           only (http: on localhost or 127.0.0.1).\n  --workspace <wksp_id>    The workspace the pages are written to. Else\n                           AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nEach content/en/<Type>/<slug>.mdx page is written to the workspace as a\ndraft through the API's content routes, with the agent key, which is read\nfrom AILK_AGENT_KEY only and needs the content-edit grant. Each page prints\ncreated, updated, unchanged, skipped or failed, so a re-run is safe. The\nsite's dependencies must be installed. Exit 0 when every page was seeded, 1\nwhen any failed, 2 on a refusal (nothing is sent).\n";
+export declare const SEED_WORKSPACE_HELP = "create-ailk seed-workspace \u2014 import a starter's pages into its workspace.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --api-url <origin>       The site's API origin. Else AILK_API_URL. https:\n                           only (http: on localhost or 127.0.0.1).\n  --workspace <wksp_id>    The workspace the pages are written to. Else\n                           AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nEach content/en/<Type>/<slug>.mdx page is written to the workspace, and set\nLive when it has no Live version, through the API's content routes, with the\nagent key, which is read from AILK_AGENT_KEY only and needs the content-edit\nand content-publish grants. Each page prints created, updated, unchanged,\nskipped or failed, so a re-run is safe. When every page is Live, the site\nswitches apps/web and apps/api to CONTENT_ADAPTER=database, keeping a value\neither already sets. The site's dependencies must be installed. Exit 0 when\nevery page was seeded, 1 when any failed, 2 on a refusal (nothing is sent).\n";
 export declare function parseSeedWorkspaceArgs(argv: string[]): SeedWorkspaceArgs;

package/dist/seed-workspace.js

@@ -6,7 +6,10 @@
  * A fresh scaffold's `content/` tree is exactly its roster (spec §1), so the
  * seed is `importMdx` over `<dir>/content` with the site's own installed
  * adapter (D1): one `text/page` Artifact per page, and a re-run writes
- * nothing and reports every page `unchanged`.
+ * nothing and reports every page `unchanged`. Each page with no Live version
+ * is set Live, and when every page is Live both apps that choose a content
+ * source are switched to `CONTENT_ADAPTER=database`, each keeping a value it
+ * already sets (#10659 D3); anything less leaves the site on `content/`.
  *
  * The API origin comes from `--api-url`, else `AILK_API_URL`; the workspace
  * id from `--workspace`, else `AILK_WORKSPACE_ID`; the agent key from
@@ -18,12 +21,14 @@
  *
  * The scaffold-time step (D3, D6) runs only on a hub with an Admin
  * (`workspace` or `multi-tenant`), after `--install`, with all three
- * variables set; otherwise it prints why and the command that seeds later,
- * or nothing on a site with no Admin. It never fails the scaffold.
+ * variables set; otherwise it prints why and the command that seeds and
+ * switches later, or nothing on a site with no Admin. It never fails the
+ * scaffold.
  *
  * Pure module: no `import.meta.url`, so jest can import it directly. `fetch`,
  * `sleep`, `env` and the adapter are injectable. Spec:
- * docs/specs/10204-seed-the-starter-s-roster-spec.md.
+ * docs/specs/10204-seed-the-starter-s-roster-spec.md; the publish and the
+ * switch docs/specs/10659-a-licensed-hub-scaffold-starts-spec.md.
  */
 import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
@@ -31,11 +36,13 @@ import { AddModuleRefusedError } from "./add-module-core.js";
 import { ImportMdxRefusedError, formatImportMdxReport, importMdx, loadSiteMdxAdapter, } from "./lib/import-mdx.js";
 import { ParseError } from "./parse-args.js";
 import { readSiteRoster } from "./site-roster.js";
-import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, readSiteTopology, } from "./topology.js";
+import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, readSiteTopology, writeApiEnv, writeWebEnv, } from "./topology.js";
 /** The environment variable the agent key is read from — and nowhere else. */
 export const AGENT_KEY_ENV_VAR = "AILK_AGENT_KEY";
 /** The environment variable the workspace id is read from when no flag names one. */
 export const WORKSPACE_ID_ENV_VAR = "AILK_WORKSPACE_ID";
+/** The environment variable each app chooses its content source by (#10659). */
+export const CONTENT_ADAPTER_ENV_VAR = "CONTENT_ADAPTER";
 /** A refusal the CLI exits 2 on, thrown before any request is sent. */
 export class SeedWorkspaceRefusedError extends Error {
     exitCode = 2;
@@ -83,7 +90,7 @@ export async function seedWorkspace(opts) {
     }
     const apiKey = given(env[AGENT_KEY_ENV_VAR]);
     if (apiKey === undefined) {
-        refuse(`set ${AGENT_KEY_ENV_VAR} to an agent key with the content-edit grant. It is read from the environment only — never a flag or a file.`);
+        refuse(`set ${AGENT_KEY_ENV_VAR} to an agent key with the content-edit and content-publish grants. It is read from the environment only — never a flag or a file.`);
     }
     const workspaceId = given(opts.workspaceId) ?? given(env[WORKSPACE_ID_ENV_VAR]);
     if (workspaceId === undefined) {
@@ -115,12 +122,30 @@ export async function seedWorkspace(opts) {
         ...(opts.fetch !== undefined && { fetch: opts.fetch }),
         ...(opts.sleep !== undefined && { sleep: opts.sleep }),
         onLine,
+        publish: true,
     });
     // The report's count line alone: no page rows.
     onLine(formatImportMdxReport({ pages: [], counts: result.counts }).trimEnd());
-    const { failed } = result.counts;
-    if (failed > 0) {
-        onLine(`${failed} page(s) were not seeded. Fix them and re-run: create-ailk seed-workspace ${opts.targetDir}`);
+    const { created, updated, unchanged, failed } = result.counts;
+    const live = result.live ?? 0;
+    onLine(`Live: ${live} page(s), ${result.published ?? 0} published now.`);
+    // #10659 D3 — both apps switch only when every page is in and Live.
+    if (failed === 0 && live >= 1 && live === created + updated + unchanged) {
+        for (const [app, file, write] of [
+            ["apps/web", "apps/web/.env.local", writeWebEnv],
+            ["apps/api", "apps/api/.env", writeApiEnv],
+        ]) {
+            onLine(write(targetDir, CONTENT_ADAPTER_ENV_VAR, () => "database")
+                ? `Content source: the database for ${app} (${CONTENT_ADAPTER_ENV_VAR}=database in ${file}).`
+                : `Content source: ${app} already sets ${CONTENT_ADAPTER_ENV_VAR}, which was kept.`);
+        }
+        onLine("  The API serves these pages from the database it was seeded through (DATABASE_URL), for the workspace its site resolves.");
+    }
+    else {
+        if (failed > 0) {
+            onLine(`${failed} page(s) were not seeded. Fix them and re-run: create-ailk seed-workspace ${opts.targetDir}`);
+        }
+        onLine("Content source: content/ (unchanged) until every page is seeded and Live.");
     }
     return { result, exitCode: failed > 0 ? 1 : 0 };
 }
@@ -166,9 +191,10 @@ export async function runScaffoldSeed(opts) {
     const plan = scaffoldSeedPlan(opts);
     if (plan.kind === "not-applicable")
         return;
+    const later = `  To seed it and switch to the database later: ${AGENT_KEY_ENV_VAR}=<key> create-ailk seed-workspace ${opts.targetDir} --api-url <origin> --workspace <wksp_id>`;
     if (plan.kind === "skip") {
         opts.onLine(plan.reason);
-        opts.onLine(`  To seed it later: ${AGENT_KEY_ENV_VAR}=<key> create-ailk seed-workspace ${opts.targetDir} --api-url <origin> --workspace <wksp_id>`);
+        opts.onLine(later);
         return;
     }
     opts.onLine("Seeding the workspace:");
@@ -188,6 +214,7 @@ export async function runScaffoldSeed(opts) {
             throw err;
         }
         opts.onLine(err.message);
+        opts.onLine(later);
     }
 }
 export const SEED_WORKSPACE_HELP = `create-ailk seed-workspace — import a starter's pages into its workspace.
@@ -205,12 +232,14 @@ Options:
                            AILK_WORKSPACE_ID.
   -h, --help               Show this help.
 
-Each content/en/<Type>/<slug>.mdx page is written to the workspace as a
-draft through the API's content routes, with the agent key, which is read
-from AILK_AGENT_KEY only and needs the content-edit grant. Each page prints
-created, updated, unchanged, skipped or failed, so a re-run is safe. The
-site's dependencies must be installed. Exit 0 when every page was seeded, 1
-when any failed, 2 on a refusal (nothing is sent).
+Each content/en/<Type>/<slug>.mdx page is written to the workspace, and set
+Live when it has no Live version, through the API's content routes, with the
+agent key, which is read from AILK_AGENT_KEY only and needs the content-edit
+and content-publish grants. Each page prints created, updated, unchanged,
+skipped or failed, so a re-run is safe. When every page is Live, the site
+switches apps/web and apps/api to CONTENT_ADAPTER=database, keeping a value
+either already sets. The site's dependencies must be installed. Exit 0 when
+every page was seeded, 1 when any failed, 2 on a refusal (nothing is sent).
 `;
 export function parseSeedWorkspaceArgs(argv) {
     let parsed;