fix: preserve nested process color output

Author: coisa

AGENTS.md

@@ -111,6 +111,24 @@ composer dev-tools tests -- --coverage=.dev-tools/coverage
 - Rector rules: `src/Rector/`
 - Composer plugin: `src/Composer/`
 
+**Architecture Direction:**
+
+- Avoid introducing new dependencies on `composer/composer` outside the
+  existing Composer plugin integration and legacy surfaces already awaiting
+  decoupling.
+- Prefer DevTools-owned interfaces for generic runtime concerns such as
+  environment variables, process execution, filesystem access, and console
+  presentation instead of reaching for Composer utility classes.
+- When an existing Composer utility is convenient, first check whether a small
+  local abstraction would support the ongoing Composer decoupling work with
+  minimal code.
+- During the Composer-to-Symfony command migration, preserve the global
+  execution affordances already relied on by nested tools: `--ansi`/`--no-ansi`,
+  cache and `--cache-dir` handling, and working-directory behavior.
+- Keep color behavior explicit in command wrappers for tools with known flags
+  instead of probing binaries dynamically; for example, Symfony/Composer-style
+  tools can receive `--ansi`, while PHPUnit uses `--colors=always`.
+
 **Naming Conventions:**
 
 - Classes: PascalCase

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Preserve color-friendly nested command environments, explicit Symfony Console ANSI flags, concise process section labels, and offline-safe PhpMetrics execution without restoring PTY (#239)
 - Keep the reports workflow permission warning loop shell-safe for paths containing backslashes (#244)
 - Keep required PHPUnit matrix checks reporting after workflow-managed `.github/wiki` pointer commits by running the pull-request test workflow without top-level path filters and aligning the packaged consumer test wrapper (#230)
 - Publish pending and per-version required PHPUnit statuses for workflow-dispatched test runs so wiki pointer commits do not wait for an all-matrix aggregate status (#230)

docs/commands/metrics.rst

@@ -93,4 +93,6 @@ Behavior
 - ``--json`` and ``--pretty-json`` keep DevTools itself structured while
   running PhpMetrics in a quieter mode to avoid polluting the captured payload;
 - it runs PhpMetrics through the active PHP binary and suppresses PhpMetrics
-  deprecation notices emitted by the dependency itself.
+  deprecation notices emitted by the dependency itself;
+- it disables PhpMetrics' Composer package freshness lookup so metrics runs do
+  not block on Packagist availability or local network state.

docs/internals/architecture.rst

@@ -75,7 +75,8 @@ command list:
      - Services
    * - ``FastForward\DevTools\Process\ProcessBuilderInterface``
      - ``ProcessBuilderInterface`` and ``ProcessQueueInterface`` build and
-       execute subprocess pipelines.
+       execute subprocess pipelines, while process environment and output
+       Symfony-style sections keep nested command output readable without PTY.
    * - ``Filesystem and metadata``
      - ``FilesystemInterface``, ``ComposerJsonInterface``, and
        ``FileLocatorInterface`` resolve local files, project metadata, and

docs/running/specialized-commands.rst

@@ -132,7 +132,9 @@ Important details:
   structured while forwarding JSON or quieter modes to the wrapped tools where
   available;
 - it suppresses deprecation notices emitted by the PhpMetrics dependency
-  itself so the command output stays readable.
+  itself so the command output stays readable;
+- it disables PhpMetrics' Composer package freshness lookup so report
+  generation does not depend on Packagist connectivity.
 
 ``code-style``
 --------------
@@ -270,6 +272,9 @@ Important details:
   ``--progress`` re-enables it for human-readable runs;
 - ``--json`` and ``--pretty-json`` are propagated to each subprocess, while
   their progress output is suppressed where supported;
+- human-readable runs keep nested command output grouped with concise local
+  section boundaries, pass color-friendly environment variables to
+  subprocesses, and forward explicit ANSI flags to Symfony Console tools;
 - it is the reporting stage used by ``standards``.
 
 ``skills``

src/Console/Command/CodeStyleCommand.php

@@ -132,6 +132,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             ->build('composer normalize');
 
         $processBuilder = $this->processBuilder
+            ->withArgument('--ansi')
             ->withArgument('--config', $this->fileLocator->locate(self::CONFIG));
 
         if (! $progress) {
@@ -148,9 +149,12 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
         $ecs = $processBuilder->build('vendor/bin/ecs');
 
-        $this->processQueue->add($composerUpdate);
-        $this->processQueue->add($composerNormalize);
-        $this->processQueue->add($ecs);
+        $this->processQueue->add(process: $composerUpdate, label: 'Refreshing Composer Lock');
+        $this->processQueue->add(
+            process: $composerNormalize,
+            label: 'Normalizing composer.json with Composer Normalize'
+        );
+        $this->processQueue->add(process: $ecs, label: 'Checking Code Style with Easy Coding Standard');
 
         $result = $this->processQueue->run($processOutput);
 

src/Console/Command/DependenciesCommand.php

@@ -129,12 +129,24 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             return $this->failure($invalidArgumentException->getMessage(), $input);
         }
 
-        $this->processQueue->add($this->getRaiseToInstalledCommand($input));
-        $this->processQueue->add($this->getOpenVersionsCommand($input));
+        $this->processQueue->add(
+            process: $this->getRaiseToInstalledCommand($input),
+            label: 'Raising Dependency Constraints with Jack',
+        );
+        $this->processQueue->add(
+            process: $this->getOpenVersionsCommand($input),
+            label: 'Opening Dependency Constraints with Jack',
+        );
 
         if ($input->getOption('upgrade')) {
-            $this->processQueue->add($this->getComposerUpdateCommand());
-            $this->processQueue->add($this->getComposerNormalizeCommand());
+            $this->processQueue->add(
+                process: $this->getComposerUpdateCommand(),
+                label: 'Updating Dependencies with Composer'
+            );
+            $this->processQueue->add(
+                process: $this->getComposerNormalizeCommand(),
+                label: 'Normalizing composer.json with Composer Normalize',
+            );
         }
 
         if (! $jsonOutput) {
@@ -143,10 +155,14 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             ]);
         }
 
-        $this->processQueue->add($this->getComposerDependencyAnalyserCommand($input));
         $this->processQueue->add(
-            $this->getJackBreakpointCommand($input, $maximumOutdated),
-            $this->shouldIgnoreOutdatedFailures($maximumOutdated),
+            process: $this->getComposerDependencyAnalyserCommand($input),
+            label: 'Analyzing Dependencies with Composer Dependency Analyser',
+        );
+        $this->processQueue->add(
+            process: $this->getJackBreakpointCommand($input, $maximumOutdated),
+            ignoreFailure: $this->shouldIgnoreOutdatedFailures($maximumOutdated),
+            label: 'Checking Outdated Dependencies with Jack',
         );
 
         $result = $this->processQueue->run($processOutput);
@@ -279,7 +295,9 @@ private function getComposerUpdateCommand(): Process
      */
     private function getComposerNormalizeCommand(): Process
     {
-        return $this->processBuilder->build('composer normalize');
+        return $this->processBuilder
+            ->withArgument('--ansi')
+            ->build('composer normalize');
     }
 
     /**

src/Console/Command/DocsCommand.php

@@ -165,7 +165,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
         $phpdoc = $processBuilder->build('vendor/bin/phpdoc');
 
-        $this->processQueue->add($phpdoc);
+        $this->processQueue->add(process: $phpdoc, label: 'Generating API Docs with phpDocumentor');
 
         $result = $this->processQueue->run($processOutput);
 

src/Console/Command/FundingCommand.php

@@ -500,7 +500,10 @@ private function normalizeComposerFile(string $composerFile, OutputInterface $ou
             $processBuilder = $processBuilder->withArgument('--file', $composerBasename);
         }
 
-        $this->processQueue->add($processBuilder->build('composer normalize'));
+        $this->processQueue->add(
+            process: $processBuilder->build('composer normalize'),
+            label: 'Normalizing composer.json with Composer Normalize',
+        );
 
         return $this->processQueue->run($output);
     }

src/Console/Command/MetricsCommand.php

@@ -118,6 +118,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $processBuilder = $this->processBuilder
             ->withArgument('--ansi')
             ->withArgument('--git', 'git')
+            ->withArgument('--composer', 'false')
             ->withArgument('--exclude', $exclude)
             ->withArgument('--report-html', $target)
             ->withArgument('--report-json', $target . '/report.json')
@@ -132,9 +133,10 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         }
 
         $this->processQueue->add(
-            $processBuilder
+            process: $processBuilder
                 ->withArgument('.')
-                ->build([\PHP_BINARY, '-derror_reporting=' . self::PHP_ERROR_REPORTING, self::BINARY])
+                ->build([\PHP_BINARY, '-derror_reporting=' . self::PHP_ERROR_REPORTING, self::BINARY]),
+            label: 'Generating Metrics with PhpMetrics',
         );
 
         $result = $this->processQueue->run($processOutput);