LTRAC-908: feat(cli) - Handle CLI-API gateway errors gracefully

The channel init/eligibility/create calls go through the cxm CLI-API gateway
(--cli-api-origin), which only exists for staging and production. Against any
other environment (e.g. integration), or on a transient 5xx, the call failed
with a raw error.

Introduce a typed CliApiError thrown by the gateway helpers in channels.ts and a
shared reportCliApiError() that prints a clear, actionable message (likely cause
+ how to verify --api-host/--cli-api-origin) and exits non-zero instead of
crashing. `channel connect` catches it before writing, so an existing .env.local
is never clobbered; `catalyst create` catches it before cloning, so there's no
partial project.

Refs LTRAC-908
Co-Authored-By: Claude <noreply@anthropic.com>

Author: jorgemoya

packages/catalyst/src/cli/commands/channel.spec.ts

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import Conf from 'conf';
 import { http, HttpResponse } from 'msw';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { afterAll, afterEach, beforeAll, describe, expect, MockInstance, test, vi } from 'vitest';
 
@@ -427,4 +427,37 @@ describe('channel connect', () => {
     expect(config.get('accessToken')).toBe('mock-access-token');
     expect(mockIdentify).toHaveBeenCalledWith('mock-store-hash');
   });
+
+  test('surfaces a clear error and leaves .env.local untouched when channel init fails', async () => {
+    // Pre-existing env file that must NOT be clobbered on a gateway failure.
+    const envPath = join(tmpDir, '.env.local');
+
+    writeFileSync(envPath, 'EXISTING=keep\n');
+
+    server.use(
+      http.get(
+        initUrl,
+        () => new HttpResponse(null, { status: 500, statusText: 'Internal Server Error' }),
+      ),
+    );
+
+    await program.parseAsync([
+      'node',
+      'catalyst',
+      'channel',
+      'connect',
+      '--store-hash',
+      storeHash,
+      '--access-token',
+      accessToken,
+      '--channel-id',
+      '2',
+    ]);
+
+    expect(consola.error).toHaveBeenCalledWith(
+      expect.stringContaining('Could not fetch channel credentials from the Catalyst CLI API'),
+    );
+    expect(exitMock).toHaveBeenCalledWith(1);
+    expect(readFileSync(envPath, 'utf8')).toBe('EXISTING=keep\n');
+  });
 });

packages/catalyst/src/cli/commands/channel.ts

@@ -5,7 +5,8 @@ import { outputFileSync } from 'fs-extra/esm';
 import { join } from 'node:path';
 
 import { runChannelSiteUrlFlow } from '../lib/channel-site-flow';
-import { fetchAvailableChannels, getChannelInit } from '../lib/channels';
+import { type ChannelInit, fetchAvailableChannels, getChannelInit } from '../lib/channels';
+import { reportCliApiError } from '../lib/cli-api-errors';
 import { NoLinkedProjectError } from '../lib/commerce-hosting';
 import { parseEnvAssignment } from '../lib/env-config';
 import { consola } from '../lib/logger';
@@ -228,7 +229,19 @@ Examples:
       channelName = channels.find((c) => c.id === channelId)?.name;
     }
 
-    const initData = await getChannelInit(channelId, storeHash, accessToken, options.cliApiOrigin);
+    let initData: ChannelInit;
+
+    try {
+      initData = await getChannelInit(channelId, storeHash, accessToken, options.cliApiOrigin);
+    } catch (error) {
+      reportCliApiError(
+        error,
+        'Could not fetch channel credentials from the Catalyst CLI API',
+        'Your existing .env.local was left unchanged.',
+      );
+
+      return;
+    }
 
     const envVars: Record<string, string> = { ...initData.envVars };
 

packages/catalyst/src/cli/commands/create.spec.ts

@@ -4,6 +4,8 @@ import { join } from 'node:path';
 import { afterAll, afterEach, beforeAll, describe, expect, MockInstance, test, vi } from 'vitest';
 
 import { buildWorkspacePackages } from '../lib/build-workspace-packages';
+import { checkChannelEligibility } from '../lib/channels';
+import { CliApiError } from '../lib/cli-api-errors';
 import { cloneCatalyst } from '../lib/clone-catalyst';
 import { promptForCommerceHostingProject, setupCommerceHosting } from '../lib/commerce-hosting';
 import { installDependencies } from '../lib/install-dependencies';
@@ -50,6 +52,12 @@ vi.mock('../lib/install-dependencies', () => ({
 }));
 vi.mock('../lib/build-workspace-packages', () => ({ buildWorkspacePackages: vi.fn() }));
 vi.mock('../lib/write-env', () => ({ writeEnv: vi.fn() }));
+vi.mock('../lib/channels', () => ({
+  checkChannelEligibility: vi.fn(),
+  createChannel: vi.fn(),
+  fetchAvailableChannels: vi.fn(),
+  getChannelInit: vi.fn(),
+}));
 
 vi.mock('../lib/commerce-hosting', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../lib/commerce-hosting')>();
@@ -476,6 +484,32 @@ describe('failure handling', () => {
 
     expect(cloneCatalyst).not.toHaveBeenCalled();
   });
+
+  test('fails gracefully when a CLI-API channel call errors (no project cloned)', async () => {
+    vi.mocked(checkChannelEligibility).mockRejectedValueOnce(
+      new CliApiError('GET /channels/catalyst/eligibility failed: 500 Internal Server Error', 500),
+    );
+
+    await program.parseAsync([
+      'node',
+      'catalyst',
+      'create',
+      '--project-name',
+      uniqueProjectName(),
+      '--project-dir',
+      tmpDir,
+      '--store-hash',
+      storeHash,
+      '--access-token',
+      accessToken,
+    ]);
+
+    expect(consola.error).toHaveBeenCalledWith(
+      expect.stringContaining('Could not set up the BigCommerce channel'),
+    );
+    expect(exitMock).toHaveBeenCalledWith(1);
+    expect(cloneCatalyst).not.toHaveBeenCalled();
+  });
 });
 
 describe('--hosting commerce preconditions', () => {

packages/catalyst/src/cli/commands/create.ts

@@ -14,6 +14,7 @@ import {
   fetchAvailableChannels,
   getChannelInit,
 } from '../lib/channels';
+import { reportCliApiError } from '../lib/cli-api-errors';
 import { cloneCatalyst } from '../lib/clone-catalyst';
 import { promptForCommerceHostingProject, setupCommerceHosting } from '../lib/commerce-hosting';
 import { installDependencies } from '../lib/install-dependencies';
@@ -368,61 +369,69 @@ Examples:
     }
 
     // Resolve channel only when we have creds and are missing channel info.
-    if (storeHash && accessToken && (!channelId || !storefrontToken)) {
-      const apiHost = `api.${options.bigcommerceHostname}`;
-      const cliApiOrigin = options.cliApiOrigin;
-
-      if (channelId && !storefrontToken) {
-        const initData = await getChannelInit(channelId, storeHash, accessToken, cliApiOrigin);
-
-        envVars = { ...initData.envVars };
-        storefrontToken = initData.storefrontToken;
-      } else if (!channelId) {
-        const eligibility = await checkChannelEligibility(storeHash, accessToken, cliApiOrigin);
-
-        if (!eligibility.eligible) {
-          consola.warn(eligibility.message);
-        }
-
-        let shouldCreateChannel;
-
-        if (eligibility.eligible) {
-          shouldCreateChannel = await select({
-            message: 'Would you like to create a new channel?',
-            choices: [
-              { name: 'Yes', value: true },
-              { name: 'No', value: false },
-            ],
-          });
-        }
-
-        if (shouldCreateChannel) {
-          const channelData = await handleChannelCreation(
-            storeHash,
-            accessToken,
-            apiHost,
-            cliApiOrigin,
-          );
-
-          channelId = channelData.channelId;
-          storefrontToken = channelData.storefrontToken;
-          envVars = { ...channelData.envVars };
-
-          consola.success('Channel created successfully.');
-          consola.warn(
-            'A preview storefront has been deployed in your BigCommerce control panel. This preview may look different from your local environment as it may be running different code. Additionally, it may take a few minutes for the channel storefront to be accessible.',
-          );
-        }
-
-        if (!shouldCreateChannel) {
-          channelId = await handleChannelSelection(storeHash, accessToken, apiHost);
+    // CLI-API (cxm gateway) failures here are surfaced cleanly rather than
+    // crashing — and this runs before any cloning, so there's no partial project.
+    try {
+      if (storeHash && accessToken && (!channelId || !storefrontToken)) {
+        const apiHost = `api.${options.bigcommerceHostname}`;
+        const cliApiOrigin = options.cliApiOrigin;
 
+        if (channelId && !storefrontToken) {
           const initData = await getChannelInit(channelId, storeHash, accessToken, cliApiOrigin);
 
           envVars = { ...initData.envVars };
           storefrontToken = initData.storefrontToken;
+        } else if (!channelId) {
+          const eligibility = await checkChannelEligibility(storeHash, accessToken, cliApiOrigin);
+
+          if (!eligibility.eligible) {
+            consola.warn(eligibility.message);
+          }
+
+          let shouldCreateChannel;
+
+          if (eligibility.eligible) {
+            shouldCreateChannel = await select({
+              message: 'Would you like to create a new channel?',
+              choices: [
+                { name: 'Yes', value: true },
+                { name: 'No', value: false },
+              ],
+            });
+          }
+
+          if (shouldCreateChannel) {
+            const channelData = await handleChannelCreation(
+              storeHash,
+              accessToken,
+              apiHost,
+              cliApiOrigin,
+            );
+
+            channelId = channelData.channelId;
+            storefrontToken = channelData.storefrontToken;
+            envVars = { ...channelData.envVars };
+
+            consola.success('Channel created successfully.');
+            consola.warn(
+              'A preview storefront has been deployed in your BigCommerce control panel. This preview may look different from your local environment as it may be running different code. Additionally, it may take a few minutes for the channel storefront to be accessible.',
+            );
+          }
+
+          if (!shouldCreateChannel) {
+            channelId = await handleChannelSelection(storeHash, accessToken, apiHost);
+
+            const initData = await getChannelInit(channelId, storeHash, accessToken, cliApiOrigin);
+
+            envVars = { ...initData.envVars };
+            storefrontToken = initData.storefrontToken;
+          }
         }
       }
+    } catch (error) {
+      reportCliApiError(error, 'Could not set up the BigCommerce channel');
+
+      return;
     }
 
     if (options.env) {

packages/catalyst/src/cli/lib/channels.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
 import { assertAuthorized } from './auth-errors';
+import { CliApiError } from './cli-api-errors';
 import { getTelemetry } from './telemetry';
 
 // `origin` is the CLI-API gateway (configured via `--cli-api-origin`, default
@@ -84,8 +85,9 @@ export async function getChannelInit(
   });
 
   if (!response.ok) {
-    throw new Error(
+    throw new CliApiError(
       `GET /channels/${channelId}/init failed: ${response.status} ${response.statusText}`,
+      response.status,
     );
   }
 
@@ -110,8 +112,9 @@ export async function checkChannelEligibility(
   });
 
   if (!response.ok) {
-    throw new Error(
+    throw new CliApiError(
       `GET /channels/catalyst/eligibility failed: ${response.status} ${response.statusText}`,
+      response.status,
     );
   }
 
@@ -147,7 +150,10 @@ export async function createChannel(
   });
 
   if (!response.ok) {
-    throw new Error(`POST /channels/catalyst failed: ${response.status} ${response.statusText}`);
+    throw new CliApiError(
+      `POST /channels/catalyst failed: ${response.status} ${response.statusText}`,
+      response.status,
+    );
   }
 
   const { data } = createChannelResponseSchema.parse(await response.json());

packages/catalyst/src/cli/lib/cli-api-errors.spec.ts

@@ -0,0 +1,53 @@
+import { afterAll, afterEach, beforeAll, describe, expect, MockInstance, test, vi } from 'vitest';
+
+import { CLI_API_ERROR_HINT, CliApiError, reportCliApiError } from './cli-api-errors';
+import { consola } from './logger';
+
+let exitMock: MockInstance;
+
+beforeAll(() => {
+  consola.mockTypes(() => vi.fn());
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  exitMock = vi.spyOn(process, 'exit').mockImplementation(() => null as never);
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+afterAll(() => {
+  vi.restoreAllMocks();
+  exitMock.mockRestore();
+});
+
+describe('CliApiError', () => {
+  test('is an Error carrying the message and status', () => {
+    const error = new CliApiError('boom', 500);
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('CliApiError');
+    expect(error.message).toBe('boom');
+    expect(error.status).toBe(500);
+  });
+});
+
+describe('reportCliApiError', () => {
+  test('logs the context + hint and exits non-zero for a CliApiError', () => {
+    reportCliApiError(new CliApiError('GET ... failed: 500', 500), 'Could not do the thing');
+
+    expect(consola.error).toHaveBeenCalledWith('Could not do the thing: GET ... failed: 500');
+    expect(consola.info).toHaveBeenCalledWith(CLI_API_ERROR_HINT);
+    expect(exitMock).toHaveBeenCalledWith(1);
+  });
+
+  test('includes the extra info line when provided', () => {
+    reportCliApiError(new CliApiError('nope'), 'ctx', 'left unchanged.');
+
+    expect(consola.info).toHaveBeenCalledWith('left unchanged.');
+  });
+
+  test('rethrows non-CliApiError errors untouched and does not exit', () => {
+    expect(() => reportCliApiError(new Error('unrelated'), 'ctx')).toThrow('unrelated');
+    expect(exitMock).not.toHaveBeenCalled();
+  });
+});

packages/catalyst/src/cli/lib/cli-api-errors.ts

@@ -0,0 +1,42 @@
+import { consola } from './logger';
+
+// Thrown by the cxm "CLI-API" gateway helpers (getChannelInit,
+// checkChannelEligibility, createChannel) when the gateway returns a non-2xx.
+// Typed distinctly so commands can fail gracefully instead of surfacing a raw
+// error, while unrelated failures keep propagating.
+export class CliApiError extends Error {
+  status?: number;
+
+  constructor(message: string, status?: number) {
+    super(message);
+    this.name = 'CliApiError';
+    this.status = status;
+  }
+}
+
+// Shared guidance shown when a CLI-API call fails. The gateway only exists in
+// staging (cxm-stg) and production (cxm-prd), so a store on another environment
+// (e.g. integration) has no gateway to answer the request.
+export const CLI_API_ERROR_HINT =
+  "This usually means the store's environment has no Catalyst CLI API gateway " +
+  '(only staging and production do), or a transient gateway error. ' +
+  'Verify --api-host and --cli-api-origin, then try again.';
+
+// Handle a caught error from a CLI-API call: when it's a CliApiError, print a
+// clear, actionable message (plus any command-specific note) and exit non-zero,
+// leaving the working tree untouched. Anything else is rethrown so unrelated
+// failures aren't swallowed.
+export function reportCliApiError(error: unknown, context: string, extraInfo?: string): void {
+  if (!(error instanceof CliApiError)) {
+    throw error;
+  }
+
+  consola.error(`${context}: ${error.message}`);
+  consola.info(CLI_API_ERROR_HINT);
+
+  if (extraInfo) {
+    consola.info(extraInfo);
+  }
+
+  process.exit(1);
+}