LTRAC-446: feat(cli) - Auto-update BC channel site URL on deploy

Add `--update-site-url <channelId>` (env: CATALYST_UPDATE_SITE_URL) to
`catalyst deploy`. After a successful deployment the CLI PUTs the
resulting deployment URL to the BC channel site endpoint
(v3/channels/:channelId/site). Failures are soft: the deploy itself
still succeeds and the user is told to update manually or re-run
`catalyst auth login` to refresh the access token with the new
`store_channel_settings` scope (added to DEVICE_OAUTH_SCOPES).

Rebased onto the current alpha branch; the 5 original PR commits were
squashed into one because origin/alpha was force-rewritten after the
PR opened (every shared commit had a new SHA), making a per-commit
replay infeasible.

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

Author: jorgemoya

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

@@ -817,3 +817,84 @@ describe('transformation guard', () => {
     expect(installDependencies).not.toHaveBeenCalled();
   });
 });
+
+describe('--update-site-url', () => {
+  const channelId = 7;
+
+  function deployArgs(extra: string[] = []) {
+    return [
+      'node',
+      'catalyst',
+      'deploy',
+      '--store-hash',
+      storeHash,
+      '--access-token',
+      accessToken,
+      '--api-host',
+      apiHost,
+      '--project-uuid',
+      projectUuid,
+      '--prebuilt',
+      ...extra,
+    ];
+  }
+
+  test('PUTs the deployment URL to the given channel', async () => {
+    let putBody: unknown;
+    let receivedChannelId: string | undefined;
+
+    server.use(
+      http.put(
+        'https://:apiHost/stores/:storeHash/v3/channels/:channelId/site',
+        async ({ request, params }) => {
+          putBody = await request.json();
+          receivedChannelId = String(params.channelId);
+
+          return HttpResponse.json({
+            data: { id: 1, url: 'https://example.com', channel_id: channelId },
+          });
+        },
+      ),
+    );
+
+    await program.parseAsync(deployArgs(['--update-site-url', String(channelId)]));
+
+    expect(receivedChannelId).toBe(String(channelId));
+    expect(putBody).toEqual({ url: 'https://example.com' });
+    expect(consola.success).toHaveBeenCalledWith(
+      `Updated channel ${channelId} site URL to https://example.com.`,
+    );
+  });
+
+  test('does not call the channel site API when the flag is omitted', async () => {
+    let putCalled = false;
+
+    server.use(
+      http.put('https://:apiHost/stores/:storeHash/v3/channels/:channelId/site', () => {
+        putCalled = true;
+
+        return HttpResponse.json({}, { status: 200 });
+      }),
+    );
+
+    await program.parseAsync(deployArgs());
+
+    expect(putCalled).toBe(false);
+    expect(consola.success).not.toHaveBeenCalledWith(expect.stringContaining('Updated channel'));
+  });
+
+  test('soft-fails with a warning when the update API returns an error', async () => {
+    server.use(
+      http.put('https://:apiHost/stores/:storeHash/v3/channels/:channelId/site', () =>
+        HttpResponse.json({}, { status: 401 }),
+      ),
+    );
+
+    await program.parseAsync(deployArgs(['--update-site-url', String(channelId)]));
+
+    expect(consola.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to update channel site URL'),
+    );
+    expect(consola.info).toHaveBeenCalledWith(expect.stringContaining('catalyst auth login'));
+  });
+});

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

@@ -6,6 +6,7 @@ import { dirname, join } from 'node:path';
 import yoctoSpinner from 'yocto-spinner';
 import { z } from 'zod';
 
+import { updateChannelSiteUrl } from '../lib/channels';
 import {
   NoLinkedProjectError,
   selectOrCreateInfrastructureProject,
@@ -268,7 +269,7 @@ export const getDeploymentStatus = async (
   storeHash: string,
   accessToken: string,
   apiHost: string,
-) => {
+): Promise<string | undefined> => {
   consola.info('Fetching deployment status...');
 
   const spinner = yoctoSpinner().start('Fetching...');
@@ -346,10 +347,14 @@ export const getDeploymentStatus = async (
   spinner.success('Deployment completed successfully.');
 
   if (deploymentHostname) {
-    consola.success(
-      `View your deployment at: ${colorize('blue', `https://${deploymentHostname}`)}`,
-    );
+    const url = `https://${deploymentHostname}`;
+
+    consola.success(`View your deployment at: ${colorize('blue', url)}`);
+
+    return url;
   }
+
+  return undefined;
 };
 
 export const fetchProject = async (
@@ -394,6 +399,14 @@ Example:
   .addOption(accessTokenOption())
   .addOption(apiHostOption())
   .addOption(projectUuidOption())
+  .addOption(
+    new Option(
+      '--update-site-url <channelId>',
+      "BigCommerce channel ID whose site URL should be updated with this deployment's URL. When omitted, no channel is updated.",
+    )
+      .env('CATALYST_UPDATE_SITE_URL')
+      .argParser((value: string) => Number(value)),
+  )
   .addOption(
     new Option(
       '--secret <value>',
@@ -545,5 +558,34 @@ Example:
       environmentVariables,
     );
 
-    await getDeploymentStatus(deploymentUuid, storeHash, accessToken, options.apiHost);
+    const deploymentUrl = await getDeploymentStatus(
+      deploymentUuid,
+      storeHash,
+      accessToken,
+      options.apiHost,
+    );
+
+    const channelId: number | undefined = options.updateSiteUrl;
+
+    if (!channelId) {
+      return;
+    }
+
+    if (!deploymentUrl) {
+      consola.warn('Skipping channel site URL update: deployment did not return a URL.');
+
+      return;
+    }
+
+    try {
+      await updateChannelSiteUrl(channelId, deploymentUrl, storeHash, accessToken, options.apiHost);
+      consola.success(`Updated channel ${channelId} site URL to ${deploymentUrl}.`);
+    } catch (error) {
+      consola.warn(
+        `Failed to update channel site URL: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      consola.info(
+        'Update it manually in the control panel, or re-run after `catalyst auth login` if the token is missing the store_channel_settings scope.',
+      );
+    }
   });

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

@@ -6,6 +6,7 @@ export const DEVICE_OAUTH_SCOPES = [
   'store_infrastructure_deployments_manage',
   'store_infrastructure_logs_read_only',
   'store_infrastructure_projects_manage',
+  'store_channel_settings',
 ].join(' ');
 export const DEFAULT_LOGIN_URL = 'https://login.bigcommerce.com';
 

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

@@ -0,0 +1,107 @@
+import { http, HttpResponse } from 'msw';
+import { afterAll, beforeAll, describe, expect, test, vi } from 'vitest';
+
+import { server } from '../../../tests/mocks/node';
+
+import { updateChannelSiteUrl } from './channels';
+
+const storeHash = 'test-store';
+const accessToken = 'test-token';
+const apiHost = 'api.bigcommerce.com';
+const channelId = 1;
+
+beforeAll(() => {
+  vi.mock('./telemetry', () => {
+    const instance = {
+      identify: vi.fn(),
+      isEnabled: vi.fn(() => true),
+      track: vi.fn(),
+      correlationId: 'test-session-uuid',
+      commandName: 'unknown',
+      durationMs: vi.fn().mockReturnValue(0),
+      analytics: {
+        closeAndFlush: vi.fn().mockResolvedValue(undefined),
+      },
+    };
+
+    return {
+      Telemetry: vi.fn().mockImplementation(() => instance),
+      getTelemetry: vi.fn(() => instance),
+      resetTelemetry: vi.fn(),
+    };
+  });
+});
+
+afterAll(() => {
+  vi.restoreAllMocks();
+});
+
+describe('updateChannelSiteUrl', () => {
+  test('PUTs the URL and returns parsed channel site', async () => {
+    let receivedBody: unknown;
+
+    server.use(
+      http.put(
+        'https://:apiHost/stores/:storeHash/v3/channels/:channelId/site',
+        async ({ request }) => {
+          receivedBody = await request.json();
+
+          return HttpResponse.json({
+            data: {
+              id: 42,
+              url: 'https://new.example.com',
+              channel_id: channelId,
+            },
+          });
+        },
+      ),
+    );
+
+    const result = await updateChannelSiteUrl(
+      channelId,
+      'https://new.example.com',
+      storeHash,
+      accessToken,
+      apiHost,
+    );
+
+    expect(receivedBody).toEqual({ url: 'https://new.example.com' });
+    expect(result).toEqual({ id: 42, url: 'https://new.example.com', channelId });
+  });
+
+  test('throws with re-auth hint on 401', async () => {
+    server.use(
+      http.put('https://:apiHost/stores/:storeHash/v3/channels/:channelId/site', () =>
+        HttpResponse.json({}, { status: 401 }),
+      ),
+    );
+
+    await expect(
+      updateChannelSiteUrl(channelId, 'https://x.example', storeHash, accessToken, apiHost),
+    ).rejects.toThrow('Re-run `catalyst auth login`');
+  });
+
+  test('throws with re-auth hint on 403', async () => {
+    server.use(
+      http.put('https://:apiHost/stores/:storeHash/v3/channels/:channelId/site', () =>
+        HttpResponse.json({}, { status: 403 }),
+      ),
+    );
+
+    await expect(
+      updateChannelSiteUrl(channelId, 'https://x.example', storeHash, accessToken, apiHost),
+    ).rejects.toThrow('Re-run `catalyst auth login`');
+  });
+
+  test('throws with status on other errors', async () => {
+    server.use(
+      http.put('https://:apiHost/stores/:storeHash/v3/channels/:channelId/site', () =>
+        HttpResponse.json({}, { status: 500 }),
+      ),
+    );
+
+    await expect(
+      updateChannelSiteUrl(channelId, 'https://x.example', storeHash, accessToken, apiHost),
+    ).rejects.toThrow('Failed to update channel site: 500');
+  });
+});

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

@@ -58,6 +58,14 @@ const eligibilityResponseSchema = z.object({
   }),
 });
 
+const channelSiteSchema = z.object({
+  data: z.object({
+    id: z.number(),
+    url: z.string(),
+    channel_id: z.number(),
+  }),
+});
+
 export interface ChannelInit {
   storefrontToken: string;
   envVars: Record<string, string>;
@@ -173,3 +181,46 @@ export async function fetchAvailableChannels(
 
   return channelsResponseSchema.parse(await response.json()).data;
 }
+
+export interface ChannelSite {
+  id: number;
+  url: string;
+  channelId: number;
+}
+
+export async function updateChannelSiteUrl(
+  channelId: number,
+  siteUrl: string,
+  storeHash: string,
+  accessToken: string,
+  apiHost: string,
+): Promise<ChannelSite> {
+  const response = await fetch(
+    `https://${apiHost}/stores/${storeHash}/v3/channels/${channelId}/site`,
+    {
+      method: 'PUT',
+      headers: {
+        'X-Auth-Token': accessToken,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        'X-Correlation-Id': getTelemetry().correlationId,
+      },
+      body: JSON.stringify({ url: siteUrl }),
+    },
+  );
+
+  if (response.status === 401 || response.status === 403) {
+    throw new Error(
+      `Failed to update channel site (${response.status}). Re-run \`catalyst auth login\` to refresh your access token with the store_channel_settings scope.`,
+    );
+  }
+
+  if (!response.ok) {
+    throw new Error(`Failed to update channel site: ${response.status} ${response.statusText}`);
+  }
+
+  const res: unknown = await response.json();
+  const { data } = channelSiteSchema.parse(res);
+
+  return { id: data.id, url: data.url, channelId: data.channel_id };
+}

packages/catalyst/tests/mocks/handlers.ts

@@ -155,4 +155,12 @@ export const handlers = [
     'https://:apiHost/stores/:storeHash/v3/infrastructure/projects/:projectUuid',
     () => new HttpResponse(null, { status: 204 }),
   ),
+
+  // Default handler for updateChannelSiteUrl — succeeds with a generic
+  // payload. Tests that need to assert error handling should override.
+  http.put('https://:apiHost/stores/:storeHash/v3/channels/:channelId/site', () =>
+    HttpResponse.json({
+      data: { id: 1, url: 'https://example.com', channel_id: 1 },
+    }),
+  ),
 ];