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
16.3 KB
Raw Blame
/**
 * `o2b install` CLI verb — subprocess-level tests.
 *
 * The adapter modules each have direct unit tests; here we verify
 * the verb wiring: detect-only printout, plan-only mode, --apply,
 * --check, --json, exit codes.
 */

import { describe, expect, test, beforeEach, afterEach, setDefaultTimeout } from "bun:test";
import {
  mkdtempSync,
  rmSync,
  existsSync,
  mkdirSync,
  readFileSync,
  writeFileSync,
  utimesSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, 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 { INSTALL_EXIT, exitCodeForVerify } from "../../src/cli/install/install.ts";
import type { VerifyResult } from "../../src/core/install/types.ts";

// The install/uninstall adapters resolve the target home directory from the
// environment at module-load time, so they need a fresh child process per call
// to honor this test's per-case temp HOME (the in-process fast path shares one
// already-loaded module graph). Force the subprocess path for every call here.
function runCli(args: ReadonlyArray<string>, opts: RunCliOptions = {}): Promise<RunResult> {
  return baseRunCli(args, { ...opts, subprocess: true });
}

// Every case here therefore pays a cold process start, which does not fit
// bun's 5 s default on a machine doing other work.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

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

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "osb-install-verb-v-"));
  home = mkdtempSync(join(tmpdir(), "osb-install-verb-h-"));
  configPath = join(home, "config.yaml");
  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 — detect mode", () => {
  test("no args prints the table with no file writes", async () => {
    const r = await runCli(["install"], { env: envBase() });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("detected runtimes");
    // No file should have been written
    expect(existsSync(join(home, ".cursor", "mcp.json"))).toBe(false);
  });

  test("--json emits machine-readable payload", async () => {
    const r = await runCli(["install", "--json"], { env: envBase() });
    expect(r.returncode).toBe(0);
    const parsed = JSON.parse(r.stdout);
    expect(parsed.schema_version).toBe(1);
    expect(Array.isArray(parsed.targets)).toBe(true);
    expect(parsed.targets.length).toBeGreaterThan(0);
  });
});

describe("o2b install --target X (plan-only)", () => {
  test("prints plan without touching the file system", async () => {
    const r = await runCli(["install", "--target", "cursor"], { env: envBase() });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("plan");
    expect(r.stdout).toContain("json-merge");
    expect(existsSync(join(home, ".cursor", "mcp.json"))).toBe(false);
  });

  test("--target unknown exits 2", async () => {
    const r = await runCli(["install", "--target", "nope"], { env: envBase() });
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("unknown --target");
  });
});

describe("o2b install --target X --apply", () => {
  test.skipIf(process.stdin.isTTY)(
    "the interactive y/N prompt rides stderr, not stdout (upgrade/protect/doctor convention)",
    async () => {
      // Reach the interactive branch: fake a TTY on the test process's
      // stdin for one in-process run. The run's own stdin is NOT a TTY
      // (this test is skipped when it is), so it sits at EOF:
      // readSingleLine answers "" at once, the run cancels, and the
      // adapter never applies - nothing touches any real HOME.
      //
      // This is the suite's ONE prompt-consuming test: readSingleLine
      // answers off the shared process stdin, whose EOF fires once per
      // bun test process, so every other interactive-ladder assertion
      // rides here rather than in a second TTY-faked test.
      const stdin = process.stdin as unknown as { isTTY?: boolean };
      const saved = stdin.isTTY;
      Object.defineProperty(stdin, "isTTY", { value: true, configurable: true });
      try {
        const r = await baseRunCli(["install", "--target", "gemini-cli", "--apply"], {
          env: envBase(),
        });
        expect(r.returncode).toBe(0);
        expect(r.stdout).toContain("install cancelled");
        expect(r.stdout).not.toContain("Proceed? [y/N]");
        expect(r.stderr).toContain("Proceed? [y/N]");
        // M15: the consent-time plan renders beside the prompt on
        // stderr - stdout is the payload stream, and a plan prefixed
        // there corrupted e.g. `generic --out -` - and its header no
        // longer says dry-run while asking for apply consent.
        expect(r.stdout).not.toContain("dry-run");
        expect(r.stdout).not.toContain("— plan");
        expect(r.stderr).toContain("— plan");
        expect(r.stderr).toContain("nothing written until you confirm");
        expect(r.stderr).not.toContain("dry-run");
        expect(existsSync(join(home, ".gemini", "settings.json"))).toBe(false);
      } finally {
        Object.defineProperty(stdin, "isTTY", { value: saved, configurable: true });
      }
    },
    5000,
  );

  test("writes the cursor config file", async () => {
    const r = await runCli(["install", "--target", "cursor", "--apply", "--yes"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(0);
    const cfgPath = join(home, ".cursor", "mcp.json");
    expect(existsSync(cfgPath)).toBe(true);
    const parsed = JSON.parse(readFileSync(cfgPath, "utf8"));
    expect(parsed.mcpServers["open-second-brain"]).toBeDefined();
    expect(parsed.mcpServers["open-second-brain-writer"]).toBeDefined();
  });

  test("user hand-edit + re-apply without --force exits 4", async () => {
    await runCli(["install", "--target", "cursor", "--apply", "--yes"], { env: envBase() });
    const cfgPath = join(home, ".cursor", "mcp.json");
    const before = JSON.parse(readFileSync(cfgPath, "utf8"));
    before.mcpServers["open-second-brain"] = { command: "TAMPERED", args: [] };
    writeFileSync(cfgPath, JSON.stringify(before, null, 2) + "\n");
    // bump mtime well into the future
    const future = new Date(Date.now() + 3600 * 1000);
    utimesSync(cfgPath, future, future);

    const r = await runCli(["install", "--target", "cursor", "--apply", "--yes"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(4);
    expect(r.stderr).toContain("hand-edited");
  });

  test(
    "--apply in --json/non-TTY without --yes exits non-zero, names --yes, " +
      "and leaves ~/.gemini/settings.json byte-identical",
    async () => {
      const cfgPath = join(home, ".gemini", "settings.json");
      // A pre-existing file with operator content must survive untouched.
      const original = '{\n  "theme": "dark"\n}\n';
      mkdirSync(dirname(cfgPath), { recursive: true });
      writeFileSync(cfgPath, original);

      // Both non-interactive shapes refuse: an explicit --json call and a
      // bare call whose stdin is not a TTY (subprocess spawns never get one).
      // M4: the --json refusal is a JSON envelope on stdout carrying the
      // reserved `headless-refused` verdict, not bare stderr prose.
      const jsonRun = await runCli(["install", "--target", "gemini-cli", "--apply", "--json"], {
        env: envBase(),
      });
      expect(jsonRun.returncode).toBe(INSTALL_EXIT.consentRefused);
      const envelope = JSON.parse(jsonRun.stdout) as Record<string, unknown>;
      expect(envelope["consent"]).toBe("headless-refused");
      expect(envelope["written"]).toBe(false);
      expect(String(envelope["error"])).toContain("--yes");
      expect(readFileSync(cfgPath, "utf8")).toBe(original);

      const ttylessRun = await runCli(["install", "--target", "gemini-cli", "--apply"], {
        env: envBase(),
      });
      expect(ttylessRun.returncode).toBe(INSTALL_EXIT.consentRefused);
      expect(ttylessRun.stderr).toContain("--yes");
      // Nothing was written: the operator's file is byte-identical.
      expect(readFileSync(cfgPath, "utf8")).toBe(original);
    },
  );

  test("--apply --yes writes and the apply JSON carries the consent verdict", async () => {
    const r = await runCli(["install", "--target", "gemini-cli", "--apply", "--yes", "--json"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(0);
    expect(existsSync(join(home, ".gemini", "settings.json"))).toBe(true);
    const payload = JSON.parse(r.stdout) as Record<string, unknown>;
    // M3: the verdict is derived from what happened (a --yes consent),
    // in the one vocabulary every guarded lane records.
    expect(payload["consent"]).toBe("yes-flag");
  });

  test("--plan prints a unified diff of the settings file", async () => {
    const cfgPath = join(home, ".gemini", "settings.json");
    mkdirSync(dirname(cfgPath), { recursive: true });
    writeFileSync(cfgPath, '{\n  "theme": "dark"\n}\n');
    const r = await runCli(["install", "--target", "gemini-cli"], { env: envBase() });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("---");
    expect(r.stdout).toContain("+++");
    expect(r.stdout).toContain("+ ");
    // The operator's own key survives in the merged preview.
    expect(r.stdout).toContain("theme");
  });

  test("a consent refusal keeps its own exit code, distinct from usage and drift", () => {
    expect(INSTALL_EXIT.consentRefused).toBe(6);
    const codes = Object.values(INSTALL_EXIT);
    expect(new Set(codes).size).toBe(codes.length);
  });
});

describe("o2b install --target generic", () => {
  test("--out <path> writes the JSON payload to that path", async () => {
    const outPath = join(home, "snippet.json");
    const r = await runCli(
      ["install", "--target", "generic", "--apply", "--yes", "--out", outPath],
      {
        env: envBase(),
      },
    );
    expect(r.returncode).toBe(0);
    expect(existsSync(outPath)).toBe(true);
    const parsed = JSON.parse(readFileSync(outPath, "utf8"));
    expect(parsed.mcpServers["open-second-brain"]).toBeDefined();
  });

  test("--out - with --yes writes the snippet first on stdout, no plan header (M15)", async () => {
    // Non-TTY with --yes: no prompt, so the run needs no interactive
    // stdin - and the payload pin holds without one. The apply consent
    // was given, so nothing may prefix the snippet on stdout (the
    // plain-text receipt after it is the apply close's own channel).
    const r = await runCli(["install", "--target", "generic", "--apply", "--yes", "--out", "-"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout.startsWith("{")).toBe(true);
    expect(r.stdout).not.toContain("dry-run");
    expect(r.stdout).not.toContain("— plan");
    expect(r.stdout).toContain('"open-second-brain"');
  });

  test("--format yaml emits YAML to stdout", async () => {
    const r = await runCli(
      ["install", "--target", "generic", "--apply", "--yes", "--out", "-", "--format", "yaml"],
      { env: envBase() },
    );
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("mcpServers:");
  });
});

describe("o2b install --check", () => {
  test("with no installs, exits 0 with 'not-installed' rows", async () => {
    const r = await runCli(["install", "--check"], { env: envBase() });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("not-installed");
  });

  test("after install --apply, reports ok and exits 0", 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");
    // The `ok` is a configuration comparison, and says so: nothing here
    // spoke MCP to Cursor.
    expect(r.stdout).toContain("no MCP handshake attempted");
  });

  test("--check without configured vault exits 2 with vault-not-configured", async () => {
    // Pass an empty/unwritable config + no VAULT_DIR — every adapter would
    // otherwise silently report not-installed against a bogus path.
    const r = await runCli(["install", "--check"], { env: { VAULT_DIR: "" } });
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("vault not configured");
  });

  test("after partial-key drift, exits 3", async () => {
    await runCli(["install", "--target", "cursor", "--apply", "--yes"], { env: envBase() });
    const cfgPath = join(home, ".cursor", "mcp.json");
    const parsed = JSON.parse(readFileSync(cfgPath, "utf8"));
    delete parsed.mcpServers["open-second-brain-writer"];
    writeFileSync(cfgPath, JSON.stringify(parsed, null, 2) + "\n");
    const r = await runCli(["install", "--check", "--target", "cursor"], { env: envBase() });
    expect(r.returncode).toBe(3);
    expect(r.stdout).toContain("drift");
  });

  test("after canonical payload drift, exits 3", async () => {
    await runCli(["install", "--target", "cursor", "--apply", "--yes"], { env: envBase() });
    const cfgPath = join(home, ".cursor", "mcp.json");
    const parsed = JSON.parse(readFileSync(cfgPath, "utf8"));
    parsed.mcpServers["open-second-brain"].command = "TAMPERED";
    writeFileSync(cfgPath, JSON.stringify(parsed, null, 2) + "\n");
    const r = await runCli(["install", "--check", "--target", "cursor"], { env: envBase() });
    expect(r.returncode).toBe(3);
    expect(r.stdout).toContain("canonical payload");
  });
});

function row(status: VerifyResult["status"], target = "unit"): VerifyResult {
  return { target, status, details: [`${target}: ${status}`], fix_hint: null };
}

describe("o2b install --check exit codes distinguish the verify states", () => {
  test("a runtime proved unreachable does not exit 0", () => {
    const code = exitCodeForVerify([row("mcp-unreachable")]);
    expect(code).toBe(INSTALL_EXIT.mcpUnreachable);
    expect(code).not.toBe(INSTALL_EXIT.ok);
  });

  test("unreachable and not-installed are different codes", () => {
    expect(exitCodeForVerify([row("not-installed")])).toBe(INSTALL_EXIT.ok);
    expect(exitCodeForVerify([row("mcp-unreachable")])).not.toBe(
      exitCodeForVerify([row("not-installed")]),
    );
  });

  test("ok alone is success, and drift keeps its historical code", () => {
    expect(exitCodeForVerify([row("ok")])).toBe(INSTALL_EXIT.ok);
    expect(exitCodeForVerify([row("drift")])).toBe(INSTALL_EXIT.drift);
    expect(INSTALL_EXIT.drift).toBe(3);
  });

  test("drift outranks unreachable: the config must be right before liveness means anything", () => {
    expect(exitCodeForVerify([row("mcp-unreachable", "a"), row("drift", "b")])).toBe(
      INSTALL_EXIT.drift,
    );
  });

  test("every exit code is distinct", () => {
    const codes = Object.values(INSTALL_EXIT);
    expect(new Set(codes).size).toBe(codes.length);
  });
});

describe("o2b uninstall --target X", () => {
  test("dry-run prints what would be removed but does nothing", async () => {
    await runCli(["install", "--target", "cursor", "--apply", "--yes"], { env: envBase() });
    const r = await runCli(["uninstall", "--target", "cursor"], { env: envBase() });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("dry-run");
    // file still has OSB keys
    const parsed = JSON.parse(readFileSync(join(home, ".cursor", "mcp.json"), "utf8"));
    expect(parsed.mcpServers["open-second-brain"]).toBeDefined();
  });

  test("--apply removes OSB keys", async () => {
    await runCli(["install", "--target", "cursor", "--apply", "--yes"], { env: envBase() });
    const r = await runCli(["uninstall", "--target", "cursor", "--apply"], { env: envBase() });
    expect(r.returncode).toBe(0);
    const parsed = JSON.parse(readFileSync(join(home, ".cursor", "mcp.json"), "utf8"));
    expect(parsed.mcpServers["open-second-brain"]).toBeUndefined();
    expect(parsed.mcpServers["open-second-brain-writer"]).toBeUndefined();
  });

  test("--target unknown exits 2", async () => {
    const r = await runCli(["uninstall", "--target", "nope", "--apply"], { env: envBase() });
    expect(r.returncode).toBe(2);
  });
});