From 790b651bc1fd52bd4686a5b0e38d9c42d41b37f6 Mon Sep 17 00:00:00 2001
From: andrewmcgov <andrew.mcgoveran@shopify.com>
Date: Wed, 12 Aug 2026 16:40:26 -0400
Subject: [PATCH] Support worktrees when generating checkout docs

Assisted-By: devx/73a9dbe2-f996-454a-bafa-ea156839ac0a
---
 .../docs/surfaces/build-doc-shared.mjs        | 14 ++++--
 .../build-docs-resolve-shopify-dev-path.mjs   | 12 +++++
 .../docs/surfaces/checkout/build-docs.sh      | 50 +++++++------------
 3 files changed, 41 insertions(+), 35 deletions(-)
 create mode 100644 packages/ui-extensions/docs/surfaces/checkout/build-docs-resolve-shopify-dev-path.mjs

diff --git a/packages/ui-extensions/docs/surfaces/build-doc-shared.mjs b/packages/ui-extensions/docs/surfaces/build-doc-shared.mjs
index 497a48945e..f860919e73 100644
--- a/packages/ui-extensions/docs/surfaces/build-doc-shared.mjs
+++ b/packages/ui-extensions/docs/surfaces/build-doc-shared.mjs
@@ -6,7 +6,10 @@ import path from 'path';
 import readline from 'readline/promises';
 import process, {stdin as input, stdout as output} from 'process';
 
-export const resolveShopifyDevPath = async (rootPath) => {
+export const resolveShopifyDevPath = async (
+  rootPath,
+  {promptInput = input, promptOutput = output} = {},
+) => {
   const normalizeShopifyDevSourceRoot = (candidatePath) => {
     if (!candidatePath) return null;
 
@@ -25,7 +28,9 @@ export const resolveShopifyDevPath = async (rootPath) => {
     // Candidate might be the zone path itself (.../areas/platforms/shopify-dev)
     if (absolutePath.endsWith(path.normalize('areas/platforms/shopify-dev'))) {
       const sourceRootPath = path.resolve(absolutePath, '../../..');
-      if (existsSync(path.join(sourceRootPath, 'areas/platforms/shopify-dev'))) {
+      if (
+        existsSync(path.join(sourceRootPath, 'areas/platforms/shopify-dev'))
+      ) {
         return sourceRootPath;
       }
     }
@@ -48,7 +53,10 @@ export const resolveShopifyDevPath = async (rootPath) => {
 
   const defaultPath = path.resolve(rootPath, '../../../world');
 
-  const rl = readline.createInterface({input, output});
+  const rl = readline.createInterface({
+    input: promptInput,
+    output: promptOutput,
+  });
   const answer = (
     await rl.question(
       `\n\x1b[33m⚠️  Could not find a world/shopify-dev repo near:\x1b[0m \x1b[1m${defaultPath}\x1b[0m\n\x1b[32mPlease provide the absolute path to your world repo, shopify-dev repo, source root, or areas/platforms/shopify-dev folder:\x1b[0m `,
diff --git a/packages/ui-extensions/docs/surfaces/checkout/build-docs-resolve-shopify-dev-path.mjs b/packages/ui-extensions/docs/surfaces/checkout/build-docs-resolve-shopify-dev-path.mjs
new file mode 100644
index 0000000000..e365872e53
--- /dev/null
+++ b/packages/ui-extensions/docs/surfaces/checkout/build-docs-resolve-shopify-dev-path.mjs
@@ -0,0 +1,12 @@
+/* eslint-disable no-undef, no-console */
+import {stderr} from 'process';
+import {fileURLToPath} from 'url';
+
+import {resolveShopifyDevPath} from '../build-doc-shared.mjs';
+
+const rootPath = fileURLToPath(new URL('../../..', import.meta.url));
+const shopifyDevPath = await resolveShopifyDevPath(rootPath, {
+  promptOutput: stderr,
+});
+
+console.log(shopifyDevPath);
diff --git a/packages/ui-extensions/docs/surfaces/checkout/build-docs.sh b/packages/ui-extensions/docs/surfaces/checkout/build-docs.sh
index faa397cede..351daf6c00 100644
--- a/packages/ui-extensions/docs/surfaces/checkout/build-docs.sh
+++ b/packages/ui-extensions/docs/surfaces/checkout/build-docs.sh
@@ -103,39 +103,25 @@ echo "  Checkout UI extensions: $PWD/$DOCS_PATH/generated"
 echo "  targets.json: $PWD/$DOCS_PATH/generated/targets.json"
 echo ""
 
-copy_generated_docs_to_shopify_dev() {
-# Copy the generated docs to shopify-dev
-if [ -d $SHOPIFY_DEV_PATH ]; then
-  SHOPIFY_DEV_DEST=$SHOPIFY_DEV_PATH/areas/platforms/shopify-dev/db/data/docs/templated_apis/checkout_extensions/$API_VERSION
-  mkdir -p $SHOPIFY_DEV_DEST
-  cp ./$DOCS_PATH/generated/* $SHOPIFY_DEV_DEST
-
-  # Replace 'latest' with the exact API version in relative doc links
-  run_sed \
-    "s/\/docs\/api\/checkout-ui-extensions\/latest/\/docs\/api\/checkout-ui-extensions\/$API_VERSION/gi" \
-    "$SHOPIFY_DEV_DEST/generated_docs_data_v2.json"
-  sed_exit=$?
-  if [ $sed_exit -ne 0 ]; then
-    fail_and_exit $sed_exit
-  fi
-
-  echo "Docs: https://shopify-dev.shop.dev/docs/api/checkout-ui-extensions"
-else
-  echo "Not copying docs to shopify-dev because it was not found at $SHOPIFY_DEV_PATH."
+# Resolve shopify-dev using the same worktree-aware logic as the other docs scripts.
+# SHOPIFY_DEV_PATH and WORLD_PATH take precedence over the default world worktree.
+SHOPIFY_DEV_PATH=$(node ./$DOCS_PATH/build-docs-resolve-shopify-dev-path.mjs)
+resolve_exit=$?
+if [ $resolve_exit -ne 0 ]; then
+  fail_and_exit $resolve_exit
 fi
-}
 
-# Try candidate paths for shopify-dev / world repo in order of preference
-for SHOPIFY_DEV_PATH in \
-  "$HOME/world/trees/root/src" \
-  "../../../shopify-dev" \
-  "$HOME/src/github.com/Shopify/shopify-dev"; do
-  if [ -d "$SHOPIFY_DEV_PATH" ]; then
-    copy_generated_docs_to_shopify_dev
-    break
-  fi
-done
+SHOPIFY_DEV_DEST="$SHOPIFY_DEV_PATH/areas/platforms/shopify-dev/db/data/docs/templated_apis/checkout_extensions/$API_VERSION"
+mkdir -p "$SHOPIFY_DEV_DEST"
+cp ./$DOCS_PATH/generated/* "$SHOPIFY_DEV_DEST"
 
-if [ ! -d "$SHOPIFY_DEV_PATH" ]; then
-  echo "Not copying docs to shopify-dev because no repo was found."
+# Replace 'latest' with the exact API version in relative doc links
+run_sed \
+  "s/\/docs\/api\/checkout-ui-extensions\/latest/\/docs\/api\/checkout-ui-extensions\/$API_VERSION/gi" \
+  "$SHOPIFY_DEV_DEST/generated_docs_data_v2.json"
+sed_exit=$?
+if [ $sed_exit -ne 0 ]; then
+  fail_and_exit $sed_exit
 fi
+
+echo "Docs: https://shopify-dev.shop.dev/docs/api/checkout-ui-extensions"