@aifabrix/builder 2.44.4 → 2.44.6

package/lib/commands/wizard.js

@@ -26,6 +26,7 @@ const {
   validateAndCheckAppDirectory,
   formatDataplaneRejectedTokenMessage,
   extractSessionId,
+  handleSourceSelection,
   handleOpenApiParsing,
   handleCredentialSelection,
   handleTypeDetection,
@@ -49,6 +50,150 @@ const {
   ensureIntegrationDir
 } = require('./wizard-helpers');
 const { humanizeAppKey } = require('../generator/wizard-prompts-secondary');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
+
+/**
+ * Map resolved source type/data onto wizard state.source.
+ * @param {Object} state - Mutable wizard state
+ * @param {string} sourceType - Source type key
+ * @param {unknown} sourceData - Raw source payload from prompts
+ */
+function applySourceSelectionToState(state, sourceType, sourceData) {
+  state.source = { type: sourceType };
+  if (sourceType === 'openapi-file') state.source.filePath = sourceData;
+  else if (sourceType === 'openapi-url') state.source.url = sourceData;
+  else if (sourceType === 'mcp-server') state.source.serverUrl = JSON.parse(sourceData).serverUrl;
+  else if (sourceType === 'known-platform') state.source.platform = sourceData;
+}
+
+/**
+ * Interactive or prefill source selection (Step 2).
+ * @returns {Promise<{ sourceType: string, sourceData: unknown }>}
+ */
+async function resolveWizardSourcePhase(dataplaneUrl, sessionId, authConfig, platforms, prefill) {
+  if (prefill?.source?.type) {
+    logger.log(chalk.gray(
+      `Using source from wizard.yaml (${prefill.source.type}). Skipping source prompts.`
+    ));
+    return handleSourceSelection(dataplaneUrl, sessionId, authConfig, prefill.source);
+  }
+  return handleInteractiveSourceSelection(dataplaneUrl, sessionId, authConfig, platforms);
+}
+
+/**
+ * Credential selection with optional prefill (Step 3).
+ * @returns {Promise<string>} credentialIdOrKey for generation step
+ */
+async function resolveWizardCredentialPhase(dataplaneUrl, authConfig, prefill, state) {
+  if (prefill?.credential) {
+    state.credential = prefill.credential;
+    return handleCredentialSelection(dataplaneUrl, authConfig, prefill.credential);
+  }
+  const credentialAction = await promptForCredentialAction();
+  const configCredential = await resolveCredentialConfig(dataplaneUrl, authConfig, credentialAction);
+  state.credential = configCredential;
+  return handleCredentialSelection(dataplaneUrl, authConfig, configCredential);
+}
+
+/**
+ * Collect user intent and UI preferences (Step 5), with optional wizard.yaml prefill.
+ * @returns {Promise<{ userIntent: string, preferences: Object, hasPrefillIntent: boolean }>}
+ */
+async function collectIntentAndPreferences(preferencesPrefill) {
+  const prefillPrefs = preferencesPrefill;
+  const hasPrefillIntent =
+    prefillPrefs &&
+    typeof prefillPrefs.intent === 'string' &&
+    prefillPrefs.intent.trim().length > 0;
+
+  if (hasPrefillIntent) {
+    logger.log(chalk.gray(
+      'Using preferences from wizard.yaml (intent and toggles). Skipping preference prompts.'
+    ));
+    const level = prefillPrefs.fieldOnboardingLevel;
+    const validLevel = level === 'standard' || level === 'minimal' ? level : 'full';
+    return {
+      userIntent: prefillPrefs.intent.trim(),
+      preferences: {
+        fieldOnboardingLevel: validLevel,
+        mcp: Boolean(prefillPrefs.enableMCP),
+        abac: Boolean(prefillPrefs.enableABAC),
+        rbac: Boolean(prefillPrefs.enableRBAC)
+      },
+      hasPrefillIntent: true
+    };
+  }
+
+  const userIntent = await promptForUserIntent();
+  const preferences = await promptForUserPreferences();
+  return { userIntent, preferences, hasPrefillIntent: false };
+}
+
+/**
+ * Run Step 5 (generate), Step 6–7 (review), and save files; updates state.preferences.
+ * @param {Object} payload
+ * @param {string} payload.appKey - Application key
+ * @param {string} payload.dataplaneUrl - Dataplane URL
+ * @param {Object} payload.authConfig - Auth configuration
+ * @param {string} payload.sessionId - Wizard session ID
+ * @param {Object} payload.state - Mutable wizard state
+ * @param {Object} payload.flowOpts - Flow options (mode, systemIdOrKey, debug, prefill, etc.)
+ * @param {Object} payload.genInput - Generation inputs (openapiSpec, detectedType, credential…)
+ * @returns {Promise<Object|null>} Updated state or null if review cancelled
+ */
+async function completeWizardGenerateReviewSave(payload) {
+  const {
+    appKey,
+    dataplaneUrl,
+    authConfig,
+    sessionId,
+    state,
+    flowOpts,
+    genInput
+  } = payload;
+  const { mode, systemIdOrKey, debug, prefill } = flowOpts;
+  const genResult = await handleInteractiveConfigGeneration({
+    dataplaneUrl,
+    authConfig,
+    mode,
+    openapiSpec: genInput.openapiSpec,
+    detectedType: genInput.detectedType,
+    credentialIdOrKey: genInput.credentialIdOrKey,
+    systemIdOrKey,
+    sourceType: genInput.sourceType,
+    sourceData: genInput.sourceData,
+    entityName: genInput.entityName,
+    appName: appKey,
+    debug,
+    systemDisplayName: flowOpts.systemDisplayName,
+    preferencesPrefill: prefill?.preferences
+  });
+  const { systemConfig, datasourceConfigs, systemKey, preferences: savedPrefs } = genResult;
+  state.preferences = savedPrefs || {};
+
+  const finalConfigs = await handleConfigurationReview(
+    dataplaneUrl,
+    authConfig,
+    sessionId,
+    systemConfig,
+    datasourceConfigs,
+    { appKey, debug }
+  );
+  if (!finalConfigs) return null;
+
+  await handleFileSaving(
+    appKey,
+    finalConfigs.systemConfig,
+    finalConfigs.datasourceConfigs,
+    systemKey || appKey,
+    {
+      dataplaneUrl,
+      authConfig,
+      enableRBAC: Boolean(savedPrefs?.enableRBAC)
+    }
+  );
+  return state;
+}
 
 /**
  * Create wizard session with given mode and optional systemIdOrKey (no prompts)
@@ -125,12 +270,15 @@ async function handleInteractiveSourceSelection(dataplaneUrl, sessionId, authCon
  * @param {Object} options.detectedType - Detected type info
  * @param {string} [options.credentialIdOrKey] - Credential ID or key (optional)
  * @param {string} [options.systemIdOrKey] - System ID or key (optional)
+ * @param {Object} [options.preferencesPrefill] - From wizard.yaml `preferences` (skip Step 5 prompts when intent is set)
  * @returns {Promise<Object>} Generated configuration and preferences { systemConfig, datasourceConfigs, systemKey, preferences }
  */
 async function handleInteractiveConfigGeneration(options) {
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 5: User Preferences'));
-  const userIntent = await promptForUserIntent();
-  const preferences = await promptForUserPreferences();
+
+  const { userIntent, preferences, hasPrefillIntent } = await collectIntentAndPreferences(
+    options.preferencesPrefill
+  );
 
   const configPrefs = {
     intent: userIntent,
@@ -138,6 +286,9 @@ async function handleInteractiveConfigGeneration(options) {
     enableMCP: preferences.mcp,
     enableABAC: preferences.abac,
     enableRBAC: preferences.rbac,
+    enableOpenAPIGeneration: hasPrefillIntent
+      ? options.preferencesPrefill?.enableOpenAPIGeneration !== false
+      : true,
     debug: options.debug === true
   };
 
@@ -222,62 +373,43 @@ async function handleConfigurationReview(dataplaneUrl, authConfig, sessionId, sy
  * @returns {Promise<Object>} Collected state (source, credential, preferences) for wizard.yaml save
  */
 async function doWizardSteps(appKey, dataplaneUrl, authConfig, sessionId, flowOpts, state) {
-  const { mode, systemIdOrKey, platforms, debug } = flowOpts;
-  const { sourceType, sourceData } = await handleInteractiveSourceSelection(
-    dataplaneUrl, sessionId, authConfig, platforms
+  const { platforms, prefill } = flowOpts;
+
+  const { sourceType, sourceData } = await resolveWizardSourcePhase(
+    dataplaneUrl,
+    sessionId,
+    authConfig,
+    platforms,
+    prefill
   );
-  state.source = { type: sourceType };
-  if (sourceType === 'openapi-file') state.source.filePath = sourceData;
-  else if (sourceType === 'openapi-url') state.source.url = sourceData;
-  else if (sourceType === 'mcp-server') state.source.serverUrl = JSON.parse(sourceData).serverUrl;
-  else if (sourceType === 'known-platform') state.source.platform = sourceData;
+  applySourceSelectionToState(state, sourceType, sourceData);
 
   const openapiSpec = await handleOpenApiParsing(dataplaneUrl, authConfig, sourceType, sourceData);
-  const credentialAction = await promptForCredentialAction();
-  const configCredential = await resolveCredentialConfig(dataplaneUrl, authConfig, credentialAction);
-  state.credential = configCredential;
-  const credentialIdOrKey = await handleCredentialSelection(dataplaneUrl, authConfig, configCredential);
+  const credentialIdOrKey = await resolveWizardCredentialPhase(dataplaneUrl, authConfig, prefill, state);
 
   const detectedType = await handleTypeDetection(dataplaneUrl, authConfig, openapiSpec);
+  const prefillEntityName = prefill?.source?.entityName;
   const entityName = openapiSpec && sourceType !== 'known-platform'
-    ? await handleEntitySelection(dataplaneUrl, authConfig, openapiSpec) : null;
-  const genResult = await handleInteractiveConfigGeneration({
-    dataplaneUrl,
-    authConfig,
-    mode,
-    openapiSpec,
-    detectedType,
-    credentialIdOrKey,
-    systemIdOrKey,
-    sourceType,
-    sourceData,
-    entityName: entityName || undefined,
-    appName: appKey,
-    debug,
-    systemDisplayName: flowOpts.systemDisplayName
-  });
-  const { systemConfig, datasourceConfigs, systemKey, preferences: savedPrefs } = genResult;
-  state.preferences = savedPrefs || {};
-
-  const finalConfigs = await handleConfigurationReview(
+    ? await handleEntitySelection(dataplaneUrl, authConfig, openapiSpec, prefillEntityName) : null;
+  if (entityName && state.source) {
+    state.source.entityName = entityName;
+  }
+  return completeWizardGenerateReviewSave({
+    appKey,
     dataplaneUrl,
     authConfig,
     sessionId,
-    systemConfig,
-    datasourceConfigs,
-    { appKey, debug }
-  );
-  if (!finalConfigs) return null;
-
-  await handleFileSaving(
-    appKey,
-    finalConfigs.systemConfig,
-    finalConfigs.datasourceConfigs,
-    systemKey || appKey,
-    dataplaneUrl,
-    authConfig
-  );
-  return state;
+    state,
+    flowOpts,
+    genInput: {
+      openapiSpec,
+      detectedType,
+      credentialIdOrKey,
+      sourceType,
+      sourceData,
+      entityName: entityName || undefined
+    }
+  });
 }
 
 async function runWizardStepsAfterSession(appKey, dataplaneUrl, authConfig, sessionId, flowOpts) {
@@ -317,14 +449,14 @@ async function runWizardStepsAfterSession(appKey, dataplaneUrl, authConfig, sess
  * @returns {Promise<void>} Resolves when wizard flow completes
  */
 async function executeWizardFlow(appKey, dataplaneUrl, authConfig, flowOpts = {}) {
-  const { mode, systemIdOrKey, configPath, debug, systemDisplayName } = flowOpts;
+  const { mode, systemIdOrKey, configPath, debug, systemDisplayName, prefill } = flowOpts;
 
   if (debug) {
     logger.log(chalk.gray(`[DEBUG] Wizard debug mode enabled for app: ${appKey}`));
   }
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 1: Create Session'));
   const sessionId = await createSessionFromParams(dataplaneUrl, authConfig, mode, systemIdOrKey, appKey);
-  logger.log(chalk.green('\u2713 Session created'));
+  logger.log(formatSuccessLine('Session created'));
 
   const platforms = mode === 'add-datasource' ? [] : await getWizardPlatforms(dataplaneUrl, authConfig);
   const state = await runWizardStepsAfterSession(appKey, dataplaneUrl, authConfig, sessionId, {
@@ -333,7 +465,8 @@ async function executeWizardFlow(appKey, dataplaneUrl, authConfig, flowOpts = {}
     platforms,
     configPath,
     debug: flowOpts.debug,
-    systemDisplayName
+    systemDisplayName,
+    prefill
   });
   if (!state) return;
 
@@ -348,6 +481,11 @@ async function executeWizardFlow(appKey, dataplaneUrl, authConfig, flowOpts = {}
  * @param {string} [appName] - App name (for log message)
  * @returns {Promise<Object|null>} Loaded config or null
  */
+/**
+ * Load wizard.yaml when present. Returns full valid config, or invalid-but-parsed config for interactive prefill.
+ *
+ * @returns {Promise<{ valid: true, config: Object } | { valid: false, config: Object, errors: string[] } | null>}
+ */
 async function loadWizardConfigIfExists(configPath, appName) {
   if (!configPath) return null;
   const displayPath = appName ? `integration/${appName}/wizard.yaml` : configPath;
@@ -360,10 +498,16 @@ async function loadWizardConfigIfExists(configPath, appName) {
     const result = await validateWizardConfig(configPath, { validateFilePaths: false });
     if (result.valid && result.config) {
       logger.log(chalk.green(`Loaded saved state from ${displayPath}. Resuming with saved choices.`));
-      return result.config;
+      return { valid: true, config: result.config };
     }
     if (result.errors?.length) {
-      logger.log(chalk.yellow(`Loaded ${displayPath} but it has errors; prompting for missing fields.`));
+      logger.log(chalk.yellow(
+        `Loaded ${displayPath} but it does not fully validate; prefilling from file where possible.`
+      ));
+      result.errors.forEach(err => logger.log(chalk.gray(`  • ${err}`)));
+    }
+    if (result.config) {
+      return { valid: false, config: result.config, errors: result.errors || [] };
     }
   } catch (e) {
     logger.log(chalk.gray(`Could not load wizard config from ${displayPath}: ${e.message}`));
@@ -470,15 +614,16 @@ async function handleWizardWithSavedConfig(options, loadedConfig, displayPath) {
 }
 
 async function handleWizardInteractive(options) {
+  const prefill = options.wizardPrefill;
   const allowAddDatasource = !options.app;
   const mode = allowAddDatasource ? await promptForMode(undefined, true) : 'create-system';
   const resolved = mode === 'create-system'
-    ? await resolveCreateNewPath(options, null)
-    : await resolveAddDatasourcePath(options, null);
+    ? await resolveCreateNewPath(options, prefill || null)
+    : await resolveAddDatasourcePath(options, prefill || null);
   if (!resolved) return;
   const { appKey, configPath, dataplaneUrl, authConfig } = resolved;
   const systemIdOrKey = mode === 'add-datasource' ? resolved.systemIdOrKey : undefined;
-  const systemDisplayName = options.systemDisplayName || options.displayName ||
+  const systemDisplayName = options.systemDisplayName || options.displayName || prefill?.systemDisplayName ||
     (mode === 'create-system' ? humanizeAppKey(appKey) : undefined);
   try {
     await executeWizardFlow(appKey, dataplaneUrl, authConfig, {
@@ -486,7 +631,8 @@ async function handleWizardInteractive(options) {
       systemIdOrKey,
       configPath,
       debug: options.debug,
-      systemDisplayName
+      systemDisplayName,
+      prefill: prefill || undefined
     });
     logger.log(chalk.gray(`To change settings, edit integration/${appKey}/wizard.yaml and run: aifabrix wizard ${appKey}`));
   } catch (error) {
@@ -504,9 +650,12 @@ async function handleWizard(options = {}) {
     return await handleWizardSilent(options);
   }
   logger.log(chalk.blue('\n\uD83E\uDDD9 AI Fabrix External System Wizard\n'));
-  const loadedConfig = await loadWizardConfigIfExists(options.configPath, options.app);
-  if (loadedConfig) {
-    return await handleWizardWithSavedConfig(options, loadedConfig, displayPath);
+  const loadResult = await loadWizardConfigIfExists(options.configPath, options.app);
+  if (loadResult?.valid && loadResult.config) {
+    return await handleWizardWithSavedConfig(options, loadResult.config, displayPath);
+  }
+  if (loadResult?.config && loadResult.valid === false) {
+    return await handleWizardInteractive({ ...options, wizardPrefill: loadResult.config });
   }
   return await handleWizardInteractive(options);
 }

package/lib/constants/infra-compose-service-names.js

@@ -0,0 +1,40 @@
+/**
+ * Infra compose service names accepted by `aifabrix restart` and {@link restartService}.
+ *
+ * @fileoverview Single source of truth for CLI help + validation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+/** @type {ReadonlyArray<{ name: string, description: string }>} */
+const RESTARTABLE_INFRA_SERVICES = Object.freeze([
+  { name: 'postgres', description: 'PostgreSQL database' },
+  { name: 'redis', description: 'Redis' },
+  { name: 'pgadmin', description: 'pgAdmin 4 web UI (only if enabled when you ran up-infra)' },
+  { name: 'redis-commander', description: 'Redis Commander web UI (only if enabled when you ran up-infra)' },
+  { name: 'traefik', description: 'Traefik reverse proxy (only if enabled when you ran up-infra)' }
+]);
+
+/**
+ * @returns {string[]} service names in compose order
+ */
+function getRestartableInfraServiceNames() {
+  return RESTARTABLE_INFRA_SERVICES.map((s) => s.name);
+}
+
+/**
+ * Aligned lines for Commander `addHelpText('after', …)`.
+ * @returns {string}
+ */
+function buildRestartInfraHelpLines() {
+  const col = 22;
+  return RESTARTABLE_INFRA_SERVICES.map((s) => `  ${s.name.padEnd(col)}${s.description}`).join('\n');
+}
+
+module.exports = {
+  RESTARTABLE_INFRA_SERVICES,
+  getRestartableInfraServiceNames,
+  buildRestartInfraHelpLines
+};

package/lib/core/env-reader.js

@@ -115,6 +115,19 @@ function detectSensitiveValue(key, value) {
   return false;
 }
 
+/**
+ * Path segment after `kv://` for sensitive env vars; must match infra.parameter.yaml keys.
+ * API_KEY uses the shared miso-controller/dataplane catalog entry (not a flat `api-key` slug).
+ * @param {string} key - Environment variable name
+ * @returns {string}
+ */
+function sensitiveKvPathSegmentFromEnvKey(key) {
+  if (key === 'API_KEY') {
+    return 'miso-controller-secrets-apiKeyVault';
+  }
+  return key.toLowerCase().replace(/[^a-z0-9]/g, '-');
+}
+
 /**
  * Convert existing .env variables to env.template format
  * @param {Object} existingEnv - Existing environment variables
@@ -128,7 +141,7 @@ function convertToEnvTemplate(existingEnv, requiredVars) {
   Object.entries(existingEnv).forEach(([key, value]) => {
     if (detectSensitiveValue(key, value)) {
       // Convert sensitive values to kv:// references
-      convertedEnv[key] = `kv://${key.toLowerCase().replace(/[^a-z0-9]/g, '-')}`;
+      convertedEnv[key] = `kv://${sensitiveKvPathSegmentFromEnvKey(key)}`;
     } else {
       // Keep non-sensitive values as-is
       convertedEnv[key] = value;
@@ -148,8 +161,8 @@ function generateSecretsFromEnv(envVars) {
 
   Object.entries(envVars).forEach(([key, value]) => {
     if (detectSensitiveValue(key, value)) {
-      // Use centralized resolver for canonical secret names
-      const secretName = getCanonicalSecretName(key);
+      const secretName =
+        key === 'API_KEY' ? sensitiveKvPathSegmentFromEnvKey(key) : getCanonicalSecretName(key);
       secrets[secretName] = value;
     }
   });

package/lib/core/secrets-admin-env.js

@@ -0,0 +1,101 @@
+/**
+ * Infrastructure admin-secrets.env generation (PG/Redis Commander defaults).
+ *
+ * @fileoverview Split from secrets.js for module size limits
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../utils/logger');
+const config = require('./config');
+const {
+  mergeInfraParameterDefaultsForCli,
+  getInfraParameterCatalog,
+  readRelaxedCatalogDefaults
+} = require('../parameters/infra-parameter-catalog');
+const { createDefaultSecrets } = require('../utils/secrets-generator');
+const pathsUtil = require('../utils/paths');
+const { loadSecrets } = require('./secrets-load');
+
+/**
+ * Writes admin env key-value pairs to content; encrypts values when encryption key is set.
+ * @async
+ * @param {Object.<string, string>} adminObj - Key-value object (e.g. POSTGRES_PASSWORD, ...)
+ * @returns {Promise<string>} .env-style content (plaintext or secure:// for secrets)
+ */
+async function formatAdminSecretsContent(adminObj) {
+  const encryptionKey = await config.getSecretsEncryptionKey();
+  const { encryptSecret } = require('../utils/secrets-encryption');
+  const lines = ['# Infrastructure Admin Credentials'];
+  for (const [k, v] of Object.entries(adminObj)) {
+    const value = (v === null || v === undefined) ? '' : String(v).replace(/\n/g, ' ').trim();
+    const valueToWrite = encryptionKey ? encryptSecret(value, encryptionKey) : value;
+    lines.push(`${k}=${valueToWrite}`);
+  }
+  return lines.join('\n');
+}
+
+async function loadSecretsOrBootstrapForAdmin(secretsPath) {
+  try {
+    return await loadSecrets(secretsPath);
+  } catch (error) {
+    const defaultSecretsPath = secretsPath || path.join(pathsUtil.getAifabrixHome(), 'secrets.yaml');
+    if (!fs.existsSync(defaultSecretsPath)) {
+      logger.log('Creating default secrets file...');
+      await createDefaultSecrets(defaultSecretsPath);
+      return await loadSecrets(secretsPath);
+    }
+    throw error;
+  }
+}
+
+function getInfraDefaultsMergedForAdmin() {
+  try {
+    return mergeInfraParameterDefaultsForCli(getInfraParameterCatalog().data, {});
+  } catch {
+    return {};
+  }
+}
+
+function buildLocalAdminSecretsObject(secrets, infraDefaults) {
+  const raw = secrets['postgres-passwordKeyVault'];
+  const relaxed = readRelaxedCatalogDefaults();
+  const postgresPassword =
+    (raw && String(raw).trim()) ||
+    infraDefaults.adminPassword ||
+    relaxed.adminPassword ||
+    '';
+  const pgAdminEmail = infraDefaults.adminEmail || relaxed.adminEmail || '';
+  return {
+    POSTGRES_PASSWORD: postgresPassword,
+    PGADMIN_DEFAULT_EMAIL: pgAdminEmail,
+    PGADMIN_DEFAULT_PASSWORD: postgresPassword,
+    REDIS_HOST: 'local:redis:6379:0:',
+    REDIS_COMMANDER_USER: 'admin',
+    REDIS_COMMANDER_PASSWORD: postgresPassword
+  };
+}
+
+/** Generates admin secrets for infrastructure (beside config.yaml, typically ~/.aifabrix/admin-secrets.env). Defaults from infra.parameter.yaml `defaults`. */
+async function generateAdminSecretsEnv(secretsPath) {
+  const secrets = await loadSecretsOrBootstrapForAdmin(secretsPath);
+  const infraDefaults = getInfraDefaultsMergedForAdmin();
+  const adminObj = buildLocalAdminSecretsObject(secrets, infraDefaults);
+  const aifabrixDir = pathsUtil.getAifabrixSystemDir();
+  const adminEnvPath = path.join(aifabrixDir, 'admin-secrets.env');
+  if (!fs.existsSync(aifabrixDir)) {
+    fs.mkdirSync(aifabrixDir, { recursive: true, mode: 0o700 });
+  }
+  const adminSecrets = await formatAdminSecretsContent(adminObj);
+  fs.writeFileSync(adminEnvPath, adminSecrets, { mode: 0o600 });
+  return adminEnvPath;
+}
+
+module.exports = {
+  formatAdminSecretsContent,
+  generateAdminSecretsEnv
+};

package/lib/core/secrets-ensure-infra.js

@@ -70,8 +70,41 @@ function getInfraSecretKeysForUpInfra() {
   }
 }
 
+/**
+ * Same merge as runtime `loadSecrets()` (user local + project path + remote shared API + defaults).
+ * Ensures missing-key checks treat remote `--shared` keys as already satisfied.
+ *
+ * @returns {Promise<Object.<string, string>>}
+ */
+async function loadMergedSecretsForEnsureMissingCheck() {
+  const { loadSecrets } = require('./secrets-load');
+  return loadSecrets(undefined);
+}
+
+/**
+ * Default on for writes to the primary user secrets file: consult full {@link loadSecrets} merge so remote
+ * `--shared` keys are not duplicated locally. Opt out with `useMergedSecretsForMissingKeys: false`.
+ *
+ * @param {{ useMergedSecretsForMissingKeys?: boolean }} options
+ * @param {{ type?: string, filePath?: string }} target
+ * @returns {boolean}
+ */
+function shouldUseMergedSecretsForMissingKeys(options, target) {
+  if (options.useMergedSecretsForMissingKeys === false) return false;
+  if (options.useMergedSecretsForMissingKeys === true) return true;
+  if (!target || target.type !== 'file' || !target.filePath) return false;
+  try {
+    const primary = pathsUtil.getPrimaryUserSecretsLocalPath();
+    return path.resolve(target.filePath) === path.resolve(primary);
+  } catch {
+    return false;
+  }
+}
+
 module.exports = {
   buildInfraPlaceholderContext,
   isSecretKeyAllowedEmpty,
-  getInfraSecretKeysForUpInfra
+  getInfraSecretKeysForUpInfra,
+  loadMergedSecretsForEnsureMissingCheck,
+  shouldUseMergedSecretsForMissingKeys
 };