@forinda/kickjs 5.17.0 → 5.18.0-alpha.1

package/dist/router-builder-Bh3qSiDz.d.mts

@@ -0,0 +1,39 @@
+
+import { J as SourcedRegistration, m as RouteEntry } from "./adapter-D_uzU-QA.mjs";
+
+//#region src/http/router-builder.d.ts
+/** @internal — set by Application.setup() before each `mod.routes()` call. */
+declare function _setExternalContributorSources(sources: readonly SourcedRegistration[]): void;
+interface BuildRoutesOptions {
+  /**
+   * Extra contributors to merge into the per-route pipeline at their declared
+   * precedence levels. Pass explicitly when calling buildRouteTable/buildRoutes
+   * outside the Application route-mount loop (typically in tests). When omitted,
+   * falls back to the slot set by Application.setup().
+   */
+  externalSources?: readonly SourcedRegistration[];
+}
+/**
+ * Turn a controller class decorated with @Get, @Post, etc. into a plain-data
+ * {@link RouteEntry}[] — the engine-neutral route table an {@link HttpRuntime}
+ * materializes (see `docs/http/spec-http-runtimes.md`, Avenue B).
+ *
+ * What used to be per-handler Express `(req, res, next)` closures is now
+ * captured as data: `middlewares` keep their `(ctx, next)` shape, the contributor
+ * pipeline is pre-built into a `contributorRunner` closure, validation / upload
+ * stay as metadata, and the terminal `handler` resolves the controller per-request
+ * (to respect DI scoping) and invokes it. The runtime owns how these get wrapped
+ * onto its engine.
+ *
+ * Routes use only the method-level decorator paths (e.g. @Get('/me') → '/me').
+ * The @Controller path is NOT baked in — it is metadata for Swagger/introspection.
+ * The module's routes().path is the single source of truth for the mount prefix,
+ * which avoids path doubling when both the module and controller specify the path.
+ *
+ * The contributor pipeline is built here, so a cycle or missing `dependsOn`
+ * throws at table-build time (boot) rather than on first request.
+ */
+declare function buildRouteTable(controllerClass: any, options?: BuildRoutesOptions): RouteEntry[];
+//#endregion
+export { _setExternalContributorSources as n, buildRouteTable as r, BuildRoutesOptions as t };
+//# sourceMappingURL=router-builder-Bh3qSiDz.d.mts.map

package/dist/router-builder-Bh3qSiDz.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-builder-Bh3qSiDz.d.mts","names":[],"sources":["../src/http/router-builder.ts"],"mappings":";;;;;iBAgCgB,8BAAA,CAA+B,OAAuC,WAArB,mBAAmB;AAAA,UAInE,kBAAA;;;AAJqE;AAItF;;;EAOE,eAAA,YAA2B,mBAAmB;AAAA;AAuBhD;;;;;;;;;AAGa;;;;;;;;;;;AAHb,iBAAgB,eAAA,CACd,eAAA,OACA,OAAA,GAAS,kBAAA,GACR,UAAU"}

package/dist/{spa-IRFC2eMN.d.mts → spa-BdvZFXJz.d.mts}

@@ -1,5 +1,6 @@
 
-import { r as AppAdapter, t as AdapterContext } from "./adapter-CkpcZwzZ.mjs";
+import { r as AppAdapter, t as AdapterContext } from "./adapter-D_uzU-QA.mjs";
+
 //#region src/http/middleware/spa.d.ts
 interface SpaAdapterOptions {
   /**
@@ -98,4 +99,4 @@ declare class SpaAdapter implements AppAdapter {
 }
 //#endregion
 export { SpaAdapterOptions as n, SpaAdapter as t };
-//# sourceMappingURL=spa-IRFC2eMN.d.mts.map
+//# sourceMappingURL=spa-BdvZFXJz.d.mts.map

package/dist/spa-BdvZFXJz.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spa-BdvZFXJz.d.mts","names":[],"sources":["../src/http/middleware/spa.ts"],"mappings":";;;;UAMiB,iBAAA;;AAAjB;;;;;;;;;;AAiDmB;AAkCnB;EArEE,SAAA;;;;;;;;;;;EAYA,SAAA;EA0DA;;;;;;;;;EA/CA,OAAA;EAiEA;;;;EA3DA,YAAA;EAoGc;;;;EA9Fd,iBAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkCW,UAAA,YAAsB,UAAA;EAAA,QASb,OAAA;EARpB,IAAA;EAAA,QACQ,SAAA;EAAA,QACA,WAAA;EAAA,QACA,YAAA;EAAA,QACA,YAAA;EAAA,QACA,iBAAA;EAAA,QACA,SAAA;EAER,WAAA,CAAoB,OAAA,GAAS,iBAAA;EAU7B,WAAA;IAAc;EAAA,GAAO,cAAA;EAyCrB,WAAA;IAAc;EAAA,GAAO,cAAA;AAAA"}

package/dist/{upload-D6edAELH.d.mts → upload-Bc_rBRtE.d.mts}

@@ -15,6 +15,41 @@ import { Options } from "multer";
  * ```
  */
 declare function resolveMimeTypes(types: string[]): string[];
+/**
+ * Build a runtime-agnostic `(mimetype, filename) => boolean` file-type filter
+ * from `allowedTypes` (a predicate, or a list of extensions / MIME types /
+ * wildcards). Returned by both the multer middleware (Express) and the
+ * Fastify / h3 multipart paths so the accept/reject rule stays identical
+ * across engines. No `allowedTypes` → accept everything.
+ */
+declare function buildFileTypeFilter(allowedTypes: BaseUploadOptions['allowedTypes'], customMimeMap?: Record<string, string>): (mimetype: string, filename: string) => boolean;
+/** A multer-shaped uploaded file — what `ctx.file` / `ctx.files` expose. */
+interface UploadedFileLike {
+  fieldname: string;
+  originalname: string;
+  encoding: string;
+  mimetype: string;
+  size: number;
+  buffer: Buffer;
+}
+/** A buffered multipart file part, as the runtime hands it to {@link applyUploadConfig}. */
+interface RawUploadPart {
+  fieldname: string;
+  filename: string;
+  mimetype: string;
+  buffer: Buffer;
+}
+/**
+ * Apply a `@FileUpload` config to already-buffered multipart parts and return
+ * the multer-shaped `file` / `files` for `ctx`. Enforces the field name, type
+ * filter, per-file size limit, and (array mode) max count — throwing
+ * `HttpException` on a violation, mirroring the Express/multer error path.
+ * Used by the Fastify and h3 runtimes; Express keeps using multer directly.
+ */
+declare function applyUploadConfig(parts: RawUploadPart[], config: FileUploadConfig): {
+  file?: UploadedFileLike;
+  files?: UploadedFileLike[];
+};
 /**
  * Upload options for the middleware.
  * Extends BaseUploadOptions from core (shared with @FileUpload decorator)
@@ -75,5 +110,5 @@ declare const upload: {
   none: typeof none;
 };
 //#endregion
-export { upload as a, resolveMimeTypes as i, buildUploadMiddleware as n, cleanupFiles as r, UploadOptions as t };
-//# sourceMappingURL=upload-D6edAELH.d.mts.map
+export { buildFileTypeFilter as a, resolveMimeTypes as c, applyUploadConfig as i, upload as l, UploadOptions as n, buildUploadMiddleware as o, UploadedFileLike as r, cleanupFiles as s, RawUploadPart as t };
+//# sourceMappingURL=upload-Bc_rBRtE.d.mts.map

package/dist/upload-Bc_rBRtE.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-Bc_rBRtE.d.mts","names":[],"sources":["../src/http/middleware/upload.ts"],"mappings":";;;;;;;;;AAsGA;;;;AAAgD;AAchD;;iBAdgB,gBAAA,CAAiB,KAAe;;;;;;;;iBAchC,mBAAA,CACd,YAAA,EAAc,iBAAA,kBACd,aAAA,GAAgB,MAAM,oBACpB,QAAA,UAAkB,QAAA;AAAgB;AAAA,UAYrB,gBAAA;EACf,SAAA;EACA,YAAA;EACA,QAAA;EACA,QAAA;EACA,IAAA;EACA,MAAA,EAAQ,MAAM;AAAA;;UAIC,aAAA;EACf,SAAA;EACA,QAAA;EACA,QAAA;EACA,MAAA,EAAQ,MAAM;AAAA;;;;;;;;iBAYA,iBAAA,CACd,KAAA,EAAO,aAAA,IACP,MAAA,EAAQ,gBAAA;EACL,IAAA,GAAO,gBAAA;EAAkB,KAAA,GAAQ,gBAAA;AAAA;;;;;;UAyCrB,aAAA,SAAsB,iBAAiB;EAzCF;EA2CpD,OAAA,GAAU,OAAA;EA7CV;EA+CA,IAAA;AAAA;;;;;;AA7CoD;AAyCtD;;;;;;iBA8CS,MAAA,CAAO,SAAA,UAAmB,OAAA,GAAS,aAAA,GAAqB,cAAc;;;AA1CzE;iBAkDG,KAAA,CAAM,SAAA,UAAmB,QAAA,WAAe,OAAA,GAAS,aAAA,GAAqB,cAAc;;;;iBAQpF,IAAA,CAAK,OAAA,GAAS,aAAA,GAAqB,cAAc;;;;;AAhBqB;AAAA;;;;;;;;;iBAmC/D,YAAA,KAAY,GAAA,EACb,OAAA,EAAO,GAAA,EAAO,QAAA,EAAQ,IAAA,EAAQ,YAAA;AA5BgD;AAAA;;;;AAAA,iBA2D7E,qBAAA,CAAsB,MAAA,EAAQ,gBAAA,GAAmB,cAAc;;cAmBlE,MAAA"}

package/dist/{views-DkllbVB3.d.mts → views-DcTVDiOh.d.mts}

@@ -1,9 +1,8 @@
 
-import { i as MetaValue } from "./execution-context-B4cfhivz.mjs";
-import { c as DepValue, n as ContextDecorator, r as ContextDecoratorSpec } from "./context-decorator-DDZ30BIW.mjs";
-import { c as AdapterFactory } from "./index-frSEHiL_.mjs";
-import { r as RequestContext } from "./context-DV7RjM9F.mjs";
-import { NextFunction, Request, Response } from "express";
+import { f as DepValue, o as ContextDecorator, s as ContextDecoratorSpec, v as MetaValue } from "./app-module-CuAS6hJC.mjs";
+import { P as AdapterFactory, T as RequestContext, f as HttpRuntime, m as RouteEntry } from "./adapter-D_uzU-QA.mjs";
+import { t as BuildRoutesOptions } from "./router-builder-Bh3qSiDz.mjs";
+import { Express, NextFunction, Request, Response, Router } from "express";
 import { AsyncLocalStorage } from "node:async_hooks";
 
 //#region src/http/cluster.d.ts
@@ -57,6 +56,31 @@ interface DefineHttpContextDecoratorFn {
 }
 declare const defineHttpContextDecorator: DefineHttpContextDecoratorFn;
 //#endregion
+//#region src/http/runtimes/express.d.ts
+/**
+ * Materialize a controller's {@link RouteEntry}[] onto a fresh `express.Router`.
+ * Reproduces the legacy handler ordering precisely: validation → upload →
+ * `(ctx, next)` middleware → contributor runner → terminal handler. Each step
+ * constructs its own `RequestContext` over the same `req`/`res` — request-scoped
+ * state lives in the AsyncLocalStorage store, not on the ctx instance, so the
+ * per-step instances share state exactly as before.
+ */
+declare function materializeRouter(entries: RouteEntry[]): Router;
+/**
+ * Build an Express Router from a controller class decorated with @Get, @Post,
+ * etc. The public, back-compatible entry point: a thin shim over
+ * {@link buildRouteTable} + {@link materializeRouter}. Returns an
+ * `express.Router` exactly as before — modules pass it to `app.use(path, router)`.
+ *
+ * @see buildRouteTable for the engine-neutral route-table form.
+ */
+declare function buildRoutes(controllerClass: any, options?: BuildRoutesOptions): Router;
+/**
+ * The default HTTP runtime. Express stays a peer dependency of `@forinda/kickjs`;
+ * apps that pass no `runtime` get this and behave exactly as before.
+ */
+declare function expressRuntime(): HttpRuntime<Express>;
+//#endregion
 //#region src/http/request-store.d.ts
 /** Per-request storage for REQUEST-scoped DI and request context propagation */
 interface RequestStore {
@@ -245,5 +269,5 @@ interface ViewAdapterOptions {
  */
 declare const ViewAdapter: AdapterFactory<ViewAdapterOptions, unknown>;
 //#endregion
-export { TraceContextOptions as a, requestScopeMiddleware as c, getRequestValue as d, requestStore as f, isClusterPrimary as h, TraceContext as i, RequestStore as l, ClusterOptions as m, ViewAdapterOptions as n, parseTraceparent as o, defineHttpContextDecorator as p, TRACEPARENT_HEADER as r, traceContext as s, ViewAdapter as t, getRequestStore as u };
-//# sourceMappingURL=views-DkllbVB3.d.mts.map
+export { ClusterOptions as _, TraceContextOptions as a, requestScopeMiddleware as c, getRequestValue as d, requestStore as f, defineHttpContextDecorator as g, materializeRouter as h, TraceContext as i, RequestStore as l, expressRuntime as m, ViewAdapterOptions as n, parseTraceparent as o, buildRoutes as p, TRACEPARENT_HEADER as r, traceContext as s, ViewAdapter as t, getRequestStore as u, isClusterPrimary as v };
+//# sourceMappingURL=views-DcTVDiOh.d.mts.map

package/dist/views-DcTVDiOh.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views-DcTVDiOh.d.mts","names":[],"sources":["../src/http/cluster.ts","../src/http/define-http-context-decorator.ts","../src/http/runtimes/express.ts","../src/http/request-store.ts","../src/http/middleware/request-scope.ts","../src/http/middleware/trace-context.ts","../src/http/middleware/views.ts"],"mappings":";;;;;;;;UAOiB,cAAA;;EAEf,OAAA;;EAEA,uBAAA;;EAEA,YAAA;;EAEA,WAAA;;EAEA,aAAA;AAAA;;iBAIc,gBAAA;;;;;;;;UCuDC,oCAAA,WAA+C,MAAA;EAAA,6BACjC,MAAA,SAAe,QAAA,IAAY,MAAA,iBACtD,IAAA,EAAM,oBAAA,CAAqB,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,cAAA,IACnC,gBAAA,CAAiB,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,cAAA;AAAA;;;;;;UAQd,4BAAA;EAAA,6BAGH,MAAA,SAAe,QAAA,IAAY,MAAA,2BAC3B,MAAA,oBAA0B,MAAA,iBAEpC,IAAA,EAAM,oBAAA,CAAqB,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,cAAA,IACnC,gBAAA,CAAiB,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,cAAA;EAPd;;;;;;;;;;;;;;;EAwBf,UAAA,WAAqB,MAAA,sBAA4B,oCAAA,CAAqC,CAAA;AAAA;AAAA,cAW3E,0BAAA,EAA4B,4BAQR;;;;;;;;;;;iBC5FjB,iBAAA,CAAkB,OAAA,EAAS,UAAA,KAAe,MAAM;;;;;;;;;iBA8DhD,WAAA,CAAY,eAAA,OAAsB,OAAA,GAAS,kBAAA,GAA0B,MAAM;AF7F3F;;;;AAAA,iBEqGgB,cAAA,IAAkB,WAAW,CAAC,OAAA;;;;UCxG7B,YAAA;;EAEf,SAAA;;;;;;EAMA,SAAA,EAAW,GAAA;;;;;;;;;;AHLb;;;;;;;;;;AAUe;EGgBb,MAAA,EAAQ,GAAG;AAAA;;cAIA,YAAA,EAAY,iBAAA,CAAA,YAAA;AHhBO;;;;AAAA,iBGsBhB,eAAA,IAAmB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoC/B,eAAA,mBAAkC,GAAA,EAAK,CAAA,GAAI,SAAA,CAAU,CAAA;;;;;;;;;;;iBCvCrD,sBAAA,KAAsB,GAAA,EACnB,OAAA,EAAO,IAAA,EAAQ,QAAA,EAAQ,IAAA,EAAQ,YAAA;;;;;;;cCjCrC,kBAAA;AAAA,UAKI,mBAAA;;;;;EAKf,iBAAiB;AAAA;;;;UAMF,YAAA;;EAEf,OAAA;;EAEA,OAAA;ELrBe;EKuBf,YAAA;;EAEA,KAAA;AAAA;;;;;iBAqBc,gBAAA,CAAiB,MAAA,WAAiB,YAAY;ALpC/C;AAIf;;;;AAAgC;;;;ACuDhC;;;;;;;;;;;;AD3De,iBK8EC,YAAA,CAAa,OAAA,GAAS,mBAAA,IAAwB,GAAA,EAC/C,OAAA,EAAO,GAAA,EAAO,QAAA,EAAQ,IAAA,EAAQ,YAAA;;;UC3F5B,kBAAA;;;;;;;;;;;;;;;EAef,MAAA;;EAGA,GAAA;;EAGA,QAAA;;EAGA,MAAA;AAAA;;;;;;;;;ANZa;AAIf;;;;AAAgC;;;;ACuDhC;;;;;;;;;;;;cKfa,WAAA,EAAW,cAAA,CAAA,kBAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forinda/kickjs",
-  "version": "5.17.0",
+  "version": "5.18.0-alpha.1",
   "description": "A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript.",
   "keywords": [
     "kickjs",
@@ -89,6 +89,14 @@
     "./config": {
       "import": "./dist/config/index.mjs",
       "types": "./dist/config/index.d.mts"
+    },
+    "./fastify": {
+      "import": "./dist/http/runtimes/fastify.mjs",
+      "types": "./dist/http/runtimes/fastify.d.mts"
+    },
+    "./h3": {
+      "import": "./dist/http/runtimes/h3.mjs",
+      "types": "./dist/http/runtimes/h3.d.mts"
     }
   },
   "files": [
@@ -101,28 +109,54 @@
     "@forinda/kickjs-schema": "0.1.2"
   },
   "peerDependencies": {
+    "@fastify/middie": "^9.0.0",
+    "@fastify/multipart": "^9.0.0",
     "dotenv": "^17.0.0",
     "express": "^5.1.0",
+    "fastify": "^5.0.0",
+    "h3": "^1.0.0",
     "multer": "^2.0.0",
+    "serve-static": "^1.15.0 || ^2.0.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "@fastify/middie": {
+      "optional": true
+    },
+    "@fastify/multipart": {
+      "optional": true
+    },
     "dotenv": {
       "optional": true
     },
+    "h3": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
     "multer": {
       "optional": true
     },
+    "serve-static": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@fastify/middie": "^9.3.2",
+    "@fastify/multipart": "^9.0.0",
     "@swc/core": "^1.15.40",
     "@types/express": "^5.0.6",
     "@types/multer": "^2.1.0",
     "@types/node": "^25.9.2",
+    "@types/serve-static": "^1.15.7",
+    "fastify": "^5.8.5",
+    "h3": "1.15.11",
     "multer": "^2.1.1",
+    "serve-static": "^2.2.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.8",

package/dist/adapter-CkpcZwzZ.d.mts

@@ -1,407 +0,0 @@
-
-import { i as Constructor, o as MaybePromise } from "./interfaces-DbTyKGdS.mjs";
-import { t as Container } from "./container-TWOUyR_0.mjs";
-import { s as ContributorRegistrations } from "./context-decorator-DDZ30BIW.mjs";
-import http from "node:http";
-import { ErrorRequestHandler, Express, RequestHandler } from "express";
-
-//#region src/core/introspect.d.ts
-/**
- * Per-primitive introspection snapshot — the JSON shape an adapter or
- * plugin's optional `introspect()` hook returns for DevTools.
- *
- * Lives in `@forinda/kickjs` (not `@forinda/kickjs-devtools-kit`) so
- * adopters can type their `introspect()` return without taking on a
- * dep on the kit just to satisfy the contract. The kit's own
- * `IntrospectionSnapshot` type is structurally identical and continues
- * to be the canonical doc location for DevTools-side consumers; the
- * two stay in lockstep — if a field is added on one side it MUST be
- * added on the other (covered by the type-equivalence test in the
- * devtools-kit package).
- *
- * Cheap-by-default principle: `state` and `metrics` should be O(1) to
- * compute (counters, flags, recent samples). Anything that requires a
- * DB round trip or a full DI graph walk belongs behind a separate
- * explicit RPC — DevTools polls topology aggressively.
- */
-interface IntrospectionSnapshot {
-  /**
-   * Wire-protocol version this snapshot conforms to. The kit ships a
-   * `PROTOCOL_VERSION` constant typed as the literal `1`; we mirror
-   * that literal here so structural parity is enforced both ways —
-   * an adopter who writes `protocolVersion: 1` satisfies both this
-   * type and the kit's `IntrospectionSnapshot`. Bumping is a
-   * coordinated kit + framework release; widen this literal in
-   * lockstep.
-   */
-  protocolVersion: 1;
-  /** Stable identity matching the `name` from `definePlugin` / `defineAdapter`. */
-  name: string;
-  /** Discriminator for what kind of primitive this is. */
-  kind: IntrospectionKind;
-  /** Optional version string from the plugin / adapter metadata. */
-  version?: string;
-  /**
-   * Reactive state surface — JSON-serialisable snapshot. Keep small
-   * (under a few KB) so polling stays cheap.
-   */
-  state?: Record<string, unknown>;
-  /** DI tokens this primitive registers (`provides`) or consumes (`requires`). */
-  tokens?: {
-    provides: readonly string[];
-    requires: readonly string[];
-  };
-  /**
-   * Per-instance counters — active connections, in-flight jobs, cached
-   * items, etc. Numbers only so the DevTools panel can chart trends.
-   */
-  metrics?: Record<string, number>;
-  /** Self-reported memory footprint estimate, in bytes. Optional. */
-  memoryBytes?: number;
-}
-/**
- * What kind of primitive an introspection snapshot describes. Matches
- * the kit's `IntrospectionKind` and the routing the topology aggregator
- * does when bucketing adapters vs plugins vs middleware vs contributor
- * primitives.
- */
-type IntrospectionKind = 'plugin' | 'adapter' | 'middleware' | 'contributor';
-/**
- * Convenience function signature for adopter-side helpers that return
- * a complete snapshot. Used by the optional `introspect?()` hook on
- * `AppAdapter` and `KickPlugin`.
- */
-type IntrospectFn = () => IntrospectionSnapshot | Promise<IntrospectionSnapshot>;
-//#endregion
-//#region src/core/augmentation.d.ts
-/**
- * Augmentation registry — runtime no-op + the canonical
- * `KickJsPluginRegistry` interface that `kick typegen` augments.
- *
- * See `architecture.md` §21.2.1 (typegen for `dependsOn`) and §21.3.3
- * (standardized augmentation registry) for the design rationale.
- *
- * @module @forinda/kickjs/core/augmentation
- */
-/**
- * Marker interface that lists every plugin/adapter in the project. The
- * keys are the literal `name` field passed to `defineAdapter` /
- * `definePlugin` (or declared on a `class implements AppAdapter`); the
- * values are the kind tag (`'plugin' | 'adapter'`).
- *
- * The framework ships this empty. `kick typegen` augments it from
- * source so `keyof KickJsPluginRegistry` resolves to a string-literal
- * union of every name in scope — and therefore so do `dependsOn`
- * declarations on plugins/adapters.
- */
-interface KickJsPluginRegistry {}
-/**
- * Resolves to a string-literal union of every registered plugin/adapter
- * name when the project's typegen has populated `KickJsPluginRegistry`,
- * or to `string` when the registry is empty (no typegen pass yet).
- *
- * Falling back to `string` keeps fresh projects compiling — the typegen
- * narrowing is a progressive enhancement, not a hard prerequisite.
- */
-type KickJsPluginName = keyof KickJsPluginRegistry extends never ? string : keyof KickJsPluginRegistry & string;
-/**
- * Metadata attached to a `defineAugmentation` call. The fields are
- * documentation-only — `kick typegen` surfaces them in the generated
- * `.kickjs/types/augmentations.d.ts` so adopters can browse every
- * augmentable interface from one place.
- *
- * `description` and `example` may both be multi-line — typegen preserves
- * line breaks when rendering them as JSDoc. There is no upper limit on
- * the example size; entire shape definitions or worked snippets are fine.
- */
-interface AugmentationMeta {
-  /**
-   * Free-form description of what the augmentation customises. May be
-   * multi-line — newlines are preserved in the generated JSDoc.
-   */
-  description?: string;
-  /**
-   * TS snippet showing a typical shape. May be multi-line; rendered
-   * inside a fenced code block in the generated catalogue. Use this
-   * for anything from `'{ foo: string }'` up to a full interface body
-   * — typegen no longer flattens newlines.
-   */
-  example?: string;
-}
-/**
- * Advertise an augmentable interface so `kick typegen` can list it in
- * `.kickjs/types/augmentations.d.ts` for project-wide discovery.
- *
- * **This function is a runtime AND type-level no-op.** It does NOT
- * augment the interface for TypeScript. The actual augmentation is
- * the `declare module` block — `defineAugmentation` only adds an
- * entry to the typegen catalogue so other contributors / adopters
- * can find the interface and know its expected shape.
- *
- * Both calls are needed:
- *
- * ```ts
- * import { defineAugmentation } from '@forinda/kickjs'
- *
- * // (1) The actual TS augmentation — what `ctx.get('tenant')` reads.
- * declare module '@forinda/kickjs' {
- *   interface ContextMeta {
- *     tenant: { id: string; name: string }
- *   }
- * }
- *
- * // (2) Catalogue entry — what `kick typegen` lists in
- * //     `.kickjs/types/augmentations.d.ts` for browseability.
- * defineAugmentation('ContextMeta', {
- *   description: 'Tenant resolved from x-tenant-id by TenantAdapter',
- *   example: `{
- *     tenant: {
- *       id: string
- *       name: string
- *       plan: 'free' | 'pro' | 'enterprise'
- *       featureFlags: Record<string, boolean>
- *     }
- *   }`,
- * })
- * ```
- *
- * Skip `defineAugmentation` if you don't care about the catalogue — the
- * `declare module` block alone is enough for runtime + type behaviour.
- *
- * @deprecated Low value in practice: it does nothing at runtime or at
- * the type level — the `declare module` block alone gives you the
- * augmentation, and the generated `.kickjs/types/kick__augmentations.d.ts`
- * catalogue it feeds is documentation-only. Prefer a plain
- * `declare module '@forinda/kickjs' { ... }` block and (optionally) a
- * JSDoc comment on your own interface. `defineAugmentation` and the
- * `kick/augmentations` typegen plugin will be removed in a future major.
- */
-declare function defineAugmentation(name: string, meta?: AugmentationMeta): void;
-//#endregion
-//#region src/core/adapter.d.ts
-/**
- * Where in the middleware pipeline an adapter's middleware should be inserted.
- *
- * - `beforeGlobal` — runs **before** any user-defined global middleware.
- *   Suitable for transport-level concerns (request tagging, low-level
- *   request rewriting). Fires on every request.
- * - `afterGlobal` — runs **after** global middleware, **before** module
- *   routes are matched. Default for most adapter middleware (auth pre-checks,
- *   tenant resolution, body shaping). Fires on every request.
- * - `beforeRoutes` — runs just before module routes are mounted. Functionally
- *   equivalent to `afterGlobal` for most cases; the explicit phase exists so
- *   adapters that *must* sit at the very end of the pre-route stack can
- *   declare intent. Fires on every request.
- * - `afterRoutes` — sits **after** module routes but **before** error
- *   handlers. **Fires only on fall-through** — when no route matched (404
- *   path) or a route handler called `next()` without ending the response.
- *   Controllers that respond with `ctx.json(...)` end the chain and skip
- *   this phase, so it is *not* a "post-response" hook. For per-response
- *   work (logging, metrics) use `res.on('finish', ...)` from inside an
- *   earlier-phase middleware instead.
- */
-type MiddlewarePhase = 'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes';
-/**
- * Path scope for an {@link AdapterMiddleware} entry. Mirrors what
- * Express's `app.use(path, handler)` accepts so adapters get the full
- * range without learning a new mini-language:
- *
- * - A `string` prefix — `'/api'` matches `/api`, `/api/v1`, `/api/v1/x`.
- * - A `RegExp` — `/^\/api\/v\d+/` matches `/api/v1`, `/api/v42`.
- * - An array of either — `['/api', '/admin']` matches either prefix;
- *   `['/api', /^\/internal\//]` mixes shapes.
- *
- * Omit to apply the middleware unconditionally (Express `app.use(handler)`).
- */
-type MiddlewarePath = string | RegExp | ReadonlyArray<string | RegExp>;
-/** A middleware entry contributed by an adapter */
-interface AdapterMiddleware {
-  /**
-   * Express handler: either a `RequestHandler` (`(req, res, next) => …`)
-   * or an `ErrorRequestHandler` (`(err, req, res, next) => …`).
-   * Express dispatches based on arity, so the same field accepts both
-   * without a discriminant.
-   */
-  handler: RequestHandler | ErrorRequestHandler;
-  /** Which phase to insert into (default: 'afterGlobal') */
-  phase?: MiddlewarePhase;
-  /**
-   * Optional path scope. See {@link MiddlewarePath} for the accepted
-   * shapes (string prefix, RegExp, or an array mixing both). Omit to
-   * apply the middleware to every request that reaches this phase.
-   */
-  path?: MiddlewarePath;
-}
-/**
- * Context passed to adapter lifecycle hooks.
- * Populated by the Application — provides access to the Express app,
- * DI container, http.Server, and environment info without requiring
- * external type imports. Cast `app` or `server` if you need specific types.
- *
- * @example
- * ```ts
- * beforeMount({ app, container }: AdapterContext) {
- *   app.use(myMiddleware())
- * }
- * ```
- */
-interface AdapterContext {
-  /** Express application instance — fully typed */
-  app: Express;
-  /** DI container */
-  container: Container;
-  /** Node.js http.Server — only available in afterStart */
-  server?: http.Server;
-  /** Current NODE_ENV value (default: 'development') */
-  env: string;
-  /** true when NODE_ENV === 'production' */
-  isProduction: boolean;
-}
-/**
- * Adapters plug into the Application lifecycle.
- * Implement this to add WebSocket, database, rate limiting, docs, etc.
- *
- * All hooks receive an `AdapterContext` populated by the framework.
- * No external type imports needed — the context is fully typed from KickJS internals.
- *
- * @example
- * ```ts
- * import type { AppAdapter, AdapterContext } from '@forinda/kickjs/adapter'
- *
- * class SentryAdapter implements AppAdapter {
- *   name = 'SentryAdapter'
- *
- *   beforeMount({ app, container }: AdapterContext) {
- *     app.use(Sentry.expressRequestHandler())
- *   }
- *
- *   afterStart({ server }: AdapterContext) {
- *     // server is the http.Server — available after listen()
- *   }
- *
- *   async shutdown() {
- *     await Sentry.close(2000)
- *   }
- * }
- * ```
- */
-interface AppAdapter {
-  /**
-   * Human-readable name for logging and `dependsOn` resolution.
-   * Required when the adapter (or any other in the same set) declares
-   * `dependsOn` — sort errors will reference adapters by name.
-   */
-  name?: string;
-  /**
-   * Other adapter names that must mount before this one. The framework
-   * topologically sorts adapters at boot — cycles or unknown names throw
-   * via `MountCycleError` / `MissingMountDepError` so bad configurations
-   * fail boot rather than corrupt live traffic.
-   *
-   * Common pattern: `TenantAdapter` populates `req.tenant` and
-   * `AuthAdapter` reads it for tenant-scoped RBAC, so AuthAdapter
-   * declares `dependsOn = ['TenantAdapter']`. Adapters without
-   * `dependsOn` retain their declaration order.
-   *
-   * @example
-   * ```ts
-   * class AuthAdapter implements AppAdapter {
-   *   name = 'AuthAdapter'
-   *   dependsOn = ['TenantAdapter']
-   * }
-   * ```
-   */
-  dependsOn?: readonly KickJsPluginName[];
-  /**
-   * Return middleware entries to be inserted into the pipeline.
-   * The `phase` controls ordering relative to global middleware and routes.
-   */
-  middleware?(): AdapterMiddleware[];
-  /**
-   * Return Context Contributors (#107) that apply to every route in the
-   * application. Adapter-level contributors merge into the per-route
-   * pipeline at the `'adapter'` precedence level — they win over global
-   * contributors but lose to module, class, and method decorators.
-   *
-   * Useful for cross-cutting concerns: an auth adapter contributing
-   * `user`, a multi-tenant adapter contributing `tenant`, etc. Optional.
-   */
-  contributors?(): ContributorRegistrations;
-  /**
-   * Called before global middleware — register early routes (docs UI, health).
-   * May return a Promise — async rejections are caught and logged.
-   */
-  beforeMount?(ctx: AdapterContext): void | Promise<void>;
-  /**
-   * Called for each module route that gets mounted.
-   * Use this to collect route metadata (e.g. for OpenAPI spec generation).
-   */
-  onRouteMount?(controllerClass: Constructor, mountPath: string): void;
-  /**
-   * Called after modules are registered and the DI container is bootstrapped,
-   * before the HTTP server starts listening. **This is the correct hook for
-   * adapters that register DI bindings, resolve services, or otherwise prepare
-   * container-side state** (e.g. `container.registerInstance(MAILER, ...)`).
-   *
-   * `beforeStart` runs inside `app.setup()`, which means it also fires under
-   * `createTestApp` — adapters using this hook work in unit tests without
-   * needing a live HTTP server. See {@link afterStart} for the contrast.
-   *
-   * May return a Promise — async rejections are caught and logged.
-   */
-  beforeStart?(ctx: AdapterContext): void | Promise<void>;
-  /**
-   * Called after the HTTP server is listening — `ctx.server` is the live
-   * `http.Server`. **Use this hook only for work that genuinely needs a
-   * listening server**: attaching Socket.IO / WS upgrades, reading the bound
-   * port via `server.address()`, dispatching to the local server over HTTP,
-   * etc.
-   *
-   * `afterStart` does NOT fire under `createTestApp`, since tests call
-   * `app.setup()` and never `app.start()`. If your adapter only registers DI
-   * bindings or resolves services, use {@link beforeStart} — that hook runs
-   * in both production (`start()`) and tests (`setup()`).
-   *
-   * May return a Promise — async rejections are caught and logged.
-   */
-  afterStart?(ctx: AdapterContext): void | Promise<void>;
-  /**
-   * Called by the /health/ready endpoint. Return the health status of your adapter's
-   * backing service (database, Redis, queue, etc.).
-   */
-  onHealthCheck?(): Promise<{
-    name: string;
-    status: 'up' | 'down';
-  }>;
-  /** Called on shutdown — clean up connections */
-  shutdown?(): MaybePromise;
-  /**
-   * Optional DevTools introspection hook (architecture.md §23). Returns
-   * a snapshot describing this adapter's current state, metrics, and DI
-   * tokens. DevTools awaits the result, so async work is fine — but keep
-   * the implementation cheap (counters + flags, no DB round trips) since
-   * the topology endpoint polls on a short interval.
-   *
-   * The return type lives in `@forinda/kickjs` itself ({@link IntrospectionSnapshot})
-   * so adopters can author `introspect()` without importing the kit just
-   * to satisfy the contract. The kit's own `IntrospectionSnapshot` type
-   * stays structurally identical; either import works.
-   */
-  introspect?(): IntrospectionSnapshot | Promise<IntrospectionSnapshot>;
-  /**
-   * Optional DevTools tabs this adapter contributes (architecture.md §23).
-   * Returns an array of `DevtoolsTabDescriptor` shapes — typically one
-   * entry per adapter-owned panel (iframe / launch / html view).
-   *
-   * Same untyped-at-this-layer convention as {@link introspect}: adapter
-   * authors import `defineDevtoolsTab` (or the bare type) from
-   * `@forinda/kickjs-devtools-kit` so `@forinda/kickjs` doesn't take on
-   * a runtime dep on the kit.
-   */
-  devtoolsTabs?(): readonly unknown[];
-}
-/** Constructor type for AppAdapter classes */
-type AppAdapterClass = new () => AppAdapter;
-//#endregion
-export { MiddlewarePath as a, KickJsPluginName as c, IntrospectFn as d, IntrospectionKind as f, AppAdapterClass as i, KickJsPluginRegistry as l, AdapterMiddleware as n, MiddlewarePhase as o, IntrospectionSnapshot as p, AppAdapter as r, AugmentationMeta as s, AdapterContext as t, defineAugmentation as u };
-//# sourceMappingURL=adapter-CkpcZwzZ.d.mts.map

package/dist/adapter-CkpcZwzZ.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter-CkpcZwzZ.d.mts","names":[],"sources":["../src/core/introspect.ts","../src/core/augmentation.ts","../src/core/adapter.ts"],"mappings":";;;;;;;;;;;;;;;AAkBA;;;;;;;;;;;UAAiB,qBAAA;EAgBf;;;;;;;;;EANA,eAAA;EAoBW;EAlBX,IAAA;EA2B2B;EAzB3B,IAAA,EAAM,iBAAA;EAyBqB;EAvB3B,OAAA;EA8BU;;;;EAzBV,KAAA,GAAQ,MAAA;EAyB+C;EAvBvD,MAAA;IAAW,QAAA;IAA6B,QAAA;EAAA;EAuBuB;;AAAqB;;EAlBpF,OAAA,GAAU,MAAA;;EAEV,WAAA;AAAA;;;AC3BmC;AAUrC;;;KD0BY,iBAAA;ACxBkB;AAY9B;;;;AAZ8B,KD+BlB,YAAA,SAAqB,qBAAA,GAAwB,OAAA,CAAQ,qBAAA;;;;;;;;;;AA9CjE;;;;;;;;;;;;;UCGiB,oBAAA;;;;;;;;AD2BJ;KCjBD,gBAAA,SAAyB,oBAAA,gCAE3B,oBAAoB;;;;ADwBD;AAO7B;;;;;;UCnBiB,gBAAA;EDmB+C;;;;ECd9D,WAAA;EDcoF;;;;AC3CtF;;EAoCE,OAAO;AAAA;AApC4B;AAUrC;;;;AAE8B;AAY9B;;;;AAYS;AAmDT;;;;;;;;AAAwE;;;;AC/ExE;;;;AAA2B;AAc3B;;;;;;;;;;;;AAA4E;AAG5E;;;;;;;ADzBqC,iBAuFrB,kBAAA,CAAmB,IAAA,UAAc,IAAA,GAAO,gBAAgB;;;AD1FxE;;;;;;;;;;;;;;;;;;;;;AAAA,KEWY,eAAA;AFmBC;AASb;;;;AAA6B;AAO7B;;;;;;AAhBa,KELD,cAAA,YAA0B,MAAA,GAAS,aAAA,UAAuB,MAAA;;UAGrD,iBAAA;EFkBwC;;;AAA6B;;;EEXpF,OAAA,EAAS,cAAA,GAAiB,mBAAA;EDhCX;ECkCf,KAAA,GAAQ,eAAA;;;ADlC2B;AAUrC;;EC8BE,IAAA,GAAO,cAAA;AAAA;AD5BqB;AAY9B;;;;AAYS;AAmDT;;;;;;;AA3E8B,UC4Cb,cAAA;ED+BuD;EC7BtE,GAAA,EAAK,OAAA;;EAEL,SAAA,EAAW,SAAA;EApDD;EAsDV,MAAA,GAAS,IAAA,CAAK,MAAA;;EAEd,GAAA;EAxDyB;EA0DzB,YAAA;AAAA;;;;;;;;;;;AA5C0E;AAG5E;;;;;;;;;;;;;;;;;UAwEiB,UAAA;EAzCA;;;;;EA+Cf,IAAA;EAzCoB;;;;;;;;;;;;AAIR;AA+Bd;;;;;;EA2BE,SAAA,YAAqB,gBAAA;EAuBqB;;;;EAjB1C,UAAA,KAAe,iBAAA;EAqD0B;;;;;;;;;EA1CzC,YAAA,KAAiB,wBAAA;EAjBI;;;;EAuBrB,WAAA,EAAa,GAAA,EAAK,cAAA,UAAwB,OAAA;EAA1C;;;;EAMA,YAAA,EAAc,eAAA,EAAiB,WAAA,EAAa,SAAA;EAAb;;;;;;;;;;;;EAc/B,WAAA,EAAa,GAAA,EAAK,cAAA,UAAwB,OAAA;EAsBd;;;;;;;;;;AA6BhB;AAId;;;EAvCE,UAAA,EAAY,GAAA,EAAK,cAAA,UAAwB,OAAA;EAuCO;;;;EAjChD,aAAA,KAAkB,OAAA;IAAU,IAAA;IAAc,MAAA;EAAA;;EAG1C,QAAA,KAAa,YAAA;;;;;;;;;;;;;EAcb,UAAA,KAAe,qBAAA,GAAwB,OAAA,CAAQ,qBAAA;;;;;;;;;;;EAY/C,YAAA;AAAA;;KAIU,eAAA,aAA4B,UAAU"}