@aixle/insights 0.1.0

package/dist/auth/keycloak.js

@@ -0,0 +1,170 @@
+/**
+ * RFC 8628 OAuth 2.0 Device Authorization Grant against Keycloak OIDC endpoints.
+ */
+import { createHash, randomBytes } from "node:crypto";
+function normalizeIssuer(issuer) {
+    return issuer.replace(/\/$/, "");
+}
+function formEncode(body) {
+    return new URLSearchParams(body).toString();
+}
+function base64Url(input) {
+    return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function generatePkceVerifier() {
+    return base64Url(randomBytes(32));
+}
+function pkceChallenge(verifier) {
+    return base64Url(createHash("sha256").update(verifier).digest());
+}
+export async function startDeviceAuthorization(params) {
+    const fetchFn = params.fetchImpl ?? fetch;
+    const issuer = normalizeIssuer(params.issuer);
+    const url = `${issuer}/protocol/openid-connect/auth/device`;
+    const scope = params.scope ?? "openid profile email";
+    const codeVerifier = generatePkceVerifier();
+    const res = await fetchFn(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: formEncode({
+            client_id: params.clientId,
+            scope,
+            code_challenge: pkceChallenge(codeVerifier),
+            code_challenge_method: "S256",
+        }),
+    });
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Keycloak device auth: expected JSON, got HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    if (!res.ok) {
+        const err = json;
+        const desc = typeof err["error_description"] === "string" ? err["error_description"] : text;
+        throw new Error(`Keycloak device auth failed (${res.status}): ${desc}`);
+    }
+    const o = json;
+    const device_code = o["device_code"];
+    const user_code = o["user_code"];
+    const verification_uri = o["verification_uri"];
+    const expires_in = o["expires_in"];
+    if (typeof device_code !== "string" ||
+        typeof user_code !== "string" ||
+        typeof verification_uri !== "string" ||
+        typeof expires_in !== "number") {
+        throw new Error("Keycloak device auth: malformed response (missing device_code, user_code, verification_uri, or expires_in)");
+    }
+    const interval = typeof o["interval"] === "number" ? o["interval"] : 5;
+    return {
+        device_code,
+        user_code,
+        verification_uri,
+        verification_uri_complete: typeof o["verification_uri_complete"] === "string" ? o["verification_uri_complete"] : undefined,
+        expires_in,
+        interval,
+        code_verifier: codeVerifier,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function pollDeviceAccessToken(params) {
+    const fetchFn = params.fetchImpl ?? fetch;
+    const issuer = normalizeIssuer(params.issuer);
+    const tokenUrl = `${issuer}/protocol/openid-connect/token`;
+    const { deviceAuthorization: d } = params;
+    let intervalSec = Math.max(1, d.interval ?? 5);
+    const deadline = Date.now() + d.expires_in * 1000;
+    let lastTransientError = null;
+    params.onInstructions?.(d.verification_uri, d.user_code);
+    // RFC 8628: wait at least `interval` before the first token request.
+    await sleep(intervalSec * 1000);
+    while (Date.now() < deadline) {
+        let res;
+        try {
+            res = await fetchFn(tokenUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: formEncode({
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                    device_code: d.device_code,
+                    client_id: params.clientId,
+                    ...(d.code_verifier ? { code_verifier: d.code_verifier } : {}),
+                }),
+            });
+        }
+        catch (e) {
+            lastTransientError = e instanceof Error ? e.message : String(e);
+            await sleep(intervalSec * 1000);
+            continue;
+        }
+        const text = await res.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            lastTransientError = `invalid JSON from token endpoint (HTTP ${res.status}): ${text.slice(0, 200)}`;
+            await sleep(intervalSec * 1000);
+            continue;
+        }
+        const o = json;
+        const err = o["error"];
+        if (res.ok && typeof o["access_token"] === "string") {
+            return o["access_token"];
+        }
+        if (err === "authorization_pending") {
+            await sleep(intervalSec * 1000);
+            continue;
+        }
+        if (err === "slow_down") {
+            intervalSec += 5;
+            await sleep(intervalSec * 1000);
+            continue;
+        }
+        if (err === "access_denied") {
+            throw new Error("Keycloak device flow: access_denied");
+        }
+        if (err === "expired_token") {
+            throw new Error("Keycloak device flow: expired_token");
+        }
+        const desc = typeof o["error_description"] === "string" ? o["error_description"] : text;
+        throw new Error(`Keycloak token endpoint error: ${String(err)} — ${desc}`);
+    }
+    if (lastTransientError) {
+        throw new Error(`Keycloak device flow: timed out waiting for authorization; last polling error: ${lastTransientError}`);
+    }
+    throw new Error("Keycloak device flow: timed out waiting for authorization");
+}
+export async function obtainKeycloakAccessTokenViaDeviceFlow(params) {
+    const start = await startDeviceAuthorization({
+        issuer: params.issuer,
+        clientId: params.clientId,
+        scope: params.scope,
+        fetchImpl: params.fetchImpl,
+    });
+    return pollDeviceAccessToken({
+        issuer: params.issuer,
+        clientId: params.clientId,
+        deviceAuthorization: start,
+        onInstructions: params.onInstructions,
+        fetchImpl: params.fetchImpl,
+    });
+}
+export function defaultKeycloakIssuer() {
+    const fromEnv = process.env["DB90_KEYCLOAK_ISSUER"]?.trim() ||
+        process.env["KEYCLOAK_ISSUER"]?.trim();
+    if (fromEnv)
+        return fromEnv.replace(/\/$/, "");
+    const useLocalDefault = ["1", "true", "yes"].includes(process.env["DB90_MCP_USE_LOCAL_KEYCLOAK_DEFAULT"]?.toLowerCase() ?? "");
+    if (useLocalDefault || process.env["NODE_ENV"] === "development") {
+        return "http://localhost:8080/realms/db90";
+    }
+    return "";
+}
+export function defaultKeycloakClientId() {
+    return process.env["DB90_KEYCLOAK_CLIENT_ID"]?.trim() || "db90-web";
+}

package/dist/cli.d.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { resolveProjectId } from "./lib/index.js";
+import { loadCredentials } from "./credentials.js";
+import { loginAndPersistCredentials } from "./auth/flow.js";
+import { defaultKeycloakIssuer } from "./auth/keycloak.js";
+import { migrateLegacyState, getAppDir } from "./state.js";
+import { syncTelemetryTools } from "./sync.js";
+import { mergePricing } from "./pricing.js";
+import { type InstallClaudeUserMcpOptions, type InstallResult } from "./install/claude.js";
+export interface Args {
+    command: "init" | "health" | "run" | "help" | "uninstall-hooks" | "verify-hooks";
+    help: boolean;
+    once: boolean;
+    /** With `run --once`: ignore Cursor watermarks and commit hash dedupe. */
+    full?: boolean;
+    host?: string;
+    keycloakUrl?: string;
+    toolName?: string;
+    /** When set on init, sent as `X-Organization-ID` on MCP exchange (overrides DB90_ORGANIZATION_ID). */
+    organizationId?: string;
+    force?: boolean;
+    /** When set on init, install the Cursor hooks forwarder into ~/.cursor/hooks.json. */
+    hooks?: boolean;
+}
+interface RunOnceDeps {
+    loadCredentials: typeof loadCredentials;
+    migrateLegacyState: typeof migrateLegacyState;
+    getAppDir: typeof getAppDir;
+    syncTelemetryTools: typeof syncTelemetryTools;
+    resolveProjectId: typeof resolveProjectId;
+    pricing: ReturnType<typeof mergePricing>;
+    log: (message: string) => void;
+    error: (message: string) => void;
+}
+interface InitDeps {
+    loginAndPersistCredentials: typeof loginAndPersistCredentials;
+    defaultKeycloakIssuer: typeof defaultKeycloakIssuer;
+    getAppDir: typeof getAppDir;
+    installClaudeUserMcp: (options: InstallClaudeUserMcpOptions) => InstallResult;
+    log: (message: string) => void;
+    error: (message: string) => void;
+}
+/** Matches DB90 Rails `McpController` UUID check for `X-Organization-ID` (RFC 4122 variant). */
+export declare const DB90_ORGANIZATION_UUID_PATTERN: RegExp;
+export declare function isValidDb90OrganizationUuid(value: string): boolean;
+export declare function parseArgs(argv: string[]): Args;
+export declare function runInit(cliArgs: Args, deps?: Partial<InitDeps>): Promise<number>;
+export declare function runOnce(deps?: Partial<RunOnceDeps>, options?: {
+    fullScan?: boolean;
+}): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { resolveProjectId } from "./lib/index.js";
+import { loadCredentials, credentialsHaveAnyToken, pickProjectLookupToken } from "./credentials.js";
+import { loginAndPersistCredentials } from "./auth/flow.js";
+import { defaultKeycloakIssuer } from "./auth/keycloak.js";
+import { migrateLegacyState, getAppDir } from "./state.js";
+import { syncTelemetryTools } from "./sync.js";
+import { DEFAULT_PRICING, mergePricing } from "./pricing.js";
+import { resolveCursorPricing } from "./cursor-config.js";
+import { buildHealthSnapshot, formatHealthForCli } from "./health.js";
+import { installClaudeUserMcp } from "./install/claude.js";
+import { installHooksConfig, uninstallHooksConfig, verifyHooksConfig, FORWARDER_FILENAME } from "./hooks/hooks-config.js";
+import { join } from "node:path";
+import { fileURLToPath as nodeFileURLToPath } from "node:url";
+import { mcpLog } from "./log.js";
+const GLOBAL_FLAGS = new Set(["--help", "-h", "--once", "--full"]);
+const INIT_VALUE_FLAGS = new Set(["--host", "--keycloak-url", "--tool-name", "--organization-id"]);
+const INIT_BOOLEAN_FLAGS = new Set(["--force", "--hooks"]);
+/** Matches DB90 Rails `McpController` UUID check for `X-Organization-ID` (RFC 4122 variant). */
+export const DB90_ORGANIZATION_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function isValidDb90OrganizationUuid(value) {
+    return DB90_ORGANIZATION_UUID_PATTERN.test(value.trim());
+}
+function takeFlagValue(argv, name) {
+    const eqForm = argv.find((a) => a.startsWith(`${name}=`));
+    if (eqForm) {
+        return eqForm.slice(name.length + 1);
+    }
+    const idx = argv.indexOf(name);
+    if (idx === -1)
+        return undefined;
+    const next = argv[idx + 1];
+    if (!next || next.startsWith("-"))
+        return undefined;
+    return next;
+}
+function unknownFlags(argv, valueFlags, booleanFlags) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith("--") && a !== "-h")
+            continue;
+        if (GLOBAL_FLAGS.has(a))
+            continue;
+        if (booleanFlags.has(a)) {
+            continue;
+        }
+        if (valueFlags.has(a)) {
+            const next = argv[i + 1];
+            if (!a.includes("=") && next && !next.startsWith("-")) {
+                i += 1;
+            }
+            continue;
+        }
+        if (a.startsWith("--") && a.includes("=")) {
+            const key = a.slice(0, a.indexOf("="));
+            if (booleanFlags.has(key)) {
+                out.push(a);
+                continue;
+            }
+            if (valueFlags.has(key))
+                continue;
+        }
+        if (a === "-h")
+            continue;
+        out.push(a);
+    }
+    return out;
+}
+function initExtraPositionals(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "init")
+            continue;
+        if (a === "-h" || GLOBAL_FLAGS.has(a) || INIT_BOOLEAN_FLAGS.has(a))
+            continue;
+        if (INIT_VALUE_FLAGS.has(a)) {
+            const next = argv[i + 1];
+            if (next && !next.startsWith("-")) {
+                i += 1;
+            }
+            continue;
+        }
+        if (a.startsWith("--")) {
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}
+export function parseArgs(argv) {
+    const args = argv.slice(2);
+    const help = args.includes("--help") || args.includes("-h");
+    const once = args.includes("--once");
+    const full = args.includes("--full");
+    const positional = args.filter((a) => !a.startsWith("-") && a !== "-h");
+    const raw = positional[0];
+    if (raw === "init") {
+        const bad = unknownFlags(args.filter((a) => a !== "init"), INIT_VALUE_FLAGS, INIT_BOOLEAN_FLAGS);
+        if (bad.length > 0) {
+            return { command: "help", help: true, once: false };
+        }
+        if (initExtraPositionals(args).length > 0) {
+            return { command: "help", help: true, once: false };
+        }
+        const host = takeFlagValue(args, "--host");
+        const keycloakUrl = takeFlagValue(args, "--keycloak-url");
+        const toolName = takeFlagValue(args, "--tool-name");
+        const organizationId = takeFlagValue(args, "--organization-id");
+        const force = args.includes("--force");
+        const hooks = args.includes("--hooks");
+        return { command: "init", help, once: false, host, keycloakUrl, toolName, organizationId, force, hooks };
+    }
+    const nonInitBad = args.filter((a) => {
+        if (!a.startsWith("--") && a !== "-h")
+            return false;
+        if (GLOBAL_FLAGS.has(a))
+            return false;
+        return true;
+    });
+    if (nonInitBad.length > 0) {
+        return { command: "help", help: true, once: false };
+    }
+    if (!raw || raw.startsWith("-")) {
+        if (raw === "--help" || raw === "-h" || (!raw && help)) {
+            return { command: "help", help: true, once: false };
+        }
+        if (!raw && once) {
+            return { command: "run", help, once: true, full: full || undefined };
+        }
+        if (!raw) {
+            return { command: "run", help, once: false, full: full || undefined };
+        }
+        return { command: "help", help: true, once: false };
+    }
+    if ((raw === "init" || raw === "health") && (once || full)) {
+        return { command: "help", help: true, once: false };
+    }
+    if (raw === "init" || raw === "health" || raw === "run") {
+        return { command: raw, help, once, full: full || undefined };
+    }
+    if (raw === "serve") {
+        return { command: "run", help, once, full: full || undefined };
+    }
+    if (raw === "uninstall-hooks" || raw === "verify-hooks") {
+        return { command: raw, help: false, once: false };
+    }
+    return { command: "help", help: true, once: false };
+}
+function printHelp() {
+    console.log(`
+aixle-insights — AI coding-assistant telemetry (Claude transcripts + Cursor SQLite ingest)
+
+Usage:
+  aixle-insights [command] [options]
+
+Commands:
+  run              Start the MCP stdio server (default — used by Claude Code).
+  init             Keycloak device login once, then persist DB90 ingest credentials (keychain or file).
+  health           Multi-line diagnostic (credentials, sync, log path, state files).
+  uninstall-hooks  Remove DB90 from ~/.cursor/hooks.json and restore backup (if any).
+  verify-hooks     Print hooks install status and queue depth as JSON.
+
+Options:
+  --once      With 'run': perform a multi-tool sync then exit (no MCP server).
+  --full      With 'run --once': ignore Cursor watermarks and commit hash dedupe (backfill).
+  --help, -h  Show this help message.
+
+init options:
+  --host <url>             DB90 API base URL (default: env DB90_API_URL or http://localhost:3000)
+  --keycloak-url <issuer>  Keycloak realm issuer (default: env KEYCLOAK_ISSUER / DB90_KEYCLOAK_ISSUER)
+  --tool-name <name>       Optional: mint only \`claude_code\`, only \`cursor\`, or omit to mint BOTH.
+  --organization-id <uuid> Optional: scope MCP token exchange to this org (overrides env DB90_ORGANIZATION_ID).
+  --force                  Replace an existing user "aixle-insights" MCP entry in ~/.claude.json if it differs.
+  --hooks                  (opt-in) Install Cursor hook forwarder for per-turn model attribution.
+                           Requires Cursor restart. Run 'aixle-insights uninstall-hooks' to remove.
+
+Multi-org:
+  Set \`DB90_ORGANIZATION_ID\` to a UUID, or pass \`--organization-id\` on \`init\`, so ingest tokens are minted for that membership instead of the default (oldest) org.
+
+Credentials:
+  Stored in the OS keychain via keytar when available; otherwise
+  ~/.aixle-insights/credentials.json (mode 0600 on POSIX).
+
+Note: Omitting --tool-name provisions separate ingest tokens for Claude Code + Cursor behind a single Keycloak login.
+`);
+}
+function defaultDb90Host() {
+    const v = process.env["DB90_API_URL"]?.trim();
+    if (v)
+        return v.replace(/\/$/, "");
+    return "http://localhost:3000";
+}
+async function runHealth() {
+    const snap = await buildHealthSnapshot();
+    console.log(formatHealthForCli(snap));
+}
+async function runMcpServer() {
+    const { startServer } = await import("./server.js");
+    await startServer();
+}
+export async function runInit(cliArgs, deps) {
+    const runtime = {
+        loginAndPersistCredentials,
+        defaultKeycloakIssuer,
+        getAppDir,
+        installClaudeUserMcp,
+        log: console.log,
+        error: console.error,
+        ...deps,
+    };
+    const db90Host = (cliArgs.host ?? defaultDb90Host()).replace(/\/$/, "");
+    const kcIssuer = (cliArgs.keycloakUrl ?? runtime.defaultKeycloakIssuer()).trim();
+    if (!kcIssuer) {
+        runtime.error("Error: Keycloak issuer is not configured. Pass --keycloak-url or set KEYCLOAK_ISSUER / DB90_KEYCLOAK_ISSUER.");
+        return 1;
+    }
+    if (cliArgs.toolName !== undefined && !["claude_code", "cursor"].includes(cliArgs.toolName)) {
+        runtime.error("Error: --tool-name must be one of: claude_code, cursor.");
+        return 1;
+    }
+    const provisionTools = cliArgs.toolName === "cursor"
+        ? ["cursor"]
+        : cliArgs.toolName === "claude_code"
+            ? ["claude_code"]
+            : ["claude_code", "cursor"];
+    const fromFlag = cliArgs.organizationId?.trim();
+    const fromEnv = process.env["DB90_ORGANIZATION_ID"]?.trim();
+    const exchangeOrganizationId = fromFlag || fromEnv;
+    if (exchangeOrganizationId && !isValidDb90OrganizationUuid(exchangeOrganizationId)) {
+        runtime.error("Error: --organization-id / DB90_ORGANIZATION_ID must be a valid UUID (RFC 4122, version 1–5, variant per DB90 API).");
+        return 1;
+    }
+    const result = await runtime.loginAndPersistCredentials({
+        db90Host,
+        keycloakIssuer: kcIssuer,
+        tools: provisionTools.length > 1 ? provisionTools : undefined,
+        toolName: provisionTools.length === 1
+            ? provisionTools[0] === "cursor"
+                ? "cursor"
+                : "claude_code"
+            : undefined,
+        deviceLabel: "aixle-insights CLI init",
+        appDir: runtime.getAppDir(),
+        exchangeOrganizationId: exchangeOrganizationId || undefined,
+        onVisitInstructions: (uri, code) => {
+            runtime.log(`Visit ${uri} and enter code ${code}`);
+        },
+    });
+    if (!result.ok) {
+        runtime.error(`Auth failed: ${result.error}`);
+        return 1;
+    }
+    runtime.log(`Credentials saved (organization ${result.organizationId}).`);
+    if (cliArgs.hooks) {
+        const appDir = runtime.getAppDir();
+        const thisFile = nodeFileURLToPath(import.meta.url);
+        // From dist/cli.js: one `..` → dist/, two `..` → package root.
+        // (Pre-existing off-by-one bug — used three `..`s, which lands on the
+        // npm scope dir `@aixle/` instead of `@aixle/insights/`. Surfaced by
+        // the rename-parity verification when the published-tarball install
+        // path exercised this code for the first time via npx.)
+        const pkgRoot = join(thisFile, "..", "..");
+        const srcForwarder = join(pkgRoot, "dist", "hooks", FORWARDER_FILENAME);
+        try {
+            const { forwarderInstalled, backupPath } = installHooksConfig(srcForwarder, appDir);
+            runtime.log(`Cursor hooks installed (forwarder: ${forwarderInstalled}).`);
+            if (backupPath) {
+                runtime.log(`Existing hooks.json backed up to: ${backupPath}`);
+            }
+            runtime.log("Restart Cursor to activate hook-based model attribution.");
+        }
+        catch (err) {
+            runtime.error(`Warning: --hooks install failed: ${err instanceof Error ? err.message : String(err)}`);
+            runtime.error(`Run 'aixle-insights init --hooks' again after verifying ${srcForwarder} exists.`);
+        }
+    }
+    const shouldInstall = provisionTools.includes("claude_code");
+    if (shouldInstall) {
+        const installResult = runtime.installClaudeUserMcp({ force: cliArgs.force === true });
+        switch (installResult.kind) {
+            case "already-configured":
+                runtime.log("Claude Code MCP: aixle-insights server is already configured for your user.");
+                break;
+            case "installed":
+                runtime.log("Claude Code MCP: added aixle-insights server to your user config (~/.claude.json).");
+                break;
+            case "requires-force":
+                runtime.error(installResult.detail);
+                return 1;
+            case "error":
+                runtime.error(`Claude Code MCP install failed: ${installResult.message}`);
+                return 1;
+        }
+        runtime.log("Restart Claude Code to activate.");
+    }
+    else {
+        runtime.log("Skipped Claude Code MCP auto-install (--tool-name cursor only).");
+    }
+    return 0;
+}
+export async function runOnce(deps, options) {
+    const runtime = {
+        loadCredentials,
+        migrateLegacyState,
+        getAppDir,
+        syncTelemetryTools,
+        resolveProjectId,
+        pricing: mergePricing(DEFAULT_PRICING, {}),
+        log: console.log,
+        error: console.error,
+        ...deps,
+    };
+    const creds = await runtime.loadCredentials();
+    if (!creds || !credentialsHaveAnyToken(creds)) {
+        mcpLog.warn("credential_validation_failed", { source: "cli_once", reason: "missing_credentials" }, false);
+        runtime.error("Error: no Aixle Insights credentials. Run `aixle-insights init` first (dual-tool auth is the default).");
+        return 1;
+    }
+    const appDirRuntime = runtime.getAppDir();
+    for (const tok of Object.values(creds.accounts)) {
+        if (typeof tok === "string" && tok.length > 0) {
+            runtime.migrateLegacyState(appDirRuntime, creds.host, tok);
+        }
+    }
+    const lookupToken = pickProjectLookupToken(creds);
+    let projectId = null;
+    let projectIdSource = "none";
+    if (lookupToken) {
+        const resolution = await runtime.resolveProjectId(undefined, undefined, creds.host, lookupToken, false);
+        projectId = resolution.projectId;
+        projectIdSource = resolution.source;
+        mcpLog.info("project_attribution_resolved", { project_id: resolution.projectId, source: resolution.source }, false);
+    }
+    const result = await runtime.syncTelemetryTools({
+        credentials: creds,
+        dryRun: false,
+        verbose: false,
+        projectId,
+        projectIdSource,
+        projectLookupToken: lookupToken,
+        pricing: runtime.pricing,
+        cursorPricing: resolveCursorPricing(undefined, appDirRuntime),
+        appDir: appDirRuntime,
+        scopeDir: process.cwd(),
+        fullScan: options?.fullScan === true,
+    });
+    if (result.locked || result.failed > 0) {
+        runtime.error(`Sync finished with failures: sent=${result.sent} failed=${result.failed} skipped=${result.skipped}`);
+        return 1;
+    }
+    runtime.log(`Sync complete: sent=${result.sent} failed=${result.failed} skipped=${result.skipped}`);
+    return 0;
+}
+async function runOnceAndExit(fullScan) {
+    const exitCode = await runOnce(undefined, { fullScan });
+    if (exitCode !== 0)
+        process.exit(exitCode);
+}
+async function main() {
+    const args = parseArgs(process.argv);
+    if (args.help || args.command === "help") {
+        printHelp();
+        return;
+    }
+    switch (args.command) {
+        case "health": {
+            await runHealth();
+            return;
+        }
+        case "init": {
+            const code = await runInit(args);
+            if (code !== 0)
+                process.exit(code);
+            return;
+        }
+        case "uninstall-hooks": {
+            const appDir = getAppDir();
+            const { restored, backupPath, queueWarning } = uninstallHooksConfig(appDir);
+            if (queueWarning)
+                console.warn(`Warning: ${queueWarning}`);
+            if (restored) {
+                console.log(backupPath ? `Hooks uninstalled; hooks.json restored from ${backupPath}.` : "Hooks uninstalled; hooks.json removed.");
+            }
+            else {
+                console.log("No DB90 hooks entry found in ~/.cursor/hooks.json — nothing to uninstall.");
+            }
+            return;
+        }
+        case "verify-hooks": {
+            const report = verifyHooksConfig(getAppDir());
+            console.log(JSON.stringify(report, null, 2));
+            if (report.next_steps.length > 0) {
+                for (const step of report.next_steps)
+                    console.log(`Next: ${step}`);
+            }
+            return;
+        }
+        case "run":
+            if (args.once) {
+                await runOnceAndExit(args.full);
+                return;
+            }
+            await runMcpServer();
+            return;
+    }
+}
+function isEntryPoint() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryPoint()) {
+    main().catch((err) => {
+        console.error("Unexpected error:", err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import { type IngestPayload, type PostEventOptions } from "./lib/index.js";
+export interface PostResult {
+    sent: number;
+    failed: number;
+}
+export interface PostEventsResult extends PostResult {
+    /** ISO timestamp of the latest successfully-sent event's occurred_at, or null if none sent. */
+    lastSentAt: string | null;
+}
+export interface PostEventExtras {
+    /** Injected wait for tests (default: real setTimeout). */
+    waitMs?: (ms: number) => Promise<void>;
+    /** When false, skip operational logging of transient retries. */
+    logTransientRetries?: boolean;
+}
+export type PostEventOptionsWithRetry = PostEventOptions & PostEventExtras;
+/** @internal */
+export declare function setIngestRetryWaitOverrideForTests(fn: ((ms: number) => Promise<void>) | undefined): void;
+/**
+ * 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 declare function postEvent(payload: IngestPayload, host: string, token: string, options?: PostEventOptionsWithRetry): Promise<boolean>;
+/**
+ * Batch POST with sent/failed aggregation plus max `occurred_at` watermarking
+ * (used by Cursor multi-event sync loops).
+ */
+export declare function postEvents(events: IngestPayload[], host: string, token: string, options?: PostEventOptionsWithRetry): Promise<PostEventsResult>;