test(cli): shared CLI contract schema-golden test (v0.19 Workstream 8)

[devarismeroxa]

Summary

Implements the schema-golden test for v0.19 Workstream 8
(v019-plans/workstreams/cli-contract.md) — the harmonization guarantee for
every other v0.19 workstream's --json surface.

Corrected premise, verified in the repo (not "one schema," per the plan's
own §4 finding): there are two distinct, both-deliberate --json families
in production today:

• Family A — envelope (cecdysis.CommandWithResult): 15 commands
  (13 pre-existing + init + pipelines init, both migrated onto the
  envelope in this PR — previously zero --json support on either).
  Validated against one committed schema,
  cmd/conduit/cecdysis/testdata/envelope.schema.json.
• Family B — client-result passthrough
  (cecdysis.CommandWithExecuteWithClientResult): 13 commands, raw
  protojson/go-json, intentionally never wrapped in the envelope (confirmed
  correct, load-bearing behavior, not a migration backlog item). Asserted to
  never accidentally match the envelope schema.
• 1 named exception: quickstart --json means "log format," not the
  envelope — documented, not silently ignored, not silently fixed.

What's implemented

1. Completeness walk (cmd/conduit/cli/schema_golden_test.go): recursively
   walks (&root.RootCommand{}).SubCommands() and classifies every leaf.
   Fails the build if a command registers --json but implements neither
   family and isn't a named exception. Verified this predicate actually
   fires (temporarily un-exempted quickstart, confirmed the test failed
   with the expected message, restored it).
2. Shared schema-validation harness
   (cmd/conduit/internal/testutils/envelope.go): ValidateEnvelope/
   MatchesEnvelope, test-only (never linked into the conduit binary —
   testutils has zero non-test importers, verified). Promotes
   github.com/santhosh-tekuri/jsonschema/v6 from an already-present
   indirect dependency to direct — no new dependency, just wiring one that
   was already in go.sum.
3. conduit init / conduit pipelines init migrated onto Family A
   (previously zero --json support on either), human-mode text preserved
   byte-for-byte.
4. Every one of the 26 pre-existing Family A/B commands gets an
   envelope-conformance (or negative) assertion added to its own existing
   test file — no production behavior changed, per AC-3. New lint/dry-run
   fixtures added where no test file existed before.
5. Doc addendum: docs/design-documents/20260707-cli-output-conventions.md
   §6 documents the two-family split and the quickstart exception.

Risk tier

Tier 2 (CLI/test infrastructure, per the plan's own assessment — no
data-path invariant touched).

Adversarial self-review

• Verified the completeness walk's failure predicate actually fires (not
  just that it passes) by temporarily removing the quickstart exception
  entry and confirming the expected failure message, then restoring it.
• Verified make generate produces zero drift beyond this diff's own
  files (git status --short after make generate shows only the files
  this PR intentionally touches).
• Verified testutils (home of the new schema validator) has zero
  non-test importers, so jsonschema/v6 does not enter the shipped
  conduit binary despite being promoted to a direct module dependency.
• connectors bundle and connector|processor new have no genuine
  end-to-end success-path test today (bundling/scaffolding need real
  artifacts/network+toolchain) — for these I added a schema-conformance
  check against the real result type with realistic synthetic data
  (mirroring the pre-existing TestResultMarshalsToTheDocumentedEnvelope
  precedent in scaffoldcmd), documented as such rather than silently
  passed off as a full E2E test.
• Checked error paths in the two migrated init commands: a HARD failure
  (unwritable directory, unknown connector) still returns a non-nil error
  from ExecuteWithResult, correctly routed through the existing
  conduiterr → ResultError mapping — no new error-shape code needed.
• No serialized-state, protocol, or config-schema changes; this is CLI
  output/test surface only.

Test plan

• go build ./...
• golangci-lint run ./cmd/conduit/... — 0 issues
• go test -race ./cmd/conduit/... — all green
• make generate && git status --short — zero unexpected drift
• markdownlint-cli2 (both local and CI-pinned 0.18.1) on the doc
  addendum — 0 errors
• Manually confirmed the completeness walk's failure predicate fires

Roadmap: v0.19 Workstream 8.

🤖 Generated with Claude Code

https://claude.ai/code/session_015GQFzakPShAYj8CcwajYDD