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

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;

package/dist/content-rest-server.js

@@ -1,9 +1,10 @@
 import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
+import { validContentPublication } from './content-delivery-validation.js';
 import { contentResourceKey } from './content-rest-contract.js';
-const publicationKey = (publication) => JSON.stringify([publication.channel, publication.version, publication.language]);
+const publicationKey = (publication) => JSON.stringify([publication.channel, publication.version, publication.language, ...(publication.product === undefined ? [] : [publication.product])]);
 const digest = async (bytes) => [...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))].map(value => value.toString(16).padStart(2, '0')).join('');
 const encoder = new TextEncoder();
-const validPublication = (value) => value && Object.keys(value).sort().join(',') === 'channel,language,version' && Object.values(value).every(part => typeof part === 'string' && part.length > 0 && part.length <= 2048);
+const validPublication = validContentPublication;
 const canonical = (value) => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
 const same = (left, right) => JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
 /** Serve already-approved, pinned snapshots. The caller retains source ownership. */
@@ -38,16 +39,20 @@ export function createContentRestHandler(options) {
         const parts = url.pathname.slice(prefix.length).split('/').slice(1);
         if (parts.length !== 0 && parts.length !== 1 && !(parts.length === 3 && parts[1] === 'representations'))
             return error(404, 'not_found', 'Unknown content route.');
-        const allowed = new Set(['channel', 'version', 'language', 'revision']);
+        const allowed = new Set(['channel', 'version', 'language', 'product', 'revision']);
         if ([...url.searchParams.keys()].some(key => !allowed.has(key) || url.searchParams.getAll(key).length !== 1))
             return error(400, 'invalid_request', 'Unknown or repeated query parameter.');
         const publication = Object.fromEntries(['channel', 'version', 'language'].map(key => [key, url.searchParams.get(key)]));
-        if (Object.values(publication).some(value => !value || value.length > 2048))
+        if (url.searchParams.has('product'))
+            publication.product = url.searchParams.get('product');
+        if (!validPublication(publication))
             return error(400, 'invalid_request', 'channel, version, and language are required.');
         const revision = url.searchParams.get('revision');
         if (revision !== null && !/^[a-f0-9]{64}$/.test(revision) || parts.length > 0 && revision === null)
             return error(400, 'invalid_request', 'A valid revision is required for resource requests.');
         const selected = publications.get(publicationKey(publication));
+        if (!selected && publication.product === undefined && [...publications.values()].some(item => item.publication.product !== undefined && item.publication.channel === publication.channel && item.publication.version === publication.version && item.publication.language === publication.language))
+            return error(400, 'invalid_request', 'product is required for product-scoped publications.');
         if (!selected)
             return error(404, 'not_found', 'Publication not found.');
         if (revision !== null && revision !== selected.revision)
@@ -59,9 +64,9 @@ export function createContentRestHandler(options) {
             let body;
             let mediaType = 'application/json';
             if (!parts.length)
-                body = JSON.stringify({ schemaVersion: 1, revision: selected.revision, publication: selected.publication, resources: selected.resources });
+                body = JSON.stringify({ schemaVersion: selected.publication.product === undefined ? 1 : 2, revision: selected.revision, publication: selected.publication, resources: selected.resources });
             else if (parts.length === 1)
-                body = JSON.stringify({ schemaVersion: 1, revision: selected.revision, publication: selected.publication, ...resource });
+                body = JSON.stringify({ schemaVersion: selected.publication.product === undefined ? 1 : 2, revision: selected.revision, publication: selected.publication, ...resource });
             else {
                 const format = parts[2];
                 if (!['html', 'markdown'].includes(format) || !resource.resource.representations[format])

package/dist/content-source.d.ts

@@ -3,6 +3,7 @@ import type { SubjectDeprecation, ResolvedSubjectDeprecation } from './subject-d
 import type { ReaderSelection } from './reader-filters.js';
 import type { StandaloneSectionDeclaration } from './section-identity.js';
 export type Variant = {
+    product?: string;
     channel: string;
     version: string;
     language: string;
@@ -18,9 +19,14 @@ export type Frontmatter = {
     updated?: string;
     verified?: string;
     releaseVersion?: string;
+    availability?: {
+        since?: string;
+        through?: string;
+    };
     channel?: string;
     version?: string;
     publications?: Array<{
+        product?: string;
         channel: string;
         version: string;
     }>;
@@ -92,6 +98,13 @@ export type PublicationRoutingConfig = {
         versions: Record<string, {
             pathPrefix?: string;
         }>;
+        products?: Record<string, {
+            pathPrefix: string;
+            defaultVersion: string;
+            versions: Record<string, {
+                pathPrefix?: string;
+            }>;
+        }>;
     };
 };
 export declare function readDocument(file: string, frontmatterConfig?: unknown, enrich?: (source: Record<string, unknown>) => Promise<Record<string, unknown>>, sourceText?: string): Promise<{

package/dist/content-source.js

@@ -26,7 +26,10 @@ export async function readDocument(file, frontmatterConfig, enrich, sourceText)
 }
 export function routeFor(frontmatter, variant, config) {
     const channel = config.publications.channels[variant.channel];
-    const version = config.publications.versions[variant.version];
+    const product = variant.product === undefined ? undefined : config.publications.products?.[variant.product];
+    if (variant.product !== undefined && !product)
+        throw new Error(`Unknown publication product ${variant.product}`);
+    const version = (product?.versions ?? config.publications.versions)[variant.version];
     if (!channel || !version)
         throw new Error(`Unknown publication ${variant.channel}/${variant.version}`);
     const slug = frontmatter.slug;
@@ -35,7 +38,7 @@ export function routeFor(frontmatter, variant, config) {
     if (/^\/(?:\.well-known|api)(?:\/|$)/i.test(slug))
         throw new Error(`${frontmatter.id}: slug uses a reserved discovery path`);
     const languagePrefix = variant.language === defaultLanguage(config) ? '' : `/${variant.language}`;
-    const parts = [normalizeBasePath(config.site.basePath), languagePrefix, channel.pathPrefix ?? '', version.pathPrefix ?? '', slug].filter(Boolean);
+    const parts = [normalizeBasePath(config.site.basePath), languagePrefix, product?.pathPrefix ?? '', channel.pathPrefix ?? '', version.pathPrefix ?? '', slug].filter(Boolean);
     const normalized = '/' + parts.join('/').replace(/\/+/g, '/').replace(/^\//, '').replace(/\/$/, '');
     return normalized === '/' ? '/' : normalized;
 }

package/dist/content-workspace.d.ts

@@ -47,7 +47,9 @@ export declare function prepareContentWorkspace({ base, basePath, config, loaded
                 path: string;
                 [key: string]: unknown;
             };
+            product?: string;
             publications?: Array<{
+                product?: string;
                 channel: string;
                 version: string;
                 source: {
@@ -90,7 +92,9 @@ export declare function prepareContentWorkspace({ base, basePath, config, loaded
                     path: string;
                     [key: string]: unknown;
                 };
+                product?: string;
                 publications?: Array<{
+                    product?: string;
                     channel: string;
                     version: string;
                     source: {
@@ -134,7 +138,9 @@ export declare function prepareContentWorkspace({ base, basePath, config, loaded
                 path: string;
                 [key: string]: unknown;
             };
+            product?: string;
             publications?: Array<{
+                product?: string;
                 channel: string;
                 version: string;
                 source: {
@@ -173,7 +179,9 @@ export declare function prepareContentWorkspace({ base, basePath, config, loaded
             path: string;
             [key: string]: unknown;
         };
+        product?: string;
         publications?: Array<{
+            product?: string;
             channel: string;
             version: string;
             source: {
@@ -216,7 +224,9 @@ export declare function prepareContentWorkspace({ base, basePath, config, loaded
                 path: string;
                 [key: string]: unknown;
             };
+            product?: string;
             publications?: Array<{
+                product?: string;
                 channel: string;
                 version: string;
                 source: {
@@ -270,7 +280,9 @@ export declare function prepareContentWorkspace({ base, basePath, config, loaded
                 path: string;
                 [key: string]: unknown;
             };
+            product?: string;
             publications?: Array<{
+                product?: string;
                 channel: string;
                 version: string;
                 source: {

package/dist/content-workspace.js

@@ -1,3 +1,4 @@
+import { documentKey } from './publication-identity.js';
 import { matchesFeatures } from './deployment-profile.js';
 import path from 'node:path';
 import { readFile } from 'node:fs/promises';
@@ -6,7 +7,7 @@ import { planAuthoredDocuments } from './publication-plan.js';
 import { materializeApiReferences } from './api-publication-plan.js';
 import { explainSegments } from './config.js';
 import { validateSnippetConfig } from './snippets.js';
-const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+const keyFor = documentKey;
 /** Shared source resolution. No website navigation, styles, hosting or provider setup. */
 export async function prepareContentWorkspace({ base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }) {
     const { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir } = await planAuthoredDocuments({

package/dist/content.js

@@ -1,3 +1,4 @@
+import { publicationKey } from './publication-identity.js';
 import { fictionalDocument, resolveLlmsDiscovery } from './llms-discovery.js';
 import YAML from 'yaml';
 import { nativePublicFields, protectedMetadataRoots, publicFrontmatterPaths } from './frontmatter.js';
@@ -8,7 +9,7 @@ export { transformMdx } from './component-transform.js';
 export { renderHtml } from './html-renderer.js';
 export { buildHtmlPage, shareCardText, typeLabel } from './page-renderer.js';
 // API separators are visually hidden punctuation; join them to the preceding text so search reads "integer; default: 0".
-const variantKey = (variant) => `${variant.channel}|${variant.version}|${variant.language}`;
+const variantKey = publicationKey;
 const plainText = (html) => html.replace(/<(script|style)[^]*?<\/\1>/g, ' ').replace(/(?:<\/[a-z]+>)?<span class="api-separator">([^<]*)<\/span>/g, '$1').replace(/<[^>]+>/g, ' ')
     .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#x27;|&#39;/g, "'").replace(/&amp;/g, '&').replace(/\s+/g, ' ').trim();
 // One compact record per published page; headings allow results to deep-link into a section.
@@ -54,7 +55,7 @@ export function projectMetadata(doc, config) {
         throw new Error('Markdown metadata projection must be a mapping');
     const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
     const safePath = (value) => /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*$/.test(value);
-    const publicationFields = new Set(['channel', 'version', 'language', 'canonicalUrl']);
+    const publicationFields = new Set(['product', 'channel', 'version', 'language', 'canonicalUrl']);
     const approved = publicFrontmatterPaths(config.frontmatter);
     const validateSource = (source) => {
         if (!safePath(source))

package/dist/cookbook-chooser.js

@@ -1,3 +1,4 @@
+import { samePublication } from './publication-identity.js';
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
 const keys = (value, allowed) => Object.keys(value).every(key => allowed.includes(key));
 const validId = (value) => typeof value === 'string' && /^[a-z][a-z0-9-]*$/.test(value);
@@ -35,7 +36,7 @@ export function cookbookChooserComponent(node, file) {
     return { type: 'docCookbookChooser', id: attributes[0].value, sourceFile: file };
 }
 export function resolveCookbookTree(tree, current, documents, cookbooks, targets) {
-    const sameVariant = (a, b) => a.variant.channel === b.variant.channel && a.variant.version === b.variant.version && a.variant.language === b.variant.language;
+    const sameVariant = (a, b) => samePublication(a.variant, b.variant);
     const walk = (node) => {
         if (node.type !== 'docCookbookChooser')
             return node.children ? { ...node, children: node.children.map(walk) } : node;

package/dist/deployment-profile.d.ts

@@ -5,6 +5,7 @@ export type FeatureRequirements = {
 export type FeatureContext = {
     requireClassification?: boolean;
     classificationPublications?: Array<{
+        product?: string;
         channel: string;
         version: string;
         language: string;
@@ -49,4 +50,4 @@ export declare function profileSelection(resolution: ProfileResolution | undefin
     }[];
 } | undefined;
 /** A profile is data, never executable configuration or a directory to discover. */
-export declare function resolveDeploymentProfile(settings: unknown, config: Record<string, any>, declaringFile: string, profileFile?: string): Promise<ProfileResolution | undefined>;
+export declare function resolveDeploymentProfile(settings: unknown, config: Record<string, any>, declaringFile: string, profileFile?: string, onDependency?: (file: string) => void): Promise<ProfileResolution | undefined>;

package/dist/deployment-profile.js

@@ -1,3 +1,5 @@
+import { resolvePublication } from './compiler-config.js';
+import { publicationKey } from './publication-identity.js';
 import { readFile, lstat, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
@@ -95,7 +97,7 @@ export function profileSelection(resolution) {
     return { schemaVersion: 1, profileDigest: resolution.digest, features: [...resolution.context.grants].sort(), provenance: resolution.context.provenance, decisions: resolution.context.decisions };
 }
 /** A profile is data, never executable configuration or a directory to discover. */
-export async function resolveDeploymentProfile(settings, config, declaringFile, profileFile) {
+export async function resolveDeploymentProfile(settings, config, declaringFile, profileFile, onDependency) {
     if (settings === undefined) {
         if (profileFile)
             throw new Error('--profile requires profiles.manifest in the shared configuration');
@@ -108,6 +110,7 @@ export async function resolveDeploymentProfile(settings, config, declaringFile,
         if (settings[setting] !== undefined && typeof settings[setting] !== 'boolean')
             throw new Error(`profiles.${setting} must be boolean`);
     const manifestFile = path.resolve(path.dirname(declaringFile), settings.manifest);
+    onDependency?.(manifestFile);
     const manifestBytes = await readFile(manifestFile);
     const manifest = parseYaml(manifestBytes.toString('utf8'), manifestFile);
     keys(manifest, ['schemaVersion', 'features', 'skus'], 'SKU manifest');
@@ -142,13 +145,15 @@ export async function resolveDeploymentProfile(settings, config, declaringFile,
     const context = { features, digest, pruneNavigation: settings.pruneNavigation ?? false, decisions: [], provenance: Object.create(null) };
     context.requireClassification = settings.requireClassification ?? false;
     if (context.requireClassification)
-        context.classificationPublications = (config.publications?.enabled ?? []).map((entry) => ({ channel: entry.channel, version: entry.version, language: entry.language ?? defaultLanguage(config) }));
+        context.classificationPublications = (config.publications?.enabled ?? []).map((entry) => resolvePublication(config.publications, entry, defaultLanguage(config)));
     if (!profileFile) {
         if (settings.required !== false)
             throw new Error('This project requires an explicit --profile FILE');
         return { context, overlay: {}, dependencies: [manifestFile], assetFiles: [], digest };
     }
+    onDependency?.(path.resolve(profileFile));
     const file = await realpath(path.resolve(profileFile));
+    onDependency?.(file);
     const bytes = await readFile(file);
     const profile = parseYaml(bytes.toString('utf8'), file);
     profileData(profile);
@@ -185,7 +190,12 @@ export async function resolveDeploymentProfile(settings, config, declaringFile,
     const overlay = {};
     const assetFiles = [];
     if (profile.site !== undefined) {
-        keys(profile.site, ['title', 'origin', 'basePath', 'favicon', 'logo', 'header', 'footer', 'indexing'], 'Profile site');
+        keys(profile.site, ['title', 'origin', 'basePath', 'favicon', 'logo', 'header', 'footer', 'indexing', 'publicationSelector'], 'Profile site');
+        if (profile.site.publicationSelector !== undefined) {
+            keys(profile.site.publicationSelector, ['showLanguage'], 'Profile site.publicationSelector');
+            if (profile.site.publicationSelector.showLanguage !== undefined && typeof profile.site.publicationSelector.showLanguage !== 'boolean')
+                throw new Error('Profile site.publicationSelector.showLanguage must be boolean');
+        }
         if (profile.site.title !== undefined && (typeof profile.site.title !== 'string' || !profile.site.title.trim()))
             throw new Error('Profile site.title must be nonempty text');
         if (profile.site.indexing !== undefined && typeof profile.site.indexing !== 'boolean')
@@ -221,11 +231,31 @@ export async function resolveDeploymentProfile(settings, config, declaringFile,
                     throw new Error('Profile asset must stay within the profile directory');
                 // Explicit assets only. Symlinks must not introduce an undeclared capture root.
                 let current = target;
+                const ancestry = [];
                 while (current !== path.dirname(file)) {
-                    if ((await lstat(current)).isSymbolicLink())
-                        throw new Error('Profile assets must not use symlinks');
+                    ancestry.unshift(current);
                     current = path.dirname(current);
                 }
+                for (const entry of ancestry) {
+                    let info;
+                    try {
+                        info = await lstat(entry);
+                    }
+                    catch (error) {
+                        // Every existing ancestor has passed the containment/symlink check.
+                        // Watch only this declared target so creating it can repair a preview.
+                        if (error.code === 'ENOENT')
+                            onDependency?.(target);
+                        throw error;
+                    }
+                    if (info.isSymbolicLink())
+                        throw new Error('Profile assets must not use symlinks');
+                    if (entry !== target && !info.isDirectory()) {
+                        onDependency?.(target);
+                        throw new Error('Profile asset parents must be directories');
+                    }
+                }
+                onDependency?.(target);
                 if (!(await lstat(target)).isFile())
                     throw new Error(`Profile ${setting} must be a regular file`);
                 assetFiles.push(target);
@@ -257,13 +287,13 @@ export async function resolveDeploymentProfile(settings, config, declaringFile,
         keys(profile.publications, ['enabled'], 'Profile publications');
         const enabled = profile.publications.enabled;
         const language = defaultLanguage(config);
-        const coordinate = (value) => JSON.stringify([value.channel, value.version, value.language ?? language]);
+        const coordinate = (value) => publicationKey(resolvePublication(config.publications, value, language));
         if (!Array.isArray(enabled) || !enabled.length)
             throw new Error('Profile publications.enabled must be a nonempty subset of shared publications.enabled');
         const selected = new Set();
         for (const variant of enabled) {
-            keys(variant, ['channel', 'version', 'language'], 'Profile publication');
-            if (typeof variant.channel !== 'string' || typeof variant.version !== 'string' || (variant.language !== undefined && typeof variant.language !== 'string') || !config.publications?.enabled?.some((entry) => coordinate(entry) === coordinate(variant)))
+            keys(variant, ['product', 'channel', 'version', 'language'], 'Profile publication');
+            if (typeof variant.channel !== 'string' || (variant.version !== undefined && typeof variant.version !== 'string') || (variant.product !== undefined && typeof variant.product !== 'string') || (variant.language !== undefined && typeof variant.language !== 'string') || !config.publications?.enabled?.some((entry) => coordinate(entry) === coordinate(variant)))
                 throw new Error('Profile publication is not enabled by the shared configuration');
             const key = coordinate(variant);
             if (selected.has(key))

package/dist/dev.d.ts

@@ -1,2 +1,4 @@
 import type { Server } from 'node:http';
-export declare function startDev(configFile: string, outputDirectory: string, host?: string, port?: number): Promise<Server>;
+export declare function startDev(configFile: string, outputDirectory: string, host?: string, port?: number, options?: {
+    profile?: string;
+}): Promise<Server>;