Refactor install commands using pipelines for granular step control and overrides

[benjam-es]

Motivation

The BuildIosAppCommand (and its Android counterpart) implements the entire build pipeline as a series of private method calls. This makes the process opaque and difficult to extend without forking the package.

Introducing a pipeline-based architecture would transform these into a sequence of discrete, named steps that can be inspected, reordered, skipped, or overridden by consuming applications.

Current Structure

The iOS build follows three broad phases:

1. Bundle — copy files, composer install, remove unnecessary files, create zip
2. Configure — version, build number, app name, Info.plist, entitlements, orientations, provisioning, icons, splash screen, plugins, CocoaPods, SPM
3. Build — archive via xcodebuild

Each phase is a flat list of private method calls with no public surface area for intervention.

Proposed Change

Replace the internal method chains with Laravel pipelines, where each step is a dedicated pipe class:

Pipeline::send($context)
    ->through([
        CopyLaravelApp::class,
        InstallComposerDependencies::class,
        RemoveUnnecessaryFiles::class,
        CleanEnvFile::class,
        CreateAppZip::class,
    ])
    ->thenReturn();

Each pipe receives a shared BuildContext object (carrying paths, options, config) and calls $next($context) to continue, or throws to abort.

What This Unlocks

Hookable steps — Prepend, append, or wrap individual steps without touching the command itself.

Overridable steps — Swap out individual pipes via config or service container bindings. A project using a private Satis instance could replace InstallComposerDependencies entirely.

First-class plugin integration — Plugins currently hook in via pre-build callbacks to mutate output files like Info.plist after the fact. With a pipeline, a plugin could register a pipe directly into the build sequence at precisely the right position, with full BuildContext access and the same abort/continue control as any core step.

Testability — Individual pipes become unit-testable in isolation.

Clarity — The pipeline declaration becomes a readable manifest of what the build actually does.

Path Extraction

The command currently constructs paths inline throughout. A BuildContext value object would centralise this and make both platform commands easier to reason about:

class BuildContext
{
    public string $basePath;
    public string $appPath;
    public string $containerPath;
    public string $xcodeProjectPath;
    public string $logPath;
    // options, config, etc.
}

Android Parity

The same pattern should apply to the Android build command. Both pipelines would share platform-agnostic pipes (e.g. CopyLaravelApp, InstallComposerDependencies) with platform-specific pipes for the native toolchain steps.

Open Questions / Proposals

Pipe registration — A config array of class strings feels like the right approach; it's inspectable and overridable without a service provider. Plugins could append to this array via their own config merging, the same way Laravel packages extend config today:

// config/nativephp.php
'build_pipeline' => [
    CopyLaravelApp::class,
    InstallComposerDependencies::class,
    RemoveUnnecessaryFiles::class,
    CleanEnvFile::class,
    CreateAppZip::class,
],

Progress reporting — Rather than coupling pipes to the command directly, the BuildContext could carry a reporter utility that abstracts output. The command would inject itself (or a wrapper) when constructing the context, and pipes would call $context->reporter->task(...) rather than $this->components->task(...). This keeps pipes decoupled from the console layer while preserving the existing output behaviour.

[simonhamp]

Yes! 👏🏼 I thought about this when building out Desktop and would love this flexibility to come to Mobile

I'm wary of ceding too much control over the whole pipeline to everyone though (e.g via config) as it introduces too many opportunities for mistakes that could lead to silly support requests

But at least if it internally uses a pipeline and we make explicit and sensible ways to override and inject custom steps, then I'm all for it

[shanerbaner82]

This seems like a great idea! My focus almost always performance, developer experience and accuracy/efficiency (not necessarily in that order). Would love to test out a pr on this @benjam-es .