feat(app-dev): add dry-run preview to dev sync (#21251)

Split out of #21240. Stacked on #21250 (review/merge that first).

`yarn twenty dev --once --dry-run` computes the migration plan and
prints the diff **without applying anything** (no migration, no
app-record update, no SDK generation). Also renders the diff on a normal
`dev --once` sync.

<img width="646" height="179" alt="image"
src="https://github.com/user-attachments/assets/59f3ddcd-2a5b-4b8a-b21a-c659abe16af0"
/>

packages/twenty-server/src/engine/core-modules/application/application-development/application-development.resolver.ts

@@ -133,7 +133,7 @@ export class ApplicationDevelopmentResolver {
 
   @Mutation(() => WorkspaceMigrationDTO)
   async syncApplication(
-    @Args() { manifest }: ApplicationInput,
+    @Args() { manifest, dryRun }: ApplicationInput,
     @AuthWorkspace() { id: workspaceId }: WorkspaceEntity,
   ): Promise<WorkspaceMigrationDTO> {
     await this.throttlePerApplication(
@@ -141,6 +141,21 @@ export class ApplicationDevelopmentResolver {
       workspaceId,
     );
 
+    if (dryRun === true) {
+      const { workspaceMigration } =
+        await this.applicationSyncService.synchronizeFromManifest({
+          workspaceId,
+          manifest,
+          dryRun: true,
+        });
+
+      return {
+        applicationUniversalIdentifier:
+          workspaceMigration.applicationUniversalIdentifier,
+        actions: workspaceMigration.actions,
+      };
+    }
+
     return this.cacheLockService.withLock(
       () => this.applyManifestSync(manifest, workspaceId),
       `app-sync:${workspaceId}`,

packages/twenty-server/src/engine/core-modules/application/application-development/dtos/application.input.ts

@@ -7,4 +7,7 @@ import { Manifest } from 'twenty-shared/application';
 export class ApplicationInput {
   @Field(() => GraphQLJSON, { nullable: false })
   manifest: Manifest;
+
+  @Field(() => Boolean, { nullable: true })
+  dryRun?: boolean;
 }

packages/twenty-server/src/engine/core-modules/application/application-manifest/application-manifest-migration.service.ts

@@ -162,10 +162,12 @@ export class ApplicationManifestMigrationService {
     manifest,
     workspaceId,
     ownerFlatApplication,
+    dryRun = false,
   }: {
     manifest: Manifest;
     workspaceId: string;
     ownerFlatApplication: FlatApplication;
+    dryRun?: boolean;
   }): Promise<{
     workspaceMigration: WorkspaceMigration;
     hasSchemaMetadataChanged: boolean;
@@ -225,6 +227,7 @@ export class ApplicationManifestMigrationService {
           workspaceId,
           dependencyAllFlatEntityMaps,
           additionalCacheDataMaps: { featureFlagsMap },
+          dryRun,
         },
       );
 
@@ -236,14 +239,16 @@ export class ApplicationManifestMigrationService {
     }
 
     this.logger.log(
-      `Metadata migration completed for application ${ownerFlatApplication.universalIdentifier}`,
+      `Metadata migration ${dryRun ? 'plan computed (dry run)' : 'completed'} for application ${ownerFlatApplication.universalIdentifier}`,
     );
 
-    await this.syncDefaultRoleAndSettingsCustomTab({
-      manifest,
-      workspaceId,
-      ownerFlatApplication,
-    });
+    if (!dryRun) {
+      await this.syncDefaultRoleAndSettingsCustomTab({
+        manifest,
+        workspaceId,
+        ownerFlatApplication,
+      });
+    }
 
     return {
       workspaceMigration: validateAndBuildResult.workspaceMigration,

packages/twenty-server/src/engine/core-modules/application/application-manifest/application-sync.service.ts

@@ -41,30 +41,38 @@ export class ApplicationSyncService {
     workspaceId,
     manifest,
     applicationRegistrationId,
+    dryRun = false,
   }: {
     workspaceId: string;
     manifest: Manifest;
     applicationRegistrationId?: string;
+    dryRun?: boolean;
   }): Promise<{
     workspaceMigration: WorkspaceMigration;
     hasSchemaMetadataChanged: boolean;
   }> {
-    const application = await this.syncApplication({
-      workspaceId,
-      manifest,
-      applicationRegistrationId,
-    });
-
-    const ownerFlatApplication: FlatApplication = application;
+    const ownerFlatApplication: FlatApplication = dryRun
+      ? await this.applicationService.findOneApplicationOrThrow({
+          universalIdentifier: manifest.application.universalIdentifier,
+          workspaceId,
+        })
+      : await this.syncApplication({
+          workspaceId,
+          manifest,
+          applicationRegistrationId,
+        });
 
     const syncResult =
       await this.applicationManifestMigrationService.syncMetadataFromManifest({
         manifest,
         workspaceId,
         ownerFlatApplication,
+        dryRun,
       });
 
-    this.logger.log('Application sync from manifest completed');
+    this.logger.log(
+      `Application sync from manifest ${dryRun ? 'plan computed (dry run)' : 'completed'}`,
+    );
 
     return syncResult;
   }
@@ -129,20 +137,13 @@ export class ApplicationSyncService {
       ).toString('utf-8'),
     ) as PackageJson;
 
-    const application = await this.applicationService.findByUniversalIdentifier(
+    const application = await this.applicationService.findOneApplicationOrThrow(
       {
         universalIdentifier: manifest.application.universalIdentifier,
         workspaceId,
       },
     );
 
-    if (!application) {
-      throw new ApplicationException(
-        `Application "${manifest.application.universalIdentifier}" is not installed in workspace "${workspaceId}". Install it first.`,
-        ApplicationExceptionCode.APP_NOT_INSTALLED,
-      );
-    }
-
     const resolvedRegistrationId =
       applicationRegistrationId ?? application.applicationRegistrationId;
 
@@ -165,17 +166,10 @@ export class ApplicationSyncService {
     workspaceId: string;
     applicationUniversalIdentifier: string;
   }): Promise<WorkspaceMigration> {
-    const application = await this.applicationService.findByUniversalIdentifier(
+    const application = await this.applicationService.findOneApplicationOrThrow(
       { universalIdentifier: applicationUniversalIdentifier, workspaceId },
     );
 
-    if (!isDefined(application)) {
-      throw new ApplicationException(
-        `Application with universalIdentifier ${applicationUniversalIdentifier} not found`,
-        ApplicationExceptionCode.ENTITY_NOT_FOUND,
-      );
-    }
-
     if (!application.canBeUninstalled) {
       throw new ApplicationException(
         'This application cannot be uninstalled.',

packages/twenty-server/src/engine/workspace-manager/workspace-migration/services/workspace-migration-validate-build-and-run-service.ts

@@ -358,6 +358,7 @@ export class WorkspaceMigrationValidateBuildAndRunService {
   public async validateBuildAndRunWorkspaceMigrationFromTo(
     args: WorkspaceMigrationOrchestratorBuildArgs & {
       idByUniversalIdentifierByMetadataName?: IdByUniversalIdentifierByMetadataName;
+      dryRun?: boolean;
     },
   ): Promise<
     | WorkspaceMigrationOrchestratorFailedResult
@@ -365,7 +366,8 @@ export class WorkspaceMigrationValidateBuildAndRunService {
         hasSchemaMetadataChanged: boolean;
       })
   > {
-    const { idByUniversalIdentifierByMetadataName, ...buildArgs } = args;
+    const { idByUniversalIdentifierByMetadataName, dryRun, ...buildArgs } =
+      args;
 
     const validateAndBuildResult =
       await this.workspaceMigrationBuildOrchestratorService
@@ -392,7 +394,7 @@ export class WorkspaceMigrationValidateBuildAndRunService {
       workspaceMigration: validateAndBuildResult.workspaceMigration,
     });
 
-    if (workspaceMigration.actions.length === 0) {
+    if (dryRun === true || workspaceMigration.actions.length === 0) {
       return {
         status: 'success',
         workspaceMigration,

packages/twenty-server/test/integration/metadata/suites/application/dry-run-manifest-sync.integration-spec.ts

@@ -0,0 +1,84 @@
+import { buildBaseManifest } from 'test/integration/metadata/suites/application/utils/build-base-manifest.util';
+import { buildDefaultObjectManifest } from 'test/integration/metadata/suites/application/utils/build-default-object-manifest.util';
+import { cleanupApplicationAndAppRegistration } from 'test/integration/metadata/suites/application/utils/cleanup-application-and-app-registration.util';
+import { setupApplicationForSync } from 'test/integration/metadata/suites/application/utils/setup-application-for-sync.util';
+import { syncApplication } from 'test/integration/metadata/suites/application/utils/sync-application.util';
+import { findManyObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/find-many-object-metadata.util';
+import { type Manifest } from 'twenty-shared/application';
+import { v4 as uuidv4 } from 'uuid';
+
+const TEST_APP_ID = uuidv4();
+const TEST_ROLE_ID = uuidv4();
+
+const buildManifest = (
+  overrides?: Partial<Pick<Manifest, 'objects' | 'fields'>>,
+) => buildBaseManifest({ appId: TEST_APP_ID, roleId: TEST_ROLE_ID, overrides });
+
+const findCustomObjectNames = async (): Promise<string[]> => {
+  const { objects } = await findManyObjectMetadata({
+    input: {
+      filter: { isCustom: { is: true } },
+      paging: { first: 100 },
+    },
+    gqlFields: 'id nameSingular',
+    expectToFail: false,
+  });
+
+  return objects.map((object) => object.nameSingular);
+};
+
+describe('Manifest sync - dry run', () => {
+  beforeEach(async () => {
+    await setupApplicationForSync({
+      applicationUniversalIdentifier: TEST_APP_ID,
+      name: 'Dry Run Test Application',
+      description: 'App for testing dry-run manifest sync',
+      sourcePath: 'dry-run-manifest-sync',
+    });
+  }, 60000);
+
+  afterEach(async () => {
+    await cleanupApplicationAndAppRegistration({
+      applicationUniversalIdentifier: TEST_APP_ID,
+    });
+  });
+
+  it('returns the planned actions without applying them', async () => {
+    const ticketObject = buildDefaultObjectManifest({
+      nameSingular: 'dryRunTicket',
+      namePlural: 'dryRunTickets',
+      labelSingular: 'Dry Run Ticket',
+      labelPlural: 'Dry Run Tickets',
+      description: 'A support ticket',
+    });
+
+    await syncApplication({
+      manifest: buildManifest({ objects: [ticketObject] }),
+      expectToFail: false,
+    });
+
+    const invoiceObject = buildDefaultObjectManifest({
+      nameSingular: 'dryRunInvoice',
+      namePlural: 'dryRunInvoices',
+      labelSingular: 'Dry Run Invoice',
+      labelPlural: 'Dry Run Invoices',
+      description: 'A billing invoice',
+    });
+
+    const dryRunResponse = await syncApplication({
+      manifest: buildManifest({ objects: [ticketObject, invoiceObject] }),
+      dryRun: true,
+      expectToFail: false,
+    });
+
+    expect(dryRunResponse.errors).toBeUndefined();
+    expect(dryRunResponse.data.syncApplication.actions.length).toBeGreaterThan(
+      0,
+    );
+
+    const customObjectNames = await findCustomObjectNames();
+
+    expect(customObjectNames).toContain('dryRunTicket');
+    expect(customObjectNames).not.toContain('dryRunInvoice');
+  }, 60000);
+});

packages/twenty-server/test/integration/metadata/suites/application/utils/sync-application-query-factory.util.ts

@@ -3,12 +3,14 @@ import { type Manifest } from 'twenty-shared/application';
 
 export const syncApplicationQueryFactory = ({
   manifest,
+  dryRun,
 }: {
   manifest: Manifest;
+  dryRun?: boolean;
 }) => ({
   query: gql`
-    mutation SyncApplication($manifest: JSON!) {
-      syncApplication(manifest: $manifest) {
+    mutation SyncApplication($manifest: JSON!, $dryRun: Boolean) {
+      syncApplication(manifest: $manifest, dryRun: $dryRun) {
         applicationUniversalIdentifier
         actions
       }
@@ -16,5 +18,6 @@ export const syncApplicationQueryFactory = ({
   `,
   variables: {
     manifest,
+    dryRun,
   },
 });

packages/twenty-server/test/integration/metadata/suites/application/utils/sync-application.util.ts

@@ -14,15 +14,18 @@ export const syncApplication = async ({
   manifest,
   expectToFail = false,
   token,
+  dryRun,
 }: {
   manifest: Manifest;
   expectToFail?: boolean;
   token?: string;
+  dryRun?: boolean;
 }): CommonResponseBody<{
   syncApplication: WorkspaceMigration;
 }> => {
   const graphqlOperation = syncApplicationQueryFactory({
     manifest,
+    dryRun,
   });
 
   const response = await makeMetadataAPIRequest(graphqlOperation, token);