feat(deploy): add --dry-run flag for instant deployability feedback

`sanity deploy --dry-run` answers "can this deploy" without deploying — a
fast feedback loop for agents and CI. It reuses the plan phase of the deploy
sequence read-only: target resolution becomes a verdict instead of a prompt or
creation, the schema worker validates and extracts without uploading, and the
output directory is listed instead of packed. Failures aggregate so one run
reports every problem, never prompts, and exits 2 when not deployable.

`--json` emits the {deployable, checks, target, files} report via oclif's
enableJsonFlag; the exit code is set without throwing so the full report still
reaches stdout on failure. The aggregating checks adapter is the only new seam
implementation — real deploys keep failing fast through the same steps.

Author: gu-stav

.changeset/pr-1255.md

@@ -0,0 +1,5 @@
+---
+'@sanity/cli': minor
+---
+
+feat(deploy): add --dry-run flag for instant deployability feedback

packages/@sanity/cli/src/actions/deploy/deployApp.ts

@@ -23,75 +23,115 @@ import {createUserApplicationForApp} from './createUserApplicationForApp.js'
 import {
   checkAutoUpdates,
   checkBuild,
+  checkOutputDir,
   checkPackageVersion,
+  createAggregatingChecks,
   createFailFastChecks,
   type DeployChecks,
   verifyOutputDir,
 } from './deployChecks.js'
 import {deployDebug} from './deployDebug.js'
+import {checkAppTarget, type DeployTarget} from './deployTargetChecks.js'
+import {type DryRunReport, isDeployable} from './dryRunReport.js'
 import {findUserApplicationForApp} from './findUserApplicationForApp.js'
-import {type DeployAppOptions} from './types.js'
+import {type DeployFileSummary} from './listDeploymentFiles.js'
+import {type DeployAppOptions, type DeployFlags} from './types.js'
 
 type Workbench = ReturnType<typeof getWorkbench>
 
 /**
- * Builds and deploys a Sanity application: a plan phase validates and produces
- * the deployable artifacts, then an execute phase ships them.
+ * Builds and deploys a Sanity application. A plan phase validates and produces
+ * the deployable artifacts; with `--dry-run` it runs read-only and returns a
+ * report instead of shipping.
  *
  * @internal
  */
-export async function deployApp(options: DeployAppOptions): Promise<void> {
-  const {cliConfig, output} = options
+export async function deployApp(options: DeployAppOptions): Promise<DryRunReport | undefined> {
+  const {cliConfig, flags, output} = options
+  const workbench = getWorkbench(cliConfig)
+
+  if (flags['dry-run']) {
+    const checks = createAggregatingChecks()
+    if (workbench) {
+      try {
+        workbench.assertDeployable()
+      } catch (err) {
+        checks.add({message: getErrorMessage(err), name: 'app-deployable', status: 'fail'})
+      }
+    }
+    const {files, target} = await planAppDeployment(options, checks, workbench, true)
+    return {
+      checks: checks.all(),
+      deployable: isDeployable(checks.all()),
+      dryRun: true,
+      files,
+      target,
+    }
+  }
 
   // A federated app with no entry, view or service would ship a remote with
   // nothing to load — fail before any prompts or API calls.
-  const workbench = getWorkbench(cliConfig)
   if (workbench) {
     try {
       workbench.assertDeployable()
     } catch (err) {
       output.error(getErrorMessage(err), {exit: exitCodes.USAGE_ERROR})
-      return
+      return undefined
     }
   }
 
   try {
     const checks = createFailFastChecks(output)
-    const plan = await planAppDeployment(options, checks, workbench)
-    if (plan) await executeAppDeployment(plan, options, workbench)
+    const {application, isAutoUpdating, manifest, version} = await planAppDeployment(
+      options,
+      checks,
+      workbench,
+      false,
+    )
+    if (application && version) {
+      await executeAppDeployment(
+        {application, isAutoUpdating, manifest, version},
+        options,
+        workbench,
+      )
+    }
   } catch (error) {
     // Don't throw a generic error when the user cancels a prompt
     if (error.name === 'ExitPromptError') {
       output.error('Deployment cancelled by user', {exit: 1})
-      return
+      return undefined
     }
     if (error instanceof CLIError) {
       const {message, ...errorOptions} = error
       output.error(message, {...errorOptions, exit: 1})
-      return
+      return undefined
     }
     deployDebug('Error deploying application', error)
     output.error(`Error deploying application: ${error}`, {exit: 1})
   }
+  return undefined
 }
 
-interface AppDeploymentPlan {
-  application: UserApplication
+interface AppPlanResult {
+  application: UserApplication | null
+  files: DeployFileSummary | null
   isAutoUpdating: boolean
   manifest: CoreAppManifest | undefined
-  version: string
+  target: DeployTarget | null
+  version: string | null
 }
 
 /**
- * Validates the app deploy and produces everything a deploy needs: the target
- * application (title synced from the manifest) and the resolved version. Steps
- * report through `checks`; a real deploy fails fast.
+ * The app deploy sequence, shared by real deploys and dry runs. Validations
+ * report through `checks` (fail fast for real deploys, aggregated for dry runs);
+ * side-effecting steps branch on `dryRun`.
  */
 async function planAppDeployment(
   options: DeployAppOptions,
   checks: DeployChecks,
   workbench: Workbench,
-): Promise<AppDeploymentPlan | null> {
+  dryRun: boolean,
+): Promise<AppPlanResult> {
   const {cliConfig, flags, output, projectRoot, sourceDir} = options
   const workDir = projectRoot.directory
   const organizationId = cliConfig.app?.organizationId
@@ -110,19 +150,27 @@ async function planAppDeployment(
       : {message: NO_ORGANIZATION_ID, name: 'organization-id', status: 'fail'},
   )
 
+  let application: UserApplication | null = null
+  let target: DeployTarget | null = null
   if (flags.external) {
     checks.add({message: EXTERNAL_APP_NOT_SUPPORTED, name: 'target', status: 'fail'})
+  } else if (dryRun) {
+    ;({existingApp: application, target} = await checkAppTarget(checks, {
+      appId: getAppId(cliConfig),
+      organizationId,
+    }))
+  } else {
+    application = await resolveAppApplication(options)
   }
 
-  let application = await resolveAppApplication(options)
-
   await checkBuild(checks, {
     build: () =>
       buildApp({
         autoUpdatesEnabled: isAutoUpdating,
         calledFromDeploy: true,
         cliConfig,
-        flags,
+        // Dry runs never prompt
+        flags: dryRun ? ({...flags, yes: true} as DeployFlags) : flags,
         outDir: sourceDir,
         output,
         workDir,
@@ -133,17 +181,58 @@ async function planAppDeployment(
     successMessage: 'App built',
   })
 
-  await verifyOutputDir({output, sourceDir, workbench})
+  let files: DeployFileSummary | null = null
+  if (dryRun) {
+    files = await checkOutputDir(checks, {sourceDir, workbench})
+  } else {
+    await verifyOutputDir({output, sourceDir, workbench})
+  }
+
+  let manifest: CoreAppManifest | undefined
+  let manifestFailed = false
+  try {
+    manifest = await extractCoreAppManifest({workDir})
+  } catch (err) {
+    deployDebug('Error extracting app manifest', err)
+    // Manifests aren't strictly essential, so a real deploy warns and continues
+    checks.add({
+      message: `Error extracting app manifest: ${getErrorMessage(err)}`,
+      name: 'app-manifest',
+      status: 'warn',
+    })
+    manifestFailed = true
+  }
+
+  const titleUpdate = application ? resolveTitleUpdate(manifest, application) : null
 
-  const manifest = await extractAppManifest(checks, workDir)
-  application = await syncAppTitle({application, manifest, output})
+  if (dryRun) {
+    if (!manifestFailed) {
+      checks.add({
+        message: titleUpdate
+          ? titleUpdate.from
+            ? `Would update application title from "${titleUpdate.from}" to "${titleUpdate.to}"`
+            : `Would set application title to "${titleUpdate.to}"`
+          : manifest
+            ? 'App manifest extracted'
+            : 'No app manifest (no icon or title in app configuration)',
+        name: 'app-manifest',
+        status: 'pass',
+      })
+    }
+  } else if (application && titleUpdate) {
+    application = await syncAppTitle(application, titleUpdate, output)
+  }
 
-  if (!application || !version) return null
-  return {application, isAutoUpdating, manifest, version}
+  return {application, files, isAutoUpdating, manifest, target, version}
 }
 
 async function executeAppDeployment(
-  plan: AppDeploymentPlan,
+  plan: {
+    application: UserApplication
+    isAutoUpdating: boolean
+    manifest: CoreAppManifest | undefined
+    version: string
+  },
   options: DeployAppOptions,
   workbench: Workbench,
 ): Promise<void> {
@@ -229,38 +318,12 @@ async function resolveAppApplication(options: DeployAppOptions): Promise<UserApp
   return application
 }
 
-/** Extracts the app manifest; a failure warns and continues (it isn't essential). */
-async function extractAppManifest(
-  checks: DeployChecks,
-  workDir: string,
-): Promise<CoreAppManifest | undefined> {
-  try {
-    return await extractCoreAppManifest({workDir})
-  } catch (err) {
-    deployDebug('Error extracting app manifest', err)
-    checks.add({
-      message: `Error extracting app manifest: ${getErrorMessage(err)}`,
-      name: 'app-manifest',
-      status: 'warn',
-    })
-    return undefined
-  }
-}
-
-/** Syncs the application title from the manifest when it has changed. */
-async function syncAppTitle({
-  application,
-  manifest,
-  output,
-}: {
-  application: UserApplication | null
-  manifest: CoreAppManifest | undefined
-  output: DeployAppOptions['output']
-}): Promise<UserApplication | null> {
-  if (!application) return application
-  const titleUpdate = resolveTitleUpdate(manifest, application)
-  if (!titleUpdate) return application
-
+/** Syncs the application title from the manifest to the user application. */
+async function syncAppTitle(
+  application: UserApplication,
+  titleUpdate: {from: string | null; to: string},
+  output: DeployAppOptions['output'],
+): Promise<UserApplication> {
   deployDebug('Updating application title from manifest', titleUpdate)
   output.log(
     titleUpdate.from

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

@@ -8,9 +8,9 @@ import {deployDebug} from './deployDebug.js'
 import {type DeployFileSummary, listDeploymentFiles} from './listDeploymentFiles.js'
 import {type DeployFlags} from './types.js'
 
-type DeployCheckStatus = 'fail' | 'pass' | 'skip' | 'warn'
+export type DeployCheckStatus = 'fail' | 'pass' | 'skip' | 'warn'
 
-interface DeployCheck {
+export interface DeployCheck {
   message: string
 
   /** Stable identifier for machine consumers; the message carries the details */