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

package/dist/cli.js

@@ -13,7 +13,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.4",
   type: "module",
   bin: {
     catalyst: "dist/cli.js"
@@ -35,22 +35,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 +75,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 +92,8 @@ function getProjectConfig() {
         }
       }
     }
-  });
+  }));
+  return userConfigInstance;
 }
 
 // src/cli/lib/telemetry.ts
@@ -104,14 +106,14 @@ 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({
-      writeKey: "not-a-valid-segment-write-key"
+      writeKey: "OCkxLj3KTc1N3ebEbnFBqbhxfE3tVb3Z"
     });
   }
   durationMs() {
@@ -159,15 +161,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;
   }
 };
@@ -179,9 +181,10 @@ 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 { Command as Command10 } from "commander";
+import { colorize as colorize9 } from "consola/utils";
 import { config } from "dotenv";
+import { existsSync as existsSync5 } from "fs";
 import { resolve } from "path";
 
 // src/cli/commands/auth.ts
@@ -193,7 +196,7 @@ import { z as z3 } 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",
@@ -257,6 +260,12 @@ async function waitForDeviceToken(loginUrl, deviceCode, interval) {
 
 // src/cli/lib/project.ts
 import { z as z2 } from "zod";
+var InfrastructureProjectValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InfrastructureProjectValidationError";
+  }
+};
 var fetchProjectsSchema = z2.object({
   data: z2.array(
     z2.object({
@@ -265,17 +274,31 @@ var fetchProjectsSchema = z2.object({
     })
   )
 });
-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)
+  });
+  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)
+  });
   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."
@@ -296,32 +319,43 @@ var createProjectSchema = z2.object({
     date_modified: z2.coerce.date()
   })
 });
+var validationErrorBodySchema = z2.object({
+  title: z2.string().optional(),
+  detail: z2.string().optional(),
+  errors: z2.record(z2.string(), z2.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 })
+  });
+  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,6 +364,44 @@ 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)
+  });
+  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" }
+    }
+  });
+}
 
 // src/cli/commands/auth.ts
 var StoreProfileSchema = z3.object({
@@ -355,7 +427,14 @@ async function fetchStoreProfile(storeHash, accessToken, apiHost) {
   }
   return result.data.data;
 }
-var whoami = new Command("whoami").description("Verify stored credentials and display store/project info.").addOption(
+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 Option(
     "--store-hash <hash>",
     "BigCommerce store hash. Can be found in the URL of your store Control Panel."
@@ -366,7 +445,7 @@ var whoami = new Command("whoami").description("Verify stored credentials and di
     "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 Option("--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();
@@ -408,7 +487,18 @@ 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(
+var login = new Command("login").configureHelp({ showGlobalOptions: true }).description(
+  "Authenticate via browser using the OAuth device code flow. If already logged in, displays current credentials and suggests running `catalyst auth logout` to re-authenticate."
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Login via browser (recommended)
+  $ catalyst auth login
+
+  # Login with existing credentials (skips browser flow)
+  $ catalyst auth login --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>`
+).addOption(
   new Option(
     "--store-hash <hash>",
     "BigCommerce store hash. Can be found in the URL of your store Control Panel."
@@ -419,7 +509,7 @@ var login = new Command("login").description("Authenticate via browser using the
     "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)
+  new Option("--login-url <url>", "BigCommerce login URL.").env("BIGCOMMERCE_LOGIN_URL").default(DEFAULT_LOGIN_URL).hideHelp()
 ).action(async (options) => {
   try {
     const config2 = getProjectConfig();
@@ -460,7 +550,12 @@ var login = new Command("login").description("Authenticate via browser using the
     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 +575,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(login).addCommand(logout);
 
 // src/cli/commands/build.ts
 import { Command as Command2, Option as Option2 } from "commander";
 import { execa } from "execa";
 import { copyFile, cp, writeFile } from "fs/promises";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 
 // src/cli/lib/get-module-cli-path.ts
 import { dirname, join as join2 } from "path";
@@ -497,6 +592,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 z4 } from "zod";
+var projectJsonSchema = z4.looseObject({
+  projectUuid: z4.string().optional()
+});
+var packageJsonSchema = z4.looseObject({
+  dependencies: z4.record(z4.string(), z4.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 +691,19 @@ 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);
   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 +716,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 +730,7 @@ async function buildCatalystProject(projectUuid) {
       `wrangler@${WRANGLER_VERSION}`,
       "deploy",
       "--config",
-      join3(coreDir, ".bigcommerce", "wrangler.jsonc"),
+      join4(coreDir, ".bigcommerce", "wrangler.jsonc"),
       "--keep-vars",
       "--outdir",
       bigcommerceDistDir,
@@ -606,36 +741,1073 @@ async function buildCatalystProject(projectUuid) {
       cwd: coreDir
     }
   );
-  consola.success("Project built");
-  await cp(join3(openNextOutDir, "assets"), join3(bigcommerceDistDir, "assets"), {
-    recursive: true,
-    force: true
+  consola.success("Project built");
+  await cp(join4(openNextOutDir, "assets"), join4(bigcommerceDistDir, "assets"), {
+    recursive: true,
+    force: true
+  });
+}
+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 Option2(
+    "--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) {
+    throw new Error(
+      "Project UUID is required. Please run `catalyst project create` or `catalyst project link` or this command again with --project-uuid <uuid>."
+    );
+  }
+  await buildCatalystProject(projectUuid);
+});
+
+// src/cli/commands/create.ts
+import { Command as Command3, InvalidArgumentError, Option as Option4 } 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 colorize4 } 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 existsSync2 } from "fs";
+import { join as join5 } from "path";
+import yoctoSpinner2 from "yocto-spinner";
+var WORKSPACE_PACKAGES = ["packages/catalyst", "packages/client"];
+var buildWorkspacePackages = (projectDir) => {
+  const hasCore = existsSync2(join5(projectDir, "core"));
+  const hasAllWorkspacePackages = WORKSPACE_PACKAGES.every(
+    (pkg) => existsSync2(join5(projectDir, pkg))
+  );
+  if (!hasCore || !hasAllWorkspacePackages) return;
+  WORKSPACE_PACKAGES.forEach((pkg) => {
+    const spinner = yoctoSpinner2().start(`Building ${pkg}...`);
+    try {
+      execSync("pnpm build", { cwd: join5(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/channels.ts
+import { z as z5 } 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}` : ""}`;
+};
+var authHeaders2 = (accessToken) => ({
+  "X-Auth-Token": accessToken,
+  "X-Correlation-Id": getTelemetry().correlationId,
+  Accept: "application/json"
+});
+var envVarsSchema = z5.record(z5.string(), z5.coerce.string());
+var channelSchema = z5.object({
+  id: z5.number(),
+  name: z5.string(),
+  platform: z5.string()
+});
+var channelsResponseSchema = z5.object({
+  data: z5.array(channelSchema)
+});
+var initResponseSchema = z5.object({
+  data: z5.object({
+    storefront_api_token: z5.string(),
+    envVars: envVarsSchema
+  })
+});
+var createChannelResponseSchema = z5.object({
+  data: z5.object({
+    id: z5.number(),
+    storefront_api_token: z5.string(),
+    envVars: envVarsSchema
+  })
+});
+var eligibilityResponseSchema = z5.object({
+  data: z5.object({
+    eligible: z5.boolean(),
+    message: z5.string()
+  })
+});
+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"
+      }
+    }
+  );
+  if (!response.ok) {
+    throw new Error(`GET /v3/channels failed: ${response.status} ${response.statusText}`);
+  }
+  return channelsResponseSchema.parse(await response.json()).data;
+}
+
+// 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/commerce-hosting.ts
+import { input, select, Separator } from "@inquirer/prompts";
+import { colorize as colorize2 } from "consola/utils";
+import {
+  existsSync as existsSync3,
+  lstatSync,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { dirname as dirname2, join as join6 } from "path";
+import { z as z6 } 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 = z6.looseObject({
+  dependencies: z6.record(z6.string(), z6.string()).optional()
+});
+var writeJson = (path, value) => {
+  mkdirSync(dirname2(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`);
+};
+var symlinkRootEnvToCore = (projectDir) => {
+  const coreEnvPath = join6(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 = join6(projectDir, "core", "proxy.ts");
+  const middlewarePath = join6(projectDir, "core", "middleware.ts");
+  if (!existsSync3(proxyPath)) return;
+  const contents = readFileSync2(proxyPath, "utf-8").replace("export const proxy", "export const middleware").replace("export const config = {", "export const config = {\n  runtime: 'experimental-edge',");
+  writeFileSync(middlewarePath, contents);
+  unlinkSync(proxyPath);
+};
+var setupCommerceHosting = ({
+  projectDir,
+  projectUuid,
+  storeHash,
+  accessToken
+}) => {
+  const corePackageJsonPath = join6(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(join6(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 };
+}
+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 };
+  } 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 };
+  } 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/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 z7 } 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 = z7.object({
+  data: z7.array(
+    z7.object({
+      id: z7.string(),
+      name: z7.string(),
+      fallback: z7.string().nullable(),
+      is_supported: z7.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"
+      }
+    }
+  );
+  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/login.ts
+import { colorize as colorize3 } from "consola/utils";
+import open2 from "open";
+import yoctoSpinner4 from "yocto-spinner";
+async function login2(loginUrl) {
+  const deviceCode = await requestDeviceCode(loginUrl);
+  consola.info(
+    `${colorize3("yellow", "Your one-time code:")} ${colorize3("bold", deviceCode.user_code)}`
+  );
+  try {
+    await open2(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 = yoctoSpinner4().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
+  };
+}
+
+// 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 z8 } from "zod";
+var corePackageJsonSchema2 = z8.looseObject({
+  scripts: z8.record(z8.string(), z8.string()).optional(),
+  dependencies: z8.record(z8.string(), z8.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/shared-options.ts
+import { Option as Option3 } from "commander";
+var storeHashOption = () => new Option3(
+  "--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 Option3(
+  "--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 Option3("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com").hideHelp();
+var projectUuidOption = () => new Option3(
+  "--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/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: () => colorize4("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;
 }
-var build = new Command2("build").addOption(
-  new Option2(
-    "--project-uuid <uuid>",
-    "Project UUID to be included in the deployment configuration."
-  ).env("CATALYST_PROJECT_UUID")
+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 Command3("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 Option4(
+    "--hosting <mode>",
+    'Hosting mode: "self-hosted" (default) or "commerce" to set up Commerce Hosting at create time. When omitted, scaffolding is hosting-agnostic; run `catalyst deploy` later to opt in.'
+  ).choices(["self-hosted", "commerce"])
+).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 Option4("--bigcommerce-hostname <hostname>", "BigCommerce hostname").default("bigcommerce.com").hideHelp()
+).addOption(
+  new Option4("--login-url <url>", "BigCommerce login URL.").env("BIGCOMMERCE_LOGIN_URL").default(DEFAULT_LOGIN_URL).hideHelp()
+).addOption(
+  new Option4("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
 ).action(async (options) => {
-  const config2 = getProjectConfig();
-  const projectUuid = options.projectUuid ?? config2.get("projectUuid");
-  if (!projectUuid) {
-    throw new Error(
-      "Project UUID is required. Please run `catalyst project create` or `catalyst project link` or this command again with --project-uuid <uuid>."
+  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 credentials = await login2(options.loginUrl);
+    storeHash = credentials.storeHash;
+    accessToken = credentials.accessToken;
+  }
+  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) {
+      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(colorize4("yellow", `  cd ${projectName}/core && pnpm run dev`));
+  if (useCommerceHosting) {
+    consola.info(
+      colorize4(
+        "yellow",
+        `  Run 'cd ${projectName}/core && pnpm run deploy' when ready to deploy to Commerce Hosting.`
+      )
     );
   }
-  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 { Command as Command4, Option as Option5 } from "commander";
+import { colorize as colorize5 } 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";
+import { dirname as dirname4, join as join10 } from "path";
+import yoctoSpinner5 from "yocto-spinner";
+import { z as z9 } from "zod";
 
 // src/cli/lib/deployment-errors.ts
 var ERROR_MESSAGES = {
@@ -669,7 +1841,7 @@ function resolveCredentials(options, config2) {
 }
 
 // src/cli/commands/deploy.ts
-var stepsEnum = z4.enum([
+var stepsEnum = z9.enum([
   "initializing",
   "downloading",
   "unzipping",
@@ -687,41 +1859,41 @@ var STEPS = {
   finalizing: "Finalizing...",
   complete: "Complete"
 };
-var UploadSignatureSchema = z4.object({
-  data: z4.object({
-    upload_url: z4.url(),
-    upload_uuid: z4.string()
+var UploadSignatureSchema = z9.object({
+  data: z9.object({
+    upload_url: z9.url(),
+    upload_uuid: z9.string()
   })
 });
-var CreateDeploymentSchema = z4.object({
-  data: z4.object({
-    deployment_uuid: z4.uuid()
+var CreateDeploymentSchema = z9.object({
+  data: z9.object({
+    deployment_uuid: z9.uuid()
   })
 });
-var ProjectSchema = z4.object({
-  data: z4.array(
-    z4.object({
-      uuid: z4.uuid(),
-      name: z4.string()
+var ProjectSchema = z9.object({
+  data: z9.array(
+    z9.object({
+      uuid: z9.uuid(),
+      name: z9.string()
     })
   )
 });
-var DeploymentStatusSchema = z4.object({
-  deployment_uuid: z4.uuid(),
-  deployment_status: z4.enum(["queued", "in_progress", "failed", "completed"]),
-  event: z4.object({
+var DeploymentStatusSchema = z9.object({
+  deployment_uuid: z9.uuid(),
+  deployment_status: z9.enum(["queued", "in_progress", "failed", "completed"]),
+  event: z9.object({
     step: stepsEnum,
-    progress: z4.number()
+    progress: z9.number()
   }).nullable(),
-  deployment_url: z4.string().nullable(),
-  error: z4.object({
-    code: z4.number()
+  deployment_url: z9.string().nullable(),
+  error: z9.object({
+    code: z9.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 +1903,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);
@@ -762,7 +1934,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",
@@ -843,7 +2015,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 = yoctoSpinner5().start("Fetching...");
   const response = await fetch(
     `https://${apiHost}/stores/${storeHash}/v3/infrastructure/deployments/${deploymentUuid}/events`,
     {
@@ -898,28 +2070,36 @@ var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost
   spinner.success("Deployment completed successfully.");
   if (deploymentUrl) {
     const url = deploymentUrl.startsWith("https://") ? deploymentUrl : `https://${deploymentUrl}`;
-    consola.success(`View your deployment at: ${colorize2("blue", url)}`);
+    consola.success(`View your deployment at: ${colorize5("blue", url)}`);
   }
 };
-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")
-).addOption(
-  new Option3(
+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
+      }
+    }
+  );
+  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 Command4("deploy").configureHelp({ showGlobalOptions: true }).description("Deploy your application to Cloudflare.").addHelpText(
+  "after",
+  `
+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()).addOption(
+  new Option5(
     "--secret <value>",
     "Secret to set for the deployment (repeatable). Format: --secret KEY=VALUE"
   ).argParser((value, previous = []) => {
@@ -932,15 +2112,67 @@ 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());
+    setupCommerceHosting({ projectDir, projectUuid, storeHash, accessToken });
+    consola.success("Commerce Hosting setup complete.");
+    await installDependencies(projectDir);
   }
-  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 {
@@ -982,37 +2214,9 @@ var deploy = new Command3("deploy").description("Deploy your application to Clou
 });
 
 // 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) => {
-  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/logs.ts
+import { Command as Command5, Option as Option6 } from "commander";
+import { colorize as colorize6 } from "consola/utils";
+import { z as z10 } from "zod";
 var telemetry = new Telemetry();
 var DEFAULT_CONNECTION_TTL_MS = 1 * 60 * 1e3;
 var MAX_RETRIES = 5;
@@ -1023,23 +2227,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 = z10.object({
+  uuid: z10.string(),
+  project_uuid: z10.string(),
+  request: z10.object({
+    method: z10.string(),
+    url: z10.string(),
+    status_code: z10.number()
   }),
-  logs: z5.array(
-    z5.object({
-      timestamp: z5.string(),
-      level: z5.string(),
-      messages: z5.array(z5.unknown())
+  logs: z10.array(
+    z10.object({
+      timestamp: z10.string(),
+      level: z10.string(),
+      messages: z10.array(z10.unknown())
     })
   ),
-  exceptions: z5.array(z5.unknown()),
-  timestamp: z5.string()
+  exceptions: z10.array(z10.unknown()),
+  timestamp: z10.string()
 }).loose();
 var StreamError = class extends Error {
   constructor(message, fatal) {
@@ -1053,7 +2257,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 = colorize6(LEVEL_COLORS[level] ?? "white", level);
     switch (format) {
       case "short":
         consola.log(msg);
@@ -1161,45 +2365,71 @@ 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 Command5("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 Option6("--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 Command5("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 Command5("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 Command6 } from "commander";
+import { colorize as colorize7 } from "consola/utils";
+import { dirname as dirname5 } from "path";
+async function offerCommerceHostingSetup(projectUuid, credentials) {
+  if (getProjectState().isTransformed) 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;
+  const projectDir = dirname5(process.cwd());
+  setupCommerceHosting({
+    projectDir,
+    projectUuid,
+    storeHash: credentials?.storeHash,
+    accessToken: credentials?.accessToken
+  });
+  consola.success("Commerce Hosting setup complete.");
+  await installDependencies(projectDir);
+}
+var list = new Command6("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,26 +2441,21 @@ 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 ? ` ${colorize7("green", "[linked]")}` : "";
+    consola.log(`${p.name} (${p.uuid})${marker}`);
   });
   process.exit(0);
 });
-var create = new Command5("create").description(
+var create2 = new Command6("create").configureHelp({ showGlobalOptions: true }).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) => {
+).addHelpText(
+  "after",
+  `
+Example:
+  $ catalyst project create`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).action(async (options) => {
   const config2 = getProjectConfig();
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
@@ -1246,24 +2471,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 Command6("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 +2495,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 Command6("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;
     }
-  );
-  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.`);
+    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} ${colorize7("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;
+    }
+  }
+  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.");
   }
-  writeProjectConfig(projectUuid, { storeHash, accessToken });
   process.exit(0);
 });
-var project = new Command5("project").description("Manage your BigCommerce infrastructure project.").addCommand(create).addCommand(list).addCommand(link);
+var project = new Command6("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure project.").addCommand(create2).addCommand(list).addCommand(link).addCommand(del);
 
 // src/cli/commands/start.ts
-import { Command as Command6 } from "commander";
+import { Command as Command7 } 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 Command7("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 +2647,7 @@ var start = new Command6("start").description(
       "opennextjs-cloudflare",
       "preview",
       "--config",
-      join5(".bigcommerce", "wrangler.jsonc")
+      join11(".bigcommerce", "wrangler.jsonc")
     ],
     {
       stdio: "inherit",
@@ -1359,11 +2657,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 Command8, Option as Option7 } from "commander";
+import { colorize as colorize8 } 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 Command8("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 Option7("--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 +2683,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 +2692,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: ${colorize8("bold", isEnabled ? colorize8("green", "Enabled") : colorize8("red", "Disabled"))}`
   );
   if (!isEnabled) {
     consola.info(
@@ -1390,8 +2702,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 Command9 } from "commander";
+var version = new Command9("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,10 +2764,19 @@ 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 Command10();
+consola.log(colorize9("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(
+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 Option8(
     "--env-path <path>",
     "Path to environment file to load (relative to current working directory)"
@@ -1467,12 +2793,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(colorize9("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(auth).addCommand(telemetry2).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
 
 // src/cli/index.ts
 var handleFatalError = async (error) => {