refactor: generate docs/schemas from typed contracts instead of hand-writing them

[DLANSAMA]

Step 3 of 4. Stacked on #100 (which is stacked on #99) — this PR targets refactor/printables-adapter, so its diff shows only the schema work.

Why

The 25 files in docs/schemas/ were hand-maintained. Nothing stopped them drifting from what the commands actually emit, and two of them had already drifted in ways nobody could see.

Now they are generated from frozen dataclasses, and CI regenerates and diffs them. Drift is a build failure.

bambu_cli/contracts/base.py	Contract base + spec() field constraints
bambu_cli/contracts/models.py	25 published contracts + 8 nested structures
scripts/gen_schemas.py	The generator; --check is the blocking CI gate

Fidelity was proven, not assumed

I did not overwrite the hand-written schemas and hope. The generator was diffed against them until it produced zero losses — every constraint the old files expressed is reproduced: minLength, minimum, nested required, field descriptions, and the entire status.printer shape including AMS.

LOSSES: 0   ADDITIONS: 78

All 78 additions are strictly more precise — type alongside const, item types on arrays, explicit nullability.

Two real defects it surfaced

1. download.json required 7 fields, but a naive model demoted 4 to optional (dataclass ordering forces defaults last). The loss diff caught it; fixed with spec(required=True).
2. error_envelope typed next_command as {} — "anything" — which hid that job/send emits it as null. The generated schema is explicit, and the contract test failed until the model admitted it.

Neither was visible while the schemas were hand-written.

Pydantic is dev-only

This is the part worth checking. Pydantic derives JSON Schema from the dataclass annotations at build time and is never imported at runtime:

• A test subprocess-imports the package and asserts pydantic is absent from sys.modules.
• uv.lock shows runtime deps unchanged at 3 (paho-mqtt, rich, zeroconf), with pydantic under the test extra behind python_full_version >= '3.10'.

Serialization stays in emit_json, because that pass applies the credential redaction a model_dump_json() would bypass. emit_json/emit_json_line now accept a contract or a plain dict.

The 3.9 floor

Contracts annotate optionals as X | None, which only evaluates on 3.10+. Nothing at runtime resolves them — dataclasses keeps annotations as strings — so the floor is unaffected. Both halves are asserted by tests, and the generator refuses to run below 3.10 with an explanatory message rather than failing obscurely. Verified against a real CPython 3.9.25.

Scope: what is wired

version, light, pause, resume, stop construct contracts today. The remaining commands still emit dicts — and every one of them is validated against its generated schema by tests/contracts/, so the published contract holds either way. Converting the rest (especially job's incrementally-built summary dict) is follow-up work rather than something to rush into this diff.

Gates

1214 passed, 1 deselected     (was 1177 on #100)
coverage 87.0%               (was 86.5%)
ruff / ruff format / mypy / bandit / layers / drift-check         green
syntax / help / workflow / compat / package-contents smokes       green

Docs: test counts and coverage refreshed to measured values rather than left stale.

Rebase note for whoever lands this

docs/schemas/tui.json lives on feat/tui, not main. When #97 merges, the drift gate will correctly fail with "no contract generates: tui.json" until a Tui contract is added to models.py — it is the same shape as Go (interactive command, --json always errors). Deliberate: the gate fails in both directions.