`@astrojs/upgrade` beta installation will downgrade packages to lower beta versions

[kydecker]

Astro Info

Astro                    v7.0.0-beta.3
Node                     v24.14.0
System                   macOS (arm64)
Package Manager          pnpm
Output                   static
Adapter                  @astrojs/cloudflare
Integrations             @astrojs/sitemap
                         @astrojs/mdx
                         @astrojs/react

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

I attempted the v7.0 beta upgrade with pnpm dlx @astrojs/upgrade beta and it reverted several packages to lower versions:

• @astrojs/markdown-remark from 7.2.0 (latest) to 7.0.0-beta.11
• @astrojs/cloudflare from 13.7.0 (latest) to 13.0.0-beta.14
• @astrojs/react from 5.0.7 (latest) to 5.0.0-beta.4
• @astrojs/rss from 4.0.18 (latest) to 4.0.15-beta.4
• @astrojs/sitemap to 3.7.3 (latest) to 3.6.1-beta.3

Seems like a bug where when a -beta flag is detected in the package, it will be chosen and installed even if the installation would downgrade the version number.

What's the expected result?

The beta flag of @astrojs/upgrade does not violate semantic versioning / does not downgrade packages.

Link to Minimal Reproducible Example

N/A

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

• Reproduced: Yes — confirmed that the beta dist-tag for multiple @astrojs/* packages (cloudflare, react, sitemap, rss, markdown-remark) points to versions older than their current stable releases, causing @astrojs/upgrade beta to downgrade them.
• Exploration: Yes — View branch
• Unit Test: Yes — packages/upgrade/test/verify.test.ts (does not downgrade packages when beta dist-tag is older than installed version)
• Priority: P4: important. This affects anyone running @astrojs/upgrade beta (or any prerelease tag) when companion packages have stable releases newer than their beta dist-tag versions — which is the case for most @astrojs/* packages right now during the v7 beta cycle.

The root cause is in resolveTargetVersion() in packages/upgrade/src/actions/verify.ts. When resolving a dist-tag like beta, the function unconditionally uses whatever version the tag points to without checking if it would be a downgrade from the currently installed version. This was an oversight from the initial implementation — the scenario where a beta dist-tag points to a version older than the current stable release was never considered.

I found a potential fix for this issue. The fix adds a semver comparison (semverGt) after resolving the dist-tag version. If the installed version is newer than the dist-tag version, it falls back to the latest dist-tag instead of downgrading. This ensures astro itself still upgrades to 7.0.0-beta.3 while companion packages like @astrojs/cloudflare stay on their current stable versions.

Full Triage Report

Triage Report: Issue #17024

Issue Summary

Title: @astrojs/upgrade beta installation will downgrade packages to lower beta versions

Author: kydecker

Description: Running pnpm dlx @astrojs/upgrade beta reverts several @astrojs/* packages to older beta versions instead of keeping newer stable versions. For example:

• @astrojs/cloudflare from 13.7.0 (latest) to 13.0.0-beta.14
• @astrojs/react from 5.0.7 (latest) to 5.0.0-beta.4
• @astrojs/rss from 4.0.18 (latest) to 4.0.15-beta.4
• @astrojs/sitemap from 3.7.3 (latest) to 3.6.1-beta.3
• @astrojs/markdown-remark from 7.2.0 (latest) to 7.0.0-beta.11

Expected: The beta flag should not downgrade packages. If the beta dist-tag version is lower than the currently installed stable version, the package should be left as-is (or upgraded to the latest stable).

Environment:

• Astro v7.0.0-beta.3
• Node v24.14.0
• macOS (arm64)
• pnpm

Reproduction Status: ✅ REPRODUCED

Reproduction Steps

1. Created a project with current latest stable versions of several @astrojs/* packages
2. Queried the npm registry for beta dist-tags of these packages
3. Confirmed that the beta dist-tag for many packages points to versions lower than their current latest stable releases

Registry Data (verified 2026-06-10)

Package	Latest (installed)	Beta dist-tag	Result
astro	6.4.5	7.0.0-beta.3	✅ OK (upgrade)
@astrojs/cloudflare	13.7.0	13.0.0-beta.14	⚠️ DOWNGRADE
@astrojs/react	5.0.7	5.0.0-beta.4	⚠️ DOWNGRADE
@astrojs/sitemap	3.7.3	3.6.1-beta.3	⚠️ DOWNGRADE
@astrojs/rss	4.0.18	4.0.15-beta.4	⚠️ DOWNGRADE
@astrojs/mdx	6.0.3	7.0.0-alpha.1	✅ OK (upgrade)

Root Cause Analysis

The bug is in packages/upgrade/src/actions/verify.ts, specifically in the resolveTargetVersion() function.

The problematic logic (lines ~146-153):

let version = distTags[packageInfo.targetVersion]; // e.g., distTags['beta']
if (version) {
    packageInfo.tag = packageInfo.targetVersion;
    packageInfo.targetVersion = version;
} else {
    packageInfo.targetVersion = 'latest';
    version = distTags.latest;
}

When the beta dist-tag exists for a package, the code unconditionally uses that version as the target. There is no comparison between the resolved beta version and the currently installed version to check if it would be a downgrade.

Fix

File: packages/upgrade/src/actions/verify.ts

Added a downgrade guard in resolveTargetVersion(). After resolving the version from a dist-tag, the fix compares it against the currently installed version using semverGt. If the installed version is newer, the function falls back to the latest dist-tag instead.

 let version = distTags[packageInfo.targetVersion];
 if (version) {
-    packageInfo.tag = packageInfo.targetVersion;
-    packageInfo.targetVersion = version;
+    const currentCoerced = semverCoerce(packageInfo.currentVersion);
+    const targetParsed = semverParse(version);
+    // Only use the dist-tag version if it's actually an upgrade.
+    // If the dist-tag points to a version older than the installed one, fall back to latest.
+    if (currentCoerced && targetParsed && semverGt(currentCoerced, targetParsed)) {
+        packageInfo.targetVersion = 'latest';
+        version = distTags.latest;
+    } else {
+        packageInfo.tag = packageInfo.targetVersion;
+        packageInfo.targetVersion = version;
+    }
 } else {

Verification

• ✅ All 25 tests pass (24 existing + 1 new)
• ✅ astro core correctly upgrades to beta when beta is newer
• ✅ Companion packages correctly fall back to latest when beta is older

Changeset

Created .changeset/rare-spiders-relax.md with a patch bump for @astrojs/upgrade.

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.