@aixle/insights 0.2.0 → 0.2.1-staging

package/dist/install/cursor.js

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, copyFileSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { desiredAixleInsightsEntry, aixleInsightsEntryMatchesDesired } from "./claude.js";
+export function defaultCursorUserConfigPath() {
+    return join(homedir(), ".cursor", "mcp.json");
+}
+/**
+ * Legacy keys to clean up on install: "db90" (pre-rebrand) and "insights" (an
+ * earlier local-dev-only convention documented in scripts/reset-local-env.mjs,
+ * never the production installer's key — see DB90DV-560 orientation.md).
+ */
+const LEGACY_MCP_KEYS = ["db90", "insights"];
+const AIXLE_INSIGHTS_MCP_KEY = "aixle-insights";
+const BACKUP_SUFFIX = ".aixle-insights-backup";
+function readRootObject(path) {
+    if (!existsSync(path)) {
+        return {};
+    }
+    try {
+        const raw = readFileSync(path, "utf-8");
+        if (!raw.trim()) {
+            return {};
+        }
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return {
+                kind: "error",
+                message: `${path}: top-level JSON value must be an object.`,
+            };
+        }
+        return parsed;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { kind: "error", message: `Cannot read ${path}: ${msg}` };
+    }
+}
+function atomicWriteJson(path, data) {
+    try {
+        const dir = dirname(path);
+        mkdirSync(dir, { recursive: true });
+        const serialized = `${JSON.stringify(data, null, 2)}\n`;
+        const tmpPath = join(dir, `.aixle-insights-cursor-json-${randomBytes(8).toString("hex")}.tmp`);
+        writeFileSync(tmpPath, serialized, "utf-8");
+        renameSync(tmpPath, path);
+        return { kind: "installed" };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { kind: "error", message: `Failed to write ${path}: ${msg}` };
+    }
+}
+/** Copy the current file to a backup path, unless a backup already exists (never clobber the user's original). */
+function backupIfNeeded(path) {
+    if (!existsSync(path))
+        return;
+    const backupPath = path + BACKUP_SUFFIX;
+    if (existsSync(backupPath))
+        return;
+    copyFileSync(path, backupPath);
+}
+/**
+ * Merges top-level `mcpServers.aixle-insights` into ~/.cursor/mcp.json (or overridden path).
+ * Preserves all other keys and MCP server entries. Backs up the existing file
+ * (once) before the first write, and removes legacy "db90"/"insights" keys so
+ * Cursor does not spawn duplicate aixle-insights servers.
+ */
+export function installCursorUserMcp(options = {}) {
+    const path = options.cursorConfigPath ?? defaultCursorUserConfigPath();
+    const force = options.force === true;
+    const desired = desiredAixleInsightsEntry();
+    const rootRead = readRootObject(path);
+    if ("kind" in rootRead && typeof rootRead.kind === "string" && rootRead.kind === "error") {
+        return rootRead;
+    }
+    const root = {
+        ...rootRead,
+    };
+    const rawServers = root["mcpServers"];
+    let mcpServers;
+    if (rawServers === undefined) {
+        mcpServers = {};
+    }
+    else if (typeof rawServers === "object" &&
+        rawServers !== null &&
+        !Array.isArray(rawServers)) {
+        mcpServers = { ...rawServers };
+    }
+    else {
+        return {
+            kind: "error",
+            message: `Invalid Cursor MCP config at ${path}: "mcpServers" must be an object when present.`,
+        };
+    }
+    const existing = mcpServers[AIXLE_INSIGHTS_MCP_KEY];
+    const hasLegacyKey = LEGACY_MCP_KEYS.some((k) => mcpServers[k] !== undefined);
+    if (existing !== undefined && aixleInsightsEntryMatchesDesired(existing, desired)) {
+        if (!hasLegacyKey) {
+            return { kind: "already-configured" };
+        }
+        backupIfNeeded(path);
+        for (const key of LEGACY_MCP_KEYS)
+            delete mcpServers[key];
+        root["mcpServers"] = mcpServers;
+        return atomicWriteJson(path, root);
+    }
+    if (existing !== undefined && !force) {
+        return {
+            kind: "requires-force",
+            detail: 'A different "aixle-insights" MCP server entry already exists in ~/.cursor/mcp.json. Re-run with `init --force` to replace only that entry.',
+        };
+    }
+    backupIfNeeded(path);
+    for (const key of LEGACY_MCP_KEYS)
+        delete mcpServers[key];
+    mcpServers[AIXLE_INSIGHTS_MCP_KEY] = { command: desired.command, args: desired.args };
+    root["mcpServers"] = mcpServers;
+    return atomicWriteJson(path, root);
+}
+/**
+ * Removes the aixle-insights entry from ~/.cursor/mcp.json without disturbing any
+ * other server entry — including ones the user or Cursor added after install.
+ * Works on the CURRENT file (never a full-file revert to the backup). If a
+ * pre-install backup exists, the user's ORIGINAL aixle-insights entry (if any)
+ * is restored from it; otherwise our key is simply removed. The backup file is
+ * cleaned up either way.
+ */
+export function uninstallCursorUserMcp(options = {}) {
+    const path = options.cursorConfigPath ?? defaultCursorUserConfigPath();
+    const backupPath = path + BACKUP_SUFFIX;
+    const hasBackup = existsSync(backupPath);
+    const cleanupBackup = () => {
+        if (hasBackup) {
+            try {
+                unlinkSync(backupPath);
+            }
+            catch {
+                /* non-fatal */
+            }
+        }
+    };
+    if (!existsSync(path)) {
+        cleanupBackup();
+        return { kind: "noop" };
+    }
+    const rootRead = readRootObject(path);
+    if ("kind" in rootRead && typeof rootRead.kind === "string" && rootRead.kind === "error") {
+        return rootRead;
+    }
+    const root = { ...rootRead };
+    const rawServers = root["mcpServers"];
+    if (typeof rawServers !== "object" || rawServers === null || Array.isArray(rawServers)) {
+        cleanupBackup();
+        return { kind: "noop" };
+    }
+    const mcpServers = { ...rawServers };
+    // If a backup exists, recover the user's ORIGINAL aixle-insights entry (if they
+    // had one we overwrote) rather than just deleting ours — but only that one key,
+    // leaving every current sibling entry intact.
+    let restoredPrior = false;
+    if (hasBackup) {
+        const backupRead = readRootObject(backupPath);
+        const backupIsObject = !("kind" in backupRead &&
+            typeof backupRead.kind === "string" &&
+            backupRead.kind === "error");
+        if (backupIsObject) {
+            const backupServers = backupRead["mcpServers"];
+            if (typeof backupServers === "object" && backupServers !== null && !Array.isArray(backupServers)) {
+                const priorEntry = backupServers[AIXLE_INSIGHTS_MCP_KEY];
+                if (priorEntry !== undefined) {
+                    mcpServers[AIXLE_INSIGHTS_MCP_KEY] = priorEntry;
+                    restoredPrior = true;
+                }
+            }
+        }
+    }
+    if (!restoredPrior) {
+        if (mcpServers[AIXLE_INSIGHTS_MCP_KEY] === undefined) {
+            cleanupBackup();
+            return { kind: "noop" };
+        }
+        delete mcpServers[AIXLE_INSIGHTS_MCP_KEY];
+    }
+    root["mcpServers"] = mcpServers;
+    const writeResult = atomicWriteJson(path, root);
+    if (writeResult.kind === "error") {
+        return writeResult;
+    }
+    cleanupBackup();
+    return restoredPrior ? { kind: "restored", backupPath } : { kind: "removed" };
+}

package/dist/install/index.d.ts

@@ -1,8 +1,10 @@
 import { type InstallClaudeUserMcpOptions, type InstallResult } from "./claude.js";
-export type SupportedEditor = "claude";
-export type { InstallClaudeUserMcpOptions, InstallResult };
+import { type InstallCursorUserMcpOptions, type UninstallResult } from "./cursor.js";
+export type SupportedEditor = "claude" | "cursor";
+export type { InstallClaudeUserMcpOptions, InstallCursorUserMcpOptions, InstallResult, UninstallResult, };
 /**
- * Editor dispatch for MCP install hooks. Only Claude Code is supported in this story.
+ * Editor dispatch for MCP install hooks.
  */
-export declare function installEditorMcp(editor: SupportedEditor, options?: InstallClaudeUserMcpOptions): InstallResult;
+export declare function installEditorMcp(editor: SupportedEditor, options?: InstallClaudeUserMcpOptions & InstallCursorUserMcpOptions): InstallResult;
 export { installClaudeUserMcp, defaultClaudeUserConfigPath, desiredAixleInsightsEntry, aixleInsightsEntryMatchesDesired, } from "./claude.js";
+export { installCursorUserMcp, uninstallCursorUserMcp, defaultCursorUserConfigPath, } from "./cursor.js";

package/dist/install/index.js

@@ -1,11 +1,16 @@
 import { installClaudeUserMcp, } from "./claude.js";
+import { installCursorUserMcp, } from "./cursor.js";
 /**
- * Editor dispatch for MCP install hooks. Only Claude Code is supported in this story.
+ * Editor dispatch for MCP install hooks.
  */
 export function installEditorMcp(editor, options = {}) {
     if (editor === "claude") {
         return installClaudeUserMcp(options);
     }
+    if (editor === "cursor") {
+        return installCursorUserMcp(options);
+    }
     return { kind: "error", message: `Unsupported editor for MCP install: ${String(editor)}` };
 }
 export { installClaudeUserMcp, defaultClaudeUserConfigPath, desiredAixleInsightsEntry, aixleInsightsEntryMatchesDesired, } from "./claude.js";
+export { installCursorUserMcp, uninstallCursorUserMcp, defaultCursorUserConfigPath, } from "./cursor.js";

package/dist/lib/client.d.ts

@@ -8,6 +8,13 @@ export interface IngestPayload {
     [key: string]: unknown;
 }
 export interface PostEventOptions {
+    /**
+     * Skip the HTTPS-or-loopback gate for this host. Only ever set this to
+     * `true` when the caller has independently confirmed the user explicitly
+     * consented via `init --insecure` for this exact credential (see
+     * `StoredCredentials.insecureHttpAllowed`). Defaults to `false`.
+     */
+    allowInsecureHttp?: boolean;
     /** Override default console.error on non-ok HTTP response. */
     onHttpError?: (status: number, statusText: string, body: string) => void;
     /** Override default console.error on network-level failure. */

package/dist/lib/client.js

@@ -1,3 +1,4 @@
+import { evaluateTransportSecurity } from "./transport-security.js";
 /**
  * POST a single event payload to the db90 ingest endpoint.
  *
@@ -10,6 +11,22 @@
  * Never throws — callers can rely on Promise.allSettled-style aggregation.
  */
 export async function postEvent(payload, host, token, options = {}) {
+    const transportSecurity = evaluateTransportSecurity(host, {
+        allowInsecureHttp: options.allowInsecureHttp === true,
+        label: "DB90 ingest host",
+    });
+    if (!transportSecurity.ok) {
+        // Deliberately does NOT call options.onNetworkError/onHttpError: the retry
+        // wrapper in src/client.ts treats those as transient and retries with
+        // backoff. A scheme rejection is permanent — retrying wastes ~21s per
+        // event for nothing. Bare console.error mirrors this file's existing
+        // unrecoverable-failure logging style.
+        console.error(`Blocked event send — ${transportSecurity.error}`);
+        return false;
+    }
+    if (transportSecurity.warning) {
+        console.error(`Warning: ${transportSecurity.warning}`);
+    }
     const url = `${host.replace(/\/$/, "")}/api/v1/ingest/events`;
     const headers = {
         "Content-Type": "application/json",

package/dist/lib/config.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { mcpLog } from "../log.js";
 /**
  * Load a connector's `config.json` from disk. Returns `{}` on missing or
  * malformed files — callers fall back to env vars / CLI flags / defaults.
@@ -32,8 +33,12 @@ export function loadBaseConfig(configDir, parsePricing) {
             return result;
         }
     }
-    catch {
-        // missing or invalid config — fall through
+    catch (err) {
+        const code = err?.code;
+        if (code !== "ENOENT") {
+            // Config file exists but failed to parse — distinguishes tampering from "never created".
+            mcpLog.warn("config_parse_failed", { path: configPath, error: err instanceof Error ? err.message : String(err) }, false);
+        }
     }
     return {};
 }

package/dist/lib/project-resolver.d.ts

@@ -6,8 +6,8 @@ export interface LookupResult {
     project_id: string;
     name: string;
 }
-export declare function resolveProjectId(flagValue: string | undefined, configValue: string | undefined, host: string, token: string, verbose: boolean): Promise<ProjectResolution>;
-export declare function resolveProjectIdForRepoPath(repoPath: string, host: string, token: string, verbose: boolean): Promise<ProjectResolution>;
+export declare function resolveProjectId(flagValue: string | undefined, configValue: string | undefined, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<ProjectResolution>;
+export declare function resolveProjectIdForRepoPath(repoPath: string, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<ProjectResolution>;
 export declare function getGitRemote(verbose: boolean): string | null;
 export declare function getGitRemoteForPath(repoPath: string, verbose: boolean): string | null;
 /**
@@ -24,7 +24,7 @@ export declare function canonicalizeGitRemote(remote: string, verbose: boolean):
  * git remote. Expand to remotes the API lookup understands (`Project.normalize_git_remote`).
  */
 export declare function repoNameToGitRemoteCandidates(repoName: string): string[];
-export declare function lookupProjectByRepoName(repoName: string, host: string, token: string, verbose: boolean): Promise<LookupResult | "not-found" | null>;
+export declare function lookupProjectByRepoName(repoName: string, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<LookupResult | "not-found" | null>;
 /** Payload shape shared by db90-cursor and telemetry-mcp commit mappers. */
 export interface CommitAttributionPayload {
     event_type?: string;
@@ -44,5 +44,6 @@ export declare function enrichCommitProjectAttribution(payloads: CommitAttributi
     host: string;
     token: string;
     verbose?: boolean;
+    allowInsecureHttp?: boolean;
 }): Promise<void>;
-export declare function lookupProjectByRemote(gitRemote: string, host: string, token: string, verbose: boolean): Promise<LookupResult | "not-found" | null>;
+export declare function lookupProjectByRemote(gitRemote: string, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<LookupResult | "not-found" | null>;

package/dist/lib/project-resolver.js

@@ -1,9 +1,10 @@
 import { execFileSync } from "node:child_process";
+import { evaluateTransportSecurity } from "./transport-security.js";
 /** Coerce empty string to undefined so "" is treated as "not set" */
 function coerce(val) {
     return val === "" ? undefined : val;
 }
-export async function resolveProjectId(flagValue, configValue, host, token, verbose) {
+export async function resolveProjectId(flagValue, configValue, host, token, verbose, allowInsecureHttp = false) {
     const flag = coerce(flagValue);
     const config = coerce(configValue);
     if (flag !== undefined)
@@ -13,18 +14,18 @@ export async function resolveProjectId(flagValue, configValue, host, token, verb
     const gitRemote = getGitRemote(verbose);
     if (gitRemote === null)
         return { projectId: null, source: "none" };
-    const result = await lookupProjectByRemote(gitRemote, host, token, verbose);
+    const result = await lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp);
     if (result === "not-found")
         return { projectId: null, source: "auto-detect-not-found" };
     if (result !== null)
         return { projectId: result.project_id, source: "auto-detect" };
     return { projectId: null, source: "none" };
 }
-export async function resolveProjectIdForRepoPath(repoPath, host, token, verbose) {
+export async function resolveProjectIdForRepoPath(repoPath, host, token, verbose, allowInsecureHttp = false) {
     const gitRemote = getGitRemoteForPath(repoPath, verbose);
     if (gitRemote === null)
         return { projectId: null, source: "none" };
-    const result = await lookupProjectByRemote(gitRemote, host, token, verbose);
+    const result = await lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp);
     if (result === "not-found")
         return { projectId: null, source: "auto-detect-not-found" };
     if (result !== null)
@@ -133,7 +134,7 @@ export function repoNameToGitRemoteCandidates(repoName) {
     }
     return [];
 }
-export async function lookupProjectByRepoName(repoName, host, token, verbose) {
+export async function lookupProjectByRepoName(repoName, host, token, verbose, allowInsecureHttp = false) {
     const candidates = repoNameToGitRemoteCandidates(repoName);
     if (candidates.length === 0) {
         if (verbose)
@@ -141,7 +142,7 @@ export async function lookupProjectByRepoName(repoName, host, token, verbose) {
         return "not-found";
     }
     for (const candidate of candidates) {
-        const result = await lookupProjectByRemote(candidate, host, token, verbose);
+        const result = await lookupProjectByRemote(candidate, host, token, verbose, allowInsecureHttp);
         if (result === "not-found")
             continue;
         return result;
@@ -164,7 +165,7 @@ export async function enrichCommitProjectAttribution(payloads, options) {
         const repoName = payload.metadata?.repo_name;
         if (!repoName)
             continue;
-        const result = await lookupProjectByRepoName(repoName, options.host, options.token, options.verbose ?? false);
+        const result = await lookupProjectByRepoName(repoName, options.host, options.token, options.verbose ?? false, options.allowInsecureHttp === true);
         if (result && typeof result === "object" && "project_id" in result) {
             payload.project_id = result.project_id;
             if (options.verbose) {
@@ -173,7 +174,18 @@ export async function enrichCommitProjectAttribution(payloads, options) {
         }
     }
 }
-export async function lookupProjectByRemote(gitRemote, host, token, verbose) {
+export async function lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp = false) {
+    const transportSecurity = evaluateTransportSecurity(host, {
+        allowInsecureHttp,
+        label: "DB90 project-lookup host",
+    });
+    if (!transportSecurity.ok) {
+        console.error(`Blocked project lookup — ${transportSecurity.error}`);
+        return null;
+    }
+    if (transportSecurity.warning) {
+        console.error(`Warning: ${transportSecurity.warning}`);
+    }
     const url = `${host.replace(/\/$/, "")}/api/v1/projects/lookup?git_remote=${encodeURIComponent(gitRemote)}`;
     try {
         const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });

package/dist/lib/transport-security.d.ts

@@ -9,4 +9,5 @@ export interface TransportSecurityOptions {
     allowInsecureHttp: boolean;
     label: string;
 }
+export declare function isLoopbackHost(hostname: string): boolean;
 export declare function evaluateTransportSecurity(rawUrl: string, options: TransportSecurityOptions): TransportSecurityResult;

package/dist/lib/transport-security.js

@@ -8,7 +8,7 @@ function isIpv4Loopback(hostname) {
         octet <= 255 &&
         String(octet) === parts[index]) && octets[0] === 127;
 }
-function isLoopbackHost(hostname) {
+export function isLoopbackHost(hostname) {
     const normalized = hostname.toLowerCase();
     return normalized === "localhost" ||
         normalized === "::1" ||

package/dist/readers/claude.d.ts

@@ -1,6 +1,21 @@
 import type { IngestPayload } from "../lib/index.js";
 import { type PricingTable } from "../pricing.js";
 import { type RiskLevel } from "../risk-scanner.js";
+export type ClaudeDerivativeEventType = "edit" | "commit" | "test" | "tool_use";
+export interface ClaudeToolUseBlock {
+    id?: string;
+    name: string;
+    input?: Record<string, unknown>;
+}
+export interface ClaudeCollectedToolUse {
+    id: string;
+    name: string;
+    eventType: ClaudeDerivativeEventType;
+    summary: string;
+}
+export declare function classifyToolUse(block: ClaudeToolUseBlock): ClaudeDerivativeEventType | null;
+export declare function scrubBashCommand(cmd: string): string;
+export declare function summarizeToolUse(block: ClaudeToolUseBlock): string;
 /** True when prompt text alone matches known local-command injection markers. */
 export declare function isClaudeLocalCommandNoisePrompt(promptText: string): boolean;
 /**
@@ -41,9 +56,13 @@ export interface ClaudeTranscriptTurn {
     riskLevel: RiskLevel;
     riskScore: number;
     riskCategories: string[];
+    toolUses: ClaudeCollectedToolUse[];
+    navToolCalls: number;
+    totalToolCalls: number;
+    messageIds: string[];
 }
-/** Payload shape expected by the db90 ingest API. */
-export interface Db90Payload extends IngestPayload {
+/** Payload shape for the parent chat turn (carries full token cost). */
+export interface ClaudePayload extends IngestPayload {
     tool_name: "claude_code";
     event_type: "chat";
     model?: string;
@@ -57,7 +76,7 @@ export interface Db90Payload extends IngestPayload {
         session_id: string;
         claude_session_id: string;
         transcript_source: "claude_jsonl";
-        model: string | null;
+        model?: string | null;
         base_input_tokens: number;
         output_tokens: number;
         cache_write_tokens: number;
@@ -68,10 +87,39 @@ export interface Db90Payload extends IngestPayload {
         prompt_text?: string;
         assistant_text?: string;
         scannable: true;
+        cost_model: "token_count";
+        nav_tool_calls: number;
+        total_tool_calls: number;
+        message_ids?: string[];
+    };
+}
+/** Payload shape for derivative tool-use children (cost_usd: 0, no tokens). */
+export interface ClaudeDerivativePayload extends IngestPayload {
+    tool_name: "claude_code";
+    event_type: ClaudeDerivativeEventType;
+    cost_usd: 0;
+    occurred_at: string;
+    model?: string;
+    project_id?: string;
+    metadata: {
+        session_id: string;
+        claude_session_id: string;
+        transcript_source: "claude_jsonl";
+        cost_model: "derivative";
+        parent_session_id: string;
+        tool_name_inner: string;
+        tool_use_id: string;
+        summary: string;
+        scannable: false;
+        risk_level: "none";
+        risk_categories: string[];
+        risk_score: 0;
     };
 }
+/** Union of all Claude transcript payloads expected by the ingest API. */
+export type ClaudeMappedPayload = ClaudePayload | ClaudeDerivativePayload;
 /** Options for mapTranscriptTurn. */
-export interface ToDb90PayloadOptions {
+export interface ToClaudePayloadOptions {
     projectId?: string | null;
     pricing?: PricingTable;
 }
@@ -79,5 +127,5 @@ export interface ToDb90PayloadOptions {
 export declare function findTranscriptFiles(baseDirs?: string[]): string[];
 /** Streams a JSONL file and splits Claude transcripts into individual turns. */
 export declare function parseTranscriptFile(filePath: string, verbose?: boolean): Promise<ClaudeTranscriptTurn[]>;
-/** Converts a Claude transcript turn to a db90 ingest payload. */
-export declare function mapTranscriptTurn(turn: ClaudeTranscriptTurn, options?: ToDb90PayloadOptions): Db90Payload;
+/** Converts a Claude transcript turn to parent chat and derivative tool-use payloads. */
+export declare function mapTranscriptTurn(turn: ClaudeTranscriptTurn, options?: ToClaudePayloadOptions): ClaudeMappedPayload[];