feat(composer): add command runtime hybrid foundation

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 hybrid command runtime bootstrap and capability bridge that keeps command discovery split between migrated Symfony commands (`DevTools`) and legacy Composer `BaseCommand` commands (`DevToolsComposer`) while exposing proxy commands during Composer execution for the first migration step (#199)
+
 ## [1.22.3] - 2026-04-25
 
 ### Fixed

bin/dev-tools.php

@@ -20,11 +20,19 @@
 namespace FastForward\DevTools;
 
 use FastForward\DevTools\Console\DevTools;
+use FastForward\DevTools\Console\DevToolsComposer;
 use Symfony\Component\Console\Input\ArgvInput;
 
 $projectVendorAutoload = \dirname(__DIR__, 4) . '/vendor/autoload.php';
 $pluginVendorAutoload = \dirname(__DIR__) . '/vendor/autoload.php';
 
 require_once file_exists($projectVendorAutoload) ? $projectVendorAutoload : $pluginVendorAutoload;
 
-DevTools::create()->run(new ArgvInput([...$argv, '--no-plugins']));
+$input = new ArgvInput([...$argv, '--no-plugins']);
+
+$command = $input->getFirstArgument();
+$application = (null !== $command && DevTools::create()->has($command))
+    ? DevTools::create()
+    : DevToolsComposer::create();
+
+$application->run($input);

src/Composer/Capability/DevToolsCommandProvider.php

@@ -21,7 +21,10 @@
 
 use Composer\Command\BaseCommand;
 use Composer\Plugin\Capability\CommandProvider;
+use FastForward\DevTools\Console\Command\ProxyCommand;
 use FastForward\DevTools\Console\DevTools;
+use FastForward\DevTools\Console\DevToolsComposer;
+use Symfony\Component\Console\Command\Command;
 
 /**
  * Provides a registry of custom dev-tools commands mapped for Composer integration.
@@ -34,9 +37,76 @@ final class DevToolsCommandProvider implements CommandProvider
      */
     public function getCommands()
     {
+        $legacyCommands = DevToolsComposer::create()->all();
+        $reservedCommandNames = $this->collectCommandNames($legacyCommands);
+        $migratedCommands = DevTools::create()->all();
+
+        $commands = $legacyCommands;
+
+        foreach ($migratedCommands as $command) {
+            if (! $command instanceof Command || $command instanceof BaseCommand) {
+                continue;
+            }
+
+            if ($this->hasReservedName($command, $reservedCommandNames)) {
+                continue;
+            }
+
+            $commands[] = new ProxyCommand($command);
+        }
+
         return array_values(array_filter(
-            DevTools::create()->all(),
+            $commands,
             static fn(object $command): bool => $command instanceof BaseCommand,
         ));
     }
+
+    /**
+     * Collects command names and aliases that must remain mapped to legacy commands.
+     *
+     * @param array<int, BaseCommand> $commands
+     *
+     * @return array<string, true>
+     */
+    private function collectCommandNames(array $commands): array
+    {
+        $commandNames = [];
+
+        foreach ($commands as $command) {
+            if (! $command instanceof BaseCommand) {
+                continue;
+            }
+
+            if (null !== $command->getName()) {
+                $commandNames[$command->getName()] = true;
+            }
+
+            foreach ($command->getAliases() as $alias) {
+                $commandNames[$alias] = true;
+            }
+        }
+
+        return $commandNames;
+    }
+
+    /**
+     * Verifies whether the command name or any aliases collide with legacy command names.
+     *
+     * @param Command $command
+     * @param array<string, true> $reservedCommandNames
+     */
+    private function hasReservedName(Command $command, array $reservedCommandNames): bool
+    {
+        if (null !== $command->getName() && isset($reservedCommandNames[$command->getName()])) {
+            return true;
+        }
+
+        foreach ($command->getAliases() as $alias) {
+            if (isset($reservedCommandNames[$alias])) {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }

src/Console/Command/AgentsCommand.php

@@ -20,21 +20,21 @@
 namespace FastForward\DevTools\Console\Command;
 
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
-use Composer\Command\BaseCommand;
 use FastForward\DevTools\Console\Input\HasJsonOption;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
 use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\Sync\PackagedDirectorySynchronizer;
 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\Output\OutputInterface;
 
 /**
  * Synchronizes packaged Fast Forward project agents into the consumer repository.
  */
 #[AsCommand(name: 'agents', description: 'Synchronizes Fast Forward project agents into .agents/agents directory.')]
-final class AgentsCommand extends BaseCommand implements LoggerAwareCommandInterface
+final class AgentsCommand extends Command implements LoggerAwareCommandInterface
 {
     use HasJsonOption;
     use LogsCommandResults;
@@ -51,7 +51,7 @@ public function __construct(
         private readonly FilesystemInterface $filesystem,
         private readonly LoggerInterface $logger,
     ) {
-        parent::__construct();
+        parent::__construct('agents');
     }
 
     /**
@@ -98,7 +98,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $this->logger->info('Created .agents/agents directory.');
         }
 
-        $this->synchronizer->setLogger($this->getIO());
+        $this->synchronizer->setLogger($this->logger);
 
         $result = $this->synchronizer->synchronize($agentsDir, $packageAgentsPath, self::AGENTS_DIRECTORY);
 

src/Console/Command/ProxyCommand.php

@@ -0,0 +1,58 @@
+<?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\Console\Command;
+
+use Composer\Command\BaseCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * Adapts migrated Symfony commands to Composer's BaseCommand contract.
+ */
+final class ProxyCommand extends BaseCommand
+{
+    public function __construct(
+        private readonly Command $command,
+    ) {
+        parent::__construct($command->getName());
+
+        $this->setAliases($command->getAliases());
+        $this->setDescription($command->getDescription());
+        $this->setHelp($command->getHelp());
+        $this->setDefinition(clone $command->getDefinition());
+        $this->setHidden($command->isHidden());
+        $this->setIgnoreValidationErrors($command->ignoreValidationErrors());
+    }
+
+    /**
+     * @param InputInterface $input
+     * @param OutputInterface $output
+     *
+     * @return int
+     */
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $this->command->setApplication($this->getApplication());
+        $this->command->setHelperSet($this->getHelperSet());
+
+        return $this->command->run($input, $output);
+    }
+}

src/Console/CommandLoader/DevToolsCommandLoader.php

@@ -19,6 +19,7 @@
 
 namespace FastForward\DevTools\Console\CommandLoader;
 
+use Composer\Command\BaseCommand;
 use FastForward\DevTools\Filesystem\FinderFactoryInterface;
 use Psr\Container\ContainerInterface;
 use ReflectionClass;
@@ -35,6 +36,7 @@
  * console commands and SHALL only register classes that:
  * - Are instantiable
  * - Extend the Symfony\Component\Console\Command\Command base class
+ * - Are not Composer\Command\BaseCommand-based command implementations
  * - Declare the Symfony\Component\Console\Attribute\AsCommand attribute
  *
  * The command name MUST be extracted from the AsCommand attribute metadata and
@@ -53,9 +55,9 @@ final class DevToolsCommandLoader extends ContainerCommandLoader
      * @param FinderFactoryInterface $finderFactory
      * @param ContainerInterface $container
      */
-    public function __construct(FinderFactoryInterface $finderFactory, ContainerInterface $container)
+    public function __construct(FinderFactoryInterface $finderFactory, ContainerInterface $container, bool $skipLegacyBaseCommands = false)
     {
-        parent::__construct($container, $this->getCommandMap($finderFactory));
+        parent::__construct($container, $this->getCommandMap($finderFactory, $skipLegacyBaseCommands));
     }
 
     /**
@@ -65,7 +67,7 @@ public function __construct(FinderFactoryInterface $finderFactory, ContainerInte
      *
      * @return array
      */
-    private function getCommandMap(FinderFactoryInterface $finderFactory): array
+    private function getCommandMap(FinderFactoryInterface $finderFactory, bool $skipLegacyBaseCommands): array
     {
         $commandMap = [];
 
@@ -89,6 +91,10 @@ private function getCommandMap(FinderFactoryInterface $finderFactory): array
                 continue;
             }
 
+            if ($skipLegacyBaseCommands && $reflection->isSubclassOf(BaseCommand::class)) {
+                continue;
+            }
+
             $attribute = $reflection->getAttributes(AsCommand::class)[0] ?? null;
 
             if (null === $attribute) {

src/Console/CommandLoader/SymfonyDevToolsCommandLoader.php

@@ -0,0 +1,38 @@
+<?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\Console\CommandLoader;
+
+use FastForward\DevTools\Filesystem\FinderFactoryInterface;
+use Psr\Container\ContainerInterface;
+
+/**
+ * Loads only migrated Symfony commands for the standalone DevTools application runtime.
+ */
+final class SymfonyDevToolsCommandLoader extends DevToolsCommandLoader
+{
+    /**
+     * @param FinderFactoryInterface $finderFactory
+     * @param ContainerInterface $container
+     */
+    public function __construct(FinderFactoryInterface $finderFactory, ContainerInterface $container)
+    {
+        parent::__construct($finderFactory, $container, true);
+    }
+}

src/Console/DevTools.php

@@ -21,7 +21,6 @@
 
 use FastForward\DevTools\ServiceProvider\DevToolsServiceProvider;
 use Override;
-use Composer\Console\Application as ComposerApplication;
 use DI\Container;
 use Psr\Container\ContainerInterface;
 use ReflectionMethod;
@@ -32,7 +31,7 @@
  * Wraps the fast-forward console tooling suite conceptually as an isolated application instance.
  * Extending the base application, it MUST provide default command injections safely.
  */
-final class DevTools extends ComposerApplication
+final class DevTools extends Application
 {
     /**
      * @var ContainerInterface holds the static container instance for global access within the DevTools context