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
12.5 KB
Raw Blame
/**
 * U7: `o2b brain snapshot log`.
 *
 * The snapshot family already had a diff and a revert (`snapshot diff`,
 * `rollback`); what it had no surface for was the LIST - so an operator
 * could not ask which recovery point covers a given boundary without
 * reading filenames out of `.snapshots/`. This file pins that surface:
 * newest-first ordering, the reason column, the reason filter, the usage
 * exit on an unregistered filter value, the limit, and the honest
 * zero-exit on a vault that has taken no snapshots at all.
 *
 * The snapshots are built through the core engine rather than by running
 * `brain dream` three times: the ordering assertions need controlled
 * mtimes and distinct reasons, and a dream run can only ever produce one
 * of the nine.
 */

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

import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { createSnapshot, SNAPSHOT_ENTRY_SKIP_REASON } from "../../src/core/brain/snapshot.ts";
import { manifestSidecarPath } from "../../src/core/brain/manifest.ts";
import { brainDirs, snapshotPath } from "../../src/core/brain/paths.ts";
import { BRAIN_SNAPSHOT_REASON } from "../../src/core/brain/types.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { CHMOD_CANNOT_DENY } from "../helpers/platform.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-cli-snaplog-"));
  vault = join(tmp, "vault");
  config = join(tmp, "config.yaml");
  atomicWriteFileSync(config, `vault: ${vault}\n`);
  bootstrapBrain(vault, { configPath: config });
  writeFileSync(
    join(brainDirs(vault).preferences, "pref-seed.md"),
    "---\nkind: brain-preference\n---\n\n## Principle\n\nseed\n",
  );
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
});

/** Run the verb with this test's sandboxed config. */
async function snapshotLog(...args: string[]): ReturnType<typeof runCli> {
  return await runCli(["brain", "snapshot", "log", "--vault", vault, ...args], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
}

/**
 * Three recovery points with distinct reasons and deliberately-ordered
 * mtimes, so "newest first" is a real assertion rather than an artefact of
 * creation order. The listing sorts by mtime because a hand-named run id
 * carries no timestamp to sort on.
 */
const SEEDED = Object.freeze([
  { runId: "dream-oldest", reason: BRAIN_SNAPSHOT_REASON.dream, minutes: 30 },
  { runId: "entity-prune-middle", reason: BRAIN_SNAPSHOT_REASON.entityPrune, minutes: 20 },
  { runId: "dream-newest", reason: BRAIN_SNAPSHOT_REASON.dream, minutes: 10 },
]);

function seedSnapshots(): void {
  const now = Date.now();
  for (const s of SEEDED) {
    createSnapshot(vault, s.runId, { reason: s.reason });
    const when = new Date(now - s.minutes * 60_000);
    utimesSync(snapshotPath(vault, s.runId), when, when);
  }
}

describe("brain snapshot log", () => {
  test("lists newest first with the reason of each recovery point", async () => {
    seedSnapshots();
    const r = await snapshotLog();
    expect(r.returncode).toBe(0);
    const rows = r.stdout.trimEnd().split("\n");
    // A header line, then one row per snapshot in mtime-descending order.
    expect(rows[0]).toContain("run_id");
    expect(rows[0]).toContain("reason");
    expect(rows.slice(1).map((line) => line.split("\t")[0])).toEqual([
      "dream-newest",
      "entity-prune-middle",
      "dream-oldest",
    ]);
    expect(rows[1]).toContain(BRAIN_SNAPSHOT_REASON.dream);
    expect(rows[2]).toContain(BRAIN_SNAPSHOT_REASON.entityPrune);
  });

  test("--json carries the reason, the manifest and the derived-store record", async () => {
    seedSnapshots();
    const r = await snapshotLog("--json");
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      total: number;
      snapshots: ReadonlyArray<{
        run_id: string;
        reason: string | null;
        manifest: boolean;
        derived_store: unknown;
        size_bytes: number;
        created_at: string;
      }>;
    };
    expect(payload.total).toBe(3);
    expect(payload.snapshots.map((s) => s.run_id)).toEqual([
      "dream-newest",
      "entity-prune-middle",
      "dream-oldest",
    ]);
    expect(payload.snapshots[0]!.reason).toBe(BRAIN_SNAPSHOT_REASON.dream);
    expect(payload.snapshots[0]!.manifest).toBe(true);
    expect(payload.snapshots[0]!.size_bytes).toBeGreaterThan(0);
    expect(payload.snapshots[0]!.derived_store).not.toBeNull();
  });

  test("--reason filters the revertible history by why it happened", async () => {
    seedSnapshots();
    const r = await snapshotLog("--reason", BRAIN_SNAPSHOT_REASON.dream, "--json");
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      total: number;
      snapshots: ReadonlyArray<{ run_id: string }>;
    };
    expect(payload.snapshots.map((s) => s.run_id)).toEqual(["dream-newest", "dream-oldest"]);
    expect(payload.total).toBe(2);
  });

  test("a reason that matches nothing exits zero with an empty listing", async () => {
    seedSnapshots();
    const r = await snapshotLog("--reason", BRAIN_SNAPSHOT_REASON.manual);
    // Nothing found is not a failure: the question was answerable and the
    // answer is none.
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("no snapshots");
  });

  test("an unregistered reason is a usage error, not an empty result", async () => {
    seedSnapshots();
    const r = await snapshotLog("--reason", "spring-cleaning");
    // Exit 2 and a named cause, matching how `brain event-trace` rejects a
    // bad --kind. Returning an empty listing would tell the operator their
    // vault has no such snapshots when in fact their filter was invalid.
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("spring-cleaning");
  });

  test("--limit honours a positive integer and rejects anything else", async () => {
    seedSnapshots();
    const limited = await snapshotLog("--limit", "2", "--json");
    expect(limited.returncode).toBe(0);
    const payload = JSON.parse(limited.stdout) as { snapshots: ReadonlyArray<{ run_id: string }> };
    expect(payload.snapshots.map((s) => s.run_id)).toEqual(["dream-newest", "entity-prune-middle"]);

    const zero = await snapshotLog("--limit", "0");
    expect(zero.returncode).toBe(2);
    const words = await snapshotLog("--limit", "many");
    expect(words.returncode).toBe(2);
  });

  test("an empty snapshots directory exits zero", async () => {
    const r = await snapshotLog();
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("no snapshots");
  });

  test("an empty snapshots directory exits zero under --json too", async () => {
    const r = await snapshotLog("--json");
    expect(r.returncode).toBe(0);
    // `skipped` is empty rather than absent: a consumer reading it to
    // decide whether the listing is complete must not have to tell an old
    // build's silence from this build's "nothing was skipped".
    expect(JSON.parse(r.stdout)).toEqual({ total: 0, snapshots: [], skipped: [] });
  });

  test("an archive nobody could describe is named on stderr and carried in --json", async () => {
    seedSnapshots();
    // A dangling symlink under the archive suffix: `readdir` names it,
    // `stat` refuses it. Dropped silently, this listing would print one
    // fewer row and claim to be the history.
    const dir = brainDirs(vault).snapshots;
    symlinkSync(join(dir, "nowhere.tar.zst"), join(dir, "dream-gone.tar.zst"));

    const text = await snapshotLog();
    expect(text.returncode).toBe(0);
    expect(text.stderr).toContain("INCOMPLETE");
    expect(text.stderr).toContain("dream-gone.tar.zst");

    const r = await snapshotLog("--json");
    const payload = JSON.parse(r.stdout) as {
      skipped: ReadonlyArray<{ name: string; reason: string }>;
    };
    expect(payload.skipped.map((s) => s.name)).toEqual(["dream-gone.tar.zst"]);
    expect(payload.skipped[0]!.reason).toBe(SNAPSHOT_ENTRY_SKIP_REASON.entryUnreadable);
  });

  // chmod 000 denies nothing to root or on Windows (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "a snapshots directory it cannot read is a failure, not an empty history",
    async () => {
      seedSnapshots();
      const snapshots = brainDirs(vault).snapshots;
      chmodSync(snapshots, 0o000);
      try {
        const r = await snapshotLog();
        // "no snapshots available" over a directory nobody could read is
        // the exact confusion this release exists to remove.
        expect(r.returncode).not.toBe(0);
        expect(r.stdout).not.toContain("no snapshots");
        expect(r.stderr).toContain(snapshots);
      } finally {
        chmodSync(snapshots, 0o755);
      }
    },
  );

  test("a snapshot with no sidecar reports an unknown reason, not its run-id prefix", async () => {
    createSnapshot(vault, "dream-unstamped", { reason: BRAIN_SNAPSHOT_REASON.dream });
    rmSync(manifestSidecarPath(vault, "dream-unstamped"), { force: true });
    const r = await snapshotLog("--json");
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      snapshots: ReadonlyArray<{ reason: string | null; manifest: boolean }>;
    };
    expect(payload.snapshots[0]!.reason).toBeNull();
    expect(payload.snapshots[0]!.manifest).toBe(false);
    const text = await snapshotLog();
    expect(text.stdout).toContain("unknown");
  });

  test("the subcommand is offered by the snapshot help", async () => {
    const r = await runCli(["brain", "snapshot", "--help", "--vault", vault], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("log");
    expect(r.stdout).toContain("diff");
  });
});

describe("brain rollback --list carries the reason", () => {
  test("the text listing gains a reason column", async () => {
    seedSnapshots();
    const r = await runCli(["brain", "rollback", "--list", "--vault", vault], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    const rows = r.stdout.trimEnd().split("\n");
    expect(rows[0]!.split("\t")).toEqual([
      "run_id",
      "created_at",
      "reason",
      "size_bytes",
      "derived_store",
    ]);
    // Column 2 (zero-based) is the reason, read off the sidecar.
    expect(rows[1]!.split("\t")[2]).toBe(BRAIN_SNAPSHOT_REASON.dream);
    expect(rows[2]!.split("\t")[2]).toBe(BRAIN_SNAPSHOT_REASON.entityPrune);
  });

  test("--list --json carries the reason on every entry", async () => {
    seedSnapshots();
    const r = await runCli(["brain", "rollback", "--list", "--vault", vault, "--json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    const snaps = JSON.parse(r.stdout) as ReadonlyArray<{ run_id: string; reason: string | null }>;
    expect(snaps.map((s) => s.reason)).toEqual([
      BRAIN_SNAPSHOT_REASON.dream,
      BRAIN_SNAPSHOT_REASON.entityPrune,
      BRAIN_SNAPSHOT_REASON.dream,
    ]);
  });

  // chmod 000 denies nothing to root or on Windows (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "an unreadable snapshots directory is reported, not listed as empty",
    async () => {
      seedSnapshots();
      const snapshots = brainDirs(vault).snapshots;
      chmodSync(snapshots, 0o000);
      try {
        const r = await runCli(["brain", "rollback", "--list", "--vault", vault], {
          env: { OPEN_SECOND_BRAIN_CONFIG: config },
        });
        expect(r.returncode).not.toBe(0);
        expect(r.stdout).not.toContain("no snapshots available");
        expect(r.stderr).toContain(snapshots);
      } finally {
        chmodSync(snapshots, 0o755);
      }
    },
  );

  test("an unstamped snapshot lists as unknown rather than as its prefix", async () => {
    createSnapshot(vault, "dream-unstamped", { reason: BRAIN_SNAPSHOT_REASON.dream });
    rmSync(manifestSidecarPath(vault, "dream-unstamped"), { force: true });
    const r = await runCli(["brain", "rollback", "--list", "--vault", vault], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout.trimEnd().split("\n")[1]!.split("\t")[2]).toBe("unknown");
  });
});