@qa-gentic/stlc-agents 1.0.16 → 1.0.18

package/bin/postinstall.js

@@ -52,7 +52,15 @@ const info = (s) => console.log(`${C.cyan}→${C.reset}  ${s}`);
 const warn = (s) => console.log(`${C.yellow}⚠${C.reset}  ${s}`);
 const d    = (s) => `${C.dim}${s}${C.reset}`;
 
-console.log(`\n${b("QA STLC Agents")} v${pkg.version} — post-install\n`);
+console.log(`
+${b("QA STLC Agents")} v${pkg.version} — post-install
+
+${d("This npm package includes:")}
+  • Five Python MCP servers for Azure DevOps + Jira Cloud
+  • Skill files for AI coding agents (Claude Code, Copilot, Cursor, Windsurf)
+  • ORCHESTRATION_RULES.md — reference guide for multi-step QA workflows
+  • Command-line tools: qa-stlc init, qa-stlc scaffold, qa-stlc skills, etc.
+`);
 
 // ── 1. Find Python ────────────────────────────────────────────────────────────
 const pythonCandidates = ["python3", "python"];
@@ -84,7 +92,23 @@ if (!python) {
   }
 }
 
-// ── 3. Print next-step instructions ──────────────────────────────────────────
+// ── 3. Activate cost tracking on MCP servers ─────────────────────────────
+info("Activating cost tracking on MCP servers...");
+const costPatch = spawnSync(
+  python,
+  ["-m", "stlc_agents.shared.install_hook"],
+  { encoding: "utf8", stdio: "pipe" }
+);
+if (costPatch.status === 0) {
+  // Print each output line through our TTY writer
+  (costPatch.stdout || "").split("\n").filter(Boolean).forEach((l) => console.log(l));
+  ok("Cost tracking active — every tool call will log tokens + cost");
+} else {
+  warn("Cost tracking patch skipped (run manually: python -m stlc_agents.shared.install_hook)");
+  if (costPatch.stderr) console.log(d(costPatch.stderr.slice(0, 300)));
+}
+ 
+// ── 4. Print next-step instructions ──────────────────────────────────────────
 console.log(`
 ${b("Next steps")} — run these inside your project root:
 

package/bin/qa-stlc.js

@@ -22,6 +22,7 @@ const cmdSkills     = require("../src/cli/cmd-skills");
 const cmdMcpConfig  = require("../src/cli/cmd-mcp-config");
 const cmdVerify     = require("../src/cli/cmd-verify");
 const cmdScaffold   = require("../src/cli/cmd-scaffold");
+const cmdCost = require("../src/cli/cmd-cost");
 
 program
   .name("qa-stlc")
@@ -83,6 +84,28 @@ program
   .option("--no-install",  "Skip npm install after scaffolding")
   .action(cmdScaffold);
 
+  program
+  .command("cost")
+  .description(
+    "Show token usage and cost for stlc-agents pipeline sessions.\n" +
+    "Reads logs from ~/.qa-stlc/cost-*.jsonl written on every MCP tool call.\n\n" +
+    "Model detection order (first match wins):\n" +
+    "  1. STLC_CODING_AGENT_MODEL env var     (explicit override)\n" +
+    "  2. ANTHROPIC_MODEL env var             (set automatically by Claude Code)\n" +
+    "  3. GITHUB_COPILOT_MODEL env var        (set by Copilot if configured)\n" +
+    "  4. ~/.qa-stlc/agent-model file         (saved by --set-model)\n" +
+    "  5. claude-sonnet-4-6                   (default fallback)\n\n" +
+    "Claude Code users: no setup needed — model is detected automatically.\n" +
+    "Cursor / Windsurf users: run  qa-stlc cost --set-model <model-id>  once."
+  )
+  .option("--all",              "Show all sessions (default: last session only)")
+  .option("--session <id>",     "Show a specific session by ID")
+  .option("--json",             "Output raw JSON instead of a formatted table")
+  .option("--set-model <model>","Save your coding agent model for accurate pricing.\n" +
+    "                             e.g. claude-opus-4-6 | gpt-4o | claude-sonnet-4-6")
+  .option("--model-help",       "Explain model detection and all ways to configure it")
+  .action(cmdCost);
+  
 // ── Quick-start hint appended to every --help output ─────────────────────────
 program.addHelpText("after", `
 Quick Start (run once in your project root):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qa-gentic/stlc-agents",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "QA STLC Agents — five MCP servers + skills for AI-powered test case, Gherkin, Playwright generation, and Helix-QA file writing against Azure DevOps and Jira Cloud. Full pipeline for both: fetch → test cases → Gherkin → Playwright → Helix-QA. Works with Claude Code, GitHub Copilot, Cursor, Windsurf.",
   "keywords": [
     "playwright",
@@ -37,11 +37,24 @@
     "src/",
     "skills/",
     ".github/agents/",
-    "README.md"
+    "README.md",
+    "ORCHESTRATION_RULES.md"
   ],
   "scripts": {
     "postinstall": "node ./bin/postinstall.js"
   },
+  "_comment": "Diff to apply to package.json — add the cost command to qa-stlc.js",
+
+  "diff": {
+    "bin/qa-stlc.js": {
+      "add_require": "const cmdCost = require('../src/cli/cmd-cost');",
+      "add_command": {
+        "after": "// ── scaffold (or any existing last command) ──────────────────────────────",
+        "insert": "\n// ── cost ─────────────────────────────────────────────────────────────────\nprogram\n  .command('cost')\n  .description('Show token usage and cost for the current or past sessions.\\n' +\n    'Reads session logs from ~/.qa-stlc/cost-*.jsonl\\n' +\n    'Written automatically by the MCP servers on every tool call.')\n  .option('--all', 'Show all sessions (default: last session only)')\n  .option('--session <id>', 'Show a specific session by ID')\n  .option('--json', 'Output raw JSON')\n  .action(cmdCost);\n"
+      }
+    }
+  },
+  "full_command_to_add_to_qa-stlc.js": "// ── cost ─────────────────────────────────────────────────────────────────\nprogram\n  .command('cost')\n  .description(\n    'Show token usage and cost for the current or past pipeline sessions.\\n' +\n    'Reads logs from ~/.qa-stlc/cost-*.jsonl written by the MCP servers.\\n' +\n    'Each MCP tool call logs tokens, cost, and latency automatically.'\n  )\n  .option('--all', 'Show all sessions (not just the last one)')\n  .option('--session <id>', 'Show a specific session by its ID')\n  .option('--json', 'Emit raw JSON instead of a formatted table')\n  .action(cmdCost);",
   "dependencies": {
     "commander": "^12.0.0",
     "which": "^4.0.0"

package/skills/write-helix-files/SKILL.md

@@ -47,6 +47,12 @@ When(/^the user enters "([^"]*)" in the username field$/, async function (value:
 If `generate_playwright_code` produced regex patterns, use `pre_validate_cucumber_steps`
 to identify them, then convert to Cucumber expressions before calling `write_helix_files`.
 
+**HARD STOP 4 — Cucumber config: append only, never create.**
+If any Cucumber config file exists (`src/config/cucumber.config.ts` or project-root
+`cucumber.js`), only append new profiles—never create a new file.
+`write_helix_files` will automatically skip profile creation if the file does not
+exist, to prevent orphaned config files from being left behind.
+
 ---
 
 Place files produced by `qa-playwright-generator` into a local Helix-QA

package/src/cli/cmd-cost.js

@@ -0,0 +1,253 @@
+/**
+ * cmd-cost.js — `qa-stlc cost`
+ *
+ * Read session cost logs from ~/.qa-stlc/cost-*.jsonl and print a report.
+ * Also handles --set-model to persist the coding agent model preference.
+ *
+ * Usage:
+ *   qa-stlc cost                          # last session
+ *   qa-stlc cost --all                    # all sessions
+ *   qa-stlc cost --session <id>           # specific session
+ *   qa-stlc cost --json                   # raw JSON output
+ *   qa-stlc cost --set-model <model-id>   # save model for Cursor/Windsurf users
+ *
+ * Model detection order (mirrors cost_tracker.py):
+ *   STLC_CODING_AGENT_MODEL env var
+ *   → ANTHROPIC_MODEL env var  (Claude Code sets this automatically)
+ *   → GITHUB_COPILOT_MODEL env var
+ *   → ~/.qa-stlc/agent-model  (saved by --set-model)
+ *   → "claude-sonnet-4-6"  (default)
+ */
+
+"use strict";
+
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+
+const LOG_DIR   = path.join(os.homedir(), ".qa-stlc");
+const PREF_FILE = path.join(LOG_DIR, "agent-model");
+
+const C = {
+  reset:  "\x1b[0m", bold:   "\x1b[1m",
+  dim:    "\x1b[2m", cyan:   "\x1b[36m",
+  green:  "\x1b[32m", yellow: "\x1b[33m",
+};
+const b   = (s) => `${C.bold}${s}${C.reset}`;
+const dim = (s) => `${C.dim}${s}${C.reset}`;
+const grn = (s) => `${C.green}${s}${C.reset}`;
+const cyn = (s) => `${C.cyan}${s}${C.reset}`;
+
+function fmtTok(n) { return n >= 1000 ? `${(n/1000).toFixed(1)}K` : String(n); }
+function fmtUsd(n) { return `$${n.toFixed(6)}`; }
+function fmtMs(n)  { return `${n}ms`; }
+
+// ── Model preference helpers ───────────────────────────────────────────────
+
+const KNOWN_MODELS = {
+  // Anthropic
+  "claude-sonnet-4-6":         "$3/$15 per MTok",
+  "claude-opus-4-6":           "$5/$25 per MTok",
+  "claude-opus-4-7":           "$5/$25 per MTok",
+  "claude-haiku-4-5-20251001": "$1/$5 per MTok",
+  "claude-sonnet-4-20250514":  "$3/$15 per MTok",
+  // OpenAI / Copilot
+  "gpt-4o":                    "$2.50/$10 per MTok",
+  "gpt-4o-mini":               "$0.15/$0.60 per MTok",
+};
+
+function saveModelPref(modelId) {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+  fs.writeFileSync(PREF_FILE, modelId.trim(), "utf8");
+}
+
+function readModelPref() {
+  try {
+    if (fs.existsSync(PREF_FILE)) return fs.readFileSync(PREF_FILE, "utf8").trim();
+  } catch (_) {}
+  return null;
+}
+
+function printModelHelp() {
+  console.log(`\n  ${b("Coding agent model for cost tracking")}\n`);
+  console.log(`  ${dim("Model is detected automatically in this order:")}`);
+  console.log(`  1. STLC_CODING_AGENT_MODEL  env var  ${dim("(explicit override, always wins)")}`);
+  console.log(`  2. ANTHROPIC_MODEL          env var  ${dim("(set automatically by Claude Code ✓ zero config)")}`);
+  console.log(`  3. GITHUB_COPILOT_MODEL     env var  ${dim("(set by Copilot if configured)")}`);
+  console.log(`  4. ~/.qa-stlc/agent-model   file     ${dim("(saved by qa-stlc cost --set-model)")}`);
+  console.log(`  5. claude-sonnet-4-6               ${dim("(default fallback)")}\n`);
+
+  const saved = readModelPref();
+  if (saved) {
+    console.log(`  ${grn("✓")}  Currently saved: ${b(saved)}  ${dim("(~/.qa-stlc/agent-model)")}\n`);
+  }
+
+  console.log(`  ${b("Known models:")}`);
+  for (const [id, rate] of Object.entries(KNOWN_MODELS)) {
+    console.log(`    ${id.padEnd(36)} ${dim(rate)}`);
+  }
+
+  console.log(`\n  ${b("To set for Cursor / Windsurf / any agent:")}`);
+  console.log(`  ${cyn("Option A — save once (recommended):")}`);
+  console.log(`    qa-stlc cost --set-model claude-opus-4-6\n`);
+  console.log(`  ${cyn("Option B — shell profile (applies to all projects):")}`);
+  console.log(`    echo 'export STLC_CODING_AGENT_MODEL=claude-opus-4-6' >> ~/.zshrc\n`);
+  console.log(`  ${cyn("Option C — .mcp.json env block (project-level):")}`);
+  console.log(`    "qa-gherkin-generator": {`);
+  console.log(`      "command": "/path/to/qa-gherkin-generator",`);
+  console.log(`      "env": { "STLC_CODING_AGENT_MODEL": "claude-opus-4-6" }`);
+  console.log(`    }\n`);
+  console.log(`  ${cyn("Option D — .env file in project root:")}`);
+  console.log(`    STLC_CODING_AGENT_MODEL=claude-opus-4-6\n`);
+  console.log(`  ${dim("Claude Code users: no action needed.")}`);
+  console.log(`  ${dim("ANTHROPIC_MODEL is passed through automatically via qa-stlc mcp-config.")}\n`);
+}
+
+// ── Log reading ────────────────────────────────────────────────────────────
+
+function readLogs() {
+  if (!fs.existsSync(LOG_DIR)) return [];
+  return fs.readdirSync(LOG_DIR)
+    .filter((f) => f.startsWith("cost-") && f.endsWith(".jsonl"))
+    .sort()
+    .map((f) => {
+      const file = path.join(LOG_DIR, f);
+      const records = fs.readFileSync(file, "utf8")
+        .split("\n").filter(Boolean).map((l) => JSON.parse(l));
+      return {
+        file,
+        sessionId: f.replace(/^cost-/, "").replace(/\.jsonl$/, ""),
+        records,
+      };
+    });
+}
+
+// ── Printing ───────────────────────────────────────────────────────────────
+
+function printSession(sess) {
+  const { sessionId, records } = sess;
+  if (!records.length) return;
+
+  const byServer = {};
+  let totalCost = 0, totalTokens = 0;
+  for (const r of records) {
+    const k = r.server || "unknown";
+    if (!byServer[k]) byServer[k] = { calls: 0, tokens: 0, cost: 0 };
+    byServer[k].calls++;
+    byServer[k].tokens += r.estimated_tokens || 0;
+    byServer[k].cost   += r.cost_usd || 0;
+    totalCost   += r.cost_usd || 0;
+    totalTokens += r.estimated_tokens || 0;
+  }
+
+  const model  = records[0]?.model || "unknown";
+  const source = records[0]?.model_source || "";
+  const method = records.some((r) => r.token_method === "estimated")
+    ? "estimated (payload chars÷4)" : "exact";
+  const ts    = records[0]?.timestamp?.slice(0, 19).replace("T", " ") || "";
+  const tsEnd = records[records.length - 1]?.timestamp?.slice(0, 19).replace("T", " ") || "";
+
+  console.log(`\n${"═".repeat(68)}`);
+  console.log(b(`  stlc-agents · Cost Report  ·  ${sessionId}`));
+  console.log(`${"═".repeat(68)}`);
+  console.log(dim(`  ${ts} → ${tsEnd}`));
+  console.log(dim(`  Model: ${model}  (detected via: ${source})`));
+  console.log(dim(`  Token method: ${method}`));
+
+  // Per-server
+  console.log(`\n  ${"Server".padEnd(30)} ${"Calls".padStart(6)} ${"~Tokens".padStart(10)} ${"Cost (USD)".padStart(14)}`);
+  console.log(`  ${"─".repeat(60)}`);
+  for (const [svr, d] of Object.entries(byServer)) {
+    console.log(
+      `  ${cyn(svr.padEnd(30))} ${String(d.calls).padStart(6)} ` +
+      `${fmtTok(d.tokens).padStart(10)} ${grn(fmtUsd(d.cost).padStart(14))}`
+    );
+  }
+
+  // Per-step
+  console.log(`\n  ${"Step detail"}`);
+  console.log(`  ${"─".repeat(68)}`);
+  for (const r of records) {
+    console.log(
+      `  ${(r.server || "?").padEnd(26)} ${(r.tool || "?").padEnd(36)} ` +
+      `${fmtTok(r.estimated_tokens || 0).padStart(6)}  ` +
+      `${grn(fmtUsd(r.cost_usd || 0))}  ${fmtMs(r.latency_ms || 0)}  ` +
+      dim(`[${r.token_method || "?"}]`)
+    );
+  }
+
+  // Totals
+  console.log(`\n  ${"─".repeat(68)}`);
+  console.log(`  ${"Total tokens".padEnd(40)} ${fmtTok(totalTokens).padStart(10)}`);
+  console.log(`  ${b("Total cost".padEnd(40))} ${grn(fmtUsd(totalCost))}`);
+  console.log(dim(`  Log: ${sess.file}`));
+  console.log(`${"═".repeat(68)}\n`);
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+module.exports = async function cost(opts) {
+
+  // --set-model: save model preference for Cursor/Windsurf users
+  if (opts.setModel) {
+    const modelId = opts.setModel.trim();
+    saveModelPref(modelId);
+    const rate = KNOWN_MODELS[modelId];
+    console.log(`\n  ${grn("✓")}  Model saved: ${b(modelId)}`);
+    if (rate) console.log(`     Pricing: ${dim(rate)}`);
+    else      console.log(`     ${dim("(unknown model — pricing may show $0.000000, add to pricing.py)")}`);
+    console.log(`     Written to: ${dim(PREF_FILE)}`);
+    console.log(`\n  This preference is used by all stlc-agents servers in all projects.`);
+    console.log(`  Override per-project via STLC_CODING_AGENT_MODEL in .env or .mcp.json.\n`);
+    return;
+  }
+
+  // --model-help: explain how model detection works
+  if (opts.modelHelp) {
+    printModelHelp();
+    return;
+  }
+
+  const sessions = readLogs();
+
+  if (!sessions.length) {
+    console.log(`\n  No cost logs found in ${LOG_DIR}`);
+    console.log(`  Run any qa-stlc MCP tool call to start tracking.\n`);
+    return;
+  }
+
+  if (opts.json) {
+    const all = opts.all ? sessions : [sessions[sessions.length - 1]];
+    console.log(JSON.stringify(all, null, 2));
+    return;
+  }
+
+  if (opts.session) {
+    const found = sessions.find((s) => s.sessionId === opts.session);
+    if (!found) {
+      console.log(`\n  Session not found: ${opts.session}`);
+      console.log(`  Available: ${sessions.map((s) => s.sessionId).join(", ")}\n`);
+      return;
+    }
+    printSession(found);
+    return;
+  }
+
+  if (opts.all) {
+    for (const s of sessions) printSession(s);
+    const allRecords  = sessions.flatMap((s) => s.records);
+    const grandTotal  = allRecords.reduce((a, r) => a + (r.cost_usd || 0), 0);
+    const grandTokens = allRecords.reduce((a, r) => a + (r.estimated_tokens || 0), 0);
+    console.log(`${"═".repeat(68)}`);
+    console.log(b(`  All sessions — grand total`));
+    console.log(`${"═".repeat(68)}`);
+    console.log(`  Sessions    : ${sessions.length}`);
+    console.log(`  Total tokens: ${fmtTok(grandTokens)}`);
+    console.log(b(`  TOTAL COST  : ${grn(fmtUsd(grandTotal))}`));
+    console.log(`${"═".repeat(68)}\n`);
+    return;
+  }
+
+  // Default: last session
+  printSession(sessions[sessions.length - 1]);
+};

package/src/cli/cmd-init.js

@@ -1,7 +1,7 @@
 /**
  * cmd-init.js — `qa-stlc init`
  *
- * Full bootstrap: install Python agents + skills + MCP config.
+ * Full bootstrap: install Python agents + skills + ORCHESTRATION_RULES.md + MCP config.
  * Accepts --integration <ado|jira|both>.  When omitted, reads
  * ~/.qa-stlc/integration (written by postinstall) or prompts interactively.
  */
@@ -89,7 +89,23 @@ module.exports = async function init(opts) {
   }
   ok("qa-gentic-stlc-agents installed.");
 
-  // ── 4. Install skills ─────────────────────────────────────────────────────
+  // ── 4. Copy ORCHESTRATION_RULES.md to project root ─────────────────────────
+  info("Installing ORCHESTRATION_RULES.md to project root…");
+  try {
+    const npmPkgDir = path.join(path.dirname(require.resolve("@qa-gentic/stlc-agents/package.json")));
+    const srcRules = path.join(npmPkgDir, "ORCHESTRATION_RULES.md");
+    const destRules = path.join(process.cwd(), "ORCHESTRATION_RULES.md");
+    if (fs.existsSync(srcRules)) {
+      fs.copyFileSync(srcRules, destRules);
+      ok("ORCHESTRATION_RULES.md copied to project root.");
+    } else {
+      warn("ORCHESTRATION_RULES.md not found in npm package (expected in development).");
+    }
+  } catch (e) {
+    // Silently skip if not available (common in dev environments before full build)
+  }
+
+  // ── 5. Install skills ─────────────────────────────────────────────────────
   info("Installing skills…");
   const skillTarget = opts.vscode ? "vscode" : "claude";
   await cmdSkills({ target: skillTarget, integration });
@@ -132,6 +148,7 @@ ${C.bold}Setup complete.${C.reset}
   ${C.dim}Integration:${C.reset} ${C.bold}${integration}${C.reset}
   ${C.dim}MCP config :${C.reset} ${mcpLocation}
   ${C.dim}Skills     :${C.reset} ${skillsLocation}
+  ${C.dim}Rules      :${C.reset} ORCHESTRATION_RULES.md ${C.dim}(project root — reference for multi-step workflows)${C.reset}
 
 ${C.bold}Start Playwright MCP${C.reset} ${C.dim}(keep running in a separate terminal):${C.reset}