@geekmidas/cli 10.0.0-alpha.93 → 10.0.0-alpha.95

package/dist/dns-Bmk7P9c2.cjs

@@ -0,0 +1,663 @@
+const require_errors = require("./errors-DMC4Umsb.cjs");
+const require_workspace = require("./workspace-cSyi5nb1.cjs");
+const require_seeds = require("./seeds-CnXkgKUv.cjs");
+let node_net = require("node:net");
+let node_dns_promises = require("node:dns/promises");
+//#region src/compose/dns.ts
+/**
+* A compose stage's DNS: the records its public hosts need, and the check that
+* they resolve to its server before a certificate is asked for.
+*
+* - **The server** (`serverAddress`): the stage's own secrets hold its public
+*   addresses — `GKM_SERVER_IPV4`, and `GKM_SERVER_IPV6` where it has one.
+*   Reserved for gkm: never handed to an app.
+* - **The plan** (`planStackDns`, pure): every public host the stack serves —
+*   its apex, each app, each file server, the public log UI — pointed at the
+*   server. An A record per host (and an AAAA with an IPv6 address), or, where
+*   the domain's `dns` entry says `records: { mode: 'cname', target }`, one A
+*   record for the target and a CNAME to it for every other host but the
+*   apex, which DNS forbids a CNAME at.
+* - **Applying it** (`applyStackDns`): through the domain's provider in `dns`,
+*   a record set at a time. A record with the right value is left alone; one
+*   with another value is replaced and the change printed. A `manual` domain
+*   is printed and nothing else. A dry run reads, prints and writes nothing.
+* - **The check** (`checkStackDns`): each host resolved with the system
+*   resolver. One that is not the server stops the deploy with
+*   {@link HostNotPointingAtServer}, before Caddy or Traefik ask Let's Encrypt
+*   for a certificate it cannot get — and use up the rate limit trying.
+* - **The step** (`stageDns`): all three, as every deploy runs them — the plan applied through each provider,
+*   what was written read back from the provider, and only the hosts no
+*   provider wrote resolved publicly. A brand-new name is never looked up
+*   before its record exists, so no resolver caches it as missing.
+*/
+/** The line that says how to set the server's address. */
+function serverAddressHint(stage) {
+	return `gkm secrets:set ${require_workspace.SERVER_IPV4_KEY} '<ip>' --stage ${stage}`;
+}
+/** A server address in the stage's secrets that is not an address. */
+var ServerAddressInvalid = class extends require_errors.GkmError {
+	stage;
+	key;
+	value;
+	constructor(stage, key, value) {
+		const ipv4 = key === require_workspace.SERVER_IPV4_KEY;
+		super(`${key} in the '${stage}' stage's secrets is ${JSON.stringify(value)}, which is not an ${ipv4 ? "IPv4 address (like 203.0.113.10)" : "IPv6 address (like 2001:db8::10)"}. Set the server's public address: gkm secrets:set ${key} '<ip>' --stage ${stage}.`);
+		this.stage = stage;
+		this.key = key;
+		this.value = value;
+		this.name = "ServerAddressInvalid";
+	}
+};
+/**
+* A compose stage that serves real domains with no server address: its hosts
+* cannot be pointed or checked, and a certificate would be asked for blind.
+*/
+var ServerAddressMissing = class extends require_errors.GkmError {
+	stage;
+	domain;
+	constructor(stage, domain) {
+		super(`The '${stage}' stage serves ${domain} and its secrets hold no ${require_workspace.SERVER_IPV4_KEY} — the public address of the server its stack runs on, which its hosts' DNS records point at and every deploy checks before asking for certificates. Set it: ${serverAddressHint(stage)} (and ${require_workspace.SERVER_IPV6_KEY} for an IPv6 address).`);
+		this.stage = stage;
+		this.domain = domain;
+		this.name = "ServerAddressMissing";
+	}
+};
+/**
+* The server's address from the stage's secrets, checked — `undefined` when
+* `GKM_SERVER_IPV4` is not set.
+*
+* @throws {ServerAddressInvalid} for a value that is not an address
+*/
+function serverAddress(stage, custom) {
+	const ipv4 = custom?.[require_workspace.SERVER_IPV4_KEY]?.trim();
+	const ipv6 = custom?.[require_workspace.SERVER_IPV6_KEY]?.trim();
+	if (ipv6 && !(0, node_net.isIPv6)(ipv6)) throw new ServerAddressInvalid(stage, require_workspace.SERVER_IPV6_KEY, ipv6);
+	if (!ipv4) return void 0;
+	if (!(0, node_net.isIPv4)(ipv4)) throw new ServerAddressInvalid(stage, require_workspace.SERVER_IPV4_KEY, ipv4);
+	return {
+		ipv4,
+		...ipv6 ? { ipv6 } : {}
+	};
+}
+/**
+* A name that resolves to this machine by definition — `localhost` and every
+* `*.localhost` — and is in nobody's DNS.
+*/
+function isLocalHost(host) {
+	const name = host.toLowerCase().replace(/\.$/, "");
+	return name === "localhost" || name.endsWith(".localhost");
+}
+/**
+* The server's address, required where the stage serves real domains — not
+* `*.localhost` ones, which point at this machine already.
+*
+* @throws {ServerAddressMissing} when the stage has a domain and no address
+* @throws {ServerAddressInvalid} for a value that is not an address
+*/
+function requiredServerAddress(stage, domain, custom) {
+	const server = serverAddress(stage, custom);
+	if (!server && domain && !isLocalHost(domain)) throw new ServerAddressMissing(stage, domain);
+	return server;
+}
+const MANAGED = [
+	"A",
+	"AAAA",
+	"CNAME"
+];
+/** Every public host the stack serves, once each, sorted. */
+function stackHosts(stack) {
+	return [...new Set(stack.routes.map((route) => route.host))].sort();
+}
+/** The TTL a domain's records are written with. */
+function recordTtl(config) {
+	const ttl = "ttl" in config ? config.ttl : void 0;
+	if (ttl) return ttl;
+	return config.provider === "godaddy" ? 600 : 300;
+}
+function providerName(config) {
+	return typeof config.provider === "string" ? config.provider : "custom";
+}
+/**
+* A wildcard host: gkm writes one record per public host, so a stage on
+* another server — or a name someone else points elsewhere — is never caught
+* by a record it did not ask for.
+*/
+var DnsWildcardRefused = class extends require_errors.GkmError {
+	stage;
+	host;
+	constructor(stage, host) {
+		super(`'${stage}' would point ${host} at its server, and gkm never writes a wildcard record: each public host gets its own. Give the app a subdomain of its own instead.`);
+		this.stage = stage;
+		this.host = host;
+		this.name = "DnsWildcardRefused";
+	}
+};
+/** The records a stage's hosts need — pure. */
+function planStackDns(input) {
+	const { stage, server } = input;
+	const dns = input.dns ? require_seeds.normalizeDnsConfig(input.dns) : {};
+	const records = /* @__PURE__ */ new Map();
+	const uncovered = [];
+	const add = (host, domain, type, value) => {
+		const name = require_seeds.extractSubdomain(host, domain);
+		records.set(`${domain} ${name} ${type}`, {
+			host,
+			domain,
+			name,
+			type,
+			value,
+			ttl: recordTtl(dns[domain])
+		});
+	};
+	const pointAt = (host, domain) => {
+		add(host, domain, "A", server.ipv4);
+		if (server.ipv6) add(host, domain, "AAAA", server.ipv6);
+	};
+	for (const raw of input.hosts) {
+		const host = raw.toLowerCase();
+		if (host.includes("*")) throw new DnsWildcardRefused(stage, host);
+		const domain = require_seeds.findRootDomain(host, dns);
+		if (!domain) {
+			uncovered.push(host);
+			continue;
+		}
+		const target = require_workspace.cnameTarget(dns[domain].records, stage);
+		if (target) pointAt(target, domain);
+		if (target && host !== domain && host !== target) add(host, domain, "CNAME", target);
+		else pointAt(host, domain);
+	}
+	const domains = /* @__PURE__ */ new Map();
+	for (const record of [...records.values()].sort((a, b) => a.domain.localeCompare(b.domain) || a.name.localeCompare(b.name) || a.type.localeCompare(b.type))) {
+		const config = dns[record.domain];
+		const plan = domains.get(record.domain) ?? {
+			domain: record.domain,
+			provider: providerName(config),
+			config,
+			records: []
+		};
+		plan.records.push(record);
+		domains.set(record.domain, plan);
+	}
+	return {
+		stage,
+		server,
+		domains: [...domains.values()],
+		uncovered: uncovered.sort()
+	};
+}
+/** Records a provider accepted and then did not read back with their value. */
+var DnsRecordsNotConfirmed = class extends require_errors.GkmError {
+	stage;
+	domain;
+	provider;
+	records;
+	constructor(stage, domain, provider, records) {
+		const lines = records.map((r) => `  - ${r.host} ${r.type}: ${r.found.length > 0 ? r.found.join(", ") : "nothing"}, expected ${r.expected}`);
+		super(`${provider} accepted '${stage}''s records for ${domain}, and reading them back does not show them:\n${lines.join("\n")}\nDeploy again; if it persists, check the records in the provider's console — another tool may be writing the same names.`);
+		this.stage = stage;
+		this.domain = domain;
+		this.provider = provider;
+		this.records = records;
+		this.name = "DnsRecordsNotConfirmed";
+	}
+};
+/** `api.example.com  A  203.0.113.10  (TTL 600)` */
+function describe(record) {
+	return `${record.host.padEnd(32)} ${record.type.padEnd(5)} ${record.value}  (TTL ${record.ttl})`;
+}
+function printManual(plan, log, why) {
+	log(`   ${plan.domain}: ${why} — create these records at its DNS host:`);
+	for (const record of plan.records) log(`     ${describe(record)}`);
+	return plan.records.map((r) => ({
+		domain: r.domain,
+		name: r.name,
+		type: r.type,
+		action: "manual",
+		value: r.value,
+		ttl: r.ttl
+	}));
+}
+/** The existing records of every planned name, for the types gkm manages. */
+async function existingRecords(provider, plan) {
+	const names = [...new Set(plan.records.map((r) => r.name))];
+	const wanted = names.flatMap((name) => MANAGED.map((type) => ({
+		name,
+		type
+	})));
+	if (provider.readRecords) return provider.readRecords(plan.domain, wanted);
+	return (await provider.getRecords(plan.domain)).filter((r) => names.includes(r.name) && MANAGED.includes(r.type));
+}
+const same = (a, b) => a.trim().replace(/\.$/, "").toLowerCase() === b.trim().replace(/\.$/, "").toLowerCase();
+/**
+* What each domain's records need, compared with what is there: creates,
+* updates, and the deletes a change of mode needs — a name moving from an A
+* record to a CNAME, or back, cannot hold both. Nothing else is deleted.
+*/
+function diffDomainDns(plan, existing) {
+	const changes = [];
+	const find = (name, type) => existing.find((r) => r.name === name && r.type === type);
+	const planned = /* @__PURE__ */ new Map();
+	for (const record of plan.records) {
+		const types = planned.get(record.name) ?? /* @__PURE__ */ new Set();
+		types.add(record.type);
+		planned.set(record.name, types);
+	}
+	for (const [name, types] of planned) {
+		const conflicting = types.has("CNAME") ? ["A", "AAAA"] : ["CNAME"];
+		for (const type of conflicting) {
+			const found = find(name, type);
+			if (!found || found.values.length === 0) continue;
+			changes.push({
+				domain: plan.domain,
+				name,
+				type,
+				action: "delete",
+				previous: found.values.join(", ")
+			});
+		}
+	}
+	for (const record of plan.records) {
+		const found = find(record.name, record.type);
+		const base = {
+			domain: plan.domain,
+			name: record.name,
+			type: record.type,
+			value: record.value,
+			ttl: record.ttl
+		};
+		if (!found || found.values.length === 0) changes.push({
+			...base,
+			action: "create"
+		});
+		else if (found.values.length === 1 && same(found.values[0], record.value)) changes.push({
+			...base,
+			action: "unchanged"
+		});
+		else changes.push({
+			...base,
+			action: "update",
+			previous: found.values.join(", ")
+		});
+	}
+	return changes;
+}
+/** A host's full name from a domain and a relative name. */
+function fullName(domain, name) {
+	return name === "@" ? domain : `${name}.${domain}`;
+}
+function printChange(change, dryRun, log) {
+	const host = fullName(change.domain, change.name).padEnd(32);
+	const type = change.type.padEnd(5);
+	const would = dryRun ? "would " : "";
+	switch (change.action) {
+		case "unchanged":
+			log(`   ✓ ${host} ${type} ${change.value}  (TTL ${change.ttl}) — up to date`);
+			break;
+		case "create":
+			log(`   + ${host} ${type} ${change.value}  (TTL ${change.ttl}) — ${would}create`);
+			break;
+		case "update":
+			log(`   ~ ${host} ${type} ${change.previous} → ${change.value}  (TTL ${change.ttl}) — ${would}update`);
+			break;
+		case "write":
+			log(dryRun ? `   ? ${host} ${type} ${change.value}  (TTL ${change.ttl}) — would write; current value unknown (key cannot read DNS)` : `   ! ${host} ${type} ${change.value}  (TTL ${change.ttl}) — written (not diffed)`);
+			break;
+		case "delete": log(`   - ${host} ${type} ${change.previous} — ${would}delete (a name cannot hold a CNAME and an A record)`);
+	}
+}
+/**
+* Each domain's records, through its provider — and, with `confirm`, what was
+* written read back from it. A record already holding its value is neither
+* written nor read again.
+*
+* @throws {DnsRecordsNotConfirmed} when a written record does not read back
+*/
+async function settleStackDns(plan, options = {}) {
+	const dryRun = options.dryRun === true;
+	const log = options.log ?? ((line) => console.log(line));
+	const providerFor = options.providerFor ?? ((config) => require_seeds.createDnsProvider({
+		config,
+		...options.credentials ? { godaddy: options.credentials } : {},
+		...options.hostinger ? { hostinger: options.hostinger } : {}
+	}));
+	const changes = [];
+	const confirmed = /* @__PURE__ */ new Set();
+	const unconfirmed = /* @__PURE__ */ new Set();
+	const hostsOf = (domain) => new Set(domain.records.map((r) => r.host));
+	for (const host of plan.uncovered) log(`   ⚠ ${host} is under no domain in dns — point it at ${plan.server.ipv4} yourself`);
+	for (const domain of plan.domains) {
+		if (domain.provider === "manual") {
+			changes.push(...printManual(domain, log, "manual"));
+			for (const host of hostsOf(domain)) unconfirmed.add(host);
+			continue;
+		}
+		const provider = await providerFor(domain.config);
+		if (!provider) {
+			changes.push(...printManual(domain, log, "manual"));
+			for (const host of hostsOf(domain)) unconfirmed.add(host);
+			continue;
+		}
+		log(`   ${domain.domain} (${provider.name})${dryRun ? " — dry run" : ""}`);
+		let existing;
+		let diff;
+		let unreadable = false;
+		try {
+			existing = await existingRecords(provider, domain);
+			diff = diffDomainDns(domain, existing);
+		} catch (error) {
+			if (!(error instanceof require_seeds.DnsRecordsUnreadable)) throw error;
+			log(`   ℹ The ${provider.name} key cannot read ${domain.domain}'s DNS records, so changes cannot be diffed: every record is written (idempotent).`);
+			unreadable = true;
+			existing = [];
+			diff = domain.records.map((r) => ({
+				domain: r.domain,
+				name: r.name,
+				type: r.type,
+				action: "write",
+				value: r.value,
+				ttl: r.ttl
+			}));
+		}
+		for (const change of diff) printChange(change, dryRun, log);
+		if (!plan.server.ipv6) for (const name of new Set(domain.records.map((r) => r.name))) {
+			const aaaa = existing.find((r) => r.name === name && r.type === "AAAA");
+			const planned = domain.records.find((r) => r.name === name && r.type === "A");
+			if (aaaa && planned && aaaa.values.length > 0) log(`   ⚠ ${fullName(domain.domain, name)} also has AAAA ${aaaa.values.join(", ")}: set ${require_workspace.SERVER_IPV6_KEY} in the '${plan.stage}' stage's secrets to the server's IPv6 address, or remove that record, or IPv6 clients go elsewhere`);
+		}
+		changes.push(...diff);
+		const written = new Set(diff.filter((c) => c.action !== "unchanged").map((c) => fullName(c.domain, c.name)));
+		for (const host of hostsOf(domain)) if (unreadable) {
+			if (!dryRun) unconfirmed.add(host);
+		} else if (!written.has(host)) confirmed.add(host);
+		if (dryRun) continue;
+		const deletes = diff.filter((c) => c.action === "delete");
+		if (deletes.length > 0) await provider.deleteRecords(domain.domain, deletes.map((c) => ({
+			name: c.name,
+			type: c.type
+		})));
+		const writes = diff.filter((c) => c.action === "create" || c.action === "update" || c.action === "write");
+		if (writes.length > 0) await provider.upsertRecords(domain.domain, writes.map((c) => ({
+			name: c.name,
+			type: c.type,
+			value: c.value,
+			ttl: c.ttl
+		})));
+		if (!options.confirm || unreadable || written.size === 0) continue;
+		const rewritten = {
+			...domain,
+			records: domain.records.filter((r) => written.has(r.host))
+		};
+		const after = await existingRecords(provider, rewritten);
+		const missing = [];
+		for (const record of rewritten.records) {
+			const values = after.find((r) => r.name === record.name && r.type === record.type)?.values ?? [];
+			if (values.length !== 1 || !same(values[0], record.value)) missing.push({
+				host: record.host,
+				type: record.type,
+				expected: record.value,
+				found: values
+			});
+		}
+		if (missing.length > 0) throw new DnsRecordsNotConfirmed(plan.stage, domain.domain, provider.name, missing);
+		for (const host of written) confirmed.add(host);
+		log(`   ✓ ${written.size} host${written.size === 1 ? "" : "s"} read back from ${provider.name}`);
+	}
+	for (const host of plan.uncovered) unconfirmed.add(host);
+	return {
+		changes,
+		confirmed: [...confirmed].sort(),
+		unconfirmed: [...unconfirmed].filter((h) => !confirmed.has(h)).sort()
+	};
+}
+/** The system resolver: what the server's own clients would be told. */
+const systemLookup = async (host) => {
+	return (await (0, node_dns_promises.lookup)(host, { all: true })).map((a) => a.address);
+};
+/** Hosts that do not resolve to the stage's server. */
+var HostNotPointingAtServer = class extends require_errors.GkmError {
+	stage;
+	hosts;
+	expected;
+	fix;
+	constructor(stage, hosts, expected, fix) {
+		const want = expected.ipv6 ? `${expected.ipv4} (and ${expected.ipv6})` : expected.ipv4;
+		const lines = hosts.map((h) => `  - ${h.host} → ${h.resolved.length > 0 ? h.resolved.join(", ") : `nothing${h.error ? ` (${h.error})` : ""}`}, expected ${want}`);
+		super(`${hosts.length === 1 ? "A host" : `${hosts.length} hosts`} of '${stage}' do${hosts.length === 1 ? "es" : ""} not resolve to its server, so a certificate for ${hosts.length === 1 ? "it" : "them"} cannot be issued:\n${lines.join("\n")}\n${fix}\nRecords can take a few minutes to propagate. With a CDN or proxy in front of the server, pass --skip-dns.`);
+		this.stage = stage;
+		this.hosts = hosts;
+		this.expected = expected;
+		this.fix = fix;
+		this.name = "HostNotPointingAtServer";
+	}
+};
+/**
+* Every host resolved: each must resolve to the server's IPv4 address and to
+* nothing but the server's addresses.
+*
+* @throws {HostNotPointingAtServer} naming every host that does not
+*/
+async function checkStackDns(input) {
+	const lookup = input.lookup ?? systemLookup;
+	const { server } = input;
+	const ours = new Set([server.ipv4, server.ipv6].filter(Boolean).map((a) => a.toLowerCase()));
+	const bad = [];
+	const ok = [];
+	for (const host of input.hosts) {
+		let resolved;
+		try {
+			resolved = [...new Set(await lookup(host))];
+		} catch (error) {
+			const code = error && typeof error === "object" && "code" in error ? String(error.code) : error instanceof Error ? error.message : String(error);
+			bad.push({
+				host,
+				resolved: [],
+				error: code
+			});
+			continue;
+		}
+		if (resolved.some((a) => a.toLowerCase() === server.ipv4.toLowerCase()) && resolved.every((a) => ours.has(a.toLowerCase()))) ok.push(host);
+		else bad.push({
+			host,
+			resolved
+		});
+	}
+	if (bad.length > 0) throw new HostNotPointingAtServer(input.stage, bad, {
+		ipv4: server.ipv4,
+		...server.ipv6 ? { ipv6: server.ipv6 } : {}
+	}, dnsFix(input, bad));
+	return ok;
+}
+/** How to fix it: the deploy, or the records to create by hand. */
+function dnsFix(input, bad) {
+	const hosts = bad.map((h) => h.host);
+	let plan;
+	try {
+		plan = planStackDns({
+			stage: input.stage,
+			hosts,
+			server: input.server,
+			dns: input.dns
+		});
+	} catch {
+		plan = {
+			stage: input.stage,
+			server: input.server,
+			domains: [],
+			uncovered: hosts
+		};
+	}
+	const automatic = plan.domains.filter((d) => d.provider !== "manual");
+	const byHand = [...plan.domains.filter((d) => d.provider === "manual").flatMap((d) => d.records.map(describe)), ...plan.uncovered.flatMap((host) => [`${host.padEnd(32)} A     ${input.server.ipv4}`, ...input.server.ipv6 ? [`${host.padEnd(32)} AAAA  ${input.server.ipv6}`] : []])];
+	const lines = [];
+	if (automatic.length > 0) lines.push(`Fix: gkm deploy --stage ${input.stage} writes the records for ${automatic.map((d) => d.domain).join(", ")} through their provider (--dry-run shows them first).`);
+	if (byHand.length > 0) lines.push(`${automatic.length > 0 ? "And create" : "Fix: create"} these records at the DNS host:`, ...byHand.map((line) => `    ${line}`));
+	return lines.join("\n");
+}
+/** The environment variable each token-authenticated provider reads. */
+const DNS_TOKEN_KEYS = {
+	godaddy: "GODADDY_API_TOKEN",
+	hostinger: "HOSTINGER_API_TOKEN"
+};
+/**
+* A domain whose records the deploy writes, and no token to write them with.
+* Raised before anything is built, started or written.
+*/
+var DnsCredentialMissing = class extends require_errors.GkmError {
+	stage;
+	domain;
+	provider;
+	key;
+	constructor(stage, domain, provider, key) {
+		super(`'${stage}''s hosts are under ${domain}, whose DNS is ${provider}'s, and the deploy writes their records — but ${key} is not set. In CI, add ${key} as a secret on the '${stage}' GitHub environment and pass it to the step that writes the records: env: { ${key}: \${{ secrets.${key} }} }. On this machine, export ${key} or run gkm login --provider ${provider}. With a CDN or proxy in front of the server, pass --skip-dns.`);
+		this.stage = stage;
+		this.domain = domain;
+		this.provider = provider;
+		this.key = key;
+		this.name = "DnsCredentialMissing";
+	}
+};
+/**
+* The `dns` domain a stage's own domain (`domains.<stage>`) is under — where
+* its hosts' records go — or none.
+*/
+function stageDnsDomains(stage, domains, dns) {
+	const own = domains?.[stage];
+	if (!own || !dns || isLocalHost(own)) return [];
+	const normalized = require_seeds.normalizeDnsConfig(dns);
+	const root = require_seeds.findRootDomain(own.toLowerCase(), normalized);
+	return root ? [{
+		domain: root,
+		config: normalized[root]
+	}] : [];
+}
+/**
+* Each token the domains' providers need, from `credentials` — `manual`,
+* Route53 (the AWS SDK's own chain) and a provider object need none.
+*
+* @throws {DnsCredentialMissing} naming the first domain with no token
+*/
+async function dnsCredentials(stage, domains, credentials) {
+	const found = {};
+	for (const { domain, config } of domains) {
+		const provider = config.provider;
+		if (provider !== "godaddy" && provider !== "hostinger") continue;
+		if (found[provider]) continue;
+		const token = await credentials.get({ kind: provider });
+		if (!token?.token) throw new DnsCredentialMissing(stage, domain, provider, DNS_TOKEN_KEYS[provider]);
+		found[provider] = token;
+	}
+	return found;
+}
+/**
+* A stage's DNS, as every deploy runs it: the
+* stage's own hosts planned, written through each domain's provider where
+* they differ, and read back from it. Only A, AAAA and CNAME records of
+* those names are touched; nothing is a wildcard, and no other name is read,
+* written or deleted. What no provider confirms — a `manual` domain, a host
+* under no domain in `dns`, a key that cannot read — is resolved publicly.
+* A dry run prints the plan and writes nothing.
+*
+* @throws {DnsCredentialMissing} before anything is read or written
+* @throws {DnsRecordsNotConfirmed} when a written record does not read back
+* @throws {HostNotPointingAtServer} when a resolved host is not the server
+*/
+async function stageDns(input) {
+	const { stage, server } = input;
+	const log = input.log ?? ((line) => console.log(line));
+	const plan = planStackDns({
+		stage,
+		hosts: input.hosts,
+		server,
+		dns: input.dns
+	});
+	const tokens = await dnsCredentials(stage, plan.domains.map(({ domain, config }) => ({
+		domain,
+		config
+	})), input.credentials);
+	const applied = !input.dns ? {
+		changes: [],
+		confirmed: [],
+		unconfirmed: [...plan.uncovered]
+	} : await settleStackDns(plan, {
+		...input.dryRun ? { dryRun: true } : { confirm: true },
+		log,
+		credentials: {
+			...input.godaddy ?? {},
+			...tokens.godaddy ? { credential: tokens.godaddy } : {},
+			log
+		},
+		...tokens.hostinger ? { hostinger: tokens.hostinger } : {},
+		...input.providerFor ? { providerFor: input.providerFor } : {}
+	});
+	let resolved = [];
+	if (applied.unconfirmed.length > 0) resolved = await checkStackDns({
+		stage,
+		hosts: applied.unconfirmed,
+		server,
+		dns: input.dns,
+		...input.lookup ? { lookup: input.lookup } : {}
+	});
+	return {
+		plan,
+		changes: applied.changes,
+		confirmed: applied.confirmed,
+		resolved
+	};
+}
+//#endregion
+Object.defineProperty(exports, "HostNotPointingAtServer", {
+	enumerable: true,
+	get: function() {
+		return HostNotPointingAtServer;
+	}
+});
+Object.defineProperty(exports, "dnsCredentials", {
+	enumerable: true,
+	get: function() {
+		return dnsCredentials;
+	}
+});
+Object.defineProperty(exports, "isLocalHost", {
+	enumerable: true,
+	get: function() {
+		return isLocalHost;
+	}
+});
+Object.defineProperty(exports, "requiredServerAddress", {
+	enumerable: true,
+	get: function() {
+		return requiredServerAddress;
+	}
+});
+Object.defineProperty(exports, "serverAddressHint", {
+	enumerable: true,
+	get: function() {
+		return serverAddressHint;
+	}
+});
+Object.defineProperty(exports, "stackHosts", {
+	enumerable: true,
+	get: function() {
+		return stackHosts;
+	}
+});
+Object.defineProperty(exports, "stageDns", {
+	enumerable: true,
+	get: function() {
+		return stageDns;
+	}
+});
+Object.defineProperty(exports, "stageDnsDomains", {
+	enumerable: true,
+	get: function() {
+		return stageDnsDomains;
+	}
+});
+Object.defineProperty(exports, "systemLookup", {
+	enumerable: true,
+	get: function() {
+		return systemLookup;
+	}
+});
+
+//# sourceMappingURL=dns-Bmk7P9c2.cjs.map