@yasserkhanorg/e2e-agents 1.3.2 → 1.5.0

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

@@ -8,6 +8,7 @@ export function createExplorationState(flows, timeLimitMs, budgetUSD) {
         flowsExplored: [],
         currentFlow: null,
         findings: [],
+        findingDedupIndex: {},
         actionsLog: [],
         recentActions: [],
         tokensUsed: 0,
@@ -24,7 +25,27 @@ export function recordAction(state, action) {
         state.recentActions.shift();
     }
 }
+/**
+ * Hash a finding on (type + severity + normalizedSummary + urlPattern) for dedup.
+ */
+function findingDedupKey(finding) {
+    // Normalize: lowercase, collapse whitespace, strip trailing punctuation
+    const normalizedSummary = finding.summary.toLowerCase().replace(/\s+/g, ' ').replace(/[.!?]+$/, '').trim();
+    // Extract URL pattern: strip query params and hash, replace path segments that look like IDs
+    const urlPattern = finding.evidence.url
+        .replace(/[?#].*$/, '')
+        .replace(/\/[a-z0-9]{20,}/gi, '/{id}')
+        .replace(/\/\d{2,}/g, '/{id}');
+    return `${finding.type}|${finding.severity}|${normalizedSummary}|${urlPattern}`;
+}
 export function recordFinding(state, finding) {
+    const key = findingDedupKey(finding);
+    const existingIdx = state.findingDedupIndex[key];
+    if (existingIdx !== undefined && existingIdx < state.findings.length) {
+        state.findings[existingIdx].duplicateCount = (state.findings[existingIdx].duplicateCount || 1) + 1;
+        return;
+    }
+    state.findingDedupIndex[key] = state.findings.length;
     state.findings.push(finding);
 }
 export function markFlowExplored(state, flowId) {

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

@@ -94,7 +94,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'report_finding',
-        description: 'Report a bug, visual issue, UX problem, or gap you discovered. Always include current URL and repro steps.',
+        description: 'Report a bug, visual issue, UX problem, or gap you discovered. Include expected/actual behavior and repro steps. Take before/after screenshots before calling this.',
         input_schema: {
             type: 'object',
             properties: {
@@ -106,6 +106,13 @@ export const TOOL_DEFINITIONS = [
                     items: { type: 'string' },
                     description: 'Steps to reproduce',
                 },
+                screenshot_refs: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Paths to before/after screenshots (from take_screenshot)',
+                },
+                expected_behavior: { type: 'string', description: 'What should have happened' },
+                actual_behavior: { type: 'string', description: 'What actually happened' },
             },
             required: ['type', 'severity', 'summary', 'repro_steps'],
         },
@@ -133,6 +140,23 @@ export const TOOL_DEFINITIONS = [
             required: ['role'],
         },
     },
+    {
+        name: 'wait_for',
+        description: 'Wait for an element condition or page state. Use after actions that trigger async changes (navigation, API calls, animations).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                condition: {
+                    type: 'string',
+                    enum: ['visible', 'hidden', 'stable', 'networkidle'],
+                    description: 'What to wait for: visible/hidden (element state), stable (no DOM changes for 1s), networkidle (no pending requests)',
+                },
+                ref: { type: 'string', description: 'Accessibility ref for element conditions (visible/hidden). Not needed for stable/networkidle.' },
+                timeout_ms: { type: 'number', description: 'Max wait time in ms (default 5000, max 15000)' },
+            },
+            required: ['condition'],
+        },
+    },
 ];
 export function executeTool(ctx, name, input) {
     switch (name) {
@@ -204,6 +228,36 @@ export function executeTool(ctx, name, input) {
             if (!Array.isArray(input.repro_steps)) {
                 return { output: `Invalid repro_steps: expected an array of strings.` };
             }
+            // Auto-capture console errors at time of finding
+            let autoConsoleErrors;
+            try {
+                const raw = ctx.browser.evaluateInternal('JSON.stringify(window.__consoleErrors || [])');
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed) && parsed.length > 0) {
+                    autoConsoleErrors = parsed.map(String).slice(-10);
+                }
+            }
+            catch {
+                // Console error capture not available
+            }
+            // Auto-take screenshot if none provided
+            let autoScreenshot;
+            const screenshotRefs = Array.isArray(input.screenshot_refs)
+                ? input.screenshot_refs.map(String)
+                : undefined;
+            if (!screenshotRefs || screenshotRefs.length === 0) {
+                try {
+                    const nextCount = ctx.screenshotCounter + 1;
+                    const filename = `${String(nextCount).padStart(3, '0')}-finding-auto.png`;
+                    const screenshotPath = `${ctx.screenshotDir}/${filename}`;
+                    ctx.browser.screenshot(screenshotPath);
+                    ctx.screenshotCounter = nextCount;
+                    autoScreenshot = screenshotPath;
+                }
+                catch {
+                    autoScreenshot = undefined;
+                }
+            }
             const finding = {
                 id: `f-${crypto.randomUUID()}`,
                 type: rawType,
@@ -213,6 +267,11 @@ export function executeTool(ctx, name, input) {
                 evidence: {
                     url: ctx.currentUrl,
                     reproSteps: input.repro_steps.map(String),
+                    screenshotRefs: screenshotRefs || (autoScreenshot ? [autoScreenshot] : undefined),
+                    screenshotPath: autoScreenshot || (screenshotRefs ? screenshotRefs[0] : undefined),
+                    consoleErrors: autoConsoleErrors,
+                    expectedBehavior: input.expected_behavior ? String(input.expected_behavior) : undefined,
+                    actualBehavior: input.actual_behavior ? String(input.actual_behavior) : undefined,
                 },
                 timestamp: Date.now(),
             };
@@ -229,6 +288,45 @@ export function executeTool(ctx, name, input) {
                 flowDone: { flowId, status: rawStatus },
             };
         }
+        case 'wait_for': {
+            const condition = String(input.condition || '');
+            const VALID_CONDITIONS = new Set(['visible', 'hidden', 'stable', 'networkidle']);
+            if (!VALID_CONDITIONS.has(condition)) {
+                return { output: `Invalid condition "${condition}". Must be one of: ${[...VALID_CONDITIONS].join(', ')}.` };
+            }
+            const timeoutMs = Math.min(Math.max(Number(input.timeout_ms) || 5000, 500), 15000);
+            try {
+                if (condition === 'stable' || condition === 'networkidle') {
+                    const waitMs = condition === 'networkidle' ? Math.min(timeoutMs, 3000) : 1000;
+                    ctx.browser.evaluateInternal(`new Promise(r => setTimeout(r, ${waitMs}))`);
+                    return { output: `Waited ${waitMs}ms for ${condition} (heuristic delay)` };
+                }
+                // Element-level wait: poll snapshot for ref presence/absence
+                const ref = input.ref ? String(input.ref) : undefined;
+                if (!ref) {
+                    return { output: `Element condition "${condition}" requires a ref parameter.` };
+                }
+                const start = Date.now();
+                const wantVisible = condition === 'visible';
+                // Use word-boundary regex to avoid false positives (@e1 matching @e10)
+                const refPattern = new RegExp(`(?<![\\w@])${ref.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w])`);
+                const pollIntervalMs = 300;
+                while (Date.now() - start < timeoutMs) {
+                    const snap = ctx.browser.snapshot();
+                    const found = refPattern.test(snap);
+                    if ((wantVisible && found) || (!wantVisible && !found)) {
+                        return { output: `Element ${ref} is now ${condition} (took ${Date.now() - start}ms)` };
+                    }
+                    // Synchronous in-process sleep via Atomics.wait (available in Node.js 8.10+)
+                    const buf = new SharedArrayBuffer(4);
+                    Atomics.wait(new Int32Array(buf), 0, 0, pollIntervalMs);
+                }
+                return { output: `Timeout: element ${ref} did not become ${condition} within ${timeoutMs}ms` };
+            }
+            catch (err) {
+                return { output: `wait_for error: ${String(err)}` };
+            }
+        }
         case 'switch_user': {
             const role = String(input.role);
             const user = ctx.users?.find((u) => u.role === role);

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

@@ -80,16 +80,43 @@ function renderMarkdown(report) {
     if (report.phase2.findings.length > 0) {
         lines.push(`## Findings`, '');
         for (const f of report.phase2.findings) {
-            lines.push(`### [${f.severity.toUpperCase()}] ${f.summary}`);
+            const dupNote = f.duplicateCount && f.duplicateCount > 1
+                ? ` (seen ${f.duplicateCount} times)`
+                : '';
+            lines.push(`### [${f.severity.toUpperCase()}] ${f.summary}${dupNote}`);
             lines.push('');
             lines.push(`- **Type:** ${f.type}`);
             lines.push(`- **Flow:** ${f.flow}`);
             lines.push(`- **URL:** ${f.evidence.url}`);
-            if (f.evidence.screenshotPath) {
-                lines.push(`- **Screenshot:** ${f.evidence.screenshotPath}`);
+            // Expected vs actual behavior
+            if (f.evidence.expectedBehavior || f.evidence.actualBehavior) {
+                const escapePipe = (s) => s.replace(/\|/g, '\\|');
+                lines.push('');
+                lines.push(`| Expected | Actual |`);
+                lines.push(`|----------|--------|`);
+                lines.push(`| ${escapePipe(f.evidence.expectedBehavior || '—')} | ${escapePipe(f.evidence.actualBehavior || '—')} |`);
+                lines.push('');
+            }
+            // Screenshot evidence (inline images)
+            if (f.evidence.screenshotRefs && f.evidence.screenshotRefs.length > 0) {
+                for (const ref of f.evidence.screenshotRefs) {
+                    lines.push(`![Evidence](${ref})`);
+                }
+            }
+            else if (f.evidence.screenshotPath) {
+                lines.push(`![Evidence](${f.evidence.screenshotPath})`);
+            }
+            // Console errors
+            if (f.evidence.consoleErrors && f.evidence.consoleErrors.length > 0) {
+                lines.push('');
+                lines.push('**Console errors:**');
+                for (const err of f.evidence.consoleErrors.slice(0, 5)) {
+                    lines.push(`- \`${err.replace(/`/g, '\\`')}\``);
+                }
             }
             if (f.evidence.reproSteps.length > 0) {
-                lines.push('- **Repro steps:**');
+                lines.push('');
+                lines.push('**Repro steps:**');
                 for (const step of f.evidence.reproSteps) {
                     lines.push(`  1. ${step}`);
                 }

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,
+    };
+}

package/dist/esm/training/merger.js

@@ -0,0 +1,137 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { isGuessedRoute } from './types.js';
+function unionArrays(existing, incoming) {
+    const set = new Set(existing || []);
+    for (const item of incoming) {
+        set.add(item);
+    }
+    return Array.from(set);
+}
+function mergeFamily(existing, scanned) {
+    const merged = { ...existing };
+    // Structural fields: union arrays
+    merged.webappPaths = unionArrays(existing.webappPaths, scanned.webappPaths);
+    merged.serverPaths = unionArrays(existing.serverPaths, scanned.serverPaths);
+    merged.specDirs = unionArrays(existing.specDirs, scanned.specDirs);
+    merged.cypressSpecDirs = unionArrays(existing.cypressSpecDirs, scanned.cypressSpecDirs);
+    merged.tags = unionArrays(existing.tags, scanned.tags);
+    // Routes: only update if existing looks like a guess
+    if (isGuessedRoute(existing.routes) && !isGuessedRoute(scanned.routes)) {
+        merged.routes = scanned.routes;
+    }
+    // Human-curated fields: never overwrite (priority, userFlows, pageObjects, components)
+    // Merge features
+    if (scanned.features.length > 0) {
+        const existingFeatures = existing.features || [];
+        const existingIds = new Set(existingFeatures.map((f) => f.id));
+        const newFeatures = scanned.features.filter((f) => !existingIds.has(f.id));
+        if (newFeatures.length > 0) {
+            merged.features = [
+                ...existingFeatures,
+                ...newFeatures.map((f) => ({
+                    id: f.id,
+                    webappPaths: f.webappPaths,
+                    serverPaths: f.serverPaths,
+                    specDirs: f.specDirs,
+                })),
+            ];
+        }
+    }
+    return merged;
+}
+function scannedToRouteFamily(scanned) {
+    const family = {
+        id: scanned.id,
+        routes: scanned.routes,
+    };
+    if (scanned.webappPaths.length > 0)
+        family.webappPaths = scanned.webappPaths;
+    if (scanned.serverPaths.length > 0)
+        family.serverPaths = scanned.serverPaths;
+    if (scanned.specDirs.length > 0)
+        family.specDirs = scanned.specDirs;
+    if (scanned.cypressSpecDirs.length > 0)
+        family.cypressSpecDirs = scanned.cypressSpecDirs;
+    if (scanned.tags.length > 0)
+        family.tags = scanned.tags;
+    if (scanned.features.length > 0) {
+        family.features = scanned.features.map((f) => ({
+            id: f.id,
+            webappPaths: f.webappPaths.length > 0 ? f.webappPaths : undefined,
+            serverPaths: f.serverPaths.length > 0 ? f.serverPaths : undefined,
+            specDirs: f.specDirs.length > 0 ? f.specDirs : undefined,
+        }));
+    }
+    return family;
+}
+export function mergeFamilies(existing, scanned) {
+    const existingFamilies = existing?.families || [];
+    const existingMap = new Map(existingFamilies.map((f) => [f.id, f]));
+    const scannedMap = new Map(scanned.map((f) => [f.id, f]));
+    const newFamilies = [];
+    const updatedFamilies = [];
+    const mergedFamilies = [];
+    // Process existing families
+    for (const ef of existingFamilies) {
+        const sf = scannedMap.get(ef.id);
+        if (sf) {
+            mergedFamilies.push(mergeFamily(ef, sf));
+            updatedFamilies.push(ef.id);
+        }
+        else {
+            // Keep untouched
+            mergedFamilies.push({ ...ef });
+        }
+    }
+    // Add new families from scanner
+    for (const sf of scanned) {
+        if (!existingMap.has(sf.id)) {
+            mergedFamilies.push(scannedToRouteFamily(sf));
+            newFamilies.push(sf.id);
+        }
+    }
+    const parts = [];
+    if (updatedFamilies.length > 0)
+        parts.push(`${updatedFamilies.length} families updated`);
+    if (newFamilies.length > 0)
+        parts.push(`${newFamilies.length} new families added`);
+    if (parts.length === 0)
+        parts.push('no changes');
+    return {
+        manifest: { families: mergedFamilies, source: existing?.source || 'train-scan' },
+        newFamilies,
+        updatedFamilies,
+        staleFamilies: [],
+        summary: parts.join(', '),
+    };
+}
+export function detectStaleFamilies(manifest, projectRoot) {
+    const resolved = resolve(projectRoot);
+    const stale = [];
+    for (const family of manifest.families) {
+        const allPatterns = [
+            ...(family.webappPaths || []),
+            ...(family.serverPaths || []),
+            ...(family.specDirs || []),
+        ];
+        if (allPatterns.length === 0)
+            continue;
+        // Check if any pattern resolves to existing files/dirs
+        let hasAny = false;
+        for (const pattern of allPatterns) {
+            // Strip trailing glob (* or **) to get the directory
+            const dirPart = pattern.replace(/\/?\*.*$/, '');
+            if (dirPart && existsSync(join(resolved, dirPart))) {
+                hasAny = true;
+                break;
+            }
+        }
+        if (!hasAny) {
+            stale.push(family.id);
+        }
+    }
+    return stale;
+}