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

package/scripts/check-gate-seam.cjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * check-gate-seam.cjs
+ *
+ * RELEASE GATE (D-08, GATE-01 G-1). lib/core/seam-liveness.cjs was built by
+ * Phase 235 as the repo-wide primitive for this milestone's recurring
+ * failure shape -- a mechanism wired at one end and inert at the other.
+ * checkMintRatifierLiveness was written for Phase 238 by name: it catches a
+ * gate kind that some mint call site can produce but no ratifier declares
+ * reachable. Until this file existed, that helper had zero production
+ * consumers -- it lived only inside a test file, which is exactly the
+ * dead-seam shape this milestone exists to close. This script exists so the
+ * check runs inside a real release gate (scripts/verify-release, section
+ * 18), not only in a test (D-08).
+ *
+ * What it checks: every gate kind a real mint call site in this repo can
+ * produce has a ratifier that can consume it.
+ *
+ * How the MINTED set is built -- three real call sites, driven for real,
+ * NOT a hand-supplied copy of what this script assumes their literals are
+ * (a hand-supplied copy would not turn red if a call site's own literal
+ * were renamed, which is exactly the mutation-gate proof
+ * tests/test-238-mint-ratifier-seam.cjs carries):
+ *
+ *   1. 'general' -- lib/mcp/tools/gate.cjs's own DEFAULT-fallback literal.
+ *      _mintLiveGate is called with a card that carries NO kind key, so
+ *      gate.cjs's own internal ternary (`card.kind ... : 'general'`)
+ *      resolves the value -- the literal lives inside gate.cjs itself, not
+ *      here.
+ *   2. 'binding' -- the caller-supplied pass-through path. There is no
+ *      hardcoded 'binding' literal anywhere in gate.cjs or chain.cjs (it is
+ *      always a value an external caller supplies via the gate_render MCP
+ *      parameter); this call proves the pass-through mechanism itself
+ *      mints a 'binding'-kind entry, which is genuinely how the real
+ *      system produces one.
+ *   3. 'material_step' -- lib/mcp/tools/chain.cjs's own halt-branch
+ *      literal, inside chainRun. Driven by running a REAL chainRun to a
+ *      real halt (the same shape tests/test-238-one-ledger.cjs's Task 1
+ *      proof uses), NOT by calling _mintResumeLedger with a hand-supplied
+ *      { kind: 'material_step' } object -- that shortcut would silently
+ *      keep passing even if chain.cjs's own literal were renamed, because
+ *      this script would still be minting its OWN copy of the string
+ *      instead of chain.cjs's.
+ *
+ * mintedGateKinds() (lib/mcp/gate-ledger.cjs's own live-ledger scan) is
+ * read back AFTER all three real mints land, so the ledger module that
+ * owns the ledger -- not a text scan of gate.cjs/chain.cjs source for
+ * kind: literals -- stays the single source of truth for what got minted.
+ * All three probe entries are consumed back out immediately after the
+ * read so this diagnostic run leaves no residue in the shared ledger.
+ *
+ * How the RATIFIABLE set is built: lib/mcp/gate-ledger.cjs's own
+ * ratifiableGateKinds() -- the frozen, independently declared list. MINTED
+ * and RATIFIABLE are sourced from two independently-computed paths (one
+ * driven live through real mint call sites, one a frozen declared
+ * constant), so a mutation to either one moves independently of the other.
+ *
+ * D-13 (vacuity is the named trap): assertSeamLive returns ok:true with a
+ * claim count of zero by design, because a seam that claims nothing cannot
+ * be dead. A wiring bug that produced an empty MINTED array would read
+ * green forever if claimedCount were ignored. This gate treats a zero claim
+ * count as a FAILURE (exit 1), never as success -- the anti-vacuity rule is
+ * part of the gate, not only of the unit test.
+ *
+ * Exit codes:
+ *   0 -- clean: every minted kind has a reachable ratifier, claim count > 0
+ *   1 -- a minted kind has no reachable ratifier, OR the minted-kind claim
+ *        set is empty (the vacuity trap)
+ *   2 -- the check itself could not run (a require failure, a missing
+ *        export, a halt that did not happen, or any other internal fault).
+ *        NEVER exit 0 on an internal error -- a scanner that silently
+ *        passes is the failure mode this whole milestone is about.
+ *
+ * Node built-ins plus repo modules only. No new dependency. No em-dashes.
+ */
+
+const path = require('node:path');
+
+// Real halt-branch driver for kind 3 ('material_step'). A postureFn that
+// always halts step 1 as a material step -- the halt CONTROL FLOW is what
+// this script needs to reach chain.cjs's own mint call site; posture
+// classification itself is a separate concern this file does not test.
+function alwaysHaltPosture() {
+  return { autonomous_safe: false, posture: 'halt' };
+}
+
+async function mintMaterialStepProbe(chainTool) {
+  async function onStep() {
+    // Never actually reached -- the gate this script mints is never
+    // answered/approved, so the halted step never executes.
+    return { chain_output: null };
+  }
+  const result = await chainTool.chainRun(
+    [{ step: 1, framework: 'check-gate-seam-probe', command: null, optional: false }],
+    { onStep: onStep, postureFn: alwaysHaltPosture, gateRenderCtx: {} }
+  );
+  if (!result || result.halted !== true || !result.gate || typeof result.gate.gate_id !== 'string' || result.gate.gate_id.length === 0) {
+    throw new Error('check-gate-seam: the probe chainRun did not halt as expected -- cannot drive chain.cjs\'s real material_step mint call site');
+  }
+  return result.gate.gate_id;
+}
+
+async function main() {
+  const gateLedger = require(path.join(__dirname, '..', 'lib', 'mcp', 'gate-ledger.cjs'));
+  const seamLiveness = require(path.join(__dirname, '..', 'lib', 'core', 'seam-liveness.cjs'));
+  const gateTool = require(path.join(__dirname, '..', 'lib', 'mcp', 'tools', 'gate.cjs'));
+  const chainTool = require(path.join(__dirname, '..', 'lib', 'mcp', 'tools', 'chain.cjs'));
+
+  if (typeof seamLiveness.checkMintRatifierLiveness !== 'function') {
+    throw new Error('lib/core/seam-liveness.cjs did not export checkMintRatifierLiveness');
+  }
+  if (typeof gateLedger.mintedGateKinds !== 'function' || typeof gateLedger.ratifiableGateKinds !== 'function') {
+    throw new Error('lib/mcp/gate-ledger.cjs did not export mintedGateKinds/ratifiableGateKinds');
+  }
+  if (!gateTool._internal || typeof gateTool._internal._mintLiveGate !== 'function') {
+    throw new Error('lib/mcp/tools/gate.cjs did not export _internal._mintLiveGate');
+  }
+  if (typeof chainTool.chainRun !== 'function') {
+    throw new Error('lib/mcp/tools/chain.cjs did not export chainRun');
+  }
+
+  const pid = process.pid;
+  const generalProbeId = 'check-gate-seam-probe-general-' + pid;
+  const bindingProbeId = 'check-gate-seam-probe-binding-' + pid;
+
+  // Kind 1: gate.cjs's own default-fallback literal (no kind key on the
+  // card -- gate.cjs's own internal ternary resolves it).
+  gateTool._internal._mintLiveGate(generalProbeId, {}, undefined);
+  // Kind 2: the caller-supplied 'binding' pass-through path.
+  gateTool._internal._mintLiveGate(bindingProbeId, { kind: 'binding' }, undefined);
+  // Kind 3: chain.cjs's own halt-branch literal, driven by a real halt.
+  const materialGateId = await mintMaterialStepProbe(chainTool);
+
+  const minted = gateLedger.mintedGateKinds();
+  const ratifiable = gateLedger.ratifiableGateKinds();
+
+  // Cleanup: consume every probe entry back out of the shared ledger so
+  // this diagnostic run leaves no residue. Best-effort by construction --
+  // each id above was just minted under the same process-scoped
+  // NO_SESSION_PREFIX key (sessionId left undefined throughout), so
+  // consumeGate is guaranteed to find it.
+  gateLedger.consumeGate(generalProbeId, undefined);
+  gateLedger.consumeGate(bindingProbeId, undefined);
+  gateLedger.consumeGate(materialGateId, undefined);
+
+  const result = seamLiveness.checkMintRatifierLiveness(minted, ratifiable);
+
+  if (result.claimedCount === 0) {
+    console.error('check-gate-seam: FAIL (vacuity)');
+    console.error('The minted-kind claim set is empty. A seam claiming nothing reads');
+    console.error('vacuously live under assertSeamLive (D-13) -- this gate refuses to');
+    console.error('treat that as success.');
+    console.error('Minted kinds observed: ' + JSON.stringify(minted));
+    process.exit(1);
+  }
+
+  if (!result.ok) {
+    console.error('check-gate-seam: FAIL');
+    console.error('claimedCount: ' + result.claimedCount + '  liveCount: ' + result.liveCount);
+    console.error('checkMintRatifierLiveness found ' + result.dead.length + ' minted kind(s) with no reachable ratifier:');
+    for (const kind of result.dead) {
+      console.error('  ' + kind);
+    }
+    console.error('Ratifiable kinds (lib/mcp/gate-ledger.cjs ratifiableGateKinds()): ' + JSON.stringify(ratifiable));
+    process.exit(1);
+  }
+
+  console.log('check-gate-seam: PASS');
+  console.log('Minted kinds (driven through the real gate.cjs/chain.cjs mint call sites): ' + JSON.stringify(minted));
+  console.log('Ratifiable kinds (lib/mcp/gate-ledger.cjs ratifiableGateKinds()): ' + JSON.stringify(ratifiable));
+  console.log('checkMintRatifierLiveness: ok=true claimedCount=' + result.claimedCount + ' liveCount=' + result.liveCount);
+}
+
+main().catch((e) => {
+  console.error('check-gate-seam: SCANNER FAILURE -- ' + ((e && e.stack) || String(e)));
+  process.exit(2);
+});

package/scripts/check-graph-derive-health.cjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * scripts/check-graph-derive-health.cjs -- Phase 298 Plan 06 (SEED-037 4d).
+ *
+ * THE GATE, NOT THE DETECTOR. This script is a THIN CLI WRAPPER over
+ * lib/core/doctor/graph-derive-health-module.cjs -- specifically its
+ * `detectRoomHealth(roomDir)` and `check(ctx)` exports. That module's own
+ * header names itself THE ONE SHARED DETECTION SIGNAL with two consumers
+ * (its own check()/fix() and the graph-derive-heal-retrofit sibling) and
+ * says "never a second copy". This script is a THIRD consumer, which per
+ * that module's own doctrine makes it a wrapper, never a reimplementation
+ * (Canon Part 7, reuse before build). It contains zero structural/semantic
+ * edge-detection logic of its own -- every status this script reports was
+ * derived by graph-derive-health-module.cjs's detectRoomHealth()/check(),
+ * never recomputed here.
+ *
+ * MONITOR, NOT REPAIR. SEED-037 4c (healing the roughly 16 already-damaged
+ * rooms) is a separate, human-gated action -- the module's own `fix()` /
+ * `--heal-room` path. This script never calls fix() and never writes into a
+ * room; it reports and exits.
+ *
+ * Canon Part 8: every read this script triggers is LOCAL. detectRoomHealth()
+ * opens room.db only through the read-only door
+ * (openRoomDbReadOnlyForCaller, lib/core/navigation/spine-events.cjs:523) --
+ * this script itself never touches node:sqlite and never opens a database.
+ * Zero network, zero Brain calls.
+ *
+ * Exit map (the repo's own 0/1/2 scanner convention):
+ *   0  clean        status 'ok' or 'skip' (skip = Tier 0 room, nothing to
+ *                    derive yet -- the committed converged-room fixture has
+ *                    no room.db and is therefore the green case)
+ *   1  finding      status 'fail', or status 'warn' under --strict
+ *   2  scanner/usage fault  unknown flag, missing --room value, a load or
+ *                    detection error -- never a raw stack trace on stderr
+ *
+ * CLI convention (CLAUDE.md): process.argv switch-case routing, no
+ * Commander/yargs, no new dependencies. Argv-loop shape copied from
+ * scripts/check-worktree-hygiene.cjs.
+ *
+ * No CIRS / HITL shape declaration: this is a script, not an invocable
+ * surface under commands/, skills/, or agents/, and no sibling
+ * scripts/check-*.cjs carries one -- confirmed with
+ * `node scripts/check-cirs-declaration.cjs --check` after this file landed.
+ */
+
+const path = require('node:path');
+
+const SCRIPT_NAME = 'check-graph-derive-health';
+
+function usage() {
+  return [
+    SCRIPT_NAME + ': the SEED-037 4d CLI gate. Wraps detectRoomHealth()/check()',
+    'from lib/core/doctor/graph-derive-health-module.cjs -- never a second detector.',
+    '',
+    'Usage: node scripts/' + SCRIPT_NAME + '.cjs [--room <dir>] [--all] [--json] [--strict] [--check] [--help]',
+    '',
+    'Flags:',
+    '  --room <dir>  check exactly one room directory via detectRoomHealth(dir)',
+    '  --all         check every registered room (cascade scope, class-level)',
+    '  (neither)     check the registry-active room only',
+    '  --json        print the module\'s returned object verbatim as JSON',
+    '  --strict      map a warn status to exit 1 (default: warn exits 0)',
+    '  --check       accepted as an explicit no-op (the default action)',
+    '  --help        print this message and exit 0',
+    '',
+    'Exit codes:',
+    '  0  clean: status ok or skip (skip = Tier 0 room, nothing to derive yet',
+    '     -- the committed converged-room fixture reports this, the green case)',
+    '  1  finding: status fail, or status warn under --strict',
+    '  2  scanner or usage fault: unknown flag, missing --room value, or a',
+    '     load/detection error -- never a raw stack trace on stderr',
+    '',
+    'Monitor only: this gate never repairs a room. Healing damaged rooms',
+    '(SEED-037 4c) is a separate, human-gated action (the wrapped module\'s',
+    'own fix() / --heal-room path), never reached from here.',
+  ].join('\n');
+}
+
+// mapStatusToExit(status, strict) -> 0 | 1. The exit map is exact: fail is
+// always a finding; warn is a finding only under --strict; ok and skip (and
+// any unrecognized status) are clean. Exported so the test can exercise the
+// mapping in-process without spawning.
+function mapStatusToExit(status, strict) {
+  if (status === 'fail') return 1;
+  if (status === 'warn') return strict ? 1 : 0;
+  return 0;
+}
+
+function printHuman(mode, result, roomArg) {
+  if (mode === 'room') {
+    const reasons = (result.reasons && result.reasons.length) ? result.reasons.join('; ') : '(none)';
+    console.log(
+      SCRIPT_NAME + ': status=' + result.status
+      + ' room=' + roomArg
+      + ' queue=' + (result.queueCount || 0)
+      + ' reasons=' + reasons
+    );
+    return;
+  }
+  console.log(
+    SCRIPT_NAME + ': status=' + result.status
+    + ' scope=' + result.scope
+    + ' ' + result.detail
+  );
+  for (const r of (result.rooms || [])) {
+    const reasons = (r.reasons && r.reasons.length) ? r.reasons.join('; ') : '(none)';
+    console.log(
+      '  ' + r.room + ' (' + (r.roomPath || 'unresolved') + '):'
+      + ' status=' + r.status
+      + ' queue=' + (r.queueCount || 0)
+      + ' reasons=' + reasons
+    );
+  }
+}
+
+// main(argv?) -> exit code (does not call process.exit itself, so the test
+// harness can call it in-process and assert on the return value).
+function main(argv) {
+  const args = argv || process.argv.slice(2);
+
+  if (args.includes('--help')) {
+    console.log(usage());
+    return 0;
+  }
+
+  let roomDir = null;
+  let all = false;
+  let asJson = false;
+  let strict = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--room') {
+      const value = args[i + 1];
+      if (!value) {
+        console.error(SCRIPT_NAME + ': --room was given with no directory argument');
+        return 2;
+      }
+      roomDir = path.resolve(value);
+      i++;
+    } else if (a === '--all') {
+      all = true;
+    } else if (a === '--json') {
+      asJson = true;
+    } else if (a === '--strict') {
+      strict = true;
+    } else if (a === '--check') {
+      /* default action, accepted explicitly as a no-op */
+    } else {
+      console.error(SCRIPT_NAME + ': unknown flag ' + a + ' (see --help)');
+      return 2;
+    }
+  }
+
+  let healthMod;
+  try {
+    healthMod = require('../lib/core/doctor/graph-derive-health-module.cjs');
+  } catch (e) {
+    console.error(SCRIPT_NAME + ': could not load graph-derive-health-module.cjs: ' + ((e && e.message) || e));
+    return 2;
+  }
+
+  let mode;
+  let result;
+  try {
+    if (roomDir) {
+      mode = 'room';
+      result = healthMod.detectRoomHealth(roomDir);
+    } else if (all) {
+      mode = 'check';
+      result = healthMod.check({ flags: { cascadeRooms: true } });
+    } else {
+      mode = 'check';
+      result = healthMod.check({ flags: {} });
+    }
+  } catch (e) {
+    console.error(SCRIPT_NAME + ': ' + ((e && e.message) || e));
+    return 2;
+  }
+
+  if (!result || typeof result.status !== 'string') {
+    console.error(SCRIPT_NAME + ': the wrapped module returned no usable status');
+    return 2;
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(mode, result, roomDir);
+  }
+
+  return mapStatusToExit(result.status, strict);
+}
+
+if (require.main === module) {
+  let exitCode;
+  try {
+    exitCode = main();
+  } catch (e) {
+    console.error(SCRIPT_NAME + ': uncaught: ' + ((e && e.message) || e));
+    exitCode = 2;
+  }
+  process.exit(exitCode);
+}
+
+module.exports = { main, mapStatusToExit, usage };

package/scripts/check-graph-export-typemap.cjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * SEED-026 W3 (Phase 162-03 Task 2) - scripts/check-graph-export-typemap.cjs
+ *
+ * The node-type-map COMPLETENESS gate (CI tripwire, T-162-08 mitigation).
+ *
+ * WHY THIS EXISTS: getGraphExport (lib/core/navigation/graph-export.cjs) renders
+ * every room.db node by looking its `type` up in NODE_TYPE_RENDER, skipping the
+ * bookkeeping set in EXCLUDE_TYPES, and rendering anything ELSE LOUD as 'unknown'
+ * (default color) + flagging it in unmapped_types. That graceful fallback keeps
+ * the hot /mos:present path from throwing -- but it also means a NEW schema phase
+ * can add a node type that silently renders as a gray 'unknown' blob in the
+ * published viz, with nobody noticing. This gate FAILS LOUD on exactly that: it
+ * opens a room.db, reads the DISTINCT node types it actually carries, and asserts
+ * every one is either in NODE_TYPE_RENDER or in EXCLUDE_TYPES. Any type that is in
+ * NEITHER set is an un-classified type -> exit non-zero, name the offender.
+ *
+ * Reads room.db DIRECTLY (node:sqlite) for a read-only SELECT DISTINCT type query.
+ * This is a CI gate over a static fixture, not a runtime navigation path, so it
+ * does not go through the navigation.cjs chokepoint -- it deliberately reuses the
+ * SAME node:sqlite DatabaseSync that lazygraph-ops.cjs/openGraph uses, mirroring
+ * the existing test idiom. It NEVER writes. Canon Part 8: LOCAL only, no Brain.
+ *
+ * CLI:    node scripts/check-graph-export-typemap.cjs <roomDir>
+ *         (exit 0 = every type classified; exit 1 = unmapped type or error)
+ * Import: const { checkTypeMap } = require('./check-graph-export-typemap.cjs');
+ *         checkTypeMap(roomDir) -> { ok, dbExists, distinctTypes, mapped,
+ *                                    excluded, unmapped }  (never throws)
+ *
+ * No emoji. No em-dashes (CLAUDE.md HARD RULE). Hyphens only.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { DatabaseSync } = require('node:sqlite');
+
+const { NODE_TYPE_RENDER, EXCLUDE_TYPES } = require('../lib/core/navigation/graph-export.cjs');
+
+/**
+ * Diff a room.db's live node types against the mapped + excluded sets.
+ * @param {string} roomDir - path to the room directory (contains .mindrian/room.db)
+ * @returns {{
+ *   ok: boolean, dbExists: boolean,
+ *   distinctTypes: string[], mapped: string[], excluded: string[], unmapped: string[],
+ *   error?: string
+ * }}
+ */
+function checkTypeMap(roomDir) {
+  const dbPath = path.join(path.resolve(roomDir), '.mindrian', 'room.db');
+  if (!fs.existsSync(dbPath)) {
+    // No db is not an unmapped-type failure: an empty/cold room has nothing to
+    // classify. ok=true, dbExists=false so callers can distinguish.
+    return { ok: true, dbExists: false, distinctTypes: [], mapped: [], excluded: [], unmapped: [] };
+  }
+
+  let db;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    const rows = db.prepare('SELECT DISTINCT type FROM nodes').all();
+    const distinctTypes = rows.map((r) => r.type).filter((t) => t != null).sort();
+
+    const mapped = [];
+    const excluded = [];
+    const unmapped = [];
+    for (const t of distinctTypes) {
+      if (Object.prototype.hasOwnProperty.call(NODE_TYPE_RENDER, t)) {
+        mapped.push(t);
+      } else if (EXCLUDE_TYPES.has(t)) {
+        excluded.push(t);
+      } else {
+        unmapped.push(t);
+      }
+    }
+    return { ok: unmapped.length === 0, dbExists: true, distinctTypes, mapped, excluded, unmapped };
+  } catch (err) {
+    return {
+      ok: false, dbExists: true,
+      distinctTypes: [], mapped: [], excluded: [], unmapped: [],
+      error: err && err.message ? err.message : String(err),
+    };
+  } finally {
+    if (db) { try { db.close(); } catch (_) {} }
+  }
+}
+
+module.exports = { checkTypeMap };
+
+// --- CLI ---
+if (require.main === module) {
+  const roomDir = process.argv[2];
+  if (!roomDir) {
+    process.stderr.write('usage: node scripts/check-graph-export-typemap.cjs <roomDir>\n');
+    process.exit(2);
+  }
+  const res = checkTypeMap(roomDir);
+  if (res.error) {
+    process.stderr.write('check-graph-export-typemap: ERROR opening ' + roomDir + ': ' + res.error + '\n');
+    process.exit(1);
+  }
+  if (!res.dbExists) {
+    process.stdout.write('check-graph-export-typemap: no room.db at ' + roomDir + ' (nothing to classify) -- PASS\n');
+    process.exit(0);
+  }
+  process.stdout.write('check-graph-export-typemap: ' + res.distinctTypes.length + ' distinct node types ('
+    + res.mapped.length + ' mapped, ' + res.excluded.length + ' excluded)\n');
+  if (!res.ok) {
+    process.stderr.write('check-graph-export-typemap: FAIL -- ' + res.unmapped.length
+      + ' UNMAPPED node type(s) (neither in NODE_TYPE_RENDER nor EXCLUDE_TYPES): '
+      + res.unmapped.join(', ') + '\n');
+    process.stderr.write('  Add each to NODE_TYPE_RENDER (to render it) or EXCLUDE_TYPES (to skip it) in '
+      + 'lib/core/navigation/graph-export.cjs.\n');
+    process.exit(1);
+  }
+  process.stdout.write('check-graph-export-typemap: PASS -- every live node type is classified.\n');
+  process.exit(0);
+}