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
/**
* The shared cron-recipe kernel, exercised through a synthetic spec.
*
* Both real consumers pin their own rendered output, which proves what
* they render but not what the kernel guarantees to ANY consumer. This
* file renders a spec made of sentinels that appear nowhere else, so it
* can assert two things the fixtures cannot:
*
* - every field of the spec actually reaches the output, and reaches it
* in exactly one place - the script is written once, the cron job is
* named once, the verification is stated once;
* - every numbered section and the scheduler line are present, so a
* future recipe cannot quietly lose one. A recipe missing its crontab
* section still looks like a recipe.
*/
import { describe, expect, test } from "bun:test";
import {
CronTemplateError,
operatorScriptPath,
parseRecipeFormat,
RECIPE_FORMATS,
renderCronRecipe,
renderSystemdTimer,
shellWord,
type CronRecipeSpec,
} from "../../src/cli/cron-recipe.ts";
/** Sentinels chosen so no two are a substring of another. */
const SENTINEL = Object.freeze({
title: "Synthetic Suite - probe recipe",
cronName: "probe-job",
scriptStem: "probe-runner",
note: "probe note line",
schedulerNote: "(probe scheduler note)",
bodyMarker: "probe_body_marker",
verify: "probe-verify --now",
});
const SPEC: CronRecipeSpec = Object.freeze<CronRecipeSpec>({
title: SENTINEL.title,
cronName: SENTINEL.cronName,
scriptPath: operatorScriptPath(SENTINEL.scriptStem),
scriptNotes: Object.freeze([SENTINEL.note]),
schedulerNote: SENTINEL.schedulerNote,
buildScriptBody: ({ o2bBin }) => `#!/usr/bin/env bash\n${SENTINEL.bodyMarker} ${o2bBin}\n`,
buildVerifyCommand: ({ o2bBin }) => `${o2bBin} ${SENTINEL.verify}`,
});
const SCRIPT_PATH = operatorScriptPath(SENTINEL.scriptStem);
function occurrences(haystack: string, needle: string): number {
return haystack.split(needle).length - 1;
}
describe("renderCronRecipe", () => {
test("every spec field reaches the output", () => {
const out = renderCronRecipe(SPEC, "30m", {});
for (const value of [
SENTINEL.title,
SENTINEL.cronName,
SCRIPT_PATH,
SENTINEL.note,
SENTINEL.schedulerNote,
SENTINEL.bodyMarker,
SENTINEL.verify,
]) {
expect(`${value} present: ${out.includes(value)}`).toBe(`${value} present: true`);
}
});
test("the cron job is named once, the script written once, the verify stated once", () => {
const out = renderCronRecipe(SPEC, "30m", {});
// The job name appears only where the scheduler is told it.
expect(occurrences(out, SENTINEL.cronName)).toBe(1);
// The script path appears in four places by design (section heading,
// heredoc, chmod, crontab line) but is CREATED exactly once - a second
// heredoc would silently overwrite the first.
expect(occurrences(out, `cat >${SCRIPT_PATH} <<`)).toBe(1);
expect(occurrences(out, SENTINEL.verify)).toBe(1);
});
test("every numbered section and the scheduler line are present", () => {
const out = renderCronRecipe(SPEC, "30m", {});
for (const section of [
"## 1. Watchdog script - save to ",
"## 2. Native crontab - open 'crontab -e' and append:",
"## 3. Hermes cron ",
]) {
expect(`${section} present: ${out.includes(section)}`).toBe(`${section} present: true`);
}
expect(out).toContain("hermes cron create \\");
expect(out).toContain(` --name ${SENTINEL.cronName} \\`);
expect(out).toContain(" --no-agent");
expect(out).toContain("# After install, verify with: ");
});
test("the interval is rendered as cron in both the crontab and the scheduler line", () => {
const out = renderCronRecipe(SPEC, "6h", {});
expect(out).toContain("# interval: 6 hours");
expect(out).toContain(`0 */6 * * * ${SCRIPT_PATH}`);
expect(out).toContain(" --schedule '0 */6 * * *' \\");
});
test("the scheduler command uses the $HOME form the shell will expand", () => {
// A quoted "~/..." argument is not tilde-expanded, so the scheduler
// would store a path that resolves to nothing.
const out = renderCronRecipe(SPEC, "30m", {});
expect(out).toContain(` --command "$HOME/.local/bin/${SENTINEL.scriptStem}.sh" \\`);
expect(out).not.toContain(` --command "~/`);
});
test("the binary override reaches both builders", () => {
const out = renderCronRecipe(SPEC, "30m", { o2bBin: "/opt/probe/o2b" });
expect(out).toContain(`${SENTINEL.bodyMarker} /opt/probe/o2b`);
expect(out).toContain(`# After install, verify with: /opt/probe/o2b ${SENTINEL.verify}`);
});
test("an interval cron cannot express is refused, not rounded", () => {
expect(() => renderCronRecipe(SPEC, "90m", {})).toThrow(CronTemplateError);
expect(() => renderCronRecipe(SPEC, "nonsense", {})).toThrow(CronTemplateError);
});
});
/**
* The synthetic spec rendered at 30m, captured BEFORE the header and the
* script section were extracted into a helper shared with the systemd
* renderer. The extraction is only correct if the cron path changed by
* zero bytes, and only a pinned string can say so.
*/
const PINNED_CRON_30M =
"# ----------------------------------------------------------------------\n# Synthetic Suite - probe recipe\n# interval: 30 minutes\n#\n# Pick ONE of the three paths below. The watchdog script is the\n# common piece; both crontab and Hermes-cron rely on it.\n# ----------------------------------------------------------------------\n\n\n## 1. Watchdog script - save to ~/.local/bin/probe-runner.sh\n## probe note line\n\ncat >~/.local/bin/probe-runner.sh <<'OSBEOF'\n#!/usr/bin/env bash\nprobe_body_marker o2b\nOSBEOF\nchmod +x ~/.local/bin/probe-runner.sh\n\n\n## 2. Native crontab - open 'crontab -e' and append:\n\n*/30 * * * * ~/.local/bin/probe-runner.sh\n\n\n## 3. Hermes cron (probe scheduler note):\n\nhermes cron create \\\n --name probe-job \\\n --schedule '*/30 * * * *' \\\n --command \"$HOME/.local/bin/probe-runner.sh\" \\\n --no-agent\n\n\n# ----------------------------------------------------------------------\n# After install, verify with: o2b probe-verify --now\n# ----------------------------------------------------------------------\n";
/** The watchdog section: from its heading through the chmod that closes it. */
function scriptSection(out: string): string {
const start = out.indexOf("## 1. Watchdog script - save to ");
const chmod = out.indexOf("chmod +x ", start);
const end = out.indexOf("\n", chmod) + 1;
expect(start).toBeGreaterThan(-1);
expect(chmod).toBeGreaterThan(start);
return out.slice(start, end);
}
/** The message a throwing render produced, so two renderers can be compared. */
function refusal(render: () => string): string {
try {
render();
} catch (err) {
expect(err).toBeInstanceOf(CronTemplateError);
return (err as Error).message;
}
throw new Error("expected a CronTemplateError, got a rendered recipe");
}
describe("renderCronRecipe is unchanged by the systemd sibling", () => {
test("the synthetic spec renders byte for byte as before the extraction", () => {
expect(renderCronRecipe(SPEC, "30m", {})).toBe(PINNED_CRON_30M);
});
});
describe("renderSystemdTimer", () => {
const UNIT_DIR = "~/.config/systemd/user/";
test("carries the same script section as the cron recipe", () => {
const systemd = renderSystemdTimer(SPEC, "30m", {});
expect(scriptSection(systemd)).toBe(scriptSection(renderCronRecipe(SPEC, "30m", {})));
});
test("names the service and timer pair and the commands that enable it", () => {
const out = renderSystemdTimer(SPEC, "30m", {});
for (const needle of [
`${UNIT_DIR}${SENTINEL.cronName}.service`,
`${UNIT_DIR}${SENTINEL.cronName}.timer`,
"OnUnitActiveSec=30m",
"OnBootSec=",
"systemctl --user daemon-reload",
`systemctl --user enable --now ${SENTINEL.cronName}.timer`,
"loginctl enable-linger",
`# After install, verify with: o2b ${SENTINEL.verify}`,
]) {
expect(`${needle} present: ${out.includes(needle)}`).toBe(`${needle} present: true`);
}
});
test("the monotonic timer carries no Persistent= line", () => {
// systemd honours Persistent= on OnCalendar= timers only; on this
// OnBootSec=/OnUnitActiveSec= timer it would claim a catch-up that
// never happens.
expect(renderSystemdTimer(SPEC, "30m", {})).not.toContain("Persistent=");
});
test("the service runs the script through the systemd home specifier", () => {
// ExecStart= does not expand a tilde, so the path must reach systemd in
// the %h form it resolves itself.
const out = renderSystemdTimer(SPEC, "30m", {});
expect(out).toContain(`ExecStart=%h/.local/bin/${SENTINEL.scriptStem}.sh`);
expect(out).not.toContain("ExecStart=~/");
});
test("prints no crontab line and no Hermes scheduler", () => {
const out = renderSystemdTimer(SPEC, "30m", {});
expect(out).not.toContain("*/30 * * * *");
expect(out).not.toContain("crontab -e");
expect(out).not.toContain("hermes cron create");
});
test("the interval reaches the timer in the unit systemd reads natively", () => {
expect(renderSystemdTimer(SPEC, "6h", {})).toContain("OnUnitActiveSec=6h\n");
expect(renderSystemdTimer(SPEC, "1d", {})).toContain("OnUnitActiveSec=1d\n");
expect(renderSystemdTimer(SPEC, " 15 m ", {})).toContain("OnUnitActiveSec=15m\n");
});
test("refuses every interval the cron renderer refuses, with the same message", () => {
for (const interval of ["90m", "30s", "24h", "28d", "nonsense"]) {
expect(refusal(() => renderSystemdTimer(SPEC, interval, {}))).toBe(
refusal(() => renderCronRecipe(SPEC, interval, {})),
);
}
});
test("the binary override reaches both builders", () => {
const out = renderSystemdTimer(SPEC, "30m", { o2bBin: "/opt/probe/o2b" });
expect(out).toContain(`${SENTINEL.bodyMarker} /opt/probe/o2b`);
expect(out).toContain(`# After install, verify with: /opt/probe/o2b ${SENTINEL.verify}`);
});
});
describe("parseRecipeFormat", () => {
test("the formats are cron and systemd, cron first", () => {
expect([...RECIPE_FORMATS]).toEqual(["cron", "systemd"]);
});
test("no flag means cron; systemd passes through", () => {
expect(parseRecipeFormat(undefined)).toBe("cron");
expect(parseRecipeFormat("cron")).toBe("cron");
expect(parseRecipeFormat("systemd")).toBe("systemd");
});
test("an unknown format is refused by name, naming both formats", () => {
const message = refusal(() => parseRecipeFormat("launchd"));
expect(message).toBe('unknown recipe format "launchd": expected cron or systemd');
});
});
describe("shellWord", () => {
test("a plain word echoes bare; anything a shell could act on is single-quoted", () => {
// The plain set is deliberately narrower than bash's own safe-word
// list: ids, dates and paths echo bare, and every other byte costs
// one quoting spell instead of one shell reading.
expect(shellWord("ent-people-ada-lovelace")).toBe("ent-people-ada-lovelace");
expect(shellWord("2026-03-04")).toBe("2026-03-04");
expect(shellWord("Notes/One.md")).toBe("Notes/One.md");
expect(shellWord("claude+v2")).toBe("'claude+v2'");
expect(shellWord("2026-03-04T00:00:00Z")).toBe("'2026-03-04T00:00:00Z'");
expect(shellWord("Ada Lovelace!")).toBe("'Ada Lovelace!'");
expect(shellWord("")).toBe("''");
});
test("a quote inside the value survives the paste-back", () => {
expect(shellWord("O'Brien")).toBe("'O'\\''Brien'");
});
});