@yasserkhanorg/e2e-agents 1.6.0 → 1.7.1

package/dist/cli/commands/train.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"train.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/train.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,aAAa,CAAC;AAqJ5C,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqL1F"}
+{"version":3,"file":"train.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/train.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,aAAa,CAAC;AAqJ5C,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsP1F"}

package/dist/cli/commands/train.js

@@ -43,6 +43,7 @@ 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 scanner_js_1 = require("../../training/scanner.js");
 const merger_js_1 = require("../../training/merger.js");
 const enricher_js_1 = require("../../training/enricher.js");
@@ -176,40 +177,47 @@ function serializeManifest(manifest) {
 }
 async function runTrainCommand(args, autoConfig) {
     const opts = resolveTrainOptions(args, autoConfig);
-    console.log('');
-    console.log('  e2e-ai-agents train');
-    console.log('  ===================');
-    console.log('');
+    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('e2e-ai-agents train');
+    logger_js_1.logger.info('===================');
     // ---------- Phase 1: Deterministic scan ----------
-    console.log('  Scanning project structure...');
+    logger_js_1.logger.info('Scanning project structure...');
     if (opts.serverRoot) {
-        console.log(`  Server root: ${opts.serverRoot}`);
+        logger_js_1.logger.info(`Server root: ${opts.serverRoot}`);
     }
-    const scanResult = (0, scanner_js_1.scanProject)(opts.appPath, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined, opts.serverRoot);
-    console.log(`  Found ${scanResult.stats.totalSourceFiles} source files, ${scanResult.stats.totalTestFiles} test files`);
-    console.log(`  Discovered ${scanResult.families.length} candidate families`);
+    const scanTimer = logger_js_1.logger.timer('scan');
+    const 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) {
-        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.');
+        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) {
-        console.log(`  Found existing manifest with ${existing.families.length} families`);
+        logger_js_1.logger.info(`Found existing manifest with ${existing.families.length} families`);
     }
     let mergeResult = (0, merger_js_1.mergeFamilies)(existing, scanResult.families);
-    console.log(`  Merge: ${mergeResult.summary}`);
+    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) {
-            console.log('');
-            console.log(`  Stale families detected (${stale.length}):`);
+            logger_js_1.logger.info(`Stale families detected (${stale.length}):`);
             for (const id of stale) {
-                console.log(`    ${id} — paths no longer exist`);
+                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 });
@@ -219,7 +227,7 @@ async function runTrainCommand(args, autoConfig) {
                         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`);
+                        logger_js_1.logger.info(`Removed ${stale.length} stale families`);
                     }
                 }
                 finally {
@@ -229,29 +237,41 @@ async function runTrainCommand(args, autoConfig) {
         }
     }
     // ---------- Phase 4: LLM Enrichment ----------
+    let enrichTokens = 0;
+    let enrichCost = 0;
+    let enrichRequests = 0;
+    let enrichAvgResponseMs = 0;
     if (opts.enrich) {
-        console.log('');
-        console.log('  Enriching with LLM...');
+        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;
-            console.log(`  Enriched ${enrichResult.enrichedFamilies.length} families (${enrichResult.tokensUsed} tokens, ~$${enrichResult.costUSD})`);
+            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) {
-                console.log(`  Skipped ${enrichResult.skippedFamilies.length} families (budget limit)`);
+                logger_js_1.logger.info(`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.');
+            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 ----------
-    console.log('');
     const json = serializeManifest(mergeResult.manifest);
     if (opts.dryRun) {
-        console.log('  Dry run — proposed manifest:');
-        console.log('');
+        logger_js_1.logger.info('Dry run — proposed manifest:');
         console.log(json);
     }
     else {
@@ -262,28 +282,42 @@ async function runTrainCommand(args, autoConfig) {
         const tmpPath = `${opts.outputPath}.tmp`;
         (0, fs_1.writeFileSync)(tmpPath, json, 'utf-8');
         (0, fs_1.renameSync)(tmpPath, opts.outputPath);
-        console.log(`  Wrote ${opts.outputPath}`);
-        console.log(`  ${mergeResult.manifest.families.length} families`);
+        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) {
-        console.log('');
-        console.log('  Unmatched (review manually):');
+        logger_js_1.logger.info('Unmatched (review manually):');
         for (const dir of scanResult.unmatchedSourceDirs.slice(0, 10)) {
-            console.log(`    source: ${dir.relativePath}`);
+            logger_js_1.logger.info(`  source: ${dir.relativePath}`);
         }
         for (const dir of scanResult.unmatchedTestDirs.slice(0, 10)) {
-            console.log(`    test:   ${dir.relativePath}`);
+            logger_js_1.logger.info(`  test:   ${dir.relativePath}`);
         }
         if (scanResult.unmatchedSourceDirs.length + scanResult.unmatchedTestDirs.length > 20) {
-            console.log('    ... and more');
+            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) {
-            console.log('');
-            console.log(`  Validating against PR #${opts.pr}...`);
+            logger_js_1.logger.info(`Validating against PR #${opts.pr}...`);
             // Check for gh CLI
             const { execFileSync } = await import('child_process');
             try {
@@ -306,29 +340,57 @@ async function runTrainCommand(args, autoConfig) {
                 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.');
+                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}`);
-                const report = (0, validator_js_1.buildValidationReport)([validation], mergeResult.manifest);
-                console.log('');
-                console.log((0, validator_js_1.formatValidationReport)(report));
+                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 {
-            console.log('');
-            console.log(`  Validating against git history (${opts.since})...`);
+            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) {
-                console.log('  No commits found in range.');
+                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));
-                const report = (0, validator_js_1.buildValidationReport)(validations, mergeResult.manifest);
-                console.log('');
-                console.log((0, validator_js_1.formatValidationReport)(report));
+                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: '1.7.0',
+            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 });
     }
-    console.log('');
+    logger_js_1.logger.info('Done.');
 }

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

@@ -1 +1 @@
-{"version":3,"file":"parse_args.d.ts","sourceRoot":"","sources":["../../src/cli/parse_args.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAU,UAAU,EAAC,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,iBAAiB,UAA8D,CAAC;AAE7F,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAmBlF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAmBtE;AA4ID,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA4EpD"}
+{"version":3,"file":"parse_args.d.ts","sourceRoot":"","sources":["../../src/cli/parse_args.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAU,UAAU,EAAC,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,iBAAiB,UAA8D,CAAC;AAE7F,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAmBlF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAmBtE;AA8ID,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA4EpD"}

package/dist/cli/parse_args.js

@@ -71,6 +71,8 @@ const FLAGS = {
     '--no-enrich': { key: 'trainEnrich', type: 'boolean-false' },
     '--validate': { key: 'trainValidate', type: 'boolean' },
     '--yes': { key: 'trainYes', type: 'boolean', aliases: ['-y'] },
+    '--verbose': { key: 'verbose', type: 'boolean', aliases: ['-v'] },
+    '--json': { key: 'jsonOutput', type: 'boolean' },
     '--mattermost': { key: 'profile', type: 'boolean', transform: () => 'mattermost' },
     // -- string flags --
     '--config': { key: 'configPath', type: 'string' },

package/dist/cli/types.d.ts

@@ -72,5 +72,7 @@ export interface ParsedArgs {
     trainOutput?: string;
     trainYes?: boolean;
     serverPath?: string;
+    verbose?: boolean;
+    jsonOutput?: boolean;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cli/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cli/types.ts"],"names":[],"mappings":"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"}

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

@@ -7,6 +7,7 @@ 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 { logger, LogLevel } from '../../logger.js';
 import { scanProject } from '../../training/scanner.js';
 import { mergeFamilies, detectStaleFamilies } from '../../training/merger.js';
 import { enrichFamilies } from '../../training/enricher.js';
@@ -140,40 +141,47 @@ function serializeManifest(manifest) {
 }
 export async function runTrainCommand(args, autoConfig) {
     const opts = resolveTrainOptions(args, autoConfig);
-    console.log('');
-    console.log('  e2e-ai-agents train');
-    console.log('  ===================');
-    console.log('');
+    const totalTimer = logger.timer('train-total');
+    const timings = {};
+    // Configure observability from CLI flags
+    if (args.verbose)
+        logger.setLevel(LogLevel.DEBUG);
+    if (args.jsonOutput)
+        logger.setJsonMode(true);
+    logger.info('e2e-ai-agents train');
+    logger.info('===================');
     // ---------- Phase 1: Deterministic scan ----------
-    console.log('  Scanning project structure...');
+    logger.info('Scanning project structure...');
     if (opts.serverRoot) {
-        console.log(`  Server root: ${opts.serverRoot}`);
+        logger.info(`Server root: ${opts.serverRoot}`);
     }
-    const scanResult = scanProject(opts.appPath, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined, opts.serverRoot);
-    console.log(`  Found ${scanResult.stats.totalSourceFiles} source files, ${scanResult.stats.totalTestFiles} test files`);
-    console.log(`  Discovered ${scanResult.families.length} candidate families`);
+    const scanTimer = logger.timer('scan');
+    const scanResult = scanProject(opts.appPath, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined, opts.serverRoot, opts.gitRepoRoot);
+    timings.scan = scanTimer.end();
+    logger.info(`Found ${scanResult.stats.totalSourceFiles} source files, ${scanResult.stats.totalTestFiles} test files`);
+    logger.info(`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.');
+        logger.info('No families discovered. Make sure your project has recognizable');
+        logger.info('source directories (src/, server/, app/) and test directories');
+        logger.info('(tests/, e2e/, specs/) with matching names.');
         return;
     }
     // ---------- Phase 2: Merge with existing ----------
+    const mergeTimer = logger.timer('merge');
     const existing = loadRouteFamilyManifest(opts.testsRoot);
     if (existing) {
-        console.log(`  Found existing manifest with ${existing.families.length} families`);
+        logger.info(`Found existing manifest with ${existing.families.length} families`);
     }
     let mergeResult = mergeFamilies(existing, scanResult.families);
-    console.log(`  Merge: ${mergeResult.summary}`);
+    timings.merge = mergeTimer.end();
+    logger.info(`Merge: ${mergeResult.summary}`);
     // ---------- Phase 3: Stale detection ----------
     if (mergeResult.manifest.families.length > 0) {
         const stale = detectStaleFamilies(mergeResult.manifest, opts.appPath, opts.testsRoot);
         if (stale.length > 0) {
-            console.log('');
-            console.log(`  Stale families detected (${stale.length}):`);
+            logger.info(`Stale families detected (${stale.length}):`);
             for (const id of stale) {
-                console.log(`    ${id} — paths no longer exist`);
+                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 });
@@ -183,7 +191,7 @@ export async function runTrainCommand(args, autoConfig) {
                         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`);
+                        logger.info(`Removed ${stale.length} stale families`);
                     }
                 }
                 finally {
@@ -193,29 +201,41 @@ export async function runTrainCommand(args, autoConfig) {
         }
     }
     // ---------- Phase 4: LLM Enrichment ----------
+    let enrichTokens = 0;
+    let enrichCost = 0;
+    let enrichRequests = 0;
+    let enrichAvgResponseMs = 0;
     if (opts.enrich) {
-        console.log('');
-        console.log('  Enriching with LLM...');
+        logger.info('Enriching with LLM...');
+        const enrichTimer = logger.timer('enrich');
         try {
             const provider = await LLMProviderFactory.createFromEnv();
             const enrichResult = await enrichFamilies(mergeResult.manifest.families, scanResult.families, opts.appPath, provider, opts.budgetUSD, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined);
             mergeResult.manifest.families = enrichResult.enrichedFamilies;
-            console.log(`  Enriched ${enrichResult.enrichedFamilies.length} families (${enrichResult.tokensUsed} tokens, ~$${enrichResult.costUSD})`);
+            enrichTokens = enrichResult.tokensUsed;
+            enrichCost = enrichResult.costUSD;
+            enrichRequests = enrichResult.requestCount ?? 0;
+            enrichAvgResponseMs = enrichResult.avgResponseMs ?? 0;
+            logger.info(`Enriched ${enrichResult.enrichedFamilies.length} families`, {
+                tokens: enrichResult.tokensUsed,
+                cost: enrichResult.costUSD,
+                requests: enrichRequests,
+                avgResponseMs: enrichAvgResponseMs,
+            });
             if (enrichResult.skippedFamilies.length > 0) {
-                console.log(`  Skipped ${enrichResult.skippedFamilies.length} families (budget limit)`);
+                logger.info(`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.');
+            logger.warn(`LLM enrichment failed: ${error instanceof Error ? error.message : String(error)}`);
+            logger.warn('Continuing with deterministic results. Use --no-enrich to skip LLM.');
         }
+        timings.enrich = enrichTimer.end();
     }
     // ---------- Phase 5: Write manifest ----------
-    console.log('');
     const json = serializeManifest(mergeResult.manifest);
     if (opts.dryRun) {
-        console.log('  Dry run — proposed manifest:');
-        console.log('');
+        logger.info('Dry run — proposed manifest:');
         console.log(json);
     }
     else {
@@ -226,28 +246,42 @@ export async function runTrainCommand(args, autoConfig) {
         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`);
+        logger.info(`Wrote ${opts.outputPath}`);
+        logger.info(`${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):');
+        logger.info('Unmatched (review manually):');
         for (const dir of scanResult.unmatchedSourceDirs.slice(0, 10)) {
-            console.log(`    source: ${dir.relativePath}`);
+            logger.info(`  source: ${dir.relativePath}`);
         }
         for (const dir of scanResult.unmatchedTestDirs.slice(0, 10)) {
-            console.log(`    test:   ${dir.relativePath}`);
+            logger.info(`  test:   ${dir.relativePath}`);
         }
         if (scanResult.unmatchedSourceDirs.length + scanResult.unmatchedTestDirs.length > 20) {
-            console.log('    ... and more');
+            logger.info('  ... and more');
         }
     }
     // ---------- Phase 7: Validation (optional) ----------
+    let validationReport;
     if (opts.validate) {
+        const validateTimer = 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.debug('Validation path prefixes', { prefixes: pathPrefixes });
         if (opts.pr) {
-            console.log('');
-            console.log(`  Validating against PR #${opts.pr}...`);
+            logger.info(`Validating against PR #${opts.pr}...`);
             // Check for gh CLI
             const { execFileSync } = await import('child_process');
             try {
@@ -270,29 +304,57 @@ export async function runTrainCommand(args, autoConfig) {
                 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.');
+                logger.info('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));
+                const validation = validateCommit(mergeResult.manifest, prFiles, `PR#${opts.pr}`, `PR #${opts.pr}`, pathPrefixes);
+                validationReport = buildValidationReport([validation], mergeResult.manifest);
+                logger.info(formatValidationReport(validationReport));
             }
         }
         else {
-            console.log('');
-            console.log(`  Validating against git history (${opts.since})...`);
+            logger.info(`Validating against git history (${opts.since})...`);
             const commits = getCommitFiles(opts.gitRepoRoot || opts.appPath, opts.since);
             if (commits.length === 0) {
-                console.log('  No commits found in range.');
+                logger.info('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));
+                const validations = commits.map((c) => validateCommit(mergeResult.manifest, c.files, c.hash, c.message, pathPrefixes));
+                validationReport = buildValidationReport(validations, mergeResult.manifest);
+                logger.info(formatValidationReport(validationReport));
             }
         }
+        timings.validate = validateTimer.end();
+    }
+    timings.total = totalTimer.end();
+    // ---------- Write train report ----------
+    if (!opts.dryRun) {
+        const reportDir = dirname(opts.outputPath);
+        const trainReport = {
+            timestamp: new Date().toISOString(),
+            version: '1.7.0',
+            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 = join(reportDir, 'train-report.json');
+        writeFileSync(reportPath, JSON.stringify(trainReport, null, 2) + '\n', 'utf-8');
+        logger.debug('Wrote train report', { path: reportPath });
     }
-    console.log('');
+    logger.info('Done.');
 }

package/dist/esm/cli/parse_args.js

@@ -65,6 +65,8 @@ const FLAGS = {
     '--no-enrich': { key: 'trainEnrich', type: 'boolean-false' },
     '--validate': { key: 'trainValidate', type: 'boolean' },
     '--yes': { key: 'trainYes', type: 'boolean', aliases: ['-y'] },
+    '--verbose': { key: 'verbose', type: 'boolean', aliases: ['-v'] },
+    '--json': { key: 'jsonOutput', type: 'boolean' },
     '--mattermost': { key: 'profile', type: 'boolean', transform: () => 'mattermost' },
     // -- string flags --
     '--config': { key: 'configPath', type: 'string' },

package/dist/esm/knowledge/route_families.js

@@ -171,6 +171,7 @@ export function bindFilesToFamilies(changedFiles, manifest) {
                     const featurePatterns = [
                         ...(feature.webappPaths || []),
                         ...(feature.serverPaths || []),
+                        ...(feature.specDirs || []),
                     ];
                     if (featurePatterns.length > 0 && matchesAnyPattern(normalized, featurePatterns)) {
                         featureBindings.push({ family: family.id, feature: feature.id });
@@ -185,6 +186,8 @@ export function bindFilesToFamilies(changedFiles, manifest) {
             const familyPatterns = [
                 ...(family.webappPaths || []),
                 ...(family.serverPaths || []),
+                ...(family.specDirs || []),
+                ...(family.cypressSpecDirs || []),
             ];
             if (familyPatterns.length > 0 && matchesAnyPattern(normalized, familyPatterns)) {
                 bindings.push({ family: family.id });

package/dist/esm/logger.js

@@ -48,6 +48,7 @@ function logLevelToString(level) {
 export class Logger {
     constructor(minLevel) {
         this.level = minLevel ?? getLogLevelFromEnv();
+        this.jsonMode = process.env.LOG_FORMAT?.toLowerCase() === 'json';
     }
     error(message, context) {
         if (this.level >= LogLevel.ERROR) {
@@ -72,11 +73,37 @@ export class Logger {
     setLevel(level) {
         this.level = level;
     }
+    setJsonMode(enabled) {
+        this.jsonMode = enabled;
+    }
+    /**
+     * Start a timer for measuring duration of an operation.
+     * Returns an object with `end()` that logs at DEBUG level and returns elapsed ms.
+     */
+    timer(label) {
+        const start = performance.now();
+        return {
+            end: () => {
+                const elapsed = Math.round(performance.now() - start);
+                this.debug(`${label} completed`, { durationMs: elapsed });
+                return elapsed;
+            },
+        };
+    }
     log(level, message, context) {
         const timestamp = new Date().toISOString();
         const levelStr = logLevelToString(level);
-        const contextStr = context ? ` ${JSON.stringify(context)}` : '';
-        const output = `[${timestamp}] [${levelStr}] ${message}${contextStr}`;
+        let output;
+        if (this.jsonMode) {
+            const entry = { ts: timestamp, level: levelStr, msg: message };
+            if (context)
+                entry.ctx = context;
+            output = JSON.stringify(entry);
+        }
+        else {
+            const contextStr = context ? ` ${JSON.stringify(context)}` : '';
+            output = `[${timestamp}] [${levelStr}] ${message}${contextStr}`;
+        }
         if (level <= LogLevel.WARN) {
             console.error(output);
         }