Issue: #5 · Phase 1 · Decisions: ADR-0001, ADR-0003, ADR-0004, ADR-0008
Depends on #3 Depends on #4
The Phase 1 deliverable is "a short technical prototype that produces a
credible demo video". This item makes it one command: demoflow run <scenario> validates the scenario, loads the project config, resolves where
artifacts go, runs the engine and the renderer(s), and prints where the video
is — for a person, or as JSON for an agent. It creates apps/cli, the package
later published as demoflow.
apps/cli, package namedemoflow,bin: { demoflow: dist/main.js }, ESM, Node ≥ 20, Vitest. Argument parsing withcommander(pinned).demoflow validate <scenario.demo.json>anddemoflow run <scenario.demo.json>.- Project root discovery,
demoflow.config.jsonloading, home and global config resolution (ADR-0004 §7) on Linux, macOS and Windows.
login,runner,mcp,project add(Phase 2–5), starting a dev server, npm publishing.
- Project root: the nearest ancestor of the scenario file containing
demoflow.config.json; none → exit 2no-project-config. The scenario id is its path relative to that root, with/separators on every OS. - Home resolution, first hit wins:
--out <dir>,DEMOFLOW_HOME,artifactsDirin the project config (relative to the project root),artifactsDirin the global config, the OS data directory. Global config:$XDG_CONFIG_HOME/demoflow/config.jsonor~/.config/demoflow/config.json;~/Library/Application Support/demoflow/config.json;%APPDATA%\demoflow\config.json. The run directory is<home>/runs/<runId>/. runoptions:--base-url <url>(overrides the config, still checked againstallowedOrigins),--out <dir>,--headed,--json. There is no--rendereroption: the FFmpeg compositor is the only renderer (ADR-0005, accepted 2026-10-17).- Output: by default a short human summary (stage statuses, video paths);
with
--json, exactly one JSON object on stdout — the finalresult.jsonplusrunDir— and nothing else on stdout; progress goes to stderr. - Exit codes:
0completed (with or without warnings),1verification or execution failed,2invalid input (schema, config, origin, missing env),3any other stage failed (recording, rendering, storage). - Environment for
valueFrom: the process environment only.
-
bun run --filter demoflow testpasses under Node;bun run checkandbun run buildpass at the root. - Home resolution has a table test per rule, per OS (paths built with the
platform's rules, the OS faked through an injected
platformand env). -
demoflow validate apps/fixture/demoflow/customers.demo.jsonexits 0; a copy with a{ role, testId }locator exits 2 and prints the step path. - With the fixture previewing on 3680,
demoflow run apps/fixture/demoflow/customers.demo.json --jsonexits 0, prints one parsable JSON object whosestatusiscompletedand whoserenderslists one existing MP4 file (render/ffmpeg.mp4), and writes nothing else to stdout. - The same for
failing.demo.jsonexits 1 withstatus: failed. -
login.demo.jsonwithoutFIXTURE_PASSWORDexits 2 before a browser starts. -
--base-url https://example.comexits 2 withorigin-not-allowed. -
apps/fixture/demoflow.config.jsonexists withbaseUrl http://localhost:3680.
| Slot | Owns | Touches | Depends on | Lead | Model |
|---|---|---|---|---|---|
| i5-config | the package, project root, config loading, home resolution | apps/cli/package.json, apps/cli/tsconfig.json, apps/cli/vitest.config.ts, apps/cli/src/config/, apps/cli/test/config/, apps/fixture/demoflow.config.json, bun.lock | — | yes | sonnet |
| i5-commands | main.ts, validate, run, output and exit codes |
apps/cli/src/main.ts, apps/cli/src/commands/, apps/cli/test/commands/ | i5-config | no | sonnet |
| Resource | Owner | Everyone else |
|---|---|---|
| apps/cli/package.json, bun.lock | i5-config | the lead adds commander for the commands slot |
- Windows paths in scenario ids (medium): normalised to
/; covered by a test and by #6.