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.9 KB
Raw Blame
/**
 * Aider adapter — managed-block in `~/.aider.conf.yml` + sidecar
 * context file in the vault.
 *
 * Aider has no native MCP client at the time this adapter was written
 * (see `docs/plans/2026-05-20-multi-runtime-install-design.md` §3.2,
 * §13). The install path is therefore:
 *
 *   1. Generate `<vault>/.open-second-brain/aider-context.md` from
 *      `templates/install/aider-context.md.tmpl` — placeholders are
 *      `{{VAULT}}` and `{{AGENT_NAME}}`.
 *   2. Write a marker-fenced managed block to `~/.aider.conf.yml`
 *      that injects the sidecar into Aider's `read:` list. If the
 *      user already has their own `read:` elsewhere in the same
 *      file, Aider's YAML loader treats it as a duplicate key —
 *      we surface this caveat in the plan's `postNotes` so the
 *      operator can merge by hand.
 *
 * If a future Aider release ships native MCP, switch this adapter to
 * the JSON-merge body. The interface stays the same.
 */

import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
import { dirname, join } from "node:path";

import { atomicWriteFileSync } from "../../fs-atomic.ts";
import {
  insertManagedBlock,
  removeManagedBlock,
  hasManagedBlock,
  extractManagedBlock,
} from "../managed-block.ts";
import { recordEntry, readManifest, removeEntry } from "../manifest.ts";
import {
  InstallError,
  type ApplyOpts,
  type ApplyResult,
  type DetectResult,
  type InstallAdapter,
  type InstallEnv,
  type InstallPlan,
  type ManifestEntry,
  type McpPayload,
  type UninstallResult,
  type VerifyResult,
  type SessionPathsResult,
} from "../types.ts";
import { sessionPathsFor } from "../session-paths.ts";
import { defaultRegistry } from "../registry.ts";
// The sidecar snapshot logic is shared with the live session-bracketing
// wrapper (E1) so the static and wrapped paths render byte-identical sidecars.
import { renderAiderSidecar, resolveAiderSidecarPath } from "./aider-wrapper.ts";

const TARGET = "aider";
const LABEL = "Aider";

function resolveConfPath(env: InstallEnv): string {
  if (env.env["AIDER_CONFIG"]) return env.env["AIDER_CONFIG"];
  const local = join(env.cwd, ".aider.conf.yml");
  if (existsSync(local)) return local;
  return join(env.home, ".aider.conf.yml");
}

function resolveSidecarPath(env: InstallEnv, opts: { aiderContextPath?: string }): string {
  return resolveAiderSidecarPath(env, opts);
}

function readSafe(path: string): string {
  try {
    return readFileSync(path, "utf8");
  } catch {
    return "";
  }
}

function fileMtimeMs(path: string): number | null {
  try {
    return statSync(path).mtimeMs;
  } catch {
    return null;
  }
}

function renderManagedBody(sidecarPath: string): string {
  return [
    "# Open Second Brain — agent context.",
    "# Aider auto-includes this file as read-only context.",
    "# Regenerated by `o2b install --target aider --apply` — do not hand-edit.",
    "read:",
    `  - ${sidecarPath}`,
    "",
  ].join("\n");
}

function ensureParent(path: string): void {
  const parent = dirname(path);
  if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
}

export const aiderAdapter: InstallAdapter = {
  target: TARGET,
  label: LABEL,

  detect(env: InstallEnv): DetectResult {
    const path = resolveConfPath(env);
    if (!existsSync(path)) {
      return {
        target: TARGET,
        status: "not-installed",
        configPath: path,
        notes: ["config file missing"],
      };
    }
    const raw = readSafe(path);
    if (hasManagedBlock(raw)) {
      return {
        target: TARGET,
        status: "installed",
        configPath: path,
        notes: [],
      };
    }
    return {
      target: TARGET,
      status: "not-installed",
      configPath: path,
      notes: [],
    };
  },

  plan(_payload: McpPayload, env: InstallEnv): InstallPlan {
    const conf = resolveConfPath(env);
    const sidecar = resolveSidecarPath(env, {});
    return {
      target: TARGET,
      steps: [
        {
          kind: "file-copy",
          path: sidecar,
          preview: `render templates/install/aider-context.md.tmpl → ${sidecar}`,
        },
        {
          kind: "managed-block",
          path: conf,
          preview: `add OSB managed block to ${conf} (read: → ${sidecar})`,
        },
      ],
      postNotes: [
        "If your existing ~/.aider.conf.yml already sets `read:`, YAML treats",
        "duplicate top-level keys as ambiguous. Merge the two `read:` lists",
        "by hand if you keep your own.",
      ],
    };
  },

  apply(_plan: InstallPlan, payload: McpPayload, env: InstallEnv, opts: ApplyOpts): ApplyResult {
    const conf = resolveConfPath(env);
    const sidecar = resolveSidecarPath(env, opts);
    const stored = readManifest(env.vault).installs[TARGET];

    // user-modified-block safety net
    if (stored && existsSync(conf) && !opts.force) {
      const raw = readSafe(conf);
      const current = extractManagedBlock(raw);
      const expected = renderManagedBody(sidecar);
      if (current !== null && current.trim() !== expected.trim()) {
        const appliedAt = Date.parse(stored.applied_at);
        const mtime = fileMtimeMs(conf) ?? 0;
        if (Number.isFinite(appliedAt) && mtime > appliedAt + 1000) {
          throw new InstallError(
            `aider: ${conf} appears hand-edited after the last install ` +
              `(managed block diverges from canonical content).`,
            TARGET,
            "user-modified-block",
            "re-run with --force to overwrite, or run `o2b uninstall --target aider --apply` first",
          );
        }
      }
    }

    // Render sidecar
    const sidecarContent = renderAiderSidecar(env, payload);
    if (!opts.dryRun) {
      ensureParent(sidecar);
      atomicWriteFileSync(sidecar, sidecarContent);
    }

    // Insert managed block
    const confRaw = existsSync(conf) ? readFileSync(conf, "utf8") : "";
    const nextConf = insertManagedBlock(confRaw, renderManagedBody(sidecar));
    if (!opts.dryRun) {
      ensureParent(conf);
      atomicWriteFileSync(conf, nextConf);
    }

    const manifest: ManifestEntry = {
      target: TARGET,
      applied_at: env.now.toISOString(),
      operation: "managed-block",
      config_path: conf,
      owned_paths: [sidecar],
      owned_block_marker: "# >>> open-second-brain managed >>>",
    };
    if (!opts.dryRun) recordEntry(env.vault, manifest);

    return { target: TARGET, manifest, steps_executed: opts.dryRun ? 0 : 2 };
  },

  uninstall(env: InstallEnv, opts: ApplyOpts & { fromSnippet?: boolean }): UninstallResult {
    const stored = readManifest(env.vault).installs[TARGET];
    // Prefer the config path recorded at install time. `AIDER_CONFIG`
    // or `cwd` can change between install and uninstall, and
    // `resolveConfPath(env)` would then return a different file.
    const conf = stored?.config_path ?? resolveConfPath(env);
    const skipped: Array<readonly [string, string]> = [];
    const removed_paths: string[] = [];

    if (!stored && !opts.fromSnippet) {
      throw new InstallError(
        "aider: no install manifest entry found",
        TARGET,
        "manifest-missing",
        "o2b uninstall --target aider --apply --force-from-snippet",
      );
    }

    // Remove managed block from conf file
    if (existsSync(conf)) {
      const raw = readFileSync(conf, "utf8");
      if (hasManagedBlock(raw)) {
        const next = removeManagedBlock(raw);
        if (!opts.dryRun) atomicWriteFileSync(conf, next);
      } else {
        skipped.push([conf, "no managed block present"]);
      }
    } else {
      skipped.push([conf, "config file no longer present"]);
    }

    // Remove sidecar file
    const sidecarTargets = stored?.owned_paths ?? [resolveSidecarPath(env, {})];
    for (const t of sidecarTargets) {
      if (existsSync(t)) {
        if (!opts.dryRun) rmSync(t, { force: true });
        removed_paths.push(t);
      } else {
        skipped.push([t, "sidecar file no longer present"]);
      }
    }

    if (!opts.dryRun) removeEntry(env.vault, TARGET);
    return { target: TARGET, removed_keys: [], removed_paths, skipped };
  },

  verify(env: InstallEnv): VerifyResult {
    const stored = readManifest(env.vault).installs[TARGET];
    if (!stored) {
      return {
        target: TARGET,
        status: "not-installed",
        details: ["no install manifest entry"],
        fix_hint: null,
      };
    }
    const conf = stored.config_path ?? resolveConfPath(env);
    if (!existsSync(conf)) {
      return {
        target: TARGET,
        status: "drift",
        details: [`config file missing: ${conf}`],
        fix_hint: "o2b install --target aider --apply",
      };
    }
    const raw = readSafe(conf);
    if (!hasManagedBlock(raw)) {
      return {
        target: TARGET,
        status: "drift",
        details: [`managed block absent from ${conf}`],
        fix_hint: "o2b install --target aider --apply",
      };
    }
    const sidecarPaths = stored.owned_paths ?? [];
    for (const p of sidecarPaths) {
      if (!existsSync(p)) {
        return {
          target: TARGET,
          status: "drift",
          details: [`sidecar context file missing: ${p}`],
          fix_hint: "o2b install --target aider --apply",
        };
      }
      // Refuse to report ok if the sidecar is suspiciously empty.
      if (readSafe(p).trim().length === 0) {
        return {
          target: TARGET,
          status: "drift",
          details: [`sidecar context file is empty: ${p}`],
          fix_hint: "o2b install --target aider --apply",
        };
      }
    }
    return {
      target: TARGET,
      status: "ok",
      details: [`${conf}: managed block present; sidecar ok`],
      fix_hint: null,
    };
  },

  /**
   * Where this runtime keeps session logs, from the one declaration.
   * `aider is wired through a managed YAML block and a sidecar context file and writes no transcript store, so the declaration is empty and the answer is null.`
   */
  sessionPaths(env: InstallEnv): SessionPathsResult | null {
    return sessionPathsFor(TARGET, env);
  },
};

defaultRegistry.register(aiderAdapter);