doomain 0.1.21 → 0.1.22

package/README.md

@@ -13,6 +13,8 @@ Use the interactive wizard when working by hand. Use explicit commands with `--j
 - Vercel project detection from `.vercel/project.json`.
 - DNS provider inference by longest matching configured zone.
 - Generic DNS pointing for VPS, load balancer, and canonical-hostname targets.
+- Exact-match DNS removal with dry-run and post-delete verification.
+- DNS diagnosis across provider, system/VPN, Cloudflare, and Google views.
 - Dry-run plans before writing changes.
 - Safety checks before replacing DNS records that point elsewhere.
 - DNS propagation and Vercel verification wait loop.
@@ -257,10 +259,38 @@ doomain dns point app.example.com --target 203.0.113.10 --dry-run --json
 
 The preview resolves the provider, account, zone, record name, type, and value without reading or writing current DNS records. Conflicts are checked when a real write is attempted.
 
-By default, a successful write waits up to 300 seconds for public DNS. Use `--no-wait` to return immediately or `--timeout <seconds>` to change the limit. Skipping the wait, a dry run, or reaching the timeout returns `propagated: false`; a propagation timeout does not turn a successful provider write into an error.
+Every real write is re-read from the provider. Success is returned only when `reconciled: true` and the non-TXT slot contains only the desired record. If an eventually consistent provider does not reach that postcondition, the command fails with `DNS_RECONCILIATION_INCOMPLETE` and includes the observed records; do not treat accepted API requests as a completed cutover.
+
+By default, a successful write waits up to 300 seconds and compares the system resolver with Cloudflare and Google public DNS. Use `--no-wait` to skip resolver verification or `--timeout <seconds>` to change the limit. The JSON `propagation` object includes each resolver's answers, TTLs, expected target, elapsed time, status, and timeout reason. Node's resolver API does not expose CNAME TTLs, so those answers use `ttl: null` with `ttlUnavailableReason` instead of silently omitting the field.
+
+- `propagated`: public and system DNS match.
+- `local_or_vpn_cache_stale`: public DNS matches but the system/VPN resolver still serves cached data. The mutation is deployed, and `propagated` is `true`.
+- `system_resolver_unavailable`: public DNS matches, but the system resolver query failed. Public propagation is complete, and the resolver error is preserved for diagnosis.
+- `public_propagation_pending`: public DNS did not match before the timeout. The reconciled provider mutation succeeded, but `propagated` is `false`; this remains an exit-code-0 partial verification result.
+- `not_checked`: resolver verification was skipped or this was a dry run.
 
 Existing exact records are skipped. Conflicting records fail with `DNS_TARGET_CONFLICT` in JSON/non-interactive mode. Use `--force` only after approving replacement of the existing target.
 
+## Removing And Diagnosing DNS Records
+
+Removal defaults to an exact name/type/value match and verifies the record is absent after deletion:
+
+```bash
+doomain dns remove app.example.com --type A --value 203.0.113.10 --dry-run --json
+doomain dns remove app.example.com --type A --value 203.0.113.10 --json
+```
+
+`dns delete` is an alias. If more than one record matches, non-interactive mode fails with `DNS_DELETE_AMBIGUOUS`. Pass `--all-matching` only after reviewing the dry-run plan; interactive mode asks before deleting multiple records.
+
+Use the read-only diagnosis command to compare provider control-plane records with system/VPN and public DNS answers:
+
+```bash
+doomain dns diagnose example.com --json
+doomain dns diagnose app.example.com --type A --target 203.0.113.10 --json
+```
+
+Diagnosis reports record conflicts, answer TTLs, resolver addresses, active interface names, scoped macOS resolver/interface metadata when available, and one of `provider_not_updated`, `public_propagation_pending`, `local_or_vpn_cache_stale`, `system_resolver_unavailable`, or `consistent`.
+
 ## Clerk Production Domains
 
 `doomain clerk domains add` mirrors Clerk CLI's initial production deployment API. It creates a production instance by cloning the application's development instance, sets the requested primary domain, writes every CNAME returned by Clerk, and optionally waits for Clerk's DNS, SSL, and email DNS status.
@@ -476,6 +506,33 @@ Common flags:
 - `--timeout <seconds>`: propagation wait timeout. Default is `300`.
 - `--json`: output one JSON object.
 
+### `doomain dns remove <domain>`
+
+Removes exact DNS records and verifies their absence. `dns delete` is an alias.
+
+```bash
+doomain dns remove app.example.com --type A --value 203.0.113.10 --dry-run --json
+doomain dns remove app.example.com --type A --value 203.0.113.10 --json
+```
+
+Common flags:
+
+- `--type <A|AAAA|CNAME|MX|TXT>`: required record type.
+- `--value <value>`: expected exact value; required unless `--all-matching` is used.
+- `--all-matching`: explicitly select every record matching the name and type.
+- `--provider <id>`, `--account <alias>`: select a configured provider account.
+- `--dry-run`: list selected records without deleting them.
+- `--json`: output one JSON object and never prompt.
+
+### `doomain dns diagnose <domain>`
+
+Compares DNS provider records with the system resolver and independent public resolvers.
+
+```bash
+doomain dns diagnose example.com --json
+doomain dns diagnose app.example.com --type A --target 203.0.113.10 --json
+```
+
 ### `doomain auth logout vercel`
 
 Removes saved Vercel credentials from the local config file.

package/bin/dev.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
 
-import { execute } from '@oclif/core'
+import { removeStaleDevelopmentManifest } from './ensure-current-manifest.js'
 
+await removeStaleDevelopmentManifest(import.meta.url)
+const { execute } = await import('@oclif/core')
 await execute({ development: true, dir: import.meta.url })

package/bin/ensure-current-manifest.js

@@ -0,0 +1,18 @@
+import { readFile, unlink } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export async function removeStaleDevelopmentManifest(binUrl) {
+  const root = dirname(dirname(fileURLToPath(binUrl)))
+  const packagePath = join(root, 'package.json')
+  const manifestPath = join(root, 'oclif.manifest.json')
+  try {
+    const [packageJson, manifest] = await Promise.all([
+      readFile(packagePath, 'utf8').then(JSON.parse),
+      readFile(manifestPath, 'utf8').then(JSON.parse),
+    ])
+    if (packageJson.version !== manifest.version) await unlink(manifestPath)
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+}

package/bin/run.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 
-import { execute } from '@oclif/core'
+import { removeStaleDevelopmentManifest } from './ensure-current-manifest.js'
+
+await removeStaleDevelopmentManifest(import.meta.url)
+const { execute } = await import('@oclif/core')
 
 const args = process.argv.slice(2)
 const routedArgs = args.length === 0 || (args.length === 1 && args[0] === '--json') ? ['wizard', ...args] : args

package/dist/commands/dns/delete.d.ts

@@ -0,0 +1 @@
+export { default } from './remove.js';

package/dist/commands/dns/delete.js

@@ -0,0 +1 @@
+export { default } from './remove.js';

package/dist/commands/dns/diagnose.d.ts

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+export default class DnsDiagnose extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        domain: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        account: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        provider: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        target: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        type: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/dns/diagnose.js

@@ -0,0 +1,49 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { diagnoseDns } from '../../lib/diagnose-dns.js';
+import { accountFlag, jsonFlag, providerFlag } from '../../lib/flags.js';
+import { createOutput, outputError } from '../../lib/output.js';
+export default class DnsDiagnose extends Command {
+    static description = 'Compare DNS provider records with system and public resolver answers.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> example.com --json',
+        '<%= config.bin %> <%= command.id %> app.example.com --type A --target 203.0.113.10 --json',
+    ];
+    static args = {
+        domain: Args.string({ description: 'Fully qualified DNS name to diagnose.', required: true }),
+    };
+    static flags = {
+        account: accountFlag,
+        json: jsonFlag,
+        provider: providerFlag,
+        target: Flags.string({ description: 'Expected IP address or canonical hostname.' }),
+        type: Flags.string({ description: 'Record type to compare.', options: ['A', 'AAAA', 'CNAME'] }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(DnsDiagnose);
+        const out = createOutput({ json: flags.json });
+        const spinner = out.json ? undefined : out.spinner();
+        try {
+            spinner?.start(`Diagnosing ${args.domain}`);
+            const result = await diagnoseDns({
+                account: flags.account,
+                domain: args.domain,
+                provider: flags.provider,
+                recordType: flags.type,
+                target: flags.target,
+            });
+            spinner?.stop('DNS diagnosis complete');
+            out.result(result);
+            out.info(`Provider: ${result.provider}/${result.account} (${result.zoneDomain})`);
+            out.info(`Status: ${result.status}`);
+            for (const observation of result.observations) {
+                const answers = observation.answers.map((answer) => `${answer.value}${answer.ttl == null ? '' : ` (TTL ${answer.ttl}s)`}`);
+                out.info(`${observation.resolver}: ${answers.join(', ') || observation.error || 'no answer'}`);
+            }
+        }
+        catch (error) {
+            spinner?.error('DNS diagnosis failed');
+            outputError(out.json, error, 'DNS_DIAGNOSE_FAILED');
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/dns/point.js

@@ -1,5 +1,6 @@
 import * as p from '@clack/prompts';
 import { Args, Command, Flags } from '@oclif/core';
+import { normalizeDnsValue } from '../../lib/dns-records.js';
 import { accountFlag, jsonFlag, providerFlag } from '../../lib/flags.js';
 import { createOutput, outputError } from '../../lib/output.js';
 import { pointDomain } from '../../lib/point-domain.js';
@@ -22,6 +23,22 @@ function conflictNote(warning) {
     ].join('\n');
 }
 function successMessages(result, waited) {
+    if (result.propagation.status === 'system_resolver_unavailable') {
+        return {
+            outro: 'Public DNS is deployed, but the system resolver could not be queried. See resolver observations for details.',
+            spinner: 'Public DNS deployed; system resolver unavailable',
+        };
+    }
+    if (result.propagation.status === 'local_or_vpn_cache_stale') {
+        const system = result.propagation.observations.find((observation) => observation.kind === 'system');
+        const remainingTtl = system?.answers
+            .filter((answer) => normalizeDnsValue(answer.value) !== normalizeDnsValue(result.propagation.expected))
+            .reduce((longest, answer) => (answer.ttl == null ? longest : Math.max(longest ?? 0, answer.ttl)), undefined);
+        return {
+            outro: `DNS is deployed; your active VPN/local resolver is serving a cached record${remainingTtl === undefined ? '' : ` for up to ${remainingTtl} more seconds`}.`,
+            spinner: 'DNS deployed; local resolver cache is stale',
+        };
+    }
     if (result.propagated) {
         return {
             outro: result.updated

package/dist/commands/dns/remove.d.ts

@@ -0,0 +1,18 @@
+import { Command } from '@oclif/core';
+export default class DnsRemove extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        domain: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        account: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'all-matching': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        provider: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        type: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        value: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/dns/remove.js

@@ -0,0 +1,77 @@
+import * as p from '@clack/prompts';
+import { Args, Command, Flags } from '@oclif/core';
+import { accountFlag, jsonFlag, providerFlag } from '../../lib/flags.js';
+import { createOutput, outputError } from '../../lib/output.js';
+import { removeDomain } from '../../lib/remove-domain.js';
+function recordLines(records) {
+    return records.map((record) => `- ${record.type} ${record.name} -> ${record.value}`).join('\n');
+}
+export default class DnsRemove extends Command {
+    static description = 'Safely remove exact DNS records and verify their absence.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> app.example.com --type A --value 203.0.113.10 --dry-run --json',
+        '<%= config.bin %> <%= command.id %> app.example.com --type A --all-matching --json',
+    ];
+    static args = {
+        domain: Args.string({ description: 'Fully qualified DNS name whose record should be removed.', required: true }),
+    };
+    static flags = {
+        account: accountFlag,
+        'all-matching': Flags.boolean({
+            description: 'Delete every record matching the name and type (and value, if set).',
+        }),
+        'dry-run': Flags.boolean({ description: 'Preview the exact records without deleting them.' }),
+        json: jsonFlag,
+        provider: providerFlag,
+        type: Flags.string({
+            description: 'DNS record type to remove.',
+            options: ['A', 'AAAA', 'CNAME', 'MX', 'TXT'],
+            required: true,
+        }),
+        value: Flags.string({ description: 'Expected record value. Required unless --all-matching is passed.' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(DnsRemove);
+        const out = createOutput({ json: flags.json });
+        const spinner = flags['dry-run'] || out.json ? undefined : out.spinner();
+        try {
+            spinner?.start(`Inspecting ${args.domain}`);
+            const result = await removeDomain({
+                account: flags.account,
+                allMatching: flags['all-matching'],
+                confirmMultiple: out.json
+                    ? undefined
+                    : async (records) => {
+                        spinner?.stop('Multiple matching records found');
+                        p.note(recordLines(records), 'Records selected for deletion');
+                        const confirmed = await p.confirm({
+                            initialValue: false,
+                            message: `Delete all ${records.length} matching records?`,
+                        });
+                        if (confirmed === true)
+                            spinner?.start(`Deleting records from ${args.domain}`);
+                        return confirmed === true;
+                    },
+                domain: args.domain,
+                dryRun: flags['dry-run'],
+                progress: out.json ? undefined : (message) => spinner?.message(message),
+                provider: flags.provider,
+                recordType: flags.type,
+                value: flags.value,
+            });
+            spinner?.stop(result.removed === 0 ? 'No matching records found' : 'DNS records removed');
+            out.result(result);
+            if (flags['dry-run'] && !out.json)
+                p.note(recordLines(result.matched) || 'No matching records.', 'Dry run');
+            else
+                out.outro(result.removed === 0
+                    ? `No matching DNS record exists for ${result.domain}.`
+                    : `Removed ${result.removed} DNS record${result.removed === 1 ? '' : 's'} from ${result.domain}.`);
+        }
+        catch (error) {
+            spinner?.error('DNS removal failed');
+            outputError(out.json, error, 'DNS_REMOVE_FAILED');
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/providers/status.js

@@ -25,8 +25,7 @@ export default class ProvidersStatus extends Command {
         const providers = await listProviderStatuses({ verify: !flags['no-verify'] });
         spinner?.stop('Checked DNS providers');
         for (const provider of providers) {
-            const account = provider.isDefaultAccount ? provider.id : `${provider.id}/${provider.account}`;
-            out.info(`${provider.displayName} (${account}) - ${formatStatus(provider)}${provider.default ? ' [default]' : ''}`);
+            out.info(`${provider.displayName} (${provider.accountLabel}) - ${formatStatus(provider)}${provider.isPreferredProvider ? ' [preferred provider]' : ''}`);
         }
         out.result({ providers });
     }

package/dist/lib/command-schema.d.ts

@@ -1,5 +1,5 @@
 import { type ProviderStatus } from './providers/status.js';
-export type ProviderConnectionStatus = Pick<ProviderStatus, 'account' | 'configured' | 'default' | 'displayName' | 'docsUrl' | 'id' | 'isDefaultAccount'>;
+export type ProviderConnectionStatus = Pick<ProviderStatus, 'account' | 'accountLabel' | 'configured' | 'default' | 'displayName' | 'docsUrl' | 'id' | 'isDefaultAccount' | 'isPreferredProvider'>;
 export interface CommandSchema {
     name: string;
     description: string;

package/dist/lib/command-schema.js

@@ -1,4 +1,14 @@
 import { listProviderStatuses } from './providers/status.js';
+const dnsRemovalFlags = [
+    { name: 'json', type: 'boolean', description: 'Output a single JSON object and never prompt.' },
+    { name: 'domain', type: 'string', description: 'Fully qualified DNS name.', required: true },
+    { name: 'type', type: 'string', description: 'A, AAAA, CNAME, MX, or TXT.', required: true },
+    { name: 'value', type: 'string', description: 'Expected exact value. Required unless --all-matching.' },
+    { name: 'provider', type: 'string', description: 'DNS provider id. Inferred when omitted.' },
+    { name: 'account', type: 'string', description: 'DNS provider profile/account alias.' },
+    { name: 'all-matching', type: 'boolean', description: 'Delete every matching record after explicit approval.' },
+    { name: 'dry-run', type: 'boolean', description: 'Preview exact records without deleting.' },
+];
 export const commandSchemas = [
     {
         name: 'dns point',
@@ -12,6 +22,7 @@ export const commandSchemas = [
         agentInstructions: [
             'When a user asks to point a domain at a VPS or hostname, run `doomain dns point <domain> --target <ip-or-hostname> --json`.',
             'Pass --force only after the user has approved replacing an existing DNS target.',
+            'A successful mutation always has reconciled=true. propagated=false with public_propagation_pending means the provider mutation succeeded but public verification timed out; system_resolver_unavailable means public DNS matches but the local resolver check failed. Inspect propagation.observations before retrying.',
         ],
         agentQuickstart: {
             doNotPreflight: true,
@@ -42,6 +53,49 @@ export const commandSchemas = [
             { name: 'timeout', type: 'integer', description: 'DNS propagation wait timeout in seconds.', default: 300 },
         ],
     },
+    {
+        name: 'dns remove',
+        description: 'Safely remove exact DNS records and verify their absence.',
+        examples: [
+            'doomain dns remove app.example.com --type A --value 203.0.113.10 --dry-run --json',
+            'doomain dns remove app.example.com --type A --value 203.0.113.10 --json',
+            'doomain dns delete app.example.com --type A --all-matching --json',
+        ],
+        agentHint: 'Default to exact name/type/value deletion. Preview with --dry-run when the expected value is unknown. Never pass --all-matching without explicit approval.',
+        mutates: true,
+        safeForAgents: true,
+        flags: dnsRemovalFlags,
+    },
+    {
+        name: 'dns diagnose',
+        description: 'Compare provider control-plane records with system and public DNS resolvers.',
+        examples: [
+            'doomain dns diagnose example.com --json',
+            'doomain dns diagnose app.example.com --type A --target 203.0.113.10 --json',
+        ],
+        agentHint: 'Use this read-only command to distinguish provider_not_updated, public_propagation_pending, and local_or_vpn_cache_stale. Resolver observations include answers and TTLs.',
+        safeForAgents: true,
+        flags: [
+            { name: 'json', type: 'boolean', description: 'Output a single JSON object and never prompt.' },
+            { name: 'domain', type: 'string', description: 'Fully qualified DNS name.', required: true },
+            { name: 'type', type: 'string', description: 'A, AAAA, or CNAME. Defaults to A.' },
+            { name: 'target', type: 'string', description: 'Optional expected IP address or canonical hostname.' },
+            { name: 'provider', type: 'string', description: 'DNS provider id. Inferred when omitted.' },
+            { name: 'account', type: 'string', description: 'DNS provider profile/account alias.' },
+        ],
+    },
+    {
+        name: 'dns delete',
+        description: 'Alias for dns remove.',
+        examples: [
+            'doomain dns delete app.example.com --type A --value 203.0.113.10 --dry-run --json',
+            'doomain dns delete app.example.com --type A --all-matching --json',
+        ],
+        agentHint: 'Alias for dns remove; use the same exact-match and explicit --all-matching safety rules.',
+        mutates: true,
+        safeForAgents: true,
+        flags: dnsRemovalFlags,
+    },
     {
         name: 'link',
         description: 'Link a Vercel project to a domain and create DNS records.',
@@ -391,16 +445,23 @@ export function getCommandSchema(name) {
 async function configuredProviders() {
     return (await listProviderStatuses({ verify: false })).map((provider) => ({
         account: provider.account,
+        accountLabel: provider.accountLabel,
         configured: provider.configured,
         default: provider.default,
         displayName: provider.displayName,
         docsUrl: provider.docsUrl,
         id: provider.id,
         isDefaultAccount: provider.isDefaultAccount,
+        isPreferredProvider: provider.isPreferredProvider,
     }));
 }
 function withProviderConnections(schema, providers) {
-    if (schema.name !== 'link' && schema.name !== 'clerk domains add' && schema.name !== 'dns point')
+    if (schema.name !== 'link' &&
+        schema.name !== 'clerk domains add' &&
+        schema.name !== 'dns point' &&
+        schema.name !== 'dns remove' &&
+        schema.name !== 'dns delete' &&
+        schema.name !== 'dns diagnose')
         return schema;
     return { ...schema, configuredProviders: providers };
 }

package/dist/lib/diagnose-dns.d.ts

@@ -0,0 +1,53 @@
+import { type DnsResolverObservation } from './dns-propagation.js';
+import { type ResolvedDnsTarget } from './domain-provider.js';
+import type { DnsProvider, DnsRecord, DnsRecordInput, DnsRecordType } from './providers/types.js';
+export type DnsDiagnosisStatus = 'consistent' | 'local_or_vpn_cache_stale' | 'provider_not_updated' | 'public_propagation_pending' | 'system_resolver_unavailable';
+export interface DiagnoseDnsInput {
+    account?: string;
+    domain: string;
+    provider?: string;
+    recordType?: 'A' | 'AAAA' | 'CNAME';
+    target?: string;
+}
+export interface DnsRecordConflict {
+    reason: 'cname_slot_conflict' | 'multiple_values';
+    records: DnsRecord[];
+    type?: DnsRecordType;
+}
+export interface MacOsResolverMetadata {
+    flags?: string;
+    interfaceIndex?: number;
+    interfaceName?: string;
+    nameservers: string[];
+    resolver: number;
+}
+export interface DiagnoseDnsResult {
+    account: string;
+    accountInferred: boolean;
+    conflicts: DnsRecordConflict[];
+    domain: string;
+    expected?: string;
+    interfaces: string[];
+    isDefaultAccount: boolean;
+    macOsResolvers?: MacOsResolverMetadata[];
+    observations: DnsResolverObservation[];
+    platform: NodeJS.Platform;
+    provider: string;
+    providerInferred: boolean;
+    providerRecords: DnsRecord[];
+    recordType: 'A' | 'AAAA' | 'CNAME';
+    status: DnsDiagnosisStatus;
+    systemResolverServers: string[];
+    warnings: ResolvedDnsTarget['warnings'];
+    zoneDomain: string;
+}
+interface DiagnoseDnsDependencies {
+    createProvider: (provider: string, opts: {
+        account?: string;
+    }) => Promise<DnsProvider>;
+    observeDns: (fqdn: string, target: Pick<DnsRecordInput, 'type' | 'value'>, elapsedMs: number) => Promise<DnsResolverObservation[]>;
+    resolveTarget: (input: Pick<DiagnoseDnsInput, 'account' | 'domain' | 'provider'>) => Promise<ResolvedDnsTarget>;
+    macOsResolvers?: () => Promise<MacOsResolverMetadata[]>;
+}
+export declare function diagnoseDns(input: DiagnoseDnsInput, dependencies?: DiagnoseDnsDependencies): Promise<DiagnoseDnsResult>;
+export {};

package/dist/lib/diagnose-dns.js

@@ -0,0 +1,156 @@
+import { execFile } from 'node:child_process';
+import { getServers } from 'node:dns';
+import { networkInterfaces, platform } from 'node:os';
+import { promisify } from 'node:util';
+import { classifyDnsPropagation, isNegativeDnsObservation, observeDnsRecord, } from './dns-propagation.js';
+import { desiredSlotPostcondition, dnsRecordNamesEqual, inferAddressRecordType, normalizeAddressRecordTarget, normalizeDnsValue, } from './dns-records.js';
+import { resolveProviderTarget } from './domain-provider.js';
+import { DoomainError } from './errors.js';
+import { createProvider } from './providers/registry.js';
+const execFileAsync = promisify(execFile);
+async function readMacOsResolvers() {
+    if (platform() !== 'darwin')
+        return [];
+    try {
+        const { stdout } = await execFileAsync('scutil', ['--dns'], { maxBuffer: 1024 * 1024 });
+        return String(stdout)
+            .split(/\n(?=resolver #\d+)/)
+            .flatMap((block) => {
+            const resolver = block.match(/resolver #(\d+)/)?.[1];
+            if (!resolver)
+                return [];
+            const interfaceMatch = block.match(/if_index\s*:\s*(\d+)(?:\s*\(([^)]+)\))?/);
+            const nameservers = [...block.matchAll(/nameserver\[\d+\]\s*:\s*(\S+)/g)].map((match) => match[1]);
+            const flags = block.match(/flags\s*:\s*(.+)/)?.[1]?.trim();
+            return [
+                {
+                    ...(flags ? { flags } : {}),
+                    ...(interfaceMatch ? { interfaceIndex: Number(interfaceMatch[1]) } : {}),
+                    ...(interfaceMatch?.[2] ? { interfaceName: interfaceMatch[2] } : {}),
+                    nameservers,
+                    resolver: Number(resolver),
+                },
+            ];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+const defaultDependencies = {
+    createProvider,
+    macOsResolvers: readMacOsResolvers,
+    observeDns: (fqdn, target, elapsedMs) => observeDnsRecord(fqdn, target, undefined, elapsedMs),
+    resolveTarget: (input) => resolveProviderTarget(input, { tolerateProviderAccountErrors: true }),
+};
+function recordConflicts(records) {
+    const conflicts = [];
+    for (const type of ['A', 'AAAA', 'CNAME']) {
+        const typed = records.filter((record) => record.type === type);
+        const values = new Set(typed.map((record) => normalizeDnsValue(record.value)));
+        if (values.size > 1)
+            conflicts.push({ reason: 'multiple_values', records: typed, type });
+    }
+    const cnames = records.filter((record) => record.type === 'CNAME');
+    const otherRecords = records.filter((record) => record.type !== 'CNAME');
+    if (cnames.length > 0 && otherRecords.length > 0) {
+        conflicts.push({ reason: 'cname_slot_conflict', records: [...cnames, ...otherRecords] });
+    }
+    return conflicts;
+}
+function activeInterfaceNames() {
+    return Object.entries(networkInterfaces())
+        .filter(([, addresses]) => addresses?.some((address) => !address.internal))
+        .map(([name]) => name)
+        .sort();
+}
+function diagnosisStatus(status) {
+    if (status === 'propagated')
+        return 'consistent';
+    if (status === 'local_or_vpn_cache_stale')
+        return status;
+    if (status === 'system_resolver_unavailable')
+        return status;
+    return 'public_propagation_pending';
+}
+function diagnosisResolutionError(error, input) {
+    if (error.code !== 'CONFIG_NOT_FOUND' && error.code !== 'PROVIDER_ZONE_NOT_FOUND')
+        return error;
+    const details = error.details && typeof error.details === 'object' ? error.details : {};
+    const provider = input.provider ? ` --provider ${input.provider}` : '';
+    const account = input.account ? ` --account ${input.account}` : '';
+    const type = input.recordType ? ` --type ${input.recordType}` : '';
+    const target = input.target ? ` --target ${input.target}` : '';
+    const retry = `doomain dns diagnose ${input.domain}${provider}${account}${type}${target} --json`;
+    return new DoomainError(error.code, error.message, {
+        ...details,
+        recovery: `Connect or repair the DNS provider account that owns this domain, then retry \`${retry}\`.`,
+        suggestedCommands: ['doomain providers connect', retry],
+    });
+}
+export async function diagnoseDns(input, dependencies = defaultDependencies) {
+    const recordType = input.recordType ?? (input.target ? inferAddressRecordType(input.target.trim()) : undefined) ?? 'A';
+    const requestedTarget = input.target === undefined ? undefined : normalizeAddressRecordTarget(recordType, input.target);
+    let resolved;
+    try {
+        resolved = await dependencies.resolveTarget(input);
+    }
+    catch (error) {
+        if (error instanceof DoomainError)
+            throw diagnosisResolutionError(error, input);
+        throw error;
+    }
+    const provider = await dependencies.createProvider(resolved.provider, { account: resolved.account });
+    const zone = await provider.getZone(resolved.target.zoneDomain);
+    if (!zone) {
+        throw diagnosisResolutionError(new DoomainError('PROVIDER_ZONE_NOT_FOUND', `${provider.name} does not have a DNS zone for ${resolved.target.zoneDomain}.`), input);
+    }
+    const allRecords = await provider.listRecords(zone);
+    const providerRecords = allRecords.filter((record) => dnsRecordNamesEqual(record.name, resolved.target.recordName));
+    const recordsOfType = providerRecords.filter((record) => record.type === recordType);
+    const expected = requestedTarget ?? (recordsOfType.length === 1 ? recordsOfType[0].value : undefined);
+    const queryTarget = { type: recordType, value: expected ?? recordsOfType[0]?.value ?? '' };
+    const observations = await dependencies.observeDns(resolved.target.fullDomain, queryTarget, 0);
+    const macOsResolvers = await dependencies.macOsResolvers?.();
+    let status;
+    if (expected) {
+        const postcondition = desiredSlotPostcondition(allRecords, {
+            name: resolved.target.recordName,
+            type: recordType,
+            value: expected,
+        });
+        status = postcondition.reconciled ? diagnosisStatus(classifyDnsPropagation(observations)) : 'provider_not_updated';
+    }
+    else {
+        const providerValues = new Set(recordsOfType.map((record) => normalizeDnsValue(record.value)));
+        const compared = observations.map((observation) => ({
+            ...observation,
+            matches: providerValues.size === 0
+                ? observation.answers.length === 0 && isNegativeDnsObservation(observation)
+                : observation.answers.length === providerValues.size &&
+                    observation.answers.every((answer) => providerValues.has(normalizeDnsValue(answer.value))),
+        }));
+        observations.splice(0, observations.length, ...compared);
+        status = diagnosisStatus(classifyDnsPropagation(observations));
+    }
+    return {
+        account: resolved.account,
+        accountInferred: resolved.accountInferred,
+        conflicts: recordConflicts(providerRecords),
+        domain: resolved.target.fullDomain,
+        ...(expected === undefined ? {} : { expected }),
+        interfaces: activeInterfaceNames(),
+        isDefaultAccount: resolved.isDefaultAccount,
+        ...(macOsResolvers && macOsResolvers.length > 0 ? { macOsResolvers } : {}),
+        observations,
+        platform: platform(),
+        provider: resolved.provider,
+        providerInferred: resolved.providerInferred,
+        providerRecords,
+        recordType,
+        status,
+        systemResolverServers: getServers(),
+        warnings: resolved.warnings,
+        zoneDomain: resolved.target.zoneDomain,
+    };
+}