ninepm 0.69.0 → 0.72.0

package/dist/index.js

@@ -13,6 +13,7 @@ import { Agent, fetch as undiciFetch } from "undici";
 import { MAX_DEPLOY_DESCRIPTION_LENGTH, normalizeDeployDescription } from "./deploy-description.js";
 import { managedHostnamesIn, siblingCallWarning, siblingsOf } from "./sibling-hostnames.js";
 import { MAX_STATIC_ASSET_FILE_BYTES, MAX_WORKER_ENTRY_COMPRESSED_BYTES, MAX_WORKER_SCRIPT_COMPRESSED_BYTES, WORKER_ENTRY_COMPRESSED_WARN_BYTES, assetFileTooLargeMessage, formatMebibytes, formatMegabytes, oversizedAssets, workerBundleNearLimitMessage, workerBundleTooLargeMessage, workerEntryNearLimitMessage, workerEntryTooLargeMessage, } from "./deploy-limits.js";
+import { guessZoneApex, relativeRecordName } from "./dns-host.js";
 import { 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 +50,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.72.0";
 const PUBLIC_DASHBOARD_URL = "https://9pm.ai/dashboard";
 const TOKEN_SERVICE = "9pm";
 const TOKEN_ACCOUNT = "default";
@@ -243,9 +244,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 +271,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 +501,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 +648,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 +1154,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 +2458,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 +2633,8 @@ const VALID_DEPLOY_FLAGS = new Set([
     "bundle",
     "assets",
     "no-assets",
+    "spa",
+    "no-spa",
 ]);
 export function parseArgs(argv) {
     const command = argv[0];
@@ -2628,6 +2653,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 +2888,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>.");
     }
@@ -3173,6 +3218,516 @@ async function runDeploymentsCommand(command) {
     });
     console.log(`Deleted deployment ${result.deleted}.`);
 }
+// The server has no field for an expired trace: it marks one by this exact provisioningError
+// (CUSTOM_DOMAIN_EXPIRED_MESSAGE in src/server/routes/shared.ts; a test holds the two equal).
+export const CUSTOM_DOMAIN_EXPIRED_TEXT = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
+export const DOMAIN_WAIT_EXIT = { live: 0, ownerAction: 10, platform: 11, failed: 20 };
+function normalizeDnsName(value) {
+    return value.trim().toLowerCase().replace(/\.$/, "");
+}
+// The value the server's DNS check compares against: TXT verbatim, names lowercased without a root dot.
+function checkedRecordValue(type, value) {
+    return type === "TXT" ? value : normalizeDnsName(value);
+}
+export function domainRecordStatuses(domain) {
+    const apex = guessZoneApex(domain.hostname);
+    return domain.dnsInstructions.map((instruction) => {
+        const type = instruction.type.toUpperCase();
+        const fqdn = normalizeDnsName(instruction.host);
+        const expected = checkedRecordValue(type, instruction.value);
+        // Matched on the expected value as well as host and type: the two TXT values of one name
+        // are separate rows, and keying on host and type alone gives both rows one verdict (#1986).
+        const seen = domain.dnsCheck?.records.find((entry) => entry.type.toUpperCase() === type && normalizeDnsName(entry.host) === fqdn && entry.expected === expected);
+        const atApex = type === "CNAME" && fqdn === apex;
+        const check = domainRecordCheck(seen, atApex);
+        return {
+            type,
+            name: relativeRecordName(fqdn, apex),
+            fqdn,
+            expected: instruction.value,
+            current: seen ? seen.current : null,
+            ok: check === "found" ? true : check === "missing" || check === "different" ? false : null,
+            check,
+            apex: atApex,
+            optional: instruction.optional === true,
+        };
+    });
+}
+const IP_ADDRESS = /^(\d{1,3}(\.\d{1,3}){3}|[0-9a-f:]*:[0-9a-f:.]+)$/i;
+// The server looks a CNAME up and, finding none, falls back to the name's A records. At the
+// zone root that is exactly what a correct ALIAS/ANAME or flattened CNAME answers: addresses,
+// never the target name. So addresses at the apex are not evidence of a wrong record; they
+// cannot be compared from outside at all.
+function domainRecordCheck(seen, atApex) {
+    if (!seen)
+        return "not_checked";
+    if (seen.matches)
+        return "found";
+    if (seen.current.length === 0)
+        return "missing";
+    if (atApex && seen.current.every((value) => IP_ADDRESS.test(value.trim())))
+        return "apex_addresses";
+    return "different";
+}
+export function deriveDomainState(domain, records = domainRecordStatuses(domain)) {
+    if (domain.provisioningError === CUSTOM_DOMAIN_EXPIRED_TEXT)
+        return "expired";
+    if (domain.routingStatus === "failed" || domain.tlsStatus === "failed" || domain.provisioningError)
+        return "failed";
+    if (domain.routingStatus === "active" && domain.tlsStatus === "active")
+        return "live";
+    const required = records.filter((record) => !record.optional);
+    if (required.some((record) => record.ok === false))
+        return "waiting_for_dns";
+    const routingActive = domain.routingStatus === "active";
+    // An apex answering with addresses defers to the platform's own routing check: active means
+    // it found the record, pending means it has not yet.
+    const unproven = required.some((record) => record.check === "not_checked" || (record.check === "apex_addresses" && !routingActive));
+    if (unproven || (!domain.dnsCheck && required.length === 0)) {
+        // Routing still pending is the platform's own evidence that it has not seen the records.
+        return routingActive ? "dns_unverified" : "waiting_for_dns";
+    }
+    return "issuing_certificate";
+}
+export function domainStatusJson(domain, app, checkedAt) {
+    const records = domainRecordStatuses(domain);
+    return {
+        hostname: domain.hostname,
+        app: domain.app?.slug ?? app,
+        state: deriveDomainState(domain, records),
+        routing: domain.routingStatus,
+        tls: domain.tlsStatus,
+        provider: domain.dnsCheck?.provider ?? null,
+        nameservers: domain.dnsCheck?.nameservers ?? [],
+        records,
+        error: domain.provisioningError,
+        expiresAt: domain.expiresAt ?? domain.expireAfter ?? null,
+        checkedAt,
+    };
+}
+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",
+};
+export function domainStateLabel(state) {
+    return DOMAIN_STATE_LABELS[state];
+}
+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";
+    // 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`;
+}
+function domainCommand(subcommand, app, hostname, owner) {
+    return `9pm domains ${subcommand} ${quoteSiteArg(app)} ${hostname}${owner ? ` --owner ${quoteSiteArg(owner)}` : ""}`;
+}
+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.owner)}`);
+        return lines;
+    }
+    if (status.state === "failed" && status.error) {
+        lines.push(status.error);
+    }
+    const apex = guessZoneApex(status.hostname);
+    if (status.records.length > 0) {
+        lines.push(status.provider
+            ? `DNS for ${apex} is managed at ${status.provider}${status.nameservers.length > 0 ? ` (${status.nameservers.join(", ")})` : ""}. Add these records there:`
+            : status.nameservers.length > 0
+                ? `DNS for ${apex} is served by ${status.nameservers.join(", ")}. Add these records there:`
+                : `Add these records where the DNS for ${apex} is managed:`);
+        lines.push("");
+        const rows = [
+            ["TYPE", "NAME", "VALUE", "STATE"],
+            ...status.records.map((record) => [record.apex ? "ALIAS" : record.type, record.name, record.expected, recordStateText(record, status.routing)]),
+        ];
+        lines.push(...renderColumns(rows).map((line) => `  ${line}`));
+        lines.push("");
+        if (status.records.some((record) => record.apex)) {
+            lines.push(`ALIAS at @: the root of ${apex} cannot hold a CNAME, so add an ALIAS or ANAME record there (or a CNAME your provider flattens), pointing at the value shown.`);
+        }
+        if (status.records.some((record) => !record.optional && record.check === "not_checked")) {
+            lines.push("Couldn't check your DNS records just now, so their state is unknown. Make sure they are published as shown.");
+        }
+        if (status.records.some((record) => record.name !== record.fqdn)) {
+            lines.push(`Enter the name as shown: most providers add ".${apex}" themselves. If yours asks for the full name, append ".${apex}".`);
+        }
+    }
+    if (status.state === "failed") {
+        lines.push(`Re-check: ${domainCommand("check", status.app, status.hostname, options.owner)}`);
+        lines.push(`Start over (the records may change): ${domainCommand("restart", status.app, status.hostname, options.owner)}`);
+        return lines;
+    }
+    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.owner)}`);
+    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.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;
+}
+// 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 };
+        }
+        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 is the platform's to finish; records that could not be
+            // checked are the owner's to confirm, so they share the owner-action code.
+            const exitCode = last.state === "issuing_certificate" ? DOMAIN_WAIT_EXIT.platform : DOMAIN_WAIT_EXIT.ownerAction;
+            return { status: last, exitCode, timedOut: true };
+        }
+        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>]",
+    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),
+        ...(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, owner, heading) {
+    if (json) {
+        console.log(JSON.stringify(status, null, 2));
+        return;
+    }
+    if (heading)
+        console.log(heading);
+    for (const line of formatDomainStatus(status, owner ? { owner } : {}))
+        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 } : {}) };
+    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, command.owner)}`);
+            return;
+        }
+        printDomainStatus(status, action.json, command.owner, action.json ? undefined : `Added ${hostname} to ${action.site}.`);
+        return;
+    }
+    if (action.kind === "status") {
+        printDomainStatus(await getDomainStatus(target), action.json, command.owner);
+        return;
+    }
+    if (action.kind === "check") {
+        await recheckDomain(target);
+        printDomainStatus(await getDomainStatus(target), action.json, command.owner);
+        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, command.owner ? { owner: command.owner } : {}))
+                console.log(line);
+            if (result.timedOut)
+                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, command.owner ? { owner: command.owner } : {}))
+            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 +3869,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 +3880,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 +3898,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 +4014,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 +5027,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));
@@ -4542,6 +5123,10 @@ async function main() {
             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.
@@ -4789,6 +5374,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 +5460,66 @@ async function runSupportCommand(command) {
     });
     console.log("Support request sent. A human will reply to your account email.");
 }
+// 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);
+    // A plain URL (scheme, host, port, path) has no shell-significant characters; anything
+    // else falls back to single quotes.
+    const url = target && /^[A-Za-z0-9._:/-]+$/.test(target.apiUrl) ? target.apiUrl : target ? quoteSiteArg(target.apiUrl) : "";
+    const apiUrl = target && target.apiUrlFrom !== "default" ? ` --api-url ${url}` : "";
+    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 +5534,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 +5691,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 +5716,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>             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 +5762,31 @@ 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, 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.
+  A record's name is relative to the zone (www, _acme-challenge.www, @). ok is null when the
+  check cannot say: check is not_checked, or apex_addresses for a root record answering with
+  addresses (a correct ALIAS does), which defers to the routing status.
+  wait exits 0 when live, 10 on timeout with records missing or unverified (the owner must act or
+  confirm), 11 on timeout with every record found (the platform is still finishing), 20 when the
+  domain failed or expired, and 1 on a usage, auth or API error.
+
 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.