mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(cli): every --json failure answers with one envelope, and --json only where supported
Under --json, failures came back as a bare string (`"error": "Command failed"`
from lint), a command-specific shape, or nothing at all on stdout (info,
compositions, render, snapshot, cloud get). Now every failure is
`{"ok": false, "error": {"code", "message", "hint"?}}`:
- jsonFailure() in utils/jsonError.ts builds it. The commands that printed
`{ok: false, error: "<text>"}` use it, keeping their extra fields (lint's
findings, validate's errors). A refused timeline edit now writes it to stdout
instead of stderr, and keeps its `reason` and `fix` fields.
- When a --json run fails without writing anything to stdout, cli.ts writes the
envelope itself: usage errors carry their own code (unknown_flag,
unknown_command, json_unsupported, confirmation_required), anything else is
runtime_error with the message the command printed on stderr.
--json is no longer accepted by every command. A command supports it by
declaring a `json` arg; the others reject it with exit 2 and the code
json_unsupported, instead of accepting the flag and printing prose.
The contract test now checks every command's --json path, and packages/cli
gets an AGENTS.md with the rules: stdout is data, stderr is messages, never
prompt without a TTY, exit 2 for usage errors, --json always returns an
envelope.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(cli): put the real failure in the --json envelope, never the generic text or a notice
lint --json and check --json in a directory with no project answered
"message": "Command failed". The project check reports the problem, then
throws a presented "Command failed" with the real error as its cause, and the
command's own catch serialized that generic text. failureMessage() now returns
the cause, or else what the command reported through errorBox, and every
command catch that writes a --json failure uses it (lint, check, validate,
layout, snapshot, compare, grade-compare, media-treatment, tts,
remove-background, add, skills, lambda policies). compare, grade-compare and
add share failCaught() for that catch.
The boundary envelope follows the same order: the error's own message unless
it is the generic one, then its cause, then the errorBox title and hint, and
only then the stderr text. Notices (the telemetry disclosure, deprecation
lines, diag progress) are no longer captured, so validate, layout and inspect
no longer put "is deprecated" in the error message.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(cli): render --json keeps human output off stdout so a failure answers with the envelope
Under --json a single render printed its header, lint findings and progress on
stdout, so a later failure such as `render --variables '{bad' --json` ended
with no JSON envelope. --json now silences that output the way --batch --json
already did, and --variables is parsed before the browser check so a bad value
fails without a Chrome download.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(cli): a --strict lint abort says why, even under --json
Under --json the render is quiet, so a --strict lint abort printed nothing and
the envelope said only "Command failed". The abort is now an error box on
stderr in every mode, naming the error and warning counts and the first
finding, and the --json envelope carries the same message. Lint now runs
before the browser check, so the abort never waits on a Chrome download.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(cli): time the render setup cancel from the wrapper's exit
The 1 s budget started when the command did. With lint now running before the
browser check, its subprocess (about 250 ms here) sat inside that budget, and
the test failed once under load. The budget now starts when the wrapper exits,
which is the latency the test is about.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
334 lines
12 KiB
TypeScript
334 lines
12 KiB
TypeScript
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
|
import { tmpdir } from "node:os";
|
|
import { join } from "node:path";
|
|
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
|
import { runCommand, type CommandDef } from "citty";
|
|
import { CliUsageError } from "./commandResult.js";
|
|
import { resolveExtraPositionals } from "./reject-extra-positionals.js";
|
|
|
|
const trackCommandFailure = vi.fn();
|
|
vi.mock("../telemetry/events.js", () => ({
|
|
trackCommandFailure: (...args: unknown[]) => trackCommandFailure(...args),
|
|
}));
|
|
|
|
const { trackCommandFailures, reportCommandFailure } =
|
|
await import("./command-failure-tracking.js");
|
|
|
|
function defineRun(run: CommandDef["run"]): CommandDef {
|
|
return { meta: { name: "test" }, run };
|
|
}
|
|
|
|
describe("trackCommandFailures", () => {
|
|
it("re-throws when run() rejects so the executable boundary can report it", async () => {
|
|
const boom = new Error("ffmpeg not found");
|
|
const wrapped = trackCommandFailures(() =>
|
|
Promise.resolve(defineRun(() => Promise.reject(boom))),
|
|
);
|
|
|
|
const cmd = await wrapped();
|
|
await expect((cmd.run as () => Promise<unknown>)()).rejects.toBe(boom);
|
|
});
|
|
|
|
it("returns the command value when run() succeeds", async () => {
|
|
const wrapped = trackCommandFailures(() =>
|
|
Promise.resolve(defineRun(() => Promise.resolve("ok" as unknown as void))),
|
|
);
|
|
|
|
const cmd = await wrapped();
|
|
await expect((cmd.run as () => Promise<unknown>)()).resolves.toBe("ok");
|
|
});
|
|
|
|
it("rejects an unknown flag on a leaf command", async () => {
|
|
const wrapped = trackCommandFailures(() =>
|
|
Promise.resolve({
|
|
meta: { name: "leaf" },
|
|
args: { out: { type: "string" } },
|
|
run: () => Promise.resolve(),
|
|
} as CommandDef),
|
|
);
|
|
const cmd = await wrapped();
|
|
await expect(
|
|
(cmd.run as (ctx: unknown) => Promise<unknown>)({ rawArgs: ["--bogus", "x"] }),
|
|
).rejects.toThrow(/--bogus/);
|
|
});
|
|
|
|
it("skips the unknown-flag check when a command group delegates to a subcommand", async () => {
|
|
// `figma component <ref> --name x`: --name belongs to the subcommand's
|
|
// table; the group (subCommands + fallback-help run) must not reject it.
|
|
const run = vi.fn(() => Promise.resolve());
|
|
const wrapped = trackCommandFailures(() =>
|
|
Promise.resolve({
|
|
meta: { name: "figma" },
|
|
subCommands: { component: () => Promise.resolve({ meta: { name: "component" } }) },
|
|
run,
|
|
} as unknown as CommandDef),
|
|
);
|
|
const cmd = await wrapped();
|
|
await expect(
|
|
(cmd.run as (ctx: unknown) => Promise<unknown>)({
|
|
rawArgs: ["component", "KEY:1-2", "--name", "hero"],
|
|
}),
|
|
).resolves.toBeUndefined();
|
|
expect(run).toHaveBeenCalled();
|
|
});
|
|
|
|
it("still rejects an unknown flag when the group is NOT delegating", async () => {
|
|
const wrapped = trackCommandFailures(() =>
|
|
Promise.resolve({
|
|
meta: { name: "figma" },
|
|
subCommands: { component: () => Promise.resolve({ meta: { name: "component" } }) },
|
|
run: () => Promise.resolve(),
|
|
} as unknown as CommandDef),
|
|
);
|
|
const cmd = await wrapped();
|
|
await expect(
|
|
(cmd.run as (ctx: unknown) => Promise<unknown>)({ rawArgs: ["--bogus"] }),
|
|
).rejects.toThrow(/--bogus/);
|
|
});
|
|
|
|
it("passes through a command with no run() untouched", async () => {
|
|
const parent: CommandDef = { meta: { name: "parent" } };
|
|
const wrapped = trackCommandFailures(() => Promise.resolve(parent));
|
|
|
|
const cmd = await wrapped();
|
|
expect(cmd).toBe(parent);
|
|
});
|
|
|
|
it("re-throws an unknown-flag rejection to the executable boundary", async () => {
|
|
const cmd = {
|
|
meta: { name: "render" },
|
|
args: { output: { type: "string", alias: "o" } },
|
|
run: vi.fn(() => Promise.resolve()),
|
|
} as unknown as CommandDef;
|
|
const wrapped = trackCommandFailures(() => Promise.resolve(cmd));
|
|
|
|
const resolved = await wrapped();
|
|
await expect(
|
|
(resolved.run as (ctx: unknown) => Promise<unknown>)({ rawArgs: ["--nope", "x"] }),
|
|
).rejects.toThrow(/unknown flag/i);
|
|
expect(cmd.run).not.toHaveBeenCalled(); // body never ran — flag rejected first
|
|
});
|
|
|
|
it("recursively wraps nested subcommands so their failures reach the boundary", async () => {
|
|
const boom = new Error("nested boom");
|
|
const group: CommandDef = {
|
|
meta: { name: "cloud" },
|
|
subCommands: {
|
|
render: defineRun(() => Promise.reject(boom)),
|
|
},
|
|
};
|
|
const wrapped = trackCommandFailures(() => Promise.resolve(group));
|
|
|
|
const resolvedGroup = await wrapped();
|
|
const subLoader = (resolvedGroup.subCommands as Record<string, () => Promise<CommandDef>>)
|
|
.render;
|
|
if (!subLoader) throw new Error("expected a wrapped 'render' subcommand loader");
|
|
const leaf = await subLoader();
|
|
await expect((leaf.run as () => Promise<unknown>)()).rejects.toBe(boom);
|
|
});
|
|
});
|
|
|
|
describe("trackCommandFailures: extra positionals", () => {
|
|
const leaf = (name: string, run = vi.fn()): CommandDef =>
|
|
({
|
|
meta: { name },
|
|
args: {
|
|
dir: { type: "positional", required: false },
|
|
json: { type: "boolean", default: false },
|
|
},
|
|
run,
|
|
}) as CommandDef;
|
|
const wrap = (cmd: CommandDef) => trackCommandFailures(() => Promise.resolve(cmd))();
|
|
let errorSpy: ReturnType<typeof vi.spyOn>;
|
|
let logSpy: ReturnType<typeof vi.spyOn>;
|
|
const tempDirs: string[] = [];
|
|
const tempDir = () => {
|
|
const dir = mkdtempSync(join(tmpdir(), "hf-join-"));
|
|
tempDirs.push(dir);
|
|
return dir;
|
|
};
|
|
|
|
beforeEach(() => {
|
|
errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
|
|
logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
|
|
});
|
|
|
|
afterEach(() => {
|
|
errorSpy.mockRestore();
|
|
logSpy.mockRestore();
|
|
for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
|
|
});
|
|
|
|
it("throws a presented error whose message carries a count, never the arguments", async () => {
|
|
const error = await runCommand(await wrap(leaf("render")), {
|
|
rawArgs: ["./proj", "secret-launch", "Jane"],
|
|
}).catch((e: unknown) => e);
|
|
expect(error).toBeInstanceOf(CliUsageError);
|
|
expect((error as CliUsageError).result.presented).toBe(true);
|
|
expect((error as Error).message).toBe("2 unexpected extra arguments for hyperframes render");
|
|
});
|
|
|
|
it("labels a required positional <NAME> and an optional one [NAME]", async () => {
|
|
const cmd = {
|
|
meta: { name: "keyframes" },
|
|
args: { file: { type: "positional" }, at: { type: "positional", required: false } },
|
|
run: vi.fn(),
|
|
};
|
|
await expect(
|
|
runCommand(await wrap(cmd as CommandDef), { rawArgs: ["a", "b", "c"] }),
|
|
).rejects.toThrow(CliUsageError);
|
|
expect(errorSpy.mock.calls.flat().join("\n")).toContain(
|
|
"Usage: hyperframes keyframes <FILE> [AT]",
|
|
);
|
|
});
|
|
|
|
it.each([
|
|
["figma asset", () => import("../commands/figma/asset.js")],
|
|
[
|
|
"skills update",
|
|
async () => ({
|
|
default: (
|
|
(await import("../commands/skills.js")).default.subCommands as Record<string, unknown>
|
|
).update,
|
|
}),
|
|
],
|
|
])("lets the real %s command read several positionals", async (path, load) => {
|
|
const def = (await (load as () => Promise<{ default: unknown }>)()).default;
|
|
const cmd = (typeof def === "function" ? await def() : def) as CommandDef;
|
|
const parsed: Record<string, unknown> = { _: ["one", "two", "three"] };
|
|
expect(() => resolveExtraPositionals(cmd, path as string, parsed)).not.toThrow();
|
|
});
|
|
|
|
it("rejects a leaf's extra positional, naming it and the usage line, before run()", async () => {
|
|
const run = vi.fn();
|
|
await expect(
|
|
runCommand(await wrap(leaf("render", run)), { rawArgs: ["./proj", "out.mp4"] }),
|
|
).rejects.toThrow(CliUsageError);
|
|
expect(run).not.toHaveBeenCalled();
|
|
expect(errorSpy.mock.calls.flat().join("\n")).toBe(
|
|
"Unexpected extra argument for hyperframes render: out.mp4\nUsage: hyperframes render [DIR] [OPTIONS]",
|
|
);
|
|
});
|
|
|
|
it.each(["--json", "--json=true", "--json=1"])(
|
|
"reports the rejection as JSON on stdout under %s",
|
|
async (flag) => {
|
|
await expect(
|
|
runCommand(await wrap(leaf("lint")), { rawArgs: ["a", "b", flag] }),
|
|
).rejects.toThrow(CliUsageError);
|
|
expect(JSON.parse(logSpy.mock.calls[0]![0] as string)).toEqual({
|
|
ok: false,
|
|
error: expect.objectContaining({
|
|
message:
|
|
"Unexpected extra argument for hyperframes lint: b\nUsage: hyperframes lint [DIR] [OPTIONS]",
|
|
}),
|
|
});
|
|
},
|
|
);
|
|
|
|
it("rejects instead of joining when the first word names a file", async () => {
|
|
const run = vi.fn();
|
|
const file = join(tempDir(), "script.txt");
|
|
writeFileSync(file, "hello");
|
|
await expect(
|
|
runCommand(await wrap(leaf("tts", run)), { rawArgs: [file, "extra"] }),
|
|
).rejects.toThrow(CliUsageError);
|
|
expect(errorSpy.mock.calls.flat().join("\n")).toContain("hyperframes tts: extra");
|
|
expect(run).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("still joins catalog words when the first one names a folder", async () => {
|
|
const run = vi.fn();
|
|
const folder = tempDir();
|
|
await runCommand(await wrap(leaf("catalog", run)), { rawArgs: [folder, "player"] });
|
|
expect(run.mock.calls[0]![0].args.dir).toBe(`${folder} player`);
|
|
});
|
|
|
|
it.each(["catalog", "tts"])(
|
|
"joins %s's trailing words into its last positional",
|
|
async (name) => {
|
|
const run = vi.fn();
|
|
await runCommand(await wrap(leaf(name, run)), { rawArgs: ["lower", "third", "--json"] });
|
|
expect(run.mock.calls[0]![0].args.dir).toBe("lower third");
|
|
},
|
|
);
|
|
|
|
it.each(["--json", "--json=1", "--json=true", "--json=false"])(
|
|
"rejects %s on a command that declares no json flag, before any other check",
|
|
async (flag) => {
|
|
const bare = {
|
|
meta: { name: "docs" },
|
|
args: { topic: { type: "positional" } },
|
|
run: vi.fn(),
|
|
};
|
|
await expect(
|
|
runCommand(await wrap(bare as CommandDef), { rawArgs: ["a", "b", flag] }),
|
|
).rejects.toMatchObject({ code: "json_unsupported", result: { exitCode: 2 } });
|
|
expect(bare.run).not.toHaveBeenCalled();
|
|
},
|
|
);
|
|
|
|
it("does not read a --json after -- as the flag", async () => {
|
|
const bare = { meta: { name: "docs" }, args: { topic: { type: "positional" } }, run: vi.fn() };
|
|
await expect(
|
|
runCommand(await wrap(bare as CommandDef), { rawArgs: ["a", "b", "--", "--json"] }),
|
|
).rejects.toThrow(CliUsageError);
|
|
expect(logSpy).not.toHaveBeenCalled();
|
|
expect(errorSpy.mock.calls.flat().join("\n")).toContain("hyperframes docs: b, --json");
|
|
});
|
|
|
|
it("runs a leaf given no more positionals than it declares", async () => {
|
|
const run = vi.fn();
|
|
await runCommand(await wrap(leaf("lint", run)), { rawArgs: ["a", "--json"] });
|
|
expect(run).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("names a nested subcommand by its full path", async () => {
|
|
const group = {
|
|
meta: { name: "cloud" },
|
|
subCommands: { get: leaf("get") },
|
|
run: vi.fn(),
|
|
} as CommandDef;
|
|
await expect(runCommand(await wrap(group), { rawArgs: ["get", "id1", "id2"] })).rejects.toThrow(
|
|
CliUsageError,
|
|
);
|
|
expect(errorSpy.mock.calls.flat().join("\n")).toContain(
|
|
"hyperframes cloud get: id2\nUsage: hyperframes cloud get [DIR]",
|
|
);
|
|
});
|
|
|
|
it("lets an opted-out command read extra positionals", async () => {
|
|
const run = vi.fn();
|
|
await runCommand(await wrap(leaf("compare", run)), { rawArgs: ["a", "b", "c"] });
|
|
expect(run).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("does not count the subcommand name against the group citty also runs", async () => {
|
|
const run = vi.fn();
|
|
const sub = vi.fn();
|
|
const group = { meta: { name: "auth" }, subCommands: { status: leaf("status", sub) }, run };
|
|
await runCommand(await wrap(group as CommandDef), { rawArgs: ["status", "--json"] });
|
|
expect(sub).toHaveBeenCalledOnce();
|
|
expect(run).toHaveBeenCalledOnce();
|
|
});
|
|
});
|
|
|
|
describe("reportCommandFailure", () => {
|
|
beforeEach(() => {
|
|
trackCommandFailure.mockReset();
|
|
});
|
|
|
|
it("forwards the command and error to trackCommandFailure", async () => {
|
|
const err = new Error("ENOENT /Users/me/project/index.html");
|
|
await reportCommandFailure("info", err);
|
|
expect(trackCommandFailure).toHaveBeenCalledWith("info", err);
|
|
});
|
|
|
|
it("never throws when the telemetry call throws", async () => {
|
|
trackCommandFailure.mockImplementationOnce(() => {
|
|
throw new Error("telemetry blew up");
|
|
});
|
|
await expect(reportCommandFailure("browser", new Error("x"))).resolves.toBeUndefined();
|
|
});
|
|
});
|