@lorekit/cli 1.55.3 → 1.57.0

package/src/shared/obligations-map.mjs

@@ -0,0 +1,154 @@
+// The Surface-Partner Map — a declarative registry of known, path-keyed file
+// partnerships in this repo. This is slice 1 of the fix for a structural
+// retrieval leak the `dash0-dev` review bot repeatedly flags: a fix to one
+// surface (a mirrored module, a doc that copies a claim, a generated artifact,
+// a required test assertion) leaves its PARTNER surface stale, because the
+// lessons documenting each partnership are retrieved lexically (FTS +
+// recency) and rarely surface at edit time for the exact file just touched.
+//
+// Every entry here is SEEDED from an existing, real CI guard — it duplicates
+// no enforcement, it just makes the partnership visible to `lorekit
+// obligations` (see `../commands/obligations.mjs`) BEFORE the guard runs, so
+// a human or agent can sweep the partner in the same commit instead of
+// discovering the gap in review. `guard` names that real spec/script per
+// entry; entries with no automated guard (`perf-index`, `error-code-doc`) say
+// so explicitly rather than implying one exists.
+//
+// Entry schema:
+//   {
+//     id: string,               // stable identifier
+//     match: string|string[],   // repo-relative glob(s); a `re:` prefix is
+//                                // used as a verbatim RegExp; `**/{name}` or
+//                                // `{name}` binds the matched module's
+//                                // relative path (dirs + stem, extension
+//                                // stripped) for reuse in `obliges`
+//     obliges: Array<string | string[]>,
+//                                // each element is EITHER a required partner
+//                                // path/glob (may reuse `{name}`), a
+//                                // `run:<action>` advisory (never gates
+//                                // --strict), OR an array of alternative
+//                                // paths satisfied by ANY ONE of them (used
+//                                // when a name-derived module's real partner
+//                                // could live under either of two sibling
+//                                // directories)
+//     lessonKey: string,        // canonical memory key to cite
+//     guard?: string,           // the existing CI spec/script that enforces
+//                                // this partnership, if any
+//     note?: string,            // why this entry exists / its limitations
+//   }
+//
+// See `obligations-pure.mjs` for the matcher and the exact `{name}` grammar.
+//
+// The `edge-mirror` / `edge-mirror-core` rows below are a special case: they
+// are GENERATED, one pair of rows per entry in `mirrorPairs`
+// (`./mirror-pairs.mjs`, the single-source inventory shared with
+// `packages/mcp-core/src/edge/edge-parity.spec.ts`), rather than hand-authored
+// with a `{name}`-substituting glob. A glob assuming the edge copy mirrors
+// mcp-core's directory structure false-positives whenever a real mirror
+// flattens or renames it (e.g. `packages/mcp-core/src/auth/auth-token.ts` ↔
+// the FLAT `supabase/functions/mcp/auth-token.ts`) — the exact-path
+// reconstruction it would need to get right is simply not derivable from the
+// two paths alone. Enumerating each KNOWN pair's real partner has no such
+// assumption to violate. `checkObligations` already merges every map entry
+// that shares an `id` into one reported bucket (see `obligations-pure.mjs`'s
+// `byId` merge in the matcher), so the many generated rows below still
+// surface as the two logical `edge-mirror` / `edge-mirror-core` entries.
+
+import { mirrorPairs } from './mirror-pairs.mjs';
+
+// The flagship recurrence class: a partner copies a CLAIM (a mirrored
+// module's behavior, a generated artifact's content, a documented mechanism)
+// and goes stale when the source changes. Cited by every entry below whose
+// obligation is "this partner copies what you just changed."
+const COPIES_A_CLAIM_LESSON =
+  'implement-suggestion-lessons::a-mechanism-clause-you-correct-in-the-pr-body-must-be-corrected-in-every-doc-that-copies-it';
+
+// The registered-everywhere / sibling-set recurrence class: adding or moving
+// something that a SET of surfaces enumerates (a doc listing every command,
+// a generated mirror listing every file) re-flags every surface that lists
+// the set and now has a hole.
+const SIBLING_SET_LESSON = 'aw-lessons::docs-drift-grep-must-search-names-not-invocation';
+
+const EDGE_MIRROR_GUARD = 'packages/mcp-core/src/edge/edge-parity.spec.ts';
+
+// One `{ match, obliges }` row PER KNOWN PAIR, in both directions — see the
+// module-level note above for why this replaces a `{name}`-templated glob.
+const EDGE_MIRROR_ENTRIES = mirrorPairs.flatMap(({ core, edge }) => [
+  {
+    id: 'edge-mirror',
+    match: edge,
+    obliges: [core],
+    lessonKey: COPIES_A_CLAIM_LESSON,
+    guard: EDGE_MIRROR_GUARD,
+    note: 'An edge (Deno) module mirrored self-contained from mcp-core — edit one, mirror the other. Partner looked up from the shared mirror-pairs inventory, never reconstructed from an assumed-symmetric path.',
+  },
+  {
+    id: 'edge-mirror-core',
+    match: core,
+    obliges: [edge],
+    lessonKey: COPIES_A_CLAIM_LESSON,
+    guard: EDGE_MIRROR_GUARD,
+    note: 'The reverse direction of edge-mirror — a mcp-core source file changed, its known edge mirror (from the same mirror-pairs inventory) is the partner.',
+  },
+]);
+
+export const SURFACE_PARTNER_MAP = [
+  ...EDGE_MIRROR_ENTRIES,
+  {
+    id: 'tool-catalog',
+    match: 'packages/schemas/src/shared/tool-catalog.ts',
+    obliges: [
+      'supabase/functions/mcp/tool-dispatch.generated.ts',
+      'packages/cli/src/surfaces.generated.mjs',
+      'packages/web/public/llms.txt',
+      'run:pnpm nx generate:llms schemas',
+    ],
+    lessonKey: COPIES_A_CLAIM_LESSON,
+    guard: 'packages/mcp-core/src/mcp-guards/tool-catalog-parity.spec.ts, scripts/codegen/gen-surfaces.mjs --check',
+    note: 'The catalog is the single origin of the operation surface — every generated projection of it must be regenerated in the same commit.',
+  },
+  {
+    id: 'llms-generated',
+    match: ['packages/schemas/src/llms/template.md', 'packages/schemas/src/shared/tool-catalog.ts'],
+    obliges: ['packages/web/public/llms.txt', 'run:pnpm nx generate:llms schemas'],
+    lessonKey: COPIES_A_CLAIM_LESSON,
+    guard: 'packages/schemas/src/llms/render.spec.ts',
+    note: 'llms.txt is GENERATED — never hand-edited; the committed file must be what the generator produces from these two sources.',
+  },
+  {
+    id: 'docs-section',
+    match: 're:^packages/web/src/content/docs/[^/]+\\.mdx$',
+    obliges: ['packages/web/src/lib/docs/sections.ts'],
+    lessonKey: SIBLING_SET_LESSON,
+    guard: 'packages/web/src/lib/docs/sections.spec.ts',
+    note: 'A new/removed docs page needs its DOCS_SECTIONS entry, or the site index and the page itself drift apart.',
+  },
+  {
+    id: 'plugin-skill',
+    match: 'packages/cli/skill/**',
+    obliges: ['run:node scripts/codegen/sync-plugin-skill.mjs', 'plugins/lorekit-claude/skills/**'],
+    lessonKey: SIBLING_SET_LESSON,
+    guard: 'scripts/codegen/sync-plugin-skill.mjs --check',
+    note: 'The Claude plugin vendors a copy of every skill/* source — regenerate the mirror, never hand-edit it.',
+  },
+  {
+    id: 'perf-index',
+    match: 're:^supabase/migrations/.*index.*\\.sql$',
+    obliges: ['supabase/tests/migrations.test.sql'],
+    lessonKey: SIBLING_SET_LESSON,
+    guard: null,
+    note: 'Convention only — a real gap. A new index migration has no automated nudge to add its coverage to the migrations test.',
+  },
+  {
+    id: 'error-code-doc',
+    match: ['supabase/functions/mcp/mcp-handler.ts', 'packages/mcp-core/src/auth/account-wide-tools.ts'],
+    obliges: [
+      'docs/mcp-tools.md',
+      'packages/schemas/src/llms/template.md',
+      'packages/web/public/llms.txt',
+    ],
+    lessonKey: COPIES_A_CLAIM_LESSON,
+    guard: null,
+    note: 'A documented path-proxy, not a content predicate — obligations sees file paths, not diffs, so it cannot tell an error-const edit from an unrelated one in the same file and may over-flag. Advisory only (never gates unless --strict, and even then it is one signal among several).',
+  },
+];

package/src/shared/obligations-pure.mjs

@@ -0,0 +1,246 @@
+// Pure, DEPENDENCY-FREE matcher for the Surface-Partner Map (`obligations-map.mjs`).
+//
+// The problem this solves: a fix to one surface (a mirrored module, a doc that
+// copies a claim, a generated artifact) routinely leaves its PARTNER surface
+// stale, because the ~45 memory lessons documenting each known partnership are
+// retrieved lexically (FTS + recency) and never surface at edit time for a
+// specific file. Since the recurrences are known, PATH-KEYED file
+// partnerships, a deterministic path-keyed check beats search — this module is
+// that check.
+//
+// Zero imports on purpose (mirrors `lessons-pure.mjs`) and NEVER touches the
+// filesystem or `process.cwd()` — see the module-level note in
+// `obligations-map.mjs`. It matches the path STRINGS it is given against the
+// map; the IO shell (`commands/obligations.mjs`) resolves those strings from
+// argv/stdin.
+//
+// ── the `{name}` placeholder ────────────────────────────────────────────────
+//
+// A `match`/`obliges` glob may contain the literal token `{name}` to bind the
+// module's relative path (directories + file stem, extension stripped) so a
+// generic partnership (`edge-mirror`) doesn't need one map entry per module.
+// The token is recognised in two shapes:
+//
+//   `**/{name}`  — ONE capturing group spanning zero or more path segments
+//                  AND the final stem, e.g. `src/**/{name}.ts` captures
+//                  `audit/audit` out of `src/audit/audit.ts`, for reuse in a
+//                  partner pattern's own `**/{name}` slot. This ONLY works
+//                  when the partner's directory structure is a predictable
+//                  function of the source's — e.g. `docs-section`'s
+//                  `sections.ts` entry needs no name at all, so it's not used
+//                  there either. It is NOT used by the seed map's
+//                  `edge-mirror`/`edge-mirror-core` entries (see
+//                  `obligations-map.mjs`): a real edge (Deno) mirror does not
+//                  reliably preserve mcp-core's directory structure — it may
+//                  flatten or rename it — so those two entries instead
+//                  enumerate every KNOWN pair's exact partner from a
+//                  single-source inventory (`mirror-pairs.mjs`) rather than
+//                  reconstruct a partner path via substitution. The token
+//                  remains available here as a general primitive for any
+//                  future map entry whose partner path genuinely IS a
+//                  predictable function of the source's.
+//   `{name}`     — a single-segment capturing group (no preceding `**/`) for
+//                  a flat `{name}.ext` match with no directory component.
+//
+// `stemOf` (below) is the simpler, general-purpose primitive — a plain
+// basename-without-extension — exported for standalone use and unit testing.
+
+export const RUN_PREFIX = 'run:';
+export const REGEX_PREFIX = 're:';
+
+const NAME_TOKEN = '{name}';
+const DIR_NAME_TOKEN = `**/${NAME_TOKEN}`;
+
+// Basename of `path`, extension stripped. A leading-dot file (`.env`) is its
+// own stem (no extension to strip) rather than an empty string.
+export function stemOf(path) {
+  const base = String(path ?? '').split('/').pop() ?? '';
+  const dot = base.lastIndexOf('.');
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+
+// Escape one character for literal inclusion in a RegExp source string.
+function escapeChar(ch) {
+  return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+
+// Compile a single glob/regex pattern string into `{ regex, capturesName }`.
+// `re:`-prefixed patterns are used verbatim (already anchored by the author,
+// per the seed map's `docs-section`/`perf-index` entries) and never capture a
+// name. Anything else is compiled token-by-token: `**/{name}` and bare
+// `{name}` become the ONE capturing group a pattern may have, `**` becomes
+// `.*`, `*` becomes `[^/]*`, and every other character is escaped literally.
+// Returns null for a non-string / empty pattern, never throws.
+export function compilePattern(pattern) {
+  if (typeof pattern !== 'string' || !pattern) return null;
+  if (pattern.startsWith(REGEX_PREFIX)) {
+    try {
+      return { regex: new RegExp(pattern.slice(REGEX_PREFIX.length)), capturesName: false };
+    } catch {
+      return null;
+    }
+  }
+  let src = '';
+  let capturesName = false;
+  let i = 0;
+  while (i < pattern.length) {
+    if (pattern.startsWith(DIR_NAME_TOKEN, i)) {
+      src += '(.+)';
+      capturesName = true;
+      i += DIR_NAME_TOKEN.length;
+    } else if (pattern.startsWith(NAME_TOKEN, i)) {
+      src += '([^/]+)';
+      capturesName = true;
+      i += NAME_TOKEN.length;
+    } else if (pattern.startsWith('**', i)) {
+      src += '.*';
+      i += 2;
+    } else if (pattern[i] === '*') {
+      src += '[^/]*';
+      i += 1;
+    } else {
+      src += escapeChar(pattern[i]);
+      i += 1;
+    }
+  }
+  return { regex: new RegExp(`^${src}$`), capturesName };
+}
+
+// Compile `glob` into a plain, non-capturing-aware `RegExp` — the general
+// membership test used both to check whether a changed file satisfies a
+// (post-substitution) oblige target, and by tests exercising the glob syntax
+// in isolation. Same token grammar as `compilePattern`; a `{name}` left
+// unsubstituted (never expected once `checkObligations` has run) simply
+// compiles to its capturing form, still usable as a plain matcher.
+export function globToRegExp(glob) {
+  return compilePattern(glob)?.regex ?? null;
+}
+
+// Replace the pattern's name placeholder with a captured value. `**/{name}`
+// is replaced as ONE unit (so the substitution reconstructs a full relative
+// path, matching how `compilePattern` captured it); a bare `{name}` is
+// replaced on its own. `name == null` (no capture in the matching `match`
+// pattern) returns `pattern` unchanged — nothing to substitute.
+export function substituteName(pattern, name) {
+  if (name == null || typeof pattern !== 'string') return pattern;
+  if (pattern.includes(DIR_NAME_TOKEN)) return pattern.split(DIR_NAME_TOKEN).join(name);
+  if (pattern.includes(NAME_TOKEN)) return pattern.split(NAME_TOKEN).join(name);
+  return pattern;
+}
+
+// Does `file` satisfy `globPattern` (post-substitution, so no `{name}` token
+// remains, but `**`/`*` wildcards may)? Compiles and tests in one step; an
+// uncompilable pattern never matches.
+function fileSatisfies(file, globPattern) {
+  const regex = globToRegExp(globPattern);
+  return regex ? regex.test(file) : false;
+}
+
+// Fold one `obliges` element into `bucket` (a `Map<target, row>` keyed by the
+// rendered target string, so repeated matches — several changed files hitting
+// the same entry — dedupe by the concrete, substituted target rather than by
+// raw template).
+//
+// An element is one of:
+//   `run:<action>`        — advisory, `kind:'action'`, `met: null`, never
+//                            gates `--strict`.
+//   a string               — a single required path/glob, `kind:'path'`.
+//   an array of strings    — an "any of" group: the obligation is met if ANY
+//                            candidate is present in `changedFiles` (for a
+//                            partner that could legitimately live in more
+//                            than one place). Rendered as one row whose
+//                            `target` joins every candidate with ` OR `,
+//                            `met` true iff any candidate matches. The seed
+//                            map's `edge-mirror`/`edge-mirror-core` entries do
+//                            NOT use this — see `obligations-map.mjs` — since
+//                            enumerating each known pair's exact partner from
+//                            `mirror-pairs.mjs` needs no "either of" guess.
+// A row already present for the same rendered target has its `met` OR'd in
+// (never downgraded from true to false by a later, differently-named match).
+function addOblige(bucket, rawOblige, name, changedFiles) {
+  if (typeof rawOblige === 'string' && rawOblige.startsWith(RUN_PREFIX)) {
+    if (!bucket.has(rawOblige)) bucket.set(rawOblige, { target: rawOblige, kind: 'action', met: null });
+    return;
+  }
+  const candidates = (Array.isArray(rawOblige) ? rawOblige : [rawOblige])
+    .filter((c) => typeof c === 'string' && c);
+  if (candidates.length === 0) return;
+  const substituted = candidates.map((c) => substituteName(c, name));
+  const met = substituted.some((c) => changedFiles.some((f) => fileSatisfies(f, c)));
+  const target = substituted.join(' OR ');
+  const existing = bucket.get(target);
+  if (existing) existing.met = existing.met || met;
+  else bucket.set(target, { target, kind: 'path', met });
+}
+
+/**
+ * Check a changed-file set against the Surface-Partner Map. For every
+ * `(file, entry)` pair where `file` satisfies one of `entry.match`'s
+ * patterns, the entry is recorded as matched and its `obliges` are resolved
+ * (with `{name}` substituted from whatever the matching pattern captured) and
+ * checked for membership in `changedFiles`. Entries are deduped by `id` — a
+ * file set can hit the same entry via several files, and each contributes its
+ * own name-substituted targets into that one entry's `obliges` list.
+ *
+ * Pure and total: a malformed `map`/`changedFiles` degrades to no matches
+ * rather than throwing.
+ *
+ * Returns `{ files, matched, unmet, ok }` — see `obligations-map.mjs`'s
+ * schema docblock for the shape of each `matched` entry.
+ */
+export function checkObligations({ changedFiles = [], map = [] } = {}) {
+  const files = Array.isArray(changedFiles)
+    ? changedFiles.filter((f) => typeof f === 'string' && f.length > 0)
+    : [];
+  const entries = Array.isArray(map) ? map : [];
+
+  const byId = new Map(); // id -> { id, lessonKey, guard, note, obliges: Map<target, row> }
+
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object' || !entry.id) continue;
+    const patterns = Array.isArray(entry.match) ? entry.match : [entry.match];
+
+    for (const file of files) {
+      let matched = false;
+      let name = null;
+      for (const pattern of patterns) {
+        const compiled = compilePattern(pattern);
+        if (!compiled) continue;
+        const m = compiled.regex.exec(file);
+        if (m) {
+          matched = true;
+          if (compiled.capturesName) name = m[1];
+          break;
+        }
+      }
+      if (!matched) continue;
+
+      let bucket = byId.get(entry.id);
+      if (!bucket) {
+        bucket = {
+          id: entry.id,
+          lessonKey: entry.lessonKey ?? null,
+          guard: entry.guard ?? null,
+          note: entry.note ?? null,
+          obliges: new Map(),
+        };
+        byId.set(entry.id, bucket);
+      }
+      for (const rawOblige of Array.isArray(entry.obliges) ? entry.obliges : []) {
+        addOblige(bucket.obliges, rawOblige, name, files);
+      }
+    }
+  }
+
+  const matched = [...byId.values()].map((b) => ({
+    id: b.id,
+    lessonKey: b.lessonKey,
+    guard: b.guard,
+    note: b.note,
+    obliges: [...b.obliges.values()],
+  }));
+
+  const unmet = matched.reduce((n, e) => n + e.obliges.filter((o) => o.met === false).length, 0);
+
+  return { files, matched, unmet, ok: unmet === 0 };
+}

package/src/telemetry/telemetry.mjs

@@ -5,7 +5,7 @@
 // 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 / scopes / diff /
-// tree / lint / dedupe / link / migrate), fired to Dash0 so the maintainers can
+// tree / lint / dedupe / obligations / link / 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:
@@ -655,25 +655,28 @@ function normalizeExitCode(result) {
  * Run a MACHINE-facing command (`hook`, `mcp`) and count the invocation —
  * counter only, no span. Returns the command's exit code unchanged.
  *
- * The export is STARTED BEFORE the command runs and awaited after, so it
- * overlaps the command's own work instead of being serialized behind it. That
- * ordering is what makes this affordable on `hook`, which fires several times
- * per agent turn: by the time there is anything to await, the POST has usually
- * already completed, and {@link METERED_TIMEOUT_MS} caps the worst case.
+ * The two commands are counted at DIFFERENT times, for a reason specific to
+ * each:
  *
- * It also makes the count robust for `mcp`, which is a LONG-LIVED stdio server —
- * `run()` does not return until the server exits, and a killed server would
- * never have reported at all if the export waited for it. Since the counter
- * reports the invocation rather than its outcome (a machine-facing command's
- * verdict belongs to its stdout contract, which the host reads), there is
- * nothing to learn by waiting.
+ *   • `mcp` is a LONG-LIVED stdio server — `run()` does not return until the
+ *     server exits, and a killed server would never report at all if the export
+ *     waited for it. So its count fires BEFORE run and is awaited after, which
+ *     also overlaps the export with the server's own startup. It carries no
+ *     outcome: a server's verdict belongs to its stdout contract.
+ *   • `hook` is short-lived and fires several times per agent turn. It is
+ *     counted AFTER run so the counter can carry the health dimensions run
+ *     reports (`lorekit.hook.event` + `lorekit.hook.outcome`) — the difference
+ *     between a healthy hook and one silently degrading (an unusable store, a
+ *     swallowed lookup error) that a bare invocation ping cannot show. The extra
+ *     latency is run's own duration (a hook is tens of ms); the
+ *     {@link METERED_TIMEOUT_MS} export cap dominates either way.
  *
  * Nothing here can affect the command: the exit code is passed through
  * untouched, and every telemetry failure is swallowed.
  *
  * @param {string} command  `hook` | `mcp`
  * @param {string} version  CLI version
- * @param {() => Promise<number>} run  the command handler
+ * @param {() => Promise<number | { exitCode?: number, meter?: object }>} run  the command handler
  */
 export async function meterCommand(command, version, run) {
   let config;
@@ -688,15 +691,26 @@ export async function meterCommand(command, version, run) {
   // cost nothing at all: no identity read, no timer, no promise.
   if (!config.enabled) return normalizeExitCode(await run());
 
-  // `.catch` attached IMMEDIATELY, before any await: an unawaited rejecting
-  // promise is an unhandled rejection, which on a machine-facing command would
-  // print to stderr and pollute a host's log.
-  const pending = countInvocation(config, command, version).catch(() => {});
-  try {
-    return normalizeExitCode(await run());
-  } finally {
-    await pending;
+  // Long-lived server: count before run (see docblock). `.catch` attached
+  // IMMEDIATELY, before any await: an unawaited rejecting promise is an
+  // unhandled rejection, which on a machine-facing command would print to
+  // stderr and pollute a host's log.
+  if (command === 'mcp') {
+    const pending = countInvocation(config, command, version).catch(() => {});
+    try {
+      return normalizeExitCode(await run());
+    } finally {
+      await pending;
+    }
   }
+
+  // Short-lived hook: count after run so the counter carries what run reported.
+  // A `meter` object on the result is the health payload; anything else (a bare
+  // exit code) counts with no extra dimensions.
+  const result = await run();
+  const meter = (result && typeof result === 'object' && result.meter) ? result.meter : {};
+  await countInvocation(config, command, version, meter).catch(() => {});
+  return normalizeExitCode(result);
 }
 
 /**
@@ -709,7 +723,7 @@ export async function meterCommand(command, version, run) {
  * `lint` finding) reports `lorekit.cli.outcome=failure` on a span the exporter
  * emits as STATUS_CODE_OK — never ERROR.
  *
- * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | scopes | diff | tree | lint | dedupe | link | migrate
+ * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | scopes | diff | tree | lint | dedupe | obligations | link | 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