@forinda/kickjs 8.2.1 → 8.3.1

package/dist/{spa-DXTOhkVK.d.mts → application-BeVzWyTq.d.mts}

@@ -1,23 +1,22 @@
 
 import { s as InjectionToken, t as Container } from "./container-Dpvd66Yt.mjs";
 import "./index-Btz1W0X5.mjs";
-import { d as RouteFlags } from "./route-flag-C6VJQ2el.mjs";
-import { C as MetaValue, c as ContextDecorator, h as DepValue, u as ContextDecoratorSpec, x as ContextMetaKey } from "./app-module-DyqiS9rQ.mjs";
-import { A as AdapterFactory, E as RequestContext, f as HttpRuntime, h as RouteEntry, nt as ModuleFactory } from "./adapter-CvHtIu8A.mjs";
-import "./application-DIxWiYOw.mjs";
-import "./bootstrap-DCUWJRmN.mjs";
-import "./cors-CsibNTQ6.mjs";
-import "./csrf-HVVOHlf8.mjs";
-import "./error-handler-DVAcTt8p.mjs";
-import "./helmet-C2QEU6S-.mjs";
-import "./rate-limit-BJc724GS.mjs";
+import { p as RouteFlags, s as RouteFlagDeclarations } from "./route-flag-BMlwj3Nk.mjs";
+import { C as MetaValue, c as ContextDecorator, h as DepValue, m as ContributorRegistrations, r as AppModuleEntry, u as ContextDecoratorSpec, x as ContextMetaKey } from "./app-module--bC2V1yw.mjs";
+import { A as AdapterFactory, E as RequestContext, b as RuntimeCapabilities, f as HttpRuntime, h as RouteEntry, lt as KickPlugin, nt as ModuleFactory, r as AppAdapter, s as ActiveRuntime, ut as ModuleRegistry, x as RuntimeResponse } from "./adapter-Duqrig18.mjs";
+import { l as Reply } from "./kv-stores-BICLX1Yy.mjs";
+import { t as BuildRoutesOptions } from "./router-builder-CGOQIi4T.mjs";
 import "./request-id-CVzJ1uHD.mjs";
-import "./session-BHgRyfqZ.mjs";
-import { l as Reply } from "./kv-stores-D_anc94e.mjs";
-import { t as BuildRoutesOptions } from "./router-builder-CxRFEM9j.mjs";
 import "./validate-DMYpUnrf.mjs";
-import "./upload-ysRl6aKu.mjs";
-import { Express, NextFunction, Request, Response, Router } from "express";
+import "./error-handler-BOT8vAPx.mjs";
+import "./csrf-DDwUOF45.mjs";
+import "./helmet-C2QEU6S-.mjs";
+import "./cors-CsibNTQ6.mjs";
+import "./rate-limit-D5FHbYKG.mjs";
+import "./session-BHgRyfqZ.mjs";
+import "./upload-B63Ayql7.mjs";
+import http from "node:http";
+import { Express, NextFunction, Request, RequestHandler, Response, Router } from "express";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/core/disposables.d.ts
 /**
@@ -414,62 +413,28 @@ declare function bindRoutePolicy<T extends object>(handler: T, receive: (table:
 /** Hand the table to a middleware if it declared the slot. */
 declare function offerRoutePolicy(handler: unknown, table: RoutePolicyTable): void;
 //#endregion
-//#region src/http/health-module.d.ts
-/** One adapter's answer to `onHealthCheck()`. */
-interface HealthCheckResult {
-  name: string;
-  status: 'up' | 'down';
-}
+//#region src/http/bootstrap.d.ts
 /**
- * What the health routes need from the running Application.
+ * Bootstrap a KickJS application.
  *
- * A controller cannot reach `Application` internals, and should not: this is
- * the whole surface the endpoints depend on, so a replacement module can
- * satisfy it without knowing anything else.
- */
-interface HealthProbe {
-  /** True once shutdown has begun and traffic should drain away. */
-  isDraining(): boolean;
-  /** Aggregated `onHealthCheck()` results from every adapter that has one. */
-  checks(): Promise<HealthCheckResult[]>;
-}
-declare const HEALTH_PROBE: InjectionToken<HealthProbe>;
-declare class HealthController {
-  private readonly probe;
-  constructor(probe: HealthProbe);
-  /** Liveness: is the process up and not shutting down. */
-  live(): Reply<200, {
-    status: string;
-    uptime: number;
-  }> | Reply<503, {
-    status: string;
-    uptime: number;
-  }>;
-  /** Readiness: is every adapter's dependency answering. */
-  ready(): Promise<Reply<200 | 503, {
-    status: string;
-    checks: HealthCheckResult[];
-  }>>;
-}
-/**
- * `GET /health/live` and `GET /health/ready`, mounted at the root.
+ * Creates the Express app, registers modules and adapters, and starts
+ * the HTTP server. In dev mode (`kick dev`), the Vite plugin manages
+ * the server and HMR — source changes are picked up instantly without
+ * losing database connections or WebSocket state.
  *
- * A `defineModule` factory like any other module — the framework's own routes
- * should be declared the way it asks adopters to declare theirs, not through a
- * shape only the framework can produce.
+ * @returns The {@link Application} instance.
  *
- * Registered automatically unless the app passes `health: false` or supplies a
- * module of its own.
- */
-declare const healthModule: ModuleFactory<Record<string, unknown>, {
-  register(container: Container): void;
-  routes(): {
-    path: string;
-    controller: typeof HealthController;
-    version: false;
-    prefix: false;
-  };
-}>;
+ * @example
+ * ```ts
+ * // src/index.ts
+ * import 'reflect-metadata'
+ * import { bootstrap } from '@forinda/kickjs'
+ * import { modules } from './modules'
+ *
+ * export const app = await bootstrap({ modules })
+ * ```
+ */
+declare function bootstrap(options: ApplicationOptions): Promise<Application>;
 //#endregion
 //#region src/http/cluster.d.ts
 interface ClusterOptions {
@@ -864,5 +829,569 @@ declare function resolveClientDir(clientDir: string, cwd?: string, entry?: strin
  */
 declare const SpaAdapter: AdapterFactory<SpaAdapterOptions, unknown>;
 //#endregion
-export { KickErrorInit as $, AssetKeyPair as A, MountSortItem as B, HealthCheckResult as C, RoutePolicyTable as D, healthModule as E, stripExt as F, MissingContributorError as G, ContributorCycleError as H, DuplicateMountNameError as I, CircuitBreakerState as J, CircuitBreaker as K, MissingMountDepError as L, GroupAssetKeysOptions as M, GroupAssetKeysResult as N, bindRoutePolicy as O, groupAssetKeys as P, KickError as Q, MountCycleError as R, HEALTH_PROBE as S, HealthProbe as T, DuplicateContributorError as U, mountSort as V, MissingContextValueError as W, CircuitOpenError as X, CircuitBreakerStats as Y, FormatKickErrorOptions as Z, expressRuntime as _, ViewAdapterOptions as a, ClusterOptions as b, TraceContextOptions as c, requestScopeMiddleware as d, formatKickError as et, RequestStore as f, buildRoutes as g, requestStore as h, ViewAdapter as i, AssetKeyStrategy as j, offerRoutePolicy as k, parseTraceparent as l, getRequestValue as m, SpaAdapterOptions as n, disposeAll as nt, TRACEPARENT_HEADER as o, getRequestStore as p, CircuitBreakerOptions as q, resolveClientDir as r, registerDisposable as rt, TraceContext as s, SpaAdapter as t, Disposable as tt, traceContext as u, materializeRouter as v, HealthController as w, isClusterPrimary as x, defineHttpContextDecorator as y, MountKind as z };
-//# sourceMappingURL=spa-DXTOhkVK.d.mts.map
+//#region src/http/health-module.d.ts
+/** One adapter's answer to `onHealthCheck()`. */
+interface HealthCheckResult {
+  name: string;
+  status: 'up' | 'down';
+}
+/**
+ * What the health routes need from the running Application.
+ *
+ * A controller cannot reach `Application` internals, and should not: this is
+ * the whole surface the endpoints depend on, so a replacement module can
+ * satisfy it without knowing anything else.
+ */
+interface HealthProbe {
+  /** True once shutdown has begun and traffic should drain away. */
+  isDraining(): boolean;
+  /** Aggregated `onHealthCheck()` results from every adapter that has one. */
+  checks(): Promise<HealthCheckResult[]>;
+}
+declare const HEALTH_PROBE: InjectionToken<HealthProbe>;
+/** Config for {@link healthModule}. */
+interface HealthModuleConfig {
+  /**
+   * Route flags to put on `GET /health/live` and `GET /health/ready`.
+   *
+   * The framework names no flags, so it cannot decide these probes are
+   * "public" on your behalf — the name is yours, and every consumer that
+   * already reads it (an auth contributor's `skipWhen`, a guard's
+   * `exemptWhen`, `SwaggerAdapter({ publicFlag })`) then covers health with no
+   * further wiring:
+   *
+   * ```ts
+   * bootstrap({ health: { flags: ['auth.public'] } })
+   * ```
+   *
+   * This replaces exempting `/health/live` and `/health/ready` by pathname,
+   * which silently stops matching if the probe paths ever move.
+   */
+  flags?: RouteFlagDeclarations;
+}
+declare class HealthController {
+  private readonly probe;
+  constructor(probe: HealthProbe);
+  /** Liveness: is the process up and not shutting down. */
+  live(): Reply<200, {
+    status: string;
+    uptime: number;
+  }> | Reply<503, {
+    status: string;
+    uptime: number;
+  }>;
+  /** Readiness: is every adapter's dependency answering. */
+  ready(): Promise<Reply<200 | 503, {
+    status: string;
+    checks: HealthCheckResult[];
+  }>>;
+}
+/**
+ * `GET /health/live` and `GET /health/ready`, mounted at the root.
+ *
+ * A `defineModule` factory like any other module — the framework's own routes
+ * should be declared the way it asks adopters to declare theirs, not through a
+ * shape only the framework can produce.
+ *
+ * Registered automatically unless the app passes `health: false` or supplies a
+ * module of its own. Pass `health: { flags: [...] }` to `bootstrap()` to flag
+ * both probes — see {@link HealthModuleConfig}.
+ */
+declare const healthModule: ModuleFactory<HealthModuleConfig, unknown>;
+//#endregion
+//#region src/http/application.d.ts
+/**
+ * A middleware entry in the declarative pipeline.
+ * Can be a bare handler or an object with path scoping.
+ */
+type MiddlewareEntry = RequestHandler | {
+  path: string;
+  handler: RequestHandler;
+};
+/** Options for {@link Application.shutdown}. */
+interface ShutdownOptions {
+  /**
+   * Close the HTTP server and drain in-flight requests. Default `true`.
+   *
+   * Set `false` for a dev HMR rebuild, where the server is shared across
+   * reloads — adapters, plugins, and disposables are still torn down, which is
+   * the part a reload needs.
+   */
+  closeServer?: boolean;
+}
+interface ApplicationOptions {
+  /**
+   * Feature modules to load. Accepts both class form
+   * (`SomeModule extends AppModule`, instantiated via `new`) and
+   * instance form (output of {@link defineModule}'s factory call,
+   * e.g. `TasksModule({ scope: 'admin' })`) — the loader discriminates
+   * and either `new`-s the class or uses the instance directly.
+   *
+   * Static path — for conditional / dynamic registration, use the
+   * {@link ApplicationOptions.setup} callback instead.
+   */
+  modules: AppModuleEntry[];
+  /**
+   * Imperative module registration callback. Receives a
+   * {@link ModuleRegistry} you call `.mount(module)` on to register
+   * modules conditionally — based on env flags, runtime config, a
+   * tenant list, etc. Runs after every plugin's `setup()` hook and
+   * after the static `modules: [...]` array is collected.
+   *
+   * @example
+   * ```ts
+   * bootstrap({
+   *   modules: [HelloModule()],
+   *   setup(registry) {
+   *     if (env.ENABLE_ADMIN) registry.mount(AdminModule())
+   *   },
+   * })
+   * ```
+   */
+  setup?(registry: ModuleRegistry): void;
+  /** Adapters that hook into the lifecycle (DB, Redis, Swagger, etc.) */
+  adapters?: AppAdapter[];
+  /** Server port (falls back to PORT env var, then 3000) */
+  port?: number;
+  /** Global API prefix (default: '/api'). Pass `''` to mount at the root. */
+  apiPrefix?: string;
+  /**
+   * Default API version (default: 1) — routes become /{prefix}/v{version}/{path}.
+   *
+   * `false` opts out of URL versioning: routes mount at /{prefix}/{path}.
+   * A module can still version itself by setting `version` on its
+   * `ModuleRoutes` — the per-mount value always wins over this default, in
+   * either direction.
+   */
+  defaultVersion?: number | false;
+  /**
+   * Global middleware pipeline. Declared in order.
+   * Replaces the hardcoded middleware stack — you control exactly what runs.
+   *
+   * @example
+   * ```ts
+   * bootstrap({
+   *   modules,
+   *   middlewares: [
+   *     helmet(),
+   *     cors(),
+   *     compression(),
+   *     morgan('dev'),
+   *     express.json({ limit: '1mb' }),
+   *   ],
+   * })
+   * ```
+   *
+   * If omitted, a sensible default is applied:
+   *   requestId(), express.json({ limit: '100kb' })
+   */
+  middlewares?: MiddlewareEntry[];
+  /** Plugins that bundle modules, adapters, middleware, and DI bindings */
+  plugins?: KickPlugin[];
+  /**
+   * Global Context Contributors (#107) that apply to every route in the
+   * application. Merge into the per-route pipeline at the `'global'`
+   * precedence level — they lose to module, adapter, class, and method
+   * contributors with the same key, providing app-wide defaults that any
+   * narrower scope can override.
+   *
+   * @example
+   * ```ts
+   * const StartedAt = defineContextDecorator({
+   *   key: 'requestStartedAt',
+   *   resolve: () => Date.now(),
+   * })
+   *
+   * bootstrap({
+   *   modules,
+   *   contributors: [StartedAt.registration],
+   * })
+   * ```
+   */
+  contributors?: ContributorRegistrations;
+  /**
+   * Backing store strategy for {@link RequestContext} `set/get` and the
+   * Context Contributor pipeline (#107).
+   *
+   * - `'auto'` (default) — Application mounts {@link requestScopeMiddleware}
+   *   automatically before any user middleware. If the user-supplied
+   *   `middleware` list already includes `requestScopeMiddleware()`,
+   *   detection skips the auto-mount so adopters can control its position.
+   * - `'manual'` — Application never mounts the wrapper. The Context
+   *   Contributor pipeline still runs on every route — the runner is
+   *   inserted by `router-builder` regardless of ALS state. What
+   *   degrades without an ALS frame is the *backing store*:
+   *   REQUEST-scoped DI throws (no `requestStore.getStore()` to read
+   *   from) and `RequestContext.set/get` throws. Use `'manual'` only when you
+   *   genuinely intend to wrap requests in your own ALS frame (rare —
+   *   multi-tenant adapters used to do this; post-Phase 3 they share
+   *   the framework's frame instead).
+   */
+  contextStore?: 'auto' | 'manual';
+  /**
+   * Controls whether KickJS registers process-level handlers at bootstrap.
+   *
+   * - `'auto'` (default) — register `uncaughtException` /
+   *   `unhandledRejection` loggers AND `SIGINT` / `SIGTERM` →
+   *   `app.shutdown()` → `process.exit(0)`.
+   * - `'errors-only'` — register the error loggers; skip the signal
+   *   handlers. Use this when you have your own shutdown choreographer
+   *   (OpenTelemetry SDK, Sentry, custom orchestrator) that calls
+   *   `app.shutdown()` itself and you don't want two listeners racing
+   *   to call `process.exit`.
+   * - `'manual'` — skip everything. Adopter is responsible for both
+   *   error logging and signal-driven shutdown.
+   *
+   * Background: many observability SDKs install their own SIGTERM
+   * handler to flush spans/metrics before the process exits. Two
+   * separate handlers calling `process.exit(0)` race each other and
+   * can truncate the in-flight flush. Setting this to `'errors-only'`
+   * or `'manual'` lets the SDK own the lifecycle while still letting
+   * KickJS surface uncaught exceptions / rejections via the logger.
+   *
+   * The dev mode auto-detect (`__kickjs_httpServer` set by the Vite
+   * plugin) suppresses signal registration regardless of this option,
+   * since Vite owns the lifecycle in development.
+   */
+  processHooks?: 'auto' | 'errors-only' | 'manual';
+  /**
+   * The HTTP engine driver. Defaults to {@link expressRuntime} — Express stays
+   * the zero-config default, so existing apps are unaffected.
+   *
+   * Any `HttpRuntime` is accepted — pass `fastifyRuntime()` (from
+   * `@forinda/kickjs/fastify`) or a custom engine driver. Defaults to
+   * {@link expressRuntime}. The engine-native escape hatches
+   * (`getRuntimeApp()`, `AdapterContext.app`) follow the active runtime via the
+   * registry (`ActiveRuntime`, spec §4.3b) — Express by default, or the augmented
+   * engine once the `kick/runtime` typegen output is present.
+   */
+  /**
+   * Mount the built-in `GET /health/live` and `GET /health/ready`.
+   *
+   * On by default. Set `false` to take them over completely — supply your own
+   * module at `/health` and nothing collides. The built-in is registered last,
+   * so an app module claiming the same path already wins without this.
+   *
+   * They mount as an ordinary module, which means they sit inside the
+   * middleware chain: whatever guards the rest of the app guards these too.
+   * Pass `{ flags: [...] }` to put your own route flags on both probes — the
+   * way to make them reachable unauthenticated without exempting a pathname
+   * that can move:
+   *
+   * ```ts
+   * bootstrap({ health: { flags: ['auth.public'] } })
+   * ```
+   */
+  health?: boolean | HealthModuleConfig;
+  runtime?: HttpRuntime;
+  /** Express `trust proxy` setting */
+  trustProxy?: boolean | number | string | ((ip: string, hopIndex: number) => boolean);
+  /** Maximum JSON body size (only used when middleware is not provided) */
+  jsonLimit?: string | number;
+  /**
+   * Print the route table on startup. Default: `false`. Set to `true`
+   * to log a per-controller summary (method counts + mount paths) once
+   * the app has mounted. Emitted at `info` level, so it is still subject
+   * to `LOG_LEVEL` filtering (visible at the default `info`; hidden at
+   * `warn`/`error`/`silent`).
+   */
+  logRouteTable?: boolean;
+  /**
+   * @deprecated Use {@link ApplicationOptions.logRouteTable}. Kept as an
+   * alias for back-compat; `logRouteTable` wins when both are set.
+   */
+  logRoutesTable?: boolean;
+  /**
+   * Maximum time (ms) to wait for graceful shutdown before forcing exit.
+   * Default: 30000 (30 seconds). Set to 0 to disable forced exit.
+   */
+  shutdownTimeout?: number;
+  /**
+   * Enable cluster mode for multi-core utilization.
+   *
+   * When enabled, the primary process forks worker processes that share the
+   * same port via Node's built-in `cluster` module (OS load balancing).
+   *
+   * - `true` — use all available CPU cores
+   * - `{ workers: N }` — use exactly N workers
+   *
+   * Workers are auto-restarted on crash. SIGTERM/SIGINT on the primary is
+   * forwarded to all workers.
+   *
+   * @example
+   * ```ts
+   * bootstrap({ modules, cluster: true })
+   * bootstrap({ modules, cluster: { workers: 4 } })
+   * ```
+   */
+  cluster?: boolean | {
+    workers?: number;
+  };
+  /**
+   * Custom 404 handler for unmatched routes. When omitted, the built-in
+   * handler returns `{ message: 'Not Found' }` with status 404.
+   *
+   * Connect-**shaped**, not Express-**semantic** — see {@link onError} for the
+   * per-runtime table. The same two caveats apply: `next()` is inert on
+   * Fastify and h3, and Express-only request members (`req.originalUrl`,
+   * `req.path`, `req.ip`) are `undefined` there, so read `req.url`.
+   *
+   * @example
+   * ```ts
+   * bootstrap({
+   *   modules,
+   *   onNotFound: (req, res) => {
+   *     // `req.originalUrl` is Express-only — use `req.url` for portability.
+   *     res.status(404).json({ error: 'Route not found', path: req.url })
+   *   },
+   * })
+   * ```
+   */
+  onNotFound?: (req: any, res: RuntimeResponse, next: (err?: unknown) => void) => void;
+  /**
+   * Custom global error handler, receiving `(err, req, res, next)`. When
+   * omitted, the built-in handler formats ZodError, HttpException, and
+   * unexpected errors.
+   *
+   * The shape is connect-style, but it is NOT "the standard Express error
+   * handler" on every engine — what you actually receive differs, and the
+   * differences bite:
+   *
+   * | | `req` | `res` | `next` |
+   * | --- | --- | --- | --- |
+   * | Express | native `Request` | native `Response` | real `next` |
+   * | Fastify | `request.raw` | reply driver | **no-op** |
+   * | h3 | `event.node.req` | response driver | no-op (or dev fall-through) |
+   *
+   * Two consequences worth knowing before you write one:
+   *
+   * - **`next(err)` does nothing on Fastify and h3.** It is a no-op function
+   *   there, so delegating to the default handler silently drops the error.
+   *   Send a response yourself rather than passing it on.
+   * - **Express-only request members are `undefined` elsewhere.**
+   *   `req.originalUrl`, `req.path`, and `req.ip` do not exist on the raw node
+   *   request — use `req.url` and the `x-forwarded-*` headers, or reach for
+   *   `ctx.ip` in a contributor / guard where a `RequestContext` is available.
+   *
+   * `res` is typed {@link RuntimeResponse} because that is what every engine
+   * genuinely provides: `status`, `json`, `send`, `setHeader`, `render`,
+   * `writeHead`, `end`. Express's own `Response` satisfies it.
+   *
+   * @example
+   * ```ts
+   * bootstrap({
+   *   modules,
+   *   onError: (err, req, res) => {
+   *     logger.error(err, `${req.method} ${req.url}`) // not `originalUrl`
+   *     res.status(err.status ?? 500).json({ error: err.message })
+   *   },
+   * })
+   * ```
+   */
+  onError?: (err: any, req: any, res: RuntimeResponse, next: (err?: unknown) => void) => void;
+  /**
+   * Security defaults applied automatically unless opted out.
+   *
+   * When not specified, secure defaults are applied:
+   * - Helmet security headers are auto-injected
+   * - JSON body limit defaults to 1MB
+   *
+   * @example
+   * ```ts
+   * bootstrap({
+   *   modules,
+   *   security: {
+   *     helmet: false,     // disable auto-helmet
+   *   },
+   * })
+   * ```
+   */
+  security?: {
+    /** Auto-inject helmet security headers. Default: true */
+    helmet?: boolean;
+  };
+}
+declare class Application {
+  private readonly options;
+  private app;
+  /** The HTTP engine driver. Defaults to {@link expressRuntime}. */
+  private readonly runtime;
+  private container;
+  private httpServer;
+  private readonly adapters;
+  /**
+   * Flags of every mounted route, for middleware that runs before routing and
+   * therefore cannot read `ctx.route` (the connect-style rate limiter). Handed
+   * to middleware that declares the slot — see `core/route-policy.ts`.
+   */
+  private readonly routePolicy;
+  private readonly plugins;
+  /**
+   * Snapshot of every module-level Context Contributor registration
+   * captured during `setup()`. The registrations themselves are
+   * frozen by `defineContextDecorator`, so storing references is
+   * safe — they outlive the module instances they came from.
+   *
+   * Used by {@link getContributors} so DevTools and adopter tooling
+   * can render the module-level contributors alongside the adapter /
+   * plugin / global ones. Populated once per `setup()` call; cleared
+   * at the start of each invocation so a re-setup (test harnesses,
+   * dev-server restarts) doesn't accumulate stale entries.
+   */
+  private _moduleContributors;
+  /** Number of HTTP requests currently being processed */
+  private _inFlightRequests;
+  /** Whether the application is draining (shutting down gracefully) */
+  private _draining;
+  /** Whether shutdown has already been initiated (prevents double-shutdown) */
+  private _shutdownInitiated;
+  /** Resolvers waiting for in-flight requests to reach zero */
+  private _drainResolvers;
+  constructor(options: ApplicationOptions);
+  /** Whether the application is currently draining in-flight requests */
+  get isDraining(): boolean;
+  /** Number of HTTP requests currently being processed */
+  get inFlightRequests(): number;
+  /** Get the DI container instance */
+  getContainer(): Container;
+  /**
+   * Express request handler — delegates to the internal Express app.
+   *
+   * Used by the Vite dev-server plugin to route requests through KickJS:
+   * ```ts
+   * const mod = await ssrLoadModule('virtual:kickjs/app')
+   * mod.app.handle(req, res, next)
+   * ```
+   *
+   * Also works as a standard Node.js request handler for production:
+   * ```ts
+   * http.createServer(app.handle.bind(app))
+   * ```
+   */
+  handle(req: http.IncomingMessage, res: http.ServerResponse, next?: (err?: any) => void): void;
+  /**
+   * Full setup pipeline:
+   * 1. Adapter beforeMount hooks (early routes — e.g. docs UI)
+   * 2. Adapter middleware (phase: beforeGlobal)
+   * 3. Global middleware (user-declared or defaults)
+   * 4. Adapter middleware (phase: afterGlobal)
+   * 5. Module registration + DI bootstrap (the built-in health module mounts
+   *    here with everything else — it is NOT an early route)
+   * 6. Adapter middleware (phase: beforeRoutes)
+   * 7. Module route mounting
+   * 8. Adapter middleware (phase: afterRoutes)
+   * 9. Adapter beforeStart hooks
+   * 10. Error handlers (notFound + global)
+   */
+  /** Build the adapter context object (shared across all hooks) */
+  private adapterCtx;
+  /**
+   * The engine-agnostic HTTP surface handed to adapters as `ctx.http`. Each
+   * call routes through the active runtime over the current `this.app`, so an
+   * adapter written against this works under any runtime.
+   */
+  private adapterHttp;
+  /** Call an adapter hook, awaiting async hooks and catching errors */
+  private callHook;
+  setup(): Promise<void>;
+  /** Register modules and DI without starting the HTTP server (used by kick tinker) */
+  registerOnly(): Promise<void>;
+  /**
+   * Start the HTTP server.
+   *
+   * In **dev mode** (Vite plugin active): reuses `globalThis.__kickjs_httpServer`
+   * created by Vite. Adapters (WsAdapter, Socket.IO, etc.) receive the real
+   * `http.Server` through `afterStart({ server })` — zero adapter changes needed.
+   *
+   * In **production**: creates its own `http.Server` and binds to the port.
+   */
+  start(): Promise<void>;
+  /** HMR rebuild: swap Express handler without restarting the server */
+  rebuild(): Promise<void>;
+  /**
+   * Graceful shutdown with request draining.
+   *
+   * 1. Stops accepting new connections (server.close())
+   * 2. Waits for in-flight requests to complete (up to shutdownTimeout)
+   * 3. Calls adapter.shutdown() for all registered adapters
+   * 4. Force-closes after timeout
+   *
+   * Safe to call multiple times — subsequent calls return the same promise.
+   */
+  shutdown(options?: ShutdownOptions): Promise<void>;
+  /**
+   * The engine-native app instance, typed from the active runtime
+   * ({@link ActiveRuntime} — Express by default). Prefer this over
+   * {@link getExpressApp}; under a non-Express runtime the type follows the
+   * augmented registry.
+   */
+  getRuntimeApp(): ActiveRuntime['app'];
+  /**
+   * The active HTTP runtime's identity + capabilities — `name` is `'express'`
+   * (default), `'fastify'`, or `'h3'`; `capabilities` reports what the engine
+   * supports (render / uploads / connectMiddleware / nativeBodyParsing).
+   * Surfaced by DevTools and the VS Code extension so tooling can show which
+   * engine the app is running on. Cheap, side-effect free.
+   */
+  getActiveRuntime(): {
+    name: string;
+    capabilities: RuntimeCapabilities;
+  };
+  /** @deprecated Use {@link getRuntimeApp}. Returns the engine-native app. */
+  getExpressApp(): Express;
+  /** Get registered adapters — used by DevToolsAdapter for peer discovery */
+  getAdapters(): AppAdapter[];
+  /**
+   * Get registered plugins — used by DevToolsAdapter for topology
+   * introspection (architecture.md §23). Read-only; returns the
+   * already-sorted plugin list (post-`dependsOn` topo-sort).
+   */
+  getPlugins(): readonly KickPlugin[];
+  /**
+   * Snapshot of every Context Contributor reachable from this app —
+   * walks **four** registration sites: adapters, plugins, modules,
+   * and the bootstrap `contributors` option. The devtools Topology
+   * tab consumes this for the Contributors panel; tests + adopters
+   * can call it for diagnostics.
+   *
+   * Per-route (method/class-decorator) registrations are NOT included
+   * here — they live on the route registry rather than on any of
+   * the four collection sites this method walks. A future RPC will
+   * surface them separately.
+   *
+   * Result shape stays minimal — `{ key, source, label, dependsOn }`
+   * — so we don't leak `resolve` closures or other internal fields.
+   * `source` matches the five-level precedence union from
+   * `ContributorSource` (minus `'method'` / `'class'` which require
+   * the per-route walk noted above).
+   */
+  getContributors(): ReadonlyArray<{
+    key: string;
+    source: 'module' | 'adapter' | 'plugin' | 'global';
+    label: string;
+    dependsOn: readonly string[];
+  }>;
+  getHttpServer(): http.Server | null;
+  /**
+   * Decide whether {@link Application} should auto-mount the
+   * {@link requestScopeMiddleware} ALS wrapper.
+   *
+   * Returns `false` when:
+   * - `contextStore: 'manual'` was set (caller manages ALS frames), or
+   * - the user-supplied `middleware` list already includes a
+   *   `requestScopeMiddleware()` (detected via the symbol marker stamped
+   *   in `middleware/request-scope.ts`).
+   *
+   * Otherwise `true` — preserves the historical default of "always wrap
+   * requests in an ALS frame" so existing apps see no behavior change.
+   */
+  private shouldAutoMountRequestScope;
+  private collectAdapterMiddleware;
+  private mountMiddlewareList;
+  private mountMiddlewareEntry;
+  /** Middleware that tracks in-flight requests for graceful draining */
+  private requestTrackingMiddleware;
+}
+//#endregion
+export { CircuitBreakerOptions as $, ClusterOptions as A, groupAssetKeys as B, getRequestStore as C, expressRuntime as D, buildRoutes as E, offerRoutePolicy as F, MountKind as G, DuplicateMountNameError as H, AssetKeyPair as I, ContributorCycleError as J, MountSortItem as K, AssetKeyStrategy as L, bootstrap as M, RoutePolicyTable as N, materializeRouter as O, bindRoutePolicy as P, CircuitBreaker as Q, GroupAssetKeysOptions as R, RequestStore as S, requestStore as T, MissingMountDepError as U, stripExt as V, MountCycleError as W, MissingContextValueError as X, DuplicateContributorError as Y, MissingContributorError as Z, TraceContext as _, HEALTH_PROBE as a, KickErrorInit as at, traceContext as b, HealthModuleConfig as c, disposeAll as ct, SpaAdapter as d, CircuitBreakerState as et, SpaAdapterOptions as f, TRACEPARENT_HEADER as g, ViewAdapterOptions as h, ShutdownOptions as i, KickError as it, isClusterPrimary as j, defineHttpContextDecorator as k, HealthProbe as l, registerDisposable as lt, ViewAdapter as m, ApplicationOptions as n, CircuitOpenError as nt, HealthCheckResult as o, formatKickError as ot, resolveClientDir as p, mountSort as q, MiddlewareEntry as r, FormatKickErrorOptions as rt, HealthController as s, Disposable as st, Application as t, CircuitBreakerStats as tt, healthModule as u, TraceContextOptions as v, getRequestValue as w, requestScopeMiddleware as x, parseTraceparent as y, GroupAssetKeysResult as z };
+//# sourceMappingURL=application-BeVzWyTq.d.mts.map