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
14.5 KB
Raw Blame
/**
 * CLI tests for `o2b search *`.
 *
 * Each test forks the actual `bun src/cli/main.ts` binary via `runCli`,
 * the same harness `tests/cli/brain.test.ts` uses. We assert exit codes,
 * canonical text patterns, and the JSON shape produced by `--json`.
 */

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

import { runCli } from "../helpers/run-cli.ts";
import { LATEST_SCHEMA_VERSION } from "../../src/core/search/schema.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;

function writeVaultFile(rel: string, content: string): void {
  const abs = join(vault, rel);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, content);
}

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-search-cli-"));
  vault = join(tmp, "vault");
  mkdirSync(vault, { recursive: true });
  config = join(tmp, "config.yaml");
  writeFileSync(config, `vault: "${vault}"\n`);
});

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

test("search index creates the index file under <vault>/.open-second-brain/", async () => {
  writeVaultFile("a.md", "# A\n\nhello world");
  const out = await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  expect(existsSync(join(vault, ".open-second-brain", "brain.sqlite"))).toBe(true);
});

test("search status without an index reports 'not initialised' and exits 0", async () => {
  const out = await runCli(["search", "status"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  expect(out.stdout).toContain("not initialised");
});

test("search status --json after an index returns documents count", async () => {
  writeVaultFile("a.md", "# A\n\nbody");
  writeVaultFile("b.md", "# B\n\nbody");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  const out = await runCli(["search", "status", "--json"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  const obj = JSON.parse(out.stdout);
  expect(obj.exists).toBe(true);
  expect(obj.documents).toBe(2);
  expect(obj.schema_version).toBe(LATEST_SCHEMA_VERSION);
});

test("search query returns a human-readable hit for indexed content", async () => {
  writeVaultFile("notes/foo.md", "# Foo\n\nthe quick brown fox jumps over the lazy dog");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  const out = await runCli(["search", "fox"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  expect(out.stdout).toContain("notes/foo.md");
});

test("search query --json returns structured results", async () => {
  writeVaultFile("notes/foo.md", "# Foo\n\nfox content");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  const out = await runCli(["search", "fox", "--json", "--limit", "5"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  const obj = JSON.parse(out.stdout);
  expect(Array.isArray(obj.results)).toBe(true);
  expect(obj.results.length).toBeGreaterThan(0);
  expect(obj.results[0].path).toBe("notes/foo.md");
});

test("search query --query-doc accepts structured recall documents", async () => {
  writeVaultFile("notes/final.md", "# Final\n\nrelease notes mention recall diagnostics.");
  writeVaultFile("notes/draft.md", "# Draft\n\ndraft release notes mention recall diagnostics.");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });

  const out = await runCli(
    ["search", "--query-doc", 'lex: "release notes" -draft', "--json", "--limit", "10"],
    { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
  );

  expect(out.returncode).toBe(0);
  const obj = JSON.parse(out.stdout);
  expect(obj.results.map((r: { path: string }) => r.path)).toContain("notes/final.md");
  expect(obj.results.map((r: { path: string }) => r.path)).not.toContain("notes/draft.md");
  expect(obj.results[0].reasons.some((reason: string) => reason.includes("lane:lex/fts5"))).toBe(
    true,
  );
});

test("search query --evidence-pack returns missing terms and why_retrieved", async () => {
  writeVaultFile("notes/foo.md", "# Foo\n\nalpha beta current support.");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });

  const out = await runCli(
    ["search", "alpha gamma", "--query-doc", "lex: alpha", "--json", "--evidence-pack"],
    {
      env: { OPEN_SECOND_BRAIN_CONFIG: config },
    },
  );

  expect(out.returncode).toBe(0);
  const obj = JSON.parse(out.stdout);
  expect(obj.evidence_pack.missing_terms).toContain("gamma");
  expect(Array.isArray(obj.results[0].why_retrieved)).toBe(true);
});

test("search focus set/status/clear steers only the focused query window", async () => {
  writeVaultFile("archive/other.md", "# Other\n\nshared recall topic.");
  writeVaultFile("sessions/focus.md", "# Focus\n\nshared recall topic.");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });

  const set = await runCli(
    ["search", "focus", "set", "--path", "sessions/", "--ttl-minutes", "60", "--json"],
    { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
  );
  expect(set.returncode).toBe(0);
  expect(JSON.parse(set.stdout).active).toBe(true);

  const focused = await runCli(["search", "shared", "--json", "--limit", "2"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(focused.returncode).toBe(0);
  const focusedJson = JSON.parse(focused.stdout);
  expect(focusedJson.results[0].path).toBe("sessions/focus.md");
  expect(
    focusedJson.results[0].reasons.some((reason: string) => reason.startsWith("session_focus:")),
  ).toBe(true);

  const clear = await runCli(["search", "focus", "clear", "--json"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(clear.returncode).toBe(0);
  expect(JSON.parse(clear.stdout).active).toBe(false);
});

test("search query on a missing index self-heals (builds it) and exits 0", async () => {
  // A query used to fail with INDEX_MISSING; the read path now builds the index
  // on first use so an upgrade never needs a manual `o2b search index`.
  const out = await runCli(["search", "nothing-here"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  expect(existsSync(join(vault, ".open-second-brain", "brain.sqlite"))).toBe(true);
});

test("search check reports vault_readable and sqlite_ok on a fresh vault", async () => {
  const out = await runCli(["search", "check", "--json"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  const obj = JSON.parse(out.stdout);
  expect(obj.vault_readable).toBe(true);
  expect(obj.sqlite_ok).toBe(true);
  expect(obj.fts5_ok).toBe(true);
});

test("search reindex rebuilds the index atomically", async () => {
  writeVaultFile("a.md", "# A");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  writeVaultFile("b.md", "# B");
  const out = await runCli(["search", "reindex"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  expect(existsSync(join(vault, ".open-second-brain", "brain.sqlite"))).toBe(true);
  expect(existsSync(join(vault, ".open-second-brain", "brain.sqlite.bak"))).toBe(true);
});

test("unknown flag exits with code 2", async () => {
  const out = await runCli(["search", "index", "--bogus"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(2);
});

test("invalid numeric search flags exit with code 2 before touching the index", async () => {
  let out = await runCli(["search", "fox", "--keyword-weight", "nan"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(2);
  expect(out.stderr).toContain("search_keyword_weight");

  out = await runCli(["search", "index", "--concurrency", "0"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(2);
  expect(out.stderr).toContain("embedding_concurrency");
});

test("path-prefix escaping returns exit 2 with INVALID_INPUT", async () => {
  writeVaultFile("a.md", "# A");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  const out = await runCli(["search", "A", "--path", "../etc/"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(2);
  expect(out.stderr).toContain("INVALID_INPUT");
});

test("the default verb is `query` when first positional is unknown", async () => {
  writeVaultFile("a.md", "# A\n\nalpha word");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  // No explicit verb, just a query token:
  const out = await runCli(["search", "alpha"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  expect(out.stdout).toContain("a.md");
});

test("search --evidence-pack --json exposes verification fields (union, completeness)", async () => {
  writeVaultFile("alpha-note.md", "# Alpha\n\nthe alpha subsystem owns the export pipeline");
  writeVaultFile("zephyr-note.md", "# Zephyr\n\nthe zephyr daemon owns the import pipeline");
  await runCli(["search", "index"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } });

  // Two-pass recall would now recover results for this AND dead end;
  // disable it - this test exercises the zero-result union/completeness
  // verification fields themselves.
  const out = await runCli(["search", "alpha zephyr", "--evidence-pack", "--json"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config, OPEN_SECOND_BRAIN_SEARCH_TWO_PASS: "false" },
  });
  expect(out.returncode).toBe(0);
  const json = JSON.parse(out.stdout) as {
    evidence_pack: {
      idf_weighted_coverage: number;
      rare_terms: string[];
      uncovered_rare_terms: string[];
      union_records: Array<{ term: string; path: string }>;
      completeness: { verdict: string; uncovered_but_present_in_corpus: string[] };
    };
  };
  const pack = json.evidence_pack;
  expect(typeof pack.idf_weighted_coverage).toBe("number");
  expect(pack.union_records.map((r) => r.term).toSorted()).toEqual(["alpha", "zephyr"]);
  expect(pack.completeness.verdict).toBe("sparse");
  expect(pack.completeness.uncovered_but_present_in_corpus.toSorted()).toEqual(["alpha", "zephyr"]);
});

test("search query --json surfaces authored_at when present, omits it otherwise", async () => {
  writeVaultFile(
    "Brain/inbox/sig-dated.md",
    "---\nkind: brain-signal\nsource_type: session\nauthored_at: 2026-05-20T10:00:00Z\n---\n\n# Turn\n\nchronology alpha token discussed here.",
  );
  writeVaultFile(
    "Brain/inbox/sig-plain.md",
    "---\nkind: brain-signal\nsource_type: session\n---\n\n# Turn\n\nchronology alpha token discussed here.",
  );
  await runCli(["search", "index"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } });

  const out = await runCli(["search", "chronology alpha token", "--json", "--limit", "10"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  const obj = JSON.parse(out.stdout);
  const dated = obj.results.find((r: { path: string }) => r.path === "Brain/inbox/sig-dated.md");
  const plain = obj.results.find((r: { path: string }) => r.path === "Brain/inbox/sig-plain.md");
  expect(dated).toBeDefined();
  expect(plain).toBeDefined();
  expect(dated.authored_at).toBe(Math.floor(Date.parse("2026-05-20T10:00:00Z") / 1000));
  expect("authored_at" in plain).toBe(false);
});

test("search query --verbose prints an authored line only when present", async () => {
  writeVaultFile(
    "Brain/inbox/sig-dated.md",
    "---\nkind: brain-signal\nsource_type: session\nauthored_at: 2026-05-20T10:00:00Z\n---\n\n# Turn\n\nchronology alpha token discussed here.",
  );
  await runCli(["search", "index"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } });

  const out = await runCli(["search", "chronology alpha token", "--verbose"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(out.returncode).toBe(0);
  expect(out.stdout).toContain("authored 2026-05-20T10:00:00.000Z");
});

test("search query --json surfaces the summary-surface verdict for a source-targeted query, omits it otherwise", async () => {
  writeVaultFile("notes/foo.md", "# Foo\n\nfox content");
  await runCli(["search", "index"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });

  const summary = await runCli(["search", "source:notes/foo.md", "--json", "--limit", "5"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(summary.returncode).toBe(0);
  const summaryObj = JSON.parse(summary.stdout);
  expect(summaryObj.surface).toBe("summary");

  const plain = await runCli(["search", "fox", "--json", "--limit", "5"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(plain.returncode).toBe(0);
  const plainObj = JSON.parse(plain.stdout);
  expect("surface" in plainObj).toBe(false);
});

test("search status reports the persisted event-time windows in text and JSON", async () => {
  const day = 24 * 60 * 60 * 1000;
  const recent = new Date(Date.now() - 2 * day).toISOString().slice(0, 10);
  writeVaultFile(
    "old.md",
    "---\nvalid_from: 2026-01-01\nvalid_until: 2026-02-01\n---\n\n# Old\n\nbody",
  );
  writeVaultFile("recent.md", `---\nvalid_from: ${recent}\n---\n\n# Recent\n\nbody`);
  writeVaultFile("plain.md", "# Plain\n\nbody");
  await runCli(["search", "index"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } });

  const json = await runCli(["search", "status", "--json"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(json.returncode).toBe(0);
  const eventTime = JSON.parse(json.stdout).event_time;
  expect(eventTime.documents).toBe(3);
  expect(eventTime.with_event_time).toBe(2);
  expect(eventTime.earliest).toBe("2026-01-01T00:00:00.000Z");
  expect(eventTime.recent_window_days).toBe(30);
  expect(eventTime.in_recent_window).toBe(1);

  const text = await runCli(["search", "status"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } });
  expect(text.stdout).toMatch(
    /event_time: +2\/3 documents \(earliest 2026-01-01T00:00:00\.000Z, latest .+, 1 in the last 30 days\)/,
  );
});

test("search status without an index carries no event-time block", async () => {
  const out = await runCli(["search", "status", "--json"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: config },
  });
  expect(JSON.parse(out.stdout)).not.toHaveProperty("event_time");
});