@shoalrun/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/dist/content-delivery-validation.js

@@ -0,0 +1,122 @@
+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));
+const nonempty = (value) => typeof value === 'string' && value.length > 0 && value.length <= 2048;
+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 function validContentRef(value) {
+    if (!object(value))
+        return false;
+    if (value.kind === 'page')
+        return Object.keys(value).length === 2 && nonempty(value.documentId);
+    if (value.kind === 'section')
+        return Object.keys(value).length === 3 && nonempty(value.documentId) && typeof value.sectionId === 'string' && /^[a-z0-9][a-z0-9-]{0,511}$/.test(value.sectionId);
+    return value.kind === 'snippet' && Object.keys(value).length === 2 && nonempty(value.id);
+}
+function safeExternal(value, image = false) {
+    try {
+        const url = new URL(value);
+        return typeof value === 'string' && !url.username && !url.password && (image ? ['http:', 'https:'] : ['http:', 'https:', 'mailto:', 'tel:']).includes(url.protocol);
+    }
+    catch {
+        return 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 ?? ''))
+        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))
+        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.');
+    if (!Array.isArray(value.resources) || !value.resources.length || value.resources.length > maxResources || !Array.isArray(value.files) || !Array.isArray(value.assets) || !Array.isArray(value.diagnostics))
+        invalid('Invalid manifest inventory.');
+    const files = new Map();
+    const checkFile = (file) => object(file) && safeContentPath(file.path) && Number.isSafeInteger(file.bytes) && file.bytes >= 0 && file.bytes <= maxResourceBytes && digestPattern.test(file.digest ?? '');
+    for (const file of value.files) {
+        if (!keys(file, ['path', 'bytes', 'digest']) || !checkFile(file) || files.has(file.path))
+            invalid('Invalid or duplicate file.');
+        files.set(file.path, file);
+    }
+    const listed = (file) => checkFile(file) && files.has(file.path) && files.get(file.path).bytes === file.bytes && files.get(file.path).digest === file.digest;
+    const assets = new Set();
+    for (const asset of value.assets) {
+        if (!keys(asset, ['path', 'bytes', 'digest', 'mediaType']) || !listed(asset) || !asset.path.startsWith('assets/') || !nonempty(asset.mediaType) || assets.has(asset.path))
+            invalid('Invalid or duplicate asset.');
+        assets.add(asset.path);
+    }
+    validateContentResources(value.resources, value.publication, assets, listed, value.publicBase);
+    if (value.diagnostics.some((item) => !keys(item, ['code', 'documentId', 'message']) || typeof item.code !== 'string' || item.documentId !== undefined && typeof item.documentId !== 'string' || typeof item.message !== 'string'))
+        invalid('Invalid diagnostics.');
+}
+/** Shared metadata validation; transport supplies its file/asset inventory policy. */
+export function validateContentResources(resources, expectedPublication, assets, checkRepresentation, publicBase = '/') {
+    const refs = new Set();
+    const links = [];
+    for (const resource of resources) {
+        if (!keys(resource, ['ref', 'publication', 'title', 'summary', 'type', 'canonicalUrl', 'source', 'representations', 'assets', 'externalDependencies']) || !validContentRef(resource.ref) || !validContentPublication(resource.publication) || !samePublication(resource.publication, expectedPublication) || typeof resource.title !== 'string' || typeof resource.summary !== 'string' || typeof resource.type !== 'string')
+            invalid('Invalid resource metadata.');
+        const key = contentRefKey(resource.ref);
+        if (refs.has(key))
+            invalid('Duplicate content reference.');
+        refs.add(key);
+        if (resource.canonicalUrl !== undefined && !safeExternal(resource.canonicalUrl, true))
+            invalid('Invalid canonical URL.');
+        if (resource.source !== undefined && (!object(resource.source) || !Object.keys(resource.source).length || Object.keys(resource.source).some(key => !['documentId', 'snippetId', 'valuesDigest'].includes(key)) || Object.values(resource.source).some(value => !nonempty(value))))
+            invalid('Invalid resource source.');
+        if (resource.source?.valuesDigest !== undefined && !digestPattern.test(resource.source.valuesDigest))
+            invalid('Invalid snippet values digest.');
+        if (!Array.isArray(resource.assets) || new Set(resource.assets).size !== resource.assets.length || resource.assets.some((asset) => !assets.has(asset)))
+            invalid('Unknown resource asset.');
+        if (!Array.isArray(resource.externalDependencies) || resource.externalDependencies.some((dependency) => !keys(dependency, ['url', 'kind']) || dependency.kind !== 'image' || !safeExternal(dependency.url, true)))
+            invalid('Invalid external dependency.');
+        if (!object(resource.representations) || !Object.keys(resource.representations).length || Object.keys(resource.representations).some(format => !['html', 'markdown'].includes(format)))
+            invalid('Invalid representations.');
+        for (const [format, rep] of Object.entries(resource.representations)) {
+            if (!keys(rep, ['path', 'bytes', 'digest', 'mediaType', 'anchors', 'links']) || !checkRepresentation(rep) || !rep.path.startsWith('content/') || rep.mediaType !== (format === 'html' ? 'text/html' : 'text/markdown') || !Array.isArray(rep.anchors) || !Array.isArray(rep.links))
+                invalid('Invalid representation file.');
+            const ids = new Set();
+            const exportedIds = new Set();
+            const linkKeys = new Set();
+            for (const anchor of rep.anchors) {
+                if (!keys(anchor, ['id', 'exportedId', 'title']) || !nonempty(anchor.id) || !nonempty(anchor.exportedId) || ids.has(anchor.id) || exportedIds.has(anchor.exportedId) || anchor.title !== undefined && typeof anchor.title !== 'string')
+                    invalid('Invalid representation anchor.');
+                ids.add(anchor.id);
+                exportedIds.add(anchor.exportedId);
+            }
+            for (const link of rep.links) {
+                if (!keys(link, ['key', 'kind', 'href', 'ref', 'fragment', 'query', 'asset']) || !nonempty(link.key) || linkKeys.has(link.key) || typeof link.href !== 'string' || !['resource', 'canonical', 'external', 'asset'].includes(link.kind))
+                    invalid('Invalid representation link.');
+                linkKeys.add(link.key);
+                if (link.kind === 'resource' && !validContentRef(link.ref) || link.kind === 'asset' && !assets.has(link.asset) || ['canonical', 'external'].includes(link.kind) && !safeExternal(link.href))
+                    invalid('Invalid link destination.');
+                if (link.fragment !== undefined && typeof link.fragment !== 'string' || link.query !== undefined && typeof link.query !== 'string')
+                    invalid('Invalid link suffix.');
+                if (['resource', 'asset'].includes(link.kind)) {
+                    const linkPath = link.href.split(/[?#]/, 1)[0];
+                    if (!link.href.startsWith('#') && !link.href.startsWith(publicBase) || /\\|%2e|%2f|%5c/i.test(linkPath))
+                        invalid('Link leaves content mount.');
+                    let url;
+                    try {
+                        url = new URL(link.href, 'https://content.invalid' + publicBase);
+                    }
+                    catch {
+                        return invalid('Invalid internal link URL.');
+                    }
+                    if (url.origin !== 'https://content.invalid' || !url.pathname.startsWith(publicBase))
+                        invalid('Link leaves content mount.');
+                }
+                links.push(link);
+            }
+        }
+    }
+    for (const link of links)
+        if (link.kind === 'resource' && !refs.has(contentRefKey(link.ref)))
+            invalid('Link references absent content.');
+}

package/dist/content-delivery.d.ts

@@ -0,0 +1,21 @@
+import type { ContentSnapshot } from './content-delivery-contract.js';
+export * from './content-delivery-contract.js';
+export * from './content-rest-contract.js';
+export { validateContentManifest } from './content-delivery-validation.js';
+export { mountContent } from './content-mount.js';
+export type { ContentMount } from './content-mount.js';
+export type ContentDeliveryLimits = {
+    manifestBytes?: number;
+    resourceBytes?: number;
+    resources?: number;
+};
+export type ManifestContentSourceOptions = {
+    manifestUrl: string | URL;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+    limits?: ContentDeliveryLimits;
+};
+/** Opens one immutable manifest revision. The caller owns trust in the build/host. */
+export declare function openManifestContentSource(options: ManifestContentSourceOptions): Promise<ContentSnapshot>;
+export { openRestContentSource } from './content-rest-client.js';
+export type { RestContentSourceOptions } from './content-rest-client.js';

package/dist/content-delivery.js

@@ -0,0 +1,119 @@
+import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
+export * from './content-delivery-contract.js';
+export * from './content-rest-contract.js';
+import { validateContentManifest, validContentRef } from './content-delivery-validation.js';
+export { validateContentManifest } from './content-delivery-validation.js';
+import { freeze, sha256, readBounded } from './content-delivery-transport.js';
+const invalid = (message) => { throw new ContentDeliveryError('invalid_manifest', message); };
+export { mountContent } from './content-mount.js';
+/** Opens one immutable manifest revision. The caller owns trust in the build/host. */
+export async function openManifestContentSource(options) {
+    const fetcher = options.fetch ?? globalThis.fetch;
+    let manifestUrl;
+    try {
+        manifestUrl = new URL(options.manifestUrl, typeof location === 'undefined' ? undefined : location.href);
+    }
+    catch {
+        throw new ContentDeliveryError('invalid_manifest', 'Manifest URL must be a valid HTTP(S) URL.');
+    }
+    if (!['http:', 'https:'].includes(manifestUrl.protocol) || manifestUrl.username || manifestUrl.password || manifestUrl.hash || manifestUrl.search)
+        invalid('Manifest URL must be an HTTP(S) URL without credentials, query, or fragment.');
+    if (typeof location !== 'undefined' && manifestUrl.origin !== location.origin)
+        invalid('Browser content must be served from the application origin.');
+    const manifestBytes = options.limits?.manifestBytes ?? 5_000_000;
+    const resourceBytes = options.limits?.resourceBytes ?? 8_000_000;
+    const resources = options.limits?.resources ?? 10_000;
+    for (const limit of [manifestBytes, resourceBytes, resources])
+        if (!Number.isSafeInteger(limit) || limit <= 0)
+            invalid('Limits must be positive safe integers.');
+    const lifetime = new AbortController();
+    let disposed = false;
+    const openSignal = options.signal ? AbortSignal.any([options.signal, lifetime.signal]) : lifetime.signal;
+    async function request(url, mediaType, limit, signal, revision = false) {
+        signal.throwIfAborted();
+        let response;
+        try {
+            response = await fetcher(url.href, { signal, redirect: 'error', credentials: 'same-origin', cache: 'no-store', headers: { Accept: mediaType } });
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            throw new ContentDeliveryError('network_error', 'Cannot fetch content.');
+        }
+        const rejectResponse = async (code, message) => { await response.body?.cancel().catch(() => { }); throw new ContentDeliveryError(code, message); };
+        if (response.status === 404)
+            return rejectResponse(revision ? 'stale_revision' : 'not_found', 'Content is unavailable.');
+        if (!response.ok)
+            return rejectResponse('network_error', `Content request failed (${response.status}).`);
+        if (response.redirected || response.url && response.url !== url.href)
+            return rejectResponse('invalid_content', 'Redirected content is not accepted.');
+        if (response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase() !== mediaType)
+            return rejectResponse('invalid_content', 'Unexpected content type.');
+        try {
+            return await readBounded(response, limit, signal);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (error instanceof ContentDeliveryError)
+                throw error;
+            throw new ContentDeliveryError('network_error', 'Content response was interrupted.');
+        }
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(await request(manifestUrl, 'application/json', manifestBytes, openSignal)));
+    }
+    catch (error) {
+        if (error instanceof ContentDeliveryError || openSignal.aborted)
+            throw error;
+        invalid('Manifest is not valid UTF-8 JSON.');
+    }
+    validateContentManifest(manifest, resources, resourceBytes);
+    const { digest, ...body } = manifest;
+    if (await sha256(new TextEncoder().encode(JSON.stringify(body))) !== digest)
+        invalid('Manifest digest does not match its contents.');
+    openSignal.throwIfAborted();
+    const mount = new URL(manifest.publicBase, manifestUrl.origin);
+    if (!manifestUrl.pathname.startsWith(mount.pathname))
+        invalid('Manifest is outside its declared content mount.');
+    freeze(manifest);
+    const byRef = new Map(manifest.resources.map(resource => [contentRefKey(resource.ref), resource]));
+    const active = () => { if (disposed)
+        throw new ContentDeliveryError('disposed', 'Content snapshot has been disposed.'); };
+    return Object.freeze({
+        revision: manifest.digest, publication: manifest.publication,
+        list() { active(); return manifest.resources; },
+        async get(ref, getOptions) {
+            active();
+            if (!validContentRef(ref))
+                throw new ContentDeliveryError('not_found', 'Invalid content reference.');
+            const resource = byRef.get(contentRefKey(ref));
+            if (!resource)
+                throw new ContentDeliveryError('not_found', 'No matching content in this publication.');
+            const format = getOptions?.format;
+            if (!['html', 'markdown'].includes(format))
+                throw new ContentDeliveryError('unsupported_format', 'The requested representation is unavailable.');
+            const representation = resource.representations[format];
+            if (!representation)
+                throw new ContentDeliveryError('unsupported_format', 'The requested representation is unavailable.');
+            const signal = getOptions.signal ? AbortSignal.any([lifetime.signal, getOptions.signal]) : lifetime.signal;
+            const bytes = await request(new URL(representation.path, mount), representation.mediaType, resourceBytes, signal, true);
+            if (bytes.byteLength !== representation.bytes || await sha256(bytes) !== representation.digest)
+                throw new ContentDeliveryError('stale_revision', 'Representation differs from the opened revision.');
+            signal.throwIfAborted();
+            active();
+            let content;
+            try {
+                content = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch {
+                throw new ContentDeliveryError('invalid_content', 'Content is not valid UTF-8.');
+            }
+            return Object.freeze({ resource, representation, format, content, revision: manifest.digest });
+        },
+        dispose() { if (!disposed) {
+            disposed = true;
+            lifetime.abort(new ContentDeliveryError('disposed', 'Content snapshot has been disposed.'));
+        } },
+    });
+}
+export { openRestContentSource } from './content-rest-client.js';

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

@@ -0,0 +1,11 @@
+/** Expanded snippets may share nodes; give every authored occurrence its own identity. */
+export declare function isolateExportTree(value: any): any;
+/** Stable internal provenance survives cloning, slicing, and portable lowering. */
+export declare function markExportSource(tree: any): void;
+/** Map semantic heading provenance to the actual IDs assigned by the renderer. */
+export declare function exportHeadingInventory(tree: any, reservedIds?: Iterable<string>): {
+    headings: Map<string, string>;
+    ids: Set<string>;
+};
+/** HTML keeps source IDs; Markdown keeps clean headings and maps source to local IDs. */
+export declare function preserveExportHeadingIds(tree: any, source: ReturnType<typeof exportHeadingInventory>, format: 'html' | 'markdown'): Map<string, string>;

package/dist/content-export-anchors.js

@@ -0,0 +1,79 @@
+import { parseFragment } from 'parse5';
+import { renderHtmlWithHeadings } from './html-renderer.js';
+/** Expanded snippets may share nodes; give every authored occurrence its own identity. */
+export function isolateExportTree(value) {
+    if (Array.isArray(value))
+        return value.map(isolateExportTree);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, isolateExportTree(item)]));
+    return value;
+}
+/** Stable internal provenance survives cloning, slicing, and portable lowering. */
+export function markExportSource(tree) {
+    let index = 0;
+    const walk = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            node.forEach(walk);
+            return;
+        }
+        if (typeof node.type === 'string')
+            node.data = { ...node.data, exportSourceKey: `source-${index++}` };
+        for (const [key, value] of Object.entries(node))
+            if (!['data', 'position'].includes(key))
+                walk(value);
+    };
+    walk(tree);
+}
+/** Map semantic heading provenance to the actual IDs assigned by the renderer. */
+export function exportHeadingInventory(tree, reservedIds = []) {
+    const copy = structuredClone(tree);
+    const mark = (node) => {
+        if (node.data?.exportSourceKey)
+            node.data.hProperties = { ...node.data.hProperties, 'data-export-source-key': node.data.exportSourceKey };
+        for (const child of node.children ?? [])
+            mark(child);
+    };
+    mark(copy);
+    const parsed = parseFragment(renderHtmlWithHeadings(copy, undefined, reservedIds).html);
+    const headings = new Map();
+    const ids = new Set();
+    const visit = (node) => {
+        const id = node.attrs?.find((attr) => attr.name === 'id')?.value;
+        if (id) {
+            ids.add(id);
+            const key = node.attrs?.find((attr) => attr.name === 'data-export-source-key')?.value;
+            if (/^h[2-6]$/.test(node.tagName ?? '') && key)
+                headings.set(key, id);
+        }
+        for (const child of node.childNodes ?? [])
+            visit(child);
+    };
+    visit(parsed);
+    return { headings, ids };
+}
+/** HTML keeps source IDs; Markdown keeps clean headings and maps source to local IDs. */
+export function preserveExportHeadingIds(tree, source, format) {
+    const local = exportHeadingInventory(tree);
+    const aliases = new Map();
+    const walk = (node) => {
+        const key = node.data?.exportSourceKey;
+        if (key && (node.type === 'heading' || /^h[2-6]$/.test(node.data?.hName ?? '')) && local.headings.has(key)) {
+            const original = source.headings.get(key);
+            if (!original)
+                throw new Error('Cannot determine full-source identity for an exported heading');
+            aliases.set(original, format === 'html' ? original : local.headings.get(key));
+            if (format === 'html')
+                node.data.hProperties = { ...node.data.hProperties, id: original };
+        }
+        for (const child of node.children ?? [])
+            walk(child);
+    };
+    walk(tree);
+    // Non-heading anchors (explicit aliases, footnotes, component IDs) retain IDs.
+    for (const id of local.ids)
+        if (!Array.from(local.headings.values()).includes(id) && source.ids.has(id))
+            aliases.set(id, id);
+    return aliases;
+}

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

@@ -1,11 +1,13 @@
-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\nExport whole pages as resolved Markdown and passive HTML, with a manifest and assets.\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";
+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       [--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;
     publication: import("./content-source.js").Variant;
     formats: import("./content-export-config.js").ExportFormat[];
+    resources: number;
     documents: number;
     documentIds: string[];
+    comparison: import("./content-export-comparison.js").ContentExportComparison;
     assets: number;
     digest: string;
     apiReview: {
@@ -14,7 +16,7 @@ export declare function runExportCommand(args: string[]): Promise<{
     }[];
     diagnostics: {
         code: string;
-        documentId: string;
+        documentId?: string;
         message: string;
     }[];
 }>;

package/dist/content-export-command.js

@@ -2,10 +2,14 @@ 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]
+       [--previous-manifest FILE] [--fail-on-removed]
 
-Export whole pages as resolved Markdown and passive HTML, with a manifest and assets.
+Export selected pages, sections, and named snippets as Markdown and passive HTML.
+Configure typed resources in an export target; --document selects whole pages.
 Navigation, facets, and a prior website build are not required.
 --review writes an API-review candidate; status needs-review exits 2 until pinned.
+--previous-manifest compares public references with an earlier reviewed export.
+--fail-on-removed requires that baseline and refuses to replace output if references disappear.
 `;
 export async function runExportCommand(args) {
     const options = {};
@@ -19,8 +23,14 @@ export async function runExportCommand(args) {
             options.review = true;
             continue;
         }
+        if (arg === '--fail-on-removed') {
+            if (options.failOnRemoved)
+                throw new Error(exportHelp);
+            options.failOnRemoved = true;
+            continue;
+        }
         if (arg.startsWith('--')) {
-            if (!['--out', '--target', '--format', '--document', '--channel', '--version', '--language', '--public-base'].includes(arg) || !args[index + 1] || args[index + 1].startsWith('--'))
+            if (!['--out', '--target', '--format', '--document', '--channel', '--version', '--language', '--public-base', '--previous-manifest'].includes(arg) || !args[index + 1] || args[index + 1].startsWith('--'))
                 throw new Error(exportHelp);
             const value = args[++index];
             if (arg === '--document') {
@@ -53,5 +63,8 @@ export async function runExportCommand(args) {
     }
     options.target = values.get('--target');
     options.publicBase = values.get('--public-base');
+    options.previousManifest = values.get('--previous-manifest');
+    if (options.failOnRemoved && !options.previousManifest)
+        throw new Error('--fail-on-removed requires --previous-manifest');
     return exportContent(config ?? 'docs.config.yaml', output, options);
 }

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

@@ -0,0 +1,16 @@
+import { type ContentPublication, type ContentRef } from './content-delivery-contract.js';
+export type ContentReference = {
+    publication: ContentPublication;
+    ref: ContentRef;
+};
+export type ContentExportComparison = {
+    status: 'no-baseline' | 'compared';
+    added: ContentReference[];
+    removed: ContentReference[];
+    diagnostics: Array<{
+        code: 'no-reference-baseline' | 'removed-content-reference';
+        message: string;
+    }>;
+};
+/** Titles, ordering and content edits do not change a public reference. */
+export declare function compareContentManifests(previous: unknown | undefined, current: unknown): ContentExportComparison;

package/dist/content-export-comparison.js

@@ -0,0 +1,48 @@
+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)]);
+/** 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)
+        return fail();
+    const publication = manifest.publication;
+    if (!object(publication) || Object.keys(publication).length !== 3 || !['channel', 'version', 'language'].every(key => nonempty(publication[key])))
+        return fail();
+    if (!object(manifest.review) || !['ok', 'required'].includes(String(manifest.review.status)))
+        return fail();
+    if (requireReviewed && manifest.review.status !== 'ok')
+        throw new Error(`${label} must be a reviewed export, not a review candidate`);
+    const result = new Map();
+    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]))
+            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 key = keyFor(entry);
+        if (result.has(key))
+            return fail();
+        result.set(key, entry);
+    }
+    return result;
+}
+/** Titles, ordering and content edits do not change a public reference. */
+export function compareContentManifests(previous, current) {
+    const next = references(current, 'Current manifest', false);
+    const sorted = (values) => [...values].sort((a, b) => keyFor(a) < keyFor(b) ? -1 : keyFor(a) > keyFor(b) ? 1 : 0);
+    if (previous === undefined)
+        return {
+            status: 'no-baseline', added: sorted(next.values()), removed: [],
+            diagnostics: [{ code: 'no-reference-baseline', message: 'No previous manifest supplied; removed public references were not checked.' }],
+        };
+    const prior = references(previous, 'Previous manifest', true);
+    const removed = sorted([...prior].filter(([key]) => !next.has(key)).map(([, value]) => value));
+    const added = sorted([...next].filter(([key]) => !prior.has(key)).map(([, value]) => value));
+    return { status: 'compared', added, removed, diagnostics: removed.length ? [{ code: 'removed-content-reference', message: `${removed.length} previously exported public reference(s) are missing. Review removed references before publishing.` }] : [] };
+}

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

@@ -1,9 +1,25 @@
 import { type ReaderSelection } from './reader-filters.js';
 import type { Variant } from './content.js';
 export type ExportFormat = 'markdown' | 'html';
+export type ExportResourceSelector = {
+    kind: 'page';
+    documentId: string;
+} | {
+    kind: 'section';
+    documentId: string;
+    sectionId: string;
+} | {
+    kind: 'snippet';
+    id: string;
+    snippetId: string;
+    title: string;
+    summary: string;
+    values?: Record<string, string | number | boolean>;
+};
 export type ExportTarget = {
     formats: ExportFormat[];
     documents?: string[];
+    resources?: ExportResourceSelector[];
     publication?: Variant;
     contentFilter?: ReaderSelection;
     publicBase: string;
@@ -11,6 +27,7 @@ export type ExportTarget = {
     apiReview: Record<string, string>;
     notices: string[];
 };
+export declare function validateExportResources(value: unknown): ExportResourceSelector[];
 export declare function exportPublicBase(value: unknown): string;
 export declare function validateExportTarget(value: unknown, readerFilters?: unknown): ExportTarget;
 export declare function validateExports(value: unknown, readerFilters?: unknown): void;

package/dist/content-export-config.js

@@ -1,6 +1,48 @@
 import { isConfigMapping } from './compiler-config.js';
 import { validateContentFilter } from './content-filter.js';
 import { validateReaderFilters } from './reader-filters.js';
+import { validSectionId } from './section-identity.js';
+const nonempty = (value) => typeof value === 'string' && value.trim() === value && value.length > 0;
+const snippetId = (value) => nonempty(value) && /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(value)
+    && value.split('.').every(part => /^[A-Za-z_][A-Za-z0-9_-]*$/.test(part) && !['__proto__', 'prototype', 'constructor'].includes(part));
+export function validateExportResources(value) {
+    if (!Array.isArray(value) || !value.length)
+        throw new Error('Export resources must be a nonempty list');
+    const seen = new Set();
+    return value.map((item, index) => {
+        const fail = (message) => { throw new Error(`Export resources[${index}]: ${message}`); };
+        if (!isConfigMapping(item))
+            fail('resource must be a mapping');
+        const resource = item;
+        const keys = resource.kind === 'page' ? ['kind', 'documentId'] : resource.kind === 'section' ? ['kind', 'documentId', 'sectionId'] : resource.kind === 'snippet' ? ['kind', 'id', 'snippetId', 'title', 'summary', 'values'] : undefined;
+        if (!keys || Object.keys(resource).some(key => !keys.includes(key)))
+            fail('expected a page, section, or snippet selector with only its supported fields');
+        let identity;
+        if (resource.kind === 'snippet') {
+            if (!snippetId(resource.id) || !snippetId(resource.snippetId))
+                fail('snippet id and snippetId must be valid stable snippet identifiers');
+            if (!nonempty(resource.title) || !nonempty(resource.summary))
+                fail('snippet needs a nonempty title and summary');
+            if (resource.values !== undefined) {
+                if (!isConfigMapping(resource.values) || Object.entries(resource.values).some(([key, value]) => !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key) || ['__proto__', 'prototype', 'constructor'].includes(key)
+                    || !['string', 'number', 'boolean'].includes(typeof value) || typeof value === 'number' && !Number.isFinite(value)))
+                    fail('snippet values must map safe variable names to finite scalar literals');
+            }
+            identity = JSON.stringify(['snippet', resource.id]);
+        }
+        else {
+            if (!nonempty(resource.documentId))
+                fail('documentId must be a nonempty trimmed string');
+            if (resource.kind === 'section' && !validSectionId(resource.sectionId))
+                fail('sectionId must be a stable lowercase anchor identifier');
+            identity = JSON.stringify([resource.kind, resource.documentId, ...(resource.kind === 'section' ? [resource.sectionId] : [])]);
+        }
+        if (seen.has(identity))
+            fail('duplicate resource reference');
+        seen.add(identity);
+        return { ...resource, ...(resource.values !== undefined ? { values: { ...resource.values } } : {}) };
+    });
+}
 export function exportPublicBase(value) {
     if (typeof value !== 'string' || !/^\/(?:[A-Za-z0-9_~.-]+\/)*$/.test(value) || value.split('/').some(part => part === '.' || part === '..')) {
         throw new Error('Export publicBase must be a root-relative path with a trailing slash, such as /help/');
@@ -8,8 +50,10 @@ export function exportPublicBase(value) {
     return value;
 }
 export function validateExportTarget(value, readerFilters) {
-    if (!isConfigMapping(value) || Object.keys(value).some(key => !['formats', 'documents', 'publication', 'contentFilter', 'publicBase', 'assetRoots', 'apiReview', 'notices'].includes(key)))
-        throw new Error('Export target accepts formats, documents, publication, contentFilter, publicBase, and assetRoots');
+    if (!isConfigMapping(value) || Object.keys(value).some(key => !['formats', 'documents', 'resources', 'publication', 'contentFilter', 'publicBase', 'assetRoots', 'apiReview', 'notices'].includes(key)))
+        throw new Error('Export target accepts formats, documents or resources, publication, contentFilter, publicBase, assetRoots, apiReview, and notices');
+    if (value.documents !== undefined && value.resources !== undefined)
+        throw new Error('Export documents and resources are mutually exclusive');
     const formats = value.formats ?? ['markdown', 'html'];
     if (!Array.isArray(formats) || !formats.length || formats.some(format => !['markdown', 'html'].includes(format)) || new Set(formats).size !== formats.length)
         throw new Error('Export formats must be a nonempty unique list of markdown and/or html');
@@ -28,7 +72,7 @@ export function validateExportTarget(value, readerFilters) {
     }
     if (value.apiReview !== undefined && (!isConfigMapping(value.apiReview) || Object.values(value.apiReview).some(digest => typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest))))
         throw new Error('Export apiReview must map API IDs to lowercase SHA-256 digests');
-    return { formats: [...formats].sort(), ...(value.documents !== undefined ? { documents: strings(value.documents, 'documents') } : {}), ...(publication ? { publication } : {}),
+    return { formats: [...formats].sort(), ...(value.documents !== undefined ? { documents: strings(value.documents, 'documents') } : {}), ...(value.resources !== undefined ? { resources: validateExportResources(value.resources) } : {}), ...(publication ? { publication } : {}),
         ...(value.contentFilter !== undefined ? { contentFilter: validateContentFilter(value.contentFilter, validateReaderFilters(readerFilters)) } : {}),
         publicBase: exportPublicBase(value.publicBase ?? '/'), assetRoots: strings(value.assetRoots, 'assetRoots') ?? [], apiReview: (value.apiReview ?? {}), notices: strings(value.notices, 'notices') ?? [] };
 }

package/dist/content-export-render.js

@@ -5,7 +5,22 @@ import { heading, link, paragraph, root, text, renderMarkdown } from './content.
 import { walkthroughMarkdown } from './walkthrough.js';
 /** Lower interactions while representation-specific source blocks still exist. */
 export function portableTree(tree, format, routes, basePath) {
+    // Provenance is internal export metadata. Keep it when component lowering
+    // synthesizes headings so a slice can retain its full-source identities.
+    const inherit = (node, key) => {
+        if (!node || typeof node !== 'object')
+            return;
+        node.data = { ...node.data, exportSourceKey: node.data?.exportSourceKey ?? key };
+        for (const [index, child] of (node.children ?? []).entries())
+            inherit(child, `${node.data.exportSourceKey}/${index}`);
+    };
     const walk = (node) => {
+        const result = lower(node);
+        if (node.data?.exportSourceKey)
+            result.forEach((child, index) => inherit(child, `${node.data.exportSourceKey}:${index}`));
+        return result;
+    };
+    const lower = (node) => {
         if (node.type === 'docRepresentation')
             return node.representation === format ? node.children.flatMap(walk) : [];
         if (node.type === 'docComponent')
@@ -39,8 +54,12 @@ export function portableTree(tree, format, routes, basePath) {
     const lowered = publicTree(root((tree.children ?? []).flatMap(walk)), format, routes, 'light', basePath);
     const definitions = new Map();
     const collectDefinitions = (node) => {
-        if (node.type === 'definition')
+        if (node.type === 'definition') {
+            const previous = definitions.get(node.identifier);
+            if (previous && (previous.url !== node.url || previous.title !== node.title))
+                throw new Error(`Ambiguous export definition ${node.identifier}`);
             definitions.set(node.identifier, node);
+        }
         for (const child of node.children ?? [])
             collectDefinitions(child);
     };