@abide/abide 0.101.0 → 0.103.0

package/src/server/appTree.ts

@@ -0,0 +1,238 @@
+// 23.14 — WHERE AN APP'S ADDRESSES ARE, read off the tree in one walk. A file directly in a directory
+// below the root is an address — a page, a layout, an error page or a handler file — and nothing
+// else is there (23.22); a fence is never one (23.15): `server` fences a graph, `public` holds files
+// answered as authored at the path of the directories above it, and `lib` and `tests` hold the rest.
+// So listing a directory lists its routes.
+//
+// ONE WALK for the sources, the handler files, the server and lib modules, and the public files
+// `abide build` copies and `abide dev` answers, and the refusals (23.16, 23.17, 23.18, 23.22) — and
+// ONE SKIP RULE, `skipped`, for every walk of the tree, beside `placeOf`, which answers the same
+// question of one path.
+//
+// A WALK RATHER THAN A GLOB: a glob descends `node_modules` and the build output before a filter
+// can drop them.
+
+import { type Dirent, existsSync, readdirSync } from 'node:fs' // bun has no directory listing or sync existence check of its own
+import { ABIDE_ADDRESS } from '#shared/ADDRESSES.ts'
+import {
+    LIB_DIRECTORY,
+    PUBLIC_DIRECTORY,
+    RESERVED_DIRECTORIES,
+    SERVER_DIRECTORY,
+} from '#shared/RESERVED_DIRECTORIES.ts'
+import { DIRECTORY_FILES, routeOf, skipped } from '#shared/routePattern.ts'
+
+/** What one walk of the app finds, every path relative to the root. */
+type AppFiles = {
+    /** Every `.abide`, in path order. */
+    abide: string[]
+    /** Every handler file, in path order. */
+    handlers: string[]
+    /** Every module under a `server` or a `lib` directory, in path order — run as it is imported. */
+    modules: string[]
+    /** Every file under a `public` directory, to the address it is answered at below the mount. */
+    published: Map<string, string>
+}
+
+/** Told of each thing the tree refuses, at the path relative to the root. */
+type Refuse = (path: string, message: string) => void
+
+const THROW: Refuse = (_path, message) => {
+    throw new Error(message)
+}
+
+/**
+ * The app's `.abide` sources, handler files, server and lib modules and public files, refusing a
+ * tree 23.16, 23.17, 23.18 or 23.22 forbids.
+ *
+ * `refuse` throws by default, which is the build's answer; `abide check` collects instead (38.33),
+ * and the checker's route table ignores them, since a refused tree is the build's to report.
+ *
+ * A missing root is an app with nothing in it, not a fault.
+ */
+export function appFiles(root: string, refuse: Refuse = THROW): AppFiles {
+    const files: AppFiles = {
+        abide: [],
+        handlers: [],
+        modules: [],
+        published: new Map(),
+    }
+    // 23.22, 38.25 — a root that is its package's directory holds the package's own files beside its
+    // pages.
+    const packaged = existsSync(`${root}/package.json`)
+    walk(root, '', undefined, files, refuse, packaged)
+    files.abide.sort()
+    files.handlers.sort()
+    files.modules.sort()
+    return files
+}
+
+// `reserved` is the nearest reserved directory above `relative` — its path and its name — or
+// `undefined` where none is.
+function walk(
+    directory: string,
+    relative: string,
+    reserved: { path: string; name: string } | undefined,
+    files: AppFiles,
+    refuse: Refuse,
+    packaged = false,
+): void {
+    let entries: Dirent[]
+    try {
+        entries = readdirSync(directory, { withFileTypes: true })
+    } catch (thrown) {
+        if ((thrown as { code?: unknown }).code === 'ENOENT') return
+        throw thrown
+    }
+    for (const entry of entries) {
+        if (skipped(entry.name)) continue
+        const path = `${relative}${entry.name}`
+        if (entry.isDirectory()) {
+            let within = reserved
+            if (RESERVED_DIRECTORIES.has(entry.name)) {
+                if (reserved !== undefined)
+                    refuse(
+                        path,
+                        `abide: ${path} is a ${entry.name} directory under the ${reserved.name} directory ${reserved.path}. RULEBOOK 23.16.`,
+                    )
+                within = { path, name: entry.name }
+            }
+            walk(
+                `${directory}/${entry.name}`,
+                `${path}/`,
+                within,
+                files,
+                refuse,
+            )
+            continue
+        }
+        const abide = path.endsWith('.abide')
+        if (abide) files.abide.push(path)
+        if (reserved === undefined) {
+            if (!abide && !isModule(path)) {
+                if (packaged && relative === '' && !path.endsWith('.ts'))
+                    continue
+                refuse(
+                    path,
+                    `abide: ${path} is directly in an address directory, which holds pages, layouts, error pages and handler files alone. Move it into a lib directory beside it. RULEBOOK 23.22.`,
+                )
+                continue
+            }
+            if (!abide) files.handlers.push(path)
+            // 23.17 — anything that could answer here would answer in abide's own namespace.
+            refuseFrameworkRoute(routeOf(path), path, refuse)
+        } else if (DIRECTORY_FILES.has(entry.name))
+            refuse(
+                path,
+                `abide: ${path} is under the ${reserved.name} directory ${reserved.path}, where nothing has an address, and ${entry.name} is a route's name. RULEBOOK 23.18.`,
+            )
+        else if (reserved.name === PUBLIC_DIRECTORY)
+            files.published.set(path, publicAddress(path, reserved.path))
+        else if (
+            (reserved.name === SERVER_DIRECTORY ||
+                reserved.name === LIB_DIRECTORY) &&
+            isModule(path)
+        )
+            files.modules.push(path)
+    }
+}
+
+/**
+ * Whether `path` names a module the app runs — neither a declaration nor a test: directly in an
+ * address directory, a handler file rather than a stray.
+ */
+function isModule(path: string): boolean {
+    return (
+        path.endsWith('.ts') &&
+        !path.endsWith('.d.ts') &&
+        !path.endsWith('.test.ts')
+    )
+}
+
+/** Refuses `source` where `route` lies in the framework's own namespace. 23.17. */
+export function refuseFrameworkRoute(
+    route: string,
+    source: string,
+    refuse: Refuse = THROW,
+): void {
+    if (route === ABIDE_ADDRESS || route.startsWith(`${ABIDE_ADDRESS}/`))
+        refuse(
+            source,
+            `abide: ${source} answers at ${route}, which is under ${ABIDE_ADDRESS}, where abide's own addresses are. RULEBOOK 23.17.`,
+        )
+}
+
+// 36.11 — the directories above `public`, then the file's own path below it.
+function publicAddress(path: string, directory: string): string {
+    const above = directory.slice(0, -PUBLIC_DIRECTORY.length)
+    return `/${above}${path.slice(directory.length + 1)}`
+}
+
+/**
+ * The public files as the server reads them: each address, without its leading `/`, to the file.
+ *
+ * 38.19 — out of the source tree, where `abide dev` answers them.
+ */
+export function publishedUnder(
+    root: string,
+    published: Map<string, string>,
+): Map<string, string> {
+    const paths = new Map<string, string>()
+    for (const [source, address] of published)
+        paths.set(address.slice(1), `${root}/${source}`)
+    return paths
+}
+
+/**
+ * Every `.abide` under `root`, relative to it, in path order — the app's own, and none a
+ * dependency ships.
+ *
+ * Refuses nothing: the language server lists them on every check, and a tree 23.16 forbids is the
+ * build's to refuse (`appFiles`).
+ */
+export function abideUnder(root: string): string[] {
+    const found: string[] = []
+    for (const path of abideFilesUnder(root, '')) found.push(path)
+    return found.sort()
+}
+
+/**
+ * Whether an app lies under `root`: a `.abide` anywhere or a handler file, stopping at the first.
+ *
+ * 38.26's question, asked of a root before anything is built from it, so asking it of a large tree
+ * is as cheap as the tree allows.
+ */
+export function holdsApp(root: string): boolean {
+    return !abideFilesUnder(root, '', true).next().done
+}
+
+// Every `.abide` under `directory` — and, where `handlers`, every handler file outside a fence.
+function* abideFilesUnder(
+    directory: string,
+    relative: string,
+    handlers = false,
+    fenced = false,
+): Generator<string> {
+    let entries: Dirent[]
+    try {
+        entries = readdirSync(directory, { withFileTypes: true })
+    } catch {
+        return
+    }
+    for (const entry of entries) {
+        if (skipped(entry.name)) continue
+        const path = `${relative}${entry.name}`
+        if (entry.isDirectory())
+            yield* abideFilesUnder(
+                `${directory}/${entry.name}`,
+                `${path}/`,
+                handlers,
+                fenced || RESERVED_DIRECTORIES.has(entry.name),
+            )
+        else if (
+            path.endsWith('.abide') ||
+            (handlers && !fenced && isModule(path))
+        )
+            yield path
+    }
+}

package/src/server/argsFor.ts

@@ -2,7 +2,7 @@
 // off the wire: over http (16.2) and a `GET` followed over the socket mux (18.3). Each lane reads the
 // args off its own transport and answers a refusal in its own form.
 
-import { normalised } from '#shared/reactive/argsContract.ts'
+import { normalized } from '#shared/reactive/argsContract.ts'
 import { validationError } from '#shared/refuse.ts'
 import { validateJson } from '#shared/validateJson.ts'
 import type { Mounted } from './answerRpc.ts'
@@ -31,7 +31,7 @@ export function argsFor(
                   found.argsDocument,
                   query,
               )
-    const args = normalised(found.handler, coerced)
+    const args = normalized(found.handler, coerced)
     if (found.wireArgs !== undefined && args !== undefined) {
         const issues = validateJson(found.wireArgs, args)
         if (issues !== null) throw validationError(issues)

package/src/server/assistant.ts

@@ -115,10 +115,10 @@ function appSurface(): McpSurface {
         throw new Error(
             'abide: assistant tools are the app’s MCP surface, and no app is answering this request. RULEBOOK 45.6.',
         )
-    // 45.8, 20.7 — asking for tools over a closed surface is a mistake to name.
+    // 45.8, 20.7 — asking for tools where no handler is published to MCP is a mistake to name.
     if (!app.mcp.opened)
         throw new Error(
-            'abide: assistant was asked for tools, and ABIDE_MCP has not opened the MCP surface. RULEBOOK 45.8.',
+            'abide: assistant was asked for tools, and this app publishes no handler to MCP. RULEBOOK 45.8.',
         )
     return app.mcp
 }

package/src/server/bridgeRelay.ts

@@ -9,13 +9,12 @@
 //
 // A PAIRING IS TO A BROWSER — the `abide-caller` its page carries (26.5) — for as long as the bridge's
 // stream is open. HELD IN THIS PROCESS: an app served by several needs a visitor's requests to reach
-// the one its bridge dialled.
+// the one its bridge dialed.
 
 import { refuse } from '#shared/refuse.ts'
 import { answered } from './answerFailure.ts'
 import { raiseTimeout } from './answerRpc.ts'
 import { framed } from './answerValue.ts'
-import { config } from './config.ts'
 import { Inbox } from './Inbox.ts'
 import { randomToken } from './randomToken.ts'
 
@@ -53,10 +52,8 @@ const BY_CALLER = new Map<string, Bridge>()
 const BY_TOKEN = new Map<string, Bridge>()
 const WATCHERS = new Map<string, Set<() => void>>()
 
-/** Whether `ABIDE_BRIDGE` has opened the relay. 45.19. */
-export function bridgeOpened(): boolean {
-    return (config.peek()?.ABIDE_BRIDGE as unknown) === true
-}
+// 45.19 — the relay answers once the app has handed out a pairing command, and never before.
+let minted = false
 
 /** A single-use pairing code for `caller`, and when it stops standing. 45.14. */
 export function mintCode(caller: string): { code: string; expires: number } {
@@ -66,6 +63,7 @@ export function mintCode(caller: string): { code: string; expires: number } {
     const code = randomToken(12, 'base64url')
     const expires = now + CODE_LIFETIME
     CODES.set(code, { caller, expires })
+    minted = true
     return { code, expires }
 }
 
@@ -172,9 +170,9 @@ function dropBridge(bridge: Bridge): void {
     wakeWatchers(bridge.caller)
 }
 
-/** Answers `/__abide/bridge`, or `undefined` where `ABIDE_BRIDGE` is closed. 45.19. */
+/** Answers `/__abide/bridge`, or `undefined` until a pairing code has been minted. 45.19. */
 export async function answerBridge(request: Request): Promise<unknown> {
-    if (!bridgeOpened()) return undefined
+    if (!minted) return undefined
     if (request.method === 'GET') return pair(request)
     if (request.method === 'POST') return relay(request)
     return new Response(null, { status: 405, headers: { allow: 'GET, POST' } })

package/src/server/claudeCode.ts

@@ -17,7 +17,6 @@ import {
 } from './assistant.ts'
 import { BRIDGE_VERSION } from './BRIDGE_VERSION.ts'
 import {
-    bridgeOpened,
     mintCode,
     openTurn,
     pairedBridge,
@@ -110,11 +109,6 @@ function foldedPrompt(messages: AssistantMessage[]): string {
 
 /** The browser asking, which a pairing is to. 45.13. */
 function askingCaller(): string {
-    // 45.19 — the relay is closed until `ABIDE_BRIDGE` opens it, and using it closed is a mistake to name.
-    if (!bridgeOpened())
-        throw new Error(
-            'abide: claudeCode reaches a visitor’s Claude Code through the bridge relay, and ABIDE_BRIDGE has not opened it. RULEBOOK 45.19.',
-        )
     const caller = callerOf()
     if (caller === undefined)
         throw refuse(

package/src/server/clientBuildOptions.ts

@@ -1,4 +1,5 @@
 import { CLIENT_ADDRESS } from '#shared/ADDRESSES.ts'
+import { tablePath } from './abideModules.ts'
 import { CLIENT_ENTRY } from './CLIENT_BUILD.ts'
 
 /**
@@ -9,13 +10,17 @@ import { CLIENT_ENTRY } from './CLIENT_BUILD.ts'
  * where the output goes and how it is named.
  */
 export function clientBuildOptions(
-    entryDirectory: string,
+    root: string,
     plugins: Bun.BunPlugin[],
     publicAddresses: string[],
 ) {
     return {
-        entrypoints: [`${entryDirectory}/${CLIENT_ENTRY}.ts`] as string[],
-        // 16.28, 16.29 — a handler module is its wrapper here, and the rest of `server/` refuses.
+        // The entry is a table the plugin serves (`abideModules`), below the root.
+        entrypoints: [tablePath(root, `${CLIENT_ENTRY}.ts`)] as string[],
+        // The app's own root, because `Bun.build` opens the entry's directory otherwise, and the
+        // tables' is not on disk to open.
+        root,
+        // 16.28, 16.29 — a `<script server>` is its stand-ins here, and a `server/` module refuses.
         plugins,
         target: 'browser',
         format: 'esm',

package/src/server/coerceArgs.ts

@@ -30,7 +30,7 @@ export function argsDocumentOf(handler: Gated<unknown>): Document | undefined {
 /**
  * Name and value pairs as args: a name given more than once is a list, one given once its text.
  *
- * 16.18 — a query's and a form's members, and 38.62 — `abide call`'s `name=value` words, alike.
+ * 16.18 — a query's and a form's members, and 38.61 — `abide call`'s `name=value` words, alike.
  */
 export function collapsed(
     entries: URLSearchParams | FormData,

package/src/server/commands.ts

@@ -1,5 +1,5 @@
-// 38.13 — THE COMMAND LINE, for both hosts that have one: `abide`, over an app on disk, and a
-// compiled app's executable, over the app it holds (38.51). One list, so a command either has is a
+// 38.12 — THE COMMAND LINE, for both hosts that have one: `abide`, over an app on disk, and a
+// compiled app's executable, over the app it holds (38.50). One list, so a command either has is a
 // command both have — the executable answers the ones that need the source and the compiler with a
 // refusal naming `abide`, rather than not knowing them.
 
@@ -14,7 +14,6 @@ import { installServer } from './installServer.ts'
 import {
     appUrl,
     callHandler,
-    followLogs,
     remoteHeaders,
     remoteUrl,
     watch as watchAddress,
@@ -30,7 +29,14 @@ type Command = (given: Given) => Promise<number | undefined>
 
 /** The commands that need the app's source and the compiler, which only `abide` holds. */
 type SourceCommands = Record<
-    'scaffold' | 'dev' | 'build' | 'check' | 'compile' | 'bundle' | 'lsp',
+    | 'scaffold'
+    | 'dev'
+    | 'build'
+    | 'check'
+    | 'routes'
+    | 'compile'
+    | 'bundle'
+    | 'lsp',
     Command
 >
 
@@ -41,7 +47,7 @@ export type Host = {
     /**
      * The handler table the shell lists and a call reads a handler's method off — so a call is
      * spelled the same whatever the handler's method, and `--method` is only for an app nobody here
-     * knows the table of. Empty where there is none to read.
+     * knows the table of. Empty where there is none to read, and never built to be read.
      */
     handlers: (given: Given) => Promise<Mount[]>
     /** The identity a script `run` resolves its configuration with. 27.3. */
@@ -83,7 +89,7 @@ export async function runCommands(
 }
 
 // A command, and whether it is one of `SourceCommands` — which a host without them still answers
-// (38.52), and does not list (38.53).
+// (38.51), and does not list (38.52).
 type Row = [usage: string, meaning: string, run: Command, sourced: boolean]
 
 function commandsOf(host: Host): Row[] {
@@ -133,12 +139,6 @@ function commandsOf(host: Host): Row[] {
             (given) => mcp(host, given),
             false,
         ],
-        [
-            'logs',
-            'a live subscription to log.records',
-            ({ values }) => followLogs(appUrl(values.url)),
-            false,
-        ],
         [
             'watch <address> [args]',
             "a live subscription to one of the app's followed GETs",
@@ -150,6 +150,11 @@ function commandsOf(host: Host): Row[] {
             'type-check the templates and the TypeScript, on the line you wrote',
             'check',
         ),
+        fromSource(
+            'routes [--json]',
+            'every address the app answers, its file, and where each hook is filed',
+            'routes',
+        ),
         fromSource(
             'compile',
             'the build, as one executable named after the app',
@@ -164,7 +169,7 @@ function commandsOf(host: Host): Row[] {
     ]
 }
 
-/** Refuses a command that needs the source, pointing at `abide`; returns the exit code. 38.52. */
+/** Refuses a command that needs the source, pointing at `abide`; returns the exit code. 38.51. */
 async function needsSource(host: Host, name: string): Promise<number> {
     console.error(
         `${host.name} ${name}: needs the app's source and the compiler, which this executable does not hold. Run \`abide ${name}\` where the source is.`,
@@ -175,7 +180,7 @@ async function needsSource(host: Host, name: string): Promise<number> {
 /**
  * The usage text, listing what the host can run.
  *
- * 38.53 — an executable lists neither the commands it only refuses nor the flags only they read.
+ * 38.52 — an executable lists neither the commands it only refuses nor the flags only they read.
  */
 function usage(host: Host, commands: Row[]): string {
     const sourced = host.source !== undefined
@@ -189,16 +194,16 @@ function usage(host: Host, commands: Row[]): string {
     if (!sourced)
         return `${text}
   --port  the listen port the app is served on
-  --url   the running app the shell, call, logs, openapi and mcp talk to
+  --url   the running app the shell, call, watch, openapi and mcp talk to
   --out   the file openapi writes
 `
     text += `
-  --root       the app's source directory, the one ui/ sits under —
+  --root       the app's source directory, where its pages sit —
                src/ where you stand, or where you stand, whichever has one
   --out        where the build goes, beside the app by default; the file openapi,
                compile and bundle write — named after the app, where you stand
   --port       the listen port for dev, start and the shell's app
-  --url        the running app the shell, call, logs, openapi and mcp talk to
+  --url        the running app the shell, call, watch, openapi and mcp talk to
   --target     the platform compile builds for — linux-x64, darwin-arm64, windows-x64…
   --platforms  several of them, comma-separated, one executable each
 `
@@ -215,13 +220,14 @@ function parsed(argv: string[]) {
             root: { type: 'string' },
             out: { type: 'string' },
             // NO DEFAULT, which is not an omission: `Bun.serve` given no port already reads
-            // `PORT` and then falls back to 3000 — `abide dev` scanning on from there, 38.64 — and
+            // `PORT` and then falls back to 3000 — `abide dev` scanning on from there, 38.63 — and
             // a default written here would take that away from every host that sets it.
             port: { type: 'string' },
             url: { type: 'string' },
             method: { type: 'string' },
             target: { type: 'string' },
             platforms: { type: 'string' },
+            json: { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
         },
         allowPositionals: true,
@@ -249,7 +255,7 @@ async function served(
 /**
  * `start`: serves the app.
  *
- * 38.68 — READS NO INPUT, and hands back no code for the process to exit on: the process is the
+ * 38.67 — READS NO INPUT, and hands back no code for the process to exit on: the process is the
  * server, for a container or a supervisor to stop.
  */
 async function start(host: Host, given: Given): Promise<number | undefined> {
@@ -263,18 +269,17 @@ async function start(host: Host, given: Given): Promise<number | undefined> {
  * The command line with no command: 38.7's shell, on the running app `--url` names or on the app
  * served here.
  *
- * 38.7 — WITH `--url`, BOOTS NOTHING. 38.54 — without, the app served and the shell on it, over http
- * as a remote one's is. 38.55 — `exit` stops the app. 38.56 — input that ends leaves it serving, and
+ * 38.7 — WITH `--url`, BOOTS NOTHING. 38.53 — without, the app served and the shell on it, over http
+ * as a remote one's is. 38.54 — `exit` stops the app. 38.55 — input that ends leaves it serving, and
  * hands back no code for the process to exit on.
  */
 async function shellOn(host: Host, given: Given): Promise<number | undefined> {
-    const handlers = await host.handlers(given)
     const remote = remoteUrl(given.values.url)
     if (remote !== undefined) {
         const url = appUrl(remote)
         await shell({
             url,
-            handlers,
+            handlers: await host.handlers(given),
             heading: `${host.name}: ${url}`,
             local: false,
         })
@@ -282,9 +287,10 @@ async function shellOn(host: Host, given: Given): Promise<number | undefined> {
     }
     const serving = await served(host, given)
     if (typeof serving === 'number') return serving
+    // After the serve, which built the app where nothing had.
     const ended = await shell({
         url: serving.url,
-        handlers,
+        handlers: await host.handlers(given),
         heading: serving.heading,
         local: true,
     })
@@ -297,7 +303,7 @@ async function shellOn(host: Host, given: Given): Promise<number | undefined> {
  * `run`: runs a script under the abide runtime.
  *
  * 38.2 — the request scope installed, the configuration resolved against the app it stands in,
- * and the script run in a scope of its own — so it imports `#server` and `#shared` and reads
+ * and the script run in a scope of its own — so it imports through `#src/*` and reads
  * `config` without a build.
  *
  * HANDS BACK NO CODE ONCE THE SCRIPT IS RUNNING, as `start` does: the script's top level settling
@@ -316,7 +322,7 @@ async function run(
     }
     const path = resolve(file)
     process.argv = [process.argv[0] as string, path, ...rest]
-    // 38.58 — RE-RESOLVED, as `bootApp` does: a module this process loaded before the script may already have
+    // 38.57 — RE-RESOLVED, as `bootApp` does: a module this process loaded before the script may already have
     // read the configuration, under no identity.
     installServer()
     APP_PACKAGE.current = host.appPackage()
@@ -326,7 +332,7 @@ async function run(
 }
 
 /** `call`: one call to one handler on a running app. 38.8. */
-/** `watch <address> [args]`: a `GET`'s value and each patch, as its event stream sends them (38.70). */
+/** `watch <address> [args]`: a `GET`'s value and each patch, as its event stream sends them (38.69). */
 async function watch(host: Host, given: Given): Promise<number> {
     const {
         positionals: [, address, ...args],
@@ -370,13 +376,11 @@ async function call(host: Host, given: Given): Promise<number> {
 /**
  * A fetch against a generated surface, on the app `--url` names or on one booted here.
  *
- * 38.9 — the app booted in this process has that surface opened, and derives it from the same
- * route table the served one does.
+ * 38.9 — the app booted in this process derives it from the same route table the served one does.
  */
 async function surfaceAt(
     host: Host,
     url: string | undefined,
-    surface: string,
     address: string,
 ): Promise<
     (
@@ -390,7 +394,6 @@ async function surfaceAt(
                 ...init,
                 headers: { ...init?.headers, ...remoteHeaders() },
             })
-    process.env[surface] = '1'
     const app = await host.boot()
     return (init) =>
         app.fetch(new Request(`http://abide.local${address}`, init))
@@ -405,12 +408,10 @@ async function openapi(
     host: Host,
     { values: { url, out } }: Given,
 ): Promise<number> {
-    const answer = await (
-        await surfaceAt(host, url, 'ABIDE_OPENAPI', OPENAPI_ADDRESS)
-    )()
+    const answer = await (await surfaceAt(host, url, OPENAPI_ADDRESS))()
     if (!answer.ok) {
         console.error(
-            `${host.name} openapi: the app answered ${answer.status}. ABIDE_OPENAPI opens the document.`,
+            `${host.name} openapi: the app answered ${answer.status}. The document lists every handler with openapi in its clients; none is.`,
         )
         return 1
     }
@@ -423,11 +424,11 @@ async function openapi(
 /**
  * `mcp`: the app's MCP server over stdio.
  *
- * 38.9, 38.14 — a bridge a model client spawns and kills: each line in is a JSON-RPC message for
+ * 38.9, 38.13 — a bridge a model client spawns and kills: each line in is a JSON-RPC message for
  * `/__abide/mcp`, and each answer is a line out.
  */
 async function mcp(host: Host, { values: { url } }: Given): Promise<number> {
-    const ask = await surfaceAt(host, url, 'ABIDE_MCP', MCP_ADDRESS)
+    const ask = await surfaceAt(host, url, MCP_ADDRESS)
     for await (const line of console) {
         if (line.trim() === '') continue
         const answer = await ask({

package/src/server/componentModules.d.ts

@@ -1,6 +1,7 @@
 // 35.4 — what a `.ts` holds where it imports a `.abide`: the component, called with its props to
-// bind them, answering the `Component` `render` takes (`componentImports`). A wildcard, so the props
+// bind them, answering the `Component` `render` takes (`abideModules`). A wildcard, so the props
 // are not checked here; a declaration in a module would be an augmentation, which takes no wildcard.
+// The component is all a `.abide` exports (34.17).
 declare module '*.abide' {
     const component: (
         props?: Record<string, unknown>,

package/src/server/compressAnswer.ts

@@ -1,4 +1,4 @@
-// 38.30 — AN ANSWER, COMPRESSED WHOLE: a document, and a JSON value at least `COMPRESSION_FLOOR`
+// 38.29 — AN ANSWER, COMPRESSED WHOLE: a document, and a JSON value at least `COMPRESSION_FLOOR`
 // bytes long. Both are in hand before a byte goes out — `render` sends nothing until the page is
 // built (41.1), and a value is stringified once — so one compression is the whole answer, with its
 // length known, where a stream compressed as it arrived had to be flushed at every chunk.
@@ -6,7 +6,7 @@
 // WHAT EACH LANE SENDS BESIDE THE BYTES is here too, so the two cannot drift. A document names
 // `accept-encoding` in `vary` through `DOCUMENT_HEADERS`, which its `HEAD` and error answers carry as
 // well; a JSON answer names it here. Both say their length: `abide dev` relays a body chunk by chunk
-// from its worker (38.36), and a relayed body with no declared length goes out chunked.
+// from its worker (38.35), and a relayed body with no declared length goes out chunked.
 // BUN'S GZIP parts from zlib's past ~130 KB, which only the off-loop lane reaches — so that lane takes
 // zlib's, the loop keeps bun's, and the two make the same bytes.
 import { brotliCompress, brotliCompressSync, constants, gzip } from 'node:zlib' // bun has no brotli, and no compression off the loop
@@ -21,12 +21,12 @@ import {
 // already under gzip's size at twice gzip's 70 µs.
 const BROTLI_OPTIONS = { params: { [constants.BROTLI_PARAM_QUALITY]: 5 } }
 
-// 38.69 — the bytes under which a JSON answer goes out as it is. Under it an answer saves tens of
+// 38.68 — the bytes under which a JSON answer goes out as it is. Under it an answer saves tens of
 // bytes that leave in the same packet anyway, for 3–8 µs of a ~57 µs request; at 8 KB the same CPU
 // saves seven kilobytes.
 const COMPRESSION_FLOOR = 1024
 
-// 38.96 — the bytes from which an answer is compressed off the event loop. Brotli 5 holds the loop
+// 38.95 — the bytes from which an answer is compressed off the event loop. Brotli 5 holds the loop
 // ~360 µs at 64 KB and ~7 ms at 700 KB — every other request and socket waits that long — where
 // the thread pool's hop adds ~20 µs to the answer it carries: 6% at 64 KB, 27% at 16 KB.
 const OFF_LOOP_FLOOR = 64 * 1024