@aixle/insights 0.1.0

package/dist/client.js

@@ -0,0 +1,102 @@
+import { postEvent as sdkPostEvent, } from "./lib/index.js";
+import { mcpLog } from "./log.js";
+/** Delays after each failed attempt (not 429): initial try, then wait 1s, 4s, 16s before retries. */
+const TRANSIENT_RETRY_DELAYS_MS = [1000, 4000, 16_000];
+const RETRY_DELAY_LABELS = ["1s", "4s", "16s"];
+/** Optional zero-delay retries in Vitest (real `setTimeout` does not play well with `vi.useFakeTimers`). */
+let ingestRetryWaitOverride;
+/** @internal */
+export function setIngestRetryWaitOverrideForTests(fn) {
+    ingestRetryWaitOverride = fn;
+}
+function defaultWait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Single-event POST with intra-sync retries for transient failures (5xx / network).
+ * Does not retry 429: the SDK invokes `on429` and returns false immediately.
+ */
+export async function postEvent(payload, host, token, options = {}) {
+    const wait = options.waitMs ?? ingestRetryWaitOverride ?? defaultWait;
+    const logRetries = options.logTransientRetries !== false;
+    for (let attempt = 0; attempt <= TRANSIENT_RETRY_DELAYS_MS.length; attempt++) {
+        let was429 = false;
+        let httpStatus = null;
+        let networkFailed = false;
+        const merged = {
+            ...options,
+            onHttpError: (status, statusText, body) => {
+                httpStatus = status;
+                if (options.onHttpError) {
+                    options.onHttpError(status, statusText, body);
+                }
+                else {
+                    console.error(`Failed to post event: HTTP ${status} ${statusText}${body ? ` — ${body}` : ""}`);
+                }
+            },
+            onNetworkError: (err) => {
+                networkFailed = true;
+                if (options.onNetworkError) {
+                    options.onNetworkError(err);
+                }
+                else {
+                    console.error(`Network error posting event: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            },
+            on429: (retryAfter, quotaExceeded) => {
+                was429 = true;
+                options.on429?.(retryAfter, quotaExceeded);
+            },
+        };
+        const ok = await sdkPostEvent(payload, host, token, merged);
+        if (ok)
+            return true;
+        if (was429)
+            return false;
+        if (!networkFailed && (httpStatus === null || httpStatus < 500))
+            return false;
+        if (attempt >= TRANSIENT_RETRY_DELAYS_MS.length)
+            return false;
+        const delayMs = TRANSIENT_RETRY_DELAYS_MS[attempt];
+        const delayLabel = RETRY_DELAY_LABELS[attempt];
+        if (logRetries) {
+            mcpLog.warn("ingest_transient_retry", {
+                attempt: attempt + 1,
+                delay: delayLabel,
+                delay_ms: delayMs,
+                occurred_at: payload.occurred_at,
+            }, true);
+        }
+        await wait(delayMs);
+    }
+    return false;
+}
+/**
+ * Batch POST with sent/failed aggregation plus max `occurred_at` watermarking
+ * (used by Cursor multi-event sync loops).
+ */
+export async function postEvents(events, host, token, options = {}) {
+    if (events.length === 0)
+        return { sent: 0, failed: 0, lastSentAt: null };
+    const outcomes = await Promise.allSettled(events.map((event) => postEvent(event, host, token, options).then((ok) => ({ event, ok }))));
+    let sent = 0;
+    let failed = 0;
+    let lastSentAt = null;
+    for (const outcome of outcomes) {
+        if (outcome.status === "rejected") {
+            failed++;
+            continue;
+        }
+        if (outcome.value.ok) {
+            sent++;
+            const t = outcome.value.event.occurred_at;
+            if (typeof t === "string" && (lastSentAt === null || t > lastSentAt)) {
+                lastSentAt = t;
+            }
+        }
+        else {
+            failed++;
+        }
+    }
+    return { sent, failed, lastSentAt };
+}

package/dist/collect-cursor-payloads.d.ts

@@ -0,0 +1,57 @@
+import type { ProjectResolution } from "./lib/index.js";
+import type { State } from "./state.js";
+import { type CursorDb90Payload, type CursorTranscriptTurn, type PricingConfig } from "./readers/cursor.js";
+export interface CursorSliceGroup {
+    key: string;
+    label: string;
+    payloads: CursorDb90Payload[];
+}
+export interface PrepareCursorSliceGroupsOptions {
+    stateBefore: State;
+    fullScan?: boolean;
+    projectId?: string | null;
+    projectIdSource?: ProjectResolution["source"];
+    host?: string;
+    token?: string;
+    projectLookupToken?: string | null;
+    verbose?: boolean;
+    cursorBaseDir?: string;
+    cursorTranscriptProjectDirs?: string[];
+    cursorPricing?: PricingConfig;
+}
+export interface PreparedCursorSliceGroups {
+    groups: CursorSliceGroup[];
+    skippedTranscriptCount: number;
+    totalPayloadCount: number;
+    transcriptTurnsById: Map<string, CursorTranscriptTurn>;
+    counts: {
+        legacy: number;
+        dailyStatsEntriesRaw: number;
+        dailyStatsEntries: number;
+        recentCommitSnapshots: number;
+        transcriptTurns: number;
+        transcriptPayloads: number;
+        /** Chat events filtered from events+stats because transcript mode covers them. */
+        suppressedComposer: number;
+    };
+}
+export interface CollectLocalCursorPayloadsOptions {
+    /** Ignore watermarks and commit hash dedupe (default true for verify scripts). */
+    fullScan?: boolean;
+    projectId?: string | null;
+    verbose?: boolean;
+    cursorBaseDir?: string;
+    cursorTranscriptProjectDirs?: string[];
+    cursorPricing?: PricingConfig;
+    stateBefore?: State;
+}
+export interface CollectedCursorPayloads {
+    payloads: CursorDb90Payload[];
+    counts: PreparedCursorSliceGroups["counts"];
+}
+/**
+ * Read local Cursor stores, apply watermarks/dedupe, and group payloads for sync posting.
+ */
+export declare function prepareCursorSliceGroups(options: PrepareCursorSliceGroupsOptions): Promise<PreparedCursorSliceGroups>;
+/** Flat payload list for dry-run verification scripts (no POST). */
+export declare function collectLocalCursorPayloads(options?: CollectLocalCursorPayloadsOptions): Promise<CollectedCursorPayloads>;

package/dist/collect-cursor-payloads.js

@@ -0,0 +1,134 @@
+import { enrichCommitProjectAttribution } from "./lib/index.js";
+import { CURSOR_DAILY_STATS_WATERMARK_KEY, CURSOR_EVENTS_WATERMARK_KEY, CURSOR_RECENT_COMMIT_WATERMARK_KEY, CURSOR_TRANSCRIPT_TURN_PREFIX, CURSOR_WATERMARK_KEY, cursorTranscriptTurnStateKey, cursorWatermarkDate, filterRecentCommitsByHashDedup, } from "./cursor-checkpoints.js";
+import { readCursorActiveModel } from "./cursor-settings.js";
+import { readEvents as readCursorEvents, readDailyStatsWithDedupe, readRecentCommitSnapshots, readCursorTranscriptSessions, mapEvent as mapCursorEvent, mapTranscriptTurn as mapCursorTranscriptTurn, mapDailyStats, mapRecentCommit, DEFAULT_CURSOR_PRICING, } from "./readers/cursor.js";
+/**
+ * Read local Cursor stores, apply watermarks/dedupe, and group payloads for sync posting.
+ */
+export async function prepareCursorSliceGroups(options) {
+    const { stateBefore, fullScan = false, projectId = null, projectIdSource, host, token, projectLookupToken, verbose = false, cursorBaseDir, cursorTranscriptProjectDirs, cursorPricing = DEFAULT_CURSOR_PRICING, } = options;
+    const useCommitHashDedup = !fullScan;
+    const eventsSince = fullScan
+        ? null
+        : cursorWatermarkDate(stateBefore, CURSOR_EVENTS_WATERMARK_KEY, CURSOR_WATERMARK_KEY);
+    const dailyStatsSince = fullScan
+        ? null
+        : cursorWatermarkDate(stateBefore, CURSOR_DAILY_STATS_WATERMARK_KEY, CURSOR_WATERMARK_KEY);
+    const recentCommitSince = fullScan
+        ? null
+        : cursorWatermarkDate(stateBefore, CURSOR_RECENT_COMMIT_WATERMARK_KEY, CURSOR_WATERMARK_KEY);
+    const commitReadSince = useCommitHashDedup ? null : recentCommitSince;
+    if (verbose && fullScan) {
+        console.log("[verbose][cursor] Full scan — ignoring saved watermarks and commit hash dedupe");
+    }
+    const baseDir = cursorBaseDir;
+    const activeModel = readCursorActiveModel(baseDir) ?? undefined;
+    const transcriptTurns = await readCursorTranscriptSessions(baseDir, cursorTranscriptProjectDirs, verbose);
+    const rawEvents = readCursorEvents(eventsSince, baseDir, verbose);
+    const { raw: dailyStatsRaw, deduped: dailyStats } = readDailyStatsWithDedupe(dailyStatsSince, baseDir, verbose);
+    const recentCommitSnapshots = readRecentCommitSnapshots(commitReadSince, baseDir, verbose);
+    const projectIdOpt = projectId ?? undefined;
+    const transcriptTurnsById = new Map(transcriptTurns.map((turn) => [turn.turnId, turn]));
+    const transcriptPayloads = [...transcriptTurnsById.values()]
+        .filter((turn) => {
+        if (fullScan)
+            return true;
+        const known = stateBefore.sessions[cursorTranscriptTurnStateKey(turn.turnId)];
+        if (!known)
+            return true;
+        // Prefer content hash comparison when both sides have it (fileSize is a fallback)
+        if (known.contentHash && turn.contentHash)
+            return known.contentHash !== turn.contentHash;
+        return known.fileSize !== turn.fileSize;
+    })
+        .map((turn) => mapCursorTranscriptTurn(turn, projectIdOpt, cursorPricing, activeModel))
+        .sort((a, b) => a.occurred_at.localeCompare(b.occurred_at));
+    const skippedTranscriptCount = transcriptTurns.length - transcriptPayloads.length;
+    const transcriptModeEnabled = transcriptTurnsById.size > 0;
+    const allMappedFromEvents = rawEvents
+        .map(({ row, workspacePath }) => mapCursorEvent(row, workspacePath, projectIdOpt, cursorPricing))
+        .filter((e) => e !== null);
+    const allMappedFromStats = dailyStats
+        .flatMap((entry) => mapDailyStats(entry, projectIdOpt, cursorPricing, activeModel));
+    // When transcripts are present they cover the same chat activity — suppress the daily aggregates
+    // to prevent double-counting. Logged at info level in sync.ts via counts.suppressedComposer.
+    const mappedFromEvents = allMappedFromEvents.filter((payload) => !transcriptModeEnabled || payload.event_type !== "chat");
+    const mappedFromStats = allMappedFromStats.filter((payload) => !transcriptModeEnabled || payload.event_type !== "chat");
+    const suppressedComposer = transcriptModeEnabled
+        ? allMappedFromEvents.filter((p) => p.event_type === "chat").length +
+            allMappedFromStats.filter((p) => p.event_type === "chat").length
+        : 0;
+    let mappedFromCommits = recentCommitSnapshots
+        .map((snapshot) => mapRecentCommit(snapshot, projectIdOpt, cursorPricing, activeModel))
+        .filter((payload) => payload !== null)
+        .sort((a, b) => a.occurred_at.localeCompare(b.occurred_at));
+    if (useCommitHashDedup) {
+        mappedFromCommits = filterRecentCommitsByHashDedup(mappedFromCommits, stateBefore.lastRecentCommitHashes);
+    }
+    if (host) {
+        const lookupToken = projectLookupToken ?? token;
+        if (lookupToken) {
+            await enrichCommitProjectAttribution(mappedFromCommits, {
+                projectIdSource,
+                host,
+                token: lookupToken,
+                verbose,
+            });
+        }
+    }
+    const groups = [
+        {
+            key: CURSOR_TRANSCRIPT_TURN_PREFIX,
+            label: "transcripts",
+            payloads: transcriptPayloads,
+        },
+        {
+            key: CURSOR_EVENTS_WATERMARK_KEY,
+            label: "events",
+            payloads: mappedFromEvents.sort((a, b) => a.occurred_at.localeCompare(b.occurred_at)),
+        },
+        {
+            key: CURSOR_DAILY_STATS_WATERMARK_KEY,
+            label: "daily_stats",
+            payloads: mappedFromStats.sort((a, b) => a.occurred_at.localeCompare(b.occurred_at)),
+        },
+        {
+            key: CURSOR_RECENT_COMMIT_WATERMARK_KEY,
+            label: "recent_commit",
+            payloads: mappedFromCommits,
+        },
+    ];
+    const totalPayloadCount = groups.reduce((sum, group) => sum + group.payloads.length, 0);
+    return {
+        groups,
+        skippedTranscriptCount,
+        totalPayloadCount,
+        transcriptTurnsById,
+        counts: {
+            legacy: mappedFromEvents.length,
+            dailyStatsEntriesRaw: dailyStatsRaw.length,
+            dailyStatsEntries: dailyStats.length,
+            recentCommitSnapshots: recentCommitSnapshots.length,
+            transcriptTurns: transcriptTurns.length,
+            transcriptPayloads: transcriptPayloads.length,
+            suppressedComposer,
+        },
+    };
+}
+/** Flat payload list for dry-run verification scripts (no POST). */
+export async function collectLocalCursorPayloads(options = {}) {
+    const { fullScan = true, projectId = null, verbose = false, cursorBaseDir, cursorTranscriptProjectDirs, cursorPricing, stateBefore = { version: 1, sessions: {} }, } = options;
+    const prepared = await prepareCursorSliceGroups({
+        stateBefore,
+        fullScan,
+        projectId,
+        verbose,
+        cursorBaseDir,
+        cursorTranscriptProjectDirs,
+        cursorPricing,
+    });
+    return {
+        payloads: prepared.groups.flatMap((group) => group.payloads),
+        counts: prepared.counts,
+    };
+}

package/dist/credentials.d.ts

@@ -0,0 +1,2 @@
+export type { StoredCredentials, TelemetryToolId } from "./auth/credentials.js";
+export { loadCredentials, saveCredentials, saveStoredCredentials, clearCredentials, loadCredentialsFromFileOnly, credentialsHaveAnyToken, pickProjectLookupToken, } from "./auth/credentials.js";

package/dist/credentials.js

@@ -0,0 +1 @@
+export { loadCredentials, saveCredentials, saveStoredCredentials, clearCredentials, loadCredentialsFromFileOnly, credentialsHaveAnyToken, pickProjectLookupToken, } from "./auth/credentials.js";

package/dist/cursor-checkpoints.d.ts

@@ -0,0 +1,12 @@
+import type { State } from "./state.js";
+import type { CursorDb90Payload } from "./readers/cursor.js";
+/** Cursor SQLite watermark checkpoints — never collide with Claude `claude_code:*` session keys. */
+export declare const CURSOR_WATERMARK_KEY: "cursor:watermark";
+export declare const CURSOR_EVENTS_WATERMARK_KEY: "cursor:events_watermark";
+export declare const CURSOR_DAILY_STATS_WATERMARK_KEY: "cursor:daily_stats_watermark";
+export declare const CURSOR_RECENT_COMMIT_WATERMARK_KEY: "cursor:recent_commit_watermark";
+export declare const CURSOR_TRANSCRIPT_TURN_PREFIX: "cursor:transcript_turn:";
+export declare function cursorTranscriptTurnStateKey(turnId: string): string;
+export declare function cursorWatermarkDate(state: Pick<State, "sessions">, ...keys: string[]): Date | null;
+/** Skip recent-commit payloads whose hash was already successfully POSTed. */
+export declare function filterRecentCommitsByHashDedup(payloads: CursorDb90Payload[], lastRecentCommitHashes?: string[]): CursorDb90Payload[];

package/dist/cursor-checkpoints.js

@@ -0,0 +1,28 @@
+/** Cursor SQLite watermark checkpoints — never collide with Claude `claude_code:*` session keys. */
+export const CURSOR_WATERMARK_KEY = "cursor:watermark";
+export const CURSOR_EVENTS_WATERMARK_KEY = "cursor:events_watermark";
+export const CURSOR_DAILY_STATS_WATERMARK_KEY = "cursor:daily_stats_watermark";
+export const CURSOR_RECENT_COMMIT_WATERMARK_KEY = "cursor:recent_commit_watermark";
+export const CURSOR_TRANSCRIPT_TURN_PREFIX = "cursor:transcript_turn:";
+export function cursorTranscriptTurnStateKey(turnId) {
+    return `${CURSOR_TRANSCRIPT_TURN_PREFIX}${turnId}`;
+}
+export function cursorWatermarkDate(state, ...keys) {
+    const rec = keys
+        .map((key) => state.sessions[key])
+        .find((value) => value !== undefined);
+    if (!rec)
+        return null;
+    const d = new Date(rec.sentAt);
+    return isNaN(d.getTime()) ? null : d;
+}
+/** Skip recent-commit payloads whose hash was already successfully POSTed. */
+export function filterRecentCommitsByHashDedup(payloads, lastRecentCommitHashes) {
+    if (!lastRecentCommitHashes || lastRecentCommitHashes.length === 0)
+        return payloads;
+    const seen = new Set(lastRecentCommitHashes);
+    return payloads.filter((p) => {
+        const hash = p.metadata.commit_hash;
+        return !hash || !seen.has(hash);
+    });
+}

package/dist/cursor-config.d.ts

@@ -0,0 +1,5 @@
+import { type PricingConfig } from "./readers/cursor.js";
+export declare function parseCursorPricing(raw: Record<string, unknown>): Partial<PricingConfig> | undefined;
+/** Load optional Cursor line-cost overrides from `~/.aixle-insights/config.json`. */
+export declare function loadCursorConfig(appDir?: string): Partial<PricingConfig>;
+export declare function resolveCursorPricing(overrides?: Partial<PricingConfig>, appDir?: string): PricingConfig;

package/dist/cursor-config.js

@@ -0,0 +1,34 @@
+import { loadBaseConfig } from "./lib/index.js";
+import { getAppDir } from "./state.js";
+import { DEFAULT_CURSOR_PRICING, } from "./readers/cursor.js";
+export function parseCursorPricing(raw) {
+    const rawPricing = typeof raw.pricing === "object" && raw.pricing !== null
+        ? raw.pricing
+        : null;
+    if (!rawPricing)
+        return undefined;
+    const pricing = {};
+    for (const key of [
+        "tokens_per_line",
+        "completion_output_per_mtok",
+        "chat_input_per_mtok",
+        "chat_output_per_mtok",
+    ]) {
+        const value = rawPricing[key];
+        if (value == null || value === "" || typeof value === "boolean")
+            continue;
+        const num = Number(value);
+        if (!Number.isNaN(num) && num >= 0)
+            pricing[key] = num;
+    }
+    return Object.keys(pricing).length > 0 ? pricing : undefined;
+}
+/** Load optional Cursor line-cost overrides from `~/.aixle-insights/config.json`. */
+export function loadCursorConfig(appDir) {
+    return loadBaseConfig(appDir ?? getAppDir(), parseCursorPricing)
+        .pricing ?? {};
+}
+export function resolveCursorPricing(overrides, appDir) {
+    const fromFile = loadCursorConfig(appDir);
+    return { ...DEFAULT_CURSOR_PRICING, ...fromFile, ...overrides };
+}

package/dist/cursor-payload-contract.d.ts

@@ -0,0 +1,17 @@
+import type { CursorDb90Payload } from "./readers/cursor.js";
+/** Ingest paths for Cursor payloads emitted by telemetry-mcp. */
+export type CursorIngestPath = "daily_tab" | "daily_composer" | "legacy_request" | "recent_commit" | "mcp_transcript" | "cursor_hook";
+export interface PayloadValidationResult {
+    ok: boolean;
+    errors: string[];
+    path: CursorIngestPath | "unknown";
+}
+export declare function inferIngestPath(payload: CursorDb90Payload): CursorIngestPath | "unknown";
+export declare function validateCursorPayload(payload: CursorDb90Payload): PayloadValidationResult;
+export interface DryRunMatrixRow {
+    path: CursorIngestPath | "unknown";
+    count: number;
+    sample_occurred_at: string | null;
+}
+export declare function summarizeDryRunMatrix(payloads: CursorDb90Payload[]): DryRunMatrixRow[];
+export declare function printCursorDryRunValidationReport(payloads: CursorDb90Payload[]): boolean;

package/dist/cursor-payload-contract.js

@@ -0,0 +1,258 @@
+import { HOOK_COST_MODEL } from "./readers/cursor.js";
+const TOP_LEVEL_KEYS = new Set([
+    "tool_name",
+    "event_type",
+    "model",
+    "tokens_in",
+    "tokens_out",
+    "cost_usd",
+    "occurred_at",
+    "project_id",
+    "metadata",
+]);
+const METADATA_BASE_KEYS = new Set([
+    "cursor_session_id",
+    "workspace",
+    "workspace_scope",
+    "workspace_folder",
+    "cost_model",
+    "scannable",
+    "risk_level",
+]);
+const METADATA_COMMIT_KEYS = new Set([
+    ...METADATA_BASE_KEYS,
+    "source",
+    "commit_hash",
+    "commit_message",
+    "repo_name",
+    "branch_name",
+    "ai_percentage",
+]);
+const METADATA_TRANSCRIPT_KEYS = new Set([
+    "session_id",
+    "cursor_session_id",
+    "workspace",
+    "cost_model",
+    "scannable",
+    "risk_level",
+    "risk_categories",
+    "risk_score",
+    "transcript_source",
+    "composer_name",
+    "prompt_text",
+    "assistant_text",
+]);
+const METADATA_HOOK_KEYS = new Set([
+    "cursor_session_id",
+    "workspace",
+    "workspace_scope",
+    "cost_model",
+    "scannable",
+    "risk_level",
+    "ingest_source",
+    "hook_event_name",
+    "generation_id",
+    "hook_tool_name",
+    "duration_ms",
+    "session_id",
+]);
+const EVENT_TYPES = new Set(["completion", "chat", "commit"]);
+// Priority: cursor_hook (cost_model discriminant) > transcript_source > event_type/source > session-based legacy path
+// IMPORTANT: cursor_hook must be checked first — hook payloads set cursor_session_id (conversation_id)
+// which would otherwise misclassify as "legacy_request".
+export function inferIngestPath(payload) {
+    if (payload.metadata.cost_model === HOOK_COST_MODEL) {
+        return "cursor_hook";
+    }
+    if (payload.metadata.transcript_source === "agent_transcript") {
+        return "mcp_transcript";
+    }
+    if (payload.event_type === "commit" || payload.metadata.source === "recent_commit") {
+        return "recent_commit";
+    }
+    if (payload.metadata.cursor_session_id !== null) {
+        return "legacy_request";
+    }
+    if (payload.event_type === "completion")
+        return "daily_tab";
+    if (payload.event_type === "chat")
+        return "daily_composer";
+    return "unknown";
+}
+function unexpectedKeys(obj, allowed, label) {
+    const errors = [];
+    for (const key of Object.keys(obj)) {
+        if (!allowed.has(key))
+            errors.push(`${label}: unexpected key "${key}"`);
+    }
+    return errors;
+}
+function isNonNegativeNumber(value, field) {
+    if (typeof value !== "number" || Number.isNaN(value) || value < 0) {
+        return `${field} must be a non-negative number`;
+    }
+    return null;
+}
+export function validateCursorPayload(payload) {
+    const errors = [];
+    const path = inferIngestPath(payload);
+    errors.push(...unexpectedKeys(payload, TOP_LEVEL_KEYS, "payload"));
+    if (payload.tool_name !== "cursor")
+        errors.push('tool_name must be "cursor"');
+    if (!EVENT_TYPES.has(payload.event_type)) {
+        errors.push(`event_type must be one of ${[...EVENT_TYPES].join(", ")}`);
+    }
+    if (typeof payload.model !== "string" || payload.model.length === 0) {
+        errors.push("model must be a non-empty string");
+    }
+    for (const field of ["tokens_in", "tokens_out", "cost_usd"]) {
+        const err = isNonNegativeNumber(payload[field], field);
+        if (err)
+            errors.push(err);
+    }
+    if (typeof payload.occurred_at !== "string" || Number.isNaN(Date.parse(payload.occurred_at))) {
+        errors.push("occurred_at must be a valid ISO-8601 string");
+    }
+    if (payload.project_id !== undefined && typeof payload.project_id !== "string") {
+        errors.push("project_id must be a string when present");
+    }
+    const meta = payload.metadata;
+    if (typeof meta !== "object" || meta === null) {
+        errors.push("metadata must be an object");
+    }
+    else {
+        const allowedMeta = path === "recent_commit"
+            ? METADATA_COMMIT_KEYS
+            : path === "mcp_transcript"
+                ? METADATA_TRANSCRIPT_KEYS
+                : path === "cursor_hook"
+                    ? METADATA_HOOK_KEYS
+                    : METADATA_BASE_KEYS;
+        errors.push(...unexpectedKeys(meta, allowedMeta, "metadata"));
+        if (meta.cursor_session_id !== null && typeof meta.cursor_session_id !== "string") {
+            errors.push("metadata.cursor_session_id must be string or null");
+        }
+        if (typeof meta.workspace !== "string" || meta.workspace.length === 0) {
+            errors.push("metadata.workspace must be a non-empty string");
+        }
+        if (path !== "mcp_transcript" && path !== "cursor_hook") {
+            if (meta.workspace_scope !== "global" && meta.workspace_scope !== "workspace") {
+                errors.push('metadata.workspace_scope must be "global" or "workspace"');
+            }
+            if (meta.workspace_folder !== undefined && typeof meta.workspace_folder !== "string") {
+                errors.push("metadata.workspace_folder must be a string when present");
+            }
+            if (meta.workspace_scope === "global" && meta.workspace_folder !== undefined) {
+                errors.push("metadata.workspace_folder must be omitted when workspace_scope is global");
+            }
+        }
+        if (path === "cursor_hook") {
+            if (meta.cost_model !== HOOK_COST_MODEL) {
+                errors.push(`metadata.cost_model must be "${HOOK_COST_MODEL}" for hook ingest`);
+            }
+            if (meta.ingest_source !== "cursor_hook") {
+                errors.push('metadata.ingest_source must be "cursor_hook"');
+            }
+            if (typeof meta.session_id !== "string" || meta.session_id.length === 0) {
+                errors.push("metadata.session_id must be a non-empty string for hook ingest");
+            }
+        }
+        else if (path === "legacy_request") {
+            if (meta.cost_model !== "token_count") {
+                errors.push('metadata.cost_model must be "token_count" for legacy cursor.db ingest');
+            }
+        }
+        else if (path === "mcp_transcript") {
+            if (meta.cost_model !== "estimated_transcript_text") {
+                errors.push('metadata.cost_model must be "estimated_transcript_text" for transcript ingest');
+            }
+            if (meta.transcript_source !== "agent_transcript") {
+                errors.push('metadata.transcript_source must be "agent_transcript"');
+            }
+            if (meta.scannable !== true) {
+                errors.push("metadata.scannable must be true for transcript ingest");
+            }
+            if (typeof meta.session_id !== "string" || meta.session_id.length === 0) {
+                errors.push("metadata.session_id must be a non-empty string for transcript ingest");
+            }
+        }
+        else if (meta.cost_model !== "estimated_line_count") {
+            errors.push('metadata.cost_model must be "estimated_line_count" for line-based cursor ingest');
+        }
+        if (path !== "mcp_transcript" && path !== "cursor_hook" && meta.scannable !== false) {
+            errors.push("metadata.scannable must be false");
+        }
+        if (path === "cursor_hook" && meta.scannable !== false) {
+            errors.push("metadata.scannable must be false for hook ingest");
+        }
+        if (path !== "mcp_transcript" && meta.risk_level !== "none") {
+            errors.push('metadata.risk_level must be "none"');
+        }
+        if (path === "recent_commit") {
+            if (meta.source !== "recent_commit") {
+                errors.push('metadata.source must be "recent_commit" for commit path');
+            }
+            if (payload.event_type !== "commit") {
+                errors.push('event_type must be "commit" when metadata.source is recent_commit');
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors, path };
+}
+export function summarizeDryRunMatrix(payloads) {
+    const byPath = new Map();
+    for (const p of payloads) {
+        const ingestPath = inferIngestPath(p);
+        const list = byPath.get(ingestPath) ?? [];
+        list.push(p);
+        byPath.set(ingestPath, list);
+    }
+    const order = [
+        "daily_tab",
+        "daily_composer",
+        "legacy_request",
+        "recent_commit",
+        "mcp_transcript",
+        "cursor_hook",
+        "unknown",
+    ];
+    return order
+        .filter((path) => (byPath.get(path)?.length ?? 0) > 0)
+        .map((path) => {
+        const list = byPath.get(path);
+        return {
+            path,
+            count: list.length,
+            sample_occurred_at: list[0]?.occurred_at ?? null,
+        };
+    });
+}
+export function printCursorDryRunValidationReport(payloads) {
+    let allOk = true;
+    for (let i = 0; i < payloads.length; i++) {
+        const result = validateCursorPayload(payloads[i]);
+        if (!result.ok) {
+            allOk = false;
+            console.error(`[dry-run][cursor] Payload #${i + 1} (${result.path}) contract errors:`);
+            for (const err of result.errors)
+                console.error(`  - ${err}`);
+        }
+    }
+    const matrix = summarizeDryRunMatrix(payloads);
+    console.log("[dry-run][cursor] Ingest path matrix:");
+    for (const row of matrix) {
+        console.log(`  ${row.path}: ${row.count} event(s)` +
+            (row.sample_occurred_at ? ` (e.g. ${row.sample_occurred_at})` : ""));
+    }
+    const expectedPaths = ["daily_tab", "daily_composer", "recent_commit"];
+    const seen = new Set(matrix.map((r) => r.path));
+    for (const path of expectedPaths) {
+        if (!seen.has(path)) {
+            console.warn(`[dry-run][cursor] No payloads for path "${path}" — OK if Cursor had no activity there`);
+        }
+    }
+    if (allOk) {
+        console.log("[dry-run][cursor] All payloads match the cursor ingest contract (DATA-CURSOR.md §3.5 + MCP transcripts).");
+    }
+    return allOk;
+}

package/dist/cursor-settings.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Best-effort: read active model name from Cursor's settings.json.
+ * Returns null on any error (file absent, unreadable, no matching key).
+ * Never throws.
+ */
+export declare function readCursorActiveModel(baseDir?: string): string | null;