@lorekit/cli 1.21.0 → 1.22.0

package/README.md

@@ -224,13 +224,13 @@ stored by basename only) — so every scope is reconstructed verbatim. Lessons
 present in both tiers are counted once (project shadows home, the same merge
 `list` uses); archived lessons are excluded.
 
-**Remote enumeration is not possible, and `scopes` says so honestly.** The
-hosted MCP surface exposes no "list all scopes" tool — every read tool
-(`memory.list` / `memory.search` / `memory.read`) *requires* a scope — so a
-remote inventory can't be built. The Remote section is therefore always a short
-note (never a faked listing), degrading gracefully at exit 0, the same way
-`stats` omits a cap-usage figure. `--endpoint` / `--token` / `--store` behave as
-in `list`.
+**Remote enumeration is exact too.** `RemoteStore.listScopes()` calls
+`GET /memories/scopes`, which aggregates one `{ scope, count }` row per scope in
+Postgres (never a truncatable `select('scope')` plus a client-side dedupe), so
+the Remote section is a real inventory rendered through the same helpers as the
+Offline one. A denied, unconfigured, unreachable, or erroring remote degrades to
+a short, accurate note (network error / HTTP status — never a faked listing) at
+exit 0. `--endpoint` / `--token` / `--store` behave as in `list`.
 
 ### `lorekit diff`
 

package/bin/lorekit.mjs

@@ -348,9 +348,10 @@ is a full inventory — it surfaces scopes anywhere in the store, regardless of
 current directory.
 
 Offline counts are exact: each scope is read from the memory files' frontmatter,
-not reverse-mapped from the directory layout. The Remote section is always a
-short note: the hosted MCP surface has no "list all scopes" tool (every read tool
-requires a scope), so a remote inventory isn't possible — never an error (exit 0).
+not reverse-mapped from the directory layout. Remote counts are exact too — they
+come from \`GET /memories/scopes\`, which aggregates one row per scope server-side.
+A denied, unconfigured, or unreachable remote degrades to a short, accurate note
+rather than an error (exit 0).
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)

package/package.json

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

package/src/mcp.mjs

@@ -27,7 +27,11 @@ export function buildRemoteUrl(endpoint, token) {
 let idCounter = 0;
 
 // Returns { ok, httpStatus, result, error, networkError }.
-export async function mcpCall(endpoint, token, method, params = {}, { timeoutMs = 10000 } = {}) {
+//
+// `opts.traceparent` is an optional W3C traceparent header value (see
+// src/telemetry.mjs `getActiveTraceparent`); when present it is forwarded so
+// the server-side span joins the CLI's trace — same idiom as restFetch.
+export async function mcpCall(endpoint, token, method, params = {}, { timeoutMs = 10000, traceparent } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -40,6 +44,7 @@ export async function mcpCall(endpoint, token, method, params = {}, { timeoutMs
         'content-type': 'application/json',
         accept: 'application/json, text/event-stream',
         ...(token ? { authorization: `Bearer ${token}` } : {}),
+        ...(traceparent ? { traceparent } : {}),
       },
       body: JSON.stringify({ jsonrpc: '2.0', id: ++idCounter, method, params }),
       signal: controller.signal,

package/src/scopes.mjs

@@ -13,10 +13,12 @@
 // mapping the on-disk directory layout, which is lossy for `project::{name}`
 // (stored by basename only) — so every scope is reconstructed exactly.
 //
-// Remote enumeration is NOT possible: the hosted MCP surface exposes no "list
-// all scopes" tool — every read tool (memory.list / search / read) REQUIRES a
-// scope — so the Remote section is always an honest note (never faked), the same
-// way `stats` omits a cap-usage figure. It still degrades gracefully at exit 0.
+// Remote enumeration is EXACT too: `RemoteStore.listScopes()` calls
+// `GET /memories/scopes`, which aggregates one row per scope in Postgres (never
+// a truncatable `select('scope')` + client-side dedupe), so both sections are
+// real inventories rendered through the same pure helpers. A denied,
+// unconfigured, unreachable, or erroring remote still degrades to a short,
+// accurate note at exit 0 — never a throw.
 //
 // Graceful, read-only, human-facing (the bin wraps it in `traceCommand`).
 // `LOREKIT_DENY` suppresses a section; `--scope <s>` filters the inventory to
@@ -26,15 +28,9 @@ import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { summarizeScopeInventory, filterScopeInventory } from './lessons-view.mjs';
+import { summarizeScopeInventory, filterScopeInventory, describeError } from './lessons-view.mjs';
 import { log, heading, status, c } from './util.mjs';
 
-// The honest note the Remote section shows when it isn't denied/unconfigured:
-// the hosted MCP surface simply can't enumerate scopes. Exported so tests can
-// assert the exact wording rather than a fragile substring.
-export const REMOTE_SCOPES_UNSUPPORTED =
-  'remote scope enumeration is not supported by the hosted MCP surface (memory.list requires a scope)';
-
 export async function scopes(args) {
   const root = resolveProjectRoot(args.dir);
   const env = { ...process.env };
@@ -63,16 +59,21 @@ export async function scopes(args) {
     offlineSection = { available: true, ...summarizeScopeInventory(inventory) };
   }
 
-  // Remote: never enumerable. A deny note, an unconfigured note, or the honest
-  // "not supported" note — all graceful (exit 0). Order matches the other
-  // commands' precedence: deny first, then connectivity, then the capability.
+  // Remote: the hosted enumeration, via `GET /memories/scopes`. Precedence is
+  // unchanged from the other read commands — deny first, then connectivity, then
+  // the call itself. A failed call degrades to the same bounded, non-PII
+  // `describeError` note a failed `list()` gets (network error / HTTP status),
+  // never a throw and never a faked inventory.
   let remoteSection;
   if (remoteDenied) {
     remoteSection = { available: false, reason: `disabled by deny constraint (${remoteDenied.source})` };
   } else if (!remote.usable()) {
     remoteSection = { available: false, reason: remoteUnavailableReason(connection) };
   } else {
-    remoteSection = { available: false, reason: REMOTE_SCOPES_UNSUPPORTED };
+    const res = await remote.listScopes();
+    remoteSection = res.ok
+      ? { available: true, ...summarizeScopeInventory(filterScopeInventory(res.scopes, filter)) }
+      : { available: false, reason: describeError(res) };
   }
 
   if (args.json) {
@@ -89,15 +90,17 @@ export async function scopes(args) {
     log('');
   }
 
-  // Bounded, non-PII telemetry extras (counts + a boolean) — never a scope
-  // string, path, or token. `remote_available` is always false: the surface
-  // can't enumerate, and saying so is the honest signal.
+  // Bounded, non-PII telemetry extras (counts + booleans) — never a scope
+  // string, path, or token. `remote_available` now reflects whether the hosted
+  // enumeration actually answered; the remote counts mirror the offline pair.
   return {
     exitCode: 0,
     'lorekit.cli.scopes.offline_scope_count': offlineSection.available ? offlineSection.scopes.length : 0,
     'lorekit.cli.scopes.offline_total': offlineSection.available ? offlineSection.total : 0,
     'lorekit.cli.scopes.filtered': Boolean(filter),
-    'lorekit.cli.scopes.remote_available': false,
+    'lorekit.cli.scopes.remote_scope_count': remoteSection.available ? remoteSection.scopes.length : 0,
+    'lorekit.cli.scopes.remote_total': remoteSection.available ? remoteSection.total : 0,
+    'lorekit.cli.scopes.remote_available': remoteSection.available,
   };
 }
 

package/src/store/remote.mjs

@@ -1,9 +1,12 @@
 // Remote store: wraps the LoreKit REST API `memory.*` endpoints behind the
-// common store contract. Memory operations use the REST API for lower overhead
-// and W3C traceparent propagation. Org operations remain on MCP because org
-// RPCs require a Supabase JWT session (auth.uid() via SECURITY DEFINER
-// functions), which is incompatible with the lk_* api_key tokens that CLI
-// users have. Zero-dependency.
+// common store contract. EVERY memory operation goes over REST — list, search,
+// read, write, delete (soft-archive AND `?force=true` hard-delete) and the
+// store-wide `listScopes()` enumeration — for lower overhead and W3C
+// traceparent propagation. MCP remains ONLY for the four `org.*` calls and the
+// `ping` fallback: org RPCs require a Supabase JWT session (they resolve the
+// actor via auth.uid() inside SECURITY DEFINER functions), which is
+// incompatible with the lk_* api_key tokens that CLI users have.
+// Zero-dependency.
 import { mcpCall, restFetch, mcpToRestBase } from '../mcp.mjs';
 import { getActiveTraceparent } from '../telemetry.mjs';
 
@@ -39,7 +42,7 @@ class RemoteStore {
 
   async _mcp(name, args) {
     if (!this.usable()) return { ok: false, unusable: true };
-    return mcpCall(this.endpoint, this.token, 'tools/call', { name, arguments: args });
+    return mcpCall(this.endpoint, this.token, 'tools/call', { name, arguments: args }, { traceparent: this._tp() });
   }
 
   _mcpEntries(res) {
@@ -79,6 +82,8 @@ class RemoteStore {
     const p = new URLSearchParams();
     if (scope) p.set('scope', scope);
     if (key) p.set('key', key);
+    // scope+key is unique, so one row is all there can be — don't pull the default page of 50.
+    p.set('limit', '1');
     const res = await this._rest(`/memories?${p}`);
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
     const entries = res.data?.entries ?? [];
@@ -99,14 +104,12 @@ class RemoteStore {
     return { ok: res.ok, error: res.error, networkError: res.networkError };
   }
 
+  // Natural-key DELETE. Without `force` the server soft-archives (stamps
+  // `archived_at`); `?force=true` hard-deletes the row outright — both forms of
+  // the same REST route (supabase/functions/memories/handlers/remove.ts).
   async delete({ scope, key, force = false } = {}) {
-    if (force) {
-      // Hard-delete requires MCP — REST only supports soft-archive (archived_at)
-      const res = await this._mcp('memory.delete', { scope, key, force: true });
-      return { ok: res.ok, error: res.error, networkError: res.networkError };
-    }
-    // Soft-archive via natural-key REST endpoint
     const p = new URLSearchParams({ scope, key });
+    if (force) p.set('force', 'true');
     const res = await this._rest(`/memories?${p}`, { method: 'DELETE' });
     return { ok: res.ok, error: res.error, networkError: res.networkError };
   }
@@ -155,12 +158,22 @@ class RemoteStore {
     return { ok: true, ...(payload ?? {}) };
   }
 
-  // Store-wide scope enumeration is NOT possible against the hosted REST surface:
-  // every read tool requires a scope, and there is no "list all scopes" endpoint.
-  // Signal that honestly so the `scopes` command shows a clear note rather than
-  // faking an inventory.
+  // Store-wide scope enumeration — every distinct scope the caller can see with
+  // its count of active (non-archived, non-expired) memories. `GET
+  // /memories/scopes` aggregates in Postgres, so the answer is exact at any size
+  // (see supabase/functions/memories/handlers/scopes.ts).
+  //
+  // The `scopes` array is the SAME `[{ scope, count }]` inventory shape
+  // `LocalStore.listScopes()` returns, so `scopes.mjs` feeds both through the
+  // same pure `filterScopeInventory`/`summarizeScopeInventory` helpers. Ordering
+  // is not relied upon (the server sorts by scope asc; the view re-sorts by
+  // scope type). Failures use this store's standard `{ ok:false, error,
+  // networkError }` envelope so the caller can degrade gracefully.
   async listScopes() {
-    return { ok: false, unsupported: true };
+    const res = await this._rest('/memories/scopes');
+    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError, unusable: res.unusable };
+    const scopes = Array.isArray(res.data?.scopes) ? res.data.scopes : [];
+    return { ok: true, scopes: scopes.map((s) => ({ scope: s.scope, count: Number(s.count) || 0 })) };
   }
 
   // Connectivity probe for doctor — a transport check, not a memory op.
@@ -171,11 +184,15 @@ class RemoteStore {
       ? `${this.restBase.replace(/\/functions\/v1$/, '')}/functions/v1/health`
       : null;
     if (healthUrl) {
+      const tp = this._tp();
       try {
-        const res = await fetch(healthUrl, { signal: AbortSignal.timeout(5000) });
+        const res = await fetch(healthUrl, {
+          signal: AbortSignal.timeout(5000),
+          ...(tp ? { headers: { traceparent: tp } } : {}),
+        });
         return { ok: res.ok, httpStatus: res.status };
       } catch (e) { return { ok: false, networkError: String(e?.message ?? e) }; }
     }
-    return mcpCall(this.endpoint, this.token, 'tools/list', {});
+    return mcpCall(this.endpoint, this.token, 'tools/list', {}, { traceparent: this._tp() });
   }
 }

package/src/telemetry.mjs

@@ -41,19 +41,30 @@ const FLAG_ATTRS = ['global', 'project', 'deep', 'yes', 'force', 'no-hooks', 'js
 const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disable', 'disabled']);
 
 // ── Active trace context (for traceparent propagation to REST calls) ──────────
-// Set at the start of each traced command run; used by RemoteStore to
-// forward the CLI span's trace identity to outgoing REST requests.
+// Set at the start of EVERY traced command run — including runs where export is
+// disabled. Context propagation is deliberately decoupled from export: a user
+// who opted out (or who simply has no OTLP endpoint configured) must still get
+// correlated server-side traces, they just don't contribute a CLI span.
 let _activeTraceId = null;
 let _activeSpanId = null;
+// Whether the current command's span will actually be exported. Drives the
+// W3C `sampled` bit only — never whether the header is sent.
+let _activeSampled = false;
 
 /**
- * Get the W3C traceparent for the currently-running CLI command, or null.
- * Called by RemoteStore to inject the header into REST fetches so CLI spans
- * are linked to REST API spans in Dash0.
+ * Get the W3C traceparent for the currently-running CLI command, or null when
+ * no command is running. Called by RemoteStore to inject the header into
+ * outgoing REST/MCP calls so the server span joins the CLI's trace.
+ *
+ * Flags are `01` when the CLI span is exported and `00` when it is not — the
+ * trace id is still carried either way, so the server can correlate. This
+ * mirrors `formatTraceparent` in `packages/mcp-core/src/trace-context.ts`
+ * (the CLI is zero-dep `.mjs` and cannot import the TS module); keep the two
+ * byte-consistent.
  */
 export function getActiveTraceparent() {
   if (!_activeTraceId || !_activeSpanId) return null;
-  return `00-${_activeTraceId}-${_activeSpanId}-01`;
+  return `00-${_activeTraceId}-${_activeSpanId}-${_activeSampled ? '01' : '00'}`;
 }
 
 // ── Config resolution ─────────────────────────────────────────────────────────
@@ -313,18 +324,32 @@ export async function traceCommand(command, args, version, run) {
     config = { enabled: false };
   }
 
+  // Generate trace context BEFORE the export gate below, so outgoing REST/MCP
+  // calls can forward it as `traceparent` even when telemetry is disabled.
+  // Propagation is decoupled from export: a user with no OTLP endpoint (the
+  // common case — TELEMETRY_TOKEN is empty in git) still gets a single
+  // correlated server-side trace. The `sampled` bit is what reflects export.
+  // The same IDs are reused in exportInvocation() to link the CLI span to
+  // REST spans.
+  _activeTraceId = randHex(16);
+  _activeSpanId = randHex(8);
+  _activeSampled = Boolean(config.enabled);
+
   // 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());
-
-  // Generate trace context before run() so REST calls can forward it as traceparent.
-  // The same IDs are reused in exportInvocation() to link the CLI span to REST spans.
-  _activeTraceId = randHex(16);
-  _activeSpanId = randHex(8);
+  if (!config.enabled) {
+    try {
+      return normalizeExitCode(await run());
+    } finally {
+      _activeTraceId = null;
+      _activeSpanId = null;
+      _activeSampled = false;
+    }
+  }
 
   const startMs = Date.now();
   let exitCode = 0;
@@ -389,6 +414,7 @@ export async function traceCommand(command, args, version, run) {
     } finally {
       _activeTraceId = null;
       _activeSpanId = null;
+      _activeSampled = false;
     }
   }
 }