fix: improve global self-update scope detection

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Improve self-update global/local scope detection by normalizing Composer home candidates with realpath fallback handling and `XDG_CONFIG_HOME` support, to avoid global installs accidentally running as local updates in symlinked or alternate Composer home environments (#335).
+
 ## [1.25.2] - 2026-05-11
 
 ### Fixed

src/SelfUpdate/ComposerSelfUpdateScopeResolver.php

@@ -22,6 +22,9 @@
 use FastForward\DevTools\Environment\EnvironmentInterface;
 use FastForward\DevTools\Path\DevToolsPathResolver;
 use Symfony\Component\Filesystem\Path;
+use Throwable;
+
+use function Safe\realpath;
 
 /**
  * Detects Composer global DevTools installations from known Composer home paths.
@@ -44,10 +47,10 @@ public function __construct(
      */
     public function isGlobalInstallation(): bool
     {
-        $packagePath = Path::canonicalize($this->packagePath ?? DevToolsPathResolver::getPackagePath());
+        $packagePath = $this->normalizePath($this->packagePath ?? DevToolsPathResolver::getPackagePath());
 
         foreach ($this->getComposerHomeCandidates() as $composerHome) {
-            $globalPackagePath = Path::canonicalize(Path::join($composerHome, self::PACKAGE_PATH));
+            $globalPackagePath = $this->normalizePath(Path::join($composerHome, self::PACKAGE_PATH));
 
             if ($packagePath === $globalPackagePath || str_starts_with(
                 $packagePath,
@@ -74,6 +77,12 @@ private function getComposerHomeCandidates(): array
             $candidates[] = $composerHome;
         }
 
+        $xdgConfigHome = $this->environment->get('XDG_CONFIG_HOME');
+
+        if (null !== $xdgConfigHome && '' !== $xdgConfigHome) {
+            $candidates[] = Path::join($xdgConfigHome, 'composer');
+        }
+
         $home = $this->environment->get('HOME');
 
         if (null !== $home && '' !== $home) {
@@ -90,4 +99,18 @@ private function getComposerHomeCandidates(): array
 
         return array_values(array_unique($candidates));
     }
+
+    /**
+     * Safely canonicalizes a path, resolving symlinks when available.
+     *
+     * @param string $path
+     */
+    private function normalizePath(string $path): string
+    {
+        try {
+            return Path::canonicalize(realpath($path));
+        } catch (Throwable) {
+            return Path::canonicalize($path);
+        }
+    }
 }

tests/SelfUpdate/ComposerSelfUpdateScopeResolverTest.php

@@ -57,6 +57,8 @@ public function isGlobalInstallationWillReturnTrueWhenPackageLivesUnderComposerH
             ->willReturn(null);
         $this->environment->get('APPDATA')
             ->willReturn(null);
+        $this->environment->get('XDG_CONFIG_HOME')
+            ->willReturn(null);
         $resolver = new ComposerSelfUpdateScopeResolver(
             $this->environment->reveal(),
             '/home/felipe/.composer/vendor/fast-forward/dev-tools',
@@ -77,6 +79,8 @@ public function isGlobalInstallationWillReturnTrueWhenPackageLivesUnderDefaultCo
             ->willReturn('/Users/felipe');
         $this->environment->get('APPDATA')
             ->willReturn(null);
+        $this->environment->get('XDG_CONFIG_HOME')
+            ->willReturn(null);
         $resolver = new ComposerSelfUpdateScopeResolver(
             $this->environment->reveal(),
             '/Users/felipe/Library/Application Support/Composer/vendor/fast-forward/dev-tools',
@@ -97,11 +101,35 @@ public function isGlobalInstallationWillReturnFalseWhenPackageLivesUnderProjectV
             ->willReturn('/home/felipe');
         $this->environment->get('APPDATA')
             ->willReturn(null);
+        $this->environment->get('XDG_CONFIG_HOME')
+            ->willReturn(null);
         $resolver = new ComposerSelfUpdateScopeResolver(
             $this->environment->reveal(),
             '/home/felipe/project/vendor/fast-forward/dev-tools',
         );
 
         self::assertFalse($resolver->isGlobalInstallation());
     }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function isGlobalInstallationWillReturnTrueWhenPackageLivesUnderXdgComposerHome(): void
+    {
+        $this->environment->get('COMPOSER_HOME')
+            ->willReturn(null);
+        $this->environment->get('HOME')
+            ->willReturn(null);
+        $this->environment->get('APPDATA')
+            ->willReturn(null);
+        $this->environment->get('XDG_CONFIG_HOME')
+            ->willReturn('/tmp/xdg');
+        $resolver = new ComposerSelfUpdateScopeResolver(
+            $this->environment->reveal(),
+            '/tmp/xdg/composer/vendor/fast-forward/dev-tools',
+        );
+
+        self::assertTrue($resolver->isGlobalInstallation());
+    }
 }