@lorekit/cli 1.0.0

package/src/core/state.mjs

@@ -0,0 +1,27 @@
+// One-shot throttle so a hook fires an injection at most once per session/tag.
+// Prevents nudge spam and, on Stop hooks, avoids re-injection loops.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+function stateDir() {
+  const base = process.env.CLAUDE_PLUGIN_DATA || path.join(os.tmpdir(), 'lorekit-hooks');
+  fs.mkdirSync(base, { recursive: true });
+  return base;
+}
+
+// Returns true the FIRST time called for a given (sessionId, tag), false after.
+// Missing sessionId → always true (cannot throttle without a key).
+export function firstTimeThisSession(sessionId, tag) {
+  if (!sessionId) return true;
+  const hash = crypto.createHash('sha256').update(`${sessionId}:${tag}`).digest('hex').slice(0, 16);
+  const marker = path.join(stateDir(), `${hash}.seen`);
+  try {
+    // wx fails if the file already exists → not the first time.
+    fs.writeFileSync(marker, '', { flag: 'wx' });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/doctor.mjs

@@ -0,0 +1,251 @@
+// `lorekit doctor` — verify the skill install and the resolved memory backend.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { execFileSync } from 'node:child_process';
+import {
+  SKILL_NAME,
+  resolveProjectRoot,
+  skillInstallDir,
+  readLorekitServer,
+  readMcpConfig,
+  tokenKind,
+} from './config.mjs';
+import { splitEndpoint } from './mcp.mjs';
+import { deriveScope } from './scope.mjs';
+import { loadControl } from './control.mjs';
+import { createStore } from './store/index.mjs';
+import { log, heading, status, c } from './util.mjs';
+
+const AUTH_CODES = new Set([401, 403, -32001]);
+
+export async function doctor(args) {
+  const root = resolveProjectRoot(args.dir);
+  let failures = 0;
+  let warnings = 0;
+  const record = (kind, label, detail) => {
+    if (kind === 'fail') failures++;
+    if (kind === 'warn') warnings++;
+    status(kind, label, detail);
+  };
+
+  heading('LoreKit doctor');
+  log(`  project: ${c.dim(root)}\n`);
+
+  // 1. Runtime.
+  const major = Number(process.versions.node.split('.')[0]);
+  record(
+    major >= 18 ? 'pass' : 'fail',
+    'node runtime',
+    `v${process.versions.node}${major < 18 ? ' — need v18+ for fetch' : ''}`,
+  );
+
+  // 2. Skill installed.
+  const skillMd = path.join(skillInstallDir(root), 'SKILL.md');
+  if (fs.existsSync(skillMd)) {
+    record('pass', `skill ${SKILL_NAME}`, path.relative(root, skillMd) || skillMd);
+  } else {
+    record('fail', `skill ${SKILL_NAME}`, 'not found — run `lorekit install`');
+  }
+
+  // 3. Resolved control model — which mode, and who decided it.
+  const control = loadControl(root, { env: withOverrides(args) });
+  record('info', 'memory mode', `${control.mode}  ${c.dim('— decided by ' + control.decidedBy)}`);
+  for (const d of control.denies) {
+    record('info', 'deny constraint', `${d.mode} forbidden by ${d.source}`);
+  }
+
+  // 4. Mode-specific checks.
+  if (control.mode === 'off') {
+    record('info', 'memory', 'disabled — hooks and the skill are silent no-ops');
+  } else if (control.mode === 'local') {
+    await checkLocal(control, root, args, record);
+  } else {
+    await checkRemote(control, root, args, record);
+  }
+
+  // 5. Scope.
+  const scope = deriveScope(root);
+  if (scope.hasRemote) {
+    record('info', 'read scope', scope.readOrder.join('  →  '));
+    record('info', 'write scope', `${scope.repoScope} (default for "went wrong" lessons)`);
+  } else {
+    record('warn', 'scope', 'no git remote here — lessons fall back to global');
+  }
+
+  // Summary.
+  heading('Summary');
+  if (failures === 0 && warnings === 0) {
+    log(`  ${c.green('All checks passed.')} LoreKit memory is ready.`);
+  } else {
+    log(
+      `  ${failures ? c.red(failures + ' failed') : c.green('0 failed')}, ${
+        warnings ? c.yellow(warnings + ' warning(s)') : '0 warnings'
+      }.`,
+    );
+  }
+  return failures === 0 ? 0 : 1;
+}
+
+// Merge doctor's --endpoint / --token flags into the env the resolver reads, so
+// an explicit connection flag is honoured without a separate resolution path.
+function withOverrides(args) {
+  const env = { ...process.env };
+  if (args.endpoint) env.LOREKIT_MCP_URL = args.endpoint;
+  if (args.token) env.LOREKIT_TOKEN = args.token;
+  if (args.mode) env.LOREKIT_MODE = args.mode;
+  if (args.store) env.LOREKIT_STORE = args.store;
+  return env;
+}
+
+// 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;
+}
+
+async function checkLocal(control, root, args, record) {
+  const store = createStore(control);
+  const scope = deriveScope(root);
+  const scopes = [...new Set([...scope.readOrder, scope.branchScope, scope.repoScope])].filter(
+    Boolean,
+  );
+
+  // Home tier — per-user, cross-repo, always available.
+  record('pass', 'home store', prettyPath(store.homeDir));
+  record('info', 'home entries', `${await store.home.count(scopes)} lesson(s)`);
+
+  // Project tier — opt-in; active only when its directory exists.
+  const projRel = path.relative(root, store.projectDir) || store.projectDir;
+  if (store.projectActive()) {
+    const sharing = gitTracked(root, store.projectDir)
+      ? 'committed — shared with the team'
+      : 'gitignored — private to your checkout';
+    record('pass', 'project store', projRel);
+    record('info', 'project entries', `${await store.project.count(scopes)} lesson(s) — ${sharing}`);
+  } else {
+    record(
+      'info',
+      'project store',
+      `${projRel} — not opted-in (create it to persist repo/branch lessons here)`,
+    );
+  }
+
+  if (args.deep) await deepCheckLocal(store, scope, record);
+}
+
+async function checkRemote(control, root, args, record) {
+  const override = { endpoint: args.endpoint || null, token: args.token || null };
+  const mcp = readMcpConfig(root);
+  const configured = mcp.valid ? readLorekitServer(root) : null;
+  const fromMcp = configured ? splitEndpoint(configured.url) : { endpoint: null, token: null };
+
+  const endpoint = override.endpoint || fromMcp.endpoint || control.connection.endpoint;
+  const token = override.token || fromMcp.token || control.connection.token;
+
+  if (mcp.present && !mcp.valid) {
+    record('fail', '.mcp.json', 'invalid JSON — fix it or re-run `lorekit install`');
+  } else if (configured) {
+    record('pass', '.mcp.json', 'lorekit server configured');
+  } else {
+    record('warn', '.mcp.json', 'no lorekit server entry — using env/flags');
+  }
+
+  if (!endpoint) {
+    record('fail', 'endpoint', 'none — set it in .mcp.json or pass --endpoint');
+  } else if (endpoint.includes('<project-ref>')) {
+    record('fail', 'endpoint', `still a placeholder: ${endpoint}`);
+  } else {
+    record('pass', 'endpoint', endpoint);
+  }
+
+  const kind = tokenKind(token);
+  if (kind === 'none') record('fail', 'token', 'none configured');
+  else if (kind === 'read-only') record('warn', 'token', 'read-only (lk_ro_*) — reads only, no writes');
+  else if (kind === 'unknown') record('warn', 'token', 'unrecognized prefix (expected lk_rw_* / lk_ro_*)');
+  else record('pass', 'token', 'read+write (lk_rw_*)');
+
+  // Connectivity, through the store.
+  const store = createStore({ mode: 'remote', connection: { endpoint, token } });
+  if (endpoint && !endpoint.includes('<project-ref>') && token) {
+    const res = await store.ping();
+    if (res.networkError) {
+      record('fail', 'connectivity', res.networkError);
+    } else if (res.ok) {
+      const tools = res.result && Array.isArray(res.result.tools) ? res.result.tools.length : null;
+      record('pass', 'connectivity', tools !== null ? `reachable, ${tools} tools` : 'reachable');
+    } else if (res.error && AUTH_CODES.has(res.error.code)) {
+      record('fail', 'connectivity', `auth rejected (${res.error.code}) — check your token`);
+    } else if (res.error) {
+      record('warn', 'connectivity', `reachable, server said: ${res.error.message || res.error.code}`);
+    } else {
+      record('warn', 'connectivity', `unexpected response (HTTP ${res.httpStatus})`);
+    }
+
+    if (args.deep) await deepCheckRemote(store, root, record);
+  } else {
+    record('warn', 'connectivity', 'skipped — need a valid endpoint and token');
+  }
+}
+
+async function deepCheckRemote(store, root, record) {
+  if (tokenKind(store.token) !== 'read-write') {
+    record('warn', 'round-trip', 'skipped — needs a read+write token');
+    return;
+  }
+  const scope = deriveScope(root);
+  const writeScope = scope.repoScope || 'global';
+  const key = 'lorekit-memory::doctor-check';
+
+  const w = await store.write({
+    scope: writeScope,
+    key,
+    value: 'LoreKit doctor round-trip check. Safe to delete.',
+    tags: ['skill::lorekit-memory', 'source::doctor'],
+    trigger: 'manual',
+  });
+  if (!w.ok) {
+    record('fail', 'round-trip', `write failed: ${w.error ? w.error.message || w.error.code : w.networkError}`);
+    return;
+  }
+  const r = await store.read({ scope: writeScope, key });
+  const readBack = r.ok && JSON.stringify(r.entry || '').includes('round-trip');
+  record(
+    readBack ? 'pass' : 'warn',
+    'round-trip',
+    readBack ? `wrote + read back in ${writeScope}` : 'wrote, but read-back was inconclusive',
+  );
+  await store.delete({ scope: writeScope, key, force: true });
+}
+
+async function deepCheckLocal(store, scope, record) {
+  const writeScope = scope.repoScope || 'global';
+  const key = 'lorekit-memory::doctor-check';
+  const w = await store.write({
+    scope: writeScope,
+    key,
+    value: 'LoreKit doctor round-trip check. Safe to delete.',
+    tags: ['skill::lorekit-memory', 'source::doctor'],
+    trigger: 'manual',
+  });
+  const r = await store.read({ scope: writeScope, key });
+  const readBack = w.ok && r.ok && r.entry && String(r.entry.value).includes('round-trip');
+  record(
+    readBack ? 'pass' : 'warn',
+    'round-trip',
+    readBack ? `wrote + read back in ${writeScope}` : 'write/read-back was inconclusive',
+  );
+  await store.delete({ scope: writeScope, key, force: true });
+}
+
+function gitTracked(root, dir) {
+  // Heuristic: is the store dir ignored by git? If `git check-ignore` names it,
+  // it is private; otherwise it will be committed (team-shared).
+  try {
+    execFileSync('git', ['check-ignore', '-q', dir], { cwd: root, stdio: 'ignore' });
+    return false; // ignored → private
+  } catch {
+    return true; // not ignored → tracked/committed
+  }
+}

package/src/hook.mjs

@@ -0,0 +1,106 @@
+// `lorekit hook --adapter <claude|cursor|codex> [--event <name>]`
+// The shared hook engine. Reads the framework's JSON on stdin, runs the shared
+// logic, and prints the framework-shaped injection on stdout. Always exits 0 —
+// a memory hook must never block or break the host agent.
+import process from 'node:process';
+import { resolveProjectRoot } from './config.mjs';
+import { deriveScope } from './scope.mjs';
+import { loadControl } from './control.mjs';
+import { createStore } from './store/index.mjs';
+import { fetchLessons, formatLessons, retrospectiveNudge, failureNudge } from './core/lessons.mjs';
+import { isFailure } from './core/failure.mjs';
+import { firstTimeThisSession } from './core/state.mjs';
+import { recordFixture } from './core/record.mjs';
+import { claude } from './adapters/claude.mjs';
+import { cursor } from './adapters/cursor.mjs';
+import { codex } from './adapters/codex.mjs';
+
+const ADAPTERS = { claude, cursor, codex };
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    if (process.stdin.isTTY) return resolve('');
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+export async function hook(args) {
+  // Guarded so any unexpected error still exits 0 (never break the host agent).
+  try {
+    return await run(args);
+  } catch {
+    return 0;
+  }
+}
+
+async function run(args) {
+  const adapter = ADAPTERS[args.adapter];
+  if (!adapter) {
+    // Unknown adapter: stay silent, don't disrupt the host.
+    return 0;
+  }
+
+  const raw = await readStdin();
+  let input = {};
+  if (raw && raw.trim()) {
+    try {
+      input = JSON.parse(raw);
+    } catch {
+      input = {};
+    }
+  }
+
+  const parsed = adapter.parse(input);
+  const event = args.event || parsed.event;
+
+  // Harvest the real payload when recording is enabled (opt-in via env).
+  recordFixture(args.adapter, event, raw);
+
+  if (!event) return 0;
+
+  const intent = adapter.intentFor(event);
+  if (intent === 'noop') return 0;
+
+  const root = resolveProjectRoot(
+    args.dir || process.env.CLAUDE_PROJECT_DIR || parsed.cwd || undefined,
+  );
+  const scope = deriveScope(root);
+
+  // Resolve the control model once. `off` disables every hook event — no read,
+  // no nudges — so memory can be turned off entirely without touching config.
+  const control = loadControl(root);
+  if (control.mode === 'off') return 0;
+
+  const emit = (text) => {
+    if (text) process.stdout.write(adapter.emit(event, text));
+  };
+
+  if (intent === 'read') {
+    if (!firstTimeThisSession(parsed.sessionId, 'read')) return 0;
+    const store = createStore(control);
+    if (!store) return 0; // unconfigured/unusable — stay silent
+    const { scope: readScope, lessons } = await fetchLessons(store, root);
+    emit(formatLessons(lessons, readScope));
+    return 0;
+  }
+
+  if (intent === 'failure') {
+    const known = adapter.guaranteedFailure ? adapter.guaranteedFailure(event) : false;
+    if (!known && !isFailure(parsed.toolName, parsed.toolResponse)) return 0;
+    if (!firstTimeThisSession(parsed.sessionId, 'failure')) return 0;
+    emit(failureNudge(parsed.toolName, scope));
+    return 0;
+  }
+
+  if (intent === 'retrospective') {
+    if (!firstTimeThisSession(parsed.sessionId, 'retro')) return 0;
+    emit(retrospectiveNudge(scope));
+    return 0;
+  }
+
+  return 0;
+}

package/src/install.mjs

@@ -0,0 +1,95 @@
+// `lorekit install` — scaffold the skill and wire the MCP server.
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import process from 'node:process';
+import {
+  SKILL_SOURCE,
+  SKILL_NAME,
+  resolveProjectRoot,
+  skillInstallDir,
+  copyDir,
+  upsertMcpServer,
+  resolveConnection,
+  tokenKind,
+} from './config.mjs';
+import { buildRemoteUrl } from './mcp.mjs';
+import { deriveScope } from './scope.mjs';
+import { log, err, heading, status, c } from './util.mjs';
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
+}
+
+const DEFAULT_ENDPOINT_HINT = 'https://<project-ref>.supabase.co/functions/v1/mcp';
+
+export async function install(args) {
+  const root = resolveProjectRoot(args.dir);
+  const nonInteractive = Boolean(args.yes) || !process.stdin.isTTY;
+
+  heading('LoreKit install');
+  log(`  project: ${c.dim(root)}`);
+
+  // 1. Connection details.
+  let { endpoint, token } = resolveConnection(args);
+
+  if (!endpoint) {
+    if (nonInteractive) {
+      err(
+        `\n${c.red('Missing endpoint.')} Pass --endpoint ${DEFAULT_ENDPOINT_HINT} ` +
+          `or set LOREKIT_MCP_URL.`,
+      );
+      return 1;
+    }
+    endpoint = await ask(`  LoreKit MCP endpoint [${DEFAULT_ENDPOINT_HINT}]: `);
+    if (!endpoint) endpoint = DEFAULT_ENDPOINT_HINT;
+  }
+  if (!token && !nonInteractive) {
+    token = await ask('  LoreKit token (lk_rw_… to allow writes, blank to skip): ');
+    token = token || null;
+  }
+
+  // 2. Install the skill files.
+  const dest = skillInstallDir(root);
+  const skillExisted = fs.existsSync(path.join(dest, 'SKILL.md'));
+  const written = copyDir(SKILL_SOURCE, dest, { force: Boolean(args.force) });
+
+  // 3. Wire .mcp.json.
+  const remoteUrl = buildRemoteUrl(endpoint, token);
+  const { file, existed } = upsertMcpServer(root, remoteUrl);
+
+  // 4. Report.
+  heading('Done');
+  const skillState = !skillExisted
+    ? 'installed'
+    : written > 0
+      ? `updated (${written} file(s) written)`
+      : 'unchanged — pass --force to overwrite';
+  status(skillExisted && written === 0 ? 'info' : 'pass', `skill ${SKILL_NAME}`, `${skillState} → ${path.relative(root, dest) || dest}`);
+  status('pass', '.mcp.json', `${existed ? 'updated' : 'created'} lorekit server → ${path.relative(root, file) || file}`);
+
+  const kind = tokenKind(token);
+  if (kind === 'none') {
+    status('warn', 'token', 'none configured — reads/writes will fail until a token is set');
+  } else if (kind === 'read-only') {
+    status('warn', 'token', 'read-only (lk_ro_*) — the skill can read lessons but not write them');
+  } else if (kind === 'unknown') {
+    status('warn', 'token', 'unrecognized prefix — expected lk_rw_* or lk_ro_*');
+  } else {
+    status('pass', 'token', 'read+write (lk_rw_*)');
+  }
+
+  const scope = deriveScope(root);
+  if (scope.hasRemote) {
+    status('info', 'scope', `${scope.repoScope}${scope.branchScope ? `  ·  ${scope.branchScope}` : ''}`);
+  } else {
+    status('warn', 'scope', 'no git remote — lessons will fall back to global');
+  }
+
+  log(`\n  Next: ${c.cyan('npx @lorekit/cli doctor')} to verify the connection.`);
+  if (token) {
+    log(`  ${c.dim('Note: your token now lives in .mcp.json — keep it out of version control.')}`);
+  }
+  return 0;
+}