@aifabrix/builder 2.31.0 → 2.32.1

package/lib/utils/health-check.js

@@ -24,40 +24,91 @@ const execAsync = promisify(exec);
  * @param {string} appName - Application name
  * @throws {Error} If db-init fails
  */
-async function waitForDbInit(appName) {
-  const dbInitContainer = `aifabrix-${appName}-db-init`;
+/**
+ * Checks if db-init container exists
+ * @async
+ * @function checkDbInitContainerExists
+ * @param {string} dbInitContainer - Container name
+ * @returns {Promise<boolean>} True if container exists
+ */
+async function checkDbInitContainerExists(dbInitContainer) {
   try {
     const { stdout } = await execAsync(`docker ps -a --filter "name=${dbInitContainer}" --format "{{.Names}}"`);
-    if (stdout.trim() !== dbInitContainer) {
-      return;
+    return stdout.trim() === dbInitContainer;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Gets container exit code
+ * @async
+ * @function getContainerExitCode
+ * @param {string} dbInitContainer - Container name
+ * @returns {Promise<string>} Exit code
+ */
+async function getContainerExitCode(dbInitContainer) {
+  const { stdout: exitCode } = await execAsync(`docker inspect --format='{{.State.ExitCode}}' ${dbInitContainer}`);
+  return exitCode.trim();
+}
+
+/**
+ * Handles exited container status
+ * @async
+ * @function handleExitedContainer
+ * @param {string} dbInitContainer - Container name
+ * @returns {Promise<boolean>} True if handled (container already exited)
+ */
+async function handleExitedContainer(dbInitContainer) {
+  const { stdout: status } = await execAsync(`docker inspect --format='{{.State.Status}}' ${dbInitContainer}`);
+  if (status.trim() === 'exited') {
+    const exitCode = await getContainerExitCode(dbInitContainer);
+    if (exitCode === '0') {
+      logger.log(chalk.green('✓ Database initialization already completed'));
+    } else {
+      logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
     }
+    return true;
+  }
+  return false;
+}
 
-    const { stdout: status } = await execAsync(`docker inspect --format='{{.State.Status}}' ${dbInitContainer}`);
-    if (status.trim() === 'exited') {
-      const { stdout: exitCode } = await execAsync(`docker inspect --format='{{.State.ExitCode}}' ${dbInitContainer}`);
-      if (exitCode.trim() === '0') {
-        logger.log(chalk.green('✓ Database initialization already completed'));
+/**
+ * Waits for container to exit
+ * @async
+ * @function waitForContainerExit
+ * @param {string} dbInitContainer - Container name
+ * @param {number} maxAttempts - Maximum attempts
+ */
+async function waitForContainerExit(dbInitContainer, maxAttempts) {
+  for (let attempts = 0; attempts < maxAttempts; attempts++) {
+    const { stdout: currentStatus } = await execAsync(`docker inspect --format='{{.State.Status}}' ${dbInitContainer}`);
+    if (currentStatus.trim() === 'exited') {
+      const exitCode = await getContainerExitCode(dbInitContainer);
+      if (exitCode === '0') {
+        logger.log(chalk.green('✓ Database initialization completed'));
       } else {
-        logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode.trim()}`));
+        logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
       }
       return;
     }
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+}
 
-    logger.log(chalk.blue('Waiting for database initialization to complete...'));
-    const maxDbInitAttempts = 30;
-    for (let dbInitAttempts = 0; dbInitAttempts < maxDbInitAttempts; dbInitAttempts++) {
-      const { stdout: currentStatus } = await execAsync(`docker inspect --format='{{.State.Status}}' ${dbInitContainer}`);
-      if (currentStatus.trim() === 'exited') {
-        const { stdout: exitCode } = await execAsync(`docker inspect --format='{{.State.ExitCode}}' ${dbInitContainer}`);
-        if (exitCode.trim() === '0') {
-          logger.log(chalk.green('✓ Database initialization completed'));
-        } else {
-          logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode.trim()}`));
-        }
-        return;
-      }
-      await new Promise(resolve => setTimeout(resolve, 1000));
+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 (error) {
     // db-init container might not exist, which is fine
   }
@@ -71,56 +122,80 @@ async function waitForDbInit(appName) {
  * @param {boolean} [debug=false] - Enable debug logging
  * @returns {Promise<number>} Container port
  */
+/**
+ * Gets port from docker inspect
+ * @async
+ * @function getPortFromDockerInspect
+ * @param {string} appName - Application name
+ * @param {boolean} debug - Debug flag
+ * @returns {Promise<number|null>} Port number or null
+ */
+async function getPortFromDockerInspect(appName, debug) {
+  const inspectCmd = `docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}}{{if $conf}}{{range $conf}}{{.HostPort}}{{end}}{{end}}{{end}}' aifabrix-${appName}`;
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Executing: ${inspectCmd}`));
+  }
+  const { stdout: portMapping } = await execAsync(inspectCmd);
+  const ports = portMapping.trim().split('\n').filter(p => p && p !== '');
+  if (ports.length > 0) {
+    const port = parseInt(ports[0], 10);
+    if (!isNaN(port) && port > 0) {
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Detected port ${port} from docker inspect`));
+      }
+      return port;
+    }
+  }
+  return null;
+}
+
+/**
+ * Gets port from docker ps (fallback)
+ * @async
+ * @function getPortFromDockerPs
+ * @param {string} appName - Application name
+ * @param {boolean} debug - Debug flag
+ * @returns {Promise<number|null>} Port number or null
+ */
+async function getPortFromDockerPs(appName, debug) {
+  const psCmd = `docker ps --filter "name=aifabrix-${appName}" --format "{{.Ports}}"`;
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Fallback: Executing: ${psCmd}`));
+  }
+  const { stdout: psOutput } = await execAsync(psCmd);
+  const portMatch = psOutput.match(/:(\d+)->/);
+  if (!portMatch) {
+    return null;
+  }
+  const port = parseInt(portMatch[1], 10);
+  if (isNaN(port) || port <= 0) {
+    return null;
+  }
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Detected port ${port} from docker ps`));
+  }
+  return port;
+}
+
 async function getContainerPort(appName, debug = false) {
   try {
-    // Try to get the actual mapped host port from Docker
-    // First try docker inspect for the container port mapping
-    const inspectCmd = `docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}}{{if $conf}}{{range $conf}}{{.HostPort}}{{end}}{{end}}{{end}}' aifabrix-${appName}`;
-    if (debug) {
-      logger.log(chalk.gray(`[DEBUG] Executing: ${inspectCmd}`));
-    }
-    const { stdout: portMapping } = await execAsync(inspectCmd);
-    const ports = portMapping.trim().split('\n').filter(p => p && p !== '');
-    if (ports.length > 0) {
-      const port = parseInt(ports[0], 10);
-      if (!isNaN(port) && port > 0) {
-        if (debug) {
-          logger.log(chalk.gray(`[DEBUG] Detected port ${port} from docker inspect`));
-        }
-        return port;
-      }
+    const port = await getPortFromDockerInspect(appName, debug);
+    if (port !== null) {
+      return port;
     }
 
-    // Fallback: try docker ps to get port mapping (format: "0.0.0.0:3010->3000/tcp")
+    // Fallback: try docker ps
     try {
-      const psCmd = `docker ps --filter "name=aifabrix-${appName}" --format "{{.Ports}}"`;
-      if (debug) {
-        logger.log(chalk.gray(`[DEBUG] Fallback: Executing: ${psCmd}`));
-      }
-      const { stdout: psOutput } = await execAsync(psCmd);
-      const portMatch = psOutput.match(/:(\d+)->/);
-      if (!portMatch) {
-        return null;
-      }
-      const port = parseInt(portMatch[1], 10);
-      if (isNaN(port) || port <= 0) {
-        return null;
-      }
-      if (debug) {
-        logger.log(chalk.gray(`[DEBUG] Detected port ${port} from docker ps`));
-      }
-      return port;
+      return await getPortFromDockerPs(appName, debug);
     } catch (error) {
       if (debug) {
         logger.log(chalk.gray(`[DEBUG] Fallback port detection failed: ${error.message}`));
       }
-      // Fall through
     }
   } catch (error) {
     if (debug) {
       logger.log(chalk.gray(`[DEBUG] Port detection failed: ${error.message}`));
     }
-    // Fall through to default
   }
   if (debug) {
     logger.log(chalk.gray('[DEBUG] Using default port 3000'));
@@ -250,17 +325,33 @@ async function checkHealthEndpoint(healthCheckUrl, debug = false) {
  * @returns {Promise<void>} Resolves when health check passes
  * @throws {Error} If health check times out
  */
-async function waitForHealthCheck(appName, timeout = 90, port = null, config = null, debug = false) {
-  await waitForDbInit(appName);
-
-  // Use provided port if given, otherwise detect from Docker
-  // Port provided should be the host port (CLI --port or config.port, NOT localPort)
+/**
+ * Determines health check port
+ * @async
+ * @function determineHealthCheckPort
+ * @param {number|null} port - Provided port
+ * @param {string} appName - Application name
+ * @param {boolean} debug - Debug flag
+ * @returns {Promise<number>} Health check port
+ */
+async function determineHealthCheckPort(port, appName, debug) {
   const healthCheckPort = port !== null && port !== undefined ? port : await getContainerPort(appName, debug);
-
   if (debug) {
     logger.log(chalk.gray(`[DEBUG] Health check port: ${healthCheckPort} (${port !== null && port !== undefined ? 'provided' : 'auto-detected'})`));
   }
+  return healthCheckPort;
+}
 
+/**
+ * Builds health check configuration
+ * @function buildHealthCheckConfig
+ * @param {number} healthCheckPort - Health check port
+ * @param {Object|null} config - Configuration object
+ * @param {number} timeout - Timeout in seconds
+ * @param {boolean} debug - Debug flag
+ * @returns {Object} Health check configuration
+ */
+function buildHealthCheckConfig(healthCheckPort, config, timeout, debug) {
   const healthCheckPath = config?.healthCheck?.path || '/health';
   const healthCheckUrl = `http://localhost:${healthCheckPort}${healthCheckPath}`;
   const maxAttempts = timeout / 2;
@@ -270,25 +361,50 @@ async function waitForHealthCheck(appName, timeout = 90, port = null, config = n
     logger.log(chalk.gray(`[DEBUG] Timeout: ${timeout} seconds, Max attempts: ${maxAttempts}`));
   }
 
-  for (let attempts = 0; attempts < maxAttempts; attempts++) {
-    try {
-      if (debug) {
-        logger.log(chalk.gray(`[DEBUG] Health check attempt ${attempts + 1}/${maxAttempts}`));
-      }
-      const healthCheckPassed = await checkHealthEndpoint(healthCheckUrl, debug);
-      if (healthCheckPassed) {
-        logger.log(chalk.green('✓ Application is healthy'));
-        if (debug) {
-          logger.log(chalk.gray(`[DEBUG] Health check passed after ${attempts + 1} attempt(s)`));
-        }
-        return;
-      }
-    } catch (error) {
+  return { healthCheckUrl, maxAttempts };
+}
+
+/**
+ * Performs a single health check attempt
+ * @async
+ * @function performHealthCheckAttempt
+ * @param {string} healthCheckUrl - Health check URL
+ * @param {number} attempt - Attempt number
+ * @param {number} maxAttempts - Maximum attempts
+ * @param {boolean} debug - Debug flag
+ * @returns {Promise<boolean>} True if health check passed
+ */
+async function performHealthCheckAttempt(healthCheckUrl, attempt, maxAttempts, debug) {
+  try {
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Health check attempt ${attempt + 1}/${maxAttempts}`));
+    }
+    const healthCheckPassed = await checkHealthEndpoint(healthCheckUrl, debug);
+    if (healthCheckPassed) {
+      logger.log(chalk.green('✓ Application is healthy'));
       if (debug) {
-        logger.log(chalk.gray(`[DEBUG] Health check exception on attempt ${attempts + 1}: ${error.message}`));
+        logger.log(chalk.gray(`[DEBUG] Health check passed after ${attempt + 1} attempt(s)`));
       }
-      // If exception occurs, continue retrying until timeout
-      // The error will be handled by timeout error below
+      return true;
+    }
+  } catch (error) {
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Health check exception on attempt ${attempt + 1}: ${error.message}`));
+    }
+  }
+  return false;
+}
+
+async function waitForHealthCheck(appName, timeout = 90, port = null, config = null, debug = false) {
+  await waitForDbInit(appName);
+
+  const healthCheckPort = await determineHealthCheckPort(port, appName, debug);
+  const { healthCheckUrl, maxAttempts } = buildHealthCheckConfig(healthCheckPort, config, timeout, debug);
+
+  for (let attempts = 0; attempts < maxAttempts; attempts++) {
+    const passed = await performHealthCheckAttempt(healthCheckUrl, attempts, maxAttempts, debug);
+    if (passed) {
+      return;
     }
 
     if (attempts < maxAttempts - 1) {

package/lib/utils/infra-containers.js

@@ -11,7 +11,7 @@
 
 const { exec } = require('child_process');
 const { promisify } = require('util');
-const config = require('../config');
+const config = require('../core/config');
 
 const execAsync = promisify(exec);
 

package/lib/utils/infra-status.js

@@ -11,7 +11,7 @@
 
 const { exec } = require('child_process');
 const { promisify } = require('util');
-const config = require('../config');
+const config = require('../core/config');
 const devConfig = require('./dev-config');
 const containerUtils = require('./infra-containers');
 
@@ -74,6 +74,64 @@ async function getInfraStatus() {
   return status;
 }
 
+/**
+ * Gets infrastructure container names for a developer ID
+ * @param {number} devIdNum - Developer ID number
+ * @param {string} devId - Developer ID string
+ * @returns {Array<string>} Array of infrastructure container names
+ */
+function getInfraContainerNames(devIdNum, devId) {
+  if (devIdNum === 0) {
+    return ['aifabrix-postgres', 'aifabrix-redis', 'aifabrix-pgadmin', 'aifabrix-redis-commander'];
+  }
+  return [`aifabrix-dev${devId}-postgres`, `aifabrix-dev${devId}-redis`, `aifabrix-dev${devId}-pgadmin`, `aifabrix-dev${devId}-redis-commander`];
+}
+
+/**
+ * Extracts app name from container name
+ * @param {string} containerName - Container name
+ * @param {number} devIdNum - Developer ID number
+ * @param {string} devId - Developer ID string
+ * @returns {string|null} App name or null if not matched
+ */
+function extractAppName(containerName, devIdNum, devId) {
+  const pattern = devIdNum === 0 ? /^aifabrix-(.+)$/ : new RegExp(`^aifabrix-dev${devId}-(.+)$`);
+  const match = containerName.match(pattern);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extracts host port from docker ports string
+ * @param {string} ports - Docker ports string
+ * @returns {string} Host port or 'unknown'
+ */
+function extractHostPort(ports) {
+  const portMatch = ports.match(/:(\d+)->\d+\//);
+  return portMatch ? portMatch[1] : 'unknown';
+}
+
+/**
+ * Parses container line and creates app status object
+ * @param {string} line - Container line from docker ps
+ * @param {Array<string>} infraContainers - Infrastructure container names
+ * @param {number} devIdNum - Developer ID number
+ * @param {string} devId - Developer ID string
+ * @returns {Object|null} App status object or null if not an app container
+ */
+function parseContainerLine(line, infraContainers, devIdNum, devId) {
+  const [containerName, ports, status] = line.split('\t');
+  if (infraContainers.includes(containerName)) {
+    return null;
+  }
+  const appName = extractAppName(containerName, devIdNum, devId);
+  if (!appName) {
+    return null;
+  }
+  const hostPort = extractHostPort(ports);
+  const url = hostPort !== 'unknown' ? `http://localhost:${hostPort}` : 'unknown';
+  return { name: appName, container: containerName, port: ports, status: status.trim(), url: url };
+}
+
 /**
  * Gets status of running application containers
  * Finds all containers matching pattern aifabrix-dev{id}-* (excluding infrastructure)
@@ -91,23 +149,16 @@ async function getAppStatus() {
   const apps = [];
 
   try {
-    const filterPattern = devId === 0 ? 'aifabrix-' : `aifabrix-dev${devId}-`;
+    const devIdNum = parseInt(devId, 10);
+    const filterPattern = devIdNum === 0 ? 'aifabrix-' : `aifabrix-dev${devId}-`;
     const { stdout } = await execAsync(`docker ps --filter "name=${filterPattern}" --format "{{.Names}}\t{{.Ports}}\t{{.Status}}"`);
     const lines = stdout.trim().split('\n').filter(line => line.trim() !== '');
-    const infraContainers = devId === 0
-      ? ['aifabrix-postgres', 'aifabrix-redis', 'aifabrix-pgadmin', 'aifabrix-redis-commander']
-      : [`aifabrix-dev${devId}-postgres`, `aifabrix-dev${devId}-redis`, `aifabrix-dev${devId}-pgadmin`, `aifabrix-dev${devId}-redis-commander`];
+    const infraContainers = getInfraContainerNames(devIdNum, devId);
     for (const line of lines) {
-      const [containerName, ports, status] = line.split('\t');
-      if (infraContainers.includes(containerName)) continue;
-      const pattern = devId === 0 ? /^aifabrix-(.+)$/ : new RegExp(`^aifabrix-dev${devId}-(.+)$`);
-      const appNameMatch = containerName.match(pattern);
-      if (!appNameMatch) continue;
-      const appName = appNameMatch[1];
-      const portMatch = ports.match(/:(\d+)->\d+\//);
-      const hostPort = portMatch ? portMatch[1] : 'unknown';
-      const url = hostPort !== 'unknown' ? `http://localhost:${hostPort}` : 'unknown';
-      apps.push({ name: appName, container: containerName, port: ports, status: status.trim(), url: url });
+      const appStatus = parseContainerLine(line, infraContainers, devIdNum, devId);
+      if (appStatus) {
+        apps.push(appStatus);
+      }
     }
   } catch (error) {
     return [];

package/lib/utils/local-secrets.js

@@ -93,53 +93,73 @@ async function saveLocalSecret(key, value) {
  * @example
  * await saveSecret('myapp-client-idKeyVault', 'client-id-value', '/path/to/secrets.yaml');
  */
-async function saveSecret(key, value, secretsPath) {
+/**
+ * Validates save secret parameters
+ * @function validateSaveSecretParams
+ * @param {string} key - Secret key
+ * @param {*} value - Secret value
+ * @param {string} secretsPath - Secrets path
+ * @throws {Error} If validation fails
+ */
+function validateSaveSecretParams(key, value, secretsPath) {
   if (!key || typeof key !== 'string') {
     throw new Error('Secret key is required and must be a string');
   }
-
   if (value === undefined || value === null) {
     throw new Error('Secret value is required');
   }
-
   if (!secretsPath || typeof secretsPath !== 'string') {
     throw new Error('Secrets path is required and must be a string');
   }
+}
 
-  // Resolve path (handle absolute vs relative)
+/**
+ * Resolves and prepares secrets path
+ * @function resolveAndPrepareSecretsPath
+ * @param {string} secretsPath - Secrets path
+ * @returns {string} Resolved path
+ */
+function resolveAndPrepareSecretsPath(secretsPath) {
   const resolvedPath = path.isAbsolute(secretsPath)
     ? secretsPath
     : path.resolve(process.cwd(), secretsPath);
 
   const secretsDir = path.dirname(resolvedPath);
-
-  // Create directory if needed
   if (!fs.existsSync(secretsDir)) {
     fs.mkdirSync(secretsDir, { recursive: true, mode: 0o700 });
   }
 
-  // Load existing secrets
-  let existingSecrets = {};
-  if (fs.existsSync(resolvedPath)) {
-    try {
-      const content = fs.readFileSync(resolvedPath, 'utf8');
-      existingSecrets = yaml.load(content) || {};
-      if (typeof existingSecrets !== 'object') {
-        existingSecrets = {};
-      }
-    } catch (error) {
-      logger.warn(`Warning: Could not read existing secrets file: ${error.message}`);
-      existingSecrets = {};
-    }
+  return resolvedPath;
+}
+
+/**
+ * Loads existing secrets from file
+ * @function loadExistingSecrets
+ * @param {string} resolvedPath - Resolved secrets path
+ * @returns {Object} Existing secrets object
+ */
+function loadExistingSecrets(resolvedPath) {
+  if (!fs.existsSync(resolvedPath)) {
+    return {};
   }
 
-  // Merge with new secret
-  const updatedSecrets = {
-    ...existingSecrets,
-    [key]: value
-  };
+  try {
+    const content = fs.readFileSync(resolvedPath, 'utf8');
+    const existingSecrets = yaml.load(content) || {};
+    return typeof existingSecrets === 'object' ? existingSecrets : {};
+  } catch (error) {
+    logger.warn(`Warning: Could not read existing secrets file: ${error.message}`);
+    return {};
+  }
+}
 
-  // Save to file
+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,

package/lib/utils/paths.js

@@ -144,66 +144,78 @@ function getFallbackProjectRoot() {
  * Works reliably in all environments including Jest tests and CI
  * @returns {string} Absolute path to project root
  */
-function getProjectRoot() {
-  // SIMPLIFIED: Always use __dirname walking - most reliable in all environments
-  // This works in: local dev, CI, tests, temp directories, etc.
-  // __dirname is lib/utils/, so we walk up to find package.json
+/**
+ * Checks if global PROJECT_ROOT is valid
+ * @function checkGlobalProjectRoot
+ * @returns {string|null} Valid global root or null
+ */
+function checkGlobalProjectRoot() {
+  if (typeof global === 'undefined' || !global.PROJECT_ROOT) {
+    return null;
+  }
 
-  // Return cached value if available and valid
-  if (cachedProjectRoot && hasPackageJson(cachedProjectRoot)) {
-    return cachedProjectRoot;
+  const globalRoot = global.PROJECT_ROOT;
+  if (!hasPackageJson(globalRoot)) {
+    return null;
   }
 
-  // Strategy 1: Check global.PROJECT_ROOT if set and valid (for test isolation)
-  // BUT: In CI simulation, the project is copied, so global.PROJECT_ROOT might point to original
-  // We need to verify it's actually the correct root by checking if __dirname is within it
-  if (typeof global !== 'undefined' && global.PROJECT_ROOT) {
-    const globalRoot = global.PROJECT_ROOT;
-    if (hasPackageJson(globalRoot)) {
-      // Verify that __dirname is actually within globalRoot (or they're the same)
-      // This ensures we're using the correct project root in CI simulation
-      const dirnameNormalized = path.resolve(__dirname);
-      const globalRootNormalized = path.resolve(globalRoot);
-      const isWithinGlobalRoot = dirnameNormalized.startsWith(globalRootNormalized + path.sep) ||
-                                  dirnameNormalized === globalRootNormalized;
-
-      if (isWithinGlobalRoot) {
-        cachedProjectRoot = globalRoot;
-        return cachedProjectRoot;
-      }
-      // If global.PROJECT_ROOT doesn't contain __dirname, it's wrong (e.g., original project in CI)
-      // Clear it and continue with other strategies
-    }
+  // Verify that __dirname is actually within globalRoot
+  const dirnameNormalized = path.resolve(__dirname);
+  const globalRootNormalized = path.resolve(globalRoot);
+  const isWithinGlobalRoot = dirnameNormalized.startsWith(globalRootNormalized + path.sep) ||
+                            dirnameNormalized === globalRootNormalized;
+
+  return isWithinGlobalRoot ? globalRoot : null;
+}
+
+/**
+ * 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 (lib/utils/) - MOST RELIABLE
-  // This always works because __dirname is always correct relative to the code
+  // Strategy 2: Walk up from __dirname
   const foundRoot = findProjectRootByWalkingUp(__dirname);
   if (foundRoot && hasPackageJson(foundRoot)) {
     cachedProjectRoot = foundRoot;
     return cachedProjectRoot;
   }
 
-  // Strategy 3: Try process.cwd() (works in most cases)
+  // Strategy 3: Try process.cwd()
   const cwdRoot = findProjectRootFromCwd();
   if (cwdRoot && hasPackageJson(cwdRoot)) {
     cachedProjectRoot = cwdRoot;
     return cachedProjectRoot;
   }
 
-  // Strategy 4: Fallback to __dirname relative (lib/utils/ -> project root)
+  // Strategy 4: Fallback
   const fallbackRoot = getFallbackProjectRoot();
   if (hasPackageJson(fallbackRoot)) {
     cachedProjectRoot = fallbackRoot;
     return cachedProjectRoot;
   }
 
-  // Last resort: return fallback even if package.json not found
-  // This prevents crashes but should rarely happen
+  // Last resort
   cachedProjectRoot = fallbackRoot;
   return cachedProjectRoot;
 }
 
+function getProjectRoot() {
+  // Return cached value if available and valid
+  if (cachedProjectRoot && hasPackageJson(cachedProjectRoot)) {
+    return cachedProjectRoot;
+  }
+
+  return tryFindProjectRoot();
+}
+
 /**
  * Returns the applications base directory for a developer.
  * Dev 0: <home>/applications