edsger 0.81.1 → 0.83.0

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 import { resolve as resolve2 } from "path";
 import { Command, Option } from "commander";
-import pc7 from "picocolors";
+import pc10 from "picocolors";
 
 // src/commands/benchmark.ts
-import { mkdirSync, writeFileSync } from "fs";
+import { appendFileSync, mkdirSync, writeFileSync } from "fs";
 import { basename, join as join3 } from "path";
 import pc3 from "picocolors";
 
@@ -127,7 +127,8 @@ function resolveStandard(kind, opts, config, configDir, forcedLanguages) {
   const roots = [
     { path: bundled, label: opts.assetsPath ? `assets:${opts.assetsPath}` : "bundled" }
   ];
-  const overrideSpec = (kind === "benchmark" ? config.benchmark?.standards : config.review?.standards) ?? config.standards;
+  const perKind = kind === "benchmark" ? config.benchmark?.standards : kind === "diagrams" ? config.diagrams?.standards : config.review?.standards;
+  const overrideSpec = perKind ?? config.standards;
   if (overrideSpec && !opts.assetsPath) {
     roots.push({ path: resolveRootPath(overrideSpec, configDir), label: `config:${overrideSpec}` });
   }
@@ -175,11 +176,38 @@ function mergeLayers(kind, layers) {
       {}
     );
   }
+  if (kind === "diagrams") {
+    return layers.reduce(
+      (acc, layer) => mergeDiagrams(acc, layer),
+      {}
+    );
+  }
   return layers.reduce(
     (acc, layer) => mergeReview(acc, layer),
     {}
   );
 }
+function mergeDiagrams(base, overlay) {
+  const groups = mergeById(base.groups ?? [], overlay.groups ?? [], (b, o) => ({
+    ...b,
+    ...o,
+    // Diagrams with the same id are overridden; new ids are appended.
+    diagrams: mergeById(b.diagrams ?? [], o.diagrams ?? [], (bd, od) => ({
+      ...bd,
+      ...od
+    }))
+  }));
+  return {
+    ...base,
+    ...overlay,
+    // Preserve the base layer's identity rather than the last overlay's.
+    id: base.id ?? overlay.id,
+    name: base.name ?? overlay.name,
+    version: base.version ?? overlay.version,
+    kind: "diagrams",
+    groups
+  };
+}
 function mergeBenchmark(base, overlay) {
   const categories = mergeById(
     base.categories ?? [],
@@ -490,6 +518,30 @@ function summarizeTool(name = "tool", input = {}) {
   }
 }
 
+// src/core/git.ts
+import { execFileSync as execFileSync2 } from "child_process";
+function tryGit(args, cwd) {
+  try {
+    return execFileSync2("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function gitInfo(cwd) {
+  const commit = tryGit(["rev-parse", "--short", "HEAD"], cwd);
+  const branch = tryGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+  const status = tryGit(["status", "--porcelain"], cwd);
+  return {
+    commit,
+    branch: branch && branch !== "HEAD" ? branch : null,
+    dirty: Boolean(status && status.length > 0)
+  };
+}
+
 // src/core/report.ts
 function scoreBenchmark(standard, result) {
   const scale = standard.scoreScale || 4;
@@ -683,6 +735,28 @@ var ResolveResultSchema = z.object({
   testsRun: z.string().nullable().default(null).describe("Command used to verify, and its outcome"),
   remaining: z.array(z.string()).default([]).describe("Anything still unresolved")
 });
+var GeneratedDiagramSchema = z.object({
+  id: z.string().describe("Diagram id from the catalog, or a descriptive slug if bespoke"),
+  groupId: z.string().describe("Catalog group id this diagram belongs to (e.g. architecture)"),
+  title: z.string().describe("Human-readable diagram title"),
+  type: z.string().describe(
+    "Mermaid diagram type used, e.g. flowchart, erDiagram, sequenceDiagram, classDiagram"
+  ),
+  mermaid: z.string().describe("Valid Mermaid source for the diagram (renders in HTML/Markdown)"),
+  description: z.string().describe("One or two sentences: what the diagram shows and why it applies to this repo"),
+  evidence: z.array(z.string()).default([]).describe("Repo files this diagram was derived from")
+});
+var DiagramsResultSchema = z.object({
+  profile: z.object({
+    summary: z.string().describe("2-4 sentence characterisation of the project"),
+    kinds: z.array(z.string()).default([]).describe("Project kind tags, e.g. cli, rest-api, spa, library, data-pipeline, monorepo"),
+    characteristics: z.array(z.string()).default([]).describe(
+      "Notable traits that drove diagram selection (owns a Postgres DB, deploys to k8s, \u2026)"
+    )
+  }).describe("The project profile that justifies which diagrams were chosen"),
+  diagrams: z.array(GeneratedDiagramSchema).describe("The diagrams selected for and generated from this repository"),
+  notes: z.string().nullable().default(null).describe("Optional notes, e.g. diagrams intentionally skipped and why")
+});
 
 // src/commands/benchmark.ts
 async function runBenchmark(opts) {
@@ -715,6 +789,7 @@ async function runBenchmark(opts) {
   const scored = scoreBenchmark(standard, result);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
   const runId = generatedAt.replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  const git = gitInfo(opts.cwd);
   const md = renderBenchmarkMarkdown(scored, {
     repo: basename(opts.cwd),
     languages: resolved.languages,
@@ -728,6 +803,7 @@ async function runBenchmark(opts) {
     generatedAt,
     model: opts.model,
     repo: basename(opts.cwd),
+    git,
     languages: resolved.languages,
     standard: { name: standard.name, version: standard.version, layers: resolved.layers },
     overall: scored.overall,
@@ -739,6 +815,19 @@ async function runBenchmark(opts) {
     recommendations: scored.recommendations,
     costUsd
   };
+  const historyRecord = {
+    runId,
+    generatedAt,
+    commit: git.commit,
+    branch: git.branch,
+    dirty: git.dirty,
+    model: opts.model,
+    standardVersion: standard.version,
+    overall: scored.overall,
+    grade: scored.grade,
+    categories: Object.fromEntries(scored.categories.map((c) => [c.id, c.fraction])),
+    costUsd
+  };
   if (!opts.noWrite && !opts.dryRun) {
     const baseDir = join3(opts.cwd, opts.out);
     const mdOut = md + "\n";
@@ -749,6 +838,7 @@ async function runBenchmark(opts) {
     writeFileSync(join3(runDir, "report.json"), jsonOut, "utf8");
     writeFileSync(join3(baseDir, "report.md"), mdOut, "utf8");
     writeFileSync(join3(baseDir, "report.json"), jsonOut, "utf8");
+    appendFileSync(join3(baseDir, "history.jsonl"), JSON.stringify(historyRecord) + "\n", "utf8");
     log.success(
       `Report written to ${pc3.bold(join3(opts.out, "report.md"))} ${pc3.dim(`(run archived at ${join3(opts.out, "runs", runId)})`)}`
     );
@@ -1221,49 +1311,616 @@ function buildPrompt3(ctx, feedback, instruction) {
   ].join("\n");
 }
 
+// src/commands/serve.ts
+import { join as join7 } from "path";
+
+// src/core/dashboard.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
+import { join as join5 } from "path";
+function assembleFrom(dir, latestFile) {
+  const latest = readJson(join5(dir, latestFile));
+  const history = readJsonl(join5(dir, "history.jsonl"));
+  const runs = {};
+  const runsDir = join5(dir, "runs");
+  if (existsSync3(runsDir)) {
+    for (const entry of readdirSync2(runsDir)) {
+      const report = readJson(join5(runsDir, entry, latestFile));
+      if (report) runs[entry] = report;
+    }
+  }
+  const repo = latest && typeof latest === "object" && "repo" in latest ? latest.repo : void 0;
+  return { repo, latest, history, runs };
+}
+function assembleData(benchmarkDir) {
+  return assembleFrom(benchmarkDir, "report.json");
+}
+function assembleDiagramData(diagramsDir) {
+  return assembleFrom(diagramsDir, "diagrams.json");
+}
+function hasData(data) {
+  return Boolean(data.latest) || data.history.length > 0;
+}
+function findViewerDir(subdir = "viewer", index = "index.html") {
+  const dir = join5(findBundledAssetsDir(), subdir);
+  if (!existsSync3(join5(dir, index))) {
+    throw new Error(
+      `Dashboard viewer assets not found (${subdir}/${index}). Reinstall edsger, or run \`npm run sync-viewer\` in a dev checkout.`
+    );
+  }
+  return dir;
+}
+function findDiagramViewerDir() {
+  return findViewerDir("diagrams-viewer", "diagrams.html");
+}
+function readSingleTemplate(file) {
+  const path = join5(findBundledAssetsDir(), file);
+  if (!existsSync3(path)) {
+    throw new Error(
+      `Single-file viewer template not found (${file}). Reinstall edsger, or run \`npm run sync-viewer\`.`
+    );
+  }
+  return readFileSync2(path, "utf8");
+}
+function readViewerSingleTemplate() {
+  return readSingleTemplate("viewer-single.html");
+}
+function readDiagramViewerSingleTemplate() {
+  return readSingleTemplate("diagrams-viewer-single.html");
+}
+function renderSingleFileWith(template, data, globalName) {
+  const json = JSON.stringify(data).replace(/<\//g, "<\\/");
+  const tag = `<script>window.${globalName}=${json}</script>`;
+  const placeholder = new RegExp(`<!--[^>]*${globalName}[^>]*-->`);
+  if (placeholder.test(template)) return template.replace(placeholder, () => tag);
+  const scriptIdx = template.indexOf("<script");
+  if (scriptIdx !== -1) return template.slice(0, scriptIdx) + tag + template.slice(scriptIdx);
+  const headIdx = template.lastIndexOf("</head>");
+  if (headIdx !== -1) return template.slice(0, headIdx) + tag + template.slice(headIdx);
+  return tag + template;
+}
+function renderSingleFile(template, data) {
+  return renderSingleFileWith(template, data, "__EDSGER_DATA__");
+}
+function renderDiagramsSingleFile(template, data) {
+  return renderSingleFileWith(template, data, "__EDSGER_DIAGRAMS__");
+}
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync2(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function readJsonl(path) {
+  if (!existsSync3(path)) return [];
+  const out = [];
+  for (const line of readFileSync2(path, "utf8").split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      out.push(JSON.parse(t));
+    } catch {
+    }
+  }
+  return out;
+}
+
+// src/core/viewer-server.ts
+import { createReadStream, existsSync as existsSync4, statSync as statSync2 } from "fs";
+import { createServer } from "http";
+import { extname, join as join6, normalize } from "path";
+import pc6 from "picocolors";
+
+// src/core/open.ts
+import { spawn } from "child_process";
+function openInBrowser(target) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", target] : [target];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+}
+
+// src/core/viewer-server.ts
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".map": "application/json",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff"
+};
+async function startViewerServer(opts) {
+  const server = createServer((req, res) => {
+    const url = (req.url ?? "/").split("?")[0] ?? "/";
+    if (url === opts.dataRoute) {
+      res.writeHead(200, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store"
+      });
+      res.end(JSON.stringify(opts.getData()));
+      return;
+    }
+    const rel = url === "/" ? opts.indexFile : decodeURIComponent(url.replace(/^\/+/, ""));
+    const safe = normalize(rel).replace(/^(\.\.(?:[/\\]|$))+/, "");
+    let file = join6(opts.viewerDir, safe);
+    if (!file.startsWith(opts.viewerDir)) {
+      res.writeHead(403);
+      res.end("forbidden");
+      return;
+    }
+    if (!existsSync4(file) || statSync2(file).isDirectory())
+      file = join6(opts.viewerDir, opts.indexFile);
+    res.writeHead(200, { "content-type": MIME[extname(file)] ?? "application/octet-stream" });
+    createReadStream(file).pipe(res);
+  });
+  return new Promise((resolve3, reject) => {
+    server.on("error", reject);
+    server.listen(opts.port, opts.host, () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : opts.port;
+      const shownHost = opts.host === "0.0.0.0" ? "localhost" : opts.host;
+      const url = `http://${shownHost}:${port}/`;
+      if (opts.emptyHint) log.warn(opts.emptyHint);
+      log.success(`Dashboard at ${pc6.bold(pc6.cyan(url))}  ${pc6.dim("(Ctrl-C to stop)")}`);
+      if (opts.open) openInBrowser(url);
+    });
+    const shutdown = () => {
+      server.close(() => resolve3(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  });
+}
+
+// src/commands/serve.ts
+async function runServe(opts) {
+  const benchmarkDir = join7(opts.cwd, opts.dir);
+  const viewerDir = findViewerDir();
+  return startViewerServer({
+    viewerDir,
+    indexFile: "index.html",
+    dataRoute: "/edsger-data.json",
+    getData: () => assembleData(benchmarkDir),
+    port: opts.port,
+    host: opts.host,
+    open: opts.open,
+    emptyHint: hasData(assembleData(benchmarkDir)) ? void 0 : `No benchmark data in ${opts.dir} yet \u2014 run \`edsger benchmark\` first.`
+  });
+}
+
+// src/commands/report.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join8 } from "path";
+import pc7 from "picocolors";
+async function runReport(opts) {
+  const benchmarkDir = join8(opts.cwd, opts.dir);
+  const data = assembleData(benchmarkDir);
+  if (!hasData(data)) {
+    log.error(`No benchmark data in ${opts.dir}. Run \`edsger benchmark\` first.`);
+    return 1;
+  }
+  const html = renderSingleFile(readViewerSingleTemplate(), data);
+  const out = isAbsolute2(opts.html) ? opts.html : join8(opts.cwd, opts.html);
+  mkdirSync2(dirname2(out), { recursive: true });
+  writeFileSync3(out, html, "utf8");
+  log.success(
+    `Wrote self-contained report to ${pc7.bold(opts.html)} ${pc7.dim(`(${Math.round(html.length / 1024)} kB, open in any browser)`)}`
+  );
+  if (opts.open) openInBrowser(out);
+  return 0;
+}
+
+// src/commands/diagram.ts
+import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { basename as basename2, dirname as dirname3, isAbsolute as isAbsolute3, join as join9 } from "path";
+import pc8 from "picocolors";
+
+// src/core/diagrams.ts
+function buildDiagramsPrompt(catalog, cwd, only) {
+  const onlySet = only && only.length ? new Set(only.map((s) => s.trim())) : null;
+  const catalogText = catalog.groups.map((group) => {
+    const diagrams = group.diagrams.filter((d) => !onlySet || onlySet.has(d.id)).map((d) => {
+      const detect = d.detect?.length ? `
+      detect: ${d.detect.join(", ")}` : "";
+      return `    - id: ${d.id}
+      title: ${d.title}
+      mermaidType: ${d.type}
+      appliesWhen: ${d.appliesWhen.trim()}` + detect + `
+      guidance: ${d.guidance.trim()}`;
+    }).join("\n");
+    if (!diagrams) return "";
+    return `- group: ${group.id} (${group.name})
+${diagrams}`;
+  }).filter(Boolean).join("\n");
+  return [
+    `Produce a set of professional software diagrams for the repository at: ${cwd}`,
+    ``,
+    `You have a catalog of candidate diagrams below. Your job is to pick the ones`,
+    `that genuinely fit THIS project and generate each as valid Mermaid.`,
+    ``,
+    `Method:`,
+    `1. Explore the repository (Read/Grep/Glob and read-only Bash like ls, cat, git log).`,
+    `   Characterise the project: what kind is it (service, library, CLI, SPA, data`,
+    `   pipeline, monorepo, \u2026), what does it integrate with, does it own a database,`,
+    `   how is it deployed?`,
+    `2. For each catalog diagram, use its appliesWhen/detect to decide whether it adds`,
+    `   value for this repo. Only include diagrams the evidence supports. A library`,
+    `   needs different diagrams than a microservice. Do NOT invent structure that is`,
+    `   not in the code. Aim for the ${onlySet ? "requested" : "5-9 most valuable"} diagrams.`,
+    `3. For each selected diagram, follow its guidance and emit VALID Mermaid of the`,
+    `   given mermaidType, grounded in real files. Rules for the mermaid field:`,
+    `     - Put ONLY the Mermaid source (starting with the diagram keyword, e.g.`,
+    `       "flowchart TD" or "erDiagram"). Do NOT wrap it in \`\`\`mermaid fences and`,
+    `       do NOT add any prose/markdown outside the diagram.`,
+    `     - It MUST parse as-is. Use simple alphanumeric node/participant ids and put`,
+    `       human text in quoted labels, e.g. A["Order Service"] not A[Order Service].`,
+    `       Quote any label containing spaces, punctuation, parentheses or slashes.`,
+    `     - Avoid Mermaid reserved words as bare node ids (especially "end" in`,
+    `       flowcharts \u2014 write End or "end" instead).`,
+    `     - Set "type" to the exact keyword the source starts with.`,
+    `     - Keep each diagram to roughly one screen and legible.`,
+    `     - Prefer faithful over exhaustive; record the files you used as evidence.`,
+    `4. When finished, call submit_result exactly once with the project profile and`,
+    `   the diagrams (each with id, groupId, title, type, mermaid, description, evidence).`,
+    ``,
+    `Diagram catalog:`,
+    catalogText
+  ].join("\n");
+}
+function sanitizeMermaid(src) {
+  let s = src.trim();
+  const fence = s.match(/^```(?:mermaid)?\s*\n([\s\S]*?)\n```$/);
+  if (fence && fence[1] !== void 0) s = fence[1].trim();
+  return s;
+}
+var KNOWN_MERMAID_TYPES = /* @__PURE__ */ new Set([
+  "flowchart",
+  "graph",
+  "sequenceDiagram",
+  "classDiagram",
+  "stateDiagram",
+  "stateDiagram-v2",
+  "erDiagram",
+  "journey",
+  "gantt",
+  "gitGraph",
+  "mindmap",
+  "timeline",
+  "requirementDiagram",
+  "quadrantChart",
+  "pie",
+  "sankey-beta",
+  "xychart-beta",
+  "block-beta",
+  "packet-beta",
+  "kanban",
+  "zenuml",
+  "C4Context",
+  "C4Container",
+  "C4Component",
+  "C4Deployment",
+  "C4Dynamic",
+  "architecture-beta"
+]);
+function firstKeyword(mermaid) {
+  for (const raw of mermaid.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("%%")) continue;
+    return line.split(/[\s({]/)[0] ?? line;
+  }
+  return "";
+}
+function normaliseType(keyword) {
+  const k = keyword.trim();
+  if (k === "graph") return "flowchart";
+  if (k === "stateDiagram") return "stateDiagram-v2";
+  return k;
+}
+function inferType(mermaid) {
+  return firstKeyword(mermaid) || "flowchart";
+}
+function validateMermaid(declaredType, mermaid) {
+  const warnings = [];
+  if (mermaid.includes("```")) warnings.push("source still contains a ``` fence");
+  const keyword = firstKeyword(mermaid);
+  if (!keyword) {
+    warnings.push("no diagram content");
+    return warnings;
+  }
+  if (!KNOWN_MERMAID_TYPES.has(keyword)) {
+    warnings.push(`unrecognised diagram keyword "${keyword}"`);
+  }
+  const body = mermaid.split("\n").filter((l) => {
+    const t = l.trim();
+    return t && !t.startsWith("%%");
+  });
+  if (body.length < 2) warnings.push("header only \u2014 the diagram has no body");
+  if (declaredType && KNOWN_MERMAID_TYPES.has(keyword)) {
+    if (normaliseType(declaredType) !== normaliseType(keyword)) {
+      warnings.push(`declared type "${declaredType}" but source starts with "${keyword}"`);
+    }
+  }
+  return warnings;
+}
+function prepareDiagrams(catalog, result) {
+  const groupName = new Map(catalog.groups.map((g) => [g.id, g.name]));
+  const groupOrder = new Map(catalog.groups.map((g, i) => [g.id, i]));
+  const prepared = [];
+  const seenIds = /* @__PURE__ */ new Map();
+  for (const d of result.diagrams) {
+    const mermaid = sanitizeMermaid(d.mermaid ?? "");
+    if (!mermaid) {
+      log.warn(`Skipping diagram "${d.id}" \u2014 it had no mermaid source.`);
+      continue;
+    }
+    const baseId = d.id || inferType(mermaid);
+    const count = seenIds.get(baseId) ?? 0;
+    seenIds.set(baseId, count + 1);
+    const id = count === 0 ? baseId : `${baseId}-${count + 1}`;
+    const type = d.type?.trim() || inferType(mermaid);
+    prepared.push({
+      ...d,
+      id,
+      mermaid,
+      type,
+      evidence: d.evidence ?? [],
+      groupName: groupName.get(d.groupId) ?? "Other",
+      warnings: validateMermaid(type, mermaid)
+    });
+  }
+  prepared.sort((a, b) => {
+    const oa = groupOrder.get(a.groupId) ?? Number.MAX_SAFE_INTEGER;
+    const ob = groupOrder.get(b.groupId) ?? Number.MAX_SAFE_INTEGER;
+    return oa - ob;
+  });
+  if (prepared.length === 0) {
+    log.warn("The agent returned no usable diagrams.");
+  } else {
+    const flagged = prepared.filter((d) => d.warnings.length);
+    if (flagged.length) {
+      log.warn(
+        `${flagged.length}/${prepared.length} diagram(s) have Mermaid warnings \u2014 they will still render if valid, but check: ${flagged.map((d) => d.id).join(", ")}`
+      );
+    }
+  }
+  return { profile: result.profile, diagrams: prepared, notes: result.notes ?? null };
+}
+function renderDiagramsMarkdown(prepared, meta) {
+  const lines = [];
+  lines.push(`# Edsger Diagrams`);
+  lines.push("");
+  lines.push(`> ${prepared.profile.summary}`);
+  lines.push("");
+  lines.push(`| Field | Value |`);
+  lines.push(`| --- | --- |`);
+  lines.push(`| Repository | \`${meta.repo}\` |`);
+  lines.push(`| Languages | ${meta.languages.join(", ") || "n/a"} |`);
+  lines.push(`| Project kinds | ${prepared.profile.kinds.join(", ") || "n/a"} |`);
+  lines.push(`| Catalog sources | ${meta.layers.join(" \u2192 ")} |`);
+  lines.push(`| Model | ${meta.model} |`);
+  lines.push(`| Generated | ${meta.generatedAt} |`);
+  lines.push("");
+  if (prepared.profile.characteristics.length) {
+    lines.push(`**Characteristics:** ${prepared.profile.characteristics.join(" \xB7 ")}`);
+    lines.push("");
+  }
+  let currentGroup = null;
+  for (const d of prepared.diagrams) {
+    if (d.groupName !== currentGroup) {
+      currentGroup = d.groupName;
+      lines.push(`## ${currentGroup}`);
+      lines.push("");
+    }
+    lines.push(`### ${d.title}`);
+    lines.push("");
+    lines.push(`${d.description} _(${d.type})_`);
+    lines.push("");
+    if (d.warnings.length) {
+      lines.push(`> \u26A0\uFE0F ${d.warnings.join("; ")}`);
+      lines.push("");
+    }
+    lines.push("```mermaid");
+    lines.push(d.mermaid);
+    lines.push("```");
+    lines.push("");
+    if (d.evidence.length) {
+      lines.push(`<sub>Evidence: ${d.evidence.map((e) => `\`${e}\``).join(", ")}</sub>`);
+      lines.push("");
+    }
+  }
+  if (prepared.notes) {
+    lines.push(`## Notes`);
+    lines.push("");
+    lines.push(prepared.notes);
+    lines.push("");
+  }
+  lines.push(`---`);
+  lines.push(`<sub>Generated by [edsger](https://www.npmjs.com/package/edsger).</sub>`);
+  return lines.join("\n");
+}
+
+// src/commands/diagram.ts
+async function runDiagramGenerate(opts) {
+  const { config, path: configPath } = loadConfig(opts.cwd);
+  const configDir = configPath ? join9(configPath, "..") : opts.cwd;
+  const resolved = resolveStandard("diagrams", opts, config, configDir);
+  const catalog = resolved.standard;
+  log.info(
+    `Diagramming ${pc8.bold(basename2(opts.cwd))} with ${pc8.bold(catalog.name)} (languages: ${resolved.languages.join(", ") || "generic"})`
+  );
+  log.debug(`catalog layers: ${resolved.layers.join(" \u2192 ")}`);
+  const prompt = buildDiagramsPrompt(catalog, opts.cwd, opts.only);
+  const { result, costUsd, numTurns } = await runAgent({
+    prompt,
+    cwd: opts.cwd,
+    model: opts.model,
+    maxTurns: opts.maxTurns,
+    timeoutMs: opts.timeoutMs,
+    allowWrite: false,
+    verbose: opts.verbose,
+    resultShape: DiagramsResultSchema.shape,
+    systemPromptAppend: "You are Edsger, a staff-level software architect. You produce accurate, legible diagrams of a codebase as valid Mermaid, grounded strictly in the code you inspect. Never invent components, tables, or flows that are not in the repository. Do not modify any files."
+  });
+  if (!result) {
+    log.error(
+      "The agent did not produce a result. Try increasing --max-turns or check credentials."
+    );
+    return 1;
+  }
+  const prepared = prepareDiagrams(catalog, result);
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const runId = generatedAt.replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  const git = gitInfo(opts.cwd);
+  const md = renderDiagramsMarkdown(prepared, {
+    repo: basename2(opts.cwd),
+    languages: resolved.languages,
+    layers: resolved.layers,
+    generatedAt,
+    model: opts.model
+  });
+  const jsonReport = {
+    schema: "edsger.diagrams/1",
+    runId,
+    generatedAt,
+    model: opts.model,
+    repo: basename2(opts.cwd),
+    git,
+    languages: resolved.languages,
+    catalog: { name: catalog.name, version: catalog.version, layers: resolved.layers },
+    profile: prepared.profile,
+    diagrams: prepared.diagrams,
+    notes: prepared.notes,
+    costUsd
+  };
+  const groupCounts = {};
+  for (const d of prepared.diagrams) groupCounts[d.groupId] = (groupCounts[d.groupId] ?? 0) + 1;
+  const historyRecord = {
+    runId,
+    generatedAt,
+    commit: git.commit,
+    branch: git.branch,
+    dirty: git.dirty,
+    model: opts.model,
+    catalogVersion: catalog.version,
+    diagramCount: prepared.diagrams.length,
+    groups: groupCounts,
+    costUsd
+  };
+  if (!opts.noWrite && !opts.dryRun) {
+    const baseDir = join9(opts.cwd, opts.out);
+    const mdOut = md + "\n";
+    const jsonOut = JSON.stringify(jsonReport, null, 2) + "\n";
+    const runDir = join9(baseDir, "runs", runId);
+    mkdirSync3(runDir, { recursive: true });
+    writeFileSync4(join9(runDir, "diagrams.json"), jsonOut, "utf8");
+    writeFileSync4(join9(runDir, "diagrams.md"), mdOut, "utf8");
+    writeFileSync4(join9(baseDir, "diagrams.json"), jsonOut, "utf8");
+    writeFileSync4(join9(baseDir, "diagrams.md"), mdOut, "utf8");
+    appendFileSync2(join9(baseDir, "history.jsonl"), JSON.stringify(historyRecord) + "\n", "utf8");
+    log.success(
+      `Diagrams written to ${pc8.bold(join9(opts.out, "diagrams.md"))} ${pc8.dim(`(run archived at ${join9(opts.out, "runs", runId)})`)}`
+    );
+  }
+  printSummary3(prepared, numTurns, costUsd);
+  if (opts.json) process.stdout.write(JSON.stringify(jsonReport, null, 2) + "\n");
+  return 0;
+}
+function printSummary3(prepared, numTurns, costUsd) {
+  log.heading(`${prepared.diagrams.length} diagram(s)`);
+  let currentGroup = null;
+  for (const d of prepared.diagrams) {
+    if (d.groupName !== currentGroup) {
+      currentGroup = d.groupName;
+      process.stderr.write(`  ${pc8.bold(currentGroup)}
+`);
+    }
+    const warn = d.warnings.length ? ` ${pc8.yellow("\u26A0")}` : "";
+    process.stderr.write(`    ${pc8.cyan("\u25C6")} ${d.title} ${pc8.dim(`(${d.type})`)}${warn}
+`);
+  }
+  log.step(`${numTurns} turns \xB7 ~$${costUsd.toFixed(3)}`);
+}
+async function runDiagramServe(opts) {
+  const diagramsDir = join9(opts.cwd, opts.dir);
+  const viewerDir = findDiagramViewerDir();
+  return startViewerServer({
+    viewerDir,
+    indexFile: "diagrams.html",
+    dataRoute: "/edsger-diagrams.json",
+    getData: () => assembleDiagramData(diagramsDir),
+    port: opts.port,
+    host: opts.host,
+    open: opts.open,
+    emptyHint: hasData(assembleDiagramData(diagramsDir)) ? void 0 : `No diagram data in ${opts.dir} yet \u2014 run \`edsger diagram\` first.`
+  });
+}
+async function runDiagramReport(opts) {
+  const diagramsDir = join9(opts.cwd, opts.dir);
+  const data = assembleDiagramData(diagramsDir);
+  if (!hasData(data)) {
+    log.error(`No diagram data in ${opts.dir}. Run \`edsger diagram\` first.`);
+    return 1;
+  }
+  const html = renderDiagramsSingleFile(readDiagramViewerSingleTemplate(), data);
+  const out = isAbsolute3(opts.html) ? opts.html : join9(opts.cwd, opts.html);
+  mkdirSync3(dirname3(out), { recursive: true });
+  writeFileSync4(out, html, "utf8");
+  log.success(
+    `Wrote self-contained diagram viewer to ${pc8.bold(opts.html)} ${pc8.dim(`(${Math.round(html.length / 1024)} kB, open in any browser)`)}`
+  );
+  if (opts.open) openInBrowser(out);
+  return 0;
+}
+
 // src/commands/skills.ts
 import {
   cpSync,
-  existsSync as existsSync3,
-  mkdirSync as mkdirSync2,
-  readFileSync as readFileSync2,
-  readdirSync as readdirSync2,
+  existsSync as existsSync5,
+  mkdirSync as mkdirSync4,
+  readFileSync as readFileSync3,
+  readdirSync as readdirSync3,
   rmSync as rmSync2,
-  statSync as statSync2,
-  writeFileSync as writeFileSync3
+  statSync as statSync3,
+  writeFileSync as writeFileSync5
 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join5 } from "path";
-import pc6 from "picocolors";
+import { join as join10 } from "path";
+import pc9 from "picocolors";
 var MANAGED = ["benchmark", "pr-review", "pr-resolve"];
 function targetSkillsDir(scope) {
-  return scope.global ? join5(homedir2(), ".claude", "skills") : join5(scope.cwd, ".claude", "skills");
+  return scope.global ? join10(homedir2(), ".claude", "skills") : join10(scope.cwd, ".claude", "skills");
 }
 function sourceSkillsDir() {
-  return join5(findBundledAssetsDir(), "skills");
+  return join10(findBundledAssetsDir(), "skills");
 }
 async function runSkillsInstall(opts) {
   const assetsDir = findBundledAssetsDir();
   const src = sourceSkillsDir();
-  if (!existsSync3(src)) {
+  if (!existsSync5(src)) {
     log.error(`Bundled skills not found at ${src}. Reinstall edsger.`);
     return 1;
   }
   const dest = targetSkillsDir(opts);
-  mkdirSync2(dest, { recursive: true });
-  const available = readdirSync2(src).filter((n) => existsSync3(join5(src, n, "SKILL.md")));
+  mkdirSync4(dest, { recursive: true });
+  const available = readdirSync3(src).filter((n) => existsSync5(join10(src, n, "SKILL.md")));
   let installed = 0;
   for (const name of available) {
-    const outDir = join5(dest, name);
-    if (existsSync3(outDir) && !opts.force) {
+    const outDir = join10(dest, name);
+    if (existsSync5(outDir) && !opts.force) {
       log.warn(`skill "${name}" already exists \u2014 use --force to overwrite`);
       continue;
     }
     rmSync2(outDir, { recursive: true, force: true });
-    cpSync(join5(src, name), outDir, { recursive: true });
-    const skillFile = join5(outDir, "SKILL.md");
-    const rewritten = readFileSync2(skillFile, "utf8").split("${CLAUDE_PLUGIN_ROOT}").join(assetsDir);
-    writeFileSync3(skillFile, rewritten, "utf8");
+    cpSync(join10(src, name), outDir, { recursive: true });
+    const skillFile = join10(outDir, "SKILL.md");
+    const rewritten = readFileSync3(skillFile, "utf8").split("${CLAUDE_PLUGIN_ROOT}").join(assetsDir);
+    writeFileSync5(skillFile, rewritten, "utf8");
     installed++;
     log.success(`installed /${name}`);
   }
@@ -1271,7 +1928,7 @@ async function runSkillsInstall(opts) {
     log.info("Nothing installed.");
     return 0;
   }
-  log.heading(`Installed ${installed} skill(s) into ${pc6.bold(dest)}`);
+  log.heading(`Installed ${installed} skill(s) into ${pc9.bold(dest)}`);
   log.step(`scope: ${opts.global ? "user (all projects)" : "this project"}`);
   log.step(`standards: ${assetsDir}`);
   log.step("Open Claude Code and run /benchmark, /pr-review, or /pr-resolve.");
@@ -1281,8 +1938,8 @@ async function runSkillsUninstall(opts) {
   const dest = targetSkillsDir(opts);
   let removed = 0;
   for (const name of MANAGED) {
-    const dir = join5(dest, name);
-    if (existsSync3(dir)) {
+    const dir = join10(dest, name);
+    if (existsSync5(dir)) {
       rmSync2(dir, { recursive: true, force: true });
       removed++;
       log.success(`removed /${name}`);
@@ -1298,20 +1955,20 @@ async function runSkillsList(opts) {
   ]) {
     const dir = targetSkillsDir(scope);
     const present = MANAGED.filter((n) => {
-      const p = join5(dir, n, "SKILL.md");
-      return existsSync3(p) && statSync2(p).isFile();
+      const p = join10(dir, n, "SKILL.md");
+      return existsSync5(p) && statSync3(p).isFile();
     });
     log.heading(`${label}: ${dir}`);
-    if (present.length) for (const n of present) process.stderr.write(`  ${pc6.green("\u2713")} /${n}
+    if (present.length) for (const n of present) process.stderr.write(`  ${pc9.green("\u2713")} /${n}
 `);
-    else process.stderr.write(`  ${pc6.dim("(none installed)")}
+    else process.stderr.write(`  ${pc9.dim("(none installed)")}
 `);
   }
   return 0;
 }
 
 // src/index.ts
-var pkg = JSON.parse(readFileSync3(new URL("../package.json", import.meta.url), "utf8"));
+var pkg = JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8"));
 var VERSION = pkg.version;
 var DEFAULT_MODEL = "claude-sonnet-4-6";
 function toGlobal(raw) {
@@ -1349,10 +2006,88 @@ program.name("edsger").description(
   "Agentic CLI to benchmark repositories and review/resolve pull requests\nagainst industrial-grade standards (from edsger-assets, fully overridable)."
 ).version(VERSION, "-V, --version");
 addGlobalOptions(
-  program.command("benchmark").description("Score a repository against a benchmark rubric and write a report").option("--out <dir>", "report output directory (relative to repo)", ".edsger/benchmark").option("--no-write", "do not write report files into the repo")
+  program.command("benchmark").description("Score a repository against a benchmark rubric and write a report").option("--out <dir>", "report output directory (relative to repo)", ".edsger/benchmark").option("--no-write", "do not write report files into the repo").option("--serve", "open the dashboard after benchmarking")
 ).action(async (opts) => {
+  await guard(async () => {
+    const g = toGlobal(opts);
+    const code = await runBenchmark({ ...g, out: opts.out, noWrite: opts.write === false });
+    if (code === 0 && opts.serve) {
+      return runServe({ cwd: g.cwd, dir: opts.out, port: 4577, host: "127.0.0.1", open: true });
+    }
+    return code;
+  });
+});
+program.command("serve").description("Serve the benchmark dashboard (current, history, trends) locally").option("-C, --cwd <dir>", "repository directory").option("--dir <dir>", "benchmark output directory (relative to repo)", ".edsger/benchmark").option("--port <n>", "port to listen on", "4577").option("--host <host>", "host to bind", "127.0.0.1").option("--no-open", "do not open the browser automatically").action(
+  async (opts) => {
+    await guard(
+      () => runServe({
+        cwd: resolve2(opts.cwd ?? process.cwd()),
+        dir: opts.dir,
+        port: Number.parseInt(opts.port, 10) || 4577,
+        host: opts.host,
+        open: opts.open !== false
+      })
+    );
+  }
+);
+program.command("report").description("Export a self-contained HTML dashboard (data inlined) for sharing").option("-C, --cwd <dir>", "repository directory").option("--dir <dir>", "benchmark output directory (relative to repo)", ".edsger/benchmark").option("--html <path>", "output HTML file path", "edsger-report.html").option("--open", "open the exported file after writing").action(async (opts) => {
   await guard(
-    () => runBenchmark({ ...toGlobal(opts), out: opts.out, noWrite: opts.write === false })
+    () => runReport({
+      cwd: resolve2(opts.cwd ?? process.cwd()),
+      dir: opts.dir,
+      html: opts.html,
+      open: Boolean(opts.open)
+    })
+  );
+});
+var diagram = program.command("diagram").description("Generate & view diagrams (architecture, ER, sequence, flow) for a repository");
+addGlobalOptions(
+  diagram.command("generate", { isDefault: true }).description("Analyze the repository and generate diagrams as Mermaid").option("--out <dir>", "diagram output directory (relative to repo)", ".edsger/diagrams").option("--no-write", "do not write diagram files into the repo").option("--only <ids>", "comma-separated catalog diagram ids to generate").option("--serve", "open the diagram dashboard after generating")
+).action(
+  async (opts) => {
+    await guard(async () => {
+      const g = toGlobal(opts);
+      const only = opts.only ? opts.only.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+      const code = await runDiagramGenerate({
+        ...g,
+        out: opts.out,
+        noWrite: opts.write === false,
+        only
+      });
+      if (code === 0 && opts.serve) {
+        return runDiagramServe({
+          cwd: g.cwd,
+          dir: opts.out,
+          port: 4578,
+          host: "127.0.0.1",
+          open: true
+        });
+      }
+      return code;
+    });
+  }
+);
+diagram.command("serve").description("Serve the diagram dashboard locally").option("-C, --cwd <dir>", "repository directory").option("--dir <dir>", "diagram output directory (relative to repo)", ".edsger/diagrams").option("--port <n>", "port to listen on", "4578").option("--host <host>", "host to bind", "127.0.0.1").option("--no-open", "do not open the browser automatically").action(
+  async (opts) => {
+    await guard(
+      () => runDiagramServe({
+        cwd: resolve2(opts.cwd ?? process.cwd()),
+        dir: opts.dir,
+        port: Number.parseInt(opts.port, 10) || 4578,
+        host: opts.host,
+        open: opts.open !== false
+      })
+    );
+  }
+);
+diagram.command("report").description("Export a self-contained HTML diagram viewer (data inlined) for sharing").option("-C, --cwd <dir>", "repository directory").option("--dir <dir>", "diagram output directory (relative to repo)", ".edsger/diagrams").option("--html <path>", "output HTML file path", "edsger-diagrams.html").option("--open", "open the exported file after writing").action(async (opts) => {
+  await guard(
+    () => runDiagramReport({
+      cwd: resolve2(opts.cwd ?? process.cwd()),
+      dir: opts.dir,
+      html: opts.html,
+      open: Boolean(opts.open)
+    })
   );
 });
 addGlobalOptions(
@@ -1403,11 +2138,14 @@ program.addHelpText(
   "after",
   `
 Examples:
-  ${pc7.dim("$")} edsger benchmark
-  ${pc7.dim("$")} edsger benchmark -C ./my-repo --json
-  ${pc7.dim("$")} edsger pr-review 123 --post
-  ${pc7.dim("$")} edsger pr-resolve 123 --instruction "fix the failing test" --push
-  ${pc7.dim("$")} edsger skills install   ${pc7.dim("# enable /benchmark etc. in Claude Code")}
+  ${pc10.dim("$")} edsger benchmark
+  ${pc10.dim("$")} edsger benchmark -C ./my-repo --json
+  ${pc10.dim("$")} edsger diagram              ${pc10.dim("# generate diagrams for the current repo")}
+  ${pc10.dim("$")} edsger diagram --serve      ${pc10.dim("# \u2026and open them in the browser")}
+  ${pc10.dim("$")} edsger diagram report --html diagrams.html
+  ${pc10.dim("$")} edsger pr-review 123 --post
+  ${pc10.dim("$")} edsger pr-resolve 123 --instruction "fix the failing test" --push
+  ${pc10.dim("$")} edsger skills install   ${pc10.dim("# enable /benchmark etc. in Claude Code")}
 
 Auth: the agent uses your Claude Code login (run \`claude\` once to sign in); run \`gh auth login\` for PR commands.
 `