@abide/abide 0.101.0 → 0.102.0

package/src/server/generatedSurfaces.ts

@@ -1,6 +1,6 @@
-// SECTION 20 — WHAT IS GENERATED OFF THE ROUTE TABLE: the OpenAPI document, the MCP endpoint, and 36.7's
-// `GET` over `log.records`. Each is derived from the handlers the app mounted (20.1) and none is
-// authored beside them; each is closed until its `ABIDE_*` opens it, and a closed one is a 404 (36.7).
+// SECTION 20 — WHAT IS GENERATED OFF THE ROUTE TABLE: the OpenAPI document and the MCP endpoint. Each
+// is derived from the handlers the app mounted (20.1) and none is authored beside them; each is open
+// exactly where the route table lists a handler for it, and a closed one is a 404 (20.7, 36.7).
 //
 // THE SURFACES ANSWER INSIDE THE APP'S OWN MIDDLEWARE (20.8), because they are answered from the one
 // request path everything under `/__abide` is — and a tool call is a request through it again (20.10).
@@ -13,15 +13,15 @@
 // `cli` to false for a handler returning a `Response`, 20.4's `ui: false`, and 20.11's type-derived
 // schema (19.9) as `argsDocument`.
 
-import { log, namedLogger } from '#shared/log.ts'
+import { isFailed } from '#shared/Failed.ts'
+import { namedLogger } from '#shared/log.ts'
 import { type Reactive, reactive } from '#shared/reactive/index.ts'
-import { refuse } from '#shared/refuse.ts'
-import { GET } from '#shared/rpc.ts'
+import { parseRoutePattern } from '#shared/routePattern.ts'
 import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
 import { answered } from './answerFailure.ts'
 import type { Mounted } from './answerRpc.ts'
 import type { ToolDefinition } from './assistant.ts'
-import { appIdentity, config } from './config.ts'
+import { appIdentity } from './config.ts'
 import { crossingOrigin, crossingRefusal } from './crossingOrigin.ts'
 import { MCP_PROTOCOL_VERSION } from './MCP_PROTOCOL_VERSION.ts'
 import { type Listed, surfaceOf } from './surfaceOf.ts'
@@ -29,14 +29,8 @@ import { type Listed, surfaceOf } from './surfaceOf.ts'
 const OPENAPI_LOG = namedLogger('abide:openapi')
 const MCP_LOG = namedLogger('abide:mcp')
 
-/** Whether the `ABIDE_*` setting `name` opens its surface. 36.7. */
-function opened(name: string): boolean {
-    return (config.peek()?.[name] as unknown) === true
-}
-
-// What MCP and OpenAPI add to a listing: whether the handler is keyed, and its name where only
-// letters, digits, `_` and `-` are admitted — a tool's, an operation's.
-type Published = Listed & { keyed: boolean; name: string }
+// What MCP and OpenAPI add to a listing: whether the handler is keyed.
+type Published = Listed & { keyed: boolean }
 
 /** Every handler `surface` lists (`surfaceOf`). */
 function listed(
@@ -53,7 +47,6 @@ function listed(
         found.push({
             ...one,
             keyed: mounted.handler.keyed,
-            name: one.path.replace(/[^a-zA-Z0-9_-]/g, '_'),
         })
     }
     return found
@@ -76,8 +69,27 @@ const PROBLEM_SCHEMA = {
     },
 }
 
+/** `schema` without the members the path carries, or `schema` itself where it carries none. */
+function withoutMembers(
+    schema: { properties?: Record<string, unknown>; required?: string[] },
+    names: Set<string>,
+): unknown {
+    if (names.size === 0 || schema.properties === undefined) return schema
+    const properties: Record<string, unknown> = {}
+    for (const name in schema.properties)
+        if (!names.has(name)) properties[name] = schema.properties[name]
+    const required: string[] = []
+    for (const name of schema.required ?? [])
+        if (!names.has(name)) required.push(name)
+    return { ...schema, properties, required }
+}
+
 /** The OpenAPI 3.1 document, each handler's `JsonSchema` published as it stands. 20.6. */
-function openApiOf(handlers: Map<string, Mounted>): unknown {
+function openApiOf(handlers: Map<string, Mounted>): {
+    openapi: string
+    info: { title: string; version: string }
+    paths: Record<string, Record<string, unknown>>
+} {
     const paths: Record<string, Record<string, unknown>> = {}
     for (const each of listed(handlers, 'openapi')) {
         const operation: Record<string, unknown> = {
@@ -102,36 +114,60 @@ function openApiOf(handlers: Map<string, Mounted>): unknown {
             OPENAPI_LOG.warning(
                 `${each.address} has no JSON Schema to publish for its args.`,
             )
-        if (each.schema !== undefined) {
-            if (argsInURL(each.method)) {
-                const properties =
-                    (
-                        each.schema as {
-                            properties?: Record<string, unknown>
-                            required?: string[]
-                        }
-                    ).properties ?? {}
-                const required = new Set(
-                    (each.schema as { required?: string[] }).required ?? [],
-                )
-                operation.parameters = Object.entries(properties).map(
-                    ([name, schema]) => ({
+        // 16.65 — a route's parameters are the path's, whatever the method, published with or
+        // without a schema to type them. OpenAPI has no optional path parameter, so an optional or
+        // rest segment is published present and says it may be left out (30.4, 30.5).
+        const schema = each.schema as
+            | { properties?: Record<string, unknown>; required?: string[] }
+            | undefined
+        const inPath = new Set<string>()
+        const parameters: unknown[] = []
+        for (const segment of parseRoutePattern(each.address)) {
+            if (segment.kind === 'static') continue
+            inPath.add(segment.name)
+            const parameter: Record<string, unknown> = {
+                name: segment.name,
+                in: 'path',
+                required: true,
+                schema: schema?.properties?.[segment.name] ?? {
+                    type: 'string',
+                },
+            }
+            if (segment.kind === 'optional')
+                parameter.description = 'May be left out, with its segment.'
+            else if (segment.kind === 'rest')
+                parameter.description =
+                    'The rest of the path, any number of segments, and may be left out with its segment.'
+            parameters.push(parameter)
+        }
+        const queried = schema !== undefined && argsInURL(each.method)
+        if (queried) {
+            const properties = schema.properties ?? {}
+            const required = new Set(schema.required ?? [])
+            for (const [name, member] of Object.entries(properties))
+                if (!inPath.has(name))
+                    parameters.push({
                         name,
                         in: 'query',
                         required: required.has(name),
-                        schema,
-                    }),
-                )
-            } else
-                operation.requestBody = {
-                    required: true,
-                    content: { 'application/json': { schema: each.schema } },
-                }
+                        schema: member,
+                    })
         }
-        paths[each.address] ??= {}
-        ;(paths[each.address] as Record<string, unknown>)[
-            each.method.toLowerCase()
-        ] = operation
+        if (parameters.length > 0) operation.parameters = parameters
+        if (schema !== undefined && !queried)
+            operation.requestBody = {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: withoutMembers(schema, inPath),
+                    },
+                },
+            }
+        // OpenAPI spells a parameter `{id}` where a route spells it `[id]`.
+        const path = each.address.replace(/\[+(?:\.\.\.)?([^\]]+)\]+/g, '{$1}')
+        paths[path] ??= {}
+        ;(paths[path] as Record<string, unknown>)[each.method.toLowerCase()] =
+            operation
     }
     const { name, version } = appIdentity()
     return {
@@ -163,15 +199,17 @@ function overTable<Built>(
     return found
 }
 
-const documents = new WeakMap<Map<string, Mounted>, Reactive<unknown>>()
+const documents = new WeakMap<
+    Map<string, Mounted>,
+    Reactive<ReturnType<typeof openApiOf>>
+>()
 
-/** The OpenAPI document over the route table, or `undefined` where `ABIDE_OPENAPI` is closed. */
+/** The OpenAPI document over the route table, or `undefined` where it lists no handler. 20.7. */
 export function openApi(
     handlers: Map<string, Mounted>,
 ): Reactive<unknown> | undefined {
-    return opened('ABIDE_OPENAPI')
-        ? overTable(documents, handlers, openApiOf)
-        : undefined
+    const document = overTable(documents, handlers, openApiOf)
+    return Object.keys(document().paths).length > 0 ? document : undefined
 }
 
 /** What the MCP surface publishes: a tool per call that takes args or writes, a resource per read. */
@@ -224,9 +262,10 @@ export class McpSurface {
         this.#answer = answer
     }
 
-    /** Whether `ABIDE_MCP` has opened it. 20.7. */
+    /** Whether the route table publishes any handler to it. 20.7. */
     get opened(): boolean {
-        return opened('ABIDE_MCP')
+        const { tools, resources } = this.#published()
+        return tools.length > 0 || resources.length > 0
     }
 
     #published(): Tools {
@@ -274,7 +313,14 @@ export class McpSurface {
         args: Record<string, unknown> | undefined,
         asker: Request,
     ): Promise<{ text: string; failed: boolean }> {
-        const answer = await this.#answer(callOf(asker, one, args))
+        let answer: Response
+        try {
+            answer = await this.#answer(callOf(asker, one, args))
+        } catch (thrown) {
+            // 15.8 — a path parameter no address carries, refused as the wire's 422 is (`rpcRequest`).
+            if (!isFailed(thrown)) throw thrown
+            answer = answered(thrown)
+        }
         return { text: await answer.text(), failed: answer.status >= 400 }
     }
 
@@ -355,7 +401,7 @@ export class McpSurface {
 }
 
 /**
- * Answers one MCP JSON-RPC request over `surface`, or `undefined` where `ABIDE_MCP` is closed.
+ * Answers one MCP JSON-RPC request over `surface`, or `undefined` where it publishes nothing.
  *
  * 20.9 — THE STREAMABLE-HTTP MCP ENDPOINT, answering JSON-RPC over `POST`, as the request's own
  * caller: a handler that takes no args is a resource, read at its address; one that takes args, and
@@ -406,7 +452,7 @@ function callOf(
     )
     const headers = new Headers(asked.headers)
     headers.delete('content-length')
-    // 38.69 — the answer is read here rather than sent on, and nothing in process decodes it.
+    // 38.68 — the answer is read here rather than sent on, and nothing in process decodes it.
     headers.delete('accept-encoding')
     if (call.body !== undefined) headers.set('content-type', 'application/json')
     return new Request(new URL(call.url, asked.url), {
@@ -415,16 +461,3 @@ function callOf(
         body: call.body ?? null,
     })
 }
-
-/**
- * The `GET` over `log.records`, mounted at `/__abide/logs`: closed until `ABIDE_LOGS` opens it.
- *
- * 36.7, 28.2 — A `GET` LIKE ANY OTHER, so it is followed as any `global` value is (18.20): the lines
- * held, then each line written as an `add` at `/-`. The rung is the gate, and makes it a guarded
- * `GET` — run once as a follow opens (18.8), and answering 404 while `ABIDE_LOGS` is closed.
- */
-export const LOGS_HANDLER = GET(log.records, {
-    middleware: [
-        (next, ctx) => (opened('ABIDE_LOGS') ? next(ctx) : refuse(404)),
-    ],
-})

package/src/server/hooks.ts

@@ -1,14 +1,25 @@
-// SECTION 37 — THE LIFECYCLE HOOKS, called from `src/server/app.ts` rather than exported from it
-// (37.1). Each call files its function here and hands back what unfiles it; `createApp` reads what
-// is filed once the app module has run.
+// SECTION 37 — THE LIFECYCLE HOOKS, called from a page's or a layout's `<script server>` rather
+// than exported from it (37.1). Each call files its function here, at the ROUTE of the file that
+// called it, and hands back what unfiles it; `createApp` reads what is filed once every module
+// holding a server block has run.
 //
-// PROCESS-WIDE, like the module that calls them: `app.ts` is evaluated once per process, so a
-// second `App` in it boots under the same hooks (42.12's sharing, from the other side).
+// WHICH ROUTE IS ASKED OF THE MODULE BEING EVALUATED, not of the hook: the compiled server module
+// calls `fileRoute` with its route before its server block's body and with `undefined` after it,
+// and a server block cannot await at its top level (34.3), so the window is synchronous. A hook
+// called outside every server block — a test, a script — files at the root.
+//
+// PROCESS-WIDE, like the modules that call them: each is evaluated once per process, so a second
+// `App` in it boots under the same hooks (42.12's sharing, from the other side).
 
 import { type Failed, isFailed } from '#shared/Failed.ts'
 import { namedLogger } from '#shared/log.ts'
 import type { Middleware } from '#shared/Middleware.ts'
 import { aborted, refuse } from '#shared/refuse.ts'
+import {
+    coversRoute,
+    parseRoutePattern,
+    type Segment,
+} from '#shared/routePattern.ts'
 import type { Schema } from '#shared/Schema.ts'
 import { config } from './config.ts'
 import { currentRequestScope } from './requestScope.ts'
@@ -21,40 +32,103 @@ export type ConfigOptions = { schema?: Schema<unknown> }
 
 type Wrapper = (inner: () => Promise<void>) => void | Promise<void>
 
-/** Everything the lifecycle hooks filed, for `createApp` to read once the app module has run. */
+/** One hook, at the route of the file that filed it. 37.1. */
+type Filed<T> = {
+    route: string
+    segments: Segment[]
+    item: T
+}
+
+/** Everything the lifecycle hooks filed, for `createApp` to read once the app's modules have run. */
 export const HOOKS = {
-    rungs: [] as AppRung[],
-    starts: [] as Wrapper[],
-    stops: [] as Wrapper[],
-    errors: [] as ((error: unknown) => unknown)[],
-    health: [] as (() => unknown)[],
-    config: undefined as
-        | {
-              defaults: ConfigDefaults | null
-              options: ConfigOptions | undefined
-          }
-        | undefined,
-    principal: undefined as
-        | ((claims: unknown) => unknown | Promise<unknown>)
-        | undefined,
+    rungs: [] as Filed<AppRung>[],
+    starts: [] as Filed<Wrapper>[],
+    stops: [] as Filed<Wrapper>[],
+    errors: [] as Filed<(error: unknown) => unknown>[],
+    health: [] as Filed<() => unknown>[],
+    config: [] as Filed<{
+        defaults: ConfigDefaults | null
+        options: ConfigOptions | undefined
+    }>[],
+    principal: [] as Filed<(claims: unknown) => unknown | Promise<unknown>>[],
+}
+
+const ROOT = '/'
+
+// The route a hook called now is filed at — the server block being evaluated, or the root.
+let filing: string | undefined
+
+/**
+ * Sets the route the hooks called next are filed at, or the root again for `undefined`.
+ *
+ * 37.1 — what a compiled server module calls around its `<script server>`; nothing an app writes.
+ */
+export function fileRoute(route: string | undefined): void {
+    filing = route
 }
 
 const LIFECYCLE_LOG = namedLogger('abide:lifecycle')
-const CONFIG_LOG = namedLogger('abide:config')
-const PRINCIPAL_LOG = namedLogger('abide:principal')
 
-function filed<T>(list: T[], item: T): () => void {
-    list.push(item)
+function filed<T>(list: Filed<T>[], item: T): () => void {
+    const route = filing ?? ROOT
+    const entry: Filed<T> = {
+        route,
+        segments: parseRoutePattern(route),
+        item,
+    }
+    list.push(entry)
+    // 37.7 — by route depth, then by route, then in the order called: kept sorted as it is filed,
+    // so a reader walks it in order and sorts nothing per request. The sort is stable and the
+    // entry lands last, so a tie stays in the order called.
+    list.sort(byRoute)
     return () => {
-        const at = list.indexOf(item)
+        const at = list.indexOf(entry)
         if (at !== -1) list.splice(at, 1)
     }
 }
 
+function byRoute(one: Filed<unknown>, two: Filed<unknown>): number {
+    if (one.segments.length !== two.segments.length)
+        return one.segments.length - two.segments.length
+    if (one.route !== two.route) return one.route < two.route ? -1 : 1
+    return 0
+}
+
+/** What `list` filed, in 37.7's order. */
+export function inOrder<T>(list: readonly Filed<T>[]): T[] {
+    const items: T[] = []
+    for (const entry of list) items.push(entry.item)
+    return items
+}
+
+/** The rungs filed at the root route, which run before routing. 37.3. */
+export function rootRungs(): AppRung[] {
+    const rungs: AppRung[] = []
+    for (const entry of HOOKS.rungs)
+        if (entry.route === ROOT) rungs.push(entry.item)
+    return rungs
+}
+
+/**
+ * The rungs filed below the root over `route`, outermost first.
+ *
+ * 37.2 — every rung filed at `route` or at a route that is its front, the root's aside: those ran
+ * before routing (37.3).
+ */
+export function rungsOver(route: string): AppRung[] {
+    const segments = parseRoutePattern(route)
+    const rungs: AppRung[] = []
+    for (const entry of HOOKS.rungs)
+        if (entry.route !== ROOT && coversRoute(entry.segments, segments))
+            rungs.push(entry.item)
+    return rungs
+}
+
 /**
- * Files middleware rungs the app runs before routing; returns what unfiles them.
+ * Files middleware rungs over the calling file's route; returns what unfiles them.
  *
- * 37.3 — pre-routing, over the request and the response, in the order registered.
+ * 37.3 at the root — pre-routing, over the request and the response, in the order registered. 37.2
+ * below it — after routing, over what that route and those below it answer.
  */
 export function middleware(...rungs: AppRung[]): () => void {
     const unfile: (() => void)[] = []
@@ -87,7 +161,7 @@ export function onStop(
 }
 
 /**
- * Files a hook handed every unexpected error; returns what unfiles it.
+ * Files a hook handed every unexpected error its route answers; returns what unfiles it.
  *
  * 37.5.
  */
@@ -98,52 +172,40 @@ export function onError(fn: (error: unknown) => unknown): () => void {
 /**
  * Files a health reporter whose account is merged over the baseline; returns what unfiles it.
  *
- * 25.2.
+ * 25.2, 37.7.
  */
 export function onHealth(report: () => unknown | Promise<unknown>): () => void {
     return filed(HOOKS.health, report)
 }
 
 /**
- * Sets the app's config defaults and schema; returns what unsets them.
+ * Files config defaults and a schema, composed with every other; returns what unfiles them.
  *
- * 27.6, 37.7 — a second replaces the first, schema and all, and says so. 27.10 — the read after
- * either is resolved under what is filed now, not what was filed when `config` was last read.
+ * 27.6, 37.7 — merged in route order rather than replacing. 27.10 — the read after either is
+ * resolved under what is filed now, not what was filed when `config` was last read.
  */
 export function onConfig(
     fn: ConfigDefaults | null,
     options?: ConfigOptions,
 ): () => void {
-    if (HOOKS.config !== undefined)
-        CONFIG_LOG.warning(
-            'a second onConfig replaced the first, and its schema with it. RULEBOOK 27.6.',
-        )
-    const entry = { defaults: fn, options }
-    HOOKS.config = entry
+    const unfile = filed(HOOKS.config, { defaults: fn, options })
     config.invalidate()
     return () => {
-        if (HOOKS.config !== entry) return
-        HOOKS.config = undefined
+        unfile()
         config.invalidate()
     }
 }
 
 /**
- * Sets the function resolving a principal from its claims; returns what unsets it.
+ * Files a function resolving a principal from its claims, composed with every other; returns what
+ * unfiles it.
  *
- * 37.7 — a second replaces the first, and says so.
+ * 37.7 — each is handed the claims, and what they answer is merged in route order.
  */
 export function onPrincipal(
     resolve: (claims: unknown) => unknown | Promise<unknown>,
 ): () => void {
-    if (HOOKS.principal !== undefined)
-        PRINCIPAL_LOG.warning(
-            'a second onPrincipal replaced the first. RULEBOOK 37.7.',
-        )
-    HOOKS.principal = resolve
-    return () => {
-        if (HOOKS.principal === resolve) HOOKS.principal = undefined
-    }
+    return filed(HOOKS.principal, resolve)
 }
 
 /**
@@ -163,12 +225,22 @@ export function reportUnexpected(error: unknown): void {
  * 12.6 — the half of 37.5 a failure already warned on its own namespace is owed.
  */
 export function handOnError(error: unknown): void {
-    for (const hook of HOOKS.errors)
+    // 37.5 — NEAREST ROUTE FIRST, over the route the request matched; outside every request, or
+    // before one matched, the root's alone.
+    const route = currentRequestScope()?.route
+    const segments = route === undefined ? undefined : parseRoutePattern(route)
+    for (let at = HOOKS.errors.length - 1; at >= 0; at -= 1) {
+        const entry = HOOKS.errors[at] as Filed<(error: unknown) => unknown>
+        const reaches =
+            entry.route === ROOT ||
+            (segments !== undefined && coversRoute(entry.segments, segments))
+        if (!reaches) continue
         try {
-            hook(error)
+            entry.item(error)
         } catch (thrown) {
             LIFECYCLE_LOG.error('an onError hook threw', thrown)
         }
+    }
 }
 
 /**