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.1 KB
Raw Blame
/**
 * Brain CLI verb-handler facade.
 *
 * # Import convention (load-bearing)
 *
 * Every file under `src/cli/brain/verbs/` MUST import shared helpers
 * through this module β€” never directly from `../argparse.ts`,
 * `../output.ts`, `../coerce.ts`, or `../helpers.ts`. The barrel
 * keeps one source of truth for "what is available to a brain verb"
 * and lets the helper bodies move between submodules without a
 * cross-cutting import sweep.
 *
 * # Layout
 *
 *   - `./help-text.ts`        β€” `BRAIN_HELP` + per-verb `VERB_HELP`.
 *   - `./upgrade-render.ts`   β€” `renderUpgradePlanJson` (the row-level
 *                               projection; this barrel wraps it to add
 *                               the plan digest), `printUpgradePlanText`,
 *                               `renderUnifiedDiff`.
 *   - `./query-render.ts`     β€” text renderers for `brain query`.
 *   - `./rollback-prompt.ts`  β€” `diffSummary`, `readSingleLine`.
 *
 * Vault resolution and the `parse` flag-parsing wrapper stay in this
 * file because they are tiny and called by every verb.
 */

import {
  defaultConfigPath,
  resolveAgentName,
  resolveTimezone,
  resolveVault,
} from "../../core/config.ts";
import { formatLocalTimestamp } from "../../core/brain/present-time.ts";
import { isoSecond } from "../../core/brain/time.ts";
import type { UpgradePlan } from "../../core/brain/upgrade.ts";

import { CliError, parseFlags, type FlagsSchema } from "../argparse.ts";
import {
  NO_VAULT_ERROR,
  NoVaultConfiguredError,
  normalizeFlagString,
  resolveOptionalVault,
  vaultRequiredMessage,
} from "../helpers.ts";
import { renderUpgradePlanJson as renderUpgradePlanJsonRows } from "./upgrade-render.ts";

// ── Vault resolution ────────────────────────────────────────────────────────

export function resolveBrainVault(flagVal: string | undefined, configPath: string | null): string {
  // Mirror `requireVault` in `../helpers.ts`: explicit `--vault ""`
  // is a user error, not an excuse to fall through to `resolveVault`.
  const explicit = normalizeFlagString(flagVal);
  if (flagVal !== undefined && explicit === null) {
    throw new CliError(NO_VAULT_ERROR);
  }
  const vault = explicit ?? resolveVault(configPath ?? undefined);
  if (vault === null || vault === undefined) {
    throw new CliError(NO_VAULT_ERROR);
  }
  return vault;
}

// ── Verb context ────────────────────────────────────────────────────────────

/** Parsed flags shape every Brain verb receives from {@link parse}. */
export type BrainVerbFlags = Record<string, string | boolean | string[] | undefined>;

export interface BrainVerbContext {
  readonly config: string;
  readonly vault: string;
}

/**
 * The verb context of a verb that also works with no vault (design D14):
 * `vault` is `null` when none is configured. A verb that needs one after
 * all (a vault-adapter step) asks {@link requireBrainVaultFor}.
 */
export interface OptionalVaultBrainVerbContext {
  readonly config: string;
  readonly vault: string | null;
}

/** Options of {@link brainVerbContext}. */
export interface BrainVerbContextOptions {
  /** `optional`: answer `vault: null` instead of refusing when none is configured. */
  readonly vault: "optional";
}

/**
 * Resolve the (config, vault) pair every Brain verb needs.
 *
 * Call it exactly where the verb used to resolve the vault β€” flag
 * validation that must precede vault resolution (and its error
 * output) stays ahead of this call, so verb output is unchanged.
 * Throws `CliError` for a missing or explicitly empty vault, same as
 * {@link resolveBrainVault}.
 */
export function brainVerbContext(flags: BrainVerbFlags): BrainVerbContext;
export function brainVerbContext(
  flags: BrainVerbFlags,
  options: BrainVerbContextOptions,
): OptionalVaultBrainVerbContext;
export function brainVerbContext(
  flags: BrainVerbFlags,
  options?: BrainVerbContextOptions,
): BrainVerbContext | OptionalVaultBrainVerbContext {
  const config = defaultConfigPath();
  const flag = flags["vault"] as string | undefined;
  if (options?.vault !== "optional") return { config, vault: resolveBrainVault(flag, config) };
  // The shared rule (an explicit empty `--vault` is a user error), with
  // the brain dispatcher's error type.
  try {
    return { config, vault: resolveOptionalVault(flag, config) };
  } catch (err) {
    if (err instanceof NoVaultConfiguredError) throw new CliError(NO_VAULT_ERROR);
    throw err;
  }
}

/**
 * The vault of an optional-vault context, or a `CliError` that names the
 * verb when there is none: `o2b brain <verb>` needs a vault here. The
 * brain dispatcher (`handleBrainSubcommand`) answers every `CliError` with
 * exit 1, the code the no-vault error always had inside `o2b brain`; it is
 * not the exit-2 usage error of the top-level commands.
 */
export function requireBrainVaultFor(context: OptionalVaultBrainVerbContext, verb: string): string {
  if (context.vault === null) throw new CliError(vaultRequiredMessage(`o2b brain ${verb}`));
  return context.vault;
}

/** Acting agent name: an explicit `--agent` flag wins over the config. */
export function resolveBrainAgent(flags: BrainVerbFlags, config: string): string {
  return (flags["agent"] as string | undefined) ?? resolveAgentName(config);
}

// ── Flag-parsing wrapper ────────────────────────────────────────────────────

export function parse(
  argv: ReadonlyArray<string>,
  schema: FlagsSchema,
): {
  flags: Record<string, string | boolean | string[] | undefined>;
  positional: string[];
} {
  return parseFlags(argv, schema);
}

// ── Re-exports (the barrel that verb handlers import from) ──────────────────

export { CliError } from "../argparse.ts";
export { describeErrorChain, fail, failWith, info, ok, okJson, writeJson } from "../output.ts";

/**
 * Usage / argument error: plain message to stderr, exit code 2. Distinct
 * from `fail()` (exit 1), which is reserved for operational/runtime
 * failures. Mirrors the exit-2 usage-error contract the brain verbs use
 * (e.g. `tune`, `bridges`).
 */
export function usageError(message: string): number {
  process.stderr.write(`error: ${message}\n`);
  return 2;
}
export { ISO_8601_RE, parseOptionalIsoDate } from "../coerce.ts";
export { NO_VAULT_ERROR, normalizeFlagString, resolveOptionalVault } from "../helpers.ts";

export { BRAIN_HELP, MAINTENANCE_USAGE, VERB_HELP } from "./help-text.ts";
export { printUpgradePlanText, renderUnifiedDiff } from "./upgrade-render.ts";

/**
 * The plan JSON an operator reads, with its seal (t_18fda844): the
 * digest carried from `--dry-run` to `--apply` via `--approval-digest`
 * (`brain upgrade --apply` requires it in non-interactive mode and
 * verifies it against the freshly computed plan, exactly as
 * import-claude-memory's does), so what lands is what was reviewed.
 * Emitted unconditionally - a `planUpgrade` result is always sealed -
 * and the row projection stays in `./upgrade-render.ts` (imported above
 * under an alias); the barrel is where the seal becomes visible, because
 * this is the module every verb imports its renderers through.
 */
export function renderUpgradePlanJson(
  plan: UpgradePlan,
): ReturnType<typeof renderUpgradePlanJsonRows> & { digest: string } {
  return { ...renderUpgradePlanJsonRows(plan), digest: plan.digest };
}
export {
  renderQueryPreferenceText,
  renderQueryRuleTopicText,
  renderQueryLogText,
} from "./query-render.ts";
export { diffSummary, readSingleLine, type DiffSummary } from "./rollback-prompt.ts";

/**
 * Timezone presentation (t_2ccadc6a): additive `timezone` +
 * `local_time` fields for JSON envelopes when the operator configured
 * an IANA zone; empty object (byte-identical output) otherwise.
 */
export function localTimeFields(configPath: string | null): Record<string, string> {
  const tz = resolveTimezone(configPath ?? undefined);
  if (tz === null) return {};
  return { timezone: tz, local_time: formatLocalTimestamp(isoSecond(new Date()), tz) };
}