wiggum-cli 0.15.0 → 0.17.0

package/dist/commands/monitor.js

@@ -2,11 +2,12 @@
  * Monitor Command
  * Display real-time status of a feature loop
  */
-import { spawn, execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { logger } from '../utils/logger.js';
 import { loadConfigWithDefaults } from '../utils/config.js';
+import { readLoopStatus, parseImplementationPlan, getGitBranch, formatNumber, } from '../tui/utils/loop-status.js';
 import pc from 'picocolors';
 /**
  * Find the ralph-monitor.sh script
@@ -29,162 +30,6 @@ function findMonitorScript(projectRoot) {
     }
     return null;
 }
-/**
- * Check if a process matching pattern is running
- * Uses pgrep with -f flag for full command line matching
- */
-function isProcessRunning(pattern) {
-    try {
-        // Use execFileSync for safer execution
-        const result = execFileSync('pgrep', ['-f', pattern], { encoding: 'utf-8' });
-        return result.trim().length > 0;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Detect current phase of the loop
- */
-function detectPhase(feature) {
-    if (isProcessRunning('PROMPT_feature.md'))
-        return 'Planning';
-    if (isProcessRunning('PROMPT_e2e.md'))
-        return 'E2E Testing';
-    if (isProcessRunning('PROMPT_verify.md'))
-        return 'Verification';
-    if (isProcessRunning('PROMPT_review_manual.md'))
-        return 'PR Review';
-    if (isProcessRunning('PROMPT_review_auto.md'))
-        return 'PR Review';
-    if (isProcessRunning('PROMPT.md'))
-        return 'Implementation';
-    if (isProcessRunning(`feature-loop.sh.*${feature}`))
-        return 'Running';
-    return 'Idle';
-}
-/**
- * Read status from temp files
- */
-function readStatus(feature) {
-    const statusFile = `/tmp/ralph-loop-${feature}.status`;
-    const tokensFile = `/tmp/ralph-loop-${feature}.tokens`;
-    let iteration = 0;
-    let maxIterations = 50;
-    // Read status file
-    if (existsSync(statusFile)) {
-        try {
-            const content = readFileSync(statusFile, 'utf-8').trim();
-            const parts = content.split('|');
-            iteration = parseInt(parts[0]) || 0;
-            maxIterations = parseInt(parts[1]) || 50;
-        }
-        catch {
-            // Ignore errors
-        }
-    }
-    // Read tokens file
-    let tokensInput = 0;
-    let tokensOutput = 0;
-    if (existsSync(tokensFile)) {
-        try {
-            const content = readFileSync(tokensFile, 'utf-8').trim();
-            const parts = content.split('|');
-            tokensInput = parseInt(parts[0]) || 0;
-            tokensOutput = parseInt(parts[1]) || 0;
-        }
-        catch {
-            // Ignore errors
-        }
-    }
-    return {
-        running: isProcessRunning(`feature-loop.sh.*${feature}`),
-        phase: detectPhase(feature),
-        iteration,
-        maxIterations,
-        tokensInput,
-        tokensOutput,
-        tasksDone: 0,
-        tasksPending: 0,
-        e2eDone: 0,
-        e2ePending: 0,
-        branch: '',
-        elapsed: '',
-    };
-}
-/**
- * Parse implementation plan for task counts
- */
-async function parseImplementationPlan(projectRoot, feature) {
-    const config = await loadConfigWithDefaults(projectRoot);
-    const planPath = join(projectRoot, config.paths.specs, `${feature}-implementation-plan.md`);
-    let tasksDone = 0;
-    let tasksPending = 0;
-    let e2eDone = 0;
-    let e2ePending = 0;
-    if (existsSync(planPath)) {
-        try {
-            const content = readFileSync(planPath, 'utf-8');
-            const lines = content.split('\n');
-            for (const line of lines) {
-                if (line.match(/^- \[x\]/)) {
-                    if (line.includes('E2E:')) {
-                        e2eDone++;
-                    }
-                    else {
-                        tasksDone++;
-                    }
-                }
-                else if (line.match(/^- \[ \]/)) {
-                    if (line.includes('E2E:')) {
-                        e2ePending++;
-                    }
-                    else {
-                        tasksPending++;
-                    }
-                }
-            }
-        }
-        catch {
-            // Ignore errors
-        }
-    }
-    return { tasksDone, tasksPending, e2eDone, e2ePending };
-}
-/**
- * Get current git branch
- */
-function getGitBranch(projectRoot) {
-    try {
-        // Try app directory first
-        const appDir = join(projectRoot, '..', 'app');
-        if (existsSync(appDir)) {
-            return execFileSync('git', ['branch', '--show-current'], {
-                cwd: appDir,
-                encoding: 'utf-8',
-            }).trim();
-        }
-        return execFileSync('git', ['branch', '--show-current'], {
-            cwd: projectRoot,
-            encoding: 'utf-8',
-        }).trim();
-    }
-    catch {
-        return '-';
-    }
-}
-/**
- * Format number with K/M suffix
- */
-function formatNumber(num) {
-    if (num >= 1000000) {
-        return (num / 1000000).toFixed(1) + 'M';
-    }
-    if (num >= 1000) {
-        return (num / 1000).toFixed(1) + 'K';
-    }
-    return String(num);
-}
 /**
  * Create a progress bar
  */
@@ -196,9 +41,9 @@ function progressBar(percent, width = 15) {
 /**
  * Display built-in monitor dashboard
  */
-async function displayDashboard(feature, projectRoot, interval = 5) {
-    const status = readStatus(feature);
-    const tasks = await parseImplementationPlan(projectRoot, feature);
+async function displayDashboard(feature, projectRoot, specsDir, interval = 5) {
+    const status = readLoopStatus(feature);
+    const tasks = await parseImplementationPlan(projectRoot, feature, specsDir);
     const branch = getGitBranch(projectRoot);
     // Calculate progress
     const totalTasks = tasks.tasksDone + tasks.tasksPending;
@@ -233,14 +78,28 @@ async function displayDashboard(feature, projectRoot, interval = 5) {
     console.log(`  Phase: ${phaseColor(pc.bold(status.phase))}` +
         `  |  Iter: ${pc.bold(String(status.iteration))}/${pc.dim(String(status.maxIterations))}` +
         `  |  Branch: ${pc.cyan(branch)}`);
-    const totalTokens = status.tokensInput + status.tokensOutput;
+    const totalTokens = status.tokensInput + status.tokensOutput + status.cacheCreate + status.cacheRead;
+    let tokensSuffix = '';
+    if (status.tokensUpdatedAt) {
+        const agoMs = Date.now() - status.tokensUpdatedAt;
+        const agoSec = Math.floor(agoMs / 1000);
+        if (agoSec >= 60) {
+            tokensSuffix = pc.dim(` updated ${Math.floor(agoSec / 60)}m ago`);
+        }
+    }
     console.log(`  Tokens: ${pc.magenta(formatNumber(totalTokens))}` +
-        pc.dim(` (in:${formatNumber(status.tokensInput)} out:${formatNumber(status.tokensOutput)})`));
+        pc.dim(` (in:${formatNumber(status.tokensInput)} out:${formatNumber(status.tokensOutput)} cache:${formatNumber(status.cacheRead)})`) +
+        tokensSuffix);
     console.log(pc.dim('  ' + '-'.repeat(74)));
     // Progress
     console.log('');
-    console.log(`  ${pc.bold('Implementation:')} ${progressBar(percentTasks)} ${pc.bold(percentTasks + '%')}` +
-        `  ${pc.green('\u2713 ' + tasks.tasksDone)} / ${pc.yellow('\u25cb ' + tasks.tasksPending)}`);
+    if (!tasks.planExists && status.running) {
+        console.log(`  ${pc.bold('Implementation:')} ${pc.dim('[waiting for plan...]')}`);
+    }
+    else {
+        console.log(`  ${pc.bold('Implementation:')} ${progressBar(percentTasks)} ${pc.bold(percentTasks + '%')}` +
+            `  ${pc.green('\u2713 ' + tasks.tasksDone)} / ${pc.yellow('\u25cb ' + tasks.tasksPending)}`);
+    }
     if (totalE2e > 0) {
         console.log(`  ${pc.bold('E2E Tests:     ')} ${progressBar(percentE2e)} ${pc.bold(percentE2e + '%')}` +
             `  ${pc.green('\u2713 ' + tasks.e2eDone)} / ${pc.yellow('\u25cb ' + tasks.e2ePending)}`);
@@ -305,12 +164,21 @@ export async function monitorCommand(feature, options = {}) {
         logger.warn('Python TUI monitor not yet implemented');
         logger.info('Using built-in monitor instead');
     }
-    // Built-in monitor
+    // Load config for correct specs path
+    let specsDir = '.ralph/specs';
+    try {
+        const config = await loadConfigWithDefaults(projectRoot);
+        specsDir = config.paths.specs;
+    }
+    catch (err) {
+        logger.debug(`Failed to load config: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Built-in monitor with sequential polling
     const intervalSeconds = options.interval || 5;
     const intervalMs = intervalSeconds * 1000;
     // Initial display
     try {
-        await displayDashboard(feature, projectRoot, intervalSeconds);
+        await displayDashboard(feature, projectRoot, specsDir, intervalSeconds);
     }
     catch (error) {
         logger.error(`Failed to display dashboard: ${error instanceof Error ? error.message : String(error)}`);
@@ -319,25 +187,24 @@ export async function monitorCommand(feature, options = {}) {
         }
         process.exit(1);
     }
-    // Refresh loop
-    const refreshTimer = setInterval(async () => {
+    // Sequential refresh loop (prevents overlapping refreshes)
+    let running = true;
+    const cleanup = () => {
+        running = false;
+        console.log('');
+        logger.info('Monitor stopped');
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    while (running) {
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        if (!running)
+            break;
         try {
-            await displayDashboard(feature, projectRoot, intervalSeconds);
+            await displayDashboard(feature, projectRoot, specsDir, intervalSeconds);
         }
         catch (error) {
-            // Log error but continue monitoring
             logger.debug(`Dashboard refresh error: ${error instanceof Error ? error.message : String(error)}`);
         }
-    }, intervalMs);
-    // Return a Promise that resolves on SIGINT
-    return new Promise((resolve) => {
-        const cleanup = () => {
-            clearInterval(refreshTimer);
-            console.log('');
-            logger.info('Monitor stopped');
-            resolve();
-        };
-        process.on('SIGINT', cleanup);
-        process.on('SIGTERM', cleanup);
-    });
+    }
 }

package/dist/commands/new-auto.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Headless Autonomous Spec Generation
+ * Drives InterviewOrchestrator without the Ink TUI for non-interactive use.
+ * Used by AI agents (e.g. OpenClaw orchestrator) to generate feature specs.
+ */
+import type { AIProvider } from '../ai/providers.js';
+export interface NewAutoOptions {
+    goals?: string;
+    initialReferences?: string[];
+    model?: string;
+    provider?: AIProvider;
+    /** Timeout in ms for spec generation (default: 5 minutes) */
+    timeoutMs?: number;
+}
+export declare function newAutoCommand(featureName: string, options?: NewAutoOptions): Promise<void>;

package/dist/commands/new-auto.js

@@ -0,0 +1,237 @@
+/**
+ * Headless Autonomous Spec Generation
+ * Drives InterviewOrchestrator without the Ink TUI for non-interactive use.
+ * Used by AI agents (e.g. OpenClaw orchestrator) to generate feature specs.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from '../utils/logger.js';
+import { getAvailableProvider, normalizeModelId, AVAILABLE_MODELS, } from '../ai/providers.js';
+import { loadConfigWithDefaults, hasConfig } from '../utils/config.js';
+import { loadContext, toScanResultFromPersisted } from '../context/index.js';
+import { detectGitHubRemote, fetchGitHubIssue } from '../utils/github.js';
+import { initTracing, flushTracing, traced, currentSpan } from '../utils/tracing.js';
+import { InterviewOrchestrator, } from '../tui/orchestration/interview-orchestrator.js';
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+export async function newAutoCommand(featureName, options = {}) {
+    // Validate inputs
+    if (!featureName) {
+        console.error('Error: feature name is required for --auto mode');
+        process.exit(1);
+    }
+    // Detect provider
+    const provider = options.provider ?? getAvailableProvider();
+    if (!provider) {
+        console.error('Error: No AI provider available. Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY.');
+        process.exit(1);
+    }
+    // Load config
+    const projectRoot = process.cwd();
+    let specsDir = join(projectRoot, '.ralph/specs');
+    if (hasConfig(projectRoot)) {
+        const config = await loadConfigWithDefaults(projectRoot);
+        specsDir = join(projectRoot, config.paths.specs);
+    }
+    // Determine model — resolve aliases (e.g. 'sonnet' → full model ID)
+    const recommendedModel = AVAILABLE_MODELS[provider].find((m) => m.hint?.includes('recommended'));
+    const defaultModel = recommendedModel?.value ?? AVAILABLE_MODELS[provider][0].value;
+    const model = normalizeModelId(provider, options.model ?? defaultModel);
+    // Init tracing
+    try {
+        initTracing();
+    }
+    catch (err) {
+        logger.debug(`Failed to init tracing: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Load project context (same logic as InterviewScreen.tsx)
+    let resolvedScanResult;
+    let resolvedSessionContext;
+    try {
+        const persisted = await loadContext(projectRoot);
+        if (persisted) {
+            resolvedSessionContext = {
+                entryPoints: persisted.aiAnalysis.projectContext?.entryPoints,
+                keyDirectories: persisted.aiAnalysis.projectContext?.keyDirectories,
+                commands: persisted.aiAnalysis.commands,
+                namingConventions: persisted.aiAnalysis.projectContext?.namingConventions,
+                implementationGuidelines: persisted.aiAnalysis.implementationGuidelines,
+                keyPatterns: persisted.aiAnalysis.technologyPractices?.practices,
+            };
+            resolvedScanResult = toScanResultFromPersisted(persisted.scanResult, projectRoot);
+            logger.info('Loaded cached project context from .ralph/.context.json');
+        }
+    }
+    catch (err) {
+        logger.debug(`Unable to load cached project context: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Drive the orchestrator headlessly
+    const spec = await traced(async () => {
+        currentSpan().log({
+            input: {
+                featureName,
+                provider,
+                model,
+                goals: options.goals,
+                hasReferences: (options.initialReferences?.length ?? 0) > 0,
+            },
+            metadata: {
+                command: 'new-auto',
+                provider,
+                model,
+            },
+            tags: ['new-auto'],
+        });
+        return driveOrchestrator({
+            featureName,
+            projectRoot,
+            provider,
+            model,
+            scanResult: resolvedScanResult,
+            sessionContext: resolvedSessionContext,
+            goals: options.goals,
+            initialReferences: options.initialReferences,
+            timeoutMs: options.timeoutMs,
+        });
+    }, { name: 'new-auto-run' });
+    // Save spec to disk
+    if (!existsSync(specsDir)) {
+        mkdirSync(specsDir, { recursive: true });
+    }
+    const specPath = join(specsDir, `${featureName}.md`);
+    writeFileSync(specPath, spec, 'utf-8');
+    // Print spec path to stdout (for piping/scripting)
+    console.log(specPath);
+    // Flush tracing before exit
+    try {
+        await flushTracing();
+    }
+    catch {
+        // Non-critical
+    }
+    process.exit(0);
+}
+async function driveOrchestrator(opts) {
+    let readyDeferred = createDeferred();
+    const completionDeferred = createDeferred();
+    let toolIdCounter = 0;
+    const orchestrator = new InterviewOrchestrator({
+        featureName: opts.featureName,
+        projectRoot: opts.projectRoot,
+        provider: opts.provider,
+        model: opts.model,
+        scanResult: opts.scanResult,
+        sessionContext: opts.sessionContext,
+        onMessage: (role, content) => {
+            logger.info(`[${role}] ${content}`);
+        },
+        onStreamChunk: () => {
+            // No-op in headless mode
+        },
+        onStreamComplete: () => {
+            // No-op in headless mode
+        },
+        onToolStart: (toolName, _input) => {
+            const id = `tool_${++toolIdCounter}`;
+            logger.debug(`Tool start: ${toolName} (${id})`);
+            return id;
+        },
+        onToolEnd: (toolId, _output, error) => {
+            if (error) {
+                logger.debug(`Tool error: ${toolId}: ${error}`);
+            }
+            else {
+                logger.debug(`Tool end: ${toolId}`);
+            }
+        },
+        onPhaseChange: (phase) => {
+            logger.info(`Phase: ${phase}`);
+        },
+        onComplete: (spec) => {
+            completionDeferred.resolve(spec);
+        },
+        onError: (error) => {
+            completionDeferred.reject(new Error(error));
+            // Also unblock readyDeferred so the flow doesn't hang
+            readyDeferred.resolve();
+        },
+        onWorkingChange: (_isWorking, status) => {
+            logger.debug(status);
+        },
+        onReady: () => {
+            readyDeferred.resolve();
+        },
+        onQuestion: () => {
+            // Auto-mode: skip Q&A when a question arrives
+            // skipToGeneration is called below after we detect interview phase
+        },
+    });
+    // Step 1: Start orchestrator (enters context phase)
+    await orchestrator.start();
+    await readyDeferred.promise;
+    readyDeferred = createDeferred();
+    // Step 2: Process initial references
+    if (opts.initialReferences && opts.initialReferences.length > 0) {
+        for (const ref of opts.initialReferences) {
+            if (ref.startsWith('issue:')) {
+                const value = ref.slice(6);
+                if (/^\d+$/.test(value)) {
+                    // Bare issue number — resolve from repo remote
+                    const repo = await detectGitHubRemote(opts.projectRoot);
+                    if (repo) {
+                        const detail = await fetchGitHubIssue(repo.owner, repo.repo, parseInt(value, 10));
+                        if (detail) {
+                            const content = `# ${detail.title}\n\n${detail.body ?? ''}`;
+                            orchestrator.addReferenceContent(content, `GitHub issue #${value}`);
+                            logger.info(`Added: GitHub issue #${value} ${detail.title}`);
+                            continue;
+                        }
+                    }
+                    logger.warn(`Could not fetch issue #${value} — no GitHub remote detected or gh CLI unavailable`);
+                }
+                else {
+                    // Full URL — use addReference which handles GitHub URLs
+                    await orchestrator.addReference(value);
+                    readyDeferred = createDeferred();
+                }
+            }
+            else {
+                await orchestrator.addReference(ref);
+                readyDeferred = createDeferred();
+            }
+        }
+    }
+    // Step 3: Advance to goals
+    await orchestrator.advanceToGoals();
+    await readyDeferred.promise;
+    readyDeferred = createDeferred();
+    // Step 4: Submit goals — this triggers codebase exploration + first question
+    // The onQuestion callback will fire, and we handle it after submitGoals returns
+    await orchestrator.submitGoals(opts.goals ?? '');
+    await readyDeferred.promise;
+    readyDeferred = createDeferred();
+    // Step 5: Skip to generation (auto-mode skips Q&A)
+    if (orchestrator.getPhase() === 'interview' ||
+        orchestrator.getPhase() === 'goals') {
+        await orchestrator.skipToGeneration();
+    }
+    // Wait for spec generation to complete (with timeout to prevent silent hangs)
+    const TIMEOUT_MS = opts.timeoutMs ?? 5 * 60 * 1000; // default: 5 minutes
+    let timeoutId;
+    const timeout = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error('Spec generation timed out after 5 minutes')), TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([completionDeferred.promise, timeout]);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/dist/commands/run.js

@@ -74,15 +74,24 @@ export async function runCommand(feature, options = {}) {
     }
     // Load config
     const config = await loadConfigWithDefaults(projectRoot);
-    // Validate spec file exists
-    const specFile = await validateSpecFile(projectRoot, feature);
-    if (!specFile) {
-        logger.error(`Spec file not found: ${feature}.md`);
-        logger.info(`Create the spec first: wiggum new ${feature}`);
-        logger.info(`Expected location: ${join(projectRoot, config.paths.specs, `${feature}.md`)}`);
-        process.exit(1);
+    // Validate spec file exists (skip when resuming — spec lives on the feature branch)
+    let specFile = null;
+    if (options.resume) {
+        // Best-effort: find it if it's here, but don't fail
+        specFile = await validateSpecFile(projectRoot, feature);
+    }
+    else {
+        specFile = await validateSpecFile(projectRoot, feature);
+        if (!specFile) {
+            logger.error(`Spec file not found: ${feature}.md`);
+            logger.info(`Create the spec first: wiggum new ${feature}`);
+            logger.info(`Expected location: ${join(projectRoot, config.paths.specs, `${feature}.md`)}`);
+            process.exit(1);
+        }
+    }
+    if (specFile) {
+        logger.info(`Found spec: ${specFile}`);
     }
-    logger.info(`Found spec: ${specFile}`);
     // Find the feature-loop.sh script
     const scriptPath = findFeatureLoopScript(projectRoot);
     if (!scriptPath) {
@@ -121,7 +130,7 @@ export async function runCommand(feature, options = {}) {
     // Display configuration
     console.log(pc.cyan('--- Run Configuration ---'));
     console.log(`  Feature: ${pc.bold(feature)}`);
-    console.log(`  Spec: ${specFile}`);
+    console.log(`  Spec: ${specFile ?? '(on feature branch)'}`);
     console.log(`  Max Iterations: ${maxIterations}`);
     console.log(`  Max E2E Attempts: ${maxE2eAttempts}`);
     console.log(`  Model: ${options.model || config.loop.defaultModel}`);
@@ -167,7 +176,8 @@ export async function runCommand(feature, options = {}) {
                 else {
                     logger.error(`Feature loop exited with code: ${code}`);
                     logger.info('Use --resume to continue from where you left off');
-                    reject(new Error(`Feature loop exited with code: ${code || 1}`));
+                    process.exitCode = code || 1;
+                    resolve();
                 }
             });
         }

package/dist/commands/sync.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Headless Sync Command
+ * Runs project scan + AI enhancement and persists context to .ralph/.context.json
+ * CLI equivalent of the TUI /sync command, for non-interactive use.
+ */
+/**
+ * Pure sync logic — scans, enhances, persists context.
+ * Returns the context file path on success. Throws on failure.
+ * Safe to call from tools/agents (no process.exit).
+ */
+export declare function syncProjectContext(projectRoot: string): Promise<string>;
+/**
+ * CLI entry point — wraps syncProjectContext with process.exit behavior.
+ */
+export declare function syncCommand(): Promise<void>;

package/dist/commands/sync.js

@@ -0,0 +1,68 @@
+/**
+ * Headless Sync Command
+ * Runs project scan + AI enhancement and persists context to .ralph/.context.json
+ * CLI equivalent of the TUI /sync command, for non-interactive use.
+ */
+import { join } from 'node:path';
+import { logger } from '../utils/logger.js';
+import { Scanner } from '../scanner/index.js';
+import { AIEnhancer } from '../ai/enhancer.js';
+import { saveContext, toPersistedScanResult, toPersistedAIAnalysis, getGitMetadata, } from '../context/index.js';
+import { getAvailableProvider, AVAILABLE_MODELS, normalizeModelId, } from '../ai/providers.js';
+/**
+ * Pure sync logic — scans, enhances, persists context.
+ * Returns the context file path on success. Throws on failure.
+ * Safe to call from tools/agents (no process.exit).
+ */
+export async function syncProjectContext(projectRoot) {
+    // Detect provider
+    const provider = getAvailableProvider();
+    if (!provider) {
+        throw new Error('No AI provider available. Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY.');
+    }
+    // Resolve model
+    const recommendedModel = AVAILABLE_MODELS[provider].find((m) => m.hint?.includes('recommended'));
+    const defaultModel = recommendedModel?.value ?? AVAILABLE_MODELS[provider][0].value;
+    const model = normalizeModelId(provider, defaultModel);
+    logger.info('Scanning project...');
+    // Step 1: Scan
+    const scanner = new Scanner();
+    const scanResult = await scanner.scan(projectRoot);
+    logger.info('Running AI analysis...');
+    // Step 2: AI enhancement
+    const enhancer = new AIEnhancer({
+        provider,
+        model,
+        agentic: true,
+    });
+    const enhanced = await enhancer.enhance(scanResult);
+    if (enhanced.aiError) {
+        throw new Error(`AI analysis failed: ${enhanced.aiError}`);
+    }
+    // Step 3: Persist
+    const git = await getGitMetadata(projectRoot);
+    await saveContext({
+        lastAnalyzedAt: new Date().toISOString(),
+        gitCommitHash: git.gitCommitHash,
+        gitBranch: git.gitBranch,
+        scanResult: toPersistedScanResult(enhanced),
+        aiAnalysis: toPersistedAIAnalysis(enhanced.aiAnalysis),
+    }, projectRoot);
+    return join(projectRoot, '.ralph', '.context.json');
+}
+/**
+ * CLI entry point — wraps syncProjectContext with process.exit behavior.
+ */
+export async function syncCommand() {
+    let contextPath;
+    try {
+        contextPath = await syncProjectContext(process.cwd());
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+        return; // unreachable, but satisfies TS control flow
+    }
+    console.log(contextPath);
+    process.exit(0);
+}