Infer self-update scope from installation

Author: coisa

README.md

@@ -294,7 +294,7 @@ skills they depend on.
 | `composer codeowners` | Generates managed `.github/CODEOWNERS` content from local repository metadata. |
 | `composer gitattributes` | Manages export-ignore rules in `.gitattributes`. |
 | `composer dev-tools:sync` | Updates scripts, CODEOWNERS, funding metadata, workflow stubs, `.editorconfig`, `.gitignore`, `.gitattributes`, wiki setup, packaged skills, and packaged agents. |
-| `vendor/bin/dev-tools self-update` / `composer dev-tools:self-update` | Updates the local DevTools package, or the Composer global installation with `--global`. |
+| `vendor/bin/dev-tools self-update` / `composer dev-tools:self-update` | Updates the local DevTools package, or the Composer global installation when the active binary is globally installed. |
 
 ## 🔌 Integration
 

docs/commands/self-update.rst

@@ -10,21 +10,12 @@ Usage
 .. code-block:: bash
 
    vendor/bin/dev-tools self-update
-   vendor/bin/dev-tools self-update --global
    composer dev-tools:self-update
 
-Options
--------
-
-.. list-table::
-   :header-rows: 1
-   :widths: 24 76
-
-   * - Option
-     - Description
-   * - ``--global``
-     - Run ``composer global update fast-forward/dev-tools`` instead of
-       updating the current project installation.
+When the standalone ``dev-tools`` binary is itself loaded from Composer's
+global installation, ``self-update`` automatically targets
+``composer global update fast-forward/dev-tools``. Local project
+installations update the current project by default.
 
 Global runtime options
 ----------------------
@@ -42,11 +33,11 @@ paths, managed files, or command defaults. This lets a globally installed
 binary operate on another project without first changing shell directories.
 Composer executions can use Composer's own ``--working-dir``/``-d`` option.
 
-``--auto-update`` runs the project self-update flow before the requested
-command. The same behavior MAY be enabled with ``FAST_FORWARD_AUTO_UPDATE``;
-set it to ``global`` when the update should target Composer's global
-installation. Auto-update failures are reported as warnings and do not block
-the requested command.
+``--auto-update`` runs the self-update flow before the requested command. The
+same behavior MAY be enabled with ``FAST_FORWARD_AUTO_UPDATE=1``. When the
+active ``dev-tools`` binary is already installed globally, auto-update also
+targets the global installation by default. Auto-update failures are reported
+as warnings and do not block the requested command.
 
 Version freshness check
 -----------------------

src/Console/Command/SelfUpdateCommand.php

@@ -22,11 +22,11 @@
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
 use FastForward\DevTools\Reflection\ClassReflection;
 use FastForward\DevTools\SelfUpdate\SelfUpdateRunnerInterface;
+use FastForward\DevTools\SelfUpdate\SelfUpdateScopeResolverInterface;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
-use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
 /**
@@ -43,10 +43,12 @@ final class SelfUpdateCommand extends Command
 
     /**
      * @param SelfUpdateRunnerInterface $selfUpdateRunner the runner that executes Composer's update command
+     * @param SelfUpdateScopeResolverInterface $scopeResolver resolves whether the active binary is globally installed
      * @param LoggerInterface $logger the output-aware logger
      */
     public function __construct(
         private readonly SelfUpdateRunnerInterface $selfUpdateRunner,
+        private readonly SelfUpdateScopeResolverInterface $scopeResolver,
         private readonly LoggerInterface $logger,
     ) {
         parent::__construct();
@@ -80,14 +82,9 @@ public static function getCommandNames(): array
     protected function configure(): void
     {
         $this->setHelp(
-            'This command updates fast-forward/dev-tools through Composer. By default it updates the current'
-            . ' project installation; use --global for Composer global installations.'
-        );
-
-        $this->addOption(
-            name: 'global',
-            mode: InputOption::VALUE_NONE,
-            description: 'Update the Composer global fast-forward/dev-tools installation.',
+            'This command updates fast-forward/dev-tools through Composer. When DevTools is running from'
+            . ' Composer global, the command updates that global installation automatically; otherwise it updates'
+            . ' the current project installation.'
         );
     }
 
@@ -101,7 +98,7 @@ protected function configure(): void
      */
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        $global = (bool) $input->getOption('global');
+        $global = $this->scopeResolver->isGlobalInstallation();
 
         $this->logger->info('Updating DevTools installation...', [
             'input' => $input,

src/Console/DevTools.php

@@ -23,6 +23,7 @@
 use Override;
 use FastForward\DevTools\Environment\EnvironmentInterface;
 use FastForward\DevTools\SelfUpdate\SelfUpdateRunnerInterface;
+use FastForward\DevTools\SelfUpdate\SelfUpdateScopeResolverInterface;
 use FastForward\DevTools\SelfUpdate\VersionCheckNotifierInterface;
 use FastForward\DevTools\SelfUpdate\WorkingDirectorySwitcherInterface;
 use FastForward\DevTools\ServiceProvider\DevToolsServiceProvider;
@@ -66,13 +67,15 @@ final class DevTools extends Application
      * @param WorkingDirectorySwitcherInterface $workingDirectorySwitcher switches the process working directory
      * @param VersionCheckNotifierInterface $versionCheckNotifier emits non-blocking version freshness warnings
      * @param SelfUpdateRunnerInterface $selfUpdateRunner runs explicit or automatic self-update flows
+     * @param SelfUpdateScopeResolverInterface $selfUpdateScopeResolver resolves whether the active binary is global
      * @param EnvironmentInterface $environment reads environment flags for optional auto-update behavior
      */
     public function __construct(
         CommandLoaderInterface $commandLoader,
         private readonly WorkingDirectorySwitcherInterface $workingDirectorySwitcher,
         private readonly VersionCheckNotifierInterface $versionCheckNotifier,
         private readonly SelfUpdateRunnerInterface $selfUpdateRunner,
+        private readonly SelfUpdateScopeResolverInterface $selfUpdateScopeResolver,
         private readonly EnvironmentInterface $environment,
     ) {
         parent::__construct('Fast Forward Dev Tools');
@@ -195,7 +198,8 @@ private function runAutoUpdateWhenRequested(InputInterface $input, OutputInterfa
         }
 
         try {
-            $statusCode = $this->selfUpdateRunner->update('global' === $autoUpdateMode, $output);
+            $global = $this->selfUpdateScopeResolver->isGlobalInstallation();
+            $statusCode = $this->selfUpdateRunner->update($global, $output);
         } catch (Throwable) {
             $output->writeln('<comment>DevTools auto-update failed; continuing with the requested command.</comment>');
 
@@ -224,6 +228,6 @@ private function isSelfUpdateCommand(InputInterface $input): bool
      */
     private function isTruthyAutoUpdateMode(?string $mode): bool
     {
-        return null !== $mode && \in_array(strtolower($mode), ['1', 'true', 'yes', 'on', 'global'], true);
+        return null !== $mode && \in_array(strtolower($mode), ['1', 'true', 'yes', 'on'], true);
     }
 }

src/SelfUpdate/ComposerSelfUpdateScopeResolver.php

@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Fast Forward Development Tools for PHP projects.
+ *
+ * This file is part of fast-forward/dev-tools project.
+ *
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/
+ * @see      https://github.com/php-fast-forward/dev-tools
+ * @see      https://github.com/php-fast-forward/dev-tools/issues
+ * @see      https://php-fast-forward.github.io/dev-tools/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\SelfUpdate;
+
+use FastForward\DevTools\Environment\EnvironmentInterface;
+use FastForward\DevTools\Path\DevToolsPathResolver;
+use Symfony\Component\Filesystem\Path;
+
+/**
+ * Detects Composer global DevTools installations from known Composer home paths.
+ */
+final readonly class ComposerSelfUpdateScopeResolver implements SelfUpdateScopeResolverInterface
+{
+    private const string PACKAGE_PATH = 'vendor/fast-forward/dev-tools';
+
+    /**
+     * @param EnvironmentInterface $environment reads Composer home environment values
+     * @param string|null $packagePath the DevTools package path; defaults to the active package root
+     */
+    public function __construct(
+        private EnvironmentInterface $environment,
+        private ?string $packagePath = null,
+    ) {}
+
+    /**
+     * Returns whether DevTools is running from Composer's global installation.
+     */
+    public function isGlobalInstallation(): bool
+    {
+        $packagePath = Path::canonicalize($this->packagePath ?? DevToolsPathResolver::getPackagePath());
+
+        foreach ($this->getComposerHomeCandidates() as $composerHome) {
+            $globalPackagePath = Path::canonicalize(Path::join($composerHome, self::PACKAGE_PATH));
+
+            if ($packagePath === $globalPackagePath || str_starts_with(
+                $packagePath,
+                $globalPackagePath . \DIRECTORY_SEPARATOR
+            )) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Returns candidate Composer home directories for supported platforms.
+     *
+     * @return list<string>
+     */
+    private function getComposerHomeCandidates(): array
+    {
+        $candidates = [];
+        $composerHome = $this->environment->get('COMPOSER_HOME');
+
+        if (null !== $composerHome && '' !== $composerHome) {
+            $candidates[] = $composerHome;
+        }
+
+        $home = $this->environment->get('HOME');
+
+        if (null !== $home && '' !== $home) {
+            $candidates[] = Path::join($home, '.composer');
+            $candidates[] = Path::join($home, '.config/composer');
+            $candidates[] = Path::join($home, 'Library/Application Support/Composer');
+        }
+
+        $appData = $this->environment->get('APPDATA');
+
+        if (null !== $appData && '' !== $appData) {
+            $candidates[] = Path::join($appData, 'Composer');
+        }
+
+        return array_values(array_unique($candidates));
+    }
+}

src/SelfUpdate/SelfUpdateScopeResolverInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Fast Forward Development Tools for PHP projects.
+ *
+ * This file is part of fast-forward/dev-tools project.
+ *
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/
+ * @see      https://github.com/php-fast-forward/dev-tools
+ * @see      https://github.com/php-fast-forward/dev-tools/issues
+ * @see      https://php-fast-forward.github.io/dev-tools/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\SelfUpdate;
+
+/**
+ * Resolves whether self-update SHOULD target the local project or Composer global project.
+ */
+interface SelfUpdateScopeResolverInterface
+{
+    /**
+     * Returns whether DevTools is running from Composer's global installation.
+     */
+    public function isGlobalInstallation(): bool;
+}

src/ServiceProvider/DevToolsServiceProvider.php

@@ -86,8 +86,10 @@
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use FastForward\DevTools\Process\XdebugDisablingProcessEnvironmentConfigurator;
 use FastForward\DevTools\SelfUpdate\ComposerSelfUpdateRunner;
+use FastForward\DevTools\SelfUpdate\ComposerSelfUpdateScopeResolver;
 use FastForward\DevTools\SelfUpdate\ComposerVersionChecker;
 use FastForward\DevTools\SelfUpdate\SelfUpdateRunnerInterface;
+use FastForward\DevTools\SelfUpdate\SelfUpdateScopeResolverInterface;
 use FastForward\DevTools\SelfUpdate\VersionCheckerInterface;
 use FastForward\DevTools\SelfUpdate\VersionCheckNotifier;
 use FastForward\DevTools\SelfUpdate\VersionCheckNotifierInterface;
@@ -147,6 +149,7 @@ public function getFactories(): array
 
             // Self-update
             SelfUpdateRunnerInterface::class => get(ComposerSelfUpdateRunner::class),
+            SelfUpdateScopeResolverInterface::class => get(ComposerSelfUpdateScopeResolver::class),
             VersionCheckerInterface::class => get(ComposerVersionChecker::class),
             VersionCheckNotifierInterface::class => get(VersionCheckNotifier::class),
             WorkingDirectorySwitcherInterface::class => get(WorkingDirectorySwitcher::class),

tests/Console/Command/SelfUpdateCommandTest.php

@@ -24,6 +24,7 @@
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
 use FastForward\DevTools\Reflection\ClassReflection;
 use FastForward\DevTools\SelfUpdate\SelfUpdateRunnerInterface;
+use FastForward\DevTools\SelfUpdate\SelfUpdateScopeResolverInterface;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -53,6 +54,11 @@ final class SelfUpdateCommandTest extends TestCase
      */
     private ObjectProphecy $logger;
 
+    /**
+     * @var ObjectProphecy<SelfUpdateScopeResolverInterface>
+     */
+    private ObjectProphecy $scopeResolver;
+
     /**
      * @var ObjectProphecy<InputInterface>
      */
@@ -71,6 +77,7 @@ final class SelfUpdateCommandTest extends TestCase
     protected function setUp(): void
     {
         $this->selfUpdateRunner = $this->prophesize(SelfUpdateRunnerInterface::class);
+        $this->scopeResolver = $this->prophesize(SelfUpdateScopeResolverInterface::class);
         $this->logger = $this->prophesize(LoggerInterface::class);
         $this->input = $this->prophesize(InputInterface::class);
         $this->output = $this->prophesize(OutputInterface::class);
@@ -80,7 +87,11 @@ protected function setUp(): void
             ->will(static function (): void {});
         $this->logger->error(Argument::cetera())
             ->will(static function (): void {});
-        $this->command = new SelfUpdateCommand($this->selfUpdateRunner->reveal(), $this->logger->reveal());
+        $this->command = new SelfUpdateCommand(
+            $this->selfUpdateRunner->reveal(),
+            $this->scopeResolver->reveal(),
+            $this->logger->reveal()
+        );
     }
 
     /**
@@ -101,7 +112,7 @@ public function getCommandNamesWillReturnAttributeNameAndAliases(): void
     #[Test]
     public function executeWillUpdateProjectInstallation(): void
     {
-        $this->input->getOption('global')
+        $this->scopeResolver->isGlobalInstallation()
             ->willReturn(false);
         $this->selfUpdateRunner->update(false, $this->output->reveal())
             ->willReturn(SelfUpdateCommand::SUCCESS)
@@ -116,15 +127,30 @@ public function executeWillUpdateProjectInstallation(): void
     #[Test]
     public function executeWillReturnFailureWhenUpdateFails(): void
     {
-        $this->input->getOption('global')
-            ->willReturn(true);
-        $this->selfUpdateRunner->update(true, $this->output->reveal())
+        $this->scopeResolver->isGlobalInstallation()
+            ->willReturn(false);
+        $this->selfUpdateRunner->update(false, $this->output->reveal())
             ->willReturn(SelfUpdateCommand::FAILURE)
             ->shouldBeCalledOnce();
 
         self::assertSame(SelfUpdateCommand::FAILURE, $this->executeCommand());
     }
 
+    /**
+     * @return void
+     */
+    #[Test]
+    public function executeWillUpdateGlobalInstallationWhenCurrentBinaryIsGlobal(): void
+    {
+        $this->scopeResolver->isGlobalInstallation()
+            ->willReturn(true);
+        $this->selfUpdateRunner->update(true, $this->output->reveal())
+            ->willReturn(SelfUpdateCommand::SUCCESS)
+            ->shouldBeCalledOnce();
+
+        self::assertSame(SelfUpdateCommand::SUCCESS, $this->executeCommand());
+    }
+
     /**
      * @return int
      */