ctx-cc 3.3.3 → 3.3.5

package/commands/qa.md

@@ -0,0 +1,625 @@
+---
+name: ctx:qa
+description: Full system QA - crawl every page, click every button, find all issues, create fix tasks. WCAG 2.1 AA compliant accessibility testing.
+---
+
+<objective>
+Run comprehensive end-to-end quality assurance on the entire application using industry best practices.
+
+This command:
+1. Discovers all routes/pages in the app
+2. Crawls every page systematically
+3. Clicks every button, link, and interactive element
+4. Fills and submits every form
+5. Tests accessibility (WCAG 2.1 AA compliance)
+6. Tests responsive design (mobile, tablet, desktop)
+7. Checks keyboard navigation
+8. Monitors performance (slow requests, large assets)
+9. Creates a comprehensive QA report with traces
+10. Generates fix tasks organized by section/page
+</objective>
+
+<usage>
+```bash
+/ctx:qa                     # Full system QA (all checks)
+/ctx:qa --pages             # List all discovered pages first
+/ctx:qa --section "auth"    # QA specific section only
+/ctx:qa --a11y-only         # Accessibility audit only (WCAG 2.1 AA)
+/ctx:qa --visual-only       # Visual regression only (3 viewports)
+/ctx:qa --resume            # Resume interrupted QA session
+/ctx:qa --report            # Show last QA report
+```
+</usage>
+
+<process>
+
+## Step 1: Discover Application Structure
+
+### 1.1 Read Codebase Map
+```bash
+# Load route definitions from REPO-MAP
+cat .ctx/REPO-MAP.md | grep -i "route\|page\|screen"
+```
+
+### 1.2 Discover Routes Programmatically
+```javascript
+// For React/Next.js
+mcp__playwright__browser_evaluate({
+  function: `
+    // Extract routes from React Router
+    const routes = [];
+    document.querySelectorAll('a[href^="/"]').forEach(a => {
+      routes.push(a.getAttribute('href'));
+    });
+    return [...new Set(routes)];
+  `
+})
+
+// For file-based routing (Next.js, Nuxt)
+// Parse pages/ or app/ directory
+```
+
+### 1.3 Build Page Inventory
+```markdown
+## Discovered Pages
+
+| # | Route | Type | Auth Required |
+|---|-------|------|---------------|
+| 1 | / | home | no |
+| 2 | /login | auth | no |
+| 3 | /dashboard | main | yes |
+| 4 | /settings | settings | yes |
+| 5 | /users | admin | yes |
+...
+```
+
+Save to `.ctx/qa/PAGE_INVENTORY.md`
+
+## Step 2: Plan QA Sessions
+
+### 2.1 Group by Section
+```
+Section: Authentication (3 pages)
+  - /login
+  - /register
+  - /forgot-password
+
+Section: Dashboard (5 pages)
+  - /dashboard
+  - /dashboard/analytics
+  - /dashboard/reports
+  ...
+
+Section: Settings (4 pages)
+  - /settings
+  - /settings/profile
+  - /settings/security
+  ...
+```
+
+### 2.2 Create QA Plan
+```markdown
+## QA Plan
+
+Total Pages: {n}
+Estimated Time: {pages * 2min}
+
+### Session 1: Public Pages (no auth)
+- [ ] Home
+- [ ] Login
+- [ ] Register
+
+### Session 2: Dashboard
+- [ ] Login first
+- [ ] Dashboard home
+- [ ] Analytics
+...
+```
+
+Save to `.ctx/qa/QA_PLAN.md`
+
+## Step 3: Execute QA Per Page
+
+For each page in inventory:
+
+### 3.1 Navigate
+```javascript
+// Load credentials from .ctx/.env
+const APP_URL = process.env.APP_URL;
+
+mcp__playwright__browser_navigate({ url: `${APP_URL}${route}` });
+```
+
+### 3.2 Handle Authentication
+```javascript
+// If login required and not logged in
+if (requiresAuth && !isLoggedIn) {
+  // Navigate to login
+  mcp__playwright__browser_navigate({ url: `${APP_URL}/login` });
+
+  // Fill credentials from .ctx/.env
+  mcp__playwright__browser_type({
+    ref: 'email-input',
+    text: process.env.TEST_USER_EMAIL
+  });
+  mcp__playwright__browser_type({
+    ref: 'password-input',
+    text: process.env.TEST_USER_PASSWORD
+  });
+  mcp__playwright__browser_click({ ref: 'submit-button' });
+
+  // Return to target page
+  mcp__playwright__browser_navigate({ url: `${APP_URL}${route}` });
+}
+```
+
+### 3.3 Take Initial Snapshot
+```javascript
+mcp__playwright__browser_snapshot();
+mcp__playwright__browser_take_screenshot({
+  filename: `.ctx/qa/screenshots/${route.replace(/\//g, '-')}-initial.png`
+});
+```
+
+### 3.4 Check Console Errors
+```javascript
+const messages = mcp__playwright__browser_console_messages({ level: 'error' });
+if (messages.length > 0) {
+  issues.push({
+    type: 'console-error',
+    page: route,
+    errors: messages
+  });
+}
+```
+
+### 3.5 Discover Interactive Elements
+```javascript
+mcp__playwright__browser_evaluate({
+  function: `
+    const elements = [];
+
+    // Buttons
+    document.querySelectorAll('button').forEach((el, i) => {
+      elements.push({
+        type: 'button',
+        ref: el.getAttribute('data-ref') || 'button-' + i,
+        text: el.textContent.trim(),
+        disabled: el.disabled
+      });
+    });
+
+    // Links
+    document.querySelectorAll('a').forEach((el, i) => {
+      elements.push({
+        type: 'link',
+        ref: el.getAttribute('data-ref') || 'link-' + i,
+        text: el.textContent.trim(),
+        href: el.getAttribute('href')
+      });
+    });
+
+    // Forms
+    document.querySelectorAll('form').forEach((el, i) => {
+      elements.push({
+        type: 'form',
+        ref: el.getAttribute('data-ref') || 'form-' + i,
+        inputs: [...el.querySelectorAll('input, select, textarea')].map(input => ({
+          name: input.name,
+          type: input.type,
+          required: input.required
+        }))
+      });
+    });
+
+    // Inputs
+    document.querySelectorAll('input, select, textarea').forEach((el, i) => {
+      elements.push({
+        type: 'input',
+        ref: el.getAttribute('data-ref') || 'input-' + i,
+        name: el.name,
+        inputType: el.type
+      });
+    });
+
+    return elements;
+  `
+})
+```
+
+### 3.6 Click Every Button
+```javascript
+for (const button of buttons) {
+  if (button.disabled) continue;
+
+  try {
+    // Take before screenshot
+    mcp__playwright__browser_take_screenshot({
+      filename: `.ctx/qa/screenshots/${route}-btn-${button.ref}-before.png`
+    });
+
+    // Click
+    mcp__playwright__browser_click({
+      element: button.text,
+      ref: button.ref
+    });
+
+    // Wait for response
+    mcp__playwright__browser_wait_for({ time: 1 });
+
+    // Take after screenshot
+    mcp__playwright__browser_take_screenshot({
+      filename: `.ctx/qa/screenshots/${route}-btn-${button.ref}-after.png`
+    });
+
+    // Check for errors
+    const errors = mcp__playwright__browser_console_messages({ level: 'error' });
+    if (errors.length > 0) {
+      issues.push({
+        type: 'button-error',
+        page: route,
+        button: button.text,
+        errors: errors
+      });
+    }
+
+    // Navigate back if needed
+    mcp__playwright__browser_navigate_back();
+
+  } catch (e) {
+    issues.push({
+      type: 'button-crash',
+      page: route,
+      button: button.text,
+      error: e.message
+    });
+  }
+}
+```
+
+### 3.7 Click Every Link
+```javascript
+for (const link of links) {
+  // Skip external links
+  if (link.href.startsWith('http') && !link.href.includes(APP_URL)) continue;
+
+  try {
+    mcp__playwright__browser_click({ element: link.text, ref: link.ref });
+    mcp__playwright__browser_wait_for({ time: 1 });
+
+    // Check if navigation worked
+    const snapshot = mcp__playwright__browser_snapshot();
+    if (snapshot.includes('404') || snapshot.includes('not found')) {
+      issues.push({
+        type: 'broken-link',
+        page: route,
+        link: link.href,
+        text: link.text
+      });
+    }
+
+    // Go back
+    mcp__playwright__browser_navigate_back();
+
+  } catch (e) {
+    issues.push({
+      type: 'link-error',
+      page: route,
+      link: link.href,
+      error: e.message
+    });
+  }
+}
+```
+
+### 3.8 Test Every Form
+```javascript
+for (const form of forms) {
+  try {
+    // Fill with test data
+    for (const input of form.inputs) {
+      const testValue = getTestValue(input.type, input.name);
+      mcp__playwright__browser_type({
+        ref: input.ref,
+        text: testValue
+      });
+    }
+
+    // Submit
+    mcp__playwright__browser_click({ ref: form.submitButton });
+    mcp__playwright__browser_wait_for({ time: 2 });
+
+    // Check for validation errors or success
+    const snapshot = mcp__playwright__browser_snapshot();
+    const errors = mcp__playwright__browser_console_messages({ level: 'error' });
+
+    if (errors.length > 0) {
+      issues.push({
+        type: 'form-error',
+        page: route,
+        form: form.ref,
+        errors: errors
+      });
+    }
+
+  } catch (e) {
+    issues.push({
+      type: 'form-crash',
+      page: route,
+      form: form.ref,
+      error: e.message
+    });
+  }
+}
+```
+
+### 3.9 Visual Checks
+```javascript
+// Check for obvious visual issues
+mcp__playwright__browser_evaluate({
+  function: `
+    const issues = [];
+
+    // Overlapping elements
+    // Missing images
+    document.querySelectorAll('img').forEach(img => {
+      if (!img.complete || img.naturalWidth === 0) {
+        issues.push({ type: 'broken-image', src: img.src });
+      }
+    });
+
+    // Tiny touch targets (WCAG)
+    document.querySelectorAll('button, a, input').forEach(el => {
+      const rect = el.getBoundingClientRect();
+      if (rect.width < 24 || rect.height < 24) {
+        issues.push({
+          type: 'small-touch-target',
+          element: el.tagName,
+          size: rect.width + 'x' + rect.height
+        });
+      }
+    });
+
+    return issues;
+  `
+})
+```
+
+### 3.10 Save Page Results
+```markdown
+## Page: {route}
+
+### Summary
+- Elements found: {count}
+- Buttons clicked: {count}
+- Links tested: {count}
+- Forms submitted: {count}
+- Issues found: {count}
+
+### Issues
+| # | Type | Element | Description |
+|---|------|---------|-------------|
+| 1 | console-error | - | TypeError: undefined |
+| 2 | broken-link | /old-page | 404 Not Found |
+| 3 | button-crash | Delete | Unhandled promise |
+
+### Screenshots
+- initial.png
+- btn-submit-before.png
+- btn-submit-after.png
+```
+
+## Step 4: Generate QA Report
+
+After all pages tested:
+
+### 4.1 Aggregate Issues
+```markdown
+# QA Report - {project_name}
+
+**Date:** {ISO-8601}
+**Pages Tested:** {total}
+**Total Issues:** {count}
+
+## Summary by Severity
+
+| Severity | Count |
+|----------|-------|
+| Critical | {n} |
+| High | {n} |
+| Medium | {n} |
+| Low | {n} |
+
+## Summary by Type
+
+| Type | Count |
+|------|-------|
+| Console Errors | {n} |
+| Broken Links | {n} |
+| Button Crashes | {n} |
+| Form Errors | {n} |
+| Visual Issues | {n} |
+| A11y Issues | {n} |
+
+## Issues by Section
+
+### Section: Authentication
+| Page | Issue | Severity | Description |
+|------|-------|----------|-------------|
+| /login | console-error | High | TypeError at line 45 |
+
+### Section: Dashboard
+...
+
+## Critical Issues (Fix First)
+1. [CRITICAL] /checkout - Payment form crashes on submit
+2. [CRITICAL] /api/users - Returns 500 error
+
+## All Screenshots
+.ctx/qa/screenshots/
+```
+
+Save to `.ctx/qa/QA_REPORT.md`
+
+## Step 5: Create Fix Tasks
+
+### 5.1 Group Issues by Section
+```markdown
+## Fix Tasks by Section
+
+### Section: Authentication (3 issues)
+
+**Task A1: Fix login console errors**
+- Page: /login
+- Issues: 2 console errors
+- Priority: High
+- Files: src/auth/login.tsx
+
+**Task A2: Fix forgot-password form**
+- Page: /forgot-password
+- Issues: Form doesn't submit
+- Priority: High
+- Files: src/auth/forgot-password.tsx
+
+### Section: Dashboard (5 issues)
+...
+```
+
+### 5.2 Create PRD Stories (Optional)
+If `--create-stories` flag:
+```json
+{
+  "stories": [
+    {
+      "id": "QA001",
+      "title": "Fix authentication section issues",
+      "type": "bug",
+      "acceptanceCriteria": [
+        "Login page has no console errors",
+        "Forgot password form submits successfully"
+      ],
+      "passes": false
+    }
+  ]
+}
+```
+
+### 5.3 Update STATE.md
+```markdown
+## QA Results
+
+Last Run: {timestamp}
+Pages Tested: {n}
+Issues Found: {n}
+
+### Fix Tasks Created
+- [ ] QA001: Fix authentication issues (3 bugs)
+- [ ] QA002: Fix dashboard issues (5 bugs)
+- [ ] QA003: Fix checkout issues (2 bugs)
+
+Next: Run `/ctx` to start fixing
+```
+
+## Step 6: Persistent State (Resume Support)
+
+### Save Progress
+```json
+// .ctx/qa/SESSION.json
+{
+  "sessionId": "qa-20240120-143000",
+  "status": "in_progress",
+  "totalPages": 25,
+  "completedPages": 12,
+  "currentPage": "/dashboard/analytics",
+  "issuesFound": 15,
+  "startedAt": "2024-01-20T14:30:00Z",
+  "lastUpdate": "2024-01-20T15:00:00Z"
+}
+```
+
+### Resume
+```bash
+/ctx:qa --resume
+# Loads SESSION.json, continues from currentPage
+```
+
+</process>
+
+<test_data>
+
+## Smart Test Data Generation
+
+For form testing, generate appropriate test data:
+
+| Field Type | Test Value |
+|------------|------------|
+| email | `test-{uuid}@example.com` |
+| password | `TestPass123!` |
+| name | `Test User` |
+| phone | `+1234567890` |
+| address | `123 Test Street` |
+| date | Today's date |
+| number | `42` |
+| url | `https://example.com` |
+| textarea | `Lorem ipsum test content` |
+
+For select/dropdown:
+- Select first non-placeholder option
+
+For checkbox/radio:
+- Toggle to opposite state
+
+</test_data>
+
+<output>
+```
+[CTX QA] Full System Quality Assurance
+
+Discovering pages...
+  Found: 25 pages in 5 sections
+
+Testing Section 1/5: Authentication
+  [✓] /login - 0 issues
+  [✓] /register - 1 issue (console warning)
+  [✗] /forgot-password - 2 issues (a11y: missing label)
+
+Testing Section 2/5: Dashboard
+  [✓] /dashboard - 0 issues
+  [✗] /dashboard/analytics - 3 issues (touch target, contrast)
+  ...
+
+Responsive Testing...
+  Mobile (375px): 25 pages tested
+  Tablet (768px): 25 pages tested
+  Desktop (1280px): 25 pages tested
+
+Accessibility Audit (WCAG 2.1 AA)...
+  Perceivable: 45/49 pass
+  Operable: 38/39 pass
+  Understandable: 22/22 pass
+  Robust: 15/15 pass
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+QA COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Pages Tested: 25 (75 viewport tests)
+Duration: 1h 23m
+
+Issues Found: 18
+├── Functional:     8 (2 critical, 4 high)
+├── Accessibility:  6 (1 critical, 3 high)
+├── Visual:         3 (1 high, 2 medium)
+└── Performance:    1 (1 high)
+
+WCAG 2.1 AA Score: 96%
+
+Fix Tasks Created: 6
+
+Report: .ctx/qa/QA_REPORT.md
+Screenshots: .ctx/qa/screenshots/ (75 files)
+Traces: .ctx/qa/traces/ (18 files)
+
+Next: Run /ctx to start fixing critical issues
+```
+</output>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx-cc",
-  "version": "3.3.3",
+  "version": "3.3.5",
   "description": "CTX 3.3 (Continuous Task eXecution) - AI that learns your preferences. Learning system, predictive planning, self-healing deployments (Sentry/LogRocket), voice control for hands-free development.",
   "keywords": [
     "claude",