Skip to content

Add shaka-perf doctor [--json] — preflight for the five host dependencies #74

Description

@justin808

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions