@lorekit/cli 1.39.0 → 1.39.1

package/package.json

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

package/src/core/lessons.mjs

@@ -13,6 +13,10 @@ import { deriveScope } from '../scope.mjs';
 // must be able to reuse it rather than grow a second ranking with its own idea
 // of what "most useful" means.
 import { resolvePrecedence, rankLessons } from '../lessons-pure.mjs';
+// The store's own scope inventory, normalised — the SAME helper `memory.scopes`
+// uses, so the map and the MCP tool cannot disagree about what a scope holds or
+// about what a failed enumeration looks like.
+import { readScopeInventory } from '../store/scope-inventory.mjs';
 // The deep-link builder is the SAME pure module the `link` command and the
 // `--link` flag use, so the hook's confirmation/nudge links are JSON-encoded
 // correctly (a raw `?scope=global` silently means "all scopes") and can't drift
@@ -93,6 +97,19 @@ export const SCOPE_READ_LIMIT = 25;
 
 export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   const scope = deriveScope(cwd);
+  // Issued BEFORE the per-scope read loop and awaited after it. Nothing in the
+  // inventory depends on the loop, so awaiting it afterwards would cost a
+  // remote store one extra SERIAL round-trip on the session-start path; started
+  // here it overlaps the per-scope reads instead. On a local store `listScopes`
+  // is synchronous under its async signature, so the overlap is nil there and
+  // the ordering is merely harmless.
+  //
+  // Leaving the promise unawaited across the loop is safe because
+  // `readScopeInventory` cannot reject: its "store cannot enumerate" guard
+  // returns before the `try`, and the `try` covers both a synchronous throw and
+  // a rejected `listScopes()`. Keep that property if either is ever touched — a
+  // floating promise that can reject would take the hook down with it.
+  const inventoryPromise = readScopeInventory(store);
   const groups = [];
   // Per scope: did the read come back full? Then the count below is a floor,
   // not a total, and the map must say so rather than quietly under-report.
@@ -152,11 +169,55 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // build its array.
   const ranked = rankLessons(winners, { terms: [], now, scopeOrder: scope.readOrder });
 
-  // The scope map is built from the SAME pass, over the winners — the set a
-  // reader could actually act on, so a shadowed duplicate is not counted twice.
-  // Order follows `readOrder` (most-specific first) rather than count, because
-  // the map is a map: it should read like the hierarchy it describes.
-  const scopeCounts = scopeInventory(ranked, scope.readOrder, truncatedScopes);
+  // ── the scope map: EXACT counts when the store can enumerate ───────────────
+  //
+  // The map's job is to tell a reader how much lore is sitting in each scope
+  // that this injection did not show them, so its numbers should be the store's
+  // real totals. Deriving them from the bounded read above cannot do that: the
+  // read stops at `SCOPE_READ_LIMIT`, so a scope holding 400 lessons reported
+  // `25+` — technically honest, useless as a quantity, and the `+` was doing a
+  // lot of work.
+  //
+  // `listScopes()` answers exactly, at any size, on BOTH stores: the local one
+  // walks its own tree, and the remote one hits `GET /memories/scopes`, which
+  // aggregates in Postgres (migration 00039) rather than counting rows a
+  // response cap may have truncated. That is the same reason `stats` and
+  // `scopes` were moved onto it.
+  //
+  // TWO SEMANTIC DIFFERENCES, both deliberate, because the map answers a
+  // different question from the injected set:
+  //
+  //   1. It counts EVERY active lesson in the scope, not just the ones that
+  //      survived precedence. A key shadowed at a broader scope is still a real
+  //      row you can `memory.read` there, and the map is a pointer to what
+  //      exists — not a summary of what was injected.
+  //   2. It is not bounded by what this session happened to read, so a scope
+  //      whose lessons all lost the ranking still appears, which is precisely
+  //      when a reader most needs telling it is there.
+  //
+  // THE COST, STATED RATHER THAN LEFT TO BE DISCOVERED. Exactness is not free
+  // on a local or two-tier store: `listScopes()` there is `_walkEntries()`
+  // (`store/local.mjs`), which reads and parses EVERY lesson file under the
+  // base dir — including the scopes outside `readOrder` that the narrowing
+  // below then throws away. So a session start now pays a store-wide walk where
+  // the derived counts cost nothing beyond the bounded read it already did. It
+  // is accepted deliberately: the walk is local disk over a store of markdown
+  // files, the hosted path aggregates in Postgres instead of walking anything,
+  // and the alternative — bounding the enumeration — reinstates the `25+` floor
+  // this change exists to remove. Narrowing the walk would mean a scope filter
+  // on the store contract, which is a change to all three implementations and
+  // to `memory.scopes`; if this ever shows up in a session-start profile, that
+  // is the fix, not a smaller limit here.
+  //
+  // Best-effort, like everything on this path: an unreachable remote, a store
+  // with no `listScopes`, or a throw all fall back to the derived counts —
+  // approximate and `+`-suffixed, exactly what shipped before — rather than
+  // costing the user their scope map. `readScopeInventory` never throws.
+  const inventory = await inventoryPromise;
+  const derivedCounts = scopeInventory(ranked, scope.readOrder, truncatedScopes);
+  const scopeCounts = inventory.ok
+    ? scopeInventoryFromStore(inventory.scopes, scope.readOrder, derivedCounts)
+    : derivedCounts;
 
   // `applicable` is the honest denominator for the header — how many the reader
   // has, as opposed to how many fitted. It is counted BEFORE the ceiling, so
@@ -169,6 +230,49 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   };
 }
 
+// Per-scope counts from the STORE's own inventory, narrowed to the scopes this
+// working directory reads and ordered by the hierarchy.
+//
+// The narrowing is the point: `listScopes()` is deliberately store-wide (it
+// backs the `scopes` command, which enumerates everywhere), but the SessionStart
+// map describes THIS workspace. Naming a scope the reader is not working in
+// would be noise dressed up as guidance.
+//
+// An enumerated row is exact and so never carries `atReadLimit` — the `+`
+// suffix exists to admit that a number is a floor, and an enumerated one is
+// not. A row that fell back to the derived count keeps the flag it came with,
+// because that number IS a floor. A scope with no active
+// lesson is omitted, matching `scopeInventory`: a row reading `0` is noise, and
+// there is nothing to drill into. Pure.
+// `fallback` is the derived inventory — the same rows the failure path uses —
+// and it is consulted PER SCOPE, not only when the whole enumeration failed.
+// `ok: true` means the store answered, not that the answer is complete: a row
+// can be missing, or carry a count that `shapeScopeRow` had to coerce to 0.
+// Without the per-scope fallback a scope that just contributed injected lessons
+// would drop off the map entirely — the reader would see lore in the digest
+// with no row saying where it lives, which is a worse answer than the
+// approximate one this had in hand all along.
+export function scopeInventoryFromStore(scopes, scopeOrder = [], fallback = []) {
+  const counts = new Map();
+  for (const row of Array.isArray(scopes) ? scopes : []) {
+    const s = row?.scope;
+    if (!s) continue;
+    const n = Number(row.count);
+    if (Number.isFinite(n) && n > 0) counts.set(s, n);
+  }
+  const derived = new Map();
+  for (const row of Array.isArray(fallback) ? fallback : []) {
+    if (row?.scope) derived.set(row.scope, row);
+  }
+  return (Array.isArray(scopeOrder) ? scopeOrder : [])
+    .filter((s) => counts.has(s) || derived.has(s))
+    .map((s) => (counts.has(s)
+      ? { scope: s, count: counts.get(s), atReadLimit: false }
+      // The derived row keeps its own `atReadLimit`, so a fallen-back scope
+      // still renders `25+` rather than posing as an exact number.
+      : { ...derived.get(s) }));
+}
+
 // Per-scope counts over an already-ranked lesson list, in the given scope order.
 // A scope with no surviving lesson is omitted — a map row reading `0` is noise,
 // and the reader cannot act on an empty scope. Pure.

package/src/mcp-server.mjs

@@ -29,6 +29,7 @@ import { loadControl } from './control.mjs';
 import { createStore } from './store/index.mjs';
 import { createRemoteStore } from './store/remote.mjs';
 import { deriveOrigin, mergeOrigin } from './origin.mjs';
+import { readScopeInventory } from './store/scope-inventory.mjs';
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_INFO = { name: 'lorekit-local', version: '1.0.0' };
@@ -239,13 +240,15 @@ const MEMORY_DISPATCH = {
 // /memories/scopes` and the `lorekit scopes` command have answered this since
 // migration 00039; the MCP surface was the one caller that could not ask.
 //
-// THE TWO STORES ANSWER IN DIFFERENT SHAPES, and normalising here is the whole
-// job of this function. `LocalStore`/`TwoTierStore.listScopes()` return a BARE
-// ARRAY (`[{ scope, count }]`), while `RemoteStore.listScopes()` returns the
-// standard `{ ok, scopes }` envelope — or `{ ok: false, error, networkError,
-// unusable }`. A tool that passed either through verbatim would hand the model
-// two different contracts for one tool name depending on a config value it
-// cannot see.
+// THE TWO STORES ANSWER IN DIFFERENT SHAPES, and reconciling them is NO LONGER
+// this function's job — it moved to `store/scope-inventory.mjs`, which the
+// SessionStart scope map reads too. `LocalStore`/`TwoTierStore.listScopes()`
+// return a BARE ARRAY (`[{ scope, count }]`), while `RemoteStore.listScopes()`
+// returns the standard `{ ok, scopes }` envelope — or `{ ok: false, error,
+// networkError, unusable }`. A tool that passed either through verbatim would
+// hand the model two different contracts for one tool name depending on a
+// config value it cannot see. What is left here is what only the MCP surface
+// owns: the ascending sort and the exit-clean degradation below.
 //
 // DEGRADATION IS EXIT-CLEAN, mirroring the `scopes` command, which reports an
 // unreachable remote as a short note at exit 0 rather than failing the run. An
@@ -255,23 +258,16 @@ const MEMORY_DISPATCH = {
 // tool-level error is liable to retry it rather than carry on with the lore it
 // can already reach. The note says which, in bounded, non-PII terms.
 export async function listScopes(store) {
-  let res;
-  try {
-    res = await store.listScopes();
-  } catch (e) {
-    // A store that cannot enumerate must not take the session down with it.
-    return { ok: true, scopes: [], note: `scope enumeration failed: ${errText(e)}` };
-  }
-
-  // Local/two-tier: the bare array form.
-  if (Array.isArray(res)) return { ok: true, scopes: sortScopes(res.map(shapeScope)) };
-
-  // Remote: the envelope form.
-  if (res && res.ok) {
-    return { ok: true, scopes: sortScopes((Array.isArray(res.scopes) ? res.scopes : []).map(shapeScope)) };
-  }
-
-  return { ok: true, scopes: [], note: scopeFailureNote(res) };
+  // The array-vs-envelope branch and the failure vocabulary live in the shared
+  // `store/scope-inventory.mjs` — the SessionStart scope map needs the same
+  // normalisation, and two copies of "what does a failed enumeration look like"
+  // is how the two surfaces end up disagreeing about it.
+  const { ok, scopes, reason } = await readScopeInventory(store);
+  // `ok: true` either way: an enumeration that could not run is a fact about
+  // the store, not a failed tool call, so it must not reach `toolResult` as an
+  // `isError` a model is liable to retry instead of carrying on with the lore
+  // it can already reach.
+  return ok ? { ok: true, scopes: sortScopes(scopes) } : { ok: true, scopes: [], note: reason };
 }
 
 // Sorted by scope ascending, which is the contract `docs/mcp-tools.md`, the
@@ -301,42 +297,6 @@ function sortScopes(rows) {
   return rows.sort((a, b) => (a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : 0));
 }
 
-// One inventory row. `last_activity` is passed through when the store supplied
-// it (the hosted `GET /memories/scopes` has returned it since migration 00049)
-// and OMITTED — never null — when it did not, so a client can tell "this store
-// does not report freshness" from "this scope has no activity".
-function shapeScope(s) {
-  const scope = String(s?.scope ?? '');
-  const count = Number(s?.count);
-  const row = { scope, count: Number.isFinite(count) ? count : 0 };
-  const last = s?.last_activity ?? s?.lastActivity;
-  return last ? { ...row, last_activity: last } : row;
-}
-
-// A short, bounded reason an enumeration produced nothing. Deliberately built
-// here rather than reusing `lessons-view.mjs`'s `describeError`: that module
-// carries the whole render/`util` stack, and this server has kept clear of it.
-// The vocabulary matches what that helper reports, so the two read alike.
-function scopeFailureNote(res) {
-  if (!res) return 'the store returned no result';
-  if (res.unusable) return 'no usable store is configured';
-  if (res.networkError) return `network error: ${String(res.networkError).slice(0, 200)}`;
-  // `httpStatus` is the ONLY field that carries a real status: `restFetch`'s
-  // error object is `{ message, code }`, and `code` is the response body's own
-  // application code on a JSON error, so rendering it as "HTTP <code>" would
-  // print a non-status. Read the top-level field first — that is the one
-  // `RemoteStore.listScopes()` passes through — and keep the nested read as a
-  // tolerance for any store that nests it instead.
-  const status = res.httpStatus ?? res.error?.httpStatus;
-  if (status) return `request failed with HTTP ${status}`;
-  if (res.error?.message) return String(res.error.message).slice(0, 200);
-  return 'the store could not enumerate its scopes';
-}
-
-function errText(e) {
-  return String(e?.message ?? e).slice(0, 200);
-}
-
 // Provenance for a tool call: the caller's explicit values win, the working
 // directory and CI environment fill the rest. Best-effort — a failure to shell
 // out to git must never fail the write, so it degrades to no origin at all.

package/src/store/remote.mjs

@@ -262,8 +262,8 @@ class RemoteStore {
   // where `code` is the response body's own application code on a JSON error
   // (a string like `permission_denied`) and only incidentally the status on a
   // non-JSON one. A consumer that wants to say "HTTP 403" must therefore read
-  // `httpStatus`, never `error.code` — `mcp-server.mjs`'s `scopeFailureNote`
-  // does exactly that, and it had nothing to read until this field was passed
+  // `httpStatus`, never `error.code` — `store/scope-inventory.mjs`'s
+  // `failureReason` does exactly that, and it had nothing to read until this field was passed
   // through. Additive: `scopes.mjs`, `stats.mjs` and `lessons-view.mjs` all
   // branch on `ok` / `unusable` / `networkError` and ignore the extra key.
   async listScopes() {

package/src/store/scope-inventory.mjs

@@ -0,0 +1,123 @@
+// Normalising a store's scope inventory into ONE shape.
+//
+// `listScopes()` is the only store method whose two implementations disagree
+// about their envelope: `LocalStore`/`TwoTierStore` return a BARE ARRAY of
+// `{ scope, count }`, while `RemoteStore` returns the standard
+// `{ ok, scopes }` — or `{ ok: false, error, networkError, unusable }`. Every
+// caller that wants an inventory therefore has to know which store it is
+// holding, which is exactly the knowledge a caller should not need.
+//
+// Two callers now want one: the `memory.scopes` MCP tool and the SessionStart
+// scope map. Before this module they each carried their own copy of the
+// array-vs-envelope branch, which is two places to get "what does a failed
+// enumeration look like" subtly different.
+//
+// TOTAL FUNCTION. Anything unrecognisable — a null, a rejected promise's value,
+// a row with a missing count — degrades to a usable answer with a reason
+// attached. Both callers are best-effort paths: the MCP tool must not turn "I
+// could not enumerate" into a tool error, and the hook must not lose a lesson
+// injection over a failed count. Neither can afford a throw.
+//
+// Zero-dependency: no imports, not even node builtins.
+
+/**
+ * Normalise whatever `listScopes()` returned into `{ ok, scopes, reason }`.
+ *
+ * `ok` is false ONLY when the store could not answer. An empty store is a
+ * SUCCESSFUL enumeration that found nothing (`ok: true`, `scopes: []`) — the
+ * distinction matters, because "no scopes" and "I could not look" lead a caller
+ * to different behaviour, and collapsing them is how a transient network error
+ * ends up rendering as an authoritative empty inventory.
+ *
+ * `reason` is a short, bounded, non-PII note when `ok` is false, and null
+ * otherwise. The vocabulary matches `lessons-view.mjs`'s `describeError`, so
+ * the notes read alike wherever they surface — but it is built here rather than
+ * imported, because this module is reached from the SessionStart hot path and
+ * that one carries the whole render/`util` stack.
+ */
+export function normalizeScopeInventory(result) {
+  // Local / two-tier: the bare array form.
+  if (Array.isArray(result)) return { ok: true, scopes: result.map(shapeScopeRow), reason: null };
+
+  // Remote: the envelope form.
+  if (result && result.ok) {
+    const scopes = Array.isArray(result.scopes) ? result.scopes : [];
+    return { ok: true, scopes: scopes.map(shapeScopeRow), reason: null };
+  }
+
+  return { ok: false, scopes: [], reason: failureReason(result) };
+}
+
+/**
+ * One inventory row, coerced.
+ *
+ * `last_activity` is passed through when the store supplied it (the hosted
+ * `GET /memories/scopes` has returned it since migration 00049) and OMITTED —
+ * never null — when it did not, so a consumer can tell "this store does not
+ * report freshness" from "this scope has none".
+ *
+ * ONE DELIBERATE DIVERGENCE from the `shapeScope` this replaced, named here so
+ * it is not mistaken for an accident: the count is clamped at 0, where the old
+ * helper passed a negative through. A negative count is not a quantity any
+ * store can honestly report — `LocalStore` increments a counter and the hosted
+ * route is a `count(*)` — so it can only ever be a malformed row, and `-3` in a
+ * `memory.scopes` answer is worse than `0`. Unreachable from either real store;
+ * it is the coercion boundary being total, not a behaviour anyone can observe.
+ */
+export function shapeScopeRow(s) {
+  const count = Number(s?.count);
+  const row = { scope: String(s?.scope ?? ''), count: Number.isFinite(count) ? Math.max(0, count) : 0 };
+  const last = s?.last_activity ?? s?.lastActivity;
+  return last ? { ...row, last_activity: last } : row;
+}
+
+/** A short, bounded reason an enumeration produced nothing. */
+export function failureReason(result) {
+  if (!result) return 'the store returned no result';
+  if (result.unusable) return 'no usable store is configured';
+  if (result.networkError) return `network error: ${clip(result.networkError)}`;
+  // `httpStatus` is the ONLY field carrying a real status: `restFetch`'s error
+  // object is `{ message, code }`, and `code` is the response body's own
+  // application code on a JSON error, so rendering it as "HTTP <code>" would
+  // print a non-status. Read the top-level field first — that is the one
+  // `RemoteStore.listScopes()` passes through — and keep the nested read as a
+  // tolerance for any store that nests it instead.
+  const status = result.httpStatus ?? result.error?.httpStatus;
+  if (status) return `request failed with HTTP ${status}`;
+  if (result.error?.message) return clip(result.error.message);
+  return 'the store could not enumerate its scopes';
+}
+
+function clip(v) {
+  return String(v).slice(0, 200);
+}
+
+/**
+ * Ask a store for its inventory without letting it fail the caller.
+ *
+ * A store need not implement `listScopes` at all (a stub, a fixture, a future
+ * adapter), and one that does may still throw. Both are ordinary here, so both
+ * come back as `ok: false` with a reason rather than as an exception the caller
+ * has to remember to catch.
+ *
+ * THE SECOND DELIBERATE DIVERGENCE from what `memory.scopes` used to answer,
+ * named here for the same reason as `shapeScopeRow`'s clamp. The old
+ * `mcp-server.mjs` path called `store.listScopes()` unguarded and let the
+ * resulting `TypeError` fall into its catch, so a store without the method
+ * reported `scope enumeration failed: store.listScopes is not a function` — an
+ * internal symbol leaked into a user-facing note, and indistinguishable from a
+ * store whose enumeration genuinely blew up. The missing method is checked
+ * first now and reported as `this store cannot enumerate scopes`; the throwing
+ * case keeps the `scope enumeration failed: <message>` wording verbatim. Two
+ * different facts, two different notes.
+ */
+export async function readScopeInventory(store) {
+  if (!store || typeof store.listScopes !== 'function') {
+    return { ok: false, scopes: [], reason: 'this store cannot enumerate scopes' };
+  }
+  try {
+    return normalizeScopeInventory(await store.listScopes());
+  } catch (e) {
+    return { ok: false, scopes: [], reason: `scope enumeration failed: ${clip(e?.message ?? e)}` };
+  }
+}