@aifabrix/builder 2.50.0 → 2.51.0

package/lib/commands/validate-json.js

@@ -0,0 +1,230 @@
+/**
+ * Offline validate then write *-deploy.json (same quality as validate + same write as json).
+ *
+ * @fileoverview aifabrix validate-json command
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const validate = require('../validation/validate');
+const generator = require('../generator');
+const { listIntegrationAppNames, listBuilderAppNames } = require('../utils/paths');
+const {
+  formatSuccessLine,
+  formatBlockingError,
+  formatWarningLine
+} = require('../utils/cli-test-layout-chalk');
+
+/**
+ * @param {string} appKey
+ * @returns {boolean}
+ */
+function looksLikeExistingFilePath(appKey) {
+  try {
+    return Boolean(appKey && fs.existsSync(appKey) && fs.statSync(appKey).isFile());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {object} opts
+ * @returns {string[]}
+ */
+function collectBatchAppNames(opts) {
+  const names = [];
+  if (opts.integration === true) {
+    names.push(...listIntegrationAppNames());
+  }
+  if (opts.builder === true) {
+    names.push(...listBuilderAppNames());
+  }
+  return [...new Set(names)];
+}
+
+/**
+ * @param {string} appKey
+ * @param {object} result
+ * @param {string} outFormat
+ */
+function emitManifestLine(appKey, result, outFormat) {
+  if (outFormat === 'json' || !result?.appPath) {
+    return;
+  }
+  try {
+    const { emitManifestMetadataLineIfTTY } = require('../utils/manifest-source-emit');
+    emitManifestMetadataLineIfTTY(logger, {
+      appKey,
+      appPath: result.appPath,
+      envOnly: false,
+      json: false
+    });
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * Validate one app/systemKey; write deploy JSON only when local validate succeeds.
+ * @param {string} appKey
+ * @param {object} [options]
+ * @returns {Promise<{ appKey: string, valid: boolean, validation: object, deploy?: object|null, error?: string }>}
+ */
+async function validateThenWriteDeploy(appKey, options = {}) {
+  let validation;
+  try {
+    validation = await validate.validateAppOrFile(appKey, { ...options, certSync: false });
+  } catch (err) {
+    return {
+      appKey,
+      valid: false,
+      validation: { valid: false, errors: [err.message || String(err)] },
+      deploy: null,
+      error: err.message || String(err)
+    };
+  }
+  if (!validation.valid) {
+    return { appKey, valid: false, validation, deploy: null };
+  }
+  const deploy = await generator.generateDeployJsonWithValidation(appKey, options);
+  const ok = deploy.success === true;
+  return {
+    appKey,
+    valid: ok,
+    validation,
+    deploy,
+    error: ok ? undefined : (deploy.validation?.errors || []).join('; ') || 'deploy JSON validation failed'
+  };
+}
+
+/**
+ * @param {object} item
+ * @param {string} outFormat
+ */
+function displayOneHumanResult(item, outFormat) {
+  emitManifestLine(item.appKey, item.validation, outFormat);
+  if (outFormat === 'json') {
+    return;
+  }
+  validate.displayValidationResults(item.validation);
+  if (!item.validation.valid) {
+    logger.log(formatBlockingError(`Skipped deploy JSON for ${item.appKey} (validation failed)`));
+    return;
+  }
+  if (item.deploy?.success && item.deploy.path) {
+    logger.log(formatSuccessLine(`Generated deployment JSON: ${item.deploy.path}`));
+    const warnings = item.deploy.validation?.warnings || [];
+    if (warnings.length > 0) {
+      warnings.forEach((w) => logger.log(formatWarningLine(w)));
+    }
+    return;
+  }
+  logger.log(formatBlockingError(`Deploy JSON write failed for ${item.appKey}`));
+  (item.deploy?.validation?.errors || []).forEach((e) => logger.log(`   • ${e}`));
+}
+
+/**
+ * @param {Array<object>} items
+ * @param {string} outFormat
+ */
+function displayBatchSummary(items, outFormat) {
+  if (outFormat === 'json') {
+    logger.log(JSON.stringify({
+      batch: true,
+      valid: items.every((i) => i.valid),
+      results: items.map((i) => ({
+        appKey: i.appKey,
+        valid: i.valid,
+        path: i.deploy?.path || null,
+        error: i.error || null
+      }))
+    }, null, 2));
+    return;
+  }
+  const passed = items.filter((i) => i.valid);
+  const failed = items.filter((i) => !i.valid);
+  logger.log('');
+  logger.log(chalk.bold('validate-json summary'));
+  logger.log(`  Passed: ${passed.length}`);
+  logger.log(`  Failed: ${failed.length}`);
+  failed.forEach((i) => {
+    logger.log(formatBlockingError(`${i.appKey}${i.error ? `: ${i.error}` : ''}`));
+  });
+}
+
+/**
+ * @param {object} opts
+ * @param {string} outFormat
+ * @returns {Promise<{ exitCode: number }>}
+ */
+async function runValidateJsonBatch(opts, outFormat) {
+  const names = collectBatchAppNames(opts);
+  const items = [];
+  for (const name of names) {
+    const item = await validateThenWriteDeploy(name, opts);
+    displayOneHumanResult(item, outFormat);
+    items.push(item);
+  }
+  displayBatchSummary(items, outFormat);
+  return { exitCode: items.every((i) => i.valid) ? 0 : 1 };
+}
+
+/**
+ * @param {string} appKey
+ * @param {object} opts
+ * @param {string} outFormat
+ * @returns {Promise<{ exitCode: number }>}
+ */
+async function runValidateJsonSingle(appKey, opts, outFormat) {
+  if (looksLikeExistingFilePath(appKey)) {
+    logger.log(
+      chalk.red(
+        'validate-json requires an appKey or systemKey (not a file path). Use aifabrix validate <file> for files.'
+      )
+    );
+    return { exitCode: 1 };
+  }
+  const item = await validateThenWriteDeploy(appKey, opts);
+  if (outFormat === 'json') {
+    logger.log(JSON.stringify({
+      appKey: item.appKey,
+      valid: item.valid,
+      path: item.deploy?.path || null,
+      validation: item.validation,
+      error: item.error || null
+    }, null, 2));
+  } else {
+    displayOneHumanResult(item, outFormat);
+  }
+  return { exitCode: item.valid ? 0 : 1 };
+}
+
+/**
+ * @param {string|undefined} appKey
+ * @param {object} options - Commander options or opts()
+ * @returns {Promise<{ exitCode: number }>}
+ */
+async function runValidateJsonCommand(appKey, options) {
+  const opts = options.opts ? options.opts() : options;
+  const outFormat = (opts.format || 'default').toLowerCase();
+  if (opts.integration === true || opts.builder === true) {
+    return runValidateJsonBatch(opts, outFormat);
+  }
+  if (!appKey || typeof appKey !== 'string') {
+    logger.log(chalk.red('App or system key is required, or use --integration / --builder'));
+    return { exitCode: 1 };
+  }
+  return runValidateJsonSingle(appKey, opts, outFormat);
+}
+
+module.exports = {
+  runValidateJsonCommand,
+  validateThenWriteDeploy,
+  collectBatchAppNames,
+  looksLikeExistingFilePath
+};

package/lib/commands/verify-operations-step-plan.js

@@ -8,58 +8,96 @@ const { validateExternalSystemComplete } = require('../validation/validate');
 const { testExternalSystem, testExternalSystemIntegration } = require('../external-system/test');
 const { runTestE2EForExternalSystem } = require('./test-e2e-external');
 
+/**
+ * @param {string} systemKey
+ * @returns {Array}
+ */
+function buildBeforeSyncSteps(systemKey) {
+  return [
+    {
+      key: 'validation',
+      run: () => validateExternalSystemComplete(systemKey, { type: 'external' }),
+      ok: (result) => result.valid === true
+    },
+    {
+      key: 'unit',
+      run: () => testExternalSystem(systemKey, { verbose: false }),
+      ok: (result) => result.valid === true
+    }
+  ];
+}
+
 /**
  * @param {string} systemKey
  * @param {Object} options
- * @returns {{ beforeSync: Array, afterSync: Array, e2e: Object }}
+ * @returns {Array}
  */
-function buildOperationsVerifyStepPlan(systemKey, options) {
-  return {
-    beforeSync: [
-      {
-        key: 'validation',
-        run: () => validateExternalSystemComplete(systemKey, { type: 'external' }),
-        ok: (result) => result.valid === true
-      },
-      {
-        key: 'unit',
-        run: () => testExternalSystem(systemKey, { verbose: false }),
-        ok: (result) => result.valid === true
-      }
-    ],
-    afterSync: [
-      {
-        key: 'integration',
-        run: () =>
-          testExternalSystemIntegration(systemKey, {
-            environment: options.env,
-            noPublish: true,
-            verbose: false,
-            debug: options.debug === true
-          }),
-        ok: (result) => result.success === true
-      }
-    ],
-    e2e: {
-      key: 'e2e',
-      run: (progress) =>
-        runTestE2EForExternalSystem(systemKey, {
-          env: options.env,
+function buildAfterSyncSteps(systemKey, options) {
+  return [
+    {
+      key: 'integration',
+      run: () =>
+        testExternalSystemIntegration(systemKey, {
+          environment: options.env || options.environment,
           noPublish: true,
           verbose: false,
           debug: options.debug === true,
-          async: options.async !== false,
+          // Token-forward (builder-api certify): same auth as E2E step — do not
+          // fall back to getDeploymentAuth inside the container.
           authConfig: options.authConfig,
           dataplaneUrl: options.dataplaneUrl,
-          silentResolve: options.silentResolve === true,
-          quietPollUi: true,
-          onDatasourceProgress: progress?.setLabel
-            ? ({ key, index, total }) =>
-              progress.setLabel(`Running E2E: ${key} (${index + 1}/${total})`)
-            : undefined
+          silentResolve: options.silentResolve === true
         }),
       ok: (result) => result.success === true
     }
+  ];
+}
+
+/**
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Object}
+ */
+function buildE2eStep(systemKey, options) {
+  if (options.skipE2e === true || options.minimal === true) {
+    return {
+      key: 'e2e',
+      run: async() => ({ success: true, skipped: true, reason: 'minimal' }),
+      ok: () => true
+    };
+  }
+  return {
+    key: 'e2e',
+    run: (progress) =>
+      runTestE2EForExternalSystem(systemKey, {
+        env: options.env,
+        noPublish: true,
+        verbose: false,
+        debug: options.debug === true,
+        async: options.async !== false,
+        authConfig: options.authConfig,
+        dataplaneUrl: options.dataplaneUrl,
+        silentResolve: options.silentResolve === true,
+        quietPollUi: true,
+        onDatasourceProgress: progress?.setLabel
+          ? ({ key, index, total }) =>
+            progress.setLabel(`Running E2E: ${key} (${index + 1}/${total})`)
+          : undefined
+      }),
+    ok: (result) => result.success === true
+  };
+}
+
+/**
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {{ beforeSync: Array, afterSync: Array, e2e: Object }}
+ */
+function buildOperationsVerifyStepPlan(systemKey, options) {
+  return {
+    beforeSync: buildBeforeSyncSteps(systemKey),
+    afterSync: buildAfterSyncSteps(systemKey, options),
+    e2e: buildE2eStep(systemKey, options)
   };
 }
 

package/lib/core/audit-logger.js

@@ -238,7 +238,7 @@ async function logApiCall({ url, options, statusCode, duration, success, errorIn
   const path = extractPathFromUrl(url);
 
   // Extract controller URL from full URL
-  let controllerUrl = 'unknown';
+  let controllerUrl;
   try {
     const urlObj = new URL(url);
     controllerUrl = `${urlObj.protocol}//${urlObj.host}`;

package/lib/core/secrets-load.js

@@ -133,9 +133,7 @@ function mergeUserWithConfigFile(userSecrets, resolvedConfigPath, keySources) {
   for (const key of Object.keys(configSecrets)) {
     if (!(key in merged) || merged[key] === undefined || merged[key] === null || merged[key] === '') {
       merged[key] = configSecrets[key];
-      if (keySources) {
-        keySources[key] = resolvedConfigPath;
-      }
+      keySources[key] = resolvedConfigPath;
     }
   }
   return merged;

package/lib/datasource/capability/relate-operations.js

@@ -23,7 +23,7 @@ function _asObject(x) {
 function _uniqStrings(list) {
   const out = [];
   const seen = new Set();
-  for (const x of list || []) {
+  for (const x of list) {
     const s = String(x || '').trim();
     if (!s || seen.has(s)) continue;
     seen.add(s);

package/lib/generator/helpers.js

@@ -156,10 +156,10 @@ function validatePortalInput(portalInput, variableName) {
  * @throws {Error} If portalInput structure is invalid
  */
 /**
- * Creates a map of portalInput configurations from variables config
+ * Creates a map of portal overlay metadata from variables config
  * @function createPortalInputMap
  * @param {Object|null} variablesConfig - Configuration from application.yaml
- * @returns {Map} Map of variable names to portalInput configurations
+ * @returns {Map} Map of variable names to { portalInput, category? }
  */
 function createPortalInputMap(variablesConfig) {
   const portalInputMap = new Map();
@@ -168,7 +168,11 @@ function createPortalInputMap(variablesConfig) {
       if (configItem.name && configItem.portalInput) {
         // Validate portalInput before adding to map
         validatePortalInput(configItem.portalInput, configItem.name);
-        portalInputMap.set(configItem.name, configItem.portalInput);
+        const overlay = { portalInput: configItem.portalInput };
+        if (typeof configItem.category === 'string' && configItem.category.trim().length > 0) {
+          overlay.category = configItem.category.trim();
+        }
+        portalInputMap.set(configItem.name, overlay);
       }
     }
   }
@@ -291,9 +295,13 @@ function createConfigItem(key, value, location, required, portalInputMap, appKey
     required
   };
 
-  // Merge portalInput if it exists in application config
+  // Merge portalInput / category if present in application config
   if (portalInputMap.has(key)) {
-    configItem.portalInput = portalInputMap.get(key);
+    const overlay = portalInputMap.get(key);
+    configItem.portalInput = overlay.portalInput;
+    if (typeof overlay.category === 'string' && overlay.category.length > 0) {
+      configItem.category = overlay.category;
+    }
   }
 
   return configItem;

package/lib/generator/split-variables.js

@@ -66,15 +66,21 @@ function extractOptionalSections(deployment) {
 }
 
 /**
- * Portal-only configuration for application.yaml (name + portalInput per entry).
+ * Portal-only configuration for application.yaml (name + optional category + portalInput).
  * @param {Array} configuration - Configuration array from deployment JSON
- * @returns {Array<{ name: string, portalInput: Object }>}
+ * @returns {Array<{ name: string, category?: string, portalInput: Object }>}
  */
 function extractPortalInputConfiguration(configuration) {
   if (!Array.isArray(configuration) || configuration.length === 0) return [];
   return configuration
     .filter(item => item && item.portalInput && typeof item.name === 'string')
-    .map(item => ({ name: item.name, portalInput: item.portalInput }));
+    .map(item => {
+      const entry = { name: item.name, portalInput: item.portalInput };
+      if (typeof item.category === 'string' && item.category.trim().length > 0) {
+        entry.category = item.category.trim();
+      }
+      return entry;
+    });
 }
 
 /**

package/lib/infrastructure/helpers-docker-check.js

@@ -53,6 +53,12 @@ function formatDockerInfrastructureFailure(detail) {
  */
 async function checkDockerAvailability() {
   await ensureDevCertsIfNeededForRemoteDocker();
+  try {
+    const { ensureDevCertFreshIfDue } = require('../commands/dev-refresh');
+    await ensureDevCertFreshIfDue({ quiet: true });
+  } catch {
+    // Best-effort renew for remote Docker TLS; docker check reports real failures
+  }
   try {
     await dockerUtils.ensureDockerAndCompose();
   } catch (error) {

package/lib/infrastructure/helpers.js

@@ -181,7 +181,7 @@ function generatePgAdminConfig(infraDir, postgresPassword) {
  * @returns {string} Escaped string
  */
 function escapePgString(s) {
-  if (s === null || s === undefined || typeof s !== 'string') return '';
+  if (typeof s !== 'string') return '';
   return s.replace(/'/g, '\'\'');
 }
 

package/lib/programmatic/auth-config.js

@@ -10,7 +10,7 @@
 
 /**
  * @param {string} bearerToken
- * @returns {{ type: 'bearer', token: string }}
+ * @returns {{ type: 'bearer', token: string, preserveBearer: true }}
  */
 function buildBearerAuthConfig(bearerToken) {
   if (!bearerToken || typeof bearerToken !== 'string') {
@@ -20,7 +20,8 @@ function buildBearerAuthConfig(bearerToken) {
   if (!token) {
     throw new Error('Bearer token is required');
   }
-  return { type: 'bearer', token };
+  // Token-forward: caller JWT must reach dataplane CIP/pipeline unchanged (no API_KEY swap).
+  return { type: 'bearer', token, preserveBearer: true };
 }
 
 /**

package/lib/programmatic/bearer-auth.js

@@ -20,7 +20,7 @@ function extractBearerToken(req) {
   if (!auth || typeof auth !== 'string') {
     return null;
   }
-  const match = auth.match(/^Bearer\s+(.+)$/i);
+  const match = auth.match(/^Bearer\s+([^\s]+)\s*$/i);
   return match ? match[1].trim() : null;
 }
 

package/lib/programmatic/enterprise-mcp-client.js

@@ -19,6 +19,21 @@ function resolveEnterpriseMcpSystemKey() {
   return (process.env.ENTERPRISE_MCP_SYSTEM_KEY || 'enterprise-integration-lifecycle').trim();
 }
 
+/**
+ * COM-generated Enterprise MCP tools sometimes use OpenAPI operationId forms
+ * (e.g. repository.getrepositorystatus) instead of canonical capability keys
+ * (repository.status). Map canonical → published name when present.
+ *
+ * @type {Record<string, string>}
+ */
+const ENTERPRISE_MCP_TOOL_ALIASES = {
+  'repository.status': 'repository.getrepositorystatus',
+  'repository.sync': 'repository.runrepositorysync',
+  'repository.createReview': 'repository.runrepositorycreatereview',
+  'repository.dispatchPipeline': 'repository.runrepositorydispatchpipeline',
+  'template.materializeWorkspace': 'template.runwizard'
+};
+
 /**
  * @param {string} capabilityKey
  * @returns {{ resourceType: string, toolName: string }}
@@ -29,9 +44,10 @@ function parseCapabilityKey(capabilityKey) {
   if (dotIndex <= 0) {
     throw new Error('capabilityKey must be resourceType.operation form');
   }
+  const toolName = ENTERPRISE_MCP_TOOL_ALIASES[key] || key;
   return {
     resourceType: key.slice(0, dotIndex),
-    toolName: key
+    toolName
   };
 }
 
@@ -42,7 +58,7 @@ function parseCapabilityKey(capabilityKey) {
  * @returns {string}
  */
 function buildMcpExecutePath(systemKey, resourceType, toolName) {
-  return `/api/v1/mcp/${encodeURIComponent(systemKey)}/${encodeURIComponent(resourceType)}/tools/${encodeURIComponent(toolName)}/execute`;
+  return `/api/v1/mcp/servers/${encodeURIComponent(systemKey)}/${encodeURIComponent(resourceType)}/tools/${encodeURIComponent(toolName)}/execute`;
 }
 
 /**

package/lib/programmatic/manifest-section-registry.js

@@ -22,6 +22,15 @@ const SCHEMA_DIR = path.join(__dirname, '..', 'schema');
 let systemSchemaDoc = null;
 /** @type {Object|null} */
 let datasourceSchemaDoc = null;
+const PROTOTYPE_POLLUTION_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+
+/**
+ * @param {string} part
+ * @returns {boolean}
+ */
+function isSafePathPart(part) {
+  return typeof part === 'string' && part.length > 0 && !PROTOTYPE_POLLUTION_KEYS.has(part);
+}
 
 function getSystemSchemaDoc() {
   if (!systemSchemaDoc) {
@@ -90,10 +99,18 @@ function getPathValue(doc, dottedPath) {
  */
 function setPathValue(doc, dottedPath, value) {
   const parts = dottedPath.split('.');
+  for (const part of parts) {
+    if (!isSafePathPart(part)) {
+      const err = new Error(`Unsafe path segment: ${part}`);
+      err.statusCode = 400;
+      throw err;
+    }
+  }
   let current = doc;
   for (let i = 0; i < parts.length - 1; i += 1) {
     const part = parts[i];
-    if (current[part] === null || current[part] === undefined || typeof current[part] !== 'object') {
+    const next = Object.prototype.hasOwnProperty.call(current, part) ? current[part] : undefined;
+    if (next === null || next === undefined || typeof next !== 'object' || Array.isArray(next)) {
       current[part] = {};
     }
     current = current[part];

package/lib/programmatic/openapi-result-schemas.js

@@ -12,18 +12,35 @@ const { frozenObject, schemaRef, stringArraySchema } = require('./openapi-schema
 
 /** @type {Record<string, Object>} */
 const OPENAPI_RESULT_SCHEMAS = {
-  ProblemDetails: frozenObject(
-    {
-      type: { type: 'string', format: 'uri-reference' },
-      title: { type: 'string' },
-      status: { type: 'integer', minimum: 100, maximum: 599 },
-      detail: { type: 'string' },
-      instance: { type: 'string' },
-      correlationId: { type: 'string' },
-      errors: { type: 'array', items: schemaRef('ProblemValidationError') }
-    },
-    ['type', 'title', 'status', 'detail']
+  ProblemDetail: Object.assign(
+    frozenObject(
+      {
+        type: { type: 'string', format: 'uri-reference' },
+        title: { type: 'string' },
+        status: { type: 'integer', minimum: 100, maximum: 599 },
+        detail: { type: 'string' },
+        instance: { type: 'string' },
+        correlationId: { type: 'string' },
+        errors: { type: 'array', items: schemaRef('ProblemValidationError') }
+      },
+      ['type', 'title', 'status', 'detail', 'correlationId', 'instance', 'errors']
+    ),
+    {
+      example: {
+        type: '/Errors/Unauthorized',
+        title: 'Unauthorized',
+        status: 401,
+        detail: 'Missing or invalid Bearer token.',
+        instance: '/api/v1/builder/workspaces/me/systems',
+        correlationId: '00000000-0000-4000-8000-000000000003',
+        errors: []
+      }
+    }
   ),
+  /** Prefer ProblemDetail; allOf alias for published REST lint (OAPI-148). */
+  ProblemDetails: {
+    allOf: [schemaRef('ProblemDetail')]
+  },
   ProblemValidationError: frozenObject(
     {
       field: { type: 'string' },

package/lib/programmatic/openapi-schema-descriptions-core.js

@@ -22,7 +22,7 @@ const CORE_SCHEMA_DESCRIPTIONS = {
   RepositorySyncDirection: {
     _schema: 'Repository sync direction: pull remote into workspace or push workspace to remote.'
   },
-  ProblemDetails: {
+  ProblemDetail: {
     _schema: 'RFC 7807 problem response for builder-api errors (application/problem+json).',
     type: 'Problem type URI or identifier.',
     title: 'Short human-readable error title.',
@@ -32,8 +32,11 @@ const CORE_SCHEMA_DESCRIPTIONS = {
     correlationId: 'Correlation id for log lookup across services.',
     errors: 'Field-level validation errors when status is 400.'
   },
+  ProblemDetails: {
+    _schema: 'Alias of ProblemDetail (allOf) for backward-compatible $refs.'
+  },
   ProblemValidationError: {
-    _schema: 'Single field validation error inside ProblemDetails.errors.',
+    _schema: 'Single field validation error inside ProblemDetail.errors.',
     field: 'JSON pointer or field name that failed validation.',
     message: 'Validation failure message.',
     value: 'Rejected value when safe to echo (may be omitted for secrets).'