@yasserkhanorg/impact-gate 2.0.0

package/dist/cli/commands/train.js

@@ -0,0 +1,391 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTrainCommand = runTrainCommand;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const readline = __importStar(require("readline"));
+const config_js_1 = require("../../agent/config.js");
+const route_families_js_1 = require("../../knowledge/route_families.js");
+const provider_factory_js_1 = require("../../provider_factory.js");
+const logger_js_1 = require("../../logger.js");
+const version_js_1 = require("../../version.js");
+const scanner_js_1 = require("../../training/scanner.js");
+const kg_scanner_js_1 = require("../../training/kg_scanner.js");
+const merger_js_1 = require("../../training/merger.js");
+const enricher_js_1 = require("../../training/enricher.js");
+const validator_js_1 = require("../../training/validator.js");
+const kg_bridge_js_1 = require("../../knowledge/kg_bridge.js");
+class TrainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TrainError';
+    }
+}
+const MAX_BUDGET_USD = 10;
+/**
+ * Resolves train-specific options from CLI args.
+ * Unlike other commands (analyze, plan, heal) that use the shared resolveConfig()
+ * for full pipeline configuration, train only needs appPath and testsRoot.
+ * We call resolveConfig() solely to extract testsRoot from the config file.
+ */
+function resolveTrainOptions(args, autoConfig) {
+    const appPath = args.path || '.';
+    let testsRoot = args.testsRoot || appPath;
+    // Try to resolve testsRoot from config
+    if (autoConfig) {
+        try {
+            const { config } = (0, config_js_1.resolveConfig)(process.cwd(), autoConfig, {
+                path: appPath,
+                testsRoot: args.testsRoot,
+            });
+            testsRoot = config.testsRoot || config.path || appPath;
+        }
+        catch {
+            // use defaults
+        }
+    }
+    const outputPath = args.trainOutput ||
+        (0, path_1.join)(testsRoot, '.e2e-ai-agents', 'route-families.json');
+    // Validate --pr is a positive integer
+    if (args.trainPr !== undefined && (!Number.isInteger(args.trainPr) || args.trainPr <= 0)) {
+        throw new TrainError('--pr must be a positive integer');
+    }
+    // Validate --pr and --since are mutually exclusive
+    if (args.trainPr && args.gitSince) {
+        throw new TrainError('--pr and --since are mutually exclusive.');
+    }
+    // Validate --since format (reject leading '-' to prevent git flag injection)
+    const since = args.gitSince || 'HEAD~20';
+    if (/^-/.test(since) || !/^[a-zA-Z0-9_.~^@\/-]+$/.test(since)) {
+        throw new TrainError(`Invalid git ref: ${since}`);
+    }
+    // Validate budget bounds
+    const budget = args.budgetUSD || 0.50;
+    if (budget <= 0) {
+        throw new TrainError('--budget-usd must be a positive number');
+    }
+    if (budget > MAX_BUDGET_USD) {
+        throw new TrainError(`Budget exceeds maximum of $${MAX_BUDGET_USD}. Use a lower --budget-usd value.`);
+    }
+    const resolvedAppPath = (0, path_1.resolve)(appPath);
+    const resolvedTestsRoot = (0, path_1.resolve)(testsRoot);
+    const resolvedOutputPath = (0, path_1.resolve)(outputPath);
+    // Validate --path is a real project
+    if (!(0, fs_1.existsSync)(resolvedAppPath)) {
+        throw new TrainError(`Project root not found: ${resolvedAppPath}`);
+    }
+    // Validate --output is within project boundary (append separator to prevent prefix attacks)
+    const inApp = resolvedOutputPath === resolvedAppPath || resolvedOutputPath.startsWith(resolvedAppPath + '/');
+    const inTests = resolvedOutputPath === resolvedTestsRoot || resolvedOutputPath.startsWith(resolvedTestsRoot + '/');
+    if (!inApp && !inTests) {
+        throw new TrainError(`Output path must be within the project root or tests root: ${resolvedOutputPath}`);
+    }
+    // Discover git repo root for monorepo-aware scanning and validation
+    let gitRepoRoot;
+    try {
+        gitRepoRoot = (0, child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], {
+            cwd: resolvedAppPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        // Not a git repo or git not available
+    }
+    // Resolve serverRoot: explicit flag, or auto-detect from git repo root
+    let serverRoot = args.serverPath;
+    if (!serverRoot && gitRepoRoot) {
+        const serverDir = (0, path_1.join)(gitRepoRoot, 'server');
+        if ((0, fs_1.existsSync)(serverDir)) {
+            serverRoot = serverDir;
+        }
+    }
+    const resolvedServerRoot = serverRoot ? (0, path_1.resolve)(serverRoot) : undefined;
+    return {
+        appPath: resolvedAppPath,
+        testsRoot: resolvedTestsRoot,
+        serverRoot: resolvedServerRoot,
+        gitRepoRoot: gitRepoRoot ? (0, path_1.resolve)(gitRepoRoot) : undefined,
+        enrich: args.trainEnrich !== false,
+        validate: args.trainValidate || false,
+        since,
+        pr: args.trainPr,
+        outputPath: resolvedOutputPath,
+        dryRun: args.dryRun || false,
+        yes: args.trainYes || false,
+        budgetUSD: budget,
+    };
+}
+function ask(rl, question, defaultValue) {
+    const suffix = defaultValue ? ` (${defaultValue})` : '';
+    return new Promise((res) => {
+        rl.question(`${question}${suffix}: `, (answer) => {
+            res(answer.trim() || defaultValue || '');
+        });
+    });
+}
+async function runTrainCommand(args, autoConfig) {
+    const opts = resolveTrainOptions(args, autoConfig);
+    const totalTimer = logger_js_1.logger.timer('train-total');
+    const timings = {};
+    // Configure observability from CLI flags
+    if (args.verbose)
+        logger_js_1.logger.setLevel(logger_js_1.LogLevel.DEBUG);
+    if (args.jsonOutput)
+        logger_js_1.logger.setJsonMode(true);
+    logger_js_1.logger.info('impact-gate train');
+    logger_js_1.logger.info('===================');
+    // ---------- Phase 1: Deterministic scan ----------
+    // Prefer knowledge graph when available
+    const kg = (0, kg_bridge_js_1.loadKnowledgeGraph)(opts.appPath);
+    logger_js_1.logger.info('Scanning project structure...');
+    if (opts.serverRoot) {
+        logger_js_1.logger.info(`Server root: ${opts.serverRoot}`);
+    }
+    const scanTimer = logger_js_1.logger.timer('scan');
+    let scanResult;
+    if (kg) {
+        logger_js_1.logger.info('Using knowledge graph for scanning (found .understand-anything/knowledge-graph.json)');
+        scanResult = (0, kg_scanner_js_1.scanFromKnowledgeGraph)(kg);
+        logger_js_1.logger.info(`KG: ${kg.nodes.length} nodes, ${kg.edges.length} edges`);
+    }
+    else {
+        scanResult = (0, scanner_js_1.scanProject)(opts.appPath, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined, opts.serverRoot, opts.gitRepoRoot);
+    }
+    timings.scan = scanTimer.end();
+    logger_js_1.logger.info(`Found ${scanResult.stats.totalSourceFiles} source files, ${scanResult.stats.totalTestFiles} test files`);
+    logger_js_1.logger.info(`Discovered ${scanResult.families.length} candidate families`);
+    if (scanResult.families.length === 0) {
+        logger_js_1.logger.info('No families discovered. Make sure your project has recognizable');
+        logger_js_1.logger.info('source directories (src/, server/, app/) and test directories');
+        logger_js_1.logger.info('(tests/, e2e/, specs/) with matching names.');
+        return;
+    }
+    // ---------- Phase 2: Merge with existing ----------
+    const mergeTimer = logger_js_1.logger.timer('merge');
+    const existing = (0, route_families_js_1.loadRouteFamilyManifest)(opts.testsRoot);
+    if (existing) {
+        logger_js_1.logger.info(`Found existing manifest with ${existing.families.length} families`);
+    }
+    let mergeResult = (0, merger_js_1.mergeFamilies)(existing, scanResult.families);
+    timings.merge = mergeTimer.end();
+    logger_js_1.logger.info(`Merge: ${mergeResult.summary}`);
+    // ---------- Phase 3: Stale detection ----------
+    if (mergeResult.manifest.families.length > 0) {
+        const stale = (0, merger_js_1.detectStaleFamilies)(mergeResult.manifest, opts.appPath, opts.testsRoot);
+        if (stale.length > 0) {
+            logger_js_1.logger.info(`Stale families detected (${stale.length}):`);
+            for (const id of stale) {
+                logger_js_1.logger.info(`  ${id} — paths no longer exist`);
+            }
+            if (!opts.yes && !opts.dryRun && process.stdin.isTTY) {
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                try {
+                    const answer = await ask(rl, '  Remove stale families? [y/N]', 'N');
+                    if (answer.toLowerCase() === 'y') {
+                        const staleSet = new Set(stale);
+                        mergeResult.manifest.families = mergeResult.manifest.families.filter((f) => !staleSet.has(f.id));
+                        mergeResult.staleFamilies = stale;
+                        logger_js_1.logger.info(`Removed ${stale.length} stale families`);
+                    }
+                }
+                finally {
+                    rl.close();
+                }
+            }
+        }
+    }
+    // ---------- Phase 4: LLM Enrichment ----------
+    let enrichTokens = 0;
+    let enrichCost = 0;
+    let enrichRequests = 0;
+    let enrichAvgResponseMs = 0;
+    if (opts.enrich) {
+        logger_js_1.logger.info('Enriching with LLM...');
+        const enrichTimer = logger_js_1.logger.timer('enrich');
+        try {
+            const provider = await provider_factory_js_1.LLMProviderFactory.createFromEnv();
+            const enrichResult = await (0, enricher_js_1.enrichFamilies)(mergeResult.manifest.families, scanResult.families, opts.appPath, provider, opts.budgetUSD, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined);
+            mergeResult.manifest.families = enrichResult.enrichedFamilies;
+            enrichTokens = enrichResult.tokensUsed;
+            enrichCost = enrichResult.costUSD;
+            enrichRequests = enrichResult.requestCount ?? 0;
+            enrichAvgResponseMs = enrichResult.avgResponseMs ?? 0;
+            logger_js_1.logger.info(`Enriched ${enrichResult.enrichedFamilies.length} families`, {
+                tokens: enrichResult.tokensUsed,
+                cost: enrichResult.costUSD,
+                requests: enrichRequests,
+                avgResponseMs: enrichAvgResponseMs,
+            });
+            if (enrichResult.skippedFamilies.length > 0) {
+                logger_js_1.logger.info(`Skipped ${enrichResult.skippedFamilies.length} families (budget limit)`);
+            }
+        }
+        catch (error) {
+            logger_js_1.logger.warn(`LLM enrichment failed: ${error instanceof Error ? error.message : String(error)}`);
+            logger_js_1.logger.warn('Continuing with deterministic results. Use --no-enrich to skip LLM.');
+        }
+        timings.enrich = enrichTimer.end();
+    }
+    // ---------- Phase 5: Write manifest ----------
+    const json = (0, route_families_js_1.serializeManifest)(mergeResult.manifest);
+    if (opts.dryRun) {
+        logger_js_1.logger.info('Dry run — proposed manifest:');
+        console.log(json);
+    }
+    else {
+        const dir = (0, path_1.dirname)(opts.outputPath);
+        if (!(0, fs_1.existsSync)(dir)) {
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+        }
+        const tmpPath = `${opts.outputPath}.tmp`;
+        (0, fs_1.writeFileSync)(tmpPath, json, 'utf-8');
+        (0, fs_1.renameSync)(tmpPath, opts.outputPath);
+        logger_js_1.logger.info(`Wrote ${opts.outputPath}`);
+        logger_js_1.logger.info(`${mergeResult.manifest.families.length} families`);
+    }
+    // ---------- Phase 6: Report unmatched ----------
+    if (scanResult.unmatchedSourceDirs.length > 0 || scanResult.unmatchedTestDirs.length > 0) {
+        logger_js_1.logger.info('Unmatched (review manually):');
+        for (const dir of scanResult.unmatchedSourceDirs.slice(0, 10)) {
+            logger_js_1.logger.info(`  source: ${dir.relativePath}`);
+        }
+        for (const dir of scanResult.unmatchedTestDirs.slice(0, 10)) {
+            logger_js_1.logger.info(`  test:   ${dir.relativePath}`);
+        }
+        if (scanResult.unmatchedSourceDirs.length + scanResult.unmatchedTestDirs.length > 20) {
+            logger_js_1.logger.info('  ... and more');
+        }
+    }
+    // ---------- Phase 7: Validation (optional) ----------
+    let validationReport;
+    if (opts.validate) {
+        const validateTimer = logger_js_1.logger.timer('validate');
+        // Build path prefixes for monorepo-aware path normalization.
+        // Git log returns repo-root-relative paths, but manifest globs are
+        // relative to appPath, testsRoot, or serverRoot.
+        const pathPrefixes = [];
+        if (opts.gitRepoRoot) {
+            const { relative: relPath } = await import('path');
+            for (const root of [opts.appPath, opts.testsRoot, opts.serverRoot].filter(Boolean)) {
+                const rel = relPath(opts.gitRepoRoot, root).replace(/\\/g, '/');
+                if (rel && !rel.startsWith('..') && rel !== '.') {
+                    pathPrefixes.push(rel.endsWith('/') ? rel : rel + '/');
+                }
+            }
+        }
+        logger_js_1.logger.debug('Validation path prefixes', { prefixes: pathPrefixes });
+        if (opts.pr) {
+            logger_js_1.logger.info(`Validating against PR #${opts.pr}...`);
+            // Check for gh CLI
+            const { execFileSync } = await import('child_process');
+            try {
+                execFileSync('gh', ['--version'], { stdio: 'pipe' });
+            }
+            catch {
+                throw new TrainError('--pr requires the GitHub CLI (gh). Install: https://cli.github.com/');
+            }
+            // Fetch PR changed files via gh CLI
+            let prFiles;
+            try {
+                const output = execFileSync('gh', ['pr', 'view', String(opts.pr), '--json', 'files', '-q', '.files[].path'], {
+                    cwd: opts.appPath,
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                prFiles = output.trim().split('\n').filter(Boolean);
+            }
+            catch (error) {
+                throw new TrainError(`Error fetching PR #${opts.pr}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (prFiles.length === 0) {
+                logger_js_1.logger.info('No files found in PR.');
+            }
+            else {
+                const validation = (0, validator_js_1.validateCommit)(mergeResult.manifest, prFiles, `PR#${opts.pr}`, `PR #${opts.pr}`, pathPrefixes);
+                validationReport = (0, validator_js_1.buildValidationReport)([validation], mergeResult.manifest);
+                logger_js_1.logger.info((0, validator_js_1.formatValidationReport)(validationReport));
+            }
+        }
+        else {
+            logger_js_1.logger.info(`Validating against git history (${opts.since})...`);
+            const commits = (0, validator_js_1.getCommitFiles)(opts.gitRepoRoot || opts.appPath, opts.since);
+            if (commits.length === 0) {
+                logger_js_1.logger.info('No commits found in range.');
+            }
+            else {
+                const validations = commits.map((c) => (0, validator_js_1.validateCommit)(mergeResult.manifest, c.files, c.hash, c.message, pathPrefixes));
+                validationReport = (0, validator_js_1.buildValidationReport)(validations, mergeResult.manifest);
+                logger_js_1.logger.info((0, validator_js_1.formatValidationReport)(validationReport));
+            }
+        }
+        timings.validate = validateTimer.end();
+    }
+    timings.total = totalTimer.end();
+    // ---------- Write train report ----------
+    if (!opts.dryRun) {
+        const reportDir = (0, path_1.dirname)(opts.outputPath);
+        const trainReport = {
+            timestamp: new Date().toISOString(),
+            version: (0, version_js_1.getVersion)(),
+            timings,
+            families: {
+                total: mergeResult.manifest.families.length,
+                new: mergeResult.newFamilies.length,
+                updated: mergeResult.updatedFamilies.length,
+                stale: mergeResult.staleFamilies.length,
+            },
+            coverage: validationReport ? {
+                percent: validationReport.coveragePercent,
+                boundFiles: validationReport.boundFiles,
+                totalFiles: validationReport.totalFiles,
+            } : undefined,
+            llm: opts.enrich ? {
+                tokensUsed: enrichTokens,
+                costUSD: enrichCost,
+                requests: enrichRequests,
+                avgResponseMs: enrichAvgResponseMs,
+            } : undefined,
+        };
+        const reportPath = (0, path_1.join)(reportDir, 'train-report.json');
+        (0, fs_1.writeFileSync)(reportPath, JSON.stringify(trainReport, null, 2) + '\n', 'utf-8');
+        logger_js_1.logger.debug('Wrote train report', { path: reportPath });
+    }
+    logger_js_1.logger.info('Done.');
+}

package/dist/cli/defaults.d.ts

@@ -0,0 +1,35 @@
+import type { FrameworkType } from '../agent/config.js';
+export interface ResolvedDefaults {
+    path: string;
+    testsRoot: string;
+    framework: FrameworkType;
+    since: string;
+}
+/**
+ * Detect the test framework from package.json dependencies.
+ */
+export declare function detectFramework(appPath: string): FrameworkType;
+/**
+ * Detect the tests root directory by scanning common conventions.
+ */
+export declare function detectTestsRoot(appPath: string): string | undefined;
+/**
+ * Detect the git default branch for diffing.
+ * Returns origin/<branch> format.
+ */
+export declare function detectGitDefaultBranch(appPath: string): string;
+/**
+ * Detect the project root by walking up to find package.json or .git.
+ */
+export declare function detectProjectRoot(startDir: string): string;
+/**
+ * Resolve defaults for CLI commands that need path/testsRoot/framework/since.
+ * Explicit values from CLI flags take precedence over detected values.
+ */
+export declare function resolveDefaults(explicit: {
+    path?: string;
+    testsRoot?: string;
+    framework?: FrameworkType;
+    gitSince?: string;
+}): ResolvedDefaults;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/cli/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/cli/defaults.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,aAAa,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACjB;AAyCD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAkC9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoBnE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA4B9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,gBAAgB,CAOnB"}

package/dist/cli/defaults.js

@@ -0,0 +1,172 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFramework = detectFramework;
+exports.detectTestsRoot = detectTestsRoot;
+exports.detectGitDefaultBranch = detectGitDefaultBranch;
+exports.detectProjectRoot = detectProjectRoot;
+exports.resolveDefaults = resolveDefaults;
+const fs_1 = require("fs");
+const child_process_1 = require("child_process");
+const path_1 = require("path");
+function detectPytestFramework(appPath) {
+    const resolvedPath = (0, path_1.resolve)(appPath);
+    const pytestIni = (0, path_1.join)(resolvedPath, 'pytest.ini');
+    if ((0, fs_1.existsSync)(pytestIni)) {
+        return 'pytest';
+    }
+    const conftest = (0, path_1.join)(resolvedPath, 'conftest.py');
+    if ((0, fs_1.existsSync)(conftest)) {
+        return 'pytest';
+    }
+    const pyproject = (0, path_1.join)(resolvedPath, 'pyproject.toml');
+    if ((0, fs_1.existsSync)(pyproject)) {
+        try {
+            const content = (0, fs_1.readFileSync)(pyproject, 'utf-8');
+            if (content.includes('pytest')) {
+                return 'pytest';
+            }
+        }
+        catch {
+            // ignore malformed or unreadable file
+        }
+    }
+    const setupCfg = (0, path_1.join)(resolvedPath, 'setup.cfg');
+    if ((0, fs_1.existsSync)(setupCfg)) {
+        try {
+            const content = (0, fs_1.readFileSync)(setupCfg, 'utf-8');
+            if (content.includes('[tool:pytest]') || content.includes('[pytest]')) {
+                return 'pytest';
+            }
+        }
+        catch {
+            // ignore malformed or unreadable file
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect the test framework from package.json dependencies.
+ */
+function detectFramework(appPath) {
+    const resolvedPath = (0, path_1.resolve)(appPath);
+    const pkgPath = (0, path_1.join)(resolvedPath, 'package.json');
+    if (!(0, fs_1.existsSync)(pkgPath)) {
+        const pytestFramework = detectPytestFramework(resolvedPath);
+        if (pytestFramework) {
+            return pytestFramework;
+        }
+        return 'auto';
+    }
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf-8'));
+        const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        if (allDeps['@playwright/test'] || allDeps.playwright) {
+            return 'playwright';
+        }
+        if (allDeps.cypress) {
+            return 'cypress';
+        }
+        if (allDeps.supertest) {
+            return 'supertest';
+        }
+        if (allDeps['selenium-webdriver'] || allDeps.webdriverio) {
+            return 'selenium';
+        }
+    }
+    catch {
+        // ignore malformed package.json
+    }
+    const pytestFramework = detectPytestFramework(resolvedPath);
+    if (pytestFramework) {
+        return pytestFramework;
+    }
+    return 'auto';
+}
+/**
+ * Detect the tests root directory by scanning common conventions.
+ */
+function detectTestsRoot(appPath) {
+    const resolvedPath = (0, path_1.resolve)(appPath);
+    const candidates = [
+        'e2e-tests/playwright',
+        'e2e-tests',
+        'e2e',
+        'tests/e2e',
+        'test/e2e',
+        'tests',
+        'test',
+        'specs',
+        'playwright',
+        'cypress',
+    ];
+    for (const candidate of candidates) {
+        if ((0, fs_1.existsSync)((0, path_1.join)(resolvedPath, candidate))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect the git default branch for diffing.
+ * Returns origin/<branch> format.
+ */
+function detectGitDefaultBranch(appPath) {
+    try {
+        // Try to find the remote HEAD branch first
+        const remoteInfo = (0, child_process_1.execFileSync)('git', ['remote', 'show', 'origin'], {
+            cwd: (0, path_1.resolve)(appPath),
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        });
+        const headMatch = remoteInfo.match(/HEAD branch:\s*(.+)/);
+        if (headMatch) {
+            return `origin/${headMatch[1].trim()}`;
+        }
+    }
+    catch {
+        // fallback to current branch
+    }
+    try {
+        const result = (0, child_process_1.execFileSync)('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd: (0, path_1.resolve)(appPath),
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        }).trim();
+        return `origin/${result}`;
+    }
+    catch {
+        return 'origin/main';
+    }
+}
+/**
+ * Detect the project root by walking up to find package.json or .git.
+ */
+function detectProjectRoot(startDir) {
+    let current = (0, path_1.resolve)(startDir);
+    while (true) {
+        if ((0, fs_1.existsSync)((0, path_1.join)(current, 'package.json')) || (0, fs_1.existsSync)((0, path_1.join)(current, '.git'))) {
+            return current;
+        }
+        const parent = (0, path_1.resolve)(current, '..');
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return startDir;
+}
+/**
+ * Resolve defaults for CLI commands that need path/testsRoot/framework/since.
+ * Explicit values from CLI flags take precedence over detected values.
+ */
+function resolveDefaults(explicit) {
+    const path = explicit.path || detectProjectRoot(process.cwd());
+    const testsRoot = explicit.testsRoot || detectTestsRoot(path) || '.';
+    const framework = explicit.framework || detectFramework(path);
+    const since = explicit.gitSince || detectGitDefaultBranch(path);
+    return { path, testsRoot, framework, since };
+}

package/dist/cli/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CLI Error types with structured exit codes.
+ *
+ * Exit codes:
+ *   0 = success
+ *   1 = general/user error (bad args, missing config, invalid input)
+ *   2 = budget exceeded
+ *   3 = LLM provider unavailable (API down, auth failure)
+ *   4 = invalid manifest or config file
+ */
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly GENERAL_ERROR: 1;
+    readonly BUDGET_EXCEEDED: 2;
+    readonly PROVIDER_UNAVAILABLE: 3;
+    readonly INVALID_CONFIG: 4;
+};
+export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
+export declare class CliError extends Error {
+    readonly exitCode: ExitCode;
+    constructor(message: string, exitCode?: ExitCode);
+}
+/**
+ * Classify an unknown error into the appropriate exit code.
+ */
+export declare function classifyError(error: unknown): ExitCode;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cli/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/cli/errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,OAAO,UAAU,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAElE,qBAAa,QAAS,SAAQ,KAAK;aAGX,QAAQ,EAAE,QAAQ;gBADlC,OAAO,EAAE,MAAM,EACC,QAAQ,GAAE,QAAmC;CAKpE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CA0BtD"}