From 58b9ec0efffec78beb028e8866bd7150397585b8 Mon Sep 17 00:00:00 2001 From: Jerrai Date: Thu, 5 Nov 2026 02:19:38 +0000 Subject: [PATCH] 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. --- packages/cli/README.md | 9 ++ packages/cli/src/commands/batchRender.test.ts | 40 +++++++++ packages/cli/src/commands/batchRender.ts | 6 +- .../cli/src/commands/render/execute.test.ts | 83 ++++++++++++++++++- packages/cli/src/commands/render/execute.ts | 4 +- packages/cli/src/ui/renderResult.test.ts | 71 ++++++++++++++++ packages/cli/src/ui/renderResult.ts | 20 +++++ 7 files changed, 230 insertions(+), 3 deletions(-) create mode 100644 packages/cli/src/ui/renderResult.test.ts create mode 100644 packages/cli/src/ui/renderResult.ts diff --git a/packages/cli/README.md b/packages/cli/README.md index d3fe270e7c..36f0db6585 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -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. diff --git a/packages/cli/src/commands/batchRender.test.ts b/packages/cli/src/commands/batchRender.test.ts index 72978a5a10..716385f2f2 100644 --- a/packages/cli/src/commands/batchRender.test.ts +++ b/packages/cli/src/commands/batchRender.test.ts @@ -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"}]'), diff --git a/packages/cli/src/commands/batchRender.ts b/packages/cli/src/commands/batchRender.ts index 74beeb4313..b901f31111 100644 --- a/packages/cli/src/commands/batchRender.ts +++ b/packages/cli/src/commands/batchRender.ts @@ -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 { 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; diff --git a/packages/cli/src/commands/render/execute.test.ts b/packages/cli/src/commands/render/execute.test.ts index a845543e65..9b63a17c2c 100644 --- a/packages/cli/src/commands/render/execute.test.ts +++ b/packages/cli/src/commands/render/execute.test.ts @@ -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"), '
'); + 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 { + 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([ + { 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([]); + }); +}); diff --git a/packages/cli/src/commands/render/execute.ts b/packages/cli/src/commands/render/execute.ts index a50eca3811..63f4352384 100644 --- a/packages/cli/src/commands/render/execute.ts +++ b/packages/cli/src/commands/render/execute.ts @@ -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 { diff --git a/packages/cli/src/ui/renderResult.test.ts b/packages/cli/src/ui/renderResult.test.ts new file mode 100644 index 0000000000..ce3dbc16a5 --- /dev/null +++ b/packages/cli/src/ui/renderResult.test.ts @@ -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([ + { 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(""); + }); +}); diff --git a/packages/cli/src/ui/renderResult.ts b/packages/cli/src/ui/renderResult.ts new file mode 100644 index 0000000000..468344d934 --- /dev/null +++ b/packages/cli/src/ui/renderResult.ts @@ -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, + 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`); +}