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

[jorgemoya]

Linear: LTRAC-466

What/Why?

Adds a catalyst field to core/package.json so the true Catalyst version is tracked independently of the top-level version (merchants may repurpose version for deploy tags, Docker labels, etc.). This gives a stable source of truth for:

• the future catalyst upgrade command (knowing which version/ref a project is based on), and
• the backend user-agent (analytics / support debugging).

"catalyst": {
  "version": "1.7.0",
  "ref": "@bigcommerce/catalyst-core@1.7.0"  // git tag the upgrade command targets
}

Changes

• core/package.json — adds the catalyst field (mirrors the current 1.7.0).
• core/user-agent.ts — backendUserAgent now uses packageInfo.catalyst?.version ?? packageInfo.version. The fallback keeps it working for projects created before this field existed.
• .github/scripts/sync-catalyst-version.mts (+ tests) — re-derives catalyst.version/catalyst.ref from version. Follows the repo's .mts script convention; idempotent (verified: re-running on core/package.json produces no diff).
• package.json — changeset:version = changeset version && node .github/scripts/sync-catalyst-version.mts.
• .github/workflows/changesets-release.yml — points the Changesets action's version: step at pnpm changeset:version, so the catalyst field is bumped in lockstep with every release (in the auto-generated Version Packages PR).
• Changeset: @bigcommerce/catalyst-core: patch.

Testing

pnpm test:scripts → 139 passed (incl. 4 new for the sync script). Ran the sync script against the real core/package.json: clean, idempotent, no reformatting. core typecheck (which needs the env-gated GraphQL generate step) runs in CI; the user-agent.ts change is type-safe (catalyst?.version ?? version, both string).

Review focus

• The release-workflow change (version: → pnpm changeset:version) — please sanity-check it fits the release process. It only adds the sync step after changeset version; publish is unchanged.

Migration

None for merchants. Existing projects without the field keep working via the user-agent fallback; the field appears on their next Catalyst upgrade.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Jun 18, 2026 9:30pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 8c5a648

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst-core	Patch

Not sure what this means? Click here to learn what changesets are.

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

[github-actions]

Bundle Size Report

Comparing against baseline from 226f2f3 (2026-06-18).

No bundle size changes detected.

[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	77	72	75	81
Accessibility	95	98	95	92
Best Practices	100	100	100	100
SEO	88	88	100	100

Core Web Vitals

Metric	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
LCP	3.6 s	4.4 s	3.7 s	5.0 s
CLS	0.037	0.247	0	0
FCP	1.2 s	1.2 s	1.2 s	1.1 s
TBT	0 ms	10 ms	0 ms	10 ms
Max Potential FID	50 ms	60 ms	50 ms	70 ms
Time to Interactive	3.6 s	4.4 s	3.7 s	5.0 s

Full Unlighthouse report →