@briancray/belte 0.1.0 → 0.2.1

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

package/src/lib/shared/keyForRemoteCall.ts

@@ -3,16 +3,18 @@ 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
+prefix is `${method} ${url}` where `url` is the route template. GET/DELETE/HEAD
 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).
+args after a space as canonical JSON. The verb split mirrors buildRpcRequest
+exactly so the key and the synthesized Request can't disagree. 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 (method === 'GET' || method === 'DELETE' || method === 'HEAD') {
         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/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/prepareRpcModule.ts

@@ -1,10 +1,10 @@
 import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import { beltePackageName } from './beltePackageName.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'
@@ -27,14 +27,24 @@ 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 {
+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.
+    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 = VERB_IMPORT_PATHS.reduce((current, path) => stripImport(current, path), source)
+    const importNames =
+        importName === beltePackageName ? [beltePackageName] : [importName, beltePackageName]
+    const stripped = importNames.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

package/src/lib/shared/prepareSocketModule.ts

@@ -1,3 +1,4 @@
+import { beltePackageName } from './beltePackageName.ts'
 import { findExportCallSite } from './findExportCallSite.ts'
 import { stripImport } from './stripImport.ts'
 
@@ -17,8 +18,21 @@ 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')
+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 importNames =
+        importName === beltePackageName ? [beltePackageName] : [importName, beltePackageName]
+    const stripped = importNames.reduce(
+        (current, name) => stripImport(current, `${name}/server/socket`),
+        source,
+    )
     const site = findExportCallSite(stripped, (ident) => ident === 'socket', SINGLE_EXPORT_ERROR)
     if (!site) {
         return undefined

package/src/lib/shared/promptNameForFile.ts

@@ -1,10 +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
+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(/\.ts$/, '').replaceAll('/', '-')
+    return relativePath.replace(/\.md$/, '').replaceAll('/', '-')
 }

package/src/lib/shared/subscribableFromResponse.ts

@@ -24,7 +24,7 @@ mirroring the plain `fn(args)` decode path.
 */
 function streamResponse<T>(response: Response): AsyncIterable<T> {
     if (!response.ok) {
-        return errorIterable(new HttpError(response))
+        return errorIterable<T>(new HttpError(response))
     }
     const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
     if (contentType.startsWith('text/event-stream')) {
@@ -36,25 +36,9 @@ function streamResponse<T>(response: Response): AsyncIterable<T> {
     return oneShot<T>(response)
 }
 
-function errorIterable<T>(error: Error): AsyncIterable<T> {
-    return {
-        [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
-            let done = false
-            return {
-                async next() {
-                    if (done) {
-                        return { value: undefined, done: true }
-                    }
-                    done = true
-                    throw error
-                },
-                async return() {
-                    done = true
-                    return { value: undefined, done: true }
-                },
-            }
-        },
-    }
+/* Surfaces a non-2xx response (or any pre-stream failure) as a thrown error on the first pull. */
+async function* errorIterable<T>(error: Error): AsyncGenerator<T> {
+    throw error
 }
 
 /*
@@ -64,120 +48,84 @@ completes. Makes `fn.stream(args)` symmetrical across streaming and
 non-streaming handlers — callers can pick the iteration shape without
 worrying about which body the handler returned.
 */
-function oneShot<T>(response: Response): AsyncIterable<T> {
-    return {
-        [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
-            let yielded = false
-            return {
-                async next() {
-                    if (yielded) {
-                        return { value: undefined, done: true }
-                    }
-                    yielded = true
-                    const value = (await decodeResponse(response)) as T
-                    return { value, done: false }
-                },
-                async return() {
-                    yielded = true
-                    return { value: undefined, done: true }
-                },
-            }
-        },
-    }
+async function* oneShot<T>(response: Response): AsyncGenerator<T> {
+    yield (await decodeResponse(response)) as T
 }
 
 /*
-SSE parser: reads the response body as text frames separated by blank
-lines, splits each frame into `event:` / `data:` lines, and yields the
-JSON-parsed data payload. The `sse()` respond helper emits an
-`event: error\ndata: {"message":...}` frame when the source generator
-throws, which we surface as a thrown Error so consumer loops can
-surface mid-stream failure rather than silently stopping.
+Reads a streaming text Response and yields raw frame strings split on
+`delimiter` (`\n\n` for SSE events, `\n` for JSON lines). Owns the whole
+buffering lifecycle: incremental decode, amortised-O(n) compaction, a
+final flush of the trailing partial frame, and reader cancellation when
+the consumer stops iterating (the generator's `finally` runs on
+`return()`). The SSE and jsonl parsers layer their per-frame parsing on
+top of this single machine so the two can't drift.
 */
-function parseSse<T>(response: Response): AsyncIterable<T> {
-    return {
-        [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
-            const body = response.body
-            if (!body) {
-                return emptyIterator<T>()
-            }
-            const reader = body.pipeThrough(new TextDecoderStream()).getReader()
-            let buffer = ''
-            let bufferStart = 0
-            const pending: Array<{ event: string; data: string }> = []
-            let done = false
-
-            async function pullFrames(): Promise<void> {
-                while (pending.length === 0 && !done) {
-                    const { value, done: streamDone } = await reader.read()
-                    if (streamDone) {
-                        done = true
-                        if (bufferStart < buffer.length) {
-                            const frame = parseFrame(buffer.slice(bufferStart))
-                            if (frame) {
-                                pending.push(frame)
-                            }
-                            buffer = ''
-                            bufferStart = 0
-                        }
-                        return
-                    }
-                    /*
-                    Compact only when the unread region is small relative to
-                    the consumed prefix — keeps amortised work O(n) instead
-                    of quadratic slicing per frame boundary.
-                    */
-                    if (bufferStart > buffer.length / 2) {
-                        buffer = buffer.slice(bufferStart) + value
-                        bufferStart = 0
-                    } else {
-                        buffer += value
-                    }
-                    let boundary = buffer.indexOf('\n\n', bufferStart)
-                    while (boundary !== -1) {
-                        const raw = buffer.slice(bufferStart, boundary)
-                        bufferStart = boundary + 2
-                        const frame = parseFrame(raw)
-                        if (frame) {
-                            pending.push(frame)
-                        }
-                        boundary = buffer.indexOf('\n\n', bufferStart)
-                    }
+async function* frameReader(response: Response, delimiter: string): AsyncGenerator<string> {
+    const body = response.body
+    if (!body) {
+        return
+    }
+    const reader = body.pipeThrough(new TextDecoderStream()).getReader()
+    let buffer = ''
+    let bufferStart = 0
+    try {
+        while (true) {
+            const { value, done } = await reader.read()
+            if (done) {
+                if (bufferStart < buffer.length) {
+                    yield buffer.slice(bufferStart)
                 }
+                return
+            }
+            /*
+            Compact only when the unread region is small relative to the
+            consumed prefix — keeps amortised work O(n) instead of
+            quadratic slicing per frame boundary.
+            */
+            if (bufferStart > buffer.length / 2) {
+                buffer = buffer.slice(bufferStart) + value
+                bufferStart = 0
+            } else {
+                buffer += value
             }
+            let boundary = buffer.indexOf(delimiter, bufferStart)
+            while (boundary !== -1) {
+                yield buffer.slice(bufferStart, boundary)
+                bufferStart = boundary + delimiter.length
+                boundary = buffer.indexOf(delimiter, bufferStart)
+            }
+        }
+    } finally {
+        await reader.cancel().catch(() => undefined)
+    }
+}
 
-            return {
-                async next() {
-                    while (true) {
-                        if (pending.length > 0) {
-                            const next = pending.shift() as { event: string; data: string }
-                            if (next.event === 'error') {
-                                try {
-                                    const decoded = JSON.parse(next.data) as { message?: string }
-                                    throw new Error(decoded?.message ?? 'sse stream error')
-                                } catch (err) {
-                                    if (err instanceof SyntaxError) {
-                                        throw new Error(next.data || 'sse stream error')
-                                    }
-                                    throw err
-                                }
-                            }
-                            const value = JSON.parse(next.data) as T
-                            return { value, done: false }
-                        }
-                        if (done) {
-                            return { value: undefined, done: true }
-                        }
-                        await pullFrames()
-                    }
-                },
-                async return() {
-                    done = true
-                    await reader.cancel().catch(() => undefined)
-                    return { value: undefined, done: true }
-                },
+/*
+SSE parser: yields the JSON-parsed `data` payload of each `event:`/`data:`
+frame. The `sse()` respond helper emits an `event: error\ndata:
+{"message":...}` frame when the source generator throws, which we surface
+as a thrown Error so consumer loops can react to mid-stream failure
+rather than silently stopping.
+*/
+async function* parseSse<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n\n')) {
+        const frame = parseFrame(raw)
+        if (!frame) {
+            continue
+        }
+        if (frame.event === 'error') {
+            try {
+                const decoded = JSON.parse(frame.data) as { message?: string }
+                throw new Error(decoded?.message ?? 'sse stream error')
+            } catch (err) {
+                if (err instanceof SyntaxError) {
+                    throw new Error(frame.data || 'sse stream error')
+                }
+                throw err
             }
-        },
+        }
+        yield JSON.parse(frame.data) as T
     }
 }
 
@@ -205,96 +153,22 @@ function parseFrame(raw: string): { event: string; data: string } | undefined {
 }
 
 /*
-JSONL/NDJSON parser: reads the response body as text, splits on `\n`,
-parses each non-empty line as JSON, and yields the value. The `jsonl()`
-respond helper emits a trailing `{"$error":"<message>"}` line when the
-source generator throws — that's surfaced here as a thrown Error so
-consumer loops can react to mid-stream failure.
+JSONL/NDJSON parser: parses each non-empty line as JSON and yields the
+value. The `jsonl()` respond helper emits a trailing
+`{"$error":"<message>"}` line when the source generator throws — that's
+surfaced here as a thrown Error so consumer loops can react to mid-stream
+failure.
 */
-function parseJsonLines<T>(response: Response): AsyncIterable<T> {
-    return {
-        [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
-            const body = response.body
-            if (!body) {
-                return emptyIterator<T>()
-            }
-            const reader = body.pipeThrough(new TextDecoderStream()).getReader()
-            let buffer = ''
-            let bufferStart = 0
-            const pending: string[] = []
-            let done = false
-
-            async function pullLines(): Promise<void> {
-                while (pending.length === 0 && !done) {
-                    const { value, done: streamDone } = await reader.read()
-                    if (streamDone) {
-                        done = true
-                        if (bufferStart < buffer.length) {
-                            pending.push(buffer.slice(bufferStart))
-                            buffer = ''
-                            bufferStart = 0
-                        }
-                        return
-                    }
-                    if (bufferStart > buffer.length / 2) {
-                        buffer = buffer.slice(bufferStart) + value
-                        bufferStart = 0
-                    } else {
-                        buffer += value
-                    }
-                    let newline = buffer.indexOf('\n', bufferStart)
-                    while (newline !== -1) {
-                        const line = buffer.slice(bufferStart, newline)
-                        bufferStart = newline + 1
-                        if (line.length > 0) {
-                            pending.push(line)
-                        }
-                        newline = buffer.indexOf('\n', bufferStart)
-                    }
-                }
-            }
-
-            return {
-                async next() {
-                    while (true) {
-                        if (pending.length > 0) {
-                            const line = pending.shift() as string
-                            const parsed = JSON.parse(line) as Record<string, unknown> & {
-                                $error?: string
-                            }
-                            if (
-                                parsed &&
-                                typeof parsed === 'object' &&
-                                typeof parsed.$error === 'string'
-                            ) {
-                                throw new Error(parsed.$error)
-                            }
-                            return { value: parsed as T, done: false }
-                        }
-                        if (done) {
-                            return { value: undefined, done: true }
-                        }
-                        await pullLines()
-                    }
-                },
-                async return() {
-                    done = true
-                    await reader.cancel().catch(() => undefined)
-                    return { value: undefined, done: true }
-                },
-            }
-        },
-    }
-}
-
-function emptyIterator<T>(): AsyncIterator<T, void, undefined> {
-    return {
-        async next() {
-            return { value: undefined, done: true }
-        },
-        async return() {
-            return { value: undefined, done: true }
-        },
+async function* parseJsonLines<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n')) {
+        if (raw.length === 0) {
+            continue
+        }
+        const parsed = JSON.parse(raw) as Record<string, unknown> & { $error?: string }
+        if (parsed && typeof parsed === 'object' && typeof parsed.$error === 'string') {
+            throw new Error(parsed.$error)
+        }
+        yield parsed as T
     }
 }
 
@@ -315,15 +189,30 @@ export function subscribableFromResponse<T>(
         name,
         [Symbol.asyncIterator]() {
             let inner: AsyncIterator<T, void, undefined> | undefined
+            let cancelled = false
             return {
                 async next() {
+                    if (cancelled) {
+                        return { value: undefined, done: true }
+                    }
                     if (!inner) {
                         const response = await fetchResponse()
                         inner = streamResponse<T>(response)[Symbol.asyncIterator]()
+                        /*
+                        If return() landed while we were awaiting the
+                        fetch, `inner` was still undefined then so its
+                        reader was never cancelled — release the body now
+                        rather than leaving the HTTP stream open.
+                        */
+                        if (cancelled) {
+                            await inner.return?.(undefined)
+                            return { value: undefined, done: true }
+                        }
                     }
                     return inner.next()
                 },
                 async return() {
+                    cancelled = true
                     await inner?.return?.(undefined)
                     return { value: undefined, done: true }
                 },

package/src/lib/shared/types/PromptArgument.ts

@@ -0,0 +1,12 @@
+/*
+A single declared argument of a markdown prompt, parsed from the file's
+YAML frontmatter `arguments:` list. `name` is the placeholder the body
+interpolates via `{{name}}`; `description` + `required` feed the argument
+list MCP advertises in `prompts/list`. Build-time only — markdown prompts
+carry no runtime schema object, so this drives the generated JSON Schema.
+*/
+export type PromptArgument = {
+    name: string
+    description?: string
+    required?: boolean
+}