e2e-ai 1.4.3 → 1.5.0

package/README.md

@@ -505,25 +505,21 @@ E2E_AI_API_KEY=key-...          # API key for push command
 
 ## AI Agents
 
-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
-- **Rules**: numbered constraints (e.g. "never remove assertions")
-- **Examples**: concrete input/output pairs
-
-| Agent | Input | Output | Used by |
-|-------|-------|--------|---------|
-| `transcript-agent` | codegen + transcript JSON | Structured narrative with intent mapping | `scenario` |
-| `scenario-agent` | narrative + issue context | YAML test scenario | `scenario` |
-| `playwright-generator-agent` | scenario + project context | `.test.ts` file | `generate` |
-| `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` or `config.llm.agentModels`).
+Nine specialized agents live in `agents/*.md`, numbered by pipeline order. Each has a system prompt, input/output schemas, rules, and examples.
+
+| # | File | Input | Output | Used by |
+|---|------|-------|--------|---------|
+| 0 | `0.init-agent` | Codebase scan | `.e2e-ai/context.md` | `init` (AI chat) |
+| 1.1 | `1_1.transcript-agent` | codegen + transcript JSON | Structured narrative with intent mapping | `scenario` |
+| 1.2 | `1_2.scenario-agent` | narrative + issue context | YAML test scenario | `scenario` |
+| 2 | `2.playwright-generator-agent` | scenario + project context | `.test.ts` file | `generate` |
+| 3 | `3.refactor-agent` | test + project context | Improved test file | `refine` |
+| 4 | `4.self-healing-agent` | failing test + error output | Diagnosis + patched test | `heal` |
+| 5 | `5.qa-testcase-agent` | test + scenario + issue data | QA markdown + test case JSON | `qa` |
+| 6.1 | `6_1.feature-analyzer-agent` | AST scan result | Features, workflows, components JSON | `analyze` |
+| 6.2 | `6_2.scenario-planner-agent` | Features + workflows | Complete QA map with scenarios JSON | `analyze` |
+
+Agents are loaded by bare name (e.g., `loadAgent('scenario-agent')`) — the numbered prefix is resolved automatically. You can customize agent behavior by editing the `.md` files in `.e2e-ai/agents/`.
 
 ## Output Directory Structure
 

package/dist/cli-hjczkpxm.js

@@ -0,0 +1,117 @@
+import {
+  getPackageRoot,
+  getProjectRoot
+} from "./cli-kx32qnf3.js";
+
+// src/agents/loadAgent.ts
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+function resolveAgentFile(dir, agentName) {
+  const exact = join(dir, `${agentName}.md`);
+  if (existsSync(exact))
+    return exact;
+  try {
+    const files = readdirSync(dir);
+    const suffix = `.${agentName}.md`;
+    const match = files.find((f) => f.endsWith(suffix));
+    if (match)
+      return join(dir, match);
+  } catch {}
+  return null;
+}
+function loadAgent(agentName, config) {
+  const localDir = join(getProjectRoot(), ".e2e-ai", "agents");
+  const packageDir = join(getPackageRoot(), "agents");
+  const filePath = resolveAgentFile(localDir, agentName) ?? resolveAgentFile(packageDir, agentName);
+  if (!filePath) {
+    throw new Error(`Agent file not found for "${agentName}" in ${localDir} or ${packageDir}`);
+  }
+  let content;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch {
+    throw new Error(`Agent file not readable: ${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.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   loadAgent
-} from "./cli-98db6h2q.js";
+} from "./cli-hjczkpxm.js";
 import {
   getPackageRoot,
   getProjectRoot,
@@ -9057,33 +9057,35 @@ function registerInit(program2) {
   program2.command("init").description("Initialize e2e-ai configuration for your project").option("--non-interactive", "Skip interactive prompts, use defaults").action(async (cmdOpts) => {
     const projectRoot = getProjectRoot();
     const e2eDir = join13(projectRoot, ".e2e-ai");
-    header("e2e-ai init");
-    const answers = cmdOpts?.nonInteractive ? getDefaultAnswers() : await askConfigQuestions();
-    const config = buildConfigFromAnswers(answers);
+    const nonInteractive = !!cmdOpts?.nonInteractive;
     const configPath = join13(e2eDir, "config.ts");
-    if (fileExists(configPath)) {
-      warn(`Config already exists: ${configPath}`);
-      const overwrite = cmdOpts?.nonInteractive ? false : await dist_default4({ message: "Overwrite existing config?", default: false });
-      if (!overwrite) {
-        info("Skipping config generation");
-      } else {
-        writeFile(configPath, generateConfigFile(config));
-        success(`Config written: ${configPath}`);
-      }
+    const isReInit = fileExists(configPath);
+    header("e2e-ai init");
+    if (isReInit) {
+      info(`Existing .e2e-ai/ detected — preserving config and context.
+`);
+      await copyAgentsToLocal(projectRoot, nonInteractive);
+      await copyWorkflowGuide(projectRoot, nonInteractive);
     } else {
+      const answers = nonInteractive ? getDefaultAnswers() : await askConfigQuestions();
+      const config = buildConfigFromAnswers(answers);
       writeFile(configPath, generateConfigFile(config));
       success(`Config written: ${configPath}`);
+      await copyAgentsToLocal(projectRoot, nonInteractive);
+      await copyWorkflowGuide(projectRoot, nonInteractive);
     }
-    await copyAgentsToLocal(projectRoot, !!cmdOpts?.nonInteractive);
-    copyWorkflowGuide(projectRoot);
     console.log("");
     success(`Initialization complete!
 `);
-    console.log(import_picocolors2.default.bold("Next steps:"));
-    console.log(`  1. Use the ${import_picocolors2.default.cyan("init-agent")} in your AI tool to generate ${import_picocolors2.default.cyan(".e2e-ai/context.md")}`);
-    console.log(`     (or use the MCP server: ${import_picocolors2.default.cyan("e2e_ai_scan_codebase")} + ${import_picocolors2.default.cyan("e2e_ai_read_agent")})`);
-    console.log(`  2. Review the generated ${import_picocolors2.default.cyan(".e2e-ai/context.md")}`);
-    console.log(`  3. Run: ${import_picocolors2.default.cyan("e2e-ai run --key PROJ-101")}`);
+    if (!isReInit) {
+      console.log(import_picocolors2.default.bold("Next steps:"));
+      console.log(`  1. Use the ${import_picocolors2.default.cyan("init-agent")} in your AI tool to generate ${import_picocolors2.default.cyan(".e2e-ai/context.md")}`);
+      console.log(`     (or use the MCP server: ${import_picocolors2.default.cyan("e2e_ai_scan_codebase")} + ${import_picocolors2.default.cyan("e2e_ai_read_agent")})`);
+      console.log(`  2. Review the generated ${import_picocolors2.default.cyan(".e2e-ai/context.md")}`);
+      console.log(`  3. Run: ${import_picocolors2.default.cyan("e2e-ai run --key PROJ-101")}`);
+    } else {
+      console.log(import_picocolors2.default.dim("Config and context.md were preserved. Only agents and workflow were checked."));
+    }
   });
 }
 function getDefaultAnswers() {
@@ -9199,8 +9201,8 @@ async function copyAgentsToLocal(projectRoot, nonInteractive) {
         return 0;
       }
       const overwrite = await dist_default4({
-        message: `Agent files already exist in .e2e-ai/agents/ (${existingFiles.length} files). Overwrite?`,
-        default: false
+        message: `Update agents to latest version? (${agentFiles.length} files, currently ${existingFiles.length} in .e2e-ai/agents/)`,
+        default: true
       });
       if (!overwrite) {
         info("Skipping agent copy");
@@ -9216,14 +9218,26 @@ async function copyAgentsToLocal(projectRoot, nonInteractive) {
   success(`Agents copied to .e2e-ai/agents/ (${agentFiles.length} files)`);
   return agentFiles.length;
 }
-function copyWorkflowGuide(projectRoot) {
+async function copyWorkflowGuide(projectRoot, nonInteractive) {
   const packageRoot = getPackageRoot();
   const source = join13(packageRoot, "templates", "workflow.md");
   const target = join13(projectRoot, ".e2e-ai", "workflow.md");
   if (!existsSync2(source))
     return;
-  if (existsSync2(target))
-    return;
+  if (existsSync2(target)) {
+    if (nonInteractive) {
+      info("Workflow guide already exists, skipping");
+      return;
+    }
+    const overwrite = await dist_default4({
+      message: "Update workflow.md to latest version?",
+      default: true
+    });
+    if (!overwrite) {
+      info("Skipping workflow guide update");
+      return;
+    }
+  }
   const content = readFileSync2(source, "utf-8");
   writeFile(target, content);
   success("Workflow guide written to .e2e-ai/workflow.md");

package/dist/mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   loadAgent
-} from "./cli-98db6h2q.js";
+} from "./cli-hjczkpxm.js";
 import {
   getPackageRoot
 } from "./cli-kx32qnf3.js";
@@ -14856,9 +14856,9 @@ 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/utils/scan.ts
 import { readdirSync, existsSync, readFileSync } from "node:fs";
@@ -14970,14 +14970,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
@@ -15095,6 +15096,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 +15261,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 +15312,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.",
@@ -15343,6 +15426,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: [{

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.0",
   "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/