mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
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:
@@ -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
@@ -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;
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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(" ");
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
"files": 78
|
||||
},
|
||||
"hyperframes-cli": {
|
||||
"hash": "571fffd79a7d42f9",
|
||||
"hash": "2c977e879386734b",
|
||||
"files": 13
|
||||
},
|
||||
"hyperframes-registry": {
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user