@lorekit/cli 1.6.0 → 1.7.1

package/package.json

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

package/src/doctor.mjs

@@ -24,8 +24,9 @@ export async function doctor(args) {
   const root = resolveProjectRoot(args.dir);
   let failures = 0;
   let warnings = 0;
+  const failedChecks = [];
   const record = (kind, label, detail) => {
-    if (kind === 'fail') failures++;
+    if (kind === 'fail') { failures++; failedChecks.push(label); }
     if (kind === 'warn') warnings++;
     status(kind, label, detail);
   };
@@ -91,7 +92,8 @@ export async function doctor(args) {
       }.`,
     );
   }
-  return failures === 0 ? 0 : 1;
+  const exitCode = failures === 0 ? 0 : 1;
+  return { exitCode, 'lorekit.cli.doctor.failed_checks': failedChecks };
 }
 
 // Merge doctor's --endpoint / --token flags into the env the resolver reads, so

package/src/telemetry.mjs

@@ -135,12 +135,13 @@ function resourceAttributes(version) {
  * 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 }) {
+export function commandAttributes({ command, args = {}, outcome, exitCode, extraAttrs = {} }) {
   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;
   }
+  Object.assign(attrs, extraAttrs);
   return attrs;
 }
 
@@ -255,6 +256,19 @@ function errorLabel(e) {
   return 'Error';
 }
 
+/**
+ * Coerce a command handler's return value to a numeric exit code. Commands may
+ * resolve to a bare number, or to an { exitCode, ...extra } object (which lets
+ * them surface bounded diagnostic fields for telemetry); anything else → 0.
+ * Single source of truth for exit-code normalization on both traceCommand paths.
+ * @param {unknown} result
+ * @returns {number}
+ */
+function normalizeExitCode(result) {
+  if (result !== null && typeof result === 'object') return result.exitCode ?? 0;
+  return result ?? 0;
+}
+
 /**
  * Time a human-facing command, record its outcome, and export one span + one
  * counter point. Returns the command's exit code unchanged. Telemetry failures
@@ -273,15 +287,33 @@ export async function traceCommand(command, args, version, run) {
     config = { enabled: false };
   }
 
-  // Fast path: no export configured → run with zero overhead.
-  if (!config.enabled) return run();
+  // Fast path: no export configured → run with zero telemetry overhead. Still
+  // normalize the result to a numeric exit code: commands may resolve to an
+  // { exitCode, ...extra } object (e.g. `doctor`), and only the instrumented
+  // path below unwraps it. Returning `run()` raw would leak that object all the
+  // way to `process.exit(obj)` in the bin entry → ERR_INVALID_ARG_TYPE crash
+  // (exit 1) for every user without an OTLP endpoint configured.
+  if (!config.enabled) return normalizeExitCode(await run());
 
   const startMs = Date.now();
   let exitCode = 0;
   let status = 'ok';
   let statusMessage;
+  let extraAttrs = {};
   try {
-    exitCode = await run();
+    const result = await run();
+    // Commands may return either a plain exit code (number) or an object with
+    // { exitCode, ...extra } — the latter lets commands surface bounded,
+    // non-PII diagnostic fields (e.g. which checks failed in `doctor`).
+    exitCode = normalizeExitCode(result);
+    if (result !== null && typeof result === 'object') {
+      const { exitCode: _ec, ...rest } = result;
+      // Flatten any array-valued extras to a comma-joined string so they fit
+      // the flat attribute bag shape (OTLP stringValue).
+      for (const [k, v] of Object.entries(rest)) {
+        extraAttrs[k] = Array.isArray(v) ? v.join(',') : v;
+      }
+    }
     if (typeof exitCode === 'number' && exitCode !== 0) {
       status = 'error';
       statusMessage = `exit ${exitCode}`;
@@ -308,6 +340,7 @@ export async function traceCommand(command, args, version, run) {
         args,
         outcome: status === 'error' ? 'error' : 'ok',
         exitCode: typeof exitCode === 'number' ? exitCode : undefined,
+        extraAttrs,
       });
       await exportInvocation(config, {
         version,