Skip to content

Commit 8411956

Browse files
fix(cli): long projects check to completion: boxed resumable copies, --prepare-media, idle deadline (#6104)
* fix(cli): check copies hostile videos at the composition size, not the source size * fix(cli): the check server serves the copy the page names with hf-proxy-box * feat(cli): check --prepare-media makes the video copies alone, and a stopped copy resumes A long source is copied in one-minute pieces that stay in the cache, so a copy that is killed or runs out of time continues from its finished pieces. check --prepare-media runs only that step: no browser, no report, a per-file result as JSON, and exit 1 when a copy failed. * fix(studio-server): keep finished copy pieces while their copy runs The short limit for dead partial copies would delete the first pieces of a long copy that is still encoding. Finished pieces now follow their own one-hour limit and are never swept while their copy is in flight. * refactor(studio-server): shorten two comments The comment gate limits a comment line to 120 characters and a run to four lines. * refactor(studio-server): drop comments the names already carry The comment ratchet lets a file's comment share only go down. * fix(cli): the check server pre-warms the copy the page asks for, not the source-size one The server started a source-size copy of every hostile video next to Chrome on each check, because its pre-warm passed no box while the page and the up-front copy use the composition's box. The pre-warm now takes the same box, found by the one helper the up-front copy uses. * fix(cli): end a check on no progress, not on a 120 s wall clock The check ended 120 s after Chrome was ready no matter what it was doing, so a long project whose sampling and overlap pass each kept working still failed (the overlap pass was one page call that reported nothing for its whole run). The deadline is now an idle clock: every phase entered, every sample finished, every overlap batch of eight times and every operation that settles restarts it, and the check ends only after 120 s with none. The overlap grid is asked for in batches so it can report between them. * refactor(cli): shorten the idle deadline comment The comment gate allows 120 characters on a comment line. * test(cli): check's overlap grid runs in page tasks of at most 8 samples * fix(cli): check test types for the cli lib, studio-server size budget for resumable copies
1 parent 2b8282f commit 8411956

20 files changed

Lines changed: 882 additions & 113 deletions

‎docs/packages/cli.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1047,6 +1047,13 @@ cover every finding from the full check.
10471047
| `--layout` | Layout knobs, currently `proseCoverageFloor=0.05` (0–1, default 0.15) |
10481048
| `--browser-gpu` / `--no-browser-gpu` | Hardware GPU capture, or deterministic SwiftShader (default: auto-detect) |
10491049
| `--proxy` / `--no-proxy` | Auto-transcode browser-hostile codecs before checking (default: on) |
1050+
| `--prepare-media` | Only make the browser-playable video copies, then exit: no browser, no report. `--json` lists each file as `ready`, `cached` or `failed`; exit 1 if any failed |
1051+
1052+
A video Chrome cannot decode (HEVC, ProRes) is copied once, and the first check waits
1053+
for it. A source longer than a few minutes is copied in one-minute pieces that are kept,
1054+
so a copy that is stopped continues from its finished pieces on the next run. For a long
1055+
project, run `hyperframes check --prepare-media` first, then the check itself finds every
1056+
copy ready.
10501057

10511058
`--caption-zone` and `--frame-check` refuse a ranged check when none of their
10521059
configured seek samples falls inside `--range`; a requested gate never silently

‎packages/cli/src/commands/check.test.ts‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -369,13 +369,77 @@ describe("contrast sample selection", () => {
369369
});
370370
});
371371

372+
describe("check --prepare-media", () => {
373+
async function runPrepare(
374+
files: Array<{ file: string; state: "ready" | "cached" | "failed"; reason?: string }>,
375+
rawArgs: string[],
376+
) {
377+
const { report } = await runScenario(fakeDriver());
378+
const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
379+
const prepareMedia = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => files);
380+
const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
381+
await runCommand(
382+
createCheckCommand({
383+
resolveProject: () => PROJECT,
384+
runPipeline,
385+
prepareMedia,
386+
withMeta: (value) => value,
387+
}),
388+
{ rawArgs },
389+
);
390+
return { runPipeline, prepareMedia, log };
391+
}
392+
393+
it("makes the copies without running the check, and reports every file", async () => {
394+
const files = [
395+
{ file: "a.mov", state: "ready" as const },
396+
{ file: "b.mov", state: "cached" as const },
397+
];
398+
const { runPipeline, prepareMedia, log } = await runPrepare(files, [
399+
"--prepare-media",
400+
"--json",
401+
"--no-proxy",
402+
]);
403+
404+
expect(runPipeline).not.toHaveBeenCalled();
405+
expect(prepareMedia).toHaveBeenCalledWith(
406+
PROJECT,
407+
expect.objectContaining({ autoProxy: false }),
408+
);
409+
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toEqual({
410+
ok: true,
411+
prepared: files,
412+
total: 2,
413+
ready: 2,
414+
failed: 0,
415+
});
416+
expect(consumeCommandResult().exitCode).toBe(0);
417+
});
418+
419+
it("exits 1 and names the reason when a copy failed", async () => {
420+
const { log } = await runPrepare(
421+
[{ file: "a.mov", state: "failed", reason: "ffmpeg exited with code 1" }],
422+
["--prepare-media", "--json"],
423+
);
424+
425+
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({
426+
ok: false,
427+
ready: 0,
428+
failed: 1,
429+
prepared: [{ file: "a.mov", state: "failed", reason: "ffmpeg exited with code 1" }],
430+
});
431+
expect(consumeCommandResult().exitCode).toBe(1);
432+
});
433+
});
434+
372435
it("parses the caption-zone grammar and enables the frame gate", async () => {
373436
const { report } = await runScenario(fakeDriver());
374437
const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
375438
vi.spyOn(console, "log").mockImplementation(() => undefined);
376439
const command = createCheckCommand({
377440
resolveProject: () => PROJECT,
378441
runPipeline,
442+
prepareMedia: vi.fn(async () => []),
379443
withMeta: (value) => value,
380444
});
381445

@@ -411,6 +475,7 @@ it("preserves caption-zone after bare --frame-check", async () => {
411475
const command = createCheckCommand({
412476
resolveProject: () => PROJECT,
413477
runPipeline,
478+
prepareMedia: vi.fn(async () => []),
414479
withMeta: (value) => value,
415480
});
416481

@@ -446,6 +511,7 @@ it("preserves --json after bare --frame-check", async () => {
446511
const command = createCheckCommand({
447512
resolveProject: () => PROJECT,
448513
runPipeline,
514+
prepareMedia: vi.fn(async () => []),
449515
withMeta: (value) => value,
450516
});
451517

@@ -472,6 +538,7 @@ it("prints a dash-prefixed --frame-check value's parse failure exactly once, not
472538
const command = createCheckCommand({
473539
resolveProject: () => PROJECT,
474540
runPipeline,
541+
prepareMedia: vi.fn(async () => []),
475542
withMeta: (value) => value,
476543
});
477544

@@ -491,6 +558,7 @@ it("no longer swallows --json after a --layout value (the wider bug class beyond
491558
const command = createCheckCommand({
492559
resolveProject: () => PROJECT,
493560
runPipeline,
561+
prepareMedia: vi.fn(async () => []),
494562
withMeta: (value) => value,
495563
});
496564

@@ -517,6 +585,7 @@ it("includes local HDR auto-promotion attribution in --json output", async () =>
517585
const command = createCheckCommand({
518586
resolveProject: () => PROJECT,
519587
runPipeline: vi.fn(async () => report),
588+
prepareMedia: vi.fn(async () => []),
520589
withMeta: (value) => value,
521590
});
522591

@@ -548,6 +617,7 @@ it("threads --no-proxy into the browser check options", async () => {
548617
const command = createCheckCommand({
549618
resolveProject: () => PROJECT,
550619
runPipeline,
620+
prepareMedia: vi.fn(async () => []),
551621
withMeta: (value) => value,
552622
});
553623

@@ -571,6 +641,7 @@ it("waits for the project lock declared in HF_TOOL_CONTEXT before running the pi
571641
const command = createCheckCommand({
572642
resolveProject: () => ({ ...PROJECT, dir }),
573643
runPipeline,
644+
prepareMedia: vi.fn(async () => []),
574645
withMeta: (value) => value,
575646
});
576647
try {
@@ -591,6 +662,7 @@ it("rejects malformed caption-zone specs instead of silently disabling the gate"
591662
const command = createCheckCommand({
592663
resolveProject: () => PROJECT,
593664
runPipeline,
665+
prepareMedia: vi.fn(async () => []),
594666
withMeta: (value) => ({ ...value, _meta: { version: "test" } }),
595667
});
596668

@@ -1164,6 +1236,7 @@ describe("check pipeline", () => {
11641236
const command = createCheckCommand({
11651237
resolveProject: () => PROJECT,
11661238
runPipeline: vi.fn(async () => report),
1239+
prepareMedia: vi.fn(async () => []),
11671240
withMeta: (value) => ({ ...value, _meta: { version: "test" } }),
11681241
});
11691242

@@ -1631,6 +1704,56 @@ describe("check pipeline", () => {
16311704
);
16321705
});
16331706

1707+
it("slow samples that each finish keep the check alive past 120 s", async () => {
1708+
vi.useFakeTimers();
1709+
try {
1710+
const collectLayout = vi.fn(async (_time: number, _tolerance: number) => {
1711+
await new Promise((resolve) => setTimeout(resolve, 30_000));
1712+
return [];
1713+
});
1714+
const driver = fakeDriver({ collectLayout });
1715+
const { deps } = dependencies(driver);
1716+
deps.runBrowserCheck = async (_project, options, motion, deadline) => {
1717+
deadline!.start();
1718+
return runAuditGrid(driver, options, motion, undefined, deadline!.enter);
1719+
};
1720+
const pending = runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps);
1721+
await vi.advanceTimersByTimeAsync(2_000_000);
1722+
const report = await pending;
1723+
expect(report.runtime.findings.map((finding) => finding.code)).not.toContain(
1724+
"check_runtime_failure",
1725+
);
1726+
expect(collectLayout.mock.calls.length * 30).toBeGreaterThan(120);
1727+
} finally {
1728+
vi.useRealTimers();
1729+
}
1730+
});
1731+
1732+
it("a long overlap pass that keeps reporting progress finishes instead of hitting a wall clock", async () => {
1733+
vi.useFakeTimers();
1734+
try {
1735+
const collectOverlapGrid = vi.fn(async (times: number[]) => {
1736+
await new Promise((resolve) => setTimeout(resolve, 10_000 * times.length));
1737+
return times.map((): AnchoredLayoutIssue[] => []);
1738+
});
1739+
const driver = fakeDriver({ collectOverlapGrid });
1740+
const { deps } = dependencies(driver);
1741+
deps.runBrowserCheck = async (_project, options, motion, deadline) => {
1742+
deadline!.start();
1743+
return runAuditGrid(driver, options, motion, undefined, deadline!.enter);
1744+
};
1745+
const pending = runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps);
1746+
await vi.advanceTimersByTimeAsync(2_000_000);
1747+
const report = await pending;
1748+
expect(report.runtime.findings.map((finding) => finding.code)).not.toContain(
1749+
"check_runtime_failure",
1750+
);
1751+
expect(collectOverlapGrid.mock.calls.length).toBeGreaterThan(1);
1752+
} finally {
1753+
vi.useRealTimers();
1754+
}
1755+
});
1756+
16341757
it("a deadline that fires in the overlap pass names that pass in its finding", async () => {
16351758
vi.useFakeTimers();
16361759
try {
@@ -2320,6 +2443,7 @@ describe("layout flag grammar", () => {
23202443
const command = createCheckCommand({
23212444
resolveProject: () => PROJECT,
23222445
runPipeline,
2446+
prepareMedia: vi.fn(async () => []),
23232447
withMeta: (value) => value,
23242448
});
23252449

@@ -2474,6 +2598,7 @@ describe("sampled finding reporting", () => {
24742598
const command = createCheckCommand({
24752599
resolveProject: () => PROJECT,
24762600
runPipeline: vi.fn(async () => report),
2601+
prepareMedia: vi.fn(async () => []),
24772602
withMeta: (value) => value,
24782603
});
24792604
const log = vi.spyOn(console, "log").mockImplementation(() => undefined);

‎packages/cli/src/commands/check.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,14 @@ import {
3636
} from "../utils/checkPipeline.js";
3737
import type { CaptionZoneOptions, FrameCheckOptions, LayoutOptions } from "../utils/checkTypes.js";
3838
import { resolveLocalBrowserGpuMode } from "../browser/gpuPolicy.js";
39+
import { preResolveHostileMediaProxies, type PreparedMediaFile } from "../utils/checkBrowser.js";
3940

4041
export const examples: Example[] = [
4142
["Run the full verification gate", "hyperframes check"],
4243
["Output one agent-readable envelope", "hyperframes check --json"],
4344
["Persist the five audited contrast frames", "hyperframes check --snapshots"],
4445
["Also fail on warnings", "hyperframes check --strict"],
46+
["Make only the browser-playable video copies, then exit", "hyperframes check --prepare-media"],
4547
];
4648

4749
type SavedCheck = Pick<ArtifactRecord, "id" | "revision" | "report" | "attribution">;
@@ -50,6 +52,7 @@ type SavedCheckReport = CheckReport & { saved?: SavedCheck };
5052
export interface CheckCommandDependencies {
5153
resolveProject(dir: string | undefined): ProjectDir;
5254
runPipeline(project: ProjectDir, options: CheckOptions): Promise<SavedCheckReport>;
55+
prepareMedia(project: ProjectDir, options: CheckOptions): Promise<PreparedMediaFile[]>;
5356
withMeta(value: object): object;
5457
}
5558

@@ -70,6 +73,11 @@ const DEFAULT_COMMAND_DEPENDENCIES: CheckCommandDependencies = {
7073
return report;
7174
}
7275
},
76+
async prepareMedia(project, options) {
77+
const { bundleWithLocalizedFonts } = await import("../utils/bundleWithLocalizedFonts.js");
78+
const html = await bundleWithLocalizedFonts(project.dir);
79+
return (await preResolveHostileMediaProxies(project.dir, html, options.autoProxy)).files;
80+
},
7381
withMeta,
7482
};
7583

@@ -211,6 +219,12 @@ const CHECK_COMMAND_ARGS = {
211219
description: "Exit non-zero on warnings too",
212220
default: false,
213221
},
222+
"prepare-media": {
223+
type: "boolean",
224+
description:
225+
"Only make the browser-playable copies of videos Chrome cannot decode, then exit (no browser, no report). Stopped copies resume on the next run",
226+
default: false,
227+
},
214228
proxy: {
215229
type: "boolean",
216230
description:
@@ -264,6 +278,10 @@ export function createCheckCommand(
264278
if (!asJson) {
265279
console.log(`${c.accent("◆")} Checking ${c.accent(project.name)}`);
266280
}
281+
if (args["prepare-media"] === true) {
282+
await runPrepareMedia(dependencies, project, options, asJson);
283+
return;
284+
}
267285
const report = await withProjectLock(project.dir, "check", () =>
268286
dependencies.runPipeline(project, options),
269287
);
@@ -294,6 +312,40 @@ export function createCheckCommand(
294312
});
295313
}
296314

315+
async function runPrepareMedia(
316+
dependencies: CheckCommandDependencies,
317+
project: ProjectDir,
318+
options: CheckOptions,
319+
asJson: boolean,
320+
): Promise<void> {
321+
const files = await withProjectLock(project.dir, "check", () =>
322+
dependencies.prepareMedia(project, options),
323+
);
324+
const failed = files.filter((file) => file.state === "failed");
325+
if (asJson) {
326+
console.log(
327+
JSON.stringify(
328+
dependencies.withMeta({
329+
ok: failed.length === 0,
330+
prepared: files,
331+
total: files.length,
332+
ready: files.length - failed.length,
333+
failed: failed.length,
334+
}),
335+
null,
336+
2,
337+
),
338+
);
339+
} else {
340+
const mark = failed.length === 0 ? c.success("✓") : c.error("✗");
341+
console.log(
342+
`${mark} Browser-playable copies: ${files.length - failed.length}/${files.length} ready`,
343+
);
344+
for (const file of failed) console.log(` ${file.file}: ${file.reason}`);
345+
}
346+
setCommandExitCode(failed.length === 0 ? 0 : 1);
347+
}
348+
297349
function parseCheckOptions(args: Record<string, unknown>): CheckOptions {
298350
const maxTransitionSamples = positiveInteger(args["max-transition-samples"], 0);
299351
return {

0 commit comments

Comments
 (0)