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
13.8 KB
Raw Blame
/**
 * Spawn tests for hooks/pretool-host-backup.ts - the opt-in PreToolUse
 * host-settings backup hook (t_f4555087). Four behavioral cases; the
 * path/collision combinatorics live in the pure-layer suite
 * (tests/core/brain/pretool-host-backup.test.ts).
 *
 * Spawn pattern shared with tests/hooks/pretool-orient.test.ts: each
 * case spawns the hook with a JSON payload on stdin and a per-case temp
 * HOME, then asserts stdout shape and on-disk effects.
 */

import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  statSync,
  symlinkSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { homeEnv, IS_WINDOWS } from "../helpers/platform.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

const HOOK = resolve(
  dirname(fileURLToPath(import.meta.url)),
  "..",
  "..",
  "hooks",
  "pretool-host-backup.ts",
);

setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

let vault: string;
let configHome: string;
let home: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "osb-hook-hb-vault-"));
  // An unswitched vault: its Brain/ tree is the legacy layout under test.
  mkdirSync(join(vault, "Brain"), { recursive: true });
  configHome = mkdtempSync(join(tmpdir(), "osb-hook-hb-cfg-"));
  home = mkdtempSync(join(tmpdir(), "osb-hook-hb-home-"));
  mkdirSync(join(home, ".claude"), { recursive: true });
  writeFileSync(join(home, ".claude", "settings.json"), '{"theme":"dark"}\n');
});

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

interface RunResult {
  readonly stdout: string;
  readonly stderr: string;
  readonly exit: number;
}

async function runHook(payload: unknown, env: Record<string, string> = {}): Promise<RunResult> {
  const inherited: Record<string, string> = {
    PATH: process.env["PATH"] ?? "",
    ...homeEnv(configHome),
    OPEN_SECOND_BRAIN_VAULT: vault,
  };
  const proc = Bun.spawn(["bun", "run", HOOK], {
    stdin: "pipe",
    stdout: "pipe",
    stderr: "pipe",
    env: { ...inherited, ...env },
  });
  proc.stdin.write(JSON.stringify(payload));
  await proc.stdin.end();
  const [stdout, stderr] = await Promise.all([
    new Response(proc.stdout).text(),
    new Response(proc.stderr).text(),
  ]);
  const exit = await proc.exited;
  return { stdout, stderr, exit };
}

function writePayload(filePath: string): Record<string, unknown> {
  return {
    hook_event_name: "PreToolUse",
    session_id: "s1",
    cwd: home,
    tool_use_id: "tu1",
    tool_name: "Write",
    tool_input: { file_path: filePath },
  };
}

function applyPatchPayload(patchBody: string): unknown {
  return {
    hook_event_name: "PreToolUse",
    session_id: "s1",
    cwd: home,
    tool_use_id: "tu1",
    tool_name: "apply_patch",
    tool_input: { input: patchBody },
  };
}

function auditRecords(from: string = vault): Array<Record<string, unknown>> {
  const dir = join(from, ".open-second-brain", "hook-audit");
  if (!existsSync(dir)) return [];
  const records: Array<Record<string, unknown>> = [];
  for (const file of readdirSync(dir)) {
    for (const line of readFileSync(join(dir, file), "utf8").split("\n")) {
      if (line.trim().length > 0) records.push(JSON.parse(line) as Record<string, unknown>);
    }
  }
  return records;
}

describe("pretool-host-backup hook", () => {
  test("flag off: a settings-targeting Write is a byte-identical no-op (exit 0, no output, no ceiling work)", async () => {
    const r = await runHook(writePayload(join(home, ".claude", "settings.json")));
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
    // Nothing backed up, nothing receipted.
    expect(existsSync(join(home, ".claude", ".o2b-backups"))).toBe(false);
    expect(auditRecords()).toEqual([]);
    // The settings file itself is untouched (the hook never writes it).
    expect(readFileSync(join(home, ".claude", "settings.json"), "utf8")).toBe('{"theme":"dark"}\n');
  });

  test("flag on: a Write to the settings file produces a backup, one receipt, and no deny", async () => {
    const r = await runHook(writePayload(join(home, ".claude", "settings.json")), {
      OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP: "true",
    });
    expect(r.exit).toBe(0);
    // No deny on the only channel that survives the fail-soft dispatcher.
    expect(r.stdout).not.toContain('"deny"');
    const backupRoot = join(home, ".claude", ".o2b-backups", "settings.json");
    expect(existsSync(backupRoot)).toBe(true);
    const backups = readdirSync(backupRoot);
    expect(backups.length).toBe(1);
    expect(readFileSync(join(backupRoot, backups[0]!), "utf8")).toBe('{"theme":"dark"}\n');
    // Exactly one receipt line carrying the trust receipt head.
    const records = auditRecords();
    expect(records.length).toBe(1);
    const record = records[0] as {
      actor: string;
      ok: boolean;
      target: string;
      details: Record<string, unknown>;
    };
    expect(record.actor).toContain("hook:");
    expect(record.ok).toBe(true);
    expect(record.target).toBe(join(home, ".claude", "settings.json"));
    expect(record.details["before_hash"]).toMatch(/^sha256:[0-9a-f]{64}$/);
    // The receipt records the spawned hook process, not this test.
    expect(typeof record.details["pid"]).toBe("number");
    expect(String(record.details["summary"])).toContain("settings.json");
    expect(record.details["backup"]).toBe(join(backupRoot, backups[0]!));
  });

  test.skipIf(IS_WINDOWS)(
    "flag on: the wrapper twin's backup is private 0600, same as the canonical core",
    async () => {
      const r = await runHook(writePayload(join(home, ".claude", "settings.json")), {
        OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP: "true",
      });
      expect(r.exit).toBe(0);
      const backupRoot = join(home, ".claude", ".o2b-backups", "settings.json");
      const backups = readdirSync(backupRoot);
      expect(backups.length).toBe(1);
      expect(statSync(join(backupRoot, backups[0]!)).mode & 0o777).toBe(0o600);
    },
  );

  test("flag on: a Write that CREATES a missing settings file is a silent allow (twin's allow-no-source)", async () => {
    // The canonical twin allows a missing source ("nothing to protect",
    // tests/core/brain/pretool-host-backup.test.ts): a fresh
    // settings.local.json must be creatable with the flag on, not denied
    // for having no prior bytes to back up.
    const target = join(home, ".claude", "settings.local.json");
    expect(existsSync(target)).toBe(false);
    const r = await runHook(writePayload(target), {
      OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP: "true",
    });
    expect(r.exit).toBe(0);
    expect(r.stdout).not.toContain('"deny"');
    // Nothing existed to back up: no backup folder, no receipt.
    expect(existsSync(join(home, ".claude", ".o2b-backups"))).toBe(false);
    expect(auditRecords()).toEqual([]);
  });

  test("flag on: a '#' inside a quoted config value does not truncate the receipt vault", async () => {
    const configVault = mkdtempSync(join(tmpdir(), "osb-hook-hb-cfgvault-"));
    // An unswitched vault: its Brain/ tree is the legacy layout under test.
    mkdirSync(join(configVault, "brain#main", "Brain"), { recursive: true });
    writeFileSync(
      join(configHome, "config.yaml"),
      `host_settings_backup: true\nvault: "${join(configVault, "brain#main")}"\n`,
    );
    try {
      const r = await runHook(writePayload(join(home, ".claude", "settings.json")), {
        OPEN_SECOND_BRAIN_VAULT: "", // vault comes from the config, not the env
        OPEN_SECOND_BRAIN_CONFIG: join(configHome, "config.yaml"),
      });
      expect(r.exit).toBe(0);
      expect(r.stdout).not.toContain('"deny"');
      expect(existsSync(join(home, ".claude", ".o2b-backups"))).toBe(true);
      // The receipt lands under the FULL quoted path, hash included - not
      // under a value truncated at the `#` as if it began a YAML comment.
      const records = auditRecords(join(configVault, "brain#main"));
      expect(records.length).toBe(1);
      expect(records[0]!["action"]).toBe("host-settings-backup");
    } finally {
      rmSync(configVault, { recursive: true, force: true });
    }
  });

  test("flag on with a backup made to fail emits a stdout deny naming the path", async () => {
    // A FILE where the backup folder must be makes the backup impossible.
    writeFileSync(join(home, ".claude", ".o2b-backups"), "not a dir\n");
    const target = join(home, ".claude", "settings.json");
    const r = await runHook(writePayload(target), {
      OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP: "true",
    });
    expect(r.exit).toBe(0); // the dispatcher contract: the deny rides stdout
    expect(r.stdout).toContain('"permissionDecision":"deny"');
    // The deny names the target. Stdout is JSON, and on Windows the
    // path's separators arrive JSON-escaped (`\\`), so match the PARSED
    // reason, not the raw bytes.
    const decision = JSON.parse(r.stdout) as {
      hookSpecificOutput: { permissionDecision: string; permissionDecisionReason: string };
    };
    expect(decision.hookSpecificOutput.permissionDecision).toBe("deny");
    expect(decision.hookSpecificOutput.permissionDecisionReason).toContain(target);
    // The settings file was not touched by the hook.
    expect(readFileSync(target, "utf8")).toBe('{"theme":"dark"}\n');
  });

  test("flag on without a vault skips the receipt but still backs up", async () => {
    const r = await runHook(writePayload(join(home, ".claude", "settings.json")), {
      OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP: "true",
      OPEN_SECOND_BRAIN_VAULT: "", // no vault resolved
    });
    expect(r.exit).toBe(0);
    expect(r.stdout).not.toContain('"deny"');
    const backupRoot = join(home, ".claude", ".o2b-backups", "settings.json");
    expect(existsSync(backupRoot)).toBe(true);
    // A missing vault degrades the receipt, never the backup or the call.
    expect(auditRecords()).toEqual([]);
  });

  test("flag on: an apply_patch Update File on a protected path backs up (Codex lane)", async () => {
    const target = join(home, ".claude", "settings.json");
    const r = await runHook(
      applyPatchPayload("*** Begin Patch\n*** Update File: " + target + "\n@@\n- old\n+ new\n"),
      { OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP: "true" },
    );
    expect(r.exit).toBe(0);
    expect(r.stdout).not.toContain('"deny"');
    const backupRoot = join(home, ".claude", ".o2b-backups", "settings.json");
    const backups = readdirSync(backupRoot);
    expect(backups.length).toBe(1);
    expect(readFileSync(join(backupRoot, backups[0]!), "utf8")).toBe('{"theme":"dark"}\n');
    const records = auditRecords();
    expect(records.length).toBe(1);
    expect((records[0] as { target: string }).target).toBe(target);
  });

  test("flag on: an apply_patch patch with several targets backs up each protected one", async () => {
    const local = join(home, ".claude", "settings.local.json");
    writeFileSync(local, '{"allow":["Bash"]}\n');
    const notes = join(home, "notes.md");
    writeFileSync(notes, "x\n");
    const r = await runHook(
      applyPatchPayload(
        "*** Begin Patch\n" +
          "*** Add File: " +
          notes +
          "\n+hello\n" +
          "*** Update File: " +
          join(home, ".claude", "settings.json") +
          "\n@@\n" +
          "*** Delete File: " +
          local +
          "\n",
      ),
      { OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP: "true" },
    );
    expect(r.exit).toBe(0);
    expect(r.stdout).not.toContain('"deny"');
    const backupRoot = join(home, ".claude", ".o2b-backups");
    // One folder per protected file name; notes.md has none. The
    // `*`-ignore marker (git hygiene) sits beside the folders.
    expect(readdirSync(backupRoot).toSorted()).toEqual([
      ".gitignore",
      "settings.json",
      "settings.local.json",
    ]);
    // Exactly one receipt per protected target, none for notes.md.
    expect(auditRecords().length).toBe(2);
  });

  test.skipIf(IS_WINDOWS)(
    "flag on: a settings file that is itself a symlink is backed up through the link",
    async () => {
      const dotfiles = join(home, "dotfiles");
      mkdirSync(dotfiles, { recursive: true });
      const real = join(dotfiles, "claude-settings.json");
      writeFileSync(real, '{"theme":"stow"}\n');
      const target = join(home, ".claude", "settings.json");
      rmSync(target);
      symlinkSync(real, target);

      const r = await runHook(writePayload(target), {
        OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP: "true",
      });
      expect(r.exit).toBe(0);
      expect(r.stdout).not.toContain('"deny"');
      // The backup lands beside the path the agent writes through, and
      // holds the real bytes (read through the link).
      const backupRoot = join(home, ".claude", ".o2b-backups", "settings.json");
      const backups = readdirSync(backupRoot);
      expect(backups.length).toBe(1);
      expect(readFileSync(join(backupRoot, backups[0]!), "utf8")).toBe('{"theme":"stow"}\n');
    },
  );

  test("flag on: the first project backup drops a *-ignore into the backups root", async () => {
    const proj = join(home, "proj");
    mkdirSync(join(proj, ".claude"), { recursive: true });
    const local = join(proj, ".claude", "settings.local.json");
    writeFileSync(local, '{"allow":["Bash"]}\n');
    const payload = { ...writePayload(local), cwd: proj };
    const r = await runHook(payload, { OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP: "true" });
    expect(r.exit).toBe(0);
    expect(r.stdout).not.toContain('"deny"');
    const ignorePath = join(proj, ".claude", ".o2b-backups", ".gitignore");
    expect(existsSync(ignorePath)).toBe(true);
    const text = readFileSync(ignorePath, "utf8");
    expect(text).toContain("*");
    expect(text).toContain("!.gitignore");
  });
});