stacks-dns

# Stacks DNS Use the native declarative DNS planner for config reconciliation, and Route53 helpers for hosted-zone/delegation management. Previewing a plan and applying provider changes are separate operations. ## Declarative additive sync ~~~ts import { syncDnsConfig } from '@stacksjs/dns' import { dns, overridesReady } from '@stacksjs/config' await overridesReady const preview = await syncDnsConfig('example.com', dns, { dryRun: true }) console.log(preview.plan.create, preview.plan.keep, preview.plan.skip) ~~~ desiredDnsRecords(domain, config) converts native config to provider records. planDnsSync(desired, current, { zone? }) returns create/keep/skip with reasons. syncDnsConfig(domain, config, { dryRun?, provider? }) reports created/kept/failed, failures/skipped/applied/provider. It only creates missing declared records; it never deletes or overwrites an existing value. Single-value A/AAAA/CNAME records are kept when present; TXT/MX can add distinct values. Editing config does not imply changing an already-present provider value. dryRun reads public DNS without provider credentials; that is not a complete zone export. Actual apply selects a ts-cloud DNS provider by domain/nameservers and credentials. A missing provider yields an unapplied plan, not fake success. The native sync interface supports Route53/Porkbun/GoDaddy/Cloudflare through the provider factory; retained request/planner tests are not live provider parity. ## Native config record shapes config/dns.ts uses a/aaaa records with address, cname with target, txt with content, and mx with mailServer/priority. Each has name and optional ttl. The older generic value field is not this contract. nameservers describe delegation and are not included in desired zone records. Names @/empty mean the apex; names already in the zone or ending in a dot are absolute. A/AAAA address @ copies an apex address declared in the same config; without one it is skipped with a reason. CNAME target @ names the apex. Private/loopback/placeholder addresses and out-of-zone records are skipped; TTL normalization applies the planner's current minimum. Resolve conflicts deliberately rather than interpreting keep as identical desired content. resolveLiveRecords(domain) reads public DNS. renderDnsConfig(domain, records) renders source for review; dnsProviderForDomain(domain) resolves the mutable provider. Use buddy dns:* --help for pull/sync command flags and output paths. ## Route53 zone and registrar helpers The public entry also exports createHostedZone, findHostedZone, deleteHostedZone/deleteHostedZoneRecords, getNameservers/getHostedZoneNameservers, updateNameservers, writeNameserversToConfig and addDomain. Their source is drivers/aws.ts; most zone operations return Result and require inspecting isOk. Registrar nameservers and hosted-zone delegation are different state. Deleting a zone or publishing delegation requires the task's authorization. writeNameserversToConfig changes config/dns.ts. addDomain delegates to the native application action. Normalization, idempotent zone lookup and provider API errors are defined by their implementations; use real results instead of assuming await means a record was published. ## Boundaries and evidence `@stacksjs/dns` does not currently re-export dnsx: the dependency's missing runtime entry was intentionally removed from the public graph. Use an installed working resolver package or native DNS where appropriate, not an import promised only by ambient declarations. Deploy mail DNS reconciliation has its own owned record policy in buddy, distinct from this strictly additive planner. Source: `storage/framework/core/dns/src/index.ts`, sync.ts, drivers/aws.ts, config/dns.ts and core/types/src/dns.ts. Evidence: core/dns/tests/sync.test.ts and dns.test.ts. No live DNS mutations are needed to review the planner.