feat(manifest): implement BuildManifestDumper for generating build manifest

src/StaticPHP/Package/PackageInstaller.php

@@ -15,6 +15,7 @@ use StaticPHP\Exception\EnvironmentException;
 use StaticPHP\Exception\WrongUsageException;
 use StaticPHP\Registry\PackageLoader;
 use StaticPHP\Runtime\SystemTarget;
+use StaticPHP\Util\BuildManifestDumper;
 use StaticPHP\Util\BuildRootTracker;
 use StaticPHP\Util\DependencyResolver;
 use StaticPHP\Util\DirDiff;
@@ -282,6 +283,11 @@ class PackageInstaller
         // pipeline above (they were merged into $this->packages in resolvePackages()). This only
         // throws if a tool genuinely failed to become available (e.g. no artifact for this platform).
         $this->ensureRequiredTools();
+
+        // Pure install operations must not overwrite the manifest of an existing build.
+        if ($this->build_packages !== []) {
+            new BuildManifestDumper()->dump($this->packages, $this->build_packages, $this->install_packages, $this);
+        }
     }
 
     public function isBuildPackage(Package|string $package): bool

src/StaticPHP/Package/TargetPackage.php

@@ -117,6 +117,19 @@ class TargetPackage extends LibraryPackage
         return null;
     }
 
+    /**
+     * Get target-specific structured data for the build manifest.
+     *
+     * Target implementations may override this method to expose build facts that
+     * cannot be represented by the generic resolved package list.
+     *
+     * @return array<string, mixed>
+     */
+    public function getBuildManifestData(PackageInstaller $installer): array
+    {
+        return [];
+    }
+
     /**
      * Gets all build options for the target package.
      *

src/StaticPHP/Util/BuildManifestDumper.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Util;
+
+use StaticPHP\ConsoleApplication;
+use StaticPHP\Exception\SPCInternalException;
+use StaticPHP\Package\Package;
+use StaticPHP\Package\PackageInstaller;
+use StaticPHP\Package\TargetPackage;
+use StaticPHP\Runtime\SystemTarget;
+
+final class BuildManifestDumper
+{
+    public const int SCHEMA_VERSION = 1;
+
+    /**
+     * @param array<string, Package> $packages        Resolved packages in dependency order
+     * @param array<string, Package> $buildPackages   Packages explicitly scheduled for building
+     * @param array<string, Package> $installPackages Packages explicitly scheduled for installation
+     */
+    public function dump(
+        array $packages,
+        array $buildPackages,
+        array $installPackages,
+        PackageInstaller $installer,
+        string $outputPath = BUILD_ROOT_PATH . '/build-manifest.json',
+    ): void {
+        $targets = [];
+        foreach ($packages as $package) {
+            if (!$package instanceof TargetPackage) {
+                continue;
+            }
+
+            $data = $package->getBuildManifestData($installer);
+            if ($data !== []) {
+                $targets[$package->getName()] = $data;
+            }
+        }
+
+        $manifest = [
+            'schema-version' => self::SCHEMA_VERSION,
+            'spc-version' => ConsoleApplication::VERSION,
+            'target' => [
+                'platform' => SystemTarget::getCurrentPlatformString(),
+                'os' => SystemTarget::getTargetOS(),
+                'architecture' => SystemTarget::getTargetArch(),
+                'libc' => SystemTarget::getLibc(),
+                'libc-version' => SystemTarget::getLibcVersion(),
+                'spc-target' => getenv('SPC_TARGET') ?: null,
+                'toolchain' => getenv('SPC_TOOLCHAIN') ?: null,
+            ],
+            'requested-packages' => [
+                'build' => array_keys($buildPackages),
+                'install' => array_keys($installPackages),
+            ],
+            'packages' => array_values(array_map(
+                static function (Package $package): array {
+                    $artifact = $package->getArtifact();
+                    return [
+                        'name' => $package->getName(),
+                        'type' => $package->getType(),
+                        'artifact' => $artifact?->getName(),
+                    ];
+                },
+                $packages,
+            )),
+            'targets' => $targets,
+        ];
+
+        $json = json_encode(
+            $manifest,
+            JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR,
+        );
+        if (FileSystem::writeFile($outputPath, $json . PHP_EOL) === false) {
+            throw new SPCInternalException("Failed to write build manifest: {$outputPath}");
+        }
+
+        logger()->info('Generated build manifest with ' . count($packages) . " package(s): {$outputPath}");
+    }
+}