@aifabrix/builder 2.3.5 → 2.4.0

package/lib/audit-logger.js

@@ -14,6 +14,7 @@
 const fs = require('fs').promises;
 const path = require('path');
 const os = require('os');
+const paths = require('./utils/paths');
 
 // Audit log file path (in user's home directory for compliance)
 let auditLogPath = null;
@@ -28,8 +29,7 @@ async function getAuditLogPath() {
     return auditLogPath;
   }
 
-  const homeDir = os.homedir();
-  const aifabrixDir = path.join(homeDir, '.aifabrix');
+  const aifabrixDir = paths.getAifabrixHome();
 
   try {
     await fs.mkdir(aifabrixDir, { recursive: true });

package/lib/build.js

@@ -13,7 +13,7 @@
 const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
-const os = require('os');
+const paths = require('./utils/paths');
 const { exec } = require('child_process');
 const { promisify } = require('util');
 const chalk = require('chalk');
@@ -198,7 +198,7 @@ async function generateDockerfile(appNameOrPath, language, config, buildConfig =
   if (devDir) {
     targetDir = devDir;
   } else {
-    targetDir = path.join(os.homedir(), '.aifabrix', appName);
+    targetDir = path.join(paths.getAifabrixHome(), appName);
   }
 
   if (!fsSync.existsSync(targetDir)) {

package/lib/config.js

@@ -11,12 +11,19 @@
 
 const fs = require('fs').promises;
 const path = require('path');
-const os = require('os');
 const yaml = require('js-yaml');
+const os = require('os');
+// Avoid importing paths here to prevent circular dependency.
+// Config location is always under OS home at ~/.aifabrix/config.yaml
 
+// Default (for tests and constants): always reflects OS home
 const CONFIG_DIR = path.join(os.homedir(), '.aifabrix');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.yaml');
 
+// Runtime config directory (always under OS home)
+const RUNTIME_CONFIG_DIR = path.join(os.homedir(), '.aifabrix');
+const RUNTIME_CONFIG_FILE = path.join(RUNTIME_CONFIG_DIR, 'config.yaml');
+
 // Cache for developer ID - loaded when getConfig() is first called
 let cachedDeveloperId = null;
 
@@ -27,7 +34,7 @@ let cachedDeveloperId = null;
  */
 async function getConfig() {
   try {
-    const configContent = await fs.readFile(CONFIG_FILE, 'utf8');
+    const configContent = await fs.readFile(RUNTIME_CONFIG_FILE, 'utf8');
     let config = yaml.load(configContent);
 
     // Handle empty file or null/undefined result from yaml.load
@@ -91,19 +98,19 @@ async function getConfig() {
 async function saveConfig(data) {
   try {
     // Create directory if it doesn't exist
-    await fs.mkdir(CONFIG_DIR, { recursive: true });
+    await fs.mkdir(RUNTIME_CONFIG_DIR, { recursive: true });
 
     // Set secure permissions
     // Force quotes to ensure numeric-like strings (e.g., "01") remain strings in YAML
     const configContent = yaml.dump(data, { forceQuotes: true });
     // Write file first
-    await fs.writeFile(CONFIG_FILE, configContent, {
+    await fs.writeFile(RUNTIME_CONFIG_FILE, configContent, {
       mode: 0o600,
       flag: 'w'
     });
     // Open file descriptor and fsync to ensure write is flushed to disk
     // This is critical on Windows where file writes may be cached
-    const fd = await fs.open(CONFIG_FILE, 'r+');
+    const fd = await fs.open(RUNTIME_CONFIG_FILE, 'r+');
     try {
       await fd.sync();
     } finally {
@@ -120,7 +127,7 @@ async function saveConfig(data) {
  */
 async function clearConfig() {
   try {
-    await fs.unlink(CONFIG_FILE);
+    await fs.unlink(RUNTIME_CONFIG_FILE);
   } catch (error) {
     if (error.code !== 'ENOENT') {
       throw new Error(`Failed to clear config: ${error.message}`);
@@ -179,7 +186,7 @@ async function setDeveloperId(developerId) {
   // Add a small delay to ensure file system has flushed the write
   await new Promise(resolve => setTimeout(resolve, 100));
   // Read file again with fresh file handle to avoid OS caching
-  const savedContent = await fs.readFile(CONFIG_FILE, 'utf8');
+  const savedContent = await fs.readFile(RUNTIME_CONFIG_FILE, 'utf8');
   const savedConfig = yaml.load(savedContent);
   // YAML may parse numbers as numbers, so convert to string for comparison
   const savedDevIdString = String(savedConfig['developer-id']);
@@ -362,7 +369,8 @@ async function setSecretsEncryptionKey(key) {
  */
 async function getSecretsPath() {
   const config = await getConfig();
-  return config['secrets-path'] || null;
+  // Backward compatibility: prefer new key, fallback to legacy
+  return config['aifabrix-secrets'] || config['secrets-path'] || null;
 }
 
 /**
@@ -376,7 +384,54 @@ async function setSecretsPath(secretsPath) {
   }
 
   const config = await getConfig();
-  config['secrets-path'] = secretsPath;
+  // Store under new canonical key
+  config['aifabrix-secrets'] = secretsPath;
+  await saveConfig(config);
+}
+
+/**
+ * Get aifabrix-home override from configuration
+ * @returns {Promise<string|null>} Home override path or null if not set
+ */
+async function getAifabrixHomeOverride() {
+  const config = await getConfig();
+  return config['aifabrix-home'] || null;
+}
+
+/**
+ * Set aifabrix-home override in configuration
+ * @param {string} homePath - Base directory path for AI Fabrix files
+ * @returns {Promise<void>}
+ */
+async function setAifabrixHomeOverride(homePath) {
+  if (!homePath || typeof homePath !== 'string') {
+    throw new Error('Home path is required and must be a string');
+  }
+  const config = await getConfig();
+  config['aifabrix-home'] = homePath;
+  await saveConfig(config);
+}
+
+/**
+ * Get aifabrix-secrets path from configuration (canonical)
+ * @returns {Promise<string|null>} Secrets path or null if not set
+ */
+async function getAifabrixSecretsPath() {
+  const config = await getConfig();
+  return config['aifabrix-secrets'] || null;
+}
+
+/**
+ * Set aifabrix-secrets path in configuration (canonical)
+ * @param {string} secretsPath - Path to default secrets file
+ * @returns {Promise<void>}
+ */
+async function setAifabrixSecretsPath(secretsPath) {
+  if (!secretsPath || typeof secretsPath !== 'string') {
+    throw new Error('Secrets path is required and must be a string');
+  }
+  const config = await getConfig();
+  config['aifabrix-secrets'] = secretsPath;
   await saveConfig(config);
 }
 
@@ -399,6 +454,10 @@ const exportsObj = {
   setSecretsEncryptionKey,
   getSecretsPath,
   setSecretsPath,
+  getAifabrixHomeOverride,
+  setAifabrixHomeOverride,
+  getAifabrixSecretsPath,
+  setAifabrixSecretsPath,
   CONFIG_DIR,
   CONFIG_FILE
 };

package/lib/infra.js

@@ -13,7 +13,6 @@ const { exec } = require('child_process');
 const { promisify } = require('util');
 const path = require('path');
 const fs = require('fs');
-const os = require('os');
 const handlebars = require('handlebars');
 const secrets = require('./secrets');
 const config = require('./config');
@@ -21,6 +20,7 @@ const devConfig = require('./utils/dev-config');
 const logger = require('./utils/logger');
 const containerUtils = require('./utils/infra-containers');
 const dockerUtils = require('./utils/docker');
+const paths = require('./utils/paths');
 
 // Register Handlebars helper for equality check
 handlebars.registerHelper('eq', (a, b) => a === b);
@@ -84,7 +84,7 @@ async function checkDockerAvailability() {
 }
 
 async function ensureAdminSecrets() {
-  const adminSecretsPath = path.join(os.homedir(), '.aifabrix', 'admin-secrets.env');
+  const adminSecretsPath = path.join(paths.getAifabrixHome(), 'admin-secrets.env');
   if (!fs.existsSync(adminSecretsPath)) {
     logger.log('Generating admin-secrets.env...');
     await secrets.generateAdminSecretsEnv();
@@ -109,8 +109,8 @@ async function startInfra(developerId = null) {
     throw new Error(`Compose template not found: ${templatePath}`);
   }
 
-  // Create infra directory in ~/.aifabrix with dev ID
-  const aifabrixDir = path.join(os.homedir(), '.aifabrix');
+  // Create infra directory in AIFABRIX_HOME with dev ID
+  const aifabrixDir = paths.getAifabrixHome();
   const infraDirName = getInfraDirName(devId);
   const infraDir = path.join(aifabrixDir, infraDirName);
   if (!fs.existsSync(infraDir)) {
@@ -164,7 +164,7 @@ async function startInfra(developerId = null) {
  */
 async function stopInfra() {
   const devId = await config.getDeveloperId();
-  const aifabrixDir = path.join(os.homedir(), '.aifabrix');
+  const aifabrixDir = paths.getAifabrixHome();
   const infraDirName = getInfraDirName(devId);
   const infraDir = path.join(aifabrixDir, infraDirName);
   const composePath = path.join(infraDir, 'compose.yaml');
@@ -201,7 +201,7 @@ async function stopInfra() {
  */
 async function stopInfraWithVolumes() {
   const devId = await config.getDeveloperId();
-  const aifabrixDir = path.join(os.homedir(), '.aifabrix');
+  const aifabrixDir = paths.getAifabrixHome();
   const infraDirName = getInfraDirName(devId);
   const infraDir = path.join(aifabrixDir, infraDirName);
   const composePath = path.join(infraDir, 'compose.yaml');
@@ -337,7 +337,7 @@ async function restartService(serviceName) {
   }
 
   const devId = await config.getDeveloperId();
-  const aifabrixDir = path.join(os.homedir(), '.aifabrix');
+  const aifabrixDir = paths.getAifabrixHome();
   const infraDirName = getInfraDirName(devId);
   const infraDir = path.join(aifabrixDir, infraDirName);
   const composePath = path.join(infraDir, 'compose.yaml');

package/lib/secrets.js

@@ -12,7 +12,6 @@
 const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
-const os = require('os');
 const chalk = require('chalk');
 const logger = require('./utils/logger');
 const config = require('./config');
@@ -33,6 +32,7 @@ const {
   resolveUrlPort
 } = require('./utils/secrets-utils');
 const { decryptSecret, isEncrypted } = require('./utils/secrets-encryption');
+const pathsUtil = require('./utils/paths');
 
 /**
  * Loads environment configuration for docker/local context
@@ -414,7 +414,7 @@ async function generateAdminSecretsEnv(secretsPath) {
     secrets = await loadSecrets(secretsPath);
   } catch (error) {
     // If secrets file doesn't exist, create default secrets
-    const defaultSecretsPath = secretsPath || path.join(os.homedir(), '.aifabrix', 'secrets.yaml');
+    const defaultSecretsPath = secretsPath || path.join(pathsUtil.getAifabrixHome(), 'secrets.yaml');
 
     if (!fs.existsSync(defaultSecretsPath)) {
       logger.log('Creating default secrets file...');
@@ -425,7 +425,7 @@ async function generateAdminSecretsEnv(secretsPath) {
     }
   }
 
-  const aifabrixDir = path.join(os.homedir(), '.aifabrix');
+  const aifabrixDir = pathsUtil.getAifabrixHome();
   const adminEnvPath = path.join(aifabrixDir, 'admin-secrets.env');
 
   if (!fs.existsSync(aifabrixDir)) {

package/lib/utils/build-copy.js

@@ -13,7 +13,7 @@
 const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
-const os = require('os');
+const paths = require('./paths');
 
 /**
  * Copies all files from builder directory to developer-specific directory
@@ -40,9 +40,7 @@ async function copyBuilderToDevDirectory(appName, developerId) {
 
   // Get base directory (applications or applications-dev-{id})
   const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
-  const baseDir = idNum === 0
-    ? path.join(os.homedir(), '.aifabrix', 'applications')
-    : path.join(os.homedir(), '.aifabrix', `applications-dev-${developerId}`);
+  const baseDir = paths.getApplicationsBaseDir(idNum);
 
   // Clear base directory before copying (delete all files)
   if (fsSync.existsSync(baseDir)) {
@@ -117,13 +115,7 @@ async function copyDirectory(sourceDir, targetDir) {
  * @returns {string} Path to developer-specific directory
  */
 function getDevDirectory(appName, developerId) {
-  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
-  if (idNum === 0) {
-    // Dev 0: all apps go directly to applications/ (no subdirectory)
-    return path.join(os.homedir(), '.aifabrix', 'applications');
-  }
-  // Dev > 0: apps go to applications-dev-{id}/{appName}-dev-{id}/
-  return path.join(os.homedir(), '.aifabrix', `applications-dev-${developerId}`, `${appName}-dev-${developerId}`);
+  return paths.getDevDirectory(appName, developerId);
 
 }
 

package/lib/utils/docker.js

@@ -49,7 +49,7 @@ async function getComposeCommand() {
     await execAsync('docker-compose --version');
     return 'docker-compose';
   } catch (_) {
-    throw new Error('Docker Compose is not available (neither "docker compose" nor "docker-compose" found).');
+    throw new Error('Docker Compose is not available (neither "docker compose" nor "docker-compose" found). Install the Docker Compose v2 plugin (e.g., apt-get install docker-compose-plugin) or ensure docker-compose is on PATH.');
   }
 }
 

package/lib/utils/paths.js

@@ -0,0 +1,97 @@
+/**
+ * Path Utilities for AI Fabrix Builder
+ *
+ * Centralized helpers for resolving filesystem locations with support for
+ * AIFABRIX_HOME override. Defaults to ~/.aifabrix when not specified.
+ *
+ * @fileoverview Path resolution utilities with environment overrides
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+function safeHomedir() {
+  try {
+    if (typeof os.homedir === 'function') {
+      const hd = os.homedir();
+      if (typeof hd === 'string' && hd.length > 0) {
+        return hd;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return process.env.HOME || process.env.USERPROFILE || '/';
+}
+
+/**
+ * Returns the base AI Fabrix directory.
+ * Resolved from config.yaml `aifabrix-home` (stored under OS home).
+ * Falls back to ~/.aifabrix when not specified.
+ *
+ * @returns {string} Absolute path to the AI Fabrix home directory
+ */
+function getAifabrixHome() {
+  try {
+    const configPath = path.join(safeHomedir(), '.aifabrix', 'config.yaml');
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, 'utf8');
+      const config = yaml.load(content) || {};
+      const homeOverride = config && typeof config['aifabrix-home'] === 'string' ? config['aifabrix-home'].trim() : '';
+      if (homeOverride) {
+        return path.resolve(homeOverride);
+      }
+    }
+  } catch {
+    // Ignore errors and fall back to default
+  }
+  return path.join(safeHomedir(), '.aifabrix');
+}
+
+/**
+ * Returns the applications base directory for a developer.
+ * Dev 0: <home>/applications
+ * Dev > 0: <home>/applications-dev-{id}
+ *
+ * @param {number|string} developerId - Developer ID
+ * @returns {string} Absolute path to applications base directory
+ */
+function getApplicationsBaseDir(developerId) {
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const base = getAifabrixHome();
+  if (idNum === 0) {
+    return path.join(base, 'applications');
+  }
+  return path.join(base, `applications-dev-${developerId}`);
+}
+
+/**
+ * Returns the developer-specific application directory.
+ * Dev 0: points to applications/ (no app subdirectory)
+ * Dev > 0: <home>/applications-dev-{id}/{appName}-dev-{id}
+ *
+ * @param {string} appName - Application name
+ * @param {number|string} developerId - Developer ID
+ * @returns {string} Absolute path to developer-specific app directory
+ */
+function getDevDirectory(appName, developerId) {
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const baseDir = getApplicationsBaseDir(developerId);
+  if (idNum === 0) {
+    return baseDir;
+  }
+  return path.join(baseDir, `${appName}-dev-${developerId}`);
+}
+
+module.exports = {
+  getAifabrixHome,
+  getApplicationsBaseDir,
+  getDevDirectory
+};
+

package/lib/utils/secrets-path.js

@@ -11,53 +11,32 @@
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
 const yaml = require('js-yaml');
 const config = require('../config');
+const paths = require('./paths');
 
 /**
- * Resolves secrets file path (backward compatibility)
- * Checks common locations if path is not provided
+ * Resolves secrets file path when an explicit path is provided.
+ * If not provided, returns default fallback under <home>/secrets.yaml.
  * @function resolveSecretsPath
  * @param {string} [secretsPath] - Path to secrets file (optional)
  * @returns {string} Resolved secrets file path
  */
 function resolveSecretsPath(secretsPath) {
-  let resolvedPath = secretsPath;
-
-  if (!resolvedPath) {
-    // Check common locations for secrets.local.yaml
-    const commonLocations = [
-      path.join(process.cwd(), '..', 'aifabrix-setup', 'secrets.local.yaml'),
-      path.join(process.cwd(), '..', '..', 'aifabrix-setup', 'secrets.local.yaml'),
-      path.join(process.cwd(), 'secrets.local.yaml'),
-      path.join(process.cwd(), '..', 'secrets.local.yaml'),
-      path.join(os.homedir(), '.aifabrix', 'secrets.yaml')
-    ];
-
-    // Find first existing file
-    for (const location of commonLocations) {
-      if (fs.existsSync(location)) {
-        resolvedPath = location;
-        break;
-      }
-    }
-
-    // If none found, use default location
-    if (!resolvedPath) {
-      resolvedPath = path.join(os.homedir(), '.aifabrix', 'secrets.yaml');
-    }
-  } else if (secretsPath.startsWith('..')) {
-    resolvedPath = path.resolve(process.cwd(), secretsPath);
+  if (secretsPath && secretsPath.startsWith('..')) {
+    return path.resolve(process.cwd(), secretsPath);
   }
-
-  return resolvedPath;
+  if (secretsPath) {
+    return secretsPath;
+  }
+  // Default fallback
+  return path.join(paths.getAifabrixHome(), 'secrets.yaml');
 }
 
 /**
  * Determines the actual secrets file paths that loadSecrets would use
  * Mirrors the cascading lookup logic from loadSecrets
- * Checks config.yaml for general secrets-path as fallback
+ * Uses config.yaml for default secrets path as fallback
  *
  * @async
  * @function getActualSecretsPath
@@ -77,8 +56,8 @@ async function getActualSecretsPath(secretsPath, appName) {
     };
   }
 
-  // Cascading lookup: user's file first
-  const userSecretsPath = path.join(os.homedir(), '.aifabrix', 'secrets.local.yaml');
+  // Cascading lookup: user's file first (under configured home)
+  const userSecretsPath = path.join(paths.getAifabrixHome(), 'secrets.local.yaml');
 
   // Check build.secrets from variables.yaml if appName provided
   let buildSecretsPath = null;
@@ -101,15 +80,14 @@ async function getActualSecretsPath(secretsPath, appName) {
     }
   }
 
-  // If no build.secrets found in variables.yaml, check config.yaml for general secrets-path
+  // If no build.secrets found in variables.yaml, check config.yaml for canonical secrets path
   if (!buildSecretsPath) {
     try {
-      const generalSecretsPath = await config.getSecretsPath();
-      if (generalSecretsPath) {
-        // Resolve relative paths from current working directory
-        buildSecretsPath = path.isAbsolute(generalSecretsPath)
-          ? generalSecretsPath
-          : path.resolve(process.cwd(), generalSecretsPath);
+      const canonicalSecretsPath = await config.getAifabrixSecretsPath();
+      if (canonicalSecretsPath) {
+        buildSecretsPath = path.isAbsolute(canonicalSecretsPath)
+          ? canonicalSecretsPath
+          : path.resolve(process.cwd(), canonicalSecretsPath);
       }
     } catch (error) {
       // Ignore errors, continue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.3.5",
+  "version": "2.4.0",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {

package/templates/applications/README.md.hbs

@@ -148,11 +148,13 @@ aifabrix login --method credentials --app {{appName}} --environment dev
 aifabrix login --method credentials --app {{appName}} --client-id $CLIENT_ID --client-secret $CLIENT_SECRET --environment dev
 ```
 
-### Environment Variables
+### Configuration
 
-```bash
-export AIFABRIX_HOME=/custom/path
-export AIFABRIX_SECRETS=/path/to/secrets.yaml
+Set overrides in `~/.aifabrix/config.yaml`:
+
+```yaml
+aifabrix-home: "/custom/path"
+aifabrix-secrets: "/path/to/secrets.yaml"
 ```
 
 ---