@belte/belte 0.19.0

package/src/lib/shared/findExportCallSite.ts

@@ -0,0 +1,479 @@
+/*
+Scans a module source character-by-character — skipping strings,
+templates, comments, and TypeScript generics — for an
+`export const <name> = <IDENT>(...)` binding the caller cares about.
+On a match returns the identifier text, the export name, and the byte
+ranges of the call's open and close parens; the $rpc and $sockets
+rewriters splice their runtime bindings into those ranges.
+
+The scanner enforces a single matching export per module: a second match
+throws `singleExportError` so each $rpc / $sockets file is required to
+declare exactly one remote function / socket.
+
+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 type ExportCallSite = {
+    ident: string
+    exportName: string
+    callStart: number
+    parenStart: number
+    parenEnd: number
+}
+
+export function findExportCallSite(
+    source: string,
+    matchIdent: (ident: string) => boolean,
+    singleExportError: string,
+): ExportCallSite | undefined {
+    let found: ExportCallSite | undefined
+    const len = source.length
+    let i = 0
+    while (i < len) {
+        const c = source[i]
+        const next = source[i + 1]
+        if (c === '/' && next === '/') {
+            const newline = source.indexOf('\n', i + 2)
+            i = newline === -1 ? len : newline + 1
+            continue
+        }
+        if (c === '/' && next === '*') {
+            const end = source.indexOf('*/', i + 2)
+            i = end === -1 ? len : end + 2
+            continue
+        }
+        if (c === '/' && isRegexContext(source, i)) {
+            i = skipRegex(source, i + 1)
+            continue
+        }
+        if (c === '"' || c === "'") {
+            i = skipString(source, i + 1, c)
+            continue
+        }
+        if (c === '`') {
+            i = skipTemplate(source, i + 1)
+            continue
+        }
+        if (isIdentStart(c) && !isIdentPart(source[i - 1])) {
+            let j = i + 1
+            while (j < len && isIdentPart(source[j])) {
+                j++
+            }
+            const ident = source.slice(i, j)
+            if (matchIdent(ident)) {
+                const tail = matchCallTail(source, j)
+                if (tail !== undefined) {
+                    const exportName = detectExportName(source, i)
+                    if (exportName !== undefined) {
+                        if (found !== undefined) {
+                            throw new Error(singleExportError)
+                        }
+                        const parenEnd = findCallEnd(source, tail)
+                        if (parenEnd === undefined) {
+                            throw new Error(`[belte] unmatched \`(\` after \`${ident}\` identifier`)
+                        }
+                        found = {
+                            ident,
+                            exportName,
+                            callStart: i,
+                            parenStart: tail,
+                            parenEnd,
+                        }
+                        i = parenEnd + 1
+                        continue
+                    }
+                }
+            }
+            i = j
+            continue
+        }
+        i++
+    }
+    return found
+}
+
+function skipString(source: string, start: number, quote: string): number {
+    let i = start
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '\\') {
+            i += 2
+            continue
+        }
+        if (c === quote) {
+            return i + 1
+        }
+        if (c === '\n') {
+            return i
+        }
+        i++
+    }
+    return source.length
+}
+
+function skipTemplate(source: string, start: number): number {
+    let i = start
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '\\') {
+            i += 2
+            continue
+        }
+        if (c === '`') {
+            return i + 1
+        }
+        if (c === '$' && source[i + 1] === '{') {
+            i = skipTemplateExpression(source, i + 2)
+            continue
+        }
+        i++
+    }
+    return source.length
+}
+
+function skipTemplateExpression(source: string, start: number): number {
+    let depth = 1
+    let i = start
+    while (i < source.length && depth > 0) {
+        const c = source[i]
+        if (c === '{') {
+            depth++
+            i++
+            continue
+        }
+        if (c === '}') {
+            depth--
+            i++
+            continue
+        }
+        if (c === '"' || c === "'") {
+            i = skipString(source, i + 1, c)
+            continue
+        }
+        if (c === '`') {
+            i = skipTemplate(source, i + 1)
+            continue
+        }
+        if (c === '/' && source[i + 1] === '/') {
+            const newline = source.indexOf('\n', i + 2)
+            i = newline === -1 ? source.length : newline + 1
+            continue
+        }
+        if (c === '/' && source[i + 1] === '*') {
+            const end = source.indexOf('*/', i + 2)
+            i = end === -1 ? source.length : end + 2
+            continue
+        }
+        if (c === '/' && isRegexContext(source, i)) {
+            i = skipRegex(source, i + 1)
+            continue
+        }
+        i++
+    }
+    return i
+}
+
+function matchCallTail(source: string, after: number): number | undefined {
+    let j = after
+    while (j < source.length && isWhitespace(source[j])) {
+        j++
+    }
+    if (source[j] === '<') {
+        const closed = skipGenerics(source, j)
+        if (closed === undefined) {
+            return undefined
+        }
+        j = closed
+        while (j < source.length && isWhitespace(source[j])) {
+            j++
+        }
+    }
+    return source[j] === '(' ? j : undefined
+}
+
+/*
+Returns the index immediately after the matching `>` for a generic
+argument list starting at `start`. TypeScript type literals inside the
+generic (`<{ a: string; b: number }>`, function types `<() => X>`,
+tuples `<[A, B]>`, etc.) bring their own paired brackets and
+semicolons, so track depth across `<>`, `()`, `{}`, and `[]` and only
+count a closing `>` when every other bracket is balanced.
+Arrow-function `=>` is treated as a single token so the `>` doesn't
+prematurely close the generic.
+*/
+function skipGenerics(source: string, start: number): number | undefined {
+    let angleDepth = 0
+    let parenDepth = 0
+    let braceDepth = 0
+    let bracketDepth = 0
+    let i = start
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '"' || c === "'") {
+            i = skipString(source, i + 1, c)
+            continue
+        }
+        if (c === '`') {
+            i = skipTemplate(source, i + 1)
+            continue
+        }
+        if (c === '<') {
+            angleDepth++
+        } else if (c === '>') {
+            const isArrow = source[i - 1] === '='
+            if (!isArrow && parenDepth === 0 && braceDepth === 0 && bracketDepth === 0) {
+                angleDepth--
+                if (angleDepth === 0) {
+                    return i + 1
+                }
+            }
+        } else if (c === '(') {
+            parenDepth++
+        } else if (c === ')') {
+            parenDepth--
+        } else if (c === '{') {
+            braceDepth++
+        } else if (c === '}') {
+            braceDepth--
+        } else if (c === '[') {
+            bracketDepth++
+        } else if (c === ']') {
+            bracketDepth--
+        }
+        i++
+    }
+    return undefined
+}
+
+/*
+Walks the call body, skipping strings/templates/comments and respecting
+nested `()` so brackets inside object literals or nested calls don't
+throw the depth count.
+*/
+function findCallEnd(source: string, parenStart: number): number | undefined {
+    let depth = 1
+    let i = parenStart + 1
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '"' || c === "'") {
+            i = skipString(source, i + 1, c)
+            continue
+        }
+        if (c === '`') {
+            i = skipTemplate(source, i + 1)
+            continue
+        }
+        if (c === '/' && source[i + 1] === '/') {
+            const newline = source.indexOf('\n', i + 2)
+            i = newline === -1 ? source.length : newline + 1
+            continue
+        }
+        if (c === '/' && source[i + 1] === '*') {
+            const end = source.indexOf('*/', i + 2)
+            i = end === -1 ? source.length : end + 2
+            continue
+        }
+        if (c === '/' && isRegexContext(source, i)) {
+            i = skipRegex(source, i + 1)
+            continue
+        }
+        if (c === '(') {
+            depth++
+        } else if (c === ')') {
+            depth--
+            if (depth === 0) {
+                return i
+            }
+        }
+        i++
+    }
+    return undefined
+}
+
+/*
+Looks backwards from a `<IDENT>(` callStart to confirm it was bound by
+`export const <name> = ...`. Returns the identifier in `<name>` if so,
+undefined otherwise — used to skip mentions of an identifier that
+isn't the module's declared export.
+*/
+function detectExportName(source: string, callStart: number): string | undefined {
+    let i = callStart - 1
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    if (source[i] !== '=') {
+        return undefined
+    }
+    i--
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    const nameEnd = i + 1
+    while (i >= 0 && isIdentPart(source[i])) {
+        i--
+    }
+    const nameStart = i + 1
+    if (nameStart === nameEnd) {
+        return undefined
+    }
+    const name = source.slice(nameStart, nameEnd)
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    if (!matchesBackwards(source, i, 'const')) {
+        return undefined
+    }
+    i -= 'const'.length
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    if (!matchesBackwards(source, i, 'export')) {
+        return undefined
+    }
+    return name
+}
+
+function matchesBackwards(source: string, end: number, keyword: string): boolean {
+    const start = end - keyword.length + 1
+    if (start < 0) {
+        return false
+    }
+    if (source.slice(start, end + 1) !== keyword) {
+        return false
+    }
+    return start === 0 || !isIdentPart(source[start - 1])
+}
+
+function isIdentStart(c: string | undefined): boolean {
+    if (c === undefined) {
+        return false
+    }
+    return (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || c === '_' || c === '$'
+}
+
+function isIdentPart(c: string | undefined): boolean {
+    if (c === undefined) {
+        return false
+    }
+    return isIdentStart(c) || (c >= '0' && c <= '9')
+}
+
+function isWhitespace(c: string | undefined): boolean {
+    return c === ' ' || c === '\t' || c === '\n' || c === '\r'
+}
+
+/*
+A `/` starts a regex literal when the prior expression context expects an
+expression rather than a value — after an open delimiter, operator, or
+expression-prefix keyword (return, typeof, instanceof, in, of, delete,
+void, await, yield, new, throw, case, do). Otherwise `/` is division.
+Without this disambiguation a regex like `/^\//` reads as `/` (division),
+then `^`, `\`, `/`, `/` — and the final `//` pair fakes a line comment
+that swallows the rest of the line, eating any `)` that closes the
+enclosing call.
+*/
+const REGEX_PREFIX_KEYWORDS = new Set([
+    'return',
+    'typeof',
+    'instanceof',
+    'in',
+    'of',
+    'delete',
+    'void',
+    'await',
+    'yield',
+    'new',
+    'throw',
+    'case',
+    'do',
+])
+
+const REGEX_PUNCTUATION = new Set([
+    '(',
+    '[',
+    '{',
+    ',',
+    ';',
+    ':',
+    '?',
+    '!',
+    '&',
+    '|',
+    '^',
+    '~',
+    '+',
+    '-',
+    '*',
+    '%',
+    '<',
+    '>',
+    '=',
+    '/',
+])
+
+function isRegexContext(source: string, slashIndex: number): boolean {
+    let i = slashIndex - 1
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    if (i < 0) {
+        return true
+    }
+    const prev = source[i] as string
+    if (REGEX_PUNCTUATION.has(prev)) {
+        return true
+    }
+    if (isIdentPart(prev)) {
+        let start = i
+        while (start > 0 && isIdentPart(source[start - 1])) {
+            start--
+        }
+        return REGEX_PREFIX_KEYWORDS.has(source.slice(start, i + 1))
+    }
+    return false
+}
+
+/*
+Walks past a regex literal body, respecting character classes (`[...]`
+where `/` is literal) and backslash escapes, then consumes trailing
+flag identifiers. Returns the index immediately after the regex. An
+unterminated regex (newline before closing `/`) returns the newline
+position so the outer scanner can resume normally on the next line.
+*/
+function skipRegex(source: string, start: number): number {
+    let i = start
+    let inClass = false
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '\\') {
+            i += 2
+            continue
+        }
+        if (c === '\n') {
+            return i
+        }
+        if (inClass) {
+            if (c === ']') {
+                inClass = false
+            }
+            i++
+            continue
+        }
+        if (c === '[') {
+            inClass = true
+            i++
+            continue
+        }
+        if (c === '/') {
+            let j = i + 1
+            while (j < source.length && isIdentPart(source[j])) {
+                j++
+            }
+            return j
+        }
+        i++
+    }
+    return source.length
+}

package/src/lib/shared/forwardHeaders.ts

@@ -0,0 +1,41 @@
+import { extraForwardHeaders } from './extraForwardHeaders.ts'
+
+/*
+Headers belte forwards from an inbound HTTP/MCP request onto every
+synthesized in-process rpc Request — cookies + bearer auth + the four
+forwarding hints proxies set when terminating TLS in front of the app.
+defineVerb uses this when an SSR pass calls a verb in-process; the MCP
+dispatcher uses it when piping a tool invocation through verb.fetch.
+
+WARNING — this is an allowlist: every inbound header NOT named here (and
+not added via app.forwardHeaders) is DROPPED on the in-process path. A
+handler that reads e.g. `accept-language`, an idempotency key, a trace
+header, or a custom `x-tenant-*` during SSR or an MCP call sees nothing,
+and the call still succeeds with a degraded request. Add the names you
+rely on via the `forwardHeaders` export in src/app.ts.
+
+Centralised so both call sites can't drift on which headers are
+considered "auth/identity" context.
+*/
+export const FORWARDED_HEADERS = [
+    'cookie',
+    'authorization',
+    'x-forwarded-for',
+    'x-forwarded-proto',
+    'x-forwarded-host',
+]
+
+export function forwardHeaders(source: Headers): Headers {
+    const headers = new Headers()
+    // Iterate the two fixed arrays directly — both are request-invariant, so
+    // a spread-concat here would allocate a fresh array on every SSR/MCP call.
+    const copy = (name: string) => {
+        const value = source.get(name)
+        if (value) {
+            headers.set(name, value)
+        }
+    }
+    FORWARDED_HEADERS.forEach(copy)
+    extraForwardHeaders.get().forEach(copy)
+    return headers
+}

package/src/lib/shared/getRemoteMeta.ts

@@ -0,0 +1,5 @@
+import { remoteMetaStore } from './remoteMetaStore.ts'
+
+export function getRemoteMeta(promise: Promise<unknown>): Request | undefined {
+    return remoteMetaStore.get(promise)?.()
+}

package/src/lib/shared/globalCacheStore.ts

@@ -0,0 +1,15 @@
+import { activeCacheStore } from './activeCacheStore.ts'
+import { globalCacheStoreSlot } from './globalCacheStoreSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Resolves the process-level CacheStore that `cache(fn, { global: true })` entries
+live in. The server entry registers a module-singleton resolver so the store
+survives across requests; the client points it at the active tab store. When no
+resolver is registered (isolated tests, or a client that never set one) it falls
+back to the active store, so `global` degrades to request/tab-scoped rather than
+throwing.
+*/
+export function globalCacheStore(): CacheStore {
+    return globalCacheStoreSlot.resolver?.() ?? activeCacheStore()
+}

package/src/lib/shared/globalCacheStoreSlot.ts

@@ -0,0 +1,14 @@
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Slot for the process-level cache store resolver used by cache() entries opting
+into `global: true`. The server entry registers a module-singleton store that
+outlives any one request; the client entry points it at its single tab store so
+`global` is a no-op there. Unset means no global store is registered, in which
+case globalCacheStore() falls back to the active (request/tab) store.
+*/
+export const globalCacheStoreSlot: {
+    resolver: (() => CacheStore | undefined) | undefined
+} = {
+    resolver: undefined,
+}

package/src/lib/shared/importNamesToStrip.ts

@@ -0,0 +1,13 @@
+import { BELTE_PACKAGE_NAME } from './BELTE_PACKAGE_NAME.ts'
+
+/*
+The names a user may import a belte server helper under: the project's chosen
+alias plus the canonical package name. The resolver strips the dead import
+under both so it can't side-effect-load the server stub into the client
+bundle. When the alias already is the canonical name, there's only one.
+*/
+export function importNamesToStrip(importName: string): string[] {
+    return importName === BELTE_PACKAGE_NAME
+        ? [BELTE_PACKAGE_NAME]
+        : [importName, BELTE_PACKAGE_NAME]
+}

package/src/lib/shared/invalidateEvent.ts

@@ -0,0 +1,11 @@
+import type { CacheInvalidation } from './types/CacheInvalidation.ts'
+
+/*
+Constructs the cache store's 'invalidate' event from the keys an
+invalidation touched. The single definition of the event name + detail
+shape, so the two dispatch sites (cache.invalidate and the streamed-
+resolution placeholder settle) can't drift from the cache store's listener.
+*/
+export function invalidateEvent(keys: Iterable<string>): CustomEvent<CacheInvalidation> {
+    return new CustomEvent('invalidate', { detail: new Set(keys) })
+}

package/src/lib/shared/isCompileTarget.ts

@@ -0,0 +1,15 @@
+import type { CompileTarget } from './types/CompileTarget.ts'
+
+/* The canonical cross-compile targets, as a runtime set for validation. */
+const COMPILE_TARGETS: readonly CompileTarget[] = [
+    'bun-darwin-arm64',
+    'bun-darwin-x64',
+    'bun-linux-arm64',
+    'bun-linux-x64',
+    'bun-windows-x64',
+]
+
+/* Narrows an arbitrary string to a known CompileTarget. */
+export function isCompileTarget(value: string): value is CompileTarget {
+    return (COMPILE_TARGETS as readonly string[]).includes(value)
+}

package/src/lib/shared/isDebugEnabled.ts

@@ -0,0 +1,23 @@
+/*
+Matches the conventions of the `debug` npm package.
+DEBUG="belte"   → enables "belte"
+DEBUG="belte:*" → enables "belte" and "belte:anything"
+DEBUG="*"       → enables everything
+DEBUG="a,belte" → comma-separated list
+*/
+export function isDebugEnabled(name: string, env: string | undefined = process.env.DEBUG): boolean {
+    if (!env) {
+        return false
+    }
+    return env.split(',').some((raw) => {
+        const pattern = raw.trim()
+        if (pattern === '*') {
+            return true
+        }
+        if (pattern.endsWith(':*')) {
+            const prefix = pattern.slice(0, -2)
+            return name === prefix || name.startsWith(`${prefix}:`)
+        }
+        return pattern === name
+    })
+}

package/src/lib/shared/isModuleNotFound.ts

@@ -0,0 +1,16 @@
+/*
+True when an error from a dynamic `import(...)` is a module-resolution
+failure (the package isn't installed) rather than an error thrown while
+the module's own code ran. Lets optional-peer loads swallow "not installed"
+while letting a genuine load-time failure surface. Bun surfaces the former
+as a ResolveMessage / ERR_MODULE_NOT_FOUND; the message check is the
+cross-runtime fallback.
+*/
+export function isModuleNotFound(error: unknown): boolean {
+    const code = (error as { code?: string })?.code
+    if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') {
+        return true
+    }
+    const message = error instanceof Error ? error.message : String(error)
+    return /cannot find (module|package)|failed to resolve/i.test(message)
+}

package/src/lib/shared/isReadOnlyMethod.ts

@@ -0,0 +1,14 @@
+import type { HttpVerb } from './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 './STREAMING_CONTENT_TYPES.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))
+}