@briancray/belte 0.1.0

package/src/lib/server/cli/buildEnvContent.ts

@@ -0,0 +1,18 @@
+/*
+Generates the `.env` file content shipped alongside the CLI binary in
+the download tarball. APP_URL is always present (derived from the
+inbound request's origin); APP_TOKEN is included only when the inbound
+request carried an Authorization: Bearer header, so an authenticated
+download bakes the caller's credential into the binary's env.
+
+Tokens forward verbatim — the framework doesn't issue or refresh; the
+user's auth code at the actual RPC endpoints validates whatever value
+arrives back in subsequent calls.
+*/
+export function buildEnvContent(appUrl: string, bearerToken: string | undefined): string {
+    const lines = [`APP_URL=${appUrl}`]
+    if (bearerToken) {
+        lines.push(`APP_TOKEN=${bearerToken}`)
+    }
+    return `${lines.join('\n')}\n`
+}

package/src/lib/server/cli/createTarGz.ts

@@ -0,0 +1,76 @@
+/*
+Minimal ustar tarball writer. Each entry is a 512-byte header followed
+by the content padded to a 512-byte boundary; the archive ends with two
+512-byte zero blocks. After assembly the buffer is gzipped via
+Bun.gzipSync — no external `tar` invocation, no extra deps.
+
+Format constraints:
+  - File names ≤ 100 bytes (we never write longer paths).
+  - Numeric fields are zero-padded octal ASCII strings (POSIX rule).
+  - Checksum is the sum of all header bytes treating the checksum
+    field as spaces; encoded as 6 octal digits + NUL + space.
+*/
+
+type TarEntry = {
+    name: string
+    content: Uint8Array
+    mode?: number
+}
+
+const BLOCK = 512
+const ENC = new TextEncoder()
+
+function writeString(buf: Uint8Array, offset: number, length: number, value: string): void {
+    const bytes = ENC.encode(value)
+    buf.set(bytes.subarray(0, Math.min(bytes.length, length)), offset)
+}
+
+function writeOctal(buf: Uint8Array, offset: number, length: number, value: number): void {
+    // length-1 octal digits + trailing NUL
+    const oct = value.toString(8).padStart(length - 1, '0')
+    writeString(buf, offset, length - 1, oct)
+    buf[offset + length - 1] = 0
+}
+
+function buildHeader(entry: TarEntry): Uint8Array {
+    const header = new Uint8Array(BLOCK)
+    writeString(header, 0, 100, entry.name)
+    writeOctal(header, 100, 8, entry.mode ?? 0o644)
+    writeOctal(header, 108, 8, 0)
+    writeOctal(header, 116, 8, 0)
+    writeOctal(header, 124, 12, entry.content.length)
+    writeOctal(header, 136, 12, Math.floor(Date.now() / 1000))
+    header.fill(0x20, 148, 156)
+    header[156] = 0x30 // '0' = regular file
+    writeString(header, 257, 6, 'ustar\0')
+    writeString(header, 263, 2, '00')
+    // Checksum: sum of all bytes with checksum field treated as spaces.
+    let sum = 0
+    for (let index = 0; index < BLOCK; index++) {
+        sum += header[index] ?? 0
+    }
+    writeOctal(header, 148, 7, sum)
+    header[155] = 0x20 // trailing space after checksum digits
+    return header
+}
+
+/*
+Builds a gzipped tarball from the given entries and returns the bytes.
+Sized eagerly (sum of headers + padded contents + 2 trailing blocks).
+*/
+export function createTarGz(entries: TarEntry[]): Uint8Array {
+    let totalSize = BLOCK * 2 // trailing zero blocks
+    for (const entry of entries) {
+        totalSize += BLOCK
+        totalSize += Math.ceil(entry.content.length / BLOCK) * BLOCK
+    }
+    const tar = new Uint8Array(totalSize)
+    let offset = 0
+    for (const entry of entries) {
+        tar.set(buildHeader(entry), offset)
+        offset += BLOCK
+        tar.set(entry.content, offset)
+        offset += Math.ceil(entry.content.length / BLOCK) * BLOCK
+    }
+    return Bun.gzipSync(tar)
+}

package/src/lib/server/cli/handleCliDownload.ts

@@ -0,0 +1,124 @@
+import { existsSync, statSync } from 'node:fs'
+import { NO_STORE } from '../../shared/cacheControlValues.ts'
+import { log } from '../../shared/log.ts'
+import { normalizeTarget } from '../../shared/normalizeTarget.ts'
+import { buildEnvContent } from './buildEnvContent.ts'
+import { createTarGz } from './createTarGz.ts'
+import { maxSourceMtime } from './maxSourceMtime.ts'
+
+/*
+Process-wide per-platform build coalescing. Two concurrent curls for
+the same /__belte/cli/<platform> share one promise; the later requests
+await the same one the first installed. The promise both runs the
+freshness check AND the rebuild, so the map insertion is synchronous
+relative to the first request's entry into the function — no window
+between an `await` and `pendingBuilds.set` for a second concurrent
+request to slip through and fire its own buildCli against the same
+output paths.
+*/
+const pendingBuilds = new Map<string, Promise<string | undefined>>()
+
+async function ensurePlatformBinary(
+    platform: string,
+    programName: string,
+    cwd: string,
+): Promise<string | undefined> {
+    const existing = pendingBuilds.get(platform)
+    if (existing) {
+        return existing
+    }
+    const promise = computeBinary(platform, programName, cwd)
+    pendingBuilds.set(platform, promise)
+    /*
+    Drop the entry after settlement so a later request rebuilds if the
+    source has changed again. Identity-guard so a still-pending entry
+    installed by a follow-up request isn't evicted by ours.
+    */
+    promise.finally(() => {
+        if (pendingBuilds.get(platform) === promise) {
+            pendingBuilds.delete(platform)
+        }
+    })
+    return promise
+}
+
+async function computeBinary(
+    platform: string,
+    programName: string,
+    cwd: string,
+): Promise<string | undefined> {
+    const binaryPath = `${cwd}/dist/cli-thin/${platform}/${programName}`
+    /*
+    On-disk binary is fresh when it exists AND its mtime beats the
+    newest rpc/socket source mtime. The mtime check catches the
+    common dev iteration where the user edits an rpc handler but
+    didn't run `belte cli` again. Other source paths (project lib,
+    transitive imports) fall back to manual rebuild.
+    */
+    if (existsSync(binaryPath)) {
+        const binaryMtime = statSync(binaryPath).mtimeMs
+        const sourceMtime = await maxSourceMtime(cwd)
+        if (binaryMtime >= sourceMtime) {
+            return binaryPath
+        }
+        log.info(`thin cli for ${platform} is stale — rebuilding`)
+    }
+    try {
+        log.info(`lazy-building thin cli for ${platform}…`)
+        // Lazy-import buildCli so the build pipeline isn't pulled into
+        // production processes that never serve a download.
+        const { buildCli } = await import('../../../buildCli.ts')
+        await buildCli({
+            cwd,
+            platforms: [normalizeTarget(platform)],
+            thin: true,
+        })
+        return existsSync(binaryPath) ? binaryPath : undefined
+    } catch (error) {
+        log.error(error)
+        return undefined
+    }
+}
+
+/*
+Handles GET /__belte/cli/<platform> — streams a gzipped tarball
+containing the platform-specific thin binary + a `.env` carrying
+APP_URL (and APP_TOKEN if the inbound request was authenticated).
+
+Thin binaries live at `dist/cli-thin/<platform>/<programName>`
+(produced by `belte cli` with APP_URL set). Missing platforms produce
+404 — the install script reports it, doesn't try to fall back.
+*/
+export async function handleCliDownload(
+    request: Request,
+    platform: string,
+    programName: string,
+    cwd: string,
+): Promise<Response> {
+    const binaryPath = await ensurePlatformBinary(platform, programName, cwd)
+    if (!binaryPath) {
+        return new Response(`unknown platform: ${platform}`, {
+            status: 404,
+            headers: { 'Cache-Control': NO_STORE },
+        })
+    }
+    const url = new URL(request.url)
+    const appUrl = `${url.protocol}//${url.host}`
+    const auth = request.headers.get('authorization')
+    const bearer =
+        auth && auth.toLowerCase().startsWith('bearer ') ? auth.slice('bearer '.length) : undefined
+    const envContent = buildEnvContent(appUrl, bearer)
+
+    const binaryBytes = await Bun.file(binaryPath).bytes()
+    const archive = createTarGz([
+        { name: programName, content: binaryBytes, mode: 0o755 },
+        { name: '.env', content: new TextEncoder().encode(envContent), mode: 0o644 },
+    ])
+    return new Response(archive, {
+        headers: {
+            'Content-Type': 'application/gzip',
+            'Content-Disposition': `attachment; filename="${programName}-${platform}.tar.gz"`,
+            'Cache-Control': NO_STORE,
+        },
+    })
+}

package/src/lib/server/cli/handleCliInstall.ts

@@ -0,0 +1,20 @@
+import { NO_STORE } from '../../shared/cacheControlValues.ts'
+import { installScript } from './installScript.ts'
+
+/*
+Handles GET /__belte/cli — returns the platform-detecting shell script.
+Authoritative URL for the tarball is derived from the inbound request
+(so the script's curl line points at whatever host the user reached us
+on). Program name is the bundler-emitted `belte:cli-name` value.
+*/
+export function handleCliInstall(request: Request, programName: string): Response {
+    const url = new URL(request.url)
+    const appUrl = `${url.protocol}//${url.host}`
+    const script = installScript(appUrl, programName)
+    return new Response(script, {
+        headers: {
+            'Content-Type': 'text/x-shellscript; charset=utf-8',
+            'Cache-Control': NO_STORE,
+        },
+    })
+}

package/src/lib/server/cli/installScript.ts

@@ -0,0 +1,29 @@
+/*
+The shell script returned by `GET /__belte/cli` (no platform). Detects
+uname OS + arch, normalises common arch aliases, then curls the right
+platform-specific tarball and extracts it into `$BELTE_INSTALL_DIR`
+(default `~/.local/bin`). The tarball already contains the `.env` next
+to the binary — no separate config write step in the script.
+
+The script is rendered server-side so `<APP_URL>` is the request's own
+origin and the embedded curl URL needs no escaping or quoting beyond
+basic shell hygiene.
+*/
+export function installScript(appUrl: string, programName: string): string {
+    return `#!/usr/bin/env sh
+set -e
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+case "$(uname -m)" in
+  x86_64|amd64)   ARCH=x64 ;;
+  aarch64|arm64)  ARCH=arm64 ;;
+  *)              echo "unsupported architecture: $(uname -m)" >&2 ; exit 1 ;;
+esac
+INSTALL_DIR="\${BELTE_INSTALL_DIR:-$HOME/.local/bin}"
+mkdir -p "$INSTALL_DIR"
+URL="${appUrl.replace(/\/$/, '')}/__belte/cli/\${OS}-\${ARCH}"
+echo "installing ${programName} from $URL into $INSTALL_DIR"
+curl -fsSL "$URL" | tar -xz -C "$INSTALL_DIR"
+echo "installed: $INSTALL_DIR/${programName}"
+echo "ensure $INSTALL_DIR is in your PATH"
+`
+}

package/src/lib/server/cli/maxSourceMtime.ts

@@ -0,0 +1,27 @@
+import { existsSync, statSync } from 'node:fs'
+import { Glob } from 'bun'
+
+/*
+Returns the most-recent mtime across every rpc + socket source file in
+the project, or 0 when both directories are absent. The lazy CLI
+download path compares this to the binary's mtime to decide whether to
+rebuild — covers the common dev iteration of "user edited an rpc
+handler" without needing to scan transitively-imported modules.
+*/
+export async function maxSourceMtime(cwd: string): Promise<number> {
+    const roots = [`${cwd}/src/server/rpc`, `${cwd}/src/server/sockets`]
+    let newest = 0
+    for (const root of roots) {
+        if (!existsSync(root)) {
+            continue
+        }
+        const files = new Glob('**/*.ts').scan({ cwd: root, onlyFiles: true })
+        for await (const file of files) {
+            const stat = statSync(`${root}/${file}`)
+            if (stat.mtimeMs > newest) {
+                newest = stat.mtimeMs
+            }
+        }
+    }
+    return newest
+}

package/src/lib/server/error.ts

@@ -0,0 +1,56 @@
+import { NO_STORE } from '../shared/cacheControlValues.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+
+/*
+Plain-text error Response — clearer than constructing a Response by
+hand with a status and a text body, and shaped so the client's
+HttpError carries the message verbatim (`HttpError.response.text()`
+returns the message, no parsing).
+
+  if (!order) return error(404, 'order not found')
+
+`message` defaults to the status's standard reason phrase when
+omitted (e.g. `error(404)` body = 'Not Found'). The body is
+text/plain so intermediaries don't try to render or sniff it.
+
+To short-circuit a handler instead of returning, `throw new Error(...)`
+or `throw new HttpError(error(...))` — the framework's `app.handleError`
+hook catches thrown errors. This helper deliberately returns a Response
+rather than throwing one so a single `return error(...)` is the
+expected pattern, with the same control flow as `return json(...)`.
+*/
+const STATUS_TEXT: Record<number, string> = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    409: 'Conflict',
+    410: 'Gone',
+    422: 'Unprocessable Content',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    501: 'Not Implemented',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+}
+
+/*
+Body type is `never` because `error()` only travels the non-2xx path on
+the wire — the caller's `await fn(args)` throws `HttpError` and never
+resolves to this response's body. Returning a TypedResponse<never> lets
+the union of branches in a handler narrow to whatever the success
+branch carries (`TypedResponse<{user}> | TypedResponse<never>` → Return
+= {user}).
+*/
+export function error(status: number, message?: string): TypedResponse<never> {
+    const body = message ?? STATUS_TEXT[status] ?? `HTTP ${status}`
+    return new Response(body, {
+        status,
+        headers: {
+            'Content-Type': 'text/plain; charset=utf-8',
+            'Cache-Control': NO_STORE,
+        },
+    }) as TypedResponse<never>
+}

package/src/lib/server/json.ts

@@ -0,0 +1,28 @@
+import { NO_STORE } from '../shared/cacheControlValues.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+
+/*
+JSON Response with rpc-friendly defaults — same shape as
+`Response.json(data, init)`, except `Cache-Control: no-store` is set
+unless the caller overrides it. Intermediary caches (browsers, CDNs,
+shared proxies) shouldn't cache rpc replies by default; the framework's
+own per-request cache handles in-process dedupe.
+
+  export const getOrder = GET<{ id: string }>(async ({ id }) =>
+      json(await db.getOrder(id)),
+  )
+
+The return type carries `T` as a phantom brand so the verb helper can
+infer the caller-facing `Return` from the handler body — no need to
+annotate `GET<Args, Return>` just to type the response shape.
+
+For non-default cache policy pass `init.headers`; explicit
+`cache-control` wins over the default.
+*/
+export function json<T>(data: T, init?: ResponseInit): TypedResponse<T> {
+    const headers = new Headers(init?.headers)
+    if (!headers.has('cache-control')) {
+        headers.set('cache-control', NO_STORE)
+    }
+    return Response.json(data, { ...init, headers }) as TypedResponse<T>
+}

package/src/lib/server/jsonl.ts

@@ -0,0 +1,40 @@
+/*
+Wraps an AsyncIterable<Frame> in a Response whose body is JSON Lines
+(application/jsonl) — one JSON value per line, terminated by `\n`. Used
+inside an rpc handler to turn a generator into a streaming HTTP response
+that `subscribe(fn.stream)(args)` consumes frame-by-frame on the client.
+
+  export const orderFeed = GET<Args>((args) =>
+      jsonl(async function* () {
+          for await (const order of db.watchOrders(args)) yield order
+      }())
+  )
+
+Cancellation flows from the consumer through ReadableStream's `cancel`
+into `iter.return()` so the handler's `for await` exits via its normal
+control path (DB cursors, file handles, etc. get to release in finally).
+
+Errors thrown by the generator are emitted as a final
+`{"$error":"<message>"}` line before the stream closes. The convention
+keeps the format JSON-safe and lets the consumer distinguish "stream
+ended cleanly" from "handler threw" without a side-channel. The full
+error is logged server-side via the framework's error handler — only the
+message crosses the wire.
+*/
+import { NO_STORE } from '../shared/cacheControlValues.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { streamFromIterator } from './runtime/streamFromIterator.ts'
+
+export function jsonl<Frame>(iterable: AsyncIterable<Frame>): TypedResponse<Frame> {
+    const body = streamFromIterator(iterable, {
+        encodeFrame: (value) => `${JSON.stringify(value)}\n`,
+        encodeError: (message) => `${JSON.stringify({ $error: message })}\n`,
+    })
+    return new Response(body, {
+        headers: {
+            'Content-Type': 'application/jsonl; charset=utf-8',
+            'Cache-Control': NO_STORE,
+            'X-Content-Type-Options': 'nosniff',
+        },
+    }) as TypedResponse<Frame>
+}

package/src/lib/server/prompt.ts

@@ -0,0 +1,30 @@
+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/definePrompt.ts

@@ -0,0 +1,20 @@
+import { registerPrompt } from './registerPrompt.ts'
+import type { Prompt } from './types/Prompt.ts'
+import type { PromptOptions } from './types/PromptOptions.ts'
+
+/*
+Builds a Prompt from a name + options. The bundler rewrites every
+`export const NAME = prompt(opts)` inside `src/server/prompts/<file>.ts`
+into `__belteDefinePrompt__("<name>", opts)` so the file path becomes the
+prompt's identity. Registers itself so the MCP dispatcher can enumerate
+and render it.
+*/
+export function definePrompt(name: string, opts: PromptOptions): Prompt {
+    const self: Prompt = {
+        name,
+        description: opts.description,
+        render: opts.render,
+    }
+    registerPrompt({ prompt: self, schema: opts.schema, jsonSchema: opts.jsonSchema })
+    return self
+}

package/src/lib/server/prompts/promptRegistry.ts

@@ -0,0 +1,9 @@
+import type { PromptRegistryEntry } from './types/PromptRegistryEntry.ts'
+
+/*
+Process-wide registry of every prompt declared in the app. definePrompt
+inserts on first construction (eagerly when the registry loader walks the
+prompts manifest at MCP boot). The MCP server reads this to build its
+`prompts/list` + `prompts/get` responses.
+*/
+export const promptRegistry = new Map<string, PromptRegistryEntry>()

package/src/lib/server/prompts/registerPrompt.ts

@@ -0,0 +1,6 @@
+import { promptRegistry } from './promptRegistry.ts'
+import type { PromptRegistryEntry } from './types/PromptRegistryEntry.ts'
+
+export function registerPrompt(entry: PromptRegistryEntry): void {
+    promptRegistry.set(entry.prompt.name, entry)
+}

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

@@ -0,0 +1,14 @@
+import type { PromptMessage } from './PromptMessage.ts'
+
+/*
+An MCP prompt declared once with `prompt(opts)` inside a file under
+`src/server/prompts/`. The bundler stamps in the `name` from the file
+path; `render(args)` produces the messages returned by `prompts/get`.
+Prompts are MCP-only — there is no client-side counterpart, so the
+shape carries no ClientFlags.
+*/
+export type Prompt<Args = Record<string, string>> = {
+    readonly name: string
+    readonly description: string | undefined
+    render(args: Args): PromptMessage[] | string | Promise<PromptMessage[] | string>
+}

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

@@ -0,0 +1,10 @@
+/*
+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/server/prompts/types/PromptOptions.ts

@@ -0,0 +1,17 @@
+import type { StandardSchemaV1 } from '../../rpc/types/StandardSchemaV1.ts'
+import type { PromptMessage } from './PromptMessage.ts'
+
+/*
+Server-side options passed when declaring a prompt via `prompt(opts)`.
+MCP prompts are read-only templates: `render(args)` turns the caller's
+arguments into one or more chat messages. The optional Standard Schema
+both validates incoming arguments and supplies the argument list MCP
+advertises in `prompts/list` (top-level properties + required array).
+All of this is server-only — prompts are never imported by client code.
+*/
+export type PromptOptions<Args = Record<string, string>> = {
+    description?: string
+    schema?: StandardSchemaV1
+    jsonSchema?: Record<string, unknown>
+    render: (args: Args) => PromptMessage[] | string | Promise<PromptMessage[] | string>
+}

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

@@ -0,0 +1,15 @@
+import type { StandardSchemaV1 } from '../../rpc/types/StandardSchemaV1.ts'
+import type { Prompt } from './Prompt.ts'
+
+/*
+Per-prompt registry record. The MCP dispatcher enumerates this to build
+`prompts/list` (description + arguments from the schema) and to dispatch
+`prompts/get` (validate args against the schema, then render). Schema +
+jsonSchema stay off the public Prompt shape so the render closure isn't
+burdened with metadata it never reads.
+*/
+export type PromptRegistryEntry = {
+    prompt: Prompt
+    schema: StandardSchemaV1 | undefined
+    jsonSchema: Record<string, unknown> | undefined
+}

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

@@ -0,0 +1,10 @@
+import type { Prompt } from './Prompt.ts'
+
+/*
+Manifest of prompt-name → module loader. Produced by the resolver plugin
+from each `.ts` under src/server/prompts/. Each module has exactly one
+named export, a Prompt whose `.name` was stamped in by the bundler
+rewrite. The registry loader imports every module once so the MCP
+dispatcher can enumerate the full prompt surface.
+*/
+export type PromptRoutes = Record<string, () => Promise<Record<string, Prompt>>>

package/src/lib/server/redirect.ts

@@ -0,0 +1,37 @@
+/*
+Redirect Response with belte-friendly ergonomics — accepts relative
+URLs (the platform's `Response.redirect` throws on them), defaults to
+302, and matches the helper-style call site of `json`/`error` for
+visual consistency inside a handler.
+
+  return redirect('/login')              // 302 to /login
+  return redirect('/articles/1', 301)    // permanent
+  return redirect(externalUrl, 307)      // preserve method (POST stays POST)
+
+Status guidance:
+- 301 — moved permanently (cacheable; browsers may swap method to GET)
+- 302 — found / temporary (default; browsers may swap method to GET)
+- 303 — "after a POST, GET this" (forces GET on the follow-up)
+- 307 — temporary, preserve method
+- 308 — permanent, preserve method
+*/
+import { NO_STORE } from '../shared/cacheControlValues.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+
+type RedirectStatus = 301 | 302 | 303 | 307 | 308
+
+/*
+Return type is `TypedResponse<never>` for the same reason `error()` is —
+the wire response is a 3xx with no body the caller resolves to, so it
+must not pollute the inferred `Return` of a route that conditionally
+redirects vs returns json.
+*/
+export function redirect(url: string, status: RedirectStatus = 302): TypedResponse<never> {
+    return new Response(null, {
+        status,
+        headers: {
+            Location: url,
+            'Cache-Control': NO_STORE,
+        },
+    }) as TypedResponse<never>
+}

package/src/lib/server/request.ts

@@ -0,0 +1,18 @@
+import { requestContext } from './runtime/requestContext.ts'
+
+/*
+Returns the inbound Request for the current SSR/RPC pass. Implemented as an
+AsyncLocalStorage lookup over the per-request store the server installs at
+the fetch boundary. Throws if called outside a request scope (e.g. from
+top-level module code or from app.ts init) — silent undefined would mask
+the misuse.
+*/
+export function request(): Request {
+    const store = requestContext.getStore()
+    if (!store) {
+        throw new Error(
+            '[belte] request() called outside a request scope — it only resolves while an SSR render or rpc handler is in flight',
+        )
+    }
+    return store.req
+}