feat(cli): add conduit doctor preflight diagnostics

[devarismeroxa]

Summary

Implements conduit doctor per docs/design-documents/20260707-cli-doctor.md and the ADR docs/architecture-decision-records/20260707-check-engine-shared-by-doctor-and-scaffold.md. Both docs (plus the shared docs/design-documents/20260707-cli-output-conventions.md doctor must follow) are brought into this PR from docs/v0.17-first-wave-design, which isn't merged to main yet — doctor's implementation needs them in-tree to be reviewable against something.

doctor is an offline, non-destructive preflight answering "would conduit run succeed here?" — config resolution/validation, database reachability, API address availability, plugin directories, the built-in plugin registry, and (optionally) whether a running engine is reachable. It does not boot a Runtime.

What's here

• pkg/conduit/runtime.go: extracted OpenStore(cfg, logger) verbatim from NewRuntime's DB-open switch (behavior-preserving; NewRuntime now just calls it). This is the one edit to existing runtime code, kept surgical per the task note about a parallel PR touching nearby files.
• cmd/conduit/root/doctor/doctorcheck (new, pure — no cobra/ecdysis import, proven by an engine-only test that calls DefaultChecks + check.Run directly): the check set — config.resolve, config.validate (reuses Config.Validate()), store.reachable (reuses conduit.OpenStore), network.grpc/network.http (reuses check.AddrBindable), plugins.connectors_dir/plugins.processors_dir, plugins.builtin, engine.reachable (reuses api.Client), and plugins.standalone_compat behind --deep.
• cmd/conduit/root/doctor (new): DoctorCommand (the cobra wrapper + human renderer) and a hidden __plugin-spec-check worker command --deep re-execs itself as (see isolation note below). Registered in root.go.
• cmd/conduit/cecdysis: added CommandWithResultExitCode, a small additive interface + cli.go wiring (ExecuteC instead of Execute, reading a cobra Annotations value back off the leaf command). See "Structural gap found" below for why this was necessary.
• README.md: new "Preflight checks" section, plus a note in "Exit codes" about multi-result aggregation.

Review must-fixes (from the design doc's own review) applied

• Exit code aggregation goes entirely through pkg/conduit/check.Report.ExitCode() (already-merged, already-tested max-bucket logic) — not reimplemented.
• --deep's plugins.standalone_compat isolates each plugin's dispense+specify call in a subprocess (re-execs the running conduit binary as __plugin-spec-check <path>) with a 15s per-plugin timeout, because hashicorp/go-plugin spawns background goroutines in the calling process that a recover() cannot catch across a goroutine boundary. Any abnormal child exit (nonzero, timeout-killed, crashed) is treated as Fail for that plugin — verified manually against both a plugin binary that exits 1 and a garbage (non-executable-format) binary; doctor itself never crashes.
• engine.reachable is documented, not glossed over, as binary pass/fail — CheckHealth can't distinguish "no server" from "unhealthy."
• Flags: --json, --check <name> (repeatable; an unknown name, or a --deep-gated name passed without --deep, is a HARD failure listing valid names, exit 2), --deep, --require-server, -q/--quiet, --no-color.
• store.reachable has no side effects: it records whether the configured badger/sqlite path existed before opening the store, and removes only what it itself created afterward — pre-existing state (a real prior conduit run) is never touched. Covered by both a doctorcheck-level test and a CLI-level end-to-end test.

A structural gap I found and fixed (not anticipated by the design doc)

The already-merged cecdysis.CommandWithResultDecorator has exactly two paths: ExecuteWithResult returns an error (a HARD failure — sets the JSON envelope's error field, RunE returns that error) or it returns nil (renders normally, RunE returns nil). But per the CLI output conventions, a domain finding (Outcome.OK == false, e.g. doctor's checks failing) must return a nil error from ExecuteWithResult — the envelope's error must stay null. With the decorator as merged, that nil-error path meant cmd.Execute() always returned nil, so cli.Run's os.Exit(exitcode.ExitCode(err)) was always 0, regardless of how many checks failed. There was no way to satisfy "exit 2/3 on failing checks" and "envelope error stays null on a domain finding" simultaneously with the merged decorator.

Fix: added cecdysis.CommandWithResultExitCode (a small, optional, additive interface: ExitCode(Outcome) int). When implemented and ExecuteWithResult returns nil, the decorator records the exit code as a cobra.Command.Annotations entry on the leaf command (there's no other channel available post-hoc without changing RunE's return value, which would defeat the "envelope error stays null" requirement). cmd/conduit/cli.go now calls cmd.ExecuteC() (returns the leaf command) instead of cmd.Execute() and reads the annotation back if the top-level error was nil. This is additive and backward compatible — no existing CommandWithResult command implements the new interface, so nothing else changes behavior. Covered by new tests in cecdysis/exitcode_test.go and end-to-end in doctor_test.go.

This will matter again for the pipelines validate design doc, which has the identical "multi-result command, exit code must reflect findings, envelope error must stay null" shape.

Adversarial self-review

• config.resolve cannot observe "unparseable config file." By the time doctor's checks run, ecdysis's own config-parsing (ParseConfig, called from CommandWithConfig's PreRunE) has already resolved c.Cfg — a malformed YAML file fails there, as a HARD failure, before ExecuteWithResult (and therefore any check) ever runs. Documented on configResolveCheck's type doc rather than silently claimed as covered; the design doc's three-way "found+parsed / defaults-used / unparseable" split degrades to a two-way "found / not found" split for this reason.
• configResolveCheck's stat-error branch originally collapsed "genuinely missing" and "some other stat error" (permission denied, etc.) into the same "no config file" message — fixed during self-review to distinguish them (os.IsNotExist vs. a generic fallback), so a permissions problem doesn't get misreported as "file doesn't exist."
• Verified manually (not just unit tests): bad badger path → fail/exit 3, port-in-use → fail/exit 3 (confirmed with a real bound listener, not just a unit test), invalid log.level → fail/exit 2, missing plugin dirs → warn/exit 0, all-good → exit 0/ok:true, --json envelope shape, --check filtering (including the standalone_compat-without---deep guard), --deep against both a broken and a garbage plugin binary (no crash), and no conduit.db/badger directory left behind after any of the above runs.
• plugins.standalone_compat is connector-only. Standalone processors are WASM (wazero, in-process), not go-plugin subprocesses — a different risk profile than the one the review flagged (background-goroutine panics in the calling process). Scoped --deep to connectors only rather than inflating this PR into wazero-compile-validation territory; documented as a deliberate scope decision, not an oversight.
• No llms.txt or conduit.io docs-source update: neither exists in this repo (llms.txt isn't present anywhere; the conduit.io docs site is a separate repo not reachable from here). Added a "Preflight checks" section to README.md instead, and left a pointer to the design doc.

Test plan

• go build ./... — clean.
• go test ./cmd/conduit/... ./pkg/conduit/... -race -count=1 — all green, including:
  • cmd/conduit/root/doctor/doctorcheck — the pure, engine-only suite (bad badger path → fail/exit 3, port-in-use → fail/exit 3, missing plugin dir → warn/exit 0, invalid config field → fail/exit 2, all-good → exit 0, no DB dir left behind — both the "fresh path" and "pre-existing path is never deleted" cases, in-memory DB warns, API-disabled warns, --require-server fails, a panicking check.Check mixed into doctor's real check set is isolated as Fail without crashing the test binary, CheckNames() covers every name DefaultChecks can produce).
  • cmd/conduit/root/doctor — the cobra-level integration suite (same scenarios driven through the real ExecuteC() path, proving CommandWithResultExitCode end-to-end: JSON envelope error:null + exit 2 on a domain finding, unknown --check name as a HARD failure, --deep-gated name without --deep, --check filtering, --quiet suppressing pass but not warn lines, no DB dir left behind at the full-CLI layer).
  • cmd/conduit/cecdysis — new tests for CommandWithResultExitCode/ResultExitCode (annotation set on a domain failure, not set on success, not set for a zero code, nil/unset/corrupted-annotation handling).
• golangci-lint run ./cmd/conduit/... ./pkg/conduit/... — 0 issues.
• Manual smoke testing (see adversarial self-review above) against a real built binary.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Tapg9dLWXKMZJoL65R24vd