@lorekit/cli 1.69.0 → 1.71.0

package/src/core/update-notify.mjs

@@ -0,0 +1,154 @@
+// SessionStart skill-update drift nudge: a terse, throttled line telling the
+// agent "your skills are stale, run `lorekit update`" — computed entirely
+// offline (see ../shared/skill-versions.mjs) and gated by `updates.notify`
+// (../shared/control.mjs).
+//
+// Throttle state lives at `$LOREKIT_HOME/update-state.json`, following the
+// exact precedent `telemetry/telemetry-identity.mjs` sets for a small,
+// user-owned JSON file under the home tier: TOTAL reads (a missing/corrupt
+// file degrades to `{}`, never throws), atomic writes via
+// `shared/config.mjs`'s `writeFileAtomic`, and the file is written ONLY when
+// there is something to record — never merely because this ran.
+//
+// The nudge fires at most once per NEW shipped-version signature, plus a
+// 7-day cooldown on repeating that same signature. `updates.notify: off`
+// short-circuits before any filesystem check runs, so an opted-out user's
+// disk is never touched by this module at all.
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { homeRoot } from '../shared/control.mjs';
+import { writeFileAtomic } from '../shared/config.mjs';
+import { checkSkillVersions, skillsNeedingUpdate } from '../shared/skill-versions.mjs';
+
+const STATE_FILE = 'update-state.json';
+const COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+/** `$LOREKIT_HOME/update-state.json`, default `~/.lorekit/update-state.json`. */
+export function updateStatePath(env = process.env) {
+  return path.join(homeRoot(env), STATE_FILE);
+}
+
+/**
+ * Read the stored throttle state, or `{}`. TOTAL — a missing file, an
+ * unreadable one, a corrupt body, or a body that parses but isn't the right
+ * shape all yield `{}`, exactly like `telemetry-identity.mjs`'s `readIdentity`.
+ */
+export function readUpdateState(file = updateStatePath()) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    const out = {};
+    if (typeof parsed.lastNotifiedVersion === 'string' && parsed.lastNotifiedVersion) {
+      out.lastNotifiedVersion = parsed.lastNotifiedVersion;
+    }
+    if (typeof parsed.lastNotifiedAt === 'number' && Number.isFinite(parsed.lastNotifiedAt)) {
+      out.lastNotifiedAt = parsed.lastNotifiedAt;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// Persist the throttle state, creating the home directory if needed. Returns
+// true on success, false on any failure (unwritable home, full disk) — a
+// write failure must not surface as an error, since a hook this fires from
+// must never break the host on a filesystem hiccup.
+function writeUpdateState(state, file = updateStatePath()) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify(state, null, 2)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A stable signature naming exactly which skills need an update and at which
+ * shipped version, e.g. `"lorekit-memory@1.2.0,lorekit-setup@1.1.0"`. Sorted
+ * by skill name so the signature is deterministic regardless of scan order.
+ *
+ * This — not a bare boolean — is what the throttle compares against: a NEW
+ * release (a shipped version bump) or a previously-current skill drifting
+ * produces a DIFFERENT signature, which re-qualifies for a nudge even inside
+ * the 7-day cooldown on the old one. `""` means nothing needs an update.
+ */
+export function driftSignature(results) {
+  const bySkill = new Map();
+  for (const r of skillsNeedingUpdate(results)) {
+    if (!r.shipped || bySkill.has(r.name)) continue;
+    bySkill.set(r.name, r.shipped);
+  }
+  return [...bySkill.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, shipped]) => `${name}@${shipped}`)
+    .join(',');
+}
+
+/**
+ * Render the one-line nudge, or `null` when nothing needs an update. De-duped
+ * by skill name (the same `name -> shipped` Map `driftSignature` builds) —
+ * `skillsNeedingUpdate` returns one row per (skill, scope), and without the
+ * dedupe a skill outdated in BOTH the project and global install would count
+ * itself twice in the "(+N more)" tail. An `unknown` row (no readable
+ * installed version — the drift signature counts it too, see
+ * `driftSignature`) still gets named, just without a "vX →" on its left side,
+ * so the nudge is never silently dropped for the one state that most needs a
+ * "go look" — a legacy install with no parseable version at all.
+ */
+export function formatUpdateNudge(results) {
+  const bySkill = new Map();
+  for (const r of skillsNeedingUpdate(results)) {
+    if (!r.shipped || bySkill.has(r.name)) continue;
+    bySkill.set(r.name, r);
+  }
+  const needing = [...bySkill.values()];
+  if (needing.length === 0) return null;
+  const [first, ...rest] = needing;
+  const extra = rest.length > 0 ? ` (+${rest.length} more)` : '';
+  const headline = first.installed
+    ? `${first.name} v${first.installed} → v${first.shipped}`
+    : `${first.name} → v${first.shipped}`;
+  return (
+    `LoreKit skills are outdated (${headline}${extra}). ` +
+    'Run `lorekit update` to refresh.'
+  );
+}
+
+/**
+ * The full resolve: should a SessionStart nudge fire right now, and if so,
+ * record the throttle state and return the text? `null` means stay silent —
+ * `notify: off`, nothing outdated, or the same signature is still inside its
+ * 7-day cooldown.
+ *
+ * TOTAL and side-effect-light: nothing is read or written when `notify` is
+ * `off`, and the state file is written ONLY on the turn that actually emits a
+ * nudge — never merely because this ran. Any unexpected error (a throwing
+ * filesystem call the individual helpers didn't already swallow) is caught
+ * here too, so a caller never needs its own try/catch to stay safe.
+ */
+export function resolveUpdateNudge(root, { notify = 'auto', now = Date.now(), env = process.env } = {}) {
+  if (notify === 'off') return null;
+  try {
+    const results = checkSkillVersions(root);
+    const signature = driftSignature(results);
+    if (!signature) return null;
+
+    const file = updateStatePath(env);
+    const state = readUpdateState(file);
+    const sameSignature = state.lastNotifiedVersion === signature;
+    const withinCooldown =
+      typeof state.lastNotifiedAt === 'number' && now - state.lastNotifiedAt < COOLDOWN_MS;
+    if (sameSignature && withinCooldown) return null;
+
+    const text = formatUpdateNudge(results);
+    if (!text) return null;
+
+    writeUpdateState({ lastNotifiedVersion: signature, lastNotifiedAt: now }, file);
+    return text;
+  } catch {
+    return null;
+  }
+}

package/src/shared/completions.mjs

@@ -43,6 +43,7 @@ const FLAG = {
   force: { desc: 'Overwrite / hard-delete' },
   deep: { desc: 'Do a write→read→delete round-trip' },
   telemetry: { desc: 'Verify the OTLP export credential works' },
+  check: { desc: 'Report drift without writing anything' },
   json: { desc: 'Machine-readable output' },
   scope: { desc: 'Restrict to / name a scope', arg: 'scope', complete: 'scope' },
   key: { desc: 'Name the key explicitly', arg: 'key' },
@@ -107,6 +108,8 @@ const COMMANDS = [
     flags: ['dir', 'project', 'global', 'yes'] },
   { name: 'doctor', summary: 'Verify the install, connectivity, token, scope',
     flags: ['dir', 'mode', 'endpoint', 'token', 'store', 'deep', 'telemetry'] },
+  { name: 'update', summary: 'Offline refresh of the bundled skills to the shipped version',
+    flags: ['dir', 'project', 'global', 'check'] },
   { name: 'list', summary: 'List memories for the current directory', aliases: ['ls'],
     flags: ['dir', 'scope', 'json', 'endpoint', 'token', 'store', 'link', 'base'] },
   { name: 'search', summary: 'Full-text search the applicable memories', aliases: ['grep'],

package/src/shared/control.mjs

@@ -61,6 +61,21 @@ export function normalizeStopMode(v) {
   return null;
 }
 
+// `updates.notify` — whether the SessionStart hook may append a terse
+// skill-update nudge when an installed skill has drifted behind the version
+// this CLI ships. `auto` (default) | `off`. Same forgiving-vocabulary /
+// repo-wins model as `hooks.stop`: a plain boolean, `false`/`none`/`disabled`
+// all mean `off`, so a hand-edited JSON file reads naturally either way.
+export const UPDATE_NOTIFY_MODES = ['auto', 'off'];
+export function normalizeUpdateNotifyMode(v) {
+  if (typeof v === 'boolean') return v ? 'auto' : 'off';
+  if (typeof v !== 'string') return null;
+  const s = v.trim().toLowerCase();
+  if (['off', 'none', 'false', 'disabled', 'never', 'no'].includes(s)) return 'off';
+  if (['auto', 'on', 'true', 'enabled', 'always', 'yes'].includes(s)) return 'auto';
+  return null;
+}
+
 // `hooks.userPrompt` — the per-turn relevance pull, on or off.
 //
 // A BOOLEAN, not a mode, and that is a deliberate limit on the surface. The
@@ -454,6 +469,12 @@ export function resolveControl({
     normalizeUserPromptMode(userConfig['hooks.sessionStart.branchHint']) ||
     'on';
 
+  // `updates.notify` — repo layer wins over user layer, default `auto`.
+  const updatesNotify =
+    normalizeUpdateNotifyMode(repoConfig['updates.notify']) ||
+    normalizeUpdateNotifyMode(userConfig['updates.notify']) ||
+    'auto';
+
   // `hooks.adapter` — repo layer wins over user layer (explicit project override).
   const hooksAdapter =
     (typeof repoConfig['hooks.adapter'] === 'string' && repoConfig['hooks.adapter'].trim()) ||
@@ -499,6 +520,7 @@ export function resolveControl({
     hooksSessionStartBranchHint,
     hooksAdapter,
     hooksInstructions,
+    updatesNotify,
   };
 }
 

package/src/shared/lessons-view.mjs

@@ -253,6 +253,36 @@ export function diffGroups(offline = {}, remote = {}) {
 // too terse to carry a durable observation (e.g. "yes", "fixed", "todo").
 export const MIN_VALUE_LEN = 12;
 
+// Blank the INTERIOR of fenced code blocks (``` or ~~~ fences) so example content
+// — a lesson documenting an `<!-- MARKER -->` or pasting a ```yaml front-matter
+// sample — is never mistaken for hidden metadata. Such content renders as VISIBLE
+// fenced text, the opposite of the digest-hidden block `hidden-metadata` targets,
+// and `lint` is a CI gate, so a false positive there fails a legitimate lesson.
+// Line positions are preserved (interiors and fence lines become empty) so the
+// heading-anchored checks still see the real document structure. A closing fence
+// is ≥3 of the SAME character as the opener with no trailing info string
+// (CommonMark); an opener may carry an info string (```yaml). Pure.
+function stripFencedCode(value) {
+  let fence = null; // the active fence character (` or ~), or null when outside a block
+  return String(value)
+    .split('\n')
+    .map((line) => {
+      const m = line.match(/^\s*(`{3,}|~{3,})/);
+      if (fence === null) {
+        if (m) {
+          fence = m[1][0];
+          return '';
+        }
+        return line;
+      }
+      if (m && m[1][0] === fence && line.trim().replace(/[`~\s]/g, '') === '') {
+        fence = null;
+      }
+      return '';
+    })
+    .join('\n');
+}
+
 // The lint rule set: each a pure predicate over a normalized entry returning a
 // short reason string when it FIRES, or null when the entry is clean. Kept as
 // discrete named functions so each rule is independently unit-testable and the
@@ -335,6 +365,47 @@ export const LINT_RULES = {
     if (parsed === null || typeof parsed !== 'object') return null; // a bare scalar — short-value's to catch when short, otherwise unjudged.
     return 'value is a JSON object/array with no kind set — it renders as a raw JSON blob in every SessionStart digest; set --kind bus or --kind signal';
   },
+  // A lesson body is markdown for humans — no HTML comment, no front-matter, no
+  // `key=value` header. The `<!-- meta: seen_count=… status=… trigger-context=… -->`
+  // block is a REPUDIATED legacy convention this repo's lorekit-setup skill once
+  // prescribed (still parsed as a read-fallback in `candidates-pure.mjs` /
+  // `commands/invariants.mjs`, and skipped by the digest preview in `core/lessons.mjs`).
+  // It is wrong on the merits: an HTML comment renders to nothing, so a human sees a
+  // lesson starting mid-sentence, while a baked-in `seen_count`/`status`/`trigger`
+  // silently disagrees with the store's own column/tag/field. Conservative like the
+  // other rules — three concrete shapes only, never a fuzzy "looks like metadata":
+  //   1. any HTML comment (`<!--`), the strongest and most common offender;
+  //   2. a body that OPENS with a YAML front-matter block (`---` as the first line);
+  //   3. a machine-metadata header (`meta:`, `seen_count`, `status=`, `expires`,
+  //      `ttl(_days)`, `trigger-context`) appearing BEFORE the first `#` title, so a
+  //      legitimate prose line mid-body never trips it.
+  // All three run against a fence-stripped copy (`stripFencedCode`) so a lesson that
+  // DOCUMENTS one of these shapes inside a code block is never flagged.
+  'hidden-metadata': (e) => {
+    const raw = String(e.value ?? '');
+    if (!raw.trim()) return null; // an empty value is `empty-value`'s to report.
+    const v = stripFencedCode(raw);
+    if (!v.trim()) return null; // nothing outside code fences — no prose metadata to flag.
+    if (v.includes('<!--')) {
+      return "value contains an HTML comment — lesson bodies are pure markdown; move seen_count → the column, status → a status:: tag, trigger → the trigger field";
+    }
+    const lines = v.split('\n');
+    const firstNonEmpty = lines.find((l) => l.trim() !== '');
+    if (firstNonEmpty !== undefined && firstNonEmpty.trim() === '---') {
+      return 'value opens with a front-matter block — lesson bodies carry no front-matter; every stored fact belongs in its own write field';
+    }
+    const headingIdx = lines.findIndex((l) => /^\s*#/.test(l));
+    if (headingIdx > 0) {
+      const metaHeader = lines
+        .slice(0, headingIdx)
+        .filter((l) => l.trim() !== '')
+        .find((l) => /^\s*(meta\b|seen_count\b|status\s*=|expires\b|ttl(?:_days)?\b|trigger[-_]context\b)/i.test(l));
+      if (metaHeader) {
+        return `value has a machine-metadata header before the title ('${metaHeader.trim().slice(0, 40)}') — move it to the store's own fields`;
+      }
+    }
+    return null;
+  },
 };
 
 // Run every lint rule against one normalized entry, returning the findings it

package/src/shared/skill-versions.mjs

@@ -0,0 +1,148 @@
+// Offline "installed vs shipped" skill version check.
+//
+// `lorekit install` copies each skill's SKILL.md verbatim and stamps no version
+// anywhere else, so a skill installed at an old version has reported a healthy
+// `doctor` PASS forever with no signal to update. The version data already
+// exists: every skill's `SKILL.md` frontmatter carries `metadata.version`
+// (e.g. `'1.0.0'`), and the shipped skill source travels in the SAME npm
+// tarball as the running CLI (`SKILLS[].source` in `./config.mjs`) — so
+// comparing "what's on disk" against "what this CLI ships" needs zero network
+// calls and no server round-trip. `doctor` (per-scope reporting) and
+// `lorekit update` (the refresh command) and the SessionStart drift nudge
+// (`../core/update-notify.mjs`) all read through this one module so the three
+// surfaces can't disagree about what counts as outdated.
+//
+// Dependency-free `.mjs`, like the other `shared/*.mjs` pure modules — no npm
+// imports beyond node builtins.
+import fs from 'node:fs';
+import path from 'node:path';
+import { SKILLS, skillInstallDir } from './config.mjs';
+
+/**
+ * Pull the YAML frontmatter block out of a SKILL.md body — the text between
+ * the first `---` line and the next one. `null` when there is no such block
+ * (not a SKILL.md-shaped file, or a corrupt/truncated one).
+ */
+export function extractFrontmatter(markdown) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(typeof markdown === 'string' ? markdown : '');
+  return m ? m[1] : null;
+}
+
+/**
+ * Parse `metadata.version` out of a SKILL.md's frontmatter.
+ *
+ * Deliberately minimal: every SKILL.md this CLI ships has exactly one
+ * `version:` line (nested under `metadata:`), so a plain line match — robust
+ * to single/double quotes and a trailing comment — is enough without pulling
+ * in a YAML parser this zero-dep package does not otherwise need. Returns
+ * `null` when the frontmatter is absent or carries no `version:` line at all
+ * (a legacy skill file predating the version stamp).
+ */
+export function parseSkillVersion(markdown) {
+  const frontmatter = extractFrontmatter(markdown);
+  if (!frontmatter) return null;
+  const m = /^[ \t]*version:[ \t]*(['"]?)([^'"\n#]+?)\1[ \t]*(?:#.*)?$/m.exec(frontmatter);
+  if (!m) return null;
+  const version = m[2].trim();
+  return version || null;
+}
+
+// Read + parse a SKILL.md's version, or `null` for anything that isn't a
+// readable, parseable file — an absent path, a permissions error, and a file
+// with no `version:` line all collapse to the same "unknown" signal.
+function readVersion(skillMdPath) {
+  try {
+    return parseSkillVersion(fs.readFileSync(skillMdPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Dependency-free semver-ish compare of two dotted-numeric version strings.
+ *
+ * Returns `-1` / `0` / `1` the usual way, or `null` when either input is not a
+ * usable version string (missing, empty, or containing a non-numeric segment —
+ * pre-release/build metadata like `1.0.0-beta` is intentionally out of scope,
+ * since every shipped SKILL.md version is a plain `x.y.z`). `null` reads as
+ * "cannot compare", which callers treat as `unknown` rather than guessing a
+ * direction.
+ */
+export function compareVersions(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || !a.trim() || !b.trim()) return null;
+  const toParts = (v) => v.trim().split('.').map((seg) => Number(seg));
+  const pa = toParts(a);
+  const pb = toParts(b);
+  if (pa.some((n) => !Number.isFinite(n)) || pb.some((n) => !Number.isFinite(n))) return null;
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+/** The scopes a skill can be installed in — matches `skillInstallDir`'s. */
+export const SKILL_SCOPES = ['project', 'global'];
+
+/**
+ * Classify one (skill, scope) pair against the version this CLI ships.
+ *
+ * `state`:
+ *   - `not-installed` — no SKILL.md at that scope.
+ *   - `current`       — installed version >= shipped version.
+ *   - `outdated`       — installed version < shipped version.
+ *   - `unknown`       — a SKILL.md exists but a version could not be
+ *                        resolved on one side (an unparseable/legacy
+ *                        installed file, or — in practice never — an
+ *                        unparseable shipped one), so no direction can be
+ *                        asserted.
+ */
+function classify(installedPath, shipped) {
+  const installedExists = fs.existsSync(installedPath);
+  if (!installedExists) {
+    return { installed: null, state: 'not-installed' };
+  }
+  const installed = readVersion(installedPath);
+  if (installed == null || shipped == null) {
+    return { installed, state: 'unknown' };
+  }
+  const cmp = compareVersions(installed, shipped);
+  if (cmp === null) return { installed, state: 'unknown' };
+  return { installed, state: cmp < 0 ? 'outdated' : 'current' };
+}
+
+/**
+ * Check every skill in `skills` (default: the CLI's own `SKILLS` list) at
+ * every scope, comparing the INSTALLED `SKILL.md`'s `metadata.version`
+ * against the SHIPPED source's. Pure filesystem reads — no network, no store.
+ *
+ * Returns one row per (skill, scope):
+ *   `{ name, scope, installedPath, installed, shipped, state }`
+ */
+export function checkSkillVersions(root, { skills = SKILLS } = {}) {
+  const results = [];
+  for (const skill of skills) {
+    const shipped = readVersion(path.join(skill.source, 'SKILL.md'));
+    for (const scope of SKILL_SCOPES) {
+      const installedPath = path.join(skillInstallDir(root, scope, skill.name), 'SKILL.md');
+      const { installed, state } = classify(installedPath, shipped);
+      results.push({ name: skill.name, scope, installedPath, installed, shipped, state });
+    }
+  }
+  return results;
+}
+
+/**
+ * The subset of `checkSkillVersions` results that need an update — `outdated`
+ * or `unknown` (a legacy install with no readable version is exactly the case
+ * `lorekit update` exists to repair, since re-copying stamps a fresh one).
+ * `not-installed` and `current` are excluded — neither one is drift to act on.
+ */
+export function skillsNeedingUpdate(results) {
+  return (Array.isArray(results) ? results : []).filter(
+    (r) => r && (r.state === 'outdated' || r.state === 'unknown'),
+  );
+}