@hubspot/cli 7.7.0-experimental.2 → 7.7.0

package/mcp-server/tools/ExplainProjectStructureTool.js

@@ -1,266 +0,0 @@
-import { MCPTool } from "mcp-framework";
-import { z } from "zod";
-class ExplainProjectStructureTool extends MCPTool {
-    name = "explainProjectStructure";
-    description = "Explains the developer projects platform structure, conventions, and best practices";
-    schema = {
-        section: {
-            type: z.string().optional(),
-            description: "Specific section to explain (overview, projectFiles, components, hierarchy, fileNaming, bestPractices, envelope). If not provided, returns complete explanation",
-        },
-    };
-    async execute(input) {
-        const { section } = input;
-        const explanation = {
-            overview: {
-                title: "Developer Projects Platform Overview",
-                content: `
-The developer projects platform allows users to build applications using a hierarchical component-based architecture with consistency and predictability as core principles.
-
-Key Concepts:
-- Projects are defined by hsproject.json files in the root directory
-- Components follow a hierarchical structure with top-level and sub-components
-- Apps are the primary top-level components that provide authentication
-- Sub-components (features) live within apps and depend on app authentication
-- All components live in the src directory with dedicated folders
-- Component instances are declared via *-hsmeta.json files
-- 1:1 relationship between components and their configuration files
-- Envelope layer (uid, type) provides meta information about components
-        `,
-            },
-            projectFiles: {
-                title: "Project Configuration Files",
-                content: `
-hsproject.json (Project Root):
-- Designates a folder as a developer project
-- Contains project metadata including name, source directory, and platform version
-- Required fields:
-  * name: Project name (e.g., "North Star Project")
-  * srcDir: Source code directory (typically "src")
-  * platformVersion: Platform version (e.g., "2025.1", defaults to "2025.2")
-
-Example:
-{
-  "name": "North Star Project",
-  "srcDir": "src",
-  "platformVersion": "2025.1"
-}
-        `,
-            },
-            components: {
-                title: "Component Architecture",
-                content: `
-Components follow a structured, predictable architecture with two main categories:
-
-**Top-Level Components:**
-- Stand-alone components that provide core functionality
-- Currently: Apps (and Themes)
-- Located directly in src/[component-type]/
-- Provide authentication and foundational services
-
-**Sub-Components (Features):**
-- Live within top-level components (primarily apps)
-- Depend on parent component's authentication
-- Located in src/app/[feature-type]/
-- Include: cards, functions, settings, webhooks, marketing-events, timeline-events, etc.
-
-Standard Component Structure (Envelope Layer):
-{
-  "uid": "unique-component-id",      // Unique identifier
-  "type": "component-type",          // Component type
-  "config": {                        // Component-specific configuration
-    // Configuration details here
-  }
-}
-
-Component Characteristics:
-- Each component has a dedicated folder and *-hsmeta.json file (1:1 relationship)
-- Some components are singular (only one per app): settings, webhooks, calling
-- Others can have multiple instances: cards, functions, marketing-events
-- All follow the envelope layer structure for consistency
-        `,
-            },
-            hierarchy: {
-                title: "Component Hierarchy & Authentication",
-                content: `
-The platform uses a hierarchical architecture where authentication flows from top-level components to sub-components.
-
-**Top-Level Components:**
-- App: Primary component providing OAuth authentication
-- Theme: Styling and branding (top-level but may depend on app context)
-
-**Sub-Components within Apps:**
-Sub-components rely on their parent app's authentication and include:
-
-- App Objects: Custom CRM objects
-- App Object Associations: Relationships between objects  
-- Cards: UI cards displayed in HubSpot
-- Functions: Serverless functions
-- Settings: Configuration interfaces
-- Marketing Events: Custom marketing event types
-- Timeline Events: Custom timeline activities
-- Webhooks: Event notification endpoints
-- Workflow Actions: Custom workflow steps
-- Calling: Phone/communication features
-- Video Conferencing: Meeting integrations
-- Media Bridge: Media handling capabilities
-
-**Authentication Flow:**
-1. App component defines OAuth scopes and authentication
-2. Sub-components inherit and utilize app authentication
-3. Sub-components cannot exist without a parent app
-4. All API calls from sub-components use app credentials
-        `,
-            },
-            fileNaming: {
-                title: "File Naming Conventions & Structure",
-                content: `
-Component Configuration Files (*-hsmeta.json):
-- Must end with "-hsmeta.json"
-- Prefix can be anything meaningful to the user
-- Recommended: use component name as prefix for clarity
-- Examples: "my-app-hsmeta.json", "contact-card-hsmeta.json"
-- Maintain 1:1 relationship between components and configuration files
-
-Complete Directory Structure:
-my-project/
-├── hsproject.json              # Project configuration
-└── src/                        # Source code directory
-    ├── app/                    # App component directory (top-level)
-    │   ├── my-app-hsmeta.json  # App component configuration
-    │   ├── cards/              # Cards sub-components
-    │   │   ├── contact-card-hsmeta.json
-    │   │   └── deal-card-hsmeta.json
-    │   ├── functions/          # Function sub-components
-    │   │   ├── data-sync-hsmeta.json
-    │   │   └── email-validator-hsmeta.json
-    │   ├── settings/           # Settings sub-component (singular)
-    │   │   └── app-settings-hsmeta.json
-    │   ├── webhooks/           # Webhooks sub-component (singular)
-    │   │   └── event-handler-hsmeta.json
-    │   └── [other-features]/   # Other sub-component directories
-    └── theme/                  # Theme component (if applicable)
-        └── brand-theme-hsmeta.json
-
-UIDs (Unique Identifiers):
-- Must be unique within each project
-- Use descriptive, kebab-case naming
-- Examples: "my-unified-app", "contact-summary-card", "lead-scoring-function"
-- Should clearly identify the component's purpose and type
-        `,
-            },
-            envelope: {
-                title: "Envelope Layer Architecture",
-                content: `
-The envelope layer provides a consistent structure for all components, enabling the system to derive meta information automatically.
-
-Envelope Structure:
-{
-  "uid": "component-identifier",     // Unique ID for component identification
-  "type": "component-type",          // Type determines component behavior
-  "config": {                       // Component-specific configuration
-    // All component-specific settings go here
-  }
-}
-
-Benefits of Envelope Layer:
-- Consistent metadata extraction across all component types
-- Predictable structure for tooling and validation
-- Clear separation between component identity (uid, type) and configuration
-- Enables automatic component discovery and management
-- Supports hierarchical relationships between components
-
-Example App Component (Top-Level):
-{
-  "uid": "my-unified-app",
-  "type": "app",
-  "config": {
-    "description": "An example to demonstrate how to build a public app with developer projects.",
-    "name": "My unified app",
-    "logo": "./app-logo.png",
-    "distribution": "A public app",
-    "auth": {
-      "type": "oauth",
-      "redirectUrls": ["http://localhost:3000/oauth-callback"],
-      "requiredScopes": ["crm.objects.contacts.read"]
-    }
-  }
-}
-
-Example Sub-Component (Card):
-{
-  "uid": "contact-summary-card",
-  "type": "cards",
-  "config": {
-    "title": "Contact Summary",
-    "description": "Displays key contact information",
-    "displayOptions": {
-      "width": "medium",
-      "height": "auto"
-    }
-  }
-}
-        `,
-            },
-            bestPractices: {
-                title: "Best Practices & Guidelines",
-                content: `
-1. Hierarchy and Authentication:
-   - Always create an app component first (provides authentication)
-   - Sub-components must live within the app directory structure
-   - Ensure app has sufficient OAuth scopes for all sub-components
-   - Consider authentication requirements when planning components
-
-2. Consistency and Predictability:
-   - Follow established folder structures exactly
-   - Maintain 1:1 relationship between components and configuration files
-   - Use consistent naming conventions across all components
-   - Ensure each component has a dedicated folder
-
-3. Project Organization:
-   - Keep hsproject.json in project root
-   - Organize sub-components in their dedicated directories within src/app/
-   - Group related functionality (e.g., all cards in cards/ directory)
-   - Follow the hierarchical structure religiously
-
-4. Component Configuration:
-   - Keep configurations clear and concise
-   - Focus on the rules established by the schema
-   - Use the envelope layer (uid, type, config) consistently
-   - Ensure UIDs are unique and descriptive across all component types
-
-5. File Management:
-   - Use meaningful -hsmeta.json file names that reflect component purpose
-   - Place sub-component files in appropriate feature directories
-   - Include necessary assets (like logos) in component directories
-   - Follow kebab-case for consistency
-
-6. Component Development:
-   - Start with app component to establish authentication foundation
-   - Plan OAuth scopes to cover all intended sub-components
-   - Consider component relationships and dependencies
-   - Validate component configurations against the schema
-   - Remember some components are singular (settings, webhooks) vs. multiple instances (cards, functions)
-        `,
-            },
-        };
-        if (section && explanation[section]) {
-            const selectedSection = explanation[section];
-            return {
-                section: section,
-                title: selectedSection.title,
-                content: selectedSection.content.trim(),
-            };
-        }
-        // Return complete explanation
-        return {
-            message: "Complete Developer Projects Platform Structure Guide",
-            sections: Object.entries(explanation).map(([key, value]) => ({
-                section: key,
-                title: value.title,
-                content: value.content.trim(),
-            })),
-        };
-    }
-}
-export default ExplainProjectStructureTool;

package/mcp-server/tools/GenerateAppComponentTool.d.ts

@@ -1,99 +0,0 @@
-import { MCPTool } from 'mcp-framework';
-import { z } from 'zod';
-interface GenerateAppComponentInput {
-    appName: string;
-    uid: string;
-    description?: string;
-    displayName?: string;
-    distribution?: string;
-    supportEmail?: string;
-    documentationUrl?: string;
-    supportUrl?: string;
-    supportPhone?: string;
-    redirectUrls?: string[];
-    requiredScopes?: string[];
-    optionalScopes?: string[];
-    permittedFetchUrls?: string[];
-    plannedFeatures?: string[];
-}
-declare class GenerateAppComponentTool extends MCPTool<GenerateAppComponentInput> {
-    name: string;
-    description: string;
-    schema: {
-        appName: {
-            type: z.ZodString;
-            description: string;
-        };
-        uid: {
-            type: z.ZodString;
-            description: string;
-        };
-        description: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        displayName: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        distribution: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        supportEmail: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        documentationUrl: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        supportUrl: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        supportPhone: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        redirectUrls: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-        requiredScopes: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-        optionalScopes: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-        permittedFetchUrls: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-        plannedFeatures: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-    };
-    execute(input: GenerateAppComponentInput): Promise<{
-        message: string;
-        config: string;
-        folderPath: string;
-        fileName: string;
-        fullPath: string;
-        architecture: {
-            componentType: string;
-            role: string;
-            singularComponent: boolean;
-            dependents: string;
-        };
-        scopeRecommendations: string[];
-        nextSteps: string[];
-        instructions: string[];
-    }>;
-    private generateScopeRecommendations;
-    private generateNextSteps;
-}
-export default GenerateAppComponentTool;

package/mcp-server/tools/GenerateAppComponentTool.js

@@ -1,193 +0,0 @@
-import { MCPTool } from 'mcp-framework';
-import { z } from 'zod';
-class GenerateAppComponentTool extends MCPTool {
-    name = 'generateAppComponent';
-    description = 'Generates an app component (top-level) with proper folder structure and hsmeta.json configuration file. Apps provide OAuth authentication that sub-components depend on.';
-    schema = {
-        appName: {
-            type: z.string(),
-            description: 'Name of the app (used for file naming and default display name)',
-        },
-        uid: {
-            type: z.string(),
-            description: 'Unique identifier for the app component (must be unique per-project)',
-        },
-        description: {
-            type: z.string().optional(),
-            description: "Description of the app. Defaults to 'A public app'",
-        },
-        displayName: {
-            type: z.string().optional(),
-            description: 'Display name of the app. Defaults to the appName',
-        },
-        distribution: {
-            type: z.string().optional(),
-            description: "Distribution type (one of 'marketplace' or 'private'). Defaults to 'marketplace'",
-        },
-        supportEmail: {
-            type: z.string().optional(),
-            description: "Support email address. Defaults to 'support@example.com'",
-        },
-        documentationUrl: {
-            type: z.string().optional(),
-            description: "Documentation URL. Defaults to 'https://example.com/docs'",
-        },
-        supportUrl: {
-            type: z.string().optional(),
-            description: "Support URL. Defaults to 'https://example.com/support'",
-        },
-        supportPhone: {
-            type: z.string().optional(),
-            description: "Support phone number. Defaults to '+18005555555'",
-        },
-        redirectUrls: {
-            type: z.array(z.string()).optional(),
-            description: "OAuth redirect URLs. Defaults to ['http://localhost:3000/oauth-callback']",
-        },
-        requiredScopes: {
-            type: z.array(z.string()).optional(),
-            description: 'Required OAuth scopes. Consider what sub-components you plan to add. Defaults to basic CRM contact scopes',
-        },
-        optionalScopes: {
-            type: z.array(z.string()).optional(),
-            description: 'Optional OAuth scopes. Defaults to empty array',
-        },
-        permittedFetchUrls: {
-            type: z.array(z.string()).optional(),
-            description: "URLs permitted for fetch requests. Defaults to ['https://api.example.com']",
-        },
-        plannedFeatures: {
-            type: z.array(z.string()).optional(),
-            description: "List of planned sub-components/features (e.g., 'cards', 'functions', 'webhooks'). Used to suggest appropriate OAuth scopes",
-        },
-    };
-    async execute(input) {
-        const { appName, uid, description = 'A public app', displayName = appName, distribution = 'marketplace', supportEmail = 'support@example.com', documentationUrl = 'https://example.com/docs', supportUrl = 'https://example.com/support', supportPhone = '+18005555555', redirectUrls = ['http://localhost:3000/oauth-callback'], requiredScopes = [
-            'crm.objects.contacts.read',
-            'crm.objects.contacts.write',
-        ], optionalScopes = [], permittedFetchUrls = ['https://api.example.com'], plannedFeatures = [], } = input;
-        // Generate the sanitized app name for file naming
-        const sanitizedAppName = appName.toLowerCase().replace(/\s+/g, '-');
-        const fileName = `${sanitizedAppName}-hsmeta.json`;
-        const folderPath = 'src/app';
-        const appConfig = {
-            uid: uid,
-            type: 'app',
-            config: {
-                description: description,
-                name: displayName,
-                distribution: distribution,
-                auth: {
-                    type: 'oauth',
-                    redirectUrls: redirectUrls,
-                    requiredScopes: requiredScopes,
-                    optionalScopes: optionalScopes,
-                    conditionallyRequiredScopes: [],
-                },
-                permittedUrls: {
-                    fetch: permittedFetchUrls,
-                    iframe: [],
-                    img: [],
-                },
-                support: {
-                    supportEmail: supportEmail,
-                    documentationUrl: documentationUrl,
-                    supportUrl: supportUrl,
-                    supportPhone: supportPhone,
-                },
-            },
-        };
-        // Generate scope recommendations based on planned features
-        const scopeRecommendations = this.generateScopeRecommendations(plannedFeatures);
-        // Generate next steps guidance
-        const nextSteps = this.generateNextSteps(plannedFeatures, folderPath);
-        return {
-            message: `Generated app component configuration for "${displayName}"`,
-            config: JSON.stringify(appConfig, null, 2),
-            folderPath: folderPath,
-            fileName: fileName,
-            fullPath: `${folderPath}/${fileName}`,
-            architecture: {
-                componentType: 'top-level',
-                role: 'authentication-provider',
-                singularComponent: true,
-                dependents: "All sub-components (cards, functions, settings, etc.) will depend on this app's authentication",
-            },
-            scopeRecommendations: scopeRecommendations,
-            nextSteps: nextSteps,
-            instructions: [
-                `Create the directory structure: ${folderPath}/`,
-                `Place the configuration file at: ${folderPath}/${fileName}`,
-                `This is a TOP-LEVEL component that provides OAuth authentication`,
-                `Sub-components (features) will live within ${folderPath}/ and depend on this app's authentication`,
-                `The app component uid: ${uid} must be unique within your project`,
-                'Consider what sub-components you plan to add and ensure sufficient OAuth scopes',
-                'Typically there is one app component per project (singular component)',
-            ],
-        };
-    }
-    generateScopeRecommendations(plannedFeatures) {
-        const recommendations = [];
-        if (plannedFeatures.length === 0) {
-            return [
-                'Consider what sub-components you plan to add to determine required OAuth scopes',
-                'Cards typically need CRM object read access',
-                'Functions may need broader API access depending on functionality',
-                'Webhooks may need specific event subscription scopes',
-            ];
-        }
-        const scopeMap = {
-            cards: [
-                'Cards typically need: crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read',
-            ],
-            functions: [
-                'Functions may need: broader API access depending on functionality',
-                'Consider: crm.objects.*.read, crm.objects.*.write if manipulating CRM data',
-            ],
-            webhooks: [
-                'Webhooks may need: specific event subscription scopes',
-                'Consider: webhooks scope and relevant object scopes for events you want to receive',
-            ],
-            settings: [
-                'Settings typically need: minimal scopes, may inherit from other components',
-            ],
-            'marketing-events': [
-                'Marketing events may need: marketing event creation and management scopes',
-            ],
-            'timeline-events': [
-                'Timeline events may need: timeline read/write scopes for the relevant objects',
-            ],
-            'workflow-actions': [
-                'Workflow actions may need: workflow and automation related scopes',
-            ],
-        };
-        plannedFeatures.forEach(feature => {
-            if (scopeMap[feature]) {
-                recommendations.push(`For ${feature}: ${scopeMap[feature].join(', ')}`);
-            }
-        });
-        return recommendations;
-    }
-    generateNextSteps(plannedFeatures, appPath) {
-        const steps = [
-            '1. Create the app component configuration file and directory structure',
-            '2. Test OAuth flow and ensure authentication works correctly',
-            '3. Add sub-components within the app directory as needed:',
-        ];
-        if (plannedFeatures.length > 0) {
-            plannedFeatures.forEach(feature => {
-                steps.push(`   - ${appPath}/${feature}/`);
-            });
-        }
-        else {
-            steps.push(`   - ${appPath}/cards/ (for UI cards)`);
-            steps.push(`   - ${appPath}/functions/ (for serverless functions)`);
-            steps.push(`   - ${appPath}/settings/ (for configuration UI)`);
-            steps.push(`   - ${appPath}/webhooks/ (for event handling)`);
-        }
-        steps.push("4. Ensure all sub-components can access required APIs with the app's OAuth scopes");
-        steps.push('5. Test the complete application with all components integrated');
-        return steps;
-    }
-}
-export default GenerateAppComponentTool;

package/mcp-server/tools/GenerateCardComponentTool.d.ts

@@ -1,74 +0,0 @@
-import { MCPTool } from "mcp-framework";
-import { z } from "zod";
-interface GenerateCardComponentInput {
-    cardName: string;
-    uid: string;
-    displayName?: string;
-    location?: string;
-    objectTypes?: string[];
-    componentFileName?: string;
-}
-declare class GenerateCardComponentTool extends MCPTool<GenerateCardComponentInput> {
-    name: string;
-    description: string;
-    schema: {
-        cardName: {
-            type: z.ZodString;
-            description: string;
-        };
-        uid: {
-            type: z.ZodString;
-            description: string;
-        };
-        displayName: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        location: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        objectTypes: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-        componentFileName: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-    };
-    execute(input: GenerateCardComponentInput): Promise<{
-        message: string;
-        files: {
-            configuration: {
-                path: string;
-                content: string;
-                description: string;
-            };
-            packageJson: {
-                path: string;
-                content: string;
-                description: string;
-            };
-            reactComponent: {
-                path: string;
-                content: string;
-                description: string;
-            };
-        };
-        folderPath: string;
-        architecture: {
-            componentType: string;
-            parentComponent: string;
-            category: string;
-            authenticationDependency: string;
-            allowMultiple: boolean;
-            technology: string;
-        };
-        instructions: string[];
-        nextSteps: string[];
-        developmentNotes: string[];
-    }>;
-    private toPascalCase;
-}
-export default GenerateCardComponentTool;