@aifabrix/builder 2.42.1 → 2.44.0

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

@@ -0,0 +1,15 @@
+---
+description: Mandatory structure for Builder CLI anchor-docs.
+globs: anchor-docs/**/*.md
+alwaysApply: false
+---
+
+# anchor-docs (Builder)
+
+When editing `anchor-docs/**/*.md` (only `README.md` is exempt). Copy `anchor-docs/_TEMPLATE` to create a new anchor (no `.md` extension — not validated):
+
+- Include YAML frontmatter: `title`, `navigation_id`, `owner`, `last_verified_commit`.
+- `navigation_id` must match **aifabrix-docs** `docs/builder/navigation.yaml` entries (`builder/<url>`).
+- Sections required: `## Summary`, `## Details`, `## Examples`, `## Paths`.
+- Reference repo files with **`[path:aifabrix-builder/...]`**; avoid backtick-only paths for the same references.
+- Align with CLI user-doc rules: keep HTTP/API endpoint names out of `docs/commands/` user text; technical anchors may cite code paths.

package/README.md

@@ -48,7 +48,7 @@ Get the platform running locally so you can try it.
    aifabrix up-infra
    ```
 
-   First-time run creates required infra secrets automatically. Use `aifabrix up-infra --adminPwd <password>` to set a custom admin password for Postgres, pgAdmin, and Redis Commander.
+   First-time run creates required infra secrets automatically. Use `aifabrix up-infra --adminPassword <password>` to set a custom admin password for Postgres, pgAdmin, and Redis Commander.
 
 2. **Start the platform** (Keycloak, Miso Controller, Dataplane) from community images:
 
@@ -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/anchor-docs/README.md

@@ -0,0 +1,10 @@
+# anchor-docs (Builder CLI)
+
+Canonical technical notes for the AI Fabrix Builder. Command references, JSON schemas, and generator entrypoints live here; **aifabrix-docs** `docs/builder/` should only summarize and link.
+
+## Conventions
+
+* Copy `anchor-docs/_TEMPLATE` to a new `*.md` file and fill in placeholders (the template is not `.md`, so it is not validated as an anchor).
+* `navigation_id` must match **aifabrix-docs** `docs/builder/navigation.yaml` (`builder/<url>`).
+* Use **`[path:aifabrix-builder/...]`** markers only.
+* PRs touching anchors should request review from the `owner` team.

package/anchor-docs/_TEMPLATE

@@ -0,0 +1,24 @@
+# Copy this file to `your-topic.md` and replace placeholders. This is not `*.md` so it is not validated as an anchor-doc.
+
+---
+title: <Title>
+navigation_id: builder/<slug-from-navigation.yaml>
+owner: <team>
+last_verified_commit: <sha-or-TBD>
+---
+
+## Summary
+
+<What this anchor covers for Builder CLI or schemas.>
+
+## Details
+
+<Implementation notes; keep persona docs in aifabrix-docs thin.>
+
+## Examples
+
+<aifabrix wizard|validate|deploy ...>
+
+## Paths
+
+[path:aifabrix-builder/README.md]

package/bin/aifabrix.js

@@ -28,14 +28,23 @@ function initializeCLI() {
 
   program.name('aifabrix')
     .version(packageJson.version)
-    .description('AI Fabrix Local Fabric & Deployment SDK');
+    .description(
+      'Local Docker infra, app scaffolding, validation, and deploy to Azure (or local) via Miso Controller'
+    );
 
   // Delegate command setup to lib/cli.js (order matches help categories for consistency)
   cli.setupCommands(program);
 
-  // Use categorized help for a more user-friendly command list
+  // Custom help replaces Commander default; append footer here (program.addHelpText is not applied)
+  const ROOT_HELP_FOOTER = `
+
+More:
+  aifabrix <command> --help    Options and examples for one command
+  docs/commands/README.md     Command reference in the repo
+`;
+
   program.helpInformation = function() {
-    return buildCategorizedHelp(program);
+    return buildCategorizedHelp(program) + ROOT_HELP_FOOTER;
   };
 
   // Parse command line arguments
@@ -51,7 +60,7 @@ if (require.main === module) {
   try {
     initializeCLI();
   } catch (error) {
-    logger.error('❌ Failed to initialize CLI:', error.message);
+    logger.error('✖ Failed to initialize CLI:', error.message);
     process.exit(1);
   }
 }

package/integration/hubspot-test/README.md

@@ -0,0 +1,157 @@
+# HubSpot CRM
+
+HubSpot CRM integration with OpenAPI support for companies, contacts, and deals
+
+## System Information
+
+- **System Key**: `hubspot-test`
+- **System Type**: `openapi`
+- **Datasources**: 4
+
+## Regenerating files with the CLI (recommended)
+
+Datasource and system JSON under this folder are **normally produced by the Builder**, not edited by hand for structural/schema changes. Use one of these flows (from the **repository root**):
+
+1. **Interactive wizard** (writes to `integration/hubspot-test/` when the app key is `hubspot-test`):
+
+   ```bash
+   aifabrix wizard hubspot-test
+   ```
+
+2. **Headless wizard – known platform HubSpot** (same folder; needs dataplane + auth):
+
+   ```bash
+   node bin/aifabrix.js wizard \
+     --config integration/hubspot-test/wizard-hubspot-test-headless.yaml \
+     --controller <YOUR_CONTROLLER_URL> \
+     --environment <YOUR_ENV>
+   ```
+
+   Edit `deployment.controller` / `deployment.environment` in that YAML if you prefer not to pass flags.
+
+3. **Helper script** (generates a temporary wizard config and runs the CLI; defaults OpenAPI to `companies.json` in this directory):
+
+   ```bash
+   node integration/hubspot-test/create-hubspot.js --name hubspot-test --keep-wizard-files
+   ```
+
+After regeneration, run `aifabrix validate hubspot-test --type external` and the HubSpot integration tests as needed.
+
+Committed copies may still be **trimmed or adjusted** for repo tests (e.g. deterministic fields); prefer changing **generators/templates** in `lib/` and `templates/` when defaults should change for everyone.
+
+## 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'));
 }
 
@@ -404,7 +404,7 @@ async function executeWizard(args) {
     args.controller,
     args.environment
   );
-  logSuccess(`✓ Created config: ${configPath}`);
+  logSuccess(`✔ Created config: ${configPath}`);
 
   logInfo('\n2. Running wizard...');
   const wizardResult = await runWizard(configPath, args.controller, args.environment);
@@ -420,7 +420,7 @@ async function executeWizard(args) {
     throw new Error('Wizard execution failed');
   }
 
-  logSuccess('✓ Wizard completed successfully');
+  logSuccess('✔ Wizard completed successfully');
   return configPath;
 }
 
@@ -444,7 +444,7 @@ async function processGeneratedFiles(args) {
   if (outputDir !== wizardOutputDir) {
     logInfo(`\n4. Copying files to: ${outputDir}`);
     const copiedFiles = await copyDirectoryContents(wizardOutputDir, outputDir);
-    logSuccess(`✓ Copied ${copiedFiles.length} files`);
+    logSuccess(`✔ Copied ${copiedFiles.length} files`);
   } else {
     logInfo(`\n4. Files are in: ${outputDir}`);
   }
@@ -462,7 +462,7 @@ async function processGeneratedFiles(args) {
  * @returns {Promise<void>} Resolves when summary is printed
  */
 async function printSummary(outputDir, appName, environment) {
-  logSuccess('\n✓ HubSpot integration created successfully!');
+  logSuccess('\n✔ HubSpot integration created successfully!');
   logger.log('\nGenerated files:');
   const files = await listFiles(outputDir);
   for (const file of files) {
@@ -490,7 +490,7 @@ async function cleanupFiles(configPath, wizardOutputDir, outputDir, keepWizardFi
   if (!keepWizardFiles && outputDir !== wizardOutputDir) {
     logInfo('\n5. Cleaning up wizard files...');
     await fs.rm(wizardOutputDir, { recursive: true, force: true });
-    logSuccess('✓ Cleaned up wizard files');
+    logSuccess('✔ Cleaned up wizard files');
   }
 
   await fs.unlink(configPath).catch(() => {

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-test/hubspot-test-datasource-company.json

@@ -0,0 +1,138 @@
+{
+  "key": "hubspot-test-company",
+  "displayName": "HubSpot Company",
+  "description": "HubSpot companies datasource with field mappings for CRM company data",
+  "systemKey": "hubspot-test",
+  "entityType": "recordStorage",
+  "resourceType": "customer",
+  "enabled": true,
+  "version": "1.0.0",
+  "primaryKey": [
+    "id"
+  ],
+  "labelKey": [
+    "name"
+  ],
+  "metadataSchema": {
+    "type": "object",
+    "required": [
+      "id",
+      "externalId",
+      "properties"
+    ],
+    "properties": {
+      "id": {
+        "type": "string",
+        "index": true
+      },
+      "externalId": {
+        "type": "string",
+        "index": true
+      },
+      "name": {
+        "type": "string",
+        "filter": true
+      },
+      "properties": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    }
+  },
+  "dimensions": {
+    "country": {
+      "type": "local",
+      "field": "country"
+    },
+    "domain": {
+      "type": "local",
+      "field": "domain"
+    }
+  },
+  "fieldMappings": {
+    "attributes": {
+      "id": {
+        "expression": "{{raw.id}}"
+      },
+      "externalId": {
+        "expression": "{{raw.id}}"
+      },
+      "name": {
+        "expression": "{{raw.properties.name.value}} | trim"
+      },
+      "domain": {
+        "expression": "{{raw.properties.domain.value}} | toLower | trim"
+      },
+      "country": {
+        "expression": "{{raw.properties.country.value}} | toUpper | trim"
+      },
+      "city": {
+        "expression": "{{raw.properties.city.value}} | trim"
+      },
+      "industry": {
+        "expression": "{{raw.properties.industry.value}} | trim"
+      },
+      "website": {
+        "expression": "{{raw.properties.website.value}} | trim"
+      },
+      "phone": {
+        "expression": "{{raw.properties.phone.value}} | trim"
+      },
+      "createdAt": {
+        "expression": "{{raw.properties.createdate.value}}"
+      },
+      "updatedAt": {
+        "expression": "{{raw.properties.hs_lastmodifieddate.value}}"
+      }
+    }
+  },
+  "exposed": {
+    "description": "Exposed fields for HubSpot companies",
+    "schema": {
+      "id": "metadata.id",
+      "externalId": "metadata.externalId",
+      "name": "metadata.name",
+      "domain": "metadata.domain",
+      "country": "metadata.country",
+      "city": "metadata.city",
+      "industry": "metadata.industry",
+      "website": "metadata.website",
+      "phone": "metadata.phone",
+      "createdAt": "metadata.createdAt",
+      "updatedAt": "metadata.updatedAt"
+    }
+  },
+  "openapi": {
+    "enabled": true,
+    "documentKey": "hubspot-v3",
+    "baseUrl": "https://api.hubapi.com",
+    "operations": {
+      "list": {
+        "operationId": "getCompanies",
+        "method": "GET",
+        "path": "/crm/v3/objects/companies"
+      },
+      "get": {
+        "operationId": "getCompany",
+        "method": "GET",
+        "path": "/crm/v3/objects/companies/{companyId}"
+      },
+      "create": {
+        "operationId": "createCompany",
+        "method": "POST",
+        "path": "/crm/v3/objects/companies"
+      },
+      "update": {
+        "operationId": "updateCompany",
+        "method": "PATCH",
+        "path": "/crm/v3/objects/companies/{companyId}"
+      },
+      "delete": {
+        "operationId": "deleteCompany",
+        "method": "DELETE",
+        "path": "/crm/v3/objects/companies/{companyId}"
+      }
+    },
+    "autoRbac": true
+  }
+}

package/integration/hubspot-test/hubspot-test-datasource-contact.json

@@ -0,0 +1,146 @@
+{
+  "key": "hubspot-test-contact",
+  "displayName": "HubSpot Contact",
+  "description": "HubSpot contacts datasource with field mappings for CRM contact data",
+  "systemKey": "hubspot-test",
+  "entityType": "recordStorage",
+  "resourceType": "contact",
+  "enabled": true,
+  "version": "1.0.0",
+  "primaryKey": [
+    "id"
+  ],
+  "labelKey": [
+    "email"
+  ],
+  "metadataSchema": {
+    "type": "object",
+    "required": [
+      "id",
+      "externalId",
+      "properties"
+    ],
+    "properties": {
+      "id": {
+        "type": "string",
+        "index": true
+      },
+      "externalId": {
+        "type": "string",
+        "index": true
+      },
+      "email": {
+        "type": "string",
+        "filter": true
+      },
+      "properties": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    }
+  },
+  "dimensions": {
+    "email": {
+      "type": "local",
+      "field": "email"
+    },
+    "country": {
+      "type": "local",
+      "field": "country"
+    }
+  },
+  "fieldMappings": {
+    "attributes": {
+      "id": {
+        "expression": "{{raw.id}}"
+      },
+      "externalId": {
+        "expression": "{{raw.id}}"
+      },
+      "firstName": {
+        "expression": "{{raw.properties.firstname.value}} | trim"
+      },
+      "lastName": {
+        "expression": "{{raw.properties.lastname.value}} | trim"
+      },
+      "email": {
+        "expression": "{{raw.properties.email.value}} | trim"
+      },
+      "phone": {
+        "expression": "{{raw.properties.phone.value}} | trim"
+      },
+      "company": {
+        "expression": "{{raw.properties.company.value}} | trim"
+      },
+      "jobTitle": {
+        "expression": "{{raw.properties.jobtitle.value}} | trim"
+      },
+      "address": {
+        "expression": "{{raw.properties.address.value}} | trim"
+      },
+      "city": {
+        "expression": "{{raw.properties.city.value}} | trim"
+      },
+      "country": {
+        "expression": "{{raw.properties.country.value}} | toUpper | trim"
+      },
+      "createdAt": {
+        "expression": "{{raw.properties.createdate.value}}"
+      },
+      "updatedAt": {
+        "expression": "{{raw.properties.hs_lastmodifieddate.value}}"
+      }
+    }
+  },
+  "exposed": {
+    "description": "Exposed fields for HubSpot contacts",
+    "schema": {
+      "id": "metadata.id",
+      "externalId": "metadata.externalId",
+      "firstName": "metadata.firstName",
+      "lastName": "metadata.lastName",
+      "email": "metadata.email",
+      "phone": "metadata.phone",
+      "company": "metadata.company",
+      "jobTitle": "metadata.jobTitle",
+      "address": "metadata.address",
+      "city": "metadata.city",
+      "country": "metadata.country",
+      "createdAt": "metadata.createdAt",
+      "updatedAt": "metadata.updatedAt"
+    }
+  },
+  "openapi": {
+    "enabled": true,
+    "documentKey": "hubspot-v3",
+    "baseUrl": "https://api.hubapi.com",
+    "operations": {
+      "list": {
+        "operationId": "getContacts",
+        "method": "GET",
+        "path": "/crm/v3/objects/contacts"
+      },
+      "get": {
+        "operationId": "getContact",
+        "method": "GET",
+        "path": "/crm/v3/objects/contacts/{contactId}"
+      },
+      "create": {
+        "operationId": "createContact",
+        "method": "POST",
+        "path": "/crm/v3/objects/contacts"
+      },
+      "update": {
+        "operationId": "updateContact",
+        "method": "PATCH",
+        "path": "/crm/v3/objects/contacts/{contactId}"
+      },
+      "delete": {
+        "operationId": "deleteContact",
+        "method": "DELETE",
+        "path": "/crm/v3/objects/contacts/{contactId}"
+      }
+    },
+    "autoRbac": true
+  }
+}