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.8 KB
Raw Blame
/**
 * The brain store guide (`docs/brain-store.md`, task 2.13) runs as written.
 *
 * Every command block of the guide carries an HTML comment that names its
 * scenario, the machine that runs it and how its commands exit:
 *
 *     <!-- doc-test: scenario=setup machine=laptop exit=0 expect="text" -->
 *
 * A `config` block holds lines for that machine's config file instead.
 * This suite extracts the blocks, gives every machine of a scenario its own
 * sandbox (HOME, XDG and Windows profile dirs, config file, device id and
 * device-local state) and runs each command through the real CLI in a
 * child process, in document order, asserting the documented exit code
 * and, when given, the text the block's output contains.
 *
 * Machines share the store the way a sync tool shares it: before a block
 * runs, the partition folders of every machine of the scenario are synced
 * into each other (a file another device appended to is copied when it is
 * missing or shorter; shards are append-only and every device writes only
 * its own), keeping the store's modes. The device-local state is never synced. The server machine
 * receives only `shared/`, so the guide's server commands are checked on a
 * machine that never held `private/`. The migration scenario runs on a
 * fixture legacy vault that both machines name, as a vault synced between
 * them would be.
 *
 * Everything lives under one temp parent removed after each scenario.
 */
import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
  appendFileSync,
  chmodSync,
  copyFileSync,
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  rmSync,
  statSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, relative, resolve } from "node:path";

import { PARTNER_CODEGRAPH_DISABLED_ENV } from "../../src/core/config.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
import {
  makeLegacyVault,
  type LegacyVaultFixture,
} from "../core/store-migration/fixtures/legacy-vault.ts";

// A scenario is one test that runs a dozen CLI processes in a row.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS * 4);

const REPO_ROOT = resolve(import.meta.dir, "..", "..");
const GUIDE = join(REPO_ROOT, "docs", "brain-store.md");
const CLI_ENTRY = join(REPO_ROOT, "src", "cli", "main.ts");
const PARTITIONS = ["shared", "private"] as const;
type Partition = (typeof PARTITIONS)[number];

const MARKER = "<!-- doc-test:";

interface Block {
  readonly scenario: string;
  readonly machine: string;
  readonly config: boolean;
  /** Expected exit code of every command, or `null` for "any". */
  readonly exit: number | null;
  readonly expect: string | null;
  readonly lines: ReadonlyArray<string>;
  /** 1-based line of the marker in the guide, for failure messages. */
  readonly at: number;
}

/** Parse `key=value`, `key="quoted value"` and bare `key` attributes. */
function parseAttrs(text: string): Map<string, string> {
  const attrs = new Map<string, string>();
  for (const m of text.matchAll(/([a-z]+)(?:=(?:"([^"]*)"|(\S+)))?/g)) {
    attrs.set(m[1]!, m[2] ?? m[3] ?? "");
  }
  return attrs;
}

function extractBlocks(markdown: string): Block[] {
  const lines = markdown.split(/\r?\n/);
  const blocks: Block[] = [];
  for (let i = 0; i < lines.length; i += 1) {
    const line = lines[i]!.trim();
    if (!line.startsWith(MARKER)) continue;
    const attrs = parseAttrs(line.slice(MARKER.length, line.lastIndexOf("-->")));
    const fence = lines[i + 1] ?? "";
    const indent = fence.length - fence.trimStart().length;
    if (!fence.trimStart().startsWith("```")) {
      throw new Error(`doc-test marker at line ${i + 1} is not followed by a code fence`);
    }
    const body: string[] = [];
    let j = i + 2;
    while (j < lines.length && !lines[j]!.trim().startsWith("```")) {
      body.push(lines[j]!.slice(indent));
      j += 1;
    }
    if (j >= lines.length) {
      throw new Error(`doc-test marker at line ${i + 1} has an unclosed code fence`);
    }
    const scenario = attrs.get("scenario");
    const machine = attrs.get("machine");
    if (!scenario || !machine) {
      throw new Error(`doc-test marker at line ${i + 1} needs scenario= and machine=`);
    }
    const exit = attrs.get("exit");
    blocks.push({
      scenario,
      machine,
      config: attrs.has("config"),
      exit: exit === undefined || exit === "any" ? null : Number(exit),
      expect: attrs.get("expect") ?? null,
      lines: body.filter((l) => l.trim().length > 0),
      at: i + 1,
    });
    i = j;
  }
  return blocks;
}

/** Split a command line into words: bare words, "double" and 'single' quotes. */
function splitWords(line: string): string[] {
  const words: string[] = [];
  for (const m of line.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) {
    words.push(m[1] ?? m[2] ?? m[3]!);
  }
  return words;
}

interface Machine {
  readonly name: string;
  readonly home: string;
  readonly configPath: string;
  readonly partitions: ReadonlyArray<Partition>;
  env(): Record<string, string>;
  /** The configured store root, `null` before the config names one. */
  storeRoot(): string | null;
}

/** The sandbox env of one machine; nothing of the developer's brain leaks in. */
function machineEnv(home: string, configPath: string, device: string): Record<string, string> {
  const env: Record<string, string> = {};
  for (const [key, value] of Object.entries(process.env)) {
    if (value === undefined) continue;
    if (/^(OPEN_SECOND_BRAIN_|O2B_|VAULT_)/i.test(key)) continue;
    env[key] = value;
  }
  return {
    ...env,
    HOME: home,
    USERPROFILE: home,
    XDG_CONFIG_HOME: join(home, ".config"),
    XDG_STATE_HOME: join(home, ".local", "state"),
    XDG_DATA_HOME: join(home, ".local", "share"),
    LOCALAPPDATA: join(home, "AppData", "Local"),
    APPDATA: join(home, "AppData", "Roaming"),
    OPEN_SECOND_BRAIN_CONFIG: configPath,
    O2B_DEVICE_ID: device,
    [PARTNER_CODEGRAPH_DISABLED_ENV]: "true",
  };
}

function makeMachine(
  parent: string,
  name: string,
  device: string,
  partitions: ReadonlyArray<Partition>,
): Machine {
  const home = join(parent, name);
  const configPath = join(home, ".config", "open-second-brain", "config.yaml");
  mkdirSync(dirname(configPath), { recursive: true });
  // The user's (empty) Obsidian vault, for the guide's `--vault ~/vault`.
  mkdirSync(join(home, "vault"), { recursive: true });
  return {
    name,
    home,
    configPath,
    partitions,
    env: () => machineEnv(home, configPath, device),
    storeRoot() {
      const text = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
      const m = /^store_root:\s*"?([^"\n]+?)"?\s*$/m.exec(text);
      // A machine whose config names no store root is not set up yet.
      if (m === null) return null;
      const value = m[1]!;
      return value.startsWith("~/") ? join(home, value.slice(2)) : value;
    },
  };
}

function filesBelow(dir: string): string[] {
  if (!existsSync(dir)) return [];
  return readdirSync(dir).flatMap((name) => {
    const path = join(dir, name);
    return statSync(path).isDirectory() ? filesBelow(path) : [path];
  });
}

/** One direction of a file sync of one partition folder. */
function syncFolder(from: string, to: string): void {
  for (const src of filesBelow(from)) {
    const dst = join(to, relative(from, src));
    if (existsSync(dst) && statSync(dst).size >= statSync(src).size) continue;
    // A sync tool that keeps permissions (Syncthing does by default)
    // creates the store's folders and files with the modes they have.
    mkdirSync(dirname(dst), { recursive: true, mode: 0o700 });
    copyFileSync(src, dst);
    chmodSync(dst, 0o600);
  }
}

/** Sync every partition both machines hold, both ways, as a sync tool would. */
function syncInto(target: Machine, machines: ReadonlyArray<Machine>): void {
  for (const other of machines) {
    if (other === target) continue;
    for (const partition of PARTITIONS) {
      if (!target.partitions.includes(partition) || !other.partitions.includes(partition)) continue;
      const [targetRoot, otherRoot] = [target.storeRoot(), other.storeRoot()];
      if (targetRoot === null || otherRoot === null) continue;
      const mine = join(targetRoot, partition);
      const theirs = join(otherRoot, partition);
      syncFolder(theirs, mine);
      syncFolder(mine, theirs);
    }
  }
}

interface RunOutcome {
  readonly code: number;
  readonly output: string;
}

function runCommand(machine: Machine, line: string): RunOutcome {
  const words = splitWords(line).map((w) =>
    w.startsWith("~/") ? join(machine.home, w.slice(2)) : w,
  );
  expect(words[0]).toBe("o2b");
  const proc = Bun.spawnSync([process.execPath, "run", CLI_ENTRY, ...words.slice(1)], {
    cwd: machine.home,
    env: machine.env(),
    stdin: "ignore",
  });
  return {
    code: proc.exitCode ?? -1,
    output: `${proc.stdout.toString()}${proc.stderr.toString()}`,
  };
}

const blocks = extractBlocks(readFileSync(GUIDE, "utf8"));

let parent: string | null = null;
let legacy: LegacyVaultFixture | null = null;
afterEach(() => {
  if (parent !== null)
    rmSync(parent, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
  legacy?.cleanup();
  parent = null;
  legacy = null;
});

/** Run every block of `scenario` in document order on `machines`. */
function runScenario(scenario: string, machines: ReadonlyArray<Machine>): Map<string, string[]> {
  const outputs = new Map<string, string[]>();
  const scenarioBlocks = blocks.filter((b) => b.scenario === scenario);
  expect(scenarioBlocks.length).toBeGreaterThan(0);
  for (const block of scenarioBlocks) {
    const machine = machines.find((m) => m.name === block.machine);
    if (machine === undefined) throw new Error(`no machine ${block.machine} (line ${block.at})`);
    if (block.config) {
      appendFileSync(machine.configPath, `${block.lines.join("\n")}\n`);
      continue;
    }
    syncInto(machine, machines);
    let output = "";
    for (const line of block.lines) {
      const res = runCommand(machine, line);
      output += res.output;
      if (block.exit !== null && res.code !== block.exit) {
        throw new Error(
          `docs/brain-store.md line ${block.at}, ${machine.name}: \`${line}\` exited ` +
            `${res.code}, the guide says ${block.exit}\n${res.output}`,
        );
      }
    }
    if (block.expect !== null && !output.includes(block.expect)) {
      throw new Error(
        `docs/brain-store.md line ${block.at}, ${machine.name}: the output does not contain ` +
          `"${block.expect}"\n${output}`,
      );
    }
    outputs.set(machine.name, [...(outputs.get(machine.name) ?? []), output]);
  }
  return outputs;
}

/** The store root of a machine the scenario has set up. */
function rootOf(machine: Machine): string {
  const root = machine.storeRoot();
  if (root === null) throw new Error(`${machine.name} has no store_root in its config`);
  return root;
}

/** The store id a machine's copy of a partition carries. */
function storeIdOf(machine: Machine, partition: Partition): string {
  const path = join(rootOf(machine), partition, "store.json");
  return (JSON.parse(readFileSync(path, "utf8")) as { store_id: string }).store_id;
}

function newParent(): string {
  parent = mkdtempSync(join(tmpdir(), "osb-doc-brain-store-"));
  return parent;
}

describe("docs/brain-store.md", () => {
  test("every o2b command block of the guide is run by a scenario", () => {
    const markdown = readFileSync(GUIDE, "utf8").split(/\r?\n/);
    const unmarked: number[] = [];
    markdown.forEach((line, i) => {
      if (!/^\s*```(sh|yaml)\s*$/.test(line)) return;
      if (!markdown[i - 1]?.trim().startsWith(MARKER)) unmarked.push(i + 1);
    });
    expect(unmarked).toEqual([]);
    const scenarios = new Set(blocks.map((b) => b.scenario));
    expect([...scenarios].toSorted()).toEqual(["migration", "server-first", "setup", "vault"]);
  });

  // One run of the 19-command scenario (cold CLI processes) proves both
  // the shared store id and the server's private refusal.
  test("setup: one machine, a second machine and a shared-only server, run as written", () => {
    const root = newParent();
    const machines = [
      makeMachine(root, "laptop", "laptop", PARTITIONS),
      makeMachine(root, "desktop", "desktop", PARTITIONS),
      makeMachine(root, "server", "vps", ["shared"]),
    ];
    const outputs = runScenario("setup", machines);
    const [laptop, desktop, server] = machines;
    // One store: every machine holds the store id the first one created.
    expect(storeIdOf(desktop!, "shared")).toBe(storeIdOf(laptop!, "shared"));
    // A server that gets only shared/ never holds private/ and refuses
    // private writes.
    expect(existsSync(join(rootOf(server!), "shared", "store.json"))).toBe(true);
    expect(existsSync(join(rootOf(server!), "private"))).toBe(false);
    const serverOutput = (outputs.get("server") ?? []).join("");
    expect(serverOutput).toContain("private:");
    expect(serverOutput).toContain("brain doctor: clean");
    // The documented refusal is the one the guide quotes, word for word
    // up to the machine's own store path.
    const guide = readFileSync(GUIDE, "utf8");
    const quoted = /```text\n(error: the brain store write failed: [^\n]+)\n```/.exec(guide)?.[1];
    expect(quoted).toBeDefined();
    // Checked on the whole output first, so a missing refusal fails with
    // what the server printed instead of a TypeError.
    expect(serverOutput).toContain("error: the brain store");
    const actual =
      serverOutput.split("\n").find((l) => l.startsWith("error: the brain store")) ?? "";
    expect(actual.replace(rootOf(server!), "/home/me/brain-store")).toBe(quoted!);
  });

  test("vault: a fresh vault gets a store and no Brain/ tree", () => {
    const root = newParent();
    const laptop = makeMachine(root, "laptop", "laptop", PARTITIONS);
    appendFileSync(laptop.configPath, "store_root: ~/brain-store\n");
    runScenario("vault", [laptop]);
    expect(existsSync(join(rootOf(laptop), "shared", "store.json"))).toBe(true);
    expect(existsSync(join(laptop.home, "vault", "Brain"))).toBe(false);
  });

  test("server-first: the store is created with shared only, private added on a trusted machine", () => {
    const root = newParent();
    const machines = [
      makeMachine(root, "server", "vps", ["shared"]),
      makeMachine(root, "desktop", "desktop", PARTITIONS),
    ];
    // The setup scenario's config blocks name the store root; here the
    // test does, so the sync finds it on every platform.
    for (const m of machines) appendFileSync(m.configPath, "store_root: ~/brain-store\n");
    runScenario("server-first", machines);
    const [server, desktop] = machines;
    expect(existsSync(join(rootOf(server!), "private"))).toBe(false);
    expect(storeIdOf(desktop!, "private")).toBe(storeIdOf(server!, "shared"));
  });

  test("migration: first machine, later machine, transition, rollback and removal", () => {
    const root = newParent();
    legacy = makeLegacyVault("osb-doc-brain-store-vault-");
    // A clean legacy install: drop the fixture's entries no mapping covers.
    for (const rel of [
      "Brain/log/2026-11-01.sync-conflict-20261101-120000-ABC.jsonl",
      "Brain/log/stray.txt",
      "Brain/procedures/index.bin",
    ]) {
      rmSync(join(legacy.vault, ...rel.split("/")), { recursive: true });
    }
    // The fixture's cohort is dev-a, dev-b and dev-c; dev-c never upgrades.
    const machines = [
      makeMachine(root, "laptop", "dev-a", PARTITIONS),
      makeMachine(root, "desktop", "dev-b", PARTITIONS),
    ];
    for (const m of machines) {
      appendFileSync(
        m.configPath,
        `vault: "${legacy.vault}"\nstore_root: ~/brain-store\nview_target: ~/brain-view\n`,
      );
    }
    runScenario("migration", machines);
    expect(existsSync(join(legacy.vault, "Brain"))).toBe(false);
    expect(existsSync(join(legacy.vault, ".open-second-brain"))).toBe(false);
    expect(existsSync(join(machines[0]!.home, "brain-view", "about-me.md"))).toBe(true);
  });
});