@qa-gentic/stlc-agents 1.0.0

package/README.md

@@ -0,0 +1,310 @@
+# @stlc/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**.
+
+[![npm version](https://img.shields.io/npm/v/@stlc/agents)](https://www.npmjs.com/package/@stlc/agents)
+[![PyPI version](https://img.shields.io/pypi/v/stlc-agents)](https://pypi.org/project/stlc-agents/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![Python >=3.10](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://python.org)
+
+---
+
+## 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 @stlc/agents
+qa-stlc init --vscode
+```
+
+`qa-stlc init` does three things:
+1. `pip install stlc-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
+
+Start the Playwright browser server before your first session:
+
+```bash
+npx @playwright/mcp@latest --port 8931
+```
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+- Python ≥ 3.10, < 3.14
+- Azure DevOps organisation with a `.env` containing:
+
+```env
+ADO_ORGANIZATION_URL=https://dev.azure.com/your-org
+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 scaffold [--name <name>] [--dir <path>] [--no-install]
+# Copy full Playwright + Cucumber + TypeScript boilerplate to a new project directory
+
+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
+```
+
+---
+
+## Usage
+
+Open your AI coding agent and use natural language:
+
+```
+# Generate test cases
+Generate test cases for work item #12345 in MyProject at https://dev.azure.com/myorg
+
+# Generate Gherkin BDD
+Generate a Gherkin regression suite for Feature #11000 in MyProject at https://dev.azure.com/myorg
+
+# Generate Playwright code (requires Playwright MCP running)
+Generate Playwright TypeScript for the Gherkin I just created. The login page is at /auth/login
+
+# Write to Helix-QA project
+Write the generated files to my Helix-QA project at /workspace/my-qa-project
+```
+
+---
+
+## 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. |
+| `fetch_feature_hierarchy` | Fetch a Feature and all child PBIs/Bugs with acceptance criteria and existing attachments. |
+| `fetch_work_item_for_gherkin` | Fetch a PBI or Bug with parent Feature context, suggested file name, and linked test case steps. |
+| `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. |
+| `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. |
+| `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` | Returns `framework_state` (`present` / `partial` / `absent`) and `recommendation`. |
+| `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. |
+
+### 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`.
+
+All suggestions require human approval before entering version control.
+
+---
+
+## 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"
+```
+
+---
+
+## Scaffold a New QA Project
+
+The `scaffold` command copies the full Playwright + Cucumber + TypeScript boilerplate framework — including three-layer AI self-healing, BDD templates, and CI/CD integration — into a new project directory.
+
+```bash
+# Scaffold into ./my-qa-project (default name)
+qa-stlc scaffold
+
+# Custom project name and location
+qa-stlc scaffold --name acme-e2e --dir /path/to/workspace/acme-e2e
+
+# Skip npm install (e.g. to inspect files first)
+qa-stlc scaffold --name acme-e2e --no-install
+```
+
+After scaffolding:
+
+```bash
+cd my-qa-project
+npx playwright install chromium     # install browser binaries
+cp .env.example .env                # already done by scaffold
+# Edit .env — set BASE_URL and optionally AI_API_KEY
+npm test                            # run the example scenario
+```
+
+### What Gets Scaffolded
+
+| Layer | Contents |
+|---|---|
+| **Config** | `package.json`, `tsconfig.json`, `cucumber.js`, `.env.example`, `.gitignore` |
+| **CI/CD** | `Dockerfile`, `docker-compose.yml`, `azure-pipelines.yml` |
+| **Framework** | `src/hooks/`, `src/pages/BasePage.ts`, `src/locators/`, `src/config/` |
+| **Self-healing** | All healing utilities: `LocatorHealer`, `TimingHealer`, `VisualIntentChecker`, `HealingDashboard`, `review-server`, `healix-ci-apply`, etc. |
+| **AI utilities** | `AILocatorGenerator`, `AISelfHealing`, `AITestGenerator` |
+| **Auth** | `AuthManager`, `AuthSetup` |
+| **Templates** | `_template.feature`, `_template.locators.ts`, `_template.steps.ts`, `_TemplatePage.ts` |
+| **Example test** | `src/test/features/example.feature` + steps |
+
+### Healing Dashboard
+
+During a test run the live dashboard is available at **http://localhost:7890**. After the run use the review server for promote-to-source + PR creation:
+
+```bash
+npm run healix:review    # http://localhost:7891
+# or in CI:
+HEALIX_CI_AUTO_APPROVE=true npm run healix:apply-ci
+```
+
+---
+
+## Development
+
+```bash
+make install      # create .venv + pip install -e .
+make test         # run pytest tests/ -v
+make skills       # install skill files to .claude/skills/
+make verify       # check MSAL auth status without making ADO calls
+make clean        # remove .venv, __pycache__, dist
+```
+
+---
+
+## Documentation
+
+- [Quick Start Guide](docs/quickstart.md)
+- [Architecture Reference](docs/architecture.md)
+- [End-to-End Walkthrough](docs/walkthrough.md)
+
+---
+
+## License
+
+MIT

package/bin/postinstall.js

@@ -0,0 +1,78 @@
+#!/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-stlc-agents");
+} else {
+  // ── 2. pip install qa-gentic-stlc-agents ──────────────────────────────────────────
+  info("Installing qa-gentic-stlc-agents via pip…");
+  const pip = spawnSync(python, ["-m", "pip", "install", "qa-gentic-stlc-agents", "--upgrade", "--quiet"], {
+    stdio: "inherit",
+    encoding: "utf8",
+  });
+
+  if (pip.status === 0) {
+    ok("qa-gentic-stlc-agents installed.");
+  } else {
+    warn("pip install failed. Run manually: pip install qa-gentic-stlc-agents");
+  }
+}
+
+// ── 3. Next steps ─────────────────────────────────────────────────────────────
+console.log(`
+${b("Setup")} — run once in your project root:
+
+  ${C.cyan}qa-stlc init --vscode${C.reset}   ${d("# GitHub Copilot / VS Code")}
+  ${C.cyan}qa-stlc init${C.reset}             ${d("# Claude Code")}
+
+  ${d("Writes .vscode/mcp.json + installs skill files — then reload VS Code.")}
+
+${b("Start Playwright MCP")} ${d("(keep running in a separate terminal)")}:
+
+  ${C.cyan}npx @playwright/mcp@latest --port 8931${C.reset}
+
+${b("STLC Workflow")} — use agents in this order:
+
+  ${d("1 →")} ${y("qa-test-case-manager")}     ${d("ADO work item ID → create manual test cases in ADO")}
+  ${d("2 →")} ${y("qa-gherkin-generator")}     ${d("Epic / Feature / PBI → BDD .feature file attached to ADO")}
+  ${d("3 →")} ${y("qa-playwright-generator")}  ${d("Gherkin + live page snapshot → self-healing Playwright TypeScript")}
+  ${d("4 →")} ${y("qa-helix-writer")}          ${d("Generated files → merged into Helix-QA project on disk")}
+
+${d("Skills reference all four steps — ask your agent: \"@generate-playwright-code\"")}
+${d("Docs: https://github.com/qa-gentic/stlc-agents")}
+`);

package/bin/qa-stlc.js

@@ -0,0 +1,89 @@
+#!/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");
+const cmdScaffold   = require("../src/cmd-scaffold");
+
+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-stlc-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);
+
+// ── scaffold ──────────────────────────────────────────────────────────────────
+program
+  .command("scaffold")
+  .description(
+    "Scaffold a new Playwright + Cucumber + TypeScript QA project from the Healix boilerplate.\n" +
+    "Includes three-layer AI self-healing, BDD templates, and CI/CD integration."
+  )
+  .option("--name <name>", "Project name (used in package.json and directory)", "my-qa-project")
+  .option("--dir  <dir>",  "Output directory (defaults to ./<name>)")
+  .option("--no-install",  "Skip npm install after scaffolding")
+  .action(cmdScaffold);
+
+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/stlc-agents",
+  "version": "1.0.0",
+  "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/stlc-agents#readme",
+  "bugs": {
+    "url": "https://github.com/qa-gentic/stlc-agents/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qa-gentic/stlc-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"
+  }
+}