Merge pull request #7104 from Shopify/03-25-phase1_port_auto_upgrade_poc_to_main

[Phase 1] Port and productionize auto-upgrade POC to main

Author: alfonso-noriega

docs-shopify.dev/commands/upgrade.doc.ts

@@ -3,8 +3,8 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'upgrade',
-  description: `Shows details on how to upgrade Shopify CLI.`,
-  overviewPreviewDescription: `Shows details on how to upgrade Shopify CLI.`,
+  description: `Upgrades Shopify CLI using your package manager.`,
+  overviewPreviewDescription: `Upgrades Shopify CLI.`,
   type: 'command',
   isVisualComponent: false,
   defaultExample: {

docs-shopify.dev/generated/generated_docs_data.json

@@ -8125,8 +8125,8 @@
   },
   {
     "name": "upgrade",
-    "description": "Shows details on how to upgrade Shopify CLI.",
-    "overviewPreviewDescription": "Shows details on how to upgrade Shopify CLI.",
+    "description": "Upgrades Shopify CLI using your package manager.",
+    "overviewPreviewDescription": "Upgrades Shopify CLI.",
     "type": "command",
     "isVisualComponent": false,
     "defaultExample": {

packages/app/src/cli/services/app/config/link.test.ts

@@ -23,6 +23,9 @@ import {setPathValue} from '@shopify/cli-kit/common/object'
 
 vi.mock('./use.js')
 vi.mock('../../../prompts/config.js')
+vi.mock('@shopify/cli-kit/node/is-global', () => ({
+  currentProcessIsGlobal: () => false,
+}))
 vi.mock('../../../models/app/loader.js', async () => {
   const loader: any = await vi.importActual('../../../models/app/loader.js')
   return {

packages/app/src/cli/services/app/config/use.test.ts

@@ -14,6 +14,9 @@ vi.mock('../../local-storage.js')
 vi.mock('../../../models/app/loader.js')
 vi.mock('@shopify/cli-kit/node/ui')
 vi.mock('../../context.js')
+vi.mock('@shopify/cli-kit/node/is-global', () => ({
+  currentProcessIsGlobal: () => false,
+}))
 
 function mockContext(directory: string, configuration: Record<string, unknown>) {
   vi.mocked(getAppConfigurationContext).mockResolvedValue({
@@ -41,6 +44,7 @@ describe('use', () => {
         developerPlatformClient: testDeveloperPlatformClient(),
       }
       writeFileSync(joinPath(tmp, 'package.json'), '{}')
+      writeFileSync(joinPath(tmp, 'shopify.app.toml'), '')
 
       // When
       await use(options)

packages/app/src/cli/services/generate.test.ts

@@ -39,6 +39,9 @@ vi.mock('../prompts/generate/extension.js')
 vi.mock('../services/generate/extension.js')
 vi.mock('../services/context.js')
 vi.mock('./local-storage.js')
+vi.mock('@shopify/cli-kit/node/is-global', () => ({
+  currentProcessIsGlobal: () => false,
+}))
 
 afterEach(() => {
   mockAndCaptureOutput().clear()

packages/app/src/cli/services/init/init.ts

@@ -124,6 +124,7 @@ async function init(options: InitOptions) {
               await appendFile(joinPath(templateScaffoldDir, '.npmrc'), `auto-install-peers=true\n`)
               break
             }
+            case 'homebrew':
             case 'unknown':
               throw new UnknownPackageManagerError()
           }

packages/cli-kit/src/private/node/conf-store.ts

@@ -32,6 +32,7 @@ export interface ConfSchema {
   devSessionStore?: string
   currentDevSessionId?: string
   cache?: Cache
+  autoUpgradeEnabled?: boolean
 }
 
 let _instance: LocalStorage<ConfSchema> | undefined
@@ -265,6 +266,24 @@ export async function runWithRateLimit(options: RunWithRateLimitOptions, config
   return true
 }
 
+/**
+ * Get auto-upgrade preference.
+ *
+ * @returns Whether auto-upgrade is enabled, or undefined if never set.
+ */
+export function getAutoUpgradeEnabled(config: LocalStorage<ConfSchema> = cliKitStore()): boolean | undefined {
+  return config.get('autoUpgradeEnabled')
+}
+
+/**
+ * Set auto-upgrade preference.
+ *
+ * @param enabled - Whether auto-upgrade should be enabled.
+ */
+export function setAutoUpgradeEnabled(enabled: boolean, config: LocalStorage<ConfSchema> = cliKitStore()): void {
+  config.set('autoUpgradeEnabled', enabled)
+}
+
 export function getConfigStoreForPartnerStatus() {
   return new LocalStorage<Record<string, {status: true; checkedAt: string}>>({
     projectName: 'shopify-cli-kit-partner-status',

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

@@ -15,7 +15,7 @@ import {
 
 import {temporaryDirectory, temporaryDirectoryTask} from 'tempy'
 import {sep, join} from 'pathe'
-import {findUp as internalFindUp} from 'find-up'
+import {findUp as internalFindUp, findUpSync as internalFindUpSync} from 'find-up'
 import {minimatch} from 'minimatch'
 import fastGlobLib from 'fast-glob'
 import {
@@ -652,6 +652,23 @@ export async function findPathUp(
   return got ? normalizePath(got) : undefined
 }
 
+/**
+ * Find a file by walking parent directories.
+ *
+ * @param matcher - A pattern or an array of patterns to match a file name.
+ * @param options - Options for the search.
+ * @returns The first path found that matches or `undefined` if none could be found.
+ */
+export function findPathUpSync(
+  matcher: OverloadParameters<typeof internalFindUp>[0],
+  options: OverloadParameters<typeof internalFindUp>[1],
+): ReturnType<typeof internalFindUpSync> {
+  // findUp has odd typing
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const got = internalFindUpSync(matcher as any, options)
+  return got ? normalizePath(got) : undefined
+}
+
 export interface MatchGlobOptions {
   matchBase: boolean
   noglobstar: boolean

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

@@ -0,0 +1,95 @@
+import {autoUpgradeIfNeeded} from './postrun.js'
+import {mockAndCaptureOutput} from '../testing/output.js'
+import {getOutputUpdateCLIReminder, runCLIUpgrade, versionToAutoUpgrade} from '../upgrade.js'
+import {isMajorVersionChange} from '../version.js'
+import {describe, expect, test, vi, afterEach} from 'vitest'
+
+vi.mock('../upgrade.js', async (importOriginal) => {
+  const actual: any = await importOriginal()
+  return {
+    ...actual,
+    runCLIUpgrade: vi.fn(),
+    getOutputUpdateCLIReminder: vi.fn(),
+    versionToAutoUpgrade: vi.fn(),
+  }
+})
+
+vi.mock('../version.js', async (importOriginal) => {
+  const actual: any = await importOriginal()
+  return {
+    ...actual,
+    isMajorVersionChange: vi.fn(),
+  }
+})
+
+// Always execute the task so the rate limit doesn't interfere with tests
+vi.mock('../../../private/node/conf-store.js', async (importOriginal) => {
+  const actual: any = await importOriginal()
+  return {
+    ...actual,
+    runAtMinimumInterval: vi.fn(async (_key: string, _interval: object, task: () => Promise<void>) => {
+      await task()
+      return true
+    }),
+  }
+})
+
+afterEach(() => {
+  mockAndCaptureOutput().clear()
+})
+
+describe('autoUpgradeIfNeeded', () => {
+  test('runs the upgrade when versionToAutoUpgrade returns a version', async () => {
+    // Given
+    vi.mocked(versionToAutoUpgrade).mockReturnValue('3.91.0')
+    vi.mocked(runCLIUpgrade).mockResolvedValue()
+
+    // When
+    await autoUpgradeIfNeeded()
+
+    // Then
+    expect(runCLIUpgrade).toHaveBeenCalled()
+  })
+
+  test('falls back to warning when the upgrade fails', async () => {
+    // Given
+    const outputMock = mockAndCaptureOutput()
+    vi.mocked(versionToAutoUpgrade).mockReturnValue('3.91.0')
+    vi.mocked(runCLIUpgrade).mockRejectedValue(new Error('upgrade failed'))
+    const installReminder = '💡 Version 3.91.0 available! Run `npm install @shopify/cli@latest`'
+    vi.mocked(getOutputUpdateCLIReminder).mockReturnValue(installReminder)
+
+    // When
+    await autoUpgradeIfNeeded()
+
+    // Then
+    expect(outputMock.warn()).toMatch(installReminder)
+  })
+
+  test('does nothing when versionToAutoUpgrade returns undefined', async () => {
+    // Given
+    vi.mocked(versionToAutoUpgrade).mockReturnValue(undefined)
+
+    // When
+    await autoUpgradeIfNeeded()
+
+    // Then
+    expect(runCLIUpgrade).not.toHaveBeenCalled()
+  })
+
+  test('shows warning instead of upgrading for a major version change', async () => {
+    // Given
+    const outputMock = mockAndCaptureOutput()
+    vi.mocked(versionToAutoUpgrade).mockReturnValue('4.0.0')
+    vi.mocked(isMajorVersionChange).mockReturnValue(true)
+    const installReminder = '💡 Version 4.0.0 available! Run `npm install @shopify/cli@latest`'
+    vi.mocked(getOutputUpdateCLIReminder).mockReturnValue(installReminder)
+
+    // When
+    await autoUpgradeIfNeeded()
+
+    // Then
+    expect(runCLIUpgrade).not.toHaveBeenCalled()
+    expect(outputMock.warn()).toMatch(installReminder)
+  })
+})

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

@@ -1,9 +1,13 @@
 import {postrun as deprecationsHook} from './deprecations.js'
 import {reportAnalyticsEvent} from '../analytics.js'
-import {outputDebug} from '../output.js'
+import {outputDebug, outputWarn} from '../output.js'
+import {getOutputUpdateCLIReminder, runCLIUpgrade, versionToAutoUpgrade, warnIfUpgradeAvailable} from '../upgrade.js'
+import {inferPackageManagerForGlobalCLI} from '../is-global.js'
 import BaseCommand from '../base-command.js'
 import * as metadata from '../metadata.js'
-
+import {runAtMinimumInterval} from '../../../private/node/conf-store.js'
+import {CLI_KIT_VERSION} from '../../common/version.js'
+import {isMajorVersionChange} from '../version.js'
 import {Command, Hook} from '@oclif/core'
 
 let postRunHookCompleted = false
@@ -26,6 +30,64 @@ export const hook: Hook.Postrun = async ({config, Command}) => {
   const command = Command.id.replace(/:/g, ' ')
   outputDebug(`Completed command ${command}`)
   postRunHookCompleted = true
+
+  if (!Command.id?.includes('upgrade') && !Command.id?.startsWith('notifications')) {
+    try {
+      await autoUpgradeIfNeeded()
+      // eslint-disable-next-line no-catch-all/no-catch-all
+    } catch (error) {
+      outputDebug(`Auto-upgrade check failed: ${error}`)
+    }
+  }
+}
+
+/**
+ * Auto-upgrades the CLI after a command completes, if a newer version is available.
+ * The entire flow is rate-limited to once per day unless forced via SHOPIFY_CLI_FORCE_AUTO_UPGRADE.
+ *
+ * @returns Resolves when the upgrade attempt (or fallback warning) is complete.
+ */
+export async function autoUpgradeIfNeeded(): Promise<void> {
+  const newerVersion = versionToAutoUpgrade()
+  if (!newerVersion) {
+    await warnIfUpgradeAvailable()
+    return
+  }
+
+  const forced = process.env.SHOPIFY_CLI_FORCE_AUTO_UPGRADE === '1'
+
+  // SHOPIFY_CLI_FORCE_AUTO_UPGRADE bypasses the daily rate limit so tests and intentional upgrades always run.
+  if (forced) {
+    await performAutoUpgrade(newerVersion)
+  } else {
+    // Rate-limit the entire upgrade flow to once per day to avoid repeated attempts and major-version warnings.
+    await runAtMinimumInterval('auto-upgrade', {days: 1}, async () => {
+      await performAutoUpgrade(newerVersion)
+    })
+  }
+}
+
+async function performAutoUpgrade(newerVersion: string): Promise<void> {
+  if (isMajorVersionChange(CLI_KIT_VERSION, newerVersion)) {
+    return outputWarn(getOutputUpdateCLIReminder(newerVersion))
+  }
+
+  try {
+    await runCLIUpgrade()
+    // eslint-disable-next-line no-catch-all/no-catch-all
+  } catch (error) {
+    const errorMessage = `Auto-upgrade failed: ${error}`
+    outputDebug(errorMessage)
+    outputWarn(getOutputUpdateCLIReminder(newerVersion))
+    // Report to Observe as a handled error without showing anything extra to the user
+    const {sendErrorToBugsnag} = await import('../error-handler.js')
+    const enrichedError = Object.assign(new Error(errorMessage), {
+      packageManager: inferPackageManagerForGlobalCLI(),
+      platform: process.platform,
+      cliVersion: CLI_KIT_VERSION,
+    })
+    await sendErrorToBugsnag(enrichedError, 'expected_error')
+  }
 }
 
 /**