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
19.8 KB
Raw Blame
/**
 * CLI tests for `o2b brain export` (§28).
 */

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

import { EXPORT_FORMAT, EXPORT_FORMATS } from "../../src/core/brain/export.ts";
import { runCli } from "../helpers/run-cli.ts";
import { fakeCredential } from "../helpers/fake-credentials.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-export-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", "TestExport"], {
    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);
}

async function seedPreference(slug: string): Promise<void> {
  const r = await runCli(
    [
      "brain",
      "feedback",
      "--vault",
      vault,
      "--topic",
      slug,
      "--signal",
      "positive",
      "--principle",
      `principle ${slug}`,
      "--scope",
      "writing",
      "--force-confirmed",
      "--agent",
      "claude",
    ],
    { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
  );
  expect(r.returncode).toBe(0);
}

describe("brain export", () => {
  test("missing --format → exit 2", async () => {
    await bootstrap();
    const r = await runCli(["brain", "export", "--vault", vault], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("--format");
  });

  test("--format json on empty vault → schema envelope, empty list", async () => {
    await bootstrap();
    const r = await runCli(["brain", "export", "--vault", vault, "--format", "json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      schema: number;
      generated_at: string;
      vault_basename: string;
      preferences: ReadonlyArray<{ id: string }>;
    };
    expect(payload.schema).toBe(1);
    expect(payload.preferences).toEqual([]);
    expect(payload.vault_basename.length).toBeGreaterThan(0);
  });

  test("--format json carries seeded preference rows", async () => {
    await bootstrap();
    await seedPreference("alpha");
    await seedPreference("beta");
    const r = await runCli(["brain", "export", "--vault", vault, "--format", "json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      preferences: Array<{ id: string; topic: string; principle: string }>;
    };
    expect(payload.preferences.map((p) => p.id).toSorted()).toEqual(["pref-alpha", "pref-beta"]);
  });

  test("a preference that cannot be parsed refuses the export by name", async () => {
    // An export that omits a rule reads identically to a vault that never
    // had it, so a row that cannot be read stops the whole export rather
    // than shrinking the list under a success exit.
    await bootstrap();
    await seedPreference("alpha");
    writeFileSync(join(vault, "Brain", "preferences", "pref-broken.md"), "no frontmatter here\n");
    const r = await runCli(["brain", "export", "--vault", vault, "--format", "json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("pref-broken.md");
    expect(r.stdout).toBe("");
  });

  test("--format llms-txt emits H1 + section + bullet", async () => {
    await bootstrap();
    await seedPreference("alpha");
    const r = await runCli(["brain", "export", "--vault", vault, "--format", "llms-txt"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toMatch(/^# .*Brain preferences/);
    expect(r.stdout).toContain("## Confirmed");
    expect(r.stdout).toContain("- pref-alpha (topic: alpha, scope: writing): principle alpha");
  });

  test("--out writes a file (and refuses to overwrite without --force)", async () => {
    await bootstrap();
    await seedPreference("alpha");
    const out = join(tmp, "out.json");
    const r1 = await runCli(
      ["brain", "export", "--vault", vault, "--format", "json", "--out", out],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r1.returncode).toBe(0);
    expect(existsSync(out)).toBe(true);
    const parsed = JSON.parse(readFileSync(out, "utf8")) as {
      preferences: ReadonlyArray<unknown>;
    };
    expect(parsed.preferences.length).toBe(1);

    // Second call without --force should refuse.
    const r2 = await runCli(
      ["brain", "export", "--vault", vault, "--format", "json", "--out", out],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r2.returncode).toBe(1);
    expect(r2.stderr).toContain("--force");

    // With --force the overwrite goes through.
    writeFileSync(out, "stale");
    const r3 = await runCli(
      ["brain", "export", "--vault", vault, "--format", "json", "--out", out, "--force"],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r3.returncode).toBe(0);
    expect(readFileSync(out, "utf8")).not.toBe("stale");
  });

  test("help text mentions export", async () => {
    const r = await runCli(["brain", "--help"]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("export");
  });

  test("an unknown --format names every format the vocabulary declares", async () => {
    await bootstrap();
    const r = await runCli(["brain", "export", "--vault", vault, "--format", "yaml"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(2);
    // Whole tokens, not substrings: `"transcripts-jsonl".includes("json")`
    // is true, so plain containment reported `json` as offered by a
    // message that had stopped naming it.
    const offered = new Set(r.stderr.split(/[^A-Za-z0-9_-]+/).filter((t) => t.length > 0));
    for (const format of EXPORT_FORMATS) {
      expect(`${format} offered: ${offered.has(format)}`).toBe(`${format} offered: true`);
    }
  });
});

describe("brain export privacy omissions", () => {
  /**
   * Hand-add an informal privacy marker the same way an operator does:
   * a user-tier frontmatter line on the preference file.
   */
  function stampMarker(slug: string, line: string): void {
    const abs = join(vault, "Brain", "preferences", `pref-${slug}.md`);
    writeFileSync(abs, readFileSync(abs, "utf8").replace(/^---\n/, `---\n${line}\n`));
  }

  test("a reserved preference is omitted from the json envelope and named on stderr", async () => {
    await bootstrap();
    await seedPreference("alpha");
    await seedPreference("reserved");
    stampMarker("reserved", "access: private");

    const r = await runCli(["brain", "export", "--vault", vault, "--format", "json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      preferences: ReadonlyArray<{ id: string }>;
      omitted?: ReadonlyArray<{ id: string; reason: string; denied_by: string }>;
    };
    expect(payload.preferences.map((p) => p.id)).toEqual(["pref-alpha"]);
    expect(payload.omitted).toEqual([
      { id: "pref-reserved", reason: "visibility", denied_by: "access" },
    ]);
    // The omission is DISCLOSED, not silent: the notice names the rule and
    // the reservation key that denied it.
    expect(r.stderr).toContain("pref-reserved");
    expect(r.stderr).toContain("(access)");
    expect(r.stderr).toContain("left out");
    // stderr only - the json bytes name the omission as data, not prose.
    expect(r.stdout).not.toContain("left out");
  });

  test("llms-txt leaves the reserved row out of the sections and names it on stderr", async () => {
    await bootstrap();
    await seedPreference("alpha");
    await seedPreference("reserved");
    stampMarker("reserved", "sensitivity: confidential");

    const r = await runCli(["brain", "export", "--vault", vault, "--format", "llms-txt"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("- pref-alpha (topic: alpha, scope: writing): principle alpha");
    expect(r.stdout).not.toContain("pref-reserved");
    expect(r.stderr).toContain("pref-reserved");
    expect(r.stderr).toContain("(sensitivity)");
    expect(r.stderr).toContain("left out");
  });

  test("a vault with no reservation emits no notice and no omitted key", async () => {
    await bootstrap();
    await seedPreference("alpha");

    const r = await runCli(["brain", "export", "--vault", vault, "--format", "json"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as { omitted?: unknown };
    expect("omitted" in payload).toBe(false);
    expect(r.stderr).not.toContain("left out");
  });
});

describe("brain export --format transcripts-jsonl", () => {
  interface TranscriptFixture {
    /** Turn id of the first line - the `turn_id` a record carries. */
    readonly uuid?: string;
    /** Basename of the transcript, which becomes the record's `session_id`. */
    readonly file?: string;
    /** Text of the user turn, for the cases that put something in it. */
    readonly text?: string;
  }

  /** A two-turn Claude Code transcript under a fresh directory. */
  function transcriptDir(opts: TranscriptFixture = {}): string {
    const uuid = opts.uuid ?? "u-1";
    const file = opts.file ?? "session.jsonl";
    const dir = join(tmp, `transcripts-${uuid}-${file}`);
    mkdirSync(dir, { recursive: true });
    const lines = [
      {
        parentUuid: null,
        sessionId: "sess-1",
        entrypoint: "cli",
        type: "user",
        uuid,
        timestamp: "2026-08-01T10:00:00.000Z",
        message: { role: "user", content: opts.text ?? "what does this verb do" },
      },
      {
        parentUuid: uuid,
        sessionId: "sess-1",
        entrypoint: "cli",
        type: "assistant",
        uuid: "a-1",
        timestamp: "2026-08-01T10:00:01.000Z",
        message: { role: "assistant", content: "it exports the corpus" },
      },
    ];
    writeFileSync(join(dir, file), lines.map((l) => JSON.stringify(l)).join("\n") + "\n", "utf8");
    return dir;
  }

  test("emits one JSONL conversation record per transcript, with no vault involved", async () => {
    // The corpus is on the machine, not in the vault, so this format asks
    // for no vault - a format that never reads one must not refuse for the
    // want of one.
    const dir = transcriptDir();
    const r = await runCli(
      ["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl, "--transcripts", dir],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(0);
    const lines = r.stdout.trimEnd().split("\n");
    expect(lines.length).toBe(1);
    const record = JSON.parse(lines[0]!) as {
      runtime: string;
      session_id: string;
      messages: ReadonlyArray<{ role: string; text: string }>;
    };
    expect(record.runtime).toBe("claude");
    expect(record.session_id).toBe("session.jsonl");
    expect(record.messages.map((m) => m.role)).toEqual(["user", "assistant"]);
  });

  test("without --transcripts the format refuses and names the flag", async () => {
    const r = await runCli(["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl], {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    });
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("--transcripts");
  });

  test("a record with a secret-shaped identifier is refused and nothing is written", async () => {
    // Transcripts are the highest-risk corpus in the vault's orbit: a key
    // pasted into a prompt is recorded verbatim, and an identifier cannot
    // be redacted without renaming what it identifies. So the export stops.
    const dir = transcriptDir({ uuid: "sk-live-9f2ba7c1d4e8" });
    const out = join(tmp, "corpus.jsonl");
    const r = await runCli(
      [
        "brain",
        "export",
        "--format",
        EXPORT_FORMAT.transcriptsJsonl,
        "--transcripts",
        dir,
        "--out",
        out,
      ],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("refused to write");
    expect(r.stderr).toContain("turn_id");
    expect(existsSync(out)).toBe(false);
    expect(r.stdout).toBe("");
  });

  test("an empty result says how much it looked at rather than writing nothing", async () => {
    const dir = transcriptDir();
    const r = await runCli(
      [
        "brain",
        "export",
        "--format",
        EXPORT_FORMAT.transcriptsJsonl,
        "--transcripts",
        dir,
        "--since",
        "2027-01-01T00:00:00Z",
      ],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(0);
    expect(r.stdout).toBe("");
    expect(r.stderr).toContain("1 transcript");
  });

  test("a secret-shaped FILENAME is refused without the refusal printing it", async () => {
    // The one path whose entire purpose is not letting this value out was
    // the path that wrote it to stderr - into CI logs and shell
    // scrollback - because the refusal prefixed the guard's sentence with
    // the record's `session_id`, which IS the transcript's basename. The
    // guard's own message is careful about exactly this: "(Locations, not
    // values: the identifier is the secret.)"
    const secret = fakeCredential("sk-", "live-9f2ba7c1d4e8.jsonl");
    const dir = transcriptDir({ file: secret });
    const out = join(tmp, "corpus.jsonl");
    const r = await runCli(
      [
        "brain",
        "export",
        "--format",
        EXPORT_FORMAT.transcriptsJsonl,
        "--transcripts",
        dir,
        "--out",
        out,
      ],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("refused to write");
    expect(r.stderr).toContain("session_id");
    // Neither the whole filename nor the credential inside it.
    expect(r.stderr).not.toContain(secret);
    expect(r.stderr).not.toContain("sk-live-9f2ba7c1d4e8");
    // Still locatable: the runtime and the instant it started are not
    // identifiers and are safe to name.
    expect(r.stderr).toContain("claude");
    expect(r.stderr).toContain("2026-08-01T10:00:00.000Z");
    expect(existsSync(out)).toBe(false);
    expect(r.stdout).toBe("");
  });

  test("the refusal still names the transcript when the name is not the secret", async () => {
    // The complement: withholding the name unconditionally would make
    // every ordinary refusal harder to act on for no gain.
    const dir = transcriptDir({ uuid: "sk-live-9f2ba7c1d4e8", file: "ordinary.jsonl" });
    const r = await runCli(
      ["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl, "--transcripts", dir],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("ordinary.jsonl");
  });

  test("a BARE high-entropy filename is refused, not exported under exit 0", async () => {
    // Vendor-prefixed refused the whole run; an unprefixed 24-character
    // mixed run in the same position exported verbatim. `session_id` is a
    // foreign harness's filename, so "ids are long mixed runs by
    // construction" - an argument about ids this vault generates - does
    // not carry over to it.
    const dir = transcriptDir({ file: "Xk7Qp2Rm9Wz4Tn6Yb8Vc3Ld5.jsonl" });
    const out = join(tmp, "corpus.jsonl");
    const r = await runCli(
      [
        "brain",
        "export",
        "--format",
        EXPORT_FORMAT.transcriptsJsonl,
        "--transcripts",
        dir,
        "--out",
        out,
      ],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("session_id");
    expect(r.stderr).not.toContain("Xk7Qp2Rm9Wz4Tn6Yb8Vc3Ld5");
    expect(existsSync(out)).toBe(false);
  });

  test("the transcript branch REDACTS a key pasted into a turn, and says so", async () => {
    // Every existing test on this branch pinned a REFUSAL. Nothing asserted
    // that the released corpus is redacted at all, and nothing covered the
    // notice that tells the operator the copy no longer matches the source.
    // The payload is the shape a key actually takes in a transcript:
    // a prefixed environment assignment, which the key-name pass could not
    // see at all until the `\b` at the front of it was replaced.
    const dir = transcriptDir({ text: "run `export ANTHROPIC_API_KEY=hunter2secretvalue` first" });
    const r = await runCli(
      ["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl, "--transcripts", dir],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(0);
    expect(r.stdout).not.toContain("hunter2secretvalue");
    expect(r.stdout).toContain("***REDACTED***");
    // The variable name survives, so the line still says what was removed.
    expect(r.stdout).toContain("ANTHROPIC_API_KEY");
    expect(r.stderr).toContain("no longer matches the vault byte for byte");
  });

  test("an existing --out is refused before the corpus is read", async () => {
    // The check used to sit after the handler, so `--out` naming a file
    // that already exists read, hashed and redacted a whole machine's
    // transcripts and then refused over a flag knowable from argv alone.
    // A source that does not exist is what makes the ordering visible:
    // whichever check runs first is the one that speaks.
    const out = join(tmp, "corpus.jsonl");
    writeFileSync(out, "existing bytes\n", "utf8");
    const r = await runCli(
      [
        "brain",
        "export",
        "--format",
        EXPORT_FORMAT.transcriptsJsonl,
        "--transcripts",
        join(tmp, "no-such-transcripts"),
        "--out",
        out,
      ],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("--force");
    expect(r.stderr).not.toContain("no-such-transcripts");
    expect(readFileSync(out, "utf8")).toBe("existing bytes\n");
  });

  test("a zero-byte transcript does not abort the run", async () => {
    const dir = transcriptDir();
    writeFileSync(join(dir, "flushed-nothing.jsonl"), "", "utf8");
    const r = await runCli(
      ["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl, "--transcripts", dir],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(0);
    expect(r.stdout.trimEnd().split("\n").length).toBe(1);
  });

  test("--out receives the corpus and stdout stays empty", async () => {
    const dir = transcriptDir();
    const out = join(tmp, "corpus.jsonl");
    const r = await runCli(
      [
        "brain",
        "export",
        "--format",
        EXPORT_FORMAT.transcriptsJsonl,
        "--transcripts",
        dir,
        "--out",
        out,
      ],
      { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
    );
    expect(r.returncode).toBe(0);
    const written = readFileSync(out, "utf8");
    expect(written.trimEnd().split("\n").length).toBe(1);
    expect(JSON.parse(written.trimEnd()) as { session_id: string }).toMatchObject({
      session_id: "session.jsonl",
    });
    // The spool is consumed by the rename, never left beside the target.
    expect(readdirSync(tmp).filter((n) => n.includes("o2b-transcripts-"))).toEqual([]);
  });
});