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
/**
* Command-manifest completeness ratchet (no-dead-ends, task 6).
*
* `command-manifest.ts` is not documentation. It is the source of the
* shell completion scripts and of `o2b help --json`, which is how an
* agent discovers what this CLI can do. A verb the manifest does not
* model is a verb that does not exist as far as either surface is
* concerned - a dead end reached by not knowing the road is there.
*
* The audit that produced this file found the manifest two top-level
* verbs, seven `search` subverbs and fifty-five `brain` cases short.
* Repairing it once fixes today; this ratchet is what stops it drifting
* again, and the direction of enumeration is the whole point: it reads
* the DISPATCHERS and asks the manifest to account for each case, never
* the reverse. A manifest cannot vouch for its own completeness.
*
* Scope is one level below each dispatcher - the switch in `main.ts`,
* the switch in `brain.ts`, `KNOWN_VERBS` in `search.ts`, and the verb
* table in `partner.ts`. Deeper nesting (`brain schema report`, `brain
* git ingest`) is parsed by each verb from its own positionals, with no
* shared table to enumerate from, so it is out of this ratchet's reach
* and stays modelled by hand.
*
* `partner codegraph` sits two levels deep but IS enumerable, because its
* dispatcher is a frozen verb table rather than a chain of comparisons.
* That is why it was written as a table: a verb the manifest never heard
* of is a verb no completion offers, and `resync --cron-template` is the
* only way to reach the codegraph resync recipe at all.
*/
import { describe, expect, setDefaultTimeout, test } from "bun:test";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import {
CLI_COMMAND_MANIFEST,
nestedCommand,
nestedCommandNames,
type CliCommandManifest,
} from "../../src/cli/command-manifest.ts";
import { renderCompletions } from "../../src/cli/completions.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);
const CLI_ROOT = join(import.meta.dir, "..", "..", "src", "cli");
/**
* Top-level cases with no manifest entry, and why. An entry may only sit
* here because listing the verb would be WRONG, never because writing
* its summary was inconvenient.
*/
const TOP_LEVEL_UNLISTED: Readonly<Record<string, string>> = Object.freeze({});
/** `brain` cases with no manifest entry, and why. */
const BRAIN_UNLISTED: Readonly<Record<string, string>> = Object.freeze({});
/** `search` verbs with no manifest entry, and why. */
const SEARCH_UNLISTED: Readonly<Record<string, string>> = Object.freeze({});
/** `partner codegraph` verbs with no manifest entry, and why. */
const PARTNER_CODEGRAPH_UNLISTED: Readonly<Record<string, string>> = Object.freeze({});
/** An exclusion reason has to say something; ten characters is the floor. */
const MIN_REASON_LENGTH = 10;
/** Read `file` under `src/cli/`. */
function cliSource(file: string): string {
return readFileSync(join(CLI_ROOT, file), "utf8");
}
/**
* Every `case "<label>":` between `marker` and the switch's `default:`.
* Bounded on both ends so an unrelated switch elsewhere in the module
* cannot leak into the census.
*/
function switchCaseLabels(file: string, marker: string): string[] {
const text = cliSource(file);
const start = text.indexOf(marker);
expect(`${file} contains ${marker}: ${start >= 0}`).toBe(`${file} contains ${marker}: true`);
const end = text.indexOf("default:", start);
expect(`${file} switch is terminated: ${end > start}`).toBe(`${file} switch is terminated: true`);
return [...text.slice(start, end).matchAll(/case "([^"]+)":/g)].map((m) => m[1]!);
}
/** The keys of the `CODEGRAPH_VERBS` table literal in `partner.ts`. */
function partnerCodegraphVerbs(): string[] {
const text = cliSource("partner.ts");
const start = text.indexOf("const CODEGRAPH_VERBS");
expect(`partner.ts declares CODEGRAPH_VERBS: ${start >= 0}`).toBe(
"partner.ts declares CODEGRAPH_VERBS: true",
);
const open = text.indexOf("Object.freeze({", start);
const end = text.indexOf("});", open);
expect(`the partner verb table is terminated: ${end > open}`).toBe(
"the partner verb table is terminated: true",
);
return [...text.slice(open, end).matchAll(/^\s{4}([A-Za-z][\w-]*):/gm)].map((m) => m[1]!);
}
/** Manifest children of `o2b partner codegraph`. */
function manifestPartnerCodegraphVerbs(): string[] {
const partner = CLI_COMMAND_MANIFEST.commands.find((c) => c.name === "partner");
const codegraph = partner?.commands?.find((c) => c.name === "codegraph");
expect(`the manifest models partner codegraph: ${codegraph !== undefined}`).toBe(
"the manifest models partner codegraph: true",
);
return (codegraph?.commands ?? []).map((c) => c.name);
}
/** The `KNOWN_VERBS` set literal in `search.ts`. */
function searchKnownVerbs(): string[] {
const text = cliSource("search.ts");
const start = text.indexOf("const KNOWN_VERBS = new Set([");
expect(`search.ts declares KNOWN_VERBS: ${start >= 0}`).toBe(
"search.ts declares KNOWN_VERBS: true",
);
const end = text.indexOf("]);", start);
return [...text.slice(start, end).matchAll(/"([^"]+)"/g)].map((m) => m[1]!);
}
/** Paths of every modelled command whose summary says nothing. */
function emptySummaries(
items: ReadonlyArray<CliCommandManifest>,
prefix: string,
): ReadonlyArray<string> {
const found: string[] = [];
for (const item of items) {
const path = `${prefix}${item.name}`;
if (item.summary.trim().length === 0) found.push(path);
if (item.commands) found.push(...emptySummaries(item.commands, `${path} `));
}
return found;
}
interface Level {
readonly label: string;
readonly dispatcherVerbs: ReadonlyArray<string>;
readonly manifestVerbs: ReadonlyArray<string>;
readonly unlisted: Readonly<Record<string, string>>;
}
function levels(): ReadonlyArray<Level> {
return [
{
label: "o2b",
dispatcherVerbs: switchCaseLabels("main.ts", "async function dispatchCommand"),
manifestVerbs: CLI_COMMAND_MANIFEST.commands.map((c) => c.name),
unlisted: TOP_LEVEL_UNLISTED,
},
{
label: "o2b brain",
dispatcherVerbs: switchCaseLabels("brain.ts", "export async function handleBrainSubcommand"),
manifestVerbs: nestedCommandNames("brain"),
unlisted: BRAIN_UNLISTED,
},
{
label: "o2b search",
dispatcherVerbs: searchKnownVerbs(),
manifestVerbs: nestedCommandNames("search"),
unlisted: SEARCH_UNLISTED,
},
{
label: "o2b partner codegraph",
dispatcherVerbs: partnerCodegraphVerbs(),
manifestVerbs: manifestPartnerCodegraphVerbs(),
unlisted: PARTNER_CODEGRAPH_UNLISTED,
},
];
}
describe("command manifest completeness", () => {
test("every dispatcher case is modelled or excluded with a written reason", () => {
// Every level folds into ONE comparison so the failure message is
// the complete list of verbs to act on. Asserting per level would
// stop at the first and hide the rest.
const unclassified: string[] = [];
for (const level of levels()) {
const modelled = new Set(level.manifestVerbs);
for (const verb of level.dispatcherVerbs) {
if (modelled.has(verb) || level.unlisted[verb] !== undefined) continue;
unclassified.push(`${level.label} ${verb}`);
}
}
expect(unclassified.toSorted().join("\n")).toBe("");
});
test("no manifest entry outlives the dispatcher case it describes", () => {
const stale: string[] = [];
for (const level of levels()) {
const dispatched = new Set(level.dispatcherVerbs);
for (const verb of level.manifestVerbs) {
if (!dispatched.has(verb)) stale.push(`${level.label} ${verb}`);
}
}
expect(stale.toSorted().join("\n")).toBe("");
});
test("no exclusion outlives the verb it excuses, and every reason says something", () => {
for (const level of levels()) {
const dispatched = new Set(level.dispatcherVerbs);
for (const [verb, reason] of Object.entries(level.unlisted)) {
expect(`${level.label} ${verb} is dispatched: ${dispatched.has(verb)}`).toBe(
`${level.label} ${verb} is dispatched: true`,
);
// A placeholder ("todo", "n/a", "") cannot satisfy this.
expect(
`${level.label} ${verb} has a reason: ${reason.trim().length >= MIN_REASON_LENGTH}`,
).toBe(`${level.label} ${verb} has a reason: true`);
}
}
});
test("the ratchet is not vacuous", () => {
// A parser that silently stopped matching would report a clean sweep
// over an empty set. Pin the measurement, not only its verdict.
const [top, brain, search, partner] = levels();
expect(top!.dispatcherVerbs.length).toBeGreaterThan(15);
expect(brain!.dispatcherVerbs.length).toBeGreaterThan(130);
expect(search!.dispatcherVerbs.length).toBeGreaterThan(10);
expect(partner!.dispatcherVerbs.toSorted()).toEqual(["report", "resync"]);
});
test("the search dispatcher and its verb gate agree", () => {
// `KNOWN_VERBS` decides whether the first positional is a verb or a
// query string; the switch decides what runs. A verb in one and not
// the other is either unreachable or an unknown-verb error.
expect(
switchCaseLabels("search.ts", "export async function handleSearchSubcommand").toSorted(),
).toEqual(searchKnownVerbs().toSorted());
});
});
describe("the repaired manifest reaches its two consumers", () => {
/** Verbs the audit found missing; a spot check of each level. */
const REPAIRED = Object.freeze({
top: ["secrets", "partner"],
brain: ["pending", "lint", "stale", "today", "obligation", "lessons"],
search: ["expand", "focus", "feedback", "weights", "rerank-provider", "rerank-fit", "plan"],
});
test("shell completions offer the repaired verbs", () => {
const bash = renderCompletions("bash", CLI_COMMAND_MANIFEST);
for (const verb of REPAIRED.top) expect(bash).toContain(verb);
const zsh = renderCompletions("zsh", CLI_COMMAND_MANIFEST);
for (const verb of [...REPAIRED.brain, ...REPAIRED.search]) {
expect(`${verb}: ${zsh.includes(verb)}`).toBe(`${verb}: true`);
}
});
test("help --json carries every dispatcher verb", async () => {
const r = await runCli(["help", "--json"]);
expect(r.returncode).toBe(0);
const payload = JSON.parse(r.stdout) as {
commands: ReadonlyArray<{ name: string; commands?: ReadonlyArray<{ name: string }> }>;
};
const names = new Set(payload.commands.map((c) => c.name));
for (const verb of REPAIRED.top) {
expect(`${verb}: ${names.has(verb)}`).toBe(`${verb}: true`);
}
const nested = (parent: string): ReadonlySet<string> =>
new Set((payload.commands.find((c) => c.name === parent)?.commands ?? []).map((c) => c.name));
const brainNames = nested("brain");
for (const verb of REPAIRED.brain) {
expect(`brain ${verb}: ${brainNames.has(verb)}`).toBe(`brain ${verb}: true`);
}
const searchNames = nested("search");
for (const verb of REPAIRED.search) {
expect(`search ${verb}: ${searchNames.has(verb)}`).toBe(`search ${verb}: true`);
}
});
test("completions offer the flags that reach the cron recipes", () => {
// `search reindex` declared no flags at all, so `--cron-template` -
// the only entry point to the reindex recipe - completed nowhere.
// Completion flag lists are built by walking the whole manifest, so a
// declared flag at any depth reaches every shell.
const zsh = renderCompletions("zsh", CLI_COMMAND_MANIFEST);
for (const token of [
"--cron-template",
"--interval",
"--format",
"--fail-on-health",
"--project",
]) {
expect(`${token}: ${zsh.includes(token)}`).toBe(`${token}: true`);
}
});
test("brain maintenance models run and status, with the recipe flags on run", () => {
// The lane is the cron entry point, and `run --cron-template` is the
// only way to reach its recipe; a flag the manifest does not declare
// completes nowhere and is invisible to `o2b help --json`.
const maintenance = nestedCommand("brain", "maintenance");
expect((maintenance?.commands ?? []).map((c) => c.name).toSorted()).toEqual(["run", "status"]);
const run = maintenance?.commands?.find((c) => c.name === "run");
const runFlags = new Set((run?.flags ?? []).map((f) => f.name));
for (const name of [
"cron-template",
"interval",
"format",
"window",
"tz",
"retry",
"force",
"force-cost",
]) {
expect(`run --${name}: ${runFlags.has(name)}`).toBe(`run --${name}: true`);
}
const status = maintenance?.commands?.find((c) => c.name === "status");
const statusFlags = new Set((status?.flags ?? []).map((f) => f.name));
expect(`status --cron-template: ${statusFlags.has("cron-template")}`).toBe(
"status --cron-template: false",
);
});
test("help --json carries the partner codegraph verbs", async () => {
// `partner` is the one modelled parent whose verbs live two levels
// down, so the top-level census above cannot see them.
const r = await runCli(["help", "--json"]);
expect(r.returncode).toBe(0);
const payload = JSON.parse(r.stdout) as {
commands: ReadonlyArray<{
name: string;
commands?: ReadonlyArray<{ name: string; commands?: ReadonlyArray<{ name: string }> }>;
}>;
};
const codegraph = payload.commands
.find((c) => c.name === "partner")
?.commands?.find((c) => c.name === "codegraph");
expect((codegraph?.commands ?? []).map((c) => c.name).toSorted()).toEqual(["report", "resync"]);
});
test("every modelled command carries a non-empty summary", () => {
// An entry added only to satisfy the ratchet, with an empty summary,
// would complete the manifest and tell a reader nothing.
expect(emptySummaries(CLI_COMMAND_MANIFEST.commands, "o2b ").join("\n")).toBe("");
});
});