ninepm 0.72.0 → 0.79.0

package/dist/index.js

@@ -13,7 +13,9 @@ import { Agent, fetch as undiciFetch } from "undici";
 import { MAX_DEPLOY_DESCRIPTION_LENGTH, normalizeDeployDescription } from "./deploy-description.js";
 import { managedHostnamesIn, siblingCallWarning, siblingsOf } from "./sibling-hostnames.js";
 import { MAX_STATIC_ASSET_FILE_BYTES, MAX_WORKER_ENTRY_COMPRESSED_BYTES, MAX_WORKER_SCRIPT_COMPRESSED_BYTES, WORKER_ENTRY_COMPRESSED_WARN_BYTES, assetFileTooLargeMessage, formatMebibytes, formatMegabytes, oversizedAssets, workerBundleNearLimitMessage, workerBundleTooLargeMessage, workerEntryNearLimitMessage, workerEntryTooLargeMessage, } from "./deploy-limits.js";
-import { guessZoneApex, relativeRecordName } from "./dns-host.js";
+import { guessZoneApex, relativeRecordName, zoneApexFor } from "./dns-host.js";
+import { dnsProviderProfile, recordAtProvider } from "./dns-providers.js";
+import { cacheMinutes, deriveDomainStatus, domainRecordStatuses, showsUseWww, } from "./domain-state.js";
 import { buildFileManifest, readManifestFile } from "./manifest.js";
 import { NO_PUBLIC_ASSETS, normalizeAssetsDirectory, privateLookingPaths, publicAssetPath } from "./public-assets.js";
 import { API_KEY_HELP, API_URL_HELP, CLI_CLIENT_ID, DEFAULT_API_URL, reportCliError } from "./cli-config.js";
@@ -50,7 +52,7 @@ export function deployDatabaseClause(databases) {
     const listed = databases.map((database) => (database.name ? `${database.bindingName}:${database.name}` : database.bindingName)).join(", ");
     return `${databases.length === 1 ? "database" : "databases"} ${listed}`;
 }
-export const CLI_VERSION = "0.72.0";
+export const CLI_VERSION = "0.79.0";
 const PUBLIC_DASHBOARD_URL = "https://9pm.ai/dashboard";
 const TOKEN_SERVICE = "9pm";
 const TOKEN_ACCOUNT = "default";
@@ -2917,7 +2919,7 @@ export function parseArgs(argv) {
         options.runtime !== "container") {
         throw new Error("--always-on, --volume, --allow-data-wipe, --allow-namespace-reset, --cpus, and --memory require --runtime container.");
     }
-    return { kind: "deploy", options };
+    return { kind: "deploy", options, apiUrlFrom: apiUrlSource(flags) };
 }
 function parseDeleteArgs(argv) {
     const flags = parseFlags(argv);
@@ -3218,91 +3220,53 @@ async function runDeploymentsCommand(command) {
     });
     console.log(`Deleted deployment ${result.deleted}.`);
 }
-// The server has no field for an expired trace: it marks one by this exact provisioningError
-// (CUSTOM_DOMAIN_EXPIRED_MESSAGE in src/server/routes/shared.ts; a test holds the two equal).
-export const CUSTOM_DOMAIN_EXPIRED_TEXT = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
+// `9pm domains` (#2000): custom domains on the existing REST API. The state, reason and next
+// step come from the server when it sends them (#1994); against an older server they are
+// derived here from the same shared definition, so both paths agree.
+export { CUSTOM_DOMAIN_EXPIRED_TEXT, deriveDomainState, deriveDomainStatus, domainRecordStatuses, } from "./domain-state.js";
 export const DOMAIN_WAIT_EXIT = { live: 0, ownerAction: 10, platform: 11, failed: 20 };
 function normalizeDnsName(value) {
     return value.trim().toLowerCase().replace(/\.$/, "");
 }
-// The value the server's DNS check compares against: TXT verbatim, names lowercased without a root dot.
-function checkedRecordValue(type, value) {
-    return type === "TXT" ? value : normalizeDnsName(value);
-}
-export function domainRecordStatuses(domain) {
-    const apex = guessZoneApex(domain.hostname);
-    return domain.dnsInstructions.map((instruction) => {
-        const type = instruction.type.toUpperCase();
-        const fqdn = normalizeDnsName(instruction.host);
-        const expected = checkedRecordValue(type, instruction.value);
-        // Matched on the expected value as well as host and type: the two TXT values of one name
-        // are separate rows, and keying on host and type alone gives both rows one verdict (#1986).
-        const seen = domain.dnsCheck?.records.find((entry) => entry.type.toUpperCase() === type && normalizeDnsName(entry.host) === fqdn && entry.expected === expected);
-        const atApex = type === "CNAME" && fqdn === apex;
-        const check = domainRecordCheck(seen, atApex);
-        return {
-            type,
-            name: relativeRecordName(fqdn, apex),
-            fqdn,
-            expected: instruction.value,
-            current: seen ? seen.current : null,
-            ok: check === "found" ? true : check === "missing" || check === "different" ? false : null,
-            check,
-            apex: atApex,
-            optional: instruction.optional === true,
-        };
+// The provider fields are an enrichment: anything malformed in them falls back to the record
+// as the server stored it rather than failing the whole status.
+function recordsAtProvider(records, profile) {
+    return records.map((record) => {
+        try {
+            const at = recordAtProvider({ type: record.type, name: record.name, value: record.expected, apex: record.apex }, profile);
+            return { ...record, typeAtProvider: at.type, nameAtProvider: at.name, valueAtProvider: at.value };
+        }
+        catch {
+            return { ...record, typeAtProvider: record.type, nameAtProvider: record.name, valueAtProvider: record.expected };
+        }
     });
 }
-const IP_ADDRESS = /^(\d{1,3}(\.\d{1,3}){3}|[0-9a-f:]*:[0-9a-f:.]+)$/i;
-// The server looks a CNAME up and, finding none, falls back to the name's A records. At the
-// zone root that is exactly what a correct ALIAS/ANAME or flattened CNAME answers: addresses,
-// never the target name. So addresses at the apex are not evidence of a wrong record; they
-// cannot be compared from outside at all.
-function domainRecordCheck(seen, atApex) {
-    if (!seen)
-        return "not_checked";
-    if (seen.matches)
-        return "found";
-    if (seen.current.length === 0)
-        return "missing";
-    if (atApex && seen.current.every((value) => IP_ADDRESS.test(value.trim())))
-        return "apex_addresses";
-    return "different";
-}
-export function deriveDomainState(domain, records = domainRecordStatuses(domain)) {
-    if (domain.provisioningError === CUSTOM_DOMAIN_EXPIRED_TEXT)
-        return "expired";
-    if (domain.routingStatus === "failed" || domain.tlsStatus === "failed" || domain.provisioningError)
-        return "failed";
-    if (domain.routingStatus === "active" && domain.tlsStatus === "active")
-        return "live";
-    const required = records.filter((record) => !record.optional);
-    if (required.some((record) => record.ok === false))
-        return "waiting_for_dns";
-    const routingActive = domain.routingStatus === "active";
-    // An apex answering with addresses defers to the platform's own routing check: active means
-    // it found the record, pending means it has not yet.
-    const unproven = required.some((record) => record.check === "not_checked" || (record.check === "apex_addresses" && !routingActive));
-    if (unproven || (!domain.dnsCheck && required.length === 0)) {
-        // Routing still pending is the platform's own evidence that it has not seen the records.
-        return routingActive ? "dns_unverified" : "waiting_for_dns";
-    }
-    return "issuing_certificate";
+function stringOrNull(value) {
+    return typeof value === "string" && value !== "" ? value : null;
 }
 export function domainStatusJson(domain, app, checkedAt) {
-    const records = domainRecordStatuses(domain);
+    const providerId = domain.dnsCheck?.provider ? stringOrNull(domain.dnsCheck.providerId) : null;
+    const records = recordsAtProvider(domainRecordStatuses(domain), dnsProviderProfile(providerId));
+    const derived = deriveDomainStatus(domain);
+    // The server's own status wins when it sent one; it is computed from the same definition.
+    const fromServer = typeof domain.state === "string" && domain.state !== "";
     return {
         hostname: domain.hostname,
         app: domain.app?.slug ?? app,
-        state: deriveDomainState(domain, records),
+        state: fromServer ? domain.state : derived.state,
         routing: domain.routingStatus,
         tls: domain.tlsStatus,
         provider: domain.dnsCheck?.provider ?? null,
+        providerId,
         nameservers: domain.dnsCheck?.nameservers ?? [],
+        zone: stringOrNull(domain.dnsCheck?.zone),
         records,
+        advisories: (domain.dnsCheck?.advisories ?? []).map(({ code, message }) => ({ code, message })),
         error: domain.provisioningError,
         expiresAt: domain.expiresAt ?? domain.expireAfter ?? null,
         checkedAt,
+        reason: fromServer ? (domain.reason ?? null) : derived.reason,
+        next: fromServer ? (domain.next ?? derived.next) : derived.next,
     };
 }
 const DOMAIN_STATE_LABELS = {
@@ -3313,33 +3277,164 @@ const DOMAIN_STATE_LABELS = {
     failed: "failed",
     expired: "expired",
 };
+// A state newer than this CLI is printed as the server named it rather than guessed at.
 export function domainStateLabel(state) {
-    return DOMAIN_STATE_LABELS[state];
+    return Object.hasOwn(DOMAIN_STATE_LABELS, state) ? DOMAIN_STATE_LABELS[state] : state;
+}
+// What `wait` exits with once it stops polling. Who acts next decides between 10 and 11, so a
+// CAA record blocking the certificate (every record found, but the owner must change CAA) exits
+// 10, and a state this CLI does not know is still mapped by who the server says acts.
+export function domainWaitExitCode(status) {
+    if (status.state === "live")
+        return DOMAIN_WAIT_EXIT.live;
+    if (status.state === "failed" || status.state === "expired")
+        return DOMAIN_WAIT_EXIT.failed;
+    if (status.state === "waiting_for_dns" || status.state === "dns_unverified")
+        return DOMAIN_WAIT_EXIT.ownerAction;
+    return status.next?.who === "owner" ? DOMAIN_WAIT_EXIT.ownerAction : DOMAIN_WAIT_EXIT.platform;
+}
+// The CAA advice follows who controls the deciding record: the owner's own zone, a CNAME
+// target only its operator can change, or a name the resolver did not attribute.
+function caaAdviceLines(next) {
+    const caa = next.caa;
+    if (!caa)
+        return [];
+    const issuers = caa.platformIssuers.join(", ");
+    if (next.action === "ask_caa_controller" && caa.via) {
+        return [
+            `A CAA record at ${caa.recordName}, which ${caa.via} points to, stops the certificate from being issued.`,
+            `Whoever runs ${caa.recordName} controls it, not your DNS: ask them to allow one of ${issuers}, or stop pointing ${caa.via} at it.`,
+        ];
+    }
+    if (next.action === "check_caa") {
+        return [
+            `A CAA record found when looking up ${caa.recordName} stops the certificate from being issued.`,
+            `If ${caa.recordName} is in your own DNS, add an issue entry there for one of ${issuers}. If it points to another service, that service controls it.`,
+        ];
+    }
+    const example = next.records?.[0];
+    return [
+        `A CAA record at ${caa.recordName} stops the certificate from being issued.`,
+        `Add an issue entry there for one of ${issuers}${example ? ` (for example: ${example.type} ${example.value})` : ""}. Your existing entries can stay.`,
+    ];
+}
+function providerMessageLine(reason) {
+    const message = reason?.providerMessage;
+    if (!message)
+        return null;
+    // Only the certificate's own validation errors are the certificate authority's; anything else
+    // (the hostname's verification note, or a source this CLI does not know) is worded neutrally.
+    const who = message.source === "certificate_authority" ? "The certificate authority" : "Our provider";
+    return `${who} reported (${message.seenAt}): ${message.text}`;
 }
 const TXT_KEEP_OTHERS = "add this value as its own TXT record; other TXT values can stay";
+// The server's next background check as "HH:MM UTC" (UTC so the line reads the same on any
+// machine); null when there is none or it is not a date, so no time is promised from it.
+export function nextCheckText(nextCheckAt) {
+    if (typeof nextCheckAt !== "string" || nextCheckAt === "")
+        return null;
+    const at = new Date(nextCheckAt);
+    return Number.isNaN(at.getTime()) ? null : `${at.toISOString().slice(11, 16)} UTC`;
+}
+// "up to N min" for a cache's time left, or nothing when the resolver did not say.
+function forUpTo(ttlSeconds) {
+    return typeof ttlSeconds === "number" ? ` for up to ${cacheMinutes(ttlSeconds)} min` : "";
+}
+function answerText(current) {
+    return current.length > 0 ? current.join(", ") : "nothing";
+}
 function recordStateText(record, routing) {
     if (record.ok === true)
         return "found";
+    if (record.check === "resolvers_disagree") {
+        // Two caches that disagree prove neither answer current: no "found", no "replace", and neither answer called old.
+        const answers = record.resolvers ?? [];
+        const seeing = answers.filter((answer) => answer.matches).map((answer) => answer.resolver);
+        const others = answers
+            .filter((answer) => !answer.matches)
+            .map((answer) => `${answer.resolver} sees ${answerText(answer.current)}${typeof answer.ttlSeconds === "number" ? ` (and may keep that answer${forUpTo(answer.ttlSeconds)})` : ""}`);
+        return `public resolvers disagree: ${seeing.join(" and ")} ${seeing.length > 1 ? "see" : "sees"} the value shown, ${others.join("; ")}. That usually means a recent change is still spreading; make sure your DNS host shows the value shown, then check again`;
+    }
+    if (record.check === "doubled") {
+        // The same name the NAME column shows, so the hint never contradicts the host's convention.
+        const name = record.nameAtProvider ?? record.name;
+        return `found at ${record.doubledAt}: your DNS provider added the domain twice; ${name === "" ? "leave the Host field empty" : `enter only ${name}`}`;
+    }
     // An optional record never holds the domain back, so its state would only be noise.
     if (record.optional)
         return "optional, only needed if the CNAME cannot be pointed first";
     if (record.check === "apex_addresses") {
         return routing === "active"
             ? "looks connected: the root answers with addresses, as an ALIAS does, and routing is active"
-            : `answers with addresses (${(record.current ?? []).join(", ")}); an ALIAS can't be verified from outside, so this waits on the platform's routing check`;
+            : // A parking page answers with addresses too, so nothing here says the record is right: the owner confirms it.
+                `answers with addresses (${(record.current ?? []).join(", ")}); an ALIAS can't be verified from outside, and a parking page answers with addresses too: make sure the ALIAS or ANAME record at the root points at the value shown. The platform's routing check confirms it`;
     }
     if (record.ok === null || record.current === null)
         return "not checked: couldn't read your DNS just now";
+    // TXT before wildcard: a name may hold several TXT values another certificate still needs, so a
+    // TXT value is always added beside them, never "changed", whatever answers at the name.
     if (record.type === "TXT") {
-        const now = record.current.length === 0 ? "not published yet" : `currently ${record.current.join(", ")}`;
+        const from = record.check === "wildcard" && record.wildcard ? ` (from the wildcard ${record.wildcard})` : "";
+        const now = record.current.length === 0 ? "not published yet" : `currently ${record.current.join(", ")}${from}`;
         return `${now}: ${TXT_KEEP_OTHERS}`;
     }
+    if (record.check === "wildcard") {
+        const name = record.nameAtProvider ?? record.name;
+        // A name holding a CNAME can hold nothing else, so an explicit record equal to the wildcard's answer is changed, not joined.
+        return `no ${record.type} record of its own yet: your DNS host's wildcard ${record.wildcard ?? ""} answers for it (${record.current.join(", ")}). Add one at ${name === "" ? "the root" : name} with the value shown; the wildcard can stay. If your DNS host already lists a record at this name, change that one instead`;
+    }
     if (record.current.length === 0)
         return "not published yet";
-    return `currently ${record.current.join(", ")}: point it at the value shown`;
-}
-function domainCommand(subcommand, app, hostname, owner) {
-    return `9pm domains ${subcommand} ${quoteSiteArg(app)} ${hostname}${owner ? ` --owner ${quoteSiteArg(owner)}` : ""}`;
+    // A changed record can keep its old answer in public caches for its TTL, which is said so the owner does not change it twice.
+    const recent = typeof record.ttlSeconds === "number" ? ` (if you changed it in the last ${cacheMinutes(record.ttlSeconds)} min, this may be the old answer still cached)` : "";
+    // Two resolvers can each hold a different old answer; both are shown, as neither is the expected value.
+    const shown = record.current.join(", ");
+    const others = (record.resolvers ?? []).filter((answer) => answer.current.join(", ") !== shown);
+    const also = others.map((answer) => `; ${answer.resolver} answers ${answerText(answer.current)}`).join("");
+    return `currently ${shown}${also}${recent}: point it at the value shown`;
+}
+// A printed command carries --owner and, when the destination is not the built-in default,
+// --api-url: pasted into a shell without NINEPM_API_URL it would otherwise act on production.
+// Never a token.
+function domainCommand(subcommand, app, hostname, options) {
+    const owner = options.owner ? ` --owner ${quoteSiteArg(options.owner)}` : "";
+    return `9pm domains ${subcommand} ${quoteSiteArg(app)} ${hostname}${owner}${apiUrlFlagFor(options.target)}`;
+}
+// Notes from src/shared/dns-providers.ts; only verified ones are printed.
+export const DNS_PROVIDER_NOTES = {
+    gandiLiveDns: "At Gandi, an ALIAS works only with LiveDNS, and no A or AAAA record may stay at @ beside it.",
+    hostingerCnameAtRoot: "At Hostinger, add the root record as a CNAME with name @: Hostinger shows it as ALIAS. A domain can have only one.",
+    // Unverified, so never printed; its text is here so a leak would show.
+    route53TxtQuotes: "In the Route 53 console, a TXT value may need to be entered in quotes.",
+};
+// A root domain at a DNS host that cannot point one at a hostname: what can stand in for the
+// root record, in the profile's order. Forwarding is text only, and unverified forwarding is
+// a possibility, never a step.
+function noApexLines(status, provider, fallbacks, options) {
+    const host = status.hostname;
+    const www = status.next?.hostname ?? `www.${host}`;
+    const lines = [`${provider} can't point a root domain like ${host} at another address. Connect ${www} instead: it works with an ordinary CNAME.`];
+    for (const fallback of fallbacks) {
+        if (fallback.kind === "use_www") {
+            lines.push(`  Add it: ${domainCommand("add", status.app, www, options)}`);
+        }
+        else if (fallback.kind === "provider_forwarding") {
+            if (!fallback.verified) {
+                lines.push(`  ${provider} may offer forwarding that sends ${host} to ${www}; we haven't confirmed it.`);
+            }
+            else {
+                lines.push(`  Then use ${provider}'s forwarding to send ${host} to https://${www}.${fallback.https === "yes" ? "" : ` We haven't confirmed that its forwarding works over HTTPS, so open https://${host} once it is set up to check.`}`);
+            }
+        }
+        else if (fallback.kind === "aws_redirect") {
+            lines.push(`  For ${host} itself, you can set up a redirect to ${www} inside AWS yourself, for example an S3 redirect bucket behind CloudFront.`);
+        }
+        else {
+            lines.push("  Or move your DNS hosting to a provider that supports ALIAS records at the root. Copy every existing record first, MX and TXT especially, or your email stops working.");
+            lines.push("  If DNSSEC is on at your registrar (it holds a DS record for the domain), turn it off first and wait for that to clear before you change the nameservers: otherwise the whole domain, email included, stops resolving for many visitors.");
+        }
+    }
+    return lines;
 }
 function renderColumns(rows) {
     const widths = (rows[0] ?? []).map((_, column) => Math.max(...rows.map((row) => (row[column] ?? "").length)));
@@ -3356,58 +3451,133 @@ export function formatDomainStatus(status, options = {}) {
     }
     if (status.state === "expired") {
         lines.push(status.error ?? "This domain expired before its DNS records were published.");
-        lines.push(`Add it again: ${domainCommand("add", status.app, status.hostname, options.owner)}`);
+        lines.push(`Add it again: ${domainCommand("add", status.app, status.hostname, options)}`);
         return lines;
     }
     if (status.state === "failed" && status.error) {
         lines.push(status.error);
     }
-    const apex = guessZoneApex(status.hostname);
+    lines.push(...status.advisories.map((advisory) => advisory.message));
+    const apex = zoneApexFor(status.hostname, status.zone);
+    const atRoot = status.hostname.toLowerCase().replace(/\.$/, "") === apex;
+    // The profile is read only for a host the server named; an id without a name is not trusted.
+    const profile = status.provider ? dnsProviderProfile(status.providerId) : undefined;
+    const provider = status.provider ?? "";
+    // The same decision as the status: never the profile alone, which would say "connect www"
+    // over routing that is already active. The profile only supplies the stand-ins to list.
+    const useWwwFallbacks = atRoot && showsUseWww(status.next) ? (profile?.apex.support === "none" ? profile.apex.fallbacks : [{ kind: "use_www" }]) : undefined;
     if (status.records.length > 0) {
+        const elsewhere = "Changes made where you bought the domain won't take effect if that is another company.";
         lines.push(status.provider
-            ? `DNS for ${apex} is managed at ${status.provider}${status.nameservers.length > 0 ? ` (${status.nameservers.join(", ")})` : ""}. Add these records there:`
+            ? `Your DNS is managed at ${status.provider}${status.nameservers.length > 0 ? ` (${status.nameservers.join(", ")})` : ""}, where your domain's nameservers point: make these changes there. ${elsewhere}`
             : status.nameservers.length > 0
-                ? `DNS for ${apex} is served by ${status.nameservers.join(", ")}. Add these records there:`
-                : `Add these records where the DNS for ${apex} is managed:`);
-        lines.push("");
-        const rows = [
-            ["TYPE", "NAME", "VALUE", "STATE"],
-            ...status.records.map((record) => [record.apex ? "ALIAS" : record.type, record.name, record.expected, recordStateText(record, status.routing)]),
-        ];
-        lines.push(...renderColumns(rows).map((line) => `  ${line}`));
-        lines.push("");
-        if (status.records.some((record) => record.apex)) {
-            lines.push(`ALIAS at @: the root of ${apex} cannot hold a CNAME, so add an ALIAS or ANAME record there (or a CNAME your provider flattens), pointing at the value shown.`);
+                ? `Your DNS is served by ${status.nameservers.join(", ")}: make these changes at the company that runs them. ${elsewhere}`
+                : `Add these records where the DNS for ${apex} is hosted, which is where its nameservers point and may not be where you bought it:`);
+        for (const note of profile?.notes ?? []) {
+            const text = note.verified ? DNS_PROVIDER_NOTES[note.id] : undefined;
+            if (text)
+                lines.push(text);
+        }
+        const shown = useWwwFallbacks ? status.records.filter((record) => !record.apex) : status.records;
+        if (shown.length > 0) {
+            lines.push("");
+            const rows = [
+                ["TYPE", "NAME", "VALUE", "STATE"],
+                ...shown.map((record) => [
+                    // null: a root the host has no record type for, shown only once routing is already active.
+                    record.typeAtProvider ?? "-",
+                    record.nameAtProvider === "" ? "(leave empty)" : record.nameAtProvider,
+                    record.valueAtProvider,
+                    recordStateText(record, status.routing),
+                ]),
+            ];
+            lines.push(...renderColumns(rows).map((line) => `  ${line}`));
+            lines.push("");
+        }
+        if (useWwwFallbacks) {
+            lines.push(...noApexLines(status, status.provider ?? "Your DNS host", useWwwFallbacks, options));
+        }
+        else if (status.records.some((record) => record.apex)) {
+            const support = profile?.apex;
+            if (support?.support === "alias") {
+                lines.push(`${support.typeLabel} at the root: ${provider} uses an ${support.typeLabel} record there. ${support.hostField === "blank" ? "Leave the Host field empty" : "Enter @ as the Host"} and point it at the value shown.`);
+            }
+            else if (support?.support === "none") {
+                lines.push(`${provider} has no record type that can point a root domain at this value, but routing for ${status.hostname} is ${status.routing === "active" ? "already active" : "being checked by the platform"}: keep the record that serves it as it is.`);
+            }
+            else if (support?.support === "cname_flattening") {
+                lines.push(`CNAME at the root: ${provider} flattens a CNAME at the root automatically, so add it at @ pointing at the value shown.`);
+            }
+            else {
+                lines.push(`ALIAS at @: the root of ${apex} cannot hold a CNAME, so add an ALIAS or ANAME record there (or a CNAME your provider flattens), pointing at the value shown.`);
+                lines.push("If your DNS host has no ALIAS or ANAME record, don't put a CNAME at the root: it would conflict with your MX and TXT records. Connect www instead.");
+            }
+        }
+        // "Replace the record at @" would take MX and TXT with it: the root names the website record types and keeps the rest.
+        if (atRoot) {
+            lines.push(`Change only the website record for ${status.hostname} (A, AAAA, ALIAS/ANAME or CNAME). Keep every MX and TXT record: they carry your email and other verifications.`);
         }
         if (status.records.some((record) => !record.optional && record.check === "not_checked")) {
             lines.push("Couldn't check your DNS records just now, so their state is unknown. Make sure they are published as shown.");
         }
-        if (status.records.some((record) => record.name !== record.fqdn)) {
-            lines.push(`Enter the name as shown: most providers add ".${apex}" themselves. If yours asks for the full name, append ".${apex}".`);
+        if (shown.some((record) => record.nameAtProvider !== "" && record.name !== record.fqdn)) {
+            lines.push(profile?.appendsZone === true
+                ? `Enter the name as shown: ${provider} adds ".${apex}" itself, so typing the full name would double it.`
+                : `Enter the name as shown: most providers add ".${apex}" themselves. If yours asks for the full name, append ".${apex}".`);
         }
     }
+    const reported = providerMessageLine(status.reason);
+    if (reported)
+        lines.push(reported);
     if (status.state === "failed") {
-        lines.push(`Re-check: ${domainCommand("check", status.app, status.hostname, options.owner)}`);
-        lines.push(`Start over (the records may change): ${domainCommand("restart", status.app, status.hostname, options.owner)}`);
+        if (status.next.action === "contact_support") {
+            lines.push("This needs the platform's support to resolve; nothing in your DNS is known to fix it.");
+        }
+        lines.push(`Re-check: ${domainCommand("check", status.app, status.hostname, options)}`);
+        // Offered only where a new certificate attempt is the remedy; a restart never speeds anything up.
+        if (status.next.action === "start_over") {
+            lines.push(`Start over (the records may change): ${domainCommand("restart", status.app, status.hostname, options)}`);
+        }
         return lines;
     }
-    if (status.state === "issuing_certificate") {
+    // Waiting on this domain cannot finish it: the next step is a different hostname, printed above.
+    if (status.next?.action === "use_www")
+        return lines;
+    const caaLines = caaAdviceLines(status.next);
+    if (caaLines.length > 0) {
+        lines.push(...caaLines);
+    }
+    else if (status.state === "issuing_certificate") {
         lines.push("Every required record is published. The platform finishes on its own, usually within minutes.");
+        const nextCheck = nextCheckText(status.next?.nextCheckAt);
+        // A restart is not offered here: nothing measured says it speeds issuance up.
+        if (nextCheck)
+            lines.push(`The platform checks it again around ${nextCheck} on its own; nothing needs restarting.`);
     }
-    lines.push(`Then run: ${domainCommand("wait", status.app, status.hostname, options.owner)}`);
+    lines.push(`Then run: ${domainCommand("wait", status.app, status.hostname, options)}`);
     return lines;
 }
 // What a timed-out wait says. "Missing" is claimed only for a record the check actually saw
 // absent or different; a record nobody could read is reported as unchecked, whatever the
 // routing status, because telling the owner to publish what may already be there misleads.
 export function domainWaitTimeoutMessage(status) {
+    if (status.next?.action === "use_www") {
+        return `Stopped waiting: no record at the root can finish ${status.hostname} at its DNS host. Connect ${status.next.hostname ?? `www.${status.hostname}`} as shown above, then wait on that instead.`;
+    }
+    if (status.next.caa) {
+        return "Timed out: a CAA record stops the certificate from being issued. Change it as described above, then wait again.";
+    }
     if (status.state === "issuing_certificate") {
-        return "Timed out: the records are published and the platform is still finishing. Wait again; nothing needs changing.";
+        const nextCheck = nextCheckText(status.next?.nextCheckAt);
+        return `Timed out: the records are published and the platform is still finishing. Wait again; nothing needs changing.${nextCheck ? ` Its next automatic check is around ${nextCheck}.` : ""}`;
     }
     const required = status.records.filter((record) => !record.optional);
     if (required.some((record) => record.ok === false)) {
         return "Timed out: records above are still missing. Publish them, then wait again.";
     }
+    if (required.some((record) => record.check === "resolvers_disagree")) {
+        return "Timed out: public resolvers still disagree about a record above. Make sure your DNS host shows the value shown, then wait again.";
+    }
     return "Timed out: the DNS records could not be checked. Make sure they are published as shown, then wait again.";
 }
 export function formatDomainsList(statuses) {
@@ -3513,6 +3683,72 @@ export async function removeDomain(options) {
     });
     return result.domain;
 }
+// The domains read is a reconcile plus a DNS lookup per record, so it can be slow; the deploy
+// has already succeeded and must not wait on it for longer than this.
+export const DEPLOY_DOMAINS_TIMEOUT_MS = 4500;
+// `null` when the read failed or timed out: unknown, which the caller must not print as
+// "this app has no custom domains".
+export async function deployCustomDomainStatuses(options) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            resolve(null);
+        }, options.timeoutMs ?? DEPLOY_DOMAINS_TIMEOUT_MS);
+    });
+    // By id, not slug: the id names this deploy's app whatever owner it belongs to, so no
+    // `?owner=` is needed to disambiguate. One chain, one catch: the request, the body and the
+    // conversion of every entry. Anything that throws - a malformed entry included - is an
+    // unknown answer, never a failed deploy.
+    const read = (async () => {
+        const result = await domainsRequest(options, `/v1/sites/${encodeURIComponent(options.projectId)}/domains`, {
+            method: "GET",
+            signal: controller.signal,
+        });
+        if (!Array.isArray(result?.domains) || !result.domains.every(isCliDomainShape))
+            return null;
+        const checkedAt = (options.now ?? (() => new Date()))().toISOString();
+        return result.domains.map((domain) => domainStatusJson(domain, options.slug, checkedAt));
+    })().catch(() => null);
+    try {
+        return await Promise.race([read, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// The fields the state derivation reads. An entry without them cannot be classified, and a
+// guess would be exactly the "live" or "missing" claim the deploy lines must not make.
+function isCliDomainShape(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const domain = value;
+    return (typeof domain.hostname === "string" &&
+        domain.hostname.length > 0 &&
+        typeof domain.routingStatus === "string" &&
+        typeof domain.tlsStatus === "string" &&
+        Array.isArray(domain.dnsInstructions) &&
+        (domain.provisioningError === null || domain.provisioningError === undefined || typeof domain.provisioningError === "string"));
+}
+// `state` is the shared definition's (src/shared/domain-state.ts), sent by the server or derived
+// from it by domainStatusJson: `live` needs routing and TLS both active. Every other state,
+// including one newer than this CLI, is named as it is, never rounded up to live or down to
+// "missing".
+export function deployCustomDomainLines(statuses, slug, owner, target) {
+    const apiUrl = apiUrlFlagFor(target);
+    if (statuses === null) {
+        return [
+            `Couldn't check this app's custom domains just now. List them: 9pm domains list ${quoteSiteArg(slug)}${owner ? ` --owner ${quoteSiteArg(owner)}` : ""}${apiUrl}`,
+        ];
+    }
+    return statuses.map((status) => {
+        if (status.state === "live")
+            return `Also serving at https://${status.hostname}`;
+        const notLive = status.state === "failed" || status.state === "expired" ? "is not live" : "is not live yet";
+        return `Custom domain ${status.hostname} ${notLive} (${domainStateLabel(status.state)}). Check it: ${domainCommand("status", slug, status.hostname, { ...(owner ? { owner } : {}), ...(target ? { target } : {}) })}`;
+    });
+}
 // Polls the read-only list, which reconciles pending domains on every read, so waiting needs
 // only access to the app. A failed read that is not the caller's fault (network, 5xx) is
 // retried until the deadline; a refusal (auth, not found) ends the wait at once.
@@ -3530,6 +3766,9 @@ export async function waitForDomain(options) {
                 return { status, exitCode: DOMAIN_WAIT_EXIT.live, timedOut: false };
             if (status.state === "failed" || status.state === "expired")
                 return { status, exitCode: DOMAIN_WAIT_EXIT.failed, timedOut: false };
+            // Nothing the owner can publish finishes this hostname, so polling until the timeout would only delay saying so.
+            if (status.next?.action === "use_www")
+                return { status, exitCode: DOMAIN_WAIT_EXIT.ownerAction, timedOut: false };
         }
         catch (error) {
             const transient = !(error instanceof DomainsApiError) || error.status >= 500;
@@ -3541,10 +3780,9 @@ export async function waitForDomain(options) {
         if (remaining <= 0) {
             if (!last)
                 throw new Error(`Timed out before ${options.hostname} could be read.`);
-            // Only a proven issuing_certificate is the platform's to finish; records that could not be
-            // checked are the owner's to confirm, so they share the owner-action code.
-            const exitCode = last.state === "issuing_certificate" ? DOMAIN_WAIT_EXIT.platform : DOMAIN_WAIT_EXIT.ownerAction;
-            return { status: last, exitCode, timedOut: true };
+            // Only a proven issuing_certificate with nothing left for the owner is the platform's to
+            // finish; records that could not be checked are the owner's to confirm.
+            return { status: last, exitCode: domainWaitExitCode(last), timedOut: true };
         }
         await sleepFn(Math.min(options.intervalMs, remaining));
     }
@@ -3574,7 +3812,7 @@ const DOMAINS_USAGE = {
     status: "9pm domains status <app> <hostname> [--owner <organisation>] [--json]",
     check: "9pm domains check <app> <hostname> [--owner <organisation>] [--json]",
     wait: "9pm domains wait <app> <hostname> [--timeout 30m] [--interval 20s] [--owner <organisation>] [--json]",
-    restart: "9pm domains restart <app> <hostname> [--owner <organisation>]",
+    restart: "9pm domains restart <app> <hostname> [--owner <organisation>]  (for a failed certificate; the record values may change)",
     remove: "9pm domains remove <app> <hostname> --confirm <hostname> [--owner <organisation>]",
 };
 function parseDomainsArgs(argv) {
@@ -3593,6 +3831,7 @@ function parseDomainsArgs(argv) {
     const withBase = (action) => ({
         kind: "domains",
         ...readBaseApiOptions(flags),
+        apiUrlFrom: apiUrlSource(flags),
         ...(owner ? { owner } : {}),
         action,
     });
@@ -3627,14 +3866,14 @@ function parseDomainsArgs(argv) {
     }
     return withBase({ kind: "remove", site, hostname });
 }
-function printDomainStatus(status, json, owner, heading) {
+function printDomainStatus(status, json, options, heading) {
     if (json) {
         console.log(JSON.stringify(status, null, 2));
         return;
     }
     if (heading)
         console.log(heading);
-    for (const line of formatDomainStatus(status, owner ? { owner } : {}))
+    for (const line of formatDomainStatus(status, options))
         console.log(line);
 }
 function instructionLines(instructions, hostname) {
@@ -3644,6 +3883,10 @@ function instructionLines(instructions, hostname) {
 async function runDomainsCommand(command) {
     const action = command.action;
     const base = { apiUrl: command.apiUrl, token: command.token, ...(command.owner ? { owner: command.owner } : {}) };
+    const format = {
+        ...(command.owner ? { owner: command.owner } : {}),
+        target: { apiUrl: command.apiUrl, apiUrlFrom: command.apiUrlFrom },
+    };
     if (action.kind === "list") {
         const statuses = await listDomainStatuses({ ...base, ...(action.site ? { site: action.site } : {}) });
         if (action.json) {
@@ -3662,19 +3905,19 @@ async function runDomainsCommand(command) {
         // says whether a record the owner already has (a wildcard, an old CNAME) is in the way.
         const status = await getDomainStatus({ ...target, hostname }).catch(() => added ? domainStatusJson(added, action.site, new Date().toISOString()) : null);
         if (!status) {
-            console.log(`Added ${hostname} to ${action.site}. See its records: ${domainCommand("status", action.site, hostname, command.owner)}`);
+            console.log(`Added ${hostname} to ${action.site}. See its records: ${domainCommand("status", action.site, hostname, format)}`);
             return;
         }
-        printDomainStatus(status, action.json, command.owner, action.json ? undefined : `Added ${hostname} to ${action.site}.`);
+        printDomainStatus(status, action.json, format, action.json ? undefined : `Added ${hostname} to ${action.site}.`);
         return;
     }
     if (action.kind === "status") {
-        printDomainStatus(await getDomainStatus(target), action.json, command.owner);
+        printDomainStatus(await getDomainStatus(target), action.json, format);
         return;
     }
     if (action.kind === "check") {
         await recheckDomain(target);
-        printDomainStatus(await getDomainStatus(target), action.json, command.owner);
+        printDomainStatus(await getDomainStatus(target), action.json, format);
         return;
     }
     if (action.kind === "wait") {
@@ -3695,9 +3938,9 @@ async function runDomainsCommand(command) {
             console.log(JSON.stringify(result.status, null, 2));
         }
         else {
-            for (const line of formatDomainStatus(result.status, command.owner ? { owner: command.owner } : {}))
+            for (const line of formatDomainStatus(result.status, format))
                 console.log(line);
-            if (result.timedOut)
+            if (result.timedOut || result.status.next?.action === "use_www")
                 console.log(domainWaitTimeoutMessage(result.status));
         }
         process.exitCode = result.exitCode;
@@ -3715,7 +3958,7 @@ async function runDomainsCommand(command) {
             console.log("No record changed.");
         }
         const status = await getDomainStatus({ ...target, hostname: restarted.domain.hostname }).catch(() => domainStatusJson(restarted.domain, action.site, new Date().toISOString()));
-        for (const line of formatDomainStatus(status, command.owner ? { owner: command.owner } : {}))
+        for (const line of formatDomainStatus(status, format))
             console.log(line);
         return;
     }
@@ -5118,7 +5361,17 @@ async function main() {
             }
             const databaseClause = deployDatabaseClause(result.databases);
             const queued = result.deployment.status === "queued" || result.deployment.status === "publishing";
+            const domainStatuses = deployCustomDomainStatuses({
+                apiUrl: command.options.apiUrl,
+                token: command.options.token,
+                projectId: result.project.id,
+                slug: result.project.slug,
+            });
             console.log(`${queued ? "Queued" : "Deployed"} ${result.project.slug} -> ${result.url}`);
+            const target = { apiUrl: command.options.apiUrl, apiUrlFrom: command.apiUrlFrom };
+            for (const line of deployCustomDomainLines(await domainStatuses, result.project.slug, command.options.owner, target)) {
+                console.log(line);
+            }
             console.log(`Deployment ${result.deployment.id} ${result.containerImageBytes ? `uploaded ${formatBytesForCli(result.containerImageBytes)} image` : `uploaded ${result.uploaded} file(s)`}${databaseClause ? `, ${databaseClause}` : ""}.`);
             if (queued) {
                 console.log(`Status: ${result.deployment.status}. Run 9pm apps to check when it becomes active.`);
@@ -5330,6 +5583,9 @@ async function main() {
             });
             console.log(`Deleted ${deleted.slug}.`);
             console.log(`Removed ${deleted.workers} Worker(s), ${deleted.databases} database(s), ${deleted.files} file(s), ${deleted.customDomains} custom domain(s), ${deleted.containerImages ?? 0} container image(s), ${deleted.accessApps} access app(s), and ${deleted.serviceTokens} service token(s). Queued ${deleted.containerApplications ?? 0} container app(s) for teardown.`);
+            if (deleted.customDomainNames && deleted.customDomainNames.length > 0) {
+                console.log(`Removed custom domain(s): ${deleted.customDomainNames.join(", ")}.`);
+            }
             // #722: a partial external-cleanup failure never fails the delete, and used to be
             // silently discarded here — visible only in the raw JSON, if a caller happened to
             // read it. Surfacing it is the whole reason a human running this command manually
@@ -5460,6 +5716,16 @@ async function runSupportCommand(command) {
     });
     console.log("Support request sent. A human will reply to your account email.");
 }
+// ` --api-url <url>` for a printed command whenever the destination is not the built-in
+// default, so a line copied from a staging session cannot act on production; "" otherwise.
+export function apiUrlFlagFor(target) {
+    if (!target || target.apiUrlFrom === "default")
+        return "";
+    // A plain URL (scheme, host, port, path) has no shell-significant characters; anything
+    // else falls back to single quotes.
+    const url = /^[A-Za-z0-9._:/-]+$/.test(target.apiUrl) ? target.apiUrl : quoteSiteArg(target.apiUrl);
+    return ` --api-url ${url}`;
+}
 // The command line that repeats this one with --switch-mode. Rebuilt from the parsed
 // action rather than echoed from argv so a --token on the original line is never printed.
 // The destination is carried explicitly whenever it is not the built-in default: a line
@@ -5468,10 +5734,7 @@ async function runSupportCommand(command) {
 // no --owner (a site id or slug already names the app), so there is none to carry.
 export function accessSwitchModeCommand(action, target) {
     const site = quoteSiteArg(action.site);
-    // A plain URL (scheme, host, port, path) has no shell-significant characters; anything
-    // else falls back to single quotes.
-    const url = target && /^[A-Za-z0-9._:/-]+$/.test(target.apiUrl) ? target.apiUrl : target ? quoteSiteArg(target.apiUrl) : "";
-    const apiUrl = target && target.apiUrlFrom !== "default" ? ` --api-url ${url}` : "";
+    const apiUrl = apiUrlFlagFor(target);
     if (action.kind === "service-create") {
         const name = action.name ? ` --name ${quoteSiteArg(action.name)}` : "";
         const duration = action.duration ? ` --duration ${quoteSiteArg(action.duration)}` : "";
@@ -5721,7 +5984,7 @@ function printUsage() {
   9pm domains status <app> <hostname> [--json]     state and, per record, what DNS shows now
   9pm domains check <app> <hostname> [--json]      re-check now, then print the status
   9pm domains wait <app> <hostname> [--timeout 30m] [--interval 20s] [--json]
-  9pm domains restart <app> <hostname>             start validation over; record values may change
+  9pm domains restart <app> <hostname>             for a failed certificate only: start validation over; record values may change
   9pm domains remove <app> <hostname> --confirm <hostname>
   9pm access show <site>
   9pm access public <site> [--switch-mode]
@@ -5776,16 +6039,19 @@ Missing pages (static sites and --entry worker apps):
 Custom domains:
   Every domains command takes --owner <organisation> for an organisation's app. list, status and
   wait only read; add, check, restart and remove need the configure role on the app.
-  --json prints {hostname, app, state, routing, tls, provider, nameservers, records[{type, name,
-  fqdn, expected, current, ok, check, apex, optional}], error, expiresAt, checkedAt}. state is one
-  of live, waiting_for_dns, dns_unverified (routing is active but the records could not be
-  checked), issuing_certificate (every required record checked and found), failed, expired.
+  --json prints {hostname, app, state, reason, next, routing, tls, provider, nameservers,
+  records[{type, name, fqdn, expected, current, ok, check, apex, optional}], error, expiresAt,
+  checkedAt}. state is one of live, waiting_for_dns, dns_unverified (routing is active but the
+  records could not be checked), issuing_certificate (every required record checked and found),
+  failed, expired. reason says why (reason.providerMessage is the provider's own text, when it
+  reported any, and its source: certificate_authority or hostname); next says who acts next (owner or platform) and what to do.
   A record's name is relative to the zone (www, _acme-challenge.www, @). ok is null when the
   check cannot say: check is not_checked, or apex_addresses for a root record answering with
   addresses (a correct ALIAS does), which defers to the routing status.
-  wait exits 0 when live, 10 on timeout with records missing or unverified (the owner must act or
-  confirm), 11 on timeout with every record found (the platform is still finishing), 20 when the
-  domain failed or expired, and 1 on a usage, auth or API error.
+  wait exits 0 when live, 10 on timeout with something for the owner to do (records missing or
+  unverified, or a CAA record blocking the certificate), 11 on timeout with every record found and
+  nothing for the owner to do (the platform is still finishing), 20 when the domain failed or
+  expired, and 1 on a usage, auth or API error.
 
 Container deploys:
   Requires Docker locally. The CLI builds linux/amd64, exports the image, uploads it through a short-lived session, then finalizes a queued deployment.