@belte/belte 0.19.0

package/src/lib/shared/jsonSchemaForPromptArguments.ts

@@ -0,0 +1,29 @@
+import type { PromptArgument } from './types/PromptArgument.ts'
+
+/*
+Turns a markdown prompt's frontmatter `arguments` list into the JSON
+Schema the MCP dispatcher advertises in `prompts/list` (top-level string
+properties + a `required` array). Prompt arguments are always strings —
+MCP fills them from model output — so every property is `{ type: 'string' }`.
+Returns undefined for an argument-less prompt so the generated module
+omits the field entirely.
+*/
+export function jsonSchemaForPromptArguments(
+    args: PromptArgument[],
+): Record<string, unknown> | undefined {
+    if (args.length === 0) {
+        return undefined
+    }
+    const properties = Object.fromEntries(
+        args.map((arg) => [
+            arg.name,
+            { type: 'string', ...(arg.description ? { description: arg.description } : {}) },
+        ]),
+    )
+    const required = args.filter((arg) => arg.required).map((arg) => arg.name)
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    }
+}

package/src/lib/shared/jsonSchemaForSchema.ts

@@ -0,0 +1,32 @@
+import type { StandardSchemaV1 } from './types/StandardSchemaV1.ts'
+
+const OPAQUE = { type: 'object', additionalProperties: true } as const
+
+/*
+Resolves a JSON Schema for an MCP tool's `inputSchema`, an OpenAPI body, a CLI
+flag set, or the bundle setup form. Probes the schema's own projection:
+
+  1. `schema.toJsonSchema()` (Arktype 2+)
+  2. `schema.toJSONSchema()` (Zod 4, Effect Schema, or a withJsonSchema wrap)
+  3. Opaque object — the surface still works, the consumer just gets no shape hint
+
+Schemas whose library exposes neither carry one via withJsonSchema. Returns a
+fresh object each call; callers can mutate (e.g. add a description) without
+aliasing the schema's own.
+*/
+export function jsonSchemaForSchema(schema: StandardSchemaV1 | undefined): Record<string, unknown> {
+    if (!schema) {
+        return { ...OPAQUE }
+    }
+    const candidate = schema as unknown as {
+        toJsonSchema?: () => Record<string, unknown>
+        toJSONSchema?: () => Record<string, unknown>
+    }
+    if (typeof candidate.toJsonSchema === 'function') {
+        return { ...candidate.toJsonSchema() }
+    }
+    if (typeof candidate.toJSONSchema === 'function') {
+        return { ...candidate.toJSONSchema() }
+    }
+    return { ...OPAQUE }
+}

package/src/lib/shared/jsonlErrorFrame.ts

@@ -0,0 +1,24 @@
+/*
+The in-band error sentinel for a JSONL/NDJSON stream: when a handler's
+generator throws, `jsonl()` emits a final `{"$error":"<message>"}` line,
+and `streamResponse` re-throws it on the consumer side. Encoder and decoder
+live together here so the sentinel field has one definition and can't drift
+between the two ends of the wire.
+*/
+export const jsonlErrorFrame = {
+    // Error line for a thrown message, including the trailing newline.
+    encode(message: string): string {
+        return `${JSON.stringify({ $error: message })}\n`
+    },
+    // The message carried by a parsed line, or undefined when it isn't the error sentinel.
+    decode(parsed: unknown): string | undefined {
+        if (
+            parsed &&
+            typeof parsed === 'object' &&
+            typeof (parsed as { $error?: unknown }).$error === 'string'
+        ) {
+            return (parsed as { $error: string }).$error
+        }
+        return undefined
+    },
+}

package/src/lib/shared/keyForRemoteCall.ts

@@ -0,0 +1,29 @@
+import { canonicalJson } from './canonicalJson.ts'
+import { carriesBodyArgs } from './carriesBodyArgs.ts'
+import { queryStringFromArgs } from './queryStringFromArgs.ts'
+import type { HttpVerb } from './types/HttpVerb.ts'
+
+/*
+Derives a cache key from a verb-defined remote function and its args. The
+prefix is `${method} ${url}` where `url` is the route template. GET/DELETE/HEAD
+serialise args onto the URL as `?key=value` (sorted, via queryStringFromArgs —
+the same encoder buildRpcRequest builds its query with, so the key and the
+synthesized Request can't disagree); POST/PUT/PATCH join args after a space as
+canonical JSON. The verb split mirrors buildRpcRequest exactly.
+*/
+export function keyForRemoteCall(method: HttpVerb, url: string, args: unknown): string {
+    const prefix = `${method} ${url}`
+    if (!carriesBodyArgs(method)) {
+        if (args && typeof args === 'object' && !Array.isArray(args)) {
+            const search = queryStringFromArgs(args as Record<string, unknown>, true)
+            if (search.length > 0) {
+                return `${prefix}?${search}`
+            }
+        }
+        return prefix
+    }
+    if (args === undefined) {
+        return prefix
+    }
+    return `${prefix} ${canonicalJson(args)}`
+}

package/src/lib/shared/lastConnectionPath.ts

@@ -0,0 +1,7 @@
+import { join } from 'node:path'
+import { appDataDir } from './appDataDir.ts'
+
+// Path to the per-program last-connection record, beside the data-dir `.env`.
+export function lastConnectionPath(programName: string): string {
+    return join(appDataDir(programName), 'last-connection.json')
+}

package/src/lib/shared/loadEnvFile.ts

@@ -0,0 +1,17 @@
+import { readEnvFile } from './readEnvFile.ts'
+
+/*
+Reads a `.env` at `path` and merges each declared var into `process.env`
+only when not already set. Fill-when-unset is the precedence rule the whole
+env stack relies on: layers loaded earlier (shell/ambient, Bun's CWD `.env`)
+win, and later callers back-fill only what's still missing. So a value's
+source is invisible to the app — it reads one flat `process.env` (Bun.env is
+the same object). Missing file is a no-op.
+*/
+export async function loadEnvFile(path: string): Promise<void> {
+    for (const [key, value] of Object.entries(await readEnvFile(path))) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value
+        }
+    }
+}

package/src/lib/shared/loadEnvFromDataDir.ts

@@ -0,0 +1,15 @@
+import { join } from 'node:path'
+import { appDataDir } from './appDataDir.ts'
+import { loadEnvFile } from './loadEnvFile.ts'
+
+/*
+Loads the user's `.env` from the program's per-user data dir into `process.env`.
+This is the cwd-independent config layer — where the connect-screen form writes
+the user's answers, and where a bundle launched via `open` (cwd `/`, so Bun's
+CWD `.env` autoload finds nothing) actually picks up its config. Loaded before
+the binary-dir `.env`, so a user's saved config overrides the shipped default;
+still loses to a shell export or a CWD `.env` (fill-when-unset, see loadEnvFile).
+*/
+export async function loadEnvFromDataDir(programName: string): Promise<void> {
+    await loadEnvFile(join(appDataDir(programName), '.env'))
+}

package/src/lib/shared/loadSvelteConfig.ts

@@ -0,0 +1,18 @@
+import type { SvelteConfig } from './types/SvelteConfig.ts'
+
+const EXTENSIONS = ['js', 'mjs', 'ts'] as const
+
+/*
+Looks for `svelte.config.{js,mjs,ts}` in `cwd` and returns its default export.
+Falls back to an empty config if no file is found.
+*/
+export async function loadSvelteConfig(cwd: string = process.cwd()): Promise<SvelteConfig> {
+    for (const extension of EXTENSIONS) {
+        const path = `${cwd}/svelte.config.${extension}`
+        if (await Bun.file(path).exists()) {
+            const module = await import(path)
+            return module.default as SvelteConfig
+        }
+    }
+    return {}
+}

package/src/lib/shared/log.ts

@@ -0,0 +1,104 @@
+import { isDebugEnabled } from './isDebugEnabled.ts'
+
+const hasBun = typeof Bun !== 'undefined'
+const useColor = hasBun && Bun.enableANSIColors
+const RESET = '\x1b[0m'
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+
+// Wraps `text` in a Bun-resolved ANSI color escape; no-op when colors are disabled or unavailable (browser).
+function paint(color: string, text: string): string {
+    if (!useColor) {
+        return text
+    }
+    return `${Bun.color(color, 'ansi-256')}${text}${RESET}`
+}
+
+// Applies the ANSI dim attribute; no-op when colors are disabled.
+function dim(text: string): string {
+    if (!useColor) {
+        return text
+    }
+    return `${DIM}${text}${RESET}`
+}
+
+// Prefers a full stack trace when the value is an Error so logs include the call site.
+function formatError(value: unknown): string {
+    if (value instanceof Error) {
+        return value.stack ?? value.message
+    }
+    return String(value)
+}
+
+// Maps an HTTP status code to a color that matches the usual server-log convention.
+function colorStatus(status: number): string {
+    if (status >= 500) {
+        return paint('red', String(status))
+    }
+    if (status >= 400) {
+        return paint('yellow', String(status))
+    }
+    if (status >= 300) {
+        return paint('cyan', String(status))
+    }
+    return paint('green', String(status))
+}
+
+// Maps an HTTP method to a color so the request log line is easy to scan.
+function colorMethod(method: string): string {
+    const upper = method.toUpperCase()
+    if (upper === 'GET') {
+        return paint('green', upper)
+    }
+    if (upper === 'POST') {
+        return paint('blue', upper)
+    }
+    if (upper === 'PUT' || upper === 'PATCH') {
+        return paint('yellow', upper)
+    }
+    if (upper === 'DELETE') {
+        return paint('red', upper)
+    }
+    return paint('magenta', upper)
+}
+
+const BELTE = useColor ? `${BOLD}${Bun.color('magenta', 'ansi-256')}[belte]${RESET}` : '[belte]'
+
+// Browser console already has its own DEBUG storage convention, but for the shared logger
+// we honor the same DEBUG env. In the browser `process.env.DEBUG` may not exist.
+const debugEnv = typeof process !== 'undefined' ? process.env.DEBUG : undefined
+
+/*
+Shared logger used by both the build pipeline and the request handler.
+Wraps console.* with ANSI coloring, a `[belte]` prefix, and a per-method/
+per-status palette for `request()`. console.* is the side effect — logging
+is intentionally impure.
+*/
+export const log = {
+    info(message: string): void {
+        console.log(`${BELTE} ${message}`)
+    },
+    warn(message: string): void {
+        console.warn(`${BELTE} ${paint('yellow', message)}`)
+    },
+    error(value: unknown): void {
+        console.error(`${BELTE} ${paint('red', formatError(value))}`)
+    },
+    success(message: string): void {
+        console.log(`${BELTE} ${paint('green', message)}`)
+    },
+    detail(message: string): void {
+        console.log(dim(message))
+    },
+    debug(scope: string, message: string): void {
+        if (!isDebugEnabled(scope, debugEnv)) {
+            return
+        }
+        console.log(`${dim(`[${scope}]`)} ${dim(message)}`)
+    },
+    request(method: string, path: string, status: number, durationMs: number): void {
+        console.log(
+            `${colorMethod(method)} ${path} ${colorStatus(status)} ${dim(`${durationMs.toFixed(2)}ms`)}`,
+        )
+    },
+}

package/src/lib/shared/manifestModule.ts

@@ -0,0 +1,39 @@
+import { log } from './log.ts'
+
+/*
+Builds one of belte's virtual manifest modules — the `{ key: () => import(...) }`
+map the bundler emits for rpc / sockets / prompts / pages / layouts. They differ
+only in their files, the key derived per file, the import dir, the export name,
+and the log label; this is the single shape they share.
+*/
+export function manifestModule(options: {
+    files: string[]
+    keyForFile: (file: string) => string
+    importDir: string
+    exportName: string
+    /*
+    A plain `resolved N <label>: keys` line at build time, when set. Omitted for
+    manifests whose contents are enumerated once at boot as an aligned table (see
+    logExposedSurfaces) — rpc/sockets/pages/layouts — which both avoids the
+    redundant list and the double-log of manifests (pages/layouts) loaded by both
+    the server and client bundles. prompts/errors have no table, so they pass a
+    label to keep their build-time line.
+    */
+    label?: string
+}): { contents: string; loader: 'js' } {
+    const entries = options.files
+        .toSorted()
+        .map((file) => ({ key: options.keyForFile(file), file }))
+    const lines = entries
+        .map(
+            ({ key, file }) =>
+                `    ${JSON.stringify(key)}: () => import(${JSON.stringify(`${options.importDir}/${file}`)}),`,
+        )
+        .join('\n')
+    if (options.label && entries.length > 0) {
+        log.info(
+            `resolved ${entries.length} ${options.label}: ${entries.map((entry) => entry.key).join(', ')}`,
+        )
+    }
+    return { contents: `export const ${options.exportName} = {\n${lines}\n}\n`, loader: 'js' }
+}

package/src/lib/shared/memoizeByKey.ts

@@ -0,0 +1,24 @@
+/*
+Memoises an async loader keyed by string: the first call for a key starts the
+load and caches its promise; later calls reuse it. `load` returns undefined when
+the key has no loader, which is passed through (and not cached) so the caller can
+treat "unknown key" distinctly from "loaded value". Used by the rpc-module and
+socket-module load caches, which share this exact shape.
+*/
+export function memoizeByKey<T>(
+    load: (key: string) => Promise<T> | undefined,
+): (key: string) => Promise<T> | undefined {
+    const cache = new Map<string, Promise<T>>()
+    return (key) => {
+        const existing = cache.get(key)
+        if (existing) {
+            return existing
+        }
+        const started = load(key)
+        if (!started) {
+            return undefined
+        }
+        cache.set(key, started)
+        return started
+    }
+}

package/src/lib/shared/nearestLayoutPrefix.ts

@@ -0,0 +1,36 @@
+/*
+Given a route URL and a list of directory prefixes that have a
+layout.svelte, returns the deepest prefix that is an ancestor of the route.
+Returns undefined when no layout applies. Implements the "nearest-only"
+resolution from the plan — no stacking.
+*/
+export type NormalizedLayoutPrefix = {
+    prefix: string
+    dir: string
+}
+
+export function normalizeLayoutPrefixes(prefixes: Iterable<string>): NormalizedLayoutPrefix[] {
+    const out: NormalizedLayoutPrefix[] = []
+    for (const prefix of prefixes) {
+        out.push({ prefix, dir: prefix === '/' ? '' : prefix.replace(/^\//, '') })
+    }
+    return out
+}
+
+export function nearestLayoutPrefix(
+    routeUrl: string,
+    layoutPrefixes: NormalizedLayoutPrefix[],
+): string | undefined {
+    const normalized = routeUrl === '/' ? '' : routeUrl.replace(/^\//, '')
+    let best: string | undefined
+    let bestLen = -1
+    for (const { prefix, dir } of layoutPrefixes) {
+        if (dir === '' || normalized === dir || normalized.startsWith(`${dir}/`)) {
+            if (dir.length > bestLen) {
+                best = prefix
+                bestLen = dir.length
+            }
+        }
+    }
+    return best
+}

package/src/lib/shared/normalizeTarget.ts

@@ -0,0 +1,10 @@
+import type { CompileTarget } from './types/CompileTarget.ts'
+
+/*
+Prepends the `bun-` prefix if missing so CLI users can pass either
+`darwin-arm64` or the canonical `bun-darwin-arm64` form to `--target`.
+*/
+export function normalizeTarget(input: string): CompileTarget {
+    const normalized = input.startsWith('bun-') ? input : `bun-${input}`
+    return normalized as CompileTarget
+}

package/src/lib/shared/pageUrlForFile.ts

@@ -0,0 +1,14 @@
+/*
+Maps a page-relative path (under `src/browser/pages/`) to its URL route. Pages are
+folder-based: every leaf is `page.svelte` or `layout.svelte`, and the URL
+is the directory path. Pages mount at the directory path; layouts mount at
+the directory prefix. Dynamic segments keep their `[name]` / `[...rest]`
+shape — translation to Bun's `:name` / `*` happens at server registration
+via toBunRoutePattern; consumers see the readable form in `nav.route`.
+*/
+export function pageUrlForFile(relPath: string): string {
+    const segments = relPath.split('/')
+    segments.pop()
+    const path = segments.filter(Boolean).join('/')
+    return path === '' ? '/' : `/${path}`
+}

package/src/lib/shared/parseBoundedEnvInt.ts

@@ -0,0 +1,20 @@
+/*
+Parses an env string into an integer within [min, max], returning undefined for
+missing, empty, or out-of-range/non-integer input so the caller can fall back to
+a default. A bare Number() turns '' into 0 and 'abc' into NaN, both silently
+wrong; this rejects them instead.
+*/
+export function parseBoundedEnvInt(
+    value: string | undefined,
+    min: number,
+    max: number,
+): number | undefined {
+    if (value === undefined || value.trim() === '') {
+        return undefined
+    }
+    const parsed = Number(value)
+    if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+        return undefined
+    }
+    return parsed
+}

package/src/lib/shared/parseEnv.ts

@@ -0,0 +1,30 @@
+const ENV_LINE = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/
+
+/*
+Parses `.env` text into a key→value record. Skips blanks, comments, and
+malformed lines; strips a single layer of surrounding single or double quotes.
+Intentionally minimal — no variable expansion, escapes, or multi-line. The pure
+counterpart to loadEnvFile (which merges into process.env) and serializeEnv
+(which writes records back), so all three round-trip the same shape.
+*/
+export function parseEnv(text: string): Record<string, string> {
+    const result: Record<string, string> = {}
+    for (const line of text.split('\n')) {
+        if (!line || line.startsWith('#')) {
+            continue
+        }
+        const match = ENV_LINE.exec(line)
+        if (!match) {
+            continue
+        }
+        const [, key, rawValue] = match
+        const trimmed = rawValue?.trim() ?? ''
+        const unquoted =
+            (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))
+                ? trimmed.slice(1, -1)
+                : trimmed
+        result[key as string] = unquoted
+    }
+    return result
+}

package/src/lib/shared/parsePromptMarkdown.ts

@@ -0,0 +1,34 @@
+import type { PromptArgument } from './types/PromptArgument.ts'
+
+export type ParsedPromptMarkdown = {
+    description: string | undefined
+    arguments: PromptArgument[]
+    body: string
+}
+
+// Leading YAML frontmatter block fenced by `---` lines (CRLF tolerant).
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/
+
+/*
+Splits a `src/mcp/prompts/**.md` file into its frontmatter metadata and
+template body. The frontmatter (optional) carries `description` and an
+`arguments` list; everything after the closing `---` is the prompt body,
+interpolated at render time via `{{name}}` placeholders. A file with no
+frontmatter is all body. Parsed with Bun.YAML — the resolver plugin runs
+under Bun, so the native parser is always available at build time.
+*/
+export function parsePromptMarkdown(source: string): ParsedPromptMarkdown {
+    const match = FRONTMATTER.exec(source)
+    if (!match) {
+        return { description: undefined, arguments: [], body: source.trim() }
+    }
+    const frontmatter = (Bun.YAML.parse(match[1]) ?? {}) as {
+        description?: string
+        arguments?: PromptArgument[]
+    }
+    return {
+        description: frontmatter.description,
+        arguments: Array.isArray(frontmatter.arguments) ? frontmatter.arguments : [],
+        body: source.slice(match[0].length).trim(),
+    }
+}

package/src/lib/shared/parseRouteSegments.ts

@@ -0,0 +1,22 @@
+export type RouteSegment =
+    | { kind: 'literal'; value: string }
+    | { kind: 'param'; name: string; catchAll: boolean }
+
+/*
+Splits a belte route URL into typed segments. `[name]` becomes a param,
+`[...rest]` becomes a catch-all param, anything else is a literal. Used
+by toBunRoutePattern (server-side Bun pattern emission) and writeRoutesDts
+(client-side `Routes` type augmentation) so the two consumers can't drift
+on what counts as a param.
+*/
+export function parseRouteSegments(routeUrl: string): RouteSegment[] {
+    return routeUrl.split('/').map((segment) => {
+        if (segment.startsWith('[...') && segment.endsWith(']')) {
+            return { kind: 'param', name: segment.slice(4, -1), catchAll: true }
+        }
+        if (segment.startsWith('[') && segment.endsWith(']')) {
+            return { kind: 'param', name: segment.slice(1, -1), catchAll: false }
+        }
+        return { kind: 'literal', value: segment }
+    })
+}

package/src/lib/shared/prepareRpcModule.ts

@@ -0,0 +1,59 @@
+import { findExportCallSite } from './findExportCallSite.ts'
+import { importNamesToStrip } from './importNamesToStrip.ts'
+import { stripImport } from './stripImport.ts'
+import type { HttpVerb } from './types/HttpVerb.ts'
+
+const VERB_NAMES = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] as const
+const VERB_SET = new Set<string>(VERB_NAMES)
+
+const SINGLE_EXPORT_ERROR =
+    '[belte] $rpc module contains more than one `<VERB>(...)` export — each file must declare exactly one remote function'
+
+export type PreparedRpcModule = {
+    verb: HttpVerb
+    exportName: string
+    rewriteForServer: (url: string) => string
+}
+
+/*
+Scans an `$rpc/**` module once and returns its declared verb + export
+name plus a closure that, given the route URL, emits the server-side
+rewrite (`__belteDefineVerb__("VERB", "<url>", … )` spliced into the
+original source). The single scan replaces the prior separate
+extract + rewrite passes, so the resolver plugin only walks each source
+character-by-character once.
+
+A regex pass would be tidier but it can't tell a `GET` mention inside a
+docstring or template literal from the real call, and it can't follow
+nested generics like `GET<Map<K, V>>(`.
+*/
+export function prepareRpcModule(
+    source: string,
+    importName: string,
+): PreparedRpcModule | undefined {
+    /*
+    The "no barrels" surface places each verb at its own path
+    (`belte/server/GET`, `belte/server/POST`, …) — strip every one so
+    the user's verb import doesn't linger and side-effect-load the
+    stub module into the server bundle. The user may import under the
+    project's chosen name or the canonical package name, so strip both.
+    */
+    const stripped = importNamesToStrip(importName).reduce(
+        (current, name) =>
+            VERB_NAMES.reduce((acc, verb) => stripImport(acc, `${name}/server/${verb}`), current),
+        source,
+    )
+    const site = findExportCallSite(stripped, (ident) => VERB_SET.has(ident), SINGLE_EXPORT_ERROR)
+    if (!site) {
+        return undefined
+    }
+    const verb = site.ident as HttpVerb
+    return {
+        verb,
+        exportName: site.exportName,
+        rewriteForServer(url: string): string {
+            const binding = `__belteDefineVerb__(${JSON.stringify(verb)}, ${JSON.stringify(url)}, `
+            return stripped.slice(0, site.callStart) + binding + stripped.slice(site.parenStart + 1)
+        },
+    }
+}

package/src/lib/shared/prepareSocketModule.ts

@@ -0,0 +1,49 @@
+import { findExportCallSite } from './findExportCallSite.ts'
+import { importNamesToStrip } from './importNamesToStrip.ts'
+import { stripImport } from './stripImport.ts'
+
+const SINGLE_EXPORT_ERROR =
+    '[belte] $sockets module contains more than one `socket(...)` export — each file must declare exactly one socket'
+
+export type PreparedSocketModule = {
+    exportName: string
+    rewriteForServer: (name: string) => string
+}
+
+/*
+Scans a `$sockets/**` module once and returns its declared export name
+plus a closure that, given the socket name, emits the server-side
+rewrite (`__belteDefineSocket__("<name>"[, opts])` spliced into the
+original source). The single scan replaces the prior separate
+extract + rewrite passes, so the resolver plugin only walks each source
+character-by-character once.
+*/
+export function prepareSocketModule(
+    source: string,
+    importName: string,
+): PreparedSocketModule | undefined {
+    /*
+    Strip the user's `socket` import under the project's chosen name and the
+    canonical package name so the dead import can't side-effect-load the
+    socket helper into the server bundle.
+    */
+    const stripped = importNamesToStrip(importName).reduce(
+        (current, name) => stripImport(current, `${name}/server/socket`),
+        source,
+    )
+    const site = findExportCallSite(stripped, (ident) => ident === 'socket', SINGLE_EXPORT_ERROR)
+    if (!site) {
+        return undefined
+    }
+    return {
+        exportName: site.exportName,
+        rewriteForServer(name: string): string {
+            const inner = stripped.slice(site.parenStart + 1, site.parenEnd).trim()
+            const binding =
+                inner.length === 0
+                    ? `__belteDefineSocket__(${JSON.stringify(name)})`
+                    : `__belteDefineSocket__(${JSON.stringify(name)}, ${stripped.slice(site.parenStart + 1, site.parenEnd)})`
+            return stripped.slice(0, site.callStart) + binding + stripped.slice(site.parenEnd + 1)
+        },
+    }
+}

package/src/lib/shared/programNameForPackage.ts

@@ -0,0 +1,14 @@
+/*
+Derives the CLI program/binary name from a package.json `name` field.
+Scoped names (`@scope/tool`) keep only the final segment so the value is
+safe as a filesystem path, tar entry name, and CLI display name — a raw
+`/` would otherwise nest the binary into an unexpected directory and break
+the `/__belte/cli/<platform>` download route's path lookup. Falls back to
+`app` when the name is absent or empty.
+*/
+export function programNameForPackage(name: string | undefined): string {
+    if (name === undefined || name === '') {
+        return 'app'
+    }
+    return name.split('/').pop() || 'app'
+}

package/src/lib/shared/promptNameForFile.ts

@@ -0,0 +1,10 @@
+/*
+Translates a prompt file path under `src/mcp/prompts/` into the prompt's
+MCP name. Strips `.md` and joins nested folder segments with `-` (e.g.
+`code/review.md` → `code-review`) so two prompts with the same stem in
+different folders don't collide and the name stays a single valid MCP
+prompt identifier.
+*/
+export function promptNameForFile(relativePath: string): string {
+    return relativePath.replace(/\.md$/, '').replaceAll('/', '-')
+}