terraform-provider-dynu/AGENTS.md

AGENTS.md

Goal

Build a Terraform provider for Dynu DNS and domains.

Scope for current phase

Read-only only. Implement provider configuration and data sources first. Do not implement any writable Terraform resources in the first phase.

Language and framework

• Language: Go
• Terraform provider framework: HashiCorp Terraform Plugin Framework
• Do not use the legacy SDK unless explicitly requested.

API usage

• Use Dynu's public API.
• Prefer stable, documented endpoints.
• Build a small internal API client package rather than scattering HTTP calls across resources/data sources.
• Add clear handling for pagination, 4xx/5xx responses, and malformed responses.
• Never log secrets.

Provider design

Implement:

• Provider configuration
• Environment variable support for credentials
• Read-only data sources:
  • dynu_domains
  • dynu_domain
  • dynu_dns_records

Do not implement:

• resource_dynu_dns_record
• any create/update/delete flows
• any speculative unsupported resources

Safety

• Read-only phase only.
• No write HTTP methods in this phase.
• Acceptance tests must only cover provider auth and read-only data sources.
• Any future write support must be added in a separate phase.

Code quality

• Keep code modular and idiomatic Go.
• Use strong typing for API models.
• Prefer explicit schema definitions with clear descriptions.
• Return actionable diagnostics.
• Keep public documentation accurate to actual implementation.

Testing

• Add unit tests where practical.
• Add acceptance tests gated behind environment variables.
• Do not require live credentials for normal unit tests.

Documentation

• Add examples for every implemented data source.
• Update README with provider configuration and environment variables.
• Document limitations and unsupported areas clearly.

Output expectations

Create a provider skeleton that can compile and expose the provider plus read-only data sources.

Codex environment

• Use codex/setup.sh to prepare the repository-local Codex environment.
• Use codex/maintain.sh to refresh and validate the environment.
• Use codex/doctor.sh for troubleshooting.
• Do not install global packages unless explicitly required.
• Prefer repo-local state under .codex/.
• Do not run docker compose up, down, or pull unless explicitly requested.
• Safe validation via ./services-up.sh --profile all config is allowed.