@prisma/cli 3.0.0-alpha.1 → 3.0.0-alpha.10

package/dist/controllers/app.js

@@ -1,19 +1,37 @@
-import { UnsafeConfigWriteError, assertLinkedProjectIdWritable, readLinkedProjectId, writeLinkedProjectId } from "../adapters/config.js";
-import { CliError, authRequiredError, featureUnavailableError, usageError } from "../shell/errors.js";
+import { SERVICE_TOKEN_ENV_VAR, getApiBaseUrl } from "../lib/auth/client.js";
+import { FileTokenStorage } from "../adapters/token-storage.js";
+import { CliError, authRequiredError, featureUnavailableError, usageError, workspaceRequiredError } from "../shell/errors.js";
+import { renderCommandHeader } from "../shell/ui.js";
+import { writeJsonEvent } from "../shell/output.js";
 import { canPrompt } from "../shell/runtime.js";
-import { textPrompt } from "../shell/prompt.js";
+import { confirmPrompt, selectPrompt, textPrompt } from "../shell/prompt.js";
 import { requireComputeAuth } from "../lib/auth/guard.js";
+import { readAuthState } from "../lib/auth/auth-ops.js";
 import { parseEnvAssignments } from "../lib/app/env-vars.js";
+import { renderDeployOutputRows } from "../lib/app/deploy-output.js";
+import { readBunPackageJson } from "../lib/app/bun-project.js";
 import { DEFAULT_LOCAL_DEV_PORT, resolveLocalBuildType, runLocalApp } from "../lib/app/local-dev.js";
-import { projectNotFoundError } from "../use-cases/project.js";
+import { inferTargetName, projectNotFoundError, resolveProjectTarget } from "../lib/project/resolution.js";
+import { LOCAL_RESOLUTION_PIN_RELATIVE_PATH, ensureLocalResolutionPinGitignore, readLocalResolutionPin, writeLocalResolutionPin } from "../lib/project/local-pin.js";
 import { PREVIEW_BUILD_TYPES, RESOLVED_PREVIEW_BUILD_TYPES, executePreviewBuild } from "../lib/app/preview-build.js";
-import { PREVIEW_DEFAULT_REGION, createPreviewDeployInteraction } from "../lib/app/preview-interaction.js";
-import { createPreviewDeployProgress, createPreviewPromoteProgress, createPreviewUpdateEnvProgress } from "../lib/app/preview-progress.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 { createSelectPromptPort } from "./select-prompt-port.js";
+import { requireAuthenticatedAuthState } from "./auth.js";
+import { listRealWorkspaceProjects } from "./project.js";
+import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import open from "open";
 //#region src/controllers/app.ts
+const DEPLOY_FRAMEWORKS = [
+	"nextjs",
+	"hono",
+	"tanstack-start"
+];
+const FRAMEWORK_DEFAULT_HTTP_PORT = 3e3;
+const PRISMA_PROJECT_ID_ENV_VAR = "PRISMA_PROJECT_ID";
+const PRISMA_APP_ID_ENV_VAR = "PRISMA_APP_ID";
 function isRealMode(context) {
 	return !context.runtime.fixturePath && !context.runtime.env.PRISMA_CLI_MOCK_FIXTURE_PATH;
 }
@@ -34,7 +52,7 @@ async function runAppBuild(context, entrypoint, requestedBuildType) {
 				buildType: actualBuildType
 			},
 			warnings: [],
-			nextSteps: ["prisma app deploy"]
+			nextSteps: ["prisma-cli app deploy"]
 		};
 	} catch (error) {
 		if (buildType === "auto" && isAutoBuildDetectionError(error)) throw usageError("App build requires an explicit framework when detection is ambiguous", `This preview auto-detects clear project shapes for ${RESOLVED_PREVIEW_BUILD_TYPES.map(formatBuildTypeName).join(", ")}.`, "Pass a supported --build-type value, or pass --entry <path> for a Bun app.", getBuildTypeExamples("build"), "app");
@@ -42,7 +60,7 @@ async function runAppBuild(context, entrypoint, requestedBuildType) {
 	}
 }
 async function runAppRun(context, entrypoint, requestedBuildType, requestedPort) {
-	if (context.flags.json) throw usageError("App run does not support --json", "This command streams the framework dev server directly and cannot return structured JSON.", "Rerun without --json to pass framework logs through directly.", ["prisma app run"], "app");
+	if (context.flags.json) throw usageError("App run does not support --json", "This command streams the framework dev server directly and cannot return structured JSON.", "Rerun without --json to pass framework logs through directly.", ["prisma-cli app run"], "app");
 	const buildType = normalizeBuildType(requestedBuildType);
 	assertSupportedEntrypoint(buildType, entrypoint, "run");
 	const port = parseLocalPort(requestedPort);
@@ -75,16 +93,75 @@ async function runAppRun(context, entrypoint, requestedBuildType, requestedPort)
 }
 async function runAppDeploy(context, appName, options) {
 	ensurePreviewAppMode(context);
-	const buildType = normalizeBuildType(options?.buildType);
-	assertSupportedEntrypoint(buildType, options?.entrypoint, "deploy");
-	const portMapping = parseDeployPortMapping(options?.httpPort);
+	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 explicitBuildType = Boolean(options?.buildType && options.buildType !== "auto");
+	const branch = await resolveDeployBranch(context, options?.branchName);
+	if (options?.httpPort) parseDeployHttpPort(options.httpPort);
+	let framework = await resolveDeployFramework(context, {
+		requestedFramework: options?.framework,
+		requestedBuildType: options?.buildType,
+		explicitBuildType
+	});
+	let runtime = resolveDeployRuntime(options?.httpPort, framework);
+	assertSupportedEntrypoint(framework.buildType, options?.entrypoint, "deploy");
 	const envVars = toOptionalEnvVars(parseEnvAssignments(options?.envAssignments, { commandName: "deploy" }));
-	const provider = await requirePreviewAppProvider(context);
-	const projectId = await resolveProjectIdForDeploy(context, provider);
-	const selectedApp = await resolveDeploySelection(context, projectId, await listApps(context, provider, projectId), appName);
+	const firstDeploy = !skipLocalPin && localPin.kind === "missing";
+	const { provider, target, projectId } = await requireProviderAndDeployProjectContext(context, options?.projectRef, {
+		allowCreate: true,
+		branch,
+		envProjectId,
+		localPin
+	});
+	const selectedApp = await resolveDeployAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), {
+		explicitAppName: appName,
+		explicitAppId: envAppId,
+		firstDeploy,
+		inferName: () => inferTargetName(context.runtime.cwd)
+	});
+	await maybeRenderDeploySetupBlock(context, {
+		firstDeploy: selectedApp.firstDeploy,
+		workspaceName: target.workspace.name,
+		projectName: target.project.name,
+		projectAnnotation: annotationForProjectResolution(target.resolution),
+		branchName: target.branch.name,
+		branchAnnotation: branch.annotation,
+		appName: selectedApp.displayName,
+		appAnnotation: selectedApp.annotation,
+		framework,
+		runtime
+	});
+	const customized = await maybeCustomizeDeploySettings(context, {
+		framework,
+		runtime,
+		firstDeploy: selectedApp.firstDeploy,
+		explicitFramework: Boolean(options?.framework),
+		explicitBuildType,
+		explicitHttpPort: Boolean(options?.httpPort)
+	});
+	framework = customized.framework;
+	runtime = customized.runtime;
+	const buildType = framework.buildType;
+	assertSupportedEntrypoint(buildType, options?.entrypoint, "deploy");
+	const portMapping = parseDeployPortMapping(String(runtime.port));
+	const shouldWriteLocalPin = firstDeploy && !skipLocalPin;
+	if (shouldWriteLocalPin) {
+		await writeLocalResolutionPin(context.runtime.cwd, {
+			workspaceId: target.workspace.id,
+			projectId: target.project.id
+		});
+		await ensureLocalResolutionPinGitignore(context.runtime.cwd);
+		maybeRenderLocalPinBound(context, target.project.name);
+	}
+	const progressState = createPreviewDeployProgressState();
+	const deployStartedAt = Date.now();
 	const deployResult = await provider.deployApp({
 		cwd: context.runtime.cwd,
 		projectId,
+		branchName: target.branch.name,
 		appId: selectedApp.appId,
 		appName: selectedApp.appName,
 		region: selectedApp.region,
@@ -92,11 +169,12 @@ async function runAppDeploy(context, appName, options) {
 		buildType,
 		portMapping,
 		envVars,
-		interaction: selectedApp.useInteractiveSelection ? createPreviewDeployInteraction(context) : void 0,
-		progress: createPreviewDeployProgress(context.output.stderr, !context.flags.json && !context.flags.quiet)
+		interaction: void 0,
+		progress: createPreviewDeployProgress(context.output.stderr, context.ui, !context.flags.json && !context.flags.quiet, progressState)
 	}).catch((error) => {
-		throw deployFailedError("App deploy failed", error, ["prisma app list-deploys"]);
+		throw appDeployFailedError(error, progressState);
 	});
+	const deployDurationMs = Date.now() - deployStartedAt;
 	await context.stateStore.setSelectedApp(projectId, {
 		id: deployResult.app.id,
 		name: deployResult.app.name
@@ -105,29 +183,37 @@ async function runAppDeploy(context, appName, options) {
 	return {
 		command: "app.deploy",
 		result: {
-			projectId: deployResult.projectId,
+			workspace: target.workspace,
+			project: target.project,
+			branch: target.branch,
+			resolution: target.resolution,
 			app: {
 				id: deployResult.app.id,
 				name: deployResult.app.name
 			},
-			deployment: deployResult.deployment
+			deployment: deployResult.deployment,
+			durationMs: deployDurationMs,
+			localPin: shouldWriteLocalPin ? {
+				path: LOCAL_RESOLUTION_PIN_RELATIVE_PATH,
+				written: true
+			} : void 0
 		},
 		warnings: [],
-		nextSteps: ["prisma app list-deploys", `prisma app show-deploy ${deployResult.deployment.id}`]
+		nextSteps: ["prisma-cli app list-deploys", `prisma-cli app show-deploy ${deployResult.deployment.id}`]
 	};
 }
-async function runAppUpdateEnv(context, appName, envAssignments) {
+async function runAppUpdateEnv(context, appName, envAssignments, projectRef) {
 	ensurePreviewAppMode(context);
+	emitLegacyEnvDeprecationWarning(context, "app update-env", "project env add");
 	const envVars = parseEnvAssignments(envAssignments, {
 		commandName: "update-env",
 		requireAtLeastOne: true
 	});
-	const projectId = await requireLinkedProjectId(context);
-	const provider = await requirePreviewAppProvider(context);
-	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId), appName);
-	if (!selectedApp) throw noDeploymentsError("No deployments available to update environment variables", "The linked project does not have any deployed app yet.");
+	const { provider, target, projectId } = await requireProviderAndProjectContext(context, projectRef);
+	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), appName);
+	if (!selectedApp) throw noDeploymentsError("No deployments available to update environment variables", "The resolved project does not have any deployed app yet.");
 	const deploymentsResult = await provider.listDeployments(selectedApp.id).catch((error) => {
-		throw deployFailedError("Failed to inspect app deployments", error, ["prisma app list-deploys"]);
+		throw deployFailedError("Failed to inspect app deployments", error, ["prisma-cli app list-deploys"]);
 	});
 	if (deploymentsResult.deployments.length === 0) throw noDeploymentsError("No deployments available to update environment variables", `The selected app "${deploymentsResult.app.name}" does not have any deployments yet.`);
 	const updateResult = await provider.updateAppEnv({
@@ -136,7 +222,7 @@ async function runAppUpdateEnv(context, appName, envAssignments) {
 		progress: createPreviewUpdateEnvProgress(context.output.stderr, !context.flags.json && !context.flags.quiet),
 		promoteProgress: createPreviewPromoteProgress(context.output.stderr, !context.flags.json && !context.flags.quiet)
 	}).catch((error) => {
-		throw deployFailedError("Failed to update app environment variables", error, ["prisma app list-env"]);
+		throw deployFailedError("Failed to update app environment variables", error, ["prisma-cli app list-env"]);
 	});
 	await context.stateStore.setSelectedApp(projectId, {
 		id: updateResult.app.id,
@@ -155,14 +241,14 @@ async function runAppUpdateEnv(context, appName, envAssignments) {
 			variables: updateResult.variables
 		},
 		warnings: [],
-		nextSteps: ["prisma app list-env", `prisma app show-deploy ${updateResult.deployment.id}`]
+		nextSteps: ["prisma-cli app list-env", `prisma-cli app show-deploy ${updateResult.deployment.id}`]
 	};
 }
-async function runAppListEnv(context, appName) {
+async function runAppListEnv(context, appName, projectRef) {
 	ensurePreviewAppMode(context);
-	const projectId = await requireLinkedProjectId(context);
-	const provider = await requirePreviewAppProvider(context);
-	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId), appName);
+	emitLegacyEnvDeprecationWarning(context, "app list-env", "project env list");
+	const { provider, target, projectId } = await requireProviderAndProjectContext(context, projectRef);
+	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), appName);
 	if (!selectedApp) return {
 		command: "app.list-env",
 		result: {
@@ -172,10 +258,10 @@ async function runAppListEnv(context, appName) {
 			variables: []
 		},
 		warnings: [],
-		nextSteps: ["prisma app deploy"]
+		nextSteps: ["prisma-cli app deploy"]
 	};
 	const deploymentsResult = await provider.listDeployments(selectedApp.id).catch((error) => {
-		throw deployFailedError("Failed to inspect app deployments", error, ["prisma app list-deploys"]);
+		throw deployFailedError("Failed to inspect app deployments", error, ["prisma-cli app list-deploys"]);
 	});
 	const knownLiveDeploymentId = await context.stateStore.readKnownLiveDeployment(projectId, deploymentsResult.app.id);
 	const missingKnownLiveDeploymentId = knownLiveDeploymentId && !deploymentsResult.deployments.some((candidate) => candidate.id === knownLiveDeploymentId) ? knownLiveDeploymentId : null;
@@ -191,7 +277,7 @@ async function runAppListEnv(context, appName) {
 			appId: deploymentsResult.app.id,
 			deploymentId: missingKnownLiveDeploymentId
 		}).catch((error) => {
-			throw deployFailedError("Failed to inspect app environment variables", error, ["prisma app list-deploys"]);
+			throw deployFailedError("Failed to inspect app environment variables", error, ["prisma-cli app list-deploys"]);
 		});
 		return {
 			command: "app.list-env",
@@ -205,7 +291,7 @@ async function runAppListEnv(context, appName) {
 				variables: envResult.variables
 			},
 			warnings: [],
-			nextSteps: [`prisma app show-deploy ${envResult.deployment.id}`]
+			nextSteps: [`prisma-cli app show-deploy ${envResult.deployment.id}`]
 		};
 	}
 	if (!deployment) return {
@@ -220,13 +306,13 @@ async function runAppListEnv(context, appName) {
 			variables: []
 		},
 		warnings: [],
-		nextSteps: ["prisma app deploy"]
+		nextSteps: ["prisma-cli app deploy"]
 	};
 	const envResult = await provider.listAppEnvNames({
 		appId: deploymentsResult.app.id,
 		deploymentId: deployment.id
 	}).catch((error) => {
-		throw deployFailedError("Failed to inspect app environment variables", error, ["prisma app list-deploys"]);
+		throw deployFailedError("Failed to inspect app environment variables", error, ["prisma-cli app list-deploys"]);
 	});
 	return {
 		command: "app.list-env",
@@ -243,14 +329,13 @@ async function runAppListEnv(context, appName) {
 			variables: envResult.variables
 		},
 		warnings: [],
-		nextSteps: deployment.id ? [`prisma app show-deploy ${deployment.id}`] : ["prisma app deploy"]
+		nextSteps: deployment.id ? [`prisma-cli app show-deploy ${deployment.id}`] : ["prisma-cli app deploy"]
 	};
 }
-async function runAppListDeploys(context, appName) {
+async function runAppListDeploys(context, appName, projectRef) {
 	ensurePreviewAppMode(context);
-	const projectId = await requireLinkedProjectId(context);
-	const provider = await requirePreviewAppProvider(context);
-	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId), appName);
+	const { provider, target, projectId } = await requireProviderAndProjectContext(context, projectRef);
+	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), appName);
 	if (!selectedApp) return {
 		command: "app.list-deploys",
 		result: {
@@ -259,10 +344,10 @@ async function runAppListDeploys(context, appName) {
 			deployments: []
 		},
 		warnings: [],
-		nextSteps: ["prisma app deploy"]
+		nextSteps: ["prisma-cli app deploy"]
 	};
 	const deploymentsResult = await provider.listDeployments(selectedApp.id).catch((error) => {
-		throw deployFailedError("Failed to list app deployments", error, ["prisma app deploy"]);
+		throw deployFailedError("Failed to list app deployments", error, ["prisma-cli app deploy"]);
 	});
 	const currentLiveDeploymentId = await resolveCurrentLiveDeploymentId(context, projectId, deploymentsResult.app, deploymentsResult.deployments);
 	const deployments = applyLiveDeploymentHint(deploymentsResult.deployments, currentLiveDeploymentId).slice().sort((left, right) => right.createdAt.localeCompare(left.createdAt) || right.id.localeCompare(left.id));
@@ -281,14 +366,13 @@ async function runAppListDeploys(context, appName) {
 			deployments
 		},
 		warnings: [],
-		nextSteps: deployments.length > 0 ? [`prisma app show-deploy ${deployments[0]?.id}`] : ["prisma app deploy"]
+		nextSteps: deployments.length > 0 ? [`prisma-cli app show-deploy ${deployments[0]?.id}`] : ["prisma-cli app deploy"]
 	};
 }
-async function runAppShow(context, appName) {
+async function runAppShow(context, appName, projectRef) {
 	ensurePreviewAppMode(context);
-	const projectId = await requireLinkedProjectId(context);
-	const provider = await requirePreviewAppProvider(context);
-	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId), appName);
+	const { provider, target, projectId } = await requireProviderAndProjectContext(context, projectRef);
+	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), appName);
 	if (!selectedApp) return {
 		command: "app.show",
 		result: {
@@ -299,10 +383,10 @@ async function runAppShow(context, appName) {
 			recentDeployments: []
 		},
 		warnings: [],
-		nextSteps: ["prisma app deploy"]
+		nextSteps: ["prisma-cli app deploy"]
 	};
 	const deploymentsResult = await provider.listDeployments(selectedApp.id).catch((error) => {
-		throw deployFailedError("Failed to inspect app", error, ["prisma app list-deploys"]);
+		throw deployFailedError("Failed to inspect app", error, ["prisma-cli app list-deploys"]);
 	});
 	const currentLiveDeploymentId = await resolveCurrentLiveDeploymentId(context, projectId, deploymentsResult.app, deploymentsResult.deployments);
 	const deployments = applyLiveDeploymentHint(deploymentsResult.deployments, currentLiveDeploymentId).slice().sort((left, right) => right.createdAt.localeCompare(left.createdAt) || right.id.localeCompare(left.id));
@@ -330,19 +414,20 @@ async function runAppShow(context, appName) {
 async function runAppShowDeploy(context, deploymentId) {
 	ensurePreviewAppMode(context);
 	const deployment = await (await requirePreviewAppProvider(context)).showDeployment(deploymentId).catch((error) => {
-		throw deployFailedError("Failed to show deployment", error, ["prisma app list-deploys"]);
+		throw deployFailedError("Failed to show deployment", error, ["prisma-cli app list-deploys"]);
 	});
 	if (!deployment) throw new CliError({
 		code: "DEPLOYMENT_NOT_FOUND",
 		domain: "app",
 		summary: `Deployment "${deploymentId}" not found`,
 		why: "The requested deployment does not exist or is no longer available.",
-		fix: "Run prisma app list-deploys to choose an available deployment id.",
+		fix: "Run prisma-cli app list-deploys to choose an available deployment id.",
 		exitCode: 1,
-		nextSteps: ["prisma app list-deploys"]
+		nextSteps: ["prisma-cli app list-deploys"]
 	});
-	const linkedProjectId = deployment?.app ? await readLinkedProjectId(context.runtime.cwd) : null;
-	const knownLiveDeploymentId = deployment?.app && linkedProjectId ? await context.stateStore.readKnownLiveDeployment(linkedProjectId, deployment.app.id) : null;
+	const workspaceId = deployment?.app ? await readCurrentWorkspaceId(context) : null;
+	const rememberedProject = workspaceId ? await context.stateStore.readRememberedProject(workspaceId) : null;
+	const knownLiveDeploymentId = deployment?.app && rememberedProject ? await context.stateStore.readKnownLiveDeployment(rememberedProject.id, deployment.app.id) : null;
 	const providerLiveDeploymentId = deployment.app?.liveDeploymentId ?? null;
 	return {
 		command: "app.show-deploy",
@@ -360,14 +445,13 @@ async function runAppShowDeploy(context, deploymentId) {
 		nextSteps: []
 	};
 }
-async function runAppOpen(context, appName) {
+async function runAppOpen(context, appName, projectRef) {
 	ensurePreviewAppMode(context);
-	const projectId = await requireLinkedProjectId(context);
-	const provider = await requirePreviewAppProvider(context);
-	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId), appName);
-	if (!selectedApp) throw noDeploymentsError("No deployments available to open", "The linked project does not have any deployed app yet.");
+	const { provider, target, projectId } = await requireProviderAndProjectContext(context, projectRef);
+	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), appName);
+	if (!selectedApp) throw noDeploymentsError("No deployments available to open", "The resolved project does not have any deployed app yet.");
 	const deploymentsResult = await provider.listDeployments(selectedApp.id).catch((error) => {
-		throw deployFailedError("Failed to resolve app URL", error, ["prisma app show"]);
+		throw deployFailedError("Failed to resolve app URL", error, ["prisma-cli app show"]);
 	});
 	const currentLiveDeploymentId = await resolveCurrentLiveDeploymentId(context, projectId, deploymentsResult.app, deploymentsResult.deployments);
 	const deployments = applyLiveDeploymentHint(deploymentsResult.deployments, currentLiveDeploymentId).slice().sort((left, right) => right.createdAt.localeCompare(left.createdAt) || right.id.localeCompare(left.id));
@@ -377,7 +461,7 @@ async function runAppOpen(context, appName) {
 		name: deploymentsResult.app.name
 	});
 	if (!liveDeployment) throw noDeploymentsError("No deployments available to open", `The selected app "${deploymentsResult.app.name}" does not have any deployments yet.`);
-	if (!deploymentsResult.app.liveUrl) throw featureUnavailableError("Live URL is not available for the selected app", "Deployments exist, but the provider does not expose a stable live service URL for this app yet.", "Run prisma app show to inspect the current deployment state and try again after the app reports a live URL.", ["prisma app show"], "app");
+	if (!deploymentsResult.app.liveUrl) throw featureUnavailableError("Live URL is not available for the selected app", "Deployments exist, but the provider does not expose a stable live service URL for this app yet.", "Run prisma-cli app show to inspect the current deployment state and try again after the app reports a live URL.", ["prisma-cli app show"], "app");
 	const shouldOpen = canPrompt(context);
 	if (shouldOpen) await open(deploymentsResult.app.liveUrl);
 	return {
@@ -392,20 +476,139 @@ async function runAppOpen(context, appName) {
 			opened: shouldOpen
 		},
 		warnings: [],
-		nextSteps: ["prisma app show", `prisma app show-deploy ${liveDeployment.id}`]
+		nextSteps: ["prisma-cli app show", `prisma-cli app show-deploy ${liveDeployment.id}`]
 	};
 }
-async function runAppLogs(context, _appName, _deploymentId) {
+async function runAppLogs(context, appName, deploymentId, projectRef) {
 	ensurePreviewAppMode(context);
-	throw blockedPreviewAppCommandError("App logs are not available in this preview", "The current preview cannot stream app logs yet.");
+	const { provider, target: resolvedTarget, projectId } = await requireProviderAndProjectContext(context, projectRef);
+	const target = deploymentId ? await resolveExplicitLogDeployment(context, provider, projectId, resolvedTarget.branch.name, appName, deploymentId) : await resolveLiveLogDeployment(context, provider, projectId, resolvedTarget.branch.name, appName);
+	if (!context.flags.json && !context.flags.quiet) {
+		const lines = renderCommandHeader(context.ui, {
+			commandLabel: "app logs",
+			description: "Streaming logs for the selected deployment.",
+			docsPath: "docs/product/command-spec.md#prisma-cli-app-logs---app-name---deployment-id",
+			rows: [
+				{
+					key: "project",
+					value: projectId
+				},
+				{
+					key: "app",
+					value: target.app.name
+				},
+				{
+					key: "deployment",
+					value: target.deployment.id
+				}
+			]
+		});
+		if (lines.length > 0) context.output.stderr.write(`${lines.join("\n")}\n`);
+	}
+	await provider.streamDeploymentLogs({
+		deploymentId: target.deployment.id,
+		onRecord: (record) => writeLogRecord(context, record)
+	}).catch((error) => {
+		throw deployFailedError("Failed to stream app logs", error, [`prisma-cli app show-deploy ${target.deployment.id}`, "prisma-cli app list-deploys"]);
+	});
+}
+async function resolveExplicitLogDeployment(context, provider, projectId, branchName, appName, deploymentId) {
+	if (appName) {
+		const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId, branchName), appName);
+		if (!selectedApp) throw noDeploymentsError("No deployments available to stream logs", "The resolved project does not have any deployed app yet.");
+		const deploymentsResult = await provider.listDeployments(selectedApp.id).catch((error) => {
+			throw deployFailedError("Failed to list app deployments", error, ["prisma-cli app list-deploys"]);
+		});
+		const deployment = requireDeploymentForApp(deploymentsResult.deployments, deploymentId, selectedApp.name);
+		await context.stateStore.setSelectedApp(projectId, {
+			id: deploymentsResult.app.id,
+			name: deploymentsResult.app.name
+		});
+		return {
+			app: deploymentsResult.app,
+			deployment
+		};
+	}
+	const shown = await provider.showDeployment(deploymentId).catch((error) => {
+		throw deployFailedError("Failed to show deployment", error, ["prisma-cli app list-deploys"]);
+	});
+	if (!shown) throw new CliError({
+		code: "DEPLOYMENT_NOT_FOUND",
+		domain: "app",
+		summary: `Deployment "${deploymentId}" not found`,
+		why: "The requested deployment does not exist or is no longer available.",
+		fix: "Run prisma-cli app list-deploys to choose an available deployment id.",
+		exitCode: 1,
+		nextSteps: ["prisma-cli app list-deploys"]
+	});
+	if (!shown.app) throw new CliError({
+		code: "DEPLOYMENT_NOT_FOUND",
+		domain: "app",
+		summary: `Deployment "${deploymentId}" is not attached to an app`,
+		why: "The requested deployment could be found, but its app could not be resolved.",
+		fix: "Run prisma-cli app list-deploys to choose an available deployment id for the selected app.",
+		exitCode: 1,
+		nextSteps: ["prisma-cli app list-deploys"]
+	});
+	const resolvedProjectApp = (await listApps(context, provider, projectId, branchName)).find((app) => app.id === shown.app?.id);
+	if (!resolvedProjectApp) throw new CliError({
+		code: "DEPLOYMENT_NOT_FOUND",
+		domain: "app",
+		summary: `Deployment "${deploymentId}" not found in the resolved project`,
+		why: "The requested deployment does not belong to an app in the resolved project.",
+		fix: "Run prisma-cli app list-deploys to choose an available deployment id for this project.",
+		exitCode: 1,
+		nextSteps: ["prisma-cli app list-deploys"]
+	});
+	await context.stateStore.setSelectedApp(projectId, {
+		id: resolvedProjectApp.id,
+		name: resolvedProjectApp.name
+	});
+	return {
+		app: resolvedProjectApp,
+		deployment: shown.deployment
+	};
+}
+async function resolveLiveLogDeployment(context, provider, projectId, branchName, appName) {
+	const selectedApp = await resolveExistingAppSelection(context, projectId, await listApps(context, provider, projectId, branchName), appName);
+	if (!selectedApp) throw noDeploymentsError("No deployments available to stream logs", "The resolved project does not have any deployed app yet.");
+	const deploymentsResult = await provider.listDeployments(selectedApp.id).catch((error) => {
+		throw deployFailedError("Failed to list app deployments", error, ["prisma-cli app list-deploys"]);
+	});
+	const currentLiveDeploymentId = await resolveCurrentLiveDeploymentId(context, projectId, deploymentsResult.app, deploymentsResult.deployments);
+	const deployments = applyLiveDeploymentHint(deploymentsResult.deployments, currentLiveDeploymentId);
+	const deployment = currentLiveDeploymentId ? deployments.find((candidate) => candidate.id === currentLiveDeploymentId) ?? null : null;
+	await context.stateStore.setSelectedApp(projectId, {
+		id: deploymentsResult.app.id,
+		name: deploymentsResult.app.name
+	});
+	if (!deployment) throw noDeploymentsError("No deployments available to stream logs", `The selected app "${deploymentsResult.app.name}" does not have any deployments yet.`);
+	return {
+		app: deploymentsResult.app,
+		deployment
+	};
+}
+function writeLogRecord(context, record) {
+	if (context.flags.json) {
+		writeJsonEvent(context.output, {
+			type: record.type,
+			command: "app.logs",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			data: record
+		});
+		return;
+	}
+	if (record.type === "log") {
+		context.output.stdout.write(record.text);
+		if (!record.text.endsWith("\n")) context.output.stdout.write("\n");
+	}
 }
-async function runAppPromote(context, deploymentId, appName) {
+async function runAppPromote(context, deploymentId, appName, projectRef) {
 	ensurePreviewAppMode(context);
-	const projectId = await requireLinkedProjectId(context);
-	const provider = await requirePreviewAppProvider(context);
-	const selectedApp = await requireReleaseAppSelection(context, projectId, await listApps(context, provider, projectId), appName, "promote");
+	const { provider, target, projectId } = await requireProviderAndProjectContext(context, projectRef);
+	const selectedApp = await requireReleaseAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), appName, "promote");
 	const deploymentsResult = await provider.listDeployments(selectedApp.id).catch((error) => {
-		throw deployFailedError("Failed to list app deployments", error, ["prisma app list-deploys"]);
+		throw deployFailedError("Failed to list app deployments", error, ["prisma-cli app list-deploys"]);
 	});
 	const currentLiveDeploymentId = await resolveCurrentLiveDeploymentId(context, projectId, deploymentsResult.app, deploymentsResult.deployments);
 	const targetDeployment = requireDeploymentForApp(deploymentsResult.deployments, deploymentId, selectedApp.name);
@@ -419,7 +622,7 @@ async function runAppPromote(context, deploymentId, appName) {
 		deploymentId: targetDeployment.id,
 		progress: createPreviewPromoteProgress(context.output.stderr, !context.flags.json && !context.flags.quiet)
 	}).catch((error) => {
-		throw deployFailedError("Failed to promote deployment", error, ["prisma app list-deploys"]);
+		throw deployFailedError("Failed to promote deployment", error, ["prisma-cli app list-deploys"]);
 	});
 	await context.stateStore.setKnownLiveDeployment(projectId, deploymentsResult.app.id, targetDeployment.id);
 	return {
@@ -437,16 +640,15 @@ async function runAppPromote(context, deploymentId, appName) {
 			}
 		},
 		warnings: targetAlreadyLive ? ["The selected deployment is already live for this app."] : [],
-		nextSteps: ["prisma app list-deploys", `prisma app show-deploy ${targetDeployment.id}`]
+		nextSteps: ["prisma-cli app list-deploys", `prisma-cli app show-deploy ${targetDeployment.id}`]
 	};
 }
-async function runAppRollback(context, appName, deploymentId) {
+async function runAppRollback(context, appName, deploymentId, projectRef) {
 	ensurePreviewAppMode(context);
-	const projectId = await requireLinkedProjectId(context);
-	const provider = await requirePreviewAppProvider(context);
-	const selectedApp = await requireReleaseAppSelection(context, projectId, await listApps(context, provider, projectId), appName, "rollback");
+	const { provider, target, projectId } = await requireProviderAndProjectContext(context, projectRef);
+	const selectedApp = await requireReleaseAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), appName, "rollback");
 	const deploymentsResult = await provider.listDeployments(selectedApp.id).catch((error) => {
-		throw deployFailedError("Failed to list app deployments", error, ["prisma app list-deploys"]);
+		throw deployFailedError("Failed to list app deployments", error, ["prisma-cli app list-deploys"]);
 	});
 	const currentLiveDeploymentId = await resolveCurrentLiveDeploymentId(context, projectId, deploymentsResult.app, deploymentsResult.deployments);
 	const currentLiveDeployment = currentLiveDeploymentId ? deploymentsResult.deployments.find((deployment) => deployment.id === currentLiveDeploymentId) ?? null : null;
@@ -461,7 +663,7 @@ async function runAppRollback(context, appName, deploymentId) {
 		deploymentId: targetDeployment.id,
 		progress: createPreviewPromoteProgress(context.output.stderr, !context.flags.json && !context.flags.quiet)
 	}).catch((error) => {
-		throw deployFailedError("Failed to roll back deployment", error, ["prisma app list-deploys"]);
+		throw deployFailedError("Failed to roll back deployment", error, ["prisma-cli app list-deploys"]);
 	});
 	await context.stateStore.setKnownLiveDeployment(projectId, deploymentsResult.app.id, targetDeployment.id);
 	return {
@@ -480,17 +682,16 @@ async function runAppRollback(context, appName, deploymentId) {
 			previousLiveDeploymentId: currentLiveDeployment?.id ?? null
 		},
 		warnings: targetAlreadyLive ? ["The selected deployment is already live for this app."] : [],
-		nextSteps: ["prisma app list-deploys", `prisma app show-deploy ${targetDeployment.id}`]
+		nextSteps: ["prisma-cli app list-deploys", `prisma-cli app show-deploy ${targetDeployment.id}`]
 	};
 }
-async function runAppRemove(context, appName) {
+async function runAppRemove(context, appName, projectRef) {
 	ensurePreviewAppMode(context);
-	const projectId = await requireLinkedProjectId(context);
-	const provider = await requirePreviewAppProvider(context);
-	const selectedApp = await requireReleaseAppSelection(context, projectId, await listApps(context, provider, projectId), appName, "remove");
+	const { provider, target, projectId } = await requireProviderAndProjectContext(context, projectRef);
+	const selectedApp = await requireReleaseAppSelection(context, projectId, await listApps(context, provider, projectId, target.branch.name), appName, "remove");
 	await confirmAppRemoval(context, selectedApp);
 	const removedApp = await provider.removeApp(selectedApp.id).catch((error) => {
-		throw removeFailedError("Failed to remove app", error, ["prisma app show", "prisma app list-deploys"]);
+		throw removeFailedError("Failed to remove app", error, ["prisma-cli app show", "prisma-cli app list-deploys"]);
 	});
 	const warnings = await cleanupRemovedAppState(context, projectId, removedApp.id);
 	return {
@@ -504,48 +705,122 @@ async function runAppRemove(context, appName) {
 			removed: true
 		},
 		warnings,
-		nextSteps: ["prisma app deploy", "prisma app list-deploys"]
+		nextSteps: ["prisma-cli app deploy", "prisma-cli app list-deploys"]
 	};
 }
-async function resolveDeploySelection(context, projectId, apps, explicitAppName) {
-	if (explicitAppName) {
-		const matched = findAppByName(apps, explicitAppName);
+async function resolveDeployAppSelection(context, projectId, apps, options) {
+	if (options.explicitAppName) {
+		const matches = findAppsByName(apps, options.explicitAppName);
+		if (matches.length > 1) return resolveAmbiguousDeployApp(context, matches, options.explicitAppName, options.firstDeploy);
+		const matched = matches[0];
 		if (matched) return {
 			appId: matched.id,
-			useInteractiveSelection: false
+			displayName: matched.name,
+			annotation: "set by --app",
+			firstDeploy: options.firstDeploy
 		};
 		return {
-			appName: explicitAppName,
+			appName: options.explicitAppName,
 			region: PREVIEW_DEFAULT_REGION,
-			useInteractiveSelection: false
+			displayName: options.explicitAppName,
+			annotation: "set by --app",
+			firstDeploy: options.firstDeploy
 		};
 	}
-	const savedSelection = await context.stateStore.readSelectedApp(projectId);
-	if (savedSelection) {
-		const matched = apps.find((app) => app.id === savedSelection.id) ?? findAppByName(apps, savedSelection.name);
-		if (matched) return {
+	if (options.explicitAppId) {
+		const matched = apps.find((app) => app.id === options.explicitAppId);
+		if (!matched) throw usageError("Selected app does not exist in the resolved project", `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 choose an app from prisma-cli app list-deploys.`, ["prisma-cli app list-deploys"], "app");
+		return {
 			appId: matched.id,
-			useInteractiveSelection: false
+			displayName: matched.name,
+			annotation: `from ${PRISMA_APP_ID_ENV_VAR}`,
+			firstDeploy: options.firstDeploy
 		};
-		if (!canPrompt(context)) throw usageError("Saved app selection is no longer available", "The locally selected app could not be found in the linked project.", "Pass --app <name>, or rerun prisma app deploy in a TTY to choose or create an app again.", ["prisma app deploy"], "app");
 	}
-	if (!canPrompt(context)) throw usageError("App deploy requires an app selection in non-interactive mode", "This command cannot choose or create an app in the current mode.", "Pass --app <name>, or rerun prisma app deploy in a TTY to choose or create an app.", ["prisma app deploy --app hello-world"], "app");
-	return { useInteractiveSelection: true };
+	const inferredName = await options.inferName();
+	const matches = findAppsByName(apps, inferredName.name);
+	if (matches.length > 1) return resolveAmbiguousDeployApp(context, matches, inferredName.name, options.firstDeploy);
+	const matched = matches[0];
+	if (matched) return {
+		appId: matched.id,
+		displayName: matched.name,
+		annotation: "existing app on this branch",
+		firstDeploy: options.firstDeploy
+	};
+	return {
+		appName: inferredName.name,
+		region: PREVIEW_DEFAULT_REGION,
+		displayName: inferredName.name,
+		annotation: inferredName.source === "package-name" ? "created from package.json" : "created from directory name",
+		firstDeploy: options.firstDeploy
+	};
+}
+async function resolveAmbiguousDeployApp(context, matches, targetName, firstDeploy) {
+	if (canPrompt(context)) {
+		const createNew = "__create_new_app__";
+		const cancel = "__cancel__";
+		const selected = await selectPrompt({
+			input: context.runtime.stdin,
+			output: context.runtime.stderr,
+			message: `Multiple apps are named "${targetName}"`,
+			choices: [
+				...sortApps(matches).map((app) => ({
+					label: `${app.name} (${app.id})`,
+					value: app
+				})),
+				{
+					label: `Create a new app named "${targetName}"`,
+					value: createNew
+				},
+				{
+					label: "Cancel",
+					value: cancel
+				}
+			]
+		});
+		if (selected === cancel) throw usageError("App selection canceled", "The command was canceled before an app was selected.", "Re-run the command and choose an app, or pass --app <name>.", ["prisma-cli app deploy --app <name>"], "app");
+		if (selected === createNew) return {
+			appName: targetName,
+			region: PREVIEW_DEFAULT_REGION,
+			displayName: targetName,
+			annotation: "created from package.json",
+			firstDeploy
+		};
+		return {
+			appId: selected.id,
+			displayName: selected.name,
+			annotation: "selected by you",
+			firstDeploy
+		};
+	}
+	throw new CliError({
+		code: "APP_AMBIGUOUS",
+		domain: "app",
+		summary: "App resolution is ambiguous",
+		why: `Multiple apps matched "${targetName}".`,
+		fix: "Pass --app <name> to choose the app explicitly.",
+		meta: { candidates: matches.map((app) => ({
+			id: app.id,
+			name: app.name
+		})) },
+		exitCode: 2,
+		nextSteps: ["prisma-cli app deploy --app <name>"]
+	});
 }
 async function resolveExistingAppSelection(context, projectId, apps, explicitAppName) {
 	if (explicitAppName) {
 		const matched = findAppByName(apps, explicitAppName);
-		if (!matched) throw usageError("Selected app does not exist in the linked project", `The app "${explicitAppName}" could not be found in linked project "${projectId}".`, "Pass the name of an existing app, or rerun prisma app list-deploys in a TTY to choose one.", ["prisma app list-deploys"], "app");
+		if (!matched) throw usageError("Selected app does not exist in the resolved project", `The app "${explicitAppName}" could not be found in resolved project "${projectId}".`, "Pass the name of an existing app, or rerun prisma-cli app list-deploys in a TTY to choose one.", ["prisma-cli app list-deploys"], "app");
 		return matched;
 	}
 	const savedSelection = await context.stateStore.readSelectedApp(projectId);
 	if (savedSelection) {
 		const matched = apps.find((app) => app.id === savedSelection.id) ?? findAppByName(apps, savedSelection.name);
 		if (matched) return matched;
-		if (!canPrompt(context)) throw usageError("Saved app selection is no longer available", "The locally selected app could not be found in the linked project.", "Pass --app <name>, or rerun prisma app list-deploys in a TTY to choose an available app.", ["prisma app list-deploys"], "app");
+		if (!canPrompt(context)) throw usageError("Saved app selection is no longer available", "The locally selected app could not be found in the resolved project.", "Pass --app <name>, or rerun prisma-cli app list-deploys in a TTY to choose an available app.", ["prisma-cli app list-deploys"], "app");
 	}
 	if (apps.length === 0) return null;
-	if (!canPrompt(context)) throw usageError("App selection required in non-interactive mode", "This command cannot choose an app in the current mode.", "Pass --app <name>, or rerun prisma app list-deploys in a TTY to choose an app.", ["prisma app list-deploys"], "app");
+	if (!canPrompt(context)) throw usageError("App selection required in non-interactive mode", "This command cannot choose an app in the current mode.", "Pass --app <name>, or rerun prisma-cli app list-deploys in a TTY to choose an app.", ["prisma-cli app list-deploys"], "app");
 	const selectedId = await createSelectPromptPort(context).select({
 		message: "Select an app",
 		choices: sortApps(apps).map((app) => ({
@@ -558,7 +833,7 @@ async function resolveExistingAppSelection(context, projectId, apps, explicitApp
 async function requireReleaseAppSelection(context, projectId, apps, explicitAppName, commandName) {
 	const selectedApp = await resolveExistingAppSelection(context, projectId, apps, explicitAppName);
 	if (selectedApp) return selectedApp;
-	throw usageError(`App ${commandName} requires an existing app`, "The linked project does not have an app that can be selected for this command.", `Deploy an app first, or rerun prisma app ${commandName} with --app <name> after an app exists.`, ["prisma app deploy", "prisma app list-deploys"], "app");
+	throw usageError(`App ${commandName} requires an existing app`, "The resolved project does not have an app that can be selected for this command.", `Deploy an app first, or rerun prisma-cli app ${commandName} with --app <name> after an app exists.`, ["prisma-cli app deploy", "prisma-cli app list-deploys"], "app");
 }
 async function confirmAppRemoval(context, app) {
 	if (context.flags.yes) return;
@@ -567,9 +842,9 @@ async function confirmAppRemoval(context, app) {
 		domain: "app",
 		summary: "App remove requires confirmation in the current mode",
 		why: "This command is destructive and cannot prompt for confirmation in the current mode.",
-		fix: `Pass --yes to confirm removal of "${app.name}", or rerun prisma app remove in an interactive TTY.`,
+		fix: `Pass --yes to confirm removal of "${app.name}", or rerun prisma-cli app remove in an interactive TTY.`,
 		exitCode: 1,
-		nextSteps: [`prisma app remove --app ${app.name} --yes`]
+		nextSteps: [`prisma-cli app remove --app ${app.name} --yes`]
 	});
 	await textPrompt({
 		input: context.runtime.stdin,
@@ -601,9 +876,9 @@ function requireDeploymentForApp(deployments, deploymentId, appName) {
 		domain: "app",
 		summary: `Deployment "${deploymentId}" not found for app "${appName}"`,
 		why: "The requested deployment does not belong to the resolved app or is no longer available.",
-		fix: "Run prisma app list-deploys to choose an available deployment id for this app.",
+		fix: "Run prisma-cli app list-deploys to choose an available deployment id for this app.",
 		exitCode: 1,
-		nextSteps: ["prisma app list-deploys"]
+		nextSteps: ["prisma-cli app list-deploys"]
 	});
 }
 async function resolveCurrentLiveDeploymentId(context, projectId, app, deployments) {
@@ -616,10 +891,10 @@ async function resolveCurrentLiveDeploymentId(context, projectId, app, deploymen
 }
 function buildAppShowNextSteps(liveUrl, liveDeployment, deployments) {
 	const nextSteps = [];
-	if (liveUrl) nextSteps.push("prisma app open");
-	if (liveDeployment) nextSteps.push(`prisma app show-deploy ${liveDeployment.id}`);
-	else if (deployments[0]) nextSteps.push(`prisma app show-deploy ${deployments[0].id}`);
-	else nextSteps.push("prisma app deploy");
+	if (liveUrl) nextSteps.push("prisma-cli app open");
+	if (liveDeployment) nextSteps.push(`prisma-cli app show-deploy ${liveDeployment.id}`);
+	else if (deployments[0]) nextSteps.push(`prisma-cli app show-deploy ${deployments[0].id}`);
+	else nextSteps.push("prisma-cli app deploy");
 	return nextSteps;
 }
 function applyLiveDeploymentHint(deployments, currentLiveDeploymentId) {
@@ -640,63 +915,503 @@ function resolveRollbackTarget(deployments, currentLiveDeploymentId) {
 		domain: "app",
 		summary: "No previous deployment available for rollback",
 		why: "The selected app does not have an earlier deployment to switch back to.",
-		fix: "Deploy a second version first, or rerun prisma app rollback --to <deployment-id> for a specific earlier deployment.",
+		fix: "Deploy a second version first, or rerun prisma-cli app rollback --to <deployment-id> for a specific earlier deployment.",
 		exitCode: 1,
-		nextSteps: ["prisma app deploy", "prisma app list-deploys"]
+		nextSteps: ["prisma-cli app deploy", "prisma-cli app list-deploys"]
 	});
 }
-async function listApps(context, provider, projectId) {
-	return provider.listApps(projectId).then(sortApps).catch((error) => {
-		if (isMissingProjectError(error)) throw projectNotFoundError(`The linked project "${projectId}" does not exist in the authenticated workspace or is no longer accessible.`, "Run prisma project show to inspect the current link, then relink the repo or rerun prisma app deploy to bootstrap a new project.", [
-			"prisma project show",
-			"prisma project link",
-			"prisma app deploy"
-		]);
-		throw deployFailedError("Failed to list apps", error, ["prisma project show"]);
+async function listApps(context, provider, projectId, branchName) {
+	return provider.listApps(projectId, { branchName }).then(sortApps).catch((error) => {
+		if (isMissingProjectError(error)) throw new CliError({
+			code: "PROJECT_NOT_FOUND",
+			domain: "project",
+			summary: "Project not found",
+			why: `The resolved project "${projectId}" does not exist in the authenticated workspace or is no longer accessible.`,
+			fix: "Pass --project <id-or-name>, or run prisma-cli project show to inspect resolution for this directory.",
+			exitCode: 1,
+			nextSteps: ["prisma-cli project show", "prisma-cli app deploy --project <id-or-name>"]
+		});
+		throw deployFailedError("Failed to list apps", error, ["prisma-cli project show"]);
 	});
 }
 async function requirePreviewAppProvider(context) {
+	const { provider } = await requirePreviewAppProviderWithClient(context);
+	return provider;
+}
+async function requirePreviewAppProviderWithClient(context) {
 	const client = await requireComputeAuth(context.runtime.env);
-	if (!client) throw authRequiredError(["prisma auth login"]);
-	return createPreviewAppProvider(client);
+	if (!client) throw authRequiredError(["prisma-cli auth login"]);
+	return {
+		client,
+		provider: createPreviewAppProvider(client, createPreviewLogAuthOptions(context.runtime.env))
+	};
 }
-async function requireLinkedProjectId(context) {
-	const projectId = await readLinkedProjectId(context.runtime.cwd);
-	if (!projectId) throw new CliError({
-		code: "PROJECT_NOT_LINKED",
-		domain: "project",
-		summary: "Project link required",
-		why: "This command needs a linked project for the current repo.",
-		fix: "Run prisma project link before deploying or inspecting app deployments.",
-		exitCode: 1,
-		nextSteps: ["prisma project link"]
-	});
-	return projectId;
+function createPreviewLogAuthOptions(env) {
+	const rawToken = env[SERVICE_TOKEN_ENV_VAR]?.trim();
+	if (rawToken) return {
+		baseUrl: getApiBaseUrl(env),
+		getToken: async () => rawToken
+	};
+	const tokenStorage = new FileTokenStorage(env);
+	return {
+		baseUrl: getApiBaseUrl(env),
+		getToken: async () => {
+			const tokens = await tokenStorage.getTokens();
+			if (!tokens) throw new Error("Authentication token is no longer available. Run prisma-cli auth login and try again.");
+			return tokens.accessToken;
+		}
+	};
+}
+async function requireProviderAndProjectContext(context, explicitProject, options) {
+	const { client, provider } = await requirePreviewAppProviderWithClient(context);
+	const target = await resolveProjectContext(context, client, provider, explicitProject, options);
+	return {
+		client,
+		provider,
+		target,
+		projectId: target.project.id
+	};
+}
+async function requireProviderAndDeployProjectContext(context, explicitProject, options) {
+	const { client, provider } = await requirePreviewAppProviderWithClient(context);
+	const target = await resolveDeployProjectContext(context, client, provider, explicitProject, options);
+	return {
+		client,
+		provider,
+		target,
+		projectId: target.project.id
+	};
 }
-async function resolveProjectIdForDeploy(context, provider) {
-	const linkedProjectId = await readLinkedProjectId(context.runtime.cwd);
-	if (linkedProjectId) return linkedProjectId;
-	await assertProjectLinkWritableForDeploy(context);
-	const projectName = path.basename(context.runtime.cwd);
-	const project = await provider.createProject({ name: projectName }).catch((error) => {
-		throw deployFailedError("Failed to create project for first deploy", error, ["prisma app deploy"]);
+async function resolveProjectContext(context, client, provider, explicitProject, options) {
+	const authState = await requireAuthenticatedAuthState(context);
+	if (!authState.workspace) throw workspaceRequiredError();
+	const resolved = await resolveProjectTarget({
+		context,
+		workspace: authState.workspace,
+		explicitProject,
+		listProjects: () => listRealWorkspaceProjects(client, authState.workspace),
+		createProject: options?.allowCreate ? async (name) => {
+			const project = await provider.createProject({ name }).catch((error) => {
+				throw createProjectOnFirstDeployError({
+					error,
+					inferredName: name,
+					workspaceName: authState.workspace.name
+				});
+			});
+			return {
+				id: project.id,
+				name: project.name,
+				workspace: authState.workspace
+			};
+		} : void 0,
+		allowCreate: options?.allowCreate,
+		prompt: createSelectPromptPort(context),
+		remember: true
 	});
+	const branch = options?.branch ?? await resolveDeployBranch(context, void 0);
+	return {
+		...resolved,
+		branch: {
+			name: branch.name,
+			kind: toBranchKind(branch.name)
+		}
+	};
+}
+async function resolveDeployProjectContext(context, client, provider, explicitProject, options) {
+	const workspace = (await requireAuthenticatedAuthState(context)).workspace;
+	if (!workspace) throw workspaceRequiredError();
+	const branch = options.branch ?? await resolveDeployBranch(context, void 0);
+	const projects = await listRealWorkspaceProjects(client, workspace);
+	const createProject = options.allowCreate ? async (name) => {
+		const project = await provider.createProject({ name }).catch((error) => {
+			throw createProjectOnFirstDeployError({
+				error,
+				inferredName: name,
+				workspaceName: workspace.name
+			});
+		});
+		return {
+			id: project.id,
+			name: project.name,
+			workspace
+		};
+	} : void 0;
+	if (explicitProject) return withDeployBranch(await resolveProjectTarget({
+		context,
+		workspace,
+		explicitProject,
+		listProjects: async () => projects,
+		createProject,
+		allowCreate: options.allowCreate,
+		prompt: createSelectPromptPort(context),
+		remember: true
+	}), branch);
+	if (options.envProjectId) {
+		const project = projects.find((candidate) => candidate.id === options.envProjectId);
+		if (!project) throw projectNotFoundError(options.envProjectId, workspace);
+		return withDeployBranch({
+			workspace,
+			project: toProjectSummary(project),
+			resolution: {
+				projectSource: "env",
+				targetName: options.envProjectId,
+				targetNameSource: "env"
+			}
+		}, branch);
+	}
+	const localPin = options.localPin;
+	if (localPin.kind === "present") {
+		if (localPin.pin.workspaceId !== workspace.id) throw localResolutionPinStaleError();
+		const project = projects.find((candidate) => candidate.id === localPin.pin.projectId);
+		if (!project) throw localResolutionPinStaleError();
+		return withDeployBranch({
+			workspace,
+			project: toProjectSummary(project),
+			resolution: {
+				projectSource: "local-pin",
+				targetName: project.name,
+				targetNameSource: "local-pin"
+			}
+		}, branch);
+	}
+	return withDeployBranch(await resolveProjectTarget({
+		context,
+		workspace,
+		listProjects: async () => projects,
+		createProject,
+		allowCreate: options.allowCreate,
+		prompt: createSelectPromptPort(context),
+		remember: true
+	}), branch);
+}
+function withDeployBranch(target, branch) {
+	return {
+		...target,
+		branch: {
+			name: branch.name,
+			kind: toBranchKind(branch.name)
+		}
+	};
+}
+function toProjectSummary(project) {
+	return {
+		id: project.id,
+		name: project.name
+	};
+}
+function toBranchKind(name) {
+	return name === "production" || name === "main" ? "production" : "preview";
+}
+async function resolveDeployBranch(context, explicitBranchName) {
+	if (explicitBranchName) return {
+		name: explicitBranchName,
+		annotation: "set by --branch"
+	};
+	const gitBranch = await readLocalGitBranch(context.runtime.cwd);
+	if (gitBranch) return {
+		name: gitBranch,
+		annotation: "from local Git branch"
+	};
+	return {
+		name: "main",
+		annotation: "default"
+	};
+}
+async function readLocalGitBranch(cwd) {
+	const headPath = await resolveGitHeadPath(path.join(cwd, ".git"));
+	if (!headPath) return null;
 	try {
-		await writeLinkedProjectId(context.runtime.cwd, project.id);
-	} catch (error) {
-		const cause = error instanceof Error ? error.message : String(error);
-		throw deployFailedError("Failed to link created project", `Project "${project.name}" (${project.id}) was created remotely but could not be linked locally: ${cause}`, ["prisma project show", "prisma app deploy"]);
+		const head = (await readFile(headPath, "utf8")).trim();
+		if (head.startsWith("ref: refs/heads/")) return head.slice(16);
+	} catch {
+		return null;
 	}
-	return project.id;
+	return null;
 }
-async function assertProjectLinkWritableForDeploy(context) {
+async function resolveGitHeadPath(gitPath) {
+	try {
+		const raw = await readFile(gitPath, "utf8");
+		if (raw.startsWith("gitdir:")) return path.join(path.resolve(path.dirname(gitPath), raw.slice(7).trim()), "HEAD");
+	} catch {}
 	try {
-		await assertLinkedProjectIdWritable(context.runtime.cwd);
+		await access(path.join(gitPath, "HEAD"));
+		return path.join(gitPath, "HEAD");
+	} catch {
+		return null;
+	}
+}
+async function resolveDeployFramework(context, options) {
+	if (options.requestedFramework) return frameworkFromUserFacingValue(options.requestedFramework, "set by --framework");
+	if (options.explicitBuildType) {
+		const buildType = normalizeBuildType(options.requestedBuildType);
+		if (buildType !== "auto") return {
+			key: buildType,
+			buildType,
+			displayName: formatBuildTypeName(buildType),
+			annotation: "set by --build-type"
+		};
+	}
+	const detected = await detectDeployFramework(context.runtime.cwd);
+	if (detected) return detected;
+	throw frameworkNotDetectedError(context.runtime.cwd);
+}
+function resolveDeployRuntime(requestedHttpPort, framework) {
+	if (requestedHttpPort) return {
+		port: parseDeployHttpPort(requestedHttpPort),
+		annotation: "set by --http-port"
+	};
+	return {
+		port: FRAMEWORK_DEFAULT_HTTP_PORT,
+		annotation: `${framework.displayName} default`
+	};
+}
+async function detectDeployFramework(cwd) {
+	const packageJson = await readBunPackageJson(cwd);
+	const nextConfig = await detectNextConfig(cwd);
+	if (nextConfig.exists || hasPackageDependency(packageJson, "next")) return {
+		key: "nextjs",
+		buildType: "nextjs",
+		displayName: "Next.js",
+		annotation: nextConfig.standalone ? "standalone output detected" : nextConfig.exists ? "detected from next.config" : "detected from package.json"
+	};
+	if (hasPackageDependency(packageJson, "hono")) return {
+		key: "hono",
+		buildType: "bun",
+		displayName: "Hono",
+		annotation: "detected from package.json"
+	};
+	if (hasPackageDependency(packageJson, "@tanstack/start")) return {
+		key: "tanstack-start",
+		buildType: "tanstack-start",
+		displayName: "TanStack Start",
+		annotation: "detected from package.json"
+	};
+	return null;
+}
+async function detectNextConfig(cwd) {
+	for (const candidate of [
+		"next.config.js",
+		"next.config.mjs",
+		"next.config.cjs",
+		"next.config.ts"
+	]) {
+		const filePath = path.join(cwd, candidate);
+		try {
+			const content = await readFile(filePath, "utf8");
+			return {
+				exists: true,
+				standalone: /\boutput\s*:\s*["'`]standalone["'`]/.test(content)
+			};
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+	}
+	return {
+		exists: false,
+		standalone: false
+	};
+}
+function hasPackageDependency(packageJson, dependencyName) {
+	return hasDependency(packageJson?.dependencies, dependencyName) || hasDependency(packageJson?.devDependencies, dependencyName);
+}
+function hasDependency(dependencies, dependencyName) {
+	return Boolean(dependencies && typeof dependencies === "object" && dependencyName in dependencies);
+}
+function frameworkFromUserFacingValue(value, annotation) {
+	switch (value.trim().toLowerCase()) {
+		case "next":
+		case "next.js":
+		case "nextjs": return {
+			key: "nextjs",
+			buildType: "nextjs",
+			displayName: "Next.js",
+			annotation
+		};
+		case "hono": return {
+			key: "hono",
+			buildType: "bun",
+			displayName: "Hono",
+			annotation
+		};
+		case "tanstack":
+		case "tanstack-start":
+		case "@tanstack/start": return {
+			key: "tanstack-start",
+			buildType: "tanstack-start",
+			displayName: "TanStack Start",
+			annotation
+		};
+		default: throw frameworkNotDetectedError(void 0, value);
+	}
+}
+function frameworkNotDetectedError(cwd, requestedFramework) {
+	const supported = "Next.js, Hono, TanStack Start";
+	const directory = cwd ? ` in ${formatDeployDirectory(cwd)}` : "";
+	return new CliError({
+		code: "FRAMEWORK_NOT_DETECTED",
+		domain: "app",
+		summary: requestedFramework ? `Unsupported framework "${requestedFramework}"` : `Cannot detect a supported framework${directory}`,
+		why: `Supported Beta frameworks: ${supported}.`,
+		fix: "Add one of these frameworks as a dependency, or pass --framework <nextjs|hono|tanstack-start>.",
+		exitCode: 2,
+		nextSteps: [
+			"prisma-cli app deploy --framework nextjs",
+			"prisma-cli app deploy --framework hono",
+			"prisma-cli app deploy --framework tanstack-start"
+		]
+	});
+}
+async function maybeRenderDeploySetupBlock(context, details) {
+	if (context.flags.json || context.flags.quiet) return;
+	const directory = formatDeployDirectory(context.runtime.cwd);
+	if (!details.firstDeploy) {
+		context.output.stderr.write(`Deploying ${directory} to ${details.projectName} / ${details.branchName} / ${details.appName}\n\n`);
+		return;
+	}
+	const title = `Setting up your local directory ${formatLocalDirectory(context.runtime.cwd, context.runtime.env)}`;
+	const rows = details.firstDeploy ? [
+		{
+			label: "Workspace",
+			value: details.workspaceName
+		},
+		{
+			label: "Project",
+			value: details.projectName,
+			origin: details.projectAnnotation
+		},
+		{
+			label: "Branch",
+			value: details.branchName,
+			origin: details.branchAnnotation
+		},
+		{
+			label: "App",
+			value: details.appName,
+			origin: details.appAnnotation
+		},
+		{
+			label: "Framework",
+			value: details.framework.displayName,
+			origin: details.framework.annotation
+		},
+		{
+			label: "Runtime",
+			value: `HTTP ${details.runtime.port}`,
+			origin: details.runtime.annotation
+		}
+	] : [];
+	const lines = [
+		title,
+		"",
+		...renderDeployOutputRows(context.ui, rows),
+		""
+	];
+	context.output.stderr.write(`${lines.join("\n")}\n`);
+}
+function maybeRenderLocalPinBound(context, projectName) {
+	if (context.flags.json || context.flags.quiet) return;
+	context.output.stderr.write(`This directory is now linked to project ${projectName}.\n\n`);
+}
+async function maybeCustomizeDeploySettings(context, options) {
+	if (!options.firstDeploy || context.flags.yes || options.explicitFramework || options.explicitBuildType || options.explicitHttpPort || !canPrompt(context)) return {
+		framework: options.framework,
+		runtime: options.runtime
+	};
+	if (!await confirmPrompt({
+		input: context.runtime.stdin,
+		output: context.runtime.stderr,
+		message: "Customize settings?",
+		initialValue: false
+	})) return {
+		framework: options.framework,
+		runtime: options.runtime
+	};
+	const framework = frameworkFromUserFacingValue(await selectPrompt({
+		input: context.runtime.stdin,
+		output: context.runtime.stderr,
+		message: `Framework (${options.framework.displayName})`,
+		choices: DEPLOY_FRAMEWORKS.map((framework) => ({
+			label: frameworkDisplayName(framework),
+			value: framework
+		}))
+	}), "set by you");
+	const requestedPort = await textPrompt({
+		input: context.runtime.stdin,
+		output: context.runtime.stderr,
+		message: `HTTP port (${options.runtime.port})`,
+		placeholder: String(options.runtime.port),
+		validate: validateDeployHttpPortText
+	});
+	const runtime = {
+		port: requestedPort.trim() ? parseDeployHttpPort(requestedPort) : options.runtime.port,
+		annotation: "set by you"
+	};
+	const changedRows = [framework.key !== options.framework.key ? {
+		label: "Framework",
+		value: framework.displayName,
+		annotation: framework.annotation
+	} : null, runtime.port !== options.runtime.port ? {
+		label: "Runtime",
+		value: `HTTP ${runtime.port}`,
+		annotation: runtime.annotation
+	} : null].filter((row) => Boolean(row));
+	if (changedRows.length > 0 && !context.flags.quiet && !context.flags.json) context.output.stderr.write(`${renderDeployOutputRows(context.ui, changedRows.map((row) => ({
+		label: row.label,
+		value: row.value,
+		origin: row.annotation
+	}))).join("\n")}\n\n`);
+	return {
+		framework,
+		runtime
+	};
+}
+function annotationForProjectResolution(resolution) {
+	switch (resolution.projectSource) {
+		case "explicit": return "set by --project";
+		case "env": return `from ${PRISMA_PROJECT_ID_ENV_VAR}`;
+		case "local-pin": return "from local pin";
+		case "created": return resolution.targetNameSource === "directory-name" ? "created from directory name" : "created from package.json";
+		case "package-name":
+		case "directory-name": return "linked to existing project";
+		case "platform-mapping":
+		case "remembered-local": return "linked to existing project";
+		case "prompt": return "selected by you";
+	}
+}
+function frameworkDisplayName(framework) {
+	switch (framework) {
+		case "nextjs": return "Next.js";
+		case "hono": return "Hono";
+		case "tanstack-start": return "TanStack Start";
+	}
+}
+function validateDeployHttpPortText(value) {
+	if (!value?.trim()) return;
+	try {
+		parseDeployHttpPort(value);
+		return;
 	} catch (error) {
-		if (error instanceof UnsafeConfigWriteError) throw usageError("Project bootstrap requires a writable Prisma config", error.message, "Update prisma.config.ts to use a recognizable project field, or remove it and rerun prisma app deploy.", ["prisma app deploy --app hello-world"], "app");
-		throw error;
+		return error instanceof CliError ? error.summary : String(error);
 	}
 }
+function formatDeployDirectory(cwd) {
+	const basename = path.basename(cwd);
+	return basename ? `./${basename}` : ".";
+}
+function formatLocalDirectory(cwd, env) {
+	const resolved = path.resolve(cwd);
+	const home = env.HOME ? path.resolve(env.HOME) : null;
+	if (home && (resolved === home || resolved.startsWith(`${home}${path.sep}`))) {
+		const relative = path.relative(home, resolved);
+		return relative ? `~/${relative}` : "~";
+	}
+	return resolved;
+}
+async function readCurrentWorkspaceId(context) {
+	const state = await context.stateStore.read();
+	if (state.auth?.workspaceId) return state.auth.workspaceId;
+	return (await readAuthState(context.runtime.env)).workspace?.id ?? null;
+}
 function normalizeBuildType(requestedBuildType) {
 	if (!requestedBuildType) return "auto";
 	if (isPreviewBuildType(requestedBuildType)) return requestedBuildType;
@@ -707,35 +1422,35 @@ function isPreviewBuildType(value) {
 }
 function getBuildTypeExamples(commandName) {
 	return RESOLVED_PREVIEW_BUILD_TYPES.map((buildType) => {
-		return `prisma app ${commandName} --build-type ${buildType}${buildType === "bun" ? " --entry server.ts" : ""}`;
+		return `prisma-cli app ${commandName} --build-type ${buildType}${buildType === "bun" ? " --entry server.ts" : ""}`;
 	});
 }
 function assertSupportedEntrypoint(buildType, entrypoint, commandName) {
-	if (buildType !== "auto" && buildType !== "bun" && entrypoint) throw usageError(`App ${commandName} does not accept --entry with --build-type ${buildType}`, `${formatBuildTypeName(buildType)} apps do not use an entrypoint flag in the current preview.`, `Remove --entry, or rerun prisma app ${commandName} with --build-type bun when you want to target a Bun entrypoint directly.`, [`prisma app ${commandName} --build-type ${buildType}`, `prisma app ${commandName} --build-type bun --entry server.ts`], "app");
+	if (buildType !== "auto" && buildType !== "bun" && entrypoint) throw usageError(`App ${commandName} does not accept --entry with --build-type ${buildType}`, `${formatBuildTypeName(buildType)} apps do not use an entrypoint flag in the current preview.`, `Remove --entry, or rerun prisma-cli app ${commandName} with --build-type bun when you want to target a Bun entrypoint directly.`, [`prisma-cli app ${commandName} --build-type ${buildType}`, `prisma-cli app ${commandName} --build-type bun --entry server.ts`], "app");
 }
 async function requireLocalBuildType(context, buildType, commandName) {
 	const resolvedBuildType = await resolveLocalBuildType(context.runtime.cwd, buildType);
 	if (resolvedBuildType) return resolvedBuildType;
-	throw usageError(`App ${commandName} requires an explicit framework when detection is ambiguous`, "This preview only starts local dev servers for clear Next.js or Bun project shapes.", "Pass --build-type nextjs for a Next.js app, or pass --build-type bun with --entry <path> for a Bun app.", [`prisma app ${commandName} --build-type nextjs`, `prisma app ${commandName} --build-type bun --entry server.ts`], "app");
+	throw usageError(`App ${commandName} requires an explicit framework when detection is ambiguous`, "This preview only starts local dev servers for clear Next.js or Bun project shapes.", "Pass --build-type nextjs for a Next.js app, or pass --build-type bun with --entry <path> for a Bun app.", [`prisma-cli app ${commandName} --build-type nextjs`, `prisma-cli app ${commandName} --build-type bun --entry server.ts`], "app");
 }
 function parseLocalPort(requestedPort) {
 	if (!requestedPort) return DEFAULT_LOCAL_DEV_PORT;
 	const port = Number.parseInt(requestedPort, 10);
-	if (!Number.isInteger(port) || port <= 0 || port > 65535) throw usageError(`Invalid port "${requestedPort}"`, "Port must be an integer between 1 and 65535.", "Pass --port <number> with a valid local port value.", ["prisma app run --port 3000"], "app");
+	if (!Number.isInteger(port) || port <= 0 || port > 65535) throw usageError(`Invalid port "${requestedPort}"`, "Port must be an integer between 1 and 65535.", "Pass --port <number> with a valid local port value.", ["prisma-cli app run --port 3000"], "app");
 	return port;
 }
 function parseDeployPortMapping(requestedPort) {
 	if (!requestedPort) return;
+	return { http: parseDeployHttpPort(requestedPort) };
+}
+function parseDeployHttpPort(requestedPort) {
 	const port = Number.parseInt(requestedPort, 10);
-	if (!Number.isInteger(port) || port <= 0 || port > 65535) throw usageError(`Invalid HTTP port "${requestedPort}"`, "HTTP port must be an integer between 1 and 65535.", "Pass --http-port <number> with a valid port value.", ["prisma app deploy --http-port 3000"], "app");
-	return { http: port };
+	if (!Number.isInteger(port) || port <= 0 || port > 65535) throw usageError(`Invalid HTTP port "${requestedPort}"`, "HTTP port must be an integer between 1 and 65535.", "Pass --http-port <number> with a valid port value.", ["prisma-cli app deploy --http-port 3000"], "app");
+	return port;
 }
 function ensurePreviewAppMode(context) {
 	if (isRealMode(context)) return;
-	throw featureUnavailableError("App commands are not available in fixture mode", "Preview app commands require live app deployment integration.", "Rerun without fixture mode enabled to use preview app deployment workflows.", ["prisma auth login", "prisma project link"], "app");
-}
-function blockedPreviewAppCommandError(summary, why) {
-	return featureUnavailableError(summary, why, "Use prisma app show, prisma app open, prisma app deploy, or prisma app list-deploys in the current preview.", ["prisma app show", "prisma app list-deploys"], "app");
+	throw featureUnavailableError("App commands are not available in fixture mode", "Preview app commands require live app deployment integration.", "Rerun without fixture mode enabled to use preview app deployment workflows.", ["prisma-cli auth login", "prisma-cli project show"], "app");
 }
 function deployFailedError(summary, error, nextSteps) {
 	return new CliError({
@@ -749,15 +1464,138 @@ function deployFailedError(summary, error, nextSteps) {
 		nextSteps
 	});
 }
+function appDeployFailedError(error, progress) {
+	const why = error instanceof Error ? error.message : String(error);
+	const debug = formatDebugDetails(error);
+	if (progress.buildStarted && !progress.buildCompleted) return new CliError({
+		code: "BUILD_FAILED",
+		domain: "app",
+		summary: "Build failed locally.",
+		why,
+		fix: "Inspect the build output above, fix the error, and redeploy.",
+		debug,
+		meta: { phase: "build" },
+		humanLines: [
+			"Build failed locally.",
+			"",
+			`✗ Built       ${why}`,
+			"",
+			"Fix: Inspect the build output above, fix the error, and redeploy."
+		],
+		exitCode: 1,
+		nextSteps: []
+	});
+	if (!progress.buildStarted) return deployFailedError("App deploy failed", error, ["prisma-cli app deploy"]);
+	const phaseHeadline = progress.containerLive ? "The deployment started, but the app is not ready yet." : "Deploy failed after the build completed.";
+	const recoveryLines = progress.versionId ? ["See what happened", `prisma-cli app logs --deployment ${progress.versionId}`] : ["Fix", "Retry the command, or rerun with --trace for more detailed diagnostics."];
+	const urlLines = progress.deploymentUrl ? [
+		"",
+		"URL",
+		progress.deploymentUrl
+	] : [];
+	const humanLines = progress.containerLive ? [
+		phaseHeadline,
+		"",
+		"This is usually a missing env var, a failed DB connection,",
+		"or a crash on startup.",
+		"",
+		...recoveryLines,
+		...urlLines
+	] : [
+		phaseHeadline,
+		"",
+		progress.uploadCompleted ? "The artifact uploaded, but the deployment did not start." : progress.archiveReady ? "The app built locally, but the artifact did not finish uploading." : "The app built locally, but the deployment did not start.",
+		"",
+		...recoveryLines
+	];
+	return new CliError({
+		code: "DEPLOY_FAILED",
+		domain: "app",
+		summary: phaseHeadline,
+		why,
+		fix: progress.versionId ? `Inspect logs with prisma-cli app logs --deployment ${progress.versionId}.` : "Retry the command, or rerun with --trace for more detailed diagnostics.",
+		debug,
+		meta: {
+			phase: progress.containerLive ? "runtime_ready" : "deploy",
+			deploymentId: progress.versionId,
+			deploymentUrl: progress.deploymentUrl
+		},
+		humanLines,
+		exitCode: 1,
+		nextSteps: []
+	});
+}
+function localResolutionPinStaleError() {
+	return new CliError({
+		code: "LOCAL_STATE_STALE",
+		domain: "project",
+		summary: "Local project binding is stale",
+		why: `The target recorded in ${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} is no longer available in the selected workspace.`,
+		fix: `Delete ${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} and re-run to re-bootstrap.`,
+		meta: { pinPath: LOCAL_RESOLUTION_PIN_RELATIVE_PATH },
+		exitCode: 1,
+		nextSteps: ["prisma-cli app deploy"]
+	});
+}
+function readDeployEnvOverride(context, name) {
+	const value = context.runtime.env[name]?.trim();
+	return value ? value : void 0;
+}
+/**
+* `app deploy` falls into "create a new project on first deploy" when no
+* existing project matches the package.json name (or the cwd basename as a
+* fallback). When the create call fails the user often doesn't realise the
+* CLI was attempting to create a project at all — they thought the deploy
+* would find an existing project. Surface that context, and recommend the
+* explicit `--project` flag as the unambiguous way out.
+*/
+function createProjectOnFirstDeployError(options) {
+	const { error, inferredName, workspaceName } = options;
+	const status = extractHttpStatus(error);
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	const inferredContext = `No existing project matched the package.json name \`${inferredName}\`, so the CLI attempted to create one.`;
+	const nextSteps = ["prisma-cli project list", "prisma-cli app deploy --project <id-or-name>"];
+	if (status === 401 || status === 403) return new CliError({
+		code: "AUTH_FORBIDDEN",
+		domain: "auth",
+		summary: "Could not create a new project for this deploy",
+		why: `${inferredContext} The platform rejected the create (HTTP ${status}).`,
+		fix: `Pass --project <id-or-name> to deploy into an existing project, or grant the service token project-create permission on workspace \`${workspaceName}\`.`,
+		debug: formatDebugDetails(error),
+		exitCode: 1,
+		nextSteps
+	});
+	return new CliError({
+		code: "DEPLOY_FAILED",
+		domain: "app",
+		summary: "Could not create a new project for this deploy",
+		why: `${inferredContext} ${errorMessage}`.trim(),
+		fix: "Pass --project <id-or-name> to deploy into an existing project, or retry after addressing the platform error above.",
+		debug: formatDebugDetails(error),
+		exitCode: 1,
+		nextSteps
+	});
+}
+function extractHttpStatus(error) {
+	if (!error || typeof error !== "object") return null;
+	const candidate = error;
+	if (typeof candidate.statusCode === "number") return candidate.statusCode;
+	if (typeof candidate.status === "number") return candidate.status;
+	if (typeof candidate.message === "string") {
+		const match = /\(HTTP (\d{3})\)/.exec(candidate.message);
+		if (match) return Number.parseInt(match[1], 10);
+	}
+	return null;
+}
 function noDeploymentsError(summary, why) {
 	return new CliError({
 		code: "NO_DEPLOYMENTS",
 		domain: "app",
 		summary,
 		why,
-		fix: "Run prisma app deploy first, or use prisma app show to inspect the current app state.",
+		fix: "Run prisma-cli app deploy first, or use prisma-cli app show to inspect the current app state.",
 		exitCode: 1,
-		nextSteps: ["prisma app deploy", "prisma app show"]
+		nextSteps: ["prisma-cli app deploy", "prisma-cli app show"]
 	});
 }
 function buildFailedError(summary, error) {
@@ -766,10 +1604,10 @@ function buildFailedError(summary, error) {
 		domain: "app",
 		summary,
 		why: error instanceof Error ? error.message : String(error),
-		fix: "Inspect the framework output, fix the build issue, and rerun prisma app build.",
+		fix: "Inspect the framework output, fix the build issue, and rerun prisma-cli app build.",
 		debug: formatDebugDetails(error),
 		exitCode: 1,
-		nextSteps: ["prisma app build", "prisma app deploy"]
+		nextSteps: ["prisma-cli app build", "prisma-cli app deploy"]
 	});
 }
 function runFailedError(summary, error, exitCode = 1) {
@@ -778,9 +1616,9 @@ function runFailedError(summary, error, exitCode = 1) {
 		domain: "app",
 		summary,
 		why: error instanceof Error ? error.message : String(error),
-		fix: "Inspect the framework output above, fix the issue, and rerun prisma app run.",
+		fix: "Inspect the framework output above, fix the issue, and rerun prisma-cli app run.",
 		exitCode,
-		nextSteps: ["prisma app run"]
+		nextSteps: ["prisma-cli app run"]
 	});
 }
 function formatFrameworkName(framework) {
@@ -824,11 +1662,30 @@ function isMissingProjectError(error) {
 function findAppByName(apps, name) {
 	return apps.find((app) => app.name === name);
 }
+function findAppsByName(apps, name) {
+	return apps.filter((app) => app.name === name);
+}
 function sortApps(apps) {
 	return apps.slice().sort((left, right) => left.name.localeCompare(right.name) || left.id.localeCompare(right.id));
 }
 function toOptionalEnvVars(envVars) {
 	return Object.keys(envVars).length > 0 ? envVars : void 0;
 }
+/**
+* Emits a deprecation banner to stderr when the legacy single-shot
+* env-var commands are invoked. The banner is suppressed in --json
+* mode so machine consumers keep their JSON channel clean; --json
+* users discover the deprecation via release notes and the new
+* `prisma-cli project env` namespace's output anyway.
+*
+* Removal of these legacy commands is deliberately scoped out of the
+* Public Beta — see the Compute Beta plan, sub-track 3B.1, where the
+* Terminal team picks an explicit removal milestone.
+*/
+function emitLegacyEnvDeprecationWarning(context, legacyCommand, replacement) {
+	if (context.flags.json) return;
+	const message = `[deprecation] \`prisma-cli ${legacyCommand}\` is deprecated. Use \`prisma-cli ${replacement}\` instead.`;
+	context.runtime.stderr.write(`${message}\n`);
+}
 //#endregion
 export { runAppBuild, runAppDeploy, runAppListDeploys, runAppListEnv, runAppLogs, runAppOpen, runAppPromote, runAppRemove, runAppRollback, runAppRun, runAppShow, runAppShowDeploy, runAppUpdateEnv };