@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/dist/authoring-review-command.js

@@ -0,0 +1,68 @@
+import { authoringReview, authoringReviewMarkdown } from './authoring-review.js';
+import { startAuthoringPreview } from './authoring-preview.js';
+import { SnapshotError } from './authoring-snapshot.js';
+import { validationFailure } from './authoring-validation.js';
+export async function runAuthoringReviewCommand(command, args) {
+    try {
+        const positional = [], seen = new Set();
+        let format = 'json', port;
+        for (let index = 0; index < args.length; index++) {
+            const flag = args[index];
+            if (!flag.startsWith('--')) {
+                positional.push(flag);
+                continue;
+            }
+            if (seen.has(flag))
+                throw new SnapshotError('invalid_input', `Duplicate ${flag}`);
+            seen.add(flag);
+            if (flag === '--json')
+                continue;
+            const value = args[++index];
+            if (command === 'review' && flag === '--format' && ['json', 'markdown'].includes(value))
+                format = value;
+            else if (command === 'preview' && flag === '--port' && /^\d+$/.test(value ?? ''))
+                port = Number(value);
+            else
+                throw new SnapshotError('invalid_input', `Unknown option or invalid value for ${flag}`);
+        }
+        if (positional.length !== 1)
+            throw new SnapshotError('invalid_input', `Usage: shoalrun docs ${command} REPORT${command === 'review' ? ' [--format json|markdown]' : ' [--port PORT]'}`);
+        if (command === 'review') {
+            const review = await authoringReview(positional[0]);
+            process.stdout.write(format === 'markdown' ? authoringReviewMarkdown(review) : JSON.stringify(review) + '\n');
+            if (review.status !== 'ok')
+                process.exitCode = 1;
+        }
+        else {
+            const preview = await startAuthoringPreview(positional[0], { port });
+            const { server, review, close, ...connection } = preview;
+            let validation;
+            try {
+                validation = await review();
+            }
+            catch (error) {
+                await close();
+                throw error;
+            }
+            const stop = async () => {
+                process.removeListener('SIGINT', stop);
+                process.removeListener('SIGTERM', stop);
+                try {
+                    await close();
+                    process.stdout.write(JSON.stringify({ schemaVersion: 1, kind: 'shoalrun-authoring-preview', status: 'stopped', snapshotId: preview.snapshotId, directoryRemoved: preview.directory, validationArtifactsRetained: true }) + '\n');
+                }
+                catch (error) {
+                    process.stdout.write(JSON.stringify(validationFailure(error)) + '\n');
+                    process.exitCode = 1;
+                }
+            };
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+            process.stdout.write(JSON.stringify({ ...connection, status: 'serving', validation }) + '\n');
+        }
+    }
+    catch (error) {
+        process.stdout.write(JSON.stringify(validationFailure(error)) + '\n');
+        process.exitCode = 1;
+    }
+}

package/dist/authoring-review.d.ts

@@ -0,0 +1,72 @@
+import { authoringValidationStatus, type ValidationReport } from './authoring-validation.js';
+export type AuthoringReview = {
+    schemaVersion: 1;
+    kind: 'shoalrun-authoring-review';
+    snapshotId: string;
+    status: ValidationReport['status'];
+    validationStatus: ValidationReport['status'];
+    freshness: Awaited<ReturnType<typeof authoringValidationStatus>> & {
+        reportChanged: boolean;
+    };
+    baseline: ValidationReport['baseline'];
+    changed: ValidationReport['changed'];
+    dependencies: Array<{
+        file: string;
+        digest: string | null;
+        source: 'captured-project' | 'validator';
+    }>;
+    checks: ValidationReport['checks'];
+    findings: ValidationReport['findings'];
+    coverage: ValidationReport['coverage'];
+    pageSelection: 'affected-authored-pages' | 'complete-rendered-project';
+    pages: Array<{
+        id: string;
+        file: string;
+        route: string;
+        markdown: string;
+        origin: 'authored' | 'generated';
+        htmlArtifact: string;
+        markdownArtifact: string;
+    }>;
+    artifacts: ValidationReport['artifacts'];
+    diff: {
+        available: false;
+        basis: ValidationReport['baseline'];
+        explanation: string;
+    };
+    evidence: {
+        status: 'harness-owned';
+        links: string[];
+    };
+    reviewers: {
+        status: 'not-run';
+        results: never[];
+    };
+    dispositions: never[];
+    nextAction: string;
+};
+export declare function reviewArtifact(site: string, route: string, html?: boolean): string;
+export declare function pinnedValidationStatus(reportFile: string, report: ValidationReport, reportDigest: string): Promise<{
+    reportChanged: boolean;
+    schemaVersion: number;
+    status: "stale" | "failed" | "ok" | "unavailable" | "incomplete";
+    snapshotId: string;
+    report: string;
+    current: boolean;
+    changed: {
+        source: boolean;
+        baseline: boolean;
+        validator: boolean;
+        artifacts: boolean;
+    };
+    nextAction: string;
+}>;
+export declare function assembleAuthoringReview(report: ValidationReport, freshness: AuthoringReview['freshness']): AuthoringReview;
+export declare function loadPinnedReview(reportFile: string): Promise<{
+    report: ValidationReport;
+    digest: string;
+    review: AuthoringReview;
+}>;
+/** Read a review without writes, providers, application or publication. */
+export declare function authoringReview(reportFile: string): Promise<AuthoringReview>;
+export declare function authoringReviewMarkdown(review: AuthoringReview): string;

package/dist/authoring-review.js

@@ -0,0 +1,71 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { authoringValidationStatus, readValidationReport } from './authoring-validation.js';
+import { isWithin, sha256, SnapshotError } from './authoring-snapshot.js';
+export function reviewArtifact(site, route, html = false) {
+    if (typeof route !== 'string' || !route.startsWith('/') || route.startsWith('//') || /[\\\0\r\n?#]/.test(route) || route.split('/').some(part => part === '..' || part === '.'))
+        throw new SnapshotError('unsafe_path', 'Invalid review artifact route');
+    const file = path.resolve(site, `.${route}`, ...(html ? ['index.html'] : []));
+    if (!isWithin(path.resolve(site), file))
+        throw new SnapshotError('unsafe_path', 'Review artifact escapes the site');
+    return file;
+}
+// Pin the report bytes. Editing/replacing the report never switches an existing
+// preview to another snapshot or makes it appear current.
+export async function pinnedValidationStatus(reportFile, report, reportDigest) {
+    const check = async () => sha256(await readFile(reportFile).catch(() => Buffer.alloc(0))) === reportDigest;
+    if (await check()) {
+        const status = await authoringValidationStatus(reportFile);
+        if (await check())
+            return { ...status, reportChanged: false };
+    }
+    return { schemaVersion: 1, status: 'stale', snapshotId: report.snapshotId, report: path.resolve(reportFile), current: false, changed: { source: false, baseline: false, validator: false, artifacts: false }, reportChanged: true, nextAction: 'The validation report changed or was removed. Validate again and start a new preview from the new report.' };
+}
+export function assembleAuthoringReview(report, freshness) {
+    const affected = new Set(report.coverage.affected);
+    const authored = new Set(report.coverage.authored);
+    // Config/dependency/deletion scope is conservative in validation. Include all
+    // generated API operations too, rather than showing only authored MDX pages.
+    const broad = report.changed.some(change => !authored.has(change.file));
+    const pages = report.coverage.rendered.filter(page => broad || affected.has(page.file)).map(page => ({ ...page, origin: authored.has(page.file) ? 'authored' : 'generated', htmlArtifact: reviewArtifact(report.artifacts.site, page.route, true), markdownArtifact: reviewArtifact(report.artifacts.site, page.markdown) }));
+    const inputs = new Map(report.inputs.map(input => [input.file, input.digest]));
+    return {
+        schemaVersion: 1, kind: 'shoalrun-authoring-review', snapshotId: report.snapshotId,
+        status: freshness.status, validationStatus: report.status, freshness,
+        baseline: report.baseline, changed: report.changed,
+        dependencies: report.dependencies.map(file => ({ file, digest: inputs.get(file) ?? report.runtimeDependencies.find(input => input.file === file)?.digest ?? null, source: inputs.has(file) ? 'captured-project' : 'validator' })),
+        checks: report.checks, findings: report.findings, coverage: report.coverage, pageSelection: broad ? 'complete-rendered-project' : 'affected-authored-pages', pages, artifacts: report.artifacts,
+        diff: { available: false, basis: report.baseline, explanation: report.baseline.kind === 'task-baseline' ? 'The task baseline records file digests, not earlier file contents. Changes below belong to that baseline; use your harness to retain and review the corresponding diff.' : 'Explicit selectors declare scope, not a before-state. No Git HEAD or whole-dirty-tree diff is attributed to this task.' },
+        evidence: { status: 'harness-owned', links: [] }, reviewers: { status: 'not-run', results: [] }, dispositions: [],
+        nextAction: freshness.current ? report.status === 'ok' ? 'Review the affected HTML/Markdown, task diff and supporting evidence before accepting the edit.' : 'Resolve findings and skipped/unavailable checks, then validate again. A preview is not a passing result.' : freshness.nextAction,
+    };
+}
+export async function loadPinnedReview(reportFile) {
+    const raw = await readFile(reportFile);
+    const report = await readValidationReport(reportFile);
+    const digest = sha256(raw);
+    if (sha256(await readFile(reportFile)) !== digest)
+        throw new SnapshotError('stale_input', 'Report changed while reading; retry.');
+    return { report, digest, review: assembleAuthoringReview(report, await pinnedValidationStatus(reportFile, report, digest)) };
+}
+/** Read a review without writes, providers, application or publication. */
+export async function authoringReview(reportFile) {
+    return (await loadPinnedReview(reportFile)).review;
+}
+const cell = (value) => value.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/[\r\n]/g, ' ');
+export function authoringReviewMarkdown(review) {
+    const lines = ['# Authoring review', '', `Snapshot: ${review.snapshotId}`, '', `Status: **${review.status}**. Validation result: ${review.validationStatus}. Current: ${review.freshness.current}.`, '', review.nextAction,
+        '', '## Task scope', '', `Baseline: ${review.baseline.kind}${review.baseline.file ? ` (${review.baseline.file}; digest ${review.baseline.digest})` : ''}.`, '', review.diff.explanation,
+        '', '| File | Change | Before digest | Snapshot digest |', '| --- | --- | --- | --- |',
+        ...review.changed.map(item => `| ${cell(item.file)} | ${item.operation} | ${item.beforeDigest ?? 'unknown'} | ${item.digest ?? 'deleted'} |`),
+        '', '## Affected pages', '', `Page selection: ${review.pageSelection}.`, '', '| Source / ID | Origin | HTML route | Markdown route |', '| --- | --- | --- | --- |',
+        ...review.pages.map(page => `| ${cell(page.file)} / ${cell(page.id)} | ${page.origin} | ${cell(page.route)} | ${cell(page.markdown)} |`),
+        '', `Not rendered: ${review.coverage.notRendered.join(', ') || 'none'}.`,
+        '', '## Checks', '', ...review.checks.map(check => `- ${check.id}: ${check.status}${check.explanation ? ` — ${check.explanation}` : ''}`),
+        '', '## Findings', '', ...review.findings.flatMap(finding => [`- ${finding.severity}: ${finding.code}${finding.file ? ` at ${finding.file}${finding.location ? `:${finding.location.line}:${finding.location.column}` : ''}` : ''}`, `  ${finding.explanation}`, `  Next: ${finding.nextAction}${finding.reference ? ` Reference: ${finding.reference}.` : ''}`, ...(finding.relatedFiles?.length ? [`  Related sources: ${finding.relatedFiles.join(', ')}.`] : [])]),
+        ...(review.findings.length ? [] : ['No findings reported. Check coverage and skipped checks before accepting the result.']),
+        '', '## Dependencies', '', ...review.dependencies.map(input => `- ${input.file}: ${input.digest ?? 'digest unavailable'} (${input.source})`),
+        '', '## Artifacts and review limits', '', `Captured project: ${review.artifacts.project}`, `Built site: ${review.artifacts.site}`, `Validation report: ${review.artifacts.report}`, '', review.artifacts.lifecycle,
+        '', 'Evidence gathering remains with your harness. No semantic reviewer ran; no author dispositions are recorded. Compiler success does not establish factual accuracy or reader usefulness.', ''];
+    return lines.join('\n');
+}

package/dist/authoring-snapshot.d.ts

@@ -0,0 +1,66 @@
+export declare const snapshotSchemaVersion = 1;
+export declare class SnapshotError extends Error {
+    readonly code: 'invalid_input' | 'unsafe_path' | 'stale_input' | 'capture_limit' | 'unsupported_dependency';
+    constructor(code: 'invalid_input' | 'unsafe_path' | 'stale_input' | 'capture_limit' | 'unsupported_dependency', message: string);
+}
+export declare const sha256: (value: string | Buffer) => string;
+export declare const isWithin: (root: string, file: string) => boolean;
+export declare const excludedNames: Set<string>;
+export type SnapshotInput = {
+    file: string;
+    digest: string;
+    mode: number;
+};
+export type SnapshotCapture = {
+    root: string;
+    config: string;
+    inputs: SnapshotInput[];
+    buffers: Map<string, Buffer>;
+    externalDirectories: string[];
+    excluded: Array<{
+        file: string;
+        reason: string;
+    }>;
+    configDigest?: string;
+};
+export type AuthoringBaseline = {
+    schemaVersion: 1;
+    kind: 'shoalrun-authoring-baseline';
+    project: string;
+    config: string;
+    digest: string;
+    inputs: SnapshotInput[];
+    externalDirectories: string[];
+    excluded: SnapshotCapture['excluded'];
+};
+export declare function relativeInput(root: string, file: string): string;
+export declare function collectSnapshotInputs(root: string, externalFiles?: string[], externalDirectories?: string[]): Promise<{
+    inputs: SnapshotInput[];
+    buffers: Map<string, Buffer<ArrayBufferLike>>;
+    excluded: {
+        file: string;
+        reason: string;
+    }[];
+}>;
+/** Capture static, project-owned inputs without running compiler/plugins/checks. */
+export declare function captureSnapshotInputs(configFile: string): Promise<SnapshotCapture>;
+export declare function confirmSnapshotInputs(capture: Pick<SnapshotCapture, 'root' | 'inputs' | 'externalDirectories'>): Promise<boolean>;
+export declare function captureAuthoringBaseline(configFile: string): Promise<AuthoringBaseline>;
+export declare function parseAuthoringBaseline(value: unknown, root: string, config: string): AuthoringBaseline;
+export declare function validatorInputs(): Promise<{
+    digest: string;
+    records: SnapshotInput[];
+}>;
+/** Artifact destinations are exclusive and cannot collide with source inputs. */
+export declare function authoringArtifactPath(root: string, destination: string): Promise<string>;
+export declare function writeAuthoringBaseline(configFile: string, output: string): Promise<{
+    schemaVersion: number;
+    status: string;
+    baseline: string;
+    digest: string;
+    files: number;
+    excluded: {
+        file: string;
+        reason: string;
+    }[];
+}>;

package/dist/authoring-snapshot.js

@@ -0,0 +1,293 @@
+import { componentPluginFiles } from './component-manifest.js';
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, realpath, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { explainSegments, loadConfig } from './config.js';
+import { parse } from './semantic-markdown.js';
+import { readDocument } from './content-source.js';
+import { parseAuditSettings } from './audit.js';
+export const snapshotSchemaVersion = 1;
+export class SnapshotError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+export const isWithin = (root, file) => file === root || file.startsWith(root + path.sep);
+export const excludedNames = new Set(['.git', 'node_modules', 'dist', 'site-dist', '.vercel', '.shoalrun', '.private-archives', '.private-evals', '.aws', '.ssh', '.codex', '.npmrc']);
+const excluded = (name) => excludedNames.has(name) || name === '.env' || name.startsWith('.env.');
+const framework = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export function relativeInput(root, file) {
+    if (typeof file !== 'string' || !file || path.isAbsolute(file) || /[\\\0\r\n]/.test(file))
+        throw new SnapshotError('unsafe_path', 'Input paths must be project-relative');
+    const target = path.resolve(root, file);
+    if (!isWithin(path.dirname(root), target) || target === path.dirname(root) || target === root)
+        throw new SnapshotError('unsafe_path', `Input escapes the project parent: ${file}`);
+    return target;
+}
+async function noSymlinks(file, boundary) {
+    let current = file;
+    while (isWithin(boundary, current)) {
+        const info = await lstat(current).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (info?.isSymbolicLink())
+            throw new SnapshotError('unsafe_path', `Snapshot inputs must not use symlinks: ${file}`);
+        if (current === boundary)
+            break;
+        current = path.dirname(current);
+    }
+}
+export async function collectSnapshotInputs(root, externalFiles = [], externalDirectories = []) {
+    const buffers = new Map();
+    const inputs = [];
+    const exclusions = [];
+    let bytes = 0;
+    const add = async (file) => {
+        const name = path.relative(root, file);
+        if (name.split(path.sep).some(excluded) && !(externalFiles.includes(name) && name.split(path.sep).includes('node_modules') && !name.split(path.sep).some(part => !['node_modules', 'dist', 'site-dist'].includes(part) && excluded(part))))
+            throw new SnapshotError('unsupported_dependency', `Dependency is in an excluded location: ${name}`);
+        if (buffers.has(name))
+            return;
+        await noSymlinks(file, path.dirname(root));
+        const before = await stat(file);
+        if (!before.isFile())
+            throw new SnapshotError('unsafe_path', `Snapshot input is not a regular file: ${name}`);
+        bytes += before.size;
+        if (bytes > 256 * 1024 * 1024 || inputs.length >= 10000)
+            throw new SnapshotError('capture_limit', 'Snapshot exceeds 10000 files or 256 MiB; use a bounded documentation project.');
+        const content = await readFile(file);
+        const after = await stat(file);
+        if (before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.mode !== after.mode)
+            throw new SnapshotError('stale_input', `Input changed while reading: ${name}`);
+        buffers.set(name, content);
+        inputs.push({ file: name, digest: sha256(content), mode: before.mode & 0o777 });
+    };
+    const walk = async (directory) => {
+        await noSymlinks(directory, path.dirname(root));
+        for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const file = path.join(directory, entry.name);
+            if (excluded(entry.name)) {
+                exclusions.push({ file: path.relative(root, file), reason: 'Generated, dependency, harness or credential files are excluded from source capture.' });
+                continue;
+            }
+            if (entry.isDirectory())
+                await walk(file);
+            else
+                await add(file);
+        }
+    };
+    await walk(root);
+    for (const file of externalFiles)
+        await add(relativeInput(root, file));
+    for (const directory of externalDirectories)
+        await walk(relativeInput(root, directory));
+    inputs.sort((a, b) => a.file.localeCompare(b.file));
+    exclusions.sort((a, b) => a.file.localeCompare(b.file));
+    return { inputs, buffers, excluded: exclusions };
+}
+/** Capture static, project-owned inputs without running compiler/plugins/checks. */
+export async function captureSnapshotInputs(configFile) {
+    const config = await realpath(path.resolve(configFile));
+    const root = path.dirname(config);
+    const externalFiles = new Set(), externalDirectories = new Set();
+    let configDigest;
+    let loaded;
+    try {
+        loaded = await loadConfig(config);
+        configDigest = loaded.digest;
+    }
+    catch { /* Invalid configuration must still be captured and diagnosed in isolation. */ }
+    const addExternal = async (absolute) => {
+        if (isWithin(root, absolute))
+            return;
+        const name = path.relative(root, absolute);
+        relativeInput(root, name);
+        await noSymlinks(absolute, path.dirname(root));
+        const info = await lstat(absolute).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (info?.isDirectory())
+            externalDirectories.add(name);
+        else if (info?.isFile())
+            externalFiles.add(name);
+    };
+    for (const file of loaded?.dependencies ?? [])
+        await addExternal(file);
+    // Commands run from the configuration directory. Their declared local inputs
+    // use that same base; never infer dependencies by interpreting command text.
+    let checks;
+    try {
+        checks = parseAuditSettings(loaded?.value.audit);
+    }
+    catch { /* Validation diagnoses malformed audit settings. */ }
+    for (const check of checks?.tests ?? [])
+        for (const input of check.inputs ?? []) {
+            const absolute = relativeInput(root, input);
+            if (path.relative(root, absolute).split(path.sep).some(excluded))
+                throw new SnapshotError('unsupported_dependency', `Check input is in an excluded location: ${input}`);
+            await noSymlinks(absolute, path.dirname(root));
+            if (!await stat(absolute).then(() => true, () => false))
+                throw new SnapshotError('unsupported_dependency', `Declared check input is missing: ${input}`);
+            await addExternal(absolute);
+        }
+    if (loaded) {
+        const visit = async (value, segments) => {
+            if (value && typeof value === 'object') {
+                for (const key of Object.keys(value))
+                    await visit(value[key], [...segments, key]);
+            }
+            else if (typeof value === 'string' && (['file', 'path', 'module', 'manifest', 'customCss', 'customReaderModule', 'body', 'template', 'favicon'].includes(segments.at(-1)) || segments.at(-2) === 'files') && !/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(value)) {
+                if (path.isAbsolute(value))
+                    throw new SnapshotError('unsupported_dependency', `Absolute dependency at ${segments.join('.')} cannot be isolated; use a relative path.`);
+                if (segments[0] === 'components' && segments.at(-1) === 'module' && !value.startsWith('.'))
+                    return;
+                const owner = explainSegments(loaded, segments).source.file;
+                await addExternal(path.resolve(path.dirname(owner), value));
+            }
+        };
+        for (const [key, value] of Object.entries(loaded.value))
+            if (!['authoring', 'audit', 'site', 'publications', 'navigation', 'relationships'].includes(key))
+                await visit(value, [key]);
+        await visit(loaded.value.site, ['site']);
+    }
+    if (loaded)
+        for (const file of await componentPluginFiles(loaded)) {
+            relativeInput(root, path.relative(root, file));
+            externalFiles.add(path.relative(root, file));
+        }
+    const captured = await collectSnapshotInputs(root, [...externalFiles], [...externalDirectories]);
+    // Walkthrough source locations are relative to their authored file. Capture
+    // referenced sibling sources while retaining the established parent boundary.
+    for (const [file, content] of captured.buffers)
+        if (/\.mdx?$/.test(file)) {
+            if (isWithin(path.resolve(root, loaded?.value.site?.contentDir ?? 'content'), path.resolve(root, file))) {
+                let image;
+                try {
+                    image = (await readDocument(path.resolve(root, file), loaded?.value.frontmatter, undefined, content.toString('utf8'))).frontmatter.image;
+                }
+                catch { /* Compiler reports invalid metadata. */ }
+                if (typeof image === 'string') {
+                    if (path.isAbsolute(image))
+                        throw new SnapshotError('unsupported_dependency', `Absolute page image dependency in ${file}`);
+                    await addExternal(path.resolve(path.dirname(path.resolve(root, file)), image));
+                }
+            }
+            const body = content.toString('utf8').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+            let tree;
+            try {
+                tree = parse.parse(body);
+            }
+            catch {
+                continue;
+            }
+            const visit = async (node) => {
+                if (node.name === 'Step' || node.name === 'Walkthrough')
+                    for (const attribute of node.attributes ?? [])
+                        if (attribute.name === 'file' && typeof attribute.value === 'string') {
+                            if (path.isAbsolute(attribute.value))
+                                throw new SnapshotError('unsupported_dependency', `Absolute walkthrough dependency in ${file}`);
+                            await addExternal(path.resolve(path.dirname(path.resolve(root, file)), attribute.value));
+                        }
+                for (const child of node.children ?? [])
+                    await visit(child);
+            };
+            await visit(tree);
+        }
+    const complete = await collectSnapshotInputs(root, [...externalFiles], [...externalDirectories]);
+    for (const input of captured.inputs)
+        if (complete.inputs.find(item => item.file === input.file)?.digest !== input.digest)
+            throw new SnapshotError('stale_input', `Input changed during dependency discovery: ${input.file}`);
+    return { root, config: path.basename(config), ...complete, externalDirectories: [...externalDirectories].sort(), configDigest };
+}
+export async function confirmSnapshotInputs(capture) {
+    const external = capture.inputs.filter(input => (!isWithin(capture.root, path.resolve(capture.root, input.file)) || input.file.split(path.sep).some(excluded))).map(input => input.file);
+    try {
+        const now = await collectSnapshotInputs(capture.root, external, capture.externalDirectories);
+        return JSON.stringify(now.inputs) === JSON.stringify(capture.inputs);
+    }
+    catch {
+        return false;
+    }
+}
+export async function captureAuthoringBaseline(configFile) {
+    const capture = await captureSnapshotInputs(configFile);
+    if (!await confirmSnapshotInputs(capture))
+        throw new SnapshotError('stale_input', 'Working tree changed while capturing the task baseline; retry.');
+    return { schemaVersion: 1, kind: 'shoalrun-authoring-baseline', project: capture.root, config: capture.config, inputs: capture.inputs, externalDirectories: capture.externalDirectories, excluded: capture.excluded, digest: sha256(JSON.stringify(capture.inputs)) };
+}
+export function parseAuthoringBaseline(value, root, config) {
+    const baseline = value;
+    if (!baseline || baseline.schemaVersion !== 1 || baseline.kind !== 'shoalrun-authoring-baseline' || baseline.project !== root || baseline.config !== config || !Array.isArray(baseline.inputs) || !Array.isArray(baseline.externalDirectories) || !Array.isArray(baseline.excluded))
+        throw new SnapshotError('invalid_input', 'Baseline must be a version-1 task baseline for this project/configuration.');
+    const seen = new Set();
+    for (const directory of baseline.externalDirectories)
+        relativeInput(root, directory);
+    for (const input of baseline.inputs) {
+        if (!input || typeof input !== 'object')
+            throw new SnapshotError('invalid_input', 'Invalid baseline input');
+        relativeInput(root, input.file);
+        if (!/^[a-f0-9]{64}$/.test(input.digest) || !Number.isInteger(input.mode) || input.mode < 0 || input.mode > 0o777 || seen.has(input.file))
+            throw new SnapshotError('invalid_input', 'Invalid or duplicate baseline input');
+        seen.add(input.file);
+    }
+    if (baseline.digest !== sha256(JSON.stringify(baseline.inputs)))
+        throw new SnapshotError('invalid_input', 'Baseline integrity digest does not match its inputs');
+    return baseline;
+}
+export async function validatorInputs() {
+    const records = [];
+    const walk = async (directory) => {
+        for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const file = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                await walk(file);
+            else if (!entry.name.endsWith('.test.js'))
+                records.push({ file, digest: sha256(await readFile(file)), mode: (await stat(file)).mode & 0o777 });
+        }
+    };
+    for (const directory of ['dist', 'assets', 'styles', 'templates'])
+        await walk(path.join(framework, directory));
+    for (const file of ['package.json', 'package-lock.json']) {
+        const absolute = path.join(framework, file);
+        try {
+            records.push({ file: absolute, digest: sha256(await readFile(absolute)), mode: 0 });
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    const renderer = process.env.PUPPETEER_EXECUTABLE_PATH;
+    const rendererStat = renderer ? await stat(renderer).then(info => ({ size: info.size, mtime: info.mtimeMs }), () => null) : undefined;
+    return { digest: sha256(JSON.stringify([process.version, { renderer, rendererStat, cache: process.env.PUPPETEER_CACHE_DIR }, records])), records };
+}
+/** Artifact destinations are exclusive and cannot collide with source inputs. */
+export async function authoringArtifactPath(root, destination) {
+    const canonical = async (file) => {
+        try {
+            return await realpath(file);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const parent = path.dirname(file);
+            if (parent === file)
+                return file;
+            return path.join(await canonical(parent), path.basename(file));
+        }
+    };
+    const target = await canonical(path.resolve(destination));
+    if (target === root || isWithin(root, target) && !isWithin(path.join(root, '.shoalrun'), target))
+        throw new SnapshotError('unsafe_path', 'Artifacts must be outside the project or inside .shoalrun');
+    await noSymlinks(target, path.parse(target).root);
+    return target;
+}
+export async function writeAuthoringBaseline(configFile, output) {
+    const baseline = await captureAuthoringBaseline(configFile);
+    const target = await authoringArtifactPath(baseline.project, output);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, JSON.stringify(baseline, null, 2) + '\n', { flag: 'wx' });
+    return { schemaVersion: 1, status: 'ok', baseline: target, digest: baseline.digest, files: baseline.inputs.length, excluded: baseline.excluded };
+}

package/dist/authoring-validation-command.d.ts

@@ -0,0 +1 @@
+export declare function runValidationCommand(command: 'baseline' | 'validate' | 'validation-status', args: string[], discoverConfig: () => Promise<string>): Promise<void>;

package/dist/authoring-validation-command.js

@@ -0,0 +1,54 @@
+import { writeAuthoringBaseline, SnapshotError } from './authoring-snapshot.js';
+import { authoringValidationStatus, validateAuthoringChanges, validationFailure } from './authoring-validation.js';
+export async function runValidationCommand(command, args, discoverConfig) {
+    try {
+        let config, output;
+        const options = {};
+        const positional = [];
+        const seen = new Set();
+        for (let index = 0; index < args.length; index++) {
+            const flag = args[index];
+            if (!flag.startsWith('--')) {
+                positional.push(flag);
+                continue;
+            }
+            if (!['--file', '--id'].includes(flag) && seen.has(flag))
+                throw new SnapshotError('invalid_input', `Duplicate ${flag}`);
+            seen.add(flag);
+            if (flag === '--json')
+                continue;
+            if (flag === '--run-checks' && command === 'validate') {
+                options.runConfiguredChecks = true;
+                continue;
+            }
+            const allowed = command === 'baseline' ? ['--config', '--out'] : command === 'validate' ? ['--config', '--file', '--id', '--baseline', '--artifacts'] : [];
+            const value = args[++index];
+            if (!allowed.includes(flag) || !value || value.startsWith('--'))
+                throw new SnapshotError('invalid_input', `Unknown option or missing value for ${flag}`);
+            if (flag === '--config')
+                config = value;
+            else if (flag === '--out')
+                output = value;
+            else if (flag === '--file')
+                (options.files ??= []).push(value);
+            else if (flag === '--id')
+                (options.ids ??= []).push(value);
+            else if (flag === '--baseline')
+                options.baselineFile = value;
+            else if (flag === '--artifacts')
+                options.artifactsDirectory = value;
+        }
+        if (command === 'validation-status' ? positional.length !== 1 : positional.length !== 0)
+            throw new SnapshotError('invalid_input', `Unexpected arguments for docs ${command}`);
+        if (command === 'baseline' && !output)
+            throw new SnapshotError('invalid_input', 'Usage: shoalrun docs baseline --out FILE [--config FILE]');
+        const result = command === 'validation-status' ? await authoringValidationStatus(positional[0]) : command === 'baseline' ? await writeAuthoringBaseline(config ?? await discoverConfig(), output) : await validateAuthoringChanges(config ?? await discoverConfig(), options);
+        process.stdout.write(JSON.stringify(result) + '\n');
+        if (result.status !== 'ok')
+            process.exitCode = 1;
+    }
+    catch (error) {
+        process.stdout.write(JSON.stringify(validationFailure(error)) + '\n');
+        process.exitCode = 1;
+    }
+}