@yasserkhanorg/e2e-agents 1.3.1 → 1.4.0

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

@@ -0,0 +1,271 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import * as readline from 'readline';
+import { resolveConfig } from '../../agent/config.js';
+import { loadRouteFamilyManifest } from '../../knowledge/route_families.js';
+import { LLMProviderFactory } from '../../provider_factory.js';
+import { scanProject } from '../../training/scanner.js';
+import { mergeFamilies, detectStaleFamilies } from '../../training/merger.js';
+import { enrichFamilies } from '../../training/enricher.js';
+import { getCommitFiles, validateCommit, buildValidationReport, formatValidationReport } from '../../training/validator.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 } = resolveConfig(process.cwd(), autoConfig, {
+                path: appPath,
+                testsRoot: args.testsRoot,
+            });
+            testsRoot = config.testsRoot || config.path || appPath;
+        }
+        catch {
+            // use defaults
+        }
+    }
+    const outputPath = args.trainOutput ||
+        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 = resolve(appPath);
+    const resolvedTestsRoot = resolve(testsRoot);
+    const resolvedOutputPath = resolve(outputPath);
+    // Validate --path is a real project
+    if (!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}`);
+    }
+    return {
+        appPath: resolvedAppPath,
+        testsRoot: resolvedTestsRoot,
+        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 || '');
+        });
+    });
+}
+function serializeManifest(manifest) {
+    const output = {
+        families: manifest.families.map((f) => {
+            // Remove undefined/empty optional fields for clean JSON
+            const cleaned = { ...f };
+            const optionalArrays = ['pageObjects', 'components', 'webappPaths', 'serverPaths', 'specDirs', 'cypressSpecDirs', 'tags', 'userFlows', 'features'];
+            for (const key of optionalArrays) {
+                if (!cleaned[key] || (Array.isArray(cleaned[key]) && cleaned[key].length === 0)) {
+                    delete cleaned[key];
+                }
+            }
+            if (!cleaned.priority)
+                delete cleaned.priority;
+            return cleaned;
+        }),
+    };
+    return JSON.stringify(output, null, 2) + '\n';
+}
+export async function runTrainCommand(args, autoConfig) {
+    const opts = resolveTrainOptions(args, autoConfig);
+    console.log('');
+    console.log('  e2e-ai-agents train');
+    console.log('  ===================');
+    console.log('');
+    // ---------- Phase 1: Deterministic scan ----------
+    console.log('  Scanning project structure...');
+    const scanResult = scanProject(opts.appPath);
+    console.log(`  Found ${scanResult.stats.totalSourceFiles} source files, ${scanResult.stats.totalTestFiles} test files`);
+    console.log(`  Discovered ${scanResult.families.length} candidate families`);
+    if (scanResult.families.length === 0) {
+        console.log('');
+        console.log('  No families discovered. Make sure your project has recognizable');
+        console.log('  source directories (src/, server/, app/) and test directories');
+        console.log('  (tests/, e2e/, specs/) with matching names.');
+        return;
+    }
+    // ---------- Phase 2: Merge with existing ----------
+    const existing = loadRouteFamilyManifest(opts.testsRoot);
+    if (existing) {
+        console.log(`  Found existing manifest with ${existing.families.length} families`);
+    }
+    let mergeResult = mergeFamilies(existing, scanResult.families);
+    console.log(`  Merge: ${mergeResult.summary}`);
+    // ---------- Phase 3: Stale detection ----------
+    if (mergeResult.manifest.families.length > 0) {
+        const stale = detectStaleFamilies(mergeResult.manifest, opts.appPath);
+        if (stale.length > 0) {
+            console.log('');
+            console.log(`  Stale families detected (${stale.length}):`);
+            for (const id of stale) {
+                console.log(`    ${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;
+                        console.log(`  Removed ${stale.length} stale families`);
+                    }
+                }
+                finally {
+                    rl.close();
+                }
+            }
+        }
+    }
+    // ---------- Phase 4: LLM Enrichment ----------
+    if (opts.enrich) {
+        console.log('');
+        console.log('  Enriching with LLM...');
+        try {
+            const provider = await LLMProviderFactory.createFromEnv();
+            const enrichResult = await enrichFamilies(mergeResult.manifest.families, scanResult.families, opts.appPath, provider, opts.budgetUSD);
+            mergeResult.manifest.families = enrichResult.enrichedFamilies;
+            console.log(`  Enriched ${enrichResult.enrichedFamilies.length} families (${enrichResult.tokensUsed} tokens, ~$${enrichResult.costUSD})`);
+            if (enrichResult.skippedFamilies.length > 0) {
+                console.log(`  Skipped ${enrichResult.skippedFamilies.length} families (budget limit)`);
+            }
+        }
+        catch (error) {
+            console.warn(`  LLM enrichment failed: ${error instanceof Error ? error.message : String(error)}`);
+            console.warn('  Continuing with deterministic results. Use --no-enrich to skip LLM.');
+        }
+    }
+    // ---------- Phase 5: Write manifest ----------
+    console.log('');
+    const json = serializeManifest(mergeResult.manifest);
+    if (opts.dryRun) {
+        console.log('  Dry run — proposed manifest:');
+        console.log('');
+        console.log(json);
+    }
+    else {
+        const dir = dirname(opts.outputPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const tmpPath = `${opts.outputPath}.tmp`;
+        writeFileSync(tmpPath, json, 'utf-8');
+        renameSync(tmpPath, opts.outputPath);
+        console.log(`  Wrote ${opts.outputPath}`);
+        console.log(`  ${mergeResult.manifest.families.length} families`);
+    }
+    // ---------- Phase 6: Report unmatched ----------
+    if (scanResult.unmatchedSourceDirs.length > 0 || scanResult.unmatchedTestDirs.length > 0) {
+        console.log('');
+        console.log('  Unmatched (review manually):');
+        for (const dir of scanResult.unmatchedSourceDirs.slice(0, 10)) {
+            console.log(`    source: ${dir.relativePath}`);
+        }
+        for (const dir of scanResult.unmatchedTestDirs.slice(0, 10)) {
+            console.log(`    test:   ${dir.relativePath}`);
+        }
+        if (scanResult.unmatchedSourceDirs.length + scanResult.unmatchedTestDirs.length > 20) {
+            console.log('    ... and more');
+        }
+    }
+    // ---------- Phase 7: Validation (optional) ----------
+    if (opts.validate) {
+        if (opts.pr) {
+            console.log('');
+            console.log(`  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) {
+                console.log('  No files found in PR.');
+            }
+            else {
+                const validation = validateCommit(mergeResult.manifest, prFiles, `PR#${opts.pr}`, `PR #${opts.pr}`);
+                const report = buildValidationReport([validation], mergeResult.manifest);
+                console.log('');
+                console.log(formatValidationReport(report));
+            }
+        }
+        else {
+            console.log('');
+            console.log(`  Validating against git history (${opts.since})...`);
+            const commits = getCommitFiles(opts.appPath, opts.since);
+            if (commits.length === 0) {
+                console.log('  No commits found in range.');
+            }
+            else {
+                const validations = commits.map((c) => validateCommit(mergeResult.manifest, c.files, c.hash, c.message));
+                const report = buildValidationReport(validations, mergeResult.manifest);
+                console.log('');
+                console.log(formatValidationReport(report));
+            }
+        }
+    }
+    console.log('');
+}

package/dist/esm/cli/parse_args.js

@@ -61,6 +61,10 @@ const FLAGS = {
     '--generate': { key: 'analyzeGenerate', type: 'boolean' },
     '--heal': { key: 'analyzeHeal', type: 'boolean' },
     '--no-ai': { key: 'noAi', type: 'boolean' },
+    '--enrich': { key: 'trainEnrich', type: 'boolean' },
+    '--no-enrich': { key: 'trainEnrich', type: 'boolean-false' },
+    '--validate': { key: 'trainValidate', type: 'boolean' },
+    '--yes': { key: 'trainYes', type: 'boolean', aliases: ['-y'] },
     '--mattermost': { key: 'profile', type: 'boolean', transform: () => 'mattermost' },
     // -- string flags --
     '--config': { key: 'configPath', type: 'string' },
@@ -90,6 +94,7 @@ const FLAGS = {
     '--generate-output': { key: 'analyzeGenerateOutputDir', type: 'string' },
     '--heal-report': { key: 'analyzeHealReport', type: 'string' },
     '--flow-catalog': { key: 'flowCatalogPath', type: 'string' },
+    '--output': { key: 'trainOutput', type: 'string' },
     // -- number flags (with isFinite guard) --
     '--pipeline-scenarios': { key: 'pipelineScenarios', type: 'number' },
     '--time': { key: 'timeLimitMinutes', type: 'number' },
@@ -101,6 +106,7 @@ const FLAGS = {
     '--traceability-min-hits': { key: 'traceabilityMinHits', type: 'number' },
     '--traceability-max-files-per-test': { key: 'traceabilityMaxFilesPerTest', type: 'number' },
     '--traceability-max-age-days': { key: 'traceabilityMaxAgeDays', type: 'number' },
+    '--pr': { key: 'trainPr', 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' },
@@ -134,7 +140,7 @@ const COMMANDS = new Set([
     'init', 'impact', 'plan', 'heal', 'suggest', 'generate',
     'finalize-generated-tests', 'feedback',
     'traceability-capture', 'traceability-ingest',
-    'analyze', 'llm-health',
+    'analyze', 'llm-health', 'train',
 ]);
 // ---------------------------------------------------------------------------
 // Parser

package/dist/esm/cli/usage.js

@@ -14,11 +14,12 @@ export function printUsage() {
         '  e2e-ai-agents traceability-ingest --path <app-root> --traceability-input <json>',
         '  e2e-ai-agents generate [--scenarios <path|json>] [--max-attempts <n>] [--dry-run]',
         '  e2e-ai-agents analyze --path <app-root> [--tests-root <path>] [--since <ref>] [--generate] [--generate-output <dir>] [--heal] [--heal-report <json>]',
+        '  e2e-ai-agents train --path <project-root> [--no-enrich] [--validate] [--since <ref>] [--pr <num>]',
         '  e2e-ai-agents llm-health',
         '',
         'Options:',
         '  --config <path>       Path to e2e-ai-agents.config.json (auto-discovered if present)',
-        '  --path <app-root>     Path to the web app (required)',
+        '  --path <project-root> Path to the project root (scans both frontend and backend)',
         '  --profile <name>     default | mattermost',
         '  --mattermost         Shortcut for --profile mattermost',
         '  --tests-root <path>   Path to tests root (optional)',
@@ -79,6 +80,11 @@ export function printUsage() {
         '  --scenarios <path|json>  Scenarios file/JSON for generate command',
         '  --apply               Apply data-testid patches and generate tests',
         '                        (legacy shortcut; prefer approve-and-generate)',
+        '  --no-enrich              Disable LLM enrichment (offline mode, train command)',
+        '  --validate               Validate manifest against git history (train command)',
+        '  --pr <number>            GitHub PR number for validation (requires gh CLI)',
+        '  --yes, -y                Non-interactive mode (train command)',
+        '  --output <path>          Output path for route-families.json (train command)',
         '  --help                Show help',
     ].join('\n'));
 }

package/dist/esm/cli.js

@@ -14,6 +14,7 @@ import { runImpactCommand } from './cli/commands/impact.js';
 import { runPlanCommand } from './cli/commands/plan.js';
 import { runGenerateCommand } from './cli/commands/generate.js';
 import { runInitCommand } from './cli/commands/init.js';
+import { runTrainCommand } from './cli/commands/train.js';
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     const autoConfig = resolveAutoConfig(args);
@@ -22,6 +23,10 @@ async function main() {
         await runInitCommand(hasYes);
         return;
     }
+    if (args.command === 'train') {
+        await runTrainCommand(args, autoConfig);
+        return;
+    }
     if (args.help || !args.command) {
         printUsage();
         process.exit(args.command ? 0 : 1);

package/dist/esm/index.js

@@ -30,3 +30,8 @@ export { buildApiSurface, loadOrBuildApiSurface } from './knowledge/api_surface.
 export { buildSpecIndex, getSpecsForFamily } from './knowledge/spec_index.js';
 // Agentic generation
 export { runAgenticGeneration } from './agentic/runner.js';
+// Training (route-families bootstrap and maintenance)
+export { scanProject } from './training/scanner.js';
+export { mergeFamilies, detectStaleFamilies } from './training/merger.js';
+export { enrichFamilies } from './training/enricher.js';
+export { getCommitFiles, validateCommit, buildValidationReport, formatValidationReport } from './training/validator.js';

package/dist/esm/knowledge/route_families.js

@@ -3,7 +3,7 @@
 import { existsSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
 const manifestCache = new Map();
-function matchesGlob(filePath, pattern) {
+export function matchesGlob(filePath, pattern) {
     const normalized = filePath.replace(/\\/g, '/');
     const parts = pattern.replace(/\\/g, '/').split('*');
     if (parts.length === 1) {
@@ -26,7 +26,7 @@ function matchesGlob(filePath, pattern) {
     }
     return true;
 }
-function matchesAnyPattern(filePath, patterns) {
+export function matchesAnyPattern(filePath, patterns) {
     return patterns.some((pattern) => matchesGlob(filePath, pattern));
 }
 function validateFamily(family) {

package/dist/esm/training/enricher.js

@@ -0,0 +1,273 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { lstatSync, readdirSync, readFileSync } from 'fs';
+import { join, relative, resolve } from 'path';
+import { isGuessedRoute } from './types.js';
+const MAX_FILES_PER_FAMILY = 20;
+const MAX_LINES_PER_FILE = 50;
+const LLM_TIMEOUT_MS = 60000;
+const MAX_PROMPT_CHARS = 100000;
+const SENSITIVE_PATTERNS = [
+    /[._]env/, /secret/i, /credential/i, /\.pem$/, /\.key$/, /password/i,
+    /config\/secrets/, /fixtures\/.*auth/i, /\.npmrc/, /\.netrc/,
+    /id_rsa/, /id_ed25519/, /\.p12$/, /\.pfx$/, /tokens?\.json/i,
+];
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', '.next', '.nuxt', 'coverage',
+]);
+function sampleFiles(dir, maxFiles) {
+    const files = [];
+    function walk(d, depth = 0, maxDepth = 10) {
+        if (files.length >= maxFiles)
+            return;
+        if (depth > maxDepth)
+            return;
+        try {
+            for (const entry of readdirSync(d)) {
+                if (files.length >= maxFiles)
+                    return;
+                // Skip dot-dirs and known heavy directories
+                if (entry.startsWith('.') || SKIP_DIRS.has(entry))
+                    continue;
+                const full = join(d, entry);
+                try {
+                    // Skip symlinks
+                    const lstat = lstatSync(full);
+                    if (lstat.isSymbolicLink())
+                        continue;
+                    // Skip sensitive files (test against relative path from scan root)
+                    const relPath = relative(dir, full);
+                    if (SENSITIVE_PATTERNS.some((p) => p.test(relPath) || p.test(entry)))
+                        continue;
+                    if (lstat.isDirectory()) {
+                        walk(full, depth + 1, maxDepth);
+                    }
+                    else if (lstat.isFile() && lstat.size < 50000) {
+                        const ext = entry.slice(entry.lastIndexOf('.'));
+                        if (['.ts', '.tsx', '.js', '.jsx', '.go', '.py', '.rs'].includes(ext)) {
+                            const content = readFileSync(full, 'utf-8');
+                            const lines = content.split('\n').slice(0, MAX_LINES_PER_FILE).join('\n');
+                            files.push({ path: full, content: lines });
+                        }
+                    }
+                }
+                catch { /* skip */ }
+            }
+        }
+        catch { /* skip */ }
+    }
+    walk(dir);
+    return files;
+}
+function buildEnrichPrompt(families, projectRoot) {
+    const sections = [];
+    for (const family of families) {
+        const allDirs = [
+            ...family.webappPaths.map((p) => p.replace(/\/?\*.*$/, '')),
+            ...family.serverPaths.map((p) => p.replace(/\/?\*.*$/, '')),
+        ];
+        const samples = [];
+        for (const dir of allDirs) {
+            if (!dir)
+                continue;
+            const fullDir = join(resolve(projectRoot), dir);
+            samples.push(...sampleFiles(fullDir, MAX_FILES_PER_FAMILY - samples.length));
+            if (samples.length >= MAX_FILES_PER_FAMILY)
+                break;
+        }
+        // Sample spec descriptions
+        const specSamples = [];
+        for (const specDir of family.specDirs) {
+            const fullDir = join(resolve(projectRoot), specDir);
+            const specFiles = sampleFiles(fullDir, 5);
+            for (const sf of specFiles) {
+                const matches = sf.content.match(/(?:test|it|describe)\s*\(\s*['"`]([^'"`]+)/g);
+                if (matches) {
+                    specSamples.push(...matches.map((m) => m.replace(/(?:test|it|describe)\s*\(\s*['"`]/, '')));
+                }
+            }
+        }
+        sections.push(`## Family: ${family.id}
+Routes (guessed): ${JSON.stringify(family.routes)}
+Webapp paths: ${JSON.stringify(family.webappPaths)}
+Server paths: ${JSON.stringify(family.serverPaths)}
+Spec dirs: ${JSON.stringify(family.specDirs)}
+Tags: ${JSON.stringify(family.tags)}
+Features: ${family.features.map((f) => f.id).join(', ') || 'none'}
+
+Sample files (${samples.length}):
+${samples.map((s) => `### ${relative(projectRoot, s.path)}\n\`\`\`\n${s.content}\n\`\`\``).join('\n')}
+
+Test descriptions:
+${specSamples.length > 0 ? specSamples.map((d) => `- ${d}`).join('\n') : '(none found)'}
+`);
+    }
+    return `You are analyzing a codebase to enrich route-family definitions for an E2E test impact analysis tool.
+
+For each family below, provide:
+1. **priority**: P0 (critical user flow), P1 (important), or P2 (nice-to-have)
+2. **userFlows**: Array of human-readable flow names (e.g., "Create channel", "Search messages")
+3. **routes**: Improved URL patterns (e.g., "/{team}/channels/{channel}" instead of "/channels")
+4. **pageObjects**: Array of page object class names found in the code
+5. **components**: Array of UI component names relevant to this family
+
+Respond in JSON format:
+\`\`\`json
+[
+  {
+    "id": "family_id",
+    "priority": "P0",
+    "userFlows": ["Flow name 1", "Flow name 2"],
+    "routes": ["/improved/route/{param}"],
+    "pageObjects": ["PageName"],
+    "components": ["ComponentName"]
+  }
+]
+\`\`\`
+
+${sections.join('\n---\n')}`;
+}
+export function validateEntries(parsed) {
+    const filterStrings = (arr, maxLen) => {
+        if (!Array.isArray(arr))
+            return undefined;
+        const filtered = arr.filter((v) => typeof v === 'string' && v.length < maxLen);
+        return filtered.length > 0 ? filtered : undefined;
+    };
+    return parsed
+        .filter((e) => !!e && typeof e.id === 'string')
+        .map((entry) => ({
+        id: entry.id,
+        priority: ['P0', 'P1', 'P2'].includes(entry.priority) ? entry.priority : undefined,
+        routes: filterStrings(entry.routes, 200),
+        userFlows: filterStrings(entry.userFlows, 500),
+        pageObjects: filterStrings(entry.pageObjects, 200),
+        components: filterStrings(entry.components, 200),
+    }));
+}
+export function parseEnrichResponse(response) {
+    // Extract JSON from response (may be wrapped in markdown code block)
+    const jsonMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/) || [null, response];
+    const jsonStr = jsonMatch[1]?.trim() || response.trim();
+    try {
+        const parsed = JSON.parse(jsonStr);
+        if (Array.isArray(parsed)) {
+            return validateEntries(parsed);
+        }
+    }
+    catch {
+        // Try to find any JSON array in the response
+        const arrayMatch = response.match(/\[[\s\S]*\]/);
+        if (arrayMatch) {
+            try {
+                const parsed = JSON.parse(arrayMatch[0]);
+                if (Array.isArray(parsed)) {
+                    return validateEntries(parsed);
+                }
+            }
+            catch {
+                // give up
+            }
+        }
+    }
+    return [];
+}
+function applyEnrichment(family, enriched) {
+    const result = { ...family };
+    if (enriched.priority && !family.priority) {
+        result.priority = enriched.priority;
+    }
+    if (enriched.userFlows && (!family.userFlows || family.userFlows.length === 0)) {
+        result.userFlows = enriched.userFlows;
+    }
+    if (enriched.routes && enriched.routes.length > 0) {
+        // Only replace if current routes look like guesses
+        if (isGuessedRoute(family.routes)) {
+            result.routes = enriched.routes;
+        }
+    }
+    if (enriched.pageObjects && (!family.pageObjects || family.pageObjects.length === 0)) {
+        result.pageObjects = enriched.pageObjects;
+    }
+    if (enriched.components && (!family.components || family.components.length === 0)) {
+        result.components = enriched.components;
+    }
+    return result;
+}
+export async function enrichFamilies(families, scanned, projectRoot, provider, budgetUSD) {
+    const scannedMap = new Map(scanned.map((s) => [s.id, s]));
+    const enriched = [];
+    let totalTokens = 0;
+    let totalCost = 0;
+    const skipped = [];
+    // Process in chunks of 4 families
+    const chunkSize = 4;
+    for (let i = 0; i < families.length; i += chunkSize) {
+        if (totalCost >= budgetUSD) {
+            for (let j = i; j < families.length; j++) {
+                skipped.push(families[j].id);
+                enriched.push(families[j]);
+            }
+            break;
+        }
+        const chunk = families.slice(i, i + chunkSize);
+        const scannedChunk = chunk
+            .map((f) => scannedMap.get(f.id))
+            .filter((s) => s !== undefined);
+        if (scannedChunk.length === 0) {
+            enriched.push(...chunk);
+            continue;
+        }
+        let prompt = buildEnrichPrompt(scannedChunk, projectRoot);
+        if (prompt.length > MAX_PROMPT_CHARS) {
+            // Truncate at the last complete section boundary to avoid malformed input
+            const lastSectionEnd = prompt.lastIndexOf('\n---\n', MAX_PROMPT_CHARS);
+            if (lastSectionEnd > 0) {
+                console.warn(`[train] Prompt truncated from ${prompt.length} chars at section boundary`);
+                prompt = prompt.slice(0, lastSectionEnd);
+            }
+            else {
+                console.warn(`[train] Prompt truncated from ${prompt.length} to ${MAX_PROMPT_CHARS} chars`);
+                prompt = prompt.slice(0, MAX_PROMPT_CHARS);
+            }
+        }
+        let timer;
+        try {
+            const timeoutPromise = new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('LLM request timed out')), LLM_TIMEOUT_MS);
+            });
+            const response = await Promise.race([
+                provider.generateText(prompt, { maxTokens: 4096, temperature: 0.3 }),
+                timeoutPromise,
+            ]);
+            totalTokens += (response.usage?.inputTokens ?? 0) + (response.usage?.outputTokens ?? 0);
+            totalCost += response.cost ?? 0;
+            const entries = parseEnrichResponse(response.text);
+            const entryMap = new Map(entries.map((e) => [e.id, e]));
+            for (const family of chunk) {
+                const entry = entryMap.get(family.id);
+                if (entry) {
+                    enriched.push(applyEnrichment(family, entry));
+                }
+                else {
+                    enriched.push(family);
+                }
+            }
+        }
+        catch (error) {
+            // On LLM failure, keep families unchanged
+            console.warn(`[train] LLM enrichment failed for chunk: ${error instanceof Error ? error.message : String(error)}`);
+            enriched.push(...chunk);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    return {
+        enrichedFamilies: enriched,
+        tokensUsed: totalTokens,
+        costUSD: Math.round(totalCost * 100) / 100,
+        skippedFamilies: skipped,
+    };
+}