From dfa95cf560440c7f82944bb0eec0c7bd24c8f5b2 Mon Sep 17 00:00:00 2001
From: Gustavo Valverde <g.valverde02@gmail.com>
Date: Tue, 11 Aug 2026 14:53:12 -0400
Subject: [PATCH] fix(cli): limit version alignment to release train

---
 docs/content/docs/concepts/cli.mdx   |  2 +-
 packages/cli/src/commands/upgrade.ts | 39 +++++++++++++++++++++++++---
 packages/cli/test/upgrade.test.ts    | 16 ++++++++++++
 3 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/docs/content/docs/concepts/cli.mdx b/docs/content/docs/concepts/cli.mdx
index 542c1d0702..e845c5dc1b 100644
--- a/docs/content/docs/concepts/cli.mdx
+++ b/docs/content/docs/concepts/cli.mdx
@@ -78,7 +78,7 @@ npx auth@latest init
 
 ## Upgrade
 
-The `upgrade` command updates older `better-auth` and official `@better-auth/*` dependencies to the version of the CLI being run. Dependencies at the same or a newer version are left unchanged.
+The `upgrade` command updates older `better-auth` dependencies and official `@better-auth/*` packages that participate in the synchronized release train to the version of the CLI being run. It compares the minimum version allowed by each `package.json` specifier; specifiers whose minimum is the same or newer are left unchanged. Independently versioned packages, such as `@better-auth/utils`, are not changed.
 
 ```package-install title="Terminal"
 npx auth@latest upgrade
diff --git a/packages/cli/src/commands/upgrade.ts b/packages/cli/src/commands/upgrade.ts
index cc388ad5ba..830ffd78c5 100644
--- a/packages/cli/src/commands/upgrade.ts
+++ b/packages/cli/src/commands/upgrade.ts
@@ -11,8 +11,33 @@ import { getPackageInfo } from "../utils/get-package-info";
 import { installDependencies } from "../utils/install-dependencies";
 import { cliVersion } from "../version";
 
-function isBetterAuthPackage(name: string): boolean {
-	return name === "better-auth" || name.startsWith("@better-auth/");
+// Keep this aligned with the fixed release group in .changeset/config.json.
+const SYNCHRONIZED_BETTER_AUTH_PACKAGES = new Set([
+	"better-auth",
+	"@better-auth/api-key",
+	"@better-auth/cimd",
+	"@better-auth/core",
+	"@better-auth/drizzle-adapter",
+	"@better-auth/electron",
+	"@better-auth/expo",
+	"@better-auth/i18n",
+	"@better-auth/kysely-adapter",
+	"@better-auth/mcp",
+	"@better-auth/memory-adapter",
+	"@better-auth/mongo-adapter",
+	"@better-auth/oauth-provider",
+	"@better-auth/passkey",
+	"@better-auth/prisma-adapter",
+	"@better-auth/redis-storage",
+	"@better-auth/scim",
+	"@better-auth/sso",
+	"@better-auth/stripe",
+	"@better-auth/telemetry",
+	"@better-auth/test-utils",
+]);
+
+function isSynchronizedBetterAuthPackage(name: string): boolean {
+	return SYNCHRONIZED_BETTER_AUTH_PACKAGES.has(name);
 }
 
 interface UpgradeEntry {
@@ -57,12 +82,18 @@ export async function upgradeAction(opts: unknown) {
 	}[] = [];
 
 	for (const [name, version] of Object.entries(deps) as [string, string][]) {
-		if (isBetterAuthPackage(name) && !version.startsWith("workspace:")) {
+		if (
+			isSynchronizedBetterAuthPackage(name) &&
+			!version.startsWith("workspace:")
+		) {
 			candidates.push({ name, current: version, depType: "prod" });
 		}
 	}
 	for (const [name, version] of Object.entries(devDeps) as [string, string][]) {
-		if (isBetterAuthPackage(name) && !version.startsWith("workspace:")) {
+		if (
+			isSynchronizedBetterAuthPackage(name) &&
+			!version.startsWith("workspace:")
+		) {
 			candidates.push({ name, current: version, depType: "dev" });
 		}
 	}
diff --git a/packages/cli/test/upgrade.test.ts b/packages/cli/test/upgrade.test.ts
index f9caef10c1..892a234f48 100644
--- a/packages/cli/test/upgrade.test.ts
+++ b/packages/cli/test/upgrade.test.ts
@@ -82,4 +82,20 @@ describe("upgradeAction", () => {
 		expect(mockDetectPackageManager).not.toHaveBeenCalled();
 		expect(mockInstallDependencies).not.toHaveBeenCalled();
 	});
+
+	/**
+	 * @see https://github.com/better-auth/better-auth/pull/10760
+	 */
+	it("does not align independently versioned Better Auth packages", async () => {
+		mockGetPackageInfo.mockReturnValue({
+			dependencies: {
+				"@better-auth/utils": "^0.4.0",
+			},
+		});
+
+		await upgradeAction({ cwd: process.cwd(), yes: true });
+
+		expect(mockDetectPackageManager).not.toHaveBeenCalled();
+		expect(mockInstallDependencies).not.toHaveBeenCalled();
+	});
 });