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
24.0 KB
Raw Blame
/**
 * Partner integration with codegraph (https://github.com/colbymchenry/codegraph).
 *
 * OSB never installs, initializes, or writes data for codegraph. This
 * module only detects presence and reports back through the standard
 * doctor `CheckResult` shape so agents (and humans) know whether the
 * partner tool is available, indexed, or missing in the current scope.
 *
 * Detection scope is intentionally narrow: the current working directory
 * plus the top-level siblings of the vault's parent (where users often
 * keep their code projects next to the vault) plus any explicit extras
 * from config. No deep filesystem walk.
 */

import { existsSync, readdirSync, realpathSync } from "node:fs";
import { dirname, join, resolve } from "node:path";

import {
  PARTNER_CODEGRAPH_DISABLED_CONFIG_KEY,
  PARTNER_CODEGRAPH_DISABLED_ENV,
} from "../config.ts";
import type { CheckResult } from "../types.ts";
import { isDir, statOrAbsent } from "../fs-utils.ts";
import { CODE_MANIFEST_FILES } from "../project-manifests.ts";
import { assessGraphHealth, summarizeGraphHealth } from "./codegraph-health.ts";

const DEFAULT_LIMIT = 50;

/**
 * The partner CLI's own vocabulary, in one place.
 *
 * These four tokens are the entire surface OSB knows about codegraph, and
 * they were previously written out five times across two modules - the
 * spawn arguments here, and the remediation sentence `run: codegraph init
 * <path>` in two separately worded messages. A partner that renames a
 * subcommand would have had to be chased through every copy, and the two
 * copies of the remediation could drift into saying different things about
 * the same repair.
 *
 * The invariant this constant serves is unchanged and absolute: OSB never
 * installs, initializes, or writes data for codegraph. `initSubcommand`
 * exists so OSB can *quote* the command an operator (or their crontab) runs
 * themselves, never so OSB can run it.
 */
export const CODEGRAPH_CLI = Object.freeze({
  /** Executable name looked up on PATH. */
  bin: "codegraph",
  /** Subcommand that reports index state. */
  statusSubcommand: "status",
  /** Flag making the status subcommand emit JSON. */
  statusJsonFlag: "-j",
  /** Subcommand that builds an index for a project root. */
  initSubcommand: "init",
} as const);

/**
 * The `codegraph init <path>` command line, as text. Quoted in operator-facing
 * remediation and in the resync cron recipe; never spawned by this project.
 */
export function codegraphInitCommand(projectPath: string): string {
  return `${CODEGRAPH_CLI.bin} ${CODEGRAPH_CLI.initSubcommand} ${projectPath}`;
}

/**
 * Heuristic check: does `dir` look like a code project root?
 * Requires BOTH a `.git/` directory AND at least one recognised
 * manifest file (the two-signal rule rejects a stray `package.json`
 * inside a notes folder).
 */
export function isCodeProject(dir: string): boolean {
  try {
    if (!existsSync(dir)) return false;
    if (!isDir(join(dir, ".git"))) return false;
    return CODE_MANIFEST_FILES.some((m) => existsSync(join(dir, m)));
  } catch {
    return false;
  }
}

export interface FindCodeProjectsOptions {
  readonly cwd: string;
  readonly vault: string;
  readonly scanExtraPaths?: ReadonlyArray<string>;
  readonly limit?: number;
}

/**
 * Walk the candidate scope (cwd + top-level siblings of `dirname(vault)`
 * + explicit extras) and return every path that passes `isCodeProject`.
 * The scan is bounded at `limit` inspected directories (default 50)
 * so a huge vault parent cannot slow doctor down.
 */
export function findCodeProjects(opts: FindCodeProjectsOptions): string[] {
  const limit = opts.limit ?? DEFAULT_LIMIT;
  const seen = new Set<string>();
  const found: string[] = [];
  let scanned = 0;

  const consider = (raw: string): void => {
    if (scanned >= limit) return;
    const path = resolve(raw);
    if (seen.has(path)) return;
    seen.add(path);
    if (!isDir(path)) return;
    scanned += 1;
    if (isCodeProject(path)) found.push(path);
  };

  consider(opts.cwd);

  const vaultParent = dirname(resolve(opts.vault));
  if (isDir(vaultParent)) {
    let entries: string[] = [];
    try {
      entries = readdirSync(vaultParent);
    } catch {
      entries = [];
    }
    entries.sort((a, b) => a.localeCompare(b));
    for (const name of entries) {
      if (scanned >= limit) break;
      consider(join(vaultParent, name));
    }
  }

  for (const extra of opts.scanExtraPaths ?? []) {
    if (scanned >= limit) break;
    consider(extra);
  }

  return found;
}

/**
 * The root the index was built for vs. the root it is being read from.
 * `codegraph status -j` emits this block only when they differ (e.g. the
 * index lives at the repo root but is queried from a git worktree). Its
 * presence is the raw signal behind the graph-health `cache-root-mismatch`
 * finding.
 */
export interface CodegraphWorktreeMismatch {
  readonly worktreeRoot: string;
  readonly indexRoot: string;
}

export interface CodegraphStatusData {
  readonly initialized: boolean;
  readonly nodeCount?: number;
  readonly fileCount?: number;
  readonly edgeCount?: number;
  /** Absolute root the index was built for (`status.projectPath`). */
  readonly projectPath?: string;
  /** Present only when the index root differs from the queried root. */
  readonly worktreeMismatch?: CodegraphWorktreeMismatch;
  /**
   * Optional partner-provided graph diagnostics. Base `codegraph status`
   * does not emit these today; the graph-health gate consumes them when a
   * richer status surface provides them, and treats their absence as
   * "not measured" (no finding), never as zero.
   */
  readonly danglingRefs?: number;
  readonly selfLoops?: number;
}

/**
 * What asking the partner for one project's status produced.
 *
 * Three arms, not two. `unanswered` is separate from `error` because the
 * two are different facts about the world and only one of them is about
 * the index: a partner that exited non-zero has told us something, and a
 * partner that never returned has told us nothing at all. Collapsing them
 * sends an operator to `codegraph init` over a process that is still
 * running. This is the same distinction `DOCTOR_EXIT.probeIncomplete`
 * draws one release earlier - a probe that did not complete is not a probe
 * that failed.
 */
export interface CodegraphUnanswered {
  readonly ok: false;
  /** Present only on this arm; the field the guard below discriminates on. */
  readonly unanswered: true;
  /** The deadline that expired, in milliseconds, as the message quotes it. */
  readonly waitedMs: number;
}

export type CodegraphStatusResult =
  | { readonly ok: true; readonly data: CodegraphStatusData }
  | { readonly ok: false; readonly error: string }
  | CodegraphUnanswered;

/**
 * Whether the partner never answered.
 *
 * A guard rather than a `kind` field on all three arms, because the two
 * existing arms are a published shape that tests and the report module
 * build by hand; narrowing on a member unique to the new arm adds the
 * distinction without rewriting what already answers.
 */
export function isCodegraphUnanswered(
  result: CodegraphStatusResult,
): result is CodegraphUnanswered {
  return result.ok === false && "unanswered" in result;
}

export interface CodegraphCheckDeps {
  readonly whichCodegraph?: () => string | null;
  readonly runStatusJson?: (projectPath: string) => CodegraphStatusResult;
  /**
   * Feature probe: does the partnered codegraph accept a per-query project
   * path, so status can be threaded per project across a multi-project
   * workspace? When it does not, checkCodegraph degrades to the first project
   * only (see {@link defaultDetectProjectPathSupport}).
   */
  readonly detectProjectPathSupport?: () => boolean;
  /**
   * Deadline for each partner invocation, defaulting to
   * {@link CODEGRAPH_PARTNER_TIMEOUT_MS}.
   *
   * It lives on the deps rather than on {@link CodegraphCheckOptions}
   * because it is a seam, not a setting: nothing in the product produces a
   * value for it, and a configurable deadline nobody configures would be
   * one more declared surface with no producer. What it buys is a test
   * that can hang a real partner and watch a real bound end it, instead of
   * asserting against a fake that returns the record the bound would have
   * produced.
   */
  readonly timeoutMs?: number;
}

export interface CodegraphCheckOptions {
  readonly cwd: string;
  readonly vault: string;
  readonly scanExtraPaths?: ReadonlyArray<string>;
  readonly limit?: number;
  readonly disabled?: boolean;
}

/**
 * The lookup path and environment the partner is resolved and run against.
 *
 * Both are read from `process.env` AT CALL TIME and passed explicitly,
 * because `Bun.which` and `Bun.spawn*` otherwise resolve a command against
 * the PATH this process was STARTED with. A long-lived process that
 * updated its own PATH - the MCP server, a host embedding this module,
 * a test standing up a fake partner - would find the binary the snapshot
 * named and never the one the environment now points at, and would report
 * that stale binary's answer as this machine's state.
 */
function partnerEnv(): Readonly<Record<string, string | undefined>> {
  return process.env;
}

export function defaultWhichCodegraph(): string | null {
  if (typeof Bun !== "undefined" && typeof (Bun as { which?: unknown }).which === "function") {
    const found = (
      Bun as unknown as {
        which: (cmd: string, opts?: { PATH?: string | undefined }) => string | null;
      }
    ).which(CODEGRAPH_CLI.bin, { PATH: partnerEnv()["PATH"] });
    return found ?? null;
  }
  return null;
}

/**
 * Structural probe for per-query project-path support: does `codegraph status
 * --help` document a positional path argument (`[path]`)? The token is the
 * partner CLI's own usage marker for "you may pass a project path here"; when
 * present, status/queries can be threaded per project across a multi-project
 * workspace. This matches a documented usage token, not natural-language text,
 * and fails closed (returns false) on any spawn/read error so a probe failure
 * degrades to today's single-project behavior rather than throwing.
 */
const CODEGRAPH_PROJECT_PATH_USAGE_TOKEN = /\[path\]/;

/** The universal flag that makes a CLI print its own usage. */
const HELP_FLAG = "--help";

/**
 * How long any single partner invocation may take before it is stopped.
 *
 * Both spawns are SYNCHRONOUS and `doctor()` has three callers - the CLI,
 * the MCP `vault_health` tool and the OpenClaw extension - so an unbounded
 * one blocks whichever of them asked, for as long as the partner is stuck.
 * The bound existed nowhere: a wedged partner (a stale lock, an index
 * rebuild that never returns, a stalled network filesystem) hung the
 * doctor with no deadline, no refusal and no record.
 *
 * Ten seconds because this is a CEILING and not a target: a warm
 * `codegraph status -j` over a 27k-node index on the machine this was
 * measured on answers in ~0.7 s, and the partner's own config docblock
 * names seconds against a cold HOME. An order of magnitude of headroom
 * keeps a slow-but-working partner reporting its answer, while a partner
 * that is not coming back stops being everyone else's problem.
 */
export const CODEGRAPH_PARTNER_TIMEOUT_MS = 10_000;

/** Bun reports a killed-by-deadline spawn with its own flag; typed once here. */
function timedOut(proc: { readonly exitedDueToTimeout?: boolean }): boolean {
  return proc.exitedDueToTimeout === true;
}

/**
 * @param timeoutMs deadline for the spawn; see {@link CODEGRAPH_PARTNER_TIMEOUT_MS}.
 *   A probe that times out returns `false` for the same reason a probe
 *   that throws does - the caller degrades to the first project and says
 *   so - and the sentence it produces claims only that support was not
 *   REPORTED, never that the partner lacks it.
 */
export function defaultDetectProjectPathSupport(
  timeoutMs: number = CODEGRAPH_PARTNER_TIMEOUT_MS,
): boolean {
  try {
    const proc = Bun.spawnSync({
      cmd: [CODEGRAPH_CLI.bin, CODEGRAPH_CLI.statusSubcommand, HELP_FLAG],
      stdout: "pipe",
      stderr: "pipe",
      env: partnerEnv(),
      timeout: timeoutMs,
    });
    if (timedOut(proc)) return false;
    const help = new TextDecoder().decode(proc.stdout) + new TextDecoder().decode(proc.stderr);
    return CODEGRAPH_PROJECT_PATH_USAGE_TOKEN.test(help);
  } catch {
    return false;
  }
}

export function defaultRunStatusJson(
  projectPath: string,
  timeoutMs: number = CODEGRAPH_PARTNER_TIMEOUT_MS,
): CodegraphStatusResult {
  try {
    const proc = Bun.spawnSync({
      cmd: [
        CODEGRAPH_CLI.bin,
        CODEGRAPH_CLI.statusSubcommand,
        CODEGRAPH_CLI.statusJsonFlag,
        projectPath,
      ],
      stdout: "pipe",
      stderr: "pipe",
      env: partnerEnv(),
      timeout: timeoutMs,
    });
    // Checked BEFORE the output is read, because a partner killed at the
    // deadline usually wrote nothing and would otherwise be reported as
    // "empty status output" - a sentence about what it said, over a
    // process that never said anything.
    if (timedOut(proc)) return { ok: false, unanswered: true, waitedMs: timeoutMs };
    const stdout = new TextDecoder().decode(proc.stdout).trim();
    const stderr = new TextDecoder().decode(proc.stderr).trim();
    if (!proc.success) {
      if (stdout) {
        try {
          const parsed = JSON.parse(stdout) as CodegraphStatusData;
          return { ok: true, data: parsed };
        } catch {}
      }
      return {
        ok: false,
        error:
          stderr ||
          `${CODEGRAPH_CLI.bin} ${CODEGRAPH_CLI.statusSubcommand} exited ${proc.exitCode}`,
      };
    }
    if (!stdout) {
      return { ok: false, error: stderr || "empty status output" };
    }
    const parsed = JSON.parse(stdout) as CodegraphStatusData;
    return { ok: true, data: parsed };
  } catch (exc) {
    return { ok: false, error: (exc as Error).message ?? String(exc) };
  }
}

/**
 * Doctor-grade check for codegraph partnership. Returns `null` (skip, no
 * doctor output) when the current scope is not a code project or when the
 * codegraph CLI is not installed — codegraph is an optional partner OSB
 * never installs, so its absence must not fail doctor.
 *
 * Non-null results carry a single `code_graph` `CheckResult` describing
 * one of four states: `disabled`, `not_indexed`, `ok`, or `error`.
 *
 * `disabled` reports itself instead of returning null, because the switch
 * that produces it would otherwise be a setting that silently does
 * nothing visible: an operator who turned the check off, one whose machine
 * has no codegraph, and one standing in a directory that is not a code
 * project would all read the same empty report. Those two remaining
 * silences are NOT distinguished here, and saying so is the honest form of
 * this docblock: separating them means emitting a `code_graph` line on
 * every machine without the partner, CI included, which is a change to the
 * base doctor output rather than to this switch.
 */
export function checkCodegraph(
  opts: CodegraphCheckOptions,
  deps?: CodegraphCheckDeps,
): CheckResult | null {
  if (opts.disabled) return codegraphDisabledResult();

  const projects = findCodeProjects(opts);
  if (projects.length === 0) return null;

  const whichFn = deps?.whichCodegraph ?? defaultWhichCodegraph;
  const cliPath = whichFn();

  if (!cliPath) {
    // codegraph is an optional partner OSB never installs. If the CLI is not
    // on PATH there is nothing to check — skip silently rather than failing
    // doctor, so `o2b doctor` stays green for users (and CI) without codegraph.
    return null;
  }

  // Single-project workspace: byte-identical to before. No project_path probe
  // runs (there is nothing to thread across), so behavior and output are
  // exactly today's.
  if (projects.length === 1) {
    return evaluateProjectStatus(projects[0]!, deps).result;
  }

  // Multi-project workspace. Threading status per project is only sound when
  // the partner accepts a per-query project path; otherwise every query would
  // report whatever project the CLI infers from its own cwd, so we degrade to
  // the first project and say so explicitly.
  const detectFn =
    deps?.detectProjectPathSupport ?? (() => defaultDetectProjectPathSupport(partnerTimeout(deps)));
  if (!detectFn()) {
    const first = evaluateProjectStatus(projects[0]!, deps).result;
    return {
      name: "code_graph",
      ok: first.ok,
      // "did not report" rather than "has no": the probe reads the
      // partner's own usage text, and a probe that failed or ran out of
      // time reads exactly like a partner without the feature. Saying the
      // stronger thing would be claiming what was not established.
      message: `${first.message}; note: codegraph CLI did not report per-query project_path support - reported 1 of ${projects.length} discovered projects only`,
    };
  }

  // A partner that has already failed to answer once is not asked again:
  // per-project retries would multiply the deadline by the project count,
  // which is how a bound stops bounding anything. The projects that were
  // consequently never consulted are named rather than dropped.
  const results: CheckResult[] = [];
  let unanswered = false;
  for (const project of projects) {
    if (unanswered) {
      results.push({
        name: "code_graph",
        ok: false,
        message:
          `code project at ${project}: not consulted - ${CODEGRAPH_CLI.bin} did not answer for ` +
          "an earlier project in this workspace, so nothing is claimed here about this index",
      });
      continue;
    }
    const evaluated = evaluateProjectStatus(project, deps);
    unanswered = evaluated.unanswered;
    results.push(evaluated.result);
  }
  const header = `${projects.length} code projects:`;
  return {
    name: "code_graph",
    ok: results.every((r) => r.ok),
    message: [header, ...results.map((r) => `- ${r.message}`)].join("\n"),
  };
}

/** The deadline this call runs under. */
function partnerTimeout(deps?: CodegraphCheckDeps): number {
  return deps?.timeoutMs ?? CODEGRAPH_PARTNER_TIMEOUT_MS;
}

/**
 * The `disabled` arm.
 *
 * `ok` is a two-valued field and this state is neither of its two
 * meanings, so the message carries what the flag cannot: which switch
 * turned the check off, and that nothing was asked of the partner. `true`
 * is the lesser wrong of the two - `false` would fail `o2b doctor` for an
 * operator who deliberately asked it to leave the partner alone, turning
 * a preference into a defect. Giving the doctor a third stream so this
 * state stops borrowing `ok` at all is a change to every consumer of
 * {@link CheckResult} (the CLI, the MCP payload, the OpenClaw extension)
 * and is named here rather than smuggled in with a switch.
 */
function codegraphDisabledResult(): CheckResult {
  return {
    name: "code_graph",
    ok: true,
    message:
      `check disabled by ${PARTNER_CODEGRAPH_DISABLED_ENV} / ` +
      `${PARTNER_CODEGRAPH_DISABLED_CONFIG_KEY}: ${CODEGRAPH_CLI.bin} was not consulted, ` +
      "so nothing is claimed here about any index",
  };
}

/** One project's verdict, plus whether the partner failed to answer for it. */
interface EvaluatedProject {
  readonly result: CheckResult;
  /**
   * True when the partner ran out of time rather than answering. Carried
   * beside the result rather than parsed back out of its message, because
   * the aggregate above changes what it DOES on this fact.
   */
  readonly unanswered: boolean;
}

/**
 * Evaluate one project's codegraph status into a `code_graph` CheckResult,
 * threading the project path into the status query. This is the exact
 * per-project logic (not-indexed / no-answer / status-failed / indexed +
 * graph-health) that the single-project path returns verbatim, so a
 * single-project workspace stays byte-identical and a multi-project
 * aggregate reuses one implementation.
 */
function evaluateProjectStatus(project: string, deps?: CodegraphCheckDeps): EvaluatedProject {
  const indexDir = join(project, ".codegraph");
  // Stat'ed rather than probed with `isDir`, which answers `false` both for
  // an index that was never built and for one this process cannot look at.
  // Only the first is "not indexed", and it is the only one `codegraph
  // init` clears - telling an operator to re-init an index that is already
  // there sends them past the permission fault that is the actual cause.
  let indexed: boolean;
  try {
    indexed = statOrAbsent(indexDir)?.isDirectory() === true;
  } catch (exc) {
    return answered({
      name: "code_graph",
      ok: false,
      message: `code project at ${project}: index directory unreadable: ${(exc as Error).message ?? exc}`,
      fix: `chmod u+rx "${indexDir}"`,
    });
  }
  if (!indexed) {
    return answered({
      name: "code_graph",
      ok: false,
      message: `code project at ${project}: not indexed (run: ${codegraphInitCommand(project)})`,
    });
  }

  const runFn =
    deps?.runStatusJson ?? ((path: string) => defaultRunStatusJson(path, partnerTimeout(deps)));
  const status = runFn(project);
  if (isCodegraphUnanswered(status)) {
    // `ok: false` is the lesser wrong of the two values this field has,
    // for the mirror of the reason `codegraphDisabledResult` chooses
    // `true`: reporting a wedged partner as a pass would be the silent
    // no-op, and the doctor has no third stream to put "did not complete"
    // on without changing every consumer of `CheckResult`. The message
    // therefore carries the distinction the flag cannot.
    return {
      result: {
        name: "code_graph",
        ok: false,
        message:
          `code project at ${project}: ${CODEGRAPH_CLI.bin} ` +
          `${CODEGRAPH_CLI.statusSubcommand} did not answer within ${status.waitedMs}ms and was ` +
          "stopped, so NOTHING is claimed here about this index - a probe that did not complete " +
          "is not an index that failed",
        fix: `${CODEGRAPH_CLI.bin} ${CODEGRAPH_CLI.statusSubcommand} ${CODEGRAPH_CLI.statusJsonFlag} ${project}`,
      },
      unanswered: true,
    };
  }
  if (!status.ok) {
    return answered({
      name: "code_graph",
      ok: false,
      message: `code project at ${project}: codegraph status failed: ${status.error}`,
    });
  }

  if (!status.data.initialized) {
    return answered({
      name: "code_graph",
      ok: false,
      message: `code project at ${project}: not indexed (run: ${codegraphInitCommand(project)})`,
    });
  }

  const nodes = status.data.nodeCount ?? 0;
  const files = status.data.fileCount ?? 0;
  const base = `code project at ${project}: indexed (${nodes} nodes, ${files} files)`;

  // Read-only graph-health gate. Runs after the partner has indexed the graph
  // and before OSB surfaces trust it. Findings are non-blocking: the graph is
  // present and usable, so `ok` stays true (a cache-root mismatch, common in
  // worktree checkouts, must not fail `o2b doctor`) - but the summary is
  // appended so an operator sees the warning and can drill in via
  // `o2b partner codegraph report`.
  const health = assessGraphHealth({
    nodeCount: nodes,
    edgeCount: status.data.edgeCount ?? 0,
    ...(status.data.danglingRefs !== undefined ? { danglingRefs: status.data.danglingRefs } : {}),
    ...(status.data.selfLoops !== undefined ? { selfLoops: status.data.selfLoops } : {}),
    indexRoot: resolveRealpath(
      status.data.worktreeMismatch?.indexRoot ?? status.data.projectPath ?? null,
    ),
    worktreeRoot: resolveRealpath(status.data.worktreeMismatch?.worktreeRoot ?? project),
  });

  return answered({
    name: "code_graph",
    ok: true,
    message: health.ok
      ? base
      : `${base}; graph-health: ${summarizeGraphHealth(health)} - run: o2b partner codegraph report`,
  });
}

/** A verdict the partner (or the filesystem) actually produced. */
function answered(result: CheckResult): EvaluatedProject {
  return { result, unanswered: false };
}

/**
 * Resolve a path through symlinks so the cache-root-mismatch comparison treats
 * a real checkout and its symlinked worktree as the same root. Falls back to
 * the raw value when the path is missing or unreadable (a missing path is not
 * a topology mismatch worth warning about here).
 */
function resolveRealpath(value: string | null | undefined): string | null {
  if (!value) return null;
  try {
    return realpathSync(value);
  } catch {
    return value;
  }
}