e2e-ai 1.3.0 → 1.4.2

package/README.md

@@ -10,9 +10,12 @@ Includes a **codebase scanner** that builds a QA map of your application's featu
 # 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
 
@@ -57,7 +60,7 @@ Scans your codebase structure (routes, components, hooks), uses AI to identify f
 
 ### `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
@@ -66,6 +69,8 @@ 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
@@ -409,7 +414,7 @@ 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';
@@ -463,12 +468,10 @@ export default defineConfig({
     retries: 0,
     traceMode: 'on',
   },
-
-  contextFile: '.e2e-ai/context.md',
 });
 ```
 
-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
 
@@ -524,7 +527,7 @@ You can customize agent behavior by editing the `.md` files directly. The frontm
 
 ## Output Directory Structure
 
-Default paths (configurable via `e2e-ai.config.ts`):
+Default paths (configurable via `.e2e-ai/config.ts`):
 
 ```
 e2e/
@@ -534,12 +537,85 @@ e2e/
 qa/                    # QA documentation .md 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:

package/agents/feature-analyzer-agent.md

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

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

package/agents/scenario-planner-agent.md

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

package/agents/self-healing-agent.md

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

package/agents/transcript-agent.md

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

package/dist/cli-98db6h2q.js

@@ -0,0 +1,101 @@
+import {
+  getPackageRoot,
+  getProjectRoot
+} from "./cli-kx32qnf3.js";
+
+// src/agents/loadAgent.ts
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+function loadAgent(agentName, config) {
+  const localPath = join(getProjectRoot(), ".e2e-ai", "agents", `${agentName}.md`);
+  const packagePath = join(getPackageRoot(), "agents", `${agentName}.md`);
+  const filePath = existsSync(localPath) ? localPath : packagePath;
+  let content;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch {
+    throw new Error(`Agent file not found: ${filePath}`);
+  }
+  const { frontmatter, body } = parseFrontmatter(content);
+  const agentConfig = extractConfig(frontmatter);
+  let systemPrompt = body;
+  if (config) {
+    const contextPath = join(getProjectRoot(), ".e2e-ai", "context.md");
+    if (existsSync(contextPath)) {
+      const projectContext = readFileSync(contextPath, "utf-8").trim();
+      if (projectContext) {
+        systemPrompt = `${body}
+
+## Project Context
+
+${projectContext}`;
+      }
+    }
+    if (config.llm.agentModels[agentName]) {
+      agentConfig.model = config.llm.agentModels[agentName];
+    }
+  }
+  const sections = parseSections(body);
+  return {
+    name: frontmatter.agent ?? agentName,
+    systemPrompt,
+    inputSchema: sections["Input Schema"],
+    outputSchema: sections["Output Schema"],
+    rules: sections["Rules"],
+    example: sections["Example"],
+    config: agentConfig
+  };
+}
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match)
+    return { frontmatter: {}, body: content };
+  const frontmatter = {};
+  for (const line of match[1].split(`
+`)) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1)
+      continue;
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"'))
+      value = value.slice(1, -1);
+    if (value === "true")
+      value = true;
+    if (value === "false")
+      value = false;
+    if (!isNaN(Number(value)) && value !== "")
+      value = Number(value);
+    frontmatter[key] = value;
+  }
+  return { frontmatter, body: match[2] };
+}
+function extractConfig(frontmatter) {
+  return {
+    model: frontmatter.model,
+    maxTokens: frontmatter.max_tokens ?? 4096,
+    temperature: frontmatter.temperature ?? 0.2
+  };
+}
+function parseSections(body) {
+  const sections = {};
+  const headingRegex = /^##\s+(.+)$/gm;
+  const headings = [];
+  let match;
+  while ((match = headingRegex.exec(body)) !== null) {
+    headings.push({ title: match[1].trim(), index: match.index });
+  }
+  const systemMatch = body.match(/^#\s+System Prompt\n([\s\S]*?)(?=\n##\s|$)/m);
+  if (systemMatch) {
+    sections["System Prompt"] = systemMatch[1].trim();
+  }
+  for (let i = 0;i < headings.length; i++) {
+    const start = headings[i].index + body.slice(headings[i].index).indexOf(`
+`) + 1;
+    const end = i + 1 < headings.length ? headings[i + 1].index : body.length;
+    sections[headings[i].title] = body.slice(start, end).trim();
+  }
+  return sections;
+}
+
+export { loadAgent };

package/dist/cli-kx32qnf3.js

@@ -0,0 +1,67 @@
+import {
+  E2eAiConfigSchema
+} from "./cli-fgp618yt.js";
+
+// src/config/loader.ts
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+var CONFIG_DIR = ".e2e-ai";
+var CONFIG_FILENAMES = ["config.ts", "config.js", "config.mjs"];
+var cachedConfig = null;
+var cachedProjectRoot = null;
+function findConfigDir(startDir) {
+  let dir = resolve(startDir);
+  const root = dirname(dir) === dir ? dir : undefined;
+  while (true) {
+    const e2eDir = join(dir, CONFIG_DIR);
+    for (const name of CONFIG_FILENAMES) {
+      if (existsSync(join(e2eDir, name))) {
+        return dir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir || dir === root)
+      return null;
+    dir = parent;
+  }
+}
+function getProjectRoot() {
+  if (cachedProjectRoot)
+    return cachedProjectRoot;
+  const found = findConfigDir(process.cwd());
+  cachedProjectRoot = found ?? process.cwd();
+  return cachedProjectRoot;
+}
+function getPackageRoot() {
+  let dir = import.meta.dirname;
+  while (!existsSync(join(dir, "package.json"))) {
+    const parent = dirname(dir);
+    if (parent === dir)
+      return dir;
+    dir = parent;
+  }
+  return dir;
+}
+async function loadConfig() {
+  if (cachedConfig)
+    return cachedConfig;
+  const projectRoot = getProjectRoot();
+  const e2eDir = join(projectRoot, CONFIG_DIR);
+  let userConfig = {};
+  for (const name of CONFIG_FILENAMES) {
+    const configPath = join(e2eDir, name);
+    if (existsSync(configPath)) {
+      try {
+        const fileUrl = pathToFileURL(configPath).href;
+        const mod = await import(fileUrl);
+        userConfig = mod.default ?? mod;
+        break;
+      } catch {}
+    }
+  }
+  cachedConfig = E2eAiConfigSchema.parse(userConfig);
+  return cachedConfig;
+}
+
+export { getProjectRoot, getPackageRoot, loadConfig };