LTRAC-988: Add custom domain command

[jorgemoya]

What/Why?

Refs LTRAC-988

Adds the catalyst domains add <domain> workflow and a shared domain API client for the Native Hosting domain endpoints. The command resolves existing CLI credentials/project config, displays the returned verification status, and can poll until a pending domain leaves pending status.

DNS record rendering is intentionally not included because the current API response only exposes domain, project UUID, and verification status.

Testing

• node_modules/.bin/vitest run src/cli/commands/domains.spec.ts
• node_modules/.bin/tsc --noEmit
• node_modules/.bin/eslint src/cli/commands/domains.ts src/cli/commands/domains.spec.ts src/cli/lib/domains.ts tests/mocks/handlers.ts src/cli/program.ts --max-warnings 0

Attempted full node_modules/.bin/vitest run --coverage, but this local environment fails unrelated existing tests that require api.github.com network access and npm package env vars.

Migration

None.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 942085a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Bundle Size Report

Comparing against baseline from 81b88df (2026-06-29).

No bundle size changes detected.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Jun 29, 2026 8:02pm

[github-actions]

Unlighthouse Performance Comparison — Vercel

Comparing PR preview deployment Unlighthouse scores vs production Unlighthouse scores.

Summary Score

Aggregate score across all categories as reported by Unlighthouse.

	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Score	90	92	92	95

Category Scores

Category	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Performance	78	84	77	77
Accessibility	95	92	95	98
Best Practices	100	100	100	100
SEO	88	86	100	100

Core Web Vitals

Metric	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
LCP	3.6 s	4.5 s	3.6 s	6.4 s
CLS	0.001	0	0.001	0.011
FCP	1.1 s	1.1 s	1.2 s	1.2 s
TBT	10 ms	0 ms	0 ms	0 ms
Max Potential FID	60 ms	60 ms	50 ms	40 ms
Time to Interactive	3.6 s	5.8 s	3.6 s	6.4 s

Full Unlighthouse report →

[jorgemoya]

Seeing an error I'm still debuging:

~/dev/catalyst/core on  jorgemoya/ltrac-988-cli-add-custom-domain-command [✘!?] took 2s
❯ node ../packages/catalyst/dist/cli.js domains add www.example-bc-jm-staging.com  --api-host api.staging.zone
◢ @bigcommerce/catalyst v1.0.0-alpha.6                                                                                                                   3:31:32 PM

◐ Adding domain www.example-bc-jm-staging.com...                                                                                                         3:31:32 PM

 ERROR  Failed to add domain: 504. This is a server-side response from the Domains API.                                                                  3:31:35 PM

ℹ Correlation ID: 29df6204-82e1-4b20-a160-458ca849d53c                                                                                                  3:31:35 PM
Share this Correlation ID with BigCommerce support.

[jorgemoya]

Fixed now:

~/dev/catalyst/core on  jorgemoya/ltrac-991-cli-remove-custom-domain-command [✘!?]
❯ node ../packages/catalyst/dist/cli.js domains add www.example-bc-jm-staging.com --api-host api.staging.zone
◢ @bigcommerce/catalyst v1.0.0-alpha.6                                                                                                                   3:44:06 PM

◐ Adding domain www.example-bc-jm-staging.com...                                                                                                         3:44:06 PM
✔ Domain www.example-bc-jm-staging.com added.                                                                                                           3:44:08 PM
www.example-bc-jm-staging.com pending        

With wait:

~/dev/catalyst/core on  jorgemoya/ltrac-991-cli-remove-custom-domain-command [✘!?] took 2s
❯ node ../packages/catalyst/dist/cli.js domains add www.jorgemoya.dev --api-host api.staging.zone --wait
◢ @bigcommerce/catalyst v1.0.0-alpha.6                                                                                                                   3:59:43 PM

◐ Adding domain www.jorgemoya.dev...                                                                                                                     3:59:43 PM
✔ Domain www.jorgemoya.dev added.                                                                                                                       3:59:45 PM
◐ Waiting for www.jorgemoya.dev to verify...                                                                                                             3:59:45 PM
www.jorgemoya.dev active