@qa-gentic/agents 1.1.2

package/README.md

@@ -0,0 +1,203 @@
+# @qa-gentic/agents
+
+> AI-powered QA STLC automation — from Azure DevOps work item to self-healing Playwright TypeScript in a Helix-QA project.
+
+Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**, and **Windsurf**.
+
+---
+
+## What It Does
+
+Four Python MCP servers cover the full QA Software Test Life Cycle:
+
+| Agent | Input | Output |
+|---|---|---|
+| `qa-test-case-manager` | ADO PBI / Bug / Feature ID | Manual test cases created & linked via TestedBy-Forward |
+| `qa-gherkin-generator` | ADO Epic / Feature / PBI / Bug ID | `.feature` file attached to the ADO work item |
+| `qa-playwright-generator` | Gherkin + live browser | `locators.ts` + page objects + step defs attached to ADO |
+| `qa-helix-writer` | Generated `.ts` files + `helix_root` | Files written to Helix-QA directory layout on disk |
+
+A fifth server — **Playwright MCP** (`http://localhost:8931/mcp`) — drives a real browser during code generation, replacing hand-authored locators with accessibility-tree-derived, zero-hallucination selectors.
+
+---
+
+## Install
+
+```bash
+npm install -g @qa-gentic/agents
+qa-stlc init --vscode
+```
+
+`qa-stlc init` does three things:
+1. `pip install qa-gentic-agents` — installs the four Python MCP servers
+2. Copies skill files to `.github/copilot-instructions/` (and `.claude/` if not `--vscode`)
+3. Writes `.vscode/mcp.json` with all five servers configured
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+- Python ≥ 3.10
+- Azure DevOps organisation with a `.env` containing:
+
+```
+ADO_ORGANIZATION_URL=https://dev.azure.com/qa-gentic
+ADO_PROJECT_NAME=YourProject
+ADO_PAT=your-personal-access-token
+APP_BASE_URL=your-app-base-url
+APP_EMAIL=your-test-email@example.com
+APP_PASSWORD=your-test-password
+```
+
+---
+
+## Commands
+
+```bash
+qa-stlc init [--vscode] [--python <path>]
+# Full bootstrap: pip install + skills + MCP config
+
+qa-stlc skills [--target claude|vscode|cursor|windsurf|both|print]
+# Copy skill files to the correct AI coding agent directory
+
+qa-stlc mcp-config [--vscode] [--print] [--python <path>] [--playwright-port <n>]
+# Write .vscode/mcp.json (--vscode) or .mcp.json (Claude Code)
+
+qa-stlc verify
+# Check that all five MCP servers are reachable
+```
+
+---
+
+## Tool Reference
+
+### qa-test-case-manager
+
+| Tool | Description |
+|---|---|
+| `fetch_work_item` | Fetch a PBI, Bug, or Feature with acceptance criteria, linked test cases, and coverage hints. Returns `epic_not_supported` for Epics. Returns `confirmation_required: true` for Features. |
+| `get_linked_test_cases` | List all test cases already linked to a work item. Call before generating to power the deduplication diff. |
+| `create_and_link_test_cases` | Create structured manual test cases in ADO and link them via TestedBy-Forward. |
+
+### qa-gherkin-generator
+
+| Tool | Description |
+|---|---|
+| `fetch_epic_hierarchy` | Fetch an Epic and all child Features, PBIs, Bugs, and existing test cases. Use when user provides an Epic ID. |
+| `fetch_feature_hierarchy` | Fetch a Feature and all child PBIs/Bugs with acceptance criteria and existing attachments. Use when user provides a Feature ID. |
+| `fetch_work_item_for_gherkin` | Fetch a PBI or Bug with parent Feature context, suggested file name, and linked test case steps. Use when user provides a PBI or Bug ID. |
+| `attach_gherkin_to_feature` | Validate and attach a `.feature` file to a Feature work item. |
+| `attach_gherkin_to_work_item` | Validate and attach a `.feature` file to a PBI or Bug work item. |
+| `validate_gherkin_content` | Structural validation — tags, scenario count, navigation steps. Returns `valid: bool` + `errors` + `warnings`. |
+
+### qa-playwright-generator
+
+| Tool | Description |
+|---|---|
+| `generate_playwright_code` | Generate `locators.ts`, `*Page.ts`, `*.steps.ts`, and `cucumber-profile.js` from validated Gherkin + live AX-tree `context_map`. Hard-blocks if `context_map` is absent to prevent hallucinated locators. |
+| `scaffold_locator_repository` | Generate the six Helix-QA healing infrastructure files: `LocatorHealer.ts`, `LocatorRepository.ts`, `TimingHealer.ts`, `VisualIntentChecker.ts`, `DevToolsHealer.ts`, `HealingDashboard.ts`. |
+| `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. Prevents `Ambiguous step definition` runtime errors. |
+| `attach_code_to_work_item` | Attach delta Playwright TypeScript files to an ADO work item. Pass only net-new delta files. |
+
+### qa-helix-writer
+
+| Tool | Description |
+|---|---|
+| `inspect_helix_project` | Inspect a Helix-QA project root. Returns `framework_state` (`present` / `partial` / `absent`) and `recommendation` (`tests_only` / `scaffold_and_tests`). |
+| `list_helix_tree` | List the full directory tree of a Helix-QA project. |
+| `read_helix_file` | Read an existing file from the Helix-QA project for overlap detection. |
+| `write_helix_files` | Write generated files to the correct Helix-QA paths. Handles routing, deduplication, and interface adaptation automatically. |
+
+### playwright (external)
+
+| Tool | Description |
+|---|---|
+| `browser_navigate` | Navigate to a URL in the live browser. |
+| `browser_snapshot` | Capture the full AX tree — source for zero-hallucination locators. |
+| `browser_fill_form` | Fill multiple form fields by ref. |
+| `browser_click` | Click an element by ref. |
+| `browser_file_upload` | Upload a file to a file input by ref. |
+
+---
+
+## MCP Config
+
+### VS Code / GitHub Copilot (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "qa-test-case-manager":    { "command": "/path/to/.venv/bin/qa-test-case-manager" },
+    "qa-gherkin-generator":    { "command": "/path/to/.venv/bin/qa-gherkin-generator" },
+    "qa-playwright-generator": { "command": "/path/to/.venv/bin/qa-playwright-generator" },
+    "qa-helix-writer":         { "command": "/path/to/.venv/bin/qa-helix-writer" },
+    "playwright": { "type": "http", "url": "http://localhost:8931/mcp" }
+  }
+}
+```
+
+### Claude Code (`.mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "qa-test-case-manager":    { "command": "/path/to/.venv/bin/qa-test-case-manager" },
+    "qa-gherkin-generator":    { "command": "/path/to/.venv/bin/qa-gherkin-generator" },
+    "qa-playwright-generator": { "command": "/path/to/.venv/bin/qa-playwright-generator" },
+    "qa-helix-writer":         { "command": "/path/to/.venv/bin/qa-helix-writer" },
+    "playwright": { "type": "url", "url": "ws://localhost:8931" }
+  }
+}
+```
+
+> VS Code requires `http://localhost:8931/mcp` (with `/mcp` suffix).  
+> Claude Code requires `ws://localhost:8931` (WebSocket, no `/mcp`).  
+> `qa-stlc mcp-config` writes the correct format automatically.
+
+---
+
+## Skills Installed
+
+| Skill | Purpose |
+|---|---|
+| `AGENT-BEHAVIOR.md` | Zero-inference contract. Read first. Always. |
+| `generate-test-cases.md` | PBI / Bug / Feature → ADO manual test cases |
+| `generate-gherkin.md` | Epic / Feature / PBI / Bug → validated `.feature` + ADO attach |
+| `generate-playwright-code.md` | Gherkin + live browser → three-layer self-healing Playwright TypeScript |
+| `write-helix-files.md` | Generated files → Helix-QA disk layout, scaffold or merge |
+| `deduplication-protocol.md` | READ → DIFF → CREATE mandatory pre-flight gate |
+
+---
+
+## Three-Layer Self-Healing Architecture
+
+| Layer | Class | What it heals |
+|---|---|---|
+| 1 — Locator | `LocatorHealer` | primary selector → role → label → text → AI Vision → CDPSession AX tree |
+| 2 — Timing | `TimingHealer` | network-trace drift → auto-adjusted timeouts → HealingDashboard |
+| 3 — Visual | `VisualIntentChecker` | element screenshot diff at assertions → HealingDashboard |
+
+Healed selectors persist in `LocatorRepository`. HealingDashboard: `http://localhost:7890`.
+
+---
+
+## Run Tests
+
+```bash
+ENABLE_SELF_HEALING=true \
+HEALING_DASHBOARD_PORT=7890 \
+APP_BASE_URL=<your-app-base-url> \
+APP_EMAIL=<email> \
+APP_PASSWORD=<password> \
+cucumber-js --config=config/cucumber.js -p <feature_profile>
+
+# Smoke only
+cucumber-js --config=config/cucumber.js -p <feature_profile> --tags "@smoke"
+```
+
+---
+
+## License
+
+MIT

package/bin/postinstall.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js — Auto-install Python MCP servers after npm install -g.
+ */
+"use strict";
+
+const { spawnSync } = require("child_process");
+const pkg = require("../package.json");
+
+const C = {
+  reset:  "\x1b[0m",
+  bold:   "\x1b[1m",
+  green:  "\x1b[32m",
+  cyan:   "\x1b[36m",
+  yellow: "\x1b[33m",
+  red:    "\x1b[31m",
+  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 y  = (s) => `${C.yellow}${s}${C.reset}`;
+const d  = (s) => `${C.dim}${s}${C.reset}`;
+
+console.log(`\n${b("QA STLC Agents")} — post-install\n`);
+
+// ── 1. Find python ────────────────────────────────────────────────────────────
+const pythonCandidates = ["python3", "python"];
+let python = null;
+for (const candidate of pythonCandidates) {
+  const r = spawnSync(candidate, ["--version"], { encoding: "utf8" });
+  if (r.status === 0) { python = candidate; break; }
+}
+
+if (!python) {
+  warn("Python not found — skipping pip install.");
+  warn("Run manually after installing Python 3.10+:");
+  warn("  pip install qa-gentic-agents");
+} else {
+  // ── 2. pip install qa-gentic-agents ──────────────────────────────────────────
+  info("Installing qa-gentic-agents via pip…");
+  const pip = spawnSync(python, ["-m", "pip", "install", "qa-gentic-agents", "--upgrade", "--quiet"], {
+    stdio: "inherit",
+    encoding: "utf8",
+  });
+
+  if (pip.status === 0) {
+    ok("qa-gentic-agents installed.");
+  } else {
+    warn("pip install failed. Run manually: pip install qa-gentic-agents");
+  }
+}
+
+// ── 3. Next steps ─────────────────────────────────────────────────────────────
+console.log(`
+${b("Next steps")} (run in your project root):
+
+  Start Playwright MCP ${d("(required for live locator generation)")}
+  ${C.cyan}npx @playwright/mcp@latest --port 8931${C.reset}
+
+  Install skills + write MCP config
+  ${C.cyan}qa-stlc init --vscode${C.reset}   ${d("# GitHub Copilot / VS Code")}
+  ${C.cyan}qa-stlc init${C.reset}             ${d("# Claude Code")}
+
+${b("Agents:")}
+  ${y("qa-test-case-manager")}     ADO work item → test cases in ADO
+  ${y("qa-gherkin-generator")}     ADO Epic/Feature/PBI/Bug → BDD .feature attached to ADO
+  ${y("qa-playwright-generator")}  Gherkin → self-healing Playwright TypeScript
+  ${y("qa-helix-writer")}          Generated files → Helix-QA paths on disk
+  ${y("playwright")} (MCP)         Live browser snapshots for verified locators
+
+${d("Docs: https://github.com/qa-gentic/qa-gentic-agents")}
+`);

package/bin/qa-stlc.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * qa-stlc — CLI for QA STLC Agents
+ *
+ * Usage:
+ *   qa-stlc init                    # Bootstrap MCP config + skills for current project
+ *   qa-stlc skills [--target]       # Install skills into a coding agent
+ *   qa-stlc mcp-config [--vscode]   # Write MCP server config
+ *   qa-stlc verify                  # Check Python agents + Playwright MCP are reachable
+ *   qa-stlc help                    # Show full help
+ */
+
+"use strict";
+
+const { program } = require("commander");
+const path = require("path");
+const pkg = require("../package.json");
+
+// Sub-commands
+const cmdInit       = require("../src/cmd-init");
+const cmdSkills     = require("../src/cmd-skills");
+const cmdMcpConfig  = require("../src/cmd-mcp-config");
+const cmdVerify     = require("../src/cmd-verify");
+
+program
+  .name("qa-stlc")
+  .description(
+    "QA STLC Agents — MCP servers + skills for AI-powered test case, Gherkin, and Playwright generation."
+  )
+  .version(pkg.version);
+
+// ── init ─────────────────────────────────────────────────────────────────────
+program
+  .command("init")
+  .description(
+    "Bootstrap the current project: install Python MCP agents, copy skills, and write MCP config.\n" +
+    "Equivalent to running: pip install qa-gentic-agents && qa-stlc skills && qa-stlc mcp-config"
+  )
+  .option("--vscode", "Also write .vscode/mcp.json for GitHub Copilot")
+  .option("--python <path>", "Path to Python 3.10+ binary", "python3")
+  .action(cmdInit);
+
+// ── skills ────────────────────────────────────────────────────────────────────
+program
+  .command("skills")
+  .description("Install agent skill files into the current project for your coding agent to read.")
+  .option(
+    "--target <target>",
+    "Where to install: claude (default), vscode, cursor, windsurf, print",
+    "claude"
+  )
+  .action(cmdSkills);
+
+// ── mcp-config ────────────────────────────────────────────────────────────────
+program
+  .command("mcp-config")
+  .description("Generate MCP server configuration for Claude Code (.mcp.json) or VS Code (.vscode/mcp.json).")
+  .option("--vscode", "Write .vscode/mcp.json instead of .mcp.json")
+  .option("--print", "Print config to stdout without writing any file")
+  .option("--python <path>", "Path to Python 3.10+ binary or venv", "python3")
+  .option("--playwright-port <port>", "Port Playwright MCP is running on", "8931")
+  .action(cmdMcpConfig);
+
+// ── verify ────────────────────────────────────────────────────────────────────
+program
+  .command("verify")
+  .description("Check that Python MCP agents are installed and Playwright MCP is reachable.")
+  .option("--playwright-port <port>", "Port Playwright MCP is running on", "8931")
+  .action(cmdVerify);
+
+program.parse(process.argv);
+
+// Show help if no command given
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@qa-gentic/agents",
+  "version": "1.1.2",
+  "description": "QA STLC Agents — MCP servers + skills for AI-powered test case, Gherkin, and Playwright generation against Azure DevOps. Works with Claude Code, GitHub Copilot, Cursor, Windsurf.",
+  "keywords": [
+    "playwright",
+    "mcp",
+    "azure-devops",
+    "gherkin",
+    "bdd",
+    "qa",
+    "test-automation",
+    "claude",
+    "copilot",
+    "claude-code",
+    "mcp-server",
+    "self-healing"
+  ],
+  "homepage": "https://github.com/qa-gentic/qa-gentic-agents#readme",
+  "bugs": {
+    "url": "https://github.com/qa-gentic/qa-gentic-agents/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qa-gentic/qa-gentic-agents.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "qa-stlc": "bin/qa-stlc.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    ".claude-plugin/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node ./bin/postinstall.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "which": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}