@aifabrix/builder 2.44.4 → 2.44.6

package/lib/utils/docker-reload-mount.js

@@ -0,0 +1,127 @@
+/**
+ * Decide whether `aifabrix run --reload` can bind-mount workspace without Mutagen.
+ * Mutagen is only needed when the CLI filesystem and the Docker engine host differ.
+ *
+ * @fileoverview Co-located Docker detection for reload mounts
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const os = require('os');
+
+/**
+ * @param {string} host
+ * @returns {string}
+ */
+function normalizeHost(host) {
+  return String(host || '')
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, '');
+}
+
+/**
+ * @param {string} host
+ * @returns {boolean}
+ */
+function isLocalLoopbackHost(host) {
+  const h = normalizeHost(host);
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '0:0:0:0:0:0:0:1';
+}
+
+/**
+ * @param {string} rest - after "tcp://"
+ * @returns {string|null}
+ */
+function tcpHostFromRest(rest) {
+  if (rest.startsWith('[')) {
+    const end = rest.indexOf(']');
+    if (end === -1) return null;
+    return normalizeHost(rest.slice(1, end));
+  }
+  const hostPort = rest.split('/')[0];
+  const colonIdx = hostPort.lastIndexOf(':');
+  if (colonIdx === -1) {
+    return normalizeHost(hostPort);
+  }
+  const maybePort = hostPort.slice(colonIdx + 1);
+  if (/^\d+$/.test(maybePort)) {
+    return normalizeHost(hostPort.slice(0, colonIdx));
+  }
+  return normalizeHost(hostPort);
+}
+
+/**
+ * Extract host from docker-endpoint (tcp, optional URL form).
+ * @param {string} endpoint
+ * @returns {string|null} normalized host, or null for unix socket paths / empty
+ */
+function extractHostFromDockerEndpoint(endpoint) {
+  const s = String(endpoint || '').trim();
+  if (!s) return null;
+  const lower = s.toLowerCase();
+  if (lower.startsWith('unix:')) {
+    return null;
+  }
+  if (lower.startsWith('tcp://')) {
+    return tcpHostFromRest(s.slice(6));
+  }
+  try {
+    const u = new URL(s.includes('://') ? s : `tcp://${s}`);
+    return normalizeHost(u.hostname);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * sync-ssh-host localhost check (same rules as run.js isLocalhostHost for reload gate).
+ * @param {string} host
+ * @returns {boolean}
+ */
+function isLocalhostSyncSshHost(host) {
+  if (!host || typeof host !== 'string') return false;
+  const h = host.trim().toLowerCase();
+  return h === 'localhost' || h === '127.0.0.1';
+}
+
+/**
+ * True when docker API host is this machine (first label or FQDN match).
+ * @param {string} dockerHost - from extractHostFromDockerEndpoint
+ * @returns {boolean}
+ */
+function hostnameMatchesDockerHost(dockerHost) {
+  const h = normalizeHost(dockerHost);
+  if (!h) return true;
+  if (isLocalLoopbackHost(h)) return true;
+  const hn = normalizeHost(os.hostname());
+  if (h === hn) return true;
+  const hnShort = hn.split('.')[0];
+  const hShort = h.split('.')[0];
+  if (h === hnShort || hn === hShort) return true;
+  return false;
+}
+
+/**
+ * When true, use a direct bind mount for --reload; Mutagen is not required.
+ * @param {string|null|undefined} dockerEndpoint - config `docker-endpoint`
+ * @returns {boolean}
+ */
+function isReloadBindMountOnEngineHost(dockerEndpoint) {
+  const e = String(dockerEndpoint || '').trim();
+  if (!e) return true;
+  if (e.toLowerCase().startsWith('unix:')) return true;
+  const host = extractHostFromDockerEndpoint(e);
+  if (host === null) {
+    return false;
+  }
+  return hostnameMatchesDockerHost(host);
+}
+
+module.exports = {
+  extractHostFromDockerEndpoint,
+  isReloadBindMountOnEngineHost,
+  isLocalhostSyncSshHost
+};

package/lib/utils/external-readme.js

@@ -15,6 +15,72 @@ const path = require('path');
 const handlebars = require('handlebars');
 const { getProjectRoot } = require('./paths');
 
+/**
+ * Extracts secret keys from integration/<appName>/env.template when present.
+ * Looks for values like `kv://systemKey/apiKey` and returns that key for
+ * `aifabrix secret set <key> <value>`.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.appName
+ * @returns {Array<{path: string, description: string}>}
+ */
+function extractSecretPathsFromEnvTemplate({ projectRoot, appName }) {
+  if (!projectRoot || !appName) return [];
+
+  const envTemplatePath = path.join(projectRoot, 'integration', appName, 'env.template');
+  if (!fs.existsSync(envTemplatePath)) return [];
+
+  const raw = _tryReadTextOrNull(envTemplatePath);
+  if (raw === null) return [];
+  if (typeof raw !== 'string') return [];
+
+  function parseSecretKey(value) {
+    if (!value || typeof value !== 'string') return null;
+    const kvIdx = value.indexOf('kv://');
+    if (kvIdx === -1) return null;
+    const after = value.slice(kvIdx + 'kv://'.length);
+    const key = after.split(/[ \t#]/)[0]?.trim();
+    return key || null;
+  }
+
+  function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return null;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx <= 0) return null;
+    const varName = trimmed.slice(0, eqIdx).trim();
+    const value = trimmed.slice(eqIdx + 1).trim();
+    const key = parseSecretKey(value);
+    if (!key) return null;
+    return { varName: varName || 'Secret', key };
+  }
+
+  const out = [];
+  const seen = new Set();
+
+  for (const line of raw.split('\n')) {
+    const parsed = parseLine(line);
+    if (!parsed) continue;
+    const dedupeKey = `${parsed.varName}::${parsed.key}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    out.push({ path: parsed.key, description: parsed.varName });
+  }
+
+  return out;
+}
+
+function _tryReadTextOrNull(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (e) {
+    // Some Jest suites partially mock fs.existsSync; treat missing files as absent templates.
+    if (e && e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
 /**
  * Formats a display name from a key
  * @param {string} key - System or app key
@@ -137,17 +203,51 @@ function rbacOptionalFilename(normalizedExt) {
   return normalizedExt === '.yaml' || normalizedExt === '.yml' ? 'rbac.yaml' : 'rbac.json';
 }
 
+/**
+ * Word-wraps plain description text for Markdown (MD013 ~80 columns). Keeps blank
+ * lines between paragraphs.
+ * @param {string} text - Raw description
+ * @param {number} [maxLen=80] - Target max line length
+ * @returns {string}
+ */
+function wrapPlainTextForMarkdown(text, maxLen = 80) {
+  if (!text || typeof text !== 'string') return text;
+  const blocks = text.split(/\n\s*\n/);
+  const wrapped = blocks.map((block) => {
+    const flat = block.replace(/\s+/g, ' ').trim();
+    if (!flat) return '';
+    const words = flat.split(' ');
+    const lines = [];
+    let current = '';
+    for (const w of words) {
+      const candidate = current ? `${current} ${w}` : w;
+      if (candidate.length <= maxLen) {
+        current = candidate;
+      } else {
+        if (current) lines.push(current);
+        current = w;
+      }
+    }
+    if (current) lines.push(current);
+    return lines.join('\n');
+  });
+  return wrapped.filter(Boolean).join('\n\n');
+}
+
 function buildExternalReadmeContext(params = {}) {
   const appName = params.appName || params.systemKey || 'external-system';
   const systemKey = params.systemKey || appName;
   const displayName = params.displayName || formatDisplayName(systemKey);
-  const description = params.description || `External system integration for ${systemKey}`;
+  const rawDescription = params.description || `External system integration for ${systemKey}`;
+  const description = wrapPlainTextForMarkdown(rawDescription);
   const systemType = params.systemType || 'openapi';
   const fileExt = params.fileExt !== undefined ? params.fileExt : '.json';
   const normalizedExt = fileExt && fileExt.startsWith('.') ? fileExt : `.${fileExt || 'json'}`;
   const datasources = normalizeDatasources(params.datasources, systemKey, fileExt);
   const authType = params.authType || params.authentication?.type || params.authentication?.method || params.authentication?.authType;
-  const secretPaths = buildSecretPaths(systemKey, authType);
+  const projectRoot = getProjectRoot();
+  const secretPathsFromEnv = extractSecretPathsFromEnvTemplate({ projectRoot, appName });
+  const secretPaths = secretPathsFromEnv.length > 0 ? secretPathsFromEnv : buildSecretPaths(systemKey, authType);
   const rbacOptionalFile = rbacOptionalFilename(normalizedExt);
 
   return {
@@ -186,13 +286,26 @@ function loadExternalReadmeTemplate() {
  * @param {Object} params - Context parameters
  * @returns {string} README content
  */
+/**
+ * Collapses 3+ consecutive newlines to 2 (fixes MD012 from Handlebars spacing).
+ * @param {string} md - Markdown body
+ * @returns {string}
+ */
+function collapseConsecutiveBlankLines(md) {
+  if (!md || typeof md !== 'string') return md;
+  return md.replace(/\n{3,}/g, '\n\n');
+}
+
 function generateExternalReadmeContent(params = {}) {
   const template = loadExternalReadmeTemplate();
   const context = buildExternalReadmeContext(params);
-  return template(context);
+  return collapseConsecutiveBlankLines(template(context));
 }
 
 module.exports = {
   buildExternalReadmeContext,
-  generateExternalReadmeContent
+  generateExternalReadmeContent,
+  wrapPlainTextForMarkdown,
+  collapseConsecutiveBlankLines,
+  extractSecretPathsFromEnvTemplate
 };

package/lib/utils/external-system-local-test-tty.js

@@ -19,6 +19,7 @@ const {
   headerKeyValue,
   formatStatusKeyValue,
   colorRollupPrefixedLine,
+  formatSuccessLine,
   metadata: metaGray
 } = require('./cli-test-layout-chalk');
 
@@ -338,7 +339,7 @@ function displayLocalExternalTestPlanLayout(results, verbose, appName) {
 function logVerboseSystemRows(systemResults) {
   for (const s of systemResults || []) {
     const ok = s.valid;
-    logger.log(ok ? chalk.green(`  ✔ ${s.file}`) : chalk.red(`  ✖ ${s.file}`));
+    logger.log(ok ? (chalk.green('  ') + formatSuccessLine(s.file)) : chalk.red(`  ✖ ${s.file}`));
     (s.errors || []).forEach(e => logger.log(chalk.red(`    - ${e}`)));
   }
 }
@@ -346,7 +347,7 @@ function logVerboseSystemRows(systemResults) {
 function logVerboseDatasourceRows(datasourceResults) {
   for (const d of datasourceResults || []) {
     const ok = d.valid;
-    logger.log(ok ? chalk.green(`  ✔ ${d.key} (${d.file})`) : chalk.red(`  ✖ ${d.key} (${d.file})`));
+    logger.log(ok ? (chalk.green('  ') + formatSuccessLine(`${d.key} (${d.file})`)) : chalk.red(`  ✖ ${d.key} (${d.file})`));
     (d.errors || []).forEach(e => logger.log(chalk.red(`    - ${e}`)));
     (d.warnings || []).forEach(w => logger.log(chalk.yellow(`    ⚠ ${w}`)));
     if (d.fieldMappingResults && d.fieldMappingResults.mappedFields) {

package/lib/utils/external-system-readiness-core.js

@@ -43,30 +43,57 @@ function unwrapPublicationResult(res) {
  * Rules: inactive/archived → Failed; MCP expected but missing → Partial; draft → Partial; published/deployed + active → Ready.
  * @param {Object} ds - ExternalDataSourceResponse-like
  * @param {boolean} generateMcpContract - From application config
- * @returns {'ready'|'partial'|'failed'}
+ * @returns {{ tier: 'ready'|'partial'|'failed', partialReason: string|null }}
  */
-function classifyDatasourceTierA(ds, generateMcpContract) {
+function classifyDatasourceTierADetail(ds, generateMcpContract) {
   const active = ds.isActive !== false;
   const status = String(ds.status || '').toLowerCase();
   if (!active || status === 'archived') {
-    return 'failed';
+    return { tier: 'failed', partialReason: null };
   }
   if (generateMcpContract === true && !ds.mcpContract) {
-    return 'partial';
+    return { tier: 'partial', partialReason: 'mcp_missing' };
   }
   if (status === 'draft') {
-    return 'partial';
+    return { tier: 'partial', partialReason: 'draft' };
   }
   if (status === 'published' || status === 'deployed') {
-    return 'ready';
+    return { tier: 'ready', partialReason: null };
+  }
+  return { tier: 'partial', partialReason: 'unknown_status' };
+}
+
+/**
+ * @param {Object} ds - ExternalDataSourceResponse-like
+ * @param {boolean} generateMcpContract - From application config
+ * @returns {'ready'|'partial'|'failed'}
+ */
+function classifyDatasourceTierA(ds, generateMcpContract) {
+  return classifyDatasourceTierADetail(ds, generateMcpContract).tier;
+}
+
+/**
+ * Short hint for CLI when Tier A is partial (machine codes from classifyDatasourceTierADetail).
+ * @param {string|null} partialReason
+ * @returns {string}
+ */
+function formatTierAPartialHint(partialReason) {
+  if (partialReason === 'mcp_missing') {
+    return 'no MCP contract stored (OpenAPI link or generation)';
+  }
+  if (partialReason === 'draft') {
+    return 'status draft (trigger paths / certification gate)';
   }
-  return 'partial';
+  if (partialReason === 'unknown_status') {
+    return 'unexpected lifecycle status';
+  }
+  return '';
 }
 
 /**
  * @param {Array<Object>} datasources - Datasource list
  * @param {boolean} generateMcpContract
- * @returns {{ rows: Array<{ key: string, tier: string }>, ready: number, partial: number, failed: number }}
+ * @returns {{ rows: Array<{ key: string, tier: string, partialReason?: string|null }>, ready: number, partial: number, failed: number }}
  */
 function summarizeDatasourceTiersA(datasources, generateMcpContract) {
   const rows = [];
@@ -75,10 +102,14 @@ function summarizeDatasourceTiersA(datasources, generateMcpContract) {
   let failed = 0;
   for (const ds of datasources || []) {
     const key = ds.key || ds.sourceKey || 'unknown';
-    const tier = classifyDatasourceTierA(ds, generateMcpContract);
-    rows.push({ key, tier });
-    if (tier === 'ready') ready += 1;
-    else if (tier === 'partial') partial += 1;
+    const detail = classifyDatasourceTierADetail(ds, generateMcpContract);
+    const row = { key, tier: detail.tier };
+    if (detail.tier === 'partial' && detail.partialReason) {
+      row.partialReason = detail.partialReason;
+    }
+    rows.push(row);
+    if (detail.tier === 'ready') ready += 1;
+    else if (detail.tier === 'partial') partial += 1;
     else failed += 1;
   }
   return { rows, ready, partial, failed };
@@ -401,7 +432,9 @@ module.exports = {
   unwrapApiData,
   unwrapPublicationResult,
   isPublicationResultShape,
+  classifyDatasourceTierADetail,
   classifyDatasourceTierA,
+  formatTierAPartialHint,
   summarizeDatasourceTiersA,
   aggregateVerdictFromCounts,
   classifyDatasourceTierB,

package/lib/utils/external-system-readiness-deploy-display.js

@@ -83,7 +83,7 @@ function logDeployProbeDatasourceSection(probeData) {
  * @param {Object|null} systemFromDataplane
  * @param {boolean} genMcp
  */
-function logDeployContractsSection(systemFromDataplane, genMcp) {
+function logDeployContractsSection(systemFromDataplane, genMcp, dataplaneUrl, systemKey) {
   if (!systemFromDataplane) return;
   logSeparator();
   logSectionTitle('Contracts:');
@@ -94,7 +94,7 @@ function logDeployContractsSection(systemFromDataplane, genMcp) {
   } else {
     logger.log(chalk.gray('○ OpenAPI docs URL not available'));
   }
-  logDocsBlock(systemFromDataplane);
+  logDocsBlock(systemFromDataplane, { dataplaneUrl, systemKey, genMcp: mcpOk });
 }
 
 /**
@@ -260,7 +260,7 @@ function logDeployReadinessSummary(ctx) {
 
   logDeployIdentityAndCredentialBlocks(systemCfg, !!probeData);
 
-  logDeployContractsSection(systemFromDataplane, genMcp);
+  logDeployContractsSection(systemFromDataplane, genMcp, dataplaneUrl, systemKey);
   logDeployNextActionsSection(systemKey, probeData, summary, genMcp);
 }
 

package/lib/utils/external-system-readiness-display-internals.js

@@ -9,7 +9,11 @@
 const chalk = require('chalk');
 const { failureGlyph, successGlyph } = require('./cli-test-layout-chalk');
 const logger = require('./logger');
-const { extractIdentitySummary, resolveCredentialTestEndpointDisplay } = require('./external-system-readiness-core');
+const {
+  extractIdentitySummary,
+  resolveCredentialTestEndpointDisplay,
+  formatTierAPartialHint
+} = require('./external-system-readiness-core');
 
 const SEP = chalk.gray('────────────────────────────────');
 
@@ -56,8 +60,12 @@ function logDatasourceTable(rows, counts, title) {
   logSectionTitle(title && String(title).trim() ? String(title).trim() : 'Datasources:');
   for (const r of rows) {
     const statusLabel = r.tier === 'ready' ? 'Ready' : r.tier === 'failed' ? 'Failed' : 'Partial';
+    const hint =
+      r.tier === 'partial' && r.partialReason
+        ? chalk.gray(` — ${formatTierAPartialHint(r.partialReason)}`)
+        : '';
     logger.log(
-      `${tierGlyph(r.tier)} ${r.key.padEnd(14, ' ')} ${chalk.gray('(' + statusLabel + ')')}`
+      `${tierGlyph(r.tier)} ${r.key.padEnd(14, ' ')} ${chalk.gray('(' + statusLabel + ')')}${hint}`
     );
   }
   logger.log('');
@@ -120,14 +128,35 @@ function logNextActions(actions, extraLine) {
   }
 }
 
+/**
+ * Dataplane serves MCP OpenAPI docs at /api/v1/mcp/{systemKey}/docs.
+ *
+ * @param {Object} sys - ExternalSystemResponse
+ * @param {{ dataplaneUrl?: string, systemKey?: string, genMcp?: boolean }} [opts]
+ * @returns {string|null}
+ */
+function deriveMcpDocsPageUrl(sys, opts) {
+  if (!sys || !opts) return null;
+  if (sys.mcpDocsPageUrl) return String(sys.mcpDocsPageUrl);
+  const { dataplaneUrl, systemKey, genMcp } = opts;
+  if (!genMcp || !dataplaneUrl || !systemKey) return null;
+  if (!sys.mcpServerUrl) return null;
+  if (!sys.openApiDocsPageUrl && !sys.apiDocumentUrl) return null;
+  const base = String(dataplaneUrl).replace(/\/+$/, '');
+  return `${base}/api/v1/mcp/${encodeURIComponent(systemKey)}/docs`;
+}
+
 /**
  * @param {Object} sys - ExternalSystemResponse
+ * @param {{ dataplaneUrl?: string, systemKey?: string, genMcp?: boolean }} [opts]
  */
-function logDocsBlock(sys) {
+function logDocsBlock(sys, opts) {
   if (!sys) return;
   const urls = [];
   if (sys.openApiDocsPageUrl) urls.push({ label: 'OpenAPI Docs Page', url: sys.openApiDocsPageUrl });
   if (sys.apiDocumentUrl) urls.push({ label: 'API Docs', url: sys.apiDocumentUrl });
+  const mcpDocs = deriveMcpDocsPageUrl(sys, opts);
+  if (mcpDocs) urls.push({ label: 'MCP Docs Page', url: mcpDocs });
   if (sys.mcpServerUrl) urls.push({ label: 'MCP Server', url: sys.mcpServerUrl });
   if (urls.length === 0) return;
   logSeparator();
@@ -147,5 +176,6 @@ module.exports = {
   logIdentityBlock,
   logCredentialIntentBlock,
   logNextActions,
+  deriveMcpDocsPageUrl,
   logDocsBlock
 };

package/lib/utils/external-system-readiness-display.js

@@ -44,7 +44,16 @@ function logPublishResultBlock(publication) {
   }
   logSeparator();
   logSectionTitle('MCP Contract:');
-  logger.log(genMcp ? formatSuccessLine('Generated') : chalk.gray('○ Not requested (generateMcpContract false)'));
+  if (genMcp) {
+    logger.log(formatSuccessLine('Generation requested (manifest generateMcpContract)'));
+    logger.log(
+      chalk.gray(
+        '  Per-datasource MCP appears when dataplane stores mcpContract (OpenAPI resolves + generation succeeds).'
+      )
+    );
+  } else {
+    logger.log(chalk.gray('○ Not requested (generateMcpContract false)'));
+  }
 }
 
 /**

package/lib/utils/file-upload.js

@@ -33,10 +33,10 @@ async function validateFileExists(filePath) {
  * @param {Object} additionalFields - Additional fields
  * @returns {Promise<FormData>} FormData object
  */
-async function buildFormData(filePath, fieldName, additionalFields) {
+async function buildFormData(filePath, fieldName, additionalFields, opts = {}) {
   const formData = new FormData();
   const fileContent = await fs.readFile(filePath);
-  const fileName = path.basename(filePath);
+  const fileName = opts.filenameOverride ? String(opts.filenameOverride) : path.basename(filePath);
   const fileBlob = new Blob([fileContent], { type: 'application/octet-stream' });
   formData.append(fieldName, fileBlob, fileName);
 
@@ -74,6 +74,43 @@ async function uploadFile(url, filePath, fieldName = 'file', authConfig = {}, ad
   return await client.postFormData(endpointPath, formData);
 }
 
+/**
+ * Upload a file using multipart/form-data but override the filename sent to the server.
+ * Useful when the server derives a key from the upload filename.
+ *
+ * @async
+ * @function uploadFileAs
+ * @param {string} url - Full API endpoint URL
+ * @param {string} filePath - Path to file to upload
+ * @param {string} filenameOverride - Filename to present to server (e.g. 'my-key.json')
+ * @param {string} fieldName - Form field name for the file (default: 'file')
+ * @param {Object} [authConfig] - Authentication configuration
+ * @param {Object} [additionalFields] - Additional form fields to include
+ * @returns {Promise<Object>} API response
+ */
+async function uploadFileAs(
+  url,
+  filePath,
+  filenameOverride,
+  fieldName = 'file',
+  authConfig = {},
+  additionalFields = {}
+) {
+  await validateFileExists(filePath);
+  if (!filenameOverride || typeof filenameOverride !== 'string') {
+    throw new Error('filenameOverride is required and must be a string');
+  }
+
+  const parsed = new URL(url);
+  const baseUrl = parsed.origin;
+  const endpointPath = parsed.pathname + parsed.search;
+
+  const formData = await buildFormData(filePath, fieldName, additionalFields, { filenameOverride });
+  const client = new ApiClient(baseUrl, authConfig);
+  return await client.postFormData(endpointPath, formData);
+}
+
 module.exports = {
-  uploadFile
+  uploadFile,
+  uploadFileAs
 };

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 };