@qa-gentic/stlc-agents 1.0.28 → 1.0.30

package/bin/postinstall.js

@@ -2,27 +2,29 @@
 /**
  * postinstall.js — Auto-install Python MCP servers after npm install -g
  *
- * npm 7+ captures all stdout/stderr from lifecycle scripts for global installs,
- * so normal process.stdout / process.stderr writes are swallowed.
+ * Goals
+ * -----
+ *   1. Always finish with a working `qa-stlc-apply-cost` on PATH (or in a
+ *      well-known location like ~/.local/bin), without ever surfacing raw
+ *      pip / PEP 668 traceback output to the user's terminal.
+ *   2. Auto-install pipx when missing (brew on macOS, pip --user elsewhere).
+ *   3. Never run the cost-tracking patch when the Python package isn't
+ *      actually installed — that produces a misleading ModuleNotFoundError.
  *
- * Fix: write directly to /dev/tty (Unix) which bypasses npm's pipe entirely.
- * Falls back to process.stderr (visible for local installs / Windows CI).
- *
- * Interactive prompts (readline / TTY) require --foreground-scripts and are
- * therefore NOT used here.  The user is instructed to run `qa-stlc` in their
- * project after install — that command IS interactive.
+ * npm 7+ swallows stdout/stderr from global lifecycle scripts, so all
+ * user-facing writes go straight to /dev/tty (with stderr as a fallback).
  */
 "use strict";
 
-// ── Open /dev/tty so writes go straight to the user's terminal ───────────────
-// npm 7+ suppresses all stdout/stderr for global lifecycle scripts; /dev/tty
-// bypasses that pipe entirely.  Fall back to stderr on Windows / non-TTY CI.
 const fs   = require("fs");
-let _tty = null;
-try {
-  _tty = fs.openSync("/dev/tty", "w");
-} catch (_) { /* Windows or no TTY — use stderr fallback */ }
+const os   = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const pkg = require("../package.json");
 
+// ── Output: write to /dev/tty so npm 7+ doesn't swallow our messages ─────────
+let _tty = null;
+try { _tty = fs.openSync("/dev/tty", "w"); } catch (_) { /* Windows / CI */ }
 const _write = (msg) => {
   const line = msg + "\n";
   if (_tty !== null) {
@@ -30,28 +32,49 @@ const _write = (msg) => {
   }
   process.stderr.write(line);
 };
-console.log   = _write;
-console.info  = _write;
-console.warn  = _write;
-console.error = _write;
-
-const { spawnSync } = require("child_process");
-const os   = require("os");
-const path = require("path");
-const pkg = require("../package.json");
+console.log = console.info = console.warn = console.error = _write;
 
 const C = {
   reset:  "\x1b[0m", bold:   "\x1b[1m",
   green:  "\x1b[32m", cyan:   "\x1b[36m",
   yellow: "\x1b[33m", dim:    "\x1b[2m",
 };
-
 const b    = (s) => `${C.bold}${s}${C.reset}`;
 const ok   = (s) => console.log(`${C.green}✓${C.reset}  ${s}`);
 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}`;
 
+const ENTRY = "qa-stlc-apply-cost";
+
+// Walk PATH plus the well-known pipx / pip --user dirs so we still find
+// scripts even when the shell hasn't refreshed PATH since `pipx install`.
+const findCommand = (cmd) => {
+  const exts = process.platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+  const dirs = [...(process.env.PATH || "").split(path.delimiter)];
+  dirs.push(path.join(os.homedir(), ".local", "bin"));
+  if (process.platform === "darwin") {
+    dirs.push("/opt/homebrew/bin", "/usr/local/bin");
+  }
+  for (const dir of dirs) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const p = path.join(dir, cmd + ext);
+      try { if (fs.existsSync(p)) return p; } catch (_) {}
+    }
+  }
+  return null;
+};
+
+// Fully silent spawn — captures stdout+stderr, returns combined output.
+const trySpawn = (cmd, args) => {
+  const r = spawnSync(cmd, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  });
+  return { status: r.status, output: `${r.stdout || ""}${r.stderr || ""}` };
+};
+
 console.log(`
 ${b("QA STLC Agents")} v${pkg.version} — post-install
 
@@ -62,53 +85,133 @@ ${d("This npm package includes:")}
   • Command-line tools: qa-stlc init, qa-stlc scaffold, qa-stlc skills, etc.
 `);
 
-// ── 1. Find Python ────────────────────────────────────────────────────────────
-const pythonCandidates = ["python3", "python"];
+// ── 1. Find Python ───────────────────────────────────────────────────────────
 let python = null;
-for (const candidate of pythonCandidates) {
+for (const candidate of ["python3", "python"]) {
   const r = spawnSync(candidate, ["--version"], { encoding: "utf8" });
   if (r.status === 0) { python = candidate; break; }
 }
 
-if (!python) {
-  warn("Python not found — skipping pip install.");
-  warn("After installing Python 3.10+, run inside your project:");
-  warn("  pip install qa-gentic-stlc-agents");
+// Quick PEP 668 detector — short-circuits plain `pip install` on Homebrew /
+// Debian Python so its traceback never reaches the terminal.
+const isPep668 = (() => {
+  if (!python) return false;
+  const r = trySpawn(python, ["-m", "pip", "install", "--dry-run", "pip"]);
+  return /externally-managed-environment/i.test(r.output);
+})();
+
+// ── 2. Make sure pipx is available (pipx handles PEP 668 cleanly) ────────────
+const ensurePipx = () => {
+  if (findCommand("pipx")) return true;
+
+  // macOS — prefer brew (matches Homebrew Python's expectations)
+  if (process.platform === "darwin" && findCommand("brew")) {
+    info("Installing pipx via Homebrew…");
+    const r = trySpawn("brew", ["install", "pipx"]);
+    if (r.status === 0) {
+      trySpawn("pipx", ["ensurepath"]);
+      if (findCommand("pipx")) { ok("pipx installed."); return true; }
+    }
+  }
+
+  // Fallback — pip --user (works on Linux, Windows, and PEP 668 systems with the flag)
+  if (python) {
+    info("Installing pipx via pip --user…");
+    const args = ["-m", "pip", "install", "--user", "--quiet", "pipx"];
+    if (isPep668) args.splice(4, 0, "--break-system-packages");
+    const r = trySpawn(python, args);
+    if (r.status === 0) {
+      trySpawn(python, ["-m", "pipx", "ensurepath"]);
+      if (findCommand("pipx")) { ok("pipx installed."); return true; }
+    }
+  }
+  return false;
+};
+
+// ── 3. Install qa-gentic-stlc-agents ─────────────────────────────────────────
+let entryPath = findCommand(ENTRY);
+let pipOk     = entryPath !== null;
+let viaTag    = null;
+
+if (pipOk) {
+  // Already installed — best-effort silent upgrade via pipx if it manages this.
+  if (findCommand("pipx")) {
+    const list = spawnSync("pipx", ["list", "--short"], { encoding: "utf8" });
+    if ((list.stdout || "").includes("qa-gentic-stlc-agents")) {
+      spawnSync("pipx", ["upgrade", "qa-gentic-stlc-agents"], { stdio: "ignore" });
+      entryPath = findCommand(ENTRY) || entryPath;
+    }
+  }
+  ok("qa-gentic-stlc-agents already installed.");
 } else {
-  // ── 2. pip install (non-interactive, pipe output to stderr) ────────────────
-  info("Installing qa-gentic-stlc-agents via pip…");
-  const pip = spawnSync(
-    python,
-    ["-m", "pip", "install", "qa-gentic-stlc-agents", "--upgrade", "--quiet"],
-    { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" }
-  );
-  if (pip.status === 0) {
-    ok("qa-gentic-stlc-agents installed.");
+  info("Installing qa-gentic-stlc-agents…");
+
+  // Attempt A — pipx (auto-installed above if missing)
+  if (ensurePipx()) {
+    const r = trySpawn("pipx", ["install", "--force", "--quiet", "qa-gentic-stlc-agents"]);
+    if (r.status === 0) { pipOk = true; viaTag = "pipx"; }
+  }
+
+  // Attempt B — plain pip (only when NOT a PEP 668 environment)
+  if (!pipOk && python && !isPep668) {
+    const r = trySpawn(python, ["-m", "pip", "install", "--upgrade", "--quiet", "qa-gentic-stlc-agents"]);
+    if (r.status === 0) { pipOk = true; viaTag = "pip"; }
+  }
+
+  // Attempt C — pip --user --break-system-packages (PEP 668 fallback)
+  if (!pipOk && python) {
+    const r = trySpawn(python, [
+      "-m", "pip", "install",
+      "--user", "--break-system-packages",
+      "--upgrade", "--quiet", "qa-gentic-stlc-agents",
+    ]);
+    if (r.status === 0) { pipOk = true; viaTag = "pip --user"; }
+  }
+
+  if (pipOk) {
+    ok(`qa-gentic-stlc-agents installed ${d(`(via ${viaTag})`)}`);
+    entryPath = findCommand(ENTRY);
   } else {
-    // Only surface pip output on failure
-    if (pip.stdout) process.stderr.write(pip.stdout);
-    if (pip.stderr) process.stderr.write(pip.stderr);
-    warn("pip install failed. Run manually: pip install qa-gentic-stlc-agents");
+    warn("Could not auto-install qa-gentic-stlc-agents. Run one of:");
+    console.log(`  ${C.cyan}pipx install qa-gentic-stlc-agents${C.reset}                                         ${d("# recommended")}`);
+    console.log(`  ${C.cyan}python3 -m pip install --user --break-system-packages qa-gentic-stlc-agents${C.reset}`);
   }
 }
 
-// ── 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. Activate cost tracking — only when the package is actually present ────
+if (pipOk) {
+  info("Activating cost tracking on MCP servers…");
+  let costPatch;
+  if (entryPath) {
+    costPatch = spawnSync(entryPath, [], {
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+      shell: process.platform === "win32",
+    });
+  } else if (findCommand("pipx")) {
+    // pipx-installed entry points may not yet be on this process's PATH —
+    // `pipx run` resolves them directly from pipx's venv.
+    costPatch = spawnSync("pipx", ["run", "--spec", "qa-gentic-stlc-agents", ENTRY], {
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+    });
+  } else if (python) {
+    costPatch = spawnSync(python, ["-m", "stlc_agents.shared.install_hook"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+    });
+  }
+
+  if (costPatch && costPatch.status === 0) {
+    (costPatch.stdout || "").split("\n").filter(Boolean).forEach((l) => console.log(l));
+    ok("Cost tracking active — every tool call will log tokens + cost");
+  } else {
+    // Silent — the patch is opt-in instrumentation and not load-bearing.
+    warn(`Cost tracking patch skipped — run later with: ${C.cyan}${ENTRY}${C.reset}`);
+  }
 }
- 
-// ── 4. Print next-step instructions ──────────────────────────────────────────
+
+// ── 5. Next-step instructions ────────────────────────────────────────────────
 console.log(`
 ${b("Next steps")} — run these inside your project root:
 
@@ -138,4 +241,4 @@ ${d("Docs: https://github.com/qa-gentic/stlc-agents")}
 ${d("  Tip: npm sometimes suppresses postinstall output for global packages.")}
 ${d("       If you missed these instructions, run  qa-stlc  in your project.")}
 ${d("       Or reinstall with: npm install -g --foreground-scripts @qa-gentic/stlc-agents")}
-`);
+`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qa-gentic/stlc-agents",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "QA STLC Agents — six MCP servers + skills for AI-powered test case, Gherkin, self-healing Playwright generation, Helix-QA file writing, and existing-framework migration against Azure DevOps and Jira Cloud. Includes an 8-strategy LocatorHealer with a live HealingDashboard (write-back-to-source) and a one-shot `stlc-migrate` CLI that converts an existing Playwright project into a fully agent-ready Helix-QA tree. Works with Claude Code, GitHub Copilot, Cursor, Windsurf.",
   "keywords": [
     "playwright",
@@ -56,7 +56,6 @@
     "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');",
@@ -68,6 +67,7 @@
   },
   "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": {
+    "@qa-gentic/stlc-agents": "^1.0.29",
     "commander": "^12.0.0",
     "which": "^4.0.0"
   },

package/src/stlc_agents/agent_playwright_generator/server.py

@@ -32,6 +32,7 @@ from mcp.server.stdio import stdio_server
 from mcp import types
 from stlc_agents.shared.auth import get_auth_headers, get_signed_in_user
 from stlc_agents.agent_playwright_generator.tools.ado_attach import attach_file_to_work_item as _attach_file
+from stlc_agents.shared.cost_tracker import track
 
 load_dotenv()
 app = Server("qa-playwright-generator")
@@ -424,6 +425,7 @@ async def list_tools() -> list[types.Tool]:
 
 @app.call_tool()
 async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+    t0 = time.monotonic()
     try:
         if name == "capture_app_context":
             result = await asyncio.to_thread(
@@ -503,7 +505,7 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
                         "and retry. No files were attached to ADO."
                     ),
                 }
-                return [types.TextContent(type="text", text=json.dumps(result, indent=2, ensure_ascii=False))]
+                return track(result, tool_name=name, server='qa-playwright-generator', t0=t0)
 
             # ── Epic guard — attachments on Epics are invisible in ADO workflow views ──
             wi_id = arguments["work_item_id"]
@@ -575,7 +577,7 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
             )
         else:
             result = {"error": f"Unknown tool: {name}"}
-        return [types.TextContent(type="text", text=json.dumps(result, indent=2, ensure_ascii=False))]
+        return track(result, tool_name=name, server='qa-playwright-generator', t0=t0)
     except Exception as exc:
         return [types.TextContent(type="text", text=json.dumps({"error": str(exc), "tool": name}, indent=2))]