@nwire/koa 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @nwire/koa
+
+> The canonical HTTP adopter — a Koa server that consumes Nwire wires.
+
+```bash
+pnpm add @nwire/koa @nwire/app @nwire/endpoint @nwire/wires
+```
+
+## Quick start
+
+```ts
+import { createApp } from "@nwire/app";
+import { endpoint } from "@nwire/endpoint";
+import { post } from "@nwire/wires/http";
+import { httpKoa } from "@nwire/koa";
+import { z } from "zod";
+
+const app = createApp({ appName: "api" });
+
+app.wire(
+  post("/hello", { body: z.object({ name: z.string().min(1) }) }),
+  async (input) => ({ message: `Hello, ${input.name}!` }),
+);
+
+await endpoint("api", { port: 3000 })
+  .use(httpKoa({ prefix: "/api" }))
+  .mount(app)
+  .run();
+```
+
+## Config
+
+```ts
+httpKoa({
+  port: 3000,                   // 0 = ephemeral; .port() returns the bound port after boot
+  host: "0.0.0.0",
+  prefix: "/api",               // mounted on every wired route
+  helmet: true,                 // default-on; pass false to disable
+  cors: { origin: "*" },        // pass an options object or true; false to disable
+  bodyParser: { jsonLimit: "1mb" },
+  middleware: [requireUser],    // adopter-wide Koa middleware run before every wire
+  logger: myLogger,             // defaults to ConsoleLogger
+});
+```
+
+## Per-route middleware
+
+Wires can carry route-scoped middleware. `httpKoa` runs them after the
+adopter-wide chain and before the handler.
+
+```ts
+import { post } from "@nwire/wires/http";
+
+app.wire(
+  post("/admin/users", {
+    body: UserBody,
+    middleware: [requireRole("admin")],
+  }),
+  createUser,
+);
+```
+
+## Handler shape
+
+Two shapes are supported and route to the same dispatch:
+
+```ts
+// Foundation HTTP — plain (input, ctx)
+app.wire(
+  post("/order", { body: OrderBody }),
+  async (input, ctx) => {
+    const repo = ctx.resolve<OrderRepo>("orders");
+    return repo.create(input);
+  },
+);
+
+// Forge HandlerDefinition — routed through runtime.execute
+const placeOrder = defineHandler(placeOrderAction, async (input, ctx) => {
+  /* ... */
+});
+app.wire(post("/order", { body: OrderBody }), placeOrder);
+```
+
+The adopter detects forge handlers (`.run` + `runtime.execute` present)
+and routes them through the runtime so `action.before/after` hooks,
+retries, telemetry, and per-action middleware all fire. Plain handlers
+take the direct path with a minimal ctx (`resolve`, `logger`, `koa`,
+`envelope`).
+
+## Response shaping
+
+| Handler returns                                     | HTTP response                  |
+| --------------------------------------------------- | ------------------------------ |
+| `{ $kind: "response-instance", status, body }`      | `status`, JSON body            |
+| `{ $status, body }` (legacy envelope)               | `$status`, JSON body           |
+| anything else                                       | `200`, JSON serialized verbatim |
+| validation throws                                   | `400`, structured error JSON   |
+| handler throws `defineError`-shaped                 | `error.status`, structured JSON |
+
+## Testing
+
+`adapter.koa()` exposes the underlying Koa app for in-process testing
+via `supertest` or `simulateRequest` from `@nwire/test-kit`:
+
+```ts
+const koa = httpKoa({ port: 0 });
+const running = await endpoint("test", { ... }).use(koa).mount(app).run();
+
+const res = await simulateRequest(koa.koa(), {
+  method: "POST",
+  path: "/hello",
+  body: { name: "Alice" },
+});
+```
+
+`adapter.port()` returns the bound port (useful when `port: 0`).
+
+## Related
+
+- [`@nwire/endpoint`](../core-endpoint) — the lifecycle host
+- [`@nwire/wires`](../core-wires) — `get`/`post`/`put`/`patch`/`del`
+  binding factories
+- [`@nwire/express`](../nwire-express) — the Express-flavored adopter

package/dist/http-koa.d.ts

@@ -0,0 +1,116 @@
+/**
+ * `@nwire/koa` — Koa-backed HTTP adopter.
+ *
+ *   import { httpKoa } from "@nwire/koa";
+ *
+ *   await endpoint("api", { port: 3000 })
+ *     .use(httpKoa({ helmet: true, cors: true }))
+ *     .mount(app)
+ *     .run();
+ *
+ * The adopter consumes wires whose `binding.$adapter === "http"`. For
+ * each wire it mounts a Koa route on the configured verb + path, parses
+ * params / body / query against the binding's zod schemas, builds a
+ * minimal handler ctx (input + resolve + logger), and invokes the
+ * wire's handler. Response shaping is intentionally loose at this stage
+ * — the handler returns a value that becomes ctx.body; status defaults
+ * to 200; { $status, body } objects unwrap.
+ *
+ * 0.10 first-pass scope:
+ *   - helmet + cors + body parser layered when configured
+ *   - per-wire handler dispatch via Koa router
+ *   - per-request scoped container (parent = wire's source app)
+ *   - dispatched as Adapter so endpoint().use(httpKoa()).mount(app).run()
+ *     works end-to-end
+ *
+ * Deferred (lands in 0.10.x):
+ *   - OpenAPI document + /docs serving
+ *   - Scalar docs UI
+ *   - Inspect endpoints under /_nwire/*
+ *   - Per-route middleware (RouteBinding.middleware)
+ *   - Per-request envelope scope (forge integration)
+ *   - fromKoaApp / fromKoaMiddleware / fromKoa auto-wrapper
+ */
+import type { Adapter } from "@nwire/endpoint";
+import { type Logger } from "@nwire/logger";
+import Koa from "koa";
+import cors from "@koa/cors";
+export interface HttpKoaConfig {
+    /** Port to listen on. Falls through to endpoint's config.port if undefined. */
+    readonly port?: number;
+    readonly host?: string;
+    /** URL prefix mounted on the router (e.g. "/api"). */
+    readonly prefix?: string;
+    /** Enable koa-helmet. Default true. */
+    readonly helmet?: boolean;
+    /** Enable @koa/cors. Default false. Pass an object to forward CORS opts. */
+    readonly cors?: boolean | Parameters<typeof cors>[0];
+    /** Body parser options forwarded to koa-bodyparser. */
+    readonly bodyParser?: any;
+    /**
+     * Adopter-wide Koa middleware — runs before every wire's handler.
+     * Use for authn / authz / request-id / logging concerns shared across
+     * every route the adopter serves.
+     */
+    readonly middleware?: readonly Koa.Middleware[];
+    readonly logger?: Logger;
+    /**
+     * OpenAPI 3.1 doc — three forms of input:
+     *   - `auto: true` — generate the spec by walking the adopter's wires;
+     *     needs `@asteasolutions/zod-to-openapi` installed as a peer dep
+     *   - `spec` — pass a pre-built object (skip codegen entirely)
+     *   - `generator` — lazy generation per request, e.g. for cache-busting
+     *
+     * The spec is served at `path` (default `/openapi.json`). `title`,
+     * `version`, `description`, `serverUrl`, `prefix` are forwarded to the
+     * auto-generator if used.
+     */
+    readonly openapi?: {
+        readonly auto?: boolean;
+        readonly spec?: object;
+        readonly generator?: () => object | Promise<object>;
+        readonly path?: string;
+        readonly title?: string;
+        readonly version?: string;
+        readonly description?: string;
+        readonly serverUrl?: string;
+    };
+    /**
+     * Scalar UI for the OpenAPI spec. When `enabled`, mounts an HTML page
+     * at `path` (default `/docs`) that loads Scalar from the JSDelivr CDN
+     * and points at the configured `openapi.path`.
+     */
+    readonly docs?: boolean | {
+        readonly path?: string;
+        readonly title?: string;
+    };
+    /**
+     * `/_nwire/*` introspection surface (manifest, wires, runtime, actors,
+     * dispatch). `true` mounts with defaults; pass an object for prefix or
+     * adopter-wide guards (`middleware: [requireAdmin]`).
+     */
+    readonly inspect?: boolean | import("./inspect.js").InspectConfig;
+}
+/** Minimal handler-ctx shape the adopter constructs per request. */
+export interface HttpKoaHandlerCtx {
+    resolve<T = unknown>(name: string): T;
+    readonly logger: Logger;
+    /** The Koa context, for adapters that need raw request access. */
+    readonly koa: Koa.ParameterizedContext;
+}
+/**
+ * `httpKoa(config)` — build the HTTP adopter. Returns an `Adapter` the
+ * endpoint installs via `.use(...)`.
+ */
+/**
+ * The adopter handle. Extends the base `Adapter` contract with a
+ * `port()` accessor so tests + tooling can discover the bound port
+ * when `config.port === 0`.
+ */
+export interface HttpKoaAdapter extends Adapter {
+    port(): number | undefined;
+    /** Underlying Koa instance — present after boot. Tests can pass this to
+     * supertest(adapter.koa()!.callback()) for in-process request simulation. */
+    koa(): Koa | undefined;
+}
+export declare function httpKoa(config?: HttpKoaConfig): HttpKoaAdapter;

package/dist/http-koa.js

@@ -0,0 +1,350 @@
+/**
+ * `@nwire/koa` — Koa-backed HTTP adopter.
+ *
+ *   import { httpKoa } from "@nwire/koa";
+ *
+ *   await endpoint("api", { port: 3000 })
+ *     .use(httpKoa({ helmet: true, cors: true }))
+ *     .mount(app)
+ *     .run();
+ *
+ * The adopter consumes wires whose `binding.$adapter === "http"`. For
+ * each wire it mounts a Koa route on the configured verb + path, parses
+ * params / body / query against the binding's zod schemas, builds a
+ * minimal handler ctx (input + resolve + logger), and invokes the
+ * wire's handler. Response shaping is intentionally loose at this stage
+ * — the handler returns a value that becomes ctx.body; status defaults
+ * to 200; { $status, body } objects unwrap.
+ *
+ * 0.10 first-pass scope:
+ *   - helmet + cors + body parser layered when configured
+ *   - per-wire handler dispatch via Koa router
+ *   - per-request scoped container (parent = wire's source app)
+ *   - dispatched as Adapter so endpoint().use(httpKoa()).mount(app).run()
+ *     works end-to-end
+ *
+ * Deferred (lands in 0.10.x):
+ *   - OpenAPI document + /docs serving
+ *   - Scalar docs UI
+ *   - Inspect endpoints under /_nwire/*
+ *   - Per-route middleware (RouteBinding.middleware)
+ *   - Per-request envelope scope (forge integration)
+ *   - fromKoaApp / fromKoaMiddleware / fromKoa auto-wrapper
+ */
+import http from "node:http";
+import { dummyContainer } from "@nwire/container";
+import { ConsoleLogger } from "@nwire/logger";
+import Koa from "koa";
+import bodyParser from "koa-bodyparser";
+import cors from "@koa/cors";
+import helmet from "koa-helmet";
+import KoaRouter from "@koa/router";
+function isHttpBinding(b) {
+    return (typeof b === "object" &&
+        b !== null &&
+        b.$adapter === "http" &&
+        typeof b.verb === "string" &&
+        typeof b.path === "string");
+}
+export function httpKoa(config = {}) {
+    let server;
+    let koaInstance;
+    const logger = config.logger ?? new ConsoleLogger();
+    return {
+        $kind: "adapter",
+        kind: "http",
+        port() {
+            if (!server)
+                return undefined;
+            const addr = server.address();
+            return typeof addr === "object" && addr !== null ? addr.port : undefined;
+        },
+        koa() {
+            return koaInstance;
+        },
+        async boot(ctx) {
+            const koa = new Koa();
+            koaInstance = koa;
+            // Top-level error mapper — catches throws from middleware and
+            // unmatched routes. Renders defineError-shaped values with their
+            // {code, status, summary} envelope; otherwise opaque 500.
+            koa.use(async (kctx, next) => {
+                try {
+                    await next();
+                }
+                catch (err) {
+                    const e = err;
+                    kctx.status = typeof e.status === "number" ? e.status : 500;
+                    kctx.body = {
+                        error: {
+                            code: e.code ?? "internal_error",
+                            summary: e.summary ?? e.message ?? "Internal error",
+                        },
+                    };
+                }
+            });
+            if (config.helmet !== false) {
+                koa.use(helmet());
+            }
+            if (config.cors) {
+                koa.use(cors(typeof config.cors === "object" ? config.cors : undefined));
+            }
+            koa.use(bodyParser(config.bodyParser));
+            // OpenAPI doc + Scalar UI (mounted before per-route middleware so
+            // they don't sit behind auth gates).
+            const openapiPath = config.openapi?.path ?? "/openapi.json";
+            const docsConfig = config.docs === true ? {} : config.docs === false ? null : (config.docs ?? null);
+            const docsPath = docsConfig?.path ?? "/docs";
+            const docsTitle = docsConfig?.title ?? "API docs";
+            if (config.openapi?.spec || config.openapi?.generator || config.openapi?.auto) {
+                // Auto-generation walks the adopter's wires at mount time and
+                // caches the resulting doc. `spec` and `generator` short-circuit
+                // the build; pass either if you want full control of the doc.
+                let cachedAutoSpec;
+                const buildAuto = async () => {
+                    if (cachedAutoSpec)
+                        return cachedAutoSpec;
+                    const { generateOpenApi } = await import("./openapi.js");
+                    cachedAutoSpec = await generateOpenApi(ctx.wires, {
+                        title: config.openapi.title,
+                        version: config.openapi.version,
+                        description: config.openapi.description,
+                        serverUrl: config.openapi.serverUrl,
+                        prefix: config.prefix,
+                    });
+                    return cachedAutoSpec;
+                };
+                koa.use(async (kctx, next) => {
+                    if (kctx.method !== "GET" || kctx.path !== openapiPath)
+                        return next();
+                    const spec = config.openapi.spec ??
+                        (config.openapi.generator ? await config.openapi.generator() : await buildAuto());
+                    kctx.type = "application/json";
+                    kctx.body = JSON.stringify(spec);
+                });
+            }
+            if (docsConfig !== null) {
+                koa.use(async (kctx, next) => {
+                    if (kctx.method !== "GET" || kctx.path !== docsPath)
+                        return next();
+                    kctx.type = "text/html";
+                    kctx.body = `<!doctype html>
+<html>
+  <head>
+    <title>${docsTitle}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <script id="api-reference" data-url="${openapiPath}"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>`;
+                });
+            }
+            // /_nwire/* introspection — mounted before adopter-wide auth so
+            // Studio can read manifest/wires/runtime without an admin token.
+            // Production consumers gate via inspect.middleware.
+            if (config.inspect) {
+                const inspectConfig = config.inspect === true ? {} : config.inspect;
+                const { mountInspect } = await import("./inspect.js");
+                // Find a representative source app — we mount inspect against the
+                // first wire's owning app; the wire collection is what we report.
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const firstApp = ctx.wires[0]?.app;
+                mountInspect(koa, {
+                    wires: ctx.wires,
+                    app: firstApp,
+                    adopterKind: "http",
+                    config: inspectConfig,
+                });
+            }
+            // Adopter-wide middleware runs before every wired handler.
+            for (const mw of config.middleware ?? []) {
+                koa.use(mw);
+            }
+            const router = config.prefix
+                ? new KoaRouter({ prefix: config.prefix })
+                : new KoaRouter();
+            for (const wire of ctx.wires) {
+                if (!isHttpBinding(wire.binding))
+                    continue;
+                const binding = wire.binding;
+                const verb = binding.verb;
+                const path = binding.path;
+                const handler = async (kctx) => {
+                    // Parse + merge params / body / query into a flat input.
+                    let input = {};
+                    try {
+                        if (binding.params) {
+                            Object.assign(input, binding.params.parse(kctx.params));
+                        }
+                        if (binding.body) {
+                            Object.assign(input, binding.body.parse(kctx.request.body));
+                        }
+                        if (binding.query) {
+                            Object.assign(input, binding.query.parse(kctx.request.query));
+                        }
+                        if (!binding.params && !binding.body && !binding.query) {
+                            // No schemas — pass merged raw values as input for hand-rolled
+                            // resolvers. Adopters can still read kctx via handlerCtx.koa.
+                            input = {
+                                ...kctx.params,
+                                ...kctx.request.body,
+                                ...kctx.request.query,
+                            };
+                        }
+                    }
+                    catch (err) {
+                        kctx.status = 400;
+                        kctx.body = {
+                            error: {
+                                code: "validation_failed",
+                                summary: err.message,
+                            },
+                        };
+                        return;
+                    }
+                    // Per-request scope: child container of the source app's container.
+                    const parentContainer = ctx.containerOf(wire) ?? dummyContainer();
+                    const reqContainer = parentContainer.createScope();
+                    const handlerCtx = {
+                        resolve: (name) => reqContainer.resolve(name),
+                        logger,
+                        koa: kctx,
+                    };
+                    // Per-request envelope derived from request headers — userId set
+                    // by adopter middleware lands on it; tenant flows from a header
+                    // for simple multi-tenancy; correlationId / causationId come
+                    // from upstream callers so distributed traces stitch in.
+                    const envelopePartial = {
+                        tenant: kctx.request.headers["x-tenant"] ?? undefined,
+                        userId: kctx.state.userId ?? undefined,
+                        correlationId: kctx.request.headers["x-correlation-id"] ?? undefined,
+                        causationId: kctx.request.headers["x-causation-id"] ?? undefined,
+                    };
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const wireApp = wire.app;
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const runtimeExecute = wireApp?.runtime?.execute;
+                    let result;
+                    try {
+                        if (runtimeExecute) {
+                            // Unified dispatch — runtime.execute builds the canonical
+                            // ctx (input + envelope + execute + emit + enqueue + resolve
+                            // + scope) for both HandlerDefinition and plain `(input, ctx)`
+                            // function shapes, threads transport extras (logger, koa)
+                            // onto the same ctx, and runs the hook chain when present.
+                            result = await runtimeExecute.call(wireApp.runtime, wire.handler, input, envelopePartial, { logger: handlerCtx.logger, koa: handlerCtx.koa });
+                        }
+                        else {
+                            // No-runtime fallback — standalone interface without an App.
+                            // Plain functions still get the unified ctx shape; lookups go
+                            // through the per-request container directly.
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            const fn = wire.handler.run ?? wire.handler;
+                            const fullCtx = { ...handlerCtx, envelope: envelopePartial };
+                            result = await fn(input, fullCtx);
+                        }
+                    }
+                    catch (err) {
+                        // Generic error envelope; downstream phases hook in nwire-error
+                        // mapping + sanitised production responses.
+                        const e = err;
+                        kctx.status = typeof e.status === "number" ? e.status : 500;
+                        kctx.body = {
+                            error: {
+                                code: e.code ?? "internal_error",
+                                summary: e.summary ?? e.message ?? "Internal error",
+                            },
+                        };
+                        return;
+                    }
+                    // Response shaping:
+                    //   - { $kind: "response-instance", status, body } — from defineResource
+                    //   - { $status, body } — legacy envelope
+                    //   - anything else — body verbatim, status 200
+                    if (result &&
+                        typeof result === "object" &&
+                        result.$kind === "response-instance") {
+                        const env = result;
+                        // Koa rewrites status to 204 when body is set to null/undefined.
+                        // For explicit 202/304/410-style "no body, but specific status"
+                        // we set the empty body first then force the status afterward.
+                        if (env.body === undefined || env.body === null) {
+                            kctx.body = "";
+                            kctx.status = env.status ?? 204;
+                            kctx.length = 0;
+                        }
+                        else {
+                            kctx.body = env.body;
+                            kctx.status = env.status ?? 200;
+                        }
+                    }
+                    else if (result &&
+                        typeof result === "object" &&
+                        "$status" in result) {
+                        const env = result;
+                        kctx.status = env.$status ?? 200;
+                        kctx.body = env.body;
+                    }
+                    else if (result === undefined || result === null) {
+                        kctx.status = 204;
+                        kctx.body = undefined;
+                    }
+                    else {
+                        kctx.status = kctx.status === 404 ? 200 : kctx.status;
+                        kctx.body = result;
+                    }
+                };
+                // Per-route middleware lands as a Koa middleware chain before
+                // the dispatch handler. The binding's `middleware` field is
+                // declared `unknown` at the @nwire/wires layer; we narrow
+                // here to Koa.Middleware shape and append.
+                const routeMw = (binding.middleware ??
+                    []);
+                switch (verb) {
+                    case "get":
+                        router.get(path, ...routeMw, handler);
+                        break;
+                    case "post":
+                        router.post(path, ...routeMw, handler);
+                        break;
+                    case "put":
+                        router.put(path, ...routeMw, handler);
+                        break;
+                    case "patch":
+                        router.patch(path, ...routeMw, handler);
+                        break;
+                    case "delete":
+                        router.delete(path, ...routeMw, handler);
+                        break;
+                }
+            }
+            koa.use(router.routes()).use(router.allowedMethods());
+            // Listen if a port is available: adopter-level config.port wins,
+            // otherwise fall back to the endpoint-level port hint from boot ctx.
+            const listenPort = config.port ?? ctx.port;
+            const listenHost = config.host ?? ctx.host ?? "0.0.0.0";
+            if (listenPort !== undefined) {
+                server = http.createServer(koa.callback());
+                await new Promise((resolve) => server.listen(listenPort, listenHost, resolve));
+                logger.info?.(`[http-koa] listening on ${listenHost}:${listenPort}`, undefined);
+            }
+            // Register a health check that surfaces "this adopter is alive."
+            ctx.addCheck({
+                name: "http-koa",
+                check: () => undefined,
+            });
+        },
+        async shutdown() {
+            if (server) {
+                await new Promise((resolve) => server.close(() => {
+                    resolve();
+                }));
+                server = undefined;
+            }
+            koaInstance = undefined;
+        },
+    };
+}

package/dist/inspect.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `/_nwire/*` — read + dispatch surface Studio (and MCP tooling) reads
+ * to render the live state of a running app.
+ *
+ *   GET  /_nwire/manifest    — app name + adopter info + wire summary
+ *   GET  /_nwire/wires       — every wire's binding kind + key fields
+ *   GET  /_nwire/runtime     — telemetry tap + framework-event log shape
+ *   GET  /_nwire/actors/:t   — actor instances of type `t` from the store
+ *   POST /_nwire/dispatch    — invoke a registered handler by name
+ *
+ * `inspect: true` (or `inspect: { ... }`) on `httpKoa({ ... })` mounts
+ * these before per-route middleware so they don't sit behind auth gates.
+ *
+ * Production deployments should add an admin guard via
+ * `inspect: { middleware: [requireAdmin] }`.
+ */
+import type Koa from "koa";
+import type { Wire } from "@nwire/wires";
+export interface InspectConfig {
+    readonly enabled?: boolean;
+    readonly prefix?: string;
+    /** Run before every /_nwire/* handler — for auth/audit. */
+    readonly middleware?: readonly Koa.Middleware[];
+}
+export interface MountInspectOptions {
+    readonly wires: ReadonlyArray<Wire>;
+    readonly app?: any;
+    readonly adopterKind: string;
+    readonly config: InspectConfig;
+}
+export declare function mountInspect(koa: Koa, opts: MountInspectOptions): void;

package/dist/inspect.js

@@ -0,0 +1,142 @@
+/**
+ * `/_nwire/*` — read + dispatch surface Studio (and MCP tooling) reads
+ * to render the live state of a running app.
+ *
+ *   GET  /_nwire/manifest    — app name + adopter info + wire summary
+ *   GET  /_nwire/wires       — every wire's binding kind + key fields
+ *   GET  /_nwire/runtime     — telemetry tap + framework-event log shape
+ *   GET  /_nwire/actors/:t   — actor instances of type `t` from the store
+ *   POST /_nwire/dispatch    — invoke a registered handler by name
+ *
+ * `inspect: true` (or `inspect: { ... }`) on `httpKoa({ ... })` mounts
+ * these before per-route middleware so they don't sit behind auth gates.
+ *
+ * Production deployments should add an admin guard via
+ * `inspect: { middleware: [requireAdmin] }`.
+ */
+function summarizeWire(wire) {
+    const b = wire.binding;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const h = wire.handler;
+    return {
+        adapter: b.$adapter ?? "unknown",
+        kind: b.kind ?? "unknown",
+        verb: b.verb,
+        path: b.path,
+        tool: b.tool,
+        queue: b.queue,
+        cron: b.cron,
+        handlerName: h?.name ?? h?.action?.name,
+        source: b.source,
+    };
+}
+export function mountInspect(koa, opts) {
+    const prefix = opts.config.prefix ?? "/_nwire";
+    const handle = async (kctx, next) => {
+        if (!kctx.path.startsWith(prefix + "/"))
+            return next();
+        // Adopter-wide middleware first (if any). We model these as a chain;
+        // Koa doesn't expose runtime chain composition for arbitrary inputs,
+        // so we fold them with a manual chain.
+        let i = 0;
+        const chain = opts.config.middleware ?? [];
+        const runNext = async () => {
+            const mw = chain[i++];
+            if (mw)
+                return mw(kctx, runNext);
+            await dispatchInspect(kctx, opts);
+        };
+        await runNext();
+    };
+    koa.use(handle);
+}
+async function dispatchInspect(kctx, opts) {
+    const prefix = opts.config.prefix ?? "/_nwire";
+    const sub = kctx.path.slice(prefix.length); // "/manifest", "/wires", …
+    const wires = opts.wires.map(summarizeWire);
+    if (kctx.method === "GET" && sub === "/manifest") {
+        kctx.type = "application/json";
+        kctx.body = JSON.stringify({
+            appName: opts.app?.appName ?? null,
+            adopter: opts.adopterKind,
+            wireCount: opts.wires.length,
+            generatedAt: new Date().toISOString(),
+        });
+        return;
+    }
+    if (kctx.method === "GET" && sub === "/wires") {
+        kctx.type = "application/json";
+        kctx.body = JSON.stringify({ wires });
+        return;
+    }
+    if (kctx.method === "GET" && sub === "/runtime") {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const rt = opts.app?.runtime;
+        kctx.type = "application/json";
+        kctx.body = JSON.stringify({
+            appName: opts.app?.appName ?? null,
+            hasRuntime: typeof rt === "object" && rt !== null,
+            lifecycle: rt?.lifecycle ?? "unknown",
+            handlers: typeof rt?.listHandlers === "function"
+                ? rt.listHandlers().map((h) => typeof h === "string" ? h : (h?.name ?? null)).filter(Boolean)
+                : [],
+        });
+        return;
+    }
+    if (kctx.method === "GET" && sub.startsWith("/actors/")) {
+        // Per-type actor listing requires an ActorStore binding. We try to
+        // resolve it from the container; if absent, return 501.
+        const actorType = sub.slice("/actors/".length);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const container = opts.app?.container;
+        let store;
+        try {
+            store = container?.resolve("actor.store");
+        }
+        catch {
+            /* not registered */
+        }
+        if (!store?.list) {
+            kctx.status = 501;
+            kctx.type = "application/json";
+            kctx.body = JSON.stringify({ error: "no actor.store on container" });
+            return;
+        }
+        const items = await store.list(actorType);
+        kctx.type = "application/json";
+        kctx.body = JSON.stringify({ actorType, items });
+        return;
+    }
+    if (kctx.method === "POST" && sub === "/dispatch") {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const body = kctx.request.body ?? {};
+        const handlerName = body.handler;
+        const input = body.input ?? {};
+        if (!handlerName) {
+            kctx.status = 400;
+            kctx.body = { error: { code: "missing_handler" } };
+            return;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const rt = opts.app?.runtime;
+        if (!rt?.execute || typeof rt.getHandler !== "function") {
+            kctx.status = 501;
+            kctx.body = { error: { code: "no_runtime" } };
+            return;
+        }
+        try {
+            const handler = rt.getHandler(handlerName);
+            const result = await rt.execute(handler, input);
+            kctx.type = "application/json";
+            kctx.body = JSON.stringify({ result });
+        }
+        catch (err) {
+            const e = err;
+            kctx.status = typeof e.status === "number" ? e.status : 500;
+            kctx.body = { error: { code: e.code ?? "internal_error", summary: e.message ?? "" } };
+        }
+        return;
+    }
+    kctx.status = 404;
+    kctx.body = { error: { code: "unknown_inspect_route", path: kctx.path } };
+}

package/dist/openapi.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generate an OpenAPI 3.1 document from a Nwire App's wires.
+ *
+ * Walks `app.interface.wires`, picks the HTTP bindings, and emits a path
+ * entry per `(verb, path)` populated from the binding's `openapi`
+ * metadata + zod schemas via `@asteasolutions/zod-to-openapi`. The output
+ * is JSON-stringifiable and can be served at `/openapi.json` directly.
+ *
+ * Optional dependency: `@asteasolutions/zod-to-openapi` is a peer dep.
+ * Consumers that don't need OpenAPI don't pay the install cost; consumers
+ * who do install it once and call `httpKoa({ openapi: { auto: true } })`.
+ */
+import type { Wire } from "@nwire/wires";
+export interface GenerateOpenApiOptions {
+    readonly title?: string;
+    readonly version?: string;
+    readonly description?: string;
+    readonly serverUrl?: string;
+    /** Prefix the spec paths with this. Match the httpKoa prefix. */
+    readonly prefix?: string;
+}
+/**
+ * Build an OpenAPI 3.1 document from a wire collection.
+ *
+ * Requires `@asteasolutions/zod-to-openapi` to be installed. Throws a
+ * clear error otherwise; install it on the consumer side.
+ */
+export declare function generateOpenApi(wires: ReadonlyArray<Wire>, options?: GenerateOpenApiOptions): Promise<object>;

package/dist/openapi.js

@@ -0,0 +1,102 @@
+/**
+ * Generate an OpenAPI 3.1 document from a Nwire App's wires.
+ *
+ * Walks `app.interface.wires`, picks the HTTP bindings, and emits a path
+ * entry per `(verb, path)` populated from the binding's `openapi`
+ * metadata + zod schemas via `@asteasolutions/zod-to-openapi`. The output
+ * is JSON-stringifiable and can be served at `/openapi.json` directly.
+ *
+ * Optional dependency: `@asteasolutions/zod-to-openapi` is a peer dep.
+ * Consumers that don't need OpenAPI don't pay the install cost; consumers
+ * who do install it once and call `httpKoa({ openapi: { auto: true } })`.
+ */
+function isOpenApiBinding(b) {
+    return (typeof b === "object" &&
+        b !== null &&
+        b.$adapter === "http" &&
+        typeof b.verb === "string" &&
+        typeof b.path === "string");
+}
+// Convert Koa-style `/users/:id` to OpenAPI `{id}` notation.
+function toOpenApiPath(p) {
+    return p.replace(/:(\w+)/g, "{$1}");
+}
+/**
+ * Build an OpenAPI 3.1 document from a wire collection.
+ *
+ * Requires `@asteasolutions/zod-to-openapi` to be installed. Throws a
+ * clear error otherwise; install it on the consumer side.
+ */
+export async function generateOpenApi(wires, options = {}) {
+    let zodToOpenapi;
+    try {
+        zodToOpenapi = await import("@asteasolutions/zod-to-openapi");
+    }
+    catch {
+        throw new Error("@nwire/koa: generateOpenApi() needs `@asteasolutions/zod-to-openapi` — `pnpm add @asteasolutions/zod-to-openapi` then retry.");
+    }
+    const { OpenAPIRegistry, OpenApiGeneratorV31, extendZodWithOpenApi } = zodToOpenapi;
+    const z = await import("zod");
+    extendZodWithOpenApi(z.z ?? z);
+    const registry = new OpenAPIRegistry();
+    const prefix = options.prefix ?? "";
+    for (const wire of wires) {
+        if (!isOpenApiBinding(wire.binding))
+            continue;
+        const b = wire.binding;
+        if (!b.openapi)
+            continue;
+        const path = prefix + toOpenApiPath(b.path);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const responses = {
+            "200": { description: "Success" },
+        };
+        // Returns from the binding override the default 200 envelope.
+        if (b.openapi.returns?.length) {
+            const first = b.openapi.returns[0];
+            const status = String(first?.status ?? 200);
+            const schema = first?.resource?.schema;
+            responses[status] = schema
+                ? {
+                    description: "Success",
+                    content: { "application/json": { schema } },
+                }
+                : { description: "Success" };
+        }
+        if (b.openapi.errors?.length) {
+            for (const e of b.openapi.errors) {
+                if (typeof e.status === "number") {
+                    responses[String(e.status)] = {
+                        description: e.code ?? "Error",
+                    };
+                }
+            }
+        }
+        registry.registerPath({
+            method: b.verb,
+            path,
+            operationId: b.openapi.operation,
+            tags: b.openapi.tags ? [...b.openapi.tags] : undefined,
+            summary: b.openapi.summary,
+            description: b.openapi.description,
+            request: {
+                ...(b.params ? { params: b.params } : {}),
+                ...(b.query ? { query: b.query } : {}),
+                ...(b.body
+                    ? { body: { content: { "application/json": { schema: b.body } } } }
+                    : {}),
+            },
+            responses,
+        });
+    }
+    const generator = new OpenApiGeneratorV31(registry.definitions);
+    return generator.generateDocument({
+        openapi: "3.1.0",
+        info: {
+            title: options.title ?? "API",
+            version: options.version ?? "1.0.0",
+            description: options.description,
+        },
+        servers: options.serverUrl ? [{ url: options.serverUrl }] : undefined,
+    });
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@nwire/koa",
+  "version": "0.10.0",
+  "description": "Nwire — Koa-backed HTTP adopter. Consumes wires from @nwire/wires/http and serves them as Koa routes under endpoint lifecycle.",
+  "keywords": [
+    "adopter",
+    "http",
+    "koa",
+    "nwire"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/http-koa.js",
+  "types": "./dist/http-koa.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/http-koa.js",
+      "types": "./dist/http-koa.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@koa/cors": "^5.0.0",
+    "@koa/router": "^13.1.0",
+    "koa": "^2.16.1",
+    "koa-bodyparser": "^4.4.1",
+    "koa-helmet": "^8.0.1",
+    "zod": "^4.0.0",
+    "@nwire/endpoint": "0.10.0",
+    "@nwire/wires": "0.10.0",
+    "@nwire/logger": "0.10.0",
+    "@nwire/container": "0.10.0"
+  },
+  "devDependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.0.0",
+    "@types/koa": "^2.15.0",
+    "@types/koa-bodyparser": "^4.3.13",
+    "@types/koa__cors": "^5.0.0",
+    "@types/koa__router": "^12.0.5",
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "@nwire/app": "0.10.0",
+    "@nwire/handler": "0.10.0"
+  },
+  "peerDependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@asteasolutions/zod-to-openapi": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}