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

package/dist/mcp-node.js

@@ -0,0 +1,68 @@
+import { Readable } from 'node:stream';
+import { once } from 'node:events';
+import { mcpRequestLimit } from './mcp-http.js';
+export async function bridgeMcp(request, response, handler) {
+    if (Number(request.headers['content-length']) > mcpRequestLimit) {
+        response.writeHead(413, { 'Content-Type': 'application/json' });
+        response.end('{"error":"MCP request too large"}');
+        request.resume();
+        return;
+    }
+    const controller = new AbortController();
+    const abort = () => { if (!response.writableEnded)
+        controller.abort(); };
+    response.setTimeout(15_000, () => { controller.abort(); response.destroy(); });
+    request.on('aborted', abort);
+    response.on('close', abort);
+    try {
+        const headers = new Headers();
+        for (const [name, value] of Object.entries(request.headers))
+            if (value !== undefined)
+                headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+        let size = 0;
+        const body = request.method === 'POST' ? new ReadableStream({
+            async start(stream) {
+                try {
+                    for await (const chunk of request) {
+                        size += chunk.length;
+                        if (size > mcpRequestLimit) {
+                            stream.error(new Error('MCP request too large'));
+                            return;
+                        }
+                        stream.enqueue(chunk);
+                    }
+                    stream.close();
+                }
+                catch (error) {
+                    stream.error(error);
+                }
+            },
+        }) : undefined;
+        const web = new Request(`http://${request.headers.host ?? 'localhost'}${request.url ?? '/'}`, { method: request.method, headers, signal: controller.signal, ...(body ? { body, duplex: 'half' } : {}) });
+        const local = ['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(request.socket.localAddress ?? '');
+        const result = await handler(web, { local });
+        response.writeHead(result.status, Object.fromEntries(result.headers));
+        if (!result.body) {
+            response.end();
+            return;
+        }
+        for await (const chunk of Readable.fromWeb(result.body)) {
+            if (!response.write(chunk))
+                await once(response, 'drain', { signal: controller.signal });
+        }
+        response.end();
+    }
+    catch {
+        if (!response.headersSent && !response.destroyed) {
+            response.writeHead(sizeStatus(request), { 'Content-Type': 'application/json' });
+            response.end('{"error":"MCP request could not be processed"}');
+        }
+        else
+            response.destroy();
+    }
+    finally {
+        request.off('aborted', abort);
+        response.off('close', abort);
+    }
+}
+function sizeStatus(request) { return Number(request.headers['content-length']) > mcpRequestLimit ? 413 : 400; }

package/dist/mcp-vercel-runtime.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function createVercelMcpHandler(directory: string, env?: NodeJS.ProcessEnv): Promise<(request: Request) => Promise<Response>>;
+export declare function vercelMcpNodeAdapter(directory: string): (request: IncomingMessage, response: ServerResponse) => Promise<void>;

package/dist/mcp-vercel-runtime.js

@@ -0,0 +1,36 @@
+import { loadMcpRuntime, createMcpHttpHandler } from './mcp-http.js';
+import { bridgeMcp } from './mcp-node.js';
+export async function createVercelMcpHandler(directory, env = process.env) {
+    const loaded = await loadMcpRuntime(directory);
+    if (!loaded)
+        throw new Error('Missing MCP function corpus');
+    const hosts = [env.VERCEL_URL, env.VERCEL_BRANCH_URL, env.VERCEL_PROJECT_PRODUCTION_URL].filter((value) => !!value);
+    for (const value of hosts) {
+        // Trust only reserved deployment metadata, never request/forwarded headers or wildcard domains.
+        const url = new URL(`https://${value}`);
+        if (url.host !== value.toLowerCase() || url.pathname !== '/' || url.search || url.hash || url.username || url.password)
+            throw new Error('Invalid Vercel MCP deployment hostname');
+        loaded.runtime.allowedHosts.push(url.hostname);
+        loaded.runtime.allowedOrigins.push(url.origin);
+    }
+    const handler = createMcpHttpHandler(loaded);
+    // A function's loopback socket may be its platform proxy, not a local developer.
+    return (request) => handler(request);
+}
+export function vercelMcpNodeAdapter(directory) {
+    let pending;
+    return async (request, response) => {
+        try {
+            pending ??= createVercelMcpHandler(directory).catch(error => { pending = undefined; throw error; });
+            await bridgeMcp(request, response, await pending);
+        }
+        catch {
+            if (!response.headersSent) {
+                response.writeHead(503, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                response.end('{"error":"MCP documentation is unavailable"}');
+            }
+            else
+                response.destroy();
+        }
+    };
+}

package/dist/mcp-vercel.d.ts

@@ -0,0 +1,15 @@
+export declare function removeStaleMcpFunctions(directory: string, keep?: string): Promise<void>;
+export type McpFunctionResult = {
+    added: false;
+} | {
+    added: true;
+    directory: string;
+    path: string;
+    buildId: string;
+    corpusDigest: string;
+};
+export declare function addMcpFunction(input: {
+    staticDirectory: string;
+    functionsDirectory: string;
+    distDirectory?: string;
+}): Promise<McpFunctionResult>;

package/dist/mcp-vercel.js

@@ -0,0 +1,65 @@
+import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { loadMcpRuntime } from './mcp-http.js';
+import { mcpRuntimePath } from './mcp-integrity.js';
+import { copyFunctionRuntime } from './function-package.js';
+const marker = 'shoalrun-function.json';
+async function owned(directory) {
+    try {
+        const record = JSON.parse(await readFile(path.join(directory, marker), 'utf8'));
+        return record.schemaVersion === 1 && record.owner === 'shoalrun-mcp';
+    }
+    catch {
+        return false;
+    }
+}
+export async function removeStaleMcpFunctions(directory, keep) {
+    for (const entry of await readdir(directory, { withFileTypes: true }).catch(() => [])) {
+        if (!entry.isDirectory())
+            continue;
+        const child = path.join(directory, entry.name);
+        if (entry.name.endsWith('.func')) {
+            if (child !== keep && await owned(child))
+                await rm(child, { recursive: true, force: true });
+        }
+        else
+            await removeStaleMcpFunctions(child, keep);
+    }
+}
+export async function addMcpFunction(input) {
+    const loaded = await loadMcpRuntime(input.staticDirectory);
+    if (!loaded)
+        return { added: false };
+    const target = path.join(input.functionsDirectory, `${loaded.runtime.path.slice(1)}.func`);
+    if (await stat(target).then(() => true, () => false) && !await owned(target))
+        throw new Error(`MCP function would replace an unrelated function: ${loaded.runtime.path}`);
+    const staging = `${target}.staging-${randomUUID()}`;
+    await mkdir(staging, { recursive: true });
+    try {
+        const site = path.join(staging, 'site');
+        await mkdir(site);
+        // Copy only the generated runtime, parent identity, and verified scoped inventory.
+        for (const name of [mcpRuntimePath.slice(1), 'build-info.json'])
+            await cp(path.join(input.staticDirectory, name), path.join(site, name));
+        for (const name of Object.keys(loaded.runtime.inventory)) {
+            const destination = path.join(site, loaded.runtime.dataDirectory, name);
+            await mkdir(path.dirname(destination), { recursive: true });
+            await cp(path.join(loaded.directory, name), destination);
+        }
+        await loadMcpRuntime(site); // verify copied bytes, not merely the source inventory
+        const dist = input.distDirectory ?? path.dirname(fileURLToPath(import.meta.url));
+        await copyFunctionRuntime(dist, 'mcp-vercel-runtime.js', staging);
+        await writeFile(path.join(staging, 'package.json'), JSON.stringify({ type: 'module' }) + '\n');
+        await writeFile(path.join(staging, marker), JSON.stringify({ schemaVersion: 1, owner: 'shoalrun-mcp' }) + '\n');
+        await writeFile(path.join(staging, 'index.js'), `import { fileURLToPath } from 'node:url';\nimport { vercelMcpNodeAdapter } from './lib/mcp-vercel-runtime.js';\nexport default vercelMcpNodeAdapter(fileURLToPath(new URL('./site/', import.meta.url)));\n`);
+        await writeFile(path.join(staging, '.vc-config.json'), JSON.stringify({ runtime: 'nodejs22.x', handler: 'index.js', launcherType: 'Nodejs', shouldAddHelpers: false, maxDuration: 30, memory: 1024 }, null, 2) + '\n');
+        await rm(target, { recursive: true, force: true });
+        await rename(staging, target);
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+    return { added: true, directory: target, path: loaded.runtime.path, buildId: loaded.runtime.buildId, corpusDigest: loaded.runtime.corpusDigest };
+}

package/dist/metadata-provider.d.ts

@@ -0,0 +1,19 @@
+export type MetadataContext = {
+    file: string;
+    source: Readonly<Record<string, unknown>>;
+    projectRoot: string;
+};
+export type MetadataResult = {
+    values: Record<string, unknown>;
+    ownedKeys?: string[];
+    dependencies?: string[];
+};
+export type MetadataProvider = (context: MetadataContext) => Promise<MetadataResult | undefined> | MetadataResult | undefined;
+export declare function loadMetadataProvider(setting: unknown, declaringFile: string): Promise<{
+    provide: MetadataProvider;
+    module: string;
+} | undefined>;
+export declare function mergeProvidedMetadata(source: Record<string, unknown>, result: MetadataResult | undefined, file: string): {
+    page: Record<string, unknown>;
+    dependencies: string[];
+};

package/dist/metadata-provider.js

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const safeKey = (key) => /^[A-Za-z_][A-Za-z0-9_-]*$/.test(key) && !['__proto__', 'prototype', 'constructor'].includes(key);
+const fixed = new Set(['id', 'slug', 'channel', 'version', 'language', 'access']);
+export async function loadMetadataProvider(setting, declaringFile) {
+    if (setting === undefined)
+        return undefined;
+    if (!object(setting) || Object.keys(setting).some(key => key !== 'module') || typeof setting.module !== 'string' || !setting.module.trim())
+        throw new Error('metadata.provider needs a local module path');
+    const module = path.resolve(path.dirname(declaringFile), setting.module);
+    const imported = await import(pathToFileURL(module).href);
+    if (typeof imported.provideMetadata !== 'function')
+        throw new Error(`${module}: metadata provider must export provideMetadata(context)`);
+    return { provide: imported.provideMetadata, module };
+}
+export function mergeProvidedMetadata(source, result, file) {
+    if (result === undefined)
+        return { page: source, dependencies: [] };
+    if (!object(result) || !object(result.values))
+        throw new Error(`${file}: metadata provider must return { values }`);
+    const values = result.values;
+    const ownedKeys = result.ownedKeys ?? Object.keys(values);
+    if (!Array.isArray(ownedKeys) || ownedKeys.some(key => typeof key !== 'string' || !safeKey(key)) || new Set(ownedKeys).size !== ownedKeys.length)
+        throw new Error(`${file}: metadata provider ownedKeys must be unique top-level field names`);
+    for (const key of Object.keys(values)) {
+        if (!safeKey(key) || fixed.has(key))
+            throw new Error(`${file}: metadata provider cannot set ${key}`);
+        if (!ownedKeys.includes(key))
+            throw new Error(`${file}: metadata provider value ${key} must be owned`);
+    }
+    for (const key of ownedKeys)
+        if (Object.hasOwn(source, key))
+            throw new Error(`${file}: ${key} is owned by the metadata provider and also appears in page frontmatter`);
+    if (result.dependencies !== undefined && (!Array.isArray(result.dependencies) || result.dependencies.some(item => typeof item !== 'string' || !path.isAbsolute(item))))
+        throw new Error(`${file}: metadata provider dependencies must be absolute file paths`);
+    return { page: { ...source, ...values }, dependencies: result.dependencies ?? [] };
+}

package/dist/negotiation.d.ts

@@ -0,0 +1,10 @@
+export type PublishedRoute = {
+    url: string;
+    markdownUrl: string;
+};
+export declare function homeUrl(documents: Array<{
+    id?: string;
+    url: string;
+}>): string | undefined;
+export declare function wantsMarkdown(accept: string | undefined): boolean;
+export declare function negotiatedDocument(pathname: string, accept: string | undefined, documents: PublishedRoute[]): PublishedRoute | undefined;

package/dist/negotiation.js

@@ -0,0 +1,35 @@
+export function homeUrl(documents) {
+    return (documents.find(item => item.id === 'guide.overview') ?? documents.find(item => item.url === '/reference') ?? documents[0])?.url;
+}
+function quality(accept, mediaType) {
+    let exact;
+    let wildcard;
+    for (const entry of accept.split(',')) {
+        const [type, ...parameters] = entry.trim().toLowerCase().split(';').map(part => part.trim());
+        if (type !== mediaType && type !== 'text/*' && type !== '*/*')
+            continue;
+        const q = parameters.find(part => part.startsWith('q='));
+        const value = q ? Number(q.slice(2)) : 1;
+        if (!Number.isFinite(value) || value < 0 || value > 1)
+            continue;
+        if (type === mediaType)
+            exact = Math.max(exact ?? 0, value);
+        else
+            wildcard = Math.max(wildcard ?? 0, value);
+    }
+    return exact ?? wildcard ?? 0;
+}
+export function wantsMarkdown(accept) {
+    if (!accept)
+        return false;
+    if (!accept.split(',').some(entry => entry.trim().toLowerCase().split(';')[0].trim() === 'text/markdown'))
+        return false;
+    const markdown = quality(accept, 'text/markdown');
+    return markdown > 0 && markdown >= quality(accept, 'text/html');
+}
+export function negotiatedDocument(pathname, accept, documents) {
+    const route = pathname === '/' ? '/' : pathname.replace(/\/+$/, '');
+    if (!wantsMarkdown(accept))
+        return undefined;
+    return documents.find(document => document.url === route);
+}

package/dist/not-found.d.ts

@@ -0,0 +1,16 @@
+export type NotFoundAppearance = {
+    stylesheets: Array<{
+        url: string;
+        kind?: 'theme' | 'palette';
+    }>;
+    theme: string;
+    palette: string;
+    mode: 'light' | 'dark' | 'system';
+    modeScript?: string;
+    switcher?: {
+        url: string;
+        settings: string;
+    };
+};
+export declare function addNotFoundTwin(html: string, twin: string): string;
+export declare function notFoundPage(basePath: string, home: string, markdown?: boolean, twin?: string, search?: boolean, appearance?: NotFoundAppearance): string;

package/dist/not-found.js

@@ -0,0 +1,25 @@
+const escape = (value) => value.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]);
+export function addNotFoundTwin(html, twin) {
+    return html.replace(/(<ul>[\s\S]*?<\/li>)/, match => `${match}<li><a href="${escape(twin)}"><span class="label">Read the HTML page<span aria-hidden="true">→</span></span><span class="description">The browser version of this page is still available.</span></a></li>`);
+}
+export function notFoundPage(basePath, home, markdown = false, twin, search = true, appearance) {
+    const links = [
+        { title: 'Go to homepage', url: home },
+        ...(twin ? [{ title: 'Read the HTML page', url: twin }] : []),
+        { title: 'Documentation index', url: `${basePath}/${markdown ? 'llms.min.txt' : 'llms.txt'}` },
+        ...(search ? [{ title: 'Search index', url: `${basePath}/${markdown ? 'search-index.min.json' : 'search-index.json'}` }] : [])
+    ];
+    if (markdown)
+        return `# 404: Page not found\n\nTry one of these resources:\n\n${links.map(link => `- [${link.title}](${encodeURI(link.url).replace(/[()]/g, c => c === '(' ? '%28' : '%29')})`).join('\n')}\n`;
+    const descriptions = {
+        'Read the HTML page': 'The browser version of this page is still available.',
+        'Documentation index': 'Browse the published pages and their summaries.',
+        'Search index': 'Explore the downloadable index of documentation text.',
+        'Go to homepage': 'Return to the beginning and choose a new path.'
+    };
+    const head = appearance ? `${appearance.modeScript ? `<script src="${escape(appearance.modeScript)}"></script>` : ''}${appearance.stylesheets.map(sheet => `<link rel="stylesheet" href="${escape(sheet.url)}"${sheet.kind ? ` data-theme-link="${sheet.kind}"` : ''}>`).join('')}${appearance.switcher ? `<script src="${escape(appearance.switcher.url)}" data-themes="${escape(appearance.switcher.settings)}"></script>` : ''}` : '';
+    return `<!doctype html><html lang="en"${appearance ? ` data-theme="${escape(appearance.theme)}" data-palette="${escape(appearance.palette)}"` : ''}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex"><title>404: Page not found</title>${head}<style>
+:root{color-scheme:${appearance?.mode === 'system' || !appearance ? 'light dark' : appearance.mode};font-family:var(--font-body,ui-sans-serif),system-ui,sans-serif;color:var(--color-text,#193b33);background:var(--color-page,#f5f8f6);--surface:var(--color-surface,#fff);--muted:var(--color-muted,#526b62);--line:var(--color-border,#d4e2db);--accent:var(--color-link,#177866);--wash:var(--color-field-surface,#e8f2ed)}
+*{box-sizing:border-box}body{margin:0;min-height:100svh;display:grid;place-items:center;padding:clamp(1.25rem,5vw,4rem);background:radial-gradient(ellipse at 10% 0%,var(--wash),transparent 55%)}main{width:100%;max-width:46rem;padding:clamp(1.5rem,5vw,3.5rem);background:var(--surface);border:1px solid var(--line);border-radius:calc(var(--radius-panel,.75rem)*2);box-shadow:0 20px 65px #173c3210}.status{display:inline-block;padding:.3rem .7rem;border-radius:2rem;background:var(--wash);color:var(--accent);font-size:.8rem;font-weight:750;letter-spacing:.08em}h1{font-family:var(--font-heading,inherit);font-size:clamp(2.2rem,6vw,3.8rem);line-height:1.1;letter-spacing:-.045em;margin:1.15rem 0}p{color:var(--muted);font-size:1.05rem;line-height:1.65;max-width:34rem;margin:0 0 2rem}ul{list-style:none;padding:0;margin:0;display:grid;gap:.7rem}li{margin:0}a{display:block;padding:1rem 1.2rem;border:1px solid var(--line);border-radius:var(--radius-panel,.85rem);text-decoration:none;color:inherit}a:hover{background:var(--wash);border-color:var(--accent)}a:focus-visible{outline:3px solid var(--accent);outline-offset:4px}.label{font-family:var(--font-ui,var(--font-body,inherit));display:flex;justify-content:space-between;gap:1rem;color:var(--accent);font-weight:700}.description{display:block;margin-top:.3rem;color:var(--muted);font-size:.9rem;line-height:1.5}${appearance ? '' : '@media(prefers-color-scheme:dark){:root{color:#e1eee7;background:#10231e;--surface:#172f28;--muted:#b5c9bf;--line:#355448;--accent:#8dd9be;--wash:#213f33}}'}@media(max-width:400px){main{border-radius:var(--radius-panel,1rem)}a{padding:.85rem}}
+</style></head><body><main><span class="status">404</span><h1>Page not found</h1><p>The page you’re looking for couldn’t be found. These links can help you find your way back.</p><ul>${links.map(link => `<li><a href="${escape(link.url)}"><span class="label">${escape(link.title)}<span aria-hidden="true">→</span></span><span class="description">${escape(descriptions[link.title])}</span></a></li>`).join('')}</ul></main></body></html>\n`;
+}

package/dist/output-commit.d.ts

@@ -0,0 +1 @@
+export declare function commitArtifacts(target: string, artifacts: Map<string, string | Buffer>, prepare?: () => Promise<void>, kind?: 'site' | 'export'): Promise<void>;

package/dist/output-commit.js

@@ -0,0 +1,133 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonical } from './output-location.js';
+const running = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (error) {
+    return error.code === 'EPERM';
+} };
+async function lockOutput(target) {
+    const file = `${target}.shoalrun.lock`;
+    await mkdir(path.dirname(target), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const handle = await open(file, 'wx');
+            try {
+                await handle.writeFile(String(process.pid));
+            }
+            catch (error) {
+                await handle.close();
+                await rm(file, { force: true });
+                throw error;
+            }
+            return async () => { await handle.close(); await rm(file, { force: true }); };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const pid = Number(await readFile(file, 'utf8').catch(() => '0'));
+            if (!pid || running(pid))
+                throw new Error(`Output directory ${target} is already being built`);
+            await rm(file, { force: true });
+        }
+    }
+    throw new Error(`Output directory ${target} is already being built`);
+}
+async function recoverOutput(target) {
+    const directory = path.dirname(target);
+    const prefix = `${path.basename(target)}.staging-`;
+    const entries = await readdir(directory).catch(() => []);
+    const abandoned = [];
+    for (const name of entries) {
+        const match = name.startsWith(prefix) ? /^(\d+)(?:-[a-f0-9-]+)?(?:-previous)?$/.exec(name.slice(prefix.length)) : null;
+        if (!match || Number(match[1]) === process.pid || running(Number(match[1])))
+            continue;
+        abandoned.push(path.join(directory, name));
+    }
+    const previous = abandoned.filter(file => file.endsWith('-previous'));
+    const exists = await stat(target).then(() => true, (error) => { if (error.code === 'ENOENT')
+        return false; throw error; });
+    if (!exists && previous.length) {
+        const byAge = await Promise.all(previous.map(async (file) => ({ file, time: (await stat(file)).mtimeMs })));
+        const latest = byAge.sort((a, b) => b.time - a.time)[0].file;
+        await rename(latest, target);
+    }
+    for (const file of abandoned)
+        await rm(file, { recursive: true, force: true });
+}
+async function checkReplaceable(target, kind) {
+    const entries = await readdir(target).catch((error) => { if (error.code === 'ENOENT')
+        return []; throw error; });
+    if (!entries.length)
+        return;
+    if (kind === 'site' && entries.includes('documents.json') && entries.includes('resource-headers.json'))
+        return;
+    if (kind === 'export' && entries.includes('manifest.json')) {
+        const manifest = JSON.parse(await readFile(path.join(target, 'manifest.json'), 'utf8'));
+        if (manifest.kind === 'shoalrun-content-export' && manifest.schemaVersion === 1)
+            return;
+    }
+    throw new Error(`Output directory ${target} already exists and is not an earlier Shoalrun ${kind === 'site' ? 'build (it has no documents.json and resource-headers.json)' : 'content export'}. The build replaces its output directory, so it stopped instead of deleting it. Choose a new or empty directory`);
+}
+export async function commitArtifacts(target, artifacts, prepare, kind = 'site') {
+    // A leading slash denotes a public route, never an absolute filesystem path.
+    // Check every entry before acquiring a lock or running preparation callbacks.
+    const names = new Set();
+    for (const route of artifacts.keys()) {
+        const relative = route.replace(/^\//, '');
+        if (!relative || /[\\\0:]/.test(relative) || relative.split('/').some(part => !part || part === '.' || part === '..')) {
+            throw new Error(`Unsafe output artifact path: ${route}`);
+        }
+        if (names.has(relative))
+            throw new Error(`Duplicate output artifact path: ${route}`);
+        names.add(relative);
+    }
+    // Aliases of the parent directory must share the same output lock. Refuse a
+    // symlink at the destination itself instead of following or replacing it.
+    target = path.join(canonical(path.dirname(path.resolve(target))), path.basename(target));
+    const checkDestination = async () => {
+        const info = await lstat(target).catch((error) => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (info?.isSymbolicLink())
+            throw new Error(`Output directory must not be a symbolic link: ${target}`);
+    };
+    await checkDestination();
+    const unlock = await lockOutput(target);
+    const staging = `${target}.staging-${process.pid}-${randomUUID()}`;
+    const previous = `${staging}-previous`;
+    try {
+        await recoverOutput(target);
+        await checkDestination();
+        await checkReplaceable(target, kind);
+        await prepare?.();
+        await mkdir(staging, { recursive: false });
+        for (const [route, data] of artifacts) {
+            const file = path.join(staging, route.replace(/^\//, ''));
+            await mkdir(path.dirname(file), { recursive: true });
+            await writeFile(file, data);
+        }
+        await checkDestination();
+        const hadPrevious = await rename(target, previous).then(() => true, (error) => { if (error.code === 'ENOENT')
+            return false; throw error; });
+        try {
+            await rename(staging, target);
+        }
+        catch (error) {
+            if (hadPrevious)
+                await rename(previous, target);
+            throw error;
+        }
+        await rm(previous, { recursive: true, force: true });
+    }
+    finally {
+        try {
+            await rm(staging, { recursive: true, force: true });
+        }
+        finally {
+            await unlock();
+        }
+    }
+}

package/dist/output-location.d.ts

@@ -0,0 +1,3 @@
+export declare const canonical: (file: string) => string;
+export declare const within: (directory: string, file: string) => boolean;
+export declare function checkOutputDirectory(destination: string, projectRoot: string, contentDir: string, inputs: string[]): void;

package/dist/output-location.js

@@ -0,0 +1,30 @@
+import path from 'node:path';
+import { realpathSync } from 'node:fs';
+// Real paths, resolved through the nearest existing parent so paths not yet created compare correctly.
+export const canonical = (file) => {
+    const resolved = path.resolve(file);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        const parent = path.dirname(resolved);
+        return parent === resolved ? resolved : path.join(canonical(parent), path.basename(resolved));
+    }
+};
+export const within = (directory, file) => {
+    const relative = path.relative(directory, file);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+};
+// The build deletes its output directory, so that directory must not hold the project or anything the build reads.
+export function checkOutputDirectory(destination, projectRoot, contentDir, inputs) {
+    const target = canonical(destination);
+    for (const [label, directory] of [['project directory', projectRoot], ['content directory', contentDir]]) {
+        if (within(target, canonical(directory)))
+            throw new Error(`Output directory ${target} is or contains the ${label} ${canonical(directory)}; the build deletes its output, so choose a separate directory such as ${path.join(canonical(projectRoot), 'dist')}`);
+    }
+    if (within(canonical(contentDir), target))
+        throw new Error(`Output directory ${target} is inside the content directory; later builds would read its Markdown as pages`);
+    const input = inputs.map(canonical).find(file => within(target, file));
+    if (input)
+        throw new Error(`Output directory ${target} contains build input ${input}; the build deletes its output, so choose a separate directory`);
+}

package/dist/page-materialization.d.ts

@@ -0,0 +1,78 @@
+import type { ComponentRegistry } from './component-plugins.js';
+import { type ApiEmbedUse } from './api-embeds.js';
+import type { ApiShape, NamedExample } from './api.js';
+import type { CodeSample } from './code-samples.js';
+import type { materializeApiReferences } from './api-publication-plan.js';
+import { type Document, type Variant } from './content.js';
+import type { OperationNavEntry } from './project-navigation.js';
+import type { SnippetDefinition, SnippetUse } from './snippets.js';
+import type { ReaderFiltersConfig } from './reader-filters.js';
+import type { resolveCalloutTypes } from './callouts.js';
+import type { resolveBadgeVariants } from './badges.js';
+type ApiPlan = Awaited<ReturnType<typeof materializeApiReferences>>;
+type SourceBinding = NonNullable<ReturnType<ApiPlan['sourceForVariant']>>;
+export type MaterializedPage = {
+    doc: Document;
+    html: string;
+    markdown: string;
+    sections?: import('./markdown-sections.js').MarkdownSection[];
+    htmlTree: unknown;
+    pageExamples: NamedExample[];
+    pageShapes: ApiShape[];
+    pageCurl?: string;
+    pageSamples?: CodeSample[];
+};
+export declare function materializePages({ variables, frontmatterConfig, publications, docs, linkDocuments, apiPlan, sourceForOperation, snippets, calloutTypes, badgeVariants, componentPlugins, readerFilters, base, publicPath, relatedApiTargets, guidesByApi }: {
+    variables: Record<string, unknown>;
+    frontmatterConfig: unknown;
+    publications: {
+        channels: Record<string, unknown>;
+        versions: Record<string, unknown>;
+    };
+    docs: Map<string, Document>;
+    linkDocuments?: Map<string, Document>;
+    apiPlan: ApiPlan;
+    sourceForOperation: (operationId: string, variant: Variant) => SourceBinding & {
+        sourceOperationId: string;
+    };
+    snippets: Map<string, SnippetDefinition>;
+    calloutTypes: ReturnType<typeof resolveCalloutTypes>;
+    badgeVariants: ReturnType<typeof resolveBadgeVariants>;
+    componentPlugins?: ComponentRegistry;
+    readerFilters?: ReaderFiltersConfig;
+    base: string;
+    publicPath: (route: string) => string;
+    relatedApiTargets: Map<string, Document[]>;
+    guidesByApi: Map<string, Document[]>;
+}): Promise<{
+    apiPublications: Map<string, {
+        apiId: string;
+        variant: Variant;
+        sourceFile: string;
+        endpoint?: string;
+        referenceUrl: string;
+        sourceUrl: string;
+        mediaType: string;
+    }>;
+    focusedContracts: Map<string, {
+        content: string;
+        bytes: number;
+        digest: string;
+    }>;
+    navigationEntries: Map<string, OperationNavEntry[]>;
+    navigationTagOrder: Map<string, Map<string, string[]>>;
+    rendered: MaterializedPage[];
+    snippetUses: SnippetUse[];
+    apiEmbedUses: ApiEmbedUse[];
+    operations: Record<string, {
+        id: string;
+        type: string;
+        channel: string;
+        version: string;
+        language: string;
+        url: string;
+        markdownUrl: string;
+        focusedContractUrl?: string;
+    }[]>;
+}>;
+export {};