@shoalrun/cli 0.1.0-alpha.16 → 0.1.0-alpha.18

package/assets/ask-widget.js

@@ -114,14 +114,28 @@
       if (current?.item && (indent > current.indent || code && current.item.textContent.replace(/\[\d+\]/g, '').trim().endsWith(':'))) current.item.append(node);
       else { lists.length = 0; parent.append(node); }
     };
-    for (const part of text.split(/((?:^[ \t]*)?```[\s\S]*?```)/m)) {
-      if (!part.trim()) continue;
-      if (part.trimStart().startsWith('```')) {
-        const indent = indentOf(part);
-        let code = part.replace(/^[ \t]*```[^\n]*\n?/, '').replace(/\n?[ \t]*```$/, '');
-        if (indent) code = code.replace(new RegExp('^ {0,' + indent + '}', 'gm'), '');
+    // A shorter fence inside an example is literal code, not its closing fence.
+    const parts = [];
+    const openings = /^([ \t]*)(`{3,}|~{3,})[^\n]*\n/gm;
+    let cursor = 0, opening;
+    while ((opening = openings.exec(text))) {
+      const closing = new RegExp('^[ \\t]*' + opening[2][0] + '{' + opening[2].length + ',}[ \\t]*\\r?$', 'gm');
+      closing.lastIndex = openings.lastIndex;
+      const end = closing.exec(text);
+      parts.push({ text: text.slice(cursor, opening.index) });
+      parts.push({ code: text.slice(openings.lastIndex, end ? end.index : text.length).replace(/\r?\n$/, ''), indent: indentOf(opening[1]) });
+      cursor = end ? closing.lastIndex : text.length;
+      openings.lastIndex = cursor;
+    }
+    parts.push({ text: text.slice(cursor) });
+    for (const blockPart of parts) {
+      if (blockPart.code !== undefined) {
+        const { indent } = blockPart;
+        const code = indent ? blockPart.code.replace(new RegExp('^ {0,' + indent + '}', 'gm'), '') : blockPart.code;
         appendBlock(el('pre', {}, el('code', { text: code })), indent, true); continue;
       }
+      const part = blockPart.text;
+      if (!part.trim()) continue;
       for (const block of part.split(/\n{2,}/)) {
         const heading = /^(#{1,6})\s+(.+)$/.exec(block.trim());
         if (heading && !block.trim().includes('\n')) { const node = el(`h${Math.max(2, heading[1].length)}`); inline(node, heading[2], sources); appendBlock(node, indentOf(block)); continue; }

package/assets/navigation.js

@@ -1,4 +1,9 @@
 const navigation = document.querySelector('.side');
+for (const select of document.querySelectorAll('[data-publication-switcher]')) {
+  select.addEventListener('change', () => {
+    if (select.value) location.assign(select.value);
+  });
+}
 const tree = navigation?.querySelector('.nav-tree');
 const search = navigation?.querySelector('.nav-search');
 const filter = navigation?.querySelector('#nav-filter');

package/dist/ai-directory.d.ts

@@ -0,0 +1 @@
+export declare function aiDirectory(directory: string): Promise<string>;

package/dist/ai-directory.js

@@ -0,0 +1,12 @@
+import { mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+export async function aiDirectory(directory) {
+    const root = path.resolve(directory);
+    const target = path.join(root, 'ai');
+    await mkdir(target, { recursive: true });
+    const real = await realpath(root);
+    const inside = await realpath(target);
+    if (inside !== real && !inside.startsWith(real + path.sep))
+        throw new Error('The ai directory leaves the site directory');
+    return target;
+}

package/dist/answer-cards.js

@@ -2,7 +2,7 @@ import { readFile, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parse } from 'yaml';
 import { cacheable, normalizeQuestion } from './answer-cache.js';
-import { aiDirectory } from './index-build.js';
+import { aiDirectory } from './ai-directory.js';
 export const encodeVector = (vector) => Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength).toString('base64');
 export function decodeVector(value) {
     const bytes = Buffer.from(value, 'base64');

package/dist/api-materialize.d.ts

@@ -1,4 +1,5 @@
-export type MaterializeOptions = {
+import type { Variant } from './content.js';
+export type MaterializeOptions = Partial<Variant> & {
     all?: boolean;
     operations?: string[];
     routes?: string[];

package/dist/api-materialize.js

@@ -1,3 +1,5 @@
+import { resolvePublication } from './compiler-config.js';
+import { samePublication } from './publication-identity.js';
 import { mkdir, readFile, readdir, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import YAML from 'yaml';
@@ -30,7 +32,7 @@ function pageIdentity(source, file) {
     const data = YAML.parse(match[1]);
     if (!data || typeof data !== 'object')
         throw new Error(`${file}: invalid page frontmatter`);
-    return { id: data.id, operation: Array.isArray(data.operations) && data.operations.length === 1 ? data.operations[0] : undefined, channel: data.channel, version: data.version, language: data.language, publications: data.publications };
+    return { id: data.id, operation: Array.isArray(data.operations) && data.operations.length === 1 ? data.operations[0] : undefined, product: data.product, channel: data.channel, version: data.version, language: data.language, publications: data.publications };
 }
 function select(candidates, options) {
     const ids = options.operations ?? [];
@@ -63,16 +65,14 @@ export async function materializeApiPages(configFile, apiId, options) {
     const config = loaded.value;
     const root = path.dirname(path.resolve(configFile));
     const contentDir = await canonical(path.resolve(root, config.site?.contentDir ?? 'content'));
-    const directory = await canonical(options.output ? path.resolve(options.output) : path.join(contentDir, 'api', apiId));
+    const { candidates, publication } = await apiCandidates(configFile, apiId, options);
+    const defaultDirectory = publication.product ? path.join(contentDir, 'api', publication.product, publication.version, apiId) : path.join(contentDir, 'api', apiId);
+    const directory = await canonical(options.output ? path.resolve(options.output) : defaultDirectory);
     const relative = path.relative(contentDir, directory);
     if (relative.startsWith('..') || path.isAbsolute(relative))
         throw new Error(`MDX output must stay inside the content directory ${contentDir}`);
-    const { candidates } = await apiCandidates(configFile, apiId);
     const selected = select(candidates, options);
-    const defaults = config.publications?.defaults;
-    if (!defaults?.channel || !defaults?.version)
-        throw new Error('API page materialization needs publication defaults');
-    const language = defaults.language ?? defaultLanguage(config);
+    const language = publication.language;
     const existing = new Map();
     for (const file of await pageFiles(contentDir)) {
         const identity = pageIdentity(await readFile(file, 'utf8'), file);
@@ -86,7 +86,19 @@ export async function materializeApiPages(configFile, apiId, options) {
     const skipped = [];
     const targets = new Set();
     for (const item of selected) {
-        const matches = (existing.get(item.reference) ?? []).filter(page => (page.publications ? page.publications.some(publication => publication.channel === defaults.channel && publication.version === defaults.version) : (page.channel ?? defaults.channel) === defaults.channel && (page.version ?? defaults.version) === defaults.version) && (page.language ?? language) === language);
+        const matches = (existing.get(item.reference) ?? []).filter(page => {
+            const sourceLanguage = config.frontmatter?.enforced?.language ?? page.language ?? config.frontmatter?.defaults?.language ?? defaultLanguage(config);
+            if (page.publications)
+                return page.publications.some(member => member.product === publication.product && member.channel === publication.channel && member.version === publication.version) && sourceLanguage === language;
+            const product = config.publications.products ? config.frontmatter?.enforced?.product ?? page.product ?? config.frontmatter?.defaults?.product : undefined;
+            const coordinate = resolvePublication(config.publications, {
+                ...(product ? { product } : {}),
+                channel: config.frontmatter?.enforced?.channel ?? page.channel ?? config.frontmatter?.defaults?.channel ?? config.publications?.defaults?.channel,
+                version: config.frontmatter?.enforced?.version ?? page.version ?? (product ? undefined : config.frontmatter?.defaults?.version ?? config.publications?.defaults?.version),
+                language: sourceLanguage
+            }, defaultLanguage(config));
+            return samePublication(coordinate, publication);
+        });
         if (matches.length > 1)
             throw new Error(`Duplicate page ID ${item.reference} in the default publication: ${matches.map(page => page.file).join(', ')}`);
         const prior = matches[0];
@@ -108,7 +120,7 @@ export async function materializeApiPages(configFile, apiId, options) {
         if (atFile !== undefined)
             throw new Error(`${file}: target exists with another page ID; no files written`);
         const summary = item.method === 'WEBHOOK' ? `Webhook event: ${item.route}` : `${item.method} ${item.route}`;
-        const header = YAML.stringify({ id: item.reference, title: item.title, summary, type: 'api-reference', slug: item.slug, channel: defaults.channel, version: defaults.version, language, operations: [item.id], access: { policy: 'draft' } });
+        const header = YAML.stringify({ id: item.reference, title: item.title, summary, type: 'api-reference', slug: item.slug, ...publication, operations: [item.id], access: { policy: 'draft' } });
         const body = 'This draft reference is based on its linked OpenAPI operation.\n\n[[TODO: Explain when to use this endpoint, its prerequisites, and any behavior the OpenAPI contract cannot express. Verify every claim before publishing.]]\n';
         pending.push({ item, file, content: `---\n${header}---\n\n${body}` });
     }

package/dist/api-publication-plan.d.ts

@@ -10,7 +10,9 @@ type ApiDefinition = {
         path: string;
         [key: string]: unknown;
     };
+    product?: string;
     publications?: Array<{
+        product?: string;
         channel: string;
         version: string;
         source: {

package/dist/api-publication-plan.js

@@ -1,3 +1,4 @@
+import { documentKey } from './publication-identity.js';
 import { matchesFeatures, validateFeatureClassification } from './deployment-profile.js';
 import { matchesContentFilter } from './content-filter.js';
 import path from 'node:path';
@@ -10,7 +11,7 @@ import { explain } from './config.js';
 import { isConfigMapping } from './compiler-config.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 keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+const keyFor = documentKey;
 function validatedApiDefinitions(value) {
     if (value === undefined)
         return {};
@@ -24,7 +25,7 @@ function validatedApiDefinitions(value) {
         if (source !== undefined && (!isConfigMapping(source) || typeof source.kind !== 'string' || typeof source.path !== 'string'))
             throw new Error(`apis.${id}.source needs kind and path`);
         const publications = raw.publications;
-        if (publications !== undefined && (!Array.isArray(publications) || publications.some(item => !isConfigMapping(item) || typeof item.channel !== 'string' || typeof item.version !== 'string' || !isConfigMapping(item.source) || typeof item.source.kind !== 'string' || typeof item.source.path !== 'string' || (item.discovery !== undefined && (!isConfigMapping(item.discovery) || (item.discovery.endpoint !== undefined && typeof item.discovery.endpoint !== 'string'))))))
+        if (publications !== undefined && (!Array.isArray(publications) || publications.some(item => !isConfigMapping(item) || (item.product !== undefined && typeof item.product !== 'string') || typeof item.channel !== 'string' || typeof item.version !== 'string' || !isConfigMapping(item.source) || typeof item.source.kind !== 'string' || typeof item.source.path !== 'string' || (item.discovery !== undefined && (!isConfigMapping(item.discovery) || (item.discovery.endpoint !== undefined && typeof item.discovery.endpoint !== 'string'))))))
             throw new Error(`apis.${id}.publications needs entries with channel, version, and a local source`);
         const operations = raw.operations;
         if (operations !== undefined && (!Array.isArray(operations) || operations.some(item => !isConfigMapping(item) || typeof item.id !== 'string' || typeof item.reference !== 'string' || (item.sourceOperationId !== undefined && typeof item.sourceOperationId !== 'string'))))
@@ -39,6 +40,18 @@ function validatedApiDefinitions(value) {
 export async function materializeApiReferences({ config, loaded, variants, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, basePath, readerFilters, contentFilter, allowRouteCollisions }) {
     const definitions = validatedApiDefinitions(config.apis);
     for (const [id, definition] of Object.entries(definitions)) {
+        if (config.publications.products && definition.product !== undefined && (typeof definition.product !== 'string' || !config.publications.products || !Object.hasOwn(config.publications.products, definition.product)))
+            throw new Error(`API ${id}: unknown product ${definition.product}`);
+        const seenPublications = new Set();
+        for (const publication of definition.publications ?? []) {
+            const catalog = publication.product === undefined ? config.publications.versions : config.publications.products?.[publication.product]?.versions;
+            if (!catalog || !Object.hasOwn(catalog, publication.version) || !Object.hasOwn(config.publications.channels, publication.channel))
+                throw new Error(`API ${id}: unknown product publication`);
+            const key = JSON.stringify([publication.product, publication.channel, publication.version]);
+            if (seenPublications.has(key))
+                throw new Error(`API ${id}: duplicate publication source`);
+            seenPublications.add(key);
+        }
         validateFeatureClassification(definition, loaded.deployment ? { ...loaded.deployment.context, requireClassification: false } : undefined, `API ${id}`);
         for (const operation of definition.operations ?? [])
             validateFeatureClassification(operation, loaded.deployment ? { ...loaded.deployment.context, requireClassification: false } : undefined, `Operation ${operation.id}`);
@@ -62,10 +75,13 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
     }
     const sourceForVariant = (apiId, definition, variant) => {
         const defaults = config.publications.defaults;
-        if (definition.source !== undefined && (!defaults?.channel || !defaults?.version))
+        if (definition.source !== undefined && (!defaults?.channel || (!defaults?.version && !((definition.product ?? defaults?.product) && config.publications.products?.[definition.product ?? defaults.product]?.defaultVersion))))
             throw new Error(`apis.${apiId}.source needs publications.defaults with channel and version to choose its publication`);
-        const isDefault = variant.channel === defaults?.channel && variant.version === defaults?.version;
-        const publicationIndex = definition.publications?.findIndex(item => item.channel === variant.channel && item.version === variant.version) ?? -1;
+        const product = config.publications.products ? definition.product ?? defaults?.product : undefined;
+        const scopedVersion = product && defaults?.product === product && defaults.version && Object.hasOwn(config.publications.products[product].versions, defaults.version) ? defaults.version : undefined;
+        const defaultVersion = product ? scopedVersion ?? config.publications.products?.[product]?.defaultVersion : defaults?.version;
+        const isDefault = variant.product === product && variant.channel === defaults?.channel && variant.version === defaultVersion;
+        const publicationIndex = definition.publications?.findIndex(item => item.product === variant.product && item.channel === variant.channel && item.version === variant.version) ?? -1;
         const source = publicationIndex >= 0 ? definition.publications?.[publicationIndex].source : (isDefault ? definition.source : undefined);
         if (!source)
             return undefined;
@@ -166,7 +182,7 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
                             const classification = requirements !== undefined || shared !== undefined ? { requires: requirements, shared } : definition;
                             validateFeatureClassification(classification, loaded.deployment?.context, `${binding.file}: ${sourceOperationId} (generated reference)`);
                         }
-                        if (!variants.some(item => item.channel === variant.channel && item.version === variant.version && item.language === variant.language))
+                        if (!variants.some(item => item.product === variant.product && item.channel === variant.channel && item.version === variant.version && item.language === variant.language))
                             continue;
                         operationRequirements.set(keyFor(id, variant), requirements);
                         const featureSelected = matchesFeatures(requirements, loaded.deployment?.context, `${binding.file}: ${sourceOperationId}`) && matchesFeatures(definition.requires, loaded.deployment?.context, `API ${apiId}`);
@@ -183,7 +199,7 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
                         knownDocumentTypes.set(reference, page.type);
                         if (!matchesFeatures(page.requires, loaded.deployment?.context, `${binding.file}: ${reference}`))
                             continue;
-                        if (page.access?.policy !== 'public' || page.channel !== variant.channel || page.version !== variant.version || page.language !== variant.language)
+                        if (page.access?.policy !== 'public' || page.channel !== variant.channel || page.version !== variant.version || page.language !== variant.language || (config.publications.products && page.product !== variant.product))
                             continue;
                         const key = keyFor(reference, variant);
                         const authored = docs.get(key);

package/dist/api-publication-review.js

@@ -1,9 +1,10 @@
+import { documentKey, publicationKey } from './publication-identity.js';
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { isConfigMapping } from './compiler-config.js';
 const digest = (value) => createHash('sha256').update(value).digest('hex');
-const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+const keyFor = documentKey;
 export async function reviewApiPublication(configFile, apiPlan, rendered, apiEmbedUses, focusedContracts, apiSources, sourceForOperation, mode) {
     const { api, knownOperations, sourceForVariant } = apiPlan;
     // Pin the source bytes and the API selections exposed by public pages. Authored
@@ -19,7 +20,7 @@ export async function reviewApiPublication(configFile, apiPlan, rendered, apiEmb
             continue;
         const bindings = new Map();
         for (const { doc } of pages) {
-            const key = `${doc.variant.channel}|${doc.variant.version}`;
+            const key = doc.variant.product ? publicationKey(doc.variant) : `${doc.variant.channel}|${doc.variant.version}`;
             if (!bindings.has(key))
                 bindings.set(key, sourceForVariant(apiId, definition, doc.variant));
         }
@@ -35,7 +36,7 @@ export async function reviewApiPublication(configFile, apiPlan, rendered, apiEmb
         }
         const reviewedPages = pages.map(({ doc }) => ({ id: doc.frontmatter.id, url: doc.route, markdownUrl: doc.markdownRoute }));
         const references = pages.filter(({ doc }) => doc.frontmatter.type === 'api-reference').flatMap(({ doc }) => (doc.frontmatter.operations ?? []).filter(id => knownOperations.get(id)?.apiId === apiId).map(id => ({
-            channel: doc.variant.channel, version: doc.variant.version, language: doc.variant.language,
+            ...(doc.variant.product ? { product: doc.variant.product } : {}), channel: doc.variant.channel, version: doc.variant.version, language: doc.variant.language,
             operation: sourceForOperation(id, doc.variant).sourceOperationId
         }))).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
         const embeds = apiEmbedUses.filter(use => use.api === apiId || (use.operation && knownOperations.get(use.operation)?.apiId === apiId))

package/dist/api-selection.d.ts

@@ -1,3 +1,4 @@
+import type { Variant } from './content.js';
 export type ApiCandidate = {
     operationId: string;
     method: string;
@@ -9,12 +10,14 @@ export type ApiCandidate = {
     slug: string;
     filename: string;
 };
-export declare function apiCandidates(configFile: string, apiId: string): Promise<{
+export declare function apiCandidates(configFile: string, apiId: string, selection?: Partial<Variant>): Promise<{
     candidates: ApiCandidate[];
     selected: Set<string>;
     pathPrefix: string;
+    publication: Variant;
+    sourceFile: string;
 }>;
-export declare function selectApiReferences(configFile: string, apiId: string, outputFile: string): Promise<{
+export declare function selectApiReferences(configFile: string, apiId: string, outputFile: string, publication?: Partial<Variant>): Promise<{
     selected: string[];
     total: number;
     file: string;

package/dist/api-selection.js

@@ -1,3 +1,6 @@
+import { resolvePublication } from './compiler-config.js';
+import { defaultLanguage } from './frontmatter.js';
+import { samePublication } from './publication-identity.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
@@ -5,23 +8,27 @@ import YAML from 'yaml';
 import { ApiReader } from './api.js';
 import { generatedOperationIdentity } from './api-identity.js';
 import { explain, loadConfig } from './config.js';
-export async function apiCandidates(configFile, apiId) {
+export async function apiCandidates(configFile, apiId, selection = {}) {
     const loaded = await loadConfig(configFile);
     const config = loaded.value;
     const definition = config.apis?.[apiId];
     if (!definition)
         throw new Error(`Unknown API ${apiId}`);
-    const defaults = config.publications?.defaults;
-    if (!defaults?.channel || !defaults?.version)
-        throw new Error('API selection needs publication defaults');
-    const publicationIndex = definition.publications?.findIndex((item) => item.channel === defaults.channel && item.version === defaults.version) ?? -1;
-    const source = publicationIndex >= 0 ? definition.publications[publicationIndex].source : definition.source;
+    const defaults = config.publications?.defaults ?? {};
+    const product = config.publications.products ? selection.product ?? definition.product ?? defaults.product : undefined;
+    const publication = resolvePublication(config.publications, { ...defaults, ...selection, ...(product ? { product, version: selection.version } : {}) }, defaultLanguage(config));
+    if (!config.publications.enabled?.some((item) => samePublication(resolvePublication(config.publications, item, defaultLanguage(config)), publication)))
+        throw new Error('API selection publication is not enabled; select an explicit product and release');
+    const publicationIndex = definition.publications?.findIndex((item) => item.product === publication.product && item.channel === publication.channel && item.version === publication.version) ?? -1;
+    const sourceDefault = definition.source ? resolvePublication(config.publications, { ...defaults, ...(config.publications.products && definition.product ? { product: definition.product, version: undefined } : {}) }, defaultLanguage(config)) : undefined;
+    const source = publicationIndex >= 0 ? definition.publications[publicationIndex].source : sourceDefault && publication.product === sourceDefault.product && publication.channel === sourceDefault.channel && publication.version === sourceDefault.version ? definition.source : undefined;
     if (source?.kind !== 'file')
-        throw new Error(`API ${apiId} needs a local file source in the default publication`);
+        throw new Error(`API ${apiId} needs a local file source in the selected publication`);
     const sourceKey = publicationIndex >= 0 ? `apis.${apiId}.publications.${publicationIndex}.source.path` : `apis.${apiId}.source.path`;
     const origin = explain(loaded, sourceKey).source.file;
     const reader = new ApiReader();
-    const loadedSpec = await reader.load(path.resolve(path.dirname(origin), source.path));
+    const sourceFile = path.resolve(path.dirname(origin), source.path);
+    const loadedSpec = await reader.load(sourceFile);
     const spec = loadedSpec.value;
     const explicit = new Map((definition.operations ?? []).map((entry) => [entry.sourceOperationId, entry]));
     const generate = definition.generateReferences;
@@ -47,10 +54,10 @@ export async function apiCandidates(configFile, apiId) {
             }
         }
     const selected = new Set(generate && generate !== true && Array.isArray(generate.include) ? generate.include : generate && generate !== true && Array.isArray(generate.exclude) ? candidates.filter(item => !generate.exclude.includes(item.operationId)).map(item => item.operationId) : generate ? candidates.map(item => item.operationId) : []);
-    return { candidates, selected, pathPrefix };
+    return { candidates, selected, pathPrefix, publication, sourceFile };
 }
-export async function selectApiReferences(configFile, apiId, outputFile) {
-    const { candidates, selected: current, pathPrefix } = await apiCandidates(configFile, apiId);
+export async function selectApiReferences(configFile, apiId, outputFile, publication = {}) {
+    const { candidates, selected: current, pathPrefix } = await apiCandidates(configFile, apiId, publication);
     const chosen = [];
     const reader = createInterface({ input: process.stdin, output: process.stdout });
     const answers = reader[Symbol.asyncIterator]();

package/dist/artifact-bundle.js

@@ -16,6 +16,7 @@ import { defaultShareSvg, faviconSvg, fillShareTemplate, renderPng, touchIconSvg
 import { paletteCatalog, paletteCss, presetCatalog, resolvePalette } from './palettes.js';
 import { heading, link, list, paragraph, renderMarkdown, root, searchIndex, shareCardText, text } from './content.js';
 import { outputUrl } from './representation-tree.js';
+const publicationLabel = (value) => [...(value.product === undefined ? [] : [value.product]), value.channel, value.version, value.language].join('/');
 export async function assembleArtifacts(input) {
     const { base, basePath, publicPath, canonical, siteOrigin, manifest, provenanceRecord, rendered, sitemaps, diagramAssets, heroImages, focusedContracts, styleFiles, themeStyleFile, generatedPaletteCss, generatedBadgeCss, search, synonyms, config, builtInSearchProvider, customReaderModule, analyticsModule, mcpAnalyticsModule, previewFiles, assetDirectory, themeSwitcher, themeDirectory, palette, colorMode, generatedFontsCss, fontFiles, fonts, shareImages, shareFor, themePreset, shareFontFiles, shareCache, faviconFile, faviconRoute, customStyleFile, scriptFiles, componentAssets, redirects, apiPublications, api, catalog, headers, documentRoutes, readerFilters, apiSources } = input;
     const artifacts = new Map();
@@ -198,7 +199,7 @@ export async function assembleArtifacts(input) {
     const discoveryEntry = ({ doc }, includeType = false) => ({ title: `${fictionalDocument(doc, llms) ? 'Fictional example: ' : ''}${doc.frontmatter.title}`, url: doc.markdownRoute, summary: `${includeType ? `${doc.frontmatter.type} — ` : ''}${fictionalDocument(doc, llms) ? 'Demonstration only; not a live API. ' : ''}${doc.frontmatter.summary}` });
     const tabs = manifest.navigationTabs ?? [];
     const tabLinks = tabs.length ? '\n\n## Navigation sections\n\n' + discoveryLinks(tabs.map(tab => ({
-        title: `${tab.label} (${tab.variant.channel}/${tab.variant.version}/${tab.variant.language})`, url: tab.indexUrl,
+        title: `${tab.label} (${publicationLabel(tab.variant)})`, url: tab.indexUrl,
         summary: `Section ID: ${tab.id}. Scoped page index.`
     }))) : '';
     const groups = new Map();
@@ -237,7 +238,7 @@ export async function assembleArtifacts(input) {
         }))])).trimEnd();
     const discovery = [renderMarkdown(root([heading(1, String(config.site.title))])).trimEnd(), '', '> Documentation and API contracts published by this site.', ...(readerFilters ? ['', 'Reader views affect the interactive HTML only. This index lists every published page, and each Markdown page includes all reader-marked sections with readable labels. The document manifest records configured reader facets and each page’s marks.'] : []), ...(llms.fictionalPrefixes.length ? ['', 'Entries labeled Fictional example demonstrate documentation features. Their operations and API contracts do not describe a live service.'] : []), '', '## Discovery', '', discoveryLinks([{ title: 'Compact documentation index', url: publicPath('/llms.min.txt'), summary: 'Start here: full-page Markdown links and author-declared standalone section links with sizes and full-page fallbacks. No tools or JSON processing required.' }, ...(search.index ? [{ title: 'Compact heading index', url: publicPath('/search-index.min.json'), summary: 'Page summaries, headings, and smaller section Markdown URLs with sizes; no article text.' }] : []), { title: 'Resource response headers', url: publicPath('/resource-headers.json'), summary: 'Published hosting metadata: content types and representation Link headers for host adapters.' }, { title: 'Document sync snapshot', url: publicPath('/documents.sync.json'), summary: 'Save and compare compact page signatures between builds; build-info.json identifies the current build.' }, { title: 'Structured document manifest', url: publicPath('/documents.json'), summary: 'Stable page IDs, HTML and Markdown URLs, and content digests.' }, ...(sitemaps.size ? [{ title: 'XML sitemap', url: publicPath('/sitemap.xml'), summary: 'Canonical URLs for indexable pages.' }] : []), ...(search.index ? [{ title: 'Lexical search index', url: publicPath('/search-index.json'), summary: 'Downloadable page titles, summaries, headings, and bounded HTML article text. It is an index file, not a query endpoint.' }] : []), ...(catalog ? [{ title: 'API catalog', url: publicPath('/.well-known/api-catalog'), summary: '' }] : [])]), ...sections, ...(apiSources.some(item => llms.format === 'flat' || !fictionalApis.has(item.apiId)) ? ['', '## API contracts', '', discoveryLinks(apiSources.filter(item => llms.format === 'flat' || !fictionalApis.has(item.apiId)).map(item => ({ title: `${fictionalApis.has(item.apiId) ? 'Fictional example: ' : ''}${item.apiId} ${item.channel} ${item.version} OpenAPI`, url: item.sourceUrl, summary: `Pinned ${item.mediaType} source used for the reference.` })))] : []), ...(llms.format === 'grouped' && optional.length ? ['', '## Optional', '', optionalList] : [])].join('\n') + '\n';
     addPublicArtifact('/llms.txt', discovery + tabLinks + (tabLinks ? '\n' : ''));
-    const publications = [...new Set(rendered.map(page => `${page.doc.variant.channel}/${page.doc.variant.version}/${page.doc.variant.language}`))].sort();
+    const publications = [...new Set(rendered.map(page => `${publicationLabel(page.doc.variant)}`))].sort();
     const pageSizes = new Map(manifest.documents.map(page => [page.markdownUrl, page]));
     const compactSummary = (page) => {
         const size = pageSizes.get(page.doc.markdownRoute);
@@ -245,21 +246,23 @@ export async function assembleArtifacts(input) {
     };
     const compactEntries = [...rendered].sort((a, b) => a.doc.route.localeCompare(b.doc.route)).map(page => {
         const entry = discoveryEntry(page);
-        const publication = `${page.doc.variant.channel}/${page.doc.variant.version}/${page.doc.variant.language}`;
+        const publication = `${publicationLabel(page.doc.variant)}`;
         const approved = (page.sections ?? []).filter(section => section.standalone === true);
         return [paragraph(link(entry.url, `${page.doc.frontmatter.id} · ${entry.title}${publications.length > 1 ? ` (${publication})` : ''}`), text(`: ${compactSummary(page)}`)),
             ...(approved.length ? [list(approved.map(section => [paragraph(text('Standalone section: '), link(section.markdownUrl, section.title), text(` — ${section.markdownTokens} tokens (${section.markdownTokenEncoding}), ${section.markdownBytes} UTF-8 bytes. `), link(entry.url, 'Full page'), text('.'))]))] : [])];
     });
     const compactList = renderMarkdown(root([list(compactEntries)])).trimEnd();
+    const productGuidance = configField(config.publications, 'products') ? [paragraph(text('Products have independent versions. Discover published product/channel/version/language coordinates with MCP get_publications, or documents.json. Keep the exact publication returned by search when reading pages; cross-product links must name their target explicitly. This edition contains only its selected content.'))] : [];
     const compactIntro = renderMarkdown(root([
         heading(1, String(config.site.title)),
+        ...productGuidance,
         paragraph(text(`Full-page token counts use ${markdownTokenEncoding}. Fetch a matching full Markdown page by default. Use a listed standalone section only for its stated topic; for setup, broader questions, or missing context, follow Full page. Standalone is an author declaration, not proof of completeness.`)),
-        paragraph(text(publications.length === 1 ? `Publication (channel/version/language): ${publications[0]}.` : 'Choose the matching channel/version/language shown on each page; keep that publication when following links.')),
+        paragraph(text(publications.length === 1 ? `Publication (${configField(config.publications, 'products') ? 'product/' : ''}channel/version/language): ${publications[0]}.` : `Choose the matching ${configField(config.publications, 'products') ? 'product/' : ''}channel/version/language shown on each page; keep that publication when following links.`)),
         paragraph(link(publicPath('/llms.txt'), 'Full documentation index'), text('. Full manifests and search indexes are optional. A missing match does not establish that a feature exists or does not exist.')),
     ])).trimEnd();
     const topicEntries = rendered.flatMap(page => {
         const entry = discoveryEntry(page);
-        const publication = `${page.doc.variant.channel}/${page.doc.variant.version}/${page.doc.variant.language}`;
+        const publication = `${publicationLabel(page.doc.variant)}`;
         const area = Array.isArray(page.doc.frontmatter.area) ? page.doc.frontmatter.area[0] : page.doc.frontmatter.area;
         const topic = JSON.stringify([publication, area ?? page.doc.frontmatter.type]);
         const topicLabel = `${(area && manifest.taxonomy?.areas[area]?.label) || area || page.doc.frontmatter.type}${publications.length > 1 ? ` (${publication})` : ''}`;
@@ -283,7 +286,7 @@ export async function assembleArtifacts(input) {
         const members = manifest.documents.filter(doc => doc.navigationTab?.indexUrl === tab.indexUrl);
         const intro = renderMarkdown(root([
             heading(1, tab.label),
-            paragraph(text(`Full-page token counts use ${markdownTokenEncoding}. Navigation section ID: ${tab.id}. Publication: ${tab.variant.channel}/${tab.variant.version}/${tab.variant.language}.`)),
+            paragraph(text(`Full-page token counts use ${markdownTokenEncoding}. Navigation section ID: ${tab.id}. Publication: ${publicationLabel(tab.variant)}.`)),
             paragraph(link(outputUrl(publicPath('/llms.min.txt'), '/', siteOrigin, 'markdown', documentRoutes, basePath), 'All sections and published pages'), text('. This index covers this section only; shared and unlisted pages remain reachable through the global index. Reader views do not remove pages from this index.')),
         ])).trimEnd();
         const memberUrls = new Set(members.flatMap(doc => [doc.markdownUrl, ...doc.sections.filter(section => section.standalone === true).map(section => section.markdownUrl)]));

package/dist/ask-function.d.ts

@@ -1,19 +1,5 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
-export type FunctionRuntime = {
-    schemaVersion: 1;
-    settings: Record<string, unknown>;
-    variant?: {
-        channel: string;
-        version: string;
-        language: string;
-    };
-    hosts?: string[];
-    callerHeader?: string;
-    maxRequestsPerMinute?: number;
-};
-export type AskFunction = (request: Request) => Promise<Response>;
-export declare function createHostedSearchFunction(directory: string, env?: NodeJS.ProcessEnv): Promise<AskFunction>;
+import { type AskFunction } from './function-runtime.js';
+export { nodeAdapter } from './function-runtime.js';
+export type { FunctionRuntime, AskFunction } from './function-runtime.js';
+export { createHostedSearchFunction } from './search-function.js';
 export declare function createAskFunction(directory: string, env?: NodeJS.ProcessEnv, send?: typeof fetch): Promise<AskFunction>;
-export declare function nodeAdapter(load: () => Promise<AskFunction>, limits?: {
-    bodyBytes: number;
-}): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/ask-function.js

@@ -1,40 +1,23 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { DailyBudget, SharedRateLimit, adaptiveChallenge } from './budget.js';
+import { SharedRateLimit, adaptiveChallenge } from './budget.js';
 import { askQuestion } from './ask.js';
 import { clientKeyFromHeader, createAskHandler } from './ask-handler.js';
-import { prepareAsk } from './ask-setup.js';
+import { prepareAskRuntime } from './ask-runtime.js';
+import { allowedHosts } from './function-runtime.js';
+export { nodeAdapter } from './function-runtime.js';
+// Keep the previous deep import available without making Search import Ask.
+export { createHostedSearchFunction } from './search-function.js';
 import { validateChat } from './chat-config.js';
 import { validateReaderFilters } from './reader-filters.js';
 import { createSession, turnstileVerifier } from './turnstile.js';
-import { envBudgetStore, envRedis } from './budget-store.js';
-import { createSearchHandler } from './search-handler.js';
-import { validateSearch } from './search-config.js';
+import { envRedis } from './budget-store.js';
 import { pausedKey } from './chat-pause.js';
 import { deleteKvLogRecord, kvLogSink } from './ask-log-kv.js';
-function allowedHosts(runtime, env) {
-    return [...new Set([...(runtime.hosts ?? []), env.VERCEL_URL, env.VERCEL_BRANCH_URL, env.VERCEL_PROJECT_PRODUCTION_URL, ...(env.SHOALRUN_ASK_HOSTS?.split(',') ?? [])].map(host => host?.trim().toLowerCase()).filter((host) => Boolean(host)))];
-}
-// Hosted search uses the same private index as chat, with separate limits for embedding spend.
-export async function createHostedSearchFunction(directory, env = process.env) {
-    const runtime = JSON.parse(await readFile(path.join(directory, 'runtime.json'), 'utf8'));
-    if (runtime?.schemaVersion !== 1 || !runtime.settings)
-        throw new Error('runtime.json is not a Shoalrun search function file');
-    const filters = validateReaderFilters(runtime.settings.readerFilters);
-    const chat = validateChat(runtime.settings.chat, filters);
-    if (!chat?.budget?.store)
-        throw new Error('Hosted semantic search needs a shared budget store');
-    const setup = await prepareAsk({ siteDirectory: path.join(directory, 'site'), settings: runtime.settings, sharedStore: true, ...(runtime.variant ?? {}) });
-    const store = envBudgetStore(chat.budget.store, env);
-    const { limits } = validateSearch(runtime.settings.search);
-    return createSearchHandler({
-        retriever: setup.options.retriever, embedQuery: setup.options.embedQuery, readerFilters: filters, hosts: allowedHosts(runtime, env),
-        onFallback: reason => console.warn(`Search fallback: ${reason}`),
-        rateLimiter: new SharedRateLimit(store, limits.perCallerPerMinute, Date.now, error => console.error(`Search rate limit: ${error.message}`), 'search-rate'),
-        budget: new DailyBudget(store, { perCaller: limits.perCallerPerDay, perDay: limits.perDay }, Date.now, error => console.error(`Search budget: ${error.message}`), 'search-budget'),
-        clientKey: clientKeyFromHeader(runtime.callerHeader ?? 'x-vercel-forwarded-for')
-    });
-}
+// The answer function for a hosted site. The build writes a directory holding `runtime.json` (the chat and retrieval settings, with no
+// keys) and `site/ai` (the passages and vectors), and this module turns that directory into a Web `Request` to `Response` function. Keys come
+// only from the environment variables the settings name. It refuses to start without a shared budget store, because per-instance counters
+// on a serverless host would not limit anything.
 export async function createAskFunction(directory, env = process.env, send) {
     const runtime = JSON.parse(await readFile(path.join(directory, 'runtime.json'), 'utf8'));
     if (runtime?.schemaVersion !== 1 || !runtime.settings)
@@ -44,7 +27,7 @@ export async function createAskFunction(directory, env = process.env, send) {
         throw new Error('The site config has no chat section');
     if (!chat.budget?.store)
         throw new Error('A hosted chat needs chat.budget with a shared store, so its daily caps hold across server instances');
-    const setup = await prepareAsk({ siteDirectory: path.join(directory, 'site'), settings: runtime.settings, cache: true, sharedStore: true, ...(runtime.variant ?? {}) });
+    const setup = await prepareAskRuntime({ siteDirectory: path.join(directory, 'site'), settings: runtime.settings, cache: true, sharedStore: true, ...(runtime.variant ?? {}) });
     for (const note of setup.notes)
         console.error(note);
     if (!setup.budget)
@@ -95,45 +78,3 @@ export async function createAskFunction(directory, env = process.env, send) {
         answer: (question, history, context) => askQuestion({ question, history, ...setup.options, modelAllowed: context.modelAllowed, signal: context.signal, requireCitations: true })
     });
 }
-const failure = (status, message) => new Response(JSON.stringify({ error: message }), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' } });
-// Vercel's Node runtime calls `(req, res)`. This turns that into a Web request and back. Starting up happens on the first request, and a
-// failed start is tried again on the next one. The reader never sees why it failed; the reason goes to the function log.
-export function nodeAdapter(load, limits = { bodyBytes: 32_768 }) {
-    let ready;
-    const write = async (res, response) => {
-        res.statusCode = response.status;
-        response.headers.forEach((value, name) => { if (name !== 'set-cookie')
-            res.setHeader(name, value); });
-        const cookies = response.headers.getSetCookie();
-        if (cookies.length)
-            res.setHeader('set-cookie', cookies);
-        res.end(Buffer.from(await response.arrayBuffer()));
-    };
-    return async (req, res) => {
-        try {
-            const handler = await (ready ??= load().catch(error => { ready = undefined; throw error; }));
-            const chunks = [];
-            let size = 0;
-            for await (const chunk of req) {
-                size += chunk.length;
-                if (size > limits.bodyBytes) {
-                    await write(res, failure(413, 'The request is too large.'));
-                    return;
-                }
-                chunks.push(chunk);
-            }
-            const headers = new Headers();
-            for (const [name, value] of Object.entries(req.headers))
-                for (const item of Array.isArray(value) ? value : value === undefined ? [] : [value])
-                    headers.append(name, item);
-            const method = req.method ?? 'GET';
-            const request = new Request(`https://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { method, headers, ...(method === 'GET' || method === 'HEAD' ? {} : { body: Buffer.concat(chunks) }) });
-            await write(res, await handler(request));
-        }
-        catch (error) {
-            console.error(`The answer function failed: ${error.message}`);
-            if (!res.headersSent)
-                await write(res, failure(503, 'The chat is unavailable right now.'));
-        }
-    };
-}

package/dist/ask-runtime.d.ts

@@ -0,0 +1,46 @@
+import type { AskOptions } from './ask.js';
+import { type ChatProvider } from './chat.js';
+import { type ReaderSelection } from './reader-filters.js';
+import { DailyBudget, type BudgetStore } from './budget.js';
+export declare function parseReaderView(specs: string[]): ReaderSelection | undefined;
+export type AskSetupInput = {
+    sharedStore?: boolean;
+    siteDirectory: string;
+    configFile?: string;
+    settings?: Record<string, unknown>;
+    model?: string;
+    passages?: number;
+    product?: string;
+    channel?: string;
+    version?: string;
+    language?: string;
+    noRerank?: boolean;
+    noDirect?: boolean;
+    noEscalate?: boolean;
+    noCards?: boolean;
+    cache?: boolean;
+    direct?: {
+        threshold: number;
+        maxChars?: number;
+    };
+    jevCacheDir?: string;
+    readerView?: ReaderSelection;
+    maxTokens?: number;
+};
+export type AskSetup = {
+    budget?: DailyBudget;
+    budgetStore?: BudgetStore;
+    chat: ChatProvider;
+    options: Omit<AskOptions, 'question'>;
+    notes: string[];
+    embedTexts?: (texts: string[]) => Promise<Float32Array[]>;
+    embedding?: {
+        provider: string;
+        model: string;
+        space: string;
+        dimension: number;
+    };
+};
+export declare function prepareAskRuntime(input: AskSetupInput & {
+    settings: Record<string, unknown>;
+}): Promise<AskSetup>;