@prisma/cli 3.0.0-beta.0 → 3.0.0-beta.10

package/dist/lib/project/resolution.js

@@ -1,76 +1,100 @@
 import { CliError } from "../../shell/errors.js";
-import { canPrompt } from "../../shell/runtime.js";
+import { formatCommandArgument } from "../../shell/command-arguments.js";
+import { LOCAL_RESOLUTION_PIN_RELATIVE_PATH, readLocalResolutionPin } from "./local-pin.js";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { Result, TaggedError, matchError } from "better-result";
 //#region src/lib/project/resolution.ts
-async function resolveProjectTarget(options) {
-	const projects = await options.listProjects();
-	const inferredName = await inferTargetName(options.context.runtime.cwd);
-	if (options.explicitProject) return rememberIfRequested(options, resolveExplicitProject(options.explicitProject, projects, options.workspace), "explicit", {
-		targetName: options.explicitProject,
-		targetNameSource: "explicit"
-	});
-	const platformMapping = await resolveDurablePlatformMapping();
-	if (platformMapping) return rememberIfRequested(options, platformMapping, "platform-mapping");
-	let staleRemembered = false;
-	if (!options.allowCreate) {
-		const rememberedResult = await resolveRememberedProject(options, projects);
-		if (rememberedResult.target) return rememberedResult.target;
-		staleRemembered = rememberedResult.stale;
+var ProjectNotFoundError = class extends TaggedError("ProjectNotFoundError")() {
+	constructor(projectRef, workspace) {
+		super({
+			message: `Project "${projectRef}" was not found in workspace "${workspace.name}".`,
+			projectRef,
+			workspace
+		});
 	}
-	const packageName = inferredName.source === "package-name" ? inferredName.name : null;
-	if (packageName) {
-		const matches = projects.filter((project) => projectMatchesPackageName(project, packageName));
-		if (matches.length === 1) return rememberIfRequested(options, matches[0], "package-name", {
-			targetName: packageName,
-			targetNameSource: "package-name"
+};
+var ProjectAmbiguousError = class extends TaggedError("ProjectAmbiguousError")() {
+	constructor(projectRef, matches) {
+		super({
+			message: projectRef ? `Multiple projects matched "${projectRef}".` : "Multiple projects matched the current directory context.",
+			projectRef,
+			matches
 		});
-		if (matches.length > 1) return resolveAmbiguousProject(options, matches, packageName, "package-name");
 	}
-	if (options.allowCreate && options.createProject) {
-		if (inferredName.name) {
-			const existing = projects.filter((project) => projectMatchesPackageName(project, inferredName.name));
-			if (existing.length === 1) return rememberIfRequested(options, existing[0], inferredName.source, {
-				targetName: inferredName.name,
-				targetNameSource: inferredName.source
-			});
-			if (existing.length > 1) return resolveAmbiguousProject(options, existing, inferredName.name, inferredName.source);
-			return rememberIfRequested(options, await options.createProject(inferredName.name), "created", {
-				targetName: inferredName.name,
-				targetNameSource: inferredName.source
-			});
-		}
+};
+var LocalStateStaleError = class extends TaggedError("LocalStateStaleError")() {
+	constructor() {
+		super({
+			message: `The target recorded in ${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} is no longer available in the selected workspace.`,
+			pinPath: LOCAL_RESOLUTION_PIN_RELATIVE_PATH
+		});
 	}
-	if (options.prompt && canPrompt(options.context) && projects.length > 0) return rememberIfRequested(options, await options.prompt.select({
-		message: "Select a project",
-		choices: sortProjects(projects).map((project) => ({
-			label: `${project.name} (${project.id})`,
-			value: project
-		}))
-	}), "prompt");
-	if (staleRemembered && projects.length > 1) throw localStateStaleError();
-	throw projectUnresolvedError();
-}
-async function resolveRememberedProject(options, projects) {
-	const remembered = await options.context.stateStore.readRememberedProject(options.workspace.id);
-	if (!remembered) return {
-		target: null,
-		stale: false
-	};
-	const matched = projects.find((project) => project.id === remembered.id);
-	if (!matched) return {
-		target: null,
-		stale: true
-	};
-	return {
-		target: await rememberIfRequested(options, matched, "remembered-local", {
-			targetName: remembered.name,
-			targetNameSource: "remembered-local"
-		}),
-		stale: false
-	};
+};
+var LocalProjectWorkspaceMismatchError = class extends TaggedError("LocalProjectWorkspaceMismatchError")() {
+	constructor(options) {
+		super({
+			message: `${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} links this directory to project ${options.pinnedProjectId} in workspace ${options.pinnedWorkspaceId}, but the active workspace is "${options.activeWorkspace.name}" (${options.activeWorkspace.id}).`,
+			pinnedWorkspaceId: options.pinnedWorkspaceId,
+			pinnedProjectId: options.pinnedProjectId,
+			activeWorkspace: options.activeWorkspace
+		});
+	}
+};
+var ProjectSetupRequiredError = class extends TaggedError("ProjectSetupRequiredError")() {
+	constructor(options) {
+		const commandLabel = options.commandName ? `prisma-cli ${options.commandName}` : "this command";
+		super({
+			message: `This directory is not linked to a Prisma Project, and ${commandLabel} will not choose one from package or directory names.`,
+			commandName: options.commandName,
+			suggestion: options.suggestion
+		});
+	}
+};
+async function resolveProjectTarget(options) {
+	return Result.gen(async function* () {
+		const localPin = yield* Result.await(readImplicitLocalPin(options, { allowEnvProjectId: true }));
+		const projects = await options.listProjects();
+		const target = yield* Result.await(resolveBoundProjectTarget(options, projects, {
+			allowEnvProjectId: true,
+			localPin
+		}));
+		if (target) return Result.ok(target);
+		return Result.err(await projectSetupRequiredError({
+			cwd: options.context.runtime.cwd,
+			projects,
+			commandName: options.commandName,
+			signal: options.context.runtime.signal
+		}));
+	});
+}
+async function inspectProjectBinding(options) {
+	return Result.gen(async function* () {
+		const localPin = yield* Result.await(readImplicitLocalPin(options, { allowEnvProjectId: false }));
+		const projects = await options.listProjects();
+		const target = yield* Result.await(resolveBoundProjectTarget(options, projects, {
+			allowEnvProjectId: false,
+			localPin
+		}));
+		if (target) return Result.ok(target);
+		return Result.ok({
+			workspace: options.workspace,
+			project: null,
+			localBinding: { status: "not-linked" },
+			resolution: { projectSource: "unbound" },
+			...await buildProjectSetupSuggestion({
+				cwd: options.context.runtime.cwd,
+				projects,
+				commandName: options.commandName ?? "project show",
+				signal: options.context.runtime.signal
+			})
+		});
+	});
 }
 function projectNotFoundError(projectRef, workspace) {
+	return projectResolutionErrorToCliError(new ProjectNotFoundError(projectRef, workspace));
+}
+function projectNotFoundCliError(projectRef, workspace) {
 	return new CliError({
 		code: "PROJECT_NOT_FOUND",
 		domain: "project",
@@ -82,6 +106,9 @@ function projectNotFoundError(projectRef, workspace) {
 	});
 }
 function projectAmbiguousError(projectRef, matches) {
+	return projectResolutionErrorToCliError(new ProjectAmbiguousError(projectRef, matches));
+}
+function projectAmbiguousCliError(projectRef, matches) {
 	const firstMatch = matches[0];
 	const nextSteps = ["prisma-cli project list"];
 	if (firstMatch) nextSteps.push(`prisma-cli app deploy --project ${firstMatch.id}`);
@@ -99,31 +126,139 @@ function projectAmbiguousError(projectRef, matches) {
 		nextSteps
 	});
 }
-function projectUnresolvedError() {
+function localStateStaleCliError() {
 	return new CliError({
-		code: "PROJECT_UNRESOLVED",
+		code: "LOCAL_STATE_STALE",
 		domain: "project",
-		summary: "No project is resolved for this directory",
-		why: "No project could be resolved from explicit input, platform mappings, remembered local context, or package metadata.",
-		fix: "Pass --project <id-or-name> on the command that needs a project, or add a package.json name that matches an accessible 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}, then choose a Project explicitly.`,
+		meta: { pinPath: LOCAL_RESOLUTION_PIN_RELATIVE_PATH },
 		exitCode: 1,
-		nextSteps: ["prisma-cli project list", "prisma-cli project show --project <id-or-name>"]
+		nextSteps: ["prisma-cli project list", "prisma-cli project link <id-or-name>"]
 	});
 }
-function localStateStaleError() {
+function localProjectWorkspaceMismatchCliError(options) {
 	return new CliError({
-		code: "LOCAL_STATE_STALE",
+		code: "LOCAL_PROJECT_WORKSPACE_MISMATCH",
 		domain: "project",
-		summary: "Remembered project context is stale",
-		why: "The remembered project is no longer available in the selected workspace, and automatic resolution would be ambiguous.",
-		fix: "Pass --project <id-or-name> to choose the project explicitly.",
+		summary: "Project link uses another workspace",
+		why: `${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} links this directory to project ${options.pinnedProjectId} in workspace ${options.pinnedWorkspaceId}, but your current CLI session is workspace "${options.activeWorkspace.name}" (${options.activeWorkspace.id}).`,
+		fix: "Sign in to the linked workspace, or relink this directory to a project in the current workspace.",
+		meta: {
+			pinPath: LOCAL_RESOLUTION_PIN_RELATIVE_PATH,
+			pinnedWorkspaceId: options.pinnedWorkspaceId,
+			pinnedProjectId: options.pinnedProjectId,
+			activeWorkspaceId: options.activeWorkspace.id,
+			activeWorkspaceName: options.activeWorkspace.name
+		},
 		exitCode: 1,
-		nextSteps: ["prisma-cli project list"]
+		nextSteps: [
+			"prisma-cli auth login",
+			"prisma-cli project list",
+			"prisma-cli project link <id-or-name>"
+		]
+	});
+}
+/**
+* Converts expected project-resolution variants to command-boundary CliErrors.
+* `LocalResolutionPinReadAbortedError` and `UnhandledException` intentionally
+* propagate as exceptions; callers such as `resolveProjectShowInRealMode`
+* throw this helper's result, so passthrough variants should keep bubbling.
+*/
+function projectResolutionErrorToCliError(error) {
+	return matchError(error, {
+		ProjectNotFoundError: (error) => projectNotFoundCliError(error.projectRef, error.workspace),
+		ProjectAmbiguousError: (error) => projectAmbiguousCliError(error.projectRef, error.matches),
+		ProjectSetupRequiredError: (error) => projectSetupRequiredCliError(error),
+		LocalStateStaleError: () => localStateStaleCliError(),
+		LocalProjectWorkspaceMismatchError: (error) => localProjectWorkspaceMismatchCliError({
+			pinnedWorkspaceId: error.pinnedWorkspaceId,
+			pinnedProjectId: error.pinnedProjectId,
+			activeWorkspace: error.activeWorkspace
+		}),
+		LocalResolutionPinReadAbortedError: (error) => {
+			throw error;
+		},
+		UnhandledException: (error) => {
+			throw error;
+		}
+	});
+}
+async function buildProjectSetupSuggestion(options) {
+	const suggestedName = await inferTargetName(options.cwd, options.signal);
+	const candidates = sortProjects(options.projects.filter((project) => projectMatchesSuggestedName(project, suggestedName.name))).map(toProjectSummary);
+	return {
+		suggestedProjectName: suggestedName.name,
+		suggestedProjectNameSource: suggestedName.source,
+		candidates,
+		recoveryCommands: buildProjectRecoveryCommands(options.commandName)
+	};
+}
+async function projectSetupRequiredError(options) {
+	const suggestion = await buildProjectSetupSuggestion(options);
+	return new ProjectSetupRequiredError({
+		commandName: options.commandName,
+		suggestion
 	});
 }
-async function readPackageName(cwd) {
+function projectSetupRequiredCliError(error) {
+	const suggestion = error.suggestion;
+	return new CliError({
+		code: "PROJECT_SETUP_REQUIRED",
+		domain: "project",
+		summary: "Choose a Project before running this command",
+		why: error.message,
+		fix: "Link the directory to an existing Project, or pass --project <id-or-name> for this command.",
+		meta: { ...suggestion },
+		exitCode: 1,
+		nextSteps: ["prisma-cli project list", ...suggestion.recoveryCommands],
+		nextActions: buildProjectSetupNextActions({
+			commandName: error.commandName,
+			suggestedProjectName: suggestion.suggestedProjectName
+		})
+	});
+}
+function buildProjectSetupNextActions(options = {}) {
+	const recoveryCommands = buildProjectRecoveryCommands(options.commandName);
+	const linkCommand = recoveryCommands[0] ?? "prisma-cli project link <id-or-name>";
+	const retryCommand = recoveryCommands[1];
+	const actions = [{
+		kind: "user-choice",
+		journey: "project-setup",
+		label: "Ask the user whether to link an existing Project or create a new one",
+		commands: ["prisma-cli project list", ...recoveryCommands],
+		reason: options.reason ?? "This directory is not linked to a Prisma Project. Package and directory names are suggestions only, not a safe Project selection."
+	}, {
+		kind: "run-command",
+		journey: "project-setup",
+		label: "Link the chosen Project",
+		command: linkCommand,
+		reason: "Linking writes the durable local Project binding for this directory."
+	}];
+	const createCommand = options.createCommand ?? (options.suggestedProjectName ? `prisma-cli project create ${formatCommandArgument(options.suggestedProjectName)}` : void 0);
+	if (createCommand) actions.push({
+		kind: "run-command",
+		journey: "project-setup",
+		label: "Create and link a new Project",
+		command: createCommand,
+		reason: "Use this when the user wants a new Prisma Project instead of an existing one."
+	});
+	if (options.commandName) actions.push({
+		kind: "run-command",
+		journey: "recover",
+		label: "Retry with an explicit Project",
+		command: retryCommand ?? `prisma-cli ${options.commandName} --project <id-or-name>`
+	});
+	return actions;
+}
+async function readPackageName(cwd, signal) {
+	signal?.throwIfAborted();
 	try {
-		const raw = await readFile(path.join(cwd, "package.json"), "utf8");
+		const raw = await readFile(path.join(cwd, "package.json"), {
+			encoding: "utf8",
+			signal
+		});
 		const parsed = JSON.parse(raw);
 		if (!parsed || typeof parsed !== "object") return null;
 		const packageName = "name" in parsed ? parsed.name : null;
@@ -134,8 +269,8 @@ async function readPackageName(cwd) {
 		throw error;
 	}
 }
-async function inferTargetName(cwd) {
-	const packageName = await readPackageName(cwd);
+async function inferTargetName(cwd, signal) {
+	const packageName = await readPackageName(cwd, signal);
 	if (packageName && isValidInferredTargetName(packageName)) return {
 		name: packageName,
 		source: "package-name"
@@ -153,37 +288,78 @@ function sortProjects(projects) {
 }
 function resolveExplicitProject(projectRef, projects, workspace) {
 	const matches = projects.filter((project) => project.id === projectRef || project.name === projectRef);
-	if (matches.length === 1) return matches[0];
-	if (matches.length > 1) throw projectAmbiguousError(projectRef, matches);
-	throw projectNotFoundError(projectRef, workspace);
-}
-function resolveAmbiguousProject(options, matches, projectRef, targetNameSource) {
-	if (options.prompt && canPrompt(options.context)) return options.prompt.select({
-		message: "Select a project",
-		choices: sortProjects(matches).map((project) => ({
-			label: `${project.name} (${project.id})`,
-			value: project
-		}))
-	}).then((selected) => rememberIfRequested(options, selected, "prompt", {
-		targetName: projectRef,
-		targetNameSource
-	}));
-	throw projectAmbiguousError(projectRef, matches);
+	if (matches.length === 1) return Result.ok(matches[0]);
+	if (matches.length > 1) return Result.err(new ProjectAmbiguousError(projectRef, matches));
+	return Result.err(new ProjectNotFoundError(projectRef, workspace));
 }
-function projectMatchesPackageName(project, packageName) {
-	return project.id === packageName || project.name === packageName || project.slug === packageName;
+function projectMatchesSuggestedName(project, suggestedName) {
+	return project.id === suggestedName || project.name === suggestedName || project.slug === suggestedName;
 }
 async function resolveDurablePlatformMapping() {
 	return null;
 }
-async function rememberIfRequested(options, project, projectSource, resolutionDetails) {
-	if (options.remember) await options.context.stateStore.setRememberedProject({
-		id: project.id,
-		name: project.name,
-		workspaceId: options.workspace.id
+async function resolveBoundProjectTarget(options, projects, settings) {
+	if (options.explicitProject) {
+		const projectResult = resolveExplicitProject(options.explicitProject, projects, options.workspace);
+		if (projectResult.isErr()) return Result.err(projectResult.error);
+		return Result.ok(resolvedTarget(options.workspace, projectResult.value, "explicit", {
+			targetName: options.explicitProject,
+			targetNameSource: "explicit"
+		}));
+	}
+	if (settings.allowEnvProjectId && options.envProjectId) {
+		const project = projects.find((candidate) => candidate.id === options.envProjectId);
+		if (!project) return Result.err(new ProjectNotFoundError(options.envProjectId, options.workspace));
+		return Result.ok(resolvedTarget(options.workspace, project, "env", {
+			targetName: options.envProjectId,
+			targetNameSource: "env"
+		}));
+	}
+	const localPin = settings.localPin;
+	if (!localPin) return Result.ok(null);
+	if (localPin.kind === "present") {
+		if (localPin.pin.workspaceId !== options.workspace.id) return Result.err(new LocalProjectWorkspaceMismatchError({
+			pinnedWorkspaceId: localPin.pin.workspaceId,
+			pinnedProjectId: localPin.pin.projectId,
+			activeWorkspace: options.workspace
+		}));
+		const project = projects.find((candidate) => candidate.id === localPin.pin.projectId);
+		if (!project) return Result.err(new LocalStateStaleError());
+		return Result.ok(resolvedTarget(options.workspace, project, "local-pin", {
+			targetName: project.name,
+			targetNameSource: "local-pin"
+		}));
+	}
+	const platformMapping = await resolveDurablePlatformMapping();
+	if (platformMapping && platformMapping.workspace.id === options.workspace.id) return Result.ok(resolvedTarget(options.workspace, platformMapping, "platform-mapping", {
+		targetName: platformMapping.name,
+		targetNameSource: "platform-mapping"
+	}));
+	return Result.ok(null);
+}
+async function readImplicitLocalPin(options, settings) {
+	if (options.explicitProject || settings.allowEnvProjectId && options.envProjectId) return Result.ok(null);
+	const localPinResult = await readLocalResolutionPin(options.context.runtime.cwd, options.context.runtime.signal);
+	if (localPinResult.isErr()) return Result.err(localPinReadErrorToProjectError(localPinResult.error));
+	const localPin = localPinResult.value;
+	if (localPin.kind === "present" && localPin.pin.workspaceId !== options.workspace.id) return Result.err(new LocalProjectWorkspaceMismatchError({
+		pinnedWorkspaceId: localPin.pin.workspaceId,
+		pinnedProjectId: localPin.pin.projectId,
+		activeWorkspace: options.workspace
+	}));
+	return Result.ok(localPin);
+}
+function localPinReadErrorToProjectError(error) {
+	return matchError(error, {
+		LocalResolutionPinInvalidJsonError: () => new LocalStateStaleError(),
+		LocalResolutionPinInvalidShapeError: () => new LocalStateStaleError(),
+		LocalResolutionPinReadAbortedError: (error) => error,
+		UnhandledException: (error) => error
 	});
+}
+function resolvedTarget(workspace, project, projectSource, resolutionDetails) {
 	return {
-		workspace: options.workspace,
+		workspace,
 		project: toProjectSummary(project),
 		resolution: {
 			projectSource,
@@ -191,11 +367,17 @@ async function rememberIfRequested(options, project, projectSource, resolutionDe
 		}
 	};
 }
+function buildProjectRecoveryCommands(commandName) {
+	const commands = ["prisma-cli project link <id-or-name>"];
+	if (commandName) commands.push(`prisma-cli ${commandName} --project <id-or-name>`);
+	return commands;
+}
 function toProjectSummary(project) {
 	return {
 		id: project.id,
-		name: project.name
+		name: project.name,
+		...project.url ? { url: project.url } : {}
 	};
 }
 //#endregion
-export { inferTargetName, projectNotFoundError, resolveProjectTarget, sortProjects };
+export { buildProjectSetupNextActions, inferTargetName, inspectProjectBinding, projectAmbiguousError, projectNotFoundError, projectResolutionErrorToCliError, resolveDurablePlatformMapping, resolveProjectTarget, sortProjects };

package/dist/lib/project/setup.js

@@ -0,0 +1,132 @@
+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 { projectAmbiguousError, projectNotFoundError } from "./resolution.js";
+import { Result, matchError } from "better-result";
+//#region src/lib/project/setup.ts
+function isValidProjectSetupName(projectName) {
+	return projectName.trim().length > 0;
+}
+function validateProjectSetupNameText(value, fallback) {
+	if ((value?.trim() || fallback).trim().length > 0) return;
+	return "Enter a Project name.";
+}
+function resolveProjectForSetup(projectRef, projects, workspace) {
+	const matches = projects.filter((project) => project.id === projectRef || project.name === projectRef);
+	if (matches.length === 1) return matches[0];
+	if (matches.length > 1) throw projectAmbiguousError(projectRef, matches);
+	throw projectNotFoundError(projectRef, workspace);
+}
+async function bindProjectToDirectory(context, workspace, project, action) {
+	return Result.gen(async function* () {
+		yield* Result.await(writeLocalResolutionPin(context.runtime.cwd, {
+			workspaceId: workspace.id,
+			projectId: project.id
+		}, context.runtime.signal));
+		yield* Result.await(ensureLocalResolutionPinGitignore(context.runtime.cwd, context.runtime.signal));
+		return Result.ok({
+			workspace,
+			project,
+			directory: formatSetupDirectory(context.runtime.cwd),
+			localPin: {
+				path: LOCAL_RESOLUTION_PIN_RELATIVE_PATH,
+				written: true
+			},
+			action
+		});
+	});
+}
+function projectDirectoryBindingErrorToCliError(error) {
+	return matchError(error, {
+		LocalResolutionPinSerializationError: (error) => {
+			throw error;
+		},
+		LocalResolutionPinWriteAbortedError: (error) => {
+			throw error;
+		},
+		LocalResolutionPinWriteFailedError: (error) => localStateWriteFailedError(error, {
+			why: `The CLI could not write ${LOCAL_RESOLUTION_PIN_RELATIVE_PATH}.`,
+			meta: {
+				pinPath: error.pinPath,
+				operation: error.operation
+			}
+		}),
+		LocalResolutionPinGitignoreUpdateAbortedError: (error) => {
+			throw error;
+		},
+		LocalResolutionPinGitignoreUpdateFailedError: (error) => localStateWriteFailedError(error, {
+			why: "The CLI could not update .gitignore to keep local Project binding state out of git.",
+			meta: {
+				gitignorePath: error.gitignorePath,
+				operation: error.operation
+			}
+		})
+	});
+}
+function localStateWriteFailedError(error, options) {
+	return new CliError({
+		code: "LOCAL_STATE_WRITE_FAILED",
+		domain: "project",
+		summary: "Could not save local Project binding",
+		why: options.why,
+		fix: "Check that this directory is writable and that .prisma/local.json and .gitignore are not blocked by directories or permissions, then retry.",
+		debug: formatDebugDetails(error.cause),
+		meta: options.meta,
+		exitCode: 1,
+		nextSteps: ["prisma-cli project link <id-or-name>", "prisma-cli app deploy --project <id-or-name>"]
+	});
+}
+function toProjectSummary(project) {
+	return {
+		id: project.id,
+		name: project.name,
+		...project.url ? { url: project.url } : {}
+	};
+}
+function projectSetupNameRequiredError(command) {
+	return usageError("Project create requires a name", "The project name must be a non-empty value.", "Pass a Project name explicitly.", [`prisma-cli ${command} my-app`], "project");
+}
+function projectCreateFailedError(error, projectName, workspace, options) {
+	const status = extractHttpStatus(error);
+	if (status === 401 || status === 403) return new CliError({
+		code: "PROJECT_CREATE_FAILED",
+		domain: "project",
+		summary: `Could not create Project "${projectName}"`,
+		why: `The platform rejected the Project create in workspace "${workspace.name}" (HTTP ${status}).`,
+		fix: options.permissionFix,
+		debug: formatDebugDetails(error),
+		exitCode: 1,
+		nextSteps: options.nextSteps
+	});
+	return new CliError({
+		code: "PROJECT_CREATE_FAILED",
+		domain: "project",
+		summary: `Could not create Project "${projectName}"`,
+		why: error instanceof Error ? error.message : String(error),
+		fix: options.fallbackFix,
+		debug: formatDebugDetails(error),
+		exitCode: 1,
+		nextSteps: options.nextSteps
+	});
+}
+function formatSetupDirectory(cwd) {
+	const basename = cwd.split(/[\\/]/).filter(Boolean).pop();
+	return basename ? `./${basename}` : ".";
+}
+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 formatDebugDetails(error) {
+	if (error instanceof Error) return error.stack ?? error.message;
+	return typeof error === "string" ? error : null;
+}
+//#endregion
+export { bindProjectToDirectory, isValidProjectSetupName, projectCreateFailedError, projectDirectoryBindingErrorToCliError, projectSetupNameRequiredError, resolveProjectForSetup, toProjectSummary, validateProjectSetupNameText };