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

package/dist/dev.js

@@ -1,8 +1,18 @@
-import { watch } from 'node:fs';
+import { statSync, watch } from 'node:fs';
 import path from 'node:path';
 import { compile } from './compiler.js';
 import { serveSite } from './server.js';
-export async function startDev(configFile, outputDirectory, host = '127.0.0.1', port = 8765) {
+import { homeUrl } from './negotiation.js';
+function dependencyStamp(file) {
+    try {
+        const info = statSync(file, { bigint: true });
+        return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}:${info.mode}`;
+    }
+    catch (error) {
+        return `missing:${error.code ?? 'unknown'}`;
+    }
+}
+export async function startDev(configFile, outputDirectory, host = '127.0.0.1', port = 8765, options = {}) {
     const config = path.resolve(configFile);
     const root = path.dirname(config);
     const output = path.resolve(outputDirectory);
@@ -10,29 +20,63 @@ export async function startDev(configFile, outputDirectory, host = '127.0.0.1',
     const stagingPrefix = `${output}.staging-`;
     const ignored = new Set(['.git', '.shoalrun', 'node_modules']);
     const clients = new Set();
-    const initial = await compile(config, output);
-    const server = await serveSite(output, host, port, clients);
+    const profile = options.profile ? path.resolve(options.profile) : undefined;
+    const initialStamps = new Map();
+    const initial = await compile(config, output, {}, { profile, onDependency: file => {
+            const resolved = path.resolve(file);
+            if (!initialStamps.has(resolved))
+                initialStamps.set(resolved, dependencyStamp(resolved));
+        } });
+    let successfulDependencies = initial.dependencies;
+    const preview = { ...(profile ? { profile: path.basename(profile) } : {}), buildId: initial.buildId, profileDigest: initial.profileSelection?.profileDigest };
+    const server = await serveSite(output, host, port, clients, { preview });
     process.stdout.write(`Preview: http://${host}:${server.address().port}/\n`);
     let timer;
     let dirty = false;
     let running = false;
+    let closed = false;
     const external = new Map();
+    const dependencyStamps = new Map();
     const changed = () => {
+        if (closed)
+            return;
         dirty = true;
         if (timer)
             clearTimeout(timer);
         timer = setTimeout(() => { void rebuild(); }, 180);
     };
     const refreshExternal = (dependencies) => {
+        if (closed)
+            return;
         const needed = new Map();
-        for (const dependency of dependencies) {
+        const files = new Set();
+        for (const dependency of [...dependencies, ...(profile ? [profile] : [])]) {
             const file = path.resolve(dependency);
+            files.add(file);
+            if (!dependencyStamps.has(file))
+                dependencyStamps.set(file, initialStamps.get(file) ?? dependencyStamp(file));
             if (file === root || (file.startsWith(`${root}${path.sep}`) && !path.relative(root, file).split(path.sep).some(part => ignored.has(part))))
                 continue;
-            const parent = path.dirname(file);
+            let parent = path.dirname(file);
+            // A missing asset may also have missing parent directories. Watch its
+            // nearest existing directory, filtered to the next declared component.
+            while (true) {
+                try {
+                    if (statSync(parent).isDirectory())
+                        break;
+                }
+                catch (error) {
+                    if (!['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+                        throw error;
+                }
+                const next = path.dirname(parent);
+                if (next === parent)
+                    throw new Error(`No watchable parent for ${file}`);
+                parent = next;
+            }
             if (!needed.has(parent))
                 needed.set(parent, new Set());
-            needed.get(parent).add(path.basename(file));
+            needed.get(parent).add(path.relative(parent, file).split(path.sep)[0]);
         }
         for (const [directory, value] of external)
             if (!needed.has(directory)) {
@@ -46,27 +90,50 @@ export async function startDev(configFile, outputDirectory, host = '127.0.0.1',
                 continue;
             }
             const entry = { names, watcher: undefined };
-            entry.watcher = watch(directory, (_event, filename) => { if (!filename || entry.names.has(filename.toString()))
-                changed(); });
+            entry.watcher = watch(directory, (_event, filename) => {
+                if (!filename || entry.names.has(filename.toString())) {
+                    const file = filename ? path.resolve(directory, filename.toString()) : undefined;
+                    if (file && dependencyStamps.has(file))
+                        dependencyStamps.set(file, dependencyStamp(file));
+                    changed();
+                }
+            });
             entry.watcher.on('error', error => process.stderr.write(`Watch failed: ${error.message}\n`));
             external.set(directory, entry);
         }
+        for (const file of dependencyStamps.keys())
+            if (!files.has(file))
+                dependencyStamps.delete(file);
+        initialStamps.clear();
     };
     const rebuild = async () => {
         if (running)
             return;
         running = true;
-        while (dirty) {
+        while (dirty && !closed) {
             dirty = false;
+            const discovered = new Set();
             try {
-                const manifest = await compile(config, output);
+                const manifest = await compile(config, output, {}, { profile, onDependency: file => discovered.add(file) });
+                preview.buildId = manifest.buildId;
+                preview.profileDigest = manifest.profileSelection?.profileDigest;
+                delete preview.error;
+                successfulDependencies = manifest.dependencies;
                 refreshExternal(manifest.dependencies);
                 process.stdout.write(`Built ${manifest.documents.length} documents\n`);
+                const update = { routes: manifest.documents.map(document => document.url), home: homeUrl(manifest.documents) };
                 for (const client of clients)
-                    client.write('event: built\ndata: {}\n\n');
+                    client.write(`event: built\ndata: ${JSON.stringify(update)}\n\n`);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                preview.error = message;
+                try {
+                    refreshExternal([...successfulDependencies, ...discovered]);
+                }
+                catch (watchError) {
+                    process.stderr.write(`Watch failed: ${watchError instanceof Error ? watchError.message : String(watchError)}\n`);
+                }
                 process.stderr.write(`Build failed: ${message}\n`);
                 for (const client of clients)
                     client.write(`event: failed\ndata: ${JSON.stringify({ message })}\n\n`);
@@ -84,6 +151,8 @@ export async function startDev(configFile, outputDirectory, host = '127.0.0.1',
                 const file = path.resolve(root, filename.toString());
                 if (file === output || file === `${output}.shoalrun.lock` || file.startsWith(outputPrefix) || file.startsWith(stagingPrefix))
                     return;
+                if (dependencyStamps.has(file))
+                    dependencyStamps.set(file, dependencyStamp(file));
             }
             changed();
         });
@@ -96,8 +165,24 @@ export async function startDev(configFile, outputDirectory, host = '127.0.0.1',
         throw error;
     }
     watcher.on('error', error => process.stderr.write(`Watch failed: ${error.message}\n`));
+    // Native directory notifications can be coalesced or lost, especially just
+    // after registration. Poll only the exact declared build dependencies as
+    // a fallback; seed their stamps synchronously so the first edit is observed.
+    const polling = setInterval(() => {
+        if (closed)
+            return;
+        for (const [file, previous] of dependencyStamps) {
+            const current = dependencyStamp(file);
+            if (current !== previous) {
+                dependencyStamps.set(file, current);
+                changed();
+            }
+        }
+    }, 500);
+    polling.unref();
     const close = server.close.bind(server);
     server.close = ((callback) => {
+        closed = true;
         for (const client of clients)
             client.end();
         return close(callback);
@@ -106,6 +191,8 @@ export async function startDev(configFile, outputDirectory, host = '127.0.0.1',
         watcher.close();
         for (const entry of external.values())
             entry.watcher.close();
+        dependencyStamps.clear();
+        clearInterval(polling);
         if (timer)
             clearTimeout(timer);
     });

package/dist/docs-author.js

@@ -1,3 +1,4 @@
+import { documentKey } from './publication-identity.js';
 import { validateAuthoringGuidance } from './authoring-guidance.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { chmod, cp, link, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
@@ -350,7 +351,7 @@ export async function docsApply(planFile, configFile, checkOnly, options = {}) {
                 if (!rendered.documents.some(doc => doc.id === id))
                     throw new Error(`Candidate excluded from rendering: ${id}`);
         }
-        const key = (doc) => `${doc.id}|${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`;
+        const key = (doc) => documentKey(doc.id, doc.variant);
         const oldDocs = new Map(before?.documents.map(doc => [key(doc), doc]) ?? []);
         const newDocs = new Map(result.documents.map(doc => [key(doc), doc]));
         const affected = [...new Set([...oldDocs.keys(), ...newDocs.keys()])].filter(id => {

package/dist/docs-command.js

@@ -20,7 +20,7 @@ export function parseDocsReadOptions(args, mcp = false) {
             continue;
         }
         const value = args[++i];
-        if (!(mcp ? ['--site'] : ['--site', '--max-tokens', '--limit', '--channel', '--version', '--language']).includes(flag) || !value || value.startsWith('--'))
+        if (!(mcp ? ['--site'] : ['--site', '--max-tokens', '--limit', '--product', '--channel', '--version', '--language']).includes(flag) || !value || value.startsWith('--'))
             throw new DocumentationError('invalid_input', `Unknown option or missing value for ${flag}`);
         if (flag === '--site')
             directory = path.resolve(value);
@@ -40,7 +40,7 @@ export async function runDocsReadCommand(command, args) {
         const parsed = parseDocsReadOptions(args);
         json = json || parsed.json;
         if (!parsed.positional.length || command !== 'search' && parsed.positional.length !== (command === 'section' ? 2 : 1) || command !== 'search' && parsed.options.limit !== undefined)
-            throw new DocumentationError('invalid_input', `Usage: shoalrun docs ${command} <${command === 'search' ? 'query' : command === 'section' ? 'document-id> <section-id' : 'document-id'}> [--site DIRECTORY] [--json] [--max-tokens N] [--channel C --version V --language L]${command === 'search' ? ' [--limit N]' : ''}`);
+            throw new DocumentationError('invalid_input', `Usage: shoalrun docs ${command} <${command === 'search' ? 'query' : command === 'section' ? 'document-id> <section-id' : 'document-id'}> [--site DIRECTORY] [--json] [--max-tokens N] [--product P --channel C --version V --language L]${command === 'search' ? ' [--limit N]' : ''}`);
         const result = command === 'search'
             ? await searchDocumentation(parsed.directory, parsed.positional.join(' '), parsed.options)
             : command === 'outline' ? await getDocumentationOutline(parsed.directory, parsed.positional[0], parsed.options)

package/dist/docs-eval.d.ts

@@ -14,6 +14,7 @@ export type EvalTasks = {
     tasks: EvalTask[];
 };
 type Publication = {
+    product?: string;
     channel: string;
     version: string;
     language: string;

package/dist/docs-eval.js

@@ -89,8 +89,8 @@ export function parseEvalReport(value) {
             throw new Error(`${where} requires status pass/fail/skipped, a text answer, citations, and criteria`);
         const citations = result.citations.map((value, j) => {
             const cite = mapping(value, `${where}.citations[${j}]`, ['id', 'publication']);
-            const publication = mapping(cite.publication, `${where}.citations[${j}].publication`, ['channel', 'version', 'language']);
-            return { id: text(cite.id, `${where}.citations[${j}].id`), publication: { channel: text(publication.channel, 'citation.channel'), version: text(publication.version, 'citation.version'), language: text(publication.language, 'citation.language') } };
+            const publication = mapping(cite.publication, `${where}.citations[${j}].publication`, ['product', 'channel', 'version', 'language']);
+            return { id: text(cite.id, `${where}.citations[${j}].id`), publication: { ...(publication.product === undefined ? {} : { product: text(publication.product, 'citation.product') }), channel: text(publication.channel, 'citation.channel'), version: text(publication.version, 'citation.version'), language: text(publication.language, 'citation.language') } };
         });
         const criteria = unique(result.criteria.map((value, j) => {
             const judgment = mapping(value, `${where}.criteria[${j}]`, ['id', 'status', 'reason']);

package/dist/docs-mcp.d.ts

@@ -1,6 +1,7 @@
 import { type McpAnalyticsEvent } from './mcp-analytics.js';
 import { McpServer } from '@modelcontextprotocol/server';
 export declare function createDocsMcpServer(directory?: string, publication?: {
+    product?: string;
     channel: string;
     version: string;
     language: string;

package/dist/docs-mcp.js

@@ -3,20 +3,20 @@ import { attemptAnalytics } from './mcp-analytics.js';
 import { McpServer } from '@modelcontextprotocol/server';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
-import { bundledDocumentation, DocumentationError, documentationFailure, getDocumentationOutline, getDocumentationSection, getDocumentationPage, searchDocumentation } from './documentation-core.js';
+import { bundledDocumentation, DocumentationError, documentationFailure, getDocumentationOutline, getDocumentationSection, getDocumentationPage, listDocumentationPublications, searchDocumentation } from './documentation-core.js';
 export function createDocsMcpServer(directory = bundledDocumentation, publication, analytics, discardAnalyticsArguments = false) {
     const server = new McpServer({ name: 'shoalrun-docs', version: '0.0.0' }, { maxToolInputElements: 1024 });
     const scope = (filters) => {
         if (!publication)
             return filters;
-        for (const key of ['channel', 'version', 'language'])
+        for (const key of ['product', 'channel', 'version', 'language'])
             if (filters[key] !== undefined && filters[key] !== publication[key])
                 throw new DocumentationError('invalid_input', 'This MCP endpoint serves a different publication');
         return { ...filters, ...publication };
     };
     const coordinate = (key) => z.string().optional().describe(publication ? `This endpoint serves ${key}=${publication[key]}; omit this argument or pass that exact value.` : `Select the documentation ${key}.`);
     const options = {
-        channel: coordinate('channel'), version: coordinate('version'), language: coordinate('language'),
+        product: coordinate('product'), channel: coordinate('channel'), version: coordinate('version'), language: coordinate('language'),
         maxTokens: z.number().int().min(256).max(100_000).default(4096).describe('Maximum serialized result tokens, counted with cl100k_base, including metadata.'),
     };
     // A client may cache the instrumented schema after withdrawing consent.
@@ -57,13 +57,18 @@ export function createDocsMcpServer(directory = bundledDocumentation, publicatio
                 await attemptAnalytics(() => analytics.capture({ name: 'mcp_tool_call', ...(analytics.clientMetadata ? mcpClientMetadata(context, server.server.getClientVersion()) : {}), tool, durationMs: Math.max(0, performance.now() - start), isError, ...(errorCode ? { errorCode } : {}), ...(pageId ? { pageId } : {}), ...(sectionId ? { sectionId } : {}), buildId: analytics.buildId, publication: { ...publication } }));
         }
     };
+    server.registerTool('get_publications', {
+        description: 'Discover available product/channel/version/language coordinates before searching. Returns one compact page and concise product defaults; follow nextOffset for more. Products have independent versions. Preserve the selected product and publication coordinates in subsequent search and read calls. This endpoint lists only its published scope.',
+        inputSchema: schema(z.object({ ...options, maxTokens: z.number().int().min(256).max(100_000).default(2048), limit: z.number().int().min(1).max(100).default(20), offset: z.number().int().min(0).default(0) }).strict()),
+        annotations,
+    }, (filters, context) => respond('get_publications', context, () => listDocumentationPublications(directory, { ...scope(filters), ...(publication ? { publication } : {}) })));
     server.registerTool('search_docs', {
-        description: 'Search the documentation by keyword. Partial fallback favors field relevance among results within one meaningful term of the best coverage (at least two matched). Complete lexical matches normally precede partial fallback; stronger near-complete matches can outrank body-only complete matches (matchMode: mixed). Search covers titles, summaries, headings, and bounded article text. For each chosen result, call read.tool with read.arguments exactly. Section recommendations require an author declaration of self-contained content. The result markdownUrl fetches the recommended section or full page; pageMarkdownUrl is always the full-page fallback. Do not guess a section ID or request an outline first.',
+        description: 'Search the documentation by keyword. Use get_publications to discover product/version scope when unknown. Partial fallback favors field relevance among results within one meaningful term of the best coverage (at least two matched). Complete lexical matches normally precede partial fallback; stronger near-complete matches can outrank body-only complete matches (matchMode: mixed). Search covers titles, summaries, headings, and bounded article text. For each chosen result, call read.tool with read.arguments exactly, retaining product and all publication coordinates. Section recommendations require an author declaration of self-contained content. The result markdownUrl fetches the recommended section or full page; pageMarkdownUrl is always the full-page fallback. Do not guess a section ID or request an outline first.',
         inputSchema: schema(z.object({ query: z.string(), limit: z.number().int().min(1).max(100).default(8), ...options }).strict()),
         annotations,
     }, ({ query, ...filters }, context) => respond('search_docs', context, () => searchDocumentation(directory, query, scope(filters))));
     server.registerTool('get_page', {
-        description: 'Read a published Markdown page by the stable document ID returned from search_docs. Includes all reader-marked sections. Check budget.truncated; increase maxTokens if needed.',
+        description: 'Read a published Markdown page by the stable document ID returned from search_docs. Retain its product/channel/version/language coordinates; IDs can repeat across products. Includes all reader-marked sections. Check budget.truncated; increase maxTokens if needed.',
         inputSchema: schema(z.object({ id: z.string(), ...options }).strict()),
         annotations,
     }, ({ id, ...filters }, context) => respond('get_page', context, () => getDocumentationPage(directory, id, scope(filters))));

package/dist/docs-tool.d.ts

@@ -20,6 +20,7 @@ export declare function searchShoalrunDocs(query: string): Promise<({
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };
@@ -27,11 +28,7 @@ export declare function searchShoalrunDocs(query: string): Promise<({
     }[];
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: import("./publication-identity.js").PublicationCoordinate;
     total: number;
     matchMode?: undefined;
 } | {
@@ -56,6 +53,7 @@ export declare function searchShoalrunDocs(query: string): Promise<({
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };
@@ -63,11 +61,7 @@ export declare function searchShoalrunDocs(query: string): Promise<({
     }[];
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: import("./publication-identity.js").PublicationCoordinate;
     total: number;
     matchMode: string;
 }) & {

package/dist/document-sync.d.ts

@@ -2,6 +2,7 @@ export declare function canonicalJson(value: unknown): string;
 export type SyncDocument = {
     id: string;
     variant: {
+        product?: string;
         channel: string;
         version: string;
         language: string;

package/dist/document-sync.js

@@ -5,7 +5,7 @@ export function canonicalJson(value) {
     return JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
         ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
 }
-const key = (doc) => JSON.stringify([doc.id, doc.variant.channel, doc.variant.version, doc.variant.language]);
+const key = (doc) => JSON.stringify([doc.id, doc.variant.channel, doc.variant.version, doc.variant.language, ...(doc.variant.product === undefined ? [] : [doc.variant.product])]);
 export function documentSnapshot(manifest, buildId) {
     const { documents, dependencies, buildId: _buildId, ...metadata } = manifest;
     const records = documents.map(doc => ({ id: doc.id, variant: doc.variant, url: doc.url, markdownUrl: doc.markdownUrl,
@@ -32,7 +32,7 @@ export function parseDocumentSnapshot(value) {
     const seen = new Set();
     for (const doc of value.documents) {
         const variant = object(doc) && object(doc.variant) ? doc.variant : {};
-        if (!object(doc) || typeof doc.id !== 'string' || !doc.id.trim() || !object(doc.variant) || ['channel', 'version', 'language'].some(field => typeof variant[field] !== 'string' || !variant[field].trim()) || !route(doc.url) || !route(doc.markdownUrl) || !doc.markdownUrl.endsWith('.md') || !hex(doc.digest) || !hex(doc.contentDigest) || !hex(doc.recordDigest))
+        if (!object(doc) || typeof doc.id !== 'string' || !doc.id.trim() || !object(doc.variant) || (variant.product !== undefined && (typeof variant.product !== 'string' || !variant.product.trim())) || ['channel', 'version', 'language'].some(field => typeof variant[field] !== 'string' || !variant[field].trim()) || !route(doc.url) || !route(doc.markdownUrl) || !doc.markdownUrl.endsWith('.md') || !hex(doc.digest) || !hex(doc.contentDigest) || !hex(doc.recordDigest))
             throw new Error('Invalid document sync record');
         const identity = key(doc);
         if (seen.has(identity))

package/dist/documentation-core.d.ts

@@ -1,4 +1,5 @@
 import { type SearchOptions } from './search-query.js';
+import { type PublicationCoordinate } from './publication-identity.js';
 export declare const bundledDocumentation: string;
 export type DocumentationErrorCode = 'invalid_input' | 'unknown_page' | 'unknown_section' | 'missing_index' | 'internal_error';
 export declare class DocumentationError extends Error {
@@ -16,6 +17,29 @@ export type DocumentationOptions = SearchOptions & {
     maxTokens?: number;
 };
 export declare const documentationTokens: (value: string) => number;
+/** Compact discovery of published coordinates, without returning page inventories. */
+export declare function listDocumentationPublications(directory: string, options?: DocumentationOptions & {
+    offset?: number;
+    publication?: PublicationCoordinate;
+}): Promise<{
+    nextOffset?: number | undefined;
+    products?: {
+        defaultVersion?: any;
+        label?: any;
+        id: string;
+    }[] | undefined;
+    status: "ok";
+    total: number;
+    offset: number;
+    publications: PublicationCoordinate[];
+} & {
+    budget: {
+        maxTokens: number;
+        encoding: string;
+        tokens: number;
+        truncated: boolean;
+    };
+}>;
 export declare function searchDocumentation(directory: string, query: string, options?: DocumentationOptions): Promise<({
     results: never[] | {
         snippet: string;
@@ -38,6 +62,7 @@ export declare function searchDocumentation(directory: string, query: string, op
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };
@@ -45,11 +70,7 @@ export declare function searchDocumentation(directory: string, query: string, op
     }[];
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: PublicationCoordinate;
     total: number;
     matchMode?: undefined;
 } | {
@@ -74,6 +95,7 @@ export declare function searchDocumentation(directory: string, query: string, op
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };
@@ -81,11 +103,7 @@ export declare function searchDocumentation(directory: string, query: string, op
     }[];
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: PublicationCoordinate;
     total: number;
     matchMode: string;
 }) & {
@@ -104,6 +122,7 @@ export declare function getDocumentationPage(directory: string, id: string, opti
     url: string;
     markdownUrl: string;
     publication: {
+        product?: string;
         channel: string;
         version: string;
         language: string;

package/dist/documentation-core.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { markdownTokens } from './markdown-size.js';
 import { queryBuiltSite } from './search-query.js';
+import { publicationKey, samePublication } from './publication-identity.js';
 export const bundledDocumentation = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../agent-docs');
 export class DocumentationError extends Error {
     code;
@@ -18,7 +19,7 @@ function validate(options) {
     const maxTokens = options.maxTokens ?? 4096;
     if (!Number.isSafeInteger(maxTokens) || maxTokens < 256 || maxTokens > 100_000)
         throw new DocumentationError('invalid_input', 'maxTokens must be an integer from 256 to 100000');
-    for (const key of ['channel', 'version', 'language'])
+    for (const key of ['product', 'channel', 'version', 'language'])
         if (options[key] !== undefined && (typeof options[key] !== 'string' || !options[key]?.trim() || options[key].length > 128))
             throw new DocumentationError('invalid_input', `${key} must be nonempty text of at most 128 characters`);
     return maxTokens;
@@ -45,6 +46,39 @@ async function loadJson(directory, name) {
         throw new DocumentationError('internal_error', `Cannot read valid ${name}. Rebuild the documentation.`);
     }
 }
+/** Compact discovery of published coordinates, without returning page inventories. */
+export async function listDocumentationPublications(directory, options = {}) {
+    const maxTokens = validate({ ...options, maxTokens: options.maxTokens ?? 2048 });
+    const limit = options.limit ?? 20;
+    const offset = options.offset ?? 0;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(offset) || offset < 0)
+        throw new DocumentationError('invalid_input', 'limit must be from 1 to 100 and offset must be a nonnegative safe integer');
+    const manifest = await loadJson(directory, 'documents.json');
+    const source = manifest?.publications?.enabled ?? manifest?.documents?.map((doc) => doc.variant);
+    const valid = (item) => item && typeof item === 'object' && !Array.isArray(item) && ['channel', 'version', 'language'].every(key => typeof item[key] === 'string' && item[key].length > 0 && item[key].length <= 128) && (item.product === undefined || typeof item.product === 'string' && item.product.length > 0 && item.product.length <= 128);
+    if (manifest?.schemaVersion !== 1 || !Array.isArray(source) || source.some(item => !valid(item)))
+        throw new DocumentationError('internal_error', 'Invalid publication metadata. Rebuild the documentation.');
+    const coordinates = source.map((item) => ({ channel: item.channel, version: item.version, language: item.language, ...(item.product === undefined ? {} : { product: item.product }) }));
+    const available = [...new Map(coordinates.map((item) => [publicationKey(item), item])).values()]
+        .filter(item => (!options.publication || samePublication(item, options.publication)) && ['product', 'channel', 'version', 'language'].every(key => !options[key] || item[key] === options[key]))
+        .sort((a, b) => publicationKey(a).localeCompare(publicationKey(b)));
+    const total = available.length;
+    let publications = available.slice(offset, offset + limit);
+    while (true) {
+        const products = [...new Set(publications.flatMap(item => item.product === undefined ? [] : [item.product]))].map(id => {
+            const catalog = manifest.publications?.products?.[id];
+            const defaultVersion = typeof catalog?.defaultVersion === 'string' && available.some(item => item.product === id && item.version === catalog.defaultVersion) ? catalog.defaultVersion : undefined;
+            return { id, ...(typeof catalog?.label === 'string' ? { label: catalog.label.slice(0, 160) } : {}), ...(defaultVersion === undefined ? {} : { defaultVersion }) };
+        });
+        const nextOffset = offset + publications.length < total ? offset + publications.length : undefined;
+        const result = budget({ status: 'ok', total, offset, publications, ...(products.length ? { products } : {}), ...(nextOffset === undefined ? {} : { nextOffset }) }, maxTokens, nextOffset !== undefined);
+        if (result.fits)
+            return result.result;
+        if (!publications.length || publications.length === 1)
+            throw new DocumentationError('invalid_input', 'maxTokens is too small for publication metadata. Increase the budget.');
+        publications = publications.slice(0, -1);
+    }
+}
 export async function searchDocumentation(directory, query, options = {}) {
     const maxTokens = validate(options);
     if (typeof query !== 'string' || !query.trim() || query.length > 512)
@@ -76,14 +110,14 @@ async function selectDocument(directory, id, options) {
     if (typeof id !== 'string' || !id.trim() || id.length > 256)
         throw new DocumentationError('invalid_input', 'id must be nonempty text of at most 256 characters');
     const manifest = await loadJson(directory, 'documents.json');
-    if (manifest?.schemaVersion !== 1 || !Array.isArray(manifest.documents) || manifest.documents.some((doc) => !doc || typeof doc.id !== 'string' || typeof doc.title !== 'string' || typeof doc.url !== 'string' || typeof doc.markdownUrl !== 'string' || !doc.variant || ['channel', 'version', 'language'].some(key => typeof doc.variant[key] !== 'string')))
+    if (manifest?.schemaVersion !== 1 || !Array.isArray(manifest.documents) || manifest.documents.some((doc) => !doc || typeof doc.id !== 'string' || typeof doc.title !== 'string' || typeof doc.url !== 'string' || typeof doc.markdownUrl !== 'string' || !doc.variant || (doc.variant.product !== undefined && (typeof doc.variant.product !== 'string' || !doc.variant.product)) || ['channel', 'version', 'language'].some(key => typeof doc.variant[key] !== 'string')))
         throw new DocumentationError('internal_error', 'Invalid documents.json. Rebuild the documentation.');
     const matching = manifest.documents.filter((doc) => doc.id === id);
     if (!matching.length)
         throw new DocumentationError('unknown_page', `No document with ID ${id}; search the documentation first.`);
-    const selected = matching.filter((doc) => ['channel', 'version', 'language'].every(key => !options[key] || doc.variant[key] === options[key]));
+    const selected = matching.filter((doc) => ['product', 'channel', 'version', 'language'].every(key => !options[key] || doc.variant[key] === options[key]));
     if (selected.length !== 1)
-        throw new DocumentationError('invalid_input', selected.length ? 'Page has multiple publications; select channel, version, and language.' : 'Page does not match the selected publication.');
+        throw new DocumentationError('invalid_input', selected.length ? 'Page has multiple publications; select product where applicable, channel, version, and language.' : 'Page does not match the selected publication.');
     return selected[0];
 }
 async function readMarkdown(directory, markdownUrl) {

package/dist/freshness.js

@@ -10,7 +10,7 @@ function stable(value) {
     return value;
 }
 export function contentDigest(doc, htmlTree, markdownTree) {
-    const fields = ['id', 'title', 'summary', 'description', 'type', 'slug', 'date', 'releaseVersion', 'subjectLifecycle', 'audiences', 'readerFilters', 'product', 'area', 'subarea', 'operations', 'displayText'];
+    const fields = ['id', 'title', 'summary', 'description', 'type', 'slug', 'date', 'releaseVersion', 'availability', 'subjectLifecycle', 'audiences', 'readerFilters', 'product', 'area', 'subarea', 'operations', 'displayText'];
     return createHash('sha256').update(JSON.stringify(stable({ metadata: Object.fromEntries(fields.map(key => [key, doc.frontmatter[key]])), html: htmlTree, markdown: markdownTree }))).digest('hex');
 }
 export async function loadFreshness(value, base, today = new Date().toISOString().slice(0, 10)) {
@@ -40,7 +40,7 @@ export async function loadFreshness(value, base, today = new Date().toISOString(
     const current = {};
     return {
         resolve(doc, digest, fallback) {
-            const key = JSON.stringify([doc.frontmatter.id, doc.variant.channel, doc.variant.version, doc.variant.language]);
+            const key = JSON.stringify([doc.frontmatter.id, doc.variant.channel, doc.variant.version, doc.variant.language, ...(doc.variant.product === undefined ? [] : [doc.variant.product])]);
             const previous = history.documents[key];
             const updated = previous ? previous.contentDigest === digest ? previous.updated : today : doc.frontmatter.updated ?? fallback ?? today;
             current[key] = { contentDigest: digest, updated };