@qa-gentic/agents 1.1.2

package/skills/qa-stlc/write-helix-files.md

@@ -0,0 +1,349 @@
+---
+name: write-helix-files
+description: >
+  Use this skill whenever generated Playwright TypeScript files (locators,
+  page objects, step definitions, feature files, healing infrastructure) need
+  to be placed into a local Helix-QA project on disk. Triggers after
+  generate-playwright-code or scaffold_locator_repository has produced a
+  'files' dict. Always calls inspect_helix_project first to determine whether
+  the framework exists, then picks the correct write mode automatically.
+compatibility:
+  tools:
+    - qa-helix-writer:inspect_helix_project
+    - qa-helix-writer:list_helix_tree
+    - qa-helix-writer:read_helix_file
+    - qa-helix-writer:write_helix_files
+    - qa-helix-writer:update_helix_file
+    - qa-playwright-generator:generate_playwright_code
+    - qa-playwright-generator:scaffold_locator_repository
+    - qa-playwright-generator:pre_validate_cucumber_steps
+---
+
+# Write Helix Files Skill
+
+## 🚨 HARD STOP RULES — Read Before Anything Else
+
+**HARD STOP 1 — NEVER use `create_file` as a fallback.**
+`create_file` bypasses deduplication, interface-adaptation rewrites, and file routing.
+If `write_helix_files` returns an error, diagnose and fix the payload — do NOT route
+around the tool. If the error cannot be resolved, surface it to the user verbatim.
+
+**HARD STOP 2 — NEVER create a new locator or step file when one already exists.**
+Before writing, call `list_helix_tree` to check what files are already on disk.
+If `src/locators/<foo>.locators.ts` already exists → it is the only correct target.
+Do NOT create `src/locators/<foo>-bar.locators.ts` or any variant filename.
+`write_helix_files` will merge new keys into the existing file automatically.
+
+**HARD STOP 3 — Step definitions MUST use Cucumber expressions, not regex.**
+`write_helix_files` runs a parenthesis-balance validator on every `*.steps.ts` file.
+Regex step patterns (e.g. `/^I click "([^"]*)"$/`) contain un-paired parentheses and
+will fail this check. Before submitting, verify every `When/Then/Given` block matches
+the Cucumber expression format:
+
+```typescript
+// ✅ Correct — Cucumber expression
+When('the user enters {string} in the username field', async function (value: string) {
+```
+
+```typescript
+// ❌ Rejected — regex pattern
+When(/^the user enters "([^"]*)" in the username field$/, async function (value: string) {
+```
+
+If `generate_playwright_code` produced regex patterns, use `pre_validate_cucumber_steps`
+to identify them, then convert to Cucumber expressions before calling `write_helix_files`.
+
+---
+
+Place files produced by `qa-playwright-generator` into a local Helix-QA
+project. The skill handles two situations automatically:
+
+| Situation | What happens |
+|---|---|
+| Framework does not exist yet | Scaffold infrastructure + write test files |
+| Framework already exists | Merge only the new work item's test files; never touch infrastructure |
+
+---
+
+## Helix-QA Directory Layout
+
+```
+<helix_root>/
+├── src/
+│   ├── locators/                   ← <kebab>.locators.ts          (merged per file)
+│   ├── pages/                      ← <Page>.page.ts               (merged per file)
+│   ├── test/
+│   │   ├── features/               ← <feature>.feature            (overwritten)
+│   │   └── steps/                  ← <feature>.steps.ts           (merged per file)
+│   ├── utils/
+│   │   └── locators/               ← LocatorHealer.ts etc.        (protected)
+│   └── config/
+│       └── cucumber.config.ts      ← profile blocks appended      (deduplicated)
+└── package.json
+```
+
+---
+
+## Decision Flow
+
+```
+inspect_helix_project(helix_root)
+         │
+         ├─ framework_state: "absent" or "partial"
+         │        │
+         │        └─ scaffold_locator_repository(...)
+         │                   │
+         │                   └─ write_helix_files(..., mode="scaffold_and_tests")
+         │                      Writes infra files that don't exist + test files
+         │
+         └─ framework_state: "present"
+                  │
+                  └─ write_helix_files(..., mode="tests_only")
+                     Merges only locators / page / steps / feature
+                     Infrastructure files are NEVER touched
+```
+
+---
+
+## Step-by-Step Workflow
+
+### Step 1 — Confirm helix_root
+
+Ask the user for the absolute path to the Helix-QA project root if not provided.
+This is the directory containing `package.json` and `src/`.
+
+---
+
+### Step 2 — Inspect framework state
+
+```
+qa-helix-writer:inspect_helix_project(helix_root)
+```
+
+Read the response:
+
+```json
+{
+  "framework_state": "present",
+  "existing_infra":  ["LocatorHealer.ts", "LocatorRepository.ts", ...],
+  "missing_infra":   [],
+  "recommendation":  "tests_only",
+  "message":         "Helix-QA framework is present. ..."
+}
+```
+
+**Act on `recommendation` directly — do not ask the user to choose the mode.**
+
+---
+
+### Step 3A — Framework absent or partial → scaffold first
+
+Only when `recommendation` is `"scaffold_and_tests"`:
+
+```
+# Generate infrastructure
+qa-playwright-generator:scaffold_locator_repository(
+  output_dir               = "src/utils/locators",
+  enable_ai_vision         = true,
+  repository_path          = "test-results/locator-repository.json",
+  dashboard_port           = 7890,
+  enable_timing_healing    = true,
+  enable_visual_regression = true,
+  enable_devtools_healer   = true
+)
+```
+
+Then proceed to Step 4 with `mode="scaffold_and_tests"`.
+
+---
+
+### Step 3B — Framework present → skip scaffold
+
+When `recommendation` is `"tests_only"`, skip Step 3A entirely.
+Proceed to Step 4 with `mode="tests_only"`.
+
+---
+
+### Step 4 — Generate test files
+
+Run `generate_playwright_code` for the work item's Gherkin feature:
+
+```
+qa-playwright-generator:generate_playwright_code(
+  gherkin_content   = <validated .feature file content>,
+  page_class_name   = "<PageClass>",
+  app_name          = "<app>",
+  healing_strategy  = "role-label-text-ai",
+  enable_visual_regression = true,
+  enable_timing_healing    = true
+)
+```
+
+---
+
+### Step 5 — Write files
+
+```
+qa-helix-writer:write_helix_files(
+  helix_root = "<helix_root>",
+  files      = <files dict from generate_playwright_code>,
+  mode       = "<recommendation from Step 2>"
+)
+```
+
+The tool handles everything automatically:
+
+**File routing:**
+
+| Generator key | Helix destination |
+|---|---|
+| `src/pages/<k>/locators.ts` | `src/locators/<k>.locators.ts` |
+| `src/pages/<k>/<k>.page.ts` | `src/pages/<k>.page.ts` |
+| `src/test/steps/<k>.steps.ts` | `src/test/steps/<k>.steps.ts` |
+| `*.feature` | `src/test/features/<k>.feature` |
+| `config/cucumber.js (add this profile)` | `src/config/cucumber.config.ts` (appended) |
+| `src/utils/locators/Locator*.ts` | `src/utils/locators/<file>` |
+
+**Deduplication per file type:**
+
+| File | Behaviour when file already exists |
+|---|---|
+| `locators.ts` | New const-object keys appended; existing keys skipped |
+| `*.steps.ts` | New step blocks appended; steps with matching regex skipped |
+| `*.page.ts` | New async methods appended; existing method names skipped |
+| `*.feature` | Overwritten (Gherkin is the source of truth) |
+| `cucumber.config.ts` | Profile block appended; duplicate profile names skipped |
+| Infrastructure `*.ts` | Protected in `tests_only`; written-if-absent in `scaffold_and_tests` |
+
+**Interface adaptation (applied automatically):**
+
+| Generated code | Rewritten to |
+|---|---|
+| `repo.updateHealed(k, s, …)` | `repo.setHealed(k, s)` |
+| `repo.getBBox(key)` | `null` |
+| `repo.incrementSuccess/Failure(…)` | removed |
+| `repo.queueSuggestion(…)` | removed |
+| `repo.updateBoundingBox(…)` | removed |
+| `fixture().logger` | `this.logger` |
+| `fixture().locatorRepository` | `this.repo` |
+| `fixture().page` | `this.page` |
+| `import { Logger } from "winston"` | `import { HealerLogger }` |
+| `EnvironmentManager` | Helix `environment` singleton |
+
+---
+
+### Step 6 — Verify the response
+
+```json
+{
+  "summary": { "requested": 4, "written": 4, "skipped": 0 },
+  "deduplication": {
+    "src/locators/checkout.locators.ts": {
+      "type": "locators",
+      "added_keys":   ["checkoutBtn", "summaryTotal"],
+      "skipped_keys": ["submitBtn", "cancelBtn"]
+    },
+    "src/test/steps/checkout.steps.ts": {
+      "type": "steps",
+      "added_patterns":   ["user completes checkout"],
+      "skipped_patterns": ["user logs in"]
+    }
+  }
+}
+```
+
+Report the `deduplication` summary to the user so they can confirm which
+symbols were added vs skipped.
+
+**Skipped reasons to handle:**
+
+| Reason | Action |
+|---|---|
+| `"empty content"` | Normal — generator produced no content for that file |
+| `"profile '…' already exists"` | Normal — no action needed |
+| `"infrastructure file already exists"` | Normal in `tests_only` mode |
+| `"infrastructure file — skipped in tests_only mode"` | Normal |
+| Any `OSError` | Report path and error to user |
+
+---
+
+## Scaffold vs Regenerate Infrastructure
+
+**First-time setup** (`framework_state` is `"absent"` or `"partial"`):
+
+```
+scaffold_locator_repository(...)   # generate 6 infra files
+write_helix_files(..., mode="scaffold_and_tests")
+# Writes missing infra files + test files
+```
+
+**Intentional infrastructure regeneration** (user explicitly requests it):
+
+```
+write_helix_files(..., mode="scaffold_and_tests", force_scaffold=true)
+# Overwrites ALL infra files — use deliberately
+```
+
+**Never** call with `force_scaffold=true` unless the user has explicitly asked
+to regenerate the healing infrastructure.
+
+---
+
+## Quality Gates
+
+Before calling `write_helix_files`:
+
+- [ ] `inspect_helix_project` has been called and `recommendation` noted.
+- [ ] `list_helix_tree` has been called — existing file names recorded to prevent new-file creation.
+- [ ] Every `*.steps.ts` in the `files` dict uses Cucumber expression syntax (not regex).
+- [ ] `pre_validate_cucumber_steps` has been called on each `*.steps.ts` and returned `valid: true`.
+- [ ] `mode` matches `recommendation` — never override without user instruction.
+- [ ] `force_scaffold` is `false` unless the user explicitly asked to regenerate.
+- [ ] The `files` dict comes directly from `generate_playwright_code` or
+      `scaffold_locator_repository` — never manually constructed.
+- [ ] After writing, the `deduplication` field has been reviewed and reported.
+
+---
+
+## Failure Recovery Procedure
+
+When `write_helix_files` returns an error:
+
+### 1 — Parenthesis / bracket balance error in a steps file
+
+**Symptom:** Tool returns a message about parenthesis balance, bracket imbalance,
+or validator failure on a `*.steps.ts` file.
+
+**Root cause:** The step definitions contain regex patterns. Regex uses un-paired
+parentheses (`(`, `)`) that the file validator counts as unbalanced.
+
+**Fix:**
+1. Call `pre_validate_cucumber_steps` on the failing steps file content — it identifies
+   every offending pattern and provides a ready-to-paste Cucumber expression replacement.
+2. Convert any regex patterns to Cucumber expressions:
+   - `"([^"]*)"` → `{string}`
+   - `(\d+)` → `{int}`
+   - `/^…$/` wrapper → plain quoted string
+3. Retry `write_helix_files` with the corrected `files` dict.
+4. Do NOT call `create_file` at any point.
+
+### 2 — `OSError` / path error
+
+**Symptom:** Tool returns an `OSError`, `FileNotFoundError`, or similar path message.
+
+**Fix:** Report the exact path and error to the user. Do not attempt to create the
+directory or file manually unless the user explicitly instructs it.
+
+### 3 — Any other tool error
+
+**Fix:** Report the raw error text to the user verbatim. Ask: "How would you like
+to proceed?" Do not attempt any workaround autonomously.
+
+---
+
+## Known Tool Limitations (Document These for Future Agent Runs)
+
+| Limitation | Description | Workaround |
+|---|---|---|
+| Parenthesis validator | Rejects step files with regex step patterns; error message names regex preprocessor as cause and prescribes Cucumber expressions | Use `pre_validate_cucumber_steps` before submitting to catch and fix offending patterns |
+| `update_helix_file` for single-file edits | Use `qa-helix-writer:update_helix_file` for targeted single-file changes instead of re-submitting the full `files` dict | Pass `relative_path` and the new content directly; set `force_overwrite=true` only when replacing existing content |

package/src/cmd-init.js

@@ -0,0 +1,84 @@
+/**
+ * cmd-init.js — `qa-stlc init`
+ *
+ * Full bootstrap: install Python agents + skills + MCP config.
+ */
+"use strict";
+
+const { execSync, spawnSync } = require("child_process");
+const path = require("path");
+const fs   = require("fs");
+
+const cmdSkills    = require("./cmd-skills");
+const cmdMcpConfig = require("./cmd-mcp-config");
+
+const C = {
+  reset: "\x1b[0m", bold: "\x1b[1m",
+  green: "\x1b[32m", cyan: "\x1b[36m",
+  yellow: "\x1b[33m", red: "\x1b[31m", dim: "\x1b[2m",
+};
+const ok   = (m) => console.log(`${C.green}✓${C.reset}  ${m}`);
+const info = (m) => console.log(`${C.cyan}→${C.reset}  ${m}`);
+const warn = (m) => console.log(`${C.yellow}⚠${C.reset}  ${m}`);
+const die  = (m) => { console.error(`${C.red}✗${C.reset}  ${m}`); process.exit(1); };
+
+module.exports = async function init(opts) {
+  console.log(`\n${C.bold}QA STLC Agents — init${C.reset}\n`);
+
+  // ── 1. Check Python ──────────────────────────────────────────────────────
+  const python = opts.python || "python3";
+  info(`Checking Python (${python})…`);
+  const pyCheck = spawnSync(python, ["--version"], { encoding: "utf8" });
+  if (pyCheck.status !== 0) {
+    die(`Python not found at '${python}'. Install Python 3.10+ or pass --python <path>.`);
+  }
+  const pyVersion = (pyCheck.stdout || pyCheck.stderr || "").trim();
+  const match = pyVersion.match(/Python (\d+)\.(\d+)/);
+  if (!match || parseInt(match[1]) < 3 || parseInt(match[2]) < 10) {
+    die(`Python 3.10+ required, found: ${pyVersion}`);
+  }
+  ok(`${pyVersion} found.`);
+
+  // ── 2. pip install qa-gentic-agents ────────────────────────────────────────
+  info("Installing qa-gentic-agents (pip)…");
+  const pip = spawnSync(python, ["-m", "pip", "install", "qa-gentic-agents>=1.0.1", "--quiet"], {
+    stdio: "inherit",
+    encoding: "utf8",
+  });
+  if (pip.status !== 0) {
+    die("pip install failed. Run manually: pip install qa-gentic-agents");
+  }
+  ok("qa-gentic-agents installed.");
+
+  // ── 3. Install skills ────────────────────────────────────────────────────
+  info("Installing skills…");
+  const skillTarget = opts.vscode ? "both" : "claude";
+  await cmdSkills({ target: skillTarget });
+
+  // ── 4. Write MCP config ──────────────────────────────────────────────────
+  info("Writing MCP config…");
+  await cmdMcpConfig({
+    vscode: opts.vscode || false,
+    print: false,
+    python: python,
+    playwrightPort: "8931",
+  });
+
+  // ── 5. Done ──────────────────────────────────────────────────────────────
+  console.log(`
+${C.bold}Done!${C.reset} Next steps:
+
+  Start Playwright MCP (required for live locator verification):
+  ${C.cyan}npx @playwright/mcp@latest --port 8931${C.reset}
+
+  ${C.bold}Claude Code${C.reset}
+    Open this project in Claude Code, then run:
+    ${C.cyan}/mcp${C.reset}   — verify all 5 servers are loaded
+    ${C.cyan}/skills${C.reset} — browse installed skills
+
+  ${C.bold}GitHub Copilot${C.reset}
+    Skills are at .github/copilot-instructions/
+    MCP config is at .vscode/mcp.json
+    Reload VS Code window to pick up the servers.
+`);
+};

package/src/cmd-mcp-config.js

@@ -0,0 +1,177 @@
+/**
+ * cmd-mcp-config.js — `qa-stlc mcp-config`
+ *
+ * Generates .mcp.json (Claude Code) or .vscode/mcp.json (GitHub Copilot / VS Code).
+ */
+"use strict";
+
+const path     = require("path");
+const fs       = require("fs");
+const { spawnSync } = require("child_process");
+
+const C = {
+  reset: "\x1b[0m", bold: "\x1b[1m",
+  green: "\x1b[32m", cyan: "\x1b[36m",
+  yellow: "\x1b[33m", red: "\x1b[31m", dim: "\x1b[2m",
+};
+const ok   = (m) => console.log(`${C.green}✓${C.reset}  ${m}`);
+const info = (m) => console.log(`${C.cyan}→${C.reset}  ${m}`);
+const warn = (m) => console.log(`${C.yellow}⚠${C.reset}  ${m}`);
+
+const CWD = process.cwd();
+const IS_WIN = process.platform === "win32";
+const EXT = IS_WIN ? ".exe" : "";
+
+const AGENT_NAMES = [
+  "qa-test-case-manager",
+  "qa-gherkin-generator",
+  "qa-playwright-generator",
+  "qa-helix-writer",
+];
+
+/**
+ * Locate the binary for an agent.
+ * Priority: .venv → --python dir → system PATH → python sys.executable dir → macOS framework dirs
+ */
+function findBinary(name, pythonBin) {
+  // 1. .venv in cwd
+  const venvBin = IS_WIN
+    ? path.join(CWD, ".venv", "Scripts", name + EXT)
+    : path.join(CWD, ".venv", "bin", name);
+  if (fs.existsSync(venvBin)) return venvBin;
+
+  // 2. dir of --python flag binary
+  if (pythonBin && pythonBin !== "python3" && pythonBin !== "python") {
+    const candidate = path.join(path.dirname(pythonBin), name + EXT);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  // 3. system PATH via which/where
+  const which = spawnSync(IS_WIN ? "where" : "which", [name], { encoding: "utf8" });
+  if (which.status === 0 && which.stdout.trim()) return which.stdout.trim().split("\n")[0].trim();
+
+  // 4. ask Python where its own bin dir is (catches framework installs not on PATH)
+  for (const py of ["python3", "python"]) {
+    const r = spawnSync(py, ["-c", "import sys, os; print(os.path.dirname(sys.executable))"], { encoding: "utf8" });
+    if (r.status === 0 && r.stdout.trim()) {
+      const candidate = path.join(r.stdout.trim(), name + EXT);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+
+  // 5. macOS Python.org framework fallback
+  if (!IS_WIN) {
+    const frameworkDirs = [
+      "/Library/Frameworks/Python.framework/Versions/3.13/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.12/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.11/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.10/bin",
+    ];
+    for (const dir of frameworkDirs) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+function buildClaudeConfig(pythonBin, playwrightPort) {
+  const servers = {};
+  const missing = [];
+
+  for (const name of AGENT_NAMES) {
+    const bin = findBinary(name, pythonBin);
+    if (bin) {
+      servers[name] = { command: bin };
+    } else {
+      missing.push(name);
+      servers[name] = { command: `/path/to/.venv/bin/${name}`, "_comment": "NOT FOUND — run: pip install qa-gentic-agents" };
+    }
+  }
+
+  servers["playwright"] = {
+    type: "url",
+    url: `ws://localhost:${playwrightPort}`,
+  };
+
+  return { config: { mcpServers: servers }, missing };
+}
+
+function buildVscodeConfig(pythonBin, playwrightPort) {
+  const servers = {};
+  const missing = [];
+
+  for (const name of AGENT_NAMES) {
+    const bin = findBinary(name, pythonBin);
+    if (bin) {
+      servers[name] = { command: bin };
+    } else {
+      missing.push(name);
+      servers[name] = { command: `/path/to/.venv/bin/${name}`, "_comment": "NOT FOUND — run: pip install qa-gentic-agents" };
+    }
+  }
+
+  servers["playwright"] = {
+    type: "http",
+    url: `http://localhost:${playwrightPort}/mcp`,
+  };
+
+  return { config: { servers }, missing };
+}
+
+function printNextSteps(mode, playwrightPort) {
+  const isVscode = mode === "vscode";
+  console.log(`
+  ${C.dim}Start Playwright MCP before running generation workflows:${C.reset}
+  npx @playwright/mcp@latest --port ${playwrightPort}
+  ${C.dim}headless (CI): npx @playwright/mcp@latest --headless --port ${playwrightPort}${C.reset}
+
+  ${isVscode
+    ? `Reload VS Code window — all 5 MCP servers will appear in the MCP panel.`
+    : `In Claude Code, run /mcp to verify all 5 servers are loaded.`
+  }
+`);
+}
+
+module.exports = async function mcpConfig(opts) {
+  const useVscode      = opts.vscode || false;
+  const printOnly      = opts.print  || false;
+  const pythonBin      = opts.python || "python3";
+  const playwrightPort = opts.playwrightPort || "8931";
+
+  if (printOnly) {
+    const { config: claudeCfg } = buildClaudeConfig(pythonBin, playwrightPort);
+    const { config: vscodeCfg } = buildVscodeConfig(pythonBin, playwrightPort);
+    console.log("\n=== Claude Code (.mcp.json) ===");
+    console.log(JSON.stringify(claudeCfg, null, 2));
+    console.log("\n=== VS Code (.vscode/mcp.json) ===");
+    console.log(JSON.stringify(vscodeCfg, null, 2));
+    printNextSteps("both", playwrightPort);
+    return;
+  }
+
+  if (useVscode) {
+    const { config, missing } = buildVscodeConfig(pythonBin, playwrightPort);
+    const dir = path.join(CWD, ".vscode");
+    fs.mkdirSync(dir, { recursive: true });
+    const out = path.join(dir, "mcp.json");
+    fs.writeFileSync(out, JSON.stringify(config, null, 2) + "\n", "utf8");
+    ok(`Written → .vscode/mcp.json`);
+    if (missing.length) {
+      warn(`${missing.length} agent(s) not found — run: pip install qa-gentic-agents`);
+      missing.forEach((m) => warn(`  missing: ${m}`));
+    }
+    printNextSteps("vscode", playwrightPort);
+  } else {
+    const { config, missing } = buildClaudeConfig(pythonBin, playwrightPort);
+    const out = path.join(CWD, ".mcp.json");
+    fs.writeFileSync(out, JSON.stringify(config, null, 2) + "\n", "utf8");
+    ok(`Written → .mcp.json`);
+    if (missing.length) {
+      warn(`${missing.length} agent(s) not found — run: pip install qa-gentic-agents`);
+      missing.forEach((m) => warn(`  missing: ${m}`));
+    }
+    printNextSteps("claude", playwrightPort);
+  }
+};