@happyvertical/smrt-planner 0.0.0-stage → 0.0.1

package/dist/inference/config.d.ts

@@ -0,0 +1,70 @@
+import { type KitchenEndpoint } from '../kitchen/client.ts';
+/**
+ * Where the assistant's language model runs, chosen at runtime by
+ * `planner.config.json` (served next to the app, like a host page's own
+ * config file) or by a mounted `Planner`'s `inference` prop, which wins.
+ *
+ * - `browser`: a small model on this device (WebLLM). The default.
+ * - `host`: the host page's server endpoint; the server owns the prompt.
+ * - `byo`: the visitor's own OpenAI-compatible endpoint (Ollama, OpenRouter,
+ *   OpenAI, custom), configured on the AI page.
+ */
+export type InferenceMode = 'browser' | 'host' | 'byo';
+export declare const INFERENCE_MODES: readonly InferenceMode[];
+/** A bring-your-own endpoint the AI page offers. */
+export interface ByoPresetDefinition {
+    id: string;
+    label: string;
+    /** OpenAI-compatible base, e.g. `http://localhost:11434/v1`; `/chat/completions` is appended. */
+    baseUrl: string;
+    /** A model to suggest. */
+    model?: string;
+    /** The visitor types the base URL themselves. */
+    customUrl?: boolean;
+    /** No key is needed (a local server). */
+    keyless?: boolean;
+    /** Browser-access note shown with the preset. */
+    cors?: string;
+}
+export interface InferenceConfig {
+    mode: InferenceMode;
+    host?: {
+        endpoint: string;
+    };
+    byo?: {
+        /**
+         * Which presets to offer: ids of the built-in ones (`ollama`,
+         * `openrouter`, `openai`, `custom`) or full definitions. Default: all
+         * built-in presets.
+         */
+        presets?: (string | ByoPresetDefinition)[];
+    };
+}
+export declare const DEFAULT_INFERENCE: InferenceConfig;
+/** The file name, served at `${base}/planner.config.json`. */
+export declare const CONFIG_FILE = "planner.config.json";
+export interface ConfigResult {
+    config: InferenceConfig;
+    /** The `kitchen` block (`smrt kitchen`), when the file has a usable one. */
+    kitchen?: KitchenEndpoint;
+    /** Shown to the visitor when the config was unusable and `browser` is used instead. */
+    notice?: string;
+}
+/** http(s) only; a path-only endpoint (`/api/planner/chat`) is the host's own origin. */
+export declare function isUsableEndpoint(value: unknown): value is string;
+/**
+ * Validate a parsed config. Anything wrong (unknown mode, `host` without a
+ * usable endpoint, a malformed preset list) falls back to `browser` with a
+ * notice, never to a half-working mode.
+ */
+export declare function validateInferenceConfig(value: unknown): ConfigResult;
+/** Parse the file's text. */
+export declare function parseInferenceConfig(text: string): ConfigResult;
+/** The mounted component's prop, validated like the file. Invalid: browser plus a notice. */
+export declare function configFromProp(prop: unknown): ConfigResult;
+/**
+ * Fetch `${base}/planner.config.json`. A missing file (404, network error)
+ * means the defaults and no notice; a file that is there but unusable means
+ * `browser` and a notice.
+ */
+export declare function loadInferenceConfig(base?: string, fetcher?: typeof fetch): Promise<ConfigResult>;

package/dist/inference/config.js

@@ -0,0 +1,149 @@
+import { parseKitchenConfig } from "../kitchen/client.js";
+export const INFERENCE_MODES = [
+    'browser',
+    'host',
+    'byo',
+];
+export const DEFAULT_INFERENCE = { mode: 'browser' };
+/** The file name, served at `${base}/planner.config.json`. */
+export const CONFIG_FILE = 'planner.config.json';
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** http(s) only; a path-only endpoint (`/api/planner/chat`) is the host's own origin. */
+export function isUsableEndpoint(value) {
+    if (typeof value !== 'string')
+        return false;
+    const text = value.trim();
+    if (!text)
+        return false;
+    if (text.startsWith('/') && !text.startsWith('//'))
+        return true;
+    try {
+        const url = new URL(text);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function parsePresetDefinition(value) {
+    if (!isObject(value))
+        return null;
+    const { id, label, baseUrl, model, keyless, cors } = value;
+    if (typeof id !== 'string' || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(id)) {
+        return null;
+    }
+    if (typeof label !== 'string' || !label.trim())
+        return null;
+    if (!isUsableEndpoint(baseUrl) || baseUrl.startsWith('/'))
+        return null;
+    return {
+        id,
+        label: label.trim(),
+        baseUrl: baseUrl.trim(),
+        ...(typeof model === 'string' && model.trim()
+            ? { model: model.trim() }
+            : {}),
+        ...(keyless === true ? { keyless: true } : {}),
+        ...(typeof cors === 'string' && cors.trim() ? { cors: cors.trim() } : {}),
+    };
+}
+const fallback = (why) => ({
+    config: DEFAULT_INFERENCE,
+    notice: `The assistant settings could not be used (${why}), so it runs in your browser instead.`,
+});
+/**
+ * Validate a parsed config. Anything wrong (unknown mode, `host` without a
+ * usable endpoint, a malformed preset list) falls back to `browser` with a
+ * notice, never to a half-working mode.
+ */
+export function validateInferenceConfig(value) {
+    if (!isObject(value))
+        return fallback('not an object');
+    const inference = value.inference;
+    if (inference === undefined)
+        return { config: DEFAULT_INFERENCE };
+    if (!isObject(inference))
+        return fallback('"inference" is not an object');
+    const mode = inference.mode;
+    if (mode === undefined || mode === 'browser') {
+        return { config: DEFAULT_INFERENCE };
+    }
+    if (mode === 'host') {
+        const host = inference.host;
+        if (!isObject(host) || !isUsableEndpoint(host.endpoint)) {
+            return fallback('host mode needs host.endpoint, an http(s) URL or path');
+        }
+        return {
+            config: { mode: 'host', host: { endpoint: host.endpoint.trim() } },
+        };
+    }
+    if (mode === 'byo') {
+        const byo = inference.byo;
+        if (byo === undefined)
+            return { config: { mode: 'byo' } };
+        if (!isObject(byo))
+            return fallback('"byo" is not an object');
+        if (byo.presets === undefined)
+            return { config: { mode: 'byo', byo: {} } };
+        if (!Array.isArray(byo.presets) || byo.presets.length === 0) {
+            return fallback('byo.presets must be a non-empty list');
+        }
+        const presets = [];
+        for (const entry of byo.presets) {
+            if (typeof entry === 'string' && entry.trim()) {
+                presets.push(entry.trim());
+                continue;
+            }
+            const definition = parsePresetDefinition(entry);
+            if (!definition)
+                return fallback('a byo preset is malformed');
+            presets.push(definition);
+        }
+        return { config: { mode: 'byo', byo: { presets } } };
+    }
+    return fallback(`unknown mode "${String(mode)}"`);
+}
+/** Parse the file's text. */
+export function parseInferenceConfig(text) {
+    try {
+        const value = JSON.parse(text);
+        const result = validateInferenceConfig(value);
+        const kitchen = isObject(value)
+            ? parseKitchenConfig(value.kitchen)
+            : undefined;
+        return kitchen ? { ...result, kitchen } : result;
+    }
+    catch {
+        return fallback('it is not valid JSON');
+    }
+}
+/** The mounted component's prop, validated like the file. Invalid: browser plus a notice. */
+export function configFromProp(prop) {
+    return validateInferenceConfig({ inference: prop });
+}
+/**
+ * Fetch `${base}/planner.config.json`. A missing file (404, network error)
+ * means the defaults and no notice; a file that is there but unusable means
+ * `browser` and a notice.
+ */
+export async function loadInferenceConfig(base = '', fetcher = fetch) {
+    let response;
+    try {
+        response = await fetcher(`${base.replace(/\/$/, '')}/${CONFIG_FILE}`, {
+            headers: { accept: 'application/json' },
+            cache: 'no-cache',
+        });
+    }
+    catch {
+        return { config: DEFAULT_INFERENCE };
+    }
+    if (response.status === 404)
+        return { config: DEFAULT_INFERENCE };
+    if (!response.ok)
+        return fallback(`the file answered ${response.status}`);
+    const text = await response.text();
+    // A static host with a SPA fallback answers a missing file with HTML.
+    if (/^\s*</.test(text))
+        return { config: DEFAULT_INFERENCE };
+    return parseInferenceConfig(text);
+}

package/dist/inference/host.d.ts

@@ -0,0 +1,40 @@
+import type { ChatModel } from '../assistant/transport.ts';
+import type { PlanSnapshot } from '../planner/commands/types.ts';
+/** Wire contract version; see `docs/inference-host.md`. */
+export declare const HOST_WIRE_VERSION = 1;
+/** Recent turns sent along (the transport already keeps six). */
+export declare const HOST_HISTORY_TURNS = 6;
+/** Longest history entry sent; the rest is cut. */
+export declare const HOST_HISTORY_CHARS = 1000;
+/** Longest message sent. */
+export declare const HOST_MESSAGE_CHARS = 2000;
+/** What the planner POSTs to the host endpoint. */
+export interface HostRequest {
+    version: typeof HOST_WIRE_VERSION;
+    /** The visitor's text, and nothing else of the prompt. */
+    message: string;
+    /** The compact plan snapshot from the controller. */
+    snapshot: PlanSnapshot;
+    /** Bounded recent turns, oldest first. Never a system message. */
+    history?: {
+        role: 'user' | 'assistant';
+        content: string;
+    }[];
+}
+export interface HostChatOptions {
+    /** `http(s)://…` or a path on the page's own origin. */
+    endpoint: string;
+    /** The plan as it is now, read per turn. */
+    snapshot: () => PlanSnapshot;
+    fetch?: typeof fetch;
+    /** Extra request headers a host wants (a CSRF token, say). */
+    headers?: () => Record<string, string>;
+}
+/**
+ * A `ChatModel` that asks the host's server. The server owns the prompt: only
+ * the visitor's text, the compact snapshot and bounded recent turns leave the
+ * page. The system prompt the transport builds for local models is dropped,
+ * as is the response schema; the server answers with the same action JSON
+ * the assistant reads from a model (see `docs/inference-host.md`).
+ */
+export declare function createHostChat(options: HostChatOptions): ChatModel;

package/dist/inference/host.js

@@ -0,0 +1,57 @@
+/** Wire contract version; see `docs/inference-host.md`. */
+export const HOST_WIRE_VERSION = 1;
+/** Recent turns sent along (the transport already keeps six). */
+export const HOST_HISTORY_TURNS = 6;
+/** Longest history entry sent; the rest is cut. */
+export const HOST_HISTORY_CHARS = 1000;
+/** Longest message sent. */
+export const HOST_MESSAGE_CHARS = 2000;
+const REQUEST_TIMEOUT_MS = 60_000;
+const clip = (text, max) => text.length > max ? text.slice(0, max) : text;
+/**
+ * A `ChatModel` that asks the host's server. The server owns the prompt: only
+ * the visitor's text, the compact snapshot and bounded recent turns leave the
+ * page. The system prompt the transport builds for local models is dropped,
+ * as is the response schema; the server answers with the same action JSON
+ * the assistant reads from a model (see `docs/inference-host.md`).
+ */
+export function createHostChat(options) {
+    const doFetch = options.fetch ?? fetch;
+    return {
+        async message(text, callOptions) {
+            const history = (callOptions?.history ?? [])
+                .filter((turn) => turn.role === 'user' || turn.role === 'assistant')
+                .slice(-HOST_HISTORY_TURNS)
+                .map((turn) => ({
+                role: turn.role,
+                content: clip(turn.content, HOST_HISTORY_CHARS),
+            }));
+            const body = {
+                version: HOST_WIRE_VERSION,
+                message: clip(text, HOST_MESSAGE_CHARS),
+                snapshot: options.snapshot(),
+                ...(history.length ? { history } : {}),
+            };
+            const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+            const signal = callOptions?.signal
+                ? AbortSignal.any([callOptions.signal, timeout])
+                : timeout;
+            const response = await doFetch(options.endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/json',
+                    ...options.headers?.(),
+                },
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!response.ok) {
+                throw new Error(`the server answered ${response.status}`);
+            }
+            const reply = await response.text();
+            // The body is the action object. Plain text is read as the reply itself.
+            return reply;
+        },
+    };
+}

package/dist/inference/openai.d.ts

@@ -0,0 +1,59 @@
+import type { ChatModel } from '../assistant/transport.ts';
+/** How hard to ask the endpoint for JSON, strictest first. */
+export type JsonMode = 'json_schema' | 'json_object' | 'none';
+export interface OpenAIChatOptions {
+    /** e.g. `http://localhost:11434/v1`. */
+    baseUrl: string;
+    model: string;
+    /** Sent as `Authorization: Bearer`; omit for a local server. */
+    apiKey?: string;
+    /** Strictest JSON mode to try first; it steps down when the endpoint refuses it. */
+    jsonMode?: JsonMode;
+    fetch?: typeof fetch;
+    /** Called with the mode that worked, so a caller can remember it. */
+    onJsonMode?: (mode: JsonMode) => void;
+}
+/** `http(s)` base without a trailing slash, or null. */
+export declare function normalizeBaseUrl(value: string): string | null;
+/** Hosts that are this computer: a key may travel to them over plain http. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/** Can a key be sent to this address? `https`, or `http` to this computer only. */
+export declare function keyMaySendTo(baseUrl: string): boolean;
+/** The origin a key was entered for: scheme, host and port of the address. */
+export declare function originOf(baseUrl: string): string | null;
+/** A failure that says what happened and never carries the key. */
+export declare class EndpointError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+export interface CompleteOptions {
+    maxTokens?: number;
+    signal?: AbortSignal;
+    /** Ask for JSON-mode output (default true). */
+    json?: boolean;
+    temperature?: number;
+    schema?: Record<string, unknown> | string;
+}
+export interface OpenAIChat extends ChatModel {
+    complete(messages: {
+        role: string;
+        content: string;
+    }[], extra?: CompleteOptions): Promise<string>;
+}
+/**
+ * A `ChatModel` over `${baseUrl}/chat/completions`. JSON-mode output is asked
+ * for with the planner's schema; an endpoint that answers 400/422 to it (many
+ * local servers know only `json_object`, some nothing) is retried one step
+ * down, and the step that worked is kept for the rest of the session.
+ */
+export declare function createOpenAIChat(options: OpenAIChatOptions): OpenAIChat;
+export interface ConnectionResult {
+    ok: boolean;
+    /** One sentence for the visitor. */
+    message: string;
+}
+/**
+ * Test connection: one tiny completion, so the address, the model and the key
+ * are all exercised. Never throws and never echoes the key.
+ */
+export declare function testConnection(options: OpenAIChatOptions): Promise<ConnectionResult>;

package/dist/inference/openai.js

@@ -0,0 +1,202 @@
+const JSON_MODES = ['json_schema', 'json_object', 'none'];
+const REQUEST_TIMEOUT_MS = 120_000;
+/** `http(s)` base without a trailing slash, or null. */
+export function normalizeBaseUrl(value) {
+    try {
+        const url = new URL(value.trim());
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return null;
+        // Credentials in a URL would travel in the clear as part of it.
+        if (url.username || url.password)
+            return null;
+        return `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Hosts that are this computer: a key may travel to them over plain http. */
+export function isLoopbackHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    return (host === 'localhost' ||
+        host.endsWith('.localhost') ||
+        host === '::1' ||
+        /^127(\.\d{1,3}){3}$/.test(host));
+}
+/** Can a key be sent to this address? `https`, or `http` to this computer only. */
+export function keyMaySendTo(baseUrl) {
+    try {
+        const url = new URL(baseUrl.trim());
+        return (url.protocol === 'https:' ||
+            (url.protocol === 'http:' && isLoopbackHost(url.hostname)));
+    }
+    catch {
+        return false;
+    }
+}
+/** The origin a key was entered for: scheme, host and port of the address. */
+export function originOf(baseUrl) {
+    try {
+        return new URL(baseUrl.trim()).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/** A failure that says what happened and never carries the key. */
+export class EndpointError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'EndpointError';
+    }
+}
+function describeStatus(status) {
+    if (status === 401 || status === 403) {
+        return `the endpoint refused the key (${status})`;
+    }
+    if (status === 404) {
+        return 'the endpoint or model was not found (404), check the address and model name';
+    }
+    if (status === 429)
+        return 'the endpoint is rate limiting you (429)';
+    return `the endpoint answered ${status}`;
+}
+/** The text of the first choice, or a reason there is none. */
+function textOf(payload) {
+    const choice = payload?.choices?.[0];
+    const content = choice?.message?.content;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => part && typeof part === 'object' && 'text' in part
+            ? String(part.text)
+            : '')
+            .join('');
+    }
+    throw new EndpointError('the endpoint sent no reply text');
+}
+function responseFormat(mode, schema) {
+    if (mode === 'none')
+        return undefined;
+    if (mode === 'json_schema' && schema && typeof schema === 'object') {
+        return {
+            type: 'json_schema',
+            json_schema: { name: 'planner_turn', strict: false, schema },
+        };
+    }
+    return { type: 'json_object' };
+}
+/**
+ * A `ChatModel` over `${baseUrl}/chat/completions`. JSON-mode output is asked
+ * for with the planner's schema; an endpoint that answers 400/422 to it (many
+ * local servers know only `json_object`, some nothing) is retried one step
+ * down, and the step that worked is kept for the rest of the session.
+ */
+export function createOpenAIChat(options) {
+    const base = normalizeBaseUrl(options.baseUrl);
+    if (!base)
+        throw new EndpointError('the address is not a valid http(s) URL');
+    if (options.apiKey && !keyMaySendTo(base)) {
+        throw new EndpointError('a key is only sent over https, or to this computer; use an https address');
+    }
+    const url = `${base}/chat/completions`;
+    const doFetch = options.fetch ?? fetch;
+    let level = Math.max(0, JSON_MODES.indexOf(options.jsonMode ?? 'json_schema'));
+    async function post(body, signal) {
+        const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+        try {
+            return await doFetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    ...(options.apiKey
+                        ? { authorization: `Bearer ${options.apiKey}` }
+                        : {}),
+                },
+                body: JSON.stringify(body),
+                // No cookies for a third-party endpoint.
+                credentials: 'omit',
+                signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+            });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            // A blocked cross-origin call and an unreachable server look the same
+            // to a page: a TypeError with no detail.
+            throw new EndpointError('could not reach the endpoint. Is it running, and does it allow this page (CORS)?');
+        }
+    }
+    async function complete(messages, extra = {}) {
+        const wantJson = extra.json !== false;
+        for (;;) {
+            const mode = wantJson ? (JSON_MODES[level] ?? 'none') : 'none';
+            const format = responseFormat(mode, extra.schema);
+            const response = await post({
+                model: options.model,
+                messages,
+                stream: false,
+                temperature: extra.temperature ?? 0,
+                ...(extra.maxTokens ? { max_tokens: extra.maxTokens } : {}),
+                ...(format ? { response_format: format } : {}),
+            }, extra.signal);
+            if (response.ok) {
+                if (wantJson)
+                    options.onJsonMode?.(mode);
+                return textOf(await response.json().catch(() => null));
+            }
+            // The endpoint refused the JSON mode: step down and ask again.
+            if (wantJson &&
+                (response.status === 400 || response.status === 422) &&
+                level < JSON_MODES.length - 1) {
+                level += 1;
+                continue;
+            }
+            throw new EndpointError(describeStatus(response.status), response.status);
+        }
+    }
+    return {
+        complete,
+        message(text, callOptions) {
+            return complete([
+                ...(callOptions?.history ?? []).map(({ role, content }) => ({
+                    role,
+                    content,
+                })),
+                { role: 'user', content: text },
+            ], {
+                maxTokens: callOptions?.maxTokens,
+                signal: callOptions?.signal,
+                temperature: callOptions?.temperature,
+                schema: callOptions?.responseSchema,
+            });
+        },
+    };
+}
+/**
+ * Test connection: one tiny completion, so the address, the model and the key
+ * are all exercised. Never throws and never echoes the key.
+ */
+export async function testConnection(options) {
+    try {
+        const chat = createOpenAIChat({ ...options, jsonMode: 'none' });
+        const reply = await chat.complete([{ role: 'user', content: 'Reply with the single word OK.' }], { maxTokens: 8, json: false });
+        return {
+            ok: true,
+            message: reply.trim()
+                ? `Connected to ${options.model}.`
+                : `Connected to ${options.model}, but it sent an empty reply.`,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: error instanceof EndpointError
+                ? `Could not connect: ${error.message}.`
+                : 'Could not connect.',
+        };
+    }
+}

package/dist/inference/presets.d.ts

@@ -0,0 +1,5 @@
+import type { ByoPresetDefinition } from './config.ts';
+/** The first-party presets; a config's `byo.presets` picks from or adds to these. */
+export declare const BUILT_IN_PRESETS: readonly ByoPresetDefinition[];
+/** Presets a config offers, in its order; unknown ids are dropped. Default: all built-ins. */
+export declare function resolvePresets(requested?: readonly (string | ByoPresetDefinition)[]): ByoPresetDefinition[];

package/dist/inference/presets.js

@@ -0,0 +1,46 @@
+/** The first-party presets; a config's `byo.presets` picks from or adds to these. */
+export const BUILT_IN_PRESETS = [
+    {
+        id: 'ollama',
+        label: 'Ollama (on this computer)',
+        baseUrl: 'http://localhost:11434/v1',
+        model: 'llama3.2',
+        keyless: true,
+        cors: 'Ollama only answers pages it trusts. Start it with OLLAMA_ORIGINS set to this site, for example OLLAMA_ORIGINS=https://your-site.example ollama serve (on macOS: launchctl setenv OLLAMA_ORIGINS https://your-site.example, then restart Ollama). A page served from http://localhost needs no change.',
+    },
+    {
+        id: 'openrouter',
+        label: 'OpenRouter',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        model: 'openai/gpt-4o-mini',
+        cors: 'OpenRouter accepts calls from any web page, so no setup is needed. Use a key with a spending limit.',
+    },
+    {
+        id: 'openai',
+        label: 'OpenAI',
+        baseUrl: 'https://api.openai.com/v1',
+        model: 'gpt-4o-mini',
+        cors: 'OpenAI accepts calls from web pages when the request carries a key. Use a restricted key with a low spending limit: anyone with access to this browser profile can read it.',
+    },
+    {
+        id: 'custom',
+        label: 'Custom OpenAI-compatible endpoint',
+        baseUrl: '',
+        customUrl: true,
+        cors: 'The server must answer the browser\'s CORS preflight: allow this site\'s origin, the "authorization" and "content-type" headers, and the POST and OPTIONS methods.',
+    },
+];
+/** Presets a config offers, in its order; unknown ids are dropped. Default: all built-ins. */
+export function resolvePresets(requested) {
+    if (!requested?.length)
+        return [...BUILT_IN_PRESETS];
+    const out = [];
+    for (const entry of requested) {
+        const preset = typeof entry === 'string'
+            ? BUILT_IN_PRESETS.find((p) => p.id === entry)
+            : entry;
+        if (preset && !out.some((p) => p.id === preset.id))
+            out.push(preset);
+    }
+    return out.length ? out : [...BUILT_IN_PRESETS];
+}

package/dist/kitchen/client.d.ts

@@ -0,0 +1,39 @@
+import type { Cookbook } from '../cookbook/types.ts';
+/** Where to send, from the config. Absent from the config means no kitchen. */
+export interface KitchenEndpoint {
+    endpoint: string;
+    /**
+     * True when the file still carried a `token`: an older `smrt` CLI that serves
+     * it where any local process can read it. The value is never kept, and
+     * sending is off until the CLI is updated.
+     */
+    tokenInConfig?: true;
+}
+/** Where and how to send: the config's endpoint and the address's token. */
+export interface KitchenConfig extends KitchenEndpoint {
+    token: string;
+}
+/** The header the CLI checks the one-time token in. */
+export declare const KITCHEN_TOKEN_HEADER = "x-kitchen-token";
+/** What the kitchen reports after writing the project. */
+export interface KitchenResult {
+    dir: string;
+    mode: 'new' | 'update';
+    installed: boolean;
+    added: string[];
+    nextSteps: string[];
+}
+export type KitchenOutcome = {
+    ok: true;
+    result: KitchenResult;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Validate the config's `kitchen` block. Anything unusable means no kitchen.
+ * Only the endpoint is read: a `token` here is ignored, never used.
+ */
+export declare function parseKitchenConfig(value: unknown): KitchenEndpoint | undefined;
+/** POST the cookbook to the kitchen. Never throws; a failure is an outcome. */
+export declare function sendToKitchen(config: KitchenConfig, cookbook: Cookbook, fetcher?: typeof fetch): Promise<KitchenOutcome>;