Files
hyperframes/packages/cli/src/utils/command-failure-tracking.ts
T
Miguel Ángel 38b27c4d82 fix(cli): report unknown-flag errors + cover nested subcommands (HF#2033) [P2] (#2072)
* 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.
2026-07-08 16:24:36 -04:00

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
}
}