feat(migrate): add support for --api-version flag (#8781)

Author: RostiMelk

Diff for: packages/sanity/src/_internal/cli/commands/migration/constants.ts

@@ -1,2 +1,3 @@
 export const MIGRATIONS_DIRECTORY = 'migrations'
 export const MIGRATION_SCRIPT_EXTENSIONS = ['mjs', 'js', 'ts', 'cjs']
+export const DEFAULT_API_VERSION = 'v2024-01-29'

Diff for: packages/sanity/src/_internal/cli/commands/migration/runMigrationCommand.ts

@@ -15,9 +15,10 @@ import {hideBin} from 'yargs/helpers'
 import yargs from 'yargs/yargs'
 
 import {debug} from '../../debug'
-import {MIGRATIONS_DIRECTORY} from './constants'
+import {DEFAULT_API_VERSION, MIGRATIONS_DIRECTORY} from './constants'
 import {resolveMigrations} from './listMigrationsCommand'
 import {prettyFormat} from './prettyMutationFormatter'
+import {ensureApiVersionFormat} from './utils/ensureApiVersionFormat'
 import {isLoadableMigrationScript, resolveMigrationScript} from './utils/resolveMigrationScript'
 
 const helpText = `
@@ -27,6 +28,7 @@ Options
   --no-progress Don't output progress. Useful if you want debug your migration script and see the output of console.log() statements.
   --dataset <dataset> Dataset to migrate. Defaults to the dataset configured in your Sanity CLI config.
   --project <project id> Project ID of the dataset to migrate. Defaults to the projectId configured in your Sanity CLI config.
+  --api-version <version> API version to use when migrating. Defaults to ${DEFAULT_API_VERSION}.
   --no-confirm Skip the confirmation prompt before running the migration. Make sure you know what you're doing before using this flag.
   --from-export <export.tar.gz> Use a local dataset export as source for migration instead of calling the Sanity API. Note: this is only supported for dry runs.
 
@@ -60,6 +62,7 @@ function parseCliFlags(args: {argv?: string[]}) {
     .options('dataset', {type: 'string'})
     .options('from-export', {type: 'string'})
     .options('project', {type: 'string'})
+    .options('api-version', {type: 'string'})
     .options('confirm', {type: 'boolean', default: true}).argv
 }
 
@@ -81,6 +84,7 @@ const runMigrationCommand: CliCommandDefinition<CreateFlags> = {
     const dry = flags.dryRun
     const dataset = flags.dataset
     const project = flags.project
+    const apiVersion = flags.apiVersion
 
     if ((dataset && !project) || (project && !dataset)) {
       throw new Error('If either --dataset or --project is provided, both must be provided')
@@ -179,7 +183,7 @@ const runMigrationCommand: CliCommandDefinition<CreateFlags> = {
       projectId: project ?? projectConfig.projectId!,
       apiHost: projectConfig.apiHost!,
       token: projectConfig.token!,
-      apiVersion: 'v2024-01-29',
+      apiVersion: ensureApiVersionFormat(apiVersion ?? DEFAULT_API_VERSION),
     } as const
     if (dry) {
       dryRunHandler()

Diff for: packages/sanity/src/_internal/cli/commands/migration/utils/ensureApiVersionFormat.ts

@@ -0,0 +1,23 @@
+import {type APIConfig} from '@sanity/migrate'
+
+type ApiVersion = APIConfig['apiVersion']
+
+const VERSION_PATTERN = /^v\d+-\d+-\d+$|^vX$/ // Matches version strings like vYYYY-MM-DD or vX
+
+/**
+ * Ensures that the provided API version string is in the correct format.
+ * If the version does not start with 'v', it will be prefixed with 'v'.
+ * If the version does not match the expected pattern, an error will be thrown.
+ */
+export function ensureApiVersionFormat(version: string): ApiVersion {
+  const normalizedVersion = version.startsWith('v') ? version : `v${version}`
+
+  // Check if the version matches the expected pattern
+  if (!VERSION_PATTERN.test(normalizedVersion)) {
+    throw new Error(
+      `Invalid API version format: ${normalizedVersion}. Expected format: vYYYY-MM-DD or vX`,
+    )
+  }
+
+  return normalizedVersion as ApiVersion
+}