@hubspot/cli 7.7.0-experimental.2 → 7.7.0

package/mcp-server/tools/project/__tests__/DocFetchTool.test.js

@@ -0,0 +1,117 @@
+import { DocFetchTool } from '../DocFetchTool.js';
+import { http } from '@hubspot/local-dev-lib/http/unauthed';
+import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
+vi.mock('@modelcontextprotocol/sdk/server/mcp.js');
+vi.mock('@hubspot/local-dev-lib/http/unauthed');
+vi.mock('@hubspot/local-dev-lib/errors/index');
+vi.mock('../../utils/toolUsageTracking');
+const mockHttp = http;
+const mockIsHubSpotHttpError = vi.mocked(isHubSpotHttpError);
+describe('mcp-server/tools/project/DocFetchTool', () => {
+    let mockMcpServer;
+    let tool;
+    let mockRegisteredTool;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // @ts-expect-error Not mocking whole server
+        mockMcpServer = {
+            registerTool: vi.fn(),
+        };
+        mockRegisteredTool = {};
+        mockMcpServer.registerTool.mockReturnValue(mockRegisteredTool);
+        tool = new DocFetchTool(mockMcpServer);
+    });
+    describe('register', () => {
+        it('should register tool with correct parameters', () => {
+            const result = tool.register();
+            expect(mockMcpServer.registerTool).toHaveBeenCalledWith('fetch-doc', {
+                title: 'Fetch HubSpot Developer Documentation (single file)',
+                description: 'Always use this immediately after `search-docs` and before creating a plan, writing code, or answering technical questions. This tool retrieves the full, authoritative content of a HubSpot Developer Documentation page from its URL, ensuring responses are accurate, up-to-date, and grounded in the official docs.',
+                inputSchema: expect.any(Object),
+            }, tool.handler);
+            expect(result).toBe(mockRegisteredTool);
+        });
+    });
+    describe('handler', () => {
+        const mockInput = {
+            docUrl: 'https://example.com/docs/test-doc',
+        };
+        it('should successfully fetch and return markdown content', async () => {
+            const mockContent = '# Test Document\n\nThis is a test markdown document.';
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.get.mockResolvedValue({
+                data: mockContent,
+            });
+            const result = await tool.handler(mockInput);
+            expect(mockHttp.get).toHaveBeenCalledWith({
+                url: 'https://example.com/docs/test-doc.md',
+            });
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: mockContent,
+                    },
+                ],
+            });
+        });
+        it('should handle HubSpot HTTP errors', async () => {
+            const mockError = {
+                toString: () => 'HubSpotHttpError: \n- message: The request was not found.\n- status: 404\n- statusText: Not Found\n- method: get\n- code: ERR_BAD_REQUEST\n- derivedContext: {\n  "request": "https://example.com/docs/test-doc.md"\n}',
+            };
+            mockHttp.get.mockRejectedValue(mockError);
+            mockIsHubSpotHttpError.mockReturnValue(true);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'HubSpotHttpError: \n- message: The request was not found.\n- status: 404\n- statusText: Not Found\n- method: get\n- code: ERR_BAD_REQUEST\n- derivedContext: {\n  "request": "https://example.com/docs/test-doc.md"\n}',
+                    },
+                ],
+            });
+        });
+        it('should handle empty content', async () => {
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.get.mockResolvedValue({
+                data: '   ',
+            });
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Document is empty or contains no content.',
+                    },
+                ],
+            });
+        });
+        it('should handle generic errors', async () => {
+            const mockError = new Error('Network error');
+            mockHttp.get.mockRejectedValue(mockError);
+            mockIsHubSpotHttpError.mockReturnValue(false);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error fetching documentation: Network error',
+                    },
+                ],
+            });
+        });
+        it('should handle non-Error rejections', async () => {
+            mockHttp.get.mockRejectedValue('String error');
+            mockIsHubSpotHttpError.mockReturnValue(false);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error fetching documentation: String error',
+                    },
+                ],
+            });
+        });
+    });
+});

package/mcp-server/tools/project/__tests__/DocsSearchTool.test.d.ts

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

package/mcp-server/tools/project/__tests__/DocsSearchTool.test.js

@@ -0,0 +1,192 @@
+import { DocsSearchTool } from '../DocsSearchTool.js';
+import { http } from '@hubspot/local-dev-lib/http';
+import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
+import { getAccountIdFromCliConfig } from '../../../utils/cliConfig.js';
+vi.mock('@modelcontextprotocol/sdk/server/mcp.js');
+vi.mock('@hubspot/local-dev-lib/http');
+vi.mock('@hubspot/local-dev-lib/errors/index');
+vi.mock('../../../utils/toolUsageTracking');
+vi.mock('../../../utils/cliConfig.js');
+const mockHttp = http;
+const mockGetAccountIdFromCliConfig = getAccountIdFromCliConfig;
+const mockIsHubSpotHttpError = vi.mocked(isHubSpotHttpError);
+describe('mcp-server/tools/project/DocsSearchTool', () => {
+    let mockMcpServer;
+    let tool;
+    let mockRegisteredTool;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // @ts-expect-error Not mocking whole server
+        mockMcpServer = {
+            registerTool: vi.fn(),
+        };
+        mockRegisteredTool = {};
+        mockMcpServer.registerTool.mockReturnValue(mockRegisteredTool);
+        tool = new DocsSearchTool(mockMcpServer);
+    });
+    describe('register', () => {
+        it('should register tool with correct parameters', () => {
+            const result = tool.register();
+            expect(mockMcpServer.registerTool).toHaveBeenCalledWith('search-docs', {
+                title: 'Search HubSpot Developer Documentation',
+                description: 'Use this first whenever you need details about HubSpot APIs, SDKs, integrations, or developer platform features. This searches the official HubSpot Developer Documentation and returns the most relevant pages, each with a URL for use in `fetch-doc`. Always follow this with a fetch to get the full, authoritative content before making plans or writing answers.',
+                inputSchema: expect.any(Object),
+            }, tool.handler);
+            expect(result).toBe(mockRegisteredTool);
+        });
+    });
+    describe('handler', () => {
+        const mockInput = {
+            docsSearchQuery: 'test query',
+            absoluteCurrentWorkingDirectory: '/foo',
+        };
+        it('should return auth error message when no account ID is found', async () => {
+            mockGetAccountIdFromCliConfig.mockReturnValue(null);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No account ID found. Please run `hs account auth` to configure an account, or set a default account with `hs account use <account>`',
+                    },
+                ],
+            });
+        });
+        it('should return successful results when docs are found', async () => {
+            mockGetAccountIdFromCliConfig.mockReturnValue(12345);
+            const mockResponse = {
+                results: [
+                    {
+                        title: 'Test Doc 1',
+                        content: 'Test content 1',
+                        description: 'Test description 1',
+                        url: 'https://example.com/doc1',
+                        score: 0.9,
+                    },
+                    {
+                        title: 'Test Doc 2',
+                        content: 'Test content 2',
+                        description: 'Test description 2',
+                        url: 'https://example.com/doc2',
+                        score: 0.8,
+                    },
+                ],
+            };
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.post.mockResolvedValue({
+                data: mockResponse,
+            });
+            const result = await tool.handler(mockInput);
+            expect(mockGetAccountIdFromCliConfig).toHaveBeenCalledWith('/foo');
+            expect(mockHttp.post).toHaveBeenCalledWith(12345, {
+                url: 'dev/docs/llms/v1/docs-search',
+                data: {
+                    query: 'test query',
+                },
+            });
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: expect.stringContaining('Found 2 documentation results:'),
+                    },
+                ],
+            });
+            const resultText = result.content[0].text;
+            expect(resultText).toContain('**Test Doc 1**');
+            expect(resultText).toContain('Test description 1');
+            expect(resultText).toContain('https://example.com/doc1');
+            expect(resultText).toContain('Score: 0.9');
+            expect(resultText).toContain('Test content 1');
+            expect(resultText).toContain('**Test Doc 2**');
+            expect(resultText).toContain('Test description 2');
+            expect(resultText).toContain('https://example.com/doc2');
+            expect(resultText).toContain('Score: 0.8');
+            expect(resultText).toContain('Test content 2');
+        });
+        it('should return no results message when no documentation is found', async () => {
+            mockGetAccountIdFromCliConfig.mockReturnValue(12345);
+            const mockResponse = {
+                results: [],
+            };
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.post.mockResolvedValue({
+                data: mockResponse,
+            });
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No documentation found for your query.',
+                    },
+                ],
+            });
+        });
+        it('should return no results message when results is null', async () => {
+            mockGetAccountIdFromCliConfig.mockReturnValue(12345);
+            const mockResponse = {
+                results: null,
+            };
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.post.mockResolvedValue({
+                data: mockResponse,
+            });
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No documentation found for your query.',
+                    },
+                ],
+            });
+        });
+        it('should handle HubSpot HTTP errors', async () => {
+            mockGetAccountIdFromCliConfig.mockReturnValue(12345);
+            const mockError = {
+                toString: () => 'HubSpot API Error: 404 Not Found',
+            };
+            mockHttp.post.mockRejectedValue(mockError);
+            mockIsHubSpotHttpError.mockReturnValue(true);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'HubSpot API Error: 404 Not Found',
+                    },
+                ],
+            });
+        });
+        it('should handle generic errors', async () => {
+            mockGetAccountIdFromCliConfig.mockReturnValue(12345);
+            const mockError = new Error('Network error');
+            mockHttp.post.mockRejectedValue(mockError);
+            mockIsHubSpotHttpError.mockReturnValue(false);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error searching documentation: Network error',
+                    },
+                ],
+            });
+        });
+        it('should handle non-Error rejections', async () => {
+            mockGetAccountIdFromCliConfig.mockReturnValue(12345);
+            mockHttp.post.mockRejectedValue('String error');
+            mockIsHubSpotHttpError.mockReturnValue(false);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error searching documentation: String error',
+                    },
+                ],
+            });
+        });
+    });
+});

package/mcp-server/tools/project/__tests__/GetConfigValuesTool.test.d.ts

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

package/mcp-server/tools/project/__tests__/GetConfigValuesTool.test.js

@@ -0,0 +1,199 @@
+import { GetConfigValuesTool } from '../GetConfigValuesTool.js';
+import { getIntermediateRepresentationSchema, mapToInternalType, } from '@hubspot/project-parsing-lib';
+import { getAccountIdFromCliConfig } from '../../../utils/cliConfig.js';
+vi.mock('@modelcontextprotocol/sdk/server/mcp.js');
+vi.mock('@hubspot/project-parsing-lib');
+vi.mock('../../../utils/cliConfig.js');
+vi.mock('../../../utils/toolUsageTracking');
+const mockGetIntermediateRepresentationSchema = getIntermediateRepresentationSchema;
+const mockMapToInternalType = mapToInternalType;
+const mockGetAccountIdFromCliConfig = getAccountIdFromCliConfig;
+describe('mcp-server/tools/project/GetConfigValuesTool', () => {
+    let mockMcpServer;
+    let tool;
+    let mockRegisteredTool;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // @ts-expect-error Not mocking the whole thing
+        mockMcpServer = {
+            registerTool: vi.fn(),
+        };
+        mockRegisteredTool = {};
+        mockMcpServer.registerTool.mockReturnValue(mockRegisteredTool);
+        tool = new GetConfigValuesTool(mockMcpServer);
+    });
+    describe('register', () => {
+        it('should register tool with correct parameters', () => {
+            const result = tool.register();
+            expect(mockMcpServer.registerTool).toHaveBeenCalledWith('get-feature-config-schema', {
+                title: 'Fetch the JSON Schema for component',
+                description: expect.stringContaining('Fetches and returns the JSON schema for the provided feature'),
+                inputSchema: expect.objectContaining({
+                    platformVersion: expect.objectContaining({
+                        describe: expect.any(Function),
+                    }),
+                    featureType: expect.objectContaining({
+                        describe: expect.any(Function),
+                    }),
+                }),
+            }, tool.handler);
+            expect(result).toBe(mockRegisteredTool);
+        });
+    });
+    describe('handler', () => {
+        const input = {
+            platformVersion: '2025.2',
+            featureType: 'card',
+            absoluteCurrentWorkingDirectory: '/foo',
+        };
+        beforeEach(() => {
+            mockGetAccountIdFromCliConfig.mockReturnValue(123456789);
+        });
+        it('should return config schema when component type exists', async () => {
+            const mockSchema = {
+                'internal-card-type': {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        description: { type: 'string' },
+                    },
+                },
+            };
+            mockGetIntermediateRepresentationSchema.mockResolvedValue(mockSchema);
+            mockMapToInternalType.mockReturnValue('internal-card-type');
+            const result = await tool.handler(input);
+            expect(mockGetAccountIdFromCliConfig).toHaveBeenCalledWith('/foo');
+            expect(mockGetIntermediateRepresentationSchema).toHaveBeenCalledWith({
+                platformVersion: '2025.2',
+                projectSourceDir: '',
+                accountId: 123456789,
+            });
+            expect(mockMapToInternalType).toHaveBeenCalledWith('card');
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            config: {
+                                type: 'object',
+                                properties: {
+                                    title: { type: 'string' },
+                                    description: { type: 'string' },
+                                },
+                            },
+                        }),
+                    },
+                ],
+            });
+        });
+        it('should return error message when component type does not exist in schema', async () => {
+            const mockSchema = {
+                'other-type': {
+                    type: 'object',
+                    properties: {},
+                },
+            };
+            mockGetIntermediateRepresentationSchema.mockResolvedValue(mockSchema);
+            mockMapToInternalType.mockReturnValue('internal-card-type');
+            const result = await tool.handler(input);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Unable to locate JSON schema for type card',
+                    },
+                ],
+            });
+        });
+        it('should return error message when getIntermediateRepresentationSchema throws', async () => {
+            mockGetIntermediateRepresentationSchema.mockRejectedValue(new Error('Schema fetch failed'));
+            mockMapToInternalType.mockReturnValue('internal-card-type');
+            const result = await tool.handler(input);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Unable to locate JSON schema for type card',
+                    },
+                ],
+            });
+        });
+        it('should return error message when mapToInternalType throws', async () => {
+            const mockSchema = {};
+            mockGetIntermediateRepresentationSchema.mockResolvedValue(mockSchema);
+            mockMapToInternalType.mockImplementation(() => {
+                throw new Error('Mapping failed');
+            });
+            const result = await tool.handler(input);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Unable to locate JSON schema for type card',
+                    },
+                ],
+            });
+        });
+        it('should handle null account id', async () => {
+            mockGetAccountIdFromCliConfig.mockReturnValue(null);
+            const result = await tool.handler(input);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No account ID found. Please run `hs account auth` to configure an account, or set a default account with `hs account use <account>`',
+                    },
+                ],
+            });
+        });
+        it('should handle empty schema object', async () => {
+            const mockSchema = {};
+            mockGetIntermediateRepresentationSchema.mockResolvedValue(mockSchema);
+            mockMapToInternalType.mockReturnValue('internal-card-type');
+            const result = await tool.handler(input);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Unable to locate JSON schema for type card',
+                    },
+                ],
+            });
+        });
+        it('should handle complex nested schema structures', async () => {
+            const complexSchema = {
+                'internal-card-type': {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string', maxLength: 100 },
+                        metadata: {
+                            type: 'object',
+                            properties: {
+                                author: { type: 'string' },
+                                tags: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                },
+                            },
+                            required: ['author'],
+                        },
+                    },
+                    required: ['title'],
+                },
+            };
+            mockGetIntermediateRepresentationSchema.mockResolvedValue(complexSchema);
+            mockMapToInternalType.mockReturnValue('internal-card-type');
+            const result = await tool.handler(input);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            config: complexSchema['internal-card-type'],
+                        }),
+                    },
+                ],
+            });
+        });
+    });
+});

package/mcp-server/tools/project/__tests__/GuidedWalkthroughTool.test.d.ts

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

package/mcp-server/tools/project/__tests__/GuidedWalkthroughTool.test.js

@@ -0,0 +1,126 @@
+import { GuidedWalkthroughTool } from '../GuidedWalkthroughTool.js';
+import { execAsync } from '../../../utils/command.js';
+vi.mock('@modelcontextprotocol/sdk/server/mcp.js');
+vi.mock('../../../utils/command');
+vi.mock('../../../utils/toolUsageTracking');
+const mockExecAsync = execAsync;
+describe('mcp-server/tools/project/GuidedWalkthroughTool', () => {
+    let mockMcpServer;
+    let tool;
+    let mockRegisteredTool;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // @ts-expect-error Not mocking whole server
+        mockMcpServer = {
+            registerTool: vi.fn(),
+        };
+        mockRegisteredTool = {};
+        mockMcpServer.registerTool.mockReturnValue(mockRegisteredTool);
+        tool = new GuidedWalkthroughTool(mockMcpServer);
+    });
+    describe('register', () => {
+        it('should register tool with correct parameters', () => {
+            const result = tool.register();
+            expect(mockMcpServer.registerTool).toHaveBeenCalledWith('guided-walkthrough-cli', {
+                title: 'Guided walkthrough of the CLI',
+                description: 'Give the user a guided walkthrough of the HubSpot CLI.',
+                inputSchema: expect.any(Object),
+            }, tool.handler);
+            expect(result).toBe(mockRegisteredTool);
+        });
+    });
+    describe('handler', () => {
+        it('should show help for hs init command', async () => {
+            const helpOutput = 'Usage: hs init [options]\nInitialize HubSpot CLI';
+            mockExecAsync.mockResolvedValue({
+                stdout: helpOutput,
+                stderr: '',
+            });
+            const result = await tool.handler({ command: 'hs init' });
+            expect(mockExecAsync).toHaveBeenCalledWith('hs init --help');
+            expect(result.content).toHaveLength(1);
+            expect(result.content[0].text).toContain(helpOutput);
+            expect(result.content[0].text).toContain('hs auth');
+        });
+        it('should show help for hs auth command', async () => {
+            const helpOutput = 'Usage: hs auth [options]\nAuthenticate with HubSpot';
+            mockExecAsync.mockResolvedValue({
+                stdout: helpOutput,
+                stderr: '',
+            });
+            const result = await tool.handler({ command: 'hs auth' });
+            expect(mockExecAsync).toHaveBeenCalledWith('hs auth --help');
+            expect(result.content[0].text).toContain(helpOutput);
+            expect(result.content[0].text).toContain('hs project create');
+        });
+        it('should show help for hs project create command', async () => {
+            const helpOutput = 'Usage: hs project create [options]\nCreate a new project';
+            mockExecAsync.mockResolvedValue({
+                stdout: helpOutput,
+                stderr: '',
+            });
+            const result = await tool.handler({ command: 'hs project create' });
+            expect(mockExecAsync).toHaveBeenCalledWith('hs project create --help');
+            expect(result.content[0].text).toContain(helpOutput);
+            expect(result.content[0].text).toContain('hs project upload');
+        });
+        it('should show help for hs project upload command', async () => {
+            const helpOutput = 'Usage: hs project upload [options]\nUpload project to HubSpot';
+            mockExecAsync.mockResolvedValue({
+                stdout: helpOutput,
+                stderr: '',
+            });
+            const result = await tool.handler({ command: 'hs project upload' });
+            expect(mockExecAsync).toHaveBeenCalledWith('hs project upload --help');
+            expect(result.content[0].text).toContain(helpOutput);
+            expect(result.content[0].text).toContain('hs project dev');
+        });
+        it('should handle command without next step', async () => {
+            const helpOutput = 'Usage: hs project dev [options]\nStart development server';
+            mockExecAsync.mockResolvedValue({
+                stdout: helpOutput,
+                stderr: '',
+            });
+            // Test with a command that doesn't have a next command
+            const result = await tool.handler({ command: 'hs project upload' });
+            expect(result.content[0].text).toContain(helpOutput);
+            expect(result.content[0].text).toContain('hs project dev');
+        });
+        it('should handle no command provided', async () => {
+            const result = await tool.handler({});
+            expect(mockExecAsync).not.toHaveBeenCalled();
+            expect(result.content).toEqual([
+                {
+                    type: 'text',
+                    text: 'Is there another command you would like to learn more about?',
+                },
+            ]);
+        });
+        it('should handle undefined command', async () => {
+            const result = await tool.handler({ command: undefined });
+            expect(mockExecAsync).not.toHaveBeenCalled();
+            expect(result.content).toEqual([
+                {
+                    type: 'text',
+                    text: 'Is there another command you would like to learn more about?',
+                },
+            ]);
+        });
+        it('should handle execAsync errors', async () => {
+            const error = new Error('Command not found');
+            mockExecAsync.mockRejectedValue(error);
+            await expect(tool.handler({ command: 'hs init' })).rejects.toThrow('Command not found');
+        });
+        it('should format help text with proper instructions', async () => {
+            const helpOutput = 'Usage: hs init\nOptions:\n  --help  Show help';
+            mockExecAsync.mockResolvedValue({
+                stdout: helpOutput,
+                stderr: '',
+            });
+            const result = await tool.handler({ command: 'hs init' });
+            expect(result.content[0].text).toContain('Display this help output for the user amd wait for them to acknowledge:');
+            expect(result.content[0].text).toContain(helpOutput);
+            expect(result.content[0].text).toContain('Once they are ready, A good command to look at next is hs auth');
+        });
+    });
+});

package/mcp-server/tools/project/__tests__/UploadProjectTools.test.d.ts

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