@prisma/cli 3.0.0-dev.81.1 → 3.0.0-dev.83.1

package/dist/lib/app/branch-database.js

@@ -69,7 +69,8 @@ function hasBranchDatabaseSignal(signal) {
 }
 async function runBranchDatabaseSchemaSetup(options) {
 	const schemaPath = path.relative(options.context.runtime.cwd, options.schema.path) || defaultSchemaSourcePath(options.schema);
-	const commands = buildSchemaSetupCommands(options.schema, schemaPath, options.databaseUrl);
+	const prisma = await resolvePrismaInvocation(options.context.runtime.cwd);
+	const commands = buildSchemaSetupCommands(options.schema, schemaPath, options.databaseUrl, prisma);
 	for (const command of commands) await runPrismaCommand({
 		context: options.context,
 		...command,
@@ -87,29 +88,41 @@ async function runBranchDatabaseSchemaSetup(options) {
 async function scanDirectory(cwd, directory, depth, state, signal) {
 	signal.throwIfAborted();
 	if (depth > MAX_SCAN_DEPTH || state.filesVisited >= MAX_SCAN_FILES) return;
-	let entries;
-	try {
-		entries = await readdir(directory, { withFileTypes: true });
-	} catch (error) {
-		if (error.code === "ENOENT") return;
-		throw error;
-	}
+	const entries = await readDirectoryEntries(directory);
+	if (!entries) return;
 	entries.sort((left, right) => left.name.localeCompare(right.name));
 	for (const entry of entries) {
 		signal.throwIfAborted();
 		if (state.filesVisited >= MAX_SCAN_FILES) return;
-		const entryPath = path.join(directory, entry.name);
-		if (entry.isDirectory()) {
-			if (!SKIPPED_DIRECTORIES.has(entry.name)) await scanDirectory(cwd, entryPath, depth + 1, state, signal);
-			continue;
-		}
-		if (!entry.isFile()) continue;
-		state.filesVisited += 1;
-		if (entry.name === "schema.prisma") state.schemaCandidates.push(entryPath);
-		if (isPrismaNextConfigFile(entry.name)) state.prismaNextConfigCandidates.push(entryPath);
-		if (state.databaseUrlReferences.length < MAX_DATABASE_URL_REFERENCE_FILES && shouldScanForDatabaseUrl(entry.name) && await fileContainsDatabaseUrl(entryPath, signal)) state.databaseUrlReferences.push(path.relative(cwd, entryPath) || entry.name);
+		await scanDirectoryEntry(cwd, directory, entry, depth, state, signal);
 	}
 }
+async function readDirectoryEntries(directory) {
+	try {
+		return await readdir(directory, { withFileTypes: true });
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+async function scanDirectoryEntry(cwd, directory, entry, depth, state, signal) {
+	const entryPath = path.join(directory, entry.name);
+	if (entry.isDirectory()) {
+		if (!SKIPPED_DIRECTORIES.has(entry.name)) await scanDirectory(cwd, entryPath, depth + 1, state, signal);
+		return;
+	}
+	if (!entry.isFile()) return;
+	state.filesVisited += 1;
+	collectBranchDatabaseCandidate(entryPath, entry.name, state);
+	if (await shouldRecordDatabaseUrlReference(entryPath, entry.name, state, signal)) state.databaseUrlReferences.push(path.relative(cwd, entryPath) || entry.name);
+}
+function collectBranchDatabaseCandidate(entryPath, entryName, state) {
+	if (entryName === "schema.prisma") state.schemaCandidates.push(entryPath);
+	if (isPrismaNextConfigFile(entryName)) state.prismaNextConfigCandidates.push(entryPath);
+}
+async function shouldRecordDatabaseUrlReference(entryPath, entryName, state, signal) {
+	return state.databaseUrlReferences.length < MAX_DATABASE_URL_REFERENCE_FILES && shouldScanForDatabaseUrl(entryName) && await fileContainsDatabaseUrl(entryPath, signal);
+}
 async function selectPrismaOrmSchema(cwd, candidates, signal) {
 	const sorted = sortByPreferredRelativePath(cwd, candidates, "schema.prisma");
 	for (const schemaPath of sorted) {
@@ -142,12 +155,15 @@ async function selectPrismaOrmSchema(cwd, candidates, signal) {
 	};
 }
 function selectPrismaNextConfig(cwd, candidates, mode) {
-	const matches = candidates.filter((candidate) => {
-		const isSupported = candidate.target === "postgresql" || candidate.target === "unknown";
-		return mode === "supported" ? isSupported : !isSupported;
-	});
+	const matches = candidates.filter(mode === "supported" ? isSupportedPrismaNextConfig : isUnsupportedPrismaNextConfig);
 	return sortByPreferredRelativePath(cwd, matches.map((candidate) => candidate.path), "prisma-next.config.ts").map((candidatePath) => matches.find((candidate) => candidate.path === candidatePath)).find((candidate) => Boolean(candidate)) ?? null;
 }
+function isSupportedPrismaNextConfig(candidate) {
+	return candidate.target === "postgresql" || candidate.target === "unknown";
+}
+function isUnsupportedPrismaNextConfig(candidate) {
+	return !isSupportedPrismaNextConfig(candidate);
+}
 function sortByPreferredRelativePath(cwd, candidates, preferredRootFile) {
 	return candidates.map((candidate) => ({
 		absolute: candidate,
@@ -229,28 +245,73 @@ async function readTextFileIfSmall(filePath, signal) {
 		signal
 	});
 }
-function buildSchemaSetupCommands(schema, schemaPath, databaseUrl) {
+const FALLBACK_PRISMA_CLI_VERSION = "6.19.3";
+/**
+* Picks how `prisma` CLI commands are invoked for schema setup. Projects
+* with the CLI installed run their own binary (version-exact). Projects
+* without it fall back to a versioned `npx prisma@<x>` pinned to the
+* installed `@prisma/client` — never bare `npx prisma`, which resolves to
+* latest and can be a major version ahead of the project's schema.
+*/
+async function resolvePrismaInvocation(cwd) {
+	if (await localPrismaBinExists(cwd)) return {
+		argsPrefix: ["--no-install", "prisma"],
+		displayPrefix: "npx --no-install prisma"
+	};
+	const pinned = await readInstalledPrismaClientVersion(cwd) ?? FALLBACK_PRISMA_CLI_VERSION;
+	return {
+		argsPrefix: ["--yes", `prisma@${pinned}`],
+		displayPrefix: `npx prisma@${pinned}`
+	};
+}
+/** npm/pnpm name the local CLI shim `prisma` on POSIX and `prisma.cmd`/`prisma.ps1` on Windows. */
+async function localPrismaBinExists(cwd) {
+	const binDir = path.join(cwd, "node_modules", ".bin");
+	return (await Promise.all([
+		"prisma",
+		"prisma.cmd",
+		"prisma.ps1"
+	].map((name) => fileExists(path.join(binDir, name))))).some(Boolean);
+}
+async function fileExists(filePath) {
+	try {
+		await access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function readInstalledPrismaClientVersion(cwd) {
+	try {
+		const raw = await readFile(path.join(cwd, "node_modules", "@prisma", "client", "package.json"), { encoding: "utf8" });
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const version = parsed.version;
+		return typeof version === "string" && version.length > 0 ? version : null;
+	} catch {
+		return null;
+	}
+}
+function buildSchemaSetupCommands(schema, schemaPath, databaseUrl, prisma) {
 	if (schema.command === "migrate-deploy") return [{
 		args: [
-			"--no-install",
-			"prisma",
+			...prisma.argsPrefix,
 			"migrate",
 			"deploy",
 			"--schema",
 			schemaPath
 		],
-		displayCommand: "npx --no-install prisma migrate deploy"
+		displayCommand: `${prisma.displayPrefix} migrate deploy`
 	}];
 	if (schema.command === "db-push") return [{
 		args: [
-			"--no-install",
-			"prisma",
+			...prisma.argsPrefix,
 			"db",
 			"push",
 			"--schema",
 			schemaPath
 		],
-		displayCommand: "npx --no-install prisma db push"
+		displayCommand: `${prisma.displayPrefix} db push`
 	}];
 	return [{
 		args: [

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

@@ -1,6 +1,6 @@
 import { readBunPackageJson, resolveBunEntrypoint } from "./bun-project.js";
 import { PRISMA_APP_CONFIG_FILENAME, hasAnyPackageDependency, hasPackageDependency, hasRootFile, joinPosix, nextOutputRootFromStandaloneDirectory, resolvePreviewBuildSettings, runResolvedBuildCommand } from "./preview-build-settings.js";
-import { chmod, copyFile, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat } from "node:fs/promises";
+import { chmod, copyFile, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
 import { AstroBuild, BunBuild, NuxtBuild } from "@prisma/compute-sdk";
@@ -151,7 +151,7 @@ var PreviewNextjsBuild = class {
 		});
 		await runResolvedBuildCommand(this.#appPath, settings, "Next.js", signal);
 		const standaloneDir = path.join(this.#appPath, settings.outputDirectory);
-		if (!await directoryExists(standaloneDir, signal)) throw new Error(`Next.js build did not produce standalone output at ${settings.outputDirectory}. Add output: "standalone" to your next.config file, or update ${PRISMA_APP_CONFIG_FILENAME}.`);
+		if (!await directoryExists(standaloneDir, signal)) return stageNextjsFullTreeFallbackArtifact(this.#appPath, signal);
 		const outDir = await unsupportedFilesystemBoundary(signal, () => mkdtemp(path.join(os.tmpdir(), "compute-build-")));
 		try {
 			const artifactDir = path.join(outDir, "app");
@@ -187,6 +187,45 @@ var PreviewNextjsBuild = class {
 		}
 	}
 };
+const FULL_TREE_NEXT_START_ENTRYPOINT = "prisma-next-start.cjs";
+const FULL_TREE_NEXT_START_SOURCE = [
+	"process.chdir(__dirname);",
+	"process.env.NODE_ENV = \"production\";",
+	"process.argv.push(\"start\", \"-p\", process.env.PORT ?? \"3000\");",
+	"require(\"next/dist/bin/next\");",
+	""
+].join("\n");
+async function stageNextjsFullTreeFallbackArtifact(appPath, signal) {
+	const outDir = await unsupportedFilesystemBoundary(signal, () => mkdtemp(path.join(os.tmpdir(), "compute-build-")));
+	try {
+		const artifactDir = path.join(outDir, "app");
+		await unsupportedFilesystemBoundary(signal, () => cp(appPath, artifactDir, {
+			recursive: true,
+			verbatimSymlinks: true,
+			filter: (source) => !isExcludedFromFullTreeArtifact(path.basename(source))
+		}));
+		await unsupportedFilesystemBoundary(signal, () => writeFile(path.join(artifactDir, FULL_TREE_NEXT_START_ENTRYPOINT), FULL_TREE_NEXT_START_SOURCE));
+		return {
+			directory: artifactDir,
+			entrypoint: FULL_TREE_NEXT_START_ENTRYPOINT,
+			defaultPortMapping: { http: 3e3 },
+			cleanup: () => rm(outDir, {
+				recursive: true,
+				force: true
+			})
+		};
+	} catch (error) {
+		await rm(outDir, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+/** Excludes VCS internals and dotenv files (local secrets, superseded by the deploy env). */
+function isExcludedFromFullTreeArtifact(basename) {
+	return basename === ".git" || basename === ".env" || basename.startsWith(".env.");
+}
 var PreviewTanstackStartBuild = class {
 	#appPath;
 	#buildSettings;
@@ -362,23 +401,31 @@ async function normalizeArtifactSymlinks(artifactDir, appPath, signal) {
 				continue;
 			}
 			if (!entry.isSymbolicLink()) continue;
-			const target = await unsupportedFilesystemBoundary(signal, () => readlink(fullPath));
-			const resolvedTarget = path.resolve(path.dirname(fullPath), target);
-			if (isPathWithin(normalizedArtifactDir, resolvedTarget)) continue;
-			if (!isPathWithin(normalizedAppPath, resolvedTarget)) throw new Error(`Build artifact symlink escapes the app directory: ${resolvedTarget}`);
-			const targetStat = await unsupportedFilesystemBoundary(signal, () => stat(resolvedTarget));
-			await unsupportedFilesystemBoundary(signal, () => rm(fullPath, {
-				force: true,
-				recursive: true
-			}));
-			await unsupportedFilesystemBoundary(signal, () => cp(resolvedTarget, fullPath, {
-				recursive: targetStat.isDirectory(),
-				dereference: true
-			}));
-			if (targetStat.isDirectory()) await walkDirectory(fullPath);
+			if (await materializeArtifactSymlink({
+				fullPath,
+				normalizedArtifactDir,
+				normalizedAppPath,
+				signal
+			}) === "directory") await walkDirectory(fullPath);
 		}
 	}
 }
+async function materializeArtifactSymlink(options) {
+	const target = await unsupportedFilesystemBoundary(options.signal, () => readlink(options.fullPath));
+	const resolvedTarget = path.resolve(path.dirname(options.fullPath), target);
+	if (isPathWithin(options.normalizedArtifactDir, resolvedTarget)) return "internal";
+	if (!isPathWithin(options.normalizedAppPath, resolvedTarget)) throw new Error(`Build artifact symlink escapes the app directory: ${resolvedTarget}`);
+	const targetStat = await unsupportedFilesystemBoundary(options.signal, () => stat(resolvedTarget));
+	await unsupportedFilesystemBoundary(options.signal, () => rm(options.fullPath, {
+		force: true,
+		recursive: true
+	}));
+	await unsupportedFilesystemBoundary(options.signal, () => cp(resolvedTarget, options.fullPath, {
+		recursive: targetStat.isDirectory(),
+		dereference: true
+	}));
+	return targetStat.isDirectory() ? "directory" : "file";
+}
 function isPathWithin(rootPath, candidatePath) {
 	const relativePath = path.relative(rootPath, candidatePath);
 	return relativePath === "" || !relativePath.startsWith(`..${path.sep}`) && relativePath !== ".." && !path.isAbsolute(relativePath);

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

@@ -509,29 +509,33 @@ async function findAppForDeployment(sdk, deploymentId, signal) {
 		});
 		if (servicesResult.isErr()) throw new Error(servicesResult.error.message);
 		for (const service of servicesResult.value) {
-			const detailResult = await sdk.showService({
-				serviceId: service.id,
-				signal
-			});
-			if (detailResult.isErr()) throw new Error(detailResult.error.message);
-			const app = {
-				id: detailResult.value.id,
-				name: detailResult.value.name,
-				region: detailResult.value.region ?? null,
-				liveDeploymentId: detailResult.value.latestVersionId ?? null,
-				liveUrl: toAbsoluteUrl(detailResult.value.serviceEndpointDomain ?? null)
-			};
-			if (app.liveDeploymentId === deploymentId) return app;
-			const versionsResult = await sdk.listVersions({
-				serviceId: service.id,
-				signal
-			});
-			if (versionsResult.isErr()) throw new Error(versionsResult.error.message);
-			if (versionsResult.value.some((version) => version.id === deploymentId)) return app;
+			const app = await findServiceAppForDeployment(sdk, service.id, deploymentId, signal);
+			if (app) return app;
 		}
 	}
 	return null;
 }
+async function findServiceAppForDeployment(sdk, serviceId, deploymentId, signal) {
+	const detailResult = await sdk.showService({
+		serviceId,
+		signal
+	});
+	if (detailResult.isErr()) throw new Error(detailResult.error.message);
+	const app = {
+		id: detailResult.value.id,
+		name: detailResult.value.name,
+		region: detailResult.value.region ?? null,
+		liveDeploymentId: detailResult.value.latestVersionId ?? null,
+		liveUrl: toAbsoluteUrl(detailResult.value.serviceEndpointDomain ?? null)
+	};
+	if (app.liveDeploymentId === deploymentId) return app;
+	const versionsResult = await sdk.listVersions({
+		serviceId,
+		signal
+	});
+	if (versionsResult.isErr()) throw new Error(versionsResult.error.message);
+	return versionsResult.value.some((version) => version.id === deploymentId) ? app : null;
+}
 function toAbsoluteUrl(url) {
 	if (!url) return null;
 	return url.startsWith("https://") || url.startsWith("http://") ? url : `https://${url}`;

package/dist/lib/app/production-deploy-gate.js

@@ -1,6 +1,6 @@
 import { CliError } from "../../shell/errors.js";
-import { canPrompt } from "../../shell/runtime.js";
 import { confirmPrompt } from "../../shell/prompt.js";
+import { canPrompt } from "../../shell/runtime.js";
 //#region src/lib/app/production-deploy-gate.ts
 async function enforceProductionDeployGate(context, provider, options) {
 	if (options.branchKind !== "production") return { firstProductionDeploy: false };

package/dist/lib/auth/login.js

@@ -106,35 +106,42 @@ async function consumePastedCallback(options) {
 	});
 	try {
 		for (;;) {
-			let answer;
-			try {
-				answer = await rl.question("Paste the callback URL here: ", { signal: options.signal });
-			} catch (error) {
-				if (error?.name === "AbortError") return;
-				throw error;
-			}
-			const trimmed = answer.trim().replace(/^["']|["']$/g, "");
-			let url;
-			try {
-				if (!trimmed) throw new Error("empty input");
-				url = new URL(trimmed);
-			} catch {
-				options.output.write("That didn't look like a URL. Paste the full localhost callback URL and try again.\n");
-				continue;
-			}
-			try {
-				await options.complete(url);
-				return;
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				options.output.write(`Sign-in didn't complete (${message}). Paste the callback URL to try again.\n`);
-				continue;
-			}
+			const url = await readPastedCallbackUrl(rl, options);
+			if (url === null) return;
+			if (url === void 0) continue;
+			if (await tryCompletePastedCallback(url, options)) return;
 		}
 	} finally {
 		rl.close();
 	}
 }
+async function readPastedCallbackUrl(rl, options) {
+	let answer;
+	try {
+		answer = await rl.question("Paste the callback URL here: ", { signal: options.signal });
+	} catch (error) {
+		if (error?.name === "AbortError") return null;
+		throw error;
+	}
+	const trimmed = answer.trim().replace(/^["']|["']$/g, "");
+	try {
+		if (!trimmed) throw new Error("empty input");
+		return new URL(trimmed);
+	} catch {
+		options.output.write("That didn't look like a URL. Paste the full localhost callback URL and try again.\n");
+		return;
+	}
+}
+async function tryCompletePastedCallback(url, options) {
+	try {
+		await options.complete(url);
+		return true;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		options.output.write(`Sign-in didn't complete (${message}). Paste the callback URL to try again.\n`);
+		return false;
+	}
+}
 var LoginState = class {
 	latestVerifier;
 	latestState;

package/dist/lib/project/resolution.js

@@ -1,6 +1,6 @@
 import { CliError } from "../../shell/errors.js";
-import { formatCommandArgument } from "../../shell/command-arguments.js";
 import { LOCAL_RESOLUTION_PIN_RELATIVE_PATH, readLocalResolutionPin } from "./local-pin.js";
+import { formatCommandArgument } from "../../shell/command-arguments.js";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { Result, TaggedError, matchError } from "better-result";

package/dist/lib/project/setup.js

@@ -1,6 +1,6 @@
 import { CliError, usageError } from "../../shell/errors.js";
-import "../../shell/command-arguments.js";
 import { LOCAL_RESOLUTION_PIN_RELATIVE_PATH, ensureLocalResolutionPinGitignore, writeLocalResolutionPin } from "./local-pin.js";
+import "../../shell/command-arguments.js";
 import { projectAmbiguousError, projectNotFoundError } from "./resolution.js";
 import { Result, matchError } from "better-result";
 //#region src/lib/project/setup.ts
@@ -13,7 +13,8 @@ function validateProjectSetupNameText(value, fallback) {
 }
 function resolveProjectForSetup(projectRef, projects, workspace) {
 	const matches = projects.filter((project) => project.id === projectRef || project.name === projectRef);
-	if (matches.length === 1) return matches[0];
+	const match = matches[0];
+	if (matches.length === 1 && match) return match;
 	if (matches.length > 1) throw projectAmbiguousError(projectRef, matches);
 	throw projectNotFoundError(projectRef, workspace);
 }

package/dist/output/patterns.js

@@ -1,5 +1,5 @@
-import { maskValue, padDisplay, renderSummaryLine } from "../shell/ui.js";
 import { formatDescriptorLabel } from "../shell/command-meta.js";
+import { maskValue, padDisplay, renderSummaryLine } from "../shell/ui.js";
 import stringWidth from "string-width";
 //#region src/output/patterns.ts
 function renderList(input, ui) {

package/dist/presenters/app.js

@@ -56,7 +56,7 @@ function serializeAppDeploy(result) {
 	};
 }
 function renderBranchDatabaseDeploySummary(context, result) {
-	if (!result.branchDatabase || result.branchDatabase.status !== "created") return [];
+	if (result.branchDatabase?.status !== "created") return [];
 	return ["", ...renderDeployOutputRows(context.ui, [
 		{
 			label: "Database",

package/dist/presenters/branch.js

@@ -1,5 +1,5 @@
-import { formatColumns } from "../shell/ui.js";
 import { formatDescriptorLabel } from "../shell/command-meta.js";
+import { formatColumns } from "../shell/ui.js";
 import { renderResolvedProjectContextBlock } from "./verbose-context.js";
 //#region src/presenters/branch.ts
 function renderBranchList(context, descriptor, result) {

package/dist/presenters/database.js

@@ -1,5 +1,5 @@
-import { formatColumns, renderSummaryLine } from "../shell/ui.js";
 import { formatDescriptorLabel } from "../shell/command-meta.js";
+import { formatColumns, renderSummaryLine } from "../shell/ui.js";
 import { renderMutate, renderShow, serializeList } from "../output/patterns.js";
 import { renderResolvedProjectContextBlock, stripVerboseContext } from "./verbose-context.js";
 //#region src/presenters/database.ts
@@ -234,7 +234,7 @@ function renderDatabaseConnectionRemove(context, descriptor, result) {
 	}, context.ui);
 }
 function serializeDatabaseConnectionRemove(result) {
-	return result;
+	return { connection: result.connection };
 }
 function formatStatus(database) {
 	return database.status ?? (database.isDefault ? "default" : "unknown");

package/dist/presenters/project.js

@@ -1,5 +1,5 @@
-import { padDisplay, renderNextSteps, renderSummaryLine, renderVerboseBlock } from "../shell/ui.js";
 import { formatDescriptorLabel } from "../shell/command-meta.js";
+import { padDisplay, renderNextSteps, renderSummaryLine, renderVerboseBlock } from "../shell/ui.js";
 import { formatCommandArgument } from "../shell/command-arguments.js";
 import { renderMutate, renderShow, serializeList } from "../output/patterns.js";
 import { renderResolvedProjectContextBlock } from "./verbose-context.js";

package/dist/shell/command-runner.js

@@ -1,8 +1,8 @@
 import { CliError, authRequiredError, commandCanceledError } from "./errors.js";
-import { cliErrorToJson, writeHumanError, writeHumanLines, writeJsonError, writeJsonEvent, writeJsonSuccess } from "./output.js";
 import { getCommandDescriptor } from "./command-meta.js";
 import { resolveGlobalFlags } from "./global-flags.js";
 import { createCommandContext } from "./runtime.js";
+import { cliErrorToJson, writeHumanError, writeHumanLines, writeJsonError, writeJsonEvent, writeJsonSuccess } from "./output.js";
 import { collectCommandDiagnostics } from "../lib/diagnostics.js";
 import { renderCommandDiagnostics } from "./diagnostics-output.js";
 import { AuthError } from "@prisma/management-api-sdk";
@@ -18,44 +18,54 @@ function isCancellationError(error) {
 	return error.name === "AbortError" || error.name === "CancelledError";
 }
 async function runCommand(runtime, commandName, options, handler, presenter) {
-	const flags = resolveGlobalFlags(runtime.argv, options);
-	const context = await createCommandContext(runtime, flags);
+	const context = await createCommandContext(runtime, resolveGlobalFlags(runtime.argv, options));
 	const descriptor = getCommandDescriptor(commandName);
 	const startedAt = Date.now();
 	try {
-		const success = await handler(context);
-		if (flags.json) {
-			writeJsonSuccess(context.output, {
-				...success,
-				result: presenter.renderJson ? presenter.renderJson(success.result) : success.result
-			});
-			return;
-		}
-		const stdout = presenter.renderStdout?.(context, descriptor, success.result) ?? [];
-		if (flags.quiet) {
-			if (stdout.length > 0) context.output.stdout.write(`${stdout.join("\n")}\n`);
-			return;
-		}
-		const rendered = presenter.renderHuman(context, descriptor, success.result);
-		const diagnostics = await renderBestEffortCommandDiagnostics(context, {
-			enabled: flags.verbose && rendered.length > 0,
-			durationMs: Date.now() - startedAt
-		});
-		const humanLines = [...rendered, ...diagnostics];
-		if (stdout.length > 0 && humanLines.length > 0) humanLines.push("");
-		writeHumanLines(context.output, humanLines);
-		if (stdout.length > 0) context.output.stdout.write(`${stdout.join("\n")}\n`);
+		await writeCommandSuccess(context, descriptor, await handler(context), presenter, Date.now() - startedAt);
 	} catch (error) {
 		const cliError = toCliError(error, runtime);
 		if (cliError) {
-			if (flags.json) writeJsonError(context.output, commandName, cliError);
-			else writeHumanError(context.output, context.ui, cliError, { trace: flags.trace });
+			writeCommandError(context, commandName, cliError);
 			process.exitCode = cliError.exitCode;
 			return;
 		}
 		throw error;
 	}
 }
+async function writeCommandSuccess(context, descriptor, success, presenter, durationMs) {
+	if (context.flags.json) {
+		writeJsonSuccess(context.output, {
+			...success,
+			result: presenter.renderJson ? presenter.renderJson(success.result) : success.result
+		});
+		return;
+	}
+	const stdout = presenter.renderStdout?.(context, descriptor, success.result) ?? [];
+	if (context.flags.quiet) {
+		writeStdoutLines(context, stdout);
+		return;
+	}
+	const rendered = presenter.renderHuman(context, descriptor, success.result);
+	const diagnostics = await renderBestEffortCommandDiagnostics(context, {
+		enabled: context.flags.verbose && rendered.length > 0,
+		durationMs
+	});
+	const humanLines = [...rendered, ...diagnostics];
+	if (stdout.length > 0 && humanLines.length > 0) humanLines.push("");
+	writeHumanLines(context.output, humanLines);
+	writeStdoutLines(context, stdout);
+}
+function writeCommandError(context, commandName, cliError) {
+	if (context.flags.json) {
+		writeJsonError(context.output, commandName, cliError);
+		return;
+	}
+	writeHumanError(context.output, context.ui, cliError, { trace: context.flags.trace });
+}
+function writeStdoutLines(context, lines) {
+	if (lines.length > 0) context.output.stdout.write(`${lines.join("\n")}\n`);
+}
 async function renderBestEffortCommandDiagnostics(context, options) {
 	if (!options.enabled) return [];
 	try {

package/dist/shell/help.js

@@ -1,6 +1,6 @@
-import { createShellUi, padDisplay, wrapText } from "./ui.js";
 import { formatDescriptorLabel, getDescriptorForCommand } from "./command-meta.js";
 import { COMPACT_GLOBAL_OPTION_FLAGS, resolveGlobalFlags } from "./global-flags.js";
+import { createShellUi, padDisplay, wrapText } from "./ui.js";
 //#region src/shell/help.ts
 function renderHelp(command, runtime) {
 	const descriptor = getDescriptorForCommand(command);
@@ -10,28 +10,38 @@ function renderHelp(command, runtime) {
 	const visibleCommands = command.commands.filter((candidate) => candidate.name() !== "help" && !candidate.hidden);
 	const visibleOptions = command.options.filter((candidate) => !candidate.hidden);
 	if (visibleCommands.length > 0) lines.push(...renderCommandRows(rail, ui, visibleCommands));
-	if (descriptor.longDescription) {
-		lines.push(`${rail}`);
-		const wrapped = wrapText(descriptor.longDescription, Math.max(ui.width - 3, 40));
-		for (const line of wrapped) lines.push(`${rail}  ${line}`);
-	}
-	if (visibleOptions.length > 0) {
-		if (visibleCommands.length > 0) lines.push(`${rail}`);
-		if (visibleCommands.length > 0 && visibleOptions.every((option) => COMPACT_GLOBAL_OPTION_FLAGS.includes(option.flags))) lines.push(`${rail}  Global options:`);
-		lines.push(...renderOptionRows(rail, ui, visibleOptions));
-	}
-	if (descriptor.examples && descriptor.examples.length > 0) {
-		lines.push(`${rail}`);
-		lines.push(`${rail}  Examples:`);
-		for (const example of descriptor.examples) lines.push(`${rail}    $ ${example}`);
-	}
-	if (descriptor.docsPath) {
-		lines.push(`${rail}`);
-		lines.push(`${rail}  ${ui.accent(padDisplay("Read more", 16))}  ${ui.link(descriptor.docsPath)}`);
-	}
+	lines.push(...renderLongDescription(rail, ui, descriptor.longDescription));
+	lines.push(...renderVisibleOptions(rail, ui, visibleCommands, visibleOptions));
+	lines.push(...renderExamples(rail, descriptor.examples));
+	lines.push(...renderDocsPath(rail, ui, descriptor.docsPath));
 	lines.push("");
 	return `${lines.join("\n")}`;
 }
+function renderLongDescription(rail, ui, longDescription) {
+	if (!longDescription) return [];
+	return [`${rail}`, ...wrapText(longDescription, Math.max(ui.width - 3, 40)).map((line) => `${rail}  ${line}`)];
+}
+function renderVisibleOptions(rail, ui, visibleCommands, visibleOptions) {
+	if (visibleOptions.length === 0) return [];
+	const lines = visibleCommands.length > 0 ? [`${rail}`] : [];
+	if (shouldLabelGlobalOptions(visibleCommands, visibleOptions)) lines.push(`${rail}  Global options:`);
+	return [...lines, ...renderOptionRows(rail, ui, visibleOptions)];
+}
+function shouldLabelGlobalOptions(visibleCommands, visibleOptions) {
+	return visibleCommands.length > 0 && visibleOptions.every((option) => COMPACT_GLOBAL_OPTION_FLAGS.includes(option.flags));
+}
+function renderExamples(rail, examples) {
+	if (!examples || examples.length === 0) return [];
+	return [
+		`${rail}`,
+		`${rail}  Examples:`,
+		...examples.map((example) => `${rail}    $ ${example}`)
+	];
+}
+function renderDocsPath(rail, ui, docsPath) {
+	if (!docsPath) return [];
+	return [`${rail}`, `${rail}  ${ui.accent(padDisplay("Read more", 16))}  ${ui.link(docsPath)}`];
+}
 function renderCommandRows(rail, ui, commands) {
 	return renderAlignedRows(rail, ui, commands.map((command) => {
 		const descriptor = getDescriptorForCommand(command);

package/dist/shell/runtime.js

@@ -1,6 +1,6 @@
-import { createShellUi } from "./ui.js";
 import { LocalStateStore } from "../adapters/local-state.js";
 import { MockApi } from "../adapters/mock-api.js";
+import { createShellUi } from "./ui.js";
 import { renderHelp } from "./help.js";
 import path from "node:path";
 //#region src/shell/runtime.ts