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
8.2 KB
Raw Blame
import {
  planUpgrade,
  applyUpgrade,
  BrainUpgradeError,
  BrainUpgradeStoreOnlyError,
  upgradeBlockedByStore,
  type UpgradePlan,
} from "../../../core/brain/upgrade.ts";
import { basename } from "node:path";
import {
  brainVerbContext,
  describeErrorChain,
  fail,
  ok,
  okJson,
  parse,
  printUpgradePlanText,
  readSingleLine,
  renderUpgradePlanJson,
} from "../helpers.ts";
import { info } from "../../output.ts";
import { runSelfHealUpgrade } from "../../../core/maintenance/self-heal-upgrade.ts";
import {
  clearSelfHealUpgradeFailure,
  describeSelfHealUpgradeFailure,
  readSelfHealUpgradeFailure,
  recordSelfHealUpgradeFailure,
  type SelfHealUpgradeFailure,
} from "../../../core/maintenance/self-heal-upgrade-state.ts";

/** JSON shape of a recorded automatic-upgrade failure. */
function failureJson(failure: SelfHealUpgradeFailure): Record<string, unknown> {
  return {
    failed_at: failure.failedAt,
    error: failure.error,
    consecutive_failures: failure.consecutiveFailures,
    pending: failure.pending,
    retry_after: failure.retryAfter,
  };
}

/** Print the plan, plus the last automatic-upgrade failure when one is recorded. */
function printPlan(plan: UpgradePlan, failure: SelfHealUpgradeFailure | null, json: boolean): void {
  if (json) {
    okJson({
      ...renderUpgradePlanJson(plan),
      self_heal_failure: failure === null ? null : failureJson(failure),
    });
    return;
  }
  printUpgradePlanText(plan);
  if (failure !== null) {
    info(`last automatic upgrade: ${describeSelfHealUpgradeFailure(failure)}`);
  }
}

export async function cmdBrainUpgrade(argv: string[]): Promise<number> {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    "dry-run": { type: "boolean" },
    apply: { type: "boolean" },
    yes: { type: "boolean" },
    check: { type: "boolean" },
    json: { type: "boolean" },
    // The plan digest a --dry-run printed and an operator approved
    // (t_18fda844) - the upgrade twin of import-claude-memory's
    // --approval-digest. Verified against the freshly computed plan
    // before anything is written.
    "approval-digest": { type: "string" },
    // The detached worker `ensureVaultCurrent` starts, with the lock claim
    // it was handed. Not an operator flag: the worker's outcome is
    // recorded, never printed (its streams are ignored).
    "self-heal": { type: "string" },
  });
  const { vault } = brainVerbContext(flags);

  const selfHealToken = flags["self-heal"] as string | undefined;
  if (selfHealToken !== undefined) {
    runSelfHealUpgrade(vault, { lockToken: selfHealToken });
    return 0;
  }

  if (flags["dry-run"] && flags["apply"])
    return fail("brain upgrade: --dry-run and --apply are mutually exclusive");
  if (flags["check"] && flags["apply"])
    return fail("brain upgrade: --check and --apply are mutually exclusive");

  // A store-only machine has no managed files to upgrade: say so before
  // planning or prompting, and record no failure for it. Asked to apply,
  // that is a refusal (exit 1, `ok: false`); asked to look, it is the
  // answer (exit 0, `ok: true`), so the exit code and `ok` always agree.
  let blocked: boolean;
  try {
    blocked = upgradeBlockedByStore(vault);
  } catch (exc) {
    return fail(`upgrade check failed: ${(exc as Error).message ?? exc}`);
  }
  if (blocked) {
    const message = new BrainUpgradeStoreOnlyError().message;
    const refused = Boolean(flags["apply"]);
    if (flags["json"]) {
      okJson(
        refused
          ? { ok: false, store_only: true, error: message }
          : { ok: true, store_only: true, note: message },
      );
    } else process.stderr.write(`${message}\n`);
    return refused ? 1 : 0;
  }

  let plan: UpgradePlan;
  try {
    plan = planUpgrade(vault);
  } catch (exc) {
    return fail(`upgrade plan failed: ${(exc as Error).message ?? exc}`);
  }

  const failure = readSelfHealUpgradeFailure(vault);

  if (flags["check"]) {
    printPlan(plan, failure, Boolean(flags["json"]));
    return plan.pending > 0 || plan.errors > 0 ? 2 : 0;
  }

  if (!flags["apply"]) {
    printPlan(plan, failure, Boolean(flags["json"]));
    return 0;
  }

  if (plan.errors > 0)
    return fail(
      `upgrade aborted: ${plan.errors} file(s) failed to plan; run with --dry-run to inspect the error.`,
    );
  if (plan.pending === 0) {
    // Nothing left for the automatic upgrade to retry either.
    clearSelfHealUpgradeFailure(vault);
    if (flags["json"]) {
      okJson({ run_id: "", snapshot_path: "", files_updated: [] });
    } else {
      ok("upgrade: nothing to do; all managed files match the current release.");
    }
    return 0;
  }
  if (!flags["yes"]) {
    if (flags["json"] || !process.stdin.isTTY)
      return fail(
        "brain upgrade --apply requires --yes in non-interactive mode (--json or non-TTY stdin)",
      );
    process.stderr.write(
      `About to rewrite ${plan.pending} managed file(s):\n` +
        plan.files
          .filter((f) => f.status === "update")
          .map((f) => `  - ${f.path}\n`)
          .join("") +
        `A pre-apply snapshot will be taken (rollback via run id).\nProceed? [y/N] `,
    );
    const ans = await readSingleLine();
    if (ans.toLowerCase() !== "y" && ans.toLowerCase() !== "yes") {
      ok("upgrade cancelled");
      return 0;
    }
  }

  // t_18fda844: a script that applies must apply the plan it approved.
  // The digest comes from a prior `--dry-run` (the JSON plan output
  // carries it); an interactive operator keeps the human escape hatch,
  // exactly as with `--yes`. Verified against the plan this run just
  // computed BEFORE anything is written - a plan that moved since the
  // approved dry run is re-reviewed, never written over.
  const approvalDigest = flags["approval-digest"] as string | undefined;
  if (flags["json"] || !process.stdin.isTTY) {
    if (approvalDigest === undefined) {
      return fail(
        "brain upgrade --apply requires --approval-digest in non-interactive mode " +
          "(--json or non-TTY stdin); take it from the --dry-run plan output",
      );
    }
  }
  if (approvalDigest !== undefined && approvalDigest !== plan.digest) {
    return fail(
      `upgrade refused: approval digest mismatch: the plan changed since the approved ` +
        `dry run (approved ${approvalDigest}, current plan ${plan.digest}); nothing was ` +
        "written and no snapshot was taken. Re-run `o2b brain upgrade --dry-run` to review " +
        "the current plan, then apply with its digest.",
    );
  }

  let result;
  const now = new Date();
  try {
    // The plan computed (and, interactively, confirmed) above, not a
    // re-plan: a file that changed since it was read is refused by name
    // instead of overwritten.
    result = applyUpgrade(vault, { plan, now });
  } catch (exc) {
    // Recorded as the automatic path records it, so `o2b doctor` shows
    // the latest failure and the automatic retry waits its cooldown.
    try {
      recordSelfHealUpgradeFailure(
        vault,
        (exc as Error).message ?? String(exc),
        plan.files.filter((f) => f.status === "update").map((f) => f.path),
        now,
      );
    } catch {
      // The error below is what the operator acts on.
    }
    if (exc instanceof BrainUpgradeError) {
      if (flags["json"]) {
        // `drifted` names each refused file, so a script can tell a drift
        // from any other failure without parsing the message.
        okJson({ ok: false, error: exc.message, run_id: exc.runId, drifted: [...exc.drifted] });
      } else {
        process.stderr.write(`error: ${exc.message}\n`);
      }
      return 1;
    }
    return fail(`upgrade failed: ${describeErrorChain(exc)}`);
  }

  clearSelfHealUpgradeFailure(vault);
  if (flags["json"]) {
    okJson({
      run_id: result.run_id,
      snapshot_path: result.snapshot_path,
      files_updated: result.files_updated,
    });
  } else {
    ok(`run_id: ${result.run_id}`);
    // Vault-relative, not the resolved path: the snapshot location is
    // machine-derived, and the file name is already pinned by the run id
    // printed directly above. The JSON twin keeps `snapshot_path` for
    // consumers that need the resolved location.
    ok(`snapshot: Brain/.snapshots/${basename(result.snapshot_path)}`);
    for (const p of result.files_updated) ok(`  updated: ${p}`);
  }
  return 0;
}