@shoalrun/cli 0.1.0-alpha.16 → 0.1.0-alpha.17

package/dist/function-runtime.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export type FunctionRuntime = {
+    schemaVersion: 1;
+    settings: Record<string, unknown>;
+    variant?: {
+        channel: string;
+        version: string;
+        language: string;
+    };
+    hosts?: string[];
+    callerHeader?: string;
+    maxRequestsPerMinute?: number;
+    searchStore?: {
+        provider: 'upstash';
+        urlEnv: string;
+        tokenEnv: string;
+    };
+};
+export type AskFunction = (request: Request) => Promise<Response>;
+export declare function allowedHosts(runtime: FunctionRuntime, env: NodeJS.ProcessEnv): string[];
+export declare function nodeAdapter(load: () => Promise<AskFunction>, limits?: {
+    bodyBytes: number;
+}): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/function-runtime.js

@@ -0,0 +1,45 @@
+export function allowedHosts(runtime, env) {
+    return [...new Set([...(runtime.hosts ?? []), env.VERCEL_URL, env.VERCEL_BRANCH_URL, env.VERCEL_PROJECT_PRODUCTION_URL, ...(env.SHOALRUN_ASK_HOSTS?.split(',') ?? [])].map(host => host?.trim().toLowerCase()).filter((host) => Boolean(host)))];
+}
+const failure = (status, message) => new Response(JSON.stringify({ error: message }), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' } });
+// Vercel's Node runtime calls `(req, res)`. This turns that into a Web request and back. Starting up happens on the first request, and a
+// failed start is tried again on the next one. The reader never sees why it failed; the reason goes to the function log.
+export function nodeAdapter(load, limits = { bodyBytes: 32_768 }) {
+    let ready;
+    const write = async (res, response) => {
+        res.statusCode = response.status;
+        response.headers.forEach((value, name) => { if (name !== 'set-cookie')
+            res.setHeader(name, value); });
+        const cookies = response.headers.getSetCookie();
+        if (cookies.length)
+            res.setHeader('set-cookie', cookies);
+        res.end(Buffer.from(await response.arrayBuffer()));
+    };
+    return async (req, res) => {
+        try {
+            const handler = await (ready ??= load().catch(error => { ready = undefined; throw error; }));
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of req) {
+                size += chunk.length;
+                if (size > limits.bodyBytes) {
+                    await write(res, failure(413, 'The request is too large.'));
+                    return;
+                }
+                chunks.push(chunk);
+            }
+            const headers = new Headers();
+            for (const [name, value] of Object.entries(req.headers))
+                for (const item of Array.isArray(value) ? value : value === undefined ? [] : [value])
+                    headers.append(name, item);
+            const method = req.method ?? 'GET';
+            const request = new Request(`https://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { method, headers, ...(method === 'GET' || method === 'HEAD' ? {} : { body: Buffer.concat(chunks) }) });
+            await write(res, await handler(request));
+        }
+        catch (error) {
+            console.error(`The answer function failed: ${error.message}`);
+            if (!res.headersSent)
+                await write(res, failure(503, 'The chat is unavailable right now.'));
+        }
+    };
+}

package/dist/index-build.d.ts

@@ -1,3 +1,4 @@
+export { aiDirectory } from './ai-directory.js';
 import { type PreparedSearchPassage } from './search-snippet.js';
 export type Chunk = {
     id: string;
@@ -46,10 +47,8 @@ export declare function chunkMarkdown(markdown: string, document: ChunkSource, a
     id: string;
     title: string;
 }>, options?: ChunkOptions): Chunk[];
-export declare function aiDirectory(directory: string): Promise<string>;
 export declare function buildChunkIndex(directory: string, options?: ChunkOptions): Promise<{
     index: ChunkIndex;
     output: string;
     documents: number;
 }>;
-export {};

package/dist/index-build.js

@@ -1,5 +1,7 @@
+import { aiDirectory } from './ai-directory.js';
+export { aiDirectory } from './ai-directory.js';
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { readFile, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { validateSearchSynonyms } from './search-synonyms.js';
 import { prepareSearchPassage } from './search-snippet.js';
@@ -187,16 +189,6 @@ async function readJson(file) {
 }
 // The directory that holds the passage and vector files. It is created on demand, and it must stay inside the site even if
 // `ai` is a symlink.
-export async function aiDirectory(directory) {
-    const root = path.resolve(directory);
-    const target = path.join(root, 'ai');
-    await mkdir(target, { recursive: true });
-    const real = await realpath(root);
-    const inside = await realpath(target);
-    if (inside !== real && !inside.startsWith(real + path.sep))
-        throw new Error('The ai directory leaves the site directory');
-    return target;
-}
 export async function buildChunkIndex(directory, options = {}) {
     const root = path.resolve(directory);
     const manifest = await readJson(path.join(root, 'documents.json'));

package/dist/retrieval-runtime.d.ts

@@ -0,0 +1,5 @@
+import { Retriever } from './retrieval.js';
+export declare function prepareSearchRetrieval(directory: string, settings: Record<string, unknown>): Promise<{
+    retriever: Retriever;
+    embedQuery: ((query: string, signal?: AbortSignal) => Promise<Float32Array>) | undefined;
+}>;

package/dist/retrieval-runtime.js

@@ -0,0 +1,21 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createProvider, readEmbeddings } from './embeddings.js';
+import { queryProviderConfig, validateRetrieval } from './retrieval-config.js';
+import { Retriever } from './retrieval.js';
+// Search needs only passage retrieval and query embeddings, never chat models,
+// answer cards, source configuration, rendering, or component compilation.
+export async function prepareSearchRetrieval(directory, settings) {
+    const retrieval = validateRetrieval(settings.retrieval);
+    const chunks = JSON.parse(await readFile(path.join(directory, 'ai', 'chunks.json'), 'utf8'));
+    const embeddings = await readEmbeddings(directory);
+    const retriever = new Retriever(chunks, embeddings);
+    let embedQuery;
+    if (embeddings) {
+        const provider = createProvider(queryProviderConfig(retrieval, embeddings.meta));
+        if (provider.space !== embeddings.meta.space || (embeddings.meta.backend && provider.backend !== embeddings.meta.backend))
+            throw new Error(`${provider.model} is not in the embedding space or backend of ${embeddings.meta.model}`);
+        embedQuery = async (query, signal) => (await provider.embed([query], 'query', signal))[0];
+    }
+    return { retriever, embedQuery };
+}

package/dist/search-function.d.ts

@@ -0,0 +1,2 @@
+import { type AskFunction } from './function-runtime.js';
+export declare function createHostedSearchFunction(directory: string, env?: NodeJS.ProcessEnv): Promise<AskFunction>;

package/dist/search-function.js

@@ -0,0 +1,30 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { DailyBudget, SharedRateLimit } from './budget.js';
+import { envBudgetStore } from './budget-store.js';
+import { validateReaderFilters } from './reader-filters.js';
+import { createSearchHandler } from './search-handler.js';
+import { validateSearch } from './search-config.js';
+import { prepareSearchRetrieval } from './retrieval-runtime.js';
+import { allowedHosts } from './function-runtime.js';
+export async function createHostedSearchFunction(directory, env = process.env) {
+    const runtime = JSON.parse(await readFile(path.join(directory, 'runtime.json'), 'utf8'));
+    if (runtime?.schemaVersion !== 1 || !runtime.settings)
+        throw new Error('runtime.json is not a Shoalrun search function file');
+    const filters = validateReaderFilters(runtime.settings.readerFilters);
+    // Accept old function metadata while new builds omit the chat configuration.
+    const legacy = runtime.settings.chat;
+    const settings = runtime.searchStore ?? legacy?.budget?.store;
+    if (!settings || typeof settings !== 'object' || !('provider' in settings) || settings.provider !== 'upstash' || !('urlEnv' in settings) || typeof settings.urlEnv !== 'string' || !('tokenEnv' in settings) || typeof settings.tokenEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(settings.urlEnv) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(settings.tokenEnv))
+        throw new Error('Hosted semantic search needs a shared budget store');
+    const setup = await prepareSearchRetrieval(path.join(directory, 'site'), runtime.settings);
+    const store = envBudgetStore({ urlEnv: settings.urlEnv, tokenEnv: settings.tokenEnv }, env);
+    const { limits } = validateSearch(runtime.settings.search);
+    return createSearchHandler({
+        ...setup, readerFilters: filters, hosts: allowedHosts(runtime, env),
+        onFallback: reason => console.warn(`Search fallback: ${reason}`),
+        rateLimiter: new SharedRateLimit(store, limits.perCallerPerMinute, Date.now, error => console.error(`Search rate limit: ${error.message}`), 'search-rate'),
+        budget: new DailyBudget(store, { perCaller: limits.perCallerPerDay, perDay: limits.perDay }, Date.now, error => console.error(`Search budget: ${error.message}`), 'search-budget'),
+        clientKey: request => request.headers.get(runtime.callerHeader ?? 'x-vercel-forwarded-for')?.split(',')[0].trim() || 'unknown'
+    });
+}

package/dist/search-handler.js

@@ -1,7 +1,7 @@
 import { compareHits } from './retrieval.js';
 import { validateReaderSelection } from './reader-filters.js';
-import { searchSnippetFromParagraphs } from './search-snippet.js';
-import { identifierMatch } from './search-identifier.js';
+import { searchSnippetFromParagraphs } from './search-text.js';
+import { identifierMatch } from './search-identifier-core.js';
 import { createSearchResultSelector } from './search-results.js';
 export function createSearchHandler(options) {
     const selectResults = createSearchResultSelector(options.retriever);

package/dist/search-identifier-core.d.ts

@@ -0,0 +1,4 @@
+import type { Hit } from './retrieval.js';
+export declare function searchIdentifiers(query: string): string[];
+export declare function identifierRescue<T extends Hit>(query: string, semantic: T[], lexical: T[], paragraphs?: (hit: Hit) => string[]): T[];
+export declare function identifierMatch(query: string, paragraphs?: (hit: Hit) => string[]): ((hit: Hit) => boolean) | undefined;

package/dist/search-identifier-core.js

@@ -0,0 +1,30 @@
+// Reserve at most one search-box result for a literal configuration key or flag
+// explained in prose. Tables, code listings and identifier prefixes do not qualify.
+export function searchIdentifiers(query) {
+    const identifiers = query.match(/\b[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+\b|--[a-z][\w-]*/g) ?? [];
+    // File names and URLs need ordinary retrieval, not a config-key shortcut.
+    return [...new Set(identifiers.filter(id => !/\.(?:txt|json|ya?ml|mdx?|[cm]?js|tsx?|html?|css|svg|png|jpe?g|com|org|net)$/i.test(id)))];
+}
+export function identifierRescue(query, semantic, lexical, paragraphs) {
+    const matches = identifierMatch(query, paragraphs);
+    if (!matches)
+        return semantic;
+    const candidate = lexical.find(matches);
+    if (!candidate)
+        return semantic;
+    const pages = [...new Set(semantic.map(h => h.chunk.docId))];
+    if (pages.slice(0, 3).includes(candidate.chunk.docId))
+        return semantic;
+    const remaining = semantic.filter(h => h.chunk.docId !== candidate.chunk.docId);
+    const seen = new Set();
+    const at = remaining.findIndex(hit => { seen.add(hit.chunk.docId); return seen.size === 3; });
+    const position = at < 0 ? remaining.length : at;
+    return [...remaining.slice(0, position), candidate, ...remaining.slice(position)];
+}
+export function identifierMatch(query, paragraphs = hit => hit.chunk.search?.paragraphs ?? []) {
+    const identifiers = searchIdentifiers(query);
+    if (!identifiers.length)
+        return undefined;
+    const matches = identifiers.map(id => new RegExp(`(?<![\\w$.-])${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w$-]|\\.[\\w$])`, 'i'));
+    return hit => paragraphs(hit).some(p => matches.every(re => re.test(p)));
+}

package/dist/search-identifier.d.ts

@@ -1,4 +1,4 @@
 import type { Hit } from './retrieval.js';
-export declare function searchIdentifiers(query: string): string[];
-export declare function identifierRescue<T extends Hit>(query: string, semantic: T[], lexical: T[]): T[];
-export declare function identifierMatch(query: string): ((hit: Hit) => boolean) | undefined;
+export { searchIdentifiers } from './search-identifier-core.js';
+export declare const identifierMatch: (query: string) => ((hit: Hit) => boolean) | undefined;
+export declare const identifierRescue: <T extends Hit>(query: string, semantic: T[], lexical: T[]) => T[];

package/dist/search-identifier.js

@@ -1,31 +1,8 @@
 import { searchParagraphs } from './search-snippet.js';
-// Reserve at most one search-box result for a literal configuration key or flag
-// explained in prose. Tables, code listings and identifier prefixes do not qualify.
-export function searchIdentifiers(query) {
-    const identifiers = query.match(/\b[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+\b|--[a-z][\w-]*/g) ?? [];
-    // File names and URLs need ordinary retrieval, not a config-key shortcut.
-    return [...new Set(identifiers.filter(id => !/\.(?:txt|json|ya?ml|mdx?|[cm]?js|tsx?|html?|css|svg|png|jpe?g|com|org|net)$/i.test(id)))];
-}
-export function identifierRescue(query, semantic, lexical) {
-    const matches = identifierMatch(query);
-    if (!matches)
-        return semantic;
-    const candidate = lexical.find(matches);
-    if (!candidate)
-        return semantic;
-    const pages = [...new Set(semantic.map(h => h.chunk.docId))];
-    if (pages.slice(0, 3).includes(candidate.chunk.docId))
-        return semantic;
-    const remaining = semantic.filter(h => h.chunk.docId !== candidate.chunk.docId);
-    const seen = new Set();
-    const at = remaining.findIndex(hit => { seen.add(hit.chunk.docId); return seen.size === 3; });
-    const position = at < 0 ? remaining.length : at;
-    return [...remaining.slice(0, position), candidate, ...remaining.slice(position)];
-}
-export function identifierMatch(query) {
-    const identifiers = searchIdentifiers(query);
-    if (!identifiers.length)
-        return undefined;
-    const matches = identifiers.map(id => new RegExp(`(?<![\\w$.-])${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w$-]|\\.[\\w$])`, 'i'));
-    return hit => (hit.chunk.search?.paragraphs ?? searchParagraphs(hit.chunk.text)).some(p => matches.every(re => re.test(p)));
-}
+import { identifierMatch as preparedMatch, identifierRescue as preparedRescue } from './search-identifier-core.js';
+export { searchIdentifiers } from './search-identifier-core.js';
+// Keep the older unprepared-passage API usable by local callers. Hosted search
+// imports the prepared core and never needs a Markdown parser at request time.
+const paragraphs = (hit) => hit.chunk.search?.paragraphs ?? searchParagraphs(hit.chunk.text);
+export const identifierMatch = (query) => preparedMatch(query, paragraphs);
+export const identifierRescue = (query, semantic, lexical) => preparedRescue(query, semantic, lexical, paragraphs);

package/dist/search-literal.js

@@ -1,4 +1,4 @@
-import { searchIdentifiers } from './search-identifier.js';
+import { searchIdentifiers } from './search-identifier-core.js';
 const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 const boundary = (value) => new RegExp(`(?<![\\w$.-])${escape(value)}(?![\\w$-]|\\.[\\w$])`, 'i');
 // Only explicit technical syntax gets this exception. Ordinary topic words must

package/dist/search-results.js

@@ -1,6 +1,6 @@
 import { compareHits, tokenize } from './retrieval.js';
 import { literalSearch } from './search-literal.js';
-import { identifierRescue } from './search-identifier.js';
+import { identifierRescue } from './search-identifier-core.js';
 // Select landing passages for the search box, without changing passage retrieval
 // used by Ask. A gallery's repeated examples must not crowd other pages out.
 export function createSearchResultSelector(retriever) {

package/dist/search-snippet.d.ts

@@ -1,3 +1,4 @@
+export { searchSnippetFromParagraphs } from './search-text.js';
 export declare function searchParagraphs(markdown: string): string[];
 export declare function searchPassageParagraphs(markdown: string): string[];
 export declare function searchLiteralLines(markdown: string): string[];
@@ -8,4 +9,3 @@ export type PreparedSearchPassage = {
 };
 export declare function prepareSearchPassage(markdown: string): PreparedSearchPassage;
 export declare function searchSnippet(markdown: string, query: string, pageSummary?: string): string;
-export declare function searchSnippetFromParagraphs(choices: string[], query: string, pageSummary?: string): string;

package/dist/search-snippet.js

@@ -1,3 +1,5 @@
+import { searchSnippetFromParagraphs } from './search-text.js';
+export { searchSnippetFromParagraphs } from './search-text.js';
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
@@ -71,23 +73,9 @@ export function prepareSearchPassage(markdown) {
     const tree = parser.parse(markdown);
     return { schemaVersion: 1, paragraphs: passageParagraphs(tree), literalLines: cleanLines(literalLines(tree)) };
 }
-const stopWords = new Set('a an the i me my we our you your how do does can could would should will is are was were be to of in on for with please what where when why which and or it this that have has after before'.split(' '));
 // Prefer substantive query matches; Markdown boilerplate and common question words
 // must not hide a useful paragraph. Keep a matching term visible in long paragraphs.
 export function searchSnippet(markdown, query, pageSummary = '') {
     const choices = searchParagraphs(markdown).filter(p => !discovery.test(p));
     return searchSnippetFromParagraphs(choices, query, pageSummary);
 }
-export function searchSnippetFromParagraphs(choices, query, pageSummary = '') {
-    const terms = [...new Set((query.toLocaleLowerCase().match(/[\p{L}\p{N}_$.-]+/gu) ?? []).map(t => t.replace(/^[.-]+|[.-]+$/g, '')).filter(t => t && !stopWords.has(t)))];
-    const matches = (text) => terms.filter(term => new RegExp(`(?<![\\p{L}\\p{N}_])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\p{L}\\p{N}_])`, 'iu').test(text));
-    const ranked = choices.map((text, at) => ({ text, at, terms: matches(text) })).sort((a, b) => b.terms.length - a.terms.length || a.at - b.at);
-    const selected = ranked[0];
-    const text = (selected?.text ?? pageSummary).replace(/\s+/g, ' ').trim();
-    if (text.length <= 180)
-        return text;
-    const first = selected?.terms.length ? Math.min(...selected.terms.map(t => text.toLocaleLowerCase().indexOf(t))) : 0;
-    const start = Math.max(0, first - 50);
-    const length = 180 - (start ? 1 : 0) - 1;
-    return `${start ? '…' : ''}${text.slice(start, start + length).trim()}…`;
-}

package/dist/search-text.d.ts

@@ -0,0 +1 @@
+export declare function searchSnippetFromParagraphs(choices: string[], query: string, pageSummary?: string): string;

package/dist/search-text.js

@@ -0,0 +1,14 @@
+const stopWords = new Set('a an the i me my we our you your how do does can could would should will is are was were be to of in on for with please what where when why which and or it this that have has after before'.split(' '));
+export function searchSnippetFromParagraphs(choices, query, pageSummary = '') {
+    const terms = [...new Set((query.toLocaleLowerCase().match(/[\p{L}\p{N}_$.-]+/gu) ?? []).map(t => t.replace(/^[.-]+|[.-]+$/g, '')).filter(t => t && !stopWords.has(t)))];
+    const matches = (text) => terms.filter(term => new RegExp(`(?<![\\p{L}\\p{N}_])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\p{L}\\p{N}_])`, 'iu').test(text));
+    const ranked = choices.map((text, at) => ({ text, at, terms: matches(text) })).sort((a, b) => b.terms.length - a.terms.length || a.at - b.at);
+    const selected = ranked[0];
+    const text = (selected?.text ?? pageSummary).replace(/\s+/g, ' ').trim();
+    if (text.length <= 180)
+        return text;
+    const first = selected?.terms.length ? Math.min(...selected.terms.map(t => text.toLocaleLowerCase().indexOf(t))) : 0;
+    const start = Math.max(0, first - 50);
+    const length = 180 - (start ? 1 : 0) - 1;
+    return `${start ? '…' : ''}${text.slice(start, start + length).trim()}…`;
+}

package/dist/vercel-function.js

@@ -100,8 +100,16 @@ export async function addAskFunction(input) {
     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`);
+    // Build Search from its own runtime closure and private retrieval data. It
+    // must not inherit chat generation, cards, logging, or compiler dependencies.
+    await mkdir(path.join(searchFunc, 'site', 'ai'), { recursive: true });
+    for (const name of ['chunks.json', 'embeddings.json', 'embeddings.bin'])
+        await cp(path.join(site, 'ai', name), path.join(searchFunc, 'site', 'ai', name));
+    const { chat: _chat, ...searchSettings } = runtime.settings;
+    await writeFile(path.join(searchFunc, 'runtime.json'), JSON.stringify({ ...runtime, settings: searchSettings, searchStore: chat.budget.store }, null, 2) + '\n');
+    await writeFile(path.join(searchFunc, 'package.json'), JSON.stringify({ type: 'module' }) + '\n');
+    await copyFunctionRuntime(dist, 'search-function.js', searchFunc);
+    await writeFile(path.join(searchFunc, 'index.js'), `import { createHostedSearchFunction } from './lib/search-function.js';\nimport { nodeAdapter } from './lib/function-runtime.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.17",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"