@vibe-validate/cli 0.17.6 → 0.18.0-rc.1

package/dist/commands/watch-pr.js

@@ -1,33 +1,46 @@
+import { getCurrentBranch, getCurrentPR, getRemoteUrl, listPullRequests } from '@vibe-validate/git';
 import { stringify as stringifyYaml } from 'yaml';
-import { CIProviderRegistry } from '../services/ci-provider-registry.js';
+import { WatchPROrchestrator } from '../services/watch-pr-orchestrator.js';
+import { getCommandName } from '../utils/command-name.js';
 /**
  * Register the watch-pr command
  */
 export function registerWatchPRCommand(program) {
     program
         .command('watch-pr [pr-number]')
-        .description('Watch CI checks for a pull/merge request in real-time')
-        .option('--provider <name>', 'Force specific CI provider (github-actions, gitlab-ci)')
-        .option('--yaml', 'Output YAML only (no interactive display)')
-        .option('--timeout <seconds>', 'Maximum time to wait in seconds (default: 3600)', '3600')
+        .description('Monitor PR checks with auto-polling, error extraction, and flaky test detection (use after creating PR, run after each push)')
+        .option('--yaml', 'Force YAML output (auto-enabled on failure)')
+        .option('--repo <owner/repo>', 'Repository (default: auto-detect from git remote)')
+        .option('--history', 'Show historical runs for the PR with pass/fail summary')
+        .option('--run-id <id>', 'Watch specific run ID instead of latest (useful for testing failed runs)')
+        .option('--timeout <seconds>', 'Maximum polling time in seconds (default: 1800 = 30 min)', '1800')
         .option('--poll-interval <seconds>', 'Polling frequency in seconds (default: 10)', '10')
-        .option('--fail-fast', 'Exit immediately on first check failure')
+        .option('--fail-fast', 'Exit immediately on first check failure (no polling)')
         .action(async (prNumber, options) => {
         try {
             const exitCode = await watchPRCommand(prNumber, options);
             process.exit(exitCode);
         }
         catch (error) {
-            if (options.yaml) {
-                // YAML mode: Output error to stdout
+            // Only output YAML for PR failures, not for usage/argument errors
+            // Check if this is a usage error (no PR detected, invalid args, etc.)
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const isUsageError = errorMessage.includes('Could not auto-detect') ||
+                errorMessage.includes('Invalid PR number') ||
+                errorMessage.includes('Invalid run ID') ||
+                errorMessage.includes('Invalid --repo format') ||
+                errorMessage.includes('Could not detect repository');
+            if (isUsageError) {
+                // Output as plain text for better UX
+                process.stderr.write(`Error: ${errorMessage}\n`);
+            }
+            else {
+                // Actual PR/API errors - output as YAML for parseability
                 process.stdout.write('---\n');
                 process.stdout.write(stringifyYaml({
-                    error: error instanceof Error ? error.message : String(error),
+                    error: errorMessage,
                 }));
             }
-            else {
-                console.error('❌ Error:', error instanceof Error ? error.message : String(error));
-            }
             process.exit(1);
         }
     });
@@ -35,295 +48,464 @@ export function registerWatchPRCommand(program) {
 /**
  * Execute watch-pr command
  *
- * @returns Exit code (0 = success, 1 = failure, 2 = timeout)
+ * @returns Exit code (0 = success, 1 = failure)
  */
-async function watchPRCommand(prNumber, options) {
-    const registry = new CIProviderRegistry();
-    // Auto-detect or use specified provider
-    const provider = options.provider
-        ? registry.getProvider(options.provider)
-        : await registry.detectProvider();
-    if (!provider) {
-        const availableProviders = registry.getProviderNames().join(', ');
-        throw new Error(`No supported CI provider detected. Available: ${availableProviders}\n` +
-            'GitHub Actions requires: gh CLI installed and github.com remote');
+export async function watchPRCommand(prNumber, options) {
+    // Detect owner/repo from git remote or --repo flag (do this early for auto-detection)
+    const { owner, repo } = options.repo
+        ? parseRepoFlag(options.repo)
+        : detectOwnerRepo();
+    // Auto-detect PR number if not provided
+    let prNum;
+    if (prNumber) {
+        // Explicit PR number provided - parse and validate
+        prNum = Number.parseInt(prNumber, 10);
+        if (Number.isNaN(prNum) || prNum <= 0) {
+            throw new Error(`Invalid PR number: ${prNumber}`);
+        }
     }
-    // If no PR number, try to detect from current branch
-    let prId = prNumber;
-    if (!prId) {
-        const pr = await provider.detectPullRequest();
-        if (!pr) {
-            throw new Error('Could not detect PR from current branch.\n' +
-                'Usage: vibe-validate watch-pr <pr-number>');
+    else {
+        // No PR number - try to auto-detect from current branch
+        prNum = await autoDetectPR(owner, repo);
+    }
+    // Create orchestrator
+    const orchestrator = new WatchPROrchestrator(owner, repo);
+    // Handle --history flag (list historical runs)
+    if (options.history) {
+        await displayHistoricalRuns(orchestrator, prNum, options.yaml ?? false);
+        return 0; // Success exit code
+    }
+    // Handle --run-id mode (single fetch, no polling)
+    if (options.runId) {
+        const runId = Number.parseInt(options.runId, 10);
+        if (Number.isNaN(runId) || runId <= 0) {
+            throw new Error(`Invalid run ID: ${options.runId}. Must be a positive integer.`);
         }
-        prId = pr.id.toString();
+        const result = await orchestrator.buildResultForRun(prNum, runId, { useCache: true });
+        return displayFinalResult(result, orchestrator, options.yaml ?? false);
     }
-    // Watch the PR
-    return await watchPR(provider, prId, options);
+    // Normal mode: poll until complete (or timeout/fail-fast)
+    return await pollUntilComplete(orchestrator, prNum, options);
 }
 /**
- * Handle timeout scenario
+ * Display final result and return exit code
+ *
+ * @param result - Result to display
+ * @param orchestrator - WatchPROrchestrator instance
+ * @param yaml - Force YAML output
+ * @returns Exit code (0 = passed, 1 = failed)
  */
-function handleTimeout(lastStatus, elapsed, yaml) {
-    if (yaml && lastStatus) {
-        const result = {
-            pr: lastStatus.pr,
-            status: 'timeout',
-            result: 'unknown',
-            duration: formatDuration(elapsed),
-            summary: 'Timed out waiting for checks to complete',
-            checks: lastStatus.checks.map((c) => ({
-                name: c.name,
-                status: c.status,
-                conclusion: c.conclusion,
-                duration: c.duration,
-                url: c.url,
-            })),
-        };
-        // YAML mode: Output timeout result to stdout
+function displayFinalResult(result, orchestrator, yaml) {
+    const shouldYAML = orchestrator.shouldOutputYAML(result.status, yaml);
+    if (shouldYAML) {
         process.stdout.write('---\n');
         process.stdout.write(stringifyYaml(result));
     }
     else {
-        console.log('\n⏱️  Timeout reached. Checks still pending.');
+        displayHumanResult(result);
     }
-    return 2;
+    return result.status === 'passed' ? 0 : 1;
 }
 /**
- * Watch PR until completion or timeout
+ * Check if polling has timed out
+ *
+ * @param startTime - Polling start time
+ * @param timeoutMs - Timeout in milliseconds
+ * @param previousResult - Last result (for displaying on timeout)
+ * @returns Exit code (2) if timeout, null otherwise
  */
-async function watchPR(provider, prId, options) {
-    const timeoutMs = Number.parseInt(options.timeout ?? '3600') * 1000;
-    const pollIntervalMs = Number.parseInt(options.pollInterval ?? '10') * 1000;
+function checkTimeout(startTime, timeoutMs, previousResult) {
+    const elapsed = Date.now() - startTime;
+    if (elapsed >= timeoutMs) {
+        if (previousResult) {
+            process.stdout.write('\n⏱️  Timeout reached. Checks still pending.\n\n');
+            process.stdout.write('---\n');
+            process.stdout.write(stringifyYaml(previousResult));
+        }
+        return 2;
+    }
+    return null;
+}
+/**
+ * Check exit conditions (fail-fast or completion)
+ *
+ * @param result - Current result
+ * @param orchestrator - WatchPROrchestrator instance
+ * @param options - Command options
+ * @returns Exit code if should exit, null to continue polling
+ */
+function checkExitConditions(result, orchestrator, options) {
+    // Check if should fail fast
+    if (options.failFast && result.status === 'failed') {
+        process.stdout.write('\n⚡ Failing fast (--fail-fast enabled)\n\n');
+        process.stdout.write('---\n');
+        process.stdout.write(stringifyYaml(result));
+        return 1;
+    }
+    // Check if all checks are complete
+    if (result.status !== 'pending') {
+        process.stdout.write('\n');
+        return displayFinalResult(result, orchestrator, options.yaml ?? false);
+    }
+    return null; // Continue polling
+}
+/**
+ * Poll until PR checks complete (or timeout/fail-fast)
+ *
+ * @param orchestrator - WatchPROrchestrator instance
+ * @param prNumber - PR number
+ * @param options - Command options
+ * @returns Exit code
+ */
+async function pollUntilComplete(orchestrator, prNumber, options) {
+    const timeoutMs = Number.parseInt(options.timeout ?? '1800', 10) * 1000;
+    const pollIntervalMs = Number.parseInt(options.pollInterval ?? '10', 10) * 1000;
     const startTime = Date.now();
-    let lastStatus = null;
+    let previousResult = null;
     let iteration = 0;
     while (true) {
-        const elapsed = Date.now() - startTime;
         // Check timeout
-        if (elapsed >= timeoutMs) {
-            return handleTimeout(lastStatus, elapsed, options.yaml ?? false);
+        const timeoutCode = checkTimeout(startTime, timeoutMs, previousResult);
+        if (timeoutCode !== null) {
+            return timeoutCode;
         }
         // Fetch current status
-        const status = await provider.fetchCheckStatus(prId);
-        lastStatus = status;
-        // Display current status
-        if (!options.yaml) {
-            displayHumanStatus(status, iteration === 0);
+        const result = await orchestrator.buildResult(prNumber);
+        // Display changes (first iteration shows everything)
+        const changes = detectChanges(previousResult, result);
+        if (iteration === 0 || changes.length > 0) {
+            displayChanges(changes, result, iteration === 0);
         }
-        // Check if we should fail fast
-        const shouldFailFast = options.failFast && status.checks.some((c) => c.conclusion === 'failure');
-        if (shouldFailFast) {
-            return await handleCompletion(provider, status, options, elapsed);
-        }
-        // Check if all checks are complete
-        if (status.status === 'completed') {
-            return await handleCompletion(provider, status, options, elapsed);
-        }
-        // Wait before next poll
+        previousResult = result;
         iteration++;
+        // Check exit conditions (fail-fast or completion)
+        const exitCode = checkExitConditions(result, orchestrator, options);
+        if (exitCode !== null) {
+            return exitCode;
+        }
+        // Sleep before next poll
         await sleep(pollIntervalMs);
     }
 }
 /**
- * Handle completion - fetch failure details if needed and output result
+ * Auto-detect PR number from current branch
+ *
+ * Tries two approaches:
+ * 1. Use `gh pr view` (fast, but can fail in some scenarios)
+ * 2. Fall back to branch name matching (more reliable)
+ *
+ * @param owner - Repository owner
+ * @param repo - Repository name
+ * @returns PR number
  */
-async function handleCompletion(provider, status, options, elapsedMs) {
-    const failures = status.checks.filter((c) => c.conclusion === 'failure');
-    // Fetch detailed failure information
-    const failureDetails = await Promise.all(failures.map(async (check) => {
+async function autoDetectPR(owner, repo) {
+    try {
+        // Approach 1: Try gh pr view (fast path)
+        // Uses getCurrentPR from @vibe-validate/git (architectural compliance)
+        const prNumber = getCurrentPR(owner, repo);
+        if (prNumber !== null) {
+            return prNumber;
+        }
+        throw new Error('No PR number found');
+    }
+    catch {
+        // Approach 2: Fall back to branch name matching (Issue #5 fix)
+        // This handles cases where gh pr view fails (detached HEAD, etc.)
         try {
-            const logs = await provider.fetchFailureLogs(check.id);
-            return {
-                name: check.name,
-                checkId: check.id,
-                errorSummary: logs.errorSummary,
-                validationResult: logs.validationResult,
-                nextSteps: generateNextSteps(check.id, logs.validationResult),
-            };
+            // Get current branch name using getCurrentBranch from @vibe-validate/git
+            const currentBranch = getCurrentBranch();
+            if (!currentBranch || currentBranch === 'HEAD') {
+                throw new Error('Not on a branch (detached HEAD?)');
+            }
+            // Get all open PRs with branch names
+            const prsData = listPullRequests(owner, repo, 20, ['number', 'headRefName']);
+            // Find PR matching current branch
+            const matchingPR = prsData.find(pr => pr.headRefName === currentBranch);
+            if (matchingPR) {
+                return matchingPR.number;
+            }
+            throw new Error(`No PR found for branch: ${currentBranch}`);
         }
-        catch (error) {
-            return {
-                name: check.name,
-                checkId: check.id,
-                errorSummary: `Failed to fetch logs: ${error}`,
-                nextSteps: [`gh run view ${check.id} --log-failed`],
-            };
+        catch {
+            // Both approaches failed - show suggestions
+            const suggestions = await suggestOpenPRs(owner, repo);
+            const cmd = getCommandName();
+            throw new Error(`Could not auto-detect PR from current branch.\n\n` +
+                `${suggestions}\n\n` +
+                `Usage: ${cmd} watch-pr <pr-number>\n` +
+                `Example: ${cmd} watch-pr 90`);
         }
-    }));
-    // Output final result
-    if (options.yaml) {
-        const result = {
-            pr: {
-                id: status.pr.id,
-                title: status.pr.title,
-                url: status.pr.url,
-            },
-            status: status.status,
-            result: status.result,
-            duration: formatDuration(elapsedMs),
-            summary: `${status.checks.filter((c) => c.conclusion === 'success').length}/${status.checks.length} checks passed`,
-            checks: status.checks.map((c) => ({
-                name: c.name,
-                status: c.status,
-                conclusion: c.conclusion,
-                duration: c.duration,
-                url: c.url,
-            })),
-            failures: failureDetails.length > 0 ? failureDetails : undefined,
-        };
-        // YAML mode: Output completion result to stdout
-        process.stdout.write('---\n');
-        process.stdout.write(stringifyYaml(result));
     }
-    else {
-        displayHumanCompletion(status, failureDetails, elapsedMs);
+}
+/**
+ * Suggest open PRs to help user choose
+ *
+ * @param owner - Repository owner
+ * @param repo - Repository name
+ * @returns Formatted suggestion text
+ */
+async function suggestOpenPRs(owner, repo) {
+    try {
+        const prsData = listPullRequests(owner, repo, 5, ['number', 'title', 'author', 'headRefName']);
+        if (prsData.length === 0) {
+            return 'No open PRs found in this repository.';
+        }
+        const prList = prsData
+            .map((pr) => `  #${pr.number} - ${pr.title}\n` +
+            `         (${pr.headRefName} by ${pr.author.login})`)
+            .join('\n');
+        return `Open PRs in ${owner}/${repo}:\n${prList}`;
+    }
+    catch {
+        return 'Could not fetch open PRs.';
     }
-    // Return appropriate exit code
-    return status.result === 'success' ? 0 : 1;
 }
 /**
- * Display human-friendly status update
+ * Detect owner/repo from git remote
+ *
+ * @returns Owner and repo from GitHub remote
  */
-function displayHumanStatus(status, isFirst) {
-    if (isFirst) {
-        console.log(`🔍 Watching PR #${status.pr.id}: ${status.pr.title}`);
-        console.log(`   ${status.pr.url}\n`);
+function detectOwnerRepo() {
+    try {
+        // Use getRemoteUrl from @vibe-validate/git (architectural compliance)
+        const remote = getRemoteUrl('origin');
+        // Parse GitHub URL (supports HTTPS, SSH, and SSH with custom host aliases)
+        // HTTPS: https://github.com/owner/repo.git
+        // SSH: git@github.com:owner/repo.git
+        // SSH with alias: git@github.com-personal:owner/repo.git
+        // SSH with alias: git@github.com-work:owner/repo.git
+        const regex = /github\.com[^/:]*[/:]([\w-]+)\/([\w-]+)/;
+        const match = regex.exec(remote);
+        if (!match) {
+            throw new Error('Could not parse GitHub owner/repo from remote URL');
+        }
+        const owner = match[1];
+        const repo = match[2].replace(/\.git$/, '');
+        return { owner, repo };
     }
-    // Clear previous output (for live updating)
-    if (!isFirst) {
-        process.stdout.write('\x1B[2J\x1B[H'); // Clear screen and move cursor to top
-        console.log(`🔍 Watching PR #${status.pr.id}: ${status.pr.title}\n`);
+    catch {
+        // Error occurred - could not detect repo from git remote
+        throw new Error('Could not detect repository from git remote.\n' +
+            'Ensure you are in a git repository with a GitHub remote.\n' +
+            'Or specify --repo <owner/repo> explicitly.');
     }
-    // Display checks
-    for (const check of status.checks) {
-        const icon = getCheckIcon(check);
-        const statusStr = check.conclusion ?? check.status;
-        const duration = check.duration ?? '';
-        console.log(`${icon} ${check.name.padEnd(40)} ${statusStr.padEnd(12)} ${duration}`);
+}
+/**
+ * Parse --repo flag (owner/repo format)
+ *
+ * @param repoFlag - Repository in owner/repo format
+ * @returns Owner and repo
+ */
+function parseRepoFlag(repoFlag) {
+    const parts = repoFlag.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`Invalid --repo format: ${repoFlag}\n` +
+            'Expected format: --repo owner/repo\n' +
+            'Example: --repo jdutton/vibe-validate');
     }
-    // Display summary
-    const completed = status.checks.filter((c) => c.status === 'completed').length;
-    const total = status.checks.length;
-    const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
-    console.log(`\n${completed}/${total} checks complete (${percentage}%)`);
+    return { owner: parts[0], repo: parts[1] };
 }
 /**
- * Display human-friendly completion message
+ * Display historical runs for a PR
+ *
+ * @param orchestrator - WatchPROrchestrator instance
+ * @param prNumber - PR number
+ * @param yaml - Output in YAML format
  */
-// eslint-disable-next-line sonarjs/cognitive-complexity -- Complex display logic, documented technical debt
-function displayHumanCompletion(status, failures, elapsedMs) {
-    console.log('\n' + '='.repeat(60));
-    if (status.result === 'success') {
-        console.log('✅ All checks passed!');
-        console.log(`   Duration: ${formatDuration(elapsedMs)}`);
-        console.log(`   Ready to merge: ${status.pr.url}`);
+async function displayHistoricalRuns(orchestrator, prNumber, yaml) {
+    const runs = await orchestrator.fetchRunsForPR(prNumber);
+    if (runs.length === 0) {
+        console.log(`No workflow runs found for PR #${prNumber}`);
+        return;
+    }
+    if (yaml) {
+        // YAML output
+        process.stdout.write('---\n');
+        process.stdout.write(stringifyYaml({ runs }));
     }
     else {
-        console.log('❌ Some checks failed');
-        console.log(`   Duration: ${formatDuration(elapsedMs)}`);
-        for (const failure of failures) {
-            console.log(`\n📋 ${failure.name}:`);
-            if (failure.validationResult) {
-                const validationResult = failure.validationResult;
-                console.log(`   Failed step: ${validationResult.failedStep}`);
-                // Find the failed step to get command and extraction data
-                const failedStep = validationResult.phases
-                    ?.flatMap(phase => phase.steps ?? [])
-                    .find(step => step && step.name === validationResult.failedStep);
-                if (failedStep?.command) {
-                    console.log(`   Re-run locally: ${failedStep.command}`);
-                }
-                // Show extracted errors from failed step (v0.15.0+)
-                if (failedStep?.extraction?.errors && failedStep.extraction.errors.length > 0) {
-                    console.log(`\n   Failed tests/errors:`);
-                    for (const error of failedStep.extraction.errors.slice(0, 10)) {
-                        let location = 'Unknown location';
-                        if (error.file) {
-                            if (error.line) {
-                                const columnPart = error.column ? `:${error.column}` : '';
-                                location = `${error.file}:${error.line}${columnPart}`;
-                            }
-                            else {
-                                location = error.file;
-                            }
-                        }
-                        const message = error.message ?? 'Error';
-                        console.log(`   ❌ ${location} - ${message}`);
-                    }
-                    if (failedStep.extraction.errors.length > 10) {
-                        console.log(`   ... and ${failedStep.extraction.errors.length - 10} more`);
-                    }
-                }
-                else if (failedStep?.extraction?.summary) {
-                    // Show summary if no specific errors extracted
-                    console.log(`\n   Error summary: ${failedStep.extraction.summary}`);
-                }
+        // Human-friendly table
+        console.log(`\n📋 Workflow Runs for PR #${prNumber}\n`);
+        console.log('   RUN ID       CONCLUSION  DURATION  WORKFLOW                      STARTED');
+        console.log('   ' + '─'.repeat(95));
+        for (const run of runs) {
+            const runId = run.run_id.toString().padEnd(12);
+            const conclusion = (run.conclusion ?? 'pending').padEnd(11);
+            const duration = (run.duration ?? '?').padEnd(9);
+            const workflow = run.workflow_name.slice(0, 29).padEnd(29);
+            const startedAt = new Date(run.started_at).toLocaleString();
+            // Color code by conclusion
+            let icon = '⏳'; // pending
+            if (run.conclusion === 'success') {
+                icon = '✅';
             }
-            else if (failure.errorSummary) {
-                console.log(`   ${failure.errorSummary}`);
+            else if (run.conclusion === 'failure') {
+                icon = '❌';
+            }
+            console.log(`${icon}  ${runId} ${conclusion} ${duration} ${workflow} ${startedAt}`);
+        }
+        console.log('\n💡 Tip: Use --run-id <id> to drill into a specific run for extraction testing');
+        const cmd = getCommandName();
+        console.log(`   Example: ${cmd} watch-pr ${prNumber} --run-id ${runs[0].run_id}`);
+    }
+}
+/**
+ * Display human-friendly result
+ *
+ * @param result - WatchPRResult
+ */
+function displayHumanResult(result) {
+    console.log(`\n🔍 PR #${result.pr.number}: ${result.pr.title}`);
+    console.log(`   ${result.pr.url}\n`);
+    // Display checks
+    const allChecks = [...result.checks.github_actions, ...result.checks.external_checks];
+    for (const check of allChecks) {
+        const icon = getCheckIcon(check.conclusion);
+        const statusStr = check.conclusion ?? check.status;
+        console.log(`${icon} ${check.name.padEnd(40)} ${statusStr}`);
+    }
+    // Display summary
+    const failedSuffix = result.checks.failed > 0 ? ` (${result.checks.failed} failed)` : '';
+    console.log(`\n${result.checks.passed}/${result.checks.total} checks passed${failedSuffix}`);
+    // Display guidance
+    if (result.guidance) {
+        console.log(`\n${result.guidance.summary}`);
+        if (result.guidance.next_steps) {
+            console.log('\nNext steps:');
+            for (const step of result.guidance.next_steps) {
+                const icon = getStepIcon(step.severity);
+                console.log(`${icon} ${step.action}`);
+                if (step.reason) {
+                    console.log(`   ${step.reason}`);
+                }
             }
-            console.log(`\n   Next steps:`);
-            for (const step of failure.nextSteps)
-                console.log(`   - ${step}`);
         }
-        // Suggest reporting extractor issues if extraction quality is poor
-        console.log('\n💡 Error output unclear or missing details?');
-        console.log('   Help improve extraction: https://github.com/jdutton/vibe-validate/issues/new?template=extractor-improvement.yml');
     }
-    console.log('='.repeat(60));
 }
 /**
- * Get icon for check status
+ * Get icon for step severity
+ *
+ * @param severity - Step severity
+ * @returns Icon emoji
+ */
+function getStepIcon(severity) {
+    if (severity === 'error')
+        return '❌';
+    if (severity === 'warning')
+        return '⚠️';
+    return 'ℹ️';
+}
+/**
+ * Get icon for check conclusion
+ *
+ * @param conclusion - Check conclusion
+ * @returns Icon emoji
  */
-function getCheckIcon(check) {
-    if (check.conclusion === 'success')
+function getCheckIcon(conclusion) {
+    if (conclusion === 'success')
         return '✅';
-    if (check.conclusion === 'failure')
+    if (conclusion === 'failure')
         return '❌';
-    if (check.conclusion === 'cancelled')
+    if (conclusion === 'neutral')
+        return 'ℹ️';
+    if (conclusion === 'cancelled')
         return '🚫';
-    if (check.conclusion === 'skipped')
-        return '⏭️ ';
-    if (check.status === 'in_progress')
-        return '⏳';
-    return '⏸️ ';
+    if (conclusion === 'skipped')
+        return '⏭️';
+    if (conclusion === 'timed_out')
+        return '⏱️';
+    if (conclusion === 'action_required')
+        return '⚠️';
+    return '⏸️';
 }
 /**
- * Generate next steps for a failure
+ * Sleep for specified milliseconds
+ *
+ * @param ms - Milliseconds to sleep
  */
-function generateNextSteps(checkId, validationResult) {
-    const steps = [];
-    // Find the failed step's command (v0.15.0+: rerunCommand removed, use step.command)
-    if (validationResult) {
-        const failedStep = validationResult.phases
-            ?.flatMap(phase => phase.steps ?? [])
-            .find(step => step && step.name === validationResult.failedStep);
-        if (failedStep?.command) {
-            steps.push(`Run locally: ${failedStep.command}`);
-        }
-    }
-    steps.push(`View logs: gh run view ${checkId} --log-failed`);
-    steps.push(`Re-run check: gh run rerun ${checkId} --failed`);
-    return steps;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
- * Format duration in human-readable format
+ * Detect changes between two results
+ *
+ * @param previous - Previous result (null on first iteration)
+ * @param current - Current result
+ * @returns Array of check changes
  */
-function formatDuration(ms) {
-    const seconds = Math.floor(ms / 1000);
-    const minutes = Math.floor(seconds / 60);
-    const remainingSeconds = seconds % 60;
-    if (minutes > 0) {
-        return `${minutes}m ${remainingSeconds}s`;
+function detectChanges(previous, current) {
+    if (!previous) {
+        // First iteration - everything is a change
+        return [
+            ...current.checks.github_actions.map((c) => ({
+                name: c.name,
+                previousStatus: null,
+                newStatus: c.status,
+                conclusion: c.conclusion,
+            })),
+            ...current.checks.external_checks.map((c) => ({
+                name: c.name,
+                previousStatus: null,
+                newStatus: c.status,
+                conclusion: c.conclusion,
+            })),
+        ];
     }
-    return `${seconds}s`;
+    const changes = [];
+    // Build map of previous checks
+    const previousChecks = new Map();
+    for (const check of [...previous.checks.github_actions, ...previous.checks.external_checks]) {
+        previousChecks.set(check.name, { status: check.status, conclusion: check.conclusion });
+    }
+    // Compare current checks to previous
+    for (const check of [...current.checks.github_actions, ...current.checks.external_checks]) {
+        const prev = previousChecks.get(check.name);
+        if (!prev || prev.status !== check.status || prev.conclusion !== check.conclusion) {
+            changes.push({
+                name: check.name,
+                previousStatus: prev?.status ?? null,
+                newStatus: check.status,
+                conclusion: check.conclusion,
+            });
+        }
+    }
+    return changes;
 }
 /**
- * Sleep for specified milliseconds
+ * Display changes incrementally during polling
+ *
+ * @param changes - Array of check changes
+ * @param result - Current result
+ * @param isFirstIteration - Whether this is the first poll
  */
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function displayChanges(changes, result, isFirstIteration) {
+    if (isFirstIteration) {
+        // First iteration - show PR info and all checks
+        process.stdout.write(`\n🔍 Monitoring PR #${result.pr.number}: ${result.pr.title}\n`);
+        process.stdout.write(`   ${result.pr.url}\n\n`);
+    }
+    // Display each change
+    for (const change of changes) {
+        const icon = getCheckIcon(change.conclusion);
+        const statusStr = change.conclusion ?? change.newStatus;
+        if (change.previousStatus === null) {
+            // New check started
+            process.stdout.write(`${icon} ${change.name} - ${statusStr}\n`);
+        }
+        else if (change.newStatus === 'completed') {
+            // Check completed
+            process.stdout.write(`${icon} ${change.name} - ${statusStr}\n`);
+        }
+        else {
+            // Status changed
+            process.stdout.write(`${icon} ${change.name} - ${change.previousStatus} → ${statusStr}\n`);
+        }
+    }
+    // Show progress summary
+    const { passed, failed, pending } = result.checks;
+    if (changes.length > 0) {
+        process.stdout.write(`\n⏸️  ${pending} running, ${passed} passed, ${failed} failed\n`);
+    }
 }
 /**
  * Show verbose help with detailed documentation
@@ -331,142 +513,214 @@ function sleep(ms) {
 export function showWatchPRVerboseHelp() {
     console.log(`# watch-pr Command Reference
 
-> Watch CI checks for a pull/merge request in real-time
+> Monitor PR checks with auto-polling, error extraction, and flaky test detection
 
 ## Overview
 
-The \`watch-pr\` command monitors CI provider (GitHub Actions) check status in real-time after pushing to a PR. It provides live progress updates, extracts validation results from CI logs on failure, and provides actionable recovery commands. This is especially useful for AI agents waiting for CI completion.
+The \`watch-pr\` command monitors pull request CI checks with **automatic polling** until completion. It provides:
+- **Auto-polling**: Waits for checks to complete (no manual refresh)
+- **Error extraction**: Extracts file:line:message from failed GitHub Actions logs
+- **Flaky test detection**: Tracks history to identify unstable tests (e.g., "Failed last 2 runs", 60% success rate)
+- **External check summaries**: codecov coverage %, SonarCloud quality gates
+- **PR metadata**: branch, labels, linked issues, mergeable state
+- **File change context**: What files changed, insertions/deletions
+- **Intelligent guidance**: Severity-based next steps
+
+**YAML output is auto-enabled on failure** (consistent with validate command).
+
+## When to Use
+
+Use \`watch-pr\` after creating a PR and after each push:
+
+\`\`\`bash
+# Workflow:
+git push                    # Push commits to PR branch
+vibe-validate watch-pr 90   # Monitor CI (auto-polls until complete)
+# → Returns structured result when checks finish
+# → YAML output if failed (with extracted errors)
+# → Text output if passed (human-friendly)
+\`\`\`
+
+**Note**: PR must exist on GitHub (watch-pr fetches data from GitHub API).
 
 ## How It Works
 
-1. Detects PR from current branch (or uses provided PR number)
-2. Polls CI provider (GitHub Actions) for check status
-3. Shows real-time progress of all matrix jobs
-4. On failure: fetches logs and extracts vibe-validate state file
-5. Provides actionable recovery commands
-6. Exits when all checks complete or timeout reached
+1. **Fetches PR metadata** and check results from GitHub
+2. **Auto-polls** until checks complete (no manual refresh needed)
+3. **Classifies checks** (GitHub Actions vs external)
+4. **Extracts errors** from failed GitHub Actions logs (matrix + non-matrix mode)
+5. **Extracts summaries** from external checks (codecov, SonarCloud)
+6. **Builds history** (last 10 runs, success rate, patterns like "flaky")
+7. **Outputs YAML on failure**, text on success (unless --yaml forced)
 
 ## Options
 
-- \`--provider <name>\` - Force specific CI provider (github-actions, gitlab-ci)
-- \`--yaml\` - Output YAML only (no interactive display)
-- \`--timeout <seconds>\` - Maximum time to wait in seconds (default: 3600)
-- \`--poll-interval <seconds>\` - Polling frequency in seconds (default: 10)
-- \`--fail-fast\` - Exit immediately on first check failure
+- \`--yaml\` - Force YAML output (auto-enabled on failure)
+- \`--repo <owner/repo>\` - Repository (default: auto-detect from git remote)
+- \`--run-id <id>\` - Watch specific run ID instead of latest (useful for testing failed runs)
 
 ## Exit Codes
 
 - \`0\` - All checks passed
 - \`1\` - One or more checks failed
-- \`2\` - Timeout reached before completion
 
 ## Examples
 
 \`\`\`bash
-# Push to PR and watch
-git push origin my-branch
-vibe-validate watch-pr              # Auto-detect PR
-
-# Watch specific PR
-vibe-validate watch-pr 42
+# Watch PR (auto-detect repo from git remote)
+vibe-validate watch-pr 90
 
-# YAML output only
-vibe-validate watch-pr --yaml
+# Force YAML output (even on success)
+vibe-validate watch-pr 90 --yaml
 
-# Exit on first failure
-vibe-validate watch-pr --fail-fast
+# Watch PR in different repo
+vibe-validate watch-pr 42 --repo jdutton/vibe-validate
 
-# Custom timeout (10 minutes)
-vibe-validate watch-pr --timeout 600
+# Watch specific failed run (useful for testing extraction with failures)
+vibe-validate watch-pr 104 --run-id 19754182675 --repo jdutton/mcp-typescript-simple --yaml
 \`\`\`
 
-## Common Workflows
+## Output Format
+
+### YAML (auto on failure, or with --yaml)
+
+\`\`\`yaml
+pr:
+  number: 90
+  title: "Enhancement: Add watch-pr improvements"
+  branch: "feature/watch-pr"
+  mergeable: true
+  labels: ["enhancement"]
+  linked_issues:
+    - number: 42
+      title: "Improve watch-pr"
+
+status: failed
+
+checks:
+  total: 3
+  passed: 2
+  failed: 1
+  history_summary:
+    total_runs: 5
+    recent_pattern: "Failed last 2 runs"
+    success_rate: "60%"
+
+  github_actions:
+    - name: "Test"
+      conclusion: failure
+      run_id: 123
+      extraction:
+        errors:
+          - file: "test.ts"
+            line: 42
+            message: "Expected success"
+        summary: "1 test failure"
+        totalErrors: 1
+
+  external_checks:
+    - name: "codecov/patch"
+      conclusion: success
+      extracted:
+        summary: "Coverage: 85%"
+
+guidance:
+  status: failed
+  severity: error
+  summary: "1 check(s) failed"
+  next_steps:
+    - action: "Fix Test failure"
+      url: "https://github.com/.../runs/123"
+      severity: error
+\`\`\`
 
-### Standard workflow after pushing PR
+### Text (on success, unless --yaml)
 
-\`\`\`bash
-# Push changes
-git push origin feature/my-work
+\`\`\`
+🔍 PR #90: Enhancement: Add watch-pr improvements
+   https://github.com/jdutton/vibe-validate/pull/90
 
-# Create PR (if not exists)
-gh pr create
+✅ Test                                     success
+✅ Lint                                     success
+✅ codecov/patch                            success
 
-# Watch CI checks
-vibe-validate watch-pr
+3/3 checks passed
 
-# If passes: merge
-gh pr merge
+All checks passed
 
-# Cleanup
-vibe-validate cleanup
+Next steps:
+ℹ️ Ready to merge
 \`\`\`
 
-### CI dogfooding workflow (for vibe-validate developers)
+## Extraction Modes
 
-\`\`\`bash
-# Push changes
-git push origin my-branch
-
-# Watch with fail-fast (exit on first failure for quick feedback)
-vibe-validate watch-pr --fail-fast
+### Matrix Mode (vibe-validate repos)
 
-# If fails: view validation result from YAML
-vibe-validate watch-pr 42 --yaml | yq '.failures[0].validationResult'
+If check uses \`vv run\` or \`vv validate\`, YAML output is parsed and extraction passed through:
 
-# Fix errors and re-run
-gh run rerun <run-id> --failed
+\`\`\`yaml
+extraction:
+  errors:
+    - file: "test.ts"
+      line: 42
+  summary: "1 test failure"
+  totalErrors: 1
 \`\`\`
 
-### AI agent workflow
-
-\`\`\`bash
-# AI agent pushes code
-git push origin feature/ai-generated
-
-# AI agent watches PR (YAML mode for parsing)
-vibe-validate watch-pr --yaml --timeout 600
-
-# AI agent parses YAML result
-# - If passed: proceed with merge
-# - If failed: extract error details and fix
+### Non-Matrix Mode (other repos)
+
+For raw test output, extractors detect tool (vitest, jest, eslint) and extract errors:
+
+\`\`\`yaml
+extraction:
+  errors:
+    - file: "test.integration.test.ts"
+      line: 10
+      message: "Connection refused"
+  summary: "2 test failures"
+  totalErrors: 2
+  metadata:
+    detection:
+      extractor: vitest
 \`\`\`
 
-## Error Recovery
+## Common Workflows
 
-### If check fails
+### Standard PR workflow
 
-**View validation result from YAML output:**
 \`\`\`bash
-# View validation result from YAML output
-vibe-validate watch-pr 42 --yaml | yq '.failures[0].validationResult'
+# Check PR status
+vibe-validate watch-pr 90
+
+# If failed, view extraction
+vibe-validate watch-pr 90 --yaml | yq '.checks.github_actions[0].extraction'
 
 # Re-run failed check
 gh run rerun <run-id> --failed
 \`\`\`
 
-### If no PR found
+### AI agent workflow
 
-**Create PR first:**
 \`\`\`bash
-# Create PR first
-gh pr create
+# AI agent checks PR (always YAML for parsing)
+vibe-validate watch-pr 90 --yaml
 
-# Or specify PR number explicitly
-vibe-validate watch-pr 42
+# Parse result
+# - If passed: proceed with merge
+# - If failed: extract errors and fix
 \`\`\`
 
-## CI Provider Support
+## Caching
 
-### GitHub Actions (default)
-
-- **Requirements**: \`gh\` CLI installed and github.com remote
-- **Auto-detection**: Checks for .github/workflows and github.com remote
-- **Features**: Matrix job support, log extraction, vibe-validate state parsing
-
-### GitLab CI (planned)
+Results are cached locally (5 minute TTL):
+\`\`\`
+/tmp/vibe-validate/watch-pr-cache/<repo>/<pr-number>/
+  metadata.json       # Complete WatchPRResult
+  logs/<run-id>.log   # Raw logs from GitHub Actions
+  extractions/        # Extracted errors
+\`\`\`
 
-- **Status**: Not yet implemented
-- **Tracking**: https://github.com/jdutton/vibe-validate/issues
+Cache location is included in YAML output (\`cache.location\` field).
 `);
 }
 //# sourceMappingURL=watch-pr.js.map