feat(cli): print the render's reference_background as an @hf-result line and in batch manifest rows (#7203)

A piped, non-quiet local render now writes one versioned @hf-result JSON line
after success. Batch manifest rows carry the same reference_background value.
This commit is contained in:
Jerrai
2026-11-05 02:19:38 +00:00
committed by GitHub
parent 071ec1fddd
commit 58b9ec0eff
7 changed files with 230 additions and 3 deletions
+9
View File
@@ -99,6 +99,15 @@ interruption path. Probe failures retain their existing stage/reason but do not
gain subprocess evidence here; browser/FX failures remain classified as internal.
Desktop ingestion and live report delivery are separate changes.
Piped, non-quiet renders also emit a single `@hf-result ` JSON line after a local
render succeeds, never after a failure. Version 1 has `operation: "render"` and
`reference_background`, the background the render measured from the composition's
root and body: `{"kind":"solid","rgb":[r,g,b]}`, `{"kind":"none"}`,
`{"kind":"unsupported_non_solid"}` or `{"kind":"unknown"}`. Consumers must ignore
unknown versions and fields. A `--docker` render prints no result line from the
launcher. In batch mode each manifest row carries the same `reference_background` value (`null` until the row completes, and for a
row that failed).
### `publish`
Upload a project directory and get a hosted URL that keeps working after the CLI exits.
@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import type { ReferenceBackground } from "@hyperframes/producer";
import {
BatchRenderInputError,
parseBatchRows,
@@ -266,6 +267,45 @@ describe("runBatchRender", () => {
expect(readFileSync(prepared.manifestPath, "utf8")).toContain('"status": "completed"');
});
it("copies each row's reference background into the manifest and leaves a failed row null", async () => {
const references: ReferenceBackground[] = [
{ kind: "solid", rgb: [12, 34, 56] },
{ kind: "none" },
{ kind: "unsupported_non_solid" },
{ kind: "unknown" },
];
const prepared = prepareBatchRender({
batchPath: writeJson(
"rows.json",
JSON.stringify([...references.map((_, id) => ({ name: `row${id}` })), { name: "bad" }]),
),
outputTemplate: join(tmpDir, "renders/{name}.mp4"),
indexPath: writeIndex(),
strictVariables: false,
quiet: true,
json: false,
});
const manifest = await runBatchRender({
prepared,
concurrency: 1,
failFast: false,
quiet: true,
json: false,
renderOne: async (row) => {
const reference = references[row.index];
if (!reference) throw new Error("render failed");
return { renderTimeMs: 10, reference_background: reference };
},
});
expect(manifest.rows.map((row) => row.reference_background)).toEqual([...references, null]);
const written = JSON.parse(readFileSync(prepared.manifestPath, "utf8")) as {
rows: Array<{ reference_background: unknown }>;
};
expect(written.rows.map((row) => row.reference_background)).toEqual([...references, null]);
});
it("emits exactly one final JSON document when json mode is enabled", async () => {
const prepared = prepareBatchRender({
batchPath: writeJson("rows.json", '[{"name":"Alice"}]'),
+5 -1
View File
@@ -6,6 +6,7 @@ import { dirname, join, resolve, sep } from "node:path";
import { c } from "../ui/colors.js";
import { errorBox } from "../ui/format.js";
import { normalizeErrorMessage as errorMessage } from "../utils/errorMessage.js";
import type { ReferenceBackground, ReferenceBackgroundResult } from "@hyperframes/producer";
import {
loadProjectVariableSchema,
reportVariableIssues,
@@ -37,7 +38,7 @@ export interface PreparedBatchRender {
rows: PreparedBatchRow[];
}
interface BatchRenderResult {
interface BatchRenderResult extends Partial<ReferenceBackgroundResult> {
durationMs?: number;
renderTimeMs: number;
}
@@ -48,6 +49,7 @@ export interface BatchManifestRow {
status: "pending" | "running" | "completed" | "failed" | "skipped";
durationMs: number | null;
renderTimeMs: number | null;
reference_background: ReferenceBackground | null;
error: string | null;
startedAt: string | null;
completedAt: string | null;
@@ -304,6 +306,7 @@ function makeInitialManifest(prepared: PreparedBatchRender): BatchManifest {
status: "pending",
durationMs: null,
renderTimeMs: null,
reference_background: null,
error: null,
startedAt: null,
completedAt: null,
@@ -347,6 +350,7 @@ async function renderBatchRow(
manifestRow.status = "completed";
manifestRow.durationMs = result.durationMs ?? null;
manifestRow.renderTimeMs = result.renderTimeMs;
manifestRow.reference_background = result.reference_background ?? null;
manifestRow.completedAt = new Date().toISOString();
writeManifest(manifest);
return true;
@@ -2,11 +2,12 @@ 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 type { ReferenceBackground } from "@hyperframes/producer";
import { createRenderPlan } from "./plan.js";
import { batchRowRenderOptions, executeRenderPlan, renderOptionsFromPlan } from "./execute.js";
import * as manager from "../../browser/manager.js";
import * as system from "../../telemetry/system.js";
import { wantsDesktopHint } from "../render.js";
import { wantsDesktopHint, type SingleRenderResult } from "../render.js";
describe("renderOptionsFromPlan", () => {
let projectDir: string;
@@ -107,3 +108,83 @@ describe("a render on a nearly full disk", () => {
},
);
});
describe("the machine result line after a single render", () => {
let projectDir: string;
const originalIsTTY = process.stdout.isTTY;
beforeEach(() => {
projectDir = mkdtempSync(join(tmpdir(), "hf-render-result-"));
writeFileSync(join(projectDir, "index.html"), '<main data-composition-id="main"></main>');
vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(manager, "sweepKilledInstalls").mockResolvedValue();
vi.spyOn(system, "getFreeDiskMb").mockReturnValue(100_000);
vi.spyOn(manager, "ensureBrowser").mockResolvedValue({
executablePath: "/usr/bin/chrome",
source: "system",
});
});
afterEach(() => {
vi.restoreAllMocks();
Object.defineProperty(process.stdout, "isTTY", { value: originalIsTTY, configurable: true });
rmSync(projectDir, { recursive: true, force: true });
});
async function resultLines(
outcome: SingleRenderResult | Error,
args: { quiet?: boolean; docker?: boolean } = {},
): Promise<string[]> {
Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
let output = "";
vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
output += String(chunk);
return true;
});
const render = vi.fn(async () => {
if (outcome instanceof Error) throw outcome;
return outcome;
});
const plan = createRenderPlan({ dir: projectDir, ...args });
const dependencies = {
renderLocal: render,
renderDocker: render,
checkResolution: async () => undefined,
};
try {
await executeRenderPlan(plan, dependencies);
} catch {
// The failure path is asserted through the absence of a result line.
}
expect(render).toHaveBeenCalledTimes(1);
return output.split("\n").filter((line) => line.startsWith("@hf-result "));
}
it.each<ReferenceBackground>([
{ kind: "solid", rgb: [12, 34, 56] },
{ kind: "none" },
{ kind: "unsupported_non_solid" },
{ kind: "unknown" },
])("prints the render's reference background once: %j", async (reference) => {
const lines = await resultLines({ renderTimeMs: 5, reference_background: reference });
expect(lines).toHaveLength(1);
expect(JSON.parse((lines[0] ?? "").slice("@hf-result ".length))).toEqual({
version: 1,
operation: "render",
reference_background: reference,
});
});
it("prints nothing when the render fails", async () => {
expect(await resultLines(new Error("capture failed"))).toEqual([]);
});
it("prints nothing in quiet mode or when a Docker render reports no background", async () => {
const measured: SingleRenderResult = {
renderTimeMs: 5,
reference_background: { kind: "none" },
};
expect(await resultLines(measured, { quiet: true })).toEqual([]);
expect(await resultLines({ renderTimeMs: 5 }, { docker: true })).toEqual([]);
});
});
+3 -1
View File
@@ -21,6 +21,7 @@ import {
validateVariablesAgainstProject,
} from "../../utils/variables.js";
import { trackRenderPreflightRejected } from "../../telemetry/events.js";
import { renderMachineResult } from "../../ui/renderResult.js";
import { applyRenderEnvironment, renderOutputDirectory, type RenderPlan } from "./plan.js";
import type { RenderOptions, SingleRenderResult } from "../render.js";
import type { RenderCancellationScope } from "../../utils/renderCancellation.js";
@@ -145,7 +146,8 @@ async function executeHeldRender(
reportSingleRenderNotes(plan, variables);
const options = renderOptionsFromPlan(plan, browserPath, variables);
const execute = plan.useDocker ? dependencies.renderDocker : dependencies.renderLocal;
await execute(plan.project.dir, plan.outputPath, options, cancellation);
const result = await execute(plan.project.dir, plan.outputPath, options, cancellation);
renderMachineResult(result, plan.effectiveQuiet);
}
function reportSingleRenderNotes(plan: RenderPlan, variables: RenderOptions["variables"]): void {
+71
View File
@@ -0,0 +1,71 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import type { ReferenceBackground } from "@hyperframes/producer";
import { renderMachineResult } from "./renderResult.js";
const originalIsTTY = process.stdout.isTTY;
afterEach(() => {
vi.restoreAllMocks();
vi.unstubAllEnvs();
Object.defineProperty(process.stdout, "isTTY", { value: originalIsTTY, configurable: true });
});
function capture(run: () => void, terminal = false): string {
Object.defineProperty(process.stdout, "isTTY", { value: terminal, configurable: true });
let output = "";
vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
output += String(chunk);
return true;
});
run();
return output;
}
function parse(line: string): unknown {
return JSON.parse(line.slice("@hf-result ".length));
}
describe("renderMachineResult", () => {
it.each<ReferenceBackground>([
{ kind: "solid", rgb: [12, 34, 56] },
{ kind: "none" },
{ kind: "unsupported_non_solid" },
{ kind: "unknown" },
])("writes one versioned line carrying reference background %j", (reference) => {
const line = capture(() => renderMachineResult({ reference_background: reference }, false));
expect(line.endsWith("\n")).toBe(true);
expect(line.trim().split("\n")).toHaveLength(1);
expect(line.startsWith("@hf-result ")).toBe(true);
expect(parse(line)).toEqual({
version: 1,
operation: "render",
reference_background: reference,
});
});
it("re-projects a malformed value to unknown at the final writer", () => {
const line = capture(() =>
renderMachineResult(
{ reference_background: { kind: "solid", rgb: [999, 0, 0], path: "/private/x" } } as never,
false,
),
);
expect(parse(line)).toEqual({
version: 1,
operation: "render",
reference_background: { kind: "unknown" },
});
expect(line).not.toContain("/private/x");
});
it("stays silent when the render measured nothing", () => {
expect(capture(() => renderMachineResult({}, false))).toBe("");
});
it("stays silent for quiet mode, a terminal, or a container attached to a terminal", () => {
const result = { reference_background: { kind: "none" } } as const;
expect(capture(() => renderMachineResult(result, true))).toBe("");
expect(capture(() => renderMachineResult(result, false), true)).toBe("");
vi.stubEnv("HYPERFRAMES_STDOUT_IS_TTY", "1");
expect(capture(() => renderMachineResult(result, false))).toBe("");
});
});
+20
View File
@@ -0,0 +1,20 @@
import {
REFERENCE_BACKGROUND_FIELD,
referenceBackgroundResult,
type ReferenceBackgroundResult,
} from "@hyperframes/producer";
/** Versioned, content-free success line for a piped CLI: the background the render measured, never a path or a word of the composition. */
export function renderMachineResult(
result: Partial<ReferenceBackgroundResult>,
quiet: boolean,
): void {
if (quiet || process.stdout.isTTY || process.env.HYPERFRAMES_STDOUT_IS_TTY === "1") return;
if (!(REFERENCE_BACKGROUND_FIELD in result)) return;
const line = {
version: 1,
operation: "render",
...referenceBackgroundResult(result[REFERENCE_BACKGROUND_FIELD]),
};
process.stdout.write(`@hf-result ${JSON.stringify(line)}\n`);
}