Skip to content

C-186: feat(cli): the runner uploads a render for a share; demoflow share and the MCP share_demo tool - #408

Merged
AndreyBegma merged 10 commits into
developfrom
card/c186-feat-cli-the-runner-uploads-a-render-for
Oct 27, 2026
Merged

AndreyBegma merged 10 commits into
developfrom
card/c186-feat-cli-the-runner-uploads-a-render-for

Conversation

@AndreyBegma

@AndreyBegma AndreyBegma commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

Closes #349. Spec: docs/specs/349-cli-share.md.

What changed and why

The API (#347, #348) can create share links; this slice gives it something to share, through the runner, the CLI and the MCP server.

  • packages/core: optional chapters ({ title, atMs }, at most MAX_CHAPTERS) on RenderOutput, so a share can show a chapter list. An optional share: { allowMcp } block on the project config. project-config.schema.json is regenerated.
  • packages/renderer: planChapters(plan) turns the placed scene cards into chapters in output milliseconds, after idle trimming and cards. Each render in result.json now gets them; a run with no scenes gets [].
  • apps/cli: runner
    • launches.sync sends features: ['share'], but only when the relay is on.
    • share.prepare is routed to runner/share/prepare.ts. It finds the reported run and the render, and answers share.prepared with the scenario's description (read only inside the project root, cut to the API limit), the render's chapters and the poster's size. Otherwise it answers share.error (not-found, no-render, io).
    • runner/share/poster.ts takes one JPEG frame with FFmpeg at min(1500, durationMs / 2), at most 1280 px wide and at most 1 MiB. The poster is cached in <runDir>/share/ and reused while it is newer than the render; two shares of the same render at once make only one poster.
    • The relay serves video.open with asset: 'poster'. An unknown asset is not-found without opening a file.
    • scenarioDescription moved to commands/scenario-file.ts so the daemon can reuse it.
  • apps/cli: demoflow share <runId>
    • Options: --format, --expires 7|30|90 (default 30), --password, --json.
    • --password is typed twice without echo, or read from DEMOFLOW_SHARE_PASSWORD when there is no terminal. It is never a flag value.
    • Before posting, the command checks the format against result.json and the run against the reported-runs index. It then waits up to 10 minutes for the upload and prints the page link, plus the file link when there is no password.
    • A share-exists answer returns the existing link.
    • Exit codes: refusals exit 2 with their own code; a failed upload, or one still going after 10 minutes, exits 1; an unreachable server exits 3.
    • The shared flow is in share/publish.ts. locateRun was extracted from render.ts, and send / readJson / unexpected are now exported from auth/client.ts.
  • apps/cli: MCP share_demo
    • Same flow, never with a password.
    • Refused with share-not-allowed unless the reported run's project root sets share.allowMcp: true. It is also refused when there is no root or the config cannot be read.
    • It waits up to 50 s, which stays under the 60 s request timeout of MCP clients, and answers status: 'uploading' if the upload is not done; calling it again returns the same link.
    • Server refusals keep their codes and come with hints.
  • apps/cli/README.md: documents the command, the tool and share.allowMcp, and corrects "videos never leave the machine".

Acceptance criteria

  • A fresh run's result.json has chapters per render, one per scene card, in output ms; no scenes → []; an old result.json still parses. Checked by packages/renderer/test/plan/chapters.spec.ts and build.spec.ts, and by packages/core/test/run-result.spec.ts.
  • The daemon's first frame carries features: ['share']. Checked by apps/cli/test/runner/connection.spec.ts and daemon-launch.spec.ts.
  • share.prepare for a reported mp4 run answers the description, the chapters and the poster size; the poster is a JPEG ≤ 1280 px wide. Checked by apps/cli/test/runner/share.spec.ts with real FFmpeg on mp4 and gif.
  • An unreported run, a missing render file or an unrendered format answers not-found / no-render, and nothing outside the run is read. Checked by apps/cli/test/runner/share.spec.ts, which covers a file outside the run and a description outside the project.
  • video.open with asset: 'poster' streams exactly the poster file. Checked by apps/cli/test/runner/relay.spec.ts.
  • demoflow share against a fake API prints the link once the share is ready; each refusal exits 2 with its code; the password is only in the request body, and --password <value> is rejected as an extra argument. Checked by apps/cli/test/commands/share.spec.ts (29 tests).
  • share_demo answers share-not-allowed without share.allowMcp: true and creates the share with it. Checked by apps/cli/test/mcp/share.spec.ts and the tool list in server.spec.ts.
  • project-config.schema.json is regenerated and share.allowMcp is in it, with a description. Checked by packages/core/test/json-schema.spec.ts (the committed schema matches the generated one) and project-config.spec.ts; I did not open it in an editor.
  • Vitest under Node on macOS and Windows: not checked here. I ran it only on Linux; execution-plane.yml CI covers the other two. On Linux, run serially: after merging develop, core 537 passed, renderer 338 passed, apps/cli 1012 passed and 1 skipped (the macOS-only plutil test). bun run check and bun run build pass.

A render carries its scene cards as chapters in output ms (at most 100), and a project opts the MCP server into publishing share links with share.allowMcp, off by default (spec 349).
planChapters takes the plan's scene cards at their output start, after the idle map and every earlier card, so a chapter lands where the card is drawn. The FFmpeg renderer records them on every format it writes (spec 349, Decision 1).
The daemon announces features: ['share'] and answers share.prepare with the scenario's description, the render's chapters and the size of a poster it makes with FFmpeg (one JPEG frame, at most 1280 px wide, reused while newer than the render). The relay serves that poster for video.open with asset: 'poster'; an unknown asset is not-found. scenarioDescription moves to scenario-file.ts so the daemon reads descriptions the way demoflow render does.
The command resolves the run like demoflow render, finds its server id in the reported-runs index, posts /runner/shares with the device token and polls the share every second for up to ten minutes. Server refusals become exit-2 CommandErrors with their codes; an existing share is kept and printed; a failed upload exits 1. --password is asked for without echo on a terminal, else read from DEMOFLOW_SHARE_PASSWORD, and never taken as a flag value.
share_demo creates a share link for a reported run without a password, only when the run's project sets share.allowMcp: true. It waits up to 50 s for the upload and answers uploading when the runner is still at it.
@AndreyBegma
AndreyBegma marked this pull request as ready for review October 27, 2026 11:03
@AndreyBegma
AndreyBegma merged commit cffa0f5 into develop Oct 27, 2026
11 of 12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(cli): the runner uploads a render for a share; demoflow share and the MCP share_demo tool

1 participant