@yasserkhanorg/e2e-agents 0.4.0 → 0.5.0

package/dist/cli.js

@@ -72,7 +72,7 @@ function printUsage() {
         '  e2e-ai-agents feedback --path <app-root> --feedback-input <json>',
         '  e2e-ai-agents traceability-capture --path <app-root> --traceability-report <json>',
         '  e2e-ai-agents traceability-ingest --path <app-root> --traceability-input <json>',
-        '  e2e-ai-agents analyze --path <app-root> [--tests-root <path>] [--since <ref>] [--generate] [--generate-output <dir>]',
+        '  e2e-ai-agents analyze --path <app-root> [--tests-root <path>] [--since <ref>] [--generate] [--generate-output <dir>] [--heal] [--heal-report <json>]',
         '  e2e-ai-agents llm-health',
         '',
         'Options:',
@@ -493,6 +493,15 @@ function parseArgs(argv) {
             i += 1;
             continue;
         }
+        if (arg === '--heal') {
+            parsed.analyzeHeal = true;
+            continue;
+        }
+        if (arg === '--heal-report' && next) {
+            parsed.analyzeHealReport = next;
+            i += 1;
+            continue;
+        }
     }
     return parsed;
 }
@@ -528,6 +537,9 @@ async function main() {
         if (args.analyzeGenerate) {
             analyzeStages.push('generation');
         }
+        if (args.analyzeHeal || args.analyzeHealReport) {
+            analyzeStages.push('heal');
+        }
         const result = await (0, orchestrator_js_1.runPipeline)({
             appPath: config.path,
             testsRoot,
@@ -541,6 +553,17 @@ async function main() {
                     dryRun: args.dryRun,
                 }
                 : undefined,
+            heal: (args.analyzeHeal || args.analyzeHealReport)
+                ? {
+                    mcp: args.pipelineMcp ?? true,
+                    mcpAllowFallback: args.pipelineMcpAllowFallback ?? false,
+                    mcpOnly: args.pipelineMcpOnly ?? false,
+                    mcpCommandTimeoutMs: args.pipelineMcpTimeoutMs,
+                    mcpRetries: args.pipelineMcpRetries ?? 1,
+                    dryRun: args.dryRun,
+                }
+                : undefined,
+            playwrightReportPath: args.analyzeHealReport,
         });
         // eslint-disable-next-line no-console
         console.log(`Analyze report: ${result.reportPath}`);
@@ -563,6 +586,12 @@ async function main() {
                 console.log(`  ${g.mode}: ${g.specPath}`);
             }
         }
+        if (result.healResult) {
+            const healed = result.healResult.summary.results.filter((r) => r.healStatus === 'success').length;
+            const healFailed = result.healResult.summary.results.filter((r) => r.healStatus === 'failed').length;
+            // eslint-disable-next-line no-console
+            console.log(`Analyze heal targets: ${result.healResult.targets.length} (healed=${healed}, failed=${healFailed})`);
+        }
         if (result.warnings.length > 0) {
             // eslint-disable-next-line no-console
             console.log(`Analyze warnings: ${result.warnings.join(' | ')}`);

package/dist/esm/cli.js

@@ -70,7 +70,7 @@ function printUsage() {
         '  e2e-ai-agents feedback --path <app-root> --feedback-input <json>',
         '  e2e-ai-agents traceability-capture --path <app-root> --traceability-report <json>',
         '  e2e-ai-agents traceability-ingest --path <app-root> --traceability-input <json>',
-        '  e2e-ai-agents analyze --path <app-root> [--tests-root <path>] [--since <ref>] [--generate] [--generate-output <dir>]',
+        '  e2e-ai-agents analyze --path <app-root> [--tests-root <path>] [--since <ref>] [--generate] [--generate-output <dir>] [--heal] [--heal-report <json>]',
         '  e2e-ai-agents llm-health',
         '',
         'Options:',
@@ -491,6 +491,15 @@ function parseArgs(argv) {
             i += 1;
             continue;
         }
+        if (arg === '--heal') {
+            parsed.analyzeHeal = true;
+            continue;
+        }
+        if (arg === '--heal-report' && next) {
+            parsed.analyzeHealReport = next;
+            i += 1;
+            continue;
+        }
     }
     return parsed;
 }
@@ -526,6 +535,9 @@ async function main() {
         if (args.analyzeGenerate) {
             analyzeStages.push('generation');
         }
+        if (args.analyzeHeal || args.analyzeHealReport) {
+            analyzeStages.push('heal');
+        }
         const result = await runPipeline({
             appPath: config.path,
             testsRoot,
@@ -539,6 +551,17 @@ async function main() {
                     dryRun: args.dryRun,
                 }
                 : undefined,
+            heal: (args.analyzeHeal || args.analyzeHealReport)
+                ? {
+                    mcp: args.pipelineMcp ?? true,
+                    mcpAllowFallback: args.pipelineMcpAllowFallback ?? false,
+                    mcpOnly: args.pipelineMcpOnly ?? false,
+                    mcpCommandTimeoutMs: args.pipelineMcpTimeoutMs,
+                    mcpRetries: args.pipelineMcpRetries ?? 1,
+                    dryRun: args.dryRun,
+                }
+                : undefined,
+            playwrightReportPath: args.analyzeHealReport,
         });
         // eslint-disable-next-line no-console
         console.log(`Analyze report: ${result.reportPath}`);
@@ -561,6 +584,12 @@ async function main() {
                 console.log(`  ${g.mode}: ${g.specPath}`);
             }
         }
+        if (result.healResult) {
+            const healed = result.healResult.summary.results.filter((r) => r.healStatus === 'success').length;
+            const healFailed = result.healResult.summary.results.filter((r) => r.healStatus === 'failed').length;
+            // eslint-disable-next-line no-console
+            console.log(`Analyze heal targets: ${result.healResult.targets.length} (healed=${healed}, failed=${healFailed})`);
+        }
         if (result.warnings.length > 0) {
             // eslint-disable-next-line no-console
             console.log(`Analyze warnings: ${result.warnings.join(' | ')}`);

package/dist/esm/index.js

@@ -18,6 +18,8 @@ export { captureTraceabilityInput } from './agent/traceability_capture.js';
 export { runPipeline } from './pipeline/orchestrator.js';
 export { runGenerationStage } from './pipeline/stage3_generation.js';
 export { buildGenerationPrompt, parseGenerationResponse, detectHallucinatedMethods } from './prompts/generation.js';
+export { runHealStage, healFromReport, resolveHealTargets, renderHealMarkdown } from './pipeline/stage4_heal.js';
+export { buildHealPrompt, buildQualityFixPrompt } from './prompts/heal.js';
 // Knowledge modules
 export { loadRouteFamilyManifest, bindFilesToFamilies } from './knowledge/route_families.js';
 export { buildApiSurface, loadOrBuildApiSurface } from './knowledge/api_surface.js';

package/dist/esm/pipeline/orchestrator.js

@@ -7,6 +7,7 @@ import { preprocess } from './stage0_preprocess.js';
 import { runImpactStage } from './stage1_impact.js';
 import { runCoverageStage } from './stage2_coverage.js';
 import { runGenerationStage } from './stage3_generation.js';
+import { runHealStage, resolveHealTargets, renderHealMarkdown } from './stage4_heal.js';
 import { buildSummary } from '../validation/output_schema.js';
 import { computeCannotDetermineRatio } from '../validation/guardrails.js';
 function createRunId() {
@@ -31,6 +32,7 @@ export async function runPipeline(config) {
     const allWarnings = [];
     const stages = config.stages || ['preprocess', 'impact', 'coverage'];
     let generatedSpecs;
+    let healResult;
     // Step 1: Get changed files
     const gitResult = getChangedFiles(config.appPath, config.gitSince, {
         includeUncommitted: config.gitIncludeUncommitted,
@@ -87,6 +89,20 @@ export async function runPipeline(config) {
         generatedSpecs = generationResult.generated;
         allWarnings.push(...generationResult.warnings);
     }
+    // Step 6: Heal stage — MCP-backed playwright-test-healer for failing/flaky specs
+    if (stages.includes('heal')) {
+        const healTargets = resolveHealTargets(config.testsRoot, {
+            playwrightReportPath: config.playwrightReportPath,
+            generatedSpecs,
+        }, decisions);
+        if (healTargets.length > 0) {
+            healResult = await runHealStage(config.testsRoot, healTargets, config.heal || { mcp: true });
+            allWarnings.push(...healResult.warnings);
+        }
+        else {
+            allWarnings.push('Heal stage: no targets found (no failing specs in report, no generated specs).');
+        }
+    }
     // Build report
     const report = {
         runId,
@@ -101,10 +117,10 @@ export async function runPipeline(config) {
             generationAgent: stages.includes('generation') ? (config.generation?.provider || 'auto') : undefined,
         },
     };
-    const reportPath = writeReport(config.testsRoot, report);
-    return { report, reportPath, warnings: allWarnings, generated: generatedSpecs };
+    const reportPath = writeReport(config.testsRoot, report, healResult);
+    return { report, reportPath, warnings: allWarnings, generated: generatedSpecs, healResult };
 }
-function writeReport(testsRoot, report) {
+function writeReport(testsRoot, report, healResult) {
     const outputDir = join(testsRoot, '.e2e-ai-agents');
     if (!existsSync(outputDir)) {
         mkdirSync(outputDir, { recursive: true });
@@ -112,10 +128,10 @@ function writeReport(testsRoot, report) {
     const jsonPath = join(outputDir, 'pipeline-report.json');
     writeFileSync(jsonPath, JSON.stringify(report, null, 2), 'utf-8');
     const mdPath = join(outputDir, 'pipeline-report.md');
-    writeFileSync(mdPath, renderMarkdown(report), 'utf-8');
+    writeFileSync(mdPath, renderMarkdown(report, healResult), 'utf-8');
     return jsonPath;
 }
-function renderMarkdown(report) {
+function renderMarkdown(report, healResult) {
     const lines = [
         `# Impact Analysis Pipeline Report`,
         '',
@@ -188,6 +204,10 @@ function renderMarkdown(report) {
             lines.push('');
         }
     }
+    if (healResult) {
+        lines.push('');
+        lines.push(renderHealMarkdown(healResult));
+    }
     if (report.warnings.length > 0) {
         lines.push('## Warnings', '');
         for (const w of report.warnings) {

package/dist/esm/pipeline/stage4_heal.js

@@ -0,0 +1,145 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { runTargetedSpecHeal } from '../agent/pipeline.js';
+import { extractPlaywrightUnstableSpecs } from '../agent/playwright_report.js';
+/**
+ * Resolve heal targets from one or more sources, in priority order:
+ * 1. Playwright JSON report (CI failures/flakes)
+ * 2. Stage 3 generated specs (newly written files that need runtime validation)
+ * 3. Explicit target list
+ */
+export function resolveHealTargets(testsRoot, options, decisions) {
+    const targets = [];
+    const seen = new Set();
+    const addTarget = (specPath, status, reason) => {
+        // Normalize to absolute path so relative (from Playwright report) and absolute
+        // (from generated specs) deduplicate correctly
+        let normalized = specPath.replace(/\\/g, '/');
+        if (!specPath.startsWith('/') && !(/^[A-Za-z]:[\\/]/).test(specPath)) {
+            normalized = join(testsRoot, specPath).replace(/\\/g, '/');
+        }
+        if (seen.has(normalized)) {
+            return;
+        }
+        seen.add(normalized);
+        // Try to match to a FlowDecision for context
+        const decision = findDecisionForSpec(normalized, decisions, testsRoot);
+        targets.push({ specPath: normalized, status, decision, reason });
+    };
+    // Source 1: Playwright JSON report
+    if (options.playwrightReportPath) {
+        const reportPath = resolve(options.playwrightReportPath);
+        if (existsSync(reportPath)) {
+            const unstable = extractPlaywrightUnstableSpecs(reportPath, [testsRoot]);
+            for (const spec of unstable) {
+                addTarget(spec.specPath, spec.status, `Playwright report: failingTests=${spec.failingTests}, flakyTests=${spec.flakyTests}`);
+            }
+        }
+    }
+    // Source 2: Stage 3 generated specs (heal immediately after generation)
+    if (options.generatedSpecs) {
+        for (const gen of options.generatedSpecs) {
+            if (gen.written) {
+                addTarget(gen.specPath, 'failed', `Newly generated spec — needs runtime validation`);
+            }
+        }
+    }
+    // Source 3: Explicit targets
+    if (options.explicitTargets) {
+        for (const t of options.explicitTargets) {
+            addTarget(t.specPath, t.status, t.reason);
+        }
+    }
+    return targets;
+}
+/**
+ * Find the FlowDecision most relevant to a given spec path by matching
+ * targetSpec / newSpecPath / specPath suffix against decisions.
+ */
+function findDecisionForSpec(specPath, decisions, testsRoot) {
+    const normalizedRoot = testsRoot.replace(/\\/g, '/');
+    const relative = specPath.startsWith(normalizedRoot)
+        ? specPath.slice(normalizedRoot.length).replace(/^\//, '')
+        : specPath;
+    return decisions.find((d) => {
+        const target = (d.targetSpec || d.newSpecPath || '').replace(/\\/g, '/');
+        return target && (target === relative || target === specPath || relative.endsWith(target) || target.endsWith(relative));
+    });
+}
+export async function runHealStage(testsRoot, targets, config) {
+    const warnings = [];
+    if (targets.length === 0) {
+        return {
+            targets,
+            summary: {
+                runner: 'package-native',
+                results: [],
+                warnings: ['No heal targets provided.'],
+            },
+            warnings,
+        };
+    }
+    const healTargets = targets.map((t) => ({
+        specPath: t.specPath,
+        status: t.status,
+        reason: t.reason,
+    }));
+    const pipelineConfig = {
+        enabled: true,
+        scenarios: 1,
+        outputDir: config.outputDir || 'specs/functional/ai-assisted',
+        heal: true,
+        dryRun: config.dryRun,
+        mcp: config.mcp ?? true,
+        mcpAllowFallback: config.mcpAllowFallback ?? false,
+        mcpOnly: config.mcpOnly ?? false,
+        mcpCommandTimeoutMs: config.mcpCommandTimeoutMs,
+        mcpRetries: config.mcpRetries ?? 1,
+    };
+    const summary = runTargetedSpecHeal(testsRoot, healTargets, pipelineConfig);
+    warnings.push(...summary.warnings);
+    return { targets, summary, warnings };
+}
+/**
+ * Convenience: extract heal targets from a complete pipeline report + optional
+ * Playwright run results, then run the heal stage.
+ */
+export async function healFromReport(testsRoot, report, options) {
+    const targets = resolveHealTargets(testsRoot, {
+        playwrightReportPath: options.playwrightReportPath,
+        generatedSpecs: options.generatedSpecs,
+    }, report.decisions);
+    return runHealStage(testsRoot, targets, options.healConfig || { mcp: true });
+}
+/**
+ * Write a heal summary section to the pipeline report markdown.
+ */
+export function renderHealMarkdown(result) {
+    const lines = ['## Heal Results', ''];
+    const healedCount = result.summary.results.filter((r) => r.healStatus === 'success').length;
+    const failedCount = result.summary.results.filter((r) => r.healStatus === 'failed').length;
+    const skippedCount = result.summary.results.filter((r) => r.healStatus === 'skipped').length;
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    lines.push(`| Targets | ${result.targets.length} |`);
+    lines.push(`| Healed | ${healedCount} |`);
+    lines.push(`| Failed | ${failedCount} |`);
+    lines.push(`| Skipped | ${skippedCount} |`);
+    lines.push('');
+    for (const r of result.summary.results) {
+        const icon = r.healStatus === 'success' ? '✅' : r.healStatus === 'failed' ? '❌' : '⏭';
+        lines.push(`- ${icon} \`${r.flowId}\` — heal: ${r.healStatus || 'n/a'}`);
+        if (r.error) {
+            lines.push(`  - Error: ${r.error}`);
+        }
+    }
+    if (result.warnings.length > 0) {
+        lines.push('', '### Heal Warnings', '');
+        for (const w of result.warnings) {
+            lines.push(`- ${w}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/esm/prompts/heal.js

@@ -0,0 +1,69 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Builds a route-family-aware heal prompt for the playwright-test-healer agent.
+ * Enriches the base healer constraints with flow context so the agent understands
+ * what the test is supposed to verify, reducing hallucination during selector repair.
+ */
+export function buildHealPrompt(ctx) {
+    const flowBlock = ctx.decision
+        ? [
+            '',
+            'FLOW CONTEXT (use to understand test intent — do not change test objectives):',
+            `  Flow: ${ctx.decision.flowName}`,
+            `  Route Family: ${ctx.decision.routeFamily}${ctx.decision.featureId ? ` / ${ctx.decision.featureId}` : ''}`,
+            `  Route: ${ctx.decision.specificRoute || '(family-level)'}`,
+            `  User Actions: ${ctx.decision.userActions.join('; ') || 'not specified'}`,
+            `  Evidence: ${ctx.decision.evidence}`,
+        ].join('\n')
+        : '';
+    const statusNote = ctx.status === 'flaky'
+        ? 'This test is FLAKY (passes sometimes, fails other times). Look for race conditions, missing waits, or order-dependent state.'
+        : 'This test is FAILING consistently. The selector, URL, or API call is likely broken.';
+    const failureBlock = ctx.failureDetail
+        ? `\nFailure detail:\n${ctx.failureDetail}`
+        : '';
+    return [
+        'Heal this specific Playwright test file and keep edits minimal.',
+        '',
+        `Target test file: ${ctx.specPath}`,
+        `Status: ${ctx.status.toUpperCase()} — ${statusNote}`,
+        failureBlock,
+        flowBlock,
+        '',
+        'Healing constraints (must follow):',
+        '- Import ONLY from "@mattermost/playwright-lib". Do not use "@playwright/test" directly.',
+        '- Do not use test.describe or test.only.',
+        '- Keep a single tag string matching the route family (e.g. "@channels", "@scheduled_posts").',
+        '- Use only existing Mattermost Playwright fixture and page-object APIs.',
+        '- Do NOT invent new pw.* clients or page object methods that do not exist.',
+        '- Avoid brittle class selectors (.backstage-navbar, .admin-console__wrapper, .left-panel, .panel-card).',
+        '- Prefer stable assertions using URL patterns, data-testid attributes, ARIA roles, and page-object methods.',
+        '- For flaky tests: add explicit waits (waitFor, expect().toBeVisible()) before interactions.',
+        '- Keep the test intent and scenario unchanged — only fix what is broken.',
+        '- If behavior is genuinely broken server-side, mark test.fixme with a clear comment explaining why.',
+        '',
+        'Run and fix this test until it compiles and passes, or mark test.fixme when the behavior is truly broken.',
+    ].filter((line) => line !== null).join('\n');
+}
+/**
+ * Builds a minimal quality-fix prompt for spec files that fail content validation
+ * (e.g. contain test.describe, test.only, wrong imports).
+ */
+export function buildQualityFixPrompt(specPath, qualityIssues) {
+    return [
+        'Fix quality issues in this Playwright spec file. Make minimal edits only.',
+        '',
+        `Target file: ${specPath}`,
+        '',
+        'Issues to fix:',
+        ...qualityIssues.map((issue) => `  - ${issue}`),
+        '',
+        'Rules:',
+        '- Import only from "@mattermost/playwright-lib".',
+        '- Remove test.describe wrappers (flatten to top-level test() calls).',
+        '- Remove test.only calls.',
+        '- Ensure each test has exactly one tag string.',
+        '- Do not change test logic — only fix structural quality issues.',
+    ].join('\n');
+}

package/dist/index.d.ts

@@ -35,6 +35,10 @@ export { runGenerationStage } from './pipeline/stage3_generation.js';
 export type { GenerationConfig, GenerationResult, GeneratedSpec } from './pipeline/stage3_generation.js';
 export { buildGenerationPrompt, parseGenerationResponse, detectHallucinatedMethods } from './prompts/generation.js';
 export type { GenerationPromptContext, GenerationAgentResponse } from './prompts/generation.js';
+export { runHealStage, healFromReport, resolveHealTargets, renderHealMarkdown } from './pipeline/stage4_heal.js';
+export type { HealConfig, HealTarget, HealResult } from './pipeline/stage4_heal.js';
+export { buildHealPrompt, buildQualityFixPrompt } from './prompts/heal.js';
+export type { HealPromptContext } from './prompts/heal.js';
 export { loadRouteFamilyManifest, bindFilesToFamilies } from './knowledge/route_families.js';
 export type { RouteFamily, RouteFeature, RouteFamilyManifest, FileBinding } from './knowledge/route_families.js';
 export { buildApiSurface, loadOrBuildApiSurface } from './knowledge/api_surface.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAGH,YAAY,EACR,WAAW,EACX,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,YAAY,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,gBAAgB,EAAE,0BAA0B,EAAC,MAAM,yBAAyB,CAAC;AAGrF,OAAO,EAAC,iBAAiB,EAAE,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AAC/E,OAAO,EAAC,cAAc,EAAE,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAC,cAAc,EAAE,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAGpD,OAAO,EAAC,kBAAkB,EAAE,qBAAqB,EAAC,MAAM,uBAAuB,CAAC;AAChF,YAAY,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAC,aAAa,EAAE,QAAQ,EAAE,cAAc,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,mBAAmB,EAAC,MAAM,UAAU,CAAC;AACjI,YAAY,EACR,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,4BAA4B,EAC5B,6BAA6B,GAChC,MAAM,UAAU,CAAC;AAClB,OAAO,EAAC,0BAA0B,EAAE,eAAe,EAAC,MAAM,qBAAqB,CAAC;AAChF,YAAY,EAAC,2BAA2B,EAAE,kBAAkB,EAAC,MAAM,qBAAqB,CAAC;AACzF,OAAO,EAAC,sBAAsB,EAAC,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAC,6BAA6B,EAAE,4BAA4B,EAAC,MAAM,oBAAoB,CAAC;AACpG,OAAO,EAAC,uBAAuB,EAAC,MAAM,gCAAgC,CAAC;AACvE,YAAY,EAAC,yBAAyB,EAAE,wBAAwB,EAAE,uBAAuB,EAAC,MAAM,gCAAgC,CAAC;AACjI,OAAO,EAAC,wBAAwB,EAAC,MAAM,iCAAiC,CAAC;AACzE,YAAY,EAAC,0BAA0B,EAAE,yBAAyB,EAAC,MAAM,iCAAiC,CAAC;AAG3G,OAAO,EAAC,WAAW,EAAC,MAAM,4BAA4B,CAAC;AACvD,YAAY,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAC/E,YAAY,EAAC,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,UAAU,EAAE,cAAc,EAAC,MAAM,+BAA+B,CAAC;AACrI,OAAO,EAAC,kBAAkB,EAAC,MAAM,iCAAiC,CAAC;AACnE,YAAY,EAAC,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAC,MAAM,iCAAiC,CAAC;AACvG,OAAO,EAAC,qBAAqB,EAAE,uBAAuB,EAAE,yBAAyB,EAAC,MAAM,yBAAyB,CAAC;AAClH,YAAY,EAAC,uBAAuB,EAAE,uBAAuB,EAAC,MAAM,yBAAyB,CAAC;AAG9F,OAAO,EAAC,uBAAuB,EAAE,mBAAmB,EAAC,MAAM,+BAA+B,CAAC;AAC3F,YAAY,EAAC,WAAW,EAAE,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAC,MAAM,+BAA+B,CAAC;AAC/G,OAAO,EAAC,eAAe,EAAE,qBAAqB,EAAC,MAAM,4BAA4B,CAAC;AAClF,YAAY,EAAC,iBAAiB,EAAE,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AACrF,OAAO,EAAC,cAAc,EAAE,iBAAiB,EAAC,MAAM,2BAA2B,CAAC;AAC5E,YAAY,EAAC,SAAS,EAAE,SAAS,EAAC,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -2,7 +2,7 @@
 // Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
 // See LICENSE.txt for license information.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSpecsForFamily = exports.buildSpecIndex = exports.loadOrBuildApiSurface = exports.buildApiSurface = exports.bindFilesToFamilies = exports.loadRouteFamilyManifest = exports.detectHallucinatedMethods = exports.parseGenerationResponse = exports.buildGenerationPrompt = exports.runGenerationStage = exports.runPipeline = exports.captureTraceabilityInput = exports.ingestTraceabilityInput = exports.finalizeGeneratedTests = exports.readCalibration = exports.appendFeedbackAndRecompute = exports.captureTraceability = exports.ingestTraceability = exports.handoffGeneratedTests = exports.recommendTests = exports.findGaps = exports.analyzeImpact = exports.validateProviderSetup = exports.LLMProviderFactory = exports.CustomProvider = exports.checkOpenAISetup = exports.OpenAIProvider = exports.checkOllamaSetup = exports.OllamaProvider = exports.checkAnthropicSetup = exports.AnthropicProvider = exports.UnsupportedCapabilityError = exports.LLMProviderError = void 0;
+exports.getSpecsForFamily = exports.buildSpecIndex = exports.loadOrBuildApiSurface = exports.buildApiSurface = exports.bindFilesToFamilies = exports.loadRouteFamilyManifest = exports.buildQualityFixPrompt = exports.buildHealPrompt = exports.renderHealMarkdown = exports.resolveHealTargets = exports.healFromReport = exports.runHealStage = exports.detectHallucinatedMethods = exports.parseGenerationResponse = exports.buildGenerationPrompt = exports.runGenerationStage = exports.runPipeline = exports.captureTraceabilityInput = exports.ingestTraceabilityInput = exports.finalizeGeneratedTests = exports.readCalibration = exports.appendFeedbackAndRecompute = exports.captureTraceability = exports.ingestTraceability = exports.handoffGeneratedTests = exports.recommendTests = exports.findGaps = exports.analyzeImpact = exports.validateProviderSetup = exports.LLMProviderFactory = exports.CustomProvider = exports.checkOpenAISetup = exports.OpenAIProvider = exports.checkOllamaSetup = exports.OllamaProvider = exports.checkAnthropicSetup = exports.AnthropicProvider = exports.UnsupportedCapabilityError = exports.LLMProviderError = void 0;
 var provider_interface_js_1 = require("./provider_interface.js");
 Object.defineProperty(exports, "LLMProviderError", { enumerable: true, get: function () { return provider_interface_js_1.LLMProviderError; } });
 Object.defineProperty(exports, "UnsupportedCapabilityError", { enumerable: true, get: function () { return provider_interface_js_1.UnsupportedCapabilityError; } });
@@ -48,6 +48,14 @@ var generation_js_1 = require("./prompts/generation.js");
 Object.defineProperty(exports, "buildGenerationPrompt", { enumerable: true, get: function () { return generation_js_1.buildGenerationPrompt; } });
 Object.defineProperty(exports, "parseGenerationResponse", { enumerable: true, get: function () { return generation_js_1.parseGenerationResponse; } });
 Object.defineProperty(exports, "detectHallucinatedMethods", { enumerable: true, get: function () { return generation_js_1.detectHallucinatedMethods; } });
+var stage4_heal_js_1 = require("./pipeline/stage4_heal.js");
+Object.defineProperty(exports, "runHealStage", { enumerable: true, get: function () { return stage4_heal_js_1.runHealStage; } });
+Object.defineProperty(exports, "healFromReport", { enumerable: true, get: function () { return stage4_heal_js_1.healFromReport; } });
+Object.defineProperty(exports, "resolveHealTargets", { enumerable: true, get: function () { return stage4_heal_js_1.resolveHealTargets; } });
+Object.defineProperty(exports, "renderHealMarkdown", { enumerable: true, get: function () { return stage4_heal_js_1.renderHealMarkdown; } });
+var heal_js_1 = require("./prompts/heal.js");
+Object.defineProperty(exports, "buildHealPrompt", { enumerable: true, get: function () { return heal_js_1.buildHealPrompt; } });
+Object.defineProperty(exports, "buildQualityFixPrompt", { enumerable: true, get: function () { return heal_js_1.buildQualityFixPrompt; } });
 // Knowledge modules
 var route_families_js_1 = require("./knowledge/route_families.js");
 Object.defineProperty(exports, "loadRouteFamilyManifest", { enumerable: true, get: function () { return route_families_js_1.loadRouteFamilyManifest; } });

package/dist/pipeline/orchestrator.d.ts

@@ -1,6 +1,7 @@
 import { type ImpactConfig } from './stage1_impact.js';
 import { type CoverageConfig } from './stage2_coverage.js';
 import { type GenerationConfig, type GeneratedSpec } from './stage3_generation.js';
+import { type HealConfig, type HealResult } from './stage4_heal.js';
 import { type FlowDecisionReport } from '../validation/output_schema.js';
 import type { RouteFamilyConfig } from '../knowledge/route_families.js';
 import type { ApiSurfaceConfig } from '../knowledge/api_surface.js';
@@ -14,13 +15,17 @@ export interface PipelineConfig {
     impact?: ImpactConfig;
     coverage?: CoverageConfig;
     generation?: GenerationConfig;
-    stages?: Array<'preprocess' | 'impact' | 'coverage' | 'generation'>;
+    heal?: HealConfig;
+    /** Path to a Playwright JSON report for heal-from-report mode */
+    playwrightReportPath?: string;
+    stages?: Array<'preprocess' | 'impact' | 'coverage' | 'generation' | 'heal'>;
 }
 export interface PipelineResult {
     report: FlowDecisionReport;
     reportPath: string;
     warnings: string[];
     generated?: GeneratedSpec[];
+    healResult?: HealResult;
 }
 export declare function runPipeline(config: PipelineConfig): Promise<PipelineResult>;
 //# sourceMappingURL=orchestrator.d.ts.map

package/dist/pipeline/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/pipeline/orchestrator.ts"],"names":[],"mappings":"AAOA,OAAO,EAAiB,KAAK,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAmB,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAqB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAC,MAAM,wBAAwB,CAAC;AACrG,OAAO,EAAe,KAAK,kBAAkB,EAAoB,MAAM,gCAAgC,CAAC;AAExG,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,6BAA6B,CAAC;AAElE,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;CAC/B;AAoBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CA6GjF"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/pipeline/orchestrator.ts"],"names":[],"mappings":"AAOA,OAAO,EAAiB,KAAK,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAmB,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAqB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAC,MAAM,wBAAwB,CAAC;AACrG,OAAO,EAAuD,KAAK,UAAU,EAAE,KAAK,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACxH,OAAO,EAAe,KAAK,kBAAkB,EAAoB,MAAM,gCAAgC,CAAC;AAExG,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,6BAA6B,CAAC;AAElE,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,iEAAiE;IACjE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;CAC3B;AAoBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAgIjF"}

package/dist/pipeline/orchestrator.js

@@ -10,6 +10,7 @@ const stage0_preprocess_js_1 = require("./stage0_preprocess.js");
 const stage1_impact_js_1 = require("./stage1_impact.js");
 const stage2_coverage_js_1 = require("./stage2_coverage.js");
 const stage3_generation_js_1 = require("./stage3_generation.js");
+const stage4_heal_js_1 = require("./stage4_heal.js");
 const output_schema_js_1 = require("../validation/output_schema.js");
 const guardrails_js_1 = require("../validation/guardrails.js");
 function createRunId() {
@@ -34,6 +35,7 @@ async function runPipeline(config) {
     const allWarnings = [];
     const stages = config.stages || ['preprocess', 'impact', 'coverage'];
     let generatedSpecs;
+    let healResult;
     // Step 1: Get changed files
     const gitResult = (0, git_js_1.getChangedFiles)(config.appPath, config.gitSince, {
         includeUncommitted: config.gitIncludeUncommitted,
@@ -90,6 +92,20 @@ async function runPipeline(config) {
         generatedSpecs = generationResult.generated;
         allWarnings.push(...generationResult.warnings);
     }
+    // Step 6: Heal stage — MCP-backed playwright-test-healer for failing/flaky specs
+    if (stages.includes('heal')) {
+        const healTargets = (0, stage4_heal_js_1.resolveHealTargets)(config.testsRoot, {
+            playwrightReportPath: config.playwrightReportPath,
+            generatedSpecs,
+        }, decisions);
+        if (healTargets.length > 0) {
+            healResult = await (0, stage4_heal_js_1.runHealStage)(config.testsRoot, healTargets, config.heal || { mcp: true });
+            allWarnings.push(...healResult.warnings);
+        }
+        else {
+            allWarnings.push('Heal stage: no targets found (no failing specs in report, no generated specs).');
+        }
+    }
     // Build report
     const report = {
         runId,
@@ -104,10 +120,10 @@ async function runPipeline(config) {
             generationAgent: stages.includes('generation') ? (config.generation?.provider || 'auto') : undefined,
         },
     };
-    const reportPath = writeReport(config.testsRoot, report);
-    return { report, reportPath, warnings: allWarnings, generated: generatedSpecs };
+    const reportPath = writeReport(config.testsRoot, report, healResult);
+    return { report, reportPath, warnings: allWarnings, generated: generatedSpecs, healResult };
 }
-function writeReport(testsRoot, report) {
+function writeReport(testsRoot, report, healResult) {
     const outputDir = (0, path_1.join)(testsRoot, '.e2e-ai-agents');
     if (!(0, fs_1.existsSync)(outputDir)) {
         (0, fs_1.mkdirSync)(outputDir, { recursive: true });
@@ -115,10 +131,10 @@ function writeReport(testsRoot, report) {
     const jsonPath = (0, path_1.join)(outputDir, 'pipeline-report.json');
     (0, fs_1.writeFileSync)(jsonPath, JSON.stringify(report, null, 2), 'utf-8');
     const mdPath = (0, path_1.join)(outputDir, 'pipeline-report.md');
-    (0, fs_1.writeFileSync)(mdPath, renderMarkdown(report), 'utf-8');
+    (0, fs_1.writeFileSync)(mdPath, renderMarkdown(report, healResult), 'utf-8');
     return jsonPath;
 }
-function renderMarkdown(report) {
+function renderMarkdown(report, healResult) {
     const lines = [
         `# Impact Analysis Pipeline Report`,
         '',
@@ -191,6 +207,10 @@ function renderMarkdown(report) {
             lines.push('');
         }
     }
+    if (healResult) {
+        lines.push('');
+        lines.push((0, stage4_heal_js_1.renderHealMarkdown)(healResult));
+    }
     if (report.warnings.length > 0) {
         lines.push('## Warnings', '');
         for (const w of report.warnings) {

package/dist/pipeline/stage4_heal.d.ts

@@ -0,0 +1,56 @@
+import type { PipelineSummary } from '../agent/pipeline.js';
+import type { FlowDecision, FlowDecisionReport } from '../validation/output_schema.js';
+import type { GeneratedSpec } from './stage3_generation.js';
+export interface HealConfig {
+    /** Enable MCP-backed heal via playwright-test-healer agent */
+    mcp?: boolean;
+    mcpAllowFallback?: boolean;
+    mcpOnly?: boolean;
+    mcpCommandTimeoutMs?: number;
+    mcpRetries?: number;
+    dryRun?: boolean;
+    /** Output directory for healed/re-generated specs */
+    outputDir?: string;
+}
+export interface HealTarget {
+    specPath: string;
+    status: 'failed' | 'flaky';
+    /** Matching FlowDecision for context-enriched prompts */
+    decision?: FlowDecision;
+    reason?: string;
+}
+export interface HealResult {
+    targets: HealTarget[];
+    summary: PipelineSummary;
+    warnings: string[];
+}
+/**
+ * Resolve heal targets from one or more sources, in priority order:
+ * 1. Playwright JSON report (CI failures/flakes)
+ * 2. Stage 3 generated specs (newly written files that need runtime validation)
+ * 3. Explicit target list
+ */
+export declare function resolveHealTargets(testsRoot: string, options: {
+    playwrightReportPath?: string;
+    generatedSpecs?: GeneratedSpec[];
+    explicitTargets?: Array<{
+        specPath: string;
+        status: 'failed' | 'flaky';
+        reason?: string;
+    }>;
+}, decisions: FlowDecision[]): HealTarget[];
+export declare function runHealStage(testsRoot: string, targets: HealTarget[], config: HealConfig): Promise<HealResult>;
+/**
+ * Convenience: extract heal targets from a complete pipeline report + optional
+ * Playwright run results, then run the heal stage.
+ */
+export declare function healFromReport(testsRoot: string, report: FlowDecisionReport, options: {
+    playwrightReportPath?: string;
+    generatedSpecs?: GeneratedSpec[];
+    healConfig?: HealConfig;
+}): Promise<HealResult>;
+/**
+ * Write a heal summary section to the pipeline report markdown.
+ */
+export declare function renderHealMarkdown(result: HealResult): string;
+//# sourceMappingURL=stage4_heal.d.ts.map

package/dist/pipeline/stage4_heal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage4_heal.d.ts","sourceRoot":"","sources":["../../src/pipeline/stage4_heal.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAiB,eAAe,EAAC,MAAM,sBAAsB,CAAC;AAE1E,OAAO,KAAK,EAAC,YAAY,EAAE,kBAAkB,EAAC,MAAM,gCAAgC,CAAC;AACrF,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAC;AAE1D,MAAM,WAAW,UAAU;IACvB,8DAA8D;IAC9D,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IACL,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,eAAe,CAAC,EAAE,KAAK,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;CAC5F,EACD,SAAS,EAAE,YAAY,EAAE,GAC1B,UAAU,EAAE,CAqDd;AAsBD,wBAAsB,YAAY,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,EAAE,UAAU,GACnB,OAAO,CAAC,UAAU,CAAC,CAsCrB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAChC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE;IACL,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,UAAU,CAAC;CAC3B,GACF,OAAO,CAAC,UAAU,CAAC,CAWrB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CA8B7D"}

package/dist/pipeline/stage4_heal.js

@@ -0,0 +1,151 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveHealTargets = resolveHealTargets;
+exports.runHealStage = runHealStage;
+exports.healFromReport = healFromReport;
+exports.renderHealMarkdown = renderHealMarkdown;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const pipeline_js_1 = require("../agent/pipeline.js");
+const playwright_report_js_1 = require("../agent/playwright_report.js");
+/**
+ * Resolve heal targets from one or more sources, in priority order:
+ * 1. Playwright JSON report (CI failures/flakes)
+ * 2. Stage 3 generated specs (newly written files that need runtime validation)
+ * 3. Explicit target list
+ */
+function resolveHealTargets(testsRoot, options, decisions) {
+    const targets = [];
+    const seen = new Set();
+    const addTarget = (specPath, status, reason) => {
+        // Normalize to absolute path so relative (from Playwright report) and absolute
+        // (from generated specs) deduplicate correctly
+        let normalized = specPath.replace(/\\/g, '/');
+        if (!specPath.startsWith('/') && !(/^[A-Za-z]:[\\/]/).test(specPath)) {
+            normalized = (0, path_1.join)(testsRoot, specPath).replace(/\\/g, '/');
+        }
+        if (seen.has(normalized)) {
+            return;
+        }
+        seen.add(normalized);
+        // Try to match to a FlowDecision for context
+        const decision = findDecisionForSpec(normalized, decisions, testsRoot);
+        targets.push({ specPath: normalized, status, decision, reason });
+    };
+    // Source 1: Playwright JSON report
+    if (options.playwrightReportPath) {
+        const reportPath = (0, path_1.resolve)(options.playwrightReportPath);
+        if ((0, fs_1.existsSync)(reportPath)) {
+            const unstable = (0, playwright_report_js_1.extractPlaywrightUnstableSpecs)(reportPath, [testsRoot]);
+            for (const spec of unstable) {
+                addTarget(spec.specPath, spec.status, `Playwright report: failingTests=${spec.failingTests}, flakyTests=${spec.flakyTests}`);
+            }
+        }
+    }
+    // Source 2: Stage 3 generated specs (heal immediately after generation)
+    if (options.generatedSpecs) {
+        for (const gen of options.generatedSpecs) {
+            if (gen.written) {
+                addTarget(gen.specPath, 'failed', `Newly generated spec — needs runtime validation`);
+            }
+        }
+    }
+    // Source 3: Explicit targets
+    if (options.explicitTargets) {
+        for (const t of options.explicitTargets) {
+            addTarget(t.specPath, t.status, t.reason);
+        }
+    }
+    return targets;
+}
+/**
+ * Find the FlowDecision most relevant to a given spec path by matching
+ * targetSpec / newSpecPath / specPath suffix against decisions.
+ */
+function findDecisionForSpec(specPath, decisions, testsRoot) {
+    const normalizedRoot = testsRoot.replace(/\\/g, '/');
+    const relative = specPath.startsWith(normalizedRoot)
+        ? specPath.slice(normalizedRoot.length).replace(/^\//, '')
+        : specPath;
+    return decisions.find((d) => {
+        const target = (d.targetSpec || d.newSpecPath || '').replace(/\\/g, '/');
+        return target && (target === relative || target === specPath || relative.endsWith(target) || target.endsWith(relative));
+    });
+}
+async function runHealStage(testsRoot, targets, config) {
+    const warnings = [];
+    if (targets.length === 0) {
+        return {
+            targets,
+            summary: {
+                runner: 'package-native',
+                results: [],
+                warnings: ['No heal targets provided.'],
+            },
+            warnings,
+        };
+    }
+    const healTargets = targets.map((t) => ({
+        specPath: t.specPath,
+        status: t.status,
+        reason: t.reason,
+    }));
+    const pipelineConfig = {
+        enabled: true,
+        scenarios: 1,
+        outputDir: config.outputDir || 'specs/functional/ai-assisted',
+        heal: true,
+        dryRun: config.dryRun,
+        mcp: config.mcp ?? true,
+        mcpAllowFallback: config.mcpAllowFallback ?? false,
+        mcpOnly: config.mcpOnly ?? false,
+        mcpCommandTimeoutMs: config.mcpCommandTimeoutMs,
+        mcpRetries: config.mcpRetries ?? 1,
+    };
+    const summary = (0, pipeline_js_1.runTargetedSpecHeal)(testsRoot, healTargets, pipelineConfig);
+    warnings.push(...summary.warnings);
+    return { targets, summary, warnings };
+}
+/**
+ * Convenience: extract heal targets from a complete pipeline report + optional
+ * Playwright run results, then run the heal stage.
+ */
+async function healFromReport(testsRoot, report, options) {
+    const targets = resolveHealTargets(testsRoot, {
+        playwrightReportPath: options.playwrightReportPath,
+        generatedSpecs: options.generatedSpecs,
+    }, report.decisions);
+    return runHealStage(testsRoot, targets, options.healConfig || { mcp: true });
+}
+/**
+ * Write a heal summary section to the pipeline report markdown.
+ */
+function renderHealMarkdown(result) {
+    const lines = ['## Heal Results', ''];
+    const healedCount = result.summary.results.filter((r) => r.healStatus === 'success').length;
+    const failedCount = result.summary.results.filter((r) => r.healStatus === 'failed').length;
+    const skippedCount = result.summary.results.filter((r) => r.healStatus === 'skipped').length;
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    lines.push(`| Targets | ${result.targets.length} |`);
+    lines.push(`| Healed | ${healedCount} |`);
+    lines.push(`| Failed | ${failedCount} |`);
+    lines.push(`| Skipped | ${skippedCount} |`);
+    lines.push('');
+    for (const r of result.summary.results) {
+        const icon = r.healStatus === 'success' ? '✅' : r.healStatus === 'failed' ? '❌' : '⏭';
+        lines.push(`- ${icon} \`${r.flowId}\` — heal: ${r.healStatus || 'n/a'}`);
+        if (r.error) {
+            lines.push(`  - Error: ${r.error}`);
+        }
+    }
+    if (result.warnings.length > 0) {
+        lines.push('', '### Heal Warnings', '');
+        for (const w of result.warnings) {
+            lines.push(`- ${w}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/prompts/heal.d.ts

@@ -0,0 +1,19 @@
+import type { FlowDecision } from '../validation/output_schema.js';
+export interface HealPromptContext {
+    specPath: string;
+    status: 'failed' | 'flaky';
+    decision?: FlowDecision;
+    failureDetail?: string;
+}
+/**
+ * Builds a route-family-aware heal prompt for the playwright-test-healer agent.
+ * Enriches the base healer constraints with flow context so the agent understands
+ * what the test is supposed to verify, reducing hallucination during selector repair.
+ */
+export declare function buildHealPrompt(ctx: HealPromptContext): string;
+/**
+ * Builds a minimal quality-fix prompt for spec files that fail content validation
+ * (e.g. contain test.describe, test.only, wrong imports).
+ */
+export declare function buildQualityFixPrompt(specPath: string, qualityIssues: string[]): string;
+//# sourceMappingURL=heal.d.ts.map

package/dist/prompts/heal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heal.d.ts","sourceRoot":"","sources":["../../src/prompts/heal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gCAAgC,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC3B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CA2C9D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,CAgBvF"}

package/dist/prompts/heal.js

@@ -0,0 +1,73 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHealPrompt = buildHealPrompt;
+exports.buildQualityFixPrompt = buildQualityFixPrompt;
+/**
+ * Builds a route-family-aware heal prompt for the playwright-test-healer agent.
+ * Enriches the base healer constraints with flow context so the agent understands
+ * what the test is supposed to verify, reducing hallucination during selector repair.
+ */
+function buildHealPrompt(ctx) {
+    const flowBlock = ctx.decision
+        ? [
+            '',
+            'FLOW CONTEXT (use to understand test intent — do not change test objectives):',
+            `  Flow: ${ctx.decision.flowName}`,
+            `  Route Family: ${ctx.decision.routeFamily}${ctx.decision.featureId ? ` / ${ctx.decision.featureId}` : ''}`,
+            `  Route: ${ctx.decision.specificRoute || '(family-level)'}`,
+            `  User Actions: ${ctx.decision.userActions.join('; ') || 'not specified'}`,
+            `  Evidence: ${ctx.decision.evidence}`,
+        ].join('\n')
+        : '';
+    const statusNote = ctx.status === 'flaky'
+        ? 'This test is FLAKY (passes sometimes, fails other times). Look for race conditions, missing waits, or order-dependent state.'
+        : 'This test is FAILING consistently. The selector, URL, or API call is likely broken.';
+    const failureBlock = ctx.failureDetail
+        ? `\nFailure detail:\n${ctx.failureDetail}`
+        : '';
+    return [
+        'Heal this specific Playwright test file and keep edits minimal.',
+        '',
+        `Target test file: ${ctx.specPath}`,
+        `Status: ${ctx.status.toUpperCase()} — ${statusNote}`,
+        failureBlock,
+        flowBlock,
+        '',
+        'Healing constraints (must follow):',
+        '- Import ONLY from "@mattermost/playwright-lib". Do not use "@playwright/test" directly.',
+        '- Do not use test.describe or test.only.',
+        '- Keep a single tag string matching the route family (e.g. "@channels", "@scheduled_posts").',
+        '- Use only existing Mattermost Playwright fixture and page-object APIs.',
+        '- Do NOT invent new pw.* clients or page object methods that do not exist.',
+        '- Avoid brittle class selectors (.backstage-navbar, .admin-console__wrapper, .left-panel, .panel-card).',
+        '- Prefer stable assertions using URL patterns, data-testid attributes, ARIA roles, and page-object methods.',
+        '- For flaky tests: add explicit waits (waitFor, expect().toBeVisible()) before interactions.',
+        '- Keep the test intent and scenario unchanged — only fix what is broken.',
+        '- If behavior is genuinely broken server-side, mark test.fixme with a clear comment explaining why.',
+        '',
+        'Run and fix this test until it compiles and passes, or mark test.fixme when the behavior is truly broken.',
+    ].filter((line) => line !== null).join('\n');
+}
+/**
+ * Builds a minimal quality-fix prompt for spec files that fail content validation
+ * (e.g. contain test.describe, test.only, wrong imports).
+ */
+function buildQualityFixPrompt(specPath, qualityIssues) {
+    return [
+        'Fix quality issues in this Playwright spec file. Make minimal edits only.',
+        '',
+        `Target file: ${specPath}`,
+        '',
+        'Issues to fix:',
+        ...qualityIssues.map((issue) => `  - ${issue}`),
+        '',
+        'Rules:',
+        '- Import only from "@mattermost/playwright-lib".',
+        '- Remove test.describe wrappers (flatten to top-level test() calls).',
+        '- Remove test.only calls.',
+        '- Ensure each test has exactly one tag string.',
+        '- Do not change test logic — only fix structural quality issues.',
+    ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yasserkhanorg/e2e-agents",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pluggable LLM provider library for AI-powered test automation. Use Claude, Ollama, or your own LLM. Integrate with Playwright, Jest, or any test framework. MCP server for test agents, cost tracking, and hybrid provider mode.",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",