tina4-nodejs 3.13.34 → 3.13.36

package/packages/core/src/mcp.ts

@@ -18,6 +18,32 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+// Synchronous CommonJS-style require that works under real ESM (where the
+// bare `require` global is undefined). Dev-tool handlers are synchronous, so
+// they can't `await import()` — this gives them a working require. Mirrors the
+// pattern already used by the ORM adapters (mysql.ts, postgres.ts, etc.).
+const req = createRequire(import.meta.url);
+
+/**
+ * Require a sibling @tina4 workspace package (orm / swagger / frond) in a way
+ * that works whether we're running from source (monorepo, where the package's
+ * `exports` only exposes the TS `import` condition that `require()` can't see)
+ * or as an installed dependency (where the package name resolves directly).
+ *
+ * Tries the package name first; on failure falls back to the in-repo source
+ * path relative to this file (packages/core/src → packages/<name>/src). This
+ * is why `route_list`, `database_query`, `swagger_spec`, etc. work when a real
+ * MCP client hits /__dev/mcp from a from-source dev server.
+ */
+function reqSibling(pkg: "orm" | "swagger" | "frond"): Record<string, unknown> {
+  try {
+    return req(`@tina4/${pkg}`) as Record<string, unknown>;
+  } catch {
+    return req(`../../${pkg}/src/index.ts`) as Record<string, unknown>;
+  }
+}
 
 // ── Types ─────────────────────────────────────────────────────
 
@@ -34,7 +60,11 @@ export interface McpToolDefinition {
   name: string;
   description: string;
   inputSchema: JsonSchema;
-  handler: (args: Record<string, unknown>) => unknown;
+  // Handlers may be sync or async — the dispatch (`_handleToolsCall`) awaits the
+  // return value, so DB tools that hit the async Database wrapper resolve before
+  // the result is formatted. A sync handler's plain return passes through awaiting
+  // unchanged.
+  handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
 }
 
 export interface McpResourceDefinition {
@@ -251,7 +281,13 @@ export class McpServer {
     });
   }
 
-  handleMessage(rawData: string | Record<string, unknown>): string {
+  // Async since the DB dev-tool handlers (database_query/execute/tables/columns,
+  // migration_*, seed_table, project_overview) reach the Database wrapper on
+  // `globalThis.__tina4_db`, whose read/write methods are async. The handler is
+  // awaited below; sync handlers (the file/plan/route tools) are unaffected
+  // because awaiting a non-Promise resolves immediately. Returns a
+  // Promise<string> — every caller must await it.
+  async handleMessage(rawData: string | Record<string, unknown>): Promise<string> {
     let method: string;
     let params: Record<string, unknown>;
     let requestId: number | string | null;
@@ -278,7 +314,7 @@ export class McpServer {
     }
 
     try {
-      const result = handler(params);
+      const result = await handler(params);
       if (requestId === null) {
         return ""; // Notification — no response
       }
@@ -323,7 +359,7 @@ export class McpServer {
     return { tools };
   }
 
-  private _handleToolsCall(params: Record<string, unknown>): Record<string, unknown> {
+  private async _handleToolsCall(params: Record<string, unknown>): Promise<Record<string, unknown>> {
     const toolName = params.name as string | undefined;
     if (!toolName) {
       throw new Error("Missing tool name");
@@ -335,7 +371,9 @@ export class McpServer {
     }
 
     const args = (params.arguments as Record<string, unknown>) || {};
-    const result = tool.handler(args);
+    // Tool handlers may be async (the DB tools await the Database wrapper); a
+    // sync handler's plain return value passes through `await` unchanged.
+    const result = await tool.handler(args);
 
     // Format result as MCP content
     let content: { type: string; text: string }[];
@@ -412,7 +450,7 @@ export class McpServer {
     const ssePath = `${this.path}/sse`;
 
     router
-      .post(msgPath, (req: unknown, res: unknown) => {
+      .post(msgPath, async (req: unknown, res: unknown) => {
         const request = req as { body: unknown; url?: string };
         const response = res as ((data: unknown, status?: number, contentType?: string) => unknown);
         const body = request.body;
@@ -422,7 +460,7 @@ export class McpServer {
         } else {
           raw = typeof body === "string" ? body : String(body);
         }
-        const result = server.handleMessage(raw);
+        const result = await server.handleMessage(raw);
         if (!result) {
           return response("", 204);
         }
@@ -484,6 +522,7 @@ export class McpServer {
 // ── Decorator API ──────────────────────────────────────────────
 
 let _defaultServer: McpServer | null = null;
+let _defaultToolsRegistered = false;
 
 function _getDefaultServer(): McpServer {
   if (_defaultServer === null) {
@@ -492,6 +531,24 @@ function _getDefaultServer(): McpServer {
   return _defaultServer;
 }
 
+/**
+ * The default `/__dev/mcp` MCP server with the built-in dev tools registered.
+ *
+ * This is the single shared instance backing BOTH the browser REST shim
+ * (`/__dev/api/mcp/tools` + `/__dev/api/mcp/call`) and the JSON-RPC + SSE
+ * endpoints (`/__dev/mcp[/message]` + `/__dev/mcp/sse`) that real MCP clients
+ * (Claude Code/Desktop) speak. Tools are registered exactly once (idempotent).
+ * Mirrors Python's default MCP server used by `get_api_handlers()`.
+ */
+export function getDefaultDevServer(): McpServer {
+  const server = _getDefaultServer();
+  if (!_defaultToolsRegistered) {
+    registerDevTools(server);
+    _defaultToolsRegistered = true;
+  }
+  return server;
+}
+
 /**
  * Register a function as an MCP tool.
  *
@@ -787,13 +844,12 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "database_query",
-    (args) => {
+    async (args) => {
       try {
-        const { initDatabase } = require("@tina4/orm");
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
         const params = typeof args.params === "string" ? JSON.parse(args.params as string) : (args.params || []);
-        const result = db.fetch(args.sql as string, params);
+        const result = await db.fetch(args.sql as string, params);
         return { records: result.records || [], count: result.count || 0 };
       } catch (e) {
         return { error: (e as Error).message };
@@ -808,14 +864,14 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "database_execute",
-    (args) => {
+    async (args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
         const params = typeof args.params === "string" ? JSON.parse(args.params as string) : (args.params || []);
-        const result = db.execute(args.sql as string, params);
-        db.commit?.();
-        return { success: true, affected_rows: result?.count ?? 0 };
+        const result = await db.execute(args.sql as string, params);
+        await db.commit?.();
+        return { success: true, affected_rows: (result as any)?.count ?? 0 };
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -829,11 +885,11 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "database_tables",
-    (_args) => {
+    async (_args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        return db.getTables?.() ?? [];
+        return (await db.getTables?.()) ?? [];
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -844,11 +900,11 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "database_columns",
-    (args) => {
+    async (args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        return db.getColumns?.(args.table as string) ?? [];
+        return (await db.getColumns?.(args.table as string)) ?? [];
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -863,8 +919,16 @@ export function registerDevTools(server: McpServer): void {
     "route_list",
     (_args) => {
       try {
-        const { defaultRouter } = require("@tina4/core");
-        const routes = defaultRouter?.listRoutes?.() ?? [];
+        // Prefer the active server router (set by startServer) so file-discovered
+        // routes are included; startServer builds a fresh Router rather than using
+        // defaultRouter. Fall back to defaultRouter when no server is running.
+        // route_list lives inside @tina4/core, so reach the router via the local
+        // module — req("@tina4/core") depends on a built dist/ and fails under a
+        // from-source ESM runtime (the real MCP-client code path).
+        const { defaultRouter } = req("./router.js") as typeof import("./router.js");
+        const activeRouter = (globalThis as any).__tina4_router;
+        const router = activeRouter ?? defaultRouter;
+        const routes = router?.listRoutes?.() ?? [];
         return routes.map((r: any) => ({
           method: r.method || "",
           path: r.pattern || r.path || "",
@@ -901,10 +965,12 @@ export function registerDevTools(server: McpServer): void {
     "swagger_spec",
     (_args) => {
       try {
-        const { generateSpec } = require("@tina4/swagger");
-        return generateSpec?.() ?? { info: "Swagger not available" };
-      } catch {
-        return { info: "Swagger package not loaded" };
+        const { generate } = reqSibling("swagger") as { generate?: (routes: unknown[], models?: unknown) => unknown };
+        const { defaultRouter } = req("./router.js") as typeof import("./router.js");
+        const routes = defaultRouter?.getRoutes?.() ?? [];
+        return generate?.(routes, []) ?? { info: "Swagger not available" };
+      } catch (e) {
+        return { error: (e as Error).message };
       }
     },
     "Return the OpenAPI 3.0.3 JSON spec",
@@ -917,9 +983,11 @@ export function registerDevTools(server: McpServer): void {
     "template_render",
     (args) => {
       try {
-        const { renderTemplate } = require("@tina4/twig");
+        const { Frond } = reqSibling("frond") as { Frond?: new (dir?: string) => { renderString: (s: string, d?: Record<string, unknown>) => string } };
+        if (!Frond) return "Template engine not available";
         const data = typeof args.data === "string" ? JSON.parse(args.data as string) : (args.data || {});
-        return renderTemplate?.(args.template as string, data) ?? "Template engine not available";
+        const frond = new Frond(path.join(projectRoot, "src", "templates"));
+        return frond.renderString(args.template as string, data as Record<string, unknown>);
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -1066,7 +1134,7 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "migration_status",
-    (_args) => {
+    async (_args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
@@ -1099,7 +1167,7 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "migration_run",
-    (_args) => {
+    async (_args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
@@ -1118,7 +1186,7 @@ export function registerDevTools(server: McpServer): void {
     "queue_status",
     (args) => {
       try {
-        const { Queue } = require("@tina4/core");
+        const { Queue } = req("./queue.js") as typeof import("./queue.js");
         const topic = (args.topic as string) || "default";
         const q = new Queue({ topic });
         return {
@@ -1166,7 +1234,7 @@ export function registerDevTools(server: McpServer): void {
       // latest snapshot once available. The very first call may report the
       // pending placeholder; subsequent calls return live figures.
       try {
-        const mod = require("@tina4/core");
+        const mod = req("./cache.js") as typeof import("./cache.js");
         const stats = mod.cacheStats?.();
         if (stats && typeof stats.then === "function") {
           stats.then((s: unknown) => { _lastCacheStats = s as Record<string, unknown>; }).catch(() => {});
@@ -1222,12 +1290,9 @@ export function registerDevTools(server: McpServer): void {
     "error_log",
     (args) => {
       try {
-        const { DevAdmin } = require("@tina4/core");
-        const tracker = DevAdmin?.errorTracker;
-        if (tracker?.get) {
-          return tracker.get(args.limit || 20);
-        }
-        return [];
+        const { ErrorTracker } = req("./devAdmin.js") as typeof import("./devAdmin.js");
+        const limit = (args.limit as number) || 20;
+        return ErrorTracker.get().slice(0, limit);
       } catch {
         return [];
       }
@@ -1256,13 +1321,13 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "seed_table",
-    (args) => {
+    async (args) => {
       try {
-        const { seedTable } = require("@tina4/orm");
+        const { seedTable } = reqSibling("orm") as { seedTable?: (db: unknown, table: string, count: number) => number | Promise<number> };
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
         const count = (args.count as number) || 10;
-        const inserted = seedTable?.(db, args.table as string, count) ?? 0;
+        const inserted = (await seedTable?.(db, args.table as string, count)) ?? 0;
         return { table: args.table, inserted };
       } catch (e) {
         return { error: (e as Error).message };
@@ -1305,9 +1370,9 @@ export function registerDevTools(server: McpServer): void {
   // Ported from Python's tina4_python.mcp.tools — names match exactly.
   // The Plan storage format is byte-for-byte compatible across frameworks.
 
-  const loadPlan = () => require("./plan.js").Plan as typeof import("./plan.js").Plan;
+  const loadPlan = () => req("./plan.js").Plan as typeof import("./plan.js").Plan;
   const loadIndex = () =>
-    require("./projectIndex.js").ProjectIndex as typeof import("./projectIndex.js").ProjectIndex;
+    req("./projectIndex.js").ProjectIndex as typeof import("./projectIndex.js").ProjectIndex;
 
   server.registerTool(
     "plan_current",
@@ -1429,14 +1494,14 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "project_overview",
-    () => {
+    async () => {
       const out: Record<string, unknown> = {};
       try { out.index = loadIndex().overview(); } catch (e) { out.index = { error: (e as Error).message }; }
       try { out.plans = loadPlan().listPlans(); } catch (e) { out.plans = { error: (e as Error).message }; }
       try { out.current_plan = loadPlan().current(); } catch (e) { out.current_plan = { error: (e as Error).message }; }
       try {
         const db = (globalThis as any).__tina4_db;
-        out.tables = db?.getTables?.() ?? [];
+        out.tables = (await db?.getTables?.()) ?? [];
       } catch (e) { out.tables = { error: (e as Error).message }; }
       return out;
     },
@@ -1633,7 +1698,7 @@ export function registerDevTools(server: McpServer): void {
     "git_status",
     () => {
       try {
-        const { execFileSync } = require("node:child_process") as typeof import("node:child_process");
+        const { execFileSync } = req("node:child_process") as typeof import("node:child_process");
         const cwd = path.resolve(process.cwd());
         const run = (args: string[]): string => {
           return execFileSync("git", args, { cwd, timeout: 3000, encoding: "utf-8" }).toString().trim();
@@ -1685,7 +1750,7 @@ export function registerDevTools(server: McpServer): void {
     (args) => {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Docs } = require("./docs.js") as typeof import("./docs.js");
+        const { Docs } = req("./docs.js") as typeof import("./docs.js");
         return Docs.mcpSearch(
           (args.query as string) || "",
           parseInt(String(args.k ?? 5), 10) || 5,
@@ -1711,7 +1776,7 @@ export function registerDevTools(server: McpServer): void {
     (args) => {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Docs } = require("./docs.js") as typeof import("./docs.js");
+        const { Docs } = req("./docs.js") as typeof import("./docs.js");
         const spec = Docs.mcpClass((args.name as string) || "");
         return spec ?? { error: `class not found: ${args.name}` };
       } catch (e) {
@@ -1727,7 +1792,7 @@ export function registerDevTools(server: McpServer): void {
     (args) => {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Docs } = require("./docs.js") as typeof import("./docs.js");
+        const { Docs } = req("./docs.js") as typeof import("./docs.js");
         // PHP names the param `class`, Python names it `class_` — Node.js MCP
         // accepts the raw `class` field from the JSON-RPC payload.
         const cls = (args.class as string) || (args.class_name as string) || "";

package/packages/core/src/routeDiscovery.ts

@@ -11,6 +11,15 @@ const VALID_METHODS = new Set(["get", "post", "put", "delete", "patch"]);
  */
 const _seenFiles = new Set<string>();
 
+/**
+ * Last-seen mtime (ms) per route file. A file is (re)imported when it is new
+ * OR its mtime has increased since the previous scan — so editing an existing
+ * route file hot-reloads its handler instead of serving the stale one. The
+ * mtime also drives the import cache-bust query, so unchanged files don't
+ * needlessly re-execute.
+ */
+const _seenMtimes = new Map<string, number>();
+
 /** The last directory passed to discoverRoutes() — used by rediscoverRoutes(). */
 let _lastRoutesDir = "";
 
@@ -31,15 +40,20 @@ export async function discoverRoutes(routesDir: string): Promise<RouteDefinition
 
     routeFileCount++;
 
-    if (_seenFiles.has(filePath)) continue;
+    // Skip ONLY if we've already imported this exact file at its current mtime.
+    // A new file (not in _seenFiles) or an edited one (mtime increased) falls
+    // through and gets re-imported, so a hot-reload picks up the new handler.
+    const currentMtime = statSync(filePath).mtimeMs;
+    if (_seenFiles.has(filePath) && _seenMtimes.get(filePath) === currentMtime) continue;
 
     const method = name.toUpperCase();
     const relativePath = relative(routesDir, filePath);
     const pattern = filePathToPattern(relativePath);
 
     try {
-      // Cache-bust for hot-reload
-      const moduleUrl = `file://${filePath}?t=${Date.now()}`;
+      // Cache-bust for hot-reload, keyed on mtime: identical content reuses the
+      // same module URL (no needless re-import), an edit produces a fresh URL.
+      const moduleUrl = `file://${filePath}?t=${currentMtime}`;
       const mod = await import(moduleUrl);
 
       const handler: RouteHandler = mod.default ?? mod.handler;
@@ -53,6 +67,7 @@ export async function discoverRoutes(routesDir: string): Promise<RouteDefinition
 
       definitions.push({ method, pattern, handler, filePath, meta, template });
       _seenFiles.add(filePath);
+      _seenMtimes.set(filePath, currentMtime);
       registeredFromThisScan++;
     } catch (err) {
       console.error(`  Error loading route ${relativePath}:`, err);
@@ -76,8 +91,10 @@ export async function discoverRoutes(routesDir: string): Promise<RouteDefinition
 
 /**
  * Re-run the most recent route scan — called by POST /__dev/api/reload so a
- * newly-added file in src/routes/ registers without a server restart. Already
- * loaded files are skipped. No-op if discoverRoutes() has never been called.
+ * newly-added OR edited file in src/routes/ registers without a server restart.
+ * A file is re-imported when it's new or its mtime increased; unchanged files
+ * are skipped. The router replaces routes by pattern, so a re-imported route
+ * overwrites the stale handler. No-op if discoverRoutes() has never been called.
  */
 export async function rediscoverRoutes(): Promise<RouteDefinition[]> {
   if (!_lastRoutesDir) return [];
@@ -87,6 +104,7 @@ export async function rediscoverRoutes(): Promise<RouteDefinition[]> {
 /** Test-only: reset the seen-files state so tests can replay the same dir. */
 export function _resetRouteDiscovery(): void {
   _seenFiles.clear();
+  _seenMtimes.clear();
   _lastRoutesDir = "";
 }
 

package/packages/core/src/server.ts

@@ -18,7 +18,8 @@ import { loadEnv, isTruthy } from "./dotenv.js";
 import { createHealthRoutes } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
-import { DevAdmin, RequestInspector } from "./devAdmin.js";
+import { DevAdmin, RequestInspector, WsTracker } from "./devAdmin.js";
+import { devReloadWs } from "./websocket.js";
 import { feedbackEnabled, injectFeedbackWidget } from "./feedback.js";
 import { I18n } from "./i18n.js";
 import { stopAllBackgroundTasks } from "./background.js";
@@ -756,6 +757,13 @@ ${reset}
   const router = new Router();
   const middleware = new MiddlewareChain();
 
+  // Expose the active server router globally so dev tools (e.g. the MCP
+  // route_list tool) can introspect the real, fully-populated route table —
+  // startServer builds a fresh Router rather than using defaultRouter, so
+  // file-discovered routes only live here. Mirrors the globalThis.__tina4_db
+  // hook other dev tools read.
+  (globalThis as any).__tina4_router = router;
+
   // Merge routes registered via top-level get(), post(), etc.
   for (const route of defaultRouter.getRoutes()) {
     router.addRoute(route);
@@ -1385,6 +1393,32 @@ ${reset}
   // posts /__dev/api/reload to the MAIN port. Matches Python (master).
   const server = createServer(dispatch);
 
+  // WebSocket-primary DevReload: accept and hold /__dev_reload upgrades on the
+  // MAIN port (debug only) so POST /__dev/api/reload can push an instant reload.
+  // Mirrors Python's _register_dev_reload_ws + _ws_manager.broadcast(path=…).
+  // Without this the handshake 404s and the whole stack silently falls back to
+  // polling. Track connections in WsTracker so they appear in the dev-admin list.
+  if (isDevMode()) {
+    devReloadWs.setTracker(
+      (remoteAddress, p) => WsTracker.add(remoteAddress, p),
+      (id) => { WsTracker.remove(id); },
+    );
+    server.on("upgrade", (req: IncomingMessage, socket, head) => {
+      const upPath = (req.url ?? "/").split("?")[0];
+      if (upPath === "/__dev_reload") {
+        devReloadWs.handleUpgrade(req, socket, head);
+        return;
+      }
+      // Not a dev-reload upgrade — refuse cleanly rather than leaving it hanging.
+      try {
+        socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+        socket.destroy();
+      } catch {
+        /* socket already gone */
+      }
+    });
+  }
+
   return new Promise((resolvePromise) => {
     server.listen(port, host, () => {
       const displayHost = host === "0.0.0.0" ? "localhost" : host;
@@ -1413,6 +1447,17 @@ ${reset}
           await dispatch(req, res);
         });
 
+        // Stable AI port never accepts /__dev_reload (or any) WS upgrade — an AI
+        // tool driving it must never get a reload channel that its own edits trip.
+        aiServer.on("upgrade", (_req: IncomingMessage, socket) => {
+          try {
+            socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+            socket.destroy();
+          } catch {
+            /* socket already gone */
+          }
+        });
+
         aiServer.on("error", (err: any) => {
           if (err.code === "EADDRINUSE") {
             Log.warn(`Test port ${testPort} in use — skipping`);

package/packages/core/src/websocket.ts

@@ -562,3 +562,142 @@ export class WebSocketServer {
     this.clientRooms.delete(clientId);
   }
 }
+
+// ── Dev-reload WebSocket manager ─────────────────────────────
+
+/** A single accepted /__dev_reload socket plus its dashboard tracker id. */
+interface DevReloadClient {
+  socket: Socket;
+  /** WsTracker id, so the connection shows in the dev-admin /__dev/api/websockets list. */
+  trackerId?: string;
+}
+
+/**
+ * Connection manager for the dev-reload channel (`/__dev_reload`).
+ *
+ * Mirrors Python's `_ws_manager` scoped to `/__dev_reload`: it accepts the
+ * RFC 6455 handshake on the *main* dev server's HTTP `upgrade` event, holds the
+ * raw sockets open, and lets `POST /__dev/api/reload` push an instant reload to
+ * every connected browser via {@link broadcast}. The framework never reads from
+ * the client — the open socket is the whole point. This restores the documented
+ * WebSocket-primary DevReload design (the dev toolbar and dev-admin dashboard
+ * both connect here). Registered only when `TINA4_DEBUG` is on, and never on the
+ * stable AI port.
+ */
+class DevReloadWsManager {
+  private clients: Set<DevReloadClient> = new Set();
+  /** Optional hooks (add/remove) so the dev-admin connection list stays in sync. */
+  private onAdd?: (remoteAddress: string, path: string) => string;
+  private onRemove?: (id: string) => void;
+
+  /** Wire dev-admin tracking callbacks (WsTracker.add / WsTracker.remove). */
+  setTracker(onAdd: (remoteAddress: string, path: string) => string, onRemove: (id: string) => void): void {
+    this.onAdd = onAdd;
+    this.onRemove = onRemove;
+  }
+
+  /** Number of currently-open dev-reload sockets (test/diagnostic helper). */
+  get size(): number {
+    return this.clients.size;
+  }
+
+  /**
+   * Accept a WebSocket upgrade on `/__dev_reload` and hold the socket open.
+   *
+   * Completes the RFC 6455 handshake, registers the connection, and drains
+   * inbound frames — responding to pings and cleaning up on close — without
+   * ever interpreting client data. Returns true if the handshake was accepted.
+   */
+  handleUpgrade(req: IncomingMessage, socket: Socket, head: Buffer): boolean {
+    const wsKey = req.headers["sec-websocket-key"];
+    if (!wsKey || (typeof wsKey === "string" && wsKey.length === 0)) {
+      try {
+        socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+        socket.destroy();
+      } catch {
+        /* socket already gone */
+      }
+      return false;
+    }
+
+    const acceptKey = computeAcceptKey(Array.isArray(wsKey) ? wsKey[0] : wsKey);
+    const response = [
+      "HTTP/1.1 101 Switching Protocols",
+      "Upgrade: websocket",
+      "Connection: Upgrade",
+      `Sec-WebSocket-Accept: ${acceptKey}`,
+      "",
+      "",
+    ].join("\r\n");
+    try {
+      socket.write(response);
+    } catch {
+      return false;
+    }
+
+    const client: DevReloadClient = { socket };
+    if (this.onAdd) {
+      client.trackerId = this.onAdd(socket.remoteAddress ?? "unknown", "/__dev_reload");
+    }
+    this.clients.add(client);
+
+    const cleanup = () => {
+      if (!this.clients.has(client)) return;
+      this.clients.delete(client);
+      if (client.trackerId && this.onRemove) this.onRemove(client.trackerId);
+    };
+
+    // We don't act on client data, but we must still drain frames so the OS
+    // buffer doesn't stall, answer pings, and notice a client-side close.
+    let buffer = head && head.length > 0 ? Buffer.from(head) : Buffer.alloc(0);
+    socket.on("data", (chunk: Buffer) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      while (buffer.length > 0) {
+        const frame = parseFrame(buffer);
+        if (!frame) break;
+        buffer = buffer.subarray(frame.bytesConsumed);
+        if (frame.opcode === OP_PING) {
+          try {
+            socket.write(buildFrame(OP_PONG, frame.payload));
+          } catch {
+            /* client disconnected */
+          }
+        } else if (frame.opcode === OP_CLOSE) {
+          try {
+            socket.write(buildFrame(OP_CLOSE, Buffer.from([0x03, 0xe8])));
+            socket.end();
+          } catch {
+            /* already closed */
+          }
+          cleanup();
+          return;
+        }
+      }
+    });
+    socket.on("close", cleanup);
+    socket.on("error", cleanup);
+    return true;
+  }
+
+  /**
+   * Broadcast a text frame to every connected dev-reload client.
+   *
+   * Best-effort: a dead socket is dropped silently. Never throws — the caller
+   * (`POST /__dev/api/reload`) must not 500 because a browser tab went away.
+   */
+  broadcast(message: string): void {
+    if (this.clients.size === 0) return;
+    const frame = buildFrame(OP_TEXT, Buffer.from(message, "utf-8"));
+    for (const client of Array.from(this.clients)) {
+      try {
+        client.socket.write(frame);
+      } catch {
+        this.clients.delete(client);
+        if (client.trackerId && this.onRemove) this.onRemove(client.trackerId);
+      }
+    }
+  }
+}
+
+/** Process-wide dev-reload manager (one channel: `/__dev_reload`). */
+export const devReloadWs = new DevReloadWsManager();