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.5 KB
Raw Blame
/**
 * `o2b brain git <ingest|status|find>` (Project History Suite,
 * t_c812752c): git history as Second Brain memory. `ingest` walks a
 * worktree read-only and lands records + digest in the vault, `status`
 * reports per-repo watermarks, `find` answers "why/when did this
 * change" from the store - no live git calls on the query path, so the
 * answers work even when the repo is gone.
 */

import { mineCommitDecisions } from "../../../core/brain/git/decisions.ts";
import { GitIngestError, ingestGitHistory } from "../../../core/brain/git/ingest.ts";
import { listGitCommits, listGitRepos, listGitTags } from "../../../core/brain/git/store.ts";
import type { GitCommitFilter, GitCommitRecord } from "../../../core/brain/git/store.ts";
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { emitNextStep, type AdvisoryStream } from "../../advisory-rail.ts";
import { brainVerbContext, fail, ok, okJson, parse } from "../helpers.ts";

const USAGE = "usage: o2b brain git <ingest|status|find|mine> [args] [--vault V] [--json]";

const FIND_DEFAULT_LIMIT = 20;

/**
 * Advisory stream for this verb (no-dead-ends, task 5). Two subverbs
 * reach the same "nothing ingested yet" state, and both used to carry
 * their own `(run: o2b brain git ingest <repo-path>)` parenthetical
 * inside the status line. One registry code, one rail, one shape.
 */
function gitAdvisoryStream(argv: ReadonlyArray<string>, jsonRequested: boolean): AdvisoryStream {
  return { command: "brain", argv, jsonRequested };
}

export async function cmdBrainGit(argv: string[]): Promise<number> {
  const action = argv[0];
  if (action === "ingest") return cmdIngest(argv.slice(1));
  if (action === "status") return cmdStatus(argv.slice(1));
  if (action === "find") return cmdFind(argv.slice(1));
  if (action === "mine") return cmdMine(argv.slice(1));
  return fail(USAGE);
}

async function cmdMine(argv: string[]): Promise<number> {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
    repo: { type: "string" },
  });
  try {
    const vault = brainVerbContext(flags).vault;
    const repoFilter = flags["repo"] as string | undefined;
    const repos = listGitRepos(vault).filter(
      (entry) => repoFilter === undefined || entry.key === repoFilter,
    );
    if (repoFilter !== undefined && repos.length === 0) {
      return fail(`no ingested git history for repo key: ${repoFilter}`);
    }
    const results = repos.map((entry) => mineCommitDecisions(vault, entry.key));
    if (flags["json"] === true) {
      okJson({
        ok: true,
        repos: results.map((res) => ({
          repo_key: res.repoKey,
          scanned: res.scanned,
          candidates: res.candidates,
          created: res.created,
          skipped_existing: res.skippedExisting,
          notes: res.notes,
        })),
        // no-dead-ends, phase 3: the rail returns the resolved step when
        // it suppresses the line; this payload carries it.
        ...(results.length === 0 ? nextCommandField("git-history-absent") : {}),
      });
      return 0;
    }
    if (results.length === 0) {
      ok("no git history ingested yet");
      // The `--json` branch above returned, so this stream is provably
      // a human one.
      emitNextStep("git-history-absent", gitAdvisoryStream(argv, false));
      return 0;
    }
    for (const res of results) {
      ok(
        `${res.repoKey}: ${res.scanned} commit(s) scanned, ${res.created} new ` +
          `candidate(s), ${res.skippedExisting} already curated`,
      );
    }
    return 0;
  } catch (err) {
    return fail(err instanceof Error ? err.message : String(err));
  }
}

async function cmdIngest(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
    "max-count": { type: "string" },
  });
  const target = positional[0];
  if (!target) return fail("brain git ingest requires a repository path");
  let maxCount: number | undefined;
  if (flags["max-count"] !== undefined) {
    maxCount = Number.parseInt(flags["max-count"] as string, 10);
    if (!Number.isInteger(maxCount) || maxCount < 1) {
      return fail("--max-count must be a positive integer");
    }
  }
  try {
    const vault = brainVerbContext(flags).vault;
    const res = ingestGitHistory(vault, target, maxCount !== undefined ? { maxCount } : {});
    if (flags["json"] === true) {
      okJson({
        ok: true,
        repo_key: res.repoKey,
        repo_path: res.repoPath,
        mode: res.mode,
        new_commits: res.newCommits,
        skipped_records: res.skippedCommits,
        new_tags: res.newTags,
        watermark: res.watermark,
        digest_path: res.digestPath,
        warning: res.warning,
      });
      return 0;
    }
    ok(
      `${res.mode} ingest of ${res.repoKey}: ${res.newCommits} new commit(s), ` +
        `${res.newTags} new tag(s)`,
    );
    if (res.warning !== null) ok(`warning: ${res.warning}`);
    ok(`digest: ${res.digestPath}`);
    return 0;
  } catch (err) {
    if (err instanceof GitIngestError) return fail(err.message);
    return fail(err instanceof Error ? err.message : String(err));
  }
}

async function cmdStatus(argv: string[]): Promise<number> {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
  });
  try {
    const vault = brainVerbContext(flags).vault;
    const repos = listGitRepos(vault).map((entry) => ({
      key: entry.key,
      repo_path: entry.state?.repoPath ?? null,
      last_sha: entry.state?.lastSha ?? null,
      last_ingested_at: entry.state?.lastIngestedAt ?? null,
      state_error: entry.stateError,
      commits: listGitCommits(vault, entry.key).length,
      tags: listGitTags(vault, entry.key).length,
    }));
    if (flags["json"] === true) {
      okJson({
        ok: true,
        repos,
        ...(repos.length === 0 ? nextCommandField("git-history-absent") : {}),
      });
      return 0;
    }
    if (repos.length === 0) {
      ok("no git history ingested yet");
      // The `--json` branch above returned; this stream is human.
      emitNextStep("git-history-absent", gitAdvisoryStream(argv, false));
      return 0;
    }
    for (const repo of repos) {
      const mark = repo.last_sha === null ? "no watermark" : repo.last_sha.slice(0, 7);
      const err = repo.state_error === null ? "" : ` [state error: ${repo.state_error}]`;
      ok(`${repo.key}: ${repo.commits} commit(s), ${repo.tags} tag(s), watermark ${mark}${err}`);
    }
    return 0;
  } catch (err) {
    return fail(err instanceof Error ? err.message : String(err));
  }
}

async function cmdFind(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
    repo: { type: "string" },
    file: { type: "string" },
    author: { type: "string" },
    since: { type: "string" },
    until: { type: "string" },
    limit: { type: "string" },
  });
  const text = positional[0];
  if (
    text === undefined &&
    flags["file"] === undefined &&
    flags["author"] === undefined &&
    flags["since"] === undefined &&
    flags["until"] === undefined
  ) {
    return fail(
      "brain git find requires a query: free text and/or --file/--author/--since/--until",
    );
  }
  let limit = FIND_DEFAULT_LIMIT;
  if (flags["limit"] !== undefined) {
    limit = Number.parseInt(flags["limit"] as string, 10);
    if (!Number.isInteger(limit) || limit < 1) return fail("--limit must be a positive integer");
  }
  try {
    const vault = brainVerbContext(flags).vault;
    const filter: GitCommitFilter = {
      ...(text !== undefined ? { text } : {}),
      ...(flags["file"] !== undefined ? { file: flags["file"] as string } : {}),
      ...(flags["author"] !== undefined ? { author: flags["author"] as string } : {}),
      ...(flags["since"] !== undefined ? { since: flags["since"] as string } : {}),
      ...(flags["until"] !== undefined ? { until: flags["until"] as string } : {}),
    };
    const repoFilter = flags["repo"] as string | undefined;
    const repos = listGitRepos(vault).filter(
      (entry) => repoFilter === undefined || entry.key === repoFilter,
    );
    const matches: Array<{ repoKey: string; commit: GitCommitRecord }> = [];
    for (const entry of repos) {
      for (const commit of listGitCommits(vault, entry.key, filter)) {
        matches.push({ repoKey: entry.key, commit });
      }
    }
    matches.sort(
      (a, b) =>
        Date.parse(b.commit.committedAt) - Date.parse(a.commit.committedAt) ||
        a.commit.sha.localeCompare(b.commit.sha),
    );
    const limited = matches.slice(0, limit);
    if (flags["json"] === true) {
      okJson({
        ok: true,
        total: matches.length,
        commits: limited.map((m) => ({
          repo_key: m.repoKey,
          sha: m.commit.sha,
          committed_at: m.commit.committedAt,
          author: m.commit.authorName,
          subject: m.commit.subject,
          release: m.commit.release,
          files: m.commit.files,
        })),
      });
      return 0;
    }
    if (matches.length === 0) {
      ok("no matching commits");
      return 0;
    }
    for (const m of limited) {
      const release = m.commit.release === null ? "" : ` [${m.commit.release}]`;
      ok(
        `${m.commit.committedAt.slice(0, 10)} ${m.commit.sha.slice(0, 7)} ` +
          `(${m.repoKey}) ${m.commit.subject}${release}`,
      );
    }
    if (matches.length > limited.length) {
      ok(`... ${matches.length - limited.length} more (raise --limit)`);
    }
    return 0;
  } catch (err) {
    return fail(err instanceof Error ? err.message : String(err));
  }
}