@devtrace-ai/cli 1.0.0

package/dist/index.js

@@ -0,0 +1,798 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const detector_1 = require("./detector");
+const git_1 = require("./git");
+const hooks_1 = require("./hooks");
+const ignore_1 = require("./ignore");
+const metrics_1 = require("./metrics");
+const reporter_1 = require("./reporter");
+const storage_1 = require("./storage");
+const test_runner_1 = require("./test_runner");
+const cli_1 = require("./cli");
+const config_1 = require("./config");
+const chat_1 = require("./chat");
+const analyzer_1 = require("./analyzer");
+const scan_1 = require("./core/scan");
+const survival_1 = require("./core/survival");
+const html_report_1 = require("./html_report");
+const card_1 = require("./card");
+const digest_1 = require("./digest");
+const claude_hooks_1 = require("./claude-hooks");
+const claude_hook_install_1 = require("./claude-hook-install");
+const claude_correlate_1 = require("./claude-correlate");
+/** Human-readable label for an AITool key, used in the reveal box's by-tool breakdown. */
+function toolLabel(tool) {
+    const labels = {
+        'claude-code': 'Claude',
+        'gemini-cli': 'Gemini',
+        'cursor': 'Cursor',
+        'copilot': 'Copilot',
+        'codex': 'Codex',
+        'aider': 'Aider',
+        'ollama': 'Ollama',
+        'other': 'Other AI',
+        'unknown-ai': 'Unknown AI (heuristic)',
+        'none': 'Human'
+    };
+    return labels[tool] || tool;
+}
+/** Best-effort read of the Claude settings.json for before/after summary counts. */
+function readClaudeSettingsForSummary() {
+    try {
+        const raw = fs.readFileSync((0, claude_hook_install_1.resolveClaudeSettingsPath)(), 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Runs the retroactive scan (Pass 1 classification + optional Pass 2 survival), dedupes
+ * against sessions already in the store, batch-writes new sessions, and prints the reveal box.
+ * See docs/plans/04-architecture-audit-build-plan.md §2.3 and 02-product-gtm-plan.md §3 Step 2.
+ */
+async function runRetroScan(cwd, opts) {
+    const config = config_1.ConfigManager.loadConfig(cwd);
+    const ignoreFilter = new ignore_1.IgnoreFilter(cwd, config.storageDir);
+    console.log(`\n📜 Scanning commit history (since ${opts.since})...`);
+    let lastReported = -1;
+    const scanResult = await (0, scan_1.scanCommitHistory)({
+        cwd,
+        since: opts.since,
+        ignoreFilter,
+        onProgress: (n) => {
+            // Throttle: redraw every 50 commits so huge repos don't spam the terminal.
+            if (n > 0 && n !== lastReported && n % 50 === 0) {
+                process.stdout.write(`\r   commits parsed: ${n}`);
+                lastReported = n;
+            }
+        }
+    });
+    if (lastReported !== -1)
+        process.stdout.write('\n');
+    console.log(`✅ Parsed ${scanResult.commits.length} commit(s) in window (${scanResult.totalCommitsSeen} seen total).`);
+    // Dedupe against sessions already in the store (by commitHash) so re-running init/scan
+    // never double-imports.
+    const existingSessions = await storage_1.StorageManager.loadSessions(cwd);
+    const existingHashes = new Set(existingSessions.map(s => s.commitHash));
+    const newCommits = scanResult.commits.filter(c => !existingHashes.has(c.commitHash));
+    if (newCommits.length === 0 && scanResult.commits.length > 0) {
+        console.log('ℹ️  All commits in this window are already recorded — nothing new to import.');
+    }
+    // Pass 2: survival, unless --fast. Computed over ALL window commits (not just new ones)
+    // so a re-run still shows the full reveal; only the storage write below is deduped.
+    let survivingLines = new Map();
+    let unknownSurvivalCommits = new Set();
+    let survival30dByCommit = new Map();
+    if (!opts.fast && scanResult.commits.length > 0) {
+        const touchedFiles = new Set();
+        for (const c of scanResult.commits) {
+            for (const f of c.diff.files) {
+                if (!f.isBinary)
+                    touchedFiles.add(f.path);
+            }
+        }
+        if (touchedFiles.size > 0) {
+            console.log(`\n🔬 Computing survival (git blame HEAD, ${touchedFiles.size} file(s))...`);
+            let lastFilesReported = -1;
+            const survivalResult = await (0, survival_1.computeSurvival)(Array.from(touchedFiles), {
+                cwd,
+                ignoreFilter,
+                onProgress: (blamed, total) => {
+                    // Throttle: redraw at most every 25 files (always drawing the final count)
+                    // so large repos don't spam the terminal with per-file updates.
+                    if (blamed !== lastFilesReported && (blamed % 25 === 0 || blamed === total)) {
+                        process.stdout.write(`\r   files blamed: ${blamed}/${total}`);
+                        lastFilesReported = blamed;
+                    }
+                }
+            });
+            if (lastFilesReported !== -1)
+                process.stdout.write('\n');
+            survivingLines = survivalResult.survivingLines;
+            const skippedSet = new Set(survivalResult.skippedFiles);
+            for (const c of scanResult.commits) {
+                if (c.diff.files.some(f => !f.isBinary && skippedSet.has(f.path))) {
+                    unknownSurvivalCommits.add(c.commitHash);
+                }
+            }
+            console.log(`✅ Blamed ${survivalResult.filesBlamed} file(s), skipped ${survivalResult.filesSkipped} (size guards or not tracked at HEAD → survival unknown).`);
+            // Windowed 30-day survival: blame at the commit boundary closest to C+30d, not HEAD.
+            // See docs/plans/04-architecture-audit-build-plan.md §Phase 1 risk #2.
+            const windowedInputs = scanResult.commits.map(c => ({
+                commitHash: c.commitHash,
+                authorDate: c.authorDate,
+                insertions: c.diff.totalInsertions,
+                files: c.diff.files.filter(f => !f.isBinary && !ignoreFilter.shouldIgnore(f.path)).map(f => f.path)
+            }));
+            console.log(`🔬 Computing windowed 30-day survival...`);
+            let lastPairsReported = -1;
+            const windowedResult = await (0, survival_1.computeWindowedSurvival)(windowedInputs, {
+                cwd,
+                onProgress: (blamed, total) => {
+                    if (blamed !== lastPairsReported && (blamed % 25 === 0 || blamed === total) && total > 0) {
+                        process.stdout.write(`\r   (file, boundary) pairs blamed: ${blamed}/${total}`);
+                        lastPairsReported = blamed;
+                    }
+                }
+            });
+            if (lastPairsReported !== -1)
+                process.stdout.write('\n');
+            survival30dByCommit = windowedResult.survival30d;
+            const measured = Array.from(survival30dByCommit.values()).filter(v => v.status === 'measured').length;
+            console.log(`✅ Windowed 30-day survival measured for ${measured} commit(s) (older, unmeasurable-eligible commits marked unknown; younger commits are window-open).`);
+        }
+    }
+    // Build TraceSessions for the new commits and batch-write.
+    const survivalComputed = !opts.fast;
+    const newSessions = newCommits.map((c) => sessionFromScannedCommit(c, cwd, survivingLines, unknownSurvivalCommits, survivalComputed, survival30dByCommit));
+    // Backfill churn on already-imported window sessions (e.g. imported by a --fast run that
+    // could not measure survival) now that fresh blame data exists.
+    let backfilled = 0;
+    if (survivalComputed) {
+        const byHash = new Map(scanResult.commits.map(c => [c.commitHash, c]));
+        for (const s of existingSessions) {
+            const c = byHash.get(s.commitHash);
+            if (!c || unknownSurvivalCommits.has(c.commitHash))
+                continue;
+            const rate = (0, survival_1.survivalRateFor)(survivingLines.get(c.commitHash) || 0, c.diff.totalInsertions);
+            if (rate === null)
+                continue;
+            s.churn = {
+                linesReverted: Math.max(0, c.diff.totalInsertions - (survivingLines.get(c.commitHash) || 0)),
+                survivalRate: rate,
+                survival30d: survival30dByCommit.get(c.commitHash)
+            };
+            backfilled++;
+        }
+    }
+    if (newSessions.length > 0 || backfilled > 0) {
+        const merged = existingSessions.concat(newSessions);
+        storage_1.StorageManager.saveAllSessions(merged, cwd);
+        const stats = analyzer_1.MetricsAnalyzer.analyze(merged);
+        reporter_1.ReportGenerator.generateReport(stats, merged, cwd);
+    }
+    printRevealBox(scanResult.commits, survivingLines, unknownSurvivalCommits, survival30dByCommit, opts);
+}
+/** Converts one classified ScannedCommit into a persistable TraceSession (source: retro-scan). */
+function sessionFromScannedCommit(c, cwd, survivingLines, unknownSurvivalCommits, survivalComputed, survival30dByCommit) {
+    // Never fabricate a survival number: --fast runs (no blame pass) and guard-skipped
+    // commits store no churn at all, which downstream reads as "unknown".
+    const rate = !survivalComputed || unknownSurvivalCommits.has(c.commitHash)
+        ? null
+        : (0, survival_1.survivalRateFor)(survivingLines.get(c.commitHash) || 0, c.diff.totalInsertions);
+    return {
+        id: crypto.randomUUID(),
+        version: 1,
+        timestamp: c.authorDate,
+        commitHash: c.commitHash,
+        parentCommitHash: c.parentHash,
+        captureMode: 'retro-scan',
+        aiTool: c.aiTool,
+        aiToolConfidence: c.aiToolConfidence,
+        aiToolTier: c.aiToolTier,
+        branchName: git_1.GitTracker.getCurrentBranch(cwd),
+        treeHashBefore: '',
+        treeHashAfter: '',
+        diff: c.diff,
+        changeType: c.changeType,
+        changeTypeConfidence: c.changeTypeConfidence,
+        testResult: null,
+        churn: rate !== null ? {
+            linesReverted: Math.max(0, c.diff.totalInsertions - (survivingLines.get(c.commitHash) || 0)),
+            survivalRate: rate,
+            // Windowed 30-day survival (T1.1): 'measured' | 'window-open' | 'unknown' — honest
+            // tri-state, never a fabricated boolean. Absent only if survival wasn't computed at all.
+            survival30d: survival30dByCommit.get(c.commitHash)
+        } : undefined
+    };
+}
+/** Prints the "reveal" box — the aha-moment number the user did not know and cannot un-know. */
+function printRevealBox(commits, survivingLines, unknownSurvivalCommits, survival30dByCommit, opts) {
+    const total = commits.length;
+    const aiCommits = commits.filter(c => c.aiTool !== 'none');
+    const aiPct = total > 0 ? ((aiCommits.length / total) * 100).toFixed(0) : '0';
+    console.log(`\n┌─ Your AI code, ${describeWindow(opts.since)} ─────────────────────────`);
+    console.log(`│   AI-authored commits:        ${aiCommits.length}  (${aiPct}% of ${total} commits)`);
+    if (opts.fast) {
+        console.log(`│   Survival rates:              skipped (--fast: numstat-only, no blame)`);
+    }
+    else {
+        const aiSurvival = weightedSurvival(aiCommits, survivingLines, unknownSurvivalCommits);
+        const humanCommits = commits.filter(c => c.aiTool === 'none');
+        const humanSurvival = weightedSurvival(humanCommits, survivingLines, unknownSurvivalCommits);
+        console.log(`│   AI lines still at HEAD:      ${fmtPct(aiSurvival)}  ← lines still attributed to their original commit at HEAD`);
+        console.log(`│   Human lines still at HEAD:   ${fmtPct(humanSurvival)}`);
+        // Windowed 30-day survival line — only shown when at least one AI commit has a measured
+        // verdict, so repos with an all-young or all-unknown window don't print a hollow line.
+        const measuredAiWindowed = aiCommits
+            .map(c => survival30dByCommit.get(c.commitHash))
+            .filter((v) => v !== undefined && v.status === 'measured');
+        if (measuredAiWindowed.length > 0) {
+            const avg30d = measuredAiWindowed.reduce((sum, v) => sum + v.rate, 0) / measuredAiWindowed.length;
+            console.log(`│   AI lines surviving 30 days:  ${fmtPct(avg30d)}  (n=${measuredAiWindowed.length} commit${measuredAiWindowed.length === 1 ? '' : 's'} measured)`);
+        }
+        const byTool = new Map();
+        for (const c of aiCommits) {
+            if (!byTool.has(c.aiTool))
+                byTool.set(c.aiTool, []);
+            byTool.get(c.aiTool).push(c);
+        }
+        if (byTool.size > 0) {
+            console.log(`│   By tool:`);
+            for (const [tool, toolCommits] of byTool.entries()) {
+                const rate = weightedSurvival(toolCommits, survivingLines, unknownSurvivalCommits);
+                const unknownCount = toolCommits.filter(c => unknownSurvivalCommits.has(c.commitHash)).length;
+                const unknownNote = unknownCount > 0 ? `, ${unknownCount} unknown` : '';
+                console.log(`│      ${toolLabel(tool).padEnd(12)} ${fmtPct(rate)} survival  (${toolCommits.length} commit${toolCommits.length === 1 ? '' : 's'}${unknownNote})`);
+            }
+        }
+        let rewrittenLines = 0;
+        for (const c of aiCommits) {
+            if (unknownSurvivalCommits.has(c.commitHash))
+                continue;
+            const surviving = survivingLines.get(c.commitHash) || 0;
+            rewrittenLines += Math.max(0, c.diff.totalInsertions - surviving);
+        }
+        console.log(`│   AI lines rewritten since:    ~${rewrittenLines.toLocaleString()}`);
+    }
+    console.log(`└──────────────────────────────────────────────────────────────`);
+    console.log(`  → devtrace status         see traced session count`);
+    console.log(`  → devtrace report         full breakdown (DEVTRACE_LOG.md)`);
+    console.log(`  → devtrace churn          re-run windowed survival later`);
+    console.log(`\n🎉 Setup complete! DevTrace-AI will now automatically record metadata on every commit in the background.`);
+}
+function describeWindow(since) {
+    const daysMatch = /^(\d+) days ago$/.exec(since);
+    return daysMatch ? `last ${daysMatch[1]} days` : `since ${since}`;
+}
+function fmtPct(rate) {
+    if (rate === null)
+        return 'unknown';
+    return `${(rate * 100).toFixed(0)}%`;
+}
+/** Insertion-weighted average survival rate across a set of commits, excluding unknowns. */
+function weightedSurvival(commits, survivingLines, unknownSurvivalCommits) {
+    let totalInsertions = 0;
+    let totalSurviving = 0;
+    let anyKnown = false;
+    for (const c of commits) {
+        if (unknownSurvivalCommits.has(c.commitHash))
+            continue;
+        if (c.diff.totalInsertions <= 0)
+            continue;
+        anyKnown = true;
+        totalInsertions += c.diff.totalInsertions;
+        totalSurviving += Math.min(c.diff.totalInsertions, survivingLines.get(c.commitHash) || 0);
+    }
+    if (!anyKnown || totalInsertions === 0)
+        return null;
+    return totalSurviving / totalInsertions;
+}
+async function run() {
+    const args = process.argv.slice(2);
+    let command = args[0] || 'status';
+    // Handle 'hook' subcommand alias as documented in the README
+    if (command === 'hook') {
+        const sub = args[1];
+        if (sub === 'install') {
+            command = 'init';
+        }
+        else if (sub === 'uninstall') {
+            command = 'uninstall';
+        }
+    }
+    // Resolve target workspace (repository root) to support execution from subdirectories
+    const rawCwd = process.cwd();
+    const cwd = git_1.GitTracker.getRepositoryRoot(rawCwd);
+    switch (command) {
+        case 'init': {
+            console.log('\n🚀 Initializing DevTrace-AI Empirical Logging Framework...');
+            // Save configuration
+            config_1.ConfigManager.saveConfig(config_1.DEFAULT_CONFIG, cwd);
+            console.log(`✅ Configuration saved to: devtrace.config.json`);
+            // Create storage directory
+            const config = config_1.ConfigManager.loadConfig(cwd);
+            const storageDir = path.join(cwd, config.storageDir);
+            if (!fs.existsSync(storageDir)) {
+                fs.mkdirSync(storageDir, { recursive: true });
+            }
+            // Install Hook
+            try {
+                const hookPath = hooks_1.HookManager.installHook(cwd);
+                console.log(`✅ Git post-commit hook successfully installed at: ${hookPath}`);
+            }
+            catch (err) {
+                console.error(`❌ Failed to install git hook: ${err.message}`);
+                process.exit(1);
+            }
+            // Retroactive scan: the aha-moment. Parse --fast and --since <n>d.
+            const fast = args.includes('--fast');
+            const sinceFlagIdx = args.indexOf('--since');
+            let sinceArg = '90 days ago';
+            if (sinceFlagIdx !== -1 && args[sinceFlagIdx + 1]) {
+                const raw = args[sinceFlagIdx + 1];
+                const daysMatch = /^(\d+)d$/.exec(raw);
+                sinceArg = daysMatch ? `${daysMatch[1]} days ago` : raw;
+            }
+            await runRetroScan(cwd, { fast, since: sinceArg });
+            break;
+        }
+        case 'scan': {
+            const fast = args.includes('--fast');
+            const sinceFlagIdx = args.indexOf('--since');
+            let sinceArg = '90 days ago';
+            if (sinceFlagIdx !== -1 && args[sinceFlagIdx + 1]) {
+                const raw = args[sinceFlagIdx + 1];
+                const daysMatch = /^(\d+)d$/.exec(raw);
+                sinceArg = daysMatch ? `${daysMatch[1]} days ago` : raw;
+            }
+            await runRetroScan(cwd, { fast, since: sinceArg });
+            break;
+        }
+        case 'post-commit': {
+            // Automatic execution triggered by git hook
+            const currentCommit = git_1.GitTracker.resolveRef('HEAD', cwd);
+            if (!currentCommit) {
+                process.exit(0);
+            }
+            // Skip merge commits
+            if (git_1.GitTracker.isMergeCommit(currentCommit, cwd)) {
+                process.exit(0);
+            }
+            const config = config_1.ConfigManager.loadConfig(cwd);
+            // Resolve parent commit (use empty tree if initial commit)
+            const parentCommit = git_1.GitTracker.resolveRef('HEAD~1', cwd) || git_1.GitTracker.getEmptyTreeHash(cwd);
+            // Get raw diff
+            const rawDiff = git_1.GitTracker.getDiff(parentCommit, currentCommit, cwd);
+            // Filter out ignored files
+            const ignoreFilter = new ignore_1.IgnoreFilter(cwd, config.storageDir);
+            const filteredFiles = rawDiff.files.filter(f => !ignoreFilter.shouldIgnore(f.path));
+            // If no code files changed, skip logging to avoid database spam
+            if (filteredFiles.length === 0) {
+                process.exit(0);
+            }
+            const totalInsertions = filteredFiles.reduce((sum, f) => sum + f.insertions, 0);
+            const totalDeletions = filteredFiles.reduce((sum, f) => sum + f.deletions, 0);
+            const filteredDiff = {
+                filesChanged: filteredFiles.length,
+                totalInsertions,
+                totalDeletions,
+                netLines: totalInsertions - totalDeletions,
+                files: filteredFiles
+            };
+            // Run tests safely matching trust restrictions
+            let testResult = null;
+            const detectedCmd = test_runner_1.TestRunner.detectTestCommand(cwd);
+            const configuredCmd = config.testCommand;
+            const isTrusted = config_1.GlobalConfigManager.isWorkspaceTrusted(cwd);
+            if (configuredCmd || detectedCmd) {
+                if (isTrusted) {
+                    testResult = test_runner_1.TestRunner.runTests(cwd);
+                }
+                else {
+                    const cmdName = configuredCmd || detectedCmd;
+                    console.warn(`[DevTrace] Skipped test command "${cmdName}" because this workspace is untrusted.`);
+                    console.warn(`[DevTrace] Run 'devtrace trust' to trust this workspace and allow test execution.`);
+                }
+            }
+            // Resolve commit metadata for classification
+            const commitMeta = git_1.GitTracker.getCommitMetadata(currentCommit, cwd);
+            // Detect AI presence and change classification
+            let aiDetection = detector_1.AIDetector.detect(currentCommit, filteredDiff, cwd);
+            const classification = metrics_1.MetricsClassifier.classify(filteredDiff, commitMeta.message);
+            // Tier-2 correlation (T1.4): if the first-party Claude Code hook ledger recorded
+            // edits (since the last commit's watermark) touching files in this commit, and no
+            // tier-1 trailer already matched, upgrade to "instrumented" — trailers stay authoritative.
+            if (aiDetection.tier !== 1) {
+                const correlation = (0, claude_correlate_1.correlateCommitWithLedger)(cwd, filteredFiles.map(f => f.path));
+                if (correlation.matched) {
+                    aiDetection = {
+                        tool: 'claude-code',
+                        confidence: claude_correlate_1.TIER2_CONFIDENCE,
+                        tier: 2,
+                        reasons: [...aiDetection.reasons, `hook:claude-code-ledger (${correlation.matchedFiles.length} file(s) matched)`]
+                    };
+                }
+            }
+            // Attempt auto-parsing of chat/prompt histories
+            let autoPromptText = '';
+            if (aiDetection.tool === 'claude-code') {
+                const claudeChat = chat_1.ChatLogParser.parseLatestClaudeCode();
+                if (claudeChat)
+                    autoPromptText = claudeChat.promptText;
+            }
+            else if (aiDetection.tool === 'cursor') {
+                const cursorChat = chat_1.ChatLogParser.parseLatestCursorChat();
+                if (cursorChat)
+                    autoPromptText = cursorChat.promptText;
+            }
+            const session = {
+                id: crypto.randomUUID(),
+                version: 1,
+                timestamp: new Date().toISOString(),
+                commitHash: currentCommit,
+                parentCommitHash: parentCommit,
+                captureMode: 'auto-hook',
+                aiTool: aiDetection.tool,
+                aiToolConfidence: aiDetection.confidence,
+                aiToolTier: aiDetection.tier,
+                branchName: git_1.GitTracker.getCurrentBranch(cwd),
+                treeHashBefore: git_1.GitTracker.getTreeHash(parentCommit, cwd),
+                treeHashAfter: git_1.GitTracker.getTreeHash(currentCommit, cwd),
+                diff: filteredDiff,
+                changeType: classification.changeType,
+                changeTypeConfidence: classification.confidence,
+                testResult,
+                annotation: autoPromptText ? { promptText: autoPromptText } : undefined
+            };
+            storage_1.StorageManager.appendSession(session, cwd);
+            // Regenerate reports
+            const sessions = await storage_1.StorageManager.loadSessions(cwd);
+            const stats = analyzer_1.MetricsAnalyzer.analyze(sessions);
+            reporter_1.ReportGenerator.generateReport(stats, sessions, cwd);
+            break;
+        }
+        case 'annotate': {
+            const sessions = await storage_1.StorageManager.loadSessions(cwd);
+            if (sessions.length === 0) {
+                console.log('❌ No traced sessions found. Make some commits first!');
+                process.exit(1);
+            }
+            // Check if CLI flags were provided
+            const flagMap = {};
+            for (let i = 0; i < args.length; i++) {
+                if (args[i].startsWith('--')) {
+                    const key = args[i].substring(2);
+                    const val = args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : 'true';
+                    flagMap[key] = val;
+                }
+            }
+            const targetId = flagMap.id;
+            const lastSession = targetId ? (sessions.find(s => s.id === targetId) || sessions[sessions.length - 1]) : sessions[sessions.length - 1];
+            if (Object.keys(flagMap).length > 0 && !flagMap.id) {
+                // We have flags (excluding just --id)
+                const correctness = flagMap.correctness ? parseInt(flagMap.correctness, 10) : undefined;
+                const completeness = flagMap.completeness ? parseInt(flagMap.completeness, 10) : undefined;
+                const effort = flagMap.effort ? parseInt(flagMap.effort, 10) : undefined;
+                const promptText = flagMap.prompt;
+                const notes = flagMap.notes;
+                const complexity = flagMap.complexity;
+                const model = flagMap.model;
+                lastSession.annotation = {
+                    ...lastSession.annotation,
+                    correctness: correctness !== undefined && !isNaN(correctness) ? correctness : lastSession.annotation?.correctness,
+                    completeness: completeness !== undefined && !isNaN(completeness) ? completeness : lastSession.annotation?.completeness,
+                    effortToIntegrate: effort !== undefined && !isNaN(effort) ? effort : lastSession.annotation?.effortToIntegrate,
+                    promptText: promptText || lastSession.annotation?.promptText,
+                    notes: notes || lastSession.annotation?.notes,
+                    taskComplexity: complexity || lastSession.annotation?.taskComplexity,
+                    llmModelName: model || lastSession.annotation?.llmModelName
+                };
+                storage_1.StorageManager.updateSessionSync(lastSession.id, (session) => {
+                    session.annotation = lastSession.annotation;
+                }, cwd);
+                // Regenerate reports
+                const freshSessions = await storage_1.StorageManager.loadSessions(cwd);
+                const stats = analyzer_1.MetricsAnalyzer.analyze(freshSessions);
+                reporter_1.ReportGenerator.generateReport(stats, freshSessions, cwd);
+                console.log('\n✅ Annotations saved successfully via flags!');
+                process.exit(0);
+            }
+            console.log(`\n================ Annotating Session ================`);
+            console.log(`Commit:  ${lastSession.commitHash.substring(0, 8)} [${lastSession.branchName}]`);
+            console.log(`Files:   ${lastSession.diff.filesChanged} files changed (+${lastSession.diff.totalInsertions}/-${lastSession.diff.totalDeletions})`);
+            const tierLabel = lastSession.aiToolTier !== undefined ? ` [tier ${lastSession.aiToolTier}]` : '';
+            console.log(`AI Tool: ${lastSession.aiTool} (Confidence: ${(lastSession.aiToolConfidence * 100).toFixed(0)}%)${tierLabel}`);
+            console.log(`Type:    ${lastSession.changeType}`);
+            const choice = await cli_1.CliHelper.askChoice('What would you like to annotate?', [
+                'Add qualitative Likert ratings & Prompt details',
+                'Upload manual Chat logs/prompts from file',
+                'Mark this session as human-only (correct AI detection error)',
+                'Exit'
+            ]);
+            if (choice === 1) {
+                const correctness = await cli_1.CliHelper.askLikert('Rate correctness of AI generated code', '1=Totally incorrect, 5=Flawless execution');
+                const completeness = await cli_1.CliHelper.askLikert('Rate completeness of changes', '1=Placeholder code/missing functions, 5=Fully complete implementation');
+                const effort = await cli_1.CliHelper.askLikert('Rate implementation/integration effort', '1=Required a full rewrite, 5=Integrated with zero modifications');
+                const complexity = await cli_1.CliHelper.askComplexity();
+                const model = await cli_1.CliHelper.askQuestion('\nEnter the LLM model name (e.g. claude-3-5-sonnet, gpt-4o):\n> ');
+                const promptText = await cli_1.CliHelper.askQuestion('\nEnter the prompt payload passed to the AI:\n> ');
+                const notes = await cli_1.CliHelper.askQuestion('\nAdd qualitative notes/observations (e.g. logic hallucinations):\n> ');
+                lastSession.annotation = {
+                    promptText: promptText || lastSession.annotation?.promptText,
+                    correctness,
+                    completeness,
+                    effortToIntegrate: effort,
+                    notes: notes || undefined,
+                    taskComplexity: complexity,
+                    llmModelName: model || undefined
+                };
+                storage_1.StorageManager.updateSessionSync(lastSession.id, (session) => {
+                    session.annotation = lastSession.annotation;
+                }, cwd);
+            }
+            else if (choice === 2) {
+                const filePath = await cli_1.CliHelper.askQuestion('\nEnter the path to the chat log file (.json or text):\n> ');
+                const parsed = chat_1.ChatLogParser.parseUserFile(path.resolve(filePath));
+                if (parsed) {
+                    lastSession.annotation = {
+                        ...lastSession.annotation,
+                        promptText: parsed.promptText,
+                        chatLogFile: filePath
+                    };
+                    storage_1.StorageManager.updateSessionSync(lastSession.id, (session) => {
+                        session.annotation = lastSession.annotation;
+                    }, cwd);
+                    console.log('✅ Chat log details parsed and linked successfully.');
+                }
+                else {
+                    console.log('❌ Failed to parse or locate log file.');
+                }
+            }
+            else if (choice === 3) {
+                storage_1.StorageManager.updateSessionSync(lastSession.id, (session) => {
+                    session.aiTool = 'none';
+                    session.aiToolConfidence = 1.0; // manually confirmed by the developer, not a heuristic guess
+                    session.aiToolTier = 1;
+                }, cwd);
+                console.log('✅ Updated session to human-only.');
+            }
+            else {
+                cli_1.CliHelper.closeInterface();
+                process.exit(0);
+            }
+            // Regenerate reports
+            const freshSessions = await storage_1.StorageManager.loadSessions(cwd);
+            const stats = analyzer_1.MetricsAnalyzer.analyze(freshSessions);
+            reporter_1.ReportGenerator.generateReport(stats, freshSessions, cwd);
+            console.log('\n✅ Annotations saved! Telemetry log updated.');
+            cli_1.CliHelper.closeInterface();
+            break;
+        }
+        case 'report': {
+            const sessions = await storage_1.StorageManager.loadSessions(cwd);
+            const stats = analyzer_1.MetricsAnalyzer.analyze(sessions);
+            // Keep the existing markdown telemetry log in sync (unchanged behavior)...
+            const reportFile = reporter_1.ReportGenerator.generateReport(stats, sessions, cwd);
+            console.log(`✅ Telemetry report compiled: ${reportFile}`);
+            // ...and additionally produce the self-contained HTML report (Phase 1 §2.5).
+            const outFlagIdx = args.indexOf('--out');
+            const outPath = outFlagIdx !== -1 && args[outFlagIdx + 1] ? args[outFlagIdx + 1] : undefined;
+            const htmlFile = (0, html_report_1.writeHtmlReport)(stats, sessions, cwd, outPath);
+            console.log(`✅ HTML report generated: ${htmlFile}`);
+            break;
+        }
+        case 'card': {
+            const sessions = await storage_1.StorageManager.loadSessions(cwd);
+            const pngFlagIdx = args.indexOf('--png');
+            if (pngFlagIdx !== -1) {
+                console.log('PNG export coming soon — render the SVG at https://svgtopng.com or use any SVG converter.');
+            }
+            const outFlagIdx = args.indexOf('--out');
+            const outPath = outFlagIdx !== -1 && args[outFlagIdx + 1] ? args[outFlagIdx + 1] : undefined;
+            const cardFile = (0, card_1.writeCardSvg)(sessions, cwd, outPath);
+            console.log(`✅ Scorecard SVG generated: ${cardFile}`);
+            break;
+        }
+        case 'digest': {
+            const sessions = await storage_1.StorageManager.loadSessions(cwd);
+            const sinceFlagIdx = args.indexOf('--since');
+            const sinceArg = sinceFlagIdx !== -1 && args[sinceFlagIdx + 1] ? args[sinceFlagIdx + 1] : undefined;
+            const days = (0, digest_1.parseSinceDays)(sinceArg);
+            const digest = (0, digest_1.buildDigest)(sessions, days);
+            console.log(`\n${digest.text}`);
+            const digestFile = (0, digest_1.writeDigestMarkdown)(digest.markdown, cwd);
+            console.log(`\n✅ Digest written: ${digestFile}`);
+            break;
+        }
+        case 'export': {
+            const csvPath = await storage_1.StorageManager.exportToCsv(cwd);
+            console.log(`✅ Successfully exported telemetry dataset to CSV: ${csvPath}`);
+            break;
+        }
+        case 'churn': {
+            console.log('\n📊 Analyzing longitudinal code survival rate (git blame HEAD + windowed 30-day)...');
+            const sessions = await storage_1.StorageManager.loadSessions(cwd);
+            const config = config_1.ConfigManager.loadConfig(cwd);
+            const ignoreFilter = new ignore_1.IgnoreFilter(cwd, config.storageDir);
+            let updatedCount = 0;
+            const eligible = sessions.filter(s => s.diff.totalInsertions > 0 && s.aiTool !== 'none');
+            const touchedFiles = new Set();
+            for (const s of eligible) {
+                for (const f of s.diff.files) {
+                    if (!f.isBinary)
+                        touchedFiles.add(f.path);
+                }
+            }
+            if (touchedFiles.size > 0) {
+                // Reuse the same reverse-attribution blame engine as the retro scan (Pass 2) instead of
+                // a bespoke, less correct blame parser — one blame per file at HEAD, amortized.
+                const survivalResult = await (0, survival_1.computeSurvival)(Array.from(touchedFiles), { cwd, ignoreFilter });
+                const skippedSet = new Set(survivalResult.skippedFiles);
+                const windowedInputs = eligible.map(s => ({
+                    commitHash: s.commitHash,
+                    authorDate: s.timestamp,
+                    insertions: s.diff.totalInsertions,
+                    files: s.diff.files.filter(f => !f.isBinary && !ignoreFilter.shouldIgnore(f.path)).map(f => f.path)
+                }));
+                const windowedResult = await (0, survival_1.computeWindowedSurvival)(windowedInputs, { cwd });
+                for (const s of eligible) {
+                    const unknown = s.diff.files.some(f => !f.isBinary && skippedSet.has(f.path));
+                    const rate = unknown
+                        ? null
+                        : (0, survival_1.survivalRateFor)(survivalResult.survivingLines.get(s.commitHash) || 0, s.diff.totalInsertions);
+                    if (rate === null)
+                        continue;
+                    s.churn = {
+                        linesReverted: Math.max(0, s.diff.totalInsertions - (survivalResult.survivingLines.get(s.commitHash) || 0)),
+                        survivalRate: rate,
+                        survival30d: windowedResult.survival30d.get(s.commitHash)
+                    };
+                    updatedCount++;
+                }
+            }
+            storage_1.StorageManager.saveAllSessions(sessions, cwd);
+            // Regenerate reports
+            const stats = analyzer_1.MetricsAnalyzer.analyze(sessions);
+            reporter_1.ReportGenerator.generateReport(stats, sessions, cwd);
+            console.log(`✅ Code churn statistics calculated for ${updatedCount} sessions.`);
+            break;
+        }
+        case 'trust': {
+            config_1.GlobalConfigManager.trustWorkspace(cwd);
+            console.log(`✅ Trusted this workspace. Custom test commands are now allowed to run.`);
+            break;
+        }
+        case 'untrust': {
+            config_1.GlobalConfigManager.untrustWorkspace(cwd);
+            console.log(`✅ Untrusted this workspace. Custom test commands are now blocked from executing.`);
+            break;
+        }
+        case 'uninstall': {
+            const success = hooks_1.HookManager.uninstallHook(cwd);
+            if (success) {
+                console.log('✅ Post-commit git hook removed successfully.');
+            }
+            else {
+                console.log('ℹ️ No DevTrace-AI hook detected in this repository.');
+            }
+            break;
+        }
+        case 'claude-hook': {
+            // Invoked BY Claude Code itself (PostToolUse / SessionStart hook command).
+            // Must never throw, never block, and always exit 0 — see src/claude-hooks.ts.
+            (0, claude_hooks_1.runClaudeHookCli)();
+            break;
+        }
+        case 'claude-install': {
+            const beforeCount = (0, claude_hook_install_1.countDevtraceEntries)(readClaudeSettingsForSummary());
+            const result = (0, claude_hook_install_1.installClaudeHooks)();
+            const afterCount = (0, claude_hook_install_1.countDevtraceEntries)(result.after);
+            console.log(`\n🔌 Installing Claude Code hook integration (PostToolUse + SessionStart)...`);
+            console.log(`   Settings file: ${result.settingsPath}`);
+            console.log(`   DevTrace hook entries: ${beforeCount} -> ${afterCount}`);
+            console.log(`✅ Claude Code will now report Edit/Write/MultiEdit + session-start events to any initialized DevTrace repo (.devtrace/claude-ledger.jsonl).`);
+            console.log(`   Metadata only — prompt text and file contents are never recorded.`);
+            break;
+        }
+        case 'claude-uninstall': {
+            const beforeCount = (0, claude_hook_install_1.countDevtraceEntries)(readClaudeSettingsForSummary());
+            const result = (0, claude_hook_install_1.uninstallClaudeHooks)();
+            const afterCount = (0, claude_hook_install_1.countDevtraceEntries)(result.after);
+            console.log(`\n🔌 Removing Claude Code hook integration...`);
+            console.log(`   Settings file: ${result.settingsPath}`);
+            console.log(`   DevTrace hook entries: ${beforeCount} -> ${afterCount}`);
+            console.log(`✅ Claude Code hook integration removed. Other hooks/settings were left untouched.`);
+            break;
+        }
+        case 'status':
+        default: {
+            const config = config_1.ConfigManager.loadConfig(cwd);
+            const jsonlPath = storage_1.StorageManager.getJsonlPath(cwd);
+            const sessions = await storage_1.StorageManager.loadSessions(cwd);
+            console.log('\n==== DevTrace-AI Telemetry Status ====');
+            console.log(`Project Directory:  ${cwd}`);
+            console.log(`Storage Directory:  ${config.storageDir}`);
+            console.log(`Workspace Trust:    ${config_1.GlobalConfigManager.isWorkspaceTrusted(cwd) ? '✅ Trusted' : '❌ Untrusted'}`);
+            console.log(`Git Hook Mode:      ${config.runTestsAsync ? 'Asynchronous (Background)' : 'Synchronous'}`);
+            console.log(`Traced Sessions:    ${sessions.length}`);
+            let hookActive = false;
+            try {
+                const hooksDir = hooks_1.HookManager.getHooksDirectory(cwd);
+                const hookPath = path.join(hooksDir, 'post-commit');
+                hookActive = fs.existsSync(hookPath) && fs.readFileSync(hookPath, 'utf8').includes('DEVTRACE-AI');
+            }
+            catch { }
+            console.log(`Git Hook Installed: ${hookActive ? '✅ Active' : '❌ Inactive'}`);
+            if (sessions.length > 0) {
+                console.log(`\nLast Session Commit: ${sessions[sessions.length - 1].commitHash.substring(0, 8)}`);
+            }
+            const measured30d = sessions
+                .map(s => s.churn?.survival30d)
+                .filter((v) => v !== undefined && v.status === 'measured');
+            if (measured30d.length > 0) {
+                const avg = measured30d.reduce((sum, v) => sum + v.rate, 0) / measured30d.length;
+                console.log(`AI lines surviving 30 days: ${(avg * 100).toFixed(0)}%  (n=${measured30d.length} commit${measured30d.length === 1 ? '' : 's'} measured)`);
+            }
+            console.log('\nAvailable Subcommands:');
+            console.log('  init       Install hook, default config, and run the retroactive scan');
+            console.log('  scan       Re-run the retroactive scan only (--fast, --since <n>d)');
+            console.log('  annotate   Rate and annotate the last session');
+            console.log('  report     Rebuild DEVTRACE_LOG.md + self-contained HTML report (--out <path>)');
+            console.log('  card       Generate a shareable SVG scorecard (--out <path>)');
+            console.log('  digest     Print + write a digest of recent activity (--since <n>d, default 7d)');
+            console.log('  churn      Retroactively analyze code survival rates');
+            console.log('  export     Compile session data to CSV');
+            console.log('  trust      Trust this workspace to run custom testCommand');
+            console.log('  untrust    Untrust this workspace');
+            console.log('  uninstall  Remove post-commit hook');
+            console.log('\nIntegration (first-party Claude Code capture, tier-2 instrumented):');
+            console.log('  claude-install    Install Claude Code hooks (PostToolUse + SessionStart)');
+            console.log('  claude-uninstall  Remove Claude Code hooks');
+            break;
+        }
+    }
+}
+run().catch(err => {
+    console.error(`❌ Unexpected execution error: ${err.message}`);
+    process.exit(1);
+});