feat: TRAC-926 upgrade: project resolution, download, and base ref

[chanceaclark]

Jira: TRAC-926

PR 3 of 4 for catalyst upgrade (LTRAC-956). Stacks on TRAC-925 (#3064).

What/Why?

Adds project layout detection, tarball download/cache, and base ref resolution — the infrastructure the CLI command action (PR 4) builds on.

Non-obvious decisions:

resolveProject: probes <gitRoot>/core → <gitRoot> → <cwd>/core → <cwd> in that order, preferring the package.json that already has catalyst.ref. A JSON.parse guard is added so a malformed candidate file is skipped rather than crashing the whole probe.

downloadCore: cache key uses repo__ref (double underscore) so bigcommerce/catalyst and a hypothetical bigcommerce_catalyst fork don't collide. Moving tags (latest, canary, alpha) are never cached. The core/ extraction has a flat-tarball fallback (insurance — all current tags are monorepo-shaped).

resolveBaseRef: the confirm() error is swallowed (.catch(() => false)) so a closed TTY in CI fails cleanly with the --from hint rather than a stack trace. Always pass --yes in non-interactive environments.

Testing

pnpm test upgrade.spec upgrade.action

upgrade.spec.ts additions: resolveProject (flat, nested, outside-git-repo), resolveBaseRef (catalyst.ref present, --from wins, inferred under --yes, unknown name defaults to catalyst-core family).

upgrade.action.spec.ts (new): action-level tests via upgrade.parseAsync() with mocked telemetry/logger/spinner. Covers: already-up-to-date short-circuit, dirty worktree rejects, invalid tag 404, --dry-run leaves project unchanged, missing ref with --yes, run-from-core/, dirty + --dry-run proceeds, staged-but-uncommitted rejects, --from bypasses prompt, --ref makeswift family.

Migration

No user-visible changes yet.

[vercel]

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

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 4d381b2

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	Minor

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 81b88df (2026-06-26).

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	87	83	98
Accessibility	95	92	95	98
Best Practices	100	100	100	100
SEO	88	100	100	100

Core Web Vitals

Metric	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
LCP	3.5 s	4.0 s	2.5 s	2.3 s
CLS	0.001	0	0.001	0
FCP	1.2 s	1.1 s	1.1 s	1.2 s
TBT	0 ms	0 ms	20 ms	0 ms
Max Potential FID	40 ms	30 ms	70 ms	50 ms
Time to Interactive	3.5 s	4.0 s	6.0 s	3.8 s

Full Unlighthouse report →