edsger 0.84.0 → 0.85.0

package/dist/index.js

@@ -4,7 +4,7 @@
 import { readFileSync as readFileSync4 } from "fs";
 import { resolve as resolve2 } from "path";
 import { Command, Option } from "commander";
-import pc12 from "picocolors";
+import pc13 from "picocolors";
 
 // src/commands/audit.ts
 import { appendFileSync, mkdirSync, writeFileSync } from "fs";
@@ -127,7 +127,7 @@ function resolveStandard(kind, opts, config, configDir, forcedLanguages) {
   const roots = [
     { path: bundled, label: opts.assetsPath ? `assets:${opts.assetsPath}` : "bundled" }
   ];
-  const perKind = kind === "benchmark" ? config.benchmark?.standards : kind === "diagrams" ? config.diagrams?.standards : kind === "mindmap" ? config.mindmap?.standards : kind === "audit" ? config.audit?.standards : config.review?.standards;
+  const perKind = kind === "benchmark" ? config.benchmark?.standards : kind === "diagrams" ? config.diagrams?.standards : kind === "mindmap" ? config.mindmap?.standards : kind === "testcases" ? config.testcases?.standards : kind === "audit" ? config.audit?.standards : config.review?.standards;
   const overrideSpec = perKind ?? config.standards;
   if (overrideSpec && !opts.assetsPath) {
     roots.push({ path: resolveRootPath(overrideSpec, configDir), label: `config:${overrideSpec}` });
@@ -188,6 +188,12 @@ function mergeLayers(kind, layers) {
       {}
     );
   }
+  if (kind === "testcases") {
+    return layers.reduce(
+      (acc, layer) => mergeTestcases(acc, layer),
+      {}
+    );
+  }
   if (kind === "audit") {
     return layers.reduce(
       (acc, layer) => mergeAudit(acc, layer),
@@ -238,6 +244,24 @@ function mergeMindmap(base, overlay) {
     aspects
   };
 }
+function mergeTestcases(base, overlay) {
+  const aspects = mergeById(base.aspects ?? [], overlay.aspects ?? [], (b, o) => ({
+    ...b,
+    ...o
+  }));
+  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: "testcases",
+    guidance: overlay.guidance ?? base.guidance,
+    maxDepth: overlay.maxDepth ?? base.maxDepth,
+    aspects
+  };
+}
 function mergeBenchmark(base, overlay) {
   const categories = mergeById(
     base.categories ?? [],
@@ -593,6 +617,9 @@ function assembleDiagramData(diagramsDir) {
 function assembleMindmapData(mindmapDir) {
   return assembleFrom(mindmapDir, "mindmap.json");
 }
+function assembleTestcasesData(testcasesDir) {
+  return assembleFrom(testcasesDir, "testcases.json");
+}
 function assembleAuditData(auditDir) {
   return assembleFrom(auditDir, "report.json");
 }
@@ -614,6 +641,9 @@ function findDiagramViewerDir() {
 function findMindmapViewerDir() {
   return findViewerDir("mindmap-viewer", "mindmap.html");
 }
+function findTestcasesViewerDir() {
+  return findViewerDir("testcases-viewer", "testcases.html");
+}
 function findAuditViewerDir() {
   return findViewerDir("audit-viewer", "audit.html");
 }
@@ -635,6 +665,9 @@ function readDiagramViewerSingleTemplate() {
 function readMindmapViewerSingleTemplate() {
   return readSingleTemplate("mindmap-viewer-single.html");
 }
+function readTestcasesViewerSingleTemplate() {
+  return readSingleTemplate("testcases-viewer-single.html");
+}
 function readAuditViewerSingleTemplate() {
   return readSingleTemplate("audit-viewer-single.html");
 }
@@ -658,6 +691,9 @@ function renderDiagramsSingleFile(template, data) {
 function renderMindmapSingleFile(template, data) {
   return renderSingleFileWith(template, data, "__EDSGER_MINDMAP__");
 }
+function renderTestcasesSingleFile(template, data) {
+  return renderSingleFileWith(template, data, "__EDSGER_TESTCASES__");
+}
 function renderAuditSingleFile(template, data) {
   return renderSingleFileWith(template, data, "__EDSGER_AUDIT__");
 }
@@ -1024,6 +1060,30 @@ var MindmapResultSchema = z.object({
   ),
   notes: z.string().nullable().default(null).describe("Optional notes, e.g. areas intentionally left out and why")
 });
+var TestcasePrioritySchema = z.enum(["critical", "high", "medium", "low"]);
+var TestcaseNodeSchema = z.object({
+  id: z.string().describe("Unique kebab-case node id, e.g. 'core-flows' or 'login-empty-password'"),
+  parentId: z.string().nullable().default(null).describe("id of the parent node; null ONLY for the single root node"),
+  title: z.string().describe("Short outline-bullet title, 2-8 words"),
+  summary: z.string().describe("One or two sentences: what this area covers, or what this case verifies"),
+  kind: z.string().default("topic").describe("Tag: area, feature, flow, scenario, case, or topic ('case' = executable leaf)"),
+  priority: TestcasePrioritySchema.nullable().default(null).describe("Case priority (critical/high/medium/low); null for grouping nodes"),
+  preconditions: z.array(z.string()).default([]).describe("State a tester must prepare before the steps (cases only)"),
+  steps: z.array(z.string()).default([]).describe("Exact, observable manual actions, in order (cases only)"),
+  expected: z.string().nullable().default(null).describe("The single expected outcome the tester verifies (cases only)"),
+  files: z.array(z.string()).default([]).describe("Repo-relative files implementing the behaviour under test")
+});
+var TestcasesResultSchema = 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 shaped the plan (owns a Postgres DB, monorepo, \u2026)")
+  }).describe("The project profile behind the plan's shape"),
+  nodes: z.array(TestcaseNodeSchema).describe(
+    "The whole test plan as a flat node list: exactly one root (parentId=null), children listed in reading order after their parent, leaves as concrete cases"
+  ),
+  notes: z.string().nullable().default(null).describe("Optional notes, e.g. areas intentionally left untested and why")
+});
 
 // src/commands/audit.ts
 async function runAudit(opts, deps = { agent: runAgent }) {
@@ -2658,26 +2718,415 @@ async function runMindmapReport(opts) {
   return 0;
 }
 
+// src/commands/testcases.ts
+import { appendFileSync as appendFileSync5, mkdirSync as mkdirSync6, writeFileSync as writeFileSync7 } from "fs";
+import { basename as basename5, dirname as dirname6, isAbsolute as isAbsolute6, join as join12 } from "path";
+import pc11 from "picocolors";
+
+// src/core/testcases.ts
+var PRIORITY_ORDER = ["critical", "high", "medium", "low"];
+function isCase(node) {
+  return node.steps.length > 0 || Boolean(node.expected);
+}
+function buildTestcasesPrompt(standard, cwd, focus) {
+  const maxDepth = standard.maxDepth ?? 5;
+  const aspectsText = standard.aspects.map((a) => {
+    const detect = a.detect?.length ? `
+    detect: ${a.detect.join(", ")}` : "";
+    return `  - id: ${a.id}
+    name: ${a.name}
+    appliesWhen: ${a.appliesWhen.trim()}` + detect + `
+    guidance: ${a.guidance.trim()}`;
+  }).join("\n");
+  return [
+    `Derive a MANUAL test-case plan for the repository at: ${cwd}`,
+    ``,
+    `The plan is an outline tree (like Workflowy): the root is the project, the`,
+    `branches are the areas a human tester should exercise, and every leaf is a`,
+    `single concrete test case a tester who has never read the code can execute.`,
+    `These are NOT automated code tests \u2014 they describe how a person verifies the`,
+    `software behaves correctly by actually using it.`,
+    ...focus ? [
+      ``,
+      `FOCUS: the user asked the plan to concentrate on: "${focus}". Give that`,
+      `area most of the depth; keep other areas to a shallow orientation level.`
+    ] : [],
+    ``,
+    `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 its real entry points and user-facing`,
+    `   behaviours are, and what failure modes the code actually handles.`,
+    `2. You have a list of candidate top-level test areas ("aspects") below. Keep`,
+    `   only the ones THIS project's code supports (use appliesWhen/detect), rename`,
+    `   them to the project's own vocabulary where that is clearer, and grow each`,
+    `   into a subtree by following its guidance. Aim for 3-7 first-level areas.`,
+    `3. Tree rules:`,
+    `   - Root node: the project \u2014 its name as the title, one line on what a tester`,
+    `     is validating. Exactly ONE root.`,
+    `   - Interior nodes group features/scenarios: short title (2-8 words) plus a`,
+    `     one-sentence summary specific to THIS codebase. Tag them kind: area,`,
+    `     feature, flow, scenario, or topic.`,
+    `   - EVERY leaf is one executable test case, tagged kind: "case", with:`,
+    `       * summary \u2014 what the case verifies and why it matters;`,
+    `       * preconditions \u2014 the state to prepare (install done, env var set, \u2026);`,
+    `       * steps \u2014 exact, observable manual actions in order ("Run \`x --y\`",`,
+    `         "Click Save", "Delete the config file"), each independently checkable;`,
+    `       * expected \u2014 the SINGLE outcome the tester verifies (message, exit`,
+    `         code, UI state, file contents);`,
+    `       * priority \u2014 critical (release blocker if broken), high (core`,
+    `         behaviour), medium (important but recoverable), or low (polish);`,
+    `       * files \u2014 the repo files implementing the behaviour under test.`,
+    `   - Ground every case in behaviour that is actually in the code: real`,
+    `     commands, flags, routes, screens, and error branches. Never invent`,
+    `     behaviour, and never write "check that it works" \u2014 say exactly what to do`,
+    `     and exactly what should happen.`,
+    `   - Maximum depth ${maxDepth} (root inclusive). Prefer depth where the risk`,
+    `     is, brevity where the behaviour is trivial \u2014 a plan a tester can work`,
+    `     through top-to-bottom, not a combinatorial matrix.`,
+    `4. Encode the tree as a FLAT node list: each node has a unique kebab-case "id"`,
+    `   and a "parentId" referencing its parent's id (null only for the root). List`,
+    `   children in reading order right after their parent.`,
+    `5. When finished, call submit_result exactly once with the project profile,`,
+    `   the flat node list, and optional notes.`,
+    ``,
+    ...standard.guidance ? [`Overall guidance: ${standard.guidance.trim()}`, ``] : [],
+    `Candidate top-level test areas:`,
+    aspectsText
+  ].join("\n");
+}
+function slugify2(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "node";
+}
+function prepareTestcases(result, fallback) {
+  const warnings = [];
+  const byId = /* @__PURE__ */ new Map();
+  for (const raw of result.nodes) {
+    const node = { ...raw, id: raw.id?.trim() || slugify2(raw.title) };
+    if (!node.title?.trim()) {
+      warnings.push(`dropped a node with no title (id "${node.id}")`);
+      continue;
+    }
+    let id = node.id;
+    for (let n = 2; byId.has(id); n++) id = `${node.id}-${n}`;
+    if (id !== node.id) warnings.push(`renamed duplicate node id "${node.id}" to "${id}"`);
+    byId.set(id, { ...node, id });
+  }
+  const parentOf = /* @__PURE__ */ new Map();
+  for (const node of byId.values()) {
+    const p = node.parentId && node.parentId !== node.id ? node.parentId : null;
+    parentOf.set(node.id, p && byId.has(p) ? p : null);
+    if (node.parentId && !byId.has(node.parentId)) {
+      warnings.push(`node "${node.id}" referenced missing parent "${node.parentId}"`);
+    }
+  }
+  for (const id of parentOf.keys()) {
+    const seen = /* @__PURE__ */ new Set([id]);
+    let cur = parentOf.get(id) ?? null;
+    while (cur) {
+      if (seen.has(cur)) {
+        warnings.push(`broke a parent cycle at node "${cur}"`);
+        parentOf.set(cur, null);
+        break;
+      }
+      seen.add(cur);
+      cur = parentOf.get(cur) ?? null;
+    }
+  }
+  const treeOf = /* @__PURE__ */ new Map();
+  for (const node of byId.values()) {
+    treeOf.set(node.id, {
+      id: node.id,
+      title: node.title.trim(),
+      summary: node.summary?.trim() ?? "",
+      kind: node.kind?.trim() || "topic",
+      priority: node.priority ?? null,
+      preconditions: node.preconditions ?? [],
+      steps: node.steps ?? [],
+      expected: node.expected?.trim() || null,
+      files: node.files ?? [],
+      children: []
+    });
+  }
+  const roots = [];
+  for (const node of byId.values()) {
+    const tree = treeOf.get(node.id);
+    const parent = parentOf.get(node.id);
+    if (parent) treeOf.get(parent).children.push(tree);
+    else roots.push(tree);
+  }
+  let root;
+  if (roots.length === 1 && roots[0]) {
+    root = roots[0];
+  } else {
+    if (roots.length > 1) warnings.push(`${roots.length} root nodes \u2014 gathered under the project`);
+    let rootId = "root";
+    for (let n = 2; treeOf.has(rootId); n++) rootId = `root-${n}`;
+    root = {
+      id: rootId,
+      title: fallback.repo,
+      summary: result.profile.summary,
+      kind: "area",
+      priority: null,
+      preconditions: [],
+      steps: [],
+      expected: null,
+      files: [],
+      children: roots
+    };
+  }
+  const nodeCount = countNodes3(root);
+  const depth = treeDepth2(root);
+  const priorities = { critical: 0, high: 0, medium: 0, low: 0 };
+  let caseCount = 0;
+  const tally = (node) => {
+    if (isCase(node)) {
+      caseCount++;
+      priorities[node.priority ?? "medium"]++;
+    }
+    node.children.forEach(tally);
+  };
+  tally(root);
+  if (nodeCount <= 1) log.warn("The agent returned an (almost) empty test plan.");
+  if (caseCount === 0 && nodeCount > 1) {
+    warnings.push("no leaf node carries steps/expected \u2014 the plan has no executable cases");
+  }
+  for (const w of warnings) log.warn(`testcases: ${w}`);
+  return {
+    profile: result.profile,
+    root,
+    nodeCount,
+    caseCount,
+    priorities,
+    depth,
+    warnings,
+    notes: result.notes ?? null
+  };
+}
+function countNodes3(node) {
+  return 1 + node.children.reduce((acc, c) => acc + countNodes3(c), 0);
+}
+function treeDepth2(node) {
+  return 1 + node.children.reduce((acc, c) => Math.max(acc, treeDepth2(c)), 0);
+}
+function renderTestcasesMarkdown(prepared, meta) {
+  const lines = [];
+  lines.push(`# Edsger Manual Test Cases`);
+  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(
+    `| Test cases | ${prepared.caseCount} (${PRIORITY_ORDER.map((p) => `${prepared.priorities[p]} ${p}`).join(", ")}) |`
+  );
+  lines.push(`| Nodes | ${prepared.nodeCount} (depth ${prepared.depth}) |`);
+  lines.push(`| Standard sources | ${meta.layers.join(" \u2192 ")} |`);
+  lines.push(`| Model | ${meta.model} |`);
+  lines.push(`| Generated | ${meta.generatedAt} |`);
+  lines.push("");
+  lines.push(`## ${prepared.root.title}`);
+  if (prepared.root.summary && prepared.root.summary !== prepared.profile.summary) {
+    lines.push("");
+    lines.push(prepared.root.summary);
+  }
+  lines.push("");
+  for (const child of prepared.root.children) renderNode2(lines, child, 0);
+  if (prepared.notes) {
+    lines.push("");
+    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");
+}
+function renderNode2(lines, node, indent2) {
+  const pad = "  ".repeat(indent2);
+  const files = node.files.length ? ` ${node.files.map((f) => `\`${f}\``).join(" ")}` : "";
+  const summary = node.summary ? ` \u2014 ${node.summary}` : "";
+  if (isCase(node)) {
+    const prio = node.priority ? ` \`${node.priority}\`` : "";
+    lines.push(`${pad}- [ ] **${node.title}**${prio}${summary}${files}`);
+    const sub = "  ".repeat(indent2 + 1);
+    if (node.preconditions.length) {
+      lines.push(`${sub}- Preconditions: ${node.preconditions.join("; ")}`);
+    }
+    for (const [i, step] of node.steps.entries()) {
+      lines.push(`${sub}- Step ${i + 1}: ${step}`);
+    }
+    if (node.expected) lines.push(`${sub}- Expected: ${node.expected}`);
+  } else {
+    lines.push(`${pad}- **${node.title}**${summary}${files}`);
+  }
+  for (const child of node.children) renderNode2(lines, child, indent2 + 1);
+}
+
+// src/commands/testcases.ts
+async function runTestcasesGenerate(opts) {
+  const { config, path: configPath } = loadConfig(opts.cwd);
+  const configDir = configPath ? join12(configPath, "..") : opts.cwd;
+  const resolved = resolveStandard("testcases", opts, config, configDir);
+  const standard = resolved.standard;
+  log.info(
+    `Deriving manual test cases for ${pc11.bold(basename5(opts.cwd))} with ${pc11.bold(standard.name)} (languages: ${resolved.languages.join(", ") || "generic"})`
+  );
+  log.debug(`standard layers: ${resolved.layers.join(" \u2192 ")}`);
+  const prompt = buildTestcasesPrompt(standard, opts.cwd, opts.focus);
+  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: TestcasesResultSchema.shape,
+    systemPromptAppend: "You are Edsger, a staff-level QA engineer writing a manual test plan for a human tester who has never read the code. You derive every test case strictly from behaviour that exists in the repository you inspect: real commands, flags, routes, screens, and error branches, with exact steps and one verifiable expected result each. Never invent behaviour that is not in the code. 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 = prepareTestcases(result, { repo: basename5(opts.cwd) });
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const runId = generatedAt.replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  const git = gitInfo(opts.cwd);
+  const md = renderTestcasesMarkdown(prepared, {
+    repo: basename5(opts.cwd),
+    languages: resolved.languages,
+    layers: resolved.layers,
+    generatedAt,
+    model: opts.model
+  });
+  const jsonReport = {
+    schema: "edsger.testcases/1",
+    runId,
+    generatedAt,
+    model: opts.model,
+    repo: basename5(opts.cwd),
+    git,
+    languages: resolved.languages,
+    standard: { name: standard.name, version: standard.version, layers: resolved.layers },
+    profile: prepared.profile,
+    root: prepared.root,
+    nodeCount: prepared.nodeCount,
+    caseCount: prepared.caseCount,
+    priorities: prepared.priorities,
+    depth: prepared.depth,
+    focus: opts.focus ?? null,
+    notes: prepared.notes,
+    costUsd
+  };
+  const historyRecord = {
+    runId,
+    generatedAt,
+    commit: git.commit,
+    branch: git.branch,
+    dirty: git.dirty,
+    model: opts.model,
+    standardVersion: standard.version,
+    nodeCount: prepared.nodeCount,
+    caseCount: prepared.caseCount,
+    priorities: prepared.priorities,
+    depth: prepared.depth,
+    costUsd
+  };
+  if (!opts.noWrite && !opts.dryRun) {
+    const baseDir = join12(opts.cwd, opts.out);
+    const mdOut = md + "\n";
+    const jsonOut = JSON.stringify(jsonReport, null, 2) + "\n";
+    const runDir = join12(baseDir, "runs", runId);
+    mkdirSync6(runDir, { recursive: true });
+    writeFileSync7(join12(runDir, "testcases.json"), jsonOut, "utf8");
+    writeFileSync7(join12(runDir, "testcases.md"), mdOut, "utf8");
+    writeFileSync7(join12(baseDir, "testcases.json"), jsonOut, "utf8");
+    writeFileSync7(join12(baseDir, "testcases.md"), mdOut, "utf8");
+    appendFileSync5(join12(baseDir, "history.jsonl"), JSON.stringify(historyRecord) + "\n", "utf8");
+    log.success(
+      `Test plan written to ${pc11.bold(join12(opts.out, "testcases.md"))} ${pc11.dim(`(run archived at ${join12(opts.out, "runs", runId)})`)}`
+    );
+  }
+  printSummary6(prepared, numTurns, costUsd);
+  if (opts.json) process.stdout.write(JSON.stringify(jsonReport, null, 2) + "\n");
+  return 0;
+}
+function printSummary6(prepared, numTurns, costUsd) {
+  const tally = PRIORITY_ORDER.filter((p) => prepared.priorities[p] > 0).map((p) => `${prepared.priorities[p]} ${p}`).join(", ");
+  log.heading(
+    `${prepared.root.title} \u2014 ${prepared.caseCount} cases${tally ? ` (${tally})` : ""}, ${prepared.nodeCount} nodes, depth ${prepared.depth}`
+  );
+  const line = (node, indent2) => {
+    const cases = countCases(node);
+    const suffix = cases ? pc11.dim(` (${cases} case${cases === 1 ? "" : "s"})`) : "";
+    process.stderr.write(`${indent2}${pc11.cyan("\u2022")} ${node.title}${suffix}
+`);
+  };
+  for (const branch of prepared.root.children) line(branch, "  ");
+  log.step(`${numTurns} turns \xB7 ~$${costUsd.toFixed(3)}`);
+}
+function countCases(node) {
+  return (isCase(node) ? 1 : 0) + node.children.reduce((acc, c) => acc + countCases(c), 0);
+}
+async function runTestcasesServe(opts) {
+  const testcasesDir = join12(opts.cwd, opts.dir);
+  const viewerDir = findTestcasesViewerDir();
+  return startViewerServer({
+    viewerDir,
+    indexFile: "testcases.html",
+    dataRoute: "/edsger-testcases.json",
+    getData: () => assembleTestcasesData(testcasesDir),
+    port: opts.port,
+    host: opts.host,
+    open: opts.open,
+    emptyHint: hasData(assembleTestcasesData(testcasesDir)) ? void 0 : `No test-case data in ${opts.dir} yet \u2014 run \`edsger testcases\` first.`
+  });
+}
+async function runTestcasesReport(opts) {
+  const testcasesDir = join12(opts.cwd, opts.dir);
+  const data = assembleTestcasesData(testcasesDir);
+  if (!hasData(data)) {
+    log.error(`No test-case data in ${opts.dir}. Run \`edsger testcases\` first.`);
+    return 1;
+  }
+  const html = renderTestcasesSingleFile(readTestcasesViewerSingleTemplate(), data);
+  const out = isAbsolute6(opts.html) ? opts.html : join12(opts.cwd, opts.html);
+  mkdirSync6(dirname6(out), { recursive: true });
+  writeFileSync7(out, html, "utf8");
+  log.success(
+    `Wrote self-contained test-case viewer to ${pc11.bold(opts.html)} ${pc11.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 existsSync5,
-  mkdirSync as mkdirSync6,
+  mkdirSync as mkdirSync7,
   readFileSync as readFileSync3,
   readdirSync as readdirSync3,
   rmSync as rmSync2,
   statSync as statSync3,
-  writeFileSync as writeFileSync7
+  writeFileSync as writeFileSync8
 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join12 } from "path";
-import pc11 from "picocolors";
+import { join as join13 } from "path";
+import pc12 from "picocolors";
 var MANAGED = ["benchmark", "audit", "pr-review", "pr-resolve"];
 function targetSkillsDir(scope) {
-  return scope.global ? join12(homedir2(), ".claude", "skills") : join12(scope.cwd, ".claude", "skills");
+  return scope.global ? join13(homedir2(), ".claude", "skills") : join13(scope.cwd, ".claude", "skills");
 }
 function sourceSkillsDir() {
-  return join12(findBundledAssetsDir(), "skills");
+  return join13(findBundledAssetsDir(), "skills");
 }
 async function runSkillsInstall(opts) {
   const assetsDir = findBundledAssetsDir();
@@ -2687,20 +3136,20 @@ async function runSkillsInstall(opts) {
     return 1;
   }
   const dest = targetSkillsDir(opts);
-  mkdirSync6(dest, { recursive: true });
-  const available = readdirSync3(src).filter((n) => existsSync5(join12(src, n, "SKILL.md")));
+  mkdirSync7(dest, { recursive: true });
+  const available = readdirSync3(src).filter((n) => existsSync5(join13(src, n, "SKILL.md")));
   let installed = 0;
   for (const name of available) {
-    const outDir = join12(dest, name);
+    const outDir = join13(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(join12(src, name), outDir, { recursive: true });
-    const skillFile = join12(outDir, "SKILL.md");
+    cpSync(join13(src, name), outDir, { recursive: true });
+    const skillFile = join13(outDir, "SKILL.md");
     const rewritten = readFileSync3(skillFile, "utf8").split("${CLAUDE_PLUGIN_ROOT}").join(assetsDir);
-    writeFileSync7(skillFile, rewritten, "utf8");
+    writeFileSync8(skillFile, rewritten, "utf8");
     installed++;
     log.success(`installed /${name}`);
   }
@@ -2708,7 +3157,7 @@ async function runSkillsInstall(opts) {
     log.info("Nothing installed.");
     return 0;
   }
-  log.heading(`Installed ${installed} skill(s) into ${pc11.bold(dest)}`);
+  log.heading(`Installed ${installed} skill(s) into ${pc12.bold(dest)}`);
   log.step(`scope: ${opts.global ? "user (all projects)" : "this project"}`);
   log.step(`standards: ${assetsDir}`);
   log.step("Open Claude Code and run /benchmark, /audit, /pr-review, or /pr-resolve.");
@@ -2718,7 +3167,7 @@ async function runSkillsUninstall(opts) {
   const dest = targetSkillsDir(opts);
   let removed = 0;
   for (const name of MANAGED) {
-    const dir = join12(dest, name);
+    const dir = join13(dest, name);
     if (existsSync5(dir)) {
       rmSync2(dir, { recursive: true, force: true });
       removed++;
@@ -2735,13 +3184,13 @@ async function runSkillsList(opts) {
   ]) {
     const dir = targetSkillsDir(scope);
     const present = MANAGED.filter((n) => {
-      const p = join12(dir, n, "SKILL.md");
+      const p = join13(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(`  ${pc11.green("\u2713")} /${n}
+    if (present.length) for (const n of present) process.stderr.write(`  ${pc12.green("\u2713")} /${n}
 `);
-    else process.stderr.write(`  ${pc11.dim("(none installed)")}
+    else process.stderr.write(`  ${pc12.dim("(none installed)")}
 `);
   }
   return 0;
@@ -2979,6 +3428,57 @@ mindmap.command("report").description("Export a self-contained HTML mind-map vie
     })
   );
 });
+var testcases = program.command("testcases").alias("test-cases").description(
+  "Derive & browse a manual test-case plan (Workflowy-style outline) for a repo \u2014 how a human should test it, not automated code tests"
+);
+addGlobalOptions(
+  testcases.command("generate", { isDefault: true }).description("Analyze the repository and derive the manual test-case plan").option("--out <dir>", "test-plan output directory (relative to repo)", ".edsger/testcases").option("--no-write", "do not write test-plan files into the repo").option("--focus <text>", "area or feature the plan should concentrate its depth on").option("--serve", "open the test-case viewer after generating")
+).action(
+  async (opts) => {
+    await guard(async () => {
+      const g = toGlobal(opts);
+      const code = await runTestcasesGenerate({
+        ...g,
+        out: opts.out,
+        noWrite: opts.write === false,
+        focus: opts.focus
+      });
+      if (code === 0 && opts.serve) {
+        return runTestcasesServe({
+          cwd: g.cwd,
+          dir: opts.out,
+          port: 4581,
+          host: "127.0.0.1",
+          open: true
+        });
+      }
+      return code;
+    });
+  }
+);
+testcases.command("serve").description("Serve the test-case viewer locally").option("-C, --cwd <dir>", "repository directory").option("--dir <dir>", "test-plan output directory (relative to repo)", ".edsger/testcases").option("--port <n>", "port to listen on", "4581").option("--host <host>", "host to bind", "127.0.0.1").option("--no-open", "do not open the browser automatically").action(
+  async (opts) => {
+    await guard(
+      () => runTestcasesServe({
+        cwd: resolve2(opts.cwd ?? process.cwd()),
+        dir: opts.dir,
+        port: Number.parseInt(opts.port, 10) || 4581,
+        host: opts.host,
+        open: opts.open !== false
+      })
+    );
+  }
+);
+testcases.command("report").description("Export a self-contained HTML test-case viewer (data inlined) for sharing").option("-C, --cwd <dir>", "repository directory").option("--dir <dir>", "test-plan output directory (relative to repo)", ".edsger/testcases").option("--html <path>", "output HTML file path", "edsger-testcases.html").option("--open", "open the exported file after writing").action(async (opts) => {
+  await guard(
+    () => runTestcasesReport({
+      cwd: resolve2(opts.cwd ?? process.cwd()),
+      dir: opts.dir,
+      html: opts.html,
+      open: Boolean(opts.open)
+    })
+  );
+});
 addGlobalOptions(
   program.command("pr-review").description("Review a pull request against the review standard (requires gh)").argument("<pr>", "PR number, URL, or branch").option("--repo <owner/repo>", "target repository (defaults to current)").option("--post", "submit the review to GitHub (otherwise preview only)")
 ).action(async (pr, opts) => {
@@ -3029,18 +3529,20 @@ program.addHelpText(
   "after",
   `
 Examples:
-  ${pc12.dim("$")} edsger benchmark
-  ${pc12.dim("$")} edsger benchmark -C ./my-repo --json
-  ${pc12.dim("$")} edsger audit                ${pc12.dim("# nitpick the whole repo, report issues")}
-  ${pc12.dim("$")} edsger audit --fail-on high ${pc12.dim("# CI gate: fail on high/critical findings")}
-  ${pc12.dim("$")} edsger diagram              ${pc12.dim("# generate diagrams for the current repo")}
-  ${pc12.dim("$")} edsger diagram --serve      ${pc12.dim("# \u2026and open them in the browser")}
-  ${pc12.dim("$")} edsger diagram report --html diagrams.html
-  ${pc12.dim("$")} edsger mindmap              ${pc12.dim("# implementation mind map of the repo")}
-  ${pc12.dim("$")} edsger mindmap --serve      ${pc12.dim("# \u2026browse it Workflowy-style")}
-  ${pc12.dim("$")} edsger pr-review 123 --post
-  ${pc12.dim("$")} edsger pr-resolve 123 --instruction "fix the failing test" --push
-  ${pc12.dim("$")} edsger skills install   ${pc12.dim("# enable /benchmark etc. in Claude Code")}
+  ${pc13.dim("$")} edsger benchmark
+  ${pc13.dim("$")} edsger benchmark -C ./my-repo --json
+  ${pc13.dim("$")} edsger audit                ${pc13.dim("# nitpick the whole repo, report issues")}
+  ${pc13.dim("$")} edsger audit --fail-on high ${pc13.dim("# CI gate: fail on high/critical findings")}
+  ${pc13.dim("$")} edsger diagram              ${pc13.dim("# generate diagrams for the current repo")}
+  ${pc13.dim("$")} edsger diagram --serve      ${pc13.dim("# \u2026and open them in the browser")}
+  ${pc13.dim("$")} edsger diagram report --html diagrams.html
+  ${pc13.dim("$")} edsger mindmap              ${pc13.dim("# implementation mind map of the repo")}
+  ${pc13.dim("$")} edsger mindmap --serve      ${pc13.dim("# \u2026browse it Workflowy-style")}
+  ${pc13.dim("$")} edsger testcases            ${pc13.dim("# manual test-case plan for the repo")}
+  ${pc13.dim("$")} edsger testcases --serve    ${pc13.dim("# \u2026browse the plan Workflowy-style")}
+  ${pc13.dim("$")} edsger pr-review 123 --post
+  ${pc13.dim("$")} edsger pr-resolve 123 --instruction "fix the failing test" --push
+  ${pc13.dim("$")} edsger skills install   ${pc13.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.
 `