@bigcommerce/catalyst 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/cli.js

@@ -1,5 +1,20 @@
 #!/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";
+  }
+};
+function assertAuthorized(response) {
+  if (response.status === 401) {
+    throw new UnauthorizedError();
+  }
+}
+
 // src/cli/lib/logger.ts
 import { createConsola } from "consola";
 var consola = createConsola({
@@ -13,7 +28,7 @@ import { randomBytes, randomUUID } from "crypto";
 // package.json
 var package_default = {
   name: "@bigcommerce/catalyst",
-  version: "1.0.0-alpha.2",
+  version: "1.0.0-alpha.5",
   type: "module",
   bin: {
     catalyst: "dist/cli.js"
@@ -35,22 +50,31 @@ var package_default = {
     node: "^20.0.0 || ^22.0.0 || ^24.0.0"
   },
   dependencies: {
+    "@commander-js/extra-typings": "^14.0.0",
+    "@inquirer/prompts": "^7.5.3",
     "@segment/analytics-node": "^2.2.1",
     "adm-zip": "^0.5.16",
     commander: "^14.0.0",
     conf: "^13.1.0",
     consola: "^3.4.2",
+    "cross-spawn": "^7.0.6",
     dotenv: "^16.5.0",
     execa: "^9.6.0",
+    "fs-extra": "^11.3.0",
+    "lodash.kebabcase": "^4.1.1",
+    nypm: "^0.5.4",
     open: "^10.1.0",
+    "std-env": "^3.9.0",
     "yocto-spinner": "^1.0.0",
     zod: "^4.0.5"
   },
   devDependencies: {
     "@bigcommerce/eslint-config": "^2.11.0",
     "@bigcommerce/eslint-config-catalyst": "workspace:^",
-    "@commander-js/extra-typings": "^14.0.0",
     "@types/adm-zip": "^0.5.7",
+    "@types/cross-spawn": "^6.0.6",
+    "@types/fs-extra": "^11.0.4",
+    "@types/lodash.kebabcase": "^4.1.9",
     "@types/node": "^22.15.30",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
@@ -66,23 +90,15 @@ var package_default = {
   }
 };
 
-// src/cli/lib/project-config.ts
+// src/cli/lib/user-config.ts
 import Conf from "conf";
-import { join } from "path";
-function getProjectConfig() {
-  return new Conf({
-    cwd: join(process.cwd(), ".bigcommerce"),
+var userConfigInstance;
+function getUserConfig() {
+  userConfigInstance ?? (userConfigInstance = new Conf({
+    projectName: "catalyst-cli",
     projectSuffix: "",
-    configName: "project",
+    configName: "config",
     schema: {
-      projectUuid: { type: "string", format: "uuid" },
-      framework: {
-        type: "string",
-        enum: ["catalyst"],
-        default: "catalyst"
-      },
-      storeHash: { type: "string" },
-      accessToken: { type: "string" },
       telemetry: {
         type: "object",
         properties: {
@@ -91,7 +107,8 @@ function getProjectConfig() {
         }
       }
     }
-  });
+  }));
+  return userConfigInstance;
 }
 
 // src/cli/lib/telemetry.ts
@@ -104,10 +121,10 @@ var Telemetry = class {
     this.projectVersion = package_default.version;
     this.setEnabled = (_enabled) => {
       const enabled = Boolean(_enabled);
-      this.projectConfig.set("telemetry.enabled", enabled);
+      this.userConfig.set("telemetry.enabled", enabled);
     };
     this.CATALYST_TELEMETRY_DISABLED = process.env.CATALYST_TELEMETRY_DISABLED;
-    this.projectConfig = getProjectConfig();
+    this.userConfig = getUserConfig();
     this.correlationId = randomUUID();
     this.startTime = Date.now();
     this.analytics = new Analytics({
@@ -159,15 +176,15 @@ var Telemetry = class {
     });
   }
   isEnabled() {
-    return !this.CATALYST_TELEMETRY_DISABLED && this.projectConfig.get(TELEMETRY_KEY_ENABLED, true);
+    return !this.CATALYST_TELEMETRY_DISABLED && this.userConfig.get(TELEMETRY_KEY_ENABLED, true);
   }
   getAnonymousId() {
-    const val = this.projectConfig.get(TELEMETRY_KEY_ID);
+    const val = this.userConfig.get(TELEMETRY_KEY_ID);
     if (val) {
       return val;
     }
     const generated = randomBytes(32).toString("hex");
-    this.projectConfig.set(TELEMETRY_KEY_ID, generated);
+    this.userConfig.set(TELEMETRY_KEY_ID, generated);
     return generated;
   }
 };
@@ -178,27 +195,33 @@ function getTelemetry() {
 }
 
 // src/cli/program.ts
-import { Option as Option8 } from "@commander-js/extra-typings";
-import { Command as Command9 } from "commander";
-import { colorize as colorize5 } from "consola/utils";
+import { Option as Option9 } from "@commander-js/extra-typings";
+import { Command as Command12 } from "commander";
+import { colorize as colorize8 } from "consola/utils";
 import { config } from "dotenv";
+import { existsSync as existsSync5 } from "fs";
 import { resolve } from "path";
 
 // src/cli/commands/auth.ts
-import { Command, Option } from "commander";
+import { Command, Option as Option2 } from "commander";
+import { z as z4 } from "zod";
+
+// src/cli/lib/login.ts
+import { password } from "@inquirer/prompts";
 import { colorize } from "consola/utils";
 import open from "open";
 import yoctoSpinner from "yocto-spinner";
-import { z as z3 } from "zod";
+import { z as z2 } from "zod";
 
 // src/cli/lib/auth.ts
 import { z } from "zod";
-var DEVICE_OAUTH_CLIENT_ID = "s1q4io7mah2lm1i6uwp9yl1eit80n3b";
+var DEVICE_OAUTH_CLIENT_ID = "b8063bu6hhml4e0lqh22yut63atsbyv";
 var DEVICE_OAUTH_SCOPES = [
   "store_v2_information",
   "store_infrastructure_deployments_manage",
   "store_infrastructure_logs_read_only",
-  "store_infrastructure_projects_manage"
+  "store_infrastructure_projects_manage",
+  "store_channel_settings"
 ].join(" ");
 var DEFAULT_LOGIN_URL = "https://login.bigcommerce.com";
 var DeviceCodeResponseSchema = z.object({
@@ -255,27 +278,149 @@ async function waitForDeviceToken(loginUrl, deviceCode, interval) {
   return waitForDeviceToken(loginUrl, deviceCode, interval);
 }
 
+// src/cli/lib/login.ts
+var LoginAbortedError = class extends Error {
+  constructor() {
+    super("Login aborted by user.");
+    this.name = "LoginAbortedError";
+  }
+};
+var StoreProfileSchema = z2.object({
+  data: z2.object({
+    store_name: z2.string()
+  })
+});
+async function fetchStoreProfile(storeHash, accessToken, apiHost) {
+  const response = await fetch(`https://${apiHost}/stores/${storeHash}/v3/settings/store/profile`, {
+    method: "GET",
+    headers: {
+      "X-Auth-Token": accessToken,
+      Accept: "application/json"
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`${response.status} ${response.statusText}`);
+  }
+  const res = await response.json();
+  const result = StoreProfileSchema.safeParse(res);
+  if (!result.success) {
+    throw new Error("Unexpected response from store profile API");
+  }
+  return result.data.data;
+}
+async function deviceCodeLogin(loginUrl) {
+  const deviceCode = await requestDeviceCode(loginUrl);
+  consola.info(
+    `${colorize("yellow", "Your one-time code:")} ${colorize("bold", deviceCode.user_code)}`
+  );
+  try {
+    await open(deviceCode.verification_uri);
+    consola.info(`Opened ${deviceCode.verification_uri} in your browser.`);
+  } catch {
+    consola.info(`Open ${deviceCode.verification_uri} in your browser and enter the code above.`);
+  }
+  const spinner = yoctoSpinner().start("Waiting for authentication...");
+  const credentials = await waitForDeviceToken(
+    loginUrl,
+    deviceCode.device_code,
+    deviceCode.interval
+  );
+  spinner.success("Authentication complete.");
+  return {
+    storeHash: credentials.store_hash,
+    accessToken: credentials.access_token
+  };
+}
+async function manualLogin(apiHost) {
+  consola.info(
+    `Create a store-level API account from your BigCommerce Control Panel:
+  Settings \u2192 API \u2192 Store-level API accounts \u2192 Create API account
+Grant these OAuth scopes: ${DEVICE_OAUTH_SCOPES}`
+  );
+  const storeHashInput = await consola.prompt("Store hash:", { type: "text" });
+  const storeHash = String(storeHashInput).trim();
+  if (!storeHash) {
+    throw new Error("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.");
+  }
+  const spinner = yoctoSpinner().start("Validating credentials...");
+  try {
+    const profile = await fetchStoreProfile(storeHash, accessToken, apiHost);
+    spinner.success(`Validated credentials for ${profile.store_name} (${storeHash}).`);
+  } catch (error) {
+    spinner.error("Failed to validate credentials.");
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Could not validate credentials (${message}). Double-check your store hash and access token, then try again.`
+    );
+  }
+  return { storeHash, accessToken };
+}
+async function login(loginUrl, apiHost) {
+  try {
+    return await deviceCodeLogin(loginUrl);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    consola.warn(`Browser login didn't work (${message}).`);
+    const shouldFallback = await consola.prompt(
+      "Try logging in manually with a store hash and access token instead?",
+      { type: "confirm", initial: true }
+    );
+    if (!shouldFallback) {
+      throw new LoginAbortedError();
+    }
+    return manualLogin(apiHost);
+  }
+}
+
 // src/cli/lib/project.ts
-import { z as z2 } from "zod";
-var fetchProjectsSchema = z2.object({
-  data: z2.array(
-    z2.object({
-      uuid: z2.string(),
-      name: z2.string()
+import { z as z3 } from "zod";
+var InfrastructureProjectValidationError = class extends Error {
+  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())
     })
   )
 });
-async function fetchProjects(storeHash, accessToken, apiHost) {
-  const response = await fetch(
-    `https://${apiHost}/stores/${storeHash}/v3/infrastructure/projects`,
-    {
-      method: "GET",
-      headers: {
-        "X-Auth-Token": accessToken,
-        "X-Correlation-Id": getTelemetry().correlationId
-      }
-    }
+function projectsUrl(storeHash, apiHost) {
+  return `https://${apiHost}/stores/${storeHash}/v3/infrastructure/projects`;
+}
+function authHeaders(accessToken) {
+  return {
+    "X-Auth-Token": accessToken,
+    "X-Correlation-Id": getTelemetry().correlationId
+  };
+}
+async function hasProjectsAccess(storeHash, accessToken, apiHost) {
+  const response = await fetch(projectsUrl(storeHash, apiHost), {
+    method: "GET",
+    headers: authHeaders(accessToken)
+  });
+  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}`
   );
+}
+async function fetchProjects(storeHash, accessToken, apiHost) {
+  const response = await fetch(projectsUrl(storeHash, apiHost), {
+    method: "GET",
+    headers: authHeaders(accessToken)
+  });
+  assertAuthorized(response);
   if (response.status === 403) {
     throw new Error(
       "Infrastructure Projects API not enabled. If you are part of the alpha, contact support@bigcommerce.com to enable it."
@@ -288,40 +433,52 @@ async function fetchProjects(storeHash, accessToken, apiHost) {
   const { data } = fetchProjectsSchema.parse(res);
   return data;
 }
-var createProjectSchema = z2.object({
-  data: z2.object({
-    uuid: z2.string(),
-    name: z2.string(),
-    date_created: z2.coerce.date(),
-    date_modified: z2.coerce.date()
+var createProjectSchema = z3.object({
+  data: z3.object({
+    uuid: z3.string(),
+    name: z3.string(),
+    date_created: z3.coerce.date(),
+    date_modified: z3.coerce.date()
   })
 });
+var validationErrorBodySchema = z3.object({
+  title: z3.string().optional(),
+  detail: z3.string().optional(),
+  errors: z3.record(z3.string(), z3.string()).optional()
+});
+function extractValidationMessage(body) {
+  const parsed = validationErrorBodySchema.safeParse(body);
+  if (!parsed.success) return null;
+  const { title, detail, errors } = parsed.data;
+  if (errors && Object.keys(errors).length > 0) {
+    return Object.values(errors).join("; ");
+  }
+  return detail ?? title ?? null;
+}
 async function createProject(name, storeHash, accessToken, apiHost) {
-  const response = await fetch(
-    `https://${apiHost}/stores/${storeHash}/v3/infrastructure/projects`,
-    {
-      method: "POST",
-      headers: {
-        "X-Auth-Token": accessToken,
-        Accept: "application/json",
-        "Content-Type": "application/json",
-        "X-Correlation-Id": getTelemetry().correlationId
-      },
-      body: JSON.stringify({ name })
-    }
-  );
-  if (response.status === 502) {
-    throw new Error("Failed to create project, is the name already in use?");
+  const response = await fetch(projectsUrl(storeHash, apiHost), {
+    method: "POST",
+    headers: {
+      ...authHeaders(accessToken),
+      Accept: "application/json",
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ name })
+  });
+  assertAuthorized(response);
+  if (response.status === 400 || response.status === 422) {
+    const body = await response.json().catch(() => null);
+    const fallback = response.status === 422 ? "The project name you entered doesn't meet the requirements. It must be 3\u201332 characters long and use only letters, numbers, hyphens (-), underscores (_), and periods (.)" : response.statusText;
+    const message = extractValidationMessage(body) ?? fallback;
+    throw new InfrastructureProjectValidationError(message);
   }
   if (response.status === 403) {
     throw new Error(
       "Infrastructure Projects API not enabled. If you are part of the alpha, contact support@bigcommerce.com to enable it."
     );
   }
-  if (response.status === 422) {
-    throw new Error(
-      "The project name you entered doesn't meet the requirements. It must be 3\u201332 characters long and use only letters, numbers, hyphens (-), underscores (_), and periods (.)"
-    );
+  if (response.status === 502) {
+    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}`);
@@ -330,14 +487,85 @@ async function createProject(name, storeHash, accessToken, apiHost) {
   const { data } = createProjectSchema.parse(res);
   return data;
 }
+async function deleteProject(projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(`${projectsUrl(storeHash, apiHost)}/${projectUuid}`, {
+    method: "DELETE",
+    headers: authHeaders(accessToken)
+  });
+  assertAuthorized(response);
+  if (response.status === 403) {
+    throw new Error(
+      "Infrastructure Projects API not enabled. If you are part of the alpha, contact support@bigcommerce.com to enable it."
+    );
+  }
+  if (response.status === 404) {
+    throw new Error(`Project ${projectUuid} not found.`);
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to delete project: ${response.statusText}`);
+  }
+}
+
+// src/cli/lib/project-config.ts
+import Conf2 from "conf";
+import { join } from "path";
+function getProjectConfig() {
+  return new Conf2({
+    cwd: join(process.cwd(), ".bigcommerce"),
+    projectSuffix: "",
+    configName: "project",
+    schema: {
+      projectUuid: { type: "string", format: "uuid" },
+      framework: {
+        type: "string",
+        enum: ["catalyst"],
+        default: "catalyst"
+      },
+      storeHash: { type: "string" },
+      accessToken: { type: "string" },
+      env: {
+        type: "object",
+        additionalProperties: { type: "string" },
+        default: {}
+      }
+    }
+  });
+}
+
+// src/cli/lib/shared-options.ts
+import { Option } from "commander";
+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."
+).env("CATALYST_STORE_HASH");
+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 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 resolveProjectUuid = (options) => {
+  const config2 = getProjectConfig();
+  const projectUuid = options.projectUuid ?? config2.get("projectUuid");
+  if (!projectUuid) {
+    throw new Error(
+      "Project UUID is required. Please run either `catalyst project link` or `catalyst project create` or this command again with --project-uuid <uuid>."
+    );
+  }
+  return projectUuid;
+};
 
 // src/cli/commands/auth.ts
-var StoreProfileSchema = z3.object({
-  data: z3.object({
-    store_name: z3.string()
+var StoreProfileSchema2 = z4.object({
+  data: z4.object({
+    store_name: z4.string()
   })
 });
-async function fetchStoreProfile(storeHash, accessToken, apiHost) {
+async function fetchStoreProfile2(storeHash, accessToken, apiHost) {
   const response = await fetch(`https://${apiHost}/stores/${storeHash}/v3/settings/store/profile`, {
     method: "GET",
     headers: {
@@ -345,28 +573,36 @@ async function fetchStoreProfile(storeHash, accessToken, apiHost) {
       Accept: "application/json"
     }
   });
+  assertAuthorized(response);
   if (!response.ok) {
     throw new Error(`${response.status} ${response.statusText}`);
   }
   const res = await response.json();
-  const result = StoreProfileSchema.safeParse(res);
+  const result = StoreProfileSchema2.safeParse(res);
   if (!result.success) {
     throw new Error("Unexpected response from store profile API");
   }
   return result.data.data;
 }
-var whoami = new Command("whoami").description("Verify stored credentials and display store/project info.").addOption(
-  new Option(
+var whoami = new Command("whoami").configureHelp({ showGlobalOptions: true }).description("Verify stored credentials and display store/project info.").addHelpText(
+  "after",
+  `
+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 Option(
+  new Option2(
     "--access-token <token>",
     "BigCommerce access token. Can be found after creating a store-level API account."
   ).env("CATALYST_ACCESS_TOKEN")
 ).addOption(
-  new Option("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com")
+  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) => {
   try {
     const config2 = getProjectConfig();
@@ -380,7 +616,7 @@ var whoami = new Command("whoami").description("Verify stored credentials and di
       process.exit(1);
       return;
     }
-    const store = await fetchStoreProfile(storeHash, accessToken, options.apiHost);
+    const store = await fetchStoreProfile2(storeHash, accessToken, options.apiHost);
     const projectUuid = config2.get("projectUuid");
     if (projectUuid) {
       const projects = await fetchProjects(storeHash, accessToken, options.apiHost);
@@ -400,7 +636,11 @@ var whoami = new Command("whoami").description("Verify stored credentials and di
     process.exit(0);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    if (message.includes("401") || message.includes("403")) {
+    if (error instanceof UnauthorizedError) {
+      consola.error(
+        "Not logged in: your access token is invalid or has expired. Run `catalyst auth login`."
+      );
+    } else if (message.includes("401") || message.includes("403")) {
       consola.error(`Not logged in: invalid credentials (${message})`);
     } else {
       consola.error(`Failed to verify credentials: ${message}`);
@@ -408,19 +648,30 @@ var whoami = new Command("whoami").description("Verify stored credentials and di
     process.exit(1);
   }
 });
-var login = new Command("login").description("Authenticate via browser using the OAuth device code flow.").addOption(
-  new Option(
+var login2 = new Command("login").configureHelp({ showGlobalOptions: true }).description(
+  "Authenticate via browser using the OAuth device code flow. Falls back to an interactive store hash + access token prompt if the browser flow is unavailable. If already logged in, displays current credentials and suggests running `catalyst auth logout` to re-authenticate."
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Login interactively (browser, with manual fallback)
+  $ catalyst auth login
+
+  # 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 Option(
+  new Option2(
     "--access-token <token>",
     "BigCommerce access token. Can be found after creating a store-level API account."
   ).env("CATALYST_ACCESS_TOKEN")
 ).addOption(
-  new Option("--login-url <url>", "BigCommerce login URL.").env("BIGCOMMERCE_LOGIN_URL").default(DEFAULT_LOGIN_URL)
-).action(async (options) => {
+  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) => {
   try {
     const config2 = getProjectConfig();
     const storeHash = options.storeHash ?? config2.get("storeHash");
@@ -431,36 +682,30 @@ var login = new Command("login").description("Authenticate via browser using the
       process.exit(0);
       return;
     }
-    const deviceCode = await requestDeviceCode(options.loginUrl);
-    consola.info(
-      `${colorize("yellow", "Your one-time code:")} ${colorize("bold", deviceCode.user_code)}`
-    );
-    try {
-      await open(deviceCode.verification_uri);
-      consola.info(`Opened ${deviceCode.verification_uri} in your browser.`);
-    } catch {
+    const credentials = await login(options.loginUrl, options.apiHost);
+    config2.set("storeHash", credentials.storeHash);
+    config2.set("accessToken", credentials.accessToken);
+    consola.success(`Logged in to store ${credentials.storeHash}.`);
+    process.exit(0);
+  } catch (error) {
+    if (error instanceof LoginAbortedError) {
       consola.info(
-        `Open ${deviceCode.verification_uri} in your browser and enter the code above.`
+        "Login aborted. Re-run `catalyst auth login` when you have your credentials ready."
       );
+      process.exit(0);
+      return;
     }
-    const spinner = yoctoSpinner().start("Waiting for authentication...");
-    const credentials = await waitForDeviceToken(
-      options.loginUrl,
-      deviceCode.device_code,
-      deviceCode.interval
-    );
-    spinner.success("Authentication complete.");
-    config2.set("storeHash", credentials.store_hash);
-    config2.set("accessToken", credentials.access_token);
-    consola.success(`Logged in to store ${credentials.store_hash}.`);
-    process.exit(0);
-  } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     consola.error(`Login failed: ${message}`);
     process.exit(1);
   }
 });
-var logout = new Command("logout").description("Remove stored credentials for the current project.").action(() => {
+var logout = new Command("logout").configureHelp({ showGlobalOptions: true }).description("Remove stored credentials for the current project.").addHelpText(
+  "after",
+  `
+Example:
+  $ catalyst auth logout`
+).action(() => {
   try {
     const config2 = getProjectConfig();
     const storeHash = config2.get("storeHash");
@@ -480,13 +725,13 @@ var logout = new Command("logout").description("Remove stored credentials for th
     process.exit(1);
   }
 });
-var auth = new Command("auth").description("Manage authentication for the BigCommerce CLI.").addCommand(whoami).addCommand(login).addCommand(logout);
+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 Option2 } from "commander";
+import { Command as Command2, Option as Option3 } from "commander";
 import { execa } from "execa";
-import { copyFile, cp, writeFile } from "fs/promises";
-import { join as join3 } from "path";
+import { copyFile, cp, rm, writeFile } from "fs/promises";
+import { join as join4 } from "path";
 
 // src/cli/lib/get-module-cli-path.ts
 import { dirname, join as join2 } from "path";
@@ -497,6 +742,46 @@ function getModuleCliPath() {
   return join2(__dirname, "..");
 }
 
+// src/cli/lib/project-state.ts
+import { existsSync, readFileSync } from "fs";
+import { join as join3 } from "path";
+import { z as z5 } from "zod";
+var projectJsonSchema = z5.looseObject({
+  projectUuid: z5.string().optional()
+});
+var packageJsonSchema = z5.looseObject({
+  dependencies: z5.record(z5.string(), z5.string()).optional()
+});
+var safeReadJson = (path) => {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+};
+function getProjectState(cwd = process.cwd()) {
+  const projectJson = projectJsonSchema.safeParse(
+    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 pkgJson = packageJsonSchema.safeParse(safeReadJson(join3(cwd, "package.json")));
+  const hasOpenNextDep = pkgJson.success ? Boolean(pkgJson.data.dependencies?.["@opennextjs/cloudflare"]) : false;
+  const isLinked = Boolean(projectUuid);
+  const isTransformed = hasMiddleware && !hasProxy && hasOpenNextDep;
+  const isFullySetUp = isLinked && isTransformed;
+  return {
+    projectUuid,
+    hasMiddleware,
+    hasProxy,
+    hasOpenNextDep,
+    isLinked,
+    isTransformed,
+    isFullySetUp
+  };
+}
+
 // src/cli/lib/wrangler-config.ts
 function getWranglerConfig(projectUuid) {
   return {
@@ -556,19 +841,20 @@ function getWranglerConfig(projectUuid) {
 }
 
 // src/cli/commands/build.ts
-var WRANGLER_VERSION = "4.24.3";
+var WRANGLER_VERSION = "4.90.0";
 async function buildCatalystProject(projectUuid) {
   const coreDir = process.cwd();
-  const openNextOutDir = join3(coreDir, ".open-next");
-  const bigcommerceDistDir = join3(coreDir, ".bigcommerce", "dist");
+  const openNextOutDir = join4(coreDir, ".open-next");
+  const bigcommerceDistDir = join4(coreDir, ".bigcommerce", "dist");
   const wranglerConfig = getWranglerConfig(projectUuid);
+  await rm(bigcommerceDistDir, { recursive: true, force: true });
   consola.start("Copying templates...");
   await copyFile(
-    join3(getModuleCliPath(), "templates", "open-next.config.ts"),
-    join3(coreDir, ".bigcommerce", "open-next.config.ts")
+    join4(getModuleCliPath(), "templates", "open-next.config.ts"),
+    join4(coreDir, ".bigcommerce", "open-next.config.ts")
   );
   await writeFile(
-    join3(coreDir, ".bigcommerce", "wrangler.jsonc"),
+    join4(coreDir, ".bigcommerce", "wrangler.jsonc"),
     JSON.stringify(wranglerConfig, null, 2)
   );
   consola.success("Templates copied");
@@ -581,7 +867,7 @@ async function buildCatalystProject(projectUuid) {
       "build",
       "--skipWranglerConfigCheck",
       "--openNextConfigPath",
-      join3(coreDir, ".bigcommerce", "open-next.config.ts")
+      join4(coreDir, ".bigcommerce", "open-next.config.ts")
     ],
     {
       stdout: ["pipe", "inherit"],
@@ -595,7 +881,7 @@ async function buildCatalystProject(projectUuid) {
       `wrangler@${WRANGLER_VERSION}`,
       "deploy",
       "--config",
-      join3(coreDir, ".bigcommerce", "wrangler.jsonc"),
+      join4(coreDir, ".bigcommerce", "wrangler.jsonc"),
       "--keep-vars",
       "--outdir",
       bigcommerceDistDir,
@@ -607,17 +893,37 @@ async function buildCatalystProject(projectUuid) {
     }
   );
   consola.success("Project built");
-  await cp(join3(openNextOutDir, "assets"), join3(bigcommerceDistDir, "assets"), {
+  await cp(join4(openNextOutDir, "assets"), join4(bigcommerceDistDir, "assets"), {
     recursive: true,
     force: true
   });
 }
-var build = new Command2("build").addOption(
-  new Option2(
+var build = new Command2("build").configureHelp({ showGlobalOptions: true }).description(
+  "Build your Catalyst project using the OpenNext/Cloudflare build pipeline. Also runs a Wrangler dry-run to generate deployment artifacts."
+).addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst build
+
+  # Include project UUID
+  $ catalyst build --project-uuid <UUID>`
+).addOption(
+  new Option3(
     "--project-uuid <uuid>",
     "Project UUID to be included in the deployment configuration."
   ).env("CATALYST_PROJECT_UUID")
 ).action(async (options) => {
+  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"], {
+      stdio: "inherit",
+      cwd: process.cwd()
+    });
+    return;
+  }
   const config2 = getProjectConfig();
   const projectUuid = options.projectUuid ?? config2.get("projectUuid");
   if (!projectUuid) {
@@ -628,34 +934,563 @@ var build = new Command2("build").addOption(
   await buildCatalystProject(projectUuid);
 });
 
-// src/cli/commands/deploy.ts
-import AdmZip from "adm-zip";
-import { Command as Command3, Option as Option3 } from "commander";
-import { colorize as colorize2 } from "consola/utils";
-import { access, readdir, readFile } from "fs/promises";
-import { join as join4 } from "path";
-import yoctoSpinner2 from "yocto-spinner";
-import { z as z4 } from "zod";
+// src/cli/commands/channel.ts
+import { Command as Command3, Option as Option4 } from "commander";
 
-// src/cli/lib/deployment-errors.ts
-var ERROR_MESSAGES = {
-  10: "Something went wrong on our end. Please try again. If the issue persists, contact support.",
-  20: "We couldn't retrieve your bundle. This is usually a temporary issue \u2014 please try deploying again. If the problem continues, contact support.",
-  30: "Your bundle could not be extracted. This may mean your build output is too large (max 64 MB compressed / 512 MB uncompressed) or the archive is corrupted. Try reducing your build size or rebuilding your project and deploying again.",
-  40: `There's a problem with your build output. This could be caused by:
-- A worker.js file larger than 40 MB
-- An individual asset file larger than 25 MB
-- More than 1,000 total files in the bundle`,
-  50: "Deployment failed. This is usually a temporary issue \u2014 please try again. If the problem persists, contact support.",
-  60: "Your code was deployed, but we couldn't determine your deployment URL. Please try deploying again. If the issue persists, contact support."
+// src/cli/lib/channels.ts
+import { z as z6 } 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();
+  return `https://${apiHost}/stores/${storeHash}/v3/channels${params ? `?${params}` : ""}`;
 };
-function getDeploymentErrorMessage(code) {
-  return ERROR_MESSAGES[code] ?? `Deployment failed with an unexpected error (code: ${code}). Please try again. If the issue persists, contact support.`;
-}
-
-// src/cli/lib/resolve-credentials.ts
-function resolveCredentials(options, config2) {
-  const storeHash = options.storeHash ?? config2.get("storeHash");
+var authHeaders2 = (accessToken) => ({
+  "X-Auth-Token": 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 channelsResponseSchema = z6.object({
+  data: z6.array(channelSchema)
+});
+var initResponseSchema = z6.object({
+  data: z6.object({
+    storefront_api_token: z6.string(),
+    envVars: envVarsSchema
+  })
+});
+var createChannelResponseSchema = z6.object({
+  data: z6.object({
+    id: z6.number(),
+    storefront_api_token: z6.string(),
+    envVars: envVarsSchema
+  })
+});
+var eligibilityResponseSchema = z6.object({
+  data: z6.object({
+    eligible: z6.boolean(),
+    message: z6.string()
+  })
+});
+var channelSiteSchema = z6.object({
+  data: z6.object({
+    id: z6.number(),
+    url: z6.string(),
+    channel_id: z6.number()
+  })
+});
+async function getChannelInit(channelId, storeHash, accessToken, origin) {
+  const response = await fetch(cliApiUrl(origin, storeHash, `/channels/${channelId}/init`), {
+    method: "GET",
+    headers: authHeaders2(accessToken)
+  });
+  if (!response.ok) {
+    throw new Error(
+      `GET /channels/${channelId}/init failed: ${response.status} ${response.statusText}`
+    );
+  }
+  const { data } = initResponseSchema.parse(await response.json());
+  return { storefrontToken: data.storefront_api_token, envVars: data.envVars };
+}
+async function checkChannelEligibility(storeHash, accessToken, origin) {
+  const response = await fetch(cliApiUrl(origin, storeHash, "/channels/catalyst/eligibility"), {
+    method: "GET",
+    headers: authHeaders2(accessToken)
+  });
+  if (!response.ok) {
+    throw new Error(
+      `GET /channels/catalyst/eligibility failed: ${response.status} ${response.statusText}`
+    );
+  }
+  return eligibilityResponseSchema.parse(await response.json()).data;
+}
+async function createChannel(name, storefrontLocale, additionalLocales, installSampleData, storeHash, accessToken, origin) {
+  const response = await fetch(cliApiUrl(origin, storeHash, "/channels/catalyst"), {
+    method: "POST",
+    headers: { ...authHeaders2(accessToken), "Content-Type": "application/json" },
+    body: JSON.stringify({
+      name,
+      initialData: { type: installSampleData ? "sample" : "none" },
+      deployStorefront: true,
+      devOrigin: "http://localhost:3000",
+      storefrontLanguage: storefrontLocale,
+      additionalLocales
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`POST /channels/catalyst failed: ${response.status} ${response.statusText}`);
+  }
+  const { data } = createChannelResponseSchema.parse(await response.json());
+  return {
+    channelId: data.id,
+    storefrontToken: data.storefront_api_token,
+    envVars: data.envVars
+  };
+}
+async function fetchAvailableChannels(storeHash, accessToken, apiHost) {
+  const response = await fetch(
+    channelsUrl(storeHash, apiHost, { available: "true", type: "storefront" }),
+    {
+      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/channels failed: ${response.status} ${response.statusText}`);
+  }
+  return channelsResponseSchema.parse(await response.json()).data;
+}
+async function updateChannelSiteUrl(channelId, siteUrl, storeHash, accessToken, apiHost) {
+  const response = await fetch(
+    `https://${apiHost}/stores/${storeHash}/v3/channels/${channelId}/site`,
+    {
+      method: "PUT",
+      headers: {
+        "X-Auth-Token": accessToken,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-Correlation-Id": getTelemetry().correlationId
+      },
+      body: JSON.stringify({ url: siteUrl })
+    }
+  );
+  if (response.status === 401 || response.status === 403) {
+    throw new Error(
+      `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}`);
+  }
+  const res = await response.json();
+  const { data } = channelSiteSchema.parse(res);
+  return { id: data.id, url: data.url, channelId: data.channel_id };
+}
+
+// src/cli/lib/commerce-hosting.ts
+import { input, select, Separator } from "@inquirer/prompts";
+import { colorize as colorize2 } from "consola/utils";
+import {
+  existsSync as existsSync2,
+  lstatSync,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { dirname as dirname2, join as join5 } from "path";
+import { z as z7 } from "zod";
+
+// src/cli/lib/sort-package-json.ts
+var FIELD_ORDER = [
+  "name",
+  "description",
+  "version",
+  "private",
+  "engines",
+  "scripts",
+  "dependencies",
+  "devDependencies"
+];
+function sortPackageJsonFields(pkg) {
+  const ordered = {};
+  FIELD_ORDER.forEach((field) => {
+    if (field in pkg) {
+      ordered[field] = pkg[field];
+    }
+  });
+  Object.keys(pkg).forEach((key) => {
+    if (!(key in ordered)) {
+      ordered[key] = pkg[key];
+    }
+  });
+  return ordered;
+}
+
+// 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 writeJson = (path, value) => {
+  mkdirSync(dirname2(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`);
+};
+var symlinkRootEnvToCore = (projectDir) => {
+  const coreEnvPath = join5(projectDir, "core", ".env.local");
+  if (lstatSync(coreEnvPath, { throwIfNoEntry: false })) return;
+  try {
+    symlinkSync("../.env.local", coreEnvPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "unknown error";
+    consola.warn(
+      `Could not create symlink at core/.env.local: ${message}
+On Windows, enable Developer Mode or run as administrator to allow symlinks.
+You will need to keep .env.local and core/.env.local in sync manually.`
+    );
+  }
+};
+var convertProxyToMiddleware = (projectDir) => {
+  const proxyPath = join5(projectDir, "core", "proxy.ts");
+  const middlewarePath = join5(projectDir, "core", "middleware.ts");
+  if (!existsSync2(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, "core", "instrumentation.ts");
+  if (!existsSync2(instrumentationPath)) return;
+  if (!process.stdin.isTTY) {
+    consola.warn(
+      "core/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."
+    );
+    return;
+  }
+  const shouldRemove = await consola.prompt(
+    'Catalyst found core/instrumentation.ts, which is incompatible with the Cloudflare Workers bundle when it uses @vercel/otel (causes "Failed to prepare server" at cold start). Remove it and drop @vercel/otel from core/package.json?',
+    { type: "confirm", initial: true }
+  );
+  consola.log("");
+  if (!shouldRemove) {
+    consola.info(
+      'Leaving core/instrumentation.ts in place. The Cloudflare worker will continue to log "Failed to prepare server" at cold start until this is resolved manually.'
+    );
+    return;
+  }
+  unlinkSync(instrumentationPath);
+  consola.info("Removed core/instrumentation.ts (incompatible with Cloudflare Workers).");
+  const corePackageJsonPath = join5(projectDir, "core", "package.json");
+  if (existsSync2(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;
+      pkg.dependencies = preservedDeps;
+      writeJson(corePackageJsonPath, sortPackageJsonFields(pkg));
+      consola.info("Dropped @vercel/otel from core/package.json.");
+    }
+  }
+};
+var setupCommerceHosting = async ({
+  projectDir,
+  projectUuid,
+  storeHash,
+  accessToken
+}) => {
+  await cleanupCloudflareIncompatibilities(projectDir);
+  const corePackageJsonPath = join5(projectDir, "core", "package.json");
+  const pkg = corePackageJsonSchema.parse(JSON.parse(readFileSync2(corePackageJsonPath, "utf-8")));
+  pkg.dependencies = {
+    ...pkg.dependencies,
+    "@opennextjs/cloudflare": OPENNEXT_CLOUDFLARE_VERSION
+  };
+  writeJson(corePackageJsonPath, sortPackageJsonFields(pkg));
+  const projectJson = {
+    projectUuid,
+    framework: "catalyst"
+  };
+  if (storeHash) projectJson.storeHash = storeHash;
+  if (accessToken) projectJson.accessToken = accessToken;
+  writeJson(join5(projectDir, "core", ".bigcommerce", "project.json"), projectJson);
+  symlinkRootEnvToCore(projectDir);
+  convertProxyToMiddleware(projectDir);
+};
+var NoLinkedProjectError = class extends Error {
+  constructor() {
+    super("No infrastructure project linked: user declined to create one.");
+    this.name = "NoLinkedProjectError";
+  }
+};
+async function promptForNewProjectName(api) {
+  const newProjectName = await consola.prompt("Enter a name for the new project:", {
+    type: "text"
+  });
+  const data = await createProject(
+    String(newProjectName),
+    api.storeHash,
+    api.accessToken,
+    api.apiHost
+  );
+  consola.success(`Project "${data.name}" created successfully.`);
+  return { uuid: data.uuid, name: data.name, deployment_hostnames: [] };
+}
+async function selectOrCreateInfrastructureProject(api, linkedProjectUuid) {
+  consola.start("Fetching projects...");
+  const existingProjects = await fetchProjects(api.storeHash, api.accessToken, api.apiHost);
+  consola.success("Projects fetched.");
+  if (existingProjects.length === 0) {
+    const shouldCreate = await consola.prompt(
+      "There are not any hosting projects that you can link to yet. Would you like to create one?",
+      { type: "confirm", initial: true }
+    );
+    if (!shouldCreate) {
+      throw new NoLinkedProjectError();
+    }
+    return promptForNewProjectName(api);
+  }
+  const promptOptions = [
+    ...existingProjects.map((p) => ({
+      label: p.uuid === linkedProjectUuid ? `${p.name} ${colorize2("green", "[linked]")}` : p.name,
+      value: p.uuid,
+      hint: p.uuid
+    })),
+    {
+      label: "Create a new project",
+      value: "create",
+      hint: "Create a new hosting project for this Catalyst storefront."
+    }
+  ];
+  const selected = await consola.prompt(
+    "Select a project or create a new project (Press <enter> to select).",
+    { type: "select", options: promptOptions, cancel: "reject" }
+  );
+  if (selected === "create") {
+    return promptForNewProjectName(api);
+  }
+  const matched = existingProjects.find((p) => p.uuid === selected);
+  if (!matched) {
+    throw new Error(`Selected project ${String(selected)} not found in fetched list.`);
+  }
+  return matched;
+}
+async function promptForCommerceHostingProject(api, defaultName, autoUseDefaultName, useExistingOnCollision) {
+  const existingProjects = await fetchProjects(api.storeHash, api.accessToken, api.apiHost);
+  const takenNames = existingProjects.map((project2) => project2.name);
+  if (autoUseDefaultName) {
+    return autoCreateCommerceHostingProject(
+      api,
+      defaultName,
+      existingProjects,
+      useExistingOnCollision
+    );
+  }
+  const conflict = existingProjects.find(
+    (project2) => project2.name.toLowerCase() === defaultName.toLowerCase()
+  );
+  if (!conflict) {
+    return autoCreateCommerceHostingProject(
+      api,
+      defaultName,
+      existingProjects,
+      useExistingOnCollision
+    );
+  }
+  const hasOtherProjects = existingProjects.length > 1;
+  const choices = [
+    { name: `Use "${conflict.name}"`, value: "use-named" }
+  ];
+  if (hasOtherProjects) {
+    choices.push({ name: "Select from my projects", value: "select-from-list" });
+  }
+  choices.push({ name: "Create a new project", value: "create" });
+  const action = await select({
+    message: hasOtherProjects ? `It looks like you already have an existing Commerce Hosting project named "${conflict.name}". Would you like to use it, select from your projects, or create a new one?` : `It looks like you already have an existing Commerce Hosting project named "${conflict.name}". Would you like to use it, or create a new one?`,
+    choices
+  });
+  if (action === "use-named") {
+    consola.success(`Using existing Commerce Hosting project "${conflict.name}"`);
+    return conflict;
+  }
+  if (action === "create") {
+    return promptAndCreateCommerceHostingProject(api, takenNames, defaultName);
+  }
+  const selected = await select({
+    message: "Which Commerce Hosting project would you like to use?",
+    choices: [
+      ...existingProjects.map((project2) => ({
+        name: project2.name,
+        value: project2,
+        description: project2.uuid
+      })),
+      new Separator(),
+      { name: "Create a new project", value: "create-new" }
+    ]
+  });
+  if (selected === "create-new") {
+    return promptAndCreateCommerceHostingProject(api, takenNames, defaultName);
+  }
+  consola.success(`Using existing Commerce Hosting project "${selected.name}"`);
+  return selected;
+}
+async function promptAndCreateCommerceHostingProject(api, takenNames, defaultName) {
+  const projectName = await input({
+    message: "What would you like to name your Commerce Hosting project?",
+    default: defaultName,
+    validate: (value) => {
+      const trimmed = value.trim();
+      if (!trimmed) return "Project name is required";
+      const conflict = takenNames.find((taken) => taken.toLowerCase() === trimmed.toLowerCase());
+      if (conflict) {
+        return `A Commerce Hosting project named "${conflict}" already exists`;
+      }
+      return true;
+    },
+    theme: {
+      style: {
+        help: () => colorize2(
+          "dim",
+          "(The project that hosts your storefront on Commerce \u2014 often matches your folder name.)"
+        )
+      }
+    }
+  });
+  try {
+    const created = await createProject(
+      projectName.trim(),
+      api.storeHash,
+      api.accessToken,
+      api.apiHost
+    );
+    consola.success(`Commerce Hosting project "${created.name}" created successfully`);
+    return { uuid: created.uuid, name: created.name, deployment_hostnames: [] };
+  } catch (error) {
+    if (error instanceof InfrastructureProjectValidationError) {
+      consola.error(error.message);
+      return promptAndCreateCommerceHostingProject(api, takenNames, defaultName);
+    }
+    throw error;
+  }
+}
+async function resolveCollisionChoice(existingName, useExistingOnCollision) {
+  if (useExistingOnCollision === true) return true;
+  if (!process.stdin.isTTY) return false;
+  return select({
+    message: `A Commerce Hosting project named "${existingName}" already exists. Use the existing project?`,
+    choices: [
+      { name: "Yes", value: true },
+      { name: "No", value: false }
+    ]
+  });
+}
+async function autoCreateCommerceHostingProject(api, name, existingProjects, useExistingOnCollision) {
+  const existing = existingProjects.find(
+    (project2) => project2.name.toLowerCase() === name.toLowerCase()
+  );
+  if (existing) {
+    const shouldUseExisting = await resolveCollisionChoice(existing.name, useExistingOnCollision);
+    if (shouldUseExisting) {
+      consola.success(`Using existing Commerce Hosting project "${existing.name}"`);
+      return existing;
+    }
+    consola.error(
+      "Not reusing the existing project. Re-run with a different --project-name, or pass --use-existing to reuse it."
+    );
+    process.exit(1);
+  }
+  try {
+    const created = await createProject(name, api.storeHash, api.accessToken, api.apiHost);
+    consola.success(`Commerce Hosting project "${created.name}" created successfully`);
+    return { uuid: created.uuid, name: created.name, deployment_hostnames: [] };
+  } catch (error) {
+    if (error instanceof InfrastructureProjectValidationError) {
+      consola.error(
+        `Failed to create Commerce Hosting project "${name}": ${error.message}
+Re-run with a different --project-name.`
+      );
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+
+// src/cli/lib/channel-site-flow.ts
+async function resolveProject(options) {
+  const api = {
+    storeHash: options.storeHash,
+    accessToken: options.accessToken,
+    apiHost: options.apiHost
+  };
+  if (options.projectUuid) {
+    const projects = await fetchProjects(api.storeHash, api.accessToken, api.apiHost);
+    const matched = projects.find((p) => p.uuid === options.projectUuid);
+    if (matched) return matched;
+    consola.warn(
+      `Project ${options.projectUuid} not found on this store. Pick another to continue.`
+    );
+  }
+  return selectOrCreateInfrastructureProject(api, options.projectUuid);
+}
+async function resolveChannel(options) {
+  if (options.channelId !== void 0) {
+    return { id: options.channelId };
+  }
+  consola.start("Fetching channels...");
+  const channels = await fetchAvailableChannels(
+    options.storeHash,
+    options.accessToken,
+    options.apiHost
+  );
+  consola.success("Channels fetched.");
+  const catalystChannels = channels.filter((c) => c.platform === "catalyst");
+  if (catalystChannels.length === 0) {
+    throw new Error(
+      "No Catalyst channels found on this store. Create one with `catalyst create` and try again."
+    );
+  }
+  const selectedId = await consola.prompt("Select the channel to update.", {
+    type: "select",
+    options: catalystChannels.map((c) => ({
+      label: c.name,
+      value: String(c.id),
+      hint: `id: ${c.id}`
+    })),
+    cancel: "reject"
+  });
+  const id = Number(selectedId);
+  const matched = catalystChannels.find((c) => c.id === id);
+  return { id, name: matched?.name };
+}
+async function resolveHostname(project2, options) {
+  if (options.hostname) {
+    return options.hostname;
+  }
+  if (project2.deployment_hostnames.length === 0) {
+    throw new Error(
+      `Project "${project2.name}" has no deployment hostnames yet. Run \`catalyst deploy\` first to create one.`
+    );
+  }
+  const ordered = options.preferHostname ? [
+    ...project2.deployment_hostnames.filter((h) => h === options.preferHostname),
+    ...project2.deployment_hostnames.filter((h) => h !== options.preferHostname)
+  ] : project2.deployment_hostnames;
+  const selected = await consola.prompt("Select the hostname to point the channel at.", {
+    type: "select",
+    options: ordered.map((h) => ({ label: h, value: h })),
+    cancel: "reject"
+  });
+  return String(selected);
+}
+async function runChannelSiteUrlFlow(options) {
+  const project2 = await resolveProject(options);
+  const channel2 = await resolveChannel(options);
+  const hostname = await resolveHostname(project2, options);
+  const siteUrl = hostname.startsWith("https://") ? hostname : `https://${hostname}`;
+  await updateChannelSiteUrl(
+    channel2.id,
+    siteUrl,
+    options.storeHash,
+    options.accessToken,
+    options.apiHost
+  );
+  const channelLabel = channel2.name ? `"${channel2.name}" (${channel2.id})` : String(channel2.id);
+  consola.success(`Updated channel ${channelLabel} site URL to ${siteUrl}.`);
+}
+
+// src/cli/lib/resolve-credentials.ts
+function resolveCredentials(options, config2) {
+  const storeHash = options.storeHash ?? config2.get("storeHash");
   const accessToken = options.accessToken ?? config2.get("accessToken");
   if (!storeHash || !accessToken) {
     consola.error("Missing credentials.");
@@ -668,8 +1503,690 @@ function resolveCredentials(options, config2) {
   return { storeHash, accessToken };
 }
 
+// src/cli/commands/channel.ts
+var update = new Command3("update").configureHelp({ showGlobalOptions: true }).description(
+  "Update a BigCommerce channel's site URL to point at one of your project's deployment hostnames."
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Pick a channel and hostname interactively
+  $ catalyst channel update
+
+  # 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(
+    "--channel-id <id>",
+    "Skip the channel prompt and target this channel directly."
+  ).argParser((value) => Number(value))
+).addOption(
+  new Option4(
+    "--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 { storeHash, accessToken } = resolveCredentials(options, config2);
+  await getTelemetry().identify(storeHash);
+  try {
+    await runChannelSiteUrlFlow({
+      storeHash,
+      accessToken,
+      apiHost: options.apiHost,
+      projectUuid: options.projectUuid ?? config2.get("projectUuid"),
+      channelId: options.channelId,
+      hostname: options.hostname
+    });
+  } catch (error) {
+    if (error instanceof NoLinkedProjectError) {
+      consola.info(
+        "When you're ready to create a project, run `catalyst project create` or re-run `catalyst channel update`."
+      );
+      process.exit(0);
+      return;
+    }
+    throw error;
+  }
+  process.exit(0);
+});
+var channel = new Command3("channel").configureHelp({ showGlobalOptions: true }).description("Manage BigCommerce channels.").addCommand(update);
+
+// src/cli/commands/create.ts
+import { Command as Command4, InvalidArgumentError, Option as Option5 } from "@commander-js/extra-typings";
+import { input as input2, select as select2 } from "@inquirer/prompts";
+import { execSync as execSync4 } from "child_process";
+import { colorize as colorize3 } from "consola/utils";
+import { pathExistsSync } from "fs-extra/esm";
+import kebabCase from "lodash.kebabcase";
+import { join as join9 } from "path";
+
+// src/cli/lib/build-workspace-packages.ts
+import { execSync } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { join as join6 } from "path";
+import yoctoSpinner2 from "yocto-spinner";
+var WORKSPACE_PACKAGES = ["packages/catalyst", "packages/client"];
+var buildWorkspacePackages = (projectDir) => {
+  const hasCore = existsSync3(join6(projectDir, "core"));
+  const hasAllWorkspacePackages = WORKSPACE_PACKAGES.every(
+    (pkg) => existsSync3(join6(projectDir, pkg))
+  );
+  if (!hasCore || !hasAllWorkspacePackages) return;
+  WORKSPACE_PACKAGES.forEach((pkg) => {
+    const spinner = yoctoSpinner2().start(`Building ${pkg}...`);
+    try {
+      execSync("pnpm build", { cwd: join6(projectDir, pkg), stdio: "ignore" });
+      spinner.success(`Built ${pkg}.`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "unknown error";
+      spinner.error(`Failed to build ${pkg}: ${message}`);
+      throw error;
+    }
+  });
+};
+
+// src/cli/lib/clone-catalyst.ts
+import { execSync as execSync3 } from "child_process";
+
+// src/cli/lib/checkout-ref.ts
+import { sync as spawnSync } from "cross-spawn";
+
+// src/cli/lib/is-exec-exception.ts
+function isExecException(error) {
+  return typeof error === "object" && error !== null && "stdout" in error && "stderr" in error;
+}
+
+// src/cli/lib/checkout-ref.ts
+function checkoutRef(repoDir, ref) {
+  try {
+    const spawn = spawnSync("git", ["checkout", ref, "--"], {
+      cwd: repoDir,
+      encoding: "utf8",
+      shell: false
+    });
+    const stderr = spawn.stderr.trim();
+    if (spawn.status !== 0 && stderr) {
+      throw new Error(stderr);
+    }
+    consola.success(`Checked out ref ${ref} successfully.`);
+  } catch (error) {
+    if (isExecException(error)) {
+      const stderr = error.stderr ? error.stderr.toString() : "";
+      if (stderr.includes(`fatal: reference is not a tree: ${ref}`) || stderr.includes(`fatal: ambiguous argument '${ref}'`) || stderr.includes(`unknown revision or path not in the working tree`)) {
+        consola.error(`Ref '${ref}' not found in the repository.`);
+      } else {
+        consola.error(`Error checking out ref '${ref}':`, stderr.trim());
+      }
+    } else if (error instanceof Error) {
+      consola.error(`Error checking out ref '${ref}':`, error.message);
+    } else {
+      consola.error(`Unknown error occurred while checking out ref '${ref}'.`);
+    }
+    consola.warn(`Falling back to the default branch.`);
+  }
+}
+
+// src/cli/lib/has-github-ssh.ts
+import { execSync as execSync2 } from "child_process";
+function hasGitHubSSH() {
+  try {
+    const output = execSync2("ssh -T git@github.com", {
+      encoding: "utf8",
+      stdio: "pipe"
+    }).toString();
+    return output.includes("successfully authenticated");
+  } catch (error) {
+    if (isExecException(error)) {
+      const stdout = error.stdout ? error.stdout.toString() : "";
+      const stderr = error.stderr ? error.stderr.toString() : "";
+      const combinedOutput = stdout + stderr;
+      if (combinedOutput.includes("successfully authenticated")) {
+        return true;
+      }
+    }
+    return false;
+  }
+}
+
+// src/cli/lib/reset-branch-to-ref.ts
+import { sync as spawnSync2 } from "cross-spawn";
+function resetBranchToRef(projectDir, ghRef) {
+  const spawn = spawnSync2("git", ["reset", "--hard", ghRef, "--"], {
+    cwd: projectDir,
+    encoding: "utf8",
+    shell: false
+  });
+  const stderr = spawn.stderr.trim();
+  if (spawn.status !== 0 && stderr) {
+    throw new Error(stderr);
+  }
+}
+
+// src/cli/lib/clone-catalyst.ts
+var cloneCatalyst = ({
+  repository,
+  projectName,
+  projectDir,
+  ghRef,
+  resetMain = false
+}) => {
+  const useSSH = hasGitHubSSH();
+  consola.info(`Cloning ${repository} using ${useSSH ? "SSH" : "HTTPS"}...`);
+  const cloneCommand = `git clone ${useSSH ? `git@github.com:${repository}` : `https://github.com/${repository}`}.git${projectName ? ` ${projectName}` : ""}`;
+  execSync3(cloneCommand, { stdio: "inherit" });
+  execSync3("git remote rename origin upstream", { cwd: projectDir, stdio: "inherit" });
+  if (ghRef) {
+    if (resetMain) {
+      execSync3("git checkout -b main", { cwd: projectDir, stdio: "inherit" });
+      resetBranchToRef(projectDir, ghRef);
+      consola.success(`Reset main to ${ghRef} successfully.`);
+      return;
+    }
+    checkoutRef(projectDir, ghRef);
+  }
+};
+
+// src/cli/lib/install-dependencies.ts
+import { installDependencies as installDeps } from "nypm";
+import yoctoSpinner3 from "yocto-spinner";
+var installDependencies = async (projectDir) => {
+  const spinner = yoctoSpinner3().start("Installing dependencies. This could take a minute...");
+  try {
+    await installDeps({ cwd: projectDir, silent: true, packageManager: "pnpm" });
+    spinner.success("Dependencies installed successfully.");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "unknown error";
+    spinner.error(`Failed to install dependencies: ${message}`);
+    throw error;
+  }
+};
+
+// 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/setup-core-project.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname3, join as join7 } from "path";
+import { z as z9 } from "zod";
+var corePackageJsonSchema2 = z9.looseObject({
+  scripts: z9.record(z9.string(), z9.string()).optional(),
+  dependencies: z9.record(z9.string(), z9.string()).optional()
+});
+var writeJson2 = (path, value) => {
+  mkdirSync2(dirname3(path), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify(value, null, 2)}
+`);
+};
+var setupCoreProject = (projectDir) => {
+  const corePackageJsonPath = join7(projectDir, "core", "package.json");
+  const pkg = corePackageJsonSchema2.parse(JSON.parse(readFileSync3(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,
+    "@bigcommerce/catalyst": package_default.version
+  };
+  writeJson2(corePackageJsonPath, sortPackageJsonFields(pkg));
+};
+
+// src/cli/lib/write-env.ts
+import { outputFileSync } from "fs-extra/esm";
+import { join as join8 } from "path";
+var writeEnv = (projectDir, envVars) => {
+  outputFileSync(
+    join8(projectDir, "core", ".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";
+  return isWindows ? `where.exe ${command}` : `which ${command}`;
+}
+function parseChannelId(value) {
+  const parsed = parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    throw new InvalidArgumentError(`"${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 InvalidArgumentError(`Expected KEY=VALUE, got "${value}".`);
+  }
+  const key = value.substring(0, eqIdx);
+  const val = value.substring(eqIdx + 1);
+  if (!val) {
+    throw new InvalidArgumentError(`Expected KEY=VALUE with non-empty value, got "${value}".`);
+  }
+  return { ...previous, [key]: val };
+}
+async function handleChannelCreation(storeHash, accessToken, apiHost, cliApiOrigin) {
+  const newChannelName = await input2({
+    message: "What would you like to name your new channel?"
+  });
+  const availableLocales = await getAvailableLocales(storeHash, accessToken, apiHost);
+  const storefrontLocale = await select2({
+    message: "Which default language would you like to set for your channel?",
+    default: "en",
+    choices: availableLocales,
+    theme: {
+      style: {
+        help: () => colorize3("dim", "(Select locale from the list or start typing the name)")
+      }
+    }
+  });
+  const shouldAddAdditionalLocales = await select2({
+    message: "Would you like to add additional languages?",
+    choices: [
+      { name: "Yes", value: true },
+      { name: "No", value: false }
+    ]
+  });
+  let additionalLocales = [];
+  if (shouldAddAdditionalLocales) {
+    const localeOptions = availableLocales.filter(({ value }) => value !== storefrontLocale).map(({ name, value }) => ({ label: name, value, hint: value }));
+    const pickLocales = async () => {
+      const selected = await consola.prompt(
+        "Which additional languages would you like to add to your channel?",
+        { type: "multiselect", options: localeOptions, cancel: "reject" }
+      );
+      if (selected.length > 4) {
+        consola.warn("You can only select up to 4 additional languages. Please try again.");
+        return pickLocales();
+      }
+      return selected;
+    };
+    additionalLocales = await pickLocales();
+  }
+  const shouldInstallSampleData = await select2({
+    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 channelSortOrder = ["catalyst", "next", "bigcommerce"];
+  const channels = await fetchAvailableChannels(storeHash, accessToken, apiHost);
+  const existingChannel = await select2({
+    message: "Which channel would you like to use?",
+    choices: channels.sort((a, b) => {
+      const aIndex = channelSortOrder.indexOf(a.platform);
+      const bIndex = channelSortOrder.indexOf(b.platform);
+      if (aIndex === -1 && bIndex === -1) {
+        return 0;
+      }
+      if (aIndex === -1) return 1;
+      if (bIndex === -1) return -1;
+      return aIndex - bIndex;
+    }).map((ch) => ({
+      name: ch.name,
+      value: ch,
+      description: `Channel Platform: ${ch.platform === "bigcommerce" ? "Stencil" : ch.platform.charAt(0).toUpperCase() + ch.platform.slice(1)}`
+    }))
+  });
+  return existingChannel.id;
+}
+async function setupProject(options) {
+  let { projectName, projectDir } = options;
+  if (!pathExistsSync(projectDir)) {
+    consola.error(`--project-dir ${projectDir} is not a valid path`);
+    process.exit(1);
+  }
+  if (projectName) {
+    projectName = kebabCase(projectName);
+    projectDir = join9(options.projectDir, projectName);
+    if (pathExistsSync(projectDir)) {
+      consola.error(`${projectDir} already exists`);
+      process.exit(1);
+    }
+  }
+  if (!projectName) {
+    const validateProjectName = (i) => {
+      const formatted = kebabCase(i);
+      if (!formatted) return "Project name is required";
+      const targetDir = join9(options.projectDir, formatted);
+      if (pathExistsSync(targetDir)) return `Destination '${targetDir}' already exists`;
+      projectName = formatted;
+      projectDir = targetDir;
+      return true;
+    };
+    await input2({
+      message: "What do you want to name your project directory?",
+      default: "my-catalyst-app",
+      validate: validateProjectName
+    });
+  }
+  if (!projectName) throw new Error("Something went wrong, projectName is not defined");
+  if (!projectDir) throw new Error("Something went wrong, projectDir is not defined");
+  return { projectName, projectDir };
+}
+function checkRequiredTools() {
+  try {
+    execSync4(getPlatformCheckCommand("git"), { stdio: "ignore" });
+  } catch {
+    consola.error("git is required to create a Catalyst project");
+    process.exit(1);
+  }
+  try {
+    execSync4(getPlatformCheckCommand("pnpm"), { stdio: "ignore" });
+  } catch {
+    consola.error(
+      "pnpm is required to create a Catalyst project. Enable it by running `corepack enable pnpm`."
+    );
+    process.exit(1);
+  }
+}
+var create = new Command4("create").configureHelp({ showGlobalOptions: true }).description("Scaffold and connect a Catalyst storefront to your BigCommerce store.").addHelpText(
+  "after",
+  `
+Examples:
+  # Interactive scaffold (default \u2014 self-hosted, no hosting prompt)
+  $ catalyst create
+
+  # Non-interactive: skip the project-name prompt
+  $ catalyst create --project-name my-store
+
+  # Eagerly set up Commerce Hosting at create time
+  $ catalyst create --project-name my-store --hosting commerce`
+).option("--project-name <name>", "Name of your Catalyst project").option("--project-dir <dir>", "Directory in which to create your project", process.cwd()).addOption(storeHashOption()).addOption(accessTokenOption()).option("--channel-id <id>", "BigCommerce channel ID", parseChannelId).option("--storefront-token <token>", "BigCommerce storefront token").option(
+  "--gh-ref <ref>",
+  "Clone a specific ref from the source repository",
+  "@bigcommerce/catalyst-core@latest"
+).option("--reset-main", "Reset the main branch to the gh-ref").option("--repository <repository>", "GitHub repository to clone from", "bigcommerce/catalyst").option(
+  "--env <vars...>",
+  "Arbitrary environment variables to set in .env.local. Format: KEY=VALUE (repeatable).",
+  parseEnvFlag
+).addOption(
+  new Option5(
+    "--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"])
+).option(
+  "--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()
+).addOption(
+  new Option5("--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()
+).action(async (options) => {
+  const { ghRef, repository } = options;
+  if (options.useExisting && options.hosting !== "commerce") {
+    consola.warn("--use-existing has no effect without --hosting commerce. Ignoring.");
+  }
+  checkRequiredTools();
+  const { projectName, projectDir } = await setupProject({
+    projectName: options.projectName,
+    projectDir: options.projectDir
+  });
+  let storeHash = options.storeHash;
+  let accessToken = options.accessToken;
+  let channelId = options.channelId;
+  let storefrontToken = options.storefrontToken;
+  let envVars = {};
+  if (!storeHash || !accessToken) {
+    const apiHost = `api.${options.bigcommerceHostname}`;
+    try {
+      const credentials = await login(options.loginUrl, apiHost);
+      storeHash = credentials.storeHash;
+      accessToken = credentials.accessToken;
+    } catch (error) {
+      if (error instanceof LoginAbortedError) {
+        consola.info(
+          "Login aborted. Re-run `catalyst create` when you have your credentials ready."
+        );
+        process.exit(0);
+        return;
+      }
+      throw error;
+    }
+  }
+  const useCommerceHosting = options.hosting === "commerce";
+  await getTelemetry().identify(storeHash);
+  if (storeHash && channelId && storefrontToken) {
+    envVars.BIGCOMMERCE_STORE_HASH = storeHash;
+    envVars.BIGCOMMERCE_CHANNEL_ID = channelId.toString();
+    envVars.BIGCOMMERCE_STOREFRONT_TOKEN = storefrontToken;
+  }
+  if (storeHash && accessToken && (!channelId || !storefrontToken)) {
+    const apiHost = `api.${options.bigcommerceHostname}`;
+    const cliApiOrigin = options.cliApiOrigin;
+    if (channelId && !storefrontToken) {
+      const initData = await getChannelInit(channelId, storeHash, accessToken, cliApiOrigin);
+      envVars = { ...initData.envVars };
+      storefrontToken = initData.storefrontToken;
+    } else if (!channelId) {
+      const eligibility = await checkChannelEligibility(storeHash, accessToken, cliApiOrigin);
+      if (!eligibility.eligible) {
+        consola.warn(eligibility.message);
+      }
+      let shouldCreateChannel;
+      if (eligibility.eligible) {
+        shouldCreateChannel = await select2({
+          message: "Would you like to create a new channel?",
+          choices: [
+            { name: "Yes", value: true },
+            { name: "No", value: false }
+          ]
+        });
+      }
+      if (shouldCreateChannel) {
+        const channelData = await handleChannelCreation(
+          storeHash,
+          accessToken,
+          apiHost,
+          cliApiOrigin
+        );
+        channelId = channelData.channelId;
+        storefrontToken = channelData.storefrontToken;
+        envVars = { ...channelData.envVars };
+        consola.success("Channel created successfully.");
+        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."
+        );
+      }
+      if (!shouldCreateChannel) {
+        channelId = await handleChannelSelection(storeHash, accessToken, apiHost);
+        const initData = await getChannelInit(channelId, storeHash, accessToken, cliApiOrigin);
+        envVars = { ...initData.envVars };
+        storefrontToken = initData.storefrontToken;
+      }
+    }
+  }
+  if (options.env) {
+    Object.assign(envVars, options.env);
+  }
+  if (options.storeHash) envVars.BIGCOMMERCE_STORE_HASH = options.storeHash;
+  if (options.channelId) envVars.BIGCOMMERCE_CHANNEL_ID = options.channelId.toString();
+  if (options.storefrontToken) envVars.BIGCOMMERCE_STOREFRONT_TOKEN = options.storefrontToken;
+  if (useCommerceHosting && accessToken) {
+    envVars.BIGCOMMERCE_ACCESS_TOKEN = accessToken;
+  }
+  if (accessToken) envVars.CATALYST_ACCESS_TOKEN = accessToken;
+  let commerceHostingProject;
+  if (useCommerceHosting && storeHash && accessToken) {
+    const apiHost = `api.${options.bigcommerceHostname}`;
+    const hasAccess = await hasProjectsAccess(storeHash, accessToken, apiHost);
+    if (!hasAccess) {
+      consola.error(
+        "This store does not have access to the Infrastructure Projects API. Contact support@bigcommerce.com to enable it."
+      );
+      process.exit(1);
+    }
+    commerceHostingProject = await promptForCommerceHostingProject(
+      { storeHash, accessToken, apiHost },
+      projectName,
+      !!options.projectName,
+      options.useExisting
+    );
+  }
+  consola.info(`Creating '${projectName}' at '${projectDir}'`);
+  try {
+    cloneCatalyst({ repository, projectName, projectDir, ghRef, resetMain: options.resetMain });
+    setupCoreProject(projectDir);
+    if (useCommerceHosting && commerceHostingProject && storeHash && accessToken) {
+      await setupCommerceHosting({
+        projectDir,
+        projectUuid: commerceHostingProject.uuid,
+        storeHash,
+        accessToken
+      });
+    }
+    writeEnv(projectDir, envVars);
+    await installDependencies(projectDir);
+    buildWorkspacePackages(projectDir);
+  } catch (error) {
+    if (pathExistsSync(projectDir)) {
+      consola.warn(
+        `Setup failed before completion. '${projectDir}' may be in a partial state \u2014 review and delete it before re-running 'catalyst create'.`
+      );
+    }
+    throw error;
+  }
+  consola.success(`Created '${projectName}' at '${projectDir}'`);
+  consola.info("Next steps:");
+  consola.info(colorize3("yellow", `  cd ${projectName}/core && pnpm run dev`));
+  if (useCommerceHosting) {
+    consola.info(
+      colorize3(
+        "yellow",
+        `  Run 'cd ${projectName}/core && pnpm run deploy' when ready to deploy to Commerce Hosting.`
+      )
+    );
+  }
+});
+
+// src/cli/commands/deploy.ts
+import AdmZip from "adm-zip";
+import { Command as Command5, Option as Option6 } from "commander";
+import { colorize as colorize4 } from "consola/utils";
+import { access, readdir, readFile } from "fs/promises";
+import { dirname as dirname4, join as join10 } from "path";
+import yoctoSpinner4 from "yocto-spinner";
+import { z as z10 } from "zod";
+
+// src/cli/lib/deployment-errors.ts
+var ERROR_MESSAGES = {
+  10: "Something went wrong on our end. Please try again. If the issue persists, contact support.",
+  20: "We couldn't retrieve your bundle. This is usually a temporary issue \u2014 please try deploying again. If the problem continues, contact support.",
+  30: "Your bundle could not be extracted. This may mean your build output is too large (max 64 MB compressed / 512 MB uncompressed) or the archive is corrupted. Try reducing your build size or rebuilding your project and deploying again.",
+  40: `There's a problem with your build output. This could be caused by:
+- A worker.js file larger than 40 MB
+- An individual asset file larger than 25 MB
+- More than 1,000 total files in the bundle`,
+  50: "Deployment failed. This is usually a temporary issue \u2014 please try again. If the problem persists, contact support.",
+  60: "Your code was deployed, but we couldn't determine your deployment URL. Please try deploying again. If the issue persists, contact support."
+};
+function getDeploymentErrorMessage(code) {
+  return ERROR_MESSAGES[code] ?? `Deployment failed with an unexpected error (code: ${code}). Please try again. If the issue persists, contact support.`;
+}
+
+// src/cli/lib/env-config.ts
+var ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var parseEnvAssignment = (input3) => {
+  const separatorIndex = input3.indexOf("=");
+  if (separatorIndex === -1) {
+    throw new Error(`Invalid env var format: ${input3}. Expected format: KEY=VALUE`);
+  }
+  const key = input3.slice(0, separatorIndex).trim();
+  const value = input3.slice(separatorIndex + 1).trim();
+  if (!key || !value) {
+    throw new Error(`Invalid env var format: ${input3}. Expected format: KEY=VALUE`);
+  }
+  if (!ENV_KEY_PATTERN.test(key)) {
+    throw new Error(
+      `Invalid env var name: ${key}. Names must start with a letter or underscore and contain only letters, numbers, and underscores.`
+    );
+  }
+  return { key, value };
+};
+var getStoredEnv = (config2) => {
+  return config2.get("env") ?? {};
+};
+var toDeploymentSecrets = (envVars) => {
+  return Object.entries(envVars).map(([key, value]) => ({ type: "secret", key, value }));
+};
+var mergeDeploymentSecrets = (persisted, flagSecrets) => {
+  const byKey = /* @__PURE__ */ new Map();
+  persisted.forEach((secret) => byKey.set(secret.key, secret));
+  flagSecrets.forEach((secret) => byKey.set(secret.key, secret));
+  return Array.from(byKey.values());
+};
+
 // src/cli/commands/deploy.ts
-var stepsEnum = z4.enum([
+var stepsEnum = z10.enum([
   "initializing",
   "downloading",
   "unzipping",
@@ -687,41 +2204,41 @@ var STEPS = {
   finalizing: "Finalizing...",
   complete: "Complete"
 };
-var UploadSignatureSchema = z4.object({
-  data: z4.object({
-    upload_url: z4.url(),
-    upload_uuid: z4.string()
+var UploadSignatureSchema = z10.object({
+  data: z10.object({
+    upload_url: z10.url(),
+    upload_uuid: z10.string()
   })
 });
-var CreateDeploymentSchema = z4.object({
-  data: z4.object({
-    deployment_uuid: z4.uuid()
+var CreateDeploymentSchema = z10.object({
+  data: z10.object({
+    deployment_uuid: z10.uuid()
   })
 });
-var ProjectSchema = z4.object({
-  data: z4.array(
-    z4.object({
-      uuid: z4.uuid(),
-      name: z4.string()
+var ProjectSchema = z10.object({
+  data: z10.array(
+    z10.object({
+      uuid: z10.uuid(),
+      name: z10.string()
     })
   )
 });
-var DeploymentStatusSchema = z4.object({
-  deployment_uuid: z4.uuid(),
-  deployment_status: z4.enum(["queued", "in_progress", "failed", "completed"]),
-  event: z4.object({
+var DeploymentStatusSchema = z10.object({
+  deployment_uuid: z10.uuid(),
+  deployment_status: z10.enum(["queued", "in_progress", "failed", "completed"]),
+  event: z10.object({
     step: stepsEnum,
-    progress: z4.number()
+    progress: z10.number()
   }).nullable(),
-  deployment_url: z4.string().nullable(),
-  error: z4.object({
-    code: z4.number()
+  deployment_hostnames: z10.array(z10.string()).optional(),
+  error: z10.object({
+    code: z10.number()
   }).optional()
 });
 var generateBundleZip = async () => {
   consola.info("Generating bundle...");
-  const bigcommerceDir = join4(process.cwd(), ".bigcommerce");
-  const distDir = join4(process.cwd(), ".bigcommerce", "dist");
+  const bigcommerceDir = join10(process.cwd(), ".bigcommerce");
+  const distDir = join10(process.cwd(), ".bigcommerce", "dist");
   try {
     await access(distDir);
   } catch {
@@ -731,7 +2248,7 @@ var generateBundleZip = async () => {
   if (buildDirContents.length === 0) {
     throw new Error(`Dist directory is empty: ${distDir}`);
   }
-  const outputZip = join4(bigcommerceDir, "bundle.zip");
+  const outputZip = join10(bigcommerceDir, "bundle.zip");
   const zip = new AdmZip();
   zip.addLocalFolder(distDir, "output");
   zip.writeZip(outputZip);
@@ -752,6 +2269,7 @@ var generateUploadSignature = async (storeHash, accessToken, apiHost) => {
       body: JSON.stringify({})
     }
   );
+  assertAuthorized(response);
   if (!response.ok) {
     throw new Error(`Failed to fetch upload signature: ${response.status} ${response.statusText}`);
   }
@@ -762,7 +2280,7 @@ var generateUploadSignature = async (storeHash, accessToken, apiHost) => {
 };
 var uploadBundleZip = async (uploadUrl) => {
   consola.info("Uploading bundle...");
-  const zipPath = join4(process.cwd(), ".bigcommerce", "bundle.zip");
+  const zipPath = join10(process.cwd(), ".bigcommerce", "bundle.zip");
   const fileBuffer = await readFile(zipPath);
   const response = await fetch(uploadUrl, {
     method: "PUT",
@@ -779,41 +2297,14 @@ var uploadBundleZip = async (uploadUrl) => {
 };
 var parseEnvironmentVariables = (secretOption) => {
   return secretOption?.map((envVar) => {
-    const [key, value] = envVar.split("=");
-    if (!key || !value) {
-      throw new Error(`Invalid secret format: ${envVar}. Expected format: KEY=VALUE`);
-    }
+    const { key, value } = parseEnvAssignment(envVar);
     return {
       type: "secret",
-      key: key.trim(),
-      value: value.trim()
+      key,
+      value
     };
   });
 };
-var AUTO_DETECT_SECRETS = [
-  { key: "BIGCOMMERCE_STORE_HASH", warnIfMissing: true },
-  { key: "BIGCOMMERCE_CHANNEL_ID", warnIfMissing: true },
-  { key: "BIGCOMMERCE_STOREFRONT_TOKEN", warnIfMissing: true },
-  { key: "BIGCOMMERCE_API_HOST", warnIfMissing: false },
-  { key: "BIGCOMMERCE_GRAPHQL_API_DOMAIN", warnIfMissing: false },
-  { key: "AUTH_SECRET", warnIfMissing: false }
-];
-var autoDetectSecrets = (environmentVariables) => {
-  const secrets = environmentVariables ?? [];
-  const existingKeys = new Set(secrets.map((s) => s.key));
-  AUTO_DETECT_SECRETS.forEach(({ key, warnIfMissing }) => {
-    if (existingKeys.has(key)) {
-      return;
-    }
-    const value = process.env[key];
-    if (value) {
-      secrets.push({ type: "secret", key, value });
-    } else if (warnIfMissing) {
-      consola.warn(`${key} is not set in the environment and was not provided via --secret.`);
-    }
-  });
-  return secrets;
-};
 var createDeployment = async (projectUuid, uploadUuid, storeHash, accessToken, apiHost, environmentVariables) => {
   consola.info("Creating deployment...");
   const response = await fetch(
@@ -833,6 +2324,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}`);
   }
@@ -843,7 +2335,7 @@ var createDeployment = async (projectUuid, uploadUuid, storeHash, accessToken, a
 };
 var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost) => {
   consola.info("Fetching deployment status...");
-  const spinner = yoctoSpinner2().start("Fetching...");
+  const spinner = yoctoSpinner4().start("Fetching...");
   const response = await fetch(
     `https://${apiHost}/stores/${storeHash}/v3/infrastructure/deployments/${deploymentUuid}/events`,
     {
@@ -856,6 +2348,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}`);
   }
@@ -865,7 +2358,7 @@ var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost
   }
   const decoder = new TextDecoder();
   let done = false;
-  let deploymentUrl;
+  let deploymentHostname;
   while (!done) {
     const { value, done: streamDone } = await reader.read();
     let json;
@@ -888,40 +2381,57 @@ var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost
         if (data.event && STEPS[data.event.step] !== spinner.text) {
           spinner.text = STEPS[data.event.step];
         }
-        if (data.deployment_url) {
-          deploymentUrl = data.deployment_url;
+        if (data.deployment_hostnames && data.deployment_hostnames.length > 0) {
+          deploymentHostname = data.deployment_hostnames[0];
         }
       });
     }
     done = streamDone;
   }
   spinner.success("Deployment completed successfully.");
-  if (deploymentUrl) {
-    const url = deploymentUrl.startsWith("https://") ? deploymentUrl : `https://${deploymentUrl}`;
-    consola.success(`View your deployment at: ${colorize2("blue", url)}`);
+  if (deploymentHostname) {
+    consola.success(
+      `View your deployment at: ${colorize4("blue", `https://${deploymentHostname}`)}`
+    );
   }
+  return deploymentHostname;
 };
-var deploy = new Command3("deploy").description("Deploy your application to Cloudflare.").addOption(
-  new Option3(
-    "--store-hash <hash>",
-    "BigCommerce store hash. Can be found in the URL of your store Control Panel. Read from .bigcommerce/project.json when not provided."
-  ).env("CATALYST_STORE_HASH")
-).addOption(
-  new Option3(
-    "--access-token <token>",
-    "BigCommerce access token. Can be found after creating a store-level API account. Read from .bigcommerce/project.json when not provided."
-  ).env("CATALYST_ACCESS_TOKEN")
-).addOption(
-  new Option3("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com")
-).addOption(
-  new Option3(
-    "--project-uuid <uuid>",
-    "BigCommerce intrastructure project UUID. Can be found via the BigCommerce API (GET /v3/infrastructure/projects)."
-  ).env("CATALYST_PROJECT_UUID")
+var fetchProject = async (projectUuid, storeHash, accessToken, apiHost) => {
+  const response = await fetch(
+    `https://${apiHost}/stores/${storeHash}/v3/infrastructure/projects`,
+    {
+      method: "GET",
+      headers: {
+        "X-Auth-Token": accessToken,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-Correlation-Id": getTelemetry().correlationId
+      }
+    }
+  );
+  assertAuthorized(response);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch projects: ${response.status} ${response.statusText}`);
+  }
+  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(
+  "after",
+  `
+Environment variables saved with \`catalyst env add\` are sent automatically on every deploy.
+Use \`--secret\` to set or override a variable for a single run.
+
+Example:
+  $ catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN>`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option(
+  "--update-site-url",
+  "After a successful deploy, prompt to update a channel's site URL to the new hostname."
 ).addOption(
-  new Option3(
+  new Option6(
     "--secret <value>",
-    "Secret to set for the deployment (repeatable). Format: --secret KEY=VALUE"
+    "Secret to set for this deployment (repeatable). Overrides a stored value for the same key. Format: --secret KEY=VALUE"
   ).argParser((value, previous = []) => {
     return previous.concat([value]);
   })
@@ -932,15 +2442,69 @@ var deploy = new Command3("deploy").description("Deploy your application to Clou
   const config2 = getProjectConfig();
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   const telemetry3 = getTelemetry();
-  const projectUuid = options.projectUuid ?? config2.get("projectUuid");
-  if (!projectUuid) {
-    throw new Error(
-      "Project UUID is required. Please run either `catalyst project link` or `catalyst project create` or this command again with --project-uuid <uuid>."
+  await telemetry3.identify(storeHash);
+  const linkedProjectUuid = options.projectUuid ?? config2.get("projectUuid");
+  let projectUuid;
+  const promptForProject = async () => {
+    try {
+      return await selectOrCreateInfrastructureProject({
+        storeHash,
+        accessToken,
+        apiHost: options.apiHost
+      });
+    } catch (error) {
+      if (error instanceof NoLinkedProjectError) {
+        consola.info(
+          "When you're ready to create a project, run `catalyst project create` or re-run `catalyst deploy`."
+        );
+        process.exit(0);
+      }
+      throw error;
+    }
+  };
+  if (linkedProjectUuid) {
+    const existing = await fetchProject(
+      linkedProjectUuid,
+      storeHash,
+      accessToken,
+      options.apiHost
+    );
+    if (existing) {
+      projectUuid = linkedProjectUuid;
+    } else {
+      consola.warn(
+        `The linked project (${linkedProjectUuid}) no longer exists on this store. It may have been deleted.`
+      );
+      const selected = await promptForProject();
+      projectUuid = selected.uuid;
+      config2.set("projectUuid", projectUuid);
+      consola.success(`Linked project "${selected.name}".`);
+    }
+  } else {
+    consola.info("No project is currently linked.");
+    const selected = await promptForProject();
+    projectUuid = selected.uuid;
+    config2.set("projectUuid", projectUuid);
+    consola.success(`Linked project "${selected.name}".`);
+  }
+  if (!getProjectState().isTransformed) {
+    const shouldSetup = await consola.prompt(
+      "Your project is not yet set up for Commerce Hosting deployments. Would you like to run the Commerce Hosting setup now?",
+      { type: "confirm", initial: true }
     );
+    if (!shouldSetup) {
+      consola.info("When you're ready to deploy, re-run `catalyst deploy` to complete setup.");
+      process.exit(0);
+    }
+    const projectDir = dirname4(process.cwd());
+    await setupCommerceHosting({ projectDir, projectUuid, storeHash, accessToken });
+    consola.success("Commerce Hosting setup complete.");
+    await installDependencies(projectDir);
+  } else {
+    await cleanupCloudflareIncompatibilities(dirname4(process.cwd()));
   }
-  await telemetry3.identify(storeHash);
   if (options.prebuilt) {
-    const distDir = join4(process.cwd(), ".bigcommerce", "dist");
+    const distDir = join10(process.cwd(), ".bigcommerce", "dist");
     try {
       await access(distDir);
     } catch {
@@ -969,7 +2533,10 @@ var deploy = new Command3("deploy").description("Deploy your application to Clou
   }
   const uploadSignature = await generateUploadSignature(storeHash, accessToken, options.apiHost);
   await uploadBundleZip(uploadSignature.upload_url);
-  const environmentVariables = autoDetectSecrets(parseEnvironmentVariables(options.secret));
+  const flagSecrets = parseEnvironmentVariables(options.secret) ?? [];
+  const persistedSecrets = toDeploymentSecrets(getStoredEnv(config2));
+  const mergedSecrets = mergeDeploymentSecrets(persistedSecrets, flagSecrets);
+  const environmentVariables = mergedSecrets.length > 0 ? mergedSecrets : void 0;
   const { deployment_uuid: deploymentUuid } = await createDeployment(
     projectUuid,
     uploadSignature.upload_uuid,
@@ -978,41 +2545,109 @@ var deploy = new Command3("deploy").description("Deploy your application to Clou
     options.apiHost,
     environmentVariables
   );
-  await getDeploymentStatus(deploymentUuid, storeHash, accessToken, options.apiHost);
+  const deploymentHostname = await getDeploymentStatus(
+    deploymentUuid,
+    storeHash,
+    accessToken,
+    options.apiHost
+  );
+  if (!options.updateSiteUrl) {
+    return;
+  }
+  try {
+    await runChannelSiteUrlFlow({
+      storeHash,
+      accessToken,
+      apiHost: options.apiHost,
+      projectUuid,
+      preferHostname: deploymentHostname
+    });
+  } catch (error) {
+    consola.warn(
+      `Failed to update channel site URL: ${error instanceof Error ? error.message : String(error)}`
+    );
+    consola.info(
+      "Update it manually in the control panel, or re-run `catalyst auth login` if the token is missing the store_channel_settings scope."
+    );
+  }
 });
 
-// src/cli/commands/logs.ts
-import { Command as Command4, Option as Option5 } from "commander";
-import { colorize as colorize3 } from "consola/utils";
-import { z as z5 } from "zod";
-
-// src/cli/lib/shared-options.ts
-import { Option as Option4 } from "commander";
-var storeHashOption = () => new Option4(
-  "--store-hash <hash>",
-  "BigCommerce store hash. Can be found in the URL of your store Control Panel."
-).env("BIGCOMMERCE_STORE_HASH");
-var accessTokenOption = () => new Option4(
-  "--access-token <token>",
-  "BigCommerce access token. Can be found after creating a store-level API account."
-).env("BIGCOMMERCE_ACCESS_TOKEN");
-var apiHostOption = () => new Option4("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com");
-var projectUuidOption = () => new Option4(
-  "--project-uuid <uuid>",
-  "BigCommerce infrastructure project UUID. Can be found via the BigCommerce API (GET /v3/infrastructure/projects)."
-).env("BIGCOMMERCE_PROJECT_UUID");
-var resolveProjectUuid = (options) => {
+// src/cli/commands/env.ts
+import { Command as Command6 } from "commander";
+var MASK = "\u2022\u2022\u2022\u2022\u2022\u2022";
+var add = new Command6("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",
+  `
+Example:
+  $ catalyst env add BIGCOMMERCE_STORE_HASH=abc123 BIGCOMMERCE_STOREFRONT_TOKEN=ey...`
+).action((vars) => {
   const config2 = getProjectConfig();
-  const projectUuid = options.projectUuid ?? config2.get("projectUuid");
-  if (!projectUuid) {
-    throw new Error(
-      "Project UUID is required. Please run either `catalyst project link` or `catalyst project create` or this command again with --project-uuid <uuid>."
+  const stored = { ...getStoredEnv(config2) };
+  const parsed = vars.map((entry) => parseEnvAssignment(entry));
+  parsed.forEach(({ key, value }) => {
+    stored[key] = value;
+  });
+  config2.set("env", stored);
+  const keys = parsed.map(({ key }) => key);
+  consola.success(
+    `Saved ${keys.length} environment variable${keys.length === 1 ? "" : "s"} to .bigcommerce/project.json:`
+  );
+  keys.forEach((key) => consola.log(`  ${key}=${MASK}`));
+  process.exit(0);
+});
+var remove = new Command6("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:
+  $ catalyst env remove BIGCOMMERCE_STORE_HASH BIGCOMMERCE_STOREFRONT_TOKEN`
+).action((keys) => {
+  const config2 = getProjectConfig();
+  const stored = getStoredEnv(config2);
+  const toRemove = /* @__PURE__ */ new Set();
+  keys.forEach((key) => {
+    if (key in stored) {
+      toRemove.add(key);
+    } else {
+      consola.warn(`No stored environment variable named "${key}". Skipping.`);
+    }
+  });
+  const next = Object.fromEntries(Object.entries(stored).filter(([key]) => !toRemove.has(key)));
+  config2.set("env", next);
+  const removed = Array.from(toRemove);
+  if (removed.length > 0) {
+    consola.success(
+      `Removed ${removed.length} environment variable${removed.length === 1 ? "" : "s"}: ${removed.join(", ")}.`
     );
   }
-  return projectUuid;
-};
+  process.exit(0);
+});
+var list = new Command6("list").configureHelp({ showGlobalOptions: true }).description("List stored deployment environment variables (values are masked).").addHelpText(
+  "after",
+  `
+Example:
+  $ catalyst env list`
+).action(() => {
+  const config2 = getProjectConfig();
+  const stored = getStoredEnv(config2);
+  const keys = Object.keys(stored).sort();
+  if (keys.length === 0) {
+    consola.info("No environment variables stored. Add one with `catalyst env add KEY=VALUE`.");
+    process.exit(0);
+    return;
+  }
+  keys.forEach((key) => consola.log(`${key}=${MASK}`));
+  process.exit(0);
+});
+var env = new Command6("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(add).addCommand(remove).addCommand(list);
 
 // src/cli/commands/logs.ts
+import { Command as Command7, Option as Option7 } from "commander";
+import { colorize as colorize5 } from "consola/utils";
+import { z as z11 } from "zod";
 var telemetry = new Telemetry();
 var DEFAULT_CONNECTION_TTL_MS = 1 * 60 * 1e3;
 var MAX_RETRIES = 5;
@@ -1023,23 +2658,23 @@ var LEVEL_COLORS = {
   ERROR: "red",
   DEBUG: "gray"
 };
-var LogEventSchema = z5.object({
-  uuid: z5.string(),
-  project_uuid: z5.string(),
-  request: z5.object({
-    method: z5.string(),
-    url: z5.string(),
-    status_code: z5.number()
+var LogEventSchema = z11.object({
+  uuid: z11.string(),
+  project_uuid: z11.string(),
+  request: z11.object({
+    method: z11.string(),
+    url: z11.string(),
+    status_code: z11.number()
   }),
-  logs: z5.array(
-    z5.object({
-      timestamp: z5.string(),
-      level: z5.string(),
-      messages: z5.array(z5.unknown())
+  logs: z11.array(
+    z11.object({
+      timestamp: z11.string(),
+      level: z11.string(),
+      messages: z11.array(z11.unknown())
     })
   ),
-  exceptions: z5.array(z5.unknown()),
-  timestamp: z5.string()
+  exceptions: z11.array(z11.unknown()),
+  timestamp: z11.string()
 }).loose();
 var StreamError = class extends Error {
   constructor(message, fatal) {
@@ -1053,7 +2688,7 @@ var formatLogEvent = (event, format) => {
   logEntries.forEach((entry) => {
     const msg = formatMessages(entry.messages);
     const level = entry.level.toUpperCase();
-    const coloredLevel = colorize3(LEVEL_COLORS[level] ?? "white", level);
+    const coloredLevel = colorize5(LEVEL_COLORS[level] ?? "white", level);
     switch (format) {
       case "short":
         consola.log(msg);
@@ -1094,6 +2729,20 @@ var processLogEvent = (event, format) => {
     consola.warn(`Failed to parse log event: ${event}`);
   }
 };
+var raceWithTimeout = async (promise, timeoutMs) => {
+  let timeoutHandle;
+  const timeoutPromise = new Promise((resolve2) => {
+    timeoutHandle = setTimeout(() => resolve2({ kind: "timeout" }), timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      promise.then((value) => ({ kind: "value", value })),
+      timeoutPromise
+    ]);
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  }
+};
 var openLogStream = async (projectUuid, storeHash, accessToken, apiHost) => {
   const response = await fetch(
     `https://${apiHost}/stores/${storeHash}/v3/infrastructure/logs/${projectUuid}/tail`,
@@ -1106,6 +2755,9 @@ var openLogStream = async (projectUuid, storeHash, accessToken, apiHost) => {
       }
     }
   );
+  if (response.status === 401) {
+    throw new StreamError(new UnauthorizedError().message, true);
+  }
   if (!response.ok) {
     throw new StreamError(
       `Failed to open log stream: ${response.status} ${response.statusText}`,
@@ -1118,28 +2770,46 @@ var openLogStream = async (projectUuid, storeHash, accessToken, apiHost) => {
   }
   return reader;
 };
+var pumpUntilRotation = async (reader, format, connectionTtlMs) => {
+  const decoder = new TextDecoder();
+  const connectTime = Date.now();
+  let buffer = "";
+  let receivedData = false;
+  while (true) {
+    const remainingTtlMs = connectionTtlMs - (Date.now() - connectTime);
+    if (remainingTtlMs <= 0) {
+      void reader.cancel();
+      return "ttl";
+    }
+    const readResult = await raceWithTimeout(reader.read(), remainingTtlMs);
+    if (readResult.kind === "timeout") {
+      void reader.cancel();
+      return receivedData ? "ttl" : "idle-timeout";
+    }
+    const { value, done: streamDone } = readResult.value;
+    if (value) {
+      receivedData = true;
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split("\n\n");
+      buffer = parts.pop() ?? "";
+      parts.map((raw) => parseSSEEvent(raw)).filter((event) => event !== null).forEach((event) => processLogEvent(event, format));
+    }
+    if (streamDone) {
+      void reader.cancel();
+      return "stream-done";
+    }
+  }
+};
 var tailLogs = async (projectUuid, storeHash, accessToken, apiHost, format, connectionTtlMs = DEFAULT_CONNECTION_TTL_MS) => {
   consola.info("Tailing logs...");
   let retries = 0;
   while (true) {
     try {
       const reader = await openLogStream(projectUuid, storeHash, accessToken, apiHost);
-      const decoder = new TextDecoder();
-      const connectTime = Date.now();
-      let buffer = "";
       retries = 0;
-      while (true) {
-        const { value, done: streamDone } = await reader.read();
-        if (value) {
-          buffer += decoder.decode(value, { stream: true });
-          const parts = buffer.split("\n\n");
-          buffer = parts.pop() ?? "";
-          parts.map((raw) => parseSSEEvent(raw)).filter((event) => event !== null).forEach((event) => processLogEvent(event, format));
-        }
-        if (streamDone || Date.now() - connectTime >= connectionTtlMs) {
-          void reader.cancel();
-          break;
-        }
+      const rotation = await pumpUntilRotation(reader, format, connectionTtlMs);
+      if (rotation === "idle-timeout") {
+        consola.warn("Log stream idle, reconnecting...");
       }
     } catch (error) {
       if (error instanceof StreamError && error.fatal) {
@@ -1161,45 +2831,74 @@ var tailLogs = async (projectUuid, storeHash, accessToken, apiHost, format, conn
     }
   }
 };
-var tail = new Command4("tail").description("Tail live logs from your deployed application.").addOption(storeHashOption().makeOptionMandatory()).addOption(accessTokenOption().makeOptionMandatory()).addOption(apiHostOption()).addOption(projectUuidOption()).addOption(
-  new Option5("--format <format>", "Output format for log events.").choices(["json", "pretty", "default", "short", "request"]).default("default")
+var tail = new Command7("tail").configureHelp({ showGlobalOptions: true }).description("Tail live logs from your deployed application.").addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst logs tail
+
+  # Tail logs with request format
+  $ catalyst logs tail --format request
+
+  # Tail logs as raw JSON (useful for piping to other tools)
+  $ catalyst logs tail --format json`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).addOption(
+  new Option7("--format <format>", "Output format for log events.").choices(["json", "pretty", "default", "short", "request"]).default("default")
 ).action(async (options) => {
   try {
-    await telemetry.identify(options.storeHash);
+    const config2 = getProjectConfig();
+    const { storeHash, accessToken } = resolveCredentials(options, config2);
+    await telemetry.identify(storeHash);
     const projectUuid = resolveProjectUuid(options);
-    await tailLogs(
-      projectUuid,
-      options.storeHash,
-      options.accessToken,
-      options.apiHost,
-      options.format
-    );
+    await tailLogs(projectUuid, storeHash, accessToken, options.apiHost, options.format);
   } catch (error) {
     consola.error(error);
     process.exit(1);
   }
 });
-var query = new Command4("query").description("Query historical logs from your deployed application.").addOption(storeHashOption().makeOptionMandatory()).addOption(accessTokenOption().makeOptionMandatory()).addOption(apiHostOption()).addOption(projectUuidOption()).action((_options) => {
+var query = new Command7("query").configureHelp({ showGlobalOptions: true }).description("Query historical logs from your deployed application.").addHelpText(
+  "after",
+  `
+Example:
+  $ catalyst logs query`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).action((options) => {
+  const config2 = getProjectConfig();
+  resolveCredentials(options, config2);
   consola.error("The query command is not yet implemented.");
   process.exit(1);
 });
-var logs = new Command4("logs").description("View logs from your deployed application.").addCommand(tail, { isDefault: true }).addCommand(query);
+var logs = new Command7("logs").configureHelp({ showGlobalOptions: true }).description("View logs from your deployed application.").addCommand(tail, { isDefault: true }).addCommand(query);
 
 // src/cli/commands/project.ts
-import { Command as Command5, Option as Option6 } from "commander";
-var list = new Command5("list").description("List BigCommerce infrastructure projects for your store.").addOption(
-  new Option6(
-    "--store-hash <hash>",
-    "BigCommerce store hash. Can be found in the URL of your store Control Panel."
-  ).env("CATALYST_STORE_HASH")
-).addOption(
-  new Option6(
-    "--access-token <token>",
-    "BigCommerce access token. Can be found after creating a store-level API account."
-  ).env("CATALYST_ACCESS_TOKEN")
-).addOption(
-  new Option6("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com")
-).action(async (options) => {
+import { Command as Command8 } from "commander";
+import { colorize as colorize6 } from "consola/utils";
+import { dirname as dirname5 } from "path";
+async function offerCommerceHostingSetup(projectUuid, credentials) {
+  const projectDir = dirname5(process.cwd());
+  if (getProjectState().isTransformed) {
+    await cleanupCloudflareIncompatibilities(projectDir);
+    return;
+  }
+  const shouldSetup = await consola.prompt(
+    "Your project has been linked, but is not fully set up for Commerce Hosting deployments yet. Would you like to run the setup now?",
+    { type: "confirm", initial: true }
+  );
+  if (!shouldSetup) return;
+  await setupCommerceHosting({
+    projectDir,
+    projectUuid,
+    storeHash: credentials?.storeHash,
+    accessToken: credentials?.accessToken
+  });
+  consola.success("Commerce Hosting setup complete.");
+  await installDependencies(projectDir);
+}
+var list2 = new Command8("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 { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
@@ -1211,28 +2910,54 @@ var list = new Command5("list").description("List BigCommerce infrastructure pro
     process.exit(0);
     return;
   }
+  const linkedProjectUuid = config2.get("projectUuid");
   projects.forEach((p) => {
-    consola.log(`${p.name} (${p.uuid})`);
+    const marker = p.uuid === linkedProjectUuid ? ` ${colorize6("green", "[linked]")}` : "";
+    consola.log(`${p.name} (${p.uuid})${marker}`);
+    if (p.deployment_hostnames.length === 0) {
+      consola.log("  (not deployed)");
+    } else {
+      p.deployment_hostnames.forEach((hostname) => {
+        consola.log(`  ${colorize6("blue", `https://${hostname}`)}`);
+      });
+    }
+    consola.log("");
   });
   process.exit(0);
 });
-var create = new Command5("create").description(
-  "Create a new BigCommerce infrastructure project and link it to your local Catalyst project."
-).addOption(
-  new Option6(
-    "--store-hash <hash>",
-    "BigCommerce store hash. Can be found in the URL of your store Control Panel."
-  ).env("CATALYST_STORE_HASH")
-).addOption(
-  new Option6(
-    "--access-token <token>",
-    "BigCommerce access token. Can be found after creating a store-level API account."
-  ).env("CATALYST_ACCESS_TOKEN")
-).addOption(
-  new Option6("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com")
-).action(async (options) => {
+var create2 = new Command8("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",
+  `
+Example:
+  $ catalyst project create`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).action(async (options) => {
   const config2 = getProjectConfig();
-  const { storeHash, accessToken } = resolveCredentials(options, config2);
+  let storeHash = options.storeHash ?? config2.get("storeHash");
+  let accessToken = options.accessToken ?? config2.get("accessToken");
+  if (!storeHash || !accessToken) {
+    consola.info(
+      "You're not logged in yet. Let's get you authenticated before creating a project."
+    );
+    try {
+      const credentials = await login(options.loginUrl, options.apiHost);
+      storeHash = credentials.storeHash;
+      accessToken = credentials.accessToken;
+      config2.set("storeHash", storeHash);
+      config2.set("accessToken", accessToken);
+      consola.success(`Logged in to store ${storeHash}.`);
+    } catch (error) {
+      if (error instanceof LoginAbortedError) {
+        consola.info(
+          "Login aborted. Re-run `catalyst project create` when you have your credentials ready."
+        );
+        process.exit(0);
+        return;
+      }
+      throw error;
+    }
+  }
   await getTelemetry().identify(storeHash);
   const newProjectName = await consola.prompt("Enter a name for the new project:", {
     type: "text"
@@ -1246,24 +2971,18 @@ var create = new Command5("create").description(
   consola.success("Project UUID written to .bigcommerce/project.json.");
   process.exit(0);
 });
-var link = new Command5("link").description(
+var link = new Command8("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."
-).addOption(
-  new Option6(
-    "--store-hash <hash>",
-    "BigCommerce store hash. Can be found in the URL of your store Control Panel."
-  ).env("CATALYST_STORE_HASH")
-).addOption(
-  new Option6(
-    "--access-token <token>",
-    "BigCommerce access token. Can be found after creating a store-level API account."
-  ).env("CATALYST_ACCESS_TOKEN")
-).addOption(
-  new Option6("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com")
-).option(
-  "--project-uuid <uuid>",
-  "BigCommerce infrastructure project UUID. Can be found via the BigCommerce API (GET /v3/infrastructure/projects). Use this to link directly without fetching projects."
-).action(async (options) => {
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Link interactively (prompts to select or create)
+  $ catalyst project link
+
+  # Link using a project UUID directly
+  $ catalyst project link --project-uuid <UUID>`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).action(async (options) => {
   const config2 = getProjectConfig();
   const writeProjectConfig = (uuid, credentials) => {
     consola.start("Writing project UUID to .bigcommerce/project.json...");
@@ -1276,63 +2995,142 @@ var link = new Command5("link").description(
   };
   if (options.projectUuid) {
     writeProjectConfig(options.projectUuid);
+    await offerCommerceHostingSetup(options.projectUuid);
     process.exit(0);
     return;
   }
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
-  consola.start("Fetching projects...");
-  const projects = await fetchProjects(storeHash, accessToken, options.apiHost);
-  consola.success("Projects fetched.");
-  const promptOptions = [
-    ...projects.map((proj) => ({
-      label: proj.name,
-      value: proj.uuid,
-      hint: proj.uuid
-    })),
-    {
-      label: "Create a new project",
-      value: "create",
-      hint: "Create a new infrastructure project for this BigCommerce store."
+  let selected;
+  try {
+    selected = await selectOrCreateInfrastructureProject(
+      { storeHash, accessToken, apiHost: options.apiHost },
+      config2.get("projectUuid")
+    );
+  } catch (error) {
+    if (error instanceof NoLinkedProjectError) {
+      consola.info(
+        "When you're ready to create a project, run `catalyst project create` or re-run `catalyst project link`."
+      );
+      process.exit(0);
+      throw error;
     }
-  ];
-  let projectUuid = await consola.prompt(
-    "Select a project or create a new project (Press <enter> to select).",
-    {
-      type: "select",
-      options: promptOptions,
-      cancel: "reject"
+    throw error;
+  }
+  writeProjectConfig(selected.uuid, { storeHash, accessToken });
+  await offerCommerceHostingSetup(selected.uuid, { storeHash, accessToken });
+  process.exit(0);
+});
+var del = new Command8("delete").configureHelp({ showGlobalOptions: true }).description(
+  "Permanently delete a BigCommerce infrastructure project. This action is irreversible."
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Select a project to delete interactively
+  $ catalyst project delete
+
+  # Delete a specific project (still prompts for confirmation)
+  $ catalyst project delete --project-uuid <UUID>
+
+  # Skip the confirmation prompt
+  $ 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 { 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);
+    consola.success("Projects fetched.");
+    if (projects.length === 0) {
+      consola.info("No projects found.");
+      process.exit(0);
+      return;
+    }
+    const linkedProjectUuid = config2.get("projectUuid");
+    const selected = await consola.prompt(
+      "Select a project to delete (Press <enter> to select).",
+      {
+        type: "select",
+        options: [
+          ...projects.map((p) => ({
+            label: p.uuid === linkedProjectUuid ? `${p.name} ${colorize6("green", "[linked]")}` : p.name,
+            value: p.uuid,
+            hint: p.uuid
+          })),
+          { label: "Cancel", value: "cancel", hint: "Exit without deleting any project." }
+        ],
+        cancel: "reject"
+      }
+    );
+    if (selected === "cancel") {
+      consola.info("Aborted. No project was deleted.");
+      process.exit(0);
+      return;
+    }
+    const matched = projects.find((p) => p.uuid === selected);
+    if (!matched) {
+      throw new Error(`Selected project ${String(selected)} not found in fetched list.`);
+    }
+    targetUuid = matched.uuid;
+    targetName = matched.name;
+  }
+  if (!options.force) {
+    const label = targetName ? `"${targetName}" (${targetUuid})` : targetUuid;
+    const confirmed = await consola.prompt(
+      `Are you sure you want to delete project ${label}? This action is irreversible and will permanently destroy the project and all of its data.`,
+      { type: "confirm", initial: false }
+    );
+    if (!confirmed) {
+      consola.info("Aborted. No project was deleted.");
+      process.exit(0);
+      return;
     }
-  );
-  if (projectUuid === "create") {
-    const newProjectName = await consola.prompt("Enter a name for the new project:", {
-      type: "text"
-    });
-    const data = await createProject(newProjectName, storeHash, accessToken, options.apiHost);
-    projectUuid = data.uuid;
-    consola.success(`Project "${data.name}" created successfully.`);
   }
-  writeProjectConfig(projectUuid, { storeHash, accessToken });
+  consola.start(`Deleting project ${targetUuid}...`);
+  await deleteProject(targetUuid, storeHash, accessToken, options.apiHost);
+  consola.success(`Project ${targetUuid} deleted.`);
+  if (config2.get("projectUuid") === targetUuid) {
+    config2.delete("projectUuid");
+    consola.info("Removed project UUID from .bigcommerce/project.json.");
+  }
   process.exit(0);
 });
-var project = new Command5("project").description("Manage your BigCommerce infrastructure project.").addCommand(create).addCommand(list).addCommand(link);
+var project = new Command8("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure project.").addCommand(create2).addCommand(list2).addCommand(link).addCommand(del);
 
 // src/cli/commands/start.ts
-import { Command as Command6 } from "commander";
+import { Command as Command9 } from "commander";
 import { execa as execa2 } from "execa";
-import { existsSync, lstatSync, symlinkSync } from "fs";
-import { join as join5, relative } from "path";
-var start = new Command6("start").description(
+import { existsSync as existsSync4, lstatSync as lstatSync2, symlinkSync as symlinkSync2 } from "fs";
+import { join as join11, relative } from "path";
+var start = new Command9("start").configureHelp({ showGlobalOptions: true }).description(
   "Start a local preview of your Catalyst storefront using the OpenNext Cloudflare adapter."
+).addHelpText(
+  "after",
+  `
+Example:
+  $ catalyst start`
 ).action(async () => {
-  const envLocal = join5(process.cwd(), ".env.local");
-  const devVars = join5(process.cwd(), ".bigcommerce", ".dev.vars");
-  if (existsSync(envLocal)) {
-    if (!existsSync(devVars)) {
-      const target = relative(join5(process.cwd(), ".bigcommerce"), envLocal);
-      symlinkSync(target, devVars);
+  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"], {
+      stdio: "inherit",
+      cwd: process.cwd()
+    });
+    return;
+  }
+  const envLocal = join11(process.cwd(), ".env.local");
+  const devVars = join11(process.cwd(), ".bigcommerce", ".dev.vars");
+  if (existsSync4(envLocal)) {
+    if (!existsSync4(devVars)) {
+      const target = relative(join11(process.cwd(), ".bigcommerce"), envLocal);
+      symlinkSync2(target, devVars);
       consola.success("Symlinked .bigcommerce/.dev.vars \u2192 .env.local");
-    } else if (!lstatSync(devVars).isSymbolicLink()) {
+    } else if (!lstatSync2(devVars).isSymbolicLink()) {
       consola.warn(
         ".bigcommerce/.dev.vars already exists and is not a symlink. Wrangler will use it instead of .env.local."
       );
@@ -1349,7 +3147,7 @@ var start = new Command6("start").description(
       "opennextjs-cloudflare",
       "preview",
       "--config",
-      join5(".bigcommerce", "wrangler.jsonc")
+      join11(".bigcommerce", "wrangler.jsonc")
     ],
     {
       stdio: "inherit",
@@ -1359,11 +3157,25 @@ var start = new Command6("start").description(
 });
 
 // src/cli/commands/telemetry.ts
-import { Argument, Command as Command7, Option as Option7 } from "commander";
-import { colorize as colorize4 } from "consola/utils";
+import { Argument, Command as Command10, Option as Option8 } from "commander";
+import { colorize as colorize7 } from "consola/utils";
 var telemetryService = getTelemetry();
 var isEnabled = telemetryService.isEnabled();
-var telemetry2 = new Command7("telemetry").addArgument(new Argument("[arg]").choices(["disable", "enable", "status"])).addOption(new Option7("--enable", `Enables CLI telemetry collection.`).conflicts("disable")).option("--disable", `Disables CLI telemetry collection.`).action((arg, options) => {
+var telemetry2 = new Command10("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",
+  `
+Examples:
+  # Show telemetry status
+  $ catalyst telemetry
+
+  # Enable telemetry collection
+  $ catalyst telemetry enable
+
+  # Disable telemetry collection
+  $ catalyst telemetry --disable`
+).addArgument(new Argument("[arg]").choices(["disable", "enable", "status"])).addOption(new Option8("--enable", `Enables CLI telemetry collection.`).conflicts("disable")).option("--disable", `Disables CLI telemetry collection.`).action((arg, options) => {
   if (options.enable || arg === "enable") {
     telemetryService.setEnabled(true);
     isEnabled = true;
@@ -1371,7 +3183,7 @@ var telemetry2 = new Command7("telemetry").addArgument(new Argument("[arg]").cho
   } else if (options.disable || arg === "disable") {
     telemetryService.setEnabled(false);
     if (isEnabled) {
-      consola.success("Your preference has been saved to .bigcommerce/project.json");
+      consola.success("Your preference has been saved.");
     } else {
       consola.info(`Catalyst CLI telemetry collection is already disabled.`);
     }
@@ -1380,7 +3192,7 @@ var telemetry2 = new Command7("telemetry").addArgument(new Argument("[arg]").cho
     consola.info("Catalyst CLI Telemetry\n");
   }
   consola.info(
-    `Status: ${colorize4("bold", isEnabled ? colorize4("green", "Enabled") : colorize4("red", "Disabled"))}`
+    `Status: ${colorize7("bold", isEnabled ? colorize7("green", "Enabled") : colorize7("red", "Disabled"))}`
   );
   if (!isEnabled) {
     consola.info(
@@ -1390,8 +3202,13 @@ var telemetry2 = new Command7("telemetry").addArgument(new Argument("[arg]").cho
 });
 
 // src/cli/commands/version.ts
-import { Command as Command8 } from "commander";
-var version = new Command8("version").description("Display detailed version information.").action(() => {
+import { Command as Command11 } from "commander";
+var version = new Command11("version").configureHelp({ showGlobalOptions: true }).description("Display detailed version information.").addHelpText(
+  "after",
+  `
+Example:
+  $ catalyst version`
+).action(() => {
   consola.log("Version Information:");
   consola.log(`CLI Version: ${package_default.version}`);
   consola.log(`Node Version: ${process.version}`);
@@ -1447,11 +3264,20 @@ var telemetryPostHook = async () => {
 };
 
 // src/cli/program.ts
-var program = new Command9();
-consola.log(colorize5("cyanBright", `\u25E2 ${package_default.name} v${package_default.version}
+var defaultEnvPath = resolve(process.cwd(), ".env.local");
+if (existsSync5(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 Command12();
+consola.log(colorize8("cyanBright", `\u25E2 ${package_default.name} v${package_default.version}
 `));
-program.name(package_default.name).version(package_default.version).description("CLI tool for Catalyst development").addOption(
-  new Option8(
+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 Option9(
     "--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.
@@ -1467,12 +3293,12 @@ program.name(package_default.name).version(package_default.version).description(
         const message = errCode === "ENOENT" ? `Env file not found: ${envFilePath}` : `Failed to load --env-path ${value}: ${result.error.message}`;
         throw new Error(message);
       }
-      consola.log(colorize5("cyanBright", `Loaded environment variables from ${envFilePath}
+      consola.log(colorize8("cyanBright", `Loaded environment variables from ${envFilePath}
 `));
     }
     return value;
   })
-).addCommand(version).addCommand(start).addCommand(build).addCommand(deploy).addCommand(logs).addCommand(project).addCommand(auth).addCommand(telemetry2).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
+).addCommand(version).addCommand(create).addCommand(start).addCommand(build).addCommand(deploy).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(telemetry2).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
 
 // src/cli/index.ts
 var handleFatalError = async (error) => {
@@ -1489,6 +3315,10 @@ var handleFatalError = async (error) => {
     await telemetry3.analytics.closeAndFlush();
   } catch {
   }
+  if (error instanceof UnauthorizedError) {
+    consola.error(errorMessage);
+    process.exit(1);
+  }
   consola.error(errorMessage);
   if (telemetry3.isEnabled()) {
     consola.info(