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

package/dist/lib/app/bun-project.js

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { access, readFile } from "node:fs/promises";
+import path from "node:path";
 //#region src/lib/app/bun-project.ts
 async function readBunPackageJson(appPath) {
 	const packageJsonPath = path.join(appPath, "package.json");

package/dist/lib/app/deploy-output.js

@@ -0,0 +1,15 @@
+import { padDisplay } from "../../shell/ui.js";
+//#region src/lib/app/deploy-output.ts
+const DEPLOY_OUTPUT_MIN_LABEL_WIDTH = 9;
+const DEPLOY_OUTPUT_MIN_VALUE_WIDTH = 9;
+function renderDeployOutputRows(ui, rows) {
+	if (rows.length === 0) return [];
+	const labelWidth = Math.max(DEPLOY_OUTPUT_MIN_LABEL_WIDTH, ...rows.map((row) => row.label.length));
+	const valueWidth = Math.max(DEPLOY_OUTPUT_MIN_VALUE_WIDTH, ...rows.map((row) => row.value?.length ?? 0));
+	return rows.map((row) => {
+		if (!row.value) return `  ${row.label}`;
+		return `  ${padDisplay(row.label, labelWidth)}  ${padDisplay(ui.strong(row.value), valueWidth)}${row.origin ? `  ${ui.dim(`· ${row.origin}`)}` : ""}`.trimEnd();
+	});
+}
+//#endregion
+export { renderDeployOutputRows };

package/dist/lib/app/env-config.js

@@ -0,0 +1,57 @@
+import { usageError } from "../../shell/errors.js";
+//#region src/lib/app/env-config.ts
+const VALID_ROLES = new Set(["production", "preview"]);
+function positionalHint(command) {
+	if (command === "add" || command === "update") return "KEY=value ";
+	if (command === "rm") return "KEY ";
+	return "";
+}
+function resolveEnvScope(flags, options) {
+	if (flags.roleName) {
+		if (!VALID_ROLES.has(flags.roleName)) throw usageError(`Unknown role "${flags.roleName}"`, "--role accepts production or preview.", "Pass --role production or --role preview.", [`prisma-cli project env ${options.command} --role production`, `prisma-cli project env ${options.command} --role preview`], "app");
+		return {
+			kind: "role",
+			role: flags.roleName
+		};
+	}
+	if (options.requireExplicit) {
+		const positional = positionalHint(options.command);
+		throw usageError(`prisma-cli project env ${options.command} requires --role`, "Writing without an explicit scope is rejected so the command never silently targets production.", "Pass --role production or --role preview.", [`prisma-cli project env ${options.command} ${positional}--role production`, `prisma-cli project env ${options.command} ${positional}--role preview`], "app");
+	}
+	return null;
+}
+function parseKeyValuePositional(raw, command, env = process.env) {
+	if (!raw) throw usageError(`prisma-cli project env ${command} requires KEY=VALUE`, "No KEY=VALUE positional argument was supplied.", "Pass the variable as KEY=VALUE, e.g. STRIPE_KEY=sk_test_xxx.", [`prisma-cli project env ${command} STRIPE_KEY=sk_test_xxx --role production`], "app");
+	const separatorIndex = raw.indexOf("=");
+	if (separatorIndex === -1) {
+		if (KEY_SHAPE.test(raw)) {
+			validateKey(raw, command);
+			const value = env[raw];
+			if (typeof value === "string" && value.length > 0) return {
+				key: raw,
+				value
+			};
+			throw usageError(`Value for "${raw}" was not provided`, `No KEY=VALUE assignment was supplied, and ${raw} is not set in the current environment.`, "Pass KEY=VALUE or export the variable before running the command.", [`prisma-cli project env ${command} ${raw}=value --role production`, `${raw}=value prisma-cli project env ${command} ${raw} --role production`], "app");
+		}
+		throw usageError(`KEY=VALUE argument is missing the = separator`, `"${raw}" does not contain an = character.`, "Pass the variable as KEY=VALUE, e.g. STRIPE_KEY=sk_test_xxx.", [`prisma-cli project env ${command} STRIPE_KEY=sk_test_xxx --role production`], "app");
+	}
+	const key = raw.slice(0, separatorIndex);
+	const value = raw.slice(separatorIndex + 1);
+	validateKey(key, command);
+	if (value.length === 0) throw usageError(`KEY=VALUE argument has an empty value`, `"${raw}" has an empty value after the = separator.`, `Pass a non-empty value, or use prisma-cli project env rm to remove a variable.`, [`prisma-cli project env ${command} ${key}=value --role production`], "app");
+	return {
+		key,
+		value
+	};
+}
+const KEY_SHAPE = /^[A-Z_][A-Z0-9_]*$/;
+function validateKey(key, command) {
+	if (key.length === 0) throw usageError(`Variable key cannot be empty`, "An empty key was passed.", "Pass an env-var key, e.g. STRIPE_KEY.", [`prisma-cli project env ${command} STRIPE_KEY${command === "rm" ? "" : "=value"} --role production`], "app");
+	if (key.length > 256) throw usageError(`Variable key "${key}" exceeds the 256-character limit`, "Env-var keys are capped at 256 characters by the platform.", "Use a shorter key.", [], "app");
+	if (!KEY_SHAPE.test(key)) throw usageError(`Variable key "${key}" must match the POSIX env-var shape`, "Keys must start with an uppercase letter or underscore and contain only uppercase letters, digits, and underscores.", "Rename the key to match [A-Z_][A-Z0-9_]*.", [`prisma-cli project env ${command} STRIPE_KEY${command === "rm" ? "" : "=value"} --role production`], "app");
+}
+function formatScopeLabel(scope) {
+	return scope.role;
+}
+//#endregion
+export { formatScopeLabel, parseKeyValuePositional, resolveEnvScope };

package/dist/lib/app/env-vars.js

@@ -2,15 +2,15 @@ import { usageError } from "../../shell/errors.js";
 //#region src/lib/app/env-vars.ts
 function parseEnvAssignments(assignments, options) {
 	const values = assignments ?? [];
-	if (options.requireAtLeastOne && values.length === 0) throw usageError("At least one environment variable is required", `prisma app ${options.commandName} needs at least one --env NAME=VALUE flag in the current mode.`, `Pass one or more --env NAME=VALUE flags, for example prisma app ${options.commandName} --env DATABASE_URL=postgresql://example.`, [`prisma app ${options.commandName} --env DATABASE_URL=postgresql://example`], "app");
+	if (options.requireAtLeastOne && values.length === 0) throw usageError("At least one environment variable is required", `prisma-cli app ${options.commandName} needs at least one --env NAME=VALUE flag in the current mode.`, `Pass one or more --env NAME=VALUE flags, for example prisma-cli app ${options.commandName} --env DATABASE_URL=postgresql://example.`, [`prisma-cli app ${options.commandName} --env DATABASE_URL=postgresql://example`], "app");
 	const parsed = {};
 	const seen = /* @__PURE__ */ new Set();
 	for (const assignment of values) {
 		const separatorIndex = assignment.indexOf("=");
-		if (separatorIndex === -1) throw usageError("Environment variable assignment must use NAME=VALUE", "A provided --env flag is missing the = separator.", `Pass repeated --env NAME=VALUE flags, for example prisma app ${options.commandName} --env DATABASE_URL=postgresql://example.`, [`prisma app ${options.commandName} --env DATABASE_URL=postgresql://example`], "app");
+		if (separatorIndex === -1) throw usageError("Environment variable assignment must use NAME=VALUE", "A provided --env flag is missing the = separator.", `Pass repeated --env NAME=VALUE flags, for example prisma-cli app ${options.commandName} --env DATABASE_URL=postgresql://example.`, [`prisma-cli app ${options.commandName} --env DATABASE_URL=postgresql://example`], "app");
 		const name = assignment.slice(0, separatorIndex);
-		if (name.length === 0) throw usageError("Environment variable name is required", "A provided --env flag has an empty variable name.", `Pass repeated --env NAME=VALUE flags, for example prisma app ${options.commandName} --env DATABASE_URL=postgresql://example.`, [`prisma app ${options.commandName} --env DATABASE_URL=postgresql://example`], "app");
-		if (seen.has(name)) throw usageError(`Environment variable "${name}" was provided more than once`, "Each environment variable name may be set only once per command invocation.", `Remove the duplicate "${name}" assignment and rerun prisma app ${options.commandName}.`, [`prisma app ${options.commandName} --env ${name}=value`], "app");
+		if (name.length === 0) throw usageError("Environment variable name is required", "A provided --env flag has an empty variable name.", `Pass repeated --env NAME=VALUE flags, for example prisma-cli app ${options.commandName} --env DATABASE_URL=postgresql://example.`, [`prisma-cli app ${options.commandName} --env DATABASE_URL=postgresql://example`], "app");
+		if (seen.has(name)) throw usageError(`Environment variable "${name}" was provided more than once`, "Each environment variable name may be set only once per command invocation.", `Remove the duplicate "${name}" assignment and rerun prisma-cli app ${options.commandName}.`, [`prisma-cli app ${options.commandName} --env ${name}=value`], "app");
 		seen.add(name);
 		parsed[name] = assignment.slice(separatorIndex + 1);
 	}

package/dist/lib/app/local-dev.js

@@ -1,6 +1,6 @@
 import { readBunPackageEntrypoint, readBunPackageJson, resolveBunEntrypoint } from "./bun-project.js";
-import path from "node:path";
 import { access } from "node:fs/promises";
+import path from "node:path";
 import { spawn } from "node:child_process";
 //#region src/lib/app/local-dev.ts
 const NEXT_CONFIG_FILENAMES = [

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

@@ -1,6 +1,6 @@
 import { resolveBunEntrypoint } from "./bun-project.js";
+import { chmod, copyFile, cp, lstat, mkdir, readFile, readdir, readlink, rm, stat } from "node:fs/promises";
 import path from "node:path";
-import { cp, readdir, readlink, rm, stat } from "node:fs/promises";
 import { AstroBuild, BunBuild, NextjsBuild, NuxtBuild, TanstackStartBuild } from "@prisma/compute-sdk";
 //#region src/lib/app/preview-build.ts
 const PREVIEW_BUILD_TYPES = [
@@ -46,6 +46,7 @@ async function executePreviewBuild(options) {
 	});
 	const artifact = await strategy.execute();
 	try {
+		if (buildType === "nextjs") await restageNextjsArtifact(artifact.directory, options.appPath);
 		await normalizeArtifactSymlinks(artifact.directory, options.appPath);
 		return {
 			artifact,
@@ -104,6 +105,68 @@ async function createPreviewBuildStrategy(options) {
 		}
 	}
 }
+async function stageNextjsStandaloneArtifact(options) {
+	const standaloneRoot = path.resolve(options.standaloneDir);
+	const artifactRoot = path.resolve(options.artifactDir);
+	const appRoot = path.resolve(options.appPath);
+	await copyPathMaterializingSymlinks(standaloneRoot, artifactRoot, {
+		standaloneRoot,
+		appRoot,
+		sourceRoot: await resolveSourceRoot(appRoot)
+	});
+	await hoistPnpmDependencies(path.join(artifactRoot, "node_modules"));
+}
+async function restageNextjsArtifact(artifactDir, appPath) {
+	const standaloneDir = path.join(appPath, ".next", "standalone");
+	await rm(artifactDir, {
+		recursive: true,
+		force: true
+	});
+	await stageNextjsStandaloneArtifact({
+		standaloneDir,
+		artifactDir,
+		appPath
+	});
+	const publicDir = path.join(appPath, "public");
+	if (await directoryExists(publicDir)) await cp(publicDir, path.join(artifactDir, "public"), {
+		recursive: true,
+		verbatimSymlinks: true
+	});
+	const staticDir = path.join(appPath, ".next", "static");
+	if (await directoryExists(staticDir)) await cp(staticDir, path.join(artifactDir, ".next", "static"), {
+		recursive: true,
+		verbatimSymlinks: true
+	});
+}
+async function hoistPnpmDependencies(nodeModulesDir) {
+	const pnpmNodeModulesDir = path.join(nodeModulesDir, ".pnpm", "node_modules");
+	if (!await directoryExists(pnpmNodeModulesDir)) return;
+	const entries = await readdir(pnpmNodeModulesDir, { withFileTypes: true });
+	for (const entry of entries) {
+		const sourcePath = path.join(pnpmNodeModulesDir, entry.name);
+		if (entry.name.startsWith("@") && entry.isDirectory()) {
+			const scopedEntries = await readdir(sourcePath, { withFileTypes: true });
+			for (const scopedEntry of scopedEntries) {
+				const scopedDestination = path.join(nodeModulesDir, entry.name, scopedEntry.name);
+				if (await pathExists(scopedDestination)) continue;
+				await mkdir(path.dirname(scopedDestination), { recursive: true });
+				await copyPathMaterializingSymlinks(path.join(sourcePath, scopedEntry.name), scopedDestination, {
+					standaloneRoot: pnpmNodeModulesDir,
+					appRoot: nodeModulesDir,
+					sourceRoot: nodeModulesDir
+				});
+			}
+			continue;
+		}
+		const destinationPath = path.join(nodeModulesDir, entry.name);
+		if (await pathExists(destinationPath)) continue;
+		await copyPathMaterializingSymlinks(sourcePath, destinationPath, {
+			standaloneRoot: pnpmNodeModulesDir,
+			appRoot: nodeModulesDir,
+			sourceRoot: nodeModulesDir
+		});
+	}
+}
 async function normalizeArtifactSymlinks(artifactDir, appPath) {
 	const normalizedArtifactDir = path.resolve(artifactDir);
 	const normalizedAppPath = path.resolve(appPath);
@@ -138,5 +201,69 @@ function isPathWithin(rootPath, candidatePath) {
 	const relativePath = path.relative(rootPath, candidatePath);
 	return relativePath === "" || !relativePath.startsWith(`..${path.sep}`) && relativePath !== ".." && !path.isAbsolute(relativePath);
 }
+async function copyPathMaterializingSymlinks(sourcePath, destinationPath, options) {
+	const sourceStat = await lstat(sourcePath);
+	if (sourceStat.isSymbolicLink()) {
+		await copyPathMaterializingSymlinks(await resolveSymlinkTarget(sourcePath, options), destinationPath, options);
+		return;
+	}
+	if (sourceStat.isDirectory()) {
+		await mkdir(destinationPath, { recursive: true });
+		const entries = await readdir(sourcePath, { withFileTypes: true });
+		for (const entry of entries) await copyPathMaterializingSymlinks(path.join(sourcePath, entry.name), path.join(destinationPath, entry.name), options);
+		return;
+	}
+	if (sourceStat.isFile()) {
+		await mkdir(path.dirname(destinationPath), { recursive: true });
+		await copyFile(sourcePath, destinationPath);
+		await chmod(destinationPath, sourceStat.mode);
+	}
+}
+async function resolveSymlinkTarget(symlinkPath, options) {
+	const linkTarget = await readlink(symlinkPath);
+	const resolvedTarget = path.resolve(path.dirname(symlinkPath), linkTarget);
+	if (await pathExists(resolvedTarget)) {
+		if (!isPathWithin(options.appRoot, resolvedTarget) && !isPathWithin(options.sourceRoot, resolvedTarget)) throw new Error(`Build artifact symlink escapes the app directory: ${resolvedTarget}`);
+		return resolvedTarget;
+	}
+	if (isPathWithin(options.standaloneRoot, resolvedTarget)) {
+		const fallbackTarget = path.join(options.appRoot, path.relative(options.standaloneRoot, resolvedTarget));
+		if (await pathExists(fallbackTarget)) return fallbackTarget;
+	}
+	throw new Error(`Next.js standalone symlink target is missing: ${symlinkPath} -> ${linkTarget} (resolved to ${resolvedTarget})`);
+}
+async function pathExists(targetPath) {
+	try {
+		await stat(targetPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function directoryExists(targetPath) {
+	try {
+		return (await stat(targetPath)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+async function resolveSourceRoot(appRoot) {
+	let current = path.resolve(appRoot);
+	while (true) {
+		if (await pathExists(path.join(current, ".git")) || await pathExists(path.join(current, "pnpm-workspace.yaml")) || await pathExists(path.join(current, "bun.lock")) || await pathExists(path.join(current, "bun.lockb")) || await packageJsonDeclaresWorkspaces(current)) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return path.resolve(appRoot);
+		current = parent;
+	}
+}
+async function packageJsonDeclaresWorkspaces(directory) {
+	try {
+		const content = await readFile(path.join(directory, "package.json"), "utf8");
+		const parsed = JSON.parse(content);
+		return Boolean(parsed.workspaces);
+	} catch {
+		return false;
+	}
+}
 //#endregion
 export { PREVIEW_BUILD_TYPES, PreviewBuildStrategy, RESOLVED_PREVIEW_BUILD_TYPES, executePreviewBuild };

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

@@ -1,38 +1,5 @@
-import { selectPrompt, textPrompt } from "../../shell/prompt.js";
+import "../../shell/prompt.js";
 //#region src/lib/app/preview-interaction.ts
-const CREATE_NEW_APP = "__create_new_app__";
 const PREVIEW_DEFAULT_REGION = "eu-central-1";
-function createPreviewDeployInteraction(context) {
-	return {
-		async selectService(services) {
-			const sorted = services.slice().sort((left, right) => left.name.localeCompare(right.name) || left.id.localeCompare(right.id));
-			const selection = await selectPrompt({
-				input: context.runtime.stdin,
-				output: context.runtime.stderr,
-				message: "Select an app",
-				choices: [...sorted.map((service) => ({
-					label: service.name,
-					value: service.id
-				})), {
-					label: "Create a new app",
-					value: CREATE_NEW_APP
-				}]
-			});
-			return selection === CREATE_NEW_APP ? null : selection;
-		},
-		async provideServiceName() {
-			return textPrompt({
-				input: context.runtime.stdin,
-				output: context.runtime.stderr,
-				message: "App name",
-				placeholder: "hello-world",
-				validate: (value) => !value?.trim() ? "App name is required" : void 0
-			}).then((value) => value.trim());
-		},
-		async selectRegion(_regions) {
-			return PREVIEW_DEFAULT_REGION;
-		}
-	};
-}
 //#endregion
-export { PREVIEW_DEFAULT_REGION, createPreviewDeployInteraction };
+export { PREVIEW_DEFAULT_REGION };

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

@@ -1,83 +1,68 @@
+import { renderDeployOutputRows } from "./deploy-output.js";
 //#region src/lib/app/preview-progress.ts
-function createPreviewDeployProgress(output, enabled) {
-	if (!enabled) return;
+function createPreviewDeployProgressState() {
+	return {
+		buildStarted: false,
+		buildCompleted: false,
+		archiveReady: false,
+		uploadCompleted: false,
+		versionId: null,
+		startRequested: false,
+		containerLive: false,
+		deploymentUrl: null,
+		promotedUrl: null
+	};
+}
+function createPreviewDeployProgress(output, ui, enabled, state = createPreviewDeployProgressState()) {
 	const write = (line) => {
+		if (!enabled) return;
 		output.write(`${line}\n`);
 	};
+	const writeRows = (rows) => {
+		for (const line of renderDeployOutputRows(ui, rows)) write(line);
+	};
 	return {
 		onBuildStart() {
-			write("Building application...");
+			state.buildStarted = true;
+			write("Building locally...");
 		},
 		onBuildComplete() {
-			write("Build complete.");
-		},
-		onArchiveCreating() {
-			write("Creating deployment artifact...");
+			state.buildCompleted = true;
 		},
 		onArchiveReady(byteLength) {
-			write(`Artifact ready (${(byteLength / 1024).toFixed(1)} KB).`);
+			state.archiveReady = true;
+			writeRows([{
+				label: "Built",
+				value: formatArtifactSize(byteLength)
+			}]);
+		},
+		onUploadStart() {
+			write("Uploading...");
 		},
 		onVersionCreated(versionId) {
-			write(`Deployment ${versionId} created.`);
+			state.versionId = versionId;
 		},
 		onUploadComplete() {
-			write("Upload complete.");
+			state.uploadCompleted = true;
+			writeRows([{ label: "Uploaded" }]);
 		},
 		onStartRequested() {
-			write("Starting deployment...");
-		},
-		onStatusChange(status) {
-			write(`Status: ${status}`);
+			state.startRequested = true;
+			write("Deploying...");
 		},
 		onRunning(url) {
-			if (url) {
-				write(`Deployment is running at ${url}.`);
-				return;
-			}
-			write("Deployment is running.");
-		},
-		onPromoteStart() {
-			write("Promoting deployment...");
+			state.containerLive = true;
+			state.deploymentUrl = url;
+			writeRows([{ label: "Deployed" }]);
 		},
 		onPromoted(url) {
-			if (url) {
-				write(`Promoted to ${url}.`);
-				return;
-			}
-			write("Promotion complete.");
-		},
-		onPromoteFailed(error) {
-			write(`Promotion failed${error?.message ? `: ${error.message}` : "."}`);
-		},
-		onOldVersionStopping(versionId) {
-			write(`Stopping previous deployment ${versionId}...`);
-		},
-		onOldVersionStopped(versionId) {
-			write(`Previous deployment ${versionId} stopped.`);
-		},
-		onOldVersionStopFailed(versionId) {
-			write(`Failed to stop previous deployment ${versionId} (non-fatal).`);
-		},
-		onOldVersionDeleting(versionId) {
-			write(`Deleting previous deployment ${versionId}...`);
-		},
-		onOldVersionDeleted(versionId) {
-			write(`Previous deployment ${versionId} deleted.`);
-		},
-		onOldVersionDeleteFailed(versionId) {
-			write(`Failed to delete previous deployment ${versionId} (non-fatal).`);
-		},
-		onCleanupDanglingVersion(versionId) {
-			write(`Cleaning up deployment ${versionId}...`);
-		},
-		onCleanupDanglingVersionComplete(versionId) {
-			write(`Deployment ${versionId} cleaned up.`);
-		},
-		onCleanupDanglingVersionFailed(versionId) {
-			write(`Failed to clean up deployment ${versionId}.`);
+			state.promotedUrl = url;
 		}
 	};
 }
+function formatArtifactSize(byteLength) {
+	return `${(byteLength / 1024 / 1024).toFixed(1)} MB`;
+}
 function createPreviewPromoteProgress(output, enabled) {
 	if (!enabled) return;
 	const write = (line) => {
@@ -136,4 +121,4 @@ function createPreviewUpdateEnvProgress(output, enabled) {
 	};
 }
 //#endregion
-export { createPreviewDeployProgress, createPreviewPromoteProgress, createPreviewUpdateEnvProgress };
+export { createPreviewDeployProgress, createPreviewDeployProgressState, createPreviewPromoteProgress, createPreviewUpdateEnvProgress };

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

@@ -1,9 +1,9 @@
 import { envVarNames } from "./env-vars.js";
 import { PreviewBuildStrategy } from "./preview-build.js";
 import path from "node:path";
-import { ApiError, ComputeClient } from "@prisma/compute-sdk";
+import { ApiError, CancelledError, ComputeClient, streamLogs } from "@prisma/compute-sdk";
 //#region src/lib/app/preview-provider.ts
-function createPreviewAppProvider(client) {
+function createPreviewAppProvider(client, options) {
 	const sdk = new ComputeClient(client);
 	return {
 		async createProject(options) {
@@ -14,25 +14,11 @@ function createPreviewAppProvider(client) {
 				name: projectResult.value.name
 			};
 		},
-		async listApps(projectId) {
-			const servicesResult = await sdk.listServices({ projectId });
-			if (servicesResult.isErr()) throw new Error(servicesResult.error.message);
-			return (await Promise.all(servicesResult.value.map(async (service) => {
-				const detailResult = await sdk.showService({ serviceId: service.id });
-				return detailResult.isOk() ? detailResult.value : {
-					id: service.id,
-					name: service.name,
-					region: service.region,
-					latestVersionId: null,
-					serviceEndpointDomain: void 0
-				};
-			}))).map((service) => ({
-				id: service.id,
-				name: service.name,
-				region: service.region ?? null,
-				liveDeploymentId: service.latestVersionId ?? null,
-				liveUrl: toAbsoluteUrl(service.serviceEndpointDomain ?? null)
-			}));
+		async listApps(projectId, options) {
+			return listComputeServices(client, {
+				projectId,
+				branchGitName: options?.branchName
+			});
 		},
 		async removeApp(appId) {
 			const appResult = await sdk.showService({ serviceId: appId });
@@ -60,6 +46,20 @@ function createPreviewAppProvider(client) {
 			if (promoteResult.isErr()) throw new Error(promoteResult.error.message);
 		},
 		async deployApp(options) {
+			const resolvedApp = options.appId ? {
+				appId: options.appId,
+				appName: options.appName,
+				region: options.region
+			} : options.branchName && options.appName ? await createBranchApp(client, {
+				projectId: options.projectId,
+				branchName: options.branchName,
+				appName: options.appName,
+				region: options.region
+			}) : {
+				appId: void 0,
+				appName: options.appName,
+				region: options.region
+			};
 			const deployResult = await sdk.deploy({
 				strategy: new PreviewBuildStrategy({
 					appPath: path.resolve(options.cwd),
@@ -67,9 +67,9 @@ function createPreviewAppProvider(client) {
 					buildType: options.buildType
 				}),
 				projectId: options.projectId,
-				serviceId: options.appId,
-				serviceName: options.appName,
-				region: options.region,
+				serviceId: resolvedApp.appId,
+				serviceName: resolvedApp.appName,
+				region: resolvedApp.region,
 				portMapping: options.portMapping,
 				envVars: options.envVars,
 				timeoutSeconds: 120,
@@ -197,9 +197,110 @@ function createPreviewAppProvider(client) {
 					live: null
 				}
 			};
+		},
+		async streamDeploymentLogs(streamOptions) {
+			if (!options?.baseUrl || !options.getToken) throw new Error("Log streaming requires an authenticated API base URL and token.");
+			const result = await streamLogs({
+				baseUrl: options.baseUrl,
+				token: await options.getToken(),
+				versionId: streamOptions.deploymentId,
+				signal: streamOptions.signal
+			}, streamOptions.onRecord);
+			if (result.isErr()) {
+				if (CancelledError.is(result.error)) return;
+				throw result.error;
+			}
 		}
 	};
 }
+async function listBranches(client, options) {
+	const result = await client.GET("/v1/projects/{projectId}/branches", { params: {
+		path: { projectId: options.projectId },
+		query: { gitName: options.gitName }
+	} });
+	if (result.error || !result.data) throw apiCallError("Failed to list branches", result.response, result.error);
+	return result.data.data;
+}
+async function resolveOrCreateBranch(client, options) {
+	const existing = (await listBranches(client, options))[0];
+	if (existing) return existing;
+	const result = await client.POST("/v1/projects/{projectId}/branches", {
+		params: { path: { projectId: options.projectId } },
+		body: {
+			gitName: options.gitName,
+			isDefault: options.gitName === "main"
+		}
+	});
+	if (result.error || !result.data) {
+		if (result.response.status === 409) {
+			const raced = (await listBranches(client, options))[0];
+			if (raced) return raced;
+		}
+		throw apiCallError(`Failed to create branch "${options.gitName}"`, result.response, result.error);
+	}
+	return result.data.data;
+}
+async function listComputeServices(client, options) {
+	const services = [];
+	let cursor;
+	while (true) {
+		const result = await client.GET("/v1/compute-services", { params: { query: {
+			projectId: options.projectId,
+			branchGitName: options.branchGitName,
+			cursor
+		} } });
+		if (result.error || !result.data) throw apiCallError("Failed to list apps", result.response, result.error);
+		services.push(...result.data.data);
+		if (!result.data.pagination.hasMore || !result.data.pagination.nextCursor) break;
+		cursor = result.data.pagination.nextCursor;
+	}
+	return services.map((service) => ({
+		id: service.id,
+		name: service.name,
+		region: service.region.id ?? null,
+		branchId: service.branchId,
+		liveDeploymentId: service.latestVersionId ?? null,
+		liveUrl: toAbsoluteUrl(service.serviceEndpointDomain ?? null)
+	}));
+}
+async function createBranchApp(client, options) {
+	const branch = await resolveOrCreateBranch(client, {
+		projectId: options.projectId,
+		gitName: options.branchName
+	});
+	const result = await client.POST("/v1/compute-services", { body: {
+		projectId: options.projectId,
+		branchId: branch.id,
+		displayName: options.appName,
+		...options.region ? { regionId: options.region } : {}
+	} });
+	if (result.error || !result.data) {
+		if (result.response.status === 409) {
+			const matched = (await listComputeServices(client, {
+				projectId: options.projectId,
+				branchGitName: options.branchName
+			})).find((app) => app.name === options.appName);
+			if (matched) return {
+				appId: matched.id,
+				appName: matched.name,
+				region: matched.region ?? options.region
+			};
+		}
+		throw apiCallError(`Failed to create app "${options.appName}"`, result.response, result.error);
+	}
+	const service = result.data.data;
+	return {
+		appId: service.id,
+		appName: service.name,
+		region: service.region.id ?? options.region
+	};
+}
+function apiCallError(summary, response, error) {
+	if (response.status === 404) return /* @__PURE__ */ new Error("Resource Not Found");
+	const message = error.error?.message ?? `Management API returned HTTP ${response.status}.`;
+	const hint = error.error?.hint ? ` ${error.error.hint}` : "";
+	return /* @__PURE__ */ new Error(`${summary}: ${message}${hint}`);
+}
 async function findAppForDeployment(sdk, deploymentId) {
 	const projectsResult = await sdk.listProjects();
 	if (projectsResult.isErr()) throw new Error(projectsResult.error.message);