Files
hyperframes/packages/cli/src/utils/reject-extra-positionals.ts
T
Miguel Ángel 4178a8f95d fix(cli): reject extra positional arguments on every command (#4905)
* fix(cli): reject extra positional arguments on every command

* fix(cli): read the command name without assuming a resolved meta

* fix(cli): join free-text words for catalog and tts, reject a bad repo root

* test(cli): load the listed commands through static imports

* fix(cli): keep a tts file path out of the word join and read the parsed json flag

* fix(cli): apply the file exception only to a tts .txt path

* fix(cli): keep usageLine private and test the json fallback for undeclared json

* fix(cli): keep extra arguments and the repo root value out of telemetry

* test(cli): type the skills update lookup

* fix(cli): read json mode from the parsed flag, reject tts words with --text-file, restore add's hint

* fix(cli): check tts words with --text-file before --list and test --json=false
2026-10-02 18:34:53 +00:00

84 lines
3.2 KiB
TypeScript

import type { ArgsDef, CommandDef } from "citty";
import { CliUsageError } from "./commandResult.js";
import { isTextFile } from "./textFile.js";
// citty binds each declared positional in order and leaves the rest in `args._`, where they were
// silently dropped (`render ./proj out.mp4` rendered to the default path). Reject them up front.
// Leaf commands that read extra positionals from `args._` on purpose, by command path.
export const ACCEPTS_EXTRA_POSITIONALS = new Set([
"compare",
"figma asset",
"skills update",
"timeline set",
]);
// Free-text commands: their last positional takes every remaining word (`tts hello world`).
export const JOINS_EXTRA_POSITIONALS = new Set(["catalog", "tts"]);
const EXTRA_POSITIONAL_HINTS: Record<string, string> = {
add: "Run add once per item, or pass a single tag to install every item tagged with it.",
};
// citty parses `--json` on every command (`--json=1` as "1"); after `--` it is a positional.
function wantsJson(value: unknown): boolean {
return value === true || (typeof value === "string" && value !== "false" && value !== "0");
}
function declaredArgs(cmd: CommandDef<ArgsDef>): ArgsDef {
const raw = cmd.args;
return raw && typeof raw === "object" ? (raw as ArgsDef) : {};
}
function usageLine(path: string, args: ArgsDef): string {
const parts = ["hyperframes", path];
let hasOptions = false;
for (const [name, def] of Object.entries(args)) {
if (def.type !== "positional") {
hasOptions = true;
continue;
}
const optional = def.required === false || def.default !== undefined;
parts.push(optional ? `[${name.toUpperCase()}]` : `<${name.toUpperCase()}>`);
}
if (hasOptions) parts.push("[OPTIONS]");
return parts.join(" ");
}
/** Join a free-text command's trailing words, else throw a usage error naming the extras. */
export function resolveExtraPositionals(
cmd: CommandDef<ArgsDef>,
path: string,
parsed: Record<string, unknown> | undefined,
): void {
if (ACCEPTS_EXTRA_POSITIONALS.has(path)) return;
const args = declaredArgs(cmd);
const positionals = Object.entries(args).filter(([, def]) => def.type === "positional");
const given = (Array.isArray(parsed?._) ? parsed._ : []).map(String);
const extra = given.slice(positionals.length);
if (extra.length === 0) return;
const last = positionals.at(-1)?.[0];
const words = given.slice(positionals.length - 1);
// `tts script.txt extra` reads the file, so its first word is a path, not free text.
const ttsFile = path === "tts" && isTextFile(words[0]!);
if (parsed && last && JOINS_EXTRA_POSITIONALS.has(path) && !ttsFile) {
parsed[last] = words.join(" ");
return;
}
const plural = extra.length === 1 ? "" : "s";
const message =
`Unexpected extra argument${plural} for hyperframes ${path}: ${extra.join(", ")}\n` +
`Usage: ${usageLine(path, args)}` +
(EXTRA_POSITIONAL_HINTS[path] ? `\n${EXTRA_POSITIONAL_HINTS[path]}` : "");
if (wantsJson(parsed?.json)) console.log(JSON.stringify({ ok: false, error: message }));
else console.error(message);
// Telemetry reads the thrown message: the command path and a count, never the arguments.
throw new CliUsageError(
`${extra.length} unexpected extra argument${plural} for hyperframes ${path}`,
{
presented: true,
},
);
}