@documentation-robotics/cli 0.1.7 → 0.1.9

package/dist/server/server.js

@@ -1,14 +1,18 @@
 import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
 import { cors } from "hono/cors";
 import { swaggerUI } from "@hono/swagger-ui";
+import { serve } from "@hono/node-server";
+import { createNodeWebSocket } from "@hono/node-ws";
+import { spawn, spawnSync } from "child_process";
+import chokidar from "chokidar";
 import { randomBytes } from "crypto";
 import { createRequire } from "module";
 import { fileURLToPath } from "url";
 import path from "path";
-let upgradeWebSocket, websocket;
 const require2 = createRequire(import.meta.url);
 import { Model } from "../core/model.js";
 import { StagedChangesetStorage } from "../core/staged-changeset-storage.js";
+import { CANONICAL_LAYER_NAMES } from "../core/layers.js";
 import { telemetryMiddleware } from "./telemetry-middleware.js";
 import { ClaudeCodeClient } from "../coding-agents/claude-code-client.js";
 import { CopilotClient } from "../coding-agents/copilot-client.js";
@@ -31,7 +35,9 @@ class VisualizationServer {
   app;
   model;
   _server;
-  // Bun.serve return type, loaded dynamically
+  // Node HTTP server returned by @hono/node-server
+  upgradeWebSocket;
+  injectWebSocket;
   clients = /* @__PURE__ */ new Set();
   watcher;
   annotations = /* @__PURE__ */ new Map();
@@ -50,7 +56,7 @@ class VisualizationServer {
   viewerPath;
   // Optional custom viewer path
   activeChatProcesses = /* @__PURE__ */ new Map();
-  // conversationId -> Bun.spawn process
+  // conversationId -> spawned chat process
   chatConversationCounter = 0;
   selectedChatClient;
   // Selected chat client for server
@@ -70,21 +76,8 @@ class VisualizationServer {
    * If any file cannot be loaded, falls back to a minimal safe set
    */
   static loadValidSpecNodeIds() {
-    const result = {}, requiredLayers = [
-      "motivation",
-      "business",
-      "security",
-      "application",
-      "technology",
-      "api",
-      "data-model",
-      "data-store",
-      "ux",
-      "navigation",
-      "apm",
-      "testing"
-    ], __dirname = path.dirname(fileURLToPath(import.meta.url)), bundledDir = path.join(__dirname, "..", "schemas", "bundled");
-    for (const layer of requiredLayers)
+    const result = {}, __dirname = path.dirname(fileURLToPath(import.meta.url)), bundledDir = path.join(__dirname, "..", "schemas", "bundled");
+    for (const layer of CANONICAL_LAYER_NAMES)
       try {
         const specFilePath = path.join(bundledDir, `${layer}.json`), nodeTypes = require2(specFilePath).layer?.node_types;
         Array.isArray(nodeTypes) && nodeTypes.length > 0 ? result[layer] = nodeTypes : (console.warn(`[SPEC-LOAD-001] Layer ${layer} has no node_types in spec file`), result[layer] = []);
@@ -99,6 +92,7 @@ class VisualizationServer {
    * or found through other resolution strategies
    */
   static LAYER_FALLBACK = {
+    product: "business.businessservice",
     security: "business.businessprocess",
     technology: "application.applicationservice",
     api: "business.businessprocess",
@@ -119,7 +113,7 @@ class VisualizationServer {
     }), ids;
   })();
   constructor(model, options) {
-    this.app = new OpenAPIHono(), this.model = model, this.loadBunAdapters(), this.authEnabled = options?.authEnabled ?? process.env.DR_AUTH_ENABLED !== "false", this.authToken = options?.authToken || process.env.DR_AUTH_TOKEN || this.generateAuthToken(), this.withDanger = options?.withDanger || !1, this.viewerPath = options?.viewerPath || new URL("../viewer", import.meta.url).pathname, !this.authEnabled && options?.authToken && console.warn("[VisualizationServer] Warning: authToken provided but authEnabled is false. The token will be generated but not used for authentication. Set authEnabled: true to enable authentication."), this.app.use("/*", cors()), this.app.use("/*", telemetryMiddleware), this.app.use("/api/*", async (c, next) => {
+    this.app = new OpenAPIHono(), this.model = model, this.loadWebSocketAdapter(), this.authEnabled = options?.authEnabled ?? process.env.DR_AUTH_ENABLED !== "false", this.authToken = options?.authToken || process.env.DR_AUTH_TOKEN || this.generateAuthToken(), this.withDanger = options?.withDanger || !1, this.viewerPath = options?.viewerPath || new URL("../viewer", import.meta.url).pathname, !this.authEnabled && options?.authToken && console.warn("[VisualizationServer] Warning: authToken provided but authEnabled is false. The token will be generated but not used for authentication. Set authEnabled: true to enable authentication."), this.app.use("/*", cors()), this.app.use("/*", telemetryMiddleware), this.app.use("/api/*", async (c, next) => {
       if (!this.authEnabled)
         return next();
       const authHeader = c.req.header("Authorization"), queryToken = c.req.query("token");
@@ -130,19 +124,21 @@ class VisualizationServer {
     });
   }
   /**
-   * Load Bun-specific WebSocket adapters if available
-   * This is called in the constructor to support WebSocket functionality in Bun runtime
-   * In Node.js/tsx environments (e.g., generating OpenAPI spec), these imports are skipped
+   * Set up the WebSocket adapter for this server instance
+   * This is called in the constructor to support WebSocket functionality via @hono/node-ws,
+   * which works identically under Node.js and Bun (both implement Node's http module).
+   * Wrapped in try/catch as a defensive guard so a WS setup failure would degrade the
+   * server gracefully (no /ws route) rather than crash construction entirely, in case
+   * this ever becomes fallible again in the future.
    */
-  loadBunAdapters() {
-    if (typeof global.Bun < "u")
-      try {
-        const honoModule = require2("hono/bun");
-        upgradeWebSocket = honoModule.upgradeWebSocket, websocket = honoModule.websocket;
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.warn(`[Server] WARNING: Could not load WebSocket adapters from hono/bun: ${message}. WebSocket endpoints (/ws) will not be available. Please ensure 'hono' is installed and the Bun runtime is properly configured.`), process.env.VERBOSE && error instanceof Error && error.stack && console.debug("[Server] Stack trace:", error.stack);
-      }
+  loadWebSocketAdapter() {
+    try {
+      const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app: this.app });
+      this.injectWebSocket = injectWebSocket, this.upgradeWebSocket = upgradeWebSocket;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[Server] WARNING: Could not set up WebSocket adapter: ${message}. WebSocket endpoints (/ws) will not be available.`), process.env.VERBOSE && error instanceof Error && error.stack && console.debug("[Server] Stack trace:", error.stack);
+    }
   }
   /**
    * Detect and initialize available chat clients
@@ -858,7 +854,7 @@ class VisualizationServer {
         { name: "Annotations", description: "User annotations on model elements" },
         { name: "WebSocket", description: "Real-time updates via WebSocket" }
       ]
-    }), this.app.get("/api-docs", swaggerUI({ url: "/api-spec.yaml" })), upgradeWebSocket && this.app.get("/ws", async (c, next) => {
+    }), this.app.get("/api-docs", swaggerUI({ url: "/api-spec.yaml" })), this.upgradeWebSocket && this.app.get("/ws", async (c, next) => {
       if (this.authEnabled) {
         const queryToken = c.req.query("token"), wsProtocol = c.req.header("Sec-WebSocket-Protocol");
         let protocolToken = null;
@@ -876,7 +872,7 @@ class VisualizationServer {
         protocolToken && c.header("Sec-WebSocket-Protocol", "token");
       }
       return next();
-    }, upgradeWebSocket(() => ({
+    }, this.upgradeWebSocket(() => ({
       onOpen: async (_evt, ws) => {
         await this.recordWebSocketEvent("ws.connection.open", {
           "ws.client_count": this.clients.size + 1
@@ -1274,23 +1270,33 @@ class VisualizationServer {
     try {
       const cmd = ["claude", "--agent", "dr-architect", "--print"];
       this.withDanger && cmd.push("--dangerously-skip-permissions"), cmd.push("--verbose", "--output-format", "stream-json");
-      const proc = Bun.spawn({
-        cmd,
+      const proc = spawn(cmd[0], cmd.slice(1), {
         cwd: this.model.rootPath,
-        stdin: "pipe",
-        stdout: "pipe",
-        stderr: "pipe"
+        stdio: ["pipe", "pipe", "pipe"]
       });
-      this.activeChatProcesses.set(conversationId, proc), proc.stdin?.write(new TextEncoder().encode(message)), proc.stdin?.end();
-      const stdoutReader = proc.stdout.getReader(), decoder = new TextDecoder();
+      proc.on("error", (err) => {
+        const errorMsg = getErrorMessage(err);
+        console.error(`[Claude Code] Failed to spawn subprocess for conversation ${conversationId}: ${errorMsg}`), this.activeChatProcesses.delete(conversationId);
+        try {
+          ws.send(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+              code: JSONRPC_ERRORS.INTERNAL_ERROR,
+              message: `Failed to launch Claude Code: ${errorMsg}`
+            },
+            id: requestId
+          }));
+        } catch (sendError) {
+          console.error(`[Claude Code] Failed to send spawn-error notification: ${getErrorMessage(sendError)}`);
+        }
+      }), proc.stdin?.on("error", () => {
+      }), this.activeChatProcesses.set(conversationId, proc), proc.stdin?.write(message), proc.stdin?.end();
+      const decoder = new TextDecoder();
       (async () => {
         let accumulatedText = "", buffer = "";
         try {
-          for (; ; ) {
-            const { done, value } = await stdoutReader.read();
-            if (done)
-              break;
-            const chunk = decoder.decode(value, { stream: !0 });
+          for await (const chunkBuf of proc.stdout) {
+            const chunk = decoder.decode(chunkBuf, { stream: !0 });
             buffer += chunk;
             const lines = buffer.split(`
 `);
@@ -1354,7 +1360,7 @@ class VisualizationServer {
               timestamp: (/* @__PURE__ */ new Date()).toISOString()
             }
           }));
-          const exitCode = await proc.exited;
+          const exitCode = await this.waitForExit(proc);
           this.activeChatProcesses.delete(conversationId), ws.send(JSON.stringify({
             jsonrpc: "2.0",
             result: {
@@ -1367,6 +1373,8 @@ class VisualizationServer {
             id: requestId
           }));
         } catch (error) {
+          if (!proc.pid)
+            return;
           const errorMsg = getErrorMessage(error);
           ws.send(JSON.stringify({
             jsonrpc: "2.0",
@@ -1416,28 +1424,37 @@ class VisualizationServer {
   async launchCopilotChat(ws, conversationId, message, requestId) {
     try {
       let cmd;
-      Bun.spawnSync({
-        cmd: ["gh", "copilot", "--version"],
-        stdout: "pipe",
-        stderr: "pipe"
-      }).exitCode === 0 ? (cmd = ["gh", "copilot", "explain"], this.withDanger && cmd.push("--allow-all-tools"), cmd.push(message)) : (cmd = ["copilot", "explain"], this.withDanger && cmd.push("--allow-all-tools"), cmd.push(message));
-      const proc = Bun.spawn({
-        cmd,
+      const ghResult = spawnSync("gh", ["copilot", "--version"], {
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      ghResult.error ? console.warn(`[Copilot] 'gh copilot --version' probe failed to spawn: ${getErrorMessage(ghResult.error)}`) : ghResult.status !== 0 && process.env.VERBOSE && console.log(`[Copilot] 'gh copilot' unavailable (exit ${ghResult.status}), falling back to standalone 'copilot'`), ghResult.status === 0 ? (cmd = ["gh", "copilot", "explain"], this.withDanger && cmd.push("--allow-all-tools"), cmd.push(message)) : (cmd = ["copilot", "explain"], this.withDanger && cmd.push("--allow-all-tools"), cmd.push(message));
+      const proc = spawn(cmd[0], cmd.slice(1), {
         cwd: this.model.rootPath,
-        stdin: "pipe",
-        stdout: "pipe",
-        stderr: "pipe"
+        stdio: ["pipe", "pipe", "pipe"]
       });
-      this.activeChatProcesses.set(conversationId, proc);
-      const stdoutReader = proc.stdout.getReader(), decoder = new TextDecoder();
+      proc.on("error", (err) => {
+        const errorMsg = getErrorMessage(err);
+        console.error(`[Copilot] Failed to spawn subprocess for conversation ${conversationId}: ${errorMsg}`), this.activeChatProcesses.delete(conversationId);
+        try {
+          ws.send(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+              code: JSONRPC_ERRORS.INTERNAL_ERROR,
+              message: `Failed to launch GitHub Copilot: ${errorMsg}`
+            },
+            id: requestId
+          }));
+        } catch (sendError) {
+          console.error(`[Copilot] Failed to send spawn-error notification: ${getErrorMessage(sendError)}`);
+        }
+      }), proc.stdin?.on("error", () => {
+      }), this.activeChatProcesses.set(conversationId, proc);
+      const decoder = new TextDecoder();
       (async () => {
         let accumulatedText = "";
         try {
-          for (; ; ) {
-            const { done, value } = await stdoutReader.read();
-            if (done)
-              break;
-            const chunk = decoder.decode(value, { stream: !0 });
+          for await (const chunkBuf of proc.stdout) {
+            const chunk = decoder.decode(chunkBuf, { stream: !0 });
             accumulatedText += chunk, ws.send(JSON.stringify({
               jsonrpc: "2.0",
               method: "chat.response.chunk",
@@ -1449,7 +1466,7 @@ class VisualizationServer {
               }
             }));
           }
-          const exitCode = await proc.exited;
+          const exitCode = await this.waitForExit(proc);
           this.activeChatProcesses.delete(conversationId), ws.send(JSON.stringify({
             jsonrpc: "2.0",
             result: {
@@ -1462,6 +1479,8 @@ class VisualizationServer {
             id: requestId
           }));
         } catch (error) {
+          if (!proc.pid)
+            return;
           const errorMsg = getErrorMessage(error);
           ws.send(JSON.stringify({
             jsonrpc: "2.0",
@@ -1496,35 +1515,33 @@ class VisualizationServer {
    * Setup file watcher for model changes
    */
   setupFileWatcher() {
-    const modelPath = `${this.model.rootPath}/documentation-robotics/model`, bunWatch = globalThis.Bun?.watch;
-    if (!bunWatch) {
-      console.warn("[Watcher] Bun.watch not available, file watching disabled");
-      return;
-    }
+    const modelPath = `${this.model.rootPath}/documentation-robotics/model`;
     try {
-      this.watcher = bunWatch(modelPath, {
-        recursive: !0,
-        onChange: async (_event, path2) => {
-          process.env.VERBOSE && console.log(`[Watcher] File changed: ${path2}`);
-          try {
-            this.model = await Model.load(this.model.rootPath, { lazyLoad: !1 }), await this.loadChangesetsFromDisk();
-            const modelData = await this.serializeModel(), message = JSON.stringify({
-              type: "model.updated",
-              data: modelData,
-              timestamp: (/* @__PURE__ */ new Date()).toISOString()
-            });
-            for (const client of this.clients)
-              try {
-                client.send(message);
-              } catch (error) {
-                const msg = getErrorMessage(error);
-                console.warn(`[Watcher] Failed to send update: ${msg}`);
-              }
-          } catch (error) {
-            const message = getErrorMessage(error);
-            console.error(`[Watcher] Failed to reload model: ${message}`);
-          }
+      this.watcher = chokidar.watch(modelPath, {
+        persistent: !0,
+        ignoreInitial: !0
+      }), this.watcher.on("all", async (_event, path2) => {
+        process.env.VERBOSE && console.log(`[Watcher] File changed: ${path2}`);
+        try {
+          this.model = await Model.load(this.model.rootPath, { lazyLoad: !1 }), await this.loadChangesetsFromDisk();
+          const modelData = await this.serializeModel(), message = JSON.stringify({
+            type: "model.updated",
+            data: modelData,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          for (const client of this.clients)
+            try {
+              client.send(message);
+            } catch (error) {
+              const msg = getErrorMessage(error);
+              console.warn(`[Watcher] Failed to send update: ${msg}`);
+            }
+        } catch (error) {
+          const message = getErrorMessage(error);
+          console.error(`[Watcher] Failed to reload model: ${message}`);
         }
+      }), this.watcher.on("error", (err) => {
+        console.warn(`[Watcher] Could not watch ${modelPath}: ${getErrorMessage(err)}`);
       });
     } catch (err) {
       console.warn(`[Watcher] Could not watch ${modelPath}: ${err}`);
@@ -2226,14 +2243,14 @@ class VisualizationServer {
    * Start the server
    */
   async start(port = 8080) {
-    this.changesetStorage = new StagedChangesetStorage(this.model.rootPath), await this.loadChangesetsFromDisk(), this.setupFileWatcher();
-    const { serve } = await import("bun");
-    this._server = serve({
+    this.changesetStorage = new StagedChangesetStorage(this.model.rootPath), await this.loadChangesetsFromDisk(), this.setupFileWatcher(), this._server = serve({
       port,
-      fetch: this.app.fetch,
-      websocket
-      // Add WebSocket handler from hono/bun
-    }), console.log(`\u2713 Visualization server running at http://localhost:${port}`);
+      fetch: this.app.fetch
+    }), await new Promise((resolve, reject) => {
+      this._server.once("listening", resolve), this._server.once("error", (err) => {
+        err.code === "EADDRINUSE" ? reject(new Error(`Port ${port} is already in use. Try a different port with --port <port>.`)) : reject(err);
+      });
+    }), this.injectWebSocket?.(this._server), console.log(`\u2713 Visualization server running at http://localhost:${port}`);
   }
   /**
    * Get the current auth token
@@ -2247,6 +2264,34 @@ class VisualizationServer {
   isAuthEnabled() {
     return this.authEnabled;
   }
+  /**
+   * Wait for a spawned child process to exit and resolve with its exit code
+   * Node's ChildProcess doesn't expose a Bun-style `.exited` promise, so this
+   * wraps the "exit" event (or the already-set exitCode, if it fired before
+   * we started listening).
+   */
+  waitForExit(proc) {
+    return new Promise((resolve) => {
+      if (proc.exitCode !== null) {
+        resolve(proc.exitCode);
+        return;
+      }
+      proc.once("exit", (code) => resolve(code ?? 0));
+    });
+  }
+  /**
+   * Whether a child process has actually terminated.
+   *
+   * NOTE: Node's `ChildProcess.killed` means "kill() was successfully used to send a
+   * signal" — it does NOT mean the process has exited (a process can ignore SIGTERM
+   * and keep running with `.killed === true`). This differs from Bun's
+   * `Subprocess.killed`, which does mean "has the process exited". Use exitCode/
+   * signalCode (set only once the process has actually terminated) instead of
+   * `.killed` to decide whether retry/escalation is still needed.
+   */
+  hasExited(proc) {
+    return proc.exitCode !== null || proc.signalCode !== null;
+  }
   /**
    * Kill a process with retry logic and exponential backoff
    * Attempts graceful SIGTERM first, then force SIGKILL if needed
@@ -2256,7 +2301,7 @@ class VisualizationServer {
     const baseDelay = 100;
     for (; attempt < 3; ) {
       try {
-        if (proc.killed || (proc.kill("SIGTERM"), await new Promise((resolve) => setTimeout(resolve, 500)), proc.killed))
+        if (this.hasExited(proc) || (proc.kill("SIGTERM"), await new Promise((resolve) => setTimeout(resolve, 500)), this.hasExited(proc)))
           return;
       } catch {
       }
@@ -2266,7 +2311,7 @@ class VisualizationServer {
       }
     }
     try {
-      proc.killed || (proc.kill("SIGKILL"), console.warn(`[${label}] Process for conversation ${conversationId} did not respond to SIGTERM, force killed with SIGKILL`));
+      this.hasExited(proc) || (proc.kill("SIGKILL"), console.warn(`[${label}] Process for conversation ${conversationId} did not respond to SIGTERM, force killed with SIGKILL`));
     } catch (error) {
       throw new Error(`Failed to kill process: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -2282,7 +2327,9 @@ class VisualizationServer {
         const errorMessage = error instanceof Error ? error.message : String(error);
         errorMessage.includes("already closed") || console.warn(`[SERVER] Unexpected error closing WebSocket client: ${errorMessage}`);
       }
-    this.clients.clear(), this.watcher && this.watcher.close?.(), this._server && this._server.stop();
+    this.clients.clear(), this.watcher && this.watcher.close?.(), this._server && this._server.close((error) => {
+      error && process.env.VERBOSE && console.warn(`[SERVER] Error while closing HTTP server: ${getErrorMessage(error)}`);
+    });
   }
 }
 export {