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

package/dist/markdown-sections.d.ts

@@ -0,0 +1,15 @@
+export type MarkdownSection = {
+    id: string;
+    title: string;
+    depth: 2;
+    standalone?: true;
+    markdownUrl: string;
+    parentMarkdownUrl: string;
+    parentDigest: string;
+    digest: string;
+    markdownBytes: number;
+    markdownTokens: number;
+    markdownTokenEncoding: string;
+    content: string;
+};
+export declare function markdownSections(tree: any, markdownUrl: string, parent: string, prefix: string, render: (tree: any) => string, standaloneTitles?: string[]): MarkdownSection[];

package/dist/markdown-sections.js

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import { markdownSize } from './markdown-size.js';
+import { link, list, paragraph, renderMarkdown, root, text } from './semantic-markdown.js';
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const pathKey = (item) => `${item.type}:${item.id}`;
+// Only direct page children qualify: hoisting a view from a ReaderSection, tab,
+// representation-only block, or another nested scope would change its meaning.
+const readingPaths = (nodes) => nodes.flatMap(node => node.data?.sectionReadingPath ?? []);
+function missingReadingPath(all, included) {
+    const seen = new Set(readingPaths(included).map(pathKey));
+    const missing = readingPaths(all).filter(item => {
+        const key = pathKey(item);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    if (!missing.length)
+        return [];
+    return [paragraph({ type: 'strong', children: [text('Page reading path')] }, text(' — these links apply to the full page.')),
+        ...['prerequisite', 'next-step'].flatMap(type => {
+            const entries = missing.filter(item => item.type === type);
+            return entries.length ? [paragraph({ type: 'strong', children: [text(type === 'prerequisite' ? 'Read first' : 'Next steps')] }),
+                list(entries.map(item => [paragraph(link(item.url, item.title), text(` — ${item.reason}`), ...(item.status ? [text(` (Status: ${item.status}.)`)] : []))]))] : [];
+        })];
+}
+const textOf = (node) => typeof node.value === 'string' ? node.value : (node.children ?? []).map(textOf).join('');
+// Split the semantic root, never the flattened Markdown: a reader section or tab
+// remains intact even when it contains headings. Nested headings are not resources.
+export function markdownSections(tree, markdownUrl, parent, prefix, render, standaloneTitles = []) {
+    const parentSize = markdownSize(parent);
+    const children = tree.children ?? [];
+    const starts = children.flatMap((node, index) => node.type === 'heading' && node.depth === 2 ? [index] : []);
+    // Check declarations even on short pages: a renamed or ambiguous heading must
+    // never silently retain an author's approval. Titles refer to normalized text.
+    for (const title of standaloneTitles) {
+        if (starts.filter(start => textOf(children[start]).trim() === title).length !== 1) {
+            throw new Error(`${markdownUrl}: standaloneSections title "${title}" must match exactly one top-level level-two heading`);
+        }
+    }
+    if (parentSize.markdownTokens < 2000)
+        return [];
+    const preamble = children.slice(0, starts[0] ?? 0);
+    const used = new Set();
+    return starts.map(start => {
+        const title = textOf(children[start]).trim();
+        const stem = title.normalize('NFKD').toLowerCase().replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80).replace(/-$/, '') || 'section';
+        let id = stem;
+        for (let suffix = 2; used.has(id); suffix++)
+            id = `${stem}-${suffix}`;
+        used.add(id);
+        const end = children.findIndex((node, position) => position > start && node.type === 'heading' && node.depth <= 2);
+        const nodes = [...preamble, ...children.slice(start, end === -1 ? children.length : end)].filter(node => !['definition', 'footnoteDefinition'].includes(node.type));
+        const definitions = children.filter(node => ['definition', 'footnoteDefinition'].includes(node.type));
+        const content = prefix + renderMarkdown(root([paragraph(text('Parent page: '), link(markdownUrl, 'Full Markdown page'))])) + '\n'
+            + render(root([...missingReadingPath(children, nodes), ...nodes, ...definitions]));
+        return { id, title, depth: 2, ...(standaloneTitles.includes(title) ? { standalone: true } : {}), markdownUrl: `${markdownUrl.slice(0, -3)}.sections/${id}.md`, parentMarkdownUrl: markdownUrl,
+            parentDigest: digest(parent), digest: digest(content), ...markdownSize(content), content };
+    }).filter(section => section.markdownTokens <= parentSize.markdownTokens / 2 && section.markdownBytes <= parentSize.markdownBytes / 2);
+}

package/dist/markdown-size.d.ts

@@ -0,0 +1,7 @@
+export declare const markdownTokenEncoding = "cl100k_base";
+export declare const markdownTokens: (value: string) => number;
+export declare const markdownSize: (value: string) => {
+    markdownBytes: number;
+    markdownTokens: number;
+    markdownTokenEncoding: string;
+};

package/dist/markdown-size.js

@@ -0,0 +1,6 @@
+import { getEncoding } from 'js-tiktoken';
+export const markdownTokenEncoding = 'cl100k_base';
+let encoding;
+// Treat special-token spellings in documentation as ordinary text.
+export const markdownTokens = (value) => (encoding ??= getEncoding(markdownTokenEncoding)).encode(value, [], []).length;
+export const markdownSize = (value) => ({ markdownBytes: Buffer.byteLength(value, 'utf8'), markdownTokens: markdownTokens(value), markdownTokenEncoding });

package/dist/mcp-analytics.d.ts

@@ -0,0 +1,38 @@
+import type { McpServer, ServerContext } from '@modelcontextprotocol/server';
+import type { McpClientMetadata } from './mcp-client-metadata.js';
+export type McpAnalyticsEvent = McpClientMetadata & {
+    name: 'mcp_tool_call';
+    tool: string;
+    durationMs: number;
+    isError: boolean;
+    errorCode?: string;
+    pageId?: string;
+    sectionId?: string;
+    buildId: string;
+    publication: {
+        channel: string;
+        version: string;
+        language: string;
+    };
+};
+export type McpAnalyticsContext = {
+    buildId: string;
+    publication: McpAnalyticsEvent['publication'];
+    clientMetadata: boolean;
+    intent: boolean;
+    conversationIds: boolean;
+    metadata(context: ServerContext): McpClientMetadata;
+    client(name: unknown, version?: unknown): McpClientMetadata['client'];
+    resource(id: unknown, section: unknown): Promise<{
+        pageId?: string;
+        sectionId?: string;
+    }>;
+    modelName(value: unknown): string | undefined;
+};
+export type McpAnalyticsAdapter = {
+    capture(event: McpAnalyticsEvent): void | Promise<void>;
+    instrument?(server: McpServer, context: McpAnalyticsContext): boolean | Promise<boolean>;
+    flush?(): void | Promise<void>;
+};
+export declare function attemptAnalytics(operation: () => unknown, milliseconds?: number): Promise<void>;
+export declare function mcpAnalyticsLoader(directory: string, module: string | undefined): () => Promise<McpAnalyticsAdapter | undefined>;

package/dist/mcp-analytics.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+// Analytics has its own small deadline and cannot reject a documentation request.
+export async function attemptAnalytics(operation, milliseconds = 1000) {
+    let timeout;
+    try {
+        await Promise.race([
+            Promise.resolve().then(operation),
+            new Promise((_, reject) => { timeout = setTimeout(() => reject(new Error('timeout')), milliseconds); }),
+        ]);
+    }
+    catch {
+        process.stderr.write('MCP analytics delivery failed or timed out\n');
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export function mcpAnalyticsLoader(directory, module) {
+    let pending;
+    return () => {
+        if (!module)
+            return Promise.resolve(undefined);
+        pending ??= (async () => {
+            const adapter = await import(pathToFileURL(path.join(directory, module)).href);
+            if (typeof adapter.capture !== 'function' || adapter.instrument !== undefined && typeof adapter.instrument !== 'function' || adapter.flush !== undefined && typeof adapter.flush !== 'function')
+                throw new Error('Invalid MCP analytics adapter');
+            return adapter;
+        })().catch(() => {
+            process.stderr.write('MCP analytics adapter could not load\n');
+            return undefined;
+        });
+        return pending;
+    };
+}

package/dist/mcp-artifacts.d.ts

@@ -0,0 +1,2 @@
+import type { ArtifactPage } from './artifact-bundle.js';
+export declare function addMcpArtifacts(artifacts: Map<string, string | Buffer>, config: any, manifest: any, rendered: ArtifactPage[], headers: Record<string, unknown>, analyticsModule?: string): Promise<void>;

package/dist/mcp-artifacts.js

@@ -0,0 +1,78 @@
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { copyFunctionRuntime } from './function-package.js';
+import { fingerprint, mcpRuntimePath, mcpDataPath } from './mcp-integrity.js';
+import { searchIndex } from './content.js';
+import { resolveMcp } from './mcp-config.js';
+export async function addMcpArtifacts(artifacts, config, manifest, rendered, headers, analyticsModule) {
+    const mcp = resolveMcp(config.mcp);
+    if (!mcp)
+        return;
+    const endpoint = `${manifest.basePath}${mcp.path}`;
+    const variant = ['channel', 'version', 'language'].map(key => mcp.publication[key]).join('|');
+    const selected = rendered.filter(page => ['channel', 'version', 'language'].every(key => page.doc.variant[key] === mcp.publication[key]));
+    if (!selected.length || selected.some(page => page.doc.frontmatter.access?.policy !== 'public'))
+        throw new Error('mcp.publication must select nonempty, normally published public documentation');
+    for (const artifact of artifacts.keys()) {
+        const route = artifact.toLowerCase();
+        if ([endpoint, mcpRuntimePath, mcpDataPath].some(reserved => {
+            const value = reserved.toLowerCase();
+            return route === value || route.startsWith(`${value}/`) || value.startsWith(`${route}/`);
+        }))
+            throw new Error(`MCP output route collision: ${artifact}`);
+    }
+    if (manifest.redirects.some((r) => r.from === endpoint || r.markdownFrom === endpoint))
+        throw new Error('MCP endpoint conflicts with a redirect');
+    const docs = manifest.documents.filter((doc) => ['channel', 'version', 'language'].every(key => doc.variant[key] === mcp.publication[key]));
+    const inventory = {};
+    const put = (file, value) => {
+        artifacts.set(`${mcpDataPath}/${file}`, value);
+        inventory[file] = fingerprint(value);
+    };
+    const records = new Map(docs.map((doc) => [doc.markdownUrl, doc]));
+    const index = searchIndex(selected, config);
+    const search = { ...index, documents: index.documents.map(doc => {
+            const record = records.get(doc.markdownUrl);
+            return { ...doc, markdownBytes: record.markdownBytes, markdownTokens: record.markdownTokens, markdownTokenEncoding: record.markdownTokenEncoding, sections: record.sections };
+        }) };
+    if (search.documents.some(doc => doc.variant !== variant))
+        throw new Error('MCP search publication mismatch');
+    put('documents.json', JSON.stringify({ schemaVersion: 1, documents: docs }));
+    put('search-index.json', JSON.stringify(search));
+    for (const doc of docs)
+        for (const resource of [doc, ...doc.sections]) {
+            const content = artifacts.get(resource.markdownUrl);
+            if (content === undefined || fingerprint(content) !== resource.digest)
+                throw new Error(`Missing or inconsistent MCP resource: ${resource.markdownUrl}`);
+            put(resource.markdownUrl.slice(1), content);
+        }
+    if (mcp.analytics) {
+        if (!analyticsModule)
+            throw new Error('Missing MCP analytics module');
+        const temporary = await mkdtemp(path.join(os.tmpdir(), 'shoalrun-mcp-adapter-'));
+        try {
+            await copyFunctionRuntime(path.dirname(analyticsModule), path.basename(analyticsModule), temporary);
+            await writeFile(path.join(temporary, 'package.json'), JSON.stringify({ type: 'module' }));
+            const collect = async (folder) => {
+                for (const entry of await readdir(folder, { withFileTypes: true })) {
+                    const file = path.join(folder, entry.name);
+                    if (entry.isDirectory())
+                        await collect(file);
+                    else
+                        put(`analytics/${path.relative(temporary, file).split(path.sep).join('/')}`, await readFile(file));
+                }
+            };
+            await collect(temporary);
+            mcp.analytics = { ...mcp.analytics, module: `analytics/lib/${path.basename(analyticsModule)}` };
+        }
+        finally {
+            await rm(temporary, { recursive: true, force: true });
+        }
+    }
+    const origin = config.site.origin ? new URL(config.site.origin).origin : undefined;
+    const runtime = { schemaVersion: 1, ...mcp, path: endpoint, dataDirectory: mcpDataPath.slice(1), allowedHosts: [...new Set([...mcp.allowedHosts, ...(origin ? [new URL(origin).hostname] : [])])], allowedOrigins: [...new Set([...mcp.allowedOrigins, ...(origin ? [origin] : [])])], inventory, corpusDigest: fingerprint(JSON.stringify(inventory)), buildId: '' };
+    artifacts.set(mcpRuntimePath, JSON.stringify(runtime));
+    // These are internal runtime files, not browser discovery artifacts.
+    headers[mcpRuntimePath] = { 'X-Robots-Tag': 'noindex' };
+}

package/dist/mcp-client-metadata.d.ts

@@ -0,0 +1,18 @@
+import { type ServerContext } from '@modelcontextprotocol/server';
+export type McpClientMetadata = {
+    client?: {
+        name: string;
+        version?: string;
+        source: 'client_metadata' | 'user_agent' | 'vendor_header' | 'client_marker';
+        verified: false;
+    };
+    model?: {
+        name: string;
+        source: 'client_metadata';
+        verified: false;
+    };
+};
+export declare function normalizeMcpClient(name: unknown, clientVersion?: unknown): McpClientMetadata['client'];
+export declare function safeMcpModelName(value: unknown): string | undefined;
+/** Only bounded labels leave this function. No raw headers, full metadata, or session cache. */
+export declare function mcpClientMetadata(context: ServerContext, legacyClient?: unknown): McpClientMetadata;

package/dist/mcp-client-metadata.js

@@ -0,0 +1,69 @@
+import { CLIENT_INFO_META_KEY } from '@modelcontextprotocol/server';
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+const clientNames = [
+    [/^(?:codex|openai-codex|codex-cli|codex-mcp-client)$/i, 'codex'],
+    [/^(?:claude-code|claude_code|claude code)$/i, 'claude-code'],
+    [/^(?:claude-desktop|claude desktop)$/i, 'claude-desktop'],
+    [/^cursor$/i, 'cursor'], [/^(?:vscode|visual studio code)$/i, 'vscode'],
+    [/^windsurf$/i, 'windsurf'], [/^cline$/i, 'cline'], [/^roo-code$/i, 'roo-code'],
+    [/^gemini-cli$/i, 'gemini-cli'], [/^opencode$/i, 'opencode'],
+];
+const knownClient = (value) => typeof value === 'string' && value.length <= 64 ? clientNames.find(([pattern]) => pattern.test(value))?.[1] : undefined;
+const version = (value) => typeof value === 'string' && /^\d{1,4}(?:\.\d{1,6}){0,3}(?:-(?:alpha|beta|rc|dev|canary)(?:[.-]?\d{1,6})?)?$/.test(value) && value.length <= 32 ? value : undefined;
+export function normalizeMcpClient(name, clientVersion) {
+    const normalized = knownClient(name);
+    return normalized ? { name: normalized, ...(version(clientVersion) ? { version: version(clientVersion) } : {}), source: 'client_metadata', verified: false } : undefined;
+}
+// Deliberately finite: a family prefix is not enough to exclude private labels.
+// Extend this registry when supporting additional public model labels.
+const modelNames = new Set([
+    'gpt-4o', 'gpt-4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'gpt-4.1-nano',
+    'gpt-5', 'gpt-5-mini', 'gpt-5-nano', 'gpt-5-codex', 'gpt-5.1', 'gpt-5.1-codex',
+    'gpt-5.2', 'gpt-5.2-codex', 'gpt-5.3-codex', 'gpt-5.4', 'gpt-6', 'gpt-6.1',
+    'o1', 'o3', 'o3-mini', 'o4-mini',
+    'claude-sonnet-4', 'claude-sonnet-4-5', 'claude-sonnet-4-6',
+    'claude-opus-4', 'claude-opus-4-1', 'claude-opus-4-5', 'claude-opus-4-6', 'claude-haiku-4-5',
+    'gemini-2.0-flash', 'gemini-2.0-flash-lite', 'gemini-2.5-pro', 'gemini-2.5-flash', 'gemini-2.5-flash-lite',
+    'gemini-3-pro', 'gemini-3-flash', 'gemini-3-pro-preview', 'gemini-3-flash-preview',
+    'deepseek-chat', 'deepseek-reasoner', 'deepseek-v3', 'deepseek-v3.1', 'deepseek-v3.2',
+    'deepseek-r1', 'deepseek-v4-flash', 'deepseek-v4-pro', 'deepseek-v4.1-flash',
+    'mistral-large', 'mistral-small', 'codestral', 'grok-3', 'grok-3-mini', 'grok-4',
+    'command-r', 'command-r-plus', 'command-a',
+]);
+export function safeMcpModelName(value) {
+    if (typeof value !== 'string' || value.length > 96)
+        return;
+    const normalized = value.toLowerCase().replace(/^(?:openai|anthropic|google|meta|mistral|xai|cohere|deepseek)\//, '');
+    return modelNames.has(normalized) ? normalized : undefined;
+}
+/** Only bounded labels leave this function. No raw headers, full metadata, or session cache. */
+export function mcpClientMetadata(context, legacyClient) {
+    const result = {};
+    const info = record(record(context.mcpReq.envelope)?.[CLIENT_INFO_META_KEY]) ?? record(legacyClient);
+    const name = knownClient(info?.name);
+    if (name)
+        result.client = { name, ...(version(info?.version) ? { version: version(info?.version) } : {}), source: 'client_metadata', verified: false };
+    const headers = context.http?.req?.headers;
+    if (!result.client && headers) {
+        const vendor = headers.get('x-anthropic-client');
+        if (vendor && vendor.length <= 128 && /^(?:claude-code|claude_code)(?:\/\d[\w.-]*)?$/i.test(vendor))
+            result.client = { name: 'claude-code', source: 'vendor_header', verified: false };
+        const agent = headers.get('user-agent');
+        if (!result.client && agent && agent.length <= 512) {
+            // Recognize product tokens; discard the original header, including any paths or device details.
+            const token = agent.match(/(?:^|[\s;(])((?:codex|codex-cli|claude-code|cursor|vscode|windsurf|cline|roo-code|gemini-cli|opencode))\/\d[\w.-]*(?=$|[\s;)])/i)?.[1];
+            const normalized = knownClient(token);
+            if (normalized)
+                result.client = { name: normalized, source: 'user_agent', verified: false };
+        }
+    }
+    // Presence identifies a claimed client only. Never retain or hash its session ID.
+    const openCodeSession = context.mcpReq._meta?.['ai.opencode/sessionID'];
+    if (!result.client && typeof openCodeSession === 'string' && /^ses_[a-zA-Z0-9]{1,128}$/.test(openCodeSession))
+        result.client = { name: 'opencode', source: 'client_marker', verified: false };
+    const turn = record(context.mcpReq._meta?.['x-codex-turn-metadata']);
+    const model = safeMcpModelName(turn?.model);
+    if (model)
+        result.model = { name: model, source: 'client_metadata', verified: false };
+    return result;
+}

package/dist/mcp-config.d.ts

@@ -0,0 +1,23 @@
+export type McpConfig = {
+    enabled: true;
+    access: 'public';
+    path: string;
+    publication: {
+        channel: string;
+        version: string;
+        language: string;
+    };
+    allowedHosts: string[];
+    allowedOrigins: string[];
+    analytics?: {
+        module: string;
+        clientMetadata?: boolean;
+        intent?: boolean;
+        conversationIds?: boolean;
+        consent?: {
+            header: string;
+            value: string;
+        };
+    };
+};
+export declare function resolveMcp(value: unknown): McpConfig | undefined;

package/dist/mcp-config.js

@@ -0,0 +1,56 @@
+import { configMappingAt } from './compiler-config.js';
+export function resolveMcp(value) {
+    if (value === undefined || value === false)
+        return;
+    const config = configMappingAt(value, 'mcp');
+    if (Object.keys(config).some(key => !['enabled', 'access', 'path', 'publication', 'allowedHosts', 'allowedOrigins', 'analytics'].includes(key)))
+        throw new Error('Unknown mcp setting');
+    if (typeof config.enabled !== 'boolean')
+        throw new Error('mcp.enabled must be a boolean');
+    if (!config.enabled)
+        return;
+    if (config.access !== 'public')
+        throw new Error('mcp.access must explicitly be public');
+    const route = config.path ?? '/mcp';
+    if (typeof route !== 'string' || !/^\/[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)*$/.test(route) || route.startsWith('/__shoalrun'))
+        throw new Error('mcp.path must be a non-reserved absolute path without a trailing slash');
+    const publication = configMappingAt(config.publication, 'mcp.publication');
+    if (Object.keys(publication).some(key => !['channel', 'version', 'language'].includes(key)) || ['channel', 'version', 'language'].some(key => typeof publication[key] !== 'string' || !/^[a-zA-Z0-9._-]{1,128}$/.test(publication[key])))
+        throw new Error('mcp.publication needs channel, version, and language');
+    const strings = (key) => {
+        const values = config[key] ?? [];
+        if (!Array.isArray(values) || values.length > 32 || values.some(v => typeof v !== 'string' || !v || v.length > 253))
+            throw new Error(`mcp.${key} must be an array of explicit hostnames or origins`);
+        return values;
+    };
+    const allowedHosts = strings('allowedHosts');
+    if (allowedHosts.some(host => !/^(?:[a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+$/.test(host)))
+        throw new Error('mcp.allowedHosts accepts hostnames without wildcards, schemes, or ports');
+    const allowedOrigins = strings('allowedOrigins');
+    if (allowedOrigins.some(origin => { try {
+        const url = new URL(origin);
+        return url.origin !== origin || !['https:', 'http:'].includes(url.protocol);
+    }
+    catch {
+        return true;
+    } }))
+        throw new Error('mcp.allowedOrigins accepts exact HTTP(S) origins');
+    let analytics;
+    if (config.analytics !== undefined && config.analytics !== false) {
+        const value = configMappingAt(config.analytics, 'mcp.analytics');
+        if (Object.keys(value).some(key => !['module', 'clientMetadata', 'intent', 'conversationIds', 'consent'].includes(key)) || typeof value.module !== 'string' || !value.module.trim() || !/\.m?js$/i.test(value.module) || /^[a-z][a-z0-9+.-]*:/i.test(value.module))
+            throw new Error('mcp.analytics.module must name a local .js or .mjs server module');
+        for (const key of ['clientMetadata', 'intent', 'conversationIds'])
+            if (value[key] !== undefined && typeof value[key] !== 'boolean')
+                throw new Error(`mcp.analytics.${key} must be a boolean`);
+        let consent;
+        if (value.consent !== undefined && value.consent !== false) {
+            const policy = configMappingAt(value.consent, 'mcp.analytics.consent');
+            if (Object.keys(policy).some(key => !['header', 'value'].includes(key)) || typeof policy.header !== 'string' || !/^x-[a-z0-9-]{1,60}$/.test(policy.header) || /^(x-forwarded-|x-vercel-|x-mcp-)/.test(policy.header) || typeof policy.value !== 'string' || !/^[a-zA-Z0-9._-]{1,64}$/.test(policy.value))
+                throw new Error('mcp.analytics.consent needs a custom lowercase x- header and a short policy value');
+            consent = { header: policy.header, value: policy.value };
+        }
+        analytics = { module: value.module, ...(consent ? { consent } : {}), ...(value.clientMetadata === true ? { clientMetadata: true } : {}), ...(value.intent === true ? { intent: true } : {}), ...(value.conversationIds === true ? { conversationIds: true } : {}) };
+    }
+    return { ...(analytics ? { analytics } : {}), enabled: true, access: 'public', path: route, publication: publication, allowedHosts: allowedHosts.map(host => host.toLowerCase()), allowedOrigins };
+}

package/dist/mcp-http.d.ts

@@ -0,0 +1,19 @@
+import { type McpConfig } from './mcp-config.js';
+export declare const mcpRequestLimit = 65536;
+export type McpRuntime = McpConfig & {
+    schemaVersion: 1;
+    dataDirectory: string;
+    inventory: Record<string, string>;
+    corpusDigest: string;
+    buildId: string;
+};
+export declare function loadMcpRuntime(directory: string): Promise<{
+    runtime: McpRuntime;
+    directory: string;
+} | undefined>;
+export declare function createMcpHttpHandler(input: {
+    runtime: McpRuntime;
+    directory: string;
+}): (request: Request, options?: {
+    local?: boolean;
+}) => Promise<Response>;

package/dist/mcp-http.js

@@ -0,0 +1,157 @@
+import { mcpClientMetadata, safeMcpModelName, normalizeMcpClient } from './mcp-client-metadata.js';
+import { attemptAnalytics, mcpAnalyticsLoader } from './mcp-analytics.js';
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fingerprint, mcpDataPath, mcpRuntimePath } from './mcp-integrity.js';
+import { resolveMcp } from './mcp-config.js';
+export const mcpRequestLimit = 65_536;
+const hex = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const fail = (status, message) => new Response(JSON.stringify({ error: message }), { status, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', ...(status === 429 ? { 'Retry-After': '1' } : {}) } });
+export async function loadMcpRuntime(directory) {
+    let raw;
+    try {
+        raw = await readFile(path.join(directory, mcpRuntimePath), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const runtime = JSON.parse(raw);
+    if (runtime.schemaVersion !== 1 || runtime.access !== 'public' || runtime.enabled !== true || runtime.dataDirectory !== mcpDataPath.slice(1) || !hex(runtime.buildId) || !hex(runtime.corpusDigest) || !runtime.inventory || Array.isArray(runtime.inventory) || fingerprint(JSON.stringify(runtime.inventory)) !== runtime.corpusDigest || !runtime.publication || ['channel', 'version', 'language'].some(key => typeof runtime.publication[key] !== 'string') || !Array.isArray(runtime.allowedHosts) || !Array.isArray(runtime.allowedOrigins) || typeof runtime.path !== 'string' || !/^\/[a-zA-Z0-9_/-]+$/.test(runtime.path))
+        throw new Error('Invalid MCP runtime metadata; rebuild the public site');
+    if (runtime.analytics?.consent)
+        resolveMcp({ enabled: true, access: 'public', publication: runtime.publication, analytics: { ...runtime.analytics, module: './adapter.mjs' } });
+    const build = JSON.parse(await readFile(path.join(directory, 'build-info.json'), 'utf8'));
+    if (build.buildId !== runtime.buildId)
+        throw new Error('MCP corpus and public site build identities differ');
+    const siteRoot = await realpath(directory);
+    const root = await realpath(path.join(directory, runtime.dataDirectory));
+    if (!root.startsWith(`${siteRoot}${path.sep}`))
+        throw new Error('MCP corpus escapes the built site');
+    for (const [file, digest] of Object.entries(runtime.inventory)) {
+        if (!file || file.startsWith('/') || file.includes('\\') || file.split('/').some(part => !part || part === '.' || part === '..') || !hex(digest))
+            throw new Error('Invalid MCP inventory path');
+        const resolved = await realpath(path.join(root, file));
+        if (!resolved.startsWith(`${root}${path.sep}`) || fingerprint(await readFile(resolved)) !== digest)
+            throw new Error(`MCP corpus resource mismatch: ${file}`);
+    }
+    if (runtime.analytics && (typeof runtime.analytics.module !== 'string' || !runtime.analytics.module.startsWith('analytics/lib/') || !runtime.inventory[runtime.analytics.module] || runtime.analytics.clientMetadata !== undefined && typeof runtime.analytics.clientMetadata !== 'boolean' || ['intent', 'conversationIds'].some(key => runtime.analytics[key] !== undefined && typeof runtime.analytics[key] !== 'boolean')))
+        throw new Error('Invalid MCP analytics module inventory');
+    if (!runtime.inventory['documents.json'] || !runtime.inventory['search-index.json'])
+        throw new Error('MCP corpus is missing its indexes');
+    return { runtime, directory: root };
+}
+export function createMcpHttpHandler(input) {
+    let active = 0;
+    let publicDocuments;
+    const resource = async (id, section) => {
+        if (typeof id !== 'string')
+            return {};
+        publicDocuments ??= readFile(path.join(input.directory, 'documents.json'), 'utf8').then(text => JSON.parse(text).documents);
+        const page = (await publicDocuments).find(page => page.id === id);
+        return page ? { pageId: page.id, ...(typeof section === 'string' && page.sections?.some(item => item.id === section) ? { sectionId: section } : {}) } : {};
+    };
+    const loadAnalytics = mcpAnalyticsLoader(input.directory, input.runtime.analytics?.module);
+    return async (request, options = {}) => {
+        const { runtime } = input;
+        const url = new URL(request.url);
+        const host = url.hostname.toLowerCase();
+        const loopback = options.local === true && ['localhost', '127.0.0.1', '[::1]'].includes(host);
+        if (!loopback && !runtime.allowedHosts.includes(host))
+            return fail(403, 'MCP Host is not allowed');
+        const origin = request.headers.get('origin');
+        if (origin && !(runtime.allowedOrigins.includes(origin) || loopback && origin === url.origin))
+            return fail(403, 'MCP Origin is not allowed');
+        const cors = origin ? { 'Access-Control-Allow-Origin': origin, Vary: 'Origin', 'Access-Control-Expose-Headers': 'MCP-Protocol-Version, Mcp-Session-Id' } : {};
+        if (url.pathname !== runtime.path)
+            return fail(404, 'Unknown MCP endpoint');
+        if (request.method === 'OPTIONS')
+            return new Response(null, { status: 204, headers: { ...cors, 'Access-Control-Allow-Methods': 'POST, OPTIONS', 'Access-Control-Allow-Headers': ['Content-Type', 'Accept', 'MCP-Protocol-Version', 'MCP-Session-Id', ...(runtime.analytics?.consent ? [runtime.analytics.consent.header] : [])].join(', ') } });
+        if (request.method !== 'POST')
+            return new Response(null, { status: 405, headers: { ...cors, Allow: 'POST, OPTIONS' } });
+        if (active >= 8)
+            return fail(429, 'MCP request capacity exceeded');
+        active++;
+        let analytics;
+        let nativeCapture = false;
+        let server;
+        const controller = new AbortController();
+        const abort = () => controller.abort(request.signal.reason);
+        request.signal.addEventListener('abort', abort, { once: true });
+        if (request.signal.aborted)
+            abort();
+        const timeout = setTimeout(() => controller.abort(new Error('MCP request deadline exceeded')), 15_000);
+        let cleaned = false;
+        const cleanup = async () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            clearTimeout(timeout);
+            request.signal.removeEventListener('abort', abort);
+            active--;
+            await server?.close().catch(() => { });
+            if (analytics?.flush)
+                await attemptAnalytics(() => analytics.flush());
+        };
+        controller.signal.addEventListener('abort', () => { void cleanup(); }, { once: true });
+        try {
+            const [{ WebStandardStreamableHTTPServerTransport }, { createDocsMcpServer }] = await Promise.all([import('@modelcontextprotocol/server'), import('./docs-mcp.js')]);
+            const consent = runtime.analytics?.consent;
+            const permitted = !consent || request.headers.get(consent.header) === consent.value;
+            if (permitted)
+                await attemptAnalytics(async () => { analytics = await loadAnalytics(); });
+            server = createDocsMcpServer(input.directory, runtime.publication, analytics ? { clientMetadata: runtime.analytics?.clientMetadata === true, buildId: runtime.buildId, capture: event => nativeCapture ? undefined : analytics.capture(event) } : undefined, !!consent && !permitted);
+            if (analytics?.instrument)
+                await attemptAnalytics(async () => {
+                    nativeCapture = await analytics.instrument(server, {
+                        buildId: runtime.buildId, publication: runtime.publication,
+                        clientMetadata: runtime.analytics?.clientMetadata === true,
+                        intent: runtime.analytics?.intent === true, conversationIds: runtime.analytics?.conversationIds === true,
+                        client: normalizeMcpClient, resource, modelName: safeMcpModelName,
+                        metadata: context => runtime.analytics?.clientMetadata ? mcpClientMetadata(context, server.server.getClientVersion()) : {},
+                    }) === true;
+                });
+            const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true, maxRequestBodySize: mcpRequestLimit });
+            await server.connect(transport);
+            const work = transport.handleRequest(new Request(request, { signal: controller.signal }));
+            const aborted = new Promise((_, reject) => {
+                if (controller.signal.aborted)
+                    reject(controller.signal.reason);
+                else
+                    controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true });
+            });
+            const response = await Promise.race([work, aborted]);
+            const headers = new Headers(response.headers);
+            headers.set('Cache-Control', 'no-store');
+            for (const [name, value] of Object.entries(cors))
+                headers.set(name, value);
+            // JSON responses are finite; close the protocol only after the body has been consumed.
+            if (!response.body) {
+                await cleanup();
+                return new Response(null, { status: response.status, headers });
+            }
+            const reader = response.body.getReader();
+            return new Response(new ReadableStream({
+                async pull(stream) { try {
+                    const next = await reader.read();
+                    if (next.done) {
+                        await cleanup();
+                        stream.close();
+                    }
+                    else
+                        stream.enqueue(next.value);
+                }
+                catch (error) {
+                    stream.error(error);
+                    await cleanup();
+                } },
+                async cancel(reason) { controller.abort(reason); await reader.cancel(reason).catch(() => { }); await cleanup(); },
+            }), { status: response.status, headers });
+        }
+        catch {
+            await cleanup();
+            return fail(controller.signal.aborted ? 503 : 400, controller.signal.aborted ? 'MCP request cancelled or timed out' : 'Invalid MCP request');
+        }
+    };
+}

package/dist/mcp-integrity.d.ts

@@ -0,0 +1,3 @@
+export declare const mcpRuntimePath = "/mcp-runtime.json";
+export declare const mcpDataPath = "/__shoalrun/mcp-data";
+export declare const fingerprint: (value: string | Buffer) => string;

package/dist/mcp-integrity.js

@@ -0,0 +1,4 @@
+import { createHash } from 'node:crypto';
+export const mcpRuntimePath = '/mcp-runtime.json';
+export const mcpDataPath = '/__shoalrun/mcp-data';
+export const fingerprint = (value) => createHash('sha256').update(value).digest('hex');

package/dist/mcp-node.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function bridgeMcp(request: IncomingMessage, response: ServerResponse, handler: (request: Request, options: {
+    local: boolean;
+}) => Promise<Response>): Promise<void>;