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
11.8 KB
Raw Blame
/**
 * Conformance: the expected-output block in every per-runtime install
 * document must match what the adapter's `verify()` actually prints.
 *
 * The Verify section of each `install/<runtime>.md` used to say "run
 * this" and never "this is what success looks like", so an agent
 * following the document had nothing to pattern-match against. Each
 * document now carries a block introduced by
 *
 *     <!-- expected-output: o2b install --check --target <t> -->
 *
 * and this suite renders the real thing: it installs the target into an
 * injected environment (temp home, temp vault - no adapter reads the
 * real one), calls `verify()`, renders it through the same
 * `renderVerifyTable` the CLI uses, and compares. Machine-specific
 * absolute paths are replaced by the placeholders the documents use.
 *
 * When this fails, the message names the document to edit.
 */

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

import { registerAllAdapters } from "../../src/core/install/adapters/all.ts";
import {
  resetCodexRunner,
  setCodexRunner,
  type CodexRunner,
} from "../../src/core/install/adapters/codex.ts";
import {
  resetCopilotRunner,
  setCopilotRunner,
  type CopilotRunner,
} from "../../src/core/install/adapters/copilot-cli.ts";
import { resetHostProbeRunner, setHostProbeRunner } from "../../src/core/install/host-probe.ts";
import { buildPayload } from "../../src/core/install/payload.ts";
import { renderVerifyTable } from "../../src/cli/install/render.ts";
import type {
  ApplyOpts,
  InstallAdapter,
  InstallEnv,
  McpPayload,
} from "../../src/core/install/types.ts";

const REPO_ROOT = resolve(import.meta.dir, "..", "..");
const INSTALL_DOCS_DIR = join(REPO_ROOT, "install");

/** Placeholders the documents use in place of machine-specific paths. */
const HOME_PLACEHOLDER = "$HOME";
const VAULT_PLACEHOLDER = "<vault>";
const PLUGIN_PLACEHOLDER = "<plugin>";

/** Marker that introduces a documented expected-output block. */
const EXPECTED_OUTPUT_MARKER = "<!-- expected-output:";

const AGENT_NAME = "claude-vps";
const TIMEZONE = "UTC";

/**
 * Install documents with no registered adapter: their Verify step runs a
 * third-party command (`claude mcp list`, `hermes memory status`, …),
 * not `o2b install --check`, so there is nothing in this codebase to
 * assert their output against. Listed rather than skipped so a NEW
 * adapter-backed document cannot quietly avoid the binding.
 */
const PIPELINE_HOSTED_DOCS: Readonly<Record<string, string>> = Object.freeze({
  "claudecode.md": "plugin-hosted; verified with `claude mcp list`, not an OSB adapter",
  "hermes.md": "provider-hosted; verified with `hermes memory status`, not an OSB adapter",
  "openclaw.md": "plugin-hosted; verified with `openclaw plugins inspect`, not an OSB adapter",
  "prerequisites.md": "shared setup, not a runtime document",
  "windows.md": "shared setup for native Windows, not a runtime document",
  "zcode.md": "manual MCP config in ZCode's own file; no install adapter yet",
});

interface Harness {
  readonly vault: string;
  readonly home: string;
  readonly opts: ApplyOpts;
  readonly env: InstallEnv;
  readonly payload: McpPayload;
}

let vault: string;
let home: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "osb-doc-v-"));
  home = mkdtempSync(join(tmpdir(), "osb-doc-h-"));
});

afterEach(() => {
  resetCodexRunner();
  resetCopilotRunner();
  resetHostProbeRunner();
  for (const dir of [vault, home]) {
    try {
      rmSync(dir, { recursive: true, force: true });
    } catch {
      // temp cleanup is best-effort
    }
  }
});

function sink(): NodeJS.WriteStream {
  return new Writable({
    write(_chunk, _enc, cb) {
      cb();
    },
  }) as unknown as NodeJS.WriteStream;
}

function harness(overrides: Partial<ApplyOpts> = {}): Harness {
  return {
    vault,
    home,
    env: {
      vault,
      home,
      cwd: home,
      env: { VAULT_AGENT_NAME: AGENT_NAME, VAULT_TIMEZONE: TIMEZONE },
      now: new Date("2026-05-20T12:00:00.000Z"),
    },
    // Built from the SAME vault the adapter verifies against: several
    // adapters recompute the expected payload from `env.vault`, so a
    // payload for any other vault would (correctly) verify as drift.
    payload: buildPayload({ vault, agent_name: AGENT_NAME, timezone: TIMEZONE }),
    opts: { dryRun: false, force: false, stdout: sink(), stderr: sink(), ...overrides },
  };
}

/**
 * Per-target setup that puts the adapter into its INSTALLED state. Every
 * entry performs a real apply against the injected environment; nothing
 * here fabricates a manifest.
 */
const INSTALLERS: Readonly<Record<string, (adapter: InstallAdapter) => Harness>> = Object.freeze({
  generic: (adapter) => {
    const h = harness({ outPath: join(home, "osb-mcp.json") });
    return applyInto(adapter, h);
  },
  pi: (adapter) => {
    const h = harness({ piSkillSource: join(REPO_ROOT, "skills", "brain-memory") });
    return applyInto(adapter, h);
  },
  codex: (adapter) => {
    // The codex CLI may or may not be on the machine running this suite,
    // and the document has to show ONE thing: what an operator who has
    // it installed sees. So the mutation seam is a fake that behaves
    // like the real binary - `mcp add` persists a `[mcp_servers.<name>]`
    // table into `$CODEX_HOME/config.toml`, in codex's own layout rather
    // than the adapter's - and the read-only probe is staged separately,
    // exactly as the copilot case below stages its two seams.
    const registered: string[] = [];
    const runner: CodexRunner = {
      available: () => true,
      run: (codexHome: string, args: ReadonlyArray<string>) => {
        if (args[0] === "mcp" && args[1] === "add" && typeof args[2] === "string") {
          registered.push(args[2]);
          mkdirSync(codexHome, { recursive: true });
          const tables = registered
            .map((name) => `[mcp_servers.${name}]\ncommand = "o2b"\nargs = [\n  "mcp",\n]\n`)
            .join("\n");
          writeFileSync(join(codexHome, "config.toml"), tables);
        }
        return { exitCode: 0, stdout: "", stderr: "" };
      },
    };
    setCodexRunner(runner);
    setHostProbeRunner({
      available: () => true,
      run: () => ({ exitCode: 0, stdout: registered.join("\n") + "\n", stderr: "" }),
    });
    return applyInto(adapter, harness());
  },
  "copilot-cli": (adapter) => {
    // The copilot CLI is not present in a test environment; inject a
    // runner that behaves like a working one so the document shows the
    // subprocess path an operator with the CLI installed will see.
    const registered: string[] = [];
    const runner: CopilotRunner = {
      available: () => true,
      list: () => ({ ok: true, names: [...registered] }),
      run: (args: ReadonlyArray<string>) => {
        if (args[0] === "mcp" && args[1] === "add" && typeof args[2] === "string") {
          registered.push(args[2]);
        }
        return { exitCode: 0, stdout: "", stderr: "" };
      },
    };
    setCopilotRunner(runner);
    // `verify` reads the host through the DECLARED probe rather than
    // through `CopilotRunner`, so the same fiction has to be staged on
    // that seam too - otherwise the document would show the verdict of a
    // machine with no `copilot` on PATH, which is not what a successful
    // check looks like.
    setHostProbeRunner({
      available: () => true,
      run: () => ({ exitCode: 0, stdout: registered.join("\n") + "\n", stderr: "" }),
    });
    return applyInto(adapter, harness());
  },
});

function defaultInstaller(adapter: InstallAdapter): Harness {
  return applyInto(adapter, harness());
}

/** Run the adapter's real plan+apply against the injected environment. */
function applyInto(adapter: InstallAdapter, h: Harness): Harness {
  adapter.apply(adapter.plan(h.payload, h.env), h.payload, h.env, h.opts);
  return h;
}

/** Replace machine-specific absolute paths with the documented placeholders. */
function placeholders(text: string, h: Harness): string {
  const replaced = text
    .split(h.vault)
    .join(VAULT_PLACEHOLDER)
    .split(h.home)
    .join(HOME_PLACEHOLDER)
    .split(REPO_ROOT)
    .join(PLUGIN_PLACEHOLDER);
  // The documents spell paths the POSIX way; on Windows the same paths are
  // joined with backslashes, which is the only difference to fold away.
  return sep === "/" ? replaced : replaced.split(sep).join("/");
}

/**
 * Trailing whitespace is not comparable across editors (the table pads
 * its status column, and a detail-less row ends in spaces), so both
 * sides are compared line-trimmed.
 */
function comparable(text: string): string {
  return text
    .split("\n")
    .map((line) => line.trimEnd())
    .join("\n")
    .trim();
}

interface DocumentedBlock {
  readonly command: string;
  readonly body: string;
  readonly line: number;
}

/** Extract the single expected-output block from an install document. */
function readDocumentedBlock(docPath: string): DocumentedBlock | null {
  const lines = readFileSync(docPath, "utf8").split("\n");
  const markerIdx = lines.findIndex((line) => line.trimStart().startsWith(EXPECTED_OUTPUT_MARKER));
  if (markerIdx < 0) return null;
  const marker = lines[markerIdx]!.trim();
  const command = marker.slice(EXPECTED_OUTPUT_MARKER.length, marker.lastIndexOf("-->")).trim();
  let cursor = markerIdx + 1;
  while (cursor < lines.length && lines[cursor]!.trim() === "") cursor++;
  if (cursor >= lines.length || !lines[cursor]!.startsWith("```")) return null;
  const bodyStart = cursor + 1;
  const bodyEnd = lines.findIndex((line, idx) => idx >= bodyStart && line.startsWith("```"));
  if (bodyEnd < 0) return null;
  return {
    command,
    body: lines.slice(bodyStart, bodyEnd).join("\n"),
    line: markerIdx + 1,
  };
}

const adapters = registerAllAdapters().list();

describe("install documents — expected output matches verify()", () => {
  for (const adapter of adapters) {
    const docRel = `install/${adapter.target}.md`;
    const docPath = join(REPO_ROOT, docRel);

    test(`${docRel} documents what a successful check prints`, () => {
      const documented = readDocumentedBlock(docPath);
      expect(`${docRel}: expected-output block present = ${documented !== null}`).toBe(
        `${docRel}: expected-output block present = true`,
      );
      const install = INSTALLERS[adapter.target] ?? defaultInstaller;
      const h = install(adapter);
      const actual = placeholders(renderVerifyTable([adapter.verify(h.env)]), h);
      // Naming the document inside the compared value puts it in the
      // failure diff, not only in the test title.
      expect(`${docRel}:${documented!.line}\n${comparable(actual)}`).toBe(
        `${docRel}:${documented!.line}\n${comparable(documented!.body)}`,
      );
    });

    test(`${docRel} documents the command the block came from`, () => {
      const documented = readDocumentedBlock(docPath);
      expect(documented?.command).toBe(`o2b install --check --target ${adapter.target}`);
    });
  }
});

describe("install documents — completeness", () => {
  test("every runtime document is either adapter-bound or listed as pipeline-hosted", () => {
    const targets = new Set(adapters.map((a) => `${a.target}.md`));
    const unbound = readdirSyncSorted(INSTALL_DOCS_DIR).filter(
      (name) => !targets.has(name) && !(name in PIPELINE_HOSTED_DOCS),
    );
    expect(unbound).toEqual([]);
  });

  test("every pipeline-hosted document carries a written reason and still exists", () => {
    for (const [name, reason] of Object.entries(PIPELINE_HOSTED_DOCS)) {
      expect(reason.trim().length).toBeGreaterThan(0);
      expect(readdirSyncSorted(INSTALL_DOCS_DIR)).toContain(name);
    }
  });
});

function readdirSyncSorted(dir: string): string[] {
  return readdirSync(dir)
    .filter((name) => name.endsWith(".md"))
    .toSorted();
}