@aifabrix/builder 2.33.1 → 2.33.4

package/README.md

@@ -36,6 +36,13 @@ aifabrix down myapp
 
 Want authentication or deployment controller?
 
+**Quick install from images (no build):**
+```bash
+aifabrix up              # Start Postgres + Redis first
+aifabrix up-miso         # Install Keycloak + Miso Controller from images (auto-generated secrets for testing)
+```
+
+**Or create and build from templates:**
 ```bash
 # Keycloak for authentication
 aifabrix create keycloak --port 8082 --database --template keycloak
@@ -48,6 +55,12 @@ aifabrix build miso-controller
 aifabrix run miso-controller
 ```
 
+**Dataplane in dev (after login):**
+```bash
+aifabrix login --environment dev
+aifabrix up-dataplane    # Register or rotate, run, and deploy dataplane in dev
+```
+
 → [Infrastructure Guide](docs/infrastructure.md)
 
 ## Documentation

package/lib/app/deploy-config.js

@@ -0,0 +1,161 @@
+/**
+ * Deployment configuration loading and validation for deploy flow.
+ * Extracted from deploy.js to keep file size within limits.
+ *
+ * @fileoverview Deployment config for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('js-yaml');
+const config = require('../core/config');
+const { getDeploymentAuth } = require('../utils/token-manager');
+const { detectAppType } = require('../utils/paths');
+const { resolveControllerUrl } = require('../utils/controller-url');
+
+/**
+ * Validates that the application directory exists
+ * @async
+ * @param {string} builderPath - Path to builder directory
+ * @param {string} appName - Application name
+ * @throws {Error} If directory doesn't exist
+ */
+async function validateAppDirectory(builderPath, appName) {
+  try {
+    await fs.access(builderPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`Application '${appName}' not found in builder/. Run 'aifabrix create ${appName}' first`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Loads variables.yaml file
+ * @async
+ * @param {string} variablesPath - Path to variables.yaml
+ * @returns {Promise<Object>} Variables object
+ * @throws {Error} If file cannot be loaded
+ */
+async function loadVariablesFile(variablesPath) {
+  try {
+    const variablesContent = await fs.readFile(variablesPath, 'utf8');
+    return yaml.load(variablesContent);
+  } catch (error) {
+    throw new Error(`Failed to load configuration from variables.yaml: ${error.message}`);
+  }
+}
+
+/**
+ * Extracts deployment configuration from config.yaml
+ * Resolves controller URL using fallback chain: config.controller → logged-in user → developer ID default
+ * Resolves environment using fallback chain: config.environment → default 'dev'
+ * @async
+ * @param {Object} options - CLI options (for poll settings only)
+ * @param {Object} _variables - Variables from variables.yaml (unused, kept for compatibility)
+ * @returns {Promise<Object>} Extracted configuration with resolved controller URL
+ */
+async function extractDeploymentConfig(options, _variables) {
+  const { resolveEnvironment } = require('../core/config');
+
+  const controllerUrl = await resolveControllerUrl();
+  const envKey = await resolveEnvironment();
+
+  return {
+    controllerUrl,
+    envKey,
+    poll: options.poll !== false,
+    pollInterval: options.pollInterval || 5000,
+    pollMaxAttempts: options.pollMaxAttempts || 60
+  };
+}
+
+/**
+ * Validates required deployment configuration
+ * @param {Object} deploymentConfig - Deployment configuration
+ * @throws {Error} If configuration is invalid
+ */
+function validateDeploymentConfig(deploymentConfig) {
+  if (!deploymentConfig.controllerUrl) {
+    throw new Error('Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml');
+  }
+  if (!deploymentConfig.auth) {
+    throw new Error('Authentication is required. Run "aifabrix login" first or ensure credentials are in secrets.local.yaml');
+  }
+}
+
+/**
+ * Configure deployment environment settings from config.yaml
+ * @async
+ * @param {Object} _options - CLI options (unused, kept for compatibility)
+ * @param {Object} deploymentConfig - Deployment configuration to update
+ * @returns {Promise<void>}
+ */
+async function configureDeploymentEnvironment(_options, deploymentConfig) {
+  const currentEnvironment = await config.getCurrentEnvironment();
+  deploymentConfig.envKey = deploymentConfig.envKey || currentEnvironment;
+}
+
+/**
+ * Refresh deployment token and configure authentication
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} deploymentConfig - Deployment configuration to update
+ * @returns {Promise<void>}
+ * @throws {Error} If authentication fails
+ */
+async function refreshDeploymentToken(appName, deploymentConfig) {
+  if (!deploymentConfig.controllerUrl) {
+    throw new Error('Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml');
+  }
+
+  try {
+    const authConfig = await getDeploymentAuth(
+      deploymentConfig.controllerUrl,
+      deploymentConfig.envKey,
+      appName
+    );
+    if (!authConfig || !authConfig.controller) {
+      throw new Error('Invalid authentication configuration: missing controller URL');
+    }
+    if (!authConfig.token) {
+      throw new Error('Authentication is required');
+    }
+    deploymentConfig.auth = authConfig;
+    deploymentConfig.controllerUrl = authConfig.controller;
+  } catch (error) {
+    throw new Error(`Failed to get authentication: ${error.message}`);
+  }
+}
+
+/**
+ * Loads deployment configuration from variables.yaml and gets/refreshes token
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} options - CLI options
+ * @returns {Promise<Object>} Deployment configuration with token
+ * @throws {Error} If configuration is invalid
+ */
+async function loadDeploymentConfig(appName, options) {
+  const { appPath } = await detectAppType(appName);
+  await validateAppDirectory(appPath, appName);
+
+  const variablesPath = path.join(appPath, 'variables.yaml');
+  const variables = await loadVariablesFile(variablesPath);
+
+  const deploymentConfig = await extractDeploymentConfig(options, variables);
+
+  await configureDeploymentEnvironment(options, deploymentConfig);
+  await refreshDeploymentToken(appName, deploymentConfig);
+
+  validateDeploymentConfig(deploymentConfig);
+
+  return deploymentConfig;
+}
+
+module.exports = {
+  loadDeploymentConfig
+};

package/lib/app/deploy.js

@@ -15,11 +15,9 @@ const yaml = require('js-yaml');
 const chalk = require('chalk');
 const pushUtils = require('../deployment/push');
 const logger = require('../utils/logger');
-const config = require('../core/config');
-const { getDeploymentAuth } = require('../utils/token-manager');
 const { detectAppType } = require('../utils/paths');
-const { resolveControllerUrl } = require('../utils/controller-url');
 const { checkApplicationExists } = require('../utils/app-existence');
+const { loadDeploymentConfig } = require('./deploy-config');
 
 /**
  * Validate application name format
@@ -145,155 +143,6 @@ async function pushApp(appName, options = {}) {
   }
 }
 
-/**
- * Validates that the application directory exists
- * @async
- * @param {string} builderPath - Path to builder directory
- * @param {string} appName - Application name
- * @throws {Error} If directory doesn't exist
- */
-async function validateAppDirectory(builderPath, appName) {
-  try {
-    await fs.access(builderPath);
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      throw new Error(`Application '${appName}' not found in builder/. Run 'aifabrix create ${appName}' first`);
-    }
-    throw error;
-  }
-}
-
-/**
- * Loads variables.yaml file
- * @async
- * @param {string} variablesPath - Path to variables.yaml
- * @returns {Promise<Object>} Variables object
- * @throws {Error} If file cannot be loaded
- */
-async function loadVariablesFile(variablesPath) {
-  try {
-    const variablesContent = await fs.readFile(variablesPath, 'utf8');
-    return yaml.load(variablesContent);
-  } catch (error) {
-    throw new Error(`Failed to load configuration from variables.yaml: ${error.message}`);
-  }
-}
-
-/**
- * Extracts deployment configuration from config.yaml
- * Resolves controller URL using fallback chain: config.controller → logged-in user → developer ID default
- * Resolves environment using fallback chain: config.environment → default 'dev'
- * @async
- * @param {Object} options - CLI options (for poll settings only)
- * @param {Object} _variables - Variables from variables.yaml (unused, kept for compatibility)
- * @returns {Promise<Object>} Extracted configuration with resolved controller URL
- */
-async function extractDeploymentConfig(options, _variables) {
-  const { resolveEnvironment } = require('../core/config');
-
-  // Resolve controller URL from config.yaml (no flags, no options)
-  const controllerUrl = await resolveControllerUrl();
-
-  // Resolve environment from config.yaml (no flags, no options)
-  const envKey = await resolveEnvironment();
-
-  return {
-    controllerUrl,
-    envKey,
-    poll: options.poll !== false,
-    pollInterval: options.pollInterval || 5000,
-    pollMaxAttempts: options.pollMaxAttempts || 60
-  };
-}
-
-/**
- * Validates required deployment configuration
- * @param {Object} deploymentConfig - Deployment configuration
- * @throws {Error} If configuration is invalid
- */
-function validateDeploymentConfig(deploymentConfig) {
-  if (!deploymentConfig.controllerUrl) {
-    throw new Error('Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml');
-  }
-  if (!deploymentConfig.auth) {
-    throw new Error('Authentication is required. Run "aifabrix login" first or ensure credentials are in secrets.local.yaml');
-  }
-}
-
-/**
- * Configure deployment environment settings from config.yaml
- * @async
- * @param {Object} _options - CLI options (unused, kept for compatibility)
- * @param {Object} deploymentConfig - Deployment configuration to update
- * @returns {Promise<void>}
- */
-async function configureDeploymentEnvironment(_options, deploymentConfig) {
-  // Get current environment from root-level config (already resolved in extractDeploymentConfig)
-  // This function is kept for compatibility but no longer updates environment from options
-  const currentEnvironment = await config.getCurrentEnvironment();
-  deploymentConfig.envKey = deploymentConfig.envKey || currentEnvironment;
-}
-
-/**
- * Refresh deployment token and configure authentication
- * @async
- * @param {string} appName - Application name
- * @param {Object} deploymentConfig - Deployment configuration to update
- * @returns {Promise<void>}
- * @throws {Error} If authentication fails
- */
-async function refreshDeploymentToken(appName, deploymentConfig) {
-  // Get controller URL (should already be resolved by extractDeploymentConfig)
-  if (!deploymentConfig.controllerUrl) {
-    throw new Error('Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml');
-  }
-
-  // Get deployment authentication (device token → client token → credentials)
-  try {
-    const authConfig = await getDeploymentAuth(
-      deploymentConfig.controllerUrl,
-      deploymentConfig.envKey,
-      appName
-    );
-    if (!authConfig || !authConfig.controller) {
-      throw new Error('Invalid authentication configuration: missing controller URL');
-    }
-    if (!authConfig.token) {
-      throw new Error('Authentication is required');
-    }
-    deploymentConfig.auth = authConfig;
-    deploymentConfig.controllerUrl = authConfig.controller;
-  } catch (error) {
-    throw new Error(`Failed to get authentication: ${error.message}`);
-  }
-}
-
-/**
- * Loads deployment configuration from variables.yaml and gets/refreshes token
- * @async
- * @param {string} appName - Application name
- * @param {Object} options - CLI options
- * @returns {Promise<Object>} Deployment configuration with token
- * @throws {Error} If configuration is invalid
- */
-async function loadDeploymentConfig(appName, options) {
-  // Detect app type and get correct path (integration or builder)
-  const { appPath } = await detectAppType(appName);
-  await validateAppDirectory(appPath, appName);
-
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const variables = await loadVariablesFile(variablesPath);
-
-  const deploymentConfig = await extractDeploymentConfig(options, variables);
-
-  await configureDeploymentEnvironment(options, deploymentConfig);
-  await refreshDeploymentToken(appName, deploymentConfig);
-
-  validateDeploymentConfig(deploymentConfig);
-
-  return deploymentConfig;
-}
-
 /**
  * Generates and validates deployment manifest
  * @async
@@ -406,6 +255,22 @@ async function handleDeploymentError(error, appName, controllerUrl, usedExternal
   await deployer.handleDeploymentErrors(error, appName, url, alreadyLogged);
 }
 
+/**
+ * Validates that the deployment image reference is pullable (includes a registry).
+ * A local ref (name:tag) causes "docker: not found" on the controller host.
+ * @param {string} imageRef - Image reference from manifest
+ * @param {string} appName - Application name (for error hint)
+ * @throws {Error} If image is missing or has no registry
+ */
+function validateImageIsPullable(imageRef, appName) {
+  if (!imageRef || !imageRef.includes('/')) {
+    const hint = `Set image.registry and image.tag in builder/${appName}/variables.yaml, or pass a full image ref (e.g. --image <registry>/${appName}:<tag>) when deploying`;
+    throw new Error(
+      `Deployed image must be pullable (include a registry). Current image: "${imageRef || 'none'}". ${hint}`
+    );
+  }
+}
+
 /**
  * Execute standard application deployment flow
  * @async
@@ -422,6 +287,15 @@ async function executeStandardDeployment(appName, options) {
   const appExists = await checkApplicationExists(appName, controllerUrl, config.envKey, config.auth);
 
   const { manifest, manifestPath } = await generateAndValidateManifest(appName);
+  if (options.imageOverride || options.image) {
+    manifest.image = options.imageOverride || options.image;
+  }
+  if (options.registryMode) {
+    manifest.registryMode = options.registryMode;
+  }
+
+  validateImageIsPullable(manifest.image, appName);
+
   displayDeploymentInfo(manifest, manifestPath);
 
   try {
@@ -489,6 +363,7 @@ async function deployApp(appName, options = {}) {
 module.exports = {
   pushApp,
   deployApp,
-  validateAppName
+  validateAppName,
+  validateImageIsPullable
 };
 

package/lib/app/register.js

@@ -48,17 +48,18 @@ function buildRegistrationData(appConfig, options) {
       registrationData.externalIntegration = appConfig.externalIntegration;
     }
   } else {
-    // For non-external types: include registryMode, port, image
-    registrationData.registryMode = appConfig.registryMode;
+    // For non-external types: include registryMode, port, image (options override when provided)
+    registrationData.registryMode = options.registryMode ?? appConfig.registryMode;
 
     // Port is required for non-external types
     if (appConfig.port) {
       registrationData.port = appConfig.port;
     }
 
-    // Image is required for non-external types
-    if (appConfig.image) {
-      registrationData.image = appConfig.image;
+    // Image is required for non-external types (options.imageOverride overrides appConfig.image)
+    const imageValue = options.imageOverride ?? options.image ?? appConfig.image;
+    if (imageValue) {
+      registrationData.image = imageValue;
     }
 
     // URL: always set when we have port so controller DB has it. Precedence: --url, variables (app.url, deployment.dataplaneUrl, deployment.appUrl), else http://localhost:{localPort|port}

package/lib/app/run-helpers.js

@@ -26,6 +26,7 @@ const { waitForHealthCheck } = require('../utils/health-check');
 const composeGenerator = require('../utils/compose-generator');
 const dockerUtils = require('../utils/docker');
 const containerHelpers = require('../utils/app-run-containers');
+const pathsUtil = require('../utils/paths');
 
 const execAsync = promisify(exec);
 
@@ -41,11 +42,12 @@ const stopAndRemoveContainer = containerHelpers.stopAndRemoveContainer;
  */
 function checkBuilderDirectory(appName) {
   const currentDir = process.cwd();
-  const normalizedPath = currentDir.replace(/\\/g, '/');
-  const expectedBuilderPath = `builder/${appName}`;
+  const expectedAppDir = pathsUtil.getBuilderPath(appName);
+  const normalizedCurrent = path.resolve(currentDir).replace(/\\/g, '/');
+  const normalizedExpected = path.resolve(expectedAppDir).replace(/\\/g, '/');
 
-  if (normalizedPath.endsWith(expectedBuilderPath)) {
-    const projectRoot = path.resolve(currentDir, '../..');
+  if (normalizedCurrent === normalizedExpected) {
+    const projectRoot = path.resolve(expectedAppDir, '../..');
     throw new Error(
       'You\'re running from inside the builder directory.\n' +
       `Current directory: ${currentDir}\n` +
@@ -58,19 +60,20 @@ function checkBuilderDirectory(appName) {
 
 /**
  * Load and validate config file exists
+ * Uses paths.getBuilderPath so AIFABRIX_BUILDER_DIR (e.g. from up-miso) is respected.
  * @param {string} appName - Application name
  * @returns {Object} Application configuration
  * @throws {Error} If config file not found
  */
 function loadAppConfig(appName) {
   const currentDir = process.cwd();
-  const configPath = path.join(currentDir, 'builder', appName, 'variables.yaml');
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const configPath = path.join(builderPath, 'variables.yaml');
   if (!fsSync.existsSync(configPath)) {
-    const expectedDir = path.join(currentDir, 'builder', appName);
     throw new Error(
       `Application configuration not found: ${configPath}\n` +
       `Current directory: ${currentDir}\n` +
-      `Expected location: ${expectedDir}\n` +
+      `Expected location: ${builderPath}\n` +
       'Make sure you\'re running from the project root (where \'builder\' directory exists)\n' +
       `Run 'aifabrix create ${appName}' first if configuration doesn't exist`
     );
@@ -194,14 +197,15 @@ async function ensureDevDirectory(appName, developerId) {
  * @async
  * @param {string} appName - Application name
  * @param {string} builderEnvPath - Path to builder .env file
+ * @param {boolean} [skipOutputPath=false] - When true, skip copying to envOutputPath (e.g. up-miso/up-dataplane, no local code)
  */
-async function ensureEnvFile(appName, builderEnvPath) {
+async function ensureEnvFile(appName, builderEnvPath, skipOutputPath = false) {
   if (!fsSync.existsSync(builderEnvPath)) {
     logger.log(chalk.yellow('Generating .env file from template...'));
-    await secrets.generateEnvFile(appName, null, 'docker');
+    await secrets.generateEnvFile(appName, null, 'docker', false, skipOutputPath);
   } else {
     logger.log(chalk.blue('Updating .env file for Docker environment...'));
-    await secrets.generateEnvFile(appName, null, 'docker');
+    await secrets.generateEnvFile(appName, null, 'docker', false, skipOutputPath);
   }
 }
 
@@ -224,9 +228,10 @@ async function copyEnvToDev(builderEnvPath, devEnvPath) {
  * @param {string} variablesPath - Path to variables.yaml
  * @param {string} builderEnvPath - Path to builder .env file
  * @param {string} devEnvPath - Path to dev .env file
+ * @param {boolean} [skipOutputPath=false] - When true, skip (e.g. up-miso/up-dataplane, no local code)
  */
-async function handleEnvOutputPath(appName, variablesPath, builderEnvPath, devEnvPath) {
-  if (!fsSync.existsSync(variablesPath)) {
+async function handleEnvOutputPath(appName, variablesPath, builderEnvPath, devEnvPath, skipOutputPath = false) {
+  if (skipOutputPath || !fsSync.existsSync(variablesPath)) {
     return;
   }
 
@@ -284,18 +289,19 @@ async function generateComposeFile(appName, appConfig, composeOptions, devDir) {
 async function prepareEnvironment(appName, appConfig, options) {
   const developerId = await config.getDeveloperId();
   const devDir = await ensureDevDirectory(appName, developerId);
+  const skipEnvOutputPath = options.skipEnvOutputPath === true;
 
-  // Generate/update .env file
-  const builderEnvPath = path.join(process.cwd(), 'builder', appName, '.env');
-  await ensureEnvFile(appName, builderEnvPath);
+  // Generate/update .env file (respect AIFABRIX_BUILDER_DIR when set by up-miso/up-dataplane)
+  const builderEnvPath = path.join(pathsUtil.getBuilderPath(appName), '.env');
+  await ensureEnvFile(appName, builderEnvPath, skipEnvOutputPath);
 
   // Copy .env to dev directory
   const devEnvPath = path.join(devDir, '.env');
   await copyEnvToDev(builderEnvPath, devEnvPath);
 
-  // Handle envOutputPath if configured
+  // Handle envOutputPath if configured (skipped when skipEnvOutputPath e.g. up-miso/up-dataplane)
   const variablesPath = path.join(devDir, 'variables.yaml');
-  await handleEnvOutputPath(appName, variablesPath, builderEnvPath, devEnvPath);
+  await handleEnvOutputPath(appName, variablesPath, builderEnvPath, devEnvPath, skipEnvOutputPath);
 
   // Generate Docker Compose
   const composeOptions = { ...options };

package/lib/cli.js

@@ -29,6 +29,8 @@ const { handleSecretsSet } = require('./commands/secrets-set');
 const { handleAuthConfig } = require('./commands/auth-config');
 const { setupAppCommands: setupAppManagementCommands } = require('./commands/app');
 const { setupDatasourceCommands } = require('./commands/datasource');
+const { handleUpMiso } = require('./commands/up-miso');
+const { handleUpDataplane } = require('./commands/up-dataplane');
 
 /**
  * Sets up authentication commands
@@ -152,6 +154,34 @@ function setupInfraCommands(program) {
       }
     });
 
+  program.command('up-miso')
+    .description('Install keycloak and miso-controller from images (no build). Infra must be up. Uses auto-generated secrets for testing.')
+    .option('-r, --registry <url>', 'Override registry for both apps (e.g. myacr.azurecr.io)')
+    .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
+    .option('-i, --image <key>=<value>', 'Override image (e.g. keycloak=myreg/keycloak:v1, miso-controller=myreg/m:v1); can be repeated', (v, prev) => (prev || []).concat([v]))
+    .action(async(options) => {
+      try {
+        await handleUpMiso(options);
+      } catch (error) {
+        handleCommandError(error, 'up-miso');
+        process.exit(1);
+      }
+    });
+
+  program.command('up-dataplane')
+    .description('Register and deploy dataplane app in dev (requires login, environment must be dev)')
+    .option('-r, --registry <url>', 'Override registry for dataplane image')
+    .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
+    .option('-i, --image <ref>', 'Override dataplane image reference (e.g. myreg/dataplane:latest)')
+    .action(async(options) => {
+      try {
+        await handleUpDataplane(options);
+      } catch (error) {
+        handleCommandError(error, 'up-dataplane');
+        process.exit(1);
+      }
+    });
+
   program.command('down [app]')
     .description('Stop and remove local infrastructure services or a specific application')
     .option('-v, --volumes', 'Remove volumes (deletes all data)')
@@ -397,7 +427,7 @@ function setupAppCommands(program) {
     .description('Build container image (auto-detects runtime)')
     .option('-l, --language <lang>', 'Override language detection')
     .option('-f, --force-template', 'Force rebuild from template')
-    .option('-t, --tag <tag>', 'Image tag (default: latest)')
+    .option('-t, --tag <tag>', 'Image tag (default: latest). Set image.tag in variables.yaml to match for deploy.')
     .action(async(appName, options) => {
       try {
         const imageTag = await app.buildApp(appName, options);

package/lib/commands/logout.js

@@ -16,11 +16,10 @@ const {
   clearClientToken,
   clearAllClientTokens,
   clearClientTokensForEnvironment,
-  normalizeControllerUrl
+  normalizeControllerUrl,
+  CONFIG_FILE
 } = require('../core/config');
 const logger = require('../utils/logger');
-const os = require('os');
-const path = require('path');
 
 /**
  * Validate environment key format
@@ -144,7 +143,7 @@ async function clearClientTokens(options) {
  * @throws {Error} If logout fails or options are invalid
  */
 async function handleLogout(options) {
-  const configPath = path.join(os.homedir(), '.aifabrix', 'config.yaml');
+  const configPath = CONFIG_FILE;
   logger.log(chalk.blue('\n🔓 Clearing authentication tokens...\n'));
 
   // Validate options

package/lib/commands/up-common.js

@@ -0,0 +1,72 @@
+/**
+ * AI Fabrix Builder - Up Commands Shared Helpers
+ *
+ * Shared logic for up-miso and up-dataplane (ensure app from template).
+ *
+ * @fileoverview Shared helpers for up-miso and up-dataplane commands
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const fs = require('fs');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const pathsUtil = require('../utils/paths');
+const { copyTemplateFiles } = require('../validation/template');
+
+/**
+ * Copy template to a target path if variables.yaml is missing there.
+ * @param {string} appName - Application name
+ * @param {string} targetAppPath - Target directory (e.g. builder/keycloak)
+ * @returns {Promise<boolean>} True if template was copied, false if already present
+ */
+async function ensureTemplateAtPath(appName, targetAppPath) {
+  const variablesPath = path.join(targetAppPath, 'variables.yaml');
+  if (fs.existsSync(variablesPath)) {
+    return false;
+  }
+  await copyTemplateFiles(appName, targetAppPath);
+  return true;
+}
+
+/**
+ * Ensures builder app directory exists from template if variables.yaml is missing.
+ * If builder/<appName>/variables.yaml does not exist, copies from templates/applications/<appName>.
+ * Uses AIFABRIX_BUILDER_DIR when set (e.g. by up-miso/up-dataplane from config aifabrix-env-config).
+ * When using a custom builder dir, also populates cwd/builder/<appName> so the repo's builder/ is not empty.
+ *
+ * @async
+ * @function ensureAppFromTemplate
+ * @param {string} appName - Application name (keycloak, miso-controller, dataplane)
+ * @returns {Promise<boolean>} True if template was copied (in either location), false if both already existed
+ * @throws {Error} If template copy fails
+ *
+ * @example
+ * await ensureAppFromTemplate('keycloak');
+ */
+async function ensureAppFromTemplate(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('Application name is required and must be a string');
+  }
+
+  const appPath = pathsUtil.getBuilderPath(appName);
+  const primaryCopied = await ensureTemplateAtPath(appName, appPath);
+  if (primaryCopied) {
+    logger.log(chalk.blue(`Creating builder/${appName} from template...`));
+    logger.log(chalk.green(`✓ Copied template for ${appName}`));
+  }
+
+  const cwdBuilderPath = path.join(process.cwd(), 'builder', appName);
+  if (path.resolve(cwdBuilderPath) !== path.resolve(appPath)) {
+    const cwdCopied = await ensureTemplateAtPath(appName, cwdBuilderPath);
+    if (cwdCopied) {
+      logger.log(chalk.blue(`Creating builder/${appName} in project (from template)...`));
+      logger.log(chalk.green(`✓ Copied template for ${appName} into builder/`));
+    }
+  }
+
+  return primaryCopied;
+}
+
+module.exports = { ensureAppFromTemplate };