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
13.2 KB
Raw Blame
/**
 * `o2b store init` (`store-init.ts`): the only way a store is created.
 * It writes one store id into every requested partition, completes a
 * half-created store with the id it already has, and refuses an existing
 * store, a partial one, and partitions of two stores.
 */
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, spyOn, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  STORE_FORMAT_FILE,
  STORE_FORMAT_VERSION,
  STORE_IDENTITY_FILE,
  STORE_ROOT_ENV,
} from "../../../src/core/store/constants.ts";
import * as blobs from "../../../src/core/store/blobs.ts";
import { shippedFormatDoc } from "../../../src/core/store/format-doc.ts";
import { initStore, StoreInitRefusal } from "../../../src/core/store/store-init.ts";
import { inspectStore } from "../../../src/core/store/store-open.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 parent: string;
let root: string;

beforeEach(() => {
  parent = mkdtempSync(join(tmpdir(), "osb-store-init-"));
  root = join(parent, "store");
});
afterEach(() => rmSync(parent, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }));

function identity(partition: string): unknown {
  return JSON.parse(readFileSync(join(root, partition, STORE_IDENTITY_FILE), "utf8"));
}

function refusal(run: () => unknown): StoreInitRefusal {
  try {
    run();
  } catch (err) {
    if (err instanceof StoreInitRefusal) return err;
    throw err;
  }
  throw new Error("init did not refuse");
}

describe("store init", () => {
  test("creates both partitions with one store id and the format document everywhere", () => {
    const result = initStore({ root });
    expect(result.status).toBe("created");
    expect(result.partitions).toEqual(["shared", "private"]);
    for (const partition of ["shared", "private"]) {
      expect(identity(partition)).toEqual({
        store_id: result.storeId,
        format: STORE_FORMAT_VERSION,
      });
    }
    for (const dir of [root, join(root, "shared"), join(root, "private")]) {
      expect(readFileSync(join(dir, STORE_FORMAT_FILE), "utf8")).toBe(shippedFormatDoc());
    }
    expect(inspectStore(root)?.storeId).toBe(result.storeId);
  });

  test("a machine that must not hold private records creates shared only", () => {
    const result = initStore({ root, partitions: ["shared"] });
    expect(result.partitions).toEqual(["shared"]);
    expect(existsSync(join(root, "private"))).toBe(false);
  });

  test("refuses when the store already exists and leaves it as it was", () => {
    const first = initStore({ root });
    const before = readFileSync(join(root, "shared", STORE_IDENTITY_FILE), "utf8");
    const err = refusal(() => initStore({ root }));
    expect(err.reason).toBe("exists");
    expect(err.message).toContain(first.storeId);
    expect(readFileSync(join(root, "shared", STORE_IDENTITY_FILE), "utf8")).toBe(before);
  });

  test("a re-run completes a half-created store with the id it already has", () => {
    const first = initStore({ root });
    // The first run stopped after shared: private has its folder but no identity.
    rmSync(join(root, "private", STORE_IDENTITY_FILE));
    const second = initStore({ root });
    expect(second.status).toBe("completed");
    expect(second.storeId).toBe(first.storeId);
    expect(second.created).toEqual(["private"]);
    expect(identity("private")).toEqual({ store_id: first.storeId, format: STORE_FORMAT_VERSION });
  });

  test("a shared-only store gains private later with the same id", () => {
    const first = initStore({ root, partitions: ["shared"] });
    const second = initStore({ root });
    expect(second.storeId).toBe(first.storeId);
    expect(second.partitions).toEqual(["shared", "private"]);
  });

  test("a partition folder with records but no identity is refused by name, not given a new id", () => {
    initStore({ root, partitions: ["shared"] });
    mkdirSync(join(root, "private", "events"), { recursive: true });
    writeFileSync(join(root, "private", "events", "dev-a.jsonl"), "{}\n");
    const err = refusal(() => initStore({ root }));
    expect(err.reason).toBe("partial");
    expect(err.message).toContain(STORE_IDENTITY_FILE);
    expect(err.message).toContain("private");
    expect(existsSync(join(root, "private", STORE_IDENTITY_FILE))).toBe(false);
  });

  test("records synced without any identity file are refused, so no store id is minted", () => {
    mkdirSync(join(root, "shared", "events"), { recursive: true });
    writeFileSync(join(root, "shared", "events", "dev-a.jsonl"), "{}\n");
    expect(refusal(() => initStore({ root })).reason).toBe("partial");
    expect(inspectStore(root)).toBeNull();
  });

  test("sync tool markers and temp files do not make a folder partial", () => {
    mkdirSync(join(root, "shared", ".stfolder"), { recursive: true });
    writeFileSync(join(root, "shared", ".tmp-store.json.1"), "");
    expect(initStore({ root }).status).toBe("created");
  });

  test("partitions of two different stores are refused", () => {
    initStore({ root, partitions: ["shared"] });
    mkdirSync(join(root, "private"), { recursive: true });
    writeFileSync(
      join(root, "private", STORE_IDENTITY_FILE),
      `${JSON.stringify({ store_id: "01JBZ3NDEKTSV4RRFFQ69G5FAV", format: 1 })}\n`,
    );
    expect(refusal(() => initStore({ root })).reason).toBe("mixed");
  });

  test("an identity file that holds no store id is refused as corrupt", () => {
    mkdirSync(join(root, "shared"), { recursive: true });
    writeFileSync(join(root, "shared", STORE_IDENTITY_FILE), "{");
    expect(refusal(() => initStore({ root })).reason).toBe("corrupt");
  });

  test("an empty partition list is a caller error, not a refusal", () => {
    expect(() => initStore({ root, partitions: [] })).toThrow(TypeError);
  });
});

function env(): Record<string, string> {
  return { [STORE_ROOT_ENV]: root, HOME: join(parent, "home") };
}

describe("o2b store init", () => {
  test("creates the store, then refuses a second run with exit 1", async () => {
    const created = await runCli(["store", "init", "--json"], { env: env() });
    expect(created.returncode).toBe(0);
    const body = JSON.parse(created.stdout) as { ok: boolean; status: string; storeId: string };
    expect(body.ok).toBe(true);
    expect(body.status).toBe("created");
    expect(inspectStore(root)?.storeId).toBe(body.storeId);

    const again = await runCli(["store", "init"], { env: env() });
    expect(again.returncode).toBe(1);
    expect(again.stderr).toContain("already exists");
  });

  test("--partitions shared leaves private out", async () => {
    const r = await runCli(["store", "init", "--partitions", "shared"], { env: env() });
    expect(r.returncode).toBe(0);
    expect([...(inspectStore(root)?.partitions ?? [])]).toEqual(["shared"]);
  });

  test("six processes running the init verb at once agree on one store and only one reports creating it", async () => {
    // Six processes run the `store init` verb (its handler, not the whole
    // CLI entry; the single-run tests above cover the CLI) against one root. Each loads the verb,
    // says it is ready and waits for one go signal, so the six really do
    // race on the store, whatever the runner's load: a process start
    // (a transpile of the CLI on a cold Windows runner takes seconds) is
    // not part of the race and cannot stagger it into six serial runs or
    // eat the test's budget while one run is still starting.
    const runs = 6;
    const go = join(parent, "go");
    const child = join(parent, "racer.ts");
    const storeVerb = join(import.meta.dir, "../../../src/cli/store.ts");
    writeFileSync(
      child,
      [
        'import { existsSync, writeFileSync } from "node:fs";',
        `import { handleStoreSubcommand } from ${JSON.stringify(storeVerb)};`,
        "writeFileSync(process.argv[2], '');",
        // Bounded on its own, so a racer whose test already gave up exits
        // instead of spinning after the run.
        "const deadline = Date.now() + 30_000;",
        `while (!existsSync(${JSON.stringify(go)})) {`,
        "  if (Date.now() > deadline) process.exit(2);",
        "  Bun.sleepSync(5);",
        "}",
        'process.exitCode = await handleStoreSubcommand(["init", "--json"]);',
      ].join("\n"),
    );
    const spawnRacer = (i: number) => {
      const home = join(parent, "home");
      const proc = Bun.spawn([process.execPath, child, join(parent, `ready-${i}`)], {
        cwd: parent,
        env: {
          ...process.env,
          ...env(),
          ...(process.platform === "win32" ? { USERPROFILE: home } : {}),
          // A machine config of its own per run, as each CLI run gets.
          OPEN_SECOND_BRAIN_CONFIG: join(parent, `config-${i}.yaml`),
        },
        stdout: "pipe",
        stderr: "pipe",
      });
      const output = Promise.all([
        new Response(proc.stdout).text(),
        new Response(proc.stderr).text(),
        proc.exited,
      ]);
      return { proc, output };
    };
    const racers: Array<ReturnType<typeof spawnRacer>> = [];
    const readyUpTo = (count: number): boolean =>
      Array.from({ length: count }, (_, i) => join(parent, `ready-${i}`)).every((f) =>
        existsSync(f),
      );
    const waitReady = async (count: number): Promise<void> => {
      while (!readyUpTo(count)) {
        // A run that died before it got ready would leave the others waiting.
        for (const { proc } of racers) {
          if (proc.exitCode !== null) {
            throw new Error(`a racer exited ${proc.exitCode} before the start`);
          }
        }
        await Bun.sleep(10);
      }
    };
    let results: Array<[string, string, number]>;
    try {
      // The first racer starts alone and fills Bun's transpiler cache, so
      // the other five start warm instead of transpiling the verb's whole
      // module graph six times at once on a slow runner.
      racers.push(spawnRacer(0));
      await waitReady(1);
      for (let i = 1; i < runs; i++) racers.push(spawnRacer(i));
      await waitReady(runs);
      writeFileSync(go, "");
      results = await Promise.all(racers.map((r) => r.output));
    } finally {
      // Whatever happened above, no racer outlives the test.
      for (const { proc } of racers) if (proc.exitCode === null) proc.kill("SIGKILL");
    }
    const answers = results.map(([stdout, stderr]) => {
      try {
        return JSON.parse(stdout) as Record<string, unknown>;
      } catch {
        throw new Error(`a racer answered no JSON: ${stdout}${stderr}`);
      }
    });
    const done = answers.filter((a) => a["ok"] === true);
    // A run that lost is refused for the store the others made, never for another reason.
    const refused = answers.filter((a) => a["ok"] !== true).map((a) => a["reason"]);
    expect(refused.filter((reason) => reason !== "exists" && reason !== "partial")).toEqual([]);
    expect(done.length + refused.length).toBe(answers.length);
    expect(done.filter((a) => a["status"] === "created").length).toBe(1);
    const written = done.flatMap((a) => a["created"] as string[]);
    expect(written.toSorted()).toEqual(["private", "shared"]);
    expect(new Set(done.map((a) => a["storeId"]))).toEqual(new Set([inspectStore(root)?.storeId]));
  }, 30_000);

  test("with --json a usage error is a JSON answer too", async () => {
    const r = await runCli(["store", "init", "--partitions", "secret", "--json"], { env: env() });
    expect(r.returncode).toBe(2);
    expect(JSON.parse(r.stdout)).toMatchObject({ ok: false, reason: "usage" });
  });

  test("with --json a filesystem error on the store root is a JSON answer", async () => {
    // The root sits under a regular file, so no folder can be made there.
    writeFileSync(join(parent, "blocker"), "");
    root = join(parent, "blocker", "store");
    const r = await runCli(["store", "init", "--json"], { env: env() });
    expect(r.returncode).toBe(1);
    expect(JSON.parse(r.stdout)).toMatchObject({ ok: false, reason: "error" });
  });

  test("an unknown partition name is a usage error that creates nothing", async () => {
    const r = await runCli(["store", "init", "--partitions", "secret"], { env: env() });
    expect(r.returncode).toBe(2);
    expect(existsSync(root)).toBe(false);
  });
});

describe("an init that loses the race to one that stopped half way", () => {
  test("an identity file that never gets its id is refused as corrupt, with the way out", () => {
    // The winner created the name with an exclusive create (no hard links
    // on its filesystem) and stopped before writing the id into it.
    const lost = spyOn(blobs, "createFileOnce").mockImplementation((path: string) => {
      mkdirSync(join(path, ".."), { recursive: true });
      writeFileSync(path, "");
      return false;
    });
    try {
      const err = refusal(() => initStore({ root }));
      expect(err.reason).toBe("corrupt");
      expect(err.message).toContain(join(root, "shared", STORE_IDENTITY_FILE));
      expect(err.message).toContain("remove the file and run `o2b store init` again");
    } finally {
      lost.mockRestore();
    }
  });
});