feat: Add migration for existing project (#1424)

Author: joe-yeager

api/__tests__/migrate.test.ts

@@ -19,6 +19,7 @@ describe('api/migrate', () => {
   const mockAppId = 67890;
   const mockMigrationId = 54321;
   const mockPlatformVersion = '2025.2';
+  const convertedPlatformVersion = 'V2025_2';
   const mockProjectName = 'Test Project';
   const mockComponentUids = { 'component-1': 'uid-1', 'component-2': 'uid-2' };
 
@@ -51,10 +52,16 @@ describe('api/migrate', () => {
       // @ts-expect-error Mock
       httpMock.get.mockResolvedValue(mockResponse);
 
-      const result = await listAppsForMigration(mockAccountId);
+      const result = await listAppsForMigration(
+        mockAccountId,
+        mockPlatformVersion
+      );
 
       expect(http.get).toHaveBeenCalledWith(mockAccountId, {
         url: 'dfs/migrations/v2/list-apps',
+        params: {
+          platformVersion: convertedPlatformVersion,
+        },
       });
       expect(result).toEqual(mockResponse);
     });
@@ -76,7 +83,7 @@ describe('api/migrate', () => {
         url: 'dfs/migrations/v2/migrations',
         data: {
           applicationId: mockAppId,
-          platformVersion: 'V2025_2',
+          platformVersion: convertedPlatformVersion,
         },
       });
       expect(result).toEqual(mockResponse);
@@ -171,7 +178,7 @@ describe('api/migrate', () => {
       const mockResponse: MigrationStatus = {
         id: mockMigrationId,
         status: MIGRATION_STATUS.FAILURE,
-        projectErrorsDetail: 'Error details',
+        projectErrorDetail: 'Error details',
         componentErrorDetails: {
           'component-1': 'Component error',
         },

api/migrate.ts

@@ -5,6 +5,8 @@ import {
 } from '@hubspot/local-dev-lib/constants/projects';
 import { http } from '@hubspot/local-dev-lib/http';
 import { MIGRATION_STATUS } from '@hubspot/local-dev-lib/types/Migration';
+import { logger } from '@hubspot/local-dev-lib/logger';
+import util from 'util';
 
 const MIGRATIONS_API_PATH_V2 = 'dfs/migrations/v2';
 
@@ -72,7 +74,7 @@ export interface MigrationSuccess extends MigrationBaseStatus {
 
 export interface MigrationFailed extends MigrationBaseStatus {
   status: typeof MIGRATION_STATUS.FAILURE;
-  projectErrorsDetail?: string;
+  projectErrorDetail: string;
   componentErrorDetails: Record<string, string>;
 }
 
@@ -82,11 +84,24 @@ export type MigrationStatus =
   | MigrationSuccess
   | MigrationFailed;
 
+export function isMigrationStatus(error: unknown): error is MigrationStatus {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'id' in error &&
+    'status' in error
+  );
+}
+
 export async function listAppsForMigration(
-  accountId: number
+  accountId: number,
+  platformVersion: string
 ): HubSpotPromise<ListAppsResponse> {
   return http.get<ListAppsResponse>(accountId, {
     url: `${MIGRATIONS_API_PATH_V2}/list-apps`,
+    params: {
+      platformVersion: mapPlatformVersionToEnum(platformVersion),
+    },
   });
 }
 
@@ -128,11 +143,15 @@ export async function continueMigration(
   });
 }
 
-export function checkMigrationStatusV2(
+export async function checkMigrationStatusV2(
   accountId: number,
   id: number
 ): HubSpotPromise<MigrationStatus> {
-  return http.get<MigrationStatus>(accountId, {
+  const response = await http.get<MigrationStatus>(accountId, {
     url: `${MIGRATIONS_API_PATH_V2}/migrations/${id}/status`,
   });
+
+  logger.debug(util.inspect(response.data, { depth: null }));
+
+  return response;
 }

commands/__tests__/project.test.ts

@@ -11,6 +11,7 @@ import open from '../project/open';
 import * as dev from '../project/dev';
 import add from '../project/add';
 import migrateApp from '../project/migrateApp';
+import migrate from '../project/migrate';
 import cloneApp from '../project/cloneApp';
 import installDeps from '../project/installDeps';
 
@@ -27,6 +28,7 @@ jest.mock('../project/dev');
 jest.mock('../project/add');
 jest.mock('../project/migrateApp', () => ({}));
 jest.mock('../project/cloneApp', () => ({}));
+jest.mock('../project/migrate', () => ({}));
 jest.mock('../project/installDeps');
 jest.mock('../../lib/commonOpts');
 
@@ -68,6 +70,7 @@ describe('commands/project', () => {
       ['migrateApp', migrateApp],
       ['cloneApp', cloneApp],
       ['installDeps', installDeps],
+      ['migrate', migrate],
     ];
 
     it('should demand the command takes one positional argument', () => {

commands/app/__tests__/migrate.test.ts

@@ -1,11 +1,10 @@
 import { ArgumentsCamelCase, Argv } from 'yargs';
 import { handler, builder } from '../migrate';
 import { getAccountConfig } from '@hubspot/local-dev-lib/config';
-import { migrateApp2025_2 } from '../../../lib/app/migrate';
+import { migrateApp2025_2, MigrateAppArgs } from '../../../lib/app/migrate';
 import { migrateApp2023_2 } from '../../../lib/app/migrate_legacy';
 import { logger } from '@hubspot/local-dev-lib/logger';
 import { EXIT_CODES } from '../../../lib/enums/exitCodes';
-import { MigrateAppOptions } from '../../../types/Yargs';
 import { PLATFORM_VERSIONS } from '@hubspot/local-dev-lib/constants/projects';
 
 jest.mock('@hubspot/local-dev-lib/config');
@@ -38,7 +37,7 @@ describe('commands/app/migrate', () => {
 
       await handler({
         derivedAccountId: mockAccountId,
-      } as ArgumentsCamelCase<MigrateAppOptions>);
+      } as ArgumentsCamelCase<MigrateAppArgs>);
 
       expect(mockedLogger.error).toHaveBeenCalled();
       expect(exitSpy).toHaveBeenCalledWith(EXIT_CODES.ERROR);
@@ -49,7 +48,7 @@ describe('commands/app/migrate', () => {
       await handler({
         derivedAccountId: mockAccountId,
         platformVersion: PLATFORM_VERSIONS.v2025_2,
-      } as ArgumentsCamelCase<MigrateAppOptions>);
+      } as ArgumentsCamelCase<MigrateAppArgs>);
 
       expect(mockedMigrateApp2025_2).toHaveBeenCalledWith(
         mockAccountId,
@@ -62,7 +61,7 @@ describe('commands/app/migrate', () => {
       await handler({
         derivedAccountId: mockAccountId,
         platformVersion: PLATFORM_VERSIONS.v2023_2,
-      } as ArgumentsCamelCase<MigrateAppOptions>);
+      } as ArgumentsCamelCase<MigrateAppArgs>);
 
       expect(mockedMigrateApp2023_2).toHaveBeenCalledWith(
         mockAccountId,
@@ -80,7 +79,7 @@ describe('commands/app/migrate', () => {
       await handler({
         derivedAccountId: mockAccountId,
         platformVersion: PLATFORM_VERSIONS.v2023_2,
-      } as ArgumentsCamelCase<MigrateAppOptions>);
+      } as ArgumentsCamelCase<MigrateAppArgs>);
 
       expect(mockedLogger.error).toHaveBeenCalled();
       expect(exitSpy).toHaveBeenCalledWith(EXIT_CODES.ERROR);

commands/app/migrate.ts

@@ -15,8 +15,7 @@ import {
 import { i18n } from '../../lib/lang';
 import { ApiErrorContext, logError } from '../../lib/errorHandlers';
 import { EXIT_CODES } from '../../lib/enums/exitCodes';
-import { MigrateAppOptions } from '../../types/Yargs';
-import { migrateApp2025_2 } from '../../lib/app/migrate';
+import { migrateApp2025_2, MigrateAppArgs } from '../../lib/app/migrate';
 import { uiBetaTag, uiLink } from '../../lib/ui';
 import { migrateApp2023_2 } from '../../lib/app/migrate_legacy';
 
@@ -26,7 +25,7 @@ export const validMigrationTargets = [v2023_2, v2025_2, unstable];
 const command = 'migrate';
 const describe = undefined; // uiBetaTag(i18n(`commands.project.subcommands.migrateApp.header.text.describe`), false);
 
-export async function handler(options: ArgumentsCamelCase<MigrateAppOptions>) {
+export async function handler(options: ArgumentsCamelCase<MigrateAppArgs>) {
   const { derivedAccountId, platformVersion } = options;
   await trackCommandUsage('migrate-app', {}, derivedAccountId);
   const accountConfig = getAccountConfig(derivedAccountId);
@@ -86,7 +85,7 @@ export async function handler(options: ArgumentsCamelCase<MigrateAppOptions>) {
   return process.exit(EXIT_CODES.SUCCESS);
 }
 
-export function builder(yargs: Argv): Argv<MigrateAppOptions> {
+export function builder(yargs: Argv): Argv<MigrateAppArgs> {
   addConfigOptions(yargs);
   addAccountOptions(yargs);
   addUseEnvironmentOptions(yargs);
@@ -125,10 +124,10 @@ export function builder(yargs: Argv): Argv<MigrateAppOptions> {
     ],
   ]);
 
-  return yargs as Argv<MigrateAppOptions>;
+  return yargs as Argv<MigrateAppArgs>;
 }
 
-const migrateCommand: CommandModule<unknown, MigrateAppOptions> = {
+const migrateCommand: CommandModule<unknown, MigrateAppArgs> = {
   command,
   describe,
   handler,

commands/project.ts

@@ -13,6 +13,7 @@ const open = require('./project/open');
 const dev = require('./project/dev');
 const add = require('./project/add');
 const migrateApp = require('./project/migrateApp');
+const migrate = require('./project/migrate');
 const cloneApp = require('./project/cloneApp');
 const installDeps = require('./project/installDeps');
 
@@ -36,6 +37,7 @@ exports.builder = yargs => {
     .command(download)
     .command(open)
     .command(migrateApp)
+    .command(migrate)
     .command(cloneApp)
     .command(installDeps)
     .demandCommand(1, '');

commands/project/cloneApp.ts

@@ -31,7 +31,12 @@ import { extractZipArchive } from '@hubspot/local-dev-lib/archive';
 import { getAccountConfig } from '@hubspot/local-dev-lib/config';
 import SpinniesManager from '../../lib/ui/SpinniesManager';
 import { ArgumentsCamelCase, Argv, CommandModule } from 'yargs';
-import { CloneAppArgs } from '../../types/Yargs';
+import {
+  AccountArgs,
+  CommonArgs,
+  ConfigArgs,
+  EnvironmentArgs,
+} from '../../types/Yargs';
 import { logInvalidAccountError } from '../../lib/app/migrate';
 
 const i18nKey = 'commands.project.subcommands.cloneApp';
@@ -40,6 +45,14 @@ export const command = 'clone-app';
 export const describe = uiDeprecatedTag(i18n(`${i18nKey}.describe`), false);
 export const deprecated = true;
 
+export type CloneAppArgs = ConfigArgs &
+  EnvironmentArgs &
+  AccountArgs &
+  CommonArgs & {
+    dest: string;
+    appId: number;
+  };
+
 export const handler = async (options: ArgumentsCamelCase<CloneAppArgs>) => {
   const { derivedAccountId } = options;
   await trackCommandUsage('clone-app', {}, derivedAccountId);
@@ -54,7 +67,7 @@ export const handler = async (options: ArgumentsCamelCase<CloneAppArgs>) => {
   }
 
   if (!isAppDeveloperAccount(accountConfig)) {
-    logInvalidAccountError(i18nKey);
+    logInvalidAccountError();
     process.exit(EXIT_CODES.SUCCESS);
   }
 

commands/project/migrate.ts

@@ -0,0 +1,84 @@
+import { i18n } from '../../lib/lang';
+
+import { ArgumentsCamelCase, Argv, CommandModule } from 'yargs';
+import { logger } from '@hubspot/local-dev-lib/logger';
+import {
+  AccountArgs,
+  CommonArgs,
+  ConfigArgs,
+  EnvironmentArgs,
+} from '../../types/Yargs';
+import {
+  addAccountOptions,
+  addConfigOptions,
+  addGlobalOptions,
+} from '../../lib/commonOpts';
+import { migrateApp2025_2 } from '../../lib/app/migrate';
+import { getProjectConfig } from '../../lib/projects';
+import { PLATFORM_VERSIONS } from '@hubspot/local-dev-lib/constants/projects';
+import { logError } from '../../lib/errorHandlers';
+import { EXIT_CODES } from '../../lib/enums/exitCodes';
+
+export type ProjectMigrateArgs = CommonArgs &
+  AccountArgs &
+  EnvironmentArgs &
+  ConfigArgs & {
+    platformVersion: string;
+  };
+
+export const command = 'migrate';
+
+export const describe = undefined; // i18n('commands.project.subcommands.migrate.noProjectConfig')
+
+export async function handler(
+  options: ArgumentsCamelCase<ProjectMigrateArgs>
+): Promise<void> {
+  const projectConfig = await getProjectConfig();
+
+  if (!projectConfig.projectConfig) {
+    logger.error(
+      i18n('commands.project.subcommands.migrate.errors.noProjectConfig')
+    );
+    return process.exit(EXIT_CODES.ERROR);
+  }
+
+  const { derivedAccountId } = options;
+  try {
+    await migrateApp2025_2(
+      derivedAccountId,
+      {
+        ...options,
+        name: projectConfig?.projectConfig?.name,
+        platformVersion: options.platformVersion,
+      },
+      projectConfig
+    );
+  } catch (error) {
+    logError(error);
+    return process.exit(EXIT_CODES.ERROR);
+  }
+  return process.exit(EXIT_CODES.SUCCESS);
+}
+
+export function builder(yargs: Argv): Argv<ProjectMigrateArgs> {
+  addConfigOptions(yargs);
+  addAccountOptions(yargs);
+  addGlobalOptions(yargs);
+
+  yargs.option('platform-version', {
+    type: 'string',
+    choices: Object.values(PLATFORM_VERSIONS),
+    default: PLATFORM_VERSIONS.v2025_2,
+    hidden: true,
+  });
+
+  return yargs as Argv<ProjectMigrateArgs>;
+}
+const migrateAppCommand: CommandModule<unknown, ProjectMigrateArgs> = {
+  command,
+  describe,
+  handler,
+  builder,
+};
+
+export default migrateAppCommand;