Merge pull request #6636 from Shopify/11-18-implement-variable-file-flag

Add `--variable-file` flag for bulk operation mutations

Author: ericlee878

packages/app/src/cli/commands/app/execute.ts

@@ -39,6 +39,7 @@ export default class Execute extends AppLinkedCommand {
       storeFqdn: store.shopDomain,
       query: flags.query,
       variables: flags.variables,
+      variableFile: flags['variable-file'],
     })
 
     return {app: appContextResult.app}

packages/app/src/cli/flags.ts

@@ -48,6 +48,14 @@ export const bulkOperationFlags = {
       'The values for any GraphQL variables in your mutation, in JSON format. Can be specified multiple times.',
     env: 'SHOPIFY_FLAG_VARIABLES',
     multiple: true,
+    exclusive: ['variable-file'],
+  }),
+  'variable-file': Flags.string({
+    description:
+      "Path to a file containing GraphQL variables in JSONL format (one JSON object per line). Can't be used with --variables.",
+    env: 'SHOPIFY_FLAG_VARIABLE_FILE',
+    parse: async (input) => resolvePath(input),
+    exclusive: ['variables'],
   }),
   store: Flags.string({
     char: 's',

packages/app/src/cli/services/bulk-operations/execute-bulk-operation.test.ts

@@ -4,6 +4,8 @@ import {runBulkOperationMutation} from './run-mutation.js'
 import {AppLinkedInterface} from '../../models/app/app.js'
 import {renderSuccess, renderWarning} from '@shopify/cli-kit/node/ui'
 import {ensureAuthenticatedAdmin} from '@shopify/cli-kit/node/session'
+import {inTemporaryDirectory, writeFile} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
 import {describe, test, expect, vi, beforeEach} from 'vitest'
 
 vi.mock('./run-query.js')
@@ -50,7 +52,6 @@ describe('executeBulkOperation', () => {
     expect(runBulkOperationQuery).toHaveBeenCalledWith({
       adminSession: mockAdminSession,
       query,
-      variables: undefined,
     })
     expect(runBulkOperationMutation).not.toHaveBeenCalled()
   })
@@ -72,7 +73,6 @@ describe('executeBulkOperation', () => {
     expect(runBulkOperationQuery).toHaveBeenCalledWith({
       adminSession: mockAdminSession,
       query,
-      variables: undefined,
     })
     expect(runBulkOperationMutation).not.toHaveBeenCalled()
   })
@@ -94,7 +94,7 @@ describe('executeBulkOperation', () => {
     expect(runBulkOperationMutation).toHaveBeenCalledWith({
       adminSession: mockAdminSession,
       query: mutation,
-      variables: undefined,
+      variablesJsonl: undefined,
     })
     expect(runBulkOperationQuery).not.toHaveBeenCalled()
   })
@@ -118,7 +118,7 @@ describe('executeBulkOperation', () => {
     expect(runBulkOperationMutation).toHaveBeenCalledWith({
       adminSession: mockAdminSession,
       query: mutation,
-      variables,
+      variablesJsonl: '{"input":{"id":"gid://shopify/Product/123","tags":["test"]}}',
     })
   })
 
@@ -216,4 +216,94 @@ describe('executeBulkOperation', () => {
     expect(runBulkOperationQuery).not.toHaveBeenCalled()
     expect(runBulkOperationMutation).not.toHaveBeenCalled()
   })
+
+  test('reads variables from file when variableFile is provided', async () => {
+    await inTemporaryDirectory(async (tmpDir) => {
+      const variableFilePath = joinPath(tmpDir, 'variables.jsonl')
+      const variables = [
+        '{"input":{"id":"gid://shopify/Product/123","tags":["test"]}}',
+        '{"input":{"id":"gid://shopify/Product/456","tags":["test2"]}}',
+      ]
+      await writeFile(variableFilePath, variables.join('\n'))
+
+      const mutation =
+        'mutation productUpdate($input: ProductInput!) { productUpdate(input: $input) { product { id } } }'
+      const mockResponse = {
+        bulkOperation: successfulBulkOperation,
+        userErrors: [],
+      }
+      vi.mocked(runBulkOperationMutation).mockResolvedValue(mockResponse as any)
+
+      await executeBulkOperation({
+        app: mockApp,
+        storeFqdn,
+        query: mutation,
+        variableFile: variableFilePath,
+      })
+
+      expect(runBulkOperationMutation).toHaveBeenCalledWith({
+        adminSession: mockAdminSession,
+        query: mutation,
+        variablesJsonl: variables.join('\n'),
+      })
+    })
+  })
+
+  test('throws error when variableFile does not exist', async () => {
+    await inTemporaryDirectory(async (tmpDir) => {
+      const nonExistentPath = joinPath(tmpDir, 'nonexistent.jsonl')
+      const mutation =
+        'mutation productUpdate($input: ProductInput!) { productUpdate(input: $input) { product { id } } }'
+
+      await expect(
+        executeBulkOperation({
+          app: mockApp,
+          storeFqdn,
+          query: mutation,
+          variableFile: nonExistentPath,
+        }),
+      ).rejects.toThrow('Variable file not found')
+
+      expect(runBulkOperationQuery).not.toHaveBeenCalled()
+      expect(runBulkOperationMutation).not.toHaveBeenCalled()
+    })
+  })
+
+  test('throws error when variables are provided with a query (not mutation)', async () => {
+    const query = 'query { products { edges { node { id } } } }'
+    const variables = ['{"input":{"id":"gid://shopify/Product/123"}}']
+
+    await expect(
+      executeBulkOperation({
+        app: mockApp,
+        storeFqdn,
+        query,
+        variables,
+      }),
+    ).rejects.toThrow('can only be used with mutations, not queries')
+
+    expect(runBulkOperationQuery).not.toHaveBeenCalled()
+    expect(runBulkOperationMutation).not.toHaveBeenCalled()
+  })
+
+  test('throws error when variableFile is provided with a query (not mutation)', async () => {
+    await inTemporaryDirectory(async (tmpDir) => {
+      const variableFilePath = joinPath(tmpDir, 'variables.jsonl')
+      await writeFile(variableFilePath, '{"input":{}}')
+
+      const query = 'query { products { edges { node { id } } } }'
+
+      await expect(
+        executeBulkOperation({
+          app: mockApp,
+          storeFqdn,
+          query,
+          variableFile: variableFilePath,
+        }),
+      ).rejects.toThrow('can only be used with mutations, not queries')
+
+      expect(runBulkOperationQuery).not.toHaveBeenCalled()
+      expect(runBulkOperationMutation).not.toHaveBeenCalled()
+    })
+  })
 })

packages/app/src/cli/services/bulk-operations/execute-bulk-operation.ts

@@ -6,28 +6,48 @@ import {outputContent, outputToken} from '@shopify/cli-kit/node/output'
 import {ensureAuthenticatedAdmin} from '@shopify/cli-kit/node/session'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import {parse} from 'graphql'
+import {readFile, fileExists} from '@shopify/cli-kit/node/fs'
 
 interface ExecuteBulkOperationInput {
   app: AppLinkedInterface
   storeFqdn: string
   query: string
   variables?: string[]
+  variableFile?: string
+}
+
+async function parseVariablesToJsonl(variables?: string[], variableFile?: string): Promise<string | undefined> {
+  if (variables) {
+    return variables.join('\n')
+  } else if (variableFile) {
+    if (!(await fileExists(variableFile))) {
+      throw new AbortError(
+        outputContent`Variable file not found at ${outputToken.path(
+          variableFile,
+        )}. Please check the path and try again.`,
+      )
+    }
+    return readFile(variableFile, {encoding: 'utf8'})
+  } else {
+    return undefined
+  }
 }
 
 export async function executeBulkOperation(input: ExecuteBulkOperationInput): Promise<void> {
-  const {app, storeFqdn, query, variables} = input
+  const {app, storeFqdn, query, variables, variableFile} = input
 
   renderInfo({
     headline: 'Starting bulk operation.',
     body: `App: ${app.name}\nStore: ${storeFqdn}`,
   })
-
   const adminSession = await ensureAuthenticatedAdmin(storeFqdn)
 
-  validateGraphQLDocument(query, variables)
+  const variablesJsonl = await parseVariablesToJsonl(variables, variableFile)
+
+  validateGraphQLDocument(query, variablesJsonl)
 
   const bulkOperationResponse = isMutation(query)
-    ? await runBulkOperationMutation({adminSession, query, variables})
+    ? await runBulkOperationMutation({adminSession, query, variablesJsonl})
     : await runBulkOperationQuery({adminSession, query})
 
   if (bulkOperationResponse?.userErrors?.length) {
@@ -72,7 +92,7 @@ export async function executeBulkOperation(input: ExecuteBulkOperationInput): Pr
   }
 }
 
-function validateGraphQLDocument(graphqlOperation: string, variables?: string[]): void {
+function validateGraphQLDocument(graphqlOperation: string, variablesJsonl?: string): void {
   const document = parse(graphqlOperation)
   const operationDefinitions = document.definitions.filter((def) => def.kind === 'OperationDefinition')
 
@@ -82,9 +102,11 @@ function validateGraphQLDocument(graphqlOperation: string, variables?: string[])
     )
   }
 
-  if (!isMutation(graphqlOperation) && variables) {
+  if (!isMutation(graphqlOperation) && variablesJsonl) {
     throw new AbortError(
-      outputContent`The ${outputToken.yellow('--variables')} flag can only be used with mutations, not queries.`,
+      outputContent`The ${outputToken.yellow('--variables')} and ${outputToken.yellow(
+        '--variable-file',
+      )} flags can only be used with mutations, not queries.`,
     )
   }
 }

packages/app/src/cli/services/bulk-operations/run-mutation.test.ts

@@ -34,7 +34,7 @@ describe('runBulkOperationMutation', () => {
     const bulkOperationResult = await runBulkOperationMutation({
       adminSession: mockSession,
       query: 'mutation productUpdate($input: ProductInput!) { productUpdate(input: $input) { product { id } } }',
-      variables: ['{"input":{"id":"gid://shopify/Product/123","tags":["test"]}}'],
+      variablesJsonl: '{"input":{"id":"gid://shopify/Product/123","tags":["test"]}}',
     })
 
     expect(bulkOperationResult?.bulkOperation).toEqual(successfulBulkOperation)

packages/app/src/cli/services/bulk-operations/run-mutation.ts

@@ -10,17 +10,17 @@ import {AdminSession} from '@shopify/cli-kit/node/session'
 interface BulkOperationRunMutationOptions {
   adminSession: AdminSession
   query: string
-  variables?: string[]
+  variablesJsonl?: string
 }
 
 export async function runBulkOperationMutation(
   options: BulkOperationRunMutationOptions,
 ): Promise<BulkOperationRunMutationMutation['bulkOperationRunMutation']> {
-  const {adminSession, query: mutation, variables} = options
+  const {adminSession, query: mutation, variablesJsonl} = options
 
   const stagedUploadPath = await stageFile({
     adminSession,
-    jsonVariables: variables,
+    variablesJsonl,
   })
 
   const response = await adminRequestDoc<BulkOperationRunMutationMutation, BulkOperationRunMutationMutationVariables>({

packages/app/src/cli/services/bulk-operations/stage-file.test.ts

@@ -44,55 +44,53 @@ describe('stageFile', () => {
     } as any)
   })
 
-  test('returns staged upload key when file is successfully staged with empty variables', async () => {
+  test('returns staged upload key when file is successfully staged with no variables', async () => {
     vi.mocked(adminRequestDoc).mockResolvedValue(mockSuccessResponse)
 
     const result = await stageFile({
       adminSession: mockSession,
-      jsonVariables: [],
+      variablesJsonl: undefined,
     })
 
     expect(result).toBe('test-key')
   })
 
-  test('converts JSON strings array to JSONL format when uploading file', async () => {
+  test('converts JSONL string to buffer when uploading file', async () => {
     vi.mocked(adminRequestDoc).mockResolvedValue(mockSuccessResponse)
     const mockAppend = vi.fn()
     vi.mocked(formData).mockReturnValue({append: mockAppend} as any)
 
-    const jsonVariables = ['{"input":{"id":"gid://shopify/Product/123","tags":["test"]}}']
+    const variablesJsonl = '{"input":{"id":"gid://shopify/Product/123","tags":["test"]}}'
 
     await stageFile({
       adminSession: mockSession,
-      jsonVariables,
+      variablesJsonl,
     })
 
-    // Find the form.append('file', buffer, options) call among all append calls
     const fileAppendCall = mockAppend.mock.calls.find((call) => {
       const fieldName = call[0]
       return fieldName === 'file'
     })
-    // Extract the buffer (second argument) that was uploaded
     const uploadedBuffer = fileAppendCall?.[1]
     const uploadedContent = uploadedBuffer?.toString('utf-8')
 
     expect(uploadedContent).toBe('{"input":{"id":"gid://shopify/Product/123","tags":["test"]}}\n')
   })
 
-  test('handles multiple JSON variable strings correctly', async () => {
+  test('handles JSONL with multiple lines correctly', async () => {
     vi.mocked(adminRequestDoc).mockResolvedValue(mockSuccessResponse)
     const mockAppend = vi.fn()
     vi.mocked(formData).mockReturnValue({append: mockAppend} as any)
 
-    const jsonVariables = [
+    const variablesJsonl = [
       '{"input":{"id":"gid://shopify/Product/1","title":"New Shirt"}}',
       '{"input":{"id":"gid://shopify/Product/2","title":"Cool Pants"}}',
       '{"input":{"id":"gid://shopify/Product/3","title":"Nice Hat"}}',
-    ]
+    ].join('\n')
 
     await stageFile({
       adminSession: mockSession,
-      jsonVariables,
+      variablesJsonl,
     })
 
     const fileAppendCall = mockAppend.mock.calls.find((call) => {

packages/app/src/cli/services/bulk-operations/stage-file.ts

@@ -10,13 +10,13 @@ import {AbortError} from '@shopify/cli-kit/node/error'
 
 interface StageFileOptions {
   adminSession: AdminSession
-  jsonVariables?: string[]
+  variablesJsonl?: string
 }
 
 export async function stageFile(options: StageFileOptions): Promise<string> {
-  const {adminSession, jsonVariables = []} = options
+  const {adminSession, variablesJsonl} = options
 
-  const buffer = convertJsonToJsonlBuffer(jsonVariables)
+  const buffer = Buffer.from(variablesJsonl ? `${variablesJsonl}\n` : '', 'utf-8')
   const filename = 'bulk-variables.jsonl'
   const size = buffer.length
 
@@ -28,11 +28,6 @@ export async function stageFile(options: StageFileOptions): Promise<string> {
   return target.stagedUploadKey
 }
 
-function convertJsonToJsonlBuffer(jsonVariables: string[]): Buffer {
-  const jsonlContent = `${jsonVariables.join('\n')}\n`
-  return Buffer.from(jsonlContent, 'utf-8')
-}
-
 async function requestStagedUpload(
   adminSession: AdminSession,
   filename: string,

packages/cli/oclif.manifest.json

@@ -885,10 +885,24 @@
           "name": "store",
           "type": "option"
         },
+        "variable-file": {
+          "description": "Path to a file containing GraphQL variables in JSONL format (one JSON object per line). Can't be used with --variables.",
+          "env": "SHOPIFY_FLAG_VARIABLE_FILE",
+          "exclusive": [
+            "variables"
+          ],
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "variable-file",
+          "type": "option"
+        },
         "variables": {
           "char": "v",
           "description": "The values for any GraphQL variables in your mutation, in JSON format. Can be specified multiple times.",
           "env": "SHOPIFY_FLAG_VARIABLES",
+          "exclusive": [
+            "variable-file"
+          ],
           "hasDynamicHelp": false,
           "multiple": true,
           "name": "variables",