@bigcommerce/catalyst 1.0.0-alpha.5 → 1.0.0

package/dist/cli.js

@@ -28,8 +28,13 @@ import { randomBytes, randomUUID } from "crypto";
 // package.json
 var package_default = {
   name: "@bigcommerce/catalyst",
-  version: "1.0.0-alpha.5",
+  version: "1.0.0",
   type: "module",
+  repository: {
+    type: "git",
+    url: "https://github.com/bigcommerce/catalyst",
+    directory: "packages/catalyst"
+  },
   bin: {
     catalyst: "dist/cli.js"
   },
@@ -65,6 +70,7 @@ var package_default = {
     nypm: "^0.5.4",
     open: "^10.1.0",
     "std-env": "^3.9.0",
+    tar: "^7.5.7",
     "yocto-spinner": "^1.0.0",
     zod: "^4.0.5"
   },
@@ -128,7 +134,7 @@ var Telemetry = class {
     this.correlationId = randomUUID();
     this.startTime = Date.now();
     this.analytics = new Analytics({
-      writeKey: "not-a-valid-segment-write-key"
+      writeKey: "OCkxLj3KTc1N3ebEbnFBqbhxfE3tVb3Z"
     });
   }
   durationMs() {
@@ -195,11 +201,11 @@ function getTelemetry() {
 }
 
 // src/cli/program.ts
-import { Option as Option9 } from "@commander-js/extra-typings";
-import { Command as Command12 } from "commander";
-import { colorize as colorize8 } from "consola/utils";
+import { Option as Option11 } from "@commander-js/extra-typings";
+import { Command as Command14 } from "commander";
+import { colorize as colorize11 } from "consola/utils";
 import { config } from "dotenv";
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { resolve } from "path";
 
 // src/cli/commands/auth.ts
@@ -207,7 +213,7 @@ import { Command, Option as Option2 } from "commander";
 import { z as z4 } from "zod";
 
 // src/cli/lib/login.ts
-import { password } from "@inquirer/prompts";
+import { confirm, input, password } from "@inquirer/prompts";
 import { colorize } from "consola/utils";
 import open from "open";
 import yoctoSpinner from "yocto-spinner";
@@ -337,8 +343,8 @@ async function manualLogin(apiHost) {
   Settings \u2192 API \u2192 Store-level API accounts \u2192 Create API account
 Grant these OAuth scopes: ${DEVICE_OAUTH_SCOPES}`
   );
-  const storeHashInput = await consola.prompt("Store hash:", { type: "text" });
-  const storeHash = String(storeHashInput).trim();
+  const storeHashInput = await input({ message: "Store hash:" });
+  const storeHash = storeHashInput.trim();
   if (!storeHash) {
     throw new Error("Store hash is required.");
   }
@@ -366,10 +372,10 @@ async function login(loginUrl, apiHost) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     consola.warn(`Browser login didn't work (${message}).`);
-    const shouldFallback = await consola.prompt(
-      "Try logging in manually with a store hash and access token instead?",
-      { type: "confirm", initial: true }
-    );
+    const shouldFallback = await confirm({
+      message: "Try logging in manually with a store hash and access token instead?",
+      default: true
+    });
     if (!shouldFallback) {
       throw new LoginAbortedError();
     }
@@ -423,7 +429,7 @@ async function fetchProjects(storeHash, accessToken, apiHost) {
   assertAuthorized(response);
   if (response.status === 403) {
     throw new Error(
-      "Infrastructure Projects API not enabled. If you are part of the alpha, contact support@bigcommerce.com to enable it."
+      "Infrastructure Projects API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
   if (!response.ok) {
@@ -474,7 +480,7 @@ async function createProject(name, storeHash, accessToken, apiHost) {
   }
   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."
+      "Infrastructure Projects API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
   if (response.status === 502) {
@@ -495,7 +501,7 @@ async function deleteProject(projectUuid, storeHash, accessToken, apiHost) {
   assertAuthorized(response);
   if (response.status === 403) {
     throw new Error(
-      "Infrastructure Projects API not enabled. If you are part of the alpha, contact support@bigcommerce.com to enable it."
+      "Infrastructure Projects API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
   if (response.status === 404) {
@@ -783,12 +789,17 @@ function getProjectState(cwd = process.cwd()) {
 }
 
 // src/cli/lib/wrangler-config.ts
+function getCompatibilityDate(now = /* @__PURE__ */ new Date()) {
+  const date = new Date(now);
+  date.setUTCMonth(date.getUTCMonth() - 1);
+  return date.toISOString().slice(0, 10);
+}
 function getWranglerConfig(projectUuid) {
   return {
     $schema: "node_modules/wrangler/config-schema.json",
     main: "../.open-next/worker.js",
     name: `project-${projectUuid}`,
-    compatibility_date: "2025-09-15",
+    compatibility_date: getCompatibilityDate(),
     compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"],
     observability: {
       enabled: true,
@@ -935,7 +946,14 @@ Examples:
 });
 
 // src/cli/commands/channel.ts
-import { Command as Command3, Option as Option4 } from "commander";
+import { select as select3 } from "@inquirer/prompts";
+import { Command as Command3, InvalidArgumentError, Option as Option4 } from "commander";
+import { colorize as colorize3 } from "consola/utils";
+import { outputFileSync } from "fs-extra/esm";
+import { join as join6 } from "path";
+
+// src/cli/lib/channel-site-flow.ts
+import { select as select2 } from "@inquirer/prompts";
 
 // src/cli/lib/channels.ts
 import { z as z6 } from "zod";
@@ -958,6 +976,20 @@ var channelSchema = z6.object({
 var channelsResponseSchema = z6.object({
   data: z6.array(channelSchema)
 });
+var CHANNEL_PLATFORM_ORDER = ["catalyst", "next", "bigcommerce"];
+function sortChannelsByPlatform(channels) {
+  return [...channels].sort((a, b) => {
+    const aIndex = CHANNEL_PLATFORM_ORDER.indexOf(a.platform);
+    const bIndex = CHANNEL_PLATFORM_ORDER.indexOf(b.platform);
+    if (aIndex === -1 && bIndex === -1) return 0;
+    if (aIndex === -1) return 1;
+    if (bIndex === -1) return -1;
+    return aIndex - bIndex;
+  });
+}
+function channelPlatformLabel(platform) {
+  return platform === "bigcommerce" ? "Stencil" : platform.charAt(0).toUpperCase() + platform.slice(1);
+}
 var initResponseSchema = z6.object({
   data: z6.object({
     storefront_api_token: z6.string(),
@@ -1078,17 +1110,9 @@ async function updateChannelSiteUrl(channelId, siteUrl, storeHash, accessToken,
 }
 
 // src/cli/lib/commerce-hosting.ts
-import { input, select, Separator } from "@inquirer/prompts";
+import { confirm as confirm2, input as input2, select, Separator } from "@inquirer/prompts";
 import { colorize as colorize2 } from "consola/utils";
-import {
-  existsSync as existsSync2,
-  lstatSync,
-  mkdirSync,
-  readFileSync as readFileSync2,
-  symlinkSync,
-  unlinkSync,
-  writeFileSync
-} from "fs";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, unlinkSync, writeFileSync } from "fs";
 import { dirname as dirname2, join as join5 } from "path";
 import { z as z7 } from "zod";
 
@@ -1128,58 +1152,43 @@ var writeJson = (path, value) => {
   writeFileSync(path, `${JSON.stringify(value, null, 2)}
 `);
 };
-var symlinkRootEnvToCore = (projectDir) => {
-  const coreEnvPath = join5(projectDir, "core", ".env.local");
-  if (lstatSync(coreEnvPath, { throwIfNoEntry: false })) return;
-  try {
-    symlinkSync("../.env.local", coreEnvPath);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "unknown error";
-    consola.warn(
-      `Could not create symlink at core/.env.local: ${message}
-On Windows, enable Developer Mode or run as administrator to allow symlinks.
-You will need to keep .env.local and core/.env.local in sync manually.`
-    );
-  }
-};
 var convertProxyToMiddleware = (projectDir) => {
-  const proxyPath = join5(projectDir, "core", "proxy.ts");
-  const middlewarePath = join5(projectDir, "core", "middleware.ts");
+  const proxyPath = join5(projectDir, "proxy.ts");
+  const middlewarePath = join5(projectDir, "middleware.ts");
   if (!existsSync2(proxyPath)) return;
   const contents = readFileSync2(proxyPath, "utf-8").replace("export const proxy", "export const middleware").replace("export const config = {", "export const config = {\n  runtime: 'experimental-edge',");
   writeFileSync(middlewarePath, contents);
   unlinkSync(proxyPath);
 };
 var cleanupCloudflareIncompatibilities = async (projectDir) => {
-  const instrumentationPath = join5(projectDir, "core", "instrumentation.ts");
+  const instrumentationPath = join5(projectDir, "instrumentation.ts");
   if (!existsSync2(instrumentationPath)) return;
   if (!process.stdin.isTTY) {
     consola.warn(
-      "core/instrumentation.ts is present and may be incompatible with the Cloudflare Workers bundle (the default @vercel/otel scaffolding throws at cold start under workerd). Skipping automatic cleanup in non-interactive mode \u2014 re-run interactively to remove it, or delete/gate it manually."
+      "instrumentation.ts is present and may be incompatible with the Cloudflare Workers bundle (the default @vercel/otel scaffolding throws at cold start under workerd). Skipping automatic cleanup in non-interactive mode \u2014 re-run interactively to remove it, or delete/gate it manually."
     );
     return;
   }
-  const shouldRemove = await consola.prompt(
-    'Catalyst found core/instrumentation.ts, which is incompatible with the Cloudflare Workers bundle when it uses @vercel/otel (causes "Failed to prepare server" at cold start). Remove it and drop @vercel/otel from core/package.json?',
-    { type: "confirm", initial: true }
-  );
-  consola.log("");
+  const shouldRemove = await confirm2({
+    message: 'Catalyst found instrumentation.ts, which is incompatible with the Cloudflare Workers bundle when it uses @vercel/otel (causes "Failed to prepare server" at cold start). Remove it and drop @vercel/otel from package.json?',
+    default: true
+  });
   if (!shouldRemove) {
     consola.info(
-      'Leaving core/instrumentation.ts in place. The Cloudflare worker will continue to log "Failed to prepare server" at cold start until this is resolved manually.'
+      'Leaving instrumentation.ts in place. The Cloudflare worker will continue to log "Failed to prepare server" at cold start until this is resolved manually.'
     );
     return;
   }
   unlinkSync(instrumentationPath);
-  consola.info("Removed core/instrumentation.ts (incompatible with Cloudflare Workers).");
-  const corePackageJsonPath = join5(projectDir, "core", "package.json");
+  consola.info("Removed instrumentation.ts (incompatible with Cloudflare Workers).");
+  const corePackageJsonPath = join5(projectDir, "package.json");
   if (existsSync2(corePackageJsonPath)) {
     const pkg = corePackageJsonSchema.parse(JSON.parse(readFileSync2(corePackageJsonPath, "utf-8")));
     if (pkg.dependencies && "@vercel/otel" in pkg.dependencies) {
       const { "@vercel/otel": _removedVercelOtel, ...preservedDeps } = pkg.dependencies;
       pkg.dependencies = preservedDeps;
       writeJson(corePackageJsonPath, sortPackageJsonFields(pkg));
-      consola.info("Dropped @vercel/otel from core/package.json.");
+      consola.info("Dropped @vercel/otel from package.json.");
     }
   }
 };
@@ -1190,7 +1199,7 @@ var setupCommerceHosting = async ({
   accessToken
 }) => {
   await cleanupCloudflareIncompatibilities(projectDir);
-  const corePackageJsonPath = join5(projectDir, "core", "package.json");
+  const corePackageJsonPath = join5(projectDir, "package.json");
   const pkg = corePackageJsonSchema.parse(JSON.parse(readFileSync2(corePackageJsonPath, "utf-8")));
   pkg.dependencies = {
     ...pkg.dependencies,
@@ -1203,8 +1212,7 @@ var setupCommerceHosting = async ({
   };
   if (storeHash) projectJson.storeHash = storeHash;
   if (accessToken) projectJson.accessToken = accessToken;
-  writeJson(join5(projectDir, "core", ".bigcommerce", "project.json"), projectJson);
-  symlinkRootEnvToCore(projectDir);
+  writeJson(join5(projectDir, ".bigcommerce", "project.json"), projectJson);
   convertProxyToMiddleware(projectDir);
 };
 var NoLinkedProjectError = class extends Error {
@@ -1214,15 +1222,8 @@ var NoLinkedProjectError = class extends Error {
   }
 };
 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
-  );
+  const newProjectName = await input2({ message: "Enter a name for the new project:" });
+  const data = await createProject(newProjectName, api.storeHash, api.accessToken, api.apiHost);
   consola.success(`Project "${data.name}" created successfully.`);
   return { uuid: data.uuid, name: data.name, deployment_hostnames: [] };
 }
@@ -1231,31 +1232,31 @@ async function selectOrCreateInfrastructureProject(api, linkedProjectUuid) {
   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 }
-    );
+    const shouldCreate = await confirm2({
+      message: "There are not any hosting projects that you can link to yet. Would you like to create one?",
+      default: true
+    });
     if (!shouldCreate) {
       throw new NoLinkedProjectError();
     }
     return promptForNewProjectName(api);
   }
-  const promptOptions = [
+  const choices = [
     ...existingProjects.map((p) => ({
-      label: p.uuid === linkedProjectUuid ? `${p.name} ${colorize2("green", "[linked]")}` : p.name,
+      name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize2("green", "[linked]")}` : p.name,
       value: p.uuid,
-      hint: p.uuid
+      description: p.uuid
     })),
     {
-      label: "Create a new project",
+      name: "Create a new project",
       value: "create",
-      hint: "Create a new hosting project for this Catalyst storefront."
+      description: "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" }
-  );
+  const selected = await select({
+    message: "Select a project or create a new project (Press <enter> to select).",
+    choices
+  });
   if (selected === "create") {
     return promptForNewProjectName(api);
   }
@@ -1325,7 +1326,7 @@ async function promptForCommerceHostingProject(api, defaultName, autoUseDefaultN
   return selected;
 }
 async function promptAndCreateCommerceHostingProject(api, takenNames, defaultName) {
-  const projectName = await input({
+  const projectName = await input2({
     message: "What would you like to name your Commerce Hosting project?",
     default: defaultName,
     validate: (value) => {
@@ -1439,16 +1440,14 @@ async function resolveChannel(options) {
       "No Catalyst channels found on this store. Create one with `catalyst create` and try again."
     );
   }
-  const selectedId = await consola.prompt("Select the channel to update.", {
-    type: "select",
-    options: catalystChannels.map((c) => ({
-      label: c.name,
-      value: String(c.id),
-      hint: `id: ${c.id}`
-    })),
-    cancel: "reject"
+  const id = await select2({
+    message: "Select the channel to update.",
+    choices: catalystChannels.map((c) => ({
+      name: c.name,
+      value: c.id,
+      description: `id: ${c.id}`
+    }))
   });
-  const id = Number(selectedId);
   const matched = catalystChannels.find((c) => c.id === id);
   return { id, name: matched?.name };
 }
@@ -1465,12 +1464,11 @@ async function resolveHostname(project2, options) {
     ...project2.deployment_hostnames.filter((h) => h === options.preferHostname),
     ...project2.deployment_hostnames.filter((h) => h !== options.preferHostname)
   ] : project2.deployment_hostnames;
-  const selected = await consola.prompt("Select the hostname to point the channel at.", {
-    type: "select",
-    options: ordered.map((h) => ({ label: h, value: h })),
-    cancel: "reject"
+  const selected = await select2({
+    message: "Select the hostname to point the channel at.",
+    choices: ordered.map((h) => ({ name: h, value: h }))
   });
-  return String(selected);
+  return selected;
 }
 async function runChannelSiteUrlFlow(options) {
   const project2 = await resolveProject(options);
@@ -1488,6 +1486,38 @@ async function runChannelSiteUrlFlow(options) {
   consola.success(`Updated channel ${channelLabel} site URL to ${siteUrl}.`);
 }
 
+// src/cli/lib/env-config.ts
+var ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var parseEnvAssignment = (input5) => {
+  const separatorIndex = input5.indexOf("=");
+  if (separatorIndex === -1) {
+    throw new Error(`Invalid env var format: ${input5}. Expected format: KEY=VALUE`);
+  }
+  const key = input5.slice(0, separatorIndex).trim();
+  const value = input5.slice(separatorIndex + 1).trim();
+  if (!key || !value) {
+    throw new Error(`Invalid env var format: ${input5}. Expected format: KEY=VALUE`);
+  }
+  if (!ENV_KEY_PATTERN.test(key)) {
+    throw new Error(
+      `Invalid env var name: ${key}. Names must start with a letter or underscore and contain only letters, numbers, and underscores.`
+    );
+  }
+  return { key, value };
+};
+var getStoredEnv = (config2) => {
+  return config2.get("env") ?? {};
+};
+var toDeploymentSecrets = (envVars) => {
+  return Object.entries(envVars).map(([key, value]) => ({ type: "secret", key, value }));
+};
+var mergeDeploymentSecrets = (persisted, flagSecrets) => {
+  const byKey = /* @__PURE__ */ new Map();
+  persisted.forEach((secret) => byKey.set(secret.key, secret));
+  flagSecrets.forEach((secret) => byKey.set(secret.key, secret));
+  return Array.from(byKey.values());
+};
+
 // src/cli/lib/resolve-credentials.ts
 function resolveCredentials(options, config2) {
   const storeHash = options.storeHash ?? config2.get("storeHash");
@@ -1504,6 +1534,31 @@ function resolveCredentials(options, config2) {
 }
 
 // src/cli/commands/channel.ts
+var parseChannelId = (value) => {
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    throw new InvalidArgumentError(`"${value}" is not a valid channel ID (expected a number).`);
+  }
+  return parsed;
+};
+async function resolveCredentialsWithLogin(options, config2) {
+  const storeHash = options.storeHash ?? config2.get("storeHash");
+  const accessToken = options.accessToken ?? config2.get("accessToken");
+  if (storeHash && accessToken) {
+    return { storeHash, accessToken };
+  }
+  try {
+    const credentials = await login(options.loginUrl, options.apiHost);
+    config2.set("storeHash", credentials.storeHash);
+    config2.set("accessToken", credentials.accessToken);
+    return credentials;
+  } catch (error) {
+    if (error instanceof LoginAbortedError) {
+      return null;
+    }
+    throw error;
+  }
+}
 var update = new Command3("update").configureHelp({ showGlobalOptions: true }).description(
   "Update a BigCommerce channel's site URL to point at one of your project's deployment hostnames."
 ).addHelpText(
@@ -1550,150 +1605,186 @@ Examples:
   }
   process.exit(0);
 });
-var channel = new Command3("channel").configureHelp({ showGlobalOptions: true }).description("Manage BigCommerce channels.").addCommand(update);
+var link = new Command3("link").configureHelp({ showGlobalOptions: true }).description(
+  "Link this Catalyst project to a BigCommerce channel and write its credentials to .env.local."
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Pick a channel interactively (logs you in if needed)
+  $ catalyst channel link
 
-// src/cli/commands/create.ts
-import { Command as Command4, InvalidArgumentError, Option as Option5 } from "@commander-js/extra-typings";
-import { input as input2, select as select2 } from "@inquirer/prompts";
-import { execSync as execSync4 } from "child_process";
-import { colorize as colorize3 } from "consola/utils";
-import { pathExistsSync } from "fs-extra/esm";
-import kebabCase from "lodash.kebabcase";
-import { join as join9 } from "path";
+  # Non-interactive
+  $ catalyst channel link --store-hash <hash> --access-token <token> --channel-id 123
 
-// src/cli/lib/build-workspace-packages.ts
-import { execSync } from "child_process";
-import { existsSync as existsSync3 } from "fs";
-import { join as join6 } from "path";
-import yoctoSpinner2 from "yocto-spinner";
-var WORKSPACE_PACKAGES = ["packages/catalyst", "packages/client"];
-var buildWorkspacePackages = (projectDir) => {
-  const hasCore = existsSync3(join6(projectDir, "core"));
-  const hasAllWorkspacePackages = WORKSPACE_PACKAGES.every(
-    (pkg) => existsSync3(join6(projectDir, pkg))
-  );
-  if (!hasCore || !hasAllWorkspacePackages) return;
-  WORKSPACE_PACKAGES.forEach((pkg) => {
-    const spinner = yoctoSpinner2().start(`Building ${pkg}...`);
-    try {
-      execSync("pnpm build", { cwd: join6(projectDir, pkg), stdio: "ignore" });
-      spinner.success(`Built ${pkg}.`);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "unknown error";
-      spinner.error(`Failed to build ${pkg}: ${message}`);
-      throw error;
+  # Append extra environment variables to .env.local
+  $ catalyst channel link --channel-id 123 --env MY_FLAG=1`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).addOption(
+  new Option4("--channel-id <id>", "Link this channel directly, skipping the picker.").argParser(
+    parseChannelId
+  )
+).option(
+  "--env <vars...>",
+  "Arbitrary environment variables to set in .env.local. Format: KEY=VALUE (repeatable)."
+).addOption(
+  new Option4("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
+).action(async (options) => {
+  const config2 = getProjectConfig();
+  const credentials = await resolveCredentialsWithLogin(options, config2);
+  if (!credentials) {
+    consola.info(
+      "Login aborted. Re-run `catalyst channel link` when you have your credentials ready."
+    );
+    process.exit(0);
+    return;
+  }
+  const { storeHash, accessToken } = credentials;
+  await getTelemetry().identify(storeHash);
+  let channelId = options.channelId;
+  let channelName;
+  if (channelId === void 0) {
+    const channels = await fetchAvailableChannels(storeHash, accessToken, options.apiHost);
+    if (channels.length === 0) {
+      consola.info(
+        "No storefront channels found on this store. Create one with `catalyst create` and try again."
+      );
+      process.exit(0);
+      return;
     }
-  });
-};
-
-// src/cli/lib/clone-catalyst.ts
-import { execSync as execSync3 } from "child_process";
+    channelId = await select3({
+      message: "Which channel would you like to link?",
+      choices: sortChannelsByPlatform(channels).map((c) => ({
+        name: c.name,
+        value: c.id,
+        description: channelPlatformLabel(c.platform)
+      }))
+    });
+    channelName = channels.find((c) => c.id === channelId)?.name;
+  }
+  const initData = await getChannelInit(channelId, storeHash, accessToken, options.cliApiOrigin);
+  const envVars = { ...initData.envVars };
+  if (options.env) {
+    options.env.forEach((entry) => {
+      const { key, value } = parseEnvAssignment(entry);
+      envVars[key] = value;
+    });
+  }
+  outputFileSync(
+    join6(process.cwd(), ".env.local"),
+    `${Object.entries(envVars).map(([key, value]) => `${key}=${value}`).join("\n")}
+`
+  );
+  const label = channelName ? `"${channelName}" (${channelId})` : `${channelId}`;
+  consola.success(
+    `Linked to channel ${label} and wrote ${colorize3("cyanBright", ".env.local")}.`
+  );
+  consola.log(`Next steps:
 
-// src/cli/lib/checkout-ref.ts
-import { sync as spawnSync } from "cross-spawn";
+  ${colorize3("yellow", "pnpm run dev")}`);
+  process.exit(0);
+});
+var channel = new Command3("channel").configureHelp({ showGlobalOptions: true }).description("Manage BigCommerce channels.").addCommand(link).addCommand(update);
 
-// src/cli/lib/is-exec-exception.ts
-function isExecException(error) {
-  return typeof error === "object" && error !== null && "stdout" in error && "stderr" in error;
-}
+// src/cli/commands/create.ts
+import { Command as Command4, InvalidArgumentError as InvalidArgumentError2, Option as Option5 } from "@commander-js/extra-typings";
+import { checkbox, input as input3, select as select4 } from "@inquirer/prompts";
+import { execSync as execSync2 } from "child_process";
+import { colorize as colorize4 } from "consola/utils";
+import { pathExistsSync } from "fs-extra/esm";
+import kebabCase from "lodash.kebabcase";
+import { join as join11 } from "path";
 
-// 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/detect-package-manager.ts
+var detectPackageManager = () => {
+  const userAgent = process.env.npm_config_user_agent ?? "";
+  const name = userAgent.split(" ")[0]?.split("/")[0];
+  if (name === "pnpm" || name === "yarn" || name === "bun") {
+    return name;
   }
-}
+  if (process.versions.bun) {
+    return "bun";
+  }
+  return "npm";
+};
 
-// src/cli/lib/has-github-ssh.ts
-import { execSync as execSync2 } from "child_process";
-function hasGitHubSSH() {
+// src/cli/lib/extract-catalyst.ts
+import { mkdirSync as mkdirSync2 } from "fs";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+import { x } from "tar";
+var SUBDIR = "core";
+var MAX_ATTEMPTS = 3;
+var codeloadUrl = (repository, ref) => `https://codeload.github.com/${repository}/tar.gz/${encodeURIComponent(ref)}`;
+var wait = (ms) => new Promise((resolve2) => {
+  setTimeout(resolve2, ms);
+});
+var downloadAndExtract = async (repository, ref, projectDir) => {
+  const url = codeloadUrl(repository, ref);
+  const response = await fetch(url);
+  if (!response.ok || !response.body) {
+    throw new Error(`Failed to download ${url} (HTTP ${response.status})`);
+  }
+  await pipeline(
+    // Node's global fetch types `body` as the DOM ReadableStream; it is the same
+    // object Readable.fromWeb expects at runtime.
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    Readable.fromWeb(response.body),
+    x({
+      cwd: projectDir,
+      strip: 2,
+      filter: (path) => path.split("/")[1] === SUBDIR
+    })
+  );
+};
+var attemptDownload = async (repository, ref, projectDir, attempt = 1) => {
   try {
-    const output = execSync2("ssh -T git@github.com", {
-      encoding: "utf8",
-      stdio: "pipe"
-    }).toString();
-    return output.includes("successfully authenticated");
+    await downloadAndExtract(repository, ref, projectDir);
   } 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;
-      }
+    const message = error instanceof Error ? error.message : "unknown error";
+    if (attempt >= MAX_ATTEMPTS) {
+      throw new Error(`Failed to download Catalyst after ${MAX_ATTEMPTS} attempts: ${message}`);
     }
-    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);
+    consola.warn(`Download attempt ${attempt} failed (${message}). Retrying...`);
+    await wait(attempt * 1e3);
+    return attemptDownload(repository, ref, projectDir, attempt + 1);
   }
-}
-
-// src/cli/lib/clone-catalyst.ts
-var cloneCatalyst = ({
+};
+var extractCatalyst = async ({
   repository,
-  projectName,
-  projectDir,
-  ghRef,
-  resetMain = false
+  ref,
+  projectDir
 }) => {
-  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);
+  consola.info(`Downloading ${repository}#${ref}...`);
+  mkdirSync2(projectDir, { recursive: true });
+  await attemptDownload(repository, ref, projectDir);
+};
+
+// src/cli/lib/init-git-repo.ts
+import { execSync } from "child_process";
+import { rmSync } from "fs";
+import { join as join7 } from "path";
+var run = (command, cwd) => execSync(command, { cwd, stdio: "ignore" });
+var initGitRepo = (projectDir) => {
+  try {
+    run("git init", projectDir);
+    run("git add -A", projectDir);
+    run('git commit -m "Initial commit from Catalyst"', projectDir);
+    consola.success("Initialized a git repository.");
+  } catch {
+    rmSync(join7(projectDir, ".git"), { recursive: true, force: true });
+    consola.warn("Could not initialize a git repository. Skipping.");
   }
 };
 
 // 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...");
+import yoctoSpinner2 from "yocto-spinner";
+var installDependencies = async (projectDir, packageManager = "pnpm") => {
+  const spinner = yoctoSpinner2().start(
+    `Installing dependencies with ${packageManager}. This could take a minute...`
+  );
   try {
-    await installDeps({ cwd: projectDir, silent: true, packageManager: "pnpm" });
+    await installDeps({ cwd: projectDir, silent: true, packageManager });
     spinner.success("Dependencies installed successfully.");
   } catch (error) {
     const message = error instanceof Error ? error.message : "unknown error";
@@ -1756,22 +1847,94 @@ var getAvailableLocales = async (storeHash, accessToken, apiHost) => {
   return AvailableLocalesSuccessSchema.parse(await response.json()).data.filter(({ id }) => allowedLocales.includes(id)).map(({ name, id }) => ({ name: `${name} (${id})`, value: id }));
 };
 
-// src/cli/lib/setup-core-project.ts
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join7 } from "path";
+// src/cli/lib/rewrite-core-package.ts
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { join as join8 } from "path";
 import { z as z9 } from "zod";
+var NATIVE_BUILD_ALLOWLIST = [
+  "@parcel/watcher",
+  "@swc/core",
+  "@vercel/speed-insights",
+  "esbuild",
+  "msw",
+  "protobufjs",
+  "puppeteer",
+  "sharp",
+  "workerd"
+];
+var DEP_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies"
+];
 var corePackageJsonSchema2 = z9.looseObject({
+  version: z9.string().optional(),
+  private: z9.boolean().optional(),
   scripts: z9.record(z9.string(), z9.string()).optional(),
-  dependencies: z9.record(z9.string(), z9.string()).optional()
+  dependencies: z9.record(z9.string(), z9.string()).optional(),
+  devDependencies: z9.record(z9.string(), z9.string()).optional(),
+  optionalDependencies: z9.record(z9.string(), z9.string()).optional(),
+  peerDependencies: z9.record(z9.string(), z9.string()).optional(),
+  pnpm: z9.looseObject({}).optional(),
+  catalyst: z9.looseObject({}).optional()
+});
+var registryVersionSchema = z9.object({ version: z9.string() });
+var resolvePublishedVersion = async (pkgName) => {
+  const response = await fetch(`https://registry.npmjs.org/${pkgName}/latest`);
+  if (!response.ok) {
+    throw new Error(
+      `Could not resolve a published version for "${pkgName}" (HTTP ${response.status}). The extracted project still references it via the workspace protocol and cannot be installed.`
+    );
+  }
+  const { version: version2 } = registryVersionSchema.parse(await response.json());
+  return `^${version2}`;
+};
+var rewriteCorePackage = async (projectDir, ref) => {
+  const packageJsonPath = join8(projectDir, "package.json");
+  const pkg = corePackageJsonSchema2.parse(JSON.parse(readFileSync3(packageJsonPath, "utf-8")));
+  const workspaceDeps = DEP_FIELDS.flatMap((field) => {
+    const deps = pkg[field];
+    if (!deps) return [];
+    return Object.entries(deps).filter(([, range]) => range.startsWith("workspace:")).map(([name]) => ({ deps, name }));
+  });
+  await Promise.all(
+    workspaceDeps.map(async ({ deps, name }) => {
+      const resolved = await resolvePublishedVersion(name);
+      deps[name] = resolved;
+      consola.info(`Resolved ${name} to ${resolved}`);
+    })
+  );
+  delete pkg.private;
+  if (pkg.scripts) {
+    pkg.scripts = Object.fromEntries(
+      Object.entries(pkg.scripts).filter(([, command]) => !command.includes("turbo"))
+    );
+  }
+  pkg.pnpm = { ...pkg.pnpm, onlyBuiltDependencies: NATIVE_BUILD_ALLOWLIST };
+  pkg.trustedDependencies = NATIVE_BUILD_ALLOWLIST;
+  pkg.catalyst = { ...pkg.catalyst, version: pkg.version, ref };
+  writeFileSync2(packageJsonPath, `${JSON.stringify(sortPackageJsonFields(pkg), null, 2)}
+`);
+  writeFileSync2(join8(projectDir, ".npmrc"), "legacy-peer-deps=true\n");
+};
+
+// src/cli/lib/setup-core-project.ts
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join9 } from "path";
+import { z as z10 } from "zod";
+var corePackageJsonSchema3 = z10.looseObject({
+  scripts: z10.record(z10.string(), z10.string()).optional(),
+  dependencies: z10.record(z10.string(), z10.string()).optional()
 });
 var writeJson2 = (path, value) => {
-  mkdirSync2(dirname3(path), { recursive: true });
-  writeFileSync2(path, `${JSON.stringify(value, null, 2)}
+  mkdirSync3(dirname3(path), { recursive: true });
+  writeFileSync3(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")));
+  const corePackageJsonPath = join9(projectDir, "package.json");
+  const pkg = corePackageJsonSchema3.parse(JSON.parse(readFileSync4(corePackageJsonPath, "utf-8")));
   pkg.scripts = {
     ...pkg.scripts,
     build: "npm run generate && catalyst build",
@@ -1786,11 +1949,11 @@ var setupCoreProject = (projectDir) => {
 };
 
 // src/cli/lib/write-env.ts
-import { outputFileSync } from "fs-extra/esm";
-import { join as join8 } from "path";
+import { outputFileSync as outputFileSync2 } from "fs-extra/esm";
+import { join as join10 } from "path";
 var writeEnv = (projectDir, envVars) => {
-  outputFileSync(
-    join8(projectDir, "core", ".env.local"),
+  outputFileSync2(
+    join10(projectDir, ".env.local"),
     `${Object.entries(envVars).map(([key, value]) => `${key}=${value}`).join("\n")}
 `
   );
@@ -1801,41 +1964,41 @@ function getPlatformCheckCommand(command) {
   const isWindows = process.platform === "win32";
   return isWindows ? `where.exe ${command}` : `which ${command}`;
 }
-function parseChannelId(value) {
+function parseChannelId2(value) {
   const parsed = parseInt(value, 10);
   if (Number.isNaN(parsed)) {
-    throw new InvalidArgumentError(`"${value}" is not a valid channel ID (expected a number).`);
+    throw new InvalidArgumentError2(`"${value}" is not a valid channel ID (expected a number).`);
   }
   return parsed;
 }
 function parseEnvFlag(value, previous = {}) {
   const eqIdx = value.indexOf("=");
   if (eqIdx <= 0) {
-    throw new InvalidArgumentError(`Expected KEY=VALUE, got "${value}".`);
+    throw new InvalidArgumentError2(`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}".`);
+    throw new InvalidArgumentError2(`Expected KEY=VALUE with non-empty value, got "${value}".`);
   }
   return { ...previous, [key]: val };
 }
 async function handleChannelCreation(storeHash, accessToken, apiHost, cliApiOrigin) {
-  const newChannelName = await input2({
+  const newChannelName = await input3({
     message: "What would you like to name your new channel?"
   });
   const availableLocales = await getAvailableLocales(storeHash, accessToken, apiHost);
-  const storefrontLocale = await select2({
+  const storefrontLocale = await select4({
     message: "Which default language would you like to set for your channel?",
     default: "en",
     choices: availableLocales,
     theme: {
       style: {
-        help: () => colorize3("dim", "(Select locale from the list or start typing the name)")
+        help: () => colorize4("dim", "(Select locale from the list or start typing the name)")
       }
     }
   });
-  const shouldAddAdditionalLocales = await select2({
+  const shouldAddAdditionalLocales = await select4({
     message: "Would you like to add additional languages?",
     choices: [
       { name: "Yes", value: true },
@@ -1844,21 +2007,14 @@ async function handleChannelCreation(storeHash, accessToken, apiHost, cliApiOrig
   });
   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 localeChoices = availableLocales.filter(({ value }) => value !== storefrontLocale).map(({ name, value }) => ({ name, value, description: value }));
+    additionalLocales = await checkbox({
+      message: "Which additional languages would you like to add to your channel?",
+      choices: localeChoices,
+      validate: (items) => items.length <= 4 || "You can only select up to 4 additional languages."
+    });
   }
-  const shouldInstallSampleData = await select2({
+  const shouldInstallSampleData = await select4({
     message: "Would you like to install sample data?",
     choices: [
       { name: "Yes", value: true },
@@ -1876,23 +2032,13 @@ async function handleChannelCreation(storeHash, accessToken, apiHost, cliApiOrig
   );
 }
 async function handleChannelSelection(storeHash, accessToken, apiHost) {
-  const channelSortOrder = ["catalyst", "next", "bigcommerce"];
   const channels = await fetchAvailableChannels(storeHash, accessToken, apiHost);
-  const existingChannel = await select2({
+  const existingChannel = await select4({
     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) => ({
+    choices: sortChannelsByPlatform(channels).map((ch) => ({
       name: ch.name,
       value: ch,
-      description: `Channel Platform: ${ch.platform === "bigcommerce" ? "Stencil" : ch.platform.charAt(0).toUpperCase() + ch.platform.slice(1)}`
+      description: `Channel Platform: ${channelPlatformLabel(ch.platform)}`
     }))
   });
   return existingChannel.id;
@@ -1905,7 +2051,7 @@ async function setupProject(options) {
   }
   if (projectName) {
     projectName = kebabCase(projectName);
-    projectDir = join9(options.projectDir, projectName);
+    projectDir = join11(options.projectDir, projectName);
     if (pathExistsSync(projectDir)) {
       consola.error(`${projectDir} already exists`);
       process.exit(1);
@@ -1915,13 +2061,13 @@ async function setupProject(options) {
     const validateProjectName = (i) => {
       const formatted = kebabCase(i);
       if (!formatted) return "Project name is required";
-      const targetDir = join9(options.projectDir, formatted);
+      const targetDir = join11(options.projectDir, formatted);
       if (pathExistsSync(targetDir)) return `Destination '${targetDir}' already exists`;
       projectName = formatted;
       projectDir = targetDir;
       return true;
     };
-    await input2({
+    await input3({
       message: "What do you want to name your project directory?",
       default: "my-catalyst-app",
       validate: validateProjectName
@@ -1933,19 +2079,11 @@ async function setupProject(options) {
 }
 function checkRequiredTools() {
   try {
-    execSync4(getPlatformCheckCommand("git"), { stdio: "ignore" });
+    execSync2(getPlatformCheckCommand("git"), { stdio: "ignore" });
   } catch {
     consola.error("git is required to create a Catalyst project");
     process.exit(1);
   }
-  try {
-    execSync4(getPlatformCheckCommand("pnpm"), { stdio: "ignore" });
-  } catch {
-    consola.error(
-      "pnpm is required to create a Catalyst project. Enable it by running `corepack enable pnpm`."
-    );
-    process.exit(1);
-  }
 }
 var create = new Command4("create").configureHelp({ showGlobalOptions: true }).description("Scaffold and connect a Catalyst storefront to your BigCommerce store.").addHelpText(
   "after",
@@ -1959,11 +2097,11 @@ Examples:
 
   # 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(
+).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", parseChannelId2).option("--storefront-token <token>", "BigCommerce storefront token").option(
   "--gh-ref <ref>",
-  "Clone a specific ref from the source repository",
+  "Extract a specific ref (tag, branch, or commit) 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(
+).option("--repository <repository>", "GitHub repository to extract from", "bigcommerce/catalyst").option(
   "--env <vars...>",
   "Arbitrary environment variables to set in .env.local. Format: KEY=VALUE (repeatable).",
   parseEnvFlag
@@ -2034,7 +2172,7 @@ Examples:
       }
       let shouldCreateChannel;
       if (eligibility.eligible) {
-        shouldCreateChannel = await select2({
+        shouldCreateChannel = await select4({
           message: "Would you like to create a new channel?",
           choices: [
             { name: "Yes", value: true },
@@ -2093,8 +2231,10 @@ Examples:
     );
   }
   consola.info(`Creating '${projectName}' at '${projectDir}'`);
+  const packageManager = detectPackageManager();
   try {
-    cloneCatalyst({ repository, projectName, projectDir, ghRef, resetMain: options.resetMain });
+    await extractCatalyst({ repository, ref: ghRef, projectDir });
+    await rewriteCorePackage(projectDir, ghRef);
     setupCoreProject(projectDir);
     if (useCommerceHosting && commerceHostingProject && storeHash && accessToken) {
       await setupCommerceHosting({
@@ -2105,8 +2245,8 @@ Examples:
       });
     }
     writeEnv(projectDir, envVars);
-    await installDependencies(projectDir);
-    buildWorkspacePackages(projectDir);
+    await installDependencies(projectDir, packageManager);
+    initGitRepo(projectDir);
   } catch (error) {
     if (pathExistsSync(projectDir)) {
       consola.warn(
@@ -2116,26 +2256,28 @@ Examples:
     throw error;
   }
   consola.success(`Created '${projectName}' at '${projectDir}'`);
-  consola.info("Next steps:");
-  consola.info(colorize3("yellow", `  cd ${projectName}/core && pnpm run dev`));
+  const steps = [`cd ${projectName} && ${packageManager} run dev`];
   if (useCommerceHosting) {
-    consola.info(
-      colorize3(
-        "yellow",
-        `  Run 'cd ${projectName}/core && pnpm run deploy' when ready to deploy to Commerce Hosting.`
-      )
+    steps.push(
+      `Run 'cd ${projectName} && ${packageManager} run deploy' when ready to deploy to Commerce Hosting.`
     );
   }
+  consola.log(
+    `Next steps:
+
+${steps.map((step) => `  ${colorize4("yellow", step)}`).join("\n")}`
+  );
 });
 
 // src/cli/commands/deploy.ts
+import { confirm as confirm3 } from "@inquirer/prompts";
 import AdmZip from "adm-zip";
 import { Command as Command5, Option as Option6 } from "commander";
-import { colorize as colorize4 } from "consola/utils";
+import { colorize as colorize5 } from "consola/utils";
 import { access, readdir, readFile } from "fs/promises";
-import { dirname as dirname4, join as join10 } from "path";
-import yoctoSpinner4 from "yocto-spinner";
-import { z as z10 } from "zod";
+import { join as join12 } from "path";
+import yoctoSpinner3 from "yocto-spinner";
+import { z as z11 } from "zod";
 
 // src/cli/lib/deployment-errors.ts
 var ERROR_MESSAGES = {
@@ -2153,40 +2295,8 @@ function getDeploymentErrorMessage(code) {
   return ERROR_MESSAGES[code] ?? `Deployment failed with an unexpected error (code: ${code}). Please try again. If the issue persists, contact support.`;
 }
 
-// src/cli/lib/env-config.ts
-var ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-var parseEnvAssignment = (input3) => {
-  const separatorIndex = input3.indexOf("=");
-  if (separatorIndex === -1) {
-    throw new Error(`Invalid env var format: ${input3}. Expected format: KEY=VALUE`);
-  }
-  const key = input3.slice(0, separatorIndex).trim();
-  const value = input3.slice(separatorIndex + 1).trim();
-  if (!key || !value) {
-    throw new Error(`Invalid env var format: ${input3}. Expected format: KEY=VALUE`);
-  }
-  if (!ENV_KEY_PATTERN.test(key)) {
-    throw new Error(
-      `Invalid env var name: ${key}. Names must start with a letter or underscore and contain only letters, numbers, and underscores.`
-    );
-  }
-  return { key, value };
-};
-var getStoredEnv = (config2) => {
-  return config2.get("env") ?? {};
-};
-var toDeploymentSecrets = (envVars) => {
-  return Object.entries(envVars).map(([key, value]) => ({ type: "secret", key, value }));
-};
-var mergeDeploymentSecrets = (persisted, flagSecrets) => {
-  const byKey = /* @__PURE__ */ new Map();
-  persisted.forEach((secret) => byKey.set(secret.key, secret));
-  flagSecrets.forEach((secret) => byKey.set(secret.key, secret));
-  return Array.from(byKey.values());
-};
-
 // src/cli/commands/deploy.ts
-var stepsEnum = z10.enum([
+var stepsEnum = z11.enum([
   "initializing",
   "downloading",
   "unzipping",
@@ -2204,41 +2314,41 @@ var STEPS = {
   finalizing: "Finalizing...",
   complete: "Complete"
 };
-var UploadSignatureSchema = z10.object({
-  data: z10.object({
-    upload_url: z10.url(),
-    upload_uuid: z10.string()
+var UploadSignatureSchema = z11.object({
+  data: z11.object({
+    upload_url: z11.url(),
+    upload_uuid: z11.string()
   })
 });
-var CreateDeploymentSchema = z10.object({
-  data: z10.object({
-    deployment_uuid: z10.uuid()
+var CreateDeploymentSchema = z11.object({
+  data: z11.object({
+    deployment_uuid: z11.uuid()
   })
 });
-var ProjectSchema = z10.object({
-  data: z10.array(
-    z10.object({
-      uuid: z10.uuid(),
-      name: z10.string()
+var ProjectSchema = z11.object({
+  data: z11.array(
+    z11.object({
+      uuid: z11.uuid(),
+      name: z11.string()
     })
   )
 });
-var DeploymentStatusSchema = z10.object({
-  deployment_uuid: z10.uuid(),
-  deployment_status: z10.enum(["queued", "in_progress", "failed", "completed"]),
-  event: z10.object({
+var DeploymentStatusSchema = z11.object({
+  deployment_uuid: z11.uuid(),
+  deployment_status: z11.enum(["queued", "in_progress", "failed", "completed"]),
+  event: z11.object({
     step: stepsEnum,
-    progress: z10.number()
+    progress: z11.number()
   }).nullable(),
-  deployment_hostnames: z10.array(z10.string()).optional(),
-  error: z10.object({
-    code: z10.number()
+  deployment_hostnames: z11.array(z11.string()).optional(),
+  error: z11.object({
+    code: z11.number()
   }).optional()
 });
 var generateBundleZip = async () => {
   consola.info("Generating bundle...");
-  const bigcommerceDir = join10(process.cwd(), ".bigcommerce");
-  const distDir = join10(process.cwd(), ".bigcommerce", "dist");
+  const bigcommerceDir = join12(process.cwd(), ".bigcommerce");
+  const distDir = join12(process.cwd(), ".bigcommerce", "dist");
   try {
     await access(distDir);
   } catch {
@@ -2248,7 +2358,7 @@ var generateBundleZip = async () => {
   if (buildDirContents.length === 0) {
     throw new Error(`Dist directory is empty: ${distDir}`);
   }
-  const outputZip = join10(bigcommerceDir, "bundle.zip");
+  const outputZip = join12(bigcommerceDir, "bundle.zip");
   const zip = new AdmZip();
   zip.addLocalFolder(distDir, "output");
   zip.writeZip(outputZip);
@@ -2280,7 +2390,7 @@ var generateUploadSignature = async (storeHash, accessToken, apiHost) => {
 };
 var uploadBundleZip = async (uploadUrl) => {
   consola.info("Uploading bundle...");
-  const zipPath = join10(process.cwd(), ".bigcommerce", "bundle.zip");
+  const zipPath = join12(process.cwd(), ".bigcommerce", "bundle.zip");
   const fileBuffer = await readFile(zipPath);
   const response = await fetch(uploadUrl, {
     method: "PUT",
@@ -2335,7 +2445,7 @@ var createDeployment = async (projectUuid, uploadUuid, storeHash, accessToken, a
 };
 var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost) => {
   consola.info("Fetching deployment status...");
-  const spinner = yoctoSpinner4().start("Fetching...");
+  const spinner = yoctoSpinner3().start("Fetching...");
   const response = await fetch(
     `https://${apiHost}/stores/${storeHash}/v3/infrastructure/deployments/${deploymentUuid}/events`,
     {
@@ -2391,7 +2501,7 @@ var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost
   spinner.success("Deployment completed successfully.");
   if (deploymentHostname) {
     consola.success(
-      `View your deployment at: ${colorize4("blue", `https://${deploymentHostname}`)}`
+      `View your deployment at: ${colorize5("blue", `https://${deploymentHostname}`)}`
     );
   }
   return deploymentHostname;
@@ -2488,23 +2598,23 @@ Example:
     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 }
-    );
+    const shouldSetup = await confirm3({
+      message: "Your project is not yet set up for Commerce Hosting deployments. Would you like to run the Commerce Hosting setup now?",
+      default: 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());
+    const projectDir = process.cwd();
     await setupCommerceHosting({ projectDir, projectUuid, storeHash, accessToken });
     consola.success("Commerce Hosting setup complete.");
     await installDependencies(projectDir);
   } else {
-    await cleanupCloudflareIncompatibilities(dirname4(process.cwd()));
+    await cleanupCloudflareIncompatibilities(process.cwd());
   }
   if (options.prebuilt) {
-    const distDir = join10(process.cwd(), ".bigcommerce", "dist");
+    const distDir = join12(process.cwd(), ".bigcommerce", "dist");
     try {
       await access(distDir);
     } catch {
@@ -2572,18 +2682,467 @@ Example:
   }
 });
 
-// src/cli/commands/env.ts
-import { Command as Command6 } from "commander";
-var MASK = "\u2022\u2022\u2022\u2022\u2022\u2022";
-var add = new Command6("add").configureHelp({ showGlobalOptions: true }).description(
-  "Add or update one or more deployment environment variables. Stored in .bigcommerce/project.json and sent as secrets on every `catalyst deploy`."
-).argument("<vars...>", "One or more environment variables in KEY=VALUE format.").addHelpText(
-  "after",
-  `
-Example:
-  $ catalyst env add BIGCOMMERCE_STORE_HASH=abc123 BIGCOMMERCE_STOREFRONT_TOKEN=ey...`
-).action((vars) => {
-  const config2 = getProjectConfig();
+// src/cli/commands/domains.ts
+import { confirm as confirm4 } from "@inquirer/prompts";
+import { Command as Command6, Option as Option7 } from "commander";
+import { colorize as colorize7 } from "consola/utils";
+
+// src/cli/lib/domains.ts
+import { z as z13 } from "zod";
+
+// src/cli/lib/observability.ts
+import { colorize as colorize6 } from "consola/utils";
+import { z as z12 } from "zod";
+var LOG_LEVELS = ["debug", "info", "warn", "error"];
+var SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1e3;
+var logEntrySchema = z12.object({
+  timestamp: z12.string().nullable().optional(),
+  level: z12.string().optional(),
+  messages: z12.array(z12.unknown()).optional(),
+  is_exception: z12.boolean().optional(),
+  exception_name: z12.string().optional(),
+  request: z12.object({
+    method: z12.string().optional(),
+    url: z12.string().optional(),
+    status_code: z12.number().optional()
+  }).nullable().optional()
+});
+var queryLogsSchema = z12.object({
+  data: z12.array(logEntrySchema)
+});
+var v3ErrorSchema = z12.object({
+  title: z12.string().optional(),
+  errors: z12.record(z12.string(), z12.string()).optional()
+});
+function formatV3Error(body) {
+  const parsed = v3ErrorSchema.safeParse(body);
+  if (!parsed.success) return void 0;
+  const { title, errors } = parsed.data;
+  const fieldErrors = errors && Object.keys(errors).length > 0 ? Object.entries(errors).map(([field, message]) => `${field}: ${message}`).join("; ") : void 0;
+  if (title && fieldErrors) return `${title} (${fieldErrors})`;
+  return title ?? fieldErrors;
+}
+function parseTimeInput(value) {
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed) * 1e3;
+  }
+  const ms = Date.parse(trimmed);
+  return Number.isNaN(ms) ? null : ms;
+}
+var DURATION_UNIT_MS = {
+  s: 1e3,
+  m: 60 * 1e3,
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3
+};
+function parseDuration(value) {
+  const match = /^(\d+)([smhd])$/.exec(value.trim());
+  if (!match) return null;
+  return Number(match[1]) * DURATION_UNIT_MS[match[2]];
+}
+function resolveTimeWindow(opts, nowMs = Date.now()) {
+  const { since } = opts;
+  let { start: start2, end } = opts;
+  let startMs;
+  let endMs;
+  if (end) {
+    endMs = parseTimeInput(end);
+    if (endMs === null) {
+      throw new Error(
+        `Invalid --end value "${end}". Provide an ISO-8601 timestamp or a Unix epoch (seconds).`
+      );
+    }
+  } else {
+    endMs = nowMs;
+    end = new Date(endMs).toISOString();
+  }
+  if (since) {
+    const durationMs = parseDuration(since);
+    if (durationMs === null) {
+      throw new Error(
+        `Invalid --since value "${since}". Provide a duration like 30m, 6h, or 2d (units: s, m, h, d).`
+      );
+    }
+    startMs = endMs - durationMs;
+    start2 = new Date(startMs).toISOString();
+  } else if (start2) {
+    startMs = parseTimeInput(start2);
+    if (startMs === null) {
+      throw new Error(
+        `Invalid --start value "${start2}". Provide an ISO-8601 timestamp or a Unix epoch (seconds).`
+      );
+    }
+  } else {
+    throw new Error("Provide a time window with --since <duration> or --start <time>.");
+  }
+  if (startMs > endMs) {
+    throw new Error("Invalid time window: --start must be before or equal to --end.");
+  }
+  if (endMs - startMs > SEVEN_DAYS_MS) {
+    throw new Error("Invalid time window: the range must not exceed 7 days.");
+  }
+  return { start: start2, end };
+}
+var LEVEL_COLORS = {
+  debug: "gray",
+  info: "green",
+  warn: "yellow",
+  error: "red"
+};
+var UNKNOWN_TIME = "unknown";
+function isRedundantExceptionName(name, message) {
+  const parts = name.split("<*>").map((part) => part.trim()).filter((part) => part.length > 0);
+  return parts.length > 0 && parts.every((part) => message.includes(part));
+}
+var stringifyMessage = (message) => typeof message === "string" ? message : JSON.stringify(message);
+function formatLogEntry(entry, format = "default") {
+  const message = (entry.messages ?? []).map(stringifyMessage).join(" ").replace(/\s+/g, " ").trim();
+  if (format === "short") return message;
+  const level = entry.level ?? "unknown";
+  const coloredLevel = colorize6(LEVEL_COLORS[level.toLowerCase()] ?? "white", level.toUpperCase());
+  const exceptionStr = entry.is_exception && entry.exception_name && !isRedundantExceptionName(entry.exception_name, message) ? ` ${colorize6("red", `[${entry.exception_name}]`)}` : "";
+  let requestStr = "";
+  if (format === "request" && entry.request) {
+    const parts = [];
+    if (entry.request.method) parts.push(entry.request.method);
+    if (entry.request.url) parts.push(entry.request.url);
+    const status = entry.request.status_code ? ` (${entry.request.status_code})` : "";
+    if (parts.length > 0) requestStr = ` ${parts.join(" ")}${status}`;
+  }
+  return `[${entry.timestamp ?? UNKNOWN_TIME}] [${coloredLevel}]${requestStr}${exceptionStr} ${message}`;
+}
+async function queryLogs(projectUuid, storeHash, accessToken, apiHost, params) {
+  const search = new URLSearchParams();
+  search.set("start", params.start);
+  search.set("end", params.end);
+  if (params.method) search.set("method", params.method);
+  if (params.statusCode != null) search.set("status_code", String(params.statusCode));
+  if (params.urlLike) search.set("url:like", params.urlLike);
+  if (params.levelMin) search.set("level:min", params.levelMin);
+  if (params.limit != null) search.set("limit", String(params.limit));
+  const response = await fetch(
+    `https://${apiHost}/stores/${storeHash}/v3/infrastructure/logs/${projectUuid}?${search.toString()}`,
+    {
+      method: "GET",
+      headers: {
+        "X-Auth-Token": accessToken,
+        "X-Correlation-Id": getTelemetry().correlationId,
+        Accept: "application/json"
+      }
+    }
+  );
+  assertAuthorized(response);
+  if (response.status === 403) {
+    throw new Error(
+      "Infrastructure Logs API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
+    );
+  }
+  if (response.status === 404) {
+    throw new Error("Project not found. Check the project UUID.");
+  }
+  if (response.status === 400 || response.status === 422) {
+    const body = await response.json().catch(() => null);
+    throw new Error(formatV3Error(body) ?? "Invalid log query.");
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to fetch logs: ${response.status} ${response.statusText}`);
+  }
+  const res = await response.json();
+  return queryLogsSchema.parse(res);
+}
+
+// src/cli/lib/domains.ts
+var domainStatusSchema = z13.enum(["pending", "verified", "failed", "unknown"]);
+var domainSchema = z13.object({
+  domain: z13.string(),
+  project_uuid: z13.string(),
+  verification_status: domainStatusSchema
+});
+var domainResponseSchema = z13.object({
+  data: domainSchema
+});
+var domainListResponseSchema = z13.object({
+  data: z13.array(domainSchema)
+});
+var DOMAINS_API_NOT_ENABLED = "Infrastructure Domains API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it.";
+function domainsUrl(storeHash, projectUuid, apiHost) {
+  return `https://${apiHost}/stores/${storeHash}/v3/infrastructure/projects/${projectUuid}/domains`;
+}
+function domainUrl(storeHash, projectUuid, domain, apiHost) {
+  return `${domainsUrl(storeHash, projectUuid, apiHost)}/${encodeURIComponent(domain)}`;
+}
+function authHeaders3(accessToken) {
+  return {
+    Accept: "application/json",
+    "X-Auth-Token": accessToken,
+    "X-Correlation-Id": getTelemetry().correlationId
+  };
+}
+function formatResponseStatus(response, message) {
+  return [response.status, response.statusText || message].filter(Boolean).join(" ");
+}
+async function getErrorMessage(response, action) {
+  const body = await response.json().catch(() => null);
+  const message = formatV3Error(body);
+  if (response.status >= 500) {
+    const status = formatResponseStatus(response, message);
+    return `${action}: ${status}. This is a server-side response from the Domains API.`;
+  }
+  return message ?? `${action}: ${response.statusText}`;
+}
+async function assertDomainResponse(response, action) {
+  assertAuthorized(response);
+  if (response.status === 403) {
+    throw new Error(DOMAINS_API_NOT_ENABLED);
+  }
+  if (!response.ok) {
+    throw new Error(await getErrorMessage(response, action));
+  }
+}
+async function createDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainsUrl(storeHash, projectUuid, apiHost), {
+    method: "POST",
+    headers: {
+      ...authHeaders3(accessToken),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ domain })
+  });
+  await assertDomainResponse(response, "Failed to add domain");
+  const result = await response.json();
+  return domainResponseSchema.parse(result).data;
+}
+async function getDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "GET",
+    headers: authHeaders3(accessToken)
+  });
+  await assertDomainResponse(response, "Failed to fetch domain");
+  const result = await response.json();
+  return domainResponseSchema.parse(result).data;
+}
+async function listDomains(projectUuid, storeHash, accessToken, apiHost, filters = {}) {
+  const search = new URLSearchParams();
+  if (filters.domains && filters.domains.length > 0) {
+    search.set("domain:in", filters.domains.join(","));
+  }
+  if (filters.verificationStatus) {
+    search.set("verification_status", filters.verificationStatus);
+  }
+  const query2 = search.toString();
+  const url = `${domainsUrl(storeHash, projectUuid, apiHost)}${query2 ? `?${query2}` : ""}`;
+  const response = await fetch(url, {
+    method: "GET",
+    headers: authHeaders3(accessToken)
+  });
+  await assertDomainResponse(response, "Failed to fetch domains");
+  const result = await response.json();
+  return domainListResponseSchema.parse(result).data;
+}
+async function deleteDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "DELETE",
+    headers: authHeaders3(accessToken)
+  });
+  await assertDomainResponse(response, `Failed to remove domain: ${response.statusText}`);
+}
+
+// src/cli/commands/domains.ts
+var WAIT_INTERVAL_MS = 5e3;
+var WAIT_TIMEOUT_MS = 5 * 60 * 1e3;
+var DOMAIN_STATUS_FILTERS = ["pending", "verified", "failed"];
+var STATUS_COLORS = {
+  pending: "yellow",
+  verified: "green",
+  failed: "red",
+  unknown: "gray"
+};
+var STATUS_LABELS = {
+  pending: "pending",
+  verified: "active",
+  failed: "failed",
+  unknown: "unknown"
+};
+var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+function resolveDomainCommandContext(options) {
+  const config2 = getProjectConfig();
+  const { storeHash, accessToken } = resolveCredentials(options, config2);
+  const projectUuid = resolveProjectUuid(options);
+  return {
+    projectUuid,
+    storeHash,
+    accessToken,
+    apiHost: options.apiHost
+  };
+}
+function formatDomainStatus(status) {
+  return colorize7(STATUS_COLORS[status], STATUS_LABELS[status]);
+}
+function formatDomain(domain) {
+  return `${domain.domain} ${formatDomainStatus(domain.verification_status)}`;
+}
+async function waitForDomainVerification({
+  domain,
+  projectUuid,
+  storeHash,
+  accessToken,
+  apiHost,
+  intervalMs = WAIT_INTERVAL_MS,
+  timeoutMs = WAIT_TIMEOUT_MS
+}) {
+  const startedAt = Date.now();
+  let current = await getDomain(domain, projectUuid, storeHash, accessToken, apiHost);
+  while (current.verification_status === "pending" && Date.now() - startedAt < timeoutMs) {
+    await sleep(intervalMs);
+    current = await getDomain(domain, projectUuid, storeHash, accessToken, apiHost);
+  }
+  return current;
+}
+var add = new Command6("add").configureHelp({ showGlobalOptions: true }).description("Add a custom domain to the current Native Hosting project.").argument("<domain>", "Custom domain to add.").addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst domains add www.example.com
+
+  # Wait until the domain leaves pending verification
+  $ catalyst domains add www.example.com --wait`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--wait", "Poll until domain verification completes or times out.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Adding domain ${domain}...`);
+  let result = await createDomain(
+    domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  consola.success(`Domain ${result.domain} added.`);
+  if (options.wait && result.verification_status === "pending") {
+    consola.start(`Waiting for ${result.domain} to verify...`);
+    result = await waitForDomainVerification({ domain: result.domain, ...context });
+  }
+  consola.log(formatDomain(result));
+  process.exit(0);
+});
+var list = new Command6("list").configureHelp({ showGlobalOptions: true }).description("List custom domains for the current Native Hosting project.").addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst domains list
+
+  # Show pending domains only
+  $ catalyst domains list --status pending`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--domain <domain>", "Only show a specific domain.").addOption(
+  new Option7("--status <status>", "Filter by verification status.").choices(
+    DOMAIN_STATUS_FILTERS
+  )
+).action(async (options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start("Fetching domains...");
+  const result = await listDomains(
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost,
+    {
+      domains: options.domain ? [options.domain] : void 0,
+      verificationStatus: options.status
+    }
+  );
+  consola.success("Domains fetched.");
+  if (result.length === 0) {
+    consola.info("No custom domains found.");
+    process.exit(0);
+    return;
+  }
+  result.forEach((item) => consola.log(formatDomain(item)));
+  process.exit(0);
+});
+var showStatus = new Command6("status").configureHelp({ showGlobalOptions: true }).description("Show the status of a custom domain on the current Native Hosting project.").argument("<domain>", "Custom domain to check.").addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst domains status www.example.com
+
+  # Wait until the domain leaves pending verification
+  $ catalyst domains status www.example.com --wait`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--wait", "Poll until domain verification completes or times out.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Fetching status for ${domain}...`);
+  let result = await getDomain(
+    domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  consola.success("Domain status fetched.");
+  if (options.wait && result.verification_status === "pending") {
+    consola.start(`Waiting for ${result.domain} to verify...`);
+    result = await waitForDomainVerification({ domain: result.domain, ...context });
+  }
+  consola.log(formatDomain(result));
+  process.exit(0);
+});
+var remove = new Command6("remove").configureHelp({ showGlobalOptions: true }).description("Remove a custom domain from the current Native Hosting project.").argument("<domain>", "Custom domain to remove.").addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst domains remove www.example.com
+
+  # Skip confirmation for an active domain
+  $ catalyst domains remove www.example.com --force`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--force", "Skip the confirmation prompt before removing an active domain.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Fetching status for ${domain}...`);
+  const current = await getDomain(
+    domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  if (current.verification_status === "verified" && !options.force) {
+    const confirmed = await confirm4({
+      message: `Remove active domain ${current.domain}? Traffic may stop routing to this project.`,
+      default: false
+    });
+    if (!confirmed) {
+      consola.info("Aborted. No domain was removed.");
+      process.exit(0);
+      return;
+    }
+  }
+  consola.start(`Removing domain ${current.domain}...`);
+  await deleteDomain(
+    current.domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  consola.success(`Domain ${current.domain} removed.`);
+  process.exit(0);
+});
+var domains = new Command6("domains").configureHelp({ showGlobalOptions: true }).description("Manage custom domains for the current Native Hosting project.").addCommand(add).addCommand(list).addCommand(showStatus).addCommand(remove);
+
+// src/cli/commands/env.ts
+import { Command as Command7 } from "commander";
+var MASK = "\u2022\u2022\u2022\u2022\u2022\u2022";
+var add2 = new Command7("add").configureHelp({ showGlobalOptions: true }).description(
+  "Add or update one or more deployment environment variables. Stored in .bigcommerce/project.json and sent as secrets on every `catalyst deploy`."
+).argument("<vars...>", "One or more environment variables in KEY=VALUE format.").addHelpText(
+  "after",
+  `
+Example:
+  $ catalyst env add BIGCOMMERCE_STORE_HASH=abc123 BIGCOMMERCE_STOREFRONT_TOKEN=ey...`
+).action((vars) => {
+  const config2 = getProjectConfig();
   const stored = { ...getStoredEnv(config2) };
   const parsed = vars.map((entry) => parseEnvAssignment(entry));
   parsed.forEach(({ key, value }) => {
@@ -2597,7 +3156,7 @@ Example:
   keys.forEach((key) => consola.log(`  ${key}=${MASK}`));
   process.exit(0);
 });
-var remove = new Command6("remove").configureHelp({ showGlobalOptions: true }).description("Remove one or more stored deployment environment variables.").argument("<keys...>", "One or more environment variable names to remove.").addHelpText(
+var remove2 = new Command7("remove").configureHelp({ showGlobalOptions: true }).description("Remove one or more stored deployment environment variables.").argument("<keys...>", "One or more environment variable names to remove.").addHelpText(
   "after",
   `
 Example:
@@ -2623,7 +3182,7 @@ Example:
   }
   process.exit(0);
 });
-var list = new Command6("list").configureHelp({ showGlobalOptions: true }).description("List stored deployment environment variables (values are masked).").addHelpText(
+var list2 = new Command7("list").configureHelp({ showGlobalOptions: true }).description("List stored deployment environment variables (values are masked).").addHelpText(
   "after",
   `
 Example:
@@ -2640,41 +3199,41 @@ Example:
   keys.forEach((key) => consola.log(`${key}=${MASK}`));
   process.exit(0);
 });
-var env = new Command6("env").configureHelp({ showGlobalOptions: true }).description(
+var env = new Command7("env").configureHelp({ showGlobalOptions: true }).description(
   "Manage persistent deployment environment variables. These are sent as secrets on every `catalyst deploy`, so you no longer need to pass `--secret` each time."
-).addCommand(add).addCommand(remove).addCommand(list);
+).addCommand(add2).addCommand(remove2).addCommand(list2);
 
 // src/cli/commands/logs.ts
-import { Command as Command7, Option as Option7 } from "commander";
-import { colorize as colorize5 } from "consola/utils";
-import { z as z11 } from "zod";
+import { Command as Command8, InvalidArgumentError as InvalidArgumentError3, Option as Option8 } from "commander";
+import { colorize as colorize8 } from "consola/utils";
+import { z as z14 } from "zod";
 var telemetry = new Telemetry();
 var DEFAULT_CONNECTION_TTL_MS = 1 * 60 * 1e3;
 var MAX_RETRIES = 5;
 var isFatalStatusCode = (status) => status >= 400 && status < 500;
-var LEVEL_COLORS = {
+var LEVEL_COLORS2 = {
   INFO: "green",
   WARN: "yellow",
   ERROR: "red",
   DEBUG: "gray"
 };
-var LogEventSchema = z11.object({
-  uuid: z11.string(),
-  project_uuid: z11.string(),
-  request: z11.object({
-    method: z11.string(),
-    url: z11.string(),
-    status_code: z11.number()
+var LogEventSchema = z14.object({
+  uuid: z14.string(),
+  project_uuid: z14.string(),
+  request: z14.object({
+    method: z14.string(),
+    url: z14.string(),
+    status_code: z14.number()
   }),
-  logs: z11.array(
-    z11.object({
-      timestamp: z11.string(),
-      level: z11.string(),
-      messages: z11.array(z11.unknown())
+  logs: z14.array(
+    z14.object({
+      timestamp: z14.string(),
+      level: z14.string(),
+      messages: z14.array(z14.unknown())
     })
   ),
-  exceptions: z11.array(z11.unknown()),
-  timestamp: z11.string()
+  exceptions: z14.array(z14.unknown()),
+  timestamp: z14.string()
 }).loose();
 var StreamError = class extends Error {
   constructor(message, fatal) {
@@ -2688,7 +3247,7 @@ var formatLogEvent = (event, format) => {
   logEntries.forEach((entry) => {
     const msg = formatMessages(entry.messages);
     const level = entry.level.toUpperCase();
-    const coloredLevel = colorize5(LEVEL_COLORS[level] ?? "white", level);
+    const coloredLevel = colorize8(LEVEL_COLORS2[level] ?? "white", level);
     switch (format) {
       case "short":
         consola.log(msg);
@@ -2831,7 +3390,7 @@ var tailLogs = async (projectUuid, storeHash, accessToken, apiHost, format, conn
     }
   }
 };
-var tail = new Command7("tail").configureHelp({ showGlobalOptions: true }).description("Tail live logs from your deployed application.").addHelpText(
+var tail = new Command8("tail").configureHelp({ showGlobalOptions: true }).description("Tail live logs from your deployed application.").addHelpText(
   "after",
   `
 Examples:
@@ -2843,7 +3402,7 @@ Examples:
   # Tail logs as raw JSON (useful for piping to other tools)
   $ catalyst logs tail --format json`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).addOption(
-  new Option7("--format <format>", "Output format for log events.").choices(["json", "pretty", "default", "short", "request"]).default("default")
+  new Option8("--format <format>", "Output format for log events.").choices(["json", "pretty", "default", "short", "request"]).default("default")
 ).action(async (options) => {
   try {
     const config2 = getProjectConfig();
@@ -2856,33 +3415,115 @@ Examples:
     process.exit(1);
   }
 });
-var query = new Command7("query").configureHelp({ showGlobalOptions: true }).description("Query historical logs from your deployed application.").addHelpText(
+var parseIntInRange = (flag, min, max) => (value) => {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new InvalidArgumentError3(`${flag} must be an integer between ${min} and ${max}.`);
+  }
+  return parsed;
+};
+var query = new Command8("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);
+Specify a time window with \`--since\` (relative to now) or \`--start\`/\`--end\`
+(ISO-8601 timestamps or Unix epoch seconds, UTC). The window may not exceed
+7 days. Entries print oldest-first; timestamps are UTC.
+
+Examples:
+  # Last hour of logs
+  $ catalyst logs query --since 1h
+
+  # Everything from today (UTC)
+  $ catalyst logs query --start 2026-06-11T00:00:00Z
+
+  # Errors only for a specific path
+  $ catalyst logs query --since 24h --level-min error --url-like /cart
+
+  # Errors with request details (method, URL, status)
+  $ catalyst logs query --since 1h --level-min error --format request
+
+  # Raw JSON (NDJSON) for piping to other tools
+  $ catalyst logs query --since 2d --format json`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).addOption(
+  new Option8(
+    "--since <duration>",
+    "Relative window ending at --end (default: now), e.g. 30m, 6h, 2d (units: s, m, h, d)."
+  ).conflicts("start")
+).option("--start <time>", "Window start: ISO-8601 timestamp or Unix epoch (seconds).").option(
+  "--end <time>",
+  "Window end: ISO-8601 timestamp or Unix epoch (seconds). Defaults to now. The window must not exceed 7 days."
+).option("--method <method>", "Filter by request HTTP method (case-insensitive).").addOption(
+  new Option8("--status-code <code>", "Filter by response status code (100-599).").argParser(
+    parseIntInRange("--status-code", 100, 599)
+  )
+).option("--url-like <substring>", "Filter by URL substring (case-sensitive).").addOption(
+  new Option8("--level-min <level>", "Minimum log level.").choices(Array.from(LOG_LEVELS))
+).addOption(
+  new Option8("--limit <n>", "Maximum number of entries to return (1-500).").argParser(parseIntInRange("--limit", 1, 500)).default(100)
+).addOption(
+  new Option8("--format <format>", "Output format for log entries.").choices(["json", "pretty", "default", "short", "request"]).default("default")
+).action(async (options) => {
+  try {
+    const config2 = getProjectConfig();
+    const { storeHash, accessToken } = resolveCredentials(options, config2);
+    await telemetry.identify(storeHash);
+    const projectUuid = resolveProjectUuid(options);
+    const { start: start2, end } = resolveTimeWindow(options);
+    const result = await queryLogs(projectUuid, storeHash, accessToken, options.apiHost, {
+      start: start2,
+      end,
+      method: options.method,
+      statusCode: options.statusCode,
+      urlLike: options.urlLike,
+      levelMin: options.levelMin,
+      limit: options.limit
+    });
+    const entries = result.data;
+    const ordered = [...entries].reverse();
+    if (options.format === "json") {
+      ordered.forEach((entry) => process.stdout.write(`${JSON.stringify(entry)}
+`));
+      return;
+    }
+    if (options.format === "pretty") {
+      ordered.forEach((entry) => consola.log(JSON.stringify(entry, null, 2)));
+      return;
+    }
+    if (entries.length === 0) {
+      consola.info("No log entries found for the given window and filters.");
+      return;
+    }
+    const lineFormat = options.format;
+    ordered.forEach((entry) => consola.log(formatLogEntry(entry, lineFormat)));
+    consola.info(
+      `${entries.length} ${entries.length === 1 ? "entry" : "entries"} shown (oldest first, times in UTC).`
+    );
+    if (entries.length === options.limit) {
+      consola.info(
+        `Limit of ${options.limit} reached; older entries may exist. Narrow the time window or raise --limit (max 500) to see more.`
+      );
+    }
+  } catch (error) {
+    consola.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
 });
-var logs = new Command7("logs").configureHelp({ showGlobalOptions: true }).description("View logs from your deployed application.").addCommand(tail, { isDefault: true }).addCommand(query);
+var logs = new Command8("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 Command8 } from "commander";
-import { colorize as colorize6 } from "consola/utils";
-import { dirname as dirname5 } from "path";
+import { confirm as confirm5, input as input4, select as select5 } from "@inquirer/prompts";
+import { Command as Command9 } from "commander";
+import { colorize as colorize9 } from "consola/utils";
 async function offerCommerceHostingSetup(projectUuid, credentials) {
-  const projectDir = dirname5(process.cwd());
+  const projectDir = process.cwd();
   if (getProjectState().isTransformed) {
     await cleanupCloudflareIncompatibilities(projectDir);
     return;
   }
-  const shouldSetup = await consola.prompt(
-    "Your project has been linked, but is not fully set up for Commerce Hosting deployments yet. Would you like to run the setup now?",
-    { type: "confirm", initial: true }
-  );
+  const shouldSetup = await confirm5({
+    message: "Your project has been linked, but is not fully set up for Commerce Hosting deployments yet. Would you like to run the setup now?",
+    default: true
+  });
   if (!shouldSetup) return;
   await setupCommerceHosting({
     projectDir,
@@ -2893,7 +3534,7 @@ async function offerCommerceHostingSetup(projectUuid, credentials) {
   consola.success("Commerce Hosting setup complete.");
   await installDependencies(projectDir);
 }
-var list2 = new Command8("list").configureHelp({ showGlobalOptions: true }).description("List BigCommerce infrastructure projects for your store.").addHelpText(
+var list3 = new Command9("list").configureHelp({ showGlobalOptions: true }).description("List BigCommerce infrastructure projects for your store.").addHelpText(
   "after",
   `
 Example:
@@ -2911,21 +3552,17 @@ Example:
     return;
   }
   const linkedProjectUuid = config2.get("projectUuid");
-  projects.forEach((p) => {
-    const marker = p.uuid === linkedProjectUuid ? ` ${colorize6("green", "[linked]")}` : "";
-    consola.log(`${p.name} (${p.uuid})${marker}`);
-    if (p.deployment_hostnames.length === 0) {
-      consola.log("  (not deployed)");
-    } else {
-      p.deployment_hostnames.forEach((hostname) => {
-        consola.log(`  ${colorize6("blue", `https://${hostname}`)}`);
-      });
-    }
-    consola.log("");
+  const projectList = projects.map((p) => {
+    const marker = p.uuid === linkedProjectUuid ? ` ${colorize9("green", "[linked]")}` : "";
+    const hostnames = p.deployment_hostnames.length === 0 ? ["  (not deployed)"] : p.deployment_hostnames.map(
+      (hostname) => `  ${colorize9("blue", `https://${hostname}`)}`
+    );
+    return [`${p.name} (${p.uuid})${marker}`, ...hostnames].join("\n");
   });
+  consola.log(projectList.join("\n\n"));
   process.exit(0);
 });
-var create2 = new Command8("create").configureHelp({ showGlobalOptions: true }).description(
+var create2 = new Command9("create").configureHelp({ showGlobalOptions: true }).description(
   "Create a new BigCommerce infrastructure project and link it to your local Catalyst project. Walks you through logging in if you are not authenticated yet."
 ).addHelpText(
   "after",
@@ -2959,9 +3596,7 @@ Example:
     }
   }
   await getTelemetry().identify(storeHash);
-  const newProjectName = await consola.prompt("Enter a name for the new project:", {
-    type: "text"
-  });
+  const newProjectName = await input4({ message: "Enter a name for the new project:" });
   const data = await createProject(newProjectName, storeHash, accessToken, options.apiHost);
   consola.success(`Project "${data.name}" created successfully.`);
   consola.start("Writing project UUID to .bigcommerce/project.json...");
@@ -2971,7 +3606,7 @@ Example:
   consola.success("Project UUID written to .bigcommerce/project.json.");
   process.exit(0);
 });
-var link = new Command8("link").configureHelp({ showGlobalOptions: true }).description(
+var link2 = new Command9("link").configureHelp({ showGlobalOptions: true }).description(
   "Link your local Catalyst project to a BigCommerce infrastructure project. You can provide a project UUID directly, or fetch and select from available projects using your store credentials."
 ).addHelpText(
   "after",
@@ -3021,7 +3656,7 @@ Examples:
   await offerCommerceHostingSetup(selected.uuid, { storeHash, accessToken });
   process.exit(0);
 });
-var del = new Command8("delete").configureHelp({ showGlobalOptions: true }).description(
+var del = new Command9("delete").configureHelp({ showGlobalOptions: true }).description(
   "Permanently delete a BigCommerce infrastructure project. This action is irreversible."
 ).addHelpText(
   "after",
@@ -3051,21 +3686,17 @@ Examples:
       return;
     }
     const linkedProjectUuid = config2.get("projectUuid");
-    const selected = await consola.prompt(
-      "Select a project to delete (Press <enter> to select).",
-      {
-        type: "select",
-        options: [
-          ...projects.map((p) => ({
-            label: p.uuid === linkedProjectUuid ? `${p.name} ${colorize6("green", "[linked]")}` : p.name,
-            value: p.uuid,
-            hint: p.uuid
-          })),
-          { label: "Cancel", value: "cancel", hint: "Exit without deleting any project." }
-        ],
-        cancel: "reject"
-      }
-    );
+    const selected = await select5({
+      message: "Select a project to delete (Press <enter> to select).",
+      choices: [
+        ...projects.map((p) => ({
+          name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize9("green", "[linked]")}` : p.name,
+          value: p.uuid,
+          description: p.uuid
+        })),
+        { name: "Cancel", value: "cancel", description: "Exit without deleting any project." }
+      ]
+    });
     if (selected === "cancel") {
       consola.info("Aborted. No project was deleted.");
       process.exit(0);
@@ -3080,10 +3711,10 @@ Examples:
   }
   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 }
-    );
+    const confirmed = await confirm5({
+      message: `Are you sure you want to delete project ${label}? This action is irreversible and will permanently destroy the project and all of its data.`,
+      default: false
+    });
     if (!confirmed) {
       consola.info("Aborted. No project was deleted.");
       process.exit(0);
@@ -3099,14 +3730,14 @@ Examples:
   }
   process.exit(0);
 });
-var project = new Command8("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure project.").addCommand(create2).addCommand(list2).addCommand(link).addCommand(del);
+var project = new Command9("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure project.").addCommand(create2).addCommand(list3).addCommand(link2).addCommand(del);
 
 // src/cli/commands/start.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 import { execa as execa2 } from "execa";
-import { existsSync as existsSync4, lstatSync as lstatSync2, symlinkSync as symlinkSync2 } from "fs";
-import { join as join11, relative } from "path";
-var start = new Command9("start").configureHelp({ showGlobalOptions: true }).description(
+import { existsSync as existsSync3, lstatSync, symlinkSync } from "fs";
+import { join as join13, relative } from "path";
+var start = new Command10("start").configureHelp({ showGlobalOptions: true }).description(
   "Start a local preview of your Catalyst storefront using the OpenNext Cloudflare adapter."
 ).addHelpText(
   "after",
@@ -3123,14 +3754,14 @@ Example:
     });
     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);
+  const envLocal = join13(process.cwd(), ".env.local");
+  const devVars = join13(process.cwd(), ".bigcommerce", ".dev.vars");
+  if (existsSync3(envLocal)) {
+    if (!existsSync3(devVars)) {
+      const target = relative(join13(process.cwd(), ".bigcommerce"), envLocal);
+      symlinkSync(target, devVars);
       consola.success("Symlinked .bigcommerce/.dev.vars \u2192 .env.local");
-    } else if (!lstatSync2(devVars).isSymbolicLink()) {
+    } else if (!lstatSync(devVars).isSymbolicLink()) {
       consola.warn(
         ".bigcommerce/.dev.vars already exists and is not a symlink. Wrangler will use it instead of .env.local."
       );
@@ -3147,7 +3778,7 @@ Example:
       "opennextjs-cloudflare",
       "preview",
       "--config",
-      join11(".bigcommerce", "wrangler.jsonc")
+      join13(".bigcommerce", "wrangler.jsonc")
     ],
     {
       stdio: "inherit",
@@ -3157,11 +3788,11 @@ Example:
 });
 
 // src/cli/commands/telemetry.ts
-import { Argument, Command as Command10, Option as Option8 } from "commander";
-import { colorize as colorize7 } from "consola/utils";
+import { Argument, Command as Command11, Option as Option9 } from "commander";
+import { colorize as colorize10 } from "consola/utils";
 var telemetryService = getTelemetry();
 var isEnabled = telemetryService.isEnabled();
-var telemetry2 = new Command10("telemetry").configureHelp({ showGlobalOptions: true }).description(
+var telemetry2 = new Command11("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",
@@ -3175,7 +3806,7 @@ Examples:
 
   # Disable telemetry collection
   $ catalyst telemetry --disable`
-).addArgument(new Argument("[arg]").choices(["disable", "enable", "status"])).addOption(new Option8("--enable", `Enables CLI telemetry collection.`).conflicts("disable")).option("--disable", `Disables CLI telemetry collection.`).action((arg, options) => {
+).addArgument(new Argument("[arg]").choices(["disable", "enable", "status"])).addOption(new Option9("--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;
@@ -3192,7 +3823,7 @@ Examples:
     consola.info("Catalyst CLI Telemetry\n");
   }
   consola.info(
-    `Status: ${colorize7("bold", isEnabled ? colorize7("green", "Enabled") : colorize7("red", "Disabled"))}`
+    `Status: ${colorize10("bold", isEnabled ? colorize10("green", "Enabled") : colorize10("red", "Disabled"))}`
   );
   if (!isEnabled) {
     consola.info(
@@ -3201,9 +3832,649 @@ Examples:
   }
 });
 
+// src/cli/commands/upgrade.ts
+import { Command as Command12, Option as Option10 } from "@commander-js/extra-typings";
+import { confirm as confirm6 } from "@inquirer/prompts";
+import { execa as execa3 } from "execa";
+import {
+  access as access2,
+  copyFile as copyFile2,
+  cp as cp2,
+  mkdir,
+  mkdtemp,
+  readdir as readdir2,
+  readFile as readFile2,
+  rename,
+  rm as rm2,
+  writeFile as writeFile2
+} from "fs/promises";
+import { homedir, tmpdir } from "os";
+import { dirname as dirname4, join as join14, relative as relative2 } from "path";
+import yoctoSpinner4 from "yocto-spinner";
+import { z as z15 } from "zod";
+var CorePackageJson = z15.object({
+  name: z15.string().optional(),
+  version: z15.string(),
+  catalyst: z15.object({ version: z15.string(), ref: z15.string() }).optional()
+});
+var DEFAULT_REPOSITORY = "bigcommerce/catalyst";
+var MOVING_TAGS = /* @__PURE__ */ new Set(["latest", "canary", "alpha"]);
+var KNOWN_FAMILIES = /* @__PURE__ */ new Set([
+  "@bigcommerce/catalyst-core",
+  "@bigcommerce/catalyst-makeswift",
+  "@bigcommerce/catalyst-b2b-makeswift",
+  "@bigcommerce/catalyst-b2b"
+]);
+var CACHE_DIR = join14(homedir(), ".cache", "catalyst-cli", "cores");
+var pathExists = (p) => access2(p).then(() => true).catch(() => false);
+async function listFiles(dir, prefix = "") {
+  const entries = await readdir2(dir, { withFileTypes: true }).catch(() => []);
+  const nested = await Promise.all(
+    entries.map((entry) => {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      return entry.isDirectory() ? listFiles(join14(dir, entry.name), rel) : Promise.resolve([rel]);
+    })
+  );
+  return nested.flat();
+}
+async function filesEqual(a, b) {
+  const [ba, bb] = await Promise.all([
+    readFile2(a).catch(() => null),
+    readFile2(b).catch(() => null)
+  ]);
+  return ba !== null && bb !== null && ba.equals(bb);
+}
+async function computeBaseSimilarity(baseDir, destDir) {
+  const baseFiles = await listFiles(baseDir);
+  if (baseFiles.length === 0) return 0;
+  const matches = await Promise.all(
+    baseFiles.map((rel) => filesEqual(join14(baseDir, rel), join14(destDir, rel)))
+  );
+  return matches.filter(Boolean).length / baseFiles.length;
+}
+async function isBinary(p) {
+  const buf = await readFile2(p).catch(() => null);
+  if (!buf) return false;
+  return buf.subarray(0, 8e3).includes(0);
+}
+async function copyInto(src, dest) {
+  await mkdir(dirname4(dest), { recursive: true });
+  await copyFile2(src, dest);
+}
+function parseRef(ref) {
+  const lastAt = ref.lastIndexOf("@");
+  if (lastAt <= 0) throw new Error(`Cannot parse ref "${ref}" \u2014 expected <package>@<version>.`);
+  return { packageName: ref.slice(0, lastAt), version: ref.slice(lastAt + 1) };
+}
+async function readResolvedVersion(coreDir) {
+  const raw = await readFile2(join14(coreDir, "package.json"), "utf-8");
+  const pkg = CorePackageJson.parse(JSON.parse(raw));
+  return pkg.catalyst?.version ?? pkg.version;
+}
+async function mergeFile(oursPath, basePath, theirsPath) {
+  const merged = await execa3(
+    "git",
+    [
+      "merge-file",
+      "-p",
+      "-L",
+      "ours",
+      "-L",
+      "base",
+      "-L",
+      "theirs",
+      oursPath,
+      basePath,
+      theirsPath
+    ],
+    { reject: false, stripFinalNewline: false }
+  );
+  if (merged.stderr) throw new Error(`git merge-file failed: ${merged.stderr}`);
+  await writeFile2(oursPath, merged.stdout);
+  return (merged.exitCode ?? 0) > 0;
+}
+async function mergeModified(rel, baseDir, theirsDir, catalystRoot) {
+  const basePath = join14(baseDir, rel);
+  const theirsPath = join14(theirsDir, rel);
+  const oursPath = join14(catalystRoot, rel);
+  if (await filesEqual(basePath, theirsPath)) return null;
+  if (!await pathExists(oursPath)) {
+    await copyInto(theirsPath, oursPath);
+    return "conflicted";
+  }
+  if (await isBinary(basePath) || await isBinary(theirsPath) || await isBinary(oursPath)) {
+    if (await filesEqual(oursPath, basePath)) {
+      await copyInto(theirsPath, oursPath);
+      return "applied";
+    }
+    return "conflicted";
+  }
+  return await mergeFile(oursPath, basePath, theirsPath) ? "conflicted" : "applied";
+}
+async function mergeAdded(rel, theirsDir, catalystRoot, emptyFile) {
+  const theirsPath = join14(theirsDir, rel);
+  const oursPath = join14(catalystRoot, rel);
+  if (!await pathExists(oursPath)) {
+    await copyInto(theirsPath, oursPath);
+    return "added";
+  }
+  if (await filesEqual(oursPath, theirsPath)) return "applied";
+  if (await isBinary(oursPath) || await isBinary(theirsPath)) return "conflicted";
+  const hadConflict = await mergeFile(oursPath, emptyFile, theirsPath);
+  return hadConflict ? "conflicted" : "applied";
+}
+async function mergeDeleted(rel, baseDir, catalystRoot) {
+  const basePath = join14(baseDir, rel);
+  const oursPath = join14(catalystRoot, rel);
+  if (!await pathExists(oursPath)) return null;
+  if (await filesEqual(oursPath, basePath)) {
+    await rm2(oursPath, { force: true });
+    return "deleted";
+  }
+  return "conflicted";
+}
+async function mergeCorePerFile(baseDir, theirsDir, catalystRoot, emptyFile) {
+  const baseFiles = new Set(await listFiles(baseDir));
+  const theirsFiles = new Set(await listFiles(theirsDir));
+  const result = { applied: [], added: [], deleted: [], conflicted: [] };
+  const decide = async (rel) => {
+    const inBase = baseFiles.has(rel);
+    const inTheirs = theirsFiles.has(rel);
+    let outcome;
+    if (inBase && inTheirs) {
+      outcome = await mergeModified(rel, baseDir, theirsDir, catalystRoot);
+    } else if (inTheirs) {
+      outcome = await mergeAdded(rel, theirsDir, catalystRoot, emptyFile);
+    } else {
+      outcome = await mergeDeleted(rel, baseDir, catalystRoot);
+    }
+    if (outcome) result[outcome].push(rel);
+  };
+  await Promise.all([.../* @__PURE__ */ new Set([...baseFiles, ...theirsFiles])].map(decide));
+  return result;
+}
+async function gitSupportsMergeTree() {
+  try {
+    const { stdout } = await execa3("git", ["--version"]);
+    const match = /(\d+)\.(\d+)/.exec(stdout);
+    if (!match) return false;
+    const [major, minor] = [Number(match[1]), Number(match[2])];
+    return major > 2 || major === 2 && minor >= 38;
+  } catch {
+    return false;
+  }
+}
+async function resolveStrategy(strategy) {
+  if (strategy !== "auto") return strategy;
+  if (await gitSupportsMergeTree()) return "tree";
+  consola.warn("git < 2.38 \u2014 using the per-file merge engine (no `git merge-tree`).");
+  return "per-file";
+}
+async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
+  const scratch = await mkdtemp(join14(tmpdir(), "catalyst-merge-"));
+  try {
+    await execa3("git", ["init", "-q", scratch]);
+    await execa3("git", ["config", "core.autocrlf", "false"], {
+      env: { ...process.env, GIT_DIR: join14(scratch, ".git") }
+    });
+    const env2 = {
+      ...process.env,
+      GIT_DIR: join14(scratch, ".git"),
+      GIT_AUTHOR_NAME: "catalyst",
+      GIT_AUTHOR_EMAIL: "catalyst@bigcommerce.com",
+      GIT_COMMITTER_NAME: "catalyst",
+      GIT_COMMITTER_EMAIL: "catalyst@bigcommerce.com"
+    };
+    const writeTree = async (workTree, tag) => {
+      const sideEnv = {
+        ...env2,
+        GIT_WORK_TREE: workTree,
+        GIT_INDEX_FILE: join14(scratch, `index.${tag}`)
+      };
+      await execa3("git", ["add", "-A"], { env: sideEnv });
+      return (await execa3("git", ["write-tree"], { env: sideEnv })).stdout.trim();
+    };
+    const commitTree = (tree, parent) => execa3("git", ["commit-tree", tree, "-m", "x", ...parent ? ["-p", parent] : []], {
+      env: env2
+    }).then((r) => r.stdout.trim());
+    const baseTree = await writeTree(baseDir, "base");
+    const oursTree = await writeTree(catalystRoot, "ours");
+    const theirsTree = await writeTree(theirsDir, "theirs");
+    const baseCommit = await commitTree(baseTree);
+    const [oursCommit, theirsCommit] = await Promise.all([
+      commitTree(oursTree, baseCommit),
+      commitTree(theirsTree, baseCommit)
+    ]);
+    await Promise.all([
+      execa3("git", ["branch", "ours", oursCommit], { env: env2 }),
+      execa3("git", ["branch", "theirs", theirsCommit], { env: env2 })
+    ]);
+    const merge = await execa3(
+      "git",
+      [
+        "merge-tree",
+        "--write-tree",
+        "-z",
+        "--name-only",
+        `--merge-base=${baseCommit}`,
+        "ours",
+        "theirs"
+      ],
+      { env: env2, reject: false }
+    );
+    if ((merge.exitCode ?? 0) > 1)
+      throw new Error(merge.stderr || merge.stdout.slice(0, 500) || "git merge-tree failed");
+    const fields = merge.stdout.split("\0");
+    const mergedTree = fields[0];
+    const afterOid = fields.slice(1);
+    const emptyAt = afterOid.indexOf("");
+    const conflicted = afterOid.slice(0, emptyAt === -1 ? afterOid.length : emptyAt);
+    const conflictedSet = new Set(conflicted);
+    const outEnv = {
+      ...env2,
+      GIT_WORK_TREE: catalystRoot,
+      GIT_INDEX_FILE: join14(scratch, "index.out")
+    };
+    await execa3("git", ["read-tree", mergedTree], { env: outEnv });
+    await execa3("git", ["checkout-index", "-a", "-f"], { env: outEnv });
+    const diff = await execa3(
+      "git",
+      ["diff", "-z", "--no-renames", "--name-status", oursTree, mergedTree],
+      { env: env2 }
+    );
+    const tokens = diff.stdout.split("\0");
+    const changes = [];
+    for (let i = 0; i + 1 < tokens.length; i += 2) {
+      const status = tokens[i];
+      const path = tokens[i + 1];
+      if (status && path && !conflictedSet.has(path)) {
+        changes.push({ status, path });
+      }
+    }
+    const deleted = changes.filter((change) => change.status === "D").map((change) => change.path);
+    await Promise.all(deleted.map((path) => rm2(join14(catalystRoot, path), { force: true })));
+    return {
+      applied: changes.filter((change) => change.status !== "A" && change.status !== "D").map((change) => change.path),
+      added: changes.filter((change) => change.status === "A").map((change) => change.path),
+      deleted,
+      conflicted
+    };
+  } finally {
+    await rm2(scratch, { recursive: true, force: true, maxRetries: 10, retryDelay: 500 });
+  }
+}
+async function applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stampedPkg) {
+  const toRepoPath = (rel) => relDir === "." ? rel : `${relDir}/${rel}`;
+  const pkgRel = "package.json";
+  const stillConflicted = result.conflicted.filter((rel) => !(stampedPkg && rel === pkgRel));
+  const conflictedRepoPaths = new Set(stillConflicted.map(toRepoPath));
+  const clean = [...result.applied, ...result.added, ...result.deleted].map(toRepoPath);
+  if (stampedPkg) clean.push(toRepoPath(pkgRel));
+  const toStage = [...new Set(clean)].filter((path) => !conflictedRepoPaths.has(path));
+  if (toStage.length) {
+    await execa3("git", ["add", "-A", "--", ...toStage], { cwd: gitRoot });
+  }
+  if (stillConflicted.length === 0) return;
+  const OID = /^[0-9a-f]{40,64}$/;
+  const gitFormat = (await execa3("git", ["rev-parse", "--show-object-format"], { cwd: gitRoot, reject: false })).stdout.trim();
+  const NULL_OID = gitFormat === "sha256" ? "0".repeat(64) : "0".repeat(40);
+  const hashBlob = async (file) => {
+    if (!await pathExists(file)) return null;
+    const oid = (await execa3("git", ["hash-object", "-w", "--", file], { cwd: gitRoot })).stdout.trim();
+    return OID.test(oid) ? oid : null;
+  };
+  const headEntry = async (repoPath) => {
+    const { stdout } = await execa3("git", ["ls-tree", "HEAD", "--", repoPath], {
+      cwd: gitRoot,
+      reject: false
+    });
+    const match = /^(\d{6}) blob ([0-9a-f]+)\t/.exec(stdout);
+    return match ? { mode: match[1], oid: match[2] } : null;
+  };
+  const records = await Promise.all(
+    stillConflicted.map(async (rel) => {
+      const repoPath = toRepoPath(rel);
+      const [base, ours, theirs] = await Promise.all([
+        hashBlob(join14(baseDir, rel)),
+        headEntry(repoPath),
+        hashBlob(join14(theirsDir, rel))
+      ]);
+      return [
+        `0 ${NULL_OID}	${repoPath}`,
+        ...base ? [`100644 ${base} 1	${repoPath}`] : [],
+        ...ours ? [`${ours.mode} ${ours.oid} 2	${repoPath}`] : [],
+        ...theirs ? [`100644 ${theirs} 3	${repoPath}`] : []
+      ].join("\n");
+    })
+  );
+  await execa3("git", ["update-index", "--index-info"], {
+    cwd: gitRoot,
+    input: `${records.join("\n")}
+`
+  });
+}
+async function resolveProject2(cwd) {
+  let gitRoot;
+  try {
+    gitRoot = (await execa3("git", ["rev-parse", "--show-toplevel"], { cwd })).stdout.trim();
+  } catch {
+    return null;
+  }
+  const candidateDirs = [.../* @__PURE__ */ new Set([join14(gitRoot, "core"), gitRoot, join14(cwd, "core"), cwd])];
+  const parsed = (await Promise.all(
+    candidateDirs.map(async (dir) => {
+      const pkgPath = join14(dir, "package.json");
+      const raw = await readFile2(pkgPath, "utf-8").catch(() => null);
+      if (!raw) return null;
+      let pkgJson;
+      try {
+        pkgJson = JSON.parse(raw);
+      } catch {
+        return null;
+      }
+      const result = CorePackageJson.safeParse(pkgJson);
+      return result.success ? { dir, pkgPath, raw, pkg: result.data } : null;
+    })
+  )).filter((entry) => entry !== null);
+  if (parsed.length === 0) return null;
+  const chosen = parsed.find((p) => p.pkg.catalyst?.ref) ?? parsed.find((p) => p.pkg.name !== void 0 && KNOWN_FAMILIES.has(p.pkg.name)) ?? parsed[0];
+  return {
+    gitRoot,
+    catalystRoot: chosen.dir,
+    relDir: relative2(gitRoot, chosen.dir) || ".",
+    pkgPath: chosen.pkgPath,
+    rawContent: chosen.raw,
+    pkg: chosen.pkg
+  };
+}
+async function downloadCore(repository, ref, destDir, token) {
+  const cacheable = !MOVING_TAGS.has(parseRef(ref).version);
+  const cacheKey = `${repository.replace(/[^a-zA-Z0-9._-]/g, "_")}__${ref.replace(/[^a-zA-Z0-9._-]/g, "_")}`;
+  const cachePath = join14(CACHE_DIR, cacheKey);
+  if (cacheable && await pathExists(cachePath) && await pathExists(join14(cachePath, "package.json"))) {
+    await cp2(cachePath, destDir, { recursive: true });
+    return;
+  }
+  const url = `https://api.github.com/repos/${repository}/tarball/${encodeURIComponent(ref)}`;
+  const headers = {
+    "User-Agent": "catalyst-cli",
+    Accept: "application/vnd.github+json"
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    let hint = "";
+    if (res.status === 404) hint = ` \u2014 tag "${ref}" not found in ${repository}`;
+    if (res.status === 403) hint = " \u2014 GitHub rate limit hit; set GITHUB_TOKEN to raise it";
+    throw new Error(`GitHub returned ${res.status} for ${ref}${hint}`);
+  }
+  const tarballPath = `${destDir}.tgz`;
+  const rawDir = `${destDir}.raw`;
+  await writeFile2(tarballPath, Buffer.from(await res.arrayBuffer()));
+  await mkdir(rawDir, { recursive: true });
+  await execa3("tar", ["-xzf", tarballPath, "-C", rawDir, "--strip-components=1"]);
+  const coreDir = join14(rawDir, "core");
+  const sourceDir = await pathExists(coreDir) ? coreDir : rawDir;
+  await rename(sourceDir, destDir);
+  await rm2(tarballPath, { force: true });
+  await rm2(rawDir, { recursive: true, force: true });
+  if (cacheable) {
+    await mkdir(CACHE_DIR, { recursive: true });
+    await cp2(destDir, cachePath, { recursive: true }).catch(() => {
+    });
+  }
+}
+async function resolveBaseRef(project2, fromOption, assumeYes) {
+  if (project2.pkg.catalyst?.ref) return project2.pkg.catalyst.ref;
+  if (fromOption) return fromOption;
+  const family = project2.pkg.name && KNOWN_FAMILIES.has(project2.pkg.name) ? project2.pkg.name : "@bigcommerce/catalyst-core";
+  const guess = `${family}@${project2.pkg.version}`;
+  consola.warn(`No \`catalyst.ref\` found in package.json. Inferred base: ${guess}`);
+  if (assumeYes) return guess;
+  const ok = await confirm6({ message: `Upgrade from ${guess}?`, default: true }).catch(() => false);
+  if (!ok) {
+    consola.info("Re-run with `--from <ref>` to set the base version explicitly.");
+    return null;
+  }
+  return guess;
+}
+function printSummary(result, relDir, stampedPkg) {
+  const unresolved = result.conflicted.filter((f) => !(stampedPkg && f === "package.json"));
+  const parts = [
+    `${result.applied.length} updated`,
+    `${result.added.length} added`,
+    `${result.deleted.length} removed`
+  ];
+  if (unresolved.length) parts.push(`${unresolved.length} with conflicts`);
+  consola.log(`
+${parts.join(", ")}`);
+  if (unresolved.length) {
+    const files = unresolved.map((f) => `  ${f}`).join("\n");
+    consola.warn(
+      `
+Staged the clean changes. ${unresolved.length} file(s) need conflict resolution (the <<<ours/===/theirs>>> markers):
+${files}
+
+Resolve them, then: git add ${relDir} && git commit`
+    );
+  } else {
+    consola.success("Staged all changes \u2014 review with `git diff --cached`, then commit.");
+  }
+}
+var upgrade = new Command12("upgrade").configureHelp({ showGlobalOptions: true }).aliases([
+  "up",
+  // These are hidden aliases
+  "upgrayedd",
+  "ugrad"
+]).description("Upgrade your Catalyst project to a newer version by applying a 3-way merge.").argument("[version]", "Target version to upgrade to (default: latest)").addOption(
+  new Option10(
+    "--ref <ref>",
+    "Full git tag to upgrade to, e.g. an integration family like @bigcommerce/catalyst-makeswift@1.7.0. Overrides [version]."
+  )
+).addOption(new Option10("--from <ref>", "Base ref to upgrade from (when catalyst.ref is missing)")).option("--dry-run", "Generate and display the diff without applying it").option("--yes", "Skip confirmation prompts (e.g. inferred base ref)").addOption(
+  new Option10(
+    "--strategy <strategy>",
+    "Merge engine: tree (git merge-tree, full fidelity), per-file (git merge-file, no-history fallback), or auto (tree when git >= 2.38, else per-file)"
+  ).choices(["auto", "tree", "per-file"]).default("auto").hideHelp()
+).addOption(
+  new Option10("--repository <owner/repo>", "GitHub repository to pull versions from").default(
+    DEFAULT_REPOSITORY
+  )
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Upgrade to the latest Catalyst version
+  $ catalyst upgrade
+
+  # Upgrade to a specific version
+  $ catalyst upgrade 1.8.0
+
+  # Preview what would change without applying
+  $ catalyst upgrade --dry-run
+
+  # Upgrade to an integration family (makeswift, b2b-makeswift, ...)
+  $ catalyst upgrade --ref @bigcommerce/catalyst-makeswift@1.7.0
+
+Conflicts are written as standard <<<ours/===/theirs>>> markers \u2014 the upgrade
+never aborts. Versions are git tags on the repository (not npm). Set GITHUB_TOKEN
+to raise the GitHub API rate limit.`
+).action(async (version2, options) => {
+  const project2 = await resolveProject2(process.cwd());
+  if (!project2) {
+    consola.error(
+      "Run `catalyst upgrade` from inside a Catalyst git repository (flat core/ repo or a project containing core/)."
+    );
+    process.exit(1);
+  }
+  const { gitRoot, catalystRoot, relDir, pkgPath } = project2;
+  const baseRef = await resolveBaseRef(project2, options.from, options.yes ?? false);
+  if (!baseRef) process.exit(1);
+  let basePackage;
+  let upstreamRef;
+  let upstreamTagVersion;
+  try {
+    ({ packageName: basePackage } = parseRef(baseRef));
+    upstreamRef = options.ref ?? `${basePackage}@${version2 ?? "latest"}`;
+    ({ version: upstreamTagVersion } = parseRef(upstreamRef));
+  } catch {
+    consola.error(
+      `Invalid ref format \u2014 expected <package>@<version> (e.g. @bigcommerce/catalyst-core@1.7.0). Got: "${baseRef}"`
+    );
+    process.exit(1);
+  }
+  if (upstreamRef === baseRef) {
+    consola.success("Already up to date.");
+    return;
+  }
+  if (!options.dryRun) {
+    const statusArgs = relDir === "." ? [] : ["--", relDir];
+    const status = await execa3("git", ["status", "--porcelain", ...statusArgs], {
+      cwd: gitRoot,
+      reject: false
+    });
+    if (status.stdout.trim()) {
+      const where = relDir === "." ? "The repo" : `${relDir}/`;
+      consola.error(
+        `${where} has uncommitted changes. Commit or stash them before upgrading, so the upgrade is isolated and reversible:
+  git add ${relDir} && git commit -m "snapshot before upgrade"
+  # or: git stash`
+      );
+      process.exit(1);
+    }
+  }
+  if (!project2.pkg.catalyst?.ref && !options.from && !options.dryRun) {
+    const { version: baseVersion } = parseRef(baseRef);
+    const rawPkg = await readFile2(pkgPath, "utf-8");
+    const parsedPkg = z15.record(z15.string(), z15.unknown()).parse(JSON.parse(rawPkg));
+    parsedPkg.catalyst = { version: baseVersion, ref: baseRef };
+    await writeFile2(pkgPath, `${JSON.stringify(parsedPkg, null, 2)}
+`);
+    await execa3("git", ["add", "--", pkgPath], { cwd: gitRoot });
+    consola.success(`Added catalyst.ref \u2192 ${baseRef}`);
+  }
+  const token = process.env.GITHUB_TOKEN;
+  const tmpDir = await mkdtemp(join14(tmpdir(), "catalyst-upgrade-"));
+  try {
+    const baseDir = join14(tmpDir, "base");
+    const theirsDir = join14(tmpDir, "theirs");
+    const emptyFile = join14(tmpDir, ".empty");
+    await writeFile2(emptyFile, "");
+    const downloadSpinner = yoctoSpinner4().start(`Downloading ${baseRef} and ${upstreamRef}...`);
+    try {
+      await Promise.all([
+        downloadCore(options.repository, baseRef, baseDir, token),
+        downloadCore(options.repository, upstreamRef, theirsDir, token)
+      ]);
+      downloadSpinner.success("Downloaded both versions.");
+    } catch (err) {
+      downloadSpinner.error("Download failed");
+      throw err;
+    }
+    if (!project2.pkg.catalyst?.ref && !options.from) {
+      const similarity = await computeBaseSimilarity(baseDir, catalystRoot);
+      const pct = Math.round(similarity * 100);
+      if (similarity < 0.5) {
+        consola.warn(
+          `Low confidence in inferred base ${baseRef} (${pct}% of base files match your project). If the merge result looks off, re-run with \`--from <correct-version>\` to set the base explicitly.`
+        );
+      }
+    }
+    const resolvedVersion = MOVING_TAGS.has(upstreamTagVersion) ? await readResolvedVersion(theirsDir) : upstreamTagVersion;
+    const newRef = MOVING_TAGS.has(upstreamTagVersion) ? `${basePackage}@${resolvedVersion}` : upstreamRef;
+    if (options.dryRun) {
+      const diffSpinner = yoctoSpinner4().start("Generating diff...");
+      const diff = await execa3(
+        "git",
+        ["diff", "--no-index", "--binary", "--diff-algorithm=histogram", "base", "theirs"],
+        { cwd: tmpDir, reject: false, stripFinalNewline: false }
+      );
+      if ((diff.exitCode ?? 0) > 1) {
+        diffSpinner.error("Failed to generate diff");
+        throw new Error(diff.stderr);
+      }
+      if (!diff.stdout.trim()) {
+        diffSpinner.success("No differences between versions \u2014 already up to date.");
+        return;
+      }
+      const fileCount = (diff.stdout.match(/^diff --git /gm) ?? []).length;
+      diffSpinner.success(`Diff ready \u2014 ${fileCount} file(s) affected.`);
+      consola.log("\nDiff preview (--dry-run, not applied):\n");
+      consola.log(diff.stdout);
+      return;
+    }
+    const strategy = await resolveStrategy(options.strategy);
+    const mergeSpinner = yoctoSpinner4().start(`Merging changes (${strategy})...`);
+    const result = strategy === "tree" ? await mergeCoreTree(baseDir, theirsDir, catalystRoot) : await mergeCorePerFile(baseDir, theirsDir, catalystRoot, emptyFile);
+    const total = result.applied.length + result.added.length + result.deleted.length + result.conflicted.length;
+    if (total === 0) {
+      mergeSpinner.success("No differences between versions \u2014 already up to date.");
+      return;
+    }
+    if (result.conflicted.length) {
+      mergeSpinner.warning("Merged with conflicts \u2014 resolve the markers, then commit.");
+    } else {
+      mergeSpinner.success("Merged cleanly.");
+    }
+    const patchedRaw = await readFile2(pkgPath, "utf-8");
+    let stampedPkg = false;
+    try {
+      const patchedPkg = z15.record(z15.string(), z15.unknown()).parse(JSON.parse(patchedRaw));
+      patchedPkg.catalyst = { version: resolvedVersion, ref: newRef };
+      await writeFile2(pkgPath, `${JSON.stringify(patchedPkg, null, 2)}
+`);
+      stampedPkg = true;
+      consola.success(`catalyst.ref updated \u2192 ${newRef}`);
+    } catch {
+      const catalystReplacement = JSON.stringify(
+        { version: resolvedVersion, ref: newRef },
+        null,
+        2
+      ).split("\n").map((line, i) => i === 0 ? line : `  ${line}`).join("\n");
+      const updated = patchedRaw.replace(
+        /"catalyst":\s*\{[^}]*\}/,
+        () => `"catalyst": ${catalystReplacement}`
+      );
+      if (updated !== patchedRaw) {
+        await writeFile2(pkgPath, updated);
+        consola.success(`catalyst.ref updated \u2192 ${newRef}`);
+        consola.info(
+          "package.json still has conflicts in other sections \u2014 resolve them, then: git add package.json"
+        );
+      } else {
+        consola.warn(
+          `package.json has conflicts \u2014 after resolving, add:
+  "catalyst": { "version": "${resolvedVersion}", "ref": "${newRef}" }`
+        );
+      }
+    }
+    try {
+      await applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stampedPkg);
+    } catch (err) {
+      consola.warn(
+        `Couldn't auto-stage the changes (${err instanceof Error ? err.message : String(err)}). Your files are merged on disk \u2014 run \`git add ${relDir}\` yourself.`
+      );
+    }
+    const gitVersion = await execa3("git", ["--version"]).then((r) => r.stdout.trim()).catch(() => "unknown");
+    await getTelemetry().track("upgrade", {
+      strategy,
+      gitVersion,
+      dryRun: Boolean(options.dryRun),
+      applied: result.applied.length,
+      added: result.added.length,
+      deleted: result.deleted.length,
+      conflicts: result.conflicted.length,
+      hasConflicts: result.conflicted.length > 0
+    });
+    printSummary(result, relDir, stampedPkg);
+  } finally {
+    await rm2(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 500 });
+  }
+});
+
 // src/cli/commands/version.ts
-import { Command as Command11 } from "commander";
-var version = new Command11("version").configureHelp({ showGlobalOptions: true }).description("Display detailed version information.").addHelpText(
+import { Command as Command13 } from "commander";
+var version = new Command13("version").configureHelp({ showGlobalOptions: true }).description("Display detailed version information.").addHelpText(
   "after",
   `
 Example:
@@ -3265,19 +4536,19 @@ var telemetryPostHook = async () => {
 
 // src/cli/program.ts
 var defaultEnvPath = resolve(process.cwd(), ".env.local");
-if (existsSync5(defaultEnvPath)) {
+if (existsSync4(defaultEnvPath)) {
   config({ path: defaultEnvPath });
 }
 if (!process.env.CATALYST_STORE_HASH && process.env.BIGCOMMERCE_STORE_HASH) {
   process.env.CATALYST_STORE_HASH = process.env.BIGCOMMERCE_STORE_HASH;
 }
-var program = new Command12();
-consola.log(colorize8("cyanBright", `\u25E2 ${package_default.name} v${package_default.version}
+var program = new Command14();
+consola.log(colorize11("cyanBright", `\u25E2 ${package_default.name} v${package_default.version}
 `));
 program.name(package_default.name).version(package_default.version).summary("CLI tool for Catalyst development").description(
   "CLI tool for Catalyst development.\n\nConfiguration priority: flags > env file (--env-path) > process.env > .env.local (auto-loaded from cwd) > .bigcommerce/project.json.\n\nCATALYST_STORE_HASH falls back to BIGCOMMERCE_STORE_HASH if unset.\n\nRun `catalyst <command> --help` for details on a specific command."
 ).configureHelp({ showGlobalOptions: true }).addOption(
-  new Option9(
+  new Option11(
     "--env-path <path>",
     "Path to environment file to load (relative to current working directory)"
     // We are using argParser, because commander loads in environment variables before executing hooks.
@@ -3293,12 +4564,12 @@ program.name(package_default.name).version(package_default.version).summary("CLI
         const message = errCode === "ENOENT" ? `Env file not found: ${envFilePath}` : `Failed to load --env-path ${value}: ${result.error.message}`;
         throw new Error(message);
       }
-      consola.log(colorize8("cyanBright", `Loaded environment variables from ${envFilePath}
+      consola.log(colorize11("cyanBright", `Loaded environment variables from ${envFilePath}
 `));
     }
     return value;
   })
-).addCommand(version).addCommand(create).addCommand(start).addCommand(build).addCommand(deploy).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(telemetry2).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
+).addCommand(version).addCommand(create).addCommand(start).addCommand(build).addCommand(deploy).addCommand(domains).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(upgrade).addCommand(telemetry2).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
 
 // src/cli/index.ts
 var handleFatalError = async (error) => {