@aifabrix/builder 2.57.0 → 2.58.0

package/lib/app/push.js

@@ -93,23 +93,24 @@ function extractImageName(config, appName) {
  */
 async function loadPushConfig(appName, options) {
   const { loadConfigFile } = require('../utils/config-format');
+  const { resolveEffectiveRegistry, stripRegistryHostFromRepository } = require('../utils/resolve-docker-image-ref');
+  let config;
   try {
     const { appPath } = await paths.detectAppType(appName);
-    const configPath = paths.resolveApplicationConfigPath(appPath);
-    const config = loadConfigFile(configPath);
-    const effective = getEffectiveConfig(config);
-    const registry = options.registry || effective.image?.registry;
-    if (!registry) {
-      throw new Error('Registry URL is required. Provide via --registry flag or configure in application config under image.registry');
-    }
-    const imageName = extractImageName(config, appName);
-    return { registry, imageName };
+    config = loadConfigFile(paths.resolveApplicationConfigPath(appPath));
   } catch (error) {
-    if (error.message.includes('Registry URL')) {
-      throw error;
-    }
     throw new Error(`Failed to load configuration: ${error.message}\nRun 'aifabrix create ${appName}' first`);
   }
+  const effective = getEffectiveConfig(config);
+  const { registry } = resolveEffectiveRegistry(effective, { registry: options.registry });
+  if (!registry) {
+    throw new Error(
+      'Registry URL is required. Provide --registry, run "aifabrix dev set-registry <registry>", ' +
+      'or configure image.registry in the application config'
+    );
+  }
+  const imageName = stripRegistryHostFromRepository(extractImageName(config, appName));
+  return { registry, imageName, appVersion: require('../utils/image-tags').readAppVersion(effective) };
 }
 
 /**
@@ -129,10 +130,43 @@ async function validatePushConfig(registry, imageName, appName) {
     throw new Error(`Invalid registry URL format: ${registry}. Expected format: *.azurecr.io`);
   }
 
-  if (!await pushUtils.checkLocalImageExists(imageName, 'latest')) {
-    throw new Error(`Docker image ${imageName}:latest not found locally.\nRun 'aifabrix build ${appName}' first`);
+  const sourceRef = await resolveLocalSourceRef(registry, imageName);
+  if (!sourceRef) {
+    throw new Error(`Docker image ${registry}/${imageName}:latest or ${imageName}:latest not found locally.\nRun 'aifabrix build ${appName}' first`);
+  }
+
+  const { getRegistryCredentialStatus } = require('../utils/registry-credentials');
+  const credentialStatus = getRegistryCredentialStatus(registry);
+  if (credentialStatus === 'partial') {
+    await require('../utils/registry-credentials').loadRegistryCredentials(registry);
+  }
+  if (credentialStatus === 'complete') {
+    return sourceRef;
+  }
+  await validateAzureCli();
+  return sourceRef;
+}
+
+/**
+ * Local image to push from: the registry-qualified build output first, else the plain repository.
+ * @param {string} registry - Registry host
+ * @param {string} imageName - Repository without host
+ * @returns {Promise<string|null>} `repository:latest` or null
+ */
+async function resolveLocalSourceRef(registry, imageName) {
+  for (const repository of [`${registry}/${imageName}`, imageName]) {
+    if (await pushUtils.checkLocalImageExists(repository, 'latest')) {
+      return `${repository}:latest`;
+    }
   }
+  return null;
+}
 
+/**
+ * Azure CLI prerequisites for the ACR login fallback (no stored registry credentials).
+ * @returns {Promise<void>}
+ */
+async function validateAzureCli() {
   if (!await pushUtils.checkAzureCLIInstalled()) {
     throw new Error('Azure CLI is not installed. Install from: https://docs.microsoft.com/cli/azure/install-azure-cli');
   }
@@ -149,7 +183,7 @@ async function validatePushConfig(registry, imageName, appName) {
  * @async
  * @param {string} registry - Registry URL
  */
-async function authenticateWithRegistry(registry) {
+async function authenticateWithAzureCli(registry) {
   if (await pushUtils.checkACRAuthentication(registry)) {
     logger.log(formatSuccessLine(`Already authenticated with ${registry}`));
   } else {
@@ -157,6 +191,16 @@ async function authenticateWithRegistry(registry) {
   }
 }
 
+/**
+ * Stored host-scoped credentials first (stdin login), else Azure CLI. Once per command.
+ * @param {string} registry - Registry host
+ * @returns {Promise<void>}
+ */
+async function authenticateWithRegistry(registry) {
+  const { ensureRegistryLogin } = require('../utils/registry-credentials');
+  await ensureRegistryLogin(registry, { fallback: authenticateWithAzureCli });
+}
+
 /**
  * Layout-aligned notice when push is skipped for external integrations.
  * @param {string} appName
@@ -191,30 +235,43 @@ function logPushCommandHeader(appName, registry, imageName) {
  * @param {string} registry - Registry URL
  * @param {Array<string>} tags - Image tags
  */
-async function pushImageTags(imageName, registry, tags) {
-  try {
-    await Promise.all(tags.map(async(tag) => {
-      await pushUtils.tagImage(`${imageName}:latest`, `${registry}/${imageName}:${tag}`);
-      await pushUtils.pushImage(`${registry}/${imageName}:${tag}`, registry);
-    }));
-  } catch (error) {
-    // If authentication error, try to re-authenticate and retry once
-    const errorMessage = error.message || String(error);
-    const isAuthError = errorMessage.includes('Authentication required') ||
-                        errorMessage.includes('authentication required') ||
-                        (errorMessage.includes('authentication') && errorMessage.includes('401'));
+function isAuthenticationError(error) {
+  const message = (error && error.message) || String(error);
+  return message.includes('Authentication required') ||
+    message.includes('authentication required') ||
+    (message.includes('authentication') && message.includes('401'));
+}
+
+async function tagAndPushOne(sourceRef, targetRef, registry) {
+  if (sourceRef !== targetRef) {
+    await pushUtils.tagImage(sourceRef, targetRef);
+  }
+  await pushUtils.pushImage(targetRef, registry);
+}
 
-    if (isAuthError) {
-      logger.log(
-        formatWarningLine('Registry authentication expired; re-authenticating, then retrying push.')
-      );
+/**
+ * Tags and pushes every unique target once, re-authenticating once on an auth failure.
+ * @async
+ * @param {string} sourceRef - Local source image
+ * @param {string} imageName - Repository without host
+ * @param {string} registry - Registry host
+ * @param {Array<string>} tags - Resolved tags
+ */
+async function pushImageTags(sourceRef, imageName, registry, tags) {
+  let reauthenticated = false;
+  for (const tag of tags) {
+    const targetRef = `${registry}/${imageName}:${tag}`;
+    try {
+      await tagAndPushOne(sourceRef, targetRef, registry);
+    } catch (error) {
+      if (reauthenticated || !isAuthenticationError(error)) {
+        throw new Error(`Push failed for ${targetRef}: ${error.message}`);
+      }
+      logger.log(formatWarningLine('Registry authentication expired; re-authenticating, then retrying push.'));
+      require('../utils/registry-credentials').resetRegistryLoginCache(registry);
       await authenticateWithRegistry(registry);
-      // Retry push after re-authentication
-      await Promise.all(tags.map(async(tag) => {
-        await pushUtils.pushImage(`${registry}/${imageName}:${tag}`, registry);
-      }));
-    } else {
-      throw error;
+      reauthenticated = true;
+      await tagAndPushOne(sourceRef, targetRef, registry);
     }
   }
 }
@@ -252,12 +309,12 @@ async function pushApp(appName, options = {}) {
   }
   try {
     validateAppName(appName);
-    const { registry, imageName } = await loadPushConfig(appName, options);
-    await validatePushConfig(registry, imageName, appName);
+    const { registry, imageName, appVersion } = await loadPushConfig(appName, options);
+    const tags = require('../utils/image-tags').resolveImageTags(options.tag, appVersion);
+    const sourceRef = await validatePushConfig(registry, imageName, appName);
     logPushCommandHeader(appName, registry, imageName);
     await authenticateWithRegistry(registry);
-    const tags = options.tag ? options.tag.split(',').map(t => t.trim()) : ['latest'];
-    await pushImageTags(imageName, registry, tags);
+    await pushImageTags(sourceRef, imageName, registry, tags);
     displayPushResults(registry, imageName, tags);
   } catch (error) {
     throw new Error(`Failed to push application: ${error.message}`);

package/lib/build/standard-docker-build.js

@@ -80,21 +80,18 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
   );
   await ensureRunSecretsForApp(appName);
   const buildArgs = await resolveDockerBuildArgsForApp(appName, contextPath);
-  const tag = options.tag || 'latest';
-  if (typeof tag === 'string' && tag.includes(',')) {
-    throw new Error('Use a single image tag per build (comma-separated multiple tags are not supported).');
-  }
+  const { primary, aliases, tags } = options.tagPlan;
   await dockerBuild.executeDockerBuildWithTag(
     effectiveImageName,
     imageName,
     dockerfilePath,
     contextPath,
-    tag,
-    { ...options, buildArgs }
+    primary,
+    { ...options, buildArgs, tagAliases: aliases }
   );
   await postBuildTasks(appName, buildConfig);
   logger.log(formatSuccessParagraph('Build completed successfully!'));
-  return `${effectiveImageName}:${tag}`;
+  return tags.map((tag) => `${effectiveImageName}:${tag}`).join(', ');
 }
 
 /**
@@ -104,12 +101,17 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
  * @returns {Promise<string>} Built image ref e.g. name:tag
  */
 async function runStandardDockerBuild(appName, options) {
-  const promotedRef = await tryCompleteDevPromoteBuild(appName, options);
+  const { resolveBuildTagPlan, readAppVersion } = require('../utils/image-tags');
+  const { buildConfig, config: appConfig } = await buildHelpers.loadAndValidateConfig(appName);
+  // Resolve and validate every tag before any Docker build, tag, login or promote.
+  const planned = { ...options, tagPlan: resolveBuildTagPlan(options.tag, readAppVersion(appConfig)) };
+  const promotedRef = await tryCompleteDevPromoteBuild(appName, planned);
   if (promotedRef) {
-    return promotedRef;
+    const { resolvePromoteBaseTags } = require('../utils/promote-dev-docker-image');
+    const baseName = promotedRef.slice(0, promotedRef.lastIndexOf(':'));
+    return resolvePromoteBaseTags(planned).map((tag) => `${baseName}:${tag}`).join(', ');
   }
-  const { buildConfig } = await buildHelpers.loadAndValidateConfig(appName);
-  return executeDockerImageBuild(appName, options, buildConfig);
+  return executeDockerImageBuild(appName, planned, buildConfig);
 }
 
 module.exports = { runStandardDockerBuild };

package/lib/cli/setup-app.js

@@ -208,6 +208,7 @@ Examples:
     .option('-p, --port <port>', 'Override local port')
     .option('-d, --debug', 'Enable debug output with detailed container information')
     .option('-t, --tag <tag>', 'Image tag to run (e.g. v1.0.0); overrides application.yaml image.tag')
+    .option('-r, --registry <registry>', 'Registry host for the image (overrides dev set-registry and application.yaml)')
     .option('-e, --env <env>', 'Environment: dev (default), tst, or pro', 'dev')
     .option('--base', 'Use manifest base image only (skip local developer-scoped tag preference)')
     .option('--reload', 'In dev: mount workspace into container (Mutagen only if docker-endpoint is a remote host)')
@@ -237,7 +238,11 @@ function registerBuildCommand(program) {
     .option('-l, --language <lang>', 'Override language detection')
     .option('-f, --force-template', 'Force rebuild from template')
     .option('--no-cache', 'Full Docker rebuild (disable layer cache); use after Dockerfile or context fixes')
-    .option('-t, --tag <tag>', 'Image tag (default: latest). Set image.tag in application.yaml to match for deploy.')
+    .option(
+      '-t, --tag <tags>',
+      'Image tag or comma-separated tags (default: latest); {version} expands to app.version, e.g. "latest,{version}"'
+    )
+    .option('-r, --registry <registry>', 'Registry host for the image name (overrides dev set-registry and application.yaml)')
     .option(
       '--base',
       'Build/run the manifest base image (no -devN suffix). Default local build uses a developer-scoped repository when developer-id > 0.'
@@ -246,10 +251,16 @@ function registerBuildCommand(program) {
       '--from-dev',
       'With --base: tag the existing developer-scoped image as the base image instead of rebuilding when possible'
     )
+    .addHelpText('after', `
+Examples:
+  $ aifabrix build myapp
+  $ aifabrix build myapp --tag v1.0.0            # also tags latest
+  $ aifabrix build myapp --base --from-dev --tag 'latest,{version}'
+  $ aifabrix build myapp --registry myregistry.azurecr.io`)
     .action(async(appName, options) => {
       try {
-        const imageTag = await app.buildApp(appName, options);
-        logger.log(`✔ Built image: ${imageTag}`);
+        const imageRefs = await app.buildApp(appName, options);
+        logger.log(`✔ Built image: ${imageRefs}`);
       } catch (error) {
         handleCommandError(error, 'build');
         process.exit(1);
@@ -403,8 +414,8 @@ function setupPushDeployDockerfileCommands(program) {
   program.command('push <appKey>')
     .description('Push builder appKey image to Azure Container Registry')
     .addHelpText('after', PUSH_HELP_AFTER)
-    .option('-r, --registry <registry>', 'ACR registry URL (overrides application.yaml)')
-    .option('-t, --tag <tag>', 'Image tag(s) - comma-separated for multiple (default: latest)')
+    .option('-r, --registry <registry>', 'Registry host (overrides dev set-registry and application.yaml)')
+    .option('-t, --tag <tags>', 'Image tag or comma-separated tags (default: latest); {version} expands to app.version')
     .action(async(appName, options) => {
       try {
         await app.pushApp(appName, options);

package/lib/cli/setup-dev-path-commands.js

@@ -1,5 +1,6 @@
 /**
- * Dev subcommands: set-home, set-work, print-home, print-work, shell-env, set-format.
+ * Dev subcommands: set-home, set-work, print-home, print-work, shell-env, set-format,
+ * set-registry, print-registry.
  *
  * @fileoverview Path and format CLI registration for `aifabrix dev`
  * @author AI Fabrix Team
@@ -178,8 +179,53 @@ function addSetFormatCommand(dev, handleSetFormat) {
     });
 }
 
+const SET_REGISTRY_HELP = `
+Examples:
+  $ aifabrix dev set-registry myregistry.azurecr.io
+  $ printf '%s' "$TOKEN" | aifabrix dev set-registry myregistry.azurecr.io --username puller --password-stdin
+  $ aifabrix dev set-registry myregistry.azurecr.io --clear-credentials
+  $ aifabrix dev set-registry --clear
+
+Registry precedence for build, run, push and deploy: --registry, then this value, then the
+application image.registry. Credentials are stored encrypted in your local secrets file as
+<registry>-username and <registry>-password and are used for docker login (password on stdin).`;
+
+function addRegistryCommands(dev) {
+  const { runSetRegistry, runPrintRegistry } = require('../commands/dev-registry');
+  dev
+    .command('set-registry [registry]')
+    .description('Set, clear or add credentials for the default container registry of this CLI installation')
+    .option('--username <username>', 'Registry username (requires a password option)')
+    .option('--password <password>', 'Registry password or token (visible in shell history; prefer --password-stdin)')
+    .option('--password-stdin', 'Read the registry password or token from stdin')
+    .option('--clear', 'Remove the saved default registry (credentials are kept)')
+    .option('--clear-credentials', 'Remove only the stored credentials for <registry>')
+    .addHelpText('after', SET_REGISTRY_HELP)
+    .action(async(registry, cmdOpts) => {
+      try {
+        await runSetRegistry(registry, cmdOpts);
+      } catch (error) {
+        handleCommandError(error, 'dev set-registry');
+        process.exit(1);
+      }
+    });
+
+  dev
+    .command('print-registry')
+    .description('Print the saved default registry or an empty line (stdout only; for scripts)')
+    .addHelpText('after', '\nExamples:\n  $ aifabrix dev print-registry\n')
+    .action(async() => {
+      try {
+        await runPrintRegistry();
+      } catch (error) {
+        handleCommandError(error, 'dev print-registry');
+        process.exit(1);
+      }
+    });
+}
+
 /**
- * Register dev set-home, set-work, print-*, set-format.
+ * Register dev set-home, set-work, print-*, set-format, set-registry, print-registry.
  * @param {import('commander').Command} dev - dev subcommand group
  * @param {function(string): Promise<void>} handleSetFormat - handler that updates format and refreshes display
  * @returns {void}
@@ -190,6 +236,7 @@ function setupDevPathAndFormatCommands(dev, handleSetFormat) {
   addSetWorkCommand(dev);
   addPrintHomeWorkCommands(dev);
   addSetFormatCommand(dev, handleSetFormat);
+  addRegistryCommands(dev);
 }
 
 module.exports = { setupDevPathAndFormatCommands };

package/lib/cli/setup-environment.js

@@ -21,14 +21,21 @@ function addMarketplaceOptions(command) {
     .option('--vendor <vendor>', 'Installation vendor: AZURE (default) or DOCKER (register only)')
     .option('--allow-my-ip', 'Allow the caller public IPv4 /32 to reach PostgreSQL, Key Vault and Storage (infra only; default off)')
     .option('--license-edition <edition>', 'License requested at activation: COMMUNITY, STANDARD, ENTERPRISE or a Marketplace subscription ID (infra only; saved in the workspace)')
+    .option('--location <region>', 'Azure region for infra (saved to the workspace; dev, tst and pro inherit it)')
+    .option(
+      '--acr-auth <mode>',
+      'Image pull auth for infra: auto (default: saved dev set-registry pair, else managed identity), mi, or credentials (admin is a deprecated alias)'
+    )
     .option('--miso-api-key-env <name>', 'Environment variable holding a temporary Miso API key (dev, tst, pro)')
-    .option('--controller-url <url>', 'Controller URL override for dev, tst or pro (deprecated platform stage also uses it)')
+    .option(
+      '--controller-url <url>',
+      'Controller endpoint override for dev, tst or pro (normally recorded by infra); does not authenticate'
+    )
     .option('--marketplace-json <file>', 'Deprecated explicit mode: ARM Marketplace infrastructure template')
     .option('--parameters <file>', 'Deprecated explicit mode: secure ARM deploymentParameters JSON file')
     .option('--subscription <id>', 'Deprecated explicit mode: Azure subscription ID')
     .option('--resource-group <name>', 'Deprecated explicit mode: new isolated Azure resource group')
-    .option('--install-id <id>', 'Deprecated explicit mode: installation ID and resume-journal key')
-    .option('--location <region>', 'Deprecated explicit mode: Azure region when not set in the parameter file');
+    .option('--install-id <id>', 'Deprecated explicit mode: installation ID and resume-journal key');
 }
 
 async function runLegacyMarketplace(envKey, options) {
@@ -78,6 +85,8 @@ Installation workspace (<env> is the resource group; files under infrastructure/
   $ af env deploy <resource-group> --stage infra
   $ af env deploy <resource-group> --stage infra --allow-my-ip
   $ af env deploy <resource-group> --stage infra --license-edition ENTERPRISE
+  $ af env deploy <resource-group> --stage infra --location swedencentral
+  $ af env deploy <resource-group> --stage infra --acr-auth credentials
   $ af env deploy <resource-group> --stage dev
   $ af env deploy <resource-group> --stage pro --preset m
   $ af env deploy <resource-group> --stage register --vendor DOCKER
@@ -86,7 +95,11 @@ Vendor/stage matrix:
   AZURE   infra, dev, tst, pro   (Mori bootstrap runs inside the Marketplace template)
   DOCKER  register only          (deploy with aifabrix setup)
 
-Prerequisites: aifabrix login (controller permission controller:deploy); infra also needs az login.
+Prerequisites: aifabrix login or MISO_API_KEY / --miso-api-key-env (controller permission controller:deploy);
+infra also needs az login. --controller-url only selects the endpoint; it never replaces authentication.
+Registry pull auth for infra: save a pair once with aifabrix dev set-registry <acr-login-server> --username <user> --password-stdin.
+Deprecated explicit Marketplace flags: --marketplace-json, --parameters, --subscription, --resource-group, --install-id
+(that route also accepts --location).
 Environment keys: miso, dev, tst, pro. Default size preset: s (use --preset s|m|l|xl).
 Tenant activation after infra is a manual step in the Miso web application.
 Run this before aifabrix deploy <app> — the environment must exist first.`;

package/lib/commands/dev-registry.js

@@ -0,0 +1,155 @@
+/**
+ * `aifabrix dev set-registry` / `dev print-registry` logic.
+ *
+ * @fileoverview Installation registry preference and host-scoped credential management
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const config = require('../core/config');
+const logger = require('../utils/logger');
+const { formatSuccessLine, formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { normalizeRegistryHost } = require('../utils/config-registry-preference');
+const registryCredentials = require('../utils/registry-credentials');
+
+/**
+ * Reads the whole of stdin (for --password-stdin).
+ * @param {NodeJS.ReadableStream} [stream] - Input stream
+ * @returns {Promise<string>}
+ */
+function readAllStdin(stream = process.stdin) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+      data += chunk;
+    });
+    stream.on('end', () => resolve(data));
+    stream.on('error', reject);
+  });
+}
+
+function hasOption(value) {
+  return value !== undefined && value !== null;
+}
+
+function assertModeOptions(registry, opts) {
+  const credentialOption = hasOption(opts.username) || hasOption(opts.password) || opts.passwordStdin === true;
+  if (opts.clear && opts.clearCredentials) {
+    throw new Error('Use either --clear or --clear-credentials, not both');
+  }
+  if ((opts.clear || opts.clearCredentials) && credentialOption) {
+    throw new Error('--clear and --clear-credentials cannot be combined with --username or a password option');
+  }
+  if (opts.clear && hasOption(registry)) {
+    throw new Error('--clear removes the saved registry and takes no registry argument');
+  }
+  if (!opts.clear && !(typeof registry === 'string' && registry.trim())) {
+    throw new Error('Registry is required (for example: aifabrix dev set-registry myregistry.azurecr.io)');
+  }
+}
+
+function assertCredentialOptions(opts) {
+  if (hasOption(opts.password) && opts.passwordStdin === true) {
+    throw new Error('Use either --password or --password-stdin, not both');
+  }
+  const passwordGiven = hasOption(opts.password) || opts.passwordStdin === true;
+  if (hasOption(opts.username) !== passwordGiven) {
+    throw new Error('--username and a password (--password or --password-stdin) must be supplied together');
+  }
+  if (hasOption(opts.username) && !String(opts.username).trim()) {
+    throw new Error('--username must not be empty');
+  }
+  if (hasOption(opts.password) && String(opts.password) === '') {
+    throw new Error('--password must not be empty');
+  }
+  return passwordGiven;
+}
+
+async function resolvePassword(opts, readStdin) {
+  if (opts.passwordStdin !== true) return String(opts.password);
+  const password = (await readStdin()).replace(/\r?\n$/, '');
+  if (!password) {
+    throw new Error('--password-stdin received an empty password');
+  }
+  return password;
+}
+
+async function saveWithCredentials(host, username, password) {
+  const saved = await registryCredentials.saveRegistryCredentials(host, username, password);
+  try {
+    await config.setRegistry(host);
+  } catch (error) {
+    saved.rollback();
+    throw new Error(`Could not save the registry preference; credentials for ${host} were restored (${error.message})`);
+  }
+}
+
+async function runClearMode(registry, opts) {
+  if (opts.clear) {
+    await config.clearRegistry();
+    logger.log(formatSuccessLine('Registry cleared (application image.registry applies again)'));
+    return { action: 'clear', registry: null, credentials: false };
+  }
+  const host = normalizeRegistryHost(registry);
+  const removed = registryCredentials.removeRegistryCredentials(host);
+  logger.log(formatSuccessLine(removed ? `Credentials removed for ${host}` : `No stored credentials for ${host}`));
+  return { action: 'clear-credentials', registry: host, credentials: false };
+}
+
+/**
+ * Runs `dev set-registry`.
+ * @param {string|undefined} registry - Positional registry
+ * @param {Object} opts - Commander options
+ * @param {Object} [deps] - `readStdin` override (tests)
+ * @returns {Promise<{ action: string, registry: string|null, credentials: boolean }>}
+ */
+async function runSetRegistry(registry, opts = {}, deps = {}) {
+  assertModeOptions(registry, opts);
+  if (opts.clear || opts.clearCredentials) return runClearMode(registry, opts);
+  const host = normalizeRegistryHost(registry);
+  const withCredentials = assertCredentialOptions(opts);
+  if (!withCredentials) {
+    await config.setRegistry(host);
+    logger.log(formatSuccessLine(`Registry set to ${host}`));
+    return { action: 'set', registry: host, credentials: false };
+  }
+  const password = await resolvePassword(opts, deps.readStdin || readAllStdin);
+  await saveWithCredentials(host, String(opts.username).trim(), password);
+  logger.log(formatSuccessLine(`Registry set to ${host}`));
+  logger.log(formatSuccessLine(`Credentials saved for ${host} in your local secrets file (encrypted)`));
+  if (opts.passwordStdin !== true) {
+    logger.log(formatWarningLine('--password can appear in shell history and process listings; prefer --password-stdin'));
+  }
+  return { action: 'set', registry: host, credentials: true };
+}
+
+/**
+ * `dev print-registry`: the saved value plus a newline, or an empty line. Stdout only.
+ * @returns {Promise<void>}
+ */
+async function runPrintRegistry() {
+  const registry = await config.getRegistry();
+  process.stdout.write(`${registry || ''}\n`);
+}
+
+/**
+ * Safe credential status label for `dev show` (never decrypts).
+ * @param {string|null} registry - Saved registry
+ * @returns {string|null}
+ */
+function registryCredentialLabel(registry) {
+  if (!registry) return null;
+  try {
+    const status = registryCredentials.getRegistryCredentialStatus(registry);
+    if (status === 'complete') return 'configured';
+    if (status === 'absent') return 'not configured';
+    return `incomplete (run: aifabrix dev set-registry ${registry} --clear-credentials)`;
+  } catch {
+    return 'unknown';
+  }
+}
+
+module.exports = { runSetRegistry, runPrintRegistry, registryCredentialLabel, readAllStdin };

package/lib/commands/dev-show-display.js

@@ -336,6 +336,8 @@ function logConfigurationSection(p) {
   logRow('Environment', p.environment);
   logRow('Controller', p.controller);
   logRow('Format', p.formatVal);
+  logRow('Registry', p.registry);
+  if (p.registry) logRow('Registry login', p.registryCredentials);
   logRow('Platform mode', p.setupPlatformMode);
   logRow('Traefik', p.traefikEnabled ? 'on' : 'off');
   logRow('Scoped resources', p.scopedResourcesLabel);
@@ -389,14 +391,16 @@ async function loadDevShowData(devIdStr) {
   const ports = devConfig.getDevPorts(Number.isNaN(devIdNum) ? 0 : devIdNum);
   const [
     environment, tlsEnabled, controller, formatRaw, useScoped, secretsRaw, setupPlatformMode, traefikEnabled,
-    remoteServer, dockerEndpoint, dockerTlsSkipVerify, mutagenFolder, syncSshUser, syncSshHost
+    remoteServer, dockerEndpoint, dockerTlsSkipVerify, mutagenFolder, syncSshUser, syncSshHost, registry
   ] = await Promise.all([
     config.getCurrentEnvironment(), config.getTlsEnabled(), config.getControllerUrl(),
     config.getFormat(), config.getUseEnvironmentScopedResources(), config.getAifabrixSecretsPath(),
     config.getSetupPlatformMode(), config.getTraefikEnabled(),
     config.getRemoteServer(), config.getDockerEndpoint(), config.getDockerTlsSkipVerify(),
-    config.getUserMutagenFolder(), config.getSyncSshUser(), config.getSyncSshHost()
+    config.getUserMutagenFolder(), config.getSyncSshUser(), config.getSyncSshHost(),
+    config.getRegistry ? config.getRegistry() : null
   ]);
+  const { registryCredentialLabel } = require('./dev-registry');
   const urlsLocalPath = getUrlsLocalYamlPath();
   const scopedResourcesLabel = useScoped ? 'on' : 'off (default)';
   const workResolved = paths.getAifabrixWork();
@@ -412,6 +416,8 @@ async function loadDevShowData(devIdStr) {
     tlsEnabled,
     controller,
     formatVal: formatRaw ?? null,
+    registry: registry || null,
+    registryCredentials: registryCredentialLabel(registry || null),
     scopedResourcesLabel,
     setupPlatformMode,
     traefikEnabled,
@@ -451,6 +457,8 @@ function renderDevShow(data) {
     tlsEnabled: data.tlsEnabled,
     controller: data.controller,
     formatVal: data.formatVal,
+    registry: data.registry,
+    registryCredentials: data.registryCredentials,
     setupPlatformMode: data.setupPlatformMode,
     traefikEnabled: data.traefikEnabled,
     scopedResourcesLabel: data.scopedResourcesLabel,

package/lib/commands/setup-image-refresh.js

@@ -21,9 +21,30 @@ const infraHelpers = require('../infrastructure/helpers');
 const upCommon = require('./up-common');
 const { sectionTitle, formatDatasourceListRow } = require('../utils/cli-test-layout-chalk');
 const { startSpinner, stopSpinnerSuccess } = require('./setup-spinners');
+const { ensureLoginForImageRefs } = require('../utils/registry-credentials');
 
 const PLATFORM_APPS = ['keycloak', 'miso-controller', 'dataplane'];
 
+/**
+ * `image:` values of a compose file (plain scan; variables are left unresolved and skipped).
+ * @param {string} composePath - Compose file path
+ * @returns {string[]}
+ */
+function readComposeImageRefs(composePath) {
+  let text = '';
+  try {
+    text = String(fs.readFileSync(composePath, 'utf8') || '');
+  } catch {
+    return [];
+  }
+  const refs = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.match(/^\s*image:\s*["']?([^"'\s#]+)["']?/);
+    if (match && !match[1].includes('$')) refs.push(match[1]);
+  }
+  return refs;
+}
+
 /**
  * Pull infra-compose images (postgres, redis, optional pgadmin/redis-commander/traefik).
  *
@@ -42,6 +63,8 @@ async function pullInfraImages(opts = {}) {
     }
     return;
   }
+  // Authenticate once per private registry host before compose pulls (stored pairs only).
+  await ensureLoginForImageRefs(readComposeImageRefs(composePath));
   const project = infraHelpers.getInfraProjectName(devId);
   const composeCmd = await dockerUtils.getComposeCommand();
   if (!quiet) {
@@ -91,6 +114,8 @@ async function pullPlatformAppImage(appName, opts = {}) {
     }
     return false;
   }
+  // A partial stored credential pair fails closed here instead of degrading to a warning.
+  await ensureLoginForImageRefs([imageRef]);
   try {
     if (!quiet) {
       const spin = startSpinner(`Pulling ${appName} image...`);
@@ -142,5 +167,6 @@ module.exports = {
   PLATFORM_APPS,
   pullInfraImages,
   pullPlatformImages,
+  readComposeImageRefs,
   runSetupImageRefresh
 };