@aifabrix/builder 2.37.9 → 2.39.0

package/lib/schema/application-schema.json

@@ -57,8 +57,7 @@
     "key",
     "displayName",
     "description",
-    "type",
-    "deploymentKey"
+    "type"
   ],
   "properties": {
     "key": {
@@ -91,6 +90,11 @@
         "external"
       ]
     },
+    "version": {
+      "type": "string",
+      "description": "Application version (semantic); default 1.0.0 when empty",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?$"
+    },
     "image": {
       "type": "string",
       "description": "Container image reference",
@@ -768,18 +772,6 @@
       },
       "additionalProperties": false
     },
-    "deployment": {
-      "type": "object",
-      "description": "Deployment configuration for pipeline API",
-      "properties": {
-        "controllerUrl": {
-          "type": "string",
-          "description": "Controller API URL for deployment",
-          "pattern": "^https://.*$"
-        }
-      },
-      "additionalProperties": false
-    },
     "system": {
       "type": "object",
       "description": "Optional: Inline external system configuration for atomic deployment. Uses external-system.schema.json structure via $ref. Alternative to externalIntegration.systems file-based approach.",

package/lib/schema/deployment-rules.yaml

@@ -0,0 +1,121 @@
+# Deployment rules – Central mapping for Controller
+#
+# Defines which manifest paths trigger deployment and which can differ per environment.
+# Controller uses this file (or equivalent) for deployment key computation and value merge.
+# Schemas (application, external-system, external-datasource) remain clean; no x-* annotations.
+#
+# Semantics:
+#   triggerPaths:   Change affects deployment key / requires deploy
+#   overridablePaths: Value can differ per environment (preserve on promote)
+# A path may appear in both (e.g. authentication.endpoints triggers deploy and is overridable).
+#
+# Path format: Dot notation. Child paths override parent when both match.
+# Schema keys: application | externalSystem | externalDataSource
+
+application:
+  triggerPaths:
+    - key
+    - displayName
+    - description
+    - type
+    - version
+    - image
+    - registryMode
+    - port
+    - requiresDatabase
+    - databases
+    - requiresRedis
+    - requiresStorage
+    - configuration
+    - configuration.items
+    - configuration.items.required
+    - configuration.items.portalInput
+    - healthCheck
+    - healthCheck.path
+    - healthCheck.probePath
+    - healthCheck.probeRequestType
+    - healthCheck.probeProtocol
+    - frontDoorRouting
+    - authentication
+    - roles
+    - permissions
+    - repository
+    - startupCommand
+    - runtimeVersion
+    - scaling
+    - build
+    - deployment
+    - externalIntegration
+  overridablePaths:
+    - configuration.items.value
+    - authentication.endpoints
+    - deployment.controllerUrl
+    - healthCheck.interval
+    - healthCheck.probeIntervalInSeconds
+
+externalSystem:
+  triggerPaths:
+    - key
+    - displayName
+    - description
+    - type
+    - enabled
+    - environment
+    - authentication
+    - openapi
+    - mcp
+    - dataSources
+    - configuration
+    - configuration.items
+    - tags
+    - roles
+    - permissions
+    - endpoints
+    - endpointsActive
+    - generateMcpContract
+    - generateOpenApiContract
+  overridablePaths:
+    - environment.baseUrl
+    - environment.region
+    - authentication.oauth2
+    - authentication.apikey
+    - authentication.basic
+    - authentication.aad
+    - openapi.specUrl
+    - openapi.documentKey
+    - mcp.serverUrl
+    - mcp.toolPrefix
+    - configuration.items.value
+    - credentialIdOrKey
+
+externalDataSource:
+  triggerPaths:
+    - key
+    - displayName
+    - description
+    - enabled
+    - systemKey
+    - entityType
+    - resourceType
+    - version
+    - metadataSchema
+    - fieldMappings
+    - exposed
+    - validation
+    - quality
+    - indexing
+    - context
+    - documentStorage
+    - portalInput
+    - capabilities
+    - execution
+    - config
+    - openapi
+  overridablePaths:
+    - sync
+    - sync.mode
+    - sync.schedule
+    - sync.batchSize
+    - sync.maxParallelRequests
+    - openapi.baseUrl
+    - openapi.resourcePath

package/lib/schema/external-system.schema.json

@@ -102,22 +102,6 @@
       "type": "boolean",
       "default": true
     },
-    "environment": {
-      "type": "object",
-      "description": "Environment-level configuration values used by dataplane and external data sources.",
-      "properties": {
-        "baseUrl": {
-          "type": "string",
-          "description": "Base API URL or MCP server URL",
-          "pattern": "^(http|https)://.*$"
-        },
-        "region": {
-          "type": "string",
-          "description": "Optional region setting for API routing"
-        }
-      },
-      "additionalProperties": true
-    },
     "authentication": {
       "type": "object",
       "description": "Authentication configuration for external system",

package/lib/utils/app-register-config.js

@@ -112,19 +112,14 @@ function resolveSystemFilePath(appPath, schemaBasePath, systemFileName) {
 }
 
 /**
- * Extracts URL from system JSON
+ * Base URL is no longer read from manifest; Controller resolves from configuration at deploy time.
  * @function extractUrlFromSystemJson
- * @param {Object} systemJson - System JSON object
- * @param {string} systemFileName - System file name
- * @returns {string} Base URL
- * @throws {Error} If URL is missing
+ * @param {Object} _systemJson - System JSON object (unused; kept for call-site compatibility)
+ * @param {string} _systemFileName - System file name (unused)
+ * @returns {undefined} URL is not supplied from manifest
  */
-function extractUrlFromSystemJson(systemJson, systemFileName) {
-  const url = systemJson.environment?.baseUrl;
-  if (!url) {
-    throw new Error(`Missing environment.baseUrl in ${systemFileName}`);
-  }
-  return url;
+function extractUrlFromSystemJson(_systemJson, _systemFileName) {
+  return undefined;
 }
 
 /**
@@ -209,7 +204,10 @@ async function extractExternalIntegrationUrl(appKey, externalIntegration) {
  */
 async function extractExternalAppConfiguration(appKey, variables, appKeyFromFile, displayName, description) {
   const { url, apiKey } = await extractExternalIntegrationUrl(appKey, variables.externalIntegration);
-  const externalIntegration = { url };
+  const externalIntegration = {};
+  if (url !== undefined && url !== null) {
+    externalIntegration.url = url;
+  }
   if (apiKey) {
     externalIntegration.apiKey = apiKey;
   }

package/lib/utils/app-run-containers.js

@@ -156,6 +156,7 @@ module.exports = {
   checkImageExists,
   checkContainerRunning,
   stopAndRemoveContainer,
-  logContainerStatus
+  logContainerStatus,
+  getContainerName
 };
 

package/lib/utils/compose-generator.js

@@ -458,7 +458,8 @@ async function generateDockerCompose(appName, appConfig, options) {
   const language = appConfig.build?.language || appConfig.language || 'typescript';
   const template = loadDockerComposeTemplate(language);
   const port = options.port || appConfig.port || 3000;
-  const imageOverride = options.image || options.imageOverride;
+  const imageOverride = options.image || options.imageOverride ||
+    (options.tag ? `${getImageName(appConfig, appName)}:${options.tag}` : null);
   const { devId, idNum } = await getDeveloperIdAndNumeric();
   const { networkName, containerName } = buildNetworkAndContainerNames(appName, devId, idNum);
   const serviceConfig = buildServiceConfig(appName, appConfig, port, devId, imageOverride);

package/lib/utils/deployment-errors.js

@@ -206,6 +206,16 @@ async function handleDeploymentErrors(error, appName, url, alreadyLogged = false
   // Extract error message
   const errorMessage = extractErrorMessage(error);
 
+  // Deployment failed/cancelled (from deploy.js): show message as-is, do not treat as HTTP error
+  if (errorMessage.startsWith('Deployment failed:') || errorMessage.startsWith('Deployment cancelled:')) {
+    if (!alreadyLogged) {
+      await logDeploymentFailure(appName, url, error);
+    }
+    const err = new Error(errorMessage);
+    err.formatted = (error.formatted || errorMessage).trim();
+    throw err;
+  }
+
   // For validation errors (like URL validation), just re-throw them directly
   if (isValidationError(errorMessage)) {
     throwValidationError(error, errorMessage);

package/lib/utils/environment-checker.js

@@ -13,6 +13,8 @@ const fs = require('fs');
 const path = require('path');
 const dockerUtils = require('./docker');
 const { getActualSecretsPath } = require('./secrets-path');
+const config = require('../core/config');
+const devConfig = require('./dev-config');
 
 /**
  * Checks if Docker is installed and available
@@ -33,17 +35,28 @@ async function checkDocker() {
 
 /**
  * Checks if required ports are available
+ * Uses developer-specific ports when developer-id greater than 0 (basePort + developerId * 100)
  *
  * @async
  * @function checkPorts
+ * @param {number[]} [requiredPorts] - Ports to check. If omitted, uses ports from config developer-id
  * @returns {Promise<string>} 'ok' if all ports are available, 'warning' otherwise
  */
-async function checkPorts() {
-  const requiredPorts = [5432, 6379, 5050, 8081];
+async function checkPorts(requiredPorts) {
   const netstat = require('net');
+  let portsToCheck = requiredPorts;
+
+  if (!portsToCheck || portsToCheck.length === 0) {
+    const devId = await config.getDeveloperId();
+    const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
+    const id = Number.isNaN(idNum) || idNum < 0 ? 0 : idNum;
+    const ports = devConfig.getDevPorts(id);
+    portsToCheck = [ports.postgres, ports.redis, ports.pgadmin, ports.redisCommander];
+  }
+
   let portIssues = 0;
 
-  for (const port of requiredPorts) {
+  for (const port of portsToCheck) {
     try {
       await new Promise((resolve, reject) => {
         const server = netstat.createServer();
@@ -128,10 +141,16 @@ async function checkEnvironment() {
     result.recommendations.push('Install Docker and Docker Compose');
   }
 
-  // Check ports
-  result.ports = await checkPorts();
+  // Check ports (developer-specific: dev 0 = base ports, dev N = base + N*100)
+  const devId = await config.getDeveloperId();
+  const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
+  const id = Number.isNaN(idNum) || idNum < 0 ? 0 : idNum;
+  const ports = devConfig.getDevPorts(id);
+  const requiredPorts = [ports.postgres, ports.redis, ports.pgadmin, ports.redisCommander];
+
+  result.ports = await checkPorts(requiredPorts);
   if (result.ports === 'warning') {
-    result.recommendations.push('Some required ports (5432, 6379, 5050, 8081) are in use');
+    result.recommendations.push(`Some required ports (${requiredPorts.join(', ')}) are in use`);
   }
 
   // Check secrets

package/lib/utils/help-builder.js

@@ -75,7 +75,6 @@ const CATEGORIES = [
       { name: 'resolve', term: 'resolve <app>' },
       { name: 'json', term: 'json <app>' },
       { name: 'split-json', term: 'split-json <app>' },
-      { name: 'genkey', term: 'genkey <app>' },
       { name: 'validate', term: 'validate <appOrFile>' },
       { name: 'diff', term: 'diff <file1> <file2>' }
     ]

package/lib/utils/image-version.js

@@ -0,0 +1,209 @@
+/**
+ * AI Fabrix Builder - Image Version Resolution
+ *
+ * Resolves application version from Docker image (OCI label or semver tag).
+ * When template is empty or image version is greater, uses image version.
+ *
+ * @fileoverview Image version resolution utilities
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { exec } = require('child_process');
+const { promisify } = require('util');
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { getBuilderPath } = require('./paths');
+const composeGenerator = require('./compose-generator');
+const containerHelpers = require('./app-run-containers');
+
+const execAsync = promisify(exec);
+
+const OCI_VERSION_LABEL = 'org.opencontainers.image.version';
+const SEMVER_REGEX = /^v?(\d+\.\d+\.\d+)(?:-[-.\w]+)?(?:\+[-.\w]+)?$/i;
+
+/**
+ * Gets version from Docker image via OCI label or semver tag
+ * @async
+ * @param {string} imageName - Image name (e.g. aifabrix/dataplane)
+ * @param {string} imageTag - Image tag (e.g. v1.0.0, latest)
+ * @returns {Promise<string|null>} Version string or null if not found
+ */
+async function getVersionFromImage(imageName, imageTag) {
+  if (!imageName || typeof imageName !== 'string') {
+    return null;
+  }
+  const tag = imageTag || 'latest';
+  const fullImage = `${imageName}:${tag}`;
+
+  try {
+    const labelFormat = `{{index .Config.Labels "${OCI_VERSION_LABEL}"}}`;
+    const { stdout } = await execAsync(
+      `docker inspect --format '${labelFormat}' "${fullImage}" 2>/dev/null || true`,
+      { timeout: 10000 }
+    );
+    const labelValue = (stdout || '').trim();
+    if (labelValue && labelValue !== '<no value>') {
+      return labelValue;
+    }
+
+    const tagMatch = tag.match(SEMVER_REGEX);
+    if (tagMatch) {
+      return tagMatch[1];
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compares two semantic versions
+ * @param {string} a - First version
+ * @param {string} b - Second version
+ * @returns {number} -1 if a < b, 0 if a === b, 1 if a > b
+ */
+function compareSemver(a, b) {
+  if (!a || !b) {
+    return 0;
+  }
+  const parse = (v) => {
+    const m = String(v).match(SEMVER_REGEX);
+    if (!m) return null;
+    const parts = m[1].split('.').map(Number);
+    return { major: parts[0] || 0, minor: parts[1] || 0, patch: parts[2] || 0 };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return 0;
+  if (pa.major !== pb.major) return pa.major > pb.major ? 1 : -1;
+  if (pa.minor !== pb.minor) return pa.minor > pb.minor ? 1 : -1;
+  if (pa.patch !== pb.patch) return pa.patch > pb.patch ? 1 : -1;
+  return 0;
+}
+
+/**
+ * Resolves version for external app (app.version or externalIntegration.version)
+ * @param {Object} variables - Parsed variables.yaml
+ * @returns {string}
+ */
+function resolveExternalVersion(variables) {
+  const version =
+    variables.app?.version ||
+    variables.externalIntegration?.version ||
+    '1.0.0';
+  return String(version).trim() || '1.0.0';
+}
+
+/**
+ * Resolves version for regular app when image exists
+ * @async
+ * @param {string} imageName - Image name
+ * @param {string} imageTag - Image tag
+ * @param {string} templateVersion - Template version (may be empty)
+ * @returns {Promise<{ version: string, fromImage: boolean }>}
+ */
+async function resolveRegularVersion(imageName, imageTag, templateVersion) {
+  const templateEmpty =
+    templateVersion === undefined ||
+    templateVersion === null ||
+    String(templateVersion).trim() === '';
+  const templateStr = String(templateVersion || '').trim();
+
+  const imageVersion = await getVersionFromImage(imageName, imageTag);
+  const useImage =
+    imageVersion &&
+    (templateEmpty || compareSemver(imageVersion, templateStr) >= 0);
+
+  const version = useImage ? imageVersion : (templateEmpty ? '1.0.0' : templateStr);
+  return { version, fromImage: Boolean(useImage) };
+}
+
+/**
+ * Resolves version for an app: from image when image exists and template empty or smaller
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} variables - Parsed variables.yaml
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.updateBuilder] - When true, update builder/variables.yaml if fromImage
+ * @param {string} [options.builderPath] - Builder path (defaults to getBuilderPath(appName))
+ * @returns {Promise<{ version: string, fromImage: boolean, updated: boolean }>}
+ */
+async function resolveVersionForApp(appName, variables, options = {}) {
+  if (!appName || typeof appName !== 'string') {
+    return { version: '1.0.0', fromImage: false, updated: false };
+  }
+
+  if (variables?.externalIntegration) {
+    const version = resolveExternalVersion(variables);
+    return { version, fromImage: false, updated: false };
+  }
+
+  const imageName = composeGenerator.getImageName(variables, appName);
+  const imageTag = variables?.image?.tag || 'latest';
+  const imageExists = await containerHelpers.checkImageExists(imageName, imageTag);
+
+  if (!imageExists) {
+    const templateVersion = variables?.app?.version;
+    const templateEmpty =
+      templateVersion === undefined ||
+      templateVersion === null ||
+      String(templateVersion).trim() === '';
+    const fallback = templateEmpty ? '1.0.0' : String(templateVersion).trim();
+    return { version: fallback, fromImage: false, updated: false };
+  }
+
+  const { version, fromImage } = await resolveRegularVersion(
+    imageName,
+    imageTag,
+    variables?.app?.version
+  );
+
+  let updated = false;
+  if (fromImage && options.updateBuilder) {
+    const builderPath = options.builderPath || getBuilderPath(appName);
+    updated = await updateAppVersionInVariablesYaml(builderPath, version);
+  }
+
+  return { version, fromImage, updated };
+}
+
+/**
+ * Updates app.version in builder variables.yaml
+ * @async
+ * @param {string} builderPath - Path to builder app directory
+ * @param {string} version - Version to set
+ * @returns {Promise<boolean>} True if file was updated
+ */
+async function updateAppVersionInVariablesYaml(builderPath, version) {
+  if (!builderPath || !version || typeof version !== 'string') {
+    return false;
+  }
+  const variablesPath = path.join(builderPath, 'variables.yaml');
+  if (!fsSync.existsSync(variablesPath)) {
+    return false;
+  }
+
+  try {
+    const content = await fs.readFile(variablesPath, 'utf8');
+    const parsed = yaml.load(content) || {};
+    if (!parsed.app) {
+      parsed.app = {};
+    }
+    parsed.app.version = version;
+    const dumped = yaml.dump(parsed, { lineWidth: -1 });
+    await fs.writeFile(variablesPath, dumped, { mode: 0o644, encoding: 'utf8' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  getVersionFromImage,
+  compareSemver,
+  resolveVersionForApp,
+  updateAppVersionInVariablesYaml
+};

package/lib/utils/schema-loader.js

@@ -199,7 +199,7 @@ function detectFromDatasourceFields(parsed) {
  * @returns {string|null} Schema type or null if not detected
  */
 function detectFromApplicationFields(parsed) {
-  if (parsed.deploymentKey || (parsed.image && parsed.registryMode && parsed.port)) {
+  if (parsed.image && parsed.registryMode && parsed.port) {
     return 'application';
   }
   return null;

package/lib/utils/variable-transformer.js

@@ -96,20 +96,6 @@ function handlePartialAuthentication(authentication) {
   return auth;
 }
 
-/**
- * Adds placeholder deployment key if missing
- * @function addPlaceholderDeploymentKey
- * @param {Object} result - Result object
- * @returns {Object} Result object with deployment key
- */
-function addPlaceholderDeploymentKey(result) {
-  if (!result.deploymentKey) {
-    // This is a 64-character hex string matching the SHA256 pattern
-    result.deploymentKey = '0000000000000000000000000000000000000000000000000000000000000000';
-  }
-  return result;
-}
-
 /**
  * Transforms flat structure to schema-compatible format
  * @function transformFlatStructure
@@ -126,9 +112,6 @@ function transformFlatStructure(variables, appName) {
     result.authentication = handlePartialAuthentication(result.authentication);
   }
 
-  // Add placeholder deploymentKey for validation
-  addPlaceholderDeploymentKey(result);
-
   return result;
 }
 
@@ -215,22 +198,14 @@ function validateBuildConfig(build) {
 }
 
 /**
- * Validates and transforms deployment configuration
+ * Validates and transforms deployment configuration.
+ * Manifest is generic: deployment URL/env are resolved outside the manifest (user/config).
  * @function validateDeploymentConfig
- * @param {Object} deployment - Deployment configuration
- * @returns {Object|null} Validated deployment config or null
+ * @param {Object} _deployment - Deployment configuration (unused; manifest is generic)
+ * @returns {null} No deployment block emitted from variables
  */
-function validateDeploymentConfig(deployment) {
-  if (!deployment) {
-    return null;
-  }
-
-  const deploymentConfig = {};
-  if (deployment.controllerUrl && deployment.controllerUrl.trim() !== '' && /^https:\/\/.*$/.test(deployment.controllerUrl)) {
-    deploymentConfig.controllerUrl = deployment.controllerUrl;
-  }
-
-  return Object.keys(deploymentConfig).length > 0 ? deploymentConfig : null;
+function validateDeploymentConfig(_deployment) {
+  return null;
 }
 
 /**
@@ -379,8 +354,7 @@ function transformVariablesForValidation(variables, appName) {
 
   // Nested structure - transform it
   const transformed = buildBaseTransformedStructure(variables, appName);
-  const result = transformOptionalFields(variables, transformed);
-  return addPlaceholderDeploymentKey(result);
+  return transformOptionalFields(variables, transformed);
 }
 
 module.exports = {

package/lib/validation/external-manifest-validator.js

@@ -148,7 +148,7 @@ function validateConditionalRequirements(manifest, errors, warnings) {
  * @returns {void}
  */
 function validateRequiredFields(manifest, errors) {
-  const requiredFields = ['key', 'displayName', 'description', 'type', 'deploymentKey'];
+  const requiredFields = ['key', 'displayName', 'description', 'type'];
   requiredFields.forEach(field => {
     if (!manifest[field]) {
       errors.push(`Required field "${field}" is missing`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.37.9",
+  "version": "2.39.0",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {

package/templates/applications/README.md.hbs

@@ -92,8 +92,7 @@ aifabrix dockerfile {{appName}} --force           # Generate Dockerfile
 aifabrix resolve {{appName}}                      # Generate .env file
 
 # Deployment
-aifabrix json {{appName}}                         # Preview deployment JSON
-aifabrix genkey {{appName}}                       # Generate deployment key
+aifabrix json {{appName}}                         # Generate deployment manifest
 aifabrix push {{appName}} --registry {{registry}} # Push to ACR
 aifabrix deploy {{appName}}                       # Deploy (controller/env from config)
 
@@ -176,7 +175,6 @@ Controller URL and environment (for `deploy`, `app register`, etc.) are set via
 ```bash
 aifabrix resolve {{appName}} --force
 aifabrix json {{appName}}
-aifabrix genkey {{appName}}
 ```
 
 ---

package/templates/applications/dataplane/Dockerfile

@@ -9,8 +9,8 @@ FROM aifabrix/dataplane:latest
 EXPOSE 3001
 
 # Health check (documentation; base image may already set this)
-HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
-    CMD curl -f http://localhost:3001/health || exit 1
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1
 
 # CMD inherited from base image; override only if needed
 # CMD inherited: uvicorn app.main:app --host 0.0.0.0 --port 3001