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
15.1 KB
Raw Blame
/**
 * `o2b install` instruction step, subprocess-level tests (t_ba41a78a B3).
 *
 * The instruction step rides `runTarget`: the plan renders it (or its
 * named skip) for every target, ONE consent verdict covers the adapter
 * write and the instruction write, a `user-modified-block` refusal exits
 * 4, and a failure after the adapter applied still exits non-zero with a
 * re-run converging. `--check` is untouched: the readiness probe remains
 * the block auditor.
 */

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

import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
import { runCli as baseRunCli, type RunCliOptions, type RunResult } from "../helpers/run-cli.ts";
import { auditWritebackContractFile } from "../../src/core/brain/writeback-contract.ts";
import { DEFAULT_BEGIN_MARKER, DEFAULT_END_MARKER } from "../../src/core/install/managed-block.ts";
import { instructionBlockLockPath } from "../../src/core/install/instruction-block.ts";

function runCli(args: ReadonlyArray<string>, opts: RunCliOptions = {}): Promise<RunResult> {
  return baseRunCli(args, { ...opts, subprocess: true });
}

setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

let vault: string;
let home: string;
let configPath: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "osb-install-step-v-"));
  home = mkdtempSync(join(tmpdir(), "osb-install-step-h-"));
  configPath = join(home, "config.yaml");
  mkdirSync(vault, { recursive: true });
  writeFileSync(configPath, `vault: "${vault}"\nagent_name: "claude-vps"\ntimezone: "UTC"\n`);
});

afterEach(() => {
  for (const p of [vault, home]) {
    try {
      rmSync(p, { recursive: true, force: true });
    } catch {}
  }
});

function envBase(extra: Record<string, string> = {}) {
  return {
    HOME: home,
    OPEN_SECOND_BRAIN_CONFIG: configPath,
    VAULT_DIR: vault,
    VAULT_AGENT_NAME: "claude-vps",
    VAULT_TIMEZONE: "UTC",
    ...extra,
  };
}

describe("o2b install --target <host>: the instruction step in the plan", () => {
  test("a cursor plan includes the managed-block step for the vault-root AGENTS.md", async () => {
    const r = await runCli(["install", "--target", "cursor", "--json"], { env: envBase() });
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      plan: { steps: ReadonlyArray<{ kind: string; path: string | null; diff?: string }> };
    };
    const step = payload.plan.steps.find((s) => s.path !== null && s.path.endsWith("AGENTS.md"));
    expect(step).toBeDefined();
    expect(step?.kind).toBe("managed-block");
    expect(step?.diff).not.toBe("");
    // Plan-only writes nothing.
    expect(existsSync(join(vault, "AGENTS.md"))).toBe(false);
  });

  test("a gemini-cli plan carries the name-implied reading caveat", async () => {
    const r = await runCli(["install", "--target", "gemini-cli", "--json"], { env: envBase() });
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      plan: { steps: ReadonlyArray<{ path: string | null; preview: string }> };
    };
    const step = payload.plan.steps.find((s) => s.path !== null && s.path.endsWith("GEMINI.md"));
    expect(step).toBeDefined();
    expect(step?.preview).toContain("name-implied");
  });

  test("a target with no precedence entry plans the named skip and no instruction step", async () => {
    const r = await runCli(["install", "--target", "copilot-cli", "--json"], { env: envBase() });
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      plan: { steps: ReadonlyArray<{ path: string | null }>; postNotes: ReadonlyArray<string> };
    };
    const instructionSteps = payload.plan.steps.filter(
      (s) =>
        s.path !== null &&
        (s.path.endsWith("AGENTS.md") ||
          s.path.endsWith("CLAUDE.md") ||
          s.path.endsWith("GEMINI.md")),
    );
    expect(instructionSteps.length).toBe(0);
    expect(payload.plan.postNotes.join("\n")).toContain("copilot-cli");
    expect(payload.plan.postNotes.join("\n")).toContain("agent-instruction");
  });

  test("a symlinked instruction file refuses the plan by name, not with a crash", async () => {
    // The checker's posture: a plan cannot even be computed against a
    // link, because the file a write would land on is not the file the
    // contract audits. The refusal must be the named one on stderr - the
    // module throws before the consent gate, so an unhandled rejection
    // here would print a stack trace and exit through the top-level
    // handler instead.
    const real = join(home, "real-agents.md");
    writeFileSync(real, "# operator notes\n");
    symlinkSync(real, join(vault, "AGENTS.md"));
    const planned = await runCli(["install", "--target", "cursor", "--json"], { env: envBase() });
    expect(planned.returncode).toBe(1);
    expect(planned.stderr).toContain("error:");
    expect(planned.stderr).toContain("symbolic link");
    expect(planned.stderr).not.toMatch(/\n\s+at /);
    // The apply path refuses the same way, before any consent or write.
    const applied = await runCli(["install", "--target", "cursor", "--apply", "--yes"], {
      env: envBase(),
    });
    expect(applied.returncode).toBe(1);
    expect(applied.stderr).toContain("symbolic link");
    expect(applied.stderr).not.toMatch(/\n\s+at /);
    expect(existsSync(join(home, ".cursor", "mcp.json"))).toBe(false);
    expect(existsSync(instructionBlockLockPath(vault))).toBe(false);
  });
});

describe("o2b install --target <host> --apply: one consent verdict, both writes", () => {
  test("headless apply without --yes refuses with exit 6 and writes nothing", async () => {
    const r = await runCli(["install", "--target", "cursor", "--apply", "--json"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(6);
    const payload = JSON.parse(r.stdout) as { consent: string; written: boolean };
    expect(payload.consent).toBe("headless-refused");
    expect(payload.written).toBe(false);
    // Neither the adapter write nor the instruction write happened.
    expect(existsSync(join(home, ".cursor", "mcp.json"))).toBe(false);
    expect(existsSync(join(vault, "AGENTS.md"))).toBe(false);
    expect(existsSync(instructionBlockLockPath(vault))).toBe(false);
  });

  test("apply with --yes writes the block, and the readiness auditor grades it conforming", async () => {
    const r = await runCli(["install", "--target", "cursor", "--apply", "--yes"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(0);
    const audit = auditWritebackContractFile(join(vault, "AGENTS.md"));
    expect(audit.finding).toBe("conforming");
    expect(r.stdout).toContain("AGENTS.md");
    const lock = JSON.parse(readFileSync(instructionBlockLockPath(vault), "utf8")) as {
      schema_version: number;
      files: Record<string, { applied_at: string; begin_marker: string }>;
    };
    expect(lock.schema_version).toBe(1);
    expect(lock.files["AGENTS.md"]?.begin_marker).toBe(DEFAULT_BEGIN_MARKER);
    expect(Number.isFinite(Date.parse(lock.files["AGENTS.md"]?.applied_at ?? "never"))).toBe(true);
  });

  test("apply is idempotent: a re-apply converges with the same bytes", async () => {
    await runCli(["install", "--target", "cursor", "--apply", "--yes"], { env: envBase() });
    const once = readFileSync(join(vault, "AGENTS.md"), "utf8");
    const r = await runCli(["install", "--target", "cursor", "--apply", "--yes"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(0);
    expect(readFileSync(join(vault, "AGENTS.md"), "utf8")).toBe(once);
  });

  test("the post-apply line reports created, updated and already-current honestly", async () => {
    // First install on a vault with no AGENTS.md: the block is CREATED,
    // and the line must not claim the file already carried it.
    const created = await runCli(["install", "--target", "cursor", "--apply", "--yes"], {
      env: envBase(),
    });
    expect(created.returncode).toBe(0);
    expect(created.stdout).toContain("instruction block: ");
    expect(created.stdout).toContain("created with the write-gate block");
    expect(created.stdout).not.toContain("already carries");

    // A hand-edited block rewritten under --force is an UPDATE.
    const rulesPath = join(vault, "AGENTS.md");
    writeFileSync(
      rulesPath,
      readFileSync(rulesPath, "utf8").replace(
        "observing-memory layer. At session start, read the current preferences",
        "hand-edited wording that no longer matches the canonical body",
      ),
    );
    const updated = await runCli(["install", "--target", "cursor", "--apply", "--yes", "--force"], {
      env: envBase(),
    });
    expect(updated.returncode).toBe(0);
    expect(updated.stdout).toContain("now carries the write-gate block");
    expect(updated.stdout).not.toContain("already carries");

    // A re-apply with nothing to change is already current.
    const current = await runCli(["install", "--target", "cursor", "--apply", "--yes"], {
      env: envBase(),
    });
    expect(current.returncode).toBe(0);
    expect(current.stdout).toContain("already carries the current write-gate block");
  });

  test("the --apply --json payload carries the instruction-block outcome", async () => {
    // A headless consumer consented to a plan whose JSON showed the
    // managed-block step, so the apply receipt on the same stream must
    // say what that step did - the same outcome the uninstall payload
    // carries as `instruction_block` (mirrored shape, mirrored skip).
    const created = await runCli(["install", "--target", "cursor", "--apply", "--yes", "--json"], {
      env: envBase(),
    });
    expect(created.returncode).toBe(0);
    const payload = JSON.parse(created.stdout) as {
      instruction_block: {
        file: string | null;
        created: boolean;
        changed: boolean;
        backup_path: string | null;
        skipped_reason: string | null;
      };
    };
    expect(payload.instruction_block.file).toBe(join(vault, "AGENTS.md"));
    expect(payload.instruction_block.created).toBe(true);
    expect(payload.instruction_block.changed).toBe(true);
    expect(payload.instruction_block.skipped_reason).toBeNull();

    // A re-apply reports the no-op honestly: nothing changed, no backup.
    const again = await runCli(["install", "--target", "cursor", "--apply", "--yes", "--json"], {
      env: envBase(),
    });
    expect(again.returncode).toBe(0);
    const second = JSON.parse(again.stdout) as {
      instruction_block: { created: boolean; changed: boolean; backup_path: string | null };
    };
    expect(second.instruction_block.created).toBe(false);
    expect(second.instruction_block.changed).toBe(false);
    expect(second.instruction_block.backup_path).toBeNull();
  });

  test("the --apply --json payload names the skip for a target with no precedence entry", async () => {
    const r = await runCli(["install", "--target", "copilot-cli", "--apply", "--yes", "--json"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      instruction_block: { file: string | null; skipped_reason: string | null };
    };
    expect(payload.instruction_block.file).toBeNull();
    expect(payload.instruction_block.skipped_reason).toContain("copilot-cli");
  });

  test("apply with --yes --dry-run writes nothing on either lane", async () => {
    const r = await runCli(["install", "--target", "cursor", "--apply", "--yes", "--dry-run"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(0);
    expect(existsSync(join(vault, "AGENTS.md"))).toBe(false);
    expect(existsSync(instructionBlockLockPath(vault))).toBe(false);
  });
});

describe("o2b install --apply: refusals and convergence", () => {
  test("a hand-edited block on a fresh file refuses with exit 4 and a force upgrade exits 0", async () => {
    // The docs-snippet block an older manual install pasted: present,
    // non-conforming, and no lock record can prove it ours.
    writeFileSync(
      join(vault, "AGENTS.md"),
      [
        "# operator notes",
        "",
        DEFAULT_BEGIN_MARKER,
        "## Open Second Brain",
        "",
        "This project shares an Obsidian-compatible vault. Read Brain/active.md.",
        DEFAULT_END_MARKER,
        "",
      ].join("\n"),
    );
    const refused = await runCli(["install", "--target", "cursor", "--apply", "--yes"], {
      env: envBase(),
    });
    expect(refused.returncode).toBe(4);
    expect(refused.stderr).toContain("hand-edited");
    // Nothing was written by the refused step.
    expect(auditWritebackContractFile(join(vault, "AGENTS.md")).finding).not.toBe("conforming");
    const forced = await runCli(["install", "--target", "cursor", "--apply", "--yes", "--force"], {
      env: envBase(),
    });
    expect(forced.returncode).toBe(0);
    expect(auditWritebackContractFile(join(vault, "AGENTS.md")).finding).toBe("conforming");
    // The operator's own bytes survived the upgrade.
    expect(readFileSync(join(vault, "AGENTS.md"), "utf8").startsWith("# operator notes")).toBe(
      true,
    );
  });

  test("a failure after the adapter apply exits non-zero; a re-run converges", async () => {
    // A hand-pasted docs-snippet block refuses at APPLY time - after the
    // adapter's config write has already landed. Symlinks refuse at PLAN
    // time instead (the checker's posture), so the refusal that proves
    // the ordering here is the hand-edit one.
    writeFileSync(
      join(vault, "AGENTS.md"),
      [
        "# operator notes",
        "",
        DEFAULT_BEGIN_MARKER,
        "## Open Second Brain",
        "",
        "This project shares an Obsidian-compatible vault. Read Brain/active.md.",
        DEFAULT_END_MARKER,
        "",
      ].join("\n"),
    );
    const failed = await runCli(["install", "--target", "cursor", "--apply", "--yes"], {
      env: envBase(),
    });
    expect(failed.returncode).toBe(4);
    // The adapter write is committed even though the run failed.
    expect(existsSync(join(home, ".cursor", "mcp.json"))).toBe(true);
    expect(auditWritebackContractFile(join(vault, "AGENTS.md")).finding).not.toBe("conforming");
    // The re-run - with the documented --force override - converges: the
    // adapter write is idempotent and the instruction block lands.
    const converged = await runCli(
      ["install", "--target", "cursor", "--apply", "--yes", "--force"],
      { env: envBase() },
    );
    expect(converged.returncode).toBe(0);
    expect(auditWritebackContractFile(join(vault, "AGENTS.md")).finding).toBe("conforming");
    expect(readFileSync(join(vault, "AGENTS.md"), "utf8").startsWith("# operator notes")).toBe(
      true,
    );
    expect(converged.stdout).toContain("instruction block");
  });
});

describe("o2b install --check stays the block-free verifier", () => {
  test("check after a successful install still exits 0 through the adapter's own verify", async () => {
    await runCli(["install", "--target", "cursor", "--apply", "--yes"], { env: envBase() });
    const r = await runCli(["install", "--check", "--target", "cursor"], { env: envBase() });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("ok");
  });
});