@aixle/insights 0.1.0

package/dist/hooks/cursor-hooks-mapper.d.ts

@@ -0,0 +1,22 @@
+import type { HookLogEvent } from "./hooks-config.js";
+import type { CursorDb90Payload } from "../readers/cursor.js";
+export { HookLogEvent };
+/** State key prefix for hook event dedup in state.sessions. */
+export declare const CURSOR_HOOK_STATE_PREFIX: "cursor:hook:";
+/**
+ * Returns the dedup key used both in state.sessions and metadata.session_id
+ * so MCP state wipe doesn't cause duplicates (server-side upsert on session_id).
+ */
+export declare function hookDedupeKey(event: HookLogEvent): string;
+/**
+ * Returns false for events that carry no attribution value or can't be deduped.
+ * Logs a reason at debug level so ops can diagnose unexpected drops.
+ */
+export declare function shouldIngestHookEvent(event: HookLogEvent, verbose?: boolean): boolean;
+/** Warn-only version gate — Cursor builds can have unusual version strings. */
+export declare function warnOnCursorVersion(event: HookLogEvent, verbose: boolean): void;
+/**
+ * Map a validated hook event to the CursorDb90Payload contract.
+ * Call shouldIngestHookEvent() before this — it does not re-validate.
+ */
+export declare function mapHookEventToPayload(event: HookLogEvent, projectId?: string | null): CursorDb90Payload;

package/dist/hooks/cursor-hooks-mapper.js

@@ -0,0 +1,84 @@
+import { HOOK_COST_MODEL } from "../readers/cursor.js";
+import { mcpLog } from "../log.js";
+/** State key prefix for hook event dedup in state.sessions. */
+export const CURSOR_HOOK_STATE_PREFIX = "cursor:hook:";
+const MIN_CURSOR_VERSION_MAJOR = 1;
+const MIN_CURSOR_VERSION_MINOR = 7;
+/**
+ * Returns the dedup key used both in state.sessions and metadata.session_id
+ * so MCP state wipe doesn't cause duplicates (server-side upsert on session_id).
+ */
+export function hookDedupeKey(event) {
+    return `${CURSOR_HOOK_STATE_PREFIX}${event.conversation_id ?? ""}:${event.generation_id ?? ""}:${event.hook_event_name ?? ""}`;
+}
+/**
+ * Returns false for events that carry no attribution value or can't be deduped.
+ * Logs a reason at debug level so ops can diagnose unexpected drops.
+ */
+export function shouldIngestHookEvent(event, verbose = false) {
+    if (event.hook_event_name === "parse_error" ||
+        event.hook_event_name === "log_parse_error") {
+        mcpLog.warn("hook_event_dropped", { reason: "parse_error", event: event.hook_event_name }, verbose);
+        return false;
+    }
+    if (!event.conversation_id || !event.hook_event_name) {
+        mcpLog.warn("hook_event_dropped", { reason: "missing_dedup_fields" }, verbose);
+        return false;
+    }
+    if (!event.model || event.model === "unknown") {
+        mcpLog.info("hook_event_dropped", { reason: "no_model_attribution", hook: event.hook_event_name }, verbose);
+        return false;
+    }
+    return true;
+}
+/** Warn-only version gate — Cursor builds can have unusual version strings. */
+export function warnOnCursorVersion(event, verbose) {
+    const v = event.cursor_version;
+    if (typeof v !== "string")
+        return;
+    const parts = v.split(".");
+    const major = parseInt(parts[0] ?? "0", 10);
+    const minor = parseInt(parts[1] ?? "0", 10);
+    if (major < MIN_CURSOR_VERSION_MAJOR || (major === MIN_CURSOR_VERSION_MAJOR && minor < MIN_CURSOR_VERSION_MINOR)) {
+        mcpLog.warn("hook_cursor_version_old", { cursor_version: v, required: `${MIN_CURSOR_VERSION_MAJOR}.${MIN_CURSOR_VERSION_MINOR}` }, true);
+        if (verbose) {
+            console.warn(`[aixle-insights][cursor-hooks] cursor_version ${v} is older than ${MIN_CURSOR_VERSION_MAJOR}.${MIN_CURSOR_VERSION_MINOR} — hook payload shape may differ`);
+        }
+    }
+}
+/**
+ * Map a validated hook event to the CursorDb90Payload contract.
+ * Call shouldIngestHookEvent() before this — it does not re-validate.
+ */
+export function mapHookEventToPayload(event, projectId) {
+    const workspace = Array.isArray(event.workspace_roots) && typeof event.workspace_roots[0] === "string"
+        ? event.workspace_roots[0]
+        : "unknown";
+    const dedupeKey = hookDedupeKey(event);
+    const payload = {
+        tool_name: "cursor",
+        event_type: "chat",
+        model: event.model,
+        tokens_in: 0,
+        tokens_out: 0,
+        cost_usd: 0,
+        occurred_at: event.captured_at ?? new Date().toISOString(),
+        metadata: {
+            cursor_session_id: event.conversation_id ?? null,
+            workspace,
+            workspace_scope: "global",
+            cost_model: HOOK_COST_MODEL,
+            scannable: false,
+            risk_level: "none",
+            ingest_source: "cursor_hook",
+            hook_event_name: event.hook_event_name,
+            generation_id: event.generation_id,
+            hook_tool_name: event.tool_name,
+            duration_ms: typeof event.duration_ms === "number" ? event.duration_ms : undefined,
+            session_id: dedupeKey,
+        },
+    };
+    if (projectId)
+        payload.project_id = projectId;
+    return payload;
+}

package/dist/hooks/cursor-hooks-reader.d.ts

@@ -0,0 +1,30 @@
+import type { State } from "../state.js";
+import { CURSOR_HOOK_STATE_PREFIX } from "./cursor-hooks-mapper.js";
+export { CURSOR_HOOK_STATE_PREFIX };
+export interface ProcessHooksQueueParams {
+    queuePath: string;
+    /** Only process events whose workspace_roots[0] is under this directory. Omit to process all. */
+    scopeDir?: string;
+    state: State;
+    host: string;
+    token: string;
+    /** Called when a 429 is received. */
+    on429: (retryAfter: number, quotaExceeded: boolean) => void;
+    /** If true, skip events already in state.sessions. */
+    skipSeen?: boolean;
+    resolveProjectId?: (workspace: string) => Promise<string | null>;
+    verbose?: boolean;
+}
+export interface ProcessHooksResult {
+    sent: number;
+    failed: number;
+    skipped: number;
+    state: State;
+}
+/**
+ * Read the hooks queue, POST new events, and atomically rewrite the queue
+ * keeping only lines that failed to send (for retry on next cycle).
+ *
+ * Partial failure: lines that succeeded are removed; lines that failed stay.
+ */
+export declare function processHooksQueue(params: ProcessHooksQueueParams): Promise<ProcessHooksResult>;

package/dist/hooks/cursor-hooks-reader.js

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { markSessionSent } from "../state.js";
+import { postEvent } from "../client.js";
+import { mcpLog } from "../log.js";
+import { shouldIngestHookEvent, mapHookEventToPayload, hookDedupeKey, warnOnCursorVersion, CURSOR_HOOK_STATE_PREFIX, } from "./cursor-hooks-mapper.js";
+export { CURSOR_HOOK_STATE_PREFIX };
+function isUnderScopeDir(workspace, scopeDir) {
+    return workspace === scopeDir || workspace.startsWith(scopeDir + "/");
+}
+/**
+ * The forwarder redacts the home directory to "~" in workspace_roots for
+ * privacy in the on-disk queue. Expand it back to an absolute path here so
+ * scopeDir comparison and git-remote project resolution operate on a real
+ * filesystem path. The payload's metadata.workspace stays redacted (the mapper
+ * reads event.workspace_roots directly).
+ */
+function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+function workspaceFromEvent(event) {
+    if (Array.isArray(event.workspace_roots) && typeof event.workspace_roots[0] === "string") {
+        return expandHome(event.workspace_roots[0]);
+    }
+    return "";
+}
+/**
+ * Rewrite the queue file keeping only the lines at the given indices.
+ * Uses atomic rename to avoid corruption if the process is interrupted.
+ */
+function rewriteQueueKeepingLines(queuePath, allLines, keepIndices) {
+    const remaining = allLines.filter((_, i) => keepIndices.has(i));
+    const tmp = join(tmpdir(), `db90-hooks-queue-${randomBytes(6).toString("hex")}.ndjson`);
+    writeFileSync(tmp, remaining.length > 0 ? remaining.join("\n") + "\n" : "", "utf-8");
+    renameSync(tmp, queuePath);
+}
+/**
+ * Read the hooks queue, POST new events, and atomically rewrite the queue
+ * keeping only lines that failed to send (for retry on next cycle).
+ *
+ * Partial failure: lines that succeeded are removed; lines that failed stay.
+ */
+export async function processHooksQueue(params) {
+    const { queuePath, scopeDir, host, token, on429, skipSeen = true, resolveProjectId, verbose = false, } = params;
+    if (!existsSync(queuePath)) {
+        return { sent: 0, failed: 0, skipped: 0, state: params.state };
+    }
+    // Single read — avoids a race window where the forwarder appends between two
+    // separate readFileSync calls, which would cause newly-appended events to be
+    // silently dropped during the queue rewrite.
+    const rawContent = readFileSync(queuePath, "utf-8");
+    const rawLines = rawContent.split("\n").filter((l) => l.trim().length > 0);
+    const allEvents = rawLines.map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return { hook_event_name: "log_parse_error" };
+        }
+    });
+    if (allEvents.length === 0) {
+        return { sent: 0, failed: 0, skipped: 0, state: params.state };
+    }
+    let stateMut = params.state;
+    let totalSent = 0;
+    let totalFailed = 0;
+    let totalSkipped = 0;
+    const failedIndices = new Set();
+    for (let i = 0; i < allEvents.length; i++) {
+        const event = allEvents[i];
+        if (!shouldIngestHookEvent(event, verbose)) {
+            totalSkipped++;
+            continue;
+        }
+        warnOnCursorVersion(event, verbose);
+        const workspace = workspaceFromEvent(event);
+        if (scopeDir && workspace && !isUnderScopeDir(workspace, scopeDir)) {
+            if (verbose) {
+                console.log(`[verbose][cursor-hooks] Skipping event — workspace=${workspace} not under scopeDir=${scopeDir}`);
+            }
+            totalSkipped++;
+            continue;
+        }
+        const dedupeKey = hookDedupeKey(event);
+        if (skipSeen && stateMut.sessions[dedupeKey]) {
+            totalSkipped++;
+            continue;
+        }
+        let projectId;
+        if (resolveProjectId && workspace) {
+            projectId = await resolveProjectId(workspace);
+        }
+        const payload = mapHookEventToPayload(event, projectId);
+        const ok = await postEvent(payload, host, token, { on429 });
+        if (ok) {
+            totalSent++;
+            stateMut = markSessionSent(stateMut, dedupeKey, 0);
+        }
+        else {
+            totalFailed++;
+            failedIndices.add(i);
+            mcpLog.error("sync_ingest_final_failure", { tool: "cursor", group: "cursor_hook", occurred_at: payload.occurred_at }, true);
+        }
+    }
+    // Rewrite queue: keep only lines that failed to send (retry next cycle)
+    if (allEvents.length > 0) {
+        rewriteQueueKeepingLines(queuePath, rawLines, failedIndices);
+    }
+    mcpLog.info("cursor_hook_sync_complete", { sent: totalSent, failed: totalFailed, skipped: totalSkipped }, verbose);
+    return { sent: totalSent, failed: totalFailed, skipped: totalSkipped, state: stateMut };
+}

package/dist/hooks/hook-forwarder.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Append redacted Cursor hook stdin to the aixle-insights hooks queue.
+ * Cursor invokes this via ~/.cursor/hooks.json on sessionEnd / postToolUse.
+ * No credentials here — aixle-insights reads the queue and POSTs on the next sync cycle.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const DEFAULT_APP_DIR = join(homedir(), ".aixle-insights");
+
+/**
+ * Resolve the app dir. Cursor's hooks.json has no `env` support, so the
+ * installer passes `--app-dir <path>` in the command string. Precedence:
+ * CLI arg → AIXLE_INSIGHTS_HOME env → default (~/.aixle-insights).
+ */
+function getAppDir() {
+  const argv = process.argv.slice(2);
+  const flagIdx = argv.indexOf("--app-dir");
+  if (flagIdx !== -1 && typeof argv[flagIdx + 1] === "string" && argv[flagIdx + 1].trim()) {
+    return argv[flagIdx + 1].trim();
+  }
+  return process.env.AIXLE_INSIGHTS_HOME?.trim() || DEFAULT_APP_DIR;
+}
+
+function getQueuePath() {
+  return join(getAppDir(), "hooks-queue.ndjson");
+}
+
+function redactPath(p) {
+  if (typeof p !== "string") return p;
+  return p.replaceAll(homedir(), "~");
+}
+
+function redactValue(key, value) {
+  if (value === null || value === undefined) return value;
+
+  if (key === "user_email") return "[redacted]";
+  if (key === "transcript_path") {
+    return typeof value === "string" ? "[redacted]" : value;
+  }
+  if (key === "workspace_roots" && Array.isArray(value)) {
+    return value.map((r) => redactPath(String(r)));
+  }
+  if (
+    key === "tool_input" ||
+    key === "tool_output" ||
+    key === "text" ||
+    key === "agent_message" ||
+    key === "error_message" ||
+    key === "command"
+  ) {
+    const s = typeof value === "string" ? value : JSON.stringify(value);
+    return `[redacted, ${s.length} chars]`;
+  }
+  if (typeof value === "object" && !Array.isArray(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = redactValue(k, v);
+    }
+    return out;
+  }
+  return value;
+}
+
+function redactHookPayload(raw) {
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    out[key] = redactValue(key, value);
+  }
+  return out;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+async function main() {
+  const input = await readStdin();
+  const queuePath = getQueuePath();
+
+  let payload;
+  try {
+    payload = JSON.parse(input || "{}");
+  } catch {
+    payload = { hook_event_name: "parse_error", raw_length: input.length };
+  }
+
+  const entry = {
+    captured_at: new Date().toISOString(),
+    ...redactHookPayload(payload),
+  };
+
+  mkdirSync(dirname(queuePath), { recursive: true });
+  appendFileSync(queuePath, `${JSON.stringify(entry)}\n`, "utf-8");
+
+  // Cursor requires an empty JSON object response from hook scripts.
+  process.stdout.write("{}");
+}
+
+main().catch((err) => {
+  console.error(`[db90-hook-forwarder] ${err instanceof Error ? err.message : String(err)}`);
+  process.stdout.write("{}");
+  process.exit(0);
+});

package/dist/hooks/hooks-config.d.ts

@@ -0,0 +1,92 @@
+export declare const USER_HOOKS_JSON: string;
+export declare const HOOKS_BACKUP_SUFFIX = ".db90-backup";
+export declare const FORWARDER_FILENAME = "hook-forwarder.mjs";
+export declare const REQUIRED_HOOK_FIELDS: readonly ["conversation_id", "model", "workspace_roots"];
+export declare const P0_HOOK_EVENTS: readonly ["sessionEnd", "postToolUse"];
+export type RequiredHookField = (typeof REQUIRED_HOOK_FIELDS)[number];
+export interface HooksJsonEntry {
+    /**
+     * Cursor executes this as a single shell command string. Cursor's hooks.json
+     * schema does NOT support `args` or `env` — everything (interpreter, script
+     * path, flags) must live in `command`. We keep `args`/`env` here only so the
+     * parser tolerates legacy/foreign configs; the installer never emits them.
+     */
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export interface HooksJsonConfig {
+    version?: number;
+    hooks?: Record<string, Array<HooksJsonEntry>>;
+}
+export interface HookLogEvent {
+    captured_at?: string;
+    hook_event_name?: string;
+    conversation_id?: string;
+    generation_id?: string;
+    model?: string;
+    workspace_roots?: unknown;
+    tool_name?: string;
+    duration_ms?: unknown;
+    cursor_version?: string;
+    [key: string]: unknown;
+}
+export interface HookEventFieldCheck {
+    field: RequiredHookField;
+    present: boolean;
+    populated: boolean;
+    note?: string;
+}
+export interface HookEventAnalysis {
+    captured_at: string | null;
+    hook_event_name: string | null;
+    field_checks: HookEventFieldCheck[];
+    passes_required_fields: boolean;
+}
+export interface HookFeasibilityReport {
+    captured_at: string;
+    platform: NodeJS.Platform;
+    hooks_json_installed: boolean;
+    backup_exists: boolean;
+    queue_path_redacted: string;
+    queue_depth: number;
+    required_fields_verified: boolean;
+    sample_events: HookEventAnalysis[];
+    next_steps: string[];
+}
+export declare function redactHomePath(p: string): string;
+export declare function parseHooksJson(raw: string): HooksJsonConfig | null;
+export declare function hooksConfigUsesForwarder(config: HooksJsonConfig, forwarderPath: string): boolean;
+/**
+ * Build the single-string `command` Cursor runs for each hook. Cursor's schema
+ * has no `args`/`env`, so the interpreter, script path, and appDir flag are all
+ * encoded inline. The forwarder reads `--app-dir` to resolve the queue path,
+ * since it runs as a Cursor subprocess outside the MCP process.
+ */
+export declare function buildForwarderCommand(forwarderPath: string, appDir: string): string;
+/**
+ * Build the hooks.json config that routes P0 events to the forwarder.
+ */
+export declare function buildUserHooksConfig(forwarderPath: string, appDir: string): HooksJsonConfig;
+/**
+ * Install the db90 hook-forwarder:
+ *  1. Copy hook-forwarder.mjs from srcForwarderPath → {appDir}/hook-forwarder.mjs
+ *  2. Backup existing ~/.cursor/hooks.json if present
+ *  3. Write new hooks.json pointing at the installed forwarder
+ */
+export declare function installHooksConfig(srcForwarderPath: string, appDir: string): {
+    forwarderInstalled: string;
+    backupPath: string | null;
+};
+/**
+ * Restore the backed-up hooks.json (or remove the current one if no backup existed).
+ * Warns (does not throw) if a queue file with unprocessed events exists.
+ */
+export declare function uninstallHooksConfig(appDir: string, queuePath?: string): {
+    restored: boolean;
+    backupPath: string | null;
+    queueWarning: string | null;
+};
+export declare function readHooksQueue(queuePath: string): HookLogEvent[];
+export declare function analyzeHookEvent(event: HookLogEvent): HookEventAnalysis;
+export declare function verifyHooksConfig(appDir: string): HookFeasibilityReport;