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

package/dist/publication-render.js

@@ -1,8 +1,9 @@
+import { documentKey, publicationKey, samePublication } from './publication-identity.js';
 import { resolveAuthoredChange, authoredChangeNotice } from './authored-change.js';
 import { resolveSubjectDeprecation, subjectDeprecationNotice } from './subject-deprecation.js';
 import { markdownSections } from './markdown-sections.js';
 import { contentDigest } from './freshness.js';
-import { configField } from './compiler-config.js';
+import { configField, isConfigMapping } from './compiler-config.js';
 import { fictionalDocument, resolveLlmsDiscovery } from './llms-discovery.js';
 import { publicationRelationships, resolveCardTree } from './cards.js';
 import { resolveCookbookTree } from './cookbook-chooser.js';
@@ -10,13 +11,17 @@ import { buildHtmlPage, heading, link, markdownRoute, paragraph, projectMetadata
 import { navigationPath, navigationTab, navigationTabRecord, resolveProjectNavigation } from './project-navigation.js';
 import { outputUrl, publicTree, resolveOutputLinks } from './representation-tree.js';
 import { presetCatalog } from './palettes.js';
-const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+const keyFor = documentKey;
 export function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }) {
     const resolvedNavigation = new Map();
+    const selector = config.site.publicationSelector;
+    if (selector !== undefined && (!isConfigMapping(selector) || Object.keys(selector).some(key => key !== 'showLanguage') || (selector.showLanguage !== undefined && typeof selector.showLanguage !== 'boolean')))
+        throw new Error('site.publicationSelector must be a mapping with an optional boolean showLanguage');
+    const showLanguage = isConfigMapping(selector) && typeof selector.showLanguage === 'boolean' ? selector.showLanguage : new Set(rendered.map(item => item.doc.variant.language)).size > 1;
     const scopedRelationships = new Map();
     const hasHome = rendered.some(page => page.doc.route === basePath || page.doc.route === '/');
     for (const page of rendered) {
-        const navVariant = `${page.doc.variant.channel}|${page.doc.variant.version}|${page.doc.variant.language}`;
+        const navVariant = publicationKey(page.doc.variant);
         let edges = scopedRelationships.get(navVariant);
         if (!edges) {
             const local = new Map([...docs.values()].filter(doc => keyFor(doc.frontmatter.id, doc.variant) === keyFor(doc.frontmatter.id, page.doc.variant)).map(doc => [doc.frontmatter.id, doc]));
@@ -60,7 +65,7 @@ export function renderPublicationPages({ rendered, docs, relationships, knownOpe
                 ...(index ? [text(' > ')] : []),
                 crumb.url && index < breadcrumbs.length - 1 ? link(outputUrl(markdownRoute(crumb.url, basePath), page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), crumb.label) : text(crumb.label)
             ]))])) + '\n' : '');
-        page.markdown = projectMetadata(page.doc, config) + renderMarkdown(root([heading(1, page.doc.frontmatter.title)])) + '\n' + renderMarkdown(root([{ type: 'blockquote', children: [paragraph(text('Documentation index: '), link(outputUrl(`${basePath}/llms.min.txt`, page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), 'llms.min.txt'), text(' · Document manifest: '), link(outputUrl(`${basePath}/documents.json`, page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), 'documents.json'))] }])) + '\n' + breadcrumbMarkdown + (page.doc.frontmatter.date ? markdownLabel('Published', page.doc.frontmatter.date) : '') + (page.doc.frontmatter.updated && !(page.doc.frontmatter.type === 'changelog-entry' && page.doc.frontmatter.date) ? markdownLabel('Updated', page.doc.frontmatter.updated) : '') + (page.doc.frontmatter.verified ? markdownLabel('Verified', page.doc.frontmatter.verified) : '') + (page.doc.frontmatter.releaseVersion ? markdownLabel('Version', page.doc.frontmatter.releaseVersion) : '') + (subjectLifecycleLabel ? markdownLabel('Status', subjectLifecycleLabel) : '') + noticeMarkdown + renderMarkdown(mdTree);
+        page.markdown = projectMetadata(page.doc, config) + renderMarkdown(root([heading(1, page.doc.frontmatter.title)])) + '\n' + renderMarkdown(root([{ type: 'blockquote', children: [paragraph(text('Documentation index: '), link(outputUrl(`${basePath}/llms.min.txt`, page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), 'llms.min.txt'), text(' · Document manifest: '), link(outputUrl(`${basePath}/documents.json`, page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), 'documents.json'))] }])) + '\n' + breadcrumbMarkdown + (page.doc.frontmatter.date ? markdownLabel('Published', page.doc.frontmatter.date) : '') + (page.doc.frontmatter.updated && !(page.doc.frontmatter.type === 'changelog-entry' && page.doc.frontmatter.date) ? markdownLabel('Updated', page.doc.frontmatter.updated) : '') + (page.doc.frontmatter.availability?.since ? markdownLabel('Available since', page.doc.frontmatter.availability.since) : '') + (page.doc.frontmatter.availability?.through ? markdownLabel('Available through', page.doc.frontmatter.availability.through) : '') + (page.doc.frontmatter.verified ? markdownLabel('Verified', page.doc.frontmatter.verified) : '') + (page.doc.frontmatter.releaseVersion ? markdownLabel('Version', page.doc.frontmatter.releaseVersion) : '') + (subjectLifecycleLabel ? markdownLabel('Status', subjectLifecycleLabel) : '') + noticeMarkdown + renderMarkdown(mdTree);
         const body = renderMarkdown(mdTree);
         const sectionPrefix = page.markdown.slice(0, -body.length) + (fictional ? renderMarkdown(root([mdTree.children[0]])) + '\n' : '');
         page.sections = markdownSections(page.doc.tree, page.doc.markdownRoute, page.markdown, sectionPrefix, tree => {
@@ -71,22 +76,33 @@ export function renderPublicationPages({ rendered, docs, relationships, knownOpe
                 ...(node.children ? { children: node.children.map(parentLinks) } : {}) });
             return renderMarkdown(parentLinks(resolved));
         }, page.doc.frontmatter.standaloneSections);
-        const externalForPage = externalDocuments.get(page.doc.frontmatter.id) ?? [];
+        const externalForPage = (externalDocuments.get(page.doc.frontmatter.id) ?? []).filter(item => item.variant.product === page.doc.variant.product);
         const shownLanguages = new Set([...variants.map(variant => variant.language), ...externalForPage.map(item => item.variant.language)]).size > 1;
         const languageSuffix = (variant) => shownLanguages ? ` · ${variant.language}` : '';
-        const localAlternates = variants.flatMap(variant => {
+        const localAlternates = variants.filter(variant => variant.product === page.doc.variant.product).flatMap(variant => {
             const alternate = docs.get(keyFor(page.doc.frontmatter.id, variant));
             const label = `${variant.channel} · ${variant.version}${languageSuffix(variant)}`;
             if (alternate)
                 return [{ label, url: alternate.route, current: alternate === page.doc }];
-            const overview = [...docs.values()].filter(doc => doc.variant.channel === variant.channel && doc.variant.version === variant.version && doc.variant.language === variant.language && doc.frontmatter.access?.policy === 'public').sort((a, b) => a.route.length - b.route.length || a.route.localeCompare(b.route))[0];
+            const overview = [...docs.values()].filter(doc => samePublication(doc.variant, variant) && doc.frontmatter.access?.policy === 'public').sort((a, b) => a.route.length - b.route.length || a.route.localeCompare(b.route))[0];
             return overview ? [{ label: `${label} · page unavailable; open overview`, url: overview.route, current: false }] : [];
         });
         const publicationAlternates = [...localAlternates, ...externalSiteLinks, ...externalForPage.map(item => ({
                 label: `${item.label}${item.label.toLowerCase() === item.variant.channel.toLowerCase() ? '' : ` · ${item.variant.channel}`} · ${item.variant.version}${languageSuffix(item.variant)}`,
                 url: item.url, current: false
             }))];
-        page.html = buildHtmlPage(page.doc, page.htmlTree, page.doc.markdownRoute, config.site.title, navigation, page.pageExamples, page.pageShapes, highlighter, editionLabel(page.doc.variant), !!customStyleFile, { preset: themePreset, palette: palette.name, themeCss: !!themeStyleFile, paletteCss: !!generatedPaletteCss, badgesCss: !!generatedBadgeCss, themeSwitcher: themeSwitcherData, fontsCss: !!generatedFontsCss, preloadFont: fontsPreload, masthead: presetCatalog.find(preset => preset.name === themePreset)?.masthead, share: shareFor(page.doc), favicon: faviconRoute, logo: logoRoute, touchIcon: !faviconRoute.endsWith('.png'), origin: siteOrigin, indexing: config.site.indexing !== false, home: hasHome, mode: colorMode, toggle: modeToggle, header, footer, search: search.provider !== 'none', publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
+        // Derive choices from the selected output, not the catalog: a customer
+        // edition must not advertise products or releases it did not publish.
+        const publicationChoices = config.publications.products ? [...new Map(rendered.map(item => [publicationKey(item.doc.variant), item.doc.variant])).values()]
+            .sort((left, right) => (left.product ?? '').localeCompare(right.product ?? '') || publicationKey(left).localeCompare(publicationKey(right)))
+            .flatMap(variant => {
+            const target = docs.get(keyFor(page.doc.frontmatter.id, variant)) ?? rendered.filter(item => samePublication(item.doc.variant, variant)).map(item => item.doc).sort((left, right) => left.route.length - right.route.length || left.route.localeCompare(right.route))[0];
+            if (!target)
+                return [];
+            const group = variant.product === undefined ? config.site.title : config.publications.products?.[variant.product]?.label ?? variant.product;
+            return [{ group, label: `${group} · ${variant.channel} · ${variant.version}${showLanguage ? ` · ${variant.language}` : ''}`, url: target.route, current: samePublication(page.doc.variant, variant) }];
+        }) : [];
+        page.html = buildHtmlPage(page.doc, page.htmlTree, page.doc.markdownRoute, config.site.title, navigation, page.pageExamples, page.pageShapes, highlighter, editionLabel(page.doc.variant), !!customStyleFile, { preset: themePreset, palette: palette.name, themeCss: !!themeStyleFile, paletteCss: !!generatedPaletteCss, badgesCss: !!generatedBadgeCss, themeSwitcher: themeSwitcherData, fontsCss: !!generatedFontsCss, preloadFont: fontsPreload, masthead: presetCatalog.find(preset => preset.name === themePreset)?.masthead, share: shareFor(page.doc), favicon: faviconRoute, logo: logoRoute, touchIcon: !faviconRoute.endsWith('.png'), origin: siteOrigin, indexing: config.site.indexing !== false, home: hasHome, mode: colorMode, toggle: modeToggle, header, footer, search: search.provider !== 'none', publicationChoices, publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
     }
     return resolvedNavigation;
 }

package/dist/recipe-draft.js

@@ -1,3 +1,5 @@
+import { resolvePublication } from './compiler-config.js';
+import { samePublication } from './publication-identity.js';
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -17,8 +19,10 @@ function parseYaml(source, file) {
     return document.toJS();
 }
 function parseSpec(value) {
-    if (!object(value) || value.schemaVersion !== 1 || Object.keys(value).some(key => !['schemaVersion', 'id', 'title', 'summary', 'slug', 'ingredients', 'inputs', 'outcome'].includes(key)))
+    if (!object(value) || value.schemaVersion !== 1 || Object.keys(value).some(key => !['schemaVersion', 'id', 'title', 'summary', 'slug', 'ingredients', 'inputs', 'outcome', 'publication'].includes(key)))
         throw new Error('Recipe spec needs schemaVersion: 1 and only supported fields');
+    if (value.publication !== undefined && (!object(value.publication) || Object.keys(value.publication).some(key => !['product', 'channel', 'version', 'language'].includes(key)) || Object.values(value.publication).some(item => typeof item !== 'string' || !item)))
+        throw new Error('Recipe publication must declare product/channel/version/language strings');
     workflowValues(value.inputs, 'Recipe inputs');
     if (value.outcome !== undefined && (typeof value.outcome !== 'string' || !value.outcome.trim()))
         throw new Error('Recipe outcome must be nonempty text');
@@ -59,9 +63,8 @@ export async function renderRecipeDraft(configFile, specFile) {
     const config = (await loadConfig(configPath)).value;
     const spec = parseSpec(parseYaml(await readFile(specFile, 'utf8'), specFile));
     const defaults = config.publications?.defaults ?? {};
-    if (!defaults.channel || !defaults.version)
-        throw new Error('Recipe draft needs a default channel and version');
-    const language = defaults.language ?? defaultLanguage(config);
+    const product = spec.publication?.product ?? defaults.product;
+    const publication = resolvePublication(config.publications, { ...defaults, ...spec.publication, ...(product ? { product, version: spec.publication?.version } : {}) }, defaultLanguage(config));
     const seen = new Set();
     const operations = new Set();
     const sources = [];
@@ -95,7 +98,7 @@ export async function renderRecipeDraft(configFile, specFile) {
             for (const prerequisite of workflow.prerequisites)
                 prerequisites.add(prerequisite);
         }
-        if (header.channel !== defaults.channel || header.version !== defaults.version || header.language !== language)
+        if (!samePublication({ channel: String(header.channel), version: String(header.version), language: String(header.language), ...(config.publications.products && header.product ? { product: String(header.product) } : {}) }, publication))
             throw new Error(`Ingredient ${header.id} must match the recipe's default publication`);
         if (header.operations !== undefined) {
             if (!Array.isArray(header.operations) || header.operations.some(value => typeof value !== 'string'))
@@ -111,7 +114,7 @@ export async function renderRecipeDraft(configFile, specFile) {
     }
     const header = {
         id: spec.id, title: spec.title, summary: spec.summary, type: 'recipe', slug: spec.slug,
-        channel: defaults.channel, version: defaults.version, language,
+        ...publication,
         ...(operations.size ? { operations: [...operations] } : {}), access: { policy: 'draft' }
     };
     const sourceDigest = digest([JSON.stringify(spec), ...sources].join('\n'));

package/dist/retrieval-runtime.d.ts

@@ -0,0 +1,5 @@
+import { Retriever } from './retrieval.js';
+export declare function prepareSearchRetrieval(directory: string, settings: Record<string, unknown>): Promise<{
+    retriever: Retriever;
+    embedQuery: ((query: string, signal?: AbortSignal) => Promise<Float32Array>) | undefined;
+}>;

package/dist/retrieval-runtime.js

@@ -0,0 +1,21 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createProvider, readEmbeddings } from './embeddings.js';
+import { queryProviderConfig, validateRetrieval } from './retrieval-config.js';
+import { Retriever } from './retrieval.js';
+// Search needs only passage retrieval and query embeddings, never chat models,
+// answer cards, source configuration, rendering, or component compilation.
+export async function prepareSearchRetrieval(directory, settings) {
+    const retrieval = validateRetrieval(settings.retrieval);
+    const chunks = JSON.parse(await readFile(path.join(directory, 'ai', 'chunks.json'), 'utf8'));
+    const embeddings = await readEmbeddings(directory);
+    const retriever = new Retriever(chunks, embeddings);
+    let embedQuery;
+    if (embeddings) {
+        const provider = createProvider(queryProviderConfig(retrieval, embeddings.meta));
+        if (provider.space !== embeddings.meta.space || (embeddings.meta.backend && provider.backend !== embeddings.meta.backend))
+            throw new Error(`${provider.model} is not in the embedding space or backend of ${embeddings.meta.model}`);
+        embedQuery = async (query, signal) => (await provider.embed([query], 'query', signal))[0];
+    }
+    return { retriever, embedQuery };
+}

package/dist/scaffold.d.ts

@@ -4,6 +4,7 @@ export type ScaffoldInput = {
     summary: string;
     slug: string;
     operations?: string[];
+    product?: string;
     channel?: string;
     version?: string;
     language?: string;
@@ -19,8 +20,9 @@ export declare function scaffold(configFile: string, templateId: string, targetF
     id: string;
     file: string;
     publication: {
-        channel: any;
-        version: any;
+        product?: string;
+        channel: string;
+        version: string;
         language: string;
     };
     access: string;
@@ -31,8 +33,9 @@ export declare function scaffoldFromPath(configFile: string, templateId: string,
     id: string;
     file: string;
     publication: {
-        channel: any;
-        version: any;
+        product?: string;
+        channel: string;
+        version: string;
         language: string;
     };
     access: string;

package/dist/scaffold.js

@@ -1,3 +1,5 @@
+import { resolvePublication } from './compiler-config.js';
+import { samePublication } from './publication-identity.js';
 import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -100,14 +102,12 @@ export async function scaffold(configFile, templateId, targetFile, input) {
         if (!knownOperations.has(operation))
             throw new Error(`Unknown scaffold operation ${operation}`);
     const defaults = config.publications?.defaults;
-    const applicability = resolveFrontmatter(Object.fromEntries(Object.entries({ channel: input.channel, version: input.version, language: input.language }).filter(([, value]) => value !== undefined)), config.frontmatter);
-    const channel = applicability.channel ?? defaults?.channel;
-    const version = applicability.version ?? defaults?.version;
-    const language = applicability.language ?? defaultLanguage(config);
-    if (!channel || !version || !language)
-        throw new Error('Scaffold needs channel, version, and language');
-    if (!config.publications?.enabled?.some((item) => item.channel === channel && item.version === version && (item.language ?? defaultLanguage(config)) === language))
-        throw new Error(`Scaffold publication ${channel}/${version}/${language} is not enabled`);
+    const applicability = resolveFrontmatter(Object.fromEntries(Object.entries({ product: input.product, channel: input.channel, version: input.version, language: input.language }).filter(([, value]) => value !== undefined)), config.frontmatter);
+    const product = config.publications?.products ? applicability.product ?? defaults?.product : undefined;
+    const publication = resolvePublication(config.publications, { ...applicability, product, ...(product ? { product, version: config.frontmatter?.enforced?.version ?? input.version } : {}), channel: applicability.channel ?? defaults?.channel }, defaultLanguage(config));
+    const { channel, version, language } = publication;
+    if (!config.publications?.enabled?.some((item) => samePublication(resolvePublication(config.publications, item, defaultLanguage(config)), publication)))
+        throw new Error(`Scaffold publication ${product ? product + '/' : ''}${channel}/${version}/${language} is not enabled`);
     const root = path.dirname(path.resolve(configFile));
     const contentDir = await canonicalPath(path.resolve(root, config.site?.contentDir ?? 'content'));
     const target = await canonicalPath(targetFile);
@@ -118,13 +118,13 @@ export async function scaffold(configFile, templateId, targetFile, input) {
         ? path.resolve(path.dirname(explainSegments(loaded, ['templates', templateId, 'body']).source.file), template.body)
         : path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../templates', template.body);
     const { header, body } = splitTemplate(await readFile(bodyFile, 'utf8'), bodyFile);
-    const frontmatter = { id: input.id, title: input.title, summary: input.summary, type: template.type, slug: input.slug, channel, version, language, ...(input.operations?.length ? { operations: input.operations } : {}), access: { policy: 'draft' } };
-    routeFor(frontmatter, { channel, version, language }, config);
+    const frontmatter = { id: input.id, title: input.title, summary: input.summary, type: template.type, slug: input.slug, ...publication, ...(!config.publications?.products && applicability.product ? { product: applicability.product } : {}), ...(input.operations?.length ? { operations: input.operations } : {}), access: { policy: 'draft' } };
+    routeFor(frontmatter, publication, config);
     const written = header ? fillTemplateHeader(header, frontmatter) : YAML.stringify(frontmatter);
     const content = `---\n${written.replace(/\s*$/, '\n')}---\n\n${body.trimStart().replace(/\s*$/, '\n')}`;
     await mkdir(path.dirname(target), { recursive: true });
     await writeFile(target, content, { flag: 'wx' });
-    return { status: 'ok', template: templateId, id: input.id, file: target, publication: { channel, version, language }, access: 'draft' };
+    return { status: 'ok', template: templateId, id: input.id, file: target, publication, access: 'draft' };
 }
 export async function scaffoldFromPath(configFile, templateId, targetFile, overrides = {}) {
     const loaded = await loadConfig(configFile);
@@ -137,14 +137,14 @@ export async function scaffoldFromPath(configFile, templateId, targetFile, overr
     if (parts.some(part => !part))
         throw new Error('Scaffold target needs a usable filename');
     const title = parts.at(-1).split('-').map(word => word[0].toUpperCase() + word.slice(1)).join(' ');
-    const selected = resolveFrontmatter(Object.fromEntries(Object.entries({ channel: overrides.channel, version: overrides.version, language: overrides.language }).filter(([, value]) => value !== undefined)), config.frontmatter);
-    const channel = selected.channel ?? config.publications?.defaults?.channel;
-    const version = selected.version ?? config.publications?.defaults?.version;
-    const language = selected.language ?? defaultLanguage(config);
+    const selected = resolveFrontmatter(Object.fromEntries(Object.entries({ product: overrides.product, channel: overrides.channel, version: overrides.version, language: overrides.language }).filter(([, value]) => value !== undefined)), config.frontmatter);
+    const product = config.publications?.products ? selected.product ?? config.publications?.defaults?.product : undefined;
+    const { channel, version, language } = resolvePublication(config.publications, { ...selected, product, ...(product ? { product, version: config.frontmatter?.enforced?.version ?? overrides.version } : {}), channel: selected.channel ?? config.publications?.defaults?.channel }, defaultLanguage(config));
     const prefixGroups = [
         language === defaultLanguage(config) ? '' : language,
+        product ? config.publications.products[product].pathPrefix : '',
         config.publications?.channels?.[channel]?.pathPrefix ?? '',
-        config.publications?.versions?.[version]?.pathPrefix ?? ''
+        (product ? config.publications.products[product].versions : config.publications?.versions)?.[version]?.pathPrefix ?? ''
     ].map(value => value.split('/').filter(Boolean));
     const prefixCandidates = [];
     for (let start = 0; start < prefixGroups.length; start++) {

package/dist/search-function.d.ts

@@ -0,0 +1,2 @@
+import { type AskFunction } from './function-runtime.js';
+export declare function createHostedSearchFunction(directory: string, env?: NodeJS.ProcessEnv): Promise<AskFunction>;

package/dist/search-function.js

@@ -0,0 +1,30 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { DailyBudget, SharedRateLimit } from './budget.js';
+import { envBudgetStore } from './budget-store.js';
+import { validateReaderFilters } from './reader-filters.js';
+import { createSearchHandler } from './search-handler.js';
+import { validateSearch } from './search-config.js';
+import { prepareSearchRetrieval } from './retrieval-runtime.js';
+import { allowedHosts } from './function-runtime.js';
+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);
+    // Accept old function metadata while new builds omit the chat configuration.
+    const legacy = runtime.settings.chat;
+    const settings = runtime.searchStore ?? legacy?.budget?.store;
+    if (!settings || typeof settings !== 'object' || !('provider' in settings) || settings.provider !== 'upstash' || !('urlEnv' in settings) || typeof settings.urlEnv !== 'string' || !('tokenEnv' in settings) || typeof settings.tokenEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(settings.urlEnv) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(settings.tokenEnv))
+        throw new Error('Hosted semantic search needs a shared budget store');
+    const setup = await prepareSearchRetrieval(path.join(directory, 'site'), runtime.settings);
+    const store = envBudgetStore({ urlEnv: settings.urlEnv, tokenEnv: settings.tokenEnv }, env);
+    const { limits } = validateSearch(runtime.settings.search);
+    return createSearchHandler({
+        ...setup, 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: request => request.headers.get(runtime.callerHeader ?? 'x-vercel-forwarded-for')?.split(',')[0].trim() || 'unknown'
+    });
+}

package/dist/search-handler.js

@@ -1,7 +1,7 @@
 import { compareHits } from './retrieval.js';
 import { validateReaderSelection } from './reader-filters.js';
-import { searchSnippetFromParagraphs } from './search-snippet.js';
-import { identifierMatch } from './search-identifier.js';
+import { searchSnippetFromParagraphs } from './search-text.js';
+import { identifierMatch } from './search-identifier-core.js';
 import { createSearchResultSelector } from './search-results.js';
 export function createSearchHandler(options) {
     const selectResults = createSearchResultSelector(options.retriever);

package/dist/search-identifier-core.d.ts

@@ -0,0 +1,4 @@
+import type { Hit } from './retrieval.js';
+export declare function searchIdentifiers(query: string): string[];
+export declare function identifierRescue<T extends Hit>(query: string, semantic: T[], lexical: T[], paragraphs?: (hit: Hit) => string[]): T[];
+export declare function identifierMatch(query: string, paragraphs?: (hit: Hit) => string[]): ((hit: Hit) => boolean) | undefined;

package/dist/search-identifier-core.js

@@ -0,0 +1,30 @@
+// Reserve at most one search-box result for a literal configuration key or flag
+// explained in prose. Tables, code listings and identifier prefixes do not qualify.
+export function searchIdentifiers(query) {
+    const identifiers = query.match(/\b[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+\b|--[a-z][\w-]*/g) ?? [];
+    // File names and URLs need ordinary retrieval, not a config-key shortcut.
+    return [...new Set(identifiers.filter(id => !/\.(?:txt|json|ya?ml|mdx?|[cm]?js|tsx?|html?|css|svg|png|jpe?g|com|org|net)$/i.test(id)))];
+}
+export function identifierRescue(query, semantic, lexical, paragraphs) {
+    const matches = identifierMatch(query, paragraphs);
+    if (!matches)
+        return semantic;
+    const candidate = lexical.find(matches);
+    if (!candidate)
+        return semantic;
+    const pages = [...new Set(semantic.map(h => h.chunk.docId))];
+    if (pages.slice(0, 3).includes(candidate.chunk.docId))
+        return semantic;
+    const remaining = semantic.filter(h => h.chunk.docId !== candidate.chunk.docId);
+    const seen = new Set();
+    const at = remaining.findIndex(hit => { seen.add(hit.chunk.docId); return seen.size === 3; });
+    const position = at < 0 ? remaining.length : at;
+    return [...remaining.slice(0, position), candidate, ...remaining.slice(position)];
+}
+export function identifierMatch(query, paragraphs = hit => hit.chunk.search?.paragraphs ?? []) {
+    const identifiers = searchIdentifiers(query);
+    if (!identifiers.length)
+        return undefined;
+    const matches = identifiers.map(id => new RegExp(`(?<![\\w$.-])${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w$-]|\\.[\\w$])`, 'i'));
+    return hit => paragraphs(hit).some(p => matches.every(re => re.test(p)));
+}

package/dist/search-identifier.d.ts

@@ -1,4 +1,4 @@
 import type { Hit } from './retrieval.js';
-export declare function searchIdentifiers(query: string): string[];
-export declare function identifierRescue<T extends Hit>(query: string, semantic: T[], lexical: T[]): T[];
-export declare function identifierMatch(query: string): ((hit: Hit) => boolean) | undefined;
+export { searchIdentifiers } from './search-identifier-core.js';
+export declare const identifierMatch: (query: string) => ((hit: Hit) => boolean) | undefined;
+export declare const identifierRescue: <T extends Hit>(query: string, semantic: T[], lexical: T[]) => T[];

package/dist/search-identifier.js

@@ -1,31 +1,8 @@
 import { searchParagraphs } from './search-snippet.js';
-// Reserve at most one search-box result for a literal configuration key or flag
-// explained in prose. Tables, code listings and identifier prefixes do not qualify.
-export function searchIdentifiers(query) {
-    const identifiers = query.match(/\b[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+\b|--[a-z][\w-]*/g) ?? [];
-    // File names and URLs need ordinary retrieval, not a config-key shortcut.
-    return [...new Set(identifiers.filter(id => !/\.(?:txt|json|ya?ml|mdx?|[cm]?js|tsx?|html?|css|svg|png|jpe?g|com|org|net)$/i.test(id)))];
-}
-export function identifierRescue(query, semantic, lexical) {
-    const matches = identifierMatch(query);
-    if (!matches)
-        return semantic;
-    const candidate = lexical.find(matches);
-    if (!candidate)
-        return semantic;
-    const pages = [...new Set(semantic.map(h => h.chunk.docId))];
-    if (pages.slice(0, 3).includes(candidate.chunk.docId))
-        return semantic;
-    const remaining = semantic.filter(h => h.chunk.docId !== candidate.chunk.docId);
-    const seen = new Set();
-    const at = remaining.findIndex(hit => { seen.add(hit.chunk.docId); return seen.size === 3; });
-    const position = at < 0 ? remaining.length : at;
-    return [...remaining.slice(0, position), candidate, ...remaining.slice(position)];
-}
-export function identifierMatch(query) {
-    const identifiers = searchIdentifiers(query);
-    if (!identifiers.length)
-        return undefined;
-    const matches = identifiers.map(id => new RegExp(`(?<![\\w$.-])${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w$-]|\\.[\\w$])`, 'i'));
-    return hit => (hit.chunk.search?.paragraphs ?? searchParagraphs(hit.chunk.text)).some(p => matches.every(re => re.test(p)));
-}
+import { identifierMatch as preparedMatch, identifierRescue as preparedRescue } from './search-identifier-core.js';
+export { searchIdentifiers } from './search-identifier-core.js';
+// Keep the older unprepared-passage API usable by local callers. Hosted search
+// imports the prepared core and never needs a Markdown parser at request time.
+const paragraphs = (hit) => hit.chunk.search?.paragraphs ?? searchParagraphs(hit.chunk.text);
+export const identifierMatch = (query) => preparedMatch(query, paragraphs);
+export const identifierRescue = (query, semantic, lexical) => preparedRescue(query, semantic, lexical, paragraphs);

package/dist/search-literal.js

@@ -1,4 +1,4 @@
-import { searchIdentifiers } from './search-identifier.js';
+import { searchIdentifiers } from './search-identifier-core.js';
 const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 const boundary = (value) => new RegExp(`(?<![\\w$.-])${escape(value)}(?![\\w$-]|\\.[\\w$])`, 'i');
 // Only explicit technical syntax gets this exception. Ordinary topic words must

package/dist/search-query.d.ts

@@ -1,4 +1,5 @@
 export type SearchOptions = {
+    product?: string;
     channel?: string;
     version?: string;
     language?: string;
@@ -7,22 +8,14 @@ export type SearchOptions = {
 export declare function queryBuiltSite(directory: string, query: string, options?: SearchOptions): Promise<{
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: import("./publication-identity.js").PublicationCoordinate;
     total: number;
     results: never[];
     matchMode?: undefined;
 } | {
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: import("./publication-identity.js").PublicationCoordinate;
     total: number;
     matchMode: string;
     results: {
@@ -46,6 +39,7 @@ export declare function queryBuiltSite(directory: string, query: string, options
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };

package/dist/search-query.js

@@ -1,3 +1,4 @@
+import { parsePublicationKey } from './publication-identity.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { phraseMatches, queryUnits, validateSearchSynonyms } from './search-synonyms.js';
@@ -30,18 +31,18 @@ export async function queryBuiltSite(directory, query, options = {}) {
         throw new Error('Unsupported or invalid search-index.json');
     const synonyms = validateSearchSynonyms(index.synonyms);
     const matching = index.documents.filter(doc => {
-        const [channel, version, language] = doc.variant.split('|');
-        return (!options.channel || channel === options.channel) && (!options.version || version === options.version) && (!options.language || language === options.language);
+        const { product, channel, version, language } = parsePublicationKey(doc.variant);
+        return (!options.product || product === options.product) && (!options.channel || channel === options.channel) && (!options.version || version === options.version) && (!options.language || language === options.language);
     });
     const variants = [...new Set(matching.map(doc => doc.variant))].sort();
     if (!variants.length)
         throw new Error('No search documents match the selected publication');
     if (variants.length > 1)
-        throw new Error(`Search matches multiple publications (${variants.join(', ')}); pass --channel, --version, and --language`);
+        throw new Error(`Search matches multiple publications (${variants.join(', ')}); pass --product where applicable, --channel, --version, and --language`);
     const terms = queryUnits(query, synonyms);
     if (!terms.length) {
-        const [channel, version, language] = variants[0].split('|');
-        return { status: 'ok', query: query.trim(), publication: { channel, version, language }, total: 0, results: [] };
+        const publication = parsePublicationKey(variants[0]);
+        return { status: 'ok', query: query.trim(), publication, total: 0, results: [] };
     }
     const match = (value, unit) => phraseMatches(value, unit.term) || unit.alternatives.some(term => phraseMatches(value, term));
     // Page titles are short subject labels, often singular. Accept a plain final
@@ -78,10 +79,10 @@ export async function queryBuiltSite(directory, query, options = {}) {
         // A complete multiword section-title match outranks incidental page-title words.
         if (meaningful.length >= 2 && candidates.some(candidate => meaningful.every(term => match(candidate.title.toLocaleLowerCase(), term))))
             score += 20;
-        const [channel, version, language] = doc.variant.split('|');
+        const { product, channel, version, language } = parsePublicationKey(doc.variant);
         const tokens = selected?.markdownTokens ?? doc.markdownTokens;
         const read = { tool: selected ? 'get_section' : 'get_page', arguments: {
-                id: doc.id, ...(selected ? { section: selected.id } : {}), channel, version, language,
+                id: doc.id, ...(selected ? { section: selected.id } : {}), ...(product === undefined ? {} : { product }), channel, version, language,
                 ...(tokens !== undefined ? { maxTokens: Math.min(100_000, Math.max(4096, tokens * 2 + 1024)) } : {}),
             } };
         return [{ score, contentScore, prominentMatches, matched: matched.length, partialMatched: matched.filter(term => !fallbackStopWords.has(term.term)).length, id: doc.id, type: doc.type, title: doc.title, summary: doc.summary, url: section ? `${doc.url}#${section.id}` : doc.url, markdownUrl: selected?.markdownUrl ?? doc.markdownUrl, pageMarkdownUrl: doc.markdownUrl, read, ...(tokens !== undefined ? { markdownTokens: tokens, markdownBytes: selected?.markdownBytes ?? doc.markdownBytes, markdownTokenEncoding: doc.markdownTokenEncoding } : {}), ...(selected || section ? { section: selected?.title ?? section?.title } : {}), snippet: excerpt(doc.text, terms.flatMap(unit => [unit.term, ...unit.alternatives])) }];
@@ -115,6 +116,6 @@ export async function queryBuiltSite(directory, query, options = {}) {
         }
         return (complete.length ? b.matched - a.matched : b.partialMatched - a.partialMatched) || b.score - a.score || a.title.localeCompare(b.title) || a.id.localeCompare(b.id);
     });
-    const [channel, version, language] = variants[0].split('|');
-    return { status: 'ok', query: query.trim(), publication: { channel, version, language }, total: ranked.length, matchMode: stronger.length ? 'mixed' : complete.length ? 'all' : 'partial', results: ranked.slice(0, limit).map(({ matched, partialMatched, contentScore, prominentMatches, ...result }) => result) };
+    const publication = parsePublicationKey(variants[0]);
+    return { status: 'ok', query: query.trim(), publication, total: ranked.length, matchMode: stronger.length ? 'mixed' : complete.length ? 'all' : 'partial', results: ranked.slice(0, limit).map(({ matched, partialMatched, contentScore, prominentMatches, ...result }) => result) };
 }

package/dist/search-results.js

@@ -1,6 +1,6 @@
 import { compareHits, tokenize } from './retrieval.js';
 import { literalSearch } from './search-literal.js';
-import { identifierRescue } from './search-identifier.js';
+import { identifierRescue } from './search-identifier-core.js';
 // Select landing passages for the search box, without changing passage retrieval
 // used by Ask. A gallery's repeated examples must not crowd other pages out.
 export function createSearchResultSelector(retriever) {

package/dist/search-snippet.d.ts

@@ -1,3 +1,4 @@
+export { searchSnippetFromParagraphs } from './search-text.js';
 export declare function searchParagraphs(markdown: string): string[];
 export declare function searchPassageParagraphs(markdown: string): string[];
 export declare function searchLiteralLines(markdown: string): string[];
@@ -8,4 +9,3 @@ export type PreparedSearchPassage = {
 };
 export declare function prepareSearchPassage(markdown: string): PreparedSearchPassage;
 export declare function searchSnippet(markdown: string, query: string, pageSummary?: string): string;
-export declare function searchSnippetFromParagraphs(choices: string[], query: string, pageSummary?: string): string;

package/dist/search-snippet.js

@@ -1,3 +1,5 @@
+import { searchSnippetFromParagraphs } from './search-text.js';
+export { searchSnippetFromParagraphs } from './search-text.js';
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
@@ -71,23 +73,9 @@ export function prepareSearchPassage(markdown) {
     const tree = parser.parse(markdown);
     return { schemaVersion: 1, paragraphs: passageParagraphs(tree), literalLines: cleanLines(literalLines(tree)) };
 }
-const stopWords = new Set('a an the i me my we our you your how do does can could would should will is are was were be to of in on for with please what where when why which and or it this that have has after before'.split(' '));
 // Prefer substantive query matches; Markdown boilerplate and common question words
 // must not hide a useful paragraph. Keep a matching term visible in long paragraphs.
 export function searchSnippet(markdown, query, pageSummary = '') {
     const choices = searchParagraphs(markdown).filter(p => !discovery.test(p));
     return searchSnippetFromParagraphs(choices, query, pageSummary);
 }
-export function searchSnippetFromParagraphs(choices, query, pageSummary = '') {
-    const terms = [...new Set((query.toLocaleLowerCase().match(/[\p{L}\p{N}_$.-]+/gu) ?? []).map(t => t.replace(/^[.-]+|[.-]+$/g, '')).filter(t => t && !stopWords.has(t)))];
-    const matches = (text) => terms.filter(term => new RegExp(`(?<![\\p{L}\\p{N}_])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\p{L}\\p{N}_])`, 'iu').test(text));
-    const ranked = choices.map((text, at) => ({ text, at, terms: matches(text) })).sort((a, b) => b.terms.length - a.terms.length || a.at - b.at);
-    const selected = ranked[0];
-    const text = (selected?.text ?? pageSummary).replace(/\s+/g, ' ').trim();
-    if (text.length <= 180)
-        return text;
-    const first = selected?.terms.length ? Math.min(...selected.terms.map(t => text.toLocaleLowerCase().indexOf(t))) : 0;
-    const start = Math.max(0, first - 50);
-    const length = 180 - (start ? 1 : 0) - 1;
-    return `${start ? '…' : ''}${text.slice(start, start + length).trim()}…`;
-}

package/dist/search-text.d.ts

@@ -0,0 +1 @@
+export declare function searchSnippetFromParagraphs(choices: string[], query: string, pageSummary?: string): string;

package/dist/search-text.js

@@ -0,0 +1,14 @@
+const stopWords = new Set('a an the i me my we our you your how do does can could would should will is are was were be to of in on for with please what where when why which and or it this that have has after before'.split(' '));
+export function searchSnippetFromParagraphs(choices, query, pageSummary = '') {
+    const terms = [...new Set((query.toLocaleLowerCase().match(/[\p{L}\p{N}_$.-]+/gu) ?? []).map(t => t.replace(/^[.-]+|[.-]+$/g, '')).filter(t => t && !stopWords.has(t)))];
+    const matches = (text) => terms.filter(term => new RegExp(`(?<![\\p{L}\\p{N}_])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\p{L}\\p{N}_])`, 'iu').test(text));
+    const ranked = choices.map((text, at) => ({ text, at, terms: matches(text) })).sort((a, b) => b.terms.length - a.terms.length || a.at - b.at);
+    const selected = ranked[0];
+    const text = (selected?.text ?? pageSummary).replace(/\s+/g, ' ').trim();
+    if (text.length <= 180)
+        return text;
+    const first = selected?.terms.length ? Math.min(...selected.terms.map(t => text.toLocaleLowerCase().indexOf(t))) : 0;
+    const start = Math.max(0, first - 50);
+    const length = 180 - (start ? 1 : 0) - 1;
+    return `${start ? '…' : ''}${text.slice(start, start + length).trim()}…`;
+}

package/dist/server.d.ts

@@ -1,10 +1,18 @@
 import { type Server, type ServerResponse } from 'node:http';
+export type PreviewStatus = {
+    profile?: string;
+    profileDigest?: string;
+    buildId?: string;
+    error?: string;
+};
 export type SiteExtras = {
     ask?: (request: Request) => Promise<Response>;
     search?: (request: Request) => Promise<Response>;
     widget?: string;
     publicSettings?: Record<string, unknown>;
     panel?: Record<string, string>;
+    preview?: PreviewStatus;
 };
+export declare function previewMarkup(basePath: string, preview?: PreviewStatus): string;
 export declare function createSiteServer(directory: string, liveClients?: Set<ServerResponse>, extras?: SiteExtras): Promise<Server>;
 export declare function serveSite(directory: string, host: string, port: number, liveClients?: Set<ServerResponse>, extras?: SiteExtras): Promise<Server>;