costhawk 1.5.12 → 1.5.13

package/dist/build-info.d.ts

@@ -1,2 +1,2 @@
-export declare const BUILD_COMMIT_SHA = "d2dc17c";
+export declare const BUILD_COMMIT_SHA = "1ed40d7";
 //# sourceMappingURL=build-info.d.ts.map

package/dist/build-info.js

@@ -1,3 +1,3 @@
 // Auto-generated during release builds. Values may be empty in dev.
-export const BUILD_COMMIT_SHA = "d2dc17c";
+export const BUILD_COMMIT_SHA = "1ed40d7";
 //# sourceMappingURL=build-info.js.map

package/dist/cursor-parser.d.ts

@@ -1,8 +1,8 @@
 /**
- * Cursor Local SQLite Parser (PR1 — dry-run only)
+ * Cursor Local SQLite Parser
  *
  * Parses Cursor IDE chat history from the local SQLite database to extract
- * token usage data. Read-only. Does not push to any backend.
+ * token usage and timestamps. Read-only. Does not push to any backend.
  *
  * Storage:
  *   macOS:   ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
@@ -18,22 +18,40 @@
  * on bubble rows. Model name at $.modelInfo.modelName. Server-side dedup id
  * at $.serverBubbleId.
  *
- * NOTE (PR1 scope): Cursor message timestamps are not yet verified across
- * versions, so this dry-run parser does NOT return startTime/endTime/dailyUsage.
- * PR2 will add timestamp support after verification on real Cursor data.
+ * 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.
  *
- * Workspace metadata fields (workspaceHash/workspaceName) are also unverified
- * and return null until PR2 confirms the stable field source.
+ * 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 type { TokenUsage } from "./transcript-parser.js";
 /**
- * Single Cursor session in dry-run output.
+ * Single Cursor session in parser output.
  *
  * Shape is intentionally distinct from Claude/Codex SessionUsage because
- * Cursor message timestamps are not yet verified — startTime/endTime are
- * deliberately absent until PR2 verifies the stable timestamp source.
+ * Cursor's timestamp coverage is partial — provenance fields surface
+ * whether startTime/endTime/dailyUsage came from per-bubble timestamps
+ * (precise) or a composer-level fallback (approximate).
+ *
+ * workspaceHash / workspaceName remain null — composerData.name is a
+ * candidate for workspaceName but was not verified in Task #30 and is
+ * deferred to a later release.
  */
-export interface CursorSessionUsageDryRun {
+export interface CursorSessionUsage {
     sessionId: string;
     workspaceHash: string | null;
     workspaceName: string | null;
@@ -41,13 +59,74 @@ export interface CursorSessionUsageDryRun {
     tokens: TokenUsage;
     messageCount: number;
     filePath: string;
+    startTime: string | null;
+    endTime: string | null;
+    timestampSource: "bubble" | "composer" | "mixed" | "none";
+    timestampQuality: "precise" | "approximate" | "none";
+    dailyUsage: Record<string, TokenUsage>;
+    dailyUsageSource: "bubble" | "composer" | "none";
+}
+/**
+ * Backward-compat alias. PR1 shipped `CursorSessionUsageDryRun` in the
+ * published `.d.ts`; removing it in a patch release would be a breaking
+ * change for anyone who imported the type. The alias will be kept for at
+ * least one release after the rename.
+ */
+export type CursorSessionUsageDryRun = CursorSessionUsage;
+/**
+ * Transparency payload for the `what_we_read` MCP mode. Describes where
+ * the parser is reading from and what it sees at the table/prefix level,
+ * without leaking conversation content. UUIDs in sample keys are
+ * truncated to 8 characters — enough to distinguish keys at a glance,
+ * not enough to be a stable correlation handle.
+ */
+export interface CursorMeta {
+    filePath: string;
+    dbFileSize: number;
+    tables: string[];
+    keyPrefixes: Record<string, number>;
+    sampleBubbleKeys: string[];
+    sampleComposerKeys: string[];
+}
+/**
+ * Output of the `self_test` MCP mode. Runs the full parser pipeline and
+ * reports health + coverage + invariant checks. overallStatus semantics:
+ *   PASS     — parser ran, invariants held, coverage looks healthy
+ *   DEGRADED — parser ran but some bubbles lack timestamps / invariants
+ *              tripped warnings / coverage is partial. Not an error.
+ *   FAIL     — parser could not run (missing DB, missing sqlite3, query
+ *              failure, or corrupt top-level output). Surfaces as
+ *              MCP isError:true at the tool boundary.
+ */
+export interface CursorSelfTestResult {
+    filePath: string;
+    dbExists: boolean;
+    sqlite3Path: string;
+    canQuery: boolean;
+    tokenBubbleCount: number;
+    composerCount: number;
+    sessionsWithTokens: number;
+    timestampCoverage: {
+        bubblesWithCreatedAt: number;
+        totalBubbles: number;
+        composersWithCreatedAt: number;
+        totalComposers: number;
+    };
+    invariantChecks: Array<{
+        name: string;
+        passed: boolean;
+        details?: string;
+    }>;
+    warnings: string[];
+    errors: string[];
+    overallStatus: "PASS" | "DEGRADED" | "FAIL";
 }
 export interface CursorParserError {
     code: "CURSOR_DB_NOT_FOUND" | "CURSOR_SQLITE3_NOT_FOUND" | "CURSOR_SQLITE_QUERY_FAILED";
     message: string;
 }
 export interface CursorParserResult {
-    sessions: CursorSessionUsageDryRun[];
+    sessions: CursorSessionUsage[];
     filePath: string;
 }
 /**
@@ -64,12 +143,13 @@ export declare function cursorDbExists(): boolean;
  */
 declare function isCursorParserError(value: unknown): value is CursorParserError;
 /**
- * Parse Cursor usage from local SQLite. Read-only dry run — does NOT push
- * anything to the costcanary backend.
+ * 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
- * and message counts. Throws CursorParserError on unrecoverable failures
- * (missing DB, missing sqlite3 binary, malformed SQLite output).
+ * 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.
@@ -78,9 +158,37 @@ declare function isCursorParserError(value: unknown): value is CursorParserError
  * the returned `model` field is "mixed". If no model info is present on any
  * bubble, the field is "unknown".
  *
- * Sort order: total tokens descending. NOT chronological — message timestamps
- * are not yet verified for Cursor.
+ * Sort order: total tokens descending.
+ */
+export declare function parseCursorUsage(): CursorParserResult;
+/**
+ * Backward-compat alias. PR1 consumers called this function name; keep it
+ * working for one release after the rename.
+ */
+export declare const parseCursorUsageDryRun: typeof parseCursorUsage;
+/**
+ * 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 declare function getCursorMeta(): CursorMeta;
+/**
+ * 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 declare function parseCursorUsageDryRun(): CursorParserResult;
+export declare function runCursorSelfTest(): CursorSelfTestResult;
 export { isCursorParserError };
 //# sourceMappingURL=cursor-parser.d.ts.map

package/dist/cursor-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-parser.d.ts","sourceRoot":"","sources":["../src/cursor-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAOzD;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EACA,qBAAqB,GACrB,0BAA0B,GAC1B,4BAA4B,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,wBAAwB,EAAE,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAmCxC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAUD;;GAEG;AACH,iBAAS,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAYvE;AA+KD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,IAAI,kBAAkB,CAuH3D;AAID,OAAO,EAAE,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"cursor-parser.d.ts","sourceRoot":"","sources":["../src/cursor-parser.ts"],"names":[],"mappings":"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"}