Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
6.5 KB
Raw Blame
/**
 * `o2b brain tiers <check|restore|accept>` (t_3f92d3f1): the staged
 * repair surface for identity-tier frontmatter hand-edits the index
 * post-pass detected. `check` lists open findings (read-only),
 * `restore <path> --apply` writes the expected value back into the
 * file, `accept <path>` adopts the hand-edit as the new truth -
 * nothing auto-resolves, the operator stays the judge.
 *
 * Exit codes: 0 on success, 1 on an operational failure, 2 on usage
 * errors.
 */

import { join } from "node:path";
import { existsSync } from "node:fs";

import { resolveSearchConfig } from "../../../core/search/index.ts";
import { Store } from "../../../core/search/store.ts";
import { parseFrontmatter, writeFrontmatterAtomic } from "../../../core/vault.ts";
import type { FrontmatterMap } from "../../../core/types.ts";
import { emitNextSteps } from "../../advisory-rail.ts";
import { brainVerbContext, fail, ok, okJson, parse } from "../helpers.ts";

const USAGE =
  "usage: o2b brain tiers check | " +
  "o2b brain tiers restore <path> [--field F] [--apply] | " +
  "o2b brain tiers accept <path> [--field F]  [--vault <path>] [--json]";

export async function cmdBrainTiers(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    field: { type: "string" },
    apply: { type: "boolean" },
    json: { type: "boolean" },
  });
  const op = positional[0];
  const asJson = flags["json"] === true;
  if (op !== "check" && op !== "restore" && op !== "accept") {
    process.stderr.write(`${USAGE}\n`);
    return 2;
  }
  const relPath = positional[1];
  if ((op === "restore" || op === "accept") && !relPath) {
    process.stderr.write(`brain tiers ${op}: a vault-relative path is required\n${USAGE}\n`);
    return 2;
  }

  const { config, vault } = brainVerbContext(flags);
  const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
  const field = (flags["field"] as string | undefined)?.trim();

  try {
    if (op === "check") {
      // Fail-soft: a vault that was never indexed has no snapshots
      // and therefore no drift - not an error.
      if (!existsSync(searchConfig.dbPath)) {
        if (asJson) okJson({ findings: [] });
        else ok("tier drift: 0 open finding(s)");
        return 0;
      }
      const store = await Store.open(searchConfig, { mode: "read" });
      try {
        const findings = store.listTierDrift();
        if (asJson) {
          // Deliberately carries no next command. `nextCommandField` is
          // singular by construction - one wire key, one string - and
          // this state has TWO exits, restore and accept. Emitting one
          // would tell a machine caller that the other does not exist,
          // which is worse than the human stream's two rail lines.
          okJson({ findings });
        } else {
          ok(`tier drift: ${findings.length} open finding(s)`);
          for (const f of findings) {
            ok(
              `  ${f.path}  ${f.field}: expected ${render(f.expected)}, actual ${render(f.actual)}`,
            );
          }
          if (findings.length > 0) {
            // no-dead-ends, phase 3. One finding, two readings: the
            // indexed value is authoritative (restore) or the note's is
            // (accept). The rail's batch form prints one line per
            // distinct command, so both exits survive the migration -
            // collapsing them into a single code would have dropped the
            // half the operator did not happen to want.
            emitNextSteps(["tier-drift-restore", "tier-drift-accept"], {
              command: "brain",
              argv,
              jsonRequested: asJson,
            });
          }
        }
        return 0;
      } finally {
        await store.close();
      }
    }

    const store = await Store.open(searchConfig, { mode: "write" });
    try {
      const docId = store.getDocumentIdByPath(relPath!);
      if (docId === null) return fail(`tiers ${op}: not indexed: ${relPath}`);
      const rows = store
        .listTierDrift()
        .filter((r) => r.documentId === docId && (field === undefined || r.field === field));
      if (rows.length === 0) {
        return fail(`tiers ${op}: no open drift for ${relPath}${field ? ` field ${field}` : ""}`);
      }

      if (op === "restore") {
        if (flags["apply"] !== true) {
          if (asJson) okJson({ would_restore: rows, applied: false });
          else {
            for (const r of rows) {
              ok(
                `would restore ${r.path} ${r.field}: ${render(r.actual)} -> ${render(r.expected)}`,
              );
            }
            ok("re-run with --apply to write");
          }
          return 0;
        }
        const path = join(vault, relPath!);
        const [metadata, body] = parseFrontmatter(path);
        const next: FrontmatterMap = { ...metadata };
        for (const r of rows) {
          next[r.field] = asFrontmatterValue(r.expected, r.field);
        }
        writeFrontmatterAtomic(path, next, body, { overwrite: true });
        for (const r of rows) store.clearTierDrift(docId, r.field);
        if (asJson) okJson({ restored: rows.map((r) => r.field), path: relPath });
        else ok(`restored ${rows.length} field(s) in ${relPath}`);
        return 0;
      }

      // accept: the hand-edit becomes the new snapshot truth.
      const snapshot: Record<string, unknown> = { ...store.getTierSnapshot(docId) };
      for (const r of rows) {
        snapshot[r.field] = r.actual;
        store.clearTierDrift(docId, r.field);
      }
      store.setTierSnapshot(docId, snapshot);
      if (asJson) okJson({ accepted: rows.map((r) => r.field), path: relPath });
      else ok(`accepted ${rows.length} field(s) as the new baseline in ${relPath}`);
      return 0;
    } finally {
      await store.close();
    }
  } catch (exc) {
    const message = `tiers ${op} failed: ${(exc as Error).message ?? exc}`;
    if (asJson) {
      okJson({ ok: false, message });
      return 1;
    }
    return fail(message);
  }
}

function render(value: unknown): string {
  return JSON.stringify(value);
}

/** Narrow a snapshot value to the shapes frontmatter can carry. */
function asFrontmatterValue(value: unknown, field: string): FrontmatterMap[string] {
  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
    return value;
  }
  if (Array.isArray(value) && value.every((v): v is string => typeof v === "string")) {
    return value;
  }
  throw new Error(`snapshot value for "${field}" is not a frontmatter scalar or string array`);
}