@aifabrix/builder 2.42.1 → 2.43.0

package/README.md

@@ -82,7 +82,7 @@ Create and deploy an external system (e.g. HubSpot): wizard or manual setup, the
 
 **Example: HubSpot**
 
-- Create: `aifabrix create hubspot` (external is the default; or `aifabrix wizard` for guided setup). For a web app use `aifabrix create my-app --type webapp`.
+- Create: `aifabrix create hubspot-test` (external is the default; or `aifabrix wizard` for guided setup). For a web app use `aifabrix create my-app --type webapp`.
 - Configure auth and datasources under `integration/hubspot-test/`.
 - Validate: `aifabrix validate hubspot-test`
 - Deploy: `aifabrix deploy hubspot-test`

package/bin/aifabrix.js

@@ -28,7 +28,7 @@ function initializeCLI() {
 
   program.name('aifabrix')
     .version(packageJson.version)
-    .description('AI Fabrix Local Fabric & Deployment SDK');
+    .description('AI Fabrix Builder – Help and documentation');
 
   // Delegate command setup to lib/cli.js (order matches help categories for consistency)
   cli.setupCommands(program);

package/integration/hubspot-test/README.md

@@ -0,0 +1,126 @@
+# HubSpot CRM
+
+HubSpot CRM integration with OpenAPI support for companies, contacts, and deals
+
+## System Information
+
+- **System Key**: `hubspot-test`
+- **System Type**: `openapi`
+- **Datasources**: 4
+
+## Files
+
+- `application.yaml` – Application configuration with `app` and `externalIntegration` blocks
+- `hubspot-test-system.json` – External system definition (authentication, OpenAPI/MCP, RBAC)
+- `hubspot-test-datasource-deal.json` – Datasource: HubSpot Deal
+- `hubspot-test-datasource-contact.json` – Datasource: HubSpot Contact
+- `hubspot-test-datasource-users.json` – Datasource: HubSpot Users
+- `hubspot-test-datasource-company.json` – Datasource: HubSpot Company
+- `env.template` – Environment variables template (secrets, API keys)
+- `hubspot-test-deploy.json` – Deployment manifest (generated by `aifabrix json`)
+
+Optional: `rbac.yaml` – Roles and permissions merged into the system when present.
+
+## Quick Start
+
+### 1. Create External System
+
+```bash
+aifabrix create hubspot-test
+```
+
+(External is the default type. Use `aifabrix create <name> --type webapp` for a builder app.)
+
+Or use the interactive wizard:
+
+```bash
+aifabrix wizard --app hubspot-test
+```
+
+### 2. Configure Authentication and Datasources
+
+Edit files in `integration/hubspot-test/`:
+
+- **Authentication**: `hubspot-test-system.json` (auth type, credentials placeholders)
+- **Field mappings**: `hubspot-test-datasource-*.json` (dimensions, attributes, operations)
+
+### 3. Validate Configuration
+
+```bash
+aifabrix validate hubspot-test --type external
+```
+
+### 4. Generate Deployment Manifest
+
+```bash
+aifabrix json hubspot-test --type external
+```
+
+This creates `hubspot-test-deploy.json` in `integration/hubspot-test/`.
+
+### 5. Deploy
+
+Controller URL and environment are read from config. Configure and log in first:
+
+```bash
+aifabrix auth config --set-controller <url> --set-environment dev
+aifabrix login
+```
+
+Then deploy:
+
+```bash
+aifabrix deploy hubspot-test
+```
+
+## Testing
+
+### Unit Tests (Local Validation, No API)
+
+```bash
+aifabrix test hubspot-test
+```
+
+### Integration Tests (Via Dataplane)
+
+```bash
+aifabrix test-integration hubspot-test
+```
+
+## Deployment
+
+Deploy via miso-controller pipeline (same as regular apps). Auth and controller come from `aifabrix login` and `aifabrix auth config`:
+
+```bash
+aifabrix deploy hubspot-test
+```
+
+## Wizard E2E tests (`test.js`)
+
+Run positive wizard tests with:
+
+```bash
+pnpm test:hubspot-wizard:positive
+```
+
+If you see **"Invalid token or insufficient permissions"** or **"Failed to create wizard session"** even though `aifabrix auth status` shows connected, the dataplane may be configured to accept only **client credentials** for the wizard API, not device tokens.
+
+**Option A – Use client credentials (recommended if dataplane requires them)**
+
+1. Get a **client ID** and **client secret** for an app that the dataplane accepts for wizard (e.g. from your admin or Miso/Keycloak for the environment).
+2. Put them in **`~/.aifabrix/secrets.local.yaml`** under keys that depend on the **app name in the wizard config**:
+   - For `wizard-hubspot-e2e.yaml` the app name is `wizard-e2e-e2e`, so use:
+     - `wizard-e2e-e2e-client-idKeyVault`: `<your client id>`
+     - `wizard-e2e-e2e-client-secretKeyVault`: `<your client secret>`
+   - If your platform uses a single “wizard” or “dataplane” app for all wizard runs, ask your admin for that app’s client ID/secret and the exact key names (they may be something like `dataplane-client-idKeyVault` / `dataplane-client-secretKeyVault`; the builder looks up `<appName>-client-idKeyVault` and `<appName>-client-secretKeyVault` where `appName` comes from the config file).
+3. **Optional fallback:** you can also set **`integration/hubspot-test/.env`** with `CLIENTID` and `CLIENTSECRET`; the test runner maps those to `HUBSPOT_CLIENT_ID` / `HUBSPOT_CLIENT_SECRET` for real-credential tests, and the token manager uses `CLIENTID`/`CLIENTSECRET` when no secrets file entry exists for the app.
+
+**Option B – Use device token**
+
+If the dataplane is configured to accept device tokens for the wizard API, ensure you are logged in with `aifabrix login` and that the controller URL and environment match (e.g. `dev`). No client credentials are needed.
+
+## Troubleshooting
+
+- **Validation errors**: Run `aifabrix validate hubspot-test --type external` to see schema and manifest errors.
+- **Deployment / auth**: Run `aifabrix auth config --set-controller <url> --set-environment <env>` and `aifabrix login` before `aifabrix deploy`.
+- **File not found**: Run commands from the project root (where `package.json` and `integration/` live).

package/integration/{hubspot → hubspot-test}/application.json

@@ -1,6 +1,6 @@
 {
   "app": {
-    "key": "hubspot",
+    "key": "hubspot-test",
     "displayName": "HubSpot CRM",
     "description": "HubSpot CRM integration with OpenAPI support for companies, contacts, and deals",
     "type": "external"
@@ -8,13 +8,13 @@
   "externalIntegration": {
     "schemaBasePath": "./",
     "systems": [
-      "hubspot-system.json"
+      "hubspot-test-system.json"
     ],
     "dataSources": [
-      "hubspot-datasource-company.json",
-      "hubspot-datasource-contact.json",
-      "hubspot-datasource-deal.json",
-      "hubspot-datasource-users.json"
+      "hubspot-test-datasource-company.json",
+      "hubspot-test-datasource-contact.json",
+      "hubspot-test-datasource-deal.json",
+      "hubspot-test-datasource-users.json"
     ],
     "autopublish": true,
     "version": "1.0.0"

package/integration/{hubspot → hubspot-test}/create-hubspot.js

@@ -24,7 +24,7 @@ const execFileAsync = promisify(execFile);
 const DEFAULT_CONTROLLER_URL = process.env.CONTROLLER_URL || 'http://localhost:3110';
 const DEFAULT_ENVIRONMENT = process.env.ENVIRONMENT || 'miso';
 const DEFAULT_OPENAPI_FILE = process.env.HUBSPOT_OPENAPI_FILE ||
-  path.join(process.cwd(), 'integration', 'hubspot', 'companies.json');
+  path.join(process.cwd(), 'integration', 'hubspot-test', 'companies.json');
 
 /**
  * Prints usage information
@@ -34,7 +34,7 @@ const DEFAULT_OPENAPI_FILE = process.env.HUBSPOT_OPENAPI_FILE ||
 function printUsage() {
   logger.log([
     'Usage:',
-    '  node integration/hubspot/create-hubspot.js [options]',
+    '  node integration/hubspot-test/create-hubspot.js [options]',
     '',
     'Options:',
     '  --name <name>              Application name (required)',
@@ -46,9 +46,9 @@ function printUsage() {
     '  --help                     Show this help message',
     '',
     'Examples:',
-    '  node integration/hubspot/create-hubspot.js --name my-hubspot',
-    '  node integration/hubspot/create-hubspot.js --name my-hubspot --output ~/my-project',
-    '  node integration/hubspot/create-hubspot.js --name my-hubspot --openapi /path/to/openapi.json'
+    '  node integration/hubspot-test/create-hubspot.js --name my-hubspot',
+    '  node integration/hubspot-test/create-hubspot.js --name my-hubspot --output ~/my-project',
+    '  node integration/hubspot-test/create-hubspot.js --name my-hubspot --openapi /path/to/openapi.json'
   ].join('\n'));
 }
 

package/integration/hubspot-test/env.template

@@ -0,0 +1,4 @@
+HUBSPOT_API_VERSION=v3
+MAX_PAGE_SIZE=100
+KV_HUBSPOT_TEST_CLIENTID=kv://hubspot-test/clientId
+KV_HUBSPOT_TEST_CLIENTSECRET=kv://hubspot-test/clientSecret

package/integration/{hubspot/hubspot-datasource-company.json → hubspot-test/hubspot-test-datasource-company.json}

@@ -1,12 +1,13 @@
 {
-  "key": "hubspot-company",
+  "key": "hubspot-test-company",
   "displayName": "HubSpot Company",
   "description": "HubSpot companies datasource with field mappings for CRM company data",
-  "systemKey": "hubspot",
+  "systemKey": "hubspot-test",
   "entityType": "record-storage",
   "resourceType": "customer",
   "enabled": true,
   "version": "1.0.0",
+  "primaryKey": ["id"],
   "metadataSchema": {
     "type": "object",
     "properties": {

package/integration/{hubspot/hubspot-datasource-contact.json → hubspot-test/hubspot-test-datasource-contact.json}

@@ -1,12 +1,13 @@
 {
-  "key": "hubspot-contact",
+  "key": "hubspot-test-contact",
   "displayName": "HubSpot Contact",
   "description": "HubSpot contacts datasource with field mappings for CRM contact data",
-  "systemKey": "hubspot",
+  "systemKey": "hubspot-test",
   "entityType": "record-storage",
   "resourceType": "contact",
   "enabled": true,
   "version": "1.0.0",
+  "primaryKey": ["id"],
   "metadataSchema": {
     "type": "object",
     "properties": {

package/integration/{hubspot/hubspot-datasource-deal.json → hubspot-test/hubspot-test-datasource-deal.json}

@@ -1,12 +1,13 @@
 {
-  "key": "hubspot-deal",
+  "key": "hubspot-test-deal",
   "displayName": "HubSpot Deal",
   "description": "HubSpot deals datasource with field mappings for CRM deal data",
-  "systemKey": "hubspot",
+  "systemKey": "hubspot-test",
   "entityType": "record-storage",
   "resourceType": "deal",
   "enabled": true,
   "version": "1.0.0",
+  "primaryKey": ["id"],
   "metadataSchema": {
     "type": "object",
     "properties": {

package/integration/{hubspot/hubspot-datasource-users.json → hubspot-test/hubspot-test-datasource-users.json}

@@ -1,10 +1,11 @@
 {
-  "key": "hubspot-users-datasource",
+  "key": "hubspot-test-users",
   "displayName": "HubSpot Users",
   "resourceType": "person",
-  "systemKey": "hubspot",
+  "systemKey": "hubspot-test",
   "enabled": true,
   "entityType": "recordStorage",
+  "primaryKey": ["id"],
   "description": "Comprehensive HubSpot users datasource with full CRUD operations, comprehensive metadata schema, ABAC dimensions, and OpenAPI support",
   "metadataSchema": {
     "type": "object",

package/integration/{hubspot/hubspot-deploy.json → hubspot-test/hubspot-test-deploy.json}

@@ -1,5 +1,5 @@
 {
-  "key": "hubspot",
+  "key": "hubspot-test",
   "displayName": "HubSpot CRM",
   "description": "HubSpot CRM integration with OpenAPI support for companies, contacts, and deals",
   "type": "external",
@@ -7,19 +7,19 @@
   "externalIntegration": {
     "schemaBasePath": "./",
     "systems": [
-      "hubspot-system.json"
+      "hubspot-test-system.json"
     ],
     "dataSources": [
-      "hubspot-datasource-company.json",
-      "hubspot-datasource-contact.json",
-      "hubspot-datasource-deal.json",
-      "hubspot-datasource-users.json"
+      "hubspot-test-datasource-company.json",
+      "hubspot-test-datasource-contact.json",
+      "hubspot-test-datasource-deal.json",
+      "hubspot-test-datasource-users.json"
     ],
     "autopublish": true,
     "version": "1.0.0"
   },
   "system": {
-    "key": "hubspot",
+    "key": "hubspot-test",
     "displayName": "HubSpot CRM",
     "description": "HubSpot CRM integration with OpenAPI support for companies, contacts, and deals",
     "type": "openapi",
@@ -29,11 +29,12 @@
       "variables": {
         "baseUrl": "https://api.hubapi.com",
         "tokenUrl": "https://api.hubapi.com/oauth/v1/token",
+        "authorizationUrl": "https://app.hubspot.com/oauth/authorize",
         "scope": "crm.objects.companies.read crm.objects.companies.write crm.objects.contacts.read crm.objects.contacts.write crm.objects.deals.read crm.objects.deals.write"
       },
       "security": {
-        "clientId": "kv://hubspot/clientid",
-        "clientSecret": "kv://hubspot/clientsecret"
+        "clientId": "kv://hubspot-test/clientId",
+        "clientSecret": "kv://hubspot-test/clientSecret"
       }
     },
     "configuration": [
@@ -85,22 +86,189 @@
       "hubspot"
     ],
     "dataSources": [
-      "hubspot-company",
-      "hubspot-contact",
-      "hubspot-deal",
-      "hubspot-users-datasource"
+      "hubspot-test-company",
+      "hubspot-test-contact",
+      "hubspot-test-deal",
+      "hubspot-test-users"
+    ],
+    "roles": [
+      {
+        "name": "HubSpot CRM Admin",
+        "value": "hubspot-test-admin",
+        "description": "Full access to all HubSpot CRM operations",
+        "groups": []
+      },
+      {
+        "name": "HubSpot CRM Reader",
+        "value": "hubspot-test-reader",
+        "description": "Read-only access to all HubSpot CRM data",
+        "groups": []
+      }
+    ],
+    "permissions": [
+      {
+        "name": "customer:list",
+        "roles": [
+          "hubspot-test-reader",
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: customer:list"
+      },
+      {
+        "name": "customer:get",
+        "roles": [
+          "hubspot-test-reader",
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: customer:get"
+      },
+      {
+        "name": "customer:create",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: customer:create"
+      },
+      {
+        "name": "customer:update",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: customer:update"
+      },
+      {
+        "name": "customer:delete",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: customer:delete"
+      },
+      {
+        "name": "contact:list",
+        "roles": [
+          "hubspot-test-reader",
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: contact:list"
+      },
+      {
+        "name": "contact:get",
+        "roles": [
+          "hubspot-test-reader",
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: contact:get"
+      },
+      {
+        "name": "contact:create",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: contact:create"
+      },
+      {
+        "name": "contact:update",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: contact:update"
+      },
+      {
+        "name": "contact:delete",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: contact:delete"
+      },
+      {
+        "name": "deal:list",
+        "roles": [
+          "hubspot-test-reader",
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: deal:list"
+      },
+      {
+        "name": "deal:get",
+        "roles": [
+          "hubspot-test-reader",
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: deal:get"
+      },
+      {
+        "name": "deal:create",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: deal:create"
+      },
+      {
+        "name": "deal:update",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: deal:update"
+      },
+      {
+        "name": "deal:delete",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: deal:delete"
+      },
+      {
+        "name": "person:list",
+        "roles": [
+          "hubspot-test-reader",
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: person:list"
+      },
+      {
+        "name": "person:get",
+        "roles": [
+          "hubspot-test-reader",
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: person:get"
+      },
+      {
+        "name": "person:create",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: person:create"
+      },
+      {
+        "name": "person:update",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: person:update"
+      },
+      {
+        "name": "person:delete",
+        "roles": [
+          "hubspot-test-admin"
+        ],
+        "description": "Permission: person:delete"
+      }
     ]
   },
   "dataSources": [
     {
-      "key": "hubspot-company",
+      "key": "hubspot-test-company",
       "displayName": "HubSpot Company",
       "description": "HubSpot companies datasource with field mappings for CRM company data",
-      "systemKey": "hubspot",
+      "systemKey": "hubspot-test",
       "entityType": "record-storage",
       "resourceType": "customer",
       "enabled": true,
       "version": "1.0.0",
+      "primaryKey": [
+        "id"
+      ],
       "metadataSchema": {
         "type": "object",
         "properties": {
@@ -634,14 +802,17 @@
       }
     },
     {
-      "key": "hubspot-contact",
+      "key": "hubspot-test-contact",
       "displayName": "HubSpot Contact",
       "description": "HubSpot contacts datasource with field mappings for CRM contact data",
-      "systemKey": "hubspot",
+      "systemKey": "hubspot-test",
       "entityType": "record-storage",
       "resourceType": "contact",
       "enabled": true,
       "version": "1.0.0",
+      "primaryKey": [
+        "id"
+      ],
       "metadataSchema": {
         "type": "object",
         "properties": {
@@ -1273,14 +1444,17 @@
       }
     },
     {
-      "key": "hubspot-deal",
+      "key": "hubspot-test-deal",
       "displayName": "HubSpot Deal",
       "description": "HubSpot deals datasource with field mappings for CRM deal data",
-      "systemKey": "hubspot",
+      "systemKey": "hubspot-test",
       "entityType": "record-storage",
       "resourceType": "deal",
       "enabled": true,
       "version": "1.0.0",
+      "primaryKey": [
+        "id"
+      ],
       "metadataSchema": {
         "type": "object",
         "properties": {
@@ -1861,12 +2035,15 @@
       }
     },
     {
-      "key": "hubspot-users-datasource",
+      "key": "hubspot-test-users",
       "displayName": "HubSpot Users",
       "resourceType": "person",
-      "systemKey": "hubspot",
+      "systemKey": "hubspot-test",
       "enabled": true,
       "entityType": "recordStorage",
+      "primaryKey": [
+        "id"
+      ],
       "description": "Comprehensive HubSpot users datasource with full CRUD operations, comprehensive metadata schema, ABAC dimensions, and OpenAPI support",
       "metadataSchema": {
         "type": "object",

package/integration/{hubspot/hubspot-system.json → hubspot-test/hubspot-test-system.json}

@@ -1,5 +1,5 @@
 {
-  "key": "hubspot",
+  "key": "hubspot-test",
   "displayName": "HubSpot CRM",
   "description": "HubSpot CRM integration with OpenAPI support for companies, contacts, and deals",
   "type": "openapi",
@@ -9,11 +9,12 @@
     "variables": {
       "baseUrl": "https://api.hubapi.com",
       "tokenUrl": "https://api.hubapi.com/oauth/v1/token",
+      "authorizationUrl": "https://app.hubspot.com/oauth/authorize",
       "scope": "crm.objects.companies.read crm.objects.companies.write crm.objects.contacts.read crm.objects.contacts.write crm.objects.deals.read crm.objects.deals.write"
     },
     "security": {
-      "clientId": "kv://hubspot/clientid",
-      "clientSecret": "kv://hubspot/clientsecret"
+      "clientId": "kv://hubspot-test/clientId",
+      "clientSecret": "kv://hubspot-test/clientSecret"
     }
   },
   "configuration": [
@@ -65,9 +66,9 @@
     "hubspot"
   ],
   "dataSources": [
-    "hubspot-company",
-    "hubspot-contact",
-    "hubspot-deal",
-    "hubspot-users-datasource"
+    "hubspot-test-company",
+    "hubspot-test-contact",
+    "hubspot-test-deal",
+    "hubspot-test-users"
   ]
 }