mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 15:24:19 +00:00
* fix(cli): report unknown-flag errors + cover nested subcommands (HF#2033) Two flag-hygiene gaps behind the assertKnownFlags arc: 1. Telemetry loss: assertKnownFlags ran BEFORE the try/catch in the command wrapper, so an unknown-flag throw skipped reportCommandFailure entirely — zero signal on how often users hit bad flags. Moved the assertion inside the try so it reports like any other failure. 2. Nested-subcommand scope: cli.ts wraps only the top-level command loaders, so command groups' leaves (cloud/*, auth/*, figma/*, lambda/*, capture/*, skills) were never wrapped — citty dispatches to the leaf, whose run had no assertion and no failure reporting. So `hyperframes cloud render --badflag` silently ignored the flag. trackCommandFailures now recurses through cmd.subCommands (normalizing citty's Resolvable entries to loaders) and wraps every leaf. Identity is preserved for bare no-run/no-subcommand defs. Verified: `auth status --badflag` now errors "Unknown flag: --badflag" (previously silent); `auth --help` still dispatches; top-level `lint --badflag` still rejected. Tests: unknown-flag rejection is reported, and a nested subcommand's failure reaches onFailure. * test(cli): guard indexed subCommands access for noUncheckedIndexedAccess CI Typecheck (tsc, unlike the local tsup build) flagged the nested-subcommand test: indexing `subCommands["render"]` yields `T | undefined` under noUncheckedIndexedAccess, so invoking it tripped TS2722/TS18048. Guard the loader before calling it.
97 lines
4.0 KiB
TypeScript
97 lines
4.0 KiB
TypeScript
import type { CommandDef } from "citty";
|
|
import { assertKnownFlags } from "./reject-unknown-flags.js";
|
|
|
|
// citty types subcommands as `CommandDef<any>` (SubCommandsDef); mirror that so
|
|
// each command's specific args type is accepted without per-command generics.
|
|
type AnyCommandDef = CommandDef<any>;
|
|
|
|
/**
|
|
* Wrap a lazy command loader so a thrown failure is reported via `onFailure`
|
|
* before it propagates. citty's `runMain` catches command errors and exits 1
|
|
* without re-throwing, so this is the only place to capture the reason. The
|
|
* error is re-thrown unchanged, preserving citty's print + exit-1 behavior.
|
|
*
|
|
* `onFailure` is awaited so it can resolve the (lazily-loaded) telemetry module
|
|
* before the error propagates — otherwise a command that throws before the
|
|
* telemetry import settles would lose its event. A throw from `onFailure` is
|
|
* swallowed so telemetry can never mask the real command failure.
|
|
*
|
|
* Commands that call `process.exit()` themselves bypass this (the process is
|
|
* already gone) and must report their failure inline.
|
|
*/
|
|
export function trackCommandFailures(
|
|
load: () => Promise<AnyCommandDef>,
|
|
onFailure: (err: unknown) => void | Promise<void>,
|
|
): () => Promise<AnyCommandDef> {
|
|
return () => load().then((cmd) => wrapCommand(cmd, onFailure));
|
|
}
|
|
|
|
/**
|
|
* Wrap a resolved command's `run` (assert-flags + report-failure) AND
|
|
* recursively wrap every entry in its `subCommands`. Two HF#2033 fixes live
|
|
* here:
|
|
* 1. `assertKnownFlags` runs INSIDE the try, so an unknown-flag throw is
|
|
* routed through `onFailure` (telemetry) like any other failure — it
|
|
* used to throw before the try and lose the event entirely.
|
|
* 2. Recursion covers nested command groups (`cloud/*`, `auth/*`, `figma/*`,
|
|
* `lambda/*`, `capture/*`, `skills`). cli.ts only wraps the top-level
|
|
* loaders, so before this a `hyperframes cloud render --badflag` silently
|
|
* ignored the flag and reported nothing — citty dispatches to the leaf,
|
|
* whose `run` was never wrapped.
|
|
*/
|
|
function wrapCommand(
|
|
cmd: AnyCommandDef,
|
|
onFailure: (err: unknown) => void | Promise<void>,
|
|
): AnyCommandDef {
|
|
const run = cmd.run;
|
|
// Nothing to wrap (no run, no nested subcommands) — preserve identity.
|
|
if (typeof run !== "function" && !cmd.subCommands) return cmd;
|
|
|
|
const wrapped: AnyCommandDef = { ...cmd };
|
|
if (typeof run === "function") {
|
|
wrapped.run = async (ctx: Parameters<typeof run>[0]) => {
|
|
try {
|
|
// Reject unknown flags before the command body: citty silently ignores
|
|
// them otherwise, dropping the value (e.g. `render --out x` fell back to
|
|
// the default output path). Inside the try so the rejection is reported.
|
|
assertKnownFlags(cmd, ctx?.rawArgs ?? []);
|
|
return await run(ctx);
|
|
} catch (err) {
|
|
try {
|
|
await onFailure(err);
|
|
} catch {
|
|
// Telemetry must never mask the real command failure.
|
|
}
|
|
throw err;
|
|
}
|
|
};
|
|
}
|
|
if (cmd.subCommands) {
|
|
const wrappedSubs: Record<string, () => Promise<AnyCommandDef>> = {};
|
|
for (const [name, sub] of Object.entries(cmd.subCommands)) {
|
|
// citty subCommands are Resolvable<CommandDef>: a def, a promise, or a
|
|
// (possibly async) loader. Normalize to a loader that resolves then wraps.
|
|
wrappedSubs[name] = () =>
|
|
Promise.resolve(typeof sub === "function" ? (sub as () => unknown)() : sub).then((c) =>
|
|
wrapCommand(c as AnyCommandDef, onFailure),
|
|
);
|
|
}
|
|
wrapped.subCommands = wrappedSubs;
|
|
}
|
|
return wrapped;
|
|
}
|
|
|
|
/**
|
|
* Report a command failure to telemetry, loading the telemetry module on demand
|
|
* (keeps it off the CLI cold-start path) and awaiting it so the event is
|
|
* enqueued before the caller re-throws / exits. Best-effort — never throws.
|
|
*/
|
|
export async function reportCommandFailure(command: string, err: unknown): Promise<void> {
|
|
try {
|
|
const { trackCommandFailure } = await import("../telemetry/events.js");
|
|
trackCommandFailure(command, err);
|
|
} catch {
|
|
// ignore: a telemetry failure must not affect the command's exit path
|
|
}
|
|
}
|