diff --git a/packages/cli/src/cli.agentMode.test.ts b/packages/cli/src/cli.agentMode.test.ts index 9687e7045f..1e31039a73 100644 --- a/packages/cli/src/cli.agentMode.test.ts +++ b/packages/cli/src/cli.agentMode.test.ts @@ -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); diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 32c4271768..59f71b91f3 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -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( 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 { 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 { 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); + } + }); +}); diff --git a/packages/cli/src/utils/didYouMean.ts b/packages/cli/src/utils/didYouMean.ts index 65caa75edd..81f7164c18 100644 --- a/packages/cli/src/utils/didYouMean.ts +++ b/packages/cli/src/utils/didYouMean.ts @@ -45,20 +45,35 @@ export function closestNames(input: string, candidates: Iterable, limit .map(({ name }) => name); } -const COMMAND_SYNONYMS: Record = { - search: "catalog", - find: "catalog", - browse: "catalog", - registry: "catalog", - list: "catalog", - install: "add", +const COMMAND_REDIRECTS: Record = { + 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 | undefined { - const target = COMMAND_SYNONYMS[input]; - return target !== undefined && [...candidates].includes(target) ? target : undefined; +export function commandRedirect( + input: string, + candidates: Iterable, +): { 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(" "); diff --git a/skills-manifest.json b/skills-manifest.json index 3fde349bbd..dd4bb7bdfb 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -10,7 +10,7 @@ "files": 78 }, "hyperframes-cli": { - "hash": "571fffd79a7d42f9", + "hash": "2c977e879386734b", "files": 13 }, "hyperframes-registry": { diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index ae0300e623..d65e6fbc66 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -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