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
10.7 KB
Raw Blame
/**
 * `scripts/sync-plugin-mirrors.ts` - the Codex plugin ships real files, not
 * symlinks, and they stay byte-identical to their sources.
 *
 * Codex copies only `plugins/codex/` into its plugin cache and drops
 * symlinks on the way, so a symlinked `hooks` or `skills` dir there reached
 * users as nothing at all.
 */

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

import {
  CODEX_SESSION_END_TIMEOUT_CAP_SEC,
  codexHooksJson,
  codexWindowsHookCommand,
  findDrift,
  REPO_BLOB_URL,
  REPO_RAW_URL,
  withAbsoluteLinks,
  writeMirrors,
} from "../../scripts/sync-plugin-mirrors.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);

const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");

type HookGroups = Array<{ hooks: Array<{ command: string; commandWindows?: string }> }>;

describe("the repository", () => {
  test("the Codex plugin mirrors are in sync with their sources", () => {
    expect(findDrift(REPO_ROOT)).toEqual([]);
  });

  test("no plugin directory tracks a symlink", () => {
    // Mode 120000 is a symlink in the git index. Checked in the index rather
    // than on disk because a Windows checkout without `core.symlinks`
    // materialises one as a plain file, which the disk check cannot tell apart.
    const r = spawnSync("git", ["ls-files", "-s", "--", "plugins", ".agents"], {
      cwd: REPO_ROOT,
      encoding: "utf8",
    });
    if (r.status !== 0) return; // not a git checkout (a packed tarball)
    const links = r.stdout.split("\n").filter((line) => line.startsWith("120000 "));
    expect(links).toEqual([]);
  });

  test("the Codex hooks mirror carries hooks.json only, never the hook scripts", () => {
    // Codex exports CLAUDE_PLUGIN_ROOT as its cache dir; a `.ts` hook there
    // would win `o2b-hook`'s resolution and then fail on `../src` imports.
    const hooksJson = join(REPO_ROOT, "plugins/codex/hooks/hooks.json");
    expect(existsSync(hooksJson)).toBe(true);
    expect(existsSync(join(REPO_ROOT, "plugins/codex/hooks/active-inject.ts"))).toBe(false);
  });
});

describe("the Codex hooks.json", () => {
  test("caps SessionEnd timeouts at the Codex limit and leaves everything else alone", () => {
    const source = readFileSync(join(REPO_ROOT, "hooks/hooks.json"), "utf8");
    const src = JSON.parse(source);
    const out = JSON.parse(codexHooksJson(source));

    const sessionEnd = out.hooks.SessionEnd.flatMap((g: { hooks: unknown[] }) => g.hooks);
    expect(sessionEnd.length).toBeGreaterThan(0);
    for (const hook of sessionEnd) {
      expect(hook.timeout).toBeLessThanOrEqual(CODEX_SESSION_END_TIMEOUT_CAP_SEC);
    }

    // Apart from those timeouts and the added Windows commands, the Codex
    // copy is the shared file.
    for (const group of src.hooks.SessionEnd) {
      for (const hook of group.hooks)
        hook.timeout = Math.min(hook.timeout, CODEX_SESSION_END_TIMEOUT_CAP_SEC);
    }
    for (const groups of Object.values(out.hooks) as HookGroups[]) {
      for (const group of groups) {
        for (const hook of group.hooks) delete hook.commandWindows;
      }
    }
    expect(out).toEqual(src);
  });

  test("gives every hook a cmd.exe form that runs the same o2b-hook", () => {
    // On Windows Codex runs `%COMSPEC% /C "<command>"`, which cannot parse
    // the POSIX command, unless the hook carries `commandWindows`.
    const source = readFileSync(join(REPO_ROOT, "hooks/hooks.json"), "utf8");
    const out = JSON.parse(codexHooksJson(source));
    let count = 0;
    for (const groups of Object.values(out.hooks) as HookGroups[]) {
      for (const group of groups) {
        for (const hook of group.hooks) {
          const name = /exec o2b-hook ([a-z0-9-]+); exit 0$/.exec(hook.command)?.[1];
          expect(name).toBeDefined();
          expect(hook.commandWindows).toBe(codexWindowsHookCommand(name!));
          const keys = Object.keys(hook);
          expect(keys.indexOf("commandWindows")).toBe(keys.indexOf("command") + 1);
          count++;
        }
      }
    }
    expect(count).toBeGreaterThan(0);
  });

  test("the cmd.exe form never looks in the current directory and never blocks", () => {
    const cmd = codexWindowsHookCommand("session-capture");
    // Set before the first bare command name, so neither `where` nor
    // `o2b-hook` resolves from the project Codex opened.
    expect(cmd.startsWith("set NoDefaultCurrentDirectoryInExePath=1&")).toBe(true);
    // A bare `where` searches the current directory; `$PATH:` does not.
    expect(cmd).toContain("where /q $PATH:o2b-hook && o2b-hook session-capture");
    expect(cmd.endsWith("& exit /b 0")).toBe(true);
    // Codex wraps the line in one pair of quotes, which cmd.exe strips
    // cleanly only while the line holds no other quote; a `%` would expand.
    expect(cmd).not.toMatch(/["%]/);
  });

  test("refuses a hook command whose Windows form it cannot derive", () => {
    const source = JSON.stringify({
      hooks: { Stop: [{ hooks: [{ type: "command", command: "echo hi", timeout: 5 }] }] },
    });
    expect(() => codexHooksJson(source)).toThrow(/cannot derive its Windows form/);
  });

  test("keeps the source's formatting, so the mirror passes fmt:check", () => {
    // With the timeouts already within the cap, everything but the added
    // commandWindows lines is the source, byte for byte.
    const source = readFileSync(join(REPO_ROOT, "hooks/hooks.json"), "utf8").replace(
      /"timeout": 10/g,
      '"timeout": 2',
    );
    const out = codexHooksJson(source)
      .split("\n")
      .filter((line) => !line.trimStart().startsWith('"commandWindows": '))
      .join("\n");
    expect(out).toBe(source);
  });
});

describe("the Codex copies of the root documents", () => {
  test("the plugin subtree carries its own license, readme, security policy and ignore list", () => {
    for (const name of ["LICENSE", "README.md", "SECURITY.md", ".codexignore"]) {
      expect(existsSync(join(REPO_ROOT, "plugins/codex", name))).toBe(true);
    }
    expect(readFileSync(join(REPO_ROOT, "plugins/codex/LICENSE"))).toEqual(
      readFileSync(join(REPO_ROOT, "LICENSE")),
    );
  });

  test("relative links and images become absolute; URLs, anchors and mail stay as they are", () => {
    const source = [
      "![poster](docs/images/poster.jpg)",
      "See [the guide](./install/codex.md) and [`install/`](install/).",
      "[CLI](docs/cli-reference.md#knowledge-packs) [site](https://obsidian.md)",
      "[top](#what-is-new) [mail](mailto:[email protected]) [root](/abs)",
    ].join("\n");
    expect(withAbsoluteLinks(source)).toBe(
      [
        `![poster](${REPO_RAW_URL}/docs/images/poster.jpg)`,
        `See [the guide](${REPO_BLOB_URL}/install/codex.md) and [\`install/\`](${REPO_BLOB_URL}/install/).`,
        `[CLI](${REPO_BLOB_URL}/docs/cli-reference.md#knowledge-packs) [site](https://obsidian.md)`,
        "[top](#what-is-new) [mail](mailto:[email protected]) [root](/abs)",
      ].join("\n"),
    );
  });
});

describe("drift detection", () => {
  let root: string;

  beforeEach(() => {
    root = mkdtempSync(join(tmpdir(), "osb-plugin-mirrors-"));
    mkdirSync(join(root, "skills/alpha"), { recursive: true });
    writeFileSync(join(root, "skills/alpha/SKILL.md"), "alpha\n");
    mkdirSync(join(root, "hooks"), { recursive: true });
    writeFileSync(join(root, "hooks/hooks.json"), '{"hooks":{}}\n');
    writeFileSync(join(root, "hooks/active-inject.ts"), "// not mirrored\n");
    writeFileSync(join(root, "LICENSE"), "license\n");
    writeFileSync(join(root, ".codexignore"), ".env\n");
    writeFileSync(join(root, "README.md"), "# readme\n");
    writeFileSync(join(root, "SECURITY.md"), "# security\n");
  });

  afterEach(() => {
    rmSync(root, { recursive: true, force: true });
  });

  test("a fresh write is clean, and copies only what the specs name", () => {
    expect(writeMirrors(root)).toBe(6);
    expect(findDrift(root)).toEqual([]);
    expect(readFileSync(join(root, "plugins/codex/skills/alpha/SKILL.md"), "utf8")).toBe("alpha\n");
    expect(existsSync(join(root, "plugins/codex/hooks/active-inject.ts"))).toBe(false);
  });

  test("a missing, a changed and an extra file are each reported", () => {
    writeMirrors(root);
    writeFileSync(join(root, "skills/alpha/SKILL.md"), "alpha, edited\n");
    mkdirSync(join(root, "skills/beta"));
    writeFileSync(join(root, "skills/beta/SKILL.md"), "beta\n");
    writeFileSync(join(root, "plugins/codex/skills/stale.md"), "gone upstream\n");

    expect(findDrift(root)).toEqual([
      { path: "plugins/codex/skills/stale.md", reason: "extra" },
      { path: "plugins/codex/skills/alpha/SKILL.md", reason: "differs" },
      { path: "plugins/codex/skills/beta/SKILL.md", reason: "missing" },
    ]);

    writeMirrors(root);
    expect(findDrift(root)).toEqual([]);
    expect(existsSync(join(root, "plugins/codex/skills/stale.md"))).toBe(false);
  });

  test.skipIf(process.platform === "win32")(
    "a symlinked mirror dir is drift, and a write replaces it with real files",
    () => {
      mkdirSync(join(root, "plugins/codex"), { recursive: true });
      symlinkSync("../../skills", join(root, "plugins/codex/skills"));
      symlinkSync("../../hooks", join(root, "plugins/codex/hooks"));

      expect(findDrift(root)).toEqual([
        { path: "plugins/codex/skills", reason: "symlink" },
        { path: "plugins/codex/hooks", reason: "symlink" },
        // The single-file mirrors were never written in this fixture.
        { path: "plugins/codex/LICENSE", reason: "missing" },
        { path: "plugins/codex/.codexignore", reason: "missing" },
        { path: "plugins/codex/README.md", reason: "missing" },
        { path: "plugins/codex/SECURITY.md", reason: "missing" },
      ]);

      writeMirrors(root);
      expect(findDrift(root)).toEqual([]);
      expect(existsSync(join(root, "hooks/active-inject.ts"))).toBe(true);
    },
  );

  test.skipIf(process.platform === "win32")(
    "a symlinked single-file mirror is drift, and a write replaces it with a real file",
    () => {
      writeMirrors(root);
      rmSync(join(root, "plugins/codex/LICENSE"));
      symlinkSync("../../LICENSE", join(root, "plugins/codex/LICENSE"));

      expect(findDrift(root)).toEqual([{ path: "plugins/codex/LICENSE", reason: "symlink" }]);

      writeMirrors(root);
      expect(findDrift(root)).toEqual([]);
      expect(lstatSync(join(root, "plugins/codex/LICENSE")).isSymbolicLink()).toBe(false);
    },
  );
});