Auto-upgrade: skip project-local installs in postrun hook

When the postrun hook triggers auto-upgrade, it now passes `{autoupgrade: true}`
to `runCLIUpgrade`. With that flag set, project-local installs are skipped so
the silent background flow doesn't surprise users by mutating their app's
`package.json` / lockfile.

Explicit `shopify upgrade` invocations still upgrade local projects \u2014 this
only changes the implicit postrun-triggered path.

Author: alfonso-noriega

.changeset/autoupgrade-skip-local-projects.md

@@ -0,0 +1,5 @@
+---
+'@shopify/cli-kit': patch
+---
+
+Auto-upgrade now skips project-local installs when triggered by the postrun hook. Running `shopify upgrade` explicitly still upgrades the project's `package.json` / lockfile; only the silent background flow is affected, so users aren't surprised by unsolicited diffs in their app project.

packages/cli-kit/src/public/node/hooks/postrun.ts

@@ -96,7 +96,7 @@ async function performAutoUpgrade(newerVersion: string): Promise<void> {
   }
 
   try {
-    await runCLIUpgrade()
+    await runCLIUpgrade({autoupgrade: true})
     await metadata.addPublicMetadata(() => ({env_auto_upgrade_success: true}))
     // eslint-disable-next-line no-catch-all/no-catch-all
   } catch (error) {

packages/cli-kit/src/public/node/upgrade.test.ts

@@ -208,6 +208,17 @@ describe('runCLIUpgrade', () => {
     // Then
     expect(exec).not.toHaveBeenCalled()
   })
+
+  test('skips project-local upgrade when called from the auto-upgrade postrun hook', async () => {
+    // Given
+    vi.mocked(currentProcessIsGlobal).mockReturnValue(false)
+
+    // When
+    await runCLIUpgrade({autoupgrade: true})
+
+    // Then
+    expect(exec).not.toHaveBeenCalled()
+  })
 })
 
 describe('versionToAutoUpgrade', () => {

packages/cli-kit/src/public/node/upgrade.ts

@@ -41,13 +41,27 @@ export function cliInstallCommand(): string | undefined {
   }
 }
 
+/**
+ * Options for {@link runCLIUpgrade}.
+ */
+export interface RunCLIUpgradeOptions {
+  /**
+   * `true` when the upgrade is being triggered by the automatic postrun hook.
+   * In that case we skip project-local upgrades — those should only happen when the
+   * user explicitly runs `shopify upgrade` so we don't surprise them by mutating
+   * their `package.json` / lockfile in the background.
+   */
+  autoupgrade?: boolean
+}
+
 /**
  * Runs the CLI upgrade using the appropriate package manager.
  * Determines the install command and executes it.
  *
+ * @param options - See {@link RunCLIUpgradeOptions}.
  * @throws AbortError if the package manager or command cannot be determined.
  */
-export async function runCLIUpgrade(): Promise<void> {
+export async function runCLIUpgrade(options: RunCLIUpgradeOptions = {}): Promise<void> {
   // Path where the current project is (app/hydrogen)
   const path = sniffForPath() ?? cwd()
   const projectDir = getProjectDir(path)
@@ -61,6 +75,15 @@ export async function runCLIUpgrade(): Promise<void> {
     return
   }
 
+  // When triggered by the automatic postrun hook, skip project-local upgrades.
+  // Bumping `package.json` / lockfile silently in the background would surprise users
+  // and produce noisy diffs; explicit `shopify upgrade` invocations still upgrade the
+  // local project.
+  if (options.autoupgrade && !isGlobal) {
+    outputDebug('Auto-upgrade: Skipping project-local upgrade triggered by the postrun hook.')
+    return
+  }
+
   // Generate the install command for the global CLI and execute it
   if (isGlobal) {
     const installCommand = cliInstallCommand()