@hubspot/cli 8.0.11-experimental.1 → 8.0.12-experimental.0

package/lang/en.js

@@ -1,12 +1,12 @@
 import chalk from 'chalk';
 import { mapToUserFriendlyName } from '@hubspot/project-parsing-lib/transform';
-import { PLATFORM_VERSIONS } from '@hubspot/local-dev-lib/constants/projects';
+import { PLATFORM_VERSIONS } from '@hubspot/project-parsing-lib/constants';
 import { PERSONAL_ACCESS_KEY_AUTH_METHOD } from '@hubspot/local-dev-lib/constants/auth';
-import { ARCHIVED_HUBSPOT_CONFIG_YAML_FILE_NAME, GLOBAL_CONFIG_PATH, DEFAULT_HUBSPOT_CONFIG_YAML_FILE_NAME, } from '@hubspot/local-dev-lib/constants/config';
-import { uiAccountDescription, uiBetaTag, uiCommandReference, uiLink, UI_COLORS, uiAuthCommandReference, } from '../lib/ui/index.js';
-import { getProjectDetailUrl, getProjectSettingsUrl, getLocalDevUiUrl, } from '../lib/projects/urls.js';
+import { ARCHIVED_HUBSPOT_CONFIG_YAML_FILE_NAME, DEFAULT_HUBSPOT_CONFIG_YAML_FILE_NAME, GLOBAL_CONFIG_PATH, } from '@hubspot/local-dev-lib/constants/config';
+import { indent, UI_COLORS, uiAccountDescription, uiAuthCommandReference, uiBetaTag, uiCommandReference, uiLink, } from '../lib/ui/index.js';
+import { getLocalDevUiUrl, getProjectDetailUrl, getProjectSettingsUrl, } from '../lib/projects/urls.js';
 import { getProductUpdatesUrl } from '../lib/links.js';
-import { APP_DISTRIBUTION_TYPES, APP_AUTH_TYPES, PROJECT_CONFIG_FILE, PROJECT_WITH_APP, LEGACY_PUBLIC_APP_FILE, } from '../lib/constants.js';
+import { APP_AUTH_TYPES, APP_DISTRIBUTION_TYPES, LEGACY_PUBLIC_APP_FILE, PROJECT_CONFIG_FILE, PROJECT_WITH_APP, } from '../lib/constants.js';
 export const commands = {
     generalErrors: {
         srcIsProject: (src, command) => `"${src}" is in a project folder. Did you mean "hs project ${command}"?`,
@@ -186,6 +186,58 @@ export const commands = {
                     defaultAccountUpdated: (accountName) => `Default account updated to "${accountName}"`,
                 },
             },
+            link: {
+                describe: 'Link authenticated HubSpot accounts to the current directory',
+                verboseDescribe: `Link one or more authenticated HubSpot accounts to the current directory. Linked accounts are saved in a local ${chalk.bold('.hs/settings.json')} file (added to .gitignore automatically).\n\nThis lets the CLI know which account to use when you run commands from this directory, without changing the global default. Run ${uiCommandReference('hs account current')} to see the active configuration.`,
+                shared: {
+                    noLinkedAccounts: 'No HubSpot accounts are linked in this directory.',
+                    globalAccountsAvailable: (count) => `You have ${chalk.cyan(count.toString())} ${count === 1 ? 'account' : 'accounts'} in your global config.`,
+                    configurePrompt: `To configure this directory, run:\n${indent(1)}${uiCommandReference('hs account link')}`,
+                    deprecatedConfigNotSupported: (command) => `${uiCommandReference(command)} does not support deprecated config. Run ${uiCommandReference('hs config migrate')} to migrate to global config. Then re-run ${uiCommandReference(command)}`,
+                    writeSettingsFailed: (path, err) => `Failed to write to ${path}: ${err}`,
+                    savedToSettings: (path) => `Saved to ${path}`,
+                },
+                linkingDirectory: (dir) => `Linking HubSpot account(s) for directory:\n${indent(1)}${dir}`,
+                managingLinkedAccounts: (dir) => `Managing linked accounts for:\n${indent(1)}${dir}`,
+                settingsInfo: (path) => `\u2139 Accounts linked here are saved in ${path}`,
+                success: {
+                    created: (path) => `Linked to ${path} (created .hs and added to .gitignore).\n${indent(1)}Now when you work within this directory, the CLI will use the linked account(s).`,
+                },
+                errors: {
+                    authFailed: `Authentication failed to complete`,
+                },
+                events: {
+                    accountsLinked: (count) => `Linked ${count} account${count !== 1 ? 's' : ''}`,
+                    accountsUnlinked: (count) => `Unlinked ${count} account${count !== 1 ? 's' : ''}`,
+                    overrideAccountDetected: (accountId) => `\nCurrent default account (from .hsaccount):\n${indent(1)}${uiAccountDescription(accountId)}`,
+                    defaultAccountSet: (accountId) => `Linked default account set to ${chalk.cyan(uiAccountDescription(accountId))}`,
+                    defaultAccountRemoved: (isSelectionRequired) => `The linked default account was removed. ${isSelectionRequired ? 'A linked default account is required.\n' : ''}`,
+                    defaultAccountRemains: (accountId) => `Linked default account remains ${chalk.cyan(uiAccountDescription(accountId))}`,
+                    updatedLinkedAccounts: 'Updated linked accounts',
+                    noAccountsLinked: `All accounts have been unlinked. Your global config accounts will be used.\n${indent(1)}The ${chalk.bold('.hs')} directory is no longer needed and can be safely deleted.`,
+                    overrideFileRemoved: '.hsaccount file removed',
+                    invalidDefaultAccount: (accountId) => `Default account ${uiAccountDescription(accountId)} is not in the linked accounts list and has been reset. Please select a new default.`,
+                },
+                prompts: {
+                    howToProceed: 'How would you like to link an account?',
+                    whatToDo: 'Which action would you like to perform?',
+                    linkExisting: 'Link existing authenticated account(s)',
+                    authenticateNew: 'Authenticate and link a new account',
+                    cancel: 'Cancel',
+                    selectDefault: 'Select a linked default account',
+                    selectToLink: 'Select authenticated account(s) to link:',
+                    selectToUnlink: 'Select account(s) to unlink',
+                    alreadyLinked: '- Already linked',
+                    fromHsAccount: '(from .hsaccount)',
+                    newlyAuthenticated: '(just authenticated)',
+                    mustSelectOne: 'You must select at least one account to link',
+                    keepAsDefault: 'Keep this as the default?',
+                },
+            },
+            unlink: {
+                describe: 'Unlink HubSpot account(s) from the current directory',
+                verboseDescribe: `Remove one or more linked accounts from this directory's ${chalk.bold('.hs/settings.json')}. If the default account is removed, you will be prompted to select a new one.\n\nThis does not delete the account from the global config - it only removes the local association.`,
+            },
             remove: {
                 describe: 'Remove an account from the config.',
                 logs: {
@@ -1321,7 +1373,7 @@ export const commands = {
         },
     },
     api: {
-        describe: 'Make an authenticated HTTP request to the HubSpot API.',
+        describe: 'Make an authenticated HTTP request to any HubSpot API endpoint that supports PAKs.',
         verboseDescribe: `Make an authenticated HTTP request to any HubSpot API that supports PAKs using your CLI authentication.\n\nThis command is intended for testing and exploration of HubSpot APIs. It uses the authentication credentials configured in the CLI to make requests on your behalf.\n\nThe endpoint should be the API path, e.g. ${chalk.bold('/crm/v3/objects/contacts')}. The request will be authenticated using the account specified by ${uiCommandReference('--account')} or the default account.\n\nNote: The available endpoints depend on the scopes granted to your personal access key. If you receive a 403 error, check that your key includes the required scopes for the endpoint you are trying to reach. ${uiLink('Learn more about the HubSpot API', 'https://developers.hubspot.com/docs/api-reference/latest/overview')}`,
         positionals: {
             endpoint: {
@@ -1474,6 +1526,9 @@ export const commands = {
                 failedToFetchProjectList: 'Failed to fetch the list of available project templates. Please try again later.',
                 cannotNestProjects: (projectDir) => `A project already exists at ${projectDir}. Projects cannot be nested within other projects. Please choose a different destination and try again.`,
             },
+            warnings: {
+                betaPlatformVersion: (platformVersion) => `Your portal must be enrolled in the beta to use platform version ${platformVersion}. If you are not enrolled in the beta, your upload will fail. ${uiLink('Enroll in the beta', getProductUpdatesUrl('286886'))}`,
+            },
             logs: {
                 success: (projectName, projectDest) => `Project ${chalk.bold(projectName)} was successfully created in ${projectDest}`,
             },
@@ -1700,6 +1755,7 @@ export const commands = {
                 noFunctionsLinkText: 'Visit developer docs',
                 noFunctionsInProject: `There aren't any functions in this project\n\t- Run ${uiCommandReference('hs project logs --help')} to learn more about logs\n\t- ${uiLink('Visit developer docs', 'https://developers.hubspot.com/docs/platform/serverless-functions')} to learn more about serverless functions`,
                 noFunctionWithName: (name) => `No function with name "${name}"`,
+                functionNameRequired: `A function name is required. Pass ${uiCommandReference('--function=<name>')} or run without it to select one interactively.`,
                 functionNotDeployed: (name) => `The function with name "${name}" is not deployed`,
                 projectLogsManagerNotInitialized: 'Function called on ProjectLogsManager before initialization',
                 noDeployedBuild: 'This project has not been deployed yet. Deploy the project first, then try again.',
@@ -1745,6 +1801,7 @@ export const commands = {
             examples: {
                 default: 'Upload a project into your HubSpot account',
                 withProfile: 'Upload a project into your HubSpot account when using profiles',
+                withPreview: 'Upload and preview the build on a target portal',
             },
             logs: {
                 buildSucceeded: (buildId) => `Build #${buildId} succeeded\n`,
@@ -1766,6 +1823,12 @@ export const commands = {
                 profile: {
                     describe: 'Profile to target for this upload',
                 },
+                preview: {
+                    describe: 'Preview the build on a target portal after a successful upload',
+                },
+                target: {
+                    describe: 'Portal ID to preview the build on',
+                },
             },
         },
         watch: {
@@ -1899,6 +1962,13 @@ export const commands = {
             },
             createEslintConfigPrompt: (directories) => `ESLint configuration file not found in the following ${directories.length === 1 ? 'directory' : 'directories'}:\n${directories.map(d => `  - ${d}`).join('\n')}\n\nWould you like to set up the required ESLint configuration?`,
             eslintConfigCreated: (configPath) => `ESLint configuration created at ${configPath}`,
+            createEslintConfigRequiresV2Platform: (platformVersion) => {
+                if (!platformVersion) {
+                    return 'Automatic ESLint configuration requires a Developer Platform project (2025.2 or later) with platformVersion set in hsproject.json. Add an eslint.config.js file manually, or set platformVersion and try again.';
+                }
+                return `Automatic ESLint configuration is not available for platform version ${platformVersion}. Use Developer Platform 2025.2 or later, or add eslint.config.js manually.`;
+            },
+            failedToFetchRemoteEslintConfig: (platformVersion) => `Could not download the ESLint config from HubSpot project components for platform version ${platformVersion}. Check your network connection and try again, or add eslint.config.js manually.`,
             failedToCreateEslintConfig: (configPath) => `Failed to create ESLint configuration at ${configPath}`,
             eslintConfigRequired: 'ESLint configuration is required to run the lint command. Run the command again to create the configuration.',
         },
@@ -2029,6 +2099,25 @@ export const commands = {
                 force: 'skip confirmation prompt',
             },
         },
+        installStatus: {
+            describe: 'Check whether a static auth app in the current project is installed in the target account. This command must be run from within a HubSpot project directory.',
+            examples: {
+                default: 'Check install status for the static auth app in the current project',
+                json: 'Output install status as JSON',
+            },
+            errors: {
+                noProjectConfig: `No project config found. Run this command from within a HubSpot project directory, or use ${uiCommandReference('hs project create')} to create a new one.`,
+                unsupportedPlatformVersion: (platformVersion) => `This command is only supported for projects on platform version 2025.2 or later (detected: ${platformVersion}).`,
+                failedToParseProject: 'Failed to parse the project. Check your project configuration is valid and try again.',
+                noAppInProject: 'No app was found in the local project. Install status is only available for projects that contain an app.',
+                unsupportedAuthType: (authType) => `This command only supports static auth apps. Detected auth type: ${authType}.`,
+            },
+            success: {
+                installed: (appName, accountId) => `${chalk.bold(appName)} is installed in ${uiAccountDescription(accountId)}.`,
+                installedWithOutdatedScopes: (appName, accountId) => `${chalk.bold(appName)} is installed in ${uiAccountDescription(accountId)} with outdated scopes. Reinstall the app to grant the latest scopes.`,
+            },
+            notInstalled: (appName, accountId) => `${chalk.bold(appName)} is not installed in ${uiAccountDescription(accountId)}.`,
+        },
     },
     sandbox: {
         describe: 'Commands for managing sandboxes.',
@@ -2324,7 +2413,7 @@ export const commands = {
             configPathPrompt: '[--config-path] Enter the path to the test account config: ',
             createTestAccountFromConfigPrompt: 'How would you like to create your test account?',
             createFromConfigOption: 'Create test account from config file',
-            createFromScratchOption: 'Create test account from scratch',
+            createFromScratchOption: 'Select hub tiers manually',
             errors: {
                 configFileNotFound: (configPath) => `No test account config file exists at ${configPath}. Create a test account config file with the ${uiCommandReference('hs test-account create-config')} command.`,
                 configFileParseFailed: (configPath) => `Failed to parse test account config file at ${configPath}`,
@@ -3310,6 +3399,16 @@ export const lib = {
             updatedFileDependency: (packageName, relativePath) => `  Updated dependencies.${packageName}: file:${relativePath}`,
         },
     },
+    projectPreview: {
+        triggeringPreview: (buildId, targetPortalId) => `Previewing build #${buildId} on portal ${targetPortalId}`,
+        pollingStatus: (releaseTag, targetPortalId) => `Previewing ${releaseTag} on portal ${targetPortalId}`,
+        succeeded: (releaseTag, targetPortalId) => `Previewed ${releaseTag} on portal ${targetPortalId}`,
+        triggerFailed: 'Failed to trigger preview',
+        pollFailed: 'Failed to poll preview status',
+        timeout: 'Preview timed out after 5 minutes',
+        warning: 'The build succeeded but the preview failed. You can manually preview this build from the project UI.',
+        missingProjectId: 'Unable to preview: could not resolve the project ID.',
+    },
     importData: {
         errors: {
             incorrectAccountType: (derivedAccountId) => `The account ${uiAccountDescription(derivedAccountId)} is not a standard account, developer test account, or app developer account.`,
@@ -4056,6 +4155,7 @@ export const lib = {
     migrate: {
         componentsToBeMigrated: (components) => `${chalk.bold('The following features will be migrated:')} ${components}`,
         componentsThatWillNotBeMigrated: (components) => `[NOTE] These features are not yet supported for migration but will be available later: ${components}`,
+        legacyCrmCardMigrationDocs: () => `For more information on migrating legacy-crm-card components, follow ${uiLink('these docs', 'https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-legacy-crm-cards-to-app-cards')}`,
         sourceContentsMoved: (newLocation) => `The contents of your old source directory have been moved to ${newLocation}, move any required files to the new source directory.`,
         projectMigrationWarningTitle: (platformVersion) => `Important: Migrating to platformVersion ${platformVersion} is irreversible`,
         projectMigrationWarning: (platformVersion) => uiBetaTag(`Running the ${uiCommandReference('hs project migrate')} command will permanently upgrade your project to platformVersion ${platformVersion}. This action cannot be undone. To ensure you have access to your original files, they will be copied to a new directory (archive) for safekeeping.\n\nThis command will guide you through the process, prompting you to enter the required fields and will download the new project source code into your project source directory.`, false),
@@ -4070,7 +4170,7 @@ export const lib = {
                 doesNotExist: (account) => `Project does not exist in ${uiAccountDescription(account)}. Migrations are only supported for existing projects.`,
                 themesAlreadyMigrated: 'This project has already been migrated to the latest platform version.',
                 noProjectForThemesMigration: 'Theme migrations are only supported for projects. Please try again from a project directory.',
-                themesAndAppsNotAllowed: 'Support for migrating projects containing both themes and apps to the latest platform version is coming soon. Try again later.',
+                themesAndAppsNotAllowed: 'Projects containing both themes and apps cannot be migrated together. To migrate, split the project into separate theme-only and app-only projects, then run migrate on each individually.',
                 multipleApps: 'Multiple apps found in project, this is not allowed in 2025.2',
                 alreadyExists: (projectName) => `A project with name ${projectName} already exists. Please choose another name.`,
                 failedToMigrateThemes: 'Failed to migrate project themes. Please verify that your themes are properly formatted before trying again.',

package/lib/app/migrate.js

@@ -124,8 +124,13 @@ export async function selectAppToMigrate(allApps, derivedAccountId, appId) {
     const selectedApp = allApps.find(app => app.appId === appIdToMigrate);
     const migratableComponents = new Set();
     const unmigratableComponents = new Set();
+    let hasLegacyCrmCards = false;
     selectedApp?.migrationComponents.forEach(component => {
         const userFacingComponentType = mapToUserFacingType(component.componentType);
+        if (component.componentType === 'LEGACY_CRM_CARD' &&
+            !component.isSupported) {
+            hasLegacyCrmCards = true;
+        }
         const shouldDisplayComponent = !AUTO_GENERATED_COMPONENT_TYPES.includes(userFacingComponentType);
         if (shouldDisplayComponent) {
             if (component.isSupported) {
@@ -142,6 +147,9 @@ export async function selectAppToMigrate(allApps, derivedAccountId, appId) {
     if (unmigratableComponents.size !== 0) {
         uiLogger.log(lib.migrate.componentsThatWillNotBeMigrated(`\n - ${[...unmigratableComponents].join('\n - ')}`));
     }
+    if (hasLegacyCrmCards) {
+        uiLogger.info(lib.migrate.legacyCrmCardMigrationDocs());
+    }
     uiLogger.log('');
     const proceed = await confirmPrompt(lib.migrate.prompt.proceed, {
         defaultAnswer: false,

package/lib/doctor/Doctor.js

@@ -26,7 +26,7 @@ import { isServerRunningAtUrl } from '../http.js';
 import { WEBHOOKS_KEY, APP_KEY } from '@hubspot/project-parsing-lib/constants';
 import { validateProjectConfig } from '../projects/config.js';
 import { validateSourceDirectory, handleTranslate, } from '../projects/upload.js';
-import { isV2Project } from '../projects/platformVersion.js';
+import { isLegacyProject } from '@hubspot/project-parsing-lib/projects';
 import { validateProjectForProfile } from '../projects/projectProfiles.js';
 import { getAllHsProfiles } from '@hubspot/project-parsing-lib/profiles';
 const minMajorNodeVersion = 20;
@@ -534,7 +534,7 @@ export class Doctor {
             if (!this.validateProjectConfigWrapper(projectConfig, projectDir)) {
                 return;
             }
-            if (!isV2Project(projectConfig.platformVersion)) {
+            if (isLegacyProject(projectConfig.platformVersion)) {
                 this.diagnosis?.addProjectSection({
                     type: 'success',
                     message: lib.doctor.projectValidation.valid,

package/lib/getStartedV2Actions.js

@@ -13,7 +13,7 @@ import { getStaticAuthAppInstallUrl } from '../lib/app/urls.js';
 import { HUBSPOT_PROJECT_COMPONENTS_GITHUB_PATH, PROJECT_CONFIG_FILE, } from '../lib/constants.js';
 import { ProjectNestingError, ProjectConfigNotFoundError, ProjectValidationError, ProjectUploadError, ProjectBuildDeployError, } from './errors/ProjectErrors.js';
 import { getProjectConfig, validateProjectConfig, writeProjectConfig, } from '../lib/projects/config.js';
-import { isV2Project } from '../lib/projects/platformVersion.js';
+import { isLegacyProject } from '@hubspot/project-parsing-lib/projects';
 import { pollProjectBuildAndDeploy } from '../lib/projects/pollProjectBuildAndDeploy.js';
 import { handleProjectUpload } from '../lib/projects/upload.js';
 import { validateProjectDirectory } from '../lib/prompts/projectNameAndDestPrompt.js';
@@ -109,7 +109,7 @@ export async function uploadAndDeployAction({ accountId, projectDest, }) {
             uploadMessage: commands.getStarted.logs.initialUploadMessage,
             forceCreate: true,
             isUploadCommand: false,
-            sendIR: isV2Project(projectConfig.platformVersion),
+            sendIR: !isLegacyProject(projectConfig.platformVersion),
             skipValidation: false,
         });
         if (uploadError) {

package/lib/link/accountTableUtils.d.ts

@@ -0,0 +1,10 @@
+export interface AccountRow {
+    name: string;
+    accountId: string;
+}
+export declare function buildAccountRow(accountId: number, isDefault: boolean): AccountRow;
+export declare function buildAccountHeader(nameColumnWidth: number): string;
+export declare function getNameColumnWidth(rows: AccountRow[]): number;
+export declare function sortDefaultFirst<T extends number | {
+    accountId: number;
+}>(items: T[], defaultAccount: number | undefined): T[];

package/lib/link/accountTableUtils.js

@@ -0,0 +1,39 @@
+import { HUBSPOT_ACCOUNT_TYPE_STRINGS } from '@hubspot/local-dev-lib/constants/config';
+import { getConfigAccountIfExists } from '@hubspot/local-dev-lib/config';
+import chalk from 'chalk';
+import { commands } from '../../lang/en.js';
+import { indent } from '../ui/index.js';
+import { INK_COLORS } from '../../ui/styles.js';
+export function buildAccountRow(accountId, isDefault) {
+    const account = getConfigAccountIfExists(accountId);
+    let name = String(accountId);
+    if (account && account.accountType) {
+        const typeStr = HUBSPOT_ACCOUNT_TYPE_STRINGS[account.accountType];
+        name = `${account.name} [${typeStr}]`;
+    }
+    if (isDefault) {
+        name = `${name} (default)`;
+    }
+    return { name, accountId: String(accountId) };
+}
+export function buildAccountHeader(nameColumnWidth) {
+    const labels = commands.account.subcommands.list.labels;
+    const paddedName = chalk.bold(chalk.hex(INK_COLORS.INFO_BLUE)(labels.name.padEnd(nameColumnWidth)));
+    const accountId = chalk.bold(chalk.hex(INK_COLORS.INFO_BLUE)(labels.accountId));
+    return `${indent(1)}${paddedName}  ${accountId}`;
+}
+export function getNameColumnWidth(rows) {
+    const labels = commands.account.subcommands.list.labels;
+    return Math.max(labels.name.length, ...rows.map(r => r.name.length));
+}
+export function sortDefaultFirst(items, defaultAccount) {
+    return [...items].sort((a, b) => {
+        const aId = typeof a === 'number' ? a : a.accountId;
+        const bId = typeof b === 'number' ? b : b.accountId;
+        if (aId === defaultAccount)
+            return -1;
+        if (bId === defaultAccount)
+            return 1;
+        return 0;
+    });
+}

package/lib/link/index.d.ts

@@ -0,0 +1,14 @@
+import { HsSettingsFile } from '@hubspot/local-dev-lib/types/HsSettings';
+import { ActionHandlerParams, ActionResult, LinkArgs } from '../../types/Link.js';
+import { ArgumentsCamelCase } from 'yargs';
+export declare class ActionHandlers {
+    static link({ state, context, }: ActionHandlerParams): Promise<ActionResult>;
+    static unlink({ state }: ActionHandlerParams): Promise<ActionResult>;
+    static authenticate({ state, context, args, }: ActionHandlerParams): Promise<ActionResult>;
+    static cancel(): Promise<ActionResult>;
+}
+export declare function handleLinkFlow({ settings, accountOverrideId, args, }: {
+    settings: HsSettingsFile;
+    accountOverrideId: number | null;
+    args: ArgumentsCamelCase<LinkArgs>;
+}): Promise<ActionResult>;

package/lib/link/index.js

@@ -0,0 +1,154 @@
+import { getAllConfigAccounts, getConfigDefaultAccountIfExists, } from '@hubspot/local-dev-lib/config';
+import { confirmPrompt } from '../prompts/promptUtils.js';
+import { promptForAccountsToLink, promptForAccountsToUnlink, promptForAction, promptForDefaultAccount, } from './prompts.js';
+import { getDefaultAccountOverrideFilePath, removeDefaultAccountOverrideFile, } from '@hubspot/local-dev-lib/config/defaultAccountOverride';
+import { ENVIRONMENTS } from '@hubspot/local-dev-lib/constants/environments';
+import { authenticateNewAccount } from '../accountAuth.js';
+import { commands } from '../../lang/en.js';
+import { uiLogger } from '../ui/logger.js';
+export class ActionHandlers {
+    static async link({ state, context, }) {
+        const { eligibleAccounts, inEligibleAccounts } = context.globalAccountsList.reduce((accumulator, account) => {
+            if (state.accounts.includes(account.accountId)) {
+                accumulator.inEligibleAccounts.push(account);
+            }
+            else {
+                accumulator.eligibleAccounts.push(account);
+            }
+            return accumulator;
+        }, { eligibleAccounts: [], inEligibleAccounts: [] });
+        const toAdd = await promptForAccountsToLink(context, eligibleAccounts, inEligibleAccounts, state.localDefaultAccount);
+        const accounts = [...state.accounts, ...toAdd];
+        uiLogger.success(commands.account.subcommands.link.events.accountsLinked(toAdd.length));
+        const overrideFilePath = getDefaultAccountOverrideFilePath();
+        if (overrideFilePath &&
+            context.accountOverrideId &&
+            accounts.includes(context.accountOverrideId)) {
+            uiLogger.log(commands.account.subcommands.link.events.overrideAccountDetected(context.accountOverrideId));
+            uiLogger.log('');
+            const useOverride = await confirmPrompt(commands.account.subcommands.link.prompts.keepAsDefault);
+            removeDefaultAccountOverrideFile();
+            uiLogger.success(commands.account.subcommands.link.events.overrideFileRemoved);
+            if (useOverride) {
+                uiLogger.success(commands.account.subcommands.link.events.defaultAccountSet(context.accountOverrideId));
+                return {
+                    status: 'success',
+                    settings: {
+                        accounts,
+                        localDefaultAccount: context.accountOverrideId,
+                    },
+                };
+            }
+        }
+        const localDefaultAccount = await resolveDefaultAccount({
+            accounts,
+            currentDefault: state.localDefaultAccount,
+        });
+        return {
+            status: 'success',
+            settings: { accounts, localDefaultAccount },
+        };
+    }
+    static async unlink({ state }) {
+        const toRemove = await promptForAccountsToUnlink(state.accounts, state.localDefaultAccount);
+        if (toRemove.length === 0) {
+            return { status: 'noop' };
+        }
+        const remainingAccounts = state.accounts.filter(account => !toRemove.includes(account));
+        const defaultWasRemoved = state.localDefaultAccount !== undefined &&
+            toRemove.includes(state.localDefaultAccount);
+        // All accounts removed
+        if (remainingAccounts.length === 0) {
+            uiLogger.success(commands.account.subcommands.link.events.noAccountsLinked);
+            return {
+                status: 'success',
+                settings: {
+                    accounts: remainingAccounts,
+                    localDefaultAccount: undefined,
+                },
+            };
+        }
+        //  Default was NOT removed — accounts remain, default unchanged
+        if (!defaultWasRemoved) {
+            uiLogger.success(commands.account.subcommands.link.events.accountsUnlinked(toRemove.length));
+            uiLogger.success(commands.account.subcommands.link.events.defaultAccountRemains(state.localDefaultAccount));
+            return {
+                status: 'success',
+                settings: {
+                    accounts: remainingAccounts,
+                    localDefaultAccount: state.localDefaultAccount,
+                },
+            };
+        }
+        //  Default WAS removed — need a new default
+        uiLogger.warn(commands.account.subcommands.link.events.defaultAccountRemoved(remainingAccounts.length !== 1));
+        const localDefaultAccount = await resolveDefaultAccount({
+            accounts: remainingAccounts,
+            currentDefault: undefined,
+        });
+        if (remainingAccounts.length === 1) {
+            uiLogger.success(commands.account.subcommands.link.events.updatedLinkedAccounts);
+        }
+        return {
+            status: 'success',
+            settings: { accounts: remainingAccounts, localDefaultAccount },
+        };
+    }
+    static async authenticate({ state, context, args, }) {
+        const updatedConfig = await authenticateNewAccount({
+            env: args.qa ? ENVIRONMENTS.QA : ENVIRONMENTS.PROD,
+            setAsDefaultAccount: false,
+        });
+        if (!updatedConfig) {
+            return {
+                status: 'error',
+                reason: commands.account.subcommands.link.errors.authFailed,
+            };
+        }
+        const updatedContext = {
+            globalAccountsList: getAllConfigAccounts(),
+            globalDefaultAccount: getConfigDefaultAccountIfExists(),
+            accountOverrideId: context.accountOverrideId,
+            preselectedAccountId: updatedConfig.accountId,
+        };
+        return ActionHandlers.link({ state, context: updatedContext, args });
+    }
+    static async cancel() {
+        return {
+            status: 'noop',
+        };
+    }
+}
+export async function handleLinkFlow({ settings, accountOverrideId, args, }) {
+    const context = {
+        globalAccountsList: getAllConfigAccounts(),
+        globalDefaultAccount: getConfigDefaultAccountIfExists(),
+        accountOverrideId,
+    };
+    const accounts = settings.accounts ?? [];
+    // The default account must be one of the linked accounts. This can get
+    // out of sync if the settings file is manually edited.
+    const hasInvalidDefault = settings.localDefaultAccount !== undefined &&
+        !accounts.includes(settings.localDefaultAccount);
+    if (hasInvalidDefault) {
+        uiLogger.warn(commands.account.subcommands.link.events.invalidDefaultAccount(settings.localDefaultAccount));
+    }
+    const initialState = {
+        localDefaultAccount: hasInvalidDefault
+            ? undefined
+            : settings.localDefaultAccount,
+        accounts,
+    };
+    return runAction(initialState, context, args);
+}
+async function runAction(state, context, args) {
+    const action = await promptForAction(state);
+    return ActionHandlers[action]({ state, context, args });
+}
+async function resolveDefaultAccount({ accounts, currentDefault, prompt = '', }) {
+    if (accounts.length === 1) {
+        uiLogger.success(commands.account.subcommands.link.events.defaultAccountSet(accounts[0]));
+        return accounts[0];
+    }
+    return promptForDefaultAccount(accounts, currentDefault, prompt);
+}

package/lib/link/linkUtils.d.ts

@@ -0,0 +1,4 @@
+import { HsSettingsFile } from '@hubspot/local-dev-lib/types/HsSettings';
+export declare function isDirectoryLinked(settings: HsSettingsFile | null): settings is HsSettingsFile;
+export declare function hasDeprecatedConfigConflict(commandArgs: (string | number)[]): boolean;
+export declare function writeLinkedSettings(settings: HsSettingsFile, settingsPath: string): boolean;

package/lib/link/linkUtils.js

@@ -0,0 +1,24 @@
+import { localConfigFileExists } from '@hubspot/local-dev-lib/config';
+import { writeHsSettingsFile } from '@hubspot/local-dev-lib/config/hsSettings';
+import { uiLogger } from '../ui/logger.js';
+import { commands } from '../../lang/en.js';
+export function isDirectoryLinked(settings) {
+    return settings !== null && settings.accounts.length > 0;
+}
+export function hasDeprecatedConfigConflict(commandArgs) {
+    if (localConfigFileExists()) {
+        uiLogger.error(commands.account.subcommands.link.shared.deprecatedConfigNotSupported(`hs ${commandArgs.join(' ')}`));
+        return true;
+    }
+    return false;
+}
+export function writeLinkedSettings(settings, settingsPath) {
+    try {
+        writeHsSettingsFile(settings);
+        return true;
+    }
+    catch (err) {
+        uiLogger.error(commands.account.subcommands.link.shared.writeSettingsFailed(settingsPath, err));
+        return false;
+    }
+}

package/lib/link/prompts.d.ts

@@ -0,0 +1,7 @@
+import { HubSpotConfigAccount } from '@hubspot/local-dev-lib/types/Accounts';
+import { ActionName, LinkContext } from '../../types/Link.js';
+import { HsSettingsFile } from '@hubspot/local-dev-lib/types/HsSettings';
+export declare function promptForAction(state: HsSettingsFile): Promise<ActionName>;
+export declare function promptForDefaultAccount(accounts: number[], currentDefaultAccount: number | undefined, prompt?: string): Promise<number>;
+export declare function promptForAccountsToLink(context: LinkContext, eligibleAccounts: HubSpotConfigAccount[], inEligibleAccounts: HubSpotConfigAccount[], localDefaultAccount: number | undefined): Promise<number[]>;
+export declare function promptForAccountsToUnlink(accounts: number[], localDefaultAccount: number | undefined): Promise<number[]>;