@hubspot/cli 7.6.0-experimental.0 → 7.7.0-experimental.1

package/mcp-server/tools/ValidateProjectTool.js

@@ -0,0 +1,324 @@
+import { MCPTool } from 'mcp-framework';
+import { z } from 'zod';
+import HubSpotCLIHelper from './HubSpotCLIHelper.js';
+class ValidateProjectTool extends MCPTool {
+    name = 'validateProject';
+    description = 'Validates a developer project using the HubSpot CLI and provides guidance for fixing any validation errors';
+    cliHelper = new HubSpotCLIHelper();
+    schema = {
+        autoFix: {
+            type: z.boolean().optional(),
+            description: 'Whether to attempt automatic fixes for common validation errors. Defaults to false',
+        },
+        projectPath: {
+            type: z.string().optional(),
+            description: 'Path to the project directory. Defaults to current directory',
+        },
+    };
+    async execute(input) {
+        // Default to current working directory, which should be where Cursor is running from
+        const { autoFix = false, projectPath = process.cwd() } = input;
+        try {
+            // Step 1: Check if HubSpot CLI is installed
+            const cliCheckResult = await this.cliHelper.checkCLIInstallation();
+            if (!cliCheckResult.isInstalled) {
+                return {
+                    status: 'cli-not-found',
+                    error: `Debug info: ${JSON.stringify(cliCheckResult.debugInfo, null, 2)}`,
+                    message: 'HubSpot CLI not found. Installing...',
+                    actions: [
+                        {
+                            action: 'install-cli',
+                            command: 'npm install -g @hubspot/cli',
+                            description: 'Installing HubSpot CLI globally',
+                        },
+                    ],
+                    nextSteps: [
+                        '1. Install HubSpot CLI globally',
+                        '2. Run project validation again',
+                        '3. Follow any additional guidance for fixing validation errors',
+                    ],
+                };
+            }
+            // Step 2: Run project validation
+            const validationResult = await this.runProjectValidation(projectPath);
+            if (validationResult.isValid) {
+                return {
+                    status: 'valid',
+                    message: '✅ Project validation passed! Your developer project is properly configured.',
+                    cliVersion: cliCheckResult.version,
+                    validationOutput: validationResult.output,
+                    projectStructure: 'All components and configurations follow platform conventions',
+                };
+            }
+            // Step 3: Parse validation errors and provide guidance
+            const errorAnalysis = this.analyzeValidationErrors(validationResult.errors);
+            const suggestions = this.generateFixSuggestions(errorAnalysis);
+            const response = {
+                status: 'validation-failed',
+                message: "❌ Project validation failed. Here's how to fix the issues:",
+                cliVersion: cliCheckResult.version,
+                validationOutput: validationResult.output,
+                errors: validationResult.errors,
+                errorAnalysis: errorAnalysis,
+                suggestions: suggestions,
+                nextSteps: this.generateNextSteps(errorAnalysis, autoFix),
+            };
+            if (autoFix) {
+                response.autoFixActions = this.generateAutoFixActions(errorAnalysis);
+            }
+            return response;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            return {
+                status: 'error',
+                message: 'An error occurred during project validation',
+                error: errorMessage,
+                troubleshooting: [
+                    "Ensure you're in a valid developer project directory",
+                    'Check that hsproject.json exists in the project root',
+                    'Verify HubSpot CLI is properly installed and accessible',
+                    "Try running 'hs project validate' manually to see detailed output",
+                    `Attempted project path: ${projectPath}`,
+                ],
+            };
+        }
+    }
+    async runProjectValidation(projectPath) {
+        try {
+            const result = await this.cliHelper.runProjectCommand('hs project validate', projectPath);
+            if (result.success) {
+                // Parse the validation output to determine if it passed
+                const output = result.output;
+                // Check for validation success indicators
+                const isValid = output.includes('✅') ||
+                    output.includes('Project validation passed') ||
+                    output.includes('valid') ||
+                    !output.includes('Project validation failed:');
+                // Parse structured validation errors if present
+                const errors = [];
+                if (!isValid && output.includes('Project validation failed:')) {
+                    errors.push(...this.parseValidationErrors(output));
+                }
+                return {
+                    isValid: isValid,
+                    output: output,
+                    errors: errors,
+                };
+            }
+            else {
+                // Command failed to run
+                const errorMessage = result.error || 'Failed to run project validation';
+                const errors = [errorMessage];
+                // Add debugging information about directory context
+                if (result.output.includes('Unable to locate a project configuration file')) {
+                    errors.push(`Working directory was: ${projectPath}`);
+                    errors.push("Make sure you're running this from a directory containing hsproject.json");
+                }
+                return {
+                    isValid: false,
+                    output: result.output || '',
+                    errors: errors,
+                };
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown validation error';
+            throw new Error(`Failed to run project validation: ${errorMessage}`);
+        }
+    }
+    runCommand(command) {
+        // Delegate to the CLI helper
+        return this.cliHelper.runCommand(command);
+    }
+    parseValidationErrors(output) {
+        const errors = [];
+        const lines = output.split('\n');
+        let currentFile = '';
+        let inErrorSection = false;
+        for (const line of lines) {
+            // Look for file error headers like "Encountered the following errors for src/app/file.json:"
+            const fileMatch = line.match(/Encountered the following errors for (.+?):/);
+            if (fileMatch) {
+                currentFile = fileMatch[1];
+                inErrorSection = true;
+                continue;
+            }
+            // Parse individual error lines (start with tab and dash)
+            if (inErrorSection && line.match(/^\s*-\s+/)) {
+                const errorText = line.replace(/^\s*-\s+/, '').trim();
+                if (errorText) {
+                    errors.push(`${currentFile}: ${errorText}`);
+                }
+                continue;
+            }
+            // Handle multi-line errors with additional indentation
+            if (inErrorSection && line.match(/^\s{2,}-\s+/)) {
+                const errorText = line.replace(/^\s*-\s+/, '').trim();
+                if (errorText && errors.length > 0) {
+                    // Append to the last error as additional context
+                    errors[errors.length - 1] += `\n  ${errorText}`;
+                }
+                continue;
+            }
+            // Reset when we hit an empty line or new section
+            if (line.trim() === '' ||
+                (!line.startsWith('\t') && !line.startsWith(' '))) {
+                inErrorSection = false;
+                currentFile = '';
+            }
+        }
+        return errors;
+    }
+    analyzeValidationErrors(errors) {
+        const analysis = [];
+        for (const error of errors) {
+            const filePath = error.split(':')[0];
+            const errorMessage = error.substring(error.indexOf(':') + 1).trim();
+            let category = 'unknown';
+            let component = 'unknown';
+            let severity = 'error';
+            // Extract file information
+            if (filePath.includes('hsproject.json')) {
+                category = 'project-config';
+                component = 'project';
+            }
+            else if (filePath.includes('-hsmeta.json')) {
+                category = 'component-config';
+                component = this.extractComponentFromPath(filePath);
+            }
+            else if (filePath.includes('package.json')) {
+                category = 'dependencies';
+                component = this.extractComponentFromPath(filePath);
+                severity = 'warning';
+            }
+            // Analyze error message content
+            if (errorMessage.includes('Invalid JSON')) {
+                category = 'json-syntax';
+            }
+            else if (errorMessage.includes('Missing required field')) {
+                category = 'required-field';
+            }
+            else if (errorMessage.includes('must NOT have additional properties')) {
+                category = 'schema-validation';
+            }
+            else if (errorMessage.includes('entrypoint')) {
+                category = 'entrypoint';
+            }
+            analysis.push({
+                category: category,
+                issue: errorMessage,
+                severity: severity,
+                component: component,
+                file: filePath,
+            });
+        }
+        return analysis;
+    }
+    extractComponentFromPath(filePath) {
+        // Extract component type from file path like "src/app/cards/my-card-hsmeta.json"
+        if (filePath.includes('/app/')) {
+            const pathParts = filePath.split('/app/')[1].split('/');
+            if (pathParts.length > 1) {
+                return pathParts[0]; // e.g., "cards", "functions", etc.
+            }
+            return 'app';
+        }
+        // Handle top-level app component files
+        if (filePath.includes('-hsmeta.json')) {
+            return 'app';
+        }
+        return 'unknown';
+    }
+    generateFixSuggestions(errorAnalysis) {
+        const suggestions = [];
+        for (const error of errorAnalysis) {
+            switch (error.category) {
+                case 'project-config':
+                    suggestions.push("Fix hsproject.json: Ensure it contains 'name', 'srcDir', and 'platformVersion' fields", 'Use the generateProjectConfig tool to create a valid hsproject.json file');
+                    break;
+                case 'component-config':
+                    suggestions.push(`Fix ${error.component} component: Check the *-hsmeta.json file structure`, 'Ensure the component follows the envelope pattern: uid, type, config', `Use the appropriate generate component tool for ${error.component} type`);
+                    break;
+                case 'json-syntax':
+                    suggestions.push(`Fix JSON syntax error in ${error.file}`, 'Check for missing commas, brackets, or quotes in the JSON file', 'Use a JSON validator to identify the specific syntax issue');
+                    break;
+                case 'required-field':
+                    suggestions.push(`Add missing required field: ${this.extractFieldFromError(error.issue)}`, `Update ${error.file} to include all required fields`, 'Refer to the platform documentation for required field specifications');
+                    break;
+                case 'schema-validation':
+                    suggestions.push(`Fix schema validation error in ${error.file}`, 'Remove additional properties that are not allowed', `Check ${error.component} component schema requirements`, 'Ensure all field types match the expected schema');
+                    break;
+                case 'dependencies':
+                    suggestions.push('Fix package.json: Ensure React and @hubspot/ui-extensions dependencies are present', "Run 'npm install' to install missing dependencies", 'Check that package.json is in the correct component directory');
+                    break;
+                case 'entrypoint':
+                    suggestions.push('Fix component entrypoint: Ensure the React file exists at the specified path', 'Check that the entrypoint path in *-hsmeta.json matches the actual file location', 'Verify the React component exports properly');
+                    break;
+                default:
+                    suggestions.push(`Review error in ${error.file || 'project'}: ${error.issue}`);
+            }
+        }
+        return [...new Set(suggestions)]; // Remove duplicates
+    }
+    extractFieldFromError(errorMessage) {
+        // Extract field name from messages like "Missing required field: config.description"
+        const match = errorMessage.match(/Missing required field:\s*(.+)/);
+        return match ? match[1] : 'unknown field';
+    }
+    generateNextSteps(errorAnalysis, autoFix) {
+        const steps = [];
+        if (autoFix) {
+            steps.push('1. Review auto-fix actions and apply them');
+        }
+        else {
+            steps.push('1. Review the validation errors and suggestions above');
+        }
+        const hasProjectConfig = errorAnalysis.some(e => e.category === 'project-config');
+        const hasComponentIssues = errorAnalysis.some(e => e.category === 'component-config');
+        const hasDependencyIssues = errorAnalysis.some(e => e.category === 'dependencies');
+        if (hasProjectConfig) {
+            steps.push('2. Fix hsproject.json configuration issues first');
+        }
+        if (hasComponentIssues) {
+            steps.push('3. Fix component configuration issues');
+        }
+        if (hasDependencyIssues) {
+            steps.push('4. Install missing dependencies');
+        }
+        steps.push('5. Run validation again to verify fixes');
+        steps.push('6. Test your components work correctly in development');
+        return steps;
+    }
+    generateAutoFixActions(errorAnalysis) {
+        const actions = [];
+        for (const error of errorAnalysis) {
+            switch (error.category) {
+                case 'project-config':
+                    actions.push({
+                        action: 'fix-project-config',
+                        description: 'Generate valid hsproject.json configuration',
+                        tool: 'generateProjectConfig',
+                    });
+                    break;
+                case 'dependencies':
+                    actions.push({
+                        action: 'install-dependencies',
+                        description: 'Install missing npm dependencies',
+                        command: 'npm install',
+                    });
+                    break;
+                case 'component-config':
+                    actions.push({
+                        action: 'fix-component-config',
+                        description: `Fix ${error.component} component configuration`,
+                        tool: `generate${error.component}Component`,
+                    });
+                    break;
+            }
+        }
+        return actions;
+    }
+}
+export default ValidateProjectTool;

package/package.json

@@ -1,15 +1,16 @@
 {
     "name": "@hubspot/cli",
-    "version": "7.6.0-experimental.0",
+    "version": "7.7.0-experimental.1",
     "description": "The official CLI for developing on HubSpot",
     "license": "Apache-2.0",
     "repository": "https://github.com/HubSpot/hubspot-cli",
     "dependencies": {
-        "@hubspot/local-dev-lib": "0.4.0-experimental.0",
+        "@hubspot/local-dev-lib": "3.7.0",
         "@hubspot/project-parsing-lib": "0.2.0",
         "@hubspot/serverless-dev-runtime": "7.0.2",
         "@hubspot/theme-preview-dev-server": "0.0.10",
         "@hubspot/ui-extensions-dev-server": "0.8.52",
+        "@modelcontextprotocol/sdk": "^1.12.1",
         "archiver": "7.0.1",
         "boxen": "8.0.1",
         "chalk": "4.1.2",
@@ -21,6 +22,7 @@
         "fs-extra": "8.1.0",
         "inquirer": "8.2.0",
         "js-yaml": "4.1.0",
+        "mcp-framework": "^0.2.2",
         "moment": "2.30.1",
         "open": "7.4.2",
         "p-queue": "6.6.2",
@@ -98,7 +100,8 @@
     },
     "bin": {
         "hs": "./bin/hs",
-        "hscms": "./bin/hscms"
+        "hscms": "./bin/hscms",
+        "hsmcp": "./bin/hsmcp.js"
     },
     "publishConfig": {
         "access": "public",

package/commands/testAccount/create.d.ts

@@ -1,7 +0,0 @@
-import { CommonArgs, YargsCommandModule } from '../../types/Yargs';
-type CreateTestAccountArgs = CommonArgs & {
-    name: string;
-    tiers: string[];
-};
-declare const createTestAccountCommand: YargsCommandModule<unknown, CreateTestAccountArgs>;
-export default createTestAccountCommand;

package/commands/testAccount/create.js

@@ -1,118 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const developerTestAccounts_1 = require("@hubspot/local-dev-lib/api/developerTestAccounts");
-const yargsUtils_1 = require("../../lib/yargsUtils");
-const promptUtils_1 = require("../../lib/prompts/promptUtils");
-const exitCodes_1 = require("../../lib/enums/exitCodes");
-const logger_1 = require("../../lib/ui/logger");
-const command = 'create [name]';
-const describe = 'Create a test account';
-const hubs = {
-    MARKETING: 'marketingLevel',
-    OPS: 'opsLevel',
-    SERVICE: 'serviceLevel',
-    SALES: 'salesLevel',
-    CONTENT: 'contentLevel',
-};
-const TEST_ACCOUNT_TIERS = [
-    { name: 'Marketing STARTER', value: 'MARKETING:STARTER' },
-    { name: 'Marketing PRO', value: 'MARKETING:PRO' },
-    { name: 'Marketing ENTERPRISE', value: 'MARKETING:ENTERPRISE' },
-    promptUtils_1.Separator,
-    { name: 'Ops STARTER', value: 'OPS:STARTER' },
-    { name: 'Ops PRO', value: 'OPS:PRO' },
-    { name: 'Ops ENTERPRISE', value: 'OPS:ENTERPRISE' },
-    promptUtils_1.Separator,
-    { name: 'Service STARTER', value: 'SERVICE:STARTER' },
-    { name: 'Service PRO', value: 'SERVICE:PRO' },
-    { name: 'Service ENTERPRISE', value: 'SERVICE:ENTERPRISE' },
-    promptUtils_1.Separator,
-    { name: 'Sales STARTER', value: 'SALES:STARTER' },
-    { name: 'Sales PRO', value: 'SALES:PRO' },
-    { name: 'Sales ENTERPRISE', value: 'SALES:ENTERPRISE' },
-    promptUtils_1.Separator,
-    { name: 'Content STARTER', value: 'CONTENT:STARTER' },
-    { name: 'Content PRO', value: 'CONTENT:PRO' },
-    { name: 'Content ENTERPRISE', value: 'CONTENT:ENTERPRISE' },
-    promptUtils_1.Separator,
-];
-async function handler(args) {
-    const { derivedAccountId, name, tiers } = args;
-    // trackCommandUsage('test-account-create', {}, derivedAccountId);
-    let accountName = name;
-    let accountLevelsArray = tiers;
-    if (!name) {
-        const namePromptResult = await (0, promptUtils_1.promptUser)({
-            name: 'accountName',
-            message: 'What is the name of the test account?',
-            type: 'input',
-        });
-        accountName = namePromptResult.accountName;
-    }
-    if (!accountLevelsArray) {
-        const accountLevelsPromptResult = await (0, promptUtils_1.promptUser)({
-            name: 'testAccountLevels',
-            message: '[--tiers] Which tiers should the test account have?',
-            type: 'checkbox',
-            choices: TEST_ACCOUNT_TIERS,
-            validate: choices => {
-                if (choices?.length > 1) {
-                    const hubMap = {};
-                    for (const choice of choices) {
-                        const hub = choice.split(':')[0];
-                        if (hubMap[hub]) {
-                            return 'Cannot have more than one tier per hub';
-                        }
-                        hubMap[hub] = true;
-                    }
-                }
-                return true;
-            },
-        });
-        accountLevelsArray = accountLevelsPromptResult.testAccountLevels;
-    }
-    const accountLevels = accountLevelsArray.reduce((acc, level) => {
-        const parts = level.split(':');
-        const hubName = hubs[parts[0]];
-        const hubTier = parts[1];
-        acc[hubName] = hubTier;
-        return acc;
-    }, {});
-    try {
-        const { data } = await (0, developerTestAccounts_1.createDeveloperTestAccount)(derivedAccountId, accountName, true, accountLevels);
-        // @ts-expect-error - testPortalId is not typed
-        logger_1.uiLogger.log(`Test account created: ${data.testPortalId}`);
-    }
-    catch (err) {
-        logger_1.uiLogger.error('Failed to create test account');
-        process.exit(exitCodes_1.EXIT_CODES.ERROR);
-    }
-    process.exit(exitCodes_1.EXIT_CODES.SUCCESS);
-}
-function createTestAccountBuilder(yargs) {
-    yargs.positional('name', {
-        type: 'string',
-        description: 'The name of the test account',
-    });
-    yargs.option('tiers', {
-        type: 'array',
-        description: 'The tiers of the test account',
-    });
-    yargs.example([
-        [
-            '$0 create my-account --tiers MARKETING:STARTER OPS:PRO',
-            'Create a test account with the name "my-account" and the tiers "Marketing - STARTER, OPS - PRO"',
-        ],
-    ]);
-    return yargs;
-}
-const builder = (0, yargsUtils_1.makeYargsBuilder)(createTestAccountBuilder, command, describe, {
-    useGlobalOptions: true,
-});
-const createTestAccountCommand = {
-    command,
-    describe,
-    handler,
-    builder,
-};
-exports.default = createTestAccountCommand;

package/commands/testAccount.d.ts

@@ -1,3 +0,0 @@
-import { YargsCommandModuleBucket } from '../types/Yargs';
-declare const testAccountCommand: YargsCommandModuleBucket;
-export default testAccountCommand;

package/commands/testAccount.js

@@ -1,23 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const create_1 = __importDefault(require("./testAccount/create"));
-const yargsUtils_1 = require("../lib/yargsUtils");
-const command = ['test-account', 'test-accounts'];
-const describe = 'Test account';
-function secretBuilder(yargs) {
-    yargs.command(create_1.default).demandCommand(1, '');
-    return yargs;
-}
-const builder = (0, yargsUtils_1.makeYargsBuilder)(secretBuilder, command, describe);
-const testAccountCommand = {
-    command,
-    describe,
-    builder,
-    handler: () => { },
-};
-exports.default = testAccountCommand;
-// TODO Remove this legacy export once we've migrated all commands to TS
-module.exports = testAccountCommand;