@aifabrix/builder 2.44.5 → 2.45.0

package/lib/utils/health-check-db-init.js

@@ -0,0 +1,107 @@
+const chalk = require('chalk');
+const { formatSuccessLine } = require('./cli-test-layout-chalk');
+const logger = require('./logger');
+const { execWithDockerEnv } = require('./docker-exec');
+
+/**
+ * Checks if db-init container exists.
+ * @async
+ * @param {string} dbInitContainer
+ * @returns {Promise<boolean>}
+ */
+async function checkDbInitContainerExists(dbInitContainer) {
+  try {
+    const { stdout } = await execWithDockerEnv(
+      `docker ps -a --filter "name=${dbInitContainer}" --format "{{.Names}}"`
+    );
+    return stdout.trim() === dbInitContainer;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Gets container exit code.
+ * @async
+ * @param {string} dbInitContainer
+ * @returns {Promise<string>}
+ */
+async function getContainerExitCode(dbInitContainer) {
+  const { stdout: exitCode } = await execWithDockerEnv(
+    `docker inspect --format='{{.State.ExitCode}}' ${dbInitContainer}`
+  );
+  return exitCode.trim();
+}
+
+/**
+ * Handles exited container status.
+ * @async
+ * @param {string} dbInitContainer
+ * @returns {Promise<boolean>}
+ */
+async function handleExitedContainer(dbInitContainer) {
+  const { stdout: status } = await execWithDockerEnv(
+    `docker inspect --format='{{.State.Status}}' ${dbInitContainer}`
+  );
+  if (status.trim() === 'exited') {
+    const exitCode = await getContainerExitCode(dbInitContainer);
+    if (exitCode === '0') {
+      logger.log(formatSuccessLine('Database initialization already completed'));
+    } else {
+      logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
+    }
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Waits for container to exit (best-effort).
+ * @async
+ * @param {string} dbInitContainer
+ * @param {number} maxAttempts
+ * @returns {Promise<void>}
+ */
+async function waitForContainerExit(dbInitContainer, maxAttempts) {
+  for (let attempts = 0; attempts < maxAttempts; attempts++) {
+    const { stdout: currentStatus } = await execWithDockerEnv(
+      `docker inspect --format='{{.State.Status}}' ${dbInitContainer}`
+    );
+    if (currentStatus.trim() === 'exited') {
+      const exitCode = await getContainerExitCode(dbInitContainer);
+      if (exitCode === '0') {
+        logger.log(formatSuccessLine('Database initialization completed'));
+      } else {
+        logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
+      }
+      return;
+    }
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+}
+
+/**
+ * Checks if db-init container exists and waits for it to complete.
+ * @async
+ * @param {string} appName
+ * @returns {Promise<void>}
+ */
+async function waitForDbInit(appName) {
+  const dbInitContainer = `aifabrix-${appName}-db-init`;
+  try {
+    if (!(await checkDbInitContainerExists(dbInitContainer))) {
+      return;
+    }
+
+    if (await handleExitedContainer(dbInitContainer)) {
+      return;
+    }
+
+    logger.log(chalk.blue('Waiting for database initialization to complete...'));
+    await waitForContainerExit(dbInitContainer, 30);
+  } catch {
+    // db-init container might not exist, which is fine
+  }
+}
+
+module.exports = { waitForDbInit };

package/lib/utils/health-check-public-warn.js

@@ -0,0 +1,69 @@
+/**
+ * Post-success warnings when public/Traefik health URL was skipped or not verified.
+ *
+ * @fileoverview Split from health-check.js for file size limits
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+/**
+ * When Traefik URL is set, drop it if the hostname does not resolve; retain full URL for UX.
+ *
+ * @param {string} traefikUrl
+ * @param {boolean} debug
+ * @param {Function} isHostnameResolvableFn - (hostname, debug) => Promise<boolean>
+ * @returns {Promise<{ traefikUrl: string, skippedPublicHealthUrl: string }>}
+ */
+async function filterTraefikUrlByDns(traefikUrl, debug, isHostnameResolvableFn) {
+  if (!traefikUrl) {
+    return { traefikUrl: '', skippedPublicHealthUrl: '' };
+  }
+  try {
+    const hn = new URL(traefikUrl).hostname;
+    const ok = await isHostnameResolvableFn(hn, debug);
+    if (!ok) {
+      return { traefikUrl: '', skippedPublicHealthUrl: traefikUrl };
+    }
+  } catch {
+    return { traefikUrl: '', skippedPublicHealthUrl: '' };
+  }
+  return { traefikUrl, skippedPublicHealthUrl: '' };
+}
+
+/**
+ * @param {Object} p
+ * @param {string} [p.skippedPublicHealthUrl]
+ * @param {string[]} [p.urlsToTry]
+ * @param {number} p.resolvedIndex
+ */
+function logPublicHealthUrlWarningIfNeeded(p) {
+  const { skippedPublicHealthUrl, urlsToTry, resolvedIndex } = p;
+  if (typeof resolvedIndex !== 'number' || resolvedIndex < 0) return;
+
+  if (skippedPublicHealthUrl) {
+    logger.log(
+      chalk.yellow(
+        `⚠ Public URL was not verified (DNS): ${skippedPublicHealthUrl}. ` +
+          'The application reported healthy via localhost only. Validate DNS names and Traefik routing for this host.'
+      )
+    );
+    return;
+  }
+  if (Array.isArray(urlsToTry) && urlsToTry.length > 1 && resolvedIndex > 0) {
+    const pub = urlsToTry[0];
+    logger.log(
+      chalk.yellow(
+        `⚠ Public URL was not verified: ${pub}. ` +
+          'Health checks succeeded via localhost only. Validate Traefik routing, TLS, and DNS.'
+      )
+    );
+  }
+}
+
+module.exports = {
+  filterTraefikUrlByDns,
+  logPublicHealthUrlWarningIfNeeded
+};

package/lib/utils/health-check-url.js

@@ -63,9 +63,8 @@ function frontDoorPattern(appConfig) {
 }
 
 /**
- * Compute the Traefik front-door health check URL when applicable.
- *
- * Returns null when Traefik/frontDoorRouting isn't active or cannot be resolved.
+ * Public app URL (Traefik + frontDoor mount path), without the health path — for CLI summaries.
+ * Requires infra Traefik on, `frontDoorRouting.enabled`, host, and pattern.
  *
  * @async
  * @param {string} appName
@@ -73,8 +72,8 @@ function frontDoorPattern(appConfig) {
  * @param {Object|null} appConfig
  * @returns {Promise<string|null>}
  */
-async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig) {
-  if (!frontDoorEnabled(appConfig)) return null;
+async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig) {
+  if (!appConfig || !frontDoorEnabled(appConfig)) return null;
   const pattern = frontDoorPattern(appConfig);
   if (!pattern) return null;
 
@@ -82,14 +81,20 @@ async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig)
   const userCfg = await coreConfig.getConfig();
   if (!(userCfg && userCfg.traefik)) return null;
 
+  const fd = appConfig.frontDoorRouting;
+  if (!fd || typeof fd !== 'object') return null;
+  const hostTemplate = typeof fd.host === 'string' ? fd.host.trim() : '';
+  if (!hostTemplate) return null;
+
+  const mountPath = normalizeFrontDoorPatternForHealth(pattern);
+
   const infraTlsEnabled = Boolean(userCfg && userCfg.tlsEnabled);
   const remoteServer = await coreConfig.getRemoteServer();
   const developerIdRaw = await coreConfig.getDeveloperId();
   const developerIdNum = parseDeveloperIdNum(developerIdRaw);
 
-  // Health checks originate from the CLI on the host, not from inside a container.
+  // URLs are resolved for the CLI on the host, not from inside a container.
   const profile = 'local';
-  const fd = appConfig.frontDoorRouting;
   const listenPort = Number(appConfig?.port || 3000);
 
   const publicBase = computePublicUrlBaseString({
@@ -105,15 +110,28 @@ async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig)
     infraTlsEnabled
   });
 
+  return joinUrlPath(publicBase, mountPath);
+}
+
+/**
+ * Traefik public URL including health path.
+ *
+ * @async
+ * @param {string} appName
+ * @param {number} healthCheckPort
+ * @param {Object|null} appConfig
+ * @returns {Promise<string|null>}
+ */
+async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig) {
+  const baseWithFrontDoor = await computeTraefikPublicAppUrl(appName, healthCheckPort, appConfig);
+  if (!baseWithFrontDoor) return null;
   const healthCheckPath = appConfig?.healthCheck?.path || '/health';
-  const mountPath = normalizeFrontDoorPatternForHealth(pattern);
-  const baseWithFrontDoor = joinUrlPath(publicBase, mountPath);
   return joinUrlPath(baseWithFrontDoor, healthCheckPath);
 }
 
 module.exports = {
   joinUrlPath,
   normalizeFrontDoorPatternForHealth,
+  computeTraefikPublicAppUrl,
   computeTraefikHealthCheckUrl
 };
-

package/lib/utils/health-check.js

@@ -12,16 +12,25 @@ const { formatSuccessLine } = require('./cli-test-layout-chalk');
 const http = require('http');
 const https = require('https');
 const net = require('net');
+const dns = require('dns');
 const chalk = require('chalk');
 const logger = require('./logger');
 const { execWithDockerEnv } = require('./docker-exec');
-const { computeTraefikHealthCheckUrl } = require('./health-check-url');
+/** Namespace require so tests can `jest.spyOn` on `./health-check-url` exports. */
+const healthCheckUrl = require('./health-check-url');
+const { computePathActive } = require('./url-declarative-url-flags');
+const { isFrontDoorRoutingEnabledInDoc } = require('./url-declarative-vdir-inactive-env');
+const { waitForDbInit } = require('./health-check-db-init');
+const {
+  filterTraefikUrlByDns,
+  logPublicHealthUrlWarningIfNeeded
+} = require('./health-check-public-warn');
 
 /**
  * Compute the health check URL for an app.
  *
- * - Default (no Traefik front-door): http://localhost:<port><healthPath>
- * - With Traefik + app frontDoorRouting.enabled: <publicBase><frontDoorRouting.pattern><healthPath>
+ * - Default (path inactive): http://localhost:<port><healthPath> (e.g. Keycloak with KC_HTTP_RELATIVE_PATH=/)
+ * - Path active (Traefik on ∧ frontDoorRouting.enabled): localhost probe uses same vdir as the container (e.g. /auth/health/ready)
  *
  * @async
  * @param {string} appName
@@ -29,117 +38,68 @@ const { computeTraefikHealthCheckUrl } = require('./health-check-url');
  * @param {Object|null} appConfig
  * @param {Object} opts
  * @param {Object} [opts.runOptions] - runApp options (may include env + effectiveEnvironmentScopedResources)
+ * @param {boolean} [opts.skipTraefikPublicUrl] - Omit Traefik URL (localhost leg in dual-probe flow only).
  * @returns {Promise<string>}
  */
 async function computeHealthCheckUrl(appName, healthCheckPort, appConfig, _opts = {}) {
-  const healthCheckPath = appConfig?.healthCheck?.path || '/health';
+  const rawHealthPath = appConfig?.healthCheck?.path || '/health';
 
-  // Traefik front-door branch: probe via resolved public host + path (e.g. https://dev02.builder02.local/auth/health/ready)
-  try {
-    const traefikUrl = await computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig);
-    if (traefikUrl) return traefikUrl;
-  } catch {
-    // If any resolver step fails, fall back to localhost probing.
-  }
-
-  // Default: probe local published port.
-  return `http://localhost:${healthCheckPort}${healthCheckPath}`;
-}
-
-/**
- * Checks if db-init container exists and waits for it to complete
- * @async
- * @function waitForDbInit
- * @param {string} appName - Application name
- * @throws {Error} If db-init fails
- */
-/**
- * Checks if db-init container exists
- * @async
- * @function checkDbInitContainerExists
- * @param {string} dbInitContainer - Container name
- * @returns {Promise<boolean>} True if container exists
- */
-async function checkDbInitContainerExists(dbInitContainer) {
-  try {
-    const { stdout } = await execWithDockerEnv(`docker ps -a --filter "name=${dbInitContainer}" --format "{{.Names}}"`);
-    return stdout.trim() === dbInitContainer;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Gets container exit code
- * @async
- * @function getContainerExitCode
- * @param {string} dbInitContainer - Container name
- * @returns {Promise<string>} Exit code
- */
-async function getContainerExitCode(dbInitContainer) {
-  const { stdout: exitCode } = await execWithDockerEnv(`docker inspect --format='{{.State.ExitCode}}' ${dbInitContainer}`);
-  return exitCode.trim();
-}
-
-/**
- * Handles exited container status
- * @async
- * @function handleExitedContainer
- * @param {string} dbInitContainer - Container name
- * @returns {Promise<boolean>} True if handled (container already exited)
- */
-async function handleExitedContainer(dbInitContainer) {
-  const { stdout: status } = await execWithDockerEnv(`docker inspect --format='{{.State.Status}}' ${dbInitContainer}`);
-  if (status.trim() === 'exited') {
-    const exitCode = await getContainerExitCode(dbInitContainer);
-    if (exitCode === '0') {
-      logger.log(formatSuccessLine('Database initialization already completed'));
-    } else {
-      logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
+  function computeLocalhostHealthPath() {
+    // Plan 124 pathActive: prepend front-door pattern when Traefik on; keep bare /health for miso/dataplane style.
+    try {
+      const runOptions = _opts && typeof _opts === 'object' && _opts.runOptions ? _opts.runOptions : null;
+      const traefikOn = Boolean(runOptions && runOptions.traefikEnabled === true);
+      const fd = appConfig && appConfig.frontDoorRouting ? appConfig.frontDoorRouting : null;
+      const pattern = fd && typeof fd.pattern === 'string' ? fd.pattern : null;
+      const pathActive = computePathActive(traefikOn, isFrontDoorRoutingEnabledInDoc(appConfig || null));
+      const shouldMount = pathActive && Boolean(pattern) && rawHealthPath !== '/health';
+      if (!shouldMount) return rawHealthPath;
+      const { joinUrlPath, normalizeFrontDoorPatternForHealth } = require('./health-check-url');
+      const mountPath = normalizeFrontDoorPatternForHealth(pattern);
+      return joinUrlPath(mountPath, rawHealthPath);
+    } catch {
+      return rawHealthPath;
     }
-    return true;
   }
-  return false;
-}
 
-/**
- * Waits for container to exit
- * @async
- * @function waitForContainerExit
- * @param {string} dbInitContainer - Container name
- * @param {number} maxAttempts - Maximum attempts
- */
-async function waitForContainerExit(dbInitContainer, maxAttempts) {
-  for (let attempts = 0; attempts < maxAttempts; attempts++) {
-    const { stdout: currentStatus } = await execWithDockerEnv(`docker inspect --format='{{.State.Status}}' ${dbInitContainer}`);
-    if (currentStatus.trim() === 'exited') {
-      const exitCode = await getContainerExitCode(dbInitContainer);
-      if (exitCode === '0') {
-        logger.log(formatSuccessLine('Database initialization completed'));
-      } else {
-        logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
-      }
-      return;
+  const localhostHealthPath = computeLocalhostHealthPath();
+
+  // Local readiness probes localhost; optional Traefik URL is for display / dual-probe (see waitForHealthCheck).
+  async function maybeGetTraefikUrl() {
+    if (_opts && _opts.skipTraefikPublicUrl) return '';
+    const runOptions = (_opts && typeof _opts === 'object') ? _opts.runOptions : null;
+    const wantsTraefik =
+      Boolean(runOptions) &&
+      (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true) &&
+      isFrontDoorRoutingEnabledInDoc(appConfig);
+    if (!wantsTraefik) return '';
+    try {
+      return await healthCheckUrl.computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig);
+    } catch {
+      return '';
     }
-    await new Promise(resolve => setTimeout(resolve, 1000));
   }
+
+  const traefikUrl = await maybeGetTraefikUrl();
+  if (traefikUrl) return traefikUrl;
+
+  return `http://localhost:${healthCheckPort}${localhostHealthPath}`;
 }
 
-async function waitForDbInit(appName) {
-  const dbInitContainer = `aifabrix-${appName}-db-init`;
+async function isHostnameResolvable(hostname, debug) {
+  if (!hostname) return false;
+  const hn = String(hostname).trim().toLowerCase();
+  if (!hn) return false;
+  if (hn === 'localhost' || hn === '127.0.0.1' || hn === '::1') return true;
   try {
-    if (!(await checkDbInitContainerExists(dbInitContainer))) {
-      return;
-    }
-
-    if (await handleExitedContainer(dbInitContainer)) {
-      return;
+    await dns.promises.lookup(hn);
+    return true;
+  } catch (err) {
+    // ENOTFOUND: caller may log a single post-success warning with the full public health URL.
+    if (debug && !(err && err.code === 'ENOTFOUND')) {
+      logger.log(chalk.gray(`[DEBUG] DNS lookup failed for ${hostname}: ${err.message}`));
     }
-
-    logger.log(chalk.blue('Waiting for database initialization to complete...'));
-    await waitForContainerExit(dbInitContainer, 30);
-  } catch (error) {
-    // db-init container might not exist, which is fine
+    return false;
   }
 }
 
@@ -411,24 +371,96 @@ async function performHealthCheckAttempt(healthCheckUrl, attempt, maxAttempts, d
   return false;
 }
 
+async function computePreferredHealthCheckUrls(appName, healthCheckPort, config, runOptions, debug) {
+  const localhostUrl = await computeHealthCheckUrl(appName, healthCheckPort, config, {
+    runOptions: runOptions && typeof runOptions === 'object' ? runOptions : {},
+    skipTraefikPublicUrl: true
+  });
+
+  let traefikUrl = '';
+  /** Full Traefik/public health URL when DNS fails — used for one post-success warning. */
+  let skippedPublicHealthUrl = '';
+  const wantsTraefikFirst = Boolean(
+    runOptions && (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true)
+  ) && isFrontDoorRoutingEnabledInDoc(config);
+  if (wantsTraefikFirst) {
+    try {
+      traefikUrl = await healthCheckUrl.computeTraefikHealthCheckUrl(appName, healthCheckPort, config);
+    } catch {
+      traefikUrl = '';
+    }
+  }
+
+  const filtered = await filterTraefikUrlByDns(traefikUrl, debug, isHostnameResolvable);
+  traefikUrl = filtered.traefikUrl;
+  skippedPublicHealthUrl = filtered.skippedPublicHealthUrl;
+
+  const urlsToTry = traefikUrl ? [traefikUrl, localhostUrl] : [localhostUrl];
+  if (urlsToTry.length > 1) {
+    logger.log(
+      chalk.gray(
+        `ℹ Health check order: Traefik/DNS (${urlsToTry[0]}), then localhost (${urlsToTry[1]}).`
+      )
+    );
+  }
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Health check URLs: ${urlsToTry.join(' | ')}`));
+  }
+  return { urlsToTry, skippedPublicHealthUrl };
+}
+
+async function performHealthCheckAttemptForUrls(urlsToTry, attempt, maxAttempts, debug) {
+  for (let i = 0; i < urlsToTry.length; i++) {
+    const url = urlsToTry[i];
+    const passed = await performHealthCheckAttempt(url, attempt, maxAttempts, debug);
+    if (passed) {
+      return { ok: true, resolvedIndex: i };
+    }
+  }
+  return { ok: false, resolvedIndex: -1 };
+}
+
 async function waitForHealthCheck(appName, timeout = 90, port = null, config = null, debug = false, runOptions = {}) {
   await waitForDbInit(appName);
 
   const healthCheckPort = await determineHealthCheckPort(port, appName, debug);
   const { maxAttempts } = buildHealthCheckConfig(healthCheckPort, config, timeout, debug);
-  const healthCheckUrl = await computeHealthCheckUrl(appName, healthCheckPort, config, { runOptions });
-  if (debug) {
-    logger.log(chalk.gray(`[DEBUG] Health check URL: ${healthCheckUrl}`));
+  const { urlsToTry, skippedPublicHealthUrl } = await computePreferredHealthCheckUrls(
+    appName,
+    healthCheckPort,
+    config,
+    runOptions,
+    debug
+  );
+
+  if (skippedPublicHealthUrl && urlsToTry.length === 1) {
+    logger.log(
+      chalk.gray(
+        `ℹ Health check: public URL not used (DNS): ${skippedPublicHealthUrl}. ` +
+          `Probing ${urlsToTry[0]} only until the app responds.`
+      )
+    );
   }
 
   for (let attempts = 0; attempts < maxAttempts; attempts++) {
-    const passed = await performHealthCheckAttempt(healthCheckUrl, attempts, maxAttempts, debug);
-    if (passed) {
+    const attemptResult = await performHealthCheckAttemptForUrls(urlsToTry, attempts, maxAttempts, debug);
+    if (attemptResult.ok) {
+      logPublicHealthUrlWarningIfNeeded({
+        skippedPublicHealthUrl,
+        urlsToTry,
+        resolvedIndex: attemptResult.resolvedIndex
+      });
       return;
     }
 
     if (attempts < maxAttempts - 1) {
-      logger.log(chalk.yellow(`Waiting for health check... (${attempts + 1}/${maxAttempts}) ${healthCheckUrl}`));
+      const probeHint =
+        urlsToTry.length > 1
+          ? `trying ${urlsToTry[0]}, then ${urlsToTry[1]}`
+          : (urlsToTry[0] || 'health URL');
+      logger.log(
+        chalk.yellow(`Waiting for health check… (${attempts + 1}/${maxAttempts}) (${probeHint})`)
+      );
       await new Promise(resolve => setTimeout(resolve, 2000));
     }
   }

package/lib/utils/help-builder.js

@@ -20,6 +20,8 @@ const CATEGORIES = [
   {
     name: 'Infrastructure (Local Development)',
     commands: [
+      { name: 'setup' },
+      { name: 'teardown' },
       { name: 'up-infra' },
       { name: 'up-platform' },
       { name: 'up-miso' },
@@ -72,7 +74,7 @@ const CATEGORIES = [
       { name: 'app' },
       { name: 'credential' },
       { name: 'deployment' },
-      { name: 'service-user' }
+      { name: 'integration-client' }
     ]
   },
   {
@@ -96,6 +98,8 @@ const CATEGORIES = [
       { name: 'delete', term: 'delete <systemKey>' },
       { name: 'repair', term: 'repair <systemKey>' },
       { name: 'datasource' },
+      { name: 'dimension' },
+      { name: 'dimension-value' },
       { name: 'test', term: 'test <app>' },
       { name: 'test-e2e', term: 'test-e2e <app>' },
       { name: 'test-integration', term: 'test-integration <app>' }

package/lib/utils/image-name.js

@@ -11,18 +11,18 @@
 
 /**
  * Builds a developer-scoped image name for local Docker builds.
- * Format: "<base>-dev<developerId>".
- * If developerId is missing, non-numeric, or 0 → "<base>-extra".
+ * Format: "<base>-dev<developerId>" when developerId is a positive integer.
+ * If developerId is missing, non-numeric, or 0 → returns baseName (manifest image; no dev suffix).
  *
  * @function buildDevImageName
  * @param {string} baseName - Base image name (no registry), e.g., "myapp"
  * @param {(string|number|null|undefined)} developerId - Developer identifier
- * @returns {string} Developer-scoped image name
+ * @returns {string} Developer-scoped image name or base name when id is 0 / absent
  *
  * @example
  * buildDevImageName('myapp', 123) // "myapp-dev123"
- * buildDevImageName('myapp', '0') // "myapp-extra"
- * buildDevImageName('myapp') // "myapp-extra"
+ * buildDevImageName('myapp', '0') // "myapp"
+ * buildDevImageName('myapp') // "myapp"
  */
 function buildDevImageName(baseName, developerId) {
   const id =
@@ -37,13 +37,40 @@ function buildDevImageName(baseName, developerId) {
   }
 
   if (!Number.isFinite(id) || id === 0) {
-    return `${baseName}-extra`;
+    return baseName;
   }
 
   return `${baseName}-dev${id}`;
 }
 
+/**
+ * Developer-scoped repository path for run/build resolution (may include registry prefix).
+ * For qualified paths (slashes), only the last segment gets `-dev<id>`; id 0 returns path unchanged.
+ *
+ * @param {string} repositoryPath - Full repository path (e.g. "reg/ns/app" or "app")
+ * @param {(string|number|null|undefined)} developerId - Developer id from config
+ * @returns {string}
+ */
+function buildDevImageRepositoryPath(repositoryPath, developerId) {
+  if (!repositoryPath || typeof repositoryPath !== 'string') {
+    throw new Error('Repository path is required and must be a string');
+  }
+  const idNum =
+    typeof developerId === 'number' ? developerId : parseInt(String(developerId), 10);
+  if (!Number.isFinite(idNum) || idNum === 0) {
+    return repositoryPath;
+  }
+  const idx = repositoryPath.lastIndexOf('/');
+  const tail = idx === -1 ? repositoryPath : repositoryPath.slice(idx + 1);
+  const scopedTail = buildDevImageName(tail, developerId);
+  if (idx === -1) {
+    return scopedTail;
+  }
+  return `${repositoryPath.slice(0, idx)}/${scopedTail}`;
+}
+
 module.exports = {
-  buildDevImageName
+  buildDevImageName,
+  buildDevImageRepositoryPath
 };