@aixle/insights 0.2.7-staging → 0.2.8-staging

package/README.md

@@ -13,7 +13,7 @@ Two channels are published. Pick one deliberately — they are **not** interchan
 | | Production | Staging (QA) |
 |---|---|---|
 | Install | `npm i -g @aixle/insights` | `npm i -g @aixle/insights@staging` |
-| Version looks like | `0.2.0` | `0.2.1-staging` |
+| Version looks like | `0.2.1` | `0.2.6-staging` |
 | Points at | the production API | the staging API |
 | Who should use it | **everyone** | QA validating unreleased work |
 | Stability | released, supported | may change or break without notice |
@@ -28,7 +28,7 @@ npx -y @aixle/insights init \
 
 # Or global install:
 npm i -g @aixle/insights
-aixle-insights --version    # e.g. 0.2.0  (no suffix)
+npm ls -g @aixle/insights   # e.g. @aixle/insights@0.2.1  (no suffix)
 ```
 
 ### Staging — QA only
@@ -44,7 +44,7 @@ npx -y @aixle/insights@staging init \
 
 # Or global install:
 npm i -g @aixle/insights@staging
-aixle-insights --version    # e.g. 0.2.1-staging  (note the suffix)
+npm ls -g @aixle/insights   # e.g. @aixle/insights@0.2.6-staging  (note the suffix)
 ```
 
 Point a staging build at the **staging** API host. Sending staging telemetry to production
@@ -53,14 +53,14 @@ pollutes production analytics.
 ### Which one do I have?
 
 ```bash
-aixle-insights --version                 # a -staging suffix means a QA build
+npm ls -g @aixle/insights                # a -staging suffix means a QA build
 npm view @aixle/insights dist-tags       # what each channel currently resolves to
 ```
 
 Expected output — `latest` and `staging` move independently:
 
 ```
-{ latest: '0.2.0', staging: '0.2.1-staging' }
+{ latest: '0.2.1', staging: '0.2.6-staging' }
 ```
 
 ### Switching back to production
@@ -73,8 +73,8 @@ Then re-run `init` against the production host, since credentials and the MCP en
 per-host.
 
 > **Why `npm install` never surprises you with a staging build:** `-staging` versions are semver
-> prereleases, and no ordinary version range resolves to a prerelease. `*`, `^0.2.0`, `~0.2.0`
-> and `>=0.1.0` all select `0.2.0` even when `0.2.1-staging` exists. Staging builds are
+> prereleases, and no ordinary version range resolves to a prerelease. `*`, `^0.2.1`, `~0.2.1`
+> and `>=0.1.0` all select `0.2.1` even when `0.2.6-staging` exists. Staging builds are
 > reachable only by exact version or the `staging` dist-tag.
 
 Maintainers: see [`../RELEASING.md`](../RELEASING.md) for how each channel is cut.
@@ -137,6 +137,45 @@ Once `init` succeeds it reports the bound org (`Credentials saved (organization
 
 > **Preferences caveat — this is non-obvious.** The web app's "current org" (the one you appear to be viewing) is normally the **last-used** org, remembered in your browser's `localStorage`. That is **not** the same as your **Default Organization** preference, which is what `init` reads. A multi-org user who has switched orgs in the UI but never explicitly set **Default Organization** in web Preferences has no server-side preference for `init` to use — so `init` will hit the org-selection error above until you either set the Default Organization preference or pass `--organization-id`.
 
+## Cursor hooks (optional)
+
+**Claude Code needs nothing beyond `init`** — the MCP transcript reader already captures model, token counts (including cache tokens), prompt and assistant text, risk scan, and tool uses.
+
+Cursor is different: its local store does not reliably record *which model* answered a turn, so events can land with `model: "unknown"`. Two things address it — the automatic `state.vscdb` fallback (DB90DV-540), and this opt-in hook forwarder for per-turn attribution captured as it happens:
+
+```bash
+npx -y @aixle/insights init --hooks --tool-name cursor --host <host> --keycloak-url <realm>
+
+aixle-insights verify-hooks     # JSON: installed? queue depth?
+aixle-insights uninstall-hooks  # remove, restoring the ~/.cursor/hooks.json backup
+```
+
+**Restart Cursor afterwards** — hooks are read at launch. The forwarder appends redacted payloads to `~/.aixle-insights/hooks-queue.ndjson`, which the next sync drains, so events arrive on the normal cycle rather than instantly.
+
+> Editor-level hooks (`~/.claude/settings.json` `PostToolUse` / `Stop`) are a **fallback for environments that cannot run an MCP server**, not an upgrade. They carry no model, token, or cost data, so the MCP path is strictly better wherever it is available.
+
+## Ingest tokens and rotation
+
+`init` mints an ingest token per tool — distinct from your Keycloak login — and stores it in the **OS keychain** (service `aixle-insights`), falling back to `~/.aixle-insights/credentials.json` at mode 0600 where no keychain is available. Tokens are `aixle_<64 hex>` and the server retains only a SHA-256 hash, so a token cannot be recovered after `init`; losing it means re-running `init`.
+
+You never need to paste a token for the MCP path — `init` obtains its own.
+
+> **Rotation policy: TBD.** There is no self-service rotation command and no documented expiry or cadence. Placeholders until an owner defines them:
+>
+> | | Placeholder |
+> |---|---|
+> | Token lifetime | _undefined — tokens do not self-expire today_ |
+> | Rotation cadence | _TBD_ |
+> | Who can revoke | _TBD — no CLI path; server-side only_ |
+
+**If a token is revoked, rotated server-side, or invalidated by a redeploy**, every sync fails with `HTTP 401` while `health` still reports `authenticated: true` — that flag only covers the OIDC login. Clear the stored credential and re-run `init`; state files are preserved, so already-sent sessions stay deduped:
+
+```bash
+security delete-generic-password -s "aixle-insights" -a "aixle-insights-ingest-credential"  # macOS
+rm -f ~/.aixle-insights/credentials.json
+# then re-run init
+```
+
 ## First run and backfill
 
 Before you run `init`, the MCP server is a deliberate no-op: it does not read, buffer, or send anything, and it does not create any state files. Nothing is lost during this window — Claude Code's transcripts and Cursor's local telemetry stores are unaffected by whether `@aixle/insights` is watching them.
@@ -145,6 +184,49 @@ The moment `init` succeeds, this package's per-credential state starts from empt
 
 If the MCP has been installed but never connected, `aixle-insights health` (or the `status` MCP tool) reports `needs_init: true` with a human-readable `onboarding_message` explaining exactly this — install-but-uninitialized is not a state you need to worry about losing data in.
 
+Once `init` succeeds it reports the bound org (`Credentials saved (organization <uuid>).`), and `aixle-insights health` (or the `aixle_insights_status` MCP tool) shows the bound `organization_id`.
+
+> **Preferences caveat — this is non-obvious.** The web app's "current org" (the one you appear to be viewing) is normally the **last-used** org, remembered in your browser's `localStorage`. That is **not** the same as your **Default Organization** preference, which is what `init` reads. A multi-org user who has switched orgs in the UI but never explicitly set **Default Organization** in web Preferences has no server-side preference for `init` to use — so `init` will hit the org-selection error above until you either set the Default Organization preference or pass `--organization-id`.
+
+## Cursor hooks (optional)
+
+**Claude Code needs nothing beyond `init`** — the MCP transcript reader already captures model, token counts (including cache tokens), prompt and assistant text, risk scan, and tool uses.
+
+Cursor is different: its local store does not reliably record *which model* answered a turn, so events can land with `model: "unknown"`. Two things address it — the automatic `state.vscdb` fallback (DB90DV-540), and this opt-in hook forwarder for per-turn attribution captured as it happens:
+
+```bash
+npx -y @aixle/insights init --hooks --tool-name cursor --host <host> --keycloak-url <realm>
+
+aixle-insights verify-hooks     # JSON: installed? queue depth?
+aixle-insights uninstall-hooks  # remove, restoring the ~/.cursor/hooks.json backup
+```
+
+**Restart Cursor afterwards** — hooks are read at launch. The forwarder appends redacted payloads to `~/.aixle-insights/hooks-queue.ndjson`, which the next sync drains, so events arrive on the normal cycle rather than instantly.
+
+> Editor-level hooks (`~/.claude/settings.json` `PostToolUse` / `Stop`) are a **fallback for environments that cannot run an MCP server**, not an upgrade. They carry no model, token, or cost data, so the MCP path is strictly better wherever it is available.
+
+## Ingest tokens and rotation
+
+`init` mints an ingest token per tool — distinct from your Keycloak login — and stores it in the **OS keychain** (service `aixle-insights`), falling back to `~/.aixle-insights/credentials.json` at mode 0600 where no keychain is available. Tokens are `aixle_<64 hex>` and the server retains only a SHA-256 hash, so a token cannot be recovered after `init`; losing it means re-running `init`.
+
+You never need to paste a token for the MCP path — `init` obtains its own.
+
+> **Rotation policy: TBD.** There is no self-service rotation command and no documented expiry or cadence. Placeholders until an owner defines them:
+>
+> | | Placeholder |
+> |---|---|
+> | Token lifetime | _undefined — tokens do not self-expire today_ |
+> | Rotation cadence | _TBD_ |
+> | Who can revoke | _TBD — no CLI path; server-side only_ |
+
+**If a token is revoked, rotated server-side, or invalidated by a redeploy**, every sync fails with `HTTP 401` while `health` still reports `authenticated: true` — that flag only covers the OIDC login. Clear the stored credential and re-run `init`; state files are preserved, so already-sent sessions stay deduped:
+
+```bash
+security delete-generic-password -s "aixle-insights" -a "aixle-insights-ingest-credential"  # macOS
+rm -f ~/.aixle-insights/credentials.json
+# then re-run init
+```
+
 ## Commands
 
 | Command | What it does |
@@ -156,7 +238,10 @@ If the MCP has been installed but never connected, `aixle-insights health` (or t
 | `aixle-insights init --host <url>` | Use an Aixle Insights API origin for token exchange. Remote hosts must use HTTPS; `http://localhost` and loopback addresses are allowed for local development. |
 | `aixle-insights init --insecure --host http://...` | Allow a remote plaintext HTTP host for a trusted non-production test endpoint. Prints a warning because tokens and telemetry can be exposed. |
 | `aixle-insights init --hooks --tool-name cursor` | Also install the Cursor-side hook forwarder (opt-in; requires Cursor restart). |
+| `aixle-insights init --force` | Re-run `init` even when credentials already exist — re-mints ingest tokens and re-writes the MCP entry. Use after changing host, org, or realm. |
+| `aixle-insights init --tool-name <tool>` | Scope `init` to a single connector. **Omit it** so one login covers both Claude Code and Cursor. |
 | `aixle-insights uninstall-hooks` | Remove the hook forwarder + restore `~/.cursor/hooks.json` backup. |
+| `aixle-insights uninstall-cursor-mcp` | Remove (or restore from backup) only the aixle-insights entry in `~/.cursor/mcp.json`, leaving sibling MCP servers untouched. |
 | `aixle-insights verify-hooks` | Print hooks install status + queue depth as JSON. |
 | `aixle-insights health` | Multi-line diagnostic (credentials, sync, log path, state files). |
 
@@ -166,9 +251,14 @@ If the MCP has been installed but never connected, `aixle-insights health` (or t
 |---|---|
 | `AIXLE_INSIGHTS_API_URL` (deprecated: `DB90_API_URL`) | API origin for ingestion + MCP exchange (defaults to `http://localhost:3000`; `init --host` overrides). |
 | `KEYCLOAK_ISSUER` / `AIXLE_INSIGHTS_KEYCLOAK_ISSUER` (deprecated: `DB90_KEYCLOAK_ISSUER`) | Realm issuer URLs (`KEYCLOAK_ISSUER` is preferred on servers + CI). |
-| `AIXLE_INSIGHTS_KEYCLOAK_CLIENT_ID` (deprecated: `DB90_KEYCLOAK_CLIENT_ID`) | Defaults to `db90-web`; must allow device authorization in Keycloak. |
+| `KEYCLOAK_CLIENT_ID` / `AIXLE_INSIGHTS_KEYCLOAK_CLIENT_ID` (deprecated: `DB90_KEYCLOAK_CLIENT_ID`) | Defaults to `aixle-insights-web`; must allow device authorization in Keycloak. |
 | `AIXLE_INSIGHTS_ORGANIZATION_ID` (deprecated: `DB90_ORGANIZATION_ID`) | Optional UUID scoping `init` to that org membership (header `X-Organization-ID`). |
 | `AIXLE_INSIGHTS_HOME` | Override the local state directory (defaults to `~/.aixle-insights/`). |
+| `AIXLE_INSIGHTS_MCP_DISABLE_KEYTAR` (deprecated: `DB90_MCP_DISABLE_KEYTAR`) | Set to skip the OS keychain entirely and use the `credentials.json` fallback. Useful on headless Linux/CI/Docker where Secret Service is absent. |
+| `AIXLE_INSIGHTS_MCP_USE_LOCAL_KEYCLOAK_DEFAULT` (deprecated: `DB90_MCP_USE_LOCAL_KEYCLOAK_DEFAULT`) | Default the Keycloak issuer to the local stack (`http://localhost:8080/realms/db90`) so `--keycloak-url` can be omitted during local development. |
+| `AIXLE_INSIGHTS_CLAUDE_USER_CONFIG_PATH` (deprecated: `DB90_CLAUDE_USER_CONFIG_PATH`) | Override the path to `~/.claude.json` that `init` merges the MCP entry into. Primarily a test seam; also lets you target a non-default Claude Code profile. |
+
+Also read, but not intended as user-facing configuration: `APPDATA` and `XDG_CONFIG_HOME` (platform config-directory discovery) and `NODE_ENV`.
 
 Remote API and ingest hosts must use `https://`. Plaintext `http://` is local-dev-only for `localhost`, `127.0.0.0/8`, and `[::1]`; those loopback URLs work without warnings. A remote `http://` host is rejected during `init` unless you pass `--insecure`, which should only be used for trusted non-production test endpoints and will print a warning because ingest tokens and telemetry can cross the network unencrypted.
 
@@ -186,11 +276,81 @@ Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per
 }
 ```
 
-The file is optional — an absent `config.json` is the normal case and is silent. A file that is
-present but unusable is ignored entirely (every override falls back to its default) and a
-`config_parse_failed` line is written to `mcp.log`. That covers malformed JSON and valid JSON that
-isn't an object, including a **top-level array** — a common mistake when writing per-model rates.
-Nothing is printed to the terminal, so check the log if an override appears to have no effect.
+### Configuration reference
+
+`~/.aixle-insights/config.json` is optional — `init` does not create it. Every key is optional too.
+
+| Key | Type | Purpose |
+|---|---|---|
+| `host` | string | Ingest API origin. Same value as `--host`. |
+| `token` | string | Ingest token. Rarely needed — `init` stores tokens in the keychain instead, and this is the plaintext alternative. |
+| `project_id` | string | Pin every event to one project instead of resolving from the git remote. |
+| `cursor.line_costs.<model>` | `{ input_per_line, output_per_line }` | Per-model cost rates for Cursor line-based accounting. |
+
+**Precedence:** CLI flag → environment variable → `config.json`. A flag always wins; the config file is the fallback of last resort. An absent `config.json` is the normal case and is silent. A file that is present but unusable — malformed JSON, or valid JSON that isn't an object, including a **top-level array** (a common mistake when writing per-model rates) — is ignored entirely: every override falls back to its default, and a `config_parse_failed` line is written to `mcp.log` rather than a crash. Nothing is printed to the terminal, so check the log if an override appears to have no effect.
+
+Worked example — pin a project and override Cursor rates for two models:
+
+```json
+{
+  "host": "https://staging.insights.aixle.com",
+  "project_id": "3f6c1e28-9b4a-4c7f-8d21-5ac0e7b91f04",
+  "cursor": {
+    "line_costs": {
+      "claude-sonnet-4-5": { "input_per_line": 0.0002, "output_per_line": 0.0008 },
+      "gpt-4o":            { "input_per_line": 0.0001, "output_per_line": 0.0004 }
+    }
+  }
+}
+```
+
+## Clean slate — full uninstall / reset
+
+Use this when a breaking change lands, when switching between the production and staging channels, or when you want to prove a problem is not stale local state. Steps are ordered least to most destructive; stop wherever your problem clears.
+
+**1. Remove editor integration**
+
+```bash
+aixle-insights uninstall-hooks        # Cursor hook forwarder + restore ~/.cursor/hooks.json backup
+aixle-insights uninstall-cursor-mcp   # remove only our entry from ~/.cursor/mcp.json
+```
+
+Then delete the `mcpServers.aixle-insights` entry from `~/.claude.json` by hand — `init` writes it and there is no command to remove it.
+
+**2. Clear credentials** — forces a fresh `init` and re-mints ingest tokens:
+
+```bash
+security delete-generic-password -s "aixle-insights" -a "aixle-insights-ingest-credential"  # macOS
+rm -f ~/.aixle-insights/credentials.json
+```
+
+**3. Reset sync state** — ⚠️ **this is the destructive one.** State files hold the watermarks and dedupe checkpoints. Deleting them makes the next sync treat all local history as new, so you get a **full re-backfill**. Ingest upserts by `metadata.session_id`, so you should get updates rather than duplicates, but volume will spike:
+
+```bash
+rm -f ~/.aixle-insights/state-*.json
+rm -f ~/.aixle-insights/state.lock          # only if no `aixle-insights run` is alive — check with: pgrep -fa aixle-insights
+rm -f ~/.aixle-insights/hooks-queue.ndjson  # discards hook events not yet drained
+```
+
+**4. Nuclear** — remove everything the package created locally:
+
+```bash
+rm -rf ~/.aixle-insights/    # credentials, state, logs, hook queue
+npm uninstall -g @aixle/insights
+```
+
+Nothing here touches your Claude Code transcripts or Cursor's own store — those belong to the editors and are only ever read. Events already delivered to the server are unaffected; this is purely local state.
+
+| Artifact | Created by | Removed in step |
+|---|---|---|
+| `~/.aixle-insights/credentials.json` / keychain entry | `init` | 2 |
+| `~/.aixle-insights/state-<host>-<hash>.json` | first sync | 3 |
+| `~/.aixle-insights/state.lock` | `run` | 3 |
+| `~/.aixle-insights/hooks-queue.ndjson` | hook forwarder | 3 |
+| `~/.aixle-insights/mcp.log`, `mcp.log.1` | any run | 4 |
+| `~/.cursor/hooks.json` entry | `init --hooks` | 1 |
+| `~/.cursor/mcp.json` entry | `init` | 1 |
+| `mcpServers.aixle-insights` in `~/.claude.json` | `init` | 1 (manual) |
 
 ## Security
 
@@ -362,6 +522,10 @@ cd packages/tools
 npm rebuild better-sqlite3
 ```
 
+## Changelog
+
+See [CHANGELOG.md](https://github.com/dualboot-partners/db90-rails/blob/develop/packages/tools/aixle-insights/CHANGELOG.md) — npm's registry page doesn't render this file directly, so it's linked here instead of duplicated.
+
 ## License
 
 MIT.

package/dist/auth/keycloak.js

@@ -193,9 +193,11 @@ export function defaultKeycloakIssuer(ingestHost) {
     return "";
 }
 export function defaultKeycloakClientId() {
-    return (readEnvWithDeprecatedAlias({
-        current: "AIXLE_INSIGHTS_KEYCLOAK_CLIENT_ID",
-        deprecated: "DB90_KEYCLOAK_CLIENT_ID",
-        onDeprecatedUse: warnDeprecatedEnvVar,
-    }) || "db90-web");
+    return (process.env["KEYCLOAK_CLIENT_ID"]?.trim() ||
+        readEnvWithDeprecatedAlias({
+            current: "AIXLE_INSIGHTS_KEYCLOAK_CLIENT_ID",
+            deprecated: "DB90_KEYCLOAK_CLIENT_ID",
+            onDeprecatedUse: warnDeprecatedEnvVar,
+        }) ||
+        "aixle-insights-web");
 }

package/dist/cli.js

@@ -238,7 +238,7 @@ export async function runInit(cliArgs, deps) {
     }
     const kcIssuer = (cliArgs.keycloakUrl ?? runtime.defaultKeycloakIssuer(apiHost)).trim();
     if (!kcIssuer) {
-        runtime.error("Error: Keycloak issuer is not configured. Pass --keycloak-url or set KEYCLOAK_ISSUER / AIXLE_INSIGHTS_KEYCLOAK_ISSUER (or deprecated DB90_KEYCLOAK_ISSUER).");
+        runtime.error("Error: Keycloak issuer is not configured. Pass --keycloak-url or set KEYCLOAK_ISSUER / AIXLE_INSIGHTS_KEYCLOAK_ISSUER.");
         return 1;
     }
     if (cliArgs.toolName !== undefined && !["claude_code", "cursor"].includes(cliArgs.toolName)) {
@@ -258,7 +258,7 @@ export async function runInit(cliArgs, deps) {
     });
     const exchangeOrganizationId = fromFlag || fromEnv;
     if (exchangeOrganizationId && !isValidOrganizationUuid(exchangeOrganizationId)) {
-        runtime.error("Error: --organization-id / AIXLE_INSIGHTS_ORGANIZATION_ID (or deprecated DB90_ORGANIZATION_ID) must be a valid UUID (RFC 4122, version 1–5, variant per Aixle Insights API).");
+        runtime.error("Error: --organization-id / AIXLE_INSIGHTS_ORGANIZATION_ID must be a valid UUID (RFC 4122, version 1–5, variant per Aixle Insights API).");
         return 1;
     }
     const result = await runtime.loginAndPersistCredentials({

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

@@ -33,7 +33,7 @@ export declare function canonicalizeGitRemote(remote: string, verbose: boolean):
  */
 export declare function repoNameToGitRemoteCandidates(repoName: string): string[];
 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. */
+/** Payload shape shared by the Cursor and Claude commit mappers. */
 export interface CommitAttributionPayload {
     event_type?: string;
     project_id?: string;

package/dist/server.js

@@ -160,7 +160,7 @@ async function authenticateHandler(args) {
         if (!kc) {
             return jsonContent({
                 ok: false,
-                error: "keycloakUrl or KEYCLOAK_ISSUER / AIXLE_INSIGHTS_KEYCLOAK_ISSUER (or deprecated DB90_KEYCLOAK_ISSUER) is required",
+                error: "keycloakUrl or KEYCLOAK_ISSUER / AIXLE_INSIGHTS_KEYCLOAK_ISSUER is required",
             });
         }
         const clientId = args.clientId?.trim() || defaultKeycloakClientId();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aixle/insights",
-  "version": "0.2.7-staging",
+  "version": "0.2.8-staging",
   "description": "stdio MCP server for AI coding-assistant telemetry — Claude transcript sync + Cursor SQLite ingest.",
   "type": "module",
   "bin": {
@@ -46,6 +46,7 @@
     "lint": "eslint . --max-warnings 0",
     "verify:cursor-dry-run": "tsx scripts/verify-cursor-dry-run.ts",
     "audit:local-stores": "tsx scripts/audit-local-stores.ts",
+    "nightly:resolve": "tsx scripts/nightly-release-resolve.ts",
     "dev": "tsx src/cli.ts",
     "prepublishOnly": "npm run build"
   },