@qa-gentic/stlc-agents 1.0.27 → 1.0.29

package/QUICKSTART-JIRA.md

@@ -0,0 +1,334 @@
+# @qa-gentic/stlc-agents — Jira Cloud Quick Start
+
+> Jira Cloud pipeline: issue → test cases → Gherkin → Playwright TypeScript → Helix-QA.
+> For Azure DevOps see [QUICKSTART-ADO.md](QUICKSTART-ADO.md).
+
+
+Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**, and **Windsurf**.
+
+[![npm version](https://img.shields.io/npm/v/@qa-gentic/stlc-agents)](https://www.npmjs.com/package/@qa-gentic/stlc-agents)
+[![PyPI version](https://img.shields.io/pypi/v/qa-gentic-stlc-agents)](https://pypi.org/project/qa-gentic-stlc-agents/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+
+## What the Jira Pipeline Does
+
+Six Python MCP servers. The Jira pipeline uses `qa-jira-manager` as its entry point, then the three shared agents, with `qa-migration` / `stlc-migrate` available for converting existing Playwright projects:
+
+| Step | Agent | What happens |
+|---|---|---|
+| 1 | `qa-jira-manager` | Fetch Jira issue + analyse acceptance criteria |
+| 2 | `qa-jira-manager` | Generate test cases → create in Jira with `is tested by` links |
+| 3 | `qa-gherkin-generator` | Generate Gherkin `.feature` file |
+| 4 | `qa-playwright-generator` | Gherkin + live browser → self-healing Playwright TypeScript |
+| 5 | `qa-helix-writer` | Write generated files to Helix-QA project on disk |
+| — | `qa-migration` / `stlc-migrate` | Existing Playwright project → fully agent-ready Helix-QA tree (Jira `.mcp.json`, skills, healer scaffold, BOILERPLATE infra) |
+
+The Playwright MCP server (`http://localhost:8931/mcp`) is required for browser-driven code generation. It is not part of this package and must be started separately.
+
+---
+
+## Install
+
+```bash
+npm install -g @qa-gentic/stlc-agents
+qa-stlc init --vscode --integration jira
+```
+
+
+`qa-stlc init --integration jira` performs:
+1. `pip install qa-gentic-stlc-agents` — installs all six Python MCP servers + `stlc-migrate` CLI
+2. Copies skill files (including `qa-jira-manager/`, `generate-gherkin/`, `generate-playwright-code/`, `write-helix-files/`, `migrate-framework/`) to your coding agent directory
+3. Writes `.vscode/mcp.json` with all required servers configured (`qa-jira-manager` + shared Agents 2–4 + `qa-migration` + `playwright`)
+
+
+Start the Playwright MCP server before your first session:
+
+```bash
+npx @playwright/mcp@latest --port 8931
+```
+
+---
+
+
+## Requirements
+
+- Node.js ≥ 18
+- Python ≥ 3.10, < 3.14
+- Jira Cloud site with OAuth 2.0 credentials (see [Authentication Setup](#authentication-setup))
+- A `.env` file containing:
+
+
+```env
+# Jira Cloud credentials
+JIRA_CLIENT_ID=your-atlassian-oauth-client-id
+JIRA_CLIENT_SECRET=your-atlassian-oauth-client-secret
+JIRA_CLOUD_ID=your-atlassian-cloud-id
+# Optional — defaults to http://localhost:8765/callback
+# JIRA_REDIRECT_URI=http://localhost:8765/callback
+
+# Application under test
+APP_BASE_URL=https://your-app.example.com
+APP_EMAIL=your-test-email@example.com
+APP_PASSWORD=your-test-password
+```
+
+---
+
+## Authentication Setup
+
+### Step 1 — Create an Atlassian OAuth 2.0 (3LO) app
+
+1. Go to <https://developer.atlassian.com/console/myapps/>
+2. Click **Create** → **OAuth 2.0 integration**
+3. Add callback URL: `http://localhost:8765/callback`
+4. Under **Permissions**, add Jira API scopes: `read:jira-user`, `read:jira-work`, `write:jira-work`
+5. Copy the **Client ID** and **Secret**
+
+### Step 2 — Find your Cloud ID
+
+```bash
+curl -H "Authorization: Bearer <any-valid-token>" \
+  https://api.atlassian.com/oauth/token/accessible-resources
+```
+
+Copy the `id` field for your Jira site.
+
+### Step 3 — Add to `.env`
+
+```env
+JIRA_CLIENT_ID=your-client-id
+JIRA_CLIENT_SECRET=your-client-secret
+JIRA_CLOUD_ID=your-cloud-id
+```
+
+### Step 4 — First run
+
+On first use a browser opens once for sign-in. The token is cached at `~/.jira-cache/jira-token.json` and silently refreshed for ~60 days.
+
+---
+
+
+## Commands
+
+All `qa-stlc` commands accept `--integration jira`:
+
+```bash
+qa-stlc init [--vscode] [--python <path>] --integration jira
+# Full bootstrap: pip install + Jira skills + MCP config with all 5 agents
+
+qa-stlc mcp-config [--vscode] [--print] [--python <path>] --integration jira
+# Write MCP config including qa-jira-manager + shared agents
+
+qa-stlc skills [--target claude|vscode|cursor|windsurf|both|print] --integration jira
+# Install Jira + shared skill files (excludes ADO-only generate-test-cases/)
+
+qa-stlc verify --integration jira
+# Check all 6 MCP servers are installed + Jira auth cache exists
+
+qa-stlc scaffold [--name <n>] [--dir <path>]
+# Scaffold a new Playwright + Cucumber + TypeScript QA project (same as ADO)
+
+stlc-migrate --source <existing> --helix <target> --integration jira [--conflict overwrite|skip|interactive] [--dry-run] [--json]
+# Migrate an existing Playwright (with or without Cucumber) project into the
+# Helix-QA layout, Jira variant. Installs Jira-only skills + .mcp.json with
+# qa-jira-manager (incl. JIRA_CLIENT_ID/SECRET/CLOUD_ID env passthrough),
+# the enhanced healer scaffold (LocatorHealer 8-strategy chain, LocatorRepository
+# schema v1, HealingDashboard with write-back), AGENT-BEHAVIOR.md,
+# ORCHESTRATION_RULES.md, and the 11-file BOILERPLATE allowlist. See
+# `skills/migrate-framework/SKILL.md` for the full pipeline reference.
+```
+
+### Makefile shortcuts
+
+```bash
+make bootstrap-jira                                       # one-shot: Jira skills + .mcp.json
+make migrate-jira SOURCE=<old> HELIX=<new>                # Jira migration with sensible defaults
+make migrate-jira SOURCE=<old> HELIX=<new> CONFLICT=overwrite   # re-migrate in place
+make audit-migration HELIX=<new>                          # framework_state + skills + healer scaffold + heal-store report
+```
+
+---
+
+## Usage
+
+Open your AI coding agent and use natural language:
+
+```
+# Full Jira pipeline — single prompt
+Run the full STLC pipeline for Jira issue PROJ-123
+
+# Step by step
+Fetch Jira issue PROJ-123 and analyse acceptance criteria
+Generate test cases for PROJ-123 and create them in Jira
+Generate Gherkin feature file for PROJ-123
+Generate Playwright TypeScript for the Gherkin I just created. The login page is at /auth/login
+Write the generated files to my Helix-QA project at /workspace/my-qa-project
+```
+
+---
+
+## Tool Reference
+
+
+### qa-jira-manager
+
+| Tool | Description |
+|---|---|
+| `fetch_jira_issue` | Fetch a Story, Bug, Task, or Sub-task with acceptance criteria and coverage hints. Routes Epics to `fetch_jira_epic_hierarchy`. |
+| `fetch_jira_epic_hierarchy` | Fetch an Epic and all child issues (Stories, Tasks, Bugs, Sub-tasks). |
+| `create_and_link_test_cases` | Create test case issues in Jira (type `Test`, falls back to `Task`) and link them via `is tested by`. Steps stored as ADF table — no Xray required. Returns `confirmation_required: true` for Epics. |
+| `get_linked_test_cases` | Return all test cases already linked to a Jira issue. Call before generating to power the deduplication gate. |
+
+### qa-gherkin-generator (shared)
+
+| Tool | Description |
+|---|---|
+| `fetch_work_item_for_gherkin` | Fetch a work item with AC context for Gherkin generation (pass Jira issue key). |
+| `validate_gherkin_content` | Structural validation — tags, scenario count, navigation steps. Returns `valid: bool` + `errors` + `warnings`. |
+| `attach_gherkin_to_work_item` | Validate and attach a `.feature` file (for Jira pipeline: saves locally or attaches via Jira REST). |
+
+### qa-playwright-generator (shared)
+
+| Tool | Description |
+|---|---|
+| `generate_playwright_code` | Generate `locators.ts`, `*Page.ts`, `*.steps.ts` from validated Gherkin + live AX-tree `context_map`. Blocks if `context_map` is absent. |
+| `scaffold_locator_repository` | Generate the six Helix-QA healing infrastructure files. |
+| `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. |
+
+### qa-helix-writer (shared)
+
+| 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 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. |
+
+---
+
+## MCP Config
+
+### VS Code / GitHub Copilot (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "qa-jira-manager":         { "command": "/path/to/.venv/bin/qa-jira-manager",
+                                  "env": { "JIRA_CLIENT_ID": "${env:JIRA_CLIENT_ID}",
+                                           "JIRA_CLIENT_SECRET": "${env:JIRA_CLIENT_SECRET}",
+                                           "JIRA_CLOUD_ID": "${env:JIRA_CLOUD_ID}" } },
+    "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" },
+    "qa-migration":            { "command": "/path/to/.venv/bin/stlc-migrate" },
+    "playwright": { "type": "http", "url": "http://localhost:8931/mcp" }
+  }
+}
+```
+
+### Claude Code (`.mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "qa-jira-manager":         { "command": "/path/to/.venv/bin/qa-jira-manager",
+                                  "env": { "JIRA_CLIENT_ID": "${env:JIRA_CLIENT_ID}",
+                                           "JIRA_CLIENT_SECRET": "${env:JIRA_CLIENT_SECRET}",
+                                           "JIRA_CLOUD_ID": "${env:JIRA_CLOUD_ID}" } },
+    "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" },
+    "qa-migration":            { "command": "/path/to/.venv/bin/stlc-migrate" },
+    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--isolated"] }
+  }
+}
+```
+
+> Run `qa-stlc mcp-config --integration jira [--vscode]` to generate this
+> manually, or run `stlc-migrate --integration jira` and the migration emits
+> `.mcp.json` automatically with absolute binary paths discovered from the
+> active venv.
+
+---
+
+
+## Skills Installed (Jira integration)
+
+| Skill | Purpose |
+|---|---|
+| `AGENT-BEHAVIOR.md` | Zero-inference contract. Read first. Always. |
+| `qa-jira-manager/` | Jira fetch, test case creation, and full pipeline orchestration |
+| `generate-gherkin/` | Gherkin generation from issue AC |
+| `generate-playwright-code/` | Gherkin + live browser → self-healing Playwright TypeScript |
+| `write-helix-files/` | Generated files → Helix-QA disk layout |
+| `deduplication-protocol/` | READ → DIFF → CREATE mandatory pre-flight gate |
+
+> `generate-test-cases/` is excluded for Jira-only installs — it is ADO work-item-scoped.
+
+---
+
+## Three-Layer Self-Healing Architecture
+
+Same as the ADO pipeline — the generated Playwright code uses identical healing infrastructure:
+
+| Layer | Class | What it heals |
+|---|---|---|
+| 1 — Locator | `LocatorHealer` | 8-strategy chain: cached → primary → **attribute** → **type-hint** → role → label → text → AI Vision. After match, introspects the live element and persists a specific single-attribute selector (`#id`, `[data-testid=…]`, etc.). |
+| 2 — Timing | `TimingHealer` | Network-trace drift → auto-adjusted timeouts → HealingDashboard |
+| 3 — Visual | `VisualIntentChecker` | Element screenshot diff at assertions → HealingDashboard |
+
+Refer to [ARCHITECTURE-ADO.md § Three-Layer Self-Healing Architecture](ARCHITECTURE-ADO.md#three-layer-self-healing-architecture) for full strategy ordering, env-var tuning (`HEAL_STRATEGY_ORDER`, `LOCATOR_TIMEOUT`, `LOCATOR_HEAL_ATTEMPTS`, etc.), and HealingDashboard write-back behaviour.
+
+---
+
+## 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>
+```
+
+### Inspect healed locators (migrated projects only)
+
+```bash
+ENV=qa4 npm run healix:dashboard   # http://localhost:7890 — Confirm / Revert
+ENV=qa4 npm run healix:review      # http://localhost:7891 — read-only mirror
+cat self-heals/healed-locators.qa4.json | jq .
+tail self-heals/heal.log
+```
+
+Confirm on a healed entry rewrites the source `*.locators.ts` file's
+`selector:` field — future runs use it as the primary probe.
+
+---
+
+## Documentation
+
+- [Quick Start: Azure DevOps](QUICKSTART-ADO.md)
+- [Quick Start: Jira Cloud](QUICKSTART-JIRA.md)
+- [Architecture: ADO](ARCHITECTURE-ADO.md)
+- [Architecture: Jira](ARCHITECTURE-JIRA.md)
+- [Walkthrough: ADO](WALKTHROUGH-ADO.md)
+- [Walkthrough: Jira](WALKTHROUGH-JIRA.md)
+
+---
+
+## License
+
+MIT

package/README.md

@@ -136,6 +136,55 @@ qa-stlc scaffold --name my-qa-project
 npx @playwright/mcp@latest --port 8931
 ```
 
+### Migrating an existing Playwright project
+
+If you have an existing Playwright (with or without Cucumber) project and want
+to bring it onto the agent rails, use `stlc-migrate`:
+
+```bash
+# Preview without writing
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --dry-run
+
+# Full migration — every agent skill, .mcp.json, healer scaffold, agent docs
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration both
+
+# ADO-only or Jira-only
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration jira
+
+# Refresh scaffold/skills on an existing migrated tree
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --conflict overwrite
+```
+
+The tool emits a complete agent-ready tree:
+
+| Layer | What lands |
+|---|---|
+| **Code** | Page objects + step files + locator files in `{selector, intent, stability}` format; every locator interaction routed through `LocatorHealer.*WithHealing`; non-BDD `.spec.*` files losslessly converted to one-scenario-per-test BDD |
+| **Healing infra** | 8-strategy `LocatorHealer` (attribute / type-hint / role / label / text / AI Vision), `LocatorRepository` with schema-versioned heal-only persist + per-env file suffix, `HealingDashboard` (read/write at 7890 + read-only mirror at `HEALIX_REVIEW_PORT`), `TimingHealer`, `VisualIntentChecker` |
+| **Agent assets** | `.mcp.json` (all 6 MCP servers + Playwright MCP), `.claude/skills/<name>/SKILL.md` per integration, `.github/copilot-instructions/<name>.md` flat copies, `AGENT-BEHAVIOR.md` + `ORCHESTRATION_RULES.md` at root + `.claude/` + `.github/` |
+| **Configs** | `cucumber.js` with `dotenv/config` as first `requireModule`, `package.json` with `dotenv` + `@types/*` companions, `tsconfig.json` aliases, `.env.example` documenting every healing knob |
+
+See `skills/migrate-framework/SKILL.md` for the full pipeline + environment variable reference.
+
+### Healing dashboard
+
+Once a migrated project has run any test that triggers healing, inspect the
+results via the dashboard:
+
+```bash
+ENV=qa4 npm run healix:dashboard     # full UI at http://localhost:7890
+ENV=qa4 npm run healix:review        # read-only mirror at http://localhost:7891
+```
+
+The dashboard shows each healed locator with its original selector, the
+specific selector that actually matched on the live page (introspected from
+the matched element — e.g. `#login-username`, not the generic search union),
+and **Confirm / Revert** buttons. **Confirm rewrites the original locator
+`.ts` file's `selector:` field** so the next run uses the verified selector
+as the primary probe — no healing chain required until the page changes
+again.
+
 ### Cost Tracking Activation
 
 **npm install** (`npm install -g @qa-gentic/stlc-agents`): Cost tracking is activated automatically after the Python servers are installed. No manual step required.

package/bin/postinstall.js

@@ -85,10 +85,20 @@ if (!python) {
   if (pip.status === 0) {
     ok("qa-gentic-stlc-agents installed.");
   } 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");
+    // Route pip's output through _write (/dev/tty) — process.stderr is swallowed
+    // by npm 7+ for global lifecycle scripts, so direct stderr writes vanish.
+    const combined = `${pip.stdout || ""}${pip.stderr || ""}`;
+    combined.split("\n").filter(Boolean).forEach((l) => console.log(d(l)));
+    warn("pip install failed.");
+    if (/externally-managed-environment/i.test(combined)) {
+      console.log("");
+      console.log(`${b("This Python is PEP 668-locked")} ${d("(Homebrew, Debian, Ubuntu).")} Install with one of:`);
+      console.log(`  ${C.cyan}brew install pipx && pipx install qa-gentic-stlc-agents${C.reset}   ${d("# isolated, commands on PATH")}`);
+      console.log(`  ${C.cyan}python3 -m pip install --user --break-system-packages qa-gentic-stlc-agents${C.reset}`);
+      console.log(`  ${C.cyan}python3 -m venv .venv && source .venv/bin/activate && pip install qa-gentic-stlc-agents${C.reset}`);
+    } else {
+      warn("Run manually: pip install qa-gentic-stlc-agents");
+    }
   }
 }
 

package/package.json

@@ -1,22 +1,29 @@
 {
   "name": "@qa-gentic/stlc-agents",
-  "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.",
+  "version": "1.0.29",
+  "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",
+    "playwright-migration",
+    "framework-migration",
     "mcp",
+    "mcp-server",
     "azure-devops",
+    "jira",
     "gherkin",
     "bdd",
+    "cucumber",
     "qa",
     "test-automation",
+    "self-healing",
+    "healing-dashboard",
+    "locator-healer",
     "claude",
-    "copilot",
     "claude-code",
-    "mcp-server",
-    "self-healing",
+    "copilot",
     "helix",
     "scaffold",
+    "stlc-migrate",
     "cursor",
     "windsurf"
   ],
@@ -38,13 +45,17 @@
     "skills/",
     ".github/agents/",
     "README.md",
-    "ORCHESTRATION_RULES.md"
+    "ORCHESTRATION_RULES.md",
+    "AGENT-BEHAVIOR.md",
+    "ARCHITECTURE-ADO.md",
+    "ARCHITECTURE-JIRA.md",
+    "QUICKSTART-ADO.md",
+    "QUICKSTART-JIRA.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');",
@@ -56,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.28",
     "commander": "^12.0.0",
     "which": "^4.0.0"
   },