@aifabrix/builder 2.45.5 → 2.47.0

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

@@ -15,12 +15,19 @@
  */
 
 const { handleCommandError } = require('../utils/cli-utils');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
 const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
 const { TEST_INTEGRATION_HELP_AFTER } = require('./setup-app.help');
+const {
+  UPLOAD_HELP_AFTER,
+  DOWNLOAD_HELP_AFTER,
+  DELETE_HELP_AFTER
+} = require('./setup-external-system-help');
 
 function setupDownloadCommand(program) {
   program.command('download <systemKey>')
     .description('Pull external system from dataplane into integration/<key>/')
+    .addHelpText('after', DOWNLOAD_HELP_AFTER)
     .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')
@@ -43,6 +50,7 @@ function setupDownloadCommand(program) {
 function setupUploadCommand(program) {
   program.command('upload <systemKey>')
     .description('Validate, publish to dataplane, and register with controller (draft application); or upload .protection batch')
+    .addHelpText('after', UPLOAD_HELP_AFTER)
     .option('--dry-run', 'Validate and build payload only; no API calls')
     .option('--no-sync', 'For .protection: skip datasource sync after upload')
     .option('--json', 'For .protection: JSON output')
@@ -55,6 +63,10 @@ function setupUploadCommand(program) {
       '--no-cert-sync',
       'Skip updating the system file certification block from the dataplane active certificate after publish'
     )
+    .option(
+      '--force',
+      'Bypass schema guards on active datasources during publish (dangerous; shows a warning)'
+    )
     .action(async(systemKey, options) => {
       try {
         const { isProtectionScope } = require('../protection/scope');
@@ -97,6 +109,7 @@ function setupUploadCommand(program) {
 function setupDeleteCommand(program) {
   program.command('delete <systemKey>')
     .description('Remove external system and its datasources from dataplane')
+    .addHelpText('after', DELETE_HELP_AFTER)
     .option('--type <type>', 'Application type (default: external; use "external" to target integration/<systemKey>)')
     .option('--yes', 'Skip confirmation prompt')
     .option('--force', 'Skip confirmation prompt (alias for --yes)')
@@ -168,7 +181,7 @@ async function runExternalSystemTestIntegration(appName, options) {
     environment: options.env || options.environment,
     debug: options.debug,
     perDatasource: options.perDatasource,
-    sync: options.sync === true
+    noSync: cliOptsSkipSync(options)
   };
   const results = await test.testExternalSystemIntegration(appName, opts);
   test.displayIntegrationTestResults(results, options.verbose, { debug: options.debug, runType: 'integration' });
@@ -225,9 +238,17 @@ function setupExternalSystemTestCommands(program) {
     .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)', 'dev')
     .option('-v, --verbose', 'Show detailed test output')
     .option('-d, --debug', 'Include debug output and write log to integration/<systemKey>/logs/')
+    .option(
+      '--no-sync',
+      'Skip publishing local integration files; use system config already on the dataplane'
+    )
     .option(
       '--sync',
-      'Publish local system and datasource files to the dataplane before running tests (same as aifabrix upload <systemKey>)'
+      'Publish local system and datasource files before tests (default for external integration; same as upload)'
+    )
+    .option(
+      '--force',
+      'With --sync, pass force to upload (bypass active-datasource schema replacement guards; same as aifabrix upload --force)'
     )
     .option('--warnings-as-errors', 'Treat aggregate warn as failure (exit 1)')
     .option('--require-cert', 'Require certification passed on every datasource (exit 2 if not)')
@@ -242,7 +263,8 @@ function setupExternalSystemTestCommands(program) {
         const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
         const opts = {
           ...options,
-          env: envExplicit ? options.env : undefined
+          env: envExplicit ? options.env : undefined,
+          noSync: cliOptsSkipSync(options, cmd)
         };
         await runTestIntegrationCommand(appName, opts);
       } catch (error) {

package/lib/cli/setup-infra-up-dataplane-action.js

@@ -15,7 +15,7 @@ const { handleCommandError, isAuthenticationError } = require('../utils/cli-util
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { handleLogin } = require('../commands/login');
 const { handleUpDataplane } = require('../commands/up-dataplane');
-const { cleanBuilderAppDirs } = require('../commands/up-common');
+const { cleanBuilderAppDirs, DATAPLANE_BUILDER_APP_KEYS } = require('../commands/up-common');
 const { runGuidedUpDataplane } = require('./infra-guided');
 const { recordInfraInstallationCommand } = require('./installation-log-command');
 
@@ -26,7 +26,7 @@ const { recordInfraInstallationCommand } = require('./installation-log-command')
 async function runUpDataplaneWork(options) {
   let cleanedAppKeys = [];
   if (options.force) {
-    const c = await cleanBuilderAppDirs(['dataplane']);
+    const c = await cleanBuilderAppDirs([...DATAPLANE_BUILDER_APP_KEYS]);
     cleanedAppKeys = Array.isArray(c) ? c : [];
   }
   if (!options.verbose) {

package/lib/cli/setup-infra-up-platform-action.js

@@ -19,6 +19,7 @@ const { handleUpDataplane } = require('../commands/up-dataplane');
 const {
   applyUpPlatformForceConfig,
   cleanBuilderAppDirs,
+  PLATFORM_BUILDER_CLEAN_APP_KEYS,
   prepareUrlsLocalRegistryForUpPlatform
 } = require('../commands/up-common');
 const { runGuidedUpPlatform } = require('./infra-guided');
@@ -35,7 +36,7 @@ async function runUpPlatformWork(options) {
   let platformForceCleanSummary = null;
   if (options.force) {
     const forceSummary = await applyUpPlatformForceConfig({ silent: !options.verbose });
-    const cleanedApps = await cleanBuilderAppDirs(PLATFORM_APPS, {
+    const cleanedApps = await cleanBuilderAppDirs(PLATFORM_BUILDER_CLEAN_APP_KEYS, {
       silent: !options.verbose
     });
     cleanedAppKeys = Array.isArray(cleanedApps) ? cleanedApps : [];

package/lib/cli/setup-infra.js

@@ -134,6 +134,8 @@ async function runUpInfraCommand(options) {
   const cfg = await config.getConfig();
   await persistOptionalInfraFlagsFromCli(options, cfg);
   await maybePersistTlsFromUpInfra(options, cfg);
+  const { passwordBundleFromCliOptions } = require('../core/admin-secrets-bundle');
+  const bundle = passwordBundleFromCliOptions(options);
   const adminPass = options.adminPassword || options.adminPwd;
   const tlsEnabledEffective = cfg.tlsEnabled === true;
   const effective = computeEffectiveInfraOptionalFlags(cfg, options);
@@ -145,6 +147,8 @@ async function runUpInfraCommand(options) {
     adminPwd: adminPass,
     adminEmail: options.adminEmail,
     userPassword: options.userPassword,
+    passwordBundle: bundle,
+    syncAdminKv: options.syncAdminKv === true,
     tlsEnabled: tlsEnabledEffective
   });
   await persistMissingInfraOptionalServiceFlags(cfg, effective);
@@ -156,8 +160,12 @@ function setupUpInfraCommand(program) {
     .addHelpText('after', UP_INFRA_HELP_AFTER)
     .option('-d, --developer <id>', 'Set developer ID and start infrastructure')
     .option('--verbose', 'Show full orchestration output (default is guided summary)')
-    .option('--adminPassword <password>', 'Override {{adminPassword}} defaults (Postgres, pgAdmin, Redis Commander, catalog literals)')
+    .option('--adminPassword <password>', 'Override admin password (dev: all roles; pro manual-single)')
     .option('--adminEmail <email>', 'Override {{adminEmail}} default (e.g. pgAdmin login email)')
+    .option('--infraAdminPassword <password>', 'Pro profile: infra DB/pgAdmin/Redis Commander password')
+    .option('--keycloakAdminPassword <password>', 'Pro profile: Keycloak install admin password')
+    .option('--platformAdminPassword <password>', 'Pro profile: platform UI login password (user admin)')
+    .option('--syncAdminKv', 'Also sync {{adminPassword}} catalog keys into secrets.local.yaml (legacy)')
     .option('--userPassword <password>', 'Override {{userPassword}} default (e.g. Keycloak default user password)')
     .option('--pgAdmin', 'Include pgAdmin web UI and save to config')
     .option('--no-pgAdmin', 'Exclude pgAdmin and save to config')

package/lib/cli/setup-platform.js

@@ -23,7 +23,7 @@ const { handleTeardown } = require('../commands/teardown');
 
 const SETUP_HELP_AFTER = `
 What this command does:
-  - With no infra running: prompts for admin email/password (used for Postgres, pgAdmin, Keycloak). The email is saved as adminEmail in config.yaml so the next setup can show it as the default (you can still change it). Prompts for an AI tool (OpenAI or Azure OpenAI) only when keys are not already set, then runs up-infra and up-platform.
+  - With no infra running: prompts for installation profile (dev = one password for infra + Keycloak + platform UI; pro = autogen or manual split passwords). Credentials are stored in admin-secrets.env (encrypted secure:// values), not in secrets.local.yaml unless you pass --syncAdminKv on up-infra. The admin email is saved in config.yaml for the next run. Prompts for an AI tool (OpenAI or Azure OpenAI) only when keys are not already set, then runs up-infra and up-platform.
   - With infra running: shows a mode menu:
       1) Re-install — stop infra and remove all volumes, then up-infra + up-platform --force.
       2) Wipe data — drop every database and DB user, then up-infra + up-platform --force.
@@ -54,6 +54,11 @@ function registerSetup(program) {
     .command('setup')
     .description('Install or refresh the full AI Fabrix platform (infra + miso + dataplane)')
     .option('-d, --developer <id>', 'Pin developer ID before fresh install (fresh path only; ignored when infra is already up)')
+    .option('--platform <mode>', 'Platform mode: single, single-traefik (Traefik + TLS), or full (multi-env; advanced)')
+    .option('--installation <profile>', 'Installation profile: dev (one password) or pro (autogen/manual)')
+    .option('--pro-password-mode <mode>', 'Pro profile only: autogen or manual')
+    .option('--admin-email <email>', 'Admin email (non-interactive fresh install)')
+    .option('--admin-password <password>', 'Admin password for dev or pro manual-single (non-interactive)')
     .option('-y, --yes', 'Skip destructive confirmation prompts (re-install, wipe data, teardown)')
     .addHelpText('after', SETUP_HELP_AFTER)
     .action(async(options) => {

package/lib/cli/setup-secrets.js

@@ -10,6 +10,7 @@ const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const { handleCommandError } = require('../utils/cli-utils');
 const { handleSecretsSet } = require('../commands/secrets-set');
 const { handleSecretsList } = require('../commands/secrets-list');
+const { handleSecretsGet } = require('../commands/secrets-get');
 const { handleSecretsRemove } = require('../commands/secrets-remove');
 const { handleSecretsValidate } = require('../commands/secrets-validate');
 const { handleSecure } = require('../commands/secure');
@@ -18,7 +19,7 @@ const logger = require('../utils/logger');
 
 const SECRET_GROUP_HELP_AFTER = `
 Subcommands:
-  list, set, remove, remove-all   User secrets.local.yaml (add --shared for shared/remote)
+  list, get, set, remove, remove-all   User secrets.local.yaml (add --shared for shared/remote)
   set-secrets-file      Point config at a shared secrets file or https URL
   validate              YAML structure (+ optional --naming)
 
@@ -38,6 +39,17 @@ Examples:
 Shared over https: key BASH_NPM_TOKEN --shared → NPM_TOKEN available in terminal (exported).
 `;
 
+const SECRET_GET_HELP_AFTER = `
+Examples:
+  $ aifabrix secret get hubspot-demo/token --shared --exists
+  $ aifabrix secret get myapp/clientSecret
+  $ aifabrix secret get hubspot/apiKey --shared --json
+
+  --exists   Script mode: exit 0 when the key is present and non-empty; no output.
+  Default      Local user secrets.local.yaml only (same target as secret set without --shared).
+  --shared     aifabrix-secrets store only (team file or remote API; same as secret set --shared).
+`;
+
 const SECRET_LIST_HELP_AFTER = `
 Examples:
   $ aifabrix secret list
@@ -168,6 +180,25 @@ function setupSecureCommand(program) {
     });
 }
 
+function setupSecretGetCommand(secretCmd) {
+  secretCmd
+    .command('get <key>')
+    .description('Get one secret (local user file by default; --shared for team store; --exists for scripts)')
+    .addHelpText('after', SECRET_GET_HELP_AFTER)
+    .option('--shared', 'Read from shared secrets (config aifabrix-secrets or remote API)')
+    .option('--exists', 'Exit 0 when key is present and non-empty; print nothing (for scripts)')
+    .option('--json', 'Output JSON { key, exists, value }')
+    .action(async(key, options) => {
+      try {
+        await config.ensureSecretsEncryptionKey();
+        await handleSecretsGet(key, options);
+      } catch (error) {
+        handleCommandError(error, 'secret get');
+        process.exit(1);
+      }
+    });
+}
+
 function setupSecretListCommand(secretCmd) {
   secretCmd
     .command('list')
@@ -196,6 +227,7 @@ function setupSecretsCommands(program) {
     .addHelpText('after', SECRET_GROUP_HELP_AFTER);
 
   setupSecretListCommand(secretCmd);
+  setupSecretGetCommand(secretCmd);
 
   secretCmd
     .command('set <key> <value>')

package/lib/cli/setup-utility-help-after.js

@@ -26,8 +26,11 @@ Examples:
   $ aifabrix repair hubspot-demo --dry-run
     Show what would change without writing files.
 
+  $ aifabrix repair hubspot-demo --auth bearerToken
+    Private-app style apikey: Authorization + Bearer prefix; preserves baseUrl/testEndpoint when present. Warns if testEndpoint is missing.
+
   $ aifabrix repair hubspot-demo --auth oauth2
-    Set authentication method; updates the system file and env.template (oauth2, aad, apikey, basic, …).
+    Set authentication method; updates the system file and env.template (oauth2, aad, apikey, bearerToken, basic, …).
 
   $ aifabrix repair hubspot-demo --rbac --expose --sync --test
     Optional datasource fixes: RBAC roles/permissions, exposed.schema from attributes, default sync block, testPayload stubs.
@@ -38,8 +41,28 @@ Examples:
   Before overwriting files, repair writes timestamped backups under integration/<systemKey>/backup/ (same as datasource capability copy). Use --no-backup to skip.
 `;
 
+const RESOLVE_HELP_AFTER = `
+Examples:
+  $ aifabrix resolve hubspot-demo
+    External integration: resolves integration/<systemKey>/env.template to .env using local host ports (no Docker rewrite).
+
+  $ aifabrix resolve dataplane --force
+    Seed missing secret keys and replace the full .env from env.template (no merge with an existing file).
+
+  $ aifabrix resolve dataplane --fresh
+    Replace the full .env only (no merge; does not seed missing secret keys). Same .env output as --force when secrets are already set.
+
+  $ aifabrix secret set hubspot-demo/token "<your-token>"
+    Store a secret when resolve reports a missing kv:// reference.
+
+  If a key is not required by your system file, comment out its line in env.template instead of creating a secret.
+  $ aifabrix repair hubspot-demo
+    Align env.template with authentication.security and comment stale OAuth KV lines after --auth bearerToken.
+`;
+
 module.exports = {
   JSON_HELP_AFTER,
   VALIDATE_HELP_AFTER,
-  REPAIR_HELP_AFTER
+  REPAIR_HELP_AFTER,
+  RESOLVE_HELP_AFTER
 };

package/lib/cli/setup-utility-repair.js

@@ -0,0 +1,198 @@
+/**
+ * `aifabrix repair` command wiring and CLI output (split from setup-utility for size limits).
+ *
+ * @fileoverview Repair CLI command
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { handleCommandError, logOfflinePathWhenType } = require('../utils/cli-utils');
+const { detectAppType } = require('../utils/paths');
+const { formatSuccessParagraph, formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { REPAIR_HELP_AFTER } = require('./setup-utility-help-after');
+
+/**
+ * @param {string} appName
+ * @param {object} options
+ * @param {string} format
+ * @returns {object}
+ */
+function buildRepairExternalIntegrationOptions(appName, options, format) {
+  const all = options.all === true;
+  return {
+    auth: options.auth,
+    doc: options.doc || all,
+    dryRun: options.dryRun,
+    format,
+    rbac: options.rbac || all,
+    expose: options.expose || all,
+    sync: options.sync || all,
+    api: options.api || all,
+    test: options.test || all,
+    backup: options.backup,
+    noBackup: options.noBackup
+  };
+}
+
+/**
+ * @param {string[]} changedFiles
+ * @param {boolean} dryRun
+ */
+function logRepairChangedFiles(changedFiles, dryRun) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) return;
+  const title = dryRun ? '\nWould change files:' : '\nChanged files:';
+  logger.log(chalk.white(title));
+  changedFiles.forEach((filePath) => logger.log(chalk.cyan(`  ${filePath}`)));
+}
+
+/**
+ * @param {string[]} warnings
+ */
+function logRepairWarnings(warnings) {
+  if (!Array.isArray(warnings) || warnings.length === 0) return;
+  warnings.forEach((msg) => logger.log(formatWarningLine(msg)));
+}
+
+/**
+ * @param {string[]} changedFiles
+ * @param {string[]} warnings
+ */
+function logRepairNextActions(changedFiles, warnings) {
+  const hasFiles = Array.isArray(changedFiles) && changedFiles.length > 0;
+  const hasWarnings = Array.isArray(warnings) && warnings.length > 0;
+  if (!hasFiles && !hasWarnings) return;
+  logger.log(chalk.white('\nNext actions:'));
+  if (hasFiles) {
+    logger.log(chalk.gray('  • Open the paths above in your editor and review the diff'));
+    logger.log(chalk.gray('  • Run: aifabrix validate <systemKey>'));
+  }
+  if (hasWarnings) {
+    logger.log(chalk.gray('  • Fix warnings in the system file (especially authentication.variables.testEndpoint)'));
+    logger.log(chalk.gray('  • Run: aifabrix json <systemKey> && aifabrix upload <systemKey>'));
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {object} result
+ * @param {string[]} changedFiles
+ */
+function logRepairDryRunOutcome(options, result, changedFiles) {
+  logger.log(chalk.yellow('\nWould apply:'));
+  result.changes.forEach((c) => logger.log(chalk.gray(`  ${c}`)));
+  logRepairChangedFiles(changedFiles, true);
+  logRepairWarnings(result.warnings);
+  logRepairNextActions(changedFiles, result.warnings);
+}
+
+/**
+ * @param {object} result
+ * @param {string[]} changedFiles
+ */
+function logRepairSuccessOutcome(result, changedFiles) {
+  if (result.updated) {
+    logger.log(formatSuccessParagraph('Repaired external integration config.'));
+    logRepairChangedFiles(changedFiles, false);
+    logRepairNextActions(changedFiles, result.warnings);
+    return;
+  }
+  if (Array.isArray(result.changes) && result.changes.length > 0) {
+    logger.log(formatSuccessParagraph('Repair actions completed.'));
+    result.changes.forEach((c) => logger.log(chalk.gray(`  ${c}`)));
+    logRepairChangedFiles(changedFiles, false);
+    logRepairNextActions(changedFiles, result.warnings);
+    return;
+  }
+  if (result.readmeRegenerated) {
+    logger.log(formatSuccessParagraph('Regenerated README.md from deployment manifest.'));
+    return;
+  }
+  if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+    logRepairNextActions(changedFiles, result.warnings);
+    return;
+  }
+  logger.log(chalk.gray('No changes needed; config already matches files on disk.'));
+}
+
+/**
+ * @param {object} options
+ * @param {object} result
+ */
+function logRepairResult(options, result) {
+  const changedFiles = result.changedFiles;
+  if (options.dryRun && result.updated && result.changes.length > 0) {
+    logRepairDryRunOutcome(options, result, changedFiles);
+    return;
+  }
+  if (Array.isArray(result.backupPaths) && result.backupPaths.length > 0) {
+    result.backupPaths.forEach((p) => logger.log(chalk.gray(`Backup: ${p}`)));
+  }
+  logRepairWarnings(result.warnings);
+  logRepairSuccessOutcome(result, changedFiles);
+}
+
+/**
+ * @param {string} appName
+ * @param {object} options
+ * @returns {Promise<void>}
+ */
+async function handleRepairCommand(appName, options) {
+  const { repairExternalIntegration } = require('../commands/repair');
+  const { appPath } = await detectAppType(appName);
+  logOfflinePathWhenType(appPath);
+  let format = 'yaml';
+  try {
+    const config = require('../core/config');
+    format = (await config.getFormat()) || format;
+  } catch (_) {
+    /* default yaml when config unavailable */
+  }
+  const result = await repairExternalIntegration(
+    appName,
+    buildRepairExternalIntegrationOptions(appName, options, format)
+  );
+  logRepairResult(options, result);
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupRepairCommand(program) {
+  program.command('repair <systemKey>')
+    .description('Fix external integration drift (files, RBAC, manifest, …)')
+    .option('--all', 'Run all repair actions (api, doc, expose, rbac, sync, test)')
+    .option(
+      '--api',
+      'Validate and sync API contracts needed for OpenAPI/MCP (uses local OpenAPI specs at integration/<systemKey>/openapi/*.json when present)'
+    )
+    .option(
+      '--auth <method>',
+      'Set authentication method (oauth2, aad, apikey, bearerToken, basic, queryParam, oidc, hmac, none); updates system file and env.template'
+    )
+    .option('--doc', 'Regenerate README.md from deployment manifest')
+    .option('--expose', 'Set exposed.schema on each datasource from all fieldMappings.attributes keys (metadata.<key>); removes deprecated exposed.attributes if present')
+    .option('--rbac', 'Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist')
+    .option('--sync', 'Add default sync section to datasources that lack it')
+    .option('--test', 'Generate testPayload.payloadTemplate and testPayload.expectedResult from attributes')
+    .option('--no-backup', 'Skip timestamped copies under integration/<systemKey>/backup/')
+    .option('--dry-run', 'Report changes only; do not write')
+    .addHelpText('after', REPAIR_HELP_AFTER)
+    .action(async(appName, options) => {
+      try {
+        await handleRepairCommand(appName, options);
+      } catch (error) {
+        handleCommandError(error, 'repair');
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  setupRepairCommand,
+  buildRepairExternalIntegrationOptions,
+  logRepairResult
+};

package/lib/cli/setup-utility-resolve.js

@@ -8,13 +8,18 @@
 
 'use strict';
 
+const path = require('path');
 const chalk = require('chalk');
 const secrets = require('../core/secrets');
+const secretsEnsure = require('../core/secrets-ensure');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
 const coreConfig = require('../core/config');
+const pathsUtil = require('../utils/paths');
 const { resolvePreferLocalEnvOutputPathFlag } = require('../utils/applications-config-defaults');
 const { getResolveAppPath } = require('../utils/paths');
+const { resolveGenerateEnvEnvironment } = require('../utils/resolve-env-mode');
+const { RESOLVE_HELP_AFTER } = require('./setup-utility-help-after');
 
 /**
  * @param {string} appName
@@ -50,10 +55,17 @@ async function runResolveJsonOutput(appName, appPath, envOnly, envPath, options,
  * @param {string} envPath
  * @param {boolean} envOnly
  * @param {{ skipValidation?: boolean }} options
+ * @param {'local'|'docker'} environment
  * @returns {Promise<void>}
  */
-async function runResolveHumanOutput(appName, envPath, envOnly, options) {
+async function runResolveHumanOutput(appName, envPath, envOnly, options, environment) {
   logger.log(`✔ Generated .env file: ${envPath}`);
+  if (options.fresh || options.force) {
+    logger.log(chalk.gray('  Wrote full resolved content (replaced existing .env from env.template; no merge).'));
+  }
+  if (environment === 'local') {
+    logger.log(chalk.gray('  Resolved for local use (host ports; no Docker port rewrite).'));
+  }
   logger.log(chalk.gray('  Note: up-platform / up-miso / up-dataplane / register / build resolve secrets in memory only.'));
   logger.log(chalk.gray(`  Re-run "aifabrix resolve ${appName}" whenever you need an on-disk .env again.`));
   if (envOnly) {
@@ -77,9 +89,26 @@ async function runResolveHumanOutput(appName, envPath, envOnly, options) {
  * @param {{ force?: boolean, skipValidation?: boolean, json?: boolean }} options
  * @returns {Promise<void>}
  */
+async function ensureResolveSecretsFromEnvTemplate(appPath, appName) {
+  const templatePath = path.join(appPath, 'env.template');
+  let emptyValuesForCredentials = false;
+  try {
+    const appType = await pathsUtil.detectAppType(appName);
+    emptyValuesForCredentials = appType?.baseDir === 'integration';
+  } catch {
+    emptyValuesForCredentials = false;
+  }
+  await secretsEnsure.ensureSecretsFromEnvTemplate(templatePath, {
+    preferredFilePath: pathsUtil.getPrimaryUserSecretsLocalPath(),
+    placeholderContext: secretsEnsure.buildInfraPlaceholderContext({}),
+    emptyValuesForCredentials
+  });
+}
+
 async function runResolveAppAction(appName, options) {
   const jsonMode = options.json === true;
   const { appPath, envOnly } = await getResolveAppPath(appName);
+  await ensureResolveSecretsFromEnvTemplate(appPath, appName);
   const manifestEmit = require('../utils/manifest-source-emit');
   manifestEmit.emitManifestMetadataLineIfTTY(logger, {
     appKey: appName,
@@ -89,24 +118,26 @@ async function runResolveAppAction(appName, options) {
   });
   const userCfg = await coreConfig.getConfig();
   const preferLocalEnvOutputPath = await resolvePreferLocalEnvOutputPathFlag(userCfg, appName);
+  const environment = resolveGenerateEnvEnvironment(appPath, appName);
   const envPath = await secrets.generateEnvFile(
     appName,
     undefined,
-    'docker',
+    environment,
     options.force,
     {
       appPath,
       envOnly,
       skipOutputPath: false,
       preserveFromPath: null,
-      preferLocalEnvOutputPath
+      preferLocalEnvOutputPath,
+      freshEnv: options.fresh === true || options.force === true
     }
   );
   if (jsonMode) {
     await runResolveJsonOutput(appName, appPath, envOnly, envPath, options, manifestEmit);
     return;
   }
-  await runResolveHumanOutput(appName, envPath, envOnly, options);
+  await runResolveHumanOutput(appName, envPath, envOnly, options, environment);
 }
 
 /**
@@ -116,7 +147,15 @@ async function runResolveAppAction(appName, options) {
 function setupResolveCommand(program) {
   program.command('resolve <appKey|systemKey>')
     .description('Generate .env from template (builder/<appKey>/ or integration/<systemKey>/); optional validate after')
-    .option('-f, --force', 'Generate missing secret keys in secrets file')
+    .addHelpText('after', RESOLVE_HELP_AFTER)
+    .option(
+      '-f, --force',
+      'Seed missing secret keys and replace .env from env.template (no merge with existing .env or envOutputPath)'
+    )
+    .option(
+      '--fresh',
+      'Same full .env replace as --force without seeding missing secret keys in the secrets file'
+    )
     .option('--skip-validation', 'Skip file validation after generating .env')
     .option('--json', 'Print JSON summary (envPath, manifestSource, optional validation)')
     .action(async(appName, options) => {