@lh8ppl/claude-memory-kit 0.2.4 → 0.3.1

package/src/config-core.mjs

@@ -0,0 +1,161 @@
+// `cmk config get/set/--show-origin` core (Task 129, D-121).
+//
+// The v0.1.0 stub became real the day `--with-semantic` shipped:
+// context/settings.json now carries a user-facing setting
+// (search.default_mode) and hand-editing JSON was the only path. This is
+// the read-merge-write surface over the kit's settings files.
+//
+// Settings live in `<tier-root>/settings.json` for each of the three tiers
+// (resolveTierRoot — the shared module, not re-derived). Resolution
+// precedence mirrors the kit's memory model + git config semantics:
+//   local (context.local/) > project (context/) > user (~/.claude-memory-kit/)
+// A `get` returns the highest-precedence tier that defines the dotted key;
+// `--show-origin` lists every tier that defines it (winner + shadowed), the
+// direnv lesson (design §7.2: "without --show-origin, users rage-quit when
+// settings appear from nowhere"). `set` writes one tier (project default),
+// preserving every sibling key (the mergeProjectSettings discipline,
+// generalized per tier).
+//
+// Scope (D-121): the kit's own JSON settings files. NOT the richer
+// settings-or-observation `--show-origin` sketch in design §7.2's example
+// (observations have their own provenance/shadowed_by surface, §6); this is
+// the concrete settings half the semantic default forced into existence.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { resolveTierRoot } from './tier-paths.mjs';
+
+// Highest-precedence first.
+const TIERS = Object.freeze([
+  { name: 'local', tier: 'L' },
+  { name: 'project', tier: 'P' },
+  { name: 'user', tier: 'U' },
+]);
+
+// Keys that would pollute the prototype chain — rejected on both read and
+// write. `cmk config set __proto__.x y` must never reach Object.prototype
+// (skill-review blocking finding); a key path containing any of these is
+// invalid, not a silent no-op.
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function hasForbiddenSegment(dottedKey) {
+  return dottedKey.split('.').some((p) => FORBIDDEN_KEYS.has(p));
+}
+
+function settingsPathFor(tierName, { projectRoot, userDir }) {
+  const tier = TIERS.find((t) => t.name === tierName)?.tier;
+  return join(resolveTierRoot({ tier, projectRoot, userDir }), 'settings.json');
+}
+
+function readSettings(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    // A malformed settings file is treated as absent for resolution — never
+    // throw on a read (a hand-broken JSON shouldn't crash `cmk config get`).
+    return null;
+  }
+}
+
+// Walk a dotted path; returns {found, value}. `found` distinguishes a key
+// set to `undefined`-ish from a key that isn't there (the honesty contract).
+function dig(obj, dottedKey) {
+  if (obj == null || typeof obj !== 'object') return { found: false };
+  const parts = dottedKey.split('.');
+  let cur = obj;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== 'object' || !(p in cur)) return { found: false };
+    cur = cur[p];
+  }
+  return { found: true, value: cur };
+}
+
+/**
+ * Resolve a dotted setting key across tiers (local > project > user).
+ *
+ * @returns {{found: boolean, value?: *, tier?: 'local'|'project'|'user'}}
+ */
+export function configGet(key, { projectRoot, userDir } = {}) {
+  if (!key || !String(key).trim()) return { found: false };
+  if (hasForbiddenSegment(key)) return { found: false };
+  for (const { name } of TIERS) {
+    const settings = readSettings(settingsPathFor(name, { projectRoot, userDir }));
+    const hit = dig(settings, key);
+    if (hit.found) return { found: true, value: hit.value, tier: name };
+  }
+  return { found: false };
+}
+
+/** Scalar coercion: true/false/null → primitives, integer/float strings →
+ *  numbers, everything else stays a string. JSON settings are typed, and a
+ *  CLI arg is always a string — `cmk config set x true` should write a bool. */
+function coerce(raw) {
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (raw === 'null') return null;
+  if (/^-?\d+$/.test(raw)) return Number.parseInt(raw, 10);
+  if (/^-?\d*\.\d+$/.test(raw)) return Number.parseFloat(raw);
+  return raw;
+}
+
+function setDeep(obj, dottedKey, value) {
+  const parts = dottedKey.split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const p = parts[i];
+    if (cur[p] == null || typeof cur[p] !== 'object' || Array.isArray(cur[p])) cur[p] = {};
+    cur = cur[p];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+/**
+ * Set a dotted key in one tier's settings.json (project default), preserving
+ * every sibling key (read-merge-write).
+ *
+ * @returns {{ok: boolean, tier?: string, path?: string, error?: string}}
+ */
+export function configSet(key, rawValue, { projectRoot, userDir, tier = 'project' } = {}) {
+  if (!key || !String(key).trim()) return { ok: false, error: 'key is required (dotted path)' };
+  if (hasForbiddenSegment(key)) {
+    return { ok: false, error: `key contains a forbidden segment (${[...FORBIDDEN_KEYS].join('/')}) — prototype-pollution guard` };
+  }
+  if (!TIERS.some((t) => t.name === tier)) {
+    return { ok: false, error: `tier must be one of local/project/user (got ${tier})` };
+  }
+  const path = settingsPathFor(tier, { projectRoot, userDir });
+  try {
+    const current = readSettings(path) ?? {};
+    setDeep(current, key, coerce(String(rawValue)));
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(current, null, 2) + '\n', 'utf8');
+    return { ok: true, tier, path };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * Every tier that defines the key, highest-precedence first. The winner is
+ * the first; the rest carry `shadowedBy` = the winning tier (the direnv
+ * "where did this come from?" surface).
+ *
+ * @returns {{found: boolean, entries: Array<{tier, value, path, winner, shadowedBy?}>}}
+ */
+export function configShowOrigin(key, { projectRoot, userDir } = {}) {
+  const entries = [];
+  if (!key || !String(key).trim()) return { found: false, entries };
+  if (hasForbiddenSegment(key)) return { found: false, entries };
+  for (const { name } of TIERS) {
+    const path = settingsPathFor(name, { projectRoot, userDir });
+    const hit = dig(readSettings(path), key);
+    if (hit.found) entries.push({ tier: name, value: hit.value, path });
+  }
+  if (entries.length === 0) return { found: false, entries: [] };
+  const winnerTier = entries[0].tier;
+  for (let i = 0; i < entries.length; i++) {
+    entries[i].winner = i === 0;
+    if (i > 0) entries[i].shadowedBy = winnerTier;
+  }
+  return { found: true, entries };
+}

package/src/conflict-queue.mjs

@@ -49,6 +49,8 @@ import {
 } from 'node:fs';
 import { join } from 'node:path';
 import { resolveTierRoot, VALID_TIERS } from './tier-paths.mjs';
+import { writeBullet } from './provenance.mjs';
+import { hashContent } from './content-hash.mjs';
 import { nowIso, appendAuditEntry, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { generateId } from '@lh8ppl/cmk-canonicalize';
@@ -786,9 +788,24 @@ export function mergeScratchpadBullets({
   const effectiveSection = section ?? discoverSectionAt(lines, matchA.bulletIdx);
   const range = effectiveSection ? findSectionRange(updatedLines, effectiveSection) : null;
   const insertAt = range ? range.endIdx : updatedLines.length;
-  const newBullet = `- (${newId}) ${combinedText}`;
-  const newProvenance = `<!-- source: merge-both, merged_from: [${idA}, ${idB}], merged_at: ${ts}, trust: ${mergedTrust} -->`;
-  updatedLines.splice(insertAt, 0, newBullet, newProvenance, '');
+  // D-125 class (Task 138 review finding): the old hand-rolled comment had
+  // no `write:` key, so the first reindex after a merge-both resolution hit
+  // the NOT-NULL observations.write_source constraint. Canonical shape via
+  // the shared builder; the merged_from trail lives in the audit entry below.
+  const sha1 = hashContent(combinedText);
+  const formatted = writeBullet({
+    id: newId,
+    text: combinedText,
+    provenance: {
+      source: 'merge-both',
+      source_line: 1,
+      sha1,
+      write: 'merged',
+      trust: mergedTrust,
+      at: ts,
+    },
+  });
+  updatedLines.splice(insertAt, 0, ...formatted.lines.split('\n'), '');
 
   writeFileSync(scratchpadPath, updatedLines.join('\n'), 'utf8');
 

package/src/content-hash.mjs

@@ -0,0 +1,30 @@
+// Content-fingerprint helper — the single home for the kit's content hash.
+//
+// Every "fingerprint this text/file content" site (provenance source_sha1,
+// the `files` checkpoint diff key, transcript dedup, conflict-merge keys)
+// MUST route through hashContent so the algorithm is defined in exactly one
+// place. Eight modules previously rolled their own `createHash('sha1')`,
+// which (a) let the algorithm drift per-site and (b) tripped CodeQL's
+// js/weak-cryptographic-algorithm on each one independently.
+//
+// SHA-256, not SHA-1: the digests are non-cryptographic content fingerprints
+// (dedup + change-detection), so SHA-1 was never a security flaw here — but a
+// weak-hash sink on every site is noise that hides real findings, and the
+// whole-convention move to SHA-256 (the user's call, D-149) removes the sink
+// kit-wide while keeping the digest consistent across writers. The on-disk
+// FIELD name stays `source_sha1` / `sha1` for back-compat (renaming the YAML
+// key + db column would break existing fact files + checkpoints); only the
+// algorithm changes. Existing `files`-table checkpoints mismatch once on the
+// first boot after upgrade and self-heal via the normal reindex.
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Hash text/file content to a hex digest used as a non-cryptographic
+ * fingerprint (dedup, drift-detection, provenance). UTF-8 input.
+ * @param {string} content
+ * @returns {string} 64-char lowercase hex SHA-256 digest
+ */
+export function hashContent(content) {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}

package/src/doctor.mjs

@@ -1,4 +1,4 @@
-// `cmk doctor` — health checks HC-1..HC-7 (Task 37, T-031; memsearch HC-1/HC-7 removed in Task 120).
+// `cmk doctor` — health checks HC-1..HC-8 (Task 37, T-031; memsearch HC-1/HC-7 removed in Task 120; HC-8 native bindings added in Task 141a).
 //
 // Public boundary:
 //   async runDoctor({projectRoot, userDir, now, promptUser?, ...overrides})
@@ -44,6 +44,8 @@ import { nowIso } from './audit-log.mjs';
 import { detectStaleLocks } from './lock-discipline.mjs';
 import { cronSentinelPath } from './lazy-compress.mjs';
 import { getNativeAutoMemoryState } from './native-memory.mjs';
+import { checkKitBinding, checkEmbedderBinding } from './native-binding.mjs';
+import { resolveDefaultSearchMode } from './semantic-backend.mjs';
 
 const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1000;
 const THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1000;
@@ -470,13 +472,67 @@ function hc7StaleLocks({ projectRoot, userDir }) {
   };
 }
 
+// --- HC-8: native bindings present (npm 12 readiness, Task 141a) -------
+// The BACKSTOP, not the primary UX: `cmk install` probes + asks inline
+// (the user's 2026-06-12 steer); HC-8 catches the after-the-fact states
+// (npm upgraded later, package reinstalled without the allow flag).
+// The repair is an `npm install -g` → requiresInstall per the design §14
+// ask-before-install rule.
+async function hc8NativeBindings({ projectRoot, kitBindingProbe, embedderBindingProbe }) {
+  const kitProbe = kitBindingProbe ?? checkKitBinding;
+  const kit = kitProbe();
+  if (!kit.ok) {
+    return {
+      id: 'HC-8',
+      name: 'Native bindings present (npm 12 readiness)',
+      status: 'fail',
+      message: `better-sqlite3 native binding unavailable (${kit.reason}) — most common cause: npm 12 blocks dependency install scripts by default, so a fresh install skips the binding build (a Node major upgrade is the other); search/reindex will crash until it is rebuilt`,
+      recoveryCommand: kit.remedy,
+      requiresInstall: true,
+    };
+  }
+  // The embedder matters only when this project actually defaults to it.
+  const mode = resolveDefaultSearchMode({ projectRoot });
+  if (mode === 'keyword') {
+    return {
+      id: 'HC-8',
+      name: 'Native bindings present (npm 12 readiness)',
+      status: 'pass',
+      message: 'better-sqlite3 binding healthy (semantic not configured — embedder not checked)',
+    };
+  }
+  const embedderProbe = embedderBindingProbe ?? checkEmbedderBinding;
+  const embedder = await embedderProbe();
+  if (!embedder.ok) {
+    const state = embedder.installed
+      ? `installed but its native binding failed (${embedder.reason}) — npm 12 blocks onnxruntime-node's install script by default`
+      : `not installed, but search.default_mode is '${mode}'`;
+    return {
+      id: 'HC-8',
+      name: 'Native bindings present (npm 12 readiness)',
+      status: 'fail',
+      message: `semantic embedder ${state}; searches degrade to keyword until fixed`,
+      recoveryCommand: embedder.remedy,
+      requiresInstall: true,
+    };
+  }
+  return {
+    id: 'HC-8',
+    name: 'Native bindings present (npm 12 readiness)',
+    status: 'pass',
+    message: `better-sqlite3 binding healthy; embedder import OK (default mode: ${mode}; the deep pipeline check runs at --with-semantic warm)`,
+  };
+}
+
 /**
- * Run the full 7-check health audit.
+ * Run the full 8-check health audit.
  *
  * @param {object} opts
  * @param {string} opts.projectRoot
  * @param {string} [opts.userDir]
  * @param {string} [opts.now]
+ * @param {Function} [opts.kitBindingProbe] - HC-8 test seam.
+ * @param {Function} [opts.embedderBindingProbe] - HC-8 test seam.
  * @returns {Promise<{action, checks, duration_ms}>}
  *
  * Note: M3 fix (skill-review 2026-05-28) dropped the v0.1.0 `promptUser`
@@ -489,6 +545,8 @@ export async function runDoctor({
   projectRoot,
   userDir,
   now,
+  kitBindingProbe,
+  embedderBindingProbe,
 } = {}) {
   const t0 = Date.now();
   if (!projectRoot) {
@@ -510,10 +568,11 @@ export async function runDoctor({
   const c5 = hc5CronRegistered({ projectRoot });
   const c6 = hc6NativeAutoMemory({ projectRoot, now: ts });
   const c7 = hc7StaleLocks({ projectRoot, userDir: resolvedUserDir });
+  const c8 = await hc8NativeBindings({ projectRoot, kitBindingProbe, embedderBindingProbe });
 
   return {
     action: 'completed',
-    checks: [c1, c2, c3, c4, c5, c6, c7],
+    checks: [c1, c2, c3, c4, c5, c6, c7, c8],
     duration_ms: Date.now() - t0,
   };
 }

package/src/forget.mjs

@@ -29,6 +29,7 @@ import { ERROR_CATEGORIES, errorResult, notFoundResult } from './result-shapes.m
 import { findBulletScratchpad } from './bullet-lookup.mjs';
 import { openIndexDb } from './index-db.mjs';
 import { reindexBoot } from './index-rebuild.mjs';
+import { reindex } from './reindex.mjs';
 
 // Layer-2 review: PR-1 rejected \n / \r / : in the `reason` field as a
 // minimum fix for the naive serializer (finding B2). PR-2's frontmatter.mjs
@@ -292,6 +293,18 @@ export function forget(opts = {}) {
     },
   });
 
+  // Task 124 (D-112): the writer owns the derived view on the DELETE path
+  // too — writeFact refreshes INDEX.md on every create (the Task-85 lesson);
+  // without this, the tombstoned fact stayed listed in INDEX.md and doctor
+  // HC-4 failed until a manual `cmk reindex` (dogfood-found 2026-06-10).
+  // Best-effort, same contract as writeFact's: the tombstone is already
+  // durable on disk, so an index hiccup must not fail the forget.
+  try {
+    reindex({ tier: match.tier, projectRoot, userDir, warn: () => {} });
+  } catch {
+    // index rebuild is best-effort; the tombstone already succeeded
+  }
+
   // Task 110 (F-7 / D-84): reindex the project tier IN-BAND so the just-
   // tombstoned fact stops surfacing in `cmk search` immediately — no manual
   // `cmk reindex`, no forgotten fact resurfacing (D-85: the action completes

package/src/frontmatter.mjs

@@ -43,7 +43,10 @@ const LOAD_OPTIONS = Object.freeze({
 
 export function parse(text) {
   if (typeof text !== 'string') return { frontmatter: null, body: '' };
-  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  // Task 139 (D-126): \r? tolerance — a Windows clone with autocrlf=true
+  // rewrites committed memory files to CRLF, and a strict-\n boundary made
+  // every fact file invisible (cut-gate9 H1: clone reindex found 0 facts).
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
   if (!m) return { frontmatter: null, body: text };
   let frontmatter;
   try {

package/src/import-anthropic-memory.mjs

@@ -39,6 +39,8 @@ import {
   REASON_CODES,
 } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+import { writeBullet } from './provenance.mjs';
+import { hashContent } from './content-hash.mjs';
 
 const MEMORY_REL = ['context', 'MEMORY.md'];
 
@@ -227,7 +229,29 @@ export async function importAnthropicMemory({
   // deduplication of section headers is a v0.1.x candidate per design §16.
   const today = ts.slice(0, 10);
   const sectionHeader = `\n## Imported (Anthropic auto-memory, ${today})\n`;
-  const bulletLines = proposals.map((p) => `- (${p.id}) ${p.text}\n<!-- write_source: imported, trust: medium, source: anthropic-auto-memory, imported_at: ${ts} -->`).join('\n');
+  // Task 138 (D-125): emit the CANONICAL provenance comment via the shared
+  // writeBullet builder — the hand-rolled `write_source:`-keyed comment was
+  // invisible to the reindex parser (it maps the `write:` key to the
+  // NOT-NULL observations.write_source column), so the first reindex after
+  // an import failed and search degraded to the stale index (cut-gate9 F-13).
+  const bulletLines = proposals
+    .map((p) => {
+      const sha1 = hashContent(p.text);
+      const formatted = writeBullet({
+        id: p.id,
+        text: p.text,
+        provenance: {
+          source: 'anthropic-auto-memory',
+          source_line: 1,
+          sha1,
+          write: 'imported',
+          trust: 'medium',
+          at: ts,
+        },
+      });
+      return formatted.lines;
+    })
+    .join('\n');
   mkdirSync(join(projectRoot, 'context'), { recursive: true });
   appendFileSync(targetPath, sectionHeader + '\n' + bulletLines + '\n', 'utf8');