Add DevTools self-update command

Author: coisa

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add a standalone DevTools `self-update` command plus global `--working-dir` and `--auto-update` binary options for local or global installations (#272)
+
 ## [1.23.0] - 2026-04-26
 
 ### Added

README.md

@@ -55,6 +55,12 @@ composer dev-tools
 
 # Automatically fix code standards issues where applicable
 composer dev-tools:fix
+
+# Run the standalone binary from another project directory
+vendor/bin/dev-tools --working-dir=/path/to/project tests
+
+# Update the installed DevTools package
+vendor/bin/dev-tools self-update
 ```
 
 You can also run individual commands for specific development tasks:
@@ -288,6 +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`. |
 
 ## 🔌 Integration
 

docs/commands/index.rst

@@ -20,6 +20,7 @@ Detailed documentation for each dev-tools command.
    agents
    skills
    sync
+   self-update
    funding
    codeowners
    gitignore

docs/commands/self-update.rst

@@ -0,0 +1,58 @@
+self-update
+===========
+
+``self-update`` updates the installed ``fast-forward/dev-tools`` package
+through Composer.
+
+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.
+
+Global runtime options
+----------------------
+
+The standalone DevTools binary also accepts Composer-like global runtime
+options before the command name:
+
+.. code-block:: bash
+
+   vendor/bin/dev-tools --working-dir=/path/to/project tests
+   vendor/bin/dev-tools --auto-update tests
+
+``--working-dir`` (or ``-d``) switches the process directory before resolving
+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.
+
+Version freshness check
+-----------------------
+
+When DevTools runs from an installed package, the binary checks Composer
+metadata for the latest stable ``fast-forward/dev-tools`` release. If a newer
+stable version is available, DevTools prints a warning recommending
+``dev-tools self-update``. This check is best-effort: network, Composer, or
+metadata failures are ignored so the requested command can continue normally.

src/Composer/Capability/DevToolsCommandProvider.php

@@ -21,19 +21,32 @@
 
 use Composer\Plugin\Capability\CommandProvider;
 use FastForward\DevTools\Composer\Command\ProxyCommand;
+use FastForward\DevTools\Composer\DevToolsPluginInterface;
 use FastForward\DevTools\Console\DevTools;
+use Symfony\Component\Console\Command\Command;
 
 /**
  * Provides a registry of custom dev-tools commands mapped for Composer integration.
  * This capability struct MUST implement the defined `CommandProvider`.
  */
-final class DevToolsCommandProvider implements CommandProvider
+final readonly class DevToolsCommandProvider implements CommandProvider
 {
     /**
      * @var string the namespace prefix for dev-tools console commands to be registered as Composer commands
      */
     private const string COMMAND_NAMESPACE = 'FastForward\DevTools\Console\Command';
 
+    private ?DevToolsPluginInterface $plugin;
+
+    /**
+     * @param array<string, mixed> $constructorArguments the Composer capability constructor arguments
+     */
+    public function __construct(array $constructorArguments = [])
+    {
+        $plugin = $constructorArguments['plugin'] ?? null;
+        $this->plugin = $plugin instanceof DevToolsPluginInterface ? $plugin : null;
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -55,9 +68,38 @@ public function getCommands()
                 continue;
             }
 
-            $commands[] = new ProxyCommand($command);
+            if ($this->isRegisteredCommand($command->getName())) {
+                continue;
+            }
+
+            $commands[] = new ProxyCommand($command, $this->getComposerAliases($command));
         }
 
         return $commands;
     }
+
+    /**
+     * Returns command aliases that may be safely exposed to Composer.
+     *
+     * @param Command $command the Symfony command being proxied
+     *
+     * @return list<string>
+     */
+    private function getComposerAliases(Command $command): array
+    {
+        return array_values(array_filter(
+            $command->getAliases(),
+            fn(string $alias): bool => ! $this->isRegisteredCommand($alias),
+        ));
+    }
+
+    /**
+     * Detects names already owned by Composer's active command surface.
+     *
+     * @param string|null $name the command name or alias being evaluated
+     */
+    private function isRegisteredCommand(?string $name): bool
+    {
+        return $this->plugin?->isRegisteredCommand($name) ?? false;
+    }
 }

src/Composer/Command/ProxyCommand.php

@@ -31,14 +31,16 @@ final class ProxyCommand extends BaseCommand
 {
     /**
      * @param Command $command the Symfony command adapted for Composer plugin execution
+     * @param list<string>|null $aliases the optional alias list exposed to Composer
      */
     public function __construct(
         private readonly Command $command,
+        ?array $aliases = null,
     ) {
         parent::__construct($this->command->getName());
 
         $this
-            ->setAliases($this->command->getAliases())
+            ->setAliases($aliases ?? $this->command->getAliases())
             ->setDescription($this->command->getDescription())
             ->setHelp($this->command->getHelp())
             ->setDefinition(clone $this->command->getDefinition())

src/Composer/DevToolsPluginInterface.php

@@ -0,0 +1,90 @@
+<?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\Composer;
+
+use Composer\Plugin\PluginInterface;
+
+/**
+ * Defines DevTools-specific Composer plugin conventions.
+ */
+interface DevToolsPluginInterface extends PluginInterface
+{
+    public const array COMPOSER_COMMAND_NAMES = [
+        '_complete',
+        'about',
+        'archive',
+        'audit',
+        'browse',
+        'bump',
+        'cc',
+        'check-platform-reqs',
+        'clear-cache',
+        'clearcache',
+        'completion',
+        'config',
+        'create-project',
+        'depends',
+        'diagnose',
+        'dump-autoload',
+        'dumpautoload',
+        'exec',
+        'fund',
+        'global',
+        'help',
+        'home',
+        'i',
+        'info',
+        'init',
+        'install',
+        'licenses',
+        'list',
+        'outdated',
+        'prohibits',
+        'r',
+        'reinstall',
+        'remove',
+        'repo',
+        'repository',
+        'require',
+        'rm',
+        'run',
+        'run-script',
+        'search',
+        'self-update',
+        'selfupdate',
+        'show',
+        'status',
+        'suggests',
+        'u',
+        'uninstall',
+        'update',
+        'upgrade',
+        'validate',
+        'why',
+        'why-not',
+    ];
+
+    /**
+     * Detects whether a command name or alias is already registered in Composer's command surface.
+     *
+     * @param string|null $name the command name or alias being evaluated
+     */
+    public function isRegisteredCommand(?string $name): bool;
+}

src/Composer/Plugin.php

@@ -21,20 +21,21 @@
 
 use Composer\Composer;
 use Composer\EventDispatcher\EventSubscriberInterface;
-use Composer\Script\Event;
 use Composer\IO\IOInterface;
 use Composer\Plugin\Capability\CommandProvider;
 use Composer\Plugin\Capable;
-use Composer\Plugin\PluginInterface;
+use Composer\Script\Event;
 use Composer\Script\ScriptEvents;
 use FastForward\DevTools\Composer\Capability\DevToolsCommandProvider;
 
 /**
  * Implements the lifecycle of the Composer dev-tools extension framework.
  * This plugin class MUST initialize and coordinate custom script registrations securely.
  */
-final class Plugin implements Capable, EventSubscriberInterface, PluginInterface
+final class Plugin implements Capable, DevToolsPluginInterface, EventSubscriberInterface
 {
+    private ?Composer $composer = null;
+
     /**
      * Resolves the implemented Composer capabilities structure.
      *
@@ -84,6 +85,29 @@ public function runSyncCommand(Event $event): void
             ->execute('vendor/bin/dev-tools dev-tools:sync');
     }
 
+    /**
+     * Detects whether a command name or alias is already registered in Composer's command surface.
+     *
+     * @param string|null $name the command name or alias being evaluated
+     */
+    public function isRegisteredCommand(?string $name): bool
+    {
+        return null !== $name && \in_array($name, $this->getReservedCommandNames(), true);
+    }
+
+    /**
+     * Returns command names and aliases that DevTools plugin commands MUST NOT override.
+     *
+     * @return list<string>
+     */
+    private function getReservedCommandNames(): array
+    {
+        return array_values(array_unique([
+            ...self::COMPOSER_COMMAND_NAMES,
+            ...$this->getRootScriptCommandNames(),
+        ]));
+    }
+
     /**
      * Handles activation lifecycle events for the Composer session.
      *
@@ -96,7 +120,7 @@ public function runSyncCommand(Event $event): void
      */
     public function activate(Composer $composer, IOInterface $io): void
     {
-        // No activation logic needed for this plugin
+        $this->composer = $composer;
     }
 
     /**
@@ -111,7 +135,7 @@ public function activate(Composer $composer, IOInterface $io): void
      */
     public function deactivate(Composer $composer, IOInterface $io): void
     {
-        // No deactivation logic needed for this plugin
+        $this->composer = null;
     }
 
     /**
@@ -126,6 +150,30 @@ public function deactivate(Composer $composer, IOInterface $io): void
      */
     public function uninstall(Composer $composer, IOInterface $io): void
     {
-        // No uninstall logic needed for this plugin
+        $this->composer = null;
+    }
+
+    /**
+     * Returns custom Composer script command names from the active root package.
+     *
+     * @return list<string>
+     */
+    private function getRootScriptCommandNames(): array
+    {
+        if (! $this->composer instanceof Composer) {
+            return [];
+        }
+
+        $names = [];
+
+        foreach (array_keys($this->composer->getPackage()->getScripts()) as $script) {
+            if (\defined(ScriptEvents::class . '::' . str_replace('-', '_', strtoupper($script)))) {
+                continue;
+            }
+
+            $names[] = $script;
+        }
+
+        return $names;
     }
 }