@aifabrix/builder 2.45.0 → 2.46.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')
@@ -42,8 +49,12 @@ function setupDownloadCommand(program) {
 
 function setupUploadCommand(program) {
   program.command('upload <systemKey>')
-    .description('Validate, publish to dataplane, and register with controller (draft application)')
+    .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')
+    .option('--warnings-as-errors', 'For .protection: pass strict=true to dataplane validate')
     .option('-v, --verbose', 'Run server-side pipeline validate and print warnings before publish')
     .option('--probe', 'After publish, run dataplane runtime checks (validation/run); slower')
     .option('--minimal', 'Print only a short readiness summary after upload')
@@ -52,8 +63,32 @@ 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');
+        if (isProtectionScope(systemKey)) {
+          const { uploadProtectionBatchCommand } = require('../protection/upload-batch');
+          const logger = require('../utils/logger');
+          const code = await uploadProtectionBatchCommand(
+            {
+              env: options.env,
+              dryRun: options.dryRun === true,
+              noSync: options.noSync === true,
+              json: options.json === true,
+              verbose: options.verbose === true,
+              warningsAsErrors: options.warningsAsErrors === true
+            },
+            logger
+          );
+          if (code !== 0) {
+            process.exit(code);
+          }
+          return;
+        }
         const upload = require('../commands/upload');
         const probeTimeout =
           options.probeTimeout === undefined || options.probeTimeout === null
@@ -74,11 +109,23 @@ 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)')
     .action(async(systemKey, options) => {
       try {
+        const { isProtectionScope } = require('../protection/scope');
+        if (isProtectionScope(systemKey)) {
+          const logger = require('../utils/logger');
+          const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
+          logger.error(
+            formatBlockingError(
+              'delete .protection is not supported. Use: aifabrix protection delete <datasourceKey>'
+            )
+          );
+          process.exit(1);
+        }
         const externalDelete = require('../external-system/delete');
         await externalDelete.deleteExternalSystem(systemKey, options);
       } catch (error) {
@@ -134,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' });
@@ -186,14 +233,22 @@ async function runTestIntegrationCommand(appName, options) {
 
 function setupExternalSystemTestCommands(program) {
   // 'test <app>' is registered in setup-app.js and dispatches by app type (builder vs external)
-  program.command('test-integration <app>')
-    .description('Integration tests: builder in container; external via dataplane')
+  program.command('test-integration <appKey|systemKey>')
+    .description('Integration tests: builder appKey in container; external systemKey via dataplane')
     .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)')
@@ -208,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.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 (direct ports) or full (Traefik front door + multi-env)')
+    .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

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Help-after strings for setup-utility CLI commands.
+ */
+
+'use strict';
+
+const JSON_HELP_AFTER = `
+Example:
+  $ aifabrix json myapp
+Generates *-deploy.json (or application-schema.json) for commit before deploy.
+`;
+
+const VALIDATE_HELP_AFTER = `
+Examples:
+  $ aifabrix validate myapp
+  $ aifabrix validate myapp --cert-sync
+  $ aifabrix validate --integration
+  $ aifabrix validate --builder
+`;
+
+const REPAIR_HELP_AFTER = `
+Examples:
+  $ aifabrix repair hubspot-demo
+    Align manifest, system/datasource files, RBAC extract, env.template, and deploy JSON under integration/<systemKey>/.
+
+  $ 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, 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.
+
+  $ aifabrix repair hubspot-demo --doc
+    Regenerate README.md from the current deployment manifest only (other drift fixes unchanged).
+
+  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 --fresh
+    Regenerate the full .env from env.template (no merge with an existing file). Use after adding many new variables or when a normal resolve did not pick up new template lines.
+
+  $ 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,
+  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) {
+    logger.log(chalk.gray('  Wrote full resolved content (--fresh; did not merge with an existing .env).'));
+  }
+  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
     }
   );
   if (jsonMode) {
     await runResolveJsonOutput(appName, appPath, envOnly, envPath, options, manifestEmit);
     return;
   }
-  await runResolveHumanOutput(appName, envPath, envOnly, options);
+  await runResolveHumanOutput(appName, envPath, envOnly, options, environment);
 }
 
 /**
@@ -114,9 +145,14 @@ async function runResolveAppAction(appName, options) {
  * @returns {void}
  */
 function setupResolveCommand(program) {
-  program.command('resolve <app>')
-    .description('Generate .env from template; optional validate after')
+  program.command('resolve <appKey|systemKey>')
+    .description('Generate .env from template (builder/<appKey>/ or integration/<systemKey>/); optional validate after')
+    .addHelpText('after', RESOLVE_HELP_AFTER)
     .option('-f, --force', 'Generate missing secret keys in secrets file')
+    .option(
+      '--fresh',
+      'Replace .env from env.template (no merge with existing .env or envOutputPath; same as deleting .env first)'
+    )
     .option('--skip-validation', 'Skip file validation after generating .env')
     .option('--json', 'Print JSON summary (envPath, manifestSource, optional validation)')
     .action(async(appName, options) => {