LTRAC-466: feat(core) - Track Catalyst version in a dedicated package.json field

Add a `catalyst` field to core/package.json (`catalyst.version` + `catalyst.ref`)
so the true Catalyst version is tracked independently of the top-level `version`,
which merchants may repurpose (deploy tags, Docker labels). The backend
user-agent now reports `catalyst.version`, falling back to `version` for projects
created before the field existed.

A release-time sync script (.github/scripts/sync-catalyst-version.mts), wired
into the Changesets `version` step via the `changeset:version` root script, keeps
`catalyst.version`/`catalyst.ref` in lockstep with each version bump.

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

Author: jorgemoya

.changeset/ltrac-466-catalyst-version-field.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/catalyst-core": patch
+---
+
+Add a `catalyst` field to `core/package.json` (`catalyst.version` and `catalyst.ref`) that tracks the true Catalyst version independently of the top-level `version`, which merchants may repurpose for their own deploy tagging. The backend user-agent now reports `catalyst.version` (falling back to `version` for projects created before the field existed), and the release pipeline keeps the field in sync on each version bump.

.github/scripts/__tests__/sync-catalyst-version.test.mts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { buildCatalystField, syncCatalystField } from '../sync-catalyst-version.mts';
+
+describe('buildCatalystField', () => {
+  it('derives version and ref from name + version', () => {
+    assert.deepEqual(
+      buildCatalystField({ name: '@bigcommerce/catalyst-core', version: '1.7.0' }),
+      { version: '1.7.0', ref: '@bigcommerce/catalyst-core@1.7.0' },
+    );
+  });
+});
+
+describe('syncCatalystField', () => {
+  it('adds the catalyst field mirroring version when absent', () => {
+    const input = `${JSON.stringify(
+      { name: '@bigcommerce/catalyst-core', version: '1.8.0' },
+      null,
+      2,
+    )}\n`;
+
+    const output = JSON.parse(syncCatalystField(input));
+
+    assert.deepEqual(output.catalyst, {
+      version: '1.8.0',
+      ref: '@bigcommerce/catalyst-core@1.8.0',
+    });
+  });
+
+  it('updates a stale catalyst field to the current version', () => {
+    const input = `${JSON.stringify(
+      {
+        name: '@bigcommerce/catalyst-core',
+        version: '2.0.0',
+        catalyst: { version: '1.9.0', ref: '@bigcommerce/catalyst-core@1.9.0' },
+      },
+      null,
+      2,
+    )}\n`;
+
+    const output = JSON.parse(syncCatalystField(input));
+
+    assert.deepEqual(output.catalyst, {
+      version: '2.0.0',
+      ref: '@bigcommerce/catalyst-core@2.0.0',
+    });
+  });
+
+  it('is idempotent and preserves the trailing newline', () => {
+    const input = `${JSON.stringify(
+      {
+        name: '@bigcommerce/catalyst-core',
+        version: '1.7.0',
+        catalyst: { version: '1.7.0', ref: '@bigcommerce/catalyst-core@1.7.0' },
+      },
+      null,
+      2,
+    )}\n`;
+
+    assert.equal(syncCatalystField(input), input);
+  });
+});

.github/scripts/sync-catalyst-version.mts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface CorePackageJson {
+  name: string;
+  version: string;
+  catalyst?: { version: string; ref: string };
+  [key: string]: unknown;
+}
+
+// `catalyst.version` mirrors the released version; `catalyst.ref` is the git tag
+// (`@bigcommerce/catalyst-core@<version>`) the version corresponds to, consumed
+// by the future `catalyst upgrade` command.
+export function buildCatalystField(
+  pkg: Pick<CorePackageJson, "name" | "version">,
+): { version: string; ref: string } {
+  return { version: pkg.version, ref: `${pkg.name}@${pkg.version}` };
+}
+
+// Returns the package.json text with its `catalyst` field synced to `version`.
+// Re-serializes with the canonical 2-space + trailing-newline format, so a run
+// where nothing changed produces no diff.
+export function syncCatalystField(packageJsonText: string): string {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const pkg = JSON.parse(packageJsonText) as CorePackageJson;
+
+  pkg.catalyst = buildCatalystField(pkg);
+
+  return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+
+function main(): void {
+  const corePackageJsonPath = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "../../core/package.json",
+  );
+
+  const updated = syncCatalystField(readFileSync(corePackageJsonPath, "utf-8"));
+
+  writeFileSync(corePackageJsonPath, updated);
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const { catalyst } = JSON.parse(updated) as CorePackageJson;
+
+  console.log(
+    `Synced core/package.json catalyst field → ${catalyst?.version} (${catalyst?.ref})`,
+  );
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main();
+}

.github/workflows/changesets-release.yml

@@ -43,6 +43,9 @@ jobs:
         id: changesets
         uses: changesets/action@v1
         with:
+          # Runs `changeset version`, then syncs core/package.json's `catalyst`
+          # field (version + git ref) to the freshly-bumped version.
+          version: pnpm changeset:version
           publish: pnpm exec changeset publish
           title: "Version Packages (`${{ github.ref_name }}`)"
           commit: "Version Packages (`${{ github.ref_name }}`)"

core/package.json

@@ -2,6 +2,10 @@
   "name": "@bigcommerce/catalyst-core",
   "description": "BigCommerce Catalyst is a Next.js starter kit for building headless BigCommerce storefronts.",
   "version": "1.7.0",
+  "catalyst": {
+    "version": "1.7.0",
+    "ref": "@bigcommerce/catalyst-core@1.7.0"
+  },
   "private": true,
   "engines": {
     "node": ">=24.0.0"

core/user-agent.ts

@@ -2,8 +2,14 @@ import packageInfo from './package.json';
 
 const commitSha = process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA;
 
-const { name, version } = packageInfo;
+const { name } = packageInfo;
+
+// Prefer the dedicated `catalyst.version` field, which always reflects the true
+// Catalyst release even if a merchant repurposes the top-level `version` (Docker
+// labels, deploy tags, etc.). Falls back to `version` for projects created
+// before the `catalyst` field existed.
+const catalystVersion = packageInfo.catalyst?.version ?? packageInfo.version;
 
 // Add package name and version to the user agent
 // Used as part of API client instantiation
-export const backendUserAgent = `${name}/${version}${commitSha ? ` (${commitSha})` : ''}`;
+export const backendUserAgent = `${name}/${catalystVersion}${commitSha ? ` (${commitSha})` : ''}`;

package.json

@@ -19,7 +19,8 @@
     "lint": "dotenv -e .env.local -- turbo lint",
     "test": "turbo run test",
     "test:scripts": "node --test .github/scripts/__tests__/*.test.mts",
-    "typecheck": "turbo typecheck"
+    "typecheck": "turbo typecheck",
+    "changeset:version": "changeset version && node .github/scripts/sync-catalyst-version.mts"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.1",