@prisma/cli 3.0.0-alpha.13 → 3.0.0-alpha.14

package/dist/commands/app/index.js

@@ -2,8 +2,8 @@ import { attachCommandDescriptor } from "../../shell/command-meta.js";
 import { addCompactGlobalFlags, addGlobalFlags } from "../../shell/global-flags.js";
 import { configureRuntimeCommand } from "../../shell/runtime.js";
 import { PREVIEW_BUILD_TYPES } from "../../lib/app/preview-build.js";
-import { runAppBuild, runAppDeploy, runAppListDeploys, runAppListEnv, runAppLogs, runAppOpen, runAppPromote, runAppRemove, runAppRollback, runAppRun, runAppShow, runAppShowDeploy, runAppUpdateEnv } from "../../controllers/app.js";
-import { renderAppBuild, renderAppDeploy, renderAppListDeploys, renderAppListEnv, renderAppOpen, renderAppPromote, renderAppRemove, renderAppRollback, renderAppRun, renderAppShow, renderAppShowDeploy, renderAppUpdateEnv, serializeAppBuild, serializeAppDeploy, serializeAppListDeploys, serializeAppListEnv, serializeAppOpen, serializeAppPromote, serializeAppRemove, serializeAppRollback, serializeAppRun, serializeAppShow, serializeAppShowDeploy, serializeAppUpdateEnv } from "../../presenters/app.js";
+import { runAppBuild, runAppDeploy, runAppDomainAdd, runAppDomainRemove, runAppDomainRetry, runAppDomainShow, runAppDomainWait, runAppListDeploys, runAppListEnv, runAppLogs, runAppOpen, runAppPromote, runAppRemove, runAppRollback, runAppRun, runAppShow, runAppShowDeploy, runAppUpdateEnv } from "../../controllers/app.js";
+import { renderAppBuild, renderAppDeploy, renderAppDomainAdd, renderAppDomainRemove, renderAppDomainRetry, renderAppDomainShow, renderAppListDeploys, renderAppListEnv, renderAppOpen, renderAppPromote, renderAppRemove, renderAppRollback, renderAppRun, renderAppShow, renderAppShowDeploy, renderAppUpdateEnv, serializeAppBuild, serializeAppDeploy, serializeAppDomainAdd, serializeAppDomainRemove, serializeAppDomainRetry, serializeAppDomainShow, serializeAppListDeploys, serializeAppListEnv, serializeAppOpen, serializeAppPromote, serializeAppRemove, serializeAppRollback, serializeAppRun, serializeAppShow, serializeAppShowDeploy, serializeAppUpdateEnv } from "../../presenters/app.js";
 import { runCommand, runStreamingCommand } from "../../shell/command-runner.js";
 import { Command, Option } from "commander";
 //#region src/commands/app/index.ts
@@ -17,6 +17,7 @@ function createAppCommand(runtime) {
 	app.addCommand(createListEnvCommand(runtime));
 	app.addCommand(createShowCommand(runtime));
 	app.addCommand(createOpenCommand(runtime));
+	app.addCommand(createDomainCommand(runtime));
 	app.addCommand(createLogsCommand(runtime));
 	app.addCommand(createListDeploysCommand(runtime));
 	app.addCommand(createShowDeployCommand(runtime));
@@ -147,6 +148,119 @@ function createOpenCommand(runtime) {
 	});
 	return command;
 }
+function createDomainCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("domain"), runtime), "app.domain");
+	addCompactGlobalFlags(command);
+	command.addCommand(createDomainAddCommand(runtime));
+	command.addCommand(createDomainShowCommand(runtime));
+	command.addCommand(createDomainRemoveCommand(runtime));
+	command.addCommand(createDomainRetryCommand(runtime));
+	command.addCommand(createDomainWaitCommand(runtime));
+	return command;
+}
+function addDomainTargetOptions(command) {
+	return command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name")).addOption(new Option("--branch <name>", "Branch name"));
+}
+function createDomainAddCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("add"), runtime), "app.domain.add");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
+	addGlobalFlags(command);
+	command.action(async (hostname, options) => {
+		const appName = options.app;
+		const projectRef = options.project;
+		const branchName = options.branch;
+		await runCommand(runtime, "app.domain.add", options, (context) => runAppDomainAdd(context, hostname, {
+			appName,
+			projectRef,
+			branchName
+		}), {
+			renderHuman: (context, descriptor, result) => renderAppDomainAdd(context, descriptor, result),
+			renderJson: (result) => serializeAppDomainAdd(result)
+		});
+	});
+	return command;
+}
+function createDomainShowCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("show"), runtime), "app.domain.show");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
+	addGlobalFlags(command);
+	command.action(async (hostname, options) => {
+		const appName = options.app;
+		const projectRef = options.project;
+		const branchName = options.branch;
+		await runCommand(runtime, "app.domain.show", options, (context) => runAppDomainShow(context, hostname, {
+			appName,
+			projectRef,
+			branchName
+		}), {
+			renderHuman: (context, descriptor, result) => renderAppDomainShow(context, descriptor, result),
+			renderJson: (result) => serializeAppDomainShow(result)
+		});
+	});
+	return command;
+}
+function createDomainRemoveCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("remove"), runtime), "app.domain.remove");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
+	addGlobalFlags(command);
+	command.action(async (hostname, options) => {
+		const appName = options.app;
+		const projectRef = options.project;
+		const branchName = options.branch;
+		await runCommand(runtime, "app.domain.remove", options, (context) => runAppDomainRemove(context, hostname, {
+			appName,
+			projectRef,
+			branchName
+		}), {
+			renderHuman: (context, descriptor, result) => renderAppDomainRemove(context, descriptor, result),
+			renderJson: (result) => serializeAppDomainRemove(result)
+		});
+	});
+	return command;
+}
+function createDomainRetryCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("retry"), runtime), "app.domain.retry");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
+	addGlobalFlags(command);
+	command.action(async (hostname, options) => {
+		const appName = options.app;
+		const projectRef = options.project;
+		const branchName = options.branch;
+		await runCommand(runtime, "app.domain.retry", options, (context) => runAppDomainRetry(context, hostname, {
+			appName,
+			projectRef,
+			branchName
+		}), {
+			renderHuman: (context, descriptor, result) => renderAppDomainRetry(context, descriptor, result),
+			renderJson: (result) => serializeAppDomainRetry(result)
+		});
+	});
+	return command;
+}
+function createDomainWaitCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("wait"), runtime), "app.domain.wait");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
+	command.addOption(new Option("--timeout <duration>", "Maximum time to wait").default("15m"));
+	addGlobalFlags(command);
+	command.action(async (hostname, options) => {
+		const appName = options.app;
+		const projectRef = options.project;
+		const branchName = options.branch;
+		const timeout = options.timeout;
+		await runStreamingCommand(runtime, "app.domain.wait", options, (context) => runAppDomainWait(context, hostname, {
+			appName,
+			projectRef,
+			branchName,
+			timeout
+		}));
+	});
+	return command;
+}
 function createLogsCommand(runtime) {
 	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("logs"), runtime), "app.logs");
 	command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name")).addOption(new Option("--deployment <id>", "Deployment id"));

package/dist/controllers/app.js

@@ -16,7 +16,8 @@ import { LOCAL_RESOLUTION_PIN_RELATIVE_PATH, ensureLocalResolutionPinGitignore,
 import { PREVIEW_BUILD_TYPES, RESOLVED_PREVIEW_BUILD_TYPES, executePreviewBuild } from "../lib/app/preview-build.js";
 import { PREVIEW_DEFAULT_REGION } from "../lib/app/preview-interaction.js";
 import { createPreviewDeployProgress, createPreviewDeployProgressState, createPreviewPromoteProgress, createPreviewUpdateEnvProgress } from "../lib/app/preview-progress.js";
-import { createPreviewAppProvider } from "../lib/app/preview-provider.js";
+import { PreviewDomainApiError, createPreviewAppProvider } from "../lib/app/preview-provider.js";
+import { formatDomainFailureFix } from "../lib/app/domain-guidance.js";
 import { createSelectPromptPort } from "./select-prompt-port.js";
 import { requireAuthenticatedAuthState } from "./auth.js";
 import { listRealWorkspaceProjects } from "./project.js";
@@ -479,6 +480,132 @@ async function runAppOpen(context, appName, projectRef) {
 		nextSteps: ["prisma-cli app show", `prisma-cli app show-deploy ${liveDeployment.id}`]
 	};
 }
+async function runAppDomainAdd(context, hostname, options) {
+	const normalizedHostname = normalizeDomainHostname(hostname);
+	const target = await resolveAppDomainTarget(context, options);
+	const added = await target.provider.addDomain({
+		appId: target.app.id,
+		hostname: normalizedHostname
+	}).catch((error) => {
+		throw domainCommandError("add", error, normalizedHostname);
+	});
+	return {
+		command: "app.domain.add",
+		result: {
+			...target.resultTarget,
+			domain: toAppDomainSummary(added.domain),
+			existing: added.existing
+		},
+		warnings: [],
+		nextSteps: [`prisma-cli app domain wait ${normalizedHostname}`, `prisma-cli app domain show ${normalizedHostname}`]
+	};
+}
+async function runAppDomainShow(context, hostname, options) {
+	const normalizedHostname = normalizeDomainHostname(hostname);
+	const target = await resolveAppDomainTarget(context, options);
+	const domain = await resolveDomainByHostname(target.provider, target.app.id, normalizedHostname, "show");
+	const detail = await target.provider.showDomain(domain.id).catch((error) => {
+		throw domainCommandError("show", error, normalizedHostname);
+	});
+	return {
+		command: "app.domain.show",
+		result: {
+			...target.resultTarget,
+			domain: toAppDomainSummary(detail)
+		},
+		warnings: [],
+		nextSteps: buildDomainShowNextSteps(detail)
+	};
+}
+async function runAppDomainRemove(context, hostname, options) {
+	const normalizedHostname = normalizeDomainHostname(hostname);
+	const target = await resolveAppDomainTarget(context, options);
+	const domain = await resolveDomainByHostname(target.provider, target.app.id, normalizedHostname, "remove");
+	await confirmDomainRemoval(context, target.resultTarget, normalizedHostname);
+	await target.provider.removeDomain(domain.id).catch((error) => {
+		throw domainCommandError("remove", error, normalizedHostname);
+	});
+	return {
+		command: "app.domain.remove",
+		result: {
+			...target.resultTarget,
+			hostname: normalizedHostname,
+			removed: true
+		},
+		warnings: [],
+		nextSteps: []
+	};
+}
+async function runAppDomainRetry(context, hostname, options) {
+	const normalizedHostname = normalizeDomainHostname(hostname);
+	const target = await resolveAppDomainTarget(context, options);
+	const domain = await resolveDomainByHostname(target.provider, target.app.id, normalizedHostname, "retry");
+	const retried = await target.provider.retryDomain(domain.id).catch((error) => {
+		throw domainCommandError("retry", error, normalizedHostname);
+	});
+	return {
+		command: "app.domain.retry",
+		result: {
+			...target.resultTarget,
+			domain: toAppDomainSummary(retried)
+		},
+		warnings: [],
+		nextSteps: [`prisma-cli app domain wait ${normalizedHostname}`]
+	};
+}
+async function runAppDomainWait(context, hostname, options) {
+	const normalizedHostname = normalizeDomainHostname(hostname);
+	const timeoutMs = parseDomainWaitTimeout(options?.timeout);
+	const target = await resolveAppDomainTarget(context, options);
+	const domain = await resolveDomainByHostname(target.provider, target.app.id, normalizedHostname, "wait");
+	if (!context.flags.json && !context.flags.quiet) context.output.stderr.write([
+		`app domain wait -> Waiting for ${normalizedHostname} to become active.`,
+		"",
+		`Workspace: ${target.resultTarget.workspace.name}   Project: ${target.resultTarget.project.name}   Branch: ${target.resultTarget.branch.name}   App: ${target.resultTarget.app.name}`,
+		""
+	].join("\n"));
+	const start = Date.now();
+	const deadline = start + timeoutMs;
+	const pollIntervalMs = readDomainWaitPollIntervalMs(context);
+	let lastStatus = null;
+	let current = domain;
+	while (true) {
+		emitDomainWaitStatus(context, {
+			hostname: normalizedHostname,
+			domainId: current.id,
+			previousStatus: lastStatus,
+			status: current.status,
+			elapsedMs: Date.now() - start
+		});
+		lastStatus = current.status;
+		if (current.status === "active") {
+			if (!context.flags.json && !context.flags.quiet) context.output.stderr.write(`\n${normalizedHostname} is live at https://${normalizedHostname}\n`);
+			return;
+		}
+		if (current.status === "failed") throw new CliError({
+			code: "DOMAIN_VERIFICATION_FAILED",
+			domain: "app",
+			summary: `Custom domain "${normalizedHostname}" failed verification`,
+			why: formatDomainFailureWhy(current),
+			fix: formatDomainFailureFix(current) ?? `Run prisma-cli app domain retry ${normalizedHostname}.`,
+			exitCode: 1,
+			nextSteps: [`prisma-cli app domain show ${normalizedHostname}`, `prisma-cli app domain retry ${normalizedHostname}`]
+		});
+		if (timeoutMs === 0 || Date.now() >= deadline) throw new CliError({
+			code: "DOMAIN_VERIFICATION_TIMEOUT",
+			domain: "app",
+			summary: `Timed out waiting for "${normalizedHostname}" to become active`,
+			why: `The domain is still "${current.status}".`,
+			fix: `Run prisma-cli app domain show ${normalizedHostname} to inspect the current status, or retry wait with a longer --timeout.`,
+			exitCode: 1,
+			nextSteps: [`prisma-cli app domain show ${normalizedHostname}`]
+		});
+		await sleep(Math.min(pollIntervalMs, Math.max(deadline - Date.now(), 0)));
+		current = await target.provider.showDomain(current.id).catch((error) => {
+			throw domainCommandError("wait", error, normalizedHostname);
+		});
+	}
+}
 async function runAppLogs(context, appName, deploymentId, projectRef) {
 	ensurePreviewAppMode(context);
 	const { provider, target: resolvedTarget, projectId } = await requireProviderAndProjectContext(context, projectRef);
@@ -708,6 +835,303 @@ async function runAppRemove(context, appName, projectRef) {
 		nextSteps: ["prisma-cli app deploy", "prisma-cli app list-deploys"]
 	};
 }
+async function resolveAppDomainTarget(context, options) {
+	ensurePreviewAppMode(context);
+	const branch = resolveDomainBranch(options?.branchName);
+	if (toBranchKind(branch.name) !== "production") throw new CliError({
+		code: "BRANCH_NOT_DEPLOYABLE",
+		domain: "branch",
+		summary: "Custom domains require the production branch",
+		why: `Custom domains on preview branch "${branch.name}" are not supported in Public Beta.`,
+		fix: "Use --branch production, or attach the domain after promoting/deploying to the production branch.",
+		exitCode: 2,
+		nextSteps: ["prisma-cli app domain add <hostname> --branch production"]
+	});
+	const envProjectId = readDeployEnvOverride(context, PRISMA_PROJECT_ID_ENV_VAR);
+	const envAppId = readDeployEnvOverride(context, PRISMA_APP_ID_ENV_VAR);
+	const skipLocalPin = Boolean(envProjectId || envAppId);
+	const localPin = skipLocalPin ? { kind: "missing" } : await readLocalResolutionPin(context.runtime.cwd);
+	if (!skipLocalPin && localPin.kind === "invalid") throw localResolutionPinStaleError();
+	const { provider, target, projectId } = await requireProviderAndDeployProjectContext(context, options?.projectRef, {
+		allowCreate: false,
+		branch,
+		envProjectId,
+		localPin
+	});
+	const selectedApp = await resolveDomainAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), {
+		explicitAppName: options?.appName,
+		explicitAppId: envAppId
+	});
+	await context.stateStore.setSelectedApp(projectId, {
+		id: selectedApp.id,
+		name: selectedApp.name
+	});
+	return {
+		provider,
+		app: selectedApp,
+		resultTarget: {
+			workspace: target.workspace,
+			project: target.project,
+			branch: target.branch,
+			app: {
+				id: selectedApp.id,
+				name: selectedApp.name
+			}
+		}
+	};
+}
+function resolveDomainBranch(explicitBranchName) {
+	return {
+		name: explicitBranchName?.trim() || "production",
+		annotation: explicitBranchName ? "set by --branch" : "production default"
+	};
+}
+async function resolveDomainAppSelection(context, projectId, apps, options) {
+	if (options.explicitAppId) {
+		const matched = apps.find((app) => app.id === options.explicitAppId);
+		if (!matched) throw usageError("Selected app does not exist in the resolved production branch", `The app "${options.explicitAppId}" from ${PRISMA_APP_ID_ENV_VAR} could not be found in resolved project "${projectId}".`, `Unset ${PRISMA_APP_ID_ENV_VAR}, pass --app <name>, or deploy the app on the production branch.`, ["prisma-cli app deploy --branch production"], "app");
+		return matched;
+	}
+	const selectedApp = await resolveExistingAppSelection(context, projectId, apps, options.explicitAppName);
+	if (selectedApp) return selectedApp;
+	throw usageError("Custom domain requires an existing app on the production branch", "The resolved production branch does not have an app that can receive a custom domain.", "Deploy or promote an app to production first, then rerun the domain command.", ["prisma-cli app deploy --branch production", "prisma-cli app show"], "app");
+}
+async function resolveDomainByHostname(provider, appId, hostname, command) {
+	const matched = (await provider.listDomains(appId).catch((error) => {
+		throw domainCommandError(command, error, hostname);
+	})).find((domain) => sameDomainHostname(domain.hostname, hostname));
+	if (matched) return matched;
+	throw domainNotFoundError(hostname);
+}
+function normalizeDomainHostname(hostname) {
+	const normalized = hostname.trim().replace(/\.$/, "").toLowerCase();
+	if (!isValidDomainHostname(normalized)) throw new CliError({
+		code: "DOMAIN_HOSTNAME_INVALID",
+		domain: "app",
+		summary: `Invalid custom domain "${hostname}"`,
+		why: "Custom domains must be valid hostnames without protocol, path, wildcard, or port.",
+		fix: "Pass a hostname like shop.acme.com.",
+		exitCode: 2,
+		nextSteps: ["prisma-cli app domain add shop.acme.com"]
+	});
+	return normalized;
+}
+function isValidDomainHostname(hostname) {
+	if (hostname.length < 1 || hostname.length > 253) return false;
+	if (hostname.includes("://") || hostname.includes("/") || hostname.includes(":") || hostname.startsWith("*.")) return false;
+	const labels = hostname.split(".");
+	if (labels.length < 2) return false;
+	return labels.every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
+}
+function sameDomainHostname(left, right) {
+	return left.trim().replace(/\.$/, "").toLowerCase() === right.trim().replace(/\.$/, "").toLowerCase();
+}
+function toAppDomainSummary(domain) {
+	return {
+		id: domain.id,
+		type: domain.type,
+		url: domain.url,
+		hostname: domain.hostname,
+		computeServiceId: domain.computeServiceId,
+		status: domain.status,
+		foundryStatus: domain.foundryStatus,
+		failureReason: domain.failureReason,
+		failureCategory: domain.failureCategory,
+		certExpiresAt: domain.certExpiresAt,
+		createdAt: domain.createdAt,
+		updatedAt: domain.updatedAt,
+		dnsRecords: toAppDomainDnsRecords(domain)
+	};
+}
+function toAppDomainDnsRecords(domain) {
+	return domain.dnsRecords.map((record) => ({
+		type: record.type,
+		name: record.name,
+		value: record.value,
+		ttl: record.ttl
+	}));
+}
+function buildDomainShowNextSteps(domain) {
+	if (domain.status === "active") return [];
+	if (domain.status === "failed") return [`prisma-cli app domain retry ${domain.hostname}`];
+	return [`prisma-cli app domain wait ${domain.hostname}`];
+}
+async function confirmDomainRemoval(context, target, hostname) {
+	if (context.flags.yes) return;
+	if (!canPrompt(context)) throw new CliError({
+		code: "CONFIRMATION_REQUIRED",
+		domain: "app",
+		summary: "Custom domain removal requires confirmation in the current mode",
+		why: "This command detaches a domain and cannot prompt for confirmation in the current mode.",
+		fix: `Pass --yes to confirm removal of "${hostname}", or rerun prisma-cli app domain remove in an interactive TTY.`,
+		exitCode: 1,
+		nextSteps: [`prisma-cli app domain remove ${hostname} --app ${target.app.name} --yes`]
+	});
+	if (!await confirmPrompt({
+		input: context.runtime.stdin,
+		output: context.output.stderr,
+		message: `Detach ${hostname} from App "${target.app.name}"?`,
+		initialValue: false
+	})) throw usageError("Custom domain removal canceled", "The command was canceled before the domain was detached.", "Rerun the command and confirm removal, or pass --yes.", [`prisma-cli app domain remove ${hostname} --app ${target.app.name} --yes`], "app");
+}
+function domainCommandError(command, error, hostname) {
+	if (error instanceof PreviewDomainApiError) {
+		if (command === "add" && (error.status === 400 || error.status === 422) && isDomainDnsError(error)) return domainDnsNotConfiguredError(hostname, error);
+		if (command === "add" && error.status === 400) return new CliError({
+			code: "DOMAIN_HOSTNAME_INVALID",
+			domain: "app",
+			summary: `Invalid custom domain "${hostname}"`,
+			why: error.message,
+			fix: "Pass a valid hostname like shop.acme.com and make sure DNS can be verified.",
+			debug: formatDebugDetails(error),
+			exitCode: 2,
+			nextSteps: ["prisma-cli app domain add shop.acme.com"]
+		});
+		if (command === "add" && (error.status === 429 || isDomainQuotaError(error))) return new CliError({
+			code: "DOMAIN_QUOTA_EXCEEDED",
+			domain: "app",
+			summary: "Custom domain quota exceeded",
+			why: error.message,
+			fix: "Remove an existing custom domain before adding another one.",
+			debug: formatDebugDetails(error),
+			exitCode: 1,
+			nextSteps: ["prisma-cli app domain remove <hostname>"]
+		});
+		if (command === "add" && error.status === 409) return domainAlreadyRegisteredError(hostname, error);
+		if (command === "add" && error.status === 422) return new CliError({
+			code: "NO_DEPLOYMENTS",
+			domain: "app",
+			summary: "Custom domain requires a live production deployment",
+			why: "The selected production app does not have a promoted version that can receive a custom domain.",
+			fix: "Deploy the app to the production branch, then rerun the domain command.",
+			debug: formatDebugDetails(error),
+			exitCode: 1,
+			nextSteps: ["prisma-cli app deploy --branch production", `prisma-cli app domain add ${hostname}`]
+		});
+		if ((command === "show" || command === "remove" || command === "retry" || command === "wait") && error.status === 404) return domainNotFoundError(hostname);
+		if (command === "retry" && error.status === 409) return new CliError({
+			code: "DOMAIN_RETRY_NOT_ELIGIBLE",
+			domain: "app",
+			summary: `Custom domain "${hostname}" is not eligible for retry`,
+			why: error.message,
+			fix: "Wait for the current verification or TLS step to finish, then rerun retry if the domain fails.",
+			debug: formatDebugDetails(error),
+			exitCode: 1,
+			nextSteps: [`prisma-cli app domain show ${hostname}`]
+		});
+	}
+	return new CliError({
+		code: "DEPLOY_FAILED",
+		domain: "app",
+		summary: `Custom domain ${command} failed`,
+		why: error instanceof Error ? error.message : String(error),
+		fix: "Retry the command, or rerun with --trace for more detailed diagnostics.",
+		debug: formatDebugDetails(error),
+		exitCode: 1,
+		nextSteps: [`prisma-cli app domain show ${hostname}`]
+	});
+}
+function isDomainQuotaError(error) {
+	if (error.status !== 409) return false;
+	const text = `${error.message} ${error.hint ?? ""}`.toLowerCase();
+	return text.includes("quota") || text.includes("maximum") || text.includes("limit");
+}
+function domainAlreadyRegisteredError(hostname, error) {
+	return new CliError({
+		code: "DOMAIN_ALREADY_REGISTERED",
+		domain: "app",
+		summary: `Custom domain "${hostname}" is already registered`,
+		why: error.hint ?? error.message,
+		fix: "Select the app that owns this hostname and remove it there, or contact support if you cannot access it.",
+		debug: formatDebugDetails(error),
+		exitCode: 1,
+		nextSteps: [`Select the owning app and remove ${hostname} there.`, "Contact Prisma support if you cannot access the owning app."]
+	});
+}
+function isDomainDnsError(error) {
+	const text = `${error.message} ${error.hint ?? ""}`.toLowerCase();
+	return text.includes("dns is not configured") || text.includes("dns verification failed") || text.includes("no cname") || text.includes("cname record") || text.includes("no a/aaaa") || /\bcname(?:s)?\s+to\b/.test(text);
+}
+function domainDnsNotConfiguredError(hostname, error) {
+	const target = extractDomainDnsTarget(error);
+	const record = target ? `CNAME ${hostname} -> ${target}` : null;
+	return new CliError({
+		code: "DOMAIN_DNS_NOT_CONFIGURED",
+		domain: "app",
+		summary: `DNS is not configured for "${hostname}"`,
+		why: error.hint ?? error.message,
+		fix: record ? `Add ${record} at your DNS provider, then rerun the domain command.` : "The platform did not return the required DNS target. Re-run with --trace for the underlying API response details.",
+		debug: formatDebugDetails(error),
+		exitCode: 1,
+		nextSteps: record ? [`add ${record}`, `prisma-cli app domain add ${hostname}`] : [`prisma-cli app domain add ${hostname} --trace`]
+	});
+}
+function extractDomainDnsTarget(error) {
+	const text = `${error.hint ?? ""} ${error.message}`;
+	return /\b((?:[a-z0-9-]+\.)+prisma\.build)\b/i.exec(text)?.[1]?.toLowerCase() ?? null;
+}
+function domainNotFoundError(hostname) {
+	return new CliError({
+		code: "DOMAIN_NOT_FOUND",
+		domain: "app",
+		summary: `Custom domain "${hostname}" not found`,
+		why: "The hostname is not attached to the selected app.",
+		fix: "Check the hostname and selected app, or add the domain first.",
+		exitCode: 1,
+		nextSteps: [`prisma-cli app domain add ${hostname}`]
+	});
+}
+function formatDomainFailureWhy(domain) {
+	if (domain.failureReason) return domain.failureCategory ? `${domain.failureCategory}: ${domain.failureReason}` : domain.failureReason;
+	return "The platform reported a terminal failed state for this custom domain.";
+}
+function parseDomainWaitTimeout(value) {
+	if (!value) return 900 * 1e3;
+	const trimmed = value.trim().toLowerCase();
+	if (trimmed === "0") return 0;
+	const match = /^(\d+)(ms|s|m|h)$/.exec(trimmed);
+	if (!match) throw usageError(`Invalid timeout "${value}"`, "Timeout must be a duration such as 0, 30s, 15m, or 1h.", "Pass --timeout 15m, or --timeout 0 to poll once.", ["prisma-cli app domain wait shop.acme.com --timeout 15m"], "app");
+	const amount = Number.parseInt(match[1], 10);
+	const unit = match[2];
+	return amount * (unit === "h" ? 3600 * 1e3 : unit === "m" ? 60 * 1e3 : unit === "s" ? 1e3 : 1);
+}
+function readDomainWaitPollIntervalMs(context) {
+	const raw = context.runtime.env.PRISMA_CLI_DOMAIN_WAIT_POLL_MS;
+	if (!raw) return 5e3;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : 5e3;
+}
+function emitDomainWaitStatus(context, event) {
+	if (context.flags.json) {
+		writeJsonEvent(context.output, {
+			type: "status",
+			command: "app.domain.wait",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			data: {
+				hostname: event.hostname,
+				domainId: event.domainId,
+				previousStatus: event.previousStatus,
+				status: event.status,
+				elapsedMs: event.elapsedMs
+			}
+		});
+		return;
+	}
+	if (context.flags.quiet) return;
+	if (event.previousStatus === event.status) return;
+	const transition = event.previousStatus ? `${event.previousStatus} -> ${event.status}` : event.status;
+	context.output.stderr.write(`  ${transition} (${formatElapsed(event.elapsedMs)})\n`);
+}
+function formatElapsed(milliseconds) {
+	const seconds = Math.max(Math.floor(milliseconds / 1e3), 0);
+	const minutes = Math.floor(seconds / 60);
+	const remainingSeconds = seconds % 60;
+	return `${minutes}:${String(remainingSeconds).padStart(2, "0")}`;
+}
+async function sleep(milliseconds) {
+	if (milliseconds <= 0) return;
+	await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
 async function resolveDeployAppSelection(context, projectId, apps, options) {
 	if (options.explicitAppName) {
 		const matches = findAppsByName(apps, options.explicitAppName);
@@ -1688,4 +2112,4 @@ function emitLegacyEnvDeprecationWarning(context, legacyCommand, replacement) {
 	context.runtime.stderr.write(`${message}\n`);
 }
 //#endregion
-export { runAppBuild, runAppDeploy, runAppListDeploys, runAppListEnv, runAppLogs, runAppOpen, runAppPromote, runAppRemove, runAppRollback, runAppRun, runAppShow, runAppShowDeploy, runAppUpdateEnv };
+export { runAppBuild, runAppDeploy, runAppDomainAdd, runAppDomainRemove, runAppDomainRetry, runAppDomainShow, runAppDomainWait, runAppListDeploys, runAppListEnv, runAppLogs, runAppOpen, runAppPromote, runAppRemove, runAppRollback, runAppRun, runAppShow, runAppShowDeploy, runAppUpdateEnv };

package/dist/lib/app/domain-guidance.js

@@ -0,0 +1,14 @@
+//#region src/lib/app/domain-guidance.ts
+function formatDomainFailureFix(domain) {
+	if (domain.status !== "failed") return null;
+	const dnsRecord = domain.dnsRecords[0];
+	if (domain.failureCategory === "dns") {
+		if (dnsRecord) return `Add ${dnsRecord.type} ${dnsRecord.name} -> ${dnsRecord.value}, then run prisma-cli app domain retry ${domain.hostname}.`;
+		return `DNS verification failed, but the platform did not return a DNS record. Run prisma-cli app domain show ${domain.hostname} later, then retry when the DNS target is available.`;
+	}
+	if (domain.failureCategory === "acme") return `Retry TLS issuance with prisma-cli app domain retry ${domain.hostname}. Contact support if it fails again.`;
+	if (domain.failureCategory === "storage") return `Retry provisioning with prisma-cli app domain retry ${domain.hostname}. Contact support if it fails again.`;
+	return `Run prisma-cli app domain retry ${domain.hostname}. Contact support if it fails again.`;
+}
+//#endregion
+export { formatDomainFailureFix };

package/dist/lib/app/preview-provider.js

@@ -3,6 +3,18 @@ import { PreviewBuildStrategy } from "./preview-build.js";
 import path from "node:path";
 import { ApiError, CancelledError, ComputeClient, streamLogs } from "@prisma/compute-sdk";
 //#region src/lib/app/preview-provider.ts
+var PreviewDomainApiError = class extends Error {
+	status;
+	code;
+	hint;
+	constructor(options) {
+		super(`${options.summary}: ${options.message}${options.hint ? ` ${options.hint}` : ""}`);
+		this.name = "PreviewDomainApiError";
+		this.status = options.status;
+		this.code = options.code ?? null;
+		this.hint = options.hint ?? null;
+	}
+};
 function createPreviewAppProvider(client, options) {
 	const sdk = new ComputeClient(client);
 	return {
@@ -35,6 +47,43 @@ function createPreviewAppProvider(client, options) {
 				name: appResult.value.name
 			};
 		},
+		async listDomains(appId) {
+			return listComputeServiceDomains(client, appId);
+		},
+		async addDomain(options) {
+			const result = await client.POST("/v1/compute-services/{computeServiceId}/domains", {
+				params: { path: { computeServiceId: options.appId } },
+				body: { hostname: options.hostname }
+			});
+			if (result.error || !result.data) {
+				if (result.response.status === 409) {
+					const existing = (await listComputeServiceDomains(client, options.appId)).find((domain) => sameHostname(domain.hostname, options.hostname));
+					if (existing) return {
+						domain: existing,
+						existing: true
+					};
+				}
+				throw domainApiCallError("Failed to add custom domain", result.response, result.error);
+			}
+			return {
+				domain: normalizeDomainRecord(result.data.data),
+				existing: false
+			};
+		},
+		async showDomain(domainId) {
+			const result = await client.GET("/v1/domains/{domainId}", { params: { path: { domainId } } });
+			if (result.error || !result.data) throw domainApiCallError("Failed to show custom domain", result.response, result.error);
+			return normalizeDomainRecord(result.data.data);
+		},
+		async removeDomain(domainId) {
+			const result = await client.DELETE("/v1/domains/{domainId}", { params: { path: { domainId } } });
+			if (result.error) throw domainApiCallError("Failed to remove custom domain", result.response, result.error);
+		},
+		async retryDomain(domainId) {
+			const result = await client.POST("/v1/domains/{domainId}/retry", { params: { path: { domainId } } });
+			if (result.error || !result.data) throw domainApiCallError("Failed to retry custom domain", result.response, result.error);
+			return normalizeDomainRecord(result.data.data);
+		},
 		async promoteDeployment(options) {
 			const promoteResult = await sdk.promote({
 				serviceId: options.appId,
@@ -263,6 +312,46 @@ async function listComputeServices(client, options) {
 		liveUrl: toAbsoluteUrl(service.serviceEndpointDomain ?? null)
 	}));
 }
+async function listComputeServiceDomains(client, computeServiceId) {
+	const result = await client.GET("/v1/compute-services/{computeServiceId}/domains", { params: { path: { computeServiceId } } });
+	if (result.error || !result.data) throw domainApiCallError("Failed to list custom domains", result.response, result.error);
+	return result.data.data.map((domain) => normalizeDomainRecord(domain));
+}
+function normalizeDomainRecord(domain) {
+	return {
+		id: domain.id,
+		type: domain.type,
+		url: domain.url,
+		hostname: domain.hostname,
+		computeServiceId: domain.computeServiceId,
+		status: domain.status,
+		foundryStatus: domain.foundryStatus,
+		failureReason: domain.failureReason,
+		failureCategory: domain.failureCategory,
+		certExpiresAt: domain.certExpiresAt,
+		createdAt: domain.createdAt,
+		updatedAt: domain.updatedAt,
+		dnsRecords: normalizeDomainDnsRecords(domain.dnsRecords)
+	};
+}
+function normalizeDomainDnsRecords(records) {
+	if (!Array.isArray(records)) return [];
+	return records.map((record) => {
+		if (typeof record.type !== "string" || typeof record.name !== "string" || typeof record.value !== "string") return null;
+		return {
+			type: record.type,
+			name: record.name,
+			value: record.value,
+			ttl: typeof record.ttl === "number" ? record.ttl : null
+		};
+	}).filter((record) => Boolean(record));
+}
+function sameHostname(left, right) {
+	return normalizeHostnameForComparison(left) === normalizeHostnameForComparison(right);
+}
+function normalizeHostnameForComparison(hostname) {
+	return hostname.trim().replace(/\.$/, "").toLowerCase();
+}
 async function createBranchApp(client, options) {
 	const branch = await resolveOrCreateBranch(client, {
 		projectId: options.projectId,
@@ -301,6 +390,15 @@ function apiCallError(summary, response, error) {
 	const hint = error.error?.hint ? ` ${error.error.hint}` : "";
 	return /* @__PURE__ */ new Error(`${summary}: ${message}${hint}`);
 }
+function domainApiCallError(summary, response, error) {
+	return new PreviewDomainApiError({
+		summary,
+		status: response.status,
+		code: error.error?.code ?? null,
+		message: error.error?.message ?? `Management API returned HTTP ${response.status}.`,
+		hint: error.error?.hint ?? null
+	});
+}
 async function findAppForDeployment(sdk, deploymentId) {
 	const projectsResult = await sdk.listProjects();
 	if (projectsResult.isErr()) throw new Error(projectsResult.error.message);
@@ -330,4 +428,4 @@ function toAbsoluteUrl(url) {
 	return url.startsWith("https://") || url.startsWith("http://") ? url : `https://${url}`;
 }
 //#endregion
-export { createPreviewAppProvider };
+export { PreviewDomainApiError, createPreviewAppProvider };

package/dist/presenters/app.js

@@ -1,4 +1,5 @@
 import { renderDeployOutputRows } from "../lib/app/deploy-output.js";
+import { formatDomainFailureFix } from "../lib/app/domain-guidance.js";
 import { renderList, renderShow, serializeList } from "../output/patterns.js";
 //#region src/presenters/app.ts
 function renderAppBuild(context, descriptor, result) {
@@ -253,6 +254,105 @@ function renderAppOpen(context, descriptor, result) {
 function serializeAppOpen(result) {
 	return result;
 }
+function renderAppDomainAdd(context, descriptor, result) {
+	return renderShow({
+		title: result.existing ? "Showing the existing custom domain for the selected app." : "Adding a custom domain to the selected app.",
+		descriptor,
+		fields: [
+			...domainTargetFields(result),
+			{
+				key: "hostname",
+				value: result.domain.hostname
+			},
+			{
+				key: "status",
+				value: result.domain.status,
+				tone: toneForDomainStatus(result.domain.status)
+			},
+			...domainDnsFields(result.domain)
+		]
+	}, context.ui);
+}
+function serializeAppDomainAdd(result) {
+	return result;
+}
+function renderAppDomainShow(context, descriptor, result) {
+	return renderShow({
+		title: "Showing custom domain status.",
+		descriptor,
+		fields: [
+			...domainTargetFields(result),
+			{
+				key: "hostname",
+				value: result.domain.hostname
+			},
+			{
+				key: "status",
+				value: result.domain.status,
+				tone: toneForDomainStatus(result.domain.status)
+			},
+			...domainFailureFields(result.domain),
+			{
+				key: "cert expires",
+				value: formatOptionalUtcDate(result.domain.certExpiresAt),
+				tone: result.domain.certExpiresAt ? "default" : "dim"
+			},
+			{
+				key: "created",
+				value: formatUtcDate(result.domain.createdAt),
+				tone: "dim"
+			},
+			...domainDnsFields(result.domain)
+		]
+	}, context.ui);
+}
+function serializeAppDomainShow(result) {
+	return result;
+}
+function renderAppDomainRemove(context, descriptor, result) {
+	return renderShow({
+		title: "Removing a custom domain from the selected app.",
+		descriptor,
+		fields: [
+			...domainTargetFields(result),
+			{
+				key: "hostname",
+				value: result.hostname
+			},
+			{
+				key: "removed",
+				value: result.removed ? "yes" : "no",
+				tone: result.removed ? "success" : "dim"
+			}
+		]
+	}, context.ui);
+}
+function serializeAppDomainRemove(result) {
+	return result;
+}
+function renderAppDomainRetry(context, descriptor, result) {
+	return renderShow({
+		title: "Retrying custom domain verification.",
+		descriptor,
+		fields: [
+			...domainTargetFields(result),
+			{
+				key: "hostname",
+				value: result.domain.hostname
+			},
+			{
+				key: "status",
+				value: result.domain.status,
+				tone: toneForDomainStatus(result.domain.status)
+			},
+			...domainFailureFields(result.domain),
+			...domainDnsFields(result.domain)
+		]
+	}, context.ui);
+}
+function serializeAppDomainRetry(result) {
+	return result;
+}
 function renderAppPromote(context, descriptor, result) {
 	return renderShow({
 		title: "Switching the live deployment for the selected app.",
@@ -380,6 +480,77 @@ function toneForStatus(status) {
 	if (status === "failed" || status === "error") return "error";
 	return "default";
 }
+function toneForDomainStatus(status) {
+	if (status === "active") return "success";
+	if (status === "failed") return "error";
+	if (status === "pending_dns" || status === "verifying" || status === "provisioning_tls" || status === "verified_routing_blocked") return "warning";
+	return "default";
+}
+function domainTargetFields(result) {
+	return [
+		{
+			key: "workspace",
+			value: result.workspace.name
+		},
+		{
+			key: "project",
+			value: result.project.name
+		},
+		{
+			key: "branch",
+			value: result.branch.name
+		},
+		{
+			key: "app",
+			value: result.app.name
+		}
+	];
+}
+function domainDnsFields(domain) {
+	const records = domain.dnsRecords;
+	if (records.length === 0) return [{
+		key: "dns record",
+		value: "not provided by platform",
+		tone: "dim"
+	}];
+	return [{
+		key: "dns record",
+		value: records.map((record) => {
+			const ttl = record.ttl ? ` ttl ${record.ttl}` : "";
+			return `${record.type} ${record.name} -> ${record.value}${ttl}`;
+		}).join(", ")
+	}];
+}
+function formatDomainFailure(domain) {
+	if (!domain.failureReason) return domain.failureCategory ?? "none";
+	return domain.failureCategory ? `${domain.failureCategory} - ${domain.failureReason}` : domain.failureReason;
+}
+function domainFailureFields(domain) {
+	const tone = hasDomainFailure(domain) ? "error" : "dim";
+	return [{
+		key: "failure",
+		value: formatDomainFailure(domain),
+		tone
+	}, ...domainFixFields(domain)];
+}
+function hasDomainFailure(domain) {
+	return Boolean(domain.failureCategory || domain.failureReason);
+}
+function domainFixFields(domain) {
+	const fix = formatDomainFailureFix(domain);
+	return fix ? [{
+		key: "fix",
+		value: fix
+	}] : [];
+}
+function formatOptionalUtcDate(value) {
+	return value ? formatUtcDate(value) : "-";
+}
+function formatUtcDate(value) {
+	const date = new Date(value);
+	if (Number.isNaN(date.getTime())) return value;
+	return `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, "0")}-${String(date.getUTCDate()).padStart(2, "0")} ${String(date.getUTCHours()).padStart(2, "0")}:${String(date.getUTCMinutes()).padStart(2, "0")} UTC`;
+}
 function formatRecentDeployments(deployments) {
 	if (deployments.length === 0) return "none";
 	return deployments.map((deployment) => `${deployment.id}${deployment.live ? " (live)" : ""}`).join(", ");
@@ -389,4 +560,4 @@ function formatVariableNames(variables) {
 	return variables.join(", ");
 }
 //#endregion
-export { renderAppBuild, renderAppDeploy, renderAppListDeploys, renderAppListEnv, renderAppOpen, renderAppPromote, renderAppRemove, renderAppRollback, renderAppRun, renderAppShow, renderAppShowDeploy, renderAppUpdateEnv, serializeAppBuild, serializeAppDeploy, serializeAppListDeploys, serializeAppListEnv, serializeAppOpen, serializeAppPromote, serializeAppRemove, serializeAppRollback, serializeAppRun, serializeAppShow, serializeAppShowDeploy, serializeAppUpdateEnv };
+export { renderAppBuild, renderAppDeploy, renderAppDomainAdd, renderAppDomainRemove, renderAppDomainRetry, renderAppDomainShow, renderAppListDeploys, renderAppListEnv, renderAppOpen, renderAppPromote, renderAppRemove, renderAppRollback, renderAppRun, renderAppShow, renderAppShowDeploy, renderAppUpdateEnv, serializeAppBuild, serializeAppDeploy, serializeAppDomainAdd, serializeAppDomainRemove, serializeAppDomainRetry, serializeAppDomainShow, serializeAppListDeploys, serializeAppListEnv, serializeAppOpen, serializeAppPromote, serializeAppRemove, serializeAppRollback, serializeAppRun, serializeAppShow, serializeAppShowDeploy, serializeAppUpdateEnv };

package/dist/shell/command-meta.js

@@ -227,6 +227,75 @@ const DESCRIPTORS = [
 		description: "Open the app's live URL",
 		examples: ["prisma-cli app open", "prisma-cli app open --app hello-world"]
 	},
+	{
+		id: "app.domain",
+		path: [
+			"prisma",
+			"app",
+			"domain"
+		],
+		description: "Manage custom domains for an app",
+		examples: [
+			"prisma-cli app domain add shop.acme.com",
+			"prisma-cli app domain wait shop.acme.com --timeout 15m",
+			"prisma-cli app domain retry shop.acme.com"
+		]
+	},
+	{
+		id: "app.domain.add",
+		path: [
+			"prisma",
+			"app",
+			"domain",
+			"add"
+		],
+		description: "Register a custom domain on the app's production branch",
+		examples: ["prisma-cli app domain add shop.acme.com"]
+	},
+	{
+		id: "app.domain.show",
+		path: [
+			"prisma",
+			"app",
+			"domain",
+			"show"
+		],
+		description: "Show custom domain status and certificate details",
+		examples: ["prisma-cli app domain show shop.acme.com"]
+	},
+	{
+		id: "app.domain.remove",
+		path: [
+			"prisma",
+			"app",
+			"domain",
+			"remove"
+		],
+		description: "Detach a custom domain from the app",
+		examples: ["prisma-cli app domain remove shop.acme.com --yes"]
+	},
+	{
+		id: "app.domain.retry",
+		path: [
+			"prisma",
+			"app",
+			"domain",
+			"retry"
+		],
+		description: "Retry custom domain DNS verification and TLS provisioning",
+		examples: ["prisma-cli app domain retry shop.acme.com"]
+	},
+	{
+		id: "app.domain.wait",
+		path: [
+			"prisma",
+			"app",
+			"domain",
+			"wait"
+		],
+		description: "Wait until a custom domain is active or failed",
+		examples: ["prisma-cli app domain wait shop.acme.com", "prisma-cli app domain wait shop.acme.com --timeout 0 --json"]
+	},
 	{
 		id: "app.logs",
 		path: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma/cli",
-  "version": "3.0.0-alpha.13",
+  "version": "3.0.0-alpha.14",
   "description": "Preview of the unified Prisma CLI.",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
     "@prisma/compute-sdk": "^0.19.0",
     "c12": "4.0.0-beta.4",
     "@prisma/credentials-store": "^7.7.0",
-    "@prisma/management-api-sdk": "^1.32.1",
+    "@prisma/management-api-sdk": "^1.33.0",
     "colorette": "^2.0.20",
     "commander": "^12.1.0",
     "magicast": "^0.3.5",