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
6.3 KB
Raw Blame
/**
 * `o2b brain page-dedup` - scan the vault for pages that share a
 * normalised dedup key and (optionally) merge them.
 *
 * Default mode is read-only listing. `--apply` performs the merge
 * for every reported candidate: writes `merged_into:` on each
 * secondary and rewrites `[[<secondary>]]` references across the
 * vault to point at the canonical page. A merge attempt that refuses
 * (a MergeChainError) or cannot write its links is collected and
 * reported per cluster; the remaining clusters still apply, and the
 * run exits 1 when any failure was collected.
 */

import type { DedupCandidate } from "../../../core/brain/page-dedup.ts";
import {
  findDuplicateCandidates,
  mergePage,
  PatchWikilinksError,
} from "../../../core/brain/page-dedup.ts";
import { brainVerbContext, fail, okJson, parse } from "../helpers.ts";

/**
 * One merge attempt that refused to land: the cluster's dedup key, the
 * SECONDARY that refused (review L8 - a cluster can hold several, and a
 * report that names only the cluster leaves the operator guessing which
 * page is still awaiting a decision), and the named error. A chain refusal
 * (MergeChainError) writes nothing, so the secondary is left exactly as it
 * was. A link-pass refusal can arrive AFTER the `merged_into:` stamp has
 * landed on the secondary - by then the merge is half-applied, and
 * {@link DedupApplyFailure.wikilinksUpdated} carries how many files the
 * rewrite repointed before the write that refused.
 */
export interface DedupApplyFailure {
  readonly key: string;
  /** The id of the secondary whose merge refused. */
  readonly secondary: string;
  readonly message: string;
  /**
   * Files the link pass rewrote before the write that refused, present
   * only when the failure came after the rewrite had already run. Absent
   * means the secondary is untouched, not zero.
   */
  readonly wikilinksUpdated?: number;
}

/** What one apply pass over a set of candidates did. */
export interface DedupApplyReport {
  readonly merged: number;
  readonly wikilinksUpdated: number;
  /** Per-attempt failures, in cluster order; empty on a clean apply. */
  readonly failures: ReadonlyArray<DedupApplyFailure>;
}

/**
 * Merge every secondary into its canonical, collecting per-attempt failures
 * instead of throwing: one cluster's MergeChainError (or one blocked wikilink
 * write) leaves every later cluster still applied. The report carries the
 * honest counts alongside the failures, so the caller can exit non-zero
 * without re-deriving what landed.
 */
export function applyDedupCandidates(
  vault: string,
  candidates: ReadonlyArray<DedupCandidate>,
): DedupApplyReport {
  let mergedCount = 0;
  let wikilinksTouched = 0;
  const failures: DedupApplyFailure[] = [];
  for (const c of candidates) {
    for (const s of c.secondaries) {
      try {
        const res = mergePage(vault, s.id, c.canonical.id);
        mergedCount++;
        wikilinksTouched += res.wikilinksUpdated;
      } catch (err) {
        // A late failure (PatchWikilinksError) means the stamp landed and
        // part of the rewrite did too: keep the partial count on the
        // failure and fold it into the aggregate, which counts files the
        // vault actually took, not only the ones behind a clean merge.
        const partial = err instanceof PatchWikilinksError ? err.rewritten : undefined;
        if (partial !== undefined) wikilinksTouched += partial;
        failures.push({
          key: c.key,
          secondary: s.id,
          message: (err as Error)?.message ?? String(err),
          ...(partial === undefined ? {} : { wikilinksUpdated: partial }),
        });
      }
    }
  }
  return {
    merged: mergedCount,
    wikilinksUpdated: wikilinksTouched,
    failures: Object.freeze(failures),
  };
}

export async function cmdBrainPageDedup(argv: string[]): Promise<number> {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    apply: { type: "boolean" },
    json: { type: "boolean" },
    yes: { type: "boolean" },
  });
  const { vault } = brainVerbContext(flags);

  const apply = Boolean(flags["apply"]);
  if (apply && !flags["yes"] && (flags["json"] || !process.stdin.isTTY)) {
    return fail("brain page-dedup --apply requires --yes in non-interactive mode");
  }

  const report = findDuplicateCandidates(vault);

  if (!apply) {
    if (flags["json"]) {
      okJson({
        scanned: report.scanned,
        candidates: report.candidates.map((c) => ({
          key: c.key,
          canonical: c.canonical.id,
          secondaries: c.secondaries.map((s) => s.id),
        })),
      });
      return 0;
    }
    process.stdout.write(`pages scanned: ${report.scanned}\n`);
    process.stdout.write(`duplicate clusters: ${report.candidates.length}\n`);
    for (const c of report.candidates) {
      process.stdout.write(`\ncanonical: ${c.canonical.id}  (topic: ${c.canonical.topic})\n`);
      for (const s of c.secondaries) {
        process.stdout.write(`  -> ${s.id}\n`);
      }
    }
    if (report.candidates.length === 0) {
      process.stdout.write("no duplicate clusters detected.\n");
    } else {
      process.stdout.write("\nre-run with --apply --yes to merge.\n");
    }
    return 0;
  }

  const applied = applyDedupCandidates(vault, report.candidates);
  // Collected failures are an honest non-zero exit, not a crash: every
  // merge that could land did land, and the failures name what did not.
  const exitCode = applied.failures.length > 0 ? 1 : 0;

  if (flags["json"]) {
    okJson({
      scanned: report.scanned,
      clusters: report.candidates.length,
      merged: applied.merged,
      wikilinks_updated: applied.wikilinksUpdated,
      failures: applied.failures.map((f) => ({
        key: f.key,
        secondary: f.secondary,
        message: f.message,
        ...(f.wikilinksUpdated === undefined ? {} : { wikilinks_updated: f.wikilinksUpdated }),
      })),
    });
    return exitCode;
  }
  process.stdout.write(`merged ${applied.merged} page(s) into canonicals.\n`);
  process.stdout.write(`wikilinks updated: ${applied.wikilinksUpdated}\n`);
  for (const f of applied.failures) {
    const partial =
      f.wikilinksUpdated === undefined ? "" : ` (wikilinks updated first: ${f.wikilinksUpdated})`;
    process.stdout.write(
      `failed cluster ${f.key}, secondary ${f.secondary}: ${f.message}${partial}\n`,
    );
  }
  return exitCode;
}