@abide/abide 0.57.1 → 0.100.0

package/src/server/fenceServer.ts

@@ -0,0 +1,48 @@
+// 16.28 AND 16.29 — WHAT THE BROWSER'S BUNDLE SEES OF `server/`. A page imports a handler from the
+// module the app wrote it in, and the server's render reaches that module as written; the bundle a
+// browser loads reaches it through here instead, and gets the wrapper the build wrote in its place
+// (`WIRE_DIRECTORY`). Anything else under `server/` is refused, so a secret, a database client or
+// the server barrel cannot ride into the browser by being imported from the wrong file.
+//
+// A PLUGIN ON THE BUNDLE, NOT A REWRITE OF THE PAGES. A rewrite reaches the specifiers the compiler
+// emitted; the bundle reaches every edge — a `#ui` helper importing a handler included.
+
+import { realpathSync } from 'node:fs' // bun exposes no realpath of its own
+import { WIRE_DIRECTORY } from './CLIENT_BUILD.ts'
+
+/**
+ * The bundler plugin handing the browser each handler's wrapper and refusing the rest of `server/`.
+ *
+ * `modules` is the compiled app, keyed by path below the output directory as `compileApp` hands it
+ * back — where the wrappers are.
+ */
+export function fenceServer(
+    root: string,
+    modules: Map<string, string>,
+): Bun.BunPlugin {
+    // BOTH SPELLINGS OF THE ROOT, because the bundler names a file with its symlinks resolved and an
+    // app under `/tmp` is `/private/tmp` to it.
+    const roots = new Set([root, realpathSync(root)])
+    return {
+        name: 'abide-fence',
+        setup(build) {
+            for (const at of roots)
+                build.onLoad(
+                    {
+                        filter: new RegExp(`^${RegExp.escape(at)}/server/`),
+                    },
+                    (args) => {
+                        const source = args.path.slice(at.length + 1)
+                        const wrapper = modules.get(
+                            `${WIRE_DIRECTORY}/${source}`,
+                        )
+                        if (wrapper === undefined)
+                            throw new Error(
+                                `abide: ${source} is server code, and the browser's bundle imports it. A browser may import a handler from a module under server/rpc and nothing else under server/. RULEBOOK 16.29.`,
+                            )
+                        return { contents: wrapper, loader: 'ts' }
+                    },
+                )
+        },
+    }
+}

package/src/server/generatedSurfaces.ts

@@ -0,0 +1,430 @@
+// 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).
+//
+// 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).
+//
+// WHAT EACH SURFACE LISTS, AND AS WHAT, is `surfaceOf`'s — the command line's listing reads it too —
+// and the MCP protocol is `McpSurface`'s alone, whoever frames it: this endpoint over http, or a
+// provider that speaks MCP itself (`assistant`'s `forwardOf`).
+//
+// WHAT ONLY THE TYPE SAYS IS THE BUILD'S, arriving here on the mount: 16.37's default of `mcp` and
+// `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 { type Reactive, reactive } from '#shared/reactive/index.ts'
+import { refuse } from '#shared/refuse.ts'
+import { GET } from '#shared/rpc.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 { crossingOrigin, crossingRefusal } from './crossingOrigin.ts'
+import { MCP_PROTOCOL_VERSION } from './MCP_PROTOCOL_VERSION.ts'
+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 }
+
+/** Every handler `surface` lists (`surfaceOf`). */
+function listed(
+    handlers: Map<string, Mounted>,
+    surface: 'openapi' | 'mcp',
+): Published[] {
+    const found: Published[] = []
+    for (const mounted of handlers.values()) {
+        const one = surfaceOf(mounted, surface)
+        if (one === undefined) {
+            if (surface === 'mcp') MCP_LOG.debug('withheld', mounted.address)
+            continue
+        }
+        found.push({
+            ...one,
+            keyed: mounted.handler.keyed,
+            name: one.path.replace(/[^a-zA-Z0-9_-]/g, '_'),
+        })
+    }
+    return found
+}
+
+/**
+ * A refusal's shape in the OpenAPI document: RFC 9457's members, and `data` as abide's extension.
+ *
+ * 15.1 — `type` is the refusal's name, or `about:blank` for an undeclared one.
+ */
+const PROBLEM_SCHEMA = {
+    type: 'object',
+    required: ['type', 'title', 'status', 'detail'],
+    properties: {
+        type: { type: 'string' },
+        title: { type: 'string' },
+        status: { type: 'integer' },
+        detail: { type: 'string' },
+        data: {},
+    },
+}
+
+/** The OpenAPI 3.1 document, each handler's `JsonSchema` published as it stands. 20.6. */
+function openApiOf(handlers: Map<string, Mounted>): unknown {
+    const paths: Record<string, Record<string, unknown>> = {}
+    for (const each of listed(handlers, 'openapi')) {
+        const operation: Record<string, unknown> = {
+            operationId: each.name,
+            responses: {
+                '200': {
+                    description: 'The value.',
+                    content: { 'application/json': {} },
+                },
+                '204': { description: 'Nothing to say.' },
+                default: {
+                    description: 'A refusal, as Problem Details (RFC 9457).',
+                    content: {
+                        'application/problem+json': { schema: PROBLEM_SCHEMA },
+                    },
+                },
+            },
+        }
+        if (each.description !== undefined)
+            operation.description = each.description
+        if (each.keyed && each.schema === undefined)
+            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]) => ({
+                        name,
+                        in: 'query',
+                        required: required.has(name),
+                        schema,
+                    }),
+                )
+            } else
+                operation.requestBody = {
+                    required: true,
+                    content: { 'application/json': { schema: each.schema } },
+                }
+        }
+        paths[each.address] ??= {}
+        ;(paths[each.address] as Record<string, unknown>)[
+            each.method.toLowerCase()
+        ] = operation
+    }
+    const { name, version } = appIdentity()
+    return {
+        openapi: '3.1.0',
+        info: { title: name, version },
+        paths,
+    }
+}
+
+/**
+ * A surface built by `build` over the route table, as a `reactive` cached in `built`.
+ *
+ * 20.5 — FROM A `reactive` OVER THE ROUTE TABLE, with no `ttl`: the table is fixed for the life of
+ * the app, so each surface is built once and served thereafter. A surface's own cache, so an app
+ * that opens one does not build the other.
+ */
+function overTable<Built>(
+    built: WeakMap<Map<string, Mounted>, Reactive<Built>>,
+    handlers: Map<string, Mounted>,
+    build: (handlers: Map<string, Mounted>) => Built,
+): Reactive<Built> {
+    let found = built.get(handlers)
+    if (found === undefined) {
+        found = reactive(() => build(handlers), {
+            global: true,
+        }) as unknown as Reactive<Built>
+        built.set(handlers, found)
+    }
+    return found
+}
+
+const documents = new WeakMap<Map<string, Mounted>, Reactive<unknown>>()
+
+/** The OpenAPI document over the route table, or `undefined` where `ABIDE_OPENAPI` is closed. */
+export function openApi(
+    handlers: Map<string, Mounted>,
+): Reactive<unknown> | undefined {
+    return opened('ABIDE_OPENAPI')
+        ? overTable(documents, handlers, openApiOf)
+        : undefined
+}
+
+/** What the MCP surface publishes: a tool per call that takes args or writes, a resource per read. */
+type Tools = { tools: Published[]; resources: Published[] }
+
+const published = new WeakMap<Map<string, Mounted>, Reactive<Tools>>()
+
+function toolsOf(handlers: Map<string, Mounted>): Tools {
+    const found: Tools = { tools: [], resources: [] }
+    for (const one of listed(handlers, 'mcp'))
+        if (one.keyed || one.method !== 'GET') found.tools.push(one)
+        else found.resources.push(one)
+    return found
+}
+
+type JsonRpc = {
+    jsonrpc: '2.0'
+    id?: number | string | null
+    method: string
+    params?: Record<string, unknown>
+}
+
+/** An MCP request answered as JSON-RPC's `result` or `error`, without the envelope. */
+export type McpReply =
+    | { result: unknown; error?: undefined }
+    | { result?: undefined; error: { code: number; message: string } }
+
+/** JSON-RPC's `error`. */
+export function mcpFailure(code: number, message: string): McpReply {
+    return { error: { code, message } }
+}
+
+/**
+ * The app's MCP surface: what it publishes off the route table, and the protocol answered over it.
+ *
+ * ONE PER APP, held by every scope that app answers (`AnsweringApp`), so the endpoint, a `Toolbox`
+ * and a bridge's Claude Code all answer from it in process — the JSON-RPC envelope is only the
+ * endpoint's to frame. A call is still a request through the app's own `fetch`, so its rungs run
+ * and refuse as they would for anyone (20.10), and in the app it was made to (42.12).
+ */
+export class McpSurface {
+    readonly #handlers: Map<string, Mounted>
+    readonly #answer: (request: Request) => Promise<Response>
+
+    constructor(
+        handlers: Map<string, Mounted>,
+        answer: (request: Request) => Promise<Response>,
+    ) {
+        this.#handlers = handlers
+        this.#answer = answer
+    }
+
+    /** Whether `ABIDE_MCP` has opened it. 20.7. */
+    get opened(): boolean {
+        return opened('ABIDE_MCP')
+    }
+
+    #published(): Tools {
+        return overTable(published, this.#handlers, toolsOf)()
+    }
+
+    /** Every tool it lists. 20.9. */
+    list(): ToolDefinition[] {
+        const listing: ToolDefinition[] = []
+        for (const tool of this.#published().tools) {
+            if (tool.description === undefined)
+                MCP_LOG.warning(
+                    `${tool.name} is published with no description.`,
+                )
+            listing.push({
+                name: tool.name,
+                description: tool.description ?? '',
+                inputSchema: tool.schema ?? { type: 'object' },
+            })
+        }
+        return listing
+    }
+
+    /** What calling the tool `name` as `asker` answered, a refusal or a missing tool a failed one. */
+    call(
+        name: string,
+        args: unknown,
+        asker: Request,
+    ): Promise<{ text: string; failed: boolean }> {
+        const tool = this.#tool(name)
+        if (tool === undefined)
+            return Promise.resolve({
+                text: `No tool named ${name}.`,
+                failed: true,
+            })
+        return this.#called(tool, args as Record<string, unknown>, asker)
+    }
+
+    #tool(name: unknown): Published | undefined {
+        return this.#published().tools.find((one) => one.name === name)
+    }
+
+    async #called(
+        one: Published,
+        args: Record<string, unknown> | undefined,
+        asker: Request,
+    ): Promise<{ text: string; failed: boolean }> {
+        const answer = await this.#answer(callOf(asker, one, args))
+        return { text: await answer.text(), failed: answer.status >= 400 }
+    }
+
+    /** One MCP request, made as `asker`, as JSON-RPC's `result` or `error`. */
+    async answer(
+        method: string,
+        params: Record<string, unknown> | undefined,
+        asker: Request,
+    ): Promise<McpReply> {
+        switch (method) {
+            case 'initialize':
+                return {
+                    result: {
+                        protocolVersion: MCP_PROTOCOL_VERSION,
+                        capabilities: { tools: {}, resources: {} },
+                        serverInfo: appIdentity(),
+                    },
+                }
+            case 'ping':
+                return { result: {} }
+            case 'tools/list':
+                return { result: { tools: this.list() } }
+            case 'resources/list':
+                return {
+                    result: {
+                        resources: this.#published().resources.map(
+                            (resource) => ({
+                                uri: `abide:${resource.address}`,
+                                name: resource.name,
+                                description: resource.description ?? '',
+                                mimeType: 'application/json',
+                            }),
+                        ),
+                    },
+                }
+            case 'tools/call': {
+                const tool = this.#tool(params?.name)
+                if (tool === undefined)
+                    return mcpFailure(
+                        -32602,
+                        `No tool named ${String(params?.name)}.`,
+                    )
+                const { text, failed } = await this.#called(
+                    tool,
+                    params?.arguments as Record<string, unknown> | undefined,
+                    asker,
+                )
+                return {
+                    result: {
+                        content: [{ type: 'text', text }],
+                        isError: failed,
+                    },
+                }
+            }
+            case 'resources/read': {
+                const uri = String(params?.uri ?? '')
+                const resource = this.#published().resources.find(
+                    (one) => `abide:${one.address}` === uri,
+                )
+                if (resource === undefined)
+                    return mcpFailure(-32602, `No resource at ${uri}.`)
+                const { text, failed } = await this.#called(
+                    resource,
+                    undefined,
+                    asker,
+                )
+                if (failed) return mcpFailure(-32603, text)
+                return {
+                    result: {
+                        contents: [{ uri, mimeType: 'application/json', text }],
+                    },
+                }
+            }
+            default:
+                return mcpFailure(-32601, `No method ${method}.`)
+        }
+    }
+}
+
+/**
+ * Answers one MCP JSON-RPC request over `surface`, or `undefined` where `ABIDE_MCP` is closed.
+ *
+ * 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
+ * every mutation, is a tool.
+ */
+export async function answerMcp(
+    surface: McpSurface,
+    request: Request,
+): Promise<unknown> {
+    if (!surface.opened) return undefined
+    if (request.method !== 'POST')
+        return new Response(null, { status: 405, headers: { allow: 'POST' } })
+    // 20.12, 16.13 — A POST FROM ANOTHER ORIGIN IS REFUSED, as a mutation's is: a tool call runs a handler
+    // with the caller's own cookies, and a `text/plain` body is sent cross-origin with no preflight.
+    const crossing = crossingOrigin(request.headers.get('origin'), request.url)
+    if (crossing !== null) return answered(crossingRefusal(crossing, 'POST'))
+    let message: JsonRpc
+    try {
+        message = (await request.json()) as JsonRpc
+    } catch {
+        return {
+            jsonrpc: '2.0',
+            id: null,
+            ...mcpFailure(-32700, 'Parse error'),
+        }
+    }
+    // A notification is acknowledged and answered with nothing.
+    if (message.id === undefined) return new Response(null, { status: 202 })
+    const reply = await surface.answer(message.method, message.params, request)
+    return { jsonrpc: '2.0', id: message.id, ...reply }
+}
+
+/**
+ * The call a tool is, as the request a browser would make.
+ *
+ * The caller's own headers are carried, so a rung reading them decides as it would for that caller.
+ */
+function callOf(
+    asked: Request,
+    handler: Listed,
+    args: Record<string, unknown> | undefined,
+): Request {
+    const method = handler.method
+    const call = rpcRequest(
+        method,
+        handler.address,
+        argsInURL(method) ? args : (args ?? {}),
+    )
+    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.
+    headers.delete('accept-encoding')
+    if (call.body !== undefined) headers.set('content-type', 'application/json')
+    return new Request(new URL(call.url, asked.url), {
+        method,
+        headers,
+        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

@@ -0,0 +1,190 @@
+// 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.
+//
+// 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).
+
+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 type { Schema } from '#shared/Schema.ts'
+import { config } from './config.ts'
+import { currentRequestScope } from './requestScope.ts'
+
+export type AppRung = Middleware<{ request: Request }, Response>
+
+export type Env = Record<string, string | undefined>
+export type ConfigDefaults = (env: Env) => unknown
+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. */
+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,
+}
+
+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)
+    return () => {
+        const at = list.indexOf(item)
+        if (at !== -1) list.splice(at, 1)
+    }
+}
+
+/**
+ * Files middleware rungs the app runs before routing; returns what unfiles them.
+ *
+ * 37.3 — pre-routing, over the request and the response, in the order registered.
+ */
+export function middleware(...rungs: AppRung[]): () => void {
+    const unfile: (() => void)[] = []
+    for (const rung of rungs) unfile.push(filed(HOOKS.rungs, rung))
+    return () => {
+        for (const undo of unfile) undo()
+    }
+}
+
+/**
+ * Files a hook wrapping the app's boot; returns what unfiles it.
+ *
+ * 37.4 — wraps `createApp`. `start` is the boot; a hook that never calls it boots nothing.
+ */
+export function onStart(
+    fn: (start: () => Promise<void>) => void | Promise<void>,
+): () => void {
+    return filed(HOOKS.starts, fn)
+}
+
+/**
+ * Files a hook wrapping the app's teardown; returns what unfiles it.
+ *
+ * 37.4 — wraps `App.stop`'s teardown.
+ */
+export function onStop(
+    fn: (stop: () => Promise<void>) => void | Promise<void>,
+): () => void {
+    return filed(HOOKS.stops, fn)
+}
+
+/**
+ * Files a hook handed every unexpected error; returns what unfiles it.
+ *
+ * 37.5.
+ */
+export function onError(fn: (error: unknown) => unknown): () => void {
+    return filed(HOOKS.errors, fn)
+}
+
+/**
+ * Files a health reporter whose account is merged over the baseline; returns what unfiles it.
+ *
+ * 25.2.
+ */
+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.
+ *
+ * 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.
+ */
+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
+    config.invalidate()
+    return () => {
+        if (HOOKS.config !== entry) return
+        HOOKS.config = undefined
+        config.invalidate()
+    }
+}
+
+/**
+ * Sets the function resolving a principal from its claims; returns what unsets it.
+ *
+ * 37.7 — a second replaces the first, and says so.
+ */
+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
+    }
+}
+
+/**
+ * Logs an unexpected error and hands it to every `onError` hook.
+ *
+ * 37.5 — AN UNEXPECTED ERROR IS ALWAYS WRITTEN, and every `onError` is then handed it. A hook that
+ * throws is itself written rather than let loose on the request that was already failing.
+ */
+export function reportUnexpected(error: unknown): void {
+    LIFECYCLE_LOG.error(error)
+    handOnError(error)
+}
+
+/**
+ * Hands an error to every `onError` hook, writing nothing of its own.
+ *
+ * 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)
+        try {
+            hook(error)
+        } catch (thrown) {
+            LIFECYCLE_LOG.error('an onError hook threw', thrown)
+        }
+}
+
+/**
+ * The `Failed` a thrown error answers with: a refusal as it is, anything else a reported 500.
+ *
+ * 16.40 — a refusal at its own status. 16.41 — anything else is the server's fault, and says
+ * nothing about itself to the caller: the log and `onError` get it (37.5).
+ *
+ * 16.63 — A CLIENT THAT LEFT IS NOT A FAULT: once the request's signal has aborted, what was thrown
+ * is the cancellation arriving, so it answers `aborted` and is not reported — a handler's throw and a
+ * page render's alike, because both answer here.
+ */
+export function failureOf(error: unknown): Failed<string, unknown> {
+    if (isFailed(error)) return error
+    if (currentRequestScope()?.request?.signal.aborted === true)
+        return aborted()
+    reportUnexpected(error)
+    return refuse(500)
+}