feat(software): read software definitions from Composer packages

README-es.md

@@ -61,6 +61,7 @@ Con DLoad puedes:
     - [Definir Software](#definir-software)
     - [Elementos de Software](#elementos-de-software)
     - [Servidores Autoalojados](#servidores-autoalojados)
+    - [Software desde Paquetes Composer](#software-desde-paquetes-composer)
 - [Casos de Uso](#casos-de-uso)
     - [Configurar Entorno de Desarrollo](#configurar-entorno-de-desarrollo)
     - [Configurar Nuevo Proyecto](#configurar-nuevo-proyecto)
@@ -597,13 +598,17 @@ El binario de RoadRunner construido incluirá solo los plugins especificados en
 
 #### Elementos Binary
 
-- **name**: Nombre del binario para referencia
+- **name**: Nombre del binario para referencia; un nombre de archivo, no una ruta
 - **pattern**: Patrón regex para hacer match con el binario en los assets
+- **version-command**: Argumentos con los que el binario imprime su versión, como `--version`; sin él la versión no se comprueba.
+  Se pasan al binario tal cual, sin shell: las comillas y las tuberías no se interpretan.
+  En las entradas de paquetes Composer es una sola opción como `--version`, o `version`
 - Maneja automáticamente el filtrado por SO/arquitectura
 
 #### Elementos File
 
 - **pattern**: Patrón regex para hacer match con archivos
+- **rename**: Nuevo nombre opcional del archivo encontrado; un nombre de archivo, no una ruta. Se añade la extensión del archivo encontrado salvo que el nuevo nombre ya termine con ella
 - **extract-path**: Directorio de extracción opcional
 - Funciona en cualquier sistema (sin filtrado por SO/arquitectura)
 
@@ -657,6 +662,59 @@ el token de un servidor solo va a ese esquema, host y puerto exactos, y se desca
 Se permite `http` sin cifrar, p. ej. para una API falsa local en tests (`uri="http://127.0.0.1:8080/owner/repo"`), pero el token
 solo se envía por él a `localhost`, `127.0.0.0/8` y `[::1]`.
 
+### Software desde Paquetes Composer
+
+Un framework o un CMS puede incluir las definiciones de los binarios que necesita, para que los proyectos que lo usan
+no tengan que copiarlas en su `dload.xml`. El paquete apunta a un archivo XML propio desde su `composer.json`:
+
+```json
+{
+    "extra": {
+        "dload": {
+            "registry": "resources/dload.xml"
+        }
+    }
+}
+```
+
+El archivo tiene el formato de `dload.xml`, así que el IDE lo autocompleta y lo valida; solo se lee su sección `<registry>`.
+Puede ser un archivo dedicado o el propio `dload.xml` del paquete. Mantenlo en el dist del paquete: no le apliques `export-ignore`.
+
+```xml
+<dload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/php-internal/dload/refs/heads/1.x/dload.xsd">
+    <registry>
+        <software name="GitHub CLI" alias="gh">
+            <repository type="github" uri="cli/cli" asset-pattern="/^gh_.*/" />
+            <binary name="gh" pattern="/^gh(\.exe)?$/" />
+        </software>
+    </registry>
+</dload>
+```
+
+DLoad busca `composer.json` junto al `dload.xml` cargado (en el directorio de trabajo si no hay uno) y lee
+los paquetes instalados de `vendor/composer/installed.json` (se respetan `COMPOSER_VENDOR_DIR` y `config.vendor-dir`, solo Composer 2).
+Funciona igual con el paquete de Composer, el PHAR y el binario.
+
+- **Quién puede declarar**: el paquete raíz y sus dependencias directas (`require`, `require-dev`).
+  Una dependencia transitiva no puede añadir software.
+- **Dónde puede estar el archivo**: solo dentro del paquete. Una ruta que sale de él, mediante `..`,
+  una ruta absoluta o un enlace simbólico, se rechaza. Los archivos remotos no están soportados.
+- **Prioridad**: `dload.xml` > el registro oficial > los paquetes. Un paquete nunca reemplaza una entrada de los otros dos;
+  cuando el registro oficial oculta una entrada de un paquete que se está descargando y apunta a otros repositorios, DLoad avisa de ello.
+- **Elección explícita**: `<package>#<id>` selecciona la entrada de un paquete, aunque otra la oculte (`__root__#<id>` para un paquete raíz sin `name`):
+  `dload get acme/framework#gh:^2.0` o `<download software="acme/framework#gh" />`.
+- **Varios paquetes, un mismo id**: si los paquetes apuntan a los mismos repositorios, coinciden y no hay nada que avisar.
+  Si no, gana el paquete raíz, luego los paquetes en el orden de `require` y `require-dev`,
+  y al descargar ese id se muestran todos los `<package>#<id>` entre los que elegir.
+- **Las declaraciones erróneas** se notifican como advertencias y se omiten; nunca detienen DLoad. Esto incluye un archivo inexistente,
+  un XML inválido, un atributo obligatorio vacío, una ruta donde se espera un nombre de archivo, una regex inválida,
+  un `version-command` que no sea una sola opción como `--version`, o `version`, y un id con `#`, `:` o espacios alrededor.
+- **Desactivación**: `<registry from-packages="false">` descarta el software de los paquetes y mantiene el registro oficial;
+  `<registry overwrite="true">` descarta ambos.
+
+`dload software` muestra de dónde viene cada entrada: `official`, `dload.xml` o el nombre del paquete. Una entrada que oculta otras las lista en `Shadows:`, las de paquetes como `<package>#<id>`; `dload show <id>` muestra el origen como `Source:`.
+
 ## Casos de Uso
 
 ### Configurar Entorno de Desarrollo

README-ru.md

@@ -62,6 +62,7 @@ DLoad решает распространённую проблему в PHP-пр
     - [Определение ПО](#определение-по)
     - [Элементы ПО](#элементы-по)
     - [Собственные серверы](#собственные-серверы)
+    - [ПО из Composer-пакетов](#по-из-composer-пакетов)
 - [Сценарии использования](#сценарии-использования)
     - [Настройка среды разработки](#настройка-среды-разработки)
     - [Настройка нового проекта](#настройка-нового-проекта)
@@ -599,13 +600,17 @@ DLoad автоматически управляет процессом сбор
 
 #### Элементы Binary
 
-- **name**: Имя бинарника для ссылки
+- **name**: Имя бинарника для ссылки; имя файла, а не путь
 - **pattern**: Regex-паттерн для соответствия бинарнику в ресурсах
+- **version-command**: Аргументы, с которыми бинарник выводит свою версию, например `--version`; без него версия не проверяется.
+  Они передаются бинарнику как есть, без shell: кавычки и пайпы не интерпретируются.
+  В записях Composer-пакетов это одна опция вроде `--version` или слово `version`
 - Автоматически обрабатывает фильтрацию по ОС/архитектуре
 
 #### Элементы File
 
 - **pattern**: Regex-паттерн для соответствия файлам
+- **rename**: Необязательное новое имя найденного файла — имя файла, а не путь. Расширение найденного файла дописывается, если новое имя на него ещё не оканчивается
 - **extract-path**: Опциональная папка извлечения
 - Работает на любой системе (без фильтрации по ОС/архитектуре)
 
@@ -659,6 +664,59 @@ DLOAD_TOKEN_GHE_EXAMPLE_COM=your_token_here ./vendor/bin/dload get
 Обычный `http` допускается, например, для локального фейкового API в тестах (`uri="http://127.0.0.1:8080/owner/repo"`), но токен
 передаётся по нему только на `localhost`, `127.0.0.0/8` и `[::1]`.
 
+### ПО из Composer-пакетов
+
+Фреймворк или CMS может поставлять описания нужных ему бинарников, чтобы использующим его проектам не приходилось
+копировать их в свой `dload.xml`. Пакет указывает на XML-файл внутри себя в своём `composer.json`:
+
+```json
+{
+    "extra": {
+        "dload": {
+            "registry": "resources/dload.xml"
+        }
+    }
+}
+```
+
+Файл имеет формат `dload.xml`, поэтому IDE его дополняет и проверяет; читается только секция `<registry>`.
+Это может быть отдельный файл или собственный `dload.xml` пакета. Файл должен попасть в дистрибутив пакета: не исключайте его через `export-ignore`.
+
+```xml
+<dload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/php-internal/dload/refs/heads/1.x/dload.xsd">
+    <registry>
+        <software name="GitHub CLI" alias="gh">
+            <repository type="github" uri="cli/cli" asset-pattern="/^gh_.*/" />
+            <binary name="gh" pattern="/^gh(\.exe)?$/" />
+        </software>
+    </registry>
+</dload>
+```
+
+DLoad ищет `composer.json` рядом с загруженным `dload.xml` (а если его нет — в рабочем каталоге) и читает
+установленные пакеты из `vendor/composer/installed.json` (`COMPOSER_VENDOR_DIR` и `config.vendor-dir` учитываются, поддерживается только Composer 2).
+Это работает одинаково для Composer-пакета, PHAR и бинарника.
+
+- **Кто может объявлять ПО**: корневой пакет и его прямые зависимости (`require`, `require-dev`).
+  Транзитивная зависимость добавить ПО не может.
+- **Где может лежать файл**: только внутри пакета. Путь, ведущий за его пределы через `..`,
+  абсолютный путь или символическую ссылку, отклоняется. Удалённые файлы не поддерживаются.
+- **Приоритет**: `dload.xml` > официальный реестр > пакеты. Пакет никогда не заменяет запись из двух других источников;
+  если официальный реестр перекрывает загружаемую запись пакета и указывает на другие репозитории, DLoad предупреждает об этом.
+- **Явный выбор**: `<package>#<id>` выбирает запись пакета, что бы её ни перекрывало (`__root__#<id>` — для корневого пакета без `name`):
+  `dload get acme/framework#gh:^2.0` или `<download software="acme/framework#gh" />`.
+- **Несколько пакетов, один id**: если пакеты указывают на одни и те же репозитории, они согласованы и сообщать не о чем.
+  Иначе побеждает корневой пакет, затем пакеты в порядке `require` и `require-dev`,
+  а при загрузке по этому id выводятся все варианты `<package>#<id>`, из которых можно выбрать.
+- **Ошибочные объявления** выводятся как предупреждения и пропускаются; они никогда не останавливают DLoad. Это отсутствующий файл,
+  невалидный XML, пустой обязательный атрибут, путь там, где ожидается имя файла, невалидное регулярное выражение,
+  `version-command`, который не является одной опцией вроде `--version` или словом `version`, и id с `#`, `:` или пробелами по краям.
+- **Отключение**: `<registry from-packages="false">` отбрасывает ПО из пакетов и сохраняет официальный реестр;
+  `<registry overwrite="true">` отбрасывает и то и другое.
+
+`dload software` показывает, откуда взята каждая запись: `official`, `dload.xml` или имя пакета. Если запись перекрывает другие, они перечислены в строке `Shadows:`, записи пакетов — в виде `<package>#<id>`; `dload show <id>` выводит источник в строке `Source:`.
+
 ## Сценарии использования
 
 ### Настройка среды разработки

README-zh.md

@@ -61,6 +61,7 @@ DLoad 解决了 PHP 项目中的一个实际问题：如何在分发 PHP 代码
     - [定义软件](#定义软件)
     - [软件要素](#软件要素)
     - [自托管服务器](#自托管服务器)
+    - [来自 Composer 包的软件](#来自-composer-包的软件)
 - [使用场景](#使用场景)
     - [开发环境配置](#开发环境配置)
     - [新项目创建](#新项目创建)
@@ -590,13 +591,17 @@ DLoad 会自动处理构建过程：
 
 #### 二进制要素
 
-- **name**：用于引用的二进制文件名
+- **name**：用于引用的二进制文件名；必须是文件名，而不是路径
 - **pattern**：匹配资源中二进制文件的正则表达式模式
+- **version-command**：让二进制文件输出版本的参数，例如 `--version`；未设置时不检查版本。
+  参数会原样传给二进制文件，不经过 shell：引号和管道不会被解释。
+  在 Composer 包的条目中只能是单个选项（如 `--version`）或 `version`
 - 自动处理操作系统/架构过滤
 
 #### 文件要素
 
 - **pattern**：匹配文件的正则表达式模式
+- **rename**：可选，匹配文件的新名称；必须是文件名，而不是路径。除非新名称已以该扩展名结尾，否则会追加匹配文件的扩展名
 - **extract-path**：可选的解压目录
 - 在任何系统上都能工作（无操作系统/架构过滤）
 
@@ -646,6 +651,56 @@ DLOAD_TOKEN_GHE_EXAMPLE_COM=your_token_here ./vendor/bin/dload get
 允许使用普通的 `http`，例如用于测试中的本地模拟 API（`uri="http://127.0.0.1:8080/owner/repo"`），但令牌
 只会通过它发送到 `localhost`、`127.0.0.0/8` 和 `[::1]`。
 
+### 来自 Composer 包的软件
+
+框架或 CMS 可以随包附带它所需二进制文件的定义，这样使用它的项目就不必把这些定义复制到自己的 `dload.xml` 中。
+包在其 `composer.json` 中指向包内的一个 XML 文件：
+
+```json
+{
+    "extra": {
+        "dload": {
+            "registry": "resources/dload.xml"
+        }
+    }
+}
+```
+
+该文件采用 `dload.xml` 格式，因此 IDE 可以为其提供补全和校验；只会读取其中的 `<registry>` 部分。
+它可以是专用文件，也可以是包自身的 `dload.xml`。请将其保留在包的 dist 中：不要对它使用 `export-ignore`。
+
+```xml
+<dload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/php-internal/dload/refs/heads/1.x/dload.xsd">
+    <registry>
+        <software name="GitHub CLI" alias="gh">
+            <repository type="github" uri="cli/cli" asset-pattern="/^gh_.*/" />
+            <binary name="gh" pattern="/^gh(\.exe)?$/" />
+        </software>
+    </registry>
+</dload>
+```
+
+DLoad 在已加载的 `dload.xml` 旁边查找 `composer.json`（没有 `dload.xml` 时在工作目录中查找），并从
+`vendor/composer/installed.json` 读取已安装的包（会遵循 `COMPOSER_VENDOR_DIR` 和 `config.vendor-dir`，仅支持 Composer 2）。
+无论是 Composer 包、PHAR 还是二进制文件，其行为都相同。
+
+- **谁可以声明**：根包及其直接依赖（`require`、`require-dev`）。传递依赖不能添加软件。
+- **文件可以放在哪里**：只能在包内部。通过 `..`、绝对路径或符号链接指向包外的路径会被拒绝。不支持远程文件。
+- **优先级**：`dload.xml` > 官方注册表 > 包。包永远不会替换另外两者中的条目；
+  当官方注册表遮蔽了正在下载的某个包条目且指向不同的仓库时，DLoad 会发出警告。
+- **显式选择**：`<package>#<id>` 选择某个包的条目，无论它被什么遮蔽（没有 `name` 的根包使用 `__root__#<id>`）：
+  `dload get acme/framework#gh:^2.0` 或 `<download software="acme/framework#gh" />`。
+- **多个包使用同一个 id**：指向相同仓库的包彼此一致，无需报告。
+  否则根包优先，然后按 `require` 和 `require-dev` 中的顺序选择包，
+  并且下载该 id 时会列出所有可供选择的 `<package>#<id>`。
+- **有问题的声明**会以警告形式报告并被跳过；它们永远不会使 DLoad 停止运行。包括：文件不存在、XML 无效、
+  必填属性为空、需要文件名的地方写了路径、无效的正则表达式、既不是单个选项（如 `--version`）也不是 `version` 的 `version-command`，以及包含 `#`、`:` 或首尾有空格的 id。
+- **关闭**：`<registry from-packages="false">` 丢弃来自包的软件并保留官方注册表；
+  `<registry overwrite="true">` 两者都丢弃。
+
+`dload software` 会显示每个条目的来源：`official`、`dload.xml` 或包名。遮盖了其他条目的条目会在 `Shadows:` 中列出它们，包中的条目以 `<package>#<id>` 形式显示；`dload show <id>` 会在 `Source:` 中显示来源。
+
 ## 使用场景
 
 ### 开发环境配置