e2e-ai 1.2.0 → 1.4.0

package/README.md

@@ -2,46 +2,65 @@
 
 AI-powered E2E test automation pipeline. Takes you from a manual browser recording all the way to a stable, documented Playwright test — with optional Zephyr integration.
 
+Includes a **codebase scanner** that builds a QA map of your application's features, workflows, and test scenarios using AI analysis.
+
 ## Quick Start
 
 ```bash
 # Install
 npm install e2e-ai
 
-# Initialize config + project context
+# Initialize config + copy agents
 npx e2e-ai init
 
+# Generate project context (use init-agent in your AI tool)
+# → produces .e2e-ai/context.md
+
 # Show all commands
 npx e2e-ai --help
 
 # Full pipeline for an issue
 npx e2e-ai run --key PROJ-101
 
-# Individual commands
-npx e2e-ai scenario --key PROJ-101
-npx e2e-ai generate --key PROJ-101
-npx e2e-ai qa --key PROJ-101
+# Scan your codebase and generate a QA map
+npx e2e-ai scan
+npx e2e-ai analyze
 ```
 
 ## Architecture
 
+e2e-ai has two main workflows:
+
+### Test Pipeline
+
 ```
-                                    AI Agents (LLM)
-                                         |
-  record -> transcribe -> scenario -> generate -> refine -> test -> heal -> qa
-    |            |            |           |          |         |       |      |
-  codegen     whisper    transcript   scenario    refactor  playwright self-  QA doc
-  + audio     + merge    + scenario     agent      agent    runner   healing  + export
-                agent      agent                                     agent   agent
+record -> transcribe -> scenario -> generate -> refine -> test -> heal -> qa
+  |            |            |           |          |         |       |      |
+codegen     whisper    transcript   scenario    refactor  playwright self-  QA doc
++ audio     + merge    + scenario     agent      agent    runner   healing  + export
+              agent      agent                                     agent   agent
 ```
 
 Each step produces an artifact that feeds the next. You can run the full pipeline or any step individually.
 
+### Scanner Pipeline
+
+```
+scan -> analyze -> push
+  |        |         |
+ AST    feature    remote
+ scan   analyzer   API
+        + scenario  upload
+        planner
+```
+
+Scans your codebase structure (routes, components, hooks), uses AI to identify features and workflows, generates test scenarios, and optionally pushes the QA map to a remote API.
+
 ## Commands
 
 ### `init` - Project Setup
 
-Interactive wizard that scans your codebase and generates configuration + project context.
+Interactive wizard that creates `.e2e-ai/config.ts` and copies agent prompts to `.e2e-ai/agents/`.
 
 ```bash
 npx e2e-ai init
@@ -50,6 +69,10 @@ npx e2e-ai init
 npx e2e-ai init --non-interactive
 ```
 
+After init, use the **init-agent** in your AI tool (Claude Code, Cursor, etc.) to generate `.e2e-ai/context.md`. This context file teaches all downstream agents about your project's test conventions. If you have the MCP server configured, the AI tool can call `e2e_ai_scan_codebase` to analyze your project automatically.
+
+---
+
 ### `record` - Browser Recording
 
 Launches Playwright codegen with optional voice recording and trace capture.
@@ -198,6 +221,115 @@ npx e2e-ai run --key PROJ-101 --from scenario --skip test,heal
 
 Each step's output feeds the next via `PipelineContext`. If a step fails, the pipeline stops (unless the step is marked `nonBlocking`).
 
+---
+
+### `scan` - Codebase AST Scanner
+
+Scans your codebase and extracts structural information: routes, components, hooks, imports, and dependencies.
+
+```bash
+# Scan using config defaults (scans src/)
+npx e2e-ai scan
+
+# Scan a specific directory
+npx e2e-ai scan --scan-dir app
+
+# Write output to a custom path
+npx e2e-ai scan --output my-scan.json
+
+# Disable file-level caching
+npx e2e-ai scan --no-cache
+```
+
+**What it does**:
+1. Collects all `.ts`, `.tsx`, `.js`, `.jsx` files matching configured include/exclude patterns
+2. Parses each file with a regex-based TypeScript parser to extract imports, exports, components, and hooks
+3. Extracts routes from Next.js App Router (`app/`) and Pages Router (`pages/`) conventions
+4. Caches results per-file (by content hash) for fast incremental re-scans
+
+**Output**: `ASTScanResult` JSON containing:
+- `files` — all scanned files with imports, exports, line counts
+- `routes` — extracted routes with paths, methods, dynamic segments, layout files
+- `components` — React components with props, hook calls, export status
+- `hooks` — custom hook definitions with dependencies
+- `dependencies` — import graph edges between files
+
+Default output location: `.e2e-ai/ast-scan.json`
+
+**Options**:
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--output <file>` | Write output to specific file | `.e2e-ai/ast-scan.json` |
+| `--scan-dir <dir>` | Directory to scan | from config (`src`) |
+| `--no-cache` | Disable file-level caching | cache enabled |
+
+### `analyze` - AI QA Map Generation
+
+Analyzes an AST scan result using AI to identify features, workflows, components, and test scenarios.
+
+```bash
+# Analyze the default scan output
+npx e2e-ai analyze
+
+# Analyze a specific scan file
+npx e2e-ai analyze path/to/ast-scan.json
+
+# Only extract features (skip scenario generation)
+npx e2e-ai analyze --skip-scenarios
+
+# Write output to a custom path
+npx e2e-ai analyze --output my-qa-map.json
+```
+
+**What it does** — two-stage AI pipeline:
+
+1. **Stage 2 — Feature Analysis** (`feature-analyzer-agent`): Receives the AST scan and groups routes, components, and hooks into logical features and user-facing workflows. Identifies component roles (form, display, navigation, modal, layout, feedback) and maps API routes to workflow steps.
+
+2. **Stage 3 — Scenario Planning** (`scenario-planner-agent`): Receives the feature map and generates test scenarios for each workflow. Covers happy paths, validation, error handling, edge cases, and permission checks. Assigns priorities (critical/high/medium/low) and links scenarios to specific workflow steps.
+
+**Output**: `QAMapV2Payload` JSON containing:
+- `features` — logical application features with routes and source files
+- `workflows` — user journeys with ordered steps, API calls, conditional branches
+- `components` — UI components with types, props, workflow references
+- `scenarios` — test scenarios with steps, preconditions, expected outcomes, priorities
+
+Default output location: `.e2e-ai/qa-map.json`
+
+**Options**:
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--output <file>` | Write QA map to specific file | `.e2e-ai/qa-map.json` |
+| `--skip-scenarios` | Only run feature analysis | both stages |
+
+### `push` - Push QA Map to API
+
+Pushes a generated QA map to a remote API endpoint.
+
+```bash
+# Push the default QA map
+npx e2e-ai push
+
+# Push a specific file
+npx e2e-ai push path/to/qa-map.json
+
+# Associate with a git commit
+npx e2e-ai push --commit-sha abc123
+```
+
+**What it does**: Sends the `QAMapV2Payload` JSON as a POST request to the configured API endpoint with Bearer token authentication. The API responds with version info and auto-linking statistics.
+
+**Requires** `push.apiUrl` and `push.apiKey` in config (or `E2E_AI_API_URL` / `E2E_AI_API_KEY` env vars).
+
+**Options**:
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--commit-sha <sha>` | Git commit SHA to associate | - |
+
+---
+
 ## Typical Workflows
 
 ### Workflow 1: Full Recording Pipeline
@@ -254,23 +386,92 @@ npx e2e-ai scenario --key PROJ-101
 npx e2e-ai run --key PROJ-101 --from generate
 ```
 
+### Workflow 5: Codebase Scanner Pipeline
+
+Generate a full QA map from your codebase structure:
+
+```bash
+# Step 1: Scan the codebase AST
+npx e2e-ai scan
+
+# Step 2: AI analysis → features, workflows, scenarios
+npx e2e-ai analyze
+
+# Step 3: Push to remote API (optional)
+npx e2e-ai push
+```
+
+Or run stages selectively:
+
+```bash
+# Just extract features (no scenarios)
+npx e2e-ai analyze --skip-scenarios
+
+# Re-scan after code changes (cached, fast)
+npx e2e-ai scan
+npx e2e-ai analyze
+```
+
 ## Configuration
 
-Run `npx e2e-ai init` to generate `e2e-ai.config.ts`:
+Run `npx e2e-ai init` to generate `.e2e-ai/config.ts`:
 
 ```typescript
 import { defineConfig } from 'e2e-ai/config';
 
 export default defineConfig({
+  // --- General ---
   inputSource: 'none',       // 'jira' | 'linear' | 'none'
   outputTarget: 'markdown',  // 'zephyr' | 'markdown' | 'both'
+
+  // --- LLM ---
+  llm: {
+    provider: 'openai',      // 'openai' | 'anthropic'
+    model: null,              // null = use agent defaults (gpt-4o)
+    agentModels: {},          // per-agent overrides: { 'scenario-agent': 'gpt-4o-mini' }
+  },
+
+  // --- Paths ---
+  paths: {
+    tests: 'e2e/tests',
+    scenarios: 'e2e/scenarios',
+    recordings: 'e2e/recordings',
+    transcripts: 'e2e/transcripts',
+    traces: 'e2e/traces',
+    workingDir: '.e2e-ai',
+    qaOutput: 'qa',
+  },
+
+  // --- Scanner ---
+  scanner: {
+    scanDir: 'src',                         // root directory to scan
+    include: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
+    exclude: [
+      '**/node_modules/**', '**/dist/**', '**/build/**',
+      '**/.next/**', '**/*.test.*', '**/*.spec.*',
+      '**/__tests__/**', '**/*.d.ts',
+    ],
+    cacheDir: '.e2e-ai/scan-cache',         // file-level parse cache
+  },
+
+  // --- Push (remote QA map API) ---
+  push: {
+    apiUrl: null,   // or set E2E_AI_API_URL env var
+    apiKey: null,   // or set E2E_AI_API_KEY env var
+  },
+
+  // --- Recording ---
   voice: { enabled: true },
-  llm: { provider: 'openai' },
-  contextFile: 'e2e-ai.context.md',
+  playwright: {
+    browser: 'chromium',
+    timeout: 120_000,
+    retries: 0,
+    traceMode: 'on',
+  },
 });
 ```
 
-See `templates/e2e-ai.context.example.md` for the project context file format.
+All configuration lives inside the `.e2e-ai/` directory — no files at project root.
 
 ## Global Options
 
@@ -298,11 +499,13 @@ AI_PROVIDER=openai              # openai | anthropic
 AI_MODEL=gpt-4o                 # Model override
 ANTHROPIC_API_KEY=sk-ant-...    # Required if AI_PROVIDER=anthropic
 BASE_URL=https://...            # Your application URL
+E2E_AI_API_URL=https://...      # Remote API for push command
+E2E_AI_API_KEY=key-...          # API key for push command
 ```
 
 ## AI Agents
 
-Six specialized agents live in `agents/*.md`. Each has:
+Eight specialized agents live in `agents/*.md`. Each has:
 - **YAML frontmatter**: model, max_tokens, temperature
 - **System prompt**: role + context
 - **Input/Output schemas**: what the agent receives and must produce
@@ -317,12 +520,14 @@ Six specialized agents live in `agents/*.md`. Each has:
 | `refactor-agent` | test + project context | Improved test file | `refine` |
 | `self-healing-agent` | failing test + error output | Diagnosis + patched test | `heal` |
 | `qa-testcase-agent` | test + scenario + issue data | QA markdown + test case JSON | `qa` |
+| `feature-analyzer-agent` | AST scan result | Features, workflows, components JSON | `analyze` |
+| `scenario-planner-agent` | Features + workflows | Complete QA map with scenarios JSON | `analyze` |
 
-You can customize agent behavior by editing the `.md` files directly. The frontmatter `model` field is the default model for that agent (overridable via `--model`).
+You can customize agent behavior by editing the `.md` files directly. The frontmatter `model` field is the default model for that agent (overridable via `--model` or `config.llm.agentModels`).
 
 ## Output Directory Structure
 
-Default paths (configurable via `e2e-ai.config.ts`):
+Default paths (configurable via `.e2e-ai/config.ts`):
 
 ```
 e2e/
@@ -331,7 +536,103 @@ e2e/
 
 qa/                    # QA documentation .md files
 
-.e2e-ai/<KEY>/         # per-issue working dir: codegen, recordings/, intermediate files
+.e2e-ai/
+  config.ts            # project configuration
+  context.md           # project context (generated by init-agent)
+  agents/              # agent prompt definitions (.md files)
+  <KEY>/               # per-issue working dir: codegen, recordings/, intermediate files
+  ast-scan.json        # scan command output
+  qa-map.json          # analyze command output
+  scan-cache/          # file-level parse cache (gitignored)
+```
+
+## MCP Server
+
+e2e-ai ships an MCP (Model Context Protocol) server that lets AI assistants interact with your project's test infrastructure directly. The server binary is `e2e-ai-mcp`.
+
+### Setup
+
+Add to your MCP client configuration:
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "e2e-ai": {
+      "command": "npx",
+      "args": ["e2e-ai-mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add e2e-ai -- npx e2e-ai-mcp
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "e2e-ai": {
+      "command": "npx",
+      "args": ["e2e-ai-mcp"]
+    }
+  }
+}
+```
+
+If e2e-ai is installed globally or as a project dependency, you can use the binary path directly instead of `npx`:
+
+```json
+{
+  "command": "node",
+  "args": ["node_modules/.bin/e2e-ai-mcp"]
+}
+```
+
+### Available Tools
+
+| Tool | Description | Input |
+|------|-------------|-------|
+| `e2e_ai_scan_codebase` | Scan project for test files, configs, fixtures, path aliases, and sample test content | `projectRoot?` (defaults to cwd) |
+| `e2e_ai_validate_context` | Validate that a context markdown file has all required sections | `content` (markdown string) |
+| `e2e_ai_read_agent` | Load an agent prompt by name — returns system prompt + config | `agentName` (e.g. `scenario-agent`) |
+| `e2e_ai_get_example` | Get the example context markdown template | (none) |
+
+### Usage with AI Assistants
+
+Once configured, an AI assistant can:
+
+1. **Scan your project** to understand its test structure, fixtures, and conventions
+2. **Read agent prompts** to understand how each pipeline step works
+3. **Validate context files** to ensure they have the right format before running commands
+4. **Get the example template** as a starting point for writing `e2e-ai.context.md`
+
+This enables AI assistants to help you set up e2e-ai, debug pipeline issues, and generate better project context files.
+
+## Library API
+
+e2e-ai also exports types and config helpers for programmatic use:
+
+```typescript
+import { defineConfig, loadConfig, getProjectRoot } from 'e2e-ai';
+import type {
+  E2eAiConfig,
+  ResolvedConfig,
+  ASTScanResult,
+  QAMapV2Payload,
+  FeatureV2,
+  WorkflowV2,
+  ScenarioV2,
+  ComponentV2,
+  PushResult,
+} from 'e2e-ai';
 ```
 
 ## License

package/agents/feature-analyzer-agent.md

@@ -0,0 +1,77 @@
+---
+agent: feature-analyzer-agent
+---
+
+# System Prompt
+
+You are a QA feature analyst. You receive an AST scan result (routes, components, hooks, dependencies) of a web application and identify the logical features, user-facing workflows, and reusable components.
+
+Your job is to transform raw structural data into a high-level QA map that captures what the application does from a user's perspective.
+
+## Input Schema
+
+You receive a JSON object with:
+- `ast`: object - The ASTScanResult from a codebase scan (files, routes, components, hooks, dependencies)
+- `existingMap`: object (optional) - A previous QAMapV2 to update incrementally
+
+## Output Schema
+
+Respond with JSON only (no markdown fences, no extra text):
+
+```json
+{
+  "features": [
+    {
+      "id": "feat:<kebab-case>",
+      "name": "Human-readable feature name",
+      "description": "What this feature does from user perspective",
+      "routes": ["/path1", "/path2"],
+      "workflowIds": ["wf:<kebab>"],
+      "sourceFiles": ["src/path/file.ts"]
+    }
+  ],
+  "workflows": [
+    {
+      "id": "wf:<kebab-case>",
+      "name": "Human-readable workflow name",
+      "featureId": "feat:<parent>",
+      "type": "navigation|crud|multi-step|configuration|search-filter",
+      "preconditions": ["User is authenticated"],
+      "steps": [
+        {
+          "id": "step:<workflow>:<index>",
+          "order": 1,
+          "description": "What the user does",
+          "componentIds": ["comp:<kebab>"],
+          "apiCalls": ["POST /api/endpoint"],
+          "conditionalBranches": []
+        }
+      ],
+      "componentIds": ["comp:<kebab>"]
+    }
+  ],
+  "components": [
+    {
+      "id": "comp:<kebab-case>",
+      "name": "ComponentName",
+      "type": "form|display|navigation|modal|layout|feedback",
+      "sourceFiles": ["src/path/Component.tsx"],
+      "props": ["prop1", "prop2"],
+      "referencedByWorkflows": ["wf:<kebab>"]
+    }
+  ]
+}
+```
+
+## Rules
+
+1. Group routes and components into logical features based on shared URL paths, layouts, and data dependencies
+2. A feature represents a user-facing capability (e.g., "User Management", "Dashboard", "Settings")
+3. A workflow represents a specific user journey within a feature (e.g., "Create new user", "Filter dashboard by date")
+4. Workflow type must be one of: navigation, crud, multi-step, configuration, search-filter
+5. Identify components by their role: form (inputs), display (data rendering), navigation, modal, layout, feedback (toasts/alerts)
+6. Link components to workflows based on which route/page uses them (infer from imports and hook usage)
+7. API routes should be mapped as apiCalls within workflow steps
+8. Dynamic routes (containing `[param]`) indicate CRUD or detail-view workflows
+9. Prefer fewer, well-defined features over many granular ones. Aim for 3-15 features per app.
+10. Output valid JSON only, no markdown code fences or surrounding text

package/agents/init-agent.md

@@ -1,20 +1,24 @@
 ---
 agent: init-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.3
 ---
 
 # System Prompt
 
-You are a codebase analysis assistant for the e2e-ai test automation tool. Your job is to analyze a project's test infrastructure and produce a well-structured context document (`e2e-ai.context.md`) that will guide AI agents when generating, refining, and healing Playwright tests for this specific project.
+You are a codebase analysis assistant for the e2e-ai test automation tool. Your job is to analyze a project's test infrastructure and produce a well-structured context document (`.e2e-ai/context.md`) that will guide AI agents when generating, refining, and healing Playwright tests for this specific project.
 
-You will receive scan results from the target codebase and engage in a conversation to clarify patterns you're uncertain about.
+## How to Use This Agent
+
+This agent is designed to be used directly in your AI tool (Claude Code, Cursor, Gemini CLI, etc.). Start a conversation and ask it to generate your project context.
+
+**If the e2e-ai MCP server is configured**, call `e2e_ai_scan_codebase` to get scan results, then follow this agent's instructions to produce the context file.
+
+**If no MCP server**, manually explore the codebase: look at test files, fixtures, playwright config, tsconfig paths, and helper modules.
 
 ## Your Task
 
-Analyze the provided codebase scan and produce a context document covering:
+Analyze the project codebase and produce a file at `.e2e-ai/context.md` that documents the project's test infrastructure, conventions, and patterns. This context file is consumed by downstream AI agents (scenario, generator, refiner, healer, QA) to produce Playwright tests that match the project's existing style.
+
+Cover these areas:
 
 1. **Application Overview**: What the app does, tech stack, key pages/routes
 2. **Test Infrastructure**: Fixtures, custom test helpers, step counters, auth patterns
@@ -26,13 +30,13 @@ Analyze the provided codebase scan and produce a context document covering:
 
 ## Output Format
 
-When you have enough information, produce the final context as a markdown document with these sections:
+Produce the context document with these sections and save it to `.e2e-ai/context.md`:
 
 ```markdown
 # Project Context for e2e-ai
 
 ## Application
-<name, description, tech stack>
+<name, description, tech stack, base URL>
 
 ## Test Infrastructure
 <fixtures, helpers, auth pattern>
@@ -53,6 +57,22 @@ When you have enough information, produce the final context as a markdown docume
 <timeouts, waits, assertion patterns>
 ```
 
+All sections are required. The file should be 100-300 lines, self-contained, and use actual code from the project (not generic Playwright examples).
+
+## How Context is Used
+
+Each pipeline agent reads `.e2e-ai/context.md` to understand project conventions:
+
+| Agent | Uses context for |
+|-------|-----------------|
+| **scenario-agent** | Structuring test steps to match project patterns |
+| **playwright-generator-agent** | Generating code with correct imports, fixtures, selectors |
+| **refactor-agent** | Applying project-specific refactoring patterns |
+| **self-healing-agent** | Understanding expected test structure when fixing failures |
+| **qa-testcase-agent** | Formatting QA documentation to match conventions |
+| **feature-analyzer-agent** | Understanding app structure for QA map generation |
+| **scenario-planner-agent** | Generating realistic test scenarios from codebase analysis |
+
 ## Rules
 
 1. Ask clarifying questions if the scan data is ambiguous — do NOT guess
@@ -61,15 +81,3 @@ When you have enough information, produce the final context as a markdown docume
 4. The context file should be self-contained — an AI agent reading only this file should understand all project conventions
 5. Keep the document concise but complete — aim for 100-300 lines
 6. If you need to see specific files to complete the analysis, list them explicitly
-
-## Conversation Flow
-
-1. **First turn**: Receive scan results, analyze them, ask clarifying questions if needed
-2. **Middle turns**: Receive answers, refine understanding
-3. **Final turn**: When you have enough info, produce the complete context document wrapped in a `<context>` tag:
-   ```
-   <context>
-   # Project Context for e2e-ai
-   ...
-   </context>
-   ```

package/agents/playwright-generator-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: playwright-generator-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.2
 ---
 
 # System Prompt

package/agents/qa-testcase-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: qa-testcase-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.2
 ---
 
 # System Prompt

package/agents/refactor-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: refactor-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.2
 ---
 
 # System Prompt

package/agents/scenario-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: scenario-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 4096
-temperature: 0.2
 ---
 
 # System Prompt