mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 00:18:27 +00:00
The error only said to run --help, so an agent guessed another flag. It now names every long flag the command declares, and --search points to --query.
255 lines
10 KiB
TypeScript
255 lines
10 KiB
TypeScript
import type { ArgDef, ArgsDef, CommandDef } from "citty";
|
|
import { CliUsageError } from "./commandResult.js";
|
|
import { c } from "../ui/colors.js";
|
|
import { closestMatch } from "./didYouMean.js";
|
|
|
|
// citty is permissive: an unrecognized flag (e.g. `render --out x` when the flag
|
|
// is `--output`/`-o`) is silently ignored instead of rejected, so the value is
|
|
// dropped and the command falls back to its default — a silent wrong result. We
|
|
// reject unknown flags up front with a clear message.
|
|
|
|
// Global flags citty / the CLI understand on every command. `--json` is not one: a command
|
|
// supports it by declaring a `json` arg, and every other command rejects it.
|
|
const ALWAYS_KNOWN = new Set(["help", "h", "version", "v"]);
|
|
|
|
// A camelCase arg name (`gifLoop`) is passed as `--gif-loop`; a kebab name is
|
|
// passed as-is. Accept both spellings so the validator matches citty's parsing.
|
|
function kebabCase(name: string): string {
|
|
return name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
|
|
}
|
|
|
|
function nameVariants(name: string): string[] {
|
|
const camel = name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
|
|
return [name, kebabCase(name), camel];
|
|
}
|
|
|
|
function declaredLongFlags(args: ArgsDef | undefined): string[] {
|
|
return Object.entries(args ?? {})
|
|
.filter(([, def]) => def?.type !== "positional")
|
|
.map(([name]) => `--${kebabCase(name)}`);
|
|
}
|
|
|
|
// Every spelling of one declared arg: name variants plus aliases. `def` may be undefined.
|
|
function* spellingsOf(name: string, def: ArgDef | undefined): Generator<string> {
|
|
yield* nameVariants(name);
|
|
const alias = def && "alias" in def ? def.alias : undefined;
|
|
if (typeof alias === "string") yield alias;
|
|
else if (Array.isArray(alias)) yield* alias;
|
|
}
|
|
|
|
function knownFlags(args: ArgsDef | undefined): Set<string> {
|
|
const known = new Set(ALWAYS_KNOWN);
|
|
for (const [name, def] of Object.entries(args ?? {})) {
|
|
for (const s of spellingsOf(name, def)) known.add(s);
|
|
}
|
|
return known;
|
|
}
|
|
|
|
// The unknown flag a single token introduces, or null when it's fine
|
|
// (positional, flag value, `--`, or all-known). `--no-foo` -> `foo`,
|
|
// `--flag=value` -> `flag`; a combined short group (`-ab`) checks each char.
|
|
// `--flag`, `--flag=value`, `--no-flag` -> the bare flag name.
|
|
function longFlagName(tok: string): string {
|
|
const name = tok.slice(2).split("=")[0] ?? "";
|
|
return name.startsWith("no-") ? name.slice(3) : name;
|
|
}
|
|
|
|
// A negative number (`-18`, `-0.5`) is a value: no flag is spelled with digits.
|
|
function isNegativeNumber(tok: string): boolean {
|
|
return /^-(\d+\.?\d*|\.\d+)$/.test(tok);
|
|
}
|
|
|
|
// Dash-prefixed and not a bare `-` (stdin) or a negative number: the only tokens that can name a flag.
|
|
function canNameFlag(tok: string): boolean {
|
|
return tok.startsWith("-") && tok !== "-" && !isNegativeNumber(tok);
|
|
}
|
|
|
|
function unknownFlagIn(tok: string, known: Set<string>): string | null {
|
|
if (!canNameFlag(tok)) return null; // positional or flag value
|
|
if (tok.startsWith("--")) {
|
|
const name = longFlagName(tok);
|
|
return name && !known.has(name) ? `--${name}` : null;
|
|
}
|
|
for (const ch of tok.slice(1).split("=")[0] ?? "") {
|
|
if (!known.has(ch)) return `-${ch}`; // combined shorts: check each char
|
|
}
|
|
return null;
|
|
}
|
|
|
|
// Flags agents carry over from other commands or tools, and the one that means the same here.
|
|
const FLAG_SYNONYMS: Readonly<Record<string, readonly string[]>> = {
|
|
from: ["start"],
|
|
to: ["end"],
|
|
start: ["from"],
|
|
end: ["to"],
|
|
o: ["out", "output"],
|
|
search: ["query"],
|
|
};
|
|
|
|
function unknownFlagError(
|
|
flag: string,
|
|
known: Set<string>,
|
|
declared: string[],
|
|
path: string,
|
|
): CliUsageError {
|
|
const command = `hyperframes ${path ? `${path} ` : ""}`.trim();
|
|
if (flag === "--json") {
|
|
return new CliUsageError(`${command} has no JSON output.`, {
|
|
code: "json_unsupported",
|
|
hint: "Run it without --json.",
|
|
});
|
|
}
|
|
const longNames = [...known].filter((name) => name.length > 1);
|
|
const name = flag.replace(/^--?/, "");
|
|
const match =
|
|
FLAG_SYNONYMS[name]?.find((s) => known.has(s)) ??
|
|
(flag.startsWith("--") ? closestMatch(name, longNames) : undefined);
|
|
const hint = [
|
|
match && `Did you mean --${match}?`,
|
|
declared.length > 0 && `Its flags: ${declared.join(", ")}.`,
|
|
`Run 'hyperframes ${path ? `${path} ` : ""}--help' for what each does.`,
|
|
]
|
|
.filter(Boolean)
|
|
.join(" ");
|
|
return new CliUsageError(`Unknown flag: ${flag}`, { hint, code: "unknown_flag" });
|
|
}
|
|
|
|
/**
|
|
* Throw on the first flag in `rawArgs` not declared by `cmd` (its args + aliases
|
|
* + the global set). Only dash-prefixed tokens are inspected, so positionals and
|
|
* flag values pass through untouched. Stops at `--`.
|
|
*/
|
|
export function assertKnownFlags(cmd: CommandDef<ArgsDef>, rawArgs: string[], path = ""): void {
|
|
if (!Array.isArray(rawArgs)) return;
|
|
// citty types `args` as Resolvable<ArgsDef> (it may be a fn/promise); every
|
|
// hyperframes command uses a static object, so treat anything else as "no
|
|
// declared args" and skip validation rather than risk a wrong rejection.
|
|
const rawDef = cmd.args;
|
|
const args = rawDef && typeof rawDef === "object" ? (rawDef as ArgsDef) : undefined;
|
|
const known = knownFlags(args);
|
|
for (const tok of rawArgs) {
|
|
if (tok === "--") break;
|
|
const bad = unknownFlagIn(tok, known);
|
|
if (bad) throw unknownFlagError(bad, known, declaredLongFlags(args), path);
|
|
}
|
|
}
|
|
|
|
// Spellings of a command's own string/enum args (the types citty lets swallow the next
|
|
// token), mapped to the canonical arg name. Args in `ignore` are left out.
|
|
function stringValueFlagOwners(
|
|
args: ArgsDef | undefined,
|
|
ignore: ReadonlySet<string> | undefined,
|
|
): Map<string, string> {
|
|
const owners = new Map<string, string>();
|
|
for (const [name, def] of Object.entries(args ?? {})) {
|
|
if (def?.type !== "string" && def?.type !== "enum") continue;
|
|
if (ignore?.has(name)) continue;
|
|
for (const s of spellingsOf(name, def)) owners.set(s, name);
|
|
}
|
|
return owners;
|
|
}
|
|
|
|
// `--flag` -> "flag", `-f` -> "f"; null for `--flag=value` or a non-flag token.
|
|
function ownableFlagSpelling(tok: string): string | null {
|
|
if (tok.includes("=")) return null;
|
|
if (tok.startsWith("--")) return tok.slice(2);
|
|
if (tok.length === 2 && tok.startsWith("-")) return tok.slice(1);
|
|
return null;
|
|
}
|
|
|
|
// Keyed by command path. "rewrite": bare flag becomes `--flag=` (check's parseFrameCheck reads
|
|
// that as defaults). "ignore": the command recovers the swallowed value itself
|
|
// (upgrade's resolveProjectArgs).
|
|
const SWALLOW_REWRITE_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {
|
|
check: new Set(["frame-check"]),
|
|
};
|
|
const SWALLOW_IGNORE_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {
|
|
upgrade: new Set(["project"]),
|
|
};
|
|
|
|
function swallowedValueMessage(flagName: string, next: string, hint: string): string {
|
|
if (next === "--")
|
|
return `Missing value for --${flagName}: "--" ends option parsing here; ${hint}`;
|
|
return `Missing value for --${flagName}: value "${next}" appears to have swallowed the next option; ${hint}`;
|
|
}
|
|
|
|
/** For a caller whose own try/catch prints the error (check.ts's run()). */
|
|
export function swallowedFlagUsageError(flagName: string, next: string): CliUsageError {
|
|
const hint = `use --${flagName}= or move --${flagName} to the end`;
|
|
return new CliUsageError(swallowedValueMessage(flagName, next, hint));
|
|
}
|
|
|
|
// Prints and marks `presented`: otherwise executeCli dumps usage to stdout, breaking `--json`.
|
|
function throwSwallowedFlagError(flagName: string, next: string): never {
|
|
const hint = `pass one: --${flagName} <value> or --${flagName}=<value>`;
|
|
const message = swallowedValueMessage(flagName, next, hint);
|
|
console.error(c.error(message));
|
|
throw new CliUsageError(message, { presented: true });
|
|
}
|
|
|
|
export interface SwallowGuardResult {
|
|
rawArgs: string[];
|
|
rewritten: boolean;
|
|
}
|
|
|
|
// End of argv and a bare `-` (stdin) are never a swallow; `--` or a known flag spelling is.
|
|
function looksLikeSwallowedFlag(next: string | undefined, known: Set<string>): boolean {
|
|
if (next === undefined || next === "-" || isNegativeNumber(next)) return false;
|
|
return next === "--" || (next.startsWith("-") && unknownFlagIn(next, known) === null);
|
|
}
|
|
|
|
// The arg `tok` spells when citty would swallow `next` as its value, else undefined.
|
|
function swallowingArgName(
|
|
tok: string,
|
|
next: string | undefined,
|
|
owners: Map<string, string>,
|
|
known: Set<string>,
|
|
): string | undefined {
|
|
const spelling = ownableFlagSpelling(tok);
|
|
const ownerArgName = spelling ? owners.get(spelling) : undefined;
|
|
return ownerArgName && looksLikeSwallowedFlag(next, known) ? ownerArgName : undefined;
|
|
}
|
|
|
|
// A rewrite flag directly followed by `--no-x` is bare too (check's `--frame-check --no-browser-gpu`).
|
|
function rewriteArgName(
|
|
tok: string,
|
|
after: string | undefined,
|
|
owners: Map<string, string>,
|
|
rewriteFlags: ReadonlySet<string> | undefined,
|
|
): string | undefined {
|
|
if (!after?.startsWith("--no-")) return undefined;
|
|
const spelling = ownableFlagSpelling(tok);
|
|
const name = spelling ? owners.get(spelling) : undefined;
|
|
return name && rewriteFlags?.has(name) ? name : undefined;
|
|
}
|
|
|
|
// Reject a string/enum flag whose value citty swallowed from the next flag (`catalog --query --json`).
|
|
// Scans rawArgs: parsed args cannot tell `--query --json` from the legitimate `--query=--json`.
|
|
export function guardSwallowedFlagValues(
|
|
// `CommandDef<any>`: citty's CommandContext is invariant in its args type.
|
|
cmd: CommandDef<any> | undefined,
|
|
path: string,
|
|
rawArgs: string[],
|
|
): SwallowGuardResult {
|
|
if (!Array.isArray(rawArgs)) return { rawArgs, rewritten: false };
|
|
const rawDef = cmd?.args;
|
|
const argsDef = rawDef && typeof rawDef === "object" ? (rawDef as ArgsDef) : undefined;
|
|
const known = knownFlags(argsDef);
|
|
const owners = stringValueFlagOwners(argsDef, SWALLOW_IGNORE_FLAGS[path]);
|
|
const rewriteFlags = SWALLOW_REWRITE_FLAGS[path];
|
|
|
|
let out: string[] | undefined;
|
|
for (const [i, tok] of rawArgs.entries()) {
|
|
if (tok === "--") break;
|
|
// citty drops every `--no-x` before parsing, so the token after them is what gets swallowed.
|
|
const next = rawArgs.slice(i + 1).find((t) => !t.startsWith("--no-"));
|
|
const ownerArgName = swallowingArgName(tok, next, owners, known);
|
|
const rewrite = rewriteArgName(tok, rawArgs[i + 1], owners, rewriteFlags) ?? ownerArgName;
|
|
if (!rewrite) continue;
|
|
if (!rewriteFlags?.has(rewrite)) throwSwallowedFlagError(rewrite, next as string);
|
|
out ??= rawArgs.slice();
|
|
out[i] = `${tok}=`;
|
|
}
|
|
return { rawArgs: out ?? rawArgs, rewritten: out !== undefined };
|
|
}
|