From a727f509a3e7deaa9bb22b790fecc4839c518c4f Mon Sep 17 00:00:00 2001
From: Gonzalo Riestra <gonzalo.riestra@shopify.com>
Date: Mon, 25 May 2026 14:23:44 +0200
Subject: [PATCH] Add theme dev reconciliation strategy flag

---
 .../interfaces/theme-dev.interface.ts         |  6 ++
 .../generated/generated_docs_data_v2.json     | 11 +++-
 packages/cli/README.md                        |  9 ++-
 packages/cli/oclif.manifest.json              | 13 ++++
 packages/theme/src/cli/commands/theme/dev.ts  |  9 ++-
 packages/theme/src/cli/services/dev.ts        |  9 ++-
 .../theme-environment/remote-theme-watcher.ts |  2 +
 .../theme-environment.test.ts                 |  2 +-
 .../theme-environment/theme-environment.ts    |  1 +
 .../theme-reconciliation.test.ts              | 61 +++++++++++++++++++
 .../theme-environment/theme-reconciliation.ts | 45 +++++++++++++-
 .../cli/utilities/theme-environment/types.ts  | 10 +++
 12 files changed, 170 insertions(+), 8 deletions(-)

diff --git a/docs-shopify.dev/commands/interfaces/theme-dev.interface.ts b/docs-shopify.dev/commands/interfaces/theme-dev.interface.ts
index d1388b0d3a4..e81f4fce843 100644
--- a/docs-shopify.dev/commands/interfaces/theme-dev.interface.ts
+++ b/docs-shopify.dev/commands/interfaces/theme-dev.interface.ts
@@ -100,6 +100,12 @@ export interface themedev {
    */
   '--port <value>'?: string
 
+  /**
+   * How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.
+   * @environment SHOPIFY_FLAG_RECONCILIATION_STRATEGY
+   */
+  '--reconciliation-strategy <value>'?: string
+
   /**
    * Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).
    * @environment SHOPIFY_FLAG_STORE
diff --git a/docs-shopify.dev/generated/generated_docs_data_v2.json b/docs-shopify.dev/generated/generated_docs_data_v2.json
index 8df22fc525f..b9b241ddbb8 100644
--- a/docs-shopify.dev/generated/generated_docs_data_v2.json
+++ b/docs-shopify.dev/generated/generated_docs_data_v2.json
@@ -4711,6 +4711,15 @@
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_PORT"
         },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/theme-dev.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "--reconciliation-strategy <value>",
+          "value": "string",
+          "description": "How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_RECONCILIATION_STRATEGY"
+        },
         {
           "filePath": "docs-shopify.dev/commands/interfaces/theme-dev.interface.ts",
           "syntaxKind": "PropertySignature",
@@ -4802,7 +4811,7 @@
           "environmentValue": "SHOPIFY_FLAG_IGNORE"
         }
       ],
-      "value": "export interface themedev {\n  /**\n   * Allow development on a live theme.\n   * @environment SHOPIFY_FLAG_ALLOW_LIVE\n   */\n  '-a, --allow-live'?: ''\n\n  /**\n   * The environment to apply to the current command.\n   * @environment SHOPIFY_FLAG_ENVIRONMENT\n   */\n  '-e, --environment <value>'?: string\n\n  /**\n   * Controls the visibility of the error overlay when an theme asset upload fails:\n- silent Prevents the error overlay from appearing.\n- default Displays the error overlay.\n      \n   * @environment SHOPIFY_FLAG_ERROR_OVERLAY\n   */\n  '--error-overlay <value>'?: string\n\n  /**\n   * Set which network interface the web server listens on. The default value is 127.0.0.1.\n   * @environment SHOPIFY_FLAG_HOST\n   */\n  '--host <value>'?: string\n\n  /**\n   * Skip hot reloading any files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_IGNORE\n   */\n  '-x, --ignore <value>'?: string\n\n  /**\n   * The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.\n   * @environment SHOPIFY_FLAG_LISTING\n   */\n  '--listing <value>'?: string\n\n  /**\n   * The live reload mode switches the server behavior when a file is modified:\n- hot-reload Hot reloads local changes to CSS and sections (default)\n- full-page  Always refreshes the entire page\n- off        Deactivate live reload\n   * @environment SHOPIFY_FLAG_LIVE_RELOAD\n   */\n  '--live-reload <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Prevents files from being deleted in the remote theme when a file has been deleted locally. This applies to files that are deleted while the command is running, and files that have been deleted locally before the command is run.\n   * @environment SHOPIFY_FLAG_NODELETE\n   */\n  '-n, --nodelete'?: ''\n\n  /**\n   * The file path or URL. The file path is to a file that you want updated on idle. The URL path is where you want a webhook posted to report on file changes.\n   * @environment SHOPIFY_FLAG_NOTIFY\n   */\n  '--notify <value>'?: string\n\n  /**\n   * Hot reload only files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_ONLY\n   */\n  '-o, --only <value>'?: string\n\n  /**\n   * Automatically launch the theme preview in your default web browser.\n   * @environment SHOPIFY_FLAG_OPEN\n   */\n  '--open'?: ''\n\n  /**\n   * Password generated from the Theme Access app or an Admin API token.\n   * @environment SHOPIFY_CLI_THEME_TOKEN\n   */\n  '--password <value>'?: string\n\n  /**\n   * The path where you want to run the command. Defaults to the current working directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Local port to serve theme preview from.\n   * @environment SHOPIFY_FLAG_PORT\n   */\n  '--port <value>'?: string\n\n  /**\n   * Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).\n   * @environment SHOPIFY_FLAG_STORE\n   */\n  '-s, --store <value>'?: string\n\n  /**\n   * The password for storefronts with password protection.\n   * @environment SHOPIFY_FLAG_STORE_PASSWORD\n   */\n  '--store-password <value>'?: string\n\n  /**\n   * Theme ID or name of the remote theme.\n   * @environment SHOPIFY_FLAG_THEME_ID\n   */\n  '-t, --theme <value>'?: string\n\n  /**\n   * Synchronize Theme Editor updates in the local theme files.\n   * @environment SHOPIFY_FLAG_THEME_EDITOR_SYNC\n   */\n  '--theme-editor-sync'?: ''\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
+      "value": "export interface themedev {\n  /**\n   * Allow development on a live theme.\n   * @environment SHOPIFY_FLAG_ALLOW_LIVE\n   */\n  '-a, --allow-live'?: ''\n\n  /**\n   * The environment to apply to the current command.\n   * @environment SHOPIFY_FLAG_ENVIRONMENT\n   */\n  '-e, --environment <value>'?: string\n\n  /**\n   * Controls the visibility of the error overlay when an theme asset upload fails:\n- silent Prevents the error overlay from appearing.\n- default Displays the error overlay.\n      \n   * @environment SHOPIFY_FLAG_ERROR_OVERLAY\n   */\n  '--error-overlay <value>'?: string\n\n  /**\n   * Set which network interface the web server listens on. The default value is 127.0.0.1.\n   * @environment SHOPIFY_FLAG_HOST\n   */\n  '--host <value>'?: string\n\n  /**\n   * Skip hot reloading any files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_IGNORE\n   */\n  '-x, --ignore <value>'?: string\n\n  /**\n   * The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.\n   * @environment SHOPIFY_FLAG_LISTING\n   */\n  '--listing <value>'?: string\n\n  /**\n   * The live reload mode switches the server behavior when a file is modified:\n- hot-reload Hot reloads local changes to CSS and sections (default)\n- full-page  Always refreshes the entire page\n- off        Deactivate live reload\n   * @environment SHOPIFY_FLAG_LIVE_RELOAD\n   */\n  '--live-reload <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Prevents files from being deleted in the remote theme when a file has been deleted locally. This applies to files that are deleted while the command is running, and files that have been deleted locally before the command is run.\n   * @environment SHOPIFY_FLAG_NODELETE\n   */\n  '-n, --nodelete'?: ''\n\n  /**\n   * The file path or URL. The file path is to a file that you want updated on idle. The URL path is where you want a webhook posted to report on file changes.\n   * @environment SHOPIFY_FLAG_NOTIFY\n   */\n  '--notify <value>'?: string\n\n  /**\n   * Hot reload only files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_ONLY\n   */\n  '-o, --only <value>'?: string\n\n  /**\n   * Automatically launch the theme preview in your default web browser.\n   * @environment SHOPIFY_FLAG_OPEN\n   */\n  '--open'?: ''\n\n  /**\n   * Password generated from the Theme Access app or an Admin API token.\n   * @environment SHOPIFY_CLI_THEME_TOKEN\n   */\n  '--password <value>'?: string\n\n  /**\n   * The path where you want to run the command. Defaults to the current working directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Local port to serve theme preview from.\n   * @environment SHOPIFY_FLAG_PORT\n   */\n  '--port <value>'?: string\n\n  /**\n   * How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.\n   * @environment SHOPIFY_FLAG_RECONCILIATION_STRATEGY\n   */\n  '--reconciliation-strategy <value>'?: string\n\n  /**\n   * Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).\n   * @environment SHOPIFY_FLAG_STORE\n   */\n  '-s, --store <value>'?: string\n\n  /**\n   * The password for storefronts with password protection.\n   * @environment SHOPIFY_FLAG_STORE_PASSWORD\n   */\n  '--store-password <value>'?: string\n\n  /**\n   * Theme ID or name of the remote theme.\n   * @environment SHOPIFY_FLAG_THEME_ID\n   */\n  '-t, --theme <value>'?: string\n\n  /**\n   * Synchronize Theme Editor updates in the local theme files.\n   * @environment SHOPIFY_FLAG_THEME_EDITOR_SYNC\n   */\n  '--theme-editor-sync'?: ''\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
     }
   },
   "themeduplicate": {
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 0a8829e72bc..ead07791c5a 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -2301,8 +2301,8 @@ Uploads the current theme as a development theme to the connected store, then pr
 USAGE
   $ shopify theme dev [-a] [-e <value>...] [--error-overlay silent|default] [--host <value>] [-x <value>...]
     [--listing <value>] [--live-reload hot-reload|full-page|off] [--no-color] [-n] [--notify <value>] [-o <value>...]
-    [--open] [--password <value>] [--path <value>] [--port <value>] [-s <value>] [--store-password <value>] [-t <value>]
-    [--theme-editor-sync] [--verbose]
+    [--open] [--password <value>] [--path <value>] [--port <value>] [--reconciliation-strategy
+    keep-local|keep-remote|abort] [-s <value>] [--store-password <value>] [-t <value>] [--theme-editor-sync] [--verbose]
 
 FLAGS
   -a, --allow-live
@@ -2371,6 +2371,11 @@ FLAGS
   --port=<value>
       [env: SHOPIFY_FLAG_PORT] Local port to serve theme preview from.
 
+  --reconciliation-strategy=<option>
+      [env: SHOPIFY_FLAG_RECONCILIATION_STRATEGY] How to resolve JSON conflicts when --theme-editor-sync is enabled. Use
+      keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.
+      <options: keep-local|keep-remote|abort>
+
   --store-password=<value>
       [env: SHOPIFY_FLAG_STORE_PASSWORD] The password for storefronts with password protection.
 
diff --git a/packages/cli/oclif.manifest.json b/packages/cli/oclif.manifest.json
index cff44545da2..12ad10be2a2 100644
--- a/packages/cli/oclif.manifest.json
+++ b/packages/cli/oclif.manifest.json
@@ -6377,6 +6377,19 @@
           "name": "port",
           "type": "option"
         },
+        "reconciliation-strategy": {
+          "description": "How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.",
+          "env": "SHOPIFY_FLAG_RECONCILIATION_STRATEGY",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "reconciliation-strategy",
+          "options": [
+            "keep-local",
+            "keep-remote",
+            "abort"
+          ],
+          "type": "option"
+        },
         "store": {
           "char": "s",
           "description": "Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).",
diff --git a/packages/theme/src/cli/commands/theme/dev.ts b/packages/theme/src/cli/commands/theme/dev.ts
index c749ed07b60..365c9f43160 100644
--- a/packages/theme/src/cli/commands/theme/dev.ts
+++ b/packages/theme/src/cli/commands/theme/dev.ts
@@ -12,7 +12,7 @@ import {recordEvent} from '@shopify/cli-kit/node/analytics'
 import {AdminSession} from '@shopify/cli-kit/node/session'
 import {InferredFlags} from '@oclif/core/interfaces'
 
-import type {ErrorOverlayMode, LiveReload} from '../../utilities/theme-environment/types.js'
+import type {ErrorOverlayMode, LiveReload, ReconciliationStrategy} from '../../utilities/theme-environment/types.js'
 
 type DevFlags = InferredFlags<typeof Dev.flags>
 
@@ -77,6 +77,12 @@ You can run this command only in a directory that matches the [default Shopify t
       description: 'Synchronize Theme Editor updates in the local theme files.',
       env: 'SHOPIFY_FLAG_THEME_EDITOR_SYNC',
     }),
+    'reconciliation-strategy': Flags.string({
+      description:
+        'How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.',
+      options: ['keep-local', 'keep-remote', 'abort'],
+      env: 'SHOPIFY_FLAG_RECONCILIATION_STRATEGY',
+    }),
     port: Flags.string({
       description: 'Local port to serve theme preview from.',
       env: 'SHOPIFY_FLAG_PORT',
@@ -180,6 +186,7 @@ You can run this command only in a directory that matches the [default Shopify t
       force: flags.force,
       open: flags.open,
       'theme-editor-sync': flags['theme-editor-sync'],
+      reconciliationStrategy: flags['reconciliation-strategy'] as ReconciliationStrategy | undefined,
       noDelete: flags.nodelete,
       ignore,
       only,
diff --git a/packages/theme/src/cli/services/dev.ts b/packages/theme/src/cli/services/dev.ts
index 6f213e45b87..1eae4f3f3db 100644
--- a/packages/theme/src/cli/services/dev.ts
+++ b/packages/theme/src/cli/services/dev.ts
@@ -1,7 +1,12 @@
 import {hasRequiredThemeDirectories, mountThemeFileSystem} from '../utilities/theme-fs.js'
 import {ensureDirectoryConfirmed} from '../utilities/theme-ui.js'
 import {setupDevServer} from '../utilities/theme-environment/theme-environment.js'
-import {DevServerContext, ErrorOverlayMode, LiveReload} from '../utilities/theme-environment/types.js'
+import {
+  DevServerContext,
+  ErrorOverlayMode,
+  LiveReload,
+  ReconciliationStrategy,
+} from '../utilities/theme-environment/types.js'
 import {isStorefrontPasswordProtected} from '../utilities/theme-environment/storefront-session.js'
 import {ensureValidPassword} from '../utilities/theme-environment/storefront-password-prompt.js'
 import {emptyThemeExtFileSystem} from '../utilities/theme-fs-empty.js'
@@ -40,6 +45,7 @@ interface DevOptions {
   port?: string
   force: boolean
   'theme-editor-sync': boolean
+  reconciliationStrategy?: ReconciliationStrategy
   'live-reload': LiveReload
   'error-overlay': ErrorOverlayMode
   noDelete: boolean
@@ -124,6 +130,7 @@ export async function dev(options: DevOptions) {
     lastRequestedPath: '',
     options: {
       themeEditorSync: options['theme-editor-sync'],
+      reconciliationStrategy: options.reconciliationStrategy,
       host,
       port,
       open: options.open,
diff --git a/packages/theme/src/cli/utilities/theme-environment/remote-theme-watcher.ts b/packages/theme/src/cli/utilities/theme-environment/remote-theme-watcher.ts
index 7c300586ee3..780534e0e42 100644
--- a/packages/theme/src/cli/utilities/theme-environment/remote-theme-watcher.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/remote-theme-watcher.ts
@@ -4,6 +4,7 @@ import {outputDebug} from '@shopify/cli-kit/node/output'
 import {AdminSession} from '@shopify/cli-kit/node/session'
 import {Checksum, Theme, ThemeFileSystem} from '@shopify/cli-kit/node/themes/types'
 import {fetchChecksums} from '@shopify/cli-kit/node/themes/api'
+import type {ReconciliationStrategy} from './types.js'
 
 export const LOCAL_STRATEGY = 'local'
 export const REMOTE_STRATEGY = 'remote'
@@ -21,6 +22,7 @@ export async function reconcileAndPollThemeEditorChanges(
     noDelete: boolean
     ignore: string[]
     only: string[]
+    reconciliationStrategy?: ReconciliationStrategy
   },
   rejectBackgroundJob: (reason?: unknown) => void,
 ): Promise<{
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts b/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts
index e6bc84ba15c..a4bc090b747 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts
@@ -160,7 +160,7 @@ describe('setupDevServer', () => {
       context.session,
       [],
       context.localThemeFileSystem,
-      {noDelete: true, ...filters},
+      {noDelete: true, ...filters, reconciliationStrategy: undefined},
       expect.anything(),
     )
     // This is the best way I could think of verifying the rejectBackgroundJob
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts b/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts
index 0426a527f2b..9b1b34df749 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts
@@ -113,6 +113,7 @@ function handleThemeEditorSync(
         noDelete: ctx.options.noDelete,
         ignore: ctx.options.ignore,
         only: ctx.options.only,
+        reconciliationStrategy: ctx.options.reconciliationStrategy,
       },
       rejectBackgroundJob,
     )
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts
index 3a885a2abdd..ae9e0b1a5a2 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts
@@ -24,6 +24,7 @@ describe('reconcileJsonFiles', () => {
   let defaultThemeFileSystem: ThemeFileSystem
 
   beforeEach(() => {
+    vi.clearAllMocks()
     defaultThemeFileSystem = fakeThemeFileSystem('tmp', new Map<string, ThemeAsset>([]))
   })
 
@@ -104,6 +105,26 @@ describe('reconcileJsonFiles', () => {
   })
 
   describe('files only present on remote developer theme', () => {
+    test('should download assets from remote theme without prompting when keep-remote strategy is selected', async () => {
+      // Given
+      const assetToBeDownloaded = {checksum: '2', key: 'templates/second_asset.json', value: 'content'}
+      vi.mocked(fetchThemeAssets).mockResolvedValue([assetToBeDownloaded])
+
+      // When
+      await reconcileAndWaitForReconciliationFinish(
+        developmentTheme,
+        adminSession,
+        [assetToBeDownloaded],
+        defaultThemeFileSystem,
+        {...defaultOptions, reconciliationStrategy: 'keep-remote'},
+      )
+
+      // Then
+      expect(renderSelectPrompt).not.toHaveBeenCalled()
+      expect(fetchThemeAssets).toHaveBeenCalledWith(developmentTheme.id, [assetToBeDownloaded.key], adminSession)
+      expect(defaultThemeFileSystem.files.get('templates/second_asset.json')).toEqual(assetToBeDownloaded)
+    })
+
     test('should download assets from remote theme when `remote` source is selected', async () => {
       // Given
       vi.mocked(renderSelectPrompt).mockResolvedValue(REMOTE_STRATEGY)
@@ -220,6 +241,46 @@ describe('reconcileJsonFiles', () => {
   })
 
   describe('files with conflicting checksums', () => {
+    test('should keep local files without prompting when keep-local strategy is selected', async () => {
+      // Given
+      const files = new Map([['templates/asset.json', {checksum: '1', key: 'templates/asset.json'}]])
+      const localThemeFileSystem = fakeThemeFileSystem('tmp', files)
+      const remoteChecksums = [{checksum: '2', key: 'templates/asset.json'}]
+
+      // When
+      await reconcileAndWaitForReconciliationFinish(
+        developmentTheme,
+        adminSession,
+        remoteChecksums,
+        localThemeFileSystem,
+        {...defaultOptions, reconciliationStrategy: 'keep-local'},
+      )
+
+      // Then
+      expect(renderSelectPrompt).not.toHaveBeenCalled()
+      expect(fetchThemeAssets).not.toHaveBeenCalled()
+    })
+
+    test('should abort without prompting when abort strategy is selected', async () => {
+      // Given
+      const files = new Map([['templates/asset.json', {checksum: '1', key: 'templates/asset.json'}]])
+      const localThemeFileSystem = fakeThemeFileSystem('tmp', files)
+      const remoteChecksums = [{checksum: '2', key: 'templates/asset.json'}]
+
+      // When
+      const result = reconcileAndWaitForReconciliationFinish(
+        developmentTheme,
+        adminSession,
+        remoteChecksums,
+        localThemeFileSystem,
+        {...defaultOptions, reconciliationStrategy: 'abort'},
+      )
+
+      // Then
+      await expect(result).rejects.toThrow('Theme JSON files need reconciliation.')
+      expect(renderSelectPrompt).not.toHaveBeenCalled()
+    })
+
     test('should download files from remote theme when `remote` source is selected', async () => {
       // Given
       vi.mocked(renderSelectPrompt).mockResolvedValue(REMOTE_STRATEGY)
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts
index d678aa06526..6351efd8753 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts
@@ -7,8 +7,10 @@ import {deleteThemeAssets, fetchThemeAssets} from '@shopify/cli-kit/node/themes/
 import {Checksum, ThemeFileSystem, ThemeAsset, Theme} from '@shopify/cli-kit/node/themes/types'
 import {renderInfo, renderSelectPrompt} from '@shopify/cli-kit/node/ui'
 import {recordEvent} from '@shopify/cli-kit/node/analytics'
+import {AbortError} from '@shopify/cli-kit/node/error'
+import type {ReconciliationStrategy} from './types.js'
 
-type ReconciliationStrategy = typeof LOCAL_STRATEGY | typeof REMOTE_STRATEGY | undefined
+type PromptReconciliationStrategy = typeof LOCAL_STRATEGY | typeof REMOTE_STRATEGY | undefined
 
 interface FilePartitions {
   localFilesToDelete: Checksum[]
@@ -20,6 +22,7 @@ interface ReconciliationOptions {
   noDelete: boolean
   only: string[]
   ignore: string[]
+  reconciliationStrategy?: ReconciliationStrategy
 }
 
 const noWorkPromise = {
@@ -129,11 +132,17 @@ async function promptFileReconciliationStrategy(
       callback: (files: Checksum[]) => void
     }
   },
-): Promise<ReconciliationStrategy | undefined> {
+  strategy?: ReconciliationStrategy,
+): Promise<PromptReconciliationStrategy> {
   if (files.length === 0) {
     return
   }
 
+  if (strategy) {
+    applyReconciliationStrategy(files, title, options, strategy)
+    return
+  }
+
   renderInfo({
     body: {
       list: {
@@ -158,6 +167,34 @@ async function promptFileReconciliationStrategy(
   }
 }
 
+function applyReconciliationStrategy(
+  files: Checksum[],
+  title: string,
+  options: {
+    remote: {
+      callback: (files: Checksum[]) => void
+    }
+    local: {
+      callback: (files: Checksum[]) => void
+    }
+  },
+  strategy: ReconciliationStrategy,
+) {
+  switch (strategy) {
+    case 'keep-remote':
+      options.remote.callback(files)
+      break
+    case 'keep-local':
+      options.local.callback(files)
+      break
+    case 'abort':
+      throw new AbortError(
+        'Theme JSON files need reconciliation.',
+        `${title}\n${files.map((file) => `- ${file.key}`).join('\n')}`,
+      )
+  }
+}
+
 async function performFileReconciliation(
   targetTheme: Theme,
   session: AdminSession,
@@ -201,6 +238,7 @@ async function partitionFilesByReconciliationStrategy(
   options: ReconciliationOptions,
 ): Promise<FilePartitions> {
   const {filesOnlyPresentLocally, filesOnlyPresentOnRemote, filesWithConflictingChecksums} = files
+  const {reconciliationStrategy} = options
 
   const localFilesToDelete: Checksum[] = []
   const filesToDownload: Checksum[] = []
@@ -222,6 +260,7 @@ async function partitionFilesByReconciliationStrategy(
           callback: () => {},
         },
       },
+      reconciliationStrategy,
     )
   }
 
@@ -242,6 +281,7 @@ async function partitionFilesByReconciliationStrategy(
         },
       },
     },
+    reconciliationStrategy,
   )
 
   await promptFileReconciliationStrategy(
@@ -259,6 +299,7 @@ async function partitionFilesByReconciliationStrategy(
         callback: () => {},
       },
     },
+    reconciliationStrategy,
   )
 
   return {localFilesToDelete, filesToDownload, remoteFilesToDelete}
diff --git a/packages/theme/src/cli/utilities/theme-environment/types.ts b/packages/theme/src/cli/utilities/theme-environment/types.ts
index 9b689c7daf8..becc7dfc1f2 100644
--- a/packages/theme/src/cli/utilities/theme-environment/types.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/types.ts
@@ -56,6 +56,11 @@ export type LiveReload = 'hot-reload' | 'full-page' | 'off'
  */
 export type ErrorOverlayMode = 'silent' | 'default'
 
+/**
+ * Controls how theme editor JSON conflicts are resolved without prompting.
+ */
+export type ReconciliationStrategy = 'keep-local' | 'keep-remote' | 'abort'
+
 /**
  * Maintains the state of local and remote assets in theme development server.
  */
@@ -115,6 +120,11 @@ export interface DevServerContext {
      */
     only: string[]
 
+    /**
+     * Strategy to apply when JSON files need reconciliation.
+     */
+    reconciliationStrategy?: ReconciliationStrategy
+
     /**
      * Network interface to bind the development server to.
      */