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
8.1 KB
Raw Blame
/**
 * `o2b doctor selftest` - the functional self-test harness (t_c00cc548).
 *
 * The harness drives a real throwaway store end to end (open + migrate,
 * index pass, direct document roundtrip, keyword/trigram query, concurrent
 * writers through the writer lock, delete, orderly close) and must satisfy
 * two contracts the plan pins:
 *
 *   - the `--json` report is STABLE: no timestamps, no paths, no durations -
 *     two runs on one machine stringify byte-identically;
 *   - the operator's configured vault is never touched - the harness creates
 *     its own temp vault and config, and even a hostile environment pointing
 *     the search store and the semantic lane at the operator's files must
 *     not move a single write outside the throwaway directory.
 */

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

import {
  runDoctorSelftest,
  SELFTEST_STAGES,
  SELFTEST_STAGE_NAMES,
  type SelftestJsonPayload,
} from "../../src/core/doctor-selftest.ts";
import { SearchError } from "../../src/core/search/search-error.ts";
import { runCli, type RunResult } 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 sandbox: string;
let canaryVault: string;
let canaryConfig: string;

beforeEach(() => {
  sandbox = mkdtempSync(join(tmpdir(), "o2b-selftest-test-"));
  canaryVault = join(sandbox, "operator-vault");
  mkdirSync(join(canaryVault, "Brain"), { recursive: true });
  writeFileSync(join(canaryVault, "Brain", "canary.md"), "# canary\n\nuntouched\n");
  canaryConfig = join(sandbox, "operator-config.yaml");
  writeFileSync(canaryConfig, `vault: ${canaryVault}\n`);
});

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

/**
 * The environment the CLI runs under: everything points at the CANARY, so
 * if the harness touched the operator-side configuration at all, the writes
 * would land where the test can see them.
 */
function canaryEnv(): Record<string, string> {
  return {
    OPEN_SECOND_BRAIN_CONFIG: canaryConfig,
    VAULT_DIR: canaryVault,
    // Hostile overrides: the store location must NOT be honored (the
    // harness pins the db inside its own temp vault), and the semantic
    // lane must NOT be honored (the harness is network-free).
    OPEN_SECOND_BRAIN_SEARCH_DB: join(canaryVault, "hostile-store.sqlite"),
    OPEN_SECOND_BRAIN_SEARCH_SEMANTIC: "true",
  };
}

/** Recursive (path, size, mtime, content) snapshot of a directory tree. */
function snapshot(root: string): Map<string, string> {
  const out = new Map<string, string>();
  const walk = (dir: string): void => {
    for (const entry of readdirSync(dir, { withFileTypes: true })) {
      const path = join(dir, entry.name);
      if (entry.isDirectory()) {
        walk(path);
        continue;
      }
      const stat = statSync(path);
      out.set(path, `${stat.size}:${stat.mtimeMs}:${readFileSync(path, "utf8").length}`);
    }
  };
  walk(root);
  return out;
}

function parseSelftestJson(result: RunResult): SelftestJsonPayload {
  return JSON.parse(result.stdout) as SelftestJsonPayload;
}

test("every stage passes on a healthy machine and the JSON report is stable across runs", async () => {
  const before = snapshot(canaryVault);
  const first = await runCli(["doctor", "selftest", "--json"], { env: canaryEnv() });
  const second = await runCli(["doctor", "selftest", "--json"], { env: canaryEnv() });
  expect(first.returncode).toBe(0);
  expect(second.returncode).toBe(0);

  // Stability is byte-level: no timestamps, paths or durations anywhere.
  expect(first.stdout).toBe(second.stdout);
  expect(first.stdout).not.toContain("durationMs");
  expect(first.stdout).not.toContain("tempVault");
  expect(first.stdout).not.toContain(sandbox);
  expect(first.stdout).not.toContain(tmpdir());

  const report = parseSelftestJson(first);
  expect(report.verb).toBe("doctor-selftest");
  expect(report.harnessRan).toBe(true);
  expect(report.ok).toBe(true);
  expect(report.walMode === "wal" || report.walMode === "delete").toBe(true);
  expect(report.warnings).toBe(report.walMode === "delete" ? 1 : 0);
  expect(report.stages.map((s) => s.name)).toEqual([...SELFTEST_STAGE_NAMES]);
  for (const stage of report.stages) {
    expect(stage.ok, `${stage.name}: ${stage.message}`).toBe(true);
  }
  expect(report.summary).toEqual({ stages: SELFTEST_STAGE_NAMES.length, failed: 0 });

  const search = report.stages.find((s) => s.name === "search");
  expect(search?.metrics?.["queries"]).toBeGreaterThan(0);
  expect(search?.metrics?.["keywordHits"]).toBeGreaterThan(0);
  expect(search?.metrics?.["trigramHits"]).toBeGreaterThan(0);

  // The configured vault is untouched, and the hostile store override
  // never materialized a file.
  expect(snapshot(canaryVault)).toEqual(before);
  expect(existsSync(join(canaryVault, "hostile-store.sqlite"))).toBe(false);
});

test("human output lists every stage with timings and a summary line", async () => {
  const res = await runCli(["doctor", "selftest"], { env: canaryEnv() });
  expect(res.returncode).toBe(0);
  for (const name of SELFTEST_STAGE_NAMES) {
    expect(res.stdout).toContain(name);
  }
  // Timings live in the human surface only.
  expect(res.stdout).toMatch(/\(\d+ms\)/);
  expect(res.stdout).toContain("(removed)");
  expect(res.stdout).toContain(
    `doctor selftest: ok (${SELFTEST_STAGE_NAMES.length} stages, 0 warnings)`,
  );
});

test("a deliberately broken stage fails with name and fix, and the temp vault is cleaned up", async () => {
  const stages = SELFTEST_STAGES.map((spec) =>
    spec.name === "upsert"
      ? {
          ...spec,
          run: () => {
            throw new SearchError("INVALID_INPUT", "injected selftest fault");
          },
        }
      : spec,
  );
  const report = await runDoctorSelftest({ stages });
  expect(report.ok).toBe(false);
  expect(report.harnessRan).toBe(true);
  expect(report.tempRemoved).toBe(true);
  expect(report.tempRoot).not.toBeNull();
  expect(existsSync(report.tempRoot ?? "")).toBe(false);
  // The run stops at the first failure: the stages after the broken one
  // never ran.
  expect(report.stages.map((s) => s.name)).toEqual(["temp-vault", "store-open", "index", "upsert"]);
  const failed = report.stages.at(-1);
  expect(failed?.ok).toBe(false);
  expect(failed?.message).toContain("INVALID_INPUT");
  expect(failed?.message).toContain("injected selftest fault");
  expect(failed?.fix).toBe("o2b search check");
});

test("the harness could not run when temp storage is unavailable", async () => {
  // A FILE sitting where os.tmpdir() points makes every mkdtemp under it
  // fail with ENOTDIR (ENOENT on Windows), regardless of process
  // privileges. A real subprocess is required: os.tmpdir() is resolved from
  // the environment the process starts with, so an in-process env swap
  // cannot redirect it. The block must name every variable os.tmpdir()
  // consults on each platform - TMPDIR on POSIX, TEMP then TMP on Windows -
  // so the canary denies the child a usable temp root either way.
  const blocked = join(sandbox, "not-a-directory");
  writeFileSync(blocked, "in the way");
  const res = await runCli(["doctor", "selftest", "--json"], {
    env: { ...canaryEnv(), TMPDIR: blocked, TEMP: blocked, TMP: blocked },
    subprocess: true,
  });
  expect(res.returncode).toBe(6);
  const report = parseSelftestJson(res);
  expect(report.harnessRan).toBe(false);
  expect(report.ok).toBe(false);
  const first = report.stages[0];
  expect(first?.name).toBe("temp-vault");
  expect(first?.ok).toBe(false);
  expect(first?.fix).toBeTruthy();
});

test("the concurrent-write stage exercises the writer lock with two writers", async () => {
  const report = await runDoctorSelftest();
  expect(report.ok).toBe(true);
  const stage = report.stages.find((s) => s.name === "concurrent-write");
  expect(stage?.ok).toBe(true);
  expect(stage?.metrics?.["writers"]).toBe(2);
});