@aifabrix/builder 2.41.0 → 2.42.0

package/.cursor/rules/docs-rules.mdc

@@ -0,0 +1,30 @@
+---
+alwaysApply: true
+---
+# Documentation Rules – CLI User Docs
+
+## Audience
+
+Documents under **docs/** (including **docs/commands/**) are **CLI developer / user documentation**. The audience is people who use the AI Fabrix Builder CLI or integrate it into workflows. They do not need to know how the CLI talks to the Controller or Dataplane over HTTP.
+
+## Do Not Include in CLI User Docs
+
+- **REST API details** – No HTTP methods, URL paths, or endpoint names (e.g. `GET /api/v1/...`, `POST .../pipeline/upload`).
+- **Request/response shapes** – No payload structures, status codes, or field names from backend APIs.
+- **Backend implementation terms** – Avoid referring to “pipeline config endpoint”, “upload endpoint”, or similar; describe what the **command** does from the user’s perspective.
+
+Keep these details in code (JSDoc, lib comments) or in separate API/implementation docs for contributors.
+
+## Do Include in CLI User Docs
+
+- **What the command does** – Outcome and behavior in user terms (e.g. “Downloads the full manifest from the dataplane”, “Uploads config and publishes to the dataplane”).
+- **Prerequisites** – Login, permissions, and auth in user terms (e.g. “Must be logged in with `aifabrix login`”; “Bearer token required” without naming the backend endpoint).
+- **Options and arguments** – All flags, arguments, and examples.
+- **What gets created or changed** – Files, folders, and config the user will see.
+- **Troubleshooting** – Common errors and fixes in CLI terms (e.g. “Run `aifabrix login`” instead of “Ensure the pipeline config endpoint receives a Bearer token”).
+
+## When Editing docs/
+
+- Prefer **command-centric** language: “the download command fetches…”, “upload publishes…”.
+- Describe **auth** by what the user must do (login, device flow) and whether a Bearer token is required, not by which backend endpoint is called.
+- If a command uses the dataplane or controller, say so in plain language (“from the dataplane”, “to the controller”) without exposing URLs or HTTP details.

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@aifabrix/builder.svg)](https://www.npmjs.com/package/@aifabrix/builder)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Install the AI Fabrix platform and test it locally. Then add external integrations or build your own applications.
+Open developer runtime for AI Fabrix ecosystem. Install the AI Fabrix platform and test it locally. Then add external integrations or build your own applications.
 
 ← **Full documentation:** [docs/README.md](docs/README.md) (table of contents for all guides)
 

package/integration/hubspot/README.md

@@ -1,17 +1,21 @@
-# HubSpot CRM Integration
+# HubSpot CRM
 
-HubSpot CRM external system integration with companies, contacts, and deals
+HubSpot CRM integration with OpenAPI support for companies, contacts, and deals
 
 ## System Information
 
 - **System Key**: `hubspot`
 - **System Type**: `openapi`
-- **Datasources**: 0
+- **Datasources**: 4
 
 ## Files
 
 - `application.yaml` – Application configuration with `app` and `externalIntegration` blocks
-- `hubspot-system.json` – External system definition (authentication, OpenAPI/MCP, RBAC)
+- `hubspot-system.yaml` – External system definition (authentication, OpenAPI/MCP, RBAC)
+- `hubspot-datasource-deal.yaml` – Datasource: HubSpot Deal
+- `hubspot-datasource-contact.yaml` – Datasource: HubSpot Contact
+- `hubspot-datasource-users-datasource.yaml` – Datasource: HubSpot Users
+- `hubspot-datasource-company.yaml` – Datasource: HubSpot Company
 - `env.template` – Environment variables template (secrets, API keys)
 - `hubspot-deploy.json` – Deployment manifest (generated by `aifabrix json`)
 

package/integration/hubspot/application.json

@@ -0,0 +1,54 @@
+{
+  "app": {
+    "key": "hubspot",
+    "displayName": "HubSpot CRM",
+    "description": "HubSpot CRM integration with OpenAPI support for companies, contacts, and deals",
+    "type": "external"
+  },
+  "externalIntegration": {
+    "schemaBasePath": "./",
+    "systems": [
+      "hubspot-system.json"
+    ],
+    "dataSources": [
+      "hubspot-datasource-company.json",
+      "hubspot-datasource-contact.json",
+      "hubspot-datasource-deal.json",
+      "hubspot-datasource-users.json"
+    ],
+    "autopublish": true,
+    "version": "1.0.0"
+  },
+  "configuration": [
+    {
+      "name": "HUBSPOT_API_VERSION",
+      "portalInput": {
+        "field": "select",
+        "label": "HubSpot API Version",
+        "placeholder": "Select API version",
+        "options": [
+          "v1",
+          "v2",
+          "v3"
+        ],
+        "validation": {
+          "required": false
+        }
+      }
+    },
+    {
+      "name": "MAX_PAGE_SIZE",
+      "portalInput": {
+        "field": "text",
+        "label": "Maximum Page Size",
+        "placeholder": "100",
+        "validation": {
+          "required": false,
+          "pattern": "^[0-9]+$",
+          "minLength": 1,
+          "maxLength": 1000
+        }
+      }
+    }
+  ]
+}

package/integration/hubspot/create-hubspot.js

@@ -42,7 +42,6 @@ function printUsage() {
     '  --output <dir>             Output directory for files (default: integration/<name>)',
     '  --controller <url>         Controller URL (default: env CONTROLLER_URL)',
     '  --environment <env>        Environment name (default: env ENVIRONMENT)',
-    '  --dataplane <url>          Dataplane URL (optional, will be auto-discovered)',
     '  --keep-wizard-files        Keep wizard-generated files in integration/ directory',
     '  --help                     Show this help message',
     '',
@@ -66,7 +65,6 @@ function parseArgs(argv) {
     output: null,
     controller: DEFAULT_CONTROLLER_URL,
     environment: DEFAULT_ENVIRONMENT,
-    dataplane: process.env.DATAPLANE_URL || null,
     keepWizardFiles: false,
     help: false
   };
@@ -76,8 +74,7 @@ function parseArgs(argv) {
     '--openapi': 'openapi',
     '--output': 'output',
     '--controller': 'controller',
-    '--environment': 'environment',
-    '--dataplane': 'dataplane'
+    '--environment': 'environment'
   };
 
   for (let i = 2; i < argv.length; i += 1) {
@@ -203,119 +200,16 @@ async function createWizardConfig(appName, openapiFile, controllerUrl, environme
   return configPath;
 }
 
-/**
- * Tests a single endpoint for reachability
- * @async
- * @function testEndpoint
- * @param {string} testUrl - URL to test
- * @param {number} timeoutMs - Timeout in milliseconds
- * @returns {Promise<boolean>} True if endpoint is reachable
- */
-async function testEndpoint(testUrl, timeoutMs) {
-  try {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-
-    const response = await Promise.race([
-      fetch(testUrl, {
-        method: 'GET',
-        signal: controller.signal,
-        headers: { 'Accept': 'application/json' }
-      }),
-      new Promise((_, reject) =>
-        setTimeout(() => reject(new Error('Timeout')), timeoutMs)
-      )
-    ]).catch(() => null);
-
-    clearTimeout(timeoutId);
-
-    // If we get any response (even 404 or 401), the service is reachable
-    // 401 is OK because it means the API is working, just needs auth
-    if (response && (response.ok || response.status === 404 || response.status === 401)) {
-      return true;
-    }
-
-    // If we get a 500 or other server error, the service is up but broken
-    // Still consider it "reachable" - the wizard will handle the actual error
-    return response && response.status >= 500;
-  } catch (error) {
-    // Timeout or abort means endpoint is not reachable
-    return false;
-  }
-}
-
-/**
- * Checks if dataplane URL is reachable and API is functional
- * @async
- * @function checkDataplaneHealth
- * @param {string} dataplaneUrl - Dataplane URL to check
- * @param {number} timeoutMs - Timeout in milliseconds (default: 5000)
- * @returns {Promise<boolean>} True if dataplane is reachable and functional
- */
-async function checkDataplaneHealth(dataplaneUrl, timeoutMs = 5000) {
-  if (!dataplaneUrl) {
-    return false;
-  }
-
-  const baseUrl = dataplaneUrl.replace(/\/$/, '');
-  const endpointsToTest = ['/health', '/api/v1/health', '/api/health', ''];
-
-  for (const endpoint of endpointsToTest) {
-    const testUrl = endpoint ? `${baseUrl}${endpoint}` : baseUrl;
-    const isReachable = await testEndpoint(testUrl, timeoutMs);
-    if (isReachable) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-/**
- * Validates dataplane health before running wizard
- * @async
- * @function validateDataplaneHealth
- * @param {string} dataplaneUrl - Dataplane URL to check
- * @returns {Promise<Object|null>} Error object if unhealthy, null if healthy
- */
-async function validateDataplaneHealth(dataplaneUrl) {
-  logInfo('Checking dataplane connectivity...');
-  try {
-    const isHealthy = await checkDataplaneHealth(dataplaneUrl, 5000);
-    if (!isHealthy) {
-      return {
-        success: false,
-        stdout: '',
-        stderr: '',
-        error: `Dataplane is not reachable at ${dataplaneUrl}.\n\n` +
-               'Please ensure the dataplane service is running and accessible, then try again.\n' +
-               `You can check dataplane status with: curl ${dataplaneUrl}/health`
-      };
-    }
-    logSuccess('✓ Dataplane is reachable');
-    return null;
-  } catch (error) {
-    return {
-      success: false,
-      stdout: '',
-      stderr: '',
-      error: `Failed to check dataplane health: ${error.message}\n\n` +
-             `The dataplane at ${dataplaneUrl} may be down or unreachable.`
-    };
-  }
-}
-
 /**
  * Builds wizard command arguments
  * @function buildWizardArgs
  * @param {string} configPath - Path to wizard config file
  * @param {string} controllerUrl - Controller URL
  * @param {string} environment - Environment name
- * @param {string|null} dataplaneUrl - Optional dataplane URL
  * @returns {string[]} Command arguments
  */
-function buildWizardArgs(configPath, controllerUrl, environment, dataplaneUrl) {
-  const args = [
+function buildWizardArgs(configPath, controllerUrl, environment) {
+  return [
     'bin/aifabrix.js',
     'wizard',
     '--config',
@@ -325,19 +219,13 @@ function buildWizardArgs(configPath, controllerUrl, environment, dataplaneUrl) {
     '--environment',
     environment
   ];
-
-  if (dataplaneUrl) {
-    args.push('--dataplane', dataplaneUrl);
-  }
-
-  return args;
 }
 
 /**
  * Handles wizard command execution errors
  * @function handleWizardError
  * @param {Error} error - Error object
- * @param {string|null} dataplaneUrl - Dataplane URL
+ * @param {string|null} dataplaneUrl - Dataplane URL (for error context; may be null when auto-discovered)
  * @returns {Object} Error result object
  */
 function handleWizardError(error, dataplaneUrl) {
@@ -382,21 +270,11 @@ function handleWizardError(error, dataplaneUrl) {
  * @param {string} configPath - Path to wizard config file
  * @param {string} controllerUrl - Controller URL
  * @param {string} environment - Environment name
- * @param {string|null} dataplaneUrl - Optional dataplane URL
  * @returns {Promise<Object>} Command result object
  */
-async function runWizard(configPath, controllerUrl, environment, dataplaneUrl) {
-  if (dataplaneUrl) {
-    const healthError = await validateDataplaneHealth(dataplaneUrl);
-    if (healthError) {
-      return healthError;
-    }
-  } else {
-    logInfo('Note: No dataplane URL provided. Wizard will attempt to discover it from controller.');
-    logInfo('If dataplane discovery fails or hangs, provide --dataplane <url> explicitly.');
-  }
-
-  const args = buildWizardArgs(configPath, controllerUrl, environment, dataplaneUrl);
+async function runWizard(configPath, controllerUrl, environment) {
+  logInfo('Note: Dataplane URL is auto-discovered from the controller.');
+  const args = buildWizardArgs(configPath, controllerUrl, environment);
 
   try {
     const result = await execFileAsync('node', args, {
@@ -407,7 +285,7 @@ async function runWizard(configPath, controllerUrl, environment, dataplaneUrl) {
     });
     return { success: true, stdout: result.stdout || '', stderr: result.stderr || '' };
   } catch (error) {
-    return handleWizardError(error, dataplaneUrl);
+    return handleWizardError(error, null);
   }
 }
 
@@ -529,12 +407,7 @@ async function executeWizard(args) {
   logSuccess(`✓ Created config: ${configPath}`);
 
   logInfo('\n2. Running wizard...');
-  const wizardResult = await runWizard(
-    configPath,
-    args.controller,
-    args.environment,
-    args.dataplane
-  );
+  const wizardResult = await runWizard(configPath, args.controller, args.environment);
 
   if (!wizardResult.success) {
     logError('Wizard failed:');

package/integration/hubspot/env.template

@@ -1,5 +1,4 @@
-CLIENTID=kv://hubspot-clientidKeyVault
-CLIENTSECRET=kv://hubspot-clientsecretKeyVault
-TOKENURL=https://api.hubapi.com/oauth/v1/token
 HUBSPOT_API_VERSION=v3
-MAX_PAGE_SIZE=100
+MAX_PAGE_SIZE=100
+KV_HUBSPOT_CLIENTID=kv://hubspot/clientid
+KV_HUBSPOT_CLIENTSECRET=kv://hubspot/clientsecret