@lorekit/cli 1.13.1 → 1.14.0

package/README.md

@@ -194,6 +194,44 @@ behave as in `list`. Remote counts reflect what the hosted `memory.list` returns
 per scope (the server's default page size); there is no cap-usage `N / limit`
 figure because the MCP surface exposes no total-count or cap tool.
 
+### `lorekit scopes`
+
+A **store-wide inventory** of every distinct scope that holds lessons, with a
+lesson count per scope, in the same Offline / Remote split as the other read
+commands:
+
+```bash
+lorekit scopes                 # every scope in the store + a count each
+lorekit scopes --scope repo::  # filter to scopes containing a substring
+lorekit scopes --json          # { offline, remote } with [{ scope, count }] rows
+```
+
+Unlike `list` / `search` / `stats` / `diff` / `tree` — which are all **cwd-scoped**
+(they only look at the scopes that resolve for the current directory:
+project / branch / repo / global) — `scopes` enumerates **every** scope present in
+the store, regardless of the current directory. That's the whole point: it lets
+you see all the scopes you have lessons in, anywhere. Scopes are grouped by type
+(global → project → repo → branch), then alphabetically; each store shows a
+per-store total and scope count.
+
+`--scope <s>` is a **substring filter** over the inventory (not a single-scope
+selector — an inventory of one scope would be pointless).
+
+**Offline enumeration is exact.** It walks the local two-tier store and reads
+each lesson file's frontmatter `scope` string directly, rather than reverse-
+mapping the on-disk directory layout (which is lossy for `project::{name}`,
+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`.
+
 ### `lorekit diff`
 
 Compare the **offline** and **remote** stores for the applicable scopes and
@@ -453,8 +491,8 @@ active deny constraints.
 | `--no-hooks` | Skip wiring the lifecycle hooks; skill + MCP only (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
-| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `diff` / `tree` / `lint` / `dedupe`) |
-| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe`; default: all applicable) |
+| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe`) |
+| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe`; default: all applicable). For `scopes` it is a **substring filter** over the inventory |
 | `--threshold <0..1>` | Duplicate-similarity cutoff (`dedupe`; default `0.8`) |
 | `--adapter <name>` | Host framework for `hook`: `claude` / `cursor` / `codex` |
 | `--event <name>` | Host hook event for `hook` (else read from the stdin payload) |
@@ -548,7 +586,7 @@ forever. This reduces manual validation to a single capture pass per tool.
 ## Usage telemetry
 
 The human-facing commands (`install`, `uninstall`, `doctor`, `list`, `search`,
-`show`, `stats`, `diff`, `migrate`)
+`show`, `stats`, `scopes`, `diff`, `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

package/bin/lorekit.mjs

@@ -10,6 +10,7 @@ import { list } from '../src/list.mjs';
 import { search } from '../src/search.mjs';
 import { show } from '../src/show.mjs';
 import { stats } from '../src/stats.mjs';
+import { scopes } from '../src/scopes.mjs';
 import { diff } from '../src/diff.mjs';
 import { tree } from '../src/tree.mjs';
 import { lint } from '../src/lint.mjs';
@@ -56,6 +57,10 @@ ${c.bold('Commands')}
   stats       Count the applicable lessons per scope and per store (offline vs
               remote), with per-store and grand totals, in the same Offline/
               Remote split. --json, --scope <s>.
+  scopes      Store-wide inventory of EVERY distinct scope that holds lessons,
+              with a lesson count per scope — not cwd-scoped like the commands
+              above (it lists scopes anywhere in the store). Offline is exact;
+              the remote can't enumerate scopes (honest note). --json, --scope <s>.
   diff        Compare the offline and remote stores for the applicable scopes and
               report divergence: local-only, remote-only, and conflicting keys
               (grouped by scope). Needs both stores readable. --json, --scope <s>.
@@ -86,8 +91,8 @@ ${c.bold('Options')}
   -t, --token <token>     LoreKit token (lk_rw_* to allow writes, lk_ro_* read-only)
       --mode <mode>       Memory mode: off | local | remote (doctor override)
       --store <path>      Local project-tier store directory (default: .lorekit)
-      --json              Machine-readable output (list / search / show / stats / diff / tree / lint / dedupe)
-      --scope <scope>     Restrict to a single scope (list / search / stats / diff / tree / lint / dedupe)
+      --json              Machine-readable output (list / search / show / stats / scopes / diff / tree / lint / dedupe)
+      --scope <scope>     Restrict to a single scope; a substring filter for scopes (list / search / stats / scopes / diff / tree / lint / dedupe)
       --threshold <0..1>  Duplicate-similarity cutoff (dedupe; default 0.8)
       --from <path>       Source store to migrate from (migrate)
       --to <tier>         Migration destination tier: home | project (migrate;
@@ -285,6 +290,35 @@ ${c.bold('Examples')}
   npx @lorekit/cli stats
   npx @lorekit/cli stats --json
   npx @lorekit/cli stats --scope global
+`,
+  scopes: `${c.bold('lorekit scopes')} — store-wide inventory of every distinct scope
+
+${c.bold('Usage')}
+  npx @lorekit/cli scopes [options]
+
+Lists EVERY distinct scope present in the store, with a lesson count per scope,
+in the same Offline / Remote split as the other read commands. Unlike \`list\` /
+\`stats\` (which only see the scopes that resolve for the current directory), this
+is a full inventory — it surfaces scopes anywhere in the store, regardless of the
+current directory.
+
+Offline counts are exact: each scope is read from the lesson 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).
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --scope <substr>    Filter the inventory to scopes containing this substring
+      --json              Machine-readable output
+  -e, --endpoint <url>    Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
+  -t, --token <token>     Remote token override (else .mcp.json / LOREKIT_TOKEN)
+      --store <path>      Local project-tier store directory (default: .lorekit)
+
+${c.bold('Examples')}
+  npx @lorekit/cli scopes
+  npx @lorekit/cli scopes --json
+  npx @lorekit/cli scopes --scope repo::
 `,
   diff: `${c.bold('lorekit diff')} — compare the offline and remote stores
 
@@ -442,8 +476,8 @@ const KNOWN_FLAGS = [
 // 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', 'list', 'search', 'show', 'stats', 'diff',
-  'tree', 'lint', 'dedupe', 'migrate',
+  'install', 'uninstall', 'doctor', 'list', 'search', 'show', 'stats', 'scopes',
+  'diff', 'tree', 'lint', 'dedupe', 'migrate',
 ]);
 
 // Command aliases — canonicalized before help / dispatch so `lorekit ls --help`
@@ -525,6 +559,8 @@ async function main() {
       return traceCommand('show', args, VERSION, () => show(args));
     case 'stats':
       return traceCommand('stats', args, VERSION, () => stats(args));
+    case 'scopes':
+      return traceCommand('scopes', args, VERSION, () => scopes(args));
     case 'diff':
       return traceCommand('diff', args, VERSION, () => diff(args));
     case 'tree':

package/package.json

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

package/src/lessons-view.mjs

@@ -112,6 +112,51 @@ export function tallyGroups({ groups = [], total } = {}) {
   return { perScope, total: typeof total === 'number' ? total : summed };
 }
 
+// ── `scopes` — store-wide scope inventory ─────────────────────────────────────
+
+// The canonical scope TYPE of a scope string — its `::`-leading segment when it
+// is one of the four recognized types, else `other` (a malformed / legacy row).
+// Pure. Shared by the `scopes` inventory ordering below.
+export function scopeTypeOf(scope) {
+  const type = String(scope == null ? '' : scope).split('::')[0];
+  return ['global', 'project', 'repo', 'branch'].includes(type) ? type : 'other';
+}
+
+// A stable type ordering for the inventory: broadest → most-specific, with any
+// unrecognized scope last. Chosen (over count-desc) so the listing groups
+// related scopes together and is deterministic run-to-run.
+const SCOPE_TYPE_RANK = { global: 0, project: 1, repo: 2, branch: 3, other: 4 };
+
+// Sort a scope inventory (`[{ scope, count }]`) into a navigable order: primary
+// by scope type (global → project → repo → branch → other), secondary
+// alphabetical by the full scope string. Pure — returns a new array, never
+// mutating its input.
+export function sortScopeInventory(list = []) {
+  return [...list].sort((a, b) => {
+    const ra = SCOPE_TYPE_RANK[scopeTypeOf(a.scope)] ?? 4;
+    const rb = SCOPE_TYPE_RANK[scopeTypeOf(b.scope)] ?? 4;
+    if (ra !== rb) return ra - rb;
+    return String(a.scope).localeCompare(String(b.scope));
+  });
+}
+
+// Narrow a scope inventory to the scopes whose string CONTAINS `needle`
+// (case-insensitive substring) — the `scopes --scope <s>` filter. An empty /
+// absent needle passes everything through unchanged. Pure.
+export function filterScopeInventory(list = [], needle) {
+  if (!needle) return list;
+  const q = String(needle).toLowerCase();
+  return list.filter((s) => String(s.scope).toLowerCase().includes(q));
+}
+
+// The pure core of the `scopes` command: sort an inventory and total its counts.
+// Returns `{ scopes: [{ scope, count }] (sorted), total }`. Pure.
+export function summarizeScopeInventory(list = []) {
+  const scopes = sortScopeInventory(list);
+  const total = scopes.reduce((n, s) => n + (Number(s.count) || 0), 0);
+  return { scopes, total };
+}
+
 // Compare two `gather()` results (offline vs remote) and classify every scope's
 // keys into three sets — the pure core of the `diff` command:
 //   • localOnly     — key present offline, absent remote;

package/src/scopes.mjs

@@ -0,0 +1,152 @@
+// `lorekit scopes` — a STORE-WIDE inventory of every distinct scope that holds
+// lessons, with a per-scope lesson count, in the same Offline / Remote split as
+// the other read commands.
+//
+// The key difference from `list` / `search` / `stats` / `diff` / `tree`: those
+// are all cwd-scoped — they only look at the scopes that resolve for the current
+// directory (project / branch / repo / global). `scopes` ignores the current
+// directory entirely and enumerates EVERY scope present in the store, so a user
+// can see all the scopes they have lessons in, anywhere.
+//
+// Offline enumeration is AUTHORITATIVE: it walks the local two-tier store and
+// reads each lesson file's frontmatter `scope` string directly — never reverse-
+// 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.
+//
+// Graceful, read-only, human-facing (the bin wraps it in `traceCommand`).
+// `LOREKIT_DENY` suppresses a section; `--scope <s>` filters the inventory to
+// scopes whose string contains that substring; `--json` emits `{ offline,
+// remote }`.
+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 { 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 };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  // `--scope <s>` is a substring filter over the inventory (NOT a single-scope
+  // selector like the cwd-scoped commands — an inventory of one scope would be
+  // pointless). Absent → the full inventory.
+  const filter = args.scope && typeof args.scope === 'string' ? args.scope : null;
+
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+
+  // Deny-wins section suppression, identical to `list` / `stats` / `diff`.
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  // Offline: the authoritative store-wide enumeration.
+  let offlineSection;
+  if (localDenied) {
+    offlineSection = { available: false, reason: `disabled by deny constraint (${localDenied.source})` };
+  } else {
+    const inventory = filterScopeInventory(await local.listScopes(), filter);
+    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.
+  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 };
+  }
+
+  if (args.json) {
+    log(JSON.stringify(buildJson({ root, filter, offlineSection, remoteSection }), null, 2));
+  } else {
+    heading('LoreKit scopes');
+    log(`  store: ${c.dim(root)}`);
+    if (filter) log(`  filter: ${c.dim(filter)}`);
+    renderScopesSection({ title: 'Offline' }, offlineSection);
+    renderScopesSection(
+      { title: 'Remote', subtitle: remote.usable() ? connection.endpoint : undefined },
+      remoteSection,
+    );
+    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.
+  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,
+  };
+}
+
+// Render one store's inventory: an unavailable note, or a right-aligned
+// `scope   count` table plus a `total` line noting the scope count.
+function renderScopesSection(header, section) {
+  heading(header.title);
+  if (header.subtitle) log(`  ${c.dim(header.subtitle)}`);
+
+  if (!section.available) {
+    status('warn', 'unavailable', section.reason);
+    return;
+  }
+
+  if (!section.scopes.length) {
+    log(`  ${c.dim('no scopes found — the store holds no lessons')}`);
+    return;
+  }
+
+  const width = Math.max(0, ...section.scopes.map((s) => String(s.scope).length));
+  for (const s of section.scopes) {
+    log(`  ${c.bold(String(s.scope).padEnd(width))}  ${s.count}`);
+  }
+  const n = section.scopes.length;
+  log(
+    `  ${c.dim('total'.padEnd(width))}  ${c.bold(String(section.total))}  ` +
+      `${c.dim(`(${n} scope${n === 1 ? '' : 's'})`)}`,
+  );
+}
+
+// The `--json` payload: `{ root, filter, offline, remote }` — each store a
+// `{ available, total, scopes: [{ scope, count }] }` record (or an unavailable
+// note), so a script gets the same shape regardless of which store answered.
+function buildJson({ root, filter, offlineSection, remoteSection }) {
+  return {
+    root,
+    filter: filter || null,
+    offline: sectionJson(offlineSection),
+    remote: sectionJson(remoteSection),
+  };
+}
+
+function sectionJson(section) {
+  if (!section.available) {
+    return { available: false, reason: section.reason, total: 0, scopes: [] };
+  }
+  return {
+    available: true,
+    total: section.total,
+    scopes: section.scopes.map((s) => ({ scope: s.scope, count: s.count })),
+  };
+}

package/src/store/local.mjs

@@ -204,6 +204,53 @@ class LocalStore {
     for (const scope of scopes || []) n += (await this.list({ scope })).entries.length;
     return n;
   }
+
+  // Recursively collect every parsed entry under baseDir, across ALL scopes —
+  // the primitive `listScopes()` builds on. Best-effort: a missing base dir or
+  // an unreadable file is skipped, never thrown. Reads each file's frontmatter
+  // (the authoritative scope string) rather than the directory it sits in.
+  _walkEntries() {
+    const out = [];
+    const walk = (dir) => {
+      let dirents;
+      try {
+        dirents = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return; // missing / unreadable directory — nothing to enumerate here
+      }
+      for (const d of dirents) {
+        const full = path.join(dir, d.name);
+        if (d.isDirectory()) {
+          walk(full);
+        } else if (d.isFile() && d.name.endsWith('.md')) {
+          try {
+            const entry = parseEntry(fs.readFileSync(full, 'utf8'));
+            if (entry) out.push({ entry, file: full });
+          } catch {
+            // Skip an unreadable file rather than fail the whole enumeration.
+          }
+        }
+      }
+    };
+    walk(this.baseDir);
+    return out;
+  }
+
+  // Enumerate every distinct scope present on disk with its non-archived lesson
+  // count — a STORE-WIDE inventory, independent of any current directory (unlike
+  // list/count, which take an explicit scope set). The scope of each lesson is
+  // read from its frontmatter `scope` field, so the reconstructed scope string
+  // is EXACT — never reverse-mapped from the on-disk directory layout, which is
+  // lossy for `project::{name}` (stored by basename only). Returns
+  // `[{ scope, count }]`, unsorted.
+  async listScopes() {
+    const counts = new Map();
+    for (const { entry } of this._walkEntries()) {
+      if (entry.archived_at || !entry.scope) continue;
+      counts.set(entry.scope, (counts.get(entry.scope) || 0) + 1);
+    }
+    return [...counts.entries()].map(([scope, count]) => ({ scope, count }));
+  }
 }
 
 // A scope string is global when its type segment is `global`.
@@ -326,4 +373,23 @@ class TwoTierStore {
     for (const scope of scopes || []) n += (await this.list({ scope })).entries.length;
     return n;
   }
+
+  // Store-wide scope inventory across both tiers, de-duplicated by scope+key so
+  // a lesson present in both tiers is counted once — project shadows home, the
+  // same first-wins merge `list()` uses. Returns `[{ scope, count }]`, unsorted.
+  async listScopes() {
+    const seen = new Set(); // `${scope}\x00${key}` — dedup across tiers
+    const counts = new Map();
+    const tiers = this.projectActive() ? [this.project, this.home] : [this.home];
+    for (const tier of tiers) {
+      for (const { entry } of tier._walkEntries()) {
+        if (entry.archived_at || !entry.scope) continue;
+        const id = `${entry.scope}\x00${entry.key ?? ''}`;
+        if (seen.has(id)) continue;
+        seen.add(id);
+        counts.set(entry.scope, (counts.get(entry.scope) || 0) + 1);
+      }
+    }
+    return [...counts.entries()].map(([scope, count]) => ({ scope, count }));
+  }
 }

package/src/store/remote.mjs

@@ -112,6 +112,14 @@ class RemoteStore {
     return { ok: true, ...payload };
   }
 
+  // Store-wide scope enumeration is NOT possible against the hosted MCP surface:
+  // every read tool (memory.list / memory.search / memory.read) REQUIRES a
+  // scope, and there is no "list all scopes" tool. Signal that honestly so the
+  // `scopes` command shows a clear note rather than faking an inventory.
+  async listScopes() {
+    return { ok: false, unsupported: true };
+  }
+
   // Connectivity probe for doctor — a transport check, not a memory op.
   async ping() {
     if (!this.usable()) return { ok: false, unusable: true };

package/src/telemetry.mjs

@@ -4,9 +4,9 @@
 // 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 / uninstall / doctor / list / search / show / stats / diff / tree /
-// lint / dedupe / migrate), fired to Dash0 so the maintainers can see which
-// commands people actually run.
+// (install / uninstall / doctor / list / search / show / stats / scopes / diff /
+// tree / lint / dedupe / 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
@@ -275,7 +275,7 @@ function normalizeExitCode(result) {
  * counter point. Returns the command's exit code unchanged. Telemetry failures
  * are swallowed — the command result is never affected.
  *
- * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | diff | tree | lint | dedupe | migrate
+ * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | scopes | diff | tree | lint | dedupe | 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