tina4-nodejs 3.13.34 → 3.13.36

package/packages/core/src/devAdmin.ts

@@ -19,6 +19,7 @@ import { DevMailbox } from "./devMailbox.js";
 import { isTruthy } from "./dotenv.js";
 import { quickMetrics, fullAnalysis, fileDetail } from "./metrics.js";
 import { registerFeedbackRoutes } from "./feedback.js";
+import { getDefaultDevServer } from "./mcp.js";
 
 const cpuCount = osCpus().length;
 
@@ -560,9 +561,18 @@ export class DevAdmin {
       { method: "POST", pattern: "/__dev/api/deps/install", handler: handleDepsInstall },
       // Git status
       { method: "GET", pattern: "/__dev/api/git/status", handler: handleGitStatus },
-      // MCP tool introspection over the built-in MCP server
+      // MCP tool introspection over the built-in MCP server (browser dev-admin REST shim)
       { method: "GET", pattern: "/__dev/api/mcp/tools", handler: handleMcpTools },
       { method: "POST", pattern: "/__dev/api/mcp/call", handler: handleMcpCall },
+      // MCP JSON-RPC + SSE endpoints that REAL MCP clients (Claude Code/Desktop)
+      // speak. POST /__dev/mcp[/message] -> JSON-RPC handleMessage; GET
+      // /__dev/mcp/sse -> SSE handshake announcing the message endpoint. Mounted
+      // through the same dispatch as the REST shim above and gated by the same
+      // /__dev public-route rule. Mirrors the Python v3 fix (POST /__dev/mcp +
+      // /__dev/mcp/message, GET /__dev/mcp/sse).
+      { method: "POST", pattern: "/__dev/mcp", handler: handleMcpMessage },
+      { method: "POST", pattern: "/__dev/mcp/message", handler: handleMcpMessage },
+      { method: "GET", pattern: "/__dev/mcp/sse", handler: handleMcpSse },
       // Scaffolding
       { method: "GET", pattern: "/__dev/api/scaffold", handler: handleScaffoldList },
       { method: "POST", pattern: "/__dev/api/scaffold/run", handler: handleScaffoldRun },
@@ -599,6 +609,13 @@ export class DevAdmin {
         handler: route.handler,
       });
     }
+
+    // Ensure the default /__dev/mcp MCP server exists with its dev tools
+    // registered. This is the single shared instance behind both the REST shim
+    // and the JSON-RPC + SSE endpoints registered above. Doing it here (gated by
+    // the same TINA4_DEBUG check that gates DevAdmin.register) means tools/list
+    // and the REST shim return tools immediately, before any first call.
+    getDefaultDevServer();
   }
 
   /**
@@ -648,14 +665,37 @@ const handleReload: RouteHandler = async (req, res) => {
     const { rediscoverRoutes } = await import("./routeDiscovery.js");
     const newRoutes = await rediscoverRoutes();
     if (newRoutes.length > 0) {
-      const { defaultRouter } = await import("./router.js");
-      for (const route of newRoutes) defaultRouter.addRoute(route);
-      console.log(`  Re-discovered ${newRoutes.length} new route(s) on reload`);
+      // Add to the LIVE server router — startServer() builds a fresh Router and
+      // exposes it as globalThis.__tina4_router; that's the instance dispatch
+      // matches against. Adding to defaultRouter would land the re-imported
+      // handler in a table nobody serves from, so the stale route keeps winning
+      // (an edited route would never hot-reload). addRoute() replaces by pattern,
+      // so the fresh handler overwrites the old one in place. Fall back to
+      // defaultRouter when no server is running (e.g. unit tests).
+      const liveRouter = (globalThis as any).__tina4_router;
+      const target = liveRouter ?? (await import("./router.js")).defaultRouter;
+      for (const route of newRoutes) target.addRoute(route);
+      console.log(`  Re-discovered ${newRoutes.length} route(s) on reload`);
     }
   } catch (err) {
     console.error(`  Re-discover on reload failed:`, err);
   }
 
+  // WebSocket-primary reload: push an instant message to every browser
+  // connected on /__dev_reload. The toolbar client (and the dev-admin
+  // dashboard) act on this immediately — the mtime poll is only a fallback for
+  // when the socket is down. CSS changes swap stylesheets; everything else
+  // triggers a full page reload, so we normalise the wire `type` to
+  // "css"/"reload". The HTTP response still echoes the caller's original type.
+  // Wrapped so a broadcast failure (or zero clients) never 500s the endpoint.
+  const wsType = reloadType === "css" ? "css" : "reload";
+  try {
+    const { devReloadWs } = await import("./websocket.js");
+    devReloadWs.broadcast(JSON.stringify({ type: wsType, file: _reloadFile, mtime: _reloadMtime }));
+  } catch (err) {
+    console.error(`  Dev-reload WebSocket broadcast failed:`, err);
+  }
+
   res.json({ ok: true, type: reloadType });
 };
 
@@ -1717,35 +1757,151 @@ const handleExecute: RouteHandler = async (req, res) => {
   }
 };
 
-const handleFiles: RouteHandler = (req, res) => {
+// --- file-browser noise filter + git decoration (mirrors PHP/Python dev-admin) ---
+const DEV_FILES_IGNORED = new Set([
+  "__pycache__", "node_modules", "vendor", ".git",
+  "venv", ".venv", "dist", "target", ".tina4",
+]);
+
+// Hidden dot-entries are filtered too, except the env files.
+function devFilesHidden(name: string): boolean {
+  if (DEV_FILES_IGNORED.has(name)) return true;
+  return name.startsWith(".") && name !== ".env" && name !== ".env.example";
+}
+
+// Same 4-status mapping Python/PHP use for a porcelain code.
+function devGitStatusLabel(code: string): string {
+  if (code === "??") return "untracked";
+  if (code.includes("M")) return "modified";
+  if (code.includes("A")) return "added";
+  if (code.includes("D")) return "deleted";
+  return "clean";
+}
+
+/**
+ * Branch + porcelain status map for the file browser, mirroring PHP's
+ * devAdminGit* helpers 1:1. Paths git reports are relative to the repo
+ * root (always forward-slash); the project root may sit inside a larger
+ * repo (monorepo), so the toplevel is returned too for rebasing. Degrades
+ * to empty (every entry "clean") on any error / no git.
+ */
+async function devGitInfo(root: string): Promise<{ branch: string; gitRoot: string | null; status: Map<string, string> }> {
+  const empty = { branch: "", gitRoot: null as string | null, status: new Map<string, string>() };
+  try {
+    const { execFileSync } = await import("node:child_process");
+    const git = (args: string[]): string | null => {
+      try {
+        return execFileSync("git", args, { cwd: root, timeout: 3000, encoding: "utf-8" }).toString();
+      } catch {
+        return null;
+      }
+    };
+    const inside = git(["rev-parse", "--is-inside-work-tree"]);
+    if (!inside || inside.trim() !== "true") return empty;
+    const branch = (git(["rev-parse", "--abbrev-ref", "HEAD"]) ?? "").trim();
+    const topRaw = git(["rev-parse", "--show-toplevel"]);
+    const gitRoot = topRaw && topRaw.trim() !== ""
+      ? topRaw.trim().replace(/\\/g, "/").replace(/\/+$/, "")
+      : null;
+    const status = new Map<string, string>();
+    const porcelain = git(["status", "--porcelain", "-uall"]);
+    if (porcelain) {
+      for (const line of porcelain.split(/\r?\n/)) {
+        if (line.length < 4) continue;
+        const code = line.slice(0, 2).trim();
+        let p = line.slice(3).trim();
+        const arrow = p.indexOf(" -> ");      // rename/copy — keep destination
+        if (arrow !== -1) p = p.slice(arrow + 4);
+        if (p === "") continue;
+        status.set(p, code);
+      }
+    }
+    return { branch, gitRoot, status };
+  } catch {
+    return empty;
+  }
+}
+
+const handleFiles: RouteHandler = async (req, res) => {
+  // Response shape matches tina4-python / tina4-php 1:1 so the dev-admin SPA
+  // works against every framework with no branching: each entry carries
+  // `is_dir`, `has_children`, `git_status` and `size`; the payload carries the
+  // git `branch`. Noise dirs + hidden dot-files (except .env/.env.example) are
+  // filtered out.
   const url = new URL(req.url ?? "/", "http://localhost");
   const rel = url.searchParams.get("path") ?? ".";
   const root = resolve(process.cwd());
   const target = safeJoin(root, rel);
-  if (!target || !existsSync(target)) {
-    res.json({ error: `Path not found: ${rel}` }, 404);
+  const { branch, gitRoot, status: gitStatus } = await devGitInfo(root);
+
+  // Missing/invalid paths return an empty-but-valid shape (not 404): the SPA
+  // restores expanded-folder state from localStorage, and folders that don't
+  // exist in this harness would otherwise spam the console with red 404s.
+  if (!target || !existsSync(target) || !statSync(target).isDirectory()) {
+    res.json({ path: rel, branch, entries: [], error: "not a directory" });
     return;
   }
-  const stat = statSync(target);
-  if (!stat.isDirectory()) {
-    res.json({ error: `Not a directory: ${rel}` }, 400);
-    return;
+
+  // Rebase entry paths onto the git repo root when the project sits inside a
+  // larger repo. Everything runs in forward-slash form.
+  const rootFwd = root.replace(/\\/g, "/");
+  let cwdInGit = "";
+  if (gitRoot && gitRoot !== rootFwd && rootFwd.startsWith(gitRoot)) {
+    cwdInGit = rootFwd.slice(gitRoot.length).replace(/^\/+/, "");
+    if (cwdInGit !== "") cwdInGit += "/";
   }
-  const entries = readdirSync(target, { withFileTypes: true })
-    .filter((e) => !e.name.startsWith(".") || e.name === ".env")
-    .map((e) => {
-      const full = join(target, e.name);
-      let size = 0;
-      try { size = e.isFile() ? statSync(full).size : 0; } catch { /* ignore */ }
-      return {
-        name: e.name,
-        type: e.isDirectory() ? "dir" : "file",
-        size,
-        path: relative(root, full),
-      };
-    })
-    .sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name) : a.type === "dir" ? -1 : 1));
-  res.json({ path: relative(root, target) || ".", entries });
+
+  const entries: Array<Record<string, unknown>> = [];
+  for (const name of readdirSync(target).sort()) {   // alphabetical; no re-sort by type
+    if (devFilesHidden(name)) continue;
+    const full = join(target, name);
+    const entryRel = relative(root, full).replace(/\\/g, "/");
+
+    let isDir = false;
+    let size: number | null = null;
+    try {
+      const st = statSync(full);
+      isDir = st.isDirectory();
+      if (!isDir) size = st.size;
+    } catch { /* unreadable entry */ }
+
+    // git status for this entry (same mapping PHP/Python use)
+    const gitPath = cwdInGit + entryRel;
+    let gitLabel = "clean";
+    const code = gitStatus.get(gitPath);
+    if (code !== undefined) {
+      gitLabel = devGitStatusLabel(code);
+    } else if (isDir) {
+      const prefix = gitPath + "/";          // propagate dirty status from any child
+      for (const [gf, gc] of gitStatus) {
+        if (gf.startsWith(prefix)) { gitLabel = gc === "??" ? "untracked" : "modified"; break; }
+      }
+    }
+
+    // has_children: does the dir contain anything visible?
+    let hasChildren: boolean | null = null;
+    if (isDir) {
+      hasChildren = false;
+      try {
+        for (const c of readdirSync(full)) {
+          if (devFilesHidden(c)) continue;
+          hasChildren = true;
+          break;
+        }
+      } catch { /* ignore */ }
+    }
+
+    entries.push({
+      name,
+      path: entryRel,
+      is_dir: isDir,
+      has_children: hasChildren,
+      git_status: gitLabel,
+      size,
+    });
+  }
+
+  res.json({ path: relative(root, target).replace(/\\/g, "/") || ".", branch, entries });
 };
 
 const handleFileRead: RouteHandler = (req, res) => {
@@ -1931,7 +2087,11 @@ const handleGitStatus: RouteHandler = async (_req, res) => {
 
 const handleMcpTools: RouteHandler = async (_req, res) => {
   try {
-    const { McpServer } = await import("./mcp.js");
+    // Ensure the default /__dev/mcp server exists with its dev tools registered,
+    // then enumerate every registered MCP server instance (app-defined servers
+    // register themselves on construction too).
+    const { McpServer, getDefaultDevServer } = await import("./mcp.js");
+    getDefaultDevServer();
     const instances = (McpServer as unknown as { _instances: Array<any> })._instances || [];
     const tools: Array<{ server: string; name: string; description: string; inputSchema: unknown }> = [];
     for (const s of instances) {
@@ -1950,7 +2110,8 @@ const handleMcpCall: RouteHandler = async (req, res) => {
   const name = (body.name as string) || "";
   const args = (body.arguments as Record<string, unknown>) || {};
   try {
-    const { McpServer } = await import("./mcp.js");
+    const { McpServer, getDefaultDevServer } = await import("./mcp.js");
+    getDefaultDevServer();
     const instances = (McpServer as unknown as { _instances: Array<any> })._instances || [];
     for (const s of instances) {
       const tool = ((s as any)._tools as Map<string, any>).get(name);
@@ -1966,6 +2127,59 @@ const handleMcpCall: RouteHandler = async (req, res) => {
   }
 };
 
+/**
+ * JSON-RPC message endpoint for real MCP clients.
+ *
+ * Mounted at POST /__dev/mcp and POST /__dev/mcp/message. Forwards the request
+ * body to the default dev MCP server's handleMessage() and returns the JSON-RPC
+ * response. Notifications / id-less requests yield an empty 204. Mirrors the
+ * Python v3 fix. The /__dev path is always public (auth-bypassed), so MCP
+ * clients connect without a token.
+ */
+const handleMcpMessage: RouteHandler = async (req, res) => {
+  try {
+    const { getDefaultDevServer } = await import("./mcp.js");
+    const server = getDefaultDevServer();
+    const body = req.body;
+    let raw: string | Record<string, unknown>;
+    if (typeof body === "object" && body !== null) {
+      raw = body as Record<string, unknown>;
+    } else {
+      raw = typeof body === "string" ? body : String(body ?? "");
+    }
+    const result = await server.handleMessage(raw);
+    if (!result) {
+      // Notification / no id — nothing to return.
+      res.send("", 204);
+      return;
+    }
+    res.json(JSON.parse(result));
+  } catch (e) {
+    res.json({ error: (e as Error).message }, 500);
+  }
+};
+
+/**
+ * SSE handshake endpoint for real MCP clients.
+ *
+ * Mounted at GET /__dev/mcp/sse. Announces the JSON-RPC message endpoint via an
+ * `endpoint` event, exactly like the canonical McpServer.registerRoutes() and
+ * the Python v3 fix. Content-Type text/event-stream, status 200.
+ */
+const handleMcpSse: RouteHandler = async (req, res) => {
+  // req.path is the path only (no query); turn /__dev/mcp/sse into the message
+  // endpoint /__dev/mcp/message that the client should POST to.
+  const reqPath = req.path || "/__dev/mcp/sse";
+  const endpointUrl = reqPath.replace(/\/sse$/, "/message");
+  const sseData = `event: endpoint\ndata: ${endpointUrl}\n\n`;
+  res.raw.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+  });
+  res.raw.end(sseData);
+};
+
 const handleScaffoldList: RouteHandler = (_req, res) => {
   res.json({
     scaffolds: [
@@ -2322,5 +2536,68 @@ function tina4VersionModal(){
         el.style.color='#f38ba8';
     });
 }
+</script>
+<script>
+(function(){
+    // WebSocket-primary dev reloader. The running server re-imports changed
+    // src/ routes in-process and pushes a {type,file,mtime} message over
+    // /__dev_reload — no respawn, instant refresh. The mtime poll below is a
+    // FALLBACK only, started when the socket is down and stopped on connect.
+    var _t4_css_exts=['.css','.scss'],_t4_debounce=null;
+    var _t4_interval=3000;
+    var _t4_ws=null,_t4_poll_timer=null,_t4_mtime=null;
+    function _t4_apply(d){
+        d=d||{};
+        var f=d.file||'',t=d.type||'';
+        var isCss=t==='css'||_t4_css_exts.some(function(e){return f.endsWith(e)});
+        if(isCss){
+            var links=document.querySelectorAll('link[rel="stylesheet"]');
+            links.forEach(function(l){
+                var href=l.getAttribute('href');
+                if(href){l.setAttribute('href',href.split('?')[0]+'?_t4='+(d.mtime||Date.now()))}
+            });
+        }else{
+            location.reload();
+        }
+    }
+    function _t4_poll(){
+        fetch('/__dev/api/mtime').then(function(r){return r.json()}).then(function(d){
+            // Sentinel: first poll only records the baseline. Use !== (not >) so
+            // the first change after load is not swallowed and a counter reset on
+            // server restart still triggers a reload.
+            if(_t4_mtime===null){_t4_mtime=d.mtime;return;}
+            if(d.mtime!==_t4_mtime){
+                _t4_mtime=d.mtime;
+                if(_t4_debounce)clearTimeout(_t4_debounce);
+                _t4_debounce=setTimeout(function(){_t4_apply(d);},500);
+            }
+        }).catch(function(){});
+    }
+    function _t4_startPoll(){
+        if(_t4_poll_timer)return;
+        _t4_mtime=null;
+        _t4_poll_timer=setInterval(_t4_poll,_t4_interval);
+    }
+    function _t4_stopPoll(){
+        if(_t4_poll_timer){clearInterval(_t4_poll_timer);_t4_poll_timer=null;}
+    }
+    function _t4_connect(){
+        var url=(location.protocol==='https:'?'wss':'ws')+'://'+location.host+'/__dev_reload';
+        try{_t4_ws=new WebSocket(url);}catch(_){_t4_startPoll();return;}
+        _t4_ws.addEventListener('open',function(){_t4_stopPoll();});
+        _t4_ws.addEventListener('message',function(ev){
+            var d=null;
+            try{d=typeof ev.data==='string'?JSON.parse(ev.data):null;}catch(_){}
+            if(!d)return;
+            if(d.type==='reload'||d.type==='change'||d.type==='css'){
+                if(_t4_debounce)clearTimeout(_t4_debounce);
+                _t4_debounce=setTimeout(function(){_t4_apply(d);},150);
+            }
+        });
+        _t4_ws.addEventListener('close',function(){_t4_ws=null;_t4_startPoll();setTimeout(_t4_connect,2000);});
+        _t4_ws.addEventListener('error',function(){try{_t4_ws&&_t4_ws.close();}catch(_){}});
+    }
+    _t4_connect();
+})();
 </script>`;
 }

package/packages/core/src/index.ts

@@ -61,6 +61,7 @@ export { GraphQL, ParseError, graphqlEndpoint, graphqlAutoSchemaEnabled } from "
 export type { GraphQLField, ResolverFn, GraphQLResult } from "./graphql.js";
 export {
   WebSocketServer,
+  devReloadWs,
   computeAcceptKey, parseUpgradeHeaders, buildFrame, parseFrame,
   OP_TEXT, OP_BINARY, OP_CLOSE, OP_PING, OP_PONG,
   CLOSE_NORMAL, CLOSE_PROTOCOL_ERROR,
@@ -121,7 +122,7 @@ export type { WebSocketConnection } from "./websocketConnection.js";
 export { RedisBackplane, NATSBackplane, createBackplane } from "./websocketBackplane.js";
 export type { WebSocketBackplane } from "./websocketBackplane.js";
 export {
-  McpServer, mcpTool, mcpResource, registerDevTools,
+  McpServer, mcpTool, mcpResource, registerDevTools, getDefaultDevServer,
   encodeResponse, encodeError, encodeNotification, decodeRequest,
   schemaFromParams, isLocalhost, mcpEnabled, mcpPort,
   PARSE_ERROR, INVALID_REQUEST, METHOD_NOT_FOUND, INVALID_PARAMS, INTERNAL_ERROR,

package/packages/core/src/mcp.test.ts

@@ -116,7 +116,7 @@ console.log("\nMcpServer Core");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-mcp", "Test Server", "0.1.0");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 1, method: "initialize",
     params: {
       protocolVersion: "2024-11-05", capabilities: {},
@@ -131,7 +131,7 @@ console.log("\nMcpServer Core");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-mcp", "Test Server");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 2, method: "ping", params: {},
   }));
   assert("ping — result empty", JSON.stringify(resp.result) === "{}");
@@ -140,7 +140,7 @@ console.log("\nMcpServer Core");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-mcp", "Test Server");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 3, method: "nonexistent", params: {},
   }));
   assert("method not found — code", resp.error.code === -32601);
@@ -149,7 +149,7 @@ console.log("\nMcpServer Core");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-mcp", "Test Server");
-  const resp = server.handleMessage({
+  const resp = await server.handleMessage({
     jsonrpc: "2.0", method: "notifications/initialized",
   });
   assert("notification — empty response", resp === "");
@@ -169,7 +169,7 @@ console.log("\nTool Registration and Call");
     schemaFromParams([{ name: "name", type: "string" }]),
   );
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 1, method: "tools/list", params: {},
   }));
   const tools = resp.result.tools;
@@ -189,7 +189,7 @@ console.log("\nTool Registration and Call");
     schemaFromParams([{ name: "a", type: "integer" }, { name: "b", type: "integer" }]),
   );
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 2, method: "tools/call",
     params: { name: "add", arguments: { a: 3, b: 5 } },
   }));
@@ -202,7 +202,7 @@ console.log("\nTool Registration and Call");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-tools", "Tool Test");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 3, method: "tools/call",
     params: { name: "missing", arguments: {} },
   }));
@@ -215,7 +215,7 @@ console.log("\nTool Registration and Call");
   server.registerTool("echo", (args) => args.msg as string, "Echo",
     schemaFromParams([{ name: "msg", type: "string" }]));
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 4, method: "tools/call",
     params: { name: "echo", arguments: { msg: "hello" } },
   }));
@@ -227,7 +227,7 @@ console.log("\nTool Registration and Call");
   const server = new McpServer("/test-tools", "Tool Test");
   server.registerTool("data", () => ({ a: 1, b: 2 }), "Return data");
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 5, method: "tools/call",
     params: { name: "data", arguments: {} },
   }));
@@ -262,7 +262,7 @@ console.log("\nResource Registration and Read");
   const server = new McpServer("/test-resources", "Resource Test");
   server.registerResource("app://tables", () => ["users", "products"], "Database tables");
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 1, method: "resources/list", params: {},
   }));
   const resources = resp.result.resources;
@@ -275,7 +275,7 @@ console.log("\nResource Registration and Read");
   const server = new McpServer("/test-resources", "Resource Test");
   server.registerResource("app://info", () => ({ version: "1.0", name: "Test App" }), "App info");
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 2, method: "resources/read",
     params: { uri: "app://info" },
   }));
@@ -288,7 +288,7 @@ console.log("\nResource Registration and Read");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-resources", "Resource Test");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 3, method: "resources/read",
     params: { uri: "app://missing" },
   }));
@@ -335,7 +335,7 @@ console.log("\nFile Sandbox");
     const server = new McpServer("/test-sandbox", "Sandbox Test");
     registerDevTools(server);
 
-    const resp = JSON.parse(server.handleMessage({
+    const resp = JSON.parse(await server.handleMessage({
       jsonrpc: "2.0", id: 1, method: "tools/call",
       params: { name: "file_read", arguments: { path: "../../../etc/passwd" } },
     }));
@@ -361,7 +361,7 @@ console.log("\nFile Sandbox");
     const server = new McpServer("/test-sandbox2", "Sandbox Test 2");
     registerDevTools(server);
 
-    const resp = JSON.parse(server.handleMessage({
+    const resp = JSON.parse(await server.handleMessage({
       jsonrpc: "2.0", id: 1, method: "tools/call",
       params: { name: "file_write", arguments: { path: "../../evil.txt", content: "hacked" } },
     }));
@@ -401,11 +401,11 @@ console.log("\nDefensive Write Helpers");
  * For string returns the inner text is the raw string; for object returns
  * it is JSON-encoded — try to parse it back, fall through to the raw text.
  */
-function callTool(server: McpServer, name: string, args: Record<string, unknown>): {
+async function callTool(server: McpServer, name: string, args: Record<string, unknown>): Promise<{
   rpc: { jsonrpc?: string; id?: unknown; result?: unknown; error?: { code: number; message: string } };
   result: Record<string, unknown> | string | null;
-} {
-  const rpc = JSON.parse(server.handleMessage({
+}> {
+  const rpc = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 1, method: "tools/call",
     params: { name, arguments: args },
   }));
@@ -431,7 +431,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
   try {
     const server = new McpServer("/test-prose", "Prose Test");
     registerDevTools(server);
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "The plan requires implementing a new feature for users.ts",
       content: "x",
     });
@@ -455,7 +455,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
   try {
     const server = new McpServer("/test-normalize", "Normalize Test");
     registerDevTools(server);
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "routes/foo.ts",
       content: "export default async function (req, res) {}\n",
     });
@@ -492,7 +492,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.writeFileSync(target, "original content\n", "utf-8");
 
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/routes/foo.ts",
       content: "new content that is reasonably similar in length to the old one\n",
     });
@@ -531,7 +531,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
     fs.writeFileSync(target, original, "utf-8");
 
     // Overwrite with 50 bytes — should be REFUSED (50/500 = 10% < 30%)
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/routes/big.ts",
       content: "y".repeat(50),
     });
@@ -562,7 +562,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
   try {
     const server = new McpServer("/test-passthrough", "Passthrough Test");
     registerDevTools(server);
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/routes/foo.ts",
       content: "export default async function (req, res) {}\n",
     });
@@ -602,7 +602,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
   try {
     const server = new McpServer("/test-verify-js", "Verify JS");
     registerDevTools(server);
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/routes/broken.js",
       content: "const x = ;\n",
     });
@@ -635,7 +635,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
     const server = new McpServer("/test-verify-skip-ext", "Verify Skip Ext");
     registerDevTools(server);
     // .twig content that would obviously fail any JS parser
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/templates/page.twig",
       content: "{% if not valid js %}<h1>Hi</h1>{% endif %}\n",
     });
@@ -668,7 +668,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
     const server = new McpServer("/test-verify-skip-outside", "Verify Skip Outside");
     registerDevTools(server);
     // Broken JS placed under tests/ — must NOT be checked
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "tests/foo.js",
       content: "const x = ;\n",
     });