@briancray/belte 0.3.0 → 0.4.0

package/src/lib/server/runtime/createServer.ts

@@ -1,5 +1,4 @@
 import type { BunRequest, Server } from 'bun'
-import { Glob } from 'bun'
 import type { Component } from 'svelte'
 import { render } from 'svelte/server'
 import App from '../../../App.svelte'
@@ -29,6 +28,8 @@ import { cacheControlForAsset } from './cacheControlForAsset.ts'
 import { containsTraversal } from './containsTraversal.ts'
 import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
+import { globToPathSet } from './globToPathSet.ts'
+import { logBrowserOnlyRoutes } from './logBrowserOnlyRoutes.ts'
 import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifests.ts'
 import { requestContext } from './requestContext.ts'
 import { safeJsonForScript } from './safeJsonForScript.ts'
@@ -58,6 +59,7 @@ function internalErrorResponse(err: unknown): Response {
 
 const IDENTITY_PATH = '/__belte/identity'
 const SOCKETS_PATH = '/__belte/sockets'
+const SOCKETS_REST_PREFIX = '/__belte/sockets/'
 const MCP_PATH = '/__belte/mcp'
 const CLI_PATH = '/__belte/cli'
 const CLI_DOWNLOAD_PREFIX = '/__belte/cli/'
@@ -125,16 +127,23 @@ export async function createServer({
     setMcpResourceServer(createMcpResourceServer({ resourcesDir, mcpResources }))
     const cliName = cliProgramName ?? 'app'
     const cliCwd = process.cwd()
-    const servePublicAsset = createPublicAssetServer({ publicDir, publicAssets })
+    const servePublicAsset = await createPublicAssetServer({ publicDir, publicAssets })
     const layoutPrefixes = layouts ? normalizeLayoutPrefixes(Object.keys(layouts)) : []
 
-    const diskZstdPaths = new Set<string>(
-        !assets && (await Bun.file(`${distDir}/_app`).exists())
-            ? (await Array.fromAsync(new Glob('**/*.zst').scan({ cwd: `${distDir}/_app` }))).map(
-                  (file) => `/_app/${file.replace(/\.zst$/, '')}`,
-              )
-            : [],
-    )
+    /*
+    Snapshot the precompressed `.zst` siblings the build wrote next to each
+    `_app` asset, keyed by the asset's request path, so a zstd-capable
+    client gets the precompressed bytes without on-the-fly compression. Only
+    in disk mode (`belte start` / dev); the compiled binary serves from the
+    embedded `assets` map instead.
+    */
+    const diskZstdPaths = assets
+        ? new Set<string>()
+        : await globToPathSet(
+              `${distDir}/_app`,
+              '**/*.zst',
+              (file) => `/_app/${file.replace(/\.zst$/, '')}`,
+          )
 
     const rpcModuleCache = new Map<string, Promise<AnyRemoteFunction | undefined>>()
     function loadRpc(url: string): Promise<AnyRemoteFunction | undefined> | undefined {
@@ -440,6 +449,17 @@ export async function createServer({
                 }
                 return new Response('Upgrade failed', { status: 400 })
             }
+            /*
+            HTTP face of a socket (`/__belte/sockets/<name>`) — tail over
+            SSE / JSON and publish — for the CLI and MCP. Runs through
+            dispatchRequest so app.handle auth applies, like the rpc paths.
+            The socket name may contain `/` (nested files), so it's the
+            whole remaining pathname, percent-decoded.
+            */
+            if (url.pathname.startsWith(SOCKETS_REST_PREFIX)) {
+                const name = decodeURIComponent(url.pathname.slice(SOCKETS_REST_PREFIX.length))
+                return dispatchRequest(req, {}, async () => socketDispatcher.rest(req, name))
+            }
             if (url.pathname === MCP_PATH && mcp) {
                 return dispatchRequest(req, {}, async () => mcp.handle(req))
             }
@@ -543,5 +563,13 @@ export async function createServer({
     }
 
     log.success(`ready at http://localhost:${server.port}`)
+    /*
+    Diagnostic only, and only under `belte` debug logging — eager-loads the
+    registry to report routes that are browser-only for lack of a schema,
+    making the opt-in nature of the MCP/CLI surfaces visible.
+    */
+    if (logRequests) {
+        void logBrowserOnlyRoutes()
+    }
     return server
 }

package/src/lib/server/runtime/globToPathSet.ts

@@ -0,0 +1,29 @@
+import { Glob } from 'bun'
+
+/*
+Scans `cwd` for files matching `pattern` and returns their request paths as
+a Set, mapping each relative file path to a root-relative URL via `keyFor`.
+Used to snapshot the on-disk asset trees (the `public/` files, the `_app`
+precompressed `.zst` siblings) once at boot so the request path is a Set
+lookup instead of a filesystem stat.
+
+A missing directory makes scan throw ENOENT — swallowed to an empty Set so
+the caller just falls through. This scan-and-catch is also the reliable
+directory existence test: `Bun.file(dir).exists()` returns false for a
+directory, so guarding the scan with it silently yields an empty Set.
+*/
+export async function globToPathSet(
+    cwd: string,
+    pattern: string,
+    keyFor: (file: string) => string,
+    options?: { dot?: boolean },
+): Promise<Set<string>> {
+    try {
+        const files = await Array.fromAsync(
+            new Glob(pattern).scan({ cwd, dot: options?.dot ?? false }),
+        )
+        return new Set(files.map(keyFor))
+    } catch {
+        return new Set()
+    }
+}

package/src/lib/server/runtime/logBrowserOnlyRoutes.ts

@@ -0,0 +1,44 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import { log } from '../../shared/log.ts'
+import { verbRegistry } from '../rpc/verbRegistry.ts'
+import { socketRegistry } from '../sockets/socketRegistry.ts'
+import { ensureRegistriesLoaded } from './registryManifests.ts'
+
+/*
+Surfaces the otherwise-silent consequence of belte's multimodal-by-default
+rule: a verb or socket with no schema never reaches MCP or the CLI, since
+the schema is what makes those surfaces safe to advertise. Loads the full
+registry, then logs (once at boot, only when `belte` debug logging is on
+so it doesn't force eager imports in production) the routes that stay
+browser-only purely for lack of a schema — so the missing matrix cells
+are visible rather than surprising. Best-effort: enumeration failures are
+swallowed since this is diagnostic only.
+*/
+export async function logBrowserOnlyRoutes(): Promise<void> {
+    try {
+        await ensureRegistriesLoaded()
+    } catch {
+        return
+    }
+    const names: string[] = []
+    for (const entry of verbRegistry.values()) {
+        if (
+            entry.clients.browser &&
+            !entry.clients.mcp &&
+            !entry.clients.cli &&
+            !entry.inputSchema
+        ) {
+            names.push(commandNameForUrl(entry.remote.url))
+        }
+    }
+    for (const entry of socketRegistry.values()) {
+        if (entry.clients.browser && !entry.clients.mcp && !entry.clients.cli && !entry.schema) {
+            names.push(entry.socket.name)
+        }
+    }
+    if (names.length > 0) {
+        log.detail(
+            `browser-only (no schema → not on MCP/CLI): ${names.sort().join(', ')} — add a schema to expose them`,
+        )
+    }
+}

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -1,6 +1,10 @@
 import type { ServerWebSocket } from 'bun'
 import { log } from '../../shared/log.ts'
+import { error } from '../error.ts'
+import { json } from '../json.ts'
+import { sse } from '../sse.ts'
 import { lookupSocket } from './lookupSocket.ts'
+import { recentHistory } from './recentHistory.ts'
 import type { SocketClientFrame } from './types/SocketClientFrame.ts'
 import type { SocketRoutes } from './types/SocketRoutes.ts'
 import type { SocketServerFrame } from './types/SocketServerFrame.ts'
@@ -12,6 +16,7 @@ type SocketDispatcher = {
     open(ws: ServerWebSocket<unknown>): void
     message(ws: ServerWebSocket<unknown>, data: string | Buffer): void
     close(ws: ServerWebSocket<unknown>): void
+    rest(req: Request, name: string): Promise<Response>
 }
 
 /*
@@ -154,14 +159,9 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         a number is clamped to the buffer length so the client can ask
         for "as many as available, up to N".
         */
-        const history = entry.snapshotHistory()
-        const replayCount =
-            frame.replay === undefined ? history.length : Math.min(frame.replay, history.length)
-        if (replayCount > 0) {
-            history.slice(history.length - replayCount).forEach((message) => {
-                send(ws, { type: 'msg', socket: frame.socket, message })
-            })
-        }
+        recentHistory(entry, frame.replay).forEach((message) => {
+            send(ws, { type: 'msg', socket: frame.socket, message })
+        })
     }
 
     function handleUnsub(
@@ -225,7 +225,70 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         void ws
     }
 
+    /*
+    HTTP face of the sockets hub at `/__belte/sockets/<name>`, for the CLI
+    and MCP (which can't speak the ws multiplex protocol):
+
+      GET  text/event-stream → live SSE stream; `?tail=N` replays the last
+           N buffered messages before tailing live (default 0 = live only).
+      GET  otherwise         → JSON array of the recent history buffer
+           (`?tail=N` caps it; default all).
+      POST                   → publish the JSON body, gated by the socket's
+           clientPublish policy and validated against its schema.
+
+    Loads the socket module on first hit (same cache the ws path uses) so
+    its defineSocket call populates the registry.
+    */
+    async function rest(req: Request, name: string): Promise<Response> {
+        const loader = ensureLoaded(name)
+        if (!loader) {
+            return error(404)
+        }
+        try {
+            await loader
+        } catch (loadError) {
+            log.error(loadError)
+            return error(500, 'socket failed to load')
+        }
+        const entry = lookupSocket(name)
+        if (!entry) {
+            return error(404)
+        }
+        const tailParam = new URL(req.url).searchParams.get('tail')
+        const count = tailParam !== null ? Number(tailParam) : undefined
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            if ((req.headers.get('accept') ?? '').includes('text/event-stream')) {
+                return sse(entry.socket.tail(count ?? 0))
+            }
+            return json(recentHistory(entry, count))
+        }
+        if (req.method === 'POST') {
+            if (!entry.allowClientPublish) {
+                return error(403, 'publishing not allowed')
+            }
+            let message: unknown
+            try {
+                message = await req.json()
+            } catch {
+                return error(400, 'body must be JSON')
+            }
+            try {
+                // publish() validates against the socket schema and throws on a bad payload.
+                entry.socket.publish(message)
+            } catch (publishError) {
+                return error(
+                    422,
+                    publishError instanceof Error ? publishError.message : String(publishError),
+                )
+            }
+            return json({ ok: true })
+        }
+        return error(405, undefined, { headers: { Allow: 'GET, POST' } })
+    }
+
     return {
+        rest,
+
         open(ws) {
             connections.set(ws, { subToSocket: new Map(), socketSubs: new Map() })
         },

package/src/lib/server/sockets/defineSocket.ts

@@ -29,7 +29,13 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
     const ttl = opts.ttl
     const schema = opts.schema
     const jsonSchema = opts.jsonSchema
-    const clients = resolveClientFlags(opts.clients, schema !== undefined)
+    /*
+    A schema makes the socket's payload safe to advertise to non-browser
+    surfaces, so it flips mcp/cli on by default — exposing the `tail` read
+    tool (and `publish` when clientPublish is set). Explicit `clients` wins.
+    */
+    const hasSchema = schema !== undefined
+    const clients = resolveClientFlags(opts.clients, { mcp: hasSchema, cli: hasSchema })
     type BufferEntry = { value: T; expiresAt: number | undefined }
     const buffer: BufferEntry[] = []
     const subscribers = new Set<(message: T) => void>()

package/src/lib/server/sockets/recentHistory.ts

@@ -0,0 +1,11 @@
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Recent slice of a socket's history buffer: the last `count` messages, or
+the whole buffer when `count` is undefined. Shared by the sockets HTTP
+`rest()` face and the MCP `<base>-tail` tool so the two can't drift.
+*/
+export function recentHistory(entry: SocketRegistryEntry, count: number | undefined): unknown[] {
+    const history = entry.snapshotHistory()
+    return count === undefined ? history : history.slice(Math.max(0, history.length - count))
+}

package/src/lib/server/sockets/socketOperations.ts

@@ -0,0 +1,35 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import type { SocketOperation } from './types/SocketOperation.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Projects a socket registry entry into the operations it exposes to the
+CLI and MCP. Single source for the naming convention (`<base>-tail` /
+`<base>-publish`), the existence rule (tail always; publish only when the
+socket allows client publishing), and each operation's HTTP face — so the
+CLI manifest builder, the MCP tool list, and the MCP tool dispatcher can't
+disagree about which operations a socket has or what they're called.
+*/
+export function socketOperations(entry: SocketRegistryEntry): SocketOperation[] {
+    const base = commandNameForUrl(entry.socket.name)
+    const restUrl = `/__belte/sockets/${entry.socket.name}`
+    const operations: SocketOperation[] = [
+        {
+            kind: 'tail',
+            name: `${base}-tail`,
+            socketName: entry.socket.name,
+            restUrl,
+            method: 'GET',
+        },
+    ]
+    if (entry.allowClientPublish) {
+        operations.push({
+            kind: 'publish',
+            name: `${base}-publish`,
+            socketName: entry.socket.name,
+            restUrl,
+            method: 'POST',
+        })
+    }
+    return operations
+}

package/src/lib/server/sockets/types/SocketOperation.ts

@@ -0,0 +1,22 @@
+import type { HttpVerb } from '../../rpc/types/HttpVerb.ts'
+
+/*
+One operation a socket exposes to the non-browser surfaces. A socket
+always offers a `tail` (read recent / stream live) and, when
+`clientPublish` is set, a `publish` (send a message). This is the shared
+skeleton — name, kind, HTTP face — that the CLI manifest, the MCP tool
+list, and the MCP dispatcher all read instead of re-deriving the naming
+convention and existence rule independently. Each surface dresses it with
+its own presentation (descriptions, input schema, annotations).
+*/
+export type SocketOperation = {
+    kind: 'tail' | 'publish'
+    // Command/tool name: the socket's command-name base plus `-tail` / `-publish`.
+    name: string
+    // Raw socket name, for the HTTP path and human-facing descriptions.
+    socketName: string
+    // HTTP face of the operation: `/__belte/sockets/<name>`.
+    restUrl: string
+    // GET for tail, POST for publish.
+    method: HttpVerb
+}

package/src/lib/server/sse.ts

@@ -24,6 +24,7 @@ EventSource surfaces this via its `error` listener and `subscribe()`
 maps it to the entry's `error` field.
 */
 import { NO_STORE } from '../shared/cacheControlValues.ts'
+import { sseErrorFrame } from '../shared/sseErrorFrame.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
 import { streamFromIterator } from './runtime/streamFromIterator.ts'
 import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
@@ -36,7 +37,7 @@ export function sse<Frame>(
 ): TypedResponse<Frame> {
     const body = streamFromIterator(iterable, {
         encodeFrame: (value) => `data: ${JSON.stringify(value)}\n\n`,
-        encodeError: (message) => `event: error\ndata: ${JSON.stringify({ message })}\n\n`,
+        encodeError: (message) => sseErrorFrame.encode(message),
         keepaliveMs: KEEPALIVE_INTERVAL_MS,
         keepalivePayload: ': keepalive\n\n',
     })

package/src/lib/shared/buildRpcRequest.ts

@@ -1,4 +1,5 @@
 import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import { carriesBodyArgs } from './carriesBodyArgs.ts'
 
 /*
 Builds the Request a verb helper uses to invoke its handler. Same shape on
@@ -27,7 +28,7 @@ export function buildRpcRequest({
     headers?: Headers
 }): Request {
     const requestHeaders = headers ?? new Headers()
-    if (method === 'GET' || method === 'DELETE' || method === 'HEAD') {
+    if (!carriesBodyArgs(method)) {
         const target = appendQuery(method, url, args)
         return new Request(new URL(target, baseUrl).href, { method, headers: requestHeaders })
     }

package/src/lib/shared/carriesBodyArgs.ts

@@ -0,0 +1,13 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+
+/*
+Whether a verb carries its args in the request body (POST/PUT/PATCH) vs
+on the query string (GET/DELETE/HEAD). Single source for the split so the
+synthesized Request (buildRpcRequest), the handler-side parse (parseArgs),
+the cache key (keyForRemoteCall), and the OpenAPI doc can't disagree.
+*/
+const BODY_METHODS = new Set<HttpVerb>(['POST', 'PUT', 'PATCH'])
+
+export function carriesBodyArgs(method: HttpVerb): boolean {
+    return BODY_METHODS.has(method)
+}

package/src/lib/shared/isReadOnlyMethod.ts

@@ -0,0 +1,14 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+
+/*
+Read-only (safe) HTTP methods — they don't mutate server state. Belte
+uses this to decide which verbs auto-expose to MCP: reads flip MCP on
+when a schema is present, mutations require an explicit `clients.mcp`
+opt-in so a model can't delete/overwrite data just because the handler
+carries a schema. Also feeds the MCP tool `readOnlyHint` annotation.
+*/
+const READ_ONLY_METHODS = new Set<HttpVerb>(['GET', 'HEAD'])
+
+export function isReadOnlyMethod(method: HttpVerb): boolean {
+    return READ_ONLY_METHODS.has(method)
+}

package/src/lib/shared/isStreamingResponse.ts

@@ -0,0 +1,11 @@
+import { STREAMING_CONTENT_TYPES } from './streamingContentTypes.ts'
+
+/*
+Whether a Response carries a streaming body (SSE / JSONL / NDJSON) by its
+Content-Type, so callers drain it frame-by-frame instead of buffering.
+Shared by the CLI print path and the MCP tool dispatcher.
+*/
+export function isStreamingResponse(response: Response): boolean {
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    return STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))
+}

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

@@ -1,5 +1,6 @@
 import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
 import { canonicalJson } from './canonicalJson.ts'
+import { carriesBodyArgs } from './carriesBodyArgs.ts'
 
 /*
 Derives a cache key from a verb-defined remote function and its args. The
@@ -14,7 +15,7 @@ URLSearchParams).
 */
 export function keyForRemoteCall(method: HttpVerb, url: string, args: unknown): string {
     const prefix = `${method} ${url}`
-    if (method === 'GET' || method === 'DELETE' || method === 'HEAD') {
+    if (!carriesBodyArgs(method)) {
         if (args && typeof args === 'object' && !Array.isArray(args)) {
             const record = args as Record<string, unknown>
             const keys = Object.keys(record).sort()

package/src/lib/shared/resolveClientFlags.ts

@@ -2,17 +2,19 @@ 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.
+always defaults to true (the historical surface). The mcp/cli auto-on
+defaults are decided by the caller and passed in, since the safe default
+differs per declaration: a read-only verb may auto-expose to MCP while a
+mutating one must not, and sockets gate differently again. Explicit
+values in `flags` always win over the computed defaults.
 */
 export function resolveClientFlags(
     flags: Partial<ClientFlags> | undefined,
-    hasSchema: boolean,
+    defaults: { mcp: boolean; cli: boolean },
 ): ClientFlags {
     return {
         browser: flags?.browser ?? true,
-        mcp: flags?.mcp ?? hasSchema,
-        cli: flags?.cli ?? hasSchema,
+        mcp: flags?.mcp ?? defaults.mcp,
+        cli: flags?.cli ?? defaults.cli,
     }
 }

package/src/lib/shared/responseErrorText.ts

@@ -0,0 +1,9 @@
+/*
+Human-readable message for a non-2xx Response: `status statusText: body`.
+Shared by the CLI error path and the MCP tool result so the two frame a
+failed request identically. Consumes the body, so call only on a response
+you're done with.
+*/
+export async function responseErrorText(response: Response): Promise<string> {
+    return `${response.status} ${response.statusText}: ${await response.text()}`
+}

package/src/lib/shared/sseErrorFrame.ts

@@ -0,0 +1,29 @@
+/*
+The in-band error sentinel for an SSE stream: when a handler's generator
+throws, `sse()` emits an `event: error` frame whose data is `{ message }`,
+and `streamResponse` re-throws it on the consumer side. Encoder and decoder
+live together here so the sentinel (event name + payload shape) has one
+definition and can't drift between the two ends of the wire.
+*/
+export const sseErrorFrame = {
+    // Full `event: error` frame for a thrown message, including the SSE delimiters.
+    encode(message: string): string {
+        return `event: error\ndata: ${JSON.stringify({ message })}\n\n`
+    },
+    /*
+    The message carried by an error frame, or undefined when `event` isn't
+    the error sentinel. Falls back to the raw data when it isn't the JSON
+    the encoder produces.
+    */
+    decode(event: string, data: string): string | undefined {
+        if (event !== 'error') {
+            return undefined
+        }
+        try {
+            const decoded = JSON.parse(data) as { message?: string }
+            return decoded?.message ?? 'sse stream error'
+        } catch {
+            return data || 'sse stream error'
+        }
+    },
+}