typespec-hono 0.1.0

package/dist/src/base-path.js

@@ -0,0 +1,47 @@
+import { getServers } from "@typespec/http";
+/**
+ * The path prefix the DOCUMENT says this service is served under.
+ *
+ * ⚠️ **Without this the two artefacts from one spec disagree, which is the thing this project exists
+ * to prevent.** `@server("/api/v1")` reaches OpenAPI as `servers: [{ url: "/api/v1" }]`, and an
+ * OpenAPI path is relative to its server — so the document says `/api/v1/accounts` while the
+ * generated router answered `/accounts`. Measured: every client generated from the document, and
+ * every "try it" button in a rendered document, 404s.
+ *
+ * ⚠️ **A prefix is only taken where the document is unambiguous about it.** Guessing wrong is worse
+ * than not applying one: a route mounted under the wrong prefix still matches, still answers, and
+ * answers the wrong URL.
+ */
+/** The static path of a server URL, or `undefined` when it has none this can rely on. */
+function pathOf(server) {
+    const url = server.url;
+    /**
+     * ⚠️ **A templated URL is not a mismatch and must not warn.** `@server("{endpoint}")` — which most
+     * of `@typespec/http-specs` uses — means the whole origin is supplied by the caller, so the paths
+     * the document publishes are already relative to whatever they choose. Mounting at the root is
+     * correct there, and warning would raise noise on the majority of real specs.
+     */
+    if (url.includes("{"))
+        return undefined;
+    // An absolute URL carries a host; only its path is a prefix.
+    const path = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? (URL.parse(url)?.pathname ?? "/") : url;
+    const trimmed = path.replace(/\/+$/, "");
+    return trimmed === "" || trimmed === "/" ? undefined : trimmed;
+}
+/**
+ * Read the service's declared servers and decide what to mount under.
+ *
+ * - no `@server`, or a templated one → the root, which is what the document means;
+ * - one static path, or several that agree → that path;
+ * - several that DISAGREE → the root, and the caller reports it. There is no answer that serves all
+ *   of them, and picking one would silently serve the wrong URLs for the others.
+ */
+export function resolveBasePath(program, namespace) {
+    const servers = getServers(program, namespace) ?? [];
+    const paths = [...new Set(servers.map(pathOf).filter((path) => path !== undefined))];
+    if (paths.length === 0)
+        return { basePath: undefined, ambiguous: [] };
+    if (paths.length === 1)
+        return { basePath: paths[0], ambiguous: [] };
+    return { basePath: undefined, ambiguous: paths.toSorted() };
+}

package/dist/src/emitter.d.ts

@@ -0,0 +1,24 @@
+import { type EmitContext } from "@typespec/compiler";
+/**
+ * What the generated files import their runtime contract from when the consumer sets nothing.
+ *
+ * ⚠️ **THIS package's runtime, not the library's, and the distinction is the whole of a defect that
+ * shipped.** `app.gen.ts` names `AppEnv`, `Awaitable`, `Ctx`, `Result`, `RouteDeps` and
+ * `selectContentType`; every one of them is declared in `src/runtime.ts` here. The library's runtime
+ * exports `ResponseArm` and `armFor` and nothing else — and it is a TRANSITIVE dependency of a
+ * consumer of this package, so under a strict `node_modules` its specifier does not resolve from
+ * consumer code at all.
+ *
+ * Pointing at `typespec-hono/runtime` fixes both halves at once, because this module RE-EXPORTS
+ * `ResponseArm` and `armFor` (see `runtime.ts`) — which is what `schemas.gen.ts` imports. One
+ * specifier, present in the consumer's own dependency, carrying every name both generated files
+ * reference.
+ *
+ * ⚠️ **Measured in a fresh project installed from `pnpm pack` tarballs, because no test could see it:**
+ * every compile in both harnesses sets `runtime-module` explicitly, so the default branch was ungraded
+ * across 240 tests. `tsp compile` succeeded with zero diagnostics and `tsc` then reported two
+ * `TS2307`s — `Cannot find module 'typespec-http-zod/runtime'` — one in each generated file.
+ * `test/adopter.test.ts` is the arm that now opens that branch.
+ */
+export declare const DEFAULT_RUNTIME_MODULE = "typespec-hono/runtime";
+export declare function $onEmit(context: EmitContext): Promise<void>;

package/dist/src/emitter.js

@@ -0,0 +1,108 @@
+import { emitFile, resolvePath } from "@typespec/compiler";
+import { emitHttpZod } from "typespec-http-zod";
+import { renderApp } from "./app.js";
+import { resolveBasePath } from "./base-path.js";
+import { securityFor } from "./security.js";
+import { reportDiagnostic } from "./lib.js";
+/**
+ * This emitter's entry point — **the whole of `typespec-http-zod`, plus one file**.
+ *
+ * ⚠️ **A consumer lists ONE emitter, and this is why.** The validators and the server share a naming
+ * contract: `app.gen.ts` imports `readWidgetPath` and `readWidgetResponses` from `schemas.gen.js` by
+ * name. Two separate TypeSpec emitters would each get their own `$onEmit` and their own registry, and
+ * would have to arrive at identical identifiers by coincidence. Running the library here means it
+ * mints the names, writes them, and hands them back — so agreement is structural rather than hoped
+ * for.
+ *
+ * ⚠️ **It uses nothing `typespec-http-zod` does not export.** The package's `exports` map makes a deep
+ * import impossible, so this file is the proof that the published API is sufficient to build a server
+ * generator on. Anything it cannot do from here is a gap in that API, to be fixed there.
+ */
+/**
+ * The HTTP operation an emitted route came from, keyed on verb and path.
+ *
+ * ⚠️ **Keyed on the ROUTE, not on the name, and the name was wrong for every interface.**
+ * `EmittedRoute.operationId` is the id the document publishes — `Accounts_list`, with the interface
+ * prefix `resolveOperationId` inserts — while `operation.operation.name` is the bare `list`. Matching
+ * them never succeeded for an operation declared inside an `interface`, which is most of them.
+ *
+ * Two things rested on that lookup and both were silently wrong: every diagnostic pointed at the
+ * service namespace instead of the operation that caused it, and the security requirements resolved
+ * to none, so a scheme-gated route emitted no gate. Verb and path identify a route exactly, and are
+ * what both sides already agree on.
+ */
+function operationFor(emitted, verb, path) {
+    return emitted.service.operations.find((candidate) => candidate.verb.toUpperCase() === verb.toUpperCase() && candidate.path === path);
+}
+/** The declaration a diagnostic should point at, falling back to the service when it cannot be found. */
+function targetFor(emitted, verb, path) {
+    return operationFor(emitted, verb, path)?.operation ?? emitted.service.namespace;
+}
+/**
+ * What the generated files import their runtime contract from when the consumer sets nothing.
+ *
+ * ⚠️ **THIS package's runtime, not the library's, and the distinction is the whole of a defect that
+ * shipped.** `app.gen.ts` names `AppEnv`, `Awaitable`, `Ctx`, `Result`, `RouteDeps` and
+ * `selectContentType`; every one of them is declared in `src/runtime.ts` here. The library's runtime
+ * exports `ResponseArm` and `armFor` and nothing else — and it is a TRANSITIVE dependency of a
+ * consumer of this package, so under a strict `node_modules` its specifier does not resolve from
+ * consumer code at all.
+ *
+ * Pointing at `typespec-hono/runtime` fixes both halves at once, because this module RE-EXPORTS
+ * `ResponseArm` and `armFor` (see `runtime.ts`) — which is what `schemas.gen.ts` imports. One
+ * specifier, present in the consumer's own dependency, carrying every name both generated files
+ * reference.
+ *
+ * ⚠️ **Measured in a fresh project installed from `pnpm pack` tarballs, because no test could see it:**
+ * every compile in both harnesses sets `runtime-module` explicitly, so the default branch was ungraded
+ * across 240 tests. `tsp compile` succeeded with zero diagnostics and `tsc` then reported two
+ * `TS2307`s — `Cannot find module 'typespec-http-zod/runtime'` — one in each generated file.
+ * `test/adopter.test.ts` is the arm that now opens that branch.
+ */
+export const DEFAULT_RUNTIME_MODULE = "typespec-hono/runtime";
+export async function $onEmit(context) {
+    for (const emitted of await emitHttpZod(context, {
+        defaultRuntimeModule: DEFAULT_RUNTIME_MODULE,
+    })) {
+        /**
+         * ⚠️ **The path the DOCUMENT says this service is served under.** An OpenAPI path is relative to
+         * its server, so `@server("/api/v1")` plus `/accounts` publishes `/api/v1/accounts`. Mounting at
+         * the root made every client generated from the document 404.
+         */
+        const base = resolveBasePath(context.program, emitted.service.namespace);
+        if (base.ambiguous.length > 0) {
+            reportDiagnostic(context.program, {
+                code: "ambiguous-server-path",
+                format: { paths: base.ambiguous.join(", ") },
+                target: emitted.service.namespace,
+            });
+        }
+        await emitFile(context.program, {
+            path: resolvePath(emitted.outputDir, "app.gen.ts"),
+            content: renderApp(emitted, {
+                /**
+                 * Reported rather than thrown, so a spec with one unmountable path still names every
+                 * other problem in the same compile — and so the validators for the rest of the service
+                 * are still written. A path this router cannot express is not a reason to emit nothing.
+                 */
+                unsupportedPathTemplate: (route, template, name) => {
+                    reportDiagnostic(context.program, {
+                        code: "unsupported-path-template",
+                        format: { template, name },
+                        target: targetFor(emitted, route.verb, route.path),
+                    });
+                },
+                unroutableVerb: (route) => {
+                    reportDiagnostic(context.program, {
+                        code: "unroutable-verb",
+                        format: { operationId: route.operationId, verb: route.verb },
+                        target: targetFor(emitted, route.verb, route.path),
+                    });
+                },
+            }, base.basePath, (verb, path) => {
+                const operation = operationFor(emitted, verb, path);
+                return operation === undefined ? [] : securityFor(context.program, operation);
+            }),
+        });
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The package's entry point: what a consumer may use, and the emitter written against it.
+ *
+ * ⚠️ **`typespec-http-zod` is re-exported deliberately.** This emitter runs the whole of it, so a
+ * consumer of the generated server is already a consumer of those validators and their types. Making
+ * them reach for a second package to name a schema this one caused to exist would be an accident of
+ * packaging showing through.
+ */
+export * from "typespec-http-zod";
+export { $lib } from "./lib.js";
+export { $onEmit } from "./emitter.js";
+export { renderApp, toHonoPath } from "./app.js";

package/dist/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * The package's entry point: what a consumer may use, and the emitter written against it.
+ *
+ * ⚠️ **`typespec-http-zod` is re-exported deliberately.** This emitter runs the whole of it, so a
+ * consumer of the generated server is already a consumer of those validators and their types. Making
+ * them reach for a second package to name a schema this one caused to exist would be an accident of
+ * packaging showing through.
+ */
+export * from "typespec-http-zod";
+export { $lib } from "./lib.js";
+export { $onEmit } from "./emitter.js";
+export { renderApp, toHonoPath } from "./app.js";

package/dist/src/lib.d.ts

@@ -0,0 +1,71 @@
+import { type CallableMessage, type DiagnosticReport, type JSONSchemaType, type Program, type TypeSpecLibrary } from "@typespec/compiler";
+import { type EmitterOptions as HttpZodOptions } from "typespec-http-zod";
+/**
+ * The library definition, kept in its own module so `tsp-index.ts` and the emitter can both reach it
+ * without importing each other.
+ */
+/**
+ * Everything `typespec-http-zod` accepts, plus what a Hono server needs on top.
+ *
+ * ⚠️ **DERIVED, never restated, and the distinction is load-bearing.** This emitter runs the whole of
+ * `typespec-http-zod` and adds one file; every option that package accepts has to reach it. Written
+ * as a second literal list, an option added there would be rejected here as unknown — or worse,
+ * accepted and silently dropped, which produces output that is wrong in a way no test of either
+ * package would see. `test/options.test.ts` asserts the forwarding as a CLASS.
+ *
+ * There is currently nothing to add: `runtime-module` belongs to the library, because the library is
+ * what emits the annotated response arms that need it. This type exists as the seam rather than
+ * because it carries anything today — the moment a Hono-only option appears it goes here, and the
+ * derivation keeps the rest honest.
+ */
+export type EmitterOptions = HttpZodOptions;
+/**
+ * ⚠️ **A spread of the published schema, so a new key arrives for free.**
+ *
+ * `properties` is spread rather than re-listed for the same reason the type is aliased rather than
+ * re-declared. If this ever needs a Hono-only key, it is added to a spread of `httpZodOptions.properties`
+ * — never by copying the list.
+ */
+declare const EmitterOptionsSchema: JSONSchemaType<EmitterOptions>;
+/**
+ * ⚠️ **Spelled out rather than inferred, and every type in it imported through THIS package's own
+ * specifier.** Both this package and `typespec-http-zod` declare `@typespec/compiler` as a peer, so a
+ * side-by-side checkout resolves two physically distinct copies of the identical version — measured,
+ * two `.pnpm` paths differing only in which repository they sit under. TypeScript then had a choice
+ * of which copy to name in the emitted declarations and chose the other package's, producing five
+ * `TS2883`s whose message is exactly the problem: *"this is likely not portable"*.
+ *
+ * A published `.d.ts` naming a `node_modules/.pnpm/...` path is broken for everyone who installed
+ * differently. Naming these through the direct import pins them to the specifier a consumer resolves,
+ * whatever their tree looks like.
+ *
+ * ⚠️ **A consumer never hits this**, because a peer dependency is installed once and both packages
+ * share it. That is precisely why it is worth guarding against here rather than trusting: the failure
+ * exists only in the arrangement that BUILDS the package, and would ship silently.
+ */
+type Diagnostics = {
+    "unroutable-verb": {
+        readonly default: CallableMessage<["operationId", "verb"]>;
+    };
+    "unsupported-path-template": {
+        readonly default: CallableMessage<["template", "name"]>;
+    };
+    "ambiguous-server-path": {
+        readonly default: CallableMessage<["paths"]>;
+    };
+};
+/**
+ * ⚠️ **Annotated rather than inferred, and the reason is a packaging fact rather than a style
+ * preference.** This package and `typespec-http-zod` each resolve their own `@typespec/compiler` —
+ * that is what a peer dependency does, and a consumer installing both gets one copy while a
+ * side-by-side checkout gets two. Inferring the type here makes the emitted `.d.ts` name a compiler
+ * through a path that exists only in the tree it was built in: `TS2883`, five of them, and the
+ * message says it outright — *"this is likely not portable"*.
+ *
+ * A published declaration file that names a `node_modules/.pnpm/...` path is broken for everyone who
+ * installed differently. Naming the type explicitly is what makes the declaration stand on its own,
+ * and this is exactly the class of defect a package built inside one workspace never has to face.
+ */
+export declare const $lib: TypeSpecLibrary<Diagnostics, EmitterOptions>;
+export declare const reportDiagnostic: <C extends keyof Diagnostics, M extends keyof Diagnostics[C]>(program: Program, diagnostic: DiagnosticReport<Diagnostics, C, M>) => void;
+export { EmitterOptionsSchema };

package/dist/src/lib.js

@@ -0,0 +1,123 @@
+import { createTypeSpecLibrary, paramMessage, } from "@typespec/compiler";
+import { EmitterOptionsSchema as httpZodOptions, } from "typespec-http-zod";
+/**
+ * ⚠️ **A spread of the published schema, so a new key arrives for free.**
+ *
+ * `properties` is spread rather than re-listed for the same reason the type is aliased rather than
+ * re-declared. If this ever needs a Hono-only key, it is added to a spread of `httpZodOptions.properties`
+ * — never by copying the list.
+ */
+const EmitterOptionsSchema = {
+    ...httpZodOptions,
+    properties: { ...httpZodOptions.properties },
+};
+/**
+ * What this emitter refuses that the library does not.
+ *
+ * The library refuses what no OpenAPI document can state. Everything here is narrower: what no *Hono
+ * router* can mount. Two different questions, and keeping them in separate libraries is what stops a
+ * consumer who wants validators without a server inheriting a refusal about routing.
+ */
+const diagnostics = {
+    /**
+     * An operation on a verb Hono cannot dispatch to — in practice, `HEAD`.
+     *
+     * ⚠️ **Hono rewrites every HEAD request to GET BEFORE routing, unconditionally.** Read from its own
+     * source, `hono-base.js`:
+     *
+     * ```js
+     * if (method === "HEAD") {
+     *   return (async () => new Response(null, await this.#dispatch(request, executionCtx, env, "GET")))();
+     * }
+     * ```
+     *
+     * So a route registered under `HEAD` is categorically unreachable. Measured on Hono 4.13.1: with a
+     * HEAD route and no GET, a HEAD request answers **404**; with both, the GET handler answers and the
+     * HEAD handler is dead code. `on("PURGE", …)` and `on("OPTIONS", …)` both work, so this is HEAD
+     * specifically and not a limitation of `on`.
+     *
+     * ⚠️ **This emitter shipped exactly that dead code, and every route-counting arm called it mounted**
+     * — including a differential written specifically to catch unreachable routes, because `app.routes`
+     * lists a registration Hono will never dispatch to. Fifteen of the seventeen HEAD operations in
+     * `@typespec/http-specs` have no sibling GET, so they were 404s that counted as present.
+     *
+     * **Refused rather than compensated for.** The workarounds are worse: registering the handler under
+     * GET invents an operation the document does not declare, and guarding it on `c.req.method` is not
+     * something a Hono author would write. The remedy is in the spec, and the message says it.
+     *
+     * ⚠️ **Hono's own best-practices guide says the same thing outright**, which this refusal predates:
+     * *"Don't create dedicated `app.head()` handlers — they won't execute as HEAD requests are converted
+     * before route matching."* The rule was derived here by reading `hono-base.js` and measuring; finding
+     * it stated in the documentation afterwards is corroboration rather than the source.
+     *
+     * ⚠️ **A refusal about the TARGET FRAMEWORK, which is why it lives here.** `typespec-http-zod` emits
+     * correct validators for these operations; only a Hono server cannot route them.
+     */
+    "unroutable-verb": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' is declared on '${"verb"}', which Hono cannot dispatch to: it rewrites every HEAD request to GET before matching, so a route registered under HEAD is never reached — 404 where the path has no GET, and dead code where it has one. Declare the operation as '@get' instead; Hono answers HEAD from it automatically with the body stripped, which is what RFC 9110 requires.`,
+        },
+    },
+    /**
+     * The document declares several servers whose paths disagree, so there is no prefix to mount under.
+     *
+     * ⚠️ **Reported rather than resolved, because every resolution is wrong for somebody.** An OpenAPI
+     * path is relative to its server, so `@server("/api/v1")` plus `/accounts` means the document
+     * publishes `/api/v1/accounts`. Where one static path is declared this emitter mounts under it and
+     * the two artefacts agree. Where several disagree there is no single answer: picking one serves
+     * the wrong URL for every other, and a route mounted under a wrong prefix still matches and still
+     * answers, which is worse than one that fails.
+     *
+     * Routes are mounted at the root in this case, which is at least predictable, and this says so.
+     */
+    "ambiguous-server-path": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `The service declares servers with different base paths (${"paths"}), so routes are mounted at the root. An OpenAPI path is relative to its server, so callers following the document will prefix one of these — mount the returned app under the prefix you serve, or declare a single base path.`,
+        },
+    },
+    /**
+     * A path template this emitter will not translate into a route.
+     *
+     * ⚠️ **Refused rather than approximated, because the failure mode is a route that WORKS and is
+     * wrong.** Hono reads `:name` up to the next `/`, so an RFC 6570 modifier survives into the
+     * parameter name — `{id*}` becomes `:id*`, where `*` is Hono's own wildcard. That mounts a route
+     * which matches, answers, and binds the wrong thing, which is strictly worse than one that 404s.
+     *
+     * ⚠️ **The refusal lands HERE and not in the library, which is the whole point of the split.** The
+     * validators for such an operation are correct and are still emitted: what a request body must
+     * look like does not depend on whether some particular router can express the path. Only the
+     * server is impossible.
+     *
+     * Plain names are translated, including the hyphens and dots that `\w` used to drop on the floor —
+     * a parameter carrying a hyphen was left alone entirely, so `@path("thing-id")` produced the
+     * literal route `/things/{thing-id}`: mounted, counted by every arm that counted routes, and
+     * reachable by nobody.
+     */
+    "unsupported-path-template": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"template"}' is not a path template this emitter can mount: the parameter '${"name"}' is not a plain name. Hono reads a parameter up to the next '/', so an RFC 6570 operator or modifier would become part of the name — or, for '*', a wildcard — and the route would match the wrong requests rather than fail. Name the parameter with letters, digits, '_', '-', '.' or '~'.`,
+        },
+    },
+};
+/**
+ * ⚠️ **Annotated rather than inferred, and the reason is a packaging fact rather than a style
+ * preference.** This package and `typespec-http-zod` each resolve their own `@typespec/compiler` —
+ * that is what a peer dependency does, and a consumer installing both gets one copy while a
+ * side-by-side checkout gets two. Inferring the type here makes the emitted `.d.ts` name a compiler
+ * through a path that exists only in the tree it was built in: `TS2883`, five of them, and the
+ * message says it outright — *"this is likely not portable"*.
+ *
+ * A published declaration file that names a `node_modules/.pnpm/...` path is broken for everyone who
+ * installed differently. Naming the type explicitly is what makes the declaration stand on its own,
+ * and this is exactly the class of defect a package built inside one workspace never has to face.
+ */
+export const $lib = createTypeSpecLibrary({
+    name: "typespec-hono",
+    diagnostics,
+    emitter: { options: EmitterOptionsSchema },
+});
+export const reportDiagnostic = $lib.reportDiagnostic;
+export { EmitterOptionsSchema };

package/dist/src/runtime.d.ts

@@ -0,0 +1,174 @@
+import type { Context, Env, Input, MiddlewareHandler } from "hono";
+import type { ResponseArm } from "typespec-http-zod/runtime";
+/**
+ * ⚠️ **`ResponseArm` and `armFor` live in `typespec-http-zod` and are re-exported here.**
+ *
+ * The library is what emits the response arms — `schemas.gen.ts` declares them and annotates them
+ * with `satisfies readonly ResponseArm[]` — so the type belongs to the package that produces it, and
+ * the rule for reading an array containing `4XX` and `default` belongs beside it. A consumer serving
+ * those validators from Express needs both and should not depend on a Hono emitter to get them.
+ *
+ * Re-exported rather than merely available, so an application still has ONE runtime import and the
+ * `runtime-module` substitution keeps working unchanged: a module an app points that option at has to
+ * supply every name the generated files reference, and they reference these.
+ */
+export { armFor, type ResponseArm } from "typespec-http-zod/runtime";
+/**
+ * One acceptable combination of credentials, exactly as OpenAPI's `security` states it: scheme id to
+ * the scopes that scheme requires. Every entry in one requirement must be satisfied TOGETHER, and
+ * satisfying ANY ONE requirement authorises the caller.
+ *
+ * ⚠️ **Declared here rather than beside the code that derives it**, because `./runtime` is what a
+ * running server imports and must stay free of every build-time dependency — a packaging arm asserts
+ * it names no `@typespec/*` package at all. An application should not drag a compiler into its
+ * Worker to read one type.
+ */
+export type SecurityRequirement = Readonly<Record<string, readonly string[]>>;
+/**
+ * The contract between the GENERATED server and the app that mounts it.
+ *
+ * ⚠️ **This exists because "here is a data table, write your own router" is not a deliverable.**
+ * The emitter used to produce `GENERATED_ROUTES` — one array of plain objects — and every consumer
+ * had to hand-write a loop that interpreted it at run time. In this repository that loop is 220
+ * lines, it sits outside every oracle the emitter is judged by, and it carries a cast that exists
+ * *only* because iterating a homogeneous array throws away the per-operation types the emitter knew:
+ * `backend[operationId]` is a union of 104 differently-typed methods, so nothing about the call can
+ * be checked. Generating the server removes the loop, the cast, and the compensating type-level
+ * assertion invented to put the guarantee back.
+ *
+ * What is left for the app to supply is genuinely app-specific: how a request becomes a caller's
+ * context, and how a result becomes a response. Everything else — routing, validation, which
+ * validator applies to which target, what status each arm answers — is generated.
+ */
+/**
+ * How an operation's return value is wrapped.
+ *
+ * Identity by default, so an operation may simply return its value. An app with a result envelope
+ * points `runtime-module` at its own module and re-declares this as, say, `ServiceResult<T>` — which
+ * is what keeps the generated `Operations` interface concretely typed end to end instead of falling
+ * back to `unknown` and reintroducing the cast this whole change exists to delete.
+ */
+export type Result<T> = T;
+/**
+ * The Hono environment the generated server mounts on, and the caller context its operations take.
+ *
+ * ⚠️ **Concrete on purpose.** Making `registerRoutes` generic over the environment does not work:
+ * Hono narrows `Context` per route and its conditional types cannot reduce
+ * `IfAnyThenEmptyObject<E extends Env ? …>` while `E` is an unbound parameter, so nothing the app
+ * supplies is ever assignable and every call site needs a cast. Naming the types here instead — an
+ * app points `runtime-module` at its own module and re-declares them — keeps every generated call
+ * site concrete and cast-free. Identity defaults, so an app with neither can ignore both.
+ */
+export type AppEnv = Env;
+export type Ctx = unknown;
+/** Anything an operation may hand back: the value, or a promise of it. */
+export type Awaitable<T> = T | Promise<T>;
+/**
+ * Pick the media type to serve, per RFC 9110 §12.5.1.
+ *
+ * ⚠️ **In the runtime rather than in {@link RouteDeps}, deliberately.** The test for admitting
+ * anything to `deps` is *the generated code cannot proceed without an answer*, and this is not that:
+ * which media types an operation offers is a contract fact the emitter reads from the document, and
+ * how `Accept` selects among them is specified by the RFC. Both sides are derivable, so an app that
+ * had to supply this would be re-implementing the standard — and could get it wrong differently from
+ * everybody else.
+ *
+ * The rules that matter, and that a naive `includes()` gets wrong:
+ * - **absent or empty `Accept` means anything is acceptable** — serve the first offer;
+ * - **`q=0` is a REFUSAL**, not a weak preference, so a range scoring zero can never be chosen;
+ * - **specificity breaks ties before quality does**: `text/plain` beats `text/*` beats `*​/*` at
+ *   equal `q`, which is why the score is a pair and not a number;
+ * - parameters after the media range (`;charset=utf-8`) are not part of the match.
+ *
+ * Returns `undefined` when nothing offered is acceptable — the caller answers 406, and the
+ * difference between "no preference" and "no acceptable option" is exactly what that turns on.
+ */
+export declare function selectContentType(accept: string | undefined, offered: readonly string[]): string | undefined;
+/**
+ * What the app provides. One object, passed once, rather than a module the generated file imports by
+ * path — a generated server that hard-codes `../../backend.js` is only usable by the project it was
+ * generated in, and this one has to be usable by any.
+ *
+ * ⚠️ **The hooks are generic over Hono's path and input parameters, deliberately.** Hono narrows
+ * `Context` per route — by the literal path, and by whatever the validators on that route produced —
+ * so a hook typed against a single `Context<E>` is not assignable at any real call site. Making the
+ * hooks generic lets the app write functions that ignore both, without a cast anywhere.
+ *
+ * ⚠️ **`E` and `C` are PARAMETERS, and they have to be.** The defaults keep the bare `RouteDeps` the
+ * generated server writes working for an app that substitutes nothing. An app that substitutes
+ * anything binds them once — `export type RouteDeps = BaseRouteDeps<AppEnv, Ctx>` in the module it
+ * points `runtime-module` at — and every hook is then typed against its own environment and its own
+ * caller context.
+ *
+ * Re-exporting this interface unparameterised instead does not work, and the reason is not obvious:
+ * **Hono's `Context` is INVARIANT in its environment**, because `Context.set` takes `E` as an
+ * argument. So `Context<AppEnv, …>` is not assignable to `Context<Env, …>` however plain the
+ * substituted environment is, and every generated `deps.*` call site fails. Separately, `context`
+ * would keep returning the identity `Ctx` — `unknown` — which the app's own handlers then reject.
+ * Measured before this was parameterised: **19 errors on a four-operation service.**
+ */
+export interface RouteDeps<E extends Env = AppEnv, C = Ctx> {
+    /**
+     * The gate the DOCUMENT publishes, as middleware.
+     *
+     * ⚠️ **Which scopes an operation demands is a contract fact; how a token is verified is not.**
+     * `@useAuth(OAuth2Auth<…>)` reaches OpenAPI as `security` per operation, so the requirement is
+     * generated and this implements the check — the same split as `context` and `respond`. Emitted
+     * only where the operation declares scopes, which is why an internal surface with none is
+     * unaffected.
+     *
+     * Its absence was a real defect for one commit: the generated server carried **zero** references
+     * to scopes while the document published eleven, so a surface mounted with its gate silently
+     * dropped.
+     *
+     * ⚠️ **It receives the document's REQUIREMENTS, not a flat list of scopes, and that is the second
+     * half of the same defect.** `@useAuth(BearerAuth)` publishes `security: [{ "BearerAuth": [] }]` —
+     * no scopes — so a scopes-only gate was emitted for OAuth2 and for nothing else. Bearer, api-key
+     * and basic, which is most services, carried no gate at all and rested entirely on `context`
+     * returning null. An app whose `context` read a cookie would serve a route the document says needs
+     * a bearer token.
+     *
+     * Satisfying ANY ONE requirement authorises the caller, and every scheme WITHIN a requirement must
+     * be satisfied together — which is exactly what an array of OpenAPI `security` objects means.
+     */
+    readonly authorize: (requirements: readonly SecurityRequirement[]) => MiddlewareHandler<E>;
+    /**
+     * The caller's context, or `null` when there is none to establish.
+     *
+     * `authentication` is what the DOCUMENT says, and only that: `"none"` where the operation
+     * declares `@useAuth(NoAuth)` — `security: []` in OpenAPI — and `"required"` otherwise. Deciding
+     * it at generation time is the point: the gate the document publishes is the gate that runs.
+     *
+     * ⚠️ **It used to be `"none" | "account" | "resource"`, and the last two were an invention.** They
+     * were chosen by whether the path had parameters, which no OpenAPI keyword expresses and which
+     * merely happened to fit the first consumer. A generated server enforcing a rule derived from
+     * nothing published is the defect class this emitter exists to remove, so it is gone. An app that
+     * needs the distinction can read the request, which is the one thing it definitely has.
+     */
+    readonly context: <P extends string, I extends Input>(c: Context<E, P, I>, authentication: "none" | "required") => C | null;
+    /** The response when `context` returns `null`. */
+    readonly noContext: <P extends string, I extends Input>(c: Context<E, P, I>) => Response;
+    /**
+     * The response when the caller's `Accept` matches nothing the operation offers — a 406.
+     *
+     * Emitted only on routes where the document declares more than one media type for a status, so
+     * a service without content negotiation never sees it. Same shape of hook as {@link noContext}
+     * and admitted on the same test: the status and the `offered` list are contract facts the
+     * generated code already has, but the body they are reported in is the app's envelope, and it
+     * cannot proceed without one. {@link selectContentType} does the choosing; this reports failure.
+     */
+    readonly notAcceptable: <P extends string, I extends Input>(c: Context<E, P, I>, offered: readonly string[]) => Response;
+    /**
+     * Passed straight to `zValidator`'s hook. Returning `undefined` lets a successful validation
+     * through; returning a `Response` is how a rejection becomes the status this API promises rather
+     * than the middleware's default.
+     */
+    readonly invalid: <P extends string, I extends Input>(result: {
+        readonly success: boolean;
+    }, c: Context<E, P, I>) => Response | undefined;
+    /**
+     * Turn an operation's result into a response, checked against the schema the document publishes
+     * for the arm that applies. A bodyless success is an arm whose `schema` is `undefined`.
+     */
+    readonly respond: <P extends string, I extends Input>(c: Context<E, P, I>, arms: readonly ResponseArm[], result: unknown) => Awaitable<Response>;
+}

package/dist/src/runtime.js

@@ -0,0 +1,63 @@
+/**
+ * ⚠️ **`ResponseArm` and `armFor` live in `typespec-http-zod` and are re-exported here.**
+ *
+ * The library is what emits the response arms — `schemas.gen.ts` declares them and annotates them
+ * with `satisfies readonly ResponseArm[]` — so the type belongs to the package that produces it, and
+ * the rule for reading an array containing `4XX` and `default` belongs beside it. A consumer serving
+ * those validators from Express needs both and should not depend on a Hono emitter to get them.
+ *
+ * Re-exported rather than merely available, so an application still has ONE runtime import and the
+ * `runtime-module` substitution keeps working unchanged: a module an app points that option at has to
+ * supply every name the generated files reference, and they reference these.
+ */
+export { armFor } from "typespec-http-zod/runtime";
+/**
+ * Pick the media type to serve, per RFC 9110 §12.5.1.
+ *
+ * ⚠️ **In the runtime rather than in {@link RouteDeps}, deliberately.** The test for admitting
+ * anything to `deps` is *the generated code cannot proceed without an answer*, and this is not that:
+ * which media types an operation offers is a contract fact the emitter reads from the document, and
+ * how `Accept` selects among them is specified by the RFC. Both sides are derivable, so an app that
+ * had to supply this would be re-implementing the standard — and could get it wrong differently from
+ * everybody else.
+ *
+ * The rules that matter, and that a naive `includes()` gets wrong:
+ * - **absent or empty `Accept` means anything is acceptable** — serve the first offer;
+ * - **`q=0` is a REFUSAL**, not a weak preference, so a range scoring zero can never be chosen;
+ * - **specificity breaks ties before quality does**: `text/plain` beats `text/*` beats `*​/*` at
+ *   equal `q`, which is why the score is a pair and not a number;
+ * - parameters after the media range (`;charset=utf-8`) are not part of the match.
+ *
+ * Returns `undefined` when nothing offered is acceptable — the caller answers 406, and the
+ * difference between "no preference" and "no acceptable option" is exactly what that turns on.
+ */
+export function selectContentType(accept, offered) {
+    if (offered.length === 0)
+        return undefined;
+    const header = accept?.trim();
+    if (header === undefined || header === "")
+        return offered[0];
+    const ranges = header.split(",").map((entry) => {
+        const [range = "", ...parameters] = entry.split(";").map((part) => part.trim());
+        const quality = parameters
+            .map((parameter) => /^q=(?<value>[\d.]+)$/i.exec(parameter)?.groups?.value)
+            .find((value) => value !== undefined);
+        return { range: range.toLowerCase(), q: quality === undefined ? 1 : Number(quality) };
+    });
+    let best;
+    for (const type of offered) {
+        const [group] = type.toLowerCase().split("/");
+        for (const { range, q } of ranges) {
+            // `q=0` is "I will not accept this", so it never becomes a candidate.
+            if (!Number.isFinite(q) || q <= 0)
+                continue;
+            const specificity = range === type.toLowerCase() ? 2 : range === `${group}/*` ? 1 : range === "*/*" ? 0 : -1;
+            if (specificity < 0)
+                continue;
+            if (best === undefined || q > best.q || (q === best.q && specificity > best.specificity)) {
+                best = { type, q, specificity };
+            }
+        }
+    }
+    return best?.type;
+}