@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/http/app/createApp.js

@@ -0,0 +1,215 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { routeRegistry, } from "../../app/registry/routes.js";
+import { AUTH_META, getMetaTag, IDEMPOTENCY_META, PERMISSION_META, RATE_LIMIT_META, SCHEMA_META, } from "../utils/metaTags.js";
+import { registerHealthRoutes } from "./health.js";
+/**
+ * `Hono<AppEnv>` factory with route-method interception.
+ *
+ * Every `app.get/post/put/patch/delete` call is wrapped: the wrapper walks
+ * the passed handlers, reads any framework metadata tags, pushes a
+ * `RouteEntry` to the registry, then delegates to Hono's real method.
+ *
+ * User code looks identical to plain Hono — no `defineRoute` ceremony, no
+ * decorators, no codegen. The metadata is captured invisibly.
+ *
+ * Routes registered without `validate` / `requireAuth` are still captured —
+ * just schema-less / anonymous, which is *correct*: agents see exactly what's
+ * there, including unprotected endpoints (which the `ship-reviewer` agent
+ * can flag as convention violations).
+ */
+export function createApp(opts = {}) {
+    const registry = opts.registry ?? routeRegistry;
+    const app = new Hono();
+    if (opts.cors) {
+        validateCorsOptions(opts.cors);
+        const corsOpts = {
+            origin: opts.cors.origin,
+        };
+        if (opts.cors.allowMethods)
+            corsOpts.allowMethods = Array.from(opts.cors.allowMethods);
+        if (opts.cors.allowHeaders)
+            corsOpts.allowHeaders = Array.from(opts.cors.allowHeaders);
+        if (opts.cors.exposeHeaders)
+            corsOpts.exposeHeaders = Array.from(opts.cors.exposeHeaders);
+        if (opts.cors.maxAge !== undefined)
+            corsOpts.maxAge = opts.cors.maxAge;
+        if (opts.cors.credentials !== undefined)
+            corsOpts.credentials = opts.cors.credentials;
+        app.use("*", cors(corsOpts));
+    }
+    // Mounted before route interception (so they stay out of the route
+    // registry) and before any consumer middleware (Hono runs handlers in
+    // registration order and these respond without calling `next`).
+    if (opts.health !== false) {
+        registerHealthRoutes(app, opts.health ?? {});
+    }
+    interceptRouteMethods(app, registry);
+    return app;
+}
+/**
+ * `Hono<AppEnv>` factory for a **module sub-app** — the building block of the
+ * v4 mount-at-root composition.
+ *
+ * A module's `defineXxxRoutes(createModuleApp("xxx"), deps)` builds its own
+ * bounded route chain on a fresh app, which the consumer mounts onto the root
+ * with `root.route("/", buildXxxApp(deps))`. Splitting each module into its
+ * own sub-app (rather than chaining every module's routes onto one app) keeps
+ * each TypeScript route-type instantiation bounded, so the `hc()` typed client
+ * scales to many modules without `tsc` blowing its instantiation budget.
+ *
+ * Identical to `createApp` except:
+ *   - it wires **no CORS** and is not meant to be the server root (global
+ *     cross-cutting middleware — `cors`, `httpLogger`, `registerErrorHandlers`
+ *     — belong on the root app the sub-app is mounted onto, never here);
+ *   - every captured `RouteEntry` is stamped with `module`, lighting up the
+ *     Module column in `/dev/routes` and the `module` filter in `list_routes`;
+ *   - `app.onError`, `app.notFound`, and global `app.use("*", …)` are
+ *     **guarded** — they throw at dev time, because a sub-app error/not-found
+ *     handler silently shadows the root's uniform AppError shape and global
+ *     sub-app middleware breaks the root-wraps-everything ordering. (Per-route
+ *     middleware — `requireAuth`/`requirePermission`/`validate` passed as route
+ *     handlers — and **path-scoped** `app.use("/x/*", …)` are still allowed.)
+ *
+ * Because module sub-apps register their **absolute** paths (`/accounts`,
+ * `/accounts/:id`) and are mounted at the root (`route("/", …)`), the registry
+ * records the same absolute paths it always has — `execute_route`,
+ * `find_route_collisions`, and `/dev/routes` need no prefix math.
+ */
+export function createModuleApp(moduleName, opts = {}) {
+    const registry = opts.registry ?? routeRegistry;
+    const app = new Hono();
+    interceptRouteMethods(app, registry, moduleName);
+    guardCrossCuttingMethods(app, moduleName);
+    return app;
+}
+/**
+ * Make a module sub-app fail fast when a developer reaches for a cross-cutting
+ * concern that belongs on the root. `onError` / `notFound` / global `use("*")`
+ * all "work" on a sub-app but silently break the contract — a sub-app
+ * `onError` shadows `registerErrorHandlers`' uniform error shape, and global
+ * sub-app middleware doesn't wrap sibling modules. We throw at dev time so the
+ * mistake surfaces as a clear error, not a production surprise.
+ *
+ * Hono reads the stored `errorHandler` / `notFoundHandler` properties at
+ * request time (never the public methods), and `.route()` merges a sub-app's
+ * pre-built routes without calling these — so overriding the methods only
+ * intercepts the developer's call, never Hono's internals.
+ */
+function guardCrossCuttingMethods(app, moduleName) {
+    const reject = (method, why) => {
+        throw new Error(`createModuleApp("${moduleName}"): ${method} is not allowed on a module sub-app — ${why} ` +
+            `Put it on the root app you mount this sub-app onto (the one from ` +
+            `\`createApp(...)\`, mounted via \`root.route("/", build${capitalize(moduleName)}App(deps))\`), not here.`);
+    };
+    const methods = app;
+    methods.onError = () => reject("app.onError(...)", "a sub-app error handler silently shadows the root's uniform AppError JSON shape (registerErrorHandlers).");
+    methods.notFound = () => reject("app.notFound(...)", "a sub-app not-found handler shadows the root's 404 handling.");
+    const originalUse = app.use.bind(app);
+    methods.use = (...args) => {
+        // Global middleware = path-less (`use(mw)`) or wildcard (`use("*", mw)`).
+        // That's the cross-cutting footgun; path-scoped `use("/x/*", mw)` is fine.
+        const first = args[0];
+        if (typeof first !== "string" || first === "*") {
+            reject('app.use("*", ...)', "cross-cutting middleware (httpLogger/request-context, cors) must wrap every module from the root.");
+        }
+        return originalUse(...args);
+    };
+}
+function capitalize(s) {
+    return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1);
+}
+/**
+ * Wrap `app.get/post/put/patch/delete` so each registration pushes a
+ * `RouteEntry` to `registry` before delegating to Hono's real method. When
+ * `moduleName` is supplied (sub-apps via `createModuleApp`) the entry is
+ * tagged with it. User code looks like plain Hono — the capture is invisible.
+ */
+function interceptRouteMethods(app, registry, moduleName) {
+    const methods = [
+        { name: "get", verb: "GET" },
+        { name: "post", verb: "POST" },
+        { name: "put", verb: "PUT" },
+        { name: "patch", verb: "PATCH" },
+        { name: "delete", verb: "DELETE" },
+    ];
+    for (const { name, verb } of methods) {
+        const original = app[name].bind(app);
+        app[name] = (path, ...handlers) => {
+            const entry = buildRouteEntry(verb, path, handlers);
+            if (moduleName !== undefined)
+                entry.module = moduleName;
+            registry.add(entry);
+            // Hono's overloaded `app.METHOD` accepts varargs of MiddlewareHandler
+            // followed by the final handler. Forward as-is.
+            return original(path, ...handlers);
+        };
+    }
+}
+/**
+ * Reject the `origin: '*'` + `credentials: true` combo at construction
+ * time. This combination is invalid per the CORS spec — browsers
+ * refuse it — but the framework defends against it explicitly so a
+ * misconfigured deployment fails on boot rather than at runtime when
+ * a non-compliant HTTP client (or a tool that ignores the response
+ * `Access-Control-*` headers) reveals the bypass.
+ */
+function validateCorsOptions(opts) {
+    if (opts.credentials !== true)
+        return;
+    const origin = opts.origin;
+    if (origin === "*") {
+        throw new Error("createApp: cors.origin: '*' is incompatible with credentials: true. " +
+            "Pass an explicit allowlist (string[] of origins) instead.");
+    }
+    if (Array.isArray(origin) && origin.length === 1 && origin[0] === "*") {
+        throw new Error("createApp: cors.origin: ['*'] is incompatible with credentials: true. " +
+            "Pass an explicit allowlist (string[] of origins) instead.");
+    }
+    if (Array.isArray(origin) && origin.includes("*")) {
+        throw new Error("createApp: cors.origin contains '*' alongside other entries, which " +
+            "is ambiguous under credentials: true. Pass only explicit origins.");
+    }
+}
+function buildRouteEntry(method, path, handlers) {
+    const entry = {
+        method,
+        path,
+        auth: { required: false },
+        permissions: [],
+        schemas: {},
+    };
+    for (const handler of handlers) {
+        const schema = getMetaTag(handler, SCHEMA_META);
+        if (schema)
+            entry.schemas[schema.target] = schema.schema;
+        const auth = getMetaTag(handler, AUTH_META);
+        if (auth) {
+            entry.auth = {
+                required: auth.required,
+                provider: auth.providerName,
+            };
+        }
+        const permission = getMetaTag(handler, PERMISSION_META);
+        if (permission) {
+            // Multiple `requirePermission(...)` middlewares on one route → union.
+            for (const slug of permission.permissions) {
+                if (!entry.permissions.includes(slug))
+                    entry.permissions.push(slug);
+            }
+        }
+        const rateLimit = getMetaTag(handler, RATE_LIMIT_META);
+        if (rateLimit) {
+            entry.rateLimit = {
+                windowMs: rateLimit.windowMs,
+                max: rateLimit.max,
+                scope: rateLimit.scope,
+            };
+        }
+        const idempotency = getMetaTag(handler, IDEMPOTENCY_META);
+        if (idempotency)
+            entry.idempotent = true;
+    }
+    return entry;
+}
+//# sourceMappingURL=createApp.js.map

package/lib/http/app/createApp.js.map

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

package/lib/http/app/devRoutes.d.ts

@@ -0,0 +1,31 @@
+import type { Hono } from "hono";
+import { type RouteRegistry } from "../../app/registry/routes.js";
+/**
+ * `registerDevRoutes(app, opts?)` — mounts `/dev/routes` (HTML index) +
+ * `/dev/routes.json` (JSON dump) backed by the framework `RouteRegistry`.
+ *
+ * Recovers the human-discoverability we deliberately gave up by deferring
+ * Scalar `/docs` / OpenAPI to v4.x. For internal devs joining the project
+ * mid-stream the HTML index is "what routes does this app actually serve,
+ * with what auth requirements, with what request schemas?" — answered
+ * from runtime data, never stale.
+ *
+ * **Production safety**: gated by `opts.enabled` (default true only when
+ * `WORKER_MODE === "local"` or `NODE_ENV` is `local` / `dev` / `development`).
+ * Pass `enabled: true` to force-enable in other environments — e.g.,
+ * staging behind an admin gateway. Production should NOT enable this; the
+ * registry data is purely useful, not authenticated.
+ */
+export interface RegisterDevRoutesOptions {
+    /** Override the default registry. */
+    registry?: RouteRegistry;
+    /**
+     * Force enable / disable. Default: enabled when `WORKER_MODE === "local"`
+     * or `NODE_ENV` is `local` / `dev` / `development`.
+     */
+    enabled?: boolean;
+    /** Mount path prefix. Default `""` (routes at `/dev/routes` + `/dev/routes.json`). */
+    prefix?: string;
+}
+export declare function registerDevRoutes(app: Hono, opts?: RegisterDevRoutesOptions): void;
+//# sourceMappingURL=devRoutes.d.ts.map

package/lib/http/app/devRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devRoutes.d.ts","sourceRoot":"","sources":["../../../src/http/app/devRoutes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,wBAAwB;IACvC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAwID,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,GAAE,wBAA6B,GAAG,IAAI,CAkBtF"}

package/lib/http/app/devRoutes.js

@@ -0,0 +1,145 @@
+import { routeRegistry as defaultRegistry, } from "../../app/registry/routes.js";
+function isDevEnvByDefault() {
+    if (process.env.WORKER_MODE === "local")
+        return true;
+    const env = process.env.NODE_ENV ?? "";
+    return env === "local" || env === "dev" || env === "development";
+}
+const STYLE = `
+* { box-sizing: border-box; }
+body { font: 14px/1.5 ui-sans-serif, system-ui, sans-serif; margin: 24px; color: #111; }
+h1 { font-size: 18px; margin: 0 0 16px; }
+table { width: 100%; border-collapse: collapse; font-size: 13px; }
+th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid #e5e5e5; vertical-align: top; }
+th { background: #f7f7f7; font-weight: 600; }
+tr:hover { background: #fafafa; }
+.method { display: inline-block; padding: 2px 6px; border-radius: 3px; font-weight: 600; font-size: 11px; color: #fff; }
+.m-GET { background: #2962ff; }
+.m-POST { background: #00897b; }
+.m-PUT { background: #ef6c00; }
+.m-PATCH { background: #6a1b9a; }
+.m-DELETE { background: #c62828; }
+.m-WS { background: #455a64; }
+.m-OPTIONS, .m-HEAD { background: #757575; }
+.path { font-family: ui-monospace, "SF Mono", Menlo, monospace; }
+.tag { display: inline-block; padding: 1px 6px; margin-right: 4px; border-radius: 3px; background: #eef; color: #335; font-size: 11px; }
+.deprecated { opacity: 0.55; }
+.muted { color: #888; }
+.empty { padding: 24px; text-align: center; color: #888; }
+small.summary { color: #555; }
+`;
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function methodClass(method) {
+    return `m-${escapeHtml(method)}`;
+}
+function renderEntry(entry) {
+    const method = `<span class="method ${methodClass(entry.method)}">${escapeHtml(entry.method)}</span>`;
+    const path = `<span class="path">${escapeHtml(entry.path)}</span>`;
+    const module = entry.module ? escapeHtml(entry.module) : `<span class="muted">—</span>`;
+    const auth = entry.auth.required
+        ? `<strong>required</strong>${entry.auth.provider ? ` <span class="muted">(${escapeHtml(entry.auth.provider)})</span>` : ""}`
+        : `<span class="muted">none</span>`;
+    const permissions = entry.permissions.length === 0
+        ? `<span class="muted">—</span>`
+        : entry.permissions.map((p) => `<span class="tag">${escapeHtml(p)}</span>`).join("");
+    const schemas = Object.keys(entry.schemas)
+        .filter((k) => Boolean(entry.schemas[k]))
+        .map((k) => `<span class="tag">${escapeHtml(k)}</span>`)
+        .join("");
+    const policy = [];
+    if (entry.rateLimit) {
+        policy.push(`<span class="tag">rate-limit ${entry.rateLimit.max}/${Math.round(entry.rateLimit.windowMs / 1000)}s</span>`);
+    }
+    if (entry.idempotent)
+        policy.push(`<span class="tag">idempotent</span>`);
+    if (entry.deprecated)
+        policy.push(`<span class="tag" style="background:#fdd;color:#900">deprecated</span>`);
+    const rowClass = entry.deprecated ? "deprecated" : "";
+    return `<tr class="${rowClass}">
+    <td>${method}</td>
+    <td>${path}</td>
+    <td>${module}</td>
+    <td>${auth}</td>
+    <td>${permissions || `<span class="muted">—</span>`}</td>
+    <td>${schemas || `<span class="muted">—</span>`}</td>
+    <td>${policy.join(" ") || `<span class="muted">—</span>`}</td>
+  </tr>`;
+}
+function renderHtml(entries) {
+    const summary = `${entries.length} route${entries.length === 1 ? "" : "s"} registered`;
+    const rows = entries.length === 0
+        ? `<tr><td colspan="7" class="empty">No routes registered yet.</td></tr>`
+        : entries.map(renderEntry).join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>ShipAPI · /dev/routes</title>
+  <style>${STYLE}</style>
+</head>
+<body>
+  <h1>Routes <small class="summary">— ${summary}</small></h1>
+  <table>
+    <thead>
+      <tr>
+        <th>Method</th><th>Path</th><th>Module</th><th>Auth</th>
+        <th>Permissions</th><th>Schemas</th><th>Policy</th>
+      </tr>
+    </thead>
+    <tbody>${rows}</tbody>
+  </table>
+</body>
+</html>`;
+}
+/**
+ * Convert Zod schemas to JSON Schema for the JSON dump so external tooling
+ * (the MCP server, generated SDKs, dev-time debug consumers) can introspect
+ * request shapes without a Zod runtime. Uses Zod v4's native
+ * `z.toJSONSchema()` (the older `zod-to-json-schema` package doesn't
+ * understand Zod v4's internal schema shape). Failed conversions degrade
+ * to a presence flag so a malformed schema doesn't break the whole route.
+ */
+async function serializeSchemasForJson(entries) {
+    const { z } = await import("zod");
+    return entries.map((e) => {
+        const out = {};
+        for (const [key, schema] of Object.entries(e.schemas)) {
+            if (!schema)
+                continue;
+            try {
+                out[key] = z.toJSONSchema(schema);
+            }
+            catch {
+                // Schema couldn't be serialized (unsupported types, recursion);
+                // surface as a presence flag so consumers know it exists.
+                out[key] = { _present: true };
+            }
+        }
+        return { ...e, schemas: out };
+    });
+}
+export function registerDevRoutes(app, opts = {}) {
+    const enabled = opts.enabled ?? isDevEnvByDefault();
+    if (!enabled)
+        return; // intentionally a no-op so production deploys don't expose the route table
+    const registry = opts.registry ?? defaultRegistry;
+    const prefix = opts.prefix ?? "";
+    app.get(`${prefix}/dev/routes`, (c) => {
+        const entries = registry.list();
+        const html = renderHtml(entries);
+        return c.html(html);
+    });
+    app.get(`${prefix}/dev/routes.json`, async (c) => {
+        const entries = registry.list();
+        const routes = await serializeSchemasForJson(entries);
+        return c.json({ ok: true, count: entries.length, routes });
+    });
+}
+//# sourceMappingURL=devRoutes.js.map

package/lib/http/app/devRoutes.js.map

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

package/lib/http/app/errors.d.ts

@@ -0,0 +1,45 @@
+import type { Env, Hono } from "hono";
+import { logger as defaultLogger } from "../../observability/logger.js";
+/**
+ * `registerErrorHandlers(app, opts?)` — wires `app.onError` and `app.notFound`
+ * so AppError throws from anywhere in the request chain produce a consistent
+ * JSON shape. Replaces v3's `ErrorHandlerMiddleware`.
+ *
+ * Response shape (matches v3 for transition compat):
+ *   {
+ *     success: false,
+ *     error: { code, message, details? },
+ *     stack?: string, // development only
+ *     name?: string,  // development only
+ *   }
+ *
+ * - `AppError` subclasses → status from `error.statusCode`, `code` from
+ *   `error.code`. `ValidationError.details` flows through.
+ * - `HTTPException` (Hono native) → its status + a generic "HTTP_<status>"
+ *   code; lets framework code throw `HTTPException` without having to
+ *   wrap in AppError.
+ * - Anything else → 500 with `INTERNAL_SERVER_ERROR`. The original message
+ *   is logged but NOT exposed (avoid leaking internals to clients).
+ *
+ * 404s are routed through `app.notFound`, which throws a `NotFoundError`
+ * so the same handler shape applies.
+ */
+export interface ErrorResponseShape {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    stack?: string;
+    name?: string;
+}
+export interface RegisterErrorHandlersOptions {
+    /** Override the framework default pino logger. */
+    logger?: typeof defaultLogger;
+    /** Force dev-mode debug fields (`stack`, `name`) in responses. Default
+     *  is `process.env.NODE_ENV === "development"`. */
+    exposeStack?: boolean;
+}
+export declare function registerErrorHandlers<E extends Env>(app: Hono<E>, opts?: RegisterErrorHandlersOptions): void;
+//# sourceMappingURL=errors.d.ts.map

package/lib/http/app/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/http/app/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAGtC,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAKxE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,4BAA4B;IAC3C,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,aAAa,CAAC;IAC9B;uDACmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA4BD,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,GAAG,EACjD,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,IAAI,GAAE,4BAAiC,GACtC,IAAI,CAqEN"}

package/lib/http/app/errors.js

@@ -0,0 +1,93 @@
+import { HTTPException } from "hono/http-exception";
+import { logger as defaultLogger } from "../../observability/logger.js";
+import { AppError } from "../errors/AppError.js";
+import { NotFoundError } from "../errors/NotFoundError.js";
+import { ValidationError } from "../errors/ValidationError.js";
+function isDevelopment() {
+    return process.env.NODE_ENV === "development";
+}
+function buildResponse(err, exposeStack) {
+    const body = {
+        success: false,
+        error: {
+            code: err.code,
+            message: err.message,
+        },
+    };
+    if (err instanceof ValidationError && err.details !== undefined) {
+        body.error.details = err.details;
+    }
+    if (exposeStack) {
+        body.stack = err.stack;
+        body.name = err.name;
+    }
+    return body;
+}
+// Generic over the `Hono<E>` Env so consumers can pass a typed app
+// (e.g. `Hono<AppEnv>`) without a cast. The error-handler logic only
+// reads from `c.req` and `c.error` — nothing that depends on a
+// specific Env shape — so widening the parameter is safe.
+export function registerErrorHandlers(app, opts = {}) {
+    const log = opts.logger ?? defaultLogger;
+    const exposeStack = opts.exposeStack ?? isDevelopment();
+    app.notFound((c) => {
+        const path = c.req.path;
+        const method = c.req.method;
+        const err = new NotFoundError(`Route ${method} ${path} not found`);
+        const body = buildResponse(err, exposeStack);
+        return c.json(body, err.statusCode);
+    });
+    app.onError((err, c) => {
+        if (err instanceof AppError) {
+            // Operational errors are expected — log at warn (4xx) or error (5xx).
+            const fields = {
+                method: c.req.method,
+                path: c.req.path,
+                status: err.statusCode,
+                code: err.code,
+                err,
+            };
+            if (err.statusCode >= 500)
+                log.error(fields, "http.error");
+            else
+                log.warn(fields, "http.error");
+            const body = buildResponse(err, exposeStack);
+            return c.json(body, err.statusCode);
+        }
+        if (err instanceof HTTPException) {
+            // Hono native — thrown by router (e.g., `c.throw(403)`).
+            const body = {
+                success: false,
+                error: {
+                    code: `HTTP_${err.status}`,
+                    message: err.message || `HTTP ${err.status}`,
+                },
+            };
+            if (exposeStack) {
+                body.stack = err.stack;
+                body.name = err.name;
+            }
+            log.warn({ method: c.req.method, path: c.req.path, status: err.status }, "http.error");
+            return c.json(body, err.status);
+        }
+        // Unknown error — log full details, return safe 500 to client.
+        log.error({
+            method: c.req.method,
+            path: c.req.path,
+            err,
+        }, "http.error.unhandled");
+        const body = {
+            success: false,
+            error: {
+                code: "INTERNAL_SERVER_ERROR",
+                message: "An unexpected error occurred",
+            },
+        };
+        if (exposeStack && err instanceof Error) {
+            body.stack = err.stack;
+            body.name = err.name;
+        }
+        return c.json(body, 500);
+    });
+}
+//# sourceMappingURL=errors.js.map

package/lib/http/app/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/http/app/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AA8C/D,SAAS,aAAa;IACpB,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa,CAAC;AAChD,CAAC;AAED,SAAS,aAAa,CAAC,GAAa,EAAE,WAAoB;IACxD,MAAM,IAAI,GAAuB;QAC/B,OAAO,EAAE,KAAK;QACd,KAAK,EAAE;YACL,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,OAAO;SACrB;KACF,CAAC;IACF,IAAI,GAAG,YAAY,eAAe,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IACnC,CAAC;IACD,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACvB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mEAAmE;AACnE,qEAAqE;AACrE,+DAA+D;AAC/D,0DAA0D;AAC1D,MAAM,UAAU,qBAAqB,CACnC,GAAY,EACZ,OAAqC,EAAE;IAEvC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,aAAa,CAAC;IACzC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,aAAa,EAAE,CAAC;IAExD,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE;QACjB,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;QACxB,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;QAC5B,MAAM,GAAG,GAAG,IAAI,aAAa,CAAC,SAAS,MAAM,IAAI,IAAI,YAAY,CAAC,CAAC;QACnE,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QAC7C,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,UAAkC,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACrB,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,sEAAsE;YACtE,MAAM,MAAM,GAAG;gBACb,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM;gBACpB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI;gBAChB,MAAM,EAAE,GAAG,CAAC,UAAU;gBACtB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,GAAG;aACJ,CAAC;YACF,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG;gBAAE,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;;gBACtD,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YAEpC,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;YAC7C,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,UAAkC,CAAC,CAAC;QAC9D,CAAC;QAED,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;YACjC,yDAAyD;YACzD,MAAM,IAAI,GAAuB;gBAC/B,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ,GAAG,CAAC,MAAM,EAAE;oBAC1B,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,QAAQ,GAAG,CAAC,MAAM,EAAE;iBAC7C;aACF,CAAC;YACF,IAAI,WAAW,EAAE,CAAC;gBAChB,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;gBACvB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YACvB,CAAC;YACD,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC,CAAC;YACvF,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAED,+DAA+D;QAC/D,GAAG,CAAC,KAAK,CACP;YACE,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM;YACpB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI;YAChB,GAAG;SACJ,EACD,sBAAsB,CACvB,CAAC;QAEF,MAAM,IAAI,GAAuB;YAC/B,OAAO,EAAE,KAAK;YACd,KAAK,EAAE;gBACL,IAAI,EAAE,uBAAuB;gBAC7B,OAAO,EAAE,8BAA8B;aACxC;SACF,CAAC;QACF,IAAI,WAAW,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;YACxC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;YACvB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACvB,CAAC;QACD,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/lib/http/app/health.d.ts

@@ -0,0 +1,66 @@
+import type { Hono } from "hono";
+import { type HealthCheckRegistry } from "../../app/health/HealthCheck.js";
+/**
+ * `registerHealthRoutes(app, opts?)` — wires `/livez` and `/readyz`.
+ *
+ * `createApp()` calls this for you (opt out with `createApp({ health: false })`),
+ * so most apps never call it directly. Calling it on an app that already has
+ * the routes mounts nothing (see below).
+ *
+ * - `GET /livez` always 200 with `{ ok: true }`. Process up. Used by the
+ *   orchestrator's restart trigger.
+ * - `GET /readyz` runs every check in the registry. 200 with
+ *   `{ ok: true, checks: [{ name, ok, latencyMs }] }` when all pass; 503 with
+ *   the same shape (and `ok: false` plus a generic per-check `error` of
+ *   `"timeout"` or `"unavailable"`) when any fail. The raw error never reaches
+ *   the response body — the endpoint is unauthenticated and database errors
+ *   can name hosts and users. Failures are logged server-side at warn level
+ *   with the check name, the `error` string a check returned (as `reason`,
+ *   truncated), and for a thrown error its `code` / `name` / `syscall` only.
+ *
+ * There is deliberately no `/healthz`: Google Cloud Run's front end intercepts
+ * that path and it never reaches the container.
+ *
+ * Replaces v3's `InitHealthCheckRoute` + `InitWarmupCheckRoute`. The
+ * dual-endpoint pattern is the Kubernetes / GCP / Fly convention.
+ */
+export interface RegisterHealthRoutesOptions {
+    /**
+     * Registry to query. Defaults to the framework-wide singleton — modules
+     * register their checks against it via `healthCheckRegistry.add(...)`.
+     */
+    registry?: HealthCheckRegistry;
+    /** Override the per-check timeout used by `/readyz`. Default 3_000 ms. */
+    readyzTimeoutMs?: number;
+    /** Mount path prefix. Default `""` (routes mount at `/livez` + `/readyz`). */
+    prefix?: string;
+}
+/** One entry of the public `/readyz` body. */
+export interface ReadyzCheck {
+    name: string;
+    ok: boolean;
+    latencyMs: number;
+    /** Present only when `ok` is false. Never the raw error text. */
+    error?: "timeout" | "unavailable";
+}
+export interface ReadyzBody {
+    ok: boolean;
+    checks: ReadyzCheck[];
+}
+/** Whether `/livez` + `/readyz` are already mounted on this app instance. */
+export declare function hasHealthRoutes(app: object): boolean;
+/**
+ * Mount `/livez` + `/readyz` on `app`, once per app instance.
+ *
+ * On an app that already has them (every `createApp()` app unless it passed
+ * `health: false`), this never mounts a second copy and never throws. A
+ * `registry` or `readyzTimeoutMs` passed to the later call is applied to the
+ * routes already mounted, so an app that wires its own registry this way keeps
+ * the readiness checks it had before `createApp` mounted the routes. That late
+ * configuration is deprecated: it logs a warning once per app, and will be
+ * removed in the next major version — pass it to `createApp({ health })`. A
+ * different `prefix` cannot be honoured without mounting again; it is ignored
+ * with a warning (configure it with `createApp({ health: { prefix } })`).
+ */
+export declare function registerHealthRoutes(app: Hono, opts?: RegisterHealthRoutesOptions): void;
+//# sourceMappingURL=health.d.ts.map

package/lib/http/app/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/http/app/health.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,iCAAiC,CAAC;AAOzC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,KAAK,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAcD,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,GAAE,2BAAgC,GAAG,IAAI,CA4C5F"}