@aiready/cli 0.9.2 → 0.9.5

package/.turbo/turbo-build.log

@@ -1,7 +1,7 @@
 
 
-> @aiready/cli@0.9.1 build /Users/pengcao/projects/aiready/packages/cli
-> tsup src/index.ts src/cli.ts --format cjs,esm --dts
+> @aiready/cli@0.9.5 build /Users/pengcao/projects/aiready/packages/cli
+> tsup src/index.ts src/cli.ts --format cjs,esm
 
 CLI Building entry: src/cli.ts, src/index.ts
 CLI Using tsconfig: tsconfig.json
@@ -9,16 +9,10 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
+CJS dist/cli.js   58.06 KB
 CJS dist/index.js 4.93 KB
-CJS dist/cli.js   44.24 KB
-CJS ⚡️ Build success in 22ms
+CJS ⚡️ Build success in 20ms
+ESM dist/cli.mjs            50.92 KB
 ESM dist/chunk-3SG2GLFJ.mjs 3.80 KB
 ESM dist/index.mjs          138.00 B
-ESM dist/cli.mjs            37.19 KB
-ESM ⚡️ Build success in 22ms
-DTS Build start
-DTS ⚡️ Build success in 616ms
-DTS dist/cli.d.ts    20.00 B
-DTS dist/index.d.ts  1.22 KB
-DTS dist/cli.d.mts   20.00 B
-DTS dist/index.d.mts 1.22 KB
+ESM ⚡️ Build success in 19ms

package/.turbo/turbo-test.log

@@ -1,34 +1,16 @@
 
 
-> @aiready/cli@0.9.1 test /Users/pengcao/projects/aiready/packages/cli
+> @aiready/cli@0.9.5 test /Users/pengcao/projects/aiready/packages/cli
 > vitest run
 
 [?25l
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/cli
 
-[?2026h
- ❯ src/__tests__/cli.test.ts [queued]
-
- Test Files 0 passed (1)
-      Tests 0 passed (0)
-   Start at 20:59:54
-   Duration 101ms
-[?2026l[?2026h
- ❯ src/__tests__/cli.test.ts 0/3
-
- Test Files 0 passed (1)
-      Tests 0 passed (3)
-   Start at 20:59:54
-   Duration 521ms
-[?2026l ✓ src/__tests__/cli.test.ts (3 tests) 2ms
-   ✓ CLI Unified Analysis (3)
-     ✓ should run unified analysis with both tools 1ms
-     ✓ should run analysis with only patterns tool 0ms
-     ✓ should run analysis with only context tool 0ms
+ ✓ src/__tests__/cli.test.ts (3 tests) 2ms
 
  Test Files  1 passed (1)
       Tests  3 passed (3)
-   Start at  20:59:54
-   Duration  581ms (transform 114ms, setup 0ms, import 378ms, tests 2ms, environment 0ms)
+   Start at  22:45:25
+   Duration  1.55s (transform 428ms, setup 0ms, import 949ms, tests 2ms, environment 0ms)
 
 [?25h

package/dist/chunk-5GZDRZ3T.mjs

@@ -0,0 +1,126 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/index.ts
+import { analyzePatterns } from "@aiready/pattern-detect";
+import { analyzeContext } from "@aiready/context-analyzer";
+import { analyzeConsistency } from "@aiready/consistency";
+var severityOrder = {
+  critical: 4,
+  major: 3,
+  minor: 2,
+  info: 1
+};
+function sortBySeverity(results) {
+  return results.map((file) => {
+    const sortedIssues = [...file.issues].sort((a, b) => {
+      const severityDiff = (severityOrder[b.severity] || 0) - (severityOrder[a.severity] || 0);
+      if (severityDiff !== 0) return severityDiff;
+      return (a.location?.line || 0) - (b.location?.line || 0);
+    });
+    return { ...file, issues: sortedIssues };
+  }).sort((a, b) => {
+    const aMaxSeverity = Math.max(...a.issues.map((i) => severityOrder[i.severity] || 0), 0);
+    const bMaxSeverity = Math.max(...b.issues.map((i) => severityOrder[i.severity] || 0), 0);
+    if (aMaxSeverity !== bMaxSeverity) {
+      return bMaxSeverity - aMaxSeverity;
+    }
+    if (a.issues.length !== b.issues.length) {
+      return b.issues.length - a.issues.length;
+    }
+    return a.fileName.localeCompare(b.fileName);
+  });
+}
+async function analyzeUnified(options) {
+  const startTime = Date.now();
+  const tools = options.tools || ["patterns", "context", "consistency"];
+  const result = {
+    summary: {
+      totalIssues: 0,
+      toolsRun: tools,
+      executionTime: 0
+    }
+  };
+  if (tools.includes("patterns")) {
+    const patternResult = await analyzePatterns(options);
+    if (options.progressCallback) {
+      options.progressCallback({ tool: "patterns", data: patternResult });
+    }
+    result.patterns = sortBySeverity(patternResult.results);
+    result.duplicates = patternResult.duplicates;
+    result.summary.totalIssues += patternResult.results.reduce(
+      (sum, file) => sum + file.issues.length,
+      0
+    );
+  }
+  if (tools.includes("context")) {
+    const contextResults = await analyzeContext(options);
+    if (options.progressCallback) {
+      options.progressCallback({ tool: "context", data: contextResults });
+    }
+    result.context = contextResults.sort((a, b) => {
+      const severityDiff = (severityOrder[b.severity] || 0) - (severityOrder[a.severity] || 0);
+      if (severityDiff !== 0) return severityDiff;
+      if (a.tokenCost !== b.tokenCost) return b.tokenCost - a.tokenCost;
+      return b.fragmentationScore - a.fragmentationScore;
+    });
+    result.summary.totalIssues += result.context?.length || 0;
+  }
+  if (tools.includes("consistency")) {
+    const consistencyOptions = {
+      rootDir: options.rootDir,
+      include: options.include,
+      exclude: options.exclude,
+      ...options.consistency || {}
+    };
+    const report = await analyzeConsistency(consistencyOptions);
+    if (options.progressCallback) {
+      options.progressCallback({ tool: "consistency", data: report });
+    }
+    if (report.results) {
+      report.results = sortBySeverity(report.results);
+    }
+    result.consistency = report;
+    result.summary.totalIssues += report.summary.totalIssues;
+  }
+  result.summary.executionTime = Date.now() - startTime;
+  return result;
+}
+function generateUnifiedSummary(result) {
+  const { summary } = result;
+  let output = `\u{1F680} AIReady Analysis Complete
+
+`;
+  output += `\u{1F4CA} Summary:
+`;
+  output += `   Tools run: ${summary.toolsRun.join(", ")}
+`;
+  output += `   Total issues found: ${summary.totalIssues}
+`;
+  output += `   Execution time: ${(summary.executionTime / 1e3).toFixed(2)}s
+
+`;
+  if (result.patterns) {
+    output += `\u{1F50D} Pattern Analysis: ${result.patterns.length} issues
+`;
+  }
+  if (result.context) {
+    output += `\u{1F9E0} Context Analysis: ${result.context.length} issues
+`;
+  }
+  if (result.consistency) {
+    output += `\u{1F3F7}\uFE0F Consistency Analysis: ${result.consistency.summary.totalIssues} issues
+`;
+  }
+  return output;
+}
+
+export {
+  __require,
+  analyzeUnified,
+  generateUnifiedSummary
+};

package/dist/cli.js

@@ -118,6 +118,7 @@ var import_fs = require("fs");
 var import_path = require("path");
 var import_core = require("@aiready/core");
 var import_fs2 = require("fs");
+var import_path2 = require("path");
 var packageJson = JSON.parse((0, import_fs2.readFileSync)((0, import_path.join)(__dirname, "../package.json"), "utf8"));
 var program = new import_commander.Command();
 program.name("aiready").description("AIReady - Assess and improve AI-readiness of codebases").version(packageJson.version).addHelpText("after", `
@@ -811,4 +812,284 @@ function generateMarkdownReport(report, elapsedTime) {
   }
   return markdown;
 }
+function generateHTML(graph) {
+  const payload = JSON.stringify(graph, null, 2);
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AIReady Visualization</title>
+    <style>
+      html,body { height: 100%; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0f172a; color: #e2e8f0 }
+      #container { display:flex; height:100vh }
+      #panel { width: 320px; padding: 16px; background: #071130; box-shadow: -2px 0 8px rgba(0,0,0,0.3); overflow:auto }
+      #canvasWrap { flex:1; display:flex; align-items:center; justify-content:center }
+      canvas { background: #0b1220; border-radius:8px }
+      .stat { margin-bottom:12px }
+    </style>
+  </head>
+  <body>
+    <div id="container">
+      <div id="canvasWrap"><canvas id="canvas" width="1200" height="800"></canvas></div>
+      <div id="panel">
+        <h2>AIReady Visualization</h2>
+        <div class="stat"><strong>Files:</strong> <span id="stat-files"></span></div>
+        <div class="stat"><strong>Dependencies:</strong> <span id="stat-deps"></span></div>
+        <div class="stat"><strong>Legend</strong></div>
+        <div style="font-size:13px;line-height:1.3;color:#cbd5e1;margin-top:8px">
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff4d4f;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Critical</strong>: highest severity issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff9900;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Major</strong>: important issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ffd666;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Minor</strong>: low priority issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#91d5ff;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Info</strong>: informational notes.</div>
+          <div style="margin-top:10px;color:#94a3b8"><strong>Node size</strong>: larger = higher token cost, more issues or dependency weight.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Proximity</strong>: nodes that are spatially close are more contextually related; relatedness is represented by distance and size rather than explicit edges.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Edge colors</strong>: <span style="color:#fb7e81">Similarity</span>, <span style="color:#84c1ff">Dependency</span>, <span style="color:#ffa500">Reference</span>, default <span style="color:#334155">Other</span>.</div>
+        </div>
+      </div>
+    </div>
+
+    <script>
+      const graphData = ${payload};
+      document.getElementById('stat-files').textContent = graphData.metadata.totalFiles;
+      document.getElementById('stat-deps').textContent = graphData.metadata.totalDependencies;
+
+      const canvas = document.getElementById('canvas');
+      const ctx = canvas.getContext('2d');
+
+      const nodes = graphData.nodes.map((n, i) => ({
+        ...n,
+        x: canvas.width / 2 + Math.cos(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+        y: canvas.height / 2 + Math.sin(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+      }));
+
+      function draw() {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+        graphData.edges.forEach(edge => {
+          const s = nodes.find(n => n.id === edge.source);
+          const t = nodes.find(n => n.id === edge.target);
+          if (!s || !t) return;
+          if (edge.type === 'related') return;
+          if (edge.type === 'similarity') {
+            ctx.strokeStyle = '#fb7e81';
+            ctx.lineWidth = 1.2;
+          } else if (edge.type === 'dependency') {
+            ctx.strokeStyle = '#84c1ff';
+            ctx.lineWidth = 1.0;
+          } else if (edge.type === 'reference') {
+            ctx.strokeStyle = '#ffa500';
+            ctx.lineWidth = 0.9;
+          } else {
+            ctx.strokeStyle = '#334155';
+            ctx.lineWidth = 0.8;
+          }
+          ctx.beginPath();
+          ctx.moveTo(s.x, s.y);
+          ctx.lineTo(t.x, t.y);
+          ctx.stroke();
+        });
+
+        const groups = {};
+        nodes.forEach(n => {
+          const g = n.group || '__default';
+          if (!groups[g]) groups[g] = { minX: n.x, minY: n.y, maxX: n.x, maxY: n.y };
+          groups[g].minX = Math.min(groups[g].minX, n.x);
+          groups[g].minY = Math.min(groups[g].minY, n.y);
+          groups[g].maxX = Math.max(groups[g].maxX, n.x);
+          groups[g].maxY = Math.max(groups[g].maxY, n.y);
+        });
+
+        const groupRelations = {};
+        graphData.edges.forEach(edge => {
+          const sNode = nodes.find(n => n.id === edge.source);
+          const tNode = nodes.find(n => n.id === edge.target);
+          if (!sNode || !tNode) return;
+          const g1 = sNode.group || '__default';
+          const g2 = tNode.group || '__default';
+          if (g1 === g2) return;
+          const key = g1 < g2 ? g1 + '::' + g2 : g2 + '::' + g1;
+          groupRelations[key] = (groupRelations[key] || 0) + 1;
+        });
+
+        Object.keys(groupRelations).forEach(k => {
+          const count = groupRelations[k];
+          const [ga, gb] = k.split('::');
+          if (!groups[ga] || !groups[gb]) return;
+          const ax = (groups[ga].minX + groups[ga].maxX) / 2;
+          const ay = (groups[ga].minY + groups[ga].maxY) / 2;
+          const bx = (groups[gb].minX + groups[gb].maxX) / 2;
+          const by = (groups[gb].minY + groups[gb].maxY) / 2;
+          ctx.beginPath();
+          ctx.strokeStyle = 'rgba(148,163,184,0.25)';
+          ctx.lineWidth = Math.min(6, 0.6 + Math.sqrt(count));
+          ctx.moveTo(ax, ay);
+          ctx.lineTo(bx, by);
+          ctx.stroke();
+        });
+
+        Object.keys(groups).forEach(g => {
+          if (g === '__default') return;
+          const box = groups[g];
+          const pad = 16;
+          const x = box.minX - pad;
+          const y = box.minY - pad;
+          const w = (box.maxX - box.minX) + pad * 2;
+          const h = (box.maxY - box.minY) + pad * 2;
+          ctx.save();
+          ctx.fillStyle = 'rgba(30,64,175,0.04)';
+          ctx.strokeStyle = 'rgba(30,64,175,0.12)';
+          ctx.lineWidth = 1.2;
+          const r = 8;
+          ctx.beginPath();
+          ctx.moveTo(x + r, y);
+          ctx.arcTo(x + w, y, x + w, y + h, r);
+          ctx.arcTo(x + w, y + h, x, y + h, r);
+          ctx.arcTo(x, y + h, x, y, r);
+          ctx.arcTo(x, y, x + w, y, r);
+          ctx.closePath();
+          ctx.fill();
+          ctx.stroke();
+          ctx.restore();
+          ctx.fillStyle = '#94a3b8';
+          ctx.font = '11px sans-serif';
+          ctx.fillText(g, x + 8, y + 14);
+        });
+
+        nodes.forEach(n => {
+          const sizeVal = (n.size || n.value || 1);
+          const r = 6 + (sizeVal / 2);
+          ctx.beginPath();
+          ctx.fillStyle = n.color || '#60a5fa';
+          ctx.arc(n.x, n.y, r, 0, Math.PI * 2);
+          ctx.fill();
+
+          ctx.fillStyle = '#e2e8f0';
+          ctx.font = '11px sans-serif';
+          ctx.textAlign = 'center';
+          ctx.fillText(n.label || n.id.split('/').slice(-1)[0], n.x, n.y + r + 12);
+        });
+      }
+
+      draw();
+    </script>
+  </body>
+</html>`;
+}
+async function handleVisualize(directory, options) {
+  try {
+    const dirPath = (0, import_path2.resolve)(process.cwd(), directory || ".");
+    const reportPath = (0, import_path2.resolve)(dirPath, options.report || "aiready-improvement-report.json");
+    if (!(0, import_fs2.existsSync)(reportPath)) {
+      console.error("Report not found at", reportPath);
+      console.log("Run `aiready scan` to generate the report, or pass --report");
+      return;
+    }
+    const raw = (0, import_fs2.readFileSync)(reportPath, "utf8");
+    const report = JSON.parse(raw);
+    console.log("Building graph from report...");
+    const { GraphBuilder } = await import("@aiready/visualizer/graph");
+    const graph = GraphBuilder.buildFromReport(report, dirPath);
+    if (options.dev) {
+      try {
+        const { spawn } = await import("child_process");
+        const webDir = (0, import_path2.resolve)(dirPath, "packages/visualizer");
+        const watcher = spawn("node", ["scripts/watch-report.js", reportPath], { cwd: webDir, stdio: "inherit" });
+        const vite = spawn("pnpm", ["run", "dev:web"], { cwd: webDir, stdio: "inherit", shell: true });
+        const onExit = () => {
+          try {
+            watcher.kill();
+          } 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("Generating HTML...");
+    const html = generateHTML(graph);
+    const outPath = (0, import_path2.resolve)(dirPath, options.output || "packages/visualizer/visualization.html");
+    (0, import_fs.writeFileSync)(outPath, html, "utf8");
+    console.log("Visualization written to:", outPath);
+    if (options.open) {
+      const { exec } = await import("child_process");
+      const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+      exec(`${opener} "${outPath}"`);
+    }
+    if (options.serve) {
+      try {
+        const port = Number(options.serve) || 5173;
+        const http = await import("http");
+        const fsp = await import("fs/promises");
+        const { exec } = await import("child_process");
+        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");
+          }
+        });
+        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";
+          exec(`${opener} "${addr}"`);
+        });
+        process.on("SIGINT", () => {
+          server.close();
+          process.exit(0);
+        });
+      } catch (err) {
+        console.error("Failed to start local server:", err);
+      }
+    }
+  } catch (err) {
+    (0, import_core.handleCLIError)(err, "Visualization");
+  }
+}
+program.command("visualise").description("Alias for visualize (British spelling)").argument("[directory]", "Directory to analyze", ".").option("--report <path>", "Report path (relative to directory)", "aiready-improvement-report.json").option("-o, --output <path>", "Output HTML path (relative to directory)", "packages/visualizer/visualization.html").option("--open", "Open generated HTML in default browser").option("--serve [port]", "Start a local static server to serve the visualization (optional port number)", false).option("--dev", "Start Vite dev server (live reload) for interactive development", false).addHelpText("after", `
+EXAMPLES:
+  $ aiready visualise . --report aiready-improvement-report.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.
+`).action(async (directory, options) => await handleVisualize(directory, options));
+program.command("visualize").description("Generate interactive visualization from an AIReady report").argument("[directory]", "Directory to analyze", ".").option("--report <path>", "Report path (relative to directory)", "aiready-improvement-report.json").option("-o, --output <path>", "Output HTML path (relative to directory)", "packages/visualizer/visualization.html").option("--open", "Open generated HTML in default browser").option("--serve [port]", "Start a local static server to serve the visualization (optional port number)", false).option("--dev", "Start Vite dev server (live reload) for interactive development", false).addHelpText("after", `
+EXAMPLES:
+  $ aiready visualize . --report aiready-improvement-report.json
+  $ aiready visualize . --report report.json -o out/visualization.html --open
+  $ aiready visualize . --report report.json --serve
+  $ aiready visualize . --report report.json --serve 8080
+  $ aiready visualize . --report report.json --dev
+
+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).
+  - --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.
+`).action(async (directory, options) => await handleVisualize(directory, options));
 program.parse();

package/dist/cli.mjs

@@ -21,7 +21,8 @@ import {
   getRatingDisplay,
   parseWeightString
 } from "@aiready/core";
-import { readFileSync } from "fs";
+import { readFileSync, existsSync } from "fs";
+import { resolve as resolvePath } from "path";
 var packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"));
 var program = new Command();
 program.name("aiready").description("AIReady - Assess and improve AI-readiness of codebases").version(packageJson.version).addHelpText("after", `
@@ -715,4 +716,284 @@ function generateMarkdownReport(report, elapsedTime) {
   }
   return markdown;
 }
+function generateHTML(graph) {
+  const payload = JSON.stringify(graph, null, 2);
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AIReady Visualization</title>
+    <style>
+      html,body { height: 100%; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0f172a; color: #e2e8f0 }
+      #container { display:flex; height:100vh }
+      #panel { width: 320px; padding: 16px; background: #071130; box-shadow: -2px 0 8px rgba(0,0,0,0.3); overflow:auto }
+      #canvasWrap { flex:1; display:flex; align-items:center; justify-content:center }
+      canvas { background: #0b1220; border-radius:8px }
+      .stat { margin-bottom:12px }
+    </style>
+  </head>
+  <body>
+    <div id="container">
+      <div id="canvasWrap"><canvas id="canvas" width="1200" height="800"></canvas></div>
+      <div id="panel">
+        <h2>AIReady Visualization</h2>
+        <div class="stat"><strong>Files:</strong> <span id="stat-files"></span></div>
+        <div class="stat"><strong>Dependencies:</strong> <span id="stat-deps"></span></div>
+        <div class="stat"><strong>Legend</strong></div>
+        <div style="font-size:13px;line-height:1.3;color:#cbd5e1;margin-top:8px">
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff4d4f;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Critical</strong>: highest severity issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff9900;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Major</strong>: important issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ffd666;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Minor</strong>: low priority issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#91d5ff;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Info</strong>: informational notes.</div>
+          <div style="margin-top:10px;color:#94a3b8"><strong>Node size</strong>: larger = higher token cost, more issues or dependency weight.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Proximity</strong>: nodes that are spatially close are more contextually related; relatedness is represented by distance and size rather than explicit edges.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Edge colors</strong>: <span style="color:#fb7e81">Similarity</span>, <span style="color:#84c1ff">Dependency</span>, <span style="color:#ffa500">Reference</span>, default <span style="color:#334155">Other</span>.</div>
+        </div>
+      </div>
+    </div>
+
+    <script>
+      const graphData = ${payload};
+      document.getElementById('stat-files').textContent = graphData.metadata.totalFiles;
+      document.getElementById('stat-deps').textContent = graphData.metadata.totalDependencies;
+
+      const canvas = document.getElementById('canvas');
+      const ctx = canvas.getContext('2d');
+
+      const nodes = graphData.nodes.map((n, i) => ({
+        ...n,
+        x: canvas.width / 2 + Math.cos(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+        y: canvas.height / 2 + Math.sin(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+      }));
+
+      function draw() {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+        graphData.edges.forEach(edge => {
+          const s = nodes.find(n => n.id === edge.source);
+          const t = nodes.find(n => n.id === edge.target);
+          if (!s || !t) return;
+          if (edge.type === 'related') return;
+          if (edge.type === 'similarity') {
+            ctx.strokeStyle = '#fb7e81';
+            ctx.lineWidth = 1.2;
+          } else if (edge.type === 'dependency') {
+            ctx.strokeStyle = '#84c1ff';
+            ctx.lineWidth = 1.0;
+          } else if (edge.type === 'reference') {
+            ctx.strokeStyle = '#ffa500';
+            ctx.lineWidth = 0.9;
+          } else {
+            ctx.strokeStyle = '#334155';
+            ctx.lineWidth = 0.8;
+          }
+          ctx.beginPath();
+          ctx.moveTo(s.x, s.y);
+          ctx.lineTo(t.x, t.y);
+          ctx.stroke();
+        });
+
+        const groups = {};
+        nodes.forEach(n => {
+          const g = n.group || '__default';
+          if (!groups[g]) groups[g] = { minX: n.x, minY: n.y, maxX: n.x, maxY: n.y };
+          groups[g].minX = Math.min(groups[g].minX, n.x);
+          groups[g].minY = Math.min(groups[g].minY, n.y);
+          groups[g].maxX = Math.max(groups[g].maxX, n.x);
+          groups[g].maxY = Math.max(groups[g].maxY, n.y);
+        });
+
+        const groupRelations = {};
+        graphData.edges.forEach(edge => {
+          const sNode = nodes.find(n => n.id === edge.source);
+          const tNode = nodes.find(n => n.id === edge.target);
+          if (!sNode || !tNode) return;
+          const g1 = sNode.group || '__default';
+          const g2 = tNode.group || '__default';
+          if (g1 === g2) return;
+          const key = g1 < g2 ? g1 + '::' + g2 : g2 + '::' + g1;
+          groupRelations[key] = (groupRelations[key] || 0) + 1;
+        });
+
+        Object.keys(groupRelations).forEach(k => {
+          const count = groupRelations[k];
+          const [ga, gb] = k.split('::');
+          if (!groups[ga] || !groups[gb]) return;
+          const ax = (groups[ga].minX + groups[ga].maxX) / 2;
+          const ay = (groups[ga].minY + groups[ga].maxY) / 2;
+          const bx = (groups[gb].minX + groups[gb].maxX) / 2;
+          const by = (groups[gb].minY + groups[gb].maxY) / 2;
+          ctx.beginPath();
+          ctx.strokeStyle = 'rgba(148,163,184,0.25)';
+          ctx.lineWidth = Math.min(6, 0.6 + Math.sqrt(count));
+          ctx.moveTo(ax, ay);
+          ctx.lineTo(bx, by);
+          ctx.stroke();
+        });
+
+        Object.keys(groups).forEach(g => {
+          if (g === '__default') return;
+          const box = groups[g];
+          const pad = 16;
+          const x = box.minX - pad;
+          const y = box.minY - pad;
+          const w = (box.maxX - box.minX) + pad * 2;
+          const h = (box.maxY - box.minY) + pad * 2;
+          ctx.save();
+          ctx.fillStyle = 'rgba(30,64,175,0.04)';
+          ctx.strokeStyle = 'rgba(30,64,175,0.12)';
+          ctx.lineWidth = 1.2;
+          const r = 8;
+          ctx.beginPath();
+          ctx.moveTo(x + r, y);
+          ctx.arcTo(x + w, y, x + w, y + h, r);
+          ctx.arcTo(x + w, y + h, x, y + h, r);
+          ctx.arcTo(x, y + h, x, y, r);
+          ctx.arcTo(x, y, x + w, y, r);
+          ctx.closePath();
+          ctx.fill();
+          ctx.stroke();
+          ctx.restore();
+          ctx.fillStyle = '#94a3b8';
+          ctx.font = '11px sans-serif';
+          ctx.fillText(g, x + 8, y + 14);
+        });
+
+        nodes.forEach(n => {
+          const sizeVal = (n.size || n.value || 1);
+          const r = 6 + (sizeVal / 2);
+          ctx.beginPath();
+          ctx.fillStyle = n.color || '#60a5fa';
+          ctx.arc(n.x, n.y, r, 0, Math.PI * 2);
+          ctx.fill();
+
+          ctx.fillStyle = '#e2e8f0';
+          ctx.font = '11px sans-serif';
+          ctx.textAlign = 'center';
+          ctx.fillText(n.label || n.id.split('/').slice(-1)[0], n.x, n.y + r + 12);
+        });
+      }
+
+      draw();
+    </script>
+  </body>
+</html>`;
+}
+async function handleVisualize(directory, options) {
+  try {
+    const dirPath = resolvePath(process.cwd(), directory || ".");
+    const reportPath = resolvePath(dirPath, options.report || "aiready-improvement-report.json");
+    if (!existsSync(reportPath)) {
+      console.error("Report not found at", reportPath);
+      console.log("Run `aiready scan` to generate the report, or pass --report");
+      return;
+    }
+    const raw = readFileSync(reportPath, "utf8");
+    const report = JSON.parse(raw);
+    console.log("Building graph from report...");
+    const { GraphBuilder } = await import("@aiready/visualizer/graph");
+    const graph = GraphBuilder.buildFromReport(report, dirPath);
+    if (options.dev) {
+      try {
+        const { spawn } = await import("child_process");
+        const webDir = resolvePath(dirPath, "packages/visualizer");
+        const watcher = spawn("node", ["scripts/watch-report.js", reportPath], { cwd: webDir, stdio: "inherit" });
+        const vite = spawn("pnpm", ["run", "dev:web"], { cwd: webDir, stdio: "inherit", shell: true });
+        const onExit = () => {
+          try {
+            watcher.kill();
+          } 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("Generating HTML...");
+    const html = generateHTML(graph);
+    const outPath = resolvePath(dirPath, options.output || "packages/visualizer/visualization.html");
+    writeFileSync(outPath, html, "utf8");
+    console.log("Visualization written to:", outPath);
+    if (options.open) {
+      const { exec } = await import("child_process");
+      const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+      exec(`${opener} "${outPath}"`);
+    }
+    if (options.serve) {
+      try {
+        const port = Number(options.serve) || 5173;
+        const http = await import("http");
+        const fsp = await import("fs/promises");
+        const { exec } = await import("child_process");
+        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");
+          }
+        });
+        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";
+          exec(`${opener} "${addr}"`);
+        });
+        process.on("SIGINT", () => {
+          server.close();
+          process.exit(0);
+        });
+      } catch (err) {
+        console.error("Failed to start local server:", err);
+      }
+    }
+  } catch (err) {
+    handleCLIError(err, "Visualization");
+  }
+}
+program.command("visualise").description("Alias for visualize (British spelling)").argument("[directory]", "Directory to analyze", ".").option("--report <path>", "Report path (relative to directory)", "aiready-improvement-report.json").option("-o, --output <path>", "Output HTML path (relative to directory)", "packages/visualizer/visualization.html").option("--open", "Open generated HTML in default browser").option("--serve [port]", "Start a local static server to serve the visualization (optional port number)", false).option("--dev", "Start Vite dev server (live reload) for interactive development", false).addHelpText("after", `
+EXAMPLES:
+  $ aiready visualise . --report aiready-improvement-report.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.
+`).action(async (directory, options) => await handleVisualize(directory, options));
+program.command("visualize").description("Generate interactive visualization from an AIReady report").argument("[directory]", "Directory to analyze", ".").option("--report <path>", "Report path (relative to directory)", "aiready-improvement-report.json").option("-o, --output <path>", "Output HTML path (relative to directory)", "packages/visualizer/visualization.html").option("--open", "Open generated HTML in default browser").option("--serve [port]", "Start a local static server to serve the visualization (optional port number)", false).option("--dev", "Start Vite dev server (live reload) for interactive development", false).addHelpText("after", `
+EXAMPLES:
+  $ aiready visualize . --report aiready-improvement-report.json
+  $ aiready visualize . --report report.json -o out/visualization.html --open
+  $ aiready visualize . --report report.json --serve
+  $ aiready visualize . --report report.json --serve 8080
+  $ aiready visualize . --report report.json --dev
+
+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).
+  - --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.
+`).action(async (directory, options) => await handleVisualize(directory, options));
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/cli",
-  "version": "0.9.2",
+  "version": "0.9.5",
   "description": "Unified CLI for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -11,10 +11,11 @@
   "dependencies": {
     "commander": "^14.0.0",
     "chalk": "^5.3.0",
-    "@aiready/consistency": "0.8.1",
-    "@aiready/context-analyzer": "0.9.1",
-    "@aiready/pattern-detect": "0.11.1",
-    "@aiready/core": "0.9.1"
+    "@aiready/core": "0.9.4",
+    "@aiready/context-analyzer": "0.9.4",
+    "@aiready/visualizer": "0.1.3",
+    "@aiready/consistency": "0.8.4",
+    "@aiready/pattern-detect": "0.11.4"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
@@ -36,7 +37,7 @@
     "url": "https://github.com/caopengau/aiready-cli/issues"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts",
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm",
     "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
     "lint": "eslint src",

package/src/cli.ts

@@ -20,7 +20,10 @@ import {
   type AIReadyConfig,
   type ToolScoringOutput,
 } from '@aiready/core';
-import { readFileSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
+import { resolve as resolvePath } from 'path';
+import { GraphBuilder } from '@aiready/visualizer/graph';
+import type { GraphData } from '@aiready/visualizer';
 
 const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
 
@@ -919,4 +922,318 @@ program
     return markdown;
   }
 
+  function generateHTML(graph: GraphData): string {
+    const payload = JSON.stringify(graph, null, 2);
+    return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AIReady Visualization</title>
+    <style>
+      html,body { height: 100%; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0f172a; color: #e2e8f0 }
+      #container { display:flex; height:100vh }
+      #panel { width: 320px; padding: 16px; background: #071130; box-shadow: -2px 0 8px rgba(0,0,0,0.3); overflow:auto }
+      #canvasWrap { flex:1; display:flex; align-items:center; justify-content:center }
+      canvas { background: #0b1220; border-radius:8px }
+      .stat { margin-bottom:12px }
+    </style>
+  </head>
+  <body>
+    <div id="container">
+      <div id="canvasWrap"><canvas id="canvas" width="1200" height="800"></canvas></div>
+      <div id="panel">
+        <h2>AIReady Visualization</h2>
+        <div class="stat"><strong>Files:</strong> <span id="stat-files"></span></div>
+        <div class="stat"><strong>Dependencies:</strong> <span id="stat-deps"></span></div>
+        <div class="stat"><strong>Legend</strong></div>
+        <div style="font-size:13px;line-height:1.3;color:#cbd5e1;margin-top:8px">
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff4d4f;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Critical</strong>: highest severity issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff9900;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Major</strong>: important issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ffd666;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Minor</strong>: low priority issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#91d5ff;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Info</strong>: informational notes.</div>
+          <div style="margin-top:10px;color:#94a3b8"><strong>Node size</strong>: larger = higher token cost, more issues or dependency weight.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Proximity</strong>: nodes that are spatially close are more contextually related; relatedness is represented by distance and size rather than explicit edges.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Edge colors</strong>: <span style="color:#fb7e81">Similarity</span>, <span style="color:#84c1ff">Dependency</span>, <span style="color:#ffa500">Reference</span>, default <span style="color:#334155">Other</span>.</div>
+        </div>
+      </div>
+    </div>
+
+    <script>
+      const graphData = ${payload};
+      document.getElementById('stat-files').textContent = graphData.metadata.totalFiles;
+      document.getElementById('stat-deps').textContent = graphData.metadata.totalDependencies;
+
+      const canvas = document.getElementById('canvas');
+      const ctx = canvas.getContext('2d');
+
+      const nodes = graphData.nodes.map((n, i) => ({
+        ...n,
+        x: canvas.width / 2 + Math.cos(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+        y: canvas.height / 2 + Math.sin(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+      }));
+
+      function draw() {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+        graphData.edges.forEach(edge => {
+          const s = nodes.find(n => n.id === edge.source);
+          const t = nodes.find(n => n.id === edge.target);
+          if (!s || !t) return;
+          if (edge.type === 'related') return;
+          if (edge.type === 'similarity') {
+            ctx.strokeStyle = '#fb7e81';
+            ctx.lineWidth = 1.2;
+          } else if (edge.type === 'dependency') {
+            ctx.strokeStyle = '#84c1ff';
+            ctx.lineWidth = 1.0;
+          } else if (edge.type === 'reference') {
+            ctx.strokeStyle = '#ffa500';
+            ctx.lineWidth = 0.9;
+          } else {
+            ctx.strokeStyle = '#334155';
+            ctx.lineWidth = 0.8;
+          }
+          ctx.beginPath();
+          ctx.moveTo(s.x, s.y);
+          ctx.lineTo(t.x, t.y);
+          ctx.stroke();
+        });
+
+        const groups = {};
+        nodes.forEach(n => {
+          const g = n.group || '__default';
+          if (!groups[g]) groups[g] = { minX: n.x, minY: n.y, maxX: n.x, maxY: n.y };
+          groups[g].minX = Math.min(groups[g].minX, n.x);
+          groups[g].minY = Math.min(groups[g].minY, n.y);
+          groups[g].maxX = Math.max(groups[g].maxX, n.x);
+          groups[g].maxY = Math.max(groups[g].maxY, n.y);
+        });
+
+        const groupRelations = {};
+        graphData.edges.forEach(edge => {
+          const sNode = nodes.find(n => n.id === edge.source);
+          const tNode = nodes.find(n => n.id === edge.target);
+          if (!sNode || !tNode) return;
+          const g1 = sNode.group || '__default';
+          const g2 = tNode.group || '__default';
+          if (g1 === g2) return;
+          const key = g1 < g2 ? g1 + '::' + g2 : g2 + '::' + g1;
+          groupRelations[key] = (groupRelations[key] || 0) + 1;
+        });
+
+        Object.keys(groupRelations).forEach(k => {
+          const count = groupRelations[k];
+          const [ga, gb] = k.split('::');
+          if (!groups[ga] || !groups[gb]) return;
+          const ax = (groups[ga].minX + groups[ga].maxX) / 2;
+          const ay = (groups[ga].minY + groups[ga].maxY) / 2;
+          const bx = (groups[gb].minX + groups[gb].maxX) / 2;
+          const by = (groups[gb].minY + groups[gb].maxY) / 2;
+          ctx.beginPath();
+          ctx.strokeStyle = 'rgba(148,163,184,0.25)';
+          ctx.lineWidth = Math.min(6, 0.6 + Math.sqrt(count));
+          ctx.moveTo(ax, ay);
+          ctx.lineTo(bx, by);
+          ctx.stroke();
+        });
+
+        Object.keys(groups).forEach(g => {
+          if (g === '__default') return;
+          const box = groups[g];
+          const pad = 16;
+          const x = box.minX - pad;
+          const y = box.minY - pad;
+          const w = (box.maxX - box.minX) + pad * 2;
+          const h = (box.maxY - box.minY) + pad * 2;
+          ctx.save();
+          ctx.fillStyle = 'rgba(30,64,175,0.04)';
+          ctx.strokeStyle = 'rgba(30,64,175,0.12)';
+          ctx.lineWidth = 1.2;
+          const r = 8;
+          ctx.beginPath();
+          ctx.moveTo(x + r, y);
+          ctx.arcTo(x + w, y, x + w, y + h, r);
+          ctx.arcTo(x + w, y + h, x, y + h, r);
+          ctx.arcTo(x, y + h, x, y, r);
+          ctx.arcTo(x, y, x + w, y, r);
+          ctx.closePath();
+          ctx.fill();
+          ctx.stroke();
+          ctx.restore();
+          ctx.fillStyle = '#94a3b8';
+          ctx.font = '11px sans-serif';
+          ctx.fillText(g, x + 8, y + 14);
+        });
+
+        nodes.forEach(n => {
+          const sizeVal = (n.size || n.value || 1);
+          const r = 6 + (sizeVal / 2);
+          ctx.beginPath();
+          ctx.fillStyle = n.color || '#60a5fa';
+          ctx.arc(n.x, n.y, r, 0, Math.PI * 2);
+          ctx.fill();
+
+          ctx.fillStyle = '#e2e8f0';
+          ctx.font = '11px sans-serif';
+          ctx.textAlign = 'center';
+          ctx.fillText(n.label || n.id.split('/').slice(-1)[0], n.x, n.y + r + 12);
+        });
+      }
+
+      draw();
+    </script>
+  </body>
+</html>`;
+  }
+
+  async function handleVisualize(directory: string | undefined, options: any) {
+    try {
+      const dirPath = resolvePath(process.cwd(), directory || '.');
+      const reportPath = resolvePath(dirPath, options.report || 'aiready-improvement-report.json');
+      if (!existsSync(reportPath)) {
+        console.error('Report not found at', reportPath);
+        console.log('Run `aiready scan` to generate the report, or pass --report');
+        return;
+      }
+
+      const raw = readFileSync(reportPath, 'utf8');
+      const report = JSON.parse(raw);
+
+      console.log("Building graph from report...");
+      const { GraphBuilder } = await import('@aiready/visualizer/graph');
+      const graph = GraphBuilder.buildFromReport(report, dirPath);
+
+      if (options.dev) {
+        try {
+          const { spawn } = await import("child_process");
+          const webDir = resolvePath(dirPath, 'packages/visualizer');
+          const watcher = spawn("node", ["scripts/watch-report.js", reportPath], { cwd: webDir, stdio: "inherit" });
+          const vite = spawn("pnpm", ["run", "dev:web"], { cwd: webDir, stdio: "inherit", shell: true });
+          const onExit = () => {
+            try {
+              watcher.kill();
+            } 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("Generating HTML...");
+      const html = generateHTML(graph);
+      const outPath = resolvePath(dirPath, options.output || 'packages/visualizer/visualization.html');
+      writeFileSync(outPath, html, 'utf8');
+      console.log("Visualization written to:", outPath);
+      
+
+      if (options.open) {
+        const { exec } = await import('child_process');
+        const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        exec(`${opener} "${outPath}"`);
+      }
+
+      if (options.serve) {
+        try {
+          const port = Number(options.serve) || 5173;
+          const http = await import('http');
+          const fsp = await import('fs/promises');
+          const { exec } = await import('child_process');
+
+          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');
+            }
+          });
+
+          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';
+            exec(`${opener} "${addr}"`);
+          });
+
+          process.on('SIGINT', () => {
+            server.close();
+            process.exit(0);
+          });
+        } catch (err) {
+          console.error('Failed to start local server:', err);
+        }
+      }
+
+    } catch (err: any) {
+      handleCLIError(err, 'Visualization');
+    }
+  }
+
+// Visualize command: build interactive HTML from an AIReady report
+program
+  .command('visualise')
+  .description('Alias for visualize (British spelling)')
+  .argument('[directory]', 'Directory to analyze', '.')
+  .option('--report <path>', 'Report path (relative to directory)', 'aiready-improvement-report.json')
+  .option('-o, --output <path>', 'Output HTML path (relative to directory)', 'packages/visualizer/visualization.html')
+  .option('--open', 'Open generated HTML in default browser')
+  .option('--serve [port]', 'Start a local static server to serve the visualization (optional port number)', false)
+  .option('--dev', 'Start Vite dev server (live reload) for interactive development', false)
+  .addHelpText('after', `
+EXAMPLES:
+  $ aiready visualise . --report aiready-improvement-report.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.
+`)
+  .action(async (directory, options) => await handleVisualize(directory, options));
+
+program
+  .command('visualize')
+  .description('Generate interactive visualization from an AIReady report')
+  .argument('[directory]', 'Directory to analyze', '.')
+  .option('--report <path>', 'Report path (relative to directory)', 'aiready-improvement-report.json')
+  .option('-o, --output <path>', 'Output HTML path (relative to directory)', 'packages/visualizer/visualization.html')
+  .option('--open', 'Open generated HTML in default browser')
+  .option('--serve [port]', 'Start a local static server to serve the visualization (optional port number)', false)
+  .option('--dev', 'Start Vite dev server (live reload) for interactive development', false)
+  .addHelpText('after', `
+EXAMPLES:
+  $ aiready visualize . --report aiready-improvement-report.json
+  $ aiready visualize . --report report.json -o out/visualization.html --open
+  $ aiready visualize . --report report.json --serve
+  $ aiready visualize . --report report.json --serve 8080
+  $ aiready visualize . --report report.json --dev
+
+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).
+  - --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.
+`)
+  .action(async (directory, options) => await handleVisualize(directory, options));
+
 program.parse();