Release: Catalyst CLI 1.0.0 and create-catalyst 2.0.0 (merge alpha → canary)

.changeset/catalyst-cli-1.0.0.md

@@ -0,0 +1,49 @@
+---
+"@bigcommerce/catalyst": major
+---
+
+Introducing the Catalyst CLI (`@bigcommerce/catalyst`) — a single command-line tool for scaffolding, building, and deploying your Catalyst storefront to BigCommerce's Native Hosting infrastructure.
+
+### Highlights
+
+- **Scaffold a storefront** — `catalyst create` downloads a clean, standalone project (flattened from `core/`, `workspace:` dependencies resolved to published versions, fresh git repo) via tarball extraction and connects it to your BigCommerce store. The package manager is auto-detected from `npm_config_user_agent`.
+- **Browser-based authentication** — Run `catalyst auth login` to authenticate via an OAuth device code flow. Credentials are stored locally in `.bigcommerce/project.json` for use by all subsequent commands. CI/CD environments can use `--store-hash` and `--access-token` flags or environment variables instead.
+- **Project & channel management** — Create, link, and list BigCommerce infrastructure projects with `catalyst project`, and connect storefront channels with `catalyst channel`.
+- **Build & deploy** — `catalyst build` runs the OpenNext Cloudflare build pipeline (deriving the Wrangler `compatibility_date` dynamically) and generates deployment artifacts. `catalyst deploy` bundles, uploads, and deploys your storefront with real-time progress streaming. Pass runtime secrets with `--secret KEY=VALUE`; environment variables are auto-detected as deploy secrets.
+- **Persisted deployment env vars** — Manage deployment environment variables across deploys with `catalyst env` (list and remove; values are masked).
+- **Custom domains** — Add, list, check the status of, and remove custom domains for a Native Hosting project with `catalyst domains`.
+- **Local preview** — `catalyst start` launches a local Cloudflare Workers preview of your built storefront via the OpenNext adapter.
+- **Live & historical logs** — `catalyst logs tail` streams real-time application logs with color-coded levels and auto-reconnect; `catalyst logs query` retrieves historical logs.
+- **In-place upgrades** — `catalyst upgrade` upgrades a project to a newer version via a resilient 3-way merge (`git merge-tree`, falling back to per-file `git merge-file`), producing resolvable conflict markers instead of ever aborting.
+- **Smart credential resolution** — Configuration is resolved in priority order: CLI flags → `--env-file` → process environment variables → `.bigcommerce/project.json`.
+- **Telemetry** — Anonymous usage telemetry with session and correlation IDs for support. Opt out anytime with `catalyst telemetry disable`.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `catalyst create` | Scaffold and connect a Catalyst storefront to your BigCommerce store |
+| `catalyst auth` | Authenticate, sign out, and verify stored credentials |
+| `catalyst project` | Create, link, and list infrastructure projects |
+| `catalyst channel` | Connect a storefront channel to your project |
+| `catalyst build` | Build your Catalyst project for deployment |
+| `catalyst deploy` | Build and deploy to BigCommerce Native Hosting |
+| `catalyst env` | Manage persisted deployment environment variables |
+| `catalyst domains` | Manage custom domains for a Native Hosting project |
+| `catalyst start` | Start a local Cloudflare Workers preview |
+| `catalyst logs` | Stream live logs and query historical logs |
+| `catalyst upgrade` | Upgrade a project to a newer version via 3-way merge |
+| `catalyst version` | Display CLI, Node.js, and platform info |
+| `catalyst telemetry` | View or change telemetry collection status |
+
+### Getting started
+
+```bash
+cd core
+pnpm add @bigcommerce/catalyst@latest @opennextjs/cloudflare@1.17.3
+pnpm catalyst auth login
+pnpm catalyst project create
+pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<hash> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<token>
+```
+
+For full documentation, see the [Native Hosting Overview](https://developer.bigcommerce.com/docs/storefront/catalyst/deployment/native-hosting/overview) and [CLI Reference](https://developer.bigcommerce.com/docs/storefront/catalyst/reference/cli).

.changeset/config.json

@@ -12,6 +12,5 @@
     "tag": true
   },
   "baseBranch": "canary",
-  "updateInternalDependencies": "patch",
-  "ignore": ["@bigcommerce/catalyst"]
+  "updateInternalDependencies": "patch"
 }

.changeset/ltrac-910-create-catalyst-thin-wrapper.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/create-catalyst": major
+---
+
+Reduce `create-catalyst` to a thin wrapper that delegates to `catalyst create`. `pnpm create catalyst` / `npx create-catalyst` still scaffold a project — now by invoking `@bigcommerce/catalyst` under the hood — so the scaffolding UX is unchanged. The standalone `init`, `integration`, and `telemetry` subcommands are removed; use `catalyst channel link` and `catalyst telemetry` from the consolidated CLI instead.

.changeset/pre.json

@@ -0,0 +1,22 @@
+{
+  "mode": "exit",
+  "tag": "alpha",
+  "initialVersions": {
+    "@bigcommerce/catalyst": "1.0.0",
+    "@bigcommerce/catalyst-core": "1.6.2",
+    "@bigcommerce/catalyst-client": "1.0.1",
+    "@bigcommerce/create-catalyst": "1.0.2",
+    "@bigcommerce/eslint-config-catalyst": "1.0.0"
+  },
+  "changesets": [
+    "alpha-release-notes",
+    "auto-detect-deploy-secrets",
+    "cli-built-in-help-text",
+    "cli-dynamic-compat-date",
+    "cli-show-env-path-in-help",
+    "cli-strip-instrumentation-hook",
+    "fix-env-var-names",
+    "project-list-deployed-url",
+    "wise-worms-hear"
+  ]
+}

core/.gitignore

@@ -54,3 +54,6 @@ build-config.json
 # OpenNext
 .open-next
 .wrangler
+
+# Catalyst CLI config
+.bigcommerce

packages/catalyst/AGENTS.md

@@ -0,0 +1,96 @@
+# Catalyst CLI (`@bigcommerce/catalyst`)
+
+CLI tool for Catalyst development and deployment — handles build, dev server, and deployment to Cloudflare Workers.
+
+## Directory Structure
+
+```
+src/cli/
+├── index.ts          # Entry point (#!/usr/bin/env node)
+├── program.ts        # Commander program setup, registers all commands
+├── commands/         # CLI command implementations (auth, build, deploy, logs, project, start, telemetry, version)
+├── hooks/            # Pre/post action hooks (telemetry)
+└── lib/              # Utilities (auth, logger, project config, credentials, wrangler config, telemetry, deployment errors)
+templates/            # OpenNext config and public_headers template
+tests/mocks/          # MSW handlers and test mocks
+dist/cli.js           # Bundled output (single ESM file)
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `auth whoami/login/logout` | Manage authentication (device code OAuth flow, credential storage) |
+| `build` | Build Catalyst project using OpenNext/Cloudflare adapter |
+| `deploy` | Deploy to Cloudflare with bundle upload |
+| `logs` | View logs (`tail` default, `query` planned). Supports `--format` (default/json/pretty/short/request) |
+| `project create/list/link` | Manage BigCommerce infrastructure projects |
+| `start` | Start local preview using OpenNext Cloudflare adapter |
+| `telemetry` | Enable/disable/check telemetry |
+| `version` | Display version and platform info |
+
+## Development
+
+```bash
+pnpm dev          # Watch mode (rebuilds dist/cli.js on changes)
+pnpm build        # Production build via tsup
+pnpm test         # Run tests (vitest)
+pnpm test:watch   # Watch mode tests
+pnpm typecheck    # tsc --noEmit
+pnpm lint         # eslint with 0 warnings threshold
+```
+
+## Testing Changes
+
+To test CLI changes directly without a full publish cycle, build the CLI package first, then run the compiled output from inside the `core/` directory using its absolute path:
+
+```bash
+# From packages/catalyst — rebuild the CLI
+pnpm build
+
+# From core/ — run the CLI using the absolute path to the built output
+pnpm exec <repo-root>/packages/catalyst/dist/cli.js <command>
+```
+
+For example: `pnpm exec <repo-root>/packages/catalyst/dist/cli.js project list`.
+
+## Build
+
+- **Bundler**: tsup (`tsup.config.ts`)
+- **Entry**: `src/cli/index.ts` → `dist/cli.js` (single ESM bundle with source maps)
+- **Environment variables** injected at build time: `CLI_SEGMENT_WRITE_KEY`, `CONSOLA_LEVEL`
+
+## Testing
+
+- **Framework**: Vitest (`vitest.config.ts`)
+- **Coverage threshold**: 100% (strict)
+- **Mocking**: MSW for BigCommerce API calls; telemetry always disabled in tests (`vitest.setup.ts`)
+- **Test files**: co-located as `*.spec.ts` next to source files
+
+## Key Dependencies
+
+- `commander` — CLI framework
+- `execa` — process execution (next, pnpm, wrangler)
+- `consola` — logging
+- `zod` — API response validation
+- `conf` — persistent config (`.bigcommerce/project.json`)
+- `@segment/analytics-node` — telemetry
+- `adm-zip` — bundle zipping for deploy
+
+## After Making Changes
+
+Always run `pnpm typecheck` and `pnpm lint` after making code changes, and fix any errors or warnings before considering the work done. The lint config enforces zero warnings (`--max-warnings 0`). Use `pnpm lint --fix` to auto-fix formatting and fixable lint issues before manually editing.
+
+## Code Style Notes
+
+- **No `let` when avoidable** — prefer `const` with `while (true)` + `break` over mutable flags.
+- **No iterators/generators** — eslint `no-restricted-syntax` disallows `for...of` and generator functions. Use `.forEach()`, `.map()`, etc.
+- **Consola for logging** — use `consola` (from `../lib/logger`) instead of `console`. Use `colorize` from `consola/utils` for colored output.
+- **Shared CLI options** — commands that need `--store-hash`, `--access-token`, `--api-host`, and `--project-uuid` should use the shared option factories from `lib/shared-options.ts`. Chain `.makeOptionMandatory()` inline where needed to preserve commander's extra-typings inference.
+- **SSE stream pattern** — the fetch API's `ReadableStreamDefaultReader` doesn't support async iteration, so `while (true)` + `reader.read()` + `break` is the standard pattern. For long-lived streams, implement a TTL-based reconnect to free connection pool resources, and distinguish server-side disconnects (`TypeError: terminated`) from actual failures for retry logic.
+
+## Integration Points
+
+- **BigCommerce Infrastructure API**: `https://api.bigcommerce.com/stores/{storeHash}/v3/infrastructure/`
+- **Next.js**: dev/build/start
+- **OpenNext + Cloudflare**: serverless build and deploy via Wrangler

packages/catalyst/CHANGELOG.md

@@ -0,0 +1,89 @@
+# @bigcommerce/catalyst
+
+## 1.0.0-alpha.6
+
+### Patch Changes
+
+- [#3061](https://github.com/bigcommerce/catalyst/pull/3061) [`eea1355`](https://github.com/bigcommerce/catalyst/commit/eea135543423dc0d50d6bff68d93f1548e54e096) Thanks [@jorgemoya](https://github.com/jorgemoya)! - `catalyst build` now derives the Cloudflare Workers `compatibility_date` dynamically (current date minus one month) instead of using a pinned date, keeping the build-time runtime semantics aligned with what the deployment service applies at deploy time.
+
+## 1.0.0-alpha.5
+
+### Minor Changes
+
+- [#2988](https://github.com/bigcommerce/catalyst/pull/2988) [`24f35a4`](https://github.com/bigcommerce/catalyst/commit/24f35a4cc60d73036c264a896e816b98aa47bfba) Thanks [@jorgemoya](https://github.com/jorgemoya)! - Show every deployed URL for each project in `catalyst project list` output (the canonical hostname plus any vanity hostnames) so users can recover the hosted storefront URLs without having to redeploy.
+
+### Patch Changes
+
+- [#3028](https://github.com/bigcommerce/catalyst/pull/3028) [`bdc6e0b`](https://github.com/bigcommerce/catalyst/commit/bdc6e0bf055262e1440bcc1ebcc55597256b424a) Thanks [@jorgemoya](https://github.com/jorgemoya)! - Remove `core/instrumentation.ts` and the `@vercel/otel` dependency during Commerce Hosting setup. The hook isn't compatible with the OpenNext + Cloudflare Workers bundling path and caused a "Failed to prepare server" error on every cold start in `catalyst logs tail`. Self-hosted (non-Commerce Hosting) deployments are unaffected.
+
+## 1.0.0-alpha.4
+
+### Patch Changes
+
+- [`de04f42`](https://github.com/bigcommerce/catalyst/commit/de04f42696b30b675bec2625eefa1e825b4a97ba) Thanks [@chanceaclark](https://github.com/chanceaclark)! - Add built-in help text to all CLI commands so `catalyst <command> --help` is the canonical reference.
+
+- [`e740158`](https://github.com/bigcommerce/catalyst/commit/e7401583603aae85d4adef23b4b72eeb96e11907) Thanks [@chanceaclark](https://github.com/chanceaclark)! - Show the global `--env-path` option in every subcommand's `--help` output.
+
+- [`e5b4dee`](https://github.com/bigcommerce/catalyst/commit/e5b4dee1fc108d648b6110707b572c1fc9bc2e7c) Thanks [@chanceaclark](https://github.com/chanceaclark)! - Update the CLI with the new client id.
+
+## 1.0.0-alpha.3
+
+### Minor Changes
+
+- [#2972](https://github.com/bigcommerce/catalyst/pull/2972) [`e681933`](https://github.com/bigcommerce/catalyst/commit/e681933ebbe798198e4c1b8f6f20f67dc4ec36ad) Thanks [@jorgemoya](https://github.com/jorgemoya)! - Auto-detect environment variables as deploy secrets.
+
+## 1.0.0-alpha.2
+
+### Patch Changes
+
+- Fix CLI environment variable resolution for `deploy`, `build`, and `project` commands. The published dist was using stale `BIGCOMMERCE_*` env var names instead of the correct `CATALYST_*` names (`CATALYST_STORE_HASH`, `CATALYST_ACCESS_TOKEN`, `CATALYST_PROJECT_UUID`).
+
+## 1.0.0-alpha.1
+
+### Major Changes
+
+- Introducing the Catalyst CLI (`@bigcommerce/catalyst`) — a command-line tool for building and deploying your Catalyst storefront to BigCommerce's Native Hosting infrastructure.
+
+  ### Highlights
+  - **Browser-based authentication** — Run `catalyst auth login` to authenticate via an OAuth device code flow. Credentials are stored locally in `.bigcommerce/project.json` for use by all subsequent commands. CI/CD environments can use `--store-hash` and `--access-token` flags or environment variables instead.
+  - **Project management** — Create, link, and list BigCommerce infrastructure projects with `catalyst project create`, `catalyst project link`, and `catalyst project list`.
+  - **Build & deploy** — `catalyst build` runs the OpenNext Cloudflare build pipeline and generates deployment artifacts. `catalyst deploy` bundles, uploads, and deploys your storefront with real-time progress streaming. Pass runtime secrets with `--secret KEY=VALUE`.
+  - **Local preview** — `catalyst start` launches a local Cloudflare Workers preview of your built storefront via the OpenNext adapter.
+  - **Live log tailing** — `catalyst logs tail` streams real-time application logs from your deployed storefront with color-coded log levels and multiple output formats.
+  - **Smart credential resolution** — Configuration is resolved in priority order: CLI flags → `--env-file` → process environment variables → `.bigcommerce/project.json`.
+  - **Telemetry** — Anonymous usage telemetry with session and correlation IDs for support. Opt out anytime with `catalyst telemetry disable`.
+
+  ### Commands
+
+  | Command                   | Description                                       |
+  | ------------------------- | ------------------------------------------------- |
+  | `catalyst auth login`     | Authenticate via browser OAuth flow               |
+  | `catalyst auth logout`    | Remove stored credentials                         |
+  | `catalyst auth whoami`    | Verify credentials and display store/project info |
+  | `catalyst project create` | Create a new infrastructure project               |
+  | `catalyst project link`   | Link to an existing infrastructure project        |
+  | `catalyst project list`   | List infrastructure projects for your store       |
+  | `catalyst build`          | Build your Catalyst project for deployment        |
+  | `catalyst deploy`         | Build and deploy to BigCommerce Native Hosting    |
+  | `catalyst start`          | Start a local Cloudflare Workers preview          |
+  | `catalyst logs tail`      | Stream live logs from your deployment             |
+  | `catalyst version`        | Display CLI, Node.js, and platform info           |
+  | `catalyst telemetry`      | View or change telemetry collection status        |
+
+  ### Getting started
+
+  ```bash
+  cd core
+  pnpm add @bigcommerce/catalyst@alpha @opennextjs/cloudflare@1.17.3
+  pnpm catalyst auth login
+  pnpm catalyst project create
+  pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<hash> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<token>
+  ```
+
+  For full documentation, see the [Native Hosting Overview](https://developer.bigcommerce.com/docs/storefront/catalyst/deployment/native-hosting/overview) and [CLI Reference](https://developer.bigcommerce.com/docs/storefront/catalyst/reference/cli).
+
+## 1.0.0-alpha.0
+
+### Major Changes
+
+- [`acee114`](https://github.com/bigcommerce/catalyst/commit/acee114ca0ee7428e33b1db28a5b3b18914cde4b) Thanks [@chanceaclark](https://github.com/chanceaclark)! - Alpha version of the CLI

packages/catalyst/README.md

@@ -1,3 +1,36 @@
 # @bigcommerce/catalyst
 
-CLI
+CLI tool for Catalyst development and deployment.
+
+## Developing the CLI
+
+You'll need two terminal windows:
+
+### Terminal 1 — Watch mode (rebuilds on changes)
+
+```bash
+cd packages/catalyst
+pnpm dev
+```
+
+This runs `tsup --watch` and rebuilds `dist/cli.js` on every source change.
+
+### Terminal 2 — Run the CLI
+
+From the `core/` directory, run the CLI using the absolute path to the built executable:
+
+```bash
+cd core
+pnpm exec <repo-root>/packages/catalyst/dist/cli.js <command>
+```
+
+For example:
+
+```bash
+pnpm exec <repo-root>/packages/catalyst/dist/cli.js project list
+pnpm exec <repo-root>/packages/catalyst/dist/cli.js logs tail
+pnpm exec <repo-root>/packages/catalyst/dist/cli.js logs query --start 2026-06-01T00:00:00Z --end 2026-06-02T00:00:00Z
+pnpm exec <repo-root>/packages/catalyst/dist/cli.js deploy
+```
+
+Replace `<repo-root>` with the absolute path to your local clone of the `catalyst` repository.

packages/catalyst/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigcommerce/catalyst",
-  "version": "0.1.0",
+  "version": "1.0.0-alpha.6",
   "type": "module",
   "bin": {
     "catalyst": "dist/cli.js"
@@ -9,7 +9,6 @@
     "dist",
     "templates"
   ],
-  "private": true,
   "scripts": {
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
@@ -23,21 +22,32 @@
     "node": "^20.0.0 || ^22.0.0 || ^24.0.0"
   },
   "dependencies": {
+    "@commander-js/extra-typings": "^14.0.0",
+    "@inquirer/prompts": "^7.5.3",
     "@segment/analytics-node": "^2.2.1",
     "adm-zip": "^0.5.16",
     "commander": "^14.0.0",
     "conf": "^13.1.0",
     "consola": "^3.4.2",
+    "cross-spawn": "^7.0.6",
     "dotenv": "^16.5.0",
     "execa": "^9.6.0",
+    "fs-extra": "^11.3.0",
+    "lodash.kebabcase": "^4.1.1",
+    "nypm": "^0.5.4",
+    "open": "^10.1.0",
+    "std-env": "^3.9.0",
+    "tar": "^7.5.7",
     "yocto-spinner": "^1.0.0",
     "zod": "^4.0.5"
   },
   "devDependencies": {
     "@bigcommerce/eslint-config": "^2.11.0",
     "@bigcommerce/eslint-config-catalyst": "workspace:^",
-    "@commander-js/extra-typings": "^14.0.0",
     "@types/adm-zip": "^0.5.7",
+    "@types/cross-spawn": "^6.0.6",
+    "@types/fs-extra": "^11.0.4",
+    "@types/lodash.kebabcase": "^4.1.9",
     "@types/node": "^22.15.30",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
@@ -49,6 +59,6 @@
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "@opennextjs/cloudflare": "^1.8.0"
+    "@opennextjs/cloudflare": "1.17.3"
   }
 }