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

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>;

package/dist/dev.js

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

package/dist/docs-author.js

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

package/dist/docs-command.js

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

package/dist/docs-eval.d.ts

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

package/dist/docs-eval.js

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

package/dist/docs-mcp.d.ts

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