mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* feat(cli): define every command through one factory and test them all as an agent Every command now comes from defineCommand in utils/defineCommand.ts. A lint rule bans importing defineCommand from citty anywhere else, and a new contract test walks the command registry in cli.ts, checks each command was built by the factory, and runs it the way a coding agent does: no terminal, stdin closed, CI=1, CLAUDECODE=1 and a home folder of its own. Usage errors now exit 2: unknown flags, extra positionals, and citty's own parse errors (missing argument, bad value, unknown or missing subcommand). An unknown flag names the help command instead of printing nothing else. isUnattended() in utils/attendedTerminal.ts is the one answer to "can a person respond here". It is true without a TTY on stdin or stdout, under CI (any value except "false" or "0"), when the existing agent detection finds an agent, or with HYPERFRAMES_AGENT=1. Color is off when it is true. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(cli): spawn preview in the agent-mode test only when the studio packages are built From source, preview refuses to load until the studio workspace packages are built, and the CLI test jobs do not build them. preview is still checked for being defined with the shared factory. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(cli): count only agent-run shells as unattended, and exit 2 for missing arguments isUnattended() used the telemetry fingerprint detectAgentRuntime(), which also matches a person typing in Cursor's or Windsurf's terminal (TERM_PROGRAM) and any Replit shell (REPL_ID, REPLIT_USER). It now uses isAgentDriven(), which keeps only markers an agent sets on the shells it runs: CURSOR_AGENT counts, TERM_PROGRAM=cursor, TERM_PROGRAM=windsurf and the Replit variables do not. The hand-written argument checks in lambda, cloudrun, lambda policies, capture, remove-background, init (--resolution), tts (--lang) and cloud render (--idempotency-key, --dry-run) exited 1. They are usage errors and now exit 2. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
111 lines
4.8 KiB
TypeScript
111 lines
4.8 KiB
TypeScript
import { parseArgs } from "citty";
|
|
import type { ArgsDef, CommandContext, CommandDef } from "citty";
|
|
import { resolveExtraPositionals } from "./reject-extra-positionals.js";
|
|
import { assertKnownFlags, guardSwallowedFlagValues } 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 leaf commands and nested subcommands share the
|
|
* unknown-flag guard. Errors propagate unchanged to the executable boundary,
|
|
* which reports them.
|
|
*/
|
|
export function trackCommandFailures(
|
|
load: () => Promise<AnyCommandDef>,
|
|
): () => Promise<AnyCommandDef> {
|
|
return () => load().then((cmd) => wrapCommand(cmd, commandName(cmd)));
|
|
}
|
|
|
|
function commandName(cmd: AnyCommandDef): string {
|
|
const name = (cmd.meta as { name?: unknown } | undefined)?.name;
|
|
return typeof name === "string" ? name : "";
|
|
}
|
|
|
|
/**
|
|
* Wrap a resolved command's `run` (assert flags and positional count) AND
|
|
* recursively wrap every entry in its `subCommands`. Two HF#2033 fixes live
|
|
* here:
|
|
* 1. `assertKnownFlags` runs in the wrapped command, so an unknown-flag
|
|
* throw reaches the executable boundary like every other failure.
|
|
* 2. Recursion covers nested command groups (`cloud/*`, `auth/*`, `figma/*`,
|
|
* `lambda/*`, `capture/*`, `skills`). Without it, a nested command's
|
|
* unknown flags would bypass the leaf's guard.
|
|
*/
|
|
function wrapCommand(cmd: AnyCommandDef, path: string): 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]) => {
|
|
// 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).
|
|
//
|
|
// A command group (subCommands + fallback-help run) delegating to a
|
|
// subcommand must NOT assert here: the flags belong to the subcommand's
|
|
// table, not the group's, and would be falsely rejected (e.g.
|
|
// `figma component <ref> --name x`). The wrapped subcommand loaders
|
|
// below assert the leaf's own table, so typo protection is preserved.
|
|
// Heuristic caveat: "first non-dash token names a subcommand" is sound
|
|
// only while command groups declare no flags of their own — if a group
|
|
// grows a flag whose value could match a subcommand name, replace this
|
|
// with a real argv parse.
|
|
const rawArgs = ctx?.rawArgs ?? [];
|
|
const firstPositional = rawArgs.find((tok) => tok && !tok.startsWith("-"));
|
|
const delegatesToSub =
|
|
cmd.subCommands != null &&
|
|
firstPositional != null &&
|
|
Object.prototype.hasOwnProperty.call(cmd.subCommands, firstPositional);
|
|
if (!delegatesToSub) guardLeafFlags(cmd, path, ctx, rawArgs);
|
|
// Groups read `args._[0]` to pick fallback help, so only leaves get the count check.
|
|
if (!cmd.subCommands) resolveExtraPositionals(cmd, path, ctx?.args);
|
|
return await run(ctx);
|
|
};
|
|
}
|
|
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, `${path} ${name}`),
|
|
);
|
|
}
|
|
wrapped.subCommands = wrappedSubs;
|
|
}
|
|
return wrapped;
|
|
}
|
|
|
|
// citty built ctx.args before this ran; re-parse when the swallow guard rewrites rawArgs.
|
|
function guardLeafFlags(
|
|
cmd: AnyCommandDef,
|
|
path: string,
|
|
ctx: CommandContext<any>,
|
|
rawArgs: string[],
|
|
): void {
|
|
assertKnownFlags(cmd, rawArgs, path);
|
|
const guarded = guardSwallowedFlagValues(cmd, path, rawArgs);
|
|
if (!guarded.rewritten) return;
|
|
ctx.rawArgs = guarded.rawArgs;
|
|
ctx.args = parseArgs(guarded.rawArgs, (cmd.args ?? {}) as ArgsDef);
|
|
}
|
|
|
|
/**
|
|
* 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
|
|
}
|
|
}
|