domains list has no machine-readable output, so the gem cannot report hold state

[mhenrixon]

Problem

kamal-proxy domains list prints a Cobra table. The data behind it — DomainsStatusResponse, including per-domain Quarantine entries with until, failures and kind — is already structured on the RPC, but the only way out of the binary is the rendered table.

That blocks the gem. dash doctor wants to tell an operator mid-DNS-cutover "certificate issuance held until 14:32 (preflight)", which was the original goal of zoolutions/dash#126. Getting there today means running docker exec kamal-proxy domains list over SSH and scraping columns out of human-readable output — brittle against any future column change, and a poor failure mode inside a read-only diagnostic. So dash#126 shipped a weaker message instead: for ACME-issued domains whose DNS does not yet point at the proxy, it says no certificate can be issued until it does and that the proxy handles it automatically. True and useful, but it cannot name the hold or when it lifts.

Suggested shape

A --json flag on domains list (and plausibly domains stats), emitting DomainsStatusResponse more or less as-is. There is precedent in this codebase: kamal-proxy list --json already exists (internal/cmd/list.go), and the gem already calls it that way via Dash::Commands::Loadbalancer#list(json: true).

Rough scope:

• internal/cmd/domains.go — add the flag to domainsListCommand, and marshal the response instead of building a table when it is set. Follow whatever list --json does so the two behave alike.
• Keep the table the default. The gem opts in; humans keep what they have.
• Worth confirming the JSON tags on DomainsStatusResponse, DomainStatus, RegisteredDomainStatus and QuarantineStatus read well as a public surface, since making them machine-readable makes them a contract.

Follow-on in the gem

Once this ships and MINIMUM_VERSION names it, dash doctor can read real hold state — replacing the generic message added in dash#126 with the specific one, and degrading to the generic form against an older proxy.

Not urgent. The automatic release means a hold usually clears itself before anyone looks, so this improves diagnosis rather than fixing a broken path.

[mhenrixon]

Problem / Goal

dash-proxy domains list and domains stats only render human tables. The gem's dash doctor (zoolutions/dash#126) wants to say "certificate issuance held until 14:32 (preflight)" but cannot read hold state without scraping columns. Done means: domains list --json emits DomainsStatusResponse as JSON, domains stats --json emits the counters as JSON, the table remains the default, and the JSON surface has no zero-time warts.

Context (read these first)

• internal/cmd/list.go — the precedent. --json bool flag, json.MarshalIndent(response, "", " ") + fmt.Println in displayJSON, table otherwise. Copy this shape exactly.
• internal/cmd/list_test.go — the precedent's tests: flag exists with default false; marshaled shape checked via json.Unmarshal into map[string]any. Same two tests per command here.
• internal/cmd/domains.go — fetchDomainsStatus(fn) wraps the kamal-proxy.DomainsStatus RPC call and hands the response to a callback returning nothing; domainsListCommand.run and domainsStatsCommand.run both use it. The callback signature has to change to return error so the JSON path can propagate a marshal error.
• internal/server/commands.go:97-138 — DomainStatus, DomainsServiceStatus, QuarantineStatus, RegisteredDomainStatus, DomainsStatusResponse. JSON tags already exist and are the contract: services, queue_length, quarantine, certificates, registered; quarantine entries carry until, failures, kind (preflight | acme | rate_limited).
• internal/server/commands.go:129 — ExpiresAt time.Time \json:"expires_at,omitempty"`: omitemptynever applies to a struct, so an uncertified host today serializes"expires_at":"0001-01-01T00:00:00Z". DomainsServiceStatus.FetchedAt (:104) has the same problem before a source's first successful poll. go.modis Go 1.26 —omitzero` is available and is the fix.
• internal/server/dynamic_domains.go:372 — DynamicDomainManager.Status() builds the response: Services and Quarantine are always non-nil maps ({} when empty); Registered comes from SANCertManager.RegisteredDomains() (internal/server/san_cert_dynamic.go:189), also always a made map. No null maps reach the wire.
• internal/server/commands.go:284 — DomainsStatus RPC handler returns an error when dynamic domains are not enabled. That stays an error (non-zero exit, message on stderr) in JSON mode too; the gem degrades to its generic message on non-zero exit.
• Gem side: ../kamal/lib/dash/commands/proxy.rb:163 — domains(subcommand, *args) already passes through arbitrary args, so domains("list", "--json") works with no gem command change. The doctor consumer is a gem follow-up, not part of this issue.

Decision

Add --json to domains list and domains stats, following list.go byte-for-byte in style. domains list --json marshals server.DomainsStatusResponse verbatim — it is already the RPC payload, and inventing a second CLI-only shape would mean two contracts to keep aligned. domains stats --json marshals a new DomainsStatsSummary struct built in internal/cmd from the same counters the text output prints, so the numbers are computed once and both renderers read them. Fix the two omitempty-on-time.Time tags to omitzero so the JSON contract does not ship year-0001 timestamps.

Alternatives rejected:

• Server-side stats RPC (new DomainsStats verb returning the summary): the counters are a pure fold over DomainsStatusResponse, adding an RPC verb for a client-side aggregation is a cold-path abstraction with no benefit and one more kamal-proxy.* call site to maintain.
• Global --json on the domains parent command (persistent flag): refresh and retry print a single sentence; a JSON mode for them is invented scope. Per-subcommand flags match list.go and keep the surface honest.
• Pointer *time.Time for ExpiresAt/FetchedAt: works on older Go but changes the Go type every caller touches (san_cert_dynamic.go:200, dynamic_domains.go, tests). omitzero is a one-token tag change with identical wire output.

Settled in interview:

• --json goes on both domains list and domains stats.
• omitempty → omitzero on RegisteredDomainStatus.ExpiresAt and DomainsServiceStatus.FetchedAt.
• Table output stays the default; no change to the text renderers.
• The "dynamic domains are not enabled" RPC error remains an error in JSON mode — no {}-with-exit-0 fallback.

Implementation steps

1. Tag fix (server layer) — internal/server/commands.go

   • RegisteredDomainStatus.ExpiresAt: json:"expires_at,omitempty" → json:"expires_at,omitzero".
   • DomainsServiceStatus.FetchedAt: json:"fetched_at" → json:"fetched_at,omitzero".
   • Test first, in internal/server/commands_test.go (create if absent, otherwise append): TestDomainsStatusResponse_JSONOmitsZeroTimes — marshal a DomainsStatusResponse with an uncertified Registered entry and a DomainsServiceStatus with zero FetchedAt; assert expires_at and fetched_at keys are absent from the decoded map[string]any, and that a certified entry with a real ExpiresAt does emit expires_at.

2. Refactor the fetch helper — internal/cmd/domains.go

   • Change fetchDomainsStatus(fn func(response server.DomainsStatusResponse)) error to fn func(server.DomainsStatusResponse) error and return fn(response). Update both existing callers to return nil at the end of their table/text path.

3. domains list --json — internal/cmd/domains.go

   • Add json bool field to domainsListCommand; register Flags().BoolVar(&c.json, "json", false, "Output the domain list as JSON") in newDomainsListCommand.
   • In run: if c.json { return c.displayJSON(response) } before the table branch. Extract the current table body into displayTable(response) (keeps run small; domains.go is ~290 lines, fine to stay one file).
   • displayJSON = json.MarshalIndent(response, "", " ") + fmt.Println, identical to listCommand.displayJSON.
   • Tests first, new file internal/cmd/domains_test.go:
     • TestDomainsListCommand_JSONFlag — flag exists, DefValue == "false" (mirror TestListCommand_JSONFlag).
     • TestDomainsListCommand_JSONOutputShape — build a server.DomainsStatusResponse with one service (source, two domains, one held removal), one quarantine entry (Kind: "preflight", Failures: 2, fixed Until), one certified registered host and one uncertified; marshal; assert quarantine["app.example.com"]["kind"] == "preflight", ["failures"] == float64(2), ["until"] is the RFC3339 string, registered[...]["service"], services[...]["held_removals"], and that the uncertified registered entry lacks expires_at.

4. domains stats --json — internal/cmd/domains.go

   • Add DomainsStatsSummary struct in internal/cmd/domains.go (not server — it is a CLI presentation type, not an RPC payload):

     type DomainsStatsSummary struct {
         Services            int `json:"services"`
         DynamicDomains      int `json:"dynamic_domains"`
         DynamicCertified    int `json:"dynamic_certified"`
         RegisteredHosts     int `json:"registered_hosts"`
         RegisteredCertified int `json:"registered_certified"`
         Queued              int `json:"queued"`
         Quarantined         int `json:"quarantined"`
         HeldRemovals        int `json:"held_removals"`
         Certificates        int `json:"certificates"`
     }

   • Extract the existing counting loop into summarizeDomains(response server.DomainsStatusResponse) DomainsStatsSummary; the text path prints from the summary's fields (same labels and order as today), the JSON path MarshalIndents it.
   • Add json bool + flag on domainsStatsCommand ("Output the counters as JSON").
   • Tests first, in internal/cmd/domains_test.go:
     • TestDomainsStatsCommand_JSONFlag — as above.
     • TestSummarizeDomains — table-driven over 2–3 responses (empty; one service with mixed certified; registered + quarantine + held removals), assert every field of the summary.
     • TestDomainsStatsSummary_JSONKeys — marshal one summary and assert the nine snake_case keys are present.

5. Docs

   • ROADMAP.md R4 table: add a DONE row for domains list has no machine-readable output, so the gem cannot report hold state #121 naming domains list --json / domains stats --json and the omitzero fix, in the same voice as neighbouring rows.
   • No README change unless a domains section already exists (check grep -n "domains" README.md; if present, add one line per flag).

Verification gates

• make test — all green (go test ./...)
• gofmt -l internal/ cmd/ — empty output
• make lint — clean (golangci-lint is installed locally)
• make build — bin/dash-proxy builds clean
• Manual shape check: go run ./cmd/kamal-proxy domains list --json against a proxy started without --acme-email exits non-zero with the "dynamic domains are not enabled" message on stderr and nothing on stdout.

Out of scope

• No gem changes — the dash doctor consumer and MINIMUM_VERSION bump are a follow-up in ../kamal after this ships in a tagged image (release proxy first).
• No --json on domains refresh / domains retry.
• No new RPC verbs; no changes to DomainsStatus() in dynamic_domains.go beyond what the tag edit implies (nothing).
• No renaming of the field names already in the JSON tags — they are now a contract.
• No edits to Dockerfile / Makefile / script/release-dash; no renaming of the Go module path or the kamal-proxy RPC service name; no direct pushes to main.

Execution

Branch feature/domains-json rooted off main; PR against main. Suggested commits: fix(rpc): omit zero timestamps from domains status JSON, feat(cmd): domains list --json, feat(cmd): domains stats --json, docs: roadmap entry for #121.