Skip to content

Commit 0a6746e

Browse files
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
1 parent b7d72c9 commit 0a6746e

6 files changed

Lines changed: 85 additions & 21 deletions

File tree

‎packages/cli/src/cli.agentMode.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -364,6 +364,22 @@ describe("agent-mode contract", () => {
364364
expect(JSON.parse(run.stdout).error.hint).toBe("Did you mean 'hyperframes render'?");
365365
});
366366

367+
it("an unknown command answers in a few lines, never the full help", async () => {
368+
const captions = await runAsAgent(["captions"]);
369+
const typo = await runAsAgent(["rendr"]);
370+
expect(captions.code).toBe(2);
371+
expect(captions.stderr).toContain("Unknown command: captions");
372+
expect(captions.stderr).toContain(
373+
"Run 'hyperframes transcribe', then read ../hyperframes/references/captions.md",
374+
);
375+
expect(typo.code).toBe(2);
376+
expect(typo.stderr).toContain("Did you mean 'hyperframes render'?");
377+
for (const run of [captions, typo]) {
378+
expect(run.stderr).toContain("Run 'hyperframes --help' to list every command.");
379+
expect(run.stderr.split("\n").length).toBeLessThan(8);
380+
}
381+
});
382+
367383
it("an unknown flag suggests the flag it most likely means", async () => {
368384
const run = await runAsAgent(["render", "--out", "x.mp4"]);
369385
expect(run.code).toBe(2);

‎packages/cli/src/cli.ts‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ import {
8888
markCommandDelivered,
8989
} from "./utils/render-success-state.js";
9090
import { resolveCommandUsage, type ResolvedCommandUsage } from "./utils/commandUsageResolution.js";
91-
import { closestMatch, fileHint, synonymMatch } from "./utils/didYouMean.js";
91+
import { closestMatch, closestNames, commandRedirect, fileHint } from "./utils/didYouMean.js";
9292
import { jsonErrorBody, watchOutput, writeJsonFailure } from "./utils/jsonError.js";
9393
import { isDevMode } from "./utils/env.js";
9494
import {
@@ -536,28 +536,37 @@ async function showUsage<T extends ArgsDef>(
536536
return impl(cmd as CommandDef, parent as CommandDef | undefined, print);
537537
}
538538

539-
// Prints the suggestion and the group's usage on stderr; the caller throws the returned error.
539+
// Prints the suggestion and where to list every command on stderr; the caller throws the returned error.
540540
async function unknownCommandError(requested: ResolvedCommandUsage): Promise<CliUsageError> {
541541
const word = requested.unknownSubcommand ?? "";
542542
const group = ["hyperframes", ...requested.path].join(" ");
543543
const declared = requested.command.subCommands;
544544
const subCommands = typeof declared === "function" ? await declared() : await declared;
545545
const names = Object.keys(subCommands ?? {});
546-
const match =
547-
(requested.path.length === 0 ? synonymMatch(word, names) : undefined) ??
548-
closestMatch(word, names);
549-
const hint = match ? `Did you mean '${group} ${match}'?` : fileHint(word, requested.path, names);
546+
const hint = unknownCommandHint(word, requested.path, names);
550547
console.error(`Unknown command: ${word}`);
551548
if (hint) console.error(hint);
552-
console.error("");
553-
await showUsage(requested.command, requested.parent, console.error);
549+
console.error(`Run '${group} --help' to list every command.`);
554550
return new CliUsageError(`Unknown command: ${word}`, {
555551
presented: true,
556552
code: "unknown_command",
557553
hint,
558554
});
559555
}
560556

557+
/** What to say after "Unknown command": the command that does that job, the closest spelling, or a file's fix. */
558+
function unknownCommandHint(word: string, path: string[], names: string[]): string | undefined {
559+
const group = ["hyperframes", ...path].join(" ");
560+
const redirect = path.length === 0 ? commandRedirect(word, names) : undefined;
561+
if (redirect?.then) return `Run '${group} ${redirect.command}', ${redirect.then}.`;
562+
const match = redirect?.command ?? closestMatch(word, names);
563+
if (match) return `Did you mean '${group} ${match}'?`;
564+
const close = closestNames(word, names, 3);
565+
return (
566+
fileHint(word, path, names) ?? (close.length ? `Closest: ${close.join(", ")}.` : undefined)
567+
);
568+
}
569+
561570
// A group like `timeline` also takes a project directory, so a word it does not know may be one.
562571
function takesPositionals(command: CommandDef): boolean {
563572
const args = command.args;

‎packages/cli/src/utils/didYouMean.test.ts‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
import { describe, expect, it } from "vitest";
2-
import { closestMatch, fileHint } from "./didYouMean.js";
2+
import { existsSync, readFileSync } from "node:fs";
3+
import { dirname, resolve } from "node:path";
4+
import { fileURLToPath } from "node:url";
5+
import { closestMatch, fileHint, REDIRECTS_WITH_NEXT_STEP, redirectLine } from "./didYouMean.js";
36

47
describe("closestMatch", () => {
58
const commands = ["render", "preview", "publish", "lint", "check", "help"];
@@ -38,3 +41,22 @@ describe("fileHint", () => {
3841
expect(fileHint("package.json", ["measure"], [])).toBeUndefined();
3942
});
4043
});
44+
45+
describe("redirectLine", () => {
46+
it("is the line the hyperframes-cli skill carries for every redirect with a next step", () => {
47+
const skill = readFileSync(
48+
new URL("../../../../skills/hyperframes-cli/SKILL.md", import.meta.url),
49+
"utf8",
50+
);
51+
expect(REDIRECTS_WITH_NEXT_STEP).toContain("captions");
52+
for (const word of REDIRECTS_WITH_NEXT_STEP) {
53+
const line = redirectLine(word);
54+
expect(skill).toContain(line);
55+
const guide = /\.\.\/\S+\.md/.exec(line)?.[0] ?? "";
56+
const skillDir = dirname(
57+
fileURLToPath(new URL("../../../../skills/hyperframes-cli/SKILL.md", import.meta.url)),
58+
);
59+
expect(existsSync(resolve(skillDir, guide)), `${word} points at ${guide}`).toBe(true);
60+
}
61+
});
62+
});

‎packages/cli/src/utils/didYouMean.ts‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -45,20 +45,35 @@ export function closestNames(input: string, candidates: Iterable<string>, limit
4545
.map(({ name }) => name);
4646
}
4747

48-
const COMMAND_SYNONYMS: Record<string, string> = {
49-
search: "catalog",
50-
find: "catalog",
51-
browse: "catalog",
52-
registry: "catalog",
53-
list: "catalog",
54-
install: "add",
48+
const COMMAND_REDIRECTS: Record<string, { command: string; then?: string }> = {
49+
search: { command: "catalog" },
50+
find: { command: "catalog" },
51+
browse: { command: "catalog" },
52+
registry: { command: "catalog" },
53+
list: { command: "catalog" },
54+
install: { command: "add" },
55+
captions: {
56+
command: "transcribe",
57+
then: "then read ../hyperframes/references/captions.md",
58+
},
5559
};
5660

57-
export function synonymMatch(input: string, candidates: Iterable<string>): string | undefined {
58-
const target = COMMAND_SYNONYMS[input];
59-
return target !== undefined && [...candidates].includes(target) ? target : undefined;
61+
export function commandRedirect(
62+
input: string,
63+
candidates: Iterable<string>,
64+
): { command: string; then?: string } | undefined {
65+
const row = COMMAND_REDIRECTS[input];
66+
return row !== undefined && [...candidates].includes(row.command) ? row : undefined;
6067
}
6168

69+
export const redirectLine = (word: string): string => {
70+
const row = COMMAND_REDIRECTS[word]!;
71+
return `\`${word}\` is not a command: run \`${row.command}\`${row.then ? `, ${row.then}` : ""}.`;
72+
};
73+
export const REDIRECTS_WITH_NEXT_STEP = Object.keys(COMMAND_REDIRECTS).filter(
74+
(word) => COMMAND_REDIRECTS[word]!.then,
75+
);
76+
6277
export function fileHint(word: string, path: string[], names: string[]): string | undefined {
6378
if (path.length === 0 || names.length === 0 || !existsSync(word)) return undefined;
6479
const group = ["hyperframes", ...path].join(" ");

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
"files": 78
1111
},
1212
"hyperframes-cli": {
13-
"hash": "571fffd79a7d42f9",
13+
"hash": "2c977e879386734b",
1414
"files": 13
1515
},
1616
"hyperframes-registry": {

‎skills/hyperframes-cli/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,9 @@ A `--json` result may carry `_meta.updateNotice`: a newer HyperFrames release is
2828
| Desktop app | `open`, `catch-up` |
2929
| Upkeep | `doctor`, `browser`, `upgrade`, `usage`, `clean`, `feedback` |
3030

31-
`validate`, `inspect` and `layout` are deprecated aliases of `check`; `events` is telemetry for skills' own scripts. Don't run them.
31+
`captions` is not a command: run `transcribe`, then read ../hyperframes/references/captions.md.
32+
33+
`validate`, `inspect` and `layout` are deprecated aliases of `check`; `events` is skills' own telemetry. Don't run them.
3234

3335
## The loop
3436

0 commit comments

Comments
 (0)