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
10.5 KB
Raw Blame
/**
 * `o2b view` - the human view: the readable pages one device, the view
 * writer, renders from the brain store into a folder of the user's choice.
 *
 * Verbs:
 *
 *  - `writer`: show which device renders the view, and a move in progress;
 *  - `writer --here [--force]`: make this machine the view writer. Without
 *    `--force` the current writer releases the role at its next catch-up;
 *    with it the role moves at once, for an old writer that is unreachable;
 *  - `render`: run one render pass (only the view writer writes pages);
 *  - `recover <page> [--print <id>]`: list the replaced versions of a page
 *    from the last 30 days, or print one of them.
 *
 * The work lives in `core/view/`; this file parses flags and renders.
 */

import {
  ConfigReadError,
  resolveAgentName,
  resolveDeviceId,
  resolveVault,
} from "../core/config.ts";
import { PartitionUnavailableError } from "../core/store/appender.ts";
import { StoreOpenError, openStore, type StoreHandle } from "../core/store/store-open.ts";
import {
  resolveConfiguredStoreRoot,
  StoreRootInsideVaultError,
} from "../core/store/store-paths.ts";
import { VIEW_RECOVER_DAYS } from "../core/view/constants.ts";
import { listReplacedVersions } from "../core/view/recover.ts";
import { runViewPass, type ViewPassReport } from "../core/view/render.ts";
import { resolveViewTarget, ViewTargetError } from "../core/view/target.ts";
import { readViewWriter, requestViewWriter, type RequestResult } from "../core/view/writer.ts";
import { pendingTarget } from "../core/view/writer-fold.ts";
import { CliError, parseFlags } from "./argparse.ts";
import { sortedReplacer } from "./helpers.ts";

const USAGE = [
  "usage: o2b view writer [--here [--force]] [--config <file>] [--json]",
  "       o2b view render [--config <file>] [--json]",
  "       o2b view recover <page> [--print <id>] [--config <file>] [--json]",
].join("\n");

const VIEW_EXIT = Object.freeze({ ok: 0, refused: 1, usage: 2 } as const);

export async function handleViewSubcommand(argv: ReadonlyArray<string>): Promise<number> {
  const verb = argv[0];
  if (verb === undefined || verb === "-h" || verb === "--help") {
    process.stdout.write(`${USAGE}\n`);
    return verb === undefined ? VIEW_EXIT.usage : VIEW_EXIT.ok;
  }
  const rest = argv.slice(1);
  try {
    switch (verb) {
      case "writer":
        return cmdWriter(rest);
      case "render":
        return cmdRender(rest);
      case "recover":
        return cmdRecover(rest);
      default:
        process.stderr.write(`error: unknown view verb: ${verb}\n${USAGE}\n`);
        return VIEW_EXIT.usage;
    }
  } catch (err) {
    if (err instanceof CliError) {
      process.stderr.write(`error: ${err.message}\n${USAGE}\n`);
      return VIEW_EXIT.usage;
    }
    if (!(err instanceof Error) || !isViewFailure(err)) throw err;
    // Another pass (a hook, a second `o2b view render`) holds the render lock.
    const message = isLocked(err)
      ? "another render of the human view is in progress; try again in a moment"
      : err.message;
    if (rest.includes("--json")) {
      writeJson({ ok: false, ...(isLocked(err) ? { reason: "busy" } : {}), error: message });
    }
    process.stderr.write(`error: ${message}\n`);
    return VIEW_EXIT.refused;
  }
}

function isLocked(err: Error): boolean {
  return (err as NodeJS.ErrnoException).code === "ELOCKED";
}

/** Failures the view verbs report as an answer rather than a crash. */
function isViewFailure(err: Error): boolean {
  return (
    isLocked(err) ||
    err instanceof StoreOpenError ||
    err instanceof StoreRootInsideVaultError ||
    err instanceof ConfigReadError ||
    err instanceof ViewTargetError ||
    err instanceof PartitionUnavailableError
  );
}

function writeJson(value: unknown): void {
  process.stdout.write(`${JSON.stringify(value, sortedReplacer, 2)}\n`);
}

function openConfiguredStore(configPath: string | undefined): StoreHandle {
  const { root } = resolveConfiguredStoreRoot(configPath);
  return openStore({ root, device: resolveDeviceId(configPath) });
}

function cmdWriter(argv: ReadonlyArray<string>): number {
  const { flags, positional } = parseFlags(argv, {
    here: { type: "boolean" },
    force: { type: "boolean" },
    config: { type: "string" },
    json: { type: "boolean" },
  });
  if (positional.length > 0) throw new CliError(`unexpected argument: ${positional[0]}`);
  if (flags["force"] === true && flags["here"] !== true) {
    throw new CliError("--force moves the role here, so it needs --here");
  }
  const configPath = flags["config"] as string | undefined;
  const json = flags["json"] === true;
  const store = openConfiguredStore(configPath);
  if (flags["here"] !== true) {
    const state = readViewWriter(store);
    const pending = pendingTarget(state);
    if (json) {
      writeJson({ ok: true, writer: state.writer, pending, device: store.device });
      return VIEW_EXIT.ok;
    }
    process.stdout.write(
      state.writer === null
        ? "No machine renders the human view yet; take the role with `writer --here` on the machine that should.\n"
        : `The human view is rendered by ${state.writer}` +
            (state.writer === store.device ? " (this machine)" : "") +
            (pending !== null ? `; a move to ${pending} waits for its release` : "") +
            ".\n",
    );
    return VIEW_EXIT.ok;
  }
  const result = requestViewWriter(store, {
    agent: resolveAgentName(configPath),
    force: flags["force"] === true,
  });
  if (json) {
    writeJson({ ok: true, ...describeRequest(result), device: store.device });
    return VIEW_EXIT.ok;
  }
  process.stdout.write(`${requestMessage(result, store.device)}\n`);
  if (result.status === "forced" && result.warning !== null) {
    process.stderr.write(`warning: ${result.warning}\n`);
  }
  return VIEW_EXIT.ok;
}

function describeRequest(result: RequestResult): Record<string, unknown> {
  if (result.status === "already-writer") return { status: result.status };
  return { status: result.status, previous: result.previous, warning: result.warning };
}

function requestMessage(result: RequestResult, device: string): string {
  switch (result.status) {
    case "already-writer":
      return `This machine (${device}) already renders the human view.`;
    case "taken":
      return result.previous === device
        ? `This machine (${device}) stays the view writer; the pending move is cancelled.`
        : `This machine (${device}) now renders the human view.`;
    case "requested":
      return (
        `Asked ${result.previous} to hand the view writer role to ${device}. It releases the ` +
        "role at its next catch-up, and this machine renders once that release has synced here."
      );
    case "forced":
      return `This machine (${device}) now renders the human view; ${result.previous} did not release it.`;
  }
}

function cmdRender(argv: ReadonlyArray<string>): number {
  const { flags, positional } = parseFlags(argv, {
    config: { type: "string" },
    json: { type: "boolean" },
  });
  if (positional.length > 0) throw new CliError(`unexpected argument: ${positional[0]}`);
  const configPath = flags["config"] as string | undefined;
  const store = openConfiguredStore(configPath);
  const vault = resolveVault(configPath);
  const target = resolveViewTarget(store.root, configPath, vault);
  const report = runViewPass(store, {
    target: target?.dir ?? null,
    vault,
    agent: resolveAgentName(configPath),
  });
  // One exit rule for both forms: a pass that could not read is refused.
  const refused = report.status === "incomplete-read";
  if (flags["json"] === true) writeJson({ ok: !refused, ...report });
  else process.stdout.write(`${renderMessage(report)}\n`);
  return refused ? VIEW_EXIT.refused : VIEW_EXIT.ok;
}

function renderMessage(report: ViewPassReport): string {
  switch (report.status) {
    case "incomplete-read":
      return `Not rendered: some shards could not be read (${report.shards.join(", ")}).`;
    case "no-writer":
      return "No machine renders the human view yet; take the role with `writer --here` on the machine that should.";
    case "not-writer":
      return `This machine writes no view page: the view writer is ${report.writer}.`;
    case "released":
      return `Handed the view writer role to ${report.to}, as the user asked.`;
    case "waiting-for-claim":
      return "This machine just took the view writer role; it renders from its next catch-up.";
    case "no-target":
      return "No human view folder is configured (`view_target`), so no page was written.";
    case "rendered": {
      const lines = report.pages
        .filter((p) => p.status !== "unchanged")
        .map(
          (p) =>
            `  ${p.page}: ${p.status}` +
            (p.ingested > 0 ? `, ${p.ingested} edit(s) stored` : "") +
            (p.detail !== undefined ? ` (${p.detail})` : ""),
        );
      return lines.length === 0
        ? `Rendered ${report.pages.length} page(s); none changed.`
        : `Rendered ${report.pages.length} page(s):\n${lines.join("\n")}`;
    }
  }
}

function cmdRecover(argv: ReadonlyArray<string>): number {
  const { flags, positional } = parseFlags(argv, {
    print: { type: "string" },
    config: { type: "string" },
    json: { type: "boolean" },
  });
  if (positional.length !== 1)
    throw new CliError("recover takes one page, for example about-me.md");
  const page = positional[0]!.replaceAll("\\", "/");
  const store = openConfiguredStore(flags["config"] as string | undefined);
  const versions = listReplacedVersions(store, page);
  const wanted = flags["print"] as string | undefined;
  if (wanted !== undefined) {
    const version = versions.find((v) => v.id === wanted);
    if (version === undefined || version.text === null) {
      process.stderr.write(
        version === undefined
          ? `error: no replaced version ${wanted} of ${page} in the last ${VIEW_RECOVER_DAYS} days\n`
          : `error: the text of ${wanted} has not synced to this machine yet\n`,
      );
      return VIEW_EXIT.refused;
    }
    process.stdout.write(version.text);
    return VIEW_EXIT.ok;
  }
  if (flags["json"] === true) {
    writeJson({ ok: true, page, versions });
    return VIEW_EXIT.ok;
  }
  if (versions.length === 0) {
    process.stdout.write(
      `No replaced versions of ${page} in the last ${VIEW_RECOVER_DAYS} days.\n`,
    );
    return VIEW_EXIT.ok;
  }
  const rows = versions.map(
    (v) =>
      `  ${v.id}  ${v.at}  ${v.device}  ${v.reason}  ${v.bytes} bytes` +
      (v.text === null ? "  (not synced yet)" : ""),
  );
  process.stdout.write(
    `Replaced versions of ${page}, newest first:\n${rows.join("\n")}\n` +
      "Print one with --print <id>.\n",
  );
  return VIEW_EXIT.ok;
}