@yasserkhanorg/e2e-agents 0.9.0 → 0.11.0

package/dist/esm/cli/commands/finalize.js

@@ -0,0 +1,38 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { resolveConfig } from '../../agent/config.js';
+import { finalizeGeneratedTests } from '../../agent/handoff.js';
+export function runFinalizeCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for finalize-generated-tests command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'gap',
+        llmProvider: args.llmProvider,
+    });
+    const result = finalizeGeneratedTests({
+        appPath: config.path,
+        testsRoot: config.testsRoot || config.path,
+        branch: args.branch,
+        commitMessage: args.commitMessage,
+        createPr: args.createPr,
+        prTitle: args.prTitle,
+        prBody: args.prBody,
+        baseBranch: args.prBase,
+        dryRun: args.dryRun,
+    });
+    console.log(`Finalize repo root: ${result.repoRoot}`);
+    console.log(`Finalize branch: ${result.branch}`);
+    console.log(`Finalize staged paths: ${result.stagedPaths.join(', ') || 'none'}`);
+    console.log(`Finalize commit: ${result.committed ? 'created' : 'skipped'}`);
+    if (result.commitSha) {
+        console.log(`Finalize commit sha: ${result.commitSha}`);
+    }
+    if (result.prUrl) {
+        console.log(`Finalize PR: ${result.prUrl}`);
+    }
+}

package/dist/esm/cli/commands/generate.js

@@ -0,0 +1,105 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { LLMProviderFactory } from '../../provider_factory.js';
+import { runAgenticGeneration } from '../../agentic/runner.js';
+import { loadOrBuildApiSurface } from '../../knowledge/api_surface.js';
+export async function runGenerateCommand(args, config) {
+    const reportRoot = config.testsRoot || config.path;
+    // Load scenarios from --scenarios flag or plan-report.json
+    let scenarios = [];
+    if (args.generateScenarios) {
+        let raw;
+        if (existsSync(args.generateScenarios)) {
+            raw = JSON.parse(readFileSync(args.generateScenarios, 'utf-8'));
+        }
+        else {
+            raw = JSON.parse(args.generateScenarios);
+        }
+        if (!Array.isArray(raw)) {
+            console.error('--scenarios must be a JSON array of ScenarioInput objects.');
+            process.exit(1);
+        }
+        for (const item of raw) {
+            if (!item.id || !item.name || !Array.isArray(item.scenarios) || !item.routeFamily || !item.priority) {
+                console.error(`Invalid scenario: each must have id, name, scenarios[], routeFamily, priority.`);
+                process.exit(1);
+            }
+        }
+        scenarios = raw;
+    }
+    else {
+        // Try plan.json first (written by plan/suggest command), then plan-report.json (legacy)
+        const planJsonPath = join(reportRoot, '.e2e-ai-agents', 'plan.json');
+        const planReportPath = join(reportRoot, '.e2e-ai-agents', 'plan-report.json');
+        const resolvedPlanPath = existsSync(planJsonPath) ? planJsonPath : existsSync(planReportPath) ? planReportPath : null;
+        if (!resolvedPlanPath) {
+            console.error('No plan report found. Run `plan` first or pass --scenarios.');
+            process.exit(1);
+        }
+        const planReport = JSON.parse(readFileSync(resolvedPlanPath, 'utf-8'));
+        scenarios = (planReport.gapDetails || []).map((gap) => ({
+            id: gap.id,
+            name: gap.id,
+            scenarios: gap.missingScenarios || gap.reasons || ['Verify core user flow'],
+            routeFamily: gap.id.split('.')[0] || gap.id,
+            priority: 'P1',
+        }));
+    }
+    if (scenarios.length === 0) {
+        console.log('No scenarios to generate tests for.');
+        return;
+    }
+    let apiSurface;
+    try {
+        apiSurface = loadOrBuildApiSurface(reportRoot, config.apiSurface);
+    }
+    catch {
+        console.warn('Could not load API surface catalog. Generation will use generic selectors.');
+    }
+    const provider = await LLMProviderFactory.createFromEnv();
+    console.log(`Generating tests for ${scenarios.length} scenario(s)...`);
+    const summary = await runAgenticGeneration({
+        scenarios,
+        config: {
+            maxAttempts: args.maxAttempts || 3,
+            project: args.pipelineProject || 'chrome',
+            baseUrl: args.pipelineBaseUrl,
+            testTimeoutMs: 120000,
+            testsRoot: reportRoot,
+            dryRun: args.dryRun,
+        },
+        provider,
+        apiSurface,
+    });
+    console.log(`\nAgentic Generation Summary:`);
+    console.log(`  Generated: ${summary.totalGenerated}`);
+    console.log(`  Passed:    ${summary.totalPassed}`);
+    console.log(`  Failed:    ${summary.totalFailed}`);
+    console.log(`  Attempts:  ${summary.totalAttempts}`);
+    console.log(`  Duration:  ${(summary.durationMs / 1000).toFixed(1)}s`);
+    for (const result of summary.results) {
+        const icon = result.status === 'passed' ? 'PASS' : result.status === 'skipped' ? 'SKIP' : 'FAIL';
+        console.log(`  [${icon}] ${result.scenarioSource} (${result.attempts} attempts)`);
+        if (result.status === 'passed' || result.status === 'skipped') {
+            console.log(`     ${result.specPath}`);
+        }
+    }
+    if (summary.warnings.length > 0) {
+        console.log(`\nWarnings:`);
+        for (const w of summary.warnings) {
+            console.warn(`  - ${w}`);
+        }
+    }
+    const summaryDir = join(reportRoot, '.e2e-ai-agents');
+    if (!existsSync(summaryDir)) {
+        mkdirSync(summaryDir, { recursive: true });
+    }
+    const summaryPath = join(summaryDir, 'agentic-summary.json');
+    writeFileSync(summaryPath, JSON.stringify(summary, null, 2), 'utf-8');
+    console.log(`\nReport: ${summaryPath}`);
+    if (summary.totalFailed > 0) {
+        process.exit(1);
+    }
+}

package/dist/esm/cli/commands/heal.js

@@ -0,0 +1,57 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { resolveConfig } from '../../agent/config.js';
+import { runTargetedSpecHeal } from '../../agent/pipeline.js';
+import { extractPlaywrightUnstableSpecs } from '../../agent/playwright_report.js';
+export function runHealCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for heal command');
+        process.exit(1);
+    }
+    if (!args.traceabilityReportPath) {
+        console.error('Error: --traceability-report <path> is required for heal command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'gap',
+        framework: args.framework,
+        pipeline: {
+            enabled: true,
+            scenarios: args.pipelineScenarios,
+            outputDir: args.pipelineOutput,
+            baseUrl: args.pipelineBaseUrl,
+            browser: args.pipelineBrowser,
+            headless: args.pipelineHeadless,
+            project: args.pipelineProject,
+            parallel: args.pipelineParallel,
+            dryRun: args.pipelineDryRun,
+            mcp: args.pipelineMcp,
+            mcpAllowFallback: args.pipelineMcpAllowFallback,
+            mcpOnly: args.pipelineMcpOnly,
+        },
+        llmProvider: args.llmProvider,
+    });
+    const reportRoot = config.testsRoot || config.path;
+    const unstableSpecs = extractPlaywrightUnstableSpecs(args.traceabilityReportPath, [reportRoot, config.path]);
+    if (unstableSpecs.length === 0) {
+        console.log('Heal targeted unstable specs: 0');
+        return;
+    }
+    const targetedSummary = runTargetedSpecHeal(reportRoot, unstableSpecs.map((spec) => ({
+        specPath: spec.specPath,
+        status: spec.status,
+        reason: `Playwright report: failingTests=${spec.failingTests}, flakyTests=${spec.flakyTests}`,
+    })), {
+        ...config.pipeline,
+        enabled: true,
+        heal: true,
+    });
+    const healedCount = targetedSummary.results.filter((result) => result.healStatus === 'success').length;
+    console.log(`Heal targeted unstable specs: ${unstableSpecs.length} (healed=${healedCount})`);
+    if (targetedSummary.warnings.length > 0) {
+        console.log(`Heal warnings: ${targetedSummary.warnings.join(' | ')}`);
+    }
+}

package/dist/esm/cli/commands/impact.js

@@ -0,0 +1,23 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { getChangedFiles } from '../../agent/git.js';
+import { analyzeImpact as analyzeImpactV2 } from '../../engine/impact_engine.js';
+export function runImpactCommand(args, config) {
+    const reportRoot = config.testsRoot || config.path;
+    const gitResult = getChangedFiles(config.path, config.git.since, { includeUncommitted: config.git.includeUncommitted });
+    const impactResult = analyzeImpactV2(gitResult.files, {
+        testsRoot: reportRoot,
+        routeFamilies: config.routeFamilies,
+    });
+    console.log(`Impact: ${impactResult.changedFiles.length} changed files → ${impactResult.impactedFeatures.length} features impacted`);
+    console.log(`Unbound files: ${impactResult.unboundFiles.length}`);
+    for (const f of impactResult.impactedFeatures) {
+        const label = f.featureId || f.familyId;
+        console.log(`  [${f.priority}] ${label}: ${f.coverageStatus} (PW=${f.playwrightSpecs.length}, Cy=${f.cypressSpecs.length})`);
+    }
+    if (impactResult.warnings.length > 0) {
+        for (const w of impactResult.warnings) {
+            console.warn(`  Warning: ${w}`);
+        }
+    }
+}

package/dist/esm/cli/commands/llm_health.js

@@ -0,0 +1,35 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { AnthropicProvider } from '../../anthropic_provider.js';
+import { LLMProviderError } from '../../provider_interface.js';
+export async function runLlmHealth() {
+    if (!process.env.ANTHROPIC_API_KEY) {
+        console.error('ANTHROPIC_API_KEY is required for llm-health.');
+        process.exit(1);
+    }
+    const model = process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-5-20250929';
+    const provider = new AnthropicProvider({
+        apiKey: process.env.ANTHROPIC_API_KEY,
+        model,
+    });
+    try {
+        const response = await provider.generateText('Reply with OK.', { maxTokens: 8, timeout: 15000 });
+        const text = response.text.trim();
+        console.log(`Anthropic OK (${model}) -> ${text}`);
+    }
+    catch (error) {
+        if (error instanceof LLMProviderError) {
+            console.error(`Anthropic failed: ${error.message}`);
+            if (error.cause instanceof Error) {
+                console.error(`Cause: ${error.cause.message}`);
+            }
+        }
+        else if (error instanceof Error) {
+            console.error(`Anthropic failed: ${error.message}`);
+        }
+        else {
+            console.error(`Anthropic failed: ${String(error)}`);
+        }
+        process.exit(1);
+    }
+}

package/dist/esm/cli/commands/plan.js

@@ -0,0 +1,80 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { appendFileSync } from 'fs';
+import { join } from 'path';
+import { writeCiSummary } from '../../engine/plan_builder.js';
+import { recommendTestsAI, recommendTestsDeterministic } from '../../api.js';
+export async function runPlanCommand(args, autoConfig, config) {
+    const reportRoot = config.testsRoot || config.path;
+    const apiOptions = {
+        cwd: process.cwd(),
+        configPath: autoConfig,
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        gitSince: args.gitSince,
+        llmProvider: args.llmProvider,
+        policy: args.policyMinConfidence !== undefined ||
+            args.policySafeMergeConfidence !== undefined ||
+            args.policyWarningsThreshold !== undefined ||
+            (args.policyRiskyPatterns && args.policyRiskyPatterns.length > 0) ||
+            args.policyEnforcementMode !== undefined ||
+            (args.policyBlockActions && args.policyBlockActions.length > 0)
+            ? {
+                minConfidenceForTargeted: args.policyMinConfidence,
+                safeMergeMinConfidence: args.policySafeMergeConfidence,
+                forceFullOnWarningsAtOrAbove: args.policyWarningsThreshold,
+                riskyFilePatterns: args.policyRiskyPatterns,
+                enforcementMode: args.policyEnforcementMode,
+                blockOnActions: args.policyBlockActions,
+            }
+            : undefined,
+    };
+    let result;
+    if (args.noAi) {
+        result = recommendTestsDeterministic(apiOptions);
+    }
+    else {
+        result = await recommendTestsAI(apiOptions);
+        if (result.aiEnrichment) {
+            const { aiEnrichment } = result;
+            console.log(`AI enrichment: ${aiEnrichment.enrichedFeatures.length} features enriched (${aiEnrichment.tokenUsage.input + aiEnrichment.tokenUsage.output} tokens)`);
+        }
+        else if (!process.env.ANTHROPIC_API_KEY) {
+            console.log('Tip: set ANTHROPIC_API_KEY to enable AI-powered enrichment');
+        }
+    }
+    const { plan, planPath, ciSummaryMarkdown, ciSummaryPath } = result;
+    // Write CI summary to an additional path if --ci-comment-path was specified
+    if (args.ciCommentPath) {
+        writeCiSummary(reportRoot, ciSummaryMarkdown, args.ciCommentPath);
+    }
+    const summaryPath = ciSummaryPath;
+    // Compute metrics paths (api already wrote metrics; derive paths for GHA output)
+    const metricsEventsPath = join(reportRoot, '.e2e-ai-agents/metrics.jsonl');
+    const metricsSummaryPath = join(reportRoot, '.e2e-ai-agents/metrics-summary.json');
+    const ghaOutput = args.githubOutputPath || process.env.GITHUB_OUTPUT;
+    if (ghaOutput) {
+        appendFileSync(ghaOutput, `run_set=${plan.runSet}\n`);
+        appendFileSync(ghaOutput, `action=${plan.decision.action}\n`);
+        appendFileSync(ghaOutput, `confidence=${plan.confidence}\n`);
+        appendFileSync(ghaOutput, `enforcement_mode=${plan.enforcement.mode}\n`);
+        appendFileSync(ghaOutput, `enforcement_should_fail=${plan.enforcement.shouldFail}\n`);
+        appendFileSync(ghaOutput, `recommended_tests_count=${plan.recommendedTests.length}\n`);
+        appendFileSync(ghaOutput, `required_new_tests_count=${plan.requiredNewTests.length}\n`);
+        appendFileSync(ghaOutput, `plan_path=${planPath}\n`);
+        appendFileSync(ghaOutput, `summary_path=${summaryPath}\n`);
+        appendFileSync(ghaOutput, `metrics_events_path=${metricsEventsPath}\n`);
+        appendFileSync(ghaOutput, `metrics_summary_path=${metricsSummaryPath}\n`);
+    }
+    console.log(`Suggested run set: ${plan.runSet} (confidence ${plan.confidence})`);
+    console.log(`Decision: ${plan.decision.action} - ${plan.decision.summary}`);
+    console.log(`Enforcement: ${plan.enforcement.mode} (shouldFail=${plan.enforcement.shouldFail})`);
+    console.log(`Plan data: ${planPath}`);
+    console.log(`CI summary: ${summaryPath}`);
+    console.log(`Plan metrics: ${metricsSummaryPath}`);
+    const failOnLegacyFlag = args.failOnMustAddTests && plan.decision.action === 'must-add-tests';
+    if (failOnLegacyFlag || plan.enforcement.shouldFail) {
+        process.exit(2);
+    }
+}

package/dist/esm/cli/commands/traceability.js

@@ -0,0 +1,73 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { readFileSync } from 'fs';
+import { resolveConfig } from '../../agent/config.js';
+import { captureTraceabilityInput } from '../../agent/traceability_capture.js';
+import { ingestTraceabilityInput } from '../../agent/traceability_ingest.js';
+export function runTraceabilityCaptureCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for traceability-capture command');
+        process.exit(1);
+    }
+    if (!args.traceabilityReportPath) {
+        console.error('Error: --traceability-report <path> is required for traceability-capture command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'impact',
+        gitSince: args.gitSince,
+        llmProvider: args.llmProvider,
+    });
+    const reportRoot = config.testsRoot || config.path;
+    const output = captureTraceabilityInput({
+        appPath: config.path,
+        testsRoot: reportRoot,
+        reportPath: args.traceabilityReportPath,
+        sinceRef: args.gitSince || config.git.since,
+        outputPath: args.traceabilityCaptureOutputPath,
+        coverageMapPath: args.traceabilityCoverageMapPath,
+        changedFilesPath: args.traceabilityChangedFilesPath,
+    });
+    console.log(`Traceability input: ${output.outputPath}`);
+    console.log(`Traceability tests seen: ${output.testsSeen}`);
+    console.log(`Traceability runs generated: ${output.runsGenerated}`);
+    console.log(`Traceability changed files used: ${output.changedFilesUsed}`);
+    if (output.warnings.length > 0) {
+        console.log(`Traceability warnings: ${output.warnings.join(' | ')}`);
+    }
+}
+export function runTraceabilityIngestCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for traceability-ingest command');
+        process.exit(1);
+    }
+    if (!args.traceabilityInputPath) {
+        console.error('Error: --traceability-input <path> is required for traceability-ingest command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'impact',
+        llmProvider: args.llmProvider,
+    });
+    const reportRoot = config.testsRoot || config.path;
+    const raw = JSON.parse(readFileSync(args.traceabilityInputPath, 'utf-8'));
+    const output = ingestTraceabilityInput(reportRoot, config.impact.traceability, raw, {
+        minHits: args.traceabilityMinHits,
+        maxFilesPerTest: args.traceabilityMaxFilesPerTest,
+        maxAgeDays: args.traceabilityMaxAgeDays,
+    });
+    console.log(`Traceability manifest: ${output.manifestPath}`);
+    console.log(`Traceability state: ${output.statePath}`);
+    console.log(`Traceability ingested entries: ${output.entriesIngested}`);
+    console.log(`Traceability tracked tests: ${output.testsTracked}`);
+    console.log(`Traceability tracked edges: ${output.edgesTracked}`);
+    if (output.warnings.length > 0) {
+        console.log(`Traceability warnings: ${output.warnings.join(' | ')}`);
+    }
+}

package/dist/esm/cli/parse_args.js

@@ -0,0 +1,210 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+export const CONFIG_CANDIDATES = ['e2e-ai-agents.config.json', '.e2e-ai-agents.config.json'];
+export function findConfigUpwards(startDir) {
+    if (!startDir) {
+        return undefined;
+    }
+    let current = resolve(startDir);
+    while (true) {
+        for (const candidate of CONFIG_CANDIDATES) {
+            const fullPath = join(current, candidate);
+            if (existsSync(fullPath)) {
+                return fullPath;
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return undefined;
+}
+export function resolveAutoConfig(args) {
+    if (args.configPath) {
+        return args.configPath;
+    }
+    const searchRoots = [
+        process.cwd(),
+        args.testsRoot,
+        args.path,
+    ].filter(Boolean);
+    for (const root of searchRoots) {
+        const found = findConfigUpwards(root);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+const csvSplit = (v) => v.split(',').map((s) => s.trim()).filter(Boolean);
+// prettier-ignore
+const FLAGS = {
+    // -- boolean flags --
+    '--help': { key: 'help', type: 'boolean', aliases: ['-h'] },
+    '--apply': { key: 'apply', type: 'boolean' },
+    '--allow-fallback': { key: 'allowFallback', type: 'boolean' },
+    '--pipeline': { key: 'pipeline', type: 'boolean' },
+    '--pipeline-mcp': { key: 'pipelineMcp', type: 'boolean' },
+    '--pipeline-mcp-allow-fallback': { key: 'pipelineMcpAllowFallback', type: 'boolean' },
+    '--pipeline-mcp-only': { key: 'pipelineMcpOnly', type: 'boolean' },
+    '--pipeline-headless': { key: 'pipelineHeadless', type: 'boolean' },
+    '--pipeline-headed': { key: 'pipelineHeadless', type: 'boolean-false' },
+    '--pipeline-parallel': { key: 'pipelineParallel', type: 'boolean' },
+    '--pipeline-dry-run': { key: 'pipelineDryRun', type: 'boolean' },
+    '--fail-on-must-add-tests': { key: 'failOnMustAddTests', type: 'boolean' },
+    '--create-pr': { key: 'createPr', type: 'boolean' },
+    '--dry-run': { key: 'dryRun', type: 'boolean' },
+    '--generate': { key: 'analyzeGenerate', type: 'boolean' },
+    '--heal': { key: 'analyzeHeal', type: 'boolean' },
+    '--no-ai': { key: 'noAi', type: 'boolean' },
+    '--mattermost': { key: 'profile', type: 'boolean', transform: () => 'mattermost' },
+    // -- string flags --
+    '--config': { key: 'configPath', type: 'string' },
+    '--path': { key: 'path', type: 'string' },
+    '--tests-root': { key: 'testsRoot', type: 'string' },
+    '--framework': { key: 'framework', type: 'string', transform: (v) => v },
+    '--scenarios': { key: 'generateScenarios', type: 'string' },
+    '--pipeline-output': { key: 'pipelineOutput', type: 'string' },
+    '--pipeline-base-url': { key: 'pipelineBaseUrl', type: 'string' },
+    '--pipeline-project': { key: 'pipelineProject', type: 'string' },
+    '--spec': { key: 'specPDF', type: 'string' },
+    '--since': { key: 'gitSince', type: 'string' },
+    '--llm-provider': { key: 'llmProvider', type: 'string' },
+    '--ci-comment-path': { key: 'ciCommentPath', type: 'string' },
+    '--github-output': { key: 'githubOutputPath', type: 'string' },
+    '--feedback-input': { key: 'feedbackInputPath', type: 'string' },
+    '--traceability-report': { key: 'traceabilityReportPath', type: 'string' },
+    '--traceability-capture-output': { key: 'traceabilityCaptureOutputPath', type: 'string' },
+    '--traceability-coverage-map': { key: 'traceabilityCoverageMapPath', type: 'string' },
+    '--traceability-changed-files': { key: 'traceabilityChangedFilesPath', type: 'string' },
+    '--traceability-input': { key: 'traceabilityInputPath', type: 'string' },
+    '--branch': { key: 'branch', type: 'string' },
+    '--commit-message': { key: 'commitMessage', type: 'string' },
+    '--pr-title': { key: 'prTitle', type: 'string' },
+    '--pr-body': { key: 'prBody', type: 'string' },
+    '--pr-base': { key: 'prBase', type: 'string' },
+    '--generate-output': { key: 'analyzeGenerateOutputDir', type: 'string' },
+    '--heal-report': { key: 'analyzeHealReport', type: 'string' },
+    '--flow-catalog': { key: 'flowCatalogPath', type: 'string' },
+    // -- number flags (with isFinite guard) --
+    '--pipeline-scenarios': { key: 'pipelineScenarios', type: 'number' },
+    '--time': { key: 'timeLimitMinutes', type: 'number' },
+    '--budget-usd': { key: 'budgetUSD', type: 'number' },
+    '--budget-tokens': { key: 'budgetTokens', type: 'number' },
+    '--policy-min-confidence': { key: 'policyMinConfidence', type: 'number' },
+    '--policy-safe-merge-confidence': { key: 'policySafeMergeConfidence', type: 'number' },
+    '--policy-force-full-on-warnings': { key: 'policyWarningsThreshold', type: 'number' },
+    '--traceability-min-hits': { key: 'traceabilityMinHits', type: 'number' },
+    '--traceability-max-files-per-test': { key: 'traceabilityMaxFilesPerTest', type: 'number' },
+    '--traceability-max-age-days': { key: 'traceabilityMaxAgeDays', type: 'number' },
+    // -- number-raw flags (no isFinite guard, assigned directly via Number()) --
+    '--max-attempts': { key: 'maxAttempts', type: 'number-raw', transform: (v) => parseInt(v, 10) },
+    '--pipeline-mcp-timeout-ms': { key: 'pipelineMcpTimeoutMs', type: 'number-raw' },
+    '--pipeline-mcp-retries': { key: 'pipelineMcpRetries', type: 'number-raw' },
+    // -- enum flags --
+    '--profile': { key: 'profile', type: 'enum', enumValues: ['default', 'mattermost'] },
+    '--pipeline-browser': { key: 'pipelineBrowser', type: 'enum', enumValues: ['chrome', 'chromium', 'firefox', 'webkit'] },
+    '--policy-enforcement-mode': { key: 'policyEnforcementMode', type: 'enum', enumValues: ['advisory', 'warn', 'block'] },
+    // -- csv flags --
+    '--patterns': { key: 'testPatterns', type: 'csv' },
+    '--flow-patterns': { key: 'flowPatterns', type: 'csv' },
+    '--flow-exclude': { key: 'flowExclude', type: 'csv' },
+    '--policy-risky-patterns': { key: 'policyRiskyPatterns', type: 'csv' },
+    '--policy-block-actions': {
+        key: 'policyBlockActions',
+        type: 'csv',
+        transform: (v) => csvSplit(v).filter((s) => s === 'run-now' || s === 'must-add-tests' || s === 'safe-to-merge'),
+    },
+};
+// Build a lookup from alias -> canonical flag name
+const ALIAS_MAP = {};
+for (const [flag, def] of Object.entries(FLAGS)) {
+    ALIAS_MAP[flag] = flag;
+    if (def.aliases) {
+        for (const alias of def.aliases) {
+            ALIAS_MAP[alias] = flag;
+        }
+    }
+}
+const COMMANDS = new Set([
+    'impact', 'plan', 'heal', 'suggest', 'generate',
+    'finalize-generated-tests', 'feedback',
+    'traceability-capture', 'traceability-ingest',
+    'analyze', 'llm-health',
+]);
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+function setField(obj, key, value) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    obj[key] = value;
+}
+export function parseArgs(argv) {
+    const parsed = { apply: false, help: false };
+    if (argv.length === 0) {
+        return parsed;
+    }
+    const command = argv[0];
+    if (COMMANDS.has(command)) {
+        parsed.command = command;
+    }
+    for (let i = 1; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const canonical = ALIAS_MAP[arg];
+        if (!canonical) {
+            continue;
+        }
+        const def = FLAGS[canonical];
+        const next = argv[i + 1];
+        switch (def.type) {
+            case 'boolean':
+                setField(parsed, def.key, def.transform ? def.transform('') : true);
+                break;
+            case 'boolean-false':
+                setField(parsed, def.key, false);
+                break;
+            case 'string':
+                if (next) {
+                    setField(parsed, def.key, def.transform ? def.transform(next) : next);
+                    i += 1;
+                }
+                break;
+            case 'number':
+                if (next) {
+                    const value = Number(next);
+                    if (Number.isFinite(value)) {
+                        setField(parsed, def.key, value);
+                    }
+                    i += 1;
+                }
+                break;
+            case 'number-raw':
+                if (next) {
+                    setField(parsed, def.key, def.transform ? def.transform(next) : Number(next));
+                    i += 1;
+                }
+                break;
+            case 'csv':
+                if (next) {
+                    setField(parsed, def.key, def.transform ? def.transform(next) : csvSplit(next));
+                    i += 1;
+                }
+                break;
+            case 'enum':
+                if (next) {
+                    if (def.enumValues.includes(next)) {
+                        setField(parsed, def.key, next);
+                    }
+                    i += 1;
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    return parsed;
+}

package/dist/esm/cli/types.js

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