An feat local cli hydrogen patch

[andguy95]

WHY are these changes introduced?

Replaces: Shopify/cli#6827

Since @shopify/cli@3.83.0 (which upgraded oclif to v4), running shopify hydrogen commands in the Hydrogen monorepo no longer loads the local packages/cli source code. Instead, the bundled version inside @shopify/cli/dist is always used, making it impossible to test local CLI changes during development.

Root cause: The previous mechanism in @shopify/cli-kit's ShopifyConfig relied on overriding oclif's determinePriority instance method to make external plugin commands win over bundled ones. In oclif v4 (shipped in @shopify/cli@3.83.0), determinePriority became a standalone utility function, so the override silently stopped working. Additionally, the monorepo detection itself is not the best:

• Brittle regex detection — /(shopify|hydrogen)\/hydrogen/i tested against cwd() to guess if you're in the monorepo
• Synchronous subprocess — ran execSync('npm', ['prefix']) on every CLI invocation to find the project root
• Private API monkey-patching — relied on overriding oclif's private determinePriority method

This PR introduces a self-contained patch system within the Hydrogen monorepo that replaces all of that.

WHAT is this pull request doing?

Adds two scripts that enable local CLI development:

scripts/patch-cli.mjs — Patches node_modules/@shopify/cli/bin/run.js to load the local @shopify/cli-hydrogen plugin from packages/cli instead of the bundled version. The patch:

1. Detects the monorepo reliably by walking up from cwd() looking for packages/cli/package.json — no regex, no subprocesses
2. Uses oclif's pluginAdditions mechanism to register the local @shopify/cli-hydrogen as a core plugin, the same mechanism ShopifyConfig uses internally
3. Replaces bundled commands post-load by deleting hydrogen entries from oclif's internal _commands Map and re-inserting them from the local plugin via loadCommands() — this is the same strategy proposed in the upstream CLI fix (Fix custom-oclif-loader.ts hydrogen loader strategy for hydrogen-cli local development cli#6827) and works with oclif v4
4. Sets IGNORE_HYDROGEN_MONOREPO=1 so the current ShopifyConfig in @shopify/cli-kit doesn't attempt its own (broken) monorepo detection on top (NOTE: We can remove this if we update the custom-oclif-loader to become purely for letting users override cli-hydrogen with a different version from their project's node_modules.)
5. Is idempotent and version-agnostic — uses a marker comment to detect if already applied, writes the full file rather than applying a diff. This was a short coming with patch-packages or pnpm patch
6. Skipped in CI — only patches in local development environments
7. Shows a visible banner when active so developers know local source is being used

scripts/unpatch-cli.mjs — Restores run.js to its original content. Also idempotent.

How the patch interacts with the CLI plugin architecture:

shopify hydrogen dev (in monorepo)
  → patched run.js detects monorepo root
  → creates oclif Config with pluginAdditions pointing to monorepo root
  → oclif resolves @shopify/cli-hydrogen via workspace:* → packages/cli
  → post-load: bundled hydrogen commands deleted, local ones re-inserted
  → local packages/cli/dist/commands/ are used

For non-hydrogen commands or when running outside the monorepo, the standard @shopify/cli entrypoint is used unchanged.

Upstream impact: This patch is can replace Shopify/cli#6827, which fixes the custom-oclif-loader for local@shopify/cli-hydrogen development in the monorepo. The custom-oclif-loader can be simplified to remove all monorepo-specific logic (regex, npm prefix, IGNORE_HYDROGEN_MONOREPO), since this patch handles that case entirely within the Hydrogen repo.

HOW to test your changes?

1. Run pnpm install (or pnpm patch-cli if already installed)
2. Make a visible change in packages/cli/src/commands/hydrogen/dev.ts (e.g. add a console.log('test') in the run() method)
3. Build the CLI: pnpm run build --filter=@shopify/cli-hydrogen
4. From templates/skeleton, run npx shopify hydrogen dev
5. Verify:
   • The orange hydrogen-monorepo banner appears
   • Your console.log from step 2 is printed
6. Run pnpm unpatch-cli and repeat step 4 — the banner should not appear and your change should not be visible (bundled version is used)

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or noteworthy changes
• I've added tests to cover my changes
• I've added or updated the documentation

[shopify]

Oxygen deployed a preview of your an-feat-local-cli-hydrogen-patch branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	March 5, 2026 6:05 AM

Learn more about Hydrogen's GitHub integration.

[isaacroldan]

If this allows us to remove all the code to detect the hydrogen monorepo and load the plugin from the CLI repo, then great! love it!

It makes more sense for you to own this part :)