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
4.0 KB
Raw Blame
/**
 * Atomic in-place annotation of `@osb` markers with their captured
 * signal id.
 *
 * Two shapes:
 *
 *   - Inline: prepend `✓ [[<sig-id>]] ` between `@osb` and the rest of
 *     the line. The leading sentinel `@osb✓` is what {@link
 *     discoverMarkers} skips on a re-run, providing idempotency.
 *
 *   - Block: flip the opening info-string `osb` → `osb-checked` and
 *     insert `<!-- @osb✓ [[<sig-id>]] -->` as the new first body line.
 *     The fence body is preserved verbatim so the human-readable
 *     payload stays in the source file (Obsidian renderers don't
 *     interpret HTML comments inside fenced blocks).
 *
 * Concurrency: a `proper-lockfile` lock on the parent directory
 * serialises rewrites. Per-file locks would race against the temp
 * file `atomicWriteFileSync` itself creates next to the target.
 *
 * Atomicity: writes go through {@link atomicWriteFileSync}, which
 * uses the tmp-file-and-rename pattern. A crash mid-rewrite leaves
 * the previous version intact; the new version becomes visible only
 * after the directory entry is updated.
 */

import { mkdirSync, readFileSync } from "node:fs";
import { dirname } from "node:path";

import lockfile from "proper-lockfile";

import { atomicWriteFileSync } from "../fs-atomic.ts";
import type { ParsedMarker } from "./inline.ts";

export interface RewriteOp {
  readonly marker: ParsedMarker;
  /** Resulting `sig-<date>-<slug>` (or any other id) to embed. */
  readonly signalId: string;
}

/**
 * Apply every op to the file at `path`. Ops are applied in document
 * order; line-shift from inserting a block-comment is handled by
 * processing the op list in reverse (so earlier line indices stay
 * valid).
 */
export async function rewriteMarkers(path: string, ops: ReadonlyArray<RewriteOp>): Promise<void> {
  if (ops.length === 0) return;

  // proper-lockfile requires the target to exist; locking the parent
  // directory serialises concurrent rewrites of the same file.
  const parent = dirname(path);
  mkdirSync(parent, { recursive: true });

  const release = await lockfile.lock(parent, {
    retries: { retries: 30, factor: 1.2, minTimeout: 30, maxTimeout: 500 },
    stale: 10_000,
    realpath: false,
  });
  try {
    const original = readFileSync(path, "utf8");
    const lines = original.split("\n");

    // Sort ops descending by originLine so that inserts in block-form
    // ops don't shift the line indices of earlier ops.
    const sorted = [...ops].toSorted((a, b) => b.marker.originLine - a.marker.originLine);

    for (const op of sorted) {
      const idx = op.marker.originLine - 1;
      if (idx < 0 || idx >= lines.length) {
        // Off-the-end: file changed since the marker was discovered.
        // Skip silently rather than corrupt; the caller's next
        // `discoverMarkers` will re-find the live state.
        continue;
      }
      if (op.marker.shape === "inline") {
        const line = lines[idx]!;
        // Replace the leading '@osb' with '@osb✓ [[id]]' — preserve any
        // leading whitespace.
        const replaced = line.replace(/@osb(?=\s)/, `@osb✓ [[${op.signalId}]]`);
        lines[idx] = replaced;
      } else {
        // Block form: idx points at the opening ```osb line. Use an
        // exact-match check so an already-rewritten `\`\`\`osb-checked`
        // fence (from a stale op replay) cannot be re-annotated.
        const fenceLine = lines[idx]!;
        if (!/^\s*```osb\s*$/.test(fenceLine)) {
          continue;
        }
        // Preserve any leading whitespace before the fence (CommonMark
        // allows up to 3 spaces of indentation on a fence).
        const indent = fenceLine.match(/^\s*/)?.[0] ?? "";
        lines[idx] = `${indent}\`\`\`osb-checked`;
        // Insert the HTML-comment sentinel as the first body line.
        lines.splice(idx + 1, 0, `<!-- @osb✓ [[${op.signalId}]] -->`);
      }
    }

    const updated = lines.join("\n");
    if (updated === original) return; // nothing to do (defensive)
    atomicWriteFileSync(path, updated);
  } finally {
    await release();
  }
}