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

package/dist/authoring-preview.js

@@ -0,0 +1,160 @@
+import { createServer } from 'node:http';
+import { chmod, lstat, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createSiteServer } from './server.js';
+import { validationArtifactDigest } from './authoring-validation.js';
+import { assembleAuthoringReview, loadPinnedReview, pinnedValidationStatus } from './authoring-review.js';
+import { SnapshotError } from './authoring-snapshot.js';
+const prefix = '/__shoalrun/authoring';
+const escape = (text) => String(text).replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]);
+const htmlUrl = (route) => route === '/' ? '/' : `${route.replace(/\/+$/, '')}/`;
+const link = (route, label) => `<a href="${escape(route)}">${escape(label)}</a>`;
+const message = (review) => `Snapshot ${review.snapshotId.slice(0, 12)} · ${review.status} · ${review.freshness.current ? 'current' : 'stale; this preview does not verify current edits'}. ${review.nextAction}`;
+const banner = (review) => `<aside class="shoalrun-preview-status" aria-label="Snapshot preview"><span id="shoalrun-preview-status" role="status" aria-live="polite">${escape(message(review))}</span> ${link(`${prefix}/review`, 'Review this snapshot')}</aside>`;
+const previewScript = `const status=document.getElementById('shoalrun-preview-status');let timer;async function refresh(){try{const response=await fetch('${prefix}/status',{cache:'no-store'});if(!response.ok)throw Error();const review=await response.json();status.textContent='Snapshot '+review.snapshotId.slice(0,12)+' · '+review.status+' · '+(review.freshness.current?'current':'stale; this preview does not verify current edits')+'. '+review.nextAction;}catch{status.textContent='Preview status unavailable. Confirm freshness before accepting this snapshot.';}timer=setTimeout(refresh,2000);}refresh();addEventListener('pagehide',()=>clearTimeout(timer));`;
+const css = `body.shoalrun-review{font-family:system-ui,sans-serif}body.shoalrun-review{max-width:72rem;margin:2rem auto;padding:0 1rem}.shoalrun-review table{border-collapse:collapse;width:100%}.shoalrun-review th,.shoalrun-review td{padding:.5rem;text-align:left;border-bottom:1px solid #888;vertical-align:top;overflow-wrap:anywhere}.shoalrun-review code{overflow-wrap:anywhere}.shoalrun-preview-status{position:sticky;top:0;z-index:10000;padding:.75rem;background:#fff3cd;color:#332600;border-bottom:2px solid #8a6400;font:14px/1.5 system-ui,sans-serif}.shoalrun-preview-status a{color:#332600;text-decoration:underline}.shoalrun-review section{margin:2rem 0}`;
+function reviewHtml(review) {
+    const table = (headings, rows) => `<table><thead><tr>${headings.map(heading => `<th scope="col">${escape(heading)}</th>`).join('')}</tr></thead><tbody>${rows.map(row => `<tr>${row.map(value => `<td>${value}</td>`).join('')}</tr>`).join('')}</tbody></table>`;
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Authoring review</title><link rel="stylesheet" href="${prefix}/preview.css"><script src="${prefix}/preview.js" defer></script></head><body class="shoalrun-review">${banner(review)}<main><h1>Authoring review</h1><p>Validation result: ${escape(review.validationStatus)}. Snapshot: <code>${escape(review.snapshotId)}</code>.</p>
+<section><h2>Task scope</h2><p>Baseline: ${escape(review.baseline.kind)}${review.baseline.file ? ` · ${escape(review.baseline.file)} · ${escape(review.baseline.digest ?? '')}` : ''}.</p><p>${escape(review.diff.explanation)}</p>${table(['Source', 'Change', 'Before digest', 'Snapshot digest'], review.changed.map(change => [escape(change.file), escape(change.operation), escape(change.beforeDigest ?? 'unknown'), escape(change.digest ?? 'deleted')]))}</section>
+<section><h2>Affected pages</h2>${table(['Source / ID', 'Origin', 'HTML', 'Markdown'], review.pages.map(page => [escape(`${page.file} / ${page.id}`), escape(page.origin), link(htmlUrl(page.route), page.route), link(page.markdown, page.markdown)]))}<p>Not rendered: ${escape(review.coverage.notRendered.join(', ') || 'none')}.</p><p>Page selection: ${escape(review.pageSelection)}.</p><p>Coverage: ${review.coverage.affected.length} affected sources; ${review.coverage.authored.length} authored sources in the captured project. Unchanged public pages may also be present in the site.</p></section>
+<section><h2>Checks</h2>${table(['Check', 'Status', 'Explanation'], review.checks.map(check => [escape(check.id), escape(check.status), escape(check.explanation ?? '')]))}</section>
+<section><h2>Findings</h2>${review.findings.length ? review.findings.map(finding => `<article><h3>${escape(finding.severity)}: ${escape(finding.code)}</h3><p>${escape(finding.file ?? 'Project')}${finding.location ? `:${finding.location.line}:${finding.location.column}${finding.location.key ? ` (${escape(finding.location.key)})` : ''}` : ''}</p><p>${escape(finding.explanation)}</p><p>Next: ${escape(finding.nextAction)}</p>${finding.reference ? `<p>Framework reference: <code>${escape(finding.reference)}</code> (read with docs read).</p>` : ''}${finding.relatedFiles?.length ? `<p>Related sources: ${escape(finding.relatedFiles.join(', '))}.</p>` : ''}</article>`).join('') : '<p>No findings reported. Review coverage and skipped checks before accepting the result.</p>'}</section>
+<section><h2>Dependencies</h2>${table(['Source', 'Digest', 'Role'], review.dependencies.map(dependency => [escape(dependency.file), escape(dependency.digest ?? 'unavailable'), escape(dependency.source)]))}</section>
+<section><h2>Artifacts and review limits</h2><p>Captured project: ${escape(review.artifacts.project)}</p><p>Built site: ${escape(review.artifacts.site)}</p><p>Report: ${escape(review.artifacts.report)}</p><p>${escape(review.artifacts.lifecycle)}</p><p>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.</p><p>Stop this foreground preview with Ctrl-C. Its private serving copy is removed; validation artifacts remain. After revisions, validate again and start a new preview with the new report.</p></section></main></body></html>`;
+}
+async function copySite(source, destination) {
+    let bytes = 0, count = 0;
+    const visit = async (from, to) => {
+        if (!(await lstat(from)).isDirectory())
+            throw new SnapshotError('unsafe_path', 'Preview site must be a regular directory');
+        await mkdir(to, { mode: 0o700 });
+        for (const entry of await readdir(from, { withFileTypes: true })) {
+            const input = path.join(from, entry.name), output = path.join(to, entry.name);
+            if (entry.isDirectory())
+                await visit(input, output);
+            else if (entry.isFile()) {
+                const content = await readFile(input);
+                bytes += content.length;
+                count++;
+                if (bytes > 512 * 1024 * 1024 || count > 20000)
+                    throw new SnapshotError('capture_limit', 'Preview copy exceeds 20000 files or 512 MiB.');
+                await writeFile(output, content, { flag: 'wx', mode: 0o400 });
+            }
+            else
+                throw new SnapshotError('unsafe_path', 'Preview artifacts must not contain symlinks or special files');
+        }
+    };
+    await visit(source, destination);
+}
+/** Local foreground preview of one pinned snapshot; no watch, rebuild or provider. */
+export async function startAuthoringPreview(reportFile, options = {}) {
+    const port = options.port ?? 8771;
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new SnapshotError('invalid_input', 'Preview port must be an integer from 0 to 65535');
+    const pinned = await loadPinnedReview(reportFile);
+    if (!pinned.report.artifacts.digest || pinned.review.freshness.changed.artifacts || pinned.review.freshness.reportChanged)
+        throw new SnapshotError('stale_input', 'Validation artifacts are missing or changed. Validate again before previewing.');
+    const directory = await mkdtemp(path.join(os.tmpdir(), 'shoalrun-authoring-preview-'));
+    await chmod(directory, 0o700);
+    const siteDirectory = path.join(directory, 'site');
+    let server;
+    try {
+        await copySite(pinned.report.artifacts.site, siteDirectory);
+        if (await validationArtifactDigest(siteDirectory) !== pinned.report.artifacts.digest)
+            throw new SnapshotError('stale_input', 'Site changed while copying the preview. Validate again.');
+        const after = await pinnedValidationStatus(reportFile, pinned.report, pinned.digest);
+        if (after.changed.artifacts || after.reportChanged)
+            throw new SnapshotError('stale_input', 'Validation artifacts changed while starting preview. Validate again.');
+        const site = await createSiteServer(siteDirectory);
+        const review = async () => {
+            const freshness = await pinnedValidationStatus(reportFile, pinned.report, pinned.digest);
+            if (await validationArtifactDigest(siteDirectory) !== pinned.report.artifacts.digest) {
+                freshness.current = false;
+                freshness.status = 'stale';
+                freshness.changed.artifacts = true;
+                freshness.nextAction = 'The private preview copy changed or was removed. Stop it, validate again and start a new preview.';
+            }
+            return assembleAuthoringReview(pinned.report, freshness);
+        };
+        let pending;
+        const sharedReview = () => pending ??= review().finally(() => { pending = undefined; });
+        server = createServer(async (request, response) => {
+            response.setHeader('Cache-Control', 'no-store');
+            response.setHeader('X-Content-Type-Options', 'nosniff');
+            response.setHeader('X-Robots-Tag', 'noindex');
+            response.setHeader('X-Shoalrun-Snapshot', pinned.report.snapshotId);
+            const expectedHost = `127.0.0.1:${server.address().port}`;
+            if (request.headers.host !== expectedHost) {
+                response.writeHead(421);
+                response.end('Use the returned loopback preview URL.');
+                return;
+            }
+            try {
+                const url = new URL(request.url ?? '/', `http://${expectedHost}`);
+                if (request.method !== 'GET' && request.method !== 'HEAD') {
+                    response.writeHead(405, { Allow: 'GET, HEAD' });
+                    response.end();
+                    return;
+                }
+                const send = (type, body) => { response.writeHead(200, { 'Content-Type': type }); response.end(request.method === 'HEAD' ? undefined : body); };
+                if (url.pathname === `${prefix}/preview.js`) {
+                    send('text/javascript; charset=utf-8', previewScript);
+                    return;
+                }
+                if (url.pathname === `${prefix}/preview.css`) {
+                    send('text/css; charset=utf-8', css);
+                    return;
+                }
+                const current = await sharedReview();
+                if (url.pathname === `${prefix}/status`) {
+                    send('application/json; charset=utf-8', JSON.stringify(current));
+                    return;
+                }
+                if (url.pathname === `${prefix}/review`) {
+                    send('text/html; charset=utf-8', reviewHtml(current));
+                    return;
+                }
+                // Invalidated original artifacts never become replacement preview content.
+                if (current.freshness.changed.artifacts) {
+                    response.writeHead(409, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    response.end('Preview artifacts changed. Stop, validate again, and start a new preview.');
+                    return;
+                }
+                const end = response.end.bind(response);
+                response.end = ((chunk, ...args) => {
+                    if (request.method !== 'HEAD' && response.statusCode === 200 && String(response.getHeader('Content-Type')).startsWith('text/html') && chunk) {
+                        const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+                        chunk = Buffer.from(text.replace(/<body([^>]*)>/i, `<body$1>${banner(current)}<link rel="stylesheet" href="${prefix}/preview.css"><script src="${prefix}/preview.js" defer></script>`));
+                    }
+                    return end(chunk, ...args);
+                });
+                site.emit('request', request, response);
+            }
+            catch {
+                response.writeHead(503, { 'Content-Type': 'text/plain; charset=utf-8' });
+                response.end('Preview freshness unavailable. Stop and validate again before accepting this snapshot.');
+            }
+        });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(port, '127.0.0.1', () => { server.off('error', reject); resolve(); });
+        });
+        const origin = `http://127.0.0.1:${server.address().port}`;
+        let closing;
+        const close = () => closing ??= (async () => {
+            await new Promise(resolve => { server.close(() => resolve()); server.closeAllConnections(); });
+            await rm(directory, { recursive: true, force: true });
+        })();
+        return { schemaVersion: 1, kind: 'shoalrun-authoring-preview', snapshotId: pinned.report.snapshotId, origin, reviewUrl: `${origin}${prefix}/review`, statusUrl: `${origin}${prefix}/status`,
+            pages: pinned.review.pages.map(page => ({ ...page, htmlUrl: `${origin}${htmlUrl(page.route)}`, markdownUrl: `${origin}${page.markdown}` })), directory,
+            lifecycle: 'Foreground loopback service. Ctrl-C/SIGTERM closes the server and removes only its private serving copy. Validation artifacts remain; remove only their reported directory when finished. Revalidate and restart after edits; this preview never rebuilds.', server, review, close };
+    }
+    catch (error) {
+        if (server?.listening)
+            await new Promise(resolve => server.close(() => resolve()));
+        await rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+}

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

@@ -0,0 +1,7 @@
+import { type ProjectOptions } from './authoring-project.js';
+export declare function parseProjectOptions(command: 'project' | 'source', args: string[]): {
+    config: string | undefined;
+    options: ProjectOptions;
+    file: string;
+};
+export declare function runProjectCommand(command: 'project' | 'source', args: string[], discoverConfig: () => Promise<string>): Promise<void>;

package/dist/authoring-project-command.js

@@ -0,0 +1,52 @@
+import { inspectAuthoringProject, projectSections, ProjectToolError, projectToolFailure, readAuthoringSource } from './authoring-project.js';
+export function parseProjectOptions(command, args) {
+    const options = {};
+    let config;
+    const positional = [];
+    const seen = new Set();
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (!flag.startsWith('--')) {
+            positional.push(flag);
+            continue;
+        }
+        if (seen.has(flag))
+            throw new ProjectToolError('invalid_input', `Duplicate ${flag}`);
+        seen.add(flag);
+        if (flag === '--json')
+            continue;
+        const allowed = command === 'project' ? ['--config', '--section', '--id', '--file', '--query', '--offset', '--limit', '--max-tokens'] : ['--config', '--offset', '--max-tokens'];
+        const value = args[++i];
+        if (!allowed.includes(flag) || !value || value.startsWith('--'))
+            throw new ProjectToolError('invalid_input', `Unknown option or missing value for ${flag}`);
+        if (flag === '--config')
+            config = value;
+        else if (['--offset', '--limit', '--max-tokens'].includes(flag)) {
+            if (!/^\d+$/.test(value))
+                throw new ProjectToolError('invalid_input', `${flag} must be an integer`);
+            options[flag === '--max-tokens' ? 'maxTokens' : flag === '--limit' ? 'limit' : 'offset'] = Number(value);
+        }
+        else if (flag === '--section') {
+            if (!projectSections.includes(value))
+                throw new ProjectToolError('invalid_input', `Unknown section ${value}`);
+            options.section = value;
+        }
+        else
+            options[flag.slice(2)] = value;
+    }
+    if (command === 'project' && positional.length || command === 'source' && positional.length !== 1)
+        throw new ProjectToolError('invalid_input', `Usage: shoalrun docs ${command}${command === 'source' ? ' <project-relative-file>' : ''} [--config FILE] [--json]`);
+    return { config, options, file: positional[0] };
+}
+export async function runProjectCommand(command, args, discoverConfig) {
+    try {
+        const parsed = parseProjectOptions(command, args);
+        const config = parsed.config ?? await discoverConfig();
+        const result = command === 'project' ? await inspectAuthoringProject(config, parsed.options) : await readAuthoringSource(config, parsed.file, parsed.options);
+        process.stdout.write(JSON.stringify(result) + '\n');
+    }
+    catch (error) {
+        process.stdout.write(JSON.stringify(projectToolFailure(error)) + '\n');
+        process.exitCode = 1;
+    }
+}

package/dist/authoring-project.d.ts

@@ -0,0 +1,104 @@
+export declare const projectToolSchemaVersion = 1;
+export declare const projectSections: readonly ["pages", "guidance", "configuration", "navigation", "relationships", "templates", "findings"];
+export type ProjectSection = typeof projectSections[number];
+export type ProjectOptions = {
+    section?: ProjectSection;
+    id?: string;
+    file?: string;
+    query?: string;
+    offset?: number;
+    limit?: number;
+    maxTokens?: number;
+};
+export type ProjectFinding = {
+    code: string;
+    severity: 'error' | 'warning' | 'review-needed';
+    file?: string;
+    location?: string;
+    explanation: string;
+    nextAction: string;
+    reference?: string;
+};
+export declare class ProjectToolError extends Error {
+    readonly code: 'invalid_input' | 'unknown_source' | 'unsafe_path' | 'invalid_project' | 'internal_error';
+    constructor(code: 'invalid_input' | 'unknown_source' | 'unsafe_path' | 'invalid_project' | 'internal_error', message: string);
+}
+export declare const projectToolFailure: (error: unknown) => {
+    schemaVersion: number;
+    status: "error";
+    error: {
+        code: "invalid_input" | "internal_error" | "unknown_source" | "unsafe_path" | "invalid_project";
+        message: string;
+    };
+};
+/** Read-only discovery of the current working tree, including unpublished pages.
+ * Digests describe inspected inputs; this is not a validated snapshot. */
+export declare function inspectAuthoringProject(configFile: string, options?: ProjectOptions): Promise<{
+    schemaVersion: number;
+    kind: string;
+    status: string;
+    summary: {
+        project: string;
+        config: string;
+        configDigest: string;
+        contentDir: string;
+        policyStatus: string;
+        policyInterpretation: string;
+        counts: {
+            [k: string]: number;
+        };
+        capabilities: string[];
+        references: string[];
+        checks: {
+            execution: string;
+            configured: boolean;
+            guidance: string;
+        };
+    };
+    section: "navigation" | "relationships" | "templates" | "pages" | "findings" | "guidance" | "configuration";
+    entries: any[];
+    pagination: {
+        offset: number;
+        limit: number;
+        total: number;
+        nextOffset: number | null;
+    };
+    coverage: {
+        mode: string;
+        validation: string;
+        findings: number;
+    };
+} & {
+    budget: {
+        maxTokens: number;
+        encoding: string;
+        tokens: number;
+        truncated: boolean;
+    };
+}>;
+/** Exact project-relative passage; role is context, not evidence approval. */
+export declare function readAuthoringSource(configFile: string, file: string, options?: {
+    offset?: number;
+    maxTokens?: number;
+}): Promise<{
+    content: string;
+    nextOffset: number | null;
+    schemaVersion: number;
+    kind: string;
+    status: string;
+    file: string;
+    digest: string;
+    role: string;
+    location: {
+        offset: number;
+        startLine: number;
+    };
+    applicability: string;
+} & {
+    budget: {
+        maxTokens: number;
+        encoding: string;
+        tokens: number;
+        truncated: boolean;
+    };
+}>;

package/dist/authoring-project.js

@@ -0,0 +1,287 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateAuthoringGuidance } from './authoring-guidance.js';
+import { explainSegments, loadConfig } from './config.js';
+import { readDocument } from './content-source.js';
+import { defaultLanguage } from './frontmatter.js';
+import { documentationTokens } from './documentation-core.js';
+import { builtinAuthoringTemplates } from './scaffold.js';
+import { phraseMatches, queryUnits, validateSearchSynonyms } from './search-synonyms.js';
+export const projectToolSchemaVersion = 1;
+export const projectSections = ['pages', 'guidance', 'configuration', 'navigation', 'relationships', 'templates', 'findings'];
+export class ProjectToolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export const projectToolFailure = (error) => ({ schemaVersion: projectToolSchemaVersion, status: 'error', error: { code: error instanceof ProjectToolError ? error.code : 'internal_error', message: error instanceof Error ? error.message : 'Project inspection failed' } });
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const inside = (root, file) => file.startsWith(root + path.sep);
+const templatesRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../templates');
+function integer(value, fallback, min, max, name) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < min || result > max)
+        throw new ProjectToolError('invalid_input', `${name} must be an integer from ${min} to ${max}`);
+    return result;
+}
+function text(value, name) {
+    if (value !== undefined && (typeof value !== 'string' || !value.trim() || value.length > 512))
+        throw new ProjectToolError('invalid_input', `${name} must be nonempty text of at most 512 characters`);
+}
+function budget(data, maxTokens, truncated) {
+    const result = { ...data, budget: { maxTokens, encoding: 'cl100k_base', tokens: maxTokens, truncated } };
+    // Count the serialized envelope too, conservatively reserving count digits.
+    result.budget.tokens = documentationTokens(JSON.stringify(result));
+    for (let i = 0; i < 8; i++) {
+        const actual = documentationTokens(JSON.stringify(result));
+        if (actual <= result.budget.tokens)
+            break;
+        result.budget.tokens = actual;
+    }
+    return result;
+}
+async function safeFile(root, file) {
+    if (!file || path.isAbsolute(file) || /[\\\0\r\n]/.test(file) || file.split('/').includes('..'))
+        throw new ProjectToolError('unsafe_path', 'Source paths must stay project-relative');
+    let actual;
+    try {
+        actual = await realpath(path.resolve(root, file));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new ProjectToolError('unknown_source', `Source not found: ${file}`);
+        throw error;
+    }
+    if (!inside(root, actual))
+        throw new ProjectToolError('unsafe_path', `Source escapes project: ${file}`);
+    return actual;
+}
+async function openProject(configFile) {
+    try {
+        const config = await realpath(path.resolve(configFile));
+        const root = path.dirname(config);
+        const loaded = await loadConfig(config);
+        const guidance = validateAuthoringGuidance(loaded.value.authoring);
+        return { config, root, loaded, guidance };
+    }
+    catch (error) {
+        throw new ProjectToolError('invalid_project', `Cannot load project configuration: ${error.message}`);
+    }
+}
+/** Read-only discovery of the current working tree, including unpublished pages.
+ * Digests describe inspected inputs; this is not a validated snapshot. */
+export async function inspectAuthoringProject(configFile, options = {}) {
+    const section = options.section ?? 'pages';
+    if (!projectSections.includes(section))
+        throw new ProjectToolError('invalid_input', `Unknown project section ${section}`);
+    for (const key of ['id', 'file', 'query'])
+        text(options[key], key);
+    if ([options.id, options.file, options.query].filter(value => value !== undefined).length > 1)
+        throw new ProjectToolError('invalid_input', 'Select at most one of id, file or query');
+    if ((options.id || options.file || options.query) && !['pages', 'navigation', 'relationships'].includes(section))
+        throw new ProjectToolError('invalid_input', 'Selectors apply to pages, navigation or relationships');
+    const offset = integer(options.offset, 0, 0, Number.MAX_SAFE_INTEGER, 'offset');
+    const limit = integer(options.limit, 20, 1, 100, 'limit');
+    const maxTokens = integer(options.maxTokens, 8192, 1024, 100000, 'maxTokens');
+    const { root, config, loaded, guidance } = await openProject(configFile);
+    const value = loaded.value;
+    const relative = (file) => path.relative(root, file);
+    const digests = new Map();
+    const source = async (segments) => {
+        const owner = explainSegments(loaded, segments).source;
+        if (!digests.has(owner.file))
+            digests.set(owner.file, digest(await readFile(owner.file, 'utf8')));
+        return { file: relative(owner.file), location: segments.join('.'), digest: digests.get(owner.file), role: 'configuration', applicability: 'configured-value' };
+    };
+    const findings = [];
+    const pages = [];
+    const bodies = new Map();
+    const instructions = [];
+    const walk = async (directory) => {
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const file = path.join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                findings.push({ code: 'project.symlink-skipped', severity: 'warning', file: relative(file), explanation: 'Discovery does not follow content symlinks.', nextAction: 'Inspect this source with the harness and use regular authored files for project discovery.' });
+            }
+            else if (entry.isDirectory())
+                await walk(file);
+            else if (entry.isFile() && entry.name === 'AGENTS.md')
+                instructions.push(relative(file));
+            else if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
+                const raw = await readFile(file, 'utf8');
+                try {
+                    const doc = await readDocument(file, value.frontmatter, undefined, raw);
+                    const fm = doc.frontmatter;
+                    pages.push({ id: fm.id, file: relative(file), digest: digest(raw), title: fm.title, summary: fm.summary, type: fm.type, slug: fm.slug,
+                        publication: { channel: fm.channel ?? value.publications?.defaults?.channel, version: fm.version ?? value.publications?.defaults?.version, language: fm.language ?? defaultLanguage(value), ...(fm.publications ? { publications: fm.publications } : {}) },
+                        access: fm.access ?? null, aliases: [] });
+                    bodies.set(relative(file), doc.body);
+                }
+                catch (error) {
+                    findings.push({ code: 'project.invalid-page', severity: 'error', file: relative(file), explanation: error.message, nextAction: 'Repair the page metadata and inspect again.', reference: 'guide.frontmatter' });
+                }
+            }
+        }
+    };
+    const content = path.resolve(root, value.site?.contentDir ?? 'content');
+    if (!inside(root, content))
+        throw new ProjectToolError('unsafe_path', 'Content directory must be inside the project');
+    try {
+        if (await realpath(content) !== content)
+            throw new ProjectToolError('unsafe_path', 'Content directory must not use symlinks');
+        await walk(content);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        findings.push({ code: 'project.missing-content', severity: 'warning', file: relative(content), explanation: 'No content directory exists yet.', nextAction: 'Create authored pages when the task requires them.' });
+    }
+    const byId = new Map();
+    for (const page of pages)
+        byId.set(page.id, [...(byId.get(page.id) ?? []), page]);
+    // Link-label aliases are leads, not identities or policy. Keep the experiment's
+    // useful heuristic without its workflow dependency or prompt representation.
+    for (const body of bodies.values())
+        for (const match of body.matchAll(/\[([^\]\n]+)\]\(doc:([^\s)#]+)(?:#[^)]*)?\)/g)) {
+            for (const page of byId.get(match[2]) ?? [])
+                if (match[1].length <= 100 && match[1] !== page.title && !page.aliases.includes(match[1]) && page.aliases.length < 5)
+                    page.aliases.push(match[1]);
+        }
+    const units = options.query ? queryUnits(options.query, validateSearchSynonyms(value.search?.synonyms)) : [];
+    const selected = pages.map((page) => {
+        const labels = `${page.id} ${page.file} ${page.title} ${page.summary} ${page.aliases.join(' ')}`;
+        const matched = units.filter(unit => [unit.term, ...unit.alternatives].some(term => phraseMatches(`${labels}\n${bodies.get(page.file)}`, term)));
+        const score = matched.reduce((sum, unit) => sum + ([unit.term, ...unit.alternatives].some(term => phraseMatches(labels, term)) ? 2 : 1), 0);
+        return { ...page, ...(options.query ? { matchedTerms: matched.map(unit => unit.term), score } : {}) };
+    }).filter(page => (!options.id || page.id === options.id) && (!options.file || page.file === options.file) && (!options.query || page.score > 0))
+        .sort((a, b) => (b.score ?? 0) - (a.score ?? 0) || a.file.localeCompare(b.file));
+    const selectedIds = new Set(selected.map(page => page.id));
+    const guidanceEntries = [];
+    // Policy for included configuration files can live outside content. Inspect
+    // their ancestor directories too, without traversing dependencies/build output.
+    const policyDirectories = new Set([root]);
+    for (const file of loaded.dependencies) {
+        let directory = path.dirname(file);
+        while (inside(root, directory)) {
+            policyDirectories.add(directory);
+            directory = path.dirname(directory);
+        }
+    }
+    for (const directory of policyDirectories) {
+        const file = relative(path.join(directory, 'AGENTS.md'));
+        try {
+            await safeFile(root, file);
+            instructions.unshift(file);
+        }
+        catch (error) {
+            if (!(error instanceof ProjectToolError && error.code === 'unknown_source'))
+                throw error;
+        }
+    }
+    if (guidance?.directives)
+        guidanceEntries.push({ kind: 'directives', text: guidance.directives, ...await source(['authoring', 'directives']), role: 'policy', applicability: 'project; interpretation requires author review' });
+    for (const [role, files] of [['policy', instructions], ['style', guidance?.guideFiles ?? []], ['example', guidance?.exemplarFiles ?? []]]) {
+        for (const file of [...new Set(files)]) {
+            try {
+                const actual = await safeFile(root, file);
+                guidanceEntries.push({ kind: 'file', file, digest: digest(await readFile(actual, 'utf8')), role, applicability: role === 'policy' ? `directory scope: ${path.dirname(file)}` : 'project authoring guidance', read: { command: 'docs source', file } });
+            }
+            catch (error) {
+                if (!(error instanceof ProjectToolError))
+                    throw error;
+                findings.push({ code: 'project.guidance-unavailable', severity: 'review-needed', file, explanation: error.message, nextAction: 'Locate or repair the declared guidance; ask the author about missing policy.' });
+            }
+        }
+    }
+    const policyStatus = guidanceEntries.some(entry => entry.role === 'policy') ? 'requires-interpretation' : 'missing';
+    if (policyStatus === 'missing')
+        findings.push({ code: 'project.policy-missing', severity: 'review-needed', explanation: 'No project AGENTS.md or authoring.directives was found. Guide files may contain additional policy.', nextAction: 'Read configured guides and ask the author about task-specific companion obligations; do not infer permission.' });
+    const configuration = [];
+    const leaves = async (at, segments) => {
+        if (at && typeof at === 'object' && Object.keys(at).length) {
+            for (const key of Object.keys(at))
+                await leaves(at[key], [...segments, key]);
+        }
+        else
+            configuration.push({ value: at, ...await source(segments) });
+    };
+    for (const key of ['site', 'frontmatter', 'publications', 'authoring', 'audit', 'templates', 'search'])
+        if (value[key] !== undefined)
+            await leaves(value[key], [key]);
+    const navigation = [];
+    const nav = async (nodes, segments) => {
+        for (let index = 0; index < nodes.length; index++) {
+            const node = nodes[index], at = [...segments, String(index)];
+            const { items, ...fields } = node;
+            if (!options.id && !options.file && !options.query || selectedIds.has(node.doc))
+                navigation.push({ ...fields, ...await source(at) });
+            if (Array.isArray(items))
+                await nav(items, [...at, 'items']);
+        }
+    };
+    if (Array.isArray(value.navigation))
+        await nav(value.navigation, ['navigation']);
+    const relationships = [];
+    for (let index = 0; index < (value.relationships ?? []).length; index++) {
+        const edge = value.relationships[index];
+        if (!options.id && !options.file && !options.query || selectedIds.has(edge.from) || selectedIds.has(edge.to))
+            relationships.push({ ...edge, ...await source(['relationships', String(index)]) });
+    }
+    const templates = [];
+    for (const id of [...new Set([...Object.keys(builtinAuthoringTemplates), ...Object.keys(value.templates ?? {})])].sort()) {
+        const local = value.templates?.[id], template = local ?? builtinAuthoringTemplates[id];
+        templates.push({ id, ...template, source: local ? await source(['templates', id]) : { file: `templates/${template.body}`, role: 'syntax-reference', applicability: 'bundled scaffold template' },
+            bodyFile: local ? relative(path.resolve(path.dirname(explainSegments(loaded, ['templates', id, 'body']).source.file), template.body)) : path.join(templatesRoot, template.body), reference: 'guide.templates' });
+    }
+    const collections = { pages: selected, guidance: guidanceEntries, configuration, navigation, relationships, templates, findings };
+    const records = collections[section];
+    const counts = Object.fromEntries(Object.entries(collections).map(([key, items]) => [key, items.length]));
+    const summary = { project: root, config: relative(config), configDigest: loaded.digest, contentDir: relative(content), policyStatus,
+        policyInterpretation: 'Read all applicable sources; conflicting prose requires author review. No companion obligation is inferred.',
+        counts, capabilities: ['project-discovery', 'project-source-read', 'documentation-search-read'], references: ['guide.frontmatter', 'guide.frontmatter-reference', 'guide.add-page', 'guide.component.steps', 'guide.templates'],
+        checks: { execution: 'not-run', configured: value.audit !== undefined, guidance: 'Inspect configuration section and project instructions; no shell commands are executed.' } };
+    let entries = records.slice(offset, offset + limit);
+    while (true) {
+        const nextOffset = offset + entries.length < records.length ? offset + entries.length : null;
+        const result = budget({ schemaVersion: projectToolSchemaVersion, kind: 'shoalrun-authoring-project', status: 'ok', summary, section, entries,
+            pagination: { offset, limit, total: records.length, nextOffset }, coverage: { mode: 'working-tree-inspection', validation: 'not-run', findings: findings.length } }, maxTokens, nextOffset !== null);
+        if (result.budget.tokens <= maxTokens)
+            return result;
+        if (!entries.length || entries.length === 1)
+            throw new ProjectToolError('invalid_input', 'maxTokens is too small for this entry; increase the budget or use docs source for a bounded passage.');
+        entries = entries.slice(0, -1);
+    }
+}
+/** Exact project-relative passage; role is context, not evidence approval. */
+export async function readAuthoringSource(configFile, file, options = {}) {
+    const offset = integer(options.offset, 0, 0, Number.MAX_SAFE_INTEGER, 'offset');
+    const maxTokens = integer(options.maxTokens, 4096, 1024, 100000, 'maxTokens');
+    const { root, loaded, guidance } = await openProject(configFile);
+    const actual = await safeFile(root, file);
+    const raw = await readFile(actual, 'utf8');
+    const chars = [...raw];
+    if (offset > chars.length)
+        throw new ProjectToolError('invalid_input', 'offset exceeds source length');
+    const role = loaded.dependencies.includes(actual) ? 'configuration' : path.basename(file) === 'AGENTS.md' ? 'policy' : guidance?.guideFiles?.includes(file) ? 'style' : guidance?.exemplarFiles?.includes(file) ? 'example' : Object.values(guidance?.pageSources ?? {}).flat().includes(file) ? 'technical-evidence' : 'unclassified';
+    const metadata = { schemaVersion: projectToolSchemaVersion, kind: 'shoalrun-authoring-source', status: 'ok', file, digest: digest(raw), role,
+        location: { offset, startLine: chars.slice(0, offset).filter(char => char === '\n').length + 1 }, applicability: 'Read source in context; editorial guidance and target pages cannot establish new technical claims.' };
+    const candidate = (length) => budget({ ...metadata, content: chars.slice(offset, offset + length).join(''), nextOffset: offset + length < chars.length ? offset + length : null }, maxTokens, offset + length < chars.length);
+    let low = 0, high = chars.length - offset;
+    if (candidate(0).budget.tokens > maxTokens)
+        throw new ProjectToolError('invalid_input', 'maxTokens is too small for source metadata');
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (candidate(middle).budget.tokens <= maxTokens)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    if (!low && offset < chars.length)
+        throw new ProjectToolError('invalid_input', 'maxTokens is too small for a source passage');
+    return candidate(low);
+}

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

@@ -0,0 +1 @@
+export declare function runAuthoringReviewCommand(command: 'review' | 'preview', args: string[]): Promise<void>;