compat

Overview ¶

cmd/compat/embed.go — wires the embedded compat UI into the binary.

The UI is embedded in the compat package (compat/embed.go) which sits alongside compat/ui/dist/. This file simply aliases it for use in main.go.

cmd/compat/launch.go — everything the compat CLI needs to stand up its own environment: choosing ports that are safe to bind, starting a throwaway Overcast instance (native binary or container), waiting for it to become healthy, running the Vite dev server for the dashboard UI, and opening a browser. This is the cross-platform replacement for the logic that used to live in compat/run.sh and compat/dev.sh — those are now thin wrappers, so the behaviour is identical on Windows, macOS, and Linux.

Port policy: 4566 (API) and 4567 (web UI) belong to the developer's own Overcast instance — see AGENTS.md § Reserved ports. Nothing started from here may bind either, even when the scan base or an explicit flag would land on them. Every port is chosen by probing, so two compat sessions (or two agents) can run side by side.

cmd/compat/main.go — Overcast compatibility test CLI.

Runs one or more test suite subprocesses, collects their NDJSON output, and prints a summary report. When --serve is set a live compatibility dashboard is served too.

Unless an endpoint is pinned, compat starts and owns a throwaway Overcast instance on a free port — 4566/4567 are reserved for the developer's own instance (AGENTS.md § Reserved ports). See launch.go.

Usage:

go run ./cmd/compat --dev            # dashboard + hot-reloading UI + browser
go run ./cmd/compat --format agent   # headless run, agent-readable summary
go build -o bin/compat ./cmd/compat

Flags (the full list is in the var block below):

--dev             Dashboard + hot-reloading UI + browser, on free ports
--endpoint        Target an instance you already run (skips managing one)
--start-overcast  auto | always | never
--suite           Comma-separated suite names to run (default: all)
--format          Output format: pretty | json | agent | junit
--serve           Start the compatibility dashboard HTTP server
--port            Preferred dashboard port; a free one is picked if taken

cmd/compat/parity.go — cross-suite uniformity enforcement.

compat/suites/registry.json is the single source of truth for what every SDK/CLI suite should test. Nothing used to check that suites actually implement it: a suite could quietly emit "not yet implemented" forever, and a new registry test could land implemented in one suite only.

The parity checker closes that. It classifies every (suite, registry test) pair from a real run's results — the same data the dashboard shows — and compares the gaps against compat/parity-debt.json. Debt must be recorded, must match reality exactly, and only ever shrinks.

See compat/AGENTS.md § Baseline & uniformity policy.