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
21.5 KB
Raw Blame
/**
 * Tests for the §14 explorer data collector. We exercise:
 *   - empty Brain → empty graph
 *   - mixed preferences (unconfirmed, confirmed, quarantine) plus
 *     retired entries appear as nodes with the expected status
 *   - supersedes edges from `superseded_by`
 *   - inline wikilink edges from body / frontmatter dedup
 *   - signal / log refs are filtered out of the edge list
 *   - byte-identical JSON across two runs on the same vault
 *   - legacy `confidence_value: null` surfaces as `null` (not zero)
 *   - `backlink_count` matches the index in `backlinks.ts`
 *
 * The render side (template + JSON inlining) gets its own task.
 */

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

import { buildBacklinkIndex, backlinkCount } from "../../../src/core/brain/backlinks.ts";
import {
  buildLiveServer,
  collectExplorerData,
  EXPLORER_SCHEMA_VERSION,
  renderExportedHtml,
} from "../../../src/core/brain/explorer.ts";
import {
  moveToRetired,
  writePreference,
  type WritePreferenceInput,
} from "../../../src/core/brain/preference.ts";
import { emitRecallTelemetry } from "../../../src/core/brain/recall-telemetry.ts";
import {
  BRAIN_CONFIDENCE,
  BRAIN_PREFERENCE_STATUS,
  BRAIN_RETIRED_REASON,
} from "../../../src/core/brain/types.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-explorer-"));
  mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
  mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
  mkdirSync(join(vault, "Brain", "log"), { recursive: true });
  mkdirSync(join(vault, "Brain", "inbox"), { recursive: true });
});
afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

function basePref(
  slug: string,
  overrides: Partial<WritePreferenceInput> = {},
): WritePreferenceInput {
  return {
    slug,
    topic: slug,
    principle: `Principle for ${slug}`,
    created_at: "2026-05-01T00:00:00Z",
    unconfirmed_until: "2026-05-08T00:00:00Z",
    status: BRAIN_PREFERENCE_STATUS.confirmed,
    evidenced_by: [`[[sig-2026-05-01-${slug}]]`],
    confirmed_at: "2026-05-02T00:00:00Z",
    applied_count: 0,
    violated_count: 0,
    last_evidence_at: null,
    confidence: BRAIN_CONFIDENCE.low,
    confidence_value: 0,
    pinned: false,
    ...overrides,
  };
}

describe("collectExplorerData", () => {
  test("empty Brain → 0 nodes, 0 edges, schema_version 1", () => {
    const g = collectExplorerData(vault);
    expect(g.nodes).toEqual([]);
    expect(g.edges).toEqual([]);
    expect(g.schema_version).toBe(1);
    expect(EXPLORER_SCHEMA_VERSION).toBe(1);
    expect(typeof g.generated_at).toBe("string");
  });

  test("nodes include confirmed, unconfirmed, quarantine, retired", () => {
    writePreference(
      vault,
      basePref("conf", {
        status: BRAIN_PREFERENCE_STATUS.confirmed,
        applied_count: 5,
        confidence: BRAIN_CONFIDENCE.high,
      }),
    );
    writePreference(
      vault,
      basePref("trial", {
        status: BRAIN_PREFERENCE_STATUS.unconfirmed,
        confirmed_at: null,
      }),
    );
    writePreference(
      vault,
      basePref("quar", {
        status: BRAIN_PREFERENCE_STATUS.quarantine,
        applied_count: 2,
        violated_count: 3,
      }),
    );
    // Create a fourth pref and retire it.
    writePreference(vault, basePref("dead"));
    const deadPath = join(vault, "Brain", "preferences", "pref-dead.md");
    moveToRetired(vault, deadPath, BRAIN_RETIRED_REASON.staleNoEvidence, {
      now: new Date("2026-05-10T00:00:00Z"),
      retired_by: "[[Brain/log/2026-05-10]]",
    });

    const g = collectExplorerData(vault);
    const ids = g.nodes.map((n) => n.id).toSorted();
    expect(ids).toEqual(["pref-conf", "pref-quar", "pref-trial", "ret-dead"]);
    const byId = new Map(g.nodes.map((n) => [n.id, n]));
    expect(byId.get("pref-conf")!.status).toBe("confirmed");
    expect(byId.get("pref-trial")!.status).toBe("unconfirmed");
    expect(byId.get("pref-quar")!.status).toBe("quarantine");
    expect(byId.get("ret-dead")!.status).toBe("retired");
    expect(byId.get("ret-dead")!.kind).toBe("retired");
    expect(byId.get("pref-conf")!.kind).toBe("preference");
  });

  test("supersedes edge: from a pref pointing at a retired", () => {
    // First, write a base pref and retire it.
    writePreference(vault, basePref("old", { topic: "shared" }));
    moveToRetired(
      vault,
      join(vault, "Brain", "preferences", "pref-old.md"),
      BRAIN_RETIRED_REASON.rebutted,
      {
        now: new Date("2026-05-05T00:00:00Z"),
        retired_by: "[[Brain/log/2026-05-05]]",
      },
    );
    // Then write a successor that names the retired pref via `supersedes`.
    writePreference(
      vault,
      basePref("new", {
        topic: "shared",
        supersedes: "[[ret-old]]",
        status: BRAIN_PREFERENCE_STATUS.unconfirmed,
        confirmed_at: null,
      }),
    );
    const g = collectExplorerData(vault);
    const supersedesEdges = g.edges.filter((e) => e.kind === "supersedes");
    expect(supersedesEdges.length).toBeGreaterThanOrEqual(1);
    const e = supersedesEdges.find((x) => x.source === "pref-new" && x.target === "ret-old");
    expect(e).toBeDefined();
  });

  test("wikilink edges between preferences land as kind 'wikilink'; signal refs excluded", () => {
    writePreference(vault, basePref("a"));
    // Cross-pref wikilink via `evidenced_by` — `principle` is a
    // frontmatter field, not body content, so wikilinks inside it
    // do not feed the backlink index. Real cross-pref refs in this
    // project flow through `evidenced_by`, `supersedes`, or body
    // sections.
    writePreference(
      vault,
      basePref("b", {
        evidenced_by: ["[[pref-a]]", "[[sig-foo]]"],
      }),
    );
    const g = collectExplorerData(vault);
    const wlEdges = g.edges.filter((e) => e.kind === "wikilink");
    const bToA = wlEdges.find((e) => e.source === "pref-b" && e.target === "pref-a");
    expect(bToA).toBeDefined();
    // No edge to the signal — sig-foo is not in the node set.
    expect(g.edges.find((e) => e.target === "sig-foo")).toBeUndefined();
    // No edge to a non-existent target.
    expect(g.edges.find((e) => e.target === "pref-nope")).toBeUndefined();
  });

  test("typed semantics metadata projects onto explorer nodes and edges", () => {
    writePreference(vault, basePref("base"));
    writePreference(
      vault,
      basePref("semantic", {
        memory_layer: "L2",
        memory_branch: "research",
        depends_on: ["[[pref-base]]"],
      }),
    );

    const g = collectExplorerData(vault);
    const node = g.nodes.find((n) => n.id === "pref-semantic");
    expect(node).toBeDefined();
    expect(node!.memory_layer).toBe("L2");
    expect(node!.memory_branch).toBe("research");

    const edge = g.edges.find((e) => e.source === "pref-semantic" && e.target === "pref-base");
    expect(edge).toBeDefined();
    expect(edge!.kind).toBe("wikilink");
    expect(edge!.relation).toBe("depends_on");
  });

  test("output is byte-identical across two runs (modulo generated_at)", () => {
    writePreference(vault, basePref("alpha", { applied_count: 2 }));
    writePreference(vault, basePref("beta"));
    const g1 = collectExplorerData(vault);
    const g2 = collectExplorerData(vault);
    // Strip the timestamp before comparing.
    const stripped = (g: { generated_at: string }): string =>
      JSON.stringify({ ...g, generated_at: "" });
    expect(stripped(g1)).toBe(stripped(g2));
  });

  test("legacy null confidence_value surfaces as null, not zero", () => {
    // `writePreference` with `confidence_value: null` writes the
    // legacy on-disk shape that pre-v0.10.3 dream passes left behind.
    writePreference(
      vault,
      basePref("legacy", {
        applied_count: 1,
        last_evidence_at: null,
        confidence: BRAIN_CONFIDENCE.low,
        confidence_value: null,
      }),
    );
    const g = collectExplorerData(vault);
    const node = g.nodes.find((n) => n.id === "pref-legacy");
    expect(node).toBeDefined();
    expect(node!.confidence_value).toBeNull();
  });

  test("backlink_count matches buildBacklinkIndex output", () => {
    writePreference(vault, basePref("target"));
    // Two sources, both reaching target via `evidenced_by` (the
    // canonical inter-pref reference field).
    writePreference(vault, basePref("source1", { evidenced_by: ["[[pref-target]]"] }));
    writePreference(vault, basePref("source2", { evidenced_by: ["[[pref-target]]"] }));
    const g = collectExplorerData(vault);
    const node = g.nodes.find((n) => n.id === "pref-target");
    const expected = backlinkCount(buildBacklinkIndex(vault), "pref-target");
    expect(node!.backlink_count).toBe(expected);
    expect(node!.backlink_count).toBeGreaterThanOrEqual(2);
  });

  test("vault_basename equals the last path segment", () => {
    const g = collectExplorerData(vault);
    expect(g.vault_basename).toBe(basename(vault));
  });

  test("stable ordering: nodes by (kind, id); edges by (source, target, kind)", () => {
    writePreference(vault, basePref("b-pref"));
    writePreference(vault, basePref("a-pref"));
    writePreference(vault, basePref("c-pref"));
    moveToRetired(
      vault,
      join(vault, "Brain", "preferences", "pref-c-pref.md"),
      BRAIN_RETIRED_REASON.rebutted,
      {
        now: new Date("2026-05-10T00:00:00Z"),
        retired_by: "[[Brain/log/2026-05-10]]",
      },
    );
    const g = collectExplorerData(vault);
    // Preferences come first (kind 'preference' < 'retired' lexically),
    // then retired. Within each kind, ids ascend.
    const kinds = g.nodes.map((n) => n.kind);
    expect(kinds).toEqual(["preference", "preference", "retired"]);
    const prefIds = g.nodes.filter((n) => n.kind === "preference").map((n) => n.id);
    expect(prefIds).toEqual([...prefIds].toSorted());
  });
});

describe("renderExportedHtml", () => {
  test("substitutes the placeholder exactly once with parseable JSON", () => {
    writePreference(vault, basePref("foo"));
    const g = collectExplorerData(vault);
    const html = renderExportedHtml(g);
    expect(html.includes("__GRAPH_JSON__")).toBe(false);
    const match = html.match(
      /<script type="application\/json" id="brain-data">([\s\S]+?)<\/script>/,
    );
    expect(match).not.toBeNull();
    const parsed = JSON.parse(match![1]!);
    expect(parsed.schema_version).toBe(1);
    expect(Array.isArray(parsed.nodes)).toBe(true);
    expect(parsed.nodes.length).toBe(1);
    expect(parsed.nodes[0].id).toBe("pref-foo");
  });

  test("survives `$` in principle bodies (no $&/$1 injection)", () => {
    writePreference(
      vault,
      basePref("dollars", {
        principle: "Money is $100 or $$abc — keep this exact",
      }),
    );
    const g = collectExplorerData(vault);
    const html = renderExportedHtml(g);
    const match = html.match(
      /<script type="application\/json" id="brain-data">([\s\S]+?)<\/script>/,
    );
    const parsed = JSON.parse(match![1]!);
    const node = parsed.nodes.find((n: { id: string }) => n.id === "pref-dollars");
    expect(node.principle).toBe("Money is $100 or $$abc — keep this exact");
  });

  test("escapes script-closing text in inline JSON", () => {
    writePreference(
      vault,
      basePref("script-close", {
        principle: "Never let </script><script>bad()</script> split the data block",
      }),
    );
    const g = collectExplorerData(vault);
    const html = renderExportedHtml(g);
    expect(html).not.toContain("</script><script>bad()");
    const match = html.match(
      /<script type="application\/json" id="brain-data">([\s\S]+?)<\/script>/,
    );
    expect(match).not.toBeNull();
    const parsed = JSON.parse(match![1]!);
    const node = parsed.nodes.find((n: { id: string }) => n.id === "pref-script-close");
    expect(node.principle).toBe("Never let </script><script>bad()</script> split the data block");
  });

  // §14 polish (v0.10.6) — the keyboard-accessible listbox markup and
  // localStorage hooks must travel with every exported HTML body.
  // These tests guard against accidental DOM removal during future
  // template edits.
  test("template ships keyboard-accessible listbox markup", () => {
    writePreference(vault, basePref("a11y"));
    const html = renderExportedHtml(collectExplorerData(vault));
    expect(html).toContain('id="node-list"');
    expect(html).toContain('role="listbox"');
    expect(html).toContain('aria-activedescendant=""');
    expect(html).toContain('id="reset-layout"');
    expect(html).toContain('id="details-body"');
  });

  test("template wires localStorage layout persistence", () => {
    writePreference(vault, basePref("store"));
    const html = renderExportedHtml(collectExplorerData(vault));
    expect(html).toContain("osb-explorer-layout:");
    expect(html).toContain("STORAGE_KEY");
    expect(html).toContain("saveLayout");
  });

  // Smoke guard against the v0.10.6 regression where the simplify
  // pass dropped `focusedNodeId` and `visibleNodesSorted()` but left
  // the keyboard-handler callsites pointing at them (Home / End /
  // Enter / Space threw ReferenceError at runtime). Without a JS
  // execution test, this regex check is the cheapest way to keep
  // the rename honest.
  test("keyboard handlers reference only live identifiers", () => {
    writePreference(vault, basePref("kb"));
    const html = renderExportedHtml(collectExplorerData(vault));
    expect(html).not.toContain("visibleNodesSorted(");
    expect(html).not.toContain("focusedNodeId");
    // The cache + canonical selection variable must both be present
    // because the handlers consume them.
    expect(html).toContain("visibleSortedCache");
    expect(html).toContain("selectedId");
  });
});

describe("buildLiveServer JSON routes", () => {
  const REPORT_SNAPSHOTS_ENV = "OPEN_SECOND_BRAIN_REPORT_SNAPSHOTS";
  let previousEnv: string | undefined;

  beforeEach(() => {
    previousEnv = process.env[REPORT_SNAPSHOTS_ENV];
    delete process.env[REPORT_SNAPSHOTS_ENV];
  });
  afterEach(() => {
    if (previousEnv === undefined) delete process.env[REPORT_SNAPSHOTS_ENV];
    else process.env[REPORT_SNAPSHOTS_ENV] = previousEnv;
  });

  test("serves /counts.json from the console collector, re-read per GET", async () => {
    emitRecallTelemetry(vault, {
      host: "unit-test",
      channel: "cli",
      mode: "search",
      status: "ok",
      durationMs: 1,
      resultCount: 1,
      topArtifacts: [{ id: "pref-seed" }],
    });
    const server = buildLiveServer(vault, 0);
    try {
      const first = await fetch(new URL("/counts.json", server.url));
      expect(first.ok).toBe(true);
      const body = JSON.parse(await first.text()) as {
        schema_version: number;
        telemetry: { total: number };
        written_per_day: ReadonlyArray<unknown>;
        report_snapshots: unknown;
      };
      expect(body.schema_version).toBe(1);
      expect(body.telemetry.total).toBe(1);
      expect(body.written_per_day.length).toBe(30);
      expect(body.report_snapshots).toEqual({ status: "disabled" });
      // A second GET re-reads: a record appended between requests is
      // visible without restarting the server.
      emitRecallTelemetry(vault, {
        host: "unit-test",
        channel: "cli",
        mode: "query",
        status: "empty",
        durationMs: 1,
        resultCount: 0,
      });
      const second = await fetch(new URL("/counts.json", server.url));
      const again = JSON.parse(await second.text()) as { telemetry: { total: number } };
      expect(again.telemetry.total).toBe(2);
    } finally {
      await server.close();
    }
  });

  test("serves /status.json from the operator snapshot with configPath threaded through", async () => {
    writePreference(vault, basePref("routed"));
    // The active profile is read from the profiles registry beside the
    // config path, so it is the observable for the additive options
    // object reaching buildOperatorSnapshot.
    const configPath = join(vault, "config.yaml");
    writeFileSync(
      join(vault, "profiles.json"),
      JSON.stringify({ active: "work", profiles: { work: { vault } } }),
    );
    const server = buildLiveServer(vault, 0, { configPath });
    try {
      const res = await fetch(new URL("/status.json", server.url));
      expect(res.ok).toBe(true);
      const body = JSON.parse(await res.text()) as {
        activeProfile: string | null;
        healthy: boolean;
        counts: { preferences: number };
      };
      expect(body.activeProfile).toBe("work");
      expect(typeof body.healthy).toBe("boolean");
      expect(body.counts.preferences).toBe(1);
    } finally {
      await server.close();
    }
    // Without the options object no config path reaches the snapshot,
    // so the profile lookup reads as none.
    const bare = buildLiveServer(vault, 0);
    try {
      const res = await fetch(new URL("/status.json", bare.url));
      const body = JSON.parse(await res.text()) as { activeProfile: string | null };
      expect(body.activeProfile).toBeNull();
    } finally {
      await bare.close();
    }
  });

  test("unknown routes still answer 404", async () => {
    const server = buildLiveServer(vault, 0);
    try {
      const res = await fetch(new URL("/nope.json", server.url));
      expect(res.status).toBe(404);
    } finally {
      await server.close();
    }
  });

  test("a broken counts section surfaces by name as a 500 JSON error", async () => {
    // With snapshots enabled the collector lists Brain/reports; a FILE
    // parked at that path makes the listing throw, and the route must
    // answer with the error message rather than an empty payload.
    process.env[REPORT_SNAPSHOTS_ENV] = "true";
    mkdirSync(join(vault, "Brain"), { recursive: true });
    writeFileSync(join(vault, "Brain", "reports"), "not a directory");
    const server = buildLiveServer(vault, 0);
    try {
      const res = await fetch(new URL("/counts.json", server.url));
      expect(res.status).toBe(500);
      const body = JSON.parse(await res.text()) as { error: string };
      expect(typeof body.error).toBe("string");
      expect(body.error).toContain("reports");
    } finally {
      await server.close();
    }
  });

  test("a non-loopback Host header is refused with a named 403 on every route", async () => {
    // The loopback BIND is not a browser boundary: a DNS-rebinding page
    // resolves an attacker hostname to 127.0.0.1 and the request arrives
    // carrying that hostname. The server itself must refuse it, on the
    // graph route and the new JSON routes alike.
    const server = buildLiveServer(vault, 0);
    try {
      const refusedOn = async (route: string): Promise<{ status: number; error: string }> => {
        const res = await fetch(new URL(route, server.url), {
          headers: { host: "attacker.example" },
        });
        const body = JSON.parse(await res.text()) as { error: string };
        return { status: res.status, error: body.error };
      };
      const forHtml = await refusedOn("/");
      expect(forHtml.status).toBe(403);
      expect(forHtml.error).toContain("loopback");
      const forGraph = await refusedOn("/data.json");
      expect(forGraph.status).toBe(403);
      expect(forGraph.error).toContain("loopback");
      const forCounts = await refusedOn("/counts.json");
      expect(forCounts.status).toBe(403);
      expect(forCounts.error).toContain("loopback");
      const forStatus = await refusedOn("/status.json");
      expect(forStatus.status).toBe(403);
      expect(forStatus.error).toContain("loopback");
    } finally {
      await server.close();
    }
  });

  test("a cross-origin request is refused before any route runs", async () => {
    // A web page's blind no-cors GET carries a loopback Host but names its
    // own site in Sec-Fetch-Site and Origin; it must not make the server
    // build the operator snapshot.
    const server = buildLiveServer(vault, 0);
    try {
      const crossSite = await fetch(new URL("/status.json", server.url), {
        headers: { "sec-fetch-site": "cross-site" },
      });
      expect(crossSite.status).toBe(403);
      expect(((await crossSite.json()) as { error: string }).error).toContain("cross-origin");
      const foreignOrigin = await fetch(new URL("/counts.json", server.url), {
        headers: { origin: "https://attacker.example" },
      });
      expect(foreignOrigin.status).toBe(403);
      // The console's own page fetching its routes is same-origin.
      const own = await fetch(new URL("/counts.json", server.url), {
        headers: { "sec-fetch-site": "same-origin", origin: `http://127.0.0.1:${server.port}` },
      });
      expect(own.ok).toBe(true);
    } finally {
      await server.close();
    }
  });

  test("a loopback Host name with any port is accepted", async () => {
    writePreference(vault, basePref("hosted"));
    const server = buildLiveServer(vault, 0);
    try {
      const servedWith = async (host: string): Promise<number> => {
        const res = await fetch(new URL("/counts.json", server.url), {
          headers: { host },
        });
        const body = JSON.parse(await res.text()) as { schema_version: number };
        return res.ok ? body.schema_version : -1;
      };
      // The default request already carries 127.0.0.1:<port>.
      const direct = await fetch(new URL("/counts.json", server.url));
      expect(direct.ok).toBe(true);
      // The other loopback spellings, port included, are the allowlist.
      expect(await servedWith(`localhost:${server.port}`)).toBe(1);
      expect(await servedWith(`[::1]:${server.port}`)).toBe(1);
    } finally {
      await server.close();
    }
  });
});