@aifabrix/builder 2.57.0 → 2.58.0

package/lib/schema/infrastructure-schema.json

@@ -12,7 +12,7 @@
     "category": "infrastructure",
     "author": "AI Fabrix Team",
     "createdAt": "2024-01-01T00:00:00Z",
-    "updatedAt": "2026-09-16T00:00:00Z",
+    "updatedAt": "2026-09-17T00:00:00Z",
     "compatibility": {
       "minVersion": "2.0.0",
       "maxVersion": "2.0.0",
@@ -34,7 +34,7 @@
           "Replaced the environment-configuration shape with the installation workspace manifest (environment-infra.json).",
           "Removed smtp without replacement.",
           "Covers every Marketplace template parameter and output with source/description metadata; secure parameters are valueFromEnv references.",
-          "Added vendor, workspace subscription/tenant, acrName, default-off allowMyIp, licenseEdition, onboardingMode, tenant activation, deployment and application variable catalog sections."
+          "Added vendor, workspace subscription/tenant, acrName, acrAuth (auto|mi|credentials, deprecated admin alias, resolved effective mode), deployRoleAssignments restore metadata, default-off allowMyIp, licenseEdition, onboardingMode, tenant activation, deployment and application variable catalog sections."
         ]
       },
       {
@@ -366,6 +366,44 @@
         }
       }
     },
+    "acrAuth": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "enum": [
+            "auto",
+            "mi",
+            "credentials",
+            "admin"
+          ],
+          "description": "Requested image-pull auth; admin is a deprecated alias for credentials."
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "effective": {
+          "enum": [
+            "mi",
+            "credentials"
+          ],
+          "description": "Pull auth resolved by the last infra run (non-secret)."
+        }
+      }
+    },
     "allowMyIp": {
       "type": "object",
       "required": [
@@ -926,6 +964,20 @@
             },
             "required": {
               "type": "boolean"
+            },
+            "restoreValue": {
+              "type": [
+                "string",
+                "boolean",
+                "number",
+                "object",
+                "array"
+              ],
+              "description": "Value to restore when credential mode no longer applies."
+            },
+            "restoreSource": {
+              "type": "string",
+              "minLength": 1
             }
           }
         },
@@ -1611,6 +1663,7 @@
       "then": {
         "required": [
           "acrName",
+          "acrAuth",
           "allowMyIp",
           "preset",
           "parameters",

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

@@ -80,10 +80,8 @@ async function createMinimalAppIfNeeded(appKey, options) {
  * @returns {string} Image reference string
  */
 function buildImageReference(variables, appKey) {
-  const imageName = variables.image?.name || variables.app?.key || appKey;
-  const registry = variables.image?.registry;
-  const tag = variables.image?.tag || 'latest';
-  return registry ? `${registry}/${imageName}:${tag}` : `${imageName}:${tag}`;
+  const { buildManifestImageReference } = require('./resolve-docker-image-ref');
+  return buildManifestImageReference(variables, appKey);
 }
 
 /**

package/lib/utils/build-resolve-image.js

@@ -14,7 +14,8 @@ const { execWithDockerEnv } = require('./docker-exec');
 const { buildDevImageName, buildDevImageRepositoryPath } = require('./image-name');
 const {
   getRepositoryPathFromConfig,
-  resolveDockerImageRef
+  resolveDockerImageRef,
+  stripRegistryHostFromRepository
 } = require('./resolve-docker-image-ref');
 
 /**
@@ -48,26 +49,6 @@ function repositoryTail(repoPath) {
   return parts[parts.length - 1] || repoPath;
 }
 
-/**
- * Remove registry host prefix from a Docker repository path (local build only).
- * @param {string} repository
- * @returns {string}
- */
-function stripRegistryHostFromRepository(repository) {
-  if (!repository || typeof repository !== 'string') {
-    return repository;
-  }
-  const parts = repository.split('/');
-  if (parts.length <= 1) {
-    return repository;
-  }
-  const host = parts[0];
-  if (host.includes('.') || host.includes(':') || host === 'localhost') {
-    return parts.slice(1).join('/');
-  }
-  return repository;
-}
-
 /**
  * Strip dev-scoped or -extra suffix from a Docker repository path.
  * @param {string} repo

package/lib/utils/cli-utils.js

@@ -198,6 +198,9 @@ function isAzureCliToolingError(errorMsg) {
   return false;
 }
 
+/** Registry-credential and per-tag push errors that already name the host and the next step. */
+const REGISTRY_ACTIONABLE_ERROR = /dev set-registry|Push failed for |No registry credentials are available/;
+
 /**
  * Format Azure-related errors
  * @param {string} errorMsg - Error message
@@ -221,6 +224,10 @@ function formatAzureError(errorMsg) {
   if (errorMsg.includes('Docker build failed') || errorMsg.includes('Build failed: Docker')) {
     return null;
   }
+  // Registry-credential and per-tag push errors already carry host-specific next steps.
+  if (REGISTRY_ACTIONABLE_ERROR.test(errorMsg)) {
+    return null;
+  }
   const lowerMsg = String(errorMsg || '').toLowerCase();
   const hasAcrDomain = /\b[a-z0-9.-]+\.azurecr\.io\b/i.test(errorMsg);
   const hasAcrKeyword = /\bacr\b/.test(lowerMsg);
@@ -238,7 +245,7 @@ function formatAzureError(errorMsg) {
   if (errorMsg.includes('Registry URL is required')) {
     return [
       '   Registry URL is required.',
-      '   Provide via --registry flag or configure in application.yaml under image.registry'
+      '   Provide via --registry, set a default with aifabrix dev set-registry <host>, or configure image.registry in application.yaml'
     ];
   }
   return null;

package/lib/utils/config-registry-preference.js

@@ -0,0 +1,106 @@
+/**
+ * Installation-level default container registry (`registry` in the Builder config.yaml).
+ *
+ * @fileoverview Registry host validation plus get/set/clear preference helpers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const yaml = require('js-yaml');
+const fs = require('../internal/fs-real-sync');
+const { getRuntimeConfigFile } = require('../core/config-runtime-paths');
+
+const REGISTRY_CONFIG_KEY = 'registry';
+const HOST_LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+const REGISTRY_HOST_RE = new RegExp(`^${HOST_LABEL}(?:\\.${HOST_LABEL})*(?::\\d{1,5})?$`);
+
+/**
+ * Normalizes and validates a registry host (optionally with a port).
+ * Rejects schemes, paths, embedded credentials, query/fragment text and whitespace.
+ * @param {string} value - Raw registry value
+ * @returns {string} Lower-case host[:port]
+ * @throws {Error} When the value is empty or not a plain host
+ */
+function normalizeRegistryHost(value) {
+  const raw = typeof value === 'string' ? value.trim() : '';
+  const withoutSlash = raw.replace(/\/+$/, '');
+  if (!withoutSlash) {
+    throw new Error('Registry is required (for example myregistry.azurecr.io)');
+  }
+  if (/[\s@?#/\\]|:\/\//.test(withoutSlash)) {
+    throw new Error(`Invalid registry "${raw}": use a host name such as myregistry.azurecr.io (no scheme, path or credentials)`);
+  }
+  const host = withoutSlash.toLowerCase();
+  const port = host.includes(':') ? Number(host.split(':')[1]) : null;
+  if (!REGISTRY_HOST_RE.test(host) || (port !== null && (port < 1 || port > 65535))) {
+    throw new Error(`Invalid registry "${raw}": use a host name such as myregistry.azurecr.io`);
+  }
+  return host;
+}
+
+/**
+ * Reads the installation registry synchronously (used by the shared image resolver).
+ * An unreadable or invalid value is treated as unset so image resolution keeps working.
+ * @returns {string} Normalized host or '' when unset
+ */
+function readInstallationRegistrySync() {
+  try {
+    const file = getRuntimeConfigFile();
+    if (!fs.existsSync(file)) return '';
+    const cfg = yaml.load(fs.readFileSync(file, 'utf8')) || {};
+    const value = cfg[REGISTRY_CONFIG_KEY];
+    return typeof value === 'string' && value.trim() ? normalizeRegistryHost(value) : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * @param {Function} getConfigFn - async () => config object
+ * @param {Function} saveConfigFn - async (config) => void
+ * @returns {{ getRegistry: Function, setRegistry: Function, clearRegistry: Function }}
+ */
+function createRegistryPreferenceFunctions(getConfigFn, saveConfigFn) {
+  return {
+    /**
+     * @returns {Promise<string|null>} Saved registry host or null
+     */
+    async getRegistry() {
+      const cfg = await getConfigFn();
+      const value = cfg[REGISTRY_CONFIG_KEY];
+      return typeof value === 'string' && value.trim() ? value.trim() : null;
+    },
+
+    /**
+     * @param {string} registry - Registry host
+     * @returns {Promise<string>} Normalized saved value
+     */
+    async setRegistry(registry) {
+      const host = normalizeRegistryHost(registry);
+      const cfg = await getConfigFn();
+      cfg[REGISTRY_CONFIG_KEY] = host;
+      await saveConfigFn(cfg);
+      return host;
+    },
+
+    /**
+     * Removes the saved registry (idempotent).
+     * @returns {Promise<void>}
+     */
+    async clearRegistry() {
+      const cfg = await getConfigFn();
+      if (!(REGISTRY_CONFIG_KEY in cfg)) return;
+      delete cfg[REGISTRY_CONFIG_KEY];
+      await saveConfigFn(cfg);
+    }
+  };
+}
+
+module.exports = {
+  REGISTRY_CONFIG_KEY,
+  normalizeRegistryHost,
+  readInstallationRegistrySync,
+  createRegistryPreferenceFunctions
+};

package/lib/utils/docker-build.js

@@ -252,13 +252,44 @@ async function executeBuild(imageName, dockerfilePath, contextPath, tag, options
       (options.cache === false || options.noCache === true || options['no-cache'] === true)
   );
   await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs, noCache);
+  await applyTagAliases(imageName, tag, resolveTagAliases(tag, options));
+}
 
-  // Also apply floating `latest` when building a version tag (matches dev-promote dual tags).
+/**
+ * Aliases for the built image: explicit `options.tagAliases` from the shared tag plan, else the
+ * legacy rule (a single non-floating `options.tag` also gets `latest`).
+ * @param {string} tag - Built tag
+ * @param {Object} [options] - Build options
+ * @returns {string[]}
+ */
+function resolveTagAliases(tag, options) {
+  if (options && Array.isArray(options.tagAliases)) {
+    return options.tagAliases.filter((alias) => alias !== tag);
+  }
   if (options && options.tag && options.tag !== 'latest' && options.tag !== 'main') {
-    const { execFileWithDockerEnv } = require('./docker-exec');
-    const { getDockerExecEnv } = require('./remote-docker-env');
-    const env = await getDockerExecEnv();
-    await execFileWithDockerEnv('docker', ['tag', `${imageName}:${tag}`, `${imageName}:latest`], { env });
+    return ['latest'];
+  }
+  return [];
+}
+
+/**
+ * Tag the built image with every alias (argument arrays; no shell interpolation).
+ * @param {string} imageName - Repository
+ * @param {string} tag - Built tag
+ * @param {string[]} aliases - Additional tags
+ * @returns {Promise<void>}
+ */
+async function applyTagAliases(imageName, tag, aliases) {
+  if (!aliases.length) return;
+  const { execFileWithDockerEnv } = require('./docker-exec');
+  const { getDockerExecEnv } = require('./remote-docker-env');
+  const env = await getDockerExecEnv();
+  for (const alias of aliases) {
+    try {
+      await execFileWithDockerEnv('docker', ['tag', `${imageName}:${tag}`, `${imageName}:${alias}`], { env });
+    } catch (error) {
+      throw new Error(`Failed to tag ${imageName}:${alias}: ${error.message}`);
+    }
   }
 }
 
@@ -286,26 +317,29 @@ async function executeDockerBuildWithTag(effectiveImageName, imageName, dockerfi
     return;
   }
 
-  try {
-    const { execFileWithDockerEnv } = require('./docker-exec');
-    const { getDockerExecEnv } = require('./remote-docker-env');
-    const env = await getDockerExecEnv();
-    await execFileWithDockerEnv(
-      'docker',
-      ['tag', `${effectiveImageName}:${tag}`, `${imageName}:${tag}`],
-      { env }
-    );
-    logger.log(formatSuccessLine(`Tagged image: ${imageName}:${tag}`));
-  } catch (err) {
-    logger.log(
-      formatWarningLine(`Could not create compatibility tag ${imageName}:${tag} - ${err.message}`)
-    );
+  const { execFileWithDockerEnv } = require('./docker-exec');
+  const { getDockerExecEnv } = require('./remote-docker-env');
+  const env = await getDockerExecEnv();
+  for (const compatTag of [tag, ...resolveTagAliases(tag, options)]) {
+    try {
+      await execFileWithDockerEnv(
+        'docker',
+        ['tag', `${effectiveImageName}:${compatTag}`, `${imageName}:${compatTag}`],
+        { env }
+      );
+      logger.log(formatSuccessLine(`Tagged image: ${imageName}:${compatTag}`));
+    } catch (err) {
+      logger.log(
+        formatWarningLine(`Could not create compatibility tag ${imageName}:${compatTag} - ${err.message}`)
+      );
+    }
   }
 }
 
 module.exports = {
   executeDockerBuild,
   executeBuild,
+  resolveTagAliases,
   executeDockerBuildWithTag,
   isDockerNotAvailableError
 };

package/lib/utils/env-map.js

@@ -12,6 +12,8 @@ const fs = require('fs');
 const yaml = require('js-yaml');
 const { loadEnvConfig, loadSchemaEnvConfig } = require('./env-config-loader');
 const config = require('../core/config');
+const { buildDevUsernameForFrontDoorHost } = require('./compose-traefik-ingress-base');
+const { resolveRemoteHostForFrontDoor } = require('./remote-host-for-front-door');
 
 /**
  * Load base environment variables from env-config.yaml
@@ -309,19 +311,34 @@ function applyPublicPortAdjustmentsForContext(result, context, devIdNum) {
 }
 
 /**
- * Set TLS_ENABLED / HTTP_ENABLED from ~/.aifabrix/config.yaml (tlsEnabled).
+ * Add config-derived interpolation values used by env.template.
  * @param {Object} result - Env map (mutated)
+ * @param {number} devIdNum - Normalized developer ID
  */
-async function applyTlsHttpManifestFlags(result) {
+async function applyRuntimeConfigVars(result, devIdNum) {
+  let userCfg = {};
   let tlsOn = false;
   try {
-    const userCfg = await config.getConfig();
+    userCfg = await config.getConfig();
     tlsOn = Boolean(userCfg && userCfg.tlsEnabled === true);
   } catch {
-    tlsOn = false;
+    userCfg = {};
   }
   result.TLS_ENABLED = tlsOn ? 'true' : 'false';
   result.HTTP_ENABLED = tlsOn ? 'false' : 'true';
+  const devUsername = buildDevUsernameForFrontDoorHost(devIdNum);
+  const remoteServerHost = resolveRemoteHostForFrontDoor({
+    remoteServer: userCfg && userCfg['remote-server']
+  });
+  const remoteHost = remoteServerHost ? remoteServerHost.split('.')[0] : '';
+  const devRootDomain = resolveRemoteHostForFrontDoor({
+    developerRootDomain: userCfg && userCfg['developer-root-domain']
+  });
+  if (devUsername || remoteHost) {
+    result.DEV_USERNAME = devUsername;
+    result.REMOTE_HOST = remoteHost;
+  }
+  if (devRootDomain) result.DEV_ROOT_DOMAIN = devRootDomain;
 }
 
 /**
@@ -333,6 +350,7 @@ async function applyTlsHttpManifestFlags(result) {
  * - Applies developer-id adjustment to port variables for local context
  * - Calculates *_PUBLIC_PORT for both local and docker context (basePort + developer-id * 100)
  * - Adds TLS_ENABLED and HTTP_ENABLED ("true" / "false"); HTTP_ENABLED = !TLS_ENABLED for manifest ${...} substitution
+ * - Adds DEV_USERNAME, REMOTE_HOST, and DEV_ROOT_DOMAIN from Builder configuration
  * @async
  * @function buildEnvVarMap
  * @param {'docker'|'local'} context - Environment context
@@ -358,7 +376,7 @@ async function buildEnvVarMap(context, osModule = null, developerId = null, opti
     applyLocalPortAdjustment(result, devIdNum);
   }
   applyPublicPortAdjustmentsForContext(result, context, devIdNum);
-  await applyTlsHttpManifestFlags(result);
+  await applyRuntimeConfigVars(result, devIdNum);
   return result;
 }
 
@@ -367,4 +385,3 @@ module.exports = {
   getDeveloperIdNumber,
   resolvePortInEnvValues
 };
-

package/lib/utils/image-tags.js

@@ -0,0 +1,88 @@
+/**
+ * Image tag lists for build and push: comma-separated tags, exact `{version}` expansion from the
+ * application's `app.version`, Docker tag validation, and order-preserving de-duplication.
+ * All validation happens before any Docker call.
+ *
+ * @fileoverview Shared image tag resolution
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { assertSafeTag } = require('./resolve-docker-image-ref');
+
+const DEFAULT_TAG = 'latest';
+const VERSION_PLACEHOLDER = '{version}';
+/** Tags that are floating aliases themselves (a single explicit one gets no extra `latest`). */
+const FLOATING_TAGS = Object.freeze(['latest', 'main']);
+
+/**
+ * @param {Object} [appConfig] - Application manifest (possibly wrapped in `variables`)
+ * @returns {string} Trimmed `app.version` or ''
+ */
+function readAppVersion(appConfig) {
+  const cfg = appConfig?.variables?.app ? appConfig.variables : appConfig;
+  const raw = cfg?.app?.version;
+  return raw === undefined || raw === null ? '' : String(raw).trim();
+}
+
+function expandTag(entry, version) {
+  if (entry === VERSION_PLACEHOLDER) {
+    if (!version) {
+      throw new Error('Tag {version} requires a non-empty app.version in the application manifest');
+    }
+    return version;
+  }
+  if (entry.includes('{') || entry.includes('}')) {
+    throw new Error(`Unsupported tag placeholder "${entry}"; only the exact token {version} is supported`);
+  }
+  return entry;
+}
+
+/**
+ * Resolves a tag option into a validated, de-duplicated list (first occurrence wins).
+ * @param {string|undefined} tagInput - `--tag` value (omitted means `latest`)
+ * @param {string} appVersion - Application `app.version`
+ * @returns {string[]}
+ * @throws {Error} On blank entries, unsupported placeholders, missing version or invalid tags
+ */
+function resolveImageTags(tagInput, appVersion) {
+  if (tagInput === undefined || tagInput === null || String(tagInput).trim() === '') {
+    return [DEFAULT_TAG];
+  }
+  const entries = String(tagInput).split(',').map((entry) => entry.trim());
+  if (entries.some((entry) => entry === '')) {
+    throw new Error(`Invalid tag list "${tagInput}": remove empty entries between commas`);
+  }
+  const resolved = [];
+  for (const entry of entries) {
+    const tag = assertSafeTag(expandTag(entry, String(appVersion || '').trim()));
+    if (!resolved.includes(tag)) resolved.push(tag);
+  }
+  return resolved;
+}
+
+/**
+ * Build plan: the first tag is the Docker build target; the rest are aliases of the same image.
+ * A single explicit non-floating tag keeps its compatibility `latest` alias.
+ * @param {string|undefined} tagInput - `--tag` value
+ * @param {string} appVersion - Application `app.version`
+ * @returns {{ primary: string, aliases: string[], tags: string[] }}
+ */
+function resolveBuildTagPlan(tagInput, appVersion) {
+  const tags = resolveImageTags(tagInput, appVersion);
+  const explicitSingle = tags.length === 1 && tagInput !== undefined && tagInput !== null && String(tagInput).trim() !== '';
+  if (explicitSingle && !FLOATING_TAGS.includes(tags[0])) {
+    tags.push(DEFAULT_TAG);
+  }
+  return { primary: tags[0], aliases: tags.slice(1), tags };
+}
+
+module.exports = {
+  DEFAULT_TAG,
+  VERSION_PLACEHOLDER,
+  readAppVersion,
+  resolveImageTags,
+  resolveBuildTagPlan
+};

package/lib/utils/promote-dev-docker-image.js

@@ -88,6 +88,12 @@ function resolvePromoteVersionTag(options = {}) {
  * @returns {string[]}
  */
 function resolvePromoteBaseTags(options = {}) {
+  if (options.tagPlan && Array.isArray(options.tagPlan.tags) && options.tagPlan.tags.length > 0) {
+    // Shared build tag plan (comma list / {version}); every tag becomes a base alias.
+    const tags = [...options.tagPlan.tags];
+    if (!tags.includes(PROMOTE_FLOATING_TAG)) tags.push(PROMOTE_FLOATING_TAG);
+    return tags;
+  }
   const versionTag = resolvePromoteVersionTag(options);
   const tags = [versionTag];
   if (versionTag !== PROMOTE_FLOATING_TAG) {