@lorekit/cli 1.30.0 → 1.30.2

package/README.md

@@ -78,7 +78,18 @@ In a TTY it prompts for the scope (and for `--endpoint` / `--token` if missing).
 Flags: `--project` / `--global` pick the scope non-interactively; `--yes` runs
 non-interactively (endpoint required via flag/env; scope defaults to project);
 `--force` overwrites an existing skill copy. Re-running is idempotent — the hook
-entries are updated in place, never duplicated.
+entries are updated in place, never duplicated, and an event that somehow ended
+up with **several** lorekit entries (the marketplace plugin wired on top of a CLI
+install, a merged `settings.json`, a hand edit) is collapsed back to exactly one,
+reported as `N duplicate(s) removed`.
+
+That repair runs on the hook-wiring step, which a plain `lorekit install` **skips**
+on an already-complete install — it short-circuits to the "already installed"
+summary instead. So if your hooks are firing twice, run `lorekit install --force`,
+or re-state the wiring you want with `lorekit install --hooks all` (or
+`--hooks read-only`); both reach the hook step and collapse the duplicates for the
+events they wire. `--hooks none` also reaches the hook step, but it is a teardown,
+not a repair — it removes every lorekit hook instead of collapsing the copies.
 
 #### Choosing the hooks
 

package/package.json

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

package/src/config.mjs

@@ -92,8 +92,19 @@ export const CLAUDE_HOOK_EVENTS = ['SessionStart', 'PostToolUseFailure', 'Stop']
 // Matches a hook command that fires the lorekit engine, whether wired as a
 // global `lorekit hook …` or `npx -y @lorekit/cli hook …`. Shared by the
 // upsert (find-or-update) and remove (uninstall) paths so they agree on what
-// counts as "ours".
-export const LOREKIT_HOOK_RE = /(?:@lorekit\/cli|lorekit) hook\b/;
+// counts as "ours" — a form this misses is not merely un-updated, it is
+// APPENDED alongside on the next install, which is how a settings.json ends up
+// firing the same hook twice.
+//
+// The three deliberate tolerances, each a real wiring seen in the wild:
+//   • a leading path or quote — `/usr/local/bin/lorekit hook`, `"…/lorekit" hook`
+//   • a pinned version        — `npx -y @lorekit/cli@1.2.3 hook`
+//   • a platform extension    — `lorekit.cmd hook` on Windows
+// The leading boundary is REQUIRED (start of string, whitespace, a path
+// separator or a quote) so an unrelated `mylorekit hook …` is somebody else's
+// command and stays untouched — the previous pattern claimed it.
+export const LOREKIT_HOOK_RE =
+  /(?:^|[\s"'`(=/\\])(?:@lorekit\/cli|lorekit)(?:@[^\s"']+)?(?:\.(?:cmd|exe|bat|ps1|mjs|js))?\s+hook\b/;
 
 // npx stages the package's own bin into an ephemeral cache dir
 // (…/_npx/<hash>/node_modules/.bin) and prepends it to PATH for the lifetime of
@@ -211,6 +222,16 @@ export function installedHookEvents(root, scope = 'project') {
 // existing lorekit hook entry per event is updated in place, never duplicated.
 // `runner` is the command prefix (e.g. 'lorekit' or 'npx -y @lorekit/cli').
 //
+// CONVERGENT, not merely additive: an event carrying SEVERAL lorekit entries
+// keeps exactly ONE — the first is updated in place and every further one is
+// deleted (counted as `deduped`). Reconciling only the first left the extras
+// firing forever, and `install --force` — the one command a user reaches for
+// precisely because the wiring is wrong — could not repair the very state it is
+// most often run against. Duplicates arrive from outside this function (the
+// marketplace plugin wiring `npx -y @lorekit/cli hook …` over a CLI-wired bare
+// `lorekit hook …`, a merged settings.json, a hand edit), so recognising them
+// on write is the only place the invariant can hold.
+//
 // `events` selects WHICH of CLAUDE_HOOK_EVENTS to wire (default: all of them).
 // Any lorekit entry for a CLAUDE_HOOK_EVENT *not* in the list is REMOVED — that
 // pruning is what makes a downgrade (all → read-only) an actual downgrade rather
@@ -226,6 +247,7 @@ export function upsertClaudeHooks(root, scope, runner, events = CLAUDE_HOOK_EVEN
   let updated = 0;
   let unchanged = 0;
   let removed = 0;
+  let deduped = 0;
 
   for (const event of CLAUDE_HOOK_EVENTS) {
     if (!wanted.has(event)) {
@@ -236,31 +258,48 @@ export function upsertClaudeHooks(root, scope, runner, events = CLAUDE_HOOK_EVEN
     if (!Array.isArray(config.hooks[event])) config.hooks[event] = [];
     const groups = config.hooks[event];
 
-    let existing = null;
+    // EVERY lorekit entry for this event, in document order — not just the
+    // first, which is what made a duplicated file un-repairable.
+    const matches = [];
     for (const group of groups) {
-      const inner = group && Array.isArray(group.hooks) ? group.hooks : [];
-      existing = inner.find(
-        (h) => h && typeof h.command === 'string' && LOREKIT_HOOK_RE.test(h.command),
-      );
-      if (existing) break;
+      if (!group || !Array.isArray(group.hooks)) continue;
+      for (const hook of group.hooks) {
+        if (hook && typeof hook.command === 'string' && LOREKIT_HOOK_RE.test(hook.command)) {
+          matches.push({ group, hook });
+        }
+      }
     }
 
-    if (existing) {
-      if (existing.command === command) unchanged++;
+    const [canonical, ...extras] = matches;
+    if (canonical) {
+      if (canonical.hook.command === command) unchanged++;
       else {
-        existing.command = command;
+        canonical.hook.command = command;
         updated++;
       }
     } else {
       groups.push({ hooks: [{ type: 'command', command }] });
       added++;
     }
+
+    // Drop the surplus copies, then tidy only the groups this emptied — a group
+    // that arrived empty is somebody else's business, and a group still holding
+    // a third-party hook must survive.
+    const emptied = new Set();
+    for (const extra of extras) {
+      extra.group.hooks = extra.group.hooks.filter((h) => h !== extra.hook);
+      deduped++;
+      if (extra.group.hooks.length === 0) emptied.add(extra.group);
+    }
+    if (emptied.size > 0) {
+      config.hooks[event] = groups.filter((g) => !emptied.has(g));
+    }
   }
 
   if (Object.keys(config.hooks).length === 0) delete config.hooks;
 
   writeFileAtomic(file, JSON.stringify(config, null, 2) + '\n');
-  return { file, added, updated, unchanged, removed };
+  return { file, added, updated, unchanged, removed, deduped };
 }
 
 // Drop every lorekit hook entry for one event from a hooks object, tidying up

package/src/deeplink-pure.mjs

@@ -29,7 +29,15 @@ export const LORE_PARAM_DEFAULTS = {
   q: '', // string search query
   range: null, // { from, to } | null (DateRange, "YYYY-MM-DD")
   owner: 'all', // 'all' | 'personal' | { orgId }
-  tags: [], // string[] — label filter (AND across labels); [] means "no filter"
+  // Filter[] | null — the Explorer's multi-dimension filter bar (label / agent /
+  // trigger / repo / branch / pr). `null`, NOT `[]`, is the default on purpose:
+  // the app has to tell "the param is absent" from "the bar is explicitly
+  // empty", because an absent `filters` falls back to the legacy `tags`
+  // shorthand while an empty one deliberately does not. Encoding `[]` here
+  // would emit the param (it is not the default) and mean the opposite of
+  // "unfiltered".
+  filters: null,
+  tags: [], // string[] — legacy label filter (AND across labels); [] means "no filter". Still READ by the app, superseded by `filters`
   view: 'scope', // 'scope' | 'time'
   archived: false, // boolean
   lesson: null, // { scope, key } | null — opens the detail sheet
@@ -37,9 +45,9 @@ export const LORE_PARAM_DEFAULTS = {
 
 // A stable, readable param order (also makes URLs deterministic for tests).
 // Mirrors the `useUrlState` call order in `LoreExplorer.tsx` (+ the `lesson`
-// param last), so `tags` sits between `owner` and `view`. `scope` precedes
-// `lesson` so a lesson link reads `?scope=…&lesson=…`.
-const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'tags', 'view', 'archived', 'lesson'];
+// param last), so `filters` and `tags` sit between `owner` and `view`. `scope`
+// precedes `lesson` so a lesson link reads `?scope=…&lesson=…`.
+const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'filters', 'tags', 'view', 'archived', 'lesson'];
 
 // Strip trailing slashes from a base URL, falling back to the default when the
 // input is empty/absent. Pure.

package/src/install.mjs

@@ -438,11 +438,16 @@ export async function install(args) {
         : 'none — the skills still work, but memory stays model-invoked',
     );
   } else {
-    const n = hooks.added + hooks.updated + hooks.removed;
+    const n = hooks.added + hooks.updated + hooks.removed + hooks.deduped;
+    // `deduped` is reported separately from `removed`: removed is a wiring the
+    // user asked for (a downgrade), deduped is a repair of a settings file that
+    // was firing the same hook twice — silently fixing that would leave the
+    // doubled output they came here about unexplained.
     const hookParts = [
       hooks.added ? `${hooks.added} added` : '',
       hooks.updated ? `${hooks.updated} updated` : '',
       hooks.removed ? `${hooks.removed} removed` : '',
+      hooks.deduped ? `${hooks.deduped} duplicate(s) removed` : '',
     ].filter(Boolean);
     const hookState = n === 0 ? 'already wired' : hookParts.join(', ');
     const wired = hookEvents.length > 0 ? ` (${hookEvents.join(', ')})` : '';

package/src/telemetry.mjs

@@ -483,6 +483,11 @@ function normalizeExitCode(result) {
  * counter point. Returns the command's exit code unchanged. Telemetry failures
  * are swallowed — the command result is never affected.
  *
+ * The span carries an ERROR status only when the command CRASHED. A command
+ * that ran to completion and exited non-zero (a failing `doctor` check, a
+ * `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 {object} args     parsed CLI args (read for allow-listed flags only)
  * @param {string} version  CLI version (from package.json)
@@ -525,6 +530,10 @@ export async function traceCommand(command, args, version, run) {
 
   const startMs = Date.now();
   let exitCode = 0;
+  // `outcome` is the command's VERDICT (ok | failure | error); `status` is the
+  // SPAN status, and only a crash sets it to error. See the note above the
+  // non-zero-exit branch below.
+  let outcome = 'ok';
   let status = 'ok';
   let statusMessage;
   let extraAttrs = {};
@@ -543,11 +552,22 @@ export async function traceCommand(command, args, version, run) {
       }
     }
     if (typeof exitCode === 'number' && exitCode !== 0) {
-      status = 'error';
-      statusMessage = `exit ${exitCode}`;
+      // A non-zero exit is a REPORTED VERDICT, not a fault: `doctor` exits 1
+      // because a check it ran came back failing, and `lint` exits 1 because it
+      // found what it was asked to look for. Both commands did their job. Only
+      // a crash (the catch below) is an error, so `status` stays `'ok'` here —
+      // which `buildTracePayload` emits as STATUS_CODE_OK (1), the same status
+      // a zero-exit run gets — and the verdict is carried by
+      // `lorekit.cli.outcome=failure` +
+      // `lorekit.cli.exit_code` — which keeps the CLI's error rate a measure of
+      // the CLI being broken rather than of the user's environment being
+      // unhealthy. Query the failure verdicts on those attributes, never on the
+      // span status.
+      outcome = 'failure';
     }
     return exitCode;
   } catch (e) {
+    outcome = 'error';
     status = 'error';
     // Record only a bounded, non-PII identifier — NEVER e.message. Node fs /
     // network error messages embed absolute paths (e.g. "ENOENT: ... open
@@ -566,7 +586,7 @@ export async function traceCommand(command, args, version, run) {
       const attributes = commandAttributes({
         command,
         args,
-        outcome: status === 'error' ? 'error' : 'ok',
+        outcome,
         exitCode: typeof exitCode === 'number' ? exitCode : undefined,
         extraAttrs,
       });