@nathanvale/chatline 0.0.1

package/dist/cli.js

@@ -0,0 +1,1805 @@
+#!/usr/bin/env node
+/**
+ * iMessage Timeline CLI
+ *
+ * Main entry point for the CLI using commander.js.
+ * Implements CLI--T01: Setup Commander.js Structure
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { humanError, humanInfo, humanWarn, setHumanLoggingEnabled, } from '#utils/human';
+import { createLogger, setCorrelationId, setLogLevel } from '#utils/logger';
+// Get package.json for version
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJsonPath = resolve(__dirname, '../package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+// ============================================================================
+// CLI--T01-AC02: Create main program with version, description, global options
+// ============================================================================
+const program = new Command();
+const cliLogger = createLogger('cli');
+function applyLogLevel(verbose, quiet) {
+    const level = quiet ? 'error' : verbose ? 'debug' : 'info';
+    setLogLevel(level);
+}
+// Exported for potential test usage
+function logEvent(event, meta) {
+    cliLogger.info(event, meta);
+}
+program
+    .name('imessage-timeline')
+    .version(packageJson.version)
+    .description('Extract, transform, and analyze iMessage conversations with AI-powered enrichment and timeline rendering');
+// ============================================================================
+// CLI--T01-AC03: Global options: --verbose, --quiet, --config <path>
+// ============================================================================
+program
+    .option('-v, --verbose', 'enable verbose logging', false)
+    .option('-q, --quiet', 'suppress non-error output', false)
+    .option('-c, --config <path>', 'path to config file', 'imessage-config.json')
+    .option('--json', 'emit structured JSON log events only (machine-readable)', false);
+// Toggle human logging before each command action
+program.hook('preAction', () => {
+    const opts = program.opts();
+    const envJson = String(process.env.IMESSAGE_JSON || '').toLowerCase();
+    const envJsonOnly = ['1', 'true', 'yes', 'y', 'json', 'json-only'].includes(envJson);
+    const jsonOnly = Boolean(opts.json) || envJsonOnly;
+    setHumanLoggingEnabled(!jsonOnly);
+});
+// ============================================================================
+// CLI--T01-AC05: Top-level error handler with user-friendly messages
+// ============================================================================
+program.configureOutput({
+    outputError: (str, write) => {
+        const errorMsg = str
+            .replace(/^error: /, '❌ Error: ')
+            .replace(/^Error: /, '❌ Error: ');
+        write(errorMsg);
+        cliLogger.error('Commander output error', { raw: str });
+    },
+});
+// Custom error handler for better error messages
+program.exitOverride((err) => {
+    // Allow help and version to exit cleanly
+    if (err.code === 'commander.help' || err.code === 'commander.helpDisplayed') {
+        process.exit(0);
+    }
+    if (err.code === 'commander.version') {
+        process.exit(0);
+    }
+    // Handle missing required options
+    if (err.code === 'commander.missingArgument') {
+        humanError(`❌ Error: ${err.message}`);
+        humanError(`\nRun 'imessage-timeline ${program.args[0] || ''} --help' for usage information`);
+        process.exit(1);
+    }
+    // Handle unknown commands
+    if (err.code === 'commander.unknownCommand') {
+        humanError(`❌ Error: ${err.message}`);
+        humanError(`\nRun 'imessage-timeline --help' to see available commands`);
+        process.exit(1);
+    }
+    // Generic error handler
+    humanError(`❌ Error: ${err.message}`);
+    cliLogger.error('CLI exit override error', {
+        code: err.code,
+        message: err.message,
+    });
+    process.exit(err.exitCode || 1);
+});
+// ============================================================================
+// Placeholder Commands (to be implemented in CLI--T02, CLI--T03, CLI--T04, CLI--T05)
+// ============================================================================
+// ============================================================================
+// Ingest commands (CLI--T02)
+// ============================================================================
+program
+    .command('ingest-csv')
+    .description('Import messages from iMazing CSV export')
+    .requiredOption('-i, --input <path>', 'path to CSV file')
+    .option('-o, --output <path>', 'output JSON file path', './messages.csv.ingested.json')
+    .option('-a, --attachments <dir...>', 'attachment root directories')
+    .action(async (options) => {
+    const { input, output, attachments } = options;
+    const verbose = program.opts().verbose;
+    applyLogLevel(verbose, program.opts().quiet);
+    setCorrelationId(`ingest-csv:${Date.now().toString(36)}`);
+    logEvent('ingest-start', {
+        command: 'ingest-csv',
+        phase: 'start',
+        options: { input, output, attachmentsCount: attachments?.length },
+    });
+    try {
+        // CLI-T02-AC04: Input file validation with clear error messages
+        const fs = await import('node:fs');
+        if (!fs.existsSync(input)) {
+            humanError(`❌ Input CSV file not found: ${input}`);
+            humanError('\nPlease check:');
+            humanError('  • File path is correct');
+            humanError('  • File exists and is readable');
+            process.exit(1);
+        }
+        // CLI-T02-AC03: Attachment root validation (check directories exist)
+        const attachmentRoots = [];
+        if (attachments && attachments.length > 0) {
+            for (const dir of attachments) {
+                if (!fs.existsSync(dir)) {
+                    humanError(`❌ Attachment directory not found: ${dir}`);
+                    process.exit(1);
+                }
+                if (!fs.statSync(dir).isDirectory()) {
+                    humanError(`❌ Not a directory: ${dir}`);
+                    process.exit(1);
+                }
+                attachmentRoots.push(dir);
+            }
+        }
+        else {
+            // Default: ~/Library/Messages/Attachments
+            const os = await import('node:os');
+            const path = await import('node:path');
+            const defaultRoot = path.join(os.homedir(), 'Library', 'Messages', 'Attachments');
+            if (fs.existsSync(defaultRoot)) {
+                attachmentRoots.push(defaultRoot);
+                if (verbose) {
+                    cliLogger.info('Using default attachment root', { defaultRoot });
+                }
+            }
+        }
+        // CLI-T02-AC01: ingest-csv command with all options from usage guide
+        const { ingestCSV, createExportEnvelope, validateMessages } = await import('./ingest/ingest-csv.js');
+        if (verbose) {
+            cliLogger.info('Reading CSV ingest', { input, attachmentRoots });
+        }
+        const messages = ingestCSV(input, { attachmentRoots });
+        // CLI-T02-AC05: Progress output: ✓ Parsed 2,847 messages from CSV
+        humanInfo(`✓ Parsed ${messages.length.toLocaleString()} messages from CSV`);
+        // Validate messages before writing
+        const validation = validateMessages(messages);
+        if (!validation.valid) {
+            humanError(`❌ ${validation.errors.length} messages failed validation`);
+            if (verbose) {
+                validation.errors.slice(0, 5).forEach((err) => {
+                    humanError(`  Message ${err.index}:`, err.issues);
+                });
+            }
+            process.exit(1);
+        }
+        // Write export envelope
+        const envelope = createExportEnvelope(messages);
+        fs.writeFileSync(output, JSON.stringify(envelope, null, 2), 'utf-8');
+        humanInfo(`✓ Wrote ${messages.length.toLocaleString()} messages to ${output}`);
+        humanInfo('\n📊 Summary:');
+        const textCount = messages.filter((m) => m.messageKind === 'text').length;
+        const mediaCount = messages.filter((m) => m.messageKind === 'media').length;
+        const notifCount = messages.filter((m) => m.messageKind === 'notification').length;
+        humanInfo(`  Text: ${textCount}`);
+        humanInfo(`  Media: ${mediaCount}`);
+        humanInfo(`  Notifications: ${notifCount}`);
+        logEvent('ingest-summary', {
+            command: 'ingest-csv',
+            phase: 'summary',
+            metrics: {
+                total: messages.length,
+                text: textCount,
+                media: mediaCount,
+                notifications: notifCount,
+            },
+            options: { output },
+            exitCode: 0,
+        });
+        process.exit(0);
+    }
+    catch (error) {
+        humanError('❌ Failed to ingest CSV:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('ingest-error', {
+            command: 'ingest-csv',
+            phase: 'error',
+            error: errorMeta,
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+program
+    .command('ingest-db')
+    .description('Import messages from macOS Messages.app database export (JSON)')
+    .requiredOption('-i, --input <path>', 'path to JSON file with DB messages')
+    .option('-o, --output <path>', 'output JSON file path', './messages.db.ingested.json')
+    .option('-a, --attachments <dir...>', 'attachment root directories')
+    .option('--contact <handle>', 'filter to specific contact handle')
+    .action(async (options) => {
+    const { input, output, attachments, contact } = options;
+    const verbose = program.opts().verbose;
+    applyLogLevel(verbose, program.opts().quiet);
+    logEvent('ingest-start', {
+        command: 'ingest-db',
+        phase: 'start',
+        options: {
+            input,
+            output,
+            attachmentsCount: attachments?.length,
+            contact,
+        },
+    });
+    try {
+        // CLI-T02-AC04: Input file validation with clear error messages
+        const fs = await import('node:fs');
+        if (!fs.existsSync(input)) {
+            humanError(`❌ Input JSON file not found: ${input}`);
+            humanError('\nPlease check:');
+            humanError('  • File path is correct');
+            humanError('  • File exists and is readable');
+            process.exit(1);
+        }
+        // CLI-T02-AC03: Attachment root validation (check directories exist)
+        const attachmentRoots = [];
+        if (attachments && attachments.length > 0) {
+            for (const dir of attachments) {
+                if (!fs.existsSync(dir)) {
+                    humanError(`❌ Attachment directory not found: ${dir}`);
+                    process.exit(1);
+                }
+                if (!fs.statSync(dir).isDirectory()) {
+                    humanError(`❌ Not a directory: ${dir}`);
+                    process.exit(1);
+                }
+                attachmentRoots.push(dir);
+            }
+        }
+        else {
+            // Default: ~/Library/Messages/Attachments
+            const os = await import('node:os');
+            const path = await import('node:path');
+            const defaultRoot = path.join(os.homedir(), 'Library', 'Messages', 'Attachments');
+            if (fs.existsSync(defaultRoot)) {
+                attachmentRoots.push(defaultRoot);
+                if (verbose) {
+                    humanInfo(`Using default attachment root: ${defaultRoot}`);
+                }
+            }
+        }
+        // CLI-T02-AC02: ingest-db command with database path and contact filtering
+        const { splitDBMessage } = await import('./ingest/ingest-db.js');
+        const { createExportEnvelope, validateMessages } = await import('./ingest/ingest-csv.js');
+        if (verbose) {
+            cliLogger.info('Reading DB export', {
+                input,
+                attachmentRoots,
+                contact,
+            });
+        }
+        // Read and parse DB export JSON
+        const content = fs.readFileSync(input, 'utf-8');
+        const dbMessages = JSON.parse(content);
+        if (!Array.isArray(dbMessages)) {
+            humanError(`❌ Expected JSON array of DB messages, got: ${typeof dbMessages}`);
+            process.exit(1);
+        }
+        // Filter by contact if specified
+        let filteredMessages = dbMessages;
+        if (contact) {
+            filteredMessages = dbMessages.filter((m) => m.handle === contact);
+            humanInfo(`✓ Filtered to ${filteredMessages.length} messages from ${contact}`);
+        }
+        // Split DB messages into Message objects
+        const messages = [];
+        filteredMessages.forEach((dbMsg, index) => {
+            const split = splitDBMessage(dbMsg, index + 1, { attachmentRoots });
+            messages.push(...split);
+        });
+        // CLI-T02-AC05: Progress output
+        humanInfo(`✓ Parsed ${messages.length.toLocaleString()} messages from DB export`);
+        // Validate messages before writing
+        const validation = validateMessages(messages);
+        if (!validation.valid) {
+            humanError(`❌ ${validation.errors.length} messages failed validation`);
+            if (verbose) {
+                validation.errors.slice(0, 5).forEach((err) => {
+                    humanError(`  Message ${err.index}:`, err.issues);
+                });
+            }
+            process.exit(1);
+        }
+        // Write export envelope
+        const envelope = createExportEnvelope(messages);
+        fs.writeFileSync(output, JSON.stringify(envelope, null, 2), 'utf-8');
+        humanInfo(`✓ Wrote ${messages.length.toLocaleString()} messages to ${output}`);
+        humanInfo('\n📊 Summary:');
+        const dbText = messages.filter((m) => m.messageKind === 'text').length;
+        const dbMedia = messages.filter((m) => m.messageKind === 'media').length;
+        humanInfo(`  Text: ${dbText}`);
+        humanInfo(`  Media: ${dbMedia}`);
+        logEvent('ingest-summary', {
+            command: 'ingest-db',
+            phase: 'summary',
+            metrics: { total: messages.length, text: dbText, media: dbMedia },
+            options: { output, contact },
+            exitCode: 0,
+        });
+        process.exit(0);
+    }
+    catch (error) {
+        humanError('❌ Failed to ingest DB export:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('ingest-error', {
+            command: 'ingest-db',
+            phase: 'error',
+            error: errorMeta,
+            options: { output, contact },
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+// Normalize command (CLI--T03-AC01)
+program
+    .command('normalize-link')
+    .description('Deduplicate and link messages from multiple sources')
+    .requiredOption('-i, --input <files...>', 'input JSON files (CSV, DB, or both)')
+    .option('-o, --output <path>', 'output JSON file path', './messages.normalized.json')
+    .option('-m, --merge-mode <mode>', 'merge mode: exact|content|all (default: all)', 'all')
+    .action(async (options) => {
+    const { input, output, mergeMode } = options;
+    const verbose = program.opts().verbose;
+    applyLogLevel(verbose, program.opts().quiet);
+    try {
+        // Validate inputs
+        const fs = await import('node:fs');
+        const inputFiles = Array.isArray(input) ? input : [input];
+        for (const file of inputFiles) {
+            if (!fs.existsSync(file)) {
+                humanError(`❌ Input file not found: ${file}`);
+                process.exit(1);
+            }
+        }
+        // CLI-T03-AC01: Validate merge mode
+        if (!['exact', 'content', 'all'].includes(mergeMode)) {
+            humanError(`❌ Invalid merge mode: ${mergeMode}`);
+            humanError('Valid modes: exact (GUID only), content (text matching), all (both)');
+            process.exit(1);
+        }
+        if (verbose) {
+            cliLogger.info('Start normalize-link', {
+                files: inputFiles.length,
+                mergeMode,
+            });
+        }
+        // Load input files
+        const allMessages = [];
+        for (const file of inputFiles) {
+            const content = fs.readFileSync(file, 'utf-8');
+            const data = JSON.parse(content);
+            const messages = Array.isArray(data) ? data : data.messages || [];
+            allMessages.push(...messages);
+            humanInfo(`✓ Loaded ${messages.length} messages from ${file}`);
+        }
+        // Import normalize pipeline
+        const { linkRepliesToParents } = await import('./ingest/link-replies-and-tapbacks.js');
+        const { dedupAndMerge } = await import('./ingest/dedup-merge.js');
+        const { validateNormalizedMessages } = await import('./normalize/validate-normalized.js');
+        if (verbose) {
+            cliLogger.info('Total messages before linking', {
+                count: allMessages.length,
+            });
+        }
+        // Step 1: Link replies and tapbacks
+        const linkedResult = linkRepliesToParents(allMessages, {
+            trackAmbiguous: true,
+        });
+        const linkedMessages = Array.isArray(linkedResult)
+            ? linkedResult
+            : linkedResult.messages;
+        if (verbose &&
+            !Array.isArray(linkedResult) &&
+            linkedResult.ambiguousLinks) {
+            cliLogger.warn('Ambiguous reply/tapback links detected', {
+                count: linkedResult.ambiguousLinks.length,
+            });
+        }
+        // Step 2: Deduplicate and merge (if multiple sources)
+        let normalizedMessages = linkedMessages;
+        if (inputFiles.length > 1) {
+            // Split messages by source for dedup-merge
+            const csvMessages = linkedMessages.filter((m) => m.exportVersion?.includes('csv') || !m.rowid);
+            const dbMessages = linkedMessages.filter((m) => m.rowid !== undefined);
+            const mergeResult = dedupAndMerge(csvMessages, dbMessages);
+            normalizedMessages = mergeResult.messages;
+            if (verbose) {
+                cliLogger.info('Merge statistics', {
+                    input: mergeResult.stats.csvCount + mergeResult.stats.dbCount,
+                    output: mergeResult.stats.outputCount,
+                    exactMatches: mergeResult.stats.exactMatches,
+                    contentMatches: mergeResult.stats.contentMatches,
+                    noMatches: mergeResult.stats.noMatches,
+                });
+            }
+        }
+        // Step 3: Validate normalized messages
+        const validatedMessages = validateNormalizedMessages(normalizedMessages);
+        // Write output envelope
+        const { createExportEnvelope } = await import('./ingest/ingest-csv.js');
+        const envelope = createExportEnvelope(validatedMessages);
+        envelope.source = 'merged';
+        fs.writeFileSync(output, JSON.stringify(envelope, null, 2), 'utf-8');
+        humanInfo(`\n✅ Normalized ${validatedMessages.length.toLocaleString()} messages`);
+        humanInfo(`✓ Wrote to ${output}`);
+        humanInfo('\n📊 Final Summary:');
+        const nText = validatedMessages.filter((m) => m.messageKind === 'text').length;
+        const nMedia = validatedMessages.filter((m) => m.messageKind === 'media').length;
+        const nTapbacks = validatedMessages.filter((m) => m.messageKind === 'tapback').length;
+        const nNotifs = validatedMessages.filter((m) => m.messageKind === 'notification').length;
+        humanInfo(`  Text: ${nText}`);
+        humanInfo(`  Media: ${nMedia}`);
+        humanInfo(`  Tapbacks: ${nTapbacks}`);
+        humanInfo(`  Notifications: ${nNotifs}`);
+        logEvent('normalize-summary', {
+            command: 'normalize-link',
+            phase: 'summary',
+            metrics: {
+                total: validatedMessages.length,
+                text: nText,
+                media: nMedia,
+                tapbacks: nTapbacks,
+                notifications: nNotifs,
+            },
+            options: { output },
+            exitCode: 0,
+        });
+        process.exit(0);
+    }
+    catch (error) {
+        humanError('❌ Failed to normalize-link:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('normalize-error', {
+            command: 'normalize-link',
+            phase: 'error',
+            error: errorMeta,
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+// Enrich command (CLI--T03-AC02, AC03, AC04, AC05)
+program
+    .command('enrich-ai')
+    .description('Add AI-powered enrichment to media messages')
+    .requiredOption('-i, --input <path>', 'input normalized JSON file')
+    .option('-o, --output <path>', 'output JSON file path', './messages.enriched.json')
+    .option('-c, --checkpoint-dir <path>', 'checkpoint directory', './.checkpoints')
+    .option('--resume', 'resume from last checkpoint', false)
+    .option('--incremental', 'only enrich messages new since last enrichment run', false)
+    .option('--state-file <path>', 'path to incremental state file (auto-detects .imessage-state.json by default)')
+    .option('--reset-state', 'clear incremental state and enrich all messages', false)
+    .option('--force-refresh', 'force re-enrichment even if already done', false)
+    .option('--rate-limit <ms>', 'delay between API calls (milliseconds)', '1000')
+    .option('--max-retries <n>', 'max retries on API errors', '3')
+    .option('--checkpoint-interval <n>', 'write checkpoint every N items', '100')
+    .option('--enable-vision', 'enable image analysis with Gemini Vision', true)
+    .option('--enable-audio', 'enable audio transcription with Gemini Audio', true)
+    .option('--enable-links', 'enable link enrichment with Firecrawl', true)
+    .action(async (options) => {
+    const { input, output, checkpointDir, resume, incremental, stateFile: userProvidedStateFile, resetState, forceRefresh: _forceRefresh, rateLimitMs, maxRetries, checkpointInterval, enableVision, enableAudio, enableLinks, } = options;
+    const verbose = program.opts().verbose;
+    applyLogLevel(verbose, program.opts().quiet);
+    logEvent('enrich-start', {
+        command: 'enrich',
+        phase: 'start',
+        options: {
+            input,
+            output,
+            checkpointDir,
+            resume,
+            incremental,
+            stateFile: userProvidedStateFile,
+            resetState,
+            rateLimitMs,
+            maxRetries,
+            checkpointInterval,
+            enableVision,
+            enableAudio,
+            enableLinks,
+        },
+    });
+    try {
+        // Validate inputs
+        const fs = await import('node:fs');
+        if (!fs.existsSync(input)) {
+            humanError(`❌ Input file not found: ${input}`);
+            process.exit(1);
+        }
+        // Parse rate limit and retry options
+        const rateLimitDelay = Number.parseInt(rateLimitMs, 10);
+        const maxRetriesNum = Number.parseInt(maxRetries, 10);
+        const checkpointIntervalNum = Number.parseInt(checkpointInterval, 10);
+        if (Number.isNaN(rateLimitDelay) || rateLimitDelay < 0) {
+            humanError('❌ --rate-limit must be a non-negative number (milliseconds)');
+            process.exit(1);
+        }
+        if (Number.isNaN(maxRetriesNum) || maxRetriesNum < 0) {
+            humanError('❌ --max-retries must be a non-negative number');
+            process.exit(1);
+        }
+        if (Number.isNaN(checkpointIntervalNum) || checkpointIntervalNum < 1) {
+            humanError('❌ --checkpoint-interval must be a positive number');
+            process.exit(1);
+        }
+        if (verbose) {
+            cliLogger.info('Enrich config', {
+                input,
+                output,
+                checkpointDir,
+                rateLimitDelay,
+                maxRetries: maxRetriesNum,
+                checkpointInterval: checkpointIntervalNum,
+                enableVision,
+                enableAudio,
+                enableLinks,
+                incremental,
+            });
+        }
+        // Create checkpoint directory if needed
+        if (!fs.existsSync(checkpointDir)) {
+            await import('node:fs/promises').then((fsp) => fsp.mkdir(checkpointDir, { recursive: true }));
+        }
+        // Load normalized messages
+        const content = fs.readFileSync(input, 'utf-8');
+        const data = JSON.parse(content);
+        const messages = Array.isArray(data) ? data : data.messages || [];
+        humanInfo(`✓ Loaded ${messages.length.toLocaleString()} messages`);
+        // Import enrichment modules
+        const { loadCheckpoint, computeConfigHash, saveCheckpoint, createCheckpoint, } = await import('./enrich/checkpoint.js');
+        // Import actual enrichment functions
+        const { analyzeImage } = await import('./enrich/image-analysis.js');
+        const { analyzeAudio } = await import('./enrich/audio-transcription.js');
+        const { enrichLinkContext } = await import('./enrich/link-enrichment.js');
+        const { createRateLimiter } = await import('./enrich/rate-limiting.js');
+        // Create rate limiter with circuit breaker
+        const rateLimiter = createRateLimiter({
+            rateLimitDelay,
+            maxRetries: maxRetriesNum,
+            circuitBreakerThreshold: 5,
+            circuitBreakerResetMs: 60000,
+        });
+        // Compute config hash for checkpoint verification (AC05: Config consistency)
+        const enrichConfig = {
+            enableVisionAnalysis: enableVision,
+            enableLinkAnalysis: enableLinks,
+            enableAudioTranscription: enableAudio,
+            rateLimitDelay,
+            maxRetries: maxRetriesNum,
+        };
+        const configHash = computeConfigHash(enrichConfig);
+        const checkpointPath = `${checkpointDir}/enrich-checkpoint-${configHash}.json`;
+        // INCREMENTAL--T04-AC02/AC03: Handle incremental state file
+        const stateFilePath = userProvidedStateFile || '.imessage-state.json';
+        const stateFileExists = fs.existsSync(stateFilePath);
+        // INCREMENTAL--T04-AC04: Handle --reset-state flag
+        if (resetState && stateFileExists) {
+            fs.unlinkSync(stateFilePath);
+            if (verbose) {
+                humanInfo(`🗑️  Reset incremental state file: ${stateFilePath}`);
+            }
+        }
+        // Import incremental state module for AC02, AC03, AC04, AC05
+        const { loadIncrementalState, detectNewMessages } = await import('./utils/incremental-state.js');
+        // INCREMENTAL--T04-AC02: Auto-detect state file and load previous state
+        let previousState = null;
+        let newMessageGuids = [];
+        let newMessageCount = messages.length;
+        if (incremental && stateFileExists && !resetState) {
+            previousState = await loadIncrementalState(stateFilePath);
+            if (previousState) {
+                // Detect new messages using GUID comparison
+                const currentGuids = new Set(messages
+                    .map((m) => m.guid)
+                    .filter((g) => Boolean(g)));
+                newMessageGuids = detectNewMessages(currentGuids, previousState);
+                newMessageCount = newMessageGuids.length;
+                if (verbose) {
+                    humanInfo(`♻️  Incremental mode: detected ${newMessageCount.toLocaleString()} new messages`);
+                    humanInfo(`   Total messages: ${messages.length.toLocaleString()}`);
+                }
+            }
+        }
+        else if (incremental && !stateFileExists && !resetState) {
+            if (verbose) {
+                humanInfo(`♻️  Incremental mode enabled but no state file found: ${stateFilePath}`);
+                humanInfo(`   Enriching all ${messages.length.toLocaleString()} messages`);
+            }
+        }
+        // AC05: Load checkpoint and verify config hash
+        let startIndex = 0;
+        if (resume) {
+            const checkpoint = await loadCheckpoint(checkpointPath);
+            if (checkpoint) {
+                if (checkpoint.configHash !== configHash) {
+                    humanError('❌ Config has changed since last checkpoint');
+                    humanError('Use --force-refresh to re-enrich or delete checkpoint file');
+                    process.exit(1);
+                }
+                startIndex = checkpoint.lastProcessedIndex + 1;
+                cliLogger.info('Resuming from checkpoint', {
+                    startIndex,
+                    alreadyProcessed: checkpoint.totalProcessed,
+                    failedItems: checkpoint.totalFailed,
+                });
+            }
+            else if (resume) {
+                humanWarn('⚠️  No checkpoint found, starting from beginning');
+            }
+        }
+        // AC02: Enrich messages with checkpoint support
+        const enrichedMessages = [];
+        let totalProcessed = 0;
+        let totalFailed = 0;
+        const failedItems = [];
+        // INCREMENTAL--T04-AC05: Show progress with new message count
+        const progressMsg = incremental && newMessageCount < messages.length
+            ? `Enriching ${newMessageCount.toLocaleString()} new messages (${messages.length.toLocaleString()} total)`
+            : `Processing ${messages.length.toLocaleString()} messages`;
+        humanInfo(`\n🚀 Starting enrichment: ${progressMsg}`);
+        // Build enrichment configs
+        const geminiApiKey = process.env.GEMINI_API_KEY || '';
+        const firecrawlApiKey = process.env.FIRECRAWL_API_KEY;
+        const imageConfig = {
+            enableVisionAnalysis: enableVision ?? true,
+            geminiApiKey,
+            geminiModel: 'gemini-1.5-pro',
+            imageCacheDir: '/tmp/image-cache',
+        };
+        const audioConfig = {
+            enableAudioTranscription: enableAudio ?? true,
+            geminiApiKey,
+            geminiModel: 'gemini-1.5-pro',
+            rateLimitDelay,
+            maxRetries: maxRetriesNum,
+        };
+        const linkConfig = {
+            enableLinkAnalysis: enableLinks ?? true,
+            ...(firecrawlApiKey ? { firecrawlApiKey } : {}),
+            rateLimitDelay,
+            maxRetries: maxRetriesNum,
+        };
+        // Build set of new message GUIDs for incremental filtering
+        const newGuidSet = new Set(newMessageGuids);
+        for (let i = startIndex; i < messages.length; i++) {
+            const message = messages[i];
+            try {
+                // INCREMENTAL--T04: Skip already-enriched messages in incremental mode
+                const shouldEnrich = !incremental || !previousState || newGuidSet.has(message.guid || '');
+                let enrichedMessage = message;
+                if (shouldEnrich) {
+                    // Check circuit breaker before making API calls
+                    if (rateLimiter.isCircuitOpen()) {
+                        // Circuit is open - skip enrichment but don't fail
+                        if (verbose) {
+                            humanWarn(`⚠️  Circuit breaker open - skipping enrichment for message ${i}`);
+                        }
+                    }
+                    else {
+                        // Apply rate limiting delay between API calls
+                        const rateLimitDelayMs = rateLimiter.shouldRateLimit();
+                        if (rateLimitDelayMs > 0) {
+                            await new Promise((resolve) => setTimeout(resolve, rateLimitDelayMs));
+                        }
+                        rateLimiter.recordCall();
+                        // Enrich based on message type and config
+                        if (enableVision &&
+                            message.messageKind === 'media' &&
+                            message.media?.mediaKind === 'image') {
+                            enrichedMessage = await analyzeImage(enrichedMessage, imageConfig);
+                            rateLimiter.recordSuccess();
+                        }
+                        else if (enableAudio &&
+                            message.messageKind === 'media' &&
+                            message.media?.mediaKind === 'audio') {
+                            enrichedMessage = await analyzeAudio(enrichedMessage, audioConfig);
+                            rateLimiter.recordSuccess();
+                        }
+                        else if (enableLinks &&
+                            message.messageKind === 'text' &&
+                            message.text) {
+                            enrichedMessage = await enrichLinkContext(enrichedMessage, linkConfig);
+                            rateLimiter.recordSuccess();
+                        }
+                    }
+                }
+                enrichedMessages.push(enrichedMessage);
+                totalProcessed++;
+                // AC01: Write checkpoint at intervals
+                if ((i + 1) % checkpointIntervalNum === 0) {
+                    const checkpoint = createCheckpoint({
+                        lastProcessedIndex: i,
+                        totalProcessed,
+                        totalFailed,
+                        stats: {
+                            processedCount: totalProcessed,
+                            failedCount: totalFailed,
+                            enrichmentsByKind: {},
+                        },
+                        failedItems,
+                        configHash,
+                    });
+                    await saveCheckpoint(checkpoint, checkpointPath);
+                    if (verbose) {
+                        cliLogger.info('Checkpoint written', { index: i + 1 });
+                    }
+                }
+            }
+            catch (error) {
+                totalFailed++;
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                failedItems.push({
+                    index: i,
+                    guid: message.guid || 'unknown',
+                    kind: message.messageKind || 'unknown',
+                    error: errorMessage,
+                });
+                if (verbose) {
+                    humanWarn(`⚠️  Failed to enrich message ${i}: ${errorMessage}`);
+                    logEvent('enrich-item-failed', {
+                        command: 'enrich',
+                        phase: 'warning',
+                        context: {
+                            index: i,
+                            guid: message.guid || 'unknown',
+                            kind: message.messageKind || 'unknown',
+                        },
+                        error: {
+                            type: error instanceof Error ? error.name : 'Unknown',
+                            message: errorMessage,
+                            ...(error instanceof Error && error.stack
+                                ? { stack: error.stack }
+                                : {}),
+                        },
+                    });
+                }
+            }
+        }
+        // Write final checkpoint
+        const finalCheckpoint = createCheckpoint({
+            lastProcessedIndex: messages.length - 1,
+            totalProcessed,
+            totalFailed,
+            stats: {
+                processedCount: totalProcessed,
+                failedCount: totalFailed,
+                enrichmentsByKind: {},
+            },
+            failedItems,
+            configHash,
+        });
+        await saveCheckpoint(finalCheckpoint, checkpointPath);
+        // Write output
+        const { createExportEnvelope } = await import('./ingest/ingest-csv.js');
+        const envelope = createExportEnvelope(enrichedMessages);
+        envelope.source = 'merged';
+        fs.writeFileSync(output, JSON.stringify(envelope, null, 2), 'utf-8');
+        humanInfo('\n✅ Enrichment complete');
+        humanInfo(`✓ Processed: ${totalProcessed.toLocaleString()} messages`);
+        if (totalFailed > 0) {
+            humanInfo(`⚠️  Failed: ${totalFailed.toLocaleString()} messages`);
+        }
+        humanInfo(`✓ Wrote to ${output}`);
+        logEvent('enrich-summary', {
+            command: 'enrich',
+            phase: 'summary',
+            metrics: { processed: totalProcessed, failed: totalFailed },
+            options: { output, checkpointInterval: checkpointIntervalNum },
+            context: { checkpointPath },
+            exitCode: 0,
+        });
+        process.exit(0);
+    }
+    catch (error) {
+        humanError('❌ Failed to enrich:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('enrich-error', {
+            command: 'enrich',
+            phase: 'error',
+            error: errorMeta,
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+// ============================================================================
+// Render command (CLI--T04: Implement Render Command)
+// ============================================================================
+program
+    .command('render-markdown')
+    .description('Generate Obsidian-compatible markdown timeline files')
+    .requiredOption('-i, --input <path>', 'input enriched JSON file')
+    .option('-o, --output <dir>', 'output directory for markdown files', './timeline')
+    .option('--start-date <date>', 'render messages from this date (YYYY-MM-DD)')
+    .option('--end-date <date>', 'render messages until this date (YYYY-MM-DD)')
+    .option('--group-by-time', 'group messages by time-of-day (Morning/Afternoon/Evening)', true)
+    .option('--nested-replies', 'render replies as nested blockquotes', true)
+    .option('--max-nesting-depth <n>', 'maximum nesting depth for replies (default 10)', '10')
+    .action(async (options) => {
+    const { input, output, startDate, endDate, groupByTime, nestedReplies, maxNestingDepth, } = options;
+    const verbose = program.opts().verbose;
+    applyLogLevel(verbose, program.opts().quiet);
+    logEvent('render-start', {
+        command: 'render-markdown',
+        phase: 'start',
+        options: {
+            input,
+            output,
+            startDate,
+            endDate,
+            groupByTime,
+            nestedReplies,
+            maxNestingDepth,
+        },
+    });
+    try {
+        // CLI-T04-AC01: Date filtering validation
+        const fs = await import('node:fs');
+        if (!fs.existsSync(input)) {
+            humanError(`❌ Input file not found: ${input}`);
+            process.exit(1);
+        }
+        let startDateObj = null;
+        let endDateObj = null;
+        if (startDate) {
+            const start = new Date(startDate);
+            if (Number.isNaN(start.getTime())) {
+                humanError(`❌ Invalid start date: ${startDate} (use YYYY-MM-DD format)`);
+                process.exit(1);
+            }
+            startDateObj = start;
+        }
+        if (endDate) {
+            const end = new Date(endDate);
+            if (Number.isNaN(end.getTime())) {
+                humanError(`❌ Invalid end date: ${endDate} (use YYYY-MM-DD format)`);
+                process.exit(1);
+            }
+            // Set to end of day
+            end.setHours(23, 59, 59, 999);
+            endDateObj = end;
+        }
+        // CLI-T04-AC03: Validate max nesting depth
+        const maxNestingDepthNum = Number.parseInt(maxNestingDepth, 10);
+        if (Number.isNaN(maxNestingDepthNum) || maxNestingDepthNum < 1) {
+            humanError('❌ --max-nesting-depth must be a positive number');
+            process.exit(1);
+        }
+        if (verbose) {
+            humanInfo(`📄 Input: ${input}`);
+            humanInfo(`📁 Output directory: ${output}`);
+            if (startDateObj) {
+                humanInfo(`📅 Start date: ${startDate}`);
+            }
+            if (endDateObj) {
+                humanInfo(`📅 End date: ${endDate}`);
+            }
+            humanInfo(`⏱️  Group by time: ${groupByTime}`);
+            humanInfo(`⬅️  Nested replies: ${nestedReplies}`);
+            humanInfo(`📊 Max nesting depth: ${maxNestingDepthNum}`);
+        }
+        // Load input messages
+        const content = fs.readFileSync(input, 'utf-8');
+        const data = JSON.parse(content);
+        let messages = Array.isArray(data) ? data : data.messages || [];
+        if (verbose) {
+            humanInfo(`✓ Loaded ${messages.length.toLocaleString()} messages`);
+        }
+        // Filter by date range if specified
+        if (startDateObj || endDateObj) {
+            const filtered = messages.filter((msg) => {
+                const msgDate = new Date(msg.date);
+                if (startDateObj && msgDate < startDateObj)
+                    return false;
+                if (endDateObj && msgDate > endDateObj)
+                    return false;
+                return true;
+            });
+            humanInfo(`📊 Filtered to ${filtered.length.toLocaleString()} messages in date range`);
+            logEvent('render-filtered', {
+                command: 'render-markdown',
+                phase: 'progress',
+                metrics: { filtered: filtered.length, original: messages.length },
+                options: {
+                    startDate: startDateObj ? startDateObj.toISOString() : undefined,
+                    endDate: endDateObj ? endDateObj.toISOString() : undefined,
+                },
+            });
+            messages = filtered;
+        }
+        // Import render functions
+        const { renderMessages } = await import('./render/index.js');
+        // Render messages to markdown
+        const rendered = renderMessages(messages);
+        if (rendered.size === 0) {
+            humanWarn('⚠️  No messages to render');
+            process.exit(0);
+        }
+        // CLI-T04-AC04: Create output directory if doesn't exist
+        const path = await import('node:path');
+        const outputDir = path.resolve(output || './timeline');
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+            if (verbose) {
+                cliLogger.info('Created output directory', { outputDir });
+            }
+        }
+        // Write markdown files
+        let filesWritten = 0;
+        const dates = Array.from(rendered.keys()).sort();
+        for (const date of dates) {
+            const markdown = rendered.get(date);
+            if (!markdown)
+                continue;
+            const filename = `${date}.md`;
+            const filepath = path.join(outputDir, filename);
+            fs.writeFileSync(filepath, markdown, 'utf-8');
+            filesWritten++;
+            if (verbose) {
+                humanInfo(`✓ Wrote ${filename}`);
+                logEvent('render-file-written', {
+                    command: 'render-markdown',
+                    phase: 'progress',
+                    metrics: { filesWritten },
+                    context: { filename, filepath },
+                });
+            }
+        }
+        // CLI-T04-AC05: Summary output
+        humanInfo(`\n✅ Rendered ${filesWritten} markdown file(s)`);
+        humanInfo(`✓ Wrote ${filesWritten.toLocaleString()} markdown file${filesWritten === 1 ? '' : 's'} to ${outputDir}`);
+        // Message summary
+        const textMessages = messages.filter((m) => m.messageKind === 'text').length;
+        const mediaMessages = messages.filter((m) => m.messageKind === 'media').length;
+        const tapbacks = messages.filter((m) => m.messageKind === 'tapback').length;
+        humanInfo('\n📊 Message Summary:');
+        humanInfo(`  Total: ${messages.length.toLocaleString()}`);
+        humanInfo(`  Text: ${textMessages.toLocaleString()}`);
+        humanInfo(`  Media: ${mediaMessages.toLocaleString()}`);
+        humanInfo(`  Tapbacks: ${tapbacks.toLocaleString()}`);
+        logEvent('render-summary', {
+            command: 'render-markdown',
+            phase: 'summary',
+            metrics: {
+                filesWritten,
+                totalMessages: messages.length,
+                textMessages,
+                mediaMessages,
+                tapbacks,
+            },
+            options: {
+                outputDir,
+                groupByTime,
+                nestedReplies,
+                maxNestingDepth: maxNestingDepthNum,
+            },
+            exitCode: 0,
+        });
+        process.exit(0);
+    }
+    catch (error) {
+        humanError('❌ Failed to render markdown:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('render-error', {
+            command: 'render-markdown',
+            phase: 'error',
+            error: errorMeta,
+            options: { output, groupByTime, nestedReplies, maxNestingDepth },
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+// ============================================================================
+// Helper commands (CLI--T05)
+// ============================================================================
+// CLI--T05-AC01: validate command to check JSON against schema
+program
+    .command('validate')
+    .description('Validate JSON file against message schema')
+    .requiredOption('-i, --input <path>', 'path to JSON file to validate')
+    .option('-q, --quiet', 'suppress detailed error messages', false)
+    .action(async (options) => {
+    const { input, quiet } = options;
+    const _verbose = program.opts().verbose;
+    applyLogLevel(_verbose, program.opts().quiet);
+    try {
+        const fs = await import('node:fs');
+        // Validate input file exists
+        if (!fs.existsSync(input)) {
+            humanError(`❌ Input file not found: ${input}`);
+            process.exit(1);
+        }
+        // Load and parse JSON
+        const content = fs.readFileSync(input, 'utf-8');
+        let data;
+        try {
+            data = JSON.parse(content);
+        }
+        catch (e) {
+            humanError(`❌ Invalid JSON: ${input}`);
+            humanError(`  ${e instanceof Error ? e.message : String(e)}`);
+            process.exit(1);
+        }
+        // Validate schema
+        const { MessageSchema } = await import('./schema/message.js');
+        const messages = Array.isArray(data)
+            ? data
+            : data.messages || [];
+        let validCount = 0;
+        const errors = [];
+        for (let i = 0; i < messages.length; i++) {
+            const result = MessageSchema.safeParse(messages[i]);
+            if (result.success) {
+                validCount++;
+            }
+            else {
+                result.error.errors.forEach((err) => {
+                    errors.push({
+                        index: i,
+                        path: err.path.join('.'),
+                        message: err.message,
+                    });
+                });
+            }
+        }
+        // Output results
+        if (!quiet) {
+            humanInfo('📊 Validation Results:');
+            humanInfo(`  Valid: ${validCount}/${messages.length}`);
+        }
+        logEvent('validate-results', {
+            command: 'validate',
+            phase: 'progress',
+            metrics: {
+                valid: validCount,
+                total: messages.length,
+                errors: errors.length,
+            },
+            options: { quiet },
+        });
+        if (errors.length === 0) {
+            humanInfo(`✅ All ${messages.length} messages are valid`);
+            logEvent('validate-summary', {
+                command: 'validate',
+                phase: 'summary',
+                metrics: { valid: validCount, total: messages.length },
+                exitCode: 0,
+            });
+            process.exit(0);
+        }
+        else {
+            humanError(`❌ ${errors.length} validation error(s) found`);
+            logEvent('validate-error-summary', {
+                command: 'validate',
+                phase: 'error',
+                metrics: {
+                    valid: validCount,
+                    total: messages.length,
+                    errors: errors.length,
+                },
+                exitCode: 1,
+            });
+            if (!quiet) {
+                const grouped = new Map();
+                errors.forEach((err) => {
+                    if (!grouped.has(err.index))
+                        grouped.set(err.index, []);
+                    grouped
+                        .get(err.index)
+                        .push({ path: err.path, message: err.message });
+                });
+                let shown = 0;
+                grouped.forEach((errs, index) => {
+                    if (shown < 10) {
+                        humanError(`\n  Message ${index}:`);
+                        errs.forEach((err) => {
+                            humanError(`    ${err.path || 'root'}: ${err.message}`);
+                            shown++;
+                            if (shown >= 10)
+                                return;
+                        });
+                    }
+                });
+                if (shown < errors.length) {
+                    humanError(`\n  ... and ${errors.length - shown} more errors`);
+                }
+            }
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        humanError('❌ Validation failed:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('validate-runtime-error', {
+            command: 'validate',
+            phase: 'error',
+            error: errorMeta,
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+// CLI--T05-AC02: stats command to show message counts by type
+program
+    .command('stats')
+    .description('Show statistics for message file')
+    .requiredOption('-i, --input <path>', 'path to message JSON file')
+    .option('-v, --verbose', 'show detailed statistics', false)
+    .action(async (options) => {
+    const { input } = options;
+    const verbose = program.opts().verbose || options.verbose;
+    applyLogLevel(verbose, program.opts().quiet);
+    logEvent('stats-start', {
+        command: 'stats',
+        phase: 'start',
+        options: { input },
+    });
+    try {
+        const fs = await import('node:fs');
+        // Validate input file exists
+        if (!fs.existsSync(input)) {
+            humanError(`❌ Input file not found: ${input}`);
+            process.exit(1);
+        }
+        // Load and parse JSON
+        const content = fs.readFileSync(input, 'utf-8');
+        let data;
+        try {
+            data = JSON.parse(content);
+        }
+        catch {
+            humanError(`❌ Invalid JSON: ${input}`);
+            process.exit(1);
+        }
+        // Extract messages
+        const messages = Array.isArray(data)
+            ? data
+            : data.messages || [];
+        // Count by messageKind
+        const stats = {
+            total: messages.length,
+            text: 0,
+            media: 0,
+            tapback: 0,
+            notification: 0,
+            withMedia: 0,
+            withEnrichment: 0,
+            dateRange: { min: null, max: null },
+        };
+        const senders = new Set();
+        let totalEnrichments = 0;
+        messages.forEach((msg) => {
+            if (msg.messageKind === 'text')
+                stats.text++;
+            if (msg.messageKind === 'media')
+                stats.media++;
+            if (msg.messageKind === 'tapback')
+                stats.tapback++;
+            if (msg.messageKind === 'notification')
+                stats.notification++;
+            if (msg.media) {
+                stats.withMedia++;
+                if (msg.media.enrichment && Array.isArray(msg.media.enrichment)) {
+                    stats.withEnrichment++;
+                    totalEnrichments += msg.media.enrichment.length;
+                }
+            }
+            const sender = msg.handle ?? (msg.isFromMe ? 'Me' : 'Unknown');
+            senders.add(sender);
+            if (msg.date) {
+                if (!stats.dateRange.min || msg.date < stats.dateRange.min) {
+                    stats.dateRange.min = msg.date;
+                }
+                if (!stats.dateRange.max || msg.date > stats.dateRange.max) {
+                    stats.dateRange.max = msg.date;
+                }
+            }
+        });
+        // Output summary
+        humanInfo('📊 Message Statistics');
+        humanInfo(`\n  Total messages: ${stats.total.toLocaleString()}`);
+        humanInfo('\n  Message Types:');
+        humanInfo(`    Text: ${stats.text}`);
+        humanInfo(`    Media: ${stats.media}`);
+        humanInfo(`    Tapbacks: ${stats.tapback}`);
+        humanInfo(`    Notifications: ${stats.notification}`);
+        humanInfo('\n  Enrichment:');
+        humanInfo(`    Messages with media: ${stats.withMedia}`);
+        humanInfo(`    Messages with enrichment: ${stats.withEnrichment}`);
+        if (stats.withEnrichment > 0) {
+            humanInfo(`    Total enrichments: ${totalEnrichments}`);
+            humanInfo(`    Avg enrichments per message: ${(totalEnrichments / stats.withEnrichment).toFixed(2)}`);
+        }
+        humanInfo('\n  Date Range:');
+        if (stats.dateRange.min && stats.dateRange.max) {
+            humanInfo(`    From: ${stats.dateRange.min}`);
+            humanInfo(`    To: ${stats.dateRange.max}`);
+            const minDate = new Date(stats.dateRange.min);
+            const maxDate = new Date(stats.dateRange.max);
+            const days = Math.floor((maxDate.getTime() - minDate.getTime()) / (1000 * 60 * 60 * 24));
+            humanInfo(`    Duration: ${days + 1} days`);
+        }
+        else {
+            humanInfo('    None');
+        }
+        if (verbose) {
+            humanInfo(`\n  Participants: ${senders.size}`);
+            if (senders.size > 0 && senders.size <= 20) {
+                Array.from(senders)
+                    .sort()
+                    .forEach((sender) => {
+                    const count = messages.filter((m) => {
+                        const msgSender = m.handle ?? (m.isFromMe ? 'Me' : 'Unknown');
+                        return msgSender === sender;
+                    }).length;
+                    humanInfo(`    ${sender}: ${count}`);
+                });
+            }
+        }
+        logEvent('stats-summary', {
+            command: 'stats',
+            phase: 'summary',
+            metrics: {
+                total: stats.total,
+                text: stats.text,
+                media: stats.media,
+                tapback: stats.tapback,
+                notification: stats.notification,
+                withMedia: stats.withMedia,
+                withEnrichment: stats.withEnrichment,
+                participants: senders.size,
+            },
+            options: { input, verbose },
+            exitCode: 0,
+        });
+        process.exit(0);
+    }
+    catch (error) {
+        humanError('❌ Stats failed:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('stats-error', {
+            command: 'stats',
+            phase: 'error',
+            error: errorMeta,
+            options: { input, verbose },
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+// CLI--T05-AC03: clean command to remove checkpoints and temp files
+program
+    .command('clean')
+    .description('Remove temporary files and checkpoints')
+    .option('-c, --checkpoint-dir <path>', 'checkpoint directory to clean', './.checkpoints')
+    .option('-f, --force', 'remove without confirmation', false)
+    .option('--all', 'also remove backup files (.backup, .old)', false)
+    .action(async (options) => {
+    const { checkpointDir, force, all } = options;
+    const verbose = program.opts().verbose;
+    applyLogLevel(verbose, program.opts().quiet);
+    try {
+        const fs = await import('node:fs');
+        const path = await import('node:path');
+        // Check if checkpoint dir exists
+        if (!fs.existsSync(checkpointDir)) {
+            if (verbose) {
+                humanInfo(`ℹ️  Checkpoint directory not found: ${checkpointDir}`);
+            }
+            logEvent('clean-missing-dir', {
+                command: 'clean',
+                phase: 'progress',
+                options: { checkpointDir },
+            });
+            process.exit(0);
+        }
+        if (!fs.statSync(checkpointDir).isDirectory()) {
+            humanError(`❌ Not a directory: ${checkpointDir}`);
+            process.exit(1);
+        }
+        // List files to be removed
+        const files = fs.readdirSync(checkpointDir);
+        const toRemove = files.filter((f) => f.startsWith('enrich-checkpoint-') ||
+            (all && (f.endsWith('.backup') || f.endsWith('.old'))));
+        if (toRemove.length === 0) {
+            humanInfo('ℹ️  No checkpoint files to clean');
+            logEvent('clean-none', {
+                command: 'clean',
+                phase: 'summary',
+                metrics: { removed: 0 },
+                options: { checkpointDir },
+                exitCode: 0,
+            });
+            process.exit(0);
+        }
+        // Show what will be removed
+        humanInfo('♻️  Files to be removed:');
+        toRemove.forEach((f) => {
+            const filepath = path.join(checkpointDir, f);
+            const size = fs.statSync(filepath).size;
+            humanInfo(`    ${f} (${(size / 1024).toFixed(1)} KB)`);
+        });
+        logEvent('clean-list', {
+            command: 'clean',
+            phase: 'progress',
+            metrics: { count: toRemove.length },
+            options: { checkpointDir, all },
+        });
+        if (!force) {
+            humanInfo('\nRun with --force to remove these files');
+            logEvent('clean-requires-force', {
+                command: 'clean',
+                phase: 'progress',
+                options: { checkpointDir, all },
+            });
+            process.exit(0);
+        }
+        // Remove files
+        let removed = 0;
+        toRemove.forEach((f) => {
+            const filepath = path.join(checkpointDir, f);
+            try {
+                fs.unlinkSync(filepath);
+                removed++;
+                if (verbose) {
+                    humanInfo(`✓ Removed ${f}`);
+                    logEvent('clean-file-removed', {
+                        command: 'clean',
+                        phase: 'progress',
+                        context: { file: f },
+                    });
+                }
+            }
+            catch {
+                humanWarn(`⚠️  Failed to remove ${f}`);
+                logEvent('clean-file-remove-failed', {
+                    command: 'clean',
+                    phase: 'warning',
+                    context: { file: f },
+                });
+            }
+        });
+        humanInfo(`✅ Cleaned ${removed} checkpoint file(s)`);
+        logEvent('clean-summary', {
+            command: 'clean',
+            phase: 'summary',
+            metrics: { removed },
+            options: { checkpointDir, all },
+            exitCode: 0,
+        });
+        process.exit(0);
+    }
+    catch (error) {
+        humanError('❌ Clean failed:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('clean-error', {
+            command: 'clean',
+            phase: 'error',
+            error: errorMeta,
+            options: { checkpointDir, all },
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+// CLI--T05-AC04: doctor command to diagnose common issues
+program
+    .command('doctor')
+    .description('Diagnose common configuration issues')
+    .option('-v, --verbose', 'show detailed diagnostics', false)
+    .action(async (options) => {
+    const verbose = program.opts().verbose || options.verbose;
+    applyLogLevel(verbose, program.opts().quiet);
+    try {
+        const fs = await import('node:fs');
+        const path = await import('node:path');
+        const os = await import('node:os');
+        humanInfo('🔍 iMessage Timeline Diagnostics\n');
+        logEvent('doctor-start', { command: 'doctor', phase: 'start' });
+        const checks = [];
+        // Check 1: Node version
+        const nodeVersion = process.version;
+        const nodeMajor = Number.parseInt(nodeVersion.slice(1).split('.')[0] ?? '0', 10);
+        const nodeOk = nodeMajor >= 18;
+        checks.push({
+            name: 'Node.js version',
+            pass: nodeOk,
+            message: `${nodeVersion} ${nodeOk ? '✓' : '(requires ≥18)'}`,
+        });
+        // Check 2: Current directory
+        const cwd = process.cwd();
+        const packageJsonExists = fs.existsSync(path.join(cwd, 'package.json'));
+        checks.push({
+            name: 'package.json',
+            pass: packageJsonExists,
+            message: packageJsonExists
+                ? `Found in ${cwd}`
+                : 'Not found in current directory',
+        });
+        // Check 3: Config file
+        const configFormats = [
+            'imessage-config.yaml',
+            'imessage-config.yml',
+            'imessage-config.json',
+        ];
+        const foundConfig = configFormats.find((f) => fs.existsSync(path.join(cwd, f)));
+        checks.push({
+            name: 'Config file',
+            pass: Boolean(foundConfig),
+            message: foundConfig
+                ? `Found: ${foundConfig}`
+                : 'Not found (run: imessage-timeline init)',
+        });
+        // Check 4: API Keys
+        const geminiKey = process.env.GEMINI_API_KEY;
+        const firecrawlKey = process.env.FIRECRAWL_API_KEY;
+        checks.push({
+            name: 'GEMINI_API_KEY',
+            pass: Boolean(geminiKey),
+            message: geminiKey
+                ? 'Set'
+                : 'Not set (required for image/audio enrichment)',
+        });
+        checks.push({
+            name: 'FIRECRAWL_API_KEY',
+            pass: Boolean(firecrawlKey),
+            message: firecrawlKey
+                ? 'Set'
+                : 'Not set (optional, improves link enrichment - get from firecrawl.dev)',
+        });
+        // Check 5: Default attachment directory
+        const defaultAttachDir = path.join(os.homedir(), 'Library', 'Messages', 'Attachments');
+        const attachDirExists = fs.existsSync(defaultAttachDir);
+        checks.push({
+            name: 'Messages attachments',
+            pass: attachDirExists,
+            message: attachDirExists
+                ? `Found: ${defaultAttachDir}`
+                : `Not found: ${defaultAttachDir}`,
+        });
+        // Check 6: Output directory permission
+        const canWrite = (() => {
+            try {
+                const testFile = path.join(cwd, '.test-write');
+                fs.writeFileSync(testFile, 'test');
+                fs.unlinkSync(testFile);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        })();
+        checks.push({
+            name: 'Write permission',
+            pass: canWrite,
+            message: canWrite
+                ? `Can write to ${cwd}`
+                : `Cannot write to ${cwd} (check permissions)`,
+        });
+        // Print results
+        let passCount = 0;
+        checks.forEach((check) => {
+            const icon = check.pass ? '✅' : '⚠️ ';
+            humanInfo(`${icon} ${check.name.padEnd(25)} ${check.message}`);
+            if (check.pass)
+                passCount++;
+            logEvent('doctor-check', {
+                command: 'doctor',
+                phase: 'progress',
+                context: { name: check.name },
+                metrics: { pass: check.pass },
+                message: check.message,
+            });
+        });
+        humanInfo(`\n📊 Summary: ${passCount}/${checks.length} checks passed`);
+        logEvent('doctor-summary', {
+            command: 'doctor',
+            phase: 'summary',
+            metrics: { passed: passCount, total: checks.length },
+        });
+        // Recommendations
+        const failures = checks.filter((c) => !c.pass);
+        if (failures.length > 0) {
+            humanInfo('\n💡 Recommendations:');
+            failures.forEach((check) => {
+                if (check.name === 'Config file') {
+                    humanInfo('   • Run: imessage-timeline init');
+                }
+                else if (check.name === 'GEMINI_API_KEY') {
+                    humanInfo('   • Get API key from: https://ai.google.dev/tutorials/setup');
+                    humanInfo('   • Set: export GEMINI_API_KEY=your_key');
+                }
+                else if (check.name === 'FIRECRAWL_API_KEY') {
+                    humanInfo('   • (Optional) Get from: https://www.firecrawl.dev');
+                }
+                logEvent('doctor-recommendation', {
+                    command: 'doctor',
+                    phase: 'progress',
+                    context: { name: check.name },
+                    message: check.message,
+                });
+            });
+        }
+        if (verbose) {
+            humanInfo('\n📝 Environment:');
+            humanInfo(`   Platform: ${os.platform()}`);
+            humanInfo(`   Arch: ${os.arch()}`);
+            humanInfo(`   Home: ${os.homedir()}`);
+            humanInfo(`   CWD: ${cwd}`);
+            logEvent('doctor-environment', {
+                command: 'doctor',
+                phase: 'progress',
+                context: {
+                    platform: os.platform(),
+                    arch: os.arch(),
+                    home: os.homedir(),
+                    cwd,
+                },
+            });
+        }
+        logEvent('doctor-exit', {
+            command: 'doctor',
+            phase: 'summary',
+            metrics: { failures: failures.length },
+            exitCode: failures.length > 0 ? 1 : 0,
+        });
+        process.exit(failures.length > 0 ? 1 : 0);
+    }
+    catch (error) {
+        humanError('❌ Doctor failed:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('doctor-error', {
+            command: 'doctor',
+            phase: 'error',
+            error: errorMeta,
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+// ============================================================================
+// Config generation command (CONFIG--T03)
+// ============================================================================
+program
+    .command('init')
+    .description('Generate starter configuration file')
+    .option('-f, --format <type>', 'config file format (json|yaml)', 'yaml')
+    .option('--force', 'overwrite existing config file without prompting', false)
+    .option('-o, --output <path>', 'output file path (default: auto-detected from format)')
+    .action(async (options) => {
+    const { format, force, output } = options;
+    // Validate format
+    if (format !== 'json' && format !== 'yaml') {
+        humanError(`❌ Invalid format: ${format}`);
+        humanError('Supported formats: json, yaml');
+        process.exit(1);
+    }
+    try {
+        // Lazy import to avoid circular dependencies
+        const { generateConfigFile, getDefaultConfigPath, configFileExists } = await import('./config/generator.js');
+        // Determine output path
+        const filePath = output || getDefaultConfigPath(format);
+        // CONFIG-T03-AC04: Check for existing file and prompt if needed
+        const exists = await configFileExists(filePath);
+        if (exists && !force) {
+            humanError(`❌ Config file already exists: ${filePath}`);
+            humanError('\nOptions:');
+            humanError('  • Use --force to overwrite');
+            humanError('  • Use --output to specify different path');
+            humanError('  • Manually remove the existing file');
+            process.exit(1);
+        }
+        // CONFIG-T03-AC01, AC02, AC03: Generate config file
+        const result = await generateConfigFile({
+            filePath,
+            format,
+            force,
+        });
+        if (result.success) {
+            humanInfo(result.message);
+            humanInfo('\n📝 Next steps:');
+            humanInfo(`  1. Edit ${filePath} to add your API keys`);
+            humanInfo('  2. Set GEMINI_API_KEY environment variable');
+            humanInfo('  3. (Optional) Set FIRECRAWL_API_KEY for enhanced link scraping');
+            humanInfo('\n💡 See inline comments in the config file for details');
+            logEvent('init-summary', {
+                command: 'init',
+                phase: 'summary',
+                options: { format, filePath, force },
+                message: result.message,
+                exitCode: 0,
+            });
+            process.exit(0);
+        }
+        else {
+            humanError(`❌ ${result.message}`);
+            logEvent('init-error', {
+                command: 'init',
+                phase: 'error',
+                options: { format, filePath, force },
+                message: result.message,
+                exitCode: 1,
+            });
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        humanError('❌ Failed to generate config:', error instanceof Error ? error.message : String(error));
+        if (program.opts().verbose && error instanceof Error) {
+            humanError(error.stack);
+        }
+        const errorMeta = {
+            type: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof Error && error.stack
+                ? { stack: error.stack }
+                : {}),
+        };
+        logEvent('init-runtime-error', {
+            command: 'init',
+            phase: 'error',
+            error: errorMeta,
+            options: { format, output, force },
+            exitCode: 2,
+        });
+        process.exit(2);
+    }
+});
+// ============================================================================
+// CLI--T01-AC04: Proper exit codes (0=success, 1=validation, 2=runtime)
+// ============================================================================
+// Global error handler for uncaught errors (guard to prevent duplicate listeners)
+const globalAny = globalThis;
+const listenersFlag = '__IMESSAGE_CLI_LISTENERS_ATTACHED__';
+if (!globalAny[listenersFlag]) {
+    globalAny[listenersFlag] = true;
+    process.on('uncaughtException', (err) => {
+        humanError('❌ Fatal Error:', err.message);
+        if (program.opts().verbose) {
+            humanError(err.stack);
+        }
+        logEvent('fatal-error', {
+            command: 'global',
+            phase: 'error',
+            error: {
+                type: err.name,
+                message: err.message,
+                ...(err.stack ? { stack: err.stack } : {}),
+            },
+            exitCode: 2,
+        });
+        process.exit(2); // Runtime error
+    });
+    process.on('unhandledRejection', (reason) => {
+        humanError('❌ Unhandled Promise Rejection:', reason);
+        logEvent('unhandled-rejection', {
+            command: 'global',
+            phase: 'error',
+            error: { message: String(reason) },
+            exitCode: 2,
+        });
+        process.exit(2); // Runtime error
+    });
+}
+// ============================================================================
+// Main Execution
+// ============================================================================
+async function main() {
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            humanError(`❌ Error: ${error.message}`);
+            if (program.opts().verbose) {
+                humanError(error.stack);
+            }
+        }
+        else {
+            humanError('❌ Unknown error:', error);
+        }
+        logEvent('cli-runtime-error', {
+            command: 'global',
+            phase: 'error',
+            error: {
+                type: error instanceof Error ? error.name : 'Unknown',
+                message: error instanceof Error ? error.message : String(error),
+                ...(error instanceof Error && error.stack
+                    ? { stack: error.stack }
+                    : {}),
+            },
+            exitCode: 1,
+        });
+        process.exit(1);
+    }
+}
+void main();
+//# sourceMappingURL=cli.js.map