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
13.8 KB
Raw Blame
/**
 * Vault graph export/import (Vault portability suite, Feature 5).
 *
 * `exportVaultGraph` serialises the user's vault pages (excluding the
 * Brain machinery root and the standard ignored dirs) into a stable,
 * sorted `graph.json`: one node per page with its wikilinks and typed
 * relations. Re-export is byte-identical (everything sorted, no
 * timestamps), so the format is a deterministic interchange artifact.
 *
 * The importer (`importVaultGraph`, Feature 5 Task 4) reconstructs page
 * stubs under three conflict modes. It refuses a node per entry rather
 * than aborting the run: an unreadable shape, a path that escapes the
 * vault, and a node whose path or title carries the redactor's
 * placeholder all land in `rejected` while the rest of the graph imports.
 * See {@link hasRedactedIdentity} for why a lost name is a refusal and not
 * a lossy import.
 */

import { existsSync, mkdirSync } from "node:fs";
import { dirname, join, posix, relative } from "node:path";

import {
  EXCLUDED_DIRS,
  extractWikilinks,
  listVaultPages,
  parseFrontmatter,
  writeFrontmatterAtomic,
} from "../../vault.ts";
import type { FrontmatterMap } from "../../types.ts";
import {
  extractFrontmatterRelations,
  normalizeRelationTarget,
} from "../../graph/frontmatter-relations.ts";
import { REDACTION_PLACEHOLDER } from "../../redactor.ts";
import { BRAIN_ROOT_REL, ensureInsideVault, isUnderBrainRoot } from "../paths.ts";
import { realVaultRelative } from "../../path-safety.ts";
import { loadVaultMap, resolveTokens } from "./role-tokens.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";

export const GRAPH_VERSION = "1";

/** Typed-relation frontmatter fields (v0.19.0) carried in the graph. */
export const RELATION_FIELDS = ["related", "extends", "contradicts", "superseded_by"] as const;

export interface VaultGraphNode {
  /** Obsidian basename id (wikilink target). */
  readonly id: string;
  /** Vault-relative POSIX path. */
  readonly path: string;
  readonly title: string;
  /** Sorted, de-duplicated wikilink targets in the body. */
  readonly links: ReadonlyArray<string>;
  /** Typed relations -> sorted target lists (only non-empty fields present). */
  readonly relations: Readonly<Record<string, ReadonlyArray<string>>>;
}

export interface VaultGraph {
  readonly version: string;
  readonly nodes: ReadonlyArray<VaultGraphNode>;
}

function stem(path: string): string {
  const base = path.split(/[\\/]/).pop() ?? path;
  return base.replace(/\.md$/i, "");
}

function sortedUnique(values: Iterable<string>): string[] {
  return [...new Set([...values].filter((v) => v.length > 0))].toSorted();
}

function collectRelations(meta: FrontmatterMap): Record<string, ReadonlyArray<string>> {
  const grouped = new Map<string, string[]>();
  for (const edge of extractFrontmatterRelations(meta)) {
    const arr = grouped.get(edge.relation);
    if (arr) arr.push(edge.target);
    else grouped.set(edge.relation, [edge.target]);
  }
  const out: Record<string, ReadonlyArray<string>> = {};
  for (const [relation, targets] of grouped) out[relation] = sortedUnique(targets);
  return out;
}

/**
 * Export every user vault page (Brain machinery excluded) as a stable,
 * sorted graph. Pure and read-only.
 */
export function exportVaultGraph(vault: string): VaultGraph {
  const pages = listVaultPages(vault, {
    skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL],
    reach: MAINTENANCE_LANE_REACH,
  });
  const nodes: VaultGraphNode[] = [];
  for (const page of pages) {
    let body: string;
    let meta: FrontmatterMap;
    try {
      const [m, b] = parseFrontmatter(page.path);
      meta = m;
      body = b;
    } catch {
      continue;
    }
    const links = sortedUnique(
      extractWikilinks(body)
        .map((t) => normalizeRelationTarget(t))
        .filter((t): t is string => t !== null),
    );
    nodes.push({
      id: stem(page.path),
      path: relative(vault, page.path).split(/[\\/]/).join(posix.sep),
      title: page.title,
      links,
      relations: collectRelations(meta),
    });
  }
  nodes.sort((a, b) =>
    a.id < b.id ? -1 : a.id > b.id ? 1 : a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
  );
  return { version: GRAPH_VERSION, nodes };
}

// ----- Import --------------------------------------------------------------

export type GraphImportMode = "skip" | "overwrite" | "merge";

export interface GraphImportResult {
  readonly created: string[];
  readonly skipped: string[];
  readonly overwritten: string[];
  readonly merged: string[];
  /**
   * Node paths the importer refused: a node whose shape is not readable,
   * one whose path escapes the vault, and one whose path or title carries
   * the redactor's placeholder (see {@link hasRedactedIdentity}).
   */
  readonly rejected: string[];
}

/** Shape the importer reads from a graph node (loosely typed for JSON input). */
interface GraphNodeInput {
  readonly path: string;
  readonly title?: string;
  readonly links?: ReadonlyArray<string>;
  readonly relations?: Readonly<Record<string, ReadonlyArray<string>>>;
}

const isStringArray = (v: unknown): boolean =>
  Array.isArray(v) && v.every((item) => typeof item === "string");

/**
 * Runtime guard for one untrusted JSON node. `path` must be a string;
 * `title` (when present) a string; `links` a string array; `relations`
 * a plain object whose every value is a string array. Anything else is
 * rejected so the import skips it rather than throwing mid-run.
 */
function isValidGraphNode(node: unknown): node is GraphNodeInput {
  if (!node || typeof node !== "object") return false;
  const n = node as Record<string, unknown>;
  if (typeof n["path"] !== "string") return false;
  if (n["title"] !== undefined && typeof n["title"] !== "string") return false;
  if (n["links"] !== undefined && !isStringArray(n["links"])) return false;
  if (n["relations"] !== undefined) {
    const rel = n["relations"];
    if (!rel || typeof rel !== "object" || Array.isArray(rel)) return false;
    if (!Object.values(rel).every((targets) => isStringArray(targets))) return false;
  }
  return true;
}

/**
 * Whether a node lost the identity that names it.
 *
 * A graph node is addressed by its `path` and displayed by its `title`,
 * and {@link REDACTION_PLACEHOLDER} is a single constant: two nodes
 * redacted in the same field are not two anonymous pages, they are one
 * path, and importing both writes the second over the first while
 * reporting two creations. The page a redacted path names cannot be
 * recovered from the bundle, so the node is refused.
 *
 * `links` and `relations` are deliberately NOT checked: those name OTHER
 * pages. A target that no longer resolves is a dangling wikilink, which is
 * the vault's ordinary state and what the stub-scaffolding verb is for -
 * losing a reference is not losing this node's identity.
 */
function hasRedactedIdentity(node: GraphNodeInput): boolean {
  if (node.path.includes(REDACTION_PLACEHOLDER)) return true;
  return node.title !== undefined && node.title.includes(REDACTION_PLACEHOLDER);
}

/**
 * Render a deterministic page stub. Single-target relations land in
 * frontmatter (the only form OSB's frontmatter parser round-trips);
 * body wikilinks list the links. Multi-target relations are flattened
 * into the body links (type not preserved - a documented limitation of
 * the frontmatter parser).
 *
 * Exported for `notes/scaffold-stub.ts` (B3), which materialises a note
 * for a dangling wikilink target. That verb needs exactly this shape and
 * for exactly this reason: every byte it emits is DERIVED - the title
 * from the target the link spelled, the body links from the documents the
 * index says referenced it - so a scaffolded note contains no prose
 * pretending to be the user's.
 */
export function renderStub(
  title: string,
  links: ReadonlyArray<string>,
  relations: Readonly<Record<string, ReadonlyArray<string>>>,
): [FrontmatterMap, string] {
  const meta: FrontmatterMap = { title };
  const bodyTargets = new Set(links);
  for (const [relation, targets] of Object.entries(relations)) {
    if (targets.length === 1) meta[relation] = `[[${targets[0]}]]`;
    else for (const t of targets) bodyTargets.add(t);
  }
  const sorted = [...bodyTargets].filter((t) => t.length > 0).toSorted();
  const body = sorted.length > 0 ? sorted.map((t) => `- [[${t}]]`).join("\n") + "\n" : "";
  return [meta, body];
}

function readExisting(path: string): { links: string[]; relations: Record<string, string[]> } {
  const [meta, body] = parseFrontmatter(path);
  const links = extractWikilinks(body)
    .map((t) => normalizeRelationTarget(t))
    .filter((t): t is string => t !== null);
  const relations: Record<string, string[]> = {};
  for (const edge of extractFrontmatterRelations(meta)) {
    (relations[edge.relation] ??= []).push(edge.target);
  }
  return { links, relations };
}

/**
 * Reconstruct vault page stubs from a graph under one conflict mode.
 * `skip` (default) never overwrites and is idempotent; `overwrite`
 * replaces; `merge` unions wikilinks + relations with the existing page.
 * Every write is guarded by {@link ensureInsideVault}.
 */
export function importVaultGraph(
  vault: string,
  // Untrusted input (JSON from a graph.json or a bank bundle); every node
  // is shape-guarded per entry below, so the element type is `unknown`
  // rather than a structural promise the runtime does not enforce.
  graph: { nodes?: ReadonlyArray<unknown> },
  opts: { mode?: GraphImportMode } = {},
): GraphImportResult {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  const mode: GraphImportMode = opts.mode ?? "skip";
  const result: GraphImportResult = {
    created: [],
    skipped: [],
    overwritten: [],
    merged: [],
    rejected: [],
  };

  const vaultMap = loadVaultMap(vault);
  // Guard the container shape: a non-array `nodes` (string, object, scalar)
  // from untrusted JSON would otherwise throw or mis-iterate. Per-entry
  // validation below still rejects each malformed element.
  const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
  for (const node of nodes) {
    // Validate the node shape per entry: a single malformed JSON node is
    // rejected and the import continues, instead of throwing and aborting
    // the whole run. `graph` arrives from untrusted JSON, so the static
    // GraphNodeInput type is not a runtime guarantee.
    if (!isValidGraphNode(node)) {
      result.rejected.push(String((node as { path?: unknown })?.path ?? "<invalid-node>"));
      continue;
    }
    // A node whose own name was redacted before it reached this bundle.
    // The export boundary refuses to emit one; a bundle written by an
    // earlier build, or scrubbed by another tool, can still carry it.
    if (hasRedactedIdentity(node)) {
      result.rejected.push(node.path);
      continue;
    }
    // Resolve `{{role}}` tokens in the target path via the vault-map so a
    // portable graph can address user folders abstractly (v0.22.0).
    const relPath = resolveTokens(vaultMap, node.path);
    // The `Brain/` machinery root is not addressable from an untrusted
    // graph bundle, in any mode. `skip` would still CREATE a missing
    // target and `overwrite` rewrites existing files, so without this
    // refusal a bundle could plant or replace standing rules, vault
    // identity, or the write binding's own config - the same wall the
    // note-target envelope applies to every caller-named note write.
    //
    // The wall reads the path the way the filesystem will: separators
    // normalized (`\` is one on Windows), `.`/`..` collapsed
    // (`./Brain/x`, `x/../Brain/x`), and the Brain segment compared
    // case-insensitively (`brain/x` opens `Brain/` on macOS and
    // Windows). A second read after containment checks where the bytes
    // actually land, so a vault folder that is a symlink into `Brain/`
    // does not carry the write past the lexical check.
    if (isUnderBrainRoot(relPath)) {
      result.rejected.push(node.path);
      continue;
    }
    let path: string;
    try {
      path = ensureInsideVault(join(vault, relPath), vault);
    } catch {
      result.rejected.push(node.path);
      continue;
    }
    // A landing path that cannot be resolved (a note used as a folder, a
    // link loop, an unreadable folder) is rejected like any other bad
    // node rather than aborting the rest of the import.
    let landsAt: string | null;
    try {
      landsAt = realVaultRelative(vault, relative(vault, path));
    } catch {
      landsAt = null;
    }
    if (landsAt === null || isUnderBrainRoot(landsAt)) {
      result.rejected.push(node.path);
      continue;
    }
    const title = node.title ?? node.path;
    const incomingLinks = node.links ?? [];
    const incomingRelations = node.relations ?? {};
    const exists = existsSync(path);

    if (exists && mode === "skip") {
      result.skipped.push(node.path);
      continue;
    }

    let links: ReadonlyArray<string> = incomingLinks;
    let relations: Record<string, ReadonlyArray<string>> = { ...incomingRelations };
    if (exists && mode === "merge") {
      const prev = readExisting(path);
      links = [...new Set([...prev.links, ...incomingLinks])];
      const merged: Record<string, string[]> = {};
      for (const [rel, targets] of Object.entries(prev.relations)) merged[rel] = [...targets];
      for (const [rel, targets] of Object.entries(incomingRelations)) {
        merged[rel] = [...new Set([...(merged[rel] ?? []), ...targets])];
      }
      relations = merged;
    }

    const [meta, body] = renderStub(title, links, relations);
    mkdirSync(dirname(path), { recursive: true });
    writeFrontmatterAtomic(path, meta, body, { overwrite: true, vaultForRelativePath: vault });

    if (!exists) result.created.push(node.path);
    else if (mode === "merge") result.merged.push(node.path);
    else result.overwritten.push(node.path);
  }

  return result;
}