@aifabrix/builder 2.22.2 → 2.31.0

package/lib/app-readme.js

@@ -44,11 +44,21 @@ function formatAppDisplayName(appName) {
  * Loads and compiles README.md template
  * @returns {Function} Compiled Handlebars template
  * @throws {Error} If template not found
+ * @private
  */
-function loadReadmeTemplate() {
-  const templatePath = path.join(__dirname, '..', 'templates', 'applications', 'README.md.hbs');
+function _loadReadmeTemplate() {
+  // Use getProjectRoot to reliably find templates in all environments
+  const { getProjectRoot } = require('./utils/paths');
+  const projectRoot = getProjectRoot();
+  const templatePath = path.join(projectRoot, 'templates', 'applications', 'README.md.hbs');
+
   if (!fsSync.existsSync(templatePath)) {
-    throw new Error(`README template not found at ${templatePath}`);
+    // Provide helpful error message with actual paths checked
+    const errorMessage = `README template not found at ${templatePath}\n` +
+      `  Project root: ${projectRoot}\n` +
+      `  Templates directory: ${path.join(projectRoot, 'templates', 'applications')}\n` +
+      `  Global PROJECT_ROOT: ${typeof global !== 'undefined' && global.PROJECT_ROOT ? global.PROJECT_ROOT : 'not set'}`;
+    throw new Error(errorMessage);
   }
 
   const templateContent = fsSync.readFileSync(templatePath, 'utf8');
@@ -62,7 +72,6 @@ function loadReadmeTemplate() {
  * @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;
@@ -88,7 +97,116 @@ function generateReadmeMd(appName, config) {
     hasAnyService
   };
 
-  return template(context);
+  // Always generate comprehensive README programmatically to ensure consistency
+  // regardless of template file content
+  return generateComprehensiveReadme(context);
+}
+
+/**
+ * Generates comprehensive README.md content programmatically
+ * @param {Object} context - Template context
+ * @returns {string} Comprehensive README.md content
+ */
+function generateComprehensiveReadme(context) {
+  const { appName, displayName, imageName, port, registry, hasDatabase, hasRedis, hasStorage, hasAuthentication, hasAnyService } = context;
+
+  let prerequisites = 'Before running this application, ensure the following prerequisites are met:\n';
+  prerequisites += '- `@aifabrix/builder` installed globally\n';
+  prerequisites += '- Docker Desktop running\n';
+
+  if (hasAnyService) {
+    if (hasDatabase) {
+      prerequisites += '- PostgreSQL database\n';
+    }
+    if (hasRedis) {
+      prerequisites += '- Redis\n';
+    }
+    if (hasStorage) {
+      prerequisites += '- File storage configured\n';
+    }
+    if (hasAuthentication) {
+      prerequisites += '- Authentication/RBAC configured\n';
+    }
+  } else {
+    prerequisites += '- Infrastructure running\n';
+  }
+
+  let troubleshooting = '';
+  if (hasDatabase) {
+    troubleshooting = `### Database Connection Issues
+
+If you encounter database connection errors, ensure:
+- PostgreSQL is running and accessible
+- Database credentials are correctly configured in your \`.env\` file
+- The database name matches your configuration
+- Verify infrastructure is running and PostgreSQL is accessible`;
+  } else {
+    troubleshooting = 'Verify infrastructure is running.';
+  }
+
+  return `# ${displayName} Builder
+
+Build, run, and deploy ${displayName}.
+
+## Prerequisites
+
+${prerequisites}
+
+## Quick Start
+
+### 1. Install
+
+Install the AI Fabrix Builder CLI if you haven't already.
+
+### 2. Configure
+
+Configure your application settings in \`variables.yaml\`.
+
+### 3. Build & Run Locally
+
+Build the application:
+\`\`\`bash
+aifabrix build ${appName}
+\`\`\`
+
+Run the application:
+\`\`\`bash
+aifabrix run ${appName}
+\`\`\`
+
+The application will be available at http://localhost:${port} (default: ${port}).
+
+### 4. Deploy to Azure
+
+Push to registry:
+\`\`\`bash
+aifabrix push ${appName} --registry ${registry} --tag "v1.0.0,latest"
+\`\`\`
+
+## Configuration
+
+- **Port**: ${port} (default: 3000)
+- **Image**: ${imageName}:latest
+- **Registry**: ${registry}
+
+## Docker Commands
+
+View logs:
+\`\`\`bash
+docker logs aifabrix-${appName} -f
+\`\`\`
+
+Stop the application:
+\`\`\`bash
+aifabrix down ${appName}
+\`\`\`
+
+## Troubleshooting
+
+${troubleshooting}
+
+For more information, see the [AI Fabrix Builder documentation](https://docs.aifabrix.com).
+`;
 }
 
 /**

package/lib/app-rotate-secret.js

@@ -20,6 +20,36 @@ const { updateEnvTemplate } = require('./utils/env-template');
 const { getEnvironmentPrefix } = require('./app-register');
 const { generateEnvFile } = require('./secrets');
 
+/**
+ * Find device token from config by trying each stored URL
+ * @async
+ * @param {Object} deviceConfig - Device configuration object
+ * @returns {Promise<Object|null>} Token result with token and controllerUrl, or null if not found
+ */
+async function findDeviceTokenFromConfig(deviceConfig) {
+  const deviceUrls = Object.keys(deviceConfig);
+  if (deviceUrls.length === 0) {
+    return null;
+  }
+
+  for (const storedUrl of deviceUrls) {
+    try {
+      const normalizedStoredUrl = normalizeControllerUrl(storedUrl);
+      const deviceToken = await getOrRefreshDeviceToken(normalizedStoredUrl);
+      if (deviceToken && deviceToken.token) {
+        return {
+          token: deviceToken.token,
+          controllerUrl: deviceToken.controller || normalizedStoredUrl
+        };
+      }
+    } catch (error) {
+      // Continue to next URL
+    }
+  }
+
+  return null;
+}
+
 /**
  * Validate environment parameter
  * @param {string} environment - Environment ID or key
@@ -79,21 +109,14 @@ function displayRotationResults(appKey, environment, credentials, apiUrl, messag
 }
 
 /**
- * Rotate secret for an application
+ * Get authentication token for rotation
  * @async
- * @param {string} appKey - Application key
- * @param {Object} options - Command options
- * @param {string} options.environment - Environment ID or key
- * @param {string} [options.controller] - Controller URL (optional, uses configured controller if not provided)
- * @throws {Error} If rotation fails
+ * @param {string} [controllerUrl] - Optional controller URL
+ * @param {Object} config - Configuration object
+ * @returns {Promise<Object>} Object with token and actualControllerUrl
+ * @throws {Error} If authentication fails
  */
-async function rotateSecret(appKey, options) {
-  logger.log(chalk.yellow('⚠️  This will invalidate the old ClientSecret!\n'));
-
-  const config = await getConfig();
-
-  // Get controller URL with priority: options.controller > device tokens
-  const controllerUrl = options.controller || null;
+async function getRotationAuthToken(controllerUrl, config) {
   let token = null;
   let actualControllerUrl = null;
 
@@ -107,7 +130,6 @@ async function rotateSecret(appKey, options) {
         actualControllerUrl = deviceToken.controller || normalizedUrl;
       }
     } catch (error) {
-      // Show which controller URL failed
       logger.error(chalk.red(`❌ Failed to authenticate with controller: ${controllerUrl}`));
       logger.error(chalk.gray(`Error: ${error.message}`));
       process.exit(1);
@@ -116,21 +138,10 @@ async function rotateSecret(appKey, options) {
 
   // If no token yet, try to find any device token in config
   if (!token && config.device) {
-    const deviceUrls = Object.keys(config.device);
-    if (deviceUrls.length > 0) {
-      for (const storedUrl of deviceUrls) {
-        try {
-          const normalizedStoredUrl = normalizeControllerUrl(storedUrl);
-          const deviceToken = await getOrRefreshDeviceToken(normalizedStoredUrl);
-          if (deviceToken && deviceToken.token) {
-            token = deviceToken.token;
-            actualControllerUrl = deviceToken.controller || normalizedStoredUrl;
-            break;
-          }
-        } catch (error) {
-          // Continue to next URL
-        }
-      }
+    const tokenResult = await findDeviceTokenFromConfig(config.device);
+    if (tokenResult) {
+      token = tokenResult.token;
+      actualControllerUrl = tokenResult.controllerUrl;
     }
   }
 
@@ -143,6 +154,65 @@ async function rotateSecret(appKey, options) {
     process.exit(1);
   }
 
+  return { token, actualControllerUrl };
+}
+
+/**
+ * Save credentials locally and update env files
+ * @async
+ * @param {string} appKey - Application key
+ * @param {Object} credentials - Credentials object
+ * @param {string} actualControllerUrl - Controller URL
+ * @throws {Error} If saving fails
+ */
+async function saveCredentialsLocally(appKey, credentials, actualControllerUrl) {
+  const clientIdKey = `${appKey}-client-idKeyVault`;
+  const clientSecretKey = `${appKey}-client-secretKeyVault`;
+
+  try {
+    await saveLocalSecret(clientIdKey, credentials.clientId);
+    await saveLocalSecret(clientSecretKey, credentials.clientSecret);
+
+    // Update env.template if localhost
+    if (isLocalhost(actualControllerUrl)) {
+      await updateEnvTemplate(appKey, clientIdKey, clientSecretKey, actualControllerUrl);
+
+      // Regenerate .env file with updated credentials
+      try {
+        await generateEnvFile(appKey, null, 'local');
+        logger.log(chalk.green('✓ .env file updated with new credentials'));
+      } catch (error) {
+        logger.warn(chalk.yellow(`⚠️  Could not regenerate .env file: ${error.message}`));
+      }
+
+      logger.log(chalk.green('\n✓ Credentials saved to ~/.aifabrix/secrets.local.yaml'));
+      logger.log(chalk.green('✓ env.template updated with MISO_CLIENTID, MISO_CLIENTSECRET, and MISO_CONTROLLER_URL\n'));
+    } else {
+      logger.log(chalk.green('\n✓ Credentials saved to ~/.aifabrix/secrets.local.yaml\n'));
+    }
+  } catch (error) {
+    logger.warn(chalk.yellow(`⚠️  Could not save credentials locally: ${error.message}`));
+  }
+}
+
+/**
+ * Rotate secret for an application
+ * @async
+ * @param {string} appKey - Application key
+ * @param {Object} options - Command options
+ * @param {string} options.environment - Environment ID or key
+ * @param {string} [options.controller] - Controller URL (optional, uses configured controller if not provided)
+ * @throws {Error} If rotation fails
+ */
+async function rotateSecret(appKey, options) {
+  logger.log(chalk.yellow('⚠️  This will invalidate the old ClientSecret!\n'));
+
+  const config = await getConfig();
+
+  // Get authentication token
+  const controllerUrl = options.controller || null;
+  const { token, actualControllerUrl } = await getRotationAuthToken(controllerUrl, config);
+
   // Validate environment
   validateEnvironment(options.environment);
 
@@ -164,34 +234,8 @@ async function rotateSecret(appKey, options) {
     const credentials = response.data.credentials;
     const message = response.data.message;
 
-    // Save credentials to local secrets (always save when rotating)
-    const clientIdKey = `${appKey}-client-idKeyVault`;
-    const clientSecretKey = `${appKey}-client-secretKeyVault`;
-
-    try {
-      await saveLocalSecret(clientIdKey, credentials.clientId);
-      await saveLocalSecret(clientSecretKey, credentials.clientSecret);
-
-      // Update env.template if localhost
-      if (isLocalhost(actualControllerUrl)) {
-        await updateEnvTemplate(appKey, clientIdKey, clientSecretKey, actualControllerUrl);
-
-        // Regenerate .env file with updated credentials
-        try {
-          await generateEnvFile(appKey, null, 'local');
-          logger.log(chalk.green('✓ .env file updated with new credentials'));
-        } catch (error) {
-          logger.warn(chalk.yellow(`⚠️  Could not regenerate .env file: ${error.message}`));
-        }
-
-        logger.log(chalk.green('\n✓ Credentials saved to ~/.aifabrix/secrets.local.yaml'));
-        logger.log(chalk.green('✓ env.template updated with MISO_CLIENTID, MISO_CLIENTSECRET, and MISO_CONTROLLER_URL\n'));
-      } else {
-        logger.log(chalk.green('\n✓ Credentials saved to ~/.aifabrix/secrets.local.yaml\n'));
-      }
-    } catch (error) {
-      logger.warn(chalk.yellow(`⚠️  Could not save credentials locally: ${error.message}`));
-    }
+    // Save credentials locally
+    await saveCredentialsLocally(appKey, credentials, actualControllerUrl);
 
     // Display results
     displayRotationResults(appKey, options.environment, credentials, actualControllerUrl, message);