@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/cli.js

@@ -40,7 +40,7 @@ import { buildChunkIndex, embeddingInput } from './index-build.js';
 import { createProvider, embedChunkIndex, readEmbeddings } from './embeddings.js';
 import { embeddingProviderConfig, queryProviderConfig, validateRetrieval } from './retrieval-config.js';
 import { defaultLogNotice, validateChat } from './chat-config.js';
-import { createSession, turnstileVerifier } from './turnstile.js';
+import { createSession, turnstilePreviewVerifier } from './turnstile.js';
 import { adaptiveChallenge } from './budget.js';
 import { validateReaderFilters } from './reader-filters.js';
 import { askQuestion } from './ask.js';
@@ -142,11 +142,19 @@ try {
         const args = [subcommand, ...rest].filter((item) => item !== undefined);
         const positional = [];
         let port = defaultPort();
+        let profile;
         for (let index = 0; index < args.length; index++) {
-            if (args[index] === '--port') {
+            if (args[index] === '--port' || args[index] === '--profile') {
+                const option = args[index];
                 if (!args[index + 1] || args[index + 1].startsWith('--'))
-                    throw new Error('Usage: shoalrun dev [config] [output] [--port PORT]');
-                port = Number(args[++index]);
+                    throw new Error('Usage: shoalrun dev [config] [output] [--port PORT] [--profile FILE]');
+                if (option === '--profile') {
+                    if (profile !== undefined)
+                        throw new Error('Duplicate dev option --profile');
+                    profile = args[++index];
+                }
+                else
+                    port = Number(args[++index]);
             }
             else if (args[index].startsWith('--'))
                 throw new Error(`Unknown dev option ${args[index]}`);
@@ -154,8 +162,8 @@ try {
                 positional.push(args[index]);
         }
         if (positional.length > 2)
-            throw new Error('Usage: shoalrun dev [config] [output] [--port PORT]');
-        await startDev(positional[0] ?? 'docs.config.yaml', positional[1] ?? 'site-dist', '127.0.0.1', port);
+            throw new Error('Usage: shoalrun dev [config] [output] [--port PORT] [--profile FILE]');
+        await startDev(positional[0] ?? 'docs.config.yaml', positional[1] ?? 'site-dist', '127.0.0.1', port, { profile });
     }
     else if (command === 'vercel' && subcommand === 'build') {
         // --chat adds the optional answer function: it needs chat and retrieval settings and the embedding key at build time.
@@ -261,7 +269,7 @@ try {
             if (publicPreview) {
                 chatConfigForPreview = chatConfig;
                 publicSettings = { siteKey: '1x00000000000000000000AA', ...(chatConfig?.challenge?.when === 'always' ? { prewarm: true } : {}), notice: chatConfig?.log?.notice ?? defaultLogNotice, ...(chatConfig?.panel ? { panel: chatConfig.panel } : {}) };
-                const verify = turnstileVerifier({ secret: '1x0000000000000000000000000000000AA' });
+                const verify = turnstilePreviewVerifier();
                 challenge = ({ token, ip }) => verify({ token, ip });
             }
             const handler = createAskHandler({ hosts, exposeErrors: true, ...(publicPreview ? { response: 'public', challenge, session: createSession({ secret: '1x0000000000000000000000000000000AA' }), ...(chatConfigForPreview?.challenge?.when === 'always' || !setup.budget ? {} : { challengeNeeded: adaptiveChallenge(setup.budget, { freeQuestions: chatConfigForPreview?.challenge?.freeQuestions, busyShare: chatConfigForPreview?.challenge?.busyShare }) }) } : {}), ...(log ? { record: event => log.write(event) } : {}), ...(setup.budget ? { budget: setup.budget } : {}), answer: (question, history, context) => askQuestion({ question, history, ...setup.options, modelAllowed: context.modelAllowed, signal: context.signal, ...(publicPreview ? { requireCitations: true } : {}) }) });
@@ -372,9 +380,9 @@ try {
     }
     else if (command === 'search') {
         if (!subcommand || !rest[0] || rest[0].startsWith('--'))
-            throw new Error('Usage: shoalrun search <site-directory> <query> [--channel C] [--version V] [--language L] [--limit N]');
+            throw new Error('Usage: shoalrun search <site-directory> <query> [--product P] [--channel C] [--version V] [--language L] [--limit N]');
         const options = {};
-        const names = { '--channel': 'channel', '--version': 'version', '--language': 'language', '--limit': 'limit' };
+        const names = { '--product': 'product', '--channel': 'channel', '--version': 'version', '--language': 'language', '--limit': 'limit' };
         for (let index = 1; index < rest.length; index += 2) {
             const flag = rest[index];
             const value = rest[index + 1];
@@ -432,7 +440,7 @@ try {
         process.stdout.write(JSON.stringify({ status: 'ok', documents: result.documents, chunks: result.index.chunks.length, sourceDigest: result.index.sourceDigest, publications, output: result.output, ...(embeddings ? { embeddings } : {}) }, null, 2) + '\n');
     }
     else if (command === 'ask') {
-        const usage = 'Usage: shoalrun ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json]';
+        const usage = 'Usage: shoalrun ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--product P] [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json]';
         if (!subcommand || subcommand.startsWith('--') || !rest[0] || rest[0].startsWith('--'))
             throw new Error(usage);
         const values = {};
@@ -449,14 +457,14 @@ try {
                 views.push(value);
                 continue;
             }
-            if (!['--config', '--model', '--passages', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--'))
+            if (!['--config', '--model', '--passages', '--product', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--'))
                 throw new Error(usage);
             if (values[flag] !== undefined)
                 throw new Error(`Duplicate ask option ${flag}`);
             values[flag] = value;
         }
         const configFile = values['--config'] ?? await discoverConfig(process.cwd()).catch(() => { throw new Error('No docs.config.yaml found; pass --config FILE. `ask` reads its chat provider and model from the config'); });
-        const setup = await prepareAsk({ siteDirectory: subcommand, configFile, model: values['--model'], passages: values['--passages'] === undefined ? undefined : Number(values['--passages']), channel: values['--channel'], version: values['--version'], language: values['--language'], noRerank: switches.has('--no-rerank'), noDirect: switches.has('--no-direct'), noEscalate: switches.has('--no-escalate'), noCards: switches.has('--no-cards'), readerView: parseReaderView(views) });
+        const setup = await prepareAsk({ siteDirectory: subcommand, configFile, model: values['--model'], passages: values['--passages'] === undefined ? undefined : Number(values['--passages']), product: values['--product'], channel: values['--channel'], version: values['--version'], language: values['--language'], noRerank: switches.has('--no-rerank'), noDirect: switches.has('--no-direct'), noEscalate: switches.has('--no-escalate'), noCards: switches.has('--no-cards'), readerView: parseReaderView(views) });
         for (const note of setup.notes)
             process.stderr.write(`${note}\n`);
         const chat = setup.chat;
@@ -544,7 +552,7 @@ try {
         }
     }
     else if (command === 'answers') {
-        const usage = 'Usage: shoalrun answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]...';
+        const usage = 'Usage: shoalrun answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--product P --channel C --version V --language L] [--reader-view FACET=CHOICE[,CHOICE]]...';
         if (!subcommand || subcommand.startsWith('--'))
             throw new Error(usage);
         const values = {};
@@ -556,7 +564,7 @@ try {
                 views.push(value);
                 continue;
             }
-            if (!['--questions', '--config', '--model'].includes(flag) || !value || value.startsWith('--'))
+            if (!['--questions', '--config', '--model', '--product', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--'))
                 throw new Error(usage);
             if (values[flag] !== undefined)
                 throw new Error(`Duplicate answers option ${flag}`);
@@ -567,7 +575,7 @@ try {
         const configFile = values['--config'] ?? await discoverConfig(process.cwd()).catch(() => { throw new Error('No docs.config.yaml found; pass --config FILE. `answers` reads its chat provider and model from the config'); });
         const questions = parseCardQuestions(await readFile(values['--questions'], 'utf8'));
         // Cards are polished answers, so they come from the model, not from a direct excerpt, and never from another card.
-        const setup = await prepareAsk({ siteDirectory: subcommand, configFile, model: values['--model'], noCards: true, noDirect: true, readerView: parseReaderView(views) });
+        const setup = await prepareAsk({ siteDirectory: subcommand, configFile, model: values['--model'], product: values['--product'], channel: values['--channel'], version: values['--version'], language: values['--language'], noCards: true, noDirect: true, readerView: parseReaderView(views) });
         for (const note of setup.notes)
             process.stderr.write(`${note}\n`);
         if (!setup.embedTexts || !setup.embedding)
@@ -620,7 +628,7 @@ try {
             if ((!flag?.startsWith('--') && flag !== '-n') || !value || value.startsWith('--'))
                 throw new Error(`Scaffold option ${flag ?? ''} needs a value`);
             const name = flag === '-n' ? 'new' : flag.slice(2);
-            if (!['new', 'config', 'id', 'title', 'summary', 'slug', 'channel', 'version', 'language', 'operation'].includes(name))
+            if (!['new', 'config', 'id', 'title', 'summary', 'slug', 'product', 'channel', 'version', 'language', 'operation'].includes(name))
                 throw new Error(`Unknown scaffold option ${flag}`);
             if (name === 'operation')
                 operations.push(value);
@@ -631,7 +639,7 @@ try {
         }
         if (shortForm && !options.new)
             throw new Error('Scaffold needs -n or --new with a target file');
-        const overrides = { id: options.id, title: options.title, summary: options.summary, slug: options.slug, channel: options.channel, version: options.version, language: options.language, ...(operations.length ? { operations } : {}) };
+        const overrides = { id: options.id, title: options.title, summary: options.summary, slug: options.slug, product: options.product, channel: options.channel, version: options.version, language: options.language, ...(operations.length ? { operations } : {}) };
         const result = shortForm
             ? await scaffoldFromPath(options.config ?? await discoverConfig(process.cwd()), subcommand, options.new, Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined)))
             : await scaffold(rest[0], subcommand, rest[1], overrides);
@@ -691,9 +699,20 @@ try {
             process.exitCode = 1;
     }
     else if (command === 'api' && subcommand === 'select') {
-        if (!rest[0] || !rest[1] || rest[2] !== '--output' || !rest[3] || rest.length !== 4)
-            throw new Error('Usage: shoalrun api select <api-id> <config> --output <selection.yaml>');
-        const result = await selectApiReferences(rest[1], rest[0], rest[3]);
+        const usage = 'Usage: shoalrun api select <api-id> <config> --output FILE [--product P --channel C --version V --language L]';
+        if (!rest[0] || !rest[1])
+            throw new Error(usage);
+        const flags = {};
+        for (let i = 2; i < rest.length; i += 2) {
+            const flag = rest[i];
+            const value = rest[i + 1];
+            if (!['--output', '--product', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--') || flags[flag])
+                throw new Error(usage);
+            flags[flag] = value;
+        }
+        if (!flags['--output'])
+            throw new Error(usage);
+        const result = await selectApiReferences(rest[1], rest[0], flags['--output'], { product: flags['--product'], channel: flags['--channel'], version: flags['--version'], language: flags['--language'] });
         process.stdout.write(JSON.stringify({ status: 'ok', ...result }, null, 2) + '\n');
     }
     else if (command === 'api' && subcommand === 'materialize') {
@@ -710,12 +729,18 @@ try {
                 continue;
             }
             const value = rest[++index];
-            if (!['--operation', '--route', '--output'].includes(flag) || !value || value.startsWith('--'))
+            if (!['--operation', '--route', '--output', '--product', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--'))
                 throw new Error(usage);
             if (flag === '--operation')
                 options.operations.push(value);
             else if (flag === '--route')
                 options.routes.push(value);
+            else if (flag !== '--output') {
+                const key = flag.slice(2);
+                if (options[key])
+                    throw new Error(`Duplicate ${flag}`);
+                options[key] = value;
+            }
             else if (options.output)
                 throw new Error('Duplicate --output');
             else
@@ -725,7 +750,7 @@ try {
         process.stdout.write(JSON.stringify({ status: 'ok', ...result }, null, 2) + '\n');
     }
     else if (command === 'operation' && subcommand === 'inspect') {
-        const usage = 'Usage: shoalrun operation inspect <id> [config] [--channel C] [--version V] [--language L]';
+        const usage = 'Usage: shoalrun operation inspect <id> [config] [--product P] [--channel C] [--version V] [--language L]';
         if (!rest[0] || rest[0].startsWith('--'))
             throw new Error(usage);
         const hasConfig = rest[1] !== undefined && !rest[1].startsWith('--');
@@ -734,7 +759,7 @@ try {
             const flag = rest[index];
             const value = rest[index + 1];
             const name = flag.slice(2);
-            if (!['--channel', '--version', '--language'].includes(flag))
+            if (!['--product', '--channel', '--version', '--language'].includes(flag))
                 throw new Error(`Unknown operation inspect option ${flag}`);
             if (!value || value.startsWith('--'))
                 throw new Error(`Operation inspect option ${flag} needs a value`);
@@ -743,11 +768,11 @@ try {
             filters[name] = value;
         }
         const manifest = await compile(hasConfig ? rest[1] : 'docs.config.yaml');
-        const matches = (manifest.operations[rest[0]] ?? []).filter(item => (!filters.channel || item.channel === filters.channel) && (!filters.version || item.version === filters.version) && (!filters.language || item.language === filters.language));
+        const matches = (manifest.operations[rest[0]] ?? []).filter(item => (!filters.product || item.product === filters.product) && (!filters.channel || item.channel === filters.channel) && (!filters.version || item.version === filters.version) && (!filters.language || item.language === filters.language));
         process.stdout.write(JSON.stringify({ status: matches.length ? 'ok' : 'missing-variant', operationId: rest[0], bindings: matches }, null, 2) + '\n');
     }
     else {
-        throw new Error('Usage: shoalrun init [directory] [--starter minimal|api-docs|showcase] | build [config] [output] [--source-commit SHA] [--release-label LABEL] | check [config] [--json] | audit [config] | vercel build [config] [output] [--source-commit SHA] [--release-label LABEL] [--chat] | serve <site-directory> [--host HOST] [--port PORT] [--search [--config FILE]] [--ask [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]...] | search <site-directory> <query> [--channel C --version V --language L --limit N] | answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]... | chat pause|resume|status --config FILE | ask-log <log-file> [--min-repeats N] [--limit N] [--cards-out FILE] [--json] | ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json] | eval prepare <site-directory> --tasks FILE --out REPORT | eval check <site-directory> --tasks FILE --report REPORT | index <site-directory> [--embed [--config FILE] [--provider voyage|openai] [--model MODEL] [--dimension N] [--base-url URL] [--key-env NAME]] | ingredient draft --spec FILE --out FILE [--config FILE] [--check] | recipe draft --spec FILE --out FILE [--config FILE] [--check] | scaffold <template> -n <target> [--config FILE] [--id ID] [--title TITLE] [--summary SUMMARY] [--slug SLUG] [--channel C] [--version V] [--language L] [--operation ID]... | scaffold <template> <config> <target> --id ID --title TITLE --summary SUMMARY --slug SLUG | config validate|resolve|graph <config> | config explain <key> <config> | operation inspect <id> <config> [--channel C --version V --language L] | api audit <openapi-file> | api focused-audit <site-directory> | api review <config-file> --output <local-directory> | api select <api-id> <config> --output <selection.yaml> | api materialize <api-id> <config> (--all | --operation ID | --route "METHOD /path")... [--output content/subdirectory]');
+        throw new Error('Usage: shoalrun init [directory] [--starter minimal|api-docs|showcase] | build [config] [output] [--source-commit SHA] [--release-label LABEL] | check [config] [--json] | audit [config] | vercel build [config] [output] [--source-commit SHA] [--release-label LABEL] [--chat] | serve <site-directory> [--host HOST] [--port PORT] [--search [--config FILE]] [--ask [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]...] | search <site-directory> <query> [--product P] [--channel C --version V --language L --limit N] | answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]... | chat pause|resume|status --config FILE | ask-log <log-file> [--min-repeats N] [--limit N] [--cards-out FILE] [--json] | ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--product P] [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json] | eval prepare <site-directory> --tasks FILE --out REPORT | eval check <site-directory> --tasks FILE --report REPORT | index <site-directory> [--embed [--config FILE] [--provider voyage|openai] [--model MODEL] [--dimension N] [--base-url URL] [--key-env NAME]] | ingredient draft --spec FILE --out FILE [--config FILE] [--check] | recipe draft --spec FILE --out FILE [--config FILE] [--check] | scaffold <template> -n <target> [--config FILE] [--id ID] [--title TITLE] [--summary SUMMARY] [--slug SLUG] [--product P] [--channel C] [--version V] [--language L] [--operation ID]... | scaffold <template> <config> <target> --id ID --title TITLE --summary SUMMARY --slug SLUG | config validate|resolve|graph <config> | config explain <key> <config> | operation inspect <id> <config> [--product P] [--channel C --version V --language L] | api audit <openapi-file> | api focused-audit <site-directory> | api review <config-file> --output <local-directory> | api select <api-id> <config> --output <selection.yaml> | api materialize <api-id> <config> (--all | --operation ID | --route "METHOD /path")... [--output content/subdirectory]');
     }
 }
 catch (error) {

package/dist/compiler-config.d.ts

@@ -39,6 +39,14 @@ export interface CompilerSiteConfig extends ConfigMapping {
     basePath?: unknown;
     contentDir?: string;
 }
+export type ProductPublicationConfig = {
+    label?: string;
+    pathPrefix: string;
+    defaultVersion: string;
+    versions: Record<string, {
+        pathPrefix?: string;
+    }>;
+};
 export interface CompilerPublicationsConfig extends ConfigMapping {
     channels: Record<string, {
         pathPrefix?: string;
@@ -46,7 +54,9 @@ export interface CompilerPublicationsConfig extends ConfigMapping {
     versions: Record<string, {
         pathPrefix?: string;
     }>;
+    products?: Record<string, ProductPublicationConfig>;
     defaults?: {
+        product?: string;
         channel?: string;
         version?: string;
         language?: string;
@@ -66,3 +76,10 @@ export declare function navigationCounts(outputs: unknown): boolean;
  */
 export declare function requireSiteSection(config: ResolvedCompilerConfig): CompilerSiteConfig;
 export declare function requirePublicationsSection(config: ResolvedCompilerConfig): CompilerPublicationsConfig;
+/** Resolve product-local defaults without borrowing another product's catalog. */
+export declare function resolvePublication(publications: CompilerPublicationsConfig, value: Record<string, unknown>, language?: string): {
+    product?: string;
+    channel: string;
+    version: string;
+    language: string;
+};

package/dist/compiler-config.js

@@ -58,12 +58,13 @@ export function requireSiteSection(config) {
 }
 export function requirePublicationsSection(config) {
     const publications = config.publications;
-    if (!isConfigMapping(publications) || !isConfigMapping(publications.channels) || !isConfigMapping(publications.versions)) {
+    if (!isConfigMapping(publications) || !isConfigMapping(publications.channels) || (publications.versions !== undefined && !isConfigMapping(publications.versions)) || (publications.versions === undefined && !isConfigMapping(publications.products))) {
         throw new Error('publications needs channels and versions mappings');
     }
     if (publications.defaults !== undefined && !isConfigMapping(publications.defaults)) {
         throw new Error('publications.defaults must be a mapping of channel, version, and language');
     }
+    publications.versions ??= {};
     for (const group of ['channels', 'versions']) {
         for (const [name, value] of Object.entries(publications[group])) {
             if (!isConfigMapping(value) || (value.pathPrefix !== undefined && typeof value.pathPrefix !== 'string')) {
@@ -72,8 +73,48 @@ export function requirePublicationsSection(config) {
         }
     }
     const defaults = publications.defaults;
-    if (isConfigMapping(defaults) && ['channel', 'version', 'language'].some(key => defaults[key] !== undefined && typeof defaults[key] !== 'string')) {
+    if (isConfigMapping(defaults) && ['product', 'channel', 'version', 'language'].some(key => defaults[key] !== undefined && typeof defaults[key] !== 'string')) {
         throw new Error('publications.defaults must be a mapping of channel, version, and language');
     }
+    if (publications.products !== undefined) {
+        if (!isConfigMapping(publications.products) || !Object.keys(publications.products).length)
+            throw new Error('publications.products must be a nonempty mapping');
+        const prefixes = new Set();
+        for (const [id, product] of Object.entries(publications.products)) {
+            if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id) || !isConfigMapping(product) || Object.keys(product).some(key => !['label', 'pathPrefix', 'defaultVersion', 'versions'].includes(key)))
+                throw new Error(`Invalid publication product ${id}`);
+            if (typeof product.pathPrefix !== 'string' || !/^\/[A-Za-z0-9/_-]+$/.test(product.pathPrefix) || product.pathPrefix.endsWith('/') || product.pathPrefix.includes('//') || product.pathPrefix.includes('..'))
+                throw new Error(`Product ${id} needs an absolute nonempty pathPrefix without a trailing slash`);
+            if (prefixes.has(product.pathPrefix.toLowerCase()))
+                throw new Error(`Duplicate product pathPrefix ${product.pathPrefix}`);
+            prefixes.add(product.pathPrefix.toLowerCase());
+            if (product.label !== undefined && (typeof product.label !== 'string' || !product.label.trim()))
+                throw new Error(`Product ${id}.label must be nonempty text`);
+            if (!isConfigMapping(product.versions) || !Object.keys(product.versions).length || typeof product.defaultVersion !== 'string' || !Object.hasOwn(product.versions, product.defaultVersion))
+                throw new Error(`Product ${id} needs versions and a valid defaultVersion`);
+            const versionPrefixes = new Set();
+            for (const [version, definition] of Object.entries(product.versions)) {
+                if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(version) || !isConfigMapping(definition) || (definition.pathPrefix !== undefined && (typeof definition.pathPrefix !== 'string' || (definition.pathPrefix !== '' && (!/^\/[A-Za-z0-9/_-]+$/.test(definition.pathPrefix) || definition.pathPrefix.includes('//') || definition.pathPrefix.endsWith('/'))))))
+                    throw new Error(`Product ${id} has invalid version ${version}`);
+                const prefix = String(definition.pathPrefix ?? '').toLowerCase();
+                if (versionPrefixes.has(prefix))
+                    throw new Error(`Product ${id} has duplicate version pathPrefix ${prefix || '(empty)'}`);
+                versionPrefixes.add(prefix);
+            }
+        }
+    }
     return publications;
 }
+/** Resolve product-local defaults without borrowing another product's catalog. */
+export function resolvePublication(publications, value, language = 'en') {
+    const product = value.product;
+    if (product !== undefined && (typeof product !== 'string' || !publications.products || !Object.hasOwn(publications.products, product)))
+        throw new Error(`Unknown publication product ${String(product)}`);
+    const catalog = product === undefined ? publications.versions ?? {} : publications.products[product].versions;
+    const scopedDefault = product !== undefined && publications.defaults?.product === product && publications.defaults.version && Object.hasOwn(catalog, publications.defaults.version) ? publications.defaults.version : undefined;
+    const version = value.version ?? (product === undefined ? publications.defaults?.version : scopedDefault ?? publications.products[product].defaultVersion);
+    const channel = value.channel ?? publications.defaults?.channel;
+    if (typeof channel !== 'string' || !Object.hasOwn(publications.channels, channel) || typeof version !== 'string' || !Object.hasOwn(catalog, version) || (value.language !== undefined && (typeof value.language !== 'string' || !value.language)))
+        throw new Error(`Unknown publication ${product === undefined ? '' : String(product) + '/'}${String(channel)}/${String(version)}`);
+    return { ...(product === undefined ? {} : { product: product }), channel, version, language: value.language ?? language };
+}

package/dist/compiler.d.ts

@@ -11,6 +11,7 @@ export declare function compile(configFile: string, destination?: string, proven
     sourceOverrides?: ReadonlyMap<string, string>;
     authoringFiles?: ReadonlySet<string>;
     profile?: string;
+    onDependency?: (file: string) => void;
 }): Promise<{
     authoringSources?: {
         id: string;
@@ -93,6 +94,10 @@ export declare function compile(configFile: string, destination?: string, proven
             url?: string;
         }[];
         verified?: string | undefined;
+        availability?: {
+            since?: string;
+            through?: string;
+        } | undefined;
         updated?: string | undefined;
         indexable: boolean;
         navigationTab: {
@@ -158,6 +163,10 @@ export declare function compile(configFile: string, destination?: string, proven
             url?: string;
         }[];
         verified?: string | undefined;
+        availability?: {
+            since?: string;
+            through?: string;
+        } | undefined;
         updated?: string | undefined;
         indexable: boolean;
         navigationTab?: undefined;
@@ -176,6 +185,7 @@ export declare function compile(configFile: string, destination?: string, proven
     operations: Record<string, {
         id: string;
         type: string;
+        product?: string;
         channel: string;
         version: string;
         language: string;
@@ -195,6 +205,7 @@ export declare function compile(configFile: string, destination?: string, proven
     }[];
     apiSources: {
         apiId: string;
+        product?: string;
         channel: string;
         version: string;
         endpoint: string | null;
@@ -216,6 +227,16 @@ export declare function compile(configFile: string, destination?: string, proven
     sitemap?: string | undefined;
     basePath: string;
     searchSynonyms?: unknown[] | undefined;
+    publications?: {
+        enabled: Variant[];
+        products: {
+            [k: string]: {
+                versions: string[];
+                defaultVersion?: string | undefined;
+                label?: string | undefined;
+            };
+        };
+    } | undefined;
     schemaVersion: number;
     configDigest: string;
 }>;

package/dist/compiler.js

@@ -1,3 +1,4 @@
+import { documentKey, publicationKey, samePublication } from './publication-identity.js';
 import { validateHeader, validateFooter } from './site-identity.js';
 import { profileSelection } from './deployment-profile.js';
 import { profileNavigation } from './project-navigation.js';
@@ -43,14 +44,14 @@ import { assembleArtifacts } from './artifact-bundle.js';
 import { materializePages } from './page-materialization.js';
 import { renderPublicationPages } from './publication-render.js';
 import { buildPublicationManifest } from './publication-manifest.js';
-import { configField, isConfigMapping, requirePublicationsSection, requireSiteSection, resolvedCompilerConfig } from './compiler-config.js';
+import { configField, isConfigMapping, requirePublicationsSection, resolvePublication, requireSiteSection, resolvedCompilerConfig } from './compiler-config.js';
 import { validateRetrieval } from './retrieval-config.js';
 import { validateChat } from './chat-config.js';
 import { normalizeBasePath, sitePath } from './site-path.js';
 const generatedReferenceBody = 'This reference is generated from the OpenAPI description. It shows the operation contract; follow any related guides below for task steps and context.\n';
 const generatedWebhookBody = 'This webhook reference is generated from the OpenAPI description. The provider sends this event to the receiver.\n';
 const digest = (value) => createHash('sha256').update(value).digest('hex');
-const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+const keyFor = documentKey;
 function validateSearch(value, declaringFile) {
     if (value === undefined)
         return { provider: 'lexical', module: builtInSearchProvider, index: true };
@@ -101,7 +102,7 @@ export async function checkThemeContrast(configFile) {
     return { modes, palette: palette.name };
 }
 export async function compile(configFile, destination, provenance = {}, options = {}) {
-    const loaded = await loadConfig(configFile, { profile: options.profile });
+    const loaded = await loadConfig(configFile, { profile: options.profile, onDependency: options.onDependency });
     const componentPlugins = await loadComponentPlugins(loaded);
     const provenanceRecord = buildInfo(loaded.digest, provenance);
     const resolvedConfig = resolvedCompilerConfig(loaded.value);
@@ -215,10 +216,12 @@ export async function compile(configFile, destination, provenance = {}, options
     if (!Array.isArray(enabledVariants))
         throw new Error('publications.enabled must declare at least one variant');
     const variants = enabledVariants.map((variant) => {
-        if (!isConfigMapping(variant) || typeof variant.channel !== 'string' || typeof variant.version !== 'string' || (variant.language !== undefined && typeof variant.language !== 'string'))
-            throw new Error('publications.enabled needs channel, version, and optional language');
-        return { ...variant, channel: variant.channel, version: variant.version, language: variant.language ?? language };
+        if (!isConfigMapping(variant))
+            throw new Error('publications.enabled needs publication coordinates');
+        return resolvePublication(config.publications, variant, language);
     });
+    if (new Set(variants.map(publicationKey)).size !== variants.length)
+        throw new Error('publications.enabled has duplicate publication coordinates');
     if (!variants.length)
         throw new Error('publications.enabled must declare at least one variant');
     const externalSites = config.publications.externalSites ?? [];
@@ -263,7 +266,7 @@ export async function compile(configFile, destination, provenance = {}, options
             const document = isConfigMapping(rawDocument) ? rawDocument : {};
             const rawVariant = document.variant;
             const route = document.url;
-            if (typeof document.id !== 'string' || !document.id || !isConfigMapping(rawVariant) || ['channel', 'version', 'language'].some(field => typeof rawVariant[field] !== 'string' || !rawVariant[field]) || typeof route !== 'string' || !route.startsWith('/') || route.startsWith('//') || route.includes('..') || /[?#\\]|%2f|%5c/i.test(route)) {
+            if (typeof document.id !== 'string' || !document.id || !isConfigMapping(rawVariant) || (rawVariant.product !== undefined && (typeof rawVariant.product !== 'string' || !rawVariant.product)) || ['channel', 'version', 'language'].some(field => typeof rawVariant[field] !== 'string' || !rawVariant[field]) || typeof route !== 'string' || !route.startsWith('/') || route.startsWith('//') || route.includes('..') || /[?#\\]|%2f|%5c/i.test(route)) {
                 throw new Error(`${setting}.manifest has an invalid document identity, publication, or URL`);
             }
             const variant = rawVariant;
@@ -283,8 +286,8 @@ export async function compile(configFile, destination, provenance = {}, options
     if (editionBadge !== 'auto' && editionBadge !== 'always' && editionBadge !== 'never')
         throw new Error('site.editionBadge must be auto, always, or never');
     const varying = (field) => new Set(variants.map(variant => variant[field])).size > 1;
-    const editionLabel = (variant) => editionBadge === 'never' ? '' : ['channel', 'version', 'language']
-        .filter(field => editionBadge === 'always' || varying(field)).map(field => variant[field]).join(' · ');
+    const editionLabel = (variant) => editionBadge === 'never' ? '' : ['product', 'channel', 'version', 'language']
+        .filter(field => variant[field] !== undefined && (editionBadge === 'always' || varying(field))).map(field => variant[field]).join(' · ');
     const { docs, knownDocumentIds, knownDocumentTypes, routeOwners, contentDir, snippets, apiPlan, api, sourceForVariant, knownOperations, relatedApiTargets, guidesByApi, sourceForOperation } = await prepareContentWorkspace({
         base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies,
         sourceOverrides: options.sourceOverrides, authoringFiles: options.authoringFiles
@@ -390,7 +393,7 @@ export async function compile(configFile, destination, provenance = {}, options
     ] : [];
     for (const [operationId, bindings] of Object.entries(operations)) {
         for (const variant of variants) {
-            const inVariant = bindings.filter(b => b.channel === variant.channel && b.version === variant.version && b.language === variant.language);
+            const inVariant = bindings.filter(b => samePublication(b, variant));
             if (inVariant.filter(b => b.type === 'api-reference').length > 1)
                 throw new Error(`Multiple canonical references for ${operationId}`);
         }
@@ -414,7 +417,7 @@ export async function compile(configFile, destination, provenance = {}, options
         const to = rule.to;
         if (!isConfigMapping(to) || typeof to.doc !== 'string' || !to.doc || typeof to.channel !== 'string' || !to.channel || typeof to.version !== 'string' || !to.version || typeof to.language !== 'string' || !to.language)
             throw new Error(`Redirect ${rule.from} needs an explicit target variant`);
-        const target = docs.get(keyFor(to.doc, { channel: to.channel, version: to.version, language: to.language }));
+        const target = docs.get(keyFor(to.doc, { channel: to.channel, version: to.version, language: to.language, ...(to.product === undefined ? {} : { product: String(to.product) }) }));
         if (!target)
             throw new Error(`Redirect ${rule.from} targets missing document variant`);
         const status = rule.status ?? 308;
@@ -423,7 +426,7 @@ export async function compile(configFile, destination, provenance = {}, options
         // The old page's Markdown twin moves too, so its .md URL redirects to the target's twin.
         redirects.push({ from: sourceRoute, to: target.route, markdownFrom: markdownRoute(sourceRoute.replace(/(.)\/+$/, '$1'), basePath), markdownTo: target.markdownRoute, status });
     }
-    const apiSources = [...apiPublications.values()].map(({ apiId, variant, endpoint, referenceUrl, sourceUrl, mediaType }) => ({ apiId, channel: variant.channel, version: variant.version, endpoint: endpoint ?? null, referenceUrl, sourceUrl, mediaType }));
+    const apiSources = [...apiPublications.values()].map(({ apiId, variant, endpoint, referenceUrl, sourceUrl, mediaType }) => ({ apiId, ...(variant.product === undefined ? {} : { product: variant.product }), channel: variant.channel, version: variant.version, endpoint: endpoint ?? null, referenceUrl, sourceUrl, mediaType }));
     let catalog = null;
     const discoverable = apiSources.filter(item => item.endpoint);
     if (discoverable.length) {
@@ -442,6 +445,7 @@ export async function compile(configFile, destination, provenance = {}, options
     const manifestDependencies = [...new Set([...loaded.dependencies, ...componentPlugins.dependencies, ...externalManifestFiles, ...api.dependencies, ...(metadataProvider ? [metadataProvider.module] : []), ...metadataDependencies, ...(highlighter.dependency ? [highlighter.dependency] : []), ...styleFiles, ...(themeStyleFile ? [themeStyleFile] : []), ...palette.files, ...(search.module ? [search.module] : []), ...previewFiles, ...(customStyleFile ? [customStyleFile] : []), ...(customReaderModule ? [customReaderModule] : []), ...(analyticsModule ? [analyticsModule] : []), ...(mcpAnalyticsModule ? [mcpAnalyticsModule] : []), ...(shareImages.template ? [shareImages.template] : []), ...shareImages.fonts, ...(faviconFile ? [faviconFile] : []), ...heroImages.values(), ...walkthroughSources, ...fontFiles, ...fonts.faces.map(face => face.file), ...scriptFiles, iconLicenseFile, ...[...snippets.values()].map(s => s.file), ...[...docs.values()].map(d => d.file)])].sort();
     const llmsDiscovery = resolveLlmsDiscovery(configField(config.outputs, 'llms'));
     const { manifest, headers, sitemaps } = buildPublicationManifest({
+        configPublications: config.publications,
         fictionalDocuments: new Set(rendered.filter(({ doc }) => fictionalDocument(doc, llmsDiscovery)).map(({ doc }) => doc)),
         configDigest: loaded.digest, synonyms, basePath, publicPath, readerFilters, taxonomy: resolveTaxonomy(configField(config.frontmatter, 'taxonomy')), dependencies: manifestDependencies,
         rendered, resolvedNavigation, cardUses, snippetUses, apiEmbedUses, focusedContracts, operations,

package/dist/component-transform.d.ts

@@ -1,10 +1,8 @@
+import type { CompilerPublicationsConfig } from './compiler-config.js';
 import { type ComponentRegistry } from './component-plugins.js';
 import { type CalloutTypes } from './callouts.js';
 import { type BadgeVariants } from './badges.js';
 import { SnippetDefinition, SnippetUse } from './snippets.js';
 import { type ReaderFiltersConfig } from './reader-filters.js';
 import type { Document } from './content-source.js';
-export declare function transformMdx(tree: unknown, current: Document, registry: Map<string, Document>, snippets?: Map<string, SnippetDefinition>, projectValues?: Record<string, unknown>, uses?: SnippetUse[], calloutTypes?: CalloutTypes, projectRoot?: string, readerConfig?: ReaderFiltersConfig, frontmatterConfig?: unknown, publicationConfig?: {
-    channels: Record<string, unknown>;
-    versions: Record<string, unknown>;
-}, badgeVariants?: BadgeVariants, componentPlugins?: ComponentRegistry): unknown;
+export declare function transformMdx(tree: unknown, current: Document, registry: Map<string, Document>, snippets?: Map<string, SnippetDefinition>, projectValues?: Record<string, unknown>, uses?: SnippetUse[], calloutTypes?: CalloutTypes, projectRoot?: string, readerConfig?: ReaderFiltersConfig, frontmatterConfig?: unknown, publicationConfig?: CompilerPublicationsConfig, badgeVariants?: BadgeVariants, componentPlugins?: ComponentRegistry, publicationRegistry?: Map<string, Document>): unknown;

package/dist/component-transform.js

@@ -1,3 +1,4 @@
+import { documentKey } from './publication-identity.js';
 import { pruneFeatureTree } from './deployment-profile.js';
 import { lowerComponent } from './component-plugins.js';
 import { cardComponent } from './cards.js';
@@ -57,7 +58,7 @@ function isMdxAttribute(value) {
 function literalAttributes(attributes) {
     return attributes.every(item => item.type === 'mdxJsxAttribute' && typeof item.value === 'string');
 }
-export function transformMdx(tree, current, registry, snippets = new Map(), projectValues = {}, uses = [], calloutTypes = resolveCalloutTypes(undefined, current.file), projectRoot, readerConfig, frontmatterConfig = {}, publicationConfig, badgeVariants = resolveBadgeVariants(undefined, current.file), componentPlugins = new Map()) {
+export function transformMdx(tree, current, registry, snippets = new Map(), projectValues = {}, uses = [], calloutTypes = resolveCalloutTypes(undefined, current.file), projectRoot, readerConfig, frontmatterConfig = {}, publicationConfig, badgeVariants = resolveBadgeVariants(undefined, current.file), componentPlugins = new Map(), publicationRegistry) {
     if (!isMdxRoot(tree))
         throw new Error(`${current.file}: parsed content must be a root with children`);
     tree = lowerSectionMarkers(pruneFeatureTree(tree, current.featureContext, current.file), current.file);
@@ -138,14 +139,18 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
             }
             if (node.name === 'ForPublication') {
                 const attributes = node.attributes ?? [];
-                const allowed = ['channel', 'version', 'language'];
+                const allowed = ['product', 'channel', 'version', 'language'];
                 if (node.type !== 'mdxJsxFlowElement' || !node.children?.length || !attributes.length || !literalAttributes(attributes) || attributes.some((item) => !allowed.includes(item.name) || !item.value.trim()) || new Set(attributes.map((item) => item.name)).size !== attributes.length) {
                     throw new Error(`${sourceFile}: <ForPublication> needs block content and distinct literal channel, version, or language attributes`);
                 }
-                for (const item of attributes)
-                    if ((item.name === 'channel' || item.name === 'version') && publicationConfig && !Object.hasOwn(publicationConfig[item.name === 'channel' ? 'channels' : 'versions'], item.value)) {
+                const product = attributes.find(item => item.name === 'product')?.value ?? current.variant.product;
+                for (const item of attributes) {
+                    const catalog = item.name === 'product' ? publicationConfig?.products
+                        : item.name === 'channel' ? publicationConfig?.channels
+                            : item.name === 'version' ? (product ? publicationConfig?.products?.[product]?.versions : publicationConfig?.versions) : undefined;
+                    if (publicationConfig && item.name !== 'language' && (!catalog || !Object.hasOwn(catalog, item.value)))
                         throw new Error(`${sourceFile}: <ForPublication> names unknown ${item.name} ${item.value}`);
-                    }
+                }
                 if (attributes.some((item) => current.variant[item.name] !== item.value))
                     return [];
                 return childrenOf(node.children, scope, stack, sourceFile);
@@ -635,9 +640,17 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
                 return text(String(scope[name]));
             }
             if (node.name === 'DocLink') {
-                const target = registry.get(attr(node, 'doc'));
+                const attributes = node.attributes ?? [];
+                if (!literalAttributes(attributes) || attributes.some(item => !['doc', 'product', 'channel', 'version', 'language'].includes(item.name)) || new Set(attributes.map(item => item.name)).size !== attributes.length)
+                    throw new Error(`${sourceFile}: DocLink needs distinct literal publication attributes`);
+                const id = attr(node, 'doc');
+                const qualified = attributes.some(item => item.name !== 'doc');
+                if (qualified && attributes.some(item => item.name === 'product' && item.value !== current.variant.product) && !attributes.some(item => item.name === 'version'))
+                    throw new Error(`${sourceFile}: cross-product DocLink needs an explicit version`);
+                const variant = { ...current.variant, ...Object.fromEntries(attributes.filter(item => item.name !== 'doc').map(item => [item.name, item.value])) };
+                const target = qualified ? publicationRegistry?.get(documentKey(id, variant)) : registry.get(id);
                 if (!target)
-                    throw new Error(`${sourceFile}: unknown DocLink target`);
+                    throw new Error(`${sourceFile}: unknown DocLink target ${id} in selected publication`);
                 return link(target.route, (node.children ?? []).map((x) => x.value ?? '').join('') || target.frontmatter.title);
             }
             if (node.name === 'Callout') {

package/dist/config.d.ts

@@ -10,6 +10,7 @@ export declare class ConfigError extends Error {
 }
 export declare function loadConfig(file: string, options?: {
     profile?: string;
+    onDependency?: (file: string) => void;
 }): Promise<{
     value: Record<string, unknown>;
     tree: Tree;

package/dist/config.js

@@ -68,6 +68,7 @@ export async function loadConfig(file, options = {}) {
         if (stack.includes(current))
             throw new ConfigError(`Configuration cycle: ${[...stack, current].join(' -> ')}`);
         dependencies.add(current);
+        options.onDependency?.(current);
         const raw = await readFile(current, 'utf8');
         let parsed;
         try {
@@ -121,7 +122,7 @@ export async function loadConfig(file, options = {}) {
     const raw = value;
     const profileSettings = treeObject(tree.value) ? tree.value.profiles : undefined;
     const manifestNode = profileSettings && treeObject(profileSettings.value) ? profileSettings.value.manifest : undefined;
-    const deployment = await resolveDeploymentProfile(raw.profiles, raw, manifestNode?.source.file ?? root, options.profile);
+    const deployment = await resolveDeploymentProfile(raw.profiles, raw, manifestNode?.source.file ?? root, options.profile, options.onDependency);
     if (deployment) {
         for (const file of deployment.dependencies)
             dependencies.add(file);

package/dist/content-delivery-contract.d.ts

@@ -3,6 +3,7 @@ export type ContentPublication = {
     channel: string;
     version: string;
     language: string;
+    product?: string;
 };
 export type ContentFormat = 'html' | 'markdown';
 export type ContentRef = {
@@ -62,7 +63,7 @@ export type ContentResource = {
     }>;
 };
 export type ContentManifest = {
-    schemaVersion: 1;
+    schemaVersion: 1 | 2;
     kind: 'shoalrun-content-export';
     digest: string;
     publicBase: string;

package/dist/content-delivery-validation.d.ts

@@ -1,6 +1,6 @@
-import type { ContentManifest, ContentRef } from './content-delivery-contract.js';
+import type { ContentManifest, ContentRef, ContentPublication } from './content-delivery-contract.js';
 export declare const safeContentPath: (value: any) => value is string;
-export declare const validContentPublication: (value: any) => boolean;
+export declare const validContentPublication: (value: any) => value is ContentPublication;
 export declare function validContentRef(value: any): value is ContentRef;
 export declare function validateContentManifest(value: any, maxResources?: number, maxResourceBytes?: number): asserts value is ContentManifest;
 /** Shared metadata validation; transport supplies its file/asset inventory policy. */