docs(acme): derive the provider table and --acme-dns-provider help from the registry

[mhenrixon]

Summary

The supported-DNS-provider list was hand-maintained in three places — and the drift the issue predicted had already happened: the README credentials table was missing Cloudflare's CF_DNS_API_TOKEN alternative and misfiled gcloud's optional variables as required. The registry (registry.go, from the #77 refactor) is now the single source:

• internal/server/acme/providers/docs.go (new) — Names() (sorted), ProviderListForHelp() (registry + auto), ProviderTableMarkdown() (docs-linked display names, credentials rendered as the same OR-of-ANDs rule the boot check enforces via credentialSets(), optionals from the entry), and ReplaceProviderTable(), the marker-based block rewrite shared by the generator and the drift test.
• internal/server/acme/providers/gen/main.go (new) — go generate ./internal/server/acme/providers rewrites the README table in place between <!-- BEGIN/END GENERATED: dns-provider-table --> markers; it refuses to touch a document without markers.
• TestREADMEProviderTable_MatchesRegistry — the drift gate: a provider added to the registry without regeneration fails make test, naming the missing rows and the generate command. A generator with no drift check is a generator nobody reruns.
• internal/cmd/run.go — the --acme-dns-provider usage string is built from ProviderListForHelp(); TestRunCommand_DNSProviderHelpMatchesRegistry pins it. The README flag-table row no longer enumerates providers.

With this in place, the two provider batches (#73, #74) become registry-entry-only changes: help text, README table, and the drift gate all follow automatically.

Closes #75

Test plan

• TestREADMEProviderTable_MatchesRegistry fails (naming rows) when a registry entry is added without regenerating — verified during RED
• bin/kamal-proxy run -h shows the registry-derived list (cloudflare, digitalocean, gcloud, godaddy, hetzner, namecheap, route53, vultr, auto)
• Regenerated table is idempotent (ReplaceProviderTable twice = identical) and deterministic (sorted names)
• make test green (323 tests across touched packages, full suite green), -race clean on touched packages, make lint 0 issues, gofmt/go vet clean, make build clean

Deviations & judgment calls

• Inline help list, not a subcommand. The issue offered kamal-proxy acme providers as an alternative if --help bloats; at eight (soon twenty) comma-separated names, one usage line is still readable, and the subcommand can be added when it isn't. No RPC/CLI surface added.
• The flag-table row points at the generated table instead of getting its own generated block — removing the third copy entirely beats maintaining two generated regions.
• Credential rendering reuses credentialSets() rather than the flattened GetProviderInfo fields, so the table shows the true OR-of-ANDs rule (Cloudflare's three alternatives) — the exact fidelity the hand-written table lost. Providers with NoBootCheck (route53) still render their Required set: it is the documented happy path even though boot doesn't enforce it.
• Sort order is by provider name (the flag value operators type), not display name — AWS Route53 sorts under route53.

---

Summary by cubic

Derives the --acme-dns-provider help text and the README’s supported-provider table from the ACME provider registry to remove drift and fix incorrect docs. Old: hand-maintained lists with errors. New: registry is the single source; help and docs update automatically. Side effects: run go generate after registry changes; removed acme.GetSupportedProviders().

• README: replaces the manual list with a generated block between markers. The table leads with the flag value (name), links to lego docs, renders the exact OR-of-ANDs credential rule, shows optional vars from the registry, and is sorted by provider name. The --acme-dns-provider row now references this table instead of enumerating names.
• CLI: internal/cmd/run.go builds the help list via providers.ProviderListForHelp(). TestRunCommand_DNSProviderHelpMatchesRegistry pins the output to the registry.
• Generator/tests: go generate ./internal/server/acme/providers rewrites the README block; ReplaceProviderTable refuses to write without markers. TestREADMEProviderTable_MatchesRegistry fails with stale or missing rows named. Removed the dead acme.GetSupportedProviders() and its cross-check test.

Developer workflow

• When adding or updating a provider: edit the registry, run go generate ./internal/server/acme/providers, commit the README change.
• Do not edit the generated README block by hand; keep the BEGIN/END markers intact.

^{Written for commit 9323e30. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 6 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 6 files (changes from recent commits).

Confidence score: 5/5

• In internal/server/acme/providers/docs_test.go, the docs registry/README consistency check can report a misleading "stale or missing row" error when a provider is removed but all rendered lines still exist, which mainly risks slower triage rather than runtime behavior — update the gate/message logic to distinguish true stale rows from registry-removal mismatches.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/server/acme/providers/docs_test.go">

<violation number="1" location="internal/server/acme/providers/docs_test.go:84">
P3: When a provider is removed from the registry but its row remains in README, the equality gate fails while `stale` stays empty (every rendered line is still present in `data`), so the error prints "stale or missing rows:" with no rows and no clue which row is obsolete. The substring `Contains` check can also miss a genuinely removed row when a rendered line appears elsewhere in the document. Compare the committed table region (between the begin/end markers) against the rendered lines to also surface rows that exist in README but are no longer generated.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P3: When a provider is removed from the registry but its row remains in README, the equality gate fails while stale stays empty (every rendered line is still present in data), so the error prints "stale or missing rows:" with no rows and no clue which row is obsolete. The substring Contains check can also miss a genuinely removed row when a rendered line appears elsewhere in the document. Compare the committed table region (between the begin/end markers) against the rendered lines to also surface rows that exist in README but are no longer generated.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At internal/server/acme/providers/docs_test.go, line 84:

<comment>When a provider is removed from the registry but its row remains in README, the equality gate fails while `stale` stays empty (every rendered line is still present in `data`), so the error prints "stale or missing rows:" with no rows and no clue which row is obsolete. The substring `Contains` check can also miss a genuinely removed row when a rendered line appears elsewhere in the document. Compare the committed table region (between the begin/end markers) against the rendered lines to also surface rows that exist in README but are no longer generated.</comment>

<file context>
@@ -77,13 +77,18 @@ func TestREADMEProviderTable_MatchesRegistry(t *testing.T) {
+	// a brand-new provider AND a changed row (credentials, optional vars)
+	// both surface as an expected line the document does not contain.
+	stale := []string{}
+	for line := range strings.Lines(ProviderTableMarkdown()) {
+		line = strings.TrimSuffix(line, "\n")
+		if line != "" && !strings.Contains(string(data), line) {
</file context>