[Phase 1] Default-on auto-upgrade with SHOPIFY_CLI_NO_AUTO_UPGRADE escape hatch

[alfonso-noriega]

Summary

• Stacks on [Phase 1] Port auto-upgrade POC to main #6999 (Phase 1 auto-upgrade PoC port to main)
• Closes shop/issues-develop#22364

Auto-upgrade is now on by default. Users who want to opt out can set SHOPIFY_CLI_NO_AUTO_UPGRADE=1. CI environments remain protected via the existing isCI() guard.

Changes

• packages/cli-kit/src/public/node/upgrade.ts: Removed getAutoUpgradeEnabled() opt-in guard from versionToAutoUpgrade(). Added SHOPIFY_CLI_NO_AUTO_UPGRADE=1 opt-out check. SHOPIFY_CLI_FORCE_AUTO_UPGRADE=1 still bypasses all guards (for testing). Removed the now-unused promptAutoUpgrade() export.
• packages/cli/src/cli/commands/upgrade.ts: Removed promptAutoUpgrade() call — the upgrade command now runs the upgrade directly without prompting.
• packages/cli-kit/src/private/node/conf-store.ts: Removed autoUpgradeEnabled from ConfSchema, and removed getAutoUpgradeEnabled() / setAutoUpgradeEnabled() exports.
• .changeset/auto-upgrade-escape-hatch.md: Added patch changeset for both @shopify/cli-kit and @shopify/cli.

Guard order in versionToAutoUpgrade()

1. No newer version cached → return undefined
2. SHOPIFY_CLI_FORCE_AUTO_UPGRADE=1 → return newerVersion (bypasses all other guards)
3. SHOPIFY_CLI_NO_AUTO_UPGRADE=1 → return undefined
4. isCI() → return undefined
5. isPreReleaseVersion() → return undefined
6. Return newerVersion

Test plan

• packages/cli-kit/src/public/node/upgrade.test.ts — 10 tests pass, including new returns undefined when SHOPIFY_CLI_NO_AUTO_UPGRADE is set and FORCE_AUTO_UPGRADE overrides NO_AUTO_UPGRADE
• packages/cli/src/cli/commands/upgrade.test.ts — 1 test passes, verifies runCLIUpgrade is called directly

🤖 Generated with Claude Code

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/public/node/fs.d.ts

@@ -1,6 +1,6 @@
 import { OverloadParameters } from '../../private/common/ts/overloaded-parameters.js';
 import { RandomNameFamily } from '../common/string.js';
-import { findUp as internalFindUp } from 'find-up';
+import { findUp as internalFindUp, findUpSync as internalFindUpSync } from 'find-up';
 import { ReadStream, WriteStream } from 'fs';
 import type { Pattern, Options as GlobOptions } from 'fast-glob';
 /**
@@ -335,6 +335,7 @@ export declare function defaultEOL(): EOL;
  * @returns The first path found that matches or  if none could be found.
  */
 export declare function findPathUp(matcher: OverloadParameters<typeof internalFindUp>[0], options: OverloadParameters<typeof internalFindUp>[1]): ReturnType<typeof internalFindUp>;
+export declare function findPathUpSync(matcher: OverloadParameters<typeof internalFindUp>[0], options: OverloadParameters<typeof internalFindUp>[1]): ReturnType<typeof internalFindUpSync>;
 export interface MatchGlobOptions {
     matchBase: boolean;
     noglobstar: boolean;

packages/cli-kit/dist/public/node/is-global.d.ts

@@ -26,6 +26,14 @@ export declare function installGlobalCLIPrompt(): Promise<InstallGlobalCLIPrompt
  * Infers the package manager used by the global CLI.
  *
  * @param argv - The arguments passed to the process.
+ * @param env - The environment variables of the process.
  * @returns The package manager used by the global CLI.
  */
-export declare function inferPackageManagerForGlobalCLI(argv?: string[]): PackageManager;
\ No newline at end of file
+export declare function inferPackageManagerForGlobalCLI(argv?: string[], env?: NodeJS.ProcessEnv): PackageManager;
+/**
+ * Returns the project directory for the given path.
+ *
+ * @param directory - The path to the directory to get the project directory for.
+ * @returns The project directory for the given path.
+ */
+export declare function getProjectDir(directory: string): string | undefined;
\ No newline at end of file

packages/cli-kit/dist/public/node/node-package-manager.d.ts

@@ -25,7 +25,7 @@ export type DependencyType = 'dev' | 'prod' | 'peer';
 /**
  * A union that represents the package managers available.
  */
-export declare const packageManager: readonly ["yarn", "npm", "pnpm", "bun", "unknown"];
+export declare const packageManager: readonly ["yarn", "npm", "pnpm", "bun", "unknown", "homebrew"];
 export type PackageManager = (typeof packageManager)[number];
 /**
  * Returns an abort error that's thrown when the package manager can't be determined.

packages/cli-kit/dist/public/node/upgrade.d.ts

@@ -2,9 +2,24 @@
  * Utility function for generating an install command for the user to run
  * to install an updated version of Shopify CLI.
  *
- * @returns A string with the command to run.
+ * @returns A string with the command to run, or undefined if the package manager cannot be determined.
  */
-export declare function cliInstallCommand(): string;
+export declare function cliInstallCommand(): string | undefined;
+/**
+ * Runs the CLI upgrade using the appropriate package manager.
+ * Determines the install command and executes it.
+ *
+ * @throws Error if the package manager or command cannot be determined.
+ */
+export declare function runCLIUpgrade(): Promise<void>;
+/**
+ * Returns the version to auto-upgrade to, or undefined if auto-upgrade should be skipped.
+ * Auto-upgrade is on by default. Set SHOPIFY_CLI_NO_AUTO_UPGRADE=1 to opt out.
+ * Also skips for CI, pre-release versions, or when no newer version is available.
+ *
+ * @returns The version string to upgrade to, or undefined if no upgrade should happen.
+ */
+export declare function versionToAutoUpgrade(): string | undefined;
 /**
  * Generates a message to remind the user to update the CLI.
  *

packages/cli-kit/dist/public/node/version.d.ts

@@ -18,4 +18,13 @@ export declare function globalCLIVersion(): Promise<string | undefined>;
  * @param version - The version to check.
  * @returns True if the version is a pre-release version.
  */
-export declare function isPreReleaseVersion(version: string): boolean;
\ No newline at end of file
+export declare function isPreReleaseVersion(version: string): boolean;
+/**
+ * Checks if there is a major version change between two versions.
+ * Pre-release versions (0.0.0-*) are treated as not having a major version change.
+ *
+ * @param currentVersion - The current version.
+ * @param newerVersion - The newer version to compare against.
+ * @returns True if there is a major version change.
+ */
+export declare function isMajorVersionChange(currentVersion: string, newerVersion: string): boolean;
\ No newline at end of file

packages/cli-kit/dist/public/node/hooks/postrun.d.ts

@@ -5,4 +5,10 @@ import { Hook } from '@oclif/core';
  * @returns Whether post run hook has completed.
  */
 export declare function postRunHookHasCompleted(): boolean;
-export declare const hook: Hook.Postrun;
\ No newline at end of file
+export declare const hook: Hook.Postrun;
+/**
+ * Auto-upgrades the CLI after a command completes, if a newer version is available.
+ *
+ * @returns Resolves when the upgrade attempt (or fallback warning) is complete.
+ */
+export declare function autoUpgradeIfNeeded(): Promise<void>;
\ No newline at end of file

packages/cli-kit/dist/public/node/hooks/prerun.d.ts

@@ -11,6 +11,7 @@ export declare function parseCommandContent(cmdInfo: {
     pluginAlias?: string;
 }): CommandContent;
 /**
- * Warns the user if there is a new version of the CLI available
+ * Triggers a background check for a newer CLI version (non-blocking).
+ * The result is cached and consumed by the postrun hook for auto-upgrade.
  */
-export declare function warnOnAvailableUpgrade(): Promise<void>;
\ No newline at end of file
+export declare function checkForNewVersionInBackground(): void;
\ No newline at end of file