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

package/dist/compiler-config.js

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

package/dist/compiler.d.ts

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

package/dist/compiler.js

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

package/dist/component-transform.d.ts

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

package/dist/component-transform.js

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

package/dist/config.d.ts

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

package/dist/config.js

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

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

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

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

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

package/dist/content-delivery-validation.js

@@ -1,3 +1,4 @@
+import { samePublication } from './publication-identity.js';
 import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
 const keys = (value, allowed) => object(value) && Object.keys(value).every(key => allowed.includes(key));
@@ -6,8 +7,7 @@ const digestPattern = /^[a-f0-9]{64}$/;
 const pathPattern = /^(?:NOTICES\.txt|(?:content|assets)\/[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*)$/;
 export const safeContentPath = (value) => typeof value === 'string' && pathPattern.test(value) && value.split('/').every(part => part !== '.' && part !== '..');
 const invalid = (message) => { throw new ContentDeliveryError('invalid_manifest', message); };
-export const validContentPublication = (value) => object(value) && Object.keys(value).length === 3 && ['channel', 'version', 'language'].every(key => nonempty(value[key]));
-const samePublication = (left, right) => ['channel', 'version', 'language'].every(key => left[key] === right[key]);
+export const validContentPublication = (value) => keys(value, ['channel', 'version', 'language', 'product']) && ['channel', 'version', 'language'].every(key => nonempty(value[key])) && (value.product === undefined ? !Object.hasOwn(value, 'product') : nonempty(value.product));
 export function validContentRef(value) {
     if (!object(value))
         return false;
@@ -27,11 +27,11 @@ function safeExternal(value, image = false) {
     }
 }
 export function validateContentManifest(value, maxResources = 10_000, maxResourceBytes = 8_000_000) {
-    if (!keys(value, ['schemaVersion', 'kind', 'digest', 'publicBase', 'publication', 'review', 'resources', 'assets', 'files', 'diagnostics']) || value.schemaVersion !== 1 || value.kind !== 'shoalrun-content-export' || !digestPattern.test(value.digest ?? ''))
+    if (!keys(value, ['schemaVersion', 'kind', 'digest', 'publicBase', 'publication', 'review', 'resources', 'assets', 'files', 'diagnostics']) || ![1, 2].includes(value.schemaVersion) || value.kind !== 'shoalrun-content-export' || !digestPattern.test(value.digest ?? ''))
         invalid('Unsupported content manifest.');
     if (typeof value.publicBase !== 'string' || !/^\/(?:[A-Za-z0-9_~.-]+\/)*$/.test(value.publicBase) || value.publicBase.split('/').some((part) => part === '.' || part === '..'))
         invalid('Invalid content mount.');
-    if (!validContentPublication(value.publication))
+    if (!validContentPublication(value.publication) || value.schemaVersion !== (value.publication.product === undefined ? 1 : 2))
         invalid('Invalid publication.');
     if (!keys(value.review, ['status', 'apis']) || value.review.status !== 'ok' || !Array.isArray(value.review.apis) || value.review.apis.some((api) => !keys(api, ['apiId', 'digest']) || !nonempty(api.apiId) || !digestPattern.test(api.digest ?? '')))
         invalid('Content must have approved API review metadata.');
@@ -57,6 +57,8 @@ export function validateContentManifest(value, maxResources = 10_000, maxResourc
 }
 /** Shared metadata validation; transport supplies its file/asset inventory policy. */
 export function validateContentResources(resources, expectedPublication, assets, checkRepresentation, publicBase = '/') {
+    if (!validContentPublication(expectedPublication))
+        invalid('Invalid expected publication.');
     const refs = new Set();
     const links = [];
     for (const resource of resources) {

package/dist/content-export-command.d.ts

@@ -1,4 +1,4 @@
-export declare const exportHelp = "Usage: shoalrun export [config] --out DIRECTORY [--target NAME]\n       [--format markdown|html|both] [--document ID]...\n       [--channel C --version V --language L] [--public-base /help/] [--review]\n       [--profile FILE] [--previous-manifest FILE] [--fail-on-removed]\n\nExport selected pages, sections, and named snippets as Markdown and passive HTML.\nConfigure typed resources in an export target; --document selects whole pages.\nNavigation, facets, and a prior website build are not required.\n--review writes an API-review candidate; status needs-review exits 2 until pinned.\n--previous-manifest compares public references with an earlier reviewed export.\n--fail-on-removed requires that baseline and refuses to replace output if references disappear.\n";
+export declare const exportHelp = "Usage: shoalrun export [config] --out DIRECTORY [--target NAME]\n       [--format markdown|html|both] [--document ID]...\n       [--channel C --version V --language L [--product P]] [--public-base /help/] [--review]\n       [--profile FILE] [--previous-manifest FILE] [--fail-on-removed]\n\nExport selected pages, sections, and named snippets as Markdown and passive HTML.\nConfigure typed resources in an export target; --document selects whole pages.\nNavigation, facets, and a prior website build are not required.\n--review writes an API-review candidate; status needs-review exits 2 until pinned.\n--previous-manifest compares public references with an earlier reviewed export.\n--fail-on-removed requires that baseline and refuses to replace output if references disappear.\n";
 export declare function runExportCommand(args: string[]): Promise<{
     status: string;
     output: string;

package/dist/content-export-command.js

@@ -1,7 +1,7 @@
 import { exportContent } from './content-export.js';
 export const exportHelp = `Usage: shoalrun export [config] --out DIRECTORY [--target NAME]
        [--format markdown|html|both] [--document ID]...
-       [--channel C --version V --language L] [--public-base /help/] [--review]
+       [--channel C --version V --language L [--product P]] [--public-base /help/] [--review]
        [--profile FILE] [--previous-manifest FILE] [--fail-on-removed]
 
 Export selected pages, sections, and named snippets as Markdown and passive HTML.
@@ -30,7 +30,7 @@ export async function runExportCommand(args) {
             continue;
         }
         if (arg.startsWith('--')) {
-            if (!['--out', '--target', '--format', '--document', '--channel', '--version', '--language', '--public-base', '--previous-manifest', '--profile'].includes(arg) || !args[index + 1] || args[index + 1].startsWith('--'))
+            if (!['--out', '--target', '--format', '--document', '--channel', '--version', '--language', '--product', '--public-base', '--previous-manifest', '--profile'].includes(arg) || !args[index + 1] || args[index + 1].startsWith('--'))
                 throw new Error(exportHelp);
             const value = args[++index];
             if (arg === '--document') {
@@ -56,10 +56,10 @@ export async function runExportCommand(args) {
     if (format)
         options.formats = format === 'both' ? ['markdown', 'html'] : [format];
     const coordinates = ['--channel', '--version', '--language'].map(key => values.get(key));
-    if (coordinates.some(Boolean)) {
+    if (coordinates.some(Boolean) || values.has('--product')) {
         if (!coordinates.every(Boolean))
             throw new Error('Select all three export publication coordinates: --channel, --version, and --language');
-        options.publication = { channel: coordinates[0], version: coordinates[1], language: coordinates[2] };
+        options.publication = { channel: coordinates[0], version: coordinates[1], language: coordinates[2], ...(values.has('--product') ? { product: values.get('--product') } : {}) };
     }
     options.profile = values.get('--profile');
     options.target = values.get('--target');

package/dist/content-export-comparison.js

@@ -1,14 +1,15 @@
+import { validContentPublication } from './content-delivery-validation.js';
 import { contentRefKey } from './content-delivery-contract.js';
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
 const nonempty = (value) => typeof value === 'string' && value.length > 0 && value.trim() === value;
-const keyFor = ({ publication, ref }) => JSON.stringify([publication.channel, publication.version, publication.language, contentRefKey(ref)]);
+const keyFor = ({ publication, ref }) => JSON.stringify([publication.channel, publication.version, publication.language, ...(publication.product === undefined ? [] : [publication.product]), contentRefKey(ref)]);
 /** Validate the public identity surface, without reading files or executing source. */
 function references(manifest, label, requireReviewed) {
     const fail = () => { throw new Error(`${label} must be a content export manifest with valid, unique public resource references`); };
-    if (!object(manifest) || manifest.schemaVersion !== 1 || manifest.kind !== 'shoalrun-content-export' || !Array.isArray(manifest.resources) || !manifest.resources.length)
+    if (!object(manifest) || manifest.schemaVersion !== 1 && manifest.schemaVersion !== 2 || manifest.kind !== 'shoalrun-content-export' || !Array.isArray(manifest.resources) || !manifest.resources.length)
         return fail();
     const publication = manifest.publication;
-    if (!object(publication) || Object.keys(publication).length !== 3 || !['channel', 'version', 'language'].every(key => nonempty(publication[key])))
+    if (!validContentPublication(publication) || !object(publication) || manifest.schemaVersion !== (publication.product === undefined ? 1 : 2))
         return fail();
     if (!object(manifest.review) || !['ok', 'required'].includes(String(manifest.review.status)))
         return fail();
@@ -18,13 +19,13 @@ function references(manifest, label, requireReviewed) {
     for (const resource of manifest.resources) {
         if (!object(resource) || !object(resource.ref) || !object(resource.publication))
             return fail();
-        if (Object.keys(resource.publication).length !== 3 || !['channel', 'version', 'language'].every(key => resource.publication && resource.publication[key] === publication[key]))
+        if (!validContentPublication(resource.publication) || !['channel', 'version', 'language', 'product'].every(key => resource.publication && resource.publication[key] === publication[key]))
             return fail();
         const ref = resource.ref;
         const keys = ref.kind === 'page' ? ['kind', 'documentId'] : ref.kind === 'section' ? ['kind', 'documentId', 'sectionId'] : ref.kind === 'snippet' ? ['kind', 'id'] : [];
         if (!keys.length || Object.keys(ref).length !== keys.length || !keys.every(key => nonempty(ref[key])))
             return fail();
-        const entry = { publication: { channel: publication.channel, version: publication.version, language: publication.language }, ref: { ...ref } };
+        const entry = { publication: { channel: publication.channel, version: publication.version, language: publication.language, ...(publication.product !== undefined ? { product: publication.product } : {}) }, ref: { ...ref } };
         const key = keyFor(entry);
         if (result.has(key))
             return fail();

package/dist/content-export-config.js

@@ -66,8 +66,10 @@ export function validateExportTarget(value, readerFilters) {
     };
     let publication;
     if (value.publication !== undefined) {
-        if (!isConfigMapping(value.publication) || Object.keys(value.publication).some(key => !['channel', 'version', 'language'].includes(key)) || ['channel', 'version', 'language'].some(key => typeof value.publication === 'object' && (typeof value.publication[key] !== 'string' || !value.publication[key].trim())))
+        if (!isConfigMapping(value.publication) || Object.keys(value.publication).some(key => !['channel', 'version', 'language', 'product'].includes(key)) || ['channel', 'version', 'language'].some(key => typeof value.publication === 'object' && (typeof value.publication[key] !== 'string' || !value.publication[key].trim())))
             throw new Error('Export publication needs channel, version, and language');
+        if (value.publication.product !== undefined && !nonempty(value.publication.product))
+            throw new Error('Export publication product must be nonempty text');
         publication = value.publication;
     }
     if (value.apiReview !== undefined && (!isConfigMapping(value.apiReview) || Object.values(value.apiReview).some(digest => typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest))))

package/dist/content-export.js

@@ -1,9 +1,10 @@
+import { documentKey, samePublication } from './publication-identity.js';
 import { pruneFeatureTree, profileSelection } from './deployment-profile.js';
 import { readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadConfig, explainSegments } from './config.js';
-import { configField, isConfigMapping, requirePublicationsSection, requireSiteSection, resolvedCompilerConfig } from './compiler-config.js';
+import { configField, isConfigMapping, requirePublicationsSection, resolvePublication, requireSiteSection, resolvedCompilerConfig } from './compiler-config.js';
 import { defaultLanguage } from './frontmatter.js';
 import { normalizeBasePath, sitePath } from './site-path.js';
 import { prepareContentWorkspace } from './content-workspace.js';
@@ -32,13 +33,13 @@ import { isolateExportTree, markExportSource, exportHeadingInventory, preserveEx
 import { selectSection } from './section-identity.js';
 import { compareContentManifests } from './content-export-comparison.js';
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-const keyFor = (doc) => `${doc.frontmatter.id}|${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`;
-const resourceIdentity = (item) => JSON.stringify([item.ref.kind, item.ref.kind === 'snippet' ? item.ref.id : item.ref.documentId, item.ref.kind === 'section' ? item.ref.sectionId : null, item.doc.variant.channel, item.doc.variant.version, item.doc.variant.language]);
+const keyFor = (doc) => documentKey(doc.frontmatter.id, doc.variant);
+const resourceIdentity = (item) => JSON.stringify([item.ref.kind, item.ref.kind === 'snippet' ? item.ref.id : item.ref.documentId, item.ref.kind === 'section' ? item.ref.sectionId : null, item.doc.variant.channel, item.doc.variant.version, item.doc.variant.language, ...(item.doc.variant.product === undefined ? [] : [item.doc.variant.product])]);
 // Pages and their sections share a source; named snippet instances do not.
-const sourceKeyFor = (doc, kind = 'document') => JSON.stringify([kind, doc.frontmatter.id, doc.variant.channel, doc.variant.version, doc.variant.language]);
+const sourceKeyFor = (doc, kind = 'document') => JSON.stringify([kind, doc.frontmatter.id, doc.variant.channel, doc.variant.version, doc.variant.language, ...(doc.variant.product === undefined ? [] : [doc.variant.product])]);
 const selectedSourceKey = (item) => sourceKeyFor(item.doc, item.ref.kind === 'snippet' ? 'snippet' : 'document');
 const resourceKey = (item) => `resource-${exportDigest(resourceIdentity(item)).slice(0, 24)}`;
-const sameVariant = (a, b) => ['channel', 'version', 'language'].every(key => a[key] === b[key]);
+const sameVariant = samePublication;
 const visitTree = (node, visit) => {
     if (!node || typeof node !== 'object')
         return;
@@ -77,9 +78,9 @@ export async function exportContent(configFile, destination, options = {}) {
     const target = validateExportTarget({ ...raw, ...(options.formats ? { formats: options.formats } : {}), ...(options.documents ? { documents: options.documents } : {}), ...(options.publication ? { publication: options.publication } : {}), ...(options.publicBase ? { publicBase: options.publicBase } : {}) }, config.readerFilters);
     const language = defaultLanguage(config);
     const enabled = config.publications.enabled;
-    if (!Array.isArray(enabled) || !enabled.length || enabled.some(value => !isConfigMapping(value) || typeof value.channel !== 'string' || typeof value.version !== 'string' || value.language !== undefined && typeof value.language !== 'string'))
+    if (!Array.isArray(enabled) || !enabled.length || enabled.some(value => !isConfigMapping(value)))
         throw new Error('publications.enabled must declare valid publication combinations');
-    const variants = enabled.map(value => ({ channel: value.channel, version: value.version, language: value.language ?? language }));
+    const variants = enabled.map(value => resolvePublication(publications, value, language));
     const unique = [...new Map(variants.map(variant => [JSON.stringify(variant), variant])).values()];
     const publication = target.publication ?? (unique.length === 1 ? unique[0] : undefined);
     if (!publication)
@@ -431,7 +432,7 @@ export async function exportContent(configFile, destination, options = {}) {
         notices += `\n${path.basename(file)}:\n${await readFile(resolvedNotice, 'utf8')}\n`;
     }
     artifacts.set('NOTICES.txt', notices);
-    const manifest = { schemaVersion: 1, kind: 'shoalrun-content-export', publicBase: target.publicBase, publication,
+    const manifest = { schemaVersion: publication.product === undefined ? 1 : 2, kind: 'shoalrun-content-export', publicBase: target.publicBase, publication,
         review: { status: unreviewed.length ? 'required' : 'ok', apis: reviews.map(row => ({ apiId: row.apiId, digest: row.digest })) },
         resources: records, assets: [...assets.records.values()].sort((a, b) => compare(a.path, b.path)),
         files: [...artifacts].map(([filename, content]) => ({ path: filename, bytes: Buffer.byteLength(content), digest: exportDigest(content) })).sort((a, b) => compare(a.path, b.path)), diagnostics };

package/dist/content-rest-client.js

@@ -1,3 +1,4 @@
+import { samePublication } from './publication-identity.js';
 import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
 import { contentResourceKey } from './content-rest-contract.js';
 import { validContentPublication, validContentRef, validateContentResources, safeContentPath } from './content-delivery-validation.js';
@@ -5,7 +6,6 @@ import { freeze, sha256, readBounded } from './content-delivery-transport.js';
 const digestPattern = /^[a-f0-9]{64}$/;
 const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
 const exactKeys = (value, keys) => record(value) && Object.keys(value).length === keys.length && Object.keys(value).every(key => keys.includes(key));
-const samePublication = (left, right) => left.channel === right.channel && left.version === right.version && left.language === right.language;
 const invalid = (message) => { throw new ContentDeliveryError('invalid_manifest', message); };
 /** Preloads a REST inventory and pins all subsequent reads to that revision. */
 export async function openRestContentSource(options) {
@@ -39,6 +39,8 @@ export async function openRestContentSource(options) {
         url.pathname = baseUrl.pathname.replace(/\/$/, '') + '/resources' + suffix;
         for (const key of ['channel', 'version', 'language'])
             url.searchParams.set(key, publication[key]);
+        if (publication.product !== undefined)
+            url.searchParams.set('product', publication.product);
         if (revision !== undefined)
             url.searchParams.set('revision', revision);
         return url;
@@ -103,7 +105,7 @@ export async function openRestContentSource(options) {
             throw error;
         return invalid('REST inventory is not valid UTF-8 JSON.');
     }
-    if (!exactKeys(envelope, ['schemaVersion', 'revision', 'publication', 'resources']) || envelope.schemaVersion !== 1 || !digestPattern.test(envelope.revision ?? '') || !validContentPublication(envelope.publication) || !samePublication(envelope.publication, publication))
+    if (!exactKeys(envelope, ['schemaVersion', 'revision', 'publication', 'resources']) || envelope.schemaVersion !== (publication.product === undefined ? 1 : 2) || !digestPattern.test(envelope.revision ?? '') || !validContentPublication(envelope.publication) || !samePublication(envelope.publication, publication))
         invalid('Invalid REST inventory identity.');
     if (requestedRevision !== undefined && requestedRevision !== envelope.revision)
         throw new ContentDeliveryError('stale_revision', 'REST inventory differs from the requested revision.');

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

@@ -6,13 +6,13 @@ export type ContentRestEntry = {
     resource: ContentResource;
 };
 export type ContentRestList = {
-    schemaVersion: 1;
+    schemaVersion: 1 | 2;
     revision: string;
     publication: ContentPublication;
     resources: ContentRestEntry[];
 };
 export type ContentRestResource = {
-    schemaVersion: 1;
+    schemaVersion: 1 | 2;
     revision: string;
     publication: ContentPublication;
     key: string;