@nanobpm/urban 0.45.1 → 0.46.0

package/dist/runtime/adapters/node.js

@@ -229,11 +229,33 @@ async function startNodeServer(port, handler) {
             nres.end(String(err));
         }
     });
+    // Track every raw TCP socket so `stop()` can force teardown. `server.close()` only
+    // stops accepting new connections and waits for existing ones to end; a lingering
+    // long-lived socket would keep it pending forever and hang `app.stop()`. Now that we
+    // expose `native` for same-port WebSocket upgrades, that is a real risk — and
+    // `server.closeAllConnections()` does NOT cover sockets that have already been
+    // upgraded (they are detached from the server's HTTP connection tracking after the
+    // `upgrade` event). The underlying TCP socket from the `connection` event is the same
+    // object that a later upgrade reuses, so destroying those is what actually unblocks
+    // shutdown regardless of what an upgrade handler left open. Attach the listener
+    // BEFORE `listen()` so no connection can slip through untracked in the window between
+    // the server accepting sockets and the tracker being wired up.
+    const sockets = new Set();
+    server.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+    });
     await new Promise((res) => server.listen(port, res));
     const addr = server.address();
     const actualPort = typeof addr === "object" && addr ? addr.port : port;
     return {
         port: actualPort,
-        stop: () => new Promise((res) => server.close(() => res())),
+        stop: () => new Promise((res) => {
+            server.close(() => res());
+            for (const socket of sockets)
+                socket.destroy();
+            sockets.clear();
+        }),
+        native: server,
     };
 }

package/dist/runtime/core/host.d.ts

@@ -20,6 +20,16 @@ export type HttpHandler = (req: HttpRequest) => Promise<HttpResponse> | HttpResp
 export interface HttpServer {
     readonly port: number;
     stop(): Promise<void>;
+    /**
+     * The host's native server object, when it exposes one — the Node adapter's `node:http` `Server`.
+     * Lets an app attach a WebSocket upgrade (e.g. `ws`'s `WebSocketServer({ server })`) to the *same*
+     * port the app already serves. `undefined` on hosts that don't surface an upgradeable server object
+     * (the Deno adapter, whose WS story is `upgradeWebSocket` on the Deno global in the request
+     * handler). Typed
+     * `unknown` because this is the host-adapter boundary — the consumer narrows it with a runtime
+     * check (e.g. `instanceof Server`) before use, rather than a type assertion.
+     */
+    readonly native?: unknown;
 }
 /** A handle to an active filesystem watch; call close() to stop watching. */
 export interface WatchHandle {

package/dist/runtime/core/modules/pages.js

@@ -482,14 +482,17 @@ body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64r
 .pc-msg { font-size:.85rem; margin-top:.5rem; min-height:1.2em; }
 .pc-msg.err { color:var(--nano-danger); }
 .pc-msg.ok { color:var(--nano-ok); }
-table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; }
-/* Wrap long, space-less cell values (e.g. a JSON blob or a 40-char SHA) so one
-   cell can't force its column wide and blow the whole table past the page.
-   overflow-wrap:anywhere reduces the cell's min-content width so the auto table
-   layout can shrink it to fit; max-width caps a single column when there is
-   ample room. vertical-align:top keeps a multi-line cell aligned with its
-   single-line neighbours. */
-table.pc-grid th, table.pc-grid td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--nano-edge); overflow-wrap:anywhere; word-wrap:break-word; max-width:32rem; vertical-align:top; }
+table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; table-layout:fixed; }
+/* table-layout:fixed divides the available width across columns and wraps text
+   within each, so a grid with several long free-text columns (e.g. the epic
+   detail's coordination-notes / trial-merge-results) can't sum its columns'
+   content widths past the page — the failure mode of table-layout:auto, where a
+   per-cell max-width let two wide columns each claim ~32rem and overrun the page.
+   overflow-wrap:anywhere additionally breaks space-less tokens (a 40-char SHA, a
+   JSON blob) so they wrap inside the column instead of forcing a scrollbar.
+   vertical-align:top keeps a multi-line cell aligned with its single-line
+   neighbours. */
+table.pc-grid th, table.pc-grid td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--nano-edge); overflow-wrap:anywhere; word-wrap:break-word; vertical-align:top; }
 table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-tabs { display:flex; gap:.5rem; margin-bottom:.75rem; }
 .pc-tab { padding:.35rem .8rem; border:1px solid var(--nano-edge); border-radius:.4rem; background:transparent; color:inherit; font:inherit; cursor:pointer; }

package/dist/runtime/core/runtime.d.ts

@@ -65,5 +65,14 @@ export interface UrbanApp {
     readonly data: DataLayer | undefined;
     readonly security: SecurityPolicy | undefined;
     readonly httpPort: number | undefined;
+    /**
+     * The runtime's native HTTP server object once `start()` has bound it (the Node adapter's
+     * `node:http` `Server`), for attaching a WebSocket upgrade on the app's *own* port. Snapshot it
+     * into a local `const` and narrow that with a runtime `instanceof` check before use (no type
+     * assertion needed) — reading the property again after the check would not narrow — e.g.
+     * `const { Server } = await import("node:http"); const server = app.httpServer; if (server instanceof Server) new WebSocketServer({ server, path: "/agentic" });`.
+     * `undefined` before `start()`, after `stop()`, and on hosts that don't surface one (Deno).
+     */
+    readonly httpServer: object | undefined;
 }
 export declare function createUrbanApp(opts: CreateUrbanAppOptions): Promise<UrbanApp>;

package/dist/runtime/core/runtime.js

@@ -114,6 +114,10 @@ export async function createUrbanApp(opts) {
         get httpPort() {
             return httpPort;
         },
+        get httpServer() {
+            const native = server?.native;
+            return typeof native === "object" && native !== null ? native : undefined;
+        },
         async start() {
             if (started)
                 throw new Error("app already started");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.45.1",
+	"version": "0.46.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/adapters/node.ts

@@ -5,6 +5,7 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { watch as fsWatch, type FSWatcher } from "node:fs";
 import { createServer } from "node:http";
+import type { Socket } from "node:net";
 import { register } from "node:module";
 import { isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -246,11 +247,33 @@ async function startNodeServer(port: number, handler: HttpHandler): Promise<Http
       nres.end(String(err));
     }
   });
+  // Track every raw TCP socket so `stop()` can force teardown. `server.close()` only
+  // stops accepting new connections and waits for existing ones to end; a lingering
+  // long-lived socket would keep it pending forever and hang `app.stop()`. Now that we
+  // expose `native` for same-port WebSocket upgrades, that is a real risk — and
+  // `server.closeAllConnections()` does NOT cover sockets that have already been
+  // upgraded (they are detached from the server's HTTP connection tracking after the
+  // `upgrade` event). The underlying TCP socket from the `connection` event is the same
+  // object that a later upgrade reuses, so destroying those is what actually unblocks
+  // shutdown regardless of what an upgrade handler left open. Attach the listener
+  // BEFORE `listen()` so no connection can slip through untracked in the window between
+  // the server accepting sockets and the tracker being wired up.
+  const sockets = new Set<Socket>();
+  server.on("connection", (socket) => {
+    sockets.add(socket);
+    socket.once("close", () => sockets.delete(socket));
+  });
   await new Promise<void>((res) => server.listen(port, res));
   const addr = server.address();
   const actualPort = typeof addr === "object" && addr ? addr.port : port;
   return {
     port: actualPort,
-    stop: () => new Promise<void>((res) => server.close(() => res())),
+    stop: () =>
+      new Promise<void>((res) => {
+        server.close(() => res());
+        for (const socket of sockets) socket.destroy();
+        sockets.clear();
+      }),
+    native: server,
   };
 }

package/src/runtime/core/host.ts

@@ -28,6 +28,16 @@ export type HttpHandler = (req: HttpRequest) => Promise<HttpResponse> | HttpResp
 export interface HttpServer {
   readonly port: number;
   stop(): Promise<void>;
+  /**
+   * The host's native server object, when it exposes one — the Node adapter's `node:http` `Server`.
+   * Lets an app attach a WebSocket upgrade (e.g. `ws`'s `WebSocketServer({ server })`) to the *same*
+   * port the app already serves. `undefined` on hosts that don't surface an upgradeable server object
+   * (the Deno adapter, whose WS story is `upgradeWebSocket` on the Deno global in the request
+   * handler). Typed
+   * `unknown` because this is the host-adapter boundary — the consumer narrows it with a runtime
+   * check (e.g. `instanceof Server`) before use, rather than a type assertion.
+   */
+  readonly native?: unknown;
 }
 
 /** A handle to an active filesystem watch; call close() to stop watching. */

package/src/runtime/core/modules/pages.test.ts

@@ -154,18 +154,25 @@ test("the warn badge stays legible in light appearance", async () => {
   );
 });
 
-test("grid cells wrap long, space-less values so one cell can't overflow the table", async () => {
-  // Regression: a dataGrid cell holding a long space-less value (e.g. a JSON
-  // blob or a 40-char SHA) has no soft-wrap opportunity, so with table-layout
-  // auto it forces its column to the value's full width and pushes the whole
-  // table past the page. The shared grid CSS must let such a cell break so the
-  // column can shrink to fit its container.
+test("grid uses fixed layout + wrapping so several wide columns can't overflow the page", async () => {
+  // Regression: with table-layout:auto a per-cell max-width let two long
+  // free-text columns (e.g. the epic detail's coordination-notes files+note, or
+  // trial-merge-results heads+conflicts+failing+summary) each claim ~32rem, and
+  // their summed content widths overran the page's width regardless of the
+  // viewport. table-layout:fixed divides the width across columns and wraps text
+  // within each; overflow-wrap:anywhere still breaks space-less tokens (a 40-char
+  // SHA, a JSON blob) inside the column instead of forcing a horizontal scrollbar.
   const res = await dispatch("GET", "/");
   const html = res.body ?? "";
-  const rule = (html.match(/table\.pc-grid th,\s*table\.pc-grid td\s*\{[^}]*\}/) ?? [""])[0];
-  assert.ok(rule, "grid th/td rule must be present");
-  assert.match(rule, /overflow-wrap:anywhere/);
-  assert.match(rule, /max-width:/);
+  const tableRule = (html.match(/table\.pc-grid\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(tableRule, "table.pc-grid rule must be present");
+  assert.match(tableRule, /table-layout:\s*fixed/);
+  const cellRule = (html.match(/table\.pc-grid th,\s*table\.pc-grid td\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(cellRule, "grid th/td rule must be present");
+  assert.match(cellRule, /overflow-wrap:anywhere/);
+  // The per-cell max-width cap was the root cause of the overflow: guard against
+  // any future change silently reintroducing it (which would pass the checks above).
+  assert.doesNotMatch(cellRule, /max-width:/);
 });
 
 test("GET /app/runtime.js serves the renderer module", async () => {

package/src/runtime/core/modules/pages.ts

@@ -533,14 +533,17 @@ body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64r
 .pc-msg { font-size:.85rem; margin-top:.5rem; min-height:1.2em; }
 .pc-msg.err { color:var(--nano-danger); }
 .pc-msg.ok { color:var(--nano-ok); }
-table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; }
-/* Wrap long, space-less cell values (e.g. a JSON blob or a 40-char SHA) so one
-   cell can't force its column wide and blow the whole table past the page.
-   overflow-wrap:anywhere reduces the cell's min-content width so the auto table
-   layout can shrink it to fit; max-width caps a single column when there is
-   ample room. vertical-align:top keeps a multi-line cell aligned with its
-   single-line neighbours. */
-table.pc-grid th, table.pc-grid td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--nano-edge); overflow-wrap:anywhere; word-wrap:break-word; max-width:32rem; vertical-align:top; }
+table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; table-layout:fixed; }
+/* table-layout:fixed divides the available width across columns and wraps text
+   within each, so a grid with several long free-text columns (e.g. the epic
+   detail's coordination-notes / trial-merge-results) can't sum its columns'
+   content widths past the page — the failure mode of table-layout:auto, where a
+   per-cell max-width let two wide columns each claim ~32rem and overrun the page.
+   overflow-wrap:anywhere additionally breaks space-less tokens (a 40-char SHA, a
+   JSON blob) so they wrap inside the column instead of forcing a scrollbar.
+   vertical-align:top keeps a multi-line cell aligned with its single-line
+   neighbours. */
+table.pc-grid th, table.pc-grid td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--nano-edge); overflow-wrap:anywhere; word-wrap:break-word; vertical-align:top; }
 table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-tabs { display:flex; gap:.5rem; margin-bottom:.75rem; }
 .pc-tab { padding:.35rem .8rem; border:1px solid var(--nano-edge); border-radius:.4rem; background:transparent; color:inherit; font:inherit; cursor:pointer; }

package/src/runtime/core/runtime.test.ts

@@ -1,5 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import * as http from "node:http";
 import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -226,6 +227,145 @@ test("app.sdk is undefined when the engine exposes no SDK client", async () => {
   }
 });
 
+test("exposes the native http server for a same-port WebSocket upgrade", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+
+  // undefined before start
+  const httpServerBeforeStart = app.httpServer;
+  assert.equal(httpServerBeforeStart, undefined);
+
+  await app.start();
+  try {
+    // the live node:http Server, on the app's own port — narrow the getter's `object | undefined`
+    // to a concrete server with runtime checks (no type assertion needed).
+    const server = app.httpServer;
+    if (server === undefined) throw new Error("httpServer should be defined after start");
+    assert.ok(server instanceof http.Server, "httpServer is a node:http Server after start");
+
+    // an attached 'upgrade' handler completes a WebSocket handshake on the app's port —
+    // exactly what @nanobpm/agentic's WebSocketChannelTransport({ server }) needs.
+    server.on("upgrade", (_req, socket) => {
+      socket.write(
+        "HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n\r\n",
+      );
+      socket.destroy();
+    });
+
+    const upgraded = await new Promise<boolean>((resolve, reject) => {
+      const req = http.request({
+        port: app.httpPort!,
+        path: "/agentic",
+        headers: { Connection: "Upgrade", Upgrade: "websocket" },
+      });
+      // fail fast rather than hang the runner if the handshake never happens
+      const timer = setTimeout(() => {
+        req.destroy();
+        reject(new Error("upgrade handshake timed out"));
+      }, 5000);
+      req.on("upgrade", (_res, socket) => {
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(true);
+      });
+      // a plain HTTP response means the server did NOT upgrade — surface it clearly
+      req.on("response", (res) => {
+        clearTimeout(timer);
+        res.resume();
+        req.destroy();
+        reject(new Error(`expected upgrade, got HTTP ${res.statusCode}`));
+      });
+      req.on("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+      req.end();
+    });
+    assert.equal(upgraded, true, "upgrade handshake completed on the app port");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+
+  // undefined again after stop
+  assert.equal(app.httpServer, undefined);
+});
+
+test("stop() completes promptly even with a lingering upgraded socket", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+
+  await app.start();
+  const openSockets: import("node:stream").Duplex[] = [];
+  try {
+    const server = app.httpServer;
+    if (server === undefined) throw new Error("httpServer should be defined after start");
+    assert.ok(server instanceof http.Server, "httpServer is a node:http Server after start");
+
+    // Complete the handshake but deliberately KEEP the upgraded socket open on both
+    // ends — this is exactly the long-lived WebSocket case that would make a plain
+    // `server.close()` hang forever.
+    server.on("upgrade", (_req, socket) => {
+      openSockets.push(socket);
+      socket.write(
+        "HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n\r\n",
+      );
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      const req = http.request({
+        port: app.httpPort!,
+        path: "/agentic",
+        headers: { Connection: "Upgrade", Upgrade: "websocket" },
+      });
+      const timer = setTimeout(() => {
+        req.destroy();
+        reject(new Error("upgrade handshake timed out"));
+      }, 5000);
+      req.on("upgrade", (_res, socket) => {
+        clearTimeout(timer);
+        openSockets.push(socket);
+        resolve();
+      });
+      req.on("response", (res) => {
+        clearTimeout(timer);
+        res.resume();
+        req.destroy();
+        reject(new Error(`expected upgrade, got HTTP ${res.statusCode}`));
+      });
+      req.on("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+      req.end();
+    });
+
+    // stop() must resolve without waiting on the still-open upgraded socket.
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("app.stop() hung on an open upgraded socket")), 5000);
+      app.stop().then(
+        () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+      );
+    });
+
+    assert.equal(app.httpServer, undefined, "httpServer is undefined after stop");
+  } finally {
+    for (const s of openSockets) s.destroy();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("stop() resets state so the app can be cleanly restarted", async () => {
   const dir = await makeFixture();
   const host = createNodeHost({ cwd: dir, log: () => {} });

package/src/runtime/core/runtime.ts

@@ -108,6 +108,15 @@ export interface UrbanApp {
   readonly data: DataLayer | undefined;
   readonly security: SecurityPolicy | undefined;
   readonly httpPort: number | undefined;
+  /**
+   * The runtime's native HTTP server object once `start()` has bound it (the Node adapter's
+   * `node:http` `Server`), for attaching a WebSocket upgrade on the app's *own* port. Snapshot it
+   * into a local `const` and narrow that with a runtime `instanceof` check before use (no type
+   * assertion needed) — reading the property again after the check would not narrow — e.g.
+   * `const { Server } = await import("node:http"); const server = app.httpServer; if (server instanceof Server) new WebSocketServer({ server, path: "/agentic" });`.
+   * `undefined` before `start()`, after `stop()`, and on hosts that don't surface one (Deno).
+   */
+  readonly httpServer: object | undefined;
 }
 
 export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<UrbanApp> {
@@ -193,6 +202,10 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
     get httpPort() {
       return httpPort;
     },
+    get httpServer(): object | undefined {
+      const native = server?.native;
+      return typeof native === "object" && native !== null ? native : undefined;
+    },
 
     async start() {
       if (started) throw new Error("app already started");

package/src/runtime/devserver.test.ts

@@ -231,6 +231,7 @@ function fakeApp(stops: string[], id: string): UrbanApp {
     data: undefined,
     security: undefined,
     httpPort: undefined,
+    httpServer: undefined,
   };
 }