@nwire/endpoint 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @nwire/endpoint
+
+> Process lifecycle — graceful shutdown, K8s probes, signal handling for any Node server.
+
+## What it is
+
+Wraps any Node server (Express, Fastify, Koa, Nest, Hono, raw `http`, or a Nwire interface) with the boring lifecycle every long-running process needs: `http-terminator` for draining keep-alive sockets, `lightship` for readiness/liveness probes on a dedicated port, signal handling, and ordered shutdown. The outermost layer of every Nwire entrypoint.
+
+## Install
+
+```bash
+pnpm add @nwire/endpoint
+```
+
+## Standalone use
+
+For developers who need real graceful shutdown around an Express/Fastify/Koa/Nest app without rewriting boot code. `endpoint().serve(target).run()` accepts any server-like target.
+
+```ts
+import express from "express";
+import { endpoint } from "@nwire/endpoint";
+
+const app = express();
+app.get("/hello", (_, res) => res.json({ ok: true }));
+
+await endpoint("api", { port: 3000 }).serve(app).run();
+// http-terminator drains keep-alive; /live + /ready on :9400; SIGTERM handled
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack. `endpoint().use(app).mount(api).run()` boots a Nwire `App` (plugins, providers, lifecycle events) and mounts one or more Nwire interfaces in the same managed process.
+
+```ts
+import { endpoint } from "@nwire/endpoint";
+import { createApp } from "@nwire/forge";
+import { http } from "@nwire/http";
+
+const app = createApp("learnflow").module(stations);
+const api = http("api").wire(stationRoutes);
+
+await endpoint("api", { port: 3000 }).use(app).mount(api).run();
+```
+
+## API
+
+- `endpoint(name, config).serve(target).run()` — canonical builder; accepts foreign frameworks, Nwire apps, and Nwire interfaces.
+- `attachLifecycle({ server, shutdown, health })` — escape hatch when you already have a `Server`.
+- `defineCheck(name, check)` — declarative readiness probe; aggregated into `/ready`.
+- `RunningEndpoint` / `EndpointConfig` / `ShutdownConfig` / `HealthConfig` / `HealthCheck` — config types.
+
+## See also
+
+- [Architecture sketch §05 — Foundation tier](../../architecture-sketch.html#packages)
+- Built on [`http-terminator`](https://github.com/gajus/http-terminator) + [`lightship`](https://github.com/gajus/lightship)
+- Sibling packages: [@nwire/container](../nwire-container), [@nwire/app](../nwire-app), [@nwire/http](../nwire-http)

package/dist/__tests__/endpoint.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Smoke tests for the endpoint builder. Exercises:
+ *
+ *   - Type guards on the three Servable shapes (Nwire interface / app / foreign)
+ *   - Builder accepts each shape via .serve()
+ *   - .serve() with an unknown shape throws a clear error
+ *
+ * Full lifecycle integration (boot → listen → SIGTERM → drain → exit) is
+ * covered by the docker-compose integration suite, not this unit file.
+ * That suite lives at `examples/integration-tests/` and runs against
+ * real K8s probes + http-terminator timing.
+ */
+export {};
+//# sourceMappingURL=endpoint.test.d.ts.map

package/dist/__tests__/endpoint.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/endpoint.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/__tests__/endpoint.test.js

@@ -0,0 +1,95 @@
+/**
+ * Smoke tests for the endpoint builder. Exercises:
+ *
+ *   - Type guards on the three Servable shapes (Nwire interface / app / foreign)
+ *   - Builder accepts each shape via .serve()
+ *   - .serve() with an unknown shape throws a clear error
+ *
+ * Full lifecycle integration (boot → listen → SIGTERM → drain → exit) is
+ * covered by the docker-compose integration suite, not this unit file.
+ * That suite lives at `examples/integration-tests/` and runs against
+ * real K8s probes + http-terminator timing.
+ */
+import { describe, it, expect } from "vitest";
+import { endpoint, isAppServable, isForeignServable, isNwireServable, } from "../endpoint.js";
+describe("endpoint() — type guards", () => {
+    it("identifies a NwireServable by the $nwireServable marker", () => {
+        const ns = {
+            $nwireServable: true,
+            transport: "http",
+            attach: () => undefined,
+        };
+        expect(isNwireServable(ns)).toBe(true);
+        expect(isAppServable(ns)).toBe(false);
+        expect(isForeignServable(ns)).toBe(false);
+    });
+    it("identifies an AppServable by the $nwireApp marker", () => {
+        const app = {
+            $nwireApp: true,
+            container: {
+                resolve: () => undefined,
+                has: () => false,
+                register: () => undefined,
+                createScope: () => app.container,
+            },
+            boot: async () => undefined,
+            shutdown: async () => undefined,
+        };
+        expect(isAppServable(app)).toBe(true);
+        expect(isNwireServable(app)).toBe(false);
+    });
+    it("identifies a ForeignServable by .listen()", () => {
+        /**
+         * Anything with `.listen(port, host?, cb?): Server` is treated as a
+         * foreign framework. The endpoint will wrap the resulting Server
+         * with attachLifecycle().
+         */
+        const foreign = {
+            listen: () => ({}),
+        };
+        expect(isForeignServable(foreign)).toBe(true);
+        expect(isNwireServable(foreign)).toBe(false);
+        expect(isAppServable(foreign)).toBe(false);
+    });
+    it("rejects plain objects that satisfy none of the contracts", () => {
+        const garbage = { foo: 1, bar: () => undefined };
+        expect(isNwireServable(garbage)).toBe(false);
+        expect(isAppServable(garbage)).toBe(false);
+        expect(isForeignServable(garbage)).toBe(false);
+    });
+});
+describe("endpoint() — builder", () => {
+    it("accepts each Servable shape via .serve() in any order", () => {
+        /**
+         * The builder doesn't run anything until .run() is called, so we can
+         * verify ordering / acceptance without spinning up a server.
+         */
+        const app = {
+            $nwireApp: true,
+            container: {
+                resolve: () => undefined,
+                has: () => false,
+                register: () => undefined,
+                createScope: () => undefined,
+            },
+            boot: async () => undefined,
+            shutdown: async () => undefined,
+        };
+        const iface = {
+            $nwireServable: true,
+            transport: "queue",
+            attach: () => undefined,
+        };
+        expect(() => endpoint("api").serve(app).serve(iface)).not.toThrow();
+        expect(() => endpoint("api").serve(iface).serve(app)).not.toThrow();
+    });
+    it("throws a clear error when .serve() gets an unknown shape", () => {
+        /**
+         * Catching the bad-input case at .serve() time (not .run() time) means
+         * the developer sees the error at the call site, not buried in a
+         * runtime stack trace from inside the boot sequence.
+         */
+        expect(() => endpoint("api").serve({ random: 42 })).toThrow(/not a Nwire app, Nwire interface, or framework app/);
+    });
+});
+//# sourceMappingURL=endpoint.test.js.map

package/dist/__tests__/endpoint.test.js.map

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

package/dist/endpoint-index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@nwire/endpoint` — production process lifecycle for Node servers.
+ *
+ * The outermost layer of any Nwire app, and the only piece that talks to
+ * the operating system. Wraps any Node server (Express, Fastify, Koa,
+ * Nest, Hono, Nwire interfaces) with K8s-grade graceful shutdown,
+ * http-terminator drain, and lightship readiness/liveness probes.
+ *
+ * Two public APIs:
+ *
+ *   - `endpoint(name, config).serve(target).run()` — high-level builder
+ *     (the v1.0 canonical entry). Handles boot ordering, transport
+ *     attachment, probes, and shutdown sequence in one chained call.
+ *   - `attachLifecycle({ server, shutdown, health })` — low-level escape
+ *     hatch. Use this when you already have a Node `Server` and just
+ *     need graceful shutdown + probes wrapped around it.
+ *
+ * Both compose around the same battle-tested primitives
+ * (`http-terminator` + `lightship`). The high-level builder is what most
+ * projects reach for; the low-level form is for adapters and tests.
+ */
+export { endpoint, EndpointBuilder, isAppServable, isForeignServable, isNwireServable, type AppServable, type EndpointConfig, type ForeignServable, type HostBindings, type HostFactory, type NwireServable, type RunningEndpoint, type Servable, } from "./endpoint.js";
+export { attachLifecycle, defineCheck, type HealthCheck, type HealthConfig, type LifecycleManager, type ShutdownConfig, } from "./lifecycle.js";
+//# sourceMappingURL=endpoint-index.d.ts.map

package/dist/endpoint-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-index.d.ts","sourceRoot":"","sources":["../src/endpoint-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,QAAQ,EACR,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,QAAQ,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC"}

package/dist/endpoint-index.js

@@ -0,0 +1,24 @@
+/**
+ * `@nwire/endpoint` — production process lifecycle for Node servers.
+ *
+ * The outermost layer of any Nwire app, and the only piece that talks to
+ * the operating system. Wraps any Node server (Express, Fastify, Koa,
+ * Nest, Hono, Nwire interfaces) with K8s-grade graceful shutdown,
+ * http-terminator drain, and lightship readiness/liveness probes.
+ *
+ * Two public APIs:
+ *
+ *   - `endpoint(name, config).serve(target).run()` — high-level builder
+ *     (the v1.0 canonical entry). Handles boot ordering, transport
+ *     attachment, probes, and shutdown sequence in one chained call.
+ *   - `attachLifecycle({ server, shutdown, health })` — low-level escape
+ *     hatch. Use this when you already have a Node `Server` and just
+ *     need graceful shutdown + probes wrapped around it.
+ *
+ * Both compose around the same battle-tested primitives
+ * (`http-terminator` + `lightship`). The high-level builder is what most
+ * projects reach for; the low-level form is for adapters and tests.
+ */
+export { endpoint, EndpointBuilder, isAppServable, isForeignServable, isNwireServable, } from "./endpoint.js";
+export { attachLifecycle, defineCheck, } from "./lifecycle.js";
+//# sourceMappingURL=endpoint-index.js.map

package/dist/endpoint-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-index.js","sourceRoot":"","sources":["../src/endpoint-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,QAAQ,EACR,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,GAShB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,WAAW,GAKZ,MAAM,aAAa,CAAC"}

package/dist/endpoint.d.ts

@@ -0,0 +1,218 @@
+/**
+ * `endpoint()` — the canonical Nwire entry point for running a process.
+ *
+ * An endpoint is the outermost layer of a Nwire app. It owns:
+ *
+ *   - the port (when listening for HTTP-class transports)
+ *   - the signal handling (SIGTERM / SIGINT)
+ *   - the graceful drain (http-terminator)
+ *   - the K8s probes (lightship — startup / liveness / readiness)
+ *   - the boot order (apps first, transports second)
+ *   - the shutdown order (transports first, apps reverse-of-boot)
+ *
+ * The endpoint is the only Nwire layer that talks to the operating
+ * system. Everything else — apps, modules, interfaces, resolvers — is
+ * pure data + functions until an endpoint wraps them in a process.
+ *
+ * ## What can be served
+ *
+ * `endpoint(name, config).serve(target)` accepts any of:
+ *
+ *   - A Nwire interface compiled to a Node server adapter (the common case)
+ *   - An existing Express / Fastify / Koa / Nest app (the interop case)
+ *   - A `@nwire/app` instance (boot order + container DI)
+ *
+ * Multiple `.serve()` calls compose: serve the app first to boot its
+ * container, then serve one or more interfaces that use that container.
+ *
+ * ## Why this exists
+ *
+ * Every framework eventually needs a process layer — something that knows
+ * about SIGTERM, drains in-flight requests, exposes `/healthz`, and binds
+ * to a port. Most frameworks bolt this on as a deployment afterthought.
+ * `@nwire/endpoint` makes it the first-class entry point so you don't
+ * write the same K8s-readiness code on every project. It works alone —
+ * install only this package and wrap any Node server.
+ */
+import type { Server } from "node:http";
+import type { Container } from "@nwire/container";
+import { type HealthConfig, type HealthCheck, type LifecycleManager, type ShutdownConfig } from "./lifecycle.js";
+/**
+ * Anything that can be served by an endpoint. Three categories:
+ *
+ *   1. **NwireServable** — a Nwire interface (http/queue/etc) that knows how
+ *      to produce a request handler and report what transport it needs.
+ *   2. **ForeignServable** — an existing framework app (Express / Fastify /
+ *      Koa / Nest / etc) that the endpoint will wrap.
+ *   3. **AppServable** — a Container-with-lifecycle that gets booted first
+ *      so transports can use its bindings.
+ *
+ * Detection is structural: the endpoint inspects the shape at runtime to
+ * decide how to serve it. No magic — see {@link isNwireServable},
+ * {@link isAppServable}, {@link isForeignServable}.
+ */
+export type Servable = NwireServable | ForeignServable | AppServable;
+/**
+ * A Nwire interface compiled for the endpoint. The interface exposes how
+ * it wants to be mounted: which transport, what handler shape, what
+ * health checks it contributes.
+ */
+export interface NwireServable {
+    readonly $nwireServable: true;
+    /** Which transport this interface uses. Decides what listener spins up. */
+    readonly transport: "http" | "graphql" | "queue" | "cron" | "ws" | "mcp" | "custom";
+    /**
+     * Attach to a host that owns the transport. For HTTP-class transports
+     * the endpoint provides a Koa/raw http server and the interface mounts
+     * its router. For queue-class transports the endpoint spins up the
+     * consumer loop.
+     */
+    attach(host: HostBindings): void | Promise<void>;
+    /** Optional health checks contributed by the interface itself. */
+    readonly checks?: readonly HealthCheck[];
+    /** Run during shutdown — disconnect from broker, flush, etc. */
+    shutdown?(): void | Promise<void>;
+}
+/**
+ * A foreign framework app — typically `express()`, `Fastify()`, `Koa()`,
+ * or `NestFactory.create(AppModule)`. The endpoint will use the framework's
+ * own listen mechanics where possible and wrap the resulting `Server` with
+ * `attachLifecycle()`.
+ */
+export interface ForeignServable {
+    /** Required marker: any object that produces an http.Server via .listen(port). */
+    listen(port: number, hostname?: string, callback?: () => void): Server;
+}
+/**
+ * A Nwire app — a Container with boot/shutdown lifecycle. The endpoint
+ * boots it before mounting transports so any handler `ctx.resolve(...)`
+ * works the moment the first request lands.
+ *
+ * `@nwire/app` produces this shape; you can build your own minimal one if
+ * you don't want the full plugin system.
+ */
+export interface AppServable {
+    readonly $nwireApp: true;
+    readonly container: Container;
+    boot(): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * Optional — app name used in lifecycle event payloads. Defaults to
+     * the endpoint's `name` when missing.
+     */
+    readonly appName?: string;
+    /**
+     * Optional — dispatch a framework lifecycle event on the app's bus.
+     * The endpoint uses this to fire `nwire.wire.mounting` /
+     * `nwire.wire.mounted` / `nwire.wire.unmounted` / `nwire.app.ready`
+     * at the right points in the serve loop.
+     *
+     * The dispatcher is duck-typed by event NAME so endpoint stays
+     * independent of `@nwire/app`. Apps that don't expose this method
+     * still serve correctly — endpoint just skips dispatch silently.
+     *
+     * Returns `false` when a series-bail subscriber prevented; `true`
+     * otherwise. Endpoint honors `false` only for the `*-ing` events.
+     */
+    dispatchFrameworkEvent?(eventName: string, payload: unknown): Promise<boolean>;
+}
+/** What the endpoint hands to each NwireServable.attach() call. */
+export interface HostBindings {
+    /**
+     * Container of the served app, or `undefined` if no app was served.
+     * When undefined, the interface should preserve its own `.provide()`
+     * container (the L2 standalone case).
+     */
+    readonly container: Container | undefined;
+    /**
+     * Register a HealthCheck on the endpoint's lifecycle. Interfaces that
+     * need readiness verification (queue connected, NATS subscribed) call
+     * this so the K8s probes reflect real state.
+     */
+    addCheck(check: HealthCheck): void;
+}
+export interface EndpointConfig {
+    /** Port for HTTP-class transports. Omit for queue-only / cron-only endpoints. */
+    readonly port?: number;
+    /** Bind address. Default `0.0.0.0`. */
+    readonly host?: string;
+    /** Shutdown timing budgets. */
+    readonly shutdown?: ShutdownConfig;
+    /** Health probe configuration (a dedicated port; defaults to 9_400). */
+    readonly probes?: HealthConfig;
+    /** Show the boot banner on stdout. Default `true`. */
+    readonly banner?: boolean;
+    /** Test seam — skip process.exit() during shutdown. Default unset. */
+    readonly exitOnShutdown?: boolean;
+}
+export interface RunningEndpoint {
+    readonly name: string;
+    readonly server?: Server;
+    readonly lifecycle: LifecycleManager;
+    /** Trigger shutdown manually. Idempotent. */
+    shutdown(reason?: string): Promise<void>;
+}
+/**
+ * Build an endpoint. The returned builder is chainable: `.serve()` adds
+ * apps + interfaces in declaration order; `.run()` boots and listens.
+ *
+ * ```ts
+ * await endpoint("api", { port: 3000 })
+ *   .serve(app)         // optional — boots container first
+ *   .serve(httpApi)     // mounts an HTTP interface
+ *   .serve(workers)     // mounts a queue worker
+ *   .run()
+ * ```
+ *
+ * For a foreign-framework integration:
+ *
+ * ```ts
+ * await endpoint("api", { port: 3000 })
+ *   .serve(existingExpressApp)
+ *   .run()
+ * ```
+ */
+export declare function endpoint(name: string, config?: EndpointConfig): EndpointBuilder;
+/** Internal builder; users get one via {@link endpoint}. */
+export declare class EndpointBuilder {
+    private readonly name;
+    private readonly config;
+    private apps;
+    private nwireServables;
+    private foreignServables;
+    constructor(name: string, config: EndpointConfig);
+    /**
+     * Add something to serve. Multiple calls compose. Apps are booted first
+     * (any order between them is OK — boot order matters within an app, not
+     * across them), then Nwire interfaces and foreign apps are attached.
+     */
+    serve(target: Servable): EndpointBuilder;
+    /**
+     * Boot all served apps in order, then attach all served interfaces +
+     * foreign apps, then start listening. Returns a {@link RunningEndpoint}
+     * with handles for manual shutdown (useful in tests).
+     *
+     * The shutdown order is reverse: foreign apps stop accepting via their
+     * own server.close(), then Nwire interfaces shutdown(), then apps
+     * shutdown() in reverse boot order. The lifecycle manager wraps the
+     * whole sequence with K8s drain semantics.
+     */
+    run(): Promise<RunningEndpoint>;
+}
+/** True when the target is a Nwire interface (http/queue/etc) compiled for endpoint mount. */
+export declare function isNwireServable(x: unknown): x is NwireServable;
+/** True when the target is a Nwire app (container + lifecycle). */
+export declare function isAppServable(x: unknown): x is AppServable;
+/** True when the target looks like a framework app — has `.listen(port, ...)`. */
+export declare function isForeignServable(x: unknown): x is ForeignServable;
+/**
+ * Per-transport host factory shape (provided by interface packages like
+ * `@nwire/http`). The endpoint stays transport-agnostic by holding a
+ * reference to this through `_buildHost` and asking the transport to
+ * produce a Server when needed.
+ */
+export interface HostFactory {
+    addCheck(check: HealthCheck): void;
+    listen(port: number, host: string): Promise<Server>;
+}
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/endpoint.d.ts.map

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

package/dist/endpoint.js

@@ -0,0 +1,376 @@
+/**
+ * `endpoint()` — the canonical Nwire entry point for running a process.
+ *
+ * An endpoint is the outermost layer of a Nwire app. It owns:
+ *
+ *   - the port (when listening for HTTP-class transports)
+ *   - the signal handling (SIGTERM / SIGINT)
+ *   - the graceful drain (http-terminator)
+ *   - the K8s probes (lightship — startup / liveness / readiness)
+ *   - the boot order (apps first, transports second)
+ *   - the shutdown order (transports first, apps reverse-of-boot)
+ *
+ * The endpoint is the only Nwire layer that talks to the operating
+ * system. Everything else — apps, modules, interfaces, resolvers — is
+ * pure data + functions until an endpoint wraps them in a process.
+ *
+ * ## What can be served
+ *
+ * `endpoint(name, config).serve(target)` accepts any of:
+ *
+ *   - A Nwire interface compiled to a Node server adapter (the common case)
+ *   - An existing Express / Fastify / Koa / Nest app (the interop case)
+ *   - A `@nwire/app` instance (boot order + container DI)
+ *
+ * Multiple `.serve()` calls compose: serve the app first to boot its
+ * container, then serve one or more interfaces that use that container.
+ *
+ * ## Why this exists
+ *
+ * Every framework eventually needs a process layer — something that knows
+ * about SIGTERM, drains in-flight requests, exposes `/healthz`, and binds
+ * to a port. Most frameworks bolt this on as a deployment afterthought.
+ * `@nwire/endpoint` makes it the first-class entry point so you don't
+ * write the same K8s-readiness code on every project. It works alone —
+ * install only this package and wrap any Node server.
+ */
+import { attachLifecycle, } from "./lifecycle.js";
+// ─── Builder API ──────────────────────────────────────────────────────────
+/**
+ * Build an endpoint. The returned builder is chainable: `.serve()` adds
+ * apps + interfaces in declaration order; `.run()` boots and listens.
+ *
+ * ```ts
+ * await endpoint("api", { port: 3000 })
+ *   .serve(app)         // optional — boots container first
+ *   .serve(httpApi)     // mounts an HTTP interface
+ *   .serve(workers)     // mounts a queue worker
+ *   .run()
+ * ```
+ *
+ * For a foreign-framework integration:
+ *
+ * ```ts
+ * await endpoint("api", { port: 3000 })
+ *   .serve(existingExpressApp)
+ *   .run()
+ * ```
+ */
+export function endpoint(name, config = {}) {
+    return new EndpointBuilder(name, config);
+}
+/** Internal builder; users get one via {@link endpoint}. */
+export class EndpointBuilder {
+    name;
+    config;
+    apps = [];
+    nwireServables = [];
+    foreignServables = [];
+    constructor(name, config) {
+        this.name = name;
+        this.config = config;
+    }
+    /**
+     * Add something to serve. Multiple calls compose. Apps are booted first
+     * (any order between them is OK — boot order matters within an app, not
+     * across them), then Nwire interfaces and foreign apps are attached.
+     */
+    serve(target) {
+        if (isAppServable(target)) {
+            this.apps.push(target);
+        }
+        else if (isNwireServable(target)) {
+            this.nwireServables.push(target);
+        }
+        else if (isForeignServable(target)) {
+            this.foreignServables.push(target);
+        }
+        else {
+            throw new Error(`endpoint("${this.name}").serve(): target is not a Nwire app, Nwire interface, or framework app.`);
+        }
+        return this;
+    }
+    /**
+     * Boot all served apps in order, then attach all served interfaces +
+     * foreign apps, then start listening. Returns a {@link RunningEndpoint}
+     * with handles for manual shutdown (useful in tests).
+     *
+     * The shutdown order is reverse: foreign apps stop accepting via their
+     * own server.close(), then Nwire interfaces shutdown(), then apps
+     * shutdown() in reverse boot order. The lifecycle manager wraps the
+     * whole sequence with K8s drain semantics.
+     */
+    async run() {
+        // 1. Boot apps in declaration order so transports can resolve from
+        //    their containers from the first request.
+        for (const app of this.apps) {
+            await app.boot();
+        }
+        // Helper to dispatch a lifecycle event on every served app's bus.
+        // Apps that don't expose `dispatchFrameworkEvent` are silently
+        // skipped (L2 standalone case has no apps; observers register on
+        // the app's bus so there's nothing to dispatch to).
+        const fireLifecycle = async (eventName, payload) => {
+            let allowed = true;
+            for (const app of this.apps) {
+                if (app.dispatchFrameworkEvent) {
+                    const ok = await app.dispatchFrameworkEvent(eventName, payload);
+                    if (!ok)
+                        allowed = false;
+                }
+            }
+            return allowed;
+        };
+        // The container the host hands to interfaces. If multiple apps were
+        // served, we use the first app's container as primary — interfaces
+        // can reach into others via `ctx.resolve` if those bindings exist.
+        // Most apps have one container; this case-edge is for BFFs.
+        //
+        // L2 path: no app served (`.serve(api)` on a bare httpInterface). The
+        // interface already has a container set via `.provide(...)`; we must
+        // NOT clobber it. Pass `undefined` so the interface's attach() can
+        // preserve its own provision.
+        const container = this.apps[0]?.container;
+        // 2. Start the operating-system listener. For HTTP-class endpoints we
+        //    spin a single Node http.Server that hosts all NwireServables +
+        //    any ForeignServable. Workers-only endpoints skip the listener
+        //    entirely; the probes server is still available.
+        //
+        // Each `s.attach(...)` is wrapped with WireMounting (interceptable)
+        // and WireMounted (observable) so dev logger + Studio Live show
+        // every wire as it comes up.
+        let server;
+        if (this.config.port !== undefined &&
+            (this.nwireServables.length || this.foreignServables.length)) {
+            // Pre-attach hook: fire WireMounting for each interface BEFORE
+            // startListener does the actual attach.
+            for (const s of this.nwireServables) {
+                const ok = await fireLifecycle("nwire.wire.mounting", {
+                    appName: this.apps[0]?.appName ?? this.name,
+                    transport: s.transport,
+                    manifest: undefined,
+                });
+                if (!ok) {
+                    throw new Error(`endpoint("${this.name}").serve(): wire "${s.transport}" mount prevented by a WireMounting subscriber.`);
+                }
+            }
+            server = await startListener({
+                port: this.config.port,
+                host: this.config.host,
+                nwireServables: this.nwireServables,
+                foreignServables: this.foreignServables,
+                container,
+            });
+            // Post-attach: every wire is now attached. Fire WireMounted.
+            for (const s of this.nwireServables) {
+                await fireLifecycle("nwire.wire.mounted", {
+                    appName: this.apps[0]?.appName ?? this.name,
+                    transport: s.transport,
+                    manifest: undefined,
+                });
+            }
+        }
+        else {
+            // Workers / queue / cron — attach NwireServables to a non-HTTP host.
+            for (const s of this.nwireServables) {
+                const ok = await fireLifecycle("nwire.wire.mounting", {
+                    appName: this.apps[0]?.appName ?? this.name,
+                    transport: s.transport,
+                    manifest: undefined,
+                });
+                if (!ok) {
+                    throw new Error(`endpoint("${this.name}").serve(): wire "${s.transport}" mount prevented by a WireMounting subscriber.`);
+                }
+                await s.attach({ container, addCheck: () => undefined });
+                await fireLifecycle("nwire.wire.mounted", {
+                    appName: this.apps[0]?.appName ?? this.name,
+                    transport: s.transport,
+                    manifest: undefined,
+                });
+            }
+        }
+        // 3. Wrap the server (if any) with graceful shutdown + probes.
+        const lifecycle = await attachLifecycle({
+            server: server ?? makeProbeOnlyServer(),
+            shutdown: {
+                ...this.config.shutdown,
+                onShutdown: async () => {
+                    // Fire WireUnmounted for each interface BEFORE its shutdown
+                    // runs, so observers can record "wire stopping" with full
+                    // context. Errors during dispatch are swallowed — shutdown
+                    // must complete regardless.
+                    for (let i = this.nwireServables.length - 1; i >= 0; i--) {
+                        const s = this.nwireServables[i];
+                        try {
+                            await fireLifecycle("nwire.wire.unmounted", {
+                                appName: this.apps[0]?.appName ?? this.name,
+                                transport: s.transport,
+                            });
+                        }
+                        catch {
+                            /* swallow — shutdown must proceed */
+                        }
+                    }
+                    // Interface shutdowns — let them disconnect cleanly.
+                    for (let i = this.nwireServables.length - 1; i >= 0; i--) {
+                        await this.nwireServables[i].shutdown?.();
+                    }
+                    // Apps shutdown in reverse boot order.
+                    for (let i = this.apps.length - 1; i >= 0; i--) {
+                        await this.apps[i].shutdown();
+                    }
+                    // User-supplied shutdown hook last, if any.
+                    await this.config.shutdown?.onShutdown?.();
+                },
+            },
+            health: {
+                ...this.config.probes,
+                checks: [
+                    ...(this.config.probes?.checks ?? []),
+                    ...this.nwireServables.flatMap((s) => s.checks ?? []),
+                ],
+            },
+            exitOnShutdown: this.config.exitOnShutdown,
+        });
+        // 4. Register interface checks dynamically too — they may have been
+        //    discovered during attach (e.g., queue probes once connected).
+        for (const s of this.nwireServables) {
+            for (const c of s.checks ?? [])
+                lifecycle.addCheck(c);
+        }
+        // 5. Flip readiness and print the banner. AppReady fires AFTER
+        // lightship marks /ready 200 — that's the moment the wire actually
+        // accepts traffic.
+        lifecycle.ready();
+        for (const app of this.apps) {
+            if (app.dispatchFrameworkEvent) {
+                await app.dispatchFrameworkEvent("nwire.app.ready", {
+                    appName: app.appName ?? this.name,
+                    readyAt: new Date().toISOString(),
+                });
+            }
+        }
+        if (this.config.banner !== false) {
+            // Only advertise probes if lightship actually bound. The bind
+            // can be skipped (probes disabled) or fail silently on
+            // EADDRINUSE (handled in attachLifecycle).
+            const probesBound = lifecycle.lightship !== undefined;
+            printBanner({
+                name: this.name,
+                port: this.config.port,
+                probePort: probesBound ? (this.config.probes?.port ?? 9_400) : undefined,
+            });
+        }
+        return {
+            name: this.name,
+            server,
+            lifecycle,
+            shutdown: (reason = "manual") => lifecycle.shutdown(reason),
+        };
+    }
+}
+// ─── Type guards ──────────────────────────────────────────────────────────
+/** True when the target is a Nwire interface (http/queue/etc) compiled for endpoint mount. */
+export function isNwireServable(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        x.$nwireServable === true);
+}
+/** True when the target is a Nwire app (container + lifecycle). */
+export function isAppServable(x) {
+    return typeof x === "object" && x !== null && x.$nwireApp === true;
+}
+/** True when the target looks like a framework app — has `.listen(port, ...)`. */
+export function isForeignServable(x) {
+    return (typeof x === "object" && x !== null && typeof x.listen === "function");
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────
+/**
+ * Start the operating-system listener. When multiple NwireServables share
+ * a port, this composes them onto a single http.Server. ForeignServables
+ * use their own `.listen()` and the resulting Server is what gets wrapped
+ * with lifecycle — meaning today only ONE ForeignServable per endpoint is
+ * supported (more would require an internal multiplexer). The 99% case
+ * is fine; multi-foreign on one port is exotic and you'd build it yourself.
+ */
+async function startListener(opts) {
+    if (opts.foreignServables.length > 1) {
+        throw new Error(`endpoint: more than one foreign-framework target on one port is not supported; ` +
+            `mount them separately or compose them inside the framework first.`);
+    }
+    // Case A — foreign app owns the server. Nwire interfaces attach onto it
+    // via to* adapters (toExpress, toKoa) the user calls themselves before
+    // serving the framework. The endpoint just wraps the resulting Server.
+    if (opts.foreignServables.length === 1) {
+        const foreign = opts.foreignServables[0];
+        const server = await new Promise((resolve) => {
+            const s = foreign.listen(opts.port, opts.host ?? "0.0.0.0", () => resolve(s));
+        });
+        // NwireServables attached to a foreign endpoint must register
+        // themselves separately — there's no way for us to mount them onto
+        // the foreign framework's router automatically without knowing the
+        // framework. Future: detect Express/Fastify/Koa and auto-mount.
+        for (const s of opts.nwireServables) {
+            await s.attach({ container: opts.container, addCheck: () => undefined });
+        }
+        return server;
+    }
+    // Case B — Nwire interfaces only. Build a host that they attach to.
+    // For now we delegate to the first servable's transport-specific host
+    // builder. Multi-transport on one port (REST + GraphQL + WS) requires
+    // a more elaborate host; that's @nwire/http's job.
+    if (opts.nwireServables.length === 0) {
+        throw new Error("endpoint: nothing to listen on (no Nwire interfaces, no foreign app)");
+    }
+    // Lean fallback: assume the first servable carries an internal listener
+    // factory. The richer multi-transport host lives in @nwire/http.
+    const primary = opts.nwireServables[0];
+    const buildHost = primary._buildHost;
+    const hostFactory = buildHost ? buildHost.bind(primary) : undefined;
+    if (!hostFactory) {
+        throw new Error(`endpoint: interface "${primary.transport}" does not expose _buildHost(); ` +
+            `it cannot be the primary listener. Install a transport package that supports it.`);
+    }
+    const built = hostFactory();
+    for (const s of opts.nwireServables) {
+        await s.attach({ container: opts.container, addCheck: built.addCheck });
+    }
+    return await built.listen(opts.port, opts.host ?? "0.0.0.0");
+}
+/** Probe-only server for workers/cron — nothing on the data port. */
+function makeProbeOnlyServer() {
+    // Lazy import keeps the cold-path module load out of the hot start.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const http = require("node:http");
+    const srv = http.createServer((_req, res) => {
+        res.statusCode = 404;
+        res.end();
+    });
+    // We don't actually .listen() this; attachLifecycle uses it only as
+    // the http-terminator target. Workers have no data port to drain;
+    // the probe port (lightship) is separate.
+    return srv;
+}
+// `emptyContainer()` was previously used when no app was served — but
+// it throws on every resolve, which clobbered the interface's own
+// `.provide()` container. The endpoint now passes `undefined` upward
+// and lets the interface preserve its own provision (the L2 path).
+/** Boot-time banner — friendly, informative, not chatty. */
+function printBanner(opts) {
+    const lines = [
+        `nwire endpoint "${opts.name}" listening`,
+        opts.port !== undefined
+            ? `   data:   http://0.0.0.0:${opts.port}`
+            : `   data:   (no HTTP listener)`,
+    ];
+    if (opts.probePort !== undefined) {
+        // lightship's actual paths — not /readyz + /healthz (which was a
+        // historical misnaming in our docs).
+        lines.push(`   probes: http://0.0.0.0:${opts.probePort}/live · /ready`);
+    }
+    else {
+        lines.push(`   probes: (disabled — port already in use or probes disabled)`);
+    }
+    console.log(lines.join("\n"));
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,EACL,eAAe,GAKhB,MAAM,aAAa,CAAC;AA8HrB,6EAA6E;AAE7E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,SAAyB,EAAE;IAChE,OAAO,IAAI,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC;AAED,4DAA4D;AAC5D,MAAM,OAAO,eAAe;IAMP;IACA;IANX,IAAI,GAAkB,EAAE,CAAC;IACzB,cAAc,GAAoB,EAAE,CAAC;IACrC,gBAAgB,GAAsB,EAAE,CAAC;IAEjD,YACmB,IAAY,EACZ,MAAsB;QADtB,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAgB;IACtC,CAAC;IAEJ;;;;OAIG;IACH,KAAK,CAAC,MAAgB;QACpB,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC;aAAM,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;aAAM,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,IAAI,2EAA2E,CAClG,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,GAAG;QACP,mEAAmE;QACnE,8CAA8C;QAC9C,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC;QAED,kEAAkE;QAClE,+DAA+D;QAC/D,iEAAiE;QACjE,oDAAoD;QACpD,MAAM,aAAa,GAAG,KAAK,EAAE,SAAiB,EAAE,OAAgB,EAAoB,EAAE;YACpF,IAAI,OAAO,GAAG,IAAI,CAAC;YACnB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5B,IAAI,GAAG,CAAC,sBAAsB,EAAE,CAAC;oBAC/B,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,sBAAsB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;oBAChE,IAAI,CAAC,EAAE;wBAAE,OAAO,GAAG,KAAK,CAAC;gBAC3B,CAAC;YACH,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC;QAEF,oEAAoE;QACpE,mEAAmE;QACnE,mEAAmE;QACnE,4DAA4D;QAC5D,EAAE;QACF,sEAAsE;QACtE,qEAAqE;QACrE,mEAAmE;QACnE,8BAA8B;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;QAE1C,sEAAsE;QACtE,oEAAoE;QACpE,mEAAmE;QACnE,qDAAqD;QACrD,EAAE;QACF,oEAAoE;QACpE,gEAAgE;QAChE,6BAA6B;QAC7B,IAAI,MAA0B,CAAC;QAC/B,IACE,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS;YAC9B,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAC5D,CAAC;YACD,+DAA+D;YAC/D,wCAAwC;YACxC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpC,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,qBAAqB,EAAE;oBACpD,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,IAAI;oBAC3C,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,QAAQ,EAAE,SAAS;iBACpB,CAAC,CAAC;gBACH,IAAI,CAAC,EAAE,EAAE,CAAC;oBACR,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,IAAI,qBAAqB,CAAC,CAAC,SAAS,iDAAiD,CACxG,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,MAAM,GAAG,MAAM,aAAa,CAAC;gBAC3B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;gBACtB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;gBACtB,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;gBACvC,SAAS;aACV,CAAC,CAAC;YACH,6DAA6D;YAC7D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpC,MAAM,aAAa,CAAC,oBAAoB,EAAE;oBACxC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,IAAI;oBAC3C,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,QAAQ,EAAE,SAAS;iBACpB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;aAAM,CAAC;YACN,qEAAqE;YACrE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpC,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,qBAAqB,EAAE;oBACpD,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,IAAI;oBAC3C,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,QAAQ,EAAE,SAAS;iBACpB,CAAC,CAAC;gBACH,IAAI,CAAC,EAAE,EAAE,CAAC;oBACR,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,IAAI,qBAAqB,CAAC,CAAC,SAAS,iDAAiD,CACxG,CAAC;gBACJ,CAAC;gBACD,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;gBACzD,MAAM,aAAa,CAAC,oBAAoB,EAAE;oBACxC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,IAAI;oBAC3C,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,QAAQ,EAAE,SAAS;iBACpB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,+DAA+D;QAC/D,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC;YACtC,MAAM,EAAE,MAAM,IAAI,mBAAmB,EAAE;YACvC,QAAQ,EAAE;gBACR,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ;gBACvB,UAAU,EAAE,KAAK,IAAI,EAAE;oBACrB,4DAA4D;oBAC5D,0DAA0D;oBAC1D,2DAA2D;oBAC3D,4BAA4B;oBAC5B,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;wBACzD,MAAM,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAE,CAAC;wBAClC,IAAI,CAAC;4BACH,MAAM,aAAa,CAAC,sBAAsB,EAAE;gCAC1C,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,IAAI;gCAC3C,SAAS,EAAE,CAAC,CAAC,SAAS;6BACvB,CAAC,CAAC;wBACL,CAAC;wBAAC,MAAM,CAAC;4BACP,qCAAqC;wBACvC,CAAC;oBACH,CAAC;oBACD,qDAAqD;oBACrD,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;wBACzD,MAAM,IAAI,CAAC,cAAc,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;oBAC7C,CAAC;oBACD,uCAAuC;oBACvC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;wBAC/C,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,CAAC;oBACjC,CAAC;oBACD,4CAA4C;oBAC5C,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC;gBAC7C,CAAC;aACF;YACD,MAAM,EAAE;gBACN,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM;gBACrB,MAAM,EAAE;oBACN,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC;oBACrC,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;iBACtD;aACF;YACD,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;SAC3C,CAAC,CAAC;QAEH,oEAAoE;QACpE,mEAAmE;QACnE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACpC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE;gBAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACxD,CAAC;QAED,+DAA+D;QAC/D,mEAAmE;QACnE,mBAAmB;QACnB,SAAS,CAAC,KAAK,EAAE,CAAC;QAClB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,GAAG,CAAC,sBAAsB,EAAE,CAAC;gBAC/B,MAAM,GAAG,CAAC,sBAAsB,CAAC,iBAAiB,EAAE;oBAClD,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI;oBACjC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBAClC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YACjC,8DAA8D;YAC9D,uDAAuD;YACvD,2CAA2C;YAC3C,MAAM,WAAW,GAAG,SAAS,CAAC,SAAS,KAAK,SAAS,CAAC;YACtD,WAAW,CAAC;gBACV,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;gBACtB,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;aACzE,CAAC,CAAC;QACL,CAAC;QAED,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM;YACN,SAAS;YACT,QAAQ,EAAE,CAAC,MAAM,GAAG,QAAQ,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC;SAC5D,CAAC;IACJ,CAAC;CACF;AAED,6EAA6E;AAE7E,8FAA8F;AAC9F,MAAM,UAAU,eAAe,CAAC,CAAU;IACxC,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAkC,CAAC,cAAc,KAAK,IAAI,CAC5D,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAA6B,CAAC,SAAS,KAAK,IAAI,CAAC;AAClG,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,CAAU;IAC1C,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAQ,CAA0B,CAAC,MAAM,KAAK,UAAU,CAChG,CAAC;AACJ,CAAC;AAED,6EAA6E;AAE7E;;;;;;;GAOG;AACH,KAAK,UAAU,aAAa,CAAC,IAO5B;IACC,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,iFAAiF;YAC/E,mEAAmE,CACtE,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,uEAAuE;IACvE,uEAAuE;IACvE,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE;YACnD,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAChF,CAAC,CAAC,CAAC;QACH,8DAA8D;QAC9D,mEAAmE;QACnE,mEAAmE;QACnE,gEAAgE;QAChE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACpC,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,oEAAoE;IACpE,sEAAsE;IACtE,sEAAsE;IACtE,mDAAmD;IACnD,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC1F,CAAC;IAED,wEAAwE;IACxE,iEAAiE;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAE,CAAC;IACxC,MAAM,SAAS,GAAI,OAAyD,CAAC,UAAU,CAAC;IACxF,MAAM,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,wBAAwB,OAAO,CAAC,SAAS,kCAAkC;YACzE,kFAAkF,CACrF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACpC,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC,CAAC;AAC/D,CAAC;AAaD,qEAAqE;AACrE,SAAS,mBAAmB;IAC1B,oEAAoE;IACpE,iEAAiE;IACjE,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAA+B,CAAC;IAChE,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;QAC1C,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;QACrB,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;IACH,oEAAoE;IACpE,kEAAkE;IAClE,0CAA0C;IAC1C,OAAO,GAAG,CAAC;AACb,CAAC;AAED,sEAAsE;AACtE,kEAAkE;AAClE,qEAAqE;AACrE,mEAAmE;AAEnE,4DAA4D;AAC5D,SAAS,WAAW,CAAC,IAAyD;IAC5E,MAAM,KAAK,GAAG;QACZ,mBAAmB,IAAI,CAAC,IAAI,aAAa;QACzC,IAAI,CAAC,IAAI,KAAK,SAAS;YACrB,CAAC,CAAC,6BAA6B,IAAI,CAAC,IAAI,EAAE;YAC1C,CAAC,CAAC,+BAA+B;KACpC,CAAC;IACF,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACjC,iEAAiE;QACjE,qCAAqC;QACrC,KAAK,CAAC,IAAI,CAAC,6BAA6B,IAAI,CAAC,SAAS,gBAAgB,CAAC,CAAC;IAC1E,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAChC,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Graceful runtime lifecycle — boot + readiness + shutdown orchestration.
+ *
+ * Composes two battle-tested libraries:
+ *
+ *   - **http-terminator** — properly drains keep-alive connections during
+ *     `server.close()`. Without it, in-flight requests on persistent
+ *     connections silently die when the process exits.
+ *   - **lightship**       — Kubernetes-style readiness/liveness probes on a
+ *     separate operational port. Flips `/readyz` to 503 the moment shutdown
+ *     starts so the load balancer stops sending new traffic — the single
+ *     most important step in a zero-downtime rolling deploy.
+ *
+ * Sequence on SIGTERM/SIGINT:
+ *
+ *   1. lightship: /readyz → 503        (LB removes us from rotation)
+ *   2. wait `drainDelay`               (LB has time to catch up; default 10s)
+ *   3. stop accepting new connections  (http-terminator)
+ *   4. drain in-flight requests        (http-terminator; bounded by drainTimeout)
+ *   5. run user `onShutdown` hooks     (close DBs, Redis, queues — in reverse boot order)
+ *   6. flush logs, exit 0              (or 1 if hardTimeout breached → SIGKILL)
+ *
+ * The whole sequence is bounded by `hardTimeout` — if shutdown takes
+ * longer, the process self-kills so the orchestrator doesn't wait forever.
+ *
+ * This module is intentionally framework-agnostic: it takes a Node `Server`
+ * and wraps it. Use it with any HTTP framework — Express, Fastify, Koa, Nest,
+ * Hono, or a raw `http.createServer` listener. The high-level
+ * `endpoint(name, config).serve(target).run()` wrapper composes this with
+ * server-construction for the common cases.
+ */
+import type { Server } from "node:http";
+import { type Lightship } from "lightship";
+/**
+ * A single health probe. Each check has a name, a function returning
+ * void-or-promise, and an optional timeout. Liveness checks kill the pod;
+ * readiness checks only flip the load-balancer signal.
+ */
+export interface HealthCheck {
+    readonly name: string;
+    readonly check: () => Promise<void> | void;
+    /** Per-check timeout in ms. Default 5_000. */
+    readonly timeout?: number;
+    /**
+     * Marks the check as `liveness` (kills the pod when it fails) vs the
+     * default `readiness` (just removes from rotation). Liveness checks
+     * should be cheap and only fail when the process is genuinely broken.
+     */
+    readonly kind?: "readiness" | "liveness";
+}
+/** Factory for a HealthCheck. Use to register checks from inside plugins/providers. */
+export declare function defineCheck(name: string, check: () => Promise<void> | void, opts?: Omit<HealthCheck, "name" | "check">): HealthCheck;
+/** Timing budgets for graceful shutdown. All in milliseconds. */
+export interface ShutdownConfig {
+    /** ms to wait after marking not-ready before stopping listen. Default 10_000. */
+    readonly drainDelay?: number;
+    /** ms to wait for in-flight requests to finish. Default 30_000. */
+    readonly drainTimeout?: number;
+    /** ms total budget before SIGKILL. Default 45_000. */
+    readonly hardTimeout?: number;
+    /**
+     * Run-after-drain hook — close DBs, Redis, queues, etc. The endpoint
+     * wires this to plugin/provider shutdown in reverse boot order when an
+     * app is served.
+     */
+    readonly onShutdown?: () => Promise<void> | void;
+}
+/** Operational HTTP server config — exposes readiness/liveness probes. */
+export interface HealthConfig {
+    /** Disable lightship entirely. Default `true` (enabled). */
+    readonly enabled?: boolean;
+    /**
+     * Port for the operational endpoints. Default `9_400`.
+     *
+     * Moved off the historic `9_000` because that's claimed by MinIO's S3
+     * API (and several other common dev services). `9_400` is in a quiet
+     * IANA range and doesn't collide with anything in our docker-compose.
+     */
+    readonly port?: number;
+    /**
+     * **Documentation-only** — lightship hardcodes its endpoints to `/live`
+     * and `/ready`; these fields are accepted for API back-compat but DO
+     * NOT actually change the paths. Track lightship upstream for a fix
+     * (or replace lightship with a custom probe server if path customization
+     * becomes important enough to own).
+     */
+    readonly livenessPath?: string;
+    /** See `livenessPath` — documentation-only. Lightship serves `/ready`. */
+    readonly readinessPath?: string;
+    readonly checks?: readonly HealthCheck[];
+}
+/** What `attachLifecycle()` returns — control surface for tests and dynamic checks. */
+export interface LifecycleManager {
+    /** Mark the process ready — call once the HTTP server is listening. */
+    ready(): void;
+    /**
+     * Run the full shutdown sequence: flip readiness → drain → close →
+     * onShutdown → exit. Idempotent; subsequent calls are no-ops.
+     */
+    shutdown(reason: string): Promise<void>;
+    /**
+     * Add a health check after the lifecycle was created — used by
+     * providers/plugins to register their own probes.
+     */
+    addCheck(check: HealthCheck): void;
+    /** The lightship instance, if enabled — for advanced/test access. */
+    readonly lightship?: Lightship;
+}
+/**
+ * Attach the graceful-shutdown lifecycle to a running HTTP server.
+ *
+ * Returns a `LifecycleManager` whose `shutdown()` flips readiness,
+ * drains the server, runs `onShutdown`, and exits. Wires `SIGTERM` and
+ * `SIGINT` to `shutdown()` automatically (via `process.once(...)`, so
+ * manual `shutdown()` calls during tests don't fight with signal-driven ones).
+ */
+export declare function attachLifecycle(opts: {
+    readonly server: Server;
+    readonly shutdown?: ShutdownConfig;
+    readonly health?: HealthConfig;
+    /** Test seam — set to false to skip process.exit() at the end. */
+    readonly exitOnShutdown?: boolean;
+}): Promise<LifecycleManager>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,UAAU,CAAC;CAC1C;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACjC,IAAI,GAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAM,GAC7C,WAAW,CAEb;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClD;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,KAAK,IAAI,IAAI,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgJ5B"}

package/dist/lifecycle.js

@@ -0,0 +1,176 @@
+/**
+ * Graceful runtime lifecycle — boot + readiness + shutdown orchestration.
+ *
+ * Composes two battle-tested libraries:
+ *
+ *   - **http-terminator** — properly drains keep-alive connections during
+ *     `server.close()`. Without it, in-flight requests on persistent
+ *     connections silently die when the process exits.
+ *   - **lightship**       — Kubernetes-style readiness/liveness probes on a
+ *     separate operational port. Flips `/readyz` to 503 the moment shutdown
+ *     starts so the load balancer stops sending new traffic — the single
+ *     most important step in a zero-downtime rolling deploy.
+ *
+ * Sequence on SIGTERM/SIGINT:
+ *
+ *   1. lightship: /readyz → 503        (LB removes us from rotation)
+ *   2. wait `drainDelay`               (LB has time to catch up; default 10s)
+ *   3. stop accepting new connections  (http-terminator)
+ *   4. drain in-flight requests        (http-terminator; bounded by drainTimeout)
+ *   5. run user `onShutdown` hooks     (close DBs, Redis, queues — in reverse boot order)
+ *   6. flush logs, exit 0              (or 1 if hardTimeout breached → SIGKILL)
+ *
+ * The whole sequence is bounded by `hardTimeout` — if shutdown takes
+ * longer, the process self-kills so the orchestrator doesn't wait forever.
+ *
+ * This module is intentionally framework-agnostic: it takes a Node `Server`
+ * and wraps it. Use it with any HTTP framework — Express, Fastify, Koa, Nest,
+ * Hono, or a raw `http.createServer` listener. The high-level
+ * `endpoint(name, config).serve(target).run()` wrapper composes this with
+ * server-construction for the common cases.
+ */
+import { createHttpTerminator } from "http-terminator";
+import { createLightship } from "lightship";
+/** Factory for a HealthCheck. Use to register checks from inside plugins/providers. */
+export function defineCheck(name, check, opts = {}) {
+    return { name, check, ...opts };
+}
+/**
+ * Attach the graceful-shutdown lifecycle to a running HTTP server.
+ *
+ * Returns a `LifecycleManager` whose `shutdown()` flips readiness,
+ * drains the server, runs `onShutdown`, and exits. Wires `SIGTERM` and
+ * `SIGINT` to `shutdown()` automatically (via `process.once(...)`, so
+ * manual `shutdown()` calls during tests don't fight with signal-driven ones).
+ */
+export async function attachLifecycle(opts) {
+    const shutdownCfg = {
+        drainDelay: opts.shutdown?.drainDelay ?? 10_000,
+        drainTimeout: opts.shutdown?.drainTimeout ?? 30_000,
+        hardTimeout: opts.shutdown?.hardTimeout ?? 45_000,
+        onShutdown: opts.shutdown?.onShutdown ?? (() => undefined),
+    };
+    const healthCfg = {
+        enabled: opts.health?.enabled ?? true,
+        port: opts.health?.port ?? 9_400,
+        livenessPath: opts.health?.livenessPath ?? "/healthz",
+        readinessPath: opts.health?.readinessPath ?? "/readyz",
+        checks: opts.health?.checks ?? [],
+    };
+    const terminator = createHttpTerminator({
+        server: opts.server,
+        gracefulTerminationTimeout: shutdownCfg.drainTimeout,
+    });
+    /**
+     * Lightship binds its own operational HTTP server on a separate port.
+     * It's the right move — operational concerns shouldn't share rate
+     * limits / middleware with app traffic. `createLightship` is async
+     * because it binds to a port.
+     */
+    let lightship;
+    if (healthCfg.enabled) {
+        try {
+            lightship = await createLightship({
+                port: healthCfg.port,
+                detectKubernetes: false, // we own the lifecycle; don't auto-detect
+                shutdownDelay: shutdownCfg.drainDelay,
+                shutdownHandlerTimeout: shutdownCfg.drainTimeout,
+                gracefulShutdownTimeout: shutdownCfg.hardTimeout,
+            });
+        }
+        catch (err) {
+            // EADDRINUSE on the probe port is the common dev case (another
+            // dev process, MinIO on 9_000, etc). Don't crash the data port —
+            // log clearly and run without lightship. K8s probes will fail
+            // until the user moves the port; that's the right signal.
+            const code = err.code;
+            if (code === "EADDRINUSE") {
+                console.warn(`[lifecycle] probe port :${healthCfg.port} already in use — probes disabled. ` +
+                    `Override with \`probes: { port: <other> }\` on endpoint().`);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    const dynamicChecks = [...healthCfg.checks];
+    let shuttingDown = false;
+    /** Run every registered check; returns true only if all pass. */
+    const runChecks = async () => {
+        if (!lightship)
+            return true;
+        for (const c of dynamicChecks) {
+            const timeout = c.timeout ?? 5_000;
+            try {
+                await Promise.race([
+                    Promise.resolve(c.check()),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`check '${c.name}' timed out after ${timeout}ms`)), timeout)),
+                ]);
+            }
+            catch (err) {
+                console.error(`[lifecycle] readiness check '${c.name}' failed:`, err.message);
+                lightship.signalNotReady();
+                return false;
+            }
+        }
+        return true;
+    };
+    const ready = () => {
+        if (!lightship)
+            return;
+        void runChecks().then((ok) => {
+            if (!shuttingDown && ok)
+                lightship.signalReady();
+        });
+    };
+    const shutdown = async (reason) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(`[lifecycle] shutdown initiated (${reason})`);
+        // Hard timeout — last-ditch SIGKILL if anything below hangs.
+        const hardKill = setTimeout(() => {
+            console.error(`[lifecycle] hard timeout (${shutdownCfg.hardTimeout}ms) — forcing exit`);
+            if (opts.exitOnShutdown !== false)
+                process.exit(1);
+        }, shutdownCfg.hardTimeout);
+        hardKill.unref(); // don't keep the loop alive on its own
+        try {
+            if (lightship) {
+                lightship.signalNotReady();
+                console.log(`[lifecycle] /readyz → 503; waiting ${shutdownCfg.drainDelay}ms for LB to catch up`);
+            }
+            await new Promise((r) => setTimeout(r, shutdownCfg.drainDelay));
+            console.log(`[lifecycle] draining in-flight requests`);
+            await terminator.terminate();
+            console.log(`[lifecycle] running onShutdown`);
+            await shutdownCfg.onShutdown();
+            if (lightship) {
+                await lightship.shutdown();
+            }
+            console.log(`[lifecycle] shutdown complete`);
+        }
+        catch (err) {
+            console.error(`[lifecycle] shutdown error:`, err);
+        }
+        finally {
+            clearTimeout(hardKill);
+            if (opts.exitOnShutdown !== false) {
+                setImmediate(() => process.exit(0));
+            }
+        }
+    };
+    process.once("SIGTERM", () => void shutdown("SIGTERM"));
+    process.once("SIGINT", () => void shutdown("SIGINT"));
+    return {
+        ready,
+        shutdown,
+        addCheck: (c) => {
+            dynamicChecks.push(c);
+        },
+        get lightship() {
+            return lightship;
+        },
+    };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nwire/endpoint",
+  "version": "0.7.0",
+  "description": "Nwire — production process lifecycle. Wraps any Node server (Express, Fastify, Koa, Nest, Nwire interfaces) with K8s-grade graceful shutdown, http-terminator drain, and lightship readiness/liveness probes. Standalone — no framework dependency beyond @nwire/container.",
+  "keywords": [
+    "endpoint",
+    "graceful-shutdown",
+    "health-check",
+    "k8s",
+    "kubernetes",
+    "lifecycle",
+    "nwire"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/endpoint-index.js",
+  "types": "./dist/endpoint-index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/endpoint-index.js",
+      "types": "./dist/endpoint-index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "http-terminator": "^3.2.0",
+    "lightship": "^9.0.4",
+    "@nwire/container": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}