@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/dist/content-workspace.d.ts

@@ -0,0 +1,293 @@
+import { type Document, type Variant } from './content.js';
+import { type AuthoredPublicationConfig } from './publication-plan.js';
+import { type loadConfig } from './config.js';
+import { type SnippetDefinition } from './snippets.js';
+import type { ReaderFiltersConfig, ReaderSelection } from './reader-filters.js';
+import type { loadMetadataProvider } from './metadata-provider.js';
+/** Shared source resolution. No website navigation, styles, hosting or provider setup. */
+export declare function prepareContentWorkspace({ base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }: {
+    base: string;
+    basePath: string;
+    config: AuthoredPublicationConfig & {
+        snippets?: unknown;
+        variables?: unknown;
+        apis?: unknown;
+    };
+    loaded: Awaited<ReturnType<typeof loadConfig>>;
+    variants: Variant[];
+    language: string;
+    readerFilters?: ReaderFiltersConfig;
+    contentFilter?: ReaderSelection;
+    metadataProvider?: Awaited<ReturnType<typeof loadMetadataProvider>>;
+    metadataDependencies: Set<string>;
+    sourceOverrides?: ReadonlyMap<string, string>;
+    authoringFiles?: ReadonlySet<string>;
+    allowRouteCollisions?: boolean;
+}): Promise<{
+    docs: Map<string, Document>;
+    knownDocumentIds: Set<string>;
+    knownDocumentTypes: Map<string, string>;
+    authoredOperationIds: Set<string>;
+    routeOwners: Map<string, string>;
+    contentDir: string;
+    snippets: Map<string, SnippetDefinition>;
+    apiPlan: {
+        api: import("./api.js").ApiReader;
+        queryRules: Map<string, import("./api.js").QuerySyntaxRule[]>;
+        lifecycleMappings: Map<string, {
+            from: string;
+            values: Record<string, "beta" | "in-development" | "deprecated" | "experimental">;
+        }>;
+        extensionValue: (operation: unknown, selector: string) => unknown;
+        sourceForVariant: (apiId: string, definition: {
+            [key: string]: unknown;
+            source?: {
+                kind: string;
+                path: string;
+                [key: string]: unknown;
+            };
+            publications?: Array<{
+                channel: string;
+                version: string;
+                source: {
+                    kind: string;
+                    path: string;
+                    [key: string]: unknown;
+                };
+                discovery?: {
+                    endpoint?: string;
+                };
+                [key: string]: unknown;
+            }>;
+            discovery?: {
+                endpoint?: string;
+            };
+            operations?: Array<{
+                id: string;
+                reference: string;
+                sourceOperationId?: string;
+            }>;
+            generateReferences?: boolean | {
+                pathPrefix?: string;
+                include?: string[];
+                exclude?: string[];
+            };
+            mappings?: unknown;
+        }, variant: Variant) => {
+            file: string;
+            source: {
+                [key: string]: unknown;
+                kind: string;
+                path: string;
+            };
+            definition: {
+                [key: string]: unknown;
+                source?: {
+                    kind: string;
+                    path: string;
+                    [key: string]: unknown;
+                };
+                publications?: Array<{
+                    channel: string;
+                    version: string;
+                    source: {
+                        kind: string;
+                        path: string;
+                        [key: string]: unknown;
+                    };
+                    discovery?: {
+                        endpoint?: string;
+                    };
+                    [key: string]: unknown;
+                }>;
+                discovery?: {
+                    endpoint?: string;
+                };
+                operations?: Array<{
+                    id: string;
+                    reference: string;
+                    sourceOperationId?: string;
+                }>;
+                generateReferences?: boolean | {
+                    pathPrefix?: string;
+                    include?: string[];
+                    exclude?: string[];
+                };
+                mappings?: unknown;
+            };
+            publicationIndex: number;
+            apiId: string;
+        } | undefined;
+        knownOperations: Map<string, {
+            apiId: string;
+            reference: string;
+        }>;
+        apiDefinitions: Record<string, {
+            [key: string]: unknown;
+            source?: {
+                kind: string;
+                path: string;
+                [key: string]: unknown;
+            };
+            publications?: Array<{
+                channel: string;
+                version: string;
+                source: {
+                    kind: string;
+                    path: string;
+                    [key: string]: unknown;
+                };
+                discovery?: {
+                    endpoint?: string;
+                };
+                [key: string]: unknown;
+            }>;
+            discovery?: {
+                endpoint?: string;
+            };
+            operations?: Array<{
+                id: string;
+                reference: string;
+                sourceOperationId?: string;
+            }>;
+            generateReferences?: boolean | {
+                pathPrefix?: string;
+                include?: string[];
+                exclude?: string[];
+            };
+            mappings?: unknown;
+        }>;
+    };
+    api: import("./api.js").ApiReader;
+    sourceForVariant: (apiId: string, definition: {
+        [key: string]: unknown;
+        source?: {
+            kind: string;
+            path: string;
+            [key: string]: unknown;
+        };
+        publications?: Array<{
+            channel: string;
+            version: string;
+            source: {
+                kind: string;
+                path: string;
+                [key: string]: unknown;
+            };
+            discovery?: {
+                endpoint?: string;
+            };
+            [key: string]: unknown;
+        }>;
+        discovery?: {
+            endpoint?: string;
+        };
+        operations?: Array<{
+            id: string;
+            reference: string;
+            sourceOperationId?: string;
+        }>;
+        generateReferences?: boolean | {
+            pathPrefix?: string;
+            include?: string[];
+            exclude?: string[];
+        };
+        mappings?: unknown;
+    }, variant: Variant) => {
+        file: string;
+        source: {
+            [key: string]: unknown;
+            kind: string;
+            path: string;
+        };
+        definition: {
+            [key: string]: unknown;
+            source?: {
+                kind: string;
+                path: string;
+                [key: string]: unknown;
+            };
+            publications?: Array<{
+                channel: string;
+                version: string;
+                source: {
+                    kind: string;
+                    path: string;
+                    [key: string]: unknown;
+                };
+                discovery?: {
+                    endpoint?: string;
+                };
+                [key: string]: unknown;
+            }>;
+            discovery?: {
+                endpoint?: string;
+            };
+            operations?: Array<{
+                id: string;
+                reference: string;
+                sourceOperationId?: string;
+            }>;
+            generateReferences?: boolean | {
+                pathPrefix?: string;
+                include?: string[];
+                exclude?: string[];
+            };
+            mappings?: unknown;
+        };
+        publicationIndex: number;
+        apiId: string;
+    } | undefined;
+    knownOperations: Map<string, {
+        apiId: string;
+        reference: string;
+    }>;
+    relatedApiTargets: Map<string, Document[]>;
+    guidesByApi: Map<string, Document[]>;
+    sourceForOperation: (operationId: string, variant: Variant) => {
+        sourceOperationId: string;
+        file: string;
+        source: {
+            [key: string]: unknown;
+            kind: string;
+            path: string;
+        };
+        definition: {
+            [key: string]: unknown;
+            source?: {
+                kind: string;
+                path: string;
+                [key: string]: unknown;
+            };
+            publications?: Array<{
+                channel: string;
+                version: string;
+                source: {
+                    kind: string;
+                    path: string;
+                    [key: string]: unknown;
+                };
+                discovery?: {
+                    endpoint?: string;
+                };
+                [key: string]: unknown;
+            }>;
+            discovery?: {
+                endpoint?: string;
+            };
+            operations?: Array<{
+                id: string;
+                reference: string;
+                sourceOperationId?: string;
+            }>;
+            generateReferences?: boolean | {
+                pathPrefix?: string;
+                include?: string[];
+                exclude?: string[];
+            };
+            mappings?: unknown;
+        };
+        publicationIndex: number;
+        apiId: string;
+    };
+}>;

package/dist/content-workspace.js

@@ -0,0 +1,69 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { parse } from './content.js';
+import { planAuthoredDocuments } from './publication-plan.js';
+import { materializeApiReferences } from './api-publication-plan.js';
+import { explainSegments } from './config.js';
+import { validateSnippetConfig } from './snippets.js';
+const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+/** Shared source resolution. No website navigation, styles, hosting or provider setup. */
+export async function prepareContentWorkspace({ base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }) {
+    const { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir } = await planAuthoredDocuments({
+        base, basePath, config, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions
+    });
+    if (config.snippets !== undefined && (!config.snippets || typeof config.snippets !== 'object' || Array.isArray(config.snippets)))
+        throw new Error('snippets must be a mapping');
+    const snippets = new Map();
+    for (const [id, definition] of Object.entries(config.snippets ?? {})) {
+        const variables = validateSnippetConfig(id, definition);
+        const source = explainSegments(loaded, ['snippets', id, 'file']).source.file;
+        const file = path.resolve(path.dirname(source), definition.file);
+        const body = await readFile(file, 'utf8');
+        if (/^---\r?\n/.test(body))
+            throw new Error(`${file}: snippets use plain Markdown without page frontmatter`);
+        snippets.set(id, { file, tree: parse.parse(body), variables });
+    }
+    if (config.variables !== undefined && (!config.variables || typeof config.variables !== 'object' || Array.isArray(config.variables)))
+        throw new Error('variables must be a mapping');
+    const apiPlan = await materializeApiReferences({
+        config, loaded, variants, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, basePath, readerFilters, contentFilter, allowRouteCollisions
+    });
+    const { api, sourceForVariant, knownOperations } = apiPlan;
+    const relatedApiTargets = new Map();
+    const guidesByApi = new Map();
+    for (const doc of docs.values()) {
+        const targets = [];
+        for (const id of doc.frontmatter.relatedApiReferences ?? []) {
+            if (!knownDocumentIds.has(id))
+                throw new Error(`${doc.file}: unknown related API reference ${id}`);
+            if (knownDocumentTypes.get(id) !== 'api-reference')
+                throw new Error(`${doc.file}: related API reference ${id} must identify an api-reference page`);
+            const target = docs.get(keyFor(id, doc.variant));
+            if (!target)
+                continue;
+            targets.push(target);
+            const key = keyFor(target.frontmatter.id, target.variant);
+            const guides = guidesByApi.get(key) ?? [];
+            guides.push(doc);
+            guidesByApi.set(key, guides);
+        }
+        relatedApiTargets.set(keyFor(doc.frontmatter.id, doc.variant), targets);
+    }
+    const sourceForOperation = (operationId, variant) => {
+        const known = knownOperations.get(operationId);
+        if (!known)
+            throw new Error(`unknown stable operation ${operationId}`);
+        const definition = apiPlan.apiDefinitions[known.apiId];
+        const operation = definition?.operations?.find(entry => entry.id === operationId);
+        if (!definition || !operation)
+            throw new Error(`unknown stable operation ${operationId}`);
+        if (!operation.sourceOperationId)
+            throw new Error(`API ${known.apiId} operation needs sourceOperationId`);
+        const binding = sourceForVariant(known.apiId, definition, variant);
+        if (!binding)
+            throw new Error(`no OpenAPI source for ${variant.channel}/${variant.version} (${operationId})`);
+        return { ...binding, sourceOperationId: operation.sourceOperationId };
+    };
+    return { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir, snippets,
+        apiPlan, api, sourceForVariant, knownOperations, relatedApiTargets, guidesByApi, sourceForOperation };
+}

package/dist/content.d.ts

@@ -0,0 +1,41 @@
+import type { ReaderSelection } from './reader-filters.js';
+import type { Document } from './content-source.js';
+export type { Document, Frontmatter, NavigationNode, Variant } from './content-source.js';
+export { readDocument, routeFor, markdownRoute } from './content-source.js';
+export { parse, parsePlainMarkdown, text, paragraph, heading, list, link, code, root, renderMarkdown } from './semantic-markdown.js';
+export { transformMdx } from './component-transform.js';
+export { renderHtml } from './html-renderer.js';
+export { buildHtmlPage, shareCardText, typeLabel } from './page-renderer.js';
+export type { SiteLink, HeaderConfig, FooterConfig, PageShell } from './page-renderer.js';
+export declare function searchIndex(pages: Array<{
+    doc: Document;
+    html: string;
+    htmlTree?: any;
+}>, config?: any): {
+    documents: {
+        readerFilters?: ReaderSelection | undefined;
+        readerSegments?: {
+            filters: ReaderSelection;
+            text: string;
+        }[] | undefined;
+        headings: {
+            id: string;
+            title: string;
+        }[];
+        text: string;
+        subarea?: string | string[] | undefined;
+        area?: string | string[] | undefined;
+        product?: string | undefined;
+        id: string;
+        demo: boolean;
+        url: string;
+        markdownUrl: string;
+        title: string;
+        summary: string;
+        type: string;
+        variant: string;
+    }[];
+    synonyms?: any;
+    schemaVersion: number;
+};
+export declare function projectMetadata(doc: Document, config: any): string;

package/dist/content.js

@@ -0,0 +1,176 @@
+import { fictionalDocument, resolveLlmsDiscovery } from './llms-discovery.js';
+import YAML from 'yaml';
+import { nativePublicFields, protectedMetadataRoots, publicFrontmatterPaths } from './frontmatter.js';
+import { surfaceText } from './surface-text.js';
+export { readDocument, routeFor, markdownRoute } from './content-source.js';
+export { parse, parsePlainMarkdown, text, paragraph, heading, list, link, code, root, renderMarkdown } from './semantic-markdown.js';
+export { transformMdx } from './component-transform.js';
+export { renderHtml } from './html-renderer.js';
+export { buildHtmlPage, shareCardText, typeLabel } from './page-renderer.js';
+// API separators are visually hidden punctuation; join them to the preceding text so search reads "integer; default: 0".
+const variantKey = (variant) => `${variant.channel}|${variant.version}|${variant.language}`;
+const plainText = (html) => html.replace(/<(script|style)[^]*?<\/\1>/g, ' ').replace(/(?:<\/[a-z]+>)?<span class="api-separator">([^<]*)<\/span>/g, '$1').replace(/<[^>]+>/g, ' ')
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#x27;|&#39;/g, "'").replace(/&amp;/g, '&').replace(/\s+/g, ' ').trim();
+// One compact record per published page; headings allow results to deep-link into a section.
+export function searchIndex(pages, config = {}) {
+    const discovery = resolveLlmsDiscovery(config.outputs?.llms);
+    const readerSegments = (tree) => {
+        const parts = new Map();
+        const walk = (node, filters) => {
+            if (!node)
+                return;
+            const local = node.data?.hProperties?.['data-reader-filters'];
+            const next = typeof local === 'string' ? { ...filters, ...JSON.parse(local) } : filters;
+            if (typeof node.value === 'string') {
+                const key = JSON.stringify(next);
+                const values = parts.get(key) ?? [];
+                if (node.data?.hProperties?.className?.includes('api-separator') && values.length)
+                    values[values.length - 1] += node.value.trimEnd();
+                else
+                    values.push(node.value);
+                parts.set(key, values);
+            }
+            for (const child of node.children ?? [])
+                walk(child, next);
+        };
+        walk(tree, {});
+        return [...parts].map(([filters, words]) => ({ filters: JSON.parse(filters), text: words.join(' ').replace(/\s+/g, ' ').trim().slice(0, 5000) }));
+    };
+    return {
+        schemaVersion: 1,
+        ...(config.searchSynonyms?.length ? { synonyms: config.searchSynonyms } : {}),
+        documents: pages.map(({ doc, html, htmlTree }) => {
+            const article = html.match(/<article>([^]*)<\/article>/)?.[1] ?? '';
+            const headings = [...article.matchAll(/<h([2-4])\b[^>]*?\bid="([^"]+)"[^>]*>([^]*?)<\/h\1>/g)].map(match => ({ id: match[2], title: plainText(match[3]) }));
+            return { id: doc.frontmatter.id, demo: fictionalDocument(doc, discovery), url: doc.route, markdownUrl: doc.markdownRoute, title: doc.frontmatter.title, summary: surfaceText(doc.frontmatter, 'search', config) ?? '', type: doc.frontmatter.type, variant: variantKey(doc.variant), ...(doc.frontmatter.product !== undefined ? { product: doc.frontmatter.product } : {}), ...(doc.frontmatter.area !== undefined ? { area: doc.frontmatter.area } : {}), ...(doc.frontmatter.subarea !== undefined ? { subarea: doc.frontmatter.subarea } : {}), headings, text: plainText(article).slice(0, 5000), ...(config.readerFilters ? { readerFilters: doc.readerFilters ?? {}, readerSegments: readerSegments(htmlTree) } : {}) };
+        })
+    };
+}
+export function projectMetadata(doc, config) {
+    const projection = config.outputs?.markdown?.metadata;
+    if (!projection)
+        return '';
+    if (typeof projection !== 'object' || Array.isArray(projection))
+        throw new Error('Markdown metadata projection must be a mapping');
+    const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+    const safePath = (value) => /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*$/.test(value);
+    const publicationFields = new Set(['channel', 'version', 'language', 'canonicalUrl']);
+    const approved = publicFrontmatterPaths(config.frontmatter);
+    const validateSource = (source) => {
+        if (!safePath(source))
+            throw new Error(`Invalid metadata source path ${source}`);
+        const [namespace, field] = source.split('.');
+        if (namespace === 'publication' && publicationFields.has(field) && source.split('.').length === 2)
+            return;
+        if (namespace !== 'frontmatter' || !field)
+            throw new Error(`Unknown metadata source ${source}`);
+        if (protectedMetadataRoots.has(field))
+            throw new Error(`Field ${source} is protected from public Markdown`);
+        if (nativePublicFields.has(field) && source.split('.').length === 2)
+            return;
+        if (!approved.has(source))
+            throw new Error(`Field ${source} is not approved for public Markdown`);
+    };
+    let format = projection.format ?? 'none';
+    let omitNull = projection.omitNull ?? true;
+    let fields = {};
+    const apply = (layer, label) => {
+        if (!object(layer))
+            throw new Error(`${label} must be a mapping`);
+        for (const key of Object.keys(layer))
+            if (!['format', 'fields', 'addFields', 'removeFields', 'omitNull'].includes(key))
+                throw new Error(`Unknown ${label} setting ${key}`);
+        if (layer.format !== undefined)
+            format = layer.format;
+        if (layer.omitNull !== undefined) {
+            if (typeof layer.omitNull !== 'boolean')
+                throw new Error(`${label}.omitNull must be true or false`);
+            omitNull = layer.omitNull;
+        }
+        if (layer.fields !== undefined) {
+            if (!object(layer.fields))
+                throw new Error(`${label}.fields must map output names to source paths`);
+            fields = { ...layer.fields };
+        }
+        if (layer.addFields !== undefined) {
+            if (!object(layer.addFields))
+                throw new Error(`${label}.addFields must map output names to source paths`);
+            fields = { ...fields, ...layer.addFields };
+        }
+        if (layer.removeFields !== undefined) {
+            if (!Array.isArray(layer.removeFields) || layer.removeFields.some((name) => typeof name !== 'string'))
+                throw new Error(`${label}.removeFields must be a list of output names`);
+            for (const name of layer.removeFields) {
+                if (!(name in fields))
+                    throw new Error(`${label}.removeFields names missing output ${name}`);
+                delete fields[name];
+            }
+        }
+    };
+    for (const key of Object.keys(projection))
+        if (!['format', 'fields', 'addFields', 'removeFields', 'omitNull', 'byType', 'profiles'].includes(key))
+            throw new Error(`Unknown metadata setting ${key}`);
+    apply(Object.fromEntries(Object.entries(projection).filter(([key]) => ['format', 'fields', 'addFields', 'removeFields', 'omitNull'].includes(key))), 'metadata');
+    const byType = projection.byType ?? {};
+    if (!object(byType))
+        throw new Error('metadata.byType must be a mapping');
+    if (byType[doc.frontmatter.type])
+        apply(byType[doc.frontmatter.type], `metadata.byType.${doc.frontmatter.type}`);
+    const profiles = projection.profiles ?? {};
+    if (!object(profiles))
+        throw new Error('metadata.profiles must be a mapping');
+    const pageSetting = doc.frontmatter.markdownMetadata;
+    if (pageSetting !== undefined) {
+        const page = typeof pageSetting === 'string' ? { profile: pageSetting } : pageSetting;
+        if (!object(page))
+            throw new Error(`${doc.file}: markdownMetadata must be a profile name or mapping`);
+        for (const key of Object.keys(page))
+            if (!['profile', 'format', 'fields', 'addFields', 'removeFields', 'omitNull'].includes(key))
+                throw new Error(`${doc.file}: unknown markdownMetadata setting ${key}`);
+        if (page.profile !== undefined) {
+            if (typeof page.profile !== 'string' || !profiles[page.profile])
+                throw new Error(`${doc.file}: unknown markdownMetadata profile ${page.profile}`);
+            apply(profiles[page.profile], `metadata.profiles.${page.profile}`);
+        }
+        const { profile, ...override } = page;
+        apply(override, `${doc.file}: markdownMetadata`);
+    }
+    if (format === 'none')
+        return '';
+    if (format !== 'yaml-frontmatter')
+        throw new Error(`Unsupported Markdown metadata format ${format}`);
+    const publication = { ...doc.variant, canonicalUrl: doc.route };
+    const output = {};
+    const readPath = (source) => {
+        const [namespace, ...segments] = source.split('.');
+        const root = namespace === 'frontmatter' ? doc.frontmatter : publication;
+        return segments.reduce((at, segment) => at !== null && at !== undefined && Object.prototype.hasOwnProperty.call(at, segment) ? at[segment] : undefined, root);
+    };
+    for (const [name, source] of Object.entries(fields)) {
+        if (!safePath(name) || ['__proto__', 'prototype', 'constructor'].some(segment => name.split('.').includes(segment)))
+            throw new Error(`Invalid metadata output name ${name}`);
+        if (typeof source !== 'string')
+            throw new Error(`Metadata source for ${name} must be a path`);
+        validateSource(source);
+        const value = readPath(source);
+        if (value === undefined || value === null) {
+            if (omitNull)
+                continue;
+            throw new Error(`Missing metadata ${source} in ${doc.file}`);
+        }
+        const segments = name.split('.');
+        let at = output;
+        for (const segment of segments.slice(0, -1)) {
+            if (at[segment] === undefined)
+                at[segment] = {};
+            if (!object(at[segment]))
+                throw new Error(`Metadata output conflict at ${name}`);
+            at = at[segment];
+        }
+        const last = segments.at(-1);
+        if (at[last] !== undefined)
+            throw new Error(`Duplicate metadata output ${name}`);
+        at[last] = value;
+    }
+    return Object.keys(output).length ? `---\n${YAML.stringify(output)}---\n\n` : '';
+}

package/dist/cookbook-chooser.d.ts

@@ -0,0 +1,19 @@
+import type { Document } from './content.js';
+type Option = {
+    id: string;
+    label: string;
+    doc: string;
+    when?: string;
+    needs?: string;
+    outcome?: string;
+};
+export type Cookbook = {
+    title: string;
+    options: Option[];
+    mode?: 'single' | 'multiple';
+};
+export type Cookbooks = Record<string, Cookbook>;
+export declare function validateCookbooks(value: unknown, file: string): Cookbooks;
+export declare function cookbookChooserComponent(node: any, file: string): any;
+export declare function resolveCookbookTree(tree: any, current: Document, documents: Map<string, Document>, cookbooks: Cookbooks, targets: string[]): any;
+export {};

package/dist/cookbook-chooser.js

@@ -0,0 +1,56 @@
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const keys = (value, allowed) => Object.keys(value).every(key => allowed.includes(key));
+const validId = (value) => typeof value === 'string' && /^[a-z][a-z0-9-]*$/.test(value);
+const nonempty = (value) => typeof value === 'string' && !!value.trim();
+export function validateCookbooks(value, file) {
+    if (value === undefined)
+        return {};
+    if (!object(value))
+        throw new Error(`${file}: cookbooks must be a mapping`);
+    const result = {};
+    for (const [id, raw] of Object.entries(value)) {
+        const prefix = `${file}: cookbooks.${id}`;
+        if (!validId(id) || !object(raw) || !keys(raw, ['title', 'options', 'mode']) || !nonempty(raw.title))
+            throw new Error(`${prefix} needs a kebab-case ID, title, and options`);
+        if (raw.mode !== undefined && !['single', 'multiple'].includes(raw.mode))
+            throw new Error(`${prefix}.mode must be single or multiple`);
+        if (!Array.isArray(raw.options) || !raw.options.length || raw.options.some(option => !object(option) || !keys(option, ['id', 'label', 'doc', 'when', 'needs', 'outcome']) || !validId(option.id) || !nonempty(option.label) || !nonempty(option.doc) || ['when', 'needs', 'outcome'].some(key => option[key] !== undefined && !nonempty(option[key]))))
+            throw new Error(`${prefix}.options needs an ID, label, and recipe document ID for each choice; when, needs, and outcome must be nonempty text`);
+        const options = raw.options;
+        const optionIds = new Set(options.map(option => option.id));
+        if (optionIds.size !== options.length)
+            throw new Error(`${prefix}.options repeats an ID`);
+        if (new Set(options.map(option => option.label.trim().toLowerCase())).size !== options.length)
+            throw new Error(`${prefix}.options repeats a label`);
+        if (new Set(options.map(option => option.doc)).size !== options.length)
+            throw new Error(`${prefix}.options repeats a recipe target`);
+        result[id] = { title: raw.title, options, ...(raw.mode ? { mode: raw.mode } : {}) };
+    }
+    return result;
+}
+export function cookbookChooserComponent(node, file) {
+    const attributes = node.attributes ?? [];
+    if (node.type !== 'mdxJsxFlowElement' || node.children?.length || attributes.length !== 1 || attributes[0].type !== 'mdxJsxAttribute' || attributes[0].name !== 'id' || !nonempty(attributes[0].value))
+        throw new Error(`${file}: <CookbookChooser> needs only a literal id and no content`);
+    return { type: 'docCookbookChooser', id: attributes[0].value, sourceFile: file };
+}
+export function resolveCookbookTree(tree, current, documents, cookbooks, targets) {
+    const sameVariant = (a, b) => a.variant.channel === b.variant.channel && a.variant.version === b.variant.version && a.variant.language === b.variant.language;
+    const walk = (node) => {
+        if (node.type !== 'docCookbookChooser')
+            return node.children ? { ...node, children: node.children.map(walk) } : node;
+        const cookbook = cookbooks[node.id];
+        if (!cookbook)
+            throw new Error(`${node.sourceFile}: unknown cookbook ${node.id}`);
+        const options = cookbook.options.map(option => {
+            const doc = [...documents.values()].find(candidate => candidate.frontmatter.id === option.doc && sameVariant(candidate, current));
+            if (!doc || doc.frontmatter.type !== 'recipe')
+                throw new Error(`${node.sourceFile}: cookbook ${node.id} target ${option.doc} needs a published recipe in this publication`);
+            if (!targets.includes(option.doc))
+                targets.push(option.doc);
+            return { ...option, title: doc.frontmatter.title, summary: doc.frontmatter.summary, route: doc.route, markdownRoute: doc.markdownRoute };
+        });
+        return { type: 'docCookbookChooser', id: node.id, mode: cookbook.mode ?? 'multiple', title: cookbook.title, options };
+    };
+    return walk(tree);
+}

package/dist/dev.d.ts

@@ -0,0 +1,2 @@
+import type { Server } from 'node:http';
+export declare function startDev(configFile: string, outputDirectory: string, host?: string, port?: number): Promise<Server>;