@abide/abide 0.28.0

package/src/lib/server/rpc/types/RemoteHandler.ts

@@ -0,0 +1,27 @@
+import type { TypedResponse } from './TypedResponse.ts'
+
+/*
+Handler signature for verb-defined remote functions. Args is `undefined` for
+GETs/DELETEs with no query, JSON-shaped objects for json bodies, and
+form-shaped objects for form-encoded bodies. For a multipart upload it's the
+text fields (`inputSchema`) intersected with the validated File parts
+(`filesSchema`), merged into one bag. For a raw binary body Args is `undefined`
+— read the stream via `request()` from `abide/server` instead.
+
+Return is the value type the call site sees after Content-Type-driven
+decoding (a parsed object for JSON, a string for text/*, a Blob otherwise,
+`undefined` for 204). The handler must return a Response at runtime; the
+`TypedResponse<Return>` brand on `json`/`error`/`redirect`/`jsonl`/`sse`
+carries the body shape through the function's inferred return type so the
+verb helper can infer `Return` automatically — no need to annotate
+`GET<Args, Return>` when the handler returns one of the respond helpers.
+A bare `new Response(...)` is still acceptable: the brand is optional, so
+untagged Responses fall back to `Return = unknown`.
+
+Handlers that need the inbound Request (headers, `request.signal`, …) read
+it via `request()` from `abide/server` rather than a handler parameter, so
+the signature stays a single parsed-`args` bag.
+*/
+export type RemoteHandler<Args, Return> = (
+    args: Args,
+) => TypedResponse<Return> | Promise<TypedResponse<Return>>

package/src/lib/server/rpc/types/RemoteRoutes.ts

@@ -0,0 +1,13 @@
+import type { RemoteFunction } from '../../../shared/types/RemoteFunction.ts'
+
+/*
+Manifest of RPC URL → module loader. Produced by the resolver plugin from
+every `.ts` under src/server/rpc — each file maps to one URL (derived from its
+path under `$rpc`, prefixed with `/rpc/`). Each module has exactly one
+named export, a RemoteFunction whose `.method` and `.url` were stamped in
+by the bundler rewrite.
+*/
+export type RemoteRoutes = Record<
+    string,
+    () => Promise<Record<string, RemoteFunction<unknown, unknown>>>
+>

package/src/lib/server/rpc/types/TypedResponse.ts

@@ -0,0 +1,18 @@
+/*
+A `Response` tagged with the body type the framework will hand back to
+callers after Content-Type-driven decoding. The tag is phantom — it
+adds no runtime field, only a type-level slot so the verb helpers can
+infer `Return` from the handler's return type instead of forcing every
+route to annotate it via `GET<Args, Return>`.
+
+The respond helpers (`json<T>`, `error`, `redirect`, `jsonl<F>`,
+`sse<F>`) all return a `TypedResponse<T>`, so a handler ending in
+`return json({ user })` exposes `{ user: ... }` as its body type; the
+verb overload picks it up via `RemoteHandler<Args, Return>`.
+
+`T` is optional on the brand so a plain `new Response(...)` (untagged)
+remains assignable to `TypedResponse<unknown>`; in that case `Return`
+just falls back to its `unknown` default, matching pre-existing
+behaviour for handlers that build Responses by hand.
+*/
+export type TypedResponse<T> = Response & { readonly __body?: T }

package/src/lib/server/rpc/types/VerbHelper.ts

@@ -0,0 +1,87 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { RemoteFunction } from '../../../shared/types/RemoteFunction.ts'
+import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
+import type { RemoteHandler } from './RemoteHandler.ts'
+
+/*
+Shared signature for every verb helper (GET / POST / …). Three overloads:
+
+  - `Verb(fn, { inputSchema, outputSchema?, clients? })` — `Args` infers
+    from `InferInput<InputSchema>`, the handler receives
+    `InferOutput<InputSchema>`. Generic order is `<Return, InputSchema>` so
+    users can override `Return` while letting `InputSchema` infer from
+    `opts.inputSchema`. `outputSchema` is an optional Standard Schema for
+    the success body — it feeds the OpenAPI 200 response and the MCP tool
+    `outputSchema`. JSON Schema is projected from each schema's own
+    `toJSONSchema()` (wrap with withJsonSchema if the library lacks one).
+    `clients` controls which surfaces (browser / mcp / cli) expose this verb.
+    `crossOrigin: true` exempts a mutating verb from the router's same-origin
+    CSRF gate — by default a browser request whose Origin doesn't match the
+    app's own host is refused with 403 on every non-GET/HEAD verb.
+    `maxBodySize` caps the body's actual received bytes (413 past it),
+    enforced before parsing; omitted, the only ceiling is Bun.serve's
+    server-wide maxRequestBodySize. `timeout` (ms) bounds the handler's
+    execution on every surface (SSR / MCP / CLI / network) — a 504 once
+    exceeded; on the network path it also aborts request().signal so a
+    handler's `fetch(ext, { signal: request().signal })` is cancelled, not
+    just abandoned.
+  - `Verb(fn, { clients })` — schemaless but with explicit client
+    targeting (e.g. server-internal RPC with `clients: { browser: false }`).
+  - `Verb(fn)` — bare handler. `Args` and `Return` come from the handler
+    type; `Return` is usually inferred via the `TypedResponse<T>` brand on
+    `json`/`error`/`redirect`/`jsonl`/`sse`.
+*/
+export type VerbHelper = {
+    /*
+    `Verb(fn, { inputSchema, filesSchema, … })` — multipart upload. The
+    handler receives the text fields (`InferOutput<InputSchema>`) intersected
+    with the validated File parts (`InferOutput<FilesSchema>`); both are merged
+    into one args bag. The call site sends a FormData (RemoteFunction's call
+    accepts it), since a File can't ride a JSON body. filesSchema stays off the
+    JSON-Schema projection — a File has no honest conversion (see
+    jsonSchemaForSchema) — so only inputSchema feeds MCP/CLI/OpenAPI.
+    */
+    <
+        Return = unknown,
+        InputSchema extends StandardSchemaV1 = StandardSchemaV1,
+        FilesSchema extends StandardSchemaV1 = StandardSchemaV1,
+    >(
+        fn: RemoteHandler<
+            StandardSchemaV1.InferOutput<InputSchema> & StandardSchemaV1.InferOutput<FilesSchema>,
+            Return
+        >,
+        opts: {
+            inputSchema: InputSchema
+            filesSchema: FilesSchema
+            outputSchema?: StandardSchemaV1
+            clients?: Partial<ClientFlags>
+            crossOrigin?: boolean
+            maxBodySize?: number
+            timeout?: number
+        },
+    ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, Return>
+    <Return = unknown, InputSchema extends StandardSchemaV1 = StandardSchemaV1>(
+        fn: RemoteHandler<StandardSchemaV1.InferOutput<InputSchema>, Return>,
+        opts: {
+            inputSchema: InputSchema
+            outputSchema?: StandardSchemaV1
+            clients?: Partial<ClientFlags>
+            crossOrigin?: boolean
+            maxBodySize?: number
+            timeout?: number
+        },
+    ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, Return>
+    <Args = undefined, Return = unknown>(
+        fn: RemoteHandler<Args, Return>,
+        opts: {
+            outputSchema?: StandardSchemaV1
+            clients?: Partial<ClientFlags>
+            crossOrigin?: boolean
+            maxBodySize?: number
+            timeout?: number
+        },
+    ): RemoteFunction<Args, Return>
+    <Args = undefined, Return = unknown>(
+        fn: RemoteHandler<Args, Return>,
+    ): RemoteFunction<Args, Return>
+}

package/src/lib/server/rpc/types/VerbRegistryEntry.ts

@@ -0,0 +1,35 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { RemoteFunction } from '../../../shared/types/RemoteFunction.ts'
+import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
+
+/*
+Per-verb registry record on the server side. MCP and CLI enumerate this
+to discover which RPCs are advertised (clients flags) and what shapes
+they expect/return. The schemas and resolved clients stay off the public
+RemoteFunction shape so the browser-side proxy doesn't need to carry
+server-only state.
+
+`inputSchema` validates the argument bag and feeds the MCP tool
+`inputSchema` / OpenAPI parameters; `outputSchema` describes the success
+body and feeds the OpenAPI 200 response + MCP tool `outputSchema`. Each
+projects to JSON Schema via its own `toJSONSchema()` (jsonSchemaForSchema) —
+schemas whose library lacks one are wrapped with withJsonSchema.
+
+`filesSchema` validates the File parts of a multipart body, kept separate
+from `inputSchema` because a File has no honest JSON-Schema conversion — it
+stays out of the MCP/CLI projection that `inputSchema` feeds, and the OpenAPI
+multipart body advertises the file parts generically as binary.
+*/
+export type VerbRegistryEntry = {
+    remote: RemoteFunction<unknown, unknown>
+    inputSchema: StandardSchemaV1 | undefined
+    outputSchema: StandardSchemaV1 | undefined
+    filesSchema: StandardSchemaV1 | undefined
+    clients: ClientFlags
+    /* The verb's declared opts, recorded so introspection (inspector) can report
+       the deadline/body-cap/CSRF-exemption a handler runs under. Undefined = the
+       framework default (no deadline, Bun's server-wide body ceiling, gated). */
+    timeout: number | undefined
+    maxBodySize: number | undefined
+    crossOrigin: boolean | undefined
+}

package/src/lib/server/rpc/unprocessed.ts

@@ -0,0 +1,14 @@
+import type { RemoteFunction } from '../../shared/types/RemoteFunction.ts'
+
+/*
+Verb helpers (GET / POST / …) are placeholders — the bundler rewrites every
+`export const x = GET(fn)` inside `src/server/rpc/<file>.ts` into a call to
+defineVerb (server target) or remoteProxy (client target). If a call slips
+through, the bundler plugin didn't process the file; throwing here surfaces
+that cleanly instead of silently returning undefined.
+*/
+export function unprocessed<Args, Return>(verb: string): RemoteFunction<Args, Return> {
+    throw new Error(
+        `[abide] \`${verb}\` was called outside an $rpc module — verb helpers are only valid as the value of \`export const <filename> = ...\` inside a file under src/server/rpc/`,
+    )
+}

package/src/lib/server/rpc/verbRegistry.ts

@@ -0,0 +1,11 @@
+import type { VerbRegistryEntry } from './types/VerbRegistryEntry.ts'
+
+/*
+Process-wide registry of every verb-bound RPC declared in the app.
+defineVerb inserts on first construction (which happens at module-load
+time inside the rpc dispatcher cache or eagerly when MCP / CLI walks the
+rpc manifest). MCP server reads this to build its tools list; the CLI
+binary reads it to generate subcommands. The browser path never touches
+this — the client stub has no schema or clients metadata to register.
+*/
+export const verbRegistry = new Map<string, VerbRegistryEntry>()

package/src/lib/server/runtime/DEFAULT_PORT.ts

@@ -0,0 +1,6 @@
+/*
+The port scanning starts from when no PORT is configured. Every selector (the
+real listener, the embedded launcher, the dev orchestrator) scans upward from
+here so all modes land on the same predictable 3000+ address.
+*/
+export const DEFAULT_PORT = 3000

package/src/lib/server/runtime/DEV_READY_MESSAGE.ts

@@ -0,0 +1,6 @@
+// IPC payload the dev server sends its orchestrator parent (via process.send)
+// once its listener is up and init() has run. The orchestrator retires the
+// previous worker only after this arrives — workers overlap on the dev port via
+// reusePort, so the port never goes dark across a restart. Shared so producer
+// (createServer) and consumer (devEntry) can't drift.
+export const DEV_READY_MESSAGE = 'abide:ready'

package/src/lib/server/runtime/DEV_REBUILD_MESSAGE.ts

@@ -0,0 +1,4 @@
+// IPC payload the dev server sends its orchestrator parent (via process.send) to
+// request a rebuild + restart. Shared so producer (createServer) and consumer
+// (devEntry) can't drift.
+export const DEV_REBUILD_MESSAGE = 'abide:reload'

package/src/lib/server/runtime/DEV_RELOAD_CLIENT_SCRIPT.ts

@@ -0,0 +1,107 @@
+/*
+Dev-only live-reload client, injected into the served shell when the server
+runs under `abide dev`. It opens an EventSource to /__abide/dev; each
+connection's first event carries the worker's reload stamp — `{ structure,
+cssHref }` (devClientFingerprint). The channel only drops when the dev
+orchestrator swaps the server after a rebuild, and on reconnect:
+  - `structure` changed → reload (any non-CSS edit).
+  - only `cssHref` changed → swap the entry stylesheet's `<link>` in place,
+    so a CSS edit restyles the live page with no reload and no state loss.
+  - both equal (server-only edit) → keep the page alive.
+Self-managed retry keeps the first reconnect fast (250ms) so a rebuild swap
+recovers quickly, then backs off exponentially up to a 5s cap — a server that
+stays down (dev stopped) settles to one attempt every 5s instead of flooding
+the network, and still reconnects on its own if the server comes back. The
+backoff resets once a connection opens.
+
+Hidden tabs hold no connection: the channel closes on `visibilitychange:
+hidden` and reopens on visible, where the reconnect's first event carries
+whatever the current worker announces — a rebuild that happened while the tab
+slept still reloads it. The initial connect runs even when the page loads
+hidden (the baseline must be the serving worker's stamp, captured before a swap
+can replace it) and releases itself once that first event lands.
+*/
+import { DEV_HOT_PREFIX } from '../../shared/DEV_HOT_PREFIX.ts'
+import { DEV_RELOAD_PATH } from '../../shared/DEV_RELOAD_PATH.ts'
+
+export const DEV_RELOAD_CLIENT_SCRIPT = `<script>
+window.__abideDev = true;
+;(() => {
+  let stamp
+  let source
+  let retryTimer
+  let retryDelay = 250
+  function disconnect() {
+    clearTimeout(retryTimer)
+    if (source) {
+      source.close()
+      source = undefined
+    }
+  }
+  function swapCss(href) {
+    const links = document.querySelectorAll('link[rel="stylesheet"]')
+    for (const link of links) {
+      const current = link.getAttribute('href') || ''
+      if (current.indexOf('/_app/') !== -1 && current.slice(-4) === '.css') {
+        link.href = href
+        return
+      }
+    }
+  }
+  function swapComponents(next, prev) {
+    const components = next.components || {}
+    const before = prev.components || {}
+    for (const id in components) {
+      if (components[id] !== before[id]) {
+        // The hot module sources its runtime from window.__abide and self-invokes
+        // hotReplace; a load/compile failure or a component with no live instance
+        // falls back to a reload.
+        import('${DEV_HOT_PREFIX}' + id + '?v=' + components[id]).catch(() => location.reload())
+      }
+    }
+  }
+  function connect() {
+    if (source) {
+      return
+    }
+    source = new EventSource('${DEV_RELOAD_PATH}')
+    source.onopen = () => {
+      retryDelay = 250
+    }
+    source.onmessage = (event) => {
+      const next = JSON.parse(event.data)
+      if (stamp === undefined) {
+        stamp = next
+        if (document.hidden) {
+          disconnect()
+        }
+        return
+      }
+      if (next.structure !== stamp.structure) {
+        location.reload()
+        return
+      }
+      if (next.cssHref && next.cssHref !== stamp.cssHref) {
+        swapCss(next.cssHref)
+      }
+      swapComponents(next, stamp)
+      stamp = next
+    }
+    source.onerror = () => {
+      disconnect()
+      if (!document.hidden) {
+        retryTimer = setTimeout(connect, retryDelay)
+        retryDelay = Math.min(retryDelay * 2, 5000)
+      }
+    }
+  }
+  document.addEventListener('visibilitychange', () => {
+    if (document.hidden) {
+      disconnect()
+    } else {
+      connect()
+    }
+  })
+  connect()
+})()
+</script>`

package/src/lib/server/runtime/SSR_SWAP_SCRIPT.ts

@@ -0,0 +1,16 @@
+/*
+The tiny inline script the abide-ui SSR stream ships in <head>. For each streamed
+`<abide-resolve data-id data-resume>` frame it registers the resolved value into
+`window.__abideResume` (the resume manifest hydration reads) and swaps the resolved
+markup into the matching `<!--abide:await:ID-->…<!--/abide:await:ID-->` boundary —
+so the pending shell paints instantly and each value lands as it arrives, before
+the client bundle even loads. Vanilla and self-contained (no framework runtime),
+minified to one line so it inlines cheaply ahead of the document body.
+*/
+export const SSR_SWAP_SCRIPT =
+    "function __abideSwap(){var f=document.querySelector('abide-resolve');while(f){" +
+    "var id=f.getAttribute('data-id'),w=document.createTreeWalker(document.body,NodeFilter.SHOW_COMMENT),o=null,c;" +
+    "try{(window.__abideResume=window.__abideResume||{})[id]=JSON.parse(f.getAttribute('data-resume')||'null');}catch(e){}" +
+    "while((c=w.nextNode())){if(c.data==='abide:await:'+id){o=c;break;}}" +
+    "if(o){var n=o.nextSibling;while(n&&!(n.nodeType===8&&n.data==='/abide:await:'+id)){var x=n.nextSibling;n.remove();n=x;}" +
+    "while(f.firstChild){o.parentNode.insertBefore(f.firstChild,n);}}f.remove();f=document.querySelector('abide-resolve');}}"

package/src/lib/server/runtime/acceptsGzip.ts

@@ -0,0 +1,24 @@
+/*
+Whether the client advertised gzip in Accept-Encoding. The static-asset
+servers and the dynamic-response gzip wrapper gate compressed output on this,
+so the check lives in one place. Effectively always true for browsers and most
+HTTP clients; a bare client that omits the header gets identity bytes.
+*/
+export function acceptsGzip(req: Request): boolean {
+    const header = (req.headers.get('accept-encoding') ?? '').toLowerCase()
+    /*
+    Honour q-values: `gzip;q=0` is an explicit refusal even though the substring
+    is present. Find the gzip (or wildcard) directive and reject only when its
+    quality is zero.
+    */
+    const directives = header.split(',').map((part) => part.trim())
+    // An explicit gzip directive wins over the wildcard; fall back to `*` otherwise.
+    const directive =
+        directives.find((part) => part === 'gzip' || part.startsWith('gzip;')) ??
+        directives.find((part) => part === '*' || part.startsWith('*;'))
+    if (directive === undefined) {
+        return false
+    }
+    const quality = directive.match(/;\s*q=([\d.]+)/)
+    return quality === null || Number(quality[1]) > 0
+}

package/src/lib/server/runtime/buildCacheSnapshot.ts

@@ -0,0 +1,61 @@
+import { globalCacheStore } from '../../shared/globalCacheStore.ts'
+import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import type { InspectorCacheEntry } from './types/InspectorCacheEntry.ts'
+import type { InspectorCacheSnapshot } from './types/InspectorCacheSnapshot.ts'
+
+const PREVIEW_LIMIT = 200
+
+/* A short JSON peek at a warm value, degrading non-serializable values to String. */
+function preview(value: unknown): string | undefined {
+    if (value === undefined) {
+        return undefined
+    }
+    try {
+        const json = JSON.stringify(value)
+        return json.length > PREVIEW_LIMIT ? `${json.slice(0, PREVIEW_LIMIT)}…` : json
+    } catch {
+        return String(value)
+    }
+}
+
+/* The entry's armed invalidate policy as a label, if it declared one. */
+function policyLabel(entry: CacheEntry): string | undefined {
+    const policy = entry.invalidation
+    if (!policy) {
+        return undefined
+    }
+    if (policy.debounce !== undefined) {
+        return `debounce ${policy.debounce}ms`
+    }
+    if (policy.throttle !== undefined) {
+        return `throttle ${policy.throttle}ms`
+    }
+    return undefined
+}
+
+function projectEntry(entry: CacheEntry, now: number): InspectorCacheEntry {
+    return {
+        key: entry.key,
+        status: entry.refreshing ? 'refreshing' : entry.settled ? 'settled' : 'in-flight',
+        remote: entry.request !== undefined,
+        ttl: entry.ttl,
+        expiresInMs: entry.expiresAt !== undefined ? entry.expiresAt - now : undefined,
+        scope: entry.scope ? [...entry.scope] : [],
+        value: preview(entry.value),
+        policy: policyLabel(entry),
+    }
+}
+
+/*
+Snapshots the process-level cache store (the persistent one `cache(fn, { global:
+true })` writes to) for the inspector. Read at call time, so it reflects the
+store as it stands; request-scoped stores are deliberately excluded — they're
+ephemeral and already visible as per-request cache tallies.
+*/
+export function buildCacheSnapshot(): InspectorCacheSnapshot {
+    const now = Date.now()
+    const entries = Array.from(globalCacheStore().entries.values(), (entry) =>
+        projectEntry(entry, now),
+    )
+    return { entries }
+}

package/src/lib/server/runtime/buildHealthPayload.ts

@@ -0,0 +1,34 @@
+import { ABIDE_VERSION } from '../../shared/ABIDE_VERSION.ts'
+import { abideLog } from '../../shared/abideLog.ts'
+import type { AppModule } from '../AppModule.ts'
+
+/*
+The canonical /__abide/health payload: the app health(request) hook's fields
+under the framework identity keys, which win on collision. A thrown or
+non-object hook degrades to no fields — an app bug must not masquerade as an
+unreachable server, so the base payload always builds. Shared by the
+health/identity routes and the SSR renderer's __SSR__.health seed so the
+wire and the seed can't drift.
+*/
+export async function buildHealthPayload(
+    request: Request,
+    opts: { app?: AppModule; appName: string; appVersion: string },
+): Promise<Record<string, unknown>> {
+    let fields: Record<string, unknown> = {}
+    if (opts.app?.health) {
+        try {
+            const result = await opts.app.health(request)
+            if (result && typeof result === 'object' && !Array.isArray(result)) {
+                fields = result as Record<string, unknown>
+            }
+        } catch (error) {
+            abideLog.error(error)
+        }
+    }
+    /*
+    `abide` carries the framework version — truthy for the probe check,
+    informative for skew diagnosis. The IDENTITY_PATH alias overrides it to
+    the legacy `abide: true` shape at its call site.
+    */
+    return { ...fields, abide: ABIDE_VERSION, name: opts.appName, version: opts.appVersion }
+}

package/src/lib/server/runtime/buildInspectorSurface.ts

@@ -0,0 +1,37 @@
+import { jsonSchemaForSchema } from '../../shared/jsonSchemaForSchema.ts'
+import { verbRegistry } from '../rpc/verbRegistry.ts'
+import { socketOperations } from '../sockets/socketOperations.ts'
+import { socketRegistry } from '../sockets/socketRegistry.ts'
+import type { InspectorSurface } from './types/InspectorSurface.ts'
+
+/*
+Projects the live verb + socket registries into the inspector's catalog. Read
+at call time (not cached) so verbs constructed after boot — lazily on first
+hit, or eagerly once ensureRegistriesLoaded walked the manifest — show up.
+Schemas go through jsonSchemaForSchema, the same projection MCP and OpenAPI
+use, so the three can't disagree on a verb's shape; a missing schema stays
+undefined to mark a verb that carries no machine-advertisable contract.
+*/
+export function buildInspectorSurface(): InspectorSurface {
+    const verbs = Array.from(verbRegistry.values()).map((entry) => ({
+        url: entry.remote.url,
+        method: entry.remote.method,
+        clients: { ...entry.remote.clients },
+        inputSchema: entry.inputSchema ? jsonSchemaForSchema(entry.inputSchema) : undefined,
+        outputSchema: entry.outputSchema ? jsonSchemaForSchema(entry.outputSchema) : undefined,
+        files: entry.filesSchema !== undefined,
+        timeout: entry.timeout,
+        maxBodySize: entry.maxBodySize,
+        crossOrigin: entry.crossOrigin,
+    }))
+    const sockets = Array.from(socketRegistry.values()).map((entry) => ({
+        name: entry.socket.name,
+        operations: socketOperations(entry).map((operation) => ({
+            kind: operation.kind,
+            name: operation.name,
+            method: operation.method,
+            restUrl: operation.restUrl,
+        })),
+    }))
+    return { verbs, sockets }
+}

package/src/lib/server/runtime/buildOpenApiSpec.ts

@@ -0,0 +1,106 @@
+import { carriesBodyArgs } from '../../shared/carriesBodyArgs.ts'
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import { jsonSchemaForSchema } from '../../shared/jsonSchemaForSchema.ts'
+import { verbRegistry } from '../rpc/verbRegistry.ts'
+
+/*
+Turns a verb's resolved JSON Schema into OpenAPI query parameters — one
+per top-level property, marked required when the schema lists it. Used
+for GET/DELETE/HEAD operations, which carry their args on the query
+string (mirroring buildRpcRequest).
+*/
+function queryParameters(jsonSchema: Record<string, unknown>): Array<Record<string, unknown>> {
+    const properties = jsonSchema.properties as Record<string, unknown> | undefined
+    if (!properties) {
+        return []
+    }
+    const required = new Set((jsonSchema.required as string[] | undefined) ?? [])
+    return Object.entries(properties).map(([name, schema]) => ({
+        name,
+        in: 'query',
+        required: required.has(name),
+        schema,
+    }))
+}
+
+/*
+Request body schema for a multipart upload verb: the text fields from
+inputSchema, plus the binary parts. A File has no honest
+Standard-Schema→JSON-Schema conversion, so the file parts are advertised
+generically as additional binary properties rather than named per field.
+*/
+function multipartBodySchema(textSchema: Record<string, unknown>): Record<string, unknown> {
+    const textProperties = (textSchema.properties as Record<string, unknown> | undefined) ?? {}
+    const schema: Record<string, unknown> = {
+        type: 'object',
+        properties: { ...textProperties },
+        additionalProperties: { type: 'string', format: 'binary' },
+    }
+    const required = (textSchema.required as string[] | undefined) ?? []
+    if (required.length > 0) {
+        schema.required = required
+    }
+    return schema
+}
+
+/*
+Builds an OpenAPI 3.1 document from the verb registry — the HTTP surface
+every rpc exposes regardless of which non-browser clients it advertises.
+GET/DELETE/HEAD args become query parameters; POST/PUT/PATCH args become
+a JSON request body. operationId is the folder-prefixed command name so
+it lines up with the MCP tool / CLI subcommand identifiers.
+*/
+export function buildOpenApiSpec(info: {
+    title: string
+    version: string
+}): Record<string, unknown> {
+    const paths: Record<string, Record<string, unknown>> = {}
+    for (const entry of verbRegistry.values()) {
+        const url = entry.remote.url
+        const method = entry.remote.method
+        const jsonSchema = jsonSchemaForSchema(entry.inputSchema)
+        const description = jsonSchema.description as string | undefined
+        /*
+        When the verb declares an `outputSchema`, describe the 200 body
+        with it so external tooling sees the real return shape; otherwise
+        fall back to a bare OK.
+        */
+        const okResponse: Record<string, unknown> = { description: 'OK' }
+        if (entry.outputSchema) {
+            okResponse.content = {
+                'application/json': {
+                    schema: jsonSchemaForSchema(entry.outputSchema),
+                },
+            }
+        }
+        const operation: Record<string, unknown> = {
+            operationId: commandNameForUrl(url),
+            ...(description ? { description } : {}),
+            responses: { '200': okResponse },
+        }
+        if (carriesBodyArgs(method)) {
+            operation.requestBody = entry.filesSchema
+                ? {
+                      content: {
+                          'multipart/form-data': {
+                              schema: multipartBodySchema(jsonSchema),
+                          },
+                      },
+                  }
+                : { content: { 'application/json': { schema: jsonSchema } } }
+        } else {
+            const parameters = queryParameters(jsonSchema)
+            if (parameters.length > 0) {
+                operation.parameters = parameters
+            }
+        }
+        paths[url] ??= {}
+        const path = paths[url]
+        path[method.toLowerCase()] = operation
+    }
+    return {
+        openapi: '3.1.0',
+        info: { title: info.title, version: info.version },
+        paths,
+    }
+}

package/src/lib/server/runtime/cacheControlForAsset.ts

@@ -0,0 +1,22 @@
+import {
+    IMMUTABLE_ASSET_CACHE_CONTROL,
+    REVALIDATE_ASSET_CACHE_CONTROL,
+} from '../../shared/CACHE_CONTROL_VALUES.ts'
+
+/*
+Bun.build emits `[name]-[hash].[ext]` for chunks; hash is alnum and >=8 chars.
+Source maps inherit the same name (e.g. foo-abc12345.js.map), so the suffix may be `.map`.
+*/
+const HASHED = /-[a-z0-9]{8,}\.[a-z0-9]+(\.map)?$/i
+
+/*
+Returns the right `Cache-Control` for an asset path served under `/_app/`.
+Hashed chunk filenames are content-addressed and immutable; everything else
+(the entry bundle, the html shell, etc.) must revalidate every time.
+*/
+export function cacheControlForAsset(pathname: string): string {
+    if (HASHED.test(pathname)) {
+        return IMMUTABLE_ASSET_CACHE_CONTROL
+    }
+    return REVALIDATE_ASSET_CACHE_CONTROL
+}