fix(cli): an unknown command answers in a few lines and says what to run instead (#7247)

* fix(cli): an unknown command answers in a few lines and says what to run instead

* fix(cli): shorten the captions pointer and drop the redirect doc comments

* fix(cli): point the captions hint at the hyperframes skill's guide, and test the path exists

* chore(cli): regenerate the skills manifest for the hyperframes-cli skill edit
This commit is contained in:
Miguel Ángel
2026-11-05 15:35:10 +00:00
committed by GitHub
parent b7d72c9478
commit 0a6746e1d6
6 changed files with 85 additions and 21 deletions
+16
View File
@@ -364,6 +364,22 @@ describe("agent-mode contract", () => {
expect(JSON.parse(run.stdout).error.hint).toBe("Did you mean 'hyperframes render'?");
});
it("an unknown command answers in a few lines, never the full help", async () => {
const captions = await runAsAgent(["captions"]);
const typo = await runAsAgent(["rendr"]);
expect(captions.code).toBe(2);
expect(captions.stderr).toContain("Unknown command: captions");
expect(captions.stderr).toContain(
"Run 'hyperframes transcribe', then read ../hyperframes/references/captions.md",
);
expect(typo.code).toBe(2);
expect(typo.stderr).toContain("Did you mean 'hyperframes render'?");
for (const run of [captions, typo]) {
expect(run.stderr).toContain("Run 'hyperframes --help' to list every command.");
expect(run.stderr.split("\n").length).toBeLessThan(8);
}
});
it("an unknown flag suggests the flag it most likely means", async () => {
const run = await runAsAgent(["render", "--out", "x.mp4"]);
expect(run.code).toBe(2);
+17 -8
View File
@@ -88,7 +88,7 @@ import {
markCommandDelivered,
} from "./utils/render-success-state.js";
import { resolveCommandUsage, type ResolvedCommandUsage } from "./utils/commandUsageResolution.js";
import { closestMatch, fileHint, synonymMatch } from "./utils/didYouMean.js";
import { closestMatch, closestNames, commandRedirect, fileHint } from "./utils/didYouMean.js";
import { jsonErrorBody, watchOutput, writeJsonFailure } from "./utils/jsonError.js";
import { isDevMode } from "./utils/env.js";
import {
@@ -536,21 +536,17 @@ async function showUsage<T extends ArgsDef>(
return impl(cmd as CommandDef, parent as CommandDef | undefined, print);
}
// Prints the suggestion and the group's usage on stderr; the caller throws the returned error.
// Prints the suggestion and where to list every command 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 names = Object.keys(subCommands ?? {});
const match =
(requested.path.length === 0 ? synonymMatch(word, names) : undefined) ??
closestMatch(word, names);
const hint = match ? `Did you mean '${group} ${match}'?` : fileHint(word, requested.path, names);
const hint = unknownCommandHint(word, requested.path, names);
console.error(`Unknown command: ${word}`);
if (hint) console.error(hint);
console.error("");
await showUsage(requested.command, requested.parent, console.error);
console.error(`Run '${group} --help' to list every command.`);
return new CliUsageError(`Unknown command: ${word}`, {
presented: true,
code: "unknown_command",
@@ -558,6 +554,19 @@ async function unknownCommandError(requested: ResolvedCommandUsage): Promise<Cli
});
}
/** What to say after "Unknown command": the command that does that job, the closest spelling, or a file's fix. */
function unknownCommandHint(word: string, path: string[], names: string[]): string | undefined {
const group = ["hyperframes", ...path].join(" ");
const redirect = path.length === 0 ? commandRedirect(word, names) : undefined;
if (redirect?.then) return `Run '${group} ${redirect.command}', ${redirect.then}.`;
const match = redirect?.command ?? closestMatch(word, names);
if (match) return `Did you mean '${group} ${match}'?`;
const close = closestNames(word, names, 3);
return (
fileHint(word, path, names) ?? (close.length ? `Closest: ${close.join(", ")}.` : undefined)
);
}
// 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;
+23 -1
View File
@@ -1,5 +1,8 @@
import { describe, expect, it } from "vitest";
import { closestMatch, fileHint } from "./didYouMean.js";
import { existsSync, readFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { closestMatch, fileHint, REDIRECTS_WITH_NEXT_STEP, redirectLine } from "./didYouMean.js";
describe("closestMatch", () => {
const commands = ["render", "preview", "publish", "lint", "check", "help"];
@@ -38,3 +41,22 @@ describe("fileHint", () => {
expect(fileHint("package.json", ["measure"], [])).toBeUndefined();
});
});
describe("redirectLine", () => {
it("is the line the hyperframes-cli skill carries for every redirect with a next step", () => {
const skill = readFileSync(
new URL("../../../../skills/hyperframes-cli/SKILL.md", import.meta.url),
"utf8",
);
expect(REDIRECTS_WITH_NEXT_STEP).toContain("captions");
for (const word of REDIRECTS_WITH_NEXT_STEP) {
const line = redirectLine(word);
expect(skill).toContain(line);
const guide = /\.\.\/\S+\.md/.exec(line)?.[0] ?? "";
const skillDir = dirname(
fileURLToPath(new URL("../../../../skills/hyperframes-cli/SKILL.md", import.meta.url)),
);
expect(existsSync(resolve(skillDir, guide)), `${word} points at ${guide}`).toBe(true);
}
});
});
+25 -10
View File
@@ -45,20 +45,35 @@ export function closestNames(input: string, candidates: Iterable<string>, limit
.map(({ name }) => name);
}
const COMMAND_SYNONYMS: Record<string, string> = {
search: "catalog",
find: "catalog",
browse: "catalog",
registry: "catalog",
list: "catalog",
install: "add",
const COMMAND_REDIRECTS: Record<string, { command: string; then?: string }> = {
search: { command: "catalog" },
find: { command: "catalog" },
browse: { command: "catalog" },
registry: { command: "catalog" },
list: { command: "catalog" },
install: { command: "add" },
captions: {
command: "transcribe",
then: "then read ../hyperframes/references/captions.md",
},
};
export function synonymMatch(input: string, candidates: Iterable<string>): string | undefined {
const target = COMMAND_SYNONYMS[input];
return target !== undefined && [...candidates].includes(target) ? target : undefined;
export function commandRedirect(
input: string,
candidates: Iterable<string>,
): { command: string; then?: string } | undefined {
const row = COMMAND_REDIRECTS[input];
return row !== undefined && [...candidates].includes(row.command) ? row : undefined;
}
export const redirectLine = (word: string): string => {
const row = COMMAND_REDIRECTS[word]!;
return `\`${word}\` is not a command: run \`${row.command}\`${row.then ? `, ${row.then}` : ""}.`;
};
export const REDIRECTS_WITH_NEXT_STEP = Object.keys(COMMAND_REDIRECTS).filter(
(word) => COMMAND_REDIRECTS[word]!.then,
);
export function fileHint(word: string, path: string[], names: string[]): string | undefined {
if (path.length === 0 || names.length === 0 || !existsSync(word)) return undefined;
const group = ["hyperframes", ...path].join(" ");
+1 -1
View File
@@ -10,7 +10,7 @@
"files": 78
},
"hyperframes-cli": {
"hash": "571fffd79a7d42f9",
"hash": "2c977e879386734b",
"files": 13
},
"hyperframes-registry": {
+3 -1
View File
@@ -28,7 +28,9 @@ A `--json` result may carry `_meta.updateNotice`: a newer HyperFrames release is
| Desktop app | `open`, `catch-up` |
| Upkeep | `doctor`, `browser`, `upgrade`, `usage`, `clean`, `feedback` |
`validate`, `inspect` and `layout` are deprecated aliases of `check`; `events` is telemetry for skills' own scripts. Don't run them.
`captions` is not a command: run `transcribe`, then read ../hyperframes/references/captions.md.
`validate`, `inspect` and `layout` are deprecated aliases of `check`; `events` is skills' own telemetry. Don't run them.
## The loop