[architecture] Reassess isolated tooling distribution after CPX and domain extraction #197

Activity

1. github-project-automation

   added this to PHP Fast Forward Projecton Apr 24, 2026
2. github-project-automation

   moved this to Backlog in PHP Fast Forward Projecton Apr 24, 2026
3. coisa

   added

   enhancementNew feature or requestNew feature or request

   on Apr 24, 2026
4. coisa

   added the

   Feature

   issue type on Apr 24, 2026
5. coisa commented on Apr 24, 2026

   

   coisa

   on Apr 24, 2026

   ContributorAuthor

   More actions

   Discussion Draft: incremental component extraction and dev-tools-shim architecture

   This is a proposed action plan for turning fast-forward/dev-tools into an orchestrator of specialized Fast Forward packages while preserving the current user-facing ergonomics:

   • consumers should still be able to run familiar composer ... commands;
   • this repository should still provide a standalone bin/dev-tools workflow for development;
   • extracted packages should be able to use Fast Forward tooling during their own development without inheriting the full unscopeable dependency graph;
   • a future fast-forward/dev-tools-shim should provide an isolated tool/runtime distribution for smaller Fast Forward packages.

   The important architectural distinction is that the current coupling is not just "we use Composer classes". The current package is doing several jobs at once:

   1. Composer plugin integration.
   2. A standalone console application.
   3. Domain commands and handlers.
   4. Heavy QA/tool orchestration.
   5. Consumer repository synchronization and workflow packaging.

   The extraction should split these jobs gradually, not all at once.

   Current Composer coupling map

   Current direct Composer touchpoints found in the repository:

   Area	Current coupling	Why it exists today	Suggested replacement strategy
   Standalone application	FastForward\DevTools\Console\DevTools extends Composer\Console\Application	Lets bin/dev-tools behave like a Composer-flavored console application even when the package is the root package and cannot consume itself as a Composer plugin.	Replace with Symfony\Component\Console\Application. Keep Composer-specific behavior in a plugin bridge only.
   Public commands	Every public command extends Composer\Command\BaseCommand	Composer capability commands are currently the same classes used by the standalone app.	Split command adapters from handlers. Components expose handlers and optionally Symfony commands. dev-tools exposes thin Composer BaseCommand adapters only for the Composer plugin surface.
   Capability provider	Composer\Plugin\Capability\CommandProvider, Composer\Command\BaseCommand filtering	Registers commands inside a consumer's Composer process.	Keep this inside fast-forward/dev-tools only. It can create Composer adapters around shared handlers instead of returning the same standalone commands.
   Plugin lifecycle	PluginInterface, Capable, EventSubscriberInterface, ScriptEvents, Event, Composer, IOInterface	Needed for installed-consumer plugin integration and post-install/update sync.	Keep in fast-forward/dev-tools. Use composer-plugin-api in require; keep composer/composer in require-dev for tests/static analysis/autocomplete. Runtime classes come from the host Composer process.
   Composer\Factory::getComposerFile()	Used by ComposerJson, FundingCommand, UpdateComposerJsonCommand	Resolves the active composer.json path, including the COMPOSER env behavior.	Introduce ProjectComposerFileResolver with explicit tests for COMPOSER, cwd, relative path, absolute path, and directory edge cases.
   Composer\Json\JsonFile	Used for reading composer.json, installed.json, and funding metadata	Convenient JSON parsing and Composer-specific behavior.	Replace with a small JsonDocumentReader/JsonDocumentWriter using json_decode(..., JSON_THROW_ON_ERROR) plus repository-specific errors. Keep Composer's reader only behind an optional bridge if needed.
   Composer\Json\JsonManipulator	Used by UpdateComposerJsonCommand to mutate composer.json while preserving structure.	This is one of the stronger remaining reasons to keep Composer internals nearby.	Extract a ComposerJsonEditor interface. Start with current JsonManipulator behind an implementation in a Composer bridge. Later evaluate a custom stable writer or a normalizer-driven approach.
   Composer\InstalledVersions	Used in ComposerJson and RectorConfig.	Reads installed package metadata. This does not justify composer/composer by itself because it is generated in normal Composer installs.	Wrap behind InstalledPackageRepositoryInterface. Use Composer\InstalledVersions when available; fallback to vendor/composer/installed.json when needed.
   Composer\Util\Platform	Used by GithubActionOutput for env checks.	Convenience wrapper for environment lookup.	Replace with a small Environment/RuntimeEnvironment abstraction around getenv()/$_SERVER.
   Composer IO	Tests and command behavior rely on Composer IOInterface through BaseCommand.	Current command classes are Composer commands.	Handlers receive PSR logger/output DTOs. Composer adapters map IOInterface to the shared logger/output contract. Symfony adapters map Symfony IO/output to the same contract.
   Composer process execution in plugin event	getLoop()->getProcessExecutor()->execute(...)	Post-install/update sync is delegated through Composer's process executor.	Keep plugin bridge-specific at first. Later prefer invoking the shared sync handler directly, with a process fallback only when isolation is required.

   Target shape

   The target model should be:

   fast-forward/dev-tools
     Composer plugin + repository orchestrator
     requires component packages
     exposes Composer BaseCommand adapters
     ships consumer sync, workflows, local actions, skills/agents/bootstrap
   
   fast-forward/dev-tools-runtime
     small reusable runtime contracts and infrastructure
     Symfony Console app bootstrap for bin/dev-tools-style execution
     no composer/composer dependency
   
   fast-forward/<component>
     focused package such as changelog, testing, docs, sync, code-quality
     owns handlers/domain logic
     MAY expose Symfony commands
     MUST NOT require composer/composer only for command execution
     MAY require-dev fast-forward/dev-tools-shim for its own QA/tooling
   
   fast-forward/dev-tools-shim
     Box + PHP-Scoper isolated PHAR/tool package
     scoped heavy toolchain and selected Fast Forward runtime
     used by smaller packages in require-dev
     does not force its scoped dependencies onto package consumers
   

   A key constraint: avoid a dependency cycle where component packages require-dev the shim while the shim also Composer-requires those same component packages. The safer approach is:

   • components depend on shared contracts/runtime, not on dev-tools;
   • dev-tools requires components and wires them into consumer-facing orchestration;
   • dev-tools-shim is built as an artifact/tool distribution and should avoid normal Composer require edges back into packages that are expected to require-dev it;
   • if the shim must include component behavior, prefer build-time inclusion or plugin-style discovery over Composer dependency cycles.

   Command architecture

   For each command domain, use three layers:

   1. Handler / application service

      • owns behavior;
      • accepts typed options DTOs;
      • returns typed result DTOs or integer exit status;
      • uses PSR logger/output abstractions;
      • has no Symfony InputInterface, no Composer BaseCommand, and no Composer IO.

   2. Symfony command adapter

      • lives in the component package or runtime package when standalone CLI matters;
      • maps Symfony input/options into the handler DTO;
      • powers bin/dev-tools and future component-local binaries.

   3. Composer command adapter

      • lives in fast-forward/dev-tools only;
      • extends Composer\Command\BaseCommand if Composer capability compatibility requires it;
      • delegates to the same handler as the Symfony adapter.

   Example for testing:

   fast-forward/testing
     RunTestsHandler
     TestsOptions
     TestsResult
     TestsSymfonyCommand (optional)
   
   fast-forward/dev-tools
     TestsComposerCommand extends Composer\Command\BaseCommand
     delegates to RunTestsHandler
   
   fast-forward/dev-tools-shim
     can run the Symfony command/handler through isolated tooling
   

   This keeps the package extractable while preserving the current composer tests UX.

   Proposed package boundaries

   1. fast-forward/dev-tools-runtime

   Purpose:

   • shared runtime used by dev-tools, components, and the shim;
   • no Composer plugin dependency;
   • no heavy QA tools.

   Likely contents:

   • process builder / process queue contracts and default Symfony Process implementation;
   • filesystem wrapper and finder factory;
   • path resolvers and managed workspace helpers;
   • console logger/output processors;
   • runtime environment abstraction;
   • lightweight container/service-provider contracts;
   • generic resource diffing.

   Dependencies:

   • php:^8.3
   • psr/log
   • psr/container
   • psr/clock
   • symfony/console
   • symfony/filesystem
   • symfony/finder
   • symfony/process
   • sebastian/diff
   • possibly container-interop/service-provider
   • avoid composer/composer

   2. fast-forward/composer-metadata

   Purpose:

   • own reading and writing Composer project metadata without forcing the full Composer package everywhere.

   Likely contents:

   • ProjectComposerFileResolver
   • ComposerJsonReader
   • ComposerJsonMetadata DTOs (Author, Support, Funding)
   • InstalledPackageRepositoryInterface
   • ComposerJsonEditorInterface
   • optional ComposerJsonManipulatorEditor implementation in a bridge namespace.

   Dependencies:

   • php:^8.3
   • symfony/filesystem or runtime filesystem contracts
   • maybe composer/composer only in a dedicated bridge package or require-dev

   Migration note:

   • Composer\Factory::getComposerFile() and Composer\Json\JsonFile should be replaced early.
   • JsonManipulator should be isolated behind an interface before deciding whether to replace it.

   3. fast-forward/changelog

   Purpose:

   • extracted changelog domain and CLI.

   Likely contents:

   • current src/Changelog/*
   • DependabotChangelogEntryMessageResolver
   • changelog command handlers for entry, check, next-version, promote, show
   • optional Symfony command adapters.

   Dependencies:

   • php:^8.3
   • fast-forward/dev-tools-runtime or smaller contracts package
   • psr/log
   • psr/clock
   • no composer/composer

   dev-tools role:

   • provide Composer BaseCommand adapters for composer changelog:*;
   • keep GitHub Actions release/changelog workflows as repository orchestration.

   4. fast-forward/testing

   Purpose:

   • own PHPUnit execution orchestration and coverage summary logic without exposing PHPUnit as a runtime dependency to every consumer unless intentionally chosen.

   Likely contents:

   • RunTestsHandler
   • TestsOptions
   • CoverageSummary, CoverageSummaryLoader
   • PHPUnit command argument builder
   • optional PHPUnit extension classes should be considered separately because consumers may reference them directly.

   Dependencies:

   • php:^8.3
   • fast-forward/dev-tools-runtime
   • psr/log
   • phpunit/php-code-coverage only if CoverageSummaryLoader directly type-checks CodeCoverage
   • avoid making phpunit/phpunit a hard runtime dependency unless the package intentionally exposes PHPUnit extension APIs.

   Shim strategy:

   • the shim can contain scoped PHPUnit for command execution;
   • packages that extend PHPUnit classes in their own tests still need real PHPUnit in require-dev or a deliberately unscoped public testing extension package.

   Open design question:

   • split user-extendable PHPUnit extension classes into fast-forward/phpunit-extension with real PHPUnit dependencies, while the shim owns isolated command execution.

   5. fast-forward/documentation

   Purpose:

   • own documentation generation handlers.

   Likely contents:

   • docs/wiki/phpdoc handlers;
   • phpDocumentor XML rendering;
   • Twig templates for generated configuration;
   • Markdown/HTML output orchestration.

   Dependencies:

   • php:^8.3
   • fast-forward/dev-tools-runtime
   • twig/twig
   • fast-forward/phpdoc-bootstrap-template
   • phpDocumentor tooling should preferably be invoked through the shim or remain a dev dependency, not leak broadly.

   Shim strategy:

   • scope phpDocumentor and markdown tooling inside the shim when possible;
   • keep templates/resources package-visible when consumers need to inspect them.

   6. fast-forward/code-quality

   Purpose:

   • own code-style, refactor, phpdoc, and maybe standards subflows that primarily orchestrate external QA tools.

   Likely contents:

   • handlers for ECS, Rector, PHP-CS-Fixer/PHPDoc cleanup;
   • config resolvers for packaged/local ecs.php, rector.php, .php-cs-fixer.dist.php;
   • command-result aggregation.

   Dependencies:

   • php:^8.3
   • fast-forward/dev-tools-runtime
   • psr/log
   • heavy tools should move toward shim-scoped execution where possible:
     • rector/rector
     • symplify/easy-coding-standard
     • friendsofphp/php-cs-fixer
     • ergebnis/rector-rules
     • rector/jack

   Important caveat:

   • if consumer configs reference tool classes directly, those classes cannot be only scoped inside a PHAR. Public config APIs and scoped execution need a deliberate boundary.

   7. fast-forward/dependency-health

   Purpose:

   • own dependency analysis and outdated/breakpoint workflows.

   Likely contents:

   • current dependencies behavior;
   • config around shipmonk/composer-dependency-analyser and Jack.

   Dependencies:

   • php:^8.3
   • fast-forward/dev-tools-runtime
   • heavy analysis tools should be shim-managed when possible.

   8. fast-forward/repository-sync

   Purpose:

   • own consumer bootstrap file synchronization that is not specifically GitHub Actions.

   Likely contents:

   • copy-resource
   • gitignore
   • gitattributes
   • git-hooks
   • license
   • funding
   • codeowners
   • packaged directory synchronizer
   • maybe agents/skills until issue [architecture] Map domain-owned skills and replace redundant agent distribution #195 extracts agent payloads.

   Dependencies:

   • php:^8.3
   • fast-forward/dev-tools-runtime
   • fast-forward/composer-metadata
   • symfony/yaml
   • no composer/composer except optional metadata bridge.

   dev-tools role:

   • keep dev-tools:sync as the orchestrator command that composes these handlers.

   9. fast-forward/github-automation

   Purpose:

   • own reusable workflow wrappers and local GitHub Actions as packaged assets, or keep them in dev-tools if we decide workflow sync is core orchestration.

   Likely contents if extracted:

   • resources/github-actions/*
   • .github/actions/* source payloads
   • workflow validation helpers
   • GitHub Pages/wiki preview action support

   Dependencies:

   • mostly packaging/assets;
   • Node scripts and shell scripts where already used;
   • no PHP dependency unless validators are added.

   Recommendation:

   • do not extract first. Workflows are central to dev-tools orchestration and release coordination, so they can remain in dev-tools until smaller domain packages stabilize.

   10. fast-forward/agents

   Purpose:

   • package agent and skill payloads independently, as discussed in [architecture] Map domain-owned skills and replace redundant agent distribution #195.

   Likely contents:

   • .agents/agents
   • maybe .agents/skills later, if skills should share the same distribution strategy.

   Dependencies:

   • likely none or only Composer installer metadata.

   dev-tools role:

   • ensure consumers install/sync the package into the expected directory;
   • stop treating agent payloads as internal DevTools source over time.

   What remains in fast-forward/dev-tools

   fast-forward/dev-tools should remain the repository-facing orchestrator:

   • Composer plugin registration and capability provider;
   • thin Composer BaseCommand adapters;
   • dev-tools:sync orchestration;
   • workflow wrappers and local action packaging;
   • repository bootstrap defaults;
   • release automation wiring;
   • docs that describe the unified Fast Forward workflow;
   • dependency on extracted Fast Forward packages.

   Target dependencies:

   • php:^8.3
   • composer-plugin-api:^2.0
   • symfony/console
   • fast-forward/dev-tools-runtime
   • extracted Fast Forward packages, such as fast-forward/changelog, fast-forward/testing, etc.
   • composer/composer should move toward require-dev only, used for tests/static analysis/autocomplete around the plugin bridge.

   What bin/dev-tools should become

   The standalone binary should stop depending on Composer\Console\Application.

   Target:

   • bin/dev-tools boots a plain Symfony\Component\Console\Application;
   • it registers Symfony command adapters around the same handlers used by Composer command adapters;
   • it does not need the package to consume itself as a Composer plugin;
   • it becomes the development entrypoint for this repository and for shim internals.

   This keeps the current local DX while removing the main reason the whole console layer needs composer/composer.

   What dev-tools-shim should do

   fast-forward/dev-tools-shim should be treated as an isolated development tool distribution, not as the main repository orchestrator.

   Responsibilities:

   • bundle a stable executable with Box;
   • scope implementation dependencies with PHP-Scoper;
   • expose shared Fast Forward tool commands to component repositories;
   • provide a stable development-time entrypoint for smaller repos;
   • avoid leaking tool dependency constraints to consumers.

   Non-responsibilities:

   • do not own consumer sync policy;
   • do not own repository workflow wrappers;
   • do not replace the Composer plugin;
   • do not become the normal runtime dependency of every component unless absolutely necessary.

   Dependency scoping strategy

   Use three buckets:

   1. Public APIs that consumers/components may extend or reference

      • do not scope these blindly;
      • examples: PHPUnit extension APIs, Symfony command interfaces if packages expose commands, Fast Forward contracts.

   2. Implementation-only tool dependencies

      • safe candidates for scoping;
      • examples: internal tool runners, phpDocumentor execution dependencies, PHP-CS-Fixer internals, Rector/ECS internals when configs do not expose their classes.

   3. Bridge dependencies

      • keep isolated in bridge packages or adapters;
      • examples: Composer JsonManipulator, Composer plugin command adapters, host Composer runtime classes.

   A practical rule: if package users need to import a class in their own PHP code or config, that class should not only exist inside a scoped PHAR.

   Migration phases

   Phase 0: Architecture guardrails

   • Document handler/adapter boundaries.
   • Add tests proving command handlers can run without Composer BaseCommand.
   • Add dependency-analysis rules that prevent new Composer\* imports outside approved bridge namespaces.
   • Keep the composer-plugin-consumer fixture as a regression surface.

   Phase 1: Replace standalone Composer application

   • Change DevTools from Composer\Console\Application to Symfony Application.
   • Keep Composer capability provider working through dedicated Composer adapters.
   • Verify:
     • php bin/dev-tools list
     • fixture composer list
     • fixture composer agents --help
     • core commands via both entrypoints.

   Phase 2: Introduce handler DTOs for one low-risk domain

   Recommended first domain: changelog.

   Why:

   • it already has a clear domain model;
   • it has fewer external process dependencies than testing/docs/code-style;
   • it is a likely first extracted package.

   Deliverables:

   • ChangelogEntryHandler, ChangelogCheckHandler, etc.;
   • Symfony command adapter;
   • Composer command adapter;
   • unchanged visible CLI behavior.

   Phase 3: Extract fast-forward/changelog

   • Move changelog domain and handlers to the new package.
   • Keep Composer adapters in dev-tools.
   • Have dev-tools require fast-forward/changelog.
   • Use dev-tools-shim in the changelog repo's require-dev once available.

   Phase 4: Extract runtime/core infrastructure

   • Move process/filesystem/path/logger/runtime abstractions to fast-forward/dev-tools-runtime.
   • Keep DevTools-specific service wiring in dev-tools.
   • Ensure components depend on the runtime package rather than on the monolithic dev-tools package.

   Phase 5: Extract repository sync

   • Move gitignore/gitattributes/license/funding/codeowners/git-hooks/copy-resource handlers.
   • Keep dev-tools:sync in dev-tools as an orchestrator that calls those handlers.
   • Align with [architecture] Map domain-owned skills and replace redundant agent distribution #195 for fast-forward/agents payload extraction.

   Phase 6: Build the first dev-tools-shim

   • Create Box config.
   • Add PHP-Scoper config.
   • Start with a minimal command set, likely changelog + runtime utilities.
   • Publish the shim as a versioned artifact/package.
   • Add a consumer/component fixture that installs only the shim as require-dev and runs a command.

   Phase 7: Move heavy tool orchestration behind shim

   • Gradually move testing/docs/code-style/refactor/dependency-health execution to shim-backed handlers.
   • Keep public extension/config classes unscoped where users need to reference them.
   • Add explicit tests for consumer projects that do not install the real heavy tools directly.

   Phase 8: Release propagation

   • Add release workflow coordination so dev-tools releases trigger or require a matching dev-tools-shim release.
   • Decide whether shim releases are same-repo artifacts or separate-repo releases.
   • Include smoke tests that install:
     • fast-forward/dev-tools in a consumer fixture;
     • one extracted package with fast-forward/dev-tools-shim in require-dev;
     • a project using both without dependency conflicts.

   Suggested first follow-up issues

   1. Replace Composer\Console\Application with Symfony Console for bin/dev-tools while keeping Composer plugin command discovery intact.
   2. Introduce handler/DTO boundaries for changelog commands without changing behavior.
   3. Add dependency-analysis rules that allow Composer imports only in bridge namespaces.
   4. Extract project Composer metadata access behind ProjectComposerFileResolver, JsonDocumentReader, and ComposerJsonEditorInterface.
   5. Prototype fast-forward/changelog as the first extracted component package.
   6. Prototype fast-forward/dev-tools-shim with Box + PHP-Scoper using the smallest useful command set.
   7. Define public-vs-scoped dependency policy for PHPUnit, Rector, ECS, phpDocumentor, PHP-CS-Fixer, and config classes.

   Success criteria for the architecture

   • dev-tools can still provide the unified Composer plugin UX.
   • bin/dev-tools can run without extending Composer's console application.
   • command behavior lives in handlers that can be reused by Symfony commands, Composer adapters, and shim execution.
   • smaller Fast Forward packages can be developed with dev-tools-shim in require-dev without depending on the monolithic dev-tools package.
   • consumers are not forced to accept direct version constraints for the entire QA/tooling stack unless they intentionally use the unscoped public APIs.
   • extracted components remain specialized and independently testable.
6. coisa

   changed the title [-][architecture] Design a Box + PHP-Scoper dev-tools-shim for extracted Fast Forward components[/-] [+][architecture] Reassess isolated tooling distribution after CPX and domain extraction[/+] on Oct 21, 2026