@nwire/endpoint 0.12.1 → 0.13.1

package/dist/adapter.d.ts

@@ -9,6 +9,7 @@
  *
  * `endpoint("api").use(adopter).mount(source).run()` is the nwire path.
  */
+import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Wire } from "@nwire/wires";
 import type { Container } from "@nwire/container";
 import type { Logger } from "@nwire/logger";
@@ -82,6 +83,29 @@ export interface Adapter {
      * adopters or before boot.
      */
     port?(): number | undefined;
+    /**
+     * Optional — a host-mountable `(req, res)` handler, available after
+     * `boot()`. HTTP-class adapters return their composed handler (koa's
+     * `.callback()`, the Express app, …) so a single in-process host (the
+     * one-Vite dev host, supertest) can mount the wire as middleware without
+     * binding a port. Non-HTTP adapters (queue, cron, nats, mcp) return
+     * `undefined` — they just run in-process. Transport-agnostic: the
+     * endpoint composes these without knowing which transport produced them.
+     */
+    handler?(): ((req: IncomingMessage, res: ServerResponse) => void) | undefined;
+    /**
+     * Optional — does this adapter own the given URL path? Available after
+     * `boot()`. The one-Vite dev host calls this to route deterministically:
+     * paths the wire owns (its route prefix + well-known surfaces like
+     * `/openapi.json`, `/docs`, `/_nwire/*`) go to the wire's handler; every
+     * other path (`/`, Studio assets, Studio deep links) goes to Studio. This
+     * removes the response-sniffing heuristic for the common case — a wire with
+     * adopter-wide auth no longer 401s `/` and shadows Studio.
+     *
+     * Returns `undefined`/absent for adapters that don't compute ownership; the
+     * host then falls back to running the handler and detecting a pass-through.
+     */
+    owns?(pathname: string): boolean;
 }
 /** Type narrow — is this an Adapter? */
 export declare function isAdapter(x: unknown): x is Adapter;

package/dist/endpoint-index.d.ts

@@ -19,6 +19,6 @@
  * (`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, type AppServable, type EndpointConfig, type ProcessConfig, type ForeignServable, type RunningEndpoint, type Servable, } from "./endpoint.js";
+export { endpoint, EndpointBuilder, isAppServable, isForeignServable, type AppServable, type EndpointConfig, type ProcessConfig, type ForeignServable, type RunningEndpoint, type Servable, type DevHostMount, type DevHostCollector, } from "./endpoint.js";
 export { attachLifecycle, defineCheck, type HealthCheck, type HealthConfig, type LifecycleManager, type ShutdownConfig, } from "./lifecycle.js";
 export { isAdapter, type Adapter, type AdapterBootContext } from "./adapter.js";

package/dist/endpoint.d.ts

@@ -34,7 +34,7 @@
  * 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 Server, type IncomingMessage, type ServerResponse } from "node:http";
 import type { Container } from "@nwire/container";
 import type { Interface } from "@nwire/wires";
 import { type HealthConfig, type LifecycleManager, type ShutdownConfig } from "./lifecycle.js";
@@ -135,10 +135,38 @@ export type ProcessConfig = EndpointConfig;
 export interface RunningEndpoint {
     readonly name: string;
     readonly server?: Server;
-    readonly lifecycle: LifecycleManager;
-    /** Trigger shutdown manually. Idempotent. */
+    /**
+     * The lifecycle manager — present for a normal `.run()`. Absent in dev-host
+     * mode, where the Vite host owns the process (no probes / signal handling).
+     */
+    readonly lifecycle?: LifecycleManager;
+    /** Trigger shutdown manually. Idempotent. Drains adapters, then apps. */
     shutdown(reason?: string): Promise<void>;
 }
+/**
+ * What a dev host collects from each `.run()` it loads (one Vite host mode).
+ * The host registers a collector on `globalThis.__nwireDevHost`; the endpoint
+ * boots port-less and hands over the booted app(s) + each adapter's mounted
+ * `(req, res)` handler so the host can mount the wire as middleware and read
+ * the in-process runtime directly. See the dev-host branch in `run()`.
+ */
+export interface DevHostMount {
+    readonly name: string;
+    readonly apps: readonly AppServable[];
+    readonly handlers: ReadonlyArray<(req: IncomingMessage, res: ServerResponse) => void>;
+    /**
+     * Does this endpoint's wire own the given URL path? OR of each HTTP adapter's
+     * `owns(pathname)`. Present only when at least one adapter computes ownership;
+     * the host routes owned paths to the wire and everything else to Studio. When
+     * absent, the host falls back to running handlers + detecting a pass-through.
+     */
+    readonly owns?: (pathname: string) => boolean;
+    /** Drain this endpoint's adapters (reverse) then its apps. Host calls on close/HMR. */
+    readonly shutdown: (reason?: string) => Promise<void>;
+}
+export interface DevHostCollector {
+    collect(mount: DevHostMount): void;
+}
 /**
  * Build an endpoint. The returned builder is chainable: `.serve()` adds
  * apps + interfaces in declaration order; `.run()` boots and listens.

package/dist/endpoint.js

@@ -34,7 +34,7 @@
  * write the same K8s-readiness code on every project. It works alone —
  * install only this package and wrap any Node server.
  */
-import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpServer, } from "node:http";
 import { hook } from "@nwire/hooks";
 import { ConsoleLogger } from "@nwire/logger";
 import { attachLifecycle, } from "./lifecycle.js";
@@ -235,8 +235,15 @@ export class EndpointBuilder {
             phase: "serve",
             startedAt: new Date().toISOString(),
         });
+        // Dev-host mode (one Vite host): when a collector is registered on the
+        // global, the endpoint boots + mounts its adapters but binds NO port —
+        // httpKoa mounts its koa without listening (it only listens when a port
+        // is present), so the host can grab `adapter.koa().callback()` and mount
+        // the wire as middleware on its own single port. Foreign listeners and
+        // probes are skipped too. `main.ts` is unchanged: it still calls `.run()`.
+        const devHost = globalThis.__nwireDevHost;
         let server;
-        if (this.config.port !== undefined && this.foreignServables.length) {
+        if (!devHost && this.config.port !== undefined && this.foreignServables.length) {
             server = await startListener({
                 port: this.config.port,
                 host: this.config.host,
@@ -286,12 +293,48 @@ export class EndpointBuilder {
                 containerOf,
                 logger: adapterLogger,
                 addCheck: (c) => accumulatedChecks.push(c),
-                port: this.config.port,
+                // Dev-host: no port → adapters mount without binding.
+                port: devHost ? undefined : this.config.port,
                 host: this.config.host,
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 installSinkStage: installSinkStage,
             });
         }
+        // Dev-host: hand the booted app + each adapter's mounted handler to the
+        // collector and return without binding a port or a probe server — the
+        // Vite host mounts the handlers + reads the in-process runtime directly.
+        if (devHost) {
+            // Transport-agnostic: ask each adapter for its mountable handler via the
+            // contract. HTTP adapters (koa, express, …) return one; non-HTTP adapters
+            // return undefined and keep running in-process. The endpoint never names
+            // a transport.
+            const handlers = [];
+            const ownsFns = [];
+            for (const adopter of this.adapters) {
+                const h = adopter.handler?.();
+                if (h)
+                    handlers.push(h);
+                if (adopter.owns)
+                    ownsFns.push((p) => adopter.owns(p));
+            }
+            // OR each adapter's ownership so the host can route deterministically:
+            // owned paths → wire, everything else → Studio. Undefined when no adapter
+            // computes ownership — the host then runs handlers + sniffs a 404.
+            const owns = ownsFns.length > 0 ? (pathname) => ownsFns.some((f) => f(pathname)) : undefined;
+            // Drain like prod: adapters in reverse boot order (so non-HTTP transports
+            // — queue/cron/nats — that started in-process get torn down), then stop
+            // the apps. The host calls this on close / HMR reload.
+            const reverseAdapters = [...this.adapters].reverse();
+            const shutdown = async (reason) => {
+                for (const adopter of reverseAdapters)
+                    await adopter.shutdown(reason);
+                for (const app of this.apps)
+                    await app.stop?.();
+            };
+            devHost.collect({ name: this.name, apps: this.apps, handlers, owns, shutdown });
+            // No lifecycle manager in dev-host mode — the Vite host owns the process.
+            return { name: this.name, shutdown };
+        }
         // 3. Wrap the server (if any) with graceful shutdown + probes.
         const lifecycle = await attachLifecycle({
             server: server ?? (await makeProbeOnlyServer()),
@@ -363,7 +406,9 @@ export class EndpointBuilder {
                 name: this.name,
                 host: this.config.host ?? "0.0.0.0",
                 port: dataPort,
-                probePort: probesBound ? (this.config.probes?.port ?? 9_400) : undefined,
+                probePort: probesBound
+                    ? (this.config.probes?.port ?? (Number(process.env.PROBE_PORT) || 9_400))
+                    : undefined,
             });
         }
         return {

package/dist/lifecycle.js

@@ -52,7 +52,10 @@ export async function attachLifecycle(opts) {
     };
     const healthCfg = {
         enabled: opts.health?.enabled ?? true,
-        port: opts.health?.port ?? 9_400,
+        // Explicit config wins; else `$PROBE_PORT` (so the probe port is tunable
+        // without a code change — e.g. when :9400 is taken by another service);
+        // else the default. A non-numeric env value falls through to 9400.
+        port: opts.health?.port ?? (Number(process.env.PROBE_PORT) || 9_400),
         livenessPath: opts.health?.livenessPath ?? "/live",
         readinessPath: opts.health?.readinessPath ?? "/ready",
         checks: opts.health?.checks ?? [],
@@ -86,7 +89,7 @@ export async function attachLifecycle(opts) {
             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().`);
+                    `Override with \`probes: { port: <other> }\` on endpoint(), or set $PROBE_PORT.`);
             }
             else {
                 throw err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/endpoint",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "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",
@@ -32,11 +32,11 @@
   "dependencies": {
     "http-terminator": "^3.2.0",
     "lightship": "^9.0.4",
-    "@nwire/hooks": "0.12.1",
-    "@nwire/logger": "0.12.1",
-    "@nwire/runtime": "0.12.1",
-    "@nwire/container": "0.12.1",
-    "@nwire/wires": "0.12.1"
+    "@nwire/runtime": "0.13.1",
+    "@nwire/logger": "0.13.1",
+    "@nwire/wires": "0.13.1",
+    "@nwire/container": "0.13.1",
+    "@nwire/hooks": "0.13.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",