@aifabrix/builder 2.3.0 → 2.3.3

package/lib/config.js

@@ -35,10 +35,24 @@ async function getConfig() {
       config = {};
     }
 
-    // Ensure developerId defaults to 0 if not set
-    if (typeof config['developer-id'] === 'undefined') {
-      config['developer-id'] = 0;
+    // Ensure developer-id exists as a digit-only string (default "0") and validate
+    const DEV_ID_DIGITS_REGEX = /^[0-9]+$/;
+    if (typeof config['developer-id'] === 'undefined' || config['developer-id'] === null) {
+      config['developer-id'] = '0';
+    } else if (typeof config['developer-id'] === 'number') {
+      // Convert numeric to string to preserve type consistency
+      if (config['developer-id'] < 0 || !Number.isFinite(config['developer-id'])) {
+        throw new Error(`Invalid developer-id value: "${config['developer-id']}". Must be a non-negative digit string.`);
+      }
+      config['developer-id'] = String(config['developer-id']);
+    } else if (typeof config['developer-id'] === 'string') {
+      if (!DEV_ID_DIGITS_REGEX.test(config['developer-id'])) {
+        throw new Error(`Invalid developer-id value: "${config['developer-id']}". Must contain only digits 0-9.`);
+      }
+    } else {
+      throw new Error(`Invalid developer-id value type: ${typeof config['developer-id']}. Must be a non-negative digit string.`);
     }
+
     // Ensure environment defaults to 'dev' if not set
     if (typeof config.environment === 'undefined') {
       config.environment = 'dev';
@@ -51,15 +65,15 @@ async function getConfig() {
     if (typeof config.device !== 'object' || config.device === null) {
       config.device = {};
     }
-    // Cache developer ID as property for easy access (use nullish coalescing to allow 0)
-    cachedDeveloperId = config['developer-id'] !== undefined ? config['developer-id'] : 0;
+    // Cache developer ID as property for easy access (string, default "0")
+    cachedDeveloperId = config['developer-id'] !== undefined ? config['developer-id'] : '0';
     return config;
   } catch (error) {
     if (error.code === 'ENOENT') {
-      // Default developer ID is 0, default environment is 'dev'
-      cachedDeveloperId = 0;
+      // Default developer ID is "0", default environment is 'dev'
+      cachedDeveloperId = '0';
       return {
-        'developer-id': 0,
+        'developer-id': '0',
         environment: 'dev',
         environments: {},
         device: {}
@@ -80,7 +94,8 @@ async function saveConfig(data) {
     await fs.mkdir(CONFIG_DIR, { recursive: true });
 
     // Set secure permissions
-    const configContent = yaml.dump(data);
+    // Force quotes to ensure numeric-like strings (e.g., "01") remain strings in YAML
+    const configContent = yaml.dump(data, { forceQuotes: true });
     // Write file first
     await fs.writeFile(CONFIG_FILE, configContent, {
       mode: 0o600,
@@ -117,7 +132,7 @@ async function clearConfig() {
  * Get developer ID from configuration
  * Loads config if not already cached, then returns cached developer ID
  * Developer ID: 0 = default infra, > 0 = developer-specific
- * @returns {Promise<number>} Developer ID (defaults to 0)
+ * @returns {Promise<string>} Developer ID as string (defaults to "0")
  */
 async function getDeveloperId() {
   // Always reload from file to ensure we have the latest value
@@ -130,21 +145,33 @@ async function getDeveloperId() {
 
 /**
  * Set developer ID in configuration
- * @param {number} developerId - Developer ID to set (0 = default infra, > 0 = developer-specific)
+ * @param {number|string} developerId - Developer ID to set (digit-only string preserved, or number). "0" = default infra, > "0" = developer-specific
  * @returns {Promise<void>}
  */
 async function setDeveloperId(developerId) {
-  if (typeof developerId !== 'number' || developerId < 0) {
-    throw new Error('Developer ID must be a non-negative number (0 = default infra, > 0 = developer-specific)');
+  const DEV_ID_DIGITS_REGEX = /^[0-9]+$/;
+  let devIdString;
+  if (typeof developerId === 'number') {
+    if (!Number.isFinite(developerId) || developerId < 0) {
+      throw new Error('Developer ID must be a non-negative digit string or number (0 = default infra, > 0 = developer-specific)');
+    }
+    devIdString = String(developerId);
+  } else if (typeof developerId === 'string') {
+    if (!DEV_ID_DIGITS_REGEX.test(developerId)) {
+      throw new Error('Developer ID must be a non-negative digit string or number (0 = default infra, > 0 = developer-specific)');
+    }
+    devIdString = developerId;
+  } else {
+    throw new Error('Developer ID must be a non-negative digit string or number (0 = default infra, > 0 = developer-specific)');
   }
   // Clear cache first to ensure we get fresh data from file
   cachedDeveloperId = null;
   // Read file directly to avoid any caching issues
   const config = await getConfig();
   // Update developer ID
-  config['developer-id'] = developerId;
+  config['developer-id'] = devIdString;
   // Update cache before saving
-  cachedDeveloperId = developerId;
+  cachedDeveloperId = devIdString;
   // Save the entire config object to ensure all fields are preserved
   await saveConfig(config);
   // Verify the file was saved correctly by reading it back
@@ -154,8 +181,10 @@ async function setDeveloperId(developerId) {
   // Read file again with fresh file handle to avoid OS caching
   const savedContent = await fs.readFile(CONFIG_FILE, 'utf8');
   const savedConfig = yaml.load(savedContent);
-  if (savedConfig['developer-id'] !== developerId) {
-    throw new Error(`Failed to save developer ID: expected ${developerId}, got ${savedConfig['developer-id']}. File content: ${savedContent.substring(0, 200)}`);
+  // YAML may parse numbers as numbers, so convert to string for comparison
+  const savedDevIdString = String(savedConfig['developer-id']);
+  if (savedDevIdString !== devIdString) {
+    throw new Error(`Failed to save developer ID: expected ${devIdString}, got ${savedDevIdString}. File content: ${savedContent.substring(0, 200)}`);
   }
   // Clear the cache to force reload from file on next getDeveloperId() call
   // This ensures we get the value that was actually saved to disk
@@ -288,7 +317,7 @@ async function saveClientToken(environment, appName, controllerUrl, token, expir
 /**
  * Initialize and load developer ID
  * Call this to ensure developerId is loaded and cached
- * @returns {Promise<number>} Developer ID
+ * @returns {Promise<string>} Developer ID (string)
  */
 async function loadDeveloperId() {
   if (cachedDeveloperId === null) {
@@ -379,7 +408,7 @@ const exportsObj = {
 // Developer ID: 0 = default infra, > 0 = developer-specific
 Object.defineProperty(exportsObj, 'developerId', {
   get() {
-    return cachedDeveloperId !== null ? cachedDeveloperId : 0; // Default to 0 if not loaded yet
+    return cachedDeveloperId !== null ? cachedDeveloperId : '0'; // Default to "0" if not loaded yet
   },
   enumerable: true,
   configurable: true

package/lib/infra.js

@@ -20,6 +20,7 @@ const config = require('./config');
 const devConfig = require('./utils/dev-config');
 const logger = require('./utils/logger');
 const containerUtils = require('./utils/infra-containers');
+const dockerUtils = require('./utils/docker');
 
 // Register Handlebars helper for equality check
 handlebars.registerHelper('eq', (a, b) => a === b);
@@ -28,21 +29,23 @@ const execAsync = promisify(exec);
 /**
  * Gets infrastructure directory name based on developer ID
  * Dev 0: infra (no dev-0 suffix), Dev > 0: infra-dev{id}
- * @param {number} devId - Developer ID
+ * @param {number|string} devId - Developer ID
  * @returns {string} Infrastructure directory name
  */
 function getInfraDirName(devId) {
-  return devId === 0 ? 'infra' : `infra-dev${devId}`;
+  const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
+  return idNum === 0 ? 'infra' : `infra-dev${devId}`;
 }
 
 /**
  * Gets Docker Compose project name based on developer ID
  * Dev 0: infra (no dev-0 suffix), Dev > 0: infra-dev{id}
- * @param {number} devId - Developer ID
+ * @param {number|string} devId - Developer ID
  * @returns {string} Docker Compose project name
  */
 function getInfraProjectName(devId) {
-  return devId === 0 ? 'infra' : `infra-dev${devId}`;
+  const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
+  return idNum === 0 ? 'infra' : `infra-dev${devId}`;
 }
 
 // Wrapper to support cwd option
@@ -74,8 +77,7 @@ function execAsyncWithCwd(command, options = {}) {
  */
 async function checkDockerAvailability() {
   try {
-    await execAsync('docker --version');
-    await execAsync('docker-compose --version');
+    await dockerUtils.ensureDockerAndCompose();
   } catch (error) {
     throw new Error('Docker or Docker Compose is not available. Please install and start Docker.');
   }
@@ -96,7 +98,10 @@ async function startInfra(developerId = null) {
 
   // Get developer ID from parameter or config
   const devId = developerId || await config.getDeveloperId();
-  const ports = devConfig.getDevPorts(devId);
+  // Convert to number for getDevPorts (it expects numbers)
+  const devIdNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
+  const ports = devConfig.getDevPorts(devIdNum);
+  const idNum = devIdNum;
 
   // Load compose template (Handlebars)
   const templatePath = path.join(__dirname, '..', 'templates', 'infra', 'compose.yaml.hbs');
@@ -116,7 +121,7 @@ async function startInfra(developerId = null) {
   const templateContent = fs.readFileSync(templatePath, 'utf8');
   const template = handlebars.compile(templateContent);
   // Dev 0: infra-aifabrix-network, Dev > 0: infra-dev{id}-aifabrix-network
-  const networkName = devId === 0 ? 'infra-aifabrix-network' : `infra-dev${devId}-aifabrix-network`;
+  const networkName = idNum === 0 ? 'infra-aifabrix-network' : `infra-dev${devId}-aifabrix-network`;
   const composeContent = template({
     devId: devId,
     postgresPort: ports.postgres,
@@ -133,7 +138,8 @@ async function startInfra(developerId = null) {
     logger.log(`Using compose file: ${composePath}`);
     logger.log(`Starting infrastructure services for developer ${devId}...`);
     const projectName = getInfraProjectName(devId);
-    await execAsyncWithCwd(`docker-compose -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" up -d`, { cwd: infraDir });
+    const composeCmd = await dockerUtils.getComposeCommand();
+    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" up -d`, { cwd: infraDir });
     logger.log('Infrastructure services started successfully');
 
     await waitForServices(devId);
@@ -172,7 +178,8 @@ async function stopInfra() {
   try {
     logger.log('Stopping infrastructure services...');
     const projectName = getInfraProjectName(devId);
-    await execAsyncWithCwd(`docker-compose -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" down`, { cwd: infraDir });
+    const composeCmd = await dockerUtils.getComposeCommand();
+    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" down`, { cwd: infraDir });
     logger.log('Infrastructure services stopped');
   } finally {
     // Keep the compose file for future use
@@ -208,7 +215,8 @@ async function stopInfraWithVolumes() {
   try {
     logger.log('Stopping infrastructure services and removing all data...');
     const projectName = getInfraProjectName(devId);
-    await execAsyncWithCwd(`docker-compose -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" down -v`, { cwd: infraDir });
+    const composeCmd = await dockerUtils.getComposeCommand();
+    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" down -v`, { cwd: infraDir });
     logger.log('Infrastructure services stopped and all data removed');
   } finally {
     // Keep the compose file for future use
@@ -261,7 +269,9 @@ async function checkInfraHealth(devId = null) {
  */
 async function getInfraStatus() {
   const devId = await config.getDeveloperId();
-  const ports = devConfig.getDevPorts(devId);
+  // Convert string developer ID to number for getDevPorts
+  const devIdNum = parseInt(devId, 10);
+  const ports = devConfig.getDevPorts(devIdNum);
   const services = {
     postgres: { port: ports.postgres, url: `localhost:${ports.postgres}` },
     redis: { port: ports.redis, url: `localhost:${ports.redis}` },
@@ -340,7 +350,8 @@ async function restartService(serviceName) {
   try {
     logger.log(`Restarting ${serviceName} service...`);
     const projectName = getInfraProjectName(devId);
-    await execAsyncWithCwd(`docker-compose -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" restart ${serviceName}`, { cwd: infraDir });
+    const composeCmd = await dockerUtils.getComposeCommand();
+    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" restart ${serviceName}`, { cwd: infraDir });
     logger.log(`${serviceName} service restarted successfully`);
   } finally {
     // Keep the compose file for future use

package/lib/secrets.js

@@ -357,7 +357,9 @@ async function generateEnvFile(appName, secretsPath, environment = 'local', forc
   // For local environment, update infrastructure ports to use dev-specific ports
   if (environment === 'local') {
     const devId = await config.getDeveloperId();
-    const ports = devConfig.getDevPorts(devId);
+    // Convert string developer ID to number for getDevPorts
+    const devIdNum = parseInt(devId, 10);
+    const ports = devConfig.getDevPorts(devIdNum);
 
     // Update DATABASE_PORT if present
     resolved = resolved.replace(/^DATABASE_PORT\s*=\s*.*$/m, `DATABASE_PORT=${ports.postgres}`);

package/lib/utils/build-copy.js

@@ -22,7 +22,7 @@ const os = require('os');
  * @async
  * @function copyBuilderToDevDirectory
  * @param {string} appName - Application name
- * @param {number} developerId - Developer ID
+ * @param {number|string} developerId - Developer ID
  * @returns {Promise<string>} Path to developer-specific directory
  * @throws {Error} If copying fails
  *
@@ -39,7 +39,8 @@ async function copyBuilderToDevDirectory(appName, developerId) {
   }
 
   // Get base directory (applications or applications-dev-{id})
-  const baseDir = developerId === 0
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const baseDir = idNum === 0
     ? path.join(os.homedir(), '.aifabrix', 'applications')
     : path.join(os.homedir(), '.aifabrix', `applications-dev-${developerId}`);
 
@@ -64,7 +65,7 @@ async function copyBuilderToDevDirectory(appName, developerId) {
   await fs.mkdir(devDir, { recursive: true });
 
   // Copy files based on developer ID
-  if (developerId === 0) {
+  if (idNum === 0) {
     // Dev 0: Copy contents from builder/{appName}/ directly to applications/
     await copyDirectory(builderPath, devDir);
   } else {
@@ -112,11 +113,12 @@ async function copyDirectory(sourceDir, targetDir) {
 /**
  * Gets developer-specific directory path for an application
  * @param {string} appName - Application name
- * @param {number} developerId - Developer ID
+ * @param {number|string} developerId - Developer ID
  * @returns {string} Path to developer-specific directory
  */
 function getDevDirectory(appName, developerId) {
-  if (developerId === 0) {
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  if (idNum === 0) {
     // Dev 0: all apps go directly to applications/ (no subdirectory)
     return path.join(os.homedir(), '.aifabrix', 'applications');
   }

package/lib/utils/compose-generator.js

@@ -307,12 +307,13 @@ async function generateDockerCompose(appName, appConfig, options) {
 
   // Get developer ID and network name
   const devId = await config.getDeveloperId();
+  const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
   // Dev 0: infra-aifabrix-network (no dev-0 suffix)
   // Dev > 0: infra-dev{id}-aifabrix-network
-  const networkName = devId === 0 ? 'infra-aifabrix-network' : `infra-dev${devId}-aifabrix-network`;
+  const networkName = idNum === 0 ? 'infra-aifabrix-network' : `infra-dev${devId}-aifabrix-network`;
   // Dev 0: aifabrix-{appName} (no dev-0 suffix)
   // Dev > 0: aifabrix-dev{id}-{appName}
-  const containerName = devId === 0 ? `aifabrix-${appName}` : `aifabrix-dev${devId}-${appName}`;
+  const containerName = idNum === 0 ? `aifabrix-${appName}` : `aifabrix-dev${devId}-${appName}`;
 
   const serviceConfig = buildServiceConfig(appName, appConfig, port);
   const volumesConfig = buildVolumesConfig(appName);

package/lib/utils/dev-config.js

@@ -27,7 +27,7 @@ const BASE_PORTS = {
  * Developer ID: 0 = default infra (base ports), > 0 = developer-specific (offset ports)
  *
  * @function getDevPorts
- * @param {number} developerId - Developer ID (0 = default infra, 1, 2, 3, etc. = developer-specific)
+ * @param {number} developerId - Developer ID (0 = default infra, 1, 2, 3, etc. = developer-specific). Must be a number.
  * @returns {Object} Object with calculated ports for all services
  *
  * @example
@@ -37,27 +37,28 @@ const BASE_PORTS = {
  * // Returns: { app: 3100, postgres: 5532, redis: 6479, pgadmin: 5150, redisCommander: 8181 }
  */
 function getDevPorts(developerId) {
-  // Validate type first - must be a number
+  // Only accept numbers, reject strings and other types
   if (typeof developerId !== 'number') {
     throw new Error('Developer ID must be a positive number');
   }
 
-  // Handle NaN, undefined, null - throw error (don't default)
-  if (isNaN(developerId) || developerId === undefined || developerId === null) {
+  // Handle invalids
+  if (developerId === undefined || developerId === null || Number.isNaN(developerId)) {
     throw new Error('Developer ID must be a positive number');
   }
-
   if (developerId < 0 || !Number.isInteger(developerId)) {
     throw new Error('Developer ID must be a positive number');
   }
 
+  const idNum = developerId;
+
   // Developer ID 0 = default infra (base ports, no offset)
-  if (developerId === 0) {
+  if (idNum === 0) {
     return { ...BASE_PORTS };
   }
 
   // Developer ID > 0 = developer-specific (add offset)
-  const offset = developerId * 100;
+  const offset = idNum * 100;
 
   return {
     app: BASE_PORTS.app + offset,

package/lib/utils/docker.js

@@ -0,0 +1,73 @@
+/**
+ * Docker CLI Utilities
+ *
+ * Detects availability of Docker and determines the correct Docker Compose command
+ * across environments (Compose v2 plugin: "docker compose", Compose v1: "docker-compose").
+ *
+ * @fileoverview Docker/Compose detection helpers for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { exec } = require('child_process');
+const { promisify } = require('util');
+
+const execAsync = promisify(exec);
+
+/**
+ * Checks that Docker CLI is available.
+ * @async
+ * @function checkDockerCli
+ * @returns {Promise<void>} Resolves if docker is available
+ * @throws {Error} If docker is unavailable
+ */
+async function checkDockerCli() {
+  await execAsync('docker --version');
+}
+
+/**
+ * Determines the correct Docker Compose command on this system.
+ * Tries Docker Compose v2 plugin first: "docker compose", then falls back to v1: "docker-compose".
+ *
+ * @async
+ * @function getComposeCommand
+ * @returns {Promise<string>} The compose command to use ("docker compose" or "docker-compose")
+ * @throws {Error} If neither v2 nor v1 is available
+ */
+async function getComposeCommand() {
+  // Prefer Compose v2 plugin if present
+  try {
+    await execAsync('docker compose version');
+    return 'docker compose';
+  } catch (_) {
+    // Fall back to legacy docker-compose
+  }
+
+  try {
+    await execAsync('docker-compose --version');
+    return 'docker-compose';
+  } catch (_) {
+    throw new Error('Docker Compose is not available (neither "docker compose" nor "docker-compose" found).');
+  }
+}
+
+/**
+ * Ensures Docker and Docker Compose are available, returning the compose command to use.
+ * @async
+ * @function ensureDockerAndCompose
+ * @returns {Promise<string>} The compose command to use
+ * @throws {Error} If docker or compose is not available
+ */
+async function ensureDockerAndCompose() {
+  await checkDockerCli();
+  return await getComposeCommand();
+}
+
+module.exports = {
+  checkDockerCli,
+  getComposeCommand,
+  ensureDockerAndCompose
+};
+

package/lib/utils/environment-checker.js

@@ -12,6 +12,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const dockerUtils = require('./docker');
 
 /**
  * Checks if Docker is installed and available
@@ -22,12 +23,8 @@ const os = require('os');
  */
 async function checkDocker() {
   try {
-    const { exec } = require('child_process');
-    const { promisify } = require('util');
-    const execAsync = promisify(exec);
-
-    await execAsync('docker --version');
-    await execAsync('docker-compose --version');
+    await dockerUtils.checkDockerCli();
+    await dockerUtils.getComposeCommand();
     return 'ok';
   } catch (error) {
     return 'error';

package/lib/utils/infra-containers.js

@@ -20,14 +20,15 @@ const execAsync = promisify(exec);
  * @private
  * @async
  * @param {string} serviceName - Service name
- * @param {number} [devId] - Developer ID (optional, will be loaded from config if not provided)
+ * @param {number|string} [devId] - Developer ID (optional, will be loaded from config if not provided)
  * @returns {Promise<string|null>} Container name or null if not found
  */
 async function findContainer(serviceName, devId = null) {
   try {
     const developerId = devId || await config.getDeveloperId();
+    const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
     // Dev 0: aifabrix-{serviceName}, Dev > 0: aifabrix-dev{id}-{serviceName}
-    const containerNamePattern = developerId === 0
+    const containerNamePattern = idNum === 0
       ? `aifabrix-${serviceName}`
       : `aifabrix-dev${developerId}-${serviceName}`;
     let { stdout } = await execAsync(`docker ps --filter "name=${containerNamePattern}" --format "{{.Names}}"`);