@ontrails/hono 1.0.0-beta.15

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc -b

package/.turbo/turbo-lint.log

@@ -0,0 +1,3 @@
+$ oxlint ./src
+Found 0 warnings and 0 errors.
+Finished in 69ms on 3 files with 93 rules using 24 threads.

package/.turbo/turbo-typecheck.log

@@ -0,0 +1 @@
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @ontrails/hono
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+  - @ontrails/http@1.0.0-beta.15

package/README.md

@@ -0,0 +1,27 @@
+# @ontrails/hono
+
+Hono surface connector for Trails. Use this package when you want to serve a topo over HTTP with Hono while keeping `@ontrails/http` focused on framework-agnostic route building.
+
+## Usage
+
+```typescript
+import { surface } from '@ontrails/hono';
+import { graph } from './app';
+
+await surface(graph, { port: 3000 });
+```
+
+For custom HTTP integrations or route inspection, keep using `deriveHttpRoutes()` from `@ontrails/http`.
+
+## Installation
+
+```bash
+bun add @ontrails/http @ontrails/hono
+```
+
+## Migration
+
+This package replaces the old `@ontrails/http/hono` subpath.
+
+- Before: `import { trailhead } from '@ontrails/http/hono'`
+- After: `import { surface } from '@ontrails/hono'`

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createApp, surface, type CreateAppOptions, type SurfaceHttpResult, } from './surface.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,OAAO,EACP,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createApp, surface, } from './surface.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,OAAO,GAGR,MAAM,cAAc,CAAC"}

package/dist/surface.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Hono connector for Trails HTTP routes.
+ *
+ * Takes framework-agnostic HttpRouteDefinition[] and wires them into a
+ * Hono application, handling request parsing, response mapping, and errors.
+ *
+ * ```ts
+ * const graph = topo("myapp", entity);
+ * await surface(graph, { port: 3000 });
+ * ```
+ */
+import type { Intent, Layer, ResourceOverrideMap, Topo, TrailContextInit } from '@ontrails/core';
+import { Hono } from 'hono';
+export interface CreateAppOptions {
+    readonly basePath?: string | undefined;
+    /** Config values for resources that declare a `config` schema, keyed by resource ID. */
+    readonly configValues?: Readonly<Record<string, Record<string, unknown>>> | undefined;
+    readonly createContext?: (() => TrailContextInit | Promise<TrailContextInit>) | undefined;
+    readonly exclude?: readonly string[] | undefined;
+    readonly hostname?: string | undefined;
+    readonly include?: readonly string[] | undefined;
+    readonly intent?: readonly Intent[] | undefined;
+    readonly layers?: readonly Layer[] | undefined;
+    readonly name?: string | undefined;
+    readonly port?: number | undefined;
+    readonly resources?: ResourceOverrideMap | undefined;
+    /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
+    readonly validate?: boolean | undefined;
+}
+export interface SurfaceHttpResult {
+    readonly close: () => Promise<void>;
+    readonly url: string;
+}
+/**
+ * Build HTTP routes from a topo and register them on a Hono app.
+ */
+export declare const createApp: (graph: Topo, options?: CreateAppOptions) => Hono;
+/**
+ * Build a Hono app from a topo and start serving it with Bun.
+ *
+ * @remarks Always starts a Bun server. Use `createApp(graph)` for an
+ * unserved Hono app that you can wire into your own server.
+ */
+export declare const surface: (graph: Topo, options?: CreateAppOptions) => Promise<SurfaceHttpResult>;
+//# sourceMappingURL=surface.d.ts.map

package/dist/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EACV,MAAM,EACN,KAAK,EACL,mBAAmB,EACnB,IAAI,EACJ,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAU5B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,wFAAwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjD,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,GACpD,SAAS,CAAC;IACd,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACrD,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AA2MD;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,OAAO,IAAI,EACX,UAAS,gBAAqB,KAC7B,IAuBF,CAAC;AAwBF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAClB,OAAO,IAAI,EACX,UAAS,gBAAqB,KAC7B,OAAO,CAAC,iBAAiB,CAI3B,CAAC"}

package/dist/surface.js

@@ -0,0 +1,219 @@
+/**
+ * Hono connector for Trails HTTP routes.
+ *
+ * Takes framework-agnostic HttpRouteDefinition[] and wires them into a
+ * Hono application, handling request parsing, response mapping, and errors.
+ *
+ * ```ts
+ * const graph = topo("myapp", entity);
+ * await surface(graph, { port: 3000 });
+ * ```
+ */
+import { isTrailsError, mapTransportError } from '@ontrails/core';
+import { Hono } from 'hono';
+import { deriveHttpRoutes } from '@ontrails/http';
+// ---------------------------------------------------------------------------
+// Request parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse query params into a plain object, preserving scalar-vs-array shape.
+ *
+ * A single `?tag=one` stays a scalar string, while repeated keys like
+ * `?tag=one&tag=two` become arrays. Schema validation owns whether that shape
+ * is accepted; the connector does not coerce singleton values into arrays.
+ */
+const parseQueryParams = (c) => {
+    const result = {};
+    const url = new URL(c.req.url);
+    const seenKeys = new Set();
+    for (const key of url.searchParams.keys()) {
+        if (seenKeys.has(key)) {
+            continue;
+        }
+        seenKeys.add(key);
+        const all = url.searchParams.getAll(key);
+        result[key] = all.length > 1 ? all : all[0];
+    }
+    return result;
+};
+/** Sentinel indicating a JSON parse failure. */
+const JSON_PARSE_ERROR = Symbol('JSON_PARSE_ERROR');
+/** Return true when the request has no body content. */
+const isEmptyBody = (c) => {
+    const contentLength = c.req.header('Content-Length');
+    if (contentLength !== undefined) {
+        return Number.parseInt(contentLength, 10) === 0;
+    }
+    // No Content-Length header — treat as empty when Content-Type is also absent.
+    return c.req.header('Content-Type') === undefined;
+};
+/** Read input from request based on input source. */
+const readInput = async (c, inputSource) => {
+    if (inputSource === 'query') {
+        return parseQueryParams(c);
+    }
+    if (isEmptyBody(c)) {
+        return {};
+    }
+    try {
+        return await c.req.json();
+    }
+    catch {
+        return JSON_PARSE_ERROR;
+    }
+};
+// ---------------------------------------------------------------------------
+// Response mapping
+// ---------------------------------------------------------------------------
+/** Map a TrailsError or generic Error to an HTTP error response. */
+const mapErrorResponse = (error) => {
+    if (isTrailsError(error)) {
+        return {
+            body: {
+                error: {
+                    category: error.category,
+                    code: error.name,
+                    message: error.message,
+                },
+            },
+            status: mapTransportError('http', error),
+        };
+    }
+    return {
+        body: {
+            error: {
+                category: 'internal',
+                code: 'InternalError',
+                message: error.message,
+            },
+        },
+        status: 500,
+    };
+};
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+/** Map a Result to an HTTP response via Hono context. */
+const mapResultToResponse = (result, c) => {
+    if (result.isOk()) {
+        return c.json({ data: result.value }, 200);
+    }
+    const { body, status } = mapErrorResponse(result.error ?? new Error('Unknown error'));
+    return c.json(body, status);
+};
+/** Convert a caught unknown value to an error response. */
+const handleCaughtError = (error, c) => {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const { body, status } = mapErrorResponse(err);
+    return c.json(body, status);
+};
+/** Create a Hono handler from a route definition. */
+const createHonoHandler = (route) => async (c) => {
+    const rawInput = await readInput(c, route.inputSource);
+    if (rawInput === JSON_PARSE_ERROR) {
+        return c.json({
+            error: {
+                category: 'validation',
+                code: 'ValidationError',
+                message: 'Invalid JSON in request body',
+            },
+        }, 400);
+    }
+    const requestId = c.req.header('X-Request-ID') ?? undefined;
+    const { signal: abortSignal } = c.req.raw;
+    try {
+        const result = await route.execute(rawInput, requestId, abortSignal);
+        return mapResultToResponse(result, c);
+    }
+    catch (error) {
+        return handleCaughtError(error, c);
+    }
+};
+/** Route registration keyed by HTTP method. */
+const routeRegistrars = {
+    DELETE: (hono, path, handler) => {
+        hono.delete(path, handler);
+    },
+    GET: (hono, path, handler) => {
+        hono.get(path, handler);
+    },
+    POST: (hono, path, handler) => {
+        hono.post(path, handler);
+    },
+};
+const registerRoutes = (hono, routes) => {
+    for (const route of routes) {
+        const handler = createHonoHandler(route);
+        routeRegistrars[route.method](hono, route.path, handler);
+    }
+};
+// ---------------------------------------------------------------------------
+// Global error handler
+// ---------------------------------------------------------------------------
+const registerErrorHandler = (hono) => {
+    // oxlint-disable-next-line prefer-await-to-callbacks -- Hono's onError API requires a callback
+    hono.onError((err, c) => c.json({
+        error: {
+            category: 'internal',
+            code: 'InternalError',
+            message: err.message,
+        },
+    }, 500));
+};
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// createApp
+// ---------------------------------------------------------------------------
+/**
+ * Build HTTP routes from a topo and register them on a Hono app.
+ */
+export const createApp = (graph, options = {}) => {
+    const hono = new Hono();
+    registerErrorHandler(hono);
+    const routesResult = deriveHttpRoutes(graph, {
+        basePath: options.basePath,
+        configValues: options.configValues,
+        createContext: options.createContext,
+        exclude: options.exclude,
+        include: options.include,
+        intent: options.intent,
+        layers: options.layers,
+        resources: options.resources,
+        validate: options.validate,
+    });
+    if (routesResult.isErr()) {
+        throw routesResult.error;
+    }
+    registerRoutes(hono, routesResult.value);
+    return hono;
+};
+const startServer = (hono, options) => {
+    const server = Bun.serve({
+        fetch: hono.fetch,
+        hostname: options.hostname ?? '0.0.0.0',
+        port: options.port ?? 3000,
+    });
+    return {
+        close: async () => {
+            await server.stop(true);
+        },
+        url: String(server.url),
+    };
+};
+// ---------------------------------------------------------------------------
+// surface
+// ---------------------------------------------------------------------------
+/**
+ * Build a Hono app from a topo and start serving it with Bun.
+ *
+ * @remarks Always starts a Bun server. Use `createApp(graph)` for an
+ * unserved Hono app that you can wire into your own server.
+ */
+export const surface = async (graph, options = {}) => {
+    // oxlint-disable-next-line require-await -- async ensures createApp() throws become rejected promises, not uncaught exceptions
+    const hono = createApp(graph, options);
+    return startServer(hono, options);
+};
+//# sourceMappingURL=surface.js.map

package/dist/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"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"}

package/dist/trailhead.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Hono connector for Trails HTTP routes.
+ *
+ * Takes framework-agnostic HttpRouteDefinition[] and wires them into a
+ * Hono application, handling request parsing, response mapping, and errors.
+ *
+ * ```ts
+ * const graph = topo("myapp", entity);
+ * await surface(graph, { port: 3000 });
+ * ```
+ */
+import type { Intent, Layer, ResourceOverrideMap, Topo, TrailContextInit } from '@ontrails/core';
+import { Hono } from 'hono';
+export interface TrailheadHttpOptions {
+    readonly basePath?: string | undefined;
+    /** Config values for resources that declare a `config` schema, keyed by resource ID. */
+    readonly configValues?: Readonly<Record<string, Record<string, unknown>>> | undefined;
+    readonly createContext?: (() => TrailContextInit | Promise<TrailContextInit>) | undefined;
+    readonly exclude?: readonly string[] | undefined;
+    readonly hostname?: string | undefined;
+    readonly include?: readonly string[] | undefined;
+    readonly intent?: readonly Intent[] | undefined;
+    readonly layers?: readonly Layer[] | undefined;
+    readonly name?: string | undefined;
+    readonly port?: number | undefined;
+    readonly resources?: ResourceOverrideMap | undefined;
+    /** Set false to return the Hono app without starting a server. */
+    readonly serve?: boolean | undefined;
+    /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
+    readonly validate?: boolean | undefined;
+}
+export type CreateAppOptions = Omit<TrailheadHttpOptions, 'hostname' | 'port' | 'serve'>;
+export interface SurfaceHttpResult {
+    readonly close: () => Promise<void>;
+    readonly url: string;
+}
+/**
+ * Build HTTP routes from a topo and register them on a Hono app.
+ */
+export declare const createApp: (app: Topo, options?: CreateAppOptions) => Hono;
+/**
+ * Build a Hono app from a topo and start serving it with Bun.
+ */
+export declare const surface: (app: Topo, options?: TrailheadHttpOptions) => Promise<SurfaceHttpResult>;
+/**
+ * Build HTTP routes from a topo, create a Hono app, and optionally start serving.
+ *
+ * Topo validation runs before route construction — pass `validate: false`
+ * to skip it (e.g. during hot-reload or progressive startup).
+ */
+export declare const trailhead: (app: Topo, options?: TrailheadHttpOptions) => Promise<Hono>;
+//# sourceMappingURL=trailhead.d.ts.map

package/dist/trailhead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailhead.d.ts","sourceRoot":"","sources":["../src/trailhead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EACV,MAAM,EACN,KAAK,EACL,mBAAmB,EACnB,IAAI,EACJ,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAY5B,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,wFAAwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjD,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,GACpD,SAAS,CAAC;IACd,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACrD,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,oBAAoB,EACpB,UAAU,GAAG,MAAM,GAAG,OAAO,CAC9B,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AA2PD;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,IAAI,EAAE,UAAS,gBAAqB,KAAG,IAuBrE,CAAC;AAwBF;;GAEG;AACH,eAAO,MAAM,OAAO,GAClB,KAAK,IAAI,EACT,UAAS,oBAAyB,KACjC,OAAO,CAAC,iBAAiB,CAU3B,CAAC;AAMF;;;;;GAKG;AAEH,eAAO,MAAM,SAAS,GACpB,KAAK,IAAI,EACT,UAAS,oBAAyB,KACjC,OAAO,CAAC,IAAI,CAQd,CAAC"}

package/dist/trailhead.js

@@ -0,0 +1,258 @@
+/**
+ * Hono connector for Trails HTTP routes.
+ *
+ * Takes framework-agnostic HttpRouteDefinition[] and wires them into a
+ * Hono application, handling request parsing, response mapping, and errors.
+ *
+ * ```ts
+ * const graph = topo("myapp", entity);
+ * await surface(graph, { port: 3000 });
+ * ```
+ */
+import { isTrailsError, mapTransportError } from '@ontrails/core';
+import { Hono } from 'hono';
+import { deriveHttpRoutes } from '@ontrails/http';
+/** Unwrap optional/default wrappers to reach the underlying Zod type name. */
+const unwrapZodType = (node) => {
+    let current = node;
+    while (current._zod.def['type'] === 'optional' ||
+        current._zod.def['type'] === 'default') {
+        current = current._zod.def['innerType'];
+    }
+    return current._zod.def['type'];
+};
+/** Extract the object shape from a Zod schema, or undefined if not an object. */
+const extractShape = (schema) => {
+    const s = schema;
+    if (s._zod.def['type'] !== 'object') {
+        return undefined;
+    }
+    return s._zod.def['shape'];
+};
+/** Collect top-level field names whose underlying type is array. */
+const collectArrayKeys = (inputSchema) => {
+    const shape = inputSchema ? extractShape(inputSchema) : undefined;
+    if (!shape) {
+        return new Set();
+    }
+    const keys = new Set();
+    for (const [key, value] of Object.entries(shape)) {
+        if (unwrapZodType(value) === 'array') {
+            keys.add(key);
+        }
+    }
+    return keys;
+};
+/** Parse query params into a plain object, preserving raw strings for Zod. */
+const parseQueryParams = (c, inputSchema) => {
+    const result = {};
+    const url = new URL(c.req.url);
+    const arrayKeys = collectArrayKeys(inputSchema);
+    for (const key of url.searchParams.keys()) {
+        // Already collected via getAll
+        if (key in result) {
+            continue;
+        }
+        const all = url.searchParams.getAll(key);
+        result[key] = all.length > 1 || arrayKeys.has(key) ? all : all[0];
+    }
+    return result;
+};
+/** Sentinel indicating a JSON parse failure. */
+const JSON_PARSE_ERROR = Symbol('JSON_PARSE_ERROR');
+/** Return true when the request has no body content. */
+const isEmptyBody = (c) => {
+    const contentLength = c.req.header('Content-Length');
+    if (contentLength !== undefined) {
+        return Number.parseInt(contentLength, 10) === 0;
+    }
+    // No Content-Length header — treat as empty when Content-Type is also absent.
+    return c.req.header('Content-Type') === undefined;
+};
+/** Read input from request based on input source. */
+const readInput = async (c, inputSource, inputSchema) => {
+    if (inputSource === 'query') {
+        return parseQueryParams(c, inputSchema);
+    }
+    if (isEmptyBody(c)) {
+        return {};
+    }
+    try {
+        return await c.req.json();
+    }
+    catch {
+        return JSON_PARSE_ERROR;
+    }
+};
+// ---------------------------------------------------------------------------
+// Response mapping
+// ---------------------------------------------------------------------------
+/** Map a TrailsError or generic Error to an HTTP error response. */
+const mapErrorResponse = (error) => {
+    if (isTrailsError(error)) {
+        return {
+            body: {
+                error: {
+                    category: error.category,
+                    code: error.name,
+                    message: error.message,
+                },
+            },
+            status: mapTransportError('http', error),
+        };
+    }
+    return {
+        body: {
+            error: {
+                category: 'internal',
+                code: 'InternalError',
+                message: error.message,
+            },
+        },
+        status: 500,
+    };
+};
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+/** Map a Result to an HTTP response via Hono context. */
+const mapResultToResponse = (result, c) => {
+    if (result.isOk()) {
+        return c.json({ data: result.value }, 200);
+    }
+    const { body, status } = mapErrorResponse(result.error ?? new Error('Unknown error'));
+    return c.json(body, status);
+};
+/** Convert a caught unknown value to an error response. */
+const handleCaughtError = (error, c) => {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const { body, status } = mapErrorResponse(err);
+    return c.json(body, status);
+};
+/** Create a Hono handler from a route definition. */
+const createHonoHandler = (route) => async (c) => {
+    const rawInput = await readInput(c, route.inputSource, route.trail.input);
+    if (rawInput === JSON_PARSE_ERROR) {
+        return c.json({
+            error: {
+                category: 'validation',
+                code: 'ValidationError',
+                message: 'Invalid JSON in request body',
+            },
+        }, 400);
+    }
+    const requestId = c.req.header('X-Request-ID') ?? undefined;
+    const { signal: abortSignal } = c.req.raw;
+    try {
+        const result = await route.execute(rawInput, requestId, abortSignal);
+        return mapResultToResponse(result, c);
+    }
+    catch (error) {
+        return handleCaughtError(error, c);
+    }
+};
+/** Route registration keyed by HTTP method. */
+const routeRegistrars = {
+    DELETE: (hono, path, handler) => {
+        hono.delete(path, handler);
+    },
+    GET: (hono, path, handler) => {
+        hono.get(path, handler);
+    },
+    POST: (hono, path, handler) => {
+        hono.post(path, handler);
+    },
+};
+const registerRoutes = (hono, routes) => {
+    for (const route of routes) {
+        const handler = createHonoHandler(route);
+        routeRegistrars[route.method](hono, route.path, handler);
+    }
+};
+// ---------------------------------------------------------------------------
+// Global error handler
+// ---------------------------------------------------------------------------
+const registerErrorHandler = (hono) => {
+    // oxlint-disable-next-line prefer-await-to-callbacks -- Hono's onError API requires a callback
+    hono.onError((err, c) => c.json({
+        error: {
+            category: 'internal',
+            code: 'InternalError',
+            message: err.message,
+        },
+    }, 500));
+};
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// createApp
+// ---------------------------------------------------------------------------
+/**
+ * Build HTTP routes from a topo and register them on a Hono app.
+ */
+export const createApp = (app, options = {}) => {
+    const hono = new Hono();
+    registerErrorHandler(hono);
+    const routesResult = deriveHttpRoutes(app, {
+        basePath: options.basePath,
+        configValues: options.configValues,
+        createContext: options.createContext,
+        exclude: options.exclude,
+        include: options.include,
+        intent: options.intent,
+        layers: options.layers,
+        resources: options.resources,
+        validate: options.validate,
+    });
+    if (routesResult.isErr()) {
+        throw routesResult.error;
+    }
+    registerRoutes(hono, routesResult.value);
+    return hono;
+};
+const startServer = (hono, options) => {
+    const server = Bun.serve({
+        fetch: hono.fetch,
+        hostname: options.hostname ?? '0.0.0.0',
+        port: options.port ?? 3000,
+    });
+    return {
+        close: async () => {
+            await server.stop(true);
+        },
+        url: String(server.url),
+    };
+};
+// ---------------------------------------------------------------------------
+// surface
+// ---------------------------------------------------------------------------
+/**
+ * Build a Hono app from a topo and start serving it with Bun.
+ */
+export const surface = async (app, options = {}) => {
+    if (options.serve === false) {
+        throw new Error('surface() always serves the HTTP app; use createApp(graph) for an unserved Hono app');
+    }
+    // oxlint-disable-next-line require-await -- async ensures createApp() throws become rejected promises, not uncaught exceptions
+    const hono = createApp(app, options);
+    return startServer(hono, options);
+};
+// ---------------------------------------------------------------------------
+// trailhead
+// ---------------------------------------------------------------------------
+/**
+ * Build HTTP routes from a topo, create a Hono app, and optionally start serving.
+ *
+ * Topo validation runs before route construction — pass `validate: false`
+ * to skip it (e.g. during hot-reload or progressive startup).
+ */
+// oxlint-disable-next-line require-await -- async for consistency with other trailhead() entrypoints
+export const trailhead = async (app, options = {}) => {
+    const hono = createApp(app, options);
+    if (options.serve !== false) {
+        startServer(hono, options);
+    }
+    return hono;
+};
+//# sourceMappingURL=trailhead.js.map

package/dist/trailhead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailhead.js","sourceRoot":"","sources":["../src/trailhead.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@ontrails/hono",
+  "version": "1.0.0-beta.15",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^1.0.0-beta.14",
+    "hono": "^4.7.0"
+  },
+  "peerDependencies": {
+    "@ontrails/http": "^1.0.0-beta.14",
+    "zod": "^4.3.5"
+  }
+}

package/src/__tests__/surface.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result, trail, topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { createApp, surface } from '../surface.js';
+
+const echoTrail = trail('echo', {
+  blaze: (input) => Result.ok({ reply: input.message }),
+  input: z.object({ message: z.string() }),
+  intent: 'read',
+  output: z.object({ reply: z.string() }),
+});
+
+const tagsTrail = trail('tags', {
+  blaze: (input) => Result.ok({ tags: input.tags }),
+  input: z.object({ tags: z.array(z.string()) }),
+  intent: 'read',
+  output: z.object({ tags: z.array(z.string()) }),
+});
+
+describe('surface API (Hono connector)', () => {
+  test('createApp materializes the Hono surface without serving', async () => {
+    const graph = topo('surface-api', { echoTrail });
+    const app = createApp(graph);
+
+    const response = await app.request('/echo?message=hello', {
+      method: 'GET',
+    });
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ data: { reply: 'hello' } });
+  });
+
+  test('surface starts a Bun server and returns a close handle', async () => {
+    const graph = topo('surface-api', { echoTrail });
+    const handle = await surface(graph, { port: 0 });
+
+    try {
+      const response = await fetch(new URL('/echo?message=hello', handle.url));
+      expect(response.status).toBe(200);
+      expect(await response.json()).toEqual({ data: { reply: 'hello' } });
+    } finally {
+      await handle.close();
+    }
+  });
+
+  test('repeated query keys arrive as arrays for GET routes', async () => {
+    const graph = topo('surface-api', { tagsTrail });
+    const app = createApp(graph);
+
+    const response = await app.request('/tags?tags=red&tags=blue', {
+      method: 'GET',
+    });
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      data: { tags: ['red', 'blue'] },
+    });
+  });
+
+  test('single query values stay scalar even when the schema expects an array', async () => {
+    const graph = topo('surface-api', { tagsTrail });
+    const app = createApp(graph);
+
+    const response = await app.request('/tags?tags=solo', {
+      method: 'GET',
+    });
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toMatchObject({
+      error: {
+        category: 'validation',
+      },
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  createApp,
+  surface,
+  type CreateAppOptions,
+  type SurfaceHttpResult,
+} from './surface.js';

package/src/surface.ts

@@ -0,0 +1,324 @@
+/**
+ * Hono connector for Trails HTTP routes.
+ *
+ * Takes framework-agnostic HttpRouteDefinition[] and wires them into a
+ * Hono application, handling request parsing, response mapping, and errors.
+ *
+ * ```ts
+ * const graph = topo("myapp", entity);
+ * await surface(graph, { port: 3000 });
+ * ```
+ */
+
+import { isTrailsError, mapTransportError } from '@ontrails/core';
+import type {
+  Intent,
+  Layer,
+  ResourceOverrideMap,
+  Topo,
+  TrailContextInit,
+} from '@ontrails/core';
+import { Hono } from 'hono';
+import type { Context as HonoContext } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import { deriveHttpRoutes } from '@ontrails/http';
+import type { HttpMethod, HttpRouteDefinition } from '@ontrails/http';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface CreateAppOptions {
+  readonly basePath?: string | undefined;
+  /** Config values for resources that declare a `config` schema, keyed by resource ID. */
+  readonly configValues?:
+    | Readonly<Record<string, Record<string, unknown>>>
+    | undefined;
+  readonly createContext?:
+    | (() => TrailContextInit | Promise<TrailContextInit>)
+    | undefined;
+  readonly exclude?: readonly string[] | undefined;
+  readonly hostname?: string | undefined;
+  readonly include?: readonly string[] | undefined;
+  readonly intent?: readonly Intent[] | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  readonly name?: string | undefined;
+  readonly port?: number | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
+  /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
+  readonly validate?: boolean | undefined;
+}
+
+export interface SurfaceHttpResult {
+  readonly close: () => Promise<void>;
+  readonly url: string;
+}
+
+// ---------------------------------------------------------------------------
+// Request parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse query params into a plain object, preserving scalar-vs-array shape.
+ *
+ * A single `?tag=one` stays a scalar string, while repeated keys like
+ * `?tag=one&tag=two` become arrays. Schema validation owns whether that shape
+ * is accepted; the connector does not coerce singleton values into arrays.
+ */
+const parseQueryParams = (c: HonoContext): Record<string, unknown> => {
+  const result: Record<string, unknown> = {};
+  const url = new URL(c.req.url);
+  const seenKeys = new Set<string>();
+
+  for (const key of url.searchParams.keys()) {
+    if (seenKeys.has(key)) {
+      continue;
+    }
+    seenKeys.add(key);
+    const all = url.searchParams.getAll(key);
+    result[key] = all.length > 1 ? all : all[0];
+  }
+
+  return result;
+};
+
+/** Sentinel indicating a JSON parse failure. */
+const JSON_PARSE_ERROR = Symbol('JSON_PARSE_ERROR');
+
+/** Return true when the request has no body content. */
+const isEmptyBody = (c: HonoContext): boolean => {
+  const contentLength = c.req.header('Content-Length');
+  if (contentLength !== undefined) {
+    return Number.parseInt(contentLength, 10) === 0;
+  }
+  // No Content-Length header — treat as empty when Content-Type is also absent.
+  return c.req.header('Content-Type') === undefined;
+};
+
+/** Read input from request based on input source. */
+const readInput = async (
+  c: HonoContext,
+  inputSource: 'query' | 'body'
+): Promise<unknown> => {
+  if (inputSource === 'query') {
+    return parseQueryParams(c);
+  }
+  if (isEmptyBody(c)) {
+    return {};
+  }
+  try {
+    return await c.req.json();
+  } catch {
+    return JSON_PARSE_ERROR;
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Response mapping
+// ---------------------------------------------------------------------------
+
+/** Map a TrailsError or generic Error to an HTTP error response. */
+const mapErrorResponse = (
+  error: Error
+): { body: Record<string, unknown>; status: ContentfulStatusCode } => {
+  if (isTrailsError(error)) {
+    return {
+      body: {
+        error: {
+          category: error.category,
+          code: error.name,
+          message: error.message,
+        },
+      },
+      status: mapTransportError('http', error) as ContentfulStatusCode,
+    };
+  }
+  return {
+    body: {
+      error: {
+        category: 'internal',
+        code: 'InternalError',
+        message: error.message,
+      },
+    },
+    status: 500,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+
+/** Map a Result to an HTTP response via Hono context. */
+const mapResultToResponse = (
+  result: { isOk(): boolean; value?: unknown; error?: Error },
+  c: HonoContext
+): Response => {
+  if (result.isOk()) {
+    return c.json({ data: result.value }, 200);
+  }
+  const { body, status } = mapErrorResponse(
+    result.error ?? new Error('Unknown error')
+  );
+  return c.json(body, status);
+};
+
+/** Convert a caught unknown value to an error response. */
+const handleCaughtError = (error: unknown, c: HonoContext): Response => {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const { body, status } = mapErrorResponse(err);
+  return c.json(body, status);
+};
+
+/** Create a Hono handler from a route definition. */
+const createHonoHandler =
+  (route: HttpRouteDefinition) =>
+  async (c: HonoContext): Promise<Response> => {
+    const rawInput = await readInput(c, route.inputSource);
+
+    if (rawInput === JSON_PARSE_ERROR) {
+      return c.json(
+        {
+          error: {
+            category: 'validation',
+            code: 'ValidationError',
+            message: 'Invalid JSON in request body',
+          },
+        },
+        400
+      );
+    }
+
+    const requestId = c.req.header('X-Request-ID') ?? undefined;
+    const { signal: abortSignal } = c.req.raw;
+
+    try {
+      const result = await route.execute(rawInput, requestId, abortSignal);
+      return mapResultToResponse(result, c);
+    } catch (error: unknown) {
+      return handleCaughtError(error, c);
+    }
+  };
+
+/** Route registration keyed by HTTP method. */
+const routeRegistrars: Record<
+  HttpMethod,
+  (
+    hono: Hono,
+    path: string,
+    handler: (c: HonoContext) => Promise<Response>
+  ) => void
+> = {
+  DELETE: (hono, path, handler) => {
+    hono.delete(path, handler);
+  },
+  GET: (hono, path, handler) => {
+    hono.get(path, handler);
+  },
+  POST: (hono, path, handler) => {
+    hono.post(path, handler);
+  },
+};
+
+const registerRoutes = (hono: Hono, routes: HttpRouteDefinition[]): void => {
+  for (const route of routes) {
+    const handler = createHonoHandler(route);
+    routeRegistrars[route.method](hono, route.path, handler);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Global error handler
+// ---------------------------------------------------------------------------
+
+const registerErrorHandler = (hono: Hono): void => {
+  // oxlint-disable-next-line prefer-await-to-callbacks -- Hono's onError API requires a callback
+  hono.onError((err, c) =>
+    c.json(
+      {
+        error: {
+          category: 'internal',
+          code: 'InternalError',
+          message: err.message,
+        },
+      },
+      500
+    )
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// createApp
+// ---------------------------------------------------------------------------
+
+/**
+ * Build HTTP routes from a topo and register them on a Hono app.
+ */
+export const createApp = (
+  graph: Topo,
+  options: CreateAppOptions = {}
+): Hono => {
+  const hono = new Hono();
+
+  registerErrorHandler(hono);
+
+  const routesResult = deriveHttpRoutes(graph, {
+    basePath: options.basePath,
+    configValues: options.configValues,
+    createContext: options.createContext,
+    exclude: options.exclude,
+    include: options.include,
+    intent: options.intent,
+    layers: options.layers,
+    resources: options.resources,
+    validate: options.validate,
+  });
+
+  if (routesResult.isErr()) {
+    throw routesResult.error;
+  }
+
+  registerRoutes(hono, routesResult.value);
+  return hono;
+};
+
+const startServer = (
+  hono: Hono,
+  options: CreateAppOptions
+): SurfaceHttpResult => {
+  const server = Bun.serve({
+    fetch: hono.fetch,
+    hostname: options.hostname ?? '0.0.0.0',
+    port: options.port ?? 3000,
+  });
+
+  return {
+    close: async () => {
+      await server.stop(true);
+    },
+    url: String(server.url),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a Hono app from a topo and start serving it with Bun.
+ *
+ * @remarks Always starts a Bun server. Use `createApp(graph)` for an
+ * unserved Hono app that you can wire into your own server.
+ */
+export const surface = async (
+  graph: Topo,
+  options: CreateAppOptions = {}
+): Promise<SurfaceHttpResult> => {
+  // oxlint-disable-next-line require-await -- async ensures createApp() throws become rejected promises, not uncaught exceptions
+  const hono = createApp(graph, options);
+  return startServer(hono, options);
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
+}

package/tsconfig.tests.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.test.ts", "src/__tests__/**/*.ts"],
+  "exclude": []
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts","./src/surface.ts"],"version":"5.9.3"}