@fugood/buttress-server 2.25.0 → 2.25.1-beta.1

package/lib/functions/config.d.ts

@@ -0,0 +1,20 @@
+import type { GlobalConfig } from '../types';
+import type { FunctionsConfig } from './types';
+export declare const DEFAULT_TIMEOUT_MS: number;
+export type ResolveFunctionsOptions = {
+    /**
+     * Directory a relative `dir` is resolved against — the directory holding the
+     * `--config` file. Inline-TOML configs have no such directory, so callers
+     * pass `process.cwd()`.
+     */
+    configDir?: string;
+    env?: Record<string, string | undefined>;
+};
+/**
+ * Resolve the `[functions]` TOML table (plus env overrides) into the shape the
+ * runtime uses. Returns null when the feature is not enabled.
+ *
+ * Enablement follows the same env-or-config idiom as the compatibility
+ * endpoints: `ENABLE_FUNCTIONS_ENDPOINT=1` or `[functions] enabled = true`.
+ */
+export declare const resolveFunctionsConfig: (globalConfig: GlobalConfig | undefined, { configDir, env }?: ResolveFunctionsOptions) => FunctionsConfig | null;

package/lib/functions/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared constants for the local function system.
+ *
+ * Kept apart from `transpile.ts` so discovery and scaffolding can import them
+ * without pulling in the native transpiler.
+ */
+/** File extensions a local function (or one of its helper modules) may use. */
+export declare const SUPPORTED_EXTENSIONS: string[];
+/** What a function (file) may be called. Doubles as a path-safety guarantee. */
+export declare const FUNCTION_NAME_PATTERN: RegExp;
+/**
+ * Static segments of the functions API a function may not be named after:
+ * `POST /functions/mcp` (MCP), `GET /functions/files/*` (downloads) and
+ * `POST /functions/upload` (uploads) would shadow — or be shadowed by — a
+ * function of the same name.
+ */
+export declare const RESERVED_FUNCTION_NAMES: Set<string>;

package/lib/functions/executor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Runs a loaded local function with a deadline, a scratch directory, and the
+ * capabilities it is allowed to reach (spawn, buttress inference, helper libs).
+ *
+ * Cancellation is cooperative *plus* forceful: the call's AbortSignal is
+ * surfaced to the function (so `fetch` and the inference helpers unwind), and
+ * every process the call spawned is terminated. Code that blocks the event loop
+ * synchronously cannot be interrupted — function files are trusted, and vm has
+ * no way to preempt a running script.
+ */
+import type { FunctionEmit, FunctionRuntime, FunctionsConfig, LoadedFunction } from './types';
+export declare class FunctionTimeoutError extends Error {
+    constructor(name: string, timeoutMs: number);
+}
+export declare class FunctionAbortError extends Error {
+    constructor(name: string);
+}
+export type ExecuteOptions = {
+    runtime: FunctionRuntime;
+    functionsConfig: FunctionsConfig;
+    /** Streams progress to the caller; ignored on non-streaming surfaces. */
+    emit?: FunctionEmit;
+    /** Aborts the call early (e.g. the HTTP client disconnected). */
+    signal?: AbortSignal;
+    callId?: string;
+};
+export declare const executeFunction: (fn: LoadedFunction, input: any, { runtime, functionsConfig, emit, signal, callId }: ExecuteOptions) => Promise<any>;

package/lib/functions/files.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Path mapping for the function file-download surface.
+ *
+ * A call's scratch directory lives at `<temp_file_dir>/functions/<name>-<id>/`;
+ * `GET /functions/files/<name>-<id>/<file>` serves what a function wrote there.
+ * Both directions of the mapping live here, pure and unit-testable: URL →
+ * filesystem path (with strict containment, for the route) and filesystem
+ * path → URL (for `context.fileUrl`).
+ */
+export declare const FUNCTIONS_FILES_PREFIX = "/functions/files";
+/**
+ * Resolve a raw wildcard path from `GET /functions/files/*` to an absolute
+ * path inside `tempRoot`. Null when the path is empty, escapes the root, or
+ * cannot be decoded — the route treats all of those as 404.
+ */
+export declare const resolveFunctionsFile: (tempRoot: string, rawPath: string) => string | null;
+/**
+ * Build the download URL path for an absolute file inside `tempRoot`.
+ * Null when the file is outside it.
+ */
+export declare const functionsFileUrl: (tempRoot: string, absolutePath: string) => string | null;
+/**
+ * Tame a client-supplied upload file name into something safe to place on
+ * disk. Every upload gets its own directory, so only the name itself needs
+ * care: no path segments, no control characters, no dot-prefixed (hidden /
+ * traversal-looking) names. The extension survives — ffmpeg and friends use
+ * it for format detection.
+ */
+export declare const sanitizeUploadFilename: (original: string) => string;

package/lib/functions/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Local function system: user-authored `.ts`/`.js` files in a configured
+ * directory, exposed as MCP tools and HTTP endpoints.
+ *
+ * `createFunctionsService` is the single entry point the server wires up; it
+ * owns discovery/reload (registry) and execution (executor), and prepares the
+ * directory for authoring on startup.
+ */
+import type { FunctionEmit, FunctionRuntime, FunctionSummary, FunctionsConfig, LoadedAuthFunction } from './types';
+export { resolveFunctionsConfig } from './config';
+export { FunctionNotFoundError } from './registry';
+export { FunctionAbortError, FunctionTimeoutError } from './executor';
+export { FunctionImportError } from './loader';
+export { AUTH_BASENAME } from './auth';
+export type * from './types';
+export type CallOptions = {
+    runtime: FunctionRuntime;
+    emit?: FunctionEmit;
+    signal?: AbortSignal;
+    callId?: string;
+    /** Which API carried the call — recorded in the status history. */
+    surface?: 'http' | 'sse' | 'mcp';
+};
+export type FunctionsService = {
+    config: FunctionsConfig;
+    dir: string;
+    list: () => Promise<FunctionSummary[]>;
+    /** One function's summary; rejects when it is unknown or fails to load. */
+    describe: (name: string) => Promise<FunctionSummary>;
+    call: (name: string, input: any, options: CallOptions) => Promise<any>;
+    /**
+     * The operator's `_auth` function, or null when none exists. Rejects while
+     * an `_auth` file is present but broken — callers treat that as deny-all.
+     */
+    getCustomAuth: () => Promise<LoadedAuthFunction | null>;
+    /**
+     * Live capability summary for `serverInfo`. Mutated in place on every
+     * `list()` so the announced count follows the directory instead of freezing
+     * at whatever was on disk during startup.
+     */
+    stats: {
+        enabled: true;
+        count: number;
+    };
+    /** Stop the hot-reload watcher, when one is running. Safe to call always. */
+    dispose: () => void;
+};
+export type CreateFunctionsServiceOptions = {
+    /** `server.temp_file_dir`; per-call scratch space lives under it. */
+    tempFileDir: string;
+};
+export declare const createFunctionsService: (config: FunctionsConfig, { tempFileDir }: CreateFunctionsServiceOptions) => Promise<FunctionsService>;

package/lib/functions/input.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The shared record contract behind the transport input parsers.
+ *
+ * `parseQueryInput` and `stageMultipartInput` both fill an input object with
+ * externally chosen field names, so plain `input[field] = value` is wrong: a
+ * field literally named `__proto__` would hit `Object.prototype`'s legacy
+ * setter instead of becoming an input value — silently dropped for strings,
+ * and a swapped prototype for object-like values.
+ */
+/** Set an externally named field as a plain own data property. */
+export declare const setInputField: (input: Record<string, any>, field: string, value: any) => void;

package/lib/functions/libs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Helper libraries handed to every local function as `context.libs`.
+ *
+ * These are the node-safe members of the BRICKS data-calculation sandbox bag,
+ * so a script author moving between device-side calc scripts and server-side
+ * local functions finds the same names. They are stateless singletons — the
+ * same instances are shared by every call.
+ */
+export declare const libs: Record<string, any>;
+export declare const LIB_NAMES: string[];

package/lib/functions/loader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Evaluates transpiled local function modules inside a `node:vm` context.
+ *
+ * Each function gets its own vm context, so its module-level state is private
+ * and a reload simply throws the whole context away. The context is a *clean*
+ * global: no `process`, no `require`, no ambient host globals beyond the
+ * curated set in `createSandboxGlobals`. That is a clarity boundary, not a
+ * security boundary — function files are trusted (an operator puts them on the
+ * server's disk, like the TOML config), and they are handed `spawn` anyway.
+ *
+ * Values crossing back from the vm belong to another realm: `Array.isArray`
+ * and `JSON.stringify` work, but `instanceof` against host constructors does
+ * not. Never `instanceof`-check a function's return value.
+ */
+export declare class FunctionImportError extends Error {
+    constructor(message: string);
+}
+/**
+ * Globals visible to function code. Everything here is a host object, so
+ * `Buffer.isBuffer` and friends still work on values a function creates.
+ */
+export declare const createSandboxGlobals: (extra?: Record<string, any>) => Record<string, any>;
+export type ResolvedSpecifier = {
+    kind: 'builtin';
+    id: string;
+} | {
+    kind: 'file';
+    path: string;
+};
+export declare const resolveSpecifier: (specifier: string, fromFile: string, rootDir: string) => Promise<ResolvedSpecifier>;
+export type ModuleGraph = {
+    exports: Record<string, any>;
+    /** Every source file in the graph → its mtimeMs at load time. */
+    files: Map<string, number>;
+};
+export type LoadOptions = {
+    rootDir: string;
+    globals?: Record<string, any>;
+};
+/**
+ * Transpile and evaluate `entryFile` plus everything it imports, returning the
+ * entry's export namespace.
+ *
+ * Note: a module body that blocks synchronously (e.g. `while (true) {}` at the
+ * top level) wedges the event loop — vm has no way to interrupt it. Callers
+ * run this inside the per-call deadline so an *async* hang is still bounded.
+ */
+export declare const loadModuleGraph: (entryFile: string, { rootDir, globals }: LoadOptions) => Promise<ModuleGraph>;

package/lib/functions/mcp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MCP surface for local functions.
+ *
+ * Served from the same Elysia app (and therefore the same port and auth guard)
+ * as the HTTP endpoints. The SDK's own Streamable HTTP transport needs Node
+ * `IncomingMessage`/`ServerResponse` objects, which Elysia does not expose and
+ * which do not exist under Bun at all — so this module pairs the SDK's protocol
+ * implementation with a minimal stateless transport that just moves one
+ * JSON-RPC message in and its response out.
+ *
+ * Stateless means a fresh `Server` per POST: no `mcp-session-id` handshake, and
+ * `tools/list` always reflects the functions on disk right now. Clients that
+ * try to open the optional GET event stream get a 405, which the spec (and the
+ * SDK's client transport) treat as "this server has no server-initiated
+ * stream".
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { FunctionRuntime } from './types';
+import type { FunctionsService } from './index';
+export declare const serializeToolResult: (result: unknown) => string;
+export type McpServerOptions = {
+    functions: FunctionsService;
+    runtime: FunctionRuntime;
+    version: string;
+    signal?: AbortSignal;
+};
+export declare const createFunctionsMcpServer: ({ functions, runtime, version, signal, }: McpServerOptions) => Server;
+type JsonRpcMessage = Record<string, any>;
+/**
+ * Run one JSON-RPC payload (single message or batch) against a fresh server.
+ *
+ * Returns null when nothing needs to be sent back — the caller answers 202.
+ */
+export declare const handleMcpPayload: (options: McpServerOptions, payload: JsonRpcMessage | JsonRpcMessage[]) => Promise<JsonRpcMessage | JsonRpcMessage[] | null>;
+export {};

package/lib/functions/query.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Query-string input for `GET /functions/<name>`.
+ *
+ * The sibling of `stageMultipartInput`: same idea, other transport. An optional
+ * `input` parameter carries a JSON object for exact types, and every other
+ * parameter overlays it — so `?input={"n":3}&note=hi` and a multipart body with
+ * the same two fields produce the same input object.
+ *
+ * Query values are always strings, so a bare `?n=3` would hand a handler `"3"`.
+ * The function's declared `meta.parameters` schema is the only thing that says
+ * otherwise, so it doubles as the coercion table: declared numbers, booleans,
+ * arrays and objects are converted, and anything undeclared stays a string.
+ * Coercion never rejects — a value that does not fit its declared type is
+ * passed through verbatim rather than turned into `NaN` (the handler, which
+ * owns validation, sees what the caller actually sent).
+ */
+/** A caller mistake in the query shape — reported as 400, not 500. */
+export declare class QueryInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * Turn a query string into a function input object.
+ *
+ * `parameters` is the function's declared JSON Schema, when it has one; without
+ * it every value stays a string.
+ */
+export declare const parseQueryInput: (search: URLSearchParams, parameters?: Record<string, any>) => Record<string, any>;

package/lib/functions/registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Discovers local function files and keeps their loaded modules fresh.
+ *
+ * Discovery is a flat scan of the functions directory: every supported
+ * top-level file is one function, named after the file. Subdirectories hold
+ * helper modules — importable by functions, never exposed as tools.
+ *
+ * Reload is lazy and mtime-driven. Before handing back a loaded function we
+ * stat every file in its module graph; if any changed, the module is
+ * re-transpiled into a fresh vm context. No watchers, identical behavior on
+ * every platform, and an edit is picked up by the very next call.
+ */
+import type { FunctionSummary, FunctionsConfig, LoadedFunction } from './types';
+type Entry = {
+    name: string;
+    file: string;
+    loaded: LoadedFunction | null;
+    loading: Promise<LoadedFunction> | null;
+    /** Signature of the last failure we logged, so a broken file logs once. */
+    reportedError: string | null;
+};
+export declare class FunctionNotFoundError extends Error {
+    constructor(name: string);
+}
+export type FunctionsRegistry = ReturnType<typeof createFunctionsRegistry>;
+export declare const createFunctionsRegistry: (config: FunctionsConfig) => {
+    dir: string;
+    config: FunctionsConfig;
+    scan: () => Promise<void>;
+    get: (name: string) => Promise<LoadedFunction>;
+    describe: (name: string) => Promise<FunctionSummary>;
+    list: () => Promise<FunctionSummary[]>;
+    entries: Map<string, Entry>;
+};
+export {};

package/lib/functions/scaffold.d.ts

@@ -0,0 +1,18 @@
+/** One day; function scratch dirs older than this are swept at startup. */
+export declare const TEMP_DIR_MAX_AGE_MS: number;
+/**
+ * Ensure the functions directory exists and carries current editor support.
+ *
+ * The ambient types are always refreshed; the tsconfig and example are only
+ * seeded into a directory that has no functions yet.
+ */
+export declare const scaffoldFunctionsDir: (dir: string) => Promise<{
+    seeded: boolean;
+}>;
+/**
+ * Remove stale per-call scratch directories.
+ *
+ * A call's `tempDir` outlives the request on purpose (a co-located agent may
+ * read the file the function produced), so cleanup is time-based instead.
+ */
+export declare const sweepFunctionTempDirs: (tempRoot: string, maxAgeMs?: number) => Promise<number>;

package/lib/functions/status.d.ts

@@ -0,0 +1,119 @@
+/**
+ * In-memory activity log for the functions surface, shown on `/status`.
+ *
+ * Counterpart to the backend-core status trackers (model loads, completions):
+ * counters since startup plus a bounded newest-first history per category.
+ * Everything here is observable metadata — names, paths, sizes, outcome codes.
+ * Credentials (tokens, API keys) are never recorded.
+ *
+ * A module-scoped singleton, like the backend trackers: the guard, the routes
+ * and the service all record into the same instance, and the status route
+ * snapshots it.
+ */
+export type FunctionCallRecord = {
+    timestamp: string;
+    name: string;
+    surface: 'http' | 'sse' | 'mcp';
+    durationMs: number;
+    success: boolean;
+    error?: string;
+};
+export type FunctionUploadRecord = {
+    timestamp: string;
+    /** 'upload' = POST /functions/upload, 'call' = multipart function call. */
+    source: 'upload' | 'call';
+    name: string;
+    size: number;
+    success: boolean;
+    error?: string;
+};
+export type FunctionDownloadRecord = {
+    timestamp: string;
+    path: string;
+    size?: number;
+    success: boolean;
+};
+export type FunctionAuthRecord = {
+    timestamp: string;
+    method: string;
+    path: string;
+    /**
+     * 'workspace' when no custom auth is active, else the `_auth` mode. Absent
+     * for decisions made before any auth regime applied (origin block, broken
+     * `_auth` file).
+     */
+    mode?: 'workspace' | 'both' | 'override';
+    /** 'allowed', or the denial error code. */
+    outcome: string;
+    subject?: string;
+};
+export declare const createFunctionsStatusTracker: (maxHistory?: number) => {
+    recordCall(record: Omit<FunctionCallRecord, 'timestamp'>): void;
+    recordUpload(record: Omit<FunctionUploadRecord, 'timestamp'>): void;
+    recordDownload(record: Omit<FunctionDownloadRecord, 'timestamp'>): void;
+    recordAuth(record: Omit<FunctionAuthRecord, 'timestamp'>): void;
+    snapshot(): {
+        counters: {
+            calls: {
+                total: number;
+                failed: number;
+            };
+            uploads: {
+                total: number;
+                failed: number;
+                bytes: number;
+            };
+            downloads: {
+                total: number;
+                missed: number;
+                bytes: number;
+            };
+            auth: {
+                total: number;
+                denied: number;
+            };
+        };
+        history: {
+            calls: FunctionCallRecord[];
+            uploads: FunctionUploadRecord[];
+            downloads: FunctionDownloadRecord[];
+            auth: FunctionAuthRecord[];
+        };
+    };
+};
+export type FunctionsStatusTracker = ReturnType<typeof createFunctionsStatusTracker>;
+/** The shared instance every functions surface records into. */
+export declare const functionsStatusTracker: {
+    recordCall(record: Omit<FunctionCallRecord, 'timestamp'>): void;
+    recordUpload(record: Omit<FunctionUploadRecord, 'timestamp'>): void;
+    recordDownload(record: Omit<FunctionDownloadRecord, 'timestamp'>): void;
+    recordAuth(record: Omit<FunctionAuthRecord, 'timestamp'>): void;
+    snapshot(): {
+        counters: {
+            calls: {
+                total: number;
+                failed: number;
+            };
+            uploads: {
+                total: number;
+                failed: number;
+                bytes: number;
+            };
+            downloads: {
+                total: number;
+                missed: number;
+                bytes: number;
+            };
+            auth: {
+                total: number;
+                denied: number;
+            };
+        };
+        history: {
+            calls: FunctionCallRecord[];
+            uploads: FunctionUploadRecord[];
+            downloads: FunctionDownloadRecord[];
+            auth: FunctionAuthRecord[];
+        };
+    };
+};

package/lib/functions/templates.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Files scaffolded into the functions directory.
+ *
+ * `buttress-functions.d.ts` is managed: it is rewritten on every start so the
+ * ambient types always match the running server. The tsconfig and the example
+ * are written only into a directory that holds no functions yet, so a deleted
+ * example never comes back.
+ */
+export declare const TYPES_FILE_NAME = "buttress-functions.d.ts";
+export declare const TSCONFIG_FILE_NAME = "tsconfig.json";
+export declare const EXAMPLE_FILE_NAME = "_example.ts";
+export declare const TYPES_TEMPLATE = "// Generated by @fugood/buttress-server \u2014 do not edit.\n// Rewritten on every server start to match the running version.\n//\n// Local functions are EXPERIMENTAL: this contract may change between\n// releases \u2014 after a server upgrade, re-read this file for the current shape.\n\n/** Result of `context.spawn(...)`. */\ntype ButtressSpawnResult = {\n  /** Exit code, or null when the process was killed by a signal. */\n  code: number | null\n  signal: NodeJS.Signals | null\n  stdout: string | Buffer\n  stderr: string | Buffer\n  /** True when output hit `maxBuffer` and capture stopped early. */\n  truncated: boolean\n}\n\ntype ButtressSpawnOptions = {\n  cwd?: string\n  /** Merged over the server's own environment. */\n  env?: Record<string, string | undefined>\n  /** Written to stdin, which is then closed. */\n  input?: string | Uint8Array\n  /** 'utf8' (default) yields strings; 'buffer' yields Buffers. */\n  encoding?: 'utf8' | 'buffer'\n  /** Per-stream capture cap in bytes (default 8MB). */\n  maxBuffer?: number\n  onStdout?: (chunk: Buffer) => void\n  onStderr?: (chunk: Buffer) => void\n}\n\ntype ButtressCompletionResult = {\n  content: string\n  reasoning_content?: string\n  tool_calls?: any[]\n  interrupted?: boolean\n  usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number }\n}\n\ntype ButtressFunctionContext = {\n  /**\n   * Run a child process. Resolves once it exits \u2014 a non-zero `code` is a\n   * normal resolution, so check it yourself. Rejects only when the process\n   * cannot be started. Every process a call spawns is killed when the call\n   * ends or times out.\n   */\n  spawn: (\n    command: string,\n    args?: string[],\n    options?: ButtressSpawnOptions,\n  ) => Promise<ButtressSpawnResult>\n\n  buttress: {\n    /**\n     * Run a chat completion on this server's LLM generator. `messages` are\n     * rendered with the model's own chat template, and thinking is off unless\n     * you pass `enable_thinking: true` (which fills `reasoning_content`).\n     */\n    completion: (options: {\n      /** Configured `[[generators]]` model; defaults to the first one. */\n      model?: string\n      messages?: { role: string; content: any }[]\n      prompt?: string\n      /** Cap on generated tokens. Unbounded when omitted. */\n      max_tokens?: number\n      temperature?: number\n      /** Emit the model's reasoning into `reasoning_content` (default false). */\n      enable_thinking?: boolean\n      /** Called for every streamed token event. */\n      onToken?: (event: { token?: string; content?: string; [key: string]: any }) => void\n      /** Any other backend sampling option (`top_p`, `stop`, `tools`, \u2026). */\n      [param: string]: any\n    }) => Promise<ButtressCompletionResult>\n\n    /** Transcribe audio with this server's STT generator. */\n    transcribe: (options: {\n      /** Must match a configured STT model (`repo_id` or `repo_id:filename`). */\n      model?: string\n      filePath?: string\n      audioData?: Uint8Array | Buffer\n      options?: Record<string, any>\n    }) => Promise<any>\n\n    /**\n     * Synthesize speech with this server's TTS generator (onnx-tts). The WAV\n     * is written into `tempDir`; return `fileUrl(path)` to let callers\n     * download it.\n     */\n    synthesize: (options: {\n      /** Must match a configured TTS model when given. */\n      model?: string\n      text: string\n      /** Backend options; `options.speaker` picks a registered voice. */\n      options?: Record<string, any>\n    }) => Promise<{ path: string; sampling_rate: number; channels: number }>\n  }\n\n  fetch: typeof fetch\n  /** Server-side log, prefixed with the function name. */\n  log: (...args: unknown[]) => void\n  /** Emit a progress event. Delivered only to SSE callers; a no-op otherwise. */\n  emit: (event: string, data?: unknown) => void\n  /** Aborted when the call times out or the caller disconnects. */\n  signal: AbortSignal\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table from the server config. */\n  config: Record<string, any>\n  /** Per-call scratch directory, created on first access. */\n  tempDir: string\n  /**\n   * Download URL path (`/functions/files/...`) for a file inside `tempDir`;\n   * relative input resolves against it. Callers fetch the URL with the same\n   * auth as any function call. Scratch dirs are swept after ~24h.\n   */\n  fileUrl: (target: string) => string\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Helper libraries: _, lodash, moment, math, mathjs, voca, chroma, json5, qs, bytes, ms, nanoid, md5. */\n  libs: Record<string, any>\n}\n\ntype ButtressFunctionMeta = {\n  /** Shown to MCP clients in `tools/list`. */\n  description?: string\n  /** JSON Schema for the input object, passed to MCP verbatim. */\n  parameters?: Record<string, any>\n  /** Deadline for this function: ms, or a duration string like \"10m\". */\n  timeout?: number | string\n}\n\n// --- Custom auth ------------------------------------------------------------\n// Drop an `_auth.ts` into this directory to gate the /functions endpoints\n// with your own logic. It exports the same shape as a function file:\n//\n//   export const meta: ButtressAuthMeta = { mode: 'both' }\n//   export default async function (\n//     request: ButtressAuthRequest,\n//     context: ButtressAuthContext,\n//   ): Promise<ButtressAuthResult> { ... }\n//\n// While an `_auth` file exists but fails to load, every call is rejected.\n\ntype ButtressAuthMeta = {\n  /**\n   * 'both' (default): runs after the built-in workspace auth passes, as an\n   * extra gate. 'override': replaces workspace auth \u2014 this function is the\n   * only authority (a presented workspace token is still verified into\n   * `request.workspaceAuth` so you can choose to honor it).\n   */\n  mode?: 'override' | 'both'\n}\n\ntype ButtressAuthRequest = {\n  method: string\n  path: string\n  /** Function name for `GET`/`POST /functions/<name>`; undefined for list and MCP. */\n  name?: string\n  headers: Record<string, string | undefined>\n  query: Record<string, string | undefined>\n  /** Raw bearer token (Authorization header or `?token=`), if any. */\n  token: string | null\n  workspaceAuth: {\n    /** Whether this server is bound to a workspace. */\n    bound: boolean\n    /** Whether the caller presented a valid workspace access token. */\n    authenticated: boolean\n    identity: {\n      workspaceId: string\n      subjectType: 'ws' | 'dev'\n      subjectId: string\n      jti?: string\n      exp: number\n    } | null\n  }\n}\n\ntype ButtressAuthContext = {\n  /** Server-side log, prefixed with \"_auth\". */\n  log: (...args: unknown[]) => void\n  fetch: typeof fetch\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table, same as `context.config` in functions. */\n  config: Record<string, any>\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Same helper libraries functions get. */\n  libs: Record<string, any>\n}\n\n/** Only `true` (or `{ ok: true }`) allows the request; anything else denies. */\ntype ButtressAuthResult =\n  | boolean\n  | {\n      ok: boolean\n      /** Response status for a denial, 400-499 (default 403). */\n      status?: number\n      /** Message returned to the caller on denial. */\n      error?: string\n    }\n";
+export declare const TSCONFIG_TEMPLATE = "{\n  // Editor support for Buttress local functions.\n  // Install @types/node here for typings on \"node:*\" imports.\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"Bundler\",\n    \"lib\": [\"ES2023\"],\n    \"strict\": true,\n    \"noEmit\": true,\n    \"allowJs\": true,\n    \"skipLibCheck\": true\n  },\n  \"include\": [\"**/*.ts\", \"**/*.js\"]\n}\n";
+export declare const EXAMPLE_TEMPLATE = "// Example Buttress local function.\n//\n// Rename (or copy) this file to expose it: files starting with \"_\" are\n// ignored. The tool name is the file name \u2014 \"video-duration.ts\" becomes the\n// tool \"video-duration\", callable over MCP, at POST /functions/video-duration\n// with a JSON body, and at GET /functions/video-duration?path=... with the\n// input in the query string.\n\nexport const meta: ButtressFunctionMeta = {\n  description: 'Report the duration of a video file using ffprobe',\n  parameters: {\n    type: 'object',\n    properties: {\n      path: { type: 'string', description: 'Absolute path to a video file' },\n    },\n    required: ['path'],\n  },\n  timeout: '2m',\n}\n\nexport default async function (\n  { path }: { path: string },\n  context: ButtressFunctionContext,\n): Promise<{ seconds: number }> {\n  const { code, stdout, stderr } = await context.spawn('ffprobe', [\n    '-v',\n    'error',\n    '-show_entries',\n    'format=duration',\n    '-of',\n    'default=noprint_wrappers=1:nokey=1',\n    path,\n  ])\n\n  if (code !== 0) throw new Error(`ffprobe failed (${code}): ${stderr}`)\n\n  return { seconds: Number(String(stdout).trim()) }\n}\n";

package/lib/functions/transpile.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Runtime transpilation of user-authored local function files.
+ *
+ * Two passes, both synchronous native (napi) calls:
+ *   1. `transformSync` strips TypeScript types (no-op for plain JS).
+ *   2. `moduleRunnerTransformSync` rewrites ESM into a flat body that reads and
+ *      writes `__vite_ssr_*` bindings, which `vm.runInContext` can evaluate on
+ *      plain Node. `vm.SourceTextModule` (real ESM in a vm) is unavailable on
+ *      Node without `--experimental-vm-modules`, and `bin/bricks-buttress` runs
+ *      `node lib/index.mjs` whenever Bun is absent — so this form is the only
+ *      one that behaves identically on both runtimes.
+ *
+ * The `moduleRunnerTransformSync` output contract (Vite's module runner) is
+ * implemented by `loader.ts`. Keep both files in sync; this module is the only
+ * place that touches oxc so swapping transpilers stays a one-file change.
+ */
+export type TranspileResult = {
+    code: string;
+    /** Static import specifiers, as written in the source. */
+    deps: string[];
+    dynamicDeps: string[];
+};
+export declare const transpileModule: (file: string, source: string) => TranspileResult;