@aifabrix/builder 2.49.2 → 2.51.0

package/lib/validation/validate-external-file.js

@@ -0,0 +1,160 @@
+/**
+ * Single external system/datasource file validation.
+ *
+ * @fileoverview Extracted from validate.js (max-lines split)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+const { loadExternalSystemSchema, loadExternalDataSourceSchema } = require('../utils/schema-loader');
+const { formatValidationErrors } = require('../utils/error-formatter');
+const { validateFieldReferences } = require('../datasource/field-reference-validator');
+const { validateAbac } = require('../datasource/abac-validator');
+const {
+  validateOAuth2GrantTypeAndAuthorizationUrl,
+  validateConfigurationNoStandardAuthVariables
+} = require('./external-system-auth-rules');
+
+/**
+ * Parses external system/datasource file content (JSON or YAML).
+ * @param {string} filePath - File path (.json, .yaml, or .yml)
+ * @returns {Object} Parse result with parsed object or error
+ */
+function parseJsonFileContent(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const isYaml = /\.(yaml|yml)$/i.test(filePath);
+  try {
+    const parsed = isYaml ? yaml.load(content) : JSON.parse(content);
+    return { parsed: parsed || {}, error: null };
+  } catch (error) {
+    return {
+      parsed: null,
+      error: {
+        valid: false,
+        errors: [isYaml ? `Invalid YAML syntax: ${error.message}` : `Invalid JSON syntax: ${error.message}`],
+        warnings: []
+      }
+    };
+  }
+}
+
+/**
+ * @param {string} normalizedType
+ * @returns {Function}
+ */
+function getValidatorForType(normalizedType) {
+  if (normalizedType === 'system') {
+    return loadExternalSystemSchema();
+  }
+  if (normalizedType === 'datasource') {
+    return loadExternalDataSourceSchema();
+  }
+  throw new Error(`Unknown file type: ${normalizedType}`);
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} errors
+ */
+function validateRoleReferences(parsed, errors) {
+  if (!parsed.permissions || !Array.isArray(parsed.permissions)) {
+    return;
+  }
+
+  const roles = parsed.roles || [];
+  const roleValues = new Set(roles.map((r) => r.value));
+
+  parsed.permissions.forEach((permission, index) => {
+    if (permission.roles && Array.isArray(permission.roles)) {
+      permission.roles.forEach((roleValue) => {
+        if (!roleValues.has(roleValue)) {
+          errors.push(
+            `Permission "${permission.name}" (index ${index}) references role "${roleValue}" which does not exist in roles array`
+          );
+        }
+      });
+    }
+  });
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} errors
+ */
+function validateSystemFileExtras(parsed, errors) {
+  validateRoleReferences(parsed, errors);
+  validateOAuth2GrantTypeAndAuthorizationUrl(parsed, errors);
+  validateConfigurationNoStandardAuthVariables(parsed, errors);
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string} filePath
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateDatasourceFileExtras(parsed, filePath) {
+  const { collectExternalDatasourceWarnings } = require('./datasource-warnings');
+  const { validateDatasourceFileContractSurface } = require('./openapi-contract-surface-validator');
+  const errors = [...validateFieldReferences(parsed), ...validateAbac(parsed)];
+  const contractSurface = validateDatasourceFileContractSurface(parsed, filePath);
+  errors.push(...contractSurface.errors);
+  const warnings = [
+    ...collectExternalDatasourceWarnings(parsed),
+    ...contractSurface.warnings
+  ];
+  return { errors, warnings };
+}
+
+/**
+ * @async
+ * @param {string} filePath
+ * @param {string} type
+ * @returns {Promise<Object>}
+ */
+async function validateExternalFile(filePath, type) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const parseResult = parseJsonFileContent(filePath);
+  if (parseResult.error) {
+    return parseResult.error;
+  }
+
+  const normalizedType =
+    type === 'external-system' ? 'system' : (type === 'external-datasource' ? 'datasource' : type);
+  const validate = getValidatorForType(normalizedType);
+  const valid = validate(parseResult.parsed);
+
+  const errors = valid ? [] : formatValidationErrors(validate.errors);
+  const warnings = [];
+
+  if (normalizedType === 'system') {
+    validateSystemFileExtras(parseResult.parsed, errors);
+  }
+
+  if (normalizedType === 'datasource') {
+    const dsResult = validateDatasourceFileExtras(parseResult.parsed, filePath);
+    errors.push(...dsResult.errors);
+    warnings.push(...dsResult.warnings);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    file: filePath,
+    type: type
+  };
+}
+
+module.exports = {
+  parseJsonFileContent,
+  getValidatorForType,
+  validateRoleReferences,
+  validateExternalFile
+};

package/lib/validation/validate.js

@@ -10,13 +10,9 @@
  */
 
 const fs = require('fs');
-const yaml = require('js-yaml');
 const validator = require('./validator');
 const { resolveExternalFiles } = require('../utils/schema-resolver');
-const { loadExternalSystemSchema, loadExternalDataSourceSchema, detectSchemaType } = require('../utils/schema-loader');
-const { formatValidationErrors } = require('../utils/error-formatter');
-const { validateFieldReferences } = require('../datasource/field-reference-validator');
-const { validateAbac } = require('../datasource/abac-validator');
+const { detectSchemaType } = require('../utils/schema-loader');
 const { detectAppType } = require('../utils/paths');
 const batch = require('./validate-batch');
 const { logOfflinePathWhenType } = require('../utils/cli-utils');
@@ -24,11 +20,8 @@ const { resolveApplicationConfigPath } = require('../utils/app-config-resolver')
 const { displayValidationResults, displayBatchValidationResults } = require('./validate-display');
 const { generateControllerManifest } = require('../generator/external-controller-manifest');
 const { validateControllerManifest } = require('./external-manifest-validator');
-const {
-  validateOAuth2GrantTypeAndAuthorizationUrl,
-  validateConfigurationNoStandardAuthVariables
-} = require('./external-system-auth-rules');
 const { runExternalValidateWithOptionalCertSync } = require('./validate-external-cert-sync');
+const { validateExternalFile } = require('./validate-external-file');
 
 /**
  * Validates a file path (detects type and validates)
@@ -106,112 +99,7 @@ function aggregateValidationResults(appValidation, externalValidations, rbacVali
 }
 
 /**
- * Parses external system/datasource file content (JSON or YAML).
- * @function parseJsonFileContent
- * @param {string} filePath - File path (.json, .yaml, or .yml)
- * @returns {Object} Parse result with parsed object or error
- */
-function parseJsonFileContent(filePath) {
-  const content = fs.readFileSync(filePath, 'utf8');
-  const isYaml = /\.(yaml|yml)$/i.test(filePath);
-  try {
-    const parsed = isYaml ? yaml.load(content) : JSON.parse(content);
-    return { parsed: parsed || {}, error: null };
-  } catch (error) {
-    return {
-      parsed: null,
-      error: {
-        valid: false,
-        errors: [isYaml ? `Invalid YAML syntax: ${error.message}` : `Invalid JSON syntax: ${error.message}`],
-        warnings: []
-      }
-    };
-  }
-}
-
-/**
- * Gets validator function for file type
- * @function getValidatorForType
- * @param {string} normalizedType - Normalized file type
- * @returns {Function} Validator function
- * @throws {Error} If type is unknown
- */
-function getValidatorForType(normalizedType) {
-  if (normalizedType === 'system') {
-    return loadExternalSystemSchema();
-  }
-  if (normalizedType === 'datasource') {
-    return loadExternalDataSourceSchema();
-  }
-  throw new Error(`Unknown file type: ${normalizedType}`);
-}
-
-/**
- * Validates role references in permissions
- * @function validateRoleReferences
- * @param {Object} parsed - Parsed JSON object
- * @param {string[]} errors - Errors array to append to
- */
-function validateRoleReferences(parsed, errors) {
-  if (!parsed.permissions || !Array.isArray(parsed.permissions)) {
-    return;
-  }
-
-  const roles = parsed.roles || [];
-  const roleValues = new Set(roles.map(r => r.value));
-
-  parsed.permissions.forEach((permission, index) => {
-    if (permission.roles && Array.isArray(permission.roles)) {
-      permission.roles.forEach(roleValue => {
-        if (!roleValues.has(roleValue)) {
-          errors.push(`Permission "${permission.name}" (index ${index}) references role "${roleValue}" which does not exist in roles array`);
-        }
-      });
-    }
-  });
-}
-
-/** @async */
-async function validateExternalFile(filePath, type) {
-  if (!fs.existsSync(filePath)) {
-    throw new Error(`File not found: ${filePath}`);
-  }
-
-  const parseResult = parseJsonFileContent(filePath);
-  if (parseResult.error) {
-    return parseResult.error;
-  }
-
-  const normalizedType = type === 'external-system' ? 'system' : (type === 'external-datasource' ? 'datasource' : type);
-  const validate = getValidatorForType(normalizedType);
-  const valid = validate(parseResult.parsed);
-
-  const errors = valid ? [] : formatValidationErrors(validate.errors);
-  const warnings = [];
-
-  if (normalizedType === 'system') {
-    validateRoleReferences(parseResult.parsed, errors);
-    validateOAuth2GrantTypeAndAuthorizationUrl(parseResult.parsed, errors);
-    validateConfigurationNoStandardAuthVariables(parseResult.parsed, errors);
-  }
-
-  if (normalizedType === 'datasource') {
-    const { collectExternalDatasourceWarnings } = require('./datasource-warnings');
-    errors.push(...validateFieldReferences(parseResult.parsed), ...validateAbac(parseResult.parsed));
-    warnings.push(...collectExternalDatasourceWarnings(parseResult.parsed));
-  }
-
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings,
-    file: filePath,
-    type: type
-  };
-}
-
-/**
- * Validates application or external integration file
+ * Validates a file path (detects type and validates)
  * Detects if input is app name or file path and validates accordingly
  *
  * @async
@@ -371,8 +259,9 @@ async function validateComponentsStep(appName, options = {}) {
  */
 async function validateManifestStep(appName, options = {}) {
   try {
+    const appPath = options.appPath || (await detectAppType(appName, options)).appPath;
     const manifest = await generateControllerManifest(appName, options);
-    const manifestValidation = await validateControllerManifest(manifest);
+    const manifestValidation = await validateControllerManifest(manifest, { appPath });
     return {
       valid: manifestValidation.valid,
       errors: manifestValidation.errors || [],
@@ -434,7 +323,7 @@ async function validateExternalSystemComplete(appName, options = {}) {
   }
 
   // Step 3 & 4: Generate and Validate Full Manifest (only if Step 2 passes)
-  steps.manifest = await validateManifestStep(appName, externalOptions);
+  steps.manifest = await validateManifestStep(appName, { ...externalOptions, appPath });
 
   // Aggregate Results
   const allErrors = [...steps.application.errors, ...steps.components.errors, ...steps.manifest.errors];

package/lib/validation/validator.js

@@ -223,10 +223,11 @@ async function validateRbac(appName, options = {}) {
     throw new Error(`Invalid syntax in ${basename}: ${error.message}`);
   }
 
-  const errors = [
-    ...validateRoles(rbac.roles),
-    ...validatePermissions(rbac.permissions)
-  ];
+  const [roleErrors, permissionErrors] = await Promise.all([
+    Promise.resolve(validateRoles(rbac.roles)),
+    Promise.resolve(validatePermissions(rbac.permissions))
+  ]);
+  const errors = [...roleErrors, ...permissionErrors];
 
   return {
     valid: errors.length === 0,
@@ -275,7 +276,7 @@ async function validateEnvTemplate(appName, options = {}) {
       if (!trimmed.includes('=')) {
         errors.push(`Line ${index + 1}: Invalid environment variable format (missing =)`);
       } else {
-        const [key, _value] = trimmed.split('=', 2);
+        const [key] = trimmed.split('=', 2);
         // Trim key to handle whitespace issues
         // Empty values are allowed (_value can be empty string or undefined)
         const trimmedKey = key ? key.trim() : '';

package/package.json

@@ -1,46 +1,55 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.49.2",
-  "description": "AI Fabrix Local Fabric & Deployment SDK",
+  "version": "2.51.0",
+  "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {
     "aifabrix": "bin/aifabrix.js",
     "af": "bin/aifabrix.js"
   },
   "scripts": {
-    "all": "npm run precommit && npm run test:manual && npm run test:integration:fixtures && npm run test:hubspot-wizard",
-    "test": "node tests/scripts/test-wrapper.js",
-    "test:ci": "bash tests/scripts/ci-simulate.sh",
-    "test:same-as-github": "npm run build:ci",
-    "test:coverage": "cross-env RUN_COVERAGE=1 node tests/scripts/test-wrapper.js",
-    "test:coverage:nyc": "nyc --reporter=text --reporter=lcov --reporter=html jest --config jest.config.coverage.js --runInBand",
-    "test:watch": "jest --watch",
-    "test:integration": "jest --config jest.config.integration.js --runInBand",
-    "test:integration:fixtures": "jest --config jest.config.integration.fixtures.js --runInBand",
-    "test:integration:python": "cross-env TEST_LANGUAGE=python jest --config jest.config.integration.js --runInBand",
-    "test:integration:typescript": "cross-env TEST_LANGUAGE=typescript jest --config jest.config.integration.js --runInBand",
-    "test:hubspot-wizard": "node integration/hubspot-test/test.js",
-    "test:hubspot-wizard:negative": "node integration/hubspot-test/test.js --type negative",
-    "test:hubspot-wizard:positive": "node integration/hubspot-test/test.js --type positive",
-    "test:hubspot-dataplane-down": "node integration/hubspot-test/test-dataplane-down.js",
-    "test:manual": "jest --config jest.config.manual.js --runInBand",
+    "help": "node scripts/pnpm/help.mjs",
+    "dev-install": "node scripts/pnpm/dev-install.mjs",
+    "dev": "node bin/builder-api-spike.js",
+    "dev-reload": "node scripts/pnpm/dev-reload.mjs",
+    "dev-build": "node scripts/pnpm/af.mjs dev-build",
+    "dev-promote": "node scripts/pnpm/af.mjs dev-promote",
+    "af": "node scripts/pnpm/af.mjs",
+    "check-quiet": "node scripts/pnpm/check-quiet.mjs",
+    "check": "npm run lint && npm run test",
     "lint": "eslint . --ext .js",
     "lint:fix": "eslint . --ext .js --fix",
-    "lint:ci": "eslint . --ext .js --format json --output-file eslint-report.json",
-    "dev": "node bin/aifabrix.js",
+    "test": "node tests/scripts/test-wrapper.js",
     "build": "npm run lint && npm run test",
     "build:ci": "npm run lint && npm run check:schema-sync && npm run check:flags && npm run test:ci",
-    "pack": "npm run build && npm pack",
-    "validate": "npm run build",
-    "prepublishOnly": "npm run validate",
-    "precommit": "npm run lint:fix && npm run test",
+    "test:ci": "bash tests/scripts/ci-simulate.sh",
     "install:local": "node scripts/install-local.js && which aifabrix && which af",
     "uninstall:local": "node scripts/install-local.js uninstall && which aifabrix && which af",
+    "sync-json": "node scripts/sync-builder-api-template.js",
+    "builder-api:build": "tsc -p packages/builder-api/tsconfig.json",
+    "builder-api:nest": "node bin/builder-api-nest.js",
+    "builder-api:cleanup": "node bin/builder-api-cleanup.js",
+    "check:builder-api-arch": "node scripts/check-builder-api-architecture-grep.js",
+    "check:schema-sync": "node scripts/check-datasource-test-run-schema-sync.js",
+    "check:flags": "jest tests/lib/schema/flag-map-validation-run.test.js --runInBand --config jest.config.default.js",
+    "test:154": "npm run check:builder-api-arch && jest --runInBand tests/lib/programmatic/ tests/packages/builder-api/ tests/lib/commands/up-builder-api.test.js tests/lib/commands/up-common.test.js tests/lib/commands/repair-deploy-script.test.js tests/lib/generator/deploy-script.test.js tests/lib/generator/wizard-generator.test.js tests/lib/scripts/sync-builder-api-template.test.js tests/lib/platform-integrations-manifest.test.js",
+    "test:154-docker-ip": "jest --runInBand tests/scripts/stage_builder_api_for_docker.test.js tests/scripts/docker_image_content_gate.test.js",
+    "stage-builder-api-docker": "node scripts/stage_builder_api_for_docker.js",
+    "docker-image-build-builder-api": "npm run stage-builder-api-docker && docker build -f builder/builder-api/Dockerfile -t builder-api:gate .",
+    "docker-image-gate-builder-api": "npm run docker-image-build-builder-api && node scripts/docker_image_content_gate.js builder-api:gate builder-api",
+    "test:manual": "jest --config jest.config.manual.js --runInBand",
+    "test:integration": "jest --config jest.config.integration.js --runInBand",
+    "test:integration:fixtures": "jest --config jest.config.integration.fixtures.js --runInBand",
+    "test:hubspot-wizard": "node integration/hubspot-test/test.js",
+    "test:hubspot-dataplane-down": "node integration/hubspot-test/test-dataplane-down.js",
+    "test:coverage": "cross-env RUN_COVERAGE=1 node tests/scripts/test-wrapper.js",
+    "test:watch": "jest --watch",
+    "diagnose:cli": "node scripts/diagnose-cli.js",
     "install:global": "npm install -g . --force && which aifabrix && which af && aifabrix --version",
     "uninstall:global": "npm uninstall -g @aifabrix/builder",
-    "diagnose:cli": "node scripts/diagnose-cli.js",
-    "check:schema-sync": "node scripts/check-datasource-test-run-schema-sync.js",
-    "check:flags": "jest tests/lib/schema/flag-map-validation-run.test.js --runInBand --config jest.config.default.js"
+    "pack": "npm run build && npm pack",
+    "validate": "npm run build",
+    "prepublishOnly": "npm run validate"
   },
   "keywords": [
     "aifabrix",
@@ -76,34 +85,64 @@
     "cache": true,
     "temp-dir": ".nyc_output"
   },
+  "overrides": {
+    "@babel/core": "^7.29.7",
+    "@babel/plugin-transform-modules-systemjs": "^7.29.7",
+    "fast-uri": "^4.1.0",
+    "flatted": "^3.4.2",
+    "follow-redirects": "^1.16.0",
+    "form-data": "^4.0.6",
+    "lodash": "^4.18.1",
+    "minimatch": "^10.2.5",
+    "picomatch": "^4.0.5",
+    "qs": "^6.15.3"
+  },
   "pnpm": {
     "overrides": {
-      "@bcoe/v8-coverage": "^1.0.2"
+      "@bcoe/v8-coverage": "^1.0.2",
+      "@babel/core": "^7.29.7",
+      "@babel/plugin-transform-modules-systemjs": "^7.29.7",
+      "fast-uri": "^4.1.0",
+      "flatted": "^3.4.2",
+      "follow-redirects": "^1.16.0",
+      "form-data": "^4.0.6",
+      "lodash": "^4.18.1",
+      "minimatch": "^10.2.5",
+      "picomatch": "^4.0.5",
+      "qs": "^6.15.3"
     }
   },
   "dependencies": {
-    "ajv": "^8.12.0",
+    "@aifabrix/miso-client": "^4.19.0",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "axios": "^1.6.0",
+    "axios": "^1.18.1",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
-    "handlebars": "^4.7.8",
+    "handlebars": "^4.7.9",
     "inquirer": "^8.2.5",
     "inquirer-autocomplete-prompt": "^2.0.0",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.3.0",
     "ora": "^5.4.1",
-    "yaml": "^2.4.0"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@babel/plugin-syntax-optional-chaining": "^7.8.3",
-    "@babel/preset-env": "^7.29.0",
+    "@babel/preset-env": "^7.29.7",
     "@bcoe/v8-coverage": "^1.0.2",
+    "@nestjs/common": "^11.1.28",
+    "@nestjs/core": "^11.1.28",
+    "@nestjs/platform-express": "^11.1.28",
     "@types/node": "^20.10.0",
     "cross-env": "^10.1.0",
     "eslint": "^8.55.0",
-    "jest": "^30.2.0",
-    "markdownlint-cli": "^0.47.0",
-    "nyc": "^17.1.0"
+    "jest": "^30.4.2",
+    "markdownlint-cli": "^0.49.0",
+    "nyc": "^18.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.2"
   },
   "repository": {
     "type": "git",

package/packages/builder-api/README.md

@@ -0,0 +1,120 @@
+# @aifabrix/builder-api (154.0)
+
+HTTP orchestration layer for external-system workspace lifecycle. V1 uses the shared
+`lib/programmatic/` adapter over existing Builder CLI libraries (no duplicate facades).
+
+## Run with Builder CLI (recommended)
+
+From the **aifabrix-builder** repository root:
+
+```bash
+# From aifabrix-builder repo root
+aifabrix auth status
+aifabrix up-platform              # full stack (includes builder-api)
+# or incremental when miso + dataplane already run:
+aifabrix up-builder-api
+aifabrix resolve builder-api      # refresh .env from env.template
+aifabrix run builder-api --reload
+```
+
+Hot reload (bind-mount repo root, same pattern as dataplane / miso-controller):
+
+```bash
+pnpm run dev-reload
+# or: aifabrix run builder-api --reload
+```
+
+Logs, stop, and lifecycle match other Builder-managed apps:
+
+```bash
+aifabrix logs builder-api
+aifabrix down-app builder-api
+```
+
+Health (adjust port for your `developer-id`): `GET http://localhost:3105/api/v1/builder/health` (dev 1 → `3005 + 100`).
+
+ReDoc (same as dataplane / miso-controller): `GET http://localhost:3105/api/docs`  
+OpenAPI JSON: `GET /api/v1/builder/api-docs/openapi.json`
+
+Platform integration SSOT lives under `integration/` in the builder repo. Publish Enterprise MCP anchor and repository provider integrations before workspace flows:
+
+```bash
+aifabrix upload enterprise-integration-lifecycle --probe
+aifabrix upload <repository-provider-systemKey> --probe
+pnpm run dev-reload   # builder-api container
+```
+
+See `integration/README.md` in the builder repo.
+
+## Run on host (development / tests only)
+
+For Jest e2e and quick iteration without Docker, resolve from `builder/builder-api/env.template` (uses `url://` tokens like miso-controller/dataplane) or set localhost URLs manually:
+
+```bash
+aifabrix resolve builder-api   # preferred — expands url://miso-controller-internal, url://dataplane-internal, url://keycloak-*
+
+# or manual host overrides:
+export WORKSPACE_ROOT=/tmp/builder-workspaces
+export MISO_CLIENTID=miso-controller-dev-builder-api
+export MISO_CLIENTSECRET=<from aifabrix app register builder-api>
+export MISO_CONTROLLER_URL=http://localhost:3100/miso
+export DATAPLANE_URL=http://localhost:3101/data
+export DEFAULT_ENVIRONMENT=dev
+
+pnpm run dev
+# or Nest bootstrap: npm run builder-api:nest
+```
+
+## Workspace cleanup
+
+Scheduled purge of stale draft workspaces (env `WORKSPACE_DRAFT_TTL_DAYS`, `WORKSPACE_INACTIVE_MAX_DAYS`):
+
+```bash
+npm run builder-api:cleanup
+npm run builder-api:cleanup -- --dry-run
+```
+
+In Docker, schedule via platform cron or sidecar invoking `node bin/builder-api-cleanup.js`.
+
+## Package layout
+
+```text
+builder/builder-api/                    # SSOT (edit here; npm run sync-json → template)
+templates/applications/builder-api/   # Shipped template copy
+packages/builder-api/
+  src/main.ts                           # Nest bootstrap → nest-http-bridge
+  src/app.module.ts
+  MANUAL-CHECKLIST.md
+lib/programmatic/                       # Shared HTTP handlers + Enterprise MCP client
+```
+
+Compile TypeScript: `npm run builder-api:build` (output in `packages/builder-api/dist/`).
+
+## 154.1 routes (Enterprise MCP client)
+
+Provider-neutral HTTP orchestration — remote repository/template via Dataplane Enterprise MCP:
+
+- `POST /systems/{systemKey}/template/materialize`
+- `GET /systems/{systemKey}/workspace/status`
+- `POST /systems/{systemKey}/workspace/diff` / `workspace/reset`
+- `POST /systems/{systemKey}/repository/sync` / `create-review` / `dispatch-pipeline`
+- `GET /systems/{systemKey}/repository/status`
+
+Governance gates use existing Dataplane lifecycle / verify-trust APIs (no can-execute proxy in builder-api V1).
+
+Architecture CI: `npm run check:builder-api-arch`
+
+All other routes require `Authorization: Bearer <token from aifabrix login>`.
+
+See `MANUAL-CHECKLIST.md` for manual verification, `docs/external-systems.md` and `docs/wizard.md` for integration workflow context.
+
+## Nest migration
+
+This package currently reuses the Node HTTP server in `lib/programmatic/builder-api-server.js`.
+NestJS scaffold wraps the same `route-handlers` module via `nest-http-bridge.js`.
+
+## Not builder-server
+
+This service is **not** the dev onboarding `builder-server`. It is stateless multi-user workspace
+orchestration with Dataplane as governance authority. Do **not** use ad hoc `docker compose` under
+`packages/builder-api/` — use `aifabrix run builder-api` for the full application lifecycle.

package/packages/builder-api/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@aifabrix/builder-api",
+  "version": "0.1.0",
+  "description": "AI Fabrix Builder API — HTTP orchestration for external system lifecycle (plan 154.0)",
+  "private": true,
+  "main": "../../lib/programmatic/builder-api-server.js",
+  "bin": {
+    "builder-api": "../../bin/builder-api-spike.js",
+    "builder-api-nest": "../../bin/builder-api-nest.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node ../../bin/builder-api-spike.js",
+    "start:nest": "node ../../bin/builder-api-nest.js",
+    "cleanup": "node ../../bin/builder-api-cleanup.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@aifabrix/miso-client": "4.19.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "@nestjs/platform-express": "^10.0.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.0"
+  }
+}

package/packages/builder-api/src/app.module.ts

@@ -0,0 +1,7 @@
+import { Module } from '@nestjs/common';
+
+/**
+ * Root Nest module — HTTP routing is delegated to lib/programmatic via nest-http-bridge.
+ */
+@Module({})
+export class AppModule {}

package/packages/builder-api/src/auth/auth.module.ts

@@ -0,0 +1,5 @@
+import { Module } from '@nestjs/common';
+
+/** Placeholder for future BearerAuthGuard wiring (V1 auth runs in lib/programmatic). */
+@Module({})
+export class AuthModule {}