create-ailk 0.29.1 → 0.31.0

package/dist/language-import.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The Language pass of `migrate-content` (#10735, spec
+ * docs/specs/10735-import-migration-inline-faq-items-spec.md D1–D7): every
+ * inline FAQ item and glossary-index term the importer reads becomes, or
+ * reuses, one Language item of its kind (#10733), and each faq /
+ * glossary-index section is written as pins in source order.
+ *
+ * `withLanguage` wraps the site's adapter module: the wrapped
+ * `getPageSource` reads the page, makes sure every item on it exists (created
+ * Live when this run creates it), and returns the frontmatter with those
+ * sections rewritten as `faq:<slug>` / `term:<slug>` pins. The importer then
+ * writes the page as it writes any other, so the pass covers exactly the
+ * pages the importer reads, and every item a page pins exists before its
+ * layout is written. An item write that fails throws, which fails that page.
+ *
+ * Nothing is sent until a page carries an item to move; the first one probes
+ * the collection (D6), and an API without it (`402`, `403`, `404`) turns the
+ * pass off for the run, so pages import inline as they did before.
+ *
+ * The key travels only as `authorization: Bearer <key>`, never across a
+ * redirect; of an API answer only a status and a `[a-z0-9_]` code reach a
+ * line, and no line carries an answer's words (SEC-7876-S1).
+ */
+import type { MdxAdapterModule } from "./lib/import-mdx.js";
+export type LanguageItemKind = "faq" | "term";
+export type LanguageItemResult = "created" | "unchanged" | "kept" | "failed";
+export interface LanguageImportOptions {
+    /** The normalized API origin. */
+    apiOrigin: string;
+    workspaceId: string;
+    apiKey: string;
+    locale: string;
+    /** The dry run's `readOnlyFetch`, or the real one with `apply`. */
+    fetch: typeof globalThis.fetch;
+    /** Whether the run writes; a dry run decides the plan without a write. */
+    apply: boolean;
+    /** The wait before a rate-limited retry. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Each rate-limit wait, as the importer prints its own. */
+    onLine?: (line: string) => void;
+}
+export interface LanguageImportResult {
+    items: {
+        kind: LanguageItemKind;
+        slug: string;
+        result: LanguageItemResult;
+        reason?: string;
+    }[];
+    counts: Record<LanguageItemResult, number>;
+    /**
+     * One per page occurrence the database read will not render as the file
+     * does. `from` is the winning page's path or `"workspace"` (the item's
+     * words differ), `"not Live"`, `"repeat"` (a key twice in one section,
+     * shown once) or `"letter"` (a term lettered otherwise at read).
+     */
+    renderChanges: {
+        kind: LanguageItemKind;
+        slug: string;
+        page: string;
+        from: string;
+    }[];
+    /** An imported item the home page's kind pull now also lists (#10734 D3); not a render change. */
+    topUps: {
+        kind: LanguageItemKind;
+        slug: string;
+        page: string;
+    }[];
+    /** An FAQ whose source carried a `kicker`, which a Language FAQ has no field for (#10750). */
+    droppedKickers: {
+        slug: string;
+        page: string;
+    }[];
+    /** A file's question displaced from a slug the workspace holds for another (D2). */
+    displaced: {
+        slug: string;
+        next: string;
+    }[];
+}
+/** The pass, and what it decided once the importer is done. */
+export interface LanguagePass {
+    adapters: MdxAdapterModule;
+    /** `off` is the probe's status when the API has no collection; `result` is absent when nothing was sent. */
+    report(): {
+        result?: LanguageImportResult;
+        off?: number;
+    };
+}
+type Words = Record<string, string>;
+/**
+ * An FAQ's slug (D2): lower-cased, diacritics stripped, each run outside
+ * `[a-z0-9]` one `-`, trimmed of `-`, cut at 64; `faq` when nothing is left.
+ */
+export declare function faqSlug(question: string): string;
+/** A term's letter as the database read derives it (`glossaryTermOf`, #10734 D4). */
+export declare function letterOf(term: string, locale: string): string;
+/**
+ * Each pinned faq / glossary-index section with `items` / `terms` set to the
+ * words of its pins found in `items` (by kind, then slug), in pin order, and
+ * no `pinned` (D9). A pin with no entry in `items` is dropped, as the read
+ * drops a pin that is missing, off or disabled.
+ */
+export declare function inlinePins(sections: readonly unknown[], items: Record<LanguageItemKind, Map<string, Words>>): unknown[];
+/** The kind a section pins, when it is a faq / glossary-index section carrying `pinned`. */
+export declare function pinnedKind(section: unknown): LanguageItemKind | undefined;
+export declare function withLanguage(adapters: MdxAdapterModule, options: LanguageImportOptions): LanguagePass;
+/** D6's one line when the API has no collection. */
+export declare function languageOffLine(status: number): string;
+/** A render change's line (D7). */
+export declare function renderChangeLine(c: LanguageImportResult["renderChanges"][number]): string;
+/** The counts line, in the dry run's verbs or `--apply`'s. */
+export declare function languageCountsLine(result: LanguageImportResult, apply: boolean): string;
+/** Every line D7 prints, in order: items, counts, render changes, top-ups, dropped kickers, displacements. */
+export declare function languageLines(result: LanguageImportResult, apply: boolean): string[];
+export {};

package/dist/language-import.js

@@ -0,0 +1,435 @@
+/** The section type that carries each kind, and the page type whose kind pull lists every Live item. */
+const SECTION_TYPE = { faq: "faq", term: "glossary-index" };
+const HOME_TYPE = { faq: "FAQPage", term: "GlossaryList" };
+const PREFIX = { faq: "faq:", term: "term:" };
+/** The answers that mean an API without the collection, or a workspace not licensed for it (D6). */
+const OFF_STATUSES = new Set([402, 403, 404]);
+/** `LANGUAGE_SLUG_PATTERN` (`@working-theory/validation`), restated: no runtime dep. */
+const ITEM_SLUG = /^[a-z0-9](?:[a-z0-9-]{0,118}[a-z0-9])?$/;
+const SAFE_CODE = /^[a-z0-9_]{1,64}$/;
+const FAQ_SLUG_MAX = 64;
+const REQUEST_TIMEOUT_MS = 15_000;
+const RATE_LIMIT_RETRIES = 3;
+const RATE_LIMIT_WAIT_MAX_S = 60;
+/**
+ * An FAQ's slug (D2): lower-cased, diacritics stripped, each run outside
+ * `[a-z0-9]` one `-`, trimmed of `-`, cut at 64; `faq` when nothing is left.
+ */
+export function faqSlug(question) {
+    const slug = question
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, FAQ_SLUG_MAX)
+        .replace(/-+$/, "");
+    return slug === "" ? "faq" : slug;
+}
+/** A term's letter as the database read derives it (`glossaryTermOf`, #10734 D4). */
+export function letterOf(term, locale) {
+    const first = Array.from(term)[0] ?? "";
+    return /\p{L}/u.test(first) ? first.toLocaleUpperCase(locale) : "#";
+}
+/**
+ * Each pinned faq / glossary-index section with `items` / `terms` set to the
+ * words of its pins found in `items` (by kind, then slug), in pin order, and
+ * no `pinned` (D9). A pin with no entry in `items` is dropped, as the read
+ * drops a pin that is missing, off or disabled.
+ */
+export function inlinePins(sections, items) {
+    return sections.map((section) => {
+        const kind = pinnedKind(section);
+        if (kind === undefined)
+            return section;
+        const { data, ...rest } = section;
+        const { pinned, items: _items, terms: _terms, ...kept } = data;
+        const entries = pinned.flatMap((pin) => {
+            if (typeof pin !== "string")
+                return [];
+            const slug = pin.slice(PREFIX[kind].length);
+            const words = pin.startsWith(PREFIX[kind]) ? items[kind].get(slug) : undefined;
+            if (words === undefined)
+                return [];
+            return kind === "faq"
+                ? [{ question: words["question"], answer: words["answer"] }]
+                : [{ term: words["term"], slug, definition: words["definition"], letter: words["letter"] }];
+        });
+        return { ...rest, data: { ...kept, [kind === "faq" ? "items" : "terms"]: entries } };
+    });
+}
+/** The kind a section pins, when it is a faq / glossary-index section carrying `pinned`. */
+export function pinnedKind(section) {
+    if (section === null || typeof section !== "object")
+        return undefined;
+    const { type, data } = section;
+    const kind = type === "faq" ? "faq" : type === "glossary-index" ? "term" : undefined;
+    return kind !== undefined && Array.isArray(data?.["pinned"]) ? kind : undefined;
+}
+/** The entries of a section D5 rewrites, or `undefined` for a section returned as read. */
+function entriesOf(section) {
+    if (section === null || typeof section !== "object")
+        return undefined;
+    const { type, data } = section;
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return undefined;
+    const fields = data;
+    if ("pinned" in fields || "tags" in fields)
+        return undefined;
+    const str = (value) => typeof value === "string" && value !== "";
+    const list = type === "faq" ? fields["items"] : type === "glossary-index" ? fields["terms"] : undefined;
+    if (!Array.isArray(list) || list.length === 0)
+        return undefined;
+    const entries = [];
+    for (const raw of list) {
+        if (raw === null || typeof raw !== "object")
+            return undefined;
+        if (type === "faq") {
+            if (!str(raw["question"]) || !str(raw["answer"]))
+                return undefined;
+            entries.push({
+                key: raw["question"],
+                words: { question: raw["question"], answer: raw["answer"] },
+                kicker: raw["kicker"] !== undefined,
+            });
+        }
+        else {
+            const { term, slug, definition, letter } = raw;
+            if (!str(term) || !str(slug) || !str(definition) || typeof letter !== "string" || !ITEM_SLUG.test(slug)) {
+                return undefined;
+            }
+            entries.push({ key: slug, words: { term, definition }, letter, kicker: false });
+        }
+    }
+    return { kind: type === "faq" ? "faq" : "term", entries };
+}
+function reasonOf(answer) {
+    return "network" in answer ? answer.network : `${answer.status} ${answer.code}`;
+}
+export function withLanguage(adapters, options) {
+    const base = `${options.apiOrigin}/v1/workspaces/${encodeURIComponent(options.workspaceId)}/language`;
+    const query = `?locale=${encodeURIComponent(options.locale)}`;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let state = "unprobed";
+    let offStatus;
+    const items = new Map();
+    /** In-run FAQ slug claims, so two questions never share a slug (D2); a term's slug is its key. */
+    const claimed = new Map();
+    const occurrences = [];
+    const homes = [];
+    const kickers = [];
+    const displaced = [];
+    async function call(method, url, body) {
+        for (let retry = 0;; retry++) {
+            let response;
+            try {
+                response = await options.fetch(url, {
+                    method,
+                    headers: {
+                        authorization: `Bearer ${options.apiKey}`,
+                        ...(body !== undefined && { "content-type": "application/json" }),
+                    },
+                    ...(body !== undefined && { body: JSON.stringify(body) }),
+                    redirect: "error",
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+            }
+            catch (err) {
+                const name = err instanceof Error ? err.name.toLowerCase() : "";
+                return { network: `network ${SAFE_CODE.test(name) ? name : "unknown"}` };
+            }
+            if (response.status === 429 && retry < RATE_LIMIT_RETRIES) {
+                const header = response.headers.get("retry-after");
+                const asked = header !== null && /^\d+$/.test(header) ? Number(header) : 0;
+                const seconds = asked >= 1 && asked <= RATE_LIMIT_WAIT_MAX_S ? asked : RATE_LIMIT_WAIT_MAX_S;
+                options.onLine?.(`rate limited — waiting ${seconds}s`);
+                await sleep(seconds * 1000);
+                continue;
+            }
+            let envelope = {};
+            try {
+                envelope = ((await response.json()) ?? {});
+            }
+            catch {
+                // No JSON body: the status alone is reported.
+            }
+            const code = envelope.error?.code;
+            const data = envelope.data;
+            return {
+                status: response.status,
+                code: typeof code === "string" && SAFE_CODE.test(code) ? code : "unknown",
+                data: data !== null && typeof data === "object" ? data : {},
+            };
+        }
+    }
+    const itemUrl = (kind, slug) => `${base}/${kind}/${encodeURIComponent(slug)}`;
+    /** The stored item at a slug, `null` for none; throws on any other answer. */
+    async function read(kind, slug) {
+        const answer = await call("GET", `${itemUrl(kind, slug)}${query}`);
+        if (!("network" in answer) && answer.status === 404)
+            return null;
+        const item = "network" in answer ? undefined : answer.data["item"];
+        if ("network" in answer || answer.status !== 200 || item === undefined) {
+            throw new Error(`language: ${kind}/${slug}: ${reasonOf(answer)}`);
+        }
+        return {
+            words: (item["words"] ?? {}),
+            published: (item["publishedWords"] ?? null),
+            live: item["live"] === true,
+        };
+    }
+    /** Writes `words` (a create when `version` is `null`) and sets the item Live. */
+    async function write(item, words, version) {
+        const url = itemUrl(item.kind, item.slug);
+        const saved = await call("PUT", `${url}${query}`, { words, version });
+        const ok = (a) => !("network" in a) && (a.status === 200 || a.status === 201);
+        if (!ok(saved))
+            throw failure(item, reasonOf(saved));
+        const tip = ("network" in saved ? undefined : saved.data["item"])?.version;
+        if (typeof tip === "string")
+            item.version = tip;
+        else if (options.apply)
+            throw failure(item, `${saved.status} unknown`);
+        const live = await call("POST", `${url}/live${query}`, { live: true, ...(item.version !== undefined && { version: item.version }) });
+        if (!ok(live))
+            throw failure(item, reasonOf(live));
+    }
+    function failure(item, reason) {
+        item.failed = reason;
+        return new Error(`language: ${item.kind}/${item.slug}: ${reason}`);
+    }
+    /** The item an entry is pinned to, created or found (D2–D4). */
+    async function ensure(kind, entry, page, home) {
+        const mapKey = `${kind}\u0000${entry.key}`;
+        const known = items.get(mapKey);
+        if (known !== undefined) {
+            // A failed item fails every page that carries it, so none pins it.
+            if (known.failed !== undefined)
+                throw new Error(`language: ${kind}/${known.slug}: ${known.failed}`);
+            if (home && !known.winner.home) {
+                // D3 — the home page outranks a page read before it; an item this run
+                // created takes its words, and a found one is never written (D4).
+                known.winner = { page, words: entry.words, home: true };
+                if (known.created && options.apply)
+                    await write(known, entry.words, known.version ?? null);
+            }
+            return known;
+        }
+        let slug = entry.key;
+        let stored;
+        if (kind === "term") {
+            stored = await read(kind, slug);
+        }
+        else {
+            const first = faqSlug(entry.key);
+            let skipped;
+            for (let n = 1;; n++) {
+                const candidate = n === 1 ? first : `${first}-${n}`;
+                const holder = claimed.get(candidate);
+                if (holder !== undefined && holder !== entry.key)
+                    continue;
+                stored = await read(kind, candidate);
+                if (stored !== null && stored.words["question"] !== entry.key) {
+                    skipped ??= candidate;
+                    continue;
+                }
+                slug = candidate;
+                break;
+            }
+            if (skipped !== undefined)
+                displaced.push({ slug: skipped, next: slug });
+        }
+        if (kind === "faq")
+            claimed.set(slug, entry.key);
+        const item = {
+            kind,
+            slug,
+            created: stored === null,
+            winner: { page, words: entry.words, home },
+            ...(stored !== null && { stored }),
+        };
+        items.set(mapKey, item);
+        if (stored === null)
+            await write(item, entry.words, null);
+        return item;
+    }
+    /** D6 — `true` when the pass runs. */
+    async function probe() {
+        if (state !== "unprobed")
+            return state === "on";
+        const answer = await call("GET", `${base}?kind=faq&locale=${encodeURIComponent(options.locale)}`);
+        if ("network" in answer || (answer.status !== 200 && !OFF_STATUSES.has(answer.status))) {
+            throw new Error(`language: the collection probe answered ${reasonOf(answer)}`);
+        }
+        if (answer.status === 200) {
+            state = "on";
+            return true;
+        }
+        state = "off";
+        offStatus = answer.status;
+        return false;
+    }
+    async function rewrite(source, type, slug, page) {
+        const sections = source.frontmatter["sections"];
+        if (!Array.isArray(sections))
+            return source;
+        const found = sections.map(entriesOf);
+        if (found.every((f) => f === undefined) || !(await probe()))
+            return source;
+        const rewritten = [];
+        for (const [index, section] of sections.entries()) {
+            const moving = found[index];
+            if (moving === undefined) {
+                rewritten.push(section);
+                continue;
+            }
+            const { kind, entries } = moving;
+            const pins = [];
+            const seen = new Set();
+            for (const entry of entries) {
+                const item = await ensure(kind, entry, page, type === HOME_TYPE[kind]);
+                pins.push(`${PREFIX[kind]}${item.slug}`);
+                occurrences.push({
+                    item,
+                    page,
+                    words: entry.words,
+                    ...(entry.letter !== undefined && { letter: entry.letter }),
+                    repeat: seen.has(item),
+                });
+                seen.add(item);
+                if (entry.kicker)
+                    kickers.push({ slug: item.slug, page });
+            }
+            const { data, ...rest } = section;
+            const { items: _items, terms: _terms, ...kept } = data;
+            // `GlossaryIndexDataSchema` requires `terms`, so a pinned glossary-index carries `[]`.
+            rewritten.push({ ...rest, data: { ...kept, ...(kind === "term" && { terms: [] }), pinned: pins } });
+        }
+        for (const kind of ["faq", "term"]) {
+            if (type !== HOME_TYPE[kind])
+                continue;
+            const own = rewritten.filter((s) => s.type === SECTION_TYPE[kind]);
+            if (own.length === 0)
+                continue;
+            const shown = new Set();
+            for (const s of own) {
+                const data = s.data ?? {};
+                for (const pin of data["pinned"] ?? [])
+                    shown.add(pin);
+            }
+            homes.push({ kind, slug, shown });
+        }
+        return { ...source, frontmatter: { ...source.frontmatter, sections: rewritten } };
+    }
+    function result() {
+        const list = [...items.values()];
+        const outcome = (item) => item.failed !== undefined
+            ? "failed"
+            : item.created
+                ? "created"
+                : same(item.stored.words, item.winner.words)
+                    ? "unchanged"
+                    : "kept";
+        const counts = { created: 0, unchanged: 0, kept: 0, failed: 0 };
+        for (const item of list)
+            counts[outcome(item)] += 1;
+        const renderChanges = [];
+        for (const o of occurrences) {
+            const { item } = o;
+            if (item.failed !== undefined)
+                continue;
+            const change = (from) => renderChanges.push({ kind: item.kind, slug: item.slug, page: o.page, from });
+            const shown = item.created ? item.winner.words : item.stored.live ? item.stored.published : null;
+            if (shown === null)
+                change("not Live");
+            else if (!same(o.words, shown))
+                change(item.created ? item.winner.page : "workspace");
+            else if (o.repeat)
+                change("repeat");
+            else if (o.letter !== undefined && o.letter !== letterOf(shown["term"] ?? "", options.locale))
+                change("letter");
+        }
+        const topUps = [];
+        for (const home of homes) {
+            for (const item of list) {
+                const key = `${PREFIX[item.kind]}${item.slug}`;
+                const live = item.created || item.stored.live;
+                if (item.kind === home.kind && item.failed === undefined && live && !home.shown.has(key)) {
+                    topUps.push({ kind: item.kind, slug: item.slug, page: `/${home.slug}` });
+                }
+            }
+        }
+        return {
+            items: list.map((item) => ({
+                kind: item.kind,
+                slug: item.slug,
+                result: outcome(item),
+                ...(item.failed !== undefined && { reason: item.failed }),
+            })),
+            counts,
+            renderChanges,
+            topUps,
+            droppedKickers: kickers,
+            displaced,
+        };
+    }
+    return {
+        adapters: {
+            ...adapters,
+            createMdxAdapter(o) {
+                const reader = adapters.createMdxAdapter(o);
+                return {
+                    async getPageSource(type, slug, locale) {
+                        const source = locale === undefined ? await reader.getPageSource(type, slug) : await reader.getPageSource(type, slug, locale);
+                        if (source === null || state === "off")
+                            return source;
+                        const page = `${locale === undefined ? "" : `${locale}/`}${type}/${slug}.mdx`;
+                        return rewrite(source, type, slug, page);
+                    },
+                };
+            },
+        },
+        report: () => state === "off" ? { off: offStatus } : state === "on" ? { result: result() } : {},
+    };
+}
+/** Whether two words records carry the same keys and values. */
+function same(a, b) {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every((k) => a[k] === b[k]);
+}
+// ── The report (D7) ─────────────────────────────────────────────────────────
+/** D6's one line when the API has no collection. */
+export function languageOffLine(status) {
+    return `language: the API has no Language collection for this workspace (${status}); FAQ and glossary items stay inline`;
+}
+/** A render change's line (D7). */
+export function renderChangeLine(c) {
+    const at = `language: ${c.kind}/${c.slug} on ${c.page}`;
+    switch (c.from) {
+        case "not Live":
+            return `${at}: is not Live, so ${c.page} will not show it`;
+        case "repeat":
+            return `${at}: repeats in one section, and the database read shows it once`;
+        case "letter":
+            return `${at}: is lettered otherwise at read than its file letters it`;
+        default:
+            return `${at}: shows ${c.from}'s words, not its own`;
+    }
+}
+/** The counts line, in the dry run's verbs or `--apply`'s. */
+export function languageCountsLine(result, apply) {
+    const { created, unchanged, kept, failed } = result.counts;
+    return `language: ${apply ? "created" : "create"} ${created} · unchanged ${unchanged} · kept ${kept} · failed ${failed}`;
+}
+/** Every line D7 prints, in order: items, counts, render changes, top-ups, dropped kickers, displacements. */
+export function languageLines(result, apply) {
+    const verb = (r) => (!apply && r === "created" ? "create" : r);
+    return [
+        ...result.items.map((i) => `language: ${i.kind}/${i.slug}: ${verb(i.result)}${i.reason === undefined ? "" : ` — ${i.reason}`}`),
+        languageCountsLine(result, apply),
+        ...result.renderChanges.map(renderChangeLine),
+        ...result.topUps.map((t) => `language: ${t.kind}/${t.slug}: now also on ${t.page}`),
+        ...result.droppedKickers.map((k) => `language: faq/${k.slug}: kicker dropped`),
+        ...result.displaced.map((d) => `language: faq/${d.slug}: the workspace holds a different question here; the file's is ${d.next}`),
+    ];
+}

package/dist/lib/env-catalog.js

@@ -120,7 +120,7 @@ export const ENV_CATALOG = {
         secret: false,
     },
     CONTENT_REVALIDATE_SECRET: {
-        description: "The shared secret /api/revalidate checks the API's publish webhook against; the same value as the API's.",
+        description: "The secret /api/revalidate checks the API's publish webhook against. On a site a hub serves, the value `spokes revalidate-url` printed for it — never the hub's own secret; otherwise the same value as the API's.",
         secret: true,
     },
     DATABASE_URL: {
@@ -164,7 +164,7 @@ export const ENV_CATALOG = {
         secret: false,
     },
     MCP_PUBLIC_HTTP_URL: {
-        description: "The public URL of the MCP HTTP transport, advertised by /.well-known/mcp.json.",
+        description: "The public URL of the MCP HTTP transport (apps/mcp's `/mcp`), advertised by /.well-known/mcp.json; with BETTER_AUTH_URL it turns on the OAuth metadata. Set by create-ailk provision-env.",
         secret: false,
     },
     MCP_TRANSPORT: {

package/dist/lib/import-mdx.d.ts

@@ -15,10 +15,29 @@ export interface MdxAdapterModule {
         } | null>;
     };
     SCHEMA_ORG_TYPES: readonly string[];
+    /**
+     * The words codec (#10534); without it a page keeps its words in `sections`
+     * and the run says so. Throws for sections the codec cannot carry.
+     */
+    sectionsToMarkdown?: (sections: readonly {
+        id: string;
+        type: string;
+        data?: unknown;
+    }[]) => string;
+    /**
+     * The adapter's frontmatter parser (#10701), for the editorial tree the
+     * adapter cannot read; without it every editorial page fails.
+     */
+    parseFrontmatter?: (raw: string) => {
+        data: Record<string, unknown>;
+        content: string;
+    };
 }
 export interface ImportMdxOptions {
     /** The site's content root (`content/`). */
     contentRoot: string;
+    /** The site's editorial root (`apps/web/content`); omitted, it is not walked. */
+    editorialRoot?: string;
     adapters: MdxAdapterModule;
     /** The API's origin: https, or http on a loopback host. */
     apiOrigin: string;
@@ -33,13 +52,19 @@ export interface ImportMdxOptions {
     sleep?: (ms: number) => Promise<void>;
     /** Each report line as it is decided, and each wait; defaults to nothing. */
     onLine?: (line: string) => void;
+    /** Set Live each written page that has no Live version (#10659 D2); off by default. */
+    publish?: boolean;
 }
+/** The tree a page came from: `content/` or the site's `apps/web/content`. */
+export type ImportMdxRoot = "content" | "editorial";
 export type ImportMdxOutcome = {
+    root: ImportMdxRoot;
     path: string;
     result: "created" | "updated" | "unchanged";
     type: string;
     slug: string;
 } | {
+    root: ImportMdxRoot;
     path: string;
     result: "skipped" | "failed";
     reason: string;
@@ -48,7 +73,19 @@ export type ImportMdxResultKind = ImportMdxOutcome["result"];
 export interface ImportMdxResult {
     pages: ImportMdxOutcome[];
     counts: Record<ImportMdxResultKind, number>;
+    /** With `publish`: the pages with a Live version at the end of the run. */
+    live?: number;
+    /** With `publish`: the publish requests answered 200. */
+    published?: number;
+}
+export declare function isDirectory(path: string): boolean;
+/** Where an outcome is about: the root and the path below it. */
+interface At {
+    root: ImportMdxRoot;
+    path: string;
 }
+/** An outcome's printed path: an editorial one says so (#10701 D6). */
+export declare function outcomePath(at: At): string;
 /** The whole report, one line per page and a final count line. */
 export declare function formatImportMdxReport(result: ImportMdxResult): string;
 export declare function importMdx(opts: ImportMdxOptions): Promise<ImportMdxResult>;
@@ -57,3 +94,4 @@ export declare function importMdx(opts: ImportMdxOptions): Promise<ImportMdxResu
  * create-ailk's own `node_modules`.
  */
 export declare function loadSiteMdxAdapter(siteRoot: string): Promise<MdxAdapterModule>;
+export {};