@qa-gentic/stlc-agents 1.0.25 → 1.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qa-gentic/stlc-agents",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "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",

package/skills/generate-test-cases/SKILL.md

@@ -152,6 +152,11 @@ Each test case:
 - `steps` — array of `{ action, expected_result }` — at least 2 steps per TC
 - `priority` — 1=Critical, 2=High (default), 3=Medium, 4=Low
 
+**Automatic post-creation actions (server-side — no skill action required):**
+- Each `TestedBy-Forward` relation is created with `"attributes": {"comment": "STLC-Agent generated test case"}` — this comment appears in the Links tab Comments column in ADO.
+- The tag `STLCAgentTestCases` is appended to the parent work item (PBI/Bug/Feature).
+Both are best-effort; a failure does not roll back test case creation.
+
 ## Example tool call
 
 ```json

package/src/cli/cmd-cost.js

@@ -124,64 +124,88 @@ function readLogs() {
 
 // ── Printing ───────────────────────────────────────────────────────────────
 
+function fmtTokens(r) {
+  const n      = r.estimated_tokens || 0;
+  const exact  = r.token_method === "exact";
+  const prefix = exact ? "" : "~";
+  return prefix + fmtTok(n);
+}
+
 function printSession(sess) {
   const { sessionId, records } = sess;
   if (!records.length) return;
 
   const byServer = {};
-  let totalCost = 0, totalTokens = 0;
+  let totalCost = 0, totalExactTokens = 0, totalEstTokens = 0;
+  let hasExact = false, hasEst = false;
+
   for (const r of records) {
     const k = r.server || "unknown";
-    if (!byServer[k]) byServer[k] = { calls: 0, tokens: 0, cost: 0 };
+    if (!byServer[k]) byServer[k] = { calls: 0, tokens: 0, cost: 0, exact: false };
     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;
+    if (r.token_method === "exact") { byServer[k].exact = true; hasExact = true; }
+    else                             { hasEst = true; }
+    totalCost += r.cost_usd || 0;
+    if (r.token_method === "exact") totalExactTokens += r.estimated_tokens || 0;
+    else                             totalEstTokens  += 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 methodLabel = hasExact && hasEst ? "mixed (exact + estimated)"
+                    : hasExact           ? "exact (from API response)"
+                    :                      "estimated (payload chars÷4)";
+
+  const models  = [...new Set(records.map((r) => r.model).filter(Boolean))].join(", ");
+  const sources = [...new Set(records.map((r) => r.model_source).filter(Boolean))].join(", ");
   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(`\n${"═".repeat(72)}`);
   console.log(b(`  stlc-agents · Cost Report  ·  ${sessionId}`));
-  console.log(`${"═".repeat(68)}`);
+  console.log(`${"═".repeat(72)}`);
   console.log(dim(`  ${ts} → ${tsEnd}`));
-  console.log(dim(`  Model: ${model}  (detected via: ${source})`));
-  console.log(dim(`  Token method: ${method}`));
+  console.log(dim(`  Model(s): ${models}  (via: ${sources})`));
+  console.log(dim(`  Token method: ${methodLabel}`));
 
   // Per-server
-  console.log(`\n  ${"Server".padEnd(30)} ${"Calls".padStart(6)} ${"~Tokens".padStart(10)} ${"Cost (USD)".padStart(14)}`);
-  console.log(`  ${"─".repeat(60)}`);
+  console.log(`\n  ${"Server".padEnd(30)} ${"Calls".padStart(6)} ${"Tokens".padStart(10)} ${"Cost (USD)".padStart(14)}  Method`);
+  console.log(`  ${"─".repeat(70)}`);
   for (const [svr, d] of Object.entries(byServer)) {
+    const meth = d.exact ? "" : dim(" [est]");
+    const prefix = d.exact ? "" : "~";
     console.log(
       `  ${cyn(svr.padEnd(30))} ${String(d.calls).padStart(6)} ` +
-      `${fmtTok(d.tokens).padStart(10)} ${grn(fmtUsd(d.cost).padStart(14))}`
+      `${(prefix + fmtTok(d.tokens)).padStart(10)} ${grn(fmtUsd(d.cost).padStart(14))}${meth}`
     );
   }
 
   // Per-step
   console.log(`\n  ${"Step detail"}`);
-  console.log(`  ${"─".repeat(68)}`);
+  console.log(`  ${"─".repeat(72)}`);
   for (const r of records) {
+    const exact   = r.token_method === "exact";
+    const methTag = exact ? "" : dim(" [est]");
+    const cacheNote = (r.cache_write_tokens || r.cache_read_tokens)
+      ? dim(` cw=${r.cache_write_tokens||0} cr=${r.cache_read_tokens||0}`) : "";
+    const iters = r.iterations > 1 ? dim(` ×${r.iterations}`) : "";
     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 || "?"}]`)
+      `  ${(r.server || "?").padEnd(26)} ${(r.tool || "?").padEnd(34)} ` +
+      `${fmtTokens(r).padStart(8)}  ` +
+      `${grn(fmtUsd(r.cost_usd || 0))}  ${fmtMs(r.latency_ms || 0)}${methTag}${cacheNote}${iters}`
     );
   }
 
   // Totals
-  console.log(`\n  ${"─".repeat(68)}`);
-  console.log(`  ${"Total tokens".padEnd(40)} ${fmtTok(totalTokens).padStart(10)}`);
+  const totalTokens = totalExactTokens + totalEstTokens;
+  const tokenNote   = hasExact && hasEst
+    ? ` (${fmtTok(totalExactTokens)} exact + ~${fmtTok(totalEstTokens)} est)`
+    : hasExact ? " (exact)" : " (estimated)";
+  console.log(`\n  ${"─".repeat(72)}`);
+  console.log(`  ${"Total tokens".padEnd(40)} ${fmtTok(totalTokens).padStart(10)}${dim(tokenNote)}`);
   console.log(`  ${b("Total cost".padEnd(40))} ${grn(fmtUsd(totalCost))}`);
   console.log(dim(`  Log: ${sess.file}`));
-  console.log(`${"═".repeat(68)}\n`);
+  console.log(`${"═".repeat(72)}\n`);
 }
 
 // ── Main ───────────────────────────────────────────────────────────────────
@@ -235,16 +259,23 @@ module.exports = async function cost(opts) {
 
   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)}`);
+    const allRecords      = sessions.flatMap((s) => s.records);
+    const grandTotal      = allRecords.reduce((a, r) => a + (r.cost_usd || 0), 0);
+    const grandExact      = allRecords.filter((r) => r.token_method === "exact")
+                                      .reduce((a, r) => a + (r.estimated_tokens || 0), 0);
+    const grandEst        = allRecords.filter((r) => r.token_method !== "exact")
+                                      .reduce((a, r) => a + (r.estimated_tokens || 0), 0);
+    const grandTokens     = grandExact + grandEst;
+    const tokenBreakdown  = grandExact && grandEst
+      ? ` (${fmtTok(grandExact)} exact + ~${fmtTok(grandEst)} est)`
+      : grandExact ? " (exact)" : " (estimated)";
+    console.log(`${"═".repeat(72)}`);
     console.log(b(`  All sessions — grand total`));
-    console.log(`${"═".repeat(68)}`);
+    console.log(`${"═".repeat(72)}`);
     console.log(`  Sessions    : ${sessions.length}`);
-    console.log(`  Total tokens: ${fmtTok(grandTokens)}`);
+    console.log(`  Total tokens: ${fmtTok(grandTokens)}${dim(tokenBreakdown)}`);
     console.log(b(`  TOTAL COST  : ${grn(fmtUsd(grandTotal))}`));
-    console.log(`${"═".repeat(68)}\n`);
+    console.log(`${"═".repeat(72)}\n`);
     return;
   }
 

package/src/cli/cmd-init.js

@@ -80,14 +80,94 @@ module.exports = async function init(opts) {
 
   // ── 3. pip install qa-gentic-stlc-agents ──────────────────────────────────
   info("Installing qa-gentic-stlc-agents (pip)…");
-  const pip = spawnSync(python, ["-m", "pip", "install", "qa-gentic-stlc-agents>=1.0.1", "--quiet"], {
-    stdio: "inherit",
-    encoding: "utf8",
-  });
-  if (pip.status !== 0) {
-    die("pip install failed. Run manually: pip install qa-gentic-stlc-agents");
+
+  const IS_WIN   = process.platform === "win32";
+  const VENV_DIR = path.join(os.homedir(), ".qa-stlc", "venv");
+  const venvPython = IS_WIN
+    ? path.join(VENV_DIR, "Scripts", "python.exe")
+    : path.join(VENV_DIR, "bin", "python3");
+
+  // Helper: check if the package is importable by a given python binary
+  function isImportable(pyBin) {
+    if (!fs.existsSync(pyBin) && pyBin !== python) return false;
+    const r = spawnSync(pyBin, ["-c", "import qa_gentic_stlc_agents"], { encoding: "utf8" });
+    return r.status === 0;
+  }
+
+  // Find a Python 3.10–3.13 binary compatible with qa-gentic-stlc-agents.
+  // The package declares Requires-Python >=3.10,<3.14 so we must avoid 3.14+.
+  function findCompatiblePython(preferred) {
+    const candidates = IS_WIN
+      ? ["py", "python", "python3"]
+      : ["python3.13", "python3.12", "python3.11", "python3.10", preferred];
+
+    for (const bin of candidates) {
+      const r = spawnSync(bin, ["--version"], { encoding: "utf8" });
+      if (r.status !== 0) continue;
+      const ver = (r.stdout || r.stderr || "").trim();
+      const m = ver.match(/Python (\d+)\.(\d+)/);
+      if (!m) continue;
+      const major = parseInt(m[1]), minor = parseInt(m[2]);
+      if (major === 3 && minor >= 10 && minor <= 13) return bin;
+    }
+    return null;
   }
-  ok("qa-gentic-stlc-agents installed.");
+
+  // Determine which python to use for MCP servers — may be updated to venv python below
+  let resolvedPython = python;
+
+  if (isImportable(python)) {
+    // Already importable by the user-supplied / system python (CI, active venv, etc.)
+    ok("qa-gentic-stlc-agents already installed — skipping pip install.");
+  } else if (isImportable(venvPython)) {
+    // Package found in the persistent qa-stlc venv from a previous run
+    ok("qa-gentic-stlc-agents found in ~/.qa-stlc/venv — skipping pip install.");
+    resolvedPython = venvPython;
+  } else {
+    // Create (or reuse) a dedicated venv and install there.
+    // Bypasses PEP 668 on Mac/Linux Homebrew Python and works on Windows & CI
+    // without requiring elevated permissions or breaking the system Python.
+
+    // Find a Python 3.10–3.13 binary (package does not support 3.14+ yet)
+    const compatPython = findCompatiblePython(python);
+    if (!compatPython) {
+      die(
+        "qa-gentic-stlc-agents requires Python 3.10–3.13 but none was found.\n" +
+        "  Mac:     brew install python@3.13\n" +
+        "  Linux:   sudo apt install python3.13\n" +
+        "  Windows: install Python 3.13 from python.org\n" +
+        "  Then re-run: qa-stlc init --python python3.13 --vscode --integration ado"
+      );
+    }
+
+    const compatPythonVer = (spawnSync(compatPython, ["--version"], { encoding: "utf8" }).stdout || "").trim();
+    info(`Using ${compatPython} (${compatPythonVer}) for venv…`);
+
+    if (!fs.existsSync(VENV_DIR)) {
+      info(`Creating Python venv at ${VENV_DIR}…`);
+      const mkVenv = spawnSync(compatPython, ["-m", "venv", VENV_DIR], { stdio: "inherit", encoding: "utf8" });
+      if (mkVenv.status !== 0) {
+        die(`Failed to create venv. Ensure python3-venv is installed:\n  ${compatPython} -m venv ${VENV_DIR}`);
+      }
+      ok("Venv created.");
+    }
+
+    info("Installing qa-gentic-stlc-agents into venv…");
+    const pip = spawnSync(
+      venvPython,
+      ["-m", "pip", "install", "qa-gentic-stlc-agents>=1.0.1", "--quiet"],
+      { stdio: "inherit", encoding: "utf8" }
+    );
+
+    if (pip.status !== 0) {
+      die(`pip install into venv failed. Try manually:\n  ${venvPython} -m pip install qa-gentic-stlc-agents`);
+    }
+    ok("qa-gentic-stlc-agents installed into ~/.qa-stlc/venv.");
+    resolvedPython = venvPython;
+  }
+
+  // Propagate the resolved python so MCP config points to the correct interpreter
+  opts.python = resolvedPython;
 
   // ── 4. Copy ORCHESTRATION_RULES.md to project root ─────────────────────────
   info("Installing ORCHESTRATION_RULES.md to project root…");
@@ -115,7 +195,7 @@ module.exports = async function init(opts) {
   await cmdMcpConfig({
     vscode:         opts.vscode || false,
     print:          false,
-    python:         python,
+    python:         resolvedPython,
     playwrightPort: "8931",
     integration,
   });

package/src/stlc_agents/agent_helix_writer/server.py

@@ -23,7 +23,9 @@ import asyncio
 import json
 import re
 import sys
+import tempfile
 import time
+from pathlib import Path
 
 from dotenv import load_dotenv
 from mcp.server import Server
@@ -298,8 +300,9 @@ async def list_tools() -> list[types.Tool]:
             description=(
                 "Write generated TypeScript/Gherkin files into the Helix-QA directory layout "
                 "with full deduplication and interface adaptation.\n\n"
-                "Pass the 'files' dict from qa-playwright-generator:generate_playwright_code "
-                "or scaffold_locator_repository directly.\n\n"
+                "Preferred: pass cache_key from generate_playwright_code — "
+                "the server loads the files from disk automatically. "
+                "Alternative: pass the 'files' dict directly.\n\n"
                 "mode='tests_only' (default, safe to run repeatedly):\n"
                 "  Writes locators.ts, *.page.ts, *.steps.ts, *.feature only.\n"
                 "  Infrastructure files (LocatorHealer.ts etc.) are always skipped.\n"
@@ -326,11 +329,20 @@ async def list_tools() -> list[types.Tool]:
                         "type": "string",
                         "description": "Absolute path to the Helix-QA project root.",
                     },
+                    "cache_key": {
+                        "type": "string",
+                        "description": (
+                            "Cache key returned by generate_playwright_code or "
+                            "scaffold_locator_repository. Preferred over passing 'files' directly — "
+                            "the server loads the files from disk automatically."
+                        ),
+                    },
                     "files": {
                         "type": "object",
                         "description": (
                             "Dict of { file_key: file_content } as returned by "
-                            "generate_playwright_code or scaffold_locator_repository."
+                            "generate_playwright_code or scaffold_locator_repository. "
+                            "Use cache_key instead whenever possible."
                         ),
                         "additionalProperties": {"type": "string"},
                     },
@@ -351,7 +363,7 @@ async def list_tools() -> list[types.Tool]:
                         ),
                     },
                 },
-                "required": ["helix_root", "files"],
+                "required": ["helix_root"],
             },
         ),
         types.Tool(
@@ -458,8 +470,31 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
             result["_validation"] = _validate_inspect_result(result)
 
         elif name == "write_helix_files":
+            # ── Resolve files: cache_key takes priority over inline dict ──
+            files = arguments.get("files") or {}
+            # Normalise: LLMs sometimes send [{file_name, content}] instead of {path: content}
+            if isinstance(files, list):
+                files = {
+                    item.get("file_name") or item.get("path") or item.get("name", ""): item.get("content", "")
+                    for item in files
+                    if isinstance(item, dict)
+                }
+            cache_key = arguments.get("cache_key", "").strip()
+            if cache_key and not files:
+                _cache_dir = Path(tempfile.gettempdir()) / "stlc_file_cache"
+                cache_file = _cache_dir / f"{cache_key}.json"
+                if cache_file.exists():
+                    files = json.loads(cache_file.read_text())
+                else:
+                    result = {
+                        "success": False,
+                        "error": f"cache_key '{cache_key}' not found — file does not exist at {cache_file}. "
+                                 "Either pass the files dict directly or call get_generated_files first.",
+                        "_validation": {"valid": False, "errors": [f"cache_key '{cache_key}' not found"], "warnings": []},
+                    }
+                    return track(result, tool_name=name, server="qa-helix-writer", t0=t0)
             # ── Pre-write input validation ────────────────────────────────
-            input_validation = _validate_write_inputs(arguments.get("files", {}))
+            input_validation = _validate_write_inputs(files)
             if not input_validation["valid"]:
                 result = {
                     "success": False,
@@ -475,7 +510,7 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
             result = await asyncio.to_thread(
                 _write_files,
                 arguments["helix_root"],
-                arguments["files"],
+                files,
                 arguments.get("mode", "tests_only"),
                 arguments.get("force_scaffold", False),
             )