ninepm 0.69.0 → 0.78.0

package/dist/index.js

@@ -13,6 +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, zoneApexFor } from "./dns-host.js";
+import { dnsProviderProfile, recordAtProvider } from "./dns-providers.js";
+import { 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";
@@ -49,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.69.0";
+export const CLI_VERSION = "0.78.0";
 const PUBLIC_DASHBOARD_URL = "https://9pm.ai/dashboard";
 const TOKEN_SERVICE = "9pm";
 const TOKEN_ACCOUNT = "default";
@@ -243,9 +246,13 @@ export class DeployError extends Error {
  * prevent (#1061).
  */
 export class DeliberateRefusalError extends Error {
-    constructor(message) {
+    // The server's error code, so a command can add what only it knows - the exact
+    // command line to re-run - to a refusal it recognises.
+    code;
+    constructor(message, code) {
         super(message);
         this.name = "DeliberateRefusalError";
+        this.code = code;
     }
 }
 /**
@@ -266,6 +273,7 @@ export class DeliberateRefusalError extends Error {
 const DELIBERATE_REFUSAL_CODES = new Set([
     "deploys_frozen",
     "cli_version_outdated",
+    "access_mode_change_unconfirmed",
 ]);
 export function isDeliberateRefusal(error) {
     if (error instanceof DeliberateRefusalError)
@@ -495,6 +503,11 @@ async function runDeploy(initialOptions, slugHolder) {
         throw new Error(options.bundleDir ? `Bundle directory contains no files: ${contentRoot}` : "Directory contains no deployable files.");
     }
     const bundle = options.bundleDir ? bundleMetadataFromManifest(manifest, contentRoot) : null;
+    // Checked here as well as at parse time because a detected framework build becomes a
+    // bundle only after parsing, and the platform would refuse it after the app exists.
+    if (bundle && options.missingPages) {
+        throw new Error("--spa and --no-spa do not apply to a framework bundle: its server answers every path itself.");
+    }
     const serverEntry = runtime === "worker" && !bundle ? normalizeServerEntry(options.entry ?? "src/index.js") : undefined;
     // Set by the size preflight below and reused by the upload loop, so the entry is read once.
     let serverEntryBytes;
@@ -637,6 +650,7 @@ async function runDeploy(initialOptions, slugHolder) {
         ...(options.description ? { description: options.description } : {}),
         runtime,
         ...(serverEntry ? { serverEntry } : {}),
+        ...(options.missingPages ? { missingPages: options.missingPages } : {}),
         metadata: {
             cli: CLI_CLIENT_ID,
             inspiredBy: "here.now",
@@ -1142,29 +1156,40 @@ export async function getSiteAccess(options) {
         method: "GET",
     });
 }
+// The server refuses an access-mode change unless the request says it means it (#1987):
+// the change can lock people out and take custom domains down. `--switch-mode` sends
+// `switchMode: true`; without it the refusal is printed with the command to re-run.
+export const ACCESS_MODE_CHANGE_UNCONFIRMED = "access_mode_change_unconfirmed";
+function switchModeField(options) {
+    return options.switchMode ? { switchMode: true } : {};
+}
 export async function setSiteAccessPublic(options) {
     const payload = await apiRequest(options, `/v1/sites/${encodeURIComponent(options.site)}/access`, {
         method: "PUT",
-        body: JSON.stringify({ mode: "public" }),
+        body: JSON.stringify({ mode: "public", ...switchModeField(options) }),
     });
     return payload.access;
 }
 export async function setSiteAccessOtp(options) {
     const payload = await apiRequest(options, `/v1/sites/${encodeURIComponent(options.site)}/access`, {
         method: "PUT",
-        body: JSON.stringify({ mode: "private_otp" }),
+        body: JSON.stringify({ mode: "private_otp", ...switchModeField(options) }),
     });
     return payload.access;
 }
 export async function setSiteAccessIdp(options) {
     const payload = await apiRequest(options, `/v1/sites/${encodeURIComponent(options.site)}/access`, {
         method: "PUT",
-        body: JSON.stringify({ mode: "private_idp", ...(options.providers?.length ? { providers: options.providers } : {}) }),
+        body: JSON.stringify({
+            mode: "private_idp",
+            ...(options.providers?.length ? { providers: options.providers } : {}),
+            ...switchModeField(options),
+        }),
     });
     return payload.access;
 }
 export async function createAccessServiceToken(options) {
-    const body = {};
+    const body = { ...switchModeField(options) };
     if (options.name) {
         body.name = options.name;
     }
@@ -2435,7 +2460,7 @@ async function expectOk(response, action) {
     const code = typeof envelope?.code === "string" ? envelope.code : "";
     const message = typeof envelope?.message === "string" ? envelope.message.trim() : "";
     if (code && message && DELIBERATE_REFUSAL_CODES.has(code)) {
-        throw new DeliberateRefusalError(message);
+        throw new DeliberateRefusalError(message, code);
     }
     throw new Error(`Failed to ${action}: ${response.status} ${text}`);
 }
@@ -2610,6 +2635,8 @@ const VALID_DEPLOY_FLAGS = new Set([
     "bundle",
     "assets",
     "no-assets",
+    "spa",
+    "no-spa",
 ]);
 export function parseArgs(argv) {
     const command = argv[0];
@@ -2628,6 +2655,9 @@ export function parseArgs(argv) {
     if (command === "deployments") {
         return parseDeploymentsArgs(argv.slice(1));
     }
+    if (command === "domains") {
+        return parseDomainsArgs(argv.slice(1));
+    }
     if (command === "logs") {
         return parseLogsArgs(argv.slice(1));
     }
@@ -2860,6 +2890,23 @@ export function parseArgs(argv) {
         }
         options.publicAssets = typeof assetsFlag === "string" ? normalizeAssetsDirectory(assetsFlag) : NO_PUBLIC_ASSETS;
     }
+    if (flags.has("spa") || flags.has("no-spa")) {
+        if (flags.has("spa") && flags.has("no-spa")) {
+            throw new Error("--spa and --no-spa cannot be combined.");
+        }
+        // The flag parser hands the next word to a flag as its value, so `--spa dist` would
+        // otherwise deploy "." and drop "dist" silently.
+        for (const name of ["spa", "no-spa"]) {
+            const value = flags.get(name);
+            if (typeof value === "string") {
+                throw new Error(`--${name} takes no value (got "${value}"). Put the directory first: 9pm deploy ${value} --${name}`);
+            }
+        }
+        if (options.runtime === "container" || options.bundleDir) {
+            throw new Error("--spa and --no-spa apply to static sites and --entry worker apps; a container or --bundle app answers every path itself.");
+        }
+        options.missingPages = flags.has("spa") ? "spa" : "404";
+    }
     if (options.runtime === "container" && !options.port) {
         throw new Error("Container deploys require --port <port>.");
     }
@@ -2872,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);
@@ -3173,6 +3220,710 @@ async function runDeploymentsCommand(command) {
     });
     console.log(`Deleted deployment ${result.deleted}.`);
 }
+// `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 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 };
+        }
+    });
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value !== "" ? value : null;
+}
+export function domainStatusJson(domain, app, checkedAt) {
+    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: 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 = {
+    live: "live",
+    waiting_for_dns: "waiting for DNS records",
+    dns_unverified: "couldn't check the DNS records just now",
+    issuing_certificate: "DNS records found, waiting for the platform to issue the certificate",
+    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 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";
+function recordStateText(record, routing) {
+    if (record.ok === true)
+        return "found";
+    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`;
+    }
+    if (record.ok === null || record.current === null)
+        return "not checked: couldn't read your DNS just now";
+    if (record.type === "TXT") {
+        const now = record.current.length === 0 ? "not published yet" : `currently ${record.current.join(", ")}`;
+        return `${now}: ${TXT_KEEP_OTHERS}`;
+    }
+    if (record.current.length === 0)
+        return "not published yet";
+    return `currently ${record.current.join(", ")}: 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)));
+    return rows.map((cells) => cells
+        .map((cell, column) => (column === cells.length - 1 ? cell : cell.padEnd(widths[column] ?? 0)))
+        .join("  ")
+        .trimEnd());
+}
+export function formatDomainStatus(status, options = {}) {
+    const lines = [`${status.hostname} (app ${status.app}): ${domainStateLabel(status.state)}`];
+    if (status.state === "live") {
+        lines.push(`Serving at https://${status.hostname}`);
+        return lines;
+    }
+    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)}`);
+        return lines;
+    }
+    if (status.state === "failed" && status.error) {
+        lines.push(status.error);
+    }
+    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
+            ? `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
+                ? `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 (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") {
+        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;
+    }
+    // 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.");
+    }
+    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 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.";
+    }
+    return "Timed out: the DNS records could not be checked. Make sure they are published as shown, then wait again.";
+}
+export function formatDomainsList(statuses) {
+    if (statuses.length === 0) {
+        return ["No custom domains. Add one: 9pm domains add <app> <hostname>"];
+    }
+    return renderColumns([
+        ["HOSTNAME", "APP", "STATE", "ROUTING", "TLS"],
+        ...statuses.map((status) => [status.hostname, status.app, status.state, status.routing, status.tls]),
+    ]);
+}
+export class DomainsApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.name = "DomainsApiError";
+        this.status = status;
+        this.code = code;
+    }
+}
+// The API's own message and code, plus `details.reason` where the refusal carries one
+// (invalid_custom_domain), rather than the raw envelope the generic path prints.
+export function domainsApiError(status, text) {
+    let envelope = null;
+    try {
+        const parsed = JSON.parse(text);
+        envelope = parsed.error && typeof parsed.error === "object" ? parsed.error : null;
+    }
+    catch {
+        envelope = null;
+    }
+    const code = typeof envelope?.code === "string" ? envelope.code : null;
+    const message = typeof envelope?.message === "string" ? envelope.message.trim() : "";
+    if (!code || !message) {
+        return new DomainsApiError(`Request failed: ${status} ${text}`.trim(), status, code);
+    }
+    const details = envelope?.details;
+    const reason = details && typeof details === "object" && typeof details.reason === "string"
+        ? details.reason
+        : null;
+    return new DomainsApiError(`${message} (${code}${reason ? `, reason: ${reason}` : ""})`, status, code);
+}
+async function domainsRequest(options, route, init = { method: "GET" }) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${options.token}`);
+    headers.set("x-9pm-cli-version", CLI_VERSION);
+    if (init.body)
+        headers.set("content-type", "application/json");
+    const response = await fetchFn(`${normalizeApiUrl(options.apiUrl)}${route}`, { ...init, headers });
+    noteCliOutdatedAdvisory(response);
+    if (!response.ok) {
+        throw domainsApiError(response.status, await response.text());
+    }
+    return (await response.json());
+}
+function ownerQuery(owner) {
+    return owner ? `?owner=${encodeURIComponent(owner)}` : "";
+}
+function siteDomainsRoute(options, hostname, action) {
+    const base = `/v1/sites/${encodeURIComponent(options.site)}/domains`;
+    const path = hostname ? `${base}/${encodeURIComponent(hostname)}${action ? `/${action}` : ""}` : base;
+    return `${path}${ownerQuery(options.owner)}`;
+}
+export function normalizeDomainArg(value) {
+    return normalizeDnsName(value);
+}
+export async function listDomainStatuses(options) {
+    const checkedAt = (options.now ?? (() => new Date()))().toISOString();
+    if (options.site) {
+        const result = await domainsRequest(options, siteDomainsRoute({ ...options, site: options.site }));
+        return result.domains.map((domain) => domainStatusJson(domain, options.site, checkedAt));
+    }
+    const result = await domainsRequest(options, `/v1/domains${ownerQuery(options.owner)}`);
+    return result.domains.map((domain) => domainStatusJson(domain, domain.app?.slug ?? "", checkedAt));
+}
+export async function getDomainStatus(options) {
+    const hostname = normalizeDomainArg(options.hostname);
+    const statuses = await listDomainStatuses(options);
+    const status = statuses.find((candidate) => candidate.hostname === hostname);
+    if (!status) {
+        throw new DomainsApiError(`${hostname} is not a custom domain of ${options.site} (custom_domain_not_found). List them: 9pm domains list ${quoteSiteArg(options.site)}`, 404, "custom_domain_not_found");
+    }
+    return status;
+}
+export async function addDomain(options) {
+    const result = await domainsRequest(options, siteDomainsRoute(options), {
+        method: "POST",
+        body: JSON.stringify({ hostname: options.hostname.trim() }),
+    });
+    return result.domain;
+}
+export async function recheckDomain(options) {
+    await domainsRequest(options, siteDomainsRoute(options, normalizeDomainArg(options.hostname), "refresh"), { method: "POST" });
+}
+export async function restartDomain(options) {
+    return domainsRequest(options, siteDomainsRoute(options, normalizeDomainArg(options.hostname), "restart"), { method: "POST" });
+}
+export async function removeDomain(options) {
+    const result = await domainsRequest(options, siteDomainsRoute(options, normalizeDomainArg(options.hostname)), {
+        method: "DELETE",
+    });
+    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.
+export async function waitForDomain(options) {
+    const nowMs = options.nowMs ?? (() => Date.now());
+    const sleepFn = options.sleepFn ?? sleep;
+    const deadline = nowMs() + options.timeoutMs;
+    let last = null;
+    for (;;) {
+        try {
+            const status = await getDomainStatus(options);
+            last = status;
+            options.onStatus?.(status);
+            if (status.state === "live")
+                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;
+            if (!transient || (nowMs() >= deadline && !last))
+                throw error;
+            options.onRetry?.(error);
+        }
+        const remaining = deadline - nowMs();
+        if (remaining <= 0) {
+            if (!last)
+                throw new Error(`Timed out before ${options.hostname} could be read.`);
+            // 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));
+    }
+}
+const DOMAINS_VALUE_FLAGS = new Set(["token", "api-url", "owner", "timeout", "interval", "confirm"]);
+const DOMAINS_BOOLEAN_FLAGS = new Set(["json"]);
+function domainsPositionals(argv) {
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const name = arg.slice(2);
+        if (!DOMAINS_VALUE_FLAGS.has(name) && !DOMAINS_BOOLEAN_FLAGS.has(name)) {
+            throw new Error(`Unknown flag for 9pm domains: --${name}`);
+        }
+        if (DOMAINS_VALUE_FLAGS.has(name))
+            index += 1;
+    }
+    return positionals;
+}
+const DOMAINS_USAGE = {
+    list: "9pm domains list [<app>] [--owner <organisation>] [--json]",
+    add: "9pm domains add <app> <hostname> [--owner <organisation>] [--json]",
+    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>]  (for a failed certificate; the record values may change)",
+    remove: "9pm domains remove <app> <hostname> --confirm <hostname> [--owner <organisation>]",
+};
+function parseDomainsArgs(argv) {
+    const subcommand = argv[0] === "ls" ? "list" : argv[0] === "rm" ? "remove" : argv[0];
+    if (!subcommand || subcommand === "help" || subcommand === "--help") {
+        throw new UsageError();
+    }
+    const usage = DOMAINS_USAGE[subcommand];
+    if (!usage) {
+        throw new Error(`Unknown domains subcommand: ${subcommand}. Expected one of: ${Object.keys(DOMAINS_USAGE).join(", ")}.`);
+    }
+    const flags = parseFlags(argv);
+    const positionals = domainsPositionals(argv.slice(1));
+    const json = flags.has("json");
+    const owner = readStringFlag(flags, "owner");
+    const withBase = (action) => ({
+        kind: "domains",
+        ...readBaseApiOptions(flags),
+        apiUrlFrom: apiUrlSource(flags),
+        ...(owner ? { owner } : {}),
+        action,
+    });
+    if (subcommand === "list") {
+        if (positionals.length > 1)
+            throw new Error(`Usage: ${usage}`);
+        const site = positionals[0];
+        return withBase({ kind: "list", json, ...(site ? { site } : {}) });
+    }
+    const [site, hostname] = positionals;
+    if (!site || !hostname || positionals.length > 2) {
+        throw new Error(`Usage: ${usage}`);
+    }
+    if (subcommand === "add" || subcommand === "status" || subcommand === "check") {
+        return withBase({ kind: subcommand, site, hostname, json });
+    }
+    if (subcommand === "wait") {
+        const timeout = readStringFlag(flags, "timeout") ?? "30m";
+        const interval = readStringFlag(flags, "interval") ?? "20s";
+        const timeoutSeconds = parseDurationSeconds(timeout);
+        const intervalSeconds = parseDurationSeconds(interval);
+        if (intervalSeconds < 1)
+            throw new Error("--interval must be at least 1s.");
+        return withBase({ kind: "wait", site, hostname, json, timeoutSeconds, intervalSeconds });
+    }
+    if (subcommand === "restart") {
+        return withBase({ kind: "restart", site, hostname });
+    }
+    const confirm = readStringFlag(flags, "confirm");
+    if (!confirm || normalizeDomainArg(confirm) !== normalizeDomainArg(hostname)) {
+        throw new Error(`Removing a domain stops it serving at once. Pass --confirm ${normalizeDomainArg(hostname)} to remove it.`);
+    }
+    return withBase({ kind: "remove", site, hostname });
+}
+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, options))
+        console.log(line);
+}
+function instructionLines(instructions, hostname) {
+    const apex = guessZoneApex(hostname);
+    return renderColumns(instructions.map((instruction) => [instruction.type.toUpperCase(), relativeRecordName(instruction.host, apex), instruction.value])).map((line) => `  ${line}`);
+}
+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) {
+            console.log(JSON.stringify({ domains: statuses }, null, 2));
+            return;
+        }
+        for (const line of formatDomainsList(statuses))
+            console.log(line);
+        return;
+    }
+    const target = { ...base, site: action.site, hostname: action.hostname };
+    if (action.kind === "add") {
+        const added = await addDomain(target);
+        const hostname = added?.hostname ?? normalizeDomainArg(action.hostname);
+        // The add response carries no DNS check; the list read that follows does, and it is what
+        // 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, format)}`);
+            return;
+        }
+        printDomainStatus(status, action.json, format, action.json ? undefined : `Added ${hostname} to ${action.site}.`);
+        return;
+    }
+    if (action.kind === "status") {
+        printDomainStatus(await getDomainStatus(target), action.json, format);
+        return;
+    }
+    if (action.kind === "check") {
+        await recheckDomain(target);
+        printDomainStatus(await getDomainStatus(target), action.json, format);
+        return;
+    }
+    if (action.kind === "wait") {
+        let lastState = null;
+        const result = await waitForDomain({
+            ...target,
+            timeoutMs: action.timeoutSeconds * 1000,
+            intervalMs: action.intervalSeconds * 1000,
+            onStatus: (status) => {
+                if (status.state !== lastState) {
+                    lastState = status.state;
+                    console.error(`${new Date().toISOString()} ${status.hostname}: ${domainStateLabel(status.state)}`);
+                }
+            },
+            onRetry: (error) => console.error(`Could not read the domain (${error instanceof Error ? error.message : String(error)}); retrying.`),
+        });
+        if (action.json) {
+            console.log(JSON.stringify(result.status, null, 2));
+        }
+        else {
+            for (const line of formatDomainStatus(result.status, format))
+                console.log(line);
+            if (result.timedOut || result.status.next?.action === "use_www")
+                console.log(domainWaitTimeoutMessage(result.status));
+        }
+        process.exitCode = result.exitCode;
+        return;
+    }
+    if (action.kind === "restart") {
+        const restarted = await restartDomain(target);
+        console.log(`Started validation for ${restarted.domain.hostname} over.`);
+        if (restarted.replacedInstructions.length > 0) {
+            console.log("These values no longer count; delete them at your DNS provider:");
+            for (const line of instructionLines(restarted.replacedInstructions, restarted.domain.hostname))
+                console.log(line);
+        }
+        else {
+            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, format))
+            console.log(line);
+        return;
+    }
+    const removed = await removeDomain(target);
+    const hostname = removed?.hostname ?? normalizeDomainArg(action.hostname);
+    console.log(`Removed ${hostname} from ${action.site}. It stops serving within seconds.`);
+    if (removed && removed.dnsInstructions.length > 0) {
+        console.log("You can now delete these records at your DNS provider, if nothing else uses them:");
+        for (const line of instructionLines(removed.dnsInstructions, hostname))
+            console.log(line);
+    }
+}
 // #807 step 5: the claim behind a health verdict, in words. A bare `unknown` reads
 // as "fine"; the reason says which statement the platform is actually making.
 export function healthWithReason(status, reason) {
@@ -3314,7 +4065,7 @@ function parseAccessArgs(argv) {
         throw new UsageError();
     }
     const flags = parseFlags(argv);
-    const base = readBaseApiOptions(flags);
+    const base = { ...readBaseApiOptions(flags), apiUrlFrom: apiUrlSource(flags) };
     const siteFrom = (index) => {
         const site = argv[index];
         if (!site || site.startsWith("--")) {
@@ -3325,16 +4076,17 @@ function parseAccessArgs(argv) {
     if (subcommand === "show") {
         return { kind: "access", ...base, action: { kind: "show", site: siteFrom(1) } };
     }
+    const switchMode = flags.has("switch-mode") ? { switchMode: true } : {};
     if (subcommand === "public") {
-        return { kind: "access", ...base, action: { kind: "public", site: siteFrom(1) } };
+        return { kind: "access", ...base, action: { kind: "public", site: siteFrom(1), ...switchMode } };
     }
     if (subcommand === "otp") {
-        return { kind: "access", ...base, action: { kind: "otp", site: siteFrom(1) } };
+        return { kind: "access", ...base, action: { kind: "otp", site: siteFrom(1), ...switchMode } };
     }
     if (subcommand === "idp") {
         const site = siteFrom(1);
         const providers = readRepeatedStringFlag(argv, "provider").map(parseProviderKey);
-        return { kind: "access", ...base, action: { kind: "idp", site, ...(providers.length ? { providers } : {}) } };
+        return { kind: "access", ...base, action: { kind: "idp", site, ...(providers.length ? { providers } : {}), ...switchMode } };
     }
     if (subcommand === "service") {
         const verb = argv[1];
@@ -3342,7 +4094,11 @@ function parseAccessArgs(argv) {
         if (verb === "create") {
             const name = readStringFlag(flags, "name");
             const duration = readStringFlag(flags, "duration");
-            return { kind: "access", ...base, action: { kind: "service-create", site, ...(name ? { name } : {}), ...(duration ? { duration } : {}) } };
+            return {
+                kind: "access",
+                ...base,
+                action: { kind: "service-create", site, ...(name ? { name } : {}), ...(duration ? { duration } : {}), ...switchMode },
+            };
         }
         if (verb === "revoke") {
             const tokenId = argv[3];
@@ -3454,6 +4210,11 @@ function parseSupportArgs(argv) {
         ...readBaseApiOptions(flags),
     };
 }
+function apiUrlSource(flags) {
+    if (readStringFlag(flags, "api-url") !== undefined)
+        return "flag";
+    return process.env.NINEPM_API_URL !== undefined ? "env" : "default";
+}
 function readApiUrl(flags, fallback) {
     return validateApiUrl(readStringFlag(flags, "api-url") ?? process.env.NINEPM_API_URL ?? fallback);
 }
@@ -4462,6 +5223,22 @@ function formatRemainingForCli(value) {
 }
 export class UsageError extends Error {
 }
+// #1856: which missing-pages mode the deployment was published with, read from the
+// deployment the platform returned rather than from the flags, because a deploy without a
+// flag keeps whatever the app chose before. Null when the platform recorded none: a bundle
+// or container app answers every path itself, and an older control plane does not say.
+export function missingPagesLine(deployment) {
+    switch (deployment.metadata.missingPages) {
+        case "404":
+            return "Missing pages: 404 (the deploy's own 404.html when it has one). If the app routes in the browser, redeploy with --spa.";
+        case "spa":
+            return "Missing pages: homepage (SPA): a path with no file serves index.html. Redeploy with --no-spa to return 404 instead.";
+        case "legacy":
+            return "Missing pages: homepage (kept from before this was a choice): a path with no file serves index.html. Redeploy with --no-spa to return 404, or --spa to keep it on purpose.";
+        default:
+            return null;
+    }
+}
 async function main() {
     try {
         const command = parseArgs(process.argv.slice(2));
@@ -4537,11 +5314,25 @@ 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.`);
             }
+            const missingPages = missingPagesLine(result.deployment);
+            if (missingPages) {
+                console.log(missingPages);
+            }
             console.log(`Manage: ${dashboardUrlForApiUrl(command.options.apiUrl)}${command.options.owner ? `?owner=${encodeURIComponent(command.options.owner)}` : ""}`);
             // Gated the same way as the reachability probe above: a programmatic
             // caller injecting fetchFn opted out of the CLI's own network side trips.
@@ -4745,6 +5536,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
@@ -4789,6 +5583,10 @@ async function main() {
             await runDeploymentsCommand(command);
             return;
         }
+        if (command.kind === "domains") {
+            await runDomainsCommand(command);
+            return;
+        }
         if (command.kind === "logs") {
             await runLogsCommand(command);
             return;
@@ -4871,25 +5669,73 @@ 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
+// copied from a staging session and pasted into a shell without that flag or env var would
+// otherwise switch the mode of the same-named app on production. The access commands read
+// 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);
+    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)}` : "";
+        return `9pm access service create ${site}${name}${duration}${apiUrl} --switch-mode`;
+    }
+    if (action.kind === "idp") {
+        const providers = (action.providers ?? []).map((provider) => ` --provider ${provider}`).join("");
+        return `9pm access idp ${site}${providers}${apiUrl} --switch-mode`;
+    }
+    return `9pm access ${action.kind} ${site}${apiUrl} --switch-mode`;
+}
+// Names the API the refusal came from, and where that choice was made, so the reader sees
+// which environment the re-run will act on before running it.
+function accessTargetNote(target) {
+    const from = target.apiUrlFrom === "flag" ? "from --api-url" : target.apiUrlFrom === "env" ? "from NINEPM_API_URL" : "the default API";
+    return `against ${target.apiUrl} (${from})`;
+}
+async function withSwitchModeRerun(action, target, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof DeliberateRefusalError && error.code === ACCESS_MODE_CHANGE_UNCONFIRMED) {
+            throw new DeliberateRefusalError(`${error.message}\n\nNothing was changed. To go ahead ${accessTargetNote(target)}, re-run:\n  ${accessSwitchModeCommand(action, target)}`, error.code);
+        }
+        throw error;
+    }
+}
 async function runAccessCommand(command) {
     const base = { apiUrl: command.apiUrl, token: command.token };
+    const target = { apiUrl: command.apiUrl, apiUrlFrom: command.apiUrlFrom };
     const action = command.action;
     if (action.kind === "show") {
         console.log(JSON.stringify(await getSiteAccess({ ...base, site: action.site }), null, 2));
         return;
     }
     if (action.kind === "public") {
-        const access = await setSiteAccessPublic({ ...base, site: action.site });
+        const access = await withSwitchModeRerun(action, target, () => setSiteAccessPublic({ ...base, site: action.site, ...switchModeField(action) }));
         console.log(`Access for ${action.site} set to ${access.mode}.`);
         return;
     }
     if (action.kind === "otp") {
-        const access = await setSiteAccessOtp({ ...base, site: action.site });
+        const access = await withSwitchModeRerun(action, target, () => setSiteAccessOtp({ ...base, site: action.site, ...switchModeField(action) }));
         console.log(`Access for ${action.site} set to ${access.mode}.`);
         return;
     }
     if (action.kind === "idp") {
-        const access = await setSiteAccessIdp({ ...base, site: action.site, ...(action.providers ? { providers: action.providers } : {}) });
+        const access = await withSwitchModeRerun(action, target, () => setSiteAccessIdp({ ...base, site: action.site, ...(action.providers ? { providers: action.providers } : {}), ...switchModeField(action) }));
         console.log(`Access for ${action.site} set to ${access.mode}.`);
         return;
     }
@@ -4904,12 +5750,13 @@ async function runAccessCommand(command) {
         return;
     }
     if (action.kind === "service-create") {
-        const created = await createAccessServiceToken({
+        const created = await withSwitchModeRerun(action, target, () => createAccessServiceToken({
             ...base,
             site: action.site,
             ...(action.name ? { name: action.name } : {}),
             ...(action.duration ? { duration: action.duration } : {}),
-        });
+            ...switchModeField(action),
+        }));
         console.log(`Created service token ${created.serviceToken.id} for ${action.site}.`);
         console.log(`CF-Access-Client-Id: ${created.serviceToken.clientId}`);
         console.log(`CF-Access-Client-Secret: ${created.clientSecret}`);
@@ -5060,8 +5907,8 @@ async function runFilesCommand(command) {
 function printUsage() {
     console.log(`Usage:
   9pm --version
-  9pm deploy [directory] --name <site-name> [--slug <slug>] [--owner <organisation>] [--description "<note>"] [--with-db] [--with-auth] [--with-email]
-  9pm deploy [directory] --runtime worker --entry src/index.js (--assets <dir> | --no-assets) [--with-db]
+  9pm deploy [directory] --name <site-name> [--slug <slug>] [--owner <organisation>] [--description "<note>"] [--spa | --no-spa] [--with-db] [--with-auth] [--with-email]
+  9pm deploy [directory] --runtime worker --entry src/index.js (--assets <dir> | --no-assets) [--spa | --no-spa] [--with-db]
   9pm deploy [directory] --runtime container --port 8080 [--health-path /health] [--region auto] [--with-db] [--always-on] [--volume <gb> | --no-volume] [--cpus <n>] [--memory <size>]
   9pm deploy [directory]                   framework projects (Next.js, Vite) are detected and built automatically; --no-build skips
   9pm deploy [directory] --bundle <dir>    deploy a pre-built Cloudflare framework bundle (e.g. .open-next)
@@ -5085,15 +5932,22 @@ function printUsage() {
   9pm deployments rm <deployment-id>
   9pm logs <app> [--lines <n>] [--json]
   9pm delete <site> --confirm <slug>
+  9pm domains list [<app>] [--owner <organisation>] [--json]
+  9pm domains add <app> <hostname> [--json]        connect a domain you own; prints the DNS records to publish
+  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>             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>
-  9pm access otp <site>
-  9pm access idp <site> [--provider google|github|entra]
+  9pm access public <site> [--switch-mode]
+  9pm access otp <site> [--switch-mode]
+  9pm access idp <site> [--provider google|github|entra] [--switch-mode]
   9pm access allow email <site> <email>
   9pm access allow domain <site> <domain>
   9pm access revoke email <site> <email>
   9pm access revoke domain <site> <domain>
-  9pm access service create <site> [--name <name>] [--duration 8760h]
+  9pm access service create <site> [--name <name>] [--duration 8760h] [--switch-mode]
   9pm access service revoke <site> <service-token-id>
   9pm access token create <site> [--name <name>]
   9pm access token revoke <site> <token-id>
@@ -5124,6 +5978,34 @@ Worker public files:
   change it. A worker app that never chose serves EVERY file except its entry publicly, and
   each deploy warns about it. --check lists the files a deploy would make public.
 
+Missing pages (static sites and --entry worker apps):
+  --no-spa         a GET for a path with no file returns 404, with the deploy's own 404.html
+                   when it has one. / still serves index.html, /menu serves menu.html (or
+                   redirects to /menu/ for menu/index.html). The default for new apps.
+  --spa            a path with no file serves index.html instead, for apps that route in the
+                   browser. Every unmatched path gets it, /missing.json included.
+  The app remembers the choice; a deploy without either flag keeps it, and a deploy that fails
+  to publish does not change it. Apps created before the choice existed keep serving
+  index.html until one of the flags is passed. A worker app's own Response, 404 included,
+  is always returned as it is. Each deploy prints the mode in effect.
+
+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, 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 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.
   The app must listen on 0.0.0.0:$PORT - always read the PORT env var; on some placements the platform holds the selected --port and hands the app a different one. Use --health-path for a cheap readiness endpoint.