@aifabrix/builder 2.22.2 → 2.31.1

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
@@ -31,20 +61,83 @@ function validateEnvironment(environment) {
   }
 }
 
+/**
+ * Validate credentials object structure
+ * @param {Object} credentials - Credentials object to validate
+ * @returns {boolean} True if credentials are valid
+ */
+function isValidCredentials(credentials) {
+  return credentials &&
+    typeof credentials === 'object' &&
+    typeof credentials.clientId === 'string' &&
+    typeof credentials.clientSecret === 'string';
+}
+
+/**
+ * Extract credentials from API response
+ * Handles multiple response formats:
+ * 1. Direct format: { success: true, data: { credentials: {...} } }
+ * 2. Wrapped format: { success: true, data: { success: true, data: { credentials: {...} } } }
+ * @param {Object} response - API response from centralized API client
+ * @returns {Object|null} Object with credentials and message, or null if not found
+ */
+function extractCredentials(response) {
+  // Note: response.data is already validated in validateResponse
+  const apiResponse = response.data;
+
+  // Try wrapped format first: response.data.data.credentials
+  if (apiResponse.data && apiResponse.data.credentials) {
+    const credentials = apiResponse.data.credentials;
+    if (isValidCredentials(credentials)) {
+      return {
+        credentials: credentials,
+        message: apiResponse.data.message || apiResponse.message
+      };
+    }
+  }
+
+  // Try direct format: response.data.credentials
+  if (apiResponse.credentials) {
+    const credentials = apiResponse.credentials;
+    if (isValidCredentials(credentials)) {
+      return {
+        credentials: credentials,
+        message: apiResponse.message
+      };
+    }
+  }
+
+  return null;
+}
+
 /**
  * Validate API response structure
  * @param {Object} response - API response
+ * @returns {Object} Object with credentials and message
  * @throws {Error} If response structure is invalid
  */
 function validateResponse(response) {
   if (!response.data || typeof response.data !== 'object') {
+    logger.error(chalk.red('❌ Invalid response: missing data'));
+    logger.error(chalk.gray('\nAPI response type:'), typeof response.data);
+    logger.error(chalk.gray('API response:'), JSON.stringify(response.data, null, 2));
+    logger.error(chalk.gray('\nFull response for debugging:'));
+    logger.error(chalk.gray(JSON.stringify(response, null, 2)));
     throw new Error('Invalid response: missing data');
   }
 
-  const credentials = response.data.credentials;
-  if (!credentials || typeof credentials !== 'object' || typeof credentials.clientId !== 'string' || typeof credentials.clientSecret !== 'string') {
+  const result = extractCredentials(response);
+
+  if (!result) {
+    logger.error(chalk.red('❌ Invalid response: missing or invalid credentials'));
+    logger.error(chalk.gray('\nAPI response type:'), typeof response.data);
+    logger.error(chalk.gray('API response:'), JSON.stringify(response.data, null, 2));
+    logger.error(chalk.gray('\nFull response for debugging:'));
+    logger.error(chalk.gray(JSON.stringify(response, null, 2)));
     throw new Error('Invalid response: missing or invalid credentials');
   }
+
+  return result;
 }
 
 /**
@@ -79,69 +172,135 @@ function displayRotationResults(appKey, environment, credentials, apiUrl, messag
 }
 
 /**
- * Rotate secret for an application
+ * Get device token from provided controller URL
  * @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 - Controller URL
+ * @returns {Promise<Object|null>} Object with token and controllerUrl, or null if failed
  */
-async function rotateSecret(appKey, options) {
-  logger.log(chalk.yellow('⚠️  This will invalidate the old ClientSecret!\n'));
+async function getTokenFromUrl(controllerUrl) {
+  try {
+    const normalizedUrl = normalizeControllerUrl(controllerUrl);
+    const deviceToken = await getOrRefreshDeviceToken(normalizedUrl);
+    if (deviceToken && deviceToken.token) {
+      return {
+        token: deviceToken.token,
+        controllerUrl: deviceToken.controller || normalizedUrl
+      };
+    }
+  } catch (error) {
+    logger.error(chalk.red(`❌ Failed to authenticate with controller: ${controllerUrl}`));
+    logger.error(chalk.gray(`Error: ${error.message}`));
+    process.exit(1);
+  }
+  return null;
+}
 
-  const config = await getConfig();
+/**
+ * Validate and handle missing authentication token
+ * @param {string|null} token - Authentication token
+ * @param {string|null} controllerUrl - Controller URL
+ * @param {string} [providedUrl] - Original provided URL for error context
+ */
+function validateAuthToken(token, controllerUrl, providedUrl) {
+  if (!token || !controllerUrl) {
+    const formattedError = formatAuthenticationError({
+      controllerUrl: providedUrl || undefined,
+      message: 'No valid authentication found'
+    });
+    logger.error(formattedError);
+    process.exit(1);
+  }
+}
 
-  // Get controller URL with priority: options.controller > device tokens
-  const controllerUrl = options.controller || null;
+/**
+ * Get authentication token for rotation
+ * @async
+ * @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 getRotationAuthToken(controllerUrl, config) {
   let token = null;
   let actualControllerUrl = null;
 
   // If controller URL provided, try to get device token
   if (controllerUrl) {
-    try {
-      const normalizedUrl = normalizeControllerUrl(controllerUrl);
-      const deviceToken = await getOrRefreshDeviceToken(normalizedUrl);
-      if (deviceToken && deviceToken.token) {
-        token = deviceToken.token;
-        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);
+    const tokenResult = await getTokenFromUrl(controllerUrl);
+    if (tokenResult) {
+      token = tokenResult.token;
+      actualControllerUrl = tokenResult.controllerUrl;
     }
   }
 
   // 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;
     }
   }
 
-  if (!token || !actualControllerUrl) {
-    const formattedError = formatAuthenticationError({
-      controllerUrl: controllerUrl || undefined,
-      message: 'No valid authentication found'
-    });
-    logger.error(formattedError);
-    process.exit(1);
+  validateAuthToken(token, actualControllerUrl, controllerUrl);
+  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);
@@ -158,40 +317,11 @@ async function rotateSecret(appKey, options) {
       process.exit(1);
     }
 
-    // Validate response structure
-    validateResponse(response);
+    // Validate response structure and extract credentials
+    const { credentials, message } = validateResponse(response);
 
-    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);