@lorekit/cli 1.2.0 → 1.4.0

package/README.md

@@ -297,6 +297,10 @@ active deny constraints.
 | `LOREKIT_MCP_URL` / `LOREKIT_ENDPOINT` | endpoint fallback |
 | `LOREKIT_TOKEN` | token fallback |
 | `NO_COLOR` | disable colored output |
+| `LOREKIT_TELEMETRY` | set to `0` / `off` / `false` to disable usage telemetry |
+| `DO_NOT_TRACK` | `1` also disables usage telemetry (cross-vendor standard) |
+| `LOREKIT_TELEMETRY_TOKEN` | bearer token for telemetry export (overrides the baked-in default) |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` | override the telemetry OTLP endpoint / headers |
 
 ## What the skill does
 
@@ -359,6 +363,24 @@ forever. This reduces manual validation to a single capture pass per tool.
 > the real Claude CLI accepts the wiring; for a true live check, install the
 > plugin and start one session per tool.
 
+## Usage telemetry
+
+The human-facing commands (`install`, `uninstall`, `doctor`, `migrate`) emit one
+OpenTelemetry span + one counter point per run so the maintainers can see which
+commands people use. It is zero-dependency (OTLP/JSON over `fetch`, no SDK) and
+deliberately narrow — it carries only the command name, a bounded set of boolean
+flags (`--global`, `--deep`, …), the CLI/runtime/OS identity, and the outcome.
+**No path, token, endpoint, repo, or scope is ever sent.** The `hook` and `mcp`
+commands are never instrumented.
+
+Opt out any time with `LOREKIT_TELEMETRY=0` (or `off` / `false` / `no`) or the
+cross-vendor `DO_NOT_TRACK=1`. Point it at your own collector with
+`OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS`, or set just the
+bearer via `LOREKIT_TELEMETRY_TOKEN`. Export is a no-op when no token is
+configured. The published package's default token is injected from a CI secret
+at release time and is never committed to git. See
+[docs/otel.md](../../docs/otel.md) for the attribute list and setup.
+
 ## Security note
 
 `install` writes your token into `.mcp.json`. Keep that file out of version

package/bin/lorekit.mjs

@@ -9,6 +9,7 @@ import { doctor } from '../src/doctor.mjs';
 import { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
 import { mcpServer } from '../src/mcp-server.mjs';
+import { traceCommand } from '../src/telemetry.mjs';
 
 // Read the version from package.json so it always matches the published
 // package — release-please bumps package.json, and this tracks it for free.
@@ -72,6 +73,8 @@ ${c.bold('Environment')}
   LOREKIT_MCP_URL / LOREKIT_ENDPOINT   endpoint fallback
   LOREKIT_TOKEN                        token fallback
   NO_COLOR                             disable colored output
+  LOREKIT_TELEMETRY / DO_NOT_TRACK     set to 0/off (or DO_NOT_TRACK=1) to opt
+                                       out of anonymous command-usage telemetry
 
 ${c.bold('Examples')}
   npx @lorekit/cli install --endpoint https://ref.supabase.co/functions/v1/mcp --token lk_rw_xxx
@@ -80,25 +83,164 @@ ${c.bold('Examples')}
   npx @lorekit/cli doctor --deep
   npx @lorekit/cli migrate --from .lore                 # preview a rename
   npx @lorekit/cli migrate --from .lore --to project --yes
+
+Run ${c.cyan('lorekit <command> --help')} for command-specific options.
 `;
 
+// Per-command help. Keyed by command; `lorekit <command> --help` prints the
+// focused entry instead of the full top-level HELP, so a user only sees the
+// flags that actually apply to what they're running.
+const COMMAND_HELP = {
+  install: `${c.bold('lorekit install')} — scaffold the skill, wire the MCP server, install the hooks
+
+${c.bold('Usage')}
+  npx @lorekit/cli install [options]
+
+Scaffolds the lorekit-memory skill, adds the LoreKit MCP server, and wires the
+deterministic hooks (lessons on SessionStart, a nudge on tool failure + at Stop).
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --project           Install into this project: .claude/skills + .mcp.json (default)
+      --global            Install for every project: ~/.claude/skills + ~/.claude.json
+  -e, --endpoint <url>    LoreKit MCP endpoint (else LOREKIT_MCP_URL)
+  -t, --token <token>     LoreKit token: lk_rw_* read+write, lk_ro_* read-only, lk_wo_* write-only
+      --no-hooks          Skip wiring the lifecycle hooks (skill stays model-invoked only)
+      --force             Overwrite existing skill files
+  -y, --yes               Non-interactive; never prompt (defaults to --project)
+
+${c.bold('Examples')}
+  npx @lorekit/cli install --endpoint https://ref.supabase.co/functions/v1/mcp --token lk_rw_xxx
+  npx @lorekit/cli install --global
+  npx @lorekit/cli install --no-hooks --yes
+`,
+  uninstall: `${c.bold('lorekit uninstall')} — reverse install for the chosen scope
+
+${c.bold('Usage')}
+  npx @lorekit/cli uninstall [options]
+
+Removes the lorekit-memory skill, the MCP server entry, and the lifecycle hooks.
+Surgical — other servers, hooks, and settings are left untouched.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --project           Uninstall from this project (default)
+      --global            Uninstall the global (~/.claude) setup
+  -y, --yes               Non-interactive; never prompt
+
+${c.bold('Examples')}
+  npx @lorekit/cli uninstall --global
+  npx @lorekit/cli uninstall --project --yes
+`,
+  doctor: `${c.bold('lorekit doctor')} — verify the skill install and the resolved memory backend
+
+${c.bold('Usage')}
+  npx @lorekit/cli doctor [options]
+
+Checks the node runtime, skill install, resolved memory mode, MCP connectivity,
+token, and scope.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --mode <mode>       Override the resolved mode: off | local | remote
+  -e, --endpoint <url>    Endpoint override (else .mcp.json / LOREKIT_MCP_URL)
+  -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
+
+${c.bold('Examples')}
+  npx @lorekit/cli doctor
+  npx @lorekit/cli doctor --deep
+  npx @lorekit/cli doctor --mode local
+`,
+  migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
+
+${c.bold('Usage')}
+  npx @lorekit/cli migrate --from <path> [options]
+
+Dry-run by default; pass --yes (or --apply) to write. Idempotent.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --from <path>       Source store to migrate from (required)
+      --to <tier>         Destination tier: home | project (default routes by scope)
+      --apply             Apply the migration (alias of --yes)
+  -y, --yes               Apply the migration; never prompt
+
+${c.bold('Examples')}
+  npx @lorekit/cli migrate --from .lore                 # preview a rename
+  npx @lorekit/cli migrate --from .lore --to project --yes
+`,
+  hook: `${c.bold('lorekit hook')} — hook engine for Claude Code / Cursor / Codex
+
+${c.bold('Usage')}
+  lorekit hook --adapter <claude|cursor|codex> --event <name> [--dir <path>]
+
+Machine-facing: reads the host's JSON on stdin and injects lessons or a
+retrospective nudge on stdout, always exiting 0. Wired into a plugin's hook
+config by \`lorekit install\` — not run by hand.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root
+      --adapter <name>    Host framework: claude | cursor | codex
+      --event <name>      Host hook event (else read from the stdin payload)
+`,
+  mcp: `${c.bold('lorekit mcp')} — local stdio MCP server
+
+${c.bold('Usage')}
+  lorekit mcp [--dir <path>]
+
+Machine-facing: exposes the memory.* tools backed by the resolved store (local
+.lorekit/ offline, or remote passthrough) over JSON-RPC on stdin/stdout, so
+.mcp.json can point at the CLI instead of mcp-remote. Not run by hand.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+`,
+};
+
+// Every long flag the CLI understands (after alias resolution). Passed to the
+// parser so an unrecognized flag is captured rather than silently ignored — a
+// typo like `--gloabl` should fail loudly, not quietly fall back to --project.
+const KNOWN_FLAGS = [
+  'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
+  'from', 'to', 'apply', 'yes', 'no-hooks', 'force', 'deep', 'adapter',
+  'event', 'help', 'version',
+];
+
+// Commands that write to disk / talk to the network on a human's behalf. These
+// reject unknown flags; the machine-facing `hook` / `mcp` do not (they must
+// never fail on a stray flag, and only ever receive flags we control).
+const HUMAN_COMMANDS = new Set(['install', 'uninstall', 'doctor', 'migrate']);
+
 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'],
+    known: KNOWN_FLAGS,
   });
 
+  const command = args._[0];
+
+  // Help is intercepted first — before the machine-facing hook/mcp dispatch — so
+  // `lorekit <command> --help` always documents the command (even hook/mcp)
+  // instead of blocking on stdin. Real hook/mcp invocations never pass --help.
+  if (args.help) {
+    log(command && COMMAND_HELP[command] ? COMMAND_HELP[command] : HELP);
+    return 0;
+  }
+
   // `hook` is machine-facing: it must never print help/errors to stdout
   // (that would corrupt the JSON the host parses). Handle it before the
-  // help/usage branch and always resolve to exit 0.
-  if (args._[0] === 'hook') {
+  // usage branch and always resolve to exit 0.
+  if (command === 'hook') {
     return hook(args);
   }
 
   // `mcp` is machine-facing too: only JSON-RPC frames may reach stdout, so it
-  // must bypass the help/usage branch. It serves stdio until the client closes.
-  if (args._[0] === 'mcp') {
+  // must bypass the usage branch. It serves stdio until the client closes.
+  if (command === 'mcp') {
     return mcpServer(args);
   }
 
@@ -107,22 +249,33 @@ async function main() {
     return 0;
   }
 
-  const command = args._[0];
-
-  if (args.help || !command) {
+  if (!command) {
     log(HELP);
-    return command ? 0 : args.help ? 0 : 1;
+    return 1;
+  }
+
+  // Reject unrecognized flags on human-facing commands with an actionable
+  // pointer, rather than silently ignoring a typo that would change behavior.
+  if (HUMAN_COMMANDS.has(command) && args._unknown.length > 0) {
+    const plural = args._unknown.length > 1 ? 's' : '';
+    err(`${c.red(`Unknown option${plural}:`)} ${args._unknown.join(', ')}`);
+    err(`Run ${c.cyan(`lorekit ${command} --help`)} to see valid options.`);
+    return 1;
   }
 
+  // Human-facing commands are wrapped so we can see which commands people run
+  // (one OTel span + counter per invocation). `hook` and `mcp` are handled
+  // above and stay uninstrumented — they are machine-facing, fire on every
+  // agent event, and must keep stdout to their host protocol.
   switch (command) {
     case 'install':
-      return install(args);
+      return traceCommand('install', args, VERSION, () => install(args));
     case 'uninstall':
-      return uninstall(args);
+      return traceCommand('uninstall', args, VERSION, () => uninstall(args));
     case 'doctor':
-      return doctor(args);
+      return traceCommand('doctor', args, VERSION, () => doctor(args));
     case 'migrate':
-      return migrate(args);
+      return traceCommand('migrate', args, VERSION, () => migrate(args));
     default:
       err(`${c.red('Unknown command:')} ${command}\n`);
       log(HELP);

package/package.json

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

package/src/telemetry-token.mjs

@@ -0,0 +1,17 @@
+// Build-time injection point for the Dash0 ingesting-only telemetry token.
+//
+// The committed value is EMPTY on purpose — default telemetry stays off in the
+// source tree and nothing secret is ever committed to git. The release workflow
+// (.github/workflows/release.yml → publish-cli) overwrites this file at publish
+// time from the LOREKIT_TELEMETRY_TOKEN secret via
+// scripts/inject-telemetry-token.mjs, so only the *published npm tarball*
+// carries the token.
+//
+// The token is public by design once published (anyone can unpack the tarball),
+// so it MUST be a Dash0 *ingesting-only* token — it can POST spans but cannot
+// read, query, or manage anything.
+//
+// At runtime this is only the lowest-priority source: an explicit
+// LOREKIT_TELEMETRY_TOKEN env var or OTEL_EXPORTER_OTLP_HEADERS still win (see
+// resolveTelemetryConfig in telemetry.mjs).
+export const TELEMETRY_TOKEN = '';

package/src/telemetry.mjs

@@ -0,0 +1,325 @@
+// LoreKit CLI — self-contained OpenTelemetry export for command usage.
+//
+// The CLI is strictly zero-dependency (see packages/cli/package.json), so this
+// mirrors the Edge Function's SDK-free approach (supabase/functions/_shared/
+// otel.ts): OTLP/JSON over the global fetch (Node 18+), no @opentelemetry/*
+// packages. One span + one counter data point per human-facing command
+// (install / doctor / migrate), fired to Dash0 so the maintainers can see
+// which commands people actually run.
+//
+// Privacy — this runs on end-users' machines, so it is deliberately narrow:
+//   • 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.
+//   • Disabled outright when no OTLP endpoint resolves.
+//
+// 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
+// and read it. It is NOT committed to git: the release workflow injects it into
+// telemetry-token.mjs at publish time from a secret (see that file). Standard
+// OTEL_EXPORTER_OTLP_* env vars — or LOREKIT_TELEMETRY_TOKEN — override it.
+
+import process from 'node:process';
+import { TELEMETRY_TOKEN } from './telemetry-token.mjs';
+
+// ── Baked-in defaults (public by design) ──────────────────────────────────────
+// The endpoint is a committed default; the token is injected at publish time
+// (empty in the source tree, so default export stays off until built/injected).
+const DEFAULT_ENDPOINT = 'https://ingress.us-east-1.aws.dash0.com';
+const DEFAULT_TOKEN = TELEMETRY_TOKEN; // injected from LOREKIT_TELEMETRY_TOKEN at publish
+const DEFAULT_DATASET = 'lorekit-cli';
+
+// Flags worth counting (e.g. how many installs are --global). Bounded on
+// purpose: only these booleans are ever attached, never free-form values.
+const FLAG_ATTRS = ['global', 'project', 'deep', 'yes', 'force', 'no-hooks'];
+
+const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disable', 'disabled']);
+
+// ── Config resolution ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve telemetry config from env + baked-in defaults.
+ * Returns { enabled: false } when disabled or unconfigured, else the endpoint
+ * and headers to export with.
+ */
+export function resolveTelemetryConfig(env = process.env) {
+  const optOut = env.LOREKIT_TELEMETRY;
+  if (optOut !== undefined && OFF_VALUES.has(String(optOut).trim().toLowerCase())) {
+    return { enabled: false };
+  }
+  // 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 };
+  }
+
+  const endpoint = (env.OTEL_EXPORTER_OTLP_ENDPOINT || DEFAULT_ENDPOINT || '')
+    .trim()
+    .replace(/\/+$/, '');
+  if (!endpoint) return { enabled: false };
+
+  const headers = {};
+  // Auth header priority (highest first):
+  //   1. OTEL_EXPORTER_OTLP_HEADERS — explicit comma list of key=value.
+  //   2. LOREKIT_TELEMETRY_TOKEN    — a bare bearer token via env (e.g. set as a
+  //      GitHub Actions secret to inject the token, or for local testing).
+  //   3. DEFAULT_TOKEN              — baked into the tarball at publish time.
+  const rawHeaders = env.OTEL_EXPORTER_OTLP_HEADERS;
+  const envToken = env.LOREKIT_TELEMETRY_TOKEN ? String(env.LOREKIT_TELEMETRY_TOKEN).trim() : '';
+  if (rawHeaders) {
+    for (const pair of String(rawHeaders).split(',')) {
+      const idx = pair.indexOf('=');
+      if (idx > 0) headers[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+    }
+  } else if (envToken) {
+    headers['Authorization'] = `Bearer ${envToken}`;
+  } else if (DEFAULT_TOKEN) {
+    headers['Authorization'] = `Bearer ${DEFAULT_TOKEN}`;
+  }
+
+  // With the baked-in default endpoint we need the baked-in token (or explicit
+  // 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 };
+  }
+
+  const dataset = env.DASH0_DATASET || DEFAULT_DATASET;
+  if (dataset) headers['Dash0-Dataset'] = dataset;
+
+  return { enabled: true, endpoint, headers };
+}
+
+// ── ID + value helpers (mirror _shared/otel.ts) ───────────────────────────────
+
+export function randHex(bytes) {
+  const b = new Uint8Array(bytes);
+  // `crypto` here is the WebCrypto global (globalThis.crypto), a stable global
+  // since Node 19 and also present on Node 18 — hence used unqualified rather
+  // than imported. (Do NOT `import crypto from 'node:crypto'`: that module's
+  // default export does not expose getRandomValues; only `webcrypto` does.)
+  crypto.getRandomValues(b);
+  return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+}
+
+function toOtlpValue(v) {
+  if (typeof v === 'number') return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+  if (typeof v === 'boolean') return { boolValue: v };
+  return { stringValue: String(v) };
+}
+
+// Map a flat attribute bag to the OTLP key/value list shape.
+function toOtlpAttributes(attributes) {
+  return Object.entries(attributes).map(([key, value]) => ({ key, value: toOtlpValue(value) }));
+}
+
+function resourceAttributes(version) {
+  return [
+    { key: 'service.name', value: { stringValue: 'lorekit-cli' } },
+    { key: 'service.namespace', value: { stringValue: 'lorekit' } },
+    { key: 'service.version', value: { stringValue: String(version) } },
+    { key: 'process.runtime.name', value: { stringValue: 'nodejs' } },
+    { key: 'process.runtime.version', value: { stringValue: process.versions.node } },
+    { key: 'os.type', value: { stringValue: process.platform } },
+    { key: 'host.arch', value: { stringValue: process.arch } },
+  ];
+}
+
+// ── Payload builders (pure — unit-tested) ─────────────────────────────────────
+
+/**
+ * Collect the bounded, non-PII attributes for a command invocation. Only the
+ * command name, allow-listed boolean flags, the outcome and the exit code.
+ */
+export function commandAttributes({ command, args = {}, outcome, exitCode }) {
+  const attrs = { 'lorekit.cli.command': command, 'lorekit.cli.outcome': outcome };
+  if (typeof exitCode === 'number') attrs['lorekit.cli.exit_code'] = exitCode;
+  for (const flag of FLAG_ATTRS) {
+    if (args[flag]) attrs[`lorekit.cli.flag.${flag}`] = true;
+  }
+  return attrs;
+}
+
+export function buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage }) {
+  return {
+    resourceSpans: [
+      {
+        resource: { attributes: resourceAttributes(version) },
+        scopeSpans: [
+          {
+            scope: { name: 'lorekit-cli', version: String(version) },
+            spans: [
+              {
+                traceId: randHex(16),
+                spanId: randHex(8),
+                name,
+                kind: 1, // INTERNAL
+                startTimeUnixNano: String(startMs * 1_000_000),
+                endTimeUnixNano: String(endMs * 1_000_000),
+                attributes: toOtlpAttributes(attributes),
+                status: {
+                  code: status === 'error' ? 2 : 1,
+                  ...(statusMessage ? { message: statusMessage } : {}),
+                },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+export function buildMetricsPayload({ version, attributes, startMs, endMs }) {
+  return {
+    resourceMetrics: [
+      {
+        resource: { attributes: resourceAttributes(version) },
+        scopeMetrics: [
+          {
+            scope: { name: 'lorekit-cli', version: String(version) },
+            metrics: [
+              {
+                name: 'lorekit.cli.invocations',
+                description: 'Count of LoreKit CLI command invocations',
+                unit: '1',
+                sum: {
+                  aggregationTemporality: 1, // DELTA — a single-shot CLI reports +1
+                  isMonotonic: true,
+                  dataPoints: [
+                    {
+                      asInt: '1',
+                      startTimeUnixNano: String(startMs * 1_000_000),
+                      timeUnixNano: String(endMs * 1_000_000),
+                      attributes: toOtlpAttributes(attributes),
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+async function post(url, headers, payload, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+  } catch {
+    // Telemetry is best-effort — never surface a network/abort error.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Export the trace + metric for one command. Best-effort and time-bounded so it
+ * 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 }, { timeoutMs = 1500 } = {}) {
+  if (!config || !config.enabled) return;
+  const trace = buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage });
+  const metric = buildMetricsPayload({ version, attributes, startMs, endMs });
+  await Promise.all([
+    post(`${config.endpoint}/v1/traces`, config.headers, trace, timeoutMs),
+    post(`${config.endpoint}/v1/metrics`, config.headers, metric, timeoutMs),
+  ]);
+}
+
+// ── Command wrapper ───────────────────────────────────────────────────────────
+
+/**
+ * A bounded, non-PII label for a thrown error: its `code` (e.g. `ENOENT`) or,
+ * failing that, its constructor name (e.g. `TypeError`). Never the free-form
+ * message, which can carry paths and other user data.
+ */
+function errorLabel(e) {
+  if (e && typeof e.code === 'string' && e.code) return e.code;
+  if (e && e.constructor && e.constructor.name) return e.constructor.name;
+  return 'Error';
+}
+
+/**
+ * Time a human-facing command, record its outcome, and export one span + one
+ * counter point. Returns the command's exit code unchanged. Telemetry failures
+ * are swallowed — the command result is never affected.
+ *
+ * @param {string} command  bounded: install | doctor | migrate
+ * @param {object} args     parsed CLI args (read for allow-listed flags only)
+ * @param {string} version  CLI version (from package.json)
+ * @param {() => Promise<number>} run  the command handler
+ */
+export async function traceCommand(command, args, version, run) {
+  let config;
+  try {
+    config = resolveTelemetryConfig();
+  } catch {
+    config = { enabled: false };
+  }
+
+  // Fast path: no export configured → run with zero overhead.
+  if (!config.enabled) return run();
+
+  const startMs = Date.now();
+  let exitCode = 0;
+  let status = 'ok';
+  let statusMessage;
+  try {
+    exitCode = await run();
+    if (typeof exitCode === 'number' && exitCode !== 0) {
+      status = 'error';
+      statusMessage = `exit ${exitCode}`;
+    }
+    return exitCode;
+  } catch (e) {
+    status = 'error';
+    // Record only a bounded, non-PII identifier — NEVER e.message. Node fs /
+    // network error messages embed absolute paths (e.g. "ENOENT: ... open
+    // '/home/me/proj/.mcp.json'"), which must never reach an exported span. The
+    // error status code already conveys failure.
+    statusMessage = errorLabel(e);
+    exitCode = 1;
+    throw e;
+  } finally {
+    // NOTE: on a thrown command error the `throw e` above is deferred until this
+    // finally settles, so a crash still awaits `exportInvocation` (up to
+    // timeoutMs, default 1500 ms) before propagating. This is intentional — the
+    // in-flight span would otherwise be dropped on exit. Do not shorten the
+    // timeout without weighing this "crash appears to hang ~1.5 s" trade-off.
+    try {
+      const attributes = commandAttributes({
+        command,
+        args,
+        outcome: status === 'error' ? 'error' : 'ok',
+        exitCode: typeof exitCode === 'number' ? exitCode : undefined,
+      });
+      await exportInvocation(config, {
+        version,
+        name: `lorekit.cli.${command}`,
+        attributes,
+        startMs,
+        endMs: Date.now(),
+        status,
+        statusMessage,
+      });
+    } catch {
+      // never let telemetry break the CLI
+    }
+  }
+}

package/src/util.mjs

@@ -119,8 +119,13 @@ export function select(question, options, { defaultIndex = 0 } = {}) {
 
 // Minimal flag parser: --key value, --key=value, -k value, and bare --flags.
 // `aliases` maps short → long; `booleans` lists flags that take no value.
-export function parseArgs(argv, { aliases = {}, booleans = [] } = {}) {
+// When `known` is a non-null list of long flag names, any flag whose resolved
+// name isn't in it is collected (as its original token) into `out._unknown` —
+// letting the caller reject typos like `--gloabl` instead of silently ignoring
+// them. `out._unknown` is only present when `known` was supplied.
+export function parseArgs(argv, { aliases = {}, booleans = [], known = null } = {}) {
   const out = { _: [] };
+  const unknown = [];
   for (let i = 0; i < argv.length; i++) {
     let token = argv[i];
     if (!token.startsWith('-')) {
@@ -135,6 +140,7 @@ export function parseArgs(argv, { aliases = {}, booleans = [] } = {}) {
     }
     let key = token.replace(/^-+/, '');
     if (aliases[key]) key = aliases[key];
+    if (known && !known.includes(key)) unknown.push(token);
     if (booleans.includes(key)) {
       out[key] = true;
       continue;
@@ -150,5 +156,6 @@ export function parseArgs(argv, { aliases = {}, booleans = [] } = {}) {
     }
     out[key] = value;
   }
+  if (known) out._unknown = unknown;
   return out;
 }