@aifabrix/builder 2.41.0 → 2.42.0

package/lib/cli/setup-credential-deployment.js

@@ -11,8 +11,37 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
 const { runCredentialList } = require('../commands/credential-list');
+const { runCredentialEnv } = require('../commands/credential-env');
+const { runCredentialPush } = require('../commands/credential-push');
 const { runDeploymentList } = require('../commands/deployment-list');
 
+function setupCredentialEnvAndPush(credential) {
+  credential
+    .command('env <system-key>')
+    .description('Prompt for KV_* credential values and write integration/<system-key>/.env')
+    .action(async(systemKey, _options) => {
+      try {
+        await runCredentialEnv(systemKey);
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'credential env');
+        process.exit(1);
+      }
+    });
+  credential
+    .command('push <system-key>')
+    .description('Push credential secrets from .env to Dataplane (KV_* vars)')
+    .action(async(systemKey, _options) => {
+      try {
+        await runCredentialPush(systemKey);
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'credential push');
+        process.exit(1);
+      }
+    });
+}
+
 /**
  * Sets up credential and deployment list commands
  * @param {Command} program - Commander program instance
@@ -21,19 +50,15 @@ function setupCredentialDeploymentCommands(program) {
   const credential = program
     .command('credential')
     .description('Manage credentials');
-
+  setupCredentialEnvAndPush(credential);
   credential
     .command('list')
-    .description('List credentials from Dataplane (GET /api/v1/credential). Controller does not expose this endpoint.')
-    .option('--controller <url>', 'Controller URL (default: from config)')
-    .option('--dataplane <url>', 'Dataplane URL (default: resolved from controller + environment)')
+    .description('Get credentials from Dataplane')
     .option('--active-only', 'List only active credentials')
     .option('--page-size <n>', 'Items per page', '50')
     .action(async(options) => {
       try {
         const opts = {
-          controller: options.controller,
-          dataplane: options.dataplane,
           activeOnly: options.activeOnly,
           pageSize: parseInt(options.pageSize, 10) || 50
         };

package/lib/cli/setup-dev.js

@@ -33,6 +33,7 @@ async function displayDevConfig(devId) {
   const controller = await config.getControllerUrl();
 
   const optionalConfigVars = [
+    { key: 'format', value: (await config.getFormat()) ?? '(not set)' },
     { key: 'aifabrix-home', value: await config.getAifabrixHomeOverride() },
     { key: 'aifabrix-secrets', value: await config.getAifabrixSecretsPath() },
     { key: 'aifabrix-env-config', value: await config.getAifabrixEnvConfigPath() },
@@ -59,6 +60,18 @@ async function displayDevConfig(devId) {
   logger.log('');
 }
 
+/**
+ * Handle dev set-format command
+ * @param {string} format - Format value (json | yaml)
+ * @returns {Promise<void>}
+ */
+async function handleSetFormat(format) {
+  await config.setFormat(format);
+  logger.log(chalk.green(`✓ Format set to ${format.toLowerCase()}`));
+  const devId = await config.getDeveloperId();
+  await displayDevConfig(devId);
+}
+
 /**
  * Register dev config and set-id commands.
  * @param {Command} dev - dev subcommand group
@@ -90,6 +103,18 @@ function setupDevConfigCommands(dev) {
       }
     });
 
+  dev
+    .command('set-format <format>')
+    .description('Set default output format for download/convert (json | yaml); used when --format not passed')
+    .action(async(format) => {
+      try {
+        await handleSetFormat(format);
+      } catch (error) {
+        handleCommandError(error, 'dev set-format');
+        process.exit(1);
+      }
+    });
+
   dev
     .command('set-id <id>')
     .description('Set developer ID (convenience alias for "dev config --set-id")')
@@ -121,6 +146,8 @@ function setupDevInitCommand(dev) {
     .requiredOption('--developer-id <id>', 'Developer ID (same as dev add; e.g. 01)')
     .requiredOption('--server <url>', 'Builder Server base URL (e.g. https://dev.aifabrix.dev)')
     .requiredOption('--pin <pin>', 'One-time PIN from your admin')
+    .option('-y, --yes', 'Auto-install development CA without prompt when certificate is untrusted')
+    .option('--no-install-ca', 'Do not offer CA install; fail with manual instructions on untrusted certificate')
     .action(async(options) => {
       try {
         await runDevInit(options);

package/lib/cli/setup-environment.js

@@ -25,30 +25,38 @@ function setupEnvironmentCommands(program) {
 
   const environment = program
     .command('environment')
-    .description('Manage environments');
+    .description('Deploy and manage Miso Controller environments (dev, tst, pro, miso)');
+
+  const deployExamples = `
+Examples:
+  $ aifabrix environment deploy dev
+  $ aifabrix environment deploy tst --preset m
+  $ aifabrix environment deploy dev --config ./env-config.json --no-poll`;
 
   environment
     .command('deploy <env>')
-    .description('Deploy/setup environment in Miso Controller')
+    .description('Deploy environment infrastructure in Miso Controller (run before deploy <app>)')
     .option('--config <file>', 'Environment configuration file (optional if --preset is used)')
     .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s)', 's')
     .option('--skip-validation', 'Skip environment validation')
     .option('--poll', 'Poll for deployment status', true)
     .option('--no-poll', 'Do not poll for status')
+    .addHelpText('after', deployExamples)
     .action(deployEnvHandler);
 
   const env = program
     .command('env')
-    .description('Environment management (alias for environment)');
+    .description('Deploy and manage Miso Controller environments (alias for environment)');
 
   env
     .command('deploy <env>')
-    .description('Deploy/setup environment in Miso Controller')
+    .description('Deploy environment infrastructure in Miso Controller (run before deploy <app>)')
     .option('--config <file>', 'Environment configuration file (optional if --preset is used)')
     .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s)', 's')
     .option('--skip-validation', 'Skip environment validation')
     .option('--poll', 'Poll for deployment status', true)
     .option('--no-poll', 'Do not poll for status')
+    .addHelpText('after', deployExamples)
     .action(deployEnvHandler);
 }
 

package/lib/cli/setup-external-system.js

@@ -1,9 +1,17 @@
 /**
- * CLI external system command setup (download, delete, test, test-integration).
+ * CLI external system command setup (download, upload, delete, test-integration).
+ *
+ * Registers these commands on the Commander program:
+ * - download <system-key> – Download external system from dataplane to integration/<system-key>/
+ * - upload <system-key> – Upload to dataplane (validate → publish; no controller deploy)
+ * - delete <system-key> – Delete external system and associated datasources from dataplane
+ * - test-integration <app> – Run integration tests (builder: in container; external: via dataplane pipeline)
  *
  * @fileoverview External system command definitions for AI Fabrix Builder CLI
  * @author AI Fabrix Team
  * @version 2.0.0
+ * @see docs/commands/external-integration.md - User-facing command reference
+ * @see docs/external-systems.md - External systems guide and workflow
  */
 
 const { handleCommandError } = require('../utils/cli-utils');
@@ -11,11 +19,18 @@ const { handleCommandError } = require('../utils/cli-utils');
 function setupDownloadCommand(program) {
   program.command('download <system-key>')
     .description('Download external system from dataplane to local development structure')
+    .option('--format <format>', 'Output format: json | yaml (default: yaml or config format)')
     .option('--dry-run', 'Show what would be downloaded without actually downloading')
+    .option('--force', 'Overwrite existing README.md without prompting')
     .action(async(systemKey, options) => {
       try {
+        const config = require('../core/config');
+        const effectiveFormat = (options.format || (await config.getFormat()) || 'yaml').trim().toLowerCase();
+        if (effectiveFormat !== 'json' && effectiveFormat !== 'yaml') {
+          throw new Error('Option --format must be \'json\' or \'yaml\'');
+        }
         const download = require('../external-system/download');
-        await download.downloadExternalSystem(systemKey, options);
+        await download.downloadExternalSystem(systemKey, { ...options, format: effectiveFormat });
       } catch (error) {
         handleCommandError(error, 'download');
         process.exit(1);
@@ -27,7 +42,6 @@ function setupUploadCommand(program) {
   program.command('upload <system-key>')
     .description('Upload external system to dataplane (upload → validate → publish; no controller deploy)')
     .option('--dry-run', 'Validate and build payload only; no API calls')
-    .option('--dataplane <url>', 'Dataplane URL (default: discovered from controller)')
     .action(async(systemKey, options) => {
       try {
         const upload = require('../commands/upload');
@@ -97,7 +111,7 @@ async function tryBuilderTestIntegration(appName, options) {
  */
 async function runExternalSystemTestIntegration(appName, options) {
   const test = require('../external-system/test');
-  const opts = { ...options, environment: options.env || options.environment };
+  const opts = { ...options, environment: options.env || options.environment, debug: options.debug };
   const results = await test.testExternalSystemIntegration(appName, opts);
   test.displayIntegrationTestResults(results, options.verbose);
   if (!results.success) process.exit(1);
@@ -131,6 +145,7 @@ function setupExternalSystemTestCommands(program) {
     .option('-p, --payload <file>', 'Path to custom test payload file')
     .option('-e, --env <env>', 'Environment: dev, tst, or pro (default: from aifabrix auth config)')
     .option('-v, --verbose', 'Show detailed test output')
+    .option('--debug', 'Include debug output and write log to integration/<app>/logs/')
     .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
     .action(async(appName, options) => {
       try {

package/lib/cli/setup-infra.js

@@ -19,8 +19,34 @@ const { handleUpMiso } = require('../commands/up-miso');
 const { handleUpDataplane } = require('../commands/up-dataplane');
 
 /**
- * Runs the up-infra command: resolves developer ID, traefik, and starts infra.
- * @param {Object} options - Commander options (developer, traefik)
+ * Persists optional service flag to config when explicitly set.
+ * @param {Object} cfg - Config object (mutated)
+ * @param {string} key - Config key (traefik, pgadmin, redisCommander)
+ * @param {boolean} value - Value to set
+ * @param {string} label - Label for log message
+ */
+async function persistOptionalServiceFlag(cfg, key, value, label) {
+  cfg[key] = value;
+  await config.saveConfig(cfg);
+  logger.log(chalk.green(`✓ ${label} ${value ? 'enabled' : 'disabled'} and saved to config`));
+}
+
+/**
+ * Resolves effective boolean from option vs config.
+ * @param {*} optValue - options.traefik | options.pgAdmin | options.redisAdmin
+ * @param {*} cfgValue - cfg.traefik | cfg.pgadmin | cfg.redisCommander
+ * @param {boolean} defaultWhenUndef - Default when config value is undefined
+ * @returns {boolean}
+ */
+function resolveFlag(optValue, cfgValue, defaultWhenUndef = true) {
+  if (optValue === true) return true;
+  if (optValue === false) return false;
+  return cfgValue !== false && (cfgValue === true || defaultWhenUndef);
+}
+
+/**
+ * Runs the up-infra command: resolves developer ID, traefik, pgAdmin, redisAdmin, and starts infra.
+ * @param {Object} options - Commander options (developer, traefik, pgAdmin, redisAdmin)
  * @returns {Promise<void>}
  */
 async function runUpInfraCommand(options) {
@@ -37,24 +63,33 @@ async function runUpInfraCommand(options) {
     logger.log(chalk.green(`✓ Developer ID set to ${id}`));
   }
   const cfg = await config.getConfig();
-  if (options.traefik === true) {
-    cfg.traefik = true;
-    await config.saveConfig(cfg);
-    logger.log(chalk.green('✓ Traefik enabled and saved to config'));
-  } else if (options.traefik === false) {
-    cfg.traefik = false;
-    await config.saveConfig(cfg);
-    logger.log(chalk.green('✓ Traefik disabled and saved to config'));
+  const flagSpecs = [
+    { opt: options.traefik, key: 'traefik', label: 'Traefik' },
+    { opt: options.pgAdmin, key: 'pgadmin', label: 'pgAdmin' },
+    { opt: options.redisAdmin, key: 'redisCommander', label: 'Redis Commander' }
+  ];
+  for (const { opt, key, label } of flagSpecs) {
+    if (opt === true || opt === false) {
+      await persistOptionalServiceFlag(cfg, key, opt, label);
+    }
   }
-  const useTraefik = options.traefik === true ? true : (options.traefik === false ? false : !!(cfg.traefik));
-  await infra.startInfra(developerId, { traefik: useTraefik, adminPwd: options.adminPwd });
+  await infra.startInfra(developerId, {
+    traefik: resolveFlag(options.traefik, cfg.traefik, false),
+    pgadmin: resolveFlag(options.pgAdmin, cfg.pgadmin, true),
+    redisCommander: resolveFlag(options.redisAdmin, cfg.redisCommander, true),
+    adminPwd: options.adminPwd
+  });
 }
 
 function setupUpInfraCommand(program) {
   program.command('up-infra')
-    .description('Start local infrastructure: Postgres, Redis, optional Traefik')
+    .description('Start local infrastructure: Postgres, Redis, optional pgAdmin, Redis Commander, Traefik')
     .option('-d, --developer <id>', 'Set developer ID and start infrastructure')
     .option('--adminPwd <password>', 'Override default admin password for new install (Postgres, pgAdmin, Redis Commander)')
+    .option('--pgAdmin', 'Include pgAdmin web UI and save to config')
+    .option('--no-pgAdmin', 'Exclude pgAdmin and save to config')
+    .option('--redisAdmin', 'Include Redis Commander web UI and save to config')
+    .option('--no-redisAdmin', 'Exclude Redis Commander and save to config')
     .option('--traefik', 'Include Traefik reverse proxy and save to config')
     .option('--no-traefik', 'Exclude Traefik and save to config')
     .action(async(options) => {
@@ -175,7 +210,12 @@ function setupDoctorCommand(program) {
         }
         if (result.docker === 'ok') {
           try {
-            const health = await infra.checkInfraHealth();
+            const cfg = await config.getConfig();
+            const health = await infra.checkInfraHealth(null, {
+              pgadmin: cfg.pgadmin !== false,
+              redisCommander: cfg.redisCommander !== false,
+              traefik: !!cfg.traefik
+            });
             logger.log('\n🏥 Infrastructure Health:');
             Object.entries(health).forEach(([service, status]) => {
               const icon = status === 'healthy' ? '✅' : status === 'unknown' ? '❓' : '❌';

package/lib/cli/setup-utility.js

@@ -77,9 +77,13 @@ function logSplitJsonResult(result) {
     result.datasourceFiles.forEach(filePath => logger.log(`  • datasource: ${filePath}`));
   }
   if (result.rbac) {
-    logger.log(`  • rbac.yml: ${result.rbac}`);
+    logger.log(`  • rbac.yaml: ${result.rbac}`);
+  }
+  if (result.readmeSkipped) {
+    logger.log(`  • README.md: (kept existing) ${result.readmeSkipped}`);
+  } else if (result.readme) {
+    logger.log(`  • README.md: ${result.readme}`);
   }
-  logger.log(`  • README.md: ${result.readme}`);
 }
 
 function setupResolveCommand(program) {
@@ -141,7 +145,7 @@ function setupJsonCommand(program) {
     });
 }
 
-function setupSplitJsonConvertShowCommands(program) {
+function setupSplitJsonCommand(program) {
   program.command('split-json <app>')
     .description('Split deployment JSON into component files (env.template, application.yaml, rbac.yml, README.md)')
     .option('-o, --output <dir>', 'Output directory for component files (defaults to same directory as JSON)')
@@ -153,15 +157,66 @@ function setupSplitJsonConvertShowCommands(program) {
         process.exit(1);
       }
     });
+}
 
+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('--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')
+    .option('--sync', 'Add default sync section to datasources that lack it')
+    .option('--test', 'Generate testPayload.payloadTemplate and testPayload.expectedResult from attributes')
+    .action(async(appName, options) => {
+      try {
+        const { repairExternalIntegration } = require('../commands/repair');
+        const { detectAppType } = require('../utils/paths');
+        const { appPath } = await detectAppType(appName);
+        logOfflinePathWhenType(appPath);
+        const result = await repairExternalIntegration(appName, {
+          auth: options.auth,
+          dryRun: options.dryRun,
+          rbac: options.rbac,
+          expose: options.expose,
+          sync: options.sync,
+          test: options.test
+        });
+        if (options.dryRun && result.updated && result.changes.length > 0) {
+          logger.log(chalk.yellow('\nWould apply:'));
+          result.changes.forEach(c => logger.log(chalk.gray(`  ${c}`)));
+        } else if (result.updated) {
+          logger.log(chalk.green('\n✓ Repaired external integration config.'));
+        } else {
+          logger.log(chalk.gray('No changes needed; config already matches files on disk.'));
+        }
+      } catch (error) {
+        handleCommandError(error, 'repair');
+        process.exit(1);
+      }
+    });
+}
+
+function setupConvertCommand(program) {
   program.command('convert <app>')
     .description('Convert integration/external system and datasource config files between JSON and YAML')
-    .option('--format <format>', 'Target format: json | yaml (required)')
+    .option('--format <format>', 'Target format: json | yaml (required unless config format is set)')
     .option('-f, --force', 'Skip confirmation prompt')
     .action(async(appName, options) => {
       try {
+        const config = require('../core/config');
+        const effectiveFormat = options.format || (await config.getFormat());
+        if (!effectiveFormat) {
+          throw new Error(
+            'Option --format is required and must be \'json\' or \'yaml\' (or set default with aifabrix dev set-format)'
+          );
+        }
+        const normalized = effectiveFormat.trim().toLowerCase();
+        if (normalized !== 'json' && normalized !== 'yaml') {
+          throw new Error('Option --format must be \'json\' or \'yaml\'');
+        }
         const { runConvert } = require('../commands/convert');
-        const { converted, deleted } = await runConvert(appName, { format: options.format, force: options.force });
+        const { converted, deleted } = await runConvert(appName, { format: normalized, force: options.force });
         logger.log(chalk.green('\n✓ Convert complete.'));
         converted.forEach(p => logger.log(`  • ${p}`));
         if (deleted.length > 0) {
@@ -173,7 +228,9 @@ function setupSplitJsonConvertShowCommands(program) {
         process.exit(1);
       }
     });
+}
 
+function setupShowCommand(program) {
   program.command('show <appKey>')
     .description('Show application info from local builder/ or integration/ (offline) or from controller (--online)')
     .option('--online', 'Fetch application data from the controller')
@@ -189,25 +246,60 @@ function setupSplitJsonConvertShowCommands(program) {
     });
 }
 
+function setupSplitJsonConvertShowCommands(program) {
+  setupSplitJsonCommand(program);
+  setupRepairCommand(program);
+  setupConvertCommand(program);
+  setupShowCommand(program);
+}
+
+async function runValidateCommand(appOrFile, options) {
+  const validate = require('../validation/validate');
+  const opts = options.opts ? options.opts() : options;
+  const integration = opts.integration === true;
+  const builder = opts.builder === true;
+  const outFormat = (opts.format || 'default').toLowerCase();
+
+  if (integration || builder) {
+    const batchResult = integration && builder
+      ? await validate.validateAll(opts)
+      : integration
+        ? await validate.validateAllIntegrations(opts)
+        : await validate.validateAllBuilderApps(opts);
+    if (outFormat === 'json') {
+      logger.log(JSON.stringify(batchResult, null, 2));
+    } else {
+      validate.displayBatchValidationResults(batchResult);
+    }
+    if (!batchResult.valid) process.exit(1);
+    return;
+  }
+
+  if (!appOrFile || typeof appOrFile !== 'string') {
+    logger.log(chalk.red('App name or file path is required, or use --integration / --builder'));
+    process.exit(1);
+  }
+
+  const result = await validate.validateAppOrFile(appOrFile, opts);
+  if (outFormat === 'json') {
+    logger.log(JSON.stringify(result, null, 2));
+  } else {
+    validate.displayValidationResults(result);
+  }
+  if (!result.valid) process.exit(1);
+}
+
 function setupValidateDiffCommands(program) {
-  program.command('validate <appOrFile>')
-    .description('Validate application or external integration file')
+  program.command('validate [appOrFile]')
+    .description('Validate application or external integration file; use --integration or --builder to validate all apps')
     .option('--format <format>', 'Output format: json | default (human-readable)')
-    .action(async(appOrFile, options) => {
-      try {
-        const validate = require('../validation/validate');
-        const result = await validate.validateAppOrFile(appOrFile, options);
-        const outFormat = (options.format || 'default').toLowerCase();
-        if (outFormat === 'json') {
-          logger.log(JSON.stringify(result, null, 2));
-        } else {
-          validate.displayValidationResults(result);
-        }
-        if (!result.valid) process.exit(1);
-      } catch (error) {
+    .option('--integration', 'Validate all applications under integration/')
+    .option('--builder', 'Validate all applications under builder/')
+    .action((appOrFile, options) => {
+      runValidateCommand(appOrFile, options).catch((error) => {
         handleCommandError(error, 'validate');
         process.exit(1);
-      }
+      });
     });
 
   program.command('diff <file1> <file2>')
@@ -238,4 +330,8 @@ function setupUtilityCommands(program) {
   setupValidateDiffCommands(program);
 }
 
-module.exports = { setupUtilityCommands };
+module.exports = {
+  setupUtilityCommands,
+  resolveSplitJsonApp,
+  handleSplitJsonCommand
+};

package/lib/commands/credential-env.js

@@ -0,0 +1,162 @@
+/**
+ * Credential env command – prompts for KV_* values and writes .env.
+ * Used by `aifabrix credential env <system-key>`.
+ *
+ * @fileoverview Credential env command – interactive credential capture to .env
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const fs = require('fs');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { getIntegrationPath } = require('../utils/paths');
+const { kvEnvKeyToPath } = require('../utils/credential-secrets-env');
+const { parseEnvToMap } = require('../utils/credential-secrets-env');
+
+const KV_PREFIX = 'KV_';
+
+/**
+ * Secret var suffixes (use password prompt).
+ * @type {Set<string>}
+ */
+const SECRET_SUFFIXES = new Set([
+  'CLIENTID', 'CLIENTSECRET', 'APIKEY', 'USERNAME', 'PASSWORD', 'PARAMVALUE',
+  'SIGNINGSECRET', 'BEARERTOKEN'
+]);
+
+/**
+ * Validates system-key format.
+ * @param {string} systemKey - System key
+ * @throws {Error} If invalid
+ */
+function validateSystemKeyFormat(systemKey) {
+  if (!systemKey || typeof systemKey !== 'string') {
+    throw new Error('System key is required and must be a string');
+  }
+  if (!/^[a-z0-9-_]+$/.test(systemKey)) {
+    throw new Error('System key must contain only lowercase letters, numbers, hyphens, and underscores');
+  }
+}
+
+/**
+ * Extracts KV_* variable names from env.template content.
+ * @param {string} content - env.template content
+ * @returns {Array<{ key: string, isSecret: boolean }>} KV_* vars to prompt
+ */
+function extractKvVarsFromTemplate(content) {
+  if (!content || typeof content !== 'string') return [];
+  const vars = [];
+  const seen = new Set();
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) continue;
+    const key = trimmed.substring(0, eq).trim();
+    if (!key.toUpperCase().startsWith(KV_PREFIX)) continue;
+    if (kvEnvKeyToPath(key) && !seen.has(key)) {
+      seen.add(key);
+      const suffix = key.slice(KV_PREFIX.length).split('_').pop() || '';
+      vars.push({ key, isSecret: SECRET_SUFFIXES.has(suffix.toUpperCase()) });
+    }
+  }
+  return vars;
+}
+
+/**
+ * Prompts for KV_* values using inquirer.
+ * @async
+ * @param {Array<{ key: string, isSecret: boolean }>} vars - Variables to prompt
+ * @param {Object} existingMap - Existing .env key-value map (for default values)
+ * @returns {Promise<Object.<string, string>>} Key-value map from prompts
+ */
+async function promptForKvValues(vars, existingMap) {
+  if (vars.length === 0) return {};
+  const inquirer = require('inquirer');
+  const questions = vars.map(({ key, isSecret }) => ({
+    type: isSecret ? 'password' : 'input',
+    name: key,
+    message: key,
+    default: existingMap[key] || undefined
+  }));
+  return await inquirer.prompt(questions);
+}
+
+/**
+ * Builds .env content: template lines with KV_* values replaced/merged from prompts.
+ * Preserves comments, non-KV lines, and structure; updates KV_* with prompted values.
+ * @param {string} templateContent - env.template content
+ * @param {Object.<string, string>} promptValues - Values from prompts
+ * @returns {string} Final .env content
+ */
+function buildEnvContent(templateContent, promptValues) {
+  if (!templateContent || typeof templateContent !== 'string') return '';
+  const lines = templateContent.split(/\r?\n/);
+  const result = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      result.push(line);
+      continue;
+    }
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) {
+      result.push(line);
+      continue;
+    }
+    const key = trimmed.substring(0, eq).trim();
+    if (key.toUpperCase().startsWith(KV_PREFIX) && key in promptValues) {
+      result.push(`${key}=${promptValues[key]}`);
+    } else {
+      result.push(line);
+    }
+  }
+  return result.join('\n');
+}
+
+/**
+ * Runs credential env command: prompt for KV_* values and write .env.
+ * @async
+ * @param {string} systemKey - External system key (integration/<system-key>/)
+ * @returns {Promise<string>} Path to written .env file
+ * @throws {Error} If env.template missing or write fails
+ */
+function loadExistingEnvMap(envPath) {
+  if (!fs.existsSync(envPath)) return {};
+  return parseEnvToMap(fs.readFileSync(envPath, 'utf8'));
+}
+
+async function runCredentialEnv(systemKey) {
+  validateSystemKeyFormat(systemKey);
+  const appPath = getIntegrationPath(systemKey);
+  const envTemplatePath = path.join(appPath, 'env.template');
+  const envPath = path.join(appPath, '.env');
+
+  if (!fs.existsSync(envTemplatePath)) {
+    throw new Error(`env.template not found at ${envTemplatePath}. Create the integration first (e.g. aifabrix wizard or download).`);
+  }
+
+  const templateContent = fs.readFileSync(envTemplatePath, 'utf8');
+  const vars = extractKvVarsFromTemplate(templateContent);
+
+  if (vars.length === 0) {
+    logger.log(chalk.yellow('No KV_* variables in env.template. Nothing to prompt.'));
+    return envPath;
+  }
+
+  const existingMap = loadExistingEnvMap(envPath);
+  logger.log(chalk.blue(`\nEnter credential values for ${systemKey} (integration/${systemKey}/):`));
+  const promptValues = await promptForKvValues(vars, existingMap);
+  const content = buildEnvContent(templateContent, promptValues);
+
+  const dir = path.dirname(envPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(envPath, content, { mode: 0o600 });
+  logger.log(chalk.green(`✓ Wrote ${envPath}`));
+  return envPath;
+}
+
+module.exports = { runCredentialEnv, validateSystemKeyFormat, extractKvVarsFromTemplate, buildEnvContent };