make version handling consistent between app execute and app bulk execute

Author: nickwesselman

docs-shopify.dev/commands/app-execute.doc.ts

@@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'app execute',
-  description: `Executes a GraphQL query or mutation on the specified store, and writes the result to STDOUT or a file.`,
+  description: `Executes an Admin API GraphQL query or mutation on the specified dev store.`,
   overviewPreviewDescription: `Execute GraphQL queries and mutations.`,
   type: 'command',
   isVisualComponent: false,

docs-shopify.dev/generated/generated_docs_data.json

@@ -1000,7 +1000,7 @@
   },
   {
     "name": "app execute",
-    "description": "Executes a GraphQL query or mutation on the specified store, and writes the result to STDOUT or a file.",
+    "description": "Executes an Admin API GraphQL query or mutation on the specified dev store.",
     "overviewPreviewDescription": "Execute GraphQL queries and mutations.",
     "type": "command",
     "isVisualComponent": false,

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

@@ -25,8 +25,8 @@ export default class Execute extends AppLinkedCommand {
       storeFqdn: store.shopDomain,
       query,
       variables: flags.variables,
-      apiVersion: flags.version,
       outputFile: flags['output-file'],
+      ...(flags.version && {version: flags.version}),
     })
 
     return {app: appContextResult.app}

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

@@ -3,6 +3,7 @@ import {runBulkOperationQuery} from './run-query.js'
 import {runBulkOperationMutation} from './run-mutation.js'
 import {watchBulkOperation} from './watch-bulk-operation.js'
 import {downloadBulkOperationResults} from './download-bulk-operation-results.js'
+import {validateApiVersion} from '../graphql/common.js'
 import {BulkOperationRunQueryMutation} from '../../api/graphql/bulk-operations/generated/bulk-operation-run-query.js'
 import {BulkOperationRunMutationMutation} from '../../api/graphql/bulk-operations/generated/bulk-operation-run-mutation.js'
 import {OrganizationApp} from '../../models/organization.js'
@@ -17,6 +18,13 @@ vi.mock('./run-query.js')
 vi.mock('./run-mutation.js')
 vi.mock('./watch-bulk-operation.js')
 vi.mock('./download-bulk-operation-results.js')
+vi.mock('../graphql/common.js', async () => {
+  const actual = await vi.importActual('../graphql/common.js')
+  return {
+    ...actual,
+    validateApiVersion: vi.fn(),
+  }
+})
 vi.mock('@shopify/cli-kit/node/ui')
 vi.mock('@shopify/cli-kit/node/fs')
 vi.mock('@shopify/cli-kit/node/session', async () => {
@@ -26,13 +34,6 @@ vi.mock('@shopify/cli-kit/node/session', async () => {
     ensureAuthenticatedAdminAsApp: vi.fn(),
   }
 })
-vi.mock('@shopify/cli-kit/node/api/admin', async () => {
-  const actual = await vi.importActual('@shopify/cli-kit/node/api/admin')
-  return {
-    ...actual,
-    supportedApiVersions: vi.fn(() => Promise.resolve(['2025-01', '2025-04', '2025-07', '2025-10'])),
-  }
-})
 
 describe('executeBulkOperation', () => {
   const mockRemoteApp = {
@@ -469,62 +470,46 @@ describe('executeBulkOperation', () => {
     expect(renderSuccess).not.toHaveBeenCalled()
   })
 
-  test('allows executing bulk operations against unstable', async () => {
+  test('validates API version when provided', async () => {
     const query = '{ products { edges { node { id } } } }'
+    const version = '2025-01'
     const mockResponse: BulkOperationRunQueryMutation['bulkOperationRunQuery'] = {
       bulkOperation: createdBulkOperation,
       userErrors: [],
     }
     vi.mocked(runBulkOperationQuery).mockResolvedValue(mockResponse)
+    vi.mocked(validateApiVersion).mockResolvedValue()
 
     await executeBulkOperation({
       remoteApp: mockRemoteApp,
       storeFqdn,
       query,
-      version: 'unstable',
+      version,
     })
 
+    expect(validateApiVersion).toHaveBeenCalledWith(mockAdminSession, version)
     expect(runBulkOperationQuery).toHaveBeenCalledWith({
       adminSession: mockAdminSession,
       query,
-      version: 'unstable',
+      version,
     })
   })
 
-  test('allows executing bulk operations against a specific stable version', async () => {
+  test('does not validate version when not provided', async () => {
     const query = '{ products { edges { node { id } } } }'
     const mockResponse: BulkOperationRunQueryMutation['bulkOperationRunQuery'] = {
       bulkOperation: createdBulkOperation,
       userErrors: [],
     }
     vi.mocked(runBulkOperationQuery).mockResolvedValue(mockResponse)
+    vi.mocked(validateApiVersion).mockClear()
 
     await executeBulkOperation({
       remoteApp: mockRemoteApp,
       storeFqdn,
       query,
-      version: '2025-01',
-    })
-
-    expect(runBulkOperationQuery).toHaveBeenCalledWith({
-      adminSession: mockAdminSession,
-      query,
-      version: '2025-01',
     })
-  })
-
-  test('throws error when an API version is specified but is not supported', async () => {
-    const query = '{ products { edges { node { id } } } }'
-
-    await expect(
-      executeBulkOperation({
-        remoteApp: mockRemoteApp,
-        storeFqdn,
-        query,
-        version: '2099-12',
-      }),
-    ).rejects.toThrow('Invalid API version')
 
-    expect(runBulkOperationQuery).not.toHaveBeenCalled()
+    expect(validateApiVersion).not.toHaveBeenCalled()
   })
 })

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

@@ -3,11 +3,10 @@ import {runBulkOperationMutation} from './run-mutation.js'
 import {watchBulkOperation, type BulkOperation} from './watch-bulk-operation.js'
 import {formatBulkOperationStatus} from './format-bulk-operation-status.js'
 import {downloadBulkOperationResults} from './download-bulk-operation-results.js'
-import {createAdminSessionAsApp, validateSingleOperation} from '../graphql/common.js'
+import {createAdminSessionAsApp, validateSingleOperation, validateApiVersion} from '../graphql/common.js'
 import {OrganizationApp} from '../../models/organization.js'
 import {renderSuccess, renderInfo, renderError, renderWarning, TokenItem} from '@shopify/cli-kit/node/ui'
 import {outputContent, outputToken, outputResult} from '@shopify/cli-kit/node/output'
-import {supportedApiVersions} from '@shopify/cli-kit/node/api/admin'
 import {AbortError, BugError} from '@shopify/cli-kit/node/error'
 import {AbortController} from '@shopify/cli-kit/node/abort'
 import {parse} from 'graphql'
@@ -176,15 +175,3 @@ function isMutation(graphqlOperation: string): boolean {
   const operation = document.definitions.find((def) => def.kind === 'OperationDefinition')
   return operation?.kind === 'OperationDefinition' && operation.operation === 'mutation'
 }
-
-async function validateApiVersion(adminSession: {token: string; storeFqdn: string}, version: string): Promise<void> {
-  if (version === 'unstable') return
-
-  const supportedVersions = await supportedApiVersions(adminSession)
-  if (supportedVersions.includes(version)) return
-
-  const firstLine = outputContent`Invalid API version: ${version}`.value
-  const secondLine = outputContent`Supported versions: ${supportedVersions.join(', ')}`.value
-
-  throw new AbortError(`${firstLine}\n${secondLine}`)
-}

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

@@ -1,5 +1,5 @@
 import {executeOperation} from './execute-operation.js'
-import {createAdminSessionAsApp} from './graphql/common.js'
+import {createAdminSessionAsApp, validateApiVersion} from './graphql/common.js'
 import {OrganizationApp} from '../models/organization.js'
 import {renderSuccess, renderError, renderSingleTask} from '@shopify/cli-kit/node/ui'
 import {adminRequestDoc} from '@shopify/cli-kit/node/api/admin'
@@ -95,24 +95,41 @@ describe('executeOperation', () => {
 
   test('uses specified API version when provided', async () => {
     const query = 'query { shop { name } }'
-    const apiVersion = '2024-01'
+    const version = '2024-01'
     const mockResult = {data: {shop: {name: 'Test Shop'}}}
     vi.mocked(adminRequestDoc).mockResolvedValue(mockResult)
+    vi.mocked(validateApiVersion).mockResolvedValue()
 
     await executeOperation({
       remoteApp: mockRemoteApp,
       storeFqdn,
       query,
-      apiVersion,
+      version,
     })
 
+    expect(validateApiVersion).toHaveBeenCalledWith(mockAdminSession, version)
     expect(adminRequestDoc).toHaveBeenCalledWith(
       expect.objectContaining({
-        version: apiVersion,
+        version,
       }),
     )
   })
 
+  test('does not validate version when not provided', async () => {
+    const query = 'query { shop { name } }'
+    const mockResult = {data: {shop: {name: 'Test Shop'}}}
+    vi.mocked(adminRequestDoc).mockResolvedValue(mockResult)
+    vi.mocked(validateApiVersion).mockClear()
+
+    await executeOperation({
+      remoteApp: mockRemoteApp,
+      storeFqdn,
+      query,
+    })
+
+    expect(validateApiVersion).not.toHaveBeenCalled()
+  })
+
   test('writes formatted JSON results to stdout by default', async () => {
     const query = 'query { shop { name } }'
     const mockResult = {data: {shop: {name: 'Test Shop'}}}

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

@@ -1,4 +1,4 @@
-import {createAdminSessionAsApp, validateSingleOperation} from './graphql/common.js'
+import {createAdminSessionAsApp, validateSingleOperation, validateApiVersion} from './graphql/common.js'
 import {OrganizationApp} from '../models/organization.js'
 import {renderSuccess, renderError, renderInfo, renderSingleTask} from '@shopify/cli-kit/node/ui'
 import {outputContent, outputToken, outputResult} from '@shopify/cli-kit/node/output'
@@ -13,8 +13,8 @@ interface ExecuteOperationInput {
   storeFqdn: string
   query: string
   variables?: string
-  apiVersion?: string
   outputFile?: string
+  version?: string
 }
 
 async function parseVariables(variables?: string): Promise<{[key: string]: unknown} | undefined> {
@@ -32,15 +32,27 @@ async function parseVariables(variables?: string): Promise<{[key: string]: unkno
 }
 
 export async function executeOperation(input: ExecuteOperationInput): Promise<void> {
-  const {remoteApp, storeFqdn, query, variables, apiVersion, outputFile} = input
+  const {remoteApp, storeFqdn, query, variables, version, outputFile} = input
 
   renderInfo({
     headline: 'Executing GraphQL operation.',
-    body: `App: ${remoteApp.title}\nStore: ${storeFqdn}`,
+    body: [
+      {
+        list: {
+          items: [
+            `App: ${remoteApp.title}`,
+            `Store: ${storeFqdn}`,
+            `API version: ${version ?? 'default (latest stable)'}`,
+          ],
+        },
+      },
+    ],
   })
 
   const adminSession = await createAdminSessionAsApp(remoteApp, storeFqdn)
 
+  if (version) await validateApiVersion(adminSession, version)
+
   const parsedVariables = await parseVariables(variables)
 
   validateSingleOperation(query)
@@ -53,7 +65,7 @@ export async function executeOperation(input: ExecuteOperationInput): Promise<vo
           query: parse(query),
           session: adminSession,
           variables: parsedVariables,
-          version: apiVersion,
+          version,
           responseOptions: {handleErrors: false},
         })
       },

packages/app/src/cli/services/graphql/common.test.ts

@@ -1,6 +1,7 @@
-import {createAdminSessionAsApp, validateSingleOperation} from './common.js'
+import {createAdminSessionAsApp, validateSingleOperation, validateApiVersion} from './common.js'
 import {OrganizationApp} from '../../models/organization.js'
 import {ensureAuthenticatedAdminAsApp} from '@shopify/cli-kit/node/session'
+import {supportedApiVersions} from '@shopify/cli-kit/node/api/admin'
 import {describe, test, expect, vi, beforeEach} from 'vitest'
 
 vi.mock('@shopify/cli-kit/node/session', async () => {
@@ -11,6 +12,14 @@ vi.mock('@shopify/cli-kit/node/session', async () => {
   }
 })
 
+vi.mock('@shopify/cli-kit/node/api/admin', async () => {
+  const actual = await vi.importActual('@shopify/cli-kit/node/api/admin')
+  return {
+    ...actual,
+    supportedApiVersions: vi.fn(),
+  }
+})
+
 describe('createAdminSessionAsApp', () => {
   const mockRemoteApp = {
     apiKey: 'test-api-key',
@@ -96,3 +105,29 @@ describe('validateSingleOperation', () => {
     expect(() => validateSingleOperation(fragmentOnly)).toThrow('must contain exactly one operation definition')
   })
 })
+
+describe('validateApiVersion', () => {
+  const mockAdminSession = {token: 'test-token', storeFqdn: 'test-store.myshopify.com'}
+
+  test('allows unstable version without validation', async () => {
+    await expect(validateApiVersion(mockAdminSession, 'unstable')).resolves.not.toThrow()
+
+    expect(supportedApiVersions).not.toHaveBeenCalled()
+  })
+
+  test('allows supported API version', async () => {
+    vi.mocked(supportedApiVersions).mockResolvedValue(['2024-01', '2024-04', '2024-07'])
+
+    await expect(validateApiVersion(mockAdminSession, '2024-04')).resolves.not.toThrow()
+
+    expect(supportedApiVersions).toHaveBeenCalledWith(mockAdminSession)
+  })
+
+  test('throws error when API version is not supported', async () => {
+    vi.mocked(supportedApiVersions).mockResolvedValue(['2024-01', '2024-04', '2024-07'])
+
+    await expect(validateApiVersion(mockAdminSession, '2023-01')).rejects.toThrow('Invalid API version: 2023-01')
+
+    expect(supportedApiVersions).toHaveBeenCalledWith(mockAdminSession)
+  })
+})

packages/app/src/cli/services/graphql/common.ts

@@ -1,6 +1,8 @@
 import {OrganizationApp} from '../../models/organization.js'
 import {ensureAuthenticatedAdminAsApp, AdminSession} from '@shopify/cli-kit/node/session'
 import {AbortError, BugError} from '@shopify/cli-kit/node/error'
+import {outputContent} from '@shopify/cli-kit/node/output'
+import {supportedApiVersions} from '@shopify/cli-kit/node/api/admin'
 import {parse} from 'graphql'
 
 /**
@@ -42,3 +44,26 @@ export function validateSingleOperation(graphqlOperation: string): void {
     )
   }
 }
+
+/**
+ * Validates that the specified API version is supported by the store.
+ * The 'unstable' version is always allowed without validation.
+ *
+ * @param adminSession - Admin session containing store credentials.
+ * @param version - The API version to validate.
+ * @throws AbortError if the version is not supported by the store.
+ */
+export async function validateApiVersion(
+  adminSession: {token: string; storeFqdn: string},
+  version: string,
+): Promise<void> {
+  if (version === 'unstable') return
+
+  const supportedVersions = await supportedApiVersions(adminSession)
+  if (supportedVersions.includes(version)) return
+
+  const firstLine = outputContent`Invalid API version: ${version}`.value
+  const secondLine = outputContent`Supported versions: ${supportedVersions.join(', ')}`.value
+
+  throw new AbortError(`${firstLine}\n${secondLine}`)
+}

packages/cli/README.md

@@ -378,7 +378,7 @@ FLAGS
 DESCRIPTION
   Execute GraphQL queries and mutations.
 
-  Executes a GraphQL query or mutation on the specified store, and writes the result to STDOUT or a file.
+  Executes an Admin API GraphQL query or mutation on the specified dev store.
 ```
 
 ## `shopify app function build`