fix(cli) - Don't frame clear user-actionable errors as bugs to report

A clear 4xx API response (validation error, not-found, not-enabled, conflict)
or bad command input was printed through the top-level handler's bug-report
path, appending a Correlation ID and "share this with BigCommerce support" to
an already-actionable message.

Add a reusable UserActionableError base class that the top-level handler prints
plainly (UnauthorizedError now extends it). Adopt it across the API clients for
their 4xx / input-validation cases:

- domains: 4xx responses, "API not enabled", ownership-verification errors
- project: validation errors, "not enabled", project-not-found
- logs: "not enabled", project-not-found, invalid query, bad time-window input
- channel: channel-site auth/scope failures
- auth/login: missing or unvalidatable credentials

5xx server-side failures and unexpected errors stay plain Errors and keep the
Correlation ID + support framing.

Refs LTRAC-1115
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jorgemoya

.changeset/user-actionable-cli-errors.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/catalyst": patch
+---
+
+Stop framing clear, user-actionable CLI errors as bugs to report. Validation errors, not-found and not-enabled responses, conflicts, and bad command input now print just the message and exit, instead of appending a Correlation ID and a "share this with BigCommerce support" prompt. That framing is now reserved for genuine server-side (5xx) failures and unexpected errors. Applies across the `domains`, `project`, `channel`, `logs`, and `auth` commands via a shared `UserActionableError` type.

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

@@ -6,6 +6,7 @@ import { afterAll, afterEach, beforeAll, describe, expect, MockInstance, test, v
 
 import { server } from '../../../tests/mocks/node';
 import { claimDomain, createDomain, deleteDomain, getDomain, listDomains } from '../lib/domains';
+import { UserActionableError } from '../lib/errors';
 import { consola } from '../lib/logger';
 import { mkTempDir } from '../lib/mk-temp-dir';
 import { getProjectConfig, ProjectConfigSchema } from '../lib/project-config';
@@ -272,13 +273,50 @@ describe('domain API client', () => {
       ),
     );
 
-    await expect(
-      createDomain(domain, projectUuid, storeHash, accessToken, apiHost),
-    ).rejects.toThrow(
+    const error = await createDomain(domain, projectUuid, storeHash, accessToken, apiHost).catch(
+      (err: unknown) => err,
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    // A 5xx is a server-side failure worth escalating, so it stays a plain Error
+    // and keeps the top-level Correlation ID + support framing.
+    expect(error).not.toBeInstanceOf(UserActionableError);
+    expect(error).toHaveProperty(
+      'message',
       'Failed to add domain: 502 Bad Gateway. This is a server-side response from the Domains API.',
     );
   });
 
+  test('treats a 4xx conflict as user-actionable (no support/correlation framing)', async () => {
+    server.use(
+      http.post(
+        'https://:apiHost/stores/:storeHash/v3/infrastructure/projects/:projectUuid/domains/:domain/claim',
+        () =>
+          HttpResponse.json(
+            {
+              status: 409,
+              title:
+                'The domain is already bound to another project in this store. Use the transfer endpoint to move it.',
+              errors: {
+                domain: `'${domain}' is already bound to another project in this store.`,
+              },
+            },
+            { status: 409 },
+          ),
+      ),
+    );
+
+    const error = await claimDomain(domain, projectUuid, storeHash, accessToken, apiHost).catch(
+      (err: unknown) => err,
+    );
+
+    expect(error).toBeInstanceOf(UserActionableError);
+    expect(error).toHaveProperty(
+      'message',
+      expect.stringContaining('already bound to another project in this store'),
+    );
+  });
+
   test('lists domains for a project', async () => {
     await expect(listDomains(projectUuid, storeHash, accessToken, apiHost)).resolves.toEqual([
       {

packages/catalyst/src/cli/index.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { UnauthorizedError } from './lib/auth-errors';
+import { UserActionableError } from './lib/errors';
 import { consola } from './lib/logger';
 import { getTelemetry } from './lib/telemetry';
 import { program } from './program';
@@ -22,9 +22,11 @@ const handleFatalError = async (error: unknown) => {
     // Don't mask the original error
   }
 
-  // An invalid/expired token is user-actionable, not a bug to report — print the
-  // re-auth guidance without the "share your Correlation ID with support" noise.
-  if (error instanceof UnauthorizedError) {
+  // A user-actionable error (invalid/expired token, a clear 4xx validation or
+  // conflict response, a feature that isn't enabled) already tells the user what
+  // to do — print it without the "share your Correlation ID with support" noise
+  // that only helps for genuine bugs and server-side failures.
+  if (error instanceof UserActionableError) {
     consola.error(errorMessage);
     process.exit(1);
   }

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

@@ -1,3 +1,5 @@
+import { UserActionableError } from './errors';
+
 // Thrown when an authenticated API call comes back 401 Unauthorized — i.e. the
 // access token was sent but rejected. This covers an expired/revoked token as
 // well as a token that was never valid (e.g. a typo'd `--access-token` flag or
@@ -10,7 +12,7 @@
 // let this propagate to the top-level handler in `index.ts`, which prints the
 // message without the generic "share your Correlation ID with support"
 // bug-report framing.
-export class UnauthorizedError extends Error {
+export class UnauthorizedError extends UserActionableError {
   constructor() {
     super(
       'Your access token is invalid or has expired.\n' +

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
 import { assertAuthorized } from './auth-errors';
+import { UserActionableError } from './errors';
 import { getTelemetry } from './telemetry';
 
 // `origin` is the CLI-API gateway (configured via `--cli-api-origin`, default
@@ -239,7 +240,7 @@ export async function updateChannelSiteUrl(
   );
 
   if (response.status === 401 || response.status === 403) {
-    throw new Error(
+    throw new UserActionableError(
       `Failed to update channel site (${response.status}). Re-run \`catalyst auth login\` to refresh your access token with the store_channel_settings scope.`,
     );
   }

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
 import { assertAuthorized } from './auth-errors';
+import { UserActionableError } from './errors';
 import { formatV3Error } from './observability';
 import { getTelemetry } from './telemetry';
 
@@ -32,7 +33,7 @@ const ownershipVerificationMetaSchema = z.object({
 // domain bound to another store has not been verified. Carries the TXT record
 // the caller must publish so the command can render actionable next steps
 // instead of an opaque error.
-export class DomainOwnershipVerificationError extends Error {
+export class DomainOwnershipVerificationError extends UserActionableError {
   readonly ownershipVerification: OwnershipVerification;
 
   constructor(message: string, ownershipVerification: OwnershipVerification) {
@@ -111,7 +112,7 @@ async function assertDomainResponse(response: Response, action: string): Promise
   assertAuthorized(response);
 
   if (response.status === 403) {
-    throw new Error(DOMAINS_API_NOT_ENABLED);
+    throw new UserActionableError(DOMAINS_API_NOT_ENABLED);
   }
 
   if (response.ok) {
@@ -126,7 +127,14 @@ async function assertDomainResponse(response: Response, action: string): Promise
     throw new DomainOwnershipVerificationError(message, ownershipVerification);
   }
 
-  throw new Error(message);
+  // 5xx responses are server-side failures worth escalating, so keep the
+  // Correlation ID + support framing. A 4xx (validation, not-found, conflict)
+  // is a clear, user-actionable response — surface just the message.
+  if (response.status >= 500) {
+    throw new Error(message);
+  }
+
+  throw new UserActionableError(message);
 }
 
 export async function createDomain(

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

@@ -0,0 +1,12 @@
+// Base class for errors that are the user's to fix and whose message already
+// says everything they need (bad input, a naming/ownership conflict, invalid
+// credentials, a feature that isn't enabled). The top-level handler in
+// `index.ts` prints these plainly and exits non-zero WITHOUT the "share your
+// Correlation ID with BigCommerce support" bug-report framing that unexpected
+// and server-side errors get — a clear 4xx response is not a bug to report.
+export class UserActionableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UserActionableError';
+  }
+}

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

@@ -5,6 +5,7 @@ import yoctoSpinner from 'yocto-spinner';
 import { z } from 'zod';
 
 import { DEVICE_OAUTH_SCOPES, requestDeviceCode, waitForDeviceToken } from './auth';
+import { UserActionableError } from './errors';
 import { consola } from './logger';
 
 export interface LoginResult {
@@ -92,14 +93,14 @@ async function manualLogin(apiHost: string): Promise<LoginResult> {
   const storeHash = storeHashInput.trim();
 
   if (!storeHash) {
-    throw new Error('Store hash is required.');
+    throw new UserActionableError('Store hash is required.');
   }
 
   const accessTokenInput = await password({ message: 'Access token:', mask: true });
   const accessToken = accessTokenInput.trim();
 
   if (!accessToken) {
-    throw new Error('Access token is required.');
+    throw new UserActionableError('Access token is required.');
   }
 
   const spinner = yoctoSpinner().start('Validating credentials...');
@@ -113,7 +114,7 @@ async function manualLogin(apiHost: string): Promise<LoginResult> {
 
     const message = error instanceof Error ? error.message : String(error);
 
-    throw new Error(
+    throw new UserActionableError(
       `Could not validate credentials (${message}). Double-check your store hash and access token, then try again.`,
     );
   }

packages/catalyst/src/cli/lib/observability.spec.ts

@@ -3,6 +3,7 @@ import { afterAll, afterEach, beforeAll, describe, expect, test, vi } from 'vite
 
 import { server } from '../../../tests/mocks/node';
 
+import { UserActionableError } from './errors';
 import { consola } from './logger';
 import { formatLogEntry, formatV3Error, queryLogs, resolveTimeWindow } from './observability';
 
@@ -34,6 +35,10 @@ describe('resolveTimeWindow', () => {
     );
   });
 
+  test('bad time-window input is user-actionable (no support/correlation framing)', () => {
+    expect(() => resolveTimeWindow({ since: 'yesterday' })).toThrow(UserActionableError);
+  });
+
   test('defaults end to now when omitted', () => {
     expect(resolveTimeWindow({ start: '2026-06-11T00:00:00Z' }, nowMs)).toEqual({
       start: '2026-06-11T00:00:00Z',
@@ -418,12 +423,14 @@ describe('queryLogs', () => {
   test('maps 404 to a project-not-found error', async () => {
     server.use(http.get(logsUrl, () => new HttpResponse(null, { status: 404 })));
 
-    await expect(
-      queryLogs(projectUuid, storeHash, accessToken, apiHost, {
-        start: '2026-06-01T00:00:00Z',
-        end: '2026-06-02T00:00:00Z',
-      }),
-    ).rejects.toThrow('Project not found');
+    const error = await queryLogs(projectUuid, storeHash, accessToken, apiHost, {
+      start: '2026-06-01T00:00:00Z',
+      end: '2026-06-02T00:00:00Z',
+    }).catch((err: unknown) => err);
+
+    // A 4xx is a clear, user-actionable response — no Correlation ID/support framing.
+    expect(error).toBeInstanceOf(UserActionableError);
+    expect(error).toHaveProperty('message', expect.stringContaining('Project not found'));
   });
 
   test('surfaces the v3 error message on 422', async () => {
@@ -453,11 +460,15 @@ describe('queryLogs', () => {
       http.get(logsUrl, () => new HttpResponse(null, { status: 500, statusText: 'Server Error' })),
     );
 
-    await expect(
-      queryLogs(projectUuid, storeHash, accessToken, apiHost, {
-        start: '2026-06-01T00:00:00Z',
-        end: '2026-06-02T00:00:00Z',
-      }),
-    ).rejects.toThrow('Failed to fetch logs: 500 Server Error');
+    const error = await queryLogs(projectUuid, storeHash, accessToken, apiHost, {
+      start: '2026-06-01T00:00:00Z',
+      end: '2026-06-02T00:00:00Z',
+    }).catch((err: unknown) => err);
+
+    // A 5xx is a server-side failure worth escalating, so it stays a plain Error
+    // and keeps the top-level Correlation ID + support framing.
+    expect(error).toBeInstanceOf(Error);
+    expect(error).not.toBeInstanceOf(UserActionableError);
+    expect(error).toHaveProperty('message', 'Failed to fetch logs: 500 Server Error');
   });
 });

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

@@ -2,6 +2,7 @@ import { colorize } from 'consola/utils';
 import { z } from 'zod';
 
 import { assertAuthorized } from './auth-errors';
+import { UserActionableError } from './errors';
 import { getTelemetry } from './telemetry';
 
 export const LOG_LEVELS = ['debug', 'info', 'warn', 'error'] as const;
@@ -111,7 +112,7 @@ export function resolveTimeWindow(
     endMs = parseTimeInput(end);
 
     if (endMs === null) {
-      throw new Error(
+      throw new UserActionableError(
         `Invalid --end value "${end}". Provide an ISO-8601 timestamp or a Unix epoch (seconds).`,
       );
     }
@@ -124,7 +125,7 @@ export function resolveTimeWindow(
     const durationMs = parseDuration(since);
 
     if (durationMs === null) {
-      throw new Error(
+      throw new UserActionableError(
         `Invalid --since value "${since}". Provide a duration like 30m, 6h, or 2d (units: s, m, h, d).`,
       );
     }
@@ -135,20 +136,22 @@ export function resolveTimeWindow(
     startMs = parseTimeInput(start);
 
     if (startMs === null) {
-      throw new Error(
+      throw new UserActionableError(
         `Invalid --start value "${start}". Provide an ISO-8601 timestamp or a Unix epoch (seconds).`,
       );
     }
   } else {
-    throw new Error('Provide a time window with --since <duration> or --start <time>.');
+    throw new UserActionableError(
+      'Provide a time window with --since <duration> or --start <time>.',
+    );
   }
 
   if (startMs > endMs) {
-    throw new Error('Invalid time window: --start must be before or equal to --end.');
+    throw new UserActionableError('Invalid time window: --start must be before or equal to --end.');
   }
 
   if (endMs - startMs > SEVEN_DAYS_MS) {
-    throw new Error('Invalid time window: the range must not exceed 7 days.');
+    throw new UserActionableError('Invalid time window: the range must not exceed 7 days.');
   }
 
   return { start, end };
@@ -246,21 +249,21 @@ export async function queryLogs(
   assertAuthorized(response);
 
   if (response.status === 403) {
-    throw new Error(
+    throw new UserActionableError(
       'Infrastructure Logs API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it.',
     );
   }
 
   if (response.status === 404) {
-    throw new Error('Project not found. Check the project UUID.');
+    throw new UserActionableError('Project not found. Check the project UUID.');
   }
 
   // 400 (bad UUID) and 422 (invalid window/filter) both carry the field-keyed
   // v3 error envelope — surface its message rather than the bare status.
   if (response.status === 400 || response.status === 422) {
     const body: unknown = await response.json().catch(() => null);
 
-    throw new Error(formatV3Error(body) ?? 'Invalid log query.');
+    throw new UserActionableError(formatV3Error(body) ?? 'Invalid log query.');
   }
 
   if (!response.ok) {