@bigcommerce/catalyst 1.0.0 → 1.1.0

package/dist/cli.js

@@ -1,24 +1,21 @@
 #!/usr/bin/env node
 
-// src/cli/lib/auth-errors.ts
-var UnauthorizedError = class extends Error {
-  constructor() {
-    super(
-      "Your access token is invalid or has expired.\nRun `catalyst auth login` to re-authenticate."
-    );
-    this.name = "UnauthorizedError";
+// src/cli/lib/errors.ts
+var UserActionableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UserActionableError";
   }
 };
-function assertAuthorized(response) {
-  if (response.status === 401) {
-    throw new UnauthorizedError();
-  }
-}
 
 // src/cli/lib/logger.ts
 import { createConsola } from "consola";
 var consola = createConsola({
-  level: "3" ? parseInt("3", 10) : 3
+  level: "3" ? parseInt("3", 10) : 3,
+  // Drop the per-line timestamp. It adds noise for a short-lived CLI and, on
+  // long lines, consola can't right-align it so it falls back to an inline
+  // `[time]` prefix that breaks copy-pasteable command suggestions.
+  formatOptions: { date: false }
 });
 
 // src/cli/lib/telemetry.ts
@@ -28,7 +25,7 @@ import { randomBytes, randomUUID } from "crypto";
 // package.json
 var package_default = {
   name: "@bigcommerce/catalyst",
-  version: "1.0.0",
+  version: "1.1.0",
   type: "module",
   repository: {
     type: "git",
@@ -69,6 +66,7 @@ var package_default = {
     "lodash.kebabcase": "^4.1.1",
     nypm: "^0.5.4",
     open: "^10.1.0",
+    semver: "^7.7.4",
     "std-env": "^3.9.0",
     tar: "^7.5.7",
     "yocto-spinner": "^1.0.0",
@@ -82,6 +80,7 @@ var package_default = {
     "@types/fs-extra": "^11.0.4",
     "@types/lodash.kebabcase": "^4.1.9",
     "@types/node": "^22.15.30",
+    "@types/semver": "^7.7.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     eslint: "^8.57.1",
@@ -201,26 +200,65 @@ function getTelemetry() {
 }
 
 // src/cli/program.ts
-import { Option as Option11 } from "@commander-js/extra-typings";
-import { Command as Command14 } from "commander";
-import { colorize as colorize11 } from "consola/utils";
-import { config } from "dotenv";
-import { existsSync as existsSync4 } from "fs";
-import { resolve } from "path";
+import { Command as Command15 } from "commander";
+import { colorize as colorize13 } from "consola/utils";
 
 // src/cli/commands/auth.ts
-import { Command, Option as Option2 } from "commander";
-import { z as z4 } from "zod";
+import { Command } from "commander";
+import { z as z5 } from "zod";
+
+// src/cli/lib/auth-errors.ts
+var UnauthorizedError = class extends UserActionableError {
+  constructor() {
+    super(
+      "Your access token is invalid or has expired.\nRun `catalyst auth login` to re-authenticate."
+    );
+    this.name = "UnauthorizedError";
+  }
+};
+function assertAuthorized(response) {
+  if (response.status === 401) {
+    throw new UnauthorizedError();
+  }
+}
 
 // src/cli/lib/login.ts
 import { confirm, input, password } from "@inquirer/prompts";
 import { colorize } from "consola/utils";
 import open from "open";
 import yoctoSpinner from "yocto-spinner";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/cli/lib/auth.ts
+import { z as z2 } from "zod";
+
+// src/cli/lib/http-errors.ts
 import { z } from "zod";
+var apiErrorBodySchema = z.object({
+  title: z.string().optional(),
+  detail: z.string().optional(),
+  errors: z.record(z.string(), z.string()).optional()
+});
+var FALLBACK_CLIENT_ERROR = "The request was rejected. Check your input \u2014 your access token may be missing a required scope, or the resource may not exist.";
+var FALLBACK_SERVER_ERROR = "Something went wrong on our end. Please try again. If the issue persists, contact support.";
+function extractApiErrorMessage(body) {
+  const parsed = apiErrorBodySchema.safeParse(body);
+  if (!parsed.success) return void 0;
+  const { title, detail, errors } = parsed.data;
+  const fieldErrors = errors && Object.keys(errors).length > 0 ? Object.entries(errors).map(([field, message]) => `${field}: ${message}`).join("; ") : void 0;
+  const headline = detail ?? title;
+  if (headline && fieldErrors) return `${headline} (${fieldErrors})`;
+  return headline ?? fieldErrors;
+}
+async function httpError(response, action) {
+  const body = await response.json().catch(() => null);
+  const isServerError = response.status >= 500;
+  const detail = extractApiErrorMessage(body) ?? (isServerError ? FALLBACK_SERVER_ERROR : FALLBACK_CLIENT_ERROR);
+  const message = `${action}: ${detail}`;
+  return isServerError ? new Error(message) : new UserActionableError(message);
+}
+
+// src/cli/lib/auth.ts
 var DEVICE_OAUTH_CLIENT_ID = "b8063bu6hhml4e0lqh22yut63atsbyv";
 var DEVICE_OAUTH_SCOPES = [
   "store_v2_information",
@@ -230,18 +268,18 @@ var DEVICE_OAUTH_SCOPES = [
   "store_channel_settings"
 ].join(" ");
 var DEFAULT_LOGIN_URL = "https://login.bigcommerce.com";
-var DeviceCodeResponseSchema = z.object({
-  device_code: z.string(),
-  user_code: z.string(),
-  verification_uri: z.string(),
-  expires_in: z.number(),
-  interval: z.number()
+var DeviceCodeResponseSchema = z2.object({
+  device_code: z2.string(),
+  user_code: z2.string(),
+  verification_uri: z2.string(),
+  expires_in: z2.number(),
+  interval: z2.number()
 });
-var DeviceCodeSuccessSchema = z.object({
-  access_token: z.string(),
-  store_hash: z.string(),
-  context: z.string(),
-  api_uri: z.string()
+var DeviceCodeSuccessSchema = z2.object({
+  access_token: z2.string(),
+  store_hash: z2.string(),
+  context: z2.string(),
+  api_uri: z2.string()
 });
 async function requestDeviceCode(loginUrl) {
   const response = await fetch(`${loginUrl}/device/token`, {
@@ -253,7 +291,7 @@ async function requestDeviceCode(loginUrl) {
     })
   });
   if (!response.ok) {
-    throw new Error(`Failed to request device code: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to request device code");
   }
   const res = await response.json();
   return DeviceCodeResponseSchema.parse(res);
@@ -284,6 +322,33 @@ async function waitForDeviceToken(loginUrl, deviceCode, interval) {
   return waitForDeviceToken(loginUrl, deviceCode, interval);
 }
 
+// src/cli/lib/clipboard.ts
+import { execa } from "execa";
+function clipboardCommand() {
+  switch (process.platform) {
+    case "darwin":
+      return { command: "pbcopy", args: [] };
+    case "win32":
+      return { command: "clip", args: [] };
+    case "linux":
+      return process.env.WAYLAND_DISPLAY ? { command: "wl-copy", args: [] } : { command: "xclip", args: ["-selection", "clipboard"] };
+    default:
+      return null;
+  }
+}
+async function copyToClipboard(text) {
+  const clipboard = clipboardCommand();
+  if (!clipboard) {
+    return false;
+  }
+  try {
+    await execa(clipboard.command, clipboard.args, { input: text });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/cli/lib/login.ts
 var LoginAbortedError = class extends Error {
   constructor() {
@@ -291,9 +356,9 @@ var LoginAbortedError = class extends Error {
     this.name = "LoginAbortedError";
   }
 };
-var StoreProfileSchema = z2.object({
-  data: z2.object({
-    store_name: z2.string()
+var StoreProfileSchema = z3.object({
+  data: z3.object({
+    store_name: z3.string()
   })
 });
 async function fetchStoreProfile(storeHash, accessToken, apiHost) {
@@ -319,6 +384,13 @@ async function deviceCodeLogin(loginUrl) {
   consola.info(
     `${colorize("yellow", "Your one-time code:")} ${colorize("bold", deviceCode.user_code)}`
   );
+  if (process.stdin.isTTY) {
+    await input({ message: "Press Enter to open your browser and sign in" });
+    const copied = await copyToClipboard(deviceCode.user_code);
+    if (copied) {
+      consola.info("Copied the code to your clipboard \u2014 paste it into the sign-in page.");
+    }
+  }
   try {
     await open(deviceCode.verification_uri);
     consola.info(`Opened ${deviceCode.verification_uri} in your browser.`);
@@ -346,12 +418,12 @@ Grant these OAuth scopes: ${DEVICE_OAUTH_SCOPES}`
   const storeHashInput = await input({ message: "Store hash:" });
   const storeHash = storeHashInput.trim();
   if (!storeHash) {
-    throw new Error("Store hash is required.");
+    throw new UserActionableError("Store hash is required.");
   }
   const accessTokenInput = await password({ message: "Access token:", mask: true });
   const accessToken = accessTokenInput.trim();
   if (!accessToken) {
-    throw new Error("Access token is required.");
+    throw new UserActionableError("Access token is required.");
   }
   const spinner = yoctoSpinner().start("Validating credentials...");
   try {
@@ -360,7 +432,7 @@ Grant these OAuth scopes: ${DEVICE_OAUTH_SCOPES}`
   } catch (error) {
     spinner.error("Failed to validate credentials.");
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(
+    throw new UserActionableError(
       `Could not validate credentials (${message}). Double-check your store hash and access token, then try again.`
     );
   }
@@ -384,19 +456,19 @@ async function login(loginUrl, apiHost) {
 }
 
 // src/cli/lib/project.ts
-import { z as z3 } from "zod";
-var InfrastructureProjectValidationError = class extends Error {
+import { z as z4 } from "zod";
+var InfrastructureProjectValidationError = class extends UserActionableError {
   constructor(message) {
     super(message);
     this.name = "InfrastructureProjectValidationError";
   }
 };
-var fetchProjectsSchema = z3.object({
-  data: z3.array(
-    z3.object({
-      uuid: z3.string(),
-      name: z3.string(),
-      deployment_hostnames: z3.array(z3.string())
+var fetchProjectsSchema = z4.object({
+  data: z4.array(
+    z4.object({
+      uuid: z4.string(),
+      name: z4.string(),
+      deployment_hostnames: z4.array(z4.string())
     })
   )
 });
@@ -417,9 +489,7 @@ async function hasProjectsAccess(storeHash, accessToken, apiHost) {
   assertAuthorized(response);
   if (response.status === 200) return true;
   if (response.status === 403) return false;
-  throw new Error(
-    `GET /v3/infrastructure/projects failed: ${response.status} ${response.statusText}`
-  );
+  throw await httpError(response, "Failed to check project access");
 }
 async function fetchProjects(storeHash, accessToken, apiHost) {
   const response = await fetch(projectsUrl(storeHash, apiHost), {
@@ -428,29 +498,29 @@ async function fetchProjects(storeHash, accessToken, apiHost) {
   });
   assertAuthorized(response);
   if (response.status === 403) {
-    throw new Error(
+    throw new UserActionableError(
       "Infrastructure Projects API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
   if (!response.ok) {
-    throw new Error(`Failed to fetch projects: ${response.statusText}`);
+    throw await httpError(response, "Failed to fetch projects");
   }
   const res = await response.json();
   const { data } = fetchProjectsSchema.parse(res);
   return data;
 }
-var createProjectSchema = z3.object({
-  data: z3.object({
-    uuid: z3.string(),
-    name: z3.string(),
-    date_created: z3.coerce.date(),
-    date_modified: z3.coerce.date()
+var createProjectSchema = z4.object({
+  data: z4.object({
+    uuid: z4.string(),
+    name: z4.string(),
+    date_created: z4.coerce.date(),
+    date_modified: z4.coerce.date()
   })
 });
-var validationErrorBodySchema = z3.object({
-  title: z3.string().optional(),
-  detail: z3.string().optional(),
-  errors: z3.record(z3.string(), z3.string()).optional()
+var validationErrorBodySchema = z4.object({
+  title: z4.string().optional(),
+  detail: z4.string().optional(),
+  errors: z4.record(z4.string(), z4.string()).optional()
 });
 function extractValidationMessage(body) {
   const parsed = validationErrorBodySchema.safeParse(body);
@@ -478,8 +548,8 @@ async function createProject(name, storeHash, accessToken, apiHost) {
     const message = extractValidationMessage(body) ?? fallback;
     throw new InfrastructureProjectValidationError(message);
   }
-  if (response.status === 403) {
-    throw new Error(
+  if (response.status === 403 || response.status === 404) {
+    throw new UserActionableError(
       "Infrastructure Projects API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
@@ -487,7 +557,7 @@ async function createProject(name, storeHash, accessToken, apiHost) {
     throw new Error("Failed to create project, is the name already in use?");
   }
   if (!response.ok) {
-    throw new Error(`Failed to create project: ${response.statusText}`);
+    throw await httpError(response, "Failed to create project");
   }
   const res = await response.json();
   const { data } = createProjectSchema.parse(res);
@@ -500,15 +570,15 @@ async function deleteProject(projectUuid, storeHash, accessToken, apiHost) {
   });
   assertAuthorized(response);
   if (response.status === 403) {
-    throw new Error(
+    throw new UserActionableError(
       "Infrastructure Projects API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
   if (response.status === 404) {
-    throw new Error(`Project ${projectUuid} not found.`);
+    throw new UserActionableError(`Project ${projectUuid} not found.`);
   }
   if (!response.ok) {
-    throw new Error(`Failed to delete project: ${response.statusText}`);
+    throw await httpError(response, "Failed to delete project");
   }
 }
 
@@ -529,6 +599,7 @@ function getProjectConfig() {
       },
       storeHash: { type: "string" },
       accessToken: { type: "string" },
+      apiHost: { type: "string" },
       env: {
         type: "object",
         additionalProperties: { type: "string" },
@@ -540,6 +611,7 @@ function getProjectConfig() {
 
 // src/cli/lib/shared-options.ts
 import { Option } from "commander";
+var DEFAULT_API_HOST = "api.bigcommerce.com";
 var storeHashOption = () => new Option(
   "--store-hash <hash>",
   "BigCommerce store hash. Can be found in the URL of your store Control Panel. Read from .bigcommerce/project.json or .env when not provided."
@@ -548,12 +620,19 @@ var accessTokenOption = () => new Option(
   "--access-token <token>",
   "BigCommerce access token. Can be found after creating a store-level API account. Read from .bigcommerce/project.json or .env when not provided."
 ).env("CATALYST_ACCESS_TOKEN");
-var apiHostOption = () => new Option("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com").hideHelp();
+var apiHostOption = () => new Option(
+  "--api-host <host>",
+  "BigCommerce API host. Read from .bigcommerce/project.json or CATALYST_API_HOST when not provided. Defaults to api.bigcommerce.com."
+).env("CATALYST_API_HOST").hideHelp();
 var loginUrlOption = () => new Option("--login-url <url>", "BigCommerce login URL.").env("BIGCOMMERCE_LOGIN_URL").default(DEFAULT_LOGIN_URL).hideHelp();
 var projectUuidOption = () => new Option(
   "--project-uuid <uuid>",
   "BigCommerce infrastructure project UUID. Read from .bigcommerce/project.json or .env when not provided."
 ).env("CATALYST_PROJECT_UUID");
+var envPathOption = () => new Option(
+  "--env-path <path>",
+  "Path to an environment file to load for the build (relative to the current working directory). When omitted, .env.local and .env are auto-loaded from the current directory. Other commands never load env files."
+);
 var resolveProjectUuid = (options) => {
   const config2 = getProjectConfig();
   const projectUuid = options.projectUuid ?? config2.get("projectUuid");
@@ -564,11 +643,12 @@ var resolveProjectUuid = (options) => {
   }
   return projectUuid;
 };
+var resolveApiHost = (options, config2) => options.apiHost ?? config2.get("apiHost") ?? DEFAULT_API_HOST;
 
 // src/cli/commands/auth.ts
-var StoreProfileSchema2 = z4.object({
-  data: z4.object({
-    store_name: z4.string()
+var StoreProfileSchema2 = z5.object({
+  data: z5.object({
+    store_name: z5.string()
   })
 });
 async function fetchStoreProfile2(storeHash, accessToken, apiHost) {
@@ -597,21 +677,10 @@ Example:
   $ catalyst auth whoami
 
   Logged in to My Store (abc123), connected to project my-project (43eba682-0c48-11f1-9bd5-827a48b0ce1e)`
-).addOption(
-  new Option2(
-    "--store-hash <hash>",
-    "BigCommerce store hash. Can be found in the URL of your store Control Panel."
-  ).env("CATALYST_STORE_HASH")
-).addOption(
-  new Option2(
-    "--access-token <token>",
-    "BigCommerce access token. Can be found after creating a store-level API account."
-  ).env("CATALYST_ACCESS_TOKEN")
-).addOption(
-  new Option2("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com").hideHelp()
-).action(async (options) => {
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).action(async (options) => {
   try {
     const config2 = getProjectConfig();
+    const apiHost = resolveApiHost(options, config2);
     const storeHash = options.storeHash ?? config2.get("storeHash");
     const accessToken = options.accessToken ?? config2.get("accessToken");
     if (!storeHash || !accessToken) {
@@ -622,10 +691,10 @@ Example:
       process.exit(1);
       return;
     }
-    const store = await fetchStoreProfile2(storeHash, accessToken, options.apiHost);
+    const store = await fetchStoreProfile2(storeHash, accessToken, apiHost);
     const projectUuid = config2.get("projectUuid");
     if (projectUuid) {
-      const projects = await fetchProjects(storeHash, accessToken, options.apiHost);
+      const projects = await fetchProjects(storeHash, accessToken, apiHost);
       const linkedProject = projects.find((p) => p.uuid === projectUuid);
       if (linkedProject) {
         consola.info(
@@ -665,21 +734,10 @@ Examples:
 
   # Login with existing credentials (skips interactive flow)
   $ catalyst auth login --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>`
-).addOption(
-  new Option2(
-    "--store-hash <hash>",
-    "BigCommerce store hash. Can be found in the URL of your store Control Panel."
-  ).env("CATALYST_STORE_HASH")
-).addOption(
-  new Option2(
-    "--access-token <token>",
-    "BigCommerce access token. Can be found after creating a store-level API account."
-  ).env("CATALYST_ACCESS_TOKEN")
-).addOption(
-  new Option2("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com").hideHelp()
-).addOption(loginUrlOption()).action(async (options) => {
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).action(async (options) => {
   try {
     const config2 = getProjectConfig();
+    const apiHost = resolveApiHost(options, config2);
     const storeHash = options.storeHash ?? config2.get("storeHash");
     const accessToken = options.accessToken ?? config2.get("accessToken");
     if (storeHash && accessToken) {
@@ -688,7 +746,7 @@ Examples:
       process.exit(0);
       return;
     }
-    const credentials = await login(options.loginUrl, options.apiHost);
+    const credentials = await login(options.loginUrl, apiHost);
     config2.set("storeHash", credentials.storeHash);
     config2.set("accessToken", credentials.accessToken);
     consola.success(`Logged in to store ${credentials.storeHash}.`);
@@ -734,10 +792,43 @@ Example:
 var auth = new Command("auth").configureHelp({ showGlobalOptions: true }).description("Manage authentication for the BigCommerce CLI.").addCommand(whoami).addCommand(login2).addCommand(logout);
 
 // src/cli/commands/build.ts
-import { Command as Command2, Option as Option3 } from "commander";
-import { execa } from "execa";
+import { Command as Command2, InvalidArgumentError, Option as Option2 } from "commander";
+import { execa as execa2 } from "execa";
 import { copyFile, cp, rm, writeFile } from "fs/promises";
 import { join as join4 } from "path";
+import { valid as validSemver } from "semver";
+
+// src/cli/lib/build-env.ts
+import { colorize as colorize2 } from "consola/utils";
+import { config } from "dotenv";
+import { existsSync } from "fs";
+import { resolve } from "path";
+var AUTO_ENV_FILES = [".env.local", ".env"];
+function loadBuildEnv({ envPath, cwd = process.cwd() }) {
+  if (envPath !== void 0) {
+    const envFilePath = resolve(cwd, envPath);
+    const result = config({ path: envFilePath, override: true });
+    if (result.error) {
+      const errCode = "code" in result.error && typeof result.error.code === "string" ? result.error.code : void 0;
+      const message = errCode === "ENOENT" ? `Env file not found: ${envFilePath}` : `Failed to load --env-path ${envPath}: ${result.error.message}`;
+      throw new UserActionableError(message);
+    }
+    consola.log(colorize2("cyanBright", `Loaded environment variables from ${envFilePath}
+`));
+    return;
+  }
+  const loaded = AUTO_ENV_FILES.filter((file) => {
+    const envFilePath = resolve(cwd, file);
+    if (!existsSync(envFilePath)) {
+      return false;
+    }
+    return !config({ path: envFilePath, override: false }).error;
+  });
+  if (loaded.length > 0) {
+    consola.log(colorize2("cyanBright", `Loaded environment variables from ${loaded.join(", ")}
+`));
+  }
+}
 
 // src/cli/lib/get-module-cli-path.ts
 import { dirname, join as join2 } from "path";
@@ -749,14 +840,14 @@ function getModuleCliPath() {
 }
 
 // src/cli/lib/project-state.ts
-import { existsSync, readFileSync } from "fs";
+import { existsSync as existsSync2, readFileSync } from "fs";
 import { join as join3 } from "path";
-import { z as z5 } from "zod";
-var projectJsonSchema = z5.looseObject({
-  projectUuid: z5.string().optional()
+import { z as z6 } from "zod";
+var projectJsonSchema = z6.looseObject({
+  projectUuid: z6.string().optional()
 });
-var packageJsonSchema = z5.looseObject({
-  dependencies: z5.record(z5.string(), z5.string()).optional()
+var packageJsonSchema = z6.looseObject({
+  dependencies: z6.record(z6.string(), z6.string()).optional()
 });
 var safeReadJson = (path) => {
   try {
@@ -770,8 +861,8 @@ function getProjectState(cwd = process.cwd()) {
     safeReadJson(join3(cwd, ".bigcommerce", "project.json"))
   );
   const projectUuid = projectJson.success ? projectJson.data.projectUuid : void 0;
-  const hasMiddleware = existsSync(join3(cwd, "middleware.ts"));
-  const hasProxy = existsSync(join3(cwd, "proxy.ts"));
+  const hasMiddleware = existsSync2(join3(cwd, "middleware.ts"));
+  const hasProxy = existsSync2(join3(cwd, "proxy.ts"));
   const pkgJson = packageJsonSchema.safeParse(safeReadJson(join3(cwd, "package.json")));
   const hasOpenNextDep = pkgJson.success ? Boolean(pkgJson.data.dependencies?.["@opennextjs/cloudflare"]) : false;
   const isLinked = Boolean(projectUuid);
@@ -788,6 +879,34 @@ function getProjectState(cwd = process.cwd()) {
   };
 }
 
+// src/cli/lib/required-build-env.ts
+var REQUIRED_BUILD_ENV_VARS = [
+  "BIGCOMMERCE_STORE_HASH",
+  "BIGCOMMERCE_STOREFRONT_TOKEN",
+  "BIGCOMMERCE_CHANNEL_ID",
+  "AUTH_SECRET"
+];
+var findMissingBuildEnv = (env2 = process.env) => {
+  return REQUIRED_BUILD_ENV_VARS.filter((name) => {
+    const value = env2[name];
+    return value === void 0 || value.trim() === "";
+  });
+};
+var assertRequiredBuildEnv = (env2 = process.env) => {
+  const missing = findMissingBuildEnv(env2);
+  if (missing.length === 0) {
+    return;
+  }
+  const missingList = missing.map((name) => `  - ${name}`).join("\n");
+  throw new UserActionableError(
+    `Missing required environment variable${missing.length === 1 ? "" : "s"} for the build:
+${missingList}
+
+These are read by the build itself, so they must be set before it runs. The build automatically loads \`.env.local\` and \`.env\` from the current directory (${process.cwd()}) \u2014 add the variables above to one of those files (\`.env.local\` takes precedence).
+To load an env file from a different location, pass \`--env-path <path>\` (for example \`--env-path ../.env.local\` when running from a subdirectory).`
+  );
+};
+
 // src/cli/lib/wrangler-config.ts
 function getCompatibilityDate(now = /* @__PURE__ */ new Date()) {
   const date = new Date(now);
@@ -853,7 +972,17 @@ function getWranglerConfig(projectUuid) {
 
 // src/cli/commands/build.ts
 var WRANGLER_VERSION = "4.90.0";
-async function buildCatalystProject(projectUuid) {
+var DIST_TAG_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+var parseWranglerVersion = (value) => {
+  if (!validSemver(value) && !DIST_TAG_PATTERN.test(value)) {
+    throw new InvalidArgumentError(
+      `"${value}" is not a valid Wrangler version or dist-tag (e.g. 4.90.0 or latest).`
+    );
+  }
+  return value;
+};
+async function buildCatalystProject(projectUuid, wranglerVersion = WRANGLER_VERSION) {
+  assertRequiredBuildEnv();
   const coreDir = process.cwd();
   const openNextOutDir = join4(coreDir, ".open-next");
   const bigcommerceDistDir = join4(coreDir, ".bigcommerce", "dist");
@@ -870,7 +999,7 @@ async function buildCatalystProject(projectUuid) {
   );
   consola.success("Templates copied");
   consola.start("Building project...");
-  await execa(
+  await execa2(
     "pnpm",
     [
       "exec",
@@ -885,11 +1014,11 @@ async function buildCatalystProject(projectUuid) {
       cwd: coreDir
     }
   );
-  await execa(
+  await execa2(
     "pnpm",
     [
       "dlx",
-      `wrangler@${WRANGLER_VERSION}`,
+      `wrangler@${wranglerVersion}`,
       "deploy",
       "--config",
       join4(coreDir, ".bigcommerce", "wrangler.jsonc"),
@@ -918,18 +1047,28 @@ Examples:
   $ catalyst build
 
   # Include project UUID
-  $ catalyst build --project-uuid <UUID>`
+  $ catalyst build --project-uuid <UUID>
+
+  # Build with a specific Wrangler version
+  $ catalyst build --wrangler-version 4.24.3`
 ).addOption(
-  new Option3(
+  new Option2(
     "--project-uuid <uuid>",
     "Project UUID to be included in the deployment configuration."
   ).env("CATALYST_PROJECT_UUID")
-).action(async (options) => {
+).addOption(
+  new Option2(
+    "--wrangler-version <version>",
+    `Wrangler version or dist-tag to build with. Defaults to ${WRANGLER_VERSION}.`
+  ).argParser(parseWranglerVersion)
+).addOption(envPathOption()).action(async (options) => {
+  loadBuildEnv({ envPath: options.envPath });
   const state = getProjectState();
   if (!state.isTransformed) {
     consola.info("Project is not set up for Commerce Hosting \u2014 running `next build`.");
     consola.info("To deploy to Commerce Hosting, run `catalyst deploy`.");
-    await execa("pnpm", ["exec", "next", "build"], {
+    assertRequiredBuildEnv();
+    await execa2("pnpm", ["exec", "next", "build"], {
       stdio: "inherit",
       cwd: process.cwd()
     });
@@ -942,21 +1081,19 @@ Examples:
       "Project UUID is required. Please run `catalyst project create` or `catalyst project link` or this command again with --project-uuid <uuid>."
     );
   }
-  await buildCatalystProject(projectUuid);
+  await buildCatalystProject(projectUuid, options.wranglerVersion);
 });
 
 // src/cli/commands/channel.ts
-import { select as select3 } from "@inquirer/prompts";
-import { Command as Command3, InvalidArgumentError, Option as Option4 } from "commander";
-import { colorize as colorize3 } from "consola/utils";
-import { outputFileSync } from "fs-extra/esm";
-import { join as join6 } from "path";
+import { select as select4 } from "@inquirer/prompts";
+import { Command as Command3, InvalidArgumentError as InvalidArgumentError2, Option as Option3 } from "commander";
+import { colorize as colorize5 } from "consola/utils";
 
 // src/cli/lib/channel-site-flow.ts
 import { select as select2 } from "@inquirer/prompts";
 
 // src/cli/lib/channels.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var cliApiUrl = (origin, storeHash, path) => `${origin}/stores/${storeHash}/cli-api/v3${path}`;
 var channelsUrl = (storeHash, apiHost, query2 = {}) => {
   const params = new URLSearchParams(query2).toString();
@@ -967,14 +1104,14 @@ var authHeaders2 = (accessToken) => ({
   "X-Correlation-Id": getTelemetry().correlationId,
   Accept: "application/json"
 });
-var envVarsSchema = z6.record(z6.string(), z6.coerce.string());
-var channelSchema = z6.object({
-  id: z6.number(),
-  name: z6.string(),
-  platform: z6.string()
+var envVarsSchema = z7.record(z7.string(), z7.coerce.string());
+var channelSchema = z7.object({
+  id: z7.number(),
+  name: z7.string(),
+  platform: z7.string()
 });
-var channelsResponseSchema = z6.object({
-  data: z6.array(channelSchema)
+var channelsResponseSchema = z7.object({
+  data: z7.array(channelSchema)
 });
 var CHANNEL_PLATFORM_ORDER = ["catalyst", "next", "bigcommerce"];
 function sortChannelsByPlatform(channels) {
@@ -990,30 +1127,30 @@ function sortChannelsByPlatform(channels) {
 function channelPlatformLabel(platform) {
   return platform === "bigcommerce" ? "Stencil" : platform.charAt(0).toUpperCase() + platform.slice(1);
 }
-var initResponseSchema = z6.object({
-  data: z6.object({
-    storefront_api_token: z6.string(),
+var initResponseSchema = z7.object({
+  data: z7.object({
+    storefront_api_token: z7.string(),
     envVars: envVarsSchema
   })
 });
-var createChannelResponseSchema = z6.object({
-  data: z6.object({
-    id: z6.number(),
-    storefront_api_token: z6.string(),
+var createChannelResponseSchema = z7.object({
+  data: z7.object({
+    id: z7.number(),
+    storefront_api_token: z7.string(),
     envVars: envVarsSchema
   })
 });
-var eligibilityResponseSchema = z6.object({
-  data: z6.object({
-    eligible: z6.boolean(),
-    message: z6.string()
+var eligibilityResponseSchema = z7.object({
+  data: z7.object({
+    eligible: z7.boolean(),
+    message: z7.string()
   })
 });
-var channelSiteSchema = z6.object({
-  data: z6.object({
-    id: z6.number(),
-    url: z6.string(),
-    channel_id: z6.number()
+var channelSiteSchema = z7.object({
+  data: z7.object({
+    id: z7.number(),
+    url: z7.string(),
+    channel_id: z7.number()
   })
 });
 async function getChannelInit(channelId, storeHash, accessToken, origin) {
@@ -1022,9 +1159,7 @@ async function getChannelInit(channelId, storeHash, accessToken, origin) {
     headers: authHeaders2(accessToken)
   });
   if (!response.ok) {
-    throw new Error(
-      `GET /channels/${channelId}/init failed: ${response.status} ${response.statusText}`
-    );
+    throw await httpError(response, "Failed to initialize channel");
   }
   const { data } = initResponseSchema.parse(await response.json());
   return { storefrontToken: data.storefront_api_token, envVars: data.envVars };
@@ -1035,9 +1170,7 @@ async function checkChannelEligibility(storeHash, accessToken, origin) {
     headers: authHeaders2(accessToken)
   });
   if (!response.ok) {
-    throw new Error(
-      `GET /channels/catalyst/eligibility failed: ${response.status} ${response.statusText}`
-    );
+    throw await httpError(response, "Failed to check Catalyst eligibility");
   }
   return eligibilityResponseSchema.parse(await response.json()).data;
 }
@@ -1055,7 +1188,7 @@ async function createChannel(name, storefrontLocale, additionalLocales, installS
     })
   });
   if (!response.ok) {
-    throw new Error(`POST /channels/catalyst failed: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to create channel");
   }
   const { data } = createChannelResponseSchema.parse(await response.json());
   return {
@@ -1078,7 +1211,7 @@ async function fetchAvailableChannels(storeHash, accessToken, apiHost) {
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`GET /v3/channels failed: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to fetch channels");
   }
   return channelsResponseSchema.parse(await response.json()).data;
 }
@@ -1097,12 +1230,12 @@ async function updateChannelSiteUrl(channelId, siteUrl, storeHash, accessToken,
     }
   );
   if (response.status === 401 || response.status === 403) {
-    throw new Error(
+    throw new UserActionableError(
       `Failed to update channel site (${response.status}). Re-run \`catalyst auth login\` to refresh your access token with the store_channel_settings scope.`
     );
   }
   if (!response.ok) {
-    throw new Error(`Failed to update channel site: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to update channel site");
   }
   const res = await response.json();
   const { data } = channelSiteSchema.parse(res);
@@ -1111,10 +1244,10 @@ async function updateChannelSiteUrl(channelId, siteUrl, storeHash, accessToken,
 
 // src/cli/lib/commerce-hosting.ts
 import { confirm as confirm2, input as input2, select, Separator } from "@inquirer/prompts";
-import { colorize as colorize2 } from "consola/utils";
-import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, unlinkSync, writeFileSync } from "fs";
+import { colorize as colorize3 } from "consola/utils";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync2, unlinkSync, writeFileSync } from "fs";
 import { dirname as dirname2, join as join5 } from "path";
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // src/cli/lib/sort-package-json.ts
 var FIELD_ORDER = [
@@ -1144,8 +1277,8 @@ function sortPackageJsonFields(pkg) {
 
 // src/cli/lib/commerce-hosting.ts
 var OPENNEXT_CLOUDFLARE_VERSION = "1.17.3";
-var corePackageJsonSchema = z7.looseObject({
-  dependencies: z7.record(z7.string(), z7.string()).optional()
+var corePackageJsonSchema = z8.looseObject({
+  dependencies: z8.record(z8.string(), z8.string()).optional()
 });
 var writeJson = (path, value) => {
   mkdirSync(dirname2(path), { recursive: true });
@@ -1155,14 +1288,14 @@ var writeJson = (path, value) => {
 var convertProxyToMiddleware = (projectDir) => {
   const proxyPath = join5(projectDir, "proxy.ts");
   const middlewarePath = join5(projectDir, "middleware.ts");
-  if (!existsSync2(proxyPath)) return;
+  if (!existsSync3(proxyPath)) return;
   const contents = readFileSync2(proxyPath, "utf-8").replace("export const proxy", "export const middleware").replace("export const config = {", "export const config = {\n  runtime: 'experimental-edge',");
   writeFileSync(middlewarePath, contents);
   unlinkSync(proxyPath);
 };
 var cleanupCloudflareIncompatibilities = async (projectDir) => {
   const instrumentationPath = join5(projectDir, "instrumentation.ts");
-  if (!existsSync2(instrumentationPath)) return;
+  if (!existsSync3(instrumentationPath)) return;
   if (!process.stdin.isTTY) {
     consola.warn(
       "instrumentation.ts is present and may be incompatible with the Cloudflare Workers bundle (the default @vercel/otel scaffolding throws at cold start under workerd). Skipping automatic cleanup in non-interactive mode \u2014 re-run interactively to remove it, or delete/gate it manually."
@@ -1182,7 +1315,7 @@ var cleanupCloudflareIncompatibilities = async (projectDir) => {
   unlinkSync(instrumentationPath);
   consola.info("Removed instrumentation.ts (incompatible with Cloudflare Workers).");
   const corePackageJsonPath = join5(projectDir, "package.json");
-  if (existsSync2(corePackageJsonPath)) {
+  if (existsSync3(corePackageJsonPath)) {
     const pkg = corePackageJsonSchema.parse(JSON.parse(readFileSync2(corePackageJsonPath, "utf-8")));
     if (pkg.dependencies && "@vercel/otel" in pkg.dependencies) {
       const { "@vercel/otel": _removedVercelOtel, ...preservedDeps } = pkg.dependencies;
@@ -1243,7 +1376,7 @@ async function selectOrCreateInfrastructureProject(api, linkedProjectUuid) {
   }
   const choices = [
     ...existingProjects.map((p) => ({
-      name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize2("green", "[linked]")}` : p.name,
+      name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize3("green", "[linked]")}` : p.name,
       value: p.uuid,
       description: p.uuid
     })),
@@ -1340,7 +1473,7 @@ async function promptAndCreateCommerceHostingProject(api, takenNames, defaultNam
     },
     theme: {
       style: {
-        help: () => colorize2(
+        help: () => colorize3(
           "dim",
           "(The project that hosts your storefront on Commerce \u2014 often matches your folder name.)"
         )
@@ -1486,17 +1619,149 @@ async function runChannelSiteUrlFlow(options) {
   consola.success(`Updated channel ${channelLabel} site URL to ${siteUrl}.`);
 }
 
+// src/cli/lib/create-channel-flow.ts
+import { checkbox, input as input3, select as select3 } from "@inquirer/prompts";
+import { colorize as colorize4 } from "consola/utils";
+
+// src/cli/lib/localization.ts
+import { z as z9 } from "zod";
+var allowedLocales = [
+  "en",
+  "da",
+  "es-AR",
+  "es-CL",
+  "es-CO",
+  "es-MX",
+  "es-PE",
+  "es-419",
+  "es",
+  "it",
+  "nl",
+  "pl",
+  "pt",
+  "de",
+  "fr",
+  "ja",
+  "no",
+  "pt-BR",
+  "sv"
+];
+var AvailableLocalesSuccessSchema = z9.object({
+  data: z9.array(
+    z9.object({
+      id: z9.string(),
+      name: z9.string(),
+      fallback: z9.string().nullable(),
+      is_supported: z9.boolean()
+    })
+  )
+});
+var getAvailableLocales = async (storeHash, accessToken, apiHost) => {
+  const response = await fetch(
+    `https://${apiHost}/stores/${storeHash}/v3/settings/store/available-locales`,
+    {
+      method: "GET",
+      headers: {
+        "X-Auth-Token": accessToken,
+        "X-Correlation-Id": getTelemetry().correlationId,
+        Accept: "application/json"
+      }
+    }
+  );
+  assertAuthorized(response);
+  if (!response.ok) {
+    throw await httpError(response, "Failed to fetch available locales");
+  }
+  return AvailableLocalesSuccessSchema.parse(await response.json()).data.filter(({ id }) => allowedLocales.includes(id)).map(({ name, id }) => ({ name: `${name} (${id})`, value: id }));
+};
+
+// src/cli/lib/create-channel-flow.ts
+var ALLOWED_CHANNEL_NAME_CHARS = "letters, numbers, spaces, hyphens (-), and underscores (_)";
+var CHANNEL_NAME_PATTERN = /^[\p{L}\p{N} _-]+$/u;
+function getChannelNameError(name) {
+  if (name.trim().length === 0) {
+    return "Channel name cannot be empty.";
+  }
+  if (!CHANNEL_NAME_PATTERN.test(name)) {
+    return `"${name}" is not a valid channel name. Channel names may contain only ${ALLOWED_CHANNEL_NAME_CHARS}.`;
+  }
+  return void 0;
+}
+async function runCreateChannelFlow(options) {
+  const { storeHash, accessToken, apiHost, cliApiOrigin } = options;
+  if (options.name !== void 0) {
+    const nameError = getChannelNameError(options.name);
+    if (nameError) {
+      throw new UserActionableError(nameError);
+    }
+  }
+  const name = options.name ?? await input3({
+    message: "What would you like to name your new channel?",
+    validate: (value) => getChannelNameError(value) ?? true
+  });
+  let availableLocales;
+  const loadLocales = async () => {
+    availableLocales ?? (availableLocales = await getAvailableLocales(storeHash, accessToken, apiHost));
+    return availableLocales;
+  };
+  const storefrontLocale = options.locale ?? await select3({
+    message: "Which default language would you like to set for your channel?",
+    default: "en",
+    choices: await loadLocales(),
+    theme: {
+      style: {
+        help: () => colorize4("dim", "(Select locale from the list or start typing the name)")
+      }
+    }
+  });
+  let additionalLocales = options.additionalLocales;
+  if (additionalLocales === void 0) {
+    const shouldAddAdditionalLocales = await select3({
+      message: "Would you like to add additional languages?",
+      choices: [
+        { name: "Yes", value: true },
+        { name: "No", value: false }
+      ]
+    });
+    additionalLocales = [];
+    if (shouldAddAdditionalLocales) {
+      const localeChoices = (await loadLocales()).filter(({ value }) => value !== storefrontLocale).map(({ name: localeName, value }) => ({ name: localeName, value, description: value }));
+      additionalLocales = await checkbox({
+        message: "Which additional languages would you like to add to your channel?",
+        choices: localeChoices,
+        validate: (items) => items.length <= 4 || "You can only select up to 4 additional languages."
+      });
+    }
+  }
+  const shouldInstallSampleData = options.sampleData ?? await select3({
+    message: "Would you like to install sample data?",
+    choices: [
+      { name: "Yes", value: true },
+      { name: "No", value: false }
+    ]
+  });
+  return createChannel(
+    name,
+    storefrontLocale,
+    additionalLocales,
+    shouldInstallSampleData,
+    storeHash,
+    accessToken,
+    cliApiOrigin
+  );
+}
+
 // src/cli/lib/env-config.ts
 var ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-var parseEnvAssignment = (input5) => {
-  const separatorIndex = input5.indexOf("=");
+var parseEnvAssignment = (input6) => {
+  const separatorIndex = input6.indexOf("=");
   if (separatorIndex === -1) {
-    throw new Error(`Invalid env var format: ${input5}. Expected format: KEY=VALUE`);
+    throw new Error(`Invalid env var format: ${input6}. Expected format: KEY=VALUE`);
   }
-  const key = input5.slice(0, separatorIndex).trim();
-  const value = input5.slice(separatorIndex + 1).trim();
+  const key = input6.slice(0, separatorIndex).trim();
+  const value = input6.slice(separatorIndex + 1).trim();
   if (!key || !value) {
-    throw new Error(`Invalid env var format: ${input5}. Expected format: KEY=VALUE`);
+    throw new Error(`Invalid env var format: ${input6}. Expected format: KEY=VALUE`);
   }
   if (!ENV_KEY_PATTERN.test(key)) {
     throw new Error(
@@ -1533,22 +1798,89 @@ function resolveCredentials(options, config2) {
   return { storeHash, accessToken };
 }
 
+// src/cli/lib/write-env.ts
+import { outputFileSync } from "fs-extra/esm";
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
+import { join as join6 } from "path";
+var ACTIVE_KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+var keyFromLine = (line) => {
+  const match = ACTIVE_KEY_LINE.exec(line);
+  return match ? match[1] : null;
+};
+var parseEnvValues = (contents) => {
+  const values = /* @__PURE__ */ new Map();
+  contents.split("\n").forEach((line) => {
+    const match = ACTIVE_KEY_LINE.exec(line);
+    if (match) {
+      values.set(match[1], match[2]);
+    }
+  });
+  return values;
+};
+var writeEnv = (projectDir, envVars) => {
+  const examplePath = join6(projectDir, ".env.example");
+  const localPath = join6(projectDir, ".env.local");
+  const existingLocal = existsSync4(localPath) ? parseEnvValues(readFileSync3(localPath, "utf-8")) : /* @__PURE__ */ new Map();
+  const resolve2 = (key) => {
+    if (key in envVars && envVars[key] !== "") {
+      return envVars[key];
+    }
+    return existingLocal.get(key);
+  };
+  if (!existsSync4(examplePath)) {
+    const keys = [.../* @__PURE__ */ new Set([...existingLocal.keys(), ...Object.keys(envVars)])];
+    outputFileSync(localPath, `${keys.map((key) => `${key}=${resolve2(key) ?? ""}`).join("\n")}
+`);
+    return;
+  }
+  const exampleLines = readFileSync3(examplePath, "utf-8").replace(/\n$/, "").split("\n");
+  const exampleKeys = /* @__PURE__ */ new Set();
+  const lines = exampleLines.map((line) => {
+    const key = keyFromLine(line);
+    if (key === null) {
+      return line;
+    }
+    exampleKeys.add(key);
+    const value = resolve2(key);
+    return value === void 0 ? line : `${key}=${value}`;
+  });
+  const extraKeys = [];
+  [...existingLocal.keys()].forEach((key) => {
+    if (!exampleKeys.has(key)) {
+      extraKeys.push(key);
+    }
+  });
+  Object.keys(envVars).forEach((key) => {
+    if (!exampleKeys.has(key) && !extraKeys.includes(key)) {
+      extraKeys.push(key);
+    }
+  });
+  if (extraKeys.length > 0) {
+    lines.push("", "# Additional variables set by the Catalyst CLI (not in .env.example).");
+    extraKeys.forEach((key) => {
+      lines.push(`${key}=${resolve2(key) ?? ""}`);
+    });
+  }
+  outputFileSync(localPath, `${lines.join("\n")}
+`);
+};
+
 // src/cli/commands/channel.ts
 var parseChannelId = (value) => {
   const parsed = Number.parseInt(value, 10);
   if (Number.isNaN(parsed)) {
-    throw new InvalidArgumentError(`"${value}" is not a valid channel ID (expected a number).`);
+    throw new InvalidArgumentError2(`"${value}" is not a valid channel ID (expected a number).`);
   }
   return parsed;
 };
-async function resolveCredentialsWithLogin(options, config2) {
+async function resolveCredentialsWithLogin(options, config2, apiHost) {
   const storeHash = options.storeHash ?? config2.get("storeHash");
   const accessToken = options.accessToken ?? config2.get("accessToken");
   if (storeHash && accessToken) {
     return { storeHash, accessToken };
   }
   try {
-    const credentials = await login(options.loginUrl, options.apiHost);
+    const credentials = await login(options.loginUrl, apiHost);
     config2.set("storeHash", credentials.storeHash);
     config2.set("accessToken", credentials.accessToken);
     return credentials;
@@ -1571,24 +1903,25 @@ Examples:
   # Skip both prompts
   $ catalyst channel update --channel-id 123 --hostname my-storefront.example.com`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).addOption(
-  new Option4(
+  new Option3(
     "--channel-id <id>",
     "Skip the channel prompt and target this channel directly."
   ).argParser((value) => Number(value))
 ).addOption(
-  new Option4(
+  new Option3(
     "--hostname <hostname>",
     "Skip the hostname prompt and use this hostname directly. Must be one of the project's deployment_hostnames."
   )
 ).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
   try {
     await runChannelSiteUrlFlow({
       storeHash,
       accessToken,
-      apiHost: options.apiHost,
+      apiHost,
       projectUuid: options.projectUuid ?? config2.get("projectUuid"),
       channelId: options.channelId,
       hostname: options.hostname
@@ -1620,17 +1953,18 @@ Examples:
   # Append extra environment variables to .env.local
   $ catalyst channel link --channel-id 123 --env MY_FLAG=1`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).addOption(
-  new Option4("--channel-id <id>", "Link this channel directly, skipping the picker.").argParser(
+  new Option3("--channel-id <id>", "Link this channel directly, skipping the picker.").argParser(
     parseChannelId
   )
 ).option(
   "--env <vars...>",
   "Arbitrary environment variables to set in .env.local. Format: KEY=VALUE (repeatable)."
 ).addOption(
-  new Option4("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
+  new Option3("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
 ).action(async (options) => {
   const config2 = getProjectConfig();
-  const credentials = await resolveCredentialsWithLogin(options, config2);
+  const apiHost = resolveApiHost(options, config2);
+  const credentials = await resolveCredentialsWithLogin(options, config2, apiHost);
   if (!credentials) {
     consola.info(
       "Login aborted. Re-run `catalyst channel link` when you have your credentials ready."
@@ -1643,7 +1977,7 @@ Examples:
   let channelId = options.channelId;
   let channelName;
   if (channelId === void 0) {
-    const channels = await fetchAvailableChannels(storeHash, accessToken, options.apiHost);
+    const channels = await fetchAvailableChannels(storeHash, accessToken, apiHost);
     if (channels.length === 0) {
       consola.info(
         "No storefront channels found on this store. Create one with `catalyst create` and try again."
@@ -1651,7 +1985,7 @@ Examples:
       process.exit(0);
       return;
     }
-    channelId = await select3({
+    channelId = await select4({
       message: "Which channel would you like to link?",
       choices: sortChannelsByPlatform(channels).map((c) => ({
         name: c.name,
@@ -1669,32 +2003,108 @@ Examples:
       envVars[key] = value;
     });
   }
-  outputFileSync(
-    join6(process.cwd(), ".env.local"),
-    `${Object.entries(envVars).map(([key, value]) => `${key}=${value}`).join("\n")}
-`
-  );
+  writeEnv(process.cwd(), envVars);
   const label = channelName ? `"${channelName}" (${channelId})` : `${channelId}`;
   consola.success(
-    `Linked to channel ${label} and wrote ${colorize3("cyanBright", ".env.local")}.`
+    `Linked to channel ${label} and wrote ${colorize5("cyanBright", ".env.local")}.`
   );
   consola.log(`Next steps:
 
-  ${colorize3("yellow", "pnpm run dev")}`);
+  ${colorize5("yellow", "pnpm run dev")}`);
+  process.exit(0);
+});
+var create = new Command3("create").configureHelp({ showGlobalOptions: true }).description("Create a new Catalyst storefront channel on your BigCommerce store.").addHelpText(
+  "after",
+  `
+Examples:
+  # Create a channel interactively (logs you in if needed)
+  $ catalyst channel create
+
+  # Non-interactive, and link it to this project afterwards
+  $ catalyst channel create --name "My Store" --locale en --no-sample-data --link
+
+  # Add additional storefront languages (max 4)
+  $ catalyst channel create --name "My Store" --additional-locales es fr`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).option("--name <name>", "Name for the new channel. Skips the name prompt.").option(
+  "--locale <locale>",
+  'Default storefront locale (e.g. "en"). Skips the default-language prompt.'
+).option(
+  "--additional-locales <locales...>",
+  "Additional storefront locales, max 4 (e.g. --additional-locales es fr). Skips the additional-languages prompt."
+).addOption(new Option3("--sample-data", "Install sample data on the new channel.")).addOption(new Option3("--no-sample-data", "Create the channel without sample data.")).option(
+  "--link",
+  "Link the new channel to this project \u2014 write its credentials to .env.local without prompting."
+).addOption(
+  new Option3("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
+).action(async (options) => {
+  if (options.additionalLocales && options.additionalLocales.length > 4) {
+    consola.error("You can only set up to 4 additional locales.");
+    process.exit(1);
+    return;
+  }
+  const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
+  const credentials = await resolveCredentialsWithLogin(options, config2, apiHost);
+  if (!credentials) {
+    consola.info(
+      "Login aborted. Re-run `catalyst channel create` when you have your credentials ready."
+    );
+    process.exit(0);
+    return;
+  }
+  const { storeHash, accessToken } = credentials;
+  await getTelemetry().identify(storeHash);
+  const eligibility = await checkChannelEligibility(storeHash, accessToken, options.cliApiOrigin);
+  if (!eligibility.eligible) {
+    consola.warn(eligibility.message);
+    process.exit(0);
+    return;
+  }
+  const channelData = await runCreateChannelFlow({
+    storeHash,
+    accessToken,
+    apiHost,
+    cliApiOrigin: options.cliApiOrigin,
+    name: options.name,
+    locale: options.locale,
+    additionalLocales: options.additionalLocales,
+    sampleData: options.sampleData
+  });
+  consola.success(`Created channel ${channelData.channelId}.`);
+  consola.warn(
+    "A preview storefront has been deployed in your BigCommerce control panel. This preview may look different from your local environment as it may be running different code. Additionally, it may take a few minutes for the channel storefront to be accessible."
+  );
+  const shouldLink = options.link ? true : await select4({
+    message: "Would you like to link this channel to your project?",
+    choices: [
+      { name: "Yes", value: true },
+      { name: "No", value: false }
+    ]
+  });
+  if (shouldLink) {
+    writeEnv(process.cwd(), channelData.envVars);
+    consola.success(
+      `Linked to channel ${channelData.channelId} and wrote ${colorize5("cyanBright", ".env.local")}.`
+    );
+    consola.log(`Next steps:
+
+  ${colorize5("yellow", "pnpm run dev")}`);
+  }
   process.exit(0);
 });
-var channel = new Command3("channel").configureHelp({ showGlobalOptions: true }).description("Manage BigCommerce channels.").addCommand(link).addCommand(update);
+var channel = new Command3("channel").configureHelp({ showGlobalOptions: true }).description("Manage BigCommerce channels.").addCommand(create).addCommand(link).addCommand(update);
 
 // src/cli/commands/create.ts
-import { Command as Command4, InvalidArgumentError as InvalidArgumentError2, Option as Option5 } from "@commander-js/extra-typings";
-import { checkbox, input as input3, select as select4 } from "@inquirer/prompts";
+import { Command as Command4, InvalidArgumentError as InvalidArgumentError3, Option as Option4 } from "@commander-js/extra-typings";
+import { input as input4, select as select5 } from "@inquirer/prompts";
 import { execSync as execSync2 } from "child_process";
-import { colorize as colorize4 } from "consola/utils";
+import { colorize as colorize6 } from "consola/utils";
 import { pathExistsSync } from "fs-extra/esm";
 import kebabCase from "lodash.kebabcase";
-import { join as join11 } from "path";
+import { join as join10 } from "path";
 
 // src/cli/lib/detect-package-manager.ts
+import { detectPackageManager as detectFromDir } from "nypm";
 var detectPackageManager = () => {
   const userAgent = process.env.npm_config_user_agent ?? "";
   const name = userAgent.split(" ")[0]?.split("/")[0];
@@ -1706,6 +2116,14 @@ var detectPackageManager = () => {
   }
   return "npm";
 };
+var detectProjectPackageManager = async (projectDir) => {
+  const detected = await detectFromDir(projectDir);
+  const name = detected?.name;
+  if (name === "pnpm" || name === "yarn" || name === "bun" || name === "npm") {
+    return name;
+  }
+  return "npm";
+};
 
 // src/cli/lib/extract-catalyst.ts
 import { mkdirSync as mkdirSync2 } from "fs";
@@ -1779,12 +2197,32 @@ var initGitRepo = (projectDir) => {
 // src/cli/lib/install-dependencies.ts
 import { installDependencies as installDeps } from "nypm";
 import yoctoSpinner2 from "yocto-spinner";
+var restoreEnv = (key, previous) => {
+  if (previous === void 0) {
+    Reflect.deleteProperty(process.env, key);
+  } else {
+    process.env[key] = previous;
+  }
+};
+var withQuietInstallEnv = async (run2) => {
+  var _a, _b;
+  const prevNodeNoWarnings = process.env.NODE_NO_WARNINGS;
+  const prevDownloadPrompt = process.env.COREPACK_ENABLE_DOWNLOAD_PROMPT;
+  (_a = process.env).NODE_NO_WARNINGS ?? (_a.NODE_NO_WARNINGS = "1");
+  (_b = process.env).COREPACK_ENABLE_DOWNLOAD_PROMPT ?? (_b.COREPACK_ENABLE_DOWNLOAD_PROMPT = "0");
+  try {
+    return await run2();
+  } finally {
+    restoreEnv("NODE_NO_WARNINGS", prevNodeNoWarnings);
+    restoreEnv("COREPACK_ENABLE_DOWNLOAD_PROMPT", prevDownloadPrompt);
+  }
+};
 var installDependencies = async (projectDir, packageManager = "pnpm") => {
   const spinner = yoctoSpinner2().start(
     `Installing dependencies with ${packageManager}. This could take a minute...`
   );
   try {
-    await installDeps({ cwd: projectDir, silent: true, packageManager });
+    await withQuietInstallEnv(() => installDeps({ cwd: projectDir, silent: true, packageManager }));
     spinner.success("Dependencies installed successfully.");
   } catch (error) {
     const message = error instanceof Error ? error.message : "unknown error";
@@ -1793,64 +2231,10 @@ var installDependencies = async (projectDir, packageManager = "pnpm") => {
   }
 };
 
-// src/cli/lib/localization.ts
-import { z as z8 } from "zod";
-var allowedLocales = [
-  "en",
-  "da",
-  "es-AR",
-  "es-CL",
-  "es-CO",
-  "es-MX",
-  "es-PE",
-  "es-419",
-  "es",
-  "it",
-  "nl",
-  "pl",
-  "pt",
-  "de",
-  "fr",
-  "ja",
-  "no",
-  "pt-BR",
-  "sv"
-];
-var AvailableLocalesSuccessSchema = z8.object({
-  data: z8.array(
-    z8.object({
-      id: z8.string(),
-      name: z8.string(),
-      fallback: z8.string().nullable(),
-      is_supported: z8.boolean()
-    })
-  )
-});
-var getAvailableLocales = async (storeHash, accessToken, apiHost) => {
-  const response = await fetch(
-    `https://${apiHost}/stores/${storeHash}/v3/settings/store/available-locales`,
-    {
-      method: "GET",
-      headers: {
-        "X-Auth-Token": accessToken,
-        "X-Correlation-Id": getTelemetry().correlationId,
-        Accept: "application/json"
-      }
-    }
-  );
-  assertAuthorized(response);
-  if (!response.ok) {
-    throw new Error(
-      `GET /v3/settings/store/available-locales failed: ${response.status} ${response.statusText}`
-    );
-  }
-  return AvailableLocalesSuccessSchema.parse(await response.json()).data.filter(({ id }) => allowedLocales.includes(id)).map(({ name, id }) => ({ name: `${name} (${id})`, value: id }));
-};
-
 // src/cli/lib/rewrite-core-package.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
 import { join as join8 } from "path";
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var NATIVE_BUILD_ALLOWLIST = [
   "@parcel/watcher",
   "@swc/core",
@@ -1868,18 +2252,18 @@ var DEP_FIELDS = [
   "optionalDependencies",
   "peerDependencies"
 ];
-var corePackageJsonSchema2 = z9.looseObject({
-  version: z9.string().optional(),
-  private: z9.boolean().optional(),
-  scripts: z9.record(z9.string(), z9.string()).optional(),
-  dependencies: z9.record(z9.string(), z9.string()).optional(),
-  devDependencies: z9.record(z9.string(), z9.string()).optional(),
-  optionalDependencies: z9.record(z9.string(), z9.string()).optional(),
-  peerDependencies: z9.record(z9.string(), z9.string()).optional(),
-  pnpm: z9.looseObject({}).optional(),
-  catalyst: z9.looseObject({}).optional()
+var corePackageJsonSchema2 = z10.looseObject({
+  version: z10.string().optional(),
+  private: z10.boolean().optional(),
+  scripts: z10.record(z10.string(), z10.string()).optional(),
+  dependencies: z10.record(z10.string(), z10.string()).optional(),
+  devDependencies: z10.record(z10.string(), z10.string()).optional(),
+  optionalDependencies: z10.record(z10.string(), z10.string()).optional(),
+  peerDependencies: z10.record(z10.string(), z10.string()).optional(),
+  pnpm: z10.looseObject({}).optional(),
+  catalyst: z10.looseObject({}).optional()
 });
-var registryVersionSchema = z9.object({ version: z9.string() });
+var registryVersionSchema = z10.object({ version: z10.string() });
 var resolvePublishedVersion = async (pkgName) => {
   const response = await fetch(`https://registry.npmjs.org/${pkgName}/latest`);
   if (!response.ok) {
@@ -1892,7 +2276,7 @@ var resolvePublishedVersion = async (pkgName) => {
 };
 var rewriteCorePackage = async (projectDir, ref) => {
   const packageJsonPath = join8(projectDir, "package.json");
-  const pkg = corePackageJsonSchema2.parse(JSON.parse(readFileSync3(packageJsonPath, "utf-8")));
+  const pkg = corePackageJsonSchema2.parse(JSON.parse(readFileSync4(packageJsonPath, "utf-8")));
   const workspaceDeps = DEP_FIELDS.flatMap((field) => {
     const deps = pkg[field];
     if (!deps) return [];
@@ -1920,12 +2304,12 @@ var rewriteCorePackage = async (projectDir, ref) => {
 };
 
 // src/cli/lib/setup-core-project.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname3, join as join9 } from "path";
-import { z as z10 } from "zod";
-var corePackageJsonSchema3 = z10.looseObject({
-  scripts: z10.record(z10.string(), z10.string()).optional(),
-  dependencies: z10.record(z10.string(), z10.string()).optional()
+import { z as z11 } from "zod";
+var corePackageJsonSchema3 = z11.looseObject({
+  scripts: z11.record(z11.string(), z11.string()).optional(),
+  devDependencies: z11.record(z11.string(), z11.string()).optional()
 });
 var writeJson2 = (path, value) => {
   mkdirSync3(dirname3(path), { recursive: true });
@@ -1934,31 +2318,20 @@ var writeJson2 = (path, value) => {
 };
 var setupCoreProject = (projectDir) => {
   const corePackageJsonPath = join9(projectDir, "package.json");
-  const pkg = corePackageJsonSchema3.parse(JSON.parse(readFileSync4(corePackageJsonPath, "utf-8")));
+  const pkg = corePackageJsonSchema3.parse(JSON.parse(readFileSync5(corePackageJsonPath, "utf-8")));
   pkg.scripts = {
     ...pkg.scripts,
     build: "npm run generate && catalyst build",
     start: "catalyst start",
     deploy: "npm run generate && catalyst deploy"
   };
-  pkg.dependencies = {
-    ...pkg.dependencies,
+  pkg.devDependencies = {
+    ...pkg.devDependencies,
     "@bigcommerce/catalyst": package_default.version
   };
   writeJson2(corePackageJsonPath, sortPackageJsonFields(pkg));
 };
 
-// src/cli/lib/write-env.ts
-import { outputFileSync as outputFileSync2 } from "fs-extra/esm";
-import { join as join10 } from "path";
-var writeEnv = (projectDir, envVars) => {
-  outputFileSync2(
-    join10(projectDir, ".env.local"),
-    `${Object.entries(envVars).map(([key, value]) => `${key}=${value}`).join("\n")}
-`
-  );
-};
-
 // src/cli/commands/create.ts
 function getPlatformCheckCommand(command) {
   const isWindows = process.platform === "win32";
@@ -1967,73 +2340,25 @@ function getPlatformCheckCommand(command) {
 function parseChannelId2(value) {
   const parsed = parseInt(value, 10);
   if (Number.isNaN(parsed)) {
-    throw new InvalidArgumentError2(`"${value}" is not a valid channel ID (expected a number).`);
+    throw new InvalidArgumentError3(`"${value}" is not a valid channel ID (expected a number).`);
   }
   return parsed;
 }
 function parseEnvFlag(value, previous = {}) {
   const eqIdx = value.indexOf("=");
   if (eqIdx <= 0) {
-    throw new InvalidArgumentError2(`Expected KEY=VALUE, got "${value}".`);
+    throw new InvalidArgumentError3(`Expected KEY=VALUE, got "${value}".`);
   }
   const key = value.substring(0, eqIdx);
   const val = value.substring(eqIdx + 1);
   if (!val) {
-    throw new InvalidArgumentError2(`Expected KEY=VALUE with non-empty value, got "${value}".`);
+    throw new InvalidArgumentError3(`Expected KEY=VALUE with non-empty value, got "${value}".`);
   }
   return { ...previous, [key]: val };
 }
-async function handleChannelCreation(storeHash, accessToken, apiHost, cliApiOrigin) {
-  const newChannelName = await input3({
-    message: "What would you like to name your new channel?"
-  });
-  const availableLocales = await getAvailableLocales(storeHash, accessToken, apiHost);
-  const storefrontLocale = await select4({
-    message: "Which default language would you like to set for your channel?",
-    default: "en",
-    choices: availableLocales,
-    theme: {
-      style: {
-        help: () => colorize4("dim", "(Select locale from the list or start typing the name)")
-      }
-    }
-  });
-  const shouldAddAdditionalLocales = await select4({
-    message: "Would you like to add additional languages?",
-    choices: [
-      { name: "Yes", value: true },
-      { name: "No", value: false }
-    ]
-  });
-  let additionalLocales = [];
-  if (shouldAddAdditionalLocales) {
-    const localeChoices = availableLocales.filter(({ value }) => value !== storefrontLocale).map(({ name, value }) => ({ name, value, description: value }));
-    additionalLocales = await checkbox({
-      message: "Which additional languages would you like to add to your channel?",
-      choices: localeChoices,
-      validate: (items) => items.length <= 4 || "You can only select up to 4 additional languages."
-    });
-  }
-  const shouldInstallSampleData = await select4({
-    message: "Would you like to install sample data?",
-    choices: [
-      { name: "Yes", value: true },
-      { name: "No", value: false }
-    ]
-  });
-  return createChannel(
-    newChannelName,
-    storefrontLocale,
-    additionalLocales,
-    shouldInstallSampleData,
-    storeHash,
-    accessToken,
-    cliApiOrigin
-  );
-}
 async function handleChannelSelection(storeHash, accessToken, apiHost) {
   const channels = await fetchAvailableChannels(storeHash, accessToken, apiHost);
-  const existingChannel = await select4({
+  const existingChannel = await select5({
     message: "Which channel would you like to use?",
     choices: sortChannelsByPlatform(channels).map((ch) => ({
       name: ch.name,
@@ -2051,7 +2376,7 @@ async function setupProject(options) {
   }
   if (projectName) {
     projectName = kebabCase(projectName);
-    projectDir = join11(options.projectDir, projectName);
+    projectDir = join10(options.projectDir, projectName);
     if (pathExistsSync(projectDir)) {
       consola.error(`${projectDir} already exists`);
       process.exit(1);
@@ -2061,13 +2386,13 @@ async function setupProject(options) {
     const validateProjectName = (i) => {
       const formatted = kebabCase(i);
       if (!formatted) return "Project name is required";
-      const targetDir = join11(options.projectDir, formatted);
+      const targetDir = join10(options.projectDir, formatted);
       if (pathExistsSync(targetDir)) return `Destination '${targetDir}' already exists`;
       projectName = formatted;
       projectDir = targetDir;
       return true;
     };
-    await input3({
+    await input4({
       message: "What do you want to name your project directory?",
       default: "my-catalyst-app",
       validate: validateProjectName
@@ -2085,7 +2410,7 @@ function checkRequiredTools() {
     process.exit(1);
   }
 }
-var create = new Command4("create").configureHelp({ showGlobalOptions: true }).description("Scaffold and connect a Catalyst storefront to your BigCommerce store.").addHelpText(
+var create2 = new Command4("create").configureHelp({ showGlobalOptions: true }).description("Scaffold and connect a Catalyst storefront to your BigCommerce store.").addHelpText(
   "after",
   `
 Examples:
@@ -2106,7 +2431,7 @@ Examples:
   "Arbitrary environment variables to set in .env.local. Format: KEY=VALUE (repeatable).",
   parseEnvFlag
 ).addOption(
-  new Option5(
+  new Option4(
     "--hosting <mode>",
     'Hosting mode: "self-hosted" (default) or "commerce" to set up Commerce Hosting at create time. When omitted, scaffolding is hosting-agnostic; run `catalyst deploy` later to opt in.'
   ).choices(["self-hosted", "commerce"])
@@ -2114,11 +2439,11 @@ Examples:
   "--use-existing",
   "Only used with --hosting commerce and --project-name. When the named project already exists on the store, reuse it instead of prompting. Has no effect without --hosting commerce."
 ).addOption(
-  new Option5("--bigcommerce-hostname <hostname>", "BigCommerce hostname").default("bigcommerce.com").hideHelp()
+  new Option4("--bigcommerce-hostname <hostname>", "BigCommerce hostname").default("bigcommerce.com").hideHelp()
 ).addOption(
-  new Option5("--login-url <url>", "BigCommerce login URL.").env("BIGCOMMERCE_LOGIN_URL").default(DEFAULT_LOGIN_URL).hideHelp()
+  new Option4("--login-url <url>", "BigCommerce login URL.").env("BIGCOMMERCE_LOGIN_URL").default(DEFAULT_LOGIN_URL).hideHelp()
 ).addOption(
-  new Option5("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
+  new Option4("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
 ).action(async (options) => {
   const { ghRef, repository } = options;
   if (options.useExisting && options.hosting !== "commerce") {
@@ -2172,7 +2497,7 @@ Examples:
       }
       let shouldCreateChannel;
       if (eligibility.eligible) {
-        shouldCreateChannel = await select4({
+        shouldCreateChannel = await select5({
           message: "Would you like to create a new channel?",
           choices: [
             { name: "Yes", value: true },
@@ -2181,12 +2506,12 @@ Examples:
         });
       }
       if (shouldCreateChannel) {
-        const channelData = await handleChannelCreation(
+        const channelData = await runCreateChannelFlow({
           storeHash,
           accessToken,
           apiHost,
           cliApiOrigin
-        );
+        });
         channelId = channelData.channelId;
         storefrontToken = channelData.storefrontToken;
         envVars = { ...channelData.envVars };
@@ -2265,19 +2590,280 @@ Examples:
   consola.log(
     `Next steps:
 
-${steps.map((step) => `  ${colorize4("yellow", step)}`).join("\n")}`
+${steps.map((step) => `  ${colorize6("yellow", step)}`).join("\n")}`
   );
 });
 
+// src/cli/commands/debug.ts
+import { Command as Command5, Option as Option5 } from "commander";
+
+// src/cli/lib/collect-diagnostics.ts
+import { parse } from "dotenv";
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
+import { release } from "os";
+import { dirname as dirname4, join as join11 } from "path";
+import { z as z12 } from "zod";
+var CLI_ENV_VARS = [
+  "CATALYST_STORE_HASH",
+  "CATALYST_ACCESS_TOKEN",
+  "CATALYST_PROJECT_UUID",
+  "CATALYST_API_HOST",
+  "BIGCOMMERCE_LOGIN_URL",
+  "CATALYST_TELEMETRY_DISABLED"
+];
+var BUILD_ENV_VARS = [
+  "BIGCOMMERCE_STORE_HASH",
+  "BIGCOMMERCE_STOREFRONT_TOKEN",
+  "BIGCOMMERCE_CHANNEL_ID",
+  "AUTH_SECRET"
+];
+var ENV_FILES = [".env.local", ".env"];
+var PROJECT_LOCKFILES = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["package-lock.json", "npm"]
+];
+var hasValue = (value) => value !== void 0 && value.trim() !== "";
+var buildEnvLayers = (cwd, env2) => {
+  const layers = [{ source: "process.env", values: env2 }];
+  ENV_FILES.forEach((file) => {
+    const path = join11(cwd, file);
+    if (!existsSync5(path)) {
+      return;
+    }
+    try {
+      layers.push({ source: file, values: parse(readFileSync6(path, "utf-8")) });
+    } catch {
+    }
+  });
+  return layers;
+};
+var resolveEnvSource = (layers, ...keys) => layers.find((layer) => keys.some((key) => hasValue(layer.values[key])))?.source;
+var resolveEnvVars = (layers, names) => Object.fromEntries(names.map((name) => [name, resolveEnvSource(layers, name) ?? "unset"]));
+var resolveValue = (envSource, configValue) => {
+  if (envSource) {
+    return { present: true, source: envSource };
+  }
+  if (hasValue(configValue)) {
+    return { present: true, source: "project.json" };
+  }
+  return { present: false, source: "unset" };
+};
+var asString = (value) => typeof value === "string" ? value : void 0;
+var lockfileManager = (dir) => PROJECT_LOCKFILES.find(([file]) => existsSync5(join11(dir, file)))?.[1];
+var detectProjectPackageManager2 = (cwd) => {
+  let dir = cwd;
+  for (; ; ) {
+    const match = lockfileManager(dir);
+    if (match) {
+      return match;
+    }
+    const parent = dirname4(dir);
+    if (parent === dir) {
+      return detectPackageManager();
+    }
+    dir = parent;
+  }
+};
+var projectJsonSchema2 = z12.looseObject({});
+var safeReadJson2 = (path) => {
+  try {
+    return JSON.parse(readFileSync6(path, "utf-8"));
+  } catch {
+    return null;
+  }
+};
+var readProjectJson = (cwd) => {
+  const result = projectJsonSchema2.safeParse(
+    safeReadJson2(join11(cwd, ".bigcommerce", "project.json"))
+  );
+  return result.success ? result.data : null;
+};
+var storefrontPackageSchema = z12.looseObject({
+  name: z12.string().optional(),
+  version: z12.string().optional(),
+  catalyst: z12.looseObject({ version: z12.string().optional() }).optional()
+});
+var readStorefrontInfo = (cwd) => {
+  const result = storefrontPackageSchema.safeParse(safeReadJson2(join11(cwd, "package.json")));
+  if (!result.success) {
+    return { name: null, version: null };
+  }
+  return {
+    name: result.data.name ?? null,
+    version: result.data.catalyst?.version ?? result.data.version ?? null
+  };
+};
+var readStoredEnvKeys = (projectJson) => {
+  const env2 = projectJson?.env;
+  if (typeof env2 === "object" && env2 !== null && !Array.isArray(env2)) {
+    return Object.keys(env2).sort();
+  }
+  return [];
+};
+function collectDiagnostics({
+  cwd = process.cwd(),
+  env: env2 = process.env
+} = {}) {
+  const state = getProjectState(cwd);
+  const telemetry3 = getTelemetry();
+  const projectJson = readProjectJson(cwd);
+  const storefront = readStorefrontInfo(cwd);
+  const cliEnv = [{ source: "process.env", values: env2 }];
+  const buildEnv = buildEnvLayers(cwd, env2);
+  return {
+    cli: {
+      name: package_default.name,
+      version: package_default.version
+    },
+    runtime: {
+      node: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      osRelease: release(),
+      packageManager: detectProjectPackageManager2(cwd)
+    },
+    project: {
+      cwd,
+      storefrontName: storefront.name,
+      storefrontVersion: storefront.version,
+      projectUuid: state.projectUuid ?? null,
+      isLinked: state.isLinked,
+      isTransformed: state.isTransformed,
+      isFullySetUp: state.isFullySetUp,
+      hasMiddleware: state.hasMiddleware,
+      hasProxy: state.hasProxy,
+      hasOpenNextDep: state.hasOpenNextDep
+    },
+    config: {
+      storeHash: resolveValue(
+        resolveEnvSource(cliEnv, "CATALYST_STORE_HASH", "BIGCOMMERCE_STORE_HASH"),
+        asString(projectJson?.storeHash)
+      ),
+      accessToken: resolveValue(
+        resolveEnvSource(cliEnv, "CATALYST_ACCESS_TOKEN"),
+        asString(projectJson?.accessToken)
+      ),
+      projectUuid: resolveValue(
+        resolveEnvSource(cliEnv, "CATALYST_PROJECT_UUID"),
+        asString(projectJson?.projectUuid)
+      ),
+      apiHost: resolveValue(
+        resolveEnvSource(cliEnv, "CATALYST_API_HOST"),
+        asString(projectJson?.apiHost)
+      ),
+      projectJsonKeys: projectJson ? Object.keys(projectJson).sort() : [],
+      storedEnvKeys: readStoredEnvKeys(projectJson),
+      cliEnvVars: resolveEnvVars(cliEnv, CLI_ENV_VARS),
+      buildEnvVars: resolveEnvVars(buildEnv, BUILD_ENV_VARS)
+    },
+    telemetry: {
+      enabled: telemetry3.isEnabled(),
+      correlationId: telemetry3.correlationId
+    },
+    files: {
+      ".env.local": existsSync5(join11(cwd, ".env.local")),
+      ".env": existsSync5(join11(cwd, ".env")),
+      ".bigcommerce/project.json": existsSync5(join11(cwd, ".bigcommerce", "project.json")),
+      ".bigcommerce/wrangler.jsonc": existsSync5(join11(cwd, ".bigcommerce", "wrangler.jsonc")),
+      ".open-next/": existsSync5(join11(cwd, ".open-next")),
+      "package.json": existsSync5(join11(cwd, "package.json"))
+    }
+  };
+}
+
+// src/cli/commands/debug.ts
+var yesNo = (value) => value ? "yes" : "no";
+var presence = (value) => value ? "present" : "absent";
+var formatResolved = (value) => value.present ? `present (source: ${value.source})` : "not set";
+var formatSource = (source) => source === "unset" ? "not set" : `set (${source})`;
+var formatStorefront = (name, version2) => {
+  if (!version2) {
+    return "(unknown)";
+  }
+  return name ? `${name}@${version2}` : version2;
+};
+var formatList = (values) => values.length > 0 ? values.join(", ") : "(none)";
+var envVarLines = (vars) => Object.entries(vars).map(([name, source]) => `  ${name}: ${formatSource(source)}`);
+var formatReport = (d) => {
+  const lines = [
+    "Catalyst CLI Diagnostics",
+    "",
+    "CLI",
+    `  Package:            ${d.cli.name}`,
+    `  Version:            ${d.cli.version}`,
+    "",
+    "Runtime",
+    `  Node:               ${d.runtime.node}`,
+    `  Platform:           ${d.runtime.platform} (${d.runtime.arch})`,
+    `  OS release:         ${d.runtime.osRelease}`,
+    `  Package manager:    ${d.runtime.packageManager}`,
+    "",
+    "Project",
+    `  Directory:          ${d.project.cwd}`,
+    `  Storefront:         ${formatStorefront(d.project.storefrontName, d.project.storefrontVersion)}`,
+    `  Project UUID:       ${d.project.projectUuid ?? "(not linked)"}`,
+    `  Linked:             ${yesNo(d.project.isLinked)}`,
+    `  Transformed:        ${yesNo(d.project.isTransformed)}`,
+    `  Fully set up:       ${yesNo(d.project.isFullySetUp)}`,
+    `  middleware.ts:      ${presence(d.project.hasMiddleware)}`,
+    `  proxy.ts:           ${presence(d.project.hasProxy)}`,
+    `  OpenNext dep:       ${d.project.hasOpenNextDep ? "installed" : "not installed"}`,
+    "",
+    "Config (resolved without secrets)",
+    `  Store hash:         ${formatResolved(d.config.storeHash)}`,
+    `  Access token:       ${formatResolved(d.config.accessToken)}`,
+    `  Project UUID:       ${formatResolved(d.config.projectUuid)}`,
+    `  API host:           ${d.config.apiHost.present ? formatResolved(d.config.apiHost) : "default (api.bigcommerce.com)"}`,
+    `  project.json keys:  ${formatList(d.config.projectJsonKeys)}`,
+    `  Stored env keys:    ${formatList(d.config.storedEnvKeys)}`,
+    "",
+    "CLI environment variables (used to run the CLI)",
+    ...envVarLines(d.config.cliEnvVars),
+    "",
+    "Build environment variables (used to build the Next.js app)",
+    ...envVarLines(d.config.buildEnvVars),
+    "",
+    "Telemetry",
+    `  Enabled:            ${yesNo(d.telemetry.enabled)}`,
+    `  Correlation ID:     ${d.telemetry.correlationId}`,
+    "",
+    "Files",
+    ...Object.entries(d.files).map(([name, exists]) => `  ${name}: ${presence(exists)}`)
+  ];
+  return lines.join("\n");
+};
+var debug = new Command5("debug").configureHelp({ showGlobalOptions: true }).description(
+  "Print a diagnostic report (CLI, runtime, project, and config state) to include when filing a bug report. Never prints secret values \u2014 credentials and env vars are reported by presence only."
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Print a human-readable report
+  $ catalyst debug
+
+  # Print machine-readable JSON (useful for copy/paste or piping)
+  $ catalyst debug --json`
+).addOption(new Option5("--json", "Output the report as JSON.")).action((options) => {
+  const diagnostics = collectDiagnostics();
+  if (options.json) {
+    consola.log(JSON.stringify(diagnostics, null, 2));
+    return;
+  }
+  consola.log(formatReport(diagnostics));
+});
+
 // src/cli/commands/deploy.ts
 import { confirm as confirm3 } from "@inquirer/prompts";
 import AdmZip from "adm-zip";
-import { Command as Command5, Option as Option6 } from "commander";
-import { colorize as colorize5 } from "consola/utils";
+import { Command as Command6, Option as Option6 } from "commander";
+import { colorize as colorize7 } from "consola/utils";
 import { access, readdir, readFile } from "fs/promises";
 import { join as join12 } from "path";
 import yoctoSpinner3 from "yocto-spinner";
-import { z as z11 } from "zod";
+import { z as z13 } from "zod";
 
 // src/cli/lib/deployment-errors.ts
 var ERROR_MESSAGES = {
@@ -2296,7 +2882,7 @@ function getDeploymentErrorMessage(code) {
 }
 
 // src/cli/commands/deploy.ts
-var stepsEnum = z11.enum([
+var stepsEnum = z13.enum([
   "initializing",
   "downloading",
   "unzipping",
@@ -2314,35 +2900,35 @@ var STEPS = {
   finalizing: "Finalizing...",
   complete: "Complete"
 };
-var UploadSignatureSchema = z11.object({
-  data: z11.object({
-    upload_url: z11.url(),
-    upload_uuid: z11.string()
+var UploadSignatureSchema = z13.object({
+  data: z13.object({
+    upload_url: z13.url(),
+    upload_uuid: z13.string()
   })
 });
-var CreateDeploymentSchema = z11.object({
-  data: z11.object({
-    deployment_uuid: z11.uuid()
+var CreateDeploymentSchema = z13.object({
+  data: z13.object({
+    deployment_uuid: z13.uuid()
   })
 });
-var ProjectSchema = z11.object({
-  data: z11.array(
-    z11.object({
-      uuid: z11.uuid(),
-      name: z11.string()
+var ProjectSchema = z13.object({
+  data: z13.array(
+    z13.object({
+      uuid: z13.uuid(),
+      name: z13.string()
     })
   )
 });
-var DeploymentStatusSchema = z11.object({
-  deployment_uuid: z11.uuid(),
-  deployment_status: z11.enum(["queued", "in_progress", "failed", "completed"]),
-  event: z11.object({
+var DeploymentStatusSchema = z13.object({
+  deployment_uuid: z13.uuid(),
+  deployment_status: z13.enum(["queued", "in_progress", "failed", "completed"]),
+  event: z13.object({
     step: stepsEnum,
-    progress: z11.number()
+    progress: z13.number()
   }).nullable(),
-  deployment_hostnames: z11.array(z11.string()).optional(),
-  error: z11.object({
-    code: z11.number()
+  deployment_hostnames: z13.array(z13.string()).optional(),
+  error: z13.object({
+    code: z13.number()
   }).optional()
 });
 var generateBundleZip = async () => {
@@ -2381,7 +2967,7 @@ var generateUploadSignature = async (storeHash, accessToken, apiHost) => {
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`Failed to fetch upload signature: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to generate upload signature");
   }
   const res = await response.json();
   const { data } = UploadSignatureSchema.parse(res);
@@ -2400,7 +2986,7 @@ var uploadBundleZip = async (uploadUrl) => {
     body: fileBuffer
   });
   if (!response.ok) {
-    throw new Error(`Failed to upload bundle: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to upload bundle");
   }
   consola.success("Bundle uploaded successfully.");
   return true;
@@ -2436,7 +3022,7 @@ var createDeployment = async (projectUuid, uploadUuid, storeHash, accessToken, a
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`Failed to create deployment: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to create deployment");
   }
   const res = await response.json();
   const { data } = CreateDeploymentSchema.parse(res);
@@ -2460,7 +3046,7 @@ var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`Failed to open event stream: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to open deployment event stream");
   }
   const reader = response.body?.getReader();
   if (!reader) {
@@ -2501,7 +3087,7 @@ var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost
   spinner.success("Deployment completed successfully.");
   if (deploymentHostname) {
     consola.success(
-      `View your deployment at: ${colorize5("blue", `https://${deploymentHostname}`)}`
+      `View your deployment at: ${colorize7("blue", `https://${deploymentHostname}`)}`
     );
   }
   return deploymentHostname;
@@ -2521,13 +3107,13 @@ var fetchProject = async (projectUuid, storeHash, accessToken, apiHost) => {
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`Failed to fetch projects: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to fetch projects");
   }
   const res = await response.json();
   const { data } = ProjectSchema.parse(res);
   return data.find((project2) => project2.uuid === projectUuid);
 };
-var deploy = new Command5("deploy").configureHelp({ showGlobalOptions: true }).description("Deploy your application to Cloudflare.").addHelpText(
+var deploy = new Command6("deploy").configureHelp({ showGlobalOptions: true }).description("Deploy your application to Cloudflare.").addHelpText(
   "after",
   `
 Environment variables saved with \`catalyst env add\` are sent automatically on every deploy.
@@ -2548,8 +3134,14 @@ Example:
 ).option("--dry-run", "Run the command to generate the bundle without uploading or deploying.").option(
   "--prebuilt",
   "Skip the build step. Requires .bigcommerce/dist/ to already contain build output."
-).action(async (options) => {
+).addOption(
+  new Option6(
+    "--wrangler-version <version>",
+    `Wrangler version or dist-tag to build with. Ignored with --prebuilt. Defaults to ${WRANGLER_VERSION}.`
+  ).argParser(parseWranglerVersion)
+).addOption(envPathOption()).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   const telemetry3 = getTelemetry();
   await telemetry3.identify(storeHash);
@@ -2560,7 +3152,7 @@ Example:
       return await selectOrCreateInfrastructureProject({
         storeHash,
         accessToken,
-        apiHost: options.apiHost
+        apiHost
       });
     } catch (error) {
       if (error instanceof NoLinkedProjectError) {
@@ -2573,12 +3165,7 @@ Example:
     }
   };
   if (linkedProjectUuid) {
-    const existing = await fetchProject(
-      linkedProjectUuid,
-      storeHash,
-      accessToken,
-      options.apiHost
-    );
+    const existing = await fetchProject(linkedProjectUuid, storeHash, accessToken, apiHost);
     if (existing) {
       projectUuid = linkedProjectUuid;
     } else {
@@ -2609,7 +3196,8 @@ Example:
     const projectDir = process.cwd();
     await setupCommerceHosting({ projectDir, projectUuid, storeHash, accessToken });
     consola.success("Commerce Hosting setup complete.");
-    await installDependencies(projectDir);
+    const packageManager = await detectProjectPackageManager(projectDir);
+    await installDependencies(projectDir, packageManager);
   } else {
     await cleanupCloudflareIncompatibilities(process.cwd());
   }
@@ -2630,7 +3218,8 @@ Example:
     }
     consola.info("Using existing build output (--prebuilt).");
   } else {
-    await buildCatalystProject(projectUuid);
+    loadBuildEnv({ envPath: options.envPath });
+    await buildCatalystProject(projectUuid, options.wranglerVersion);
   }
   await generateBundleZip();
   if (options.dryRun) {
@@ -2641,7 +3230,7 @@ Example:
     consola.info("- Create deployment");
     process.exit(0);
   }
-  const uploadSignature = await generateUploadSignature(storeHash, accessToken, options.apiHost);
+  const uploadSignature = await generateUploadSignature(storeHash, accessToken, apiHost);
   await uploadBundleZip(uploadSignature.upload_url);
   const flagSecrets = parseEnvironmentVariables(options.secret) ?? [];
   const persistedSecrets = toDeploymentSecrets(getStoredEnv(config2));
@@ -2652,14 +3241,14 @@ Example:
     uploadSignature.upload_uuid,
     storeHash,
     accessToken,
-    options.apiHost,
+    apiHost,
     environmentVariables
   );
   const deploymentHostname = await getDeploymentStatus(
     deploymentUuid,
     storeHash,
     accessToken,
-    options.apiHost
+    apiHost
   );
   if (!options.updateSiteUrl) {
     return;
@@ -2668,7 +3257,7 @@ Example:
     await runChannelSiteUrlFlow({
       storeHash,
       accessToken,
-      apiHost: options.apiHost,
+      apiHost,
       projectUuid,
       preferHostname: deploymentHostname
     });
@@ -2683,36 +3272,36 @@ Example:
 });
 
 // src/cli/commands/domains.ts
-import { confirm as confirm4 } from "@inquirer/prompts";
-import { Command as Command6, Option as Option7 } from "commander";
-import { colorize as colorize7 } from "consola/utils";
+import { confirm as confirm4, select as select6 } from "@inquirer/prompts";
+import { Command as Command7, Option as Option7 } from "commander";
+import { colorize as colorize9 } from "consola/utils";
 
 // src/cli/lib/domains.ts
-import { z as z13 } from "zod";
+import { z as z15 } from "zod";
 
 // src/cli/lib/observability.ts
-import { colorize as colorize6 } from "consola/utils";
-import { z as z12 } from "zod";
+import { colorize as colorize8 } from "consola/utils";
+import { z as z14 } from "zod";
 var LOG_LEVELS = ["debug", "info", "warn", "error"];
 var SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1e3;
-var logEntrySchema = z12.object({
-  timestamp: z12.string().nullable().optional(),
-  level: z12.string().optional(),
-  messages: z12.array(z12.unknown()).optional(),
-  is_exception: z12.boolean().optional(),
-  exception_name: z12.string().optional(),
-  request: z12.object({
-    method: z12.string().optional(),
-    url: z12.string().optional(),
-    status_code: z12.number().optional()
+var logEntrySchema = z14.object({
+  timestamp: z14.string().nullable().optional(),
+  level: z14.string().optional(),
+  messages: z14.array(z14.unknown()).optional(),
+  is_exception: z14.boolean().optional(),
+  exception_name: z14.string().optional(),
+  request: z14.object({
+    method: z14.string().optional(),
+    url: z14.string().optional(),
+    status_code: z14.number().optional()
   }).nullable().optional()
 });
-var queryLogsSchema = z12.object({
-  data: z12.array(logEntrySchema)
+var queryLogsSchema = z14.object({
+  data: z14.array(logEntrySchema)
 });
-var v3ErrorSchema = z12.object({
-  title: z12.string().optional(),
-  errors: z12.record(z12.string(), z12.string()).optional()
+var v3ErrorSchema = z14.object({
+  title: z14.string().optional(),
+  errors: z14.record(z14.string(), z14.string()).optional()
 });
 function formatV3Error(body) {
   const parsed = v3ErrorSchema.safeParse(body);
@@ -2749,7 +3338,7 @@ function resolveTimeWindow(opts, nowMs = Date.now()) {
   if (end) {
     endMs = parseTimeInput(end);
     if (endMs === null) {
-      throw new Error(
+      throw new UserActionableError(
         `Invalid --end value "${end}". Provide an ISO-8601 timestamp or a Unix epoch (seconds).`
       );
     }
@@ -2760,7 +3349,7 @@ function resolveTimeWindow(opts, nowMs = Date.now()) {
   if (since) {
     const durationMs = parseDuration(since);
     if (durationMs === null) {
-      throw new Error(
+      throw new UserActionableError(
         `Invalid --since value "${since}". Provide a duration like 30m, 6h, or 2d (units: s, m, h, d).`
       );
     }
@@ -2769,18 +3358,20 @@ function resolveTimeWindow(opts, nowMs = Date.now()) {
   } else if (start2) {
     startMs = parseTimeInput(start2);
     if (startMs === null) {
-      throw new Error(
+      throw new UserActionableError(
         `Invalid --start value "${start2}". Provide an ISO-8601 timestamp or a Unix epoch (seconds).`
       );
     }
   } else {
-    throw new Error("Provide a time window with --since <duration> or --start <time>.");
+    throw new UserActionableError(
+      "Provide a time window with --since <duration> or --start <time>."
+    );
   }
   if (startMs > endMs) {
-    throw new Error("Invalid time window: --start must be before or equal to --end.");
+    throw new UserActionableError("Invalid time window: --start must be before or equal to --end.");
   }
   if (endMs - startMs > SEVEN_DAYS_MS) {
-    throw new Error("Invalid time window: the range must not exceed 7 days.");
+    throw new UserActionableError("Invalid time window: the range must not exceed 7 days.");
   }
   return { start: start2, end };
 }
@@ -2800,8 +3391,8 @@ function formatLogEntry(entry, format = "default") {
   const message = (entry.messages ?? []).map(stringifyMessage).join(" ").replace(/\s+/g, " ").trim();
   if (format === "short") return message;
   const level = entry.level ?? "unknown";
-  const coloredLevel = colorize6(LEVEL_COLORS[level.toLowerCase()] ?? "white", level.toUpperCase());
-  const exceptionStr = entry.is_exception && entry.exception_name && !isRedundantExceptionName(entry.exception_name, message) ? ` ${colorize6("red", `[${entry.exception_name}]`)}` : "";
+  const coloredLevel = colorize8(LEVEL_COLORS[level.toLowerCase()] ?? "white", level.toUpperCase());
+  const exceptionStr = entry.is_exception && entry.exception_name && !isRedundantExceptionName(entry.exception_name, message) ? ` ${colorize8("red", `[${entry.exception_name}]`)}` : "";
   let requestStr = "";
   if (format === "request" && entry.request) {
     const parts = [];
@@ -2834,36 +3425,73 @@ async function queryLogs(projectUuid, storeHash, accessToken, apiHost, params) {
   );
   assertAuthorized(response);
   if (response.status === 403) {
-    throw new Error(
+    throw new UserActionableError(
       "Infrastructure Logs API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
   if (response.status === 404) {
-    throw new Error("Project not found. Check the project UUID.");
+    throw new UserActionableError("Project not found. Check the project UUID.");
   }
   if (response.status === 400 || response.status === 422) {
     const body = await response.json().catch(() => null);
-    throw new Error(formatV3Error(body) ?? "Invalid log query.");
+    throw new UserActionableError(formatV3Error(body) ?? "Invalid log query.");
   }
   if (!response.ok) {
-    throw new Error(`Failed to fetch logs: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to fetch logs");
   }
   const res = await response.json();
   return queryLogsSchema.parse(res);
 }
 
 // src/cli/lib/domains.ts
-var domainStatusSchema = z13.enum(["pending", "verified", "failed", "unknown"]);
-var domainSchema = z13.object({
-  domain: z13.string(),
-  project_uuid: z13.string(),
+var domainStatusSchema = z15.enum(["pending", "verified", "failed", "unknown"]);
+var domainSchema = z15.object({
+  domain: z15.string(),
+  project_uuid: z15.string(),
   verification_status: domainStatusSchema
 });
-var domainResponseSchema = z13.object({
+var ownershipVerificationSchema = z15.object({
+  type: z15.string(),
+  name: z15.string(),
+  value: z15.string().optional()
+});
+var ownershipVerificationMetaSchema = z15.object({
+  meta: z15.object({
+    ownership_verification: ownershipVerificationSchema
+  })
+});
+var DomainOwnershipVerificationError = class extends UserActionableError {
+  constructor(message, ownershipVerification) {
+    super(message);
+    this.name = "DomainOwnershipVerificationError";
+    this.ownershipVerification = ownershipVerification;
+  }
+};
+function parseOwnershipVerification(body) {
+  const parsed = ownershipVerificationMetaSchema.safeParse(body);
+  return parsed.success ? parsed.data.meta.ownership_verification : void 0;
+}
+var boundProjectMetaSchema = z15.object({
+  meta: z15.object({
+    project_uuid: z15.string()
+  })
+});
+var DomainBoundToProjectError = class extends UserActionableError {
+  constructor(message, projectUuid) {
+    super(message);
+    this.name = "DomainBoundToProjectError";
+    this.projectUuid = projectUuid;
+  }
+};
+function parseBoundProjectUuid(body) {
+  const parsed = boundProjectMetaSchema.safeParse(body);
+  return parsed.success ? parsed.data.meta.project_uuid : void 0;
+}
+var domainResponseSchema = z15.object({
   data: domainSchema
 });
-var domainListResponseSchema = z13.object({
-  data: z13.array(domainSchema)
+var domainListResponseSchema = z15.object({
+  data: z15.array(domainSchema)
 });
 var DOMAINS_API_NOT_ENABLED = "Infrastructure Domains API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it.";
 function domainsUrl(storeHash, projectUuid, apiHost) {
@@ -2872,6 +3500,12 @@ function domainsUrl(storeHash, projectUuid, apiHost) {
 function domainUrl(storeHash, projectUuid, domain, apiHost) {
   return `${domainsUrl(storeHash, projectUuid, apiHost)}/${encodeURIComponent(domain)}`;
 }
+function domainClaimUrl(storeHash, projectUuid, domain, apiHost) {
+  return `${domainUrl(storeHash, projectUuid, domain, apiHost)}/claim`;
+}
+function domainTransferUrl(storeHash, projectUuid, domain, apiHost) {
+  return `${domainUrl(storeHash, projectUuid, domain, apiHost)}/transfer`;
+}
 function authHeaders3(accessToken) {
   return {
     Accept: "application/json",
@@ -2882,8 +3516,7 @@ function authHeaders3(accessToken) {
 function formatResponseStatus(response, message) {
   return [response.status, response.statusText || message].filter(Boolean).join(" ");
 }
-async function getErrorMessage(response, action) {
-  const body = await response.json().catch(() => null);
+function buildErrorMessage(response, body, action) {
   const message = formatV3Error(body);
   if (response.status >= 500) {
     const status = formatResponseStatus(response, message);
@@ -2894,11 +3527,25 @@ async function getErrorMessage(response, action) {
 async function assertDomainResponse(response, action) {
   assertAuthorized(response);
   if (response.status === 403) {
-    throw new Error(DOMAINS_API_NOT_ENABLED);
+    throw new UserActionableError(DOMAINS_API_NOT_ENABLED);
   }
-  if (!response.ok) {
-    throw new Error(await getErrorMessage(response, action));
+  if (response.ok) {
+    return;
+  }
+  const body = await response.json().catch(() => null);
+  const message = buildErrorMessage(response, body, action);
+  const ownershipVerification = parseOwnershipVerification(body);
+  if (ownershipVerification) {
+    throw new DomainOwnershipVerificationError(message, ownershipVerification);
+  }
+  const boundProjectUuid = parseBoundProjectUuid(body);
+  if (boundProjectUuid) {
+    throw new DomainBoundToProjectError(message, boundProjectUuid);
   }
+  if (response.status >= 500) {
+    throw new Error(message);
+  }
+  throw new UserActionableError(message);
 }
 async function createDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
   const response = await fetch(domainsUrl(storeHash, projectUuid, apiHost), {
@@ -2922,6 +3569,18 @@ async function getDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
   const result = await response.json();
   return domainResponseSchema.parse(result).data;
 }
+async function findDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "GET",
+    headers: authHeaders3(accessToken)
+  });
+  if (response.status === 404) {
+    return null;
+  }
+  await assertDomainResponse(response, "Failed to fetch domain");
+  const result = await response.json();
+  return domainResponseSchema.parse(result).data;
+}
 async function listDomains(projectUuid, storeHash, accessToken, apiHost, filters = {}) {
   const search = new URLSearchParams();
   if (filters.domains && filters.domains.length > 0) {
@@ -2947,6 +3606,24 @@ async function deleteDomain(domain, projectUuid, storeHash, accessToken, apiHost
   });
   await assertDomainResponse(response, `Failed to remove domain: ${response.statusText}`);
 }
+async function claimDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainClaimUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "POST",
+    headers: authHeaders3(accessToken)
+  });
+  await assertDomainResponse(response, "Failed to claim domain");
+}
+async function transferDomain(domain, projectUuid, newProjectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainTransferUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "POST",
+    headers: {
+      ...authHeaders3(accessToken),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ new_project_uuid: newProjectUuid })
+  });
+  await assertDomainResponse(response, "Failed to transfer domain");
+}
 
 // src/cli/commands/domains.ts
 var WAIT_INTERVAL_MS = 5e3;
@@ -2967,21 +3644,58 @@ var STATUS_LABELS = {
 var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 function resolveDomainCommandContext(options) {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   const projectUuid = resolveProjectUuid(options);
   return {
     projectUuid,
     storeHash,
     accessToken,
-    apiHost: options.apiHost
+    apiHost
   };
 }
+async function resolveDestinationProject(domain, context, toProjectUuid) {
+  if (toProjectUuid) {
+    if (toProjectUuid === context.projectUuid) {
+      throw new UserActionableError("The destination project must differ from the source project.");
+    }
+    return toProjectUuid;
+  }
+  consola.start("Fetching projects...");
+  const projects = await fetchProjects(context.storeHash, context.accessToken, context.apiHost);
+  consola.success("Projects fetched.");
+  const destinations = projects.filter((project2) => project2.uuid !== context.projectUuid);
+  if (destinations.length === 0) {
+    throw new UserActionableError(
+      "No other projects to transfer to. Create another project with `catalyst project create` first."
+    );
+  }
+  return select6({
+    message: `Select the project to transfer ${domain} to (Press <enter> to select).`,
+    choices: destinations.map((project2) => ({
+      name: project2.name,
+      value: project2.uuid,
+      description: project2.uuid
+    }))
+  });
+}
 function formatDomainStatus(status) {
-  return colorize7(STATUS_COLORS[status], STATUS_LABELS[status]);
+  return colorize9(STATUS_COLORS[status], STATUS_LABELS[status]);
 }
 function formatDomain(domain) {
   return `${domain.domain} ${formatDomainStatus(domain.verification_status)}`;
 }
+function formatOwnershipVerification(record) {
+  const lines = [
+    "Add this DNS record to verify ownership:",
+    `  Type:  ${record.type}`,
+    `  Name:  ${record.name}`
+  ];
+  if (record.value) {
+    lines.push(`  Value: ${record.value}`);
+  }
+  return lines.join("\n");
+}
 async function waitForDomainVerification({
   domain,
   projectUuid,
@@ -2999,7 +3713,7 @@ async function waitForDomainVerification({
   }
   return current;
 }
-var add = new Command6("add").configureHelp({ showGlobalOptions: true }).description("Add a custom domain to the current Native Hosting project.").argument("<domain>", "Custom domain to add.").addHelpText(
+var add = new Command7("add").configureHelp({ showGlobalOptions: true }).description("Add a custom domain to the current Native Hosting project.").argument("<domain>", "Custom domain to add.").addHelpText(
   "after",
   `
 Examples:
@@ -3011,13 +3725,35 @@ Examples:
   const context = resolveDomainCommandContext(options);
   await getTelemetry().identify(context.storeHash);
   consola.start(`Adding domain ${domain}...`);
-  let result = await createDomain(
-    domain,
-    context.projectUuid,
-    context.storeHash,
-    context.accessToken,
-    context.apiHost
-  );
+  let result;
+  try {
+    result = await createDomain(
+      domain,
+      context.projectUuid,
+      context.storeHash,
+      context.accessToken,
+      context.apiHost
+    );
+  } catch (error) {
+    if (error instanceof DomainOwnershipVerificationError) {
+      consola.warn(`${domain} is already in use on another store.`);
+      consola.log(formatOwnershipVerification(error.ownershipVerification));
+      consola.info("Once the record is live, claim it with:");
+      consola.log(`  catalyst domains claim ${domain}`);
+      process.exit(1);
+      return;
+    }
+    if (error instanceof DomainBoundToProjectError) {
+      consola.warn(`${domain} is already bound to another project in this store.`);
+      consola.info("To move it to this project, run:");
+      consola.log(
+        `  catalyst domains transfer ${domain} --project-uuid ${error.projectUuid} --to-project-uuid ${context.projectUuid}`
+      );
+      process.exit(1);
+      return;
+    }
+    throw error;
+  }
   consola.success(`Domain ${result.domain} added.`);
   if (options.wait && result.verification_status === "pending") {
     consola.start(`Waiting for ${result.domain} to verify...`);
@@ -3026,7 +3762,7 @@ Examples:
   consola.log(formatDomain(result));
   process.exit(0);
 });
-var list = new Command6("list").configureHelp({ showGlobalOptions: true }).description("List custom domains for the current Native Hosting project.").addHelpText(
+var list = new Command7("list").configureHelp({ showGlobalOptions: true }).description("List custom domains for the current Native Hosting project.").addHelpText(
   "after",
   `
 Examples:
@@ -3061,7 +3797,7 @@ Examples:
   result.forEach((item) => consola.log(formatDomain(item)));
   process.exit(0);
 });
-var showStatus = new Command6("status").configureHelp({ showGlobalOptions: true }).description("Show the status of a custom domain on the current Native Hosting project.").argument("<domain>", "Custom domain to check.").addHelpText(
+var showStatus = new Command7("status").configureHelp({ showGlobalOptions: true }).description("Show the status of a custom domain on the current Native Hosting project.").argument("<domain>", "Custom domain to check.").addHelpText(
   "after",
   `
 Examples:
@@ -3088,7 +3824,143 @@ Examples:
   consola.log(formatDomain(result));
   process.exit(0);
 });
-var remove = new Command6("remove").configureHelp({ showGlobalOptions: true }).description("Remove a custom domain from the current Native Hosting project.").argument("<domain>", "Custom domain to remove.").addHelpText(
+var claim = new Command7("claim").configureHelp({ showGlobalOptions: true }).description("Claim a custom domain that is currently in use on another store.").argument("<domain>", "Custom domain to claim.").addHelpText(
+  "after",
+  `
+Claiming requires publishing the ownership-verification TXT record returned when
+you try to add a domain that is already in use on another store. Publish the
+record with your DNS provider, then run this command to complete the claim.
+
+Examples:
+  $ catalyst domains claim www.example.com
+
+  # Wait until the claimed domain leaves pending verification
+  $ catalyst domains claim www.example.com --wait`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--wait", "Poll until domain verification completes or times out.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Claiming domain ${domain}...`);
+  try {
+    await claimDomain(
+      domain,
+      context.projectUuid,
+      context.storeHash,
+      context.accessToken,
+      context.apiHost
+    );
+  } catch (error) {
+    if (error instanceof DomainOwnershipVerificationError) {
+      consola.warn(`Ownership of ${domain} could not be verified yet.`);
+      consola.log(formatOwnershipVerification(error.ownershipVerification));
+      consola.info("Once the record is live, run the claim again:");
+      consola.log(`  catalyst domains claim ${domain}`);
+      process.exit(1);
+      return;
+    }
+    throw error;
+  }
+  consola.success(`Domain ${domain} claimed.`);
+  let result = await getDomain(
+    domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  if (options.wait && result.verification_status === "pending") {
+    consola.start(`Waiting for ${result.domain} to verify...`);
+    result = await waitForDomainVerification({ domain: result.domain, ...context });
+  }
+  consola.log(formatDomain(result));
+  process.exit(0);
+});
+var transfer = new Command7("transfer").configureHelp({ showGlobalOptions: true }).description("Transfer a custom domain to another project in the same store.").argument("<domain>", "Custom domain to transfer.").addHelpText(
+  "after",
+  `
+The domain is transferred from the current project to the destination project.
+Omit --to-project-uuid to pick the destination from a list of your projects.
+
+Examples:
+  # Pick the destination project interactively
+  $ catalyst domains transfer www.example.com
+
+  # Transfer to a specific project
+  $ catalyst domains transfer www.example.com --to-project-uuid <uuid>`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--to-project-uuid <uuid>", "Destination project UUID. Prompts to choose one if omitted.").option("--wait", "Poll until domain verification completes or times out.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Checking ${domain} on the current project...`);
+  const owned = await findDomain(
+    domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  if (!owned) {
+    consola.start(`Locating the project that owns ${domain}...`);
+    const projects = await fetchProjects(context.storeHash, context.accessToken, context.apiHost);
+    const candidates = projects.filter((project2) => project2.uuid !== context.projectUuid);
+    const matches = await Promise.all(
+      candidates.map(async (project2) => ({
+        project: project2,
+        found: await findDomain(
+          domain,
+          project2.uuid,
+          context.storeHash,
+          context.accessToken,
+          context.apiHost
+        )
+      }))
+    );
+    const owner = matches.find((match) => match.found)?.project;
+    if (!owner) {
+      throw new UserActionableError(
+        `${domain} isn't on any project in this store. If it's in use on another store, claim it with \`catalyst domains claim ${domain}\`; otherwise double-check the domain name.`
+      );
+    }
+    const toSuffix = options.toProjectUuid ? ` --to-project-uuid ${options.toProjectUuid}` : "";
+    consola.warn(
+      `${domain} is on project "${owner.name}" (${owner.uuid}), not the current project.`
+    );
+    consola.info("Re-run the transfer from that project:");
+    consola.log(`  catalyst domains transfer ${domain} --project-uuid ${owner.uuid}${toSuffix}`);
+    process.exit(1);
+    return;
+  }
+  consola.success(`${domain} found on the current project.`);
+  const newProjectUuid = await resolveDestinationProject(domain, context, options.toProjectUuid);
+  consola.start(`Transferring domain ${domain}...`);
+  await transferDomain(
+    domain,
+    context.projectUuid,
+    newProjectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  consola.success(`Domain ${domain} transferred.`);
+  let result = await getDomain(
+    domain,
+    newProjectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  if (options.wait && result.verification_status === "pending") {
+    consola.start(`Waiting for ${result.domain} to verify...`);
+    result = await waitForDomainVerification({
+      domain: result.domain,
+      projectUuid: newProjectUuid,
+      storeHash: context.storeHash,
+      accessToken: context.accessToken,
+      apiHost: context.apiHost
+    });
+  }
+  consola.log(formatDomain(result));
+  process.exit(0);
+});
+var remove = new Command7("remove").configureHelp({ showGlobalOptions: true }).description("Remove a custom domain from the current Native Hosting project.").argument("<domain>", "Custom domain to remove.").addHelpText(
   "after",
   `
 Examples:
@@ -3129,12 +4001,12 @@ Examples:
   consola.success(`Domain ${current.domain} removed.`);
   process.exit(0);
 });
-var domains = new Command6("domains").configureHelp({ showGlobalOptions: true }).description("Manage custom domains for the current Native Hosting project.").addCommand(add).addCommand(list).addCommand(showStatus).addCommand(remove);
+var domains = new Command7("domains").configureHelp({ showGlobalOptions: true }).description("Manage custom domains for the current Native Hosting project.").addCommand(add).addCommand(list).addCommand(showStatus).addCommand(claim).addCommand(transfer).addCommand(remove);
 
 // src/cli/commands/env.ts
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 var MASK = "\u2022\u2022\u2022\u2022\u2022\u2022";
-var add2 = new Command7("add").configureHelp({ showGlobalOptions: true }).description(
+var add2 = new Command8("add").configureHelp({ showGlobalOptions: true }).description(
   "Add or update one or more deployment environment variables. Stored in .bigcommerce/project.json and sent as secrets on every `catalyst deploy`."
 ).argument("<vars...>", "One or more environment variables in KEY=VALUE format.").addHelpText(
   "after",
@@ -3156,7 +4028,7 @@ Example:
   keys.forEach((key) => consola.log(`  ${key}=${MASK}`));
   process.exit(0);
 });
-var remove2 = new Command7("remove").configureHelp({ showGlobalOptions: true }).description("Remove one or more stored deployment environment variables.").argument("<keys...>", "One or more environment variable names to remove.").addHelpText(
+var remove2 = new Command8("remove").configureHelp({ showGlobalOptions: true }).description("Remove one or more stored deployment environment variables.").argument("<keys...>", "One or more environment variable names to remove.").addHelpText(
   "after",
   `
 Example:
@@ -3182,7 +4054,7 @@ Example:
   }
   process.exit(0);
 });
-var list2 = new Command7("list").configureHelp({ showGlobalOptions: true }).description("List stored deployment environment variables (values are masked).").addHelpText(
+var list2 = new Command8("list").configureHelp({ showGlobalOptions: true }).description("List stored deployment environment variables (values are masked).").addHelpText(
   "after",
   `
 Example:
@@ -3199,14 +4071,14 @@ Example:
   keys.forEach((key) => consola.log(`${key}=${MASK}`));
   process.exit(0);
 });
-var env = new Command7("env").configureHelp({ showGlobalOptions: true }).description(
+var env = new Command8("env").configureHelp({ showGlobalOptions: true }).description(
   "Manage persistent deployment environment variables. These are sent as secrets on every `catalyst deploy`, so you no longer need to pass `--secret` each time."
 ).addCommand(add2).addCommand(remove2).addCommand(list2);
 
 // src/cli/commands/logs.ts
-import { Command as Command8, InvalidArgumentError as InvalidArgumentError3, Option as Option8 } from "commander";
-import { colorize as colorize8 } from "consola/utils";
-import { z as z14 } from "zod";
+import { Command as Command9, InvalidArgumentError as InvalidArgumentError4, Option as Option8 } from "commander";
+import { colorize as colorize10 } from "consola/utils";
+import { z as z16 } from "zod";
 var telemetry = new Telemetry();
 var DEFAULT_CONNECTION_TTL_MS = 1 * 60 * 1e3;
 var MAX_RETRIES = 5;
@@ -3217,23 +4089,23 @@ var LEVEL_COLORS2 = {
   ERROR: "red",
   DEBUG: "gray"
 };
-var LogEventSchema = z14.object({
-  uuid: z14.string(),
-  project_uuid: z14.string(),
-  request: z14.object({
-    method: z14.string(),
-    url: z14.string(),
-    status_code: z14.number()
+var LogEventSchema = z16.object({
+  uuid: z16.string(),
+  project_uuid: z16.string(),
+  request: z16.object({
+    method: z16.string(),
+    url: z16.string(),
+    status_code: z16.number()
   }),
-  logs: z14.array(
-    z14.object({
-      timestamp: z14.string(),
-      level: z14.string(),
-      messages: z14.array(z14.unknown())
+  logs: z16.array(
+    z16.object({
+      timestamp: z16.string(),
+      level: z16.string(),
+      messages: z16.array(z16.unknown())
     })
   ),
-  exceptions: z14.array(z14.unknown()),
-  timestamp: z14.string()
+  exceptions: z16.array(z16.unknown()),
+  timestamp: z16.string()
 }).loose();
 var StreamError = class extends Error {
   constructor(message, fatal) {
@@ -3247,7 +4119,7 @@ var formatLogEvent = (event, format) => {
   logEntries.forEach((entry) => {
     const msg = formatMessages(entry.messages);
     const level = entry.level.toUpperCase();
-    const coloredLevel = colorize8(LEVEL_COLORS2[level] ?? "white", level);
+    const coloredLevel = colorize10(LEVEL_COLORS2[level] ?? "white", level);
     switch (format) {
       case "short":
         consola.log(msg);
@@ -3318,10 +4190,8 @@ var openLogStream = async (projectUuid, storeHash, accessToken, apiHost) => {
     throw new StreamError(new UnauthorizedError().message, true);
   }
   if (!response.ok) {
-    throw new StreamError(
-      `Failed to open log stream: ${response.status} ${response.statusText}`,
-      isFatalStatusCode(response.status)
-    );
+    const error = await httpError(response, "Failed to open log stream");
+    throw new StreamError(error.message, isFatalStatusCode(response.status));
   }
   const reader = response.body?.getReader();
   if (!reader) {
@@ -3390,7 +4260,7 @@ var tailLogs = async (projectUuid, storeHash, accessToken, apiHost, format, conn
     }
   }
 };
-var tail = new Command8("tail").configureHelp({ showGlobalOptions: true }).description("Tail live logs from your deployed application.").addHelpText(
+var tail = new Command9("tail").configureHelp({ showGlobalOptions: true }).description("Tail live logs from your deployed application.").addHelpText(
   "after",
   `
 Examples:
@@ -3406,10 +4276,11 @@ Examples:
 ).action(async (options) => {
   try {
     const config2 = getProjectConfig();
+    const apiHost = resolveApiHost(options, config2);
     const { storeHash, accessToken } = resolveCredentials(options, config2);
     await telemetry.identify(storeHash);
     const projectUuid = resolveProjectUuid(options);
-    await tailLogs(projectUuid, storeHash, accessToken, options.apiHost, options.format);
+    await tailLogs(projectUuid, storeHash, accessToken, apiHost, options.format);
   } catch (error) {
     consola.error(error);
     process.exit(1);
@@ -3418,11 +4289,11 @@ Examples:
 var parseIntInRange = (flag, min, max) => (value) => {
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
-    throw new InvalidArgumentError3(`${flag} must be an integer between ${min} and ${max}.`);
+    throw new InvalidArgumentError4(`${flag} must be an integer between ${min} and ${max}.`);
   }
   return parsed;
 };
-var query = new Command8("query").configureHelp({ showGlobalOptions: true }).description("Query historical logs from your deployed application.").addHelpText(
+var query = new Command9("query").configureHelp({ showGlobalOptions: true }).description("Query historical logs from your deployed application.").addHelpText(
   "after",
   `
 Specify a time window with \`--since\` (relative to now) or \`--start\`/\`--end\`
@@ -3465,11 +4336,12 @@ Examples:
 ).action(async (options) => {
   try {
     const config2 = getProjectConfig();
+    const apiHost = resolveApiHost(options, config2);
     const { storeHash, accessToken } = resolveCredentials(options, config2);
     await telemetry.identify(storeHash);
     const projectUuid = resolveProjectUuid(options);
     const { start: start2, end } = resolveTimeWindow(options);
-    const result = await queryLogs(projectUuid, storeHash, accessToken, options.apiHost, {
+    const result = await queryLogs(projectUuid, storeHash, accessToken, apiHost, {
       start: start2,
       end,
       method: options.method,
@@ -3508,12 +4380,12 @@ Examples:
     process.exit(1);
   }
 });
-var logs = new Command8("logs").configureHelp({ showGlobalOptions: true }).description("View logs from your deployed application.").addCommand(tail, { isDefault: true }).addCommand(query);
+var logs = new Command9("logs").configureHelp({ showGlobalOptions: true }).description("View logs from your deployed application.").addCommand(tail, { isDefault: true }).addCommand(query);
 
 // src/cli/commands/project.ts
-import { confirm as confirm5, input as input4, select as select5 } from "@inquirer/prompts";
-import { Command as Command9 } from "commander";
-import { colorize as colorize9 } from "consola/utils";
+import { confirm as confirm5, input as input5, select as select7 } from "@inquirer/prompts";
+import { Command as Command10 } from "commander";
+import { colorize as colorize11 } from "consola/utils";
 async function offerCommerceHostingSetup(projectUuid, credentials) {
   const projectDir = process.cwd();
   if (getProjectState().isTransformed) {
@@ -3532,19 +4404,21 @@ async function offerCommerceHostingSetup(projectUuid, credentials) {
     accessToken: credentials?.accessToken
   });
   consola.success("Commerce Hosting setup complete.");
-  await installDependencies(projectDir);
+  const packageManager = await detectProjectPackageManager(projectDir);
+  await installDependencies(projectDir, packageManager);
 }
-var list3 = new Command9("list").configureHelp({ showGlobalOptions: true }).description("List BigCommerce infrastructure projects for your store.").addHelpText(
+var list3 = new Command10("list").configureHelp({ showGlobalOptions: true }).description("List BigCommerce infrastructure projects for your store.").addHelpText(
   "after",
   `
 Example:
   $ catalyst project list`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
   consola.start("Fetching projects...");
-  const projects = await fetchProjects(storeHash, accessToken, options.apiHost);
+  const projects = await fetchProjects(storeHash, accessToken, apiHost);
   consola.success("Projects fetched.");
   if (projects.length === 0) {
     consola.info("No projects found.");
@@ -3553,16 +4427,16 @@ Example:
   }
   const linkedProjectUuid = config2.get("projectUuid");
   const projectList = projects.map((p) => {
-    const marker = p.uuid === linkedProjectUuid ? ` ${colorize9("green", "[linked]")}` : "";
+    const marker = p.uuid === linkedProjectUuid ? ` ${colorize11("green", "[linked]")}` : "";
     const hostnames = p.deployment_hostnames.length === 0 ? ["  (not deployed)"] : p.deployment_hostnames.map(
-      (hostname) => `  ${colorize9("blue", `https://${hostname}`)}`
+      (hostname) => `  ${colorize11("blue", `https://${hostname}`)}`
     );
     return [`${p.name} (${p.uuid})${marker}`, ...hostnames].join("\n");
   });
   consola.log(projectList.join("\n\n"));
   process.exit(0);
 });
-var create2 = new Command9("create").configureHelp({ showGlobalOptions: true }).description(
+var create3 = new Command10("create").configureHelp({ showGlobalOptions: true }).description(
   "Create a new BigCommerce infrastructure project and link it to your local Catalyst project. Walks you through logging in if you are not authenticated yet."
 ).addHelpText(
   "after",
@@ -3571,6 +4445,7 @@ Example:
   $ catalyst project create`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   let storeHash = options.storeHash ?? config2.get("storeHash");
   let accessToken = options.accessToken ?? config2.get("accessToken");
   if (!storeHash || !accessToken) {
@@ -3578,7 +4453,7 @@ Example:
       "You're not logged in yet. Let's get you authenticated before creating a project."
     );
     try {
-      const credentials = await login(options.loginUrl, options.apiHost);
+      const credentials = await login(options.loginUrl, apiHost);
       storeHash = credentials.storeHash;
       accessToken = credentials.accessToken;
       config2.set("storeHash", storeHash);
@@ -3596,8 +4471,8 @@ Example:
     }
   }
   await getTelemetry().identify(storeHash);
-  const newProjectName = await input4({ message: "Enter a name for the new project:" });
-  const data = await createProject(newProjectName, storeHash, accessToken, options.apiHost);
+  const newProjectName = await input5({ message: "Enter a name for the new project:" });
+  const data = await createProject(newProjectName, storeHash, accessToken, apiHost);
   consola.success(`Project "${data.name}" created successfully.`);
   consola.start("Writing project UUID to .bigcommerce/project.json...");
   config2.set("projectUuid", data.uuid);
@@ -3606,7 +4481,7 @@ Example:
   consola.success("Project UUID written to .bigcommerce/project.json.");
   process.exit(0);
 });
-var link2 = new Command9("link").configureHelp({ showGlobalOptions: true }).description(
+var link2 = new Command10("link").configureHelp({ showGlobalOptions: true }).description(
   "Link your local Catalyst project to a BigCommerce infrastructure project. You can provide a project UUID directly, or fetch and select from available projects using your store credentials."
 ).addHelpText(
   "after",
@@ -3619,6 +4494,7 @@ Examples:
   $ catalyst project link --project-uuid <UUID>`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const writeProjectConfig = (uuid, credentials) => {
     consola.start("Writing project UUID to .bigcommerce/project.json...");
     config2.set("projectUuid", uuid);
@@ -3639,7 +4515,7 @@ Examples:
   let selected;
   try {
     selected = await selectOrCreateInfrastructureProject(
-      { storeHash, accessToken, apiHost: options.apiHost },
+      { storeHash, accessToken, apiHost },
       config2.get("projectUuid")
     );
   } catch (error) {
@@ -3656,7 +4532,7 @@ Examples:
   await offerCommerceHostingSetup(selected.uuid, { storeHash, accessToken });
   process.exit(0);
 });
-var del = new Command9("delete").configureHelp({ showGlobalOptions: true }).description(
+var del = new Command10("delete").configureHelp({ showGlobalOptions: true }).description(
   "Permanently delete a BigCommerce infrastructure project. This action is irreversible."
 ).addHelpText(
   "after",
@@ -3672,13 +4548,14 @@ Examples:
   $ catalyst project delete --project-uuid <UUID> --force`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--force", "Skip the confirmation prompt before deleting.").action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
   let targetUuid = options.projectUuid;
   let targetName;
   if (!targetUuid) {
     consola.start("Fetching projects...");
-    const projects = await fetchProjects(storeHash, accessToken, options.apiHost);
+    const projects = await fetchProjects(storeHash, accessToken, apiHost);
     consola.success("Projects fetched.");
     if (projects.length === 0) {
       consola.info("No projects found.");
@@ -3686,11 +4563,11 @@ Examples:
       return;
     }
     const linkedProjectUuid = config2.get("projectUuid");
-    const selected = await select5({
+    const selected = await select7({
       message: "Select a project to delete (Press <enter> to select).",
       choices: [
         ...projects.map((p) => ({
-          name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize9("green", "[linked]")}` : p.name,
+          name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize11("green", "[linked]")}` : p.name,
           value: p.uuid,
           description: p.uuid
         })),
@@ -3722,7 +4599,7 @@ Examples:
     }
   }
   consola.start(`Deleting project ${targetUuid}...`);
-  await deleteProject(targetUuid, storeHash, accessToken, options.apiHost);
+  await deleteProject(targetUuid, storeHash, accessToken, apiHost);
   consola.success(`Project ${targetUuid} deleted.`);
   if (config2.get("projectUuid") === targetUuid) {
     config2.delete("projectUuid");
@@ -3730,14 +4607,14 @@ Examples:
   }
   process.exit(0);
 });
-var project = new Command9("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure project.").addCommand(create2).addCommand(list3).addCommand(link2).addCommand(del);
+var project = new Command10("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure project.").addCommand(create3).addCommand(list3).addCommand(link2).addCommand(del);
 
 // src/cli/commands/start.ts
-import { Command as Command10 } from "commander";
-import { execa as execa2 } from "execa";
-import { existsSync as existsSync3, lstatSync, symlinkSync } from "fs";
+import { Command as Command11 } from "commander";
+import { execa as execa3 } from "execa";
+import { existsSync as existsSync6, lstatSync, symlinkSync } from "fs";
 import { join as join13, relative } from "path";
-var start = new Command10("start").configureHelp({ showGlobalOptions: true }).description(
+var start = new Command11("start").configureHelp({ showGlobalOptions: true }).description(
   "Start a local preview of your Catalyst storefront using the OpenNext Cloudflare adapter."
 ).addHelpText(
   "after",
@@ -3748,7 +4625,7 @@ Example:
   const state = getProjectState();
   if (!state.isTransformed) {
     consola.info("Project is not set up for Commerce Hosting \u2014 running `next start`.");
-    await execa2("pnpm", ["exec", "next", "start"], {
+    await execa3("pnpm", ["exec", "next", "start"], {
       stdio: "inherit",
       cwd: process.cwd()
     });
@@ -3756,8 +4633,8 @@ Example:
   }
   const envLocal = join13(process.cwd(), ".env.local");
   const devVars = join13(process.cwd(), ".bigcommerce", ".dev.vars");
-  if (existsSync3(envLocal)) {
-    if (!existsSync3(devVars)) {
+  if (existsSync6(envLocal)) {
+    if (!existsSync6(devVars)) {
       const target = relative(join13(process.cwd(), ".bigcommerce"), envLocal);
       symlinkSync(target, devVars);
       consola.success("Symlinked .bigcommerce/.dev.vars \u2192 .env.local");
@@ -3771,7 +4648,7 @@ Example:
       "No .env.local file found. The preview server may fail without environment variables.\nCreate a .env.local file in your project root with the required variables."
     );
   }
-  await execa2(
+  await execa3(
     "pnpm",
     [
       "exec",
@@ -3788,11 +4665,11 @@ Example:
 });
 
 // src/cli/commands/telemetry.ts
-import { Argument, Command as Command11, Option as Option9 } from "commander";
-import { colorize as colorize10 } from "consola/utils";
+import { Argument, Command as Command12, Option as Option9 } from "commander";
+import { colorize as colorize12 } from "consola/utils";
 var telemetryService = getTelemetry();
 var isEnabled = telemetryService.isEnabled();
-var telemetry2 = new Command11("telemetry").configureHelp({ showGlobalOptions: true }).description(
+var telemetry2 = new Command12("telemetry").configureHelp({ showGlobalOptions: true }).description(
   "View or change CLI telemetry collection status. Enabling telemetry helps BigCommerce support diagnose and troubleshoot errors you encounter when using the CLI."
 ).addHelpText(
   "after",
@@ -3823,7 +4700,7 @@ Examples:
     consola.info("Catalyst CLI Telemetry\n");
   }
   consola.info(
-    `Status: ${colorize10("bold", isEnabled ? colorize10("green", "Enabled") : colorize10("red", "Disabled"))}`
+    `Status: ${colorize12("bold", isEnabled ? colorize12("green", "Enabled") : colorize12("red", "Disabled"))}`
   );
   if (!isEnabled) {
     consola.info(
@@ -3833,9 +4710,9 @@ Examples:
 });
 
 // src/cli/commands/upgrade.ts
-import { Command as Command12, Option as Option10 } from "@commander-js/extra-typings";
+import { Command as Command13, Option as Option10 } from "@commander-js/extra-typings";
 import { confirm as confirm6 } from "@inquirer/prompts";
-import { execa as execa3 } from "execa";
+import { execa as execa4 } from "execa";
 import {
   access as access2,
   copyFile as copyFile2,
@@ -3849,13 +4726,13 @@ import {
   writeFile as writeFile2
 } from "fs/promises";
 import { homedir, tmpdir } from "os";
-import { dirname as dirname4, join as join14, relative as relative2 } from "path";
+import { dirname as dirname5, join as join14, relative as relative2 } from "path";
 import yoctoSpinner4 from "yocto-spinner";
-import { z as z15 } from "zod";
-var CorePackageJson = z15.object({
-  name: z15.string().optional(),
-  version: z15.string(),
-  catalyst: z15.object({ version: z15.string(), ref: z15.string() }).optional()
+import { z as z17 } from "zod";
+var CorePackageJson = z17.object({
+  name: z17.string().optional(),
+  version: z17.string(),
+  catalyst: z17.object({ version: z17.string(), ref: z17.string() }).optional()
 });
 var DEFAULT_REPOSITORY = "bigcommerce/catalyst";
 var MOVING_TAGS = /* @__PURE__ */ new Set(["latest", "canary", "alpha"]);
@@ -3898,7 +4775,7 @@ async function isBinary(p) {
   return buf.subarray(0, 8e3).includes(0);
 }
 async function copyInto(src, dest) {
-  await mkdir(dirname4(dest), { recursive: true });
+  await mkdir(dirname5(dest), { recursive: true });
   await copyFile2(src, dest);
 }
 function parseRef(ref) {
@@ -3912,7 +4789,7 @@ async function readResolvedVersion(coreDir) {
   return pkg.catalyst?.version ?? pkg.version;
 }
 async function mergeFile(oursPath, basePath, theirsPath) {
-  const merged = await execa3(
+  const merged = await execa4(
     "git",
     [
       "merge-file",
@@ -3995,7 +4872,7 @@ async function mergeCorePerFile(baseDir, theirsDir, catalystRoot, emptyFile) {
 }
 async function gitSupportsMergeTree() {
   try {
-    const { stdout } = await execa3("git", ["--version"]);
+    const { stdout } = await execa4("git", ["--version"]);
     const match = /(\d+)\.(\d+)/.exec(stdout);
     if (!match) return false;
     const [major, minor] = [Number(match[1]), Number(match[2])];
@@ -4013,8 +4890,8 @@ async function resolveStrategy(strategy) {
 async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
   const scratch = await mkdtemp(join14(tmpdir(), "catalyst-merge-"));
   try {
-    await execa3("git", ["init", "-q", scratch]);
-    await execa3("git", ["config", "core.autocrlf", "false"], {
+    await execa4("git", ["init", "-q", scratch]);
+    await execa4("git", ["config", "core.autocrlf", "false"], {
       env: { ...process.env, GIT_DIR: join14(scratch, ".git") }
     });
     const env2 = {
@@ -4031,10 +4908,10 @@ async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
         GIT_WORK_TREE: workTree,
         GIT_INDEX_FILE: join14(scratch, `index.${tag}`)
       };
-      await execa3("git", ["add", "-A"], { env: sideEnv });
-      return (await execa3("git", ["write-tree"], { env: sideEnv })).stdout.trim();
+      await execa4("git", ["add", "-A"], { env: sideEnv });
+      return (await execa4("git", ["write-tree"], { env: sideEnv })).stdout.trim();
     };
-    const commitTree = (tree, parent) => execa3("git", ["commit-tree", tree, "-m", "x", ...parent ? ["-p", parent] : []], {
+    const commitTree = (tree, parent) => execa4("git", ["commit-tree", tree, "-m", "x", ...parent ? ["-p", parent] : []], {
       env: env2
     }).then((r) => r.stdout.trim());
     const baseTree = await writeTree(baseDir, "base");
@@ -4046,10 +4923,10 @@ async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
       commitTree(theirsTree, baseCommit)
     ]);
     await Promise.all([
-      execa3("git", ["branch", "ours", oursCommit], { env: env2 }),
-      execa3("git", ["branch", "theirs", theirsCommit], { env: env2 })
+      execa4("git", ["branch", "ours", oursCommit], { env: env2 }),
+      execa4("git", ["branch", "theirs", theirsCommit], { env: env2 })
     ]);
-    const merge = await execa3(
+    const merge = await execa4(
       "git",
       [
         "merge-tree",
@@ -4075,9 +4952,9 @@ async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
       GIT_WORK_TREE: catalystRoot,
       GIT_INDEX_FILE: join14(scratch, "index.out")
     };
-    await execa3("git", ["read-tree", mergedTree], { env: outEnv });
-    await execa3("git", ["checkout-index", "-a", "-f"], { env: outEnv });
-    const diff = await execa3(
+    await execa4("git", ["read-tree", mergedTree], { env: outEnv });
+    await execa4("git", ["checkout-index", "-a", "-f"], { env: outEnv });
+    const diff = await execa4(
       "git",
       ["diff", "-z", "--no-renames", "--name-status", oursTree, mergedTree],
       { env: env2 }
@@ -4112,19 +4989,19 @@ async function applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stam
   if (stampedPkg) clean.push(toRepoPath(pkgRel));
   const toStage = [...new Set(clean)].filter((path) => !conflictedRepoPaths.has(path));
   if (toStage.length) {
-    await execa3("git", ["add", "-A", "--", ...toStage], { cwd: gitRoot });
+    await execa4("git", ["add", "-A", "--", ...toStage], { cwd: gitRoot });
   }
   if (stillConflicted.length === 0) return;
   const OID = /^[0-9a-f]{40,64}$/;
-  const gitFormat = (await execa3("git", ["rev-parse", "--show-object-format"], { cwd: gitRoot, reject: false })).stdout.trim();
+  const gitFormat = (await execa4("git", ["rev-parse", "--show-object-format"], { cwd: gitRoot, reject: false })).stdout.trim();
   const NULL_OID = gitFormat === "sha256" ? "0".repeat(64) : "0".repeat(40);
   const hashBlob = async (file) => {
     if (!await pathExists(file)) return null;
-    const oid = (await execa3("git", ["hash-object", "-w", "--", file], { cwd: gitRoot })).stdout.trim();
+    const oid = (await execa4("git", ["hash-object", "-w", "--", file], { cwd: gitRoot })).stdout.trim();
     return OID.test(oid) ? oid : null;
   };
   const headEntry = async (repoPath) => {
-    const { stdout } = await execa3("git", ["ls-tree", "HEAD", "--", repoPath], {
+    const { stdout } = await execa4("git", ["ls-tree", "HEAD", "--", repoPath], {
       cwd: gitRoot,
       reject: false
     });
@@ -4147,7 +5024,7 @@ async function applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stam
       ].join("\n");
     })
   );
-  await execa3("git", ["update-index", "--index-info"], {
+  await execa4("git", ["update-index", "--index-info"], {
     cwd: gitRoot,
     input: `${records.join("\n")}
 `
@@ -4156,7 +5033,7 @@ async function applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stam
 async function resolveProject2(cwd) {
   let gitRoot;
   try {
-    gitRoot = (await execa3("git", ["rev-parse", "--show-toplevel"], { cwd })).stdout.trim();
+    gitRoot = (await execa4("git", ["rev-parse", "--show-toplevel"], { cwd })).stdout.trim();
   } catch {
     return null;
   }
@@ -4212,7 +5089,7 @@ async function downloadCore(repository, ref, destDir, token) {
   const rawDir = `${destDir}.raw`;
   await writeFile2(tarballPath, Buffer.from(await res.arrayBuffer()));
   await mkdir(rawDir, { recursive: true });
-  await execa3("tar", ["-xzf", tarballPath, "-C", rawDir, "--strip-components=1"]);
+  await execa4("tar", ["-xzf", tarballPath, "-C", rawDir, "--strip-components=1"]);
   const coreDir = join14(rawDir, "core");
   const sourceDir = await pathExists(coreDir) ? coreDir : rawDir;
   await rename(sourceDir, destDir);
@@ -4261,7 +5138,7 @@ Resolve them, then: git add ${relDir} && git commit`
     consola.success("Staged all changes \u2014 review with `git diff --cached`, then commit.");
   }
 }
-var upgrade = new Command12("upgrade").configureHelp({ showGlobalOptions: true }).aliases([
+var upgrade = new Command13("upgrade").configureHelp({ showGlobalOptions: true }).aliases([
   "up",
   // These are hidden aliases
   "upgrayedd",
@@ -4329,7 +5206,7 @@ to raise the GitHub API rate limit.`
   }
   if (!options.dryRun) {
     const statusArgs = relDir === "." ? [] : ["--", relDir];
-    const status = await execa3("git", ["status", "--porcelain", ...statusArgs], {
+    const status = await execa4("git", ["status", "--porcelain", ...statusArgs], {
       cwd: gitRoot,
       reject: false
     });
@@ -4346,11 +5223,11 @@ to raise the GitHub API rate limit.`
   if (!project2.pkg.catalyst?.ref && !options.from && !options.dryRun) {
     const { version: baseVersion } = parseRef(baseRef);
     const rawPkg = await readFile2(pkgPath, "utf-8");
-    const parsedPkg = z15.record(z15.string(), z15.unknown()).parse(JSON.parse(rawPkg));
+    const parsedPkg = z17.record(z17.string(), z17.unknown()).parse(JSON.parse(rawPkg));
     parsedPkg.catalyst = { version: baseVersion, ref: baseRef };
     await writeFile2(pkgPath, `${JSON.stringify(parsedPkg, null, 2)}
 `);
-    await execa3("git", ["add", "--", pkgPath], { cwd: gitRoot });
+    await execa4("git", ["add", "--", pkgPath], { cwd: gitRoot });
     consola.success(`Added catalyst.ref \u2192 ${baseRef}`);
   }
   const token = process.env.GITHUB_TOKEN;
@@ -4384,7 +5261,7 @@ to raise the GitHub API rate limit.`
     const newRef = MOVING_TAGS.has(upstreamTagVersion) ? `${basePackage}@${resolvedVersion}` : upstreamRef;
     if (options.dryRun) {
       const diffSpinner = yoctoSpinner4().start("Generating diff...");
-      const diff = await execa3(
+      const diff = await execa4(
         "git",
         ["diff", "--no-index", "--binary", "--diff-algorithm=histogram", "base", "theirs"],
         { cwd: tmpDir, reject: false, stripFinalNewline: false }
@@ -4419,7 +5296,7 @@ to raise the GitHub API rate limit.`
     const patchedRaw = await readFile2(pkgPath, "utf-8");
     let stampedPkg = false;
     try {
-      const patchedPkg = z15.record(z15.string(), z15.unknown()).parse(JSON.parse(patchedRaw));
+      const patchedPkg = z17.record(z17.string(), z17.unknown()).parse(JSON.parse(patchedRaw));
       patchedPkg.catalyst = { version: resolvedVersion, ref: newRef };
       await writeFile2(pkgPath, `${JSON.stringify(patchedPkg, null, 2)}
 `);
@@ -4455,7 +5332,7 @@ to raise the GitHub API rate limit.`
         `Couldn't auto-stage the changes (${err instanceof Error ? err.message : String(err)}). Your files are merged on disk \u2014 run \`git add ${relDir}\` yourself.`
       );
     }
-    const gitVersion = await execa3("git", ["--version"]).then((r) => r.stdout.trim()).catch(() => "unknown");
+    const gitVersion = await execa4("git", ["--version"]).then((r) => r.stdout.trim()).catch(() => "unknown");
     await getTelemetry().track("upgrade", {
       strategy,
       gitVersion,
@@ -4473,8 +5350,8 @@ to raise the GitHub API rate limit.`
 });
 
 // src/cli/commands/version.ts
-import { Command as Command13 } from "commander";
-var version = new Command13("version").configureHelp({ showGlobalOptions: true }).description("Display detailed version information.").addHelpText(
+import { Command as Command14 } from "commander";
+var version = new Command14("version").configureHelp({ showGlobalOptions: true }).description("Display detailed version information.").addHelpText(
   "after",
   `
 Example:
@@ -4535,41 +5412,15 @@ var telemetryPostHook = async () => {
 };
 
 // src/cli/program.ts
-var defaultEnvPath = resolve(process.cwd(), ".env.local");
-if (existsSync4(defaultEnvPath)) {
-  config({ path: defaultEnvPath });
-}
 if (!process.env.CATALYST_STORE_HASH && process.env.BIGCOMMERCE_STORE_HASH) {
   process.env.CATALYST_STORE_HASH = process.env.BIGCOMMERCE_STORE_HASH;
 }
-var program = new Command14();
-consola.log(colorize11("cyanBright", `\u25E2 ${package_default.name} v${package_default.version}
+var program = new Command15();
+consola.log(colorize13("cyanBright", `\u25E2 ${package_default.name} v${package_default.version}
 `));
 program.name(package_default.name).version(package_default.version).summary("CLI tool for Catalyst development").description(
-  "CLI tool for Catalyst development.\n\nConfiguration priority: flags > env file (--env-path) > process.env > .env.local (auto-loaded from cwd) > .bigcommerce/project.json.\n\nCATALYST_STORE_HASH falls back to BIGCOMMERCE_STORE_HASH if unset.\n\nRun `catalyst <command> --help` for details on a specific command."
-).configureHelp({ showGlobalOptions: true }).addOption(
-  new Option11(
-    "--env-path <path>",
-    "Path to environment file to load (relative to current working directory)"
-    // We are using argParser, because commander loads in environment variables before executing hooks.
-  ).argParser((value) => {
-    if (value) {
-      const envFilePath = resolve(process.cwd(), value);
-      const result = config({
-        path: envFilePath,
-        override: true
-      });
-      if (result.error) {
-        const errCode = "code" in result.error && typeof result.error.code === "string" ? result.error.code : void 0;
-        const message = errCode === "ENOENT" ? `Env file not found: ${envFilePath}` : `Failed to load --env-path ${value}: ${result.error.message}`;
-        throw new Error(message);
-      }
-      consola.log(colorize11("cyanBright", `Loaded environment variables from ${envFilePath}
-`));
-    }
-    return value;
-  })
-).addCommand(version).addCommand(create).addCommand(start).addCommand(build).addCommand(deploy).addCommand(domains).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(upgrade).addCommand(telemetry2).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
+  "CLI tool for Catalyst development.\n\nConfiguration priority: flags > process.env > .bigcommerce/project.json. `build` and `deploy` additionally load env files (--env-path, or an auto-loaded .env.local/.env) for the build.\n\nCATALYST_STORE_HASH falls back to BIGCOMMERCE_STORE_HASH if unset.\n\nRun `catalyst <command> --help` for details on a specific command."
+).configureHelp({ showGlobalOptions: true }).addCommand(version).addCommand(create2).addCommand(start).addCommand(build).addCommand(deploy).addCommand(domains).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(upgrade).addCommand(telemetry2).addCommand(debug).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
 
 // src/cli/index.ts
 var handleFatalError = async (error) => {
@@ -4586,7 +5437,7 @@ var handleFatalError = async (error) => {
     await telemetry3.analytics.closeAndFlush();
   } catch {
   }
-  if (error instanceof UnauthorizedError) {
+  if (error instanceof UserActionableError) {
     consola.error(errorMessage);
     process.exit(1);
   }