@briancray/belte 0.1.0 → 0.2.0

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/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
+}

package/src/lib/shared/writeRoutesDts.ts

@@ -9,13 +9,11 @@ when dispatching, so the page component sees `params.rest`, not
 `params['*']`.
 */
 function paramsForRoute(routeUrl: string): Record<string, 'string'> {
-    const params: Record<string, 'string'> = {}
-    for (const segment of parseRouteSegments(routeUrl)) {
-        if (segment.kind === 'param') {
-            params[segment.name] = 'string'
-        }
-    }
-    return params
+    return Object.fromEntries(
+        parseRouteSegments(routeUrl)
+            .filter((segment) => segment.kind === 'param')
+            .map((segment) => [segment.name, 'string'] as const),
+    )
 }
 
 function renderParamsShape(shape: Record<string, 'string'>): string {

package/src/serverBuildPlugins.ts

@@ -0,0 +1,25 @@
+import type { BunPlugin } from 'bun'
+import { belteResolverPlugin } from './belteResolverPlugin.ts'
+import type { SvelteConfig } from './lib/server/runtime/types/SvelteConfig.ts'
+import { sveltePlugin } from './sveltePlugin.ts'
+
+/*
+The server-target Bun.build plugin pair shared by compile / buildCli /
+bundleApp: the svelte loader (server generate) plus belte's virtual-module
+resolver. `embedAssets` flips on the zstd asset embed used by the standalone
+server binary; the CLI + launcher builds leave it off.
+*/
+export function serverBuildPlugins({
+    cwd,
+    svelteConfig,
+    embedAssets = false,
+}: {
+    cwd: string
+    svelteConfig?: SvelteConfig
+    embedAssets?: boolean
+}): BunPlugin[] {
+    return [
+        sveltePlugin({ generate: 'server', svelteConfig }),
+        belteResolverPlugin({ cwd, embedAssets, target: 'server' }),
+    ]
+}

package/src/serverEntry.ts

@@ -24,10 +24,14 @@ import { rpc } from './_virtual/rpc.ts'
 import { shell } from './_virtual/shell.ts'
 // @ts-expect-error virtual module resolved by belteResolverPlugin
 import { sockets } from './_virtual/sockets.ts'
+import { exitWithParent } from './lib/bundle/exitWithParent.ts'
 import { createServer } from './lib/server/runtime/createServer.ts'
 import { requestContext } from './lib/server/runtime/requestContext.ts'
 import { setCacheStoreResolver } from './lib/shared/setCacheStoreResolver.ts'
 
+// In a bundle, tie this server's life to the launcher's (no-op standalone).
+exitWithParent()
+
 setCacheStoreResolver(() => requestContext.getStore()?.cache)
 
 await createServer({

package/template/package.json

@@ -7,7 +7,8 @@
         "dev": "belte dev",
         "build": "belte build",
         "start": "belte start",
-        "compile": "belte compile"
+        "compile": "belte compile",
+        "bundle": "belte bundle"
     },
     "dependencies": {
         "@briancray/belte": "^0.1.0",

package/src/lib/server/prompt.ts

@@ -1,30 +0,0 @@
-import type { Prompt } from './prompts/types/Prompt.ts'
-import type { PromptOptions } from './prompts/types/PromptOptions.ts'
-import type { StandardSchemaV1 } from './rpc/types/StandardSchemaV1.ts'
-
-/*
-Declares an MCP prompt inside a file under `src/server/prompts/`. Each
-file contains exactly one export, named after the file (e.g.
-`summarize.ts` → `export const summarize = prompt(...)`). The bundler
-reads the export name from the filename and the prompt name from the file
-path under `src/server/prompts/`, then rewrites this call to bind the name
-into definePrompt.
-
-`render(args)` returns the messages MCP hands back for `prompts/get`:
-either a bare string (one user message) or an explicit message array.
-When `schema` is set, `Args` infers from `InferOutput<Schema>`, incoming
-arguments validate against it, and MCP advertises the argument list in
-`prompts/list`.
-
-This function exists only for the type signature; calling it directly
-means the bundler plugin didn't process the file, which throws.
-*/
-export function prompt<Schema extends StandardSchemaV1>(
-    opts: PromptOptions<StandardSchemaV1.InferOutput<Schema>> & { schema: Schema },
-): Prompt<StandardSchemaV1.InferOutput<Schema>>
-export function prompt<Args = Record<string, string>>(opts: PromptOptions<Args>): Prompt<Args>
-export function prompt(_opts: PromptOptions): Prompt {
-    throw new Error(
-        '[belte] `prompt(...)` was called outside a prompts module — the prompt helper is only valid as the value of `export const <filename> = ...` inside a file under src/server/prompts/',
-    )
-}

package/src/lib/server/prompts/types/PromptMessage.ts

@@ -1,10 +0,0 @@
-/*
-A single message in an MCP prompt's rendered output. `prompt({ render })`
-returns either a bare string (sugar for one `user` message) or an array
-of these. The dispatcher maps each into the MCP `prompts/get` wire shape
-({ role, content: { type: 'text', text } }).
-*/
-export type PromptMessage = {
-    role: 'user' | 'assistant'
-    text: string
-}

package/src/lib/shared/preparePromptModule.ts

@@ -1,36 +0,0 @@
-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)
-        },
-    }
-}