@sylphx/contract 0.2.0 → 0.3.0

package/dist/hono-app.d.ts

@@ -0,0 +1,206 @@
+/**
+ * `HonoAppFromEndpoints<G, BasePath>` — derive a Hono RPC-compatible app
+ * type purely from an `EndpointGroup`.
+ *
+ * ## Why this exists
+ *
+ * Pre-2026-05-03 the platform used `@sylphx/api-types` to re-export route
+ * types DIRECTLY from `apps/api/src/server/...`:
+ *
+ *   ```ts
+ *   // packages/api-types/src/routes/admin-billing.ts (OLD)
+ *   export type * from '@/server/platform/routes/admin-billing'
+ *   ```
+ *
+ * That re-export forced `apps/web`'s typecheck to traverse the entire
+ * backend implementation graph (`@sylphx/core/lib/db/effect`, the K8s
+ * reconciler, audit pipeline, …). Every backend type bug cascaded into
+ * a Web build failure — 24+ hours of consecutive web build failures
+ * on 2026-05-03. SoC violation at the package boundary; ADR-084
+ * contract-first violated.
+ *
+ * The SOTA fix (this file): synthesise the Hono RPC type purely from
+ * `@sylphx/contract` endpoint definitions. Web depends only on
+ * Effect Schema + Hono types — never on backend code.
+ *
+ * ## How it composes
+ *
+ * Hono's RPC client `hc<T>(baseUrl)` accepts a `Hono<E, Schema, BasePath>`
+ * type and produces a typed proxy where each path segment is a property
+ * and each HTTP method is a `$method` key. The Schema shape (verified
+ * from `node_modules/hono/dist/types/types/types.d.ts`) is:
+ *
+ *   ```ts
+ *   type Schema = {
+ *     [Path: string]: {
+ *       [`$${Lowercase<HttpMethod>}`]: {
+ *         input: { json?, query?, param?, header?, form? }
+ *         output: ResponseBodyType
+ *         outputFormat: 'json' | 'text' | …
+ *         status: StatusCode
+ *       }
+ *     }
+ *   }
+ *   ```
+ *
+ * `HonoAppFromEndpoints<G>` constructs exactly that Schema by recursively
+ * walking each `Endpoint` in the group to one entry, then intersecting them.
+ *
+ * ## BasePath / StripPrefix
+ *
+ * Each contract endpoint carries the FULL public path (e.g.
+ * `/operator/billing/overview`). The web's hc-client historically mounts
+ * at the parent prefix (e.g. `${PLATFORM_BASE_PATH}/operator/billing`)
+ * and accesses `.overview` — so the type's path keys must be RELATIVE
+ * to the mount. `StripPrefix<G, BP>` rewrites each endpoint path to
+ * remove the leading `BP`, preserving the existing client structure
+ * with zero consumer churn.
+ *
+ * @see ADR-084 — Effect Schema contract-first
+ * @see docs/audit/2026-05-03-e2e-run/SSOT.md — E-25 (web build chronic failure)
+ */
+import type { Schema } from 'effect';
+import type { Hono } from 'hono';
+import type { Endpoint, EndpointGroup, HttpMethod } from './endpoint.js';
+type HonoBaseSchema = import('hono').Schema;
+/**
+ * Distribute a union into a function-parameter position then re-extract,
+ * collapsing it to an intersection. Standard TypeScript trick.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * Recursively strip `readonly` from objects and arrays. Effect Schema
+ * `Type<S>` produces deeply-readonly shapes; consumer code in `apps/web`
+ * (and downstream React libraries) historically receives mutable
+ * arrays — preserve assignability by unwrapping.
+ *
+ * Skips Date / function / class instances (they're not plain objects);
+ * `T extends T` distributes over unions so `string | readonly string[]`
+ * is processed branch-by-branch.
+ */
+type WritableDeep<T> = T extends Date | RegExp | ((...args: unknown[]) => unknown) ? T : T extends string | number | boolean | bigint | symbol | null | undefined ? T : T extends ReadonlyArray<infer E> ? WritableDeep<E>[] : T extends object ? {
+    -readonly [K in keyof T]: WritableDeep<T[K]>;
+} : T;
+/**
+ * Extract the runtime TypeScript type `A` from an Effect `Schema<A, I, R>`,
+ * then strip deeply-nested `readonly` modifiers so consumer assignment
+ * targets (mutable arrays, mutable objects) typecheck.
+ *
+ * Returns `never` when the input isn't a recognised schema (so the
+ * conditional in `EndpointInput` cleanly omits the key).
+ *
+ * IMPORTANT: we must NOT constrain the encoded `I` to `unknown` — most
+ * struct schemas have `I` being a structurally-distinct encoded shape,
+ * not `unknown`. Using `Schema.Schema.AnyNoContext` matches any schema
+ * with `R = never` regardless of `I`, which is what we want for response
+ * type extraction. Pre-2026-05-04 the constraint was `Schema.Schema<infer
+ * A, unknown, never>` which failed to match struct schemas — every
+ * endpoint resolved to `never` and `apps/web` consumers saw
+ * `anomaly.status → Property does not exist on type 'never'`.
+ */
+type SchemaType<S> = S extends Schema.Schema.AnyNoContext ? WritableDeep<Schema.Schema.Type<S>> : never;
+/**
+ * Strip a leading prefix from a literal string type.
+ *
+ *   StripBase<'/operator/billing/overview', '/operator/billing'> → '/overview'
+ *   StripBase<'/operator/billing',           '/operator/billing'> → '/'
+ *   StripBase<'/foo',                        '/operator/billing'> → '/foo'  (no match — passthrough)
+ */
+type StripBase<Path extends string, BasePath extends string> = BasePath extends '/' ? Path : Path extends `${BasePath}${infer Rest}` ? Rest extends '' ? '/' : Rest : Path;
+/**
+ * Build the Hono `input` shape from a contract endpoint.
+ *
+ * Hono's validation targets are `param` (path), `query`, `json` (body),
+ * `header`, `form`. Our contract uses `params`, `query`, `body` — map
+ * `params → param` and `body → json`.
+ *
+ * The schema entry stores the validation targets at the TOP level of
+ * `input` (matching what `@hono/zod-validator`-style middlewares produce
+ * after running). Hono's `hc<T>(...)` proxy reads this shape directly to
+ * type-check the `client[path].$method(<args>)` call argument.
+ */
+type EndpointInput<E extends Endpoint> = (E['params'] extends Schema.Schema.AnyNoContext ? {
+    param: SchemaType<E['params']>;
+} : {}) & (E['query'] extends Schema.Schema.AnyNoContext ? {
+    query: SchemaType<E['query']>;
+} : {}) & (E['body'] extends Schema.Schema.AnyNoContext ? {
+    json: SchemaType<E['body']>;
+} : {});
+/**
+ * Build a single Hono Schema entry for one endpoint after BasePath stripping.
+ *
+ * The `$method` key uses lowercase + `$` prefix per Hono's `AddDollar<T>`.
+ * Output collapses to `status: 200` + `outputFormat: 'json'` because that
+ * is the success path of every public endpoint we emit. Multi-status
+ * differentiation (e.g. 202 vs 200) can be added later by reading
+ * `endpoint.errors` and projecting per-status entries — out of scope for
+ * the chronic-build-failure fix.
+ */
+type EndpointToHonoEntry<E extends Endpoint, BasePath extends string> = {
+    [P in StripBase<E['path'], BasePath>]: {
+        [M in `$${Lowercase<E['method']>}`]: {
+            input: EndpointInput<E>;
+            output: SchemaType<E['response']>;
+            outputFormat: 'json';
+            status: 200;
+        };
+    };
+};
+/**
+ * Walk every endpoint in `G`, recursively flatten nested endpoint groups,
+ * build per-endpoint Hono entries with BasePath stripped, then intersect them
+ * into one Schema object.
+ *
+ * NOTE: we intentionally do NOT intersect with `HonoSchema` here. That
+ * outer index signature `{[Path: string]: {[Method]: Endpoint}}` would
+ * widen the precise per-endpoint entries we just built — Hono's hc<T>
+ * proxy navigates by literal property keys, and the index-signature
+ * intersection causes TS to infer everything as the loose Endpoint
+ * fallback (`output: any` etc.), which then fails to match
+ * `ClientResponse<infer Body, 200, 'json'>` in `serverFetch`'s
+ * ExtractSuccessBody and resolves to `never`.
+ */
+type SchemaFromGroup<G extends EndpointGroup, BasePath extends string> = UnionToIntersection<{
+    [K in keyof G]: G[K] extends Endpoint ? EndpointToHonoEntry<G[K], BasePath> : G[K] extends EndpointGroup ? SchemaFromGroup<G[K], BasePath> : never;
+}[keyof G]>;
+/**
+ * Synthesise a Hono RPC-compatible app type from a contract endpoint group.
+ *
+ * @template G — a `Record<string, Endpoint>` exported from `@sylphx/contract`
+ *   (e.g. `typeof adminBillingEndpoints`).
+ * @template BasePath — the URL prefix at which the Hono app will be mounted
+ *   on the production API. Each endpoint path that starts with this prefix
+ *   has the prefix stripped before being added to the Schema. Defaults to
+ *   `'/'` (no stripping — paths are kept verbatim from the contract).
+ *
+ * @example
+ *   ```ts
+ *   import type { HonoAppFromEndpoints } from '@sylphx/contract/hono-app'
+ *   import type { adminBillingEndpoints } from '@sylphx/contract'
+ *   import { hc } from 'hono/client'
+ *
+ *   // Mount path strips '/operator/billing' from contract paths so that
+ *   // `client.overview.$get({})` lands at `/v1/operator/billing/overview`
+ *   // when the client is constructed with `baseUrl = '/v1/operator/billing'`.
+ *   export type AdminBillingRoutes = HonoAppFromEndpoints<
+ *     typeof adminBillingEndpoints,
+ *     '/operator/billing'
+ *   >
+ *
+ *   const client = hc<AdminBillingRoutes>('/v1/operator/billing')
+ *   const res = await client.overview.$get({})
+ *   ```
+ *
+ * @example
+ *   ```ts
+ *   // Or — mount at root, paths kept verbatim:
+ *   export type ProjectsRoutes = HonoAppFromEndpoints<typeof projectsEndpoints>
+ *   const client = hc<ProjectsRoutes>('/v1')
+ *   const res = await client.projects.$get({})
+ *   ```
+ */
+type AsHonoSchema<T> = T extends HonoBaseSchema ? T : never;
+export type HonoAppFromEndpoints<G extends EndpointGroup, BasePath extends string = '/'> = Hono<Record<never, never>, AsHonoSchema<SchemaFromGroup<G, BasePath>>, BasePath>;
+/** Re-export so consumers don't need a second import for endpoint typing. */
+export type { Endpoint, EndpointGroup, HttpMethod };
+//# sourceMappingURL=hono-app.d.ts.map

package/dist/hono-app.d.ts.map

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

package/dist/hono-app.js

@@ -0,0 +1,62 @@
+/**
+ * `HonoAppFromEndpoints<G, BasePath>` — derive a Hono RPC-compatible app
+ * type purely from an `EndpointGroup`.
+ *
+ * ## Why this exists
+ *
+ * Pre-2026-05-03 the platform used `@sylphx/api-types` to re-export route
+ * types DIRECTLY from `apps/api/src/server/...`:
+ *
+ *   ```ts
+ *   // packages/api-types/src/routes/admin-billing.ts (OLD)
+ *   export type * from '@/server/platform/routes/admin-billing'
+ *   ```
+ *
+ * That re-export forced `apps/web`'s typecheck to traverse the entire
+ * backend implementation graph (`@sylphx/core/lib/db/effect`, the K8s
+ * reconciler, audit pipeline, …). Every backend type bug cascaded into
+ * a Web build failure — 24+ hours of consecutive web build failures
+ * on 2026-05-03. SoC violation at the package boundary; ADR-084
+ * contract-first violated.
+ *
+ * The SOTA fix (this file): synthesise the Hono RPC type purely from
+ * `@sylphx/contract` endpoint definitions. Web depends only on
+ * Effect Schema + Hono types — never on backend code.
+ *
+ * ## How it composes
+ *
+ * Hono's RPC client `hc<T>(baseUrl)` accepts a `Hono<E, Schema, BasePath>`
+ * type and produces a typed proxy where each path segment is a property
+ * and each HTTP method is a `$method` key. The Schema shape (verified
+ * from `node_modules/hono/dist/types/types/types.d.ts`) is:
+ *
+ *   ```ts
+ *   type Schema = {
+ *     [Path: string]: {
+ *       [`$${Lowercase<HttpMethod>}`]: {
+ *         input: { json?, query?, param?, header?, form? }
+ *         output: ResponseBodyType
+ *         outputFormat: 'json' | 'text' | …
+ *         status: StatusCode
+ *       }
+ *     }
+ *   }
+ *   ```
+ *
+ * `HonoAppFromEndpoints<G>` constructs exactly that Schema by recursively
+ * walking each `Endpoint` in the group to one entry, then intersecting them.
+ *
+ * ## BasePath / StripPrefix
+ *
+ * Each contract endpoint carries the FULL public path (e.g.
+ * `/operator/billing/overview`). The web's hc-client historically mounts
+ * at the parent prefix (e.g. `${PLATFORM_BASE_PATH}/operator/billing`)
+ * and accesses `.overview` — so the type's path keys must be RELATIVE
+ * to the mount. `StripPrefix<G, BP>` rewrites each endpoint path to
+ * remove the leading `BP`, preserving the existing client structure
+ * with zero consumer churn.
+ *
+ * @see ADR-084 — Effect Schema contract-first
+ * @see docs/audit/2026-05-03-e2e-run/SSOT.md — E-25 (web build chronic failure)
+ */
+export {};