@aiready/cli 0.9.2 → 0.9.6

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.6 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/index.js 4.93 KB
-CJS dist/cli.js   44.24 KB
-CJS ⚡️ Build success in 22ms
-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 dist/cli.mjs            50.92 KB
+ESM dist/chunk-3SG2GLFJ.mjs 3.80 KB
+ESM ⚡️ Build success in 32ms
+CJS dist/cli.js   58.06 KB
+CJS dist/index.js 4.93 KB
+CJS ⚡️ Build success in 32ms

package/.turbo/turbo-test.log

@@ -1,34 +1,17 @@
 
 
-> @aiready/cli@0.9.1 test /Users/pengcao/projects/aiready/packages/cli
+> @aiready/cli@0.9.6 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]
+ ✓ src/__tests__/cli.test.ts (3 tests) 2ms
+ ✓ dist/__tests__/cli.test.js (3 tests) 2ms
 
- 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
-
- 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)
+ Test Files  2 passed (2)
+      Tests  6 passed (6)
+   Start at  22:40:01
+   Duration  1.23s (transform 446ms, setup 0ms, import 1.97s, tests 4ms, environment 0ms)
 
 [?25h

package/dist/__tests__/cli.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.test.d.ts.map

package/dist/__tests__/cli.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cli.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/cli.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi } from 'vitest';
+import { analyzeUnified } from '../index';
+// Mock the individual tools
+vi.mock('@aiready/pattern-detect', () => ({
+    analyzePatterns: vi.fn().mockResolvedValue({
+        results: [],
+        duplicates: [],
+        files: [],
+    }),
+    generateSummary: vi.fn().mockReturnValue({
+        totalDuplicateLines: 0,
+        potentialSavings: 0,
+    }),
+}));
+vi.mock('@aiready/context-analyzer', () => ({
+    analyzeContext: vi.fn().mockResolvedValue([]),
+    generateSummary: vi.fn().mockReturnValue({
+        totalFiles: 0,
+        averageCohesion: 0,
+        averageFragmentation: 0,
+    }),
+}));
+describe('CLI Unified Analysis', () => {
+    it('should run unified analysis with both tools', async () => {
+        const results = await analyzeUnified({
+            rootDir: '/test',
+            tools: ['patterns', 'context'],
+        });
+        expect(results).toHaveProperty('patterns');
+        expect(results).toHaveProperty('context');
+        expect(results).toHaveProperty('summary');
+    });
+    it('should run analysis with only patterns tool', async () => {
+        const results = await analyzeUnified({
+            rootDir: '/test',
+            tools: ['patterns'],
+        });
+        expect(results).toHaveProperty('patterns');
+        expect(results).not.toHaveProperty('context');
+        expect(results).toHaveProperty('summary');
+    });
+    it('should run analysis with only context tool', async () => {
+        const results = await analyzeUnified({
+            rootDir: '/test',
+            tools: ['context'],
+        });
+        expect(results).not.toHaveProperty('patterns');
+        expect(results).toHaveProperty('context');
+        expect(results).toHaveProperty('summary');
+    });
+});
+//# sourceMappingURL=cli.test.js.map

package/dist/__tests__/cli.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.test.js","sourceRoot":"","sources":["../../src/__tests__/cli.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C,4BAA4B;AAC5B,EAAE,CAAC,IAAI,CAAC,yBAAyB,EAAE,GAAG,EAAE,CAAC,CAAC;IACxC,eAAe,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC;QACzC,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,EAAE;QACd,KAAK,EAAE,EAAE;KACV,CAAC;IACF,eAAe,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC;QACvC,mBAAmB,EAAE,CAAC;QACtB,gBAAgB,EAAE,CAAC;KACpB,CAAC;CACH,CAAC,CAAC,CAAC;AAEJ,EAAE,CAAC,IAAI,CAAC,2BAA2B,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1C,cAAc,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAC7C,eAAe,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC;QACvC,UAAU,EAAE,CAAC;QACb,eAAe,EAAE,CAAC;QAClB,oBAAoB,EAAE,CAAC;KACxB,CAAC;CACH,CAAC,CAAC,CAAC;AAEJ,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;QAC3D,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC;YACnC,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;SAC/B,CAAC,CAAC;QAEH,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAC1C,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;QAC3D,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC;YACnC,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,CAAC,UAAU,CAAC;SACpB,CAAC,CAAC;QAEH,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAC9C,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC;YACnC,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,CAAC,SAAS,CAAC;SACnB,CAAC,CAAC;QAEH,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAC/C,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAC1C,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

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.d.ts

@@ -1 +1,3 @@
 #!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

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();