@lorekit/cli 1.7.1 → 1.8.0

package/README.md

@@ -106,6 +106,34 @@ lorekit doctor --deep     # also does a write → read → delete round-trip (ne
 
 Exit code is non-zero if any check fails, so it fits CI gates.
 
+### `lorekit list` (alias `ls`)
+
+Shows the lessons that apply to **where you are** — the scopes `deriveScope`
+resolves for the current directory (`project::{name}`, `branch::…`, `repo::…`,
+and `global`) — split into two clearly-labelled sections so you can see where
+each lesson lives:
+
+- **Offline** — the local two-tier store (`.lorekit/` in the repo + `~/.lorekit/`).
+- **Remote** — the hosted MCP store. When no token/endpoint is configured this
+  section is a short note on how to set it up; it is **never an error** (the
+  command still exits 0 and shows your offline lessons). A network/server error
+  is likewise a per-scope warning, not a crash.
+
+It is read-only — it never writes, deletes, or reveals archived lessons — and it
+independently queries both stores regardless of the resolved memory mode. A
+`LOREKIT_DENY=remote` (or `local`) ceiling suppresses that section, honoring the
+same deny-wins privacy invariant the control model enforces for agents.
+
+```bash
+lorekit list                 # both sections, grouped by scope
+lorekit ls                   # same, via the alias
+lorekit list --scope global  # narrow to a single scope
+lorekit list --json          # structured { offline, remote } payload for scripts
+```
+
+`--endpoint` / `--token` override the remote connection; `--store` overrides the
+local project-tier directory.
+
 ### `lorekit hook`
 
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
@@ -288,6 +316,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`) |
+| `--scope <scope>` | Restrict to a single scope (`list`; default: all applicable) |
 | `--adapter <name>` | Host framework for `hook`: `claude` / `cursor` / `codex` |
 | `--event <name>` | Host hook event for `hook` (else read from the stdin payload) |
 | `-h, --help` | Help |
@@ -372,8 +402,8 @@ forever. This reduces manual validation to a single capture pass 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
+The human-facing commands (`install`, `uninstall`, `doctor`, `list`, `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.

package/bin/lorekit.mjs

@@ -6,6 +6,7 @@ import { parseArgs, log, err, c } from '../src/util.mjs';
 import { install } from '../src/install.mjs';
 import { uninstall } from '../src/uninstall.mjs';
 import { doctor } from '../src/doctor.mjs';
+import { list } from '../src/list.mjs';
 import { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
 import { mcpServer } from '../src/mcp-server.mjs';
@@ -35,6 +36,10 @@ ${c.bold('Commands')}
               other servers, hooks, and settings are left untouched. Prompts
               project vs global; --project / --global choose non-interactively.
   doctor      Verify the skill install, MCP connectivity, token, and scope.
+  list (ls)   List the lessons that apply to the current directory, split into
+              an Offline section (local .lorekit/ + ~/.lorekit/) and a Remote
+              section (hosted MCP). Groups by scope (project/branch/repo/global).
+              --json for scripting, --scope <s> to narrow.
   migrate     Relocate a LoreKit-format local store into the current layout.
               Dry-run by default; pass --yes to apply. Idempotent.
   hook        Hook engine for Claude Code / Cursor / Codex. Reads the host's
@@ -53,6 +58,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)
+      --scope <scope>     Restrict to a single scope (list)
       --from <path>       Source store to migrate from (migrate)
       --to <tier>         Migration destination tier: home | project (migrate;
                           default routes each entry by scope)
@@ -156,6 +163,30 @@ ${c.bold('Examples')}
   npx @lorekit/cli doctor
   npx @lorekit/cli doctor --deep
   npx @lorekit/cli doctor --mode local
+`,
+  list: `${c.bold('lorekit list')} — list the lessons that apply to the current directory ${c.dim('(alias: ls)')}
+
+${c.bold('Usage')}
+  npx @lorekit/cli list [options]
+
+Shows the lessons for the scopes that resolve for the current directory
+(project/branch/repo/global), split into an Offline section (the local
+.lorekit/ + ~/.lorekit/ two-tier store) and a Remote section (the hosted MCP
+server). When no remote token/endpoint is configured the Remote section is a
+short note on how to set it up — never an error.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --scope <scope>     Restrict to a single scope (default: all applicable)
+      --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 list
+  npx @lorekit/cli list --json
+  npx @lorekit/cli list --scope global
 `,
   migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
 
@@ -209,13 +240,17 @@ ${c.bold('Options')}
 const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
   'from', 'to', 'apply', 'yes', 'no-hooks', 'force', 'deep', 'adapter',
-  'event', 'help', 'version',
+  'event', 'json', 'scope', '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']);
+const HUMAN_COMMANDS = new Set(['install', 'uninstall', 'doctor', 'list', 'migrate']);
+
+// Command aliases — canonicalized before help / dispatch so `lorekit ls --help`
+// and telemetry both resolve to the real command name.
+const COMMAND_ALIASES = { ls: 'list' };
 
 async function main() {
   // Load a `.env` from the current directory (if any) before anything reads the
@@ -227,11 +262,11 @@ 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'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'json'],
     known: KNOWN_FLAGS,
   });
 
-  const command = args._[0];
+  const command = COMMAND_ALIASES[args._[0]] || args._[0];
 
   // Help is intercepted first — before the machine-facing hook/mcp dispatch — so
   // `lorekit <command> --help` always documents the command (even hook/mcp)
@@ -284,6 +319,8 @@ async function main() {
       return traceCommand('uninstall', args, VERSION, () => uninstall(args));
     case 'doctor':
       return traceCommand('doctor', args, VERSION, () => doctor(args));
+    case 'list':
+      return traceCommand('list', args, VERSION, () => list(args));
     case 'migrate':
       return traceCommand('migrate', args, VERSION, () => migrate(args));
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.7.1",
+  "version": "1.8.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

@@ -0,0 +1,109 @@
+// Shared, store-agnostic view layer for the read commands (`list`, and the
+// stacked `search` / `show` / `stats` / `diff` to come). Two responsibilities:
+//   1. pure helpers — the applicable-scope set, entry normalization, previews;
+//   2. `gather()` — collect a store's entries per scope behind the common
+//      store contract; and `renderSection()` — print one offline/remote section.
+//
+// Kept separate from `list.mjs` on purpose: the offline/remote sectioned
+// rendering is a reusable seam, not a `list`-only detail. Zero-dependency.
+import { log, heading, status, c } from './util.mjs';
+
+// The scopes that apply to the current directory, most-specific → broadest:
+// project, branch, repo, global. De-duplicated (a repo with no branch scope,
+// or a project whose name collides, never lists a scope twice). Pure — takes an
+// already-derived `deriveScope()` result so it is trivially unit-testable.
+export function scopeList({ projectScope, branchScope, repoScope } = {}) {
+  return [...new Set([projectScope, branchScope, repoScope, 'global'].filter(Boolean))];
+}
+
+// Normalize an entry from either store (local markdown row or hosted DB row)
+// into one stable shape the view + `--json` output can rely on. Remote rows may
+// spell the timestamp `updated_at`; local rows use `updated`.
+export function normalizeEntry(e = {}) {
+  return {
+    scope: e.scope ?? null,
+    key: e.key ?? null,
+    value: e.value == null ? '' : String(e.value),
+    updated: e.updated ?? e.updated_at ?? null,
+    tags: Array.isArray(e.tags) ? e.tags : [],
+  };
+}
+
+// A single-line, whitespace-collapsed, length-bounded preview of a lesson body.
+export function preview(value, max = 72) {
+  const s = String(value == null ? '' : value)
+    .replace(/\s+/g, ' ')
+    .trim();
+  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+// Just the calendar date from an ISO timestamp, for compact `(updated …)` tags.
+export function shortDate(iso) {
+  const s = String(iso || '');
+  return /^\d{4}-\d{2}-\d{2}/.test(s) ? s.slice(0, 10) : s;
+}
+
+// A bounded, non-PII description of a per-scope read failure (network / server).
+function describeError(res) {
+  if (!res) return 'no response';
+  if (res.networkError) return String(res.networkError);
+  if (res.error) return res.error.message || `error ${res.error.code}`;
+  return 'unreadable';
+}
+
+// Collect a store's non-archived entries for each scope, via the common
+// `store.list({scope})` contract. Returns ordered per-scope groups plus a total
+// — a per-scope read failure is captured on the group, never thrown, so one bad
+// scope can't abort the listing. `store` may be a local or remote store.
+export async function gather(store, scopes) {
+  const groups = [];
+  let total = 0;
+  for (const scope of scopes) {
+    let res;
+    try {
+      res = await store.list({ scope });
+    } catch (e) {
+      res = { ok: false, networkError: (e && e.message) || 'error' };
+    }
+    if (!res || res.ok === false) {
+      groups.push({ scope, entries: [], error: describeError(res) });
+      continue;
+    }
+    const entries = (res.entries || []).map(normalizeEntry);
+    total += entries.length;
+    groups.push({ scope, entries, error: null });
+  }
+  return { groups, total };
+}
+
+// Render one section (Offline or Remote). `section` is either
+//   { available:false, reason }                         → a graceful note, or
+//   { available:true, groups, total }                   → grouped lessons.
+export function renderSection(header, section) {
+  heading(header.title);
+  if (header.subtitle) log(`  ${c.dim(header.subtitle)}`);
+
+  if (!section.available) {
+    status('warn', 'unavailable', section.reason);
+    return;
+  }
+
+  const printable = (section.groups || []).filter((g) => g.entries.length || g.error);
+  if (!printable.length) {
+    log(`  ${c.dim('no lessons found in the applicable scopes')}`);
+    return;
+  }
+
+  for (const g of printable) {
+    log(`  ${c.bold(g.scope)}`);
+    if (g.error) {
+      log(`    ${c.yellow('!')} ${c.dim(g.error)}`);
+      continue;
+    }
+    for (const e of g.entries) {
+      const when = e.updated ? `  ${c.dim(`(updated ${shortDate(e.updated)})`)}` : '';
+      log(`    ${c.cyan('•')} ${e.key}${when}`);
+      if (e.value) log(`      ${c.dim(preview(e.value))}`);
+    }
+  }
+}

package/src/list.mjs

@@ -0,0 +1,123 @@
+// `lorekit list` — show the lessons that apply to the current directory, split
+// into an Offline section (the local two-tier store) and a Remote section (the
+// hosted MCP store). Scopes searched are the ones `deriveScope` resolves for the
+// cwd: project, branch, repo, and global.
+//
+// Graceful by design: when no remote token/endpoint is configured the Remote
+// section is a short note on how to set it up — never an error (mirrors
+// `doctor`'s tone). Human-facing, so it is wrapped in `traceCommand` by the bin.
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveProjectRoot } from './config.mjs';
+import { deriveScope } from './scope.mjs';
+import { loadControl } from './control.mjs';
+import { resolveStores, remoteUnavailableReason } from './stores.mjs';
+import { scopeList, gather, renderSection } from './lessons-view.mjs';
+import { log, heading, c } from './util.mjs';
+
+// Abbreviate the user's home directory to `~` for readable paths.
+function prettyPath(p) {
+  const home = os.homedir();
+  return p && home && p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+
+// A human label for where the offline store reads from.
+function offlineSubtitle(local, root) {
+  const home = prettyPath(local.homeDir);
+  if (!local.projectActive()) return `${home} (home tier only — no project .lorekit/ yet)`;
+  const projRel = path.relative(root, local.projectDir) || local.projectDir;
+  return `${projRel} + ${home}`;
+}
+
+export async function list(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  const scopeInfo = deriveScope(root);
+  // Default to every applicable scope; `--scope <s>` narrows to one (an explicit
+  // scope outside the applicable set is honoured — the user asked for it).
+  const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeList(scopeInfo);
+
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+
+  // A `LOREKIT_DENY=remote|local` privacy/compliance ceiling (deny-wins, never
+  // overridable) suppresses that section entirely — the same invariant the
+  // agent-facing control model enforces, honored here in the human read view.
+  const control = loadControl(root, { env });
+  const deny = (mode) => control.denies.find((d) => d.mode === mode) || null;
+  const localDenied = deny('local');
+  const remoteDenied = deny('remote');
+
+  const offline = localDenied ? { groups: [], total: 0 } : await gather(local, scopes);
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteResult = remoteAvailable ? await gather(remote, scopes) : { groups: [], total: 0 };
+
+  const offlineSection = localDenied
+    ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
+    : { available: true, ...offline };
+  const remoteSection = remoteAvailable
+    ? { available: true, ...remoteResult }
+    : {
+        available: false,
+        reason: remoteDenied
+          ? `disabled by deny constraint (${remoteDenied.source})`
+          : remoteUnavailableReason(connection),
+      };
+
+  if (args.json) {
+    log(JSON.stringify(buildJson({ root, scopes, offlineSection, remoteSection }), null, 2));
+  } else {
+    heading('LoreKit lessons');
+    log(`  project: ${c.dim(root)}`);
+    log(`  scopes:  ${scopes.join('  →  ')}`);
+
+    renderSection(
+      { title: 'Offline', subtitle: localDenied ? undefined : offlineSubtitle(local, root) },
+      offlineSection,
+    );
+    renderSection(
+      { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined },
+      remoteSection,
+    );
+
+    log('');
+  }
+
+  // Bounded, non-PII telemetry extras (counts + a boolean) — never a scope
+  // string, path, key, or token.
+  return {
+    exitCode: 0,
+    'lorekit.cli.list.scope_count': scopes.length,
+    'lorekit.cli.list.offline_count': offline.total,
+    'lorekit.cli.list.remote_count': remoteResult.total,
+    'lorekit.cli.list.remote_available': remoteAvailable,
+  };
+}
+
+// The `--json` payload: normalized groups per section so a script gets the same
+// shape regardless of which store an entry came from.
+function buildJson({ root, scopes, offlineSection, remoteSection }) {
+  return { root, scopes, offline: sectionJson(offlineSection), remote: sectionJson(remoteSection) };
+}
+
+function sectionJson(section) {
+  if (!section.available) {
+    return { available: false, reason: section.reason, total: 0, groups: [] };
+  }
+  return {
+    available: true,
+    total: section.total,
+    groups: (section.groups || []).map((g) => ({
+      scope: g.scope,
+      error: g.error || null,
+      // `gather()` already normalized these entries; no second pass needed.
+      entries: g.entries,
+    })),
+  };
+}

package/src/stores.mjs

@@ -0,0 +1,49 @@
+// Resolve BOTH memory stores at once — the offline (local two-tier) store and
+// the remote (hosted MCP) store — independent of the active control mode. The
+// read commands (`list`, and the stacked `search` / `show` / `stats` / `diff`)
+// want to show whatever lives in each place side by side, so unlike
+// `createStore(control)` (which picks exactly one by mode) this builds both.
+//
+// Nothing here invents scope or connection logic: it composes the existing
+// `localStoreDirs` (two-tier dirs), `resolveProjectConnection` + `splitEndpoint`
+// (endpoint/token from .mcp.json → global → env), and the store builders.
+// Zero-dependency.
+import process from 'node:process';
+import { localStoreDirs } from './control.mjs';
+import { resolveProjectConnection } from './config.mjs';
+import { splitEndpoint } from './mcp.mjs';
+import { createTwoTierStore, createRemoteStore } from './store/index.mjs';
+
+// Build both stores for `root`. Explicit `endpoint` / `token` (e.g. from
+// `--endpoint` / `--token` flags) take precedence over the resolved connection;
+// `env` feeds the local-tier directory resolution ($LOREKIT_HOME / $LOREKIT_STORE).
+// Returns { local, remote, connection } — `connection` is the resolved
+// endpoint/token so callers can explain why remote is unusable.
+export function resolveStores(root, { env = process.env, endpoint = null, token = null } = {}) {
+  const dirs = localStoreDirs(root, env);
+  const local = createTwoTierStore(dirs);
+
+  const conn = resolveProjectConnection(root, splitEndpoint);
+  const resolvedEndpoint = endpoint || conn.endpoint || null;
+  const resolvedToken = token || conn.token || null;
+  const remote = createRemoteStore({ endpoint: resolvedEndpoint, token: resolvedToken });
+
+  return {
+    local,
+    remote,
+    connection: { endpoint: resolvedEndpoint, token: resolvedToken },
+  };
+}
+
+// A bounded, actionable reason a remote listing is unavailable — mirrors the
+// checks in `RemoteStore.usable()` so the note tells the user what to fix.
+export function remoteUnavailableReason({ endpoint, token } = {}) {
+  if (!endpoint) return 'no endpoint configured — run `lorekit install` or set LOREKIT_MCP_URL';
+  if (String(endpoint).includes('<project-ref>')) return `endpoint is still a placeholder (${endpoint})`;
+  if (!token) return 'no token configured — set LOREKIT_TOKEN or run `lorekit install`';
+  // Defensive catch-all: unreachable while this mirrors `RemoteStore.usable()` —
+  // callers only reach here when the remote is unusable, so one check above has
+  // already fired. Kept as a total return (never a throw): this helper is on the
+  // graceful read path and must never break the listing.
+  return 'not configured';
+}

package/src/telemetry.mjs

@@ -34,7 +34,7 @@ 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 FLAG_ATTRS = ['global', 'project', 'deep', 'yes', 'force', 'no-hooks', 'json'];
 
 const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disable', 'disabled']);