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
9.7 KB
Raw Blame
/**
 * `o2b partner codegraph resync --cron-template` renderer.
 *
 * An external code index goes stale the moment the repository moves ahead
 * of it, and this project deliberately owns no mechanism that would notice:
 * it refuses daemons and filesystem watchers for this purpose, and the
 * partner module's invariant - OSB never installs, initializes, or writes
 * data for codegraph - forbids the obvious alternative of re-indexing from
 * a maintenance lane. The sanctioned mechanism is a cron recipe: text on
 * stdout, in which every write is a shell command the operator's own
 * crontab runs on the operator's own host. Rendering it touches nothing.
 *
 * The emitted script runs four steps, in this order:
 *
 *   1. A health pre-flight through `o2b partner codegraph report --json`
 *      that aborts non-zero when the index was built for a different root.
 *      Re-indexing over a mismatched root would bake the wrong provenance
 *      into the graph, so reconciling it stays an operator decision. The
 *      gate needs a JSON parser and refuses to run without one, rather
 *      than falling back to a text match that would answer "no mismatch"
 *      for output it failed to understand.
 *   2. Change detection: the repository's current commit against a stamp
 *      file on the operator's host. Unchanged means exit quietly, so the
 *      common case costs one `git rev-parse`.
 *   3. The partner's own indexer, quoted from the shared partner CLI
 *      vocabulary so a renamed subcommand cannot drift out of the recipe.
 *   4. A post-state verification through `--fail-on-health`. The stamp is
 *      written only after that passes: a stamp written after a failed or
 *      empty index would suppress every later attempt, which is exactly
 *      the silence this recipe exists to end.
 */

import {
  operatorScriptPath,
  parseRecipeFormat,
  renderCronRecipe,
  renderSystemdTimer,
  shellQuote,
  singleLinePath,
  type CronRecipeOptions,
  type CronRecipeSpec,
  type RecipeFormat,
} from "./cron-recipe.ts";
import { CODEGRAPH_CLI } from "../core/partner/codegraph.ts";
import { GRAPH_HEALTH_CODES } from "../core/partner/codegraph-health.ts";

/** Inputs the codegraph recipe needs on top of the shared ones. */
export interface CodegraphResyncOptions extends CronRecipeOptions {
  /** Absolute path of the repository the emitted script keeps indexed. */
  readonly projectPath: string;
}

/** Cron job name, and the stem of the script path derived from it. */
const CODEGRAPH_RESYNC_CRON_NAME = "osb-codegraph-resync";

/**
 * Where the emitted script keeps its stamp: the operator's XDG state
 * directory, never the vault and never the partner's index. State
 * directories are for exactly this - data a program may lose without the
 * operator losing anything they authored.
 */
const STAMP_DIR_EXPRESSION = "${XDG_STATE_HOME:-$HOME/.local/state}/open-second-brain";

/** Extension of the per-repository stamp file. */
const STAMP_EXTENSION = ".stamp";

/** Characters kept verbatim in a stamp file name; everything else folds to a dash. */
const STAMP_NAME_UNSAFE = /[^A-Za-z0-9._-]+/g;

/** The `o2b partner codegraph` verb path the emitted script calls back into. */
const REPORT_COMMAND = "partner codegraph report";

/** Flag that turns the report's health verdict into its exit code. */
const FAIL_ON_HEALTH_FLAG = "--fail-on-health";

/** Flag that makes the report machine-readable. */
const JSON_FLAG = "--json";

/** Label the line-break refusal names the repository path with. */
const PROJECT_LABEL = "project";

/** The JSON parser the health gate requires. */
const JSON_PARSER = "jq";

/**
 * One stamp file per repository, named after the repository's path so two
 * recipes on one host cannot silently share a change detector and starve
 * each other of re-indexes.
 */
function stampFileName(projectPath: string): string {
  const slug = projectPath.replace(STAMP_NAME_UNSAFE, "-").replace(/^-+|-+$/g, "");
  return `${CODEGRAPH_RESYNC_CRON_NAME}-${slug}${STAMP_EXTENSION}`;
}

/**
 * The bash body of the resync script. JS-side strings are plain text: the
 * heredoc that carries them is quoted, so nothing here is interpolated by
 * the shell that installs the script, and every `$name` below is expanded
 * later, when cron runs it.
 */
function renderResyncBody(o2bBin: string, projectPath: string): string {
  const report = `${o2bBin} ${REPORT_COMMAND}`;
  const lines = [
    "#!/usr/bin/env bash",
    "set -euo pipefail",
    "",
    "# The repository this recipe keeps indexed, baked in when the recipe",
    "# was rendered. Re-render for a different repository.",
    "project=" + shellQuote(singleLinePath(PROJECT_LABEL, projectPath)),
    'stamp_dir="' + STAMP_DIR_EXPRESSION + '"',
    'stamp_file="$stamp_dir/' + stampFileName(projectPath) + '"',
    "",
    "# 1. Health pre-flight. " + JSON_PARSER + " is REQUIRED here, not preferred:",
    "#    this gate decides whether a re-index may run, and a gate that",
    "#    cannot parse its input must not pass. A looser text match would",
    "#    report no mismatch for output it failed to understand, so a",
    "#    missing parser aborts instead of guessing.",
    "if ! command -v " + JSON_PARSER + " >/dev/null 2>&1; then",
    '  printf "%s\\n" "' +
      CODEGRAPH_RESYNC_CRON_NAME +
      ": " +
      JSON_PARSER +
      ' is required to read the health report; aborting" >&2',
    "  exit 1",
    "fi",
    "",
    'health=$(cd "$project" && ' + report + " " + JSON_FLAG + ")",
    "# An index built for another root must be reconciled by a human before",
    "# a re-index writes over it; every other finding is what re-indexing is",
    "# for, so only this one blocks.",
    // The exit status is read explicitly rather than through `if`, because
    // `if` collapses every non-zero status into one answer. This parser
    // exits 0 when the selection is truthy, 1 when it is falsy, and
    // something larger when it could not read its input at all - and a
    // bare `if` reads that last case as "no mismatch" and re-indexes over
    // a root nobody verified. Only a literal 1 is a pass.
    "mismatch_status=0",
    'printf "%s" "$health" | ' +
      JSON_PARSER +
      " -e '[.index.health.warnings[]? | select(.code == \"" +
      GRAPH_HEALTH_CODES.cacheRootMismatch +
      "\")] | length > 0' >/dev/null || mismatch_status=$?",
    'if [ "$mismatch_status" -eq 0 ]; then',
    '  printf "%s\\n" "' +
      CODEGRAPH_RESYNC_CRON_NAME +
      ": index was built for a different root (" +
      GRAPH_HEALTH_CODES.cacheRootMismatch +
      '); reconcile it before re-indexing" >&2',
    "  exit 1",
    'elif [ "$mismatch_status" -ne 1 ]; then',
    '  printf "%s\\n" "' +
      CODEGRAPH_RESYNC_CRON_NAME +
      ": could not read the health report (" +
      JSON_PARSER +
      ' exit $mismatch_status); aborting rather than re-indexing blind" >&2',
    "  exit 1",
    "fi",
    "",
    "# 2. Change detection. The stamp holds the commit the last verified",
    "#    index was built from; an unchanged commit exits quietly so the",
    "#    common case costs one git call and prints nothing.",
    'current=$(git -C "$project" rev-parse HEAD)',
    'previous=""',
    'if [[ -f "$stamp_file" ]]; then',
    '  previous=$(cat "$stamp_file")',
    "fi",
    'if [[ "$current" == "$previous" ]]; then',
    "  exit 0",
    "fi",
    "",
    "# 3. Re-index through the partner's own CLI. This is the operator's",
    "#    command, running on the operator's host; o2b only quotes it.",
    CODEGRAPH_CLI.bin + " " + CODEGRAPH_CLI.initSubcommand + ' "$project"',
    "",
    "# 4. Verify the post-index state before recording the commit. A stamp",
    "#    written after a failed or empty index would suppress every later",
    "#    attempt and leave the graph quietly stale.",
    'if ! (cd "$project" && ' +
      report +
      " " +
      JSON_FLAG +
      " " +
      FAIL_ON_HEALTH_FLAG +
      " >/dev/null); then",
    '  printf "%s\\n" "' +
      CODEGRAPH_RESYNC_CRON_NAME +
      ': re-index finished but the health gate refused the result; stamp not written" >&2',
    "  exit 1",
    "fi",
    "",
    'mkdir -p "$stamp_dir"',
    'printf "%s\\n" "$current" >"$stamp_file"',
  ];
  return lines.join("\n") + "\n";
}

/** The resync recipe: the codegraph-specific half of the shared layout. */
export const CODEGRAPH_RESYNC_RECIPE: CronRecipeSpec<CodegraphResyncOptions> = Object.freeze<
  CronRecipeSpec<CodegraphResyncOptions>
>({
  title: "Open Second Brain - codegraph resync template",
  cronName: CODEGRAPH_RESYNC_CRON_NAME,
  scriptPath: operatorScriptPath(CODEGRAPH_RESYNC_CRON_NAME),
  scriptNotes: Object.freeze([
    "(then chmod +x). The repository is baked into the script, so a",
    "second repository needs its own script path and cron job name.",
  ]),
  schedulerNote: "(preferred when Hermes owns the host's scheduled jobs)",
  buildScriptBody: ({ o2bBin, projectPath }) => renderResyncBody(o2bBin, projectPath),
  buildVerifyCommand: ({ o2bBin }) => `${o2bBin} ${REPORT_COMMAND} ${FAIL_ON_HEALTH_FLAG}`,
});

/** Options for {@link renderCodegraphResyncTemplate}. */
export interface RenderCodegraphResyncOptions extends CronRecipeOptions {
  /** Recipe format; cron when omitted. */
  readonly format?: RecipeFormat;
}

/**
 * Render the resync recipe for one repository, as a crontab and Hermes
 * recipe (the default) or as a systemd user timer. Pure text: nothing is
 * created, spawned or scheduled here.
 */
export function renderCodegraphResyncTemplate(
  projectPath: string,
  interval: string,
  opts: RenderCodegraphResyncOptions = {},
): string {
  const { format, ...rest } = opts;
  const recipeOpts: CodegraphResyncOptions = { ...rest, projectPath };
  return parseRecipeFormat(format) === "systemd"
    ? renderSystemdTimer(CODEGRAPH_RESYNC_RECIPE, interval, recipeOpts)
    : renderCronRecipe(CODEGRAPH_RESYNC_RECIPE, interval, recipeOpts);
}