@mindrian_os/cli 1.13.0-beta.10 → 1.13.0-beta.43

package/lib/core/folder-memory-async.cjs

@@ -1,338 +0,0 @@
-/*
- * Copyright (c) 2026 Mindrian. BSL 1.1.
- *
- * Phase 88-01 -- folder-memory ASYNC entry point
- * ===============================================
- * Promise-returning twin of lib/core/folder-memory.cjs. Import this from
- * MCP tool handlers and any caller that returns a Promise to the MCP
- * runtime. NEVER import from CLI hook scripts that expect synchronous
- * semantics -- use the sync entry point.
- *
- * Key-set parity with the sync entry point is enforced programmatically
- * by lib/memory/folder-memory.test.cjs (mirrors the Phase 87-04
- * sync-async-entry-points.test.cjs pattern). Future maintainers cannot
- * drift signatures without breaking the test.
- *
- * All reads go through fs.promises so the MCP handler loop stays
- * non-blocking. Invariant validation falls back to the sync validator
- * (feynman-minto-invariants.cjs validate() is pure-CPU; the MCP loop
- * does not see disk blocking because the file content is already
- * loaded into memory at that point).
- *
- * License: BSL 1.1.
- */
-
-'use strict';
-
-const fs = require('node:fs');
-const fsp = fs.promises;
-const path = require('node:path');
-const shared = require('./folder-memory-shared.cjs');
-const invariants = require('./feynman-minto-invariants.cjs');
-
-const RESERVED = new Set(['ROOM.md', 'STATE.md', 'MINTO.md', 'TEAM-STATE.md']);
-
-async function safeStatAsync(p) {
-  try {
-    return await fsp.stat(p);
-  } catch (_e) {
-    return null;
-  }
-}
-
-async function safeReadAsync(p) {
-  try {
-    return await fsp.readFile(p, 'utf8');
-  } catch (_e) {
-    return null;
-  }
-}
-
-async function collectArtifactMtimesAsync(sectionPath) {
-  const mtimes = [];
-  let entries = [];
-  try {
-    entries = await fsp.readdir(sectionPath);
-  } catch (_e) {
-    return mtimes;
-  }
-  for (const name of entries) {
-    if (name[0] === '.') continue;
-    if (RESERVED.has(name)) continue;
-    const abs = path.join(sectionPath, name);
-    const st = await safeStatAsync(abs);
-    if (!st) continue;
-    if (st.isFile() && name.endsWith('.md')) {
-      mtimes.push(st.mtimeMs);
-    }
-  }
-  return mtimes;
-}
-
-/**
- * Async readTriple. Promise resolves to the same shape as the sync
- * entry point's return value. Never rejects for missing files; only
- * rejects on truly unexpected errors (e.g. out-of-memory while reading
- * a huge file) -- at which point the caller should fall back to the
- * sync path or log and degrade.
- */
-async function readTriple(sectionPath) {
-  const room = { ...shared.emptyRoom() };
-  const state = { ...shared.emptyState() };
-  const reasoning = { ...shared.emptyReasoning() };
-
-  const sectionStat = await safeStatAsync(sectionPath);
-  if (!sectionStat || !sectionStat.isDirectory()) {
-    reasoning.reasoning_health_score = shared.computeHealthScore(reasoning);
-    return { room: room, state: state, reasoning: reasoning };
-  }
-
-  const roomPath = path.join(sectionPath, 'ROOM.md');
-  const [roomStat, roomBuf] = await Promise.all([
-    safeStatAsync(roomPath),
-    safeReadAsync(roomPath),
-  ]);
-  if (roomStat && roomStat.isFile() && roomBuf !== null) {
-    Object.assign(room, shared.parseRoomMd(roomBuf, roomStat.mtimeMs));
-  }
-
-  const statePath = path.join(sectionPath, 'STATE.md');
-  const [stateStat, stateBuf] = await Promise.all([
-    safeStatAsync(statePath),
-    safeReadAsync(statePath),
-  ]);
-  if (stateStat && stateStat.isFile() && stateBuf !== null) {
-    Object.assign(state, shared.parseStateMd(stateBuf));
-  }
-
-  const mintoPath = path.join(sectionPath, 'MINTO.md');
-  const [mintoStat, mintoBuf] = await Promise.all([
-    safeStatAsync(mintoPath),
-    safeReadAsync(mintoPath),
-  ]);
-  if (mintoStat && mintoStat.isFile() && mintoBuf !== null) {
-    const parsed = shared.parseMintoMd(mintoBuf);
-    Object.assign(reasoning, parsed);
-    reasoning.exists = true;
-
-    let invariantSeverity = null;
-    try {
-      const v = invariants.validate(mintoPath);
-      invariantSeverity = v.severity;
-    } catch (_e) {
-      invariantSeverity = null;
-    }
-
-    const artifactMtimes = await collectArtifactMtimesAsync(sectionPath);
-    const stale = shared.computeStale(
-      reasoning,
-      artifactMtimes,
-      mintoStat.mtimeMs,
-      invariantSeverity
-    );
-    reasoning.is_stale = stale.is_stale;
-    reasoning.stale_reason = stale.stale_reason;
-  }
-
-  reasoning.reasoning_health_score = shared.computeHealthScore(reasoning);
-
-  return { room: room, state: state, reasoning: reasoning };
-}
-
-/**
- * Async readDecisionLog. Promise resolves to the decision_log array
- * (same permissive shape as the sync twin).
- */
-async function readDecisionLog(sectionPath) {
-  const mintoPath = path.join(sectionPath, 'MINTO.md');
-  const buf = await safeReadAsync(mintoPath);
-  if (buf === null) return [];
-  const parsed = shared.parseMintoMd(buf);
-  return Array.isArray(parsed.decision_log) ? parsed.decision_log : [];
-}
-
-/**
- * computeHealthScore is pure-CPU (no I/O). Wrapped in an async function
- * so every exported name is an AsyncFunction, matching the Phase 87-04
- * enforcement pattern: the parity test asserts every async export is
- * constructor.name === 'AsyncFunction'. Wrapping eliminates the
- * footgun where a future maintainer could accidentally expose a
- * synchronous helper on the async surface.
- */
-async function computeHealthScore(reasoning) {
-  return shared.computeHealthScore(reasoning);
-}
-
-// ---------- Phase 90-04 readQuadruple async twin (additive) ----------
-//
-// Async pair of the sync readQuadruple. Same shape, same semantics.
-// Key-set parity with the sync entry point is asserted by
-// lib/memory/folder-memory-quadruple.test.cjs (the same mechanism used
-// by the Phase 88-01 sync/async parity test).
-//
-// parseBrainMd in shared.cjs is a synchronous fs.readFileSync call.
-// Wrapping the call inside an async function keeps the async surface
-// consistent -- every exported name is an AsyncFunction, matching the
-// Phase 87-04 enforcement pattern. The cost is one synchronous file
-// read inside an async function; BRAIN.md is small (< 10KB in practice)
-// and this call happens once per section per session-start, so the
-// blocking cost is negligible compared to a dedicated promise-returning
-// parse variant.
-
-async function readQuadruple(sectionPath) {
-  const triple = await readTriple(sectionPath);
-  const brainPath = path.join(sectionPath, 'BRAIN.md');
-  const brain = shared.parseBrainMd(brainPath);
-  return shared.attachBrainToTriple(triple, brain);
-}
-
-/**
- * Async isQuadrupleFresh. Pure function wrapped in async to keep
- * key-set parity with the sync entry point. Same predicate semantics
- * as the sync version: reasoning.is_stale:false AND
- * (brain:null OR brain.staleness:'fresh' OR stale_reason:'brain_offline').
- */
-async function isQuadrupleFresh(quadruple) {
-  if (!quadruple || typeof quadruple !== 'object') return false;
-  const reasoning = quadruple.reasoning;
-  if (!reasoning || reasoning.is_stale !== false) return false;
-  const brain = quadruple.brain;
-  if (brain === null || brain === undefined) return true;
-  if (brain.staleness === 'fresh') return true;
-  if (brain.stale_reason === 'brain_offline') return true;
-  return false;
-}
-
-// ---------- Phase 94-01 getCurrentRoom async twin ----------
-//
-// Async pair of the sync getCurrentRoom. Same shape, same fallback
-// chain, same Tier 0 graceful null. Key-set parity required by the
-// Phase 88-01 sync/async parity test in lib/memory/folder-memory.test.cjs.
-//
-// MCP / Desktop / Cowork callers consume this when the handler loop is
-// async; CLI hook scripts (statusline, session-start, on-stop) consume
-// the sync entry point. Both return identical {slug, path, source} | null
-// shape so the canonical contract is surface-uniform.
-
-/**
- * Resolve canonical STATE.md path async. Mirror of the sync helper.
- * @param {string} workDir
- * @returns {Promise<string|null>}
- */
-async function resolveCanonicalStateMdAsync(workDir) {
-  let resolved;
-  try {
-    resolved = path.resolve(workDir);
-  } catch (_e) {
-    return null;
-  }
-
-  const registryPath = path.join(resolved, '.rooms', 'registry.json');
-  const regStat = await safeStatAsync(registryPath);
-  if (regStat && regStat.isFile()) {
-    const regBuf = await safeReadAsync(registryPath);
-    if (regBuf !== null) {
-      try {
-        const reg = JSON.parse(regBuf);
-        if (reg && reg.active && reg.rooms && reg.rooms[reg.active]) {
-          const roomDir = path.resolve(resolved, reg.rooms[reg.active].path);
-          const candidate = path.join(roomDir, 'STATE.md');
-          const st = await safeStatAsync(candidate);
-          if (st && st.isFile()) return candidate;
-        }
-      } catch (_e) { /* fall through */ }
-    }
-  }
-
-  const legacy = path.join(resolved, 'room', 'STATE.md');
-  const legacyStat = await safeStatAsync(legacy);
-  if (legacyStat && legacyStat.isFile()) return legacy;
-
-  const direct = path.join(resolved, 'STATE.md');
-  const directStat = await safeStatAsync(direct);
-  if (directStat && directStat.isFile()) return direct;
-
-  return null;
-}
-
-/**
- * Pure-CPU frontmatter sniff. Lifted byte-identical from the sync twin.
- * @param {string} buf
- * @returns {string|null}
- */
-function parseCurrentRoomFieldAsync(buf) {
-  if (typeof buf !== 'string' || buf.length === 0) return null;
-
-  if (buf.indexOf('---') !== 0) return null;
-  if (buf.length < 4) return null;
-  if (buf[3] !== '\n' && buf[3] !== '\r') return null;
-
-  const rest = buf.slice(buf.indexOf('\n') + 1);
-  const closeMatch = rest.match(/^---\s*$/m);
-  if (!closeMatch) return null;
-  const fmText = rest.slice(0, closeMatch.index);
-
-  const lines = fmText.split(/\r?\n/);
-  for (const raw of lines) {
-    if (raw.length === 0) continue;
-    if (/^\s*#/.test(raw)) continue;
-    const m = raw.match(/^current_room\s*:\s*(.+?)\s*$/);
-    if (!m) continue;
-    let value = m[1].trim();
-    if (value.length === 0) return null;
-    if (value === 'null' || value === '~') return null;
-
-    if (
-      (value[0] === '"' && value[value.length - 1] === '"') ||
-      (value[0] === "'" && value[value.length - 1] === "'")
-    ) {
-      if (value.length >= 2) value = value.slice(1, -1).trim();
-    }
-    if (value.length === 0) return null;
-    if (value.indexOf(':') !== -1) return null;
-
-    return value;
-  }
-  return null;
-}
-
-/**
- * Async getCurrentRoom. Mirror of sync twin. Returns Promise resolving
- * to {slug, path, source: 'state_md'} | null. Never rejects on missing
- * files or malformed YAML; the resolution chain plus null on every
- * failure mode matches sync semantics byte for byte.
- *
- * @param {string} [workDir]
- * @returns {Promise<{slug:string,path:string,source:'state_md'}|null>}
- */
-async function getCurrentRoom(workDir) {
-  const root = workDir || process.cwd();
-  const statePath = await resolveCanonicalStateMdAsync(root);
-  if (!statePath) return null;
-
-  const buf = await safeReadAsync(statePath);
-  if (buf === null) return null;
-
-  let slug;
-  try {
-    slug = parseCurrentRoomFieldAsync(buf);
-  } catch (_e) {
-    return null;
-  }
-  if (slug === null) return null;
-
-  return {
-    slug: slug,
-    path: statePath,
-    source: 'state_md',
-  };
-}
-
-module.exports = {
-  readTriple: readTriple,
-  readDecisionLog: readDecisionLog,
-  readQuadruple: readQuadruple,
-  isQuadrupleFresh: isQuadrupleFresh,
-  computeHealthScore: computeHealthScore,
-  getCurrentRoom: getCurrentRoom,
-};