@hubspot/cli 7.10.0-beta.0 → 7.10.0-beta.1

package/lang/en.js

@@ -118,7 +118,7 @@ export const commands = {
                     },
                 },
                 success: {
-                    renamed: (name, newName) => `Account "${name}" renamed to "${newName}"`,
+                    renamed: (name, newName, nameWasSanitized) => `Account "${chalk.bold(name)}" successfully renamed to "${chalk.bold(newName)}"${nameWasSanitized ? ' (Sanitized to remove invalid characters)' : ''}.`,
                 },
             },
             use: {
@@ -1196,6 +1196,7 @@ export const commands = {
         setup: {
             describe: 'Setup the HubSpot development MCP servers.',
             installingDocSearch: 'Adding the docs-search mcp server',
+            codex: 'Codex CLI',
             claudeCode: 'Claude Code',
             cursor: 'Cursor',
             windsurf: 'Windsurf',
@@ -1217,7 +1218,11 @@ export const commands = {
                 configuredClaudeCode: 'Configured Claude Code',
                 claudeCodeNotFound: 'Claude Code not found - skipping configuration',
                 claudeCodeInstallFailed: 'Claude Code CLI not working - skipping configuration',
-                failedToConfigureClaudeDesktop: 'Failed to configure Claude Desktop',
+                // Codex
+                configuringCodex: 'Configuring Codex...',
+                configuredCodex: 'Configured Codex',
+                codexNotFound: 'Codex command not found - skipping configuration',
+                codexInstallFailed: 'Failed to configure Codex',
                 // Cursor
                 configuringCursor: 'Configuring Cursor...',
                 failedToConfigureCursor: 'Failed to configure Cursor',
@@ -2113,9 +2118,21 @@ export const commands = {
                 createFailure: 'Failed to create test account.',
             },
             options: {
-                configPath: 'The path to the test account config',
+                configPath: 'Path to config file (mutually exclusive with other flags)',
+                accountName: 'Name for the test account',
+                description: 'Description for the test account',
+                marketingLevel: 'Marketing Hub tier. Unprovided tiers default to ENTERPRISE. Choices: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
+                opsLevel: 'Operations Hub tier. Unprovided tiers default to ENTERPRISE. Choices: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
+                serviceLevel: 'Service Hub tier. Unprovided tiers default to ENTERPRISE. Choices: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
+                salesLevel: 'Sales Hub tier. Unprovided tiers default to ENTERPRISE. Choices: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
+                contentLevel: 'CMS Hub tier. Unprovided tiers default to ENTERPRISE. Choices: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
             },
             example: (configPath) => `Create a test account from the config file at ${configPath}`,
+            examples: {
+                withAllHubsEnterprise: 'Create a test account with all hubs at ENTERPRISE level',
+                withSpecificHubLevels: 'Create a test account with specific hub levels',
+            },
+            savedAccountNameDiffers: (originalName, savedName) => `Account name "${chalk.bold(originalName)}" was saved as "${chalk.bold(savedName)}" in config.`,
         },
         createConfig: {
             describe: 'Create a test account config file.',
@@ -2984,6 +3001,10 @@ export const lib = {
             header: 'Created the following components and features:',
             applicationLog: (componentType, uid, name) => `  - Created ${chalk.bold(componentType)} with uid ${chalk.bold(uid)} and name ${chalk.bold(name)}`,
             componentLog: (componentType, uid) => `  - Created ${chalk.bold(componentType)} feature with uid ${chalk.bold(uid)}`,
+            failedToUpdate: (hsMetaFile) => `Failed to update the uid in ${chalk.bold(hsMetaFile)}`,
+        },
+        generateSafeFilenameDifferentiator: {
+            failedToCheckFiles: 'Failed to check files for filename differentiator. Falling back to timestamp.',
         },
         validateProjectConfig: {
             configNotFound: `Unable to locate a project configuration file. Try running again from a project directory, or run ${uiCommandReference('hs project create')} to create a new project.`,

package/lib/constants.d.ts

@@ -139,3 +139,4 @@ export declare const LEGACY_PRIVATE_APP_FILE = "app.json";
 export declare const THEME_FILE = "theme.json";
 export declare const CMS_ASSETS_FILE = "cms-assets.json";
 export declare const LEGACY_CONFIG_FILES: string[];
+export declare const ACCOUNT_LEVEL_CHOICES: readonly ["FREE", "STARTER", "PROFESSIONAL", "ENTERPRISE"];

package/lib/constants.js

@@ -135,3 +135,9 @@ export const LEGACY_CONFIG_FILES = [
     LEGACY_PRIVATE_APP_FILE,
     LEGACY_PUBLIC_APP_FILE,
 ];
+export const ACCOUNT_LEVEL_CHOICES = [
+    'FREE',
+    'STARTER',
+    'PROFESSIONAL',
+    'ENTERPRISE',
+];

package/lib/mcp/__tests__/setup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/mcp/__tests__/setup.test.js

@@ -0,0 +1,127 @@
+import { execAsync } from '../../../mcp-server/utils/command.js';
+import { setupCodex, supportedTools } from '../setup.js';
+import SpinniesManager from '../../ui/SpinniesManager.js';
+import { logError } from '../../errorHandlers/index.js';
+import { commands } from '../../../lang/en.js';
+// Mock dependencies
+vi.mock('../../../mcp-server/utils/command.js');
+vi.mock('../../ui/SpinniesManager.js');
+vi.mock('../../ui/logger.js');
+vi.mock('../../errorHandlers/index.js');
+vi.mock('../../../lang/en.js', () => ({
+    commands: {
+        mcp: {
+            setup: {
+                codex: 'Codex CLI',
+                claudeCode: 'Claude Code',
+                cursor: 'Cursor',
+                vsCode: 'VS Code',
+                windsurf: 'Windsurf',
+                success: vi.fn(targets => `Success message for ${targets.join(', ')}`),
+                spinners: {
+                    configuringCodex: 'Configuring Codex...',
+                    configuredCodex: 'Configured Codex',
+                    codexNotFound: 'Codex command not found - skipping configuration',
+                    codexInstallFailed: 'Failed to configure Codex',
+                },
+            },
+        },
+    },
+}));
+const mockedExecAsync = vi.mocked(execAsync);
+const mockedSpinniesManager = vi.mocked(SpinniesManager);
+const mockedLogError = vi.mocked(logError);
+describe('lib/mcp/setup', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    describe('supportedTools', () => {
+        it('should include Codex in the supported tools list', () => {
+            const codexTool = supportedTools.find(tool => tool.value === 'codex');
+            expect(codexTool).toBeDefined();
+            expect(codexTool?.name).toBe(commands.mcp.setup.codex);
+            expect(codexTool?.value).toBe('codex');
+        });
+        it('should have Codex as the first tool in the list', () => {
+            expect(supportedTools[0].value).toBe('codex');
+        });
+        it('should contain all expected tools', () => {
+            const toolValues = supportedTools.map(tool => tool.value);
+            expect(toolValues).toContain('codex');
+            expect(toolValues).toContain('claude');
+            expect(toolValues).toContain('cursor');
+            expect(toolValues).toContain('vscode');
+            expect(toolValues).toContain('windsurf');
+        });
+    });
+    describe('setupCodex', () => {
+        const mockMcpCommand = {
+            command: 'test-command',
+            args: ['--arg1', '--arg2'],
+        };
+        it('should successfully configure Codex when command is available', async () => {
+            mockedExecAsync.mockResolvedValueOnce({
+                stdout: 'codex version 1.0.0',
+                stderr: '',
+            }); // version check
+            mockedExecAsync.mockResolvedValueOnce({ stdout: '', stderr: '' }); // mcp add command
+            const result = await setupCodex(mockMcpCommand);
+            expect(result).toBe(true);
+            expect(mockedSpinniesManager.add).toHaveBeenCalledWith('codexSpinner', {
+                text: commands.mcp.setup.spinners.configuringCodex,
+            });
+            expect(mockedExecAsync).toHaveBeenCalledWith('codex --version');
+            expect(mockedExecAsync).toHaveBeenCalledWith('codex mcp add "HubSpotDev" -- test-command --arg1 --arg2 --ai-agent codex');
+            expect(mockedSpinniesManager.succeed).toHaveBeenCalledWith('codexSpinner', {
+                text: commands.mcp.setup.spinners.configuredCodex,
+            });
+        });
+        it('should use default mcp command when none provided', async () => {
+            mockedExecAsync.mockResolvedValueOnce({
+                stdout: 'codex version 1.0.0',
+                stderr: '',
+            }); // version check
+            mockedExecAsync.mockResolvedValueOnce({ stdout: '', stderr: '' }); // mcp add command
+            const result = await setupCodex();
+            expect(result).toBe(true);
+            expect(mockedExecAsync).toHaveBeenCalledWith('codex mcp add "HubSpotDev" -- hs mcp start --ai-agent codex');
+        });
+        it('should handle codex command not found', async () => {
+            const error = new Error('Command not found: codex');
+            mockedExecAsync.mockRejectedValueOnce(error);
+            const result = await setupCodex(mockMcpCommand);
+            expect(result).toBe(false);
+            expect(mockedSpinniesManager.fail).toHaveBeenCalledWith('codexSpinner', {
+                text: commands.mcp.setup.spinners.codexNotFound,
+            });
+        });
+        it('should handle codex installation failure', async () => {
+            const error = new Error('Some other error');
+            mockedExecAsync.mockResolvedValueOnce({
+                stdout: 'codex version 1.0.0',
+                stderr: '',
+            }); // version check passes
+            mockedExecAsync.mockRejectedValueOnce(error); // mcp add fails
+            const result = await setupCodex(mockMcpCommand);
+            expect(result).toBe(false);
+            expect(mockedSpinniesManager.fail).toHaveBeenCalledWith('codexSpinner', {
+                text: commands.mcp.setup.spinners.codexInstallFailed,
+            });
+            expect(mockedLogError).toHaveBeenCalledWith(error);
+        });
+        it('should handle unexpected errors during spinner setup', async () => {
+            const error = new Error('Unexpected error');
+            mockedSpinniesManager.add.mockImplementationOnce(() => {
+                throw error;
+            });
+            const result = await setupCodex(mockMcpCommand);
+            expect(result).toBe(false);
+            expect(mockedSpinniesManager.fail).toHaveBeenCalledWith('codexSpinner', {
+                text: commands.mcp.setup.spinners.codexInstallFailed,
+            });
+            expect(mockedLogError).toHaveBeenCalledWith(error);
+        });
+    });
+    // Note: addMcpServerToConfig integration tests would require mocking many dependencies
+    // and complex setup. The setupCodex function tests above cover the new functionality.
+});

package/lib/mcp/setup.d.ts

@@ -1,16 +1,7 @@
-export declare const supportedTools: ({
-    name: "Claude Code";
+export declare const supportedTools: {
+    name: string;
     value: string;
-} | {
-    name: "Cursor";
-    value: string;
-} | {
-    name: "Windsurf";
-    value: string;
-} | {
-    name: "VSCode";
-    value: string;
-})[];
+}[];
 interface McpCommand {
     command: string;
     args: string[];
@@ -20,4 +11,5 @@ export declare function setupVsCode(mcpCommand?: McpCommand): Promise<boolean>;
 export declare function setupClaudeCode(mcpCommand?: McpCommand): Promise<boolean>;
 export declare function setupCursor(mcpCommand?: McpCommand): boolean;
 export declare function setupWindsurf(mcpCommand?: McpCommand): boolean;
+export declare function setupCodex(mcpCommand?: McpCommand): Promise<boolean>;
 export {};

package/lib/mcp/setup.js

@@ -13,11 +13,13 @@ const claudeCode = 'claude';
 const windsurf = 'windsurf';
 const cursor = 'cursor';
 const vscode = 'vscode';
+const codex = 'codex';
 export const supportedTools = [
+    { name: commands.mcp.setup.codex, value: codex },
     { name: commands.mcp.setup.claudeCode, value: claudeCode },
     { name: commands.mcp.setup.cursor, value: cursor },
-    { name: commands.mcp.setup.windsurf, value: windsurf },
     { name: commands.mcp.setup.vsCode, value: vscode },
+    { name: commands.mcp.setup.windsurf, value: windsurf },
 ];
 const defaultMcpCommand = {
     command: 'hs',
@@ -56,6 +58,9 @@ export async function addMcpServerToConfig(targets) {
         if (derivedTargets.includes(vscode)) {
             await runSetupFunction(setupVsCode);
         }
+        if (derivedTargets.includes(codex)) {
+            await runSetupFunction(setupCodex);
+        }
         uiLogger.info(commands.mcp.setup.success(derivedTargets));
         return derivedTargets;
     }
@@ -231,6 +236,34 @@ export function setupWindsurf(mcpCommand = defaultMcpCommand) {
         mcpCommand: buildCommandWithAgentString(mcpCommand, windsurf),
     });
 }
+export async function setupCodex(mcpCommand = defaultMcpCommand) {
+    try {
+        SpinniesManager.add('codexSpinner', {
+            text: commands.mcp.setup.spinners.configuringCodex,
+        });
+        // Check if codex command is available
+        await execAsync('codex --version');
+        await execAsync(`codex mcp add "${mcpServerName}" -- ${mcpCommand.command} ${mcpCommand.args.join(' ')} --ai-agent codex`);
+        SpinniesManager.succeed('codexSpinner', {
+            text: commands.mcp.setup.spinners.configuredCodex,
+        });
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('codex')) {
+            SpinniesManager.fail('codexSpinner', {
+                text: commands.mcp.setup.spinners.codexNotFound,
+            });
+        }
+        else {
+            SpinniesManager.fail('codexSpinner', {
+                text: commands.mcp.setup.spinners.codexInstallFailed,
+            });
+            logError(error);
+        }
+        return false;
+    }
+}
 function buildCommandWithAgentString(mcpCommand, agent) {
     const mcpCommandCopy = structuredClone(mcpCommand);
     mcpCommandCopy.args.push('--ai-agent', agent);

package/lib/middleware/autoUpdateMiddleware.d.ts

@@ -1,2 +1,4 @@
 import { Arguments } from 'yargs';
-export declare function autoUpdateCLI(argv: Arguments): Promise<void>;
+export declare function autoUpdateCLI(argv: Arguments<{
+    useEnv?: boolean;
+}>): Promise<void>;

package/lib/middleware/autoUpdateMiddleware.js

@@ -47,6 +47,7 @@ export async function autoUpdateCLI(argv) {
     let showManualInstallHelp = true;
     if (notifier &&
         notifier.update &&
+        !argv.useEnv &&
         !process.env.SKIP_HUBSPOT_CLI_AUTO_UPDATES &&
         isConfigFlagEnabled('allowAutoUpdates') &&
         !preventAutoUpdateForCommand(argv._)) {

package/lib/projects/__tests__/components.test.js

@@ -2,8 +2,10 @@ import fs from 'fs';
 import { handleComponentCollision, updateHsMetaFilesWithAutoGeneratedFields, } from '../components.js';
 import { uiLogger } from '../../ui/logger.js';
 import { coerceToValidUid } from '@hubspot/project-parsing-lib';
+import { fileExists } from '../../validation.js';
 vi.mock('fs');
 vi.mock('../../ui/logger.js');
+vi.mock('../../validation.js');
 vi.mock('@hubspot/project-parsing-lib', () => ({
     coerceToValidUid: vi.fn(),
     metafileExtension: '.module.meta.json',
@@ -19,11 +21,15 @@ vi.mock('../../../lang/en.js', () => ({
                 applicationLog: (type, uid, name) => `Updated ${type} component with uid: ${uid} and name: ${name}`,
                 componentLog: (type, uid) => `Updated ${type} component with uid: ${uid}`,
             },
+            generateSafeFilenameDifferentiator: {
+                failedToCheckFiles: 'Failed to check files for filename differentiator. Falling back to timestamp.',
+            },
         },
     },
 }));
 const mockedFs = vi.mocked(fs);
 const mockCoerceToValidUid = vi.mocked(coerceToValidUid);
+const mockedFileExists = vi.mocked(fileExists);
 describe('lib/projects/components', () => {
     describe('handleComponentCollision()', () => {
         const mockCollision = {
@@ -33,13 +39,13 @@ describe('lib/projects/components', () => {
         };
         beforeEach(() => {
             vi.resetAllMocks();
-            // Mock Date.now to return consistent values for testing
-            vi.spyOn(Date, 'now').mockReturnValue(1234567890);
+            // Default: fileExists returns false (file doesn't exist)
+            mockedFileExists.mockReturnValue(false);
         });
         afterEach(() => {
             vi.restoreAllMocks();
         });
-        it('handles source file collisions by renaming them with timestamps', () => {
+        it('handles source file collisions by renaming them with sequential numbers', () => {
             const collision = {
                 ...mockCollision,
                 collisions: ['component.js', 'utils.ts'],
@@ -47,8 +53,8 @@ describe('lib/projects/components', () => {
             mockedFs.copyFileSync.mockImplementation(() => { });
             handleComponentCollision(collision);
             expect(mockedFs.copyFileSync).toHaveBeenCalledTimes(2);
-            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/component.js', '/dest/path/component-1234567890.js');
-            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/utils.ts', '/dest/path/utils-1234567890.ts');
+            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/component.js', '/dest/path/component-2.js');
+            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/utils.ts', '/dest/path/utils-2.ts');
         });
         it('handles metafile collisions by renaming and updating references', () => {
             const collision = {
@@ -69,8 +75,8 @@ describe('lib/projects/components', () => {
             });
             handleComponentCollision(collision);
             expect(mockedFs.readFileSync).toHaveBeenCalledWith('/src/path/component.module.meta.json', 'utf-8');
-            expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/dest/path/component-1234567890.module.meta.json', expect.stringContaining('source-1234567890.js'));
-            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/source.js', '/dest/path/source-1234567890.js');
+            expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/dest/path/component-2.module.meta.json', expect.stringContaining('source-2.js'));
+            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/source.js', '/dest/path/source-2.js');
         });
         it('handles package.json collisions by merging dependencies', () => {
             const collision = {
@@ -150,10 +156,10 @@ describe('lib/projects/components', () => {
             const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
             handleComponentCollision(collision);
             // Verify source files are copied with new names
-            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/component.js', '/dest/path/component-1234567890.js');
-            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/utils.ts', '/dest/path/utils-1234567890.ts');
+            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/component.js', '/dest/path/component-2.js');
+            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/utils.ts', '/dest/path/utils-2.ts');
             // Verify metafile is updated and written with new name
-            expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/dest/path/component-1234567890.module.meta.json', expect.stringContaining('component-1234567890.js'));
+            expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/dest/path/component-2.module.meta.json', expect.stringContaining('component-2.js'));
             // Verify package.json is merged
             expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/dest/path/package.json', expect.stringContaining('"dependencies"'));
             consoleSpy.mockRestore();
@@ -198,6 +204,47 @@ describe('lib/projects/components', () => {
             expect(mockedFs.readFileSync).toHaveBeenCalledWith('/src/path/package.json', 'utf-8');
             consoleSpy.mockRestore();
         });
+        it('falls back to timestamp when maxAttempts is exhausted', () => {
+            const collision = {
+                ...mockCollision,
+                collisions: ['component.js'],
+            };
+            // Mock Date.now to return a consistent timestamp
+            const mockTimestamp = 1234567890;
+            vi.spyOn(Date, 'now').mockReturnValue(mockTimestamp);
+            // Mock fileExists to return true 10 times (exhausting maxAttempts)
+            // The function starts with differentiator = 1, then increments to 2, 3, etc.
+            // It will try 10 times (differentiators 2-11), and if all return true,
+            // maxAttempts will be 0 and it will fall back to timestamp
+            mockedFileExists.mockReturnValue(true);
+            mockedFs.copyFileSync.mockImplementation(() => { });
+            handleComponentCollision(collision);
+            // Should use timestamp as differentiator
+            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/component.js', `/dest/path/component-${mockTimestamp}.js`);
+            vi.restoreAllMocks();
+        });
+        it('falls back to timestamp when fileExists throws an error', () => {
+            const collision = {
+                ...mockCollision,
+                collisions: ['component.js'],
+            };
+            // Mock Date.now to return a consistent timestamp
+            const mockTimestamp = 9876543210;
+            vi.spyOn(Date, 'now').mockReturnValue(mockTimestamp);
+            // Mock fileExists to throw an error
+            const mockError = new Error('File system error');
+            mockedFileExists.mockImplementation(() => {
+                throw mockError;
+            });
+            mockedFs.copyFileSync.mockImplementation(() => { });
+            const mockUiLogger = vi.mocked(uiLogger);
+            handleComponentCollision(collision);
+            // Should log debug message about the error
+            expect(mockUiLogger.debug).toHaveBeenCalledWith('Failed to check files for filename differentiator. Falling back to timestamp.');
+            // Should use timestamp as differentiator
+            expect(mockedFs.copyFileSync).toHaveBeenCalledWith('/src/path/component.js', `/dest/path/component-${mockTimestamp}.js`);
+            vi.restoreAllMocks();
+        });
     });
     describe('updateHsMetaFilesWithAutoGeneratedFields()', () => {
         const mockUiLogger = vi.mocked(uiLogger);
@@ -233,20 +280,22 @@ describe('lib/projects/components', () => {
                 .mockReturnValueOnce('card-my-project')
                 .mockReturnValueOnce('function-my-project');
             updateHsMetaFilesWithAutoGeneratedFields(projectName, hsMetaFilePaths);
+            expect(mockCoerceToValidUid).toHaveBeenCalledWith('my-project_card');
+            expect(mockCoerceToValidUid).toHaveBeenCalledWith('my-project_function');
             expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/path/to/component1.meta.json', JSON.stringify({
                 type: 'card',
-                uid: 'card-my-project',
+                uid: 'card_my_project',
                 config: {
                     name: 'Old Name',
                 },
             }, null, 2));
             expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/path/to/component2.meta.json', JSON.stringify({
                 type: 'function',
-                uid: 'function-my-project',
+                uid: 'function_my_project',
             }, null, 2));
             expect(mockUiLogger.log).toHaveBeenCalledWith('Updating component metadata files...');
-            expect(mockUiLogger.log).toHaveBeenCalledWith('Updated card component with uid: card-my-project');
-            expect(mockUiLogger.log).toHaveBeenCalledWith('Updated function component with uid: function-my-project');
+            expect(mockUiLogger.log).toHaveBeenCalledWith('Updated card component with uid: card_my_project');
+            expect(mockUiLogger.log).toHaveBeenCalledWith('Updated function component with uid: function_my_project');
         });
         it('handles app components by updating both uid and config.name', () => {
             const projectName = 'test-app';
@@ -263,32 +312,36 @@ describe('lib/projects/components', () => {
             mockedFs.writeFileSync.mockImplementation(() => { });
             mockCoerceToValidUid.mockReturnValue('app-test-app');
             updateHsMetaFilesWithAutoGeneratedFields(projectName, hsMetaFilePaths);
+            expect(mockCoerceToValidUid).toHaveBeenCalledWith('test-app_app');
             expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/path/to/app.meta.json', JSON.stringify({
                 type: 'app',
-                uid: 'app-test-app',
+                uid: 'app_test_app',
                 config: {
                     name: 'test-app-Application',
                     other: 'property',
                 },
             }, null, 2));
-            expect(mockUiLogger.log).toHaveBeenCalledWith('Updated app component with uid: app-test-app and name: test-app-Application');
+            expect(mockUiLogger.log).toHaveBeenCalledWith('Updated app component with uid: app_test_app and name: test-app-Application');
         });
-        it('handles UID collisions by using timestamps', () => {
+        it('handles UID collisions by using differentiators', () => {
             const projectName = 'collision-project';
             const hsMetaFilePaths = ['/path/to/component1.meta.json'];
-            const existingUids = ['card-collision-project'];
+            const existingUids = ['card_collision_project'];
             const component1 = { type: 'card', uid: 'old-uid-1' };
             mockedFs.readFileSync.mockReturnValue(JSON.stringify(component1));
             mockedFs.writeFileSync.mockImplementation(() => { });
-            // Mock Date.now to return consistent value for testing
-            vi.spyOn(Date, 'now').mockReturnValue(1234567890);
+            // First call for getBaseUid() check, second call when adding differentiator
             mockCoerceToValidUid
                 .mockReturnValueOnce('card-collision-project')
-                .mockReturnValueOnce('card-1234567890-collision-project');
+                .mockReturnValueOnce('card-collision-project');
             updateHsMetaFilesWithAutoGeneratedFields(projectName, hsMetaFilePaths, existingUids);
+            expect(mockCoerceToValidUid).toHaveBeenCalledWith('collision-project_card');
+            // getBaseUid() is called twice - once for initial check, once when adding differentiator
+            expect(mockCoerceToValidUid).toHaveBeenCalledTimes(2);
+            // The differentiator is appended with a hyphen, so the final UID has a hyphen before the number
             expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/path/to/component1.meta.json', JSON.stringify({
                 type: 'card',
-                uid: 'card-1234567890-collision-project',
+                uid: 'card_collision_project-2',
             }, null, 2));
         });
         it('falls back to original uid when coerceToValidUid returns null', () => {
@@ -328,11 +381,82 @@ describe('lib/projects/components', () => {
             mockedFs.writeFileSync.mockImplementation(() => { });
             mockCoerceToValidUid.mockReturnValue('app-no-config-project');
             updateHsMetaFilesWithAutoGeneratedFields(projectName, hsMetaFilePaths);
+            expect(mockCoerceToValidUid).toHaveBeenCalledWith('no-config-project_app');
             expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/path/to/app.meta.json', JSON.stringify({
                 type: 'app',
-                uid: 'app-no-config-project',
+                uid: 'app_no_config_project',
+            }, null, 2));
+            expect(mockUiLogger.log).toHaveBeenCalledWith('Updated app component with uid: app_no_config_project');
+        });
+        it('replaces hyphens with underscores in coerced UIDs', () => {
+            const projectName = 'my-project';
+            const hsMetaFilePaths = ['/path/to/component.meta.json'];
+            const component = {
+                type: 'card',
+                uid: 'old-uid',
+            };
+            mockedFs.readFileSync.mockReturnValue(JSON.stringify(component));
+            mockedFs.writeFileSync.mockImplementation(() => { });
+            // coerceToValidUid returns a value with hyphens that should be converted to underscores
+            mockCoerceToValidUid.mockReturnValue('my-project-card-with-hyphens');
+            updateHsMetaFilesWithAutoGeneratedFields(projectName, hsMetaFilePaths);
+            expect(mockCoerceToValidUid).toHaveBeenCalledWith('my-project_card');
+            expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/path/to/component.meta.json', JSON.stringify({
+                type: 'card',
+                uid: 'my_project_card_with_hyphens',
+            }, null, 2));
+        });
+        it('handles UIDs with multiple hyphens correctly', () => {
+            const projectName = 'test-project';
+            const hsMetaFilePaths = ['/path/to/component.meta.json'];
+            const component = {
+                type: 'custom-object',
+                uid: 'old-uid',
+            };
+            mockedFs.readFileSync.mockReturnValue(JSON.stringify(component));
+            mockedFs.writeFileSync.mockImplementation(() => { });
+            mockCoerceToValidUid.mockReturnValue('test-project-custom-object-type');
+            updateHsMetaFilesWithAutoGeneratedFields(projectName, hsMetaFilePaths);
+            expect(mockCoerceToValidUid).toHaveBeenCalledWith('test-project_custom-object');
+            expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/path/to/component.meta.json', JSON.stringify({
+                type: 'custom-object',
+                uid: 'test_project_custom_object_type',
+            }, null, 2));
+        });
+        it('preserves UIDs without hyphens unchanged', () => {
+            const projectName = 'simpleproject';
+            const hsMetaFilePaths = ['/path/to/component.meta.json'];
+            const component = {
+                type: 'card',
+                uid: 'old-uid',
+            };
+            mockedFs.readFileSync.mockReturnValue(JSON.stringify(component));
+            mockedFs.writeFileSync.mockImplementation(() => { });
+            // coerceToValidUid returns a value without hyphens
+            mockCoerceToValidUid.mockReturnValue('simpleprojectcard');
+            updateHsMetaFilesWithAutoGeneratedFields(projectName, hsMetaFilePaths);
+            expect(mockCoerceToValidUid).toHaveBeenCalledWith('simpleproject_card');
+            expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/path/to/component.meta.json', JSON.stringify({
+                type: 'card',
+                uid: 'simpleprojectcard',
+            }, null, 2));
+        });
+        it('handles project names with hyphens in UID generation', () => {
+            const projectName = 'my-super-project';
+            const hsMetaFilePaths = ['/path/to/component.meta.json'];
+            const component = {
+                type: 'function',
+                uid: 'old-uid',
+            };
+            mockedFs.readFileSync.mockReturnValue(JSON.stringify(component));
+            mockedFs.writeFileSync.mockImplementation(() => { });
+            mockCoerceToValidUid.mockReturnValue('my-super-project-function');
+            updateHsMetaFilesWithAutoGeneratedFields(projectName, hsMetaFilePaths);
+            expect(mockCoerceToValidUid).toHaveBeenCalledWith('my-super-project_function');
+            expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/path/to/component.meta.json', JSON.stringify({
+                type: 'function',
+                uid: 'my_super_project_function',
             }, null, 2));
-            expect(mockUiLogger.log).toHaveBeenCalledWith('Updated app component with uid: app-no-config-project');
         });
     });
 });