@aifabrix/builder 2.42.0 → 2.43.0

package/lib/cli/setup-utility.js

@@ -163,6 +163,7 @@ function setupRepairCommand(program) {
   program.command('repair <app>')
     .description('Repair external integration config: fix drift (file lists, app key, datasource alignment, rbac, manifest)')
     .option('--auth <method>', 'Set authentication method (oauth2, aad, apikey, basic, queryParam, oidc, hmac, none); updates system file and env.template')
+    .option('--doc', 'Regenerate README.md from deployment manifest')
     .option('--dry-run', 'Report changes only; do not write')
     .option('--rbac', 'Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist')
     .option('--expose', 'Set exposed.attributes on each datasource to all fieldMappings.attributes keys')
@@ -174,9 +175,18 @@ function setupRepairCommand(program) {
         const { detectAppType } = require('../utils/paths');
         const { appPath } = await detectAppType(appName);
         logOfflinePathWhenType(appPath);
+        let format = 'yaml';
+        try {
+          const config = require('../core/config');
+          format = (await config.getFormat()) || format;
+        } catch (_) {
+          // use default yaml when config unavailable
+        }
         const result = await repairExternalIntegration(appName, {
           auth: options.auth,
+          doc: options.doc,
           dryRun: options.dryRun,
+          format,
           rbac: options.rbac,
           expose: options.expose,
           sync: options.sync,
@@ -187,6 +197,8 @@ function setupRepairCommand(program) {
           result.changes.forEach(c => logger.log(chalk.gray(`  ${c}`)));
         } else if (result.updated) {
           logger.log(chalk.green('\n✓ Repaired external integration config.'));
+        } else if (result.readmeRegenerated) {
+          logger.log(chalk.green('\n✓ Regenerated README.md from deployment manifest.'));
         } else {
           logger.log(chalk.gray('No changes needed; config already matches files on disk.'));
         }

package/lib/commands/auth-config.js

@@ -19,34 +19,44 @@ const {
   validateEnvironment,
   checkUserLoggedIn
 } = require('../utils/auth-config-validator');
+const { getControllerUrlFromLoggedInUser } = require('../utils/controller-url');
 const logger = require('../utils/logger');
 
 /**
  * Handle set-controller command
+ * Allows setting the default controller when no credentials are stored, or when already logged in to that controller.
+ * If credentials exist for a different controller, throws with a clear message.
+ *
  * @async
  * @function handleSetController
  * @param {string} url - Controller URL to set
  * @returns {Promise<void>}
- * @throws {Error} If validation fails
+ * @throws {Error} If validation fails or credentials exist for another controller
  */
 async function handleSetController(url) {
   try {
-    // Validate URL format
     validateControllerUrl(url);
+    const normalizedUrl = url.trim().replace(/\/+$/, '');
 
-    // Check if user is logged in to that controller
-    const isLoggedIn = await checkUserLoggedIn(url);
-    if (!isLoggedIn) {
-      throw new Error(
-        `You are not logged in to controller ${url}.\n` +
-        'Please run "aifabrix login" first to authenticate with this controller.'
-      );
+    const loggedInControllerUrl = await getControllerUrlFromLoggedInUser();
+    if (!loggedInControllerUrl) {
+      // No stored credentials: allow setting controller so "aifabrix login" opens the right place
+      await setControllerUrl(url);
+      logger.log(chalk.green(`✓ Controller URL set to: ${url}`));
+      return;
     }
 
-    // Save controller URL
-    await setControllerUrl(url);
+    const normalizedLoggedIn = loggedInControllerUrl.trim().replace(/\/+$/, '');
+    if (normalizedLoggedIn === normalizedUrl) {
+      await setControllerUrl(url);
+      logger.log(chalk.green(`✓ Controller URL set to: ${url}`));
+      return;
+    }
 
-    logger.log(chalk.green(`✓ Controller URL set to: ${url}`));
+    throw new Error(
+      `You have credentials for another controller (${loggedInControllerUrl}).\n` +
+      'To use a different controller either run "aifabrix login" with that controller, or run "aifabrix logout" first to clear credentials, then set the new controller with "aifabrix auth --set-controller <url>".'
+    );
   } catch (error) {
     logger.error(chalk.red(`✗ Failed to set controller URL: ${error.message}`));
     throw error;
@@ -70,8 +80,7 @@ async function handleSetEnvironment(environment) {
     const controllerUrl = await getControllerUrl();
     if (!controllerUrl) {
       throw new Error(
-        'No controller URL found in config.\n' +
-        'Please run "aifabrix login" first to set the controller URL.'
+        'No controller URL found in config. Run "aifabrix login" first, or set the controller with "aifabrix auth --set-controller <url>".'
       );
     }
 
@@ -79,8 +88,7 @@ async function handleSetEnvironment(environment) {
     const isLoggedIn = await checkUserLoggedIn(controllerUrl);
     if (!isLoggedIn) {
       throw new Error(
-        `You are not logged in to controller ${controllerUrl}.\n` +
-        'Please run "aifabrix login" first to authenticate with this controller.'
+        `You are not logged in to controller ${controllerUrl}. Run "aifabrix login" first to authenticate.`
       );
     }
 
@@ -107,9 +115,7 @@ async function handleSetEnvironment(environment) {
 async function handleAuthConfig(options) {
   if (!options.setController && !options.setEnvironment) {
     throw new Error(
-      'No action specified. Use one of:\n' +
-      '  --set-controller <url>\n' +
-      '  --set-environment <env>'
+      'No action specified. Use "aifabrix auth --set-controller <url>" or "aifabrix auth --set-environment <env>".'
     );
   }
   if (options.setController) {

package/lib/commands/datasource.js

@@ -17,6 +17,7 @@ const { compareDatasources } = require('../datasource/diff');
 const { deployDatasource } = require('../datasource/deploy');
 const { runDatasourceTestIntegration } = require('../datasource/test-integration');
 const { runDatasourceTestE2E } = require('../datasource/test-e2e');
+const { runLogViewer } = require('../datasource/log-viewer');
 const { displayIntegrationTestResults, displayE2EResults } = require('../utils/external-system-display');
 
 function setupDatasourceValidateCommand(datasource) {
@@ -81,9 +82,10 @@ function setupDatasourceUploadCommand(datasource) {
 function setupDatasourceTestIntegrationCommand(datasource) {
   datasource.command('test-integration <datasourceKey>')
     .description('Run integration (config) test for one datasource via dataplane pipeline')
-    .option('-a, --app <appKey>', 'App key (default: resolve from cwd if inside integration/<appKey>/)')
+    .option('-a, --app <appKey>', 'App key (optional: resolve from cwd or datasource key if single match)')
     .option('-p, --payload <file>', 'Path to custom test payload file')
     .option('-e, --env <env>', 'Environment: dev, tst, or pro')
+    .option('-v, --verbose', 'Show detailed step and validation output')
     .option('--debug', 'Include debug output and write log to integration/<appKey>/logs/')
     .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
     .action(async(datasourceKey, options) => {
@@ -144,18 +146,61 @@ function setupDatasourceTestE2ECommand(datasource) {
     });
 }
 
+function setupDatasourceLogE2ECommand(datasource) {
+  datasource.command('log-e2e <datasourceKey>')
+    .description('Display latest or specified E2E test log in readable format')
+    .option('-a, --app <appKey>', 'App key (optional: resolve from cwd or datasource key if single match)')
+    .option('-f, --file <path>', 'Path to log file (default: latest in app logs folder)')
+    .action(async(datasourceKey, options) => {
+      try {
+        await runLogViewer(datasourceKey, {
+          app: options.app,
+          file: options.file,
+          logType: 'test-e2e'
+        });
+      } catch (error) {
+        logger.error(chalk.red('❌ log-e2e failed:'), error.message);
+        process.exit(1);
+      }
+    });
+}
+
+function setupDatasourceLogIntegrationCommand(datasource) {
+  datasource.command('log-integration <datasourceKey>')
+    .description('Display latest or specified integration test log in readable format')
+    .option('-a, --app <appKey>', 'App key (optional: resolve from cwd or datasource key if single match)')
+    .option('-f, --file <path>', 'Path to log file (default: latest in app logs folder)')
+    .action(async(datasourceKey, options) => {
+      try {
+        await runLogViewer(datasourceKey, {
+          app: options.app,
+          file: options.file,
+          logType: 'test-integration'
+        });
+      } catch (error) {
+        logger.error(chalk.red('❌ log-integration failed:'), error.message);
+        process.exit(1);
+      }
+    });
+}
+
 /**
  * Setup datasource management commands
  * @param {Command} program - Commander program instance
  */
 function setupDatasourceCommands(program) {
   const datasource = program.command('datasource').description('Manage external data sources');
+  if (typeof datasource.alias === 'function') {
+    datasource.alias('ds');
+  }
   setupDatasourceValidateCommand(datasource);
   setupDatasourceListCommand(datasource);
   setupDatasourceDiffCommand(datasource);
   setupDatasourceUploadCommand(datasource);
   setupDatasourceTestIntegrationCommand(datasource);
   setupDatasourceTestE2ECommand(datasource);
+  setupDatasourceLogE2ECommand(datasource);
+  setupDatasourceLogIntegrationCommand(datasource);
 }
 
 module.exports = { setupDatasourceCommands };

package/lib/commands/dev-init.js

@@ -341,7 +341,7 @@ async function runDevRefresh(options = {}) {
   logger.log(chalk.blue('\n🔄 Fetching settings from Builder Server...\n'));
   const settings = await devApi.getSettings(auth.serverUrl, clientCertPem, clientKeyPem || undefined);
   await config.mergeRemoteSettings(settings);
-  logger.log(chalk.green('✓ Config updated from server. Run "aifabrix dev config" to verify.\n'));
+  logger.log(chalk.green('✓ Config updated from server. Run "aifabrix dev show" to verify.\n'));
 }
 
 module.exports = { runDevInit, runDevRefresh };

package/lib/commands/repair-env-template.js

@@ -11,6 +11,7 @@ const path = require('path');
 const fs = require('fs');
 const { systemKeyToKvPrefix, kvEnvKeyToPath, securityKeyToVar } = require('../utils/credential-secrets-env');
 const { extractEnvTemplate } = require('../generator/split');
+const { generateExternalEnvTemplateContent } = require('../utils/external-env-template');
 
 /**
  * Normalizes a keyvault config entry to canonical KV_* name and path-style value.
@@ -126,20 +127,25 @@ function buildExpectedByKey(effective) {
 }
 
 /**
- * Creates env.template when missing. Returns true if created (and change pushed).
+ * Creates env.template when missing using the Handlebars template (Authentication + Configuration sections).
  * @param {string} envPath - Path to env.template
- * @param {Map<string, string>} expectedByKey - Expected key->line map
+ * @param {Map<string, string>} expectedByKey - Expected key->line map (fallback when no systemParsed)
  * @param {boolean} dryRun - If true, do not write
  * @param {string[]} changes - Array to append to
+ * @param {Object} [systemParsed] - Parsed system config for template context (preferred)
  * @returns {boolean}
  */
-function createEnvTemplateIfMissing(envPath, expectedByKey, dryRun, changes) {
+function createEnvTemplateIfMissing(envPath, expectedByKey, dryRun, changes, systemParsed) {
   if (fs.existsSync(envPath)) return false;
-  const lines = Array.from(expectedByKey.values());
-  const content = lines.join('\n');
-  if (!content) return false;
+  if (expectedByKey.size === 0) return false;
+  const content = systemParsed
+    ? generateExternalEnvTemplateContent(systemParsed)
+    : Array.from(expectedByKey.values()).join('\n');
+  if (!content || !content.trim()) return false;
+  const hasKeyValueLine = /^[A-Z_][A-Z0-9_]*=/m.test(content);
+  if (!hasKeyValueLine) return false;
   if (!dryRun) {
-    fs.writeFileSync(envPath, content + '\n', { mode: 0o644, encoding: 'utf8' });
+    fs.writeFileSync(envPath, content + (content.endsWith('\n') ? '' : '\n'), { mode: 0o644, encoding: 'utf8' });
   }
   changes.push('Created env.template from system configuration');
   return true;
@@ -236,7 +242,7 @@ function repairEnvTemplate(appPath, systemParsed, systemKey, dryRun, changes) {
   const expectedByKey = buildExpectedByKey(effective);
   const envPath = path.join(appPath, 'env.template');
 
-  if (createEnvTemplateIfMissing(envPath, expectedByKey, dryRun, changes)) {
+  if (createEnvTemplateIfMissing(envPath, expectedByKey, dryRun, changes, systemParsed)) {
     return true;
   }
   if (!fs.existsSync(envPath)) {

package/lib/commands/repair-rbac.js

@@ -10,10 +10,10 @@
 
 const path = require('path');
 const fs = require('fs');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { loadConfigFile } = require('../utils/config-format');
+const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
+const { resolveRbacPath } = require('../utils/app-config-resolver');
 
 const DEFAULT_CAPABILITIES = ['list', 'get', 'create', 'update', 'delete'];
 
@@ -55,26 +55,30 @@ function collectPermissionNames(appPath, datasourceFiles) {
 }
 
 /**
- * Loads existing rbac or creates empty structure. Uses extractRbacFromSystem when provided.
+ * Loads existing RBAC file (rbac.yaml, rbac.yml, or rbac.json) or creates empty structure.
+ * Uses extractRbacFromSystem when no file exists. New file path respects format (rbac.json when format is 'json').
+ *
  * @param {string} appPath - Application path
  * @param {Object} [systemParsed] - Parsed system for extractRbacFromSystem
  * @param {Function} extractRbacFromSystem - (system) => rbac or null
- * @returns {{ rbac: Object, rbacPath: string, rbacYmlPath: string }}
+ * @param {string} [format] - 'json' or 'yaml'; used only when creating a new file (default 'yaml')
+ * @returns {{ rbac: Object, rbacPath: string }} rbacPath is resolved path or path.join(appPath, 'rbac.{json|yaml}') for new file
  */
-function loadOrCreateRbac(appPath, systemParsed, extractRbacFromSystem) {
-  const rbacPath = path.join(appPath, 'rbac.yaml');
-  const rbacYmlPath = path.join(appPath, 'rbac.yml');
+function loadOrCreateRbac(appPath, systemParsed, extractRbacFromSystem, format) {
+  const resolvedPath = resolveRbacPath(appPath);
   let rbac;
-  if (fs.existsSync(rbacPath)) {
-    rbac = loadConfigFile(rbacPath);
-  } else if (fs.existsSync(rbacYmlPath)) {
-    rbac = loadConfigFile(rbacYmlPath);
+  let rbacPath;
+  if (resolvedPath) {
+    rbac = loadConfigFile(resolvedPath);
+    rbacPath = resolvedPath;
   } else {
     rbac = extractRbacFromSystem(systemParsed) || { roles: [], permissions: [] };
     if (!Array.isArray(rbac.roles)) rbac.roles = [];
     if (!Array.isArray(rbac.permissions)) rbac.permissions = [];
+    const ext = (format === 'json') ? 'rbac.json' : 'rbac.yaml';
+    rbacPath = path.join(appPath, ext);
   }
-  return { rbac, rbacPath, rbacYmlPath };
+  return { rbac, rbacPath };
 }
 
 /**
@@ -123,31 +127,33 @@ function ensureDefaultRoles(rbac, systemKey, displayName, changes) {
     if (p.name && listGetPerms.includes(p.name) && !p.roles.includes(readerValue)) p.roles.push(readerValue);
     if (!p.roles.includes(adminValue)) p.roles.push(adminValue);
   }
-  changes.push('Added default Admin and Reader roles to rbac.yaml');
+  changes.push('Added default Admin and Reader roles to rbac file');
   return true;
 }
 
 /**
  * Merges RBAC from datasources: ensures permission per resourceType:capability, adds Admin/Reader roles if none.
+ * When creating a new RBAC file, uses rbac.json if format is 'json', otherwise rbac.yaml.
+ *
  * @param {string} appPath - Application path
  * @param {Object} systemParsed - Parsed system (key, displayName)
  * @param {string[]} datasourceFiles - Datasource file names
  * @param {Function} extractRbacFromSystem - (system) => rbac or null
- * @param {boolean} dryRun - If true, do not write
- * @param {string[]} changes - Array to append change descriptions to
+ * @param {{ format?: string, dryRun: boolean, changes: string[] }} options - format ('json'|'yaml'), dryRun, changes array
  * @returns {boolean} True if rbac was updated (or would be in dry-run)
  */
-function mergeRbacFromDatasources(appPath, systemParsed, datasourceFiles, extractRbacFromSystem, dryRun, changes) {
+function mergeRbacFromDatasources(appPath, systemParsed, datasourceFiles, extractRbacFromSystem, options) {
+  const { format = 'yaml', dryRun, changes } = options;
+  const rbacFormat = format === 'json' ? 'json' : 'yaml';
   const permissionNames = collectPermissionNames(appPath, datasourceFiles);
   if (permissionNames.size === 0) return false;
   const systemKey = systemParsed?.key || 'system';
   const displayName = systemParsed?.displayName || systemKey;
-  const { rbac, rbacPath, rbacYmlPath } = loadOrCreateRbac(appPath, systemParsed, extractRbacFromSystem);
+  const { rbac, rbacPath } = loadOrCreateRbac(appPath, systemParsed, extractRbacFromSystem, rbacFormat);
   let updated = addMissingPermissions(rbac, permissionNames, changes);
   updated = ensureDefaultRoles(rbac, systemKey, displayName, changes) || updated;
   if (updated && !dryRun) {
-    const outPath = fs.existsSync(rbacPath) ? rbacPath : (fs.existsSync(rbacYmlPath) ? rbacYmlPath : rbacPath);
-    fs.writeFileSync(outPath, yaml.dump(rbac, { indent: 2, lineWidth: -1 }), { mode: 0o644, encoding: 'utf8' });
+    writeConfigFile(rbacPath, rbac);
   }
   return updated;
 }

package/lib/commands/repair.js

@@ -16,14 +16,14 @@
 const path = require('path');
 const fs = require('fs');
 const chalk = require('chalk');
-const yaml = require('js-yaml');
-const { detectAppType } = require('../utils/paths');
-const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+const { detectAppType, getDeployJsonPath } = require('../utils/paths');
+const { resolveApplicationConfigPath, resolveRbacPath } = require('../utils/app-config-resolver');
 const { loadConfigFile, writeConfigFile, writeYamlPreservingComments, isYamlPath } = require('../utils/config-format');
 const { systemKeyToKvPrefix, securityKeyToVar } = require('../utils/credential-secrets-env');
 const logger = require('../utils/logger');
 const generator = require('../generator');
 const { repairEnvTemplate, normalizeSystemFileAuthAndConfig } = require('./repair-env-template');
+const { generateReadmeFromDeployJson } = require('../generator/split-readme');
 const { repairDatasourceFile } = require('./repair-datasource');
 const { mergeRbacFromDatasources } = require('./repair-rbac');
 const { discoverIntegrationFiles, buildEffectiveDatasourceFiles } = require('./repair-internal');
@@ -249,6 +249,11 @@ function normalizedAuthPartFromConfigName(name, systemKey) {
     const rest = n.slice(kvPrefix.length);
     return rest.toUpperCase().replace(/_/g, '');
   }
+  // Old-style or other KV_* names: treat last segment as var (e.g. KV_HUBSPOT_CLIENTID → CLIENTID)
+  if (n.toUpperCase().startsWith('KV_')) {
+    const parts = n.split('_').filter(Boolean);
+    if (parts.length >= 2) return parts[parts.length - 1].toUpperCase();
+  }
   return n.toUpperCase().replace(/_/g, '');
 }
 
@@ -273,21 +278,20 @@ function removeAuthVarsFromConfiguration(systemParsed, systemKey, dryRun, change
   return true;
 }
 
-function createRbacFromSystemIfNeeded(appPath, systemFilePath, systemParsed, dryRun, changes) {
-  const rbacPath = path.join(appPath, 'rbac.yaml');
-  const rbacYmlPath = path.join(appPath, 'rbac.yml');
-  if (fs.existsSync(rbacPath) || fs.existsSync(rbacYmlPath)) return false;
+function createRbacFromSystemIfNeeded(appPath, systemFilePath, systemParsed, dryRun, changes, format) {
+  if (resolveRbacPath(appPath)) return false;
   const rbacFromSystem = extractRbacFromSystem(systemParsed);
   if (!rbacFromSystem) return false;
   if (!dryRun) {
-    const rbacYaml = yaml.dump(rbacFromSystem, { indent: 2, lineWidth: -1 });
-    fs.writeFileSync(rbacPath, rbacYaml, { mode: 0o644, encoding: 'utf8' });
+    const rbacFormat = format === 'json' ? 'json' : 'yaml';
+    const defaultRbacPath = path.join(appPath, rbacFormat === 'json' ? 'rbac.json' : 'rbac.yaml');
+    writeConfigFile(defaultRbacPath, rbacFromSystem, rbacFormat);
     delete systemParsed.roles;
     delete systemParsed.permissions;
     writeConfigFile(systemFilePath, systemParsed);
   }
   changes.push('Created rbac.yaml from system roles/permissions');
-  changes.push('Removed roles/permissions from system file (now in rbac.yaml)');
+  changes.push('Removed roles/permissions from system file (now in rbac file)');
   return true;
 }
 
@@ -338,6 +342,36 @@ async function regenerateManifest(appName, appPath, changes) {
   }
 }
 
+/**
+ * Regenerates README.md from deployment manifest when options.doc is set.
+ * @param {string} appName - Application name
+ * @param {string} appPath - Application path
+ * @param {Object} options - Options (doc, dryRun)
+ * @param {string[]} changes - Array to append change messages to
+ * @returns {Promise<boolean>} True if README was regenerated
+ */
+async function regenerateReadmeIfRequested(appName, appPath, options, changes) {
+  if (!options.doc) return false;
+  const deployJsonPath = getDeployJsonPath(appName, 'external', true);
+  if (!fs.existsSync(deployJsonPath) && !options.dryRun) {
+    await regenerateManifest(appName, appPath, changes);
+  }
+  if (!fs.existsSync(deployJsonPath)) return false;
+  try {
+    const deployment = JSON.parse(fs.readFileSync(deployJsonPath, 'utf8'));
+    const readmeContent = generateReadmeFromDeployJson(deployment);
+    const readmePath = path.join(appPath, 'README.md');
+    if (!options.dryRun) {
+      fs.writeFileSync(readmePath, readmeContent, { mode: 0o644, encoding: 'utf8' });
+    }
+    changes.push('Regenerated README.md from deployment manifest');
+    return true;
+  } catch (err) {
+    logger.log(chalk.yellow(`⚠ Could not regenerate README: ${err.message}`));
+    return false;
+  }
+}
+
 function persistChangesAndRegenerate(configPath, variables, appName, appPath, changes, originalYamlContent) {
   if (originalYamlContent !== null && originalYamlContent !== undefined && typeof originalYamlContent === 'string' && isYamlPath(configPath)) {
     writeYamlPreservingComments(configPath, originalYamlContent, variables);
@@ -351,6 +385,7 @@ function persistChangesAndRegenerate(configPath, variables, appName, appPath, ch
 
 /**
  * Apply --auth: replace system file authentication with canonical block for the given method.
+ * Preserves existing authentication.variables (e.g. baseUrl, tokenUrl) from the current system file.
  * @param {Object} ctx - Context with systemParsed, systemKey, auth, dryRun, changes
  * @returns {boolean} True if auth was replaced
  */
@@ -362,8 +397,18 @@ function applyAuthMethod(ctx) {
       `Invalid --auth "${ctx.auth}". Allowed methods: ${ALLOWED_AUTH.join(', ')}`
     );
   }
+  const existingAuth = ctx.systemParsed.authentication || ctx.systemParsed.auth || {};
   const { buildAuthenticationFromMethod } = require('../external-system/generator');
-  ctx.systemParsed.authentication = buildAuthenticationFromMethod(ctx.systemKey, method);
+  const newAuth = buildAuthenticationFromMethod(ctx.systemKey, method);
+  const existingVars = existingAuth.variables && typeof existingAuth.variables === 'object' ? existingAuth.variables : {};
+  const mergedVariables = { ...newAuth.variables, ...existingVars };
+  ctx.systemParsed.authentication = {
+    ...newAuth,
+    variables: Object.keys(mergedVariables).length ? mergedVariables : newAuth.variables
+  };
+  if (existingAuth.displayName !== undefined) {
+    ctx.systemParsed.authentication.displayName = existingAuth.displayName;
+  }
   ctx.changes.push(`Set authentication method to ${method}`);
   return true;
 }
@@ -399,7 +444,7 @@ function runRepairSteps(ctx) {
     ctx.appPath, ctx.datasourceFiles, ctx.systemKey, ctx.dryRun, ctx.changes
   );
   const rbacFileCreated = createRbacFromSystemIfNeeded(
-    ctx.appPath, ctx.systemFilePath, ctx.systemParsed, ctx.dryRun, ctx.changes
+    ctx.appPath, ctx.systemFilePath, ctx.systemParsed, ctx.dryRun, ctx.changes, ctx.format
   );
   const envTemplateRepaired = repairEnvTemplate(
     ctx.appPath, ctx.systemParsed, ctx.systemKey, ctx.dryRun, ctx.changes
@@ -420,7 +465,8 @@ function runRepairSteps(ctx) {
  * @param {string} appName - Application/integration name
  * @param {Object} [options] - Options
  * @param {boolean} [options.dryRun] - If true, only report changes; do not write
- * @returns {Promise<{ updated: boolean, changes: string[], systemFiles: string[], datasourceFiles: string[], appKeyFixed?: boolean, datasourceKeysFixed?: boolean, rbacFileCreated?: boolean, envTemplateRepaired?: boolean, manifestRegenerated?: boolean }>}
+ * @param {boolean} [options.doc] - If true, regenerate README.md from deployment manifest
+ * @returns {Promise<{ updated: boolean, changes: string[], systemFiles: string[], datasourceFiles: string[], appKeyFixed?: boolean, datasourceKeysFixed?: boolean, rbacFileCreated?: boolean, envTemplateRepaired?: boolean, manifestRegenerated?: boolean, readmeRegenerated?: boolean }>}
  */
 /**
  * Loads application config and discovers integration files; validates at least one system file exists.
@@ -442,7 +488,36 @@ function loadConfigAndDiscover(appPath, configPath) {
   return { variables, originalYamlContent, systemFiles, datasourceFiles };
 }
 
-async function repairExternalIntegration(appName, options = {}) {
+/**
+ * Builds the repair result object from steps and flags.
+ * @param {Object} steps - Result of runRepairSteps
+ * @param {boolean} anyUpdated - Whether any repair made changes
+ * @param {boolean} manifestRegenerated - Whether manifest was regenerated
+ * @param {boolean} readmeRegenerated - Whether README was regenerated
+ * @param {{ changes: string[], systemFiles: string[], datasourceFiles: string[] }} ctx - changes and file lists
+ * @returns {Object} Combined result object
+ */
+function buildRepairResult(steps, anyUpdated, manifestRegenerated, readmeRegenerated, ctx) {
+  return Object.assign(
+    { updated: anyUpdated, changes: ctx.changes, systemFiles: ctx.systemFiles, datasourceFiles: ctx.datasourceFiles },
+    {
+      appKeyFixed: steps.appKeyFixed,
+      datasourceKeysFixed: steps.datasourceKeysFixed,
+      rbacFileCreated: steps.rbacFileCreated,
+      envTemplateRepaired: steps.envTemplateRepaired,
+      manifestRegenerated,
+      readmeRegenerated
+    }
+  );
+}
+
+/**
+ * Validates repair inputs and resolves app path and config path.
+ * @param {string} appName - Application name
+ * @param {Object} options - Command options (auth)
+ * @returns {Promise<{ appPath: string, configPath: string, dryRun: boolean, authOption: string|undefined }>}
+ */
+async function validateAndResolveRepairPaths(appName, options) {
   if (!appName || typeof appName !== 'string') throw new Error('App name is required');
   const { dryRun = false, auth: authOption } = options;
   if (authOption !== undefined && authOption !== null && typeof authOption !== 'string') {
@@ -452,6 +527,11 @@ async function repairExternalIntegration(appName, options = {}) {
   if (!isExternal) throw new Error(`App '${appName}' is not an external integration`);
   const configPath = resolveApplicationConfigPath(appPath);
   if (!fs.existsSync(configPath)) throw new Error(`Application config not found: ${configPath}`);
+  return { appPath, configPath, dryRun, authOption };
+}
+
+async function repairExternalIntegration(appName, options = {}) {
+  const { appPath, configPath, dryRun, authOption } = await validateAndResolveRepairPaths(appName, options);
 
   const { variables, originalYamlContent, systemFiles, datasourceFiles: initialDatasourceFiles } = loadConfigAndDiscover(appPath, configPath);
   const changes = [];
@@ -475,30 +555,27 @@ async function repairExternalIntegration(appName, options = {}) {
     datasourceFiles,
     dryRun,
     changes,
-    auth: authOption
+    auth: authOption,
+    format: options.format === 'json' ? 'json' : 'yaml'
   });
-
-  const opts = { expose: Boolean(options.expose), sync: Boolean(options.sync), test: Boolean(options.test) };
-  const datasourceRepairUpdated = runDatasourceRepairs(appPath, datasourceFiles, opts, dryRun, changes);
+  const datasourceRepairUpdated = runDatasourceRepairs(appPath, datasourceFiles, {
+    expose: Boolean(options.expose),
+    sync: Boolean(options.sync),
+    test: Boolean(options.test)
+  }, dryRun, changes);
   const rbacMergeUpdated = options.rbac
-    ? mergeRbacFromDatasources(appPath, systemParsed, datasourceFiles, extractRbacFromSystem, dryRun, changes)
+    ? mergeRbacFromDatasources(appPath, systemParsed, datasourceFiles, extractRbacFromSystem, {
+      format: options.format === 'json' ? 'json' : 'yaml',
+      dryRun,
+      changes
+    })
     : false;
   const anyUpdated = keysNormalized || steps.updated || datasourceRepairUpdated || rbacMergeUpdated;
   const manifestRegenerated = (anyUpdated && !dryRun)
     ? await persistChangesAndRegenerate(configPath, variables, appName, appPath, changes, originalYamlContent)
     : false;
-
-  return {
-    updated: anyUpdated,
-    changes,
-    systemFiles,
-    datasourceFiles,
-    appKeyFixed: steps.appKeyFixed,
-    datasourceKeysFixed: steps.datasourceKeysFixed,
-    rbacFileCreated: steps.rbacFileCreated,
-    envTemplateRepaired: steps.envTemplateRepaired,
-    manifestRegenerated
-  };
+  const readmeRegenerated = await regenerateReadmeIfRequested(appName, appPath, options, changes);
+  return buildRepairResult(steps, anyUpdated, manifestRegenerated, readmeRegenerated, { changes, systemFiles, datasourceFiles });
 }
 
 module.exports = {

package/lib/commands/secrets-remove.js

@@ -33,7 +33,7 @@ function removeKeyFromFile(key, filePath) {
     throw new Error(`Secret '${key}' not found.`);
   }
   delete data[key];
-  const yamlContent = yaml.dump(data, { indent: 2, lineWidth: 120, noRefs: true, sortKeys: false });
+  const yamlContent = yaml.dump(data, { indent: 2, lineWidth: -1, noRefs: true, sortKeys: false });
   fs.writeFileSync(filePath, yamlContent, { mode: 0o600 });
 }
 

package/lib/commands/secrets-set.js

@@ -60,6 +60,12 @@ async function handleSecretsSet(key, value, options) {
     throw new Error('Secret key is required and must be a string');
   }
 
+  if (key.startsWith('kv://')) {
+    throw new Error(
+      'Secret key must not start with kv://. Use the key path without the prefix (e.g. my-app/clientSecret or hubspot/apiKey).'
+    );
+  }
+
   if (value === undefined || value === null || value === '') {
     throw new Error('Secret value is required');
   }