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
4.5 KB
Raw Blame
/**
 * `o2b brain backlinks` reports what it could not read
 * (a-label-is-not-a-boundary review, C7).
 *
 * `buildBacklinkIndex` stopped swallowing parse failures and started
 * carrying them on the returned index; `brain_backlinks` renders them.
 * This verb - the surface an operator debugging a legacy vault reaches
 * FIRST, before any MCP client is involved - kept printing `Backlinks to
 * <id>: 0` and nothing else, which is the same confident zero the core
 * change removed, one layer up.
 */

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

import { runCli } from "../helpers/run-cli.ts";
import { brainDirs } from "../../src/core/brain/paths.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-backlinks-cli-"));
  vault = join(tmp, "vault");
  config = join(tmp, "config.yaml");
});
afterEach(() => rmSync(tmp, { recursive: true, force: true }));

const env = (): Record<string, string> => ({ OPEN_SECOND_BRAIN_CONFIG: config });

async function bootstrap(): Promise<void> {
  const init = await runCli(["init", "--vault", vault, "--name", "TestBacklinks"], { env: env() });
  expect(init.returncode).toBe(0);
  const brainInit = await runCli(["brain", "init", "--vault", vault], { env: env() });
  expect(brainInit.returncode).toBe(0);
}

/**
 * A preference whose frontmatter the collector cannot read, holding a
 * reference to the target. The legacy shape: Group C derived keys written
 * WITHOUT the `_` prefix, which `normalizeDerivedKeys` refuses - the exact
 * vault the swallowed `catch { continue }` used to hide.
 */
function seedUnreadableReferrer(slug: string, target: string): void {
  writeFileSync(
    join(brainDirs(vault).preferences, `pref-${slug}.md`),
    [
      "---",
      "kind: brain-preference",
      "id: `pref-" + slug + "`",
      "status: confirmed",
      "_status: confirmed",
      "topic: legacy",
      `evidenced_by: ["[[${target}]]"]`,
      "---",
      "",
      `## Principle`,
      "",
      `see [[${target}]]`,
      "",
    ].join("\n"),
  );
}

describe("brain backlinks does not report an unmeasured zero", () => {
  test("an unparseable referrer is named on the human surface", async () => {
    await bootstrap();
    seedUnreadableReferrer("legacy-rule", "pref-target");

    const r = await runCli(["brain", "backlinks", "--vault", vault, "pref-target"], {
      env: env(),
    });

    expect(r.returncode).toBe(0);
    // The count is still printed - it is what the caller asked for…
    expect(r.stdout).toContain("Backlinks to pref-target: 0");
    // …but it no longer stands alone. The artifact and the reason travel
    // with it, in the same vocabulary `brain_backlinks` uses.
    expect(r.stderr).toContain("pref-legacy-rule");
    expect(r.stderr).toContain("incomplete");
    // No host path in the reason: `buildBacklinkIndex` strips it, and this
    // verb must not put one back.
    expect(r.stderr).not.toContain(vault);
  });

  test("--json carries the same failures under the MCP tool's key", async () => {
    await bootstrap();
    seedUnreadableReferrer("legacy-rule", "pref-target");

    const r = await runCli(["brain", "backlinks", "--vault", vault, "--json", "pref-target"], {
      env: env(),
    });

    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      count: number;
      unparsed?: ReadonlyArray<{ source: string; sourceKind: string; reason: string }>;
    };
    expect(payload.count).toBe(0);
    expect(payload.unparsed?.map((u) => u.source)).toEqual(["pref-legacy-rule"]);
    expect(payload.unparsed?.[0]?.sourceKind).toBe("preference");
  });

  test("a healthy vault's output is unchanged - no key, no note", async () => {
    await bootstrap();

    const r = await runCli(["brain", "backlinks", "--vault", vault, "--json", "pref-target"], {
      env: env(),
    });

    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as Record<string, unknown>;
    // Absent, never an empty array: an empty list would make every caller
    // branch on a state that cannot happen on a healthy vault.
    expect("unparsed" in payload).toBe(false);
    expect(r.stderr).not.toContain("incomplete");
  });
});