@roopesh.yadava/qa-pack 1.5.0 → 1.6.0

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

@@ -17,11 +17,35 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
 const { spawnSync } = require('child_process');
 
 const ROOT = process.cwd();
+
+// ── .env loading ─────────────────────────────────────────────────────────
+// Every doc in the pack tells users to put QA_* config in `.env`, but this is a
+// plain `node` script invoked by skills via Bash — nothing exports that file into
+// the environment, and the pack ships no dotenv. Without this, every
+// `process.env.QA_*` read below is permanently undefined and the features gated
+// on them (report-run, token tracking) are silent no-ops no matter what the user
+// configures. Real env vars always win, so an explicit `export` still overrides.
+function loadDotEnv() {
+  let raw;
+  try { raw = fs.readFileSync(path.join(ROOT, '.env'), 'utf8'); } catch { return; }
+  for (const line of raw.split(/\r?\n/)) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!m) continue; // blank line, comment, or malformed — skip
+    let val = m[2].trim();
+    // strip one layer of matching quotes; leave inner content untouched
+    if (val.length >= 2 && ((val[0] === '"' && val.endsWith('"')) || (val[0] === "'" && val.endsWith("'")))) {
+      val = val.slice(1, -1);
+    }
+    if (process.env[m[1]] === undefined) process.env[m[1]] = val;
+  }
+}
+loadDotEnv();
 const PRODUCT_CONTEXT_ROOT = path.join(ROOT, '.claude', 'skills', 'qa-agent', 'product_context');
 const OUTPUTS_DIR = path.join(ROOT, 'outputs');
 const TRUST_THRESHOLD = 5;
@@ -365,11 +389,17 @@ function cmdRiskScore(args) {
 
 // ── trust: trust ratchet on auto-approve ──────────────────────────────────
 
-function trustFile(product) { return path.join(productDir(product), 'trust.json'); }
+// `namespace` (optional) routes to trust.{namespace}.json instead of trust.json — full
+// isolation for a second automation surface (e.g. mobile-automation) on the same product,
+// so its gate streaks never enter the min() that decides an unrelated pipeline's eligibility.
+// Omitted → identical behavior to before this flag existed (trust.json, no callers changed).
+function trustFile(product, namespace) {
+  return path.join(productDir(product), namespace ? `trust.${namespace}.json` : 'trust.json');
+}
 
 function cmdTrustRecord(args) {
   requireArgs(args, ['product', 'gate', 'result']);
-  const file = trustFile(args.product);
+  const file = trustFile(args.product, args.namespace);
   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++; }
@@ -380,7 +410,7 @@ function cmdTrustRecord(args) {
 
 function cmdTrustStatus(args) {
   requireArgs(args, ['product']);
-  const store = readJson(trustFile(args.product), {});
+  const store = readJson(trustFile(args.product, args.namespace), {});
   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));
@@ -500,9 +530,12 @@ function escapeHtml(s) {
   return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
 }
 
-function cmdDashboard() {
+function cmdDashboard(args) {
   const products = listProductFolders();
-  if (!products.length) return console.log('NO_PRODUCTS — no product has run yet.');
+  if (!products.length) {
+    if (args && args.json) return console.log(JSON.stringify({ products: 0, totalRuns: 0, totalOpenBugs: 0, repos: [] }));
+    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);
@@ -553,6 +586,21 @@ function cmdDashboard() {
 
   ensureDir(OUTPUTS_DIR);
   fs.writeFileSync(path.join(OUTPUTS_DIR, 'dashboard.html'), html);
+
+  if (args && args.json) {
+    console.log(JSON.stringify({
+      products: products.length,
+      totalRuns,
+      totalOpenBugs,
+      htmlPath: 'outputs/dashboard.html',
+      repos: stats.map((s) => ({
+        product: s.product, name: s.name, env: s.env, runCount: s.runCount,
+        avgReuse: s.avgReuse, flowCount: s.flowCount, openBugs: s.openBugs, bugCount: s.bugCount,
+        lastRunDate: s.lastRun ? s.lastRun['Date'] : null, lastRunCard: s.lastRun ? s.lastRun['Card'] : null,
+      })),
+    }));
+    return;
+  }
   console.log(`Dashboard saved: outputs/dashboard.html (${products.length} products, ${totalRuns} runs, ${totalOpenBugs} open bugs)`);
 }
 
@@ -569,11 +617,15 @@ function withinDays(dateStr, days) {
 function cmdDigest(args) {
   const days = parseInt(args.days, 10) || 7;
   const products = listProductFolders();
-  if (!products.length) return console.log('NO_PRODUCTS');
+  if (!products.length) {
+    if (args && args.json) return console.log(JSON.stringify({ days, totalRuns: 0, totalBugs: 0, activeProducts: 0, totalProducts: 0, products: [] }));
+    return console.log('NO_PRODUCTS');
+  }
 
   let totalRuns = 0;
   let totalBugs = 0;
   const sections = [];
+  const productsOut = [];
   for (const product of products) {
     const info = getProductInfo(product);
     const runs = getTable(product, 'Runs Log').rows.filter((r) => withinDays(r['Date'], days));
@@ -582,10 +634,12 @@ function cmdDigest(args) {
     const bugsFiled = runs.reduce((sum, r) => sum + bugsFiledCount(r), 0);
     totalBugs += bugsFiled;
     const avgReuse = avg(pctList(runs, 'Reuse %'));
+    const cards = runs.map((r) => r['Card']);
     sections.push(
-      `### ${info.name || product}\n- Runs: ${runs.length} (${runs.map((r) => r['Card']).join(', ')})\n` +
+      `### ${info.name || product}\n- Runs: ${runs.length} (${cards.join(', ')})\n` +
       `- Bugs filed: ${bugsFiled}\n- Avg reuse: ${avgReuse !== null ? avgReuse + '%' : 'n/a'}\n`
     );
+    productsOut.push({ product, name: info.name || product, runCount: runs.length, cards, bugsFiled, avgReuse });
   }
 
   const today = todayStr();
@@ -598,6 +652,16 @@ function cmdDigest(args) {
   ensureDir(OUTPUTS_DIR);
   const file = path.join(OUTPUTS_DIR, `qa-weekly-digest-${today}.md`);
   fs.writeFileSync(file, md);
+
+  if (args && args.json) {
+    console.log(JSON.stringify({
+      days, totalRuns, totalBugs,
+      activeProducts: sections.length, totalProducts: products.length,
+      mdPath: `outputs/qa-weekly-digest-${today}.md`,
+      products: productsOut,
+    }));
+    return;
+  }
   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.`
@@ -606,9 +670,12 @@ function cmdDigest(args) {
 
 // ── roi: token-spend / ROI view ────────────────────────────────────────────
 
-function cmdRoi() {
+function cmdRoi(args) {
   const products = listProductFolders();
-  if (!products.length) return console.log('NO_PRODUCTS');
+  if (!products.length) {
+    if (args && args.json) return console.log(JSON.stringify({ totalRuns: 0, totalBugs: 0, hasTracking: false, rows: [] }));
+    return console.log('NO_PRODUCTS');
+  }
 
   const tracking = tryReadTrackingLog();
   const hasTracking = Array.isArray(tracking) && tracking.length > 0;
@@ -660,12 +727,125 @@ function cmdRoi() {
 
   ensureDir(OUTPUTS_DIR);
   fs.writeFileSync(path.join(OUTPUTS_DIR, 'roi-report.md'), md);
+
+  if (args && args.json) {
+    console.log(JSON.stringify({
+      totalRuns, totalBugs, hasTracking,
+      avgTokensPerRun: hasTracking && tokenRuns ? Math.round(totalTokens / tokenRuns) : null,
+      mdPath: 'outputs/roi-report.md',
+      rows: rowsOut,
+    }));
+    return;
+  }
   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)'}.`
   );
 }
 
+// ── report-run: optional team dashboard reporting (git-based, silent opt-in) ──
+//
+// Mirrors the QA_TRACKING_DIR convention (see SKILLS_CONTEXT.md "Token Tracking"):
+// unset config = silent no-op, never mention it, never retry, never break the run.
+// When configured, pushes one JSON file per run to a shared GitHub repo via the
+// Contents API (a plain create — no local git commit/push in the calling repo, no
+// read-modify-write race with other teammates' concurrent runs).
+
+function gitConfigValue(key) {
+  const res = spawnSync('git', ['config', key], { cwd: ROOT, encoding: 'utf8' });
+  return res.status === 0 ? res.stdout.trim() : '';
+}
+
+function currentRepoName() {
+  const remote = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: ROOT, encoding: 'utf8' });
+  if (remote.status === 0 && remote.stdout.trim()) {
+    return remote.stdout.trim().replace(/\.git$/, '').split(/[/:]/).pop();
+  }
+  return path.basename(ROOT);
+}
+
+async function cmdReportRun(args) {
+  const repo = process.env.QA_DASHBOARD_REPO;
+  const token = process.env.QA_DASHBOARD_TOKEN;
+  if (!repo || !token) return; // team dashboard not configured — silent no-op
+
+  // Only --skill and --outcome are universal. Half the skills in the pack have no
+  // Jira card at all (impacted-tests, k6-framework-scaffold, test-charter, and
+  // roam-testing when run without one) and some have no product context, so
+  // requiring either would make "log every skill" impossible to satisfy.
+  requireArgs(args, ['skill', 'outcome']);
+
+  // No freeform --notes flag: only short, structurally-constrained values (product/card/
+  // phase/outcome/bug IDs) are safe to inline into the caller's shell command — see the
+  // "Never inline arbitrary text" rule in SKILLS_CONTEXT.md.
+  const payload = {
+    product: args.product || currentRepoName(),
+    card: args.card || null,
+    // One record per skill execution. `skill` is what ran (manual-testing,
+    // automation, ...); `phase` stays for backward compat with records already
+    // in the dashboard repo, defaulting to the skill name when a caller omits it.
+    skill: args.skill,
+    phase: args.phase || args.skill,
+    outcome: args.outcome,
+    bugsFiled: String(args.bugs || '').split(',').map((s) => s.trim()).filter(Boolean),
+    reusePct: args.reuse !== undefined ? parseFloat(args.reuse) : null,
+    date: args.date || todayStr(),
+    // Display name only — never user.email. The dashboard repo is public, so an
+    // email here is published permanently in git history; the "runs by teammate"
+    // panel only ever needs a label. QA_DASHBOARD_AUTHOR overrides.
+    author: process.env.QA_DASHBOARD_AUTHOR || gitConfigValue('user.name') || os.userInfo().username,
+    repo: currentRepoName(),
+    reportedAt: new Date().toISOString(),
+  };
+
+  // These land in a URL path, so restrict them to a safe charset rather than
+  // trusting the caller — a stray `/` or `..` in a product name would otherwise
+  // write outside runs/ in the dashboard repo.
+  const seg = (v, fallback) => String(v || fallback).replace(/[^A-Za-z0-9._-]/g, '-').replace(/^[.-]+/, '') || fallback;
+  const filePath = `runs/${seg(payload.product, 'unknown')}/${payload.date}-${seg(payload.card, 'no-card')}-${seg(payload.skill, 'skill')}-${crypto.randomBytes(4).toString('hex')}.json`;
+  const content = Buffer.from(JSON.stringify(payload, null, 2)).toString('base64');
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5000);
+  try {
+    const res = await fetch(`https://api.github.com/repos/${repo}/contents/${filePath}`, {
+      method: 'PUT',
+      signal: controller.signal,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'Content-Type': 'application/json',
+        'User-Agent': 'qa-pack-toolkit',
+      },
+      body: JSON.stringify({ message: `run: ${payload.product} ${payload.card}`, content }),
+    });
+    // A 401 (dead/expired PAT — fine-grained tokens cap at 1 year), a 404 (wrong
+    // QA_DASHBOARD_REPO, or a token without Contents:write) and a success are all
+    // indistinguishable if the status is never read. Stay silent on stdout so a
+    // broken dashboard can't derail a QA run, but always leave a trace on disk.
+    if (!res.ok) reportRunFailure(args, `HTTP ${res.status} ${res.statusText} — ${(await res.text().catch(() => '')).slice(0, 200)}`);
+    else if (args.verbose) console.log(`report-run OK → ${repo}/${filePath}`);
+  } catch (err) {
+    reportRunFailure(args, err && err.name === 'AbortError' ? 'timed out after 5s' : String(err && err.message || err));
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// Failure trail for report-run. stdout stays clean (the calling skill must never
+// print or retry), so the evidence goes to outputs/ — already gitignored — and to
+// stdout only under --verbose, which is how you verify a fresh PAT once.
+function reportRunFailure(args, detail) {
+  const line = `${new Date().toISOString()} report-run failed: ${detail}\n`;
+  if (args.verbose) console.log(line.trim());
+  try {
+    ensureDir(OUTPUTS_DIR);
+    fs.appendFileSync(path.join(OUTPUTS_DIR, 'report-run-errors.log'), line);
+  } catch {
+    // last resort: swallow — a dashboard problem must never fail a QA run
+  }
+}
+
 // ── dispatch ────────────────────────────────────────────────────────────
 
 function main() {
@@ -688,6 +868,7 @@ function main() {
     dashboard: cmdDashboard,
     digest: cmdDigest,
     roi: cmdRoi,
+    'report-run': cmdReportRun,
   };
   const handler = handlers[command];
   if (!handler) {
@@ -695,11 +876,11 @@ function main() {
       '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'
+      '          locator-record, locator-query, dashboard, digest, roi, report-run'
     );
     process.exit(command ? 1 : 0);
   }
-  handler(args);
+  Promise.resolve(handler(args)).catch(() => {});
 }
 
 main();

package/claude/skills/roam-testing/SKILL.md

@@ -185,3 +185,22 @@ If yes: `Skill: test-charter`, pre-filled with the roam report path just saved.
 | A page 500s on load | Record as 🔴, do not retry, continue the loop |
 | Page cap hit with queue still non-empty | Stop cleanly, report `{visited} of {discovered}` coverage — never silently keep going |
 | `browser_network_requests` unavailable | Skip failed-request detection for that page, note it once in the report, continue |
+
+---
+
+## Final Step — Report to team dashboard (optional, silent)
+
+Always the last action of the run, after everything else has printed. This is a no-op
+unless `QA_DASHBOARD_REPO`/`QA_DASHBOARD_TOKEN` are set in `.env` — never print anything
+about it, never retry, never treat a non-zero exit as a run failure.
+
+```
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs report-run \
+  --skill roam-testing --product {PRODUCT_FOLDER} --card {CARD_ID, omit if none} \
+  --outcome {Pass|Fail|Partial} --bugs "{comma-separated bug IDs, or omit if none}"
+```
+A card is optional in this skill (Step 0 allows `skip`) — omit `--card` entirely when
+there isn't one rather than passing a placeholder. `report-run` takes only short, structurally-constrained values (product folder, card ID,
+skill name, outcome, bug IDs). It has no `--notes` flag — never inline freeform text such as
+a finding, a page title, or a bug description (see "Never inline arbitrary text" in
+`SKILLS_CONTEXT.md`).

package/claude/skills/test-charter/SKILL.md

@@ -298,3 +298,17 @@ TEST CHARTER PUBLISHED
   Published: [published_url or "URL not returned by API"]
   ✅ Uploaded to decision record
 ```
+
+---
+
+## Final Step — Report to team dashboard (optional, silent)
+
+Always the last action of the run, after everything else has printed. This is a no-op
+unless `QA_DASHBOARD_REPO`/`QA_DASHBOARD_TOKEN` are set in `.env` — never print anything
+about it, never retry, never treat a non-zero exit as a run failure.
+
+```
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs report-run \
+  --skill test-charter --outcome {Pass|Fail}
+```
+No product folder and no card — omit both flags.

package/claude/skills/ui-test-figma/SKILL.md

@@ -236,3 +236,18 @@ JIRA UPDATED
 ```
 
 Run `end + report + session` token close-out.
+
+---
+
+## Final Step — Report to team dashboard (optional, silent)
+
+Always the last action of the run, after everything else has printed. This is a no-op
+unless `QA_DASHBOARD_REPO`/`QA_DASHBOARD_TOKEN` are set in `.env` — never print anything
+about it, never retry, never treat a non-zero exit as a run failure.
+
+```
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs report-run \
+  --skill ui-test-figma --card {CARD_ID, omit if none} \
+  --outcome {Pass|Fail|Partial} --bugs "{comma-separated bug IDs, or omit if none}"
+```
+Omit `--product` (no product folder in this skill) and omit `--card` when no card was given.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roopesh.yadava/qa-pack",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "AI-powered QA agent skills for Claude Code — manual testing, BDD automation, accessibility, UI/Figma diff, bug reporting",
   "scripts": {
     "postinstall": "node bin/postinstall.js"

package/templates/.env.example

@@ -24,3 +24,16 @@ JIRA_API_TOKEN=
 # ── Optional: model-tier recommendation for qa-agent (see SKILLS_CONTEXT.md) ──
 # recommend (default) | off | subagent (advanced — see "Model Routing" in SKILLS_CONTEXT.md)
 # QA_MODEL_ROUTING=recommend
+
+# ── Optional: team QA dashboard (shared, git-based, no server to host) ────────
+# Point at the shared dashboard-data repo ("owner/repo") + a fine-grained PAT
+# scoped to only that repo with Contents: Read and write access.
+# When either is unset, runs are skipped silently — nothing is sent anywhere.
+# Once set, EVERY skill reports its own execution as its last step.
+# Note: if the dashboard repo is public, everything below is published permanently
+# in its git history — product folder names, Jira card IDs, bug IDs and the author
+# label. The author label is git config user.name (never your email); override it
+# here if you'd rather publish something else, e.g. a first name or initials.
+# QA_DASHBOARD_REPO=your-org/qa-dashboard-data
+# QA_DASHBOARD_TOKEN=
+# QA_DASHBOARD_AUTHOR=