Allow "one of" multi env flag requirements

Previously, the multi environment required flags
array was flat and any missing flag would cause
validation to fail. However, some commands provide
a few different flags that will meet the same req.
This commit updates validation logic to take in a
nested array to account for this.

Example:

`['name', ['theme', 'live', 'development']]`

To run with multiple environments, `name` flag and
one of `theme`, `live`, or `development` are required

Author: dejmedus

.changeset/wet-lions-cross.md

@@ -0,0 +1,6 @@
+---
+'@shopify/theme': minor
+'@shopify/cli': minor
+---
+
+Allow commands run with multiple environments to require "one of" a list of flags

packages/theme/src/cli/utilities/theme-command.test.ts

@@ -1,4 +1,4 @@
-import ThemeCommand from './theme-command.js'
+import ThemeCommand, {RequiredFlags} from './theme-command.js'
 import {ensureThemeStore} from './theme-store.js'
 import {describe, vi, expect, test, beforeEach} from 'vitest'
 import {Config, Flags} from '@oclif/core'
@@ -29,7 +29,7 @@ class TestThemeCommand extends ThemeCommand {
     }),
   }
 
-  static multiEnvironmentsFlags = ['store']
+  static multiEnvironmentsFlags: RequiredFlags = ['store']
 
   commandCalls: {flags: any; session: AdminSession; multiEnvironment?: boolean; context?: any}[] = []
 
@@ -58,6 +58,23 @@ class TestThemeCommandWithForce extends TestThemeCommand {
   }
 }
 
+class TestThemeCommandWithUnionFlags extends TestThemeCommand {
+  static multiEnvironmentsFlags: RequiredFlags = ['store', ['live', 'development', 'theme']]
+
+  static flags = {
+    ...TestThemeCommand.flags,
+    development: Flags.boolean({
+      env: 'SHOPIFY_FLAG_DEVELOPMENT',
+    }),
+    theme: Flags.string({
+      env: 'SHOPIFY_FLAG_THEME_ID',
+    }),
+    live: Flags.boolean({
+      env: 'SHOPIFY_FLAG_LIVE',
+    }),
+  }
+}
+
 describe('ThemeCommand', () => {
   let mockSession: AdminSession
 
@@ -246,6 +263,31 @@ describe('ThemeCommand', () => {
       expect(renderConcurrent).not.toHaveBeenCalled()
     })
 
+    test('should execute commands in environments with all required flags', async () => {
+      // Given
+      vi.mocked(loadEnvironment)
+        .mockResolvedValueOnce({store: 'store1.myshopify.com', theme: 'theme1.myshopify.com'})
+        .mockResolvedValueOnce({store: 'store2.myshopify.com', development: true})
+        .mockResolvedValueOnce({store: 'store3.myshopify.com', live: true})
+
+      vi.mocked(renderConfirmationPrompt).mockResolvedValue(true)
+      vi.mocked(renderConcurrent).mockResolvedValue(undefined)
+
+      await CommandConfig.load()
+      const command = new TestThemeCommandWithUnionFlags(
+        ['--environment', 'theme', '--environment', 'development', '--environment', 'live'],
+        CommandConfig,
+      )
+
+      // When
+      await command.run()
+
+      // Then
+      const renderConcurrentProcesses = vi.mocked(renderConcurrent).mock.calls[0]?.[0]?.processes
+      expect(renderConcurrentProcesses).toHaveLength(3)
+      expect(renderConcurrentProcesses?.map((process) => process.prefix)).toEqual(['theme', 'development', 'live'])
+    })
+
     test('should not execute commands in environments that are missing required flags', async () => {
       // Given
       vi.mocked(loadEnvironment)
@@ -271,6 +313,31 @@ describe('ThemeCommand', () => {
       expect(renderConcurrentProcesses?.map((process) => process.prefix)).toEqual(['development', 'production'])
     })
 
+    test('should not execute commands in environments that are missing required "one of" flags', async () => {
+      // Given
+      vi.mocked(loadEnvironment)
+        .mockResolvedValueOnce({store: 'store1.myshopify.com', theme: 'theme1.myshopify.com'})
+        .mockResolvedValueOnce({store: 'store2.myshopify.com'})
+        .mockResolvedValueOnce({store: 'store3.myshopify.com', live: true})
+
+      vi.mocked(renderConfirmationPrompt).mockResolvedValue(true)
+      vi.mocked(renderConcurrent).mockResolvedValue(undefined)
+
+      await CommandConfig.load()
+      const command = new TestThemeCommandWithUnionFlags(
+        ['--environment', 'theme', '--environment', 'missing-theme-live-or-development', '--environment', 'live'],
+        CommandConfig,
+      )
+
+      // When
+      await command.run()
+
+      // Then
+      const renderConcurrentProcesses = vi.mocked(renderConcurrent).mock.calls[0]?.[0]?.processes
+      expect(renderConcurrentProcesses).toHaveLength(2)
+      expect(renderConcurrentProcesses?.map((process) => process.prefix)).toEqual(['theme', 'live'])
+    })
+
     test('commands error gracefully and continue with other environments', async () => {
       // Given
       vi.mocked(loadEnvironment).mockResolvedValue({store: 'store.myshopify.com'})

packages/theme/src/cli/utilities/theme-command.ts

@@ -22,6 +22,21 @@ interface PassThroughFlagsOptions {
   allowedFlags?: string[]
 }
 type EnvironmentName = string
+/**
+ * Flags required to run a command in multiple environments
+ *
+ * If the command does not support multiple environments, set to null
+ *
+ * Otherwise, each element can be:
+ * - string: A required flag
+ * - string[]: Multiple flags where at least one is required,
+ *             ordered by precedence
+ *
+ *  @example
+ * // store, password, and one of: live, development, or theme
+ * ['store', 'password', ['live', 'development', 'theme']]
+ */
+export type RequiredFlags = (string | string[])[] | null
 
 export default abstract class ThemeCommand extends Command {
   passThroughFlags(flags: FlagValues, {allowedFlags}: PassThroughFlagsOptions): string[] {
@@ -58,7 +73,7 @@ export default abstract class ThemeCommand extends Command {
   >(_opts?: Input<TFlags, TGlobalFlags, TArgs>): Promise<void> {
     // Parse command flags using the current command class definitions
     const klass = this.constructor as unknown as Input<TFlags, TGlobalFlags, TArgs> & {
-      multiEnvironmentsFlags: string[] | null
+      multiEnvironmentsFlags: RequiredFlags
       flags: FlagOutput
     }
     const requiredFlags = klass.multiEnvironmentsFlags
@@ -128,7 +143,10 @@ export default abstract class ThemeCommand extends Command {
    * @param requiredFlags - The required flags to check for
    * @returns An object containing valid and invalid environment arrays
    */
-  private async validateEnvironments(environmentMap: Map<EnvironmentName, FlagValues>, requiredFlags: string[]) {
+  private async validateEnvironments(
+    environmentMap: Map<EnvironmentName, FlagValues>,
+    requiredFlags: Exclude<RequiredFlags, null>,
+  ) {
     const valid: {environment: EnvironmentName; flags: FlagValues; session: AdminSession}[] = []
     const invalid: {environment: EnvironmentName; reason: string}[] = []
 
@@ -158,7 +176,7 @@ export default abstract class ThemeCommand extends Command {
    */
   private async showConfirmation(
     commandName: string,
-    requiredFlags: string[],
+    requiredFlags: Exclude<RequiredFlags, null>,
     validationResults: {
       valid: {environment: string; flags: FlagValues}[]
       invalid: {environment: string; reason: string}[]
@@ -176,7 +194,10 @@ export default abstract class ThemeCommand extends Command {
     const environmentDetails = [
       ...validationResults.valid.map(({environment, flags}) => {
         const flagDetails = requiredFlags
-          .map((flag) => (flag.includes('password') ? flag : `${flag}: ${String(flags[flag])}`))
+          .map((flag) => {
+            const usedFlag = Array.isArray(flag) ? flag.find((flag) => flags[flag]) : flag
+            return usedFlag && [usedFlag.includes('password') ? usedFlag : `${usedFlag}: ${flags[usedFlag]}`]
+          })
           .join(', ')
 
         return [environment, {subdued: flagDetails || 'No flags required'}]
@@ -241,8 +262,14 @@ export default abstract class ThemeCommand extends Command {
    * @param environmentName - The name of the environment
    * @returns The missing flags or true if the environment has all required flags
    */
-  private validConfig(environmentFlags: FlagValues, requiredFlags: string[], environmentName: string): string[] | true {
-    const missingFlags = requiredFlags.filter((flag) => !environmentFlags[flag])
+  private validConfig(
+    environmentFlags: FlagValues,
+    requiredFlags: Exclude<RequiredFlags, null>,
+    environmentName: string,
+  ): string[] | true {
+    const missingFlags = requiredFlags
+      .filter((flag) => (Array.isArray(flag) ? !flag.some((flag) => environmentFlags[flag]) : !environmentFlags[flag]))
+      .map((flag) => (Array.isArray(flag) ? flag.join(' or ') : flag))
 
     if (missingFlags.length > 0) {
       renderWarning({