@aifabrix/builder 2.40.2 → 2.42.0

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

package/lib/utils/paths.js

@@ -1,13 +1,11 @@
 /**
  * Path Utilities for AI Fabrix Builder
- *
- * Centralized helpers for resolving filesystem locations with support for
- * AIFABRIX_HOME override. Defaults to ~/.aifabrix when not specified.
- *
+ * Centralized helpers for resolving filesystem locations with AIFABRIX_HOME override.
  * @fileoverview Path resolution utilities with environment overrides
  * @author AI Fabrix Team
  * @version 2.0.0
  */
+/* eslint-disable max-lines -- Central path resolution; resolveIntegrationAppKeyFromCwd for datasource commands */
 
 'use strict';
 
@@ -158,14 +156,8 @@ function getFallbackProjectRoot() {
   return path.resolve(__dirname, '..', '..');
 }
 
-/**
- * Gets the project root directory by finding package.json
- * Works reliably in all environments including Jest tests and CI
- * @returns {string} Absolute path to project root
- */
 /**
  * Checks if global PROJECT_ROOT is valid
- * @function checkGlobalProjectRoot
  * @returns {string|null} Valid global root or null
  */
 function checkGlobalProjectRoot() {
@@ -195,39 +187,29 @@ function checkGlobalProjectRoot() {
 
 /**
  * Tries different strategies to find project root
- * @function tryFindProjectRoot
  * @returns {string} Found project root
  */
 function tryFindProjectRoot() {
-  // Strategy 1: Check global.PROJECT_ROOT
   const globalRoot = checkGlobalProjectRoot();
   if (globalRoot) {
     cachedProjectRoot = globalRoot;
     return cachedProjectRoot;
   }
-
-  // Strategy 2: Walk up from __dirname
   const foundRoot = findProjectRootByWalkingUp(__dirname);
   if (foundRoot && hasPackageJson(foundRoot)) {
     cachedProjectRoot = foundRoot;
     return cachedProjectRoot;
   }
-
-  // Strategy 3: Try process.cwd()
   const cwdRoot = findProjectRootFromCwd();
   if (cwdRoot && hasPackageJson(cwdRoot)) {
     cachedProjectRoot = cwdRoot;
     return cachedProjectRoot;
   }
-
-  // Strategy 4: Fallback
   const fallbackRoot = getFallbackProjectRoot();
   if (hasPackageJson(fallbackRoot)) {
     cachedProjectRoot = fallbackRoot;
     return cachedProjectRoot;
   }
-
-  // Last resort
   cachedProjectRoot = fallbackRoot;
   return cachedProjectRoot;
 }
@@ -242,10 +224,7 @@ function getProjectRoot() {
 }
 
 /**
- * Returns the applications base directory for a developer.
- * Dev 0: <home>/applications
- * Dev > 0: <home>/applications-dev-{id}
- *
+ * Returns the applications base directory. Dev 0: <home>/applications; Dev > 0: <home>/applications-dev-{id}
  * @param {number|string} developerId - Developer ID
  * @returns {string} Absolute path to applications base directory
  */
@@ -259,19 +238,13 @@ function getApplicationsBaseDir(developerId) {
 }
 
 /**
- * Returns the developer-specific application directory.
- * Dev 0: points to applications/ (root)
- * Dev > 0: <home>/applications-dev-{id} (root)
- *
+ * Returns the developer-specific application directory. Dev 0: applications/; Dev > 0: applications-dev-{id}
  * @param {string} appName - Application name
  * @param {number|string} developerId - Developer ID
- * @returns {string} Absolute path to developer-specific app directory
+ * @returns {string} Developer-specific app directory (root)
  */
 function getDevDirectory(appName, developerId) {
   const baseDir = getApplicationsBaseDir(developerId);
-  // All files should be generated at the root of the applications folder
-  // Dev 0: <home>/applications
-  // Dev > 0: <home>/applications-dev-{id}
   return baseDir;
 }
 
@@ -292,7 +265,6 @@ function getAppPath(appName, appType) {
 
 /**
  * Base directory for integration/builder: project root when cwd is inside project, else cwd.
- * So deploy works when run from integration/<app> (e.g. node deploy.js), and tests using temp dirs still work.
  * @returns {string} Directory to resolve integration/ and builder/ from
  */
 function getIntegrationBuilderBaseDir() {
@@ -305,9 +277,78 @@ function getIntegrationBuilderBaseDir() {
   return cwd;
 }
 
+/**
+ * Returns the integration root directory (used for listing apps).
+ * @returns {string} Absolute path to integration/ directory
+ */
+function getIntegrationRoot() {
+  return path.join(getIntegrationBuilderBaseDir(), 'integration');
+}
+
+/**
+ * Returns the builder root directory. Uses AIFABRIX_BUILDER_DIR when set, else project/cwd + builder.
+ * @returns {string} Absolute path to builder/ directory
+ */
+function getBuilderRoot() {
+  const envDir = process.env.AIFABRIX_BUILDER_DIR && typeof process.env.AIFABRIX_BUILDER_DIR === 'string'
+    ? process.env.AIFABRIX_BUILDER_DIR.trim()
+    : null;
+  if (envDir) {
+    return path.resolve(envDir);
+  }
+  return path.join(getIntegrationBuilderBaseDir(), 'builder');
+}
+
+/**
+ * Lists app names (directories) under integration root. Excludes dot-prefixed entries.
+ * Returns [] if root does not exist.
+ * @returns {string[]} Sorted list of app directory names
+ */
+function listIntegrationAppNames() {
+  const root = getIntegrationRoot();
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  const stat = fs.statSync(root);
+  if (!stat || typeof stat.isDirectory !== 'function' || !stat.isDirectory()) {
+    return [];
+  }
+  const entries = fs.readdirSync(root);
+  return entries
+    .filter(name => !name.startsWith('.'))
+    .filter(name => {
+      const fullPath = path.join(root, name);
+      return fs.statSync(fullPath).isDirectory();
+    })
+    .sort();
+}
+
+/**
+ * Lists app names (directories) under builder root. Excludes dot-prefixed entries.
+ * Returns [] if root does not exist.
+ * @returns {string[]} Sorted list of app directory names
+ */
+function listBuilderAppNames() {
+  const root = getBuilderRoot();
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  const stat = fs.statSync(root);
+  if (!stat || typeof stat.isDirectory !== 'function' || !stat.isDirectory()) {
+    return [];
+  }
+  const entries = fs.readdirSync(root);
+  return entries
+    .filter(name => !name.startsWith('.'))
+    .filter(name => {
+      const fullPath = path.join(root, name);
+      return fs.statSync(fullPath).isDirectory();
+    })
+    .sort();
+}
+
 /**
  * Gets the integration folder path for external systems.
- * Uses project root when cwd is inside project so deploy works when run from integration/<app> (e.g. node deploy.js).
  * @param {string} appName - Application name
  * @returns {string} Absolute path to integration directory
  */
@@ -320,9 +361,21 @@ function getIntegrationPath(appName) {
 }
 
 /**
- * Gets the builder folder path for regular applications.
- * When AIFABRIX_BUILDER_DIR is set (e.g. by up-miso/up-dataplane from config aifabrix-env-config),
- * uses that as builder root; otherwise uses project root so deploy works when run from integration/<app>.
+ * Resolves build.context from application.yaml to an absolute path.
+ * Used as the canonical app code directory for local mount and (when remote) Mutagen local path.
+ *
+ * @param {string} configDir - Directory containing the application config (e.g. builder/<appKey>/)
+ * @param {string} [buildContext='.'] - build.context value (relative to configDir)
+ * @returns {string} Absolute path to the app code directory
+ */
+function resolveBuildContext(configDir, buildContext) {
+  const dir = (configDir && typeof configDir === 'string') ? configDir : '';
+  const ctx = (buildContext && typeof buildContext === 'string') ? buildContext : '.';
+  return path.resolve(dir, ctx);
+}
+
+/**
+ * Gets the builder folder path. Uses AIFABRIX_BUILDER_DIR when set, else project root.
  * @param {string} appName - Application name
  * @returns {string} Absolute path to builder directory
  */
@@ -462,6 +515,37 @@ async function detectAppType(appName, _options = {}) {
   if (builderResult) return builderResult;
   throw new Error(`App '${appName}' not found in integration/${appName} or builder/${appName}`);
 }
+
+/**
+ * Resolve-specific app path: prefer integration + env.template only (env-only mode).
+ * If integration/<appName>/env.template exists, use that directory without requiring application.yaml.
+ * Otherwise fall back to detectAppType (integration or builder with full config).
+ *
+ * @param {string} appName - Application name
+ * @returns {Promise<{appPath: string, envOnly: boolean}>} appPath and envOnly (true when only env.template is used)
+ * @throws {Error} When app not found in integration or builder
+ */
+async function getResolveAppPath(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+  const integrationPath = getIntegrationPath(appName);
+  const envTemplatePath = path.join(integrationPath, 'env.template');
+  if (fs.existsSync(integrationPath) && fs.existsSync(envTemplatePath)) {
+    return { appPath: integrationPath, envOnly: true };
+  }
+  const result = await detectAppType(appName);
+  return { appPath: result.appPath, envOnly: false };
+}
+
+/** Resolve appKey when cwd is inside integration/<appKey>/. */
+function resolveIntegrationAppKeyFromCwd() {
+  const integrationNorm = path.resolve(path.join(getIntegrationBuilderBaseDir(), 'integration'));
+  const cwd = path.resolve(process.cwd());
+  if (cwd !== integrationNorm && !cwd.startsWith(integrationNorm + path.sep)) return null;
+  return path.relative(integrationNorm, cwd).split(path.sep)[0] || null;
+}
+
 module.exports = {
   getAifabrixHome,
   getConfigDirForPaths,
@@ -471,9 +555,16 @@ module.exports = {
   getProjectRoot,
   getIntegrationPath,
   getBuilderPath,
+  getIntegrationRoot,
+  getBuilderRoot,
+  listIntegrationAppNames,
+  listBuilderAppNames,
+  resolveBuildContext,
   getDeployJsonPath,
   resolveApplicationConfigPath,
   detectAppType,
+  getResolveAppPath,
+  resolveIntegrationAppKeyFromCwd,
   clearProjectRootCache
 };