feat(tool): implement tool package support with validation and configuration

src/StaticPHP/Package/Package.php

@@ -120,6 +120,20 @@ abstract class Package
         return false;
     }
 
+    /**
+     * Get the target directory where this package's artifacts should be placed.
+     *
+     * Libraries install to BUILD_ROOT_PATH (static-libs, headers, pkg-configs).
+     * Tools install to PKG_ROOT_PATH (executables).
+     * Extensions install to php-src/ext/ (shared objects).
+     *
+     * Override in subclasses to change the default.
+     */
+    public function getInstallTarget(): string
+    {
+        return BUILD_ROOT_PATH;
+    }
+
     /**
      * Add a stage to the package.
      */

src/StaticPHP/Package/PackageInstaller.php

@@ -11,6 +11,7 @@ use StaticPHP\Artifact\ArtifactExtractor;
 use StaticPHP\Artifact\DownloaderOptions;
 use StaticPHP\Config\PackageConfig;
 use StaticPHP\DI\ApplicationContext;
+use StaticPHP\Exception\EnvironmentException;
 use StaticPHP\Exception\WrongUsageException;
 use StaticPHP\Registry\PackageLoader;
 use StaticPHP\Runtime\SystemTarget;
@@ -167,6 +168,9 @@ class PackageInstaller
         // Early validation: check if packages can be built or installed before downloading
         $this->validatePackagesBeforeBuild();
 
+        // Check that all required tools are installed before proceeding
+        $this->ensureRequiredTools();
+
         // check download
         if ($this->download) {
             $downloaderOptions = DownloaderOptions::extractFromConsoleOptions($this->options, 'dl');
@@ -574,6 +578,66 @@ class PackageInstaller
         return null;
     }
 
+    /**
+     * Collect all tool packages required by the currently resolved packages.
+     *
+     * Reads the 'tools' field from each resolved package's YAML config.
+     * The field supports platform suffixes (tools@windows, tools@linux, etc.)
+     * resolved automatically by PackageConfig::get().
+     *
+     * Tools are NOT part of the library dependency graph — they are
+     * build-time prerequisites that must be installed before any library
+     * build begins.
+     *
+     * @return string[] Unique tool package names required for this build
+     */
+    public function collectRequiredTools(): array
+    {
+        $tools = [];
+        foreach ($this->packages as $package) {
+            $deps = PackageConfig::get($package->getName(), 'tools', []);
+            foreach ((array) $deps as $tool_name) {
+                $tools[$tool_name] = true;
+            }
+        }
+        return array_keys($tools);
+    }
+
+    /**
+     * Check that all required tools are installed.
+     *
+     * Iterates through tools collected by collectRequiredTools(),
+     * resolves each to a ToolPackage instance, and checks isInstalled().
+     *
+     * @return array{missing: array<string>, installed: array<string>}
+     */
+    public function checkRequiredTools(): array
+    {
+        $missing = [];
+        $installed = [];
+        foreach ($this->collectRequiredTools() as $tool_name) {
+            try {
+                $tool = PackageLoader::getPackage($tool_name);
+            } catch (WrongUsageException) {
+                $missing[] = $tool_name;
+                logger()->warning("Required tool '{$tool_name}' is not registered as a package.");
+                continue;
+            }
+
+            if (!$tool instanceof ToolPackage) {
+                logger()->warning("Package '{$tool_name}' is declared as a tool dependency but is not a ToolPackage (type: {$tool->getType()}).");
+                continue;
+            }
+
+            if ($tool->isInstalled()) {
+                $installed[] = $tool_name;
+            } else {
+                $missing[] = $tool_name;
+            }
+        }
+        return ['missing' => $missing, 'installed' => $installed];
+    }
+
     /**
      * @param Package[] $packages
      */
@@ -636,6 +700,27 @@ class PackageInstaller
         }
     }
 
+    /**
+     * Ensure all required tools are installed, throwing if any are missing.
+     *
+     * Called early in the build pipeline (before download/extract).
+     * When tools are missing, lists them with install hints.
+     */
+    private function ensureRequiredTools(): void
+    {
+        $status = $this->checkRequiredTools();
+        if (empty($status['missing'])) {
+            if (!empty($status['installed'])) {
+                logger()->info('Required tools: ' . implode(', ', $status['installed']) . ' — all installed.');
+            }
+            return;
+        }
+
+        $msg = 'Missing required build tools: ' . implode(', ', $status['missing']) . "\n";
+        $msg .= "Run 'bin/spc doctor' to check your environment, or install the missing tools manually.";
+        throw new EnvironmentException($msg);
+    }
+
     private function injectPackageEnvs(Package $package): void
     {
         $name = $package->getName();

src/StaticPHP/Package/ToolPackage.php

@@ -0,0 +1,151 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Package;
+
+use StaticPHP\Config\PackageConfig;
+use StaticPHP\Util\FileSystem;
+use StaticPHP\Util\GlobalPathTrait;
+
+/**
+ * Represents a build-time tool package.
+ *
+ * Tool packages are NOT link-time dependencies. They provide executables
+ * that are needed during the build process (compilers, code generators,
+ * assemblers, etc.) and are installed into PKG_ROOT_PATH.
+ *
+ * Tool packages do NOT produce static-libs, headers, or pkg-config files.
+ * They are resolved and installed independently from the library dependency graph.
+ *
+ * YAML config schema (config/pkg/tool/<name>.yml):
+ *
+ *   nasm:
+ *     type: tool
+ *     tool:
+ *       provides: [nasm.exe, ndisasm.exe]       # executables this tool installs
+ *       binary-subdir: ''                        # subdirectory under install root (default: '')
+ *       min-version: '2.16'                      # minimum required version (optional)
+ *     artifact:
+ *       binary:
+ *         windows-x86_64:
+ *           type: url
+ *           url: 'https://...'
+ *           extract:
+ *             nasm.exe: '{php_sdk_path}/bin/nasm.exe'
+ */
+class ToolPackage extends Package
+{
+    use GlobalPathTrait;
+
+    /**
+     * Get the install root directory for this tool.
+     *
+     * Defaults to PKG_ROOT_PATH. Override via 'tool.install-root' in YAML
+     * or via the TOOL_INSTALL_ROOT_{NAME} environment variable.
+     */
+    public function getInstallRoot(): string
+    {
+        $env_var = 'TOOL_INSTALL_ROOT_' . strtoupper(str_replace('-', '_', $this->name));
+        if ($root = getenv($env_var)) {
+            return $root;
+        }
+        $config_root = $this->getToolConfig()['install-root'] ?? null;
+        if ($config_root !== null) {
+            return FileSystem::replacePathVariable((string) $config_root);
+        }
+        return PKG_ROOT_PATH;
+    }
+
+    /**
+     * Get the directory where this tool's binaries reside.
+     *
+     * This is {install-root}/{binary-subdir}. If binary-subdir is not
+     * configured, returns the install root directly.
+     */
+    public function getBinaryDir(): string
+    {
+        $subdir = $this->getToolConfig()['binary-subdir'] ?? '';
+        if ($subdir === '') {
+            return $this->getInstallRoot();
+        }
+        return $this->getInstallRoot() . DIRECTORY_SEPARATOR . $subdir;
+    }
+
+    /**
+     * Get the list of executables this tool provides.
+     *
+     * Reads from YAML 'tool.provides' field. Each entry is a bare filename
+     * (e.g. 'nasm.exe'), resolved relative to getBinaryDir().
+     *
+     * @return string[] Bare executable names (not full paths)
+     */
+    public function getProvides(): array
+    {
+        return $this->getToolConfig()['provides'] ?? [];
+    }
+
+    /**
+     * Get the full path to a specific binary provided by this tool.
+     *
+     * @param  string $name Bare executable name (must be listed in tool.provides).
+     *                      If empty, defaults to the first entry in provides.
+     * @return string Full absolute path to the binary
+     */
+    public function getBinary(string $name = ''): string
+    {
+        $provides = $this->getProvides();
+        if ($name === '') {
+            $name = $provides[0] ?? throw new \RuntimeException("Tool '{$this->name}' has no 'tool.provides' configured.");
+        }
+        if (!in_array($name, $provides, true)) {
+            throw new \RuntimeException("Binary '{$name}' is not listed in tool.provides for '{$this->name}'. Available: " . implode(', ', $provides));
+        }
+        return $this->getBinaryDir() . DIRECTORY_SEPARATOR . $name;
+    }
+
+    /**
+     * Check whether this tool is installed (all provided binaries exist on disk).
+     */
+    public function isInstalled(): bool
+    {
+        return array_all($this->getProvides(), fn ($binary) => file_exists($this->getBinary($binary)));
+    }
+
+    /**
+     * Get the minimum required version for this tool, if specified.
+     *
+     * Returns null if no version constraint is configured.
+     */
+    public function getMinVersion(): ?string
+    {
+        $version = $this->getToolConfig()['min-version'] ?? null;
+        return $version !== null ? (string) $version : null;
+    }
+
+    /**
+     * Tools install to PKG_ROOT_PATH (or the configured install-root),
+     * not BUILD_ROOT_PATH.
+     */
+    public function getInstallTarget(): string
+    {
+        return $this->getBinaryDir();
+    }
+
+    /**
+     * Get the 'tool' sub-config for this package.
+     *
+     * Returns the nested array under the 'tool' key in the package YAML,
+     * or an empty array if not configured.
+     *
+     * @return array<string, mixed>
+     */
+    private function getToolConfig(): array
+    {
+        $config = PackageConfig::get($this->name);
+        if (!is_array($config) || !isset($config['tool']) || !is_array($config['tool'])) {
+            return [];
+        }
+        return $config['tool'];
+    }
+}