@aifabrix/builder 2.0.8 → 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/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.8",
+  "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}})
+