@abide/abide 0.28.0

package/src/lib/shared/createPushIterator.ts

@@ -0,0 +1,127 @@
+/*
+Single-slot-mailbox AsyncIterator factory shared by the in-process
+socket fan-out (defineSocket) and the client-side ws proxy
+(socketProxy). Callers push values, signal end, signal an error, or
+signal a transport disconnect; the iterator drains a queue then awaits
+the next push. Cancellation runs the optional `onClose` so subscribers
+can drop their backref. `disconnect()` is terminal like `error()` but
+throws the typed SocketDisconnectedError so consumers can tell a
+recoverable transport loss from an application error.
+
+The pending-value buffer is bounded: a subscriber whose `next()` falls
+behind a chatty producer would otherwise grow it without limit, which on
+the server is a remotely-triggerable memory-exhaustion vector. At the cap
+the oldest pending value is dropped (live fan-out is latest-wins) so
+memory stays bounded; terminal end/error slots are always appended and
+never dropped.
+*/
+
+import { SocketDisconnectedError } from './SocketDisconnectedError.ts'
+
+type Slot<T> =
+    | { kind: 'value'; value: T }
+    | { kind: 'control'; run: () => void }
+    | { kind: 'end' }
+    | { kind: 'error'; message: string }
+    | { kind: 'disconnect' }
+
+export type PushIterator<T> = AsyncIterator<T, void, undefined> & {
+    push(value: T): void
+    /*
+    Queues an in-band signal (e.g. the replay/live boundary): `run` executes
+    inside next() when drained, strictly ordered against pushed values, and
+    is invisible to the consumer — next() continues to the following slot.
+    Never dropped by the buffer cap.
+    */
+    control(run: () => void): void
+    end(): void
+    error(message: string): void
+    disconnect(): void
+}
+
+const DEFAULT_MAX_BUFFER = 1024
+
+export function createPushIterator<T>(
+    onClose?: () => void,
+    maxBuffer = DEFAULT_MAX_BUFFER,
+): PushIterator<T> {
+    const buffer: Slot<T>[] = []
+    let waiter: ((slot: Slot<T>) => void) | undefined
+    let closed = false
+
+    function deliver(slot: Slot<T>): void {
+        if (closed) {
+            return
+        }
+        if (waiter) {
+            const wake = waiter
+            waiter = undefined
+            wake(slot)
+            return
+        }
+        // Drop the oldest pending value before exceeding the cap.
+        if (slot.kind === 'value' && buffer.length >= maxBuffer) {
+            buffer.shift()
+        }
+        buffer.push(slot)
+    }
+
+    function close(): void {
+        if (closed) {
+            return
+        }
+        closed = true
+        onClose?.()
+    }
+
+    return {
+        push(value) {
+            deliver({ kind: 'value', value })
+        },
+        control(run) {
+            deliver({ kind: 'control', run })
+        },
+        end() {
+            deliver({ kind: 'end' })
+        },
+        error(message) {
+            deliver({ kind: 'error', message })
+        },
+        disconnect() {
+            deliver({ kind: 'disconnect' })
+        },
+        async next() {
+            while (true) {
+                if (closed) {
+                    return { value: undefined, done: true }
+                }
+                const slot = buffer.shift() ?? (await new Promise<Slot<T>>((r) => (waiter = r)))
+                if (slot.kind === 'control') {
+                    slot.run()
+                    continue
+                }
+                if (slot.kind === 'end') {
+                    close()
+                    return { value: undefined, done: true }
+                }
+                if (slot.kind === 'error') {
+                    close()
+                    throw new Error(slot.message)
+                }
+                if (slot.kind === 'disconnect') {
+                    close()
+                    throw new SocketDisconnectedError()
+                }
+                return { value: slot.value, done: false }
+            }
+        },
+        async return() {
+            if (!closed) {
+                close()
+                waiter?.({ kind: 'end' })
+                waiter = undefined
+            }
+            return { value: undefined, done: true }
+        },
+    }
+}

package/src/lib/shared/createRemoteFunction.ts

@@ -0,0 +1,122 @@
+import { decodeResponse } from './decodeResponse.ts'
+import { HttpError } from './HttpError.ts'
+import { keyForRemoteCall } from './keyForRemoteCall.ts'
+import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
+import { recordRemoteMeta } from './recordRemoteMeta.ts'
+import { subscribableFromResponse } from './subscribableFromResponse.ts'
+import type { ClientFlags } from './types/ClientFlags.ts'
+import type { HttpVerb } from './types/HttpVerb.ts'
+import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
+import type { RemoteFunction } from './types/RemoteFunction.ts'
+import type { Subscribable } from './types/Subscribable.ts'
+
+/*
+Assembles the public RemoteFunction shape used identically by the
+server-side defineVerb (in-process handler invocation) and the
+client-side remoteProxy (network fetch). Centralising the wiring here
+keeps the call/raw/stream/fetch semantics — including WeakMap meta
+recording, Content-Type decode, and Subscribable derivation — in one
+place so the two halves can't drift.
+
+- `buildRequest(args)` synthesizes the Request a meta reader (cache()) or
+  the client invoke needs. Server uses the inbound request's URL as the
+  base; client uses window.location. The result is memoised inside the
+  per-call `getRequest` thunk so the Request is built at most once per
+  call regardless of how many readers pull on it.
+- `invoke(args, getRequest)` actually runs the call: server defineVerb
+  runs the handler and ignores `getRequest`; client remoteProxy calls
+  `fetch(getRequest())`. The thunk lets the server skip the Request
+  allocation entirely on the SSR hot path — the only consumer that ever
+  forces it is cache(), via the meta thunk recorded below.
+- `parseArgsForFetch` is optional and only set by the server, so the
+  framework's router can call `.fetch(inboundRequest)` and have the
+  handler receive parsed args. Client `remoteProxy.fetch` just
+  forwards the request through invoke().
+*/
+export function createRemoteFunction<Args, Return>(opts: {
+    method: HttpVerb
+    url: string
+    clients: ClientFlags
+    /* Server-side only: exempts a mutating verb from the router's same-origin CSRF gate. */
+    crossOrigin?: boolean
+    buildRequest: (args: Args | undefined) => Request
+    invoke: (args: Args | undefined, getRequest: () => Request) => Promise<Response>
+    parseArgsForFetch?: (request: Request) => Promise<Args | undefined>
+}): RemoteFunction<Args, Return> {
+    const { method, url, clients, crossOrigin, buildRequest, invoke, parseArgsForFetch } = opts
+
+    /*
+    Dispatch is the one-stop entry for both the plain call (no prebuilt
+    Request) and the fetch path (router hands us the inbound Request as
+    `prebuilt`). The `getRequest` thunk lazily synthesizes — or
+    short-circuits to the prebuilt one — and caches the result so the
+    client invoke + the cache meta reader share a single Request.
+    */
+    function dispatch(args: Args | undefined, prebuilt?: Request): Promise<Response> {
+        let cached = prebuilt
+        function getRequest(): Request {
+            if (cached === undefined) {
+                cached = buildRequest(args)
+            }
+            return cached
+        }
+        const promise = invoke(args, getRequest)
+        recordRemoteMeta(promise, getRequest)
+        return promise
+    }
+
+    /*
+    A body verb may receive a FormData in place of typed Args (the upload
+    escape hatch). It flows through dispatch only into buildRpcRequest /
+    keyForRemoteCall, both of which take it as-is, so the cast to Args is a
+    contained type lie — buildRpcRequest's `instanceof FormData` branch handles
+    it at runtime.
+    */
+    function rawCall(args: Args | FormData): Promise<Response> {
+        return dispatch(args as Args)
+    }
+    rawCall.method = method
+    rawCall.url = url
+    /* Non-enumerable brand on both variants; see REMOTE_FUNCTION. */
+    Object.defineProperty(rawCall, REMOTE_FUNCTION, { value: true })
+    const raw = rawCall as RawRemoteFunction<Args>
+
+    function callable(args: Args | FormData): Promise<Return> {
+        return raw(args).then(decodeResponse) as Promise<Return>
+    }
+    callable.method = method
+    callable.url = url
+    callable.clients = clients
+    callable.crossOrigin = crossOrigin
+    callable.raw = raw
+    callable.stream = (args?: Args | FormData): Subscribable<Return> => {
+        return subscribableFromResponse(keyForRemoteCall(method, url, args), () =>
+            raw(args as Args),
+        )
+    }
+    Object.defineProperty(callable, REMOTE_FUNCTION, { value: true })
+    callable.fetch = parseArgsForFetch
+        ? async (request: Request): Promise<Response> => {
+              let args: Args | undefined
+              try {
+                  args = await parseArgsForFetch(request)
+              } catch (error) {
+                  /*
+                  Parse-stage rejections that already chose their wire shape
+                  (readBodyWithinLimit's 413) return it; anything else (e.g.
+                  malformed JSON) keeps propagating to the scope's catch.
+                  Handler errors are outside this try on purpose — throwing
+                  is the app.handleError path, `return error(...)` the wire one.
+                  */
+                  if (error instanceof HttpError) {
+                      return error.response
+                  }
+                  throw error
+              }
+              return dispatch(args, request)
+          }
+        : (request: Request): Promise<Response> => {
+              return dispatch(undefined, request)
+          }
+    return callable as RemoteFunction<Args, Return>
+}

package/src/lib/shared/createSubscriber.ts

@@ -0,0 +1,55 @@
+import { createSignalNode } from '../ui/runtime/createSignalNode.ts'
+import { OWNER } from '../ui/runtime/OWNER.ts'
+import { track } from '../ui/runtime/track.ts'
+import { trigger } from '../ui/runtime/trigger.ts'
+
+/*
+abide-ui-native `createSubscriber`: open-on-first-read, close-on-last-reader,
+grounded in abide's own signal core (no external reactivity library). The
+reactivity substrate lives in `../ui/runtime` — pure, DOM-free signal primitives
+that the isomorphic shared layer reuses, the same way the cache reuses other
+shared machinery.
+
+`start` opens the resource and returns a cleanup; the returned `subscribe()`,
+read inside a abide-ui effect/derived, registers that reader (via `track`) and
+re-runs it whenever `update` fires.
+
+Lifecycle rides the signal node's observer set. The resource opens SYNCHRONOUSLY
+on the first tracked read — a consumer like tail() flips state in
+`start` that its very read path checks, so a deferred open would let it read a
+not-yet-open entry and evict it. The close is deferred to a microtask scheduled on
+a reader's scope disposal: an effect re-run momentarily drops then re-adds itself
+as an observer, so checking on the microtask (not synchronously) avoids tearing the
+resource down and reopening it across a re-run. Called outside any tracking scope,
+`track` is a no-op, observers stay empty, and the resource never opens — matching
+the open-on-first-read contract.
+*/
+// @readme plumbing
+export function createSubscriber(start: (update: () => void) => () => void): () => void {
+    const node = createSignalNode(undefined)
+    let cleanup: (() => void) | undefined
+    let closeScheduled = false
+
+    const maybeClose = (): void => {
+        closeScheduled = false
+        if (node.subsHead === undefined && cleanup !== undefined) {
+            cleanup()
+            cleanup = undefined
+        }
+    }
+
+    return () => {
+        track(node)
+        /* Open eagerly on the first reader within a tracking scope. */
+        if (cleanup === undefined && node.subsHead !== undefined) {
+            cleanup = start(() => trigger(node))
+        }
+        /* Close once this reader's scope tears down and no observers remain. */
+        OWNER.current?.push(() => {
+            if (!closeScheduled) {
+                closeScheduled = true
+                queueMicrotask(maybeClose)
+            }
+        })
+    }
+}

package/src/lib/shared/createTraceContext.ts

@@ -0,0 +1,21 @@
+import { parseTraceparent } from './parseTraceparent.ts'
+import { randomHexId } from './randomHexId.ts'
+import type { TraceContext } from './types/TraceContext.ts'
+
+/*
+Builds this request's trace position from an inbound `traceparent` header.
+Prefer-incoming rule: a valid header keeps its trace id and sampling flags
+(abide never overwrites a trace someone upstream started); the header's span
+id becomes `parentSpanId`. Either way abide mints a fresh `spanId` for this
+request — the one outbound hops carry as parent. No header (or a malformed
+one) starts a new trace, sampled ('01') so downstream recorders keep it.
+*/
+export function createTraceContext(header: string | null | undefined): TraceContext {
+    const incoming = header ? parseTraceparent(header) : undefined
+    return {
+        traceId: incoming?.traceId ?? randomHexId(16),
+        spanId: randomHexId(8),
+        parentSpanId: incoming?.spanId,
+        flags: incoming?.flags ?? '01',
+    }
+}

package/src/lib/shared/dataDirEnvPath.ts

@@ -0,0 +1,12 @@
+import { join } from 'node:path'
+import { appDataDir } from './appDataDir.ts'
+
+/*
+The user's `.env` in the program's per-user data dir — the cwd-independent
+config layer the connect-screen form writes and the server loads first at
+boot. One statement of the location so the writer (controlServerWorker), the
+boot loader (loadEnvFromDataDir), and the embedded-port resolver can't drift.
+*/
+export function dataDirEnvPath(programName: string): string {
+    return join(appDataDir(programName), '.env')
+}

package/src/lib/shared/decodeResponse.ts

@@ -0,0 +1,47 @@
+import { HttpError } from './HttpError.ts'
+import { isStreamingResponse } from './isStreamingResponse.ts'
+
+/*
+Decodes a Response into the natural body value based on Content-Type:
+  application/json (or `*\/+json`) → parsed JSON
+  text/*                           → string
+  204 No Content / empty body      → undefined
+  everything else                  → Blob
+
+Non-2xx responses throw HttpError so the happy path never has to check
+`.ok` — error handling moves into try/catch (or unhandled exception
+propagation), and the success path types as Promise<Return> cleanly.
+
+Streaming Content-Types (SSE / JSONL / NDJSON) throw a clear error
+rather than silently doing the wrong thing: response.text() would hang
+forever on a never-ending body and response.json() would fail mid-parse.
+The error points callers at the right tools — `tail(fn.stream(args))`
+for a shared reactive view, or `fn.stream(args)` directly for a fresh
+per-call AsyncIterable — both of which know how to consume the body
+frame-by-frame.
+
+Callers that need headers, streaming, or per-status branching should use
+the `.raw(args)` escape hatch on the remote function instead — that
+returns the underlying Response untouched.
+*/
+export async function decodeResponse(response: Response): Promise<unknown> {
+    if (!response.ok) {
+        throw new HttpError(response)
+    }
+    if (response.status === 204) {
+        return undefined
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (isStreamingResponse(response)) {
+        throw new Error(
+            `[abide] response at ${response.url} is a stream (${contentType}) — use tail(fn.stream(args)) for a reactive view, or fn.stream(args) for per-call iteration, instead of awaiting the bare call or cache()`,
+        )
+    }
+    if (contentType.includes('json')) {
+        return response.json()
+    }
+    if (contentType.startsWith('text/')) {
+        return response.text()
+    }
+    return response.blob()
+}

package/src/lib/shared/detectTarget.ts

@@ -0,0 +1,27 @@
+import type { CompileTarget } from './types/CompileTarget.ts'
+
+/*
+Picks the Bun compile target matching the current host. Throws if the
+platform/arch pair isn't one of the supported Bun standalone targets — the
+CLI's `--target` flag is the escape hatch for cross-compilation.
+*/
+const HOST_TO_TARGET: Record<string, CompileTarget> = {
+    'darwin-arm64': 'bun-darwin-arm64',
+    'darwin-x64': 'bun-darwin-x64',
+    'linux-arm64': 'bun-linux-arm64',
+    'linux-x64': 'bun-linux-x64',
+    'win32-x64': 'bun-windows-x64',
+}
+
+export function detectTarget(
+    platform: NodeJS.Platform = process.platform,
+    arch: NodeJS.Architecture = process.arch,
+): CompileTarget {
+    const target = HOST_TO_TARGET[`${platform}-${arch}`]
+    if (!target) {
+        throw new Error(
+            `[abide] unsupported host platform ${platform}/${arch}. Pass --target=<bun-...> explicitly.`,
+        )
+    }
+    return target
+}

package/src/lib/shared/detectVerbMethod.ts

@@ -0,0 +1,17 @@
+import type { HttpVerb } from './types/HttpVerb.ts'
+
+/*
+Reads the HTTP verb of an $rpc module from its source. Every file under
+src/server/rpc/ follows the convention `export const <name> = GET(fn)` (the
+verb helper picks the method, possibly with an explicit generic
+`GET<{…}>(fn)`), so the helper name at the export is the method. Returns
+undefined when no verb export matches — the caller skips the file rather
+than guessing. Used by the rpc.d.ts codegen to type url() against
+query-carrying verbs; matching the same convention the bundler rewrites
+keeps the two from drifting.
+*/
+const VERB_EXPORT = /export\s+const\s+\w+\s*=\s*(GET|POST|PUT|PATCH|DELETE|HEAD)\s*[<(]/
+
+export function detectVerbMethod(source: string): HttpVerb | undefined {
+    return (source.match(VERB_EXPORT)?.[1] as HttpVerb | undefined) ?? undefined
+}

package/src/lib/shared/emitLogRecord.ts

@@ -0,0 +1,190 @@
+import { logTapSlot } from './logTapSlot.ts'
+import { requestScopeSlot } from './requestScopeSlot.ts'
+import type { LogRecord } from './types/LogRecord.ts'
+import type { LogVoice } from './types/LogVoice.ts'
+
+const hasBun = typeof Bun !== 'undefined'
+const useColor = hasBun && Bun.enableANSIColors
+const RESET = '\x1b[0m'
+const DIM = '\x1b[2m'
+
+// Wraps `text` in a Bun-resolved ANSI color escape; no-op when colors are disabled or unavailable (browser).
+function paint(color: string, text: string): string {
+    if (!useColor) {
+        return text
+    }
+    return `${Bun.color(color, 'ansi-256')}${text}${RESET}`
+}
+
+// Applies the ANSI dim attribute; no-op when colors are disabled.
+function dim(text: string): string {
+    if (!useColor) {
+        return text
+    }
+    return `${DIM}${text}${RESET}`
+}
+
+// Maps an HTTP status code to a color that matches the usual server-log convention.
+function colorStatus(status: number): string {
+    if (status >= 500) {
+        return paint('red', String(status))
+    }
+    if (status >= 400) {
+        return paint('yellow', String(status))
+    }
+    if (status >= 300) {
+        return paint('cyan', String(status))
+    }
+    return paint('green', String(status))
+}
+
+// Maps an HTTP method to a color so the request log line is easy to scan.
+function colorMethod(method: string): string {
+    const upper = method.toUpperCase()
+    if (upper === 'GET') {
+        return paint('green', upper)
+    }
+    if (upper === 'POST') {
+        return paint('blue', upper)
+    }
+    if (upper === 'PUT' || upper === 'PATCH') {
+        return paint('yellow', upper)
+    }
+    if (upper === 'DELETE') {
+        return paint('red', upper)
+    }
+    return paint('white', upper)
+}
+
+/* json emission is a server concern (stdout ingestion); the browser console always gets tsv. Read per call — log volume never makes this hot. */
+function useJson(): boolean {
+    return typeof process !== 'undefined' && process.env.ABIDE_LOG_FORMAT === 'json'
+}
+
+/* `+12.30ms` — unpadded: the timing trails the line, so no width keeps columns aligned. */
+function formatElapsed(ms: number): string {
+    return `+${ms.toFixed(2)}ms`
+}
+
+/*
+Builds the record from the emission's own fields plus the ambient request
+scope (trace, elapsed, verb+path), then renders it through the active
+formatter. The scope is read at emission time so a record emitted from a
+stream-flush callback re-entered into the scope still carries its context.
+Internal seam shared by the public logger and the framework's closing-record
+emitter; console.* is the side effect — logging is intentionally impure.
+*/
+export function emitLogRecord(fields: Omit<LogRecord, 'ts'>, voice?: LogVoice): void {
+    const scope = requestScopeSlot.resolver?.()
+    const record: LogRecord = { ts: Date.now(), ...fields }
+    if (scope) {
+        record.trace = scope.trace.traceId
+        record.requestSpan = scope.trace.spanId
+        record.parentSpan = scope.trace.parentSpanId
+        record.elapsedMs = scope.elapsedMs
+        record.method = fields.method ?? scope.method
+        record.path = fields.path ?? scope.path
+    }
+    // Hand the finished record to the inspector tap (when installed) before
+    // formatting — it observes the same structure the console receives.
+    logTapSlot.tap?.(record)
+    if (useJson()) {
+        printJson(record)
+        return
+    }
+    printTsv(record, voice)
+}
+
+/*
+One JSON object per line on the level-matched console stream. Undefined
+fields drop out of JSON.stringify; non-serialisable `data` degrades to its
+String form rather than killing the record.
+*/
+function printJson(record: LogRecord): void {
+    const payload = { ...record, ts: new Date(record.ts).toISOString() }
+    let line: string
+    try {
+        line = JSON.stringify(payload)
+    } catch {
+        line = JSON.stringify({ ...payload, data: String(record.data) })
+    }
+    consoleFor(record.level)(line)
+}
+
+function consoleFor(level: LogRecord['level']): (...args: unknown[]) => void {
+    if (level === 'error') {
+        return console.error
+    }
+    if (level === 'warn') {
+        return console.warn
+    }
+    return console.log
+}
+
+/*
+The unified tsv line (the default format): tab-separated
+`<trace8>	<verb path>	[channel] <message>	+0.00ms`. Inside a
+request scope the trace column leads and the elapsed-at-emission timing
+trails; a closing record emitted outside one (asset hits sidestep the scope)
+pads a blank trace column and trails its serve duration instead, so request
+lines stay aligned whatever produced them. Every record speaks on a channel
+(the app name, 'abide', or a diagnostic channel), shown as a dim `[name]`
+tag opening the message field. The verb+path pair is one field — it's the
+line's anchor unit — and the tag folds into the message field so field
+positions stay stable for cut/awk consumers.
+*/
+function printTsv(record: LogRecord, voice?: LogVoice): void {
+    const fields: string[] = []
+    const closing = record.status !== undefined
+    if (record.trace) {
+        fields.push(dim(record.trace.slice(0, 8)))
+    } else if (closing) {
+        fields.push(' '.repeat(8))
+    }
+    if (record.method && record.path) {
+        fields.push(`${colorMethod(record.method)} ${record.path}`)
+    }
+    const message: string[] = []
+    if (record.channel) {
+        message.push(dim(`[${record.channel}]`))
+    }
+    message.push(tsvBody(record, voice))
+    fields.push(message.join(' '))
+    if (record.elapsedMs !== undefined) {
+        fields.push(dim(formatElapsed(record.elapsedMs)))
+    } else if (closing && record.durationMs !== undefined) {
+        fields.push(dim(formatElapsed(record.durationMs)))
+    }
+    const writer = consoleFor(record.level)
+    if (record.data !== undefined) {
+        writer(fields.join('\t'), record.data)
+        return
+    }
+    writer(fields.join('\t'))
+}
+
+// The message field after the context fields, styled by level/kind/voice.
+function tsvBody(record: LogRecord, voice?: LogVoice): string {
+    /* Closing request record: status is the message; the duration rides the elapsed column. */
+    if (record.status !== undefined) {
+        return colorStatus(record.status)
+    }
+    /* log.trace operation record: name + settled duration. */
+    if (record.name !== undefined && record.durationMs !== undefined) {
+        const failure = record.level === 'error' ? ` ${paint('red', record.msg)}` : ''
+        return `${record.name} ${dim(`${record.durationMs.toFixed(2)}ms`)}${failure}`
+    }
+    if (record.level === 'error') {
+        return paint('red', record.stack ?? record.msg)
+    }
+    if (record.level === 'warn') {
+        return paint('yellow', record.msg)
+    }
+    if (voice === 'success') {
+        return paint('green', record.msg)
+    }
+    if (voice === 'detail') {
+        return dim(record.msg)
+    }
+    return record.msg
+}

package/src/lib/shared/exeSuffix.ts

@@ -0,0 +1,9 @@
+import type { CompileTarget } from './types/CompileTarget.ts'
+
+/*
+Executable filename suffix for a compile target — `.exe` on Windows targets,
+empty elsewhere. Single source so every cross-compile output path agrees.
+*/
+export function exeSuffix(target: CompileTarget): string {
+    return target.includes('windows') ? '.exe' : ''
+}

package/src/lib/shared/exitOnBuildFailure.ts

@@ -0,0 +1,17 @@
+import type { BuildOutput } from 'bun'
+import { abideLog } from './abideLog.ts'
+
+/*
+On a failed Bun.build(), logs each diagnostic and exits non-zero. Every abide
+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) => {
+        abideLog.error(entry)
+    })
+    process.exit(1)
+}

package/src/lib/shared/extraForwardHeaders.ts

@@ -0,0 +1,16 @@
+/*
+App-configured inbound header names to forward onto in-process rpc Requests,
+on top of the built-in FORWARDED_HEADERS. Set once at boot from
+app.forwardHeaders so the SSR in-process path (defineVerb) and the MCP
+dispatcher honour the same list without re-reading app config per call. A
+module-level slot rather than threaded config because both call sites are deep
+in the request path and the value is fixed for the process lifetime.
+*/
+let names: readonly string[] = []
+
+export const extraForwardHeaders = {
+    get: (): readonly string[] => names,
+    set: (configured: readonly string[]): void => {
+        names = configured
+    },
+}

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(/\.[^.]+$/, '')
+}