@aiready/cli 0.9.28 → 0.9.29

package/dist/cli.js

@@ -1011,7 +1011,9 @@ Or specify a custom report:
     console.log("Building graph from report...");
     const { GraphBuilder } = await import("@aiready/visualizer/graph");
     const graph = GraphBuilder.buildFromReport(report, dirPath);
-    if (options.dev) {
+    let useDevMode = options.dev || false;
+    let devServerStarted = false;
+    if (useDevMode) {
       try {
         const monorepoWebDir = (0, import_path6.resolve)(dirPath, "packages/visualizer");
         let webDir = "";
@@ -1047,96 +1049,100 @@ Or specify a custom report:
             }
           }
         }
-        const spawnCwd = webDir || process.cwd();
-        const nodeBinCandidate = process.execPath;
-        const nodeBin = (0, import_fs3.existsSync)(nodeBinCandidate) ? nodeBinCandidate : "node";
-        if (!visualizerAvailable) {
-          console.error(import_chalk6.default.red("\u274C Cannot start dev server: @aiready/visualizer not available."));
-          console.log(import_chalk6.default.dim("Install @aiready/visualizer in your project with:\n  npm install @aiready/visualizer"));
+        const webViteConfigExists = webDir && (0, import_fs3.existsSync)((0, import_path6.resolve)(webDir, "web", "vite.config.ts"));
+        if (visualizerAvailable && webViteConfigExists) {
+          const spawnCwd = webDir;
+          const { watch } = await import("fs");
+          const copyReportToViz = () => {
+            try {
+              const destPath = (0, import_path6.resolve)(spawnCwd, "web", "report-data.json");
+              (0, import_fs3.copyFileSync)(reportPath, destPath);
+              console.log(`\u{1F4CB} Report synced to ${destPath}`);
+            } catch (e) {
+              console.error("Failed to sync report:", e);
+            }
+          };
+          copyReportToViz();
+          let watchTimeout = null;
+          const reportWatcher = watch(reportPath, () => {
+            if (watchTimeout) clearTimeout(watchTimeout);
+            watchTimeout = setTimeout(copyReportToViz, 100);
+          });
+          const envForSpawn = {
+            ...process.env,
+            AIREADY_REPORT_PATH: reportPath,
+            AIREADY_VISUALIZER_CONFIG: envVisualizerConfig
+          };
+          const vite = (0, import_child_process.spawn)("pnpm", ["run", "dev:web"], { cwd: spawnCwd, stdio: "inherit", shell: true, env: envForSpawn });
+          const onExit = () => {
+            try {
+              reportWatcher.close();
+            } catch (e) {
+            }
+            try {
+              vite.kill();
+            } catch (e) {
+            }
+            process.exit(0);
+          };
+          process.on("SIGINT", onExit);
+          process.on("SIGTERM", onExit);
+          devServerStarted = true;
           return;
+        } else {
+          console.log(import_chalk6.default.yellow("\u26A0\uFE0F  Dev server not available (requires local @aiready/visualizer with web assets)."));
+          console.log(import_chalk6.default.cyan("   Falling back to static HTML generation...\n"));
+          useDevMode = false;
         }
-        const { watch } = await import("fs");
-        const copyReportToViz = () => {
-          try {
-            const destPath = (0, import_path6.resolve)(spawnCwd, "web", "report-data.json");
-            (0, import_fs3.copyFileSync)(reportPath, destPath);
-            console.log(`\u{1F4CB} Report synced to ${destPath}`);
-          } catch (e) {
-            console.error("Failed to sync report:", e);
-          }
-        };
-        copyReportToViz();
-        let watchTimeout = null;
-        const reportWatcher = watch(reportPath, () => {
-          if (watchTimeout) clearTimeout(watchTimeout);
-          watchTimeout = setTimeout(copyReportToViz, 100);
-        });
-        const envForSpawn = {
-          ...process.env,
-          AIREADY_REPORT_PATH: reportPath,
-          AIREADY_VISUALIZER_CONFIG: envVisualizerConfig
-        };
-        const vite = (0, import_child_process.spawn)("pnpm", ["run", "dev:web"], { cwd: spawnCwd, stdio: "inherit", shell: true, env: envForSpawn });
-        const onExit = () => {
-          try {
-            reportWatcher.close();
-          } catch (e) {
-          }
-          try {
-            vite.kill();
-          } catch (e) {
-          }
-          process.exit(0);
-        };
-        process.on("SIGINT", onExit);
-        process.on("SIGTERM", onExit);
-        return;
       } catch (err) {
         console.error("Failed to start dev server:", err);
+        console.log(import_chalk6.default.cyan("   Falling back to static HTML generation...\n"));
+        useDevMode = false;
       }
     }
     console.log("Generating HTML...");
     const html = (0, import_core6.generateHTML)(graph);
-    const outPath = (0, import_path6.resolve)(dirPath, options.output || "packages/visualizer/visualization.html");
+    const defaultOutput = "visualization.html";
+    const outPath = (0, import_path6.resolve)(dirPath, options.output || defaultOutput);
     (0, import_fs3.writeFileSync)(outPath, html, "utf8");
-    console.log("Visualization written to:", outPath);
-    if (options.open) {
+    console.log(import_chalk6.default.green(`\u2705 Visualization written to: ${outPath}`));
+    if (options.open || options.serve) {
       const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-      (0, import_child_process.spawn)(opener, [`"${outPath}"`], { shell: true });
-    }
-    if (options.serve) {
-      try {
-        const port = typeof options.serve === "number" ? options.serve : 5173;
-        const http = await import("http");
-        const fsp = await import("fs/promises");
-        const server = http.createServer(async (req, res) => {
-          try {
-            const urlPath = req.url || "/";
-            if (urlPath === "/" || urlPath === "/index.html") {
-              const content = await fsp.readFile(outPath, "utf8");
-              res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-              res.end(content);
-              return;
+      if (options.serve) {
+        try {
+          const port = typeof options.serve === "number" ? options.serve : 5173;
+          const http = await import("http");
+          const fsp = await import("fs/promises");
+          const server = http.createServer(async (req, res) => {
+            try {
+              const urlPath = req.url || "/";
+              if (urlPath === "/" || urlPath === "/index.html") {
+                const content = await fsp.readFile(outPath, "utf8");
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(content);
+                return;
+              }
+              res.writeHead(404, { "Content-Type": "text/plain" });
+              res.end("Not found");
+            } catch (e) {
+              res.writeHead(500, { "Content-Type": "text/plain" });
+              res.end("Server error");
             }
-            res.writeHead(404, { "Content-Type": "text/plain" });
-            res.end("Not found");
-          } catch (e) {
-            res.writeHead(500, { "Content-Type": "text/plain" });
-            res.end("Server error");
-          }
-        });
-        server.listen(port, () => {
-          const addr = `http://localhost:${port}/`;
-          console.log(`Local visualization server running at ${addr}`);
-          const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-          (0, import_child_process.spawn)(opener, [`"${addr}"`], { shell: true });
-        });
-        process.on("SIGINT", () => {
-          server.close();
-          process.exit(0);
-        });
-      } catch (err) {
-        console.error("Failed to start local server:", err);
+          });
+          server.listen(port, () => {
+            const addr = `http://localhost:${port}/`;
+            console.log(import_chalk6.default.cyan(`\u{1F310} Local visualization server running at ${addr}`));
+            (0, import_child_process.spawn)(opener, [`"${addr}"`], { shell: true });
+          });
+          process.on("SIGINT", () => {
+            server.close();
+            process.exit(0);
+          });
+        } catch (err) {
+          console.error("Failed to start local server:", err);
+        }
+      } else if (options.open) {
+        (0, import_child_process.spawn)(opener, [`"${outPath}"`], { shell: true });
       }
     }
   } catch (err) {
@@ -1145,7 +1151,7 @@ Or specify a custom report:
 }
 var visualizeHelpText = `
 EXAMPLES:
-  $ aiready visualize .  # Auto-detects latest report
+  $ aiready visualize .  # Auto-detects latest report, generates HTML
   $ aiready visualize . --report .aiready/aiready-report-20260217-143022.json
   $ aiready visualize . --report report.json -o out/visualization.html --open
   $ aiready visualize . --report report.json --serve
@@ -1155,23 +1161,19 @@ EXAMPLES:
 NOTES:
   - The value passed to --report is interpreted relative to the directory argument (first positional).
     If the report is not found, the CLI will suggest running 'aiready scan' to generate it.
-  - Default output path: packages/visualizer/visualization.html (relative to the directory argument).
+  - Default output path: visualization.html (in the current directory).
   - --serve starts a tiny single-file HTTP server (default port: 5173) and opens your browser.
-    It serves only the generated HTML (no additional asset folders).
-  - Relatedness is represented by node proximity and size; explicit 'related' edges are not drawn to
-    reduce clutter and improve interactivity on large graphs.
-  - For very large graphs, consider narrowing the input with --include/--exclude or use --serve and
-    allow the browser a moment to stabilize after load.
+  - --dev starts a Vite dev server with live reload (requires local @aiready/visualizer installation).
+    When --dev is not available, it falls back to static HTML generation.
 `;
 var visualiseHelpText = `
 EXAMPLES:
   $ aiready visualise .  # Auto-detects latest report
   $ aiready visualise . --report .aiready/aiready-report-20260217-143022.json
-  $ aiready visualise . --report report.json --dev
   $ aiready visualise . --report report.json --serve 8080
 
 NOTES:
-  - Same options as 'visualize'. Use --dev for live reload and --serve to host a static HTML.
+  - Same options as 'visualize'. Use --serve to host the static HTML, or --dev for live reload.
 `;
 
 // src/cli.ts

package/dist/cli.mjs

@@ -939,7 +939,9 @@ Or specify a custom report:
     console.log("Building graph from report...");
     const { GraphBuilder } = await import("@aiready/visualizer/graph");
     const graph = GraphBuilder.buildFromReport(report, dirPath);
-    if (options.dev) {
+    let useDevMode = options.dev || false;
+    let devServerStarted = false;
+    if (useDevMode) {
       try {
         const monorepoWebDir = resolvePath6(dirPath, "packages/visualizer");
         let webDir = "";
@@ -975,96 +977,100 @@ Or specify a custom report:
             }
           }
         }
-        const spawnCwd = webDir || process.cwd();
-        const nodeBinCandidate = process.execPath;
-        const nodeBin = existsSync2(nodeBinCandidate) ? nodeBinCandidate : "node";
-        if (!visualizerAvailable) {
-          console.error(chalk6.red("\u274C Cannot start dev server: @aiready/visualizer not available."));
-          console.log(chalk6.dim("Install @aiready/visualizer in your project with:\n  npm install @aiready/visualizer"));
+        const webViteConfigExists = webDir && existsSync2(resolvePath6(webDir, "web", "vite.config.ts"));
+        if (visualizerAvailable && webViteConfigExists) {
+          const spawnCwd = webDir;
+          const { watch } = await import("fs");
+          const copyReportToViz = () => {
+            try {
+              const destPath = resolvePath6(spawnCwd, "web", "report-data.json");
+              copyFileSync2(reportPath, destPath);
+              console.log(`\u{1F4CB} Report synced to ${destPath}`);
+            } catch (e) {
+              console.error("Failed to sync report:", e);
+            }
+          };
+          copyReportToViz();
+          let watchTimeout = null;
+          const reportWatcher = watch(reportPath, () => {
+            if (watchTimeout) clearTimeout(watchTimeout);
+            watchTimeout = setTimeout(copyReportToViz, 100);
+          });
+          const envForSpawn = {
+            ...process.env,
+            AIREADY_REPORT_PATH: reportPath,
+            AIREADY_VISUALIZER_CONFIG: envVisualizerConfig
+          };
+          const vite = spawn("pnpm", ["run", "dev:web"], { cwd: spawnCwd, stdio: "inherit", shell: true, env: envForSpawn });
+          const onExit = () => {
+            try {
+              reportWatcher.close();
+            } catch (e) {
+            }
+            try {
+              vite.kill();
+            } catch (e) {
+            }
+            process.exit(0);
+          };
+          process.on("SIGINT", onExit);
+          process.on("SIGTERM", onExit);
+          devServerStarted = true;
           return;
+        } else {
+          console.log(chalk6.yellow("\u26A0\uFE0F  Dev server not available (requires local @aiready/visualizer with web assets)."));
+          console.log(chalk6.cyan("   Falling back to static HTML generation...\n"));
+          useDevMode = false;
         }
-        const { watch } = await import("fs");
-        const copyReportToViz = () => {
-          try {
-            const destPath = resolvePath6(spawnCwd, "web", "report-data.json");
-            copyFileSync2(reportPath, destPath);
-            console.log(`\u{1F4CB} Report synced to ${destPath}`);
-          } catch (e) {
-            console.error("Failed to sync report:", e);
-          }
-        };
-        copyReportToViz();
-        let watchTimeout = null;
-        const reportWatcher = watch(reportPath, () => {
-          if (watchTimeout) clearTimeout(watchTimeout);
-          watchTimeout = setTimeout(copyReportToViz, 100);
-        });
-        const envForSpawn = {
-          ...process.env,
-          AIREADY_REPORT_PATH: reportPath,
-          AIREADY_VISUALIZER_CONFIG: envVisualizerConfig
-        };
-        const vite = spawn("pnpm", ["run", "dev:web"], { cwd: spawnCwd, stdio: "inherit", shell: true, env: envForSpawn });
-        const onExit = () => {
-          try {
-            reportWatcher.close();
-          } catch (e) {
-          }
-          try {
-            vite.kill();
-          } catch (e) {
-          }
-          process.exit(0);
-        };
-        process.on("SIGINT", onExit);
-        process.on("SIGTERM", onExit);
-        return;
       } catch (err) {
         console.error("Failed to start dev server:", err);
+        console.log(chalk6.cyan("   Falling back to static HTML generation...\n"));
+        useDevMode = false;
       }
     }
     console.log("Generating HTML...");
     const html = generateHTML(graph);
-    const outPath = resolvePath6(dirPath, options.output || "packages/visualizer/visualization.html");
+    const defaultOutput = "visualization.html";
+    const outPath = resolvePath6(dirPath, options.output || defaultOutput);
     writeFileSync2(outPath, html, "utf8");
-    console.log("Visualization written to:", outPath);
-    if (options.open) {
+    console.log(chalk6.green(`\u2705 Visualization written to: ${outPath}`));
+    if (options.open || options.serve) {
       const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-      spawn(opener, [`"${outPath}"`], { shell: true });
-    }
-    if (options.serve) {
-      try {
-        const port = typeof options.serve === "number" ? options.serve : 5173;
-        const http = await import("http");
-        const fsp = await import("fs/promises");
-        const server = http.createServer(async (req, res) => {
-          try {
-            const urlPath = req.url || "/";
-            if (urlPath === "/" || urlPath === "/index.html") {
-              const content = await fsp.readFile(outPath, "utf8");
-              res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-              res.end(content);
-              return;
+      if (options.serve) {
+        try {
+          const port = typeof options.serve === "number" ? options.serve : 5173;
+          const http = await import("http");
+          const fsp = await import("fs/promises");
+          const server = http.createServer(async (req, res) => {
+            try {
+              const urlPath = req.url || "/";
+              if (urlPath === "/" || urlPath === "/index.html") {
+                const content = await fsp.readFile(outPath, "utf8");
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(content);
+                return;
+              }
+              res.writeHead(404, { "Content-Type": "text/plain" });
+              res.end("Not found");
+            } catch (e) {
+              res.writeHead(500, { "Content-Type": "text/plain" });
+              res.end("Server error");
             }
-            res.writeHead(404, { "Content-Type": "text/plain" });
-            res.end("Not found");
-          } catch (e) {
-            res.writeHead(500, { "Content-Type": "text/plain" });
-            res.end("Server error");
-          }
-        });
-        server.listen(port, () => {
-          const addr = `http://localhost:${port}/`;
-          console.log(`Local visualization server running at ${addr}`);
-          const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-          spawn(opener, [`"${addr}"`], { shell: true });
-        });
-        process.on("SIGINT", () => {
-          server.close();
-          process.exit(0);
-        });
-      } catch (err) {
-        console.error("Failed to start local server:", err);
+          });
+          server.listen(port, () => {
+            const addr = `http://localhost:${port}/`;
+            console.log(chalk6.cyan(`\u{1F310} Local visualization server running at ${addr}`));
+            spawn(opener, [`"${addr}"`], { shell: true });
+          });
+          process.on("SIGINT", () => {
+            server.close();
+            process.exit(0);
+          });
+        } catch (err) {
+          console.error("Failed to start local server:", err);
+        }
+      } else if (options.open) {
+        spawn(opener, [`"${outPath}"`], { shell: true });
       }
     }
   } catch (err) {
@@ -1073,7 +1079,7 @@ Or specify a custom report:
 }
 var visualizeHelpText = `
 EXAMPLES:
-  $ aiready visualize .  # Auto-detects latest report
+  $ aiready visualize .  # Auto-detects latest report, generates HTML
   $ aiready visualize . --report .aiready/aiready-report-20260217-143022.json
   $ aiready visualize . --report report.json -o out/visualization.html --open
   $ aiready visualize . --report report.json --serve
@@ -1083,23 +1089,19 @@ EXAMPLES:
 NOTES:
   - The value passed to --report is interpreted relative to the directory argument (first positional).
     If the report is not found, the CLI will suggest running 'aiready scan' to generate it.
-  - Default output path: packages/visualizer/visualization.html (relative to the directory argument).
+  - Default output path: visualization.html (in the current directory).
   - --serve starts a tiny single-file HTTP server (default port: 5173) and opens your browser.
-    It serves only the generated HTML (no additional asset folders).
-  - Relatedness is represented by node proximity and size; explicit 'related' edges are not drawn to
-    reduce clutter and improve interactivity on large graphs.
-  - For very large graphs, consider narrowing the input with --include/--exclude or use --serve and
-    allow the browser a moment to stabilize after load.
+  - --dev starts a Vite dev server with live reload (requires local @aiready/visualizer installation).
+    When --dev is not available, it falls back to static HTML generation.
 `;
 var visualiseHelpText = `
 EXAMPLES:
   $ aiready visualise .  # Auto-detects latest report
   $ aiready visualise . --report .aiready/aiready-report-20260217-143022.json
-  $ aiready visualise . --report report.json --dev
   $ aiready visualise . --report report.json --serve 8080
 
 NOTES:
-  - Same options as 'visualize'. Use --dev for live reload and --serve to host a static HTML.
+  - Same options as 'visualize'. Use --serve to host the static HTML, or --dev for live reload.
 `;
 
 // src/cli.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/cli",
-  "version": "0.9.28",
+  "version": "0.9.29",
   "description": "Unified CLI for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -11,11 +11,11 @@
   "dependencies": {
     "commander": "^14.0.0",
     "chalk": "^5.3.0",
-    "@aiready/pattern-detect": "0.11.22",
     "@aiready/core": "0.9.22",
-    "@aiready/context-analyzer": "0.9.26",
+    "@aiready/pattern-detect": "0.11.22",
     "@aiready/visualizer": "0.1.28",
-    "@aiready/consistency": "0.8.22"
+    "@aiready/consistency": "0.8.22",
+    "@aiready/context-analyzer": "0.9.26"
   },
   "devDependencies": {
     "tsup": "^8.3.5",

package/src/commands/visualize.ts

@@ -65,17 +65,21 @@ export async function visualizeAction(directory: string, options: VisualizeOptio
     const { GraphBuilder } = await import('@aiready/visualizer/graph');
     const graph = GraphBuilder.buildFromReport(report, dirPath);
 
-    if (options.dev) {
+    // Check if --dev mode is requested and available
+    let useDevMode = options.dev || false;
+    let devServerStarted = false;
+    
+    if (useDevMode) {
       try {
         const monorepoWebDir = resolvePath(dirPath, 'packages/visualizer');
         let webDir = '';
         let visualizerAvailable = false;
+        
         if (existsSync(monorepoWebDir)) {
           webDir = monorepoWebDir;
           visualizerAvailable = true;
         } else {
           // Try to resolve installed @aiready/visualizer package from node_modules
-          // Check multiple locations to support pnpm, npm, yarn, etc.
           const nodemodulesLocations: string[] = [
             resolvePath(dirPath, 'node_modules', '@aiready', 'visualizer'),
             resolvePath(process.cwd(), 'node_modules', '@aiready', 'visualizer'),
@@ -86,7 +90,7 @@ export async function visualizeAction(directory: string, options: VisualizeOptio
           while (currentDir !== '/' && currentDir !== '.') {
             nodemodulesLocations.push(resolvePath(currentDir, 'node_modules', '@aiready', 'visualizer'));
             const parent = resolvePath(currentDir, '..');
-            if (parent === currentDir) break; // Reached filesystem root
+            if (parent === currentDir) break;
             currentDir = parent;
           }
           
@@ -109,109 +113,113 @@ export async function visualizeAction(directory: string, options: VisualizeOptio
             }
           }
         }
-        const spawnCwd = webDir || process.cwd();
-        const nodeBinCandidate = process.execPath;
-        const nodeBin = existsSync(nodeBinCandidate) ? nodeBinCandidate : 'node';
-        if (!visualizerAvailable) {
-          console.error(chalk.red('❌ Cannot start dev server: @aiready/visualizer not available.'));
-          console.log(chalk.dim('Install @aiready/visualizer in your project with:\n  npm install @aiready/visualizer'));
-          return;
-        }
-
-        // Inline report watcher: copy report to web/report-data.json and watch for changes
-        const { watch } = await import('fs');
-        const copyReportToViz = () => {
-          try {
-            const destPath = resolvePath(spawnCwd, 'web', 'report-data.json');
-            copyFileSync(reportPath!, destPath);
-            console.log(`📋 Report synced to ${destPath}`);
-          } catch (e) {
-            console.error('Failed to sync report:', e);
-          }
-        };
         
-        // Initial copy
-        copyReportToViz();
+        // Check if web directory with vite config exists (required for dev mode)
+        const webViteConfigExists = webDir && existsSync(resolvePath(webDir, 'web', 'vite.config.ts'));
         
-        // Watch source report for changes
-        let watchTimeout: NodeJS.Timeout | null = null;
-        const reportWatcher = watch(reportPath, () => {
-          // Debounce to avoid multiple copies during file write
-          if (watchTimeout) clearTimeout(watchTimeout);
-          watchTimeout = setTimeout(copyReportToViz, 100);
-        });
-
-        const envForSpawn = { 
-          ...process.env, 
-          AIREADY_REPORT_PATH: reportPath,
-          AIREADY_VISUALIZER_CONFIG: envVisualizerConfig 
-        };
-        const vite = spawn("pnpm", ["run", "dev:web"], { cwd: spawnCwd, stdio: "inherit", shell: true, env: envForSpawn });
-        const onExit = () => {
-          try {
-            reportWatcher.close();
-          } catch (e) {}
-          try {
-            vite.kill();
-          } catch (e) {}
-          process.exit(0);
-        };
-        process.on("SIGINT", onExit);
-        process.on("SIGTERM", onExit);
-        return;
+        if (visualizerAvailable && webViteConfigExists) {
+          // Dev mode is available - start Vite dev server
+          const spawnCwd = webDir!;
+
+          // Inline report watcher: copy report to web/report-data.json and watch for changes
+          const { watch } = await import('fs');
+          const copyReportToViz = () => {
+            try {
+              const destPath = resolvePath(spawnCwd, 'web', 'report-data.json');
+              copyFileSync(reportPath!, destPath);
+              console.log(`📋 Report synced to ${destPath}`);
+            } catch (e) {
+              console.error('Failed to sync report:', e);
+            }
+          };
+          
+          // Initial copy
+          copyReportToViz();
+          
+          // Watch source report for changes
+          let watchTimeout: NodeJS.Timeout | null = null;
+          const reportWatcher = watch(reportPath, () => {
+            if (watchTimeout) clearTimeout(watchTimeout);
+            watchTimeout = setTimeout(copyReportToViz, 100);
+          });
+
+          const envForSpawn = { 
+            ...process.env, 
+            AIREADY_REPORT_PATH: reportPath,
+            AIREADY_VISUALIZER_CONFIG: envVisualizerConfig 
+          };
+          const vite = spawn("pnpm", ["run", "dev:web"], { cwd: spawnCwd, stdio: "inherit", shell: true, env: envForSpawn });
+          const onExit = () => {
+            try { reportWatcher.close(); } catch (e) {}
+            try { vite.kill(); } catch (e) {}
+            process.exit(0);
+          };
+          process.on("SIGINT", onExit);
+          process.on("SIGTERM", onExit);
+          devServerStarted = true;
+          return;
+        } else {
+          console.log(chalk.yellow('⚠️  Dev server not available (requires local @aiready/visualizer with web assets).'));
+          console.log(chalk.cyan('   Falling back to static HTML generation...\n'));
+          useDevMode = false;
+        }
       } catch (err) {
         console.error("Failed to start dev server:", err);
+        console.log(chalk.cyan('   Falling back to static HTML generation...\n'));
+        useDevMode = false;
       }
     }
 
+    // Generate static HTML (default behavior or fallback from failed --dev)
     console.log("Generating HTML...");
     const html = generateHTML(graph);
-    const outPath = resolvePath(dirPath, options.output || 'packages/visualizer/visualization.html');
+    const defaultOutput = 'visualization.html';
+    const outPath = resolvePath(dirPath, options.output || defaultOutput);
     writeFileSync(outPath, html, 'utf8');
-    console.log("Visualization written to:", outPath);
+    console.log(chalk.green(`✅ Visualization written to: ${outPath}`));
     
 
-    if (options.open) {
+    if (options.open || options.serve) {
       const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-      spawn(opener, [`"${outPath}"`], { shell: true });
-    }
+      
+      if (options.serve) {
+        try {
+          const port = typeof options.serve === 'number' ? options.serve : 5173;
+          const http = await import('http');
+          const fsp = await import('fs/promises');
 
-    if (options.serve) {
-      try {
-        const port = typeof options.serve === 'number' ? options.serve : 5173;
-        const http = await import('http');
-        const fsp = await import('fs/promises');
-
-        const server = http.createServer(async (req, res) => {
-          try {
-            const urlPath = req.url || '/';
-            if (urlPath === '/' || urlPath === '/index.html') {
-              const content = await fsp.readFile(outPath, 'utf8');
-              res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-              res.end(content);
-              return;
+          const server = http.createServer(async (req, res) => {
+            try {
+              const urlPath = req.url || '/';
+              if (urlPath === '/' || urlPath === '/index.html') {
+                const content = await fsp.readFile(outPath, 'utf8');
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(content);
+                return;
+              }
+              res.writeHead(404, { 'Content-Type': 'text/plain' });
+              res.end('Not found');
+            } catch (e: any) {
+              res.writeHead(500, { 'Content-Type': 'text/plain' });
+              res.end('Server error');
             }
-            res.writeHead(404, { 'Content-Type': 'text/plain' });
-            res.end('Not found');
-          } catch (e: any) {
-            res.writeHead(500, { 'Content-Type': 'text/plain' });
-            res.end('Server error');
-          }
-        });
-
-        server.listen(port, () => {
-          const addr = `http://localhost:${port}/`;
-          console.log(`Local visualization server running at ${addr}`);
-          const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-          spawn(opener, [`"${addr}"`], { shell: true });
-        });
-
-        process.on('SIGINT', () => {
-          server.close();
-          process.exit(0);
-        });
-      } catch (err) {
-        console.error('Failed to start local server:', err);
+          });
+
+          server.listen(port, () => {
+            const addr = `http://localhost:${port}/`;
+            console.log(chalk.cyan(`🌐 Local visualization server running at ${addr}`));
+            spawn(opener, [`"${addr}"`], { shell: true });
+          });
+
+          process.on('SIGINT', () => {
+            server.close();
+            process.exit(0);
+          });
+        } catch (err) {
+          console.error('Failed to start local server:', err);
+        }
+      } else if (options.open) {
+        spawn(opener, [`"${outPath}"`], { shell: true });
       }
     }
 
@@ -222,7 +230,7 @@ export async function visualizeAction(directory: string, options: VisualizeOptio
 
 export const visualizeHelpText = `
 EXAMPLES:
-  $ aiready visualize .  # Auto-detects latest report
+  $ aiready visualize .  # Auto-detects latest report, generates HTML
   $ aiready visualize . --report .aiready/aiready-report-20260217-143022.json
   $ aiready visualize . --report report.json -o out/visualization.html --open
   $ aiready visualize . --report report.json --serve
@@ -232,22 +240,18 @@ EXAMPLES:
 NOTES:
   - The value passed to --report is interpreted relative to the directory argument (first positional).
     If the report is not found, the CLI will suggest running 'aiready scan' to generate it.
-  - Default output path: packages/visualizer/visualization.html (relative to the directory argument).
+  - Default output path: visualization.html (in the current directory).
   - --serve starts a tiny single-file HTTP server (default port: 5173) and opens your browser.
-    It serves only the generated HTML (no additional asset folders).
-  - Relatedness is represented by node proximity and size; explicit 'related' edges are not drawn to
-    reduce clutter and improve interactivity on large graphs.
-  - For very large graphs, consider narrowing the input with --include/--exclude or use --serve and
-    allow the browser a moment to stabilize after load.
+  - --dev starts a Vite dev server with live reload (requires local @aiready/visualizer installation).
+    When --dev is not available, it falls back to static HTML generation.
 `;
 
 export const visualiseHelpText = `
 EXAMPLES:
   $ aiready visualise .  # Auto-detects latest report
   $ aiready visualise . --report .aiready/aiready-report-20260217-143022.json
-  $ aiready visualise . --report report.json --dev
   $ aiready visualise . --report report.json --serve 8080
 
 NOTES:
-  - Same options as 'visualize'. Use --dev for live reload and --serve to host a static HTML.
+  - Same options as 'visualize'. Use --serve to host the static HTML, or --dev for live reload.
 `;