@briancray/belte 0.1.0 → 0.2.0

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

@@ -1,3 +1,8 @@
+import {
+    IMMUTABLE_ASSET_CACHE_CONTROL,
+    REVALIDATE_ASSET_CACHE_CONTROL,
+} from '../../shared/cacheControlValues.ts'
+
 /*
 Bun.build emits `[name]-[hash].[ext]` for chunks; hash is alnum and >=8 chars.
 Source maps inherit the same name (e.g. foo-abc12345.js.map), so the suffix may be `.map`.
@@ -11,7 +16,7 @@ Hashed chunk filenames are content-addressed and immutable; everything else
 */
 export function cacheControlForAsset(pathname: string): string {
     if (HASHED.test(pathname)) {
-        return 'public, max-age=31536000, immutable'
+        return IMMUTABLE_ASSET_CACHE_CONTROL
     }
-    return 'public, max-age=0, must-revalidate'
+    return REVALIDATE_ASSET_CACHE_CONTROL
 }

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

@@ -0,0 +1,35 @@
+import { mimeForExtension } from './mimeForExtension.ts'
+
+/*
+A static-asset response's headers depend only on its pathname (extension →
+Content-Type, path → Cache-Control), so each distinct pathname's header bundle
+is built once and reused across every hit on that chunk — avoiding a per-request
+allocation on a cold page load that pulls dozens of files. Each bundle carries
+the plain `base` headers plus a `zstd` variant with `Content-Encoding: zstd`.
+`cacheControlFor` lets callers vary the policy: hashed-aware for `/_app/`,
+fixed for public/.
+*/
+type AssetHeaderBundle = {
+    base: HeadersInit
+    zstd: HeadersInit
+}
+
+export function createAssetHeaderCache(
+    cacheControlFor: (pathname: string) => string,
+): (pathname: string) => AssetHeaderBundle {
+    const cache = new Map<string, AssetHeaderBundle>()
+    return function headersFor(pathname) {
+        const cached = cache.get(pathname)
+        if (cached) {
+            return cached
+        }
+        const base: HeadersInit = {
+            'Content-Type': mimeForExtension(pathname),
+            Vary: 'Accept-Encoding',
+            'Cache-Control': cacheControlFor(pathname),
+        }
+        const bundle: AssetHeaderBundle = { base, zstd: { ...base, 'Content-Encoding': 'zstd' } }
+        cache.set(pathname, bundle)
+        return bundle
+    }
+}

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

@@ -1,9 +1,9 @@
+import { PUBLIC_ASSET_CACHE_CONTROL } from '../../shared/cacheControlValues.ts'
+import { acceptsZstd } from './acceptsZstd.ts'
 import { containsTraversal } from './containsTraversal.ts'
-import { mimeForExtension } from './mimeForExtension.ts'
+import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import type { Assets } from './types/Assets.ts'
 
-const PUBLIC_CACHE_CONTROL = 'public, max-age=3600'
-
 /*
 Serves files from the project's `public/` folder at the site root. Two
 sources, picked at construction:
@@ -25,27 +25,13 @@ export function createPublicAssetServer({
     publicDir: string
     publicAssets?: Assets
 }): (req: Request, url: URL) => Promise<Response | undefined> {
-    const headerCache = new Map<string, { base: HeadersInit; zstd: HeadersInit }>()
-    function headersFor(pathname: string): { base: HeadersInit; zstd: HeadersInit } {
-        const cached = headerCache.get(pathname)
-        if (cached) {
-            return cached
-        }
-        const base: HeadersInit = {
-            'Content-Type': mimeForExtension(pathname),
-            Vary: 'Accept-Encoding',
-            'Cache-Control': PUBLIC_CACHE_CONTROL,
-        }
-        const bundle = { base, zstd: { ...base, 'Content-Encoding': 'zstd' } }
-        headerCache.set(pathname, bundle)
-        return bundle
-    }
+    const headersFor = createAssetHeaderCache(() => PUBLIC_ASSET_CACHE_CONTROL)
 
     return async function servePublicAsset(req, url) {
         if (containsTraversal(req.url)) {
             return undefined
         }
-        const wantsZstd = (req.headers.get('accept-encoding') ?? '').toLowerCase().includes('zstd')
+        const wantsZstd = acceptsZstd(req)
         const { base, zstd } = headersFor(url.pathname)
         if (publicAssets) {
             const compressed = publicAssets[url.pathname]
@@ -55,7 +41,7 @@ export function createPublicAssetServer({
             if (wantsZstd) {
                 return new Response(compressed, { headers: zstd })
             }
-            return new Response(Bun.zstdDecompressSync(compressed), { headers: base })
+            return new Response(await Bun.zstdDecompress(compressed), { headers: base })
         }
         const file = Bun.file(publicDir + url.pathname)
         if (!(await file.exists())) {

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

@@ -23,11 +23,12 @@ import type { RemoteFunction } from '../rpc/types/RemoteFunction.ts'
 import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
 import { createSocketDispatcher } from '../sockets/createSocketDispatcher.ts'
 import type { SocketRoutes } from '../sockets/types/SocketRoutes.ts'
+import { acceptsZstd } from './acceptsZstd.ts'
 import { buildOpenApiSpec } from './buildOpenApiSpec.ts'
 import { cacheControlForAsset } from './cacheControlForAsset.ts'
 import { containsTraversal } from './containsTraversal.ts'
+import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
-import { mimeForExtension } from './mimeForExtension.ts'
 import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifests.ts'
 import { requestContext } from './requestContext.ts'
 import { safeJsonForScript } from './safeJsonForScript.ts'
@@ -36,18 +37,38 @@ import { setActiveServer } from './setActiveServer.ts'
 import type { Assets } from './types/Assets.ts'
 import type { RequestStore } from './types/RequestStore.ts'
 
-function acceptsZstd(req: Request): boolean {
-    return (req.headers.get('accept-encoding') ?? '').toLowerCase().includes('zstd')
-}
-
 function wantsJson(req: Request): boolean {
     return (req.headers.get('accept') ?? '').includes('application/json')
 }
 
+/*
+The framework's default 500 response — a `<pre>` stack dump. Shared by the
+per-request catch and Bun.serve's global error() fallback so the two can't
+drift. Only reached when the app supplies no `handleError` hook.
+*/
+function internalErrorResponse(err: unknown): Response {
+    return new Response(`<pre>${String((err as Error)?.stack ?? err)}</pre>`, {
+        status: 500,
+        headers: {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Cache-Control': NO_STORE,
+        },
+    })
+}
+
+const IDENTITY_PATH = '/__belte/identity'
 const SOCKETS_PATH = '/__belte/sockets'
 const MCP_PATH = '/__belte/mcp'
 const CLI_PATH = '/__belte/cli'
 const CLI_DOWNLOAD_PREFIX = '/__belte/cli/'
+/*
+Unlike the framework's own plumbing routes above (the socket multiplex, MCP
+endpoint, CLI download), the OpenAPI document describes the app's public HTTP
+surface — the /rpc/* verbs — rather than belte internals, so it sits at the
+conventional root path where external tooling and scanners expect to find it
+(/openapi.json, alongside /swagger.json, /.well-known/*) rather than under the
+/__belte/ namespace.
+*/
 const OPENAPI_PATH = '/openapi.json'
 
 type AnyRemoteFunction = RemoteFunction<unknown, unknown>
@@ -105,12 +126,6 @@ export async function createServer({
     const cliName = cliProgramName ?? 'app'
     const cliCwd = process.cwd()
     const servePublicAsset = createPublicAssetServer({ publicDir, publicAssets })
-    /*
-    Forward-declared so the per-request closures below can reference it. The
-    value is assigned by Bun.serve() further down; closures only fire after
-    that, so the read-before-write is safe at runtime.
-    */
-    let server!: Server<unknown>
     const layoutPrefixes = layouts ? normalizeLayoutPrefixes(Object.keys(layouts)) : []
 
     const diskZstdPaths = new Set<string>(
@@ -150,32 +165,8 @@ export async function createServer({
 
     const logRequests = isDebugEnabled('belte')
 
-    /*
-    Header objects for a pathname depend only on the pathname's extension
-    and the immutable HASHED test. Cache them so repeat hits on the same
-    chunk reuse a single frozen header bag instead of allocating per
-    request.
-    */
-    type AssetHeaderBundle = {
-        base: HeadersInit
-        zstd: HeadersInit
-    }
-    const assetHeaderCache = new Map<string, AssetHeaderBundle>()
-    function headersForAsset(pathname: string): AssetHeaderBundle {
-        const cached = assetHeaderCache.get(pathname)
-        if (cached) {
-            return cached
-        }
-        const base: HeadersInit = {
-            'Content-Type': mimeForExtension(pathname),
-            Vary: 'Accept-Encoding',
-            'Cache-Control': cacheControlForAsset(pathname),
-        }
-        const zstd: HeadersInit = { ...base, 'Content-Encoding': 'zstd' }
-        const bundle = { base, zstd }
-        assetHeaderCache.set(pathname, bundle)
-        return bundle
-    }
+    // Per-pathname asset header bundles, hashed-chunk-aware Cache-Control.
+    const headersForAsset = createAssetHeaderCache(cacheControlForAsset)
 
     async function serveStaticAsset(req: Request, url: URL): Promise<Response> {
         /*
@@ -206,7 +197,7 @@ export async function createServer({
             if (wantsZstd) {
                 return new Response(compressed, { headers: zstdHeaders })
             }
-            return new Response(Bun.zstdDecompressSync(compressed), { headers: baseHeaders })
+            return new Response(await Bun.zstdDecompress(compressed), { headers: baseHeaders })
         }
         const diskPath = distDir + url.pathname
         if (wantsZstd && diskZstdPaths.has(url.pathname)) {
@@ -374,9 +365,7 @@ export async function createServer({
         const store: RequestStore = {
             url,
             req,
-            signal: req.signal,
             cache: createCacheStore(),
-            server,
         }
         return requestContext.run(store, async () => {
             const start = logRequests ? Bun.nanoseconds() : 0
@@ -388,16 +377,7 @@ export async function createServer({
                     response = await app.handleError(error, req)
                 } else {
                     log.error(error)
-                    response = new Response(
-                        `<pre>${String((error as Error)?.stack ?? error)}</pre>`,
-                        {
-                            status: 500,
-                            headers: {
-                                'Content-Type': 'text/html; charset=utf-8',
-                                'Cache-Control': NO_STORE,
-                            },
-                        },
-                    )
+                    response = internalErrorResponse(error)
                 }
             }
             if (logRequests) {
@@ -417,7 +397,8 @@ export async function createServer({
     a busy socket doesn't iterate JS per subscriber per message.
     */
     const socketDispatcher = createSocketDispatcher(sockets)
-    server = Bun.serve({
+    // Server<unknown> pins Bun's WebSocketData generic so upgrade({ data: {} }) typechecks.
+    const server: Server<unknown> = Bun.serve({
         port,
 
         websocket: {
@@ -436,6 +417,23 @@ export async function createServer({
 
         async fetch(req, bunServer) {
             const url = new URL(req.url)
+            /*
+            Identity probe — answered directly, ahead of any app.handle middleware,
+            so the bundle's connect screen can confirm a URL really is a belte
+            server (and which app) before pointing the desktop window at it. It
+            must stay reachable even when the app guards everything behind auth,
+            hence the early return that bypasses dispatchRequest.
+            */
+            if (url.pathname === IDENTITY_PATH) {
+                return Response.json(
+                    {
+                        belte: true,
+                        name: appInfo?.name ?? cliName,
+                        version: appInfo?.version ?? '0.0.0',
+                    },
+                    { headers: { 'Cache-Control': NO_STORE } },
+                )
+            }
             if (url.pathname === SOCKETS_PATH) {
                 if (bunServer.upgrade(req, { data: {} })) {
                     return undefined as unknown as Response
@@ -515,13 +513,7 @@ export async function createServer({
 
         error(err) {
             log.error(err)
-            return new Response(`<pre>${String(err.stack ?? err)}</pre>`, {
-                status: 500,
-                headers: {
-                    'Content-Type': 'text/html; charset=utf-8',
-                    'Cache-Control': NO_STORE,
-                },
-            })
+            return internalErrorResponse(err)
         },
     })
 

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

@@ -20,29 +20,47 @@ type RegistryManifests = {
 }
 
 let manifests: RegistryManifests | undefined
-let loadedAll = false
+let loading: Promise<void> | undefined
 
 export function setRegistryManifests(value: RegistryManifests): void {
     manifests = value
-    loadedAll = false
+    loading = undefined
 }
 
 /*
 On first call, eagerly imports every rpc + socket + prompt module so
 defineVerb / defineSocket / definePrompt fire and populate the
-registries. Idempotent — repeat calls are no-ops. Eager loading is
-acceptable here because enumeration (MCP tool/resource/prompt lists,
-the OpenAPI document) fundamentally requires the full surface; the
-alternative of per-call lazy loading produces flaky first-call latency.
+registries. Idempotent — repeat calls reuse the same in-flight promise,
+so concurrent first requests (e.g. /openapi.json + an MCP tools/list)
+trigger exactly one load instead of racing to fire the full import set
+each. Eager loading is acceptable here because enumeration (MCP
+tool/resource/prompt lists, the OpenAPI document) fundamentally requires
+the full surface; the alternative of per-call lazy loading produces flaky
+first-call latency.
 */
-export async function ensureRegistriesLoaded(): Promise<void> {
-    if (loadedAll || !manifests) {
-        return
+export function ensureRegistriesLoaded(): Promise<void> {
+    if (!manifests) {
+        return Promise.resolve()
     }
-    await Promise.all([
-        ...Object.values(manifests.rpc).map((loader) => loader()),
-        ...Object.values(manifests.sockets).map((loader) => loader()),
-        ...Object.values(manifests.prompts).map((loader) => loader()),
-    ])
-    loadedAll = true
+    if (!loading) {
+        const { rpc, sockets, prompts } = manifests
+        loading = Promise.all([
+            ...Object.values(rpc).map((loader) => loader()),
+            ...Object.values(sockets).map((loader) => loader()),
+            ...Object.values(prompts).map((loader) => loader()),
+        ])
+            .then(() => undefined)
+            /*
+            Clear the memo on failure so a transient import error (a
+            module that throws at load, fixed by the next HMR pass)
+            doesn't poison every later enumeration request for the
+            process lifetime. The rejection still propagates to this
+            caller; the reset only affects subsequent calls.
+            */
+            .catch((error) => {
+                loading = undefined
+                throw error
+            })
+    }
+    return loading
 }

package/src/lib/server/runtime/types/RequestStore.ts

@@ -1,15 +1,14 @@
-import type { Server } from 'bun'
 import type { CacheStore } from '../../../shared/types/CacheStore.ts'
 
 /*
 Per-request state propagated through AsyncLocalStorage. Every field is
 populated once at the server's fetch boundary; helpers and verb-defined
 remote functions read from it without threading arguments through user code.
+The inbound request's AbortSignal is reached via `req.signal` rather than a
+separate field.
 */
 export type RequestStore = {
     url: URL
     req: Request
-    signal: AbortSignal
     cache: CacheStore
-    server: Server<unknown>
 }

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

@@ -0,0 +1,24 @@
+/*
+Merges a caller's `ResponseInit` over a respond helper's default headers.
+The helper's defaults seed the header set; the caller's headers overlay them
+per-key (so an explicit `cache-control` wins over the helper's `no-store`),
+and the rest of `init` (status, statusText) passes straight through. Shared
+by `json` / `jsonl` / `sse` / `error` / `redirect` so every helper accepts a
+final `ResponseInit` with identical override semantics.
+
+A helper that owns the status itself (`error`, `redirect`) passes it as the
+final `status` argument; it is applied last so it always wins over any
+`init.status`, keeping that precedence inside the helper rather than relying
+on each call site spreading in the right order.
+*/
+export function withResponseDefaults(
+    init: ResponseInit | undefined,
+    defaultHeaders: Record<string, string>,
+    status?: number,
+): ResponseInit {
+    const headers = new Headers(defaultHeaders)
+    new Headers(init?.headers).forEach((value, key) => {
+        headers.set(key, value)
+    })
+    return { ...init, headers, ...(status !== undefined && { status }) }
+}

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

@@ -3,6 +3,10 @@ import { log } from '../../shared/log.ts'
 import { lookupSocket } from './lookupSocket.ts'
 import type { SocketClientFrame } from './types/SocketClientFrame.ts'
 import type { SocketRoutes } from './types/SocketRoutes.ts'
+import type { SocketServerFrame } from './types/SocketServerFrame.ts'
+
+// Reused across every inbound binary frame rather than allocated per message.
+const textDecoder = new TextDecoder()
 
 type SocketDispatcher = {
     open(ws: ServerWebSocket<unknown>): void
@@ -60,8 +64,8 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         return promise
     }
 
-    function send(ws: ServerWebSocket<unknown>, frame: unknown): void {
-        if (ws.readyState !== 1) {
+    function send(ws: ServerWebSocket<unknown>, frame: SocketServerFrame): void {
+        if (ws.readyState !== WebSocket.OPEN) {
             return
         }
         ws.send(JSON.stringify(frame))
@@ -154,10 +158,9 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         const replayCount =
             frame.replay === undefined ? history.length : Math.min(frame.replay, history.length)
         if (replayCount > 0) {
-            const start = history.length - replayCount
-            for (let index = start; index < history.length; index++) {
-                send(ws, { type: 'msg', socket: frame.socket, message: history[index] })
-            }
+            history.slice(history.length - replayCount).forEach((message) => {
+                send(ws, { type: 'msg', socket: frame.socket, message })
+            })
         }
     }
 
@@ -232,7 +235,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             if (!state) {
                 return
             }
-            const text = typeof data === 'string' ? data : data.toString('utf8')
+            const text = typeof data === 'string' ? data : textDecoder.decode(data)
             let frame: SocketClientFrame
             try {
                 frame = JSON.parse(text) as SocketClientFrame

package/src/lib/server/sse.ts

@@ -26,22 +26,27 @@ maps it to the entry's `error` field.
 import { NO_STORE } from '../shared/cacheControlValues.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
 import { streamFromIterator } from './runtime/streamFromIterator.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
 
 const KEEPALIVE_INTERVAL_MS = 15000
 
-export function sse<Frame>(iterable: AsyncIterable<Frame>): TypedResponse<Frame> {
+export function sse<Frame>(
+    iterable: AsyncIterable<Frame>,
+    init?: ResponseInit,
+): TypedResponse<Frame> {
     const body = streamFromIterator(iterable, {
         encodeFrame: (value) => `data: ${JSON.stringify(value)}\n\n`,
         encodeError: (message) => `event: error\ndata: ${JSON.stringify({ message })}\n\n`,
         keepaliveMs: KEEPALIVE_INTERVAL_MS,
         keepalivePayload: ': keepalive\n\n',
     })
-    return new Response(body, {
-        headers: {
+    return new Response(
+        body,
+        withResponseDefaults(init, {
             'Content-Type': 'text/event-stream; charset=utf-8',
             'Cache-Control': NO_STORE,
             'X-Content-Type-Options': 'nosniff',
             Connection: 'keep-alive',
-        },
-    }) as TypedResponse<Frame>
+        }),
+    ) as TypedResponse<Frame>
 }

package/src/lib/shared/cacheControlValues.ts

@@ -1,8 +1,16 @@
 /*
 Cache-Control values used by belte's framework responses. Centralised so
 the framework's policy (no-store on errors and rpc dispatch helpers,
-private/no-cache on SSR HTML) lives in one place and can't drift between
-the server core and the respond helpers.
+private/no-cache on SSR HTML, the static-asset policies) lives in one place
+and can't drift between the server core, the asset servers, and the respond
+helpers.
 */
 export const NO_STORE = 'no-store'
 export const SSR_CACHE_CONTROL = 'private, no-cache'
+
+// Content-addressed `/_app/` chunks (name carries the hash) — cache forever.
+export const IMMUTABLE_ASSET_CACHE_CONTROL = 'public, max-age=31536000, immutable'
+// Unhashed `/_app/` entries (entry bundle, shell) — must revalidate each time.
+export const REVALIDATE_ASSET_CACHE_CONTROL = 'public, max-age=0, must-revalidate'
+// Files served from public/ at the site root — short shared cache.
+export const PUBLIC_ASSET_CACHE_CONTROL = 'public, max-age=3600'

package/src/lib/shared/canonicalJson.ts

@@ -16,9 +16,5 @@ function sortedKeysReplacer(_key: string, value: unknown): unknown {
     }
     const record = value as Record<string, unknown>
     const sortedKeys = Object.keys(record).sort()
-    const sorted: Record<string, unknown> = {}
-    for (const key of sortedKeys) {
-        sorted[key] = record[key]
-    }
-    return sorted
+    return Object.fromEntries(sortedKeys.map((key) => [key, record[key]]))
 }

package/src/lib/shared/createCacheStore.ts

@@ -7,14 +7,16 @@ Returns a fresh cache store. On the server, every request gets its own
 store via the AsyncLocalStorage RequestStore. On the client, a single
 module-level store is created at startup and shared across the tab.
 
-Each key gets a lazily-created Svelte subscriber that lives for the
-lifetime of the store. Reading a key from a tracking scope
-($derived / $effect) subscribes that scope; invalidating the key dispatches
-an 'invalidate' event whose detail is a Set of affected keys so each
-listener's lookup is O(1). When the entry is later re-created the same
-subscriber is reused — no listener churn, no risk of duplicate registrations
-during entry eviction. Svelte tears down the underlying listener on its
-own when the last tracker stops reading.
+Each key gets a lazily-created Svelte subscriber. Reading a key from a
+tracking scope ($derived / $effect) subscribes that scope; invalidating
+the key dispatches an 'invalidate' event whose detail is a Set of affected
+keys so each listener's lookup is O(1). The subscriber outlives entry
+eviction — invalidating/refetching a key reuses the same subscriber, so
+there's no listener churn or duplicate registration as cache values come
+and go. It's evicted only when its last reactive reader tears down (the
+client store is module-level/tab-scoped, so retaining a thunk per distinct
+key would otherwise grow unbounded across a session), identity-guarded so
+a concurrent re-subscribe isn't clobbered — mirroring subscribe.ts.
 */
 export function createCacheStore(): CacheStore {
     const entries = new Map<string, CacheEntry>()
@@ -22,19 +24,26 @@ export function createCacheStore(): CacheStore {
     const subscribers = new Map<string, () => void>()
 
     function subscribe(key: string): void {
-        let registered = subscribers.get(key)
-        if (!registered) {
-            registered = createSubscriber((update) => {
-                const onInvalidate = (event: Event) => {
-                    if ((event as CustomEvent<Set<string>>).detail.has(key)) {
-                        update()
-                    }
-                }
-                events.addEventListener('invalidate', onInvalidate)
-                return () => events.removeEventListener('invalidate', onInvalidate)
-            })
-            subscribers.set(key, registered)
+        const existing = subscribers.get(key)
+        if (existing) {
+            existing()
+            return
         }
+        const registered = createSubscriber((update) => {
+            const onInvalidate = (event: Event) => {
+                if ((event as CustomEvent<Set<string>>).detail.has(key)) {
+                    update()
+                }
+            }
+            events.addEventListener('invalidate', onInvalidate)
+            return () => {
+                events.removeEventListener('invalidate', onInvalidate)
+                if (subscribers.get(key) === registered) {
+                    subscribers.delete(key)
+                }
+            }
+        })
+        subscribers.set(key, registered)
         registered()
     }
 

package/src/lib/shared/exitOnBuildFailure.ts

@@ -0,0 +1,17 @@
+import type { BuildOutput } from 'bun'
+import { log } from './log.ts'
+
+/*
+On a failed Bun.build(), logs each diagnostic and exits non-zero. Every belte
+build entrypoint (build / compile / buildCli / bundleApp) funnels its result
+through here so failure reporting can't drift between them.
+*/
+export function exitOnBuildFailure(result: BuildOutput): void {
+    if (result.success) {
+        return
+    }
+    result.logs.forEach((entry) => {
+        log.error(entry)
+    })
+    process.exit(1)
+}

package/src/lib/shared/fileStem.ts

@@ -0,0 +1,9 @@
+/*
+The bare filename of a path, with directory and trailing extension stripped —
+e.g. `users/list.ts` → `list`, `/_virtual/mcp-resources.ts` → `mcp-resources`.
+Used to derive a virtual-module name from its path and to check an $rpc /
+$sockets module's single export name against its file stem.
+*/
+export function fileStem(path: string): string {
+    return (path.split('/').pop() ?? '').replace(/\.[^.]+$/, '')
+}

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 } : {}),
+    }
+}