@roopesh.yadava/qa-pack 1.4.0 → 1.5.0

package/claude/skills/qa-agent/toolkit/qa-toolkit.cjs

@@ -0,0 +1,705 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * qa-toolkit — deterministic helper CLI for qa-pack skills.
+ *
+ * Every command here does work that would otherwise cost an LLM a full file
+ * Read (or worse, an in-context reasoning pass) to accomplish: parsing
+ * markdown tables, hashing DOM snapshots, scoring string similarity, walking
+ * git history, aggregating dozens of product_context files. None of that
+ * needs a model — it needs a parser. Skills shell out here via Bash and read
+ * only the one-line (or few-line) result, never the underlying file.
+ *
+ * No npm dependencies (qa-pack ships none) — Node core only.
+ * Always invoked from the repo root, e.g.:
+ *   node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs <command> [--flags]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const ROOT = process.cwd();
+const PRODUCT_CONTEXT_ROOT = path.join(ROOT, '.claude', 'skills', 'qa-agent', 'product_context');
+const OUTPUTS_DIR = path.join(ROOT, 'outputs');
+const TRUST_THRESHOLD = 5;
+
+// ── generic fs / arg helpers ─────────────────────────────────────────────
+
+function productDir(product) { return path.join(PRODUCT_CONTEXT_ROOT, product); }
+function contextFile(product) { return path.join(productDir(product), 'context.md'); }
+function ensureDir(dir) { fs.mkdirSync(dir, { recursive: true }); }
+function todayStr() { return new Date().toISOString().slice(0, 10); }
+
+function readFileSafe(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+}
+function readJson(p, fallback) {
+  const raw = readFileSafe(p);
+  if (raw === null) return fallback;
+  try { return JSON.parse(raw); } catch { return fallback; }
+}
+function writeJson(p, obj) {
+  ensureDir(path.dirname(p));
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
+}
+function readStdinSync() {
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+function listProductFolders() {
+  if (!fs.existsSync(PRODUCT_CONTEXT_ROOT)) return [];
+  return fs.readdirSync(PRODUCT_CONTEXT_ROOT, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(PRODUCT_CONTEXT_ROOT, e.name, 'context.md')))
+    .map((e) => e.name);
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok.startsWith('--')) {
+      const key = tok.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) args[key] = true;
+      else { args[key] = next; i++; }
+    }
+  }
+  return args;
+}
+
+function requireArgs(args, names) {
+  const missing = names.filter((n) => args[n] === undefined);
+  if (missing.length) {
+    console.log(`ERROR: missing required flag(s): ${missing.map((n) => '--' + n).join(', ')}`);
+    process.exit(1);
+  }
+}
+
+// ── markdown table parsing (context.md tables) ───────────────────────────
+
+function extractSectionLines(content, headingText) {
+  const lines = content.split('\n');
+  const headingRe = new RegExp('^##\\s+' + headingText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*$', 'i');
+  const start = lines.findIndex((l) => headingRe.test(l.trim()));
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s/.test(lines[i])) { end = i; break; }
+  }
+  return lines.slice(start + 1, end);
+}
+
+function splitRow(line) {
+  return line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((s) => s.trim());
+}
+
+function parseMarkdownTable(sectionLines) {
+  const tableLines = sectionLines.filter((l) => l.trim().startsWith('|'));
+  if (tableLines.length < 2) return { headers: [], rows: [] };
+  const headers = splitRow(tableLines[0]);
+  const rows = tableLines.slice(2).map((line) => {
+    const cells = splitRow(line);
+    const obj = {};
+    headers.forEach((h, i) => { obj[h] = cells[i] !== undefined ? cells[i] : ''; });
+    return obj;
+  });
+  return { headers, rows };
+}
+
+function isPlaceholderRow(row) {
+  const values = Object.values(row);
+  if (!values.length) return true;
+  if (/^—+$/.test(values[0] || '')) return true;
+  const joined = values.join(' ');
+  return /\{[^}]+\}/.test(joined) || /No bugs filed yet/i.test(joined);
+}
+
+/** Returns { found: bool, rows: [...] } — found=false means no context.md at all yet. */
+function getTable(product, headingText) {
+  const content = readFileSafe(contextFile(product));
+  if (content === null) return { found: false, rows: [] };
+  const section = extractSectionLines(content, headingText);
+  if (!section) return { found: true, rows: [] };
+  const { rows } = parseMarkdownTable(section);
+  return { found: true, rows: rows.filter((r) => !isPlaceholderRow(r)) };
+}
+
+function getProductInfo(product) {
+  const content = readFileSafe(contextFile(product));
+  const info = {};
+  if (!content) return info;
+  const patterns = {
+    name: /\*\*Product Name\*\*:\s*(.+)/i,
+    appUrl: /\*\*App URL\*\*:\s*(.+)/i,
+    env: /\*\*Environment\*\*:\s*(.+)/i,
+    key: /\*\*Jira Project Key\*\*:\s*(.+)/i,
+  };
+  for (const [k, re] of Object.entries(patterns)) {
+    const m = content.match(re);
+    if (m) info[k] = m[1].trim();
+  }
+  return info;
+}
+
+// ── list-products ─────────────────────────────────────────────────────────
+
+function cmdListProducts() {
+  const products = listProductFolders();
+  if (!products.length) { console.log('NO_PRODUCTS'); return; }
+  products.forEach((p) => console.log(p));
+}
+
+// ── get-bugs / get-runs (cheap reads — no LLM file parse needed) ─────────
+
+function cmdGetBugs(args) {
+  requireArgs(args, ['product']);
+  const { found, rows } = getTable(args.product, 'Known Bugs');
+  if (!found) return console.log('NO_CONTEXT_FILE');
+  if (!rows.length) return console.log('NO_BUGS');
+  rows.forEach((r) => console.log([r['Bug ID'], r['Title'], r['Severity'], r['Status'], r['Card']].join(' | ')));
+}
+
+function cmdGetSelectors(args) {
+  requireArgs(args, ['product']);
+  const { found, rows } = getTable(args.product, 'Element Selectors');
+  if (!found) return console.log('NO_CONTEXT_FILE');
+  const filtered = args.url ? rows.filter((r) => (r['Page URL'] || '').includes(args.url)) : rows;
+  if (!filtered.length) return console.log('NO_SELECTORS');
+  filtered.forEach((r) =>
+    console.log([r['Element Label'], r['Page URL'], r['Locator'], r['Method'], r['data-testid'], r['Card']].join(' | '))
+  );
+}
+
+function cmdGetRuns(args) {
+  requireArgs(args, ['product']);
+  const { found, rows } = getTable(args.product, 'Runs Log');
+  if (!found) return console.log('NO_CONTEXT_FILE');
+  const filtered = args.phase
+    ? rows.filter((r) => (r['Phase'] || '').toLowerCase().includes(String(args.phase).toLowerCase()))
+    : rows;
+  if (!filtered.length) return console.log('NO_RUNS');
+  filtered.forEach((r) =>
+    console.log([r['Date'], r['Card'], r['Phase'], r['Outcome'], r['Bugs Filed'], r['Reuse %'], r['Notes']].join(' | '))
+  );
+}
+
+// ── fingerprint: DOM fingerprint cache ────────────────────────────────────
+
+function hashList(items) {
+  const sorted = [...new Set(items)].sort();
+  return crypto.createHash('sha1').update(sorted.join('\n')).digest('hex').slice(0, 16);
+}
+
+function cmdFingerprint(args) {
+  requireArgs(args, ['product', 'url']);
+  const testids = String(args.testids || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const file = path.join(productDir(args.product), 'dom-fingerprints.json');
+  const store = readJson(file, {});
+  const newHash = hashList(testids);
+  const prev = store[args.url];
+  const changed = !prev || prev.hash !== newHash;
+  store[args.url] = { hash: newHash, count: testids.length, updatedAt: todayStr() };
+  writeJson(file, store);
+
+  if (!prev) console.log('NEW — no prior fingerprint for this page. Run full DOM discovery.');
+  else if (changed) {
+    console.log(`CHANGED — DOM signature differs from ${prev.updatedAt} (${prev.count} → ${testids.length} testids). Re-discover this page.`);
+  } else {
+    console.log(`UNCHANGED — matches fingerprint from ${prev.updatedAt}. Skip DOM re-discovery, reuse cached selectors.`);
+  }
+}
+
+// ── pii-scan: PII / secrets scan before any Jira post ─────────────────────
+
+const PII_PATTERNS = [
+  { name: 'email', re: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g },
+  { name: 'ssn', re: /\b\d{3}-\d{2}-\d{4}\b/g },
+  { name: 'credit_card', re: /\b\d{4}[ -]\d{4}[ -]\d{4}[ -]\d{1,4}\b|\b\d{15,16}\b/g },
+  { name: 'aws_key', re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { name: 'openai_key', re: /\bsk-[A-Za-z0-9]{20,}\b/g },
+  { name: 'github_token', re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g },
+  { name: 'slack_token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  { name: 'gcp_key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { name: 'jwt', re: /\bey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
+  { name: 'generic_secret_assignment', re: /\b(api[_-]?key|secret|password|passwd|token)\b\s*[:=]\s*["']?[^\s"'<]{6,}/gi },
+];
+
+function redact(match) {
+  const s = String(match);
+  if (s.length <= 4) return '*'.repeat(s.length);
+  return s.slice(0, 2) + '*'.repeat(Math.max(s.length - 4, 3)) + s.slice(-2);
+}
+
+function cmdPiiScan(args) {
+  let text;
+  if (args.file) {
+    text = readFileSafe(args.file);
+    if (text === null) { console.log(`ERROR: cannot read ${args.file}`); process.exit(1); }
+  } else {
+    text = readStdinSync();
+  }
+  const findings = [];
+  for (const { name, re } of PII_PATTERNS) {
+    const matches = text.match(re) || [];
+    if (matches.length) findings.push({ name, count: matches.length, sample: redact(matches[0]) });
+  }
+  if (!findings.length) return console.log('CLEAN');
+  console.log(`FLAGGED: ${findings.length} pattern type(s) detected — confirm with the user before posting`);
+  findings.forEach((f) => console.log(`  - ${f.name}: ${f.count} match(es), e.g. "${f.sample}"`));
+}
+
+// ── dup-bug: duplicate-bug detector ───────────────────────────────────────
+
+function tokenize(s) {
+  return String(s || '').toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/).filter((w) => w.length > 2);
+}
+
+function diceSimilarity(a, b) {
+  const setA = new Set(tokenize(a));
+  const setB = new Set(tokenize(b));
+  if (!setA.size || !setB.size) return 0;
+  let overlap = 0;
+  for (const w of setA) if (setB.has(w)) overlap++;
+  return (2 * overlap) / (setA.size + setB.size);
+}
+
+function resolveTextArg(args, inlineKey, fileKey) {
+  if (args[fileKey]) {
+    const content = readFileSafe(args[fileKey]);
+    if (content === null) { console.log(`ERROR: cannot read ${args[fileKey]}`); process.exit(1); }
+    return content.trim();
+  }
+  return args[inlineKey];
+}
+
+function cmdDupBug(args) {
+  requireArgs(args, ['product']);
+  const summary = resolveTextArg(args, 'summary', 'summary-file');
+  if (!summary) { console.log('ERROR: --summary or --summary-file required'); process.exit(1); }
+  const { found, rows } = getTable(args.product, 'Known Bugs');
+  if (!found || !rows.length) return console.log('NO_DUPLICATE_FOUND — no bug history yet');
+  const scored = rows
+    .map((r) => ({ id: r['Bug ID'], title: r['Title'], status: r['Status'], score: diceSimilarity(summary, r['Title']) }))
+    .filter((r) => r.score >= 0.35)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 3);
+  if (!scored.length) return console.log('NO_DUPLICATE_FOUND');
+  scored.forEach((r) => console.log(`POSSIBLE_DUPLICATE: ${r.id} (score ${r.score.toFixed(2)}, status ${r.status}) — "${r.title}"`));
+}
+
+// ── cost-estimate: pre-run cost estimate ──────────────────────────────────
+
+function tryReadTrackingLog() {
+  const dir = process.env.QA_TRACKING_DIR;
+  if (!dir) return null;
+  return readJson(path.join(dir, 'token_usage_log.json'), null);
+}
+
+function avgTokensForCards(tracking, cardIds) {
+  if (!Array.isArray(tracking)) return null;
+  const entries = tracking.filter((e) => e && cardIds.has(e.card));
+  const totals = entries.map((e) => (e.input_tokens || 0) + (e.output_tokens || 0)).filter((v) => v > 0);
+  if (!totals.length) return null;
+  return Math.round(totals.reduce((a, b) => a + b, 0) / totals.length);
+}
+
+function cmdCostEstimate(args) {
+  requireArgs(args, ['product']);
+  const { found, rows } = getTable(args.product, 'Runs Log');
+  if (!found || !rows.length) {
+    console.log(`No run history yet for ${args.product} — first run, no estimate available.`);
+    return;
+  }
+  const phase = args.phase ? String(args.phase) : '';
+  const relevant = phase ? rows.filter((r) => (r['Phase'] || '').toLowerCase().includes(phase.toLowerCase())) : rows;
+  const pool = relevant.length ? relevant : rows;
+  const n = pool.length;
+
+  const reuseVals = pool.map((r) => parseFloat((r['Reuse %'] || '').replace('%', ''))).filter((v) => !isNaN(v));
+  const avgReuse = reuseVals.length ? Math.round(reuseVals.reduce((a, b) => a + b, 0) / reuseVals.length) : null;
+  const bugRuns = pool.filter((r) => (r['Bugs Filed'] || '').trim() && r['Bugs Filed'] !== '—').length;
+
+  const tracking = tryReadTrackingLog();
+  const avgTok = tracking ? avgTokensForCards(tracking, new Set(pool.map((r) => r['Card']))) : null;
+  const tokenLine = avgTok ? `, ~${avgTok.toLocaleString()} tokens/run avg` : '';
+
+  console.log(
+    `Estimated for ${args.product}${phase ? ' (Phase ' + phase + ')' : ''}: based on ${n} past run(s), ` +
+    `avg reuse ${avgReuse !== null ? avgReuse + '%' : 'n/a'}${tokenLine}. ${bugRuns}/${n} past runs found bugs.`
+  );
+}
+
+// ── risk-score: risk-based test ordering ──────────────────────────────────
+
+function gitChangedFiles(days) {
+  const res = spawnSync('git', ['log', `--since=${days} days ago`, '--name-only', '--pretty=format:'], {
+    cwd: ROOT, encoding: 'utf8',
+  });
+  if (res.status !== 0 || !res.stdout) return [];
+  return res.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+function cmdRiskScore(args) {
+  requireArgs(args, ['product', 'modules']);
+  const modules = String(args.modules).split(',').map((s) => s.trim()).filter(Boolean);
+  if (!modules.length) { console.log('ERROR: --modules "a,b,c" required'); process.exit(1); }
+  const changedFiles = gitChangedFiles(180);
+  const { rows: bugRows } = getTable(args.product, 'Known Bugs');
+
+  const scored = modules
+    .map((mod) => {
+      const kw = mod.toLowerCase();
+      const churn = changedFiles.filter((f) => f.toLowerCase().includes(kw)).length;
+      const bugs = (bugRows || []).filter((r) => (r['Title'] || '').toLowerCase().includes(kw)).length;
+      return { mod, churn, bugs, risk: churn * 0.6 + bugs * 3 };
+    })
+    .sort((a, b) => b.risk - a.risk);
+
+  scored.forEach((s, i) =>
+    console.log(`${i + 1}. ${s.mod} — risk ${s.risk.toFixed(1)} (${s.churn} commits/180d, ${s.bugs} known bug${s.bugs === 1 ? '' : 's'})`)
+  );
+}
+
+// ── trust: trust ratchet on auto-approve ──────────────────────────────────
+
+function trustFile(product) { return path.join(productDir(product), 'trust.json'); }
+
+function cmdTrustRecord(args) {
+  requireArgs(args, ['product', 'gate', 'result']);
+  const file = trustFile(args.product);
+  const store = readJson(file, {});
+  if (!store[args.gate]) store[args.gate] = { clean: 0, edited: 0, streak: 0 };
+  if (args.result === 'clean') { store[args.gate].clean++; store[args.gate].streak++; }
+  else { store[args.gate].edited++; store[args.gate].streak = 0; }
+  writeJson(file, store);
+  console.log(`Recorded — ${args.gate}: streak ${store[args.gate].streak}, ${store[args.gate].clean} clean / ${store[args.gate].edited} edited total.`);
+}
+
+function cmdTrustStatus(args) {
+  requireArgs(args, ['product']);
+  const store = readJson(trustFile(args.product), {});
+  const gates = Object.keys(store);
+  if (!gates.length) return console.log('NOT_ELIGIBLE — no gate history yet for this product.');
+  const minStreak = Math.min(...gates.map((g) => store[g].streak || 0));
+  const summary = gates.map((g) => `${g}: streak ${store[g].streak}`).join(', ');
+  if (minStreak >= TRUST_THRESHOLD) {
+    console.log(`ELIGIBLE — ${summary}. All gates clean for ${minStreak}+ consecutive runs; offer to raise autonomy for this product.`);
+  } else {
+    console.log(`NOT_ELIGIBLE — ${summary} (needs ${TRUST_THRESHOLD} consecutive clean approvals to qualify).`);
+  }
+}
+
+// ── locator: self-improving locator memory ────────────────────────────────
+
+function locatorFile(product) { return path.join(productDir(product), 'locator-learnings.md'); }
+
+function ensureLocatorFile(product) {
+  const file = locatorFile(product);
+  if (!fs.existsSync(file)) {
+    ensureDir(path.dirname(file));
+    fs.writeFileSync(
+      file,
+      `# Locator Learnings — ${product}\n` +
+      `Auto-maintained by qa-toolkit.cjs — do not edit by hand.\n\n` +
+      `| Page | Element | Failed Locator | Working Locator | Reason | Card | Date |\n` +
+      `|------|---------|-----------------|------------------|--------|------|------|\n`
+    );
+  }
+  return file;
+}
+
+// Markdown-table-safe cell: locators legitimately contain "|" (xpath unions especially) —
+// escape it rather than let it silently corrupt the table's column count on re-parse.
+function tableCell(v) {
+  return String(v ?? '').replace(/\|/g, '&#124;').replace(/\n/g, ' ').trim();
+}
+
+function cmdLocatorRecord(args) {
+  // Free-text locator strings routinely contain quotes/brackets that are unsafe to inline
+  // into a shell command — accept a JSON --file as the safe path; individual --flags remain
+  // for short, technical values a skill is confident contain no special characters.
+  let fields = args;
+  if (args.file) {
+    const parsed = readJson(args.file, null);
+    if (!parsed) { console.log(`ERROR: cannot read/parse JSON at ${args.file}`); process.exit(1); }
+    fields = parsed;
+  }
+  const { product, page, element, failed, fixed, reason, card } = fields;
+  if (!product || !page || !element || !fixed) {
+    console.log('ERROR: --product --page --element --fixed required (or an equivalent --file JSON)');
+    process.exit(1);
+  }
+  const file = ensureLocatorFile(product);
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  const key = `${page}|||${element}`.toLowerCase();
+  const rowLine = `| ${tableCell(page)} | ${tableCell(element)} | ${tableCell(failed || '—')} | ${tableCell(fixed)} | ${tableCell(reason || '—')} | ${tableCell(card || '—')} | ${todayStr()} |`;
+
+  const filtered = lines.filter((l) => {
+    if (!l.trim().startsWith('|')) return true;
+    const cells = splitRow(l);
+    if (cells.length < 3 || cells[0] === 'Page') return true; // keep header row
+    return `${cells[0]}|||${cells[1]}`.toLowerCase() !== key;
+  });
+  while (filtered.length && filtered[filtered.length - 1].trim() === '') filtered.pop();
+  filtered.push(rowLine);
+  fs.writeFileSync(file, filtered.join('\n') + '\n');
+  console.log(`Locator learning recorded: ${element} on ${page} → ${fixed}`);
+}
+
+function cmdLocatorQuery(args) {
+  requireArgs(args, ['product']);
+  const content = readFileSafe(locatorFile(args.product));
+  if (!content) return console.log('NONE — no locator learnings yet for this product.');
+  const dataLines = content.split('\n').filter(
+    (l) => l.trim().startsWith('|') && !l.includes('---') && !l.trim().startsWith('| Page |')
+  );
+  const matches = args.page ? dataLines.filter((l) => l.toLowerCase().includes(String(args.page).toLowerCase())) : dataLines;
+  if (!matches.length) return console.log('NONE — no learnings for this page yet.');
+  matches.forEach((l) => console.log(l.trim()));
+}
+
+// ── shared stats collector (dashboard / digest / roi) ─────────────────────
+
+function pctList(rows, field) {
+  return rows.map((r) => parseFloat((r[field] || '').replace('%', ''))).filter((v) => !isNaN(v));
+}
+function avg(nums) {
+  return nums.length ? Math.round(nums.reduce((a, b) => a + b, 0) / nums.length) : null;
+}
+function bugsFiledCount(row) {
+  const bf = (row['Bugs Filed'] || '').trim();
+  return !bf || bf === '—' ? 0 : bf.split(',').filter(Boolean).length;
+}
+
+function collectProductStats(product) {
+  const info = getProductInfo(product);
+  const runs = getTable(product, 'Runs Log').rows;
+  const bugs = getTable(product, 'Known Bugs').rows;
+  const flows = getTable(product, 'Covered Flows').rows;
+  const openBugs = bugs.filter((b) => !/closed|done|fixed|resolved/i.test(b['Status'] || '')).length;
+  return {
+    product,
+    name: info.name || product,
+    env: info.env || '—',
+    runCount: runs.length,
+    bugCount: bugs.length,
+    openBugs,
+    flowCount: flows.length,
+    avgReuse: avg(pctList(runs, 'Reuse %')),
+    lastRun: runs.length ? runs[runs.length - 1] : null,
+    runs,
+  };
+}
+
+// ── dashboard: product health dashboard ───────────────────────────────────
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+function cmdDashboard() {
+  const products = listProductFolders();
+  if (!products.length) return console.log('NO_PRODUCTS — no product has run yet.');
+  const stats = products.map(collectProductStats).sort((a, b) => b.runCount - a.runCount);
+  const totalRuns = stats.reduce((a, s) => a + s.runCount, 0);
+  const totalOpenBugs = stats.reduce((a, s) => a + s.openBugs, 0);
+
+  const rows = stats.map((s) => `
+    <tr>
+      <td>${escapeHtml(s.name)}</td>
+      <td>${escapeHtml(s.env)}</td>
+      <td class="num">${s.runCount}</td>
+      <td class="num">${s.avgReuse !== null ? s.avgReuse + '%' : '—'}</td>
+      <td class="num">${s.flowCount}</td>
+      <td class="num ${s.openBugs > 0 ? 'warn' : ''}">${s.openBugs} / ${s.bugCount}</td>
+      <td>${s.lastRun ? escapeHtml(s.lastRun['Date'] + ' · ' + s.lastRun['Card']) : '—'}</td>
+    </tr>`).join('');
+
+  const html = `<!doctype html>
+<html><head><meta charset="utf-8"><title>QA Product Health Dashboard</title>
+<style>
+  :root{ --bg:#f4f5f2; --panel:#fff; --ink:#1c2420; --muted:#5b6659; --line:#dfe3d8; --warn:#a6472b; }
+  @media (prefers-color-scheme: dark){ :root{ --bg:#12160f; --panel:#181f16; --ink:#e8ece2; --muted:#93998c; --line:#2b342a; --warn:#e08767; } }
+  *{box-sizing:border-box} body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.5 -apple-system,Segoe UI,Roboto,sans-serif;padding:2.5rem 1.5rem}
+  .wrap{max-width:980px;margin:0 auto}
+  h1{font-size:1.5rem;margin:0 0 .25rem}
+  .meta{color:var(--muted);font-size:.85rem;margin-bottom:1.75rem}
+  .stats{display:flex;gap:1rem;margin-bottom:1.75rem;flex-wrap:wrap}
+  .stat{background:var(--panel);border:1px solid var(--line);border-radius:6px;padding:.85rem 1.1rem;min-width:140px}
+  .stat b{display:block;font-size:1.4rem} .stat span{color:var(--muted);font-size:.78rem;text-transform:uppercase;letter-spacing:.04em}
+  table{width:100%;border-collapse:collapse;background:var(--panel);border:1px solid var(--line);border-radius:6px;overflow:hidden}
+  th,td{padding:.6rem .8rem;border-bottom:1px solid var(--line);text-align:left;font-size:.88rem}
+  th{font-size:.72rem;text-transform:uppercase;letter-spacing:.04em;color:var(--muted)}
+  td.num{font-variant-numeric:tabular-nums;text-align:right} td.warn{color:var(--warn);font-weight:600}
+  tr:last-child td{border-bottom:none}
+  .wrap{overflow-x:auto}
+</style></head>
+<body><div class="wrap">
+  <h1>QA Product Health Dashboard</h1>
+  <div class="meta">Generated ${todayStr()} from ${products.length} product context file(s)</div>
+  <div class="stats">
+    <div class="stat"><b>${products.length}</b><span>Products</span></div>
+    <div class="stat"><b>${totalRuns}</b><span>Total runs</span></div>
+    <div class="stat"><b>${totalOpenBugs}</b><span>Open bugs</span></div>
+  </div>
+  <table>
+    <thead><tr><th>Product</th><th>Env</th><th>Runs</th><th>Avg reuse</th><th>Flows covered</th><th>Open / total bugs</th><th>Last run</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table>
+</div></body></html>`;
+
+  ensureDir(OUTPUTS_DIR);
+  fs.writeFileSync(path.join(OUTPUTS_DIR, 'dashboard.html'), html);
+  console.log(`Dashboard saved: outputs/dashboard.html (${products.length} products, ${totalRuns} runs, ${totalOpenBugs} open bugs)`);
+}
+
+// ── digest: QA weekly digest ───────────────────────────────────────────────
+
+function withinDays(dateStr, days) {
+  const d = new Date(dateStr);
+  if (isNaN(d.getTime())) return false;
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+  return d >= cutoff;
+}
+
+function cmdDigest(args) {
+  const days = parseInt(args.days, 10) || 7;
+  const products = listProductFolders();
+  if (!products.length) return console.log('NO_PRODUCTS');
+
+  let totalRuns = 0;
+  let totalBugs = 0;
+  const sections = [];
+  for (const product of products) {
+    const info = getProductInfo(product);
+    const runs = getTable(product, 'Runs Log').rows.filter((r) => withinDays(r['Date'], days));
+    if (!runs.length) continue;
+    totalRuns += runs.length;
+    const bugsFiled = runs.reduce((sum, r) => sum + bugsFiledCount(r), 0);
+    totalBugs += bugsFiled;
+    const avgReuse = avg(pctList(runs, 'Reuse %'));
+    sections.push(
+      `### ${info.name || product}\n- Runs: ${runs.length} (${runs.map((r) => r['Card']).join(', ')})\n` +
+      `- Bugs filed: ${bugsFiled}\n- Avg reuse: ${avgReuse !== null ? avgReuse + '%' : 'n/a'}\n`
+    );
+  }
+
+  const today = todayStr();
+  const md =
+    `# QA Weekly Digest — ${today}\n` +
+    `Window: last ${days} day(s) · ${sections.length}/${products.length} product(s) active\n\n` +
+    `**Totals:** ${totalRuns} run(s) · ${totalBugs} bug(s) filed\n\n` +
+    (sections.length ? sections.join('\n') : '_No runs recorded in this window._\n');
+
+  ensureDir(OUTPUTS_DIR);
+  const file = path.join(OUTPUTS_DIR, `qa-weekly-digest-${today}.md`);
+  fs.writeFileSync(file, md);
+  console.log(
+    `Digest saved: outputs/qa-weekly-digest-${today}.md — ${totalRuns} runs, ${totalBugs} bugs across ` +
+    `${sections.length} active product(s) in the last ${days} days.`
+  );
+}
+
+// ── roi: token-spend / ROI view ────────────────────────────────────────────
+
+function cmdRoi() {
+  const products = listProductFolders();
+  if (!products.length) return console.log('NO_PRODUCTS');
+
+  const tracking = tryReadTrackingLog();
+  const hasTracking = Array.isArray(tracking) && tracking.length > 0;
+
+  const rowsOut = [];
+  let totalRuns = 0;
+  let totalBugs = 0;
+  let totalTokens = 0;
+  let tokenRuns = 0;
+
+  for (const product of products) {
+    const runs = getTable(product, 'Runs Log').rows;
+    if (!runs.length) continue;
+    totalRuns += runs.length;
+    const bugsFiled = runs.reduce((sum, r) => sum + bugsFiledCount(r), 0);
+    totalBugs += bugsFiled;
+    const avgReuse = avg(pctList(runs, 'Reuse %'));
+
+    let avgTokens = null;
+    if (hasTracking) {
+      const cardIds = new Set(runs.map((r) => r['Card']));
+      const entries = tracking.filter((e) => e && cardIds.has(e.card));
+      const totals = entries.map((e) => (e.input_tokens || 0) + (e.output_tokens || 0)).filter((v) => v > 0);
+      if (totals.length) {
+        avgTokens = Math.round(totals.reduce((a, b) => a + b, 0) / totals.length);
+        totalTokens += totals.reduce((a, b) => a + b, 0);
+        tokenRuns += totals.length;
+      }
+    }
+    rowsOut.push({ product, runs: runs.length, bugsFiled, avgReuse, avgTokens });
+  }
+
+  const today = todayStr();
+  let md = `# QA Token-Spend / ROI View — ${today}\n\n`;
+  md += `| Product | Runs | Bugs found | Avg reuse | Avg tokens/run | Bugs per 1k tokens |\n`;
+  md += `|---|---|---|---|---|---|\n`;
+  for (const r of rowsOut) {
+    const bugsPer1k = r.avgTokens && r.bugsFiled ? ((r.bugsFiled / r.runs) / (r.avgTokens / 1000)).toFixed(2) : '—';
+    md += `| ${r.product} | ${r.runs} | ${r.bugsFiled} | ${r.avgReuse !== null ? r.avgReuse + '%' : '—'} | ` +
+      `${r.avgTokens !== null ? r.avgTokens.toLocaleString() : '—'} | ${bugsPer1k} |\n`;
+  }
+  md += `\n**Totals:** ${totalRuns} runs · ${totalBugs} bugs found`;
+  if (hasTracking && tokenRuns) {
+    md += ` · ${Math.round(totalTokens / tokenRuns).toLocaleString()} avg tokens/run across ${tokenRuns} tracked run(s)\n`;
+  } else {
+    md += `\n\n_Token columns require \`QA_TRACKING_DIR\` set in \`.env\` with an active token tracker — ` +
+      `showing coverage/bug metrics only until then._\n`;
+  }
+
+  ensureDir(OUTPUTS_DIR);
+  fs.writeFileSync(path.join(OUTPUTS_DIR, 'roi-report.md'), md);
+  console.log(
+    `ROI report saved: outputs/roi-report.md — ${totalRuns} runs, ${totalBugs} bugs` +
+    `${hasTracking ? ', token data included' : ' (token data unavailable — set QA_TRACKING_DIR to enable)'}.`
+  );
+}
+
+// ── dispatch ────────────────────────────────────────────────────────────
+
+function main() {
+  const [, , command, ...rest] = process.argv;
+  const args = parseArgs(rest);
+  const handlers = {
+    'list-products': cmdListProducts,
+    'get-bugs': cmdGetBugs,
+    'get-runs': cmdGetRuns,
+    'get-selectors': cmdGetSelectors,
+    fingerprint: cmdFingerprint,
+    'pii-scan': cmdPiiScan,
+    'dup-bug': cmdDupBug,
+    'cost-estimate': cmdCostEstimate,
+    'risk-score': cmdRiskScore,
+    'trust-record': cmdTrustRecord,
+    'trust-status': cmdTrustStatus,
+    'locator-record': cmdLocatorRecord,
+    'locator-query': cmdLocatorQuery,
+    dashboard: cmdDashboard,
+    digest: cmdDigest,
+    roi: cmdRoi,
+  };
+  const handler = handlers[command];
+  if (!handler) {
+    console.log(
+      'Usage: qa-toolkit.cjs <command> [--flags]\n' +
+      'Commands: list-products, get-bugs, get-runs, get-selectors, fingerprint, pii-scan, dup-bug,\n' +
+      '          cost-estimate, risk-score, trust-record, trust-status,\n' +
+      '          locator-record, locator-query, dashboard, digest, roi'
+    );
+    process.exit(command ? 1 : 0);
+  }
+  handler(args);
+}
+
+main();