@hubspot/cli 8.2.0 → 8.2.1-experimental.0

package/lib/CLIWebSocketServer.d.ts

@@ -5,11 +5,11 @@ export type CLIWebSocketMessage = {
 };
 declare class CLIWebSocketServer {
     private server?;
-    private instanceId;
+    private instanceId?;
     private logPrefix?;
     private debug?;
     constructor({ instanceId, logPrefix, debug, }: {
-        instanceId: string;
+        instanceId?: string;
         logPrefix?: string;
         debug?: boolean;
     });
@@ -17,12 +17,14 @@ declare class CLIWebSocketServer {
     private logError;
     sendMessage(websocket: WebSocket, message: CLIWebSocketMessage): void;
     private sendCliMetadata;
+    private bindPortManagerPort;
+    private bindEphemeralPort;
     start({ onConnection, onMessage, onClose, metadata, }: {
         onConnection?: (websocket: WebSocket) => void;
         onMessage?: (websocket: WebSocket, message: CLIWebSocketMessage) => boolean;
         onClose?: () => void;
         metadata?: Record<string, unknown>;
-    }): Promise<void>;
+    }): Promise<number>;
     shutdown(): void;
 }
 export default CLIWebSocketServer;

package/lib/CLIWebSocketServer.js

@@ -39,14 +39,40 @@ class CLIWebSocketServer {
             },
         });
     }
-    async start({ onConnection, onMessage, onClose, metadata, }) {
+    async bindPortManagerPort(instanceId) {
         const portManagerIsRunning = await isPortManagerServerRunning();
         if (!portManagerIsRunning) {
             throw new Error(lib.CLIWebsocketServer.errors.portManagerNotRunning(this.logPrefix));
         }
-        const portData = await requestPorts([{ instanceId: this.instanceId }]);
-        const port = portData[this.instanceId];
-        this.server = new WebSocketServer({ port });
+        const portData = await requestPorts([{ instanceId }]);
+        const port = portData[instanceId];
+        return { server: new WebSocketServer({ port }), port };
+    }
+    async bindEphemeralPort() {
+        const server = new WebSocketServer({ port: 0 });
+        await new Promise((resolve, reject) => {
+            const onListening = () => {
+                server.off('error', onError);
+                resolve();
+            };
+            const onError = (err) => {
+                server.off('listening', onListening);
+                reject(err);
+            };
+            server.once('listening', onListening);
+            server.once('error', onError);
+        });
+        const address = server.address();
+        if (!address || typeof address !== 'object') {
+            throw new Error(lib.CLIWebsocketServer.errors.failedToBindEphemeralPort(this.logPrefix));
+        }
+        return { server, port: address.port };
+    }
+    async start({ onConnection, onMessage, onClose, metadata, }) {
+        const { server, port } = this.instanceId
+            ? await this.bindPortManagerPort(this.instanceId)
+            : await this.bindEphemeralPort();
+        this.server = server;
         this.log(lib.CLIWebsocketServer.logs.startup(port));
         this.server.on('connection', (ws, req) => {
             const origin = req.headers.origin;
@@ -82,6 +108,7 @@ class CLIWebSocketServer {
                 onClose();
             }
         });
+        return port;
     }
     shutdown() {
         this.server?.close();

package/lib/accountAuth.d.ts

@@ -5,6 +5,8 @@ type AuthenticateNewAccountOptions = {
     providedPersonalAccessKey?: string;
     accountId?: number;
     setAsDefaultAccount?: boolean;
+    accountName?: string;
+    useDefaultAccountName?: boolean;
 };
-export declare function authenticateNewAccount({ env, providedPersonalAccessKey, accountId, setAsDefaultAccount, }: AuthenticateNewAccountOptions): Promise<HubSpotConfigAccount | null>;
+export declare function authenticateNewAccount({ env, providedPersonalAccessKey, accountId, setAsDefaultAccount, accountName: providedAccountName, useDefaultAccountName, }: AuthenticateNewAccountOptions): Promise<HubSpotConfigAccount | null>;
 export {};

package/lib/accountAuth.js

@@ -1,28 +1,52 @@
-import { updateConfigAccount, createEmptyConfigFile, getConfigFilePath, localConfigFileExists, globalConfigFileExists, setConfigAccountAsDefault, } from '@hubspot/local-dev-lib/config';
+import { updateConfigAccount, createEmptyConfigFile, getConfigFilePath, localConfigFileExists, globalConfigFileExists, setConfigAccountAsDefault, getConfigDefaultAccountIfExists, } from '@hubspot/local-dev-lib/config';
 import { getAccessToken, updateConfigWithAccessToken, } from '@hubspot/local-dev-lib/personalAccessKey';
 import { toKebabCase } from '@hubspot/local-dev-lib/text';
 import { handleMerge, handleMigration } from './configMigrate.js';
 import { debugError, logError } from './errorHandlers/index.js';
-import { personalAccessKeyPrompt } from './prompts/personalAccessKeyPrompt.js';
+import { isPromptExitError } from './errors/PromptExitError.js';
+import { legacyPersonalAccessKeyPrompt } from './prompts/personalAccessKeyPrompt.js';
 import { cliAccountNamePrompt } from './prompts/accountNamePrompt.js';
 import { setAsDefaultAccountPrompt } from './prompts/setAsDefaultAccountPrompt.js';
+import { awaitPersonalAccessKeyOverWebsocket } from './auth/awaitPersonalAccessKeyOverWebsocket.js';
 import { commands } from '../lang/en.js';
 import { uiLogger } from './ui/logger.js';
-async function updateConfigWithNewAccount(env, configAlreadyExists, providedPersonalAccessKey, accountId) {
-    try {
-        const { personalAccessKey } = providedPersonalAccessKey
-            ? { personalAccessKey: providedPersonalAccessKey }
-            : await personalAccessKeyPrompt({
+async function getPersonalAccessKey(env, accountId) {
+    if (process.env.BROWSER !== 'none') {
+        try {
+            return await awaitPersonalAccessKeyOverWebsocket({
                 env,
                 account: accountId,
             });
+        }
+        catch (e) {
+            if (isPromptExitError(e))
+                throw e;
+            debugError(e);
+        }
+    }
+    const { personalAccessKey } = await legacyPersonalAccessKeyPrompt({
+        env,
+        account: accountId,
+    });
+    return personalAccessKey;
+}
+async function updateConfigWithNewAccount(env, configAlreadyExists, providedPersonalAccessKey, accountId, providedAccountName, useDefaultAccountName) {
+    try {
+        const personalAccessKey = providedPersonalAccessKey ?? (await getPersonalAccessKey(env, accountId));
         const token = await getAccessToken(personalAccessKey, env);
         const defaultAccountName = token.hubName
             ? toKebabCase(token.hubName)
             : undefined;
-        const accountName = configAlreadyExists
-            ? undefined
-            : (await cliAccountNamePrompt(defaultAccountName)).name;
+        let accountName;
+        if (providedAccountName) {
+            accountName = providedAccountName;
+        }
+        else if (useDefaultAccountName && defaultAccountName) {
+            accountName = defaultAccountName;
+        }
+        else if (!configAlreadyExists) {
+            accountName = (await cliAccountNamePrompt(defaultAccountName)).name;
+        }
         const updatedConfig = await updateConfigWithAccessToken(token, personalAccessKey, env, accountName, !configAlreadyExists);
         if (!updatedConfig)
             return null;
@@ -36,6 +60,9 @@ async function updateConfigWithNewAccount(env, configAlreadyExists, providedPers
         return updatedConfig;
     }
     catch (e) {
+        if (isPromptExitError(e)) {
+            throw e;
+        }
         debugError(e);
         return null;
     }
@@ -73,7 +100,7 @@ async function handleConfigMigration() {
         return false;
     }
 }
-export async function authenticateNewAccount({ env, providedPersonalAccessKey, accountId, setAsDefaultAccount, }) {
+export async function authenticateNewAccount({ env, providedPersonalAccessKey, accountId, setAsDefaultAccount, accountName: providedAccountName, useDefaultAccountName, }) {
     const configMigrationSuccess = await handleConfigMigration();
     if (!configMigrationSuccess) {
         return null;
@@ -82,7 +109,7 @@ export async function authenticateNewAccount({ env, providedPersonalAccessKey, a
     if (!configAlreadyExists) {
         createEmptyConfigFile(true);
     }
-    const updatedConfig = await updateConfigWithNewAccount(env, configAlreadyExists, providedPersonalAccessKey, accountId);
+    const updatedConfig = await updateConfigWithNewAccount(env, configAlreadyExists, providedPersonalAccessKey, accountId, providedAccountName, useDefaultAccountName);
     if (!updatedConfig) {
         uiLogger.error(commands.account.subcommands.auth.errors.failedToUpdateConfig);
         return null;
@@ -93,12 +120,15 @@ export async function authenticateNewAccount({ env, providedPersonalAccessKey, a
         uiLogger.success(commands.account.subcommands.auth.success.configFileCreated(getConfigFilePath()));
         uiLogger.success(commands.account.subcommands.auth.success.configFileUpdated(newAccountId));
     }
-    else if (setAsDefaultAccount) {
-        setConfigAccountAsDefault(name);
-        uiLogger.log('');
-        uiLogger.success(commands.account.subcommands.auth.success.configFileUpdated(newAccountId));
+    else if (setAsDefaultAccount === true) {
+        const currentDefault = getConfigDefaultAccountIfExists();
+        if (currentDefault?.name !== name) {
+            setConfigAccountAsDefault(name);
+            uiLogger.log('');
+            uiLogger.success(commands.account.subcommands.auth.success.configFileUpdated(newAccountId));
+        }
     }
-    else {
+    else if (setAsDefaultAccount !== false) {
         await setAsDefaultAccountPrompt(name);
     }
     return updatedConfig;

package/lib/accountTargetDiscovery.d.ts

@@ -0,0 +1,15 @@
+import { DiscoverAccountTargetsOptions, DiscoverAccountTargetsResult } from '../types/AccountTargets.js';
+/**
+ * Discovers the candidate target accounts for a command, plus the recommended
+ * one to use when a single account is the obvious choice.
+ *
+ * Profiles take precedence: when the project defines profiles, the candidates
+ * are the profile accounts only. Otherwise they are ranked explicit account,
+ * then env config, then linked directory, then global default.
+ *
+ * Takes plain options (not yargs argv) and never prompts or exits, so both the
+ * CLI and MCP can call it. `recommended` is omitted when no account is the
+ * obvious choice (for example, several profiles). Throws when an explicit
+ * account is provided but not found in the config.
+ */
+export declare function discoverAccountTargets(options?: DiscoverAccountTargetsOptions): Promise<DiscoverAccountTargetsResult>;

package/lib/accountTargetDiscovery.js

@@ -0,0 +1,175 @@
+import path from 'path';
+import { getConfigAccountIfExists, getConfigDefaultAccountIfExists, } from '@hubspot/local-dev-lib/config';
+import { getHsSettingsFileIfExists } from '@hubspot/local-dev-lib/config/hsSettings';
+import { ENVIRONMENT_VARIABLES } from '@hubspot/local-dev-lib/constants/config';
+import { getAllHsProfiles, loadHsProfileFile, } from '@hubspot/project-parsing-lib/profiles';
+import { isTestAccountOrSandbox } from './accountTypes.js';
+import { isDirectoryLinked } from './link/linkUtils.js';
+import { lib } from '../lang/en.js';
+import { ACCOUNT_TARGET_CATEGORIES, ACCOUNT_TARGET_SELECTION_SOURCES, } from '../types/AccountTargets.js';
+function categorizeAccount(account) {
+    if (isTestAccountOrSandbox(account)) {
+        return ACCOUNT_TARGET_CATEGORIES.RECOMMENDED_TESTING;
+    }
+    if (!account.accountType) {
+        return ACCOUNT_TARGET_CATEGORIES.UNKNOWN;
+    }
+    return ACCOUNT_TARGET_CATEGORIES.PRODUCTION_WITH_CARE;
+}
+function candidateFromAccount(account, source, profileName) {
+    return {
+        accountId: account.accountId,
+        accountName: account.name,
+        accountType: account.accountType,
+        environment: account.env || undefined,
+        source,
+        category: categorizeAccount(account),
+        ...(profileName ? { profileName } : {}),
+    };
+}
+function candidateFromAccountId(accountId, source, profileName) {
+    const account = getConfigAccountIfExists(accountId);
+    if (account) {
+        return candidateFromAccount(account, source, profileName);
+    }
+    return {
+        accountId,
+        source,
+        category: ACCOUNT_TARGET_CATEGORIES.UNKNOWN,
+        ...(profileName ? { profileName } : {}),
+    };
+}
+function dedupeByAccountId(candidates) {
+    const seen = new Set();
+    return candidates.filter(candidate => {
+        if (seen.has(candidate.accountId)) {
+            return false;
+        }
+        seen.add(candidate.accountId);
+        return true;
+    });
+}
+async function gatherProfileCandidates(projectDir, projectConfig) {
+    const projectSourceDir = path.join(projectDir, projectConfig.srcDir);
+    const profileNames = await getAllHsProfiles(projectSourceDir);
+    const candidates = [];
+    for (const name of profileNames) {
+        let profile;
+        try {
+            profile = loadHsProfileFile(projectSourceDir, name);
+        }
+        catch {
+            continue;
+        }
+        if (profile && profile.accountId) {
+            candidates.push(candidateFromAccountId(profile.accountId, ACCOUNT_TARGET_SELECTION_SOURCES.PROFILE, name));
+        }
+    }
+    return candidates;
+}
+function resolveProfileRecommendation(profileCandidates, explicitProfileName) {
+    if (explicitProfileName) {
+        return profileCandidates.find(candidate => candidate.profileName === explicitProfileName);
+    }
+    if (profileCandidates.length === 1) {
+        return profileCandidates[0];
+    }
+    return undefined;
+}
+function resolveNonProfileRecommendation({ explicitCandidate, envCandidate, linkedCandidates, linkedDefaultAccountId, defaultCandidate, }) {
+    if (explicitCandidate) {
+        return explicitCandidate;
+    }
+    if (envCandidate) {
+        return envCandidate;
+    }
+    if (linkedCandidates.length > 0) {
+        if (linkedDefaultAccountId !== undefined) {
+            const linkedDefault = linkedCandidates.find(candidate => candidate.accountId === linkedDefaultAccountId);
+            if (linkedDefault) {
+                return linkedDefault;
+            }
+        }
+        if (linkedCandidates.length === 1) {
+            return linkedCandidates[0];
+        }
+        return undefined;
+    }
+    return defaultCandidate;
+}
+/**
+ * Discovers the candidate target accounts for a command, plus the recommended
+ * one to use when a single account is the obvious choice.
+ *
+ * Profiles take precedence: when the project defines profiles, the candidates
+ * are the profile accounts only. Otherwise they are ranked explicit account,
+ * then env config, then linked directory, then global default.
+ *
+ * Takes plain options (not yargs argv) and never prompts or exits, so both the
+ * CLI and MCP can call it. `recommended` is omitted when no account is the
+ * obvious choice (for example, several profiles). Throws when an explicit
+ * account is provided but not found in the config.
+ */
+export async function discoverAccountTargets(options = {}) {
+    const { explicitAccount, useEnv, profileName, projectDir, projectConfig } = options;
+    if (projectDir && projectConfig) {
+        const profileCandidates = await gatherProfileCandidates(projectDir, projectConfig);
+        if (profileCandidates.length > 0) {
+            return {
+                candidates: dedupeByAccountId(profileCandidates),
+                recommended: resolveProfileRecommendation(profileCandidates, profileName),
+            };
+        }
+    }
+    const envConfigActive = Boolean(useEnv) ||
+        process.env[ENVIRONMENT_VARIABLES.USE_ENVIRONMENT_HUBSPOT_CONFIG] ===
+            'true';
+    const ordered = [];
+    let explicitCandidate;
+    if (explicitAccount !== undefined && explicitAccount !== '') {
+        const account = getConfigAccountIfExists(explicitAccount);
+        if (!account) {
+            throw new Error(lib.accountTargetDiscovery.errors.explicitAccountNotFound(explicitAccount));
+        }
+        explicitCandidate = candidateFromAccount(account, ACCOUNT_TARGET_SELECTION_SOURCES.EXPLICIT_ACCOUNT);
+        ordered.push(explicitCandidate);
+    }
+    let envCandidate;
+    if (envConfigActive) {
+        const envAccount = getConfigDefaultAccountIfExists();
+        if (envAccount) {
+            envCandidate = candidateFromAccount(envAccount, ACCOUNT_TARGET_SELECTION_SOURCES.ENV_CONFIG);
+            ordered.push(envCandidate);
+        }
+    }
+    const settings = getHsSettingsFileIfExists();
+    const directoryIsLinked = isDirectoryLinked(settings);
+    const linkedCandidates = [];
+    if (directoryIsLinked) {
+        for (const accountId of settings.accounts) {
+            const candidate = candidateFromAccountId(accountId, ACCOUNT_TARGET_SELECTION_SOURCES.LINKED_DIRECTORY);
+            linkedCandidates.push(candidate);
+            ordered.push(candidate);
+        }
+    }
+    let defaultCandidate;
+    if (!envConfigActive) {
+        const defaultAccount = getConfigDefaultAccountIfExists();
+        if (defaultAccount) {
+            defaultCandidate = candidateFromAccount(defaultAccount, ACCOUNT_TARGET_SELECTION_SOURCES.GLOBAL_DEFAULT);
+            ordered.push(defaultCandidate);
+        }
+    }
+    return {
+        candidates: dedupeByAccountId(ordered),
+        recommended: resolveNonProfileRecommendation({
+            explicitCandidate,
+            envCandidate,
+            linkedCandidates,
+            linkedDefaultAccountId: directoryIsLinked
+                ? settings.localDefaultAccount
+                : undefined,
+            defaultCandidate,
+        }),
+    };
+}

package/lib/api/usageTracking.d.ts

@@ -0,0 +1,30 @@
+export type ConfigType = 'local' | 'global';
+export type ExecutionSource = 'ci' | 'mcp' | 'user';
+export type UsageTrackingMeta = {
+    action?: string;
+    os?: string;
+    nodeVersion?: string;
+    nodeMajorVersion?: string;
+    version?: string;
+    command?: string;
+    authType?: string;
+    step?: string;
+    assetType?: string;
+    mode?: string;
+    type?: string | number;
+    file?: boolean;
+    successful?: boolean;
+    configType?: ConfigType;
+    executionSource?: ExecutionSource;
+    platformVersion?: string;
+    executionTime?: number;
+};
+export type UsageTrackingRequest = {
+    portalId?: number;
+    accountId?: number;
+    userId?: number;
+    eventName: string;
+    eventClass: string;
+    meta: UsageTrackingMeta;
+};
+export declare function sendUsageEvent(request: UsageTrackingRequest): Promise<void>;

package/lib/api/usageTracking.js

@@ -0,0 +1,11 @@
+import { http as unauthedHttp } from '@hubspot/local-dev-lib/http/unauthed';
+const USAGE_PATH = 'local/dev/tools/proxy/v1/usage';
+export async function sendUsageEvent(request) {
+    try {
+        await unauthedHttp.post({
+            url: USAGE_PATH,
+            data: request,
+        });
+    }
+    catch (_e) { }
+}

package/lib/app/install.d.ts

@@ -0,0 +1,22 @@
+import type { HubSpotConfigAccount } from '@hubspot/local-dev-lib/types/Accounts';
+import type { IntermediateRepresentationNodeLocalDev } from '@hubspot/project-parsing-lib/translate';
+import type { AppInstallationState, AppIRNode } from '../../types/ProjectComponents.js';
+export type ScopeGroup = {
+    id: number;
+    name: string;
+};
+type CanUseStaticAuthTestAccountInstallOptions = {
+    accountConfig?: HubSpotConfigAccount;
+    appNode?: AppIRNode | null;
+    parentAccountId?: number;
+};
+export declare function getAppNodeFromProjectNodes(projectNodes: {
+    [key: string]: IntermediateRepresentationNodeLocalDev;
+}): AppIRNode | null;
+export declare function isStaticAuthApp(appNode?: AppIRNode | null): boolean;
+export declare function isOAuthApp(appNode?: AppIRNode | null): boolean;
+export declare function isPrivateApp(appNode?: AppIRNode | null): boolean;
+export declare function isMarketplaceApp(appNode?: AppIRNode | null): boolean;
+export declare function getAppInstallationState(isInstalledWithScopeGroups: boolean, previouslyAuthorizedScopeGroups: ScopeGroup[]): AppInstallationState;
+export declare function canUseStaticAuthTestAccountInstall({ accountConfig, appNode, parentAccountId, }: CanUseStaticAuthTestAccountInstallOptions): boolean;
+export {};

package/lib/app/install.js

@@ -0,0 +1,42 @@
+import { APP_AUTH_TYPES, APP_DISTRIBUTION_TYPES, APP_INSTALLATION_STATES, } from '../constants.js';
+import { isDeveloperTestAccount, isSandbox } from '../accountTypes.js';
+import { isAppIRNode } from '../projects/structure.js';
+export function getAppNodeFromProjectNodes(projectNodes) {
+    return Object.values(projectNodes).find(isAppIRNode) || null;
+}
+export function isStaticAuthApp(appNode) {
+    return appNode?.config.auth.type.toLowerCase() === APP_AUTH_TYPES.STATIC;
+}
+export function isOAuthApp(appNode) {
+    return appNode?.config.auth.type.toLowerCase() === APP_AUTH_TYPES.OAUTH;
+}
+export function isPrivateApp(appNode) {
+    return (appNode?.config.distribution?.toLowerCase() ===
+        APP_DISTRIBUTION_TYPES.PRIVATE);
+}
+export function isMarketplaceApp(appNode) {
+    return (appNode?.config.distribution?.toLowerCase() ===
+        APP_DISTRIBUTION_TYPES.MARKETPLACE);
+}
+export function getAppInstallationState(isInstalledWithScopeGroups, previouslyAuthorizedScopeGroups) {
+    if (isInstalledWithScopeGroups) {
+        return APP_INSTALLATION_STATES.INSTALLED;
+    }
+    if (previouslyAuthorizedScopeGroups.length > 0) {
+        return APP_INSTALLATION_STATES.INSTALLED_WITH_OUTDATED_SCOPES;
+    }
+    return APP_INSTALLATION_STATES.NOT_INSTALLED;
+}
+export function canUseStaticAuthTestAccountInstall({ accountConfig, appNode, parentAccountId, }) {
+    if (!accountConfig || !isStaticAuthApp(appNode)) {
+        return false;
+    }
+    const accountCanUseTestInstall = isDeveloperTestAccount(accountConfig) || isSandbox(accountConfig);
+    if (!accountCanUseTestInstall) {
+        return false;
+    }
+    if (parentAccountId === undefined) {
+        return true;
+    }
+    return accountConfig.parentAccountId === parentAccountId;
+}

package/lib/app/logs.d.ts

@@ -0,0 +1,38 @@
+import { AppLogEntry as ApiAppLogEntry, SystemType } from '@hubspot/local-dev-lib/types/AppLogs';
+export declare const SYSTEM_TYPE_DISPLAY_NAMES: {
+    [key: string]: string;
+};
+export declare const SYSTEM_TYPE_CHOICES: string[];
+export declare function parseSinceTime(sinceInput: string): {
+    startTime: number;
+    endTime: number;
+};
+export declare function transformApiLogEntry(apiLog: ApiAppLogEntry): {
+    id: string;
+    createdAt: number;
+    executionTimeMillis?: number;
+    portalId?: number;
+    traceId?: string;
+    status: 'SUCCESS' | 'ERROR';
+    errorType?: string;
+    errorMessage?: string;
+};
+export type AppLogsOptions = {
+    since?: string;
+    compact?: boolean;
+    json?: boolean;
+    limit?: number;
+    errorsOnly?: boolean;
+};
+export declare function toTypeChoice(systemType: string): string;
+export declare function toSystemType(choice: string): string;
+export declare function getTypeChoices(): {
+    name: string;
+    value: string;
+}[];
+export declare const handleLogsRequest: (accountId: number, appId: number, systemType: string, options: AppLogsOptions) => Promise<void>;
+export declare const tailAppLogs: (accountId: number, appId: number, systemType: string, options: AppLogsOptions) => Promise<void>;
+export type LogDetailsOptions = {
+    json?: boolean;
+};
+export declare const handleLogDetailsRequest: (accountId: number, appId: number, logId: string, systemType: SystemType, options: LogDetailsOptions) => Promise<void>;