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

[alfonso-noriega]

What

When the autoupgrade postrun hook fires, it now passes {autoupgrade: true} to runCLIUpgrade. With that flag set, project-local installs are skipped — only global installs get upgraded silently in the background.

Explicit shopify upgrade invocations are unchanged: they still upgrade the project's package.json / lockfile.

Why

Mutating a user's package.json and lockfile in the background is surprising and produces noisy diffs in their app project. The postrun-triggered upgrade should be unobtrusive; users who want their project bumped can run shopify upgrade explicitly.

Changes

• runCLIUpgrade accepts a new optional RunCLIUpgradeOptions arg with an autoupgrade?: boolean field.
• When autoupgrade && !isGlobal, we skip with a debug log and return early.
• postrun.ts passes {autoupgrade: true}; shopify upgrade calls runCLIUpgrade() with no args (default false).
• Added a unit test covering the new skip path.
• Changeset (patch on @shopify/cli-kit).

Testing

pnpm vitest run src/public/node/upgrade.test.ts        # 29/29 ✓
pnpm vitest run src/public/node/hooks/postrun.test.ts  # 9/9 ✓
pnpm type-check                                         # ✓

[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/upgrade.d.ts

@@ -7,13 +7,26 @@ export { getAutoUpgradeEnabled, setAutoUpgradeEnabled };
  * @returns A string with the command to run, or undefined if the package manager cannot be determined.
  */
 export declare function cliInstallCommand(): string | undefined;
+/**
+ * Options for {@link runCLIUpgrade}.
+ */
+export interface RunCLIUpgradeOptions {
+    /**
+     *  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  so we don't surprise them by mutating
+     * their  / 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 declare function runCLIUpgrade(): Promise<void>;
+export declare function runCLIUpgrade(options?: RunCLIUpgradeOptions): Promise<void>;
 /**
  * Returns the version to auto-upgrade to, or undefined if auto-upgrade should be skipped.
  * Auto-upgrade is disabled by default and must be enabled via .