ninepm 0.72.0 → 0.79.0

package/README.md

@@ -62,6 +62,8 @@ Deploy a static directory:
 9pm deploy . --name my-app --slug my-app
 ```
 
+Deploying again under the same slug replaces the live app. To try a change without touching it, deploy under a different slug, which creates a separate app at its own address. On Free, your one app slot can't also hold a separate preview app. Deploying to your existing app updates its live version. Practice mode rehearses the current app's workflow. Testing a changed version separately requires another app slot: a plan with more apps (Hobby allows 3).
+
 ### How long an app's address stays the same
 
 Check this before printing a link or QR code. The live URL is `<slug>-<suffix>.9pm.ai`, and the suffix comes from the app's internal id, not from the slug:
@@ -223,16 +225,47 @@ cannot be compared from outside, so that row follows the platform's own routing
 9pm domains wait my-app www.example.com
 ```
 
-`wait` exits `0` once the domain is live, `10` if it timed out while a record is missing or could
-not be checked, `11` if it timed out with every record checked and found (the platform is still
-finishing; wait again), `20` if the domain failed or expired, and `1` on a usage, sign-in or API
-error. `9pm domains status <app> <hostname> --json` prints `{hostname, app, state, routing, tls,
-provider, nameservers, records, error, expiresAt, checkedAt}`, where `state` is `live`,
+`wait` exits `0` once the domain is live, `10` if it timed out while you have something to do (a
+record is missing or could not be checked, or a CAA record blocks the certificate even though every
+record is found), `11` if it timed out with every record checked and found and nothing left for you
+(the platform is still finishing; wait again), `20` if the domain failed or expired, and `1` on a
+usage, sign-in or API error. Since 0.74.0 a CAA block exits `10`; earlier versions exited `11`. Since 0.77.0 a bare domain whose DNS host cannot point a root
+domain at a hostname (GoDaddy, Route 53, IONOS, Wix) makes `wait` stop at once with `10`: its `next`
+is `use_www` with the `www` hostname to add instead, since no record at the root can finish it.
+`9pm domains status <app> <hostname> --json` prints `{hostname, app, state, reason, next, routing,
+tls, provider, providerId, nameservers, zone, records, advisories, error, expiresAt, checkedAt}`, where `provider` is
+the DNS host (where the nameservers point, not necessarily where the domain was bought), `reason` says why
+(`reason.providerMessage` carries the provider's own words when it reported any, with `source`
+saying whether they are the certificate authority's),
+`next` says who acts next and what to do, and `state` is `live`,
 `waiting_for_dns`, `dns_unverified` (routing is active but the records could not be checked),
 `issuing_certificate`, `failed` or `expired`. Each record's `ok` is `null` when the check cannot
-say, and its `check` says why (`not_checked`, or `apex_addresses`). `list`, `status` and `wait`
+say, and its `check` says why (`not_checked`, or `apex_addresses`). A record whose value was found
+at the name with the domain typed twice (`_acme-challenge.www.example.com.example.com`) has
+`check: "doubled"` and `doubledAt`: enter only the short name shown. Since 0.79.0, against a server
+that sends them: a record answered by a wildcard record of the DNS host (`*.example.com`) rather
+than one of its own has `check: "wildcard"` and `wildcard`, and the row says to add a record at that
+name (the wildcard can stay; a TXT value is always added beside the values already there);
+`resolvers` lists what each public resolver answered when two were asked, and when one shows the
+expected value and another does not, the record is `check: "resolvers_disagree"` with `ok: null`:
+neither cache proves which answer is current, so confirm the record at your DNS host and check again.
+A record that does not match carries `ttlSeconds`, how long that answer may stay cached. A root
+answering with addresses while routing is pending asks you to confirm the ALIAS or ANAME target,
+since a parking page answers with addresses too. With every record found, the text names the
+platform's next automatic check from `next.nextCheckAt`. `advisories` lists hints that
+the hostname may be a typo, such as a domain that is not in DNS; the domain is added either way.
+Since 0.78.0 each record also carries `typeAtProvider`, `nameAtProvider` (`""` means leave the Host
+field empty) and `valueAtProvider`: the record as a recognised DNS host's editor wants it.
+`typeAtProvider` is `null` for a root record the host cannot hold (GoDaddy, Route 53, IONOS, Wix);
+the text output then suggests connecting `www` instead. `list`, `status` and `wait`
 only read; `add`, `check`, `restart` and `remove` need permission to configure the app.
 
+Every `9pm deploy` lists the app's custom domains under its `Deployed` line: `Also serving at
+https://<domain>` for a live one, and for any other its state and the `9pm domains status`
+command to run. If the domains cannot be read within a few seconds, the deploy says so in one
+line instead; the deploy itself is never held back by it. `9pm delete` names the custom domains
+it removed.
+
 ## Commands
 
 ```sh
@@ -259,7 +292,7 @@ only read; `add`, `check`, `restart` and `remove` need permission to configure t
 9pm domains status <app> <hostname> [--json]
 9pm domains check <app> <hostname> [--json]
 9pm domains wait <app> <hostname> [--timeout 30m] [--interval 20s] [--json]
-9pm domains restart <app> <hostname>
+9pm domains restart <app> <hostname>          # only after a certificate failed; record values may change
 9pm domains remove <app> <hostname> --confirm <hostname>
 9pm access show <site>
 9pm access public <site> [--switch-mode]

package/dist/dns-host.d.ts

@@ -5,3 +5,11 @@ export declare function guessZoneApex(hostname: string): string;
  * `www.tmrwtitans.com` -> `www`, the apex itself -> `@`. A name outside the zone stays whole.
  */
 export declare function relativeRecordName(recordHost: string, apex: string): string;
+/**
+ * The zone a hostname's records go in: the zone the DNS check found by walking up to the first
+ * name that answers NS, when it has one, otherwise the guess. The found zone is used only when
+ * the hostname is inside it and it is no shorter than the guess: a shorter one (`co.uk`) means
+ * the walk climbed past a domain that does not exist, which says nothing about where its
+ * records would go.
+ */
+export declare function zoneApexFor(hostname: string, checkedZone?: unknown): string;

package/dist/dns-host.js

@@ -25,3 +25,19 @@ export function relativeRecordName(recordHost, apex) {
         return "@";
     return host.endsWith(`.${apex}`) ? host.slice(0, -(apex.length + 1)) : host;
 }
+/**
+ * The zone a hostname's records go in: the zone the DNS check found by walking up to the first
+ * name that answers NS, when it has one, otherwise the guess. The found zone is used only when
+ * the hostname is inside it and it is no shorter than the guess: a shorter one (`co.uk`) means
+ * the walk climbed past a domain that does not exist, which says nothing about where its
+ * records would go.
+ */
+export function zoneApexFor(hostname, checkedZone) {
+    const guess = guessZoneApex(hostname);
+    if (typeof checkedZone !== "string" || checkedZone === "")
+        return guess;
+    const host = hostname.toLowerCase().replace(/\.$/, "");
+    const zone = checkedZone.toLowerCase().replace(/\.$/, "");
+    const inside = host === zone || host.endsWith(`.${zone}`);
+    return inside && zone.split(".").length >= guess.split(".").length ? zone : guess;
+}

package/dist/dns-providers.d.ts

@@ -0,0 +1,91 @@
+export declare const DNS_PROVIDER_SOURCE = "registrars-and-dns-automation.md, 2026-10-09 (Route 53 rechecked 2026-10-13)";
+/** What can stand in for a root-domain record when the host cannot point the root at a hostname. */
+export type ApexFallback = 
+/** Connect www.<zone> to the app instead: an ordinary CNAME, always possible. */
+{
+    kind: "use_www";
+}
+/** The host's own forwarding of the root to www. Unverified: mentioned as a possibility, never as a step. */
+ | {
+    kind: "provider_forwarding";
+    verified: boolean;
+    https: "yes" | "unverified";
+}
+/** Route 53 only: an S3 redirect bucket behind CloudFront, aliased at the root. AWS-documented, not tested by us. */
+ | {
+    kind: "aws_redirect";
+}
+/** Move DNS hosting to a host that offers ALIAS or flattening, copying every existing record first. */
+ | {
+    kind: "move_dns_host";
+};
+export type ApexSupport = {
+    support: "alias";
+    typeLabel: "ALIAS" | "ANAME";
+    hostField: "blank" | "@";
+} | {
+    support: "cname_flattening";
+    typeLabel: "CNAME";
+    hostField: "@";
+}
+/**
+ * `fallbacks` is ordered and always starts with use_www. `hostField` is the root's Host
+ * convention where the source states one, used only when routing is already active and the
+ * root row is shown after all; absent means `@`.
+ */
+ | {
+    support: "none";
+    fallbacks: ApexFallback[];
+    hostField?: "blank";
+};
+/** A note shown under the "your DNS is at" line. Only verified notes are rendered. */
+export interface DnsProviderNote {
+    id: string;
+    verified: boolean;
+}
+export interface DnsProviderProfile {
+    apex: ApexSupport;
+    /**
+     * Whether the editor appends the zone to the name typed. True: the full name is never
+     * offered, since typing it creates `www.example.com.example.com`. "unknown" keeps showing it.
+     */
+    appendsZone: true | false | "unknown";
+    /** The editor makes a hostname value relative unless it ends in a dot (Gandi). */
+    valueNeedsTrailingDot?: true;
+    notes: DnsProviderNote[];
+    source: string;
+}
+export interface DnsProvider {
+    /** Stable key, sent as `dnsCheck.providerId`; the display name may change. */
+    id: string;
+    /** What `dnsCheck.provider` says. */
+    name: string;
+    nameservers: RegExp[];
+    /** Absent for a host nobody has researched: it is named, and gets the generic instructions. */
+    profile?: DnsProviderProfile;
+}
+export declare const DNS_PROVIDERS: readonly DnsProvider[];
+/** The DNS host a zone's nameservers belong to, or null for one not in the table. Entries that are not names are skipped. */
+export declare function dnsProviderForNameservers(nameservers: readonly unknown[]): DnsProvider | null;
+/** The profile for a `dnsCheck.providerId`; undefined for an unknown id or a host with no profile. */
+export declare function dnsProviderProfile(providerId: unknown): DnsProviderProfile | undefined;
+/** How one routing or TXT record is entered at a given host. */
+export interface RecordAtProvider {
+    /** The record type the host's editor calls it; null when the host cannot hold it at all (a root record at a no-ALIAS host). */
+    type: string | null;
+    /** The name to type; "" means leave the Host field empty. */
+    name: string;
+    /** The value to type, with a trailing dot where the editor needs one. */
+    value: string;
+}
+/**
+ * The record as the host's editor wants it. `apex` is whether this is the routing record at
+ * the zone root; `name` is the relative name (`@` at the root). Without a profile this is the
+ * record unchanged, with the root's type named the way every host that can hold it does.
+ */
+export declare function recordAtProvider(record: {
+    type: string;
+    name: string;
+    value: string;
+    apex: boolean;
+}, profile: DnsProviderProfile | undefined): RecordAtProvider;

package/dist/dns-providers.js

@@ -0,0 +1,194 @@
+// AUTO-GENERATED by scripts/generate-cli-package.mjs from the in-repo CLI source -- do not edit.
+// Edit src/cli or src/shared instead; this is regenerated on typecheck/test/build/pack.
+// DNS hosts: how each is recognised from the nameservers a custom domain's zone answers with,
+// and, for the ones researched, how its record editor wants the records we ask for. Detection
+// and profiles live in one table so a host can never be named without the rules that follow
+// from it. Read by the control plane's DNS check, the dashboard and `9pm domains`, and copied
+// into the CLI tarball by scripts/generate-cli-package.mjs, so it must import nothing.
+//
+// Every rule is a property of the DNS HOST (where the nameservers point), never the registrar:
+// records only take effect at the host, whoever sold the domain.
+//
+// Facts come from the BYOD walkthrough's research note (registrars-and-dns-automation.md,
+// researched 2026-10-09 from each provider's help center; the Route 53 row rechecked against
+// AWS's docs on 2026-10-13). That note is not in this repository, so each row cites the
+// provider's own page it relied on, and keeps the note's verified/unverified marks. A fact the note marks unverified or
+// inferred is used only where being wrong is harmless: it never removes information (an
+// "unknown" appendsZone keeps the full-name line) and never becomes a button or a step.
+// Re-check the source before widening any row.
+export const DNS_PROVIDER_SOURCE = "registrars-and-dns-automation.md, 2026-10-09 (Route 53 rechecked 2026-10-13)";
+// Order matters only where two patterns could match one nameserver; none do today.
+export const DNS_PROVIDERS = [
+    {
+        id: "namecheap",
+        name: "Namecheap",
+        nameservers: [/(^|\.)registrar-servers\.com$/],
+        // Documented: "ALIAS Record", host @; "enter your subdomain just like mysubdomain and not like mysubdomain.domain.tld".
+        // https://www.namecheap.com/support/knowledgebase/article.aspx/10128/2237/how-to-create-an-alias-record
+        // https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain
+        profile: { apex: { support: "alias", typeLabel: "ALIAS", hostField: "@" }, appendsZone: true, notes: [], source: DNS_PROVIDER_SOURCE },
+    },
+    {
+        id: "godaddy",
+        name: "GoDaddy",
+        nameservers: [/(^|\.)domaincontrol\.com$/],
+        // No ALIAS/ANAME; a CNAME Name "cannot be the @ symbol". Forwarding exists (GoDaddy's own
+        // pages); whether it answers over HTTPS is unverified. appendsZone is inferred from the
+        // Name rules, so true is used only to hide the full-name line, which GoDaddy would double.
+        // https://www.godaddy.com/en/help/add-a-cname-record-19236
+        // https://www.godaddy.com/resources/news/beyond-cname-flattening
+        profile: {
+            apex: { support: "none", fallbacks: [{ kind: "use_www" }, { kind: "provider_forwarding", verified: true, https: "unverified" }] },
+            appendsZone: true,
+            notes: [],
+            source: DNS_PROVIDER_SOURCE,
+        },
+    },
+    {
+        id: "cloudflare",
+        name: "Cloudflare",
+        nameservers: [/(^|\.)ns\.cloudflare\.com$/],
+        // A CNAME at the root is flattened. Both name forms are accepted (inferred), so the full
+        // name stays visible. No DCV advice until #1990 settles the _acme-challenge question.
+        // https://developers.cloudflare.com/dns/cname-flattening/
+        // https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-zone-apex/
+        profile: { apex: { support: "cname_flattening", typeLabel: "CNAME", hostField: "@" }, appendsZone: "unknown", notes: [], source: DNS_PROVIDER_SOURCE },
+    },
+    {
+        id: "route53",
+        name: "Amazon Route 53",
+        nameservers: [/awsdns-\d+\./],
+        // ALIAS targets only AWS resources or same-zone records, and Route 53 has no forwarding
+        // service: so www, a redirect the owner runs inside AWS, or another DNS host. The root's
+        // record name is left blank; "@" outside a zone-file import creates a literal label.
+        // https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html
+        // https://repost.aws/questions/QUt4eylJxXQ5On1SEzH09USQ/route-53-records
+        profile: {
+            apex: { support: "none", fallbacks: [{ kind: "use_www" }, { kind: "aws_redirect" }, { kind: "move_dns_host" }], hostField: "blank" },
+            appendsZone: "unknown",
+            notes: [{ id: "route53TxtQuotes", verified: false }],
+            source: DNS_PROVIDER_SOURCE,
+        },
+    },
+    // `googledomains.com` may be Squarespace Domains rather than Google Cloud DNS (unverified), so no profile.
+    { id: "google-cloud-dns", name: "Google Cloud DNS", nameservers: [/(^|\.)googledomains\.com$/] },
+    { id: "squarespace", name: "Squarespace", nameservers: [/(^|\.)squarespacedns\.com$/] },
+    {
+        id: "porkbun",
+        name: "Porkbun",
+        nameservers: [/(^|\.)porkbun\.com$/],
+        // Documented: host blank for the root, "enter only the subdomain".
+        // https://kb.porkbun.com/article/231-how-to-add-dns-records-on-porkbun
+        profile: { apex: { support: "alias", typeLabel: "ALIAS", hostField: "blank" }, appendsZone: true, notes: [], source: DNS_PROVIDER_SOURCE },
+    },
+    {
+        id: "namecom",
+        name: "Name.com",
+        nameservers: [/(^|\.)name\.com$/],
+        // https://www.name.com/support/articles/115010493967-adding-an-aname-alias-record
+        profile: { apex: { support: "alias", typeLabel: "ANAME", hostField: "blank" }, appendsZone: true, notes: [], source: DNS_PROVIDER_SOURCE },
+    },
+    {
+        id: "gandi",
+        name: "Gandi",
+        nameservers: [/(^|\.)gandi\.net$/],
+        // LiveDNS only; the value needs a trailing dot or the zone is appended to it; no A/AAAA may
+        // stay at @ beside the ALIAS.
+        // https://docs.gandi.net/en/domain_names/faq/record_types/alias_record.html
+        profile: {
+            apex: { support: "alias", typeLabel: "ALIAS", hostField: "@" },
+            appendsZone: true,
+            valueNeedsTrailingDot: true,
+            notes: [{ id: "gandiLiveDns", verified: true }],
+            source: DNS_PROVIDER_SOURCE,
+        },
+    },
+    { id: "ovhcloud", name: "OVHcloud", nameservers: [/(^|\.)ovh\.net$/] },
+    {
+        id: "ionos",
+        name: "IONOS",
+        nameservers: [/(^|\.)ui-dns\.(com|de|org|biz)$/],
+        // "CNAME only on subdomains" is IONOS's own; "only HTTP forwarding" for the root is one
+        // integrator's report, so forwarding is unverified and rendered as a possibility only.
+        // https://www.ionos.com/help/domains/configuring-cname-records-for-subdomains/configuring-a-cname-record-for-a-subdomain/
+        profile: {
+            apex: { support: "none", fallbacks: [{ kind: "use_www" }, { kind: "provider_forwarding", verified: false, https: "unverified" }] },
+            appendsZone: true,
+            notes: [],
+            source: DNS_PROVIDER_SOURCE,
+        },
+    },
+    {
+        id: "hostinger",
+        name: "Hostinger",
+        nameservers: [/(^|\.)dns-parking\.com$/],
+        // A CNAME at @ is shown as ALIAS, one per zone; "@ is appended by default".
+        // https://www.hostinger.com/support/10085192-cname-vs-alias-records-at-hostinger/
+        profile: {
+            apex: { support: "alias", typeLabel: "ALIAS", hostField: "@" },
+            appendsZone: true,
+            notes: [{ id: "hostingerCnameAtRoot", verified: true }],
+            source: DNS_PROVIDER_SOURCE,
+        },
+    },
+    { id: "hover", name: "Hover", nameservers: [/(^|\.)hover\.com$/] },
+    {
+        id: "wix",
+        name: "Wix",
+        nameservers: [/(^|\.)wixdns\.net$/],
+        // No ALIAS found and no forwarding researched, so no forwarding is offered. Wix's own
+        // instruction is to leave the Host blank wherever another one says "@".
+        // https://support.wix.com/en/article/adding-or-updating-cname-records-in-your-wix-account
+        profile: {
+            apex: { support: "none", fallbacks: [{ kind: "use_www" }, { kind: "move_dns_host" }], hostField: "blank" },
+            appendsZone: true,
+            notes: [],
+            source: DNS_PROVIDER_SOURCE,
+        },
+    },
+    { id: "vercel", name: "Vercel", nameservers: [/(^|\.)vercel-dns\.com$/] },
+    { id: "ns1", name: "NS1", nameservers: [/(^|\.)nsone\.net$/] },
+    { id: "digitalocean", name: "DigitalOcean", nameservers: [/(^|\.)digitalocean\.com$/] },
+    { id: "azure", name: "Azure DNS", nameservers: [/azure-dns\./] },
+    { id: "hetzner", name: "Hetzner", nameservers: [/(^|\.)hetzner\.(com|de)$/] },
+    // ALIAS support is second-hand and the host convention unknown, so no profile yet.
+    { id: "dnsimple", name: "DNSimple", nameservers: [/(^|\.)dnsimple\.com$/] },
+    { id: "netlify", name: "Netlify", nameservers: [/(^|\.)netlify\.com$/] },
+];
+/** The DNS host a zone's nameservers belong to, or null for one not in the table. Entries that are not names are skipped. */
+export function dnsProviderForNameservers(nameservers) {
+    if (!Array.isArray(nameservers))
+        return null;
+    for (const ns of nameservers) {
+        if (typeof ns !== "string")
+            continue;
+        const name = ns.toLowerCase().replace(/\.$/, "");
+        const hit = DNS_PROVIDERS.find((provider) => provider.nameservers.some((pattern) => pattern.test(name)));
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/** The profile for a `dnsCheck.providerId`; undefined for an unknown id or a host with no profile. */
+export function dnsProviderProfile(providerId) {
+    if (typeof providerId !== "string" || providerId === "")
+        return undefined;
+    return DNS_PROVIDERS.find((provider) => provider.id === providerId)?.profile;
+}
+/**
+ * The record as the host's editor wants it. `apex` is whether this is the routing record at
+ * the zone root; `name` is the relative name (`@` at the root). Without a profile this is the
+ * record unchanged, with the root's type named the way every host that can hold it does.
+ */
+export function recordAtProvider(record, profile) {
+    const type = String(record.type).toUpperCase();
+    const value = profile?.valueNeedsTrailingDot && typeof record.value === "string" && type === "CNAME" && !record.value.endsWith(".") ? `${record.value}.` : record.value;
+    if (!record.apex)
+        return { type, name: record.name, value };
+    if (!profile)
+        return { type: "ALIAS", name: record.name, value };
+    const apex = profile.apex;
+    if (apex.support === "none")
+        return { type: null, name: apex.hostField === "blank" ? "" : "@", value };
+    return { type: apex.typeLabel, name: apex.hostField === "blank" ? "" : "@", value };
+}

package/dist/domain-state.d.ts

@@ -0,0 +1,176 @@
+export declare const CUSTOM_DOMAIN_EXPIRED_MESSAGE = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
+/** The name the CLI has always exported the expired marker under. */
+export declare const CUSTOM_DOMAIN_EXPIRED_TEXT = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
+export declare const CUSTOM_DOMAINS_SERVICE_MODE_MESSAGE = "Custom domains are not available for service-token apps, so this domain's hostname was removed. Switching the app to another access mode sets it up again, with new DNS verification values to publish.";
+export declare const LEGACY_SERVICE_MODE_MESSAGE = "Custom domains are available only for public apps.";
+/** Whether a stored error is the service-mode teardown marker, in either wording. */
+export declare function isServiceModeProvisioningError(error: string | null | undefined): boolean;
+export declare const CUSTOM_DOMAINS_NOT_CONFIGURED_MESSAGE = "Custom domains are not fully configured on this platform.";
+export declare const CUSTOM_DOMAIN_ROUTE_CONFLICT_MESSAGE = "This domain is already claimed elsewhere on the platform. Contact support to release it.";
+export interface DomainStateDnsInstruction {
+    type: string;
+    host: string;
+    value: string;
+    optional?: boolean;
+}
+/** Whether CAA records let one of the platform's certificate authorities issue (#1999). */
+export interface DomainStateCaaCheck {
+    status: "none" | "allows" | "blocks";
+    recordName: string | null;
+    via?: string;
+    ownerUnknown?: true;
+    allowedIssuers: string[];
+    platformIssuers: string[];
+}
+export interface DomainStateDnsCheck {
+    provider: string | null;
+    /** The DNS host's stable id (src/shared/dns-providers.ts). Absent for an unknown host and from older servers. */
+    providerId?: string;
+    nameservers: string[];
+    /** The zone the records go in, as the check found it. Absent from older servers and when no name answered NS. */
+    zone?: string;
+    records: DomainStateDnsRecord[];
+    caa?: DomainStateCaaCheck;
+}
+/** What one public resolver answered for a record (#1991). */
+export interface DomainStateResolverAnswer {
+    resolver: string;
+    current: string[];
+    matches: boolean;
+    /** Seconds it may go on serving this answer from its cache. */
+    ttlSeconds?: number;
+}
+export interface DomainStateDnsRecord {
+    type: string;
+    host: string;
+    expected: string;
+    current: string[];
+    matches: boolean;
+    /** The value is published at `<host>.<zone>` instead, the provider having added the zone twice. */
+    doubledAt?: string;
+    /** The answer is a wildcard's (`*.<parent>`): the name has no record of its own. */
+    wildcard?: string;
+    /** Seconds `current` may still be served from a resolver's cache; set only when it does not match. */
+    ttlSeconds?: number;
+    /** Each public resolver's answer, when a second one was asked. `matches` above is the first resolver's, so a disagreement is never a match. */
+    resolvers?: DomainStateResolverAnswer[];
+}
+/** What the derivation reads: a domain as any of the domain endpoints returns it. */
+export interface DomainStateInput {
+    hostname: string;
+    routingStatus: string;
+    tlsStatus: string;
+    dnsInstructions: DomainStateDnsInstruction[];
+    provisioningError: string | null;
+    activatedAt?: string | null;
+    dnsCheck?: DomainStateDnsCheck;
+    providerMessage?: string | null;
+    providerMessageAt?: string | null;
+    providerMessageSource?: string | null;
+}
+export type DomainState = "live" | "waiting_for_dns" | "dns_unverified" | "issuing_certificate" | "failed" | "expired";
+export type DomainRecordCheck = "found" | "missing" | "different" | "doubled" | "wildcard" | "resolvers_disagree" | "not_checked" | "apex_addresses";
+export interface DomainRecordStatus {
+    type: string;
+    name: string;
+    fqdn: string;
+    expected: string;
+    current: string[] | null;
+    ok: boolean | null;
+    check: DomainRecordCheck;
+    doubledAt?: string;
+    wildcard?: string;
+    ttlSeconds?: number;
+    resolvers?: DomainStateResolverAnswer[];
+    apex: boolean;
+    optional: boolean;
+}
+export declare function domainRecordStatuses(domain: DomainStateInput): DomainRecordStatus[];
+export declare function domainRecordCheck(seen: DomainStateDnsRecord | undefined, atApex: boolean): DomainRecordCheck;
+/**
+ * Each resolver's answer as the server reported it, with malformed entries dropped, so a bad entry
+ * neither breaks a row nor counts towards a disagreement.
+ */
+export declare function resolverAnswers(seen: DomainStateDnsRecord | undefined): DomainStateResolverAnswer[];
+/** Whether one resolver shows the expected value while another shows something else. */
+export declare function resolversDisagree(seen: DomainStateDnsRecord | undefined): boolean;
+/** A cache's time left in whole minutes, at least one: "up to N min". */
+export declare function cacheMinutes(ttlSeconds: number): number;
+/**
+ * The `www.<domain>` to connect instead, when this hostname is a bare domain whose DNS host
+ * cannot point a root at a hostname at all (#1996): GoDaddy, Route 53, IONOS, Wix. Read only
+ * from a host the check both named and identified, so an unknown host, an older server and a
+ * domain with no check keep the ordinary records. Routing that is already active is the
+ * platform's own evidence that the root record exists, and wins over the profile.
+ */
+export declare function rootUnsupportedWwwHostname(domain: DomainStateInput): string | null;
+/**
+ * Whether a domain's instructions show "connect www instead" in place of the root record. It
+ * reads the status's own next step, so the display and the status cannot disagree: routing
+ * that is already active, an unknown host or an older server never show it, and a server's
+ * verdict is honoured even for a host this copy's table does not know.
+ */
+export declare function showsUseWww(next: {
+    action?: string;
+} | null | undefined): boolean;
+export declare function deriveDomainState(domain: DomainStateInput, records?: DomainRecordStatus[]): DomainState;
+export type DomainReasonCode = "records_missing" | "record_points_elsewhere" | "dns_changed_after_live" | "dns_not_checked" | "apex_unverifiable" | "dns_resolvers_disagree" | "dns_host_cannot_point_root" | "caa_blocks" | "certificate_pending" | "certificate_failed" | "hostname_failed" | "service_mode" | "claimed_elsewhere" | "platform_not_configured" | "provider_error" | "expired";
+export interface DomainReason {
+    code: DomainReasonCode;
+    /**
+     * The provider's own text, verbatim, when one was reported. `source` says whose it is: only
+     * "certificate_authority" may be presented as the certificate authority's; "hostname" is the
+     * hostname's own verification note and is worded neutrally.
+     */
+    providerMessage?: {
+        text: string;
+        seenAt: string;
+        source: "certificate_authority" | "hostname";
+    };
+}
+export type DomainNextAction = "none" | "add_records" | "replace_record" | "confirm_records" | "use_www" | "allow_ca_in_your_zone" | "ask_caa_controller" | "check_caa" | "wait" | "start_over" | "change_access_mode" | "add_again" | "recheck" | "contact_support";
+export interface DomainNextRecord {
+    type: string;
+    host: string;
+    value: string;
+    /**
+     * What to do with this one record. A step can mix them: a routing record pointing elsewhere is
+     * "replace" while a missing TXT value beside it is "add", because a name may hold several TXT
+     * values and replacing one could remove a value that must stay. TXT is never "replace".
+     */
+    action: "add" | "replace" | "confirm";
+    check: DomainRecordCheck;
+}
+export interface DomainNext {
+    /** Who has to act; absent when nobody does (a live domain). */
+    who?: "owner" | "platform";
+    action: DomainNextAction;
+    /** add/replace name only rows checked missing or different; not_checked rows only ever get confirm_records. */
+    records?: DomainNextRecord[];
+    /** CAA only: the name whose records decide, and the name of the owner's that points at it. */
+    caa?: {
+        recordName: string;
+        via?: string;
+        ownerUnknown?: true;
+        platformIssuers: string[];
+    };
+    /** The platform's next background re-read. It reads the status again and restarts nothing. */
+    nextCheckAt?: string;
+    /** use_www only: the hostname to add to the app instead. */
+    hostname?: string;
+}
+export interface DomainStatus {
+    state: DomainState;
+    /** Null only for a live domain. */
+    reason: DomainReason | null;
+    next: DomainNext;
+}
+/**
+ * The state, why, and the one next step. `state` is exactly deriveDomainState's; `reason` and
+ * `next` only refine it. Two rules hold throughout: a record nobody looked at is never called
+ * missing (it gets confirm_records, never add), and nothing here restarts validation or
+ * suggests that a restart speeds things up - Start over is named only for a failed certificate.
+ */
+export declare function deriveDomainStatus(domain: DomainStateInput, options?: {
+    nextCheckAt?: string | null;
+}): DomainStatus;