feat: Add migration for existing project

api/__tests__/migrate.test.ts

@@ -171,7 +171,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

@@ -72,7 +72,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,6 +82,15 @@ 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
 ): HubSpotPromise<ListAppsResponse> {

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;

commands/project/migrateApp.ts

@@ -7,12 +7,12 @@ import {
 
 import { ArgumentsCamelCase, Argv, CommandModule } from 'yargs';
 import { logger } from '@hubspot/local-dev-lib/logger';
-import { MigrateAppOptions } from '../../types/Yargs';
 import {
   addAccountOptions,
   addConfigOptions,
   addUseEnvironmentOptions,
 } from '../../lib/commonOpts';
+import { MigrateAppArgs } from '../../lib/app/migrate';
 
 export const command = 'migrate-app';
 
@@ -23,7 +23,7 @@ export const describe = uiDeprecatedTag(
 );
 export const deprecated = true;
 
-export async function handler(yargs: ArgumentsCamelCase<MigrateAppOptions>) {
+export async function handler(yargs: ArgumentsCamelCase<MigrateAppArgs>) {
   logger.warn(
     i18n(`commands.project.subcommands.migrateApp.deprecationWarning`, {
       oldCommand: uiCommandReference('hs project migrate-app'),
@@ -33,7 +33,7 @@ export async function handler(yargs: ArgumentsCamelCase<MigrateAppOptions>) {
   await migrateHandler(yargs);
 }
 
-export function builder(yargs: Argv): Argv<MigrateAppOptions> {
+export function builder(yargs: Argv): Argv<MigrateAppArgs> {
   addConfigOptions(yargs);
   addAccountOptions(yargs);
   addUseEnvironmentOptions(yargs);
@@ -72,10 +72,10 @@ export function builder(yargs: Argv): Argv<MigrateAppOptions> {
     ],
   ]);
 
-  return yargs as Argv<MigrateAppOptions>;
+  return yargs as Argv<MigrateAppArgs>;
 }
 
-const migrateAppCommand: CommandModule<unknown, MigrateAppOptions> = {
+const migrateAppCommand: CommandModule<unknown, MigrateAppArgs> = {
   command,
   describe,
   deprecated,

lang/en.lyaml

@@ -650,6 +650,7 @@ en:
           componentsToBeMigrated: "The following component types will be migrated: {{ components }}"
           componentsThatWillNotBeMigrated: "[NOTE] These component types are not yet supported for migration but will be available later: {{ components }}"
           errors:
+            noAppsForProject: "No apps associated with project {{ projectName }}"
             noAppsEligible: "No apps in account {{ accountId }} are currently migratable"
             noAccountConfig: "There is no account associated with {{ accountId }} in the config file. Please choose another account and try again, or authenticate {{ accountId }} using {{ authCommand }}."
             invalidAccountTypeTitle: "{{#bold}}Developer account not targeted{{/bold}}"
@@ -676,11 +677,7 @@ en:
             copyingProjectFiles: "Copying migrated project files"
             copyingProjectFilesComplete: "Migrated project files copied"
             copyingProjectFilesFailed: "Unable to copy migrated project files"
-          unmigratableReasons:
-            upToDate: 'App is already up to date'
-            isPrivateApp: 'Private apps are not currently migratable'
-            listedInMarketplace: 'Listed apps are not currently migratable'
-            generic: "Unable to migrate app: {{ reasonCode }}"
+
         cloneApp:
           describe: "Clone a public app using the projects framework."
           examples:
@@ -717,6 +714,12 @@ en:
           examples:
             default: "Create a component within your project"
             withFlags: "Use --name and --type flags to bypass the prompt."
+        migrate:
+            describe: "Migrate an existing project to the new version of the projects framework."
+            errors:
+                noProjectConfig: "No project detected. Please run this command again from a project directory."
+            examples:
+                default: "Migrate an existing project to the new version of the projects framework."
         deploy:
           describe: "Deploy a project build."
           deployBuildIdPrompt: "[--build] Deploy which build?"