@aifabrix/builder 2.0.7 → 2.1.0

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

@@ -281,11 +281,11 @@ async function startContainer(appName, composePath, port, config = null) {
   await execAsync(`docker-compose -f "${composePath}" up -d`, { env });
   logger.log(chalk.green(`✓ Container aifabrix-${appName} started`));
 
-  // Wait for health check - detect actual mapped port from Docker
-  // Don't pass port so waitForHealthCheck will auto-detect it from container
+  // 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, null, config);
+  await waitForHealthCheck(appName, 90, port, config);
 }
 
 /**
@@ -343,7 +343,8 @@ async function runApp(appName, options = {}) {
     }
 
     // Check port availability
-    const port = options.port || config.build?.localPort || config.port || 3000;
+    // Host port: CLI --port if provided, otherwise port from variables.yaml (NOT localPort)
+    const port = options.port || config.port || 3000;
     const portAvailable = await checkPortAvailable(port);
     if (!portAvailable) {
       throw new Error(`Port ${port} is already in use. Try --port <alternative>`);

package/lib/secrets.js

@@ -257,6 +257,22 @@ async function generateEnvFile(appName, secretsPath, environment = 'local', forc
   const resolved = await resolveKvReferences(template, secrets, environment, resolvedSecretsPath);
 
   fs.writeFileSync(envPath, resolved, { mode: 0o600 });
+
+  // Update PORT variable in container .env file to use port (from variables.yaml)
+  // Note: containerPort is ONLY used for Docker Compose port mapping, NOT for PORT env variable
+  // The application inside container listens on PORT env variable, which should be 'port' from variables.yaml
+  if (fs.existsSync(variablesPath)) {
+    const variablesContent = fs.readFileSync(variablesPath, 'utf8');
+    const variables = yaml.load(variablesContent);
+    const port = variables.port || 3000;
+
+    // Update PORT in container .env file to use port (NOT containerPort, NOT localPort)
+    let envContent = fs.readFileSync(envPath, 'utf8');
+    envContent = envContent.replace(/^PORT\s*=\s*.*$/m, `PORT=${port}`);
+    fs.writeFileSync(envPath, envContent, { mode: 0o600 });
+  }
+
+  // Process and copy to envOutputPath if configured (uses localPort for copied file)
   processEnvVariables(envPath, variablesPath);
 
   return envPath;

package/lib/utils/compose-generator.js

@@ -110,10 +110,9 @@ function buildServiceConfig(appName, config, port) {
   // Container port: build.containerPort > config.port
   const containerPortValue = config.build?.containerPort || config.port || port;
 
-  // Host port: use options.port if provided (CLI --port), otherwise use config.port
-  // Container port: use containerPort if exists, otherwise port
+  // Host port: use port parameter (already calculated from CLI --port or config.port in generateDockerCompose)
   // Note: build.localPort is ONLY used for .env file PORT variable (for local PC dev), NOT for Docker Compose
-  const hostPort = port !== config.port ? port : (config.port || port);
+  const hostPort = port;
 
   return {
     app: buildAppConfig(appName, config),

package/lib/utils/health-check.js

@@ -171,9 +171,9 @@ async function checkHealthEndpoint(healthCheckUrl) {
 async function waitForHealthCheck(appName, timeout = 90, port = null, config = null) {
   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);
 
   const healthCheckPath = config?.healthCheck?.path || '/health';
   const healthCheckUrl = `http://localhost:${healthCheckPort}${healthCheckPath}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "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}})
+