@kevinrabun/judges-cli 3.124.0

package/dist/commands/governance.js

@@ -0,0 +1,202 @@
+/**
+ * `judges governance` — Multi-repo governance dashboard.
+ *
+ * Aggregates snapshot data from multiple repos into a unified governance view.
+ * Teams self-host their own snapshot files; this command reads them from a
+ * directory of exported snapshots (each repo pushes to a shared location).
+ *
+ * Usage:
+ *   judges governance --dir ./governance-data         # read snapshots from dir
+ *   judges governance --dir ./governance-data --html  # HTML dashboard output
+ *   judges governance --dir ./governance-data --json  # JSON output
+ */
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { resolve, basename } from "path";
+import { computeTrend, detectRegressions } from "./snapshot.js";
+// ─── Grade Calculation ──────────────────────────────────────────────────────
+function gradeFromTrend(trend) {
+    const t = trend.stats;
+    if (t.currentTotal === 0 && t.trend === "improving")
+        return "A";
+    if (t.currentTotal <= 3 && t.trend !== "regressing")
+        return "A";
+    if (t.currentTotal <= 10 && t.trend !== "regressing")
+        return "B";
+    if (t.currentTotal <= 20)
+        return "C";
+    if (t.currentTotal <= 50)
+        return "D";
+    return "F";
+}
+// ─── Snapshot Directory Loading ─────────────────────────────────────────────
+function loadSnapshotFiles(dir) {
+    const repos = new Map();
+    if (!existsSync(dir))
+        return repos;
+    const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+    for (const file of files) {
+        try {
+            const raw = readFileSync(resolve(dir, file), "utf-8");
+            const store = JSON.parse(raw);
+            if (store.version === 1 && Array.isArray(store.snapshots)) {
+                // Use filename (minus extension) as repo name
+                const repoName = basename(file, ".json").replace(/-snapshots$/, "");
+                repos.set(repoName, store);
+            }
+        }
+        catch {
+            // Skip invalid files
+        }
+    }
+    return repos;
+}
+// ─── Report Generation ──────────────────────────────────────────────────────
+export function buildGovernanceReport(dir) {
+    const stores = loadSnapshotFiles(dir);
+    const repos = [];
+    let totalFindings = 0;
+    const criticalRepos = [];
+    for (const [repoName, store] of stores) {
+        const trend = computeTrend(store);
+        const regressions = detectRegressions(store);
+        const grade = gradeFromTrend(trend);
+        repos.push({
+            repo: repoName,
+            trend,
+            regressions,
+            lastRun: trend.stats.lastRun,
+            grade,
+        });
+        totalFindings += trend.stats.currentTotal;
+        if (grade === "D" || grade === "F" || regressions.some((r) => r.severity === "error")) {
+            criticalRepos.push(repoName);
+        }
+    }
+    // Sort by grade (worst first) then by findings count
+    const gradeOrder = { F: 0, D: 1, C: 2, B: 3, A: 4 };
+    repos.sort((a, b) => (gradeOrder[a.grade] ?? 5) - (gradeOrder[b.grade] ?? 5) ||
+        b.trend.stats.currentTotal - a.trend.stats.currentTotal);
+    const overallHealth = criticalRepos.length === 0 ? "healthy" : criticalRepos.length <= repos.length * 0.3 ? "at-risk" : "critical";
+    return {
+        repos,
+        overallHealth,
+        totalFindings,
+        repoCount: repos.length,
+        criticalRepos,
+        generatedAt: new Date().toISOString(),
+    };
+}
+// ─── CLI Formatters ─────────────────────────────────────────────────────────
+function formatGovernanceText(report) {
+    const lines = [];
+    const healthIcon = report.overallHealth === "healthy" ? "✅" : report.overallHealth === "at-risk" ? "⚠️ " : "🔴";
+    lines.push("╔══════════════════════════════════════════════════════════════╗");
+    lines.push("║        Judges Panel — Governance Dashboard                  ║");
+    lines.push("╚══════════════════════════════════════════════════════════════╝");
+    lines.push("");
+    lines.push(`  Health    : ${healthIcon} ${report.overallHealth.toUpperCase()}`);
+    lines.push(`  Repos     : ${report.repoCount}`);
+    lines.push(`  Findings  : ${report.totalFindings} total across all repos`);
+    if (report.criticalRepos.length > 0) {
+        lines.push(`  Critical  : ${report.criticalRepos.join(", ")}`);
+    }
+    lines.push(`  Generated : ${report.generatedAt.slice(0, 10)}`);
+    lines.push("");
+    lines.push("  Repository Summary:");
+    lines.push("  " + "─".repeat(58));
+    lines.push(`  ${"Repository".padEnd(30)} Grade  Findings  Trend`);
+    lines.push("  " + "─".repeat(58));
+    for (const r of report.repos) {
+        const trendIcon = r.trend.stats.trend === "improving" ? "📉" : r.trend.stats.trend === "regressing" ? "📈" : "➡️ ";
+        const findings = String(r.trend.stats.currentTotal).padStart(6);
+        lines.push(`  ${r.repo.padEnd(30)} ${r.grade.padEnd(6)} ${findings}   ${trendIcon} ${r.trend.stats.trend}`);
+        if (r.regressions.length > 0) {
+            for (const alert of r.regressions.slice(0, 2)) {
+                const icon = alert.severity === "error" ? "🔴" : "🟡";
+                lines.push(`    ${icon} ${alert.message}`);
+            }
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function formatGovernanceHtml(report) {
+    const healthColor = report.overallHealth === "healthy" ? "#16a34a" : report.overallHealth === "at-risk" ? "#ca8a04" : "#dc2626";
+    const gradeColor = { A: "#16a34a", B: "#65a30d", C: "#ca8a04", D: "#ea580c", F: "#dc2626" };
+    const rows = report.repos
+        .map((r) => `<tr>
+      <td>${esc(r.repo)}</td>
+      <td style="color:${gradeColor[r.grade] ?? "#666"};font-weight:700">${r.grade}</td>
+      <td>${r.trend.stats.currentTotal}</td>
+      <td>${r.trend.stats.trend}</td>
+      <td>${r.regressions.length}</td>
+      <td>${r.lastRun.slice(0, 10)}</td>
+    </tr>`)
+        .join("\n");
+    return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Judges Governance Dashboard</title>
+<style>
+  :root{--bg:#fff;--fg:#1a1a1a;--card:#f9fafb;--border:#e5e7eb;--muted:#6b7280}
+  @media(prefers-color-scheme:dark){:root{--bg:#0f172a;--fg:#e2e8f0;--card:#1e293b;--border:#334155;--muted:#94a3b8}}
+  *{margin:0;padding:0;box-sizing:border-box}
+  body{font-family:system-ui,sans-serif;background:var(--bg);color:var(--fg);padding:2rem}
+  h1{margin-bottom:1rem}
+  .badge{display:inline-block;padding:.25rem .75rem;border-radius:4px;font-weight:700}
+  table{width:100%;border-collapse:collapse;margin-top:1rem}
+  th,td{padding:.5rem .75rem;text-align:left;border-bottom:1px solid var(--border)}
+  th{font-size:.75rem;text-transform:uppercase;color:var(--muted)}
+</style></head><body>
+<h1>Judges Panel &mdash; Governance Dashboard</h1>
+<p><span class="badge" style="background:${healthColor};color:#fff">${esc(report.overallHealth.toUpperCase())}</span>
+${report.repoCount} repos, ${report.totalFindings} total findings</p>
+<table><thead><tr><th>Repository</th><th>Grade</th><th>Findings</th><th>Trend</th><th>Alerts</th><th>Last Run</th></tr></thead>
+<tbody>${rows}</tbody></table>
+<p style="margin-top:2rem;font-size:.75rem;color:var(--muted)">Generated ${report.generatedAt.slice(0, 10)} by Judges Panel</p>
+</body></html>`;
+}
+function esc(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+// ─── CLI Command ────────────────────────────────────────────────────────────
+export function runGovernance(argv) {
+    let dir = ".";
+    let format = "text";
+    for (let i = 3; i < argv.length; i++) {
+        switch (argv[i]) {
+            case "--dir":
+            case "-d":
+                dir = argv[++i] || ".";
+                break;
+            case "--html":
+                format = "html";
+                break;
+            case "--json":
+                format = "json";
+                break;
+            case "--format":
+                format = argv[++i] || "text";
+                break;
+        }
+    }
+    if (!existsSync(dir)) {
+        console.error(`Error: Directory not found: ${dir}`);
+        console.error("Usage: judges governance --dir ./governance-data");
+        process.exit(1);
+    }
+    const report = buildGovernanceReport(dir);
+    if (report.repoCount === 0) {
+        console.log("\n  No snapshot files found. Export repo snapshots as JSON files to the governance directory.");
+        console.log(`  Expected: ${resolve(dir)}/*.json\n`);
+        return;
+    }
+    switch (format) {
+        case "json":
+            console.log(JSON.stringify(report, null, 2));
+            break;
+        case "html":
+            console.log(formatGovernanceHtml(report));
+            break;
+        default:
+            console.log(formatGovernanceText(report));
+    }
+}

package/dist/commands/group-findings.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Finding grouping — group related findings by category, file, or rule
+ * for better review UX and digest-style reporting.
+ */
+import type { Finding } from "../types.js";
+export type GroupByKey = "category" | "severity" | "file" | "rule" | "judge";
+export interface FindingGroup {
+    key: string;
+    label: string;
+    findings: Finding[];
+    count: number;
+    criticalCount: number;
+    highCount: number;
+}
+export interface GroupedReport {
+    groupBy: GroupByKey;
+    groups: FindingGroup[];
+    totalFindings: number;
+    totalGroups: number;
+}
+export declare function groupFindings(findings: Finding[], groupBy: GroupByKey): GroupedReport;
+export declare function runGroupFindings(argv: string[]): void;

package/dist/commands/group-findings.js

@@ -0,0 +1,154 @@
+/**
+ * Finding grouping — group related findings by category, file, or rule
+ * for better review UX and digest-style reporting.
+ */
+// ─── Category Classification ────────────────────────────────────────────────
+const RULE_CATEGORIES = {
+    // Security
+    "SEC-": "Security",
+    "AUTH-": "Authentication",
+    "CRYPTO-": "Cryptography",
+    "INJECT-": "Injection",
+    "XSS-": "Cross-Site Scripting",
+    "SSRF-": "Server-Side Request Forgery",
+    "IDOR-": "Broken Access Control",
+    // Quality
+    "PERF-": "Performance",
+    "ERR-": "Error Handling",
+    "LOG-": "Logging",
+    "TEST-": "Testing",
+    "DOC-": "Documentation",
+    "MAINT-": "Maintainability",
+    "STRUCT-": "Code Structure",
+    // Reliability
+    "CONCUR-": "Concurrency",
+    "RACE-": "Race Conditions",
+    "SCALE-": "Scalability",
+    "CACHE-": "Caching",
+    "RATE-": "Rate Limiting",
+    // Compliance
+    "COMPLY-": "Compliance",
+    "DATA-": "Data Protection",
+    "PII-": "Privacy",
+    // AI
+    "AI-": "AI Safety",
+    "HALLUC-": "Hallucination",
+    "FW-": "Framework Safety",
+    // Infrastructure
+    "IAC-": "Infrastructure as Code",
+    "CICD-": "CI/CD",
+    "CLOUD-": "Cloud Readiness",
+    "DB-": "Database",
+    // Accessibility / UX
+    "A11Y-": "Accessibility",
+    "I18N-": "Internationalization",
+    "UX-": "User Experience",
+};
+function classifyRule(ruleId) {
+    for (const [prefix, category] of Object.entries(RULE_CATEGORIES)) {
+        if (ruleId.toUpperCase().startsWith(prefix))
+            return category;
+    }
+    return "Other";
+}
+// ─── Grouping Logic ─────────────────────────────────────────────────────────
+function getGroupKey(finding, groupBy) {
+    switch (groupBy) {
+        case "category":
+            return classifyRule(finding.ruleId);
+        case "severity":
+            return finding.severity;
+        case "file":
+            return "(grouped)";
+        case "rule":
+            return finding.ruleId;
+        case "judge":
+            return finding.judgeId || "(unknown)";
+    }
+}
+export function groupFindings(findings, groupBy) {
+    const groups = new Map();
+    for (const f of findings) {
+        const key = getGroupKey(f, groupBy);
+        const arr = groups.get(key) || [];
+        arr.push(f);
+        groups.set(key, arr);
+    }
+    const sortedGroups = [...groups.entries()]
+        .map(([key, items]) => ({
+        key,
+        label: key,
+        findings: items,
+        count: items.length,
+        criticalCount: items.filter((f) => f.severity === "critical").length,
+        highCount: items.filter((f) => f.severity === "high").length,
+    }))
+        .sort((a, b) => b.criticalCount - a.criticalCount || b.highCount - a.highCount || b.count - a.count);
+    return {
+        groupBy,
+        groups: sortedGroups,
+        totalFindings: findings.length,
+        totalGroups: sortedGroups.length,
+    };
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runGroupFindings(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges group — Group findings by category, severity, file, rule, or judge
+
+Usage:
+  judges group --input results.json                 Group by category (default)
+  judges group --input results.json --by severity   Group by severity
+  judges group --input results.json --by file       Group by file
+
+Options:
+  --input <path>      Path to JSON results file (required)
+  --by <key>          Group by: category, severity, file, rule, judge (default: category)
+  --format json       JSON output
+  --help, -h          Show this help
+`);
+        return;
+    }
+    const { readFileSync, existsSync } = require("fs");
+    const inputPath = argv.find((_a, i) => argv[i - 1] === "--input");
+    if (!inputPath || !existsSync(inputPath)) {
+        console.error("Error: --input <path> required (JSON results file)");
+        process.exit(1);
+    }
+    const byArg = argv.find((_a, i) => argv[i - 1] === "--by") || "category";
+    const validKeys = new Set(["category", "severity", "file", "rule", "judge"]);
+    if (!validKeys.has(byArg)) {
+        console.error(`Error: --by must be one of: ${[...validKeys].join(", ")}`);
+        process.exit(1);
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    const data = JSON.parse(readFileSync(inputPath, "utf-8"));
+    const findings = data.evaluations
+        ? data.evaluations.flatMap((e) => e.findings || [])
+        : data.findings || data;
+    const report = groupFindings(findings, byArg);
+    if (format === "json") {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(`\n  Findings Grouped by ${report.groupBy}\n`);
+    console.log(`  Total: ${report.totalFindings} findings in ${report.totalGroups} groups\n`);
+    for (const g of report.groups) {
+        const badges = [];
+        if (g.criticalCount > 0)
+            badges.push(`🔴 ${g.criticalCount} critical`);
+        if (g.highCount > 0)
+            badges.push(`🟠 ${g.highCount} high`);
+        const badge = badges.length > 0 ? ` (${badges.join(", ")})` : "";
+        console.log(`  📁 ${g.label} — ${g.count} findings${badge}`);
+        for (const f of g.findings.slice(0, 5)) {
+            const loc = f.lineNumbers?.length ? `:${f.lineNumbers[0]}` : "";
+            console.log(`     ${f.severity.padEnd(8)} ${f.ruleId}: ${f.title.slice(0, 80)}${loc}`);
+        }
+        if (g.findings.length > 5) {
+            console.log(`     ... and ${g.findings.length - 5} more`);
+        }
+        console.log("");
+    }
+}

package/dist/commands/guided-tour.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Guided tour — interactive onboarding tutorial for new Judges users.
+ * Step-by-step walkthrough: first evaluation, understanding output,
+ * suppression/baseline workflows, building .judgesrc by example.
+ *
+ * All data local.
+ */
+export declare function runGuidedTour(argv: string[]): void;

package/dist/commands/guided-tour.js

@@ -0,0 +1,287 @@
+/**
+ * Guided tour — interactive onboarding tutorial for new Judges users.
+ * Step-by-step walkthrough: first evaluation, understanding output,
+ * suppression/baseline workflows, building .judgesrc by example.
+ *
+ * All data local.
+ */
+import { existsSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+// ─── Tour content ───────────────────────────────────────────────────────────
+const TOUR_TRACKS = [
+    {
+        id: "quickstart",
+        name: "Quick Start",
+        description: "Get your first code review in under 5 minutes",
+        steps: [
+            {
+                id: "install",
+                title: "Step 1: Installation",
+                description: "Install Judges globally or as a dev dependency.",
+                command: "npm install -g @kevinrabun/judges-cli",
+                example: "# Or as a dev dependency:\nnpm install --save-dev @kevinrabun/judges-cli",
+                tips: [
+                    "Use --save-dev for project-specific installations",
+                    "Global install lets you run 'judges' from anywhere",
+                ],
+            },
+            {
+                id: "first-review",
+                title: "Step 2: Run Your First Review",
+                description: "Point Judges at any source file to get an instant security review.",
+                command: "judges review src/app.ts",
+                example: "# Review an entire directory:\njudges review src/\n\n# Review with a specific preset:\njudges review src/ --preset strict",
+                tips: [
+                    "Start with a single file to learn the output format",
+                    "Use --preset lenient for fewer false positives initially",
+                ],
+            },
+            {
+                id: "understand-output",
+                title: "Step 3: Understanding the Output",
+                description: "Judges outputs findings with severity, confidence, and actionable recommendations.",
+                example: `Finding output explained:
+─────────────────────────
+  [HIGH] sql-injection-risk
+    Title: Potential SQL injection in query builder
+    Line: 42
+    Confidence: 0.92 (high tier)
+    Recommendation: Use parameterized queries instead of string concatenation
+
+  Fields:
+    severity   — critical / high / medium / low
+    confidence — 0.0–1.0 score (how certain the judge is)
+    ruleId     — unique identifier for the finding type
+    title      — human-readable description
+    recommendation — how to fix the issue`,
+                tips: [
+                    "High confidence + high severity = fix immediately",
+                    "Low confidence findings may be false positives — review carefully",
+                ],
+            },
+            {
+                id: "suppress",
+                title: "Step 4: Suppressing False Positives",
+                description: "Mark findings as acknowledged or false positives so they don't appear again.",
+                command: "judges baseline create --output .judges-baseline.json",
+                example: `# Create a baseline from current findings:
+judges baseline create --output .judges-baseline.json
+
+# Run review with baseline (only new findings shown):
+judges review src/ --baseline .judges-baseline.json
+
+# Suppress a specific rule:
+# Add to .judgesrc: { "disabledRules": ["rule-id-here"] }`,
+                tips: [
+                    "Baselines capture current state — only new issues surface",
+                    "Commit .judges-baseline.json to share with your team",
+                ],
+            },
+            {
+                id: "configure",
+                title: "Step 5: Create Your .judgesrc",
+                description: "Customize Judges behavior with a configuration file.",
+                example: `// .judgesrc (JSON format)
+{
+  "preset": "recommended",
+  "minSeverity": "medium",
+  "disabledRules": [],
+  "disabledJudges": [],
+  "ruleOverrides": {
+    "some-noisy-rule": { "severity": "low" }
+  }
+}`,
+                tips: [
+                    "Start with 'recommended' preset",
+                    "Use minSeverity to filter out low-priority findings",
+                    "Override specific rules without disabling them entirely",
+                ],
+            },
+        ],
+    },
+    {
+        id: "ci-integration",
+        name: "CI/CD Integration",
+        description: "Add Judges to your continuous integration pipeline",
+        steps: [
+            {
+                id: "github-actions",
+                title: "Step 1: GitHub Actions Setup",
+                description: "Add Judges as a review step in your GitHub Actions workflow.",
+                example: `# .github/workflows/judges.yml
+name: Judges Code Review
+on: [pull_request]
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install -g @kevinrabun/judges-cli
+      - run: judges review src/ --format sarif --output results.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif`,
+            },
+            {
+                id: "quality-gate",
+                title: "Step 2: Quality Gate",
+                description: "Block PRs that introduce critical or high-severity findings.",
+                command: "judges gate --max-critical 0 --max-high 3",
+                example: "# In CI:\njudges review src/ --format json | judges gate --max-critical 0 --max-high 3\n# Exit code 1 = gate failed, PR should not merge",
+                tips: ["Start lenient (allow some highs) and tighten over time", "Always block on critical findings"],
+            },
+            {
+                id: "diff-review",
+                title: "Step 3: Diff-Only Review",
+                description: "Review only changed files in a PR for faster feedback.",
+                command: "judges diff-review --base main",
+                tips: ["Diff review is much faster than full review", "Combine with baseline for minimal noise"],
+            },
+        ],
+    },
+    {
+        id: "team-adoption",
+        name: "Team Adoption",
+        description: "Roll out Judges across your development team",
+        steps: [
+            {
+                id: "shared-config",
+                title: "Step 1: Shared Configuration",
+                description: "Create a team-wide .judgesrc and commit it to your repository.",
+                example: `// Recommended team .judgesrc
+{
+  "preset": "recommended",
+  "minSeverity": "medium",
+  "disabledRules": []
+}`,
+                tips: ["Start with recommended preset for team consensus", "Document why rules are disabled"],
+            },
+            {
+                id: "baseline-workflow",
+                title: "Step 2: Baseline Workflow",
+                description: "Establish a baseline then only review new findings going forward.",
+                command: "judges baseline create --output .judges-baseline.json",
+                tips: ["Create baseline on main branch", "Each team member starts from the shared baseline"],
+            },
+            {
+                id: "metrics",
+                title: "Step 3: Track Metrics",
+                description: "Monitor your team's security posture over time.",
+                command: "judges trend --days 30",
+                tips: ["Track findings-per-PR to measure improvement", "Celebrate declining finding counts"],
+            },
+        ],
+    },
+];
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runGuidedTour(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges guided-tour — Interactive onboarding tutorials
+
+Usage:
+  judges guided-tour                      List available tour tracks
+  judges guided-tour quickstart           Start the quick start tour
+  judges guided-tour ci-integration       CI/CD integration guide
+  judges guided-tour team-adoption        Team rollout guide
+  judges guided-tour --init               Generate starter .judgesrc
+  judges guided-tour --all                Show all tour content
+
+Options:
+  --init          Generate a starter .judgesrc file
+  --all           Show all tracks at once
+  --format json   JSON output
+  --step <n>      Jump to specific step number
+  --help, -h      Show this help
+
+Available tracks: ${TOUR_TRACKS.map((t) => t.id).join(", ")}
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    // Generate starter config
+    if (argv.includes("--init")) {
+        const rcPath = join(".", ".judgesrc");
+        if (existsSync(rcPath)) {
+            console.log("  .judgesrc already exists — skipping");
+            return;
+        }
+        const config = {
+            preset: "recommended",
+            minSeverity: "medium",
+            disabledRules: [],
+            disabledJudges: [],
+            ruleOverrides: {},
+        };
+        writeFileSync(rcPath, JSON.stringify(config, null, 2) + "\n");
+        console.log("  ✅ Created .judgesrc with recommended defaults");
+        return;
+    }
+    const trackId = argv.find((a) => !a.startsWith("--") && !argv[argv.indexOf(a) - 1]?.startsWith("--"));
+    const stepNum = argv.find((_a, i) => argv[i - 1] === "--step");
+    const showAll = argv.includes("--all");
+    if (format === "json") {
+        const data = trackId
+            ? TOUR_TRACKS.find((t) => t.id === trackId) || TOUR_TRACKS
+            : showAll
+                ? TOUR_TRACKS
+                : TOUR_TRACKS.map(({ steps: _s, ...rest }) => rest);
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    // List tracks
+    if (!trackId && !showAll) {
+        console.log(`\n  📚 Judges Guided Tour\n  ──────────────────────────`);
+        for (const track of TOUR_TRACKS) {
+            console.log(`\n    ${track.name} (${track.id})`);
+            console.log(`      ${track.description}`);
+            console.log(`      Steps: ${track.steps.length}`);
+            console.log(`      Run: judges guided-tour ${track.id}`);
+        }
+        console.log(`\n    💡 Quick setup: judges guided-tour --init\n`);
+        return;
+    }
+    // Show track(s)
+    const tracks = showAll ? TOUR_TRACKS : [TOUR_TRACKS.find((t) => t.id === trackId)];
+    if (!tracks[0]) {
+        console.error(`  Unknown track: ${trackId}\n  Available: ${TOUR_TRACKS.map((t) => t.id).join(", ")}`);
+        return;
+    }
+    for (const track of tracks) {
+        console.log(`\n  ═══════════════════════════════════════`);
+        console.log(`  📚 ${track.name}`);
+        console.log(`  ${track.description}`);
+        console.log(`  ═══════════════════════════════════════`);
+        const steps = stepNum ? [track.steps[parseInt(stepNum) - 1]].filter(Boolean) : track.steps;
+        for (let i = 0; i < steps.length; i++) {
+            const step = steps[i];
+            const num = stepNum ? parseInt(stepNum) : i + 1;
+            console.log(`\n  ─── ${num}/${track.steps.length} ──────────────────────────`);
+            console.log(`  ${step.title}`);
+            console.log(`  ${step.description}`);
+            if (step.command) {
+                console.log(`\n    $ ${step.command}`);
+            }
+            if (step.example) {
+                console.log(`\n${step.example
+                    .split("\n")
+                    .map((l) => "    " + l)
+                    .join("\n")}`);
+            }
+            if (step.tips && step.tips.length > 0) {
+                console.log("");
+                for (const tip of step.tips) {
+                    console.log(`    💡 ${tip}`);
+                }
+            }
+        }
+        console.log("");
+    }
+    // Generate .judgesrc directory for tour progress
+    const tourDir = join(".", ".judges-tour");
+    if (!existsSync(tourDir))
+        mkdirSync(tourDir, { recursive: true });
+}