@bigcommerce/catalyst 1.2.0 → 1.3.0

package/dist/cli.js

@@ -25,7 +25,7 @@ import { randomBytes, randomUUID } from "crypto";
 // package.json
 var package_default = {
   name: "@bigcommerce/catalyst",
-  version: "1.2.0",
+  version: "1.3.0",
   type: "module",
   repository: {
     type: "git",
@@ -594,9 +594,9 @@ async function deleteProject(projectUuid, storeHash, accessToken, apiHost) {
 // src/cli/lib/project-config.ts
 import Conf2 from "conf";
 import { join } from "path";
-function getProjectConfig() {
+function getProjectConfig(cwd = process.cwd()) {
   return new Conf2({
-    cwd: join(process.cwd(), ".bigcommerce"),
+    cwd: join(cwd, ".bigcommerce"),
     projectSuffix: "",
     configName: "project",
     schema: {
@@ -647,7 +647,7 @@ var resolveProjectUuid = (options) => {
   const projectUuid = options.projectUuid ?? config2.get("projectUuid");
   if (!projectUuid) {
     throw new Error(
-      "Project UUID is required. Please run either `catalyst project link` or `catalyst project create` or this command again with --project-uuid <uuid>."
+      "Project UUID is required. Please run either `catalyst projects link` or `catalyst projects create` or this command again with --project-uuid <uuid>."
     );
   }
   return projectUuid;
@@ -703,8 +703,8 @@ Example:
     const store = await fetchStoreProfile2(storeHash, accessToken, apiHost);
     const projectUuid = config2.get("projectUuid");
     if (projectUuid) {
-      const projects = await fetchProjects(storeHash, accessToken, apiHost);
-      const linkedProject = projects.find((p) => p.uuid === projectUuid);
+      const projects2 = await fetchProjects(storeHash, accessToken, apiHost);
+      const linkedProject = projects2.find((p) => p.uuid === projectUuid);
       if (linkedProject) {
         consola.info(
           `Logged in to ${store.store_name} (${storeHash}), connected to project ${linkedProject.name} (${projectUuid})`
@@ -1023,6 +1023,10 @@ async function buildCatalystProject(projectUuid, wranglerVersion = WRANGLER_VERS
       cwd: coreDir
     }
   );
+  await copyFile(
+    join4(getModuleCliPath(), "templates", "public_headers"),
+    join4(openNextOutDir, "assets", "_headers")
+  );
   await execa2(
     "pnpm",
     [
@@ -1087,13 +1091,13 @@ Examples:
   const projectUuid = options.projectUuid ?? config2.get("projectUuid");
   if (!projectUuid) {
     throw new Error(
-      "Project UUID is required. Please run `catalyst project create` or `catalyst project link` or this command again with --project-uuid <uuid>."
+      "Project UUID is required. Please run `catalyst projects create` or `catalyst projects link` or this command again with --project-uuid <uuid>."
     );
   }
   await buildCatalystProject(projectUuid, options.wranglerVersion);
 });
 
-// src/cli/commands/channel.ts
+// src/cli/commands/channels.ts
 import { select as select4 } from "@inquirer/prompts";
 import { Command as Command3, InvalidArgumentError as InvalidArgumentError2, Option as Option3 } from "commander";
 import { colorize as colorize5 } from "consola/utils";
@@ -1123,8 +1127,8 @@ var channelsResponseSchema = z7.object({
   data: z7.array(channelSchema)
 });
 var CHANNEL_PLATFORM_ORDER = ["catalyst", "next", "bigcommerce"];
-function sortChannelsByPlatform(channels) {
-  return [...channels].sort((a, b) => {
+function sortChannelsByPlatform(channels2) {
+  return [...channels2].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;
@@ -1289,6 +1293,16 @@ var OPENNEXT_CLOUDFLARE_VERSION = "1.17.3";
 var corePackageJsonSchema = z8.looseObject({
   dependencies: z8.record(z8.string(), z8.string()).optional()
 });
+var projectJsonSchema2 = z8.looseObject({});
+var readProjectJson = (path) => {
+  if (!existsSync3(path)) return {};
+  try {
+    const parsed = projectJsonSchema2.safeParse(JSON.parse(readFileSync2(path, "utf-8")));
+    return parsed.success ? parsed.data : {};
+  } catch {
+    return {};
+  }
+};
 var writeJson = (path, value) => {
   mkdirSync(dirname2(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(value, null, 2)}
@@ -1348,13 +1362,15 @@ var setupCommerceHosting = async ({
     "@opennextjs/cloudflare": OPENNEXT_CLOUDFLARE_VERSION
   };
   writeJson(corePackageJsonPath, sortPackageJsonFields(pkg));
+  const projectJsonPath = join5(projectDir, ".bigcommerce", "project.json");
   const projectJson = {
+    ...readProjectJson(projectJsonPath),
     projectUuid,
     framework: "catalyst"
   };
   if (storeHash) projectJson.storeHash = storeHash;
   if (accessToken) projectJson.accessToken = accessToken;
-  writeJson(join5(projectDir, ".bigcommerce", "project.json"), projectJson);
+  writeJson(projectJsonPath, projectJson);
   convertProxyToMiddleware(projectDir);
 };
 var NoLinkedProjectError = class extends Error {
@@ -1410,7 +1426,7 @@ async function selectOrCreateInfrastructureProject(api, linkedProjectUuid) {
 }
 async function promptForCommerceHostingProject(api, defaultName, autoUseDefaultName, useExistingOnCollision) {
   const existingProjects = await fetchProjects(api.storeHash, api.accessToken, api.apiHost);
-  const takenNames = existingProjects.map((project2) => project2.name);
+  const takenNames = existingProjects.map((project) => project.name);
   if (autoUseDefaultName) {
     return autoCreateCommerceHostingProject(
       api,
@@ -1420,7 +1436,7 @@ async function promptForCommerceHostingProject(api, defaultName, autoUseDefaultN
     );
   }
   const conflict = existingProjects.find(
-    (project2) => project2.name.toLowerCase() === defaultName.toLowerCase()
+    (project) => project.name.toLowerCase() === defaultName.toLowerCase()
   );
   if (!conflict) {
     return autoCreateCommerceHostingProject(
@@ -1452,10 +1468,10 @@ async function promptForCommerceHostingProject(api, defaultName, autoUseDefaultN
   const selected = await select({
     message: "Which Commerce Hosting project would you like to use?",
     choices: [
-      ...existingProjects.map((project2) => ({
-        name: project2.name,
-        value: project2,
-        description: project2.uuid
+      ...existingProjects.map((project) => ({
+        name: project.name,
+        value: project,
+        description: project.uuid
       })),
       new Separator(),
       { name: "Create a new project", value: "create-new" }
@@ -1519,7 +1535,7 @@ async function resolveCollisionChoice(existingName, useExistingOnCollision) {
 }
 async function autoCreateCommerceHostingProject(api, name, existingProjects, useExistingOnCollision) {
   const existing = existingProjects.find(
-    (project2) => project2.name.toLowerCase() === name.toLowerCase()
+    (project) => project.name.toLowerCase() === name.toLowerCase()
   );
   if (existing) {
     const shouldUseExisting = await resolveCollisionChoice(existing.name, useExistingOnCollision);
@@ -1556,8 +1572,8 @@ async function resolveProject(options) {
     apiHost: options.apiHost
   };
   if (options.projectUuid) {
-    const projects = await fetchProjects(api.storeHash, api.accessToken, api.apiHost);
-    const matched = projects.find((p) => p.uuid === options.projectUuid);
+    const projects2 = await fetchProjects(api.storeHash, api.accessToken, api.apiHost);
+    const matched = projects2.find((p) => p.uuid === options.projectUuid);
     if (matched) return matched;
     consola.warn(
       `Project ${options.projectUuid} not found on this store. Pick another to continue.`
@@ -1570,13 +1586,13 @@ async function resolveChannel(options) {
     return { id: options.channelId };
   }
   consola.start("Fetching channels...");
-  const channels = await fetchAvailableChannels(
+  const channels2 = await fetchAvailableChannels(
     options.storeHash,
     options.accessToken,
     options.apiHost
   );
   consola.success("Channels fetched.");
-  const catalystChannels = channels.filter((c) => c.platform === "catalyst");
+  const catalystChannels = channels2.filter((c) => c.platform === "catalyst");
   if (catalystChannels.length === 0) {
     throw new Error(
       "No Catalyst channels found on this store. Create one with `catalyst create` and try again."
@@ -1593,19 +1609,19 @@ async function resolveChannel(options) {
   const matched = catalystChannels.find((c) => c.id === id);
   return { id, name: matched?.name };
 }
-async function resolveHostname(project2, options) {
+async function resolveHostname(project, options) {
   if (options.hostname) {
     return options.hostname;
   }
-  if (project2.deployment_hostnames.length === 0) {
+  if (project.deployment_hostnames.length === 0) {
     throw new Error(
-      `Project "${project2.name}" has no deployment hostnames yet. Run \`catalyst deploy\` first to create one.`
+      `Project "${project.name}" has no deployment hostnames yet. Run \`catalyst deploy\` first to create one.`
     );
   }
   const ordered = options.preferHostname ? [
-    ...project2.deployment_hostnames.filter((h) => h === options.preferHostname),
-    ...project2.deployment_hostnames.filter((h) => h !== options.preferHostname)
-  ] : project2.deployment_hostnames;
+    ...project.deployment_hostnames.filter((h) => h === options.preferHostname),
+    ...project.deployment_hostnames.filter((h) => h !== options.preferHostname)
+  ] : project.deployment_hostnames;
   const selected = await select2({
     message: "Select the hostname to point the channel at.",
     choices: ordered.map((h) => ({ name: h, value: h }))
@@ -1613,18 +1629,18 @@ async function resolveHostname(project2, options) {
   return selected;
 }
 async function runChannelSiteUrlFlow(options) {
-  const project2 = await resolveProject(options);
-  const channel2 = await resolveChannel(options);
-  const hostname = await resolveHostname(project2, options);
+  const project = await resolveProject(options);
+  const channel = await resolveChannel(options);
+  const hostname = await resolveHostname(project, options);
   const siteUrl = hostname.startsWith("https://") ? hostname : `https://${hostname}`;
   await updateChannelSiteUrl(
-    channel2.id,
+    channel.id,
     siteUrl,
     options.storeHash,
     options.accessToken,
     options.apiHost
   );
-  const channelLabel = channel2.name ? `"${channel2.name}" (${channel2.id})` : String(channel2.id);
+  const channelLabel = channel.name ? `"${channel.name}" (${channel.id})` : String(channel.id);
   consola.success(`Updated channel ${channelLabel} site URL to ${siteUrl}.`);
 }
 
@@ -1749,7 +1765,8 @@ async function runCreateChannelFlow(options) {
       { name: "No", value: false }
     ]
   });
-  return createChannel(
+  consola.start("Creating channel...");
+  const channel = await createChannel(
     name,
     storefrontLocale,
     additionalLocales,
@@ -1758,6 +1775,8 @@ async function runCreateChannelFlow(options) {
     accessToken,
     cliApiOrigin
   );
+  consola.success("Channel created.");
+  return channel;
 }
 
 // src/cli/lib/env-config.ts
@@ -1874,7 +1893,7 @@ var writeEnv = (projectDir, envVars) => {
 `);
 };
 
-// src/cli/commands/channel.ts
+// src/cli/commands/channels.ts
 var parseChannelId = (value) => {
   const parsed = Number.parseInt(value, 10);
   if (Number.isNaN(parsed)) {
@@ -1907,10 +1926,10 @@ var update = new Command3("update").configureHelp({ showGlobalOptions: true }).d
   `
 Examples:
   # Pick a channel and hostname interactively
-  $ catalyst channel update
+  $ catalyst channels update
 
   # Skip both prompts
-  $ catalyst channel update --channel-id 123 --hostname my-storefront.example.com`
+  $ catalyst channels update --channel-id 123 --hostname my-storefront.example.com`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).addOption(
   new Option3(
     "--channel-id <id>",
@@ -1938,7 +1957,7 @@ Examples:
   } catch (error) {
     if (error instanceof NoLinkedProjectError) {
       consola.info(
-        "When you're ready to create a project, run `catalyst project create` or re-run `catalyst channel update`."
+        "When you're ready to create a project, run `catalyst projects create` or re-run `catalyst channels update`."
       );
       process.exit(0);
       return;
@@ -1954,13 +1973,13 @@ var link = new Command3("link").configureHelp({ showGlobalOptions: true }).descr
   `
 Examples:
   # Pick a channel interactively (logs you in if needed)
-  $ catalyst channel link
+  $ catalyst channels link
 
   # Non-interactive
-  $ catalyst channel link --store-hash <hash> --access-token <token> --channel-id 123
+  $ catalyst channels link --store-hash <hash> --access-token <token> --channel-id 123
 
   # Append extra environment variables to .env.local
-  $ catalyst channel link --channel-id 123 --env MY_FLAG=1`
+  $ catalyst channels link --channel-id 123 --env MY_FLAG=1`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).addOption(
   new Option3("--channel-id <id>", "Link this channel directly, skipping the picker.").argParser(
     parseChannelId
@@ -1976,7 +1995,7 @@ Examples:
   const credentials = await resolveCredentialsWithLogin(options, config2, apiHost);
   if (!credentials) {
     consola.info(
-      "Login aborted. Re-run `catalyst channel link` when you have your credentials ready."
+      "Login aborted. Re-run `catalyst channels link` when you have your credentials ready."
     );
     process.exit(0);
     return;
@@ -1986,8 +2005,8 @@ Examples:
   let channelId = options.channelId;
   let channelName;
   if (channelId === void 0) {
-    const channels = await fetchAvailableChannels(storeHash, accessToken, apiHost);
-    if (channels.length === 0) {
+    const availableChannels = await fetchAvailableChannels(storeHash, accessToken, apiHost);
+    if (availableChannels.length === 0) {
       consola.info(
         "No storefront channels found on this store. Create one with `catalyst create` and try again."
       );
@@ -1996,13 +2015,13 @@ Examples:
     }
     channelId = await select4({
       message: "Which channel would you like to link?",
-      choices: sortChannelsByPlatform(channels).map((c) => ({
+      choices: sortChannelsByPlatform(availableChannels).map((c) => ({
         name: c.name,
         value: c.id,
         description: channelPlatformLabel(c.platform)
       }))
     });
-    channelName = channels.find((c) => c.id === channelId)?.name;
+    channelName = availableChannels.find((c) => c.id === channelId)?.name;
   }
   const initData = await getChannelInit(channelId, storeHash, accessToken, options.cliApiOrigin);
   const envVars = { ...initData.envVars };
@@ -2027,13 +2046,13 @@ var create = new Command3("create").configureHelp({ showGlobalOptions: true }).d
   `
 Examples:
   # Create a channel interactively (logs you in if needed)
-  $ catalyst channel create
+  $ catalyst channels create
 
   # Non-interactive, and link it to this project afterwards
-  $ catalyst channel create --name "My Store" --locale en --no-sample-data --link
+  $ catalyst channels create --name "My Store" --locale en --no-sample-data --link
 
   # Add additional storefront languages (max 4)
-  $ catalyst channel create --name "My Store" --additional-locales es fr`
+  $ catalyst channels create --name "My Store" --additional-locales es fr`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).option("--name <name>", "Name for the new channel. Skips the name prompt.").option(
   "--locale <locale>",
   'Default storefront locale (e.g. "en"). Skips the default-language prompt.'
@@ -2056,7 +2075,7 @@ Examples:
   const credentials = await resolveCredentialsWithLogin(options, config2, apiHost);
   if (!credentials) {
     consola.info(
-      "Login aborted. Re-run `catalyst channel create` when you have your credentials ready."
+      "Login aborted. Re-run `catalyst channels create` when you have your credentials ready."
     );
     process.exit(0);
     return;
@@ -2101,7 +2120,7 @@ Examples:
   }
   process.exit(0);
 });
-var channel = new Command3("channel").configureHelp({ showGlobalOptions: true }).description("Manage BigCommerce channels.").addCommand(create).addCommand(link).addCommand(update);
+var channels = new Command3("channels").alias("channel").configureHelp({ showGlobalOptions: true }).description("Manage BigCommerce channels.").addCommand(create).addCommand(link).addCommand(update);
 
 // src/cli/commands/create.ts
 import { Command as Command4, InvalidArgumentError as InvalidArgumentError3, Option as Option4 } from "@commander-js/extra-typings";
@@ -2110,10 +2129,27 @@ import { execSync as execSync2 } from "child_process";
 import { colorize as colorize6 } from "consola/utils";
 import { pathExistsSync } from "fs-extra/esm";
 import kebabCase from "lodash.kebabcase";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 
 // src/cli/lib/detect-package-manager.ts
+import { access } from "fs/promises";
+import { join as join7 } from "path";
 import { detectPackageManager as detectFromDir } from "nypm";
+var PROJECT_LOCKFILES = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["package-lock.json", "npm"]
+];
+var detectLockfileManager = async (dir) => {
+  const found = await Promise.all(
+    PROJECT_LOCKFILES.map(
+      async ([file, manager]) => access(join7(dir, file)).then(() => manager).catch(() => null)
+    )
+  );
+  return found.find((manager) => manager !== null) ?? null;
+};
 var detectPackageManager = () => {
   const userAgent = process.env.npm_config_user_agent ?? "";
   const name = userAgent.split(" ")[0]?.split("/")[0];
@@ -2189,7 +2225,7 @@ var extractCatalyst = async ({
 // src/cli/lib/init-git-repo.ts
 import { execSync } from "child_process";
 import { rmSync } from "fs";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 var run = (command, cwd) => execSync(command, { cwd, stdio: "ignore" });
 var initGitRepo = (projectDir) => {
   try {
@@ -2198,7 +2234,7 @@ var initGitRepo = (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 });
+    rmSync(join8(projectDir, ".git"), { recursive: true, force: true });
     consola.warn("Could not initialize a git repository. Skipping.");
   }
 };
@@ -2242,7 +2278,7 @@ var installDependencies = async (projectDir, packageManager = "pnpm") => {
 
 // src/cli/lib/rewrite-core-package.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 import { z as z10 } from "zod";
 var NATIVE_BUILD_ALLOWLIST = [
   "@parcel/watcher",
@@ -2284,7 +2320,7 @@ var resolvePublishedVersion = async (pkgName) => {
   return `^${version2}`;
 };
 var rewriteCorePackage = async (projectDir, ref) => {
-  const packageJsonPath = join8(projectDir, "package.json");
+  const packageJsonPath = join9(projectDir, "package.json");
   const pkg = corePackageJsonSchema2.parse(JSON.parse(readFileSync4(packageJsonPath, "utf-8")));
   const workspaceDeps = DEP_FIELDS.flatMap((field) => {
     const deps = pkg[field];
@@ -2309,12 +2345,12 @@ var rewriteCorePackage = async (projectDir, ref) => {
   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");
+  writeFileSync2(join9(projectDir, ".npmrc"), "legacy-peer-deps=true\n");
 };
 
 // src/cli/lib/setup-core-project.ts
 import { mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname3, join as join9 } from "path";
+import { dirname as dirname3, join as join10 } from "path";
 import { z as z11 } from "zod";
 var corePackageJsonSchema3 = z11.looseObject({
   scripts: z11.record(z11.string(), z11.string()).optional(),
@@ -2326,7 +2362,7 @@ var writeJson2 = (path, value) => {
 `);
 };
 var setupCoreProject = (projectDir) => {
-  const corePackageJsonPath = join9(projectDir, "package.json");
+  const corePackageJsonPath = join10(projectDir, "package.json");
   const pkg = corePackageJsonSchema3.parse(JSON.parse(readFileSync5(corePackageJsonPath, "utf-8")));
   pkg.scripts = {
     ...pkg.scripts,
@@ -2366,10 +2402,10 @@ function parseEnvFlag(value, previous = {}) {
   return { ...previous, [key]: val };
 }
 async function handleChannelSelection(storeHash, accessToken, apiHost) {
-  const channels = await fetchAvailableChannels(storeHash, accessToken, apiHost);
+  const channels2 = await fetchAvailableChannels(storeHash, accessToken, apiHost);
   const existingChannel = await select5({
     message: "Which channel would you like to use?",
-    choices: sortChannelsByPlatform(channels).map((ch) => ({
+    choices: sortChannelsByPlatform(channels2).map((ch) => ({
       name: ch.name,
       value: ch,
       description: `Channel Platform: ${channelPlatformLabel(ch.platform)}`
@@ -2385,7 +2421,7 @@ async function setupProject(options) {
   }
   if (projectName) {
     projectName = kebabCase(projectName);
-    projectDir = join10(options.projectDir, projectName);
+    projectDir = join11(options.projectDir, projectName);
     if (pathExistsSync(projectDir)) {
       consola.error(`${projectDir} already exists`);
       process.exit(1);
@@ -2395,7 +2431,7 @@ async function setupProject(options) {
     const validateProjectName = (i) => {
       const formatted = kebabCase(i);
       if (!formatted) return "Project name is required";
-      const targetDir = join10(options.projectDir, formatted);
+      const targetDir = join11(options.projectDir, formatted);
       if (pathExistsSync(targetDir)) return `Destination '${targetDir}' already exists`;
       projectName = formatted;
       projectDir = targetDir;
@@ -2578,6 +2614,11 @@ Examples:
         accessToken
       });
     }
+    if (storeHash && accessToken) {
+      const projectConfig = getProjectConfig(projectDir);
+      projectConfig.set("storeHash", storeHash);
+      projectConfig.set("accessToken", accessToken);
+    }
     writeEnv(projectDir, envVars);
     await installDependencies(projectDir, packageManager);
     initGitRepo(projectDir);
@@ -2610,7 +2651,7 @@ import { Command as Command5, Option as Option5 } from "commander";
 import { parse } from "dotenv";
 import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
 import { release } from "os";
-import { dirname as dirname4, join as join11 } from "path";
+import { dirname as dirname4, join as join12 } from "path";
 import { z as z12 } from "zod";
 var CLI_ENV_VARS = [
   "CATALYST_STORE_HASH",
@@ -2627,7 +2668,7 @@ var BUILD_ENV_VARS = [
   "AUTH_SECRET"
 ];
 var ENV_FILES = [".env.local", ".env"];
-var PROJECT_LOCKFILES = [
+var PROJECT_LOCKFILES2 = [
   ["pnpm-lock.yaml", "pnpm"],
   ["yarn.lock", "yarn"],
   ["bun.lock", "bun"],
@@ -2638,7 +2679,7 @@ var hasValue = (value) => value !== void 0 && value.trim() !== "";
 var buildEnvLayers = (cwd, env2) => {
   const layers = [{ source: "process.env", values: env2 }];
   ENV_FILES.forEach((file) => {
-    const path = join11(cwd, file);
+    const path = join12(cwd, file);
     if (!existsSync5(path)) {
       return;
     }
@@ -2661,7 +2702,7 @@ var resolveValue = (envSource, configValue) => {
   return { present: false, source: "unset" };
 };
 var asString = (value) => typeof value === "string" ? value : void 0;
-var lockfileManager = (dir) => PROJECT_LOCKFILES.find(([file]) => existsSync5(join11(dir, file)))?.[1];
+var lockfileManager = (dir) => PROJECT_LOCKFILES2.find(([file]) => existsSync5(join12(dir, file)))?.[1];
 var detectProjectPackageManager2 = (cwd) => {
   let dir = cwd;
   for (; ; ) {
@@ -2676,7 +2717,7 @@ var detectProjectPackageManager2 = (cwd) => {
     dir = parent;
   }
 };
-var projectJsonSchema2 = z12.looseObject({});
+var projectJsonSchema3 = z12.looseObject({});
 var safeReadJson2 = (path) => {
   try {
     return JSON.parse(readFileSync6(path, "utf-8"));
@@ -2684,9 +2725,9 @@ var safeReadJson2 = (path) => {
     return null;
   }
 };
-var readProjectJson = (cwd) => {
-  const result = projectJsonSchema2.safeParse(
-    safeReadJson2(join11(cwd, ".bigcommerce", "project.json"))
+var readProjectJson2 = (cwd) => {
+  const result = projectJsonSchema3.safeParse(
+    safeReadJson2(join12(cwd, ".bigcommerce", "project.json"))
   );
   return result.success ? result.data : null;
 };
@@ -2696,7 +2737,7 @@ var storefrontPackageSchema = z12.looseObject({
   catalyst: z12.looseObject({ version: z12.string().optional() }).optional()
 });
 var readStorefrontInfo = (cwd) => {
-  const result = storefrontPackageSchema.safeParse(safeReadJson2(join11(cwd, "package.json")));
+  const result = storefrontPackageSchema.safeParse(safeReadJson2(join12(cwd, "package.json")));
   if (!result.success) {
     return { name: null, version: null };
   }
@@ -2718,7 +2759,7 @@ function collectDiagnostics({
 } = {}) {
   const state = getProjectState(cwd);
   const telemetry2 = getTelemetry();
-  const projectJson = readProjectJson(cwd);
+  const projectJson = readProjectJson2(cwd);
   const storefront = readStorefrontInfo(cwd);
   const cliEnv = [{ source: "process.env", values: env2 }];
   const buildEnv = buildEnvLayers(cwd, env2);
@@ -2773,12 +2814,12 @@ function collectDiagnostics({
       correlationId: telemetry2.correlationId
     },
     files: {
-      ".env.local": existsSync5(join11(cwd, ".env.local")),
-      ".env": existsSync5(join11(cwd, ".env")),
-      ".bigcommerce/project.json": existsSync5(join11(cwd, ".bigcommerce", "project.json")),
-      ".bigcommerce/wrangler.jsonc": existsSync5(join11(cwd, ".bigcommerce", "wrangler.jsonc")),
-      ".open-next/": existsSync5(join11(cwd, ".open-next")),
-      "package.json": existsSync5(join11(cwd, "package.json"))
+      ".env.local": existsSync5(join12(cwd, ".env.local")),
+      ".env": existsSync5(join12(cwd, ".env")),
+      ".bigcommerce/project.json": existsSync5(join12(cwd, ".bigcommerce", "project.json")),
+      ".bigcommerce/wrangler.jsonc": existsSync5(join12(cwd, ".bigcommerce", "wrangler.jsonc")),
+      ".open-next/": existsSync5(join12(cwd, ".open-next")),
+      "package.json": existsSync5(join12(cwd, "package.json"))
     }
   };
 }
@@ -2869,8 +2910,8 @@ import { confirm as confirm3 } from "@inquirer/prompts";
 import AdmZip from "adm-zip";
 import { Command as Command6, Option as Option6 } from "commander";
 import { colorize as colorize7 } from "consola/utils";
-import { access, readdir, readFile } from "fs/promises";
-import { join as join12 } from "path";
+import { access as access2, readdir, readFile } from "fs/promises";
+import { join as join13 } from "path";
 import yoctoSpinner3 from "yocto-spinner";
 import { z as z13 } from "zod";
 
@@ -2942,10 +2983,10 @@ var DeploymentStatusSchema = z13.object({
 });
 var generateBundleZip = async () => {
   consola.info("Generating bundle...");
-  const bigcommerceDir = join12(process.cwd(), ".bigcommerce");
-  const distDir = join12(process.cwd(), ".bigcommerce", "dist");
+  const bigcommerceDir = join13(process.cwd(), ".bigcommerce");
+  const distDir = join13(process.cwd(), ".bigcommerce", "dist");
   try {
-    await access(distDir);
+    await access2(distDir);
   } catch {
     throw new Error(`Dist directory not found: ${distDir}`);
   }
@@ -2953,7 +2994,7 @@ var generateBundleZip = async () => {
   if (buildDirContents.length === 0) {
     throw new Error(`Dist directory is empty: ${distDir}`);
   }
-  const outputZip = join12(bigcommerceDir, "bundle.zip");
+  const outputZip = join13(bigcommerceDir, "bundle.zip");
   const zip = new AdmZip();
   zip.addLocalFolder(distDir, "output");
   zip.writeZip(outputZip);
@@ -2985,7 +3026,7 @@ var generateUploadSignature = async (storeHash, accessToken, apiHost) => {
 };
 var uploadBundleZip = async (uploadUrl) => {
   consola.info("Uploading bundle...");
-  const zipPath = join12(process.cwd(), ".bigcommerce", "bundle.zip");
+  const zipPath = join13(process.cwd(), ".bigcommerce", "bundle.zip");
   const fileBuffer = await readFile(zipPath);
   const response = await fetch(uploadUrl, {
     method: "PUT",
@@ -3120,7 +3161,7 @@ var fetchProject = async (projectUuid, storeHash, accessToken, apiHost) => {
   }
   const res = await response.json();
   const { data } = ProjectSchema.parse(res);
-  return data.find((project2) => project2.uuid === projectUuid);
+  return data.find((project) => project.uuid === projectUuid);
 };
 var deploy = new Command6("deploy").configureHelp({ showGlobalOptions: true }).description("Deploy your application to Cloudflare.").addHelpText(
   "after",
@@ -3166,7 +3207,7 @@ Example:
     } catch (error) {
       if (error instanceof NoLinkedProjectError) {
         consola.info(
-          "When you're ready to create a project, run `catalyst project create` or re-run `catalyst deploy`."
+          "When you're ready to create a project, run `catalyst projects create` or re-run `catalyst deploy`."
         );
         process.exit(0);
       }
@@ -3211,9 +3252,9 @@ Example:
     await cleanupCloudflareIncompatibilities(process.cwd());
   }
   if (options.prebuilt) {
-    const distDir = join12(process.cwd(), ".bigcommerce", "dist");
+    const distDir = join13(process.cwd(), ".bigcommerce", "dist");
     try {
-      await access(distDir);
+      await access2(distDir);
     } catch {
       throw new Error(
         "No build output found at .bigcommerce/dist/. Run `catalyst build` first or remove `--prebuilt` to build automatically."
@@ -3295,6 +3336,7 @@ var LOG_LEVELS = ["debug", "info", "warn", "error"];
 var SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1e3;
 var logEntrySchema = z14.object({
   timestamp: z14.string().nullable().optional(),
+  entry_type: z14.string().optional(),
   level: z14.string().optional(),
   messages: z14.array(z14.unknown()).optional(),
   is_exception: z14.boolean().optional(),
@@ -3411,8 +3453,16 @@ function isRedundantExceptionName(name, message) {
   return parts.length > 0 && parts.every((part) => message.includes(part));
 }
 var stringifyMessage = (message) => typeof message === "string" ? message : JSON.stringify(message);
+var joinMessages = (messages) => (messages ?? []).map(stringifyMessage).join(" ").replace(/\s+/g, " ").trim();
+function isRequestLogEntry(entry) {
+  if (entry.entry_type != null) return entry.entry_type === "request";
+  const method = entry.request?.method;
+  const url = entry.request?.url;
+  if (!method || !url) return false;
+  return joinMessages(entry.messages) === `${method} ${url}`;
+}
 function formatLogEntry(entry, format = "default") {
-  const message = (entry.messages ?? []).map(stringifyMessage).join(" ").replace(/\s+/g, " ").trim();
+  const message = joinMessages(entry.messages);
   if (format === "short") return message;
   const level = entry.level ?? "unknown";
   const coloredLevel = colorize8(LEVEL_COLORS[level.toLowerCase()] ?? "white", level.toUpperCase());
@@ -3425,12 +3475,16 @@ function formatLogEntry(entry, format = "default") {
     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}`;
+  if (format === "request" && isRequestLogEntry(entry)) {
+    return `[${entry.timestamp ?? UNKNOWN_TIME}]${requestStr}`;
+  }
+  return `[${entry.timestamp ?? UNKNOWN_TIME}]${requestStr} [${coloredLevel}]${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.entryType) search.set("entry_type", params.entryType);
   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);
@@ -3473,11 +3527,18 @@ async function queryLogs(projectUuid, storeHash, accessToken, apiHost, params) {
 
 // src/cli/lib/domains.ts
 var domainStatusSchema = z15.enum(["pending", "verified", "failed", "unknown"]);
+var pointingRecordsSchema = z15.object({
+  a_record_value: z15.string().nullish(),
+  cname_record_value: z15.string().nullish()
+});
 var domainSchema = z15.object({
   domain: z15.string(),
   project_uuid: z15.string(),
   verification_status: domainStatusSchema
 });
+var createdDomainSchema = domainSchema.extend({
+  pointing_records: pointingRecordsSchema.nullish()
+});
 var ownershipVerificationSchema = z15.object({
   type: z15.string(),
   name: z15.string(),
@@ -3518,6 +3579,9 @@ function parseBoundProjectUuid(body) {
 var domainResponseSchema = z15.object({
   data: domainSchema
 });
+var createdDomainResponseSchema = z15.object({
+  data: createdDomainSchema
+});
 var domainListResponseSchema = z15.object({
   data: z15.array(domainSchema)
 });
@@ -3586,7 +3650,7 @@ async function createDomain(domain, projectUuid, storeHash, accessToken, apiHost
   });
   await assertDomainResponse(response, "Failed to add domain");
   const result = await response.json();
-  return domainResponseSchema.parse(result).data;
+  return createdDomainResponseSchema.parse(result).data;
 }
 async function getDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
   const response = await fetch(domainUrl(storeHash, projectUuid, domain, apiHost), {
@@ -3657,6 +3721,7 @@ async function transferDomain(domain, projectUuid, newProjectUuid, storeHash, ac
 var WAIT_INTERVAL_MS = 5e3;
 var WAIT_TIMEOUT_MS = 5 * 60 * 1e3;
 var DOMAIN_STATUS_FILTERS = ["pending", "verified", "failed"];
+var RECORD_TYPE_WIDTH = "CNAME".length;
 var STATUS_COLORS = {
   pending: "yellow",
   verified: "green",
@@ -3690,20 +3755,20 @@ async function resolveDestinationProject(domain, context, toProjectUuid) {
     return toProjectUuid;
   }
   consola.start("Fetching projects...");
-  const projects = await fetchProjects(context.storeHash, context.accessToken, context.apiHost);
+  const projects2 = await fetchProjects(context.storeHash, context.accessToken, context.apiHost);
   consola.success("Projects fetched.");
-  const destinations = projects.filter((project2) => project2.uuid !== context.projectUuid);
+  const destinations = projects2.filter((project) => project.uuid !== context.projectUuid);
   if (destinations.length === 0) {
     throw new UserActionableError(
-      "No other projects to transfer to. Create another project with `catalyst project create` first."
+      "No other projects to transfer to. Create another project with `catalyst projects create` first."
     );
   }
   return select6({
     message: `Select the project to transfer ${domain} to (Press <enter> to select).`,
-    choices: destinations.map((project2) => ({
-      name: project2.name,
-      value: project2.uuid,
-      description: project2.uuid
+    choices: destinations.map((project) => ({
+      name: project.name,
+      value: project.uuid,
+      description: project.uuid
     }))
   });
 }
@@ -3713,6 +3778,19 @@ function formatDomainStatus(status) {
 function formatDomain(domain) {
   return `${domain.domain} ${formatDomainStatus(domain.verification_status)}`;
 }
+function formatPointingRecords(records) {
+  const rows = [];
+  if (records?.a_record_value) {
+    rows.push(`${"A".padEnd(RECORD_TYPE_WIDTH)}  ${records.a_record_value}`);
+  }
+  if (records?.cname_record_value) {
+    rows.push(`${"CNAME".padEnd(RECORD_TYPE_WIDTH)}  ${records.cname_record_value}`);
+  }
+  if (rows.length === 0) {
+    return null;
+  }
+  return rows.map((row) => `  ${row}`).join("\n");
+}
 function formatOwnershipVerification(record) {
   const lines = [
     "Add this DNS record to verify ownership:",
@@ -3744,6 +3822,10 @@ async function waitForDomainVerification({
 var add = new Command7("add").configureHelp({ showGlobalOptions: true }).description("Add a custom domain to the current Native Hosting project.").argument("<domain>", "Custom domain to add.").addHelpText(
   "after",
   `
+The DNS records that point the domain at this project are printed once the domain
+is added. They are returned only by this command, so save them: publish the CNAME
+for a subdomain, or the A record for an apex domain.
+
 Examples:
   $ catalyst domains add www.example.com
 
@@ -3753,9 +3835,9 @@ Examples:
   const context = resolveDomainCommandContext(options);
   await getTelemetry().identify(context.storeHash);
   consola.start(`Adding domain ${domain}...`);
-  let result;
+  let created;
   try {
-    result = await createDomain(
+    created = await createDomain(
       domain,
       context.projectUuid,
       context.storeHash,
@@ -3782,12 +3864,26 @@ Examples:
     }
     throw error;
   }
-  consola.success(`Domain ${result.domain} added.`);
+  consola.success(`Domain ${created.domain} added.`);
+  const records = formatPointingRecords(created.pointing_records);
+  let result = created;
   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));
+  if (records) {
+    consola.info(`Point ${created.domain} at this project with one of these DNS records:`);
+    consola.log(records);
+    consola.info(
+      "Use the CNAME for a subdomain, or the A record for an apex domain. Save them now \u2014 only `domains add` returns them."
+    );
+  }
+  if (result.verification_status === "pending") {
+    consola.info(
+      `Run \`catalyst domains status ${result.domain}\` to check verification progress.`
+    );
+  }
   process.exit(0);
 });
 var list = new Command7("list").configureHelp({ showGlobalOptions: true }).description("List custom domains for the current Native Hosting project.").addHelpText(
@@ -3927,14 +4023,14 @@ Examples:
   );
   if (!owned) {
     consola.start(`Locating the project that owns ${domain}...`);
-    const projects = await fetchProjects(context.storeHash, context.accessToken, context.apiHost);
-    const candidates = projects.filter((project2) => project2.uuid !== context.projectUuid);
+    const projects2 = await fetchProjects(context.storeHash, context.accessToken, context.apiHost);
+    const candidates = projects2.filter((project) => project.uuid !== context.projectUuid);
     const matches = await Promise.all(
-      candidates.map(async (project2) => ({
-        project: project2,
+      candidates.map(async (project) => ({
+        project,
         found: await findDomain(
           domain,
-          project2.uuid,
+          project.uuid,
           context.storeHash,
           context.accessToken,
           context.apiHost
@@ -4029,7 +4125,7 @@ Examples:
   consola.success(`Domain ${current.domain} removed.`);
   process.exit(0);
 });
-var domains = new Command7("domains").configureHelp({ showGlobalOptions: true }).description("Manage custom domains for the current Native Hosting project.").addCommand(add).addCommand(list).addCommand(showStatus).addCommand(claim).addCommand(transfer).addCommand(remove);
+var domains = new Command7("domains").alias("domain").configureHelp({ showGlobalOptions: true }).description("Manage custom domains for the current Native Hosting project.").addCommand(add).addCommand(list).addCommand(showStatus).addCommand(claim).addCommand(transfer).addCommand(remove);
 
 // src/cli/commands/env.ts
 import { Command as Command8 } from "commander";
@@ -4141,8 +4237,19 @@ var StreamError = class extends Error {
   }
 };
 var formatMessages = (messages) => messages.map((m) => typeof m === "string" ? m : JSON.stringify(m)).join(" ");
+var formatRequestLine = (event, entry) => {
+  const { request } = event;
+  const msg = entry ? formatMessages(entry.messages) : "";
+  const msgPart = msg ? ` ${msg}` : "";
+  const level = msg ? entry?.level.toUpperCase() : void 0;
+  const levelPart = level ? ` [${colorize10(LEVEL_COLORS2[level] ?? "white", level)}]` : "";
+  return `[${entry?.timestamp ?? event.timestamp}] ${request.method} ${request.url} (${request.status_code})${levelPart}${msgPart}`;
+};
 var formatLogEvent = (event, format) => {
-  const { request, logs: logEntries, exceptions } = event;
+  const { logs: logEntries, exceptions } = event;
+  if (format === "request" && logEntries.length === 0) {
+    consola.log(formatRequestLine(event));
+  }
   logEntries.forEach((entry) => {
     const msg = formatMessages(entry.messages);
     const level = entry.level.toUpperCase();
@@ -4152,9 +4259,7 @@ var formatLogEvent = (event, format) => {
         consola.log(msg);
         break;
       case "request":
-        consola.log(
-          `[${entry.timestamp}] [${coloredLevel}] ${request.method} ${request.url} (${request.status_code}) ${msg}`
-        );
+        consola.log(formatRequestLine(event, entry));
         break;
       default:
         consola.log(`[${entry.timestamp}] [${coloredLevel}] ${msg}`);
@@ -4290,6 +4395,19 @@ var tailLogs = async (projectUuid, storeHash, accessToken, apiHost, format, conn
 var tail = new Command9("tail").configureHelp({ showGlobalOptions: true }).description("Tail live logs from your deployed application.").addHelpText(
   "after",
   `
+Formats:
+  default  One line per log message: timestamp, level, and message.
+  short    Message text only.
+  request  One line per log message: timestamp, request method, URL, status
+           code, level, and message. Requests that logged no messages are
+           printed too, without the level and message.
+  pretty   Indented JSON of the whole event.
+  json     Raw JSON, one event per line (useful for piping to other tools).
+
+The \`default\` and \`short\` formats only print requests that produced a log
+message. Use \`--format request\` (or \`json\`/\`pretty\`) to see every request,
+including ones with no message body.
+
 Examples:
   $ catalyst logs tail
 
@@ -4349,6 +4467,8 @@ function printPaginationHints(pagination, start2, end, options) {
     ...options.urlLike ? [`--url-like ${quoteArg(options.urlLike)}`] : [],
     ...options.levelMin ? [`--level-min ${options.levelMin}`] : [],
     ...options.limit != null ? [`--limit ${options.limit}`] : [],
+    // The entry_type filter derives from --format (default/short request only
+    // application logs), so echoing --format is enough to reproduce it.
     ...options.format !== "default" ? [`--format ${options.format}`] : []
   ];
   const command = `${invocationPrefix()} logs query ${baseFlags.join(" ")}`;
@@ -4375,6 +4495,10 @@ entries with \`--before\`. Cursors are only valid with the same window and
 filters they came from. With \`--format json\`, the pagination cursors are
 emitted as a final \`{"meta": ...}\` line after the entries.
 
+The \`default\` and \`short\` formats show only application log output,
+excluding Cloudflare's auto-generated per-request rows. Use
+\`--format request\` (or \`json\`/\`pretty\`) to include them.
+
 Examples:
   # Last hour of logs
   $ catalyst logs query --since 1h
@@ -4432,9 +4556,11 @@ Examples:
     await getTelemetry().identify(storeHash);
     const projectUuid = resolveProjectUuid(options);
     const { start: start2, end } = resolveTimeWindow(options);
+    const hideRequestRows = options.format === "default" || options.format === "short";
     const result = await queryLogs(projectUuid, storeHash, accessToken, apiHost, {
       start: start2,
       end,
+      entryType: hideRequestRows ? "log" : void 0,
       method: options.method,
       statusCode: options.statusCode,
       urlLike: options.urlLike,
@@ -4466,9 +4592,12 @@ Examples:
       return;
     }
     const lineFormat = options.format;
-    ordered.forEach((entry) => consola.log(formatLogEntry(entry, lineFormat)));
+    const visible = hideRequestRows ? ordered.filter((entry) => !isRequestLogEntry(entry)) : ordered;
+    const hiddenCount = ordered.length - visible.length;
+    visible.forEach((entry) => consola.log(formatLogEntry(entry, lineFormat)));
+    const shownPart = `${visible.length} ${visible.length === 1 ? "entry" : "entries"} shown`;
     consola.info(
-      `${entries.length} ${entries.length === 1 ? "entry" : "entries"} shown (oldest first, times in UTC).`
+      hiddenCount > 0 ? `${shownPart}, ${hiddenCount} request ${hiddenCount === 1 ? "row" : "rows"} hidden (oldest first, times in UTC). Use --format request to see request rows.` : `${shownPart} (oldest first, times in UTC).`
     );
     printPaginationHints(result.meta?.cursor_pagination, start2, end, options);
   } catch (error) {
@@ -4476,9 +4605,9 @@ Examples:
     process.exit(1);
   }
 });
-var logs = new Command9("logs").configureHelp({ showGlobalOptions: true }).description("View logs from your deployed application.").addCommand(tail, { isDefault: true }).addCommand(query);
+var logs = new Command9("logs").alias("log").configureHelp({ showGlobalOptions: true }).description("View logs from your deployed application.").addCommand(tail, { isDefault: true }).addCommand(query);
 
-// src/cli/commands/project.ts
+// src/cli/commands/projects.ts
 import { confirm as confirm5, input as input5, select as select7 } from "@inquirer/prompts";
 import { Command as Command10 } from "commander";
 import { colorize as colorize11 } from "consola/utils";
@@ -4507,22 +4636,22 @@ var list3 = new Command10("list").configureHelp({ showGlobalOptions: true }).des
   "after",
   `
 Example:
-  $ catalyst project list`
+  $ catalyst projects list`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).action(async (options) => {
   const config2 = getProjectConfig();
   const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
   consola.start("Fetching projects...");
-  const projects = await fetchProjects(storeHash, accessToken, apiHost);
+  const storeProjects = await fetchProjects(storeHash, accessToken, apiHost);
   consola.success("Projects fetched.");
-  if (projects.length === 0) {
+  if (storeProjects.length === 0) {
     consola.info("No projects found.");
     process.exit(0);
     return;
   }
   const linkedProjectUuid = config2.get("projectUuid");
-  const projectList = projects.map((p) => {
+  const projectList = storeProjects.map((p) => {
     const marker = p.uuid === linkedProjectUuid ? ` ${colorize11("green", "[linked]")}` : "";
     const hostnames = p.deployment_hostnames.length === 0 ? ["  (not deployed)"] : p.deployment_hostnames.map(
       (hostname) => `  ${colorize11("blue", `https://${hostname}`)}`
@@ -4538,7 +4667,7 @@ var create3 = new Command10("create").configureHelp({ showGlobalOptions: true })
   "after",
   `
 Example:
-  $ catalyst project create`
+  $ catalyst projects create`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).action(async (options) => {
   const config2 = getProjectConfig();
   const apiHost = resolveApiHost(options, config2);
@@ -4558,7 +4687,7 @@ Example:
     } catch (error) {
       if (error instanceof LoginAbortedError) {
         consola.info(
-          "Login aborted. Re-run `catalyst project create` when you have your credentials ready."
+          "Login aborted. Re-run `catalyst projects create` when you have your credentials ready."
         );
         process.exit(0);
         return;
@@ -4584,10 +4713,10 @@ var link2 = new Command10("link").configureHelp({ showGlobalOptions: true }).des
   `
 Examples:
   # Link interactively (prompts to select or create)
-  $ catalyst project link
+  $ catalyst projects link
 
   # Link using a project UUID directly
-  $ catalyst project link --project-uuid <UUID>`
+  $ catalyst projects link --project-uuid <UUID>`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).action(async (options) => {
   const config2 = getProjectConfig();
   const apiHost = resolveApiHost(options, config2);
@@ -4617,7 +4746,7 @@ Examples:
   } catch (error) {
     if (error instanceof NoLinkedProjectError) {
       consola.info(
-        "When you're ready to create a project, run `catalyst project create` or re-run `catalyst project link`."
+        "When you're ready to create a project, run `catalyst projects create` or re-run `catalyst projects link`."
       );
       process.exit(0);
       throw error;
@@ -4635,13 +4764,13 @@ var del = new Command10("delete").configureHelp({ showGlobalOptions: true }).des
   `
 Examples:
   # Select a project to delete interactively
-  $ catalyst project delete
+  $ catalyst projects delete
 
   # Delete a specific project (still prompts for confirmation)
-  $ catalyst project delete --project-uuid <UUID>
+  $ catalyst projects delete --project-uuid <UUID>
 
   # Skip the confirmation prompt
-  $ catalyst project delete --project-uuid <UUID> --force`
+  $ catalyst projects delete --project-uuid <UUID> --force`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--force", "Skip the confirmation prompt before deleting.").action(async (options) => {
   const config2 = getProjectConfig();
   const apiHost = resolveApiHost(options, config2);
@@ -4651,9 +4780,9 @@ Examples:
   let targetName;
   if (!targetUuid) {
     consola.start("Fetching projects...");
-    const projects = await fetchProjects(storeHash, accessToken, apiHost);
+    const storeProjects = await fetchProjects(storeHash, accessToken, apiHost);
     consola.success("Projects fetched.");
-    if (projects.length === 0) {
+    if (storeProjects.length === 0) {
       consola.info("No projects found.");
       process.exit(0);
       return;
@@ -4662,7 +4791,7 @@ Examples:
     const selected = await select7({
       message: "Select a project to delete (Press <enter> to select).",
       choices: [
-        ...projects.map((p) => ({
+        ...storeProjects.map((p) => ({
           name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize11("green", "[linked]")}` : p.name,
           value: p.uuid,
           description: p.uuid
@@ -4675,7 +4804,7 @@ Examples:
       process.exit(0);
       return;
     }
-    const matched = projects.find((p) => p.uuid === selected);
+    const matched = storeProjects.find((p) => p.uuid === selected);
     if (!matched) {
       throw new Error(`Selected project ${String(selected)} not found in fetched list.`);
     }
@@ -4703,13 +4832,13 @@ Examples:
   }
   process.exit(0);
 });
-var project = new Command10("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure project.").addCommand(create3).addCommand(list3).addCommand(link2).addCommand(del);
+var projects = new Command10("projects").alias("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure projects.").addCommand(create3).addCommand(list3).addCommand(link2).addCommand(del);
 
 // src/cli/commands/start.ts
 import { Command as Command11 } from "commander";
 import { execa as execa3 } from "execa";
 import { existsSync as existsSync6, lstatSync, symlinkSync } from "fs";
-import { join as join13, relative } from "path";
+import { join as join14, relative } from "path";
 var start = new Command11("start").configureHelp({ showGlobalOptions: true }).description(
   "Start a local preview of your Catalyst storefront using the OpenNext Cloudflare adapter."
 ).addHelpText(
@@ -4727,11 +4856,11 @@ Example:
     });
     return;
   }
-  const envLocal = join13(process.cwd(), ".env.local");
-  const devVars = join13(process.cwd(), ".bigcommerce", ".dev.vars");
+  const envLocal = join14(process.cwd(), ".env.local");
+  const devVars = join14(process.cwd(), ".bigcommerce", ".dev.vars");
   if (existsSync6(envLocal)) {
     if (!existsSync6(devVars)) {
-      const target = relative(join13(process.cwd(), ".bigcommerce"), envLocal);
+      const target = relative(join14(process.cwd(), ".bigcommerce"), envLocal);
       symlinkSync(target, devVars);
       consola.success("Symlinked .bigcommerce/.dev.vars \u2192 .env.local");
     } else if (!lstatSync(devVars).isSymbolicLink()) {
@@ -4751,7 +4880,7 @@ Example:
       "opennextjs-cloudflare",
       "preview",
       "--config",
-      join13(".bigcommerce", "wrangler.jsonc")
+      join14(".bigcommerce", "wrangler.jsonc")
     ],
     {
       stdio: "inherit",
@@ -4810,7 +4939,7 @@ import { Command as Command13, Option as Option10 } from "@commander-js/extra-ty
 import { confirm as confirm6 } from "@inquirer/prompts";
 import { execa as execa4 } from "execa";
 import {
-  access as access2,
+  access as access3,
   copyFile as copyFile2,
   cp as cp2,
   mkdir,
@@ -4822,7 +4951,8 @@ import {
   writeFile as writeFile2
 } from "fs/promises";
 import { homedir, tmpdir } from "os";
-import { dirname as dirname5, join as join14, relative as relative2 } from "path";
+import { dirname as dirname5, join as join15, relative as relative2 } from "path";
+import { minVersion, satisfies, lt as semverLt, validRange, valid as validSemver2 } from "semver";
 import yoctoSpinner4 from "yocto-spinner";
 import { z as z17 } from "zod";
 var CorePackageJson = z17.object({
@@ -4830,6 +4960,20 @@ var CorePackageJson = z17.object({
   version: z17.string(),
   catalyst: z17.object({ version: z17.string(), ref: z17.string() }).optional()
 });
+var DEP_FIELDS2 = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies"
+];
+var DepsPackageJson = z17.looseObject({
+  dependencies: z17.record(z17.string(), z17.string()).optional(),
+  devDependencies: z17.record(z17.string(), z17.string()).optional(),
+  optionalDependencies: z17.record(z17.string(), z17.string()).optional(),
+  peerDependencies: z17.record(z17.string(), z17.string()).optional()
+});
+var WorkspacePackageJson = z17.object({ name: z17.string(), version: z17.string() });
+var CATALYST_CLI_PACKAGE = "@bigcommerce/catalyst";
 var DEFAULT_REPOSITORY = "bigcommerce/catalyst";
 var MOVING_TAGS = /* @__PURE__ */ new Set(["latest", "canary", "alpha"]);
 var KNOWN_FAMILIES = /* @__PURE__ */ new Set([
@@ -4838,14 +4982,14 @@ var KNOWN_FAMILIES = /* @__PURE__ */ new Set([
   "@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);
+var CACHE_DIR = join15(homedir(), ".cache", "catalyst-cli", "cores");
+var pathExists = (p) => access3(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 entry.isDirectory() ? listFiles(join15(dir, entry.name), rel) : Promise.resolve([rel]);
     })
   );
   return nested.flat();
@@ -4861,7 +5005,7 @@ 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)))
+    baseFiles.map((rel) => filesEqual(join15(baseDir, rel), join15(destDir, rel)))
   );
   return matches.filter(Boolean).length / baseFiles.length;
 }
@@ -4880,10 +5024,79 @@ function parseRef(ref) {
   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 raw = await readFile2(join15(coreDir, "package.json"), "utf-8");
   const pkg = CorePackageJson.parse(JSON.parse(raw));
   return pkg.catalyst?.version ?? pkg.version;
 }
+var readDepSpecifiers = (raw) => {
+  let parsed;
+  try {
+    parsed = DepsPackageJson.parse(JSON.parse(raw));
+  } catch {
+    return {};
+  }
+  return Object.fromEntries(DEP_FIELDS2.flatMap((field) => Object.entries(parsed[field] ?? {})));
+};
+var escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var rewriteWorkspaceSpecifier = (raw, name, version2) => raw.replace(
+  new RegExp(`("${escapeRegExp(name)}"\\s*:\\s*)"workspace:[^"]*"`, "g"),
+  (_match, key) => `${key}"^${version2}"`
+);
+async function normalizeWorkspaceDeps(ourPkgRaw, baseDir, theirsDir, baseVersions, targetVersions) {
+  const basePath = join15(baseDir, "package.json");
+  const theirsPath = join15(theirsDir, "package.json");
+  const [originalBase, originalTheirs] = await Promise.all([
+    readFile2(basePath, "utf-8").catch(() => null),
+    readFile2(theirsPath, "utf-8").catch(() => null)
+  ]);
+  if (originalBase === null || originalTheirs === null) return { workspace: [], bumped: [] };
+  const ourSpecifiers = readDepSpecifiers(ourPkgRaw);
+  const names = new Set(
+    [
+      ...Object.entries(readDepSpecifiers(originalBase)),
+      ...Object.entries(readDepSpecifiers(originalTheirs))
+    ].filter(([, range]) => range?.startsWith("workspace:")).map(([name]) => name)
+  );
+  const decisions = [...names].map((name) => ({
+    name,
+    ours: ourSpecifiers[name],
+    baseVersion: baseVersions[name],
+    targetVersion: targetVersions[name]
+  }));
+  const workspace = decisions.flatMap(
+    ({ name, ours, targetVersion }) => ours?.startsWith("workspace:") && targetVersion !== void 0 ? [{ name, ours, version: targetVersion }] : []
+  );
+  const normalizable = decisions.filter(({ ours }) => !ours?.startsWith("workspace:"));
+  const baseRaw = normalizable.reduce(
+    (acc, { name, baseVersion }) => baseVersion === void 0 ? acc : rewriteWorkspaceSpecifier(acc, name, baseVersion),
+    originalBase
+  );
+  const theirsRaw = normalizable.reduce(
+    (acc, { name, targetVersion }) => targetVersion === void 0 ? acc : rewriteWorkspaceSpecifier(acc, name, targetVersion),
+    originalTheirs
+  );
+  const bumped = normalizable.filter(
+    ({ baseVersion, targetVersion }) => baseVersion !== void 0 && targetVersion !== void 0 && baseVersion !== targetVersion
+  ).map(({ name }) => name);
+  await Promise.all([
+    baseRaw === originalBase ? null : writeFile2(basePath, baseRaw),
+    theirsRaw === originalTheirs ? null : writeFile2(theirsPath, theirsRaw)
+  ]);
+  return { workspace, bumped };
+}
+var migrateWorkspaceDeps = (raw, findings) => findings.reduce((acc, { name, version: version2 }) => rewriteWorkspaceSpecifier(acc, name, version2), raw);
+async function findStaleCli(pkgRaw) {
+  const range = readDepSpecifiers(pkgRaw)[CATALYST_CLI_PACKAGE];
+  if (range === void 0 || !validRange(range)) return null;
+  const body = await fetch(`https://registry.npmjs.org/${CATALYST_CLI_PACKAGE}/latest`, {
+    // A hanging registry would otherwise stall the CLI indefinitely.
+    signal: AbortSignal.timeout(5e3)
+  }).then((res) => res.ok ? res.json() : null).catch(() => null);
+  const latest = z17.object({ version: z17.string() }).safeParse(body).data?.version;
+  if (latest === void 0 || !validSemver2(latest) || satisfies(latest, range)) return null;
+  const current = minVersion(range)?.version;
+  return current !== void 0 && semverLt(current, latest) ? { current, latest } : null;
+}
 async function mergeFile(oursPath, basePath, theirsPath) {
   const merged = await execa4(
     "git",
@@ -4907,9 +5120,9 @@ async function mergeFile(oursPath, basePath, theirsPath) {
   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);
+  const basePath = join15(baseDir, rel);
+  const theirsPath = join15(theirsDir, rel);
+  const oursPath = join15(catalystRoot, rel);
   if (await filesEqual(basePath, theirsPath)) return null;
   if (!await pathExists(oursPath)) {
     await copyInto(theirsPath, oursPath);
@@ -4925,8 +5138,8 @@ async function mergeModified(rel, baseDir, theirsDir, catalystRoot) {
   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);
+  const theirsPath = join15(theirsDir, rel);
+  const oursPath = join15(catalystRoot, rel);
   if (!await pathExists(oursPath)) {
     await copyInto(theirsPath, oursPath);
     return "added";
@@ -4937,8 +5150,8 @@ async function mergeAdded(rel, theirsDir, catalystRoot, emptyFile) {
   return hadConflict ? "conflicted" : "applied";
 }
 async function mergeDeleted(rel, baseDir, catalystRoot) {
-  const basePath = join14(baseDir, rel);
-  const oursPath = join14(catalystRoot, rel);
+  const basePath = join15(baseDir, rel);
+  const oursPath = join15(catalystRoot, rel);
   if (!await pathExists(oursPath)) return null;
   if (await filesEqual(oursPath, basePath)) {
     await rm2(oursPath, { force: true });
@@ -4984,15 +5197,15 @@ async function resolveStrategy(strategy) {
   return "per-file";
 }
 async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
-  const scratch = await mkdtemp(join14(tmpdir(), "catalyst-merge-"));
+  const scratch = await mkdtemp(join15(tmpdir(), "catalyst-merge-"));
   try {
     await execa4("git", ["init", "-q", scratch]);
     await execa4("git", ["config", "core.autocrlf", "false"], {
-      env: { ...process.env, GIT_DIR: join14(scratch, ".git") }
+      env: { ...process.env, GIT_DIR: join15(scratch, ".git") }
     });
     const env2 = {
       ...process.env,
-      GIT_DIR: join14(scratch, ".git"),
+      GIT_DIR: join15(scratch, ".git"),
       GIT_AUTHOR_NAME: "catalyst",
       GIT_AUTHOR_EMAIL: "catalyst@bigcommerce.com",
       GIT_COMMITTER_NAME: "catalyst",
@@ -5002,7 +5215,7 @@ async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
       const sideEnv = {
         ...env2,
         GIT_WORK_TREE: workTree,
-        GIT_INDEX_FILE: join14(scratch, `index.${tag}`)
+        GIT_INDEX_FILE: join15(scratch, `index.${tag}`)
       };
       await execa4("git", ["add", "-A"], { env: sideEnv });
       return (await execa4("git", ["write-tree"], { env: sideEnv })).stdout.trim();
@@ -5046,7 +5259,7 @@ async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
     const outEnv = {
       ...env2,
       GIT_WORK_TREE: catalystRoot,
-      GIT_INDEX_FILE: join14(scratch, "index.out")
+      GIT_INDEX_FILE: join15(scratch, "index.out")
     };
     await execa4("git", ["read-tree", mergedTree], { env: outEnv });
     await execa4("git", ["checkout-index", "-a", "-f"], { env: outEnv });
@@ -5065,7 +5278,7 @@ async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
       }
     }
     const deleted = changes.filter((change) => change.status === "D").map((change) => change.path);
-    await Promise.all(deleted.map((path) => rm2(join14(catalystRoot, path), { force: true })));
+    await Promise.all(deleted.map((path) => rm2(join15(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),
@@ -5108,9 +5321,9 @@ async function applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stam
     stillConflicted.map(async (rel) => {
       const repoPath = toRepoPath(rel);
       const [base, ours, theirs] = await Promise.all([
-        hashBlob(join14(baseDir, rel)),
+        hashBlob(join15(baseDir, rel)),
         headEntry(repoPath),
-        hashBlob(join14(theirsDir, rel))
+        hashBlob(join15(theirsDir, rel))
       ]);
       return [
         `0 ${NULL_OID}	${repoPath}`,
@@ -5133,10 +5346,10 @@ async function resolveProject2(cwd) {
   } catch {
     return null;
   }
-  const candidateDirs = [.../* @__PURE__ */ new Set([join14(gitRoot, "core"), gitRoot, join14(cwd, "core"), cwd])];
+  const candidateDirs = [.../* @__PURE__ */ new Set([join15(gitRoot, "core"), gitRoot, join15(cwd, "core"), cwd])];
   const parsed = (await Promise.all(
     candidateDirs.map(async (dir) => {
-      const pkgPath = join14(dir, "package.json");
+      const pkgPath = join15(dir, "package.json");
       const raw = await readFile2(pkgPath, "utf-8").catch(() => null);
       if (!raw) return null;
       let pkgJson;
@@ -5160,13 +5373,44 @@ async function resolveProject2(cwd) {
     pkg: chosen.pkg
   };
 }
+var readWorkspaceVersions = async (repoDir) => {
+  const packagesDir = join15(repoDir, "packages");
+  const entries = await readdir2(packagesDir, { withFileTypes: true }).catch(() => []);
+  const manifests = await Promise.all(
+    entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
+      const raw = await readFile2(join15(packagesDir, entry.name, "package.json"), "utf-8").catch(
+        () => null
+      );
+      if (raw === null) return null;
+      try {
+        return WorkspacePackageJson.parse(JSON.parse(raw));
+      } catch {
+        return null;
+      }
+    })
+  );
+  return Object.fromEntries(
+    manifests.filter((pkg) => pkg !== null).map(({ name, version: version2 }) => [name, version2])
+  );
+};
+var readCachedVersions = async (path) => {
+  const raw = await readFile2(path, "utf-8").catch(() => null);
+  if (raw === null) return null;
+  try {
+    return z17.record(z17.string(), z17.string()).parse(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+};
 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"))) {
+  const cachePath = join15(CACHE_DIR, cacheKey);
+  const versionsPath = `${cachePath}.versions.json`;
+  const cachedVersions = cacheable && await pathExists(join15(cachePath, "package.json")) ? await readCachedVersions(versionsPath) : null;
+  if (cachedVersions) {
     await cp2(cachePath, destDir, { recursive: true });
-    return;
+    return cachedVersions;
   }
   const url = `https://api.github.com/repos/${repository}/tarball/${encodeURIComponent(ref)}`;
   const headers = {
@@ -5186,22 +5430,24 @@ async function downloadCore(repository, ref, destDir, token) {
   await writeFile2(tarballPath, Buffer.from(await res.arrayBuffer()));
   await mkdir(rawDir, { recursive: true });
   await execa4("tar", ["-xzf", tarballPath, "-C", rawDir, "--strip-components=1"]);
-  const coreDir = join14(rawDir, "core");
+  const coreDir = join15(rawDir, "core");
   const sourceDir = await pathExists(coreDir) ? coreDir : rawDir;
+  const workspaceVersions = await readWorkspaceVersions(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(() => {
+    await cp2(destDir, cachePath, { recursive: true }).then(() => writeFile2(versionsPath, JSON.stringify(workspaceVersions))).catch(() => {
     });
   }
+  return workspaceVersions;
 }
-async function resolveBaseRef(project2, fromOption, assumeYes) {
-  if (project2.pkg.catalyst?.ref) return project2.pkg.catalyst.ref;
+async function resolveBaseRef(project, fromOption, assumeYes) {
+  if (project.pkg.catalyst?.ref) return project.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}`;
+  const family = project.pkg.name && KNOWN_FAMILIES.has(project.pkg.name) ? project.pkg.name : "@bigcommerce/catalyst-core";
+  const guess = `${family}@${project.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);
@@ -5211,7 +5457,25 @@ async function resolveBaseRef(project2, fromOption, assumeYes) {
   }
   return guess;
 }
-function printSummary(result, relDir, stampedPkg) {
+function printWorkspaceFindings(findings) {
+  if (findings.length === 0) return;
+  const pad = Math.max(...findings.map((finding) => finding.name.length));
+  const rows = findings.map((finding) => `  ${finding.name.padEnd(pad)}  ${finding.ours} \u2192 ^${finding.version}`).join("\n");
+  consola.warn(
+    `Catalyst dependencies still using the workspace protocol (${findings.length}):
+${rows}
+
+They resolve to your local packages/ copies, which \`catalyst upgrade\` does not update \u2014 so they never receive upgrades.`
+  );
+}
+function printSummary({
+  result,
+  relDir,
+  stampedPkg,
+  migratedDeps,
+  packageManager,
+  staleCli
+}) {
   const unresolved = result.conflicted.filter((f) => !(stampedPkg && f === "package.json"));
   const parts = [
     `${result.applied.length} updated`,
@@ -5221,18 +5485,31 @@ function printSummary(result, relDir, stampedPkg) {
   if (unresolved.length) parts.push(`${unresolved.length} with conflicts`);
   consola.log(`
 ${parts.join(", ")}`);
+  const pkgConflicted = unresolved.includes("package.json");
+  const depsChanged = migratedDeps > 0 || [...result.applied, ...result.added, ...result.conflicted].includes("package.json");
+  if (depsChanged && !pkgConflicted) {
+    consola.info(
+      `Dependencies changed \u2014 run \`${packageManager} install\` to update your lockfile.`
+    );
+  }
   if (unresolved.length) {
     const files = unresolved.map((f) => `  ${f}`).join("\n");
+    const install = depsChanged && pkgConflicted ? ` && ${packageManager} install` : "";
     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`
+Resolve them, then: git add ${relDir} && git commit${install}`
     );
   } else {
     consola.success("Staged all changes \u2014 review with `git diff --cached`, then commit.");
   }
+  if (staleCli) {
+    consola.info(
+      `Your Catalyst CLI is behind (${staleCli.current} \u2192 ${staleCli.latest}). Update it with \`${packageManager} add -D ${CATALYST_CLI_PACKAGE}@${staleCli.latest}\`.`
+    );
+  }
 }
 var upgrade = new Command13("upgrade").configureHelp({ showGlobalOptions: true }).aliases([
   "up",
@@ -5273,15 +5550,15 @@ Conflicts are written as standard <<<ours/===/theirs>>> markers \u2014 the upgra
 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) {
+  const project = await resolveProject2(process.cwd());
+  if (!project) {
     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);
+  const { gitRoot, catalystRoot, relDir, pkgPath } = project;
+  const baseRef = await resolveBaseRef(project, options.from, options.yes ?? false);
   if (!baseRef) process.exit(1);
   let basePackage;
   let upstreamRef;
@@ -5316,7 +5593,7 @@ to raise the GitHub API rate limit.`
       process.exit(1);
     }
   }
-  if (!project2.pkg.catalyst?.ref && !options.from && !options.dryRun) {
+  if (!project.pkg.catalyst?.ref && !options.from && !options.dryRun) {
     const { version: baseVersion } = parseRef(baseRef);
     const rawPkg = await readFile2(pkgPath, "utf-8");
     const parsedPkg = z17.record(z17.string(), z17.unknown()).parse(JSON.parse(rawPkg));
@@ -5327,15 +5604,18 @@ to raise the GitHub API rate limit.`
     consola.success(`Added catalyst.ref \u2192 ${baseRef}`);
   }
   const token = process.env.GITHUB_TOKEN;
-  const tmpDir = await mkdtemp(join14(tmpdir(), "catalyst-upgrade-"));
+  const tmpDir = await mkdtemp(join15(tmpdir(), "catalyst-upgrade-"));
   try {
-    const baseDir = join14(tmpDir, "base");
-    const theirsDir = join14(tmpDir, "theirs");
-    const emptyFile = join14(tmpDir, ".empty");
+    const baseDir = join15(tmpDir, "base");
+    const theirsDir = join15(tmpDir, "theirs");
+    const emptyFile = join15(tmpDir, ".empty");
     await writeFile2(emptyFile, "");
+    const staleCliCheck = findStaleCli(project.rawContent).catch(() => null);
     const downloadSpinner = yoctoSpinner4().start(`Downloading ${baseRef} and ${upstreamRef}...`);
+    let baseVersions;
+    let targetVersions;
     try {
-      await Promise.all([
+      [baseVersions, targetVersions] = await Promise.all([
         downloadCore(options.repository, baseRef, baseDir, token),
         downloadCore(options.repository, upstreamRef, theirsDir, token)
       ]);
@@ -5344,7 +5624,7 @@ to raise the GitHub API rate limit.`
       downloadSpinner.error("Download failed");
       throw err;
     }
-    if (!project2.pkg.catalyst?.ref && !options.from) {
+    if (!project.pkg.catalyst?.ref && !options.from) {
       const similarity = await computeBaseSimilarity(baseDir, catalystRoot);
       const pct = Math.round(similarity * 100);
       if (similarity < 0.5) {
@@ -5355,6 +5635,13 @@ to raise the GitHub API rate limit.`
     }
     const resolvedVersion = MOVING_TAGS.has(upstreamTagVersion) ? await readResolvedVersion(theirsDir) : upstreamTagVersion;
     const newRef = MOVING_TAGS.has(upstreamTagVersion) ? `${basePackage}@${resolvedVersion}` : upstreamRef;
+    const { workspace: workspaceDeps, bumped } = await normalizeWorkspaceDeps(
+      project.rawContent,
+      baseDir,
+      theirsDir,
+      baseVersions,
+      targetVersions
+    );
     if (options.dryRun) {
       const diffSpinner = yoctoSpinner4().start("Generating diff...");
       const diff = await execa4(
@@ -5374,6 +5661,7 @@ to raise the GitHub API rate limit.`
       diffSpinner.success(`Diff ready \u2014 ${fileCount} file(s) affected.`);
       consola.log("\nDiff preview (--dry-run, not applied):\n");
       consola.log(diff.stdout);
+      printWorkspaceFindings(workspaceDeps);
       return;
     }
     const strategy = await resolveStrategy(options.strategy);
@@ -5390,13 +5678,13 @@ to raise the GitHub API rate limit.`
       mergeSpinner.success("Merged cleanly.");
     }
     const patchedRaw = await readFile2(pkgPath, "utf-8");
-    let stampedPkg = false;
+    let stampedText = null;
     try {
       const patchedPkg = z17.record(z17.string(), z17.unknown()).parse(JSON.parse(patchedRaw));
       patchedPkg.catalyst = { version: resolvedVersion, ref: newRef };
-      await writeFile2(pkgPath, `${JSON.stringify(patchedPkg, null, 2)}
-`);
-      stampedPkg = true;
+      stampedText = `${JSON.stringify(patchedPkg, null, 2)}
+`;
+      await writeFile2(pkgPath, stampedText);
       consola.success(`catalyst.ref updated \u2192 ${newRef}`);
     } catch {
       const catalystReplacement = JSON.stringify(
@@ -5421,14 +5709,35 @@ to raise the GitHub API rate limit.`
         );
       }
     }
+    printWorkspaceFindings(workspaceDeps);
+    let migratedDeps = 0;
+    if (workspaceDeps.length) {
+      const accepted = stampedText !== null && (options.yes === true || Boolean(process.stdin.isTTY) && await confirm6({
+        message: "Replace them with the published versions?",
+        default: true
+      }).catch(() => false));
+      if (accepted && stampedText !== null) {
+        await writeFile2(pkgPath, migrateWorkspaceDeps(stampedText, workspaceDeps));
+        migratedDeps = workspaceDeps.length;
+        consola.success(
+          `Migrated ${migratedDeps} dependenc${migratedDeps === 1 ? "y" : "ies"} to published versions.`
+        );
+      } else {
+        consola.info(
+          "Keeping the workspace references. Switching abandons any local packages/ copy you've customized; otherwise apply the versions above in package.json and reinstall."
+        );
+      }
+    }
     try {
-      await applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stampedPkg);
+      await applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stampedText !== null);
     } 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 execa4("git", ["--version"]).then((r) => r.stdout.trim()).catch(() => "unknown");
+    const packageManager = await detectLockfileManager(gitRoot) ?? "pnpm";
+    const staleCli = await staleCliCheck;
     await getTelemetry().track("upgrade", {
       strategy,
       gitVersion,
@@ -5437,9 +5746,20 @@ to raise the GitHub API rate limit.`
       added: result.added.length,
       deleted: result.deleted.length,
       conflicts: result.conflicted.length,
-      hasConflicts: result.conflicted.length > 0
+      hasConflicts: result.conflicted.length > 0,
+      workspaceDepsFound: workspaceDeps.length,
+      workspaceDepsMigrated: migratedDeps,
+      catalystDepsBumped: bumped.length,
+      cliOutdated: staleCli !== null
+    });
+    printSummary({
+      result,
+      relDir,
+      stampedPkg: stampedText !== null,
+      migratedDeps,
+      packageManager,
+      staleCli
     });
-    printSummary(result, relDir, stampedPkg);
   } finally {
     await rm2(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 500 });
   }
@@ -5516,7 +5836,7 @@ consola.log(colorize13("cyanBright", `\u25E2 ${package_default.name} v${package_
 `));
 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 > process.env > .bigcommerce/project.json. `build` and `deploy` additionally load env files (--env-path, or an auto-loaded .env.local/.env) for the build.\n\nCATALYST_STORE_HASH falls back to BIGCOMMERCE_STORE_HASH if unset.\n\nRun `catalyst <command> --help` for details on a specific command."
-).configureHelp({ showGlobalOptions: true }).addCommand(version).addCommand(create2).addCommand(start).addCommand(build).addCommand(deploy).addCommand(domains).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(upgrade).addCommand(telemetry).addCommand(debug).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
+).configureHelp({ showGlobalOptions: true }).addCommand(version).addCommand(create2).addCommand(start).addCommand(build).addCommand(deploy).addCommand(domains).addCommand(logs).addCommand(projects).addCommand(env).addCommand(channels).addCommand(auth).addCommand(upgrade).addCommand(telemetry).addCommand(debug).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
 
 // src/cli/index.ts
 var handleFatalError = async (error) => {