FastForward\DevTools

FastForward DevTools is a Composer plugin that standardizes quality checks, documentation builds, consumer repository bootstrap, and packaged agent skills across Fast Forward libraries.

✨ Features

• Aggregates refactoring, PHPDoc, code style, tests, and reporting under a single Composer-facing command vocabulary
• Adds dependency analysis for missing and unused Composer packages through a single report entrypoint
• Ships shared workflow stubs, .editorconfig, Dependabot configuration, and other onboarding defaults for consumer repositories
• Synchronizes packaged agent skills into consumer .agents/skills directories using safe link-based updates
• Works both as a Composer plugin and as a local binary
• Preserves local overrides through consumer-first configuration resolution

🚀 Installation

composer require --dev fast-forward/dev-tools:dev-main

🛠️ Usage

Once installed, the plugin automatically exposes the aggregated dev-tools command and the individual Composer commands described below.

# Run all standard checks (refactoring, code styling, docs, tests, and reports)
composer dev-tools

# Automatically fix code standards issues where applicable
composer dev-tools:fix

You can also run individual commands for specific development tasks:

# Run PHPUnit tests
composer dev-tools tests

# Analyze missing, unused, and outdated Composer dependencies
composer dependencies
composer dependencies --max-outdated=8
composer dependencies --dev
composer dependencies --upgrade --dev

# Analyze code metrics with PhpMetrics
composer metrics
composer metrics --target=.dev-tools/metrics
composer --working-dir=packages/example metrics

# Check and fix code style using ECS and Composer Normalize
composer code-style

# Refactor code using Rector
composer refactor

# Check and fix PHPDoc comments
composer phpdoc

# Generate HTML API documentation using phpDocumentor
composer docs

# Generate Markdown documentation for the wiki
composer wiki

# Generate documentation frontpage and related reports
composer reports
composer reports --target=.dev-tools --coverage=.dev-tools/coverage

# Synchronize packaged agent skills into .agents/skills
composer skills

# Merges and synchronizes .gitignore files
composer gitignore

# Manages .gitattributes export-ignore rules for leaner package archives
composer gitattributes

# Generates a LICENSE file from composer.json license information
composer license

# Copies packaged or local resources into the consumer repository
composer copy-resource --source resources/docblock --target .docheader

# Installs Fast Forward Git hooks
composer git-hooks

# Updates the composer.json file to match the packaged schema
composer 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
composer dev-tools:sync

The dependencies command ships with both dependency analyzers and rector/jack as direct dependencies of fast-forward/dev-tools, so it works without extra installation in the consumer project.

The metrics command ships with phpmetrics/phpmetrics as a direct dependency of fast-forward/dev-tools, so consumer repositories can generate metrics reports without extra setup.

The skills command keeps .agents/skills aligned with the packaged Fast Forward skill set. It creates missing links, repairs broken links, and preserves existing non-symlink directories. The dev-tools:sync command calls skills automatically after refreshing the rest of the consumer-facing automation assets.

🧰 Command Summary

Command	Purpose
composer dev-tools	Runs the full standards pipeline.
composer tests	Runs PHPUnit with local-or-packaged configuration.
composer dependencies	Previews Jack dependency updates, then reports missing, unused, and overly outdated Composer dependencies.
composer metrics	Runs PhpMetrics for the current project and generates requested report artifacts.
composer docs	Builds the HTML documentation site from PSR-4 code and docs/.
composer skills	Creates or repairs packaged skill links in .agents/skills.
composer gitattributes	Manages export-ignore rules in .gitattributes.
composer dev-tools:sync	Updates scripts, workflow stubs, .editorconfig, .gitignore, .gitattributes, wiki setup, and packaged skills.

🔌 Integration

DevTools integrates with consumer repositories in two ways. The Composer plugin exposes the command set automatically after installation, and the local binary 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 commands or consumer onboarding behavior, update README.md and docs/ together so downstream libraries keep accurate guidance.

📄 License

This package is licensed under the MIT License. See the LICENSE file for more details.

🔗 Links

• Repository
• Packagist
• Documentation
• RFC 2119