fix(cli): add help [cmd], suggest the closest command or flag, and quiet the nags (#6621)

* fix(cli): add help [cmd], suggest the closest command or flag, and quiet the nags

`hyperframes help` printed "Unknown command help" with raw ANSI codes and no
suggestion. It is now an alias: `help [cmd...]` is `[cmd...] --help`.

An unknown command (at the root or inside a group like `cloud`) prints
"Unknown command: rendr", "Did you mean 'hyperframes render'?" and the group's
usage, all on stderr, and exits 2. An unknown flag suggests the flag it most
likely means ("Did you mean --output?"). Usage text printed for a usage error
now goes to stderr instead of stdout, and citty's colors are stripped from
help whenever this CLI's own colors are off.

No update, skills or app-history notice is appended to a usage error. The
skills notice shows at most once a day per project (timestamps in
~/.hyperframes/skills-notice.json) and, in an unattended run, only when a core
skill is missing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): reject an unknown top-level command without loading every command

citty looks for an alias on every registered command before it reports an
unknown name, which loads all of them. From a source checkout without the
studio packages built, that meant `hyperframes rendr` failed in preview's
build check with exit 1 instead of suggesting `render`. The name is now
checked against the registry first.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): help with a mistyped subcommand reports it like the command itself

`hyperframes help cloud rendr` printed cloud's help and exited 0, while
`hyperframes cloud rendr` exits 2 with a suggestion. Both now exit 2 with the
suggestion. A group that also takes positional arguments (timeline takes a
project directory) still shows its help for a word it does not know.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
James Russo
2026-10-28 09:39:06 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 3d1c0764a0
commit e2c9151320
11 changed files with 311 additions and 42 deletions
@@ -36,3 +36,29 @@ describe("resolveCommandUsage", () => {
expect((await resolveCommandUsage(root, ["--help"])).command).toBe(root);
});
});
describe("resolveCommandUsage path and unknown words", () => {
const render = defineCommand({ meta: { name: "render" } });
const cloud = defineCommand({ meta: { name: "cloud" }, subCommands: { render } });
const root = defineCommand({ meta: { name: "hyperframes" }, subCommands: { cloud } });
it("returns the words that named the command", async () => {
expect((await resolveCommandUsage(root, ["cloud", "render", "x"])).path).toEqual([
"cloud",
"render",
]);
});
it("names the first word that is not a subcommand of a group", async () => {
const resolved = await resolveCommandUsage(root, ["cloud", "rendr"]);
expect(resolved.command).toBe(cloud);
expect(resolved.path).toEqual(["cloud"]);
expect(resolved.unknownSubcommand).toBe("rendr");
});
it("does not treat a leaf command's positional as an unknown command", async () => {
expect(
(await resolveCommandUsage(root, ["cloud", "render", "./dir"])).unknownSubcommand,
).toBeUndefined();
});
});