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
+73 -15
View File
@@ -50,6 +50,10 @@ import { existsSync } from "node:fs";
import { VERSION } from "./version.js";
let argv = process.argv.slice(2);
if (argv[0] === "help") {
process.argv = [...process.argv.slice(0, 2), ...argv.slice(1), "--help"];
argv = process.argv.slice(2);
}
const commandArg = argv[0];
const rootVersionRequested =
commandArg === "--version" ||
@@ -89,7 +93,8 @@ import type { ArgsDef, CommandDef } from "citty";
import { getRunId } from "./telemetry/runId.js";
import { reportCommandFailure, trackCommandFailures } from "./utils/command-failure-tracking.js";
import { isRenderSucceeded } from "./utils/render-success-state.js";
import { resolveCommandUsage } from "./utils/commandUsageResolution.js";
import { resolveCommandUsage, type ResolvedCommandUsage } from "./utils/commandUsageResolution.js";
import { closestMatch } from "./utils/didYouMean.js";
import { isDevMode } from "./utils/env.js";
import {
CliResultSignal,
@@ -347,13 +352,17 @@ async function finalizeCli(result: CommandResult): Promise<void> {
runId,
});
// No network wait: the exit handler's flushSync() delivers what is still queued.
if (result.kind !== "usage_error") printNotices();
process.exitCode = exitCode;
}
function printNotices(): void {
if (!hasJsonFlag) {
_printUpdateNotice?.();
_printStalePinNotice?.();
}
_printSkillsUpdateNotice?.();
if (_appHistoryNotice) process.stderr.write(`◇ ${_appHistoryNotice}\n`);
process.exitCode = exitCode;
}
registerRootExitRequester((exitCode) => {
@@ -512,26 +521,69 @@ process.on("unhandledRejection", (reason) => {
// Lazy-load help renderer — avoids allocating help data on non-help invocations
async function showUsage<T extends ArgsDef>(
cmd: CommandDef<T>,
parent?: CommandDef<T>,
parent: CommandDef<T> | undefined,
print: (text: string) => void,
): Promise<void> {
const { showUsage: impl } = await import("./help.js");
return impl(cmd as CommandDef, parent as CommandDef | undefined);
return impl(cmd as CommandDef, parent as CommandDef | undefined, print);
}
async function showRequestedUsage(): Promise<void> {
// Prints the suggestion and the group's usage on stderr; the caller throws the returned error.
async function unknownCommandError(requested: ResolvedCommandUsage): Promise<CliUsageError> {
const word = requested.unknownSubcommand ?? "";
const group = ["hyperframes", ...requested.path].join(" ");
const declared = requested.command.subCommands;
const subCommands = typeof declared === "function" ? await declared() : await declared;
const match = closestMatch(word, Object.keys(subCommands ?? {}));
console.error(`Unknown command: ${word}`);
if (match) console.error(`Did you mean '${group} ${match}'?`);
console.error("");
await showUsage(requested.command, requested.parent, console.error);
return new CliUsageError(`Unknown command: ${word}`, { presented: true });
}
// A group like `timeline` also takes a project directory, so a word it does not know may be one.
function takesPositionals(command: CommandDef): boolean {
const args = command.args;
return (
typeof args === "object" &&
args !== null &&
Object.values(args).some((arg) => arg.type === "positional")
);
}
async function showRequestedUsage(print: (text: string) => void): Promise<void> {
const requested = await resolveCommandUsage(main as CommandDef, argv);
return showUsage(requested.command, requested.parent);
if (requested.unknownSubcommand && !takesPositionals(requested.command)) {
throw await unknownCommandError(requested);
}
return showUsage(requested.command, requested.parent, print);
}
// citty would load every command looking for an alias before it gives up on an unknown name.
async function rejectUnknownTopLevelCommand(): Promise<void> {
const word = argv[0];
if (!word || word.startsWith("-") || Object.hasOwn(subCommands, word)) return;
throw await unknownCommandError({
command: main as CommandDef,
path: [],
unknownSubcommand: word,
});
}
function isCittyError(error: unknown, code: string): boolean {
return (
error instanceof Error &&
error.name === "CLIError" &&
(error as { code?: unknown }).code === code
);
}
// citty's own parse errors (missing argument, bad enum value, unknown or missing subcommand).
const CITTY_USAGE_CODES = new Set(["EARG", "E_UNKNOWN_COMMAND", "E_NO_COMMAND"]);
function isCittyUsageError(error: unknown): boolean {
return (
error instanceof Error &&
error.name === "CLIError" &&
CITTY_USAGE_CODES.has(String((error as { code?: unknown }).code))
);
return [...CITTY_USAGE_CODES].some((code) => isCittyError(error, code));
}
function commandResultForError(error: unknown): CommandResult {
@@ -547,16 +599,22 @@ function commandResultForError(error: unknown): CommandResult {
async function executeCli(): Promise<void> {
let result: CommandResult = { exitCode: 0, kind: "success" };
try {
if (isHelp) await showRequestedUsage();
else await runCommand(main, { rawArgs: argv });
} catch (error) {
if (isHelp) await showRequestedUsage(console.log);
else {
await rejectUnknownTopLevelCommand();
await runCommand(main, { rawArgs: argv });
}
} catch (caught) {
const error = isCittyError(caught, "E_UNKNOWN_COMMAND")
? await unknownCommandError(await resolveCommandUsage(main as CommandDef, argv))
: caught;
result = commandResultForError(error);
if (!(error instanceof CliResultSignal)) {
commandFailed = true;
await reportCommandFailure(command, error);
const typed = error instanceof CliUsageError || error instanceof CliRuntimeError;
const usage = error instanceof CliUsageError && !error.result.presented;
if (usage && !error.hint) await showRequestedUsage();
if (usage && !error.hint) await showRequestedUsage(console.error);
if (!typed || !error.result.presented) {
console.error(error instanceof Error ? error.message : String(error));
}