e2e-ai 1.4.3 → 1.5.1

package/dist/mcp.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
-  loadAgent
-} from "./cli-98db6h2q.js";
+  loadAgent,
+  runStage1
+} from "./cli-h86f3dv5.js";
 import {
   getPackageRoot
 } from "./cli-kx32qnf3.js";
@@ -40,6 +41,7 @@ import {
 } from "./cli-fgp618yt.js";
 import {
   __commonJS,
+  __require,
   __toESM
 } from "./cli-wckvcay0.js";
 
@@ -14856,9 +14858,282 @@ class StdioServerTransport {
 }
 
 // src/mcp.ts
-import { readFileSync as readFileSync2, existsSync as existsSync2 } from "node:fs";
-import { join as join2 } from "node:path";
 import { execSync } from "node:child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/scanner/summarize.ts
+import { dirname } from "node:path";
+function summarizeAST(ast, savedPath) {
+  const dirGroups = {};
+  for (const f of ast.files) {
+    const dir = dirname(f.path).split("/")[0] || ".";
+    dirGroups[dir] = (dirGroups[dir] ?? 0) + 1;
+  }
+  return {
+    stats: ast.stats,
+    routes: ast.routes.map((r) => ({
+      path: r.path,
+      filePath: r.filePath,
+      isDynamic: r.isDynamic
+    })),
+    fileTree: ast.files.map((f) => f.path),
+    componentNames: ast.components.map((c) => c.name),
+    hookNames: ast.hooks.filter((h) => h.isCustom).map((h) => h.name),
+    directoryGroups: dirGroups,
+    astScanPath: savedPath
+  };
+}
+function filterASTByCategory(ast, category, filter, limit) {
+  const matchesFilter = (path) => {
+    if (!filter)
+      return true;
+    const regex = new RegExp("^" + filter.replace(/\*\*/g, "__.DOUBLE__").replace(/\*/g, "[^/]*").replace(/__.DOUBLE__/g, ".*") + "$");
+    return regex.test(path);
+  };
+  let items;
+  switch (category) {
+    case "routes":
+      items = filter ? ast.routes.filter((r) => matchesFilter(r.path) || matchesFilter(r.filePath)) : ast.routes;
+      break;
+    case "components":
+      items = filter ? ast.components.filter((c) => matchesFilter(c.filePath) || matchesFilter(c.name)) : ast.components;
+      break;
+    case "hooks":
+      items = filter ? ast.hooks.filter((h) => matchesFilter(h.filePath) || matchesFilter(h.name)) : ast.hooks;
+      break;
+    case "dependencies":
+      items = filter ? ast.dependencies.filter((d) => matchesFilter(d.from) || matchesFilter(d.to)) : ast.dependencies;
+      break;
+    case "files":
+      items = filter ? ast.files.filter((f) => matchesFilter(f.path)) : ast.files;
+      break;
+  }
+  if (limit && limit > 0) {
+    items = items.slice(0, limit);
+  }
+  return {
+    category,
+    filter: filter ?? null,
+    total: items.length,
+    items
+  };
+}
+
+// src/scanner/validate.ts
+var WORKFLOW_TYPES = ["navigation", "crud", "multi-step", "configuration", "search-filter"];
+var COMPONENT_TYPES = ["form", "display", "navigation", "modal", "layout", "feedback"];
+var SCENARIO_CATEGORIES = ["happy-path", "permission", "validation", "error", "edge-case", "precondition"];
+var SCENARIO_PRIORITIES = ["critical", "high", "medium", "low"];
+var BRANCH_TYPES = ["validation", "permission", "error", "business-logic"];
+function validateQAMap(payload) {
+  const errors = [];
+  const warnings = [];
+  if (!payload || typeof payload !== "object") {
+    return { valid: false, errors: ["Payload must be a non-null object"], warnings };
+  }
+  const p = payload;
+  const features = assertArray(p, "features", errors);
+  const workflows = assertArray(p, "workflows", errors);
+  const components = assertArray(p, "components", errors);
+  const scenarios = assertArray(p, "scenarios", errors);
+  if (errors.length > 0) {
+    return { valid: false, errors, warnings };
+  }
+  const featureIds = new Set;
+  const workflowIds = new Set;
+  const componentIds = new Set;
+  const scenarioIds = new Set;
+  const workflowStepIds = new Set;
+  for (const f of features) {
+    requireString(f, "id", "feature", errors);
+    requireString(f, "name", "feature", errors);
+    requireString(f, "description", "feature", errors);
+    requireArray(f, "routes", "feature", errors);
+    requireArray(f, "workflowIds", "feature", errors);
+    requireArray(f, "sourceFiles", "feature", errors);
+    if (f.id) {
+      if (featureIds.has(f.id))
+        errors.push(`Duplicate feature id: ${f.id}`);
+      featureIds.add(f.id);
+    }
+  }
+  for (const w of workflows) {
+    requireString(w, "id", "workflow", errors);
+    requireString(w, "name", "workflow", errors);
+    requireString(w, "featureId", "workflow", errors);
+    requireEnum(w, "type", WORKFLOW_TYPES, "workflow", errors);
+    requireArray(w, "preconditions", "workflow", errors);
+    requireArray(w, "steps", "workflow", errors);
+    requireArray(w, "componentIds", "workflow", errors);
+    if (w.id) {
+      if (workflowIds.has(w.id))
+        errors.push(`Duplicate workflow id: ${w.id}`);
+      workflowIds.add(w.id);
+    }
+    if (Array.isArray(w.steps)) {
+      for (const s of w.steps) {
+        requireString(s, "id", "workflowStep", errors);
+        requireNumber(s, "order", "workflowStep", errors);
+        requireString(s, "description", "workflowStep", errors);
+        requireArray(s, "componentIds", "workflowStep", errors);
+        requireArray(s, "apiCalls", "workflowStep", errors);
+        requireArray(s, "conditionalBranches", "workflowStep", errors);
+        if (s.id)
+          workflowStepIds.add(s.id);
+        if (Array.isArray(s.conditionalBranches)) {
+          for (const b of s.conditionalBranches) {
+            requireString(b, "condition", "conditionalBranch", errors);
+            requireString(b, "outcome", "conditionalBranch", errors);
+            requireEnum(b, "type", BRANCH_TYPES, "conditionalBranch", errors);
+          }
+        }
+      }
+    }
+  }
+  for (const c of components) {
+    requireString(c, "id", "component", errors);
+    requireString(c, "name", "component", errors);
+    requireEnum(c, "type", COMPONENT_TYPES, "component", errors);
+    requireArray(c, "sourceFiles", "component", errors);
+    requireArray(c, "props", "component", errors);
+    requireArray(c, "referencedByWorkflows", "component", errors);
+    if (c.id) {
+      if (componentIds.has(c.id))
+        errors.push(`Duplicate component id: ${c.id}`);
+      componentIds.add(c.id);
+    }
+  }
+  for (const s of scenarios) {
+    requireString(s, "id", "scenario", errors);
+    requireString(s, "workflowId", "scenario", errors);
+    requireString(s, "featureId", "scenario", errors);
+    requireString(s, "name", "scenario", errors);
+    requireString(s, "description", "scenario", errors);
+    requireEnum(s, "category", SCENARIO_CATEGORIES, "scenario", errors);
+    requireArray(s, "preconditions", "scenario", errors);
+    requireArray(s, "steps", "scenario", errors);
+    requireString(s, "expectedOutcome", "scenario", errors);
+    requireArray(s, "componentIds", "scenario", errors);
+    requireArray(s, "workflowStepIds", "scenario", errors);
+    requireEnum(s, "priority", SCENARIO_PRIORITIES, "scenario", errors);
+    if (s.id) {
+      if (scenarioIds.has(s.id))
+        errors.push(`Duplicate scenario id: ${s.id}`);
+      scenarioIds.add(s.id);
+    }
+    if (Array.isArray(s.steps)) {
+      for (const step of s.steps) {
+        requireNumber(step, "order", "scenarioStep", errors);
+        requireString(step, "action", "scenarioStep", errors);
+        requireString(step, "expectedResult", "scenarioStep", errors);
+      }
+    }
+  }
+  for (const w of workflows) {
+    if (w.featureId && !featureIds.has(w.featureId)) {
+      errors.push(`Workflow "${w.id}" references unknown feature: ${w.featureId}`);
+    }
+    if (Array.isArray(w.componentIds)) {
+      for (const cid of w.componentIds) {
+        if (!componentIds.has(cid)) {
+          errors.push(`Workflow "${w.id}" references unknown component: ${cid}`);
+        }
+      }
+    }
+  }
+  for (const f of features) {
+    if (Array.isArray(f.workflowIds)) {
+      for (const wid of f.workflowIds) {
+        if (!workflowIds.has(wid)) {
+          errors.push(`Feature "${f.id}" references unknown workflow: ${wid}`);
+        }
+      }
+    }
+  }
+  for (const s of scenarios) {
+    if (s.workflowId && !workflowIds.has(s.workflowId)) {
+      errors.push(`Scenario "${s.id}" references unknown workflow: ${s.workflowId}`);
+    }
+    if (s.featureId && !featureIds.has(s.featureId)) {
+      errors.push(`Scenario "${s.id}" references unknown feature: ${s.featureId}`);
+    }
+    if (Array.isArray(s.componentIds)) {
+      for (const cid of s.componentIds) {
+        if (!componentIds.has(cid)) {
+          errors.push(`Scenario "${s.id}" references unknown component: ${cid}`);
+        }
+      }
+    }
+    if (Array.isArray(s.workflowStepIds)) {
+      for (const wsid of s.workflowStepIds) {
+        if (!workflowStepIds.has(wsid)) {
+          errors.push(`Scenario "${s.id}" references unknown workflow step: ${wsid}`);
+        }
+      }
+    }
+  }
+  for (const c of components) {
+    if (Array.isArray(c.referencedByWorkflows)) {
+      for (const wid of c.referencedByWorkflows) {
+        if (!workflowIds.has(wid)) {
+          errors.push(`Component "${c.id}" references unknown workflow: ${wid}`);
+        }
+      }
+    }
+  }
+  for (const f of features) {
+    if (Array.isArray(f.workflowIds) && f.workflowIds.length === 0) {
+      warnings.push(`Feature "${f.id}" has no workflows`);
+    }
+  }
+  for (const w of workflows) {
+    const hasScenarios = scenarios.some((s) => s.workflowId === w.id);
+    if (!hasScenarios) {
+      warnings.push(`Workflow "${w.id}" has no scenarios`);
+    }
+  }
+  const referencedComponentIds = new Set;
+  for (const w of workflows) {
+    if (Array.isArray(w.componentIds)) {
+      for (const cid of w.componentIds)
+        referencedComponentIds.add(cid);
+    }
+  }
+  for (const c of components) {
+    if (c.id && !referencedComponentIds.has(c.id)) {
+      warnings.push(`Component "${c.id}" is not referenced by any workflow`);
+    }
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+function assertArray(obj, field, errors) {
+  if (!Array.isArray(obj[field])) {
+    errors.push(`Missing or invalid top-level array: ${field}`);
+    return [];
+  }
+  return obj[field];
+}
+function requireString(obj, field, context, errors) {
+  if (typeof obj?.[field] !== "string" || obj[field].length === 0) {
+    errors.push(`${context} missing required string field: ${field} (id: ${obj?.id ?? "unknown"})`);
+  }
+}
+function requireNumber(obj, field, context, errors) {
+  if (typeof obj?.[field] !== "number") {
+    errors.push(`${context} missing required number field: ${field} (id: ${obj?.id ?? "unknown"})`);
+  }
+}
+function requireArray(obj, field, context, errors) {
+  if (!Array.isArray(obj?.[field])) {
+    errors.push(`${context} missing required array field: ${field} (id: ${obj?.id ?? "unknown"})`);
+  }
+}
+function requireEnum(obj, field, allowed, context, errors) {
+  if (typeof obj?.[field] !== "string" || !allowed.includes(obj[field])) {
+    errors.push(`${context} invalid ${field}: "${obj?.[field]}" — expected one of: ${allowed.join(", ")} (id: ${obj?.id ?? "unknown"})`);
+  }
+}
 
 // src/utils/scan.ts
 import { readdirSync, existsSync, readFileSync } from "node:fs";
@@ -14970,14 +15245,15 @@ NEVER run multiple pipeline steps at once. Each step is a separate job with its
 ## Protocol
 
 1. **Plan first.** Call \`e2e_ai_plan_workflow\` with the user's goal. This returns a structured todo list of steps.
-2. **Present the plan.** Show the user the ordered step list with descriptions. Ask for confirmation or adjustments before proceeding.
-3. **Execute one step at a time.** For each step in the approved plan:
+2. **Check prerequisites.** The plan includes a \`ready\` boolean and \`missingPrerequisites\` array. If \`ready\` is false, show the user what's missing (API keys, config, etc.) and **wait for them to fix it** before proceeding. Do NOT attempt to execute any step while prerequisites are missing.
+3. **Present the plan.** Show the user the ordered step list with descriptions. Ask for confirmation or adjustments before proceeding.
+4. **Execute one step at a time.** For each step in the approved plan:
    a. Tell the user which step you're about to run and why.
    b. Call \`e2e_ai_execute_step\` with the step name and parameters.
    c. Report the result to the user (success, key output, any warnings).
    d. If the step fails, stop and discuss with the user before continuing.
    e. Move to the next step only after the current one succeeds.
-4. **Use subagents when available.** If your AI platform supports subagents (e.g., Claude Code Agent tool), dispatch each step as a dedicated subagent to preserve context. Each subagent should:
+5. **Use subagents when available.** If your AI platform supports subagents (e.g., Claude Code Agent tool), dispatch each step as a dedicated subagent to preserve context. Each subagent should:
    - Receive only the context it needs (step name, key, relevant file paths)
    - Call \`e2e_ai_execute_step\` to do its work
    - Return the result to the orchestrator
@@ -15010,6 +15286,20 @@ The \`record\` step opens a browser and requires user interaction. When the plan
 - **Single step**: any individual command
 
 Always use \`e2e_ai_plan_workflow\` to determine the right steps — don't guess.
+
+## Scanner Analysis (Interactive QA Map)
+
+For deep codebase analysis and QA map generation, use the interactive scanner workflow instead of the CLI pipeline:
+
+1. **Load the protocol.** Call \`e2e_ai_read_agent("scanner-agent")\` — this returns the full interactive protocol.
+2. **Scan.** Call \`e2e_ai_scan_ast()\` to run the AST scanner and get a compact summary.
+3. **Explore.** Use \`e2e_ai_scan_ast_detail()\` to drill into routes, components, hooks, or files.
+4. **Propose & discuss.** Present candidate features to the user, ask clarifying questions.
+5. **Build.** Construct the QA map payload and validate with \`e2e_ai_build_qa_map({ dryRun: true })\`.
+6. **Write.** Once validated and approved, call \`e2e_ai_build_qa_map({ dryRun: false })\` to save.
+7. **Read existing.** Use \`e2e_ai_read_qa_map()\` to load a previously generated QA map for incremental updates.
+
+This approach is preferred over \`scan → analyze\` CLI steps because it allows interactive refinement with the user.
 `.trim();
 var TEST_PIPELINE_STEPS = [
   {
@@ -15095,6 +15385,87 @@ var SCANNER_PIPELINE_STEPS = [
   }
 ];
 var ALL_STEPS = [...TEST_PIPELINE_STEPS, ...SCANNER_PIPELINE_STEPS];
+var STEP_REQUIREMENTS = {
+  record: { envVars: [] },
+  transcribe: { envVars: [{ name: "OPENAI_API_KEY", reason: "Whisper transcription requires OpenAI API key" }] },
+  scenario: { envVars: [
+    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
+    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
+  ] },
+  generate: { envVars: [
+    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
+    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
+  ] },
+  refine: { envVars: [
+    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
+    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
+  ] },
+  test: { envVars: [] },
+  heal: { envVars: [
+    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
+    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
+  ] },
+  qa: { envVars: [
+    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
+    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
+  ] },
+  scan: { envVars: [] },
+  analyze: { envVars: [
+    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
+    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
+  ] },
+  push: { envVars: [
+    { name: "E2E_AI_API_URL", reason: "Push requires API URL (set E2E_AI_API_URL or push.apiUrl in config)" },
+    { name: "E2E_AI_API_KEY", reason: "Push requires API key (set E2E_AI_API_KEY or push.apiKey in config)" }
+  ] }
+};
+function getProvider() {
+  return process.env.AI_PROVIDER ?? "openai";
+}
+function checkPrerequisites(stepNames) {
+  const issueMap = new Map;
+  for (const stepName of stepNames) {
+    const reqs = STEP_REQUIREMENTS[stepName];
+    if (!reqs)
+      continue;
+    for (const envReq of reqs.envVars) {
+      if (envReq.onlyIf && !envReq.onlyIf())
+        continue;
+      if (!process.env[envReq.name]) {
+        const key = `env:${envReq.name}`;
+        if (issueMap.has(key)) {
+          issueMap.get(key).stepsAffected.push(stepName);
+        } else {
+          issueMap.set(key, {
+            type: "env_var",
+            name: envReq.name,
+            reason: envReq.reason,
+            stepsAffected: [stepName]
+          });
+        }
+      }
+    }
+    if (reqs.files) {
+      for (const fileReq of reqs.files) {
+        if (!existsSync2(fileReq.path)) {
+          const key = `file:${fileReq.path}`;
+          if (issueMap.has(key)) {
+            issueMap.get(key).stepsAffected.push(stepName);
+          } else {
+            issueMap.set(key, {
+              type: "file",
+              name: fileReq.label,
+              reason: `File not found: ${fileReq.path}`,
+              stepsAffected: [stepName]
+            });
+          }
+        }
+      }
+    }
+  }
+  const missing = Array.from(issueMap.values());
+  return { ready: missing.length === 0, missing };
+}
 function planWorkflow(goal, options) {
   const goalLower = goal.toLowerCase();
   const notes = [];
@@ -15179,7 +15550,8 @@ function planWorkflow(goal, options) {
   if (!options.key && pipeline2 === "test" && steps.length > 1) {
     notes.push("No --key provided. Use --key <ISSUE-KEY> to organize files by issue.");
   }
-  return { goal, pipeline: pipeline2, steps, notes };
+  const prereqs = checkPrerequisites(steps.map((s) => s.name));
+  return { goal, pipeline: pipeline2, ready: prereqs.ready, missingPrerequisites: prereqs.missing, steps, notes };
 }
 function executeStep(stepName, options) {
   const args = [stepName];
@@ -15229,7 +15601,7 @@ ${stderr}`,
     };
   }
 }
-var server = new McpServer({ name: "e2e-ai", version: "1.2.0" }, { instructions: SERVER_INSTRUCTIONS });
+var server = new McpServer({ name: "e2e-ai", version: "1.5.0" }, { instructions: SERVER_INSTRUCTIONS });
 server.registerTool("e2e_ai_scan_codebase", {
   title: "Scan Codebase",
   description: "Scan a project directory for test files, configs, fixtures, path aliases, and sample test content. Use this during project setup or to understand test infrastructure.",
@@ -15257,7 +15629,7 @@ server.registerTool("e2e_ai_validate_context", {
 });
 server.registerTool("e2e_ai_read_agent", {
   title: "Read Agent",
-  description: "Read an agent prompt definition by name. Returns the agent system prompt and config. Agents: transcript-agent, scenario-agent, playwright-generator-agent, refactor-agent, self-healing-agent, qa-testcase-agent, feature-analyzer-agent, scenario-planner-agent, init-agent.",
+  description: "Read an agent prompt definition by name. Returns the agent system prompt and config. Agents: transcript-agent, scenario-agent, playwright-generator-agent, refactor-agent, self-healing-agent, qa-testcase-agent, feature-analyzer-agent, scenario-planner-agent, scanner-agent, init-agent.",
   inputSchema: exports_external.object({
     agentName: exports_external.string().describe("Agent name (e.g. scenario-agent, playwright-generator-agent)")
   })
@@ -15343,6 +15715,27 @@ server.registerTool("e2e_ai_execute_step", {
       isError: true
     };
   }
+  const prereqs = checkPrerequisites([step]);
+  if (!prereqs.ready) {
+    const lines = prereqs.missing.map((m) => `- ${m.type === "env_var" ? `Set ${m.name}` : m.name}: ${m.reason}`);
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          step,
+          success: false,
+          blocked: true,
+          missingPrerequisites: prereqs.missing,
+          message: `Cannot run "${step}" — missing prerequisites:
+${lines.join(`
+`)}
+
+Ask the user to provide these before retrying.`
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
   const result = executeStep(step, { key, voice, trace, scanDir, output, extraArgs });
   return {
     content: [{
@@ -15380,6 +15773,147 @@ server.registerTool("e2e_ai_get_workflow_guide", {
     };
   }
 });
+server.registerTool("e2e_ai_scan_ast", {
+  title: "Scan AST",
+  description: "Run the deep AST scanner on the codebase. Returns a compact summary (stats, routes, components, hooks, directory groups). " + "The full AST is saved to .e2e-ai/ast-scan.json for follow-up queries via e2e_ai_scan_ast_detail.",
+  inputSchema: exports_external.object({
+    scanDir: exports_external.string().optional().describe('Directory to scan (defaults to "src")'),
+    include: exports_external.array(exports_external.string()).optional().describe('Glob patterns to include (defaults to ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"])'),
+    exclude: exports_external.array(exports_external.string()).optional().describe("Glob patterns to exclude (defaults to common non-source dirs)")
+  })
+}, async ({ scanDir, include, exclude }) => {
+  try {
+    const cwd = process.cwd();
+    const dir = scanDir ?? "src";
+    const scanConfig = {
+      scanDir: join2(cwd, dir),
+      include: include ?? ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
+      exclude: exclude ?? ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.next/**", "**/*.test.*", "**/*.spec.*", "**/__tests__/**"],
+      cacheDir: join2(cwd, ".e2e-ai", "cache")
+    };
+    const ast = await runStage1(scanConfig);
+    const astPath = join2(cwd, ".e2e-ai", "ast-scan.json");
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+    mkdirSync(join2(cwd, ".e2e-ai"), { recursive: true });
+    writeFileSync(astPath, JSON.stringify(ast, null, 2));
+    const summary = summarizeAST(ast, astPath);
+    return {
+      content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error scanning AST: ${err.message}` }],
+      isError: true
+    };
+  }
+});
+server.registerTool("e2e_ai_scan_ast_detail", {
+  title: "Scan AST Detail",
+  description: "Retrieve a filtered slice of the AST scan. Requires a prior e2e_ai_scan_ast call. " + "Use to drill into routes, components, hooks, dependencies, or files.",
+  inputSchema: exports_external.object({
+    category: exports_external.enum(["routes", "components", "hooks", "dependencies", "files"]).describe("Which AST category to retrieve"),
+    filter: exports_external.string().optional().describe('Glob pattern to filter results (e.g. "src/app/**", "Dashboard*")'),
+    limit: exports_external.number().optional().describe("Max number of items to return")
+  })
+}, async ({ category, filter, limit }) => {
+  try {
+    const astPath = join2(process.cwd(), ".e2e-ai", "ast-scan.json");
+    if (!existsSync2(astPath)) {
+      return {
+        content: [{ type: "text", text: "Error: No AST scan found. Run e2e_ai_scan_ast first." }],
+        isError: true
+      };
+    }
+    const ast = JSON.parse(readFileSync2(astPath, "utf-8"));
+    const result = filterASTByCategory(ast, category, filter, limit);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error reading AST detail: ${err.message}` }],
+      isError: true
+    };
+  }
+});
+server.registerTool("e2e_ai_build_qa_map", {
+  title: "Build QA Map",
+  description: "Validate and optionally write a QAMapV2Payload. Use dryRun: true to validate without writing. " + "Returns validation result with errors, warnings, and stats.",
+  inputSchema: exports_external.object({
+    payload: exports_external.any().describe("QAMapV2Payload JSON object with features, workflows, components, scenarios"),
+    output: exports_external.string().optional().describe("Output file path (defaults to .e2e-ai/qa-map.json)"),
+    dryRun: exports_external.boolean().optional().describe("If true, validate only without writing (default: false)")
+  })
+}, async ({ payload, output, dryRun }) => {
+  try {
+    const validation = validateQAMap(payload);
+    if (validation.valid && payload && typeof payload === "object") {
+      try {
+        const sha = execSync("git rev-parse HEAD", { encoding: "utf-8" }).trim();
+        payload.commitSha = sha;
+      } catch {}
+    }
+    const outputPath = output ?? join2(process.cwd(), ".e2e-ai", "qa-map.json");
+    let written = false;
+    if (validation.valid && !dryRun) {
+      const { mkdirSync, writeFileSync } = await import("node:fs");
+      const { dirname: dirname2 } = await import("node:path");
+      mkdirSync(dirname2(outputPath), { recursive: true });
+      writeFileSync(outputPath, JSON.stringify(payload, null, 2));
+      written = true;
+    }
+    const p = payload;
+    const stats = validation.valid ? {
+      features: Array.isArray(p?.features) ? p.features.length : 0,
+      workflows: Array.isArray(p?.workflows) ? p.workflows.length : 0,
+      components: Array.isArray(p?.components) ? p.components.length : 0,
+      scenarios: Array.isArray(p?.scenarios) ? p.scenarios.length : 0
+    } : null;
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          valid: validation.valid,
+          errors: validation.errors,
+          warnings: validation.warnings,
+          written,
+          outputPath: written ? outputPath : null,
+          stats
+        }, null, 2)
+      }]
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error building QA map: ${err.message}` }],
+      isError: true
+    };
+  }
+});
+server.registerTool("e2e_ai_read_qa_map", {
+  title: "Read QA Map",
+  description: "Read an existing QA map file. Returns the parsed QAMapV2Payload or null if not found.",
+  inputSchema: exports_external.object({
+    path: exports_external.string().optional().describe("Path to QA map file (defaults to .e2e-ai/qa-map.json)")
+  })
+}, async ({ path }) => {
+  try {
+    const mapPath = path ?? join2(process.cwd(), ".e2e-ai", "qa-map.json");
+    if (!existsSync2(mapPath)) {
+      return {
+        content: [{ type: "text", text: JSON.stringify(null) }]
+      };
+    }
+    const content = readFileSync2(mapPath, "utf-8");
+    return {
+      content: [{ type: "text", text: content }]
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error reading QA map: ${err.message}` }],
+      isError: true
+    };
+  }
+});
 async function main() {
   const transport = new StdioServerTransport;
   await server.connect(transport);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "e2e-ai",
   "description": "AI-powered test automation pipeline — record, transcribe, generate, heal and ship Playwright tests from a single CLI",
-  "version": "1.4.3",
+  "version": "1.5.1",
   "private": false,
   "type": "module",
   "bin": {

package/templates/workflow.md

@@ -232,7 +232,16 @@ After running the pipeline for `PROJ-101`:
   config.ts              ← your configuration
   context.md             ← project context (teach AI your conventions)
   workflow.md            ← this file
-  agents/                ← AI agent prompts (customizable)
+  agents/                ← AI agent prompts (numbered by pipeline order)
+    0.init-agent.md
+    1_1.transcript-agent.md
+    1_2.scenario-agent.md
+    2.playwright-generator-agent.md
+    3.refactor-agent.md
+    4.self-healing-agent.md
+    5.qa-testcase-agent.md
+    6_1.feature-analyzer-agent.md
+    6_2.scenario-planner-agent.md
   PROJ-101/              ← working files (codegen, recordings)
 
 e2e/