@lorekit/cli 1.53.0 → 1.55.0

package/src/telemetry-identity.mjs

@@ -0,0 +1,276 @@
+// LoreKit CLI — durable telemetry identity.
+//
+// The CLI's own OTLP export (src/telemetry.mjs) was, by construction,
+// unattributable: one span per command carrying the command name, a bounded
+// flag allow-list and the runtime/OS tuple, and nothing that linked two runs.
+// Server-side that gap does not exist — every authenticated REST/MCP call lands
+// on an edge root span carrying `auth.user_id`, and `usage_events` records the
+// same id — but a run that never leaves the machine (`--offline`, the two-tier
+// local store, `lorekit hook`) makes no server call at all, so 1000 local spans
+// could equally be one user or a thousand.
+//
+// This module closes that gap with TWO ids, because they answer different
+// questions and neither substitutes for the other:
+//
+//   • installId — a random, opaque, locally-minted id, persisted so it survives
+//     across runs. Always available once minted, including fully offline. It
+//     differentiates INSTALLS: the same person on a laptop and in CI is two
+//     ids, and two people sharing a container are one.
+//
+//   • accountId — the LoreKit account (Supabase auth UUID) the CLI last
+//     authenticated as, learned from the `X-LoreKit-User-Id` response header
+//     that `restFetch` reads off any authenticated call and cached here. Once
+//     learned it is stamped on EVERY later run, offline ones included, which is
+//     what makes local CLI usage joinable to server-side `auth.user_id` and
+//     `usage_events.user_id`.
+//
+// PRIVACY — this runs on end-users' machines, so the invariants matter more
+// than the feature:
+//
+//   1. Nothing is minted, and NO FILE IS EVER CREATED, while telemetry is
+//      disabled. `ensureInstallId` takes the resolved config and returns null
+//      when export is off, so an opt-out (LOREKIT_TELEMETRY=0, DO_NOT_TRACK=1,
+//      `telemetry.disabled`) never gets a tracking id written to their disk.
+//   2. `rememberAccountId` only ever UPDATES an existing file — it never
+//      creates one. The file exists only where (1) already minted an install
+//      id, so an opted-out user's account id is not recorded either, even
+//      though the header is on every response they receive.
+//   3. The install id is opaque and carries nothing derived from the machine —
+//      no hostname, no MAC, no username, no path. It is random, so it says
+//      "these runs are the same install" and nothing else about who that is.
+//   4. It is a plain file the user owns and can inspect or delete; `doctor`
+//      prints its location for exactly that reason. Deleting it resets the
+//      install identity, which is the whole opt-out-after-the-fact story.
+//
+// Everything here is TOTAL: an unreadable file, an unwritable home, a corrupt
+// JSON body and a full disk all degrade to "no identity" rather than throwing.
+// Telemetry must never be the thing that breaks a command — the same contract
+// `exportInvocation` holds.
+
+import process from 'node:process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { homeRoot } from './control.mjs';
+import { writeFileAtomic } from './config.mjs';
+
+/** Filename under the home tier. Sits beside `config.json` and the local store. */
+const IDENTITY_FILE = 'telemetry-id.json';
+
+/**
+ * Absolute path to the identity file: `$LOREKIT_HOME/telemetry-id.json`,
+ * defaulting to `~/.lorekit/telemetry-id.json`.
+ *
+ * Resolved through `homeRoot` — the SAME function that resolves the home-tier
+ * store and `config.json` — rather than re-deriving `LOREKIT_HOME || ~/.lorekit`
+ * here. A duplicated path resolution is not like the duplicated regexes
+ * elsewhere in the zero-dep CLI: if the two drifted, the id would silently land
+ * in a different directory than the store it belongs to, minting a "new install"
+ * for a user who had one all along.
+ *
+ * @param {object} [env] defaults to process.env
+ */
+export function identityPath(env = process.env) {
+  return path.join(homeRoot(env), IDENTITY_FILE);
+}
+
+/**
+ * Read the stored identity, or an empty object. TOTAL — a missing file, an
+ * unreadable one, a corrupt body, or a body that is valid JSON but not an
+ * object all yield `{}`.
+ *
+ * The `typeof` guards are not defensive noise: `JSON.parse('null')`,
+ * `JSON.parse('42')` and `JSON.parse('"x"')` all succeed, and a non-string
+ * `installId` reaching an attribute bag would be emitted as `String(value)` —
+ * so `{"installId": {}}` would ship the literal `[object Object]` as an
+ * identity and quietly fold every such install into one bucket.
+ *
+ * @param {string} [file] defaults to {@link identityPath}
+ * @returns {{ installId?: string, accountId?: string }}
+ */
+export function readIdentity(file = identityPath()) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    const out = {};
+    if (typeof parsed.installId === 'string' && parsed.installId) out.installId = parsed.installId;
+    if (typeof parsed.accountId === 'string' && parsed.accountId) out.accountId = parsed.accountId;
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Persist an identity object, creating the home directory if needed.
+ * Returns true on success, false on any failure (unwritable home, full disk).
+ *
+ * @param {{ installId?: string, accountId?: string }} identity
+ * @param {string} [file] defaults to {@link identityPath}
+ */
+function writeIdentity(identity, file = identityPath()) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify(identity, null, 2)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mint a fresh install id: 32 random hex characters.
+ *
+ * Deliberately opaque and machine-independent. A hostname- or MAC-derived id
+ * would be stable without a file, but it would also be a fingerprint the user
+ * cannot reset and one that leaks their machine into a span attribute.
+ */
+export function mintInstallId() {
+  const b = new Uint8Array(16);
+  // The WebCrypto global, as in telemetry.mjs — see the note there on why this
+  // is used unqualified rather than imported from `node:crypto`.
+  crypto.getRandomValues(b);
+  return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Resolve the install id, minting and persisting one on first use.
+ *
+ * Returns null — no identity, same as today's behaviour — when:
+ *   • telemetry export is disabled (`config.enabled !== true`). This is the
+ *     opt-out invariant: no id is minted and no file is created.
+ *   • the id could not be persisted. An id that cannot be stored would be a
+ *     DIFFERENT value on every run, which is strictly worse than none: it
+ *     inflates the distinct-install count to equal the invocation count and is
+ *     indistinguishable, in the data, from that many real installs. A read-only
+ *     home therefore reports no identity rather than a misleading one.
+ *
+ * @param {{ enabled?: boolean }} config  the resolved telemetry config
+ * @param {object} [opts]
+ * @param {string} [opts.file] defaults to {@link identityPath}
+ * @returns {string | null}
+ */
+export function ensureInstallId(config, { file = identityPath() } = {}) {
+  // Delegates rather than repeating the mint-and-persist logic: two copies of
+  // "read, mint if absent, preserve accountId, bail if unwritable" is two places
+  // for the opt-out invariant to be broken independently.
+  return ensureIdentity(config, { file }).installId;
+}
+
+/**
+ * Resolve the full identity for a run — install id (minted on first use) plus
+ * any cached account id — in ONE file read.
+ *
+ * The single entry point callers should use. `ensureInstallId` reads the file
+ * and so did a follow-up `readIdentity()` for the account id, which put two
+ * reads of the same small file on `lorekit hook`'s per-turn path for no reason.
+ *
+ * Same contract as {@link ensureInstallId}: nothing is minted and no file is
+ * created while export is disabled, and a non-persistable id reports as no
+ * identity rather than as a fresh one per run.
+ *
+ * @param {{ enabled?: boolean }} config  the resolved telemetry config
+ * @param {object} [opts]
+ * @param {string} [opts.file] defaults to {@link identityPath}
+ * @returns {{ installId: string | null, accountId: string | null }}
+ */
+export function ensureIdentity(config, { file = identityPath() } = {}) {
+  if (!config || config.enabled !== true) return { installId: null, accountId: null };
+  const stored = readIdentity(file);
+  const accountId = stored.accountId ?? null;
+  if (stored.installId) return { installId: stored.installId, accountId };
+  const installId = mintInstallId();
+  // Preserve any accountId already cached — a corrupt-but-partial file should
+  // not lose the account linkage on the run that repairs the install id.
+  if (!writeIdentity({ ...stored, installId }, file)) return { installId: null, accountId: null };
+  return { installId, accountId };
+}
+
+/**
+ * Cache the LoreKit account id the CLI just authenticated as.
+ *
+ * Called from `restFetch` for every authenticated response that carries an
+ * `X-LoreKit-User-Id` header — so the id is learned on any remote call and then
+ * available to every later run, including offline ones.
+ *
+ * NEVER CREATES THE FILE. It writes only when a file with an install id already
+ * exists, which is exactly the set of machines where telemetry was enabled and
+ * minted one. That is what keeps an opted-out user's account id off their disk
+ * without threading the telemetry config all the way into the HTTP layer.
+ *
+ * A no-op when the value is unchanged, so the common case is one read and no
+ * write. Returns true only when something was actually persisted.
+ *
+ * @param {string | null | undefined} accountId
+ * @param {object} [opts]
+ * @param {string} [opts.file] defaults to {@link identityPath}
+ */
+export function rememberAccountId(accountId, { file = identityPath() } = {}) {
+  if (typeof accountId !== 'string' || !accountId) return false;
+  const stored = readIdentity(file);
+  if (!stored.installId) return false; // no file / telemetry never enabled
+  if (stored.accountId === accountId) return false;
+  return writeIdentity({ ...stored, accountId }, file);
+}
+
+/**
+ * The identity RESOURCE attribute, or `{}` when there is no identity.
+ *
+ * `service.instance.id` is the OTel semconv key for "which instance of this
+ * service produced the telemetry", which is exactly what an install is — so the
+ * install id belongs on the resource under the standard key rather than under a
+ * `lorekit.*` one a backend has no built-in understanding of. Distinct installs
+ * are then countable with no LoreKit-specific knowledge.
+ *
+ * @param {{ installId?: string | null }} identity
+ */
+export function identityResourceAttributes({ installId } = {}) {
+  return installId ? { 'service.instance.id': installId } : {};
+}
+
+/**
+ * The identity attribute for a CLI span / metric data point, or `{}` when there
+ * is no identity to report.
+ *
+ * `user.id` is the ACCOUNT when one is known, else `install:<installId>`. This
+ * mirrors the browser RUM decision (`web/src/lib/dash0-rum.ts`: an `anon:<uuid>`
+ * upgraded in place to the real id), so a backend that folds `user.id` into
+ * unique-user analytics answers "how many PEOPLE use the CLI" — collapsing one
+ * person's laptop and CI runs into one user — while `service.instance.id` on the
+ * resource still tells those installs apart underneath. The `install:` prefix
+ * keeps a pre-auth run visibly distinct from a real account id instead of
+ * silently occupying the same value space.
+ *
+ * CARDINALITY: this rides on the `lorekit.cli.invocations` counter as well as
+ * the span, so the counter's series count is multiplied by the number of
+ * distinct users. That is inherent to being able to differentiate them at all,
+ * and it is bounded by real adoption rather than by anything a caller controls
+ * — but it is the reason no FURTHER identity dimension belongs on the metric.
+ *
+ * @param {{ installId?: string | null, accountId?: string | null }} identity
+ */
+export function identityAttributes({ installId, accountId } = {}) {
+  if (!installId) {
+    // No install id means nothing was persisted (opted out, or unwritable
+    // home). An accountId alone is not emitted: it can only have come from a
+    // file that also holds an installId, so this branch means "no identity".
+    return {};
+  }
+  return { 'user.id': accountId || `install:${installId}` };
+}
+
+/**
+ * Read-only view of the identity for `doctor` to report: what is stored, where,
+ * and whether an account has been linked yet. Never mints anything, so running
+ * `doctor` cannot itself create the file.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.file] defaults to {@link identityPath}
+ */
+export function describeIdentity({ file = identityPath() } = {}) {
+  const stored = readIdentity(file);
+  return {
+    file,
+    installId: stored.installId ?? null,
+    accountId: stored.accountId ?? null,
+  };
+}

package/src/telemetry.mjs

@@ -12,10 +12,19 @@
 //   • Opt-out honored: LOREKIT_TELEMETRY=0|off|false|no|disable, or the
 //     cross-vendor DO_NOT_TRACK=1, disables all export.
 //   • No PII is ever attached: only the command name, a bounded allow-list of
-//     boolean flags, the CLI/runtime/OS identity, and the outcome. Never a
-//     path, cwd, token, endpoint, repo, or scope string.
+//     boolean flags, the CLI/runtime/OS identity, the outcome, and the durable
+//     telemetry identity described below. Never a path, cwd, token, endpoint,
+//     repo, or scope string.
 //   • Disabled outright when no OTLP endpoint resolves.
 //
+// IDENTITY — runs are attributable, which they deliberately were not before.
+// `telemetry-identity.mjs` supplies an opaque, locally-minted install id
+// (`service.instance.id` on the resource) and, once any authenticated call has
+// taught the CLI which account it is, that account on `user.id`. Read that
+// module's header for the invariants; the one that constrains THIS file is that
+// nothing is minted while export is disabled, so `ensureInstallId` is only ever
+// called with an already-enabled config.
+//
 // The default endpoint + token below are baked into the published package and
 // are therefore public by design. The token MUST be Dash0 ingestion-only
 // (write/POST spans, no read/query/manage) — anyone can unpack the npm tarball
@@ -26,6 +35,11 @@
 import process from 'node:process';
 import { TELEMETRY_TOKEN } from './telemetry-token.mjs';
 import { readLorekitJson } from './config.mjs';
+import {
+  ensureIdentity,
+  identityAttributes,
+  identityResourceAttributes,
+} from './telemetry-identity.mjs';
 
 // ── Baked-in defaults (public by design) ──────────────────────────────────────
 // The endpoint is a committed default; the token is injected at publish time
@@ -231,7 +245,7 @@ export function resolveDeploymentEnvironment(env = process.env) {
   return value || undefined;
 }
 
-function resourceAttributes(version, env = process.env) {
+function resourceAttributes(version, env = process.env, identity = {}) {
   const attrs = [
     { key: 'service.name', value: { stringValue: 'cli' } },
     { key: 'service.namespace', value: { stringValue: 'lorekit' } },
@@ -243,6 +257,12 @@ function resourceAttributes(version, env = process.env) {
   ];
   const deploymentEnv = resolveDeploymentEnvironment(env);
   if (deploymentEnv) attrs.push({ key: 'deployment.environment.name', value: { stringValue: deploymentEnv } });
+  // `service.instance.id` — the install. Omitted entirely when there is no
+  // identity (opted out, or an unwritable home), never placeholdered: a
+  // constant stand-in would fold every such machine into one instance.
+  for (const [key, value] of Object.entries(identityResourceAttributes(identity))) {
+    attrs.push({ key, value: { stringValue: String(value) } });
+  }
   return attrs;
 }
 
@@ -332,11 +352,11 @@ export function commandAttributes({ command, args = {}, outcome, exitCode, extra
   return attrs;
 }
 
-export function buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId }) {
+export function buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId, identity }) {
   return {
     resourceSpans: [
       {
-        resource: { attributes: resourceAttributes(version) },
+        resource: { attributes: resourceAttributes(version, process.env, identity) },
         scopeSpans: [
           {
             scope: { name: 'cli', version: String(version) },
@@ -362,11 +382,11 @@ export function buildTracePayload({ version, name, attributes, startMs, endMs, s
   };
 }
 
-export function buildMetricsPayload({ version, attributes, startMs, endMs }) {
+export function buildMetricsPayload({ version, attributes, startMs, endMs, identity }) {
   return {
     resourceMetrics: [
       {
-        resource: { attributes: resourceAttributes(version) },
+        resource: { attributes: resourceAttributes(version, process.env, identity) },
         scopeMetrics: [
           {
             scope: { name: 'cli', version: String(version) },
@@ -396,6 +416,31 @@ export function buildMetricsPayload({ version, attributes, startMs, endMs }) {
   };
 }
 
+// ── Identity ──────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the durable telemetry identity for this run: the install id (minting
+ * and persisting one on first use) plus any account id a previous authenticated
+ * call cached.
+ *
+ * TOTAL and side-effect-free when export is off — `ensureInstallId` returns
+ * null for a disabled config without touching the disk, so the opt-out
+ * invariant holds here by delegation rather than by a second check that could
+ * drift from it.
+ *
+ * @param {{ enabled?: boolean }} config
+ * @returns {{ installId: string | null, accountId: string | null }}
+ */
+function resolveIdentity(config) {
+  try {
+    return ensureIdentity(config);
+  } catch {
+    // Identity is an enrichment, never a precondition. A failure here degrades
+    // to the pre-identity behaviour: telemetry still exports, unattributed.
+    return { installId: null, accountId: null };
+  }
+}
+
 // ── Export ────────────────────────────────────────────────────────────────────
 
 async function post(url, headers, payload, timeoutMs) {
@@ -420,16 +465,71 @@ async function post(url, headers, payload, timeoutMs) {
  * can never delay or fail the CLI. Awaited before process exit (Node would
  * otherwise drop the in-flight request), but capped at timeoutMs.
  */
-export async function exportInvocation(config, { version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId }, { timeoutMs = 1500 } = {}) {
+export async function exportInvocation(config, { version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId, identity }, { timeoutMs = 1500 } = {}) {
   if (!config || !config.enabled) return;
-  const trace = buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId });
-  const metric = buildMetricsPayload({ version, attributes, startMs, endMs });
+  // `user.id` rides on BOTH payloads: on the span so a trace is attributable,
+  // and on the counter data point so "distinct users who ran `search`" is
+  // answerable without touching traces at all.
+  const identified = { ...attributes, ...identityAttributes(identity) };
+  const trace = buildTracePayload({ version, name, attributes: identified, startMs, endMs, status, statusMessage, traceId, spanId, identity });
+  const metric = buildMetricsPayload({ version, attributes: identified, startMs, endMs, identity });
   await Promise.all([
     post(`${config.endpoint}/v1/traces`, config.headers, trace, timeoutMs),
     post(`${config.endpoint}/v1/metrics`, config.headers, metric, timeoutMs),
   ]);
 }
 
+/**
+ * Export ONLY the invocation counter — no span — for the machine-facing
+ * commands (`hook`, `mcp`).
+ *
+ * These are the highest-volume entry points by a wide margin: `hook` fires on
+ * every agent turn, several times per turn. They were `traced: false` and so
+ * emitted nothing at all, which meant the identity work above would have
+ * differentiated users across the human-facing commands while the traffic that
+ * actually dominates stayed invisible.
+ *
+ * Metric-only, and on a much tighter budget than {@link exportInvocation}, for
+ * three reasons specific to this path:
+ *   • A span per hook invocation would be a firehose of near-identical traces
+ *     for no analytical gain over a counter — the question here is "how much,
+ *     by whom", not "what happened inside this one".
+ *   • `hook` and `mcp` own stdout as a machine contract (the host parses it),
+ *     and `traceCommand`'s 1500 ms export budget sits between the command
+ *     finishing and the process exiting. On a per-turn hook that is a latency
+ *     the user feels; {@link METERED_TIMEOUT_MS} is the cap that keeps it
+ *     imperceptible, accepting a dropped data point over a delayed agent.
+ *   • Nothing here is allowed to change the exit code or stdout, so every
+ *     failure path returns quietly.
+ *
+ * @param {object} config  resolved telemetry config
+ * @param {string} command  `hook` | `mcp`
+ * @param {string} version  CLI version
+ * @param {object} [extraAttrs]  bounded extra dimensions (e.g. the hook event)
+ */
+export async function countInvocation(config, command, version, extraAttrs = {}) {
+  if (!config || !config.enabled) return;
+  const identity = resolveIdentity(config);
+  const now = Date.now();
+  const attributes = {
+    ...commandAttributes({ command, outcome: CLI_OUTCOMES.OK, extraAttrs }),
+    ...identityAttributes(identity),
+  };
+  await post(
+    `${config.endpoint}/v1/metrics`,
+    config.headers,
+    buildMetricsPayload({ version, attributes, startMs: now, endMs: now, identity }),
+    METERED_TIMEOUT_MS,
+  );
+}
+
+/**
+ * The export budget for the metric-only machine-facing path. Deliberately much
+ * shorter than the 1500 ms default: this sits on the agent's per-turn critical
+ * path, so a slow collector must cost a data point, not a visible stall.
+ */
+export const METERED_TIMEOUT_MS = 400;
+
 /**
  * Send ONE synthetic span to the configured OTLP endpoint and report what the
  * collector said about it.
@@ -551,6 +651,54 @@ function normalizeExitCode(result) {
   return result ?? 0;
 }
 
+/**
+ * Run a MACHINE-facing command (`hook`, `mcp`) and count the invocation —
+ * counter only, no span. Returns the command's exit code unchanged.
+ *
+ * The export is STARTED BEFORE the command runs and awaited after, so it
+ * overlaps the command's own work instead of being serialized behind it. That
+ * ordering is what makes this affordable on `hook`, which fires several times
+ * per agent turn: by the time there is anything to await, the POST has usually
+ * already completed, and {@link METERED_TIMEOUT_MS} caps the worst case.
+ *
+ * It also makes the count robust for `mcp`, which is a LONG-LIVED stdio server —
+ * `run()` does not return until the server exits, and a killed server would
+ * never have reported at all if the export waited for it. Since the counter
+ * reports the invocation rather than its outcome (a machine-facing command's
+ * verdict belongs to its stdout contract, which the host reads), there is
+ * nothing to learn by waiting.
+ *
+ * Nothing here can affect the command: the exit code is passed through
+ * untouched, and every telemetry failure is swallowed.
+ *
+ * @param {string} command  `hook` | `mcp`
+ * @param {string} version  CLI version
+ * @param {() => Promise<number>} run  the command handler
+ */
+export async function meterCommand(command, version, run) {
+  let config;
+  try {
+    config = resolveTelemetryConfig();
+  } catch {
+    config = { enabled: false };
+  }
+
+  // Fast path — no export configured. The overwhelmingly common case for these
+  // two commands (the baked-in token is absent in the source tree), so it must
+  // cost nothing at all: no identity read, no timer, no promise.
+  if (!config.enabled) return normalizeExitCode(await run());
+
+  // `.catch` attached IMMEDIATELY, before any await: an unawaited rejecting
+  // promise is an unhandled rejection, which on a machine-facing command would
+  // print to stderr and pollute a host's log.
+  const pending = countInvocation(config, command, version).catch(() => {});
+  try {
+    return normalizeExitCode(await run());
+  } finally {
+    await pending;
+  }
+}
+
 /**
  * Time a human-facing command, record its outcome, and export one span + one
  * counter point. Returns the command's exit code unchanged. Telemetry failures
@@ -601,6 +749,14 @@ export async function traceCommand(command, args, version, run) {
     }
   }
 
+  // Resolved once, before the command runs, so the export in `finally` cannot
+  // pay for a first-run mint on the crash path — and so a command that itself
+  // learns the account id (any remote call, via `restFetch`) does not race the
+  // read. A run that learns it for the first time reports `install:<id>` and the
+  // NEXT run reports the account; one deliberately-late run beats a mid-command
+  // re-read whose result depends on which subcommand happened to phone home.
+  const identity = resolveIdentity(config);
+
   const startMs = Date.now();
   let exitCode = 0;
   // `outcome` is the command's VERDICT (ok | failure | error); `status` is the
@@ -673,6 +829,7 @@ export async function traceCommand(command, args, version, run) {
         statusMessage,
         traceId: _activeTraceId,
         spanId: _activeSpanId,
+        identity,
       });
     } catch {
       // never let telemetry break the CLI