Problem
A working setup needs, beyond npm packages: Docker, Overmind, GNU parallel (all listed as prerequisites in packages/shaka-perf/SETUP-twin-servers.md), a Playwright-usable browser, and optionally ffmpeg (client-report load videos are "silently omitted otherwise") and the claude CLI (AI narrative/caption/a11y passes). Plus a C++ toolchain at install time for the native addon, and Node >= 20.6 (engines).
Nothing checks any of this up front. Users and agents discover missing dependencies by crashing mid-run — often deep into a twin-servers build, the most expensive possible place to learn "Overmind isn't installed."
Why it matters
For a coding agent, doctor --json is the natural first command in any repo: one call answers "can I run this here, and if not, what exactly do I install?" It also collapses a whole class of support requests and makes CI images verifiable in seconds.
Direction
shaka-perf doctor [--json]:
- Checks: node version, native addon loadable, playwright browser present, docker daemon reachable, overmind on PATH, parallel on PATH, ffmpeg (optional, note what degrades), claude CLI (optional, note what degrades), config file found/parses, ports pair assignable.
- Human output: ✓/✗ with the exact install command per miss (brew/apt variants).
--json: { ok, checks: [{ name, ok, required, version?, remediation }] } with exit 0/1 — so agents and CI can gate on it.
- Reference it as step 0 in the setup skill and README quickstarts.
Problem
A working setup needs, beyond npm packages: Docker, Overmind, GNU parallel (all listed as prerequisites in
packages/shaka-perf/SETUP-twin-servers.md), a Playwright-usable browser, and optionally ffmpeg (client-report load videos are "silently omitted otherwise") and theclaudeCLI (AI narrative/caption/a11y passes). Plus a C++ toolchain at install time for the native addon, and Node >= 20.6 (engines).Nothing checks any of this up front. Users and agents discover missing dependencies by crashing mid-run — often deep into a twin-servers build, the most expensive possible place to learn "Overmind isn't installed."
Why it matters
For a coding agent,
doctor --jsonis the natural first command in any repo: one call answers "can I run this here, and if not, what exactly do I install?" It also collapses a whole class of support requests and makes CI images verifiable in seconds.Direction
shaka-perf doctor [--json]:--json:{ ok, checks: [{ name, ok, required, version?, remediation }] }with exit 0/1 — so agents and CI can gate on it.