@wipcomputer/wip-ai-devops-toolbox 1.9.20

package/tools/wip-license-hook/src/cli/index.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * wip-license-hook CLI
+ *
+ * Commands:
+ *   init        Initialize ledger for current project
+ *   scan        Scan all deps, update ledger
+ *   check <dep> Check specific dependency
+ *   gate        Pre-merge license gate (for hooks)
+ *   report      Print ledger report
+ *   dashboard   Generate static dashboard HTML
+ *   alert       Print current alerts
+ *   install     Install git hooks in current repo
+ */
+
+import { resolve } from "node:path";
+import { existsSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
+import {
+  readLedger, writeLedger, createEmptyLedger, findEntry,
+  scanAndUpdate, gateCheck,
+  formatScanReport, formatGateOutput, formatLedgerReport,
+  writeDashboard, generateBadgeUrl,
+} from "../core/index.js";
+
+const args = process.argv.slice(2);
+const command = args[0];
+const flags = new Set(args.filter((a) => a.startsWith("--")));
+const positional = args.filter((a) => !a.startsWith("--")).slice(1);
+
+const repoRoot = resolve(process.cwd());
+const offline = flags.has("--offline");
+const verbose = flags.has("--verbose");
+
+function help(): void {
+  console.log(`
+wip-license-hook — License rug-pull detection
+
+Usage: wip-license-hook <command> [options]
+
+Commands:
+  init              Initialize LICENSE-LEDGER.json
+  scan              Scan all dependencies, update ledger
+  check <name>      Check a specific dependency
+  gate              Pre-merge license gate (exit 1 if changed)
+  report            Print ledger status
+  dashboard         Generate static HTML dashboard
+  alert             Show current alerts
+  install           Install git hooks in .git/hooks/
+  badge             Print shields.io badge URL
+
+Options:
+  --offline         Skip network calls (use cached data only)
+  --verbose         Verbose output
+  --help            Show this help
+`);
+}
+
+async function main(): Promise<void> {
+  if (!command || command === "--help" || flags.has("--help")) {
+    help();
+    return;
+  }
+
+  switch (command) {
+    case "init": {
+      const ledgerPath = resolve(repoRoot, "LICENSE-LEDGER.json");
+      if (existsSync(ledgerPath)) {
+        console.log("⚠️  LICENSE-LEDGER.json already exists. Use 'scan' to update.");
+        return;
+      }
+      writeLedger(repoRoot, createEmptyLedger());
+      mkdirSync(resolve(repoRoot, "ledger/snapshots"), { recursive: true });
+      console.log("✅ Initialized LICENSE-LEDGER.json and ledger/snapshots/");
+      console.log("   Run 'wip-license-hook scan' to populate.");
+      break;
+    }
+
+    case "scan": {
+      console.log(offline ? "📡 Scanning (offline mode)..." : "📡 Scanning dependencies...");
+      const results = scanAndUpdate({ repoRoot, offline, verbose });
+      console.log(formatScanReport(results));
+      break;
+    }
+
+    case "check": {
+      const name = positional[0];
+      if (!name) {
+        console.error("Usage: wip-license-hook check <dependency-name>");
+        process.exit(1);
+      }
+      const ledger = readLedger(repoRoot);
+      const entry = findEntry(ledger, name);
+      if (!entry) {
+        console.log(`❓ ${name} not found in ledger. Run 'scan' first.`);
+        process.exit(1);
+      }
+      console.log(`\n  ${entry.status === "clean" ? "✅" : "🚫"} ${entry.name}`);
+      console.log(`     Type:    ${entry.type}`);
+      console.log(`     Source:  ${entry.source}`);
+      console.log(`     Adopted: ${entry.license_at_adoption} on ${entry.adopted_date}`);
+      console.log(`     Current: ${entry.license_current} (checked ${entry.last_checked})`);
+      console.log(`     Status:  ${entry.status}\n`);
+      break;
+    }
+
+    case "gate": {
+      if (offline) {
+        console.log("⚠️  Offline mode — skipping license gate (cannot verify upstream).");
+        console.log("    Your push will proceed, but licenses were NOT checked.");
+        process.exit(0);
+      }
+      const { safe, alerts } = gateCheck(repoRoot, offline);
+      console.log(formatGateOutput(safe, alerts));
+      if (!safe) process.exit(1);
+      break;
+    }
+
+    case "report": {
+      const ledger = readLedger(repoRoot);
+      console.log(formatLedgerReport(ledger));
+      break;
+    }
+
+    case "dashboard": {
+      const outPath = writeDashboard(repoRoot);
+      console.log(`✅ Dashboard written to ${outPath}`);
+      break;
+    }
+
+    case "alert": {
+      const ledger = readLedger(repoRoot);
+      if (ledger.alerts.length === 0) {
+        console.log("✅ No active alerts.");
+      } else {
+        console.log(`\n⚠️  ${ledger.alerts.length} alert(s):\n`);
+        for (const a of ledger.alerts) {
+          console.log(`  ${a.message}`);
+          console.log(`  Detected: ${a.detected}\n`);
+        }
+      }
+      break;
+    }
+
+    case "install": {
+      const hooksDir = resolve(repoRoot, ".git/hooks");
+      if (!existsSync(resolve(repoRoot, ".git"))) {
+        console.error("❌ Not a git repository. Run from a git repo root.");
+        process.exit(1);
+      }
+      mkdirSync(hooksDir, { recursive: true });
+
+      // Find hooks relative to the package
+      const pkgRoot = resolve(new URL(".", import.meta.url).pathname, "../../..");
+      const prePullSrc = resolve(pkgRoot, "hooks/pre-pull.sh");
+      const preCommitSrc = resolve(pkgRoot, "hooks/pre-push.sh");
+
+      for (const [src, dest] of [
+        [prePullSrc, resolve(hooksDir, "pre-merge-commit")],
+        [preCommitSrc, resolve(hooksDir, "pre-push")],
+      ]) {
+        if (existsSync(src)) {
+          copyFileSync(src, dest);
+          const { chmodSync } = await import("node:fs");
+          chmodSync(dest, 0o755);
+          console.log(`✅ Installed ${dest}`);
+        } else {
+          console.log(`⚠️  Hook source not found: ${src}`);
+        }
+      }
+      break;
+    }
+
+    case "badge": {
+      const ledger = readLedger(repoRoot);
+      console.log(generateBadgeUrl(ledger));
+      break;
+    }
+
+    default:
+      console.error(`Unknown command: ${command}`);
+      help();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err.message);
+  process.exit(1);
+});

package/tools/wip-license-hook/src/core/detector.ts

@@ -0,0 +1,130 @@
+/**
+ * License text fingerprinting — identifies license type from file content.
+ */
+
+export type LicenseId =
+  | "MIT"
+  | "Apache-2.0"
+  | "BSD-2-Clause"
+  | "BSD-3-Clause"
+  | "GPL-2.0"
+  | "GPL-3.0"
+  | "LGPL-2.1"
+  | "LGPL-3.0"
+  | "MPL-2.0"
+  | "ISC"
+  | "BSL-1.1"
+  | "SSPL-1.0"
+  | "Unlicense"
+  | "AGPL-3.0"
+  | "UNKNOWN";
+
+interface Fingerprint {
+  id: LicenseId;
+  markers: string[];       // All must match (case-insensitive)
+  antiMarkers?: string[];  // None must match
+}
+
+const FINGERPRINTS: Fingerprint[] = [
+  {
+    id: "MIT",
+    markers: ["permission is hereby granted, free of charge", "the software is provided \"as is\""],
+    antiMarkers: ["apache", "gnu general public"],
+  },
+  {
+    id: "Apache-2.0",
+    markers: ["apache license", "version 2.0"],
+  },
+  {
+    id: "GPL-3.0",
+    markers: ["gnu general public license", "version 3"],
+    antiMarkers: ["lesser general public"],
+  },
+  {
+    id: "GPL-2.0",
+    markers: ["gnu general public license", "version 2"],
+    antiMarkers: ["lesser general public", "version 3"],
+  },
+  {
+    id: "LGPL-3.0",
+    markers: ["gnu lesser general public license", "version 3"],
+  },
+  {
+    id: "LGPL-2.1",
+    markers: ["gnu lesser general public license", "version 2.1"],
+  },
+  {
+    id: "AGPL-3.0",
+    markers: ["gnu affero general public license", "version 3"],
+  },
+  {
+    id: "BSD-3-Clause",
+    markers: ["redistribution and use in source and binary forms", "neither the name"],
+  },
+  {
+    id: "BSD-2-Clause",
+    markers: ["redistribution and use in source and binary forms"],
+    antiMarkers: ["neither the name"],
+  },
+  {
+    id: "MPL-2.0",
+    markers: ["mozilla public license", "version 2.0"],
+  },
+  {
+    id: "ISC",
+    markers: ["isc license", "permission to use, copy, modify"],
+  },
+  {
+    id: "BSL-1.1",
+    markers: ["business source license", "1.1"],
+  },
+  {
+    id: "SSPL-1.0",
+    markers: ["server side public license"],
+  },
+  {
+    id: "Unlicense",
+    markers: ["this is free and unencumbered software released into the public domain"],
+  },
+];
+
+/**
+ * Detect license type from raw license file text.
+ */
+export function detectLicenseFromText(text: string): LicenseId {
+  const lower = text.toLowerCase();
+
+  for (const fp of FINGERPRINTS) {
+    const allMatch = fp.markers.every((m) => lower.includes(m));
+    const anyAnti = fp.antiMarkers?.some((m) => lower.includes(m)) ?? false;
+    if (allMatch && !anyAnti) return fp.id;
+  }
+
+  return "UNKNOWN";
+}
+
+/**
+ * Normalize a license SPDX identifier from package metadata.
+ */
+export function normalizeSpdx(raw: string): LicenseId {
+  const map: Record<string, LicenseId> = {
+    mit: "MIT",
+    "apache-2.0": "Apache-2.0",
+    apache2: "Apache-2.0",
+    "bsd-2-clause": "BSD-2-Clause",
+    "bsd-3-clause": "BSD-3-Clause",
+    "gpl-2.0": "GPL-2.0",
+    "gpl-3.0": "GPL-3.0",
+    "gpl-3.0-only": "GPL-3.0",
+    "lgpl-2.1": "LGPL-2.1",
+    "lgpl-3.0": "LGPL-3.0",
+    "mpl-2.0": "MPL-2.0",
+    isc: "ISC",
+    "bsl-1.1": "BSL-1.1",
+    "sspl-1.0": "SSPL-1.0",
+    unlicense: "Unlicense",
+    "agpl-3.0": "AGPL-3.0",
+    "agpl-3.0-only": "AGPL-3.0",
+  };
+  return map[raw.toLowerCase().trim()] ?? "UNKNOWN";
+}

package/tools/wip-license-hook/src/core/index.ts

@@ -0,0 +1,4 @@
+export { detectLicenseFromText, normalizeSpdx, type LicenseId } from "./detector.js";
+export { readLedger, writeLedger, createEmptyLedger, findEntry, upsertEntry, archiveSnapshot, hasLicenseChanged, addAlert, type Ledger, type LedgerEntry, type Alert, type DependencyType, type DependencyStatus } from "./ledger.js";
+export { scanAll, scanAndUpdate, gateCheck, findLicenseFile, readLicenseFromDir, type ScanResult } from "./scanner.js";
+export { formatScanReport, formatGateOutput, formatLedgerReport, generateDashboardHtml, generateBadgeUrl, writeDashboard } from "./reporter.js";

package/tools/wip-license-hook/src/core/ledger.ts

@@ -0,0 +1,116 @@
+/**
+ * License ledger — read/write/compare LICENSE-LEDGER.json + snapshot archiving.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import type { LicenseId } from "./detector.js";
+
+export type DependencyStatus = "clean" | "changed" | "removed" | "unknown";
+export type DependencyType = "fork" | "npm" | "pip" | "cargo" | "go";
+
+export interface LedgerEntry {
+  name: string;
+  source: string;
+  type: DependencyType;
+  license_at_adoption: LicenseId;
+  license_current: LicenseId;
+  adopted_date: string;       // ISO date
+  last_checked: string;       // ISO date
+  commit_at_adoption?: string;
+  status: DependencyStatus;
+}
+
+export interface Alert {
+  dependency: string;
+  from: LicenseId;
+  to: LicenseId;
+  detected: string;  // ISO datetime
+  message: string;
+}
+
+export interface Ledger {
+  version: 1;
+  dependencies: LedgerEntry[];
+  last_full_scan: string | null;
+  alerts: Alert[];
+}
+
+const LEDGER_FILE = "LICENSE-LEDGER.json";
+const SNAPSHOT_DIR = "ledger/snapshots";
+
+export function ledgerPath(repoRoot: string): string {
+  return join(repoRoot, LEDGER_FILE);
+}
+
+export function createEmptyLedger(): Ledger {
+  return {
+    version: 1,
+    dependencies: [],
+    last_full_scan: null,
+    alerts: [],
+  };
+}
+
+export function readLedger(repoRoot: string): Ledger {
+  const p = ledgerPath(repoRoot);
+  if (!existsSync(p)) return createEmptyLedger();
+  return JSON.parse(readFileSync(p, "utf-8"));
+}
+
+export function writeLedger(repoRoot: string, ledger: Ledger): void {
+  const p = ledgerPath(repoRoot);
+  writeFileSync(p, JSON.stringify(ledger, null, 2) + "\n", "utf-8");
+}
+
+export function findEntry(ledger: Ledger, name: string): LedgerEntry | undefined {
+  return ledger.dependencies.find((d) => d.name === name);
+}
+
+export function upsertEntry(ledger: Ledger, entry: LedgerEntry): void {
+  const idx = ledger.dependencies.findIndex((d) => d.name === entry.name);
+  if (idx >= 0) {
+    ledger.dependencies[idx] = entry;
+  } else {
+    ledger.dependencies.push(entry);
+  }
+}
+
+/**
+ * Archive a LICENSE file snapshot for a dependency.
+ */
+export function archiveSnapshot(
+  repoRoot: string,
+  depName: string,
+  licenseContent: string,
+  date?: string
+): string {
+  const d = date ?? new Date().toISOString().slice(0, 10);
+  const dir = join(repoRoot, SNAPSHOT_DIR, depName);
+  mkdirSync(dir, { recursive: true });
+  const filename = `LICENSE-${d}.txt`;
+  const p = join(dir, filename);
+  writeFileSync(p, licenseContent, "utf-8");
+  return p;
+}
+
+/**
+ * Compare an entry's current license against its adoption license.
+ * Returns true if changed.
+ */
+export function hasLicenseChanged(entry: LedgerEntry): boolean {
+  return entry.license_at_adoption !== entry.license_current;
+}
+
+/**
+ * Add an alert to the ledger.
+ */
+export function addAlert(ledger: Ledger, dep: string, from: LicenseId, to: LicenseId): void {
+  ledger.alerts.push({
+    dependency: dep,
+    from,
+    to,
+    detected: new Date().toISOString(),
+    message: `⚠️  License changed: ${dep} went from ${from} → ${to}`,
+  });
+}

package/tools/wip-license-hook/src/core/reporter.ts

@@ -0,0 +1,255 @@
+/**
+ * Reporter — generate reports, alerts, and static dashboard HTML.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { readLedger, type Ledger, type LedgerEntry, type Alert } from "./ledger.js";
+import type { ScanResult } from "./scanner.js";
+
+// ─── Console reports ───
+
+export function formatScanReport(results: ScanResult[]): string {
+  const lines: string[] = [
+    "",
+    "╔══════════════════════════════════════════════════╗",
+    "║         wip-license-hook — Scan Report           ║",
+    "╚══════════════════════════════════════════════════╝",
+    "",
+  ];
+
+  const changed = results.filter((r) => r.wasChanged);
+  const newDeps = results.filter((r) => r.isNew);
+  const clean = results.filter((r) => !r.wasChanged && !r.isNew);
+
+  if (changed.length > 0) {
+    lines.push("🚨 LICENSE CHANGES DETECTED:");
+    lines.push("─".repeat(50));
+    for (const r of changed) {
+      lines.push(`  🚫 ${r.name} (${r.type})`);
+      lines.push(`     License changed → now: ${r.detectedLicense}`);
+      lines.push(`     Source: ${r.source}`);
+    }
+    lines.push("");
+  }
+
+  if (newDeps.length > 0) {
+    lines.push(`📦 New dependencies found: ${newDeps.length}`);
+    for (const r of newDeps) {
+      lines.push(`  ➕ ${r.name} (${r.type}) — ${r.detectedLicense}`);
+    }
+    lines.push("");
+  }
+
+  if (clean.length > 0) {
+    lines.push(`✅ Clean dependencies: ${clean.length}`);
+    for (const r of clean) {
+      lines.push(`  ✓ ${r.name} — ${r.detectedLicense}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(`Total scanned: ${results.length}`);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export function formatGateOutput(safe: boolean, alerts: string[]): string {
+  const lines: string[] = [];
+
+  if (safe) {
+    lines.push("");
+    lines.push("╔══════════════════════════════════════════════════╗");
+    lines.push("║  ✅  LICENSE CHECK PASSED — All licenses clean   ║");
+    lines.push("╚══════════════════════════════════════════════════╝");
+    lines.push("");
+  } else {
+    lines.push("");
+    lines.push("╔══════════════════════════════════════════════════╗");
+    lines.push("║  🚫  LICENSE CHECK FAILED — Changes detected!    ║");
+    lines.push("╚══════════════════════════════════════════════════╝");
+    lines.push("");
+    for (const alert of alerts) {
+      lines.push(`  ${alert}`);
+    }
+    lines.push("");
+    lines.push("  Action required: Review license changes before proceeding.");
+    lines.push("  Run: wip-license-hook scan --verbose for details.");
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+export function formatLedgerReport(ledger: Ledger): string {
+  const lines: string[] = [
+    "",
+    "╔══════════════════════════════════════════════════╗",
+    "║         wip-license-hook — Ledger Status         ║",
+    "╚══════════════════════════════════════════════════╝",
+    "",
+    `Last full scan: ${ledger.last_full_scan ?? "never"}`,
+    `Total dependencies: ${ledger.dependencies.length}`,
+    `Active alerts: ${ledger.alerts.length}`,
+    "",
+  ];
+
+  const statusIcon: Record<string, string> = {
+    clean: "✅",
+    changed: "🚫",
+    removed: "❓",
+    unknown: "❔",
+  };
+
+  for (const dep of ledger.dependencies) {
+    const icon = statusIcon[dep.status] ?? "❔";
+    lines.push(`  ${icon} ${dep.name} (${dep.type})`);
+    lines.push(`     Adopted: ${dep.license_at_adoption} on ${dep.adopted_date}`);
+    lines.push(`     Current: ${dep.license_current} (checked ${dep.last_checked})`);
+    lines.push(`     Source:  ${dep.source}`);
+  }
+
+  if (ledger.alerts.length > 0) {
+    lines.push("");
+    lines.push("⚠️  ALERTS:");
+    lines.push("─".repeat(50));
+    for (const a of ledger.alerts) {
+      lines.push(`  ${a.message}`);
+      lines.push(`  Detected: ${a.detected}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+// ─── Dashboard HTML generation ───
+
+export function generateDashboardHtml(ledger: Ledger): string {
+  const rows = ledger.dependencies
+    .map((d) => {
+      const statusClass = d.status === "clean" ? "clean" : d.status === "changed" ? "changed" : "unknown";
+      const statusEmoji = d.status === "clean" ? "✅" : d.status === "changed" ? "🚫" : "❔";
+      return `<tr class="${statusClass}">
+        <td>${statusEmoji} ${escHtml(d.name)}</td>
+        <td>${escHtml(d.type)}</td>
+        <td>${escHtml(d.license_at_adoption)}</td>
+        <td>${escHtml(d.license_current)}</td>
+        <td>${escHtml(d.adopted_date)}</td>
+        <td>${escHtml(d.last_checked)}</td>
+        <td>${escHtml(d.status)}</td>
+      </tr>`;
+    })
+    .join("\n");
+
+  const alertRows = ledger.alerts
+    .map(
+      (a) => `<tr>
+        <td>⚠️ ${escHtml(a.dependency)}</td>
+        <td>${escHtml(a.from)} → ${escHtml(a.to)}</td>
+        <td>${escHtml(a.detected)}</td>
+        <td>${escHtml(a.message)}</td>
+      </tr>`
+    )
+    .join("\n");
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>License Compliance Dashboard — wip-license-hook</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0d1117; color: #c9d1d9; padding: 2rem; }
+    h1 { color: #58a6ff; margin-bottom: 0.5rem; }
+    .subtitle { color: #8b949e; margin-bottom: 2rem; }
+    .stats { display: flex; gap: 2rem; margin-bottom: 2rem; }
+    .stat { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 1rem 1.5rem; }
+    .stat-value { font-size: 2rem; font-weight: bold; }
+    .stat-label { color: #8b949e; font-size: 0.875rem; }
+    .stat-clean .stat-value { color: #3fb950; }
+    .stat-changed .stat-value { color: #f85149; }
+    .stat-total .stat-value { color: #58a6ff; }
+    table { width: 100%; border-collapse: collapse; background: #161b22; border: 1px solid #30363d; border-radius: 8px; overflow: hidden; margin-bottom: 2rem; }
+    th { background: #21262d; text-align: left; padding: 0.75rem 1rem; color: #8b949e; font-weight: 600; border-bottom: 1px solid #30363d; }
+    td { padding: 0.75rem 1rem; border-bottom: 1px solid #30363d; }
+    tr.changed td { background: #f8514922; }
+    tr.clean td { }
+    .footer { color: #8b949e; font-size: 0.8rem; margin-top: 2rem; }
+    h2 { color: #58a6ff; margin: 1.5rem 0 1rem; }
+  </style>
+</head>
+<body>
+  <h1>🔒 License Compliance Dashboard</h1>
+  <p class="subtitle">Generated by wip-license-hook — ${new Date().toISOString()}</p>
+
+  <div class="stats">
+    <div class="stat stat-total">
+      <div class="stat-value">${ledger.dependencies.length}</div>
+      <div class="stat-label">Total Dependencies</div>
+    </div>
+    <div class="stat stat-clean">
+      <div class="stat-value">${ledger.dependencies.filter((d) => d.status === "clean").length}</div>
+      <div class="stat-label">Clean</div>
+    </div>
+    <div class="stat stat-changed">
+      <div class="stat-value">${ledger.dependencies.filter((d) => d.status === "changed").length}</div>
+      <div class="stat-label">Changed</div>
+    </div>
+  </div>
+
+  <h2>Dependencies</h2>
+  <table>
+    <thead>
+      <tr><th>Name</th><th>Type</th><th>License (Adopted)</th><th>License (Current)</th><th>Adopted</th><th>Last Checked</th><th>Status</th></tr>
+    </thead>
+    <tbody>${rows}</tbody>
+  </table>
+
+  ${
+    ledger.alerts.length > 0
+      ? `<h2>⚠️ Alerts</h2>
+  <table>
+    <thead><tr><th>Dependency</th><th>Change</th><th>Detected</th><th>Message</th></tr></thead>
+    <tbody>${alertRows}</tbody>
+  </table>`
+      : ""
+  }
+
+  <div class="footer">
+    <p>Last full scan: ${ledger.last_full_scan ?? "never"}</p>
+    <p>Powered by <a href="https://github.com/wipcomputer/wip-license-hook" style="color: #58a6ff;">wip-license-hook</a></p>
+  </div>
+</body>
+</html>`;
+}
+
+function escHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+// ─── Badge generation (shields.io style) ───
+
+export function generateBadgeUrl(ledger: Ledger): string {
+  const changed = ledger.dependencies.filter((d) => d.status === "changed").length;
+  const total = ledger.dependencies.length;
+  const color = changed === 0 ? "brightgreen" : "red";
+  const label = "license%20compliance";
+  const message = changed === 0 ? `${total}%20clean` : `${changed}%20changed`;
+  return `https://img.shields.io/badge/${label}-${message}-${color}`;
+}
+
+/**
+ * Write the dashboard HTML to disk.
+ */
+export function writeDashboard(repoRoot: string, ledger?: Ledger): string {
+  const l = ledger ?? readLedger(repoRoot);
+  const html = generateDashboardHtml(l);
+  const dir = join(repoRoot, "dashboard");
+  mkdirSync(dir, { recursive: true });
+  const outPath = join(dir, "index.html");
+  writeFileSync(outPath, html, "utf-8");
+  return outPath;
+}