@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.33

package/scripts/frontmatter-schema-validator.cjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 88.1-07 -- frontmatter schema validation PostToolUse hook.
+ * =================================================================
+ * ADVISORY, NOT BLOCKING. Fires after Write|Edit|MultiEdit on files that
+ * live inside a .room-root subtree (Phase 87-01a sentinel). Parses the
+ * written file's YAML frontmatter, delegates structural validation to
+ * lib/core/frontmatter-schemas.cjs (pure function), and:
+ *
+ *   - emits a one-line systemMessage advisory on violation,
+ *   - appends one JSON line per violation-event to
+ *     ${CLAUDE_PLUGIN_DATA}/schema-violations.jsonl (offense log for
+ *     /mos:admin to consume in a future plan),
+ *   - ALWAYS exits 0 (never blocks the Write / Edit / MultiEdit call).
+ *
+ * Policy rationale: per CONTEXT 88.1-07 R2 (Mitigation #2), user friction
+ * is the anti-pattern for a schema enforcement surface. The hook surfaces
+ * drift without halting work. The offense log lets the user review and
+ * fix later via /mos:admin.
+ *
+ * Canon:
+ *   Part 5 Evidence Graded By Context -- schemas codify per-section
+ *     evidence-tier properties; the hook is the runtime enforcement arm.
+ *   Part 6 Product-as-Venture -- plugin dog-foods its own schema on every
+ *     write inside a .room-root subtree.
+ *   Part 8 Graph Boundary -- hook runs LOCAL only; violations log to
+ *     ${CLAUDE_PLUGIN_DATA} on the user's machine. No HTTP, no Brain.
+ *
+ * Claude Code PostToolUse envelope (read on stdin):
+ *   {
+ *     "tool_name":  "Write" | "Edit" | "MultiEdit",
+ *     "tool_input": { "file_path": "<abs path>", ... },
+ *     ...
+ *   }
+ *
+ * Stdout emission (JSON on one line, Claude Code 2.x PostToolUse envelope):
+ *   With message:  { "hookSpecificOutput": { "hookEventName": "PostToolUse",
+ *                                            "additionalContext": "<one-line advisory>" } }
+ *   Silent path:   no stdout output at all (process exits 0 silently).
+ *
+ * Three-surface compatibility: triggered by Claude Code's PostToolUse
+ * lifecycle via hooks.json. Desktop MCP and Cowork share the same hooks.json
+ * bundle. No surface-specific branches.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// ---------- Soft-fail envelope ----------
+// v1.11.2 (2026-04-29): completes the v1.10.19 schema-compliance sweep that
+// missed this hook. Claude Code 2.x added `additionalProperties: false` to
+// the PostToolUse output schema. Top-level `systemMessage` and
+// `additionalContext` are no longer accepted -- they must be wrapped in
+// `hookSpecificOutput`. Without this fix, every Write/Edit/MultiEdit fires
+// "Hook JSON output validation failed -- (root): Invalid input" in the
+// user's terminal. Reference fix: scripts/query-efficiency-telemetry.cjs
+// (v1.10.19). See: https://docs.anthropic.com/en/docs/claude-code/hooks
+
+function emitEnvelope(systemMessage) {
+  if (!systemMessage) return; // silent exit -- never emit JSON when no message
+  try {
+    const payload = {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: String(systemMessage),
+      },
+    };
+    process.stdout.write(JSON.stringify(payload) + '\n');
+  } catch (_e) { /* best-effort */ }
+}
+
+function exitSilent() {
+  // v1.11.2 (2026-04-29): previously called emitEnvelope(null) which wrote an
+  // invalid JSON envelope on every Write/Edit/MultiEdit outside a room.
+  // Silent now means truly silent -- exit 0 with no stdout output. Schema
+  // validation passes by emitting nothing.
+  process.exit(0);
+}
+
+// ---------- Helpers ----------
+
+/**
+ * Read stdin synchronously. Returns empty string on any failure.
+ */
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch (_e) {
+    return '';
+  }
+}
+
+/**
+ * Extract file path from the Claude Code PostToolUse envelope.
+ * Claude Code passes tool_name + tool_input. Older hook envelopes use
+ * input.file_path; both shapes are tolerated.
+ */
+function extractFilePath(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const ti = payload.tool_input || payload.input || null;
+  if (!ti || typeof ti !== 'object') return null;
+  const candidates = ['file_path', 'filePath', 'path'];
+  for (const k of candidates) {
+    const v = ti[k];
+    if (typeof v === 'string' && v.length > 0) return v;
+  }
+  return null;
+}
+
+/**
+ * Extract the tool name. Accepts 'tool_name' (current) and 'tool' (legacy).
+ */
+function extractToolName(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  if (typeof payload.tool_name === 'string') return payload.tool_name;
+  if (typeof payload.tool === 'string') return payload.tool;
+  return null;
+}
+
+/**
+ * Walk upward from filePath looking for a .room-root sentinel file
+ * (Phase 87-01a). Returns { roomRoot, section } where section is the first
+ * path segment under the room root, or null if no .room-root found within
+ * MAX_DEPTH hops, or if the file is directly in the room root with no
+ * section underneath.
+ */
+const MAX_DEPTH = 10;
+function resolveRoomScope(filePath) {
+  let dir = path.dirname(filePath);
+  for (let hops = 0; hops < MAX_DEPTH; hops += 1) {
+    if (dir === path.dirname(dir)) break; // reached filesystem root
+    try {
+      const sentinel = path.join(dir, '.room-root');
+      if (fs.existsSync(sentinel)) {
+        const rel = path.relative(dir, filePath);
+        if (!rel || rel.startsWith('..')) return null;
+        const parts = rel.split(path.sep).filter(Boolean);
+        if (parts.length < 2) {
+          // file is directly in room root, not inside a section. Skip.
+          return null;
+        }
+        return { roomRoot: dir, section: parts[0] };
+      }
+    } catch (_e) { /* ignore; keep walking */ }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Parse YAML frontmatter block from a .md file buffer.
+ * Uses gray-matter (already a repo dep per package.json). On any parse
+ * error, returns null so the schema validator records a malformed
+ * violation. Non-frontmatter files return an empty object (no YAML to
+ * validate; schemas module treats {} as "all required missing" and the
+ * caller short-circuits on lack of delimiters).
+ */
+function parseFrontmatter(buf) {
+  // If the file does not START with a frontmatter delimiter, treat it as
+  // "no frontmatter present": nothing to validate (return sentinel to
+  // short-circuit in main()). This prevents spamming advisories for every
+  // non-frontmatter markdown artifact.
+  if (typeof buf !== 'string' || !/^---\r?\n/.test(buf)) {
+    return { noFrontmatter: true };
+  }
+  let matter;
+  try {
+    matter = require('gray-matter');
+  } catch (_e) {
+    // gray-matter missing -> we cannot validate. Advisory hook must never
+    // block, so treat the case as no-op.
+    return { noFrontmatter: true };
+  }
+  try {
+    const parsed = matter(buf);
+    // gray-matter returns .data:{} when the frontmatter block is present
+    // but empty. We return {} so the schema validator records missing-
+    // required violations for that case.
+    const data = (parsed && parsed.data && typeof parsed.data === 'object')
+      ? parsed.data : {};
+    return { frontmatter: data };
+  } catch (_e) {
+    // Malformed YAML inside the delimiters.
+    return { frontmatter: null };
+  }
+}
+
+/**
+ * Resolve the violations JSONL path. Prefers ${CLAUDE_PLUGIN_DATA}, falls
+ * back to ${HOME}/.mindrian/schema-violations.jsonl.
+ */
+function resolveLogPath() {
+  const envDir = process.env.CLAUDE_PLUGIN_DATA;
+  if (envDir && typeof envDir === 'string' && envDir.length > 0) {
+    return path.join(envDir, 'schema-violations.jsonl');
+  }
+  const home = process.env.HOME || os.homedir();
+  if (!home) return null;
+  return path.join(home, '.mindrian', 'schema-violations.jsonl');
+}
+
+/**
+ * Append one JSON line to the violations log. Creates the parent
+ * directory if missing. Soft-fails silently on any I/O error.
+ */
+function appendViolationLog(entry) {
+  const logPath = resolveLogPath();
+  if (!logPath) return;
+  try {
+    const dir = path.dirname(logPath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', { encoding: 'utf8' });
+  } catch (_e) { /* soft-fail */ }
+}
+
+/**
+ * Summarize violations into a tight one-line advisory. Keeps the message
+ * short enough for the statusline. LOCAL-only: no file content echoed,
+ * only basename + field names.
+ */
+function summarizeViolations(violations, basename, severity) {
+  const MAX_FIELDS = 3;
+  // Split the flat field list into the two actionable buckets: fields the
+  // schema wanted but the writer omitted (missing), and fields the writer
+  // emitted that the schema does not recognize (unexpected drift). A reader
+  // needs to know WHICH way the mismatch runs to fix it -- "add X" vs
+  // "the schema is missing Y". Malformed / delegate markers (fields starting
+  // with '__') are structural, not per-field, so they are excluded here.
+  const missing = [];
+  const unexpected = [];
+  for (const v of violations) {
+    if (!v || !v.field || v.field.startsWith('__')) continue;
+    const bucket = v.type === 'missing' ? missing : unexpected;
+    if (bucket.indexOf(v.field) === -1 && bucket.length < MAX_FIELDS) {
+      bucket.push(v.field);
+    }
+  }
+  const parts = [];
+  if (missing.length > 0) parts.push('missing: ' + missing.join(', '));
+  if (unexpected.length > 0) parts.push('unexpected: ' + unexpected.join(', '));
+  const detail = parts.length > 0 ? parts.join('; ') : '(structure)';
+  const label = severity === 'warning' ? 'schema drift' : 'schema violation';
+  return label + ': ' + detail + ' in ' + basename;
+}
+
+// ---------- Main ----------
+
+function main() {
+  // Soft-fail: any exception in this hook becomes a silent advisory. The
+  // PostToolUse surface must NEVER break a user's Write / Edit / MultiEdit
+  // tool call.
+  let raw;
+  try {
+    raw = readStdinSync();
+    if (!raw || !raw.trim()) return exitSilent();
+  } catch (_e) { return exitSilent(); }
+
+  let payload;
+  try { payload = JSON.parse(raw); }
+  catch (_e) { return exitSilent(); }
+  if (!payload || typeof payload !== 'object') return exitSilent();
+
+  const tool = extractToolName(payload);
+  if (tool && !/^(Write|Edit|MultiEdit)$/.test(tool)) return exitSilent();
+
+  const filePath = extractFilePath(payload);
+  if (!filePath) return exitSilent();
+
+  // Only .md files carry frontmatter schemas we care about.
+  if (!/\.md$/i.test(filePath)) return exitSilent();
+
+  const scope = resolveRoomScope(filePath);
+  if (!scope) return exitSilent(); // not in a room: nothing to validate
+
+  // Read the file body. Absent or unreadable -> silent no-op.
+  let body;
+  try {
+    if (!fs.existsSync(filePath)) return exitSilent();
+    body = fs.readFileSync(filePath, 'utf8');
+  } catch (_e) { return exitSilent(); }
+
+  const parsed = parseFrontmatter(body);
+  if (parsed.noFrontmatter) return exitSilent(); // no YAML block to check
+
+  // Load the pure schema validator. If the require fails, silent no-op.
+  let schemas;
+  try {
+    schemas = require(path.resolve(__dirname, '..', 'lib', 'core', 'frontmatter-schemas.cjs'));
+  } catch (_e) { return exitSilent(); }
+
+  let result;
+  try {
+    result = schemas.validate(filePath, parsed.frontmatter);
+  } catch (_e) { return exitSilent(); }
+
+  if (!result || result.severity === 'info' || result.valid === true) {
+    return exitSilent();
+  }
+
+  const basename = path.basename(filePath);
+  const violations = Array.isArray(result.violations) ? result.violations : [];
+
+  // Append one log entry per advisory event. Keeps one-file-one-event
+  // semantics for /mos:admin review.
+  appendViolationLog({
+    ts: new Date().toISOString(),
+    file_path: filePath,
+    room_root: scope.roomRoot,
+    section: scope.section,
+    schema_used: schemas.selectSchemaKey
+      ? schemas.selectSchemaKey(filePath)
+      : 'artifact-default',
+    violations: violations,
+    severity: result.severity,
+  });
+
+  // Severity routing:
+  //   critical / error   -> systemMessage advisory
+  //   warning            -> systemMessage drift notice (still advisory)
+  //   info               -> silent (handled above)
+  if (result.severity === 'critical' || result.severity === 'error' ||
+      result.severity === 'warning') {
+    const msg = summarizeViolations(violations, basename, result.severity);
+    emitEnvelope(msg);
+    process.exit(0);
+  }
+
+  return exitSilent();
+}
+
+// Outer try/catch is the soft-fail guarantee. An advisory hook must never
+// crash the PostToolUse lifecycle.
+try { main(); }
+catch (_e) { try { exitSilent(); } catch (_f) { process.exit(0); } }

package/scripts/fts-index-drain.cjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * scripts/fts-index-drain.cjs -- Phase 244 Plan 02, the EXPENSIVE half of the
+ * enqueue-then-drain debounce whose CHEAP half is
+ * lib/core/eureka/fts-index-lifecycle.cjs. Structured exactly like the
+ * shipped scripts/gsd-graph-derive-drain.cjs / scripts/brain-derivation-
+ * drain.cjs pair: the lifecycle module enqueues a build request and spawns
+ * this file detached; this file builds the index and reconciles the queue.
+ *
+ * DIVISION OF LABOR: lib/core/eureka/fts-index-lifecycle.cjs enqueues
+ * (requestFtsBuild) and spawns (spawnFtsBuildDrain), both sync and cheap,
+ * safe to call inside the 1200 ms NAV budget. THIS file does the expensive
+ * work -- it opens room.db, calls the async tri-modal-index.indexNodes, and
+ * reconciles the queue -- and only ever runs detached, off the foreground
+ * turn.
+ *
+ * FAILURE DISCIPLINE: exit-0-never-block, but NEVER SILENT ROT. This process
+ * ALWAYS exits 0 on every non-fatal path (it must never block a session-start
+ * or post-write hook). A failed build KEEPS its queue entry with an
+ * incremented `attempts` counter, so the next drain retries it -- it is NEVER
+ * silently cleared on failure. Only after FTS_BUILD_MAX_ATTEMPTS failed
+ * passes is the entry dropped, and even then a permanent-failure record is
+ * appended to <roomDir>/.mindrian/fts-index-failures.json (Plan 06's doctor
+ * module reads this file), so a doctor check can surface it. Only a
+ * SUCCESSFUL build clears an entry.
+ *
+ * NON-GOAL, with the measurement behind it: this script does NOT index
+ * `fragments`. `indexNodes` reads `SELECT id, type, properties FROM nodes`
+ * and never touches `fragments`, so the correct behavior here is simply the
+ * default -- no code change is needed to exclude it, and none should ever be
+ * added. Measured live against the real `rethinking-mindrianos` room.db: with
+ * `fragments` INCLUDED in the corpus, the turn "what is the weather in paris
+ * today" produced 3 confident hits (fragments is raw conversation transcript
+ * that contains every common English word many times, so it false-matches
+ * anything). With `fragments` EXCLUDED, that same turn plus "my cat needs a
+ * vet appointment tomorrow" and "order pizza for dinner tonight" all produced
+ * 0 hits, while two genuinely relevant turns produced 5 hits each. The corpus
+ * choice does almost all the work and needs no threshold tuning. A future
+ * edit that "helpfully" widens the corpus to include `fragments` destroys
+ * this phase's whole precision story.
+ *
+ * Canon Part 8: LOCAL only. Opens room.db through the navigation chokepoint's
+ * WRITABLE door (openRoomDbForCaller) -- this process WRITES the index, so
+ * the read-only door (openRoomDbReadOnlyForCaller) would be wrong here. Zero
+ * network, zero Brain call.
+ * Canon Part 9: room.db is reached ONLY through lib/core/navigation.cjs.
+ *
+ * CLI modes:
+ *   node scripts/fts-index-drain.cjs --worker --room <dir>  -- drain one room's
+ *                                                               queue. --worker
+ *                                                               is informational:
+ *                                                               this process IS
+ *                                                               the detached
+ *                                                               worker already,
+ *                                                               so it must never
+ *                                                               re-spawn a second
+ *                                                               copy of itself.
+ *   node scripts/fts-index-drain.cjs --worker                -- drain the
+ *                                                               active/resolved
+ *                                                               room's queue
+ *                                                               (same resolver
+ *                                                               gsd-graph-derive-
+ *                                                               drain.cjs uses).
+ *
+ * Pure CJS, node built-ins plus the repo's own lib/core modules, zero npm
+ * deps. No em-dashes (CLAUDE.md).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  readQueue,
+  writeQueue,
+  FTS_BUILD_MAX_ATTEMPTS,
+} = require('../lib/core/eureka/fts-index-lifecycle.cjs');
+const { indexNodes } = require('../lib/core/eureka/tri-modal-index.cjs');
+const { openRoomDbForCaller, closeRoomDbForCaller } = require('../lib/core/navigation.cjs');
+// Reuse the room resolver verbatim rather than hand-rolling a second one
+// (Part 7): gsd-graph-derive-drain.cjs itself resolves its no-argument case
+// the exact same way, through sweep.resolveRoomDir.
+const sweep = require('./gsd-graph-derive-sweep.cjs');
+
+// ---------------------------------------------------------------------------
+// Permanent-failure log: <roomDir>/.mindrian/fts-index-failures.json
+// ---------------------------------------------------------------------------
+
+function failuresLogPath(roomDir) {
+  return path.join(roomDir, '.mindrian', 'fts-index-failures.json');
+}
+
+// Truncate an error to a short SCALAR string (Part 8 belt-and-suspenders:
+// this is a producer/sqlite error message, not artifact body, but the cap
+// keeps the LOCAL-disk-only log bounded and honest).
+function scalarError(err) {
+  const msg = (err && typeof err.message === 'string') ? err.message : String(err || 'unknown_error');
+  return msg.slice(0, 200);
+}
+
+// Append a permanent-failure record. Bounded to the most-recent MAX_LOG rows
+// so a permanently-broken room never grows the log unbounded. Atomic
+// tmp+rename write (the sweep idiom). Advisory: a failed log write NEVER
+// blocks the drain.
+function appendFailureRecord(roomDir, record) {
+  const MAX_LOG = 200;
+  try {
+    const p = failuresLogPath(roomDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    let log = [];
+    try {
+      const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+      if (Array.isArray(parsed)) log = parsed;
+      else if (parsed && Array.isArray(parsed.failures)) log = parsed.failures;
+    } catch (_e) { log = []; }
+    log.push(record);
+    if (log.length > MAX_LOG) log = log.slice(log.length - MAX_LOG);
+    const tmp = p + '.tmp-' + process.pid + '-' + Date.now().toString(36);
+    fs.writeFileSync(tmp, JSON.stringify({ failures: log }, null, 2));
+    fs.renameSync(tmp, p);
+  } catch (_e) {
+    /* advisory: a failed log write must never block the drain. */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Argv parsing: a process.argv loop matching the repo convention (no
+// Commander, no yargs).
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = { worker: false, roomDir: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--worker') {
+      out.worker = true; // informational: this process IS the detached worker.
+    } else if (argv[i] === '--room' && argv[i + 1]) {
+      out.roomDir = argv[i + 1];
+      i += 1;
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The drain: read the queue, build per entry, reconcile.
+// ---------------------------------------------------------------------------
+
+// drainRoom(resolved) -> void. Never throws (every per-entry fault is caught
+// individually so one bad room/entry cannot abort the pass).
+async function drainRoom(resolved) {
+  const q = readQueue(resolved);
+  const entries = Array.isArray(q.entries) ? q.entries : [];
+  if (entries.length === 0) return; // empty queue: no db work, no queue mutation.
+
+  const kept = [];
+  for (const entry of entries) {
+    const roomDir = (entry && typeof entry.roomDir === 'string' && entry.roomDir.length > 0)
+      ? entry.roomDir
+      : resolved;
+    let db = null;
+    try {
+      db = openRoomDbForCaller(roomDir);
+      if (!db) {
+        throw new Error('fts-index-drain: room.db unavailable for ' + roomDir);
+      }
+      // roomDir threaded explicitly: without it the corpus collapses to claim
+      // text plus artifact TITLES only, because the Artifact/memory_artifact
+      // path-body fallback (tri-modal-index.cjs) is what makes the corpus
+      // substantive.
+      // eslint-disable-next-line no-await-in-loop
+      await indexNodes(db, { roomDir: roomDir });
+      // Success: entry is cleared (not pushed onto `kept`).
+    } catch (e) {
+      const priorAttempts = (entry && Number.isFinite(entry.attempts)) ? entry.attempts : 0;
+      const attempts = priorAttempts + 1;
+      if (attempts >= FTS_BUILD_MAX_ATTEMPTS) {
+        // Capped: drop the entry, but NEVER silently -- a permanent-failure
+        // record survives so a doctor check can surface it.
+        appendFailureRecord(resolved, {
+          roomDir: roomDir,
+          failed_at: new Date().toISOString(),
+          attempts: attempts,
+          message: scalarError(e),
+        });
+      } else {
+        // Keep-on-failure: the retry signal survives for the next drain.
+        kept.push(Object.assign({}, entry, { attempts: attempts }));
+      }
+    } finally {
+      closeRoomDbForCaller(db);
+    }
+  }
+  writeQueue(resolved, { entries: kept });
+}
+
+// ---------------------------------------------------------------------------
+// Entry point: drain one room's queue and exit 0 always.
+// ---------------------------------------------------------------------------
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const roomDir = args.roomDir
+      ? path.resolve(args.roomDir)
+      : sweep.resolveRoomDir(null);
+    if (roomDir) {
+      await drainRoom(path.resolve(roomDir));
+    }
+    // No room resolves: exit 0 silently (nothing to drain).
+  } catch (_e) {
+    // Top-level guard: this process must ALWAYS exit 0 on any non-fatal path.
+  }
+  process.exit(0);
+}
+
+module.exports = { drainRoom, failuresLogPath };
+
+if (require.main === module) {
+  main();
+}