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

package/dist/structured-model-output.d.ts

@@ -0,0 +1,6 @@
+import type { ChatResult } from './chat.js';
+import { z } from 'zod';
+export declare function requireCompleteOutput(reply: ChatResult): void;
+export declare function parseStructuredOutput<T extends z.ZodType>(reply: ChatResult, schema: T, options?: {
+    allowJsonFence?: boolean;
+}): z.output<T>;

package/dist/structured-model-output.js

@@ -0,0 +1,21 @@
+export function requireCompleteOutput(reply) {
+    if (['length', 'max_tokens', 'max_output_tokens'].includes(reply.finishReason?.toLowerCase() ?? '')) {
+        throw new Error(`Model output was truncated (${reply.finishReason}); no candidate or action was accepted. Increase the output allowance or reduce the task.`);
+    }
+}
+export function parseStructuredOutput(reply, schema, options = {}) {
+    requireCompleteOutput(reply);
+    let value;
+    const text = reply.text.trim();
+    const fenced = options.allowJsonFence ? /^```(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n```$/.exec(text) : undefined;
+    try {
+        value = JSON.parse(fenced ? fenced[1] : text);
+    }
+    catch {
+        throw new Error('Invalid structured model response: expected JSON only');
+    }
+    const parsed = schema.safeParse(value);
+    if (!parsed.success)
+        throw new Error(`Invalid structured model response: ${parsed.error.issues.slice(0, 5).map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; ')}`);
+    return parsed.data;
+}

package/dist/subject-deprecation.d.ts

@@ -0,0 +1,21 @@
+import type { Document } from './content-source.js';
+export type SubjectDeprecation = {
+    deprecatedOn?: string;
+    sunsetOn?: string;
+    replacement?: string;
+    migration?: string;
+};
+type Target = {
+    id: string;
+    title: string;
+    url: string;
+    markdownUrl: string;
+};
+export type ResolvedSubjectDeprecation = Omit<SubjectDeprecation, 'replacement' | 'migration'> & {
+    replacement?: Target;
+    migration?: Target;
+};
+export declare function validateSubjectDeprecation(value: unknown, file: string): asserts value is SubjectDeprecation | undefined;
+export declare function resolveSubjectDeprecation(doc: Document, docs: Map<string, Document>): ResolvedSubjectDeprecation | undefined;
+export declare function subjectDeprecationNotice(value: ResolvedSubjectDeprecation | undefined, format: 'html' | 'markdown'): any;
+export {};

package/dist/subject-deprecation.js

@@ -0,0 +1,57 @@
+import { link, paragraph, root, text } from './semantic-markdown.js';
+export function validateSubjectDeprecation(value, file) {
+    if (value === undefined)
+        return;
+    const fail = (message) => { throw new Error(`${file}: subjectDeprecation ${message}`); };
+    if (!value || typeof value !== 'object' || Array.isArray(value) || !Object.keys(value).length)
+        fail('must be a nonempty mapping');
+    for (const [key, item] of Object.entries(value)) {
+        if (!['deprecatedOn', 'sunsetOn', 'replacement', 'migration'].includes(key))
+            fail(`has unknown field ${key}`);
+        if (typeof item !== 'string' || !item.trim() || item !== item.trim())
+            fail(`${key} must be nonempty, trimmed text`);
+        if (key === 'deprecatedOn' || key === 'sunsetOn') {
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(item) || Number.isNaN(Date.parse(`${item}T00:00:00Z`)) || new Date(`${item}T00:00:00Z`).toISOString().slice(0, 10) !== item)
+                fail(`${key} must be a real YYYY-MM-DD calendar date`);
+        }
+    }
+    const dates = value;
+    if (dates.deprecatedOn && dates.sunsetOn && dates.sunsetOn < dates.deprecatedOn)
+        fail('sunsetOn must not precede deprecatedOn');
+}
+// Called after API materialization so authoritative OpenAPI deprecation is available.
+export function resolveSubjectDeprecation(doc, docs) {
+    const value = doc.frontmatter.subjectDeprecation;
+    if (!value)
+        return;
+    if (doc.frontmatter.subjectLifecycle !== 'deprecated')
+        throw new Error(`${doc.file}: subjectDeprecation requires subjectLifecycle: deprecated (authored or inferred from OpenAPI)`);
+    const result = {};
+    for (const key of ['deprecatedOn', 'sunsetOn'])
+        if (value[key])
+            result[key] = value[key];
+    for (const key of ['replacement', 'migration']) {
+        const id = value[key];
+        if (!id)
+            continue;
+        const target = docs.get(`${id}|${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`);
+        if (id === doc.frontmatter.id || !target || target.frontmatter.access?.policy !== 'public')
+            throw new Error(`${doc.file}: subjectDeprecation.${key} must name another public document in the same publication: ${id}`);
+        result[key] = { id, title: target.frontmatter.title, url: target.route, markdownUrl: target.markdownRoute };
+    }
+    return result;
+}
+export function subjectDeprecationNotice(value, format) {
+    if (!value)
+        return root([]);
+    return root([{ type: 'blockquote', children: [
+                paragraph({ type: 'strong', children: [text('Subject deprecation')] }, text(': The documented API or feature is deprecated.')),
+                ...(value.deprecatedOn ? [paragraph(text(`Deprecation date: ${value.deprecatedOn}.`))] : []),
+                ...(value.sunsetOn ? [paragraph(text(`Sunset date: ${value.sunsetOn}.`))] : []),
+                ...['replacement', 'migration'].flatMap(key => {
+                    const target = value[key];
+                    return target ? [paragraph(text(key === 'replacement' ? 'Replacement: ' : 'Migration guide: '), { ...link(format === 'html' ? target.url : target.markdownUrl, target.title), exportDocumentId: target.id }, text('.'))] : [];
+                }),
+                paragraph(text('These details describe the documented subject, not the availability of this documentation page.'))
+            ] }]);
+}

package/dist/surface-text.d.ts

@@ -0,0 +1,4 @@
+export type TextSurface = 'card' | 'pageHeader' | 'search' | 'htmlDescription' | 'socialCard';
+export declare function validateTextSurfaces(config: unknown): void;
+export declare function validatePageText(value: unknown, file: string): void;
+export declare function surfaceText(frontmatter: Record<string, unknown>, surface: TextSurface, config?: any): string | undefined;

package/dist/surface-text.js

@@ -0,0 +1,42 @@
+const surfaces = new Set(['card', 'pageHeader', 'search', 'htmlDescription', 'socialCard']);
+const defaults = {
+    card: ['summary'], pageHeader: ['summary'], search: ['summary'], htmlDescription: ['summary']
+};
+const fieldPath = /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*$/;
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+export function validateTextSurfaces(config) {
+    if (config === undefined)
+        return;
+    if (!object(config))
+        throw new Error('outputs.text must be a mapping');
+    for (const [surface, fields] of Object.entries(config)) {
+        if (!surfaces.has(surface))
+            throw new Error(`Unknown text surface ${surface}`);
+        if (!Array.isArray(fields) || fields.some(field => typeof field !== 'string' || !fieldPath.test(field) || field.split('.').some(part => ['__proto__', 'prototype', 'constructor'].includes(part))))
+            throw new Error(`outputs.text.${surface} must list frontmatter field paths`);
+    }
+}
+export function validatePageText(value, file) {
+    if (value === undefined)
+        return;
+    if (!object(value))
+        throw new Error(`${file}: displayText must be a mapping`);
+    for (const [surface, text] of Object.entries(value)) {
+        if (!surfaces.has(surface))
+            throw new Error(`${file}: unknown displayText surface ${surface}`);
+        if (typeof text !== 'string' || !text.trim())
+            throw new Error(`${file}: displayText.${surface} must be nonempty text`);
+    }
+}
+export function surfaceText(frontmatter, surface, config = {}) {
+    const override = frontmatter.displayText?.[surface];
+    if (override !== undefined)
+        return override;
+    const fields = config.outputs?.text?.[surface] ?? defaults[surface] ?? [];
+    for (const field of fields) {
+        const value = field.split('.').reduce((at, part) => object(at) ? at[part] : undefined, frontmatter);
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return undefined;
+}

package/dist/taxonomy.d.ts

@@ -0,0 +1,14 @@
+type Field = 'area' | 'subarea';
+export type Taxonomy = {
+    required: Field[];
+    requireExplicit: Field[];
+    multiple: Field[];
+    areas: Record<string, {
+        label: string;
+        subareas: Record<string, string>;
+    }>;
+};
+export declare function resolveTaxonomy(value: unknown): Taxonomy | undefined;
+export declare function validateTaxonomy(page: Record<string, any>, taxonomy: Taxonomy | undefined, file: string, source?: Record<string, unknown>): void;
+export declare function taxonomySchema(taxonomy: Taxonomy, properties: Record<string, any>, required: string[], inherited: Record<string, any>): Record<string, any>;
+export {};

package/dist/taxonomy.js

@@ -0,0 +1,88 @@
+const mapping = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const identifier = /^[a-z][a-z0-9-]*$/;
+export function resolveTaxonomy(value) {
+    if (value === undefined || value === false)
+        return;
+    if (!mapping(value))
+        throw new Error('frontmatter.taxonomy must be a mapping');
+    for (const key of Object.keys(value))
+        if (!['required', 'requireExplicit', 'multiple', 'areas'].includes(key))
+            throw new Error(`Unknown frontmatter.taxonomy setting ${key}`);
+    const fields = (name) => {
+        const list = value[name] ?? [];
+        if (!Array.isArray(list) || list.some(field => !['area', 'subarea'].includes(field)) || new Set(list).size !== list.length)
+            throw new Error(`frontmatter.taxonomy.${name} must be a unique list of area and subarea`);
+        return list;
+    };
+    const required = fields('required'), requireExplicit = fields('requireExplicit'), multiple = fields('multiple');
+    if (!mapping(value.areas) || !Object.keys(value.areas).length)
+        throw new Error('frontmatter.taxonomy.areas must be a nonempty mapping');
+    const areas = {};
+    const seen = new Set();
+    for (const [id, area] of Object.entries(value.areas)) {
+        if (!identifier.test(id) || !mapping(area) || Object.keys(area).some(key => !['label', 'subareas'].includes(key)) || typeof area.label !== 'string' || !area.label.trim())
+            throw new Error(`frontmatter.taxonomy.areas.${id} needs a valid ID and readable label`);
+        if (area.subareas !== undefined && !mapping(area.subareas))
+            throw new Error(`frontmatter.taxonomy.areas.${id}.subareas must be a mapping`);
+        const subareas = {};
+        for (const [subarea, label] of Object.entries(area.subareas ?? {})) {
+            if (!identifier.test(subarea) || typeof label !== 'string' || !label.trim())
+                throw new Error(`Invalid taxonomy subarea ${id}.${subarea}`);
+            if (seen.has(subarea))
+                throw new Error(`Taxonomy subarea ${subarea} must belong to exactly one area`);
+            seen.add(subarea);
+            subareas[subarea] = label;
+        }
+        areas[id] = { label: area.label, subareas };
+    }
+    return { required, requireExplicit, multiple, areas };
+}
+export function validateTaxonomy(page, taxonomy, file, source) {
+    if (!taxonomy)
+        return;
+    for (const field of new Set([...taxonomy.required, ...taxonomy.requireExplicit]))
+        if (page[field] === undefined)
+            throw new Error(`${file}: taxonomy requires ${field}`);
+    if (source)
+        for (const field of taxonomy.requireExplicit)
+            if (source[field] === undefined)
+                throw new Error(`${file}: taxonomy requires explicit ${field} on authored pages`);
+    const choices = (field) => {
+        const value = page[field];
+        if (value === undefined)
+            return [];
+        if (Array.isArray(value)) {
+            if (!taxonomy.multiple.includes(field))
+                throw new Error(`${file}: taxonomy allows only one ${field}`);
+            if (!value.length || value.some(item => typeof item !== 'string' || !item.trim()) || new Set(value).size !== value.length)
+                throw new Error(`${file}: taxonomy ${field} must be a nonempty list of unique IDs`);
+            return value;
+        }
+        if (typeof value !== 'string' || !value.trim())
+            throw new Error(`${file}: taxonomy ${field} must be a category ID`);
+        return [value];
+    };
+    const areas = choices('area'), subareas = choices('subarea');
+    for (const area of areas)
+        if (!Object.hasOwn(taxonomy.areas, area))
+            throw new Error(`${file}: unknown taxonomy area ${area}`);
+    if (subareas.length && !areas.length)
+        throw new Error(`${file}: taxonomy subarea requires area`);
+    for (const subarea of subareas)
+        if (!areas.some(area => Object.hasOwn(taxonomy.areas[area].subareas, subarea)))
+            throw new Error(`${file}: taxonomy subarea ${subarea} does not belong to area ${areas.join(', ')}`);
+}
+export function taxonomySchema(taxonomy, properties, required, inherited) {
+    const values = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
+    const shape = (field, ids) => { const scalar = ids.length ? { type: 'string', enum: ids } : false; return taxonomy.multiple.includes(field) ? { oneOf: [scalar, { type: 'array', minItems: 1, uniqueItems: true, items: scalar }] } : scalar; };
+    const membership = (field, id) => taxonomy.multiple.includes(field) ? { anyOf: [{ const: id }, { type: 'array', contains: { const: id } }] } : { const: id };
+    const effective = (field, id) => ({ anyOf: [{ properties: { [field]: membership(field, id) }, required: [field] }, ...(values(inherited[field]).includes(id) ? [{ not: { required: [field] } }] : [])] });
+    properties.area = { description: properties.area.description, ...shape('area', Object.keys(taxonomy.areas)) };
+    const subareas = Object.entries(taxonomy.areas).flatMap(([area, definition]) => Object.keys(definition.subareas).map(id => ({ id, area })));
+    const subareaShape = shape('subarea', subareas.map(item => item.id));
+    properties.subarea = subareaShape === false ? false : { description: properties.subarea.description, ...subareaShape };
+    for (const field of new Set([...taxonomy.required, ...taxonomy.requireExplicit]))
+        if (taxonomy.requireExplicit.includes(field) || inherited[field] === undefined)
+            required.push(field);
+    return { allOf: subareas.map(({ id, area }) => ({ if: effective('subarea', id), then: effective('area', area) })), ...(inherited.area === undefined ? { dependentRequired: { subarea: ['area'] } } : {}) };
+}

package/dist/turnstile.d.ts

@@ -0,0 +1,21 @@
+export type TurnstileOptions = {
+    secret: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+};
+export declare const turnstileVerifyUrl = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+export declare function turnstileVerifier(options: TurnstileOptions): (input: {
+    token?: string;
+    ip?: string;
+}) => Promise<boolean>;
+export type SessionOptions = {
+    secret: string;
+    maxAgeSeconds?: number;
+    now?: () => number;
+};
+export type Session = {
+    name: string;
+    valid(cookieHeader: string | null, caller: string): boolean;
+    header(caller: string, secure: boolean): string;
+};
+export declare function createSession(options: SessionOptions): Session;

package/dist/turnstile.js

@@ -0,0 +1,52 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export const turnstileVerifyUrl = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+export function turnstileVerifier(options) {
+    if (!options.secret)
+        throw new Error('Turnstile needs a secret key');
+    const send = options.fetch ?? fetch;
+    return async ({ token, ip }) => {
+        // Tokens are short. A missing or oversized one is refused without asking Cloudflare.
+        if (typeof token !== 'string' || !token || token.length > 2048)
+            return false;
+        try {
+            const form = new URLSearchParams({ secret: options.secret, response: token });
+            if (ip && ip !== 'unknown')
+                form.set('remoteip', ip);
+            const response = await send(turnstileVerifyUrl, { method: 'POST', body: form, signal: AbortSignal.timeout(options.timeoutMs ?? 3000) });
+            if (!response.ok)
+                return false;
+            const body = await response.json();
+            return body?.success === true;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+export function createSession(options) {
+    if (!options.secret)
+        throw new Error('A session needs a secret');
+    const now = options.now ?? Date.now;
+    const maxAge = options.maxAgeSeconds ?? 900;
+    const name = 'sr_ask';
+    // A separate key, so the cookie signature is never the Turnstile secret itself.
+    const key = createHmac('sha256', options.secret).update('shoalrun-ask-session').digest();
+    const sign = (expires, caller) => createHmac('sha256', key).update(`${expires}.${caller}`).digest('base64url');
+    return {
+        name,
+        valid(cookieHeader, caller) {
+            const value = cookieHeader?.split(';').map(part => part.trim()).find(part => part.startsWith(`${name}=`))?.slice(name.length + 1);
+            if (!value)
+                return false;
+            const [expires, signature, extra] = value.split('.');
+            if (extra !== undefined || !expires || !signature || !/^\d{1,13}$/.test(expires) || Number(expires) * 1000 < now())
+                return false;
+            const expected = sign(expires, caller);
+            return signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+        },
+        header(caller, secure) {
+            const expires = String(Math.floor(now() / 1000) + maxAge);
+            return `${name}=${expires}.${sign(expires, caller)}; Max-Age=${maxAge}; Path=/__shoalrun/ask; HttpOnly; SameSite=Strict${secure ? '; Secure' : ''}`;
+        }
+    };
+}

package/dist/vale.d.ts

@@ -0,0 +1,28 @@
+export type ValeFinding = {
+    rule: string;
+    severity: string;
+    message: string;
+    line?: number;
+    span?: [number, number];
+    match?: string;
+};
+export type ValeResult = {
+    status: 'ok' | 'error' | 'unavailable';
+    findings: ValeFinding[];
+    error?: string;
+};
+export declare function parseValeAlerts(value: unknown): ValeFinding[];
+export type ValeOptions = {
+    directory: string;
+    files: string[];
+    config?: string;
+    command?: string[];
+    signal?: AbortSignal;
+};
+export declare function runVale(options: ValeOptions): Promise<ValeResult>;
+export declare function createValeRunner(options: {
+    directory: string;
+    config?: string;
+    command?: string[];
+    signal?: AbortSignal;
+}): (content: string) => Promise<ValeResult>;

package/dist/vale.js

@@ -0,0 +1,103 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+const stringField = (value) => typeof value === 'string' ? value : '';
+// Vale's JSON is a map of file path to alerts. Any other shape yields no findings, so a version change cannot crash a build.
+export function parseValeAlerts(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    const findings = [];
+    for (const alerts of Object.values(value)) {
+        if (!Array.isArray(alerts))
+            continue;
+        for (const alert of alerts) {
+            if (!alert || typeof alert !== 'object' || Array.isArray(alert))
+                continue;
+            const item = alert;
+            const severity = stringField(item.Severity).toLowerCase() || 'error';
+            const span = Array.isArray(item.Span) && item.Span.length === 2 && item.Span.every(part => typeof part === 'number') ? [item.Span[0], item.Span[1]] : undefined;
+            findings.push({
+                rule: stringField(item.Check) || 'unknown',
+                severity,
+                message: stringField(item.Message),
+                ...(typeof item.Line === 'number' ? { line: item.Line } : {}),
+                ...(span ? { span } : {}),
+                ...(item.Match !== undefined ? { match: stringField(item.Match) } : {})
+            });
+        }
+    }
+    return findings;
+}
+// A config problem (a missing StylesPath, an unknown style) comes back as one object with a Code and Text, not alerts.
+const valeError = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const item = value;
+    return typeof item.Code === 'string' && typeof item.Text === 'string' ? item.Text : undefined;
+};
+// Run Vale once over the given files. A missing executable is `unavailable`, not a failure, so a project without Vale installed
+// can still draft; it simply gets no style check and a note. Exit 1 with valid findings is a normal style failure.
+export function runVale(options) {
+    const command = options.command ?? ['vale'];
+    if (!command.length || !command[0])
+        throw new Error('The Vale command must name an executable');
+    const args = [...command.slice(1), '--output=JSON', ...(options.config ? ['--config', options.config] : []), ...options.files];
+    return new Promise(resolve => {
+        const child = spawn(command[0], args, { cwd: options.directory, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        let err = '';
+        const append = (target) => (chunk) => { if (target === 'out')
+            out = (out + chunk.toString()).slice(-1_000_000);
+        else
+            err = (err + chunk.toString()).slice(-16000); };
+        child.stdout.on('data', append('out'));
+        child.stderr.on('data', append('err'));
+        const abort = () => child.kill();
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            child.kill();
+        const done = (result) => { options.signal?.removeEventListener('abort', abort); resolve(result); };
+        child.on('error', error => done({ status: error.code === 'ENOENT' ? 'unavailable' : 'error', findings: [], error: error.message }));
+        child.on('close', (code, signal) => {
+            let value;
+            try {
+                value = JSON.parse(out);
+            }
+            catch {
+                // No JSON came back. Vale writes rich text when it cannot read the config or the files, so its message is the error.
+                done({ status: 'error', findings: [], error: err.trim() || `Vale exited with code ${code} and produced no JSON` });
+                return;
+            }
+            const configError = valeError(value);
+            if (configError) {
+                done({ status: 'error', findings: [], error: configError });
+                return;
+            }
+            const findings = parseValeAlerts(value);
+            const validAlerts = value !== null && typeof value === 'object' && !Array.isArray(value)
+                && Object.values(value).every(alerts => Array.isArray(alerts) && alerts.every(alert => alert && typeof alert === 'object' && typeof alert.Check === 'string' && typeof alert.Message === 'string'
+                    && ['error', 'warning', 'suggestion'].includes(alert.Severity)));
+            if (!validAlerts || signal || (code !== 0 && !(code === 1 && findings.length))) {
+                done({ status: 'error', findings, error: err.trim() || (signal ? `Vale terminated by ${signal}` : `Vale exited with code ${code}${validAlerts ? ' without a successful check' : ' and produced invalid alerts'}`) });
+                return;
+            }
+            done({ status: findings.some(finding => finding.severity === 'error') ? 'error' : 'ok', findings });
+        });
+    });
+}
+// A runner for one draft at a time. The content is written to a temporary page so Vale applies the same `[*.{md,mdx}]` rules it
+// uses on authored files, then removed. `directory` is the project root so Vale finds the config's relative StylesPath.
+export function createValeRunner(options) {
+    return async (content) => {
+        const directory = await mkdtemp(path.join(os.tmpdir(), 'shoalrun-vale-'));
+        try {
+            const file = path.join(directory, 'draft.mdx');
+            await writeFile(file, content);
+            return await runVale({ directory: options.directory, files: [file], config: options.config, command: options.command, signal: options.signal });
+        }
+        finally {
+            await rm(directory, { recursive: true, force: true });
+        }
+    };
+}

package/dist/vercel-function.d.ts

@@ -0,0 +1,21 @@
+export type AskFunctionResult = {
+    added: true;
+    directory: string;
+    chunks: number;
+    embedded: boolean;
+    embeddingCounts: {
+        embedded: number;
+        reused: number;
+    };
+} | {
+    added: false;
+    reason: string;
+};
+export declare function addAskFunction(input: {
+    configFile: string;
+    staticDirectory: string;
+    functionsDirectory: string;
+    basePath?: string;
+    distDirectory?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<AskFunctionResult>;

package/dist/vercel-function.js

@@ -0,0 +1,108 @@
+import { copyFunctionRuntime } from './function-package.js';
+import { cp, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateChat } from './chat-config.js';
+import { loadConfig } from './config.js';
+import { createProvider, embedChunkIndex, readEmbeddings, writeEmbeddings } from './embeddings.js';
+import { buildChunkIndex, embeddingInput } from './index-build.js';
+import { validateReaderFilters } from './reader-filters.js';
+import { embeddingProviderConfig, validateRetrieval } from './retrieval-config.js';
+// Puts the panel script on every page. A page that already has it is left alone.
+async function addPanelToPages(directory, basePath) {
+    const tag = `<script src="${basePath}/__shoalrun/ask.js" defer></script>`;
+    let pages = 0;
+    const visit = async (folder) => {
+        for (const entry of await readdir(folder, { withFileTypes: true })) {
+            const file = path.join(folder, entry.name);
+            if (entry.isDirectory()) {
+                await visit(file);
+                continue;
+            }
+            if (!entry.name.endsWith('.html'))
+                continue;
+            const html = await readFile(file, 'utf8');
+            if (html.includes(tag) || !html.includes('</body>'))
+                continue;
+            await writeFile(file, html.replace('</body>', `${tag}</body>`));
+            pages++;
+        }
+    };
+    await visit(directory);
+    return pages;
+}
+export async function addAskFunction(input) {
+    const basePath = input.basePath ?? '';
+    const func = path.join(input.functionsDirectory, basePath.slice(1), '__shoalrun', 'ask.func');
+    const searchFunc = path.join(input.functionsDirectory, basePath.slice(1), '__shoalrun', 'search.func');
+    let previous;
+    try {
+        const runtime = JSON.parse(await readFile(path.join(func, 'runtime.json'), 'utf8'));
+        const embeddings = await readEmbeddings(path.join(func, 'site'));
+        if (embeddings)
+            previous = { retrieval: runtime.settings?.retrieval, embeddings };
+    }
+    catch { /* A missing or damaged previous bundle is a cache miss. */ }
+    await rm(func, { recursive: true, force: true });
+    await rm(searchFunc, { recursive: true, force: true });
+    const env = input.env ?? process.env;
+    const settings = (await loadConfig(input.configFile)).value;
+    const readerFilters = validateReaderFilters(settings.readerFilters);
+    const chat = validateChat(settings.chat, readerFilters);
+    if (!chat)
+        return { added: false, reason: 'the config has no chat section' };
+    if (!chat.budget?.store)
+        return { added: false, reason: 'chat.budget needs a shared store (chat.budget.store), so the daily caps hold across server instances' };
+    const retrieval = validateRetrieval(settings.retrieval);
+    if (!retrieval?.embeddings)
+        return { added: false, reason: 'the config has no retrieval.embeddings, so there is nothing to search meaningfully' };
+    const provider = createProvider(embeddingProviderConfig(retrieval, {}));
+    const keyName = retrieval.embeddings.keyEnv ?? (provider.name === 'voyage' ? 'VOYAGE_API_KEY' : 'OPENAI_API_KEY');
+    if (!env[keyName])
+        return { added: false, reason: `set ${keyName} at build time to embed the passages` };
+    const built = await buildChunkIndex(input.staticDirectory);
+    const site = path.join(func, 'site');
+    let embedded;
+    try {
+        // Compilation replaces static output, while the prior function holds the only private vectors.
+        // Reuse them only when the exact retrieval settings still name the same embedding service.
+        if (previous && JSON.stringify(previous.retrieval) === JSON.stringify(settings.retrieval)) {
+            await writeEmbeddings(input.staticDirectory, previous.embeddings.meta, previous.embeddings.vectors);
+        }
+        embedded = await embedChunkIndex(input.staticDirectory, built.index, provider, embeddingInput);
+        await mkdir(site, { recursive: true });
+        // The index is private. It must not stay in the static directory, which is served to everyone.
+        await rename(path.join(input.staticDirectory, 'ai'), path.join(site, 'ai'));
+    }
+    finally {
+        await rm(path.join(input.staticDirectory, 'ai'), { recursive: true, force: true });
+    }
+    // What the browser needs: the panel script, and a small public settings file with the Turnstile site key, the recording notice, and the panel wording.
+    // Nothing in it is secret. The panel is added to every page.
+    const shoalrun = path.join(input.staticDirectory, basePath.slice(1), '__shoalrun');
+    await mkdir(shoalrun, { recursive: true });
+    const assets = path.join(input.distDirectory ?? path.dirname(fileURLToPath(import.meta.url)), '..', 'assets');
+    await cp(path.join(assets, 'ask-widget.js'), path.join(shoalrun, 'ask.js'));
+    await writeFile(path.join(shoalrun, 'chat.json'), JSON.stringify({ ...(chat.challenge ? { siteKey: chat.challenge.siteKey, ...(chat.challenge.when === 'always' ? { prewarm: true } : {}) } : {}), ...(chat.log ? { notice: chat.log.notice } : {}), ...(chat.panel ? { panel: chat.panel } : {}) }, null, 2) + '\n');
+    await addPanelToPages(input.staticDirectory, basePath);
+    const publications = settings.publications?.defaults;
+    const origin = settings.site?.origin;
+    const runtime = {
+        schemaVersion: 1,
+        settings: { chat: settings.chat, retrieval: settings.retrieval, ...(settings.search ? { search: settings.search } : {}), ...(settings.readerFilters ? { readerFilters: settings.readerFilters } : {}) },
+        ...(publications?.channel && publications.version && publications.language ? { variant: { channel: publications.channel, version: publications.version, language: publications.language } } : {}),
+        ...(origin ? { hosts: [new URL(origin).host] } : {})
+    };
+    await writeFile(path.join(func, 'runtime.json'), JSON.stringify(runtime, null, 2) + '\n');
+    const dist = input.distDirectory ?? path.dirname(fileURLToPath(import.meta.url));
+    await copyFunctionRuntime(dist, 'ask-function.js', func);
+    await writeFile(path.join(func, 'package.json'), JSON.stringify({ type: 'module' }, null, 2) + '\n');
+    await writeFile(path.join(func, 'index.js'), `import { createAskFunction, nodeAdapter } from './lib/ask-function.js';\n\nconst directory = new URL('.', import.meta.url).pathname;\nexport default nodeAdapter(() => createAskFunction(directory));\n`);
+    // The answer can take about a minute. Hobby allows up to 300 seconds with Fluid compute, so 120 leaves room.
+    await writeFile(path.join(func, '.vc-config.json'), JSON.stringify({ runtime: 'nodejs22.x', handler: 'index.js', launcherType: 'Nodejs', shouldAddHelpers: false, maxDuration: 120, memory: 1024 }, null, 2) + '\n');
+    await cp(func, searchFunc, { recursive: true });
+    await writeFile(path.join(searchFunc, 'index.js'), `import { createHostedSearchFunction, nodeAdapter } from './lib/ask-function.js';\n\nconst directory = new URL('.', import.meta.url).pathname;\nexport default nodeAdapter(() => createHostedSearchFunction(directory));\n`);
+    await writeFile(path.join(searchFunc, '.vc-config.json'), JSON.stringify({ runtime: 'nodejs22.x', handler: 'index.js', launcherType: 'Nodejs', shouldAddHelpers: false, maxDuration: 30, memory: 1024 }, null, 2) + '\n');
+    await readdir(func);
+    return { added: true, directory: func, chunks: built.index.chunks.length, embedded: true, embeddingCounts: { embedded: embedded.embedded, reused: embedded.reused } };
+}

package/dist/vercel.d.ts

@@ -0,0 +1,11 @@
+import { type McpFunctionResult } from './mcp-vercel.js';
+import type { BuildProvenance } from './build-info.js';
+import { type AskFunctionResult } from './vercel-function.js';
+export declare function buildVercel(configFile: string, outputDirectory: string, provenance?: BuildProvenance, options?: {
+    chat?: boolean;
+}): Promise<{
+    documents: number;
+    output: string;
+    chat?: AskFunctionResult;
+    mcp?: McpFunctionResult;
+}>;