refactor(deploy): restructure core app deploy and extract shared deploy checks

The app deploy command had grown into one long interleaved function.
Restructure it into a single createAppDeployment that validates, prepares and
ships, reporting through a shared checks seam, so the command reads as one
clear call.

This also lands the shared scaffolding the studio deploy will reuse: the checks
seam and step helpers (deployChecks), read-only target resolution
(resolveDeployTarget), and one home for the auto-update rules
(resolveAutoUpdates/getAutoUpdateIssueMessage). Workbench-specific validation
moves out of the CLI: viewDeployment goes into @sanity/workbench-cli.

Tighten the deploy seams while here: verifyOutputDir takes an isWorkbenchApp
boolean instead of a workbench object, checkBuiltOutput becomes a standalone
@sanity/workbench-cli/deploy export rather than a method on getWorkbench, and
DeployTarget models isExternal as its own field instead of folding it into the
type. Adds unit coverage for resolveDeployTarget and resolveTitleUpdate.

No behavior change — the integration deploy tests pass unchanged.

Author: gu-stav

packages/@sanity/cli/src/actions/build/__tests__/shouldAutoUpdate.test.ts

@@ -1,7 +1,7 @@
 import {type Output} from '@sanity/cli-core'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {shouldAutoUpdate} from '../shouldAutoUpdate'
+import {resolveAutoUpdates, shouldAutoUpdate} from '../shouldAutoUpdate'
 import {type BuildFlags} from '../types'
 
 describe('shouldAutoUpdate', () => {
@@ -236,3 +236,55 @@ describe('shouldAutoUpdate', () => {
     })
   })
 })
+
+describe('resolveAutoUpdates', () => {
+  it('returns disabled with no issue when nothing is configured', () => {
+    expect(resolveAutoUpdates({cliConfig: {}, flags: {} as BuildFlags})).toEqual({
+      enabled: false,
+      issue: null,
+    })
+  })
+
+  it('reads deployment.autoUpdates without an issue', () => {
+    expect(
+      resolveAutoUpdates({cliConfig: {deployment: {autoUpdates: true}}, flags: {} as BuildFlags}),
+    ).toEqual({enabled: true, issue: null})
+    expect(
+      resolveAutoUpdates({cliConfig: {deployment: {autoUpdates: false}}, flags: {} as BuildFlags}),
+    ).toEqual({enabled: false, issue: null})
+  })
+
+  it('reports the deprecated top-level config', () => {
+    expect(resolveAutoUpdates({cliConfig: {autoUpdates: true}, flags: {} as BuildFlags})).toEqual({
+      enabled: true,
+      issue: {type: 'deprecated-config'},
+    })
+  })
+
+  it('reports a conflict when both configs are present, preferring the new value', () => {
+    expect(
+      resolveAutoUpdates({
+        cliConfig: {autoUpdates: true, deployment: {autoUpdates: false}},
+        flags: {} as BuildFlags,
+      }),
+    ).toEqual({enabled: false, issue: {type: 'conflicting-config'}})
+  })
+
+  it('reports the deprecated flag and takes its value', () => {
+    expect(
+      resolveAutoUpdates({cliConfig: {}, flags: {'auto-updates': true} as BuildFlags}),
+    ).toEqual({enabled: true, issue: {flag: '--auto-updates', type: 'deprecated-flag'}})
+    expect(
+      resolveAutoUpdates({cliConfig: {}, flags: {'auto-updates': false} as BuildFlags}),
+    ).toEqual({enabled: false, issue: {flag: '--no-auto-updates', type: 'deprecated-flag'}})
+  })
+
+  it('lets the flag take precedence over config, masking config issues', () => {
+    expect(
+      resolveAutoUpdates({
+        cliConfig: {autoUpdates: true, deployment: {autoUpdates: true}},
+        flags: {'auto-updates': false} as BuildFlags,
+      }),
+    ).toEqual({enabled: false, issue: {flag: '--no-auto-updates', type: 'deprecated-flag'}})
+  })
+})

packages/@sanity/cli/src/actions/build/shouldAutoUpdate.ts

@@ -9,23 +9,39 @@ import {type BuildFlags} from './types.js'
 interface AutoUpdateSources {
   cliConfig: CliConfig
   flags: BuildFlags | DeployFlags | DevFlags
-  output: Output
 }
 
 /**
- * Compares parameters from various sources to determine whether or not to auto-update.
- * @remarks Throws an error if both the old and new auto update config are used; throws a warning if the old config is used, or if the auto updates flags are used.
+ * The single auto-update configuration problem to surface, if any.
+ * Flag usage takes precedence over config problems: when the deprecated flag
+ * is passed, config is not consulted, so config issues are not reported.
+ */
+type AutoUpdateIssue =
+  | {flag: '--auto-updates' | '--no-auto-updates'; type: 'deprecated-flag'}
+  | {type: 'conflicting-config'}
+  | {type: 'deprecated-config'}
+
+export interface AutoUpdateSettings {
+  enabled: boolean
+  issue: AutoUpdateIssue | null
+}
+
+/**
+ * Owns the auto-update rules: flag-over-config precedence, the deprecated
+ * top-level `autoUpdates` config, and the old/new config conflict.
+ * Returns plain facts so each surface (deploy warnings, dry-run checks)
+ * decides its own presentation.
+ *
  * @internal
  */
-export function shouldAutoUpdate({cliConfig, flags, output}: AutoUpdateSources): boolean {
-  // Auto updates in flags is deprecated; throw a warning if used
+export function resolveAutoUpdates({cliConfig, flags}: AutoUpdateSources): AutoUpdateSettings {
+  // Flags always take precedence over config
   if ('auto-updates' in flags) {
-    const flagUsed = flags['auto-updates'] ? '--auto-updates' : '--no-auto-updates'
-    output.warn(
-      `The ${flagUsed} flag is deprecated for deploy and build commands. Set the autoUpdates option in the deployment section of sanity.cli.ts or sanity.cli.js instead.`,
-    )
-    // Flags always take precedence over config
-    return Boolean(flags['auto-updates'])
+    const enabled = Boolean(flags['auto-updates'])
+    return {
+      enabled,
+      issue: {flag: enabled ? '--auto-updates' : '--no-auto-updates', type: 'deprecated-flag'},
+    }
   }
 
   const hasOldConfig = cliConfig && 'autoUpdates' in cliConfig
@@ -36,30 +52,74 @@ export function shouldAutoUpdate({cliConfig, flags, output}: AutoUpdateSources):
     cliConfig.deployment &&
     'autoUpdates' in cliConfig.deployment
 
-  if (hasOldConfig && hasNewConfig) {
-    output.error(
-      'Found both `autoUpdates` (deprecated) and `deployment.autoUpdates` in sanity.cli.js/.ts. Please remove the deprecated top level `autoUpdates` config.',
-      {
-        exit: 1,
-      },
-    )
+  if (hasNewConfig) {
+    return {
+      enabled: Boolean(cliConfig?.deployment?.autoUpdates),
+      issue: hasOldConfig ? {type: 'conflicting-config'} : null,
+    }
   }
 
   if (hasOldConfig) {
-    output.warn('The autoUpdates config has moved to deployment.autoUpdates.')
-    output.warn(`Please update sanity.cli.ts or sanity.cli.js and make the following change:
-  ${styleText('red', `-  autoUpdates: ${cliConfig.autoUpdates},`)}
-  ${styleText('green', `+  deployment: {autoUpdates: ${cliConfig.autoUpdates}}`)}
-`)
+    return {enabled: Boolean(cliConfig?.autoUpdates), issue: {type: 'deprecated-config'}}
   }
 
-  if (hasNewConfig) {
-    return Boolean(cliConfig?.deployment?.autoUpdates)
+  return {enabled: false, issue: null}
+}
+
+/**
+ * The user-facing message for an auto-update configuration problem.
+ * Shared by every surface that reports the issue (deploy warnings, dry-run
+ * checks) so the wording has one home.
+ *
+ * @internal
+ */
+export function getAutoUpdateIssueMessage(issue: AutoUpdateIssue): string {
+  switch (issue.type) {
+    case 'conflicting-config': {
+      return 'Found both `autoUpdates` (deprecated) and `deployment.autoUpdates` in sanity.cli.js/.ts. Please remove the deprecated top level `autoUpdates` config.'
+    }
+    case 'deprecated-config': {
+      return 'The autoUpdates config has moved to deployment.autoUpdates.'
+    }
+    case 'deprecated-flag': {
+      return `The ${issue.flag} flag is deprecated for deploy and build commands. Set the autoUpdates option in the deployment section of sanity.cli.ts or sanity.cli.js instead.`
+    }
   }
+}
 
-  if (hasOldConfig) {
-    return Boolean(cliConfig?.autoUpdates)
+/**
+ * Resolves the auto-update setting and prints any configuration problem.
+ * @remarks Throws an error if both the old and new auto update config are used; throws a warning if the old config is used, or if the auto updates flags are used.
+ * @internal
+ */
+export function shouldAutoUpdate({
+  cliConfig,
+  flags,
+  output,
+}: AutoUpdateSources & {output: Output}): boolean {
+  const {enabled, issue} = resolveAutoUpdates({cliConfig, flags})
+
+  switch (issue?.type) {
+    case 'conflicting-config': {
+      output.error(getAutoUpdateIssueMessage(issue), {exit: 1})
+      break
+    }
+    case 'deprecated-config': {
+      output.warn(getAutoUpdateIssueMessage(issue))
+      output.warn(`Please update sanity.cli.ts or sanity.cli.js and make the following change:
+  ${styleText('red', `-  autoUpdates: ${cliConfig.autoUpdates},`)}
+  ${styleText('green', `+  deployment: {autoUpdates: ${cliConfig.autoUpdates}}`)}
+`)
+      break
+    }
+    case 'deprecated-flag': {
+      output.warn(getAutoUpdateIssueMessage(issue))
+      break
+    }
+    default: {
+      break
+    }
   }
 
-  return false
+  return enabled
 }

packages/@sanity/cli/src/actions/deploy/__tests__/deployChecks.test.ts

@@ -0,0 +1,134 @@
+import {beforeEach, describe, expect, test, vi} from 'vitest'
+
+import {type UserApplication} from '../../../services/userApplications.js'
+import {checkAppTarget, createAggregatingChecks} from '../deployChecks.js'
+import {resolveAppDeployTarget} from '../resolveDeployTarget.js'
+
+vi.mock('../resolveDeployTarget.js', () => ({
+  resolveAppDeployTarget: vi.fn(),
+}))
+
+const mockResolveApp = vi.mocked(resolveAppDeployTarget)
+
+function application(overrides: Partial<UserApplication> = {}): UserApplication {
+  return {
+    appHost: 'my-studio',
+    createdAt: '2024-01-01T00:00:00Z',
+    id: 'app-1',
+    organizationId: null,
+    projectId: 'project-1',
+    title: null,
+    type: 'studio',
+    updatedAt: '2024-01-01T00:00:00Z',
+    urlType: 'internal',
+    ...overrides,
+  }
+}
+
+beforeEach(() => vi.clearAllMocks())
+
+describe('createAggregatingChecks', () => {
+  test('records checks without exiting', () => {
+    const checks = createAggregatingChecks()
+    checks.add({message: 'ok', name: 'a', status: 'pass'})
+    checks.add({message: 'bad', name: 'b', status: 'fail'})
+    expect(checks.all()).toHaveLength(2)
+  })
+
+  test('a thrown step becomes a fail check', async () => {
+    const checks = createAggregatingChecks()
+    const result = await checks.run('boom', async () => {
+      throw new Error('nope')
+    })
+    expect(result).toBeNull()
+    expect(checks.all()[0]).toMatchObject({name: 'boom', status: 'fail'})
+    expect(checks.all()[0]?.message).toContain('nope')
+  })
+
+  test('run returns the value when the step succeeds', async () => {
+    const checks = createAggregatingChecks()
+    const result = await checks.run('ok', async () => 42)
+    expect(result).toBe(42)
+    expect(checks.all()).toHaveLength(0)
+  })
+})
+
+describe('checkAppTarget', () => {
+  test('found → pass check, existing app and target', async () => {
+    const app = application({appHost: 'app-host', id: 'core-1', title: 'My App', type: 'coreApp'})
+    mockResolveApp.mockResolvedValue({application: app, type: 'found'})
+    const checks = createAggregatingChecks()
+
+    const {existingApp, target} = await checkAppTarget(checks, {
+      appId: 'core-1',
+      organizationId: 'org-1',
+    })
+
+    expect(existingApp).toBe(app)
+    expect(target).toEqual({
+      appId: 'core-1',
+      exists: true,
+      host: 'app-host',
+      isExternal: false,
+      type: 'coreApp',
+    })
+    expect(checks.all()[0]?.message).toContain('Deploys to existing application "My App"')
+  })
+
+  test('would-create → pass check, no existing app', async () => {
+    mockResolveApp.mockResolvedValue({type: 'would-create'})
+    const checks = createAggregatingChecks()
+
+    const {existingApp, target} = await checkAppTarget(checks, {
+      appId: undefined,
+      organizationId: 'org-1',
+    })
+
+    expect(existingApp).toBeNull()
+    expect(target).toEqual({
+      appId: null,
+      exists: false,
+      host: null,
+      isExternal: false,
+      type: 'coreApp',
+    })
+  })
+
+  test('needs-input → fail check (would prompt)', async () => {
+    mockResolveApp.mockResolvedValue({
+      existing: [application(), application()],
+      type: 'needs-input',
+    })
+    const checks = createAggregatingChecks()
+
+    const {target} = await checkAppTarget(checks, {appId: undefined, organizationId: 'org-1'})
+
+    expect(target).toBeNull()
+    expect(checks.all()[0]).toMatchObject({name: 'target', status: 'fail'})
+    expect(checks.all()[0]?.message).toContain('2 existing applications found')
+  })
+
+  test('invalid → fail check', async () => {
+    mockResolveApp.mockResolvedValue({
+      message: 'Cannot find app with app ID nope',
+      reason: 'app-not-found',
+      type: 'invalid',
+    })
+    const checks = createAggregatingChecks()
+
+    const {target} = await checkAppTarget(checks, {appId: 'nope', organizationId: 'org-1'})
+
+    expect(target).toBeNull()
+    expect(checks.all()[0]?.status).toBe('fail')
+  })
+
+  test('a 403 becomes a permissions fail check', async () => {
+    mockResolveApp.mockRejectedValue(Object.assign(new Error('forbidden'), {statusCode: 403}))
+    const checks = createAggregatingChecks()
+
+    const {target} = await checkAppTarget(checks, {appId: undefined, organizationId: 'org-1'})
+
+    expect(target).toBeNull()
+    expect(checks.all()[0]?.message).toContain('don’t have permission')
+  })
+})

packages/@sanity/cli/src/actions/deploy/__tests__/resolveDeployTarget.test.ts

@@ -0,0 +1,15 @@
+import {describe, expect, test} from 'vitest'
+
+import {resolveAppDeployTarget} from '../resolveDeployTarget.js'
+
+// The verdicts that hit the API (found / would-create / needs-input) are
+// exercised end-to-end by the deploy integration tests; this covers the guard
+// that short-circuits before any lookup.
+
+describe('resolveAppDeployTarget', () => {
+  test('no appId and no organizationId → blocked', async () => {
+    const result = await resolveAppDeployTarget({appId: undefined, organizationId: undefined})
+
+    expect(result).toEqual({message: 'app.organizationId is missing', type: 'blocked'})
+  })
+})