feat(plugin): serve ProcessExecutor as a proxy stub

Composer reaches this class two ways: the object graph hands one out through
Composer::getLoop()->getProcessExecutor(), and plugins write
`new ProcessExecutor($io)` freely. Both bind to a Rust-side entity, so the
timeout the run shares -- seeded from process-timeout and rewritten while the
run is in flight -- has one value instead of one per world, and the executor
can still be passed to the classes that take one (`new Filesystem($process)`).

Three things the stub generator was missing came with it:

- By-ref parameters. The call carries their positions and the answer carries
  what each holds afterwards; a position the answer omits was never assigned
  to, which is what PHP does with an untouched by-ref parameter.
  ProcessExecutor::execute is the only one on a proxied class.
- Argument arity, reproduced where the real body reads func_num_args().
  execute($cmd) forwards the child's output and execute($cmd, $out) captures
  it, and nothing but the argument count separates the two.
- Static methods that cannot run in the worker. One that reads a static
  property the Rust side owns, or that reaches a guarded class, forwards
  through __shirabeCallStatic instead of being materialized. That also fixes
  Filesystem::isLocalPath and getPlatformPath, whose materialized bodies
  called the guarded Composer\Util\Platform.

The async surface stays an explicit error. executeAsync resolves its promise
with a Symfony Process, whose proc_open() resource and pipes belong to
whichever process called start(), so a Rust-side spawn has none to hand back;
running the real start() in the worker needs a promise representation that
crosses the boundary unresolved.

The fixture project drives the whole synchronous surface from plugin code and
compares the trace against upstream Composer byte for byte.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

3 files changed, 159 insertions, 0 deletions

diff --git a/crates/shirabe/tests/plugin/fixtures/e2e-process-executor/plugin/composer.json b/crates/shirabe/tests/plugin/fixtures/e2e-process-executor/plugin/composer.json
new file mode 100644
index 00000000..5d5609c1
--- /dev/null
+++ b/crates/shirabe/tests/plugin/fixtures/e2e-process-executor/plugin/composer.json
@@ -0,0 +1,17 @@
+{
+    "name": "shirabe-test/process-executor-probe",
+    "version": "1.0.0",
+    "type": "composer-plugin",
+    "description": "Fixture plugin driving a ProcessExecutor it constructs itself.",
+    "autoload": {
+        "psr-4": {
+            "ShirabeTest\\ProcessExecutor\\": "src/"
+        }
+    },
+    "require": {
+        "composer-plugin-api": "^2.0"
+    },
+    "extra": {
+        "class": "ShirabeTest\\ProcessExecutor\\Plugin"
+    }
+}
diff --git a/crates/shirabe/tests/plugin/fixtures/e2e-process-executor/plugin/src/Plugin.php b/crates/shirabe/tests/plugin/fixtures/e2e-process-executor/plugin/src/Plugin.php
new file mode 100644
index 00000000..1f58a11d
--- /dev/null
+++ b/crates/shirabe/tests/plugin/fixtures/e2e-process-executor/plugin/src/Plugin.php
@@ -0,0 +1,117 @@
+<?php
+
+namespace ShirabeTest\ProcessExecutor;
+
+use Composer\Composer;
+use Composer\EventDispatcher\EventSubscriberInterface;
+use Composer\IO\IOInterface;
+use Composer\Plugin\PluginInterface;
+use Composer\Script\Event;
+use Composer\Script\ScriptEvents;
+use Composer\Util\Filesystem;
+use Composer\Util\ProcessExecutor;
+
+/**
+ * Drives a ProcessExecutor the plugin constructs itself and appends what every call reports to
+ * process-executor-trace.txt, so the whole surface can be compared line by line between
+ * implementations: the timeout shared with the rest of the run, both command forms, the three
+ * ways the second argument is treated, the error output, and a Filesystem built on the executor.
+ */
+class Plugin implements PluginInterface, EventSubscriberInterface
+{
+    /** @var IOInterface */
+    private $io;
+
+    public function activate(Composer $composer, IOInterface $io): void
+    {
+        $this->io = $io;
+    }
+
+    public function deactivate(Composer $composer, IOInterface $io): void
+    {
+    }
+
+    public function uninstall(Composer $composer, IOInterface $io): void
+    {
+    }
+
+    public static function getSubscribedEvents()
+    {
+        // Whether an install resolves or replays a lock file decides which of the two fires, so
+        // both are subscribed and the trace records the one that ran.
+        return [
+            ScriptEvents::POST_INSTALL_CMD => 'onPostCommand',
+            ScriptEvents::POST_UPDATE_CMD => 'onPostCommand',
+        ];
+    }
+
+    public function onPostCommand(Event $event): void
+    {
+        $process = new ProcessExecutor($this->io);
+        $lines = ['event=' . $event->getName()];
+
+        // The timeout is process-wide state Composer seeds from the config, so both worlds have
+        // to report the value this project asked for and to observe each other's writes.
+        $original = ProcessExecutor::getTimeout();
+        $lines[] = 'timeout=' . $original;
+        ProcessExecutor::setTimeout(7);
+        $lines[] = 'timeout-after-set=' . ProcessExecutor::getTimeout();
+        ProcessExecutor::setTimeout($original);
+
+        $code = $process->execute('echo captured', $captured);
+        $lines[] = 'capture code=' . $code . ' output=' . json_encode($captured)
+            . ' error=' . json_encode($process->getErrorOutput());
+
+        $code = $process->execute(['echo', 'from', 'a', 'list'], $listed);
+        $lines[] = 'list code=' . $code . ' output=' . json_encode($listed);
+
+        $code = $process->execute('echo out; echo err 1>&2; exit 3', $failed);
+        $lines[] = 'failing code=' . $code . ' output=' . json_encode($failed)
+            . ' error=' . json_encode($process->getErrorOutput());
+
+        // Without a second argument the child's output is forwarded rather than captured, which
+        // is a different branch of the same method; the redirection keeps it out of the terminal
+        // so the trace stays the only thing under comparison.
+        $code = $process->execute('echo forwarded > forwarded.txt');
+        $lines[] = 'forwarded code=' . $code
+            . ' file=' . json_encode(trim((string) @file_get_contents('forwarded.txt')));
+
+        // A callable second argument drives the child's output itself and is never assigned to.
+        $seen = [];
+        $callback = static function (string $type, string $buffer) use (&$seen): void {
+            $seen[] = $type . ':' . trim($buffer);
+        };
+        $code = $process->execute('echo through-a-callback', $callback);
+        $lines[] = 'callback code=' . $code . ' seen=' . json_encode($seen)
+            . ' argument=' . json_encode(\is_callable($callback));
+
+        $code = $process->execute('pwd', $cwdOutput, 'vendor');
+        $lines[] = 'cwd code=' . $code . ' basename=' . json_encode(basename(trim((string) $cwdOutput)));
+
+        $code = $process->execute('echo x; echo y', $multiline);
+        $lines[] = 'splitLines code=' . $code
+            . ' lines=' . json_encode($process->splitLines($multiline))
+            . ' empty=' . json_encode($process->splitLines(null));
+
+        $lines[] = 'escape=' . json_encode(ProcessExecutor::escape("a b'c"));
+        // TODO(php-semantics): a command matching GIT_CMDS_NEED_GIT_DIR has no agreed value to
+        // compare. array_intersect() keeps its first argument's keys and `===` compares an
+        // array's keys too, so Composer answers false for those patterns as well; the shim's
+        // array_intersect drops the keys and Shirabe answers true.
+        $lines[] = 'requiresGitDirEnv status='
+            . json_encode($process->requiresGitDirEnv('git status'));
+
+        $process->setMaxJobs(4);
+        $process->resetMaxJobs();
+        $lines[] = 'maxJobs=ok';
+
+        // The executor is a constructor argument of other Composer utilities, so a plugin-built
+        // one has to be accepted wherever the real class is.
+        $filesystem = new Filesystem($process);
+        $lines[] = 'filesystem normalizePath=' . json_encode($filesystem->normalizePath('/a/b/../c'))
+            . ' isLocalPath=' . json_encode(Filesystem::isLocalPath('/a/b'))
+            . ' getPlatformPath=' . json_encode(Filesystem::getPlatformPath('file:///a/b'));
+
+        file_put_contents('process-executor-trace.txt', implode("\n", $lines) . "\n");
+    }
+}
diff --git a/crates/shirabe/tests/plugin/fixtures/e2e-process-executor/project/composer.json b/crates/shirabe/tests/plugin/fixtures/e2e-process-executor/project/composer.json
new file mode 100644
index 00000000..61ca9a5a
--- /dev/null
+++ b/crates/shirabe/tests/plugin/fixtures/e2e-process-executor/project/composer.json
@@ -0,0 +1,25 @@
+{
+    "name": "shirabe/e2e-process-executor",
+    "description": "E2E fixture project: record what a plugin's own ProcessExecutor reports.",
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../plugin",
+            "options": {
+                "symlink": false
+            }
+        },
+        {
+            "packagist.org": false
+        }
+    ],
+    "require": {
+        "shirabe-test/process-executor-probe": "1.0.0"
+    },
+    "config": {
+        "process-timeout": 42,
+        "allow-plugins": {
+            "shirabe-test/process-executor-probe": true
+        }
+    }
+}