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
8.9 KB
Raw Blame
/**
 * `o2b partner` subcommand dispatcher.
 *
 * Reports on external code-project partners (currently codegraph). It is a
 * top-level command rather than a `brain` verb because it inspects an external
 * code project, not vault memory content. Every verb here is strictly
 * read-only: it never installs, initializes, extracts, or mutates a partner
 * index or the vault. `resync` is no exception - it renders a cron recipe as
 * text and runs no indexer; the writes in the recipe belong to the operator's
 * own crontab, on the operator's own host.
 */

import { resolve } from "node:path";

import { CliError, parseFlags } from "./argparse.ts";
import { CronTemplateError, parseRecipeFormat } from "./cron-recipe.ts";
import { renderCodegraphResyncTemplate } from "./partner-codegraph-cron.ts";
import { defaultConfigPath, resolveVault } from "../core/config.ts";
import { isDir } from "../core/fs-utils.ts";
import { findCodeProjects } from "../core/partner/codegraph.ts";
import { summarizeGraphHealth } from "../core/partner/codegraph-health.ts";
import { buildCodegraphReport, type CodegraphReport } from "../core/partner/codegraph-report.ts";

/** Both verbs, in one usage block so the two error paths cannot drift. */
const PARTNER_USAGE =
  "usage: o2b partner codegraph report [--vault <path>] [--fail-on-health] [--json]\n" +
  "       o2b partner codegraph resync --cron-template [--interval <N>] " +
  "[--format cron|systemd] [--project <path>] [--vault <path>]\n";

/** Cadence the resync recipe uses when the caller names none. */
const DEFAULT_RESYNC_INTERVAL = "6h";

/**
 * Exit for a report whose graph health the caller asked to gate on and
 * which did not pass. Distinct from the 2 this command line reserves for a
 * mistake in the argv: nothing is wrong with the invocation here, the index
 * is simply not in a state the caller declared acceptable.
 */
const EXIT_HEALTH_REFUSED = 1;

/**
 * Exit for an interval cron cannot express, or a recipe format this CLI
 * does not render - the input is a value, not a flag error.
 */
const EXIT_INTERVAL_REFUSED = 1;

function resolveScopeVault(flagVal: string | undefined): string {
  // The report scans the cwd plus the vault parent's siblings. A configured
  // vault sharpens that scope; without one we fall back to the cwd so the
  // command still works inside a bare code checkout.
  return flagVal ?? resolveVault(defaultConfigPath() ?? undefined) ?? process.cwd();
}

function renderCodegraphReport(report: CodegraphReport): string {
  const lines: string[] = [];
  lines.push(`project: ${report.project ?? "(none in scope)"}`);
  lines.push(`codegraph CLI: ${report.cli.available ? report.cli.path : "not installed"}`);
  const idx = report.index;
  const detail = idx.reason ? ` (${idx.reason})` : "";
  if (idx.state === "indexed") {
    lines.push(
      `index: indexed (${idx.node_count ?? 0} nodes, ${idx.file_count ?? 0} files, ` +
        `${idx.edge_count ?? 0} edges)`,
    );
    // Read-only graph-health gate: surface non-blocking findings before any
    // labeling/import/recall surface trusts the graph.
    if (idx.health) {
      if (idx.health.ok) {
        lines.push("graph health: ok");
      } else {
        lines.push(`graph health: ${idx.health.warnings.length} warning(s)`);
        for (const w of idx.health.warnings) lines.push(`  - ${w.code}: ${w.message}`);
      }
    }
  } else {
    lines.push(`index: ${idx.state}${detail}`);
  }
  if (report.cargo_workspace) {
    const ws = report.cargo_workspace;
    lines.push(`cargo workspace: ${ws.memberCount} member(s)`);
    for (const m of ws.members) lines.push(`  - ${m}`);
  } else {
    lines.push(`cargo workspace: none (${report.cargo_workspace_reason})`);
  }
  return lines.join("\n");
}

/**
 * Why `--fail-on-health` refuses this report, or `null` when it passes.
 *
 * Passing requires a measured, healthy graph. An index that is absent, not
 * built, or unreadable does not pass by default: the caller asked for a gate,
 * and a gate that could not measure its subject must not report the same
 * thing as one that measured it and found it clean. Without the flag the
 * report's exit is unchanged, so nothing that reads this surface today moves.
 */
function healthGateRefusal(report: CodegraphReport): string | null {
  const idx = report.index;
  if (idx.state !== "indexed") {
    const detail = idx.reason ? ` (${idx.reason})` : "";
    return `index state is ${idx.state}${detail}, so graph health was never measured`;
  }
  if (!idx.health) {
    return "the report carries no graph-health block, so graph health was never measured";
  }
  if (idx.health.ok) return null;
  return `graph health: ${summarizeGraphHealth(idx.health)}`;
}

function codegraphReportVerb(argv: ReadonlyArray<string>): number {
  const { flags, positional } = parseFlags(argv, {
    vault: { type: "string" },
    "fail-on-health": { type: "boolean" },
  });
  if (positional.length > 0) {
    throw new CliError(
      `partner codegraph report does not accept positional arguments: ${positional.join(" ")}`,
    );
  }
  const vaultFlag = flags["vault"] as string | undefined;
  const asJson = Boolean(flags["json"]);
  const report = buildCodegraphReport({ cwd: process.cwd(), vault: resolveScopeVault(vaultFlag) });
  if (asJson) {
    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
  } else {
    process.stdout.write(renderCodegraphReport(report) + "\n");
  }
  if (!flags["fail-on-health"]) return 0;
  const refusal = healthGateRefusal(report);
  if (refusal === null) return 0;
  process.stderr.write(`error: --fail-on-health: ${refusal}\n`);
  return EXIT_HEALTH_REFUSED;
}

/**
 * The repository the resync recipe is rendered for: the explicit `--project`
 * when given, otherwise the first project the same scan the report uses finds.
 * An empty scan is an error rather than a recipe for nothing - a cron job
 * pointed at no repository would run forever and index nothing.
 */
function resolveResyncProject(
  projectFlag: string | undefined,
  vaultFlag: string | undefined,
): string {
  if (projectFlag !== undefined) {
    const resolved = resolve(projectFlag);
    if (!isDir(resolved)) {
      throw new CliError(`--project ${projectFlag} is not a readable directory`);
    }
    return resolved;
  }
  const found = findCodeProjects({ cwd: process.cwd(), vault: resolveScopeVault(vaultFlag) });
  const first = found[0];
  if (first === undefined) {
    throw new CliError(
      "no code project in scope: pass --project <path> to name the repository to resync",
    );
  }
  return first;
}

/**
 * Render the resync cron recipe. `--cron-template` is required and has no
 * default-on twin: without it there is nothing this verb could honestly do.
 * Doing nothing quietly would be the silence this surface exists to end, and
 * running the partner's indexer would break the module invariant that OSB
 * never writes into the external tool's store. So it is a usage error.
 */
function codegraphResyncVerb(argv: ReadonlyArray<string>): number {
  const { flags, positional } = parseFlags(argv, {
    vault: { type: "string" },
    project: { type: "string" },
    interval: { type: "string" },
    format: { type: "string" },
    "cron-template": { type: "boolean" },
  });
  if (positional.length > 0) {
    throw new CliError(
      `partner codegraph resync does not accept positional arguments: ${positional.join(" ")}`,
    );
  }
  if (!flags["cron-template"]) {
    throw new CliError(
      "partner codegraph resync requires --cron-template: this verb only prints a cron " +
        "recipe for the operator to install, and never runs an indexer itself",
    );
  }
  const projectPath = resolveResyncProject(
    flags["project"] as string | undefined,
    flags["vault"] as string | undefined,
  );
  const interval = (flags["interval"] as string | undefined) ?? DEFAULT_RESYNC_INTERVAL;
  try {
    const format = parseRecipeFormat(flags["format"] as string | undefined);
    process.stdout.write(renderCodegraphResyncTemplate(projectPath, interval, { format }));
  } catch (err) {
    if (err instanceof CronTemplateError) {
      process.stderr.write(`error: ${err.message}\n`);
      return EXIT_INTERVAL_REFUSED;
    }
    throw err;
  }
  return 0;
}

/** Every codegraph verb, in one table the manifest ratchet enumerates. */
const CODEGRAPH_VERBS: Readonly<Record<string, (argv: ReadonlyArray<string>) => number>> =
  Object.freeze({
    report: codegraphReportVerb,
    resync: codegraphResyncVerb,
  });

export async function handlePartnerSubcommand(argv: ReadonlyArray<string>): Promise<number> {
  const partner = argv[0];
  const verb = argv[1];
  const rest = argv.slice(2);

  if (partner === "codegraph") {
    const handler = verb === undefined ? undefined : CODEGRAPH_VERBS[verb];
    if (handler !== undefined) return handler(rest);
    process.stderr.write(`error: unknown partner codegraph subcommand: ${verb ?? "(none)"}\n`);
    process.stderr.write(PARTNER_USAGE);
    return 2;
  }
  process.stderr.write(`error: unknown partner: ${partner ?? "(none)"}\n`);
  process.stderr.write(PARTNER_USAGE);
  return 2;
}