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
5.5 KB
Raw Blame
/**
 * `o2b vault inspect <relpath>` — point-check one vault-relative path.
 *
 * Anchored in `docs/plans/2026-05-19-vault-scope-design.md` §7.2.
 *
 * Reports TWO independent verdicts about the same path, because they
 * answer different questions and an operator who conflates them will
 * look in the wrong file:
 *
 *   - VAULT SCOPE — is this path part of the vault at all? Governs every
 *     walker (indexer, scanners) and is declared in `vault.ignore_paths`
 *     and `vault.include_paths`. The refusal names which of the two
 *     decided, because they are different lists to go and fix.
 *   - WRITE BINDING — may a CALLER-NAMED write author here? Governs
 *     `brain_create_note` and the update / append / batch arms, and is
 *     declared in `write_binding.path_prefixes`
 *     (provenance-at-the-boundary, unit B).
 *
 * This verb is the registered exit for `write-binding-refused`, so the
 * binding half is not decoration: it is the surface that answers the
 * question the refusal raises.
 */

import { defaultConfigPath } from "../../../core/config.ts";
import { inspectPath, resolveVaultScope } from "../../../core/vault-scope/index.ts";
import { resolveWriteBinding, writeBindingAdmits } from "../../../core/write-binding/index.ts";
import { CliError, parseFlags } from "../../argparse.ts";
import { resolveBrainVault } from "../../brain/helpers.ts";
import { fail, info, writeJson } from "../../output.ts";

export async function cmdVaultInspect(argv: ReadonlyArray<string>): Promise<number> {
  const { flags, positional } = parseFlags(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
  });
  const relpath = positional[0];
  if (!relpath) {
    process.stderr.write("error: usage: o2b vault inspect <relpath> [--vault <path>] [--json]\n");
    return 2;
  }
  const config = defaultConfigPath();
  let vault: string;
  try {
    vault = resolveBrainVault(flags["vault"] as string | undefined, config);
  } catch (exc) {
    if (exc instanceof CliError) return fail(exc.message);
    throw exc;
  }
  let result: ReturnType<typeof inspectPath>;
  let binding: ReturnType<typeof resolveWriteBinding>;
  try {
    const scope = resolveVaultScope(vault);
    result = inspectPath(relpath, scope, vault);
    binding = resolveWriteBinding(vault);
  } catch (exc) {
    process.stderr.write(`error: ${(exc as Error).message ?? exc}\n`);
    return 2;
  }
  // Three states, not two. "No binding is declared" is a different
  // answer from "a binding is declared and admits this path", and
  // collapsing them would tell an operator their boundary is working
  // when they never declared one.
  const bindingAdmits = binding === null ? null : writeBindingAdmits(binding, result.relPath);
  // Per design §7.2: the rule decision is meaningful even for paths
  // that do not exist on disk (operator may be checking the policy
  // before authoring the file), but the operator should know
  // whether the answer applies to a real path or a hypothetical one.
  const notFoundSuffix = result.existsOnDisk ? "" : " (not found on disk)";
  if (flags["json"]) {
    writeJson({
      relpath: result.relPath,
      status: result.excluded ? "excluded" : "included",
      reason: result.reason,
      exists_on_disk: result.existsOnDisk,
      matched_rule: result.rule ? { raw: result.rule.raw, kind: result.rule.kind } : null,
      matched_at: result.matchedAt,
      source: result.source,
      index_admitted: result.indexAdmitted,
      index_refusal: result.admissionReason,
      write_binding:
        binding === null
          ? { declared: false }
          : {
              declared: true,
              admits: bindingAdmits,
              path_prefixes: binding.pathPrefixes,
            },
    });
    return 0;
  }
  info(`relpath:      ${result.relPath}`);
  if (!result.excluded) {
    info(`status:       included${notFoundSuffix}`);
    reportIndexAdmission(result);
    reportWriteBinding(binding, bindingAdmits);
    return 0;
  }
  info(`status:       excluded${notFoundSuffix}`);
  info(`reason:       ${refusalSentence(result)}`);
  if (result.rule) info(`matched rule: ${result.rule.raw} (${result.rule.kind})`);
  if (result.matchedAt) info(`matched at:   ${result.matchedAt}`);
  info(`source:       ${result.source}`);
  reportWriteBinding(binding, bindingAdmits);
  return 0;
}

/**
 * Which polarity refused, in the operator's own vocabulary: the key
 * they have to open. An exclusion has an entry to point at; an
 * allowlist refusal has none, and saying "excluded" alone would send
 * them to read the wrong list.
 */
function refusalSentence(result: ReturnType<typeof inspectPath>): string {
  return result.reason === "not-included"
    ? "outside vault.include_paths"
    : "excluded by vault.ignore_paths";
}

/**
 * The third verdict, printed only when it disagrees with the scope one.
 * A path can be part of the vault and still never enter the index - the
 * exact-state lane is - and reporting only "included" told an operator
 * the file was searchable.
 */
function reportIndexAdmission(result: ReturnType<typeof inspectPath>): void {
  if (result.indexAdmitted) return;
  info(`index:        not indexed (${result.admissionReason ?? "refused"})`);
}

/** Human-stream rendering of the three write-binding states. */
function reportWriteBinding(
  binding: ReturnType<typeof resolveWriteBinding>,
  admits: boolean | null,
): void {
  if (binding === null) {
    info("write binding: none declared");
    return;
  }
  info(`write binding: ${admits === true ? "admits" : "refuses"} caller-named writes`);
  info(`  prefixes:    ${binding.pathPrefixes.join(", ")}`);
}