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.6 KB
Raw Blame
/**
 * The two help surfaces describe one command set (no-dead-ends, phase 3,
 * item 1).
 *
 * `o2b help --json` serialises the command manifest; `o2b help` used to
 * print a hand-written constant. Two lists mean two truths, and the
 * manifest repair that added sixty-four entries widened the gap until the
 * human surface named twelve `brain` verbs out of a hundred and thirty.
 * An operator reading the human surface therefore could not reach most of
 * this tool - a discoverability dead end.
 *
 * The repair is derivation: one renderer over the manifest feeds both. A
 * derived surface cannot disagree with its source by construction, so
 * this file asserts the property that derivation is FOR - it parses the
 * human text back into paths, summaries and flags and requires the result
 * to equal the manifest exactly. A renderer that truncated, wrapped or
 * dropped a level would pass a "both come from the manifest" claim and
 * fail here.
 */

import { describe, expect, setDefaultTimeout, test } from "bun:test";

import {
  manifestForJson,
  type CliCommandManifest,
  type CliRootManifest,
} from "../../src/cli/command-manifest.ts";
import { runCli } from "../helpers/run-cli.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

/** `  <path>  <summary>` - two-space indent, two-or-more-space gutter. */
const ENTRY_RE = /^ {2}(\S(?:.*?\S)?) {2,}(\S.*)$/;
/** `      flags: --a --b` - the continuation line a flagged entry carries. */
const FLAGS_RE = /^ {6}flags: (.+)$/;

interface ParsedEntry {
  readonly summary: string;
  readonly flags: ReadonlyArray<string>;
}

/** Parse the human help back into `path -> { summary, flags }`. */
function parseHumanHelp(text: string): ReadonlyMap<string, ParsedEntry> {
  const out = new Map<string, ParsedEntry>();
  let last: string | null = null;
  for (const line of text.split("\n")) {
    const flags = FLAGS_RE.exec(line);
    if (flags !== null) {
      expect(`flags line has an owner: ${last !== null}`).toBe("flags line has an owner: true");
      const owner = out.get(last!)!;
      out.set(last!, { summary: owner.summary, flags: flags[1]!.trim().split(/\s+/) });
      continue;
    }
    const entry = ENTRY_RE.exec(line);
    if (entry === null) continue;
    last = entry[1]!;
    out.set(last, { summary: entry[2]!.trimEnd(), flags: [] });
  }
  return out;
}

/** Walk the manifest into the same `path -> { summary, flags }` shape. */
function walkManifest(root: CliRootManifest): ReadonlyMap<string, ParsedEntry> {
  const out = new Map<string, ParsedEntry>();
  const visit = (items: ReadonlyArray<CliCommandManifest>, prefix: string): void => {
    for (const item of items) {
      const path = `${prefix}${item.name}`;
      out.set(path, {
        summary: item.summary,
        // The inherited `--json` flag is stated once in the header rather
        // than repeated on all two hundred entries; parity is asserted over
        // the flags a command DECLARES.
        flags: (item.flags ?? []).filter((f) => f.inherited !== true).map((f) => `--${f.name}`),
      });
      if (item.commands) visit(item.commands, `${path} `);
    }
  };
  visit(root.commands, "");
  return out;
}

async function humanHelp(): Promise<string> {
  const r = await runCli(["help"]);
  expect(r.returncode).toBe(0);
  return r.stdout;
}

describe("o2b help and o2b help --json describe one command set", () => {
  test("every command the manifest models is named by the human help, and nothing else is", async () => {
    const human = parseHumanHelp(await humanHelp());
    const modelled = walkManifest(manifestForJson());
    // Named, not counted: the failure message is the work to be done.
    const missing = [...modelled.keys()].filter((p) => !human.has(p)).toSorted();
    const invented = [...human.keys()].filter((p) => !modelled.has(p)).toSorted();
    expect(missing.join("\n")).toBe("");
    expect(invented.join("\n")).toBe("");
  });

  test("every summary is the manifest's, verbatim", async () => {
    const human = parseHumanHelp(await humanHelp());
    const modelled = walkManifest(manifestForJson());
    const drifted: string[] = [];
    for (const [path, entry] of modelled) {
      const shown = human.get(path);
      if (shown !== undefined && shown.summary !== entry.summary) {
        drifted.push(`${path}\n  manifest: ${entry.summary}\n  help:     ${shown.summary}`);
      }
    }
    expect(drifted.join("\n")).toBe("");
  });

  test("every declared flag is the manifest's, verbatim", async () => {
    const human = parseHumanHelp(await humanHelp());
    const modelled = walkManifest(manifestForJson());
    const drifted: string[] = [];
    for (const [path, entry] of modelled) {
      const shown = human.get(path);
      if (shown === undefined) continue;
      if (shown.flags.join(" ") !== entry.flags.join(" ")) {
        drifted.push(
          `${path}: manifest [${entry.flags.join(" ")}] help [${shown.flags.join(" ")}]`,
        );
      }
    }
    expect(drifted.join("\n")).toBe("");
  });

  test("the parse is not vacuous", async () => {
    // A regex that stopped matching would report two empty sets as equal.
    const human = parseHumanHelp(await humanHelp());
    expect(human.size).toBeGreaterThan(180);
    expect([...human.values()].filter((e) => e.flags.length > 0).length).toBeGreaterThan(10);
  });

  test("the JSON surface serialises the same manifest the human one renders", async () => {
    const r = await runCli(["help", "--json"]);
    expect(r.returncode).toBe(0);
    expect(JSON.parse(r.stdout)).toEqual(JSON.parse(JSON.stringify(manifestForJson())));
  });
});

describe("the flags the branch added verbs for are advertised", () => {
  /** `path -> declared flag names`, from the JSON surface itself. */
  async function jsonFlags(): Promise<ReadonlyMap<string, ReadonlyArray<string>>> {
    const r = await runCli(["help", "--json"]);
    expect(r.returncode).toBe(0);
    return walkManifestFlags(JSON.parse(r.stdout) as CliRootManifest);
  }

  function walkManifestFlags(root: CliRootManifest): ReadonlyMap<string, ReadonlyArray<string>> {
    const out = new Map<string, ReadonlyArray<string>>();
    for (const [path, entry] of walkManifest(root)) out.set(path, entry.flags);
    return out;
  }

  test("brain lint advertises the consolidation flags its summary already mentions", async () => {
    const flags = await jsonFlags();
    expect((flags.get("brain lint") ?? []).toSorted()).toEqual(
      ["--apply", "--consolidate", "--vault", "--yes"].toSorted(),
    );
  });

  test("brain pending apply advertises the dry run this branch gave it", async () => {
    const flags = await jsonFlags();
    expect(flags.get("brain pending apply")).toContain("--dry-run");
  });

  test("brain pending reject advertises its reason, and list advertises neither", async () => {
    const flags = await jsonFlags();
    expect(flags.get("brain pending reject")).toContain("--reason");
    expect(flags.get("brain pending list")).not.toContain("--dry-run");
    expect(flags.get("brain pending list")).not.toContain("--reason");
  });

  // t_1e952e43: the lessons verb family rides the install consent ladder,
  // so the consent-bearing subcommands advertise the ladder flags and the
  // read-only one advertises no write flag at all.
  test("brain lessons approve advertises the consent ladder flags", async () => {
    const flags = await jsonFlags();
    const approve = flags.get("brain lessons approve") ?? [];
    expect(approve).toContain("--apply");
    expect(approve).toContain("--yes");
    expect(approve).toContain("--target");
    expect(approve).toContain("--force");
  });

  test("brain lessons candidates advertises no write flag", async () => {
    const flags = await jsonFlags();
    const candidates = flags.get("brain lessons candidates") ?? [];
    expect(candidates).not.toContain("--apply");
    expect(candidates).not.toContain("--yes");
  });

  test("brain lessons refresh-blocks advertises the ladder and force", async () => {
    const flags = await jsonFlags();
    const refresh = flags.get("brain lessons refresh-blocks") ?? [];
    expect(refresh).toContain("--apply");
    expect(refresh).toContain("--yes");
    expect(refresh).toContain("--force");
  });
});

describe("the terse usage names the complete help", () => {
  test("an unknown command lists every top-level verb and where the rest are", async () => {
    const r = await runCli(["no-such-verb"]);
    expect(r.returncode).toBe(2);
    for (const item of manifestForJson().commands) {
      expect(`${item.name} listed: ${r.stderr.includes(item.name)}`).toBe(
        `${item.name} listed: true`,
      );
    }
    expect(r.stderr).toContain("o2b help");
  });
});