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
/**
* 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");
});
});