@hubspot/cli 7.5.11-experimental.0 → 7.7.0-experimental.0

package/lib/validation.js

@@ -145,28 +145,27 @@ function validateCmsPublishMode(options) {
     return false;
 }
 function fileExists(_path) {
-    let isFile;
     try {
         const absoluteSrcPath = path.resolve((0, path_1.getCwd)(), _path);
         if (!absoluteSrcPath)
             return false;
         const stats = fs.statSync(absoluteSrcPath);
-        isFile = stats.isFile();
+        const isFile = stats.isFile();
         if (!isFile) {
-            logger_1.logger.error(`The path "${_path}" is not a path to a file`);
             return false;
         }
     }
     catch (e) {
-        logger_1.logger.error(`The path "${_path}" is not a path to a file`);
         return false;
     }
     return true;
 }
 function checkAndConvertToJson(_path) {
     const filePath = (0, path_1.getAbsoluteFilePath)(_path);
-    if (!fileExists(filePath))
+    if (!fileExists(filePath)) {
+        logger_1.logger.error(`The path "${_path}" is not a path to a file`);
         return null;
+    }
     if ((0, path_1.getExt)(_path) !== 'json') {
         logger_1.logger.error(`The file "${_path}" must be a valid JSON file`);
         return null;

package/lib/yargsUtils.d.ts

@@ -6,4 +6,8 @@ export declare function makeYargsBuilder<T>(callback: (yargs: Argv) => Argv<T>,
     useConfigOptions?: boolean;
     useEnvironmentOptions?: boolean;
     useTestingOptions?: boolean;
+    useCmsPublishModeOptions?: boolean | {
+        read?: boolean;
+        write?: boolean;
+    };
 }): (yargs: Argv) => Promise<Argv<T>>;

package/lib/yargsUtils.js

@@ -32,6 +32,12 @@ function makeYargsBuilder(callback, command, describe, options = {}) {
         if (options.useTestingOptions) {
             (0, commonOpts_1.addTestingOptions)(yargs);
         }
+        if (options.useCmsPublishModeOptions) {
+            const opts = typeof options.useCmsPublishModeOptions === 'object'
+                ? options.useCmsPublishModeOptions
+                : { write: true };
+            (0, commonOpts_1.addCmsPublishModeOptions)(yargs, opts);
+        }
         const result = callback(yargs);
         // Must go last to pick up available options
         await (0, commonOpts_1.addCustomHelpOutput)(result, command, describe);

package/mcp-server/index.d.ts

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

package/mcp-server/index.js

@@ -0,0 +1,17 @@
+import { MCPServer } from 'mcp-framework';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Calculate the correct base path for tools
+// ToolLoader does: dirname(basePath) + "/tools"
+// We want it to look in dist/mcp-server/tools
+// So basePath should be dist/mcp-server/anything
+// __filename is dist/mcp-server/index.js, so dirname is dist/mcp-server
+// We need to provide a path like dist/mcp-server/main.js
+const basePath = join(__dirname, 'main.js');
+console.log('Debug: basePath:', basePath);
+const server = new MCPServer({
+    basePath: basePath,
+});
+server.start();

package/mcp-server/mcpLoader.d.ts

@@ -0,0 +1,5 @@
+export declare function getMCPServer(): Promise<any>;
+export declare function getMCPTool(): Promise<any>;
+export declare class MCPToolBase {
+    static create(): Promise<any>;
+}

package/mcp-server/mcpLoader.js

@@ -0,0 +1,24 @@
+// Dynamic import loader for mcp-framework to handle ESM/CommonJS compatibility
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mcpFramework = null;
+async function loadMCPFramework() {
+    if (!mcpFramework) {
+        mcpFramework = await import('mcp-framework');
+    }
+    return mcpFramework;
+}
+export async function getMCPServer() {
+    const framework = await loadMCPFramework();
+    return framework.MCPServer;
+}
+export async function getMCPTool() {
+    const framework = await loadMCPFramework();
+    return framework.MCPTool;
+}
+// Export a ready-to-use MCPTool base class
+export class MCPToolBase {
+    static async create() {
+        const MCPTool = await getMCPTool();
+        return MCPTool;
+    }
+}

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

@@ -0,0 +1,33 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+interface ExplainProjectStructureInput {
+    section?: string;
+}
+declare class ExplainProjectStructureTool extends MCPTool<ExplainProjectStructureInput> {
+    name: string;
+    description: string;
+    schema: {
+        section: {
+            type: z.ZodOptional<z.ZodString>;
+            description: string;
+        };
+    };
+    execute(input: ExplainProjectStructureInput): Promise<{
+        section: string;
+        title: string;
+        content: string;
+        message?: undefined;
+        sections?: undefined;
+    } | {
+        message: string;
+        sections: {
+            section: string;
+            title: string;
+            content: string;
+        }[];
+        section?: undefined;
+        title?: undefined;
+        content?: undefined;
+    }>;
+}
+export default ExplainProjectStructureTool;

package/mcp-server/tools/ExplainProjectStructureTool.js

@@ -0,0 +1,266 @@
+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

@@ -0,0 +1,99 @@
+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;