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
9.3 KB
Raw Blame
/**
 * `o2b store device list|retire` (design D6, D11a): the devices the brain
 * store knows, and the human `device-retire` record that takes a machine
 * that is gone for good off the digest roster and out of the legacy
 * removal gate. The work lives in `core/store/device-roster.ts`; this file
 * parses flags and renders.
 *
 * Exit codes: 0 for an answer (a list, a retirement, a device already
 * retired), 1 for a refusal (no store, no device id, this machine's own
 * id, an id the store has never seen without `--force`, a private
 * reason), 2 for a broken argv. Under `--json` every refusal and usage
 * error is a `{ ok: false, reason, error }` answer on stdout.
 */

import {
  ConfigReadError,
  isValidDeviceId,
  readDeviceId,
  resolveAgentName,
  resolveDeviceId,
  resolveVault,
} from "../core/config.ts";
import {
  DeviceRetireRefusal,
  listDevices,
  retireDevice,
  type DeviceEntry,
} from "../core/store/device-roster.ts";
import { PartitionUnavailableError } from "../core/store/appender.ts";
import { openStore, StoreOpenError, type StoreHandle } from "../core/store/store-open.ts";
import {
  resolveConfiguredStoreRoot,
  StoreRootInsideVaultError,
} from "../core/store/store-paths.ts";
import { CliError, parseFlags } from "./argparse.ts";
import { sortedReplacer } from "./helpers.ts";

const LIST_USAGE = "usage: o2b store device list [--config <file>] [--json]";
const RETIRE_USAGE =
  "usage: o2b store device retire <device-id> [--reason <text>] [--force] [--config <file>] [--json]";
export const STORE_DEVICE_USAGE = `${LIST_USAGE}\n${RETIRE_USAGE}`;

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

export function cmdStoreDevice(argv: ReadonlyArray<string>): number {
  const verb = argv[0];
  if (verb === "-h" || verb === "--help") {
    process.stdout.write(`${STORE_DEVICE_USAGE}\n`);
    return EXIT.ok;
  }
  if (verb === "list") return cmdList(argv.slice(1));
  if (verb === "retire") return cmdRetire(argv.slice(1));
  process.stderr.write(
    `error: ${verb === undefined ? "missing" : `unknown`} store device verb` +
      `${verb === undefined ? "" : `: ${verb}`}\n${STORE_DEVICE_USAGE}\n`,
  );
  return EXIT.usage;
}

/** A refusal of this verb itself, with its JSON reason. */
class DeviceVerbRefusal extends Error {
  constructor(
    readonly reason: "no-device" | "unknown-device",
    message: string,
  ) {
    super(message);
    this.name = "DeviceVerbRefusal";
  }
}

/**
 * The store this machine writes to, as its own device. `list` only reads:
 * it never mints a device id into the machine config (`readDeviceId`).
 */
function openHere(configPath: string | undefined, mode: "read" | "write"): StoreHandle {
  const { root } = resolveConfiguredStoreRoot(configPath);
  if (mode === "write") return openStore({ root, device: resolveDeviceId(configPath) });
  const device = readDeviceId(configPath ?? null);
  if (device === null) {
    throw new DeviceVerbRefusal(
      "no-device",
      "this machine has no device id; run `o2b store init` to give it one",
    );
  }
  return openStore({ root, device });
}

function isRefusal(err: unknown): err is Error {
  return (
    err instanceof DeviceRetireRefusal ||
    err instanceof DeviceVerbRefusal ||
    err instanceof StoreOpenError ||
    err instanceof StoreRootInsideVaultError ||
    err instanceof PartitionUnavailableError ||
    err instanceof ConfigReadError
  );
}

/** The JSON reason of a refusal: one per error class, so a caller can act on it. */
function reasonOf(err: Error): string {
  if (err instanceof DeviceRetireRefusal || err instanceof DeviceVerbRefusal) return err.reason;
  if (err instanceof StoreOpenError) return "no-store";
  if (err instanceof StoreRootInsideVaultError) return "store-root-in-vault";
  if (err instanceof PartitionUnavailableError) return "partition-unavailable";
  return "config";
}

function refuse(err: Error, json: boolean): number {
  if (json) {
    process.stdout.write(
      `${JSON.stringify({ ok: false, reason: reasonOf(err), error: err.message }, sortedReplacer, 2)}\n`,
    );
  }
  process.stderr.write(`error: ${err.message}\n`);
  return EXIT.refused;
}

/** A usage error: the usage on stderr, and the JSON failure on stdout under `--json`. */
function usage(argv: ReadonlyArray<string>, message: string, text: string): number {
  if (argv.includes("--json")) {
    process.stdout.write(
      `${JSON.stringify({ ok: false, reason: "usage", error: message }, sortedReplacer, 2)}\n`,
    );
  }
  process.stderr.write(`error: ${message}\n${text}\n`);
  return EXIT.usage;
}

function parse(
  argv: ReadonlyArray<string>,
  usageText: string,
  extra: Record<string, { type: "string" | "boolean" }> = {},
): { flags: Record<string, unknown>; positional: string[] } | number {
  try {
    const { flags, positional } = parseFlags(argv, {
      config: { type: "string" },
      json: { type: "boolean" },
      ...extra,
    });
    return { flags, positional };
  } catch (err) {
    if (!(err instanceof CliError)) throw err;
    return usage(argv, err.message, usageText);
  }
}

const iso = (ms: number | null): string | null => (ms === null ? null : new Date(ms).toISOString());

function renderList(devices: ReadonlyArray<DeviceEntry>): string {
  if (devices.length === 0) return "The brain store knows no device yet.\n";
  const width = Math.max(6, ...devices.map((d) => d.device.length)) + 2;
  const lines = [`${"device".padEnd(width)}${"last seen".padEnd(26)}state`];
  for (const d of devices) {
    const notes = [
      d.thisMachine ? "this machine" : null,
      !d.onRoster && d.state !== "retired" ? "off the roster" : null,
      d.returnedAfterRetire ? "wrote again after it was retired" : null,
    ].filter((n): n is string => n !== null);
    lines.push(
      `${d.device.padEnd(width)}${(iso(d.lastSeenMs) ?? "never").padEnd(26)}${d.state}` +
        (notes.length > 0 ? ` (${notes.join(", ")})` : ""),
    );
  }
  return `${lines.join("\n")}\n`;
}

function cmdList(argv: ReadonlyArray<string>): number {
  const parsed = parse(argv, LIST_USAGE);
  if (typeof parsed === "number") return parsed;
  const json = parsed.flags["json"] === true;
  if (parsed.positional.length > 0) {
    return usage(argv, `unexpected argument: ${parsed.positional[0]}`, LIST_USAGE);
  }
  let store: StoreHandle;
  let devices: DeviceEntry[];
  try {
    store = openHere(parsed.flags["config"] as string | undefined, "read");
    devices = listDevices(store);
  } catch (err) {
    if (!isRefusal(err)) throw err;
    return refuse(err, json);
  }
  process.stdout.write(
    json
      ? `${JSON.stringify(
          {
            ok: true,
            device: store.device,
            devices: devices.map((d) => ({
              device: d.device,
              last_seen: iso(d.lastSeenMs),
              state: d.state,
              on_roster: d.onRoster,
              this_machine: d.thisMachine,
              returned_after_retire: d.returnedAfterRetire,
            })),
          },
          sortedReplacer,
          2,
        )}\n`
      : renderList(devices),
  );
  return EXIT.ok;
}

function cmdRetire(argv: ReadonlyArray<string>): number {
  const parsed = parse(argv, RETIRE_USAGE, {
    reason: { type: "string" },
    force: { type: "boolean" },
  });
  if (typeof parsed === "number") return parsed;
  const json = parsed.flags["json"] === true;
  if (parsed.positional.length === 0)
    return usage(argv, "name the device id to retire", RETIRE_USAGE);
  if (parsed.positional.length > 1) {
    return usage(argv, `unexpected argument: ${parsed.positional[1]}`, RETIRE_USAGE);
  }
  const device = parsed.positional[0]!;
  const configPath = parsed.flags["config"] as string | undefined;
  const reason = parsed.flags["reason"] as string | undefined;
  try {
    const store = openHere(configPath, "write");
    // A retirement is a permanent record: an id the store has never seen
    // (a typo) is refused unless the operator insists. This machine's own
    // id, a malformed id and a machine without the shared partition are
    // refused by the roster with their own reasons, which `--force` would
    // not get past, so the guard leaves them to it.
    const knowable = isValidDeviceId(device) && store.partitions.has("shared");
    const unknown =
      knowable && device !== store.device && !listDevices(store).some((d) => d.device === device);
    if (unknown && parsed.flags["force"] !== true) {
      throw new DeviceVerbRefusal(
        "unknown-device",
        `the brain store has no record of a device ${device}; check \`o2b store device list\`, ` +
          "or pass --force to retire it anyway",
      );
    }
    const result = retireDevice(store, {
      device,
      ...(reason !== undefined ? { reason } : {}),
      agent: resolveAgentName(configPath),
      vault: resolveVault(configPath),
    });
    const message =
      result.status === "retired"
        ? `Retired ${device} (record ${result.record.id}). It leaves the digest roster and no ` +
          "longer holds back the removal of the legacy tree; if it writes again, doctor says so."
        : `${device} is already retired (record ${result.record.id}); nothing was written.`;
    process.stdout.write(
      json
        ? `${JSON.stringify({ ok: true, status: result.status, device, record: result.record.id }, sortedReplacer, 2)}\n`
        : `${message}\n`,
    );
    return EXIT.ok;
  } catch (err) {
    if (!isRefusal(err)) throw err;
    return refuse(err, json);
  }
}