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.0 KB
Raw Blame
/**
 * The maintenance lane recipe printed by
 * `o2b brain maintenance run --cron-template`.
 *
 * The lane is the cron entry point for the heavy passes, and a scheduler
 * runs it without the operator's shell environment, so the recipe has to
 * carry everything the lane needs on the command line: the vault, and the
 * window and zone when the operator gave them. It also has to keep the
 * lane's exit code - a gate skip exits 0 and should cost a cron mail
 * nothing, while any other exit is a verdict someone must read.
 *
 * Rendering is pure text: the last case lists a vault tree before and
 * after and requires them to be the same.
 */

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

import { CronTemplateError } from "../../src/cli/cron-recipe.ts";
import {
  DEFAULT_MAINTENANCE_INTERVAL,
  MAINTENANCE_CRON_NAME,
  maintenanceCronName,
  parseWindowBounds,
  renderMaintenanceCronTemplate,
} from "../../src/cli/maintenance-cron.ts";
import { IS_WINDOWS } from "../helpers/platform.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);

/** The heredoc body: the script exactly as the operator's host will run it. */
function scriptBody(out: string): string {
  const open = out.indexOf("<<'OSBEOF'\n");
  const close = out.indexOf("\nOSBEOF\n", open);
  expect(open).toBeGreaterThan(-1);
  expect(close).toBeGreaterThan(open);
  return out.slice(open + "<<'OSBEOF'\n".length, close + 1);
}

/** The job name for `vault`, after proving every recipe section carries it. */
function namesIn(vault: string): string {
  const name = maintenanceCronName(vault);
  const cron = renderMaintenanceCronTemplate("1h", { vault });
  const systemd = renderMaintenanceCronTemplate("1h", { vault, format: "systemd" });
  expect(cron).toContain(`cat >~/.local/bin/${name}.sh <<'OSBEOF'`);
  expect(cron).toContain(`  --name ${name} \\`);
  expect(systemd).toContain(`${name}.service`);
  expect(systemd).toContain(`${name}.timer`);
  return name;
}

describe("renderMaintenanceCronTemplate", () => {
  test("names the lane job and renders the hourly default", () => {
    expect(MAINTENANCE_CRON_NAME).toBe("osb-maintenance");
    expect(DEFAULT_MAINTENANCE_INTERVAL).toBe("1h");
    const name = maintenanceCronName("/v");
    expect(name).toMatch(/^osb-maintenance-[0-9a-f]{8}$/u);
    const out = renderMaintenanceCronTemplate("1h", { vault: "/v" });
    expect(out).toContain("# interval: 1 hours");
    expect(out).toContain(`0 */1 * * *    ~/.local/bin/${name}.sh`);
    expect(out).toContain(`cat >~/.local/bin/${name}.sh <<'OSBEOF'`);
    expect(out).toContain(`  --name ${name} \\`);
    expect(out).toContain("(when Hermes owns the schedule)");
  });

  test("the script runs the lane against the baked-in vault as JSON", () => {
    const body = scriptBody(renderMaintenanceCronTemplate("1h", { vault: "/v" }));
    expect(body).toContain("o2b brain maintenance run --vault '/v' --json");
    expect(body).not.toContain("--window");
    expect(body).not.toContain("--tz");
  });

  test("the window and the zone reach the command only when given", () => {
    const both = scriptBody(
      renderMaintenanceCronTemplate("1h", { vault: "/v", window: "3-5", tz: "Europe/Berlin" }),
    );
    expect(both).toContain(
      "o2b brain maintenance run --vault '/v' --window 3-5 --tz Europe/Berlin --json",
    );
    const windowOnly = scriptBody(
      renderMaintenanceCronTemplate("1h", { vault: "/v", window: "22-6" }),
    );
    expect(windowOnly).toContain("o2b brain maintenance run --vault '/v' --window 22-6 --json");
  });

  test("a vault with a single quote stays one shell word", () => {
    const body = scriptBody(renderMaintenanceCronTemplate("1h", { vault: "/srv/it's vault" }));
    expect(body).toContain("--vault '/srv/it'\\''s vault' --json");
  });

  test("a window or zone that is not a plain token is refused, not pasted into shell", () => {
    for (const window of ["25-3", "3-5; rm -rf ~", "3"]) {
      expect(() => renderMaintenanceCronTemplate("1h", { vault: "/v", window })).toThrow(
        CronTemplateError,
      );
    }
    for (const tz of ["$(id)", "--force"]) {
      expect(() => renderMaintenanceCronTemplate("1h", { vault: "/v", window: "3-5", tz })).toThrow(
        CronTemplateError,
      );
    }
  });

  test("a zone the runtime does not know is refused by name", () => {
    expect(() =>
      renderMaintenanceCronTemplate("1h", { vault: "/v", window: "3-5", tz: "Mars/Base" }),
    ).toThrow(/unknown time zone: "Mars\/Base"/u);
    for (const tz of ["Europe/Berlin", "Etc/GMT+3", "UTC"]) {
      expect(renderMaintenanceCronTemplate("1h", { vault: "/v", window: "3-5", tz })).toContain(
        `--tz ${tz} --json`,
      );
    }
  });

  test("a vault path with a line break is refused by name in both formats", () => {
    for (const vault of ["/v\nOSBEOF", "/v\rx"]) {
      for (const format of ["cron", "systemd"] as const) {
        expect(() => renderMaintenanceCronTemplate("1h", { vault, format })).toThrow(
          /vault path must not contain a line break/u,
        );
      }
    }
  });

  test.skipIf(IS_WINDOWS)(
    "the script is silent on exit 0 and passes any other exit through with its JSON",
    () => {
      // Run the rendered script for real against a stub o2b that prints a
      // verdict and exits with the code the case asks for.
      const dir = mkdtempSync(join(tmpdir(), "o2b-maint-cron-run-"));
      try {
        const stub = join(dir, "o2b-stub");
        writeFileSync(stub, '#!/bin/sh\nprintf \'{"x":1}\\n\'\nexit "$STUB_EXIT"\n');
        chmodSync(stub, 0o755);
        const script = join(dir, "run.sh");
        writeFileSync(
          script,
          scriptBody(renderMaintenanceCronTemplate("1h", { vault: "/v", o2bBin: stub })),
        );
        const run = (code: string) =>
          Bun.spawnSync(["bash", script], {
            env: { PATH: process.env["PATH"] ?? "", HOME: dir, STUB_EXIT: code },
          });
        const quiet = run("0");
        expect(quiet.exitCode).toBe(0);
        expect(quiet.stdout.toString()).toBe("");
        const failed = run("3");
        expect(failed.exitCode).toBe(3);
        expect(failed.stdout.toString()).toBe('{"x":1}\n');
      } finally {
        rmSync(dir, { recursive: true, force: true });
      }
    },
  );

  test("the verify footer points at the lane status of the baked-in vault", () => {
    const out = renderMaintenanceCronTemplate("1h", { vault: "/srv/it's vault" });
    expect(out).toContain(
      "# After install, verify with: o2b brain maintenance status --vault '/srv/it'\\''s vault'",
    );
  });

  test("the binary override reaches the script and the footer", () => {
    const out = renderMaintenanceCronTemplate("1h", { vault: "/v", o2bBin: "/opt/o2b" });
    expect(out).toContain("/opt/o2b brain maintenance run --vault '/v' --json");
    expect(out).toContain(
      "# After install, verify with: /opt/o2b brain maintenance status --vault '/v'",
    );
  });

  test("two vaults get different job names; the same vault always gets the same one", () => {
    expect(namesIn("/a")).not.toBe(namesIn("/b"));
    expect(namesIn("/a")).toBe(namesIn("/a"));
    expect(renderMaintenanceCronTemplate("1h", { vault: "/a" })).toBe(
      renderMaintenanceCronTemplate("1h", { vault: "/a" }),
    );
  });

  test("an explicit cron format renders the default recipe", () => {
    expect(renderMaintenanceCronTemplate("1h", { vault: "/v", format: "cron" })).toBe(
      renderMaintenanceCronTemplate("1h", { vault: "/v" }),
    );
  });

  test("the systemd format prints a timer on the same cadence with the same script", () => {
    const cron = renderMaintenanceCronTemplate("1h", { vault: "/v" });
    const systemd = renderMaintenanceCronTemplate("1h", { vault: "/v", format: "systemd" });
    expect(systemd).toContain("OnUnitActiveSec=1h");
    expect(systemd).toContain(`systemctl --user enable --now ${maintenanceCronName("/v")}.timer`);
    expect(systemd).not.toContain("hermes cron create");
    expect(scriptBody(systemd)).toBe(scriptBody(cron));
  });

  test("an interval cron cannot express is refused", () => {
    expect(() => renderMaintenanceCronTemplate("30s", { vault: "/v" })).toThrow(CronTemplateError);
    expect(() => renderMaintenanceCronTemplate("90d", { vault: "/v", format: "systemd" })).toThrow(
      CronTemplateError,
    );
  });
});

/** Every path under `root`, recursively, as a sorted list. */
function listTree(root: string): string[] {
  const out: string[] = [];
  const walk = (dir: string, prefix: string): void => {
    for (const entry of readdirSync(dir, { withFileTypes: true })) {
      const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
      out.push(rel);
      if (entry.isDirectory()) walk(join(dir, entry.name), rel);
    }
  };
  walk(root, "");
  return out.toSorted();
}

describe("parseWindowBounds", () => {
  test("reads H-H bounds and refuses any other shape or an hour above 23", () => {
    expect(parseWindowBounds("22-6")).toEqual({ startHour: 22, endHour: 6 });
    expect(parseWindowBounds("0-23")).toEqual({ startHour: 0, endHour: 23 });
    for (const raw of ["24-3", "3-24", "3", "3-5x", " 3-5", "a-b"]) {
      expect(parseWindowBounds(raw)).toBeNull();
    }
  });
});

describe("rendering writes nothing", () => {
  let tmp: string;

  beforeEach(() => {
    tmp = mkdtempSync(join(tmpdir(), "o2b-maintenance-cron-"));
  });

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

  test("a vault tree is unchanged by both formats", () => {
    const vault = join(tmp, "vault");
    mkdirSync(join(vault, "Brain"), { recursive: true });
    writeFileSync(join(vault, "Brain", "note.md"), "# note\n");
    const before = listTree(tmp);
    renderMaintenanceCronTemplate("1h", { vault });
    renderMaintenanceCronTemplate("6h", { vault, format: "systemd" });
    expect(listTree(tmp)).toEqual(before);
  });
});