[refactor] Process queue refactoring for better process management (#45)

.docheader

@@ -1,14 +1,14 @@
 /**
- * This file is part of fast-forward/dev-tools.
+ * Fast Forward Development Tools for PHP projects.
  *
- * This source file is subject to the license bundled
- * with this source code in the file LICENSE.
+ * This file is part of fast-forward/dev-tools project.
  *
- * @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
- * @license   https://opensource.org/licenses/MIT MIT License
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
  *
- * @see       https://github.com/php-fast-forward/dev-tools
- * @see       https://github.com/php-fast-forward
- * @see       https://datatracker.ietf.org/doc/html/rfc2119
+ * @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
  */
-

README.md

@@ -83,6 +83,15 @@ composer dev-tools gitattributes
 # Generates a LICENSE file from composer.json license information
 composer dev-tools license
 
+# Copies packaged or local resources into the consumer repository
+composer dev-tools copy-resource --source resources/docblock --target .docheader
+
+# Installs Fast Forward Git hooks
+composer dev-tools git-hooks
+
+# Updates the composer.json file to match the packaged schema
+composer dev-tools update-composer-json --force
+
 # Installs and synchronizes dev-tools scripts, GitHub Actions workflows,
 # .editorconfig, .gitignore rules, packaged skills, and the repository wiki
 # submodule in .github/wiki
@@ -119,6 +128,14 @@ keeps the same command vocabulary when you prefer running tools directly from
 `vendor/bin/dev-tools`. The consumer sync flow also refreshes `.agents/skills`
 so agents can discover the packaged skills shipped with this repository.
 
+## 🏗️ Architecture
+
+Each command is self-contained and receives its dependencies through constructor injection, following the :abbr:`DI` pattern. The ``ProcessBuilder`` and ``ProcessQueue`` classes provide a fluent API for constructing and executing system processes in sequence.
+
+- ``ProcessBuilderInterface`` - Builds process commands with arguments
+- ``ProcessQueueInterface`` - Manages and executes process queues
+- ``FilesystemInterface`` - Abstracts filesystem operations
+
 ## 🤝 Contributing
 
 Run `composer dev-tools` before opening a pull request. If you change public

bin/dev-tools.php

@@ -3,17 +3,18 @@
 declare(strict_types=1);
 
 /**
- * This file is part of fast-forward/dev-tools.
+ * Fast Forward Development Tools for PHP projects.
  *
- * This source file is subject to the license bundled
- * with this source code in the file LICENSE.
+ * This file is part of fast-forward/dev-tools project.
  *
- * @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
- * @license   https://opensource.org/licenses/MIT MIT License
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
  *
- * @see       https://github.com/php-fast-forward/dev-tools
- * @see       https://github.com/php-fast-forward
- * @see       https://datatracker.ietf.org/doc/html/rfc2119
+ * @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.json

@@ -18,10 +18,12 @@
             "email": "github@mentordosnerds.com"
         }
     ],
-    "homepage": "https://php-fast-forward.github.io/dev-tools/",
+    "homepage": "https://github.com/php-fast-forward/",
     "support": {
         "issues": "https://github.com/php-fast-forward/dev-tools/issues",
-        "source": "https://github.com/php-fast-forward/dev-tools"
+        "wiki": "https://github.com/php-fast-forward/dev-tools/wiki",
+        "source": "https://github.com/php-fast-forward/dev-tools",
+        "docs": "https://php-fast-forward.github.io/dev-tools/"
     },
     "require": {
         "php": "^8.3",
@@ -43,21 +45,25 @@
         "phpro/grumphp-shim": "^2.19",
         "phpspec/prophecy": "^1.26",
         "phpspec/prophecy-phpunit": "^2.5",
+        "phpunit/php-code-coverage": "^12.5",
         "phpunit/phpunit": "^12.5",
         "psr/clock": "^1.0",
+        "psr/container": "^2.0",
         "psr/log": "^3.0",
         "pyrech/composer-changelogs": "^2.2",
         "rector/rector": "^2.3",
         "saggre/phpdocumentor-markdown": "^1.0",
         "shipmonk/composer-dependency-analyser": "^1.8.4",
+        "symfony/config": "^7.4",
         "symfony/console": "^7.4 || ^8.0",
         "symfony/filesystem": "^7.4 || ^8.0",
         "symfony/finder": "^7.4 || ^8.0",
         "symfony/process": "^7.4 || ^8.0",
         "symfony/var-dumper": "^7.4 || ^8.0",
         "symfony/var-exporter": "^7.4 || ^8.0",
         "symplify/easy-coding-standard": "^13.0",
-        "thecodingmachine/safe": "^3.4"
+        "thecodingmachine/safe": "^3.4",
+        "twig/twig": "^3.0"
     },
     "minimum-stability": "stable",
     "autoload": {

docs/api/commands.rst

@@ -1,20 +1,16 @@
 Command Classes
 ===============
 
-All public CLI commands extend
-``FastForward\DevTools\Console\Command\AbstractCommand``, which provides path
-resolution, configuration fallback, PSR-4 lookup, and child-command dispatch.
+All public CLI commands extend ``Composer\Command\BaseCommand`` and receive
+dependencies through constructor injection. The architecture uses
+``ProcessBuilder`` and ``ProcessQueue`` for fluent process management.
 
 .. list-table::
    :header-rows: 1
 
    * - Class
      - CLI command
      - Responsibility
-   * - ``FastForward\DevTools\Console\Command\AbstractCommand``
-     - n/a
-     - Shared helpers for path resolution, packaged fallback files, PSR-4
-       discovery, and subcommand execution.
    * - ``FastForward\DevTools\Console\Command\StandardsCommand``
      - ``standards``
      - Runs the full quality pipeline.
@@ -49,9 +45,21 @@ resolution, configuration fallback, PSR-4 lookup, and child-command dispatch.
      - ``dev-tools:sync``
      - Synchronizes consumer-facing scripts, automation assets, and packaged
        skills.
-    * - ``FastForward\DevTools\Console\Command\GitIgnoreCommand``
-      - ``gitignore``
-      - Merges and synchronizes .gitignore files.
-    * - ``FastForward\DevTools\Console\Command\CopyLicenseCommand``
-      - ``license``
-      - Generates a LICENSE file from composer.json license information.
+   * - ``FastForward\DevTools\Console\Command\GitIgnoreCommand``
+     - ``gitignore``
+     - Merges and synchronizes .gitignore files.
+   * - ``FastForward\DevTools\Console\Command\GitAttributesCommand``
+     - ``gitattributes``
+     - Manages export-ignore rules in .gitattributes.
+   * - ``FastForward\DevTools\Console\Command\LicenseCommand``
+     - ``license``
+     - Generates a LICENSE file from composer.json license information.
+   * - ``FastForward\DevTools\Console\Command\CopyResourceCommand``
+     - ``copy-resource``
+     - Copies packaged or local resources into the consumer repository.
+   * - ``FastForward\DevTools\Console\Command\GitHooksCommand``
+     - ``git-hooks``
+     - Installs Fast Forward Git hooks.
+   * - ``FastForward\DevTools\Console\Command\UpdateComposerJsonCommand``
+     - ``update-composer-json``
+     - Updates the composer.json file to match the packaged schema.

docs/api/phpunit-support.rst

@@ -19,18 +19,18 @@ The packaged test configuration includes a small integration layer under
    * - ``FastForward\DevTools\PhpUnit\Event\TestSuite\ByPassfinalsStartedSubscriber``
      - Enables ``DG\BypassFinals``
      - Allows tests to work with final constructs.
-    * - ``FastForward\DevTools\PhpUnit\Event\TestSuite\JoliNotifExecutionFinishedSubscriber``
-      - Sends desktop notifications
-      - Summarizes pass, failure, error, runtime, and memory data.
-    * - ``FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoaderInterface``
-      - Loads PHPUnit coverage reports
-      - Contract for loading serialized PHP coverage data.
-    * - ``FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoader``
-      - Loads PHPUnit coverage reports
-      - Implementation that reads ``coverage-php`` output.
-    * - ``FastForward\DevTools\PhpUnit\Coverage\CoverageSummary``
-      - Represents line coverage metrics
-      - Provides executed lines, total executable lines, and percentage calculations.
+   * - ``FastForward\DevTools\PhpUnit\Event\TestSuite\JoliNotifExecutionFinishedSubscriber``
+     - Sends desktop notifications
+     - Summarizes pass, failure, error, runtime, and memory data.
+   * - ``FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoaderInterface``
+     - Loads PHPUnit coverage reports
+     - Contract for loading serialized PHP coverage data.
+   * - ``FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoader``
+     - Loads PHPUnit coverage reports
+     - Implementation that reads ``coverage-php`` output.
+   * - ``FastForward\DevTools\PhpUnit\Coverage\CoverageSummary``
+     - Represents line coverage metrics
+     - Provides executed lines, total executable lines, and percentage calculations.
 
 Coverage Report Loading
 -----------------------

docs/commands/code-style.rst

@@ -0,0 +1,69 @@
+code-style
+==========
+
+Checks and fixes code style issues using EasyCodingStandard and Composer Normalize.
+
+Description
+-----------
+
+The ``code-style`` command orchestrates code style checking and fixing using:
+
+- ``composer update --lock --quiet`` - updates lock file
+- ``composer normalize`` - normalizes composer.json format
+- ``vendor/bin/ecs`` - EasyCodingStandard for PHP code style
+
+Usage
+-----
+
+.. code-block:: bash
+
+   composer code-style
+   composer dev-tools code-style
+
+   composer code-style --fix
+   composer dev-tools:fix code-style
+
+   vendor/bin/dev-tools code-style [options]
+
+Options
+-------
+
+``--fix, -f``
+   Automatically fix code style issues. Without this option, ECS runs in dry-run mode.
+
+Examples
+--------
+
+Check code style (dry-run):
+
+.. code-block:: bash
+
+   composer code-style
+
+Fix code style automatically:
+
+.. code-block:: bash
+
+   composer code-style --fix
+   composer dev-tools:fix code-style
+
+Exit Codes
+---------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Code
+     - Meaning
+   * - 0
+     - Success. All checks passed or fixes applied.
+   * - 1
+     - Failure. Style issues found or fix failed.
+
+Behavior
+---------
+
+- Always runs ``composer update --lock --quiet`` first.
+- Composer Normalize runs in ``--dry-run`` mode unless ``--fix`` is specified.
+- ECS uses local ``ecs.php`` when present, otherwise falls back to packaged default.
+- The command executes processes in sequence via ProcessQueue.

docs/commands/copy-resource.rst

@@ -0,0 +1,73 @@
+copy-resource
+============
+
+Copies packaged or local resources into the consumer repository.
+
+Description
+-----------
+
+The ``copy-resource`` command copies files or directories from a source path to a
+target path. The source is resolved using ``FileLocatorInterface``, while the
+target is resolved to an absolute path using ``FilesystemInterface``.
+
+This command is especially useful for:
+
+- Copying docblock templates, license templates, or other packaged resources
+- Copying resources during project initialization
+- Bulk copying from directory sources
+
+Usage
+-----
+
+.. code-block:: bash
+
+   composer copy-resource --source <path> --target <path>
+   composer dev-tools copy-resource -- --source <path> --target <path> [--overwrite]
+   vendor/bin/dev-tools copy-resource --source <path> --target <path> [--overwrite]
+
+Options
+-------
+
+``--source, -s``
+   Source file or directory to copy. This option is **required**.
+
+``--target, -t``
+   Target file or directory path. This option is **required**.
+
+``--overwrite, -o``
+   Overwrite existing target files. Without this option, existing files
+   are skipped.
+
+Examples
+--------
+
+Copy a docblock template:
+
+.. code-block:: bash
+
+   composer copy-resource --source resources/docblock --target .docheader
+
+Copy a directory of resources:
+
+.. code-block:: bash
+
+   composer copy-resource --source resources/git-hooks --target .git/hooks --overwrite
+
+Copy and overwrite an existing file:
+
+.. code-block:: bash
+
+   composer copy-resource --source .editorconfig --target .editorconfig --overwrite
+
+Exit Codes
+---------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Code
+     - Meaning
+   * - 0
+     - Success. All resources were copied or skipped.
+   * - 1
+     - Failure. Missing required options or copy error.