@aixle/insights 0.2.5-staging → 0.2.6-staging

package/README.md

@@ -102,7 +102,27 @@ After `init` succeeds:
 
 ## Multi-org
 
-If your account has several organization memberships, `init` mints ingest tokens for the **oldest** membership unless you scope to a different org:
+If your account belongs to a **single** organization, `init` binds that org automatically — no flag, zero friction.
+
+If your account belongs to **more than one** organization, `init` needs to know which org to bind. It resolves the target in this order:
+
+1. `--organization-id <uuid>` flag (or `DB90_ORGANIZATION_ID` env var), or
+2. your **Default Organization** preference from the web app.
+
+If neither is set, `init` **does not** guess. It prints the organizations you belong to and exits non-zero without saving credentials:
+
+```
+Multiple organizations found — choose one to bind this install:
+  - Acme Corp (b1e2...  ) — owner
+  - Contoso (c3d4...  ) — member
+Then either:
+  1. Re-run init with --organization-id <uuid> (completes device login again), or
+  2. Set a Default Organization in web Preferences, then re-run init.
+```
+
+Because credentials are only persisted on success, re-running `init` means completing the Keycloak device login again.
+
+To scope explicitly:
 
 ```bash
 npx -y @aixle/insights init \
@@ -113,6 +133,10 @@ npx -y @aixle/insights init \
 
 You can also set `DB90_ORGANIZATION_ID=<uuid>` in your shell environment, or pin it via `mcpServers.aixle-insights.env` in `~/.claude.json`. The CLI flag overrides the env var when both are set.
 
+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`.
+
 ## 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.

package/dist/auth/exchange.d.ts

@@ -1,3 +1,12 @@
+export interface OrgOption {
+    id: string;
+    name: string;
+    role: string;
+}
+export declare class OrganizationSelectionRequiredError extends Error {
+    readonly organizations: OrgOption[];
+    constructor(message: string, organizations: OrgOption[]);
+}
 export interface ExchangeAccount {
     ingestToken: string;
 }

package/dist/auth/exchange.js

@@ -1,3 +1,11 @@
+export class OrganizationSelectionRequiredError extends Error {
+    organizations;
+    constructor(message, organizations) {
+        super(message);
+        this.name = "OrganizationSelectionRequiredError";
+        this.organizations = organizations;
+    }
+}
 export async function exchangeIngestToken(params) {
     const fetchFn = params.fetchImpl ?? fetch;
     const requestedTools = params.tools?.length ? [...params.tools] : params.toolName ? [params.toolName] : [];
@@ -38,6 +46,21 @@ export async function exchangeIngestToken(params) {
         throw new Error(`DB90 exchange: invalid JSON (HTTP ${res.status}): ${text.slice(0, 200)}`);
     }
     if (!res.ok) {
+        const errBody = json;
+        if (errBody["error"] === "organization_selection_required") {
+            const rawOrgs = Array.isArray(errBody["organizations"]) ? errBody["organizations"] : [];
+            // Defensive: skip null/non-object elements so a malformed server body cannot crash init.
+            const orgs = rawOrgs
+                .filter((o) => typeof o === "object" && o !== null && !Array.isArray(o))
+                .filter((o) => typeof o["id"] === "string" && typeof o["name"] === "string")
+                .map((o) => ({
+                id: o["id"],
+                name: o["name"],
+                role: String(o["role"] ?? ""),
+            }));
+            const msg = typeof errBody["message"] === "string" ? errBody["message"] : "Organization selection required.";
+            throw new OrganizationSelectionRequiredError(msg, orgs);
+        }
         throw new Error(`DB90 exchange failed (HTTP ${res.status}): ${text.slice(0, 500)}`);
     }
     const root = json;

package/dist/auth/flow.d.ts

@@ -1,3 +1,4 @@
+import { type OrgOption } from "./exchange.js";
 import { defaultKeycloakClientId, defaultKeycloakIssuer } from "./keycloak.js";
 import type { TelemetryToolId } from "./credentials.js";
 export interface LoginAndPersistOptions {
@@ -29,5 +30,7 @@ export declare function loginAndPersistCredentials(opts: LoginAndPersistOptions)
 } | {
     ok: false;
     error: string;
+    code?: "organization_selection_required";
+    organizations?: OrgOption[];
 }>;
 export { defaultKeycloakIssuer, defaultKeycloakClientId };

package/dist/auth/flow.js

@@ -1,4 +1,4 @@
-import { exchangeIngestToken } from "./exchange.js";
+import { exchangeIngestToken, OrganizationSelectionRequiredError } from "./exchange.js";
 import { defaultKeycloakClientId, defaultKeycloakIssuer, obtainKeycloakAccessTokenViaDeviceFlow } from "./keycloak.js";
 import { loadCredentials, saveStoredCredentials } from "./credentials.js";
 import { getAppDir } from "../state.js";
@@ -78,10 +78,11 @@ export async function loginAndPersistCredentials(opts) {
             opts.onSecurityWarning?.(ingestHostSecurity.warning);
         }
         const existing = await loadCredentials(appDir);
+        const sameOrg = existing?.host === exchanged.ingestHost && existing.organizationId === exchanged.organizationId;
         const stored = {
             host: exchanged.ingestHost,
             organizationId: exchanged.organizationId,
-            accounts: existing?.host === exchanged.ingestHost ? { ...existing.accounts } : {},
+            accounts: sameOrg ? { ...existing.accounts } : {},
             ...(opts.allowInsecureHttp === true ? { insecureHttpAllowed: true } : {}),
         };
         for (const tid of ["claude_code", "cursor"]) {
@@ -92,6 +93,14 @@ export async function loginAndPersistCredentials(opts) {
         await saveStoredCredentials(stored, appDir);
     }
     catch (e) {
+        if (e instanceof OrganizationSelectionRequiredError) {
+            return {
+                ok: false,
+                code: "organization_selection_required",
+                organizations: e.organizations,
+                error: e.message,
+            };
+        }
         return { ok: false, error: e instanceof Error ? e.message : String(e) };
     }
     return { ok: true, organizationId: exchanged.organizationId };

package/dist/cli.js

@@ -185,7 +185,9 @@ init options:
   --insecure               Allow remote http:// hosts for trusted non-production test endpoints only.
 
 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.
+  If you belong to more than one org, pass \`--organization-id <uuid>\` (or set \`DB90_ORGANIZATION_ID\`),
+  or set a Default Organization in web Preferences. Without either, \`init\` lists your orgs and exits.
+  Single-org users need no flag. Run \`aixle-insights health\` to see the bound organization_id.
 
 Credentials:
   Stored in the OS keychain via keytar when available; otherwise
@@ -270,6 +272,19 @@ export async function runInit(cliArgs, deps) {
         },
     });
     if (!result.ok) {
+        if (result.code === "organization_selection_required") {
+            runtime.error(result.error);
+            if (result.organizations?.length) {
+                runtime.error("Multiple organizations found — choose one to bind this install:");
+                for (const o of result.organizations) {
+                    runtime.error(`  - ${o.name} (${o.id})${o.role ? ` — ${o.role}` : ""}`);
+                }
+            }
+            runtime.error("Then either:");
+            runtime.error("  1. Re-run init with --organization-id <uuid> (completes device login again), or");
+            runtime.error("  2. Set a Default Organization in web Preferences, then re-run init.");
+            return 1;
+        }
         runtime.error(`Auth failed: ${result.error}`);
         return 1;
     }

package/dist/health.d.ts

@@ -5,6 +5,7 @@ export interface HealthSnapshot {
     authenticated: boolean;
     configured: boolean;
     host: string | null;
+    organization_id: string | null;
     ingest_tools: TelemetryToolId[];
     app_dir: string;
     log_path: string;

package/dist/health.js

@@ -70,6 +70,7 @@ export async function buildHealthSnapshot() {
                 authenticated: false,
                 configured: false,
                 host: null,
+                organization_id: null,
                 ingest_tools: [],
                 app_dir: appDir,
                 log_path: logPath,
@@ -94,6 +95,7 @@ export async function buildHealthSnapshot() {
             authenticated: true,
             configured: true,
             host: creds.host,
+            organization_id: creds.organizationId ?? null,
             ingest_tools,
             app_dir: appDir,
             log_path: logPath,
@@ -114,6 +116,7 @@ export async function buildHealthSnapshot() {
             authenticated: false,
             configured: false,
             host: null,
+            organization_id: null,
             ingest_tools: [],
             app_dir: appDir,
             log_path: logPath,
@@ -150,6 +153,7 @@ export function healthSnapshotToStatusPayload(snapshot) {
         authenticated: snapshot.authenticated,
         configured: snapshot.configured,
         host: snapshot.host,
+        organization_id: snapshot.organization_id,
         ingest_tools: snapshot.ingest_tools,
         needs_init: needsInit,
         onboarding_message: onboardingMessage,
@@ -172,6 +176,7 @@ export function formatHealthForCli(snapshot) {
     lines.push(`authenticated: ${snapshot.authenticated}`);
     lines.push(`configured: ${snapshot.configured}`);
     lines.push(`host: ${snapshot.host ?? "(none)"}`);
+    lines.push(`organization_id: ${snapshot.organization_id ?? "(none)"}`);
     lines.push(`ingest_tools: ${snapshot.ingest_tools.length ? snapshot.ingest_tools.join(", ") : "(none)"}`);
     lines.push(`state_file_paths:`);
     if (snapshot.state_file_paths.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aixle/insights",
-  "version": "0.2.5-staging",
+  "version": "0.2.6-staging",
   "description": "stdio MCP server for AI coding-assistant telemetry — Claude transcript sync + Cursor SQLite ingest.",
   "type": "module",
   "bin": {