@aifabrix/builder 2.0.8 → 2.1.1

package/lib/app-config.js

@@ -13,6 +13,7 @@ const path = require('path');
 const chalk = require('chalk');
 const { generateVariablesYaml, generateEnvTemplate, generateRbacYaml } = require('./templates');
 const { generateEnvTemplate: generateEnvTemplateFromReader } = require('./env-reader');
+const { generateReadmeMdFile } = require('./app-readme');
 const logger = require('./utils/logger');
 
 /**
@@ -146,6 +147,7 @@ async function generateConfigFiles(appPath, appName, config, existingEnv) {
     await generateEnvTemplateFile(appPath, config, existingEnv);
     await generateRbacYamlFile(appPath, appName, config);
     await generateDeployJsonFile(appPath, appName, config);
+    await generateReadmeMdFile(appPath, appName, config);
   } catch (error) {
     throw new Error(`Failed to generate configuration files: ${error.message}`);
   }

package/lib/app-readme.js

@@ -0,0 +1,107 @@
+/**
+ * Application README.md Generation
+ *
+ * Generates README.md files for applications based on configuration
+ *
+ * @fileoverview README.md generation for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const path = require('path');
+const handlebars = require('handlebars');
+
+/**
+ * Checks if a file exists
+ * @async
+ * @param {string} filePath - Path to file
+ * @returns {Promise<boolean>} True if file exists
+ */
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Formats application name for display (capitalize first letter of each word)
+ * @param {string} appName - Application name
+ * @returns {string} Formatted display name
+ */
+function formatAppDisplayName(appName) {
+  return appName
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * Loads and compiles README.md template
+ * @returns {Function} Compiled Handlebars template
+ * @throws {Error} If template not found
+ */
+function loadReadmeTemplate() {
+  const templatePath = path.join(__dirname, '..', 'templates', 'applications', 'README.md.hbs');
+  if (!fsSync.existsSync(templatePath)) {
+    throw new Error(`README template not found at ${templatePath}`);
+  }
+
+  const templateContent = fsSync.readFileSync(templatePath, 'utf8');
+  return handlebars.compile(templateContent);
+}
+
+/**
+ * Generates README.md content for an application using Handlebars template
+ * @param {string} appName - Application name
+ * @param {Object} config - Application configuration
+ * @returns {string} README.md content
+ */
+function generateReadmeMd(appName, config) {
+  const template = loadReadmeTemplate();
+  const displayName = formatAppDisplayName(appName);
+  const imageName = `aifabrix/${appName}`;
+  const port = config.port || 3000;
+
+  const context = {
+    appName,
+    displayName,
+    imageName,
+    port,
+    hasDatabase: config.database || false,
+    hasRedis: config.redis || false,
+    hasStorage: config.storage || false,
+    hasAuthentication: config.authentication || false
+  };
+
+  return template(context);
+}
+
+/**
+ * Generates README.md file if it doesn't exist
+ * @async
+ * @function generateReadmeMdFile
+ * @param {string} appPath - Path to application directory
+ * @param {string} appName - Application name
+ * @param {Object} config - Application configuration
+ * @returns {Promise<void>} Resolves when README.md is generated or skipped
+ * @throws {Error} If file generation fails
+ */
+async function generateReadmeMdFile(appPath, appName, config) {
+  const readmePath = path.join(appPath, 'README.md');
+  if (!(await fileExists(readmePath))) {
+    const readmeContent = generateReadmeMd(appName, config);
+    await fs.writeFile(readmePath, readmeContent);
+  }
+}
+
+module.exports = {
+  generateReadmeMdFile,
+  generateReadmeMd,
+  formatAppDisplayName
+};
+

package/lib/app-run.js

@@ -30,16 +30,28 @@ const execAsync = promisify(exec);
  * Checks if Docker image exists for the application
  * @param {string} imageName - Image name (can include repository prefix)
  * @param {string} tag - Image tag (default: latest)
+ * @param {boolean} [debug=false] - Enable debug logging
  * @returns {Promise<boolean>} True if image exists
  */
-async function checkImageExists(imageName, tag = 'latest') {
+async function checkImageExists(imageName, tag = 'latest', debug = false) {
   try {
     const fullImageName = `${imageName}:${tag}`;
+    const cmd = `docker images --format "{{.Repository}}:{{.Tag}}" --filter "reference=${fullImageName}"`;
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Executing: ${cmd}`));
+    }
     // Use Docker's native filtering for cross-platform compatibility (Windows-safe)
-    const { stdout } = await execAsync(`docker images --format "{{.Repository}}:{{.Tag}}" --filter "reference=${fullImageName}"`);
+    const { stdout } = await execAsync(cmd);
     const lines = stdout.trim().split('\n').filter(line => line.trim() !== '');
-    return lines.some(line => line.trim() === fullImageName);
+    const exists = lines.some(line => line.trim() === fullImageName);
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Image ${fullImageName} exists: ${exists}`));
+    }
+    return exists;
   } catch (error) {
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Image check failed: ${error.message}`));
+    }
     return false;
   }
 }
@@ -47,13 +59,34 @@ async function checkImageExists(imageName, tag = 'latest') {
 /**
  * Checks if container is already running
  * @param {string} appName - Application name
+ * @param {boolean} [debug=false] - Enable debug logging
  * @returns {Promise<boolean>} True if container is running
  */
-async function checkContainerRunning(appName) {
+async function checkContainerRunning(appName, debug = false) {
   try {
-    const { stdout } = await execAsync(`docker ps --filter "name=aifabrix-${appName}" --format "{{.Names}}"`);
-    return stdout.trim() === `aifabrix-${appName}`;
+    const cmd = `docker ps --filter "name=aifabrix-${appName}" --format "{{.Names}}"`;
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Executing: ${cmd}`));
+    }
+    const { stdout } = await execAsync(cmd);
+    const isRunning = stdout.trim() === `aifabrix-${appName}`;
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Container aifabrix-${appName} running: ${isRunning}`));
+      if (isRunning) {
+        // Get container status details
+        const statusCmd = `docker ps --filter "name=aifabrix-${appName}" --format "{{.Status}}"`;
+        const { stdout: status } = await execAsync(statusCmd);
+        const portsCmd = `docker ps --filter "name=aifabrix-${appName}" --format "{{.Ports}}"`;
+        const { stdout: ports } = await execAsync(portsCmd);
+        logger.log(chalk.gray(`[DEBUG] Container status: ${status.trim()}`));
+        logger.log(chalk.gray(`[DEBUG] Container ports: ${ports.trim()}`));
+      }
+    }
+    return isRunning;
   } catch (error) {
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Container check failed: ${error.message}`));
+    }
     return false;
   }
 }
@@ -61,14 +94,26 @@ async function checkContainerRunning(appName) {
 /**
  * Stops and removes existing container
  * @param {string} appName - Application name
+ * @param {boolean} [debug=false] - Enable debug logging
  */
-async function stopAndRemoveContainer(appName) {
+async function stopAndRemoveContainer(appName, debug = false) {
   try {
     logger.log(chalk.yellow(`Stopping existing container aifabrix-${appName}...`));
-    await execAsync(`docker stop aifabrix-${appName}`);
-    await execAsync(`docker rm aifabrix-${appName}`);
+    const stopCmd = `docker stop aifabrix-${appName}`;
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Executing: ${stopCmd}`));
+    }
+    await execAsync(stopCmd);
+    const rmCmd = `docker rm aifabrix-${appName}`;
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Executing: ${rmCmd}`));
+    }
+    await execAsync(rmCmd);
     logger.log(chalk.green(`✓ Container aifabrix-${appName} stopped and removed`));
   } catch (error) {
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Stop/remove container error: ${error.message}`));
+    }
     // Container might not exist, which is fine
     logger.log(chalk.gray(`Container aifabrix-${appName} was not running`));
   }
@@ -180,17 +225,22 @@ async function validateAppConfiguration(appName) {
  * @async
  * @param {string} appName - Application name
  * @param {Object} config - Application configuration
+ * @param {boolean} [debug=false] - Enable debug logging
  * @throws {Error} If prerequisites are not met
  */
-async function checkPrerequisites(appName, config) {
+async function checkPrerequisites(appName, config, debug = false) {
   // Extract image name from configuration (same logic as build process)
   const imageName = getImageName(config, appName);
   const imageTag = config.image?.tag || 'latest';
   const fullImageName = `${imageName}:${imageTag}`;
 
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Image name: ${imageName}, tag: ${imageTag}`));
+  }
+
   // Check if Docker image exists
   logger.log(chalk.blue(`Checking if image ${fullImageName} exists...`));
-  const imageExists = await checkImageExists(imageName, imageTag);
+  const imageExists = await checkImageExists(imageName, imageTag, debug);
   if (!imageExists) {
     throw new Error(`Docker image ${fullImageName} not found\nRun 'aifabrix build ${appName}' first`);
   }
@@ -199,6 +249,9 @@ async function checkPrerequisites(appName, config) {
   // Check infrastructure health
   logger.log(chalk.blue('Checking infrastructure health...'));
   const infraHealth = await infra.checkInfraHealth();
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Infrastructure health: ${JSON.stringify(infraHealth, null, 2)}`));
+  }
   const unhealthyServices = Object.entries(infraHealth)
     .filter(([_, status]) => status !== 'healthy')
     .map(([service, _]) => service);
@@ -258,13 +311,18 @@ async function prepareEnvironment(appName, config, options) {
  * @param {string} appName - Application name
  * @param {string} composePath - Path to Docker Compose file
  * @param {number} port - Application port
+ * @param {Object} config - Application configuration
+ * @param {boolean} [debug=false] - Enable debug logging
  * @throws {Error} If container fails to start or become healthy
  */
-async function startContainer(appName, composePath, port, config = null) {
+async function startContainer(appName, composePath, port, config = null, debug = false) {
   logger.log(chalk.blue(`Starting ${appName}...`));
 
   // Ensure ADMIN_SECRETS_PATH is set for db-init service
   const adminSecretsPath = await infra.ensureAdminSecrets();
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Admin secrets path: ${adminSecretsPath}`));
+  }
 
   // Load POSTGRES_PASSWORD from admin-secrets.env
   const adminSecretsContent = fsSync.readFileSync(adminSecretsPath, 'utf8');
@@ -278,14 +336,33 @@ async function startContainer(appName, composePath, port, config = null) {
     POSTGRES_PASSWORD: postgresPassword
   };
 
-  await execAsync(`docker-compose -f "${composePath}" up -d`, { env });
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Environment variables: ADMIN_SECRETS_PATH=${adminSecretsPath}, POSTGRES_PASSWORD=${postgresPassword ? '***' : '(not set)'}`));
+  }
+
+  const composeCmd = `docker-compose -f "${composePath}" up -d`;
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Executing: ${composeCmd}`));
+    logger.log(chalk.gray(`[DEBUG] Compose file: ${composePath}`));
+  }
+  await execAsync(composeCmd, { env });
   logger.log(chalk.green(`✓ Container aifabrix-${appName} started`));
 
+  if (debug) {
+    // Get container status after start
+    const statusCmd = `docker ps --filter "name=aifabrix-${appName}" --format "{{.Status}}"`;
+    const { stdout: status } = await execAsync(statusCmd);
+    const portsCmd = `docker ps --filter "name=aifabrix-${appName}" --format "{{.Ports}}"`;
+    const { stdout: ports } = await execAsync(portsCmd);
+    logger.log(chalk.gray(`[DEBUG] Container status: ${status.trim()}`));
+    logger.log(chalk.gray(`[DEBUG] Container ports: ${ports.trim()}`));
+  }
+
   // Wait for health check using host port
   // Port is the host port (CLI --port or config.port, NOT localPort)
   const healthCheckPath = config?.healthCheck?.path || '/health';
   logger.log(chalk.blue(`Waiting for application to be healthy at http://localhost:${port}${healthCheckPath}...`));
-  await waitForHealthCheck(appName, 90, port, config);
+  await waitForHealthCheck(appName, 90, port, config, debug);
 }
 
 /**
@@ -320,6 +397,7 @@ function displayRunStatus(appName, port, config) {
  * @param {string} appName - Name of the application to run
  * @param {Object} options - Run options
  * @param {number} [options.port] - Override local port
+ * @param {boolean} [options.debug] - Enable debug output
  * @returns {Promise<void>} Resolves when app is running
  * @throws {Error} If run fails or app is not built
  *
@@ -328,34 +406,53 @@ function displayRunStatus(appName, port, config) {
  * // Application is now running on localhost:3001
  */
 async function runApp(appName, options = {}) {
+  const debug = options.debug || false;
+
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Starting run process for: ${appName}`));
+    logger.log(chalk.gray(`[DEBUG] Options: ${JSON.stringify(options, null, 2)}`));
+  }
+
   try {
     // Validate app name and load configuration
     const config = await validateAppConfiguration(appName);
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Configuration loaded: port=${config.port || 'default'}, healthCheck.path=${config.healthCheck?.path || '/health'}`));
+    }
 
     // Check prerequisites: image and infrastructure
-    await checkPrerequisites(appName, config);
+    await checkPrerequisites(appName, config, debug);
 
     // Check if container is already running
-    const containerRunning = await checkContainerRunning(appName);
+    const containerRunning = await checkContainerRunning(appName, debug);
     if (containerRunning) {
       logger.log(chalk.yellow(`Container aifabrix-${appName} is already running`));
-      await stopAndRemoveContainer(appName);
+      await stopAndRemoveContainer(appName, debug);
     }
 
     // Check port availability
     // Host port: CLI --port if provided, otherwise port from variables.yaml (NOT localPort)
     const port = options.port || config.port || 3000;
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Port selection: ${port} (${options.port ? 'CLI override' : config.port ? 'config.port' : 'default'})`));
+    }
     const portAvailable = await checkPortAvailable(port);
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Port ${port} available: ${portAvailable}`));
+    }
     if (!portAvailable) {
       throw new Error(`Port ${port} is already in use. Try --port <alternative>`);
     }
 
     // Prepare environment: ensure .env file and generate Docker Compose
     const tempComposePath = await prepareEnvironment(appName, config, options);
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Compose file generated: ${tempComposePath}`));
+    }
 
     try {
       // Start container and wait for health check
-      await startContainer(appName, tempComposePath, port, config);
+      await startContainer(appName, tempComposePath, port, config, debug);
 
       // Display success message
       displayRunStatus(appName, port, config);
@@ -364,10 +461,16 @@ async function runApp(appName, options = {}) {
       // Keep the compose file for debugging - don't delete on error
       logger.log(chalk.yellow(`\n⚠️  Compose file preserved at: ${tempComposePath}`));
       logger.log(chalk.yellow('   Review the file to debug issues'));
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Error during container start: ${error.message}`));
+      }
       throw error;
     }
 
   } catch (error) {
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Run failed: ${error.message}`));
+    }
     throw new Error(`Failed to run application: ${error.message}`);
   }
 }

package/lib/app.js

@@ -361,6 +361,7 @@ async function generateDockerfile(appPath, language, config) {
  * @param {string} appName - Name of the application to run
  * @param {Object} options - Run options
  * @param {number} [options.port] - Override local port
+ * @param {boolean} [options.debug] - Enable debug output
  * @returns {Promise<void>} Resolves when app is running
  * @throws {Error} If run fails or app is not built
  *

package/lib/cli.js

@@ -111,6 +111,7 @@ function setupCommands(program) {
   program.command('run <app>')
     .description('Run application locally')
     .option('-p, --port <port>', 'Override local port')
+    .option('-d, --debug', 'Enable debug output with detailed container information')
     .action(async(appName, options) => {
       try {
         await app.runApp(appName, options);

package/lib/schema/application-schema.json

@@ -284,7 +284,7 @@
     },
     "healthCheck": {
       "type": "object",
-      "description": "Health check configuration",
+      "description": "Health check configuration. The health check endpoint must return HTTP 200 and a JSON response with one of the following formats: {\"status\": \"UP\"} (Keycloak format), {\"status\": \"ok\"} (standard format, optionally with {\"database\": \"connected\"}), {\"status\": \"healthy\"} (alternative format), or {\"success\": true} (success-based format). For non-JSON responses, HTTP 200 status code is sufficient.",
       "required": ["path", "interval"],
       "properties": {
         "path": {
@@ -320,7 +320,51 @@
           "maximum": 600
         }
       },
-      "additionalProperties": false
+      "additionalProperties": false,
+      "examples": [
+        {
+          "path": "/health",
+          "interval": 30
+        },
+        {
+          "path": "/api/health",
+          "interval": 60,
+          "probePath": "/api/health",
+          "probeRequestType": "GET",
+          "probeProtocol": "Http",
+          "probeIntervalInSeconds": 120
+        }
+      ],
+      "responseFormats": {
+        "description": "Valid health check response formats",
+        "formats": [
+          {
+            "format": "Keycloak",
+            "example": "{\"status\": \"UP\", \"checks\": []}",
+            "validation": "status === 'UP'"
+          },
+          {
+            "format": "Standard",
+            "example": "{\"status\": \"ok\", \"database\": \"connected\"}",
+            "validation": "status === 'ok' && (database === 'connected' || !database)"
+          },
+          {
+            "format": "Alternative",
+            "example": "{\"status\": \"healthy\", \"service\": \"dataplane\"}",
+            "validation": "status === 'healthy'"
+          },
+          {
+            "format": "Success-based",
+            "example": "{\"success\": true, \"message\": \"Service is running\"}",
+            "validation": "success === true"
+          },
+          {
+            "format": "Non-JSON",
+            "example": "OK",
+            "validation": "HTTP status code === 200"
+          }
+        ]
+      }
     },
     "frontDoorRouting": {
       "type": "object",

package/lib/utils/health-check.js

@@ -67,37 +67,61 @@ async function waitForDbInit(appName) {
  * @async
  * @function getContainerPort
  * @param {string} appName - Application name
+ * @param {boolean} [debug=false] - Enable debug logging
  * @returns {Promise<number>} Container port
  */
-async function getContainerPort(appName) {
+async function getContainerPort(appName, debug = false) {
   try {
     // Try to get the actual mapped host port from Docker
     // First try docker inspect for the container port mapping
-    const { stdout: portMapping } = await execAsync(`docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}}{{if $conf}}{{range $conf}}{{.HostPort}}{{end}}{{end}}{{end}}' aifabrix-${appName}`);
+    const inspectCmd = `docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}}{{if $conf}}{{range $conf}}{{.HostPort}}{{end}}{{end}}{{end}}' aifabrix-${appName}`;
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Executing: ${inspectCmd}`));
+    }
+    const { stdout: portMapping } = await execAsync(inspectCmd);
     const ports = portMapping.trim().split('\n').filter(p => p && p !== '');
     if (ports.length > 0) {
       const port = parseInt(ports[0], 10);
       if (!isNaN(port) && port > 0) {
+        if (debug) {
+          logger.log(chalk.gray(`[DEBUG] Detected port ${port} from docker inspect`));
+        }
         return port;
       }
     }
 
     // Fallback: try docker ps to get port mapping (format: "0.0.0.0:3010->3000/tcp")
     try {
-      const { stdout: psOutput } = await execAsync(`docker ps --filter "name=aifabrix-${appName}" --format "{{.Ports}}"`);
+      const psCmd = `docker ps --filter "name=aifabrix-${appName}" --format "{{.Ports}}"`;
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Fallback: Executing: ${psCmd}`));
+      }
+      const { stdout: psOutput } = await execAsync(psCmd);
       const portMatch = psOutput.match(/:(\d+)->/);
       if (portMatch) {
         const port = parseInt(portMatch[1], 10);
         if (!isNaN(port) && port > 0) {
+          if (debug) {
+            logger.log(chalk.gray(`[DEBUG] Detected port ${port} from docker ps`));
+          }
           return port;
         }
       }
     } catch (error) {
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Fallback port detection failed: ${error.message}`));
+      }
       // Fall through
     }
   } catch (error) {
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Port detection failed: ${error.message}`));
+    }
     // Fall through to default
   }
+  if (debug) {
+    logger.log(chalk.gray('[DEBUG] Using default port 3000'));
+  }
   return 3000;
 }
 
@@ -117,6 +141,12 @@ function parseHealthResponse(data, statusCode) {
     if (health.status === 'ok') {
       return health.database === 'connected' || !health.database;
     }
+    if (health.status === 'healthy') {
+      return true;
+    }
+    if (health.success === true) {
+      return true;
+    }
     return false;
   } catch (error) {
     return statusCode === 200;
@@ -128,27 +158,68 @@ function parseHealthResponse(data, statusCode) {
  * @async
  * @function checkHealthEndpoint
  * @param {string} healthCheckUrl - Health check URL
+ * @param {boolean} [debug=false] - Enable debug logging
  * @returns {Promise<boolean>} True if healthy
  * @throws {Error} If request fails with exception
  */
-async function checkHealthEndpoint(healthCheckUrl) {
+async function checkHealthEndpoint(healthCheckUrl, debug = false) {
   return new Promise((resolve, reject) => {
     try {
-      const req = http.get(healthCheckUrl, { timeout: 5000 }, (res) => {
+      const urlObj = new URL(healthCheckUrl);
+      const options = {
+        hostname: urlObj.hostname,
+        port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
+        path: urlObj.pathname + urlObj.search,
+        method: 'GET',
+        timeout: 5000
+      };
+
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Health check request: ${healthCheckUrl}`));
+        logger.log(chalk.gray(`[DEBUG] Request options: ${JSON.stringify(options, null, 2)}`));
+      }
+
+      const req = http.request(options, (res) => {
         let data = '';
+        if (debug) {
+          logger.log(chalk.gray(`[DEBUG] Response status code: ${res.statusCode}`));
+          logger.log(chalk.gray(`[DEBUG] Response headers: ${JSON.stringify(res.headers, null, 2)}`));
+        }
         res.on('data', (chunk) => {
           data += chunk;
         });
         res.on('end', () => {
-          resolve(parseHealthResponse(data, res.statusCode));
+          if (debug) {
+            const truncatedData = data.length > 200 ? data.substring(0, 200) + '...' : data;
+            logger.log(chalk.gray(`[DEBUG] Response body: ${truncatedData}`));
+          }
+          const isHealthy = parseHealthResponse(data, res.statusCode);
+          if (debug) {
+            logger.log(chalk.gray(`[DEBUG] Health check result: ${isHealthy ? 'healthy' : 'unhealthy'}`));
+          }
+          resolve(isHealthy);
         });
       });
-      req.on('error', () => resolve(false));
+
+      req.on('error', (error) => {
+        if (debug) {
+          logger.log(chalk.gray(`[DEBUG] Health check request error: ${error.message}`));
+        }
+        resolve(false);
+      });
       req.on('timeout', () => {
+        if (debug) {
+          logger.log(chalk.gray('[DEBUG] Health check request timeout after 5 seconds'));
+        }
         req.destroy();
         resolve(false);
       });
+
+      req.end();
     } catch (error) {
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Health check exception: ${error.message}`));
+      }
       // Re-throw exceptions (not just network errors)
       reject(error);
     }
@@ -165,28 +236,47 @@ async function checkHealthEndpoint(healthCheckUrl) {
  * @param {number} timeout - Timeout in seconds (default: 90)
  * @param {number} [port] - Application port (auto-detected if not provided)
  * @param {Object} [config] - Application configuration
+ * @param {boolean} [debug=false] - Enable debug logging
  * @returns {Promise<void>} Resolves when health check passes
  * @throws {Error} If health check times out
  */
-async function waitForHealthCheck(appName, timeout = 90, port = null, config = null) {
+async function waitForHealthCheck(appName, timeout = 90, port = null, config = null, debug = false) {
   await waitForDbInit(appName);
 
-  // Always detect the actual port from Docker to ensure we use the correct mapped port
-  const detectedPort = await getContainerPort(appName);
-  const healthCheckPort = port || detectedPort;
+  // Use provided port if given, otherwise detect from Docker
+  // Port provided should be the host port (CLI --port or config.port, NOT localPort)
+  const healthCheckPort = port !== null && port !== undefined ? port : await getContainerPort(appName, debug);
+
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Health check port: ${healthCheckPort} (${port !== null && port !== undefined ? 'provided' : 'auto-detected'})`));
+  }
 
   const healthCheckPath = config?.healthCheck?.path || '/health';
   const healthCheckUrl = `http://localhost:${healthCheckPort}${healthCheckPath}`;
   const maxAttempts = timeout / 2;
 
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Health check URL: ${healthCheckUrl}`));
+    logger.log(chalk.gray(`[DEBUG] Timeout: ${timeout} seconds, Max attempts: ${maxAttempts}`));
+  }
+
   for (let attempts = 0; attempts < maxAttempts; attempts++) {
     try {
-      const healthCheckPassed = await checkHealthEndpoint(healthCheckUrl);
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Health check attempt ${attempts + 1}/${maxAttempts}`));
+      }
+      const healthCheckPassed = await checkHealthEndpoint(healthCheckUrl, debug);
       if (healthCheckPassed) {
         logger.log(chalk.green('✓ Application is healthy'));
+        if (debug) {
+          logger.log(chalk.gray(`[DEBUG] Health check passed after ${attempts + 1} attempt(s)`));
+        }
         return;
       }
     } catch (error) {
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Health check exception on attempt ${attempts + 1}: ${error.message}`));
+      }
       // If exception occurs, continue retrying until timeout
       // The error will be handled by timeout error below
     }
@@ -197,10 +287,14 @@ async function waitForHealthCheck(appName, timeout = 90, port = null, config = n
     }
   }
 
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Health check failed after ${maxAttempts} attempts`));
+  }
   throw new Error(`Health check timeout after ${timeout} seconds`);
 }
 
 module.exports = {
-  waitForHealthCheck
+  waitForHealthCheck,
+  checkHealthEndpoint
 };
 

package/package.json

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

package/templates/applications/README.md.hbs

@@ -0,0 +1,70 @@
+# {{displayName}} Builder
+
+Build, run, and deploy {{displayName}} using `@aifabrix/builder`.
+
+## Install
+
+```bash
+npm install -g @aifabrix/builder
+```
+
+## Build
+
+```bash
+aifabrix build {{appName}}
+```
+
+Builds Docker image: `{{imageName}}:latest`
+
+## Run Locally
+
+```bash
+aifabrix run {{appName}}
+```
+
+**Access:** http://localhost:{{port}}
+
+**Logs:**
+```bash
+docker logs {{appName}} -f
+```
+
+**Stop:**
+```bash
+docker stop {{appName}}
+```
+
+## Push to Azure Container Registry
+
+```bash
+aifabrix push {{appName}} --action acr --tag latest
+```
+
+**Note:** ACR push requires `az login` or ACR credentials in `variables.yaml`
+
+## Prerequisites
+
+- `@aifabrix/builder` installed globally
+- Docker Desktop running
+- Infrastructure running (`aifabrix up`)
+{{#if hasDatabase}}
+- PostgreSQL database
+{{/if}}
+{{#if hasRedis}}
+- Redis
+{{/if}}
+{{#if hasStorage}}
+- File storage configured
+{{/if}}
+{{#if hasAuthentication}}
+- Authentication/RBAC configured
+{{/if}}
+
+## Troubleshooting
+
+**Build fails:** Check Docker is running and `variables.yaml` → `build.secrets` path is correct
+
+**Can't connect:** Verify infrastructure is running (`aifabrix up`){{#if hasDatabase}} and PostgreSQL is accessible{{/if}}
+
+**Port in use:** Change `build.localPort` in `variables.yaml` (default: {{port}})
+