@code-insights/cli 1.2.0 → 2.0.0

package/dist/utils/telemetry.js

@@ -0,0 +1,304 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+import { createRequire } from 'module';
+import { loadConfig, getConfigDir, getClaudeDir } from './config.js';
+const TELEMETRY_ENDPOINT = 'https://xrbkoqjfolxiyfxubiom.supabase.co/functions/v1/cli-telemetry';
+// Touch file path that tracks whether the one-time disclosure has been shown
+const NOTICE_FILE = path.join(getConfigDir(), '.telemetry-notice-shown');
+/**
+ * Check if telemetry is enabled.
+ *
+ * Check order (first match wins):
+ * 1. CODE_INSIGHTS_TELEMETRY_DISABLED=1 env var — respects CI/automation opt-out
+ * 2. DO_NOT_TRACK=1 env var — respects the community standard
+ * 3. config.telemetry field — user's explicit preference
+ * 4. Default: true (opt-out model)
+ */
+export function isTelemetryEnabled() {
+    if (process.env.CODE_INSIGHTS_TELEMETRY_DISABLED === '1')
+        return false;
+    if (process.env.DO_NOT_TRACK === '1')
+        return false;
+    const config = loadConfig();
+    // If explicitly set in config, respect it
+    if (config !== null && typeof config.telemetry === 'boolean') {
+        return config.telemetry;
+    }
+    // Default: enabled (opt-out model)
+    return true;
+}
+/**
+ * Show the one-time telemetry disclosure notice if it hasn't been shown yet.
+ *
+ * Uses a touch file at ~/.code-insights/.telemetry-notice-shown to track state.
+ * Only displays if telemetry is currently enabled — no point disclosing disabled telemetry.
+ *
+ * Returns true if the notice was shown, false if it was already shown or telemetry is off.
+ */
+export function showTelemetryNoticeIfNeeded() {
+    if (!isTelemetryEnabled())
+        return false;
+    if (fs.existsSync(NOTICE_FILE))
+        return false;
+    // Show the disclosure banner
+    console.log('');
+    console.log('  Code Insights collects anonymous usage data to improve the CLI.');
+    console.log('  Includes: command name, OS, CLI version, AI tool types.');
+    console.log('  Never includes: file paths, project names, session content, or personal data.');
+    console.log('');
+    console.log('  Disable: code-insights telemetry disable');
+    console.log('  Details: code-insights telemetry status');
+    console.log('');
+    // Mark notice as shown — best-effort write, ignore failures
+    try {
+        // Ensure config dir exists before writing touch file
+        const configDir = getConfigDir();
+        if (!fs.existsSync(configDir)) {
+            fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+        }
+        fs.writeFileSync(NOTICE_FILE, '', { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch {
+        // Non-fatal — if we can't write the touch file, we'll show the notice again
+        // next time. That's acceptable; we don't want to break the CLI over this.
+    }
+    return true;
+}
+/**
+ * Fire-and-forget telemetry event. Does NOT block the calling command.
+ *
+ * Design principles:
+ * - Never awaited: the caller doesn't wait for this
+ * - 2s AbortController timeout: we don't hang if the endpoint is slow
+ * - Swallows ALL errors: network failures, JSON errors, anything — telemetry
+ *   must never cause a CLI command to fail
+ * - No retries: if it fails, it fails. Reliability of individual events
+ *   matters less than not disrupting the user's workflow.
+ */
+export function trackEvent(command, success, subcommand) {
+    if (!isTelemetryEnabled())
+        return;
+    // Build the event synchronously — filesystem reads happen here
+    let event;
+    try {
+        event = buildEvent(command, success, subcommand);
+    }
+    catch {
+        // If building the event fails (e.g., filesystem read error), silently skip
+        return;
+    }
+    // Fire-and-forget: intentionally not awaited
+    // The void cast suppresses the "floating promise" lint warning
+    void sendEvent(event);
+}
+/**
+ * Build the event payload that would be sent for the given command.
+ * Exported for use by `telemetry status` to show a preview without sending.
+ */
+export function buildEventPreview(command) {
+    return buildEvent(command, true);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build a TelemetryEvent with all fields populated.
+ * Separated from sendEvent so buildEventPreview can reuse it without sending.
+ */
+function buildEvent(command, success, subcommand) {
+    return {
+        machineId: getMachineId(),
+        command,
+        subcommand,
+        success,
+        cliVersion: getCliVersion(),
+        nodeVersion: process.version.replace('v', ''),
+        os: process.platform,
+        arch: process.arch,
+        providers: detectProviders(),
+        sessionCountBucket: getSessionCountBucket(),
+        dataSource: getDataSource(),
+        hasHook: detectHook(),
+        // Day precision only — avoids time-of-day behavioral fingerprinting
+        timestamp: new Date().toISOString().slice(0, 10),
+    };
+}
+/**
+ * Anonymous machine ID, rotated monthly.
+ *
+ * Format: SHA-256(hostname:username:code-insights-YYYY-MM).slice(0, 16)
+ *
+ * Monthly rotation ensures:
+ * - Long-term tracking is not possible across months
+ * - Events within a month can be correlated for "unique users" metrics
+ * - No PII: hostname and username are never sent, only their hash
+ */
+function getMachineId() {
+    const now = new Date();
+    // YYYY-MM format for monthly rotation
+    const monthSalt = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+    let username;
+    try {
+        username = os.userInfo().username;
+    }
+    catch {
+        // os.userInfo() throws in Docker/CI when UID has no /etc/passwd entry
+        username = `uid-${process.getuid?.() ?? 'unknown'}`;
+    }
+    const input = [os.hostname(), username, `code-insights-${monthSalt}`].join(':');
+    return crypto.createHash('sha256').update(input).digest('hex').slice(0, 16);
+}
+/**
+ * Read CLI version from package.json.
+ * Uses createRequire for JSON imports since this is ESM and JSON imports
+ * have inconsistent support across Node versions and bundlers.
+ */
+function getCliVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        // package.json is two levels up from src/utils/ -> src/ -> cli/
+        const pkg = require('../../package.json');
+        return pkg.version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Detect which AI coding tool data directories exist on this machine.
+ * We check for the existence of known directories — we never read their contents.
+ *
+ * Returns only the tools that are actually present. This tells us which tools
+ * users are running alongside code-insights, helping us prioritize provider support.
+ */
+function detectProviders() {
+    const home = os.homedir();
+    const detected = [];
+    // Claude Code: ~/.claude/projects/
+    if (fs.existsSync(path.join(home, '.claude', 'projects'))) {
+        detected.push('claude-code');
+    }
+    // Cursor: workspace storage directory (cross-platform path)
+    const cursorStoragePaths = [
+        // macOS
+        path.join(home, 'Library', 'Application Support', 'Cursor', 'User', 'workspaceStorage'),
+        // Linux
+        path.join(home, '.config', 'Cursor', 'User', 'workspaceStorage'),
+        // Windows
+        path.join(home, 'AppData', 'Roaming', 'Cursor', 'User', 'workspaceStorage'),
+    ];
+    if (cursorStoragePaths.some((p) => fs.existsSync(p))) {
+        detected.push('cursor');
+    }
+    // Codex CLI: ~/.codex/sessions
+    if (fs.existsSync(path.join(home, '.codex', 'sessions'))) {
+        detected.push('codex-cli');
+    }
+    // GitHub Copilot CLI: ~/.copilot/session-state
+    if (fs.existsSync(path.join(home, '.copilot', 'session-state'))) {
+        detected.push('copilot-cli');
+    }
+    return detected;
+}
+/**
+ * Count .jsonl files under ~/.claude/projects/ and bucket the count.
+ *
+ * Buckets are intentionally coarse — we want to understand "heavy vs light"
+ * usage without counting exact files, which could vary wildly and feels more
+ * private than a range.
+ */
+function getSessionCountBucket() {
+    try {
+        const claudeDir = getClaudeDir();
+        if (!fs.existsSync(claudeDir))
+            return '0';
+        // Count all .jsonl files recursively under the Claude projects directory
+        let count = 0;
+        const walk = (dir) => {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    walk(path.join(dir, entry.name));
+                }
+                else if (entry.name.endsWith('.jsonl')) {
+                    count++;
+                }
+            }
+        };
+        walk(claudeDir);
+        // Coarse buckets for privacy — exact session counts are never sent
+        if (count === 0)
+            return '0';
+        if (count <= 10)
+            return '1-10';
+        if (count <= 50)
+            return '11-50';
+        if (count <= 200)
+            return '51-200';
+        return '200+';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Determine the configured data source preference.
+ * Returns 'none' if no config exists at all.
+ */
+function getDataSource() {
+    const config = loadConfig();
+    if (!config)
+        return 'none';
+    if (config.dataSource)
+        return config.dataSource;
+    // Infer from credentials: if Firebase is configured, they're likely using it
+    if (config.firebase?.projectId)
+        return 'firebase';
+    return 'local';
+}
+/**
+ * Check if code-insights is registered as a Claude Code hook.
+ *
+ * Reads ~/.claude/settings.json and looks for 'code-insights' anywhere in the
+ * file content. A hook registration means the user has automated sync on session end.
+ */
+function detectHook() {
+    try {
+        const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+        if (!fs.existsSync(settingsPath))
+            return false;
+        const content = fs.readFileSync(settingsPath, 'utf-8');
+        return content.includes('code-insights');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Internal: Send the event to the telemetry endpoint.
+ * AbortController ensures we don't hang longer than 2 seconds.
+ * All errors are swallowed — telemetry failures must never propagate.
+ */
+async function sendEvent(event) {
+    const controller = new AbortController();
+    // 2s timeout — enough for a healthy network, short enough to not delay anything
+    const timer = setTimeout(() => controller.abort(), 2000);
+    try {
+        await fetch(TELEMETRY_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(event),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        // Swallow everything: network errors, AbortError, JSON serialization errors.
+        // Telemetry failures are silent — the CLI command already completed.
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/utils/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/utils/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,kBAAkB,GAAG,qEAAqE,CAAC;AAEjG,6EAA6E;AAC7E,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,yBAAyB,CAAC,CAAC;AAkBzE;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB;IAChC,IAAI,OAAO,CAAC,GAAG,CAAC,gCAAgC,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACvE,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IAEnD,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,0CAA0C;IAC1C,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7D,OAAO,MAAM,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED,mCAAmC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B;IACzC,IAAI,CAAC,kBAAkB,EAAE;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IAE7C,6BAA6B;IAC7B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,mEAAmE,CAAC,CAAC;IACjF,OAAO,CAAC,GAAG,CAAC,2DAA2D,CAAC,CAAC;IACzE,OAAO,CAAC,GAAG,CAAC,iFAAiF,CAAC,CAAC;IAC/F,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;IAC1D,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,4DAA4D;IAC5D,IAAI,CAAC;QACH,qDAAqD;QACrD,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,0EAA0E;IAC5E,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,OAAgB,EAAE,UAAmB;IAC/E,IAAI,CAAC,kBAAkB,EAAE;QAAE,OAAO;IAElC,+DAA+D;IAC/D,IAAI,KAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,OAAO;IACT,CAAC;IAED,6CAA6C;IAC7C,+DAA+D;IAC/D,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,UAAU,CAAC,OAAe,EAAE,OAAgB,EAAE,UAAmB;IACxE,OAAO;QACL,SAAS,EAAE,YAAY,EAAE;QACzB,OAAO;QACP,UAAU;QACV,OAAO;QACP,UAAU,EAAE,aAAa,EAAE;QAC3B,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;QAC7C,EAAE,EAAE,OAAO,CAAC,QAAQ;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,SAAS,EAAE,eAAe,EAAE;QAC5B,kBAAkB,EAAE,qBAAqB,EAAE;QAC3C,UAAU,EAAE,aAAa,EAAE;QAC3B,OAAO,EAAE,UAAU,EAAE;QACrB,oEAAoE;QACpE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;KACjD,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,YAAY;IACnB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,sCAAsC;IACtC,MAAM,SAAS,GAAG,GAAG,GAAG,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IAExF,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,QAAQ,GAAG,OAAO,OAAO,CAAC,MAAM,EAAE,EAAE,IAAI,SAAS,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,iBAAiB,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEhF,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa;IACpB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,gEAAgE;QAChE,MAAM,GAAG,GAAG,OAAO,CAAC,oBAAoB,CAAwB,CAAC;QACjE,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe;IACtB,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC1B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,mCAAmC;IACnC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC;QAC1D,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC/B,CAAC;IAED,4DAA4D;IAC5D,MAAM,kBAAkB,GAAG;QACzB,QAAQ;QACR,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,CAAC;QACvF,QAAQ;QACR,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,CAAC;QAChE,UAAU;QACV,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,CAAC;KAC5E,CAAC;IACF,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAED,+BAA+B;IAC/B,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC;QACzD,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7B,CAAC;IAED,+CAA+C;IAC/C,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC;QAChE,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,qBAAqB;IAC5B,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,GAAG,CAAC;QAE1C,yEAAyE;QACzE,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,MAAM,IAAI,GAAG,CAAC,GAAW,EAAQ,EAAE;YACjC,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;oBACxB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;gBACnC,CAAC;qBAAM,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACzC,KAAK,EAAE,CAAC;gBACV,CAAC;YACH,CAAC;QACH,CAAC,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,CAAC;QAEhB,mEAAmE;QACnE,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC;QAC5B,IAAI,KAAK,IAAI,EAAE;YAAE,OAAO,MAAM,CAAC;QAC/B,IAAI,KAAK,IAAI,EAAE;YAAE,OAAO,OAAO,CAAC;QAChC,IAAI,KAAK,IAAI,GAAG;YAAE,OAAO,QAAQ,CAAC;QAClC,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa;IACpB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC;IAC3B,IAAI,MAAM,CAAC,UAAU;QAAE,OAAO,MAAM,CAAC,UAAU,CAAC;IAChD,6EAA6E;IAC7E,IAAI,MAAM,CAAC,QAAQ,EAAE,SAAS;QAAE,OAAO,UAAU,CAAC;IAClD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU;IACjB,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;QACzE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC;YAAE,OAAO,KAAK,CAAC;QAE/C,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,SAAS,CAAC,KAAqB;IAC5C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,gFAAgF;IAChF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;IAEzD,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,kBAAkB,EAAE;YAC9B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAC3B,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,6EAA6E;QAC7E,qEAAqE;IACvE,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/utils/tips.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Show a rotating contextual tip after a CLI command.
+ *
+ * Tips are suppressed once a command has accumulated MAX_TIPS_PER_COMMAND
+ * displays, so they phase out naturally after the user's first few runs.
+ * All state is stored in ~/.code-insights/.tips-state.json.
+ *
+ * Returns the tip string if one was printed, or null if suppressed.
+ */
+export declare function showTip(command: string): string | null;
+//# sourceMappingURL=tips.d.ts.map

package/dist/utils/tips.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tips.d.ts","sourceRoot":"","sources":["../../src/utils/tips.ts"],"names":[],"mappings":"AA8EA;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA+BtD"}

package/dist/utils/tips.js

@@ -0,0 +1,106 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import { ensureConfigDir, getConfigDir } from './config.js';
+// Tips stop showing after this many displays per command.
+// Five is enough to surface the tip on early uses without becoming annoying.
+const MAX_TIPS_PER_COMMAND = 5;
+const TIPS_STATE_FILE = '.tips-state.json';
+/**
+ * Per-command tip arrays. Tips cycle with modulo so they don't repeat
+ * in strict sequence once the list wraps — they're educational hints,
+ * not a tutorial that must be seen in order.
+ */
+const TIPS = {
+    stats: [
+        'Try `code-insights stats cost` for a cost and token breakdown by session',
+        'Try `code-insights stats today` to see only today\'s activity',
+        'Try `code-insights stats models` to compare usage across AI models',
+        'Try `code-insights stats projects` to see which projects you\'ve worked on most',
+        'Run `code-insights init` to sync sessions to Firebase and unlock the web dashboard',
+    ],
+    'stats cost': [
+        'Use `--period 30d` to see cost over the last 30 days (default is 7d)',
+        'Try `code-insights stats models` to break down cost by model',
+        'Try `code-insights stats` for a full activity overview',
+    ],
+    'stats today': [
+        'Try `code-insights stats` for a full activity overview across all time',
+        'Try `code-insights stats cost` to see what today\'s sessions cost',
+    ],
+    'stats projects': [
+        'Use `--project <name>` to filter sessions to a specific project',
+        'Try `code-insights stats cost` to see how spend is distributed across projects',
+    ],
+    'stats models': [
+        'Try `code-insights stats cost` to see per-session cost alongside model usage',
+        'Try `code-insights stats` for the full overview including all activity',
+    ],
+};
+/**
+ * Load tips state from ~/.code-insights/.tips-state.json.
+ * Returns an empty state on any I/O or parse error — tips are non-critical.
+ */
+function loadTipsState() {
+    try {
+        const file = path.join(getConfigDir(), TIPS_STATE_FILE);
+        if (!fs.existsSync(file)) {
+            return { shown: {} };
+        }
+        const content = fs.readFileSync(file, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return { shown: {} };
+    }
+}
+/**
+ * Persist tips state. Silently swallows errors — a failed write just
+ * means the same tip might show again next run, which is acceptable.
+ */
+function saveTipsState(state) {
+    try {
+        ensureConfigDir();
+        const file = path.join(getConfigDir(), TIPS_STATE_FILE);
+        fs.writeFileSync(file, JSON.stringify(state, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // Non-critical — swallow silently
+    }
+}
+/**
+ * Show a rotating contextual tip after a CLI command.
+ *
+ * Tips are suppressed once a command has accumulated MAX_TIPS_PER_COMMAND
+ * displays, so they phase out naturally after the user's first few runs.
+ * All state is stored in ~/.code-insights/.tips-state.json.
+ *
+ * Returns the tip string if one was printed, or null if suppressed.
+ */
+export function showTip(command) {
+    try {
+        const tips = TIPS[command];
+        // No tips defined for this command — nothing to show
+        if (!tips || tips.length === 0) {
+            return null;
+        }
+        const state = loadTipsState();
+        const count = state.shown[command] ?? 0;
+        // User has seen enough tips for this command — stop showing them
+        if (count >= MAX_TIPS_PER_COMMAND) {
+            return null;
+        }
+        // Cycle through tips so we don't always repeat the first one
+        const tip = tips[count % tips.length];
+        const formatted = chalk.gray(`\n  Tip: ${tip}`);
+        console.log(formatted);
+        state.shown[command] = count + 1;
+        saveTipsState(state);
+        return formatted;
+    }
+    catch {
+        // Tips are non-critical — swallow all errors silently
+        return null;
+    }
+}
+//# sourceMappingURL=tips.js.map

package/dist/utils/tips.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tips.js","sourceRoot":"","sources":["../../src/utils/tips.ts"],"names":[],"mappings":"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"}

package/dist/utils/welcome.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Show a one-time welcome banner for first-time users.
+ *
+ * Only fires when no ~/.code-insights/.welcome-shown marker exists.
+ * Intentionally non-critical — all file I/O is wrapped so errors
+ * are swallowed silently rather than interrupting the user's command.
+ *
+ * Returns true if the banner was printed, false if already shown.
+ */
+export declare function showWelcomeIfFirstRun(): boolean;
+//# sourceMappingURL=welcome.d.ts.map

package/dist/utils/welcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"welcome.d.ts","sourceRoot":"","sources":["../../src/utils/welcome.ts"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAqC/C"}

package/dist/utils/welcome.js

@@ -0,0 +1,101 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import { ensureConfigDir, getClaudeDir, getConfigDir } from './config.js';
+const WELCOME_MARKER = '.welcome-shown';
+/**
+ * Show a one-time welcome banner for first-time users.
+ *
+ * Only fires when no ~/.code-insights/.welcome-shown marker exists.
+ * Intentionally non-critical — all file I/O is wrapped so errors
+ * are swallowed silently rather than interrupting the user's command.
+ *
+ * Returns true if the banner was printed, false if already shown.
+ */
+export function showWelcomeIfFirstRun() {
+    try {
+        const markerPath = path.join(getConfigDir(), WELCOME_MARKER);
+        // Already greeted this user — bail out fast
+        if (fs.existsSync(markerPath)) {
+            return false;
+        }
+        const { sessionCount, projectCount } = countClaudeSessions();
+        console.log('');
+        console.log(chalk.bold.cyan('  Welcome to Code Insights!'));
+        console.log('');
+        if (sessionCount > 0) {
+            console.log(chalk.dim('  Found ') +
+                chalk.white.bold(sessionCount) +
+                chalk.dim(` session${sessionCount === 1 ? '' : 's'} across `) +
+                chalk.white.bold(projectCount) +
+                chalk.dim(` project${projectCount === 1 ? '' : 's'} in ~/.claude/projects`));
+        }
+        else {
+            console.log(chalk.dim('  No sessions found yet in ~/.claude/projects'));
+        }
+        console.log('');
+        // Touch the marker so we never show this again
+        touchWelcomeMarker(markerPath);
+        return true;
+    }
+    catch {
+        // Welcome is non-critical — swallow all errors silently
+        return false;
+    }
+}
+/**
+ * Count JSONL sessions and project directories in ~/.claude/projects/.
+ * Mirrors the discovery logic in ClaudeCodeProvider without pulling in
+ * the full provider dependency chain.
+ */
+function countClaudeSessions() {
+    const baseDir = getClaudeDir();
+    if (!fs.existsSync(baseDir)) {
+        return { sessionCount: 0, projectCount: 0 };
+    }
+    let sessionCount = 0;
+    let projectCount = 0;
+    try {
+        const entries = fs.readdirSync(baseDir);
+        for (const entry of entries) {
+            // Skip hidden files/dirs (matches ClaudeCodeProvider behaviour)
+            if (entry.startsWith('.'))
+                continue;
+            const entryPath = path.join(baseDir, entry);
+            try {
+                const stat = fs.statSync(entryPath);
+                if (!stat.isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            projectCount++;
+            try {
+                const files = fs.readdirSync(entryPath);
+                for (const file of files) {
+                    if (file.endsWith('.jsonl')) {
+                        sessionCount++;
+                    }
+                }
+            }
+            catch {
+                // Can't read this project dir — skip it, keep counting others
+            }
+        }
+    }
+    catch {
+        return { sessionCount: 0, projectCount: 0 };
+    }
+    return { sessionCount, projectCount };
+}
+/**
+ * Create the welcome-shown marker file.
+ * Ensures the config directory exists first (handles brand-new installs
+ * where no config has been written yet).
+ */
+function touchWelcomeMarker(markerPath) {
+    ensureConfigDir();
+    fs.writeFileSync(markerPath, '', { mode: 0o600 });
+}
+//# sourceMappingURL=welcome.js.map

package/dist/utils/welcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"welcome.js","sourceRoot":"","sources":["../../src/utils/welcome.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@code-insights/cli",
-  "version": "1.2.0",
-  "description": "Sync your AI coding sessions to Firebase for analysis",
+  "version": "2.0.0",
+  "description": "Parse and sync AI coding sessions (Claude Code, Cursor, Codex, Copilot) to Firebase for analysis",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -16,6 +16,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -24,6 +25,10 @@
   "keywords": [
     "claude",
     "claude-code",
+    "cursor",
+    "codex",
+    "copilot",
+    "ai-coding",
     "insights",
     "analytics",
     "firestore"
@@ -43,6 +48,7 @@
   },
   "license": "MIT",
   "dependencies": {
+    "better-sqlite3": "^12.6.2",
     "chalk": "^5.4.1",
     "commander": "^12.1.0",
     "firebase-admin": "^13.4.0",
@@ -50,6 +56,7 @@
     "ora": "^8.2.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.15.30",
     "typescript": "^5.9.3"
   }