@abide/abide 0.49.0 → 0.50.0

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

@@ -1,7 +1,10 @@
 import { carriesBodyArgs } from '../../shared/carriesBodyArgs.ts'
 import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
 import { jsonSchemaForSchema } from '../../shared/jsonSchemaForSchema.ts'
+import type { ErrorJsonSchemas } from '../../shared/types/ErrorJsonSchemas.ts'
+import { resolveInputJsonSchema, resolveOutputJsonSchema } from '../rpc/resolveRpcJsonSchema.ts'
 import { rpcRegistry } from '../rpc/rpcRegistry.ts'
+import { STATUS_TEXT } from './STATUS_TEXT.ts'
 
 /*
 Turns a rpc's resolved JSON Schema into OpenAPI query parameters — one
@@ -43,6 +46,34 @@ function multipartBodySchema(textSchema: Record<string, unknown>): Record<string
     return schema
 }
 
+/*
+Adds one `responses[status]` entry per typed-error branch (ADR-0030) — its description is the
+status's standard reason phrase, and its `application/json` content is the error's projected `data`
+schema (omitted for a bare `{}`, a nullary error with no payload). An already-present status (the
+200, or any explicit response) is left untouched, so the success body and validation responses win a
+collision. A no-op when the handler declared no typed errors (`errorJsonSchemas` undefined).
+*/
+function mergeErrorResponses(
+    responses: Record<string, unknown>,
+    errorJsonSchemas: ErrorJsonSchemas | undefined,
+): void {
+    if (errorJsonSchemas === undefined) {
+        return
+    }
+    for (const [status, schema] of Object.entries(errorJsonSchemas)) {
+        if (responses[status] !== undefined) {
+            continue
+        }
+        const response: Record<string, unknown> = {
+            description: STATUS_TEXT[Number(status)] ?? 'Error',
+        }
+        if (Object.keys(schema).length > 0) {
+            response.content = { 'application/json': { schema } }
+        }
+        responses[status] = response
+    }
+}
+
 /*
 Builds an OpenAPI 3.1 document from the rpc registry — the HTTP surface
 every rpc exposes regardless of which non-browser clients it advertises.
@@ -58,25 +89,38 @@ export function buildOpenApiSpec(info: {
     for (const entry of rpcRegistry.values()) {
         const url = entry.remote.url
         const method = entry.remote.method
-        const jsonSchema = jsonSchemaForSchema(entry.inputSchema)
+        /*
+        Describe the parameters/request body from the `inputSchema` VALIDATOR when declared, else from
+        the handler's input parameter type projected to JSON Schema at build time (ADR-0030 input side —
+        `entry.inputJsonSchema`); otherwise the opaque fallback. The validator overrides the projection
+        (a runtime narrowing the type can't express), mirroring the 200-body output path below.
+        */
+        const jsonSchema = resolveInputJsonSchema(entry) ?? jsonSchemaForSchema(undefined)
         const description = jsonSchema.description as string | undefined
         /*
-        When the rpc declares an `outputSchema`, describe the 200 body
-        with it so external tooling sees the real return shape; otherwise
-        fall back to a bare OK.
+        Describe the 200 body from the `outputSchema` VALIDATOR when declared, else from the handler
+        return type projected to JSON Schema at build time (ADR-0030 D2 — `entry.outputJsonSchema`);
+        otherwise fall back to a bare OK. The validator overrides the projection (a runtime narrowing
+        the type can't express).
         */
         const okResponse: Record<string, unknown> = { description: 'OK' }
-        if (entry.outputSchema) {
-            okResponse.content = {
-                'application/json': {
-                    schema: jsonSchemaForSchema(entry.outputSchema),
-                },
-            }
+        const outputSchema = resolveOutputJsonSchema(entry)
+        if (outputSchema) {
+            okResponse.content = { 'application/json': { schema: outputSchema } }
         }
+        /*
+        Merge the handler's typed-error branches (ADR-0030 — `entry.errorJsonSchemas`, a status-keyed
+        data-schema map baked from the `error.typed(...)` return branches) into the responses. Each
+        status gets a `responses[status]` entry describing the error's data payload; an existing
+        response (the 200, or a future explicit entry) is never clobbered. So the 200 success body and
+        every typed error's status + payload are documented from the one handler return type.
+        */
+        const responses: Record<string, unknown> = { '200': okResponse }
+        mergeErrorResponses(responses, entry.errorJsonSchemas)
         const operation: Record<string, unknown> = {
             operationId: commandNameForUrl(url),
             ...(description ? { description } : {}),
-            responses: { '200': okResponse },
+            responses,
         }
         if (carriesBodyArgs(method)) {
             operation.requestBody = entry.filesSchema

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

@@ -18,7 +18,7 @@ const ROUTE_CHUNK = /"(\/[^"]*)"\s*:\s*\(\)\s*=>\s*import\("\.\/((?:page|layout)
 /* Reads a `_app` chunk's source by filename — gunzipped from the embedded asset map
    (standalone compile) or off disk (dev + `abide start`). Undefined on a miss. */
 function chunkReader(
-    distDir: string,
+    appDir: string,
     assets?: Assets,
 ): (name: string) => Promise<string | undefined> {
     if (assets) {
@@ -28,23 +28,25 @@ function chunkReader(
         }
     }
     return async (name) => {
-        const file = Bun.file(`${distDir}/_app/${name}`)
+        const file = Bun.file(`${appDir}/${name}`)
         return (await file.exists()) ? file.text() : undefined
     }
 }
 
-/* The hashed client entry filename (`client-<hash>.js`), from the asset map or disk. */
-async function findEntry(distDir: string, assets?: Assets): Promise<string | undefined> {
+/* The hashed client entry filename (`client-<hash>.js`), from the asset map or disk.
+   Each build's `appDir` holds exactly one entry (production `_app`, or a dev
+   generation dir), so `.find` is unambiguous. */
+async function findEntry(appDir: string, assets?: Assets): Promise<string | undefined> {
     const isEntry = (name: string): boolean => /^client-[a-z0-9]+\.js$/i.test(name)
     if (assets) {
         const key = Object.keys(assets).find((path) => isEntry(path.replace('/_app/', '')))
         return key?.replace('/_app/', '')
     }
-    if (!existsSync(`${distDir}/_app`)) {
+    if (!existsSync(appDir)) {
         return undefined
     }
     const names = await Array.fromAsync(
-        new Glob('client-*.js').scan({ cwd: `${distDir}/_app`, onlyFiles: true }),
+        new Glob('client-*.js').scan({ cwd: appDir, onlyFiles: true }),
     )
     return names.find(isEntry)
 }
@@ -64,14 +66,14 @@ stream-close instead of waterfalling after it. Returns an empty map when the bun
 absent or unparseable, so rendering degrades to the entry-only preload.
 */
 export async function buildPreloadManifest({
-    distDir,
+    appDir,
     assets,
 }: {
-    distDir: string
+    appDir: string
     assets?: Assets
 }): Promise<Record<string, string[]>> {
-    const read = chunkReader(distDir, assets)
-    const entryName = await findEntry(distDir, assets)
+    const read = chunkReader(appDir, assets)
+    const entryName = await findEntry(appDir, assets)
     const entrySource = entryName ? await read(entryName) : undefined
     if (entryName === undefined || entrySource === undefined) {
         return {}

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

@@ -1,11 +1,10 @@
-import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
-import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
 import { acceptsGzip } from './acceptsGzip.ts'
 import { cacheControlForAsset } from './cacheControlForAsset.ts'
 import { containsTraversal } from './containsTraversal.ts'
 import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { globToPathSet } from './globToPathSet.ts'
 import { respondWithEmbeddedAsset } from './respondWithEmbeddedAsset.ts'
+import { textResponse } from './textResponse.ts'
 import type { Assets } from './types/Assets.ts'
 
 /*
@@ -24,23 +23,29 @@ Unlike the public server this answers every `/_app/` request itself (404 on
 a miss — nothing falls through past the build tree). The path-traversal
 guard inspects the raw request URL because the WHATWG parser normalizes
 encoded `..` segments away before `url.pathname` is visible.
+
+`appDir` is the physical directory the `/_app/*` URLs map onto: `dist/_app` for
+a production build, or — under `abide dev` — the generation dir this worker was
+spawned on (`ABIDE_APP_DIR`). The URL space stays `/_app/*` either way; only the
+disk location this worker reads from moves, so a rebuild's new worker reads a new
+dir while this one keeps serving its own, immutable for its lifetime.
 */
 export async function createAppAssetServer({
-    distDir,
+    appDir,
     assets,
 }: {
-    distDir: string
+    appDir: string
     assets?: Assets
 }): Promise<(req: Request, url: URL) => Promise<Response>> {
     // Per-pathname asset header bundles, hashed-chunk-aware Cache-Control.
     const headersForAsset = createAssetHeaderCache(cacheControlForAsset)
-    /* Boot snapshot of every disk `_app` path, mirroring createPublicAssetServer: the
-       header cache keys on (request-controlled) pathnames, so building bundles for junk
-       `/_app/*` probes would grow it without bound. A rebuild restarts the server (same
-       restart `bun --watch` triggers on a code change), re-snapshotting. */
+    /* Boot snapshot of every disk chunk path (keyed by its `/_app/*` URL), mirroring
+       createPublicAssetServer: the header cache keys on (request-controlled) pathnames,
+       so building bundles for junk `/_app/*` probes would grow it without bound. A
+       rebuild spawns a fresh worker (against a fresh generation dir), re-snapshotting. */
     const diskPaths = assets
         ? new Set<string>()
-        : await globToPathSet(`${distDir}/_app`, '**/*', (file) => `/_app/${file}`)
+        : await globToPathSet(appDir, '**/*', (file) => `/_app/${file}`)
     /* Derive the precompressed `.gz` sibling set from the single tree scan (it already
        includes the `.gz` files) — a gzip-capable client gets those bytes without
        on-the-fly compression. Keyed by the base path (the `.gz` suffix stripped). */
@@ -49,11 +54,7 @@ export async function createAppAssetServer({
     )
 
     // Fresh 404 per call — a Response body is single-use, so it can't be hoisted to a const.
-    const notFound = (): Response =>
-        new Response('Not Found', {
-            status: 404,
-            headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
-        })
+    const notFound = (): Response => textResponse(404)
 
     return async function serveAppAsset(req, url) {
         if (containsTraversal(req.url)) {
@@ -88,7 +89,9 @@ export async function createAppAssetServer({
             return notFound()
         }
         const { base: baseHeaders, gzip: gzipHeaders } = headersForAsset(assetPath)
-        const diskPath = distDir + assetPath
+        // Map the `/_app/<file>` URL onto the physical dir: strip the `/_app` prefix
+        // (5 chars) and join under appDir, which already IS the `_app` (or generation) dir.
+        const diskPath = appDir + assetPath.slice('/_app'.length)
         if (acceptsGzip(req) && diskGzipPaths.has(assetPath)) {
             return new Response(Bun.file(`${diskPath}.gz`), { headers: gzipHeaders })
         }

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

@@ -0,0 +1,145 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { matchRoute } from '../../shared/matchRoute.ts'
+import { normalizePathname } from '../../shared/normalizePathname.ts'
+import { parseRouteSegments } from '../../shared/parseRouteSegments.ts'
+import type { Pages } from '../../ui/types/Pages.ts'
+import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
+import type { createRouteDispatcher } from './createRouteDispatcher.ts'
+
+/* A route handler pre-bound to one registered URL — the dispatcher's output. */
+type RouteHandler = ReturnType<ReturnType<typeof createRouteDispatcher>>
+
+/*
+The URL-shape decision for one request, once the framework plumbing has passed
+on it. A `handler` case (rpc, page, or the openapi doc) is dispatched through
+the request scope; a `redirect` is returned verbatim; the asset cases name
+which asset server serves the path, with `publicAsset` as the catch-all bucket
+whose miss falls through to the 404 path. Keeping the decision data-only lets a
+test assert it without booting Bun.serve — the effects (ALS dispatch, asset
+serving, 404 render) stay in the fetch closure.
+*/
+export type RouteResolution =
+    | { kind: 'redirect'; response: Response }
+    | { kind: 'handler'; handler: RouteHandler; params: Record<string, string> }
+    | { kind: 'appAsset' }
+    | { kind: 'publicAsset' }
+
+/*
+Owns the URL-shape decisions that used to sit inline in the Bun.serve fetch
+closure: canonical-slash redirects (308), the openapi document's build +
+memo, and the asset-precedence ordering. Route dispatch (rpc-vs-page-vs-404,
+method matching) stays behind createRouteDispatcher; this resolver composes its
+per-URL handlers and adds the request-URL → decision layer on top, so both the
+redirect logic and the memo semantics become unit-testable without a listener.
+
+App routes are matched AFTER the `/__abide/*` plumbing (a reserved namespace no
+app route occupies) and BEFORE the root-level framework surfaces (the openapi
+doc, `/_app/`, public/ files), so a page route shadows a same-path public file
+— the precedence the Bun routes table used to impose implicitly, now pinned
+here. rpc URLs are flat literals (always `/rpc/...`) resolved by direct lookup;
+page URLs carry `[name]` / `[[name]]` / `[...rest]` segments resolved through
+the shared matchRoute — the same matcher the client router runs — so params
+decode and precedence agree across the sides by construction.
+*/
+export function createAppRouteResolver({
+    pages,
+    rpc,
+    buildRouteHandler,
+    openApiPath,
+    buildOpenApiDocument,
+}: {
+    pages: Pages
+    rpc: RemoteRoutes
+    buildRouteHandler: ReturnType<typeof createRouteDispatcher>
+    openApiPath: string
+    buildOpenApiDocument: () => Promise<Record<string, unknown>>
+}): (req: Request, url: URL) => RouteResolution {
+    /* Handlers pre-bound per registered URL. rpc URLs dispatch by direct lookup;
+       page URLs resolve through matchRoute against pageRouteUrls below. */
+    const rpcHandlers = new Map<string, RouteHandler>()
+    for (const routeUrl of Object.keys(rpc)) {
+        rpcHandlers.set(routeUrl, buildRouteHandler(routeUrl))
+    }
+    const pageHandlers = new Map<string, RouteHandler>()
+    for (const routeUrl of Object.keys(pages)) {
+        /* A `[...rest]` consumes every remaining segment, so segments after it
+           can never constrain matching — the route would silently serve paths
+           it shouldn't. Fail at boot instead. */
+        const segments = parseRouteSegments(routeUrl)
+        const catchAllIndex = segments.findIndex(
+            (segment) => segment.kind === 'param' && segment.catchAll,
+        )
+        if (catchAllIndex !== -1 && catchAllIndex !== segments.length - 1) {
+            throw new Error(
+                `[abide] invalid page route ${routeUrl}: a [...name] catch-all must be the last segment`,
+            )
+        }
+        pageHandlers.set(routeUrl, buildRouteHandler(routeUrl))
+    }
+    const pageRouteUrls = Object.keys(pages)
+
+    /* Built on first request, then reused — the rpc registry is frozen after load.
+       Memoised as a promise so two concurrent cold requests share one build instead
+       of both building (the second otherwise clobbering the first). A rejected build
+       clears the memo so the next request retries rather than caching the failure. */
+    let openApiSpec: Promise<Record<string, unknown>> | undefined
+    const openApiHandler: RouteHandler = async () => {
+        openApiSpec ??= buildOpenApiDocument().catch((error) => {
+            // Don't cache a failed build — clear the memo so a later request
+            // retries instead of 500-ing forever.
+            openApiSpec = undefined
+            throw error
+        })
+        return Response.json(await openApiSpec, { headers: { 'Cache-Control': NO_STORE } })
+    }
+
+    return function resolveAppRoute(_req, url): RouteResolution {
+        const rpcHandler = rpcHandlers.get(url.pathname)
+        if (rpcHandler) {
+            return { kind: 'handler', handler: rpcHandler, params: {} }
+        }
+        /*
+        Pages match only in canonical slash form; a non-canonical request
+        (`/admin/`, `//admin`) that would match is 308'd to the canonical URL
+        instead of served. Serving it directly would hand app.handle — the auth
+        seam — a pathname the matcher silently normalized away, so an exact-match
+        guard on `/admin` never sees the request it's guarding (the old Bun routes
+        table 404'd these forms; the redirect keeps the guard sound AND the URL
+        friendly). rpc URLs stay exact-match strict, as they always were.
+        */
+        const canonicalPathname = normalizePathname(url.pathname)
+        if (canonicalPathname !== url.pathname) {
+            if (matchRoute(pageRouteUrls, canonicalPathname)) {
+                return {
+                    kind: 'redirect',
+                    response: new Response(null, {
+                        status: 308,
+                        headers: {
+                            Location: `${canonicalPathname}${url.search}`,
+                            'Cache-Control': NO_STORE,
+                        },
+                    }),
+                }
+            }
+        } else {
+            const matchedPage = matchRoute(pageRouteUrls, url.pathname)
+            if (matchedPage) {
+                const pageHandler = pageHandlers.get(matchedPage.route)
+                if (pageHandler) {
+                    return { kind: 'handler', handler: pageHandler, params: matchedPage.params }
+                }
+            }
+        }
+        if (url.pathname === openApiPath) {
+            return { kind: 'handler', handler: openApiHandler, params: {} }
+        }
+        /* Static assets sidestep ALS + the per-request CacheStore + app.handle
+           (see the fetch closure); `/_app/` build output takes precedence over
+           public/ files, and anything else falls to the public bucket whose miss
+           becomes the 404. */
+        if (url.pathname.startsWith('/_app/')) {
+            return { kind: 'appAsset' }
+        }
+        return { kind: 'publicAsset' }
+    }
+}

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

@@ -0,0 +1,212 @@
+import type { Server } from 'bun'
+import type { McpServer } from '../../mcp/types/McpServer.ts'
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { CLI_PATH } from '../../shared/CLI_PATH.ts'
+import { DEV_REBUILD_PATH } from '../../shared/DEV_REBUILD_PATH.ts'
+import { DEV_RELOAD_PATH } from '../../shared/DEV_RELOAD_PATH.ts'
+import { HEALTH_PATH } from '../../shared/HEALTH_PATH.ts'
+import { IDENTITY_PATH } from '../../shared/IDENTITY_PATH.ts'
+import { INSPECTOR_PATH } from '../../shared/INSPECTOR_PATH.ts'
+import { lenientDecode } from '../../shared/lenientDecode.ts'
+import { MCP_PATH } from '../../shared/MCP_PATH.ts'
+import { SOCKETS_PATH } from '../../shared/SOCKETS_PATH.ts'
+import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
+import { handleCliDownload } from '../cli/handleCliDownload.ts'
+import { handleCliInstall } from '../cli/handleCliInstall.ts'
+import type { createSocketDispatcher } from '../sockets/createSocketDispatcher.ts'
+import type { buildHealthPayload } from './buildHealthPayload.ts'
+import { crossOriginGate } from './crossOriginGate.ts'
+import { DEV_REBUILD_MESSAGE } from './DEV_REBUILD_MESSAGE.ts'
+import { devReloadResponse } from './devReloadResponse.ts'
+import { disableIdleTimeoutForStream } from './disableIdleTimeoutForStream.ts'
+import { gzipResponse } from './gzipResponse.ts'
+import { textResponse } from './textResponse.ts'
+import type { DevReloadStamp } from './types/DevReloadStamp.ts'
+import type { RequestStore } from './types/RequestStore.ts'
+
+const SOCKETS_REST_PREFIX = `${SOCKETS_PATH}/`
+const CLI_DOWNLOAD_PREFIX = `${CLI_PATH}/`
+
+/*
+Returned by the router when a request matches none of its framework routes, so
+the fetch handler falls through to the app's rpc/page/asset routes. A dedicated
+sentinel — not `undefined` — because a successful socket upgrade legitimately
+returns `undefined` (Bun's signal that it took the connection over), which must
+stay distinct from "not a plumbing route".
+*/
+export const PLUMBING_PASS: unique symbol = Symbol('abide.plumbingPass')
+
+/* Either the handled response (buffered, streamed, or `undefined` for a socket
+   upgrade handoff) or the pass sentinel. Returned synchronously so the common
+   app-route path pays no extra await/promise allocation — only a matched route
+   yields a promise. */
+type PlumbingResult = Response | undefined | Promise<Response | undefined> | typeof PLUMBING_PASS
+
+/* dispatchRequest, injected: runs a handler inside the per-request scope + app.handle middleware. */
+type DispatchRequest = (
+    req: Request,
+    pathParams: Record<string, string>,
+    handler: (
+        req: Request,
+        pathParams: Record<string, string>,
+        store: RequestStore,
+    ) => Promise<Response>,
+    url: URL,
+) => Promise<Response>
+
+/*
+The framework's own HTTP surface — health/identity probe, inspector, the dev
+live-reload + rebuild channels, the sockets upgrade and its
+SSE/JSON HTTP face, the MCP endpoint, and CLI install/download — resolved ahead
+of the app's rpc/page routes. Extracted from createServer's fetch handler as a
+sibling of createRouteDispatcher: the app-route half already sat behind a seam,
+this is the framework-plumbing half, testable without a live socket. The probe
+and dev/inspector channels answer directly (ahead of app.handle) so they land
+even when the app guards everything behind auth; the sockets-REST/MCP/CLI faces
+run through dispatchRequest so app.handle auth applies like the rpc paths.
+Returns PLUMBING_PASS for any path it doesn't own, so the caller continues to
+the app routes.
+*/
+export function createPlumbingRouter({
+    dev,
+    clientFingerprint,
+    inspectorHandler,
+    socketDispatcher,
+    mcp,
+    cliName,
+    cliCwd,
+    healthPayload,
+    dispatchRequest,
+}: {
+    dev: boolean
+    clientFingerprint: DevReloadStamp | undefined
+    inspectorHandler: ((request: Request, url: URL) => Promise<Response>) | undefined
+    socketDispatcher: ReturnType<typeof createSocketDispatcher>
+    mcp: McpServer | undefined
+    cliName: string
+    cliCwd: string
+    healthPayload: (req: Request) => ReturnType<typeof buildHealthPayload>
+    dispatchRequest: DispatchRequest
+}): (req: Request, url: URL, bunServer: Server<unknown>) => PlumbingResult {
+    /*
+    Health/identity probe — answered directly, ahead of any app.handle
+    middleware, so the bundle's connect screen, the CLI, and the client
+    health() can confirm a URL really is a live abide server even when the app
+    guards everything behind auth (reporting `authenticated: false` requires
+    exactly that). The app's optional health hook contributes fields; the
+    framework's identity keys win on collision, and a thrown hook is logged and
+    skipped so an app bug can't masquerade as an unreachable server.
+    IDENTITY_PATH is the compatibility alias for the same payload.
+    */
+    async function healthProbe(req: Request, url: URL): Promise<Response> {
+        const payload = await healthPayload(req)
+        return gzipResponse(
+            req,
+            Response.json(
+                /*
+                The IDENTITY_PATH alias keeps the legacy `abide: true` shape:
+                already-shipped probers check it with strict equality, and a
+                version string would make them treat an upgraded healthy server
+                as not-abide.
+                */
+                url.pathname === IDENTITY_PATH ? { ...payload, abide: true } : payload,
+                { headers: { 'Cache-Control': NO_STORE } },
+            ),
+        )
+    }
+
+    return function routePlumbing(req, url, bunServer) {
+        if (url.pathname === HEALTH_PATH || url.pathname === IDENTITY_PATH) {
+            return healthProbe(req, url)
+        }
+        /*
+        Inspector surface — answered directly, ahead of app.handle, since it's
+        privileged operator tooling gated by ABIDE_ENABLE_INSPECTOR (not the
+        app's user auth). Undefined handler = flag off, so the whole block
+        compiles out of the hot path when the inspector's off.
+        */
+        if (
+            inspectorHandler &&
+            (url.pathname === INSPECTOR_PATH || url.pathname.startsWith(`${INSPECTOR_PATH}/`))
+        ) {
+            // The events feed is long-lived SSE: opt it out of the idle timeout,
+            // else Bun reaps it and the reconnect replays the whole buffer
+            // (duplicate boot logs every ~10s).
+            return inspectorHandler(req, url).then((response) =>
+                disableIdleTimeoutForStream(bunServer, req, response),
+            )
+        }
+        /*
+        Dev live-reload channel — answered directly, ahead of app.handle, so a
+        restart-driven reconnect always lands even when the app guards
+        everything behind auth. Only mounted under `abide dev`.
+        */
+        if (clientFingerprint !== undefined && url.pathname === DEV_RELOAD_PATH) {
+            // Long-lived SSE: opt out of the idle timeout, else Bun reaps it and
+            // the reconnect triggers a spurious reload loop.
+            return disableIdleTimeoutForStream(bunServer, req, devReloadResponse(clientFingerprint))
+        }
+        /*
+        Manual rebuild trigger: signal the orchestrator parent over IPC to
+        rebuild + restart. Same-origin sibling of the live-reload channel, so a
+        script refreshes on the app's own port. process.send exists only when
+        the dev orchestrator spawned us with ipc; the optional chain no-ops on a
+        bare server.
+        */
+        if (dev && req.method === 'POST' && url.pathname === DEV_REBUILD_PATH) {
+            process.send?.(DEV_REBUILD_MESSAGE)
+            return new Response('rebuilding\n', { headers: { 'Content-Type': TEXT_PLAIN } })
+        }
+        if (url.pathname === SOCKETS_PATH) {
+            // Reject cross-origin upgrades (CSWSH) before handing off to Bun.
+            const upgradeForbidden = crossOriginGate(req, url)
+            if (upgradeForbidden) {
+                return upgradeForbidden
+            }
+            if (bunServer.upgrade(req, { data: {} })) {
+                return undefined
+            }
+            return textResponse(400, 'Upgrade failed')
+        }
+        /*
+        HTTP face of a socket (`/__abide/sockets/<name>`) — tail over SSE / JSON
+        and publish — for the CLI and MCP. Runs through dispatchRequest so
+        app.handle auth applies, like the rpc paths. The socket name may contain
+        `/` (nested files), so it's the whole remaining pathname, percent-decoded.
+        */
+        if (url.pathname.startsWith(SOCKETS_REST_PREFIX)) {
+            /*
+            Gate cross-origin browser publishes (CSRF, see crossOriginGate). GET
+            tail reads stay open cross-origin like rpc reads; only the mutating
+            POST is gated.
+            */
+            const publishForbidden = crossOriginGate(req, url, { allowReadOnly: true })
+            if (publishForbidden) {
+                return publishForbidden
+            }
+            const name = lenientDecode(url.pathname.slice(SOCKETS_REST_PREFIX.length))
+            return dispatchRequest(req, {}, async () => socketDispatcher.rest(req, name), url)
+        }
+        if (url.pathname === MCP_PATH && mcp) {
+            // Gate cross-site browser posts (CSRF, see crossOriginGate).
+            const mcpForbidden = crossOriginGate(req, url)
+            if (mcpForbidden) {
+                return mcpForbidden
+            }
+            return dispatchRequest(req, {}, async () => mcp.handle(req), url)
+        }
+        if (url.pathname === CLI_PATH) {
+            return dispatchRequest(req, {}, async () => handleCliInstall(req, cliName), url)
+        }
+        if (url.pathname.startsWith(CLI_DOWNLOAD_PREFIX)) {
+            const platform = url.pathname.slice(CLI_DOWNLOAD_PREFIX.length)
+            return dispatchRequest(
+                req,
+                {},
+                async () => handleCliDownload(req, platform, cliName, cliCwd),
+                url,
+            )
+        }
+        return PLUMBING_PASS
+    }
+}

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

@@ -2,12 +2,12 @@ import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
 import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { NAV_HEADER } from '../../shared/NAV_HEADER.ts'
 import { REMOTE_FUNCTION } from '../../shared/REMOTE_FUNCTION.ts'
-import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
 import type { HttpMethod } from '../../shared/types/HttpMethod.ts'
 import type { RemoteFunction } from '../../shared/types/RemoteFunction.ts'
 import type { Pages } from '../../ui/types/Pages.ts'
 import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
 import { crossOriginGate } from './crossOriginGate.ts'
+import { textResponse } from './textResponse.ts'
 import type { RequestStore } from './types/RequestStore.ts'
 
 type AnyRemoteFunction = RemoteFunction<unknown, unknown>
@@ -26,12 +26,9 @@ type RenderPage = (
     store: RequestStore,
 ) => Promise<Response>
 
-/* The framework's 405 — `Allow` names the permitted rpc(s), body and NO_STORE shared so the rpc and page branches can't drift. */
+/* The framework's 405 — `Allow` names the permitted rpc(s); body/headers come from the shared textResponse so the rpc and page branches can't drift. */
 function methodNotAllowed(allow: string): Response {
-    return new Response('Method Not Allowed', {
-        status: 405,
-        headers: { Allow: allow, 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
-    })
+    return textResponse(405, undefined, { Allow: allow })
 }
 
 /*
@@ -118,10 +115,7 @@ export function createRouteDispatcher({
                 }
                 return renderPage(routeUrl, pathParams, store)
             }
-            return new Response('Not Found', {
-                status: 404,
-                headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
-            })
+            return textResponse(404)
         }
     }
 }