From dd1e70a394abc7356b71db50d28a03fc155e5a7b Mon Sep 17 00:00:00 2001
From: crazywhalecc <jesse2061@outlook.com>
Date: Mon, 6 Jul 2026 15:10:22 +0800
Subject: [PATCH] feat: declare tool dependencies in package configs via tools
 field

- Add 'tools' field to ConfigValidator for build-time tool declarations
- Move jom and strawberry-perl from depends@windows to tools@windows in openssl.yml
- Move go-xcaddy/go-win from depends to tools in frankenphp.yml
- Register config/pkg/tool/ path in spc.registry.yml
- Use addInstallPackage for upx tool in php.php (ToolPackage instead of library dep)
- Include 'tool' type in DumpCapabilitiesCommand and InstallPackageCommand package lists
---
 config/pkg/lib/openssl.yml                            | 4 +++-
 config/pkg/target/frankenphp.yml                      | 6 ++++--
 spc.registry.yml                                      | 1 +
 src/Package/Target/php.php                            | 6 ++++--
 src/StaticPHP/Command/Dev/DumpCapabilitiesCommand.php | 4 ++--
 src/StaticPHP/Command/InstallPackageCommand.php       | 2 +-
 src/StaticPHP/Config/ConfigValidator.php              | 7 +++++++
 7 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/config/pkg/lib/openssl.yml b/config/pkg/lib/openssl.yml
index cbbd0984..42672183 100644
--- a/config/pkg/lib/openssl.yml
+++ b/config/pkg/lib/openssl.yml
@@ -17,7 +17,6 @@ openssl:
     - zlib
   depends@windows:
     - zlib
-    - jom
   headers:
     - openssl
   static-libs@unix:
@@ -26,3 +25,6 @@ openssl:
   static-libs@windows:
     - libssl.lib
     - libcrypto.lib
+  tools@windows:
+    - jom
+    - strawberry-perl
diff --git a/config/pkg/target/frankenphp.yml b/config/pkg/target/frankenphp.yml
index 21d47448..dc3f9fa9 100644
--- a/config/pkg/target/frankenphp.yml
+++ b/config/pkg/target/frankenphp.yml
@@ -10,10 +10,8 @@ frankenphp:
       license: MIT
   depends:
     - php-embed
-    - go-xcaddy
   depends@windows:
     - php-embed
-    - go-win
     - pthreads4w
   suggests@unix:
     - brotli
@@ -24,3 +22,7 @@ frankenphp:
     - frankenphp
   static-bins@windows:
     - frankenphp.exe
+  tools:
+    - go-xcaddy
+  tools@windows:
+    - go-win
diff --git a/spc.registry.yml b/spc.registry.yml
index 98e4bb42..dbaa6ee0 100644
--- a/spc.registry.yml
+++ b/spc.registry.yml
@@ -10,6 +10,7 @@ package:
     - config/pkg/lib/
     - config/pkg/target/
     - config/pkg/ext/
+    - config/pkg/tool/
 artifact:
   config:
     - config/artifact/
diff --git a/src/Package/Target/php.php b/src/Package/Target/php.php
index d1f5a54e..9efd5867 100644
--- a/src/Package/Target/php.php
+++ b/src/Package/Target/php.php
@@ -255,9 +255,11 @@ class php extends TargetPackage
             $installer->addBuildPackage('php-embed');
         }
 
-        // UPX compression: ensure the upx binary package is installed when requested
+        // UPX compression: ensure the upx tool package is installed when requested.
+        // upx is a ToolPackage now, so it's installed directly rather than added as a
+        // library dependency (tool packages bypass the DependencyResolver graph).
         if ($package->getBuildOption('with-upx-pack')) {
-            $additional_packages[] = 'upx';
+            $installer->addInstallPackage('upx');
         }
 
         return [...$extensions_pkg, ...$additional_packages];
diff --git a/src/StaticPHP/Command/Dev/DumpCapabilitiesCommand.php b/src/StaticPHP/Command/Dev/DumpCapabilitiesCommand.php
index e2f3dba9..f4923b33 100644
--- a/src/StaticPHP/Command/Dev/DumpCapabilitiesCommand.php
+++ b/src/StaticPHP/Command/Dev/DumpCapabilitiesCommand.php
@@ -54,8 +54,8 @@ class DumpCapabilitiesCommand extends BaseCommand
     {
         $result = [];
 
-        // library / target / virtual-target
-        foreach (PackageLoader::getPackages(['library', 'target', 'virtual-target']) as $name => $pkg) {
+        // library / target / virtual-target / tool
+        foreach (PackageLoader::getPackages(['library', 'target', 'virtual-target', 'tool']) as $name => $pkg) {
             $installable = [];
             $artifact = $pkg->getArtifact();
             if ($artifact !== null) {
diff --git a/src/StaticPHP/Command/InstallPackageCommand.php b/src/StaticPHP/Command/InstallPackageCommand.php
index 1185e9f9..2dc668c8 100644
--- a/src/StaticPHP/Command/InstallPackageCommand.php
+++ b/src/StaticPHP/Command/InstallPackageCommand.php
@@ -23,7 +23,7 @@ class InstallPackageCommand extends BaseCommand
             'The package to install (name or path)',
             suggestedValues: function (CompletionInput $input) {
                 $packages = [];
-                foreach (PackageLoader::getPackages(['target', 'virtual-target']) as $name => $_) {
+                foreach (PackageLoader::getPackages(['target', 'virtual-target', 'tool']) as $name => $_) {
                     $packages[] = $name;
                 }
                 $val = $input->getCompletionValue();
diff --git a/src/StaticPHP/Config/ConfigValidator.php b/src/StaticPHP/Config/ConfigValidator.php
index 7aac35ac..6bb4e11b 100644
--- a/src/StaticPHP/Config/ConfigValidator.php
+++ b/src/StaticPHP/Config/ConfigValidator.php
@@ -24,6 +24,10 @@ class ConfigValidator
         'lang' => ConfigType::STRING,
         'frameworks' => ConfigType::LIST_ARRAY, // @
 
+        // build-time tool dependency declaration (resolved independently of the library
+        // dependency graph, see PackageInstaller::collectRequiredTools())
+        'tools' => ConfigType::LIST_ARRAY, // @
+
         // php-extension type fields
         'php-extension' => ConfigType::ASSOC_ARRAY,
         'zend-extension' => ConfigType::BOOL,
@@ -63,6 +67,9 @@ class ConfigValidator
         'lang' => false,
         'frameworks' => false, // @
 
+        // build-time tool dependency declaration
+        'tools' => false, // @
+
         // php-extension type fields
         'php-extension' => false,