ninepm 0.72.0 → 0.78.0

package/dist/domain-state.js

@@ -0,0 +1,248 @@
+// AUTO-GENERATED by scripts/generate-cli-package.mjs from the in-repo CLI source -- do not edit.
+// Edit src/cli or src/shared instead; this is regenerated on typecheck/test/build/pack.
+// One plain-language status for a custom domain (#1994): which of six states it is in, why,
+// and the one thing that happens next. The control plane computes it after its DNS check and
+// sends it on every domain; the CLI and the dashboard derive it from this same file when they
+// meet a server that predates the field, so the two paths cannot disagree. Copied into the CLI
+// tarball by scripts/generate-cli-package.mjs, so it imports nothing but dns-host and
+// dns-providers, which are copied beside it.
+import { relativeRecordName, zoneApexFor } from "./dns-host.js";
+import { dnsProviderProfile } from "./dns-providers.js";
+// The markers the control plane writes into provisioningError. Matched as exact strings, so a
+// wording change here changes what every reader recognises at once; the server's reconcilers
+// import them from this file for the same reason.
+// #751: the expired marker. Deliberately static - no configured day-count inside it - because
+// the reconcilers, claim checks and quota carve-outs key on this exact string.
+export const CUSTOM_DOMAIN_EXPIRED_MESSAGE = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
+/** The name the CLI has always exported the expired marker under. */
+export const CUSTOM_DOMAIN_EXPIRED_TEXT = CUSTOM_DOMAIN_EXPIRED_MESSAGE;
+// Written onto a domain row when its app is in private_service mode, the only mode whose
+// domains are torn down (#750 kept them for otp/idp).
+export const CUSTOM_DOMAINS_SERVICE_MODE_MESSAGE = "Custom domains are not available for service-token apps, so this domain's hostname was removed. Switching the app to another access mode sets it up again, with new DNS verification values to publish.";
+// The wording rows torn down by earlier releases still carry. It says custom domains are
+// public-only, which is false (otp/idp apps keep theirs), so it is recognised and replaced.
+export const LEGACY_SERVICE_MODE_MESSAGE = "Custom domains are available only for public apps.";
+/** Whether a stored error is the service-mode teardown marker, in either wording. */
+export function isServiceModeProvisioningError(error) {
+    return error === CUSTOM_DOMAINS_SERVICE_MODE_MESSAGE || error === LEGACY_SERVICE_MODE_MESSAGE;
+}
+// Written when the platform has no fallback script, so nothing can create, re-adopt or tear
+// down this domain's route.
+export const CUSTOM_DOMAINS_NOT_CONFIGURED_MESSAGE = "Custom domains are not fully configured on this platform.";
+// Written when another script's route already holds the hostname.
+export const CUSTOM_DOMAIN_ROUTE_CONFLICT_MESSAGE = "This domain is already claimed elsewhere on the platform. Contact support to release it.";
+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 = zoneApexFor(domain.hostname, domain.dnsCheck?.zone);
+    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" || check === "doubled" ? false : null,
+            check,
+            ...(check === "doubled" && seen?.doubledAt ? { doubledAt: seen.doubledAt } : {}),
+            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.doubledAt)
+        return "doubled";
+    if (seen.current.length === 0)
+        return "missing";
+    if (atApex && seen.current.every((value) => IP_ADDRESS.test(value.trim())))
+        return "apex_addresses";
+    return "different";
+}
+// Unproven is decided by `ok`, not by listing check values: a check this code does not know yet
+// carries ok null and so reads as unknown, never as found. The one exception is an apex
+// answering with addresses, which the platform's own active routing vouches for.
+function isUnproven(record, routingActive) {
+    if (record.ok !== null)
+        return false;
+    return !(record.check === "apex_addresses" && routingActive);
+}
+/**
+ * The `www.<domain>` to connect instead, when this hostname is a bare domain whose DNS host
+ * cannot point a root at a hostname at all (#1996): GoDaddy, Route 53, IONOS, Wix. Read only
+ * from a host the check both named and identified, so an unknown host, an older server and a
+ * domain with no check keep the ordinary records. Routing that is already active is the
+ * platform's own evidence that the root record exists, and wins over the profile.
+ */
+export function rootUnsupportedWwwHostname(domain) {
+    const check = domain.dnsCheck;
+    if (!check?.provider || domain.routingStatus === "active")
+        return null;
+    if (dnsProviderProfile(check.providerId)?.apex.support !== "none")
+        return null;
+    const host = domain.hostname.toLowerCase().replace(/\.$/, "");
+    return host === zoneApexFor(host, check.zone) ? `www.${host}` : null;
+}
+/**
+ * Whether a domain's instructions show "connect www instead" in place of the root record. It
+ * reads the status's own next step, so the display and the status cannot disagree: routing
+ * that is already active, an unknown host or an older server never show it, and a server's
+ * verdict is honoured even for a host this copy's table does not know.
+ */
+export function showsUseWww(next) {
+    return next?.action === "use_www";
+}
+export function deriveDomainState(domain, records = domainRecordStatuses(domain)) {
+    if (domain.provisioningError === CUSTOM_DOMAIN_EXPIRED_MESSAGE)
+        return "expired";
+    if (domain.routingStatus === "failed" || domain.tlsStatus === "failed" || domain.provisioningError)
+        return "failed";
+    if (domain.routingStatus === "active" && domain.tlsStatus === "active")
+        return "live";
+    // No record the owner can publish will finish this domain: it waits on the owner choosing www.
+    if (rootUnsupportedWwwHostname(domain))
+        return "waiting_for_dns";
+    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) => isUnproven(record, routingActive));
+    if (unproven || (!domain.dnsCheck && required.length === 0)) {
+        // Routing still pending is the platform's own evidence that it has not seen the records.
+        return routingActive ? "dns_unverified" : "waiting_for_dns";
+    }
+    return "issuing_certificate";
+}
+function nextRecord(record) {
+    const action = record.ok === false ? (record.check === "different" && record.type !== "TXT" ? "replace" : "add") : "confirm";
+    return { type: record.type, host: record.fqdn, value: record.expected, action, check: record.check };
+}
+// Who controls the CAA record that decides, which decides the advice: in the owner's own zone
+// they can add an entry; at a CNAME target only whoever runs that name can; and when the
+// resolver did not say, nothing is handed over to edit at a name the owner may not control.
+function caaNext(caa) {
+    const summary = {
+        recordName: caa.recordName,
+        ...(caa.via ? { via: caa.via } : {}),
+        ...(caa.ownerUnknown ? { ownerUnknown: true } : {}),
+        platformIssuers: caa.platformIssuers,
+    };
+    if (caa.via)
+        return { who: "owner", action: "ask_caa_controller", caa: summary };
+    if (caa.ownerUnknown)
+        return { who: "owner", action: "check_caa", caa: summary };
+    const issuer = caa.platformIssuers[0];
+    return {
+        who: "owner",
+        action: "allow_ca_in_your_zone",
+        caa: summary,
+        ...(issuer ? { records: [{ type: "CAA", host: caa.recordName, value: `0 issue "${issuer}"`, action: "add", check: "missing" }] } : {}),
+    };
+}
+/**
+ * The state, why, and the one next step. `state` is exactly deriveDomainState's; `reason` and
+ * `next` only refine it. Two rules hold throughout: a record nobody looked at is never called
+ * missing (it gets confirm_records, never add), and nothing here restarts validation or
+ * suggests that a restart speeds things up - Start over is named only for a failed certificate.
+ */
+export function deriveDomainStatus(domain, options = {}) {
+    const records = domainRecordStatuses(domain);
+    const state = deriveDomainState(domain, records);
+    const source = domain.providerMessageSource === "certificate_authority" ? "certificate_authority" : "hostname";
+    // A hostname's own note while the owner is still publishing records is the expected "does not
+    // CNAME to this zone": it says nothing the records table does not, so it is not surfaced there.
+    const showMessage = Boolean(domain.providerMessage && domain.providerMessageAt) && state !== "live" && !(source === "hostname" && state === "waiting_for_dns");
+    const withMessage = (code) => showMessage ? { code, providerMessage: { text: domain.providerMessage, seenAt: domain.providerMessageAt, source } } : { code };
+    const nextCheckAt = options.nextCheckAt ? { nextCheckAt: options.nextCheckAt } : {};
+    const required = records.filter((record) => !record.optional);
+    if (state === "expired")
+        return { state, reason: withMessage("expired"), next: { who: "owner", action: "add_again" } };
+    if (state === "live")
+        return { state, reason: null, next: { action: "none" } };
+    if (state === "failed") {
+        const error = domain.provisioningError;
+        if (isServiceModeProvisioningError(error)) {
+            return { state, reason: withMessage("service_mode"), next: { who: "owner", action: "change_access_mode" } };
+        }
+        if (error === CUSTOM_DOMAINS_NOT_CONFIGURED_MESSAGE) {
+            return { state, reason: withMessage("platform_not_configured"), next: { who: "platform", action: "contact_support" } };
+        }
+        if (error === CUSTOM_DOMAIN_ROUTE_CONFLICT_MESSAGE) {
+            return { state, reason: withMessage("claimed_elsewhere"), next: { who: "platform", action: "contact_support" } };
+        }
+        if (!error && domain.tlsStatus === "failed") {
+            const fix = required.filter((record) => record.ok === false).map(nextRecord);
+            return {
+                state,
+                reason: withMessage("certificate_failed"),
+                next: { who: "owner", action: "start_over", ...(fix.length > 0 ? { records: fix } : {}) },
+            };
+        }
+        if (!error) {
+            // Routing failed with nothing recorded to say why. Nothing measured says the owner can
+            // fix it, so DNS edits are not prescribed: support is, and Re-check stays available.
+            return { state, reason: withMessage("hostname_failed"), next: { who: "platform", action: "contact_support" } };
+        }
+        // An upstream call threw; the background reconcile retries it, and Re-check retries now.
+        return { state, reason: withMessage("provider_error"), next: { who: "platform", action: "recheck" } };
+    }
+    const www = rootUnsupportedWwwHostname(domain);
+    if (www) {
+        return { state, reason: withMessage("dns_host_cannot_point_root"), next: { who: "owner", action: "use_www", hostname: www } };
+    }
+    if (state === "waiting_for_dns" || state === "dns_unverified") {
+        const wrong = required.filter((record) => record.ok === false);
+        if (wrong.length > 0) {
+            // TXT is never "replace": a name may hold several TXT values, so a missing one is added beside them.
+            const pointsElsewhere = wrong.some((record) => record.type !== "TXT" && record.check === "different");
+            const code = domain.activatedAt
+                ? "dns_changed_after_live"
+                : pointsElsewhere
+                    ? "record_points_elsewhere"
+                    : "records_missing";
+            return {
+                state,
+                reason: withMessage(code),
+                next: { who: "owner", action: pointsElsewhere ? "replace_record" : "add_records", records: wrong.map(nextRecord), ...nextCheckAt },
+            };
+        }
+        const routingActive = domain.routingStatus === "active";
+        const unproven = required.filter((record) => isUnproven(record, routingActive));
+        const code = unproven.length > 0 && unproven.every((record) => record.check === "apex_addresses") ? "apex_unverifiable" : "dns_not_checked";
+        return {
+            state,
+            reason: withMessage(code),
+            next: { who: "owner", action: "confirm_records", ...(unproven.length > 0 ? { records: unproven.map(nextRecord) } : {}), ...nextCheckAt },
+        };
+    }
+    // issuing_certificate: every required record was checked and found.
+    const caa = domain.dnsCheck?.caa;
+    if (caa?.status === "blocks" && caa.recordName) {
+        return { state, reason: withMessage("caa_blocks"), next: caaNext({ ...caa, recordName: caa.recordName }) };
+    }
+    return { state, reason: withMessage("certificate_pending"), next: { who: "platform", action: "wait", ...nextCheckAt } };
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Agent } from "undici";
+import { type DomainNext, type DomainReason, type DomainRecordStatus, type DomainState, type DomainStateDnsCheck, type DomainStateDnsInstruction, type DomainStateInput } from "./domain-state.js";
 import type { AccessGrant, AccessGrantType, AccessProviderKey, AppAccessSettings, AppAccessServiceToken, AppAccessToken, AppDatabase, AppRuntime, AppUserFilesUsage, ContainerImageUploadInstruction, ContainerRegion, Deployment, ManagedFileObject, ManagedFileShare, ManagedFileUsage, Project } from "./cli-types.js";
 export interface DeployOptions {
     directory: string;
@@ -106,6 +107,7 @@ export interface DeletedSiteResult {
     slug: string;
     workers: number;
     customDomains: number;
+    customDomainNames?: string[];
     containerApplications?: number;
     containerImages?: number;
     accessApps: number;
@@ -125,7 +127,7 @@ export interface CreatedServiceToken {
     clientSecret: string;
 }
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-export declare const CLI_VERSION = "0.72.0";
+export declare const CLI_VERSION = "0.78.0";
 type CredentialBackend = "macos-keychain" | "windows-dpapi" | "linux-secret-service" | "file-plaintext" | "none";
 export interface StoredCredentialEntry {
     token: string;
@@ -491,6 +493,7 @@ export declare function dashboardUrlForApiUrl(apiUrl: string): string;
 type CliCommand = {
     kind: "deploy";
     options: DeployOptions;
+    apiUrlFrom: ApiUrlSource;
 } | {
     kind: "version";
 } | {
@@ -621,6 +624,7 @@ type CliCommand = {
 } | {
     kind: "domains";
     owner?: string;
+    apiUrlFrom: ApiUrlSource;
     action: {
         kind: "list";
         site?: string;
@@ -729,64 +733,52 @@ export declare function deploymentsListJson<T extends ListedDeployment>(deployme
         serving: boolean;
     }>;
 };
-export interface CliDnsInstruction {
-    type: string;
-    host: string;
-    value: string;
-    optional?: boolean;
-}
-export interface CliDomainDnsCheck {
-    provider: string | null;
-    nameservers: string[];
-    records: Array<{
-        type: string;
-        host: string;
-        expected: string;
-        current: string[];
-        matches: boolean;
+export { CUSTOM_DOMAIN_EXPIRED_TEXT, deriveDomainState, deriveDomainStatus, domainRecordStatuses, type DomainRecordCheck, type DomainRecordStatus, type DomainState, } from "./domain-state.js";
+export type CliDnsInstruction = DomainStateDnsInstruction;
+export type CliDomainDnsCheck = DomainStateDnsCheck & {
+    advisories?: Array<{
+        code: string;
+        message: string;
     }>;
-}
-export interface CliDomain {
-    hostname: string;
-    routingStatus: string;
-    tlsStatus: string;
-    dnsInstructions: CliDnsInstruction[];
-    provisioningError: string | null;
+};
+export interface CliDomain extends DomainStateInput {
+    dnsCheck?: CliDomainDnsCheck;
     expireAfter?: string | null;
     expiresAt?: string | null;
-    dnsCheck?: CliDomainDnsCheck;
     app?: {
         id: string;
         slug: string;
         name: string;
     };
+    state?: string;
+    reason?: DomainReason | null;
+    next?: DomainNext;
+}
+export interface DomainRecordStatusJson extends DomainRecordStatus {
+    typeAtProvider: string | null;
+    nameAtProvider: string;
+    valueAtProvider: string;
 }
-export type DomainState = "live" | "waiting_for_dns" | "dns_unverified" | "issuing_certificate" | "failed" | "expired";
-export declare const CUSTOM_DOMAIN_EXPIRED_TEXT = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
-export interface DomainRecordStatus {
-    type: string;
-    name: string;
-    fqdn: string;
-    expected: string;
-    current: string[] | null;
-    ok: boolean | null;
-    check: DomainRecordCheck;
-    apex: boolean;
-    optional: boolean;
-}
-export type DomainRecordCheck = "found" | "missing" | "different" | "not_checked" | "apex_addresses";
 export interface DomainStatusJson {
     hostname: string;
     app: string;
-    state: DomainState;
+    state: DomainState | (string & {});
     routing: string;
     tls: string;
     provider: string | null;
+    providerId: string | null;
     nameservers: string[];
-    records: DomainRecordStatus[];
+    zone: string | null;
+    records: DomainRecordStatusJson[];
+    advisories: Array<{
+        code: string;
+        message: string;
+    }>;
     error: string | null;
     expiresAt: string | null;
     checkedAt: string;
+    reason: DomainReason | null;
+    next: DomainNext;
 }
 export declare const DOMAIN_WAIT_EXIT: {
     readonly live: 0;
@@ -794,13 +786,15 @@ export declare const DOMAIN_WAIT_EXIT: {
     readonly platform: 11;
     readonly failed: 20;
 };
-export declare function domainRecordStatuses(domain: CliDomain): DomainRecordStatus[];
-export declare function deriveDomainState(domain: CliDomain, records?: DomainRecordStatus[]): DomainState;
 export declare function domainStatusJson(domain: CliDomain, app: string, checkedAt: string): DomainStatusJson;
-export declare function domainStateLabel(state: DomainState): string;
-export declare function formatDomainStatus(status: DomainStatusJson, options?: {
+export declare function domainStateLabel(state: string): string;
+export declare function domainWaitExitCode(status: Pick<DomainStatusJson, "state" | "next">): number;
+export interface DomainFormatOptions {
     owner?: string;
-}): string[];
+    target?: AccessApiTarget;
+}
+export declare const DNS_PROVIDER_NOTES: Record<string, string>;
+export declare function formatDomainStatus(status: DomainStatusJson, options?: DomainFormatOptions): string[];
 export declare function domainWaitTimeoutMessage(status: DomainStatusJson): string;
 export declare function formatDomainsList(statuses: DomainStatusJson[]): string[];
 export declare class DomainsApiError extends Error {
@@ -838,6 +832,14 @@ export declare function restartDomain(options: DomainCommandOptions & {
 export declare function removeDomain(options: DomainCommandOptions & {
     hostname: string;
 }): Promise<CliDomain | null>;
+export declare const DEPLOY_DOMAINS_TIMEOUT_MS = 4500;
+export declare function deployCustomDomainStatuses(options: ApiOptions & {
+    projectId: string;
+    slug: string;
+    timeoutMs?: number;
+    now?: () => Date;
+}): Promise<DomainStatusJson[] | null>;
+export declare function deployCustomDomainLines(statuses: DomainStatusJson[] | null, slug: string, owner?: string, target?: AccessApiTarget): string[];
 export interface DomainWaitResult {
     status: DomainStatusJson;
     exitCode: number;
@@ -898,5 +900,5 @@ export interface AccessApiTarget {
     apiUrl: string;
     apiUrlFrom: ApiUrlSource;
 }
+export declare function apiUrlFlagFor(target?: AccessApiTarget): string;
 export declare function accessSwitchModeCommand(action: AccessModeChangeAction, target?: AccessApiTarget): string;
-export {};