@briancray/belte 0.1.0

package/src/lib/shared/jsonSchemaForSchema.ts

@@ -0,0 +1,38 @@
+import type { StandardSchemaV1 } from '../server/rpc/types/StandardSchemaV1.ts'
+
+const OPAQUE = { type: 'object', additionalProperties: true } as const
+
+/*
+Resolves a JSON Schema for an MCP tool's `inputSchema` or a resource's
+payload type. Priority:
+
+  1. Explicit `jsonSchema` field on the verb/socket opts (user-supplied)
+  2. `schema.toJsonSchema()` (Arktype 2+)
+  3. `schema.toJSONSchema()` (Zod 4, Effect Schema, etc.)
+  4. Opaque object — the tool still works, the model just gets no shape hint
+
+Returns a fresh object each call; callers can mutate (e.g. add a
+description) without aliasing.
+*/
+export function jsonSchemaForSchema(
+    schema: StandardSchemaV1 | undefined,
+    jsonSchema: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+    if (jsonSchema) {
+        return { ...jsonSchema }
+    }
+    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/keyForRemoteCall.ts

@@ -0,0 +1,38 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import { canonicalJson } from './canonicalJson.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
+serialise args onto the URL as `?key=value` with keys sorted so the order
+the caller assembled the object doesn't change the key; POST/PUT/PATCH join
+args after a space as canonical JSON. Sorted key/value pairs are walked once
+and concatenated directly so the hot GET-cache path doesn't allocate per
+intermediate (entries / filtered / URLSearchParams).
+*/
+export function keyForRemoteCall(method: HttpVerb, url: string, args: unknown): string {
+    const prefix = `${method} ${url}`
+    if (method === 'GET' || method === 'DELETE') {
+        if (args && typeof args === 'object' && !Array.isArray(args)) {
+            const record = args as Record<string, unknown>
+            const keys = Object.keys(record).sort()
+            let search = ''
+            for (const key of keys) {
+                const value = record[key]
+                if (value === undefined) {
+                    continue
+                }
+                search += search ? '&' : ''
+                search += `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`
+            }
+            if (search.length > 0) {
+                return `${prefix}?${search}`
+            }
+        }
+        return prefix
+    }
+    if (args === undefined) {
+        return prefix
+    }
+    return `${prefix} ${canonicalJson(args)}`
+}

package/src/lib/shared/loadSvelteConfig.ts

@@ -0,0 +1,18 @@
+import type { SvelteConfig } from '../server/runtime/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/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 '../server/runtime/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/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/preparePromptModule.ts

@@ -0,0 +1,36 @@
+import { findExportCallSite } from './findExportCallSite.ts'
+import { stripImport } from './stripImport.ts'
+
+const SINGLE_EXPORT_ERROR =
+    '[belte] prompts module contains more than one `prompt(...)` export — each file must declare exactly one prompt'
+
+export type PreparedPromptModule = {
+    exportName: string
+    rewriteForServer: (name: string) => string
+}
+
+/*
+Scans a `src/server/prompts/**` module once and returns its declared
+export name plus a closure that, given the prompt name, emits the
+server-side rewrite (`__belteDefinePrompt__("<name>", opts)` spliced into
+the original source). Mirrors prepareSocketModule — a single tokenizer
+pass so a `prompt` mention inside a string or comment is left alone.
+*/
+export function preparePromptModule(source: string): PreparedPromptModule | undefined {
+    const stripped = stripImport(source, 'belte/server/prompt')
+    const site = findExportCallSite(stripped, (ident) => ident === 'prompt', 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
+                    ? `__belteDefinePrompt__(${JSON.stringify(name)})`
+                    : `__belteDefinePrompt__(${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/prepareRpcModule.ts

@@ -0,0 +1,51 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import { findExportCallSite } from './findExportCallSite.ts'
+import { stripImport } from './stripImport.ts'
+
+const VERB_NAMES = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] as const
+const VERB_SET = new Set<string>(VERB_NAMES)
+const VERB_IMPORT_PATHS = VERB_NAMES.map((verb) => `belte/server/${verb}`)
+
+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): 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.
+    */
+    const stripped = VERB_IMPORT_PATHS.reduce((current, path) => stripImport(current, path), 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,37 @@
+import { findExportCallSite } from './findExportCallSite.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): PreparedSocketModule | undefined {
+    const stripped = stripImport(source, 'belte/server/socket')
+    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/server/prompts/` into the
+prompt's MCP name. Strips `.ts` and joins nested folder segments with `-`
+(e.g. `code/review.ts` → `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(/\.ts$/, '').replaceAll('/', '-')
+}

package/src/lib/shared/recordRemoteMeta.ts

@@ -0,0 +1,5 @@
+import { remoteMetaStore } from './remoteMetaStore.ts'
+
+export function recordRemoteMeta(promise: Promise<unknown>, getRequest: () => Request): void {
+    remoteMetaStore.set(promise, getRequest)
+}

package/src/lib/shared/remoteMetaStore.ts

@@ -0,0 +1,16 @@
+/*
+WeakMap that records how to obtain the synthesized Request for a verb
+call. The cache layer reads it to populate an entry's stored request
+without rebuilding from scratch.
+
+Stored as a thunk rather than the Request itself so SSR pages that fire
+dozens of in-process verb calls without ever reaching cache() don't pay
+the URL + Headers + Request allocation per call. The thunk memoises its
+own first call inside createRemoteFunction, so cache() and any future
+meta reader see the same Request instance.
+
+method/url/key are intentionally not stored — they're derivable from
+the RemoteFunction itself, and cache() does that derivation
+independently.
+*/
+export const remoteMetaStore = new WeakMap<Promise<unknown>, () => Request>()

package/src/lib/shared/resolveClientFlags.ts

@@ -0,0 +1,18 @@
+import type { ClientFlags } from './types/ClientFlags.ts'
+
+/*
+Fills in the missing keys of a user-supplied `clients` option. Browser
+defaults to true (the historical surface); mcp/cli default to true only
+when a schema is attached, since exposing an unvalidated handler as a
+tool / shell command is a foot-gun.
+*/
+export function resolveClientFlags(
+    flags: Partial<ClientFlags> | undefined,
+    hasSchema: boolean,
+): ClientFlags {
+    return {
+        browser: flags?.browser ?? true,
+        mcp: flags?.mcp ?? hasSchema,
+        cli: flags?.cli ?? hasSchema,
+    }
+}

package/src/lib/shared/rpcUrlForFile.ts

@@ -0,0 +1,19 @@
+/*
+Maps an rpc-relative path (under `src/server/rpc/`) to its URL. Each file
+is one endpoint at `/rpc/<file path>`, dropping the `.ts` extension.
+$rpc URLs are flat function-call endpoints (args go in query or body), so
+bracket-style `[name]` / `[...rest]` segments are rejected — those belong
+in `src/browser/pages/` where they map to dynamic path params.
+*/
+export function rpcUrlForFile(relPath: string): string {
+    const withoutExt = relPath.replace(/\.ts$/, '')
+    const segments = withoutExt.split('/').filter(Boolean)
+    for (const segment of segments) {
+        if (segment.startsWith('[')) {
+            throw new Error(
+                `[belte] src/server/rpc/${relPath} has a dynamic segment '${segment}' — $rpc URLs are flat; pass identifiers via args, not the path`,
+            )
+        }
+    }
+    return `/rpc/${segments.join('/')}`
+}

package/src/lib/shared/setCacheStoreResolver.ts

@@ -0,0 +1,6 @@
+import { cacheStoreSlot } from './cacheStoreSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+export function setCacheStoreResolver(fn: () => CacheStore | undefined): void {
+    cacheStoreSlot.resolver = fn
+}

package/src/lib/shared/socketNameForFile.ts

@@ -0,0 +1,11 @@
+/*
+Translates a socket file path under `src/server/sockets/` into the socket's
+identity used on the wire. The name is the file path minus `.ts` so
+nested paths (e.g. `orders/new.ts`) become `orders/new`. Sockets don't
+need a URL prefix the way rpc routes do — they multiplex over the
+framework-owned `/__belte/sockets` ws and are dispatched by name in the
+registry, not by HTTP path.
+*/
+export function socketNameForFile(relativePath: string): string {
+    return relativePath.replace(/\.ts$/, '')
+}

package/src/lib/shared/streamingContentTypes.ts

@@ -0,0 +1,11 @@
+/*
+Content-Type prefixes belte treats as streaming bodies — SSE for the
+`sse()` helper, JSONL / NDJSON for the `jsonl()` helper. Used by
+decodeResponse to refuse a buffered decode and by streamResponse to
+choose the frame parser.
+*/
+export const STREAMING_CONTENT_TYPES = [
+    'text/event-stream',
+    'application/jsonl',
+    'application/x-ndjson',
+]

package/src/lib/shared/stripImport.ts

@@ -0,0 +1,27 @@
+/*
+Strips the user's `import { … } from '<moduleName>'` declaration from a
+module source. Used by the $rpc / $sockets rewriters to remove the
+verb / `socket` import after its call site has been replaced by the
+runtime-injected binding (defineVerb / defineSocket). Without this
+strip the dead import would still side-effect-load the verb/socket
+helper module into the server bundle for every $rpc / $sockets file.
+
+The braced body is `[^}]*` rather than `[\s\S]*?` so the lazy match
+can't backtrack across a `}` and accidentally swallow a preceding
+import whose `from` clause doesn't match (e.g. stripping
+`import { GET } from 'belte/server/GET'` from a file that also has
+`import { json } from 'belte/server/json'` on the line above). `[^}]`
+includes newlines, so multi-line braced imports like
+  import {
+    GET,
+  } from 'belte/server/GET'
+still match — the body just can't contain another `}` to bound it.
+*/
+export function stripImport(source: string, moduleName: string): string {
+    const escaped = moduleName.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&')
+    const pattern = new RegExp(
+        `^\\s*import\\s*\\{[^}]*\\}\\s*from\\s*['"]${escaped}['"]\\s*;?\\s*$`,
+        'gm',
+    )
+    return source.replace(pattern, '')
+}