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
15.2 KB
Raw Blame
/**
 * CLI tests for `o2b brain upgrade`.
 *
 * Forks the real `o2b` binary via `runCli`. Each test mutates a
 * freshly-bootstrapped vault to create a known drift (stale manual or
 * truncated `_brain.yaml`), then asserts the verb's exit code,
 * stdout shape, and (for `--apply`) post-state on disk.
 */

import { afterEach, beforeEach, describe, expect, setDefaultTimeout, spyOn, test } from "bun:test";
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { cmdBrainUpgrade } from "../../src/cli/brain/verbs/upgrade.ts";
import * as upgradeModule from "../../src/core/brain/upgrade.ts";
import type { UpgradePlan } from "../../src/core/brain/upgrade.ts";
import { runCli } from "../helpers/run-cli.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

let tmp: string;
let vault: string;
let config: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-upgrade-cli-"));
  vault = join(tmp, "vault");
  config = join(tmp, "config.yaml");
});
afterEach(() => rmSync(tmp, { recursive: true, force: true }));

async function bootstrap(): Promise<void> {
  const init = await runCli(["init", "--vault", vault, "--name", "Test"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(init.returncode).toBe(0);
  const brainInit = await runCli(["brain", "init", "--vault", vault], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(brainInit.returncode).toBe(0);
}

describe("brain upgrade", () => {
  test("clean vault → dry-run reports up-to-date, exit 0", async () => {
    await bootstrap();
    const r = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("up to date");
  });

  test("--check on clean vault → exit 0", async () => {
    await bootstrap();
    const r = await runCli(["brain", "upgrade", "--vault", vault, "--check"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
  });

  test("--check with pending updates → exit 2", async () => {
    await bootstrap();
    // Drift: stale operator copy of _BRAIN.md.
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n");
    const r = await runCli(["brain", "upgrade", "--vault", vault, "--check"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(2);
    expect(r.stdout).toContain("Brain/_BRAIN.md");
  });

  test("--dry-run with pending updates → exit 0, shows the diff", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n");
    const r = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("update");
    expect(r.stdout).toContain("--- Brain/_BRAIN.md (live)");
    expect(r.stdout).toContain("+++ Brain/_BRAIN.md (release)");
  });

  test("--apply --yes rewrites pending files and creates upgrade-<ts> snapshot", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n");
    // Non-interactive apply carries the approval digest (t_18fda844):
    // the plan is deterministic for the drifted state, so the digest
    // here is what a prior --dry-run would have printed.
    const digest = upgradeModule.planUpgrade(vault).digest;
    const r = await runCli(
      ["brain", "upgrade", "--vault", vault, "--apply", "--yes", "--approval-digest", digest],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(0);
    expect(r.stdout).toMatch(/run_id: upgrade-/);
    expect(r.stdout).toContain("Brain/_BRAIN.md");
    // The snapshot line names the artifact vault-relative: the absolute
    // location is machine-derived (state the vault never supplied), and
    // the run id printed directly above already pins the file name.
    const runId = /run_id: (upgrade-\S+)/.exec(r.stdout)![1]!;
    expect(r.stdout).toContain(`snapshot: Brain/.snapshots/${runId}.tar.zst`);
    expect(r.stdout).not.toContain(tmp);
    // Post-apply: the file is now the canonical template body, not
    // the stale copy.
    const body = readFileSync(join(vault, "Brain", "_BRAIN.md"), "utf8");
    expect(body).not.toBe("stale\n");
    // A snapshot named upgrade-<ts> landed under .snapshots/.
    const snapEntries = require("node:fs").readdirSync(join(vault, "Brain", ".snapshots"));
    expect(snapEntries.some((n: string) => n.startsWith("upgrade-"))).toBe(true);
  });

  test("--apply in --json mode requires --yes (non-interactive guard)", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n");
    const r = await runCli(["brain", "upgrade", "--vault", vault, "--apply", "--json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("--yes");
  });

  test("--apply in non-interactive mode without --approval-digest refuses before writing", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n");
    // `brain init` pre-creates the snapshots directory; the refusal must
    // not add an archive to it.
    const snapsBefore = existsSync(join(vault, "Brain", ".snapshots"))
      ? require("node:fs").readdirSync(join(vault, "Brain", ".snapshots")).length
      : 0;
    const r = await runCli(["brain", "upgrade", "--vault", vault, "--apply", "--yes"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("--approval-digest");
    // Nothing was written and no snapshot was taken.
    expect(readFileSync(join(vault, "Brain", "_BRAIN.md"), "utf8")).toBe("stale\n");
    const snapsAfter = existsSync(join(vault, "Brain", ".snapshots"))
      ? require("node:fs").readdirSync(join(vault, "Brain", ".snapshots")).length
      : 0;
    expect(snapsAfter).toBe(snapsBefore);
  });

  test("--apply with the matching dry-run digest lands; a stale digest refuses", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n");
    const dry = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run", "--json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    const digest = (JSON.parse(dry.stdout) as { digest: string }).digest;
    const ok = await runCli(
      ["brain", "upgrade", "--vault", vault, "--apply", "--yes", "--approval-digest", digest],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(ok.returncode).toBe(0);
    expect(readFileSync(join(vault, "Brain", "_BRAIN.md"), "utf8")).not.toBe("stale\n");

    // A second drift, a fresh approval, then the file moves again before
    // the apply: the approved plan no longer describes the vault, and the
    // refusal says so before anything is written.
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale again\n");
    const secondDry = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run", "--json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    const approved = (JSON.parse(secondDry.stdout) as { digest: string }).digest;
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "moved after approval\n");
    const stale = await runCli(
      ["brain", "upgrade", "--vault", vault, "--apply", "--yes", "--approval-digest", approved],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(stale.returncode).toBe(1);
    expect(stale.stderr).toContain("approval digest mismatch");
    expect(stale.stderr).toContain("nothing was written");
    expect(readFileSync(join(vault, "Brain", "_BRAIN.md"), "utf8")).toBe("moved after approval\n");
  });

  test("--apply on clean vault → no snapshot, no log, exit 0", async () => {
    await bootstrap();
    const snapsBefore = existsSync(join(vault, "Brain", ".snapshots"))
      ? require("node:fs").readdirSync(join(vault, "Brain", ".snapshots")).length
      : 0;
    const r = await runCli(["brain", "upgrade", "--vault", vault, "--apply", "--yes"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("nothing to do");
    const snapsAfter = existsSync(join(vault, "Brain", ".snapshots"))
      ? require("node:fs").readdirSync(join(vault, "Brain", ".snapshots")).length
      : 0;
    expect(snapsAfter).toBe(snapsBefore);
  });

  test("malformed _brain.yaml reports error in plan and refuses --apply", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Brain", "_brain.yaml"), "not: a valid: brain yaml\n");
    const dry = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(dry.returncode).toBe(0);
    expect(dry.stdout).toMatch(/ERROR/);

    const apply = await runCli(["brain", "upgrade", "--vault", vault, "--apply", "--yes"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(apply.returncode).toBe(1);
    expect(apply.stderr).toContain("upgrade aborted");
  });

  test("--dry-run and --apply are mutually exclusive", async () => {
    await bootstrap();
    const r = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run", "--apply"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("mutually exclusive");
  });

  test("--json --dry-run emits structured plan", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n");
    const r = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run", "--json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      pending: number;
      errors: number;
      files: Array<{ path: string; status: string }>;
    };
    expect(payload.pending).toBeGreaterThanOrEqual(1);
    expect(payload.files.some((f) => f.path === "Brain/_BRAIN.md" && f.status === "update")).toBe(
      true,
    );
  });

  test("--json --dry-run carries the plan digest (t_18fda844)", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n");
    const first = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run", "--json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(first.returncode).toBe(0);
    const payload = JSON.parse(first.stdout) as { digest: string };
    expect(payload.digest).toMatch(/^[0-9a-f]{64}$/);
    // The seal binds the plan, not the moment it was rendered.
    const second = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run", "--json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect((JSON.parse(second.stdout) as { digest: string }).digest).toBe(payload.digest);
  });

  test("a missing _BRAIN.md renders as an update from absent (text and JSON)", async () => {
    await bootstrap();
    rmSync(join(vault, "Brain", "_BRAIN.md"), { force: true });
    const text = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(text.returncode).toBe(0);
    expect(text.stdout).toContain("Brain/_BRAIN.md: update (absent →");
    expect(text.stdout).toContain("+++ Brain/_BRAIN.md (release)");

    const json = await runCli(["brain", "upgrade", "--vault", vault, "--dry-run", "--json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(json.returncode).toBe(0);
    const payload = JSON.parse(json.stdout) as {
      files: Array<{ path: string; status: string; before_size: number; after_size: number }>;
    };
    const manual = payload.files.find((f) => f.path === "Brain/_BRAIN.md")!;
    expect(manual.status).toBe("update");
    expect(manual.before_size).toBe(0);
    expect(manual.after_size).toBeGreaterThan(0);
  });
});

describe("brain upgrade --apply applies the plan it printed", () => {
  let prevConfigEnv: string | undefined;
  beforeEach(() => {
    prevConfigEnv = process.env["OPEN_SECOND_BRAIN_CONFIG"];
    process.env["OPEN_SECOND_BRAIN_CONFIG"] = config;
  });
  afterEach(() => {
    if (prevConfigEnv === undefined) delete process.env["OPEN_SECOND_BRAIN_CONFIG"];
    else process.env["OPEN_SECOND_BRAIN_CONFIG"] = prevConfigEnv;
  });

  test("--apply --yes hands the shown plan to applyUpgrade, planning once", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n");
    const realPlan = upgradeModule.planUpgrade;
    // The approval digest of the plan the CLI is about to compute itself:
    // same drifted state, same deterministic seal.
    const digest = realPlan(vault).digest;
    const shown: UpgradePlan[] = [];
    const planSpy = spyOn(upgradeModule, "planUpgrade").mockImplementation((v) => {
      const plan = realPlan(v);
      shown.push(plan);
      return plan;
    });
    const applySpy = spyOn(upgradeModule, "applyUpgrade");
    const out = spyOn(process.stdout, "write").mockImplementation(() => true);
    try {
      const code = await cmdBrainUpgrade([
        "--vault",
        vault,
        "--apply",
        "--yes",
        "--approval-digest",
        digest,
        "--json",
      ]);
      out.mockRestore();
      expect(code).toBe(0);
      expect(shown).toHaveLength(1);
      expect(applySpy).toHaveBeenCalledTimes(1);
      expect(applySpy.mock.calls[0]![1]?.plan).toBe(shown[0]);
    } finally {
      out.mockRestore();
      planSpy.mockRestore();
      applySpy.mockRestore();
    }
    expect(readFileSync(join(vault, "Brain", "_BRAIN.md"), "utf8")).not.toBe("stale\n");
  });

  test("--apply --json reports a drift refusal as JSON with run_id and drifted", async () => {
    await bootstrap();
    const manual = join(vault, "Brain", "_BRAIN.md");
    writeFileSync(manual, "stale\n");
    const realPlan = upgradeModule.planUpgrade;
    // The digest of the plan the mocked planning is about to return (the
    // file is still "stale\n" at that moment; the hand edit lands after).
    const digest = realPlan(vault).digest;
    // The hand edit lands between the plan and the apply.
    const planSpy = spyOn(upgradeModule, "planUpgrade").mockImplementation((v) => {
      const plan = realPlan(v);
      writeFileSync(manual, "hand edit\n");
      return plan;
    });
    const written: string[] = [];
    const out = spyOn(process.stdout, "write").mockImplementation((chunk) => {
      written.push(String(chunk));
      return true;
    });
    let code: number;
    try {
      code = await cmdBrainUpgrade([
        "--vault",
        vault,
        "--apply",
        "--yes",
        "--approval-digest",
        digest,
        "--json",
      ]);
    } finally {
      out.mockRestore();
      planSpy.mockRestore();
    }
    expect(code).toBe(1);
    const payload = JSON.parse(written.join("")) as Record<string, unknown>;
    expect(payload["ok"]).toBe(false);
    expect(payload["error"]).toContain("Brain/_BRAIN.md");
    expect(payload["run_id"]).toBeNull();
    expect(payload["drifted"]).toEqual(["Brain/_BRAIN.md"]);
    expect(readFileSync(manual, "utf8")).toBe("hand edit\n");
  });
});