@lorekit/cli 1.29.3 → 1.30.1

package/bin/lorekit.mjs

@@ -125,6 +125,7 @@ ${c.bold('Options')}
       --no-hooks          Skip wiring the lifecycle hooks (install)
       --force             Overwrite existing skill files (install)
       --deep              Do a write→read→delete round-trip (doctor)
+      --telemetry         Verify the OTLP export credential works (doctor)
       --adapter <name>    Host framework for hook: claude | cursor | codex
       --event <name>      Host hook event (else read from stdin payload)
   -h, --help              Show this help
@@ -230,10 +231,15 @@ ${c.bold('Options')}
   -t, --token <token>     Token override (else .mcp.json / LOREKIT_TOKEN)
       --store <path>      Local project-tier store directory (default: .lorekit)
       --deep              Do a write→read→delete round-trip
+      --telemetry         Focused run: skip the other checks, POST a probe
+                          span to the OTLP endpoint, and FAIL if the Dash0
+                          ingesting token is missing or rejected. Without it,
+                          telemetry is reported as info only.
 
 ${c.bold('Examples')}
   npx @lorekit/cli doctor
   npx @lorekit/cli doctor --deep
+  npx @lorekit/cli doctor --telemetry
   npx @lorekit/cli doctor --mode local
 `,
   list: `${c.bold('lorekit list')} — list the memories that apply to the current directory ${c.dim('(alias: ls)')}
@@ -593,7 +599,7 @@ ${c.bold('Options')}
 const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
   'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'force', 'deep', 'adapter',
-  'event', 'json', 'scope', 'threshold', 'help', 'version',
+  'event', 'json', 'scope', 'threshold', 'help', 'version', 'telemetry',
   'value', 'tags', 'source-agent', 'trigger', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
   'link', 'base', 'q', 'owner', 'range', 'view', 'archived',
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
@@ -621,7 +627,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
-    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.29.3",
+  "version": "1.30.1",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/deeplink-pure.mjs

@@ -29,7 +29,15 @@ export const LORE_PARAM_DEFAULTS = {
   q: '', // string search query
   range: null, // { from, to } | null (DateRange, "YYYY-MM-DD")
   owner: 'all', // 'all' | 'personal' | { orgId }
-  tags: [], // string[] — label filter (AND across labels); [] means "no filter"
+  // Filter[] | null — the Explorer's multi-dimension filter bar (label / agent /
+  // trigger / repo / branch / pr). `null`, NOT `[]`, is the default on purpose:
+  // the app has to tell "the param is absent" from "the bar is explicitly
+  // empty", because an absent `filters` falls back to the legacy `tags`
+  // shorthand while an empty one deliberately does not. Encoding `[]` here
+  // would emit the param (it is not the default) and mean the opposite of
+  // "unfiltered".
+  filters: null,
+  tags: [], // string[] — legacy label filter (AND across labels); [] means "no filter". Still READ by the app, superseded by `filters`
   view: 'scope', // 'scope' | 'time'
   archived: false, // boolean
   lesson: null, // { scope, key } | null — opens the detail sheet
@@ -37,9 +45,9 @@ export const LORE_PARAM_DEFAULTS = {
 
 // A stable, readable param order (also makes URLs deterministic for tests).
 // Mirrors the `useUrlState` call order in `LoreExplorer.tsx` (+ the `lesson`
-// param last), so `tags` sits between `owner` and `view`. `scope` precedes
-// `lesson` so a lesson link reads `?scope=…&lesson=…`.
-const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'tags', 'view', 'archived', 'lesson'];
+// param last), so `filters` and `tags` sit between `owner` and `view`. `scope`
+// precedes `lesson` so a lesson link reads `?scope=…&lesson=…`.
+const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'filters', 'tags', 'view', 'archived', 'lesson'];
 
 // Strip trailing slashes from a base URL, falling back to the default when the
 // input is empty/absent. Pure.

package/src/doctor.mjs

@@ -17,6 +17,11 @@ import {
   readLorekitJson,
 } from './config.mjs';
 import { splitEndpoint } from './mcp.mjs';
+import {
+  resolveTelemetryConfig,
+  resolveTelemetryTokenSource,
+  probeTelemetryExport,
+} from './telemetry.mjs';
 import { deriveScope } from './scope.mjs';
 import { loadControl } from './control.mjs';
 import { createStore } from './store/index.mjs';
@@ -38,6 +43,19 @@ export async function doctor(args) {
   heading('LoreKit doctor');
   log(`  project: ${c.dim(root)}\n`);
 
+  // 0. `--telemetry` is a FOCUSED run, not a modifier on the full sweep.
+  //
+  // It exists to be a CI gate on one specific credential — the Dash0
+  // ingesting-only OTLP token — and a bare runner has no skills installed, no
+  // .mcp.json and no LoreKit API token, so a full sweep there fails for four
+  // unrelated reasons and tells you nothing about the one thing being gated.
+  // Returning early keeps the exit code a clean answer to a single question:
+  // "can this build still emit telemetry?"
+  if (args.telemetry) {
+    await checkTelemetryExport(args, root, record);
+    return summarize(failures, warnings, failedChecks, 'Telemetry export is working.');
+  }
+
   // 1. Runtime.
   const major = Number(process.versions.node.split('.')[0]);
   record(
@@ -123,6 +141,9 @@ export async function doctor(args) {
   // 4b. BYOD storage connectivity check.
   await checkBYODStorage(record);
 
+  // 4c. Dash0 telemetry export — is the CLI's own phone-home still working?
+  await checkTelemetryExport(args, root, record);
+
   // 5. Scope.
   const scope = deriveScope(root);
   if (scope.hasRemote) {
@@ -165,10 +186,18 @@ export async function doctor(args) {
     }
   }
 
-  // Summary.
+  return summarize(failures, warnings, failedChecks);
+}
+
+/**
+ * Print the Summary block and build doctor's `{ exitCode, ...extra }` return.
+ * Extracted so the focused `--telemetry` run and the full sweep end the same
+ * way — same summary line, same exit-code rule, same bounded telemetry extra.
+ */
+function summarize(failures, warnings, failedChecks, ready = 'LoreKit memory is ready.') {
   heading('Summary');
   if (failures === 0 && warnings === 0) {
-    log(`  ${c.green('All checks passed.')} LoreKit memory is ready.`);
+    log(`  ${c.green('All checks passed.')} ${ready}`);
   } else {
     log(
       `  ${failures ? c.red(failures + ' failed') : c.green('0 failed')}, ${
@@ -438,6 +467,102 @@ function detectDuplicateHooks(root) {
   return CLAUDE_HOOK_EVENTS.filter((event) => inProject.has(event) && inGlobal.has(event));
 }
 
+/**
+ * Is the CLI's own OpenTelemetry export still working?
+ *
+ * This is a DIFFERENT credential from the `token` / `authentication` checks
+ * above: those verify the LoreKit API token (`lk_rw_*`) that reads and writes
+ * memories. This one verifies the Dash0 ingesting-only OTLP token, which is
+ * baked into the published tarball at release time and is otherwise invisible —
+ * `exportInvocation` swallows every transport error by design, so a revoked
+ * token, a moved endpoint, or a release that published with the
+ * `LOREKIT_TELEMETRY_TOKEN` secret unset all look identical from the outside:
+ * silence. Nothing in CI noticed, because nothing was looking.
+ *
+ * Two tiers, so the default `doctor` run stays offline and side-effect-free:
+ *   • always — report whether export is ON and where the credential came from,
+ *     as `info`. Never a failure: end users legitimately opt out, and a user's
+ *     machine having no phone-home is not a broken install.
+ *   • `--telemetry` — actually POST a probe span and assert the endpoint
+ *     accepted it. Here a dead export IS a failure; that flag is what CI passes.
+ */
+async function checkTelemetryExport(args, root, record) {
+  const required = Boolean(args.telemetry);
+
+  let config;
+  try {
+    // Read `.lorekit.json` from the SAME root every other check uses. Left to
+    // its default, `resolveTelemetryConfig` reads it from `process.cwd()`, so a
+    // `telemetry.disabled` in the shell's directory would decide the verdict for
+    // an unrelated `--dir`.
+    config = resolveTelemetryConfig(process.env, readLorekitJson(root));
+  } catch {
+    config = { enabled: false, reason: 'error' };
+  }
+  const source = resolveTelemetryTokenSource();
+
+  if (!config.enabled) {
+    // Report the reason `resolveTelemetryConfig` actually returned. Deriving it
+    // from the token source instead misreports every case where a credential
+    // variable is set but unusable — e.g. an OTEL_EXPORTER_OTLP_HEADERS that
+    // parses to zero headers, which is a broken credential, not an opt-out.
+    const detail =
+      config.reason === 'opted-out'
+        ? 'export off — opted out via LOREKIT_TELEMETRY / DO_NOT_TRACK / `telemetry.disabled` in .lorekit.json'
+        : config.reason === 'no-endpoint'
+          ? 'export off — no OTLP endpoint resolved. Published tarballs get one baked in at release; ' +
+            'set OTEL_EXPORTER_OTLP_ENDPOINT to override.'
+          : config.reason === 'error'
+            ? 'export off — the telemetry config could not be resolved'
+            : 'export off — no OTLP credential resolved. Published tarballs get one injected at release; ' +
+              'set LOREKIT_TELEMETRY_TOKEN (or OTEL_EXPORTER_OTLP_HEADERS) to override.';
+    record(required ? 'fail' : 'info', 'telemetry', detail);
+    return;
+  }
+
+  record('info', 'telemetry', `export on → ${config.endpoint} ${c.dim(`(credential from ${source})`)}`);
+
+  // The probe writes a real span to a real backend — only on explicit request.
+  if (!required) return;
+
+  const probe = await probeTelemetryExport(config, { version: cliVersion(), timeoutMs: 5000 });
+
+  if (probe.networkError) {
+    record('fail', 'telemetry export', `could not reach ${config.endpoint} — ${probe.networkError}`);
+  } else if (probe.unauthorized) {
+    record(
+      'fail',
+      'telemetry export',
+      `probe span REJECTED (HTTP ${probe.httpStatus}) — the OTLP token is revoked, expired, or was never valid. ` +
+        'Mint a new Dash0 ingesting-only token and update the LOREKIT_TELEMETRY_TOKEN secret.',
+    );
+  } else if (probe.rejectedSpans) {
+    // A 2xx that dropped the span. Reporting the bare status here would read as
+    // a contradiction ("rejected (HTTP 200)"), so name the partial-success
+    // envelope the collector actually answered with.
+    record(
+      'fail',
+      'telemetry export',
+      `probe span REJECTED by the collector (HTTP ${probe.httpStatus}, partialSuccess.rejectedSpans=${probe.rejectedSpans}) — ` +
+        'the endpoint answered success but did not ingest the span' +
+        (probe.rejectionMessage ? `: ${probe.rejectionMessage}` : '.'),
+    );
+  } else if (probe.ok) {
+    record('pass', 'telemetry export', `probe span accepted (HTTP ${probe.httpStatus}) — the token can ingest`);
+  } else {
+    record('fail', 'telemetry export', `probe span rejected (HTTP ${probe.httpStatus})`);
+  }
+}
+
+/** The running CLI version, for stamping the telemetry probe span. */
+function cliVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
 async function checkBYODStorage(record) {
   const storageUrl = process.env['LOREKIT_STORAGE_URL'];
   const storageAnonKey = process.env['LOREKIT_STORAGE_ANON_KEY'];

package/src/telemetry.mjs

@@ -73,33 +73,42 @@ export function getActiveTraceparent() {
 
 /**
  * Resolve telemetry config from env + baked-in defaults + .lorekit.json.
- * Returns { enabled: false } when disabled or unconfigured, else the endpoint
- * and headers to export with.
+ * Returns { enabled: false, reason } when disabled or unconfigured, else the
+ * endpoint and headers to export with.
+ *
+ * `reason` names WHY export is off, because the three causes are not
+ * interchangeable to a user and cannot be re-derived from the outside:
+ *   • `opted-out`     — LOREKIT_TELEMETRY / DO_NOT_TRACK / `telemetry.disabled`.
+ *   • `no-endpoint`   — nothing to export to.
+ *   • `no-credential` — an endpoint, but no usable auth header. Note that an
+ *     OTEL_EXPORTER_OTLP_HEADERS that parses to zero headers lands here, which
+ *     is exactly why a caller must not infer the cause from the token source:
+ *     the variable is set, yet no credential resolved.
  * @param {object} [env]  defaults to process.env
  * @param {object} [repoConfig]  pre-loaded .lorekit.json (optional; read from cwd if absent)
  */
 export function resolveTelemetryConfig(env = process.env, repoConfig) {
   const optOut = env.LOREKIT_TELEMETRY;
   if (optOut !== undefined && OFF_VALUES.has(String(optOut).trim().toLowerCase())) {
-    return { enabled: false };
+    return { enabled: false, reason: 'opted-out' };
   }
   // DNT spec designates exactly `1` as the opt-out signal (consoledonottrack.com).
   // Match it precisely — a stray `DO_NOT_TRACK=false` should NOT disable export
   // (use LOREKIT_TELEMETRY for the loose app-specific opt-out values).
   if (env.DO_NOT_TRACK && String(env.DO_NOT_TRACK).trim() === '1') {
-    return { enabled: false };
+    return { enabled: false, reason: 'opted-out' };
   }
   // `telemetry.disabled: true` in .lorekit.json — team-level opt-out committed
   // to the repo. Checked after env overrides (env always wins).
   const cfg = repoConfig !== undefined ? repoConfig : readLorekitJson(process.cwd());
   if (cfg['telemetry.disabled'] === true) {
-    return { enabled: false };
+    return { enabled: false, reason: 'opted-out' };
   }
 
   const endpoint = (env.OTEL_EXPORTER_OTLP_ENDPOINT || DEFAULT_ENDPOINT || '')
     .trim()
     .replace(/\/+$/, '');
-  if (!endpoint) return { enabled: false };
+  if (!endpoint) return { enabled: false, reason: 'no-endpoint' };
 
   const headers = {};
   // Auth header priority (highest first):
@@ -124,7 +133,7 @@ export function resolveTelemetryConfig(env = process.env, repoConfig) {
   // headers) to authenticate — no point exporting an unauthenticated request.
   const usingDefaultEndpoint = !env.OTEL_EXPORTER_OTLP_ENDPOINT;
   if (usingDefaultEndpoint && Object.keys(headers).length === 0) {
-    return { enabled: false };
+    return { enabled: false, reason: 'no-credential' };
   }
 
   // Dataset routing, highest precedence first: an explicit `Dash0-Dataset`
@@ -142,6 +151,21 @@ export function resolveTelemetryConfig(env = process.env, repoConfig) {
   return { enabled: true, endpoint, headers };
 }
 
+/**
+ * Which source supplied the OTLP credential, for `doctor` to report. Mirrors
+ * the priority order in `resolveTelemetryConfig` above — keep the two in step.
+ * Returns a human-readable label, or `'none'` when nothing resolved.
+ * @param {object} [env]  defaults to process.env
+ */
+export function resolveTelemetryTokenSource(env = process.env) {
+  if (env.OTEL_EXPORTER_OTLP_HEADERS) return 'OTEL_EXPORTER_OTLP_HEADERS';
+  if (env.LOREKIT_TELEMETRY_TOKEN && String(env.LOREKIT_TELEMETRY_TOKEN).trim()) {
+    return 'LOREKIT_TELEMETRY_TOKEN';
+  }
+  if (DEFAULT_TOKEN) return 'the token baked in at publish time';
+  return 'none';
+}
+
 // ── ID + value helpers (mirror _shared/otel.ts) ───────────────────────────────
 
 export function randHex(bytes) {
@@ -333,6 +357,101 @@ export async function exportInvocation(config, { version, name, attributes, star
   ]);
 }
 
+/**
+ * Send ONE synthetic span to the configured OTLP endpoint and report what the
+ * collector said about it.
+ *
+ * Deliberately not routed through `post()`: command telemetry swallows every
+ * error on purpose (it must never disturb the CLI), which is exactly the
+ * behaviour that let export die silently. `doctor --telemetry` needs the
+ * opposite — the HTTP status, so it can tell "accepted" from "token rejected"
+ * from "endpoint unreachable".
+ *
+ * The probe span is tagged `lorekit.telemetry.probe=true` so it is trivially
+ * filtered out of usage dashboards, and carries the same bounded, non-PII
+ * attribute set as a real command span.
+ *
+ * `ok` means the span was INGESTED, not merely that the POST returned 2xx —
+ * OTLP/HTTP reports a dropped span as a 2xx carrying
+ * `partialSuccess.rejectedSpans`, so a status-only verdict would report a
+ * rejected probe as accepted. That false green is the exact failure this probe
+ * exists to catch, and the probe sends exactly one span, so any non-zero
+ * `rejectedSpans` means the thing we sent was dropped.
+ *
+ * @returns {Promise<{skipped?: boolean, ok?: boolean, unauthorized?: boolean, httpStatus?: number, rejectedSpans?: number, rejectionMessage?: string, networkError?: string}>}
+ */
+export async function probeTelemetryExport(config, { version = '0.0.0', timeoutMs = 5000 } = {}) {
+  if (!config || !config.enabled) return { skipped: true };
+
+  const now = Date.now();
+  const payload = buildTracePayload({
+    version,
+    name: 'lorekit.cli.doctor.telemetry_probe',
+    attributes: {
+      'lorekit.cli.command': 'doctor',
+      'lorekit.cli.outcome': 'ok',
+      'lorekit.telemetry.probe': true,
+    },
+    startMs: now,
+    endMs: now,
+    status: 'ok',
+  });
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${config.endpoint}/v1/traces`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...config.headers },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    const httpStatus = res.status;
+    const accepted = httpStatus >= 200 && httpStatus < 300;
+
+    // A 2xx only means the collector took the REQUEST. Read the OTLP
+    // partial-success envelope to find out whether it took the SPAN.
+    // Deliberately one-directional: only a positively parsed, non-zero
+    // `rejectedSpans` downgrades the verdict. An empty, non-JSON, or
+    // unreadable body leaves the status-based answer alone, so a terse but
+    // healthy collector can never be turned into a false red — and the read is
+    // wrapped in its own try so a failure here cannot erase an HTTP status we
+    // already have by falling into the transport `catch` below.
+    let rejectedSpans = 0;
+    let rejectionMessage;
+    if (accepted) {
+      try {
+        const partial = JSON.parse(await res.text())?.['partialSuccess'];
+        const count = Number(partial?.['rejectedSpans'] ?? 0);
+        if (Number.isFinite(count) && count > 0) {
+          rejectedSpans = count;
+          const message = partial?.['errorMessage'];
+          // Collector-controlled free text — bounded before it reaches output.
+          if (typeof message === 'string' && message) rejectionMessage = message.slice(0, 200);
+        }
+      } catch {
+        // Unreadable or non-OTLP body — fall back to the status alone.
+      }
+    }
+
+    return {
+      httpStatus,
+      ok: accepted && rejectedSpans === 0,
+      unauthorized: httpStatus === 401 || httpStatus === 403,
+      ...(rejectedSpans > 0 ? { rejectedSpans } : {}),
+      ...(rejectionMessage ? { rejectionMessage } : {}),
+    };
+  } catch (e) {
+    const networkError =
+      e && e.name === 'AbortError'
+        ? `no response within ${timeoutMs}ms`
+        : (e && e.message) || String(e);
+    return { networkError };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // ── Command wrapper ───────────────────────────────────────────────────────────
 
 /**
@@ -364,6 +483,11 @@ function normalizeExitCode(result) {
  * counter point. Returns the command's exit code unchanged. Telemetry failures
  * are swallowed — the command result is never affected.
  *
+ * The span carries an ERROR status only when the command CRASHED. A command
+ * that ran to completion and exited non-zero (a failing `doctor` check, a
+ * `lint` finding) reports `lorekit.cli.outcome=failure` on a span the exporter
+ * emits as STATUS_CODE_OK — never ERROR.
+ *
  * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | scopes | diff | tree | lint | dedupe | link | migrate
  * @param {object} args     parsed CLI args (read for allow-listed flags only)
  * @param {string} version  CLI version (from package.json)
@@ -406,6 +530,10 @@ export async function traceCommand(command, args, version, run) {
 
   const startMs = Date.now();
   let exitCode = 0;
+  // `outcome` is the command's VERDICT (ok | failure | error); `status` is the
+  // SPAN status, and only a crash sets it to error. See the note above the
+  // non-zero-exit branch below.
+  let outcome = 'ok';
   let status = 'ok';
   let statusMessage;
   let extraAttrs = {};
@@ -424,11 +552,22 @@ export async function traceCommand(command, args, version, run) {
       }
     }
     if (typeof exitCode === 'number' && exitCode !== 0) {
-      status = 'error';
-      statusMessage = `exit ${exitCode}`;
+      // A non-zero exit is a REPORTED VERDICT, not a fault: `doctor` exits 1
+      // because a check it ran came back failing, and `lint` exits 1 because it
+      // found what it was asked to look for. Both commands did their job. Only
+      // a crash (the catch below) is an error, so `status` stays `'ok'` here —
+      // which `buildTracePayload` emits as STATUS_CODE_OK (1), the same status
+      // a zero-exit run gets — and the verdict is carried by
+      // `lorekit.cli.outcome=failure` +
+      // `lorekit.cli.exit_code` — which keeps the CLI's error rate a measure of
+      // the CLI being broken rather than of the user's environment being
+      // unhealthy. Query the failure verdicts on those attributes, never on the
+      // span status.
+      outcome = 'failure';
     }
     return exitCode;
   } catch (e) {
+    outcome = 'error';
     status = 'error';
     // Record only a bounded, non-PII identifier — NEVER e.message. Node fs /
     // network error messages embed absolute paths (e.g. "ENOENT: ... open
@@ -447,7 +586,7 @@ export async function traceCommand(command, args, version, run) {
       const attributes = commandAttributes({
         command,
         args,
-        outcome: status === 'error' ? 'error' : 'ok',
+        outcome,
         exitCode: typeof exitCode === 'number' ? exitCode : undefined,
         extraAttrs,
       });