@aifabrix/builder 2.40.2 → 2.41.0

package/lib/utils/env-map.js

@@ -144,6 +144,27 @@ function handlePlainValue(result, key, rawVal, options) {
   result[key] = val;
 }
 
+/** Placeholder in env-config values; replaced with application or default port */
+const PORT_PLACEHOLDER = '${PORT}';
+
+/**
+ * Replaces ${PORT} in all string values of env object (in-place).
+ * Used so env-config.yaml docker/local values resolve correctly (e.g. PORT: ${PORT} -> application port).
+ *
+ * @param {Object} envObj - Flat key-value object (e.g. merged env-config environments.docker)
+ * @param {number} [portNumber=3000] - Port to substitute when value contains ${PORT}
+ */
+function resolvePortInEnvValues(envObj, portNumber = 3000) {
+  if (!envObj || typeof envObj !== 'object') return;
+  const portStr = String(portNumber);
+  for (const key of Object.keys(envObj)) {
+    const val = envObj[key];
+    if (typeof val === 'string' && val.includes(PORT_PLACEHOLDER)) {
+      envObj[key] = val.split(PORT_PLACEHOLDER).join(portStr);
+    }
+  }
+}
+
 /**
  * Normalize environment variable map by splitting host:port values
  * @function normalizeEnvVars
@@ -270,30 +291,38 @@ function calculateDockerPublicPorts(result, devIdNum, schemaBaseVars = {}) {
 /**
  * Build environment variable map for interpolation based on env-config.yaml
  * - Supports values like "host:port" by splitting into *_HOST (host) and *_PORT (port)
+ * - Resolves ${PORT} in env-config values using options.appPort or default 3000 (so docker/local values are correct)
  * - Merges overrides from ~/.aifabrix/config.yaml under environments.{env}
  * - Applies aifabrix-localhost override for local context if configured
  * - Applies developer-id adjustment to port variables for local context
- * - Calculates *_PUBLIC_PORT for docker context (basePort + developer-id * 100)
+ * - Calculates *_PUBLIC_PORT for both local and docker context (basePort + developer-id * 100)
  * @async
  * @function buildEnvVarMap
  * @param {'docker'|'local'} context - Environment context
  * @param {Object} [osModule] - Optional os module (for testing). If not provided, requires 'os'
  * @param {number|null} [developerId] - Optional developer ID for port adjustment. If not provided, will be fetched from config for local context.
+ * @param {Object} [options] - Optional options
+ * @param {number} [options.appPort] - Port to use when resolving ${PORT} in env-config values (e.g. from application.yaml)
  * @returns {Promise<Object>} Map of variables for interpolation
  */
-async function buildEnvVarMap(context, osModule = null, developerId = null) {
+async function buildEnvVarMap(context, osModule = null, developerId = null, options = null) {
   const baseVars = await loadBaseVars(context);
   const os = osModule || require('os');
   const overrideVars = loadOverrideVars(context, os);
   const localhostOverride = context === 'local' ? getLocalhostOverride(os) : null;
   const merged = { ...baseVars, ...overrideVars };
+  const appPort = (options && options.appPort !== undefined && options.appPort !== null && Number.isFinite(Number(options.appPort)))
+    ? Number(options.appPort) : 3000;
+  resolvePortInEnvValues(merged, appPort);
   const result = normalizeEnvVars(merged, context, localhostOverride);
 
+  const devIdNum = await getDeveloperIdNumber(developerId);
   if (context === 'local') {
-    const devIdNum = await getDeveloperIdNumber(developerId);
     applyLocalPortAdjustment(result, devIdNum);
+    const schemaCfg = loadSchemaEnvConfig();
+    const schemaBaseVars = (schemaCfg && schemaCfg.environments && schemaCfg.environments.local) ? schemaCfg.environments.local : {};
+    calculateDockerPublicPorts(result, devIdNum, schemaBaseVars);
   } else if (context === 'docker') {
-    const devIdNum = await getDeveloperIdNumber(developerId);
     const schemaCfg = loadSchemaEnvConfig();
     const schemaBaseVars = (schemaCfg && schemaCfg.environments && schemaCfg.environments[context]) ? schemaCfg.environments[context] : {};
     calculateDockerPublicPorts(result, devIdNum, schemaBaseVars);
@@ -304,6 +333,7 @@ async function buildEnvVarMap(context, osModule = null, developerId = null) {
 
 module.exports = {
   buildEnvVarMap,
-  getDeveloperIdNumber
+  getDeveloperIdNumber,
+  resolvePortInEnvValues
 };
 

package/lib/utils/env-template.js

@@ -15,7 +15,8 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 
 /**
- * Updates env.template to add MISO_CLIENTID, MISO_CLIENTSECRET, and MISO_CONTROLLER_URL entries
+ * Updates env.template to add MISO_CLIENTID, MISO_CLIENTSECRET, and optionally MISO_CONTROLLER_URL.
+ * When MISO_CONTROLLER_URL already exists, its value is left unchanged (e.g. http://${MISO_HOST}:${MISO_PORT}).
  * @async
  * @param {string} appKey - Application key
  * @param {string} clientIdKey - Secret key for client ID (e.g., 'myapp-client-idKeyVault')
@@ -39,7 +40,9 @@ function checkMisoEntries(content) {
 }
 
 /**
- * Updates existing MISO entries
+ * Updates existing MISO entries.
+ * MISO_CONTROLLER_URL is never overwritten when present so that template form
+ * (e.g. http://${MISO_HOST}:${MISO_PORT}) or custom URLs are preserved.
  * @function updateExistingMisoEntries
  * @param {string} content - File content
  * @param {string} clientIdKey - Client ID key
@@ -54,9 +57,7 @@ function updateExistingMisoEntries(content, clientIdKey, clientSecretKey, entrie
   if (entries.hasClientSecret) {
     content = content.replace(/^MISO_CLIENTSECRET\s*=.*$/m, `MISO_CLIENTSECRET=kv://${clientSecretKey}`);
   }
-  if (entries.hasControllerUrl) {
-    content = content.replace(/^MISO_CONTROLLER_URL\s*=.*$/m, 'MISO_CONTROLLER_URL=http://${MISO_HOST}:${MISO_PORT}');
-  }
+  // Do not change existing MISO_CONTROLLER_URL (preserve template or custom value)
   return content;
 }
 

package/lib/utils/error-formatters/http-status-errors.js

@@ -79,12 +79,31 @@ function addErrorMessageIfNotGeneric(lines, errorData) {
 }
 
 /**
- * Adds authentication guidance
+ * Returns true when the error is about Builder Server client certificate (not Controller token).
+ * @param {Object} errorData - Error data
+ * @returns {boolean}
+ */
+function isBuilderServerCertError(errorData) {
+  const msg = (errorData.message || errorData.error || errorData.detail || '').toLowerCase();
+  return msg.includes('client certificate') || msg.includes('issue-cert') || msg.includes('x-client-cert');
+}
+
+/**
+ * Adds authentication guidance (Controller token login). Skipped for Builder Server cert errors.
  * @function addAuthenticationGuidance
  * @param {string[]} lines - Error message lines
  * @param {Object} errorData - Error data
  */
 function addAuthenticationGuidance(lines, errorData) {
+  if (isBuilderServerCertError(errorData)) {
+    lines.push(chalk.gray('Use a certificate from: aifabrix dev init --developer-id <id> --server <url> --pin <pin>'));
+    if (errorData.correlationId) {
+      lines.push('');
+      lines.push(chalk.gray(`Correlation ID: ${errorData.correlationId}`));
+    }
+    return;
+  }
+
   lines.push(chalk.gray('Your authentication token is invalid or has expired.'));
   lines.push('');
   lines.push(chalk.gray('To authenticate, run:'));

package/lib/utils/help-builder.js

@@ -45,6 +45,13 @@ const CATEGORIES = [
       { name: 'wizard' },
       { name: 'build', term: 'build <app>' },
       { name: 'run', term: 'run <app>' },
+      { name: 'shell', term: 'shell <app>' },
+      { name: 'test', term: 'test <app>' },
+      { name: 'install', term: 'install <app>' },
+      { name: 'test-e2e', term: 'test-e2e <app>' },
+      { name: 'lint', term: 'lint <app>' },
+      { name: 'logs', term: 'logs <app>' },
+      { name: 'stop', term: 'stop <app>' },
       { name: 'dockerfile', term: 'dockerfile <app>' }
     ]
   },
@@ -66,7 +73,10 @@ const CATEGORIES = [
     name: 'Application & Datasource Management',
     commands: [
       { name: 'app' },
-      { name: 'datasource' }
+      { name: 'datasource' },
+      { name: 'credential' },
+      { name: 'deployment' },
+      { name: 'service-user' }
     ]
   },
   {
@@ -75,6 +85,8 @@ const CATEGORIES = [
       { name: 'resolve', term: 'resolve <app>' },
       { name: 'json', term: 'json <app>' },
       { name: 'split-json', term: 'split-json <app>' },
+      { name: 'convert', term: 'convert <app>' },
+      { name: 'show', term: 'show <appKey>' },
       { name: 'validate', term: 'validate <appOrFile>' },
       { name: 'diff', term: 'diff <file1> <file2>' }
     ]
@@ -83,6 +95,7 @@ const CATEGORIES = [
     name: 'External Systems',
     commands: [
       { name: 'download', term: 'download <system-key>' },
+      { name: 'upload', term: 'upload <system-key>' },
       { name: 'delete', term: 'delete <system-key>' },
       { name: 'test', term: 'test <app>' },
       { name: 'test-integration', term: 'test-integration <app>' }
@@ -92,7 +105,7 @@ const CATEGORIES = [
     name: 'Developer & Secrets',
     commands: [
       { name: 'dev' },
-      { name: 'secrets' },
+      { name: 'secret' },
       { name: 'secure' }
     ]
   }

package/lib/utils/infra-status.js

@@ -186,8 +186,37 @@ async function getAppStatus() {
   return apps;
 }
 
+/**
+ * Lists app container names for a developer (excludes infra containers).
+ * Used by down-infra to stop/remove all app-related containers on the same network.
+ * When includeExited is true, includes stopped/exited containers (e.g. db-init one-offs).
+ *
+ * @async
+ * @function listAppContainerNamesForDeveloper
+ * @param {string} devId - Developer ID
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.includeExited=false] - If true, use docker ps -a to include exited containers
+ * @returns {Promise<string[]>} Container names (e.g. aifabrix-myapp, aifabrix-keycloak-db-init)
+ */
+async function listAppContainerNamesForDeveloper(devId, options = {}) {
+  const devIdNum = parseInt(devId, 10);
+  const filterPattern = devIdNum === 0 ? 'aifabrix-' : `aifabrix-dev${devId}-`;
+  const infraContainers = getInfraContainerNames(devIdNum, devId);
+  const includeExited = !!options.includeExited;
+  try {
+    const allFlag = includeExited ? ' -a' : '';
+    const { stdout } = await execAsync(`docker ps${allFlag} --filter "name=${filterPattern}" --format "{{.Names}}"`);
+    const names = (stdout || '').trim().split('\n').filter(Boolean);
+    return names.filter(n => !infraContainers.includes(n));
+  } catch {
+    return [];
+  }
+}
+
 module.exports = {
   getInfraStatus,
-  getAppStatus
+  getAppStatus,
+  extractAppName,
+  listAppContainerNamesForDeveloper
 };
 

package/lib/utils/local-secrets.js

@@ -13,11 +13,12 @@ const path = require('path');
 const yaml = require('js-yaml');
 const logger = require('../utils/logger');
 const pathsUtil = require('./paths');
+const { appendSecretsToFile } = require('./secrets-generator');
 
 /**
  * Saves a secret to ~/.aifabrix/secrets.local.yaml
  * Uses paths.getAifabrixHome() to respect config.yaml aifabrix-home override
- * Merges with existing secrets without overwriting other keys
+ * Appends the key to the end of the file without changing existing content (preserves comments and structure)
  *
  * @async
  * @function saveLocalSecret
@@ -39,48 +40,12 @@ async function saveLocalSecret(key, value) {
   }
 
   const secretsPath = path.join(pathsUtil.getAifabrixHome(), 'secrets.local.yaml');
-  const secretsDir = path.dirname(secretsPath);
-
-  // Create directory if needed
-  if (!fs.existsSync(secretsDir)) {
-    fs.mkdirSync(secretsDir, { recursive: true, mode: 0o700 });
-  }
-
-  // Load existing secrets
-  let existingSecrets = {};
-  if (fs.existsSync(secretsPath)) {
-    try {
-      const content = fs.readFileSync(secretsPath, 'utf8');
-      existingSecrets = yaml.load(content) || {};
-      if (typeof existingSecrets !== 'object') {
-        existingSecrets = {};
-      }
-    } catch (error) {
-      logger.warn(`Warning: Could not read existing secrets file: ${error.message}`);
-      existingSecrets = {};
-    }
-  }
-
-  // Merge with new secret
-  const updatedSecrets = {
-    ...existingSecrets,
-    [key]: value
-  };
-
-  // Save to file
-  const yamlContent = yaml.dump(updatedSecrets, {
-    indent: 2,
-    lineWidth: 120,
-    noRefs: true,
-    sortKeys: false
-  });
-
-  fs.writeFileSync(secretsPath, yamlContent, { mode: 0o600 });
+  appendSecretsToFile(secretsPath, { [key]: value });
 }
 
 /**
  * Saves a secret to a specified secrets file path
- * Merges with existing secrets without overwriting other keys
+ * Appends the key to the end of the file without changing existing content (preserves comments and structure)
  *
  * @async
  * @function saveSecret
@@ -134,11 +99,11 @@ function resolveAndPrepareSecretsPath(secretsPath) {
 
 /**
  * Loads existing secrets from file
- * @function loadExistingSecrets
+ * @function _loadExistingSecrets
  * @param {string} resolvedPath - Resolved secrets path
  * @returns {Object} Existing secrets object
  */
-function loadExistingSecrets(resolvedPath) {
+function _loadExistingSecrets(resolvedPath) {
   if (!fs.existsSync(resolvedPath)) {
     return {};
   }
@@ -157,17 +122,7 @@ async function saveSecret(key, value, secretsPath) {
   validateSaveSecretParams(key, value, secretsPath);
 
   const resolvedPath = resolveAndPrepareSecretsPath(secretsPath);
-  const existingSecrets = loadExistingSecrets(resolvedPath);
-
-  const updatedSecrets = { ...existingSecrets, [key]: value };
-  const yamlContent = yaml.dump(updatedSecrets, {
-    indent: 2,
-    lineWidth: 120,
-    noRefs: true,
-    sortKeys: false
-  });
-
-  fs.writeFileSync(resolvedPath, yamlContent, { mode: 0o600 });
+  appendSecretsToFile(resolvedPath, { [key]: value });
 }
 
 /**

package/lib/utils/mutagen-install.js

@@ -0,0 +1,195 @@
+/**
+ * Mutagen binary auto-install: download from GitHub releases into ~/.aifabrix/bin/.
+ * Per remote-docker.md: CLI installs Mutagen when missing; never rely on system PATH.
+ *
+ * @fileoverview Download and install Mutagen to AI Fabrix bin directory
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const fs = require('fs');
+const https = require('https');
+const { getAifabrixHome } = require('./paths');
+const { exec } = require('child_process');
+const { promisify } = require('util');
+
+const execAsync = promisify(exec);
+const fsPromises = fs.promises;
+
+const MUTAGEN_RELEASE_API = 'https://api.github.com/repos/mutagen-io/mutagen/releases/latest';
+
+/**
+ * Platform/arch to Mutagen asset basename (e.g. mutagen_linux_amd64).
+ * @returns {string|null} Basename without version or extension, or null if unsupported
+ */
+function getPlatformAssetBasename() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if (platform === 'win32') {
+    return arch === 'x64' ? 'mutagen_windows_amd64' : arch === 'arm64' ? 'mutagen_windows_arm64' : null;
+  }
+  if (platform === 'darwin') {
+    return arch === 'x64' ? 'mutagen_darwin_amd64' : arch === 'arm64' ? 'mutagen_darwin_arm64' : null;
+  }
+  if (platform === 'linux') {
+    if (arch === 'x64') return 'mutagen_linux_amd64';
+    if (arch === 'arm64') return 'mutagen_linux_arm64';
+    if (arch === 'arm') return 'mutagen_linux_arm';
+    if (arch === 'ia32') return 'mutagen_linux_386';
+  }
+  return null;
+}
+
+/**
+ * Fetch latest release info from GitHub API.
+ * @returns {Promise<{ tagName: string, assets: Array<{ name: string, browser_download_url: string }> }>}
+ * @throws {Error} If request fails or response is invalid
+ */
+function fetchLatestRelease() {
+  return new Promise((resolve, reject) => {
+    const req = https.get(MUTAGEN_RELEASE_API, {
+      headers: { 'User-Agent': 'aifabrix-builder-cli' }
+    }, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`GitHub API returned ${res.statusCode}`));
+        return;
+      }
+      let body = '';
+      res.on('data', chunk => {
+        body += chunk;
+      });
+      res.on('end', () => {
+        try {
+          const data = JSON.parse(body);
+          const tagName = data.tag_name;
+          const assets = (data.assets || []).map(a => ({ name: a.name, browser_download_url: a.browser_download_url }));
+          if (!tagName || !Array.isArray(assets)) {
+            reject(new Error('Invalid GitHub release response'));
+            return;
+          }
+          resolve({ tagName, assets });
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(15000, () => {
+      req.destroy(); reject(new Error('Request timeout'));
+    });
+  });
+}
+
+/**
+ * Download URL to a file.
+ * @param {string} url - Download URL
+ * @param {string} destPath - Full path to write file
+ * @param {(msg: string) => void} [log] - Optional progress logger
+ * @returns {Promise<void>}
+ */
+function downloadToFile(url, destPath, log) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destPath, { flags: 'w' });
+    const req = https.get(url, { headers: { 'User-Agent': 'aifabrix-builder-cli' } }, (res) => {
+      if (res.statusCode !== 200) {
+        file.close();
+        fs.unlink(destPath, () => {});
+        reject(new Error(`Download returned ${res.statusCode}`));
+        return;
+      }
+      res.pipe(file);
+      file.on('finish', () => {
+        file.close(() => resolve());
+      });
+    });
+    req.on('error', (err) => {
+      file.close();
+      fs.unlink(destPath, () => {});
+      reject(err);
+    });
+    req.setTimeout(120000, () => {
+      req.destroy(); reject(new Error('Download timeout'));
+    });
+    if (typeof log === 'function') log('Downloading Mutagen...');
+  });
+}
+
+/**
+ * Extract .tar.gz using system tar; find binary and copy to destPath.
+ * Mutagen tarballs may have binary at root or inside a single top-level directory.
+ * @param {string} archivePath - Path to .tar.gz
+ * @param {string} destPath - Final binary path
+ * @param {string} binaryName - mutagen or mutagen.exe
+ */
+async function extractAndInstall(archivePath, destPath, binaryName) {
+  const tmpDir = path.join(path.dirname(archivePath), `mutagen-extract-${Date.now()}`);
+  await fsPromises.mkdir(tmpDir, { recursive: true });
+  try {
+    await execAsync(`tar -xzf "${archivePath}" -C "${tmpDir}"`, { timeout: 60000 });
+    let sourcePath = path.join(tmpDir, binaryName);
+    if (!fs.existsSync(sourcePath)) {
+      const entries = await fsPromises.readdir(tmpDir, { withFileTypes: true });
+      const sub = entries.length === 1 && entries[0].isDirectory() ? path.join(tmpDir, entries[0].name) : tmpDir;
+      sourcePath = path.join(sub, binaryName);
+      if (!fs.existsSync(sourcePath)) {
+        throw new Error(`Binary ${binaryName} not found in archive`);
+      }
+    }
+    await fsPromises.copyFile(sourcePath, destPath);
+    if (process.platform !== 'win32') {
+      await fsPromises.chmod(destPath, 0o755);
+    }
+  } finally {
+    await fsPromises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Resolve install paths: bin dir, binary name, dest path, and archive path.
+ * @returns {{ binDir: string, binaryName: string, destPath: string, archivePath: string }}
+ */
+function getInstallPaths() {
+  const home = getAifabrixHome();
+  const binDir = path.join(home, 'bin');
+  const binaryName = process.platform === 'win32' ? 'mutagen.exe' : 'mutagen';
+  const destPath = path.join(binDir, binaryName);
+  const archivePath = path.join(binDir, `mutagen-dl-${Date.now()}.tar.gz`);
+  return { binDir, binaryName, destPath, archivePath };
+}
+
+/**
+ * Download and install Mutagen to ~/.aifabrix/bin/. Uses internal path only (no PATH).
+ * @param {(msg: string) => void} [log] - Optional progress logger
+ * @returns {Promise<string>} Path to installed binary
+ * @throws {Error} If platform unsupported, download fails, or install fails
+ */
+async function installMutagen(log) {
+  const basename = getPlatformAssetBasename();
+  if (!basename) {
+    throw new Error(`Mutagen does not provide a binary for ${process.platform}/${process.arch}. Install manually to ~/.aifabrix/bin/.`);
+  }
+  const { tagName, assets } = await fetchLatestRelease();
+  const version = tagName.replace(/^v/, '');
+  const assetName = `${basename}_v${version}.tar.gz`;
+  const asset = assets.find(a => a.name === assetName);
+  if (!asset) {
+    throw new Error(`Mutagen release ${tagName} has no asset ${assetName}. Install manually to ~/.aifabrix/bin/.`);
+  }
+  const { binDir, binaryName, destPath, archivePath } = getInstallPaths();
+  await fsPromises.mkdir(binDir, { recursive: true });
+  try {
+    await downloadToFile(asset.browser_download_url, archivePath, log);
+    if (typeof log === 'function') log('Installing Mutagen...');
+    await extractAndInstall(archivePath, destPath, binaryName);
+  } finally {
+    await fsPromises.unlink(archivePath).catch(() => {});
+  }
+  return destPath;
+}
+
+module.exports = {
+  getPlatformAssetBasename,
+  fetchLatestRelease,
+  installMutagen
+};

package/lib/utils/mutagen.js

@@ -0,0 +1,146 @@
+/**
+ * Mutagen sync – binary path and session helpers (plan 65: sync for dev).
+ *
+ * @fileoverview Mutagen binary resolution; session create/resume/terminate
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { getAifabrixHome } = require('./paths');
+const { exec } = require('child_process');
+const { promisify } = require('util');
+
+const execAsync = promisify(exec);
+
+/**
+ * Name of the Mutagen binary (platform-specific).
+ * @returns {string} mutagen or mutagen.exe
+ */
+function getMutagenBinaryName() {
+  return process.platform === 'win32' ? 'mutagen.exe' : 'mutagen';
+}
+
+/**
+ * Preferred path for Mutagen binary (~/.aifabrix/bin/mutagen or mutagen.exe).
+ * @returns {string} Absolute path
+ */
+function getMutagenBinPath() {
+  const home = getAifabrixHome();
+  return path.join(home, 'bin', getMutagenBinaryName());
+}
+
+/**
+ * Resolve path to Mutagen binary. Uses only ~/.aifabrix/bin/ (never system PATH).
+ * @returns {Promise<string|null>} Path to binary or null if not installed
+ */
+async function getMutagenPath() {
+  const preferred = getMutagenBinPath();
+  return fs.existsSync(preferred) ? preferred : null;
+}
+
+/**
+ * Ensure Mutagen is available: return path if already installed, otherwise download and install
+ * to ~/.aifabrix/bin/ then return that path. Per remote-docker.md: CLI installs when missing.
+ * @param {(msg: string) => void} [log] - Optional progress logger (e.g. logger.log)
+ * @returns {Promise<string>} Path to Mutagen binary
+ * @throws {Error} If install fails (unsupported platform, network, etc.)
+ */
+async function ensureMutagenPath(log) {
+  const existing = await getMutagenPath();
+  if (existing) return existing;
+  const installMutagen = require('./mutagen-install').installMutagen;
+  await installMutagen(log);
+  const pathAfter = getMutagenBinPath();
+  if (!fs.existsSync(pathAfter)) {
+    throw new Error('Mutagen install did not create binary at ' + pathAfter);
+  }
+  return pathAfter;
+}
+
+/**
+ * Session name for app: aifabrix-<dev-id>-<app-key>
+ * @param {string} developerId - Developer ID
+ * @param {string} appKey - App key (e.g. app name)
+ * @returns {string}
+ */
+function getSessionName(developerId, appKey) {
+  return `aifabrix-${developerId}-${appKey}`;
+}
+
+/**
+ * Remote path for sync and Docker -v: user-mutagen-folder + '/' + relative path.
+ * Relative path is remoteSyncPath (normalized) when set, else 'dev/' + appKey.
+ * @param {string} userMutagenFolder - From config (no trailing slash)
+ * @param {string} appKey - App key (used when relativePathOverride is unset)
+ * @param {string} [relativePathOverride] - Optional; when non-empty, used as relative path under user-mutagen-folder (leading slashes stripped)
+ * @returns {string}
+ */
+function getRemotePath(userMutagenFolder, appKey, relativePathOverride) {
+  const base = (userMutagenFolder || '').trim().replace(/\/+$/, '');
+  if (!base) return '';
+  const raw = typeof relativePathOverride === 'string' ? relativePathOverride.trim() : '';
+  const relative = raw ? raw.replace(/^\/+/, '') : '';
+  if (relative) return `${base}/${relative}`;
+  return `${base}/dev/${appKey}`;
+}
+
+/**
+ * SSH URL for Mutagen: sync-ssh-user@sync-ssh-host:remote_path
+ * @param {string} syncSshUser - SSH user
+ * @param {string} syncSshHost - SSH host
+ * @param {string} remotePath - Remote path
+ * @returns {string}
+ */
+function getSyncSshUrl(syncSshUser, syncSshHost, remotePath) {
+  if (!syncSshUser || !syncSshHost || !remotePath) return '';
+  return `${syncSshUser}@${syncSshHost}:${remotePath}`;
+}
+
+/**
+ * List sync session names (one per line).
+ * @param {string} mutagenPath - Path to mutagen binary
+ * @returns {Promise<string[]>}
+ */
+async function listSyncSessionNames(mutagenPath) {
+  const { stdout } = await execAsync(`"${mutagenPath}" sync list --template '{{.Name}}'`, {
+    encoding: 'utf8',
+    timeout: 5000
+  });
+  return (stdout || '').trim().split('\n').filter(Boolean);
+}
+
+/**
+ * Ensure a sync session exists: create or resume. Idempotent.
+ * @param {string} mutagenPath - Path to mutagen binary
+ * @param {string} sessionName - Session name (e.g. aifabrix-01-myapp)
+ * @param {string} localPath - Local app directory (absolute)
+ * @param {string} sshUrl - Remote SSH URL (user@host:path)
+ * @returns {Promise<void>}
+ * @throws {Error} If create or resume fails
+ */
+async function ensureSyncSession(mutagenPath, sessionName, localPath, sshUrl) {
+  const sessions = await listSyncSessionNames(mutagenPath);
+  if (sessions.includes(sessionName)) {
+    await execAsync(`"${mutagenPath}" sync resume "${sessionName}"`, { timeout: 10000 });
+    return;
+  }
+  const local = path.resolve(localPath).replace(/\\/g, '/');
+  await execAsync(
+    `"${mutagenPath}" sync create "${local}" "${sshUrl}" --name "${sessionName}" --sync-mode two-way-resolved`,
+    { timeout: 15000 }
+  );
+}
+
+module.exports = {
+  getMutagenPath,
+  ensureMutagenPath,
+  getMutagenBinaryName,
+  getMutagenBinPath,
+  getSessionName,
+  getRemotePath,
+  getSyncSshUrl,
+  listSyncSessionNames,
+  ensureSyncSession
+};