@yasserkhanorg/e2e-agents 1.2.2 → 1.3.0

package/dist/esm/qa-agent/phase2/tools.js

@@ -0,0 +1,288 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+// ---------------------------------------------------------------------------
+// Tool definitions (Anthropic tool_use schema)
+// ---------------------------------------------------------------------------
+export const TOOL_DEFINITIONS = [
+    {
+        name: 'navigate',
+        description: 'Navigate to a URL. Use absolute paths starting with / or full URLs.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'URL or path to navigate to' },
+            },
+            required: ['url'],
+        },
+    },
+    {
+        name: 'click',
+        description: 'Click an element by its accessibility ref (e.g. @e4).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                ref: { type: 'string', description: 'Accessibility ref like @e4' },
+            },
+            required: ['ref'],
+        },
+    },
+    {
+        name: 'fill',
+        description: 'Clear a field and type new text into it.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                ref: { type: 'string', description: 'Accessibility ref of the input field' },
+                value: { type: 'string', description: 'Text to type' },
+            },
+            required: ['ref', 'value'],
+        },
+    },
+    {
+        name: 'press_key',
+        description: 'Press a keyboard key (e.g. Enter, Escape, Tab).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                key: { type: 'string', description: 'Key name (Enter, Escape, Tab, etc.)' },
+            },
+            required: ['key'],
+        },
+    },
+    {
+        name: 'scroll',
+        description: 'Scroll the page or a specific element up or down.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                direction: { type: 'string', enum: ['up', 'down'] },
+                ref: { type: 'string', description: 'Optional element ref to scroll within' },
+            },
+            required: ['direction'],
+        },
+    },
+    {
+        name: 'go_back',
+        description: 'Go back to the previous page.',
+        input_schema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'take_screenshot',
+        description: 'Take an annotated screenshot for evidence or vision analysis. Use sparingly (costs tokens).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                label: { type: 'string', description: 'Short label for the screenshot (used in filename)' },
+            },
+            required: ['label'],
+        },
+    },
+    {
+        name: 'get_text',
+        description: 'Read the text content of a specific element.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                ref: { type: 'string', description: 'Accessibility ref' },
+            },
+            required: ['ref'],
+        },
+    },
+    {
+        name: 'report_finding',
+        description: 'Report a bug, visual issue, UX problem, or gap you discovered. Always include current URL and repro steps.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                type: { type: 'string', enum: ['bug', 'visual-regression', 'ux-issue', 'gap'] },
+                severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'] },
+                summary: { type: 'string', description: 'What you found' },
+                repro_steps: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Steps to reproduce',
+                },
+            },
+            required: ['type', 'severity', 'summary', 'repro_steps'],
+        },
+    },
+    {
+        name: 'mark_flow_done',
+        description: 'Mark the current flow as verified/explored. Call when you are done testing a flow.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                flow_id: { type: 'string', description: 'ID of the flow being marked done' },
+                status: { type: 'string', enum: ['verified-ok', 'has-issues'] },
+            },
+            required: ['flow_id', 'status'],
+        },
+    },
+    {
+        name: 'switch_user',
+        description: 'Log out and log in as a different user role.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                role: { type: 'string', description: 'Role of the user to switch to (e.g. admin, regular, guest)' },
+            },
+            required: ['role'],
+        },
+    },
+];
+export function executeTool(ctx, name, input) {
+    switch (name) {
+        case 'navigate': {
+            const url = String(input.url || '');
+            const fullUrl = url.startsWith('http') ? url : `${ctx.baseUrl}${url}`;
+            // Security: restrict navigation to the configured baseUrl domain
+            if (!isAllowedUrl(fullUrl, ctx.baseUrl)) {
+                return { output: `Blocked: navigation to "${fullUrl}" is outside the allowed domain (${ctx.baseUrl}).` };
+            }
+            const output = ctx.browser.open(fullUrl);
+            ctx.currentUrl = ctx.browser.getUrl();
+            return { output: output || `Navigated to ${ctx.currentUrl}`, navigated: true };
+        }
+        case 'click': {
+            const output = ctx.browser.click(String(input.ref));
+            return { output: output || `Clicked ${input.ref}` };
+        }
+        case 'fill': {
+            const ref = String(input.ref);
+            const value = String(input.value);
+            const output = ctx.browser.fill(ref, value);
+            // Redact value for password-like fields to avoid leaking credentials to LLM
+            const isSensitive = /password|passwd|pwd|secret|token/i.test(ref);
+            const displayValue = isSensitive ? '[REDACTED]' : `"${value}"`;
+            return { output: output || `Filled ${ref} with ${displayValue}` };
+        }
+        case 'press_key': {
+            const output = ctx.browser.press(String(input.key));
+            return { output: output || `Pressed ${input.key}` };
+        }
+        case 'scroll': {
+            const rawDir = String(input.direction);
+            if (rawDir !== 'up' && rawDir !== 'down') {
+                return { output: `Invalid scroll direction "${rawDir}". Must be "up" or "down".` };
+            }
+            const ref = input.ref ? String(input.ref) : undefined;
+            const output = ctx.browser.scroll(rawDir, ref);
+            return { output: output || `Scrolled ${rawDir}` };
+        }
+        case 'go_back': {
+            const output = ctx.browser.back();
+            ctx.currentUrl = ctx.browser.getUrl();
+            return { output: output || `Went back to ${ctx.currentUrl}` };
+        }
+        case 'take_screenshot': {
+            ctx.screenshotCounter++;
+            const label = String(input.label || 'evidence').replace(/[^a-zA-Z0-9_-]/g, '_');
+            const filename = `${String(ctx.screenshotCounter).padStart(3, '0')}-${label}.png`;
+            const path = `${ctx.screenshotDir}/${filename}`;
+            ctx.browser.screenshot(path);
+            return { output: `Screenshot saved: ${path}` };
+        }
+        case 'get_text': {
+            const text = ctx.browser.getText(String(input.ref));
+            return { output: text || '(empty)' };
+        }
+        case 'report_finding': {
+            const VALID_TYPES = new Set(['bug', 'visual-regression', 'ux-issue', 'gap']);
+            const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info']);
+            const rawType = String(input.type);
+            const rawSeverity = String(input.severity);
+            if (!VALID_TYPES.has(rawType)) {
+                return { output: `Invalid finding type "${rawType}". Must be one of: ${[...VALID_TYPES].join(', ')}.` };
+            }
+            if (!VALID_SEVERITIES.has(rawSeverity)) {
+                return { output: `Invalid severity "${rawSeverity}". Must be one of: ${[...VALID_SEVERITIES].join(', ')}.` };
+            }
+            if (!Array.isArray(input.repro_steps)) {
+                return { output: `Invalid repro_steps: expected an array of strings.` };
+            }
+            const finding = {
+                id: `f-${crypto.randomUUID()}`,
+                type: rawType,
+                severity: rawSeverity,
+                summary: String(input.summary),
+                flow: ctx.currentFlow,
+                evidence: {
+                    url: ctx.currentUrl,
+                    reproSteps: input.repro_steps.map(String),
+                },
+                timestamp: Date.now(),
+            };
+            return { output: `Finding recorded: [${finding.severity}] ${finding.summary}`, finding };
+        }
+        case 'mark_flow_done': {
+            const flowId = String(input.flow_id);
+            const rawStatus = String(input.status);
+            if (rawStatus !== 'verified-ok' && rawStatus !== 'has-issues') {
+                return { output: `Invalid status "${rawStatus}". Must be "verified-ok" or "has-issues".` };
+            }
+            return {
+                output: `Flow "${flowId}" marked as ${rawStatus}`,
+                flowDone: { flowId, status: rawStatus },
+            };
+        }
+        case 'switch_user': {
+            const role = String(input.role);
+            const user = ctx.users?.find((u) => u.role === role);
+            if (!user) {
+                return { output: `No user configured for role "${role}". Available: ${(ctx.users || []).map((u) => u.role).join(', ')}` };
+            }
+            // Log out first, then log in as new user
+            try {
+                ctx.browser.open(`${ctx.baseUrl}/logout`);
+            }
+            catch {
+                // May not be logged in
+            }
+            ctx.browser.open(`${ctx.baseUrl}/login`);
+            // Use snapshot to find login fields, then fill
+            const snap = ctx.browser.snapshot();
+            const emailRef = extractRef(snap, 'email') || extractRef(snap, 'username') || '@e1';
+            const passRef = extractRef(snap, 'password') || '@e2';
+            ctx.browser.fill(emailRef, user.username);
+            ctx.browser.fill(passRef, user.password);
+            ctx.browser.press('Enter');
+            ctx.currentUrl = ctx.browser.getUrl();
+            // Redact credentials from LLM context — only expose role
+            return { output: `Switched to user role: ${user.role}` };
+        }
+        default:
+            return { output: `Unknown tool: ${name}` };
+    }
+}
+function isAllowedUrl(url, baseUrl) {
+    // Block dangerous schemes
+    const scheme = url.split(':')[0]?.toLowerCase();
+    if (scheme && !['http', 'https'].includes(scheme))
+        return false;
+    // Parse both URLs and compare origins (hostname + port)
+    try {
+        const target = new URL(url);
+        const base = new URL(baseUrl);
+        return target.origin === base.origin;
+    }
+    catch {
+        // If URL parsing fails, only allow relative paths (already prefixed with baseUrl)
+        return url.startsWith(baseUrl);
+    }
+}
+function extractRef(snapshot, fieldHint) {
+    // Look for lines containing the hint and extract the @eN ref
+    const lines = snapshot.split('\n');
+    for (const line of lines) {
+        if (line.toLowerCase().includes(fieldHint)) {
+            const match = line.match(/@e\d+/);
+            if (match)
+                return match[0];
+        }
+    }
+    return undefined;
+}

package/dist/esm/qa-agent/phase2/vision.js

@@ -0,0 +1,75 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { readFileSync } from 'fs';
+import { LLMProviderFactory } from '../../provider_factory.js';
+const VALID_TYPES = new Set(['bug', 'visual-regression', 'ux-issue', 'gap']);
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info']);
+const VISION_PROMPT = `You are a QA engineer analyzing a screenshot of a web application.
+Look for these categories of issues:
+
+1. **Layout issues**: overlapping elements, misaligned content, broken grid, elements outside viewport
+2. **Visual issues**: truncated text, missing icons/images, broken styling, inconsistent spacing
+3. **UX issues**: unclear button labels, confusing navigation, missing feedback states, poor contrast
+4. **State issues**: loading spinners stuck, empty states without messaging, stale data indicators
+5. **Error states**: visible error messages, 404/500 pages, broken components
+
+For each issue found, respond with a JSON array of objects:
+[
+  {
+    "type": "bug" | "visual-regression" | "ux-issue",
+    "severity": "critical" | "high" | "medium" | "low" | "info",
+    "summary": "description of the issue"
+  }
+]
+
+If no issues are found, respond with an empty array: []
+
+Only report clear, actionable issues. Do not speculate about functionality you cannot see.`;
+export async function analyzeScreenshot(screenshotPath, url, flow) {
+    const provider = await LLMProviderFactory.createFromEnv();
+    if (!provider.capabilities.vision || !provider.analyzeImage) {
+        return [];
+    }
+    let imageData;
+    try {
+        imageData = readFileSync(screenshotPath).toString('base64');
+    }
+    catch {
+        return [];
+    }
+    const response = await provider.analyzeImage([{ base64: imageData, mediaType: 'image/png' }], VISION_PROMPT, { maxTokens: 2000, temperature: 0.1 });
+    return parseVisionResponse(response.text, url, flow, screenshotPath);
+}
+function parseVisionResponse(text, url, flow, screenshotPath) {
+    // Extract JSON array from response
+    const jsonMatch = text.match(/\[[\s\S]*\]/);
+    if (!jsonMatch)
+        return [];
+    try {
+        const items = JSON.parse(jsonMatch[0]);
+        if (!Array.isArray(items))
+            return [];
+        return items
+            .filter((item) => {
+            const t = String(item.type || '');
+            const s = String(item.severity || '');
+            return VALID_TYPES.has(t) && VALID_SEVERITIES.has(s);
+        })
+            .map((item) => ({
+            id: `v-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`,
+            type: String(item.type),
+            severity: String(item.severity),
+            summary: String(item.summary || 'Visual issue detected'),
+            flow,
+            evidence: {
+                url,
+                screenshotPath,
+                reproSteps: ['Captured via automated vision analysis'],
+            },
+            timestamp: Date.now(),
+        }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/esm/qa-agent/phase3/feedback.js

@@ -0,0 +1,34 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { spawnSync } from 'child_process';
+import { logger } from '../../logger.js';
+import { safeEnv } from '../safe_env.js';
+export function submitFeedback(config) {
+    const args = ['e2e-ai-agents', 'feedback'];
+    if (config.testsRoot) {
+        args.push('--tests-root', config.testsRoot);
+    }
+    logger.info('Submitting feedback to calibration system');
+    const result = spawnSync('npx', args, {
+        cwd: config.testsRoot || process.cwd(),
+        encoding: 'utf-8',
+        timeout: 30000,
+        env: safeEnv(),
+    });
+    if (result.error) {
+        logger.warn('Feedback submission spawn failed', {
+            error: result.error.message,
+        });
+    }
+    else if (result.signal) {
+        logger.warn('Feedback submission killed by signal', {
+            signal: result.signal,
+        });
+    }
+    else if (result.status !== 0) {
+        logger.warn('Feedback submission failed', {
+            status: result.status,
+            stderr: (result.stderr || '').slice(0, 200),
+        });
+    }
+}

package/dist/esm/qa-agent/phase3/reporter.js

@@ -0,0 +1,118 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+export function generateReport(config, phase1, phase2, verdict, generatedSpecs) {
+    const outputDir = config.outputDir || '.e2e-ai-agents';
+    mkdirSync(outputDir, { recursive: true });
+    const reportPath = join(outputDir, 'qa-report.json');
+    const summaryPath = join(outputDir, 'qa-summary.md');
+    const report = {
+        schemaVersion: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        mode: config.mode,
+        config: {
+            baseUrl: config.baseUrl,
+            timeLimitMinutes: config.timeLimitMinutes,
+            budgetUSD: config.budgetUSD,
+        },
+        phase1,
+        phase2,
+        phase3: {
+            reportPath,
+            summaryPath,
+            verdict,
+            generatedSpecs,
+        },
+        verdict,
+    };
+    try {
+        writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`Failed to write report to ${reportPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const markdown = renderMarkdown(report);
+    try {
+        writeFileSync(summaryPath, markdown, 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`Failed to write summary to ${summaryPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        reportPath,
+        summaryPath,
+        verdict,
+        generatedSpecs,
+    };
+}
+function renderMarkdown(report) {
+    const v = report.verdict;
+    const badge = v.decision === 'go' ? '✅ GO' : v.decision === 'no-go' ? '❌ NO-GO' : '⚠️ CONDITIONAL';
+    const lines = [
+        `# QA Agent Report — ${badge}`,
+        '',
+        `**Mode:** ${report.mode}`,
+        `**Base URL:** ${report.config.baseUrl}`,
+        `**Generated:** ${report.generatedAt}`,
+        '',
+        `## Verdict`,
+        '',
+        `**Decision:** ${badge}`,
+        `**Reason:** ${v.reason}`,
+        '',
+        `| Severity | Count |`,
+        `|----------|-------|`,
+        `| Critical | ${v.criticalFindings} |`,
+        `| High | ${v.highFindings} |`,
+        `| Medium | ${v.mediumFindings} |`,
+        `| Low | ${v.lowFindings} |`,
+        '',
+    ];
+    // Phase 1 summary
+    const specTotal = report.phase1.specResults.length;
+    const specPassed = report.phase1.specResults.reduce((s, r) => s + r.passed, 0);
+    const specFailed = report.phase1.specResults.reduce((s, r) => s + r.failed, 0);
+    lines.push(`## Phase 1: Scripted Tests`, '', `- Flows identified: ${report.phase1.flows.length}`, `- Specs run: ${specTotal} (${specPassed} passed, ${specFailed} failed)`, '');
+    // Phase 2 summary
+    lines.push(`## Phase 2: Autonomous Exploration`, '', `- Flows explored: ${report.phase2.flowsExplored.length}`, `- Actions taken: ${report.phase2.actionsCount}`, `- Duration: ${Math.round(report.phase2.durationMs / 1000)}s`, `- Cost: $${report.phase2.costUSD.toFixed(4)}`, `- Tokens: ${report.phase2.tokensUsed}`, '');
+    // Findings
+    if (report.phase2.findings.length > 0) {
+        lines.push(`## Findings`, '');
+        for (const f of report.phase2.findings) {
+            lines.push(`### [${f.severity.toUpperCase()}] ${f.summary}`);
+            lines.push('');
+            lines.push(`- **Type:** ${f.type}`);
+            lines.push(`- **Flow:** ${f.flow}`);
+            lines.push(`- **URL:** ${f.evidence.url}`);
+            if (f.evidence.screenshotPath) {
+                lines.push(`- **Screenshot:** ${f.evidence.screenshotPath}`);
+            }
+            if (f.evidence.reproSteps.length > 0) {
+                lines.push('- **Repro steps:**');
+                for (const step of f.evidence.reproSteps) {
+                    lines.push(`  1. ${step}`);
+                }
+            }
+            lines.push('');
+        }
+    }
+    // Flow sign-offs
+    lines.push(`## Flow Sign-offs`, '');
+    lines.push(`| Flow | Status | Findings |`);
+    lines.push(`|------|--------|----------|`);
+    for (const s of v.flowSignoffs) {
+        const statusIcon = s.status === 'passed' ? '✅' : s.status === 'failed' ? '❌' : '⏭️';
+        lines.push(`| ${s.flowName} | ${statusIcon} ${s.status} | ${s.findings.length} |`);
+    }
+    lines.push('');
+    // Generated specs
+    if (report.phase3.generatedSpecs.length > 0) {
+        lines.push(`## Generated Specs`, '');
+        for (const spec of report.phase3.generatedSpecs) {
+            lines.push(`- ${spec}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/esm/qa-agent/phase3/spec_generator.js

@@ -0,0 +1,62 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { spawnSync } from 'child_process';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { logger } from '../../logger.js';
+import { safeEnv } from '../safe_env.js';
+export function generateSpecsForFindings(findings, config) {
+    // Only generate specs for bugs and gaps (not visual/UX issues)
+    const actionable = findings.filter((f) => f.type === 'bug' || f.type === 'gap');
+    if (actionable.length === 0) {
+        logger.info('No actionable findings for spec generation');
+        return [];
+    }
+    const scenarios = actionable.map((f) => ({
+        title: `Verify: ${f.summary}`,
+        flow: f.flow,
+        steps: f.evidence.reproSteps,
+        expected: `The issue "${f.summary}" should not occur`,
+        priority: f.severity === 'critical' || f.severity === 'high' ? 'P0' : 'P1',
+    }));
+    // Write scenarios to a temp file
+    const outputDir = config.outputDir || '.e2e-ai-agents';
+    mkdirSync(outputDir, { recursive: true });
+    const scenariosPath = join(outputDir, 'qa-findings-scenarios.json');
+    writeFileSync(scenariosPath, JSON.stringify(scenarios, null, 2), 'utf-8');
+    // Call e2e-ai-agents generate with the scenarios
+    const args = [
+        'e2e-ai-agents', 'generate',
+        '--scenarios', scenariosPath,
+    ];
+    if (config.testsRoot) {
+        args.push('--tests-root', config.testsRoot);
+    }
+    if (config.baseUrl) {
+        args.push('--pipeline-base-url', config.baseUrl);
+    }
+    logger.info('Generating specs for findings', { count: scenarios.length });
+    const result = spawnSync('npx', args, {
+        cwd: config.testsRoot || process.cwd(),
+        encoding: 'utf-8',
+        timeout: 300000,
+        maxBuffer: 4 * 1024 * 1024,
+        env: safeEnv(),
+    });
+    if (result.status !== 0) {
+        logger.warn('Spec generation exited with non-zero', {
+            status: result.status,
+            stderr: (result.stderr || '').slice(0, 500),
+        });
+    }
+    // Parse generated spec paths from output
+    const generatedPaths = [];
+    const lines = (result.stdout || '').split('\n');
+    for (const line of lines) {
+        const match = line.match(/generated.*?:\s*(.+\.spec\.ts)/i);
+        if (match) {
+            generatedPaths.push(match[1].trim());
+        }
+    }
+    return generatedPaths;
+}

package/dist/esm/qa-agent/phase3/verdict.js

@@ -0,0 +1,66 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+export function computeVerdict(phase1, phase2) {
+    const findings = phase2.findings;
+    const critical = findings.filter((f) => f.severity === 'critical').length;
+    const high = findings.filter((f) => f.severity === 'high').length;
+    const medium = findings.filter((f) => f.severity === 'medium').length;
+    const low = findings.filter((f) => f.severity === 'low' || f.severity === 'info').length;
+    // Flow sign-offs
+    const flowSignoffs = buildFlowSignoffs(phase1.flows, phase2);
+    // Decision logic
+    let decision;
+    let reason;
+    if (critical > 0) {
+        decision = 'no-go';
+        reason = `${critical} critical finding(s) — must fix before release.`;
+    }
+    else if (high > 0) {
+        decision = 'no-go';
+        reason = `${high} high-severity finding(s) — requires triage before release.`;
+    }
+    else if (medium > 0) {
+        decision = 'conditional';
+        reason = `${medium} medium-severity finding(s) — review and decide if acceptable.`;
+    }
+    else {
+        decision = 'go';
+        reason = findings.length === 0
+            ? 'No issues found across all tested flows.'
+            : `Only low/info findings (${low}). Safe to proceed.`;
+    }
+    // Check for untested flows (P0/P1 not tested → downgrade to conditional)
+    const untestedP0P1 = flowSignoffs.filter((s) => s.status === 'not-tested' && phase1.flows.find((f) => f.id === s.flowId && (f.priority === 'P0' || f.priority === 'P1')));
+    if (untestedP0P1.length > 0 && decision === 'go') {
+        decision = 'conditional';
+        reason += ` ${untestedP0P1.length} P0/P1 flow(s) were not tested.`;
+    }
+    // Check Phase 1 spec failures
+    const specFailures = phase1.specResults.reduce((sum, r) => sum + r.failed, 0);
+    if (specFailures > 0 && decision === 'go') {
+        decision = 'conditional';
+        reason += ` ${specFailures} existing spec(s) failed in Phase 1.`;
+    }
+    return {
+        decision,
+        reason,
+        flowSignoffs,
+        criticalFindings: critical,
+        highFindings: high,
+        mediumFindings: medium,
+        lowFindings: low,
+    };
+}
+function buildFlowSignoffs(flows, phase2) {
+    return flows.map((flow) => {
+        const explored = phase2.flowsExplored.includes(flow.id);
+        const flowFindings = phase2.findings.filter((f) => f.flow === flow.id);
+        const hasIssues = flowFindings.some((f) => f.type === 'bug' || f.severity === 'critical' || f.severity === 'high');
+        return {
+            flowId: flow.id,
+            flowName: flow.name,
+            status: explored ? (hasIssues ? 'failed' : 'passed') : 'not-tested',
+            findings: flowFindings.map((f) => f.id),
+        };
+    });
+}

package/dist/esm/qa-agent/safe_env.js

@@ -0,0 +1,23 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/** Build a minimal env for child processes — only forward what's needed. */
+export function safeEnv(extra) {
+    const env = {
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        NODE_PATH: process.env.NODE_PATH,
+        ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
+        OPENAI_API_KEY: process.env.OPENAI_API_KEY,
+        LLM_PROVIDER: process.env.LLM_PROVIDER,
+        LOG_LEVEL: process.env.LOG_LEVEL,
+        // Node needs LANG/LC_ALL for proper string handling
+        LANG: process.env.LANG,
+        // npm/npx need these
+        npm_config_prefix: process.env.npm_config_prefix,
+        NVM_DIR: process.env.NVM_DIR,
+        NVM_BIN: process.env.NVM_BIN,
+    };
+    if (extra)
+        Object.assign(env, extra);
+    return env;
+}

package/dist/esm/qa-agent/types.js

@@ -0,0 +1,3 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+export {};