feat: plug-and-play v0.5.0 — Proposals 1 + 2 (Pydantic config, builder, Protocol, testing plugin)

[cipher813]

Summary

Lands Proposals 1 + 2 from private/plug-and-play-260513.md — typed, IDE-discoverable configuration AND the Protocol + testing-plugin surface that unblocks morning-signal's cutover.

Proposal 1 — Pydantic v2 config + builder

• flow_doctor/core/config.py — all 11 @dataclass config models → Pydantic v2 BaseModel via a shared _ConfigModel base. Field names + defaults preserved → drop-in for existing test fixtures and 0.4.0 callers. Adds pydantic>=2.0 to runtime deps.
• flow_doctor/notify/configs.py — SlackNotifierConfig | EmailNotifierConfig | GitHubNotifierConfig | S3NotifierConfig as a Pydantic discriminated union (Field(discriminator="type")). EmailNotifierConfig.recipients accepts a CSV string or a list and normalizes via a field_validator.
• flow_doctor/core/builder.py — FlowDoctorBuilder with fluent add_notifier / with_repo / with_dedup / with_store / with_diagnosis / with_github / with_auto_fix / with_remediation / with_handler / with_dependencies methods + build_config() and build(strict=True).
• FlowDoctor.builder(flow_name) classmethod is the recommended new entry point; flow_doctor.init(config_path=...) still works unchanged.

Proposal 2 — Protocol + contextvars + async + testing plugin

• flow_doctor/_protocol.py — @runtime_checkable FlowDoctorProtocol declaring report() / guard() / monitor() / report_async() as the cross-version public contract. Consumers type-hint against the Protocol; mypy/isinstance verifies swap-ins.
• flow_doctor/core/_context.py — per-task/-thread contextvars for flow_name + stage + extras, exposed via flow_doctor.context(). Inner scopes shadow outer; the active snapshot merges into every report's context at _build_context() time. Deep call-stacks no longer thread context=... explicitly.
• FlowDoctor.report_async() — async coroutine running the existing sync pipeline via asyncio.to_thread(). Contextvars inherit across the thread boundary automatically.
• flow_doctor/testing/_recording.py — RecordingFlowDoctor implementing FlowDoctorProtocol + ReportedIncident dataclass with .clear() / .last / .of_type(exc_name) ergonomic helpers.
• flow_doctor/testing/_plugin.py — flow_doctor_recorder pytest fixture, auto-discovered via [project.entry-points.pytest11]. Downstreams pip install flow-doctor and the fixture is available in any test file with no imports.

Morning-signal cutover example (from the plan)

from flow_doctor import FlowDoctor
from flow_doctor.notify import EmailNotifierConfig

fd = (
    FlowDoctor.builder("morning-signal")
    .add_notifier(EmailNotifierConfig(
        sender="x@y.com",
        recipients=["x@y.com"],
        smtp_password=os.environ["GMAIL_APP_PASSWORD"],
    ))
    .with_dedup(cooldown_minutes=60)
    .build()
)

Downstream consumer test (no imports required):

def test_pipeline_reports_db_errors(flow_doctor_recorder):
    run_pipeline_that_should_fail(flow_doctor_recorder)
    assert len(flow_doctor_recorder.reports) == 1
    assert flow_doctor_recorder.last.exc_type == "DBError"

Back-compat

• flow_doctor.init(config_path=...) — unchanged. Alpha-engine, the 0.4.0 consumer, doesn't move.
• NotifyChannelConfig — kept as the internal lingua franca that _init_notifiers consumes; typed configs convert via .to_channel_config().
• load_config() — accepts already-constructed Pydantic instances in addition to dicts (so the builder hands typed sub-configs straight down without re-serializing).

Not in this PR (planned follow-ups)

• BaseSettings env-var injection (pydantic-settings dep) — deferred so the dep trade-off can be decided separately.
• PEP 702 @deprecated markers on init() + NotifyChannelConfig — Proposal 3.
• py.typed marker + OTel mapping doc — Proposal 3.
• Cut v0.5.0 to PyPI + cut over morning-signal — once Proposal 3 lands.

Test plan

• pytest tests/ → 335/335 pass (296 baseline + 39 new across builder, Protocol/context, testing-plugin).
• New tests cover: discriminated-union deserialization (TypeAdapter, ValidationError), list→CSV recipients normalization, Protocol runtime satisfaction for FlowDoctor and arbitrary stubs, contextvars nested-scope shadowing + post-exit reset, contextvar inheritance into report_async's worker thread, RecordingFlowDoctor ergonomics, pytest11 entry-point wiring.
• Manual cutover smoke test on morning-signal — defer until Proposal 3 ships.

🤖 Generated with Claude Code