Issue: #255 Depends on: nothing.
ADR-0004 keeps
recording apart from rendering so that "the same source must be renderable
again in another style without rerunning the scenario". Its Consequences say
"Rendering can be retried or restyled from runs/<runId>/ alone". Vision §12
asks the same: "allow rendering to be retried from existing source artifacts
without rerunning a successful browser scenario".
The pieces exist: buildRenderPlan(runDir, options) reads only the run
directory, and the renderer's recordRender replaces renders[] and the
rendering stage of result.json. No command calls them on an existing
run. Today a new background, a GIF after the fact, or a retry after a render
crash means running the scenario again, with the app, the browser and its
timing.
This slice adds demoflow render <runId>.
apps/cli/src/commands/render.ts(new):renderCommand.apps/cli/src/main.ts: therendercommand and its flags.apps/cli/src/config/project.tsandapps/cli/src/record/command.ts:projectRootAbovemoves from the second to the first (Decision 2).apps/cli/test/**: its tests (Vitest under Node).apps/cli/README.mdandapps/web/src/app/docs/cli/page.mdx: the command.
- An MCP tool for it. No source asks for one.
- Reporting the re-render to the website (Decision 7).
- Any change to
packages/**: the plan and the renderer are used as they are. - Deleting render files of formats the new render does not write (Decision 6).
- Re-rendering from the website: ADR-0008 §3 lists exactly what the website may make a Runner do, and this is not on it.
- Command.
demoflow render <runId> [--format <format>]... [--out <dir>] [--json], plus a hidden--project <dir>likerunandrecord.<runId>is the run directory's name, therunIdofresult.jsonand of the MCP answers. It passesassertSafeRunIdfirst.- Why a run id, not a path: runs live under the resolved home
(ADR-0004 §7). A path would let the command write
result.jsonin any directory; the id keeps it inside<home>/runs/.
- Project and home. The project root is found upwards from the current
directory, or is
projectRootAt(--project), exactly asdemoflow recordresolves it. Its privateprojectRootAbovemoves toapps/cli/src/config/project.ts, exported, and both commands use it. The config isloadProjectConfig(root). The home isresolveHomewith the same inputs asrunCommand(--out,DEMOFLOW_HOME, project config, global config, OS default). The run directory isrunDir(home, runId, platform)from../config(imported asrunDirForinrun.ts). - Style. The plan is built with the project's current
render.*: the same options objectrunCommandpasses tobuildRenderPlan, withformats: flags.format ?? config.render.formats.- Why: restyling is the reason ADR-0004 gives. A render that copied the old settings would only be a retry, and a retry with unchanged config is the same call.
- The intro card's subtitle is the scenario's
description. It is read from<root>/<result.scenarioId>when that file exists and loads; otherwise the card has no subtitle. The card's title isresult.scenarioName, which the plan already reads. An MCP inline scenario (deleted after its run) renders without a subtitle.
- Refusals. Each is a
CommandError, exit 2, before anything is written:invalid-run-id: the id failsassertSafeRunId;run-not-found: the run directory does not exist;invalid-result:result.jsonis missing or failsRunResultSchema;run-unfinished: any ofreadiness,execution,verification,recordingispendingorrunning;no-recording:recordingis notpassed, or the source video (RUN_FILES.video) is missing.- A
renderingstage leftrunningby a crashed render is not refused: retrying that render is the point of the command. - Why no lock: a second
renderof the same run at the same time is a person's own action on their own machine; the capture stages check stops the case that matters, a run still in progress.
- Verdict. Only
renders[]and therenderingstage change, throughffmpegRenderer.render(runDir, plan)(which callsrecordRender); thensettleRun(runDir)derives the status again. Readiness, execution, verification and recording are never touched, so a failed run staysfailedand keeps its failure card and watermark (ADR-0004 §3–4). - Old files.
recordRenderreplaces every earlierrenders[]entry of theffmpegrenderer. A file of a format this render does not write stays on disk but is no longer listed, so nothing claims it (vision §7); playback through the relay looks formats up inrenders[]and answersnot-foundfor it.- Why not delete it: deleting files is the riskier choice and no source asks for it; a later render that asks for the format writes it again.
- No website report.
demoflow renderdoes not callPOST /runner/runs.- Why: that endpoint inserts a run (spec 178, Decision 3), so a report
would duplicate the run in the library. Updating a reported run needs a
new endpoint no source asks for. The library row keeps the formats of
the original run; the run page's playback reads
renders[]on the machine and shows what exists.
- Why: that endpoint inserts a run (spec 178, Decision 3), so a report
would duplicate the run in the library. Updating a reported run needs a
new endpoint no source asks for. The library row keeps the formats of
the original run; the run page's playback reads
- Output and exit code. Like
demoflow run:Renderingon stderr, thenformatSummaryor, with--json,formatJsonon stdout, andexitCodeFor(result). A render error is printed asrendering failed: <reason>and the exit code is 3 even if the derived status would give 0 (the same guard asrunCommand). - Testability.
renderCommand(runId, flags, io, deps)takesRenderDeps { host, cwd, buildPlan, renderer }, defaulting tobuildRenderPlanandffmpegRenderer, so tests use fakes and need no FFmpeg. - Docs.
apps/cli/README.mdand/docs/cligain ademoflow rendersection: what it does, the flags, that the verdict never changes, that the website is not told (Decision 7).
Vitest under Node, a temporary home with a fixture run directory
(result.json, timeline.json, an empty source video file), fake
buildPlan and renderer:
- A finished run is re-rendered:
buildPlanreceives the run directory and the current config's options;--format gifreplaces the formats; the fake renderer is called once; stdout has the summary (or one JSON object with--json); exit code followsexitCodeFor. - A failed run (verification
failed, recordingpassed) is re-rendered and keeps statusfailed; its other stages are byte-equal before and after. - Each refusal of Decision 4 exits 2 with its code and leaves
result.jsonunchanged; a run withrendering: runningis accepted. - A renderer that rejects gives exit 3 and
rendering failed:on stderr. - The scenario's
descriptionreaches the plan when the file exists, and is absent when it does not. - No HTTP request is made (no report).
-
demoflow render --helplists the flags; README and/docs/clidescribe the command. -
bun run check,bun run test,bun run buildand the execution-plane OS matrix are green.
| Resource | Owner | Others |
|---|---|---|
apps/cli/src/commands/render.ts, apps/cli/test/** (new tests) |
#255 | No other open issue touches apps/cli. |
apps/cli/src/main.ts, apps/cli/src/config/project.ts, apps/cli/src/record/command.ts |
#255 | No other open issue. |
apps/web/src/app/docs/cli/page.mdx |
#254 (the --format row) |
#255 adds a new section; different lines. Whichever merges second rebases. |
None.