@belte/belte 0.19.0

package/src/lib/server/cli/createTarGz.ts

@@ -0,0 +1,76 @@
+/*
+Minimal ustar tarball writer. Each entry is a 512-byte header followed
+by the content padded to a 512-byte boundary; the archive ends with two
+512-byte zero blocks. After assembly the buffer is gzipped via
+Bun.gzipSync — no external `tar` invocation, no extra deps.
+
+Format constraints:
+  - File names ≤ 100 bytes (we never write longer paths).
+  - Numeric fields are zero-padded octal ASCII strings (POSIX rule).
+  - Checksum is the sum of all header bytes treating the checksum
+    field as spaces; encoded as 6 octal digits + NUL + space.
+*/
+
+type TarEntry = {
+    name: string
+    content: Uint8Array
+    mode?: number
+}
+
+const BLOCK = 512
+const ENC = new TextEncoder()
+
+function writeString(buf: Uint8Array, offset: number, length: number, value: string): void {
+    const bytes = ENC.encode(value)
+    buf.set(bytes.subarray(0, Math.min(bytes.length, length)), offset)
+}
+
+function writeOctal(buf: Uint8Array, offset: number, length: number, value: number): void {
+    // length-1 octal digits + trailing NUL
+    const oct = value.toString(8).padStart(length - 1, '0')
+    writeString(buf, offset, length - 1, oct)
+    buf[offset + length - 1] = 0
+}
+
+function buildHeader(entry: TarEntry): Uint8Array {
+    const header = new Uint8Array(BLOCK)
+    writeString(header, 0, 100, entry.name)
+    writeOctal(header, 100, 8, entry.mode ?? 0o644)
+    writeOctal(header, 108, 8, 0)
+    writeOctal(header, 116, 8, 0)
+    writeOctal(header, 124, 12, entry.content.length)
+    writeOctal(header, 136, 12, Math.floor(Date.now() / 1000))
+    header.fill(0x20, 148, 156)
+    header[156] = 0x30 // '0' = regular file
+    writeString(header, 257, 6, 'ustar\0')
+    writeString(header, 263, 2, '00')
+    // Checksum: sum of all bytes with checksum field treated as spaces.
+    let sum = 0
+    for (let index = 0; index < BLOCK; index++) {
+        sum += header[index] ?? 0
+    }
+    writeOctal(header, 148, 7, sum)
+    header[155] = 0x20 // trailing space after checksum digits
+    return header
+}
+
+/*
+Builds a gzipped tarball from the given entries and returns the bytes.
+Sized eagerly (sum of headers + padded contents + 2 trailing blocks).
+*/
+export function createTarGz(entries: TarEntry[]): Uint8Array {
+    let totalSize = BLOCK * 2 // trailing zero blocks
+    for (const entry of entries) {
+        totalSize += BLOCK
+        totalSize += Math.ceil(entry.content.length / BLOCK) * BLOCK
+    }
+    const tar = new Uint8Array(totalSize)
+    let offset = 0
+    for (const entry of entries) {
+        tar.set(buildHeader(entry), offset)
+        offset += BLOCK
+        tar.set(entry.content, offset)
+        offset += Math.ceil(entry.content.length / BLOCK) * BLOCK
+    }
+    return Bun.gzipSync(tar)
+}

package/src/lib/server/cli/handleCliDownload.ts

@@ -0,0 +1,153 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { exeSuffix } from '../../shared/exeSuffix.ts'
+import { isCompileTarget } from '../../shared/isCompileTarget.ts'
+import { log } from '../../shared/log.ts'
+import { normalizeTarget } from '../../shared/normalizeTarget.ts'
+import { buildEnvContent } from './buildEnvContent.ts'
+import { createTarGz } from './createTarGz.ts'
+import { maxSourceMtime } from './maxSourceMtime.ts'
+
+// The sibling server binary's name for a platform — `server` / `server.exe` — must
+// match what resolveServerBinary() looks for next to the unpacked CLI binary.
+function serverBinaryName(platform: string): string {
+    return `server${exeSuffix(normalizeTarget(platform))}`
+}
+
+/*
+Process-wide per-platform build coalescing. Two concurrent curls for
+the same /__belte/cli/<platform> share one promise; the later requests
+await the same one the first installed. The promise both runs the
+freshness check AND the rebuild, so the map insertion is synchronous
+relative to the first request's entry into the function — no window
+between an `await` and `pendingBuilds.set` for a second concurrent
+request to slip through and fire its own buildCli against the same
+output paths.
+*/
+const pendingBuilds = new Map<string, Promise<string | undefined>>()
+
+async function ensurePlatformBinary(
+    platform: string,
+    programName: string,
+    cwd: string,
+): Promise<string | undefined> {
+    const existing = pendingBuilds.get(platform)
+    if (existing) {
+        return existing
+    }
+    const promise = computeBinary(platform, programName, cwd)
+    pendingBuilds.set(platform, promise)
+    /*
+    Drop the entry after settlement so a later request rebuilds if the
+    source has changed again. Identity-guard so a still-pending entry
+    installed by a follow-up request isn't evicted by ours.
+    */
+    promise.finally(() => {
+        if (pendingBuilds.get(platform) === promise) {
+            pendingBuilds.delete(platform)
+        }
+    })
+    return promise
+}
+
+async function computeBinary(
+    platform: string,
+    programName: string,
+    cwd: string,
+): Promise<string | undefined> {
+    const dir = `${cwd}/dist/cli-thin/${platform}`
+    const binaryPath = `${dir}/${programName}`
+    const serverPath = `${dir}/${serverBinaryName(platform)}`
+    /*
+    On-disk binaries are fresh when both the CLI and its sibling server exist AND
+    the CLI's mtime beats the newest rpc/socket source mtime. The mtime check
+    catches the common dev iteration where the user edits an rpc handler but didn't
+    run `belte cli` again; the server-exists check forces a rebuild for a dist
+    produced before the CLI co-shipped a server. Other source paths (project lib,
+    transitive imports) fall back to manual rebuild.
+    */
+    const binaryFile = Bun.file(binaryPath)
+    const serverFile = Bun.file(serverPath)
+    if ((await binaryFile.exists()) && (await serverFile.exists())) {
+        const binaryMtime = (await binaryFile.stat()).mtimeMs
+        const sourceMtime = await maxSourceMtime(cwd)
+        if (binaryMtime >= sourceMtime) {
+            return binaryPath
+        }
+        log.info(`thin cli for ${platform} is stale — rebuilding`)
+    }
+    try {
+        log.info(`lazy-building cli + server for ${platform}…`)
+        // Lazy-import buildCli so the build pipeline isn't pulled into
+        // production processes that never serve a download.
+        const { buildCli } = await import('../../../buildCli.ts')
+        await buildCli({
+            cwd,
+            platforms: [normalizeTarget(platform)],
+        })
+        return (await binaryFile.exists()) && (await serverFile.exists()) ? binaryPath : undefined
+    } catch (error) {
+        log.error(error)
+        return undefined
+    }
+}
+
+/*
+Handles GET /__belte/cli/<platform> — streams a gzipped tarball
+containing the platform-specific thin binary + a `.env` carrying
+BELTE_APP_URL (and BELTE_APP_TOKEN if the inbound request was authenticated).
+
+Thin binaries live at `dist/cli-thin/<platform>/<programName>`
+(produced by `belte cli` with BELTE_APP_URL set). Missing platforms produce
+404 — the install script reports it, doesn't try to fall back.
+*/
+export async function handleCliDownload(
+    request: Request,
+    platform: string,
+    programName: string,
+    cwd: string,
+): Promise<Response> {
+    /*
+    Validate the URL-supplied platform against the known target set before any
+    filesystem access or lazy build. Without this, an arbitrary `platform`
+    segment flows into `dist/cli-thin/<platform>` paths (a traversal/oracle
+    surface) and a cache miss triggers an expensive cross-compile — so spraying
+    distinct junk strings amplifies into unbounded concurrent builds.
+    */
+    if (!isCompileTarget(normalizeTarget(platform))) {
+        return new Response(`unknown platform: ${platform}`, {
+            status: 404,
+            headers: { 'Cache-Control': NO_STORE },
+        })
+    }
+    const binaryPath = await ensurePlatformBinary(platform, programName, cwd)
+    if (!binaryPath) {
+        return new Response(`unknown platform: ${platform}`, {
+            status: 404,
+            headers: { 'Cache-Control': NO_STORE },
+        })
+    }
+    const appUrl = new URL(request.url).origin
+    const auth = request.headers.get('authorization')
+    const bearer =
+        auth && auth.toLowerCase().startsWith('bearer ') ? auth.slice('bearer '.length) : undefined
+    const envContent = buildEnvContent(appUrl, bearer)
+
+    const serverPath = `${cwd}/dist/cli-thin/${platform}/${serverBinaryName(platform)}`
+    const [binaryBytes, serverBytes] = await Promise.all([
+        Bun.file(binaryPath).bytes(),
+        Bun.file(serverPath).bytes(),
+    ])
+    // Ship the server beside the CLI so `/start` can spawn a local instance.
+    const archive = createTarGz([
+        { name: programName, content: binaryBytes, mode: 0o755 },
+        { name: serverBinaryName(platform), content: serverBytes, mode: 0o755 },
+        { name: '.env', content: new TextEncoder().encode(envContent), mode: 0o644 },
+    ])
+    return new Response(archive, {
+        headers: {
+            'Content-Type': 'application/gzip',
+            'Content-Disposition': `attachment; filename="${programName}-${platform}.tar.gz"`,
+            'Cache-Control': NO_STORE,
+        },
+    })
+}

package/src/lib/server/cli/handleCliInstall.ts

@@ -0,0 +1,37 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { installScript } from './installScript.ts'
+
+/*
+The request host is reflected verbatim into a shell script the user pipes
+to `sh`, so it's constrained to the strict authority charset: letters,
+digits, `.`, `-`, `_`, `:` (port + IPv6 separators), and IPv6 `[` `]`
+brackets. That set excludes every character that could break out of the
+interpolated `URL="…"` line in installScript (`"`, `$`, backtick, `\`,
+whitespace), neutralising shell injection via a crafted Host header
+regardless of how lenient the upstream URL parser is.
+*/
+const SAFE_HOST = /^[A-Za-z0-9._:[\]-]+$/
+
+/*
+Handles GET /__belte/cli — returns the platform-detecting shell script.
+Authoritative URL for the tarball is derived from the inbound request
+(so the script's curl line points at whatever host the user reached us
+on). Program name is the bundler-emitted `belte:cli-name` value.
+*/
+export function handleCliInstall(request: Request, programName: string): Response {
+    const url = new URL(request.url)
+    if (!SAFE_HOST.test(url.host)) {
+        return new Response('Bad Request', {
+            status: 400,
+            headers: { 'Cache-Control': NO_STORE },
+        })
+    }
+    const appUrl = url.origin
+    const script = installScript(appUrl, programName)
+    return new Response(script, {
+        headers: {
+            'Content-Type': 'text/x-shellscript; charset=utf-8',
+            'Cache-Control': NO_STORE,
+        },
+    })
+}

package/src/lib/server/cli/installScript.ts

@@ -0,0 +1,29 @@
+/*
+The shell script returned by `GET /__belte/cli` (no platform). Detects
+uname OS + arch, normalises common arch aliases, then curls the right
+platform-specific tarball and extracts it into `$BELTE_INSTALL_DIR`
+(default `~/.local/bin`). The tarball already contains the `.env` next
+to the binary — no separate config write step in the script.
+
+The script is rendered server-side so `<BELTE_APP_URL>` is the request's own
+origin and the embedded curl URL needs no escaping or quoting beyond
+basic shell hygiene.
+*/
+export function installScript(appUrl: string, programName: string): string {
+    return `#!/usr/bin/env sh
+set -e
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+case "$(uname -m)" in
+  x86_64|amd64)   ARCH=x64 ;;
+  aarch64|arm64)  ARCH=arm64 ;;
+  *)              echo "unsupported architecture: $(uname -m)" >&2 ; exit 1 ;;
+esac
+INSTALL_DIR="\${BELTE_INSTALL_DIR:-$HOME/.local/bin}"
+mkdir -p "$INSTALL_DIR"
+URL="${appUrl.replace(/\/$/, '')}/__belte/cli/\${OS}-\${ARCH}"
+echo "installing ${programName} from $URL into $INSTALL_DIR"
+curl -fsSL "$URL" | tar -xz -C "$INSTALL_DIR"
+echo "installed: $INSTALL_DIR/${programName}"
+echo "ensure $INSTALL_DIR is in your PATH"
+`
+}

package/src/lib/server/cli/maxSourceMtime.ts

@@ -0,0 +1,26 @@
+import { existsSync } from 'node:fs'
+import { Glob } from 'bun'
+
+/*
+Returns the most-recent mtime across every rpc + socket source file in
+the project, or 0 when both directories are absent. The lazy CLI
+download path compares this to the binary's mtime to decide whether to
+rebuild — covers the common dev iteration of "user edited an rpc
+handler" without needing to scan transitively-imported modules. Globs and
+stats run concurrently since each file is independent.
+*/
+export async function maxSourceMtime(cwd: string): Promise<number> {
+    const roots = [`${cwd}/src/server/rpc`, `${cwd}/src/server/sockets`].filter(existsSync)
+    const perRoot = await Promise.all(
+        roots.map(async (root) => {
+            const files = await Array.fromAsync(
+                new Glob('**/*.ts').scan({ cwd: root, onlyFiles: true }),
+            )
+            return files.map((file) => `${root}/${file}`)
+        }),
+    )
+    const mtimes = await Promise.all(
+        perRoot.flat().map(async (path) => (await Bun.file(path).stat()).mtimeMs),
+    )
+    return mtimes.reduce((newest, mtime) => Math.max(newest, mtime), 0)
+}

package/src/lib/server/cookies.ts

@@ -0,0 +1,29 @@
+import { requestContext } from './runtime/requestContext.ts'
+
+/*
+The cookie jar for the in-flight request. Reads parse the inbound `Cookie`
+header; writes (`set` / `delete`) are collected and flushed to the response as
+`Set-Cookie` headers when the handler returns (see runWithRequestScope). Backed
+by Bun's native `CookieMap`, so it's a live `Map<string, string>` plus
+`.set(name, value, options)` carrying the standard attributes (httpOnly, secure,
+sameSite, maxAge, path, …) and `.delete(name)` for expiry:
+
+  const jar = cookies()
+  const session = jar.get('session')                       // read inbound
+  jar.set('session', token, { httpOnly: true, sameSite: 'lax' })
+  jar.delete('session')                                     // expire on the way out
+
+Materialized lazily on first call and cached on the request store, so a request
+that never touches cookies parses nothing and emits no `Set-Cookie`. Throws
+outside a request scope, like request().
+*/
+export function cookies(): Bun.CookieMap {
+    const store = requestContext.getStore()
+    if (!store) {
+        throw new Error(
+            '[belte] cookies() called outside a request scope — it only resolves while an SSR render or rpc handler is in flight',
+        )
+    }
+    store.cookies ??= new Bun.CookieMap(store.req.headers.get('cookie') ?? '')
+    return store.cookies
+}

package/src/lib/server/env.ts

@@ -0,0 +1,50 @@
+import type { StandardSchemaV1 } from '../shared/types/StandardSchemaV1.ts'
+import { envSchemaStore } from './runtime/envSchemaStore.ts'
+
+/*
+Validates the process environment against a Standard Schema and returns the
+typed, parsed config. Built to be called at module top level so a missing or
+malformed variable fails the boot loudly rather than surfacing as `undefined`
+deep inside a handler:
+
+  // src/server/config.ts
+  export const config = env(
+      v.object({ DATABASE_URL: v.string(), STRIPE_KEY: v.string() }),
+  )
+
+Reads `Bun.env` (the process environment plus any `.env` Bun loaded), so any
+Standard Schema library — zod, valibot, arktype — works without an adapter,
+same as the verb helpers. Coercion (e.g. a numeric PORT) lives in the schema.
+
+The schema is registered (envSchemaStore) so the bundle launcher can project
+the first-run setup form from the same declaration. When the launcher imports
+this purely to read that schema it sets `skipValidation`, so env() registers
+and returns without validating Bun.env — boot validation stays the server's.
+
+Validation must be synchronous — boot can't await config — so a schema whose
+`validate` returns a Promise throws. On failure every issue is reported at once
+(path + message) so a misconfigured deploy shows the full list rather than one
+variable per restart.
+*/
+export function env<Schema extends StandardSchemaV1>(
+    schema: Schema,
+): StandardSchemaV1.InferOutput<Schema> {
+    envSchemaStore.schema = schema
+    if (envSchemaStore.skipValidation) {
+        return Bun.env as unknown as StandardSchemaV1.InferOutput<Schema>
+    }
+    const result = schema['~standard'].validate(Bun.env)
+    if (result instanceof Promise) {
+        throw new Error('[belte] env() schema must validate synchronously')
+    }
+    if (result.issues) {
+        const lines = result.issues.map((issue) => {
+            const path = issue.path
+                ?.map((segment) => String(typeof segment === 'object' ? segment.key : segment))
+                .join('.')
+            return path ? `  ${path}: ${issue.message}` : `  ${issue.message}`
+        })
+        throw new Error(`[belte] invalid environment:\n${lines.join('\n')}`)
+    }
+    return result.value
+}

package/src/lib/server/error.ts

@@ -0,0 +1,70 @@
+import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
+
+/*
+Plain-text error Response — clearer than constructing a Response by
+hand with a status and a text body, and shaped so the client's
+HttpError carries the message verbatim (`HttpError.response.text()`
+returns the message, no parsing).
+
+  if (!order) return error(404, 'order not found')
+
+`message` defaults to the status's standard reason phrase when
+omitted (e.g. `error(404)` body = 'Not Found'). The body is
+text/plain so intermediaries don't try to render or sniff it. A final
+`ResponseInit` adds headers (e.g. `Retry-After` on a 429); the positional
+`status` always wins over any `init.status`.
+
+To short-circuit a handler instead of returning, `throw new Error(...)`
+or `throw new HttpError(error(...))` — the framework's `app.handleError`
+hook catches thrown errors. This helper deliberately returns a Response
+rather than throwing one so a single `return error(...)` is the
+expected pattern, with the same control flow as `return json(...)`.
+*/
+
+/*
+Standard reason phrases for the statuses error() is realistically called
+with. Maintained explicitly because Bun's `Response` does not populate
+`statusText` from the status code, so there's no platform table to read.
+Unlisted codes fall back to `HTTP <status>`.
+*/
+const STATUS_TEXT: Record<number, string> = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    409: 'Conflict',
+    410: 'Gone',
+    422: 'Unprocessable Content',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    501: 'Not Implemented',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+}
+
+/*
+Body type is `never` because `error()` only travels the non-2xx path on
+the wire — the caller's `await fn(args)` throws `HttpError` and never
+resolves to this response's body. Returning a TypedResponse<never> lets
+the union of branches in a handler narrow to whatever the success
+branch carries (`TypedResponse<{user}> | TypedResponse<never>` → Return
+= {user}).
+*/
+export function error(status: number, message?: string, init?: ResponseInit): TypedResponse<never> {
+    const body = message ?? STATUS_TEXT[status] ?? `HTTP ${status}`
+    return new Response(
+        body,
+        withResponseDefaults(
+            init,
+            {
+                'Content-Type': 'text/plain; charset=utf-8',
+                'Cache-Control': NO_STORE,
+            },
+            status,
+        ),
+    ) as TypedResponse<never>
+}

package/src/lib/server/json.ts

@@ -0,0 +1,28 @@
+import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
+
+/*
+JSON Response with rpc-friendly defaults — same shape as
+`Response.json(data, init)`, except `Cache-Control: no-store` is set
+unless the caller overrides it. Intermediary caches (browsers, CDNs,
+shared proxies) shouldn't cache rpc replies by default; the framework's
+own per-request cache handles in-process dedupe.
+
+  export const getOrder = GET<{ id: string }>(async ({ id }) =>
+      json(await db.getOrder(id)),
+  )
+
+The return type carries `T` as a phantom brand so the verb helper can
+infer the caller-facing `Return` from the handler body — no need to
+annotate `GET<Args, Return>` just to type the response shape.
+
+For non-default cache policy pass `init.headers`; explicit
+`cache-control` wins over the default.
+*/
+export function json<T>(data: T, init?: ResponseInit): TypedResponse<T> {
+    return Response.json(
+        data,
+        withResponseDefaults(init, { 'Cache-Control': NO_STORE }),
+    ) as TypedResponse<T>
+}

package/src/lib/server/jsonl.ts

@@ -0,0 +1,46 @@
+/*
+Wraps an AsyncIterable<Frame> in a Response whose body is JSON Lines
+(application/jsonl) — one JSON value per line, terminated by `\n`. Used
+inside an rpc handler to turn a generator into a streaming HTTP response
+that `subscribe(fn.stream)(args)` consumes frame-by-frame on the client.
+
+  export const orderFeed = GET<Args>((args) =>
+      jsonl(async function* () {
+          for await (const order of db.watchOrders(args)) yield order
+      }())
+  )
+
+Cancellation flows from the consumer through ReadableStream's `cancel`
+into `iter.return()` so the handler's `for await` exits via its normal
+control path (DB cursors, file handles, etc. get to release in finally).
+
+Errors thrown by the generator are emitted as a final
+`{"$error":"<message>"}` line before the stream closes. The convention
+keeps the format JSON-safe and lets the consumer distinguish "stream
+ended cleanly" from "handler threw" without a side-channel. The full
+error is logged server-side via the framework's error handler — only the
+message crosses the wire.
+*/
+import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
+import { jsonlErrorFrame } from '../shared/jsonlErrorFrame.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { streamFromIterator } from './runtime/streamFromIterator.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
+
+export function jsonl<Frame>(
+    iterable: AsyncIterable<Frame>,
+    init?: ResponseInit,
+): TypedResponse<Frame> {
+    const body = streamFromIterator(iterable, {
+        encodeFrame: (value) => `${JSON.stringify(value)}\n`,
+        encodeError: (message) => jsonlErrorFrame.encode(message),
+    })
+    return new Response(
+        body,
+        withResponseDefaults(init, {
+            'Content-Type': 'application/jsonl; charset=utf-8',
+            'Cache-Control': NO_STORE,
+            'X-Content-Type-Options': 'nosniff',
+        }),
+    ) as TypedResponse<Frame>
+}

package/src/lib/server/prompts/definePrompt.ts

@@ -0,0 +1,20 @@
+import { registerPrompt } from './registerPrompt.ts'
+import type { Prompt } from './types/Prompt.ts'
+import type { PromptOptions } from './types/PromptOptions.ts'
+
+/*
+Builds a Prompt from a name + options. The resolver plugin parses every
+`src/mcp/prompts/<file>.md` and generates a module that calls
+`definePrompt("<name>", { description, jsonSchema, render })`, so the file
+path becomes the prompt's identity. Registers itself so the MCP dispatcher
+can enumerate and render it.
+*/
+export function definePrompt(name: string, opts: PromptOptions): Prompt {
+    const self: Prompt = {
+        name,
+        description: opts.description,
+        render: opts.render,
+    }
+    registerPrompt({ prompt: self, jsonSchema: opts.jsonSchema })
+    return self
+}

package/src/lib/server/prompts/promptRegistry.ts

@@ -0,0 +1,9 @@
+import type { PromptRegistryEntry } from './types/PromptRegistryEntry.ts'
+
+/*
+Process-wide registry of every prompt declared in the app. definePrompt
+inserts on first construction (eagerly when the registry loader walks the
+prompts manifest at MCP boot). The MCP server reads this to build its
+`prompts/list` + `prompts/get` responses.
+*/
+export const promptRegistry = new Map<string, PromptRegistryEntry>()

package/src/lib/server/prompts/registerPrompt.ts

@@ -0,0 +1,6 @@
+import { promptRegistry } from './promptRegistry.ts'
+import type { PromptRegistryEntry } from './types/PromptRegistryEntry.ts'
+
+export function registerPrompt(entry: PromptRegistryEntry): void {
+    promptRegistry.set(entry.prompt.name, entry)
+}

package/src/lib/server/prompts/renderPromptTemplate.ts

@@ -0,0 +1,16 @@
+// `{{name}}` placeholder, surrounding whitespace tolerated, names are
+// word chars or hyphens to match valid MCP argument identifiers.
+const PLACEHOLDER = /\{\{\s*([\w-]+)\s*\}\}/g
+
+/*
+Renders a markdown prompt body by substituting each `{{name}}` placeholder
+with the matching argument value. Missing arguments collapse to an empty
+string — MCP only enforces `required` at the client, so an optional
+argument the model omits should vanish from the text. Called by the
+render closure the resolver plugin generates for every `.md` prompt.
+*/
+export function renderPromptTemplate(template: string, args: Record<string, string>): string {
+    return template.replace(PLACEHOLDER, (_match, key: string) =>
+        args[key] === undefined ? '' : String(args[key]),
+    )
+}

package/src/lib/server/prompts/types/Prompt.ts

@@ -0,0 +1,13 @@
+/*
+An MCP prompt declared by a markdown file under `src/mcp/prompts/`. The
+resolver plugin parses the file's frontmatter + body and generates a call
+to definePrompt, stamping in the `name` from the file path; `render(args)`
+interpolates the body's `{{name}}` placeholders into the single user
+message returned by `prompts/get`. Prompts are MCP-only — there is no
+client-side counterpart, so the shape carries no ClientFlags.
+*/
+export type Prompt = {
+    readonly name: string
+    readonly description: string | undefined
+    render(args: Record<string, string>): string
+}

package/src/lib/server/prompts/types/PromptOptions.ts

@@ -0,0 +1,12 @@
+/*
+Options definePrompt receives for one markdown prompt. The resolver plugin
+generates this object from the file: `description` + `jsonSchema` come from
+the frontmatter (the schema built from the `arguments` list), and `render`
+closes over the parsed body. All of this is server-only — prompts are never
+imported by client code.
+*/
+export type PromptOptions = {
+    description?: string
+    jsonSchema?: Record<string, unknown>
+    render: (args: Record<string, string>) => string
+}

package/src/lib/server/prompts/types/PromptRegistryEntry.ts

@@ -0,0 +1,13 @@
+import type { Prompt } from './Prompt.ts'
+
+/*
+Per-prompt registry record. The MCP dispatcher enumerates this to build
+`prompts/list` (description + arguments from the JSON Schema) and to
+dispatch `prompts/get` (render the body with the caller's arguments).
+jsonSchema stays off the public Prompt shape so the render closure isn't
+burdened with metadata it never reads.
+*/
+export type PromptRegistryEntry = {
+    prompt: Prompt
+    jsonSchema: Record<string, unknown> | undefined
+}

package/src/lib/server/prompts/types/PromptRoutes.ts

@@ -0,0 +1,10 @@
+import type { Prompt } from './Prompt.ts'
+
+/*
+Manifest of prompt-name → module loader. Produced by the resolver plugin
+from each `.md` under src/mcp/prompts/. Each markdown file is transformed
+into a module that registers one Prompt (its `.name` stamped in by the
+generated definePrompt call) on import. The registry loader imports every
+module once so the MCP dispatcher can enumerate the full prompt surface.
+*/
+export type PromptRoutes = Record<string, () => Promise<Record<string, Prompt>>>