qaa-agent 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qaa-agent",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "QA Automation Agent for Claude Code — multi-agent pipeline that analyzes repos, generates tests, validates, and creates PRs",
   "bin": {
     "qaa-agent": "./bin/install.cjs"
@@ -26,6 +26,7 @@
     "agents/",
     "workflows/",
     "templates/",
+    "docs/",
     ".claude/commands/",
     ".claude/skills/",
     ".claude/settings.json",

package/workflows/qa-pr.md

@@ -0,0 +1,389 @@
+<purpose>
+Create a draft PR from QA artifacts (test files, POMs, fixtures, reports) already on disk. Detects git platform (GitHub, Azure DevOps, GitLab), applies the team's branch naming convention (saved in preferences), stages only test/QA files, and creates a draft PR with a summary. Standalone command -- does not require the full pipeline to have run.
+</purpose>
+
+<required_reading>
+- `CLAUDE.md` -- Git workflow section (branch naming, commit conventions, PR template)
+- `~/.claude/qaa/MY_PREFERENCES.md` -- Branch naming convention (if saved)
+- `templates/pr-template.md` -- PR body template
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+## Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` to extract optional flags.
+
+**Supported arguments:**
+
+| Flag | Example | Description |
+|------|---------|-------------|
+| `--ticket` | `--ticket PROJ-123` | Ticket/issue ID for branch name |
+| `--title` | `--title "login tests"` | Short description for branch and PR title |
+| `--scope` | `--scope unit` | Limit to file type: unit, api, e2e, all (default: all) |
+| `--files` | `--files tests/unit/auth*` | Explicit file glob to include |
+| `--base` | `--base develop` | Target branch for PR (default: auto-detect) |
+
+**If no arguments provided:**
+
+Scan for QA artifacts to include:
+1. Check `.qa-output/` for generated test files, POMs, fixtures
+2. Check current git status for unstaged/untracked test files
+3. If nothing found, print error and STOP:
+```
+Error: No QA artifacts found to deliver.
+Run /qa-start, /create-test, or /qa-map first to generate artifacts.
+```
+</step>
+
+<step name="detect_platform">
+## Step 2: Detect Git Platform
+
+```bash
+REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
+```
+
+**Platform detection from remote URL:**
+
+| Pattern | Platform | CLI Tool | PR Command |
+|---------|----------|----------|------------|
+| `github.com` or `gh:` | GitHub | `gh` | `gh pr create` |
+| `dev.azure.com` or `visualstudio.com` or `azure` | Azure DevOps | `az` | `az repos pr create` |
+| `gitlab.com` or `gitlab` | GitLab | `glab` | `glab mr create` |
+
+```bash
+PLATFORM=""
+PR_CLI=""
+
+if echo "$REMOTE_URL" | grep -qi "github"; then
+  PLATFORM="github"
+  PR_CLI="gh"
+elif echo "$REMOTE_URL" | grep -qi "dev.azure.com\|visualstudio.com\|azure"; then
+  PLATFORM="azure"
+  PR_CLI="az"
+elif echo "$REMOTE_URL" | grep -qi "gitlab"; then
+  PLATFORM="gitlab"
+  PR_CLI="glab"
+else
+  PLATFORM="unknown"
+fi
+```
+
+**If platform is unknown:**
+```
+CHECKPOINT:
+type: human-action
+blocking: "Cannot detect git platform from remote URL"
+details: "Remote URL: ${REMOTE_URL}"
+awaiting: "Which platform? (github / azure / gitlab)"
+```
+
+**Verify CLI tool is available and authenticated:**
+
+For GitHub:
+```bash
+gh auth status 2>/dev/null
+```
+
+For Azure DevOps:
+```bash
+az account show 2>/dev/null
+```
+
+For GitLab:
+```bash
+glab auth status 2>/dev/null
+```
+
+If CLI tool is not installed or not authenticated:
+```
+Error: ${PR_CLI} CLI not found or not authenticated.
+
+GitHub:  Install from https://cli.github.com, then run: gh auth login
+Azure:   Install from https://aka.ms/azure-cli, then run: az login
+GitLab:  Install from https://gitlab.com/gitlab-org/cli, then run: glab auth login
+```
+</step>
+
+<step name="resolve_branch_convention">
+## Step 3: Resolve Branch Naming Convention
+
+**Check saved preferences:**
+```bash
+BRANCH_PATTERN=""
+if [ -f ~/.claude/qaa/MY_PREFERENCES.md ]; then
+  # Look for branch pattern in Workflow section
+  BRANCH_PATTERN=$(grep -A1 "branch.*pattern\|branch.*convention\|branch.*naming" ~/.claude/qaa/MY_PREFERENCES.md | tail -1)
+fi
+```
+
+**If no saved convention, ask the user:**
+
+```
+No branch naming convention configured.
+What pattern does your team use?
+
+  1) feature/{ticket}-{description}
+  2) test/{ticket}-{description}
+  3) qa/{ticket}-{description}
+  4) {user}/{ticket}-{description}
+  5) feature/QAA-{date}-{description}
+  6) Custom (write your own with placeholders)
+
+Placeholders: {ticket}, {date}, {description}, {user}, {scope}
+```
+
+**On user response:**
+- Save the chosen pattern to `~/.claude/qaa/MY_PREFERENCES.md` under `## Workflow` section
+- Format: `- Branch naming convention: {pattern} — (added {date}, context: "user configured branch pattern via /qa-pr")`
+
+**Build actual branch name from pattern:**
+
+Replace placeholders with real values:
+- `{ticket}` -- from `--ticket` flag, or prompt user if pattern requires it
+- `{date}` -- today's date YYYY-MM-DD
+- `{description}` -- from `--title` flag, sanitized to kebab-case (lowercase, hyphens, no special chars)
+- `{user}` -- from `git config user.name`, sanitized to kebab-case
+- `{scope}` -- from `--scope` flag or "qa"
+
+```bash
+BRANCH_NAME=$(echo "$BRANCH_PATTERN" | sed \
+  -e "s/{ticket}/${TICKET}/g" \
+  -e "s/{date}/${DATE}/g" \
+  -e "s/{description}/${DESCRIPTION}/g" \
+  -e "s/{user}/${USER}/g" \
+  -e "s/{scope}/${SCOPE}/g")
+```
+
+**If ticket is required by pattern but not provided:**
+```
+Your branch pattern requires a ticket ID: {pattern}
+Provide ticket ID (e.g., PROJ-123):
+```
+</step>
+
+<step name="collect_files">
+## Step 4: Collect Files to Include
+
+Gather all QA artifacts that should go into the PR.
+
+**If `--files` flag provided:** Use that glob directly.
+
+**Otherwise, auto-detect:**
+
+```bash
+QA_FILES=()
+
+# 1. Generated test files
+find . -path '*/tests/*' -name '*.spec.*' -o -name '*.test.*' -o -name '*.e2e.*' -o -name '*.cy.*' | while read f; do
+  QA_FILES+=("$f")
+done
+
+# 2. Page Object Models
+find . -path '*/pages/*' -o -path '*/page-objects/*' | grep -E '\.(ts|js|py)$' | while read f; do
+  QA_FILES+=("$f")
+done
+
+# 3. Fixtures
+find . -path '*/fixtures/*' -name '*-data.*' | while read f; do
+  QA_FILES+=("$f")
+done
+
+# 4. Config files (test configs only)
+for cfg in playwright.config.* jest.config.* vitest.config.* cypress.config.* pytest.ini conftest.py; do
+  [ -f "$cfg" ] && QA_FILES+=("$cfg")
+done
+
+# 5. QA output reports
+find .qa-output -name '*.md' 2>/dev/null | while read f; do
+  QA_FILES+=("$f")
+done
+```
+
+**Apply scope filter if `--scope` provided:**
+- `unit` -- only `*.unit.spec.*`, `*.test.*` files
+- `api` -- only `*.api.spec.*` files
+- `e2e` -- only `*.e2e.spec.*`, `*.cy.*` files + POMs
+- `all` -- everything (default)
+
+**If no files found:** Print error and STOP.
+
+**Security check:**
+- Exclude any `.env`, `credentials.*`, `secrets.*`, `*.key`, `*.pem` files
+- Warn if any file contains hardcoded passwords/tokens (grep for common patterns)
+</step>
+
+<step name="confirm_with_user">
+## Step 5: Confirmation Checkpoint
+
+Present the plan to the user and wait for confirmation.
+
+```
+╔══════════════════════════════════════════╗
+║  /qa-pr — Create QA Pull Request        ║
+╠══════════════════════════════════════════╣
+║                                          ║
+║  Platform:  {PLATFORM}                   ║
+║  Branch:    {BRANCH_NAME}                ║
+║  Target:    {DEFAULT_BRANCH}             ║
+║  Type:      Draft PR                     ║
+║                                          ║
+║  Files ({FILE_COUNT}):                   ║
+║    {N} test specs                        ║
+║    {N} page objects                      ║
+║    {N} fixtures                          ║
+║    {N} config files                      ║
+║    {N} QA reports                        ║
+║                                          ║
+╚══════════════════════════════════════════╝
+
+Proceed? (y/n)
+```
+
+**If user says no:** Print "Cancelled." and STOP.
+</step>
+
+<step name="create_branch_and_commit">
+## Step 6: Create Branch and Commit
+
+**Detect default branch:**
+```bash
+# GitHub
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null)
+
+# Azure DevOps
+if [ -z "$DEFAULT_BRANCH" ]; then
+  DEFAULT_BRANCH=$(az repos show --query 'defaultBranch' -o tsv 2>/dev/null | sed 's|refs/heads/||')
+fi
+
+# GitLab
+if [ -z "$DEFAULT_BRANCH" ]; then
+  DEFAULT_BRANCH=$(glab repo view --json default_branch --jq '.default_branch' 2>/dev/null)
+fi
+
+# Fallback
+DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
+```
+
+**Override with `--base` flag if provided.**
+
+**Create branch:**
+```bash
+git checkout -b "$BRANCH_NAME" "origin/$DEFAULT_BRANCH"
+```
+
+**Handle collision:**
+```bash
+if git rev-parse --verify "$BRANCH_NAME" 2>/dev/null; then
+  SUFFIX=2
+  while git rev-parse --verify "${BRANCH_NAME}-${SUFFIX}" 2>/dev/null; do
+    SUFFIX=$((SUFFIX + 1))
+  done
+  BRANCH_NAME="${BRANCH_NAME}-${SUFFIX}"
+  git checkout -b "$BRANCH_NAME" "origin/$DEFAULT_BRANCH"
+fi
+```
+
+**Stage and commit:**
+```bash
+git add ${QA_FILES[@]}
+git commit -m "qa(pr): add ${FILE_COUNT} QA artifacts — ${DESCRIPTION}"
+```
+</step>
+
+<step name="push_and_create_pr">
+## Step 7: Push and Create PR
+
+**Push branch:**
+```bash
+git push -u origin "$BRANCH_NAME"
+```
+
+**Build PR body from template (if available) or minimal summary:**
+
+If `templates/pr-template.md` exists and QA reports are available, populate it.
+Otherwise use minimal body:
+
+```markdown
+## QA Artifacts
+
+${FILE_COUNT} files added:
+- ${test_count} test specs
+- ${pom_count} page objects
+- ${fixture_count} fixtures
+
+${TICKET_REF}
+
+---
+Generated by QAA (QA Automation Agent)
+```
+
+**Create PR by platform:**
+
+**GitHub:**
+```bash
+PR_URL=$(gh pr create \
+  --draft \
+  --title "qa: ${DESCRIPTION}" \
+  --body "${PR_BODY}")
+```
+
+**Azure DevOps:**
+```bash
+PR_URL=$(az repos pr create \
+  --draft \
+  --title "qa: ${DESCRIPTION}" \
+  --description "${PR_BODY}" \
+  --source-branch "$BRANCH_NAME" \
+  --target-branch "$DEFAULT_BRANCH" \
+  --query 'url' -o tsv)
+```
+
+**GitLab:**
+```bash
+PR_URL=$(glab mr create \
+  --draft \
+  --title "qa: ${DESCRIPTION}" \
+  --description "${PR_BODY}" \
+  --source-branch "$BRANCH_NAME" \
+  --target-branch "$DEFAULT_BRANCH" \
+  --yes)
+```
+
+**On failure:** Print error with branch name so user can create PR manually.
+</step>
+
+<step name="print_result">
+## Step 8: Print Result
+
+```
+╔══════════════════════════════════════════╗
+║  PR Created ✓                            ║
+╠══════════════════════════════════════════╣
+║                                          ║
+║  ${PR_URL}                               ║
+║                                          ║
+║  Branch:   ${BRANCH_NAME}                ║
+║  Target:   ${DEFAULT_BRANCH}             ║
+║  Files:    ${FILE_COUNT}                 ║
+║  Status:   Draft                         ║
+║                                          ║
+╚══════════════════════════════════════════╝
+```
+</step>
+
+</process>
+
+<error_handling>
+| Error | Cause | Action |
+|-------|-------|--------|
+| No QA artifacts found | Nothing generated yet | Print error, suggest /qa-start or /create-test |
+| Platform not detected | Unusual remote URL | Ask user to specify platform |
+| CLI not installed | gh/az/glab missing | Print install instructions for detected platform |
+| CLI not authenticated | Not logged in | Print auth command for detected platform |
+| Branch already exists | Name collision | Auto-append numeric suffix |
+| Push fails | Permission or network | Print error, keep local commits |
+| PR creation fails | API error | Print error with branch name for manual PR creation |
+| Ticket required but missing | Pattern uses {ticket} | Prompt user for ticket ID |
+</error_handling>