feat(plugin): widen the RPC surface to LibraryInstaller-based plugins

An installer that extends LibraryInstaller reaches for the Composer object
graph in ways the proxy did not answer: the download manager and the config,
the writable repository methods, a React promise as its own return value, and
`new Package(...)` from its supports() path.

* `Composer::getConfig`/`getDownloadManager` are dispatched, and both classes
  become generated proxy stubs. Their reads and mutators answer from the Rust
  entity; the surfaces needing stubs of their own (ConfigSourceInterface,
  DownloaderInterface) stay explicit errors.
* The download manager's futures are driven to completion and handed back as
  already-settled React promises, since PHP declares a non-nullable
  PromiseInterface there. A promise a plugin returns is drained the same way:
  settled yields its value, rejected re-raises, pending is an explicit error.
* Proxy stubs now carry the real class's constructor and ask the Rust side to
  allocate the entity; reviving a stub for an existing entity binds the handle
  without running it. Classes Rust cannot build name themselves in the error.
* The package proxy covers `Package`'s own setters, `CompletePackage`'s
  metadata, `RootPackage`'s root-only state, and `BasePackage::$id`.

Link values and release dates still have no wire image, so the methods
carrying them remain explicit errors.

1 files changed, 50 insertions, 9 deletions

diff --git a/scripts/plugin-stub-generator/src/Generator.php b/scripts/plugin-stub-generator/src/Generator.php
index ce8f612b..395155dd 100644
--- a/scripts/plugin-stub-generator/src/Generator.php
+++ b/scripts/plugin-stub-generator/src/Generator.php
@@ -23,16 +23,12 @@ final class Generator
         /** @var int */
         protected $__epoch;
 
-        public function __construct(int $rhandle = 0, int $epoch = 0)
+        /**
+         * Binds a stub the registry built for an existing entity. Proxy instantiation bypasses
+         * the constructor, which belongs to plugin code building a new entity instead.
+         */
+        public function __shirabeBind(int $rhandle, int $epoch): void
         {
-            if (func_num_args() < 2) {
-                // Constructing the class from plugin code (a common idiom for e.g. `new BufferIO()`)
-                // is an open question of the plugin design; only proxy instantiation passes a
-                // Rust handle. Fail with a diagnosable message instead of an ArgumentCountError.
-                throw new \RuntimeException(
-                    'Shirabe does not support constructing ' . static::class . ' inside the plugin process yet'
-                );
-            }
             $this->__rhandle = $rhandle;
             $this->__epoch = $epoch;
         }
@@ -235,9 +231,13 @@ final class Generator
         $publicStatics = [];
         $nonPublicStatics = [];
         $ownInstanceMethods = [];
+        $constructor = null;
         foreach ($class->getMethods() as $method) {
             $name = $method->name->toString();
             if ($name === '__construct') {
+                if ($method->isPublic()) {
+                    $constructor = $method;
+                }
                 continue;
             }
             if (str_starts_with($name, '__')) {
@@ -332,6 +332,9 @@ final class Generator
         if ($isRoot) {
             $members[] = self::BOILERPLATE;
         }
+        if ($isRoot || $constructor !== null) {
+            $members[] = $this->renderConstructor($fqcn, $constructor, $file);
+        }
         if ($constants !== []) {
             $members[] = implode("\n", $constants);
         }
@@ -355,6 +358,44 @@ final class Generator
     }
 
     /**
+     * The constructor plugin code reaches when it writes `new SomeProxiedClass(...)`. The real
+     * class's parameter list is reproduced and forwarded to the Rust side, which allocates the
+     * entity and answers with its handle; classes whose entity it cannot build answer with an
+     * explicit error naming the class.
+     */
+    private function renderConstructor(string $fqcn, ?ClassMethod $constructor, SourceFile $file): string
+    {
+        $params = [];
+        $args = [];
+        foreach ($constructor?->params ?? [] as $param) {
+            $paramName = $param->var->name;
+            if ($param->byRef) {
+                $this->errors[] = "$fqcn::__construct: by-ref parameter \$$paramName cannot be proxied yet";
+            }
+            if ($param->variadic) {
+                $this->errors[] = "$fqcn::__construct: variadic parameter \$$paramName cannot be proxied yet";
+            }
+            $rendered = '';
+            if ($param->type !== null) {
+                $rendered = $this->printer->renderType($param->type, $file) . ' ';
+            }
+            $rendered .= '$' . $paramName;
+            if ($param->default !== null) {
+                $rendered .= ' = ' . $this->printer->renderExpr($param->default, $file);
+            }
+            $params[] = $rendered;
+            $args[] = '$' . $paramName;
+        }
+        $call = "\\ShirabeRpcRuntime::callRust(0, '__shirabeConstruct', [static::class, ["
+            . implode(', ', $args) . ']])';
+        return "    public function __construct(" . implode(', ', $params) . ")\n"
+            . "    {\n"
+            . "        [\$this->__rhandle, \$this->__epoch] = $call;\n"
+            . "        \\ShirabeRustObjectRegistry::adopt(\$this->__rhandle, \$this);\n"
+            . "    }";
+    }
+
+    /**
      * Static methods read no instance state; their real implementation is materialized
      * verbatim so they run locally in the worker. Non-public static helpers they call
      * (through `self::`, `static::` or the class name) are materialized along with them.