Add theme dev reconciliation strategy flag

[gonzaloriestra]

WHY are these changes introduced?

Fixes https://github.com/shop/issues-develop/issues/22873

The interactivity audit found that theme dev with --theme-editor-sync could still prompt when JSON files needed reconciliation.

WHAT is this pull request doing?

• Adds --reconciliation-strategy with keep-local, keep-remote, and abort options.
• Threads the strategy through theme editor sync reconciliation and refreshes generated command docs.

How to test your changes?

Make a change in a theme file (like templates/404.json) locally and remotely and run:

• shopify theme dev --theme-editor-sync
• shopify theme dev --theme-editor-sync --reconciliation-strategy keep-local
• shopify theme dev --theme-editor-sync --reconciliation-strategy keep-remote
• shopify theme dev --theme-editor-sync --reconciliation-strategy abort

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing, so I've added a changelog entry with pnpm changeset add

[gonzaloriestra]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Error before app config link prompts in non-TTY #7687
• Add theme dev reconciliation strategy flag #7634 👈 (View in Graphite)
• Add non-interactive app dev prompt bypasses #7632 : 1 other dependent PR (#7633 )
• Allow app config validate to target config by client ID #7631
• Add flags to avoid prompts in app config link #7630
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[karreiro]

Thank you for this PR, @gonzaloriestra!

What if we repurpose the --theme-editor-sync flag, since we're defining the sync strategy? We could have something like this:

shopify theme dev --theme-editor-sync ask [default]
shopify theme dev --theme-editor-sync keep-local
shopify theme dev --theme-editor-sync keep-remote
shopify theme dev --theme-editor-sync abort

This would be a backward-compatible change, since ask would be the default value. It also reduces the blast radius of the change and keeps the dev command simpler.

Thanks again for the PR!

[gonzaloriestra]

@karreiro I like the idea, but Oclif doesn't support default values like that. A default value can be used when the flag is omitted, but if you just add --theme-editor-sync, it would fail because it expects an additional string (it's not a boolean).

Maybe there's a hacky way to do it, but I think I prefer to just add an additional flag. Wdyt?

[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/private/node/constants.d.ts

@@ -6,6 +6,7 @@ export declare const environmentVariables: {
     doctor: string;
     enableCliRedirect: string;
     env: string;
+    firstPartyDev: string;
     noAnalytics: string;
     optOutInstrumentation: string;
     appAutomationToken: string;

packages/cli-kit/dist/public/node/context/local.d.ts

@@ -63,6 +63,13 @@ export declare function alwaysLogAnalytics(env?: NodeJS.ProcessEnv): boolean;
  * @returns True if SHOPIFY_CLI_ALWAYS_LOG_METRICS is truthy.
  */
 export declare function alwaysLogMetrics(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Returns true if the CLI User is 1P.
+ *
+ * @param env - The environment variables from the environment of the current process.
+ * @returns True if SHOPIFY_CLI_1P is truthy.
+ */
+export declare function firstPartyDev(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Returns true if the CLI can run the "doctor-release" command.
  *

[karreiro]

Thank you for this PR, @gonzaloriestra!

I looked into it, and the alternatives for implementing the single-flag approach are indeed hacky. It also reveals that having union types (boolean | string) in CLI flags might not be the ideal pattern. So, from my side, +1 for proceeding with this approach.

Thanks again for this PR!