@aifabrix/builder 2.49.1 → 2.50.0

package/integration/README.md

@@ -0,0 +1,81 @@
+# Platform integrations (aifabrix-builder SSOT)
+
+Production and platform integration manifests live here — **not** in aifabrix-dataplane `integration/` (lab/CI mirrors only).
+
+**Use the Builder CLI for everything below** — do not hand-scaffold folders or copy from dataplane. SSOT files in git are maintained by the team; developers bootstrap and change integrations with `aifabrix` commands.
+
+## Three-layer model (154.0 / 154.1)
+
+| Layer | Artifact | Path | Bootstrap (Builder CLI) |
+| --- | --- | --- | --- |
+| **1 — Builder API** | Platform webapp (workspace HTTP orchestration) | `../builder/builder-api/` | `aifabrix up-builder-api` or `aifabrix create builder-api --template builder-api --type webapp` |
+| **1 — GitHub provider** | Production GitHub external system (`apiProvider: github`) | `github/` | `aifabrix create github --type external` then repair/json — **not** OpenAPI wizard (custom CIP + delegated OAuth) |
+| **2 — Enterprise MCP** | COM anchor (repository.\*, template.\*) | `../enterprise-knowledge/enterprise-integration-lifecycle/` | `aifabrix create enterprise-integration-lifecycle --type external` then edit system subscriptions — wizard does not generate COM tasks yet |
+
+**Role assistants (Layer 3):** Platform-generated from certified business roles — not hand-authored integration folders here. See [How role assistants are created](https://docs.aifabrix.ai/docs/role-assistants-how-role-assistants-are-created). Admins **Activate for AI**; users do not submit role keys or capability lists.
+
+```text
+builder-api  →  WORKSPACE_ROOT/{userId}/integration/{systemKey}/
+              →  Enterprise MCP execute on enterprise-integration-lifecycle
+github       →  production repository provider (aifabrix upload → dataplane)
+```
+
+## Builder CLI workflow (normative)
+
+### Prerequisites
+
+```bash
+aifabrix auth status
+aifabrix up-infra          # Postgres, Redis
+aifabrix up-platform       # or up-miso + up-dataplane + up-builder-api
+```
+
+### Builder API (webapp — `builder/`, not `integration/`)
+
+Materialized from `templates/applications/builder-api/` into `builder/builder-api/`:
+
+```bash
+aifabrix up-builder-api              # copy template if missing, resolve, run
+aifabrix resolve builder-api         # expand url:// and kv:// in env.template → .env
+aifabrix run builder-api --reload    # or: pnpm run dev-reload (from aifabrix-builder repo root)
+aifabrix validate builder-api
+```
+
+Repo maintainers edit SSOT under `builder/builder-api/` and run `npm run sync-json` to refresh templates — same pattern as miso-controller/dataplane.
+
+### External integrations (`integration/<systemKey>/`)
+
+| Command | When |
+| --- | --- |
+| `aifabrix create <app> --type external` | New integration folder scaffold |
+| `aifabrix wizard` / `aifabrix wizard --config …` | OpenAPI/MCP/known-platform integrations (HubSpot, etc.) |
+| `aifabrix repair <systemKey>` | Fix manifest drift, auth, env.template, `deploy.js`, deploy JSON |
+| `aifabrix json <systemKey>` | Regenerate `<systemKey>-deploy.json` |
+| `aifabrix validate <systemKey>` | Schema + deployment manifest gate |
+| `aifabrix upload <systemKey> --probe` | Publish config to dataplane (pipeline) |
+| `aifabrix download <systemKey>` | Pull an already-published system from dataplane into `integration/` |
+
+**Platform SSOT in this repo** was checked in after initial `create` + manual COM/custom auth edits (see each folder’s `INTEGRATION_CHANGELOG.md`).
+
+### Publish order (dev)
+
+```bash
+aifabrix upload enterprise-integration-lifecycle --probe
+aifabrix upload github --probe
+aifabrix run builder-api --reload
+```
+
+Enterprise MCP anchor must be on dataplane **before** repository provider integrations such as **`github`**.
+
+## Why not wizard for these two?
+
+| Integration | Reason |
+| --- | --- |
+| `github` | `type: custom`, `authType: apiProvider` (Miso GitHub App + delegated OAuth). Wizard targets OpenAPI/MCP shapes; manifests are maintained with `create` → edit → `repair` → `json`. |
+| `enterprise-integration-lifecycle` | COM subscription + `generateEnterpriseDatasources` task. Not generated by wizard today; use `create --type external` + system.json subscription block. |
+
+For standard CRM/API integrations, use `integration/wizard-configs/*.yaml` and `aifabrix wizard --config …` (see `integration/hubspot-test/` examples).
+
+**Note:** Dataplane may still mirror legacy `integration/test-e2e-github/` for CI until aligned; **production SSOT is `integration/github/`** in this repo.
+
+Lab-only fixtures (`hubspot-test/`, `roundtrip-test-local*`) remain for Builder CLI regression tests.

package/integration/github/README.md

@@ -0,0 +1,53 @@
+# GitHub (production repository provider)
+
+**Production SSOT** for the GitHub repository provider (Layer 1 — 154.1). Path: **`aifabrix-builder/integration/github/`**.
+
+Delegated OAuth via Miso **`apiProvider: github`**, issues/comments datasources, and **`github-repository`** (`resourceType: repository`) for Enterprise MCP lifecycle.
+
+**Setup:** `aifabrix upload github --probe` after Miso GitHub provider is linked.
+
+## Scope
+
+| Datasource | Operations |
+| --- | --- |
+| `github-issues` | list, get, create, update, delete (maps to **close**; GitHub has no hard delete) |
+| `github-issue-comments` | list (by `issueNumber`), create |
+| `github-repository` | repository lifecycle CIP (`status`, `sync`, branches, reviews, pipeline dispatch) |
+
+## Authentication
+
+- External system key: **`github`**
+- Auth: **`authType: apiProvider`** → Miso provider **`github`**
+- Use a **GitHub App** with **expiring user access tokens** (refresh tokens required for Miso link/mint).
+- Link the provider for your user in Miso before running CIP execute tests.
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `BASE_URL` | `https://api.github.com` (default in manifest) |
+| `GITHUB_OWNER` | Repository owner |
+| `GITHUB_REPO` | Repository name |
+
+See [`env.template`](env.template) for deploy placeholders.
+
+## Quick start
+
+```bash
+aifabrix validate github
+aifabrix json github
+aifabrix upload github --probe
+
+# Or run the generated deploy script from the integration folder:
+node integration/github/deploy.js
+```
+
+## Manifest files
+
+| File | Role |
+| --- | --- |
+| [`github-system.json`](github-system.json) | External system |
+| [`github-datasource-issues.json`](github-datasource-issues.json) | Issues datasource |
+| [`github-datasource-issue-comments.json`](github-datasource-issue-comments.json) | Comments datasource |
+| [`github-datasource-repository.json`](github-datasource-repository.json) | Repository datasource (`resourceType: repository`) |
+| [`github-deploy.json`](github-deploy.json) | Pipeline upload payload (regenerate with `aifabrix json github`) |

package/integration/github/application.json

@@ -0,0 +1,21 @@
+{
+  "app": {
+    "key": "github",
+    "displayName": "GitHub",
+    "description": "Production GitHub repository provider: delegated OAuth via Miso apiProvider, issues, comments, and repository lifecycle CIP.",
+    "type": "external"
+  },
+  "externalIntegration": {
+    "schemaBasePath": "./",
+    "systems": [
+      "github-system.json"
+    ],
+    "dataSources": [
+      "github-datasource-issues.json",
+      "github-datasource-issue-comments.json",
+      "github-datasource-repository.json"
+    ],
+    "autopublish": true,
+    "version": "1.0.0"
+  }
+}

package/integration/github/deploy.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * Deploy github external system and datasources using aifabrix CLI.
+ * Run: node deploy.js
+ * Flow: check auth → login if needed → deploy → run integration tests.
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const scriptDir = __dirname;
+// Project root (repo containing integration/ and builder/) so deploy/test-integration resolve app paths correctly
+const projectRoot = path.join(scriptDir, '..', '..');
+const appKey = 'github';
+const env = process.env.ENVIRONMENT || 'dev';
+// Controller URL: from config (aifabrix auth config) or set CONTROLLER env before running
+
+/**
+ * Run a shell command with optional options.
+ * @param {string} cmd - Command to run
+ * @param {Object} [options={}] - Options (cwd, stdio, ignoreExit)
+ * @returns {boolean} True if command succeeded
+ */
+function run(cmd, options = {}) {
+  const opts = { cwd: scriptDir, stdio: 'inherit', ...options };
+  try {
+    execSync(cmd, opts);
+    return true;
+  } catch (err) {
+    if (options.ignoreExit) return false;
+    process.exit(err.status ?? 1);
+  }
+}
+
+/**
+ * Check if aifabrix auth is logged in.
+ * @returns {boolean} True if logged in
+ */
+function isLoggedIn() {
+  try {
+    execSync('aifabrix auth status', { cwd: scriptDir, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+console.log('🔍 Checking authentication...');
+if (!isLoggedIn()) {
+  console.log('⚠  Not logged in. Run login (e.g. aifabrix login --controller <url> --method device --environment ' + env + ').');
+  run('aifabrix login --environment ' + env);
+}
+
+console.log('🔍 Validating configuration...');
+run('aifabrix validate "' + path.join(scriptDir, 'github-system.json') + '"');
+run('aifabrix validate "' + path.join(scriptDir, 'github-datasource-issues.json') + '"');
+run('aifabrix validate "' + path.join(scriptDir, 'github-datasource-issue-comments.json') + '"');
+run('aifabrix validate "' + path.join(scriptDir, 'github-datasource-repository.json') + '"');
+console.log('✔ Validation passed');
+
+console.log('🚀 Deploying ' + appKey + '...');
+run('aifabrix deploy ' + appKey, { cwd: projectRoot });
+console.log('✔ Deployment complete');
+
+if (process.env.RUN_TESTS !== 'false') {
+  console.log('🧪 Running integration tests...');
+  run('aifabrix test-integration ' + appKey, { cwd: projectRoot });
+  console.log('✔ Tests passed');
+}
+
+console.log('✔ Done.');

package/integration/github/env.template

@@ -0,0 +1,11 @@
+# GitHub test E2E – copy values into deploy / system configuration.
+# Authentication is delegated via Miso API Provider `github` (GitHub App + expiring user tokens).
+# Do not store OAuth client secrets here; configure the provider in Miso Controller.
+
+# Repository owner (organization or user login)
+GITHUB_OWNER=your-github-owner
+
+# Repository name (without owner prefix)
+GITHUB_REPO=your-repo-name
+
+BASE_URL=https://api.github.com

package/integration/github/github-datasource-issue-comments.json

@@ -0,0 +1,239 @@
+{
+  "key": "github-issue-comments",
+  "displayName": "GitHub Issue Comments",
+  "description": "Comments on repository issues via GitHub REST API: list and create.",
+  "enabled": true,
+  "systemKey": "github",
+  "resourceType": "message",
+  "entityType": "recordStorage",
+  "version": "1.0.0",
+  "businessOrder": 2,
+  "metadataSchema": {
+    "type": "object",
+    "properties": {
+      "externalId": {
+        "type": "string",
+        "index": true,
+        "description": "Stable external record identifier (comment id as string)"
+      },
+      "id": {
+        "type": "integer",
+        "index": true,
+        "description": "GitHub comment id"
+      },
+      "issueNumber": {
+        "type": "integer",
+        "index": true,
+        "description": "Parent issue number"
+      },
+      "body": {
+        "type": "string",
+        "description": "Comment body (markdown)"
+      },
+      "htmlUrl": {
+        "type": "string",
+        "format": "uri",
+        "description": "Web URL for the comment"
+      },
+      "createdAt": {
+        "type": "string",
+        "format": "date-time",
+        "description": "Comment creation timestamp"
+      },
+      "updatedAt": {
+        "type": "string",
+        "format": "date-time",
+        "description": "Comment last update timestamp"
+      }
+    },
+    "required": [
+      "id"
+    ]
+  },
+  "fieldMappings": {
+    "attributes": {
+      "externalId": {
+        "expression": "{{raw.id}}"
+      },
+      "id": {
+        "expression": "{{raw.id}}"
+      },
+      "body": {
+        "expression": "{{raw.body}}"
+      },
+      "htmlUrl": {
+        "expression": "{{raw.html_url}}"
+      },
+      "createdAt": {
+        "expression": "{{raw.created_at}}"
+      },
+      "updatedAt": {
+        "expression": "{{raw.updated_at}}"
+      }
+    }
+  },
+  "primaryKey": [
+    "id"
+  ],
+  "labelKey": [
+    "id"
+  ],
+  "exposed": {
+    "readonly": [
+      "id",
+      "htmlUrl",
+      "createdAt",
+      "updatedAt"
+    ],
+    "schema": {
+      "externalId": "metadata.externalId",
+      "id": "metadata.id",
+      "body": "metadata.body",
+      "htmlUrl": "metadata.htmlUrl",
+      "createdAt": "metadata.createdAt",
+      "updatedAt": "metadata.updatedAt"
+    },
+    "profiles": {
+      "default": [
+        "id",
+        "body",
+        "htmlUrl",
+        "createdAt",
+        "updatedAt"
+      ],
+      "create": [
+        "body"
+      ]
+    }
+  },
+  "openapi": {
+    "enabled": true,
+    "autoRbac": false,
+    "operations": {
+      "list": {
+        "operationId": "list-repos-owner-repo-issues-issue-number-comments",
+        "method": "GET",
+        "path": "/repos/{GITHUB_OWNER}/{GITHUB_REPO}/issues/{issueNumber}/comments",
+        "permissions": ["external-system:read"]
+      }
+    },
+    "documentKey": "github-issue-comments"
+  },
+  "quality": {
+    "rejectIf": [
+      {
+        "field": "id",
+        "operator": "empty",
+        "message": "Comment id cannot be empty"
+      },
+      {
+        "field": "body",
+        "operator": "empty",
+        "message": "Comment body cannot be empty"
+      }
+    ]
+  },
+  "testPayload": {
+    "payloadTemplate": {
+      "id": 900001,
+      "body": "E2E test comment from AI Fabrix.",
+      "html_url": "https://github.com/octocat/Hello-World/issues/42#issuecomment-900001",
+      "created_at": "2025-01-15T11:00:00Z",
+      "updated_at": "2025-01-15T11:00:00Z"
+    },
+    "expectedResult": {
+      "id": 900001,
+      "issueNumber": 42,
+      "body": "E2E test comment from AI Fabrix.",
+      "htmlUrl": "https://github.com/octocat/Hello-World/issues/42#issuecomment-900001"
+    }
+  },
+  "execution": {
+    "engine": "cip",
+    "cip": {
+      "version": "1.0",
+      "inputType": "void",
+      "outputType": "records",
+      "operations": {
+        "list": {
+          "enabled": true,
+          "description": "List comments on an issue (requires parameters.issueNumber)",
+          "steps": [
+            {
+              "fetch": {
+                "source": "openapi",
+                "openapiRef": "list",
+                "query": {
+                  "per_page": "100"
+                }
+              }
+            },
+            {
+              "map": {
+                "useFieldMappings": true,
+                "inputPath": "$",
+                "inline": {
+                  "issueNumber": "{{parameters.issueNumber}}"
+                }
+              }
+            },
+            {
+              "output": {
+                "mode": "records"
+              }
+            }
+          ]
+        },
+        "create": {
+          "enabled": true,
+          "description": "Create a comment on an issue",
+          "steps": [
+            {
+              "fetch": {
+                "source": "http",
+                "method": "POST",
+                "path": "/repos/{{GITHUB_OWNER}}/{{GITHUB_REPO}}/issues/{{parameters.issueNumber}}/comments",
+                "headers": {
+                  "Accept": "application/vnd.github+json",
+                  "X-GitHub-Api-Version": "2022-11-28",
+                  "Content-Type": "application/json"
+                },
+                "bodyTemplate": {
+                  "body": "{{parameters.body}}"
+                }
+              }
+            },
+            {
+              "map": {
+                "useFieldMappings": true,
+                "inputPath": "$",
+                "inline": {
+                  "issueNumber": "{{parameters.issueNumber}}"
+                }
+              }
+            },
+            {
+              "output": {
+                "mode": "records"
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  "capabilities": [
+    {
+      "key": "list",
+      "description": "List comments on an issue",
+      "riskLevel": "low",
+      "approvalRequired": false
+    },
+    {
+      "key": "create",
+      "description": "Create a comment on an issue",
+      "riskLevel": "medium",
+      "approvalRequired": false
+    }
+  ]
+}