@aiready/cli 0.9.25 → 0.9.27

package/.turbo/turbo-build.log

@@ -1,18 +1,17 @@
-
-
-> @aiready/cli@0.9.23 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
-CLI tsup v8.5.1
-CLI Target: es2020
-CJS Build start
-ESM Build start
-ESM dist/index.mjs          138.00 B
-ESM dist/chunk-5GZDRZ3T.mjs 4.17 KB
-ESM dist/cli.mjs            57.52 KB
-ESM ⚡️ Build success in 140ms
-CJS dist/index.js 4.93 KB
-CJS dist/cli.js   65.17 KB
-CJS ⚡️ Build success in 141ms
+
+> @aiready/cli@0.9.26 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
+CLI tsup v8.5.1
+CLI Target: es2020
+CJS Build start
+ESM Build start
+CJS dist/cli.js   57.70 KB
+CJS dist/index.js 4.93 KB
+CJS ⚡️ Build success in 32ms
+ESM dist/cli.mjs            50.05 KB
+ESM dist/index.mjs          138.00 B
+ESM dist/chunk-5GZDRZ3T.mjs 4.17 KB
+ESM ⚡️ Build success in 32ms

package/.turbo/turbo-test.log

@@ -1,17 +1,17 @@
 
 
-> @aiready/cli@0.9.23 test /Users/pengcao/projects/aiready/packages/cli
+> @aiready/cli@0.9.25 test /Users/pengcao/projects/aiready/packages/cli
 > vitest run
 
 [?25l
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/cli
 
- ✓ dist/__tests__/cli.test.js (3 tests) 5ms
- ✓ src/__tests__/cli.test.ts (3 tests) 67ms
+ ✓ dist/__tests__/cli.test.js (3 tests) 39ms
+ ✓ src/__tests__/cli.test.ts (3 tests) 7ms
 
  Test Files  2 passed (2)
       Tests  6 passed (6)
-   Start at  11:30:30
-   Duration  3.93s (transform 604ms, setup 0ms, import 4.85s, tests 72ms, environment 0ms)
+   Start at  14:43:49
+   Duration  5.00s (transform 1.06s, setup 0ms, import 7.11s, tests 47ms, environment 1ms)
 
 [?25h

package/dist/cli.js

@@ -157,12 +157,24 @@ VERSION: ${packageJson.version}
 DOCUMENTATION: https://aiready.dev/docs/cli
 GITHUB: https://github.com/caopengau/aiready-cli
 LANDING: https://github.com/caopengau/aiready-landing`);
-program.command("scan").description("Run comprehensive AI-readiness analysis (patterns + context + consistency)").argument("[directory]", "Directory to analyze", ".").option("-t, --tools <tools>", "Tools to run (comma-separated: patterns,context,consistency)", "patterns,context,consistency").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "json").option("--output-file <path>", "Output file path (for json)").option("--no-score", "Disable calculating AI Readiness Score (enabled by default)").option("--weights <weights>", "Custom scoring weights (patterns:40,context:35,consistency:25)").option("--threshold <score>", "Fail CI/CD if score below threshold (0-100)").addHelpText("after", `
+program.command("scan").description("Run comprehensive AI-readiness analysis (patterns + context + consistency)").argument("[directory]", "Directory to analyze", ".").option("-t, --tools <tools>", "Tools to run (comma-separated: patterns,context,consistency)", "patterns,context,consistency").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "json").option("--output-file <path>", "Output file path (for json)").option("--no-score", "Disable calculating AI Readiness Score (enabled by default)").option("--weights <weights>", "Custom scoring weights (patterns:40,context:35,consistency:25)").option("--threshold <score>", "Fail CI/CD if score below threshold (0-100)").option("--ci", "CI mode: GitHub Actions annotations, no colors, fail on threshold").option("--fail-on <level>", "Fail on issues: critical, major, any", "critical").addHelpText("after", `
 EXAMPLES:
   $ aiready scan                                    # Analyze all tools
   $ aiready scan --tools patterns,context           # Skip consistency
   $ aiready scan --score --threshold 75             # CI/CD with threshold
+  $ aiready scan --ci --threshold 70                # GitHub Actions gatekeeper
+  $ aiready scan --ci --fail-on major               # Fail on major+ issues
   $ aiready scan --output json --output-file report.json
+
+CI/CD INTEGRATION (Gatekeeper Mode):
+  Use --ci for GitHub Actions integration:
+  - Outputs GitHub Actions annotations for PR checks
+  - Fails with exit code 1 if threshold not met
+  - Shows clear "blocked" message with remediation steps
+
+  Example GitHub Actions workflow:
+    - name: AI Readiness Check
+      run: aiready scan --ci --threshold 70
 `).action(async (directory, options) => {
   console.log(import_chalk.default.blue("\u{1F680} Starting AIReady unified analysis...\n"));
   const startTime = Date.now();
@@ -394,6 +406,91 @@ EXAMPLES:
       (0, import_core.handleJSONOutput)(outputData, outputPath, `\u2705 Report saved to ${outputPath}`);
       warnIfGraphCapExceeded(outputData, resolvedDir);
     }
+    const isCI = options.ci || process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true";
+    if (isCI && scoringResult) {
+      const threshold = options.threshold ? parseInt(options.threshold) : void 0;
+      const failOnLevel = options.failOn || "critical";
+      if (process.env.GITHUB_ACTIONS === "true") {
+        console.log(`
+::group::AI Readiness Score`);
+        console.log(`score=${scoringResult.overallScore}`);
+        if (scoringResult.breakdown) {
+          scoringResult.breakdown.forEach((tool) => {
+            console.log(`${tool.toolName}=${tool.score}`);
+          });
+        }
+        console.log("::endgroup::");
+        if (threshold && scoringResult.overallScore < threshold) {
+          console.log(`::error::AI Readiness Score ${scoringResult.overallScore} is below threshold ${threshold}`);
+        } else if (threshold) {
+          console.log(`::notice::AI Readiness Score: ${scoringResult.overallScore}/100 (threshold: ${threshold})`);
+        }
+        if (results.patterns) {
+          const criticalPatterns = results.patterns.flatMap(
+            (p) => p.issues.filter((i) => i.severity === "critical")
+          );
+          criticalPatterns.slice(0, 10).forEach((issue) => {
+            console.log(`::warning file=${issue.location?.file || "unknown"},line=${issue.location?.line || 1}::${issue.message}`);
+          });
+        }
+      }
+      let shouldFail = false;
+      let failReason = "";
+      if (threshold && scoringResult.overallScore < threshold) {
+        shouldFail = true;
+        failReason = `AI Readiness Score ${scoringResult.overallScore} is below threshold ${threshold}`;
+      }
+      if (failOnLevel !== "none") {
+        const severityLevels = { critical: 4, major: 3, minor: 2, any: 1 };
+        const minSeverity = severityLevels[failOnLevel] || 4;
+        let criticalCount = 0;
+        let majorCount = 0;
+        if (results.patterns) {
+          results.patterns.forEach((p) => {
+            p.issues.forEach((i) => {
+              if (i.severity === "critical") criticalCount++;
+              if (i.severity === "major") majorCount++;
+            });
+          });
+        }
+        if (results.context) {
+          results.context.forEach((c) => {
+            if (c.severity === "critical") criticalCount++;
+            if (c.severity === "major") majorCount++;
+          });
+        }
+        if (results.consistency?.results) {
+          results.consistency.results.forEach((r) => {
+            r.issues?.forEach((i) => {
+              if (i.severity === "critical") criticalCount++;
+              if (i.severity === "major") majorCount++;
+            });
+          });
+        }
+        if (minSeverity >= 4 && criticalCount > 0) {
+          shouldFail = true;
+          failReason = `Found ${criticalCount} critical issues`;
+        } else if (minSeverity >= 3 && criticalCount + majorCount > 0) {
+          shouldFail = true;
+          failReason = `Found ${criticalCount} critical and ${majorCount} major issues`;
+        }
+      }
+      if (shouldFail) {
+        console.log(import_chalk.default.red("\n\u{1F6AB} PR BLOCKED: AI Readiness Check Failed"));
+        console.log(import_chalk.default.red(`   Reason: ${failReason}`));
+        console.log(import_chalk.default.dim("\n   Remediation steps:"));
+        console.log(import_chalk.default.dim("   1. Run `aiready scan` locally to see detailed issues"));
+        console.log(import_chalk.default.dim("   2. Fix the critical issues before merging"));
+        console.log(import_chalk.default.dim("   3. Consider upgrading to Team plan for historical tracking: https://getaiready.dev/pricing"));
+        process.exit(1);
+      } else {
+        console.log(import_chalk.default.green("\n\u2705 PR PASSED: AI Readiness Check"));
+        if (threshold) {
+          console.log(import_chalk.default.green(`   Score: ${scoringResult.overallScore}/100 (threshold: ${threshold})`));
+        }
+        console.log(import_chalk.default.dim("\n   \u{1F4A1} Track historical trends: https://getaiready.dev \u2014 Team plan $99/mo"));
+      }
+    }
   } catch (error) {
     (0, import_core.handleCLIError)(error, "Analysis");
   }
@@ -817,170 +914,6 @@ 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>`;
-}
 function getReportTimestamp() {
   const now = /* @__PURE__ */ new Date();
   const pad = (n) => String(n).padStart(2, "0");
@@ -1173,7 +1106,7 @@ Or specify a custom report:
       }
     }
     console.log("Generating HTML...");
-    const html = generateHTML(graph);
+    const html = (0, import_core.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);
@@ -1184,7 +1117,7 @@ Or specify a custom report:
     }
     if (options.serve) {
       try {
-        const port = Number(options.serve) || 5173;
+        const port = typeof options.serve === "number" ? options.serve : 5173;
         const http = await import("http");
         const fsp = await import("fs/promises");
         const { exec } = await import("child_process");

package/dist/cli.mjs

@@ -20,7 +20,8 @@ import {
   formatToolScore,
   getRating,
   getRatingDisplay,
-  parseWeightString
+  parseWeightString,
+  generateHTML
 } from "@aiready/core";
 import { readFileSync, existsSync, copyFileSync } from "fs";
 import { resolve as resolvePath } from "path";
@@ -62,12 +63,24 @@ VERSION: ${packageJson.version}
 DOCUMENTATION: https://aiready.dev/docs/cli
 GITHUB: https://github.com/caopengau/aiready-cli
 LANDING: https://github.com/caopengau/aiready-landing`);
-program.command("scan").description("Run comprehensive AI-readiness analysis (patterns + context + consistency)").argument("[directory]", "Directory to analyze", ".").option("-t, --tools <tools>", "Tools to run (comma-separated: patterns,context,consistency)", "patterns,context,consistency").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "json").option("--output-file <path>", "Output file path (for json)").option("--no-score", "Disable calculating AI Readiness Score (enabled by default)").option("--weights <weights>", "Custom scoring weights (patterns:40,context:35,consistency:25)").option("--threshold <score>", "Fail CI/CD if score below threshold (0-100)").addHelpText("after", `
+program.command("scan").description("Run comprehensive AI-readiness analysis (patterns + context + consistency)").argument("[directory]", "Directory to analyze", ".").option("-t, --tools <tools>", "Tools to run (comma-separated: patterns,context,consistency)", "patterns,context,consistency").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "json").option("--output-file <path>", "Output file path (for json)").option("--no-score", "Disable calculating AI Readiness Score (enabled by default)").option("--weights <weights>", "Custom scoring weights (patterns:40,context:35,consistency:25)").option("--threshold <score>", "Fail CI/CD if score below threshold (0-100)").option("--ci", "CI mode: GitHub Actions annotations, no colors, fail on threshold").option("--fail-on <level>", "Fail on issues: critical, major, any", "critical").addHelpText("after", `
 EXAMPLES:
   $ aiready scan                                    # Analyze all tools
   $ aiready scan --tools patterns,context           # Skip consistency
   $ aiready scan --score --threshold 75             # CI/CD with threshold
+  $ aiready scan --ci --threshold 70                # GitHub Actions gatekeeper
+  $ aiready scan --ci --fail-on major               # Fail on major+ issues
   $ aiready scan --output json --output-file report.json
+
+CI/CD INTEGRATION (Gatekeeper Mode):
+  Use --ci for GitHub Actions integration:
+  - Outputs GitHub Actions annotations for PR checks
+  - Fails with exit code 1 if threshold not met
+  - Shows clear "blocked" message with remediation steps
+
+  Example GitHub Actions workflow:
+    - name: AI Readiness Check
+      run: aiready scan --ci --threshold 70
 `).action(async (directory, options) => {
   console.log(chalk.blue("\u{1F680} Starting AIReady unified analysis...\n"));
   const startTime = Date.now();
@@ -299,6 +312,91 @@ EXAMPLES:
       handleJSONOutput(outputData, outputPath, `\u2705 Report saved to ${outputPath}`);
       warnIfGraphCapExceeded(outputData, resolvedDir);
     }
+    const isCI = options.ci || process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true";
+    if (isCI && scoringResult) {
+      const threshold = options.threshold ? parseInt(options.threshold) : void 0;
+      const failOnLevel = options.failOn || "critical";
+      if (process.env.GITHUB_ACTIONS === "true") {
+        console.log(`
+::group::AI Readiness Score`);
+        console.log(`score=${scoringResult.overallScore}`);
+        if (scoringResult.breakdown) {
+          scoringResult.breakdown.forEach((tool) => {
+            console.log(`${tool.toolName}=${tool.score}`);
+          });
+        }
+        console.log("::endgroup::");
+        if (threshold && scoringResult.overallScore < threshold) {
+          console.log(`::error::AI Readiness Score ${scoringResult.overallScore} is below threshold ${threshold}`);
+        } else if (threshold) {
+          console.log(`::notice::AI Readiness Score: ${scoringResult.overallScore}/100 (threshold: ${threshold})`);
+        }
+        if (results.patterns) {
+          const criticalPatterns = results.patterns.flatMap(
+            (p) => p.issues.filter((i) => i.severity === "critical")
+          );
+          criticalPatterns.slice(0, 10).forEach((issue) => {
+            console.log(`::warning file=${issue.location?.file || "unknown"},line=${issue.location?.line || 1}::${issue.message}`);
+          });
+        }
+      }
+      let shouldFail = false;
+      let failReason = "";
+      if (threshold && scoringResult.overallScore < threshold) {
+        shouldFail = true;
+        failReason = `AI Readiness Score ${scoringResult.overallScore} is below threshold ${threshold}`;
+      }
+      if (failOnLevel !== "none") {
+        const severityLevels = { critical: 4, major: 3, minor: 2, any: 1 };
+        const minSeverity = severityLevels[failOnLevel] || 4;
+        let criticalCount = 0;
+        let majorCount = 0;
+        if (results.patterns) {
+          results.patterns.forEach((p) => {
+            p.issues.forEach((i) => {
+              if (i.severity === "critical") criticalCount++;
+              if (i.severity === "major") majorCount++;
+            });
+          });
+        }
+        if (results.context) {
+          results.context.forEach((c) => {
+            if (c.severity === "critical") criticalCount++;
+            if (c.severity === "major") majorCount++;
+          });
+        }
+        if (results.consistency?.results) {
+          results.consistency.results.forEach((r) => {
+            r.issues?.forEach((i) => {
+              if (i.severity === "critical") criticalCount++;
+              if (i.severity === "major") majorCount++;
+            });
+          });
+        }
+        if (minSeverity >= 4 && criticalCount > 0) {
+          shouldFail = true;
+          failReason = `Found ${criticalCount} critical issues`;
+        } else if (minSeverity >= 3 && criticalCount + majorCount > 0) {
+          shouldFail = true;
+          failReason = `Found ${criticalCount} critical and ${majorCount} major issues`;
+        }
+      }
+      if (shouldFail) {
+        console.log(chalk.red("\n\u{1F6AB} PR BLOCKED: AI Readiness Check Failed"));
+        console.log(chalk.red(`   Reason: ${failReason}`));
+        console.log(chalk.dim("\n   Remediation steps:"));
+        console.log(chalk.dim("   1. Run `aiready scan` locally to see detailed issues"));
+        console.log(chalk.dim("   2. Fix the critical issues before merging"));
+        console.log(chalk.dim("   3. Consider upgrading to Team plan for historical tracking: https://getaiready.dev/pricing"));
+        process.exit(1);
+      } else {
+        console.log(chalk.green("\n\u2705 PR PASSED: AI Readiness Check"));
+        if (threshold) {
+          console.log(chalk.green(`   Score: ${scoringResult.overallScore}/100 (threshold: ${threshold})`));
+        }
+        console.log(chalk.dim("\n   \u{1F4A1} Track historical trends: https://getaiready.dev \u2014 Team plan $99/mo"));
+      }
+    }
   } catch (error) {
     handleCLIError(error, "Analysis");
   }
@@ -722,170 +820,6 @@ 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>`;
-}
 function getReportTimestamp() {
   const now = /* @__PURE__ */ new Date();
   const pad = (n) => String(n).padStart(2, "0");
@@ -1089,7 +1023,7 @@ Or specify a custom report:
     }
     if (options.serve) {
       try {
-        const port = Number(options.serve) || 5173;
+        const port = typeof options.serve === "number" ? options.serve : 5173;
         const http = await import("http");
         const fsp = await import("fs/promises");
         const { exec } = await import("child_process");

package/package.json

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

package/src/cli.ts

@@ -17,6 +17,7 @@ import {
   getRating,
   getRatingDisplay,
   parseWeightString,
+  generateHTML,
   type AIReadyConfig,
   type ToolScoringOutput,
 } from '@aiready/core';
@@ -82,12 +83,26 @@ program
   .option('--no-score', 'Disable calculating AI Readiness Score (enabled by default)')
   .option('--weights <weights>', 'Custom scoring weights (patterns:40,context:35,consistency:25)')
   .option('--threshold <score>', 'Fail CI/CD if score below threshold (0-100)')
+  .option('--ci', 'CI mode: GitHub Actions annotations, no colors, fail on threshold')
+  .option('--fail-on <level>', 'Fail on issues: critical, major, any', 'critical')
   .addHelpText('after', `
 EXAMPLES:
   $ aiready scan                                    # Analyze all tools
   $ aiready scan --tools patterns,context           # Skip consistency
   $ aiready scan --score --threshold 75             # CI/CD with threshold
+  $ aiready scan --ci --threshold 70                # GitHub Actions gatekeeper
+  $ aiready scan --ci --fail-on major               # Fail on major+ issues
   $ aiready scan --output json --output-file report.json
+
+CI/CD INTEGRATION (Gatekeeper Mode):
+  Use --ci for GitHub Actions integration:
+  - Outputs GitHub Actions annotations for PR checks
+  - Fails with exit code 1 if threshold not met
+  - Shows clear "blocked" message with remediation steps
+
+  Example GitHub Actions workflow:
+    - name: AI Readiness Check
+      run: aiready scan --ci --threshold 70
 `)
   .action(async (directory, options) => {
     console.log(chalk.blue('🚀 Starting AIReady unified analysis...\n'));
@@ -385,6 +400,109 @@ EXAMPLES:
         // Warn if graph caps may be exceeded
         warnIfGraphCapExceeded(outputData, resolvedDir);
       }
+
+      // CI/CD Gatekeeper Mode
+      const isCI = options.ci || process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
+      if (isCI && scoringResult) {
+        const threshold = options.threshold ? parseInt(options.threshold) : undefined;
+        const failOnLevel = options.failOn || 'critical';
+        
+        // Output GitHub Actions annotations
+        if (process.env.GITHUB_ACTIONS === 'true') {
+          console.log(`\n::group::AI Readiness Score`);
+          console.log(`score=${scoringResult.overallScore}`);
+          if (scoringResult.breakdown) {
+            scoringResult.breakdown.forEach(tool => {
+              console.log(`${tool.toolName}=${tool.score}`);
+            });
+          }
+          console.log('::endgroup::');
+          
+          // Output annotation for score
+          if (threshold && scoringResult.overallScore < threshold) {
+            console.log(`::error::AI Readiness Score ${scoringResult.overallScore} is below threshold ${threshold}`);
+          } else if (threshold) {
+            console.log(`::notice::AI Readiness Score: ${scoringResult.overallScore}/100 (threshold: ${threshold})`);
+          }
+          
+          // Output annotations for critical issues
+          if (results.patterns) {
+            const criticalPatterns = results.patterns.flatMap((p: any) => 
+              p.issues.filter((i: any) => i.severity === 'critical')
+            );
+            criticalPatterns.slice(0, 10).forEach((issue: any) => {
+              console.log(`::warning file=${issue.location?.file || 'unknown'},line=${issue.location?.line || 1}::${issue.message}`);
+            });
+          }
+        }
+
+        // Determine if we should fail
+        let shouldFail = false;
+        let failReason = '';
+        
+        // Check threshold
+        if (threshold && scoringResult.overallScore < threshold) {
+          shouldFail = true;
+          failReason = `AI Readiness Score ${scoringResult.overallScore} is below threshold ${threshold}`;
+        }
+        
+        // Check fail-on severity
+        if (failOnLevel !== 'none') {
+          const severityLevels = { critical: 4, major: 3, minor: 2, any: 1 };
+          const minSeverity = severityLevels[failOnLevel as keyof typeof severityLevels] || 4;
+          
+          let criticalCount = 0;
+          let majorCount = 0;
+          
+          if (results.patterns) {
+            results.patterns.forEach((p: any) => {
+              p.issues.forEach((i: any) => {
+                if (i.severity === 'critical') criticalCount++;
+                if (i.severity === 'major') majorCount++;
+              });
+            });
+          }
+          if (results.context) {
+            results.context.forEach((c: any) => {
+              if (c.severity === 'critical') criticalCount++;
+              if (c.severity === 'major') majorCount++;
+            });
+          }
+          if (results.consistency?.results) {
+            results.consistency.results.forEach((r: any) => {
+              r.issues?.forEach((i: any) => {
+                if (i.severity === 'critical') criticalCount++;
+                if (i.severity === 'major') majorCount++;
+              });
+            });
+          }
+          
+          if (minSeverity >= 4 && criticalCount > 0) {
+            shouldFail = true;
+            failReason = `Found ${criticalCount} critical issues`;
+          } else if (minSeverity >= 3 && (criticalCount + majorCount) > 0) {
+            shouldFail = true;
+            failReason = `Found ${criticalCount} critical and ${majorCount} major issues`;
+          }
+        }
+        
+        // Output result
+        if (shouldFail) {
+          console.log(chalk.red('\n🚫 PR BLOCKED: AI Readiness Check Failed'));
+          console.log(chalk.red(`   Reason: ${failReason}`));
+          console.log(chalk.dim('\n   Remediation steps:'));
+          console.log(chalk.dim('   1. Run `aiready scan` locally to see detailed issues'));
+          console.log(chalk.dim('   2. Fix the critical issues before merging'));
+          console.log(chalk.dim('   3. Consider upgrading to Team plan for historical tracking: https://getaiready.dev/pricing'));
+          process.exit(1);
+        } else {
+          console.log(chalk.green('\n✅ PR PASSED: AI Readiness Check'));
+          if (threshold) {
+            console.log(chalk.green(`   Score: ${scoringResult.overallScore}/100 (threshold: ${threshold})`));
+          }
+          console.log(chalk.dim('\n   💡 Track historical trends: https://getaiready.dev — Team plan $99/mo'));
+        }
+      }
     } catch (error) {
       handleCLIError(error, 'Analysis');
     }
@@ -930,170 +1048,6 @@ 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>`;
-  }
 
   /**
    * Generate timestamp for report filenames (YYYYMMDD-HHMMSS)
@@ -1351,7 +1305,7 @@ program
 
       if (options.serve) {
         try {
-          const port = Number(options.serve) || 5173;
+          const port = typeof options.serve === 'number' ? options.serve : 5173;
           const http = await import('http');
           const fsp = await import('fs/promises');
           const { exec } = await import('child_process');