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
13.8 KB
Raw Blame
/**
 * The `.gitignore` guard seeder (t_206562ae): one managed block in the
 * vault's `.gitignore` covering the derived store.
 *
 * `<vault>/.open-second-brain/` holds every piece of derived runtime
 * state this tool keeps for itself - brain.sqlite, the hook audit, the
 * secrets store, the maintenance lease and journals, the ingest
 * checkpoints, dead letters, the session ledgers, the watchdog fallback,
 * the self-heal state, the lockfiles and the bench runs. The vault scope
 * already excludes the directory (`DEFAULT_VAULT_IGNORE_PATHS`), but
 * nothing told git, so a fresh `o2b brain init` in a repository left
 * `brain.sqlite` visible to `git status`. This module seeds the git-side
 * guard: a managed block whose entry list starts as exactly one
 * vault-root-anchored line, `/.open-second-brain/`.
 *
 * Behaviour:
 *
 *   - No `.gitignore` → one is created containing only the block.
 *   - An existing file keeps every byte of its user content and gains
 *     the block appended with one separating blank line (the
 *     `insertManagedBlock` merge). A conforming block already present is
 *     MERGED, never clobbered: its own entries survive and only the
 *     missing guard entries are added. The MERGED content is re-checked
 *     for a negation after the entry before anything is written, because
 *     a merge that lands the entry inside an earlier block does not move
 *     it past a later `!.open-second-brain` - and a hit refuses the
 *     write like every other conflict.
 *   - Exact-line membership is checked first, so a user who already
 *     ignores the path - inside the block or beside it - yields a skip,
 *     not a duplicate. The skip is only clean while no LATER line
 *     negates the entry: git evaluates patterns in order and the last
 *     match wins, so `!.open-second-brain` after the entry leaves the
 *     store visible, and that surfaces as the same named conflict a
 *     malformed block gets.
 *   - A second run is a no-op: byte-equal file, `skipped`.
 *   - Markers present but malformed (unpaired, doubled, inverted) surface
 *     as a named conflict with warn-and-continue: nothing is written,
 *     and the doctor's git tracked-state row reports the still-unprotected
 *     state. Surgery on a block a human or another tool mangled is not a
 *     decision for a seeder to make.
 *   - A `.gitignore` that is itself a symbolic link - live or dangling -
 *     is the same named conflict: every write this seeder makes is an
 *     atomic rename over the path, which would silently replace the
 *     operator's link with a regular file. The refusal names the link
 *     target, writes nothing, and the doctor row reports the
 *     still-unprotected store.
 *   - CRLF files keep their line endings, inside the block too (the
 *     managed-block editor detects and restores them).
 *   - No git subprocess is ever spawned: git is asked only by the
 *     doctor's `git-tracked-state` probe, which measures what actually
 *     happened on disk.
 */

import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
import { join } from "node:path";

import { atomicWriteFileSync } from "../fs-atomic.ts";
import {
  DEFAULT_BEGIN_MARKER,
  DEFAULT_END_MARKER,
  extractManagedBlock,
  hasManagedBlock,
  insertManagedBlock,
  ManagedBlockError,
} from "../install/managed-block.ts";
import { isMachineStateRelocated } from "../state/machine-state.ts";
import { DERIVED_STORE_DIR } from "./path-constants.ts";

/** Vault-relative name of the file this guard seeds. */
export const GITIGNORE_GUARD_FILE = ".gitignore";

/**
 * The identity of this guard's block, named in warnings and doctor
 * messages so an operator can tell which managed block a finding is
 * about. The markers themselves are the shared `install/managed-block.ts`
 * defaults - the same convention `o2b brain protect` uses - so every
 * block this tree writes parses with the one editor.
 */
export const GITIGNORE_GUARD_BLOCK_ID = "derived-brain-state";

/**
 * The seeded entry list: starts as exactly one vault-root-anchored
 * pattern. Anchored at the vault root (`/.open-second-brain/`, with
 * trailing slash) so a vault nested inside a larger repository ignores
 * its own store and not a sibling's, and one entry covers every Tier A
 * writer. The source-reading census in
 * `tests/core/brain/gitignore-guard.test.ts` pins the list and the
 * population it covers.
 */
export const GITIGNORE_GUARD_ENTRIES: ReadonlyArray<string> = Object.freeze([
  `/${DERIVED_STORE_DIR}/`,
]);

/**
 * The exact `.gitignore` line the seeded block carries: the entry list
 * joined, so a remediation message that names "the exact line" quotes
 * the same constant the seeder writes and the two cannot drift. The
 * census in `tests/core/brain/gitignore-guard.test.ts` pins the list at
 * exactly one entry, so the joined form IS one line.
 */
export const GITIGNORE_GUARD_IGNORE_LINE = GITIGNORE_GUARD_ENTRIES.join("\n");

/** What one seeding pass did to `<vault>/.gitignore`. */
export type GitignoreGuardStatus =
  | "created" // the file did not exist and was written with only the block
  | "updated" // an existing file gained the block (or the block gained entries)
  | "skipped" // every entry already present as an exact line; no bytes moved
  | "conflict"; // malformed markers, a later line negates the entry, or the file is a symlink; nothing written, warning emitted

export interface GitignoreGuardResult {
  readonly status: GitignoreGuardStatus;
  /** Vault-relative name of the file, always {@link GITIGNORE_GUARD_FILE}. */
  readonly file: string;
  /** The named conflict detail, present only when status is "conflict". */
  readonly detail?: string;
}

/** The exact block body for `entries`: markers around one entry per line. */
function blockBody(entries: ReadonlyArray<string>): string {
  return `${DEFAULT_BEGIN_MARKER}\n${entries.join("\n")}\n${DEFAULT_END_MARKER}\n`;
}

/**
 * A line that re-includes the derived store. Built from the directory
 * constant so the guard and its negation cannot drift apart, and
 * matched over the git-valid spellings of the negation:
 *
 *   - `!.open-second-brain` and `!/.open-second-brain`, with or without
 *     git's optional trailing slash;
 *   - unescaped trailing whitespace, which git strips from a pattern
 *     (only a backslash-escaped space is significant);
 *   - the double-star-slash prefix, which matches zero or more
 *     directories and so covers the vault root too.
 *
 * Everything else - escaped-dot spellings, character-class tricks - is
 * deliberately out of scope: the doctor's git-tracked-state row measures
 * what git actually did and is the authority for any spelling this
 * matcher cannot name.
 */
const NEGATED_ENTRY_RE = new RegExp(
  `^!(?:/?|\\*\\*/)${DERIVED_STORE_DIR.replaceAll(".", "\\.")}/?[ \\t]*$`,
);

/**
 * The first line after the LAST guard entry that negates it, or null.
 * git evaluates .gitignore patterns in order and the last match wins, so
 * only a negation AFTER the entry re-opens the store - one before it is
 * overridden and harmless.
 */
function negationAfterEntry(lines: ReadonlyArray<string>): string | null {
  let lastEntry = -1;
  for (let i = 0; i < lines.length; i += 1) {
    if (GITIGNORE_GUARD_ENTRIES.includes(lines[i]!)) lastEntry = i;
  }
  for (let i = lastEntry + 1; i < lines.length; i += 1) {
    if (NEGATED_ENTRY_RE.test(lines[i]!)) return lines[i]!;
  }
  return null;
}

/**
 * Seed the guard block into `<vault>/.gitignore`, merging with whatever
 * is already there. Idempotent and best-effort in the conflict case; the
 * only throws are genuine I/O errors reading or writing the file.
 */
export function ensureVaultGitignoreEntries(vault: string): GitignoreGuardResult {
  // A switched machine keeps its derived state in the device-local state,
  // so there is nothing under the vault to keep out of git, and the vault
  // is not written (design D14, `state/machine-state.ts`).
  if (isMachineStateRelocated(vault)) return { status: "skipped", file: GITIGNORE_GUARD_FILE };
  const file = join(vault, GITIGNORE_GUARD_FILE);

  // A symlinked .gitignore is refused, never written through or over:
  // every write below lands an atomic rename on `file`, and rename(2)
  // swaps the LINK itself for a regular file - an operator who manages
  // the vault .gitignore as a link into their dotfiles (or a shared
  // file) would lose the link with a clean `updated` (or, through the
  // created branch, a dangling link with `created`) reported as if
  // nothing happened. lstat does not follow the link, so it sees the
  // link itself in both the live and the dangling case, before either
  // branch; the doctor's git tracked-state row then reports the still-
  // unprotected store, the same as every other conflict.
  let linkTarget: string | null = null;
  try {
    if (lstatSync(file).isSymbolicLink()) linkTarget = readlinkSync(file);
  } catch {
    // No path at all (ENOENT and friends): the created branch below
    // owns that case. A stat here is not a read of protected bytes.
  }
  if (linkTarget !== null) return symlinkConflict(linkTarget, file);

  if (!existsSync(file)) {
    atomicWriteFileSync(file, blockBody(GITIGNORE_GUARD_ENTRIES));
    return { status: "created", file: GITIGNORE_GUARD_FILE };
  }

  const current = readFileSync(file, "utf8");

  // Exact-line membership first, over the CRLF-normalized whole file: a
  // user who already ignores the path anywhere in it gets a skip, never
  // a second (redundant) line.
  const lines = current.replace(/\r\n/g, "\n").split("\n");
  const present = new Set(lines);
  const missing = GITIGNORE_GUARD_ENTRIES.filter((entry) => !present.has(entry));
  if (missing.length === 0) {
    // The entry being present is not the whole story: git takes the LAST
    // matching pattern, so a later `!.open-second-brain` re-includes the
    // store and a clean skip here would be optimistic - the doctor's
    // tracked-state row would catch it, but the init report should not
    // wait to be corrected. Surface the same named conflict the
    // malformed-marker case gets; write nothing either way.
    const negation = negationAfterEntry(lines);
    if (negation !== null) {
      return conflict(`the guard entry is negated by the later line ${negation} `, file);
    }
    return { status: "skipped", file: GITIGNORE_GUARD_FILE };
  }

  try {
    // Merge, never clobber: a conforming block's own entries survive and
    // only the missing guard entries are added to it. Entries the user
    // already wrote elsewhere in the file are not duplicated into it. An
    // empty existing block contributes no lines - the empty string splits
    // to [""], which would open the merged block with a stray blank line.
    const blockEntries = hasManagedBlock(current) ? blockEntryLines(current) : [];
    const next = insertManagedBlock(current, [...blockEntries, ...missing].join("\n"));
    if (next === current) {
      return { status: "skipped", file: GITIGNORE_GUARD_FILE };
    }
    // The merge moving the entry INSIDE the block does not move it after
    // the file's other patterns: a negation later in the file still wins
    // under git's last-match rule, so a clean `updated` here could seed
    // an entry that protects nothing. The merged content is asked the
    // same question the exact-line skip asks, and a hit refuses the
    // write - the seeder's one conflict convention is warn-and-continue
    // with the file byte-identical, and this case keeps it.
    const negation = negationAfterEntry(next.replace(/\r\n/g, "\n").split("\n"));
    if (negation !== null) {
      return conflict(
        `the merged block would still be negated by the later line ${negation} `,
        file,
      );
    }
    atomicWriteFileSync(file, next);
    return { status: "updated", file: GITIGNORE_GUARD_FILE };
  } catch (err) {
    if (!(err instanceof ManagedBlockError)) throw err;
    const detail = err.message;
    process.stderr.write(
      `warning: could not seed the ${GITIGNORE_GUARD_BLOCK_ID} .gitignore block ` +
        `(derived brain state stays visible to git): ${file}: ${detail}\n`,
    );
    return { status: "conflict", file: GITIGNORE_GUARD_FILE, detail };
  }
}

/** The existing block's entry lines, [] for a block that holds none. */
function blockEntryLines(current: string): ReadonlyArray<string> {
  const body = extractManagedBlock(current) ?? "";
  return body.length === 0 ? [] : body.split("\n");
}

/**
 * Report the named negation conflict: warn on stderr, write nothing.
 * The one conflict convention this seeder has - malformed markers behave
 * the same way - and the init report's `guard.status` carries it to
 * machine readers while the doctor's tracked-state row reports the
 * still-unprotected store.
 */
function conflict(detail: string, file: string): GitignoreGuardResult {
  process.stderr.write(
    `warning: the ${GITIGNORE_GUARD_BLOCK_ID} .gitignore guard is negated ` +
      `(derived brain state stays visible to git): ${file}: ${detail}` +
      "(git last-match-wins: the derived store stays visible to git)\n",
  );
  return { status: "conflict", file: GITIGNORE_GUARD_FILE, detail };
}

/**
 * Report a symlinked `.gitignore`: warn on stderr, write nothing. Same
 * conflict convention as {@link conflict} - `status: "conflict"` with a
 * detail naming the link target - because the store stays unprotected
 * either way; only the reason differs. The warning mirrors the
 * malformed-marker wording ("could not seed"), since seeding is exactly
 * what did not happen.
 */
function symlinkConflict(target: string, file: string): GitignoreGuardResult {
  const detail =
    `the file is a symbolic link to ${target} - seeding would replace the link ` +
    "with a regular file, so nothing was written";
  process.stderr.write(
    `warning: could not seed the ${GITIGNORE_GUARD_BLOCK_ID} .gitignore block ` +
      `(derived brain state stays visible to git): ${file}: ${detail}\n`,
  );
  return { status: "conflict", file: GITIGNORE_GUARD_FILE, detail };
}