@briancray/belte 0.3.1 → 0.5.0

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/loadEnvFile.ts

@@ -0,0 +1,17 @@
+import { readEnvFile } from './readEnvFile.ts'
+
+/*
+Reads a `.env` at `path` and merges each declared var into `process.env`
+only when not already set. Fill-when-unset is the precedence rule the whole
+env stack relies on: layers loaded earlier (shell/ambient, Bun's CWD `.env`)
+win, and later callers back-fill only what's still missing. So a value's
+source is invisible to the app — it reads one flat `process.env` (Bun.env is
+the same object). Missing file is a no-op.
+*/
+export async function loadEnvFile(path: string): Promise<void> {
+    for (const [key, value] of Object.entries(await readEnvFile(path))) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value
+        }
+    }
+}

package/src/lib/shared/loadEnvFromDataDir.ts

@@ -0,0 +1,15 @@
+import { join } from 'node:path'
+import { appDataDir } from './appDataDir.ts'
+import { loadEnvFile } from './loadEnvFile.ts'
+
+/*
+Loads the user's `.env` from the program's per-user data dir into `process.env`.
+This is the cwd-independent config layer — where the connect-screen form writes
+the user's answers, and where a bundle launched via `open` (cwd `/`, so Bun's
+CWD `.env` autoload finds nothing) actually picks up its config. Loaded before
+the binary-dir `.env`, so a user's saved config overrides the shipped default;
+still loses to a shell export or a CWD `.env` (fill-when-unset, see loadEnvFile).
+*/
+export async function loadEnvFromDataDir(programName: string): Promise<void> {
+    await loadEnvFile(join(appDataDir(programName), '.env'))
+}

package/src/lib/shared/parseEnv.ts

@@ -0,0 +1,30 @@
+const ENV_LINE = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/
+
+/*
+Parses `.env` text into a key→value record. Skips blanks, comments, and
+malformed lines; strips a single layer of surrounding single or double quotes.
+Intentionally minimal — no variable expansion, escapes, or multi-line. The pure
+counterpart to loadEnvFile (which merges into process.env) and serializeEnv
+(which writes records back), so all three round-trip the same shape.
+*/
+export function parseEnv(text: string): Record<string, string> {
+    const result: Record<string, string> = {}
+    for (const line of text.split('\n')) {
+        if (!line || line.startsWith('#')) {
+            continue
+        }
+        const match = ENV_LINE.exec(line)
+        if (!match) {
+            continue
+        }
+        const [, key, rawValue] = match
+        const trimmed = rawValue?.trim() ?? ''
+        const unquoted =
+            (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))
+                ? trimmed.slice(1, -1)
+                : trimmed
+        result[key as string] = unquoted
+    }
+    return result
+}

package/src/lib/shared/readEnvFile.ts

@@ -0,0 +1,15 @@
+import { existsSync } from 'node:fs'
+import { parseEnv } from './parseEnv.ts'
+
+/*
+Reads a `.env` at `path` into a key→value record, or {} when it doesn't exist.
+The shared read-and-parse primitive: loadEnvFile builds on it to merge into
+process.env, and the bundle launcher uses the record directly to resolve config
+form pre-fills.
+*/
+export async function readEnvFile(path: string): Promise<Record<string, string>> {
+    if (!existsSync(path)) {
+        return {}
+    }
+    return parseEnv(await Bun.file(path).text())
+}

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/serializeEnv.ts

@@ -0,0 +1,18 @@
+// Quote only values that wouldn't round-trip bare through parseEnv — empties and
+// anything carrying whitespace or a `#` (which would otherwise read as a comment).
+function needsQuoting(value: string): boolean {
+    return value === '' || /[\s#]/.test(value)
+}
+
+/*
+Serializes a key→value record to `.env` text — the inverse of parseEnv, used by
+the connect-screen config form to persist the user's answers to the data-dir
+`.env`. One `KEY=value` per line; values that need it are wrapped in double
+quotes so parseEnv reads them back unchanged.
+*/
+export function serializeEnv(values: Record<string, string>): string {
+    const lines = Object.entries(values).map(([key, value]) =>
+        needsQuoting(value) ? `${key}="${value}"` : `${key}=${value}`,
+    )
+    return `${lines.join('\n')}\n`
+}

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'
+        }
+    },
+}

package/src/lib/shared/streamResponse.ts

@@ -0,0 +1,168 @@
+import { HttpError } from '../server/HttpError.ts'
+import { decodeResponse } from './decodeResponse.ts'
+import { jsonlErrorFrame } from './jsonlErrorFrame.ts'
+import { sseErrorFrame } from './sseErrorFrame.ts'
+import { STREAMING_CONTENT_TYPES } from './streamingContentTypes.ts'
+
+/*
+Turns a Response into an AsyncIterable of frames, regardless of the
+handler's chosen body format. Shared by `fn.stream(args)` (via
+subscribableFromResponse), the CLI's streaming print path, and the MCP
+tool dispatcher's stream drain — so every surface consumes sse/jsonl
+identically. Three shapes are handled:
+
+- text/event-stream (SSE): emits the JSON-parsed `data:` payload of
+  each event. The `event: error\ndata: {message}` frame the `sse()`
+  helper emits on generator throws is mapped back to a thrown Error so
+  consumers see the failure mid-iteration.
+- application/jsonl + application/x-ndjson: emits one JSON value per
+  line. The trailing `{"$error":"..."}` line the `jsonl()` helper
+  emits on generator throws is likewise re-thrown.
+- everything else: one-shot — yields the Content-Type-decoded body
+  once, then completes. Lets callers iterate uniformly on every rpc
+  handler, not just the streaming ones.
+
+Non-2xx responses surface as a thrown HttpError on the first pull,
+mirroring the plain `fn(args)` decode path.
+*/
+export function streamResponse<T>(response: Response): AsyncIterable<T> {
+    if (!response.ok) {
+        return errorIterable<T>(new HttpError(response))
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (contentType.startsWith('text/event-stream')) {
+        return parseSse<T>(response)
+    }
+    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
+        return parseJsonLines<T>(response)
+    }
+    return oneShot<T>(response)
+}
+
+/* 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
+}
+
+/*
+One-shot iterator over a non-streaming Response: decodes the body once
+via the same Content-Type sniffing the plain call uses, yields it, then
+completes. Makes streaming symmetrical across streaming and
+non-streaming handlers — callers can pick the iteration shape without
+worrying about which body the handler returned.
+*/
+async function* oneShot<T>(response: Response): AsyncGenerator<T> {
+    yield (await decodeResponse(response)) as T
+}
+
+/*
+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.
+*/
+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)
+    }
+}
+
+/*
+SSE parser: yields the JSON-parsed `data` payload of each `event:`/`data:`
+frame. The error sentinel (`sseErrorFrame`) the `sse()` helper emits on a
+generator throw is surfaced 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
+        }
+        const errorMessage = sseErrorFrame.decode(frame.event, frame.data)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield JSON.parse(frame.data) as T
+    }
+}
+
+function parseFrame(raw: string): { event: string; data: string } | undefined {
+    const lines = raw.split('\n').filter((line) => line.length > 0 && !line.startsWith(':'))
+    if (lines.length === 0) {
+        return undefined
+    }
+    let event = 'message'
+    const dataLines: string[] = []
+    for (const line of lines) {
+        const colon = line.indexOf(':')
+        const field = colon === -1 ? line : line.slice(0, colon)
+        const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
+        if (field === 'event') {
+            event = value
+        } else if (field === 'data') {
+            dataLines.push(value)
+        }
+    }
+    if (dataLines.length === 0) {
+        return undefined
+    }
+    return { event, data: dataLines.join('\n') }
+}
+
+/*
+JSONL/NDJSON parser: parses each non-empty line as JSON and yields the
+value. The error sentinel (`jsonlErrorFrame`) the `jsonl()` helper emits as
+a trailing line on a generator throw is surfaced here as a thrown Error so
+consumer loops can react to mid-stream failure.
+*/
+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)
+        const errorMessage = jsonlErrorFrame.decode(parsed)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield parsed as T
+    }
+}

package/src/lib/shared/subscribableFromResponse.ts

@@ -1,177 +1,6 @@
-import { HttpError } from '../server/HttpError.ts'
-import { decodeResponse } from './decodeResponse.ts'
-import { STREAMING_CONTENT_TYPES } from './streamingContentTypes.ts'
+import { streamResponse } from './streamResponse.ts'
 import type { Subscribable } from './types/Subscribable.ts'
 
-/*
-Turns a Response into an AsyncIterable of frames. Used by
-`fn.stream(args)` to give callers a uniform iterator regardless of the
-handler's chosen body format. Three shapes are handled:
-
-- text/event-stream (SSE): emits the JSON-parsed `data:` payload of
-  each event. The `event: error\ndata: {message}` frame the `sse()`
-  helper emits on generator throws is mapped back to a thrown Error so
-  consumers see the failure mid-iteration.
-- application/jsonl + application/x-ndjson: emits one JSON value per
-  line. The trailing `{"$error":"..."}` line the `jsonl()` helper
-  emits on generator throws is likewise re-thrown.
-- everything else: one-shot — yields the Content-Type-decoded body
-  once, then completes. Lets `fn.stream(args)` work uniformly on every
-  rpc handler, not just the streaming ones.
-
-Non-2xx responses surface as a thrown HttpError on the first pull,
-mirroring the plain `fn(args)` decode path.
-*/
-function streamResponse<T>(response: Response): AsyncIterable<T> {
-    if (!response.ok) {
-        return errorIterable<T>(new HttpError(response))
-    }
-    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
-    if (contentType.startsWith('text/event-stream')) {
-        return parseSse<T>(response)
-    }
-    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
-        return parseJsonLines<T>(response)
-    }
-    return oneShot<T>(response)
-}
-
-/* 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
-}
-
-/*
-One-shot iterator over a non-streaming Response: decodes the body once
-via the same Content-Type sniffing the plain call uses, yields it, then
-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.
-*/
-async function* oneShot<T>(response: Response): AsyncGenerator<T> {
-    yield (await decodeResponse(response)) as T
-}
-
-/*
-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.
-*/
-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)
-    }
-}
-
-/*
-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
-    }
-}
-
-function parseFrame(raw: string): { event: string; data: string } | undefined {
-    const lines = raw.split('\n').filter((line) => line.length > 0 && !line.startsWith(':'))
-    if (lines.length === 0) {
-        return undefined
-    }
-    let event = 'message'
-    const dataLines: string[] = []
-    for (const line of lines) {
-        const colon = line.indexOf(':')
-        const field = colon === -1 ? line : line.slice(0, colon)
-        const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
-        if (field === 'event') {
-            event = value
-        } else if (field === 'data') {
-            dataLines.push(value)
-        }
-    }
-    if (dataLines.length === 0) {
-        return undefined
-    }
-    return { event, data: dataLines.join('\n') }
-}
-
-/*
-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.
-*/
-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
-    }
-}
-
 /*
 Builds the Subscribable returned by `fn.stream(args)`. The carried
 `name` is the cache-style key for (method, url, args) so subscribe()

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

@@ -6,6 +6,11 @@ the function. `ttl`/`expiresAt` drive eviction: expiresAt = undefined means
 soon as the promise settles). The stored promise resolves to the raw
 Response so the snapshot can read its status/headers/body; the cache
 layer hands callers a decoded view derived from this same promise.
+
+`value` is set only for entries hydrated from the SSR snapshot: the
+snapshot body is pre-decoded synchronously so the first client render can
+read it without a microtask hop and byte-match the SSR DOM. Live fetches
+leave it undefined and take the async decode path.
 */
 export type CacheEntry = {
     key: string
@@ -13,4 +18,5 @@ export type CacheEntry = {
     request: Request
     ttl: number | undefined
     expiresAt: number | undefined
+    value?: unknown
 }

package/src/serverEntry.ts

@@ -25,10 +25,22 @@ 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 { loadEnvFromBinaryDir } from './lib/cli/loadEnvFromBinaryDir.ts'
 import { createServer } from './lib/server/runtime/createServer.ts'
 import { requestContext } from './lib/server/runtime/requestContext.ts'
+import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
 import { setCacheStoreResolver } from './lib/shared/setCacheStoreResolver.ts'
 
+/*
+Resolve config into process.env before anything reads it (createServer reads
+PORT, app code reads Bun.env.*). Data-dir first so the user's saved config wins
+over the binary-dir shipped default; both back-fill only what the shell or Bun's
+CWD `.env` didn't already set. A bundle launched via `open` has cwd `/`, so the
+data-dir `.env` is how it gets its config at all.
+*/
+await loadEnvFromDataDir(cliProgramName)
+await loadEnvFromBinaryDir()
+
 // In a bundle, tie this server's life to the launcher's (no-op standalone).
 exitWithParent()
 

package/template/src/server/rpc/getHello.ts

@@ -12,9 +12,11 @@ decoding) is inferred from the handler's return type via the
 `TypedResponse<T>` brand on `json`/`error`/`redirect`/`jsonl`/`sse`, so
 plain `GET(() => json({...}))` already types end-to-end.
 
-For inbound validation pass a Standard Schema-compatible schema as the
-second argument: `GET(fn, { schema })`. Args then infers from the schema's
-output type and the server replies with 422 on validation failure.
+For inbound validation pass a Standard Schema as `inputSchema` in the
+second argument: `GET(fn, { inputSchema })`. Args then infers from the
+schema's output type and the server replies with 422 on validation
+failure. An optional `outputSchema` describes the success body for the
+OpenAPI 200 response and the MCP tool output.
 
 `json(...)` from `belte/server/json` is a thin wrapper over `Response.json`
 that defaults `Cache-Control: no-store`, since intermediary caches shouldn't