@shoalrun/cli 0.1.0-alpha.12 → 0.1.0-alpha.14

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

package/dist/content-export.d.ts

@@ -7,6 +7,8 @@ export type ContentExportOptions = {
     publication?: Variant;
     publicBase?: string;
     review?: boolean;
+    previousManifest?: string;
+    failOnRemoved?: boolean;
 };
 /** Export selected source content; never invoke the website shell/compiler. */
 export declare function exportContent(configFile: string, destination: string, options?: ContentExportOptions): Promise<{
@@ -14,8 +16,10 @@ export declare function exportContent(configFile: string, destination: string, o
     output: string;
     publication: Variant;
     formats: ExportFormat[];
+    resources: number;
     documents: number;
     documentIds: string[];
+    comparison: import("./content-export-comparison.js").ContentExportComparison;
     assets: number;
     digest: string;
     apiReview: {
@@ -24,7 +28,7 @@ export declare function exportContent(configFile: string, destination: string, o
     }[];
     diagnostics: {
         code: string;
-        documentId: string;
+        documentId?: string;
         message: string;
     }[];
 }>;