costhawk 1.5.11 → 1.5.13

package/dist/cursor-parser.js

@@ -0,0 +1,888 @@
+/**
+ * Cursor Local SQLite Parser
+ *
+ * Parses Cursor IDE chat history from the local SQLite database to extract
+ * token usage and timestamps. Read-only. Does not push to any backend.
+ *
+ * Storage:
+ *   macOS:   ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
+ *   Linux:   ~/.config/Cursor/User/globalStorage/state.vscdb
+ *   Windows: %APPDATA%/Cursor/User/globalStorage/state.vscdb
+ *
+ * Schema:
+ *   Table cursorDiskKV (key TEXT, value BLOB)
+ *   Conversations: composerData:<composerId>
+ *   Messages:      bubbleId:<composerId>:<bubbleId>
+ *
+ * Token data lives at $.tokenCount.inputTokens and $.tokenCount.outputTokens
+ * on bubble rows. Model name at $.modelInfo.modelName. Server-side dedup id
+ * at $.serverBubbleId.
+ *
+ * Timestamps (verified in Task #30 against a real state.vscdb):
+ *   - $.createdAt on bubbles is an ISO 8601 string (~56% coverage, all-or-
+ *     nothing per composer — likely added in a newer Cursor version).
+ *   - $.createdAt on composerData rows is a Unix milliseconds number (100%
+ *     coverage). Same field name, different type — parser handles both.
+ *   - $.lastUpdatedAt on composerData rows is Unix ms (~13% coverage).
+ *   - $.timingInfo.client* on bubbles is performance.now()-style relative
+ *     (seconds since Cursor process start), NOT absolute — never use it as
+ *     a wall-clock timestamp.
+ *
+ * Fallback ladder for per-session timestamps: prefer min/max of bubble
+ * createdAt when present, otherwise use composerData.createdAt with optional
+ * composerData.lastUpdatedAt as end time. Every session gets non-null
+ * timestamps; the `timestampSource` / `timestampQuality` fields surface
+ * whether the values are precise or approximate.
+ *
+ * Workspace metadata fields (workspaceHash/workspaceName) remain unverified
+ * and return null. composerData.name is a candidate for workspaceName but
+ * has not been confirmed yet.
+ */
+import { execFileSync } from "child_process";
+import { existsSync, statSync } from "fs";
+import { homedir, platform } from "os";
+import { join } from "path";
+// Defaults — overridable via env vars
+const DEFAULT_SQLITE3_PATH = "/usr/bin/sqlite3";
+const SQLITE_TIMEOUT_MS = 10_000;
+const SQLITE_MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+// Sanity-check range for parsed Unix-ms timestamps. We reject anything before
+// 2020 or at/after 2100 as "not plausibly a Cursor message timestamp" — this
+// catches both `performance.now`-style relative values (which look like
+// fractional seconds) and negative / NaN parse results from malformed data.
+const MIN_UNIX_MS = Date.UTC(2020, 0, 1);
+const MAX_UNIX_MS = Date.UTC(2100, 0, 1);
+// Self-test invariant: bubbles sometimes persist a few minutes earlier than
+// the composerData row due to clock skew or write-order races. Tolerate 5
+// minutes before raising a warning.
+const INVARIANT_SKEW_TOLERANCE_MS = 5 * 60 * 1000;
+/**
+ * Parse an ISO 8601 string into Unix ms, or null if the input is not a
+ * string, not parseable, or outside the sane range. Callers should treat
+ * null as "no usable timestamp here" and fall through to the next source.
+ */
+function parseIsoToMs(value) {
+    if (typeof value !== "string")
+        return null;
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms) || ms < MIN_UNIX_MS || ms >= MAX_UNIX_MS) {
+        return null;
+    }
+    return ms;
+}
+/**
+ * Parse a number that is supposed to be Unix ms, rejecting values outside
+ * the sane range. This specifically catches `timingInfo.clientStartTime`
+ * (which is `performance.now()` seconds since process start and lands
+ * far below MIN_UNIX_MS).
+ */
+function parseUnixMsLoose(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    if (value < MIN_UNIX_MS || value >= MAX_UNIX_MS)
+        return null;
+    return Math.floor(value);
+}
+/**
+ * Accept either shape for a `createdAt`-style field. composerData.createdAt
+ * is a number; bubble.createdAt is an ISO string. We try both without
+ * signaling which one matched — the caller does not need to know.
+ */
+function parseTimestampField(value) {
+    return parseUnixMsLoose(value) ?? parseIsoToMs(value);
+}
+function msToIso(ms) {
+    return new Date(ms).toISOString();
+}
+function msToUtcDateKey(ms) {
+    return new Date(ms).toISOString().split("T")[0];
+}
+function createEmptyTokenUsage() {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheCreationTokens: 0,
+        cacheReadTokens: 0,
+    };
+}
+/**
+ * Get the default Cursor SQLite path for the current platform, honoring
+ * the COSTHAWK_CURSOR_DB_PATH environment override.
+ */
+export function getCursorDbPath() {
+    const envOverride = process.env.COSTHAWK_CURSOR_DB_PATH;
+    if (envOverride && envOverride.length > 0) {
+        return envOverride;
+    }
+    const home = homedir();
+    if (platform() === "darwin") {
+        return join(home, "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb");
+    }
+    if (platform() === "win32") {
+        const appData = process.env.APPDATA;
+        if (appData) {
+            return join(appData, "Cursor", "User", "globalStorage", "state.vscdb");
+        }
+        return join(home, "AppData", "Roaming", "Cursor", "User", "globalStorage", "state.vscdb");
+    }
+    // Linux and other unix-likes
+    return join(home, ".config", "Cursor", "User", "globalStorage", "state.vscdb");
+}
+/**
+ * Check whether the Cursor SQLite database exists at the resolved path.
+ */
+export function cursorDbExists() {
+    return existsSync(getCursorDbPath());
+}
+/**
+ * Resolve the sqlite3 binary path. Defaults to /usr/bin/sqlite3, honoring
+ * the COSTHAWK_SQLITE3_PATH environment override.
+ */
+function getSqlite3Path() {
+    return process.env.COSTHAWK_SQLITE3_PATH ?? DEFAULT_SQLITE3_PATH;
+}
+/**
+ * Type guard — narrows an unknown error to a CursorParserError.
+ */
+function isCursorParserError(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj.code === "string" &&
+        (obj.code === "CURSOR_DB_NOT_FOUND" ||
+            obj.code === "CURSOR_SQLITE3_NOT_FOUND" ||
+            obj.code === "CURSOR_SQLITE_QUERY_FAILED") &&
+        typeof obj.message === "string");
+}
+/**
+ * Run a SQL query against the Cursor SQLite via shell-out to the system
+ * sqlite3 binary. Returns parsed rows as an array of {key, value} objects,
+ * or throws CursorParserError on unrecoverable failures.
+ *
+ * Uses execFileSync with an arg array (not shell strings) to avoid shell
+ * injection. Sets explicit timeout and maxBuffer to defend against runaway
+ * queries or oversized state.vscdb files.
+ */
+function runCursorQuery(sql) {
+    const sqlite3Path = getSqlite3Path();
+    const dbPath = getCursorDbPath();
+    if (!existsSync(dbPath)) {
+        const error = {
+            code: "CURSOR_DB_NOT_FOUND",
+            message: `Cursor SQLite database not found at ${dbPath}. Make sure Cursor is installed and you have used it at least once. Set COSTHAWK_CURSOR_DB_PATH to override.`,
+        };
+        throw error;
+    }
+    let stdout;
+    try {
+        stdout = execFileSync(sqlite3Path, ["-readonly", "-batch", "-json", "--", dbPath, sql], {
+            encoding: "utf8",
+            timeout: SQLITE_TIMEOUT_MS,
+            maxBuffer: SQLITE_MAX_BUFFER_BYTES,
+        });
+    }
+    catch (err) {
+        const errno = err.code;
+        if (errno === "ENOENT") {
+            const error = {
+                code: "CURSOR_SQLITE3_NOT_FOUND",
+                message: `sqlite3 binary not found at ${sqlite3Path}. Set COSTHAWK_SQLITE3_PATH to override the default path.`,
+            };
+            throw error;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        const error = {
+            code: "CURSOR_SQLITE_QUERY_FAILED",
+            message,
+        };
+        throw error;
+    }
+    if (!stdout || stdout.trim().length === 0) {
+        return [];
+    }
+    // sqlite3 -json output is a JSON array of objects when rows exist,
+    // or empty / whitespace when no rows. Anything else is a real failure
+    // and must surface as CURSOR_SQLITE_QUERY_FAILED — silently returning
+    // [] would mask a parser failure as "no sessions found".
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        const error = {
+            code: "CURSOR_SQLITE_QUERY_FAILED",
+            message: "sqlite3 returned invalid JSON output",
+        };
+        throw error;
+    }
+    if (!Array.isArray(parsed)) {
+        const error = {
+            code: "CURSOR_SQLITE_QUERY_FAILED",
+            message: "sqlite3 returned a non-array JSON payload",
+        };
+        throw error;
+    }
+    return parsed.filter((row) => typeof row === "object" &&
+        row !== null &&
+        "key" in row &&
+        "value" in row &&
+        typeof row.key === "string" &&
+        typeof row.value === "string");
+}
+function hasTokenUsage(bubble) {
+    return bubble.inputTokens > 0 || bubble.outputTokens > 0;
+}
+const BUBBLE_KEY_REGEX = /^bubbleId:([^:]+):(.+)$/;
+const COMPOSER_KEY_REGEX = /^composerData:(.+)$/;
+/**
+ * Parse a single bubbleId row into structured BubbleData.
+ *
+ * Returns null if the row key is malformed, the value is not parseable JSON,
+ * or the row contains neither a non-empty model name, positive token counts,
+ * nor a parseable timestamp. Cursor can store model metadata, token usage,
+ * and timestamps on different rows, so the parser accepts any usable signal
+ * in isolation and lets the per-composer aggregation merge them.
+ *
+ * Timestamp handling: `createdAt` is accepted as either an ISO 8601 string
+ * (standard shape on bubble rows) or a Unix-ms number (defensive fallback).
+ * Rows with only a timestamp and no tokens/model still return BubbleData
+ * so the timestamp contributes to per-composer start/end resolution.
+ */
+function parseBubble(row) {
+    const match = BUBBLE_KEY_REGEX.exec(row.key);
+    if (!match) {
+        return null;
+    }
+    const [, composerId, bubbleId] = match;
+    let value;
+    try {
+        value = JSON.parse(row.value);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const obj = value;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    const tokenCount = obj.tokenCount;
+    if (typeof tokenCount === "object" && tokenCount !== null) {
+        const tc = tokenCount;
+        inputTokens = typeof tc.inputTokens === "number" ? tc.inputTokens : 0;
+        outputTokens = typeof tc.outputTokens === "number" ? tc.outputTokens : 0;
+    }
+    let modelName;
+    const modelInfo = obj.modelInfo;
+    if (typeof modelInfo === "object" && modelInfo !== null) {
+        const mi = modelInfo;
+        if (typeof mi.modelName === "string" && mi.modelName.length > 0) {
+            modelName = mi.modelName;
+        }
+    }
+    const createdAtMs = parseTimestampField(obj.createdAt);
+    // Skip rows with no usable signal at all — neither model metadata,
+    // positive token counts, nor a parseable timestamp. These are typically
+    // system messages, empty bubbles, or tool-call bookkeeping rows.
+    if (!modelName && inputTokens === 0 && outputTokens === 0 && createdAtMs === null) {
+        return null;
+    }
+    let serverBubbleId;
+    if (typeof obj.serverBubbleId === "string" &&
+        obj.serverBubbleId.length > 0) {
+        serverBubbleId = obj.serverBubbleId;
+    }
+    return {
+        composerId,
+        bubbleId,
+        serverBubbleId,
+        modelName,
+        inputTokens,
+        outputTokens,
+        createdAtMs,
+    };
+}
+/**
+ * Parse a composerData row into ComposerMetadata.
+ *
+ * Returns null for malformed keys, unparseable JSON, or rows with no
+ * usable timestamp fields. composerData.createdAt in real Cursor data
+ * is a Unix-ms number, but the parser accepts either shape defensively.
+ *
+ * If lastUpdatedAt is earlier than createdAt (clock skew, data corruption),
+ * lastUpdatedAt is dropped rather than trusted, so downstream aggregation
+ * never produces endTime < startTime.
+ */
+function parseComposerData(row) {
+    const match = COMPOSER_KEY_REGEX.exec(row.key);
+    if (!match) {
+        return null;
+    }
+    const [, composerId] = match;
+    let value;
+    try {
+        value = JSON.parse(row.value);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const obj = value;
+    const createdAtMs = parseTimestampField(obj.createdAt);
+    const rawLastUpdatedAtMs = parseTimestampField(obj.lastUpdatedAt);
+    // Drop lastUpdatedAt if it violates the ordering invariant. We never want
+    // to produce a session where endTime < startTime because the source
+    // values were corrupt.
+    const lastUpdatedAtMs = createdAtMs !== null &&
+        rawLastUpdatedAtMs !== null &&
+        rawLastUpdatedAtMs < createdAtMs
+        ? null
+        : rawLastUpdatedAtMs;
+    if (createdAtMs === null && lastUpdatedAtMs === null) {
+        return null;
+    }
+    return {
+        composerId,
+        createdAtMs,
+        lastUpdatedAtMs,
+    };
+}
+/**
+ * Resolve per-session start/end times and provenance from the bubble and
+ * composer timestamp sources. This is the core of the PR2 fallback ladder:
+ *
+ *   - If any bubble in the composer has createdAtMs, use min/max of bubble
+ *     timestamps. Source = "bubble", quality = "precise". If composerData
+ *     provides a later lastUpdatedAt, prefer it for endTime and downgrade
+ *     the source to "mixed" (still "approximate" since we can't prove
+ *     those two sources describe the same timeline fidelity).
+ *   - Otherwise, if composerData has createdAtMs, use it for start and
+ *     (lastUpdatedAt ?? createdAtMs) for end. Source = "composer",
+ *     quality = "approximate".
+ *   - Otherwise, source = "none", quality = "none", startTime = endTime
+ *     = null. Callers should still emit the session — the tokens are real
+ *     even if the timing isn't.
+ */
+function resolveSessionTimestamps(bubbleCreatedAtsMs, composerMeta) {
+    const hasBubbleTimestamps = bubbleCreatedAtsMs.length > 0;
+    const composerCreatedAtMs = composerMeta?.createdAtMs ?? null;
+    const composerLastUpdatedAtMs = composerMeta?.lastUpdatedAtMs ?? null;
+    if (hasBubbleTimestamps) {
+        let startMs = bubbleCreatedAtsMs[0];
+        let endMs = bubbleCreatedAtsMs[0];
+        for (const ms of bubbleCreatedAtsMs) {
+            if (ms < startMs)
+                startMs = ms;
+            if (ms > endMs)
+                endMs = ms;
+        }
+        // If the composer's own lastUpdatedAt is AFTER our max bubble timestamp,
+        // prefer it — Cursor can persist the composer row when the session is
+        // closed, capturing activity that never produced a token-bearing bubble.
+        let mixed = false;
+        if (composerLastUpdatedAtMs !== null && composerLastUpdatedAtMs > endMs) {
+            endMs = composerLastUpdatedAtMs;
+            mixed = true;
+        }
+        return {
+            startTime: msToIso(startMs),
+            endTime: msToIso(endMs),
+            source: mixed ? "mixed" : "bubble",
+            quality: mixed ? "approximate" : "precise",
+        };
+    }
+    if (composerCreatedAtMs !== null) {
+        const endMs = composerLastUpdatedAtMs !== null && composerLastUpdatedAtMs >= composerCreatedAtMs
+            ? composerLastUpdatedAtMs
+            : composerCreatedAtMs;
+        return {
+            startTime: msToIso(composerCreatedAtMs),
+            endTime: msToIso(endMs),
+            source: "composer",
+            quality: "approximate",
+        };
+    }
+    return {
+        startTime: null,
+        endTime: null,
+        source: "none",
+        quality: "none",
+    };
+}
+/**
+ * Parse Cursor usage from local SQLite. Read-only — does NOT push anything
+ * to the costcanary backend.
+ *
+ * Returns aggregated session data per composer with per-session token totals,
+ * message counts, start/end timestamps, and daily usage buckets. Throws
+ * CursorParserError on unrecoverable failures (missing DB, missing sqlite3
+ * binary, malformed SQLite output).
+ *
+ * Dedup strategy: per composer, keep one entry per (serverBubbleId ?? bubbleId).
+ * On collision, keep the candidate with the larger token total.
+ *
+ * Mixed-model handling: if a composer contains multiple non-empty model names,
+ * the returned `model` field is "mixed". If no model info is present on any
+ * bubble, the field is "unknown".
+ *
+ * Sort order: total tokens descending.
+ */
+export function parseCursorUsage() {
+    const dbPath = getCursorDbPath();
+    // Throws CursorParserError on missing DB / missing sqlite3 / query failure
+    const bubbleRows = runCursorQuery("SELECT key, value FROM cursorDiskKV WHERE key LIKE 'bubbleId:%'");
+    const composerRows = runCursorQuery("SELECT key, value FROM cursorDiskKV WHERE key LIKE 'composerData:%'");
+    // Cursor splits model metadata, token usage, and timestamps across
+    // different bubble rows. We collect them into separate per-composer
+    // structures so each signal is captured even when rows carry only one
+    // of them.
+    //
+    // - tokenBubblesByComposer: per-composer dedup map for bubbles that carry
+    //   positive token counts. Dedup key is (serverBubbleId ?? bubbleId).
+    //   Collision rule: keep the candidate with the larger token total.
+    // - modelsByComposer: per-composer set of all distinct non-empty model
+    //   names found on ANY bubble row in the composer.
+    // - bubbleCreatedAtsByComposer: per-composer list of parsed bubble
+    //   createdAtMs values. Not deduped — we only need min/max, and duplicate
+    //   values are harmless for those aggregations.
+    // - composerMetaById: composerData row metadata, used as the fallback
+    //   source for per-session timestamps.
+    const tokenBubblesByComposer = new Map();
+    const modelsByComposer = new Map();
+    const bubbleCreatedAtsByComposer = new Map();
+    const composerMetaById = new Map();
+    for (const row of composerRows) {
+        const meta = parseComposerData(row);
+        if (!meta) {
+            continue;
+        }
+        composerMetaById.set(meta.composerId, meta);
+    }
+    for (const row of bubbleRows) {
+        const bubble = parseBubble(row);
+        if (!bubble) {
+            continue;
+        }
+        if (bubble.modelName) {
+            let composerModels = modelsByComposer.get(bubble.composerId);
+            if (!composerModels) {
+                composerModels = new Set();
+                modelsByComposer.set(bubble.composerId, composerModels);
+            }
+            composerModels.add(bubble.modelName);
+        }
+        if (bubble.createdAtMs !== null) {
+            let composerCreatedAts = bubbleCreatedAtsByComposer.get(bubble.composerId);
+            if (!composerCreatedAts) {
+                composerCreatedAts = [];
+                bubbleCreatedAtsByComposer.set(bubble.composerId, composerCreatedAts);
+            }
+            composerCreatedAts.push(bubble.createdAtMs);
+        }
+        if (!hasTokenUsage(bubble)) {
+            continue;
+        }
+        let composerMap = tokenBubblesByComposer.get(bubble.composerId);
+        if (!composerMap) {
+            composerMap = new Map();
+            tokenBubblesByComposer.set(bubble.composerId, composerMap);
+        }
+        const dedupKey = bubble.serverBubbleId ?? bubble.bubbleId;
+        const existing = composerMap.get(dedupKey);
+        if (existing) {
+            const existingTotal = existing.inputTokens + existing.outputTokens;
+            const newTotal = bubble.inputTokens + bubble.outputTokens;
+            if (newTotal > existingTotal) {
+                composerMap.set(dedupKey, bubble);
+            }
+            continue;
+        }
+        composerMap.set(dedupKey, bubble);
+    }
+    // Aggregate per composer into the parser output shape.
+    const sessions = [];
+    for (const [composerId, composerMap] of tokenBubblesByComposer) {
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let messageCount = 0;
+        const modelsSeen = modelsByComposer.get(composerId) ?? new Set();
+        const composerMeta = composerMetaById.get(composerId);
+        const bubbleCreatedAts = bubbleCreatedAtsByComposer.get(composerId) ?? [];
+        // Daily bucketing: for each token-bearing bubble, prefer its own
+        // createdAt; otherwise fall back to the composer's createdAt so the
+        // session still contributes to some day rather than silently
+        // dropping tokens from the daily view. We track whether any bucket
+        // used the composer fallback so the session-level dailyUsageSource
+        // reflects approximate day attribution.
+        const dailyUsage = {};
+        let anyBubbleFellBackToComposer = false;
+        for (const bubble of composerMap.values()) {
+            inputTokens += bubble.inputTokens;
+            outputTokens += bubble.outputTokens;
+            messageCount += 1;
+            let bucketMs = null;
+            if (bubble.createdAtMs !== null) {
+                bucketMs = bubble.createdAtMs;
+            }
+            else if (composerMeta?.createdAtMs != null) {
+                bucketMs = composerMeta.createdAtMs;
+                anyBubbleFellBackToComposer = true;
+            }
+            if (bucketMs !== null) {
+                const dateKey = msToUtcDateKey(bucketMs);
+                let bucket = dailyUsage[dateKey];
+                if (!bucket) {
+                    bucket = createEmptyTokenUsage();
+                    dailyUsage[dateKey] = bucket;
+                }
+                bucket.inputTokens += bubble.inputTokens;
+                bucket.outputTokens += bubble.outputTokens;
+            }
+        }
+        if (messageCount === 0) {
+            continue;
+        }
+        let model;
+        if (modelsSeen.size === 0) {
+            model = "unknown";
+        }
+        else if (modelsSeen.size === 1) {
+            model = Array.from(modelsSeen)[0];
+        }
+        else {
+            model = "mixed";
+        }
+        const timing = resolveSessionTimestamps(bubbleCreatedAts, composerMeta);
+        // dailyUsageSource classification:
+        //   "bubble"   — every bucket came from a bubble-level createdAt (precise)
+        //   "composer" — at least one bucket fell back to composer.createdAt,
+        //                so the whole per-day view is approximate. Any fallback
+        //                downgrades the entire session so downstream renderers
+        //                don't imply message-level precision we can't back up.
+        //   "none"     — no bucket had any timestamp source; dailyUsage is empty.
+        let dailyUsageSource;
+        if (Object.keys(dailyUsage).length === 0) {
+            dailyUsageSource = "none";
+        }
+        else if (anyBubbleFellBackToComposer) {
+            dailyUsageSource = "composer";
+        }
+        else {
+            dailyUsageSource = "bubble";
+        }
+        sessions.push({
+            sessionId: composerId,
+            workspaceHash: null,
+            workspaceName: null,
+            model,
+            tokens: {
+                inputTokens,
+                outputTokens,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+            },
+            messageCount,
+            filePath: dbPath,
+            startTime: timing.startTime,
+            endTime: timing.endTime,
+            timestampSource: timing.source,
+            timestampQuality: timing.quality,
+            dailyUsage,
+            dailyUsageSource,
+        });
+    }
+    // Sort by total tokens descending. Downstream surfaces can re-sort by
+    // startTime if chronological order matters.
+    sessions.sort((a, b) => {
+        const aTotal = a.tokens.inputTokens + a.tokens.outputTokens;
+        const bTotal = b.tokens.inputTokens + b.tokens.outputTokens;
+        return bTotal - aTotal;
+    });
+    return {
+        sessions,
+        filePath: dbPath,
+    };
+}
+/**
+ * Backward-compat alias. PR1 consumers called this function name; keep it
+ * working for one release after the rename.
+ */
+export const parseCursorUsageDryRun = parseCursorUsage;
+/**
+ * Truncate a UUID-ish identifier to 8 characters for safe display in
+ * transparency output. Real UUIDs become e.g. "399974f0" — enough for a
+ * human to distinguish keys at a glance, not enough to serve as a stable
+ * correlation handle if the output leaks.
+ */
+function truncateId(id) {
+    return id.length <= 8 ? id : id.slice(0, 8);
+}
+/**
+ * Return transparency metadata about the Cursor SQLite: file size, table
+ * list, key-prefix histogram, and a small sample of bubble and composer
+ * keys with their UUIDs truncated. Powers the `what_we_read` MCP mode so
+ * users can see exactly what data CostHawk is reading.
+ *
+ * Throws CursorParserError on missing DB, missing sqlite3, or query failure.
+ */
+export function getCursorMeta() {
+    const dbPath = getCursorDbPath();
+    if (!existsSync(dbPath)) {
+        const error = {
+            code: "CURSOR_DB_NOT_FOUND",
+            message: `Cursor SQLite database not found at ${dbPath}. Make sure Cursor is installed and you have used it at least once. Set COSTHAWK_CURSOR_DB_PATH to override.`,
+        };
+        throw error;
+    }
+    let dbFileSize = 0;
+    try {
+        dbFileSize = statSync(dbPath).size;
+    }
+    catch {
+        dbFileSize = 0;
+    }
+    const tableRows = runCursorQuery("SELECT name AS key, 'table' AS value FROM sqlite_master WHERE type='table' ORDER BY name");
+    const tables = tableRows.map((row) => row.key);
+    // Histogram of key prefixes in cursorDiskKV. The CASE expression mirrors
+    // the manual probe from Task #30 — substring up to the first colon, or
+    // the whole key if there is no colon. ORDER BY count(*) (not the TEXT
+    // cast of the count) so the ordering is numeric — otherwise "9" sorts
+    // above "184" lexicographically.
+    const prefixRows = runCursorQuery("SELECT CASE WHEN instr(key,':')>0 THEN substr(key,1,instr(key,':')-1) ELSE key END AS key, CAST(count(*) AS TEXT) AS value FROM cursorDiskKV GROUP BY 1 ORDER BY count(*) DESC");
+    const keyPrefixes = {};
+    for (const row of prefixRows) {
+        const count = Number.parseInt(row.value, 10);
+        if (Number.isFinite(count)) {
+            keyPrefixes[row.key] = count;
+        }
+    }
+    const bubbleSampleRows = runCursorQuery("SELECT key, '' AS value FROM cursorDiskKV WHERE key LIKE 'bubbleId:%' LIMIT 5");
+    const composerSampleRows = runCursorQuery("SELECT key, '' AS value FROM cursorDiskKV WHERE key LIKE 'composerData:%' LIMIT 5");
+    const sampleBubbleKeys = bubbleSampleRows.map((row) => {
+        const match = BUBBLE_KEY_REGEX.exec(row.key);
+        if (!match)
+            return row.key;
+        const [, composerId, bubbleId] = match;
+        return `bubbleId:${truncateId(composerId)}:${truncateId(bubbleId)}`;
+    });
+    const sampleComposerKeys = composerSampleRows.map((row) => {
+        const match = COMPOSER_KEY_REGEX.exec(row.key);
+        if (!match)
+            return row.key;
+        const [, composerId] = match;
+        return `composerData:${truncateId(composerId)}`;
+    });
+    return {
+        filePath: dbPath,
+        dbFileSize,
+        tables,
+        keyPrefixes,
+        sampleBubbleKeys,
+        sampleComposerKeys,
+    };
+}
+/**
+ * Run a full parser health check against the live DB. Reports coverage
+ * numbers, validates invariants, and classifies the result as PASS,
+ * DEGRADED, or FAIL.
+ *
+ * - FAIL is reserved for unrecoverable failures (DB missing, sqlite3
+ *   missing, query error). The MCP tool surfaces FAIL as isError:true.
+ * - DEGRADED means the parser ran but flagged warnings — e.g., invariant
+ *   tolerance exceeded, partial timestamp coverage, unexpected row shapes.
+ * - PASS means the parser ran cleanly with full coverage and no warnings.
+ *
+ * Never throws — catches errors and reports them as FAIL so callers can
+ * present the full structured payload to users.
+ */
+export function runCursorSelfTest() {
+    const dbPath = getCursorDbPath();
+    const sqlite3Path = getSqlite3Path();
+    const errors = [];
+    const warnings = [];
+    const invariantChecks = [];
+    const result = {
+        filePath: dbPath,
+        dbExists: existsSync(dbPath),
+        sqlite3Path,
+        canQuery: false,
+        tokenBubbleCount: 0,
+        composerCount: 0,
+        sessionsWithTokens: 0,
+        timestampCoverage: {
+            bubblesWithCreatedAt: 0,
+            totalBubbles: 0,
+            composersWithCreatedAt: 0,
+            totalComposers: 0,
+        },
+        invariantChecks,
+        warnings,
+        errors,
+        overallStatus: "FAIL",
+    };
+    if (!result.dbExists) {
+        errors.push(`Cursor SQLite database not found at ${dbPath}. Set COSTHAWK_CURSOR_DB_PATH to override.`);
+        return result;
+    }
+    let bubbleRows;
+    let composerRows;
+    try {
+        bubbleRows = runCursorQuery("SELECT key, value FROM cursorDiskKV WHERE key LIKE 'bubbleId:%'");
+        composerRows = runCursorQuery("SELECT key, value FROM cursorDiskKV WHERE key LIKE 'composerData:%'");
+        result.canQuery = true;
+    }
+    catch (err) {
+        const code = isCursorParserError(err) ? err.code : "UNKNOWN";
+        const message = err instanceof Error
+            ? err.message
+            : typeof err === "object" && err !== null && "message" in err
+                ? String(err.message)
+                : "Unknown error";
+        errors.push(`[${code}] ${message}`);
+        return result;
+    }
+    result.timestampCoverage.totalBubbles = bubbleRows.length;
+    result.timestampCoverage.totalComposers = composerRows.length;
+    // Count bubbles with a usable createdAt timestamp (string or number).
+    // This mirrors parseBubble's `createdAtMs` logic so the reported
+    // coverage matches what the parser will actually use.
+    for (const row of bubbleRows) {
+        let obj;
+        try {
+            obj = JSON.parse(row.value);
+        }
+        catch {
+            continue;
+        }
+        if (typeof obj !== "object" || obj === null)
+            continue;
+        const record = obj;
+        if (parseTimestampField(record.createdAt) !== null) {
+            result.timestampCoverage.bubblesWithCreatedAt += 1;
+        }
+    }
+    for (const row of composerRows) {
+        const meta = parseComposerData(row);
+        if (meta && meta.createdAtMs !== null) {
+            result.timestampCoverage.composersWithCreatedAt += 1;
+        }
+    }
+    // Invariant 1: the parser runs without throwing.
+    let parserResult = null;
+    try {
+        parserResult = parseCursorUsage();
+        invariantChecks.push({ name: "parser_runs", passed: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        invariantChecks.push({
+            name: "parser_runs",
+            passed: false,
+            details: message,
+        });
+        errors.push(`Parser threw: ${message}`);
+        return result;
+    }
+    result.sessionsWithTokens = parserResult.sessions.length;
+    result.tokenBubbleCount = parserResult.sessions.reduce((acc, s) => acc + s.messageCount, 0);
+    result.composerCount = composerRows.length;
+    // Invariant 2: every session has a non-null timestampSource classification.
+    const sessionsWithoutTiming = parserResult.sessions.filter((s) => s.timestampSource === "none");
+    if (sessionsWithoutTiming.length > 0) {
+        invariantChecks.push({
+            name: "all_sessions_have_timestamp_source",
+            passed: false,
+            details: `${sessionsWithoutTiming.length} sessions have timestampSource="none"`,
+        });
+        warnings.push(`${sessionsWithoutTiming.length}/${parserResult.sessions.length} sessions have no parseable timestamp source. They will appear with null startTime/endTime in usage output.`);
+    }
+    else {
+        invariantChecks.push({
+            name: "all_sessions_have_timestamp_source",
+            passed: true,
+        });
+    }
+    // Invariant 3: for every session that resolved start AND end, start <= end.
+    const ordering = parserResult.sessions.filter((s) => s.startTime !== null && s.endTime !== null);
+    const badOrdering = ordering.filter((s) => (s.startTime !== null ? Date.parse(s.startTime) : 0) >
+        (s.endTime !== null ? Date.parse(s.endTime) : 0));
+    if (badOrdering.length > 0) {
+        invariantChecks.push({
+            name: "start_time_le_end_time",
+            passed: false,
+            details: `${badOrdering.length} sessions violate start <= end`,
+        });
+        warnings.push(`${badOrdering.length} sessions have startTime > endTime after resolution. This is a parser bug — please report.`);
+    }
+    else {
+        invariantChecks.push({
+            name: "start_time_le_end_time",
+            passed: true,
+        });
+    }
+    // Invariant 4: for composers where both bubble and composer timestamps
+    // exist, min(bubble.createdAt) should be within tolerance of composer
+    // createdAt. Violations suggest schema drift or corrupt timing data.
+    //
+    // We re-derive the per-composer minimum bubble createdAtMs from
+    // bubbleRows directly rather than re-running the parser, so the check
+    // stays independent of any changes to the main aggregation logic.
+    const minBubbleCreatedAtByComposer = new Map();
+    for (const row of bubbleRows) {
+        const bubble = parseBubble(row);
+        if (!bubble || bubble.createdAtMs === null)
+            continue;
+        const prior = minBubbleCreatedAtByComposer.get(bubble.composerId);
+        if (prior === undefined || bubble.createdAtMs < prior) {
+            minBubbleCreatedAtByComposer.set(bubble.composerId, bubble.createdAtMs);
+        }
+    }
+    const composerMetaByIdForCheck = new Map();
+    for (const row of composerRows) {
+        const meta = parseComposerData(row);
+        if (meta)
+            composerMetaByIdForCheck.set(meta.composerId, meta);
+    }
+    let skewWarnings = 0;
+    for (const [composerId, minBubbleMs] of minBubbleCreatedAtByComposer) {
+        const meta = composerMetaByIdForCheck.get(composerId);
+        if (!meta || meta.createdAtMs === null)
+            continue;
+        const skew = meta.createdAtMs - minBubbleMs;
+        if (skew > INVARIANT_SKEW_TOLERANCE_MS) {
+            skewWarnings += 1;
+        }
+    }
+    if (skewWarnings > 0) {
+        invariantChecks.push({
+            name: "bubble_composer_createdat_skew",
+            passed: false,
+            details: `${skewWarnings} composers where min(bubble.createdAt) is more than ${INVARIANT_SKEW_TOLERANCE_MS / 1000}s before composerData.createdAt`,
+        });
+        warnings.push(`${skewWarnings} composers show unexpected clock skew between bubble and composer timestamps. Values are still usable but may indicate schema drift.`);
+    }
+    else {
+        invariantChecks.push({
+            name: "bubble_composer_createdat_skew",
+            passed: true,
+        });
+    }
+    if (errors.length > 0) {
+        result.overallStatus = "FAIL";
+    }
+    else if (warnings.length > 0) {
+        result.overallStatus = "DEGRADED";
+    }
+    else {
+        result.overallStatus = "PASS";
+    }
+    return result;
+}
+// Re-export the type guard so the MCP tool registration in index.ts can
+// distinguish CursorParserError from generic Error in its catch block.
+export { isCursorParserError };
+//# sourceMappingURL=cursor-parser.js.map