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
19.8 KB
Raw Blame
/**
 * Shared renderer for every `--cron-template` recipe this CLI prints.
 *
 * A recipe is text on stdout and nothing else. It prints a script body,
 * a native crontab line, and an optional 'hermes cron create'
 * invocation; the operator (or an agent acting in the operator's name)
 * copies whichever path fits their host into their own scheduler. No
 * verb that renders a recipe writes a file, spawns a scheduler, or
 * installs anything - the writes all happen later, on the operator's
 * host, from the operator's own crontab.
 *
 * That shape was previously welded to one consumer: the search reindex
 * template hardcoded its script name, its command and its
 * change-detection expression inside the renderer, so a second consumer
 * could not reach the interval-to-cron kernel without copying the whole
 * file. This module is that kernel. The section headers, the heredoc
 * mechanics and the scheduler-recipe block now live in exactly one
 * place, and each consumer supplies a {@link CronRecipeSpec} for the
 * parts that genuinely differ.
 *
 * Duration parser accepts <N>s|m|h|d. Mapping to a cron expression
 * covers the common cadences:
 *   - minutes:  every N (N less than 60)   maps to N-step minutes
 *   - hours:    every N (N less than 24)   maps to N-step hours
 *   - days:     every N (N less than 28)   maps to N-step days
 *   - seconds:  rejected (cron's finest grain is one minute)
 *
 * Every cron step field restarts at the head of its enclosing period, and
 * each unit is bounded so the rendered expression means what the operator
 * asked for INSIDE that period. The day bound is the strictest of the
 * three because its enclosing period varies: a star-slash-N step in the
 * day-of-month field means "the 1st, then every Nth day within each
 * month", so at 28 - the shortest month - and above it collapses to the
 * 1st of every month.
 * `--interval 90d` used to render exactly that and call it 90 days.
 *
 * Inputs outside those bounds raise a CronTemplateError naming what the
 * field can express, rather than a schedule that quietly means something
 * else.
 *
 * A second renderer, {@link renderSystemdTimer}, reads the same spec and
 * prints the same script section followed by a systemd user service and
 * timer pair instead of the crontab and Hermes paths. It is print-only in
 * exactly the same way: the unit files, `systemctl --user` and
 * `loginctl enable-linger` are commands the operator runs, never this
 * CLI. It validates the interval through the same {@link parseInterval},
 * so a cadence cron cannot express is refused in both formats with the
 * same message - a recipe cannot say one thing in cron and another in
 * systemd. {@link parseRecipeFormat} maps a `--format` flag onto one of
 * {@link RECIPE_FORMATS}.
 */

export class CronTemplateError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "CronTemplateError";
  }
}

/**
 * Single-quote a value for bash, the way `discipline-install.ts` quotes
 * the vault it bakes into its job: a quote inside the value closes the
 * string, emits an escaped quote and reopens it. Inside single quotes a
 * backslash, a `$` and a backtick are literal, so nothing else needs
 * escaping. Every operator path a recipe bakes into its script goes
 * through here.
 */
export function shellQuote(value: string): string {
  return "'" + value.replace(/'/gu, "'\\''") + "'";
}

/**
 * A word a POSIX shell needs no quoting for: ids like `ent-people-ada`,
 * bare dates and vault-relative paths echo as themselves, everything
 * else gets {@link shellQuote}'d.
 *
 * The plain set is deliberately narrower than bash's own safe-word list
 * (`[A-Za-z0-9_@%+=:,./-]`): the extra characters are safe in a shell
 * but quoting them costs one spelling and saves one audit, and one
 * shared set means every echoed command line - the entity merge preview,
 * the revert plan - quotes by the same rule. Single quotes rather than
 * double because an interactive bash history-expands `!` inside double
 * quotes even when the escaper never mentions it; inside single quotes
 * nothing expands, so the quote itself is the only character needing a
 * spell. The verbs echo these lines for an operator (or an agent) to
 * paste back, so every argument a shell would split, glob or expand is
 * quoted - an unquoted empty value would even render its flag as
 * dropped, which a paste-back then folds to no flag at all.
 */
const PLAIN_SHELL_WORD = /^[A-Za-z0-9_./-]+$/u;

/** One shell-safe argv word: bare when plain, single-quoted otherwise. */
export function shellWord(value: string): string {
  return PLAIN_SHELL_WORD.test(value) ? value : shellQuote(value);
}

/** A line feed or a carriage return anywhere in a value. */
const LINE_BREAK_PATTERN = /[\n\r]/u;

/**
 * Refuse a path that would not survive being baked into a recipe. The
 * script travels inside a heredoc, so a line break in a baked value
 * could end that heredoc early; no real vault or repository path needs
 * one. Returns the value unchanged when it is a single line.
 */
export function singleLinePath(label: string, value: string): string {
  if (LINE_BREAK_PATTERN.test(value)) {
    throw new CronTemplateError(
      label + " path must not contain a line break, got: " + JSON.stringify(value),
    );
  }
  return value;
}

/** Every recipe format a `--format` flag can select; the first is the default. */
export const RECIPE_FORMATS = Object.freeze(["cron", "systemd"] as const);

export type RecipeFormat = (typeof RECIPE_FORMATS)[number];

/** The format a recipe verb renders when no `--format` is given. */
const DEFAULT_RECIPE_FORMAT: RecipeFormat = RECIPE_FORMATS[0];

function isRecipeFormat(value: string): value is RecipeFormat {
  return (RECIPE_FORMATS as ReadonlyArray<string>).includes(value);
}

/**
 * Map a `--format` flag value onto a recipe format. No flag means cron, the
 * format every recipe printed before systemd existed. Anything else that is
 * not a known format is a {@link CronTemplateError}, which every recipe verb
 * already reports through its own refusal exit.
 */
export function parseRecipeFormat(raw: string | undefined): RecipeFormat {
  if (raw === undefined) return DEFAULT_RECIPE_FORMAT;
  if (isRecipeFormat(raw)) return raw;
  throw new CronTemplateError(
    "unknown recipe format " +
      JSON.stringify(raw) +
      ": expected " +
      RECIPE_FORMATS.slice(0, -1).join(", ") +
      " or " +
      RECIPE_FORMATS[RECIPE_FORMATS.length - 1],
  );
}

/** Cron's minute field restarts every hour, so a step must stay under it. */
const MINUTES_PER_HOUR = 60;

/** Cron's hour field restarts every day. */
const HOURS_PER_DAY = 24;

/**
 * The shortest month, and therefore the ceiling on a day-of-month step.
 *
 * A star-slash-N day step fires on the 1st and every Nth day after it
 * WITHIN the month; at 28 no month is long enough for a second firing, so the
 * expression is a monthly schedule whatever N says. Refusing at that
 * boundary is what keeps the rendered cadence and the requested cadence
 * the same claim.
 */
const SHORTEST_MONTH_DAYS = 28;

/** The expression an operator wanting a monthly cadence installs by hand. */
const MONTHLY_CRON_EXPRESSION = "0 0 1 * *";

export interface ParsedInterval {
  /** Cron expression for the chosen interval. */
  readonly cron: string;
  /** Human-readable label (e.g. "30 minutes"). */
  readonly human: string;
  /** Schedule string for 'hermes cron create --schedule ...'. */
  readonly hermesSchedule: string;
  /**
   * The same cadence as a systemd time span (`30m`, `6h`, `1d`): the
   * normalised `<N><unit>`, which systemd reads natively for m, h and d.
   */
  readonly systemdSpan: string;
}

export function parseInterval(raw: string): ParsedInterval {
  const trimmed = raw.trim();
  const m = /^(\d+)\s*(s|m|h|d)$/.exec(trimmed);
  if (!m) {
    throw new CronTemplateError(
      "cannot parse interval " + JSON.stringify(raw) + ": expected <N>s|m|h|d (e.g. 30m, 6h, 1d)",
    );
  }
  const n = parseInt(m[1]!, 10);
  const unit = m[2]!;
  const systemdSpan = n + unit;
  if (n <= 0) {
    throw new CronTemplateError("interval must be positive; got " + JSON.stringify(raw));
  }
  if (unit === "s") {
    throw new CronTemplateError(
      "cron grain is one minute -- second-level intervals are not supported",
    );
  }
  if (unit === "m") {
    if (n >= MINUTES_PER_HOUR) {
      const hours = Math.round(n / MINUTES_PER_HOUR);
      throw new CronTemplateError(
        "intervals of " +
          MINUTES_PER_HOUR +
          " minutes or more must use the h unit (e.g. " +
          hours +
          "h)",
      );
    }
    const cron = "*/" + n + " * * * *";
    return { cron, human: n + " minutes", hermesSchedule: cron, systemdSpan };
  }
  if (unit === "h") {
    if (n >= HOURS_PER_DAY) {
      const days = Math.round(n / HOURS_PER_DAY);
      throw new CronTemplateError(
        "intervals of " + HOURS_PER_DAY + " hours or more must use the d unit (e.g. " + days + "d)",
      );
    }
    const cron = "0 */" + n + " * * *";
    return { cron, human: n + " hours", hermesSchedule: cron, systemdSpan };
  }
  // unit === "d". The day-of-month field is the one that cannot be widened
  // by moving to a larger unit, because there is none - so the refusal
  // states what the field means and hands over the monthly expression
  // instead of rendering a step that silently becomes it.
  if (n >= SHORTEST_MONTH_DAYS) {
    throw new CronTemplateError(
      "cron's day-of-month field restarts every month, so an interval of " +
        n +
        " days cannot be expressed: '0 0 */" +
        n +
        " * *' fires on the 1st of every month, not every " +
        n +
        " days. Use an interval below " +
        SHORTEST_MONTH_DAYS +
        "d, or install a monthly job with '" +
        MONTHLY_CRON_EXPRESSION +
        "' yourself.",
    );
  }
  const cron = "0 0 */" + n + " * *";
  return { cron, human: n + " days", hermesSchedule: cron, systemdSpan };
}

/** Options every recipe accepts. Consumers widen this with their own inputs. */
export interface CronRecipeOptions {
  /** Override the resolved o2b binary path (test seam). */
  readonly o2bBin?: string;
}

/**
 * A recipe's options with every default filled in - what the spec's
 * builders receive, so a builder never repeats a default resolution and
 * never has to answer "which binary" for itself.
 */
export type ResolvedCronRecipeOptions<TOptions extends CronRecipeOptions> = TOptions & {
  readonly o2bBin: string;
};

/**
 * Everything one recipe contributes to the shared layout. Anything not
 * named here is common to every recipe and is rendered by
 * {@link renderCronRecipe} from a single source.
 */
export interface CronRecipeSpec<TOptions extends CronRecipeOptions = CronRecipeOptions> {
  /** Header line naming the recipe, e.g. "... - periodic reindex template". */
  readonly title: string;
  /** Job name for the scheduler recipe (`hermes cron create --name`). */
  readonly cronName: string;
  /** Where the operator saves the script, in tilde form. */
  readonly scriptPath: string;
  /** Extra `##` lines under the script section, without their prefix. */
  readonly scriptNotes: ReadonlyArray<string>;
  /** Parenthetical appended to the scheduler section header. */
  readonly schedulerNote: string;
  /** The bash body placed inside the heredoc, newline-terminated. */
  readonly buildScriptBody: (opts: ResolvedCronRecipeOptions<TOptions>) => string;
  /** The command the footer tells the operator to verify the install with. */
  readonly buildVerifyCommand: (opts: ResolvedCronRecipeOptions<TOptions>) => string;
}

/** The binary name assumed when the caller does not override it. */
export const DEFAULT_O2B_BIN = "o2b";

/** Directory the recipes tell operators to keep their scripts in. */
const OPERATOR_SCRIPT_DIR = "~/.local/bin/";

/** Extension of the emitted script. */
const SCRIPT_EXTENSION = ".sh";

/** Heredoc delimiter wrapping the script body. */
const HEREDOC_MARKER = "OSBEOF";

/** Prefix of a tilde-relative home path, and its shell-variable form. */
const TILDE_HOME_PREFIX = "~/";
const SHELL_HOME_PREFIX = "$HOME/";

/** The horizontal rule that opens and closes the recipe. */
const RULE = "# ----------------------------------------------------------------------\n";

/** Prefix of the commentary lines under the script section. */
const NOTE_PREFIX = "##    ";

/** Where a systemd user manager reads unit files from, in tilde form. */
const SYSTEMD_USER_UNIT_DIR = "~/.config/systemd/user/";

/**
 * systemd's own home-directory specifier. `ExecStart=` expands no tilde
 * and no shell variable, so a tilde-relative script path reaches the unit
 * in this form.
 */
const SYSTEMD_HOME_PREFIX = "%h/";

/**
 * Delay after boot before the first run. The timer is monotonic
 * (`OnBootSec=` plus `OnUnitActiveSec=`), not calendar based: without an
 * `OnBootSec=` it has no first activation after a reboot and never fires
 * again. `Persistent=` applies to `OnCalendar=` timers only, so the unit
 * carries none; the boot delay is what catches up after downtime.
 */
const SYSTEMD_BOOT_DELAY = "5m";

/**
 * Conventional install path for a recipe's script, derived from the cron
 * job name so the two can never drift: `osb-reindex` becomes
 * `~/.local/bin/osb-reindex.sh`.
 */
export function operatorScriptPath(cronName: string): string {
  return OPERATOR_SCRIPT_DIR + cronName + SCRIPT_EXTENSION;
}

/**
 * Rewrite a tilde-relative path into its `$HOME` form. The scheduler
 * recipe passes the script path as a quoted argument, where a leading
 * `~` is not expanded by the shell, so the variable form is the only
 * one that resolves. Paths that are not tilde-relative pass through.
 */
function homeExpanded(path: string): string {
  return path.startsWith(TILDE_HOME_PREFIX)
    ? SHELL_HOME_PREFIX + path.slice(TILDE_HOME_PREFIX.length)
    : path;
}

/** The `%h` form of a tilde-relative path, for `ExecStart=`. */
function systemdHomeExpanded(path: string): string {
  return path.startsWith(TILDE_HOME_PREFIX)
    ? SYSTEMD_HOME_PREFIX + path.slice(TILDE_HOME_PREFIX.length)
    : path;
}

/** What both renderers derive from one call before printing anything. */
interface RecipeInputs<TOptions extends CronRecipeOptions> {
  readonly parsed: ParsedInterval;
  readonly resolved: ResolvedCronRecipeOptions<TOptions>;
}

/**
 * Validate the interval and fill the option defaults. Shared so the two
 * renderers refuse the same intervals with the same message.
 */
function recipeInputs<TOptions extends CronRecipeOptions>(
  interval: string,
  opts: TOptions,
): RecipeInputs<TOptions> {
  const parsed = parseInterval(interval);
  const resolved: ResolvedCronRecipeOptions<TOptions> = {
    ...opts,
    o2bBin: opts.o2bBin ?? DEFAULT_O2B_BIN,
  };
  return { parsed, resolved };
}

/** The opening block: title, interval and the format's own lead lines. */
function renderHeader(title: string, parsed: ParsedInterval, lead: ReadonlyArray<string>): string {
  return (
    RULE +
    "# " +
    title +
    "\n" +
    "# interval: " +
    parsed.human +
    "\n" +
    "#\n" +
    lead.map((line) => "# " + line + "\n").join("") +
    RULE
  );
}

/** Section 1, identical in every format: save the script, make it executable. */
function renderScriptSection<TOptions extends CronRecipeOptions>(
  spec: CronRecipeSpec<TOptions>,
  resolved: ResolvedCronRecipeOptions<TOptions>,
): string {
  return (
    "## 1. Watchdog script - save to " +
    spec.scriptPath +
    "\n" +
    spec.scriptNotes.map((line) => NOTE_PREFIX + line + "\n").join("") +
    "\n" +
    "cat >" +
    spec.scriptPath +
    " <<'" +
    HEREDOC_MARKER +
    "'\n" +
    spec.buildScriptBody(resolved) +
    HEREDOC_MARKER +
    "\n" +
    "chmod +x " +
    spec.scriptPath +
    "\n"
  );
}

/** The closing block: how the operator checks the install worked. */
function renderFooter<TOptions extends CronRecipeOptions>(
  spec: CronRecipeSpec<TOptions>,
  resolved: ResolvedCronRecipeOptions<TOptions>,
): string {
  return RULE + "# After install, verify with: " + spec.buildVerifyCommand(resolved) + "\n" + RULE;
}

/**
 * Render one recipe: header, script section, native crontab section,
 * scheduler section, footer. Throws {@link CronTemplateError} for an
 * interval cron cannot express - the caller reports it rather than
 * emitting a recipe on a cadence the scheduler would silently round.
 */
export function renderCronRecipe<TOptions extends CronRecipeOptions>(
  spec: CronRecipeSpec<TOptions>,
  interval: string,
  opts: TOptions,
): string {
  const { parsed, resolved } = recipeInputs(interval, opts);
  const header = renderHeader(spec.title, parsed, [
    "Pick ONE of the three paths below. The watchdog script is the",
    "common piece; both crontab and Hermes-cron rely on it.",
  ]);
  const watchdog = renderScriptSection(spec, resolved);
  const nativeCron =
    "## 2. Native crontab - open 'crontab -e' and append:\n" +
    "\n" +
    parsed.cron +
    "    " +
    spec.scriptPath +
    "\n";
  const hermesCron =
    "## 3. Hermes cron " +
    spec.schedulerNote +
    ":\n" +
    "\n" +
    "hermes cron create \\\n" +
    "  --name " +
    spec.cronName +
    " \\\n" +
    "  --schedule '" +
    parsed.hermesSchedule +
    "' \\\n" +
    '  --command "' +
    homeExpanded(spec.scriptPath) +
    '" \\\n' +
    "  --no-agent\n";
  const footer = renderFooter(spec, resolved);
  return [header, "", watchdog, "", nativeCron, "", hermesCron, "", footer].join("\n");
}

/**
 * Render one recipe as a systemd user timer: header, the same script
 * section {@link renderCronRecipe} prints, a `.service`/`.timer` pair to
 * save under `~/.config/systemd/user/`, the commands that load and enable
 * the timer, the lingering note, and the same verify footer.
 *
 * Print-only, like the cron form: every file and every `systemctl` call
 * in the output is the operator's to run. Throws
 * {@link CronTemplateError} for exactly the intervals the cron form
 * refuses, so switching `--format` never changes which cadences exist.
 */
export function renderSystemdTimer<TOptions extends CronRecipeOptions>(
  spec: CronRecipeSpec<TOptions>,
  interval: string,
  opts: TOptions,
): string {
  const { parsed, resolved } = recipeInputs(interval, opts);
  const servicePath = SYSTEMD_USER_UNIT_DIR + spec.cronName + ".service";
  const timerPath = SYSTEMD_USER_UNIT_DIR + spec.cronName + ".timer";
  const timerUnit = spec.cronName + ".timer";
  const header = renderHeader(spec.title, parsed, [
    "systemd user timer. Save the script and both units below, then",
    "enable the timer. Nothing here is installed for you.",
  ]);
  const watchdog = renderScriptSection(spec, resolved);
  const service =
    "## 2. systemd service - save to " +
    servicePath +
    "\n" +
    "\n" +
    "mkdir -p " +
    SYSTEMD_USER_UNIT_DIR +
    "\n" +
    "cat >" +
    servicePath +
    " <<'" +
    HEREDOC_MARKER +
    "'\n" +
    "[Unit]\n" +
    "Description=" +
    spec.title +
    "\n" +
    "\n" +
    "[Service]\n" +
    "Type=oneshot\n" +
    "ExecStart=" +
    systemdHomeExpanded(spec.scriptPath) +
    "\n" +
    HEREDOC_MARKER +
    "\n";
  const timer =
    "## 3. systemd timer - save to " +
    timerPath +
    "\n" +
    "\n" +
    "cat >" +
    timerPath +
    " <<'" +
    HEREDOC_MARKER +
    "'\n" +
    "[Unit]\n" +
    "Description=" +
    spec.title +
    " (every " +
    parsed.human +
    ")\n" +
    "\n" +
    "[Timer]\n" +
    "OnBootSec=" +
    SYSTEMD_BOOT_DELAY +
    "\n" +
    "OnUnitActiveSec=" +
    parsed.systemdSpan +
    "\n" +
    "\n" +
    "[Install]\n" +
    "WantedBy=timers.target\n" +
    HEREDOC_MARKER +
    "\n";
  const enable =
    "## 4. Load and enable the timer:\n" +
    "\n" +
    "systemctl --user daemon-reload\n" +
    "systemctl --user enable --now " +
    timerUnit +
    "\n" +
    "\n" +
    NOTE_PREFIX +
    "A user timer stops with your last session unless lingering is on;\n" +
    NOTE_PREFIX +
    "run 'loginctl enable-linger \"$USER\"' once so it keeps firing.\n";
  const footer = renderFooter(spec, resolved);
  return [header, "", watchdog, "", service, "", timer, "", enable, "", footer].join("\n");
}