feat: version registry that keeps release lists between runs

README-es.md

@@ -48,6 +48,7 @@ Con DLoad puedes:
     - [Tipos de Descarga](#tipos-de-descarga)
     - [Restricciones de Versión](#restricciones-de-versión)
     - [Opciones de Configuración Avanzadas](#opciones-de-configuración-avanzadas)
+    - [Registro de Versiones](#registro-de-versiones)
 - [Construir RoadRunner Personalizado](#construir-roadrunner-personalizado)
     - [Configuración de Acción de Construcción](#configuración-de-acción-de-construcción)
     - [Atributos de Acción Velox](#atributos-de-acción-velox)
@@ -348,6 +349,72 @@ Usa restricciones de versión estilo Composer:
 </dload>
 ```
 
+### Registro de Versiones
+
+Resolver una versión significa pedir a GitHub o GitLab la lista de releases del repositorio. DLoad
+guarda lo que aprende en un **registro de versiones** local: una pequeña base de datos con los releases
+y assets de cada repositorio conocido, un archivo JSON por repositorio. Las versiones nunca expiran.
+Lo que expira es la *última comprobación* del repositorio: mientras sea más reciente que `cache-ttl`,
+`dload get` se responde desde el registro sin una sola petición a la API. Cuando es más antigua, DLoad
+pide a la API solo los releases publicados desde entonces, normalmente una única petición.
+
+Las páginas de releases se siguen cargando de forma perezosa. La primera ejecución obtiene solo las
+páginas necesarias para encontrar un release que cumpla la versión pedida; los releases más antiguos se
+cargan después, bajo demanda.
+
+El registro está activado por defecto y vive en el directorio de caché del usuario
+(`$XDG_CACHE_HOME/dload`, `%LOCALAPPDATA%\dload\cache` en Windows, `~/.cache/dload` en otros casos):
+
+```xml
+<dload temp-dir="./runtime" cache-dir="./runtime/dload-cache" cache-ttl="3600">
+    <actions>
+        <download software="rr" />
+    </actions>
+</dload>
+```
+
+| Atributo    | Variable de entorno | Por defecto                    | Significado                                                                          |
+|-------------|---------------------|--------------------------------|--------------------------------------------------------------------------------------|
+| `cache-dir` | `DLOAD_CACHE_DIR`   | directorio de caché del usuario | Directorio del registro de versiones.                                                |
+| `cache-ttl` | `DLOAD_CACHE_TTL`   | `600`                          | Segundos que sigue siendo válida la última comprobación. `0` desactiva el registro. |
+
+```bash
+# Comprobar si hay nuevos releases aunque la última comprobación siga vigente
+./vendor/bin/dload get rr --refresh
+
+# Olvidar los repositorios de un software, o todo el registro
+./vendor/bin/dload cache:clear rr
+./vendor/bin/dload cache:clear
+```
+
+> [!NOTE]
+> El registro solo contiene metadatos de releases: tags, nombres y enlaces de descarga. Las descargas
+> no pasan por él y nunca guarda credenciales, así que el directorio puede compartirse o guardarse en
+> la caché de CI sin problemas. Si una comprobación falla por un error de red o un límite de la API, se
+> usan los releases almacenados; un repositorio nunca visto sigue fallando de forma visible. Un
+> release almacenado cuyos assets desaparecieron del origen se elimina del registro en cuanto falla
+> su descarga, y la lista de releases se vuelve a obtener antes de que la ejecución se dé por vencida.
+
+En GitHub Actions el directorio puede conservarse entre ejecuciones del workflow, de modo que cada
+ejecución gasta el límite de la API solo en los releases publicados desde la anterior:
+
+```yaml
+- name: Restore DLoad version registry
+  uses: actions/cache@v4
+  with:
+    path: ./runtime/dload-cache
+    key: dload-registry-${{ github.run_id }}
+    restore-keys: dload-registry-
+
+- run: ./vendor/bin/dload get
+  env:
+    DLOAD_CACHE_DIR: ./runtime/dload-cache
+```
+
+El `github.run_id` en la clave hace que cada ejecución guarde su registro, y `restore-keys` permite
+que la siguiente parta del más reciente. Los jobs paralelos de un mismo workflow no ven la caché de los
+demás, ya que `actions/cache` la guarda al terminar cada job.
+
 ## Construir RoadRunner Personalizado
 
 DLoad soporta la construcción de binarios personalizados de RoadRunner usando la herramienta Velox. Esto es útil cuando necesitas RoadRunner con combinaciones específicas de plugins que no están disponibles en las versiones pre-construidas.

README-ru.md

@@ -49,6 +49,7 @@ DLoad решает распространённую проблему в PHP-пр
     - [Типы загрузки](#типы-загрузки)
     - [Ограничения версий](#ограничения-версий)
     - [Расширенные настройки](#расширенные-настройки)
+    - [Реестр версий](#реестр-версий)
 - [Сборка кастомного RoadRunner](#сборка-кастомного-roadrunner)
     - [Настройка действия сборки](#настройка-действия-сборки)
     - [Атрибуты Velox-действия](#атрибуты-velox-действия)
@@ -349,6 +350,73 @@ DLoad поддерживает три типа загрузки, которые
 </dload>
 ```
 
+### Реестр версий
+
+Чтобы определить версию, DLoad запрашивает у GitHub или GitLab список релизов репозитория. Всё,
+что он узнаёт, сохраняется в локальном **реестре версий**: небольшой базе релизов и ассетов каждого
+известного репозитория, по одному JSON-файлу на репозиторий. Версии из реестра не устаревают.
+Устаревает только *последняя проверка* репозитория: пока она моложе `cache-ttl`, `dload get`
+отвечает из реестра без единого запроса к API. Когда проверка устарела, DLoad запрашивает у API
+только релизы, вышедшие после неё, и обычно это один запрос.
+
+Страницы релизов по-прежнему загружаются лениво. Первый запуск получает столько страниц, сколько
+нужно, чтобы найти релиз под запрошенную версию, а более старые релизы догружаются позже, по мере
+надобности.
+
+Реестр включён по умолчанию и живёт в пользовательском каталоге кэша (`$XDG_CACHE_HOME/dload`,
+`%LOCALAPPDATA%\dload\cache` в Windows, иначе `~/.cache/dload`):
+
+```xml
+<dload temp-dir="./runtime" cache-dir="./runtime/dload-cache" cache-ttl="3600">
+    <actions>
+        <download software="rr" />
+    </actions>
+</dload>
+```
+
+| Атрибут     | Переменная окружения | По умолчанию              | Значение                                                                        |
+|-------------|----------------------|---------------------------|---------------------------------------------------------------------------------|
+| `cache-dir` | `DLOAD_CACHE_DIR`    | каталог кэша пользователя | Каталог реестра версий.                                                         |
+| `cache-ttl` | `DLOAD_CACHE_TTL`    | `600`                     | Сколько секунд действует последняя проверка репозитория. `0` отключает реестр. |
+
+```bash
+# Проверить репозитории на новые релизы, даже если последняя проверка ещё свежая
+./vendor/bin/dload get rr --refresh
+
+# Забыть репозитории, из которых берётся программа, или весь реестр целиком
+./vendor/bin/dload cache:clear rr
+./vendor/bin/dload cache:clear
+```
+
+> [!NOTE]
+> В реестре хранятся только метаданные релизов: теги, имена и ссылки на ассеты. Загрузки через него
+> не проходят, учётные данные в нём не сохраняются, поэтому каталог можно свободно передавать между
+> машинами и складывать в кэш CI. Если проверка не удалась из-за сетевой ошибки или лимита API,
+> используются сохранённые релизы, а репозиторий, который раньше не встречался, по-прежнему
+> завершится ошибкой. Сохранённый релиз, ассеты которого исчезли из источника, удаляется из
+> реестра сразу после неудачной загрузки, а список релизов запрашивается заново, прежде чем
+> запуск завершится ошибкой.
+
+В GitHub Actions каталог можно переносить между запусками workflow, тогда запуск тратит лимит API
+только на релизы, вышедшие после предыдущего:
+
+```yaml
+- name: Restore DLoad version registry
+  uses: actions/cache@v4
+  with:
+    path: ./runtime/dload-cache
+    key: dload-registry-${{ github.run_id }}
+    restore-keys: dload-registry-
+
+- run: ./vendor/bin/dload get
+  env:
+    DLOAD_CACHE_DIR: ./runtime/dload-cache
+```
+
+`github.run_id` в ключе заставляет каждый запуск сохранять свой реестр, а `restore-keys` позволяет
+следующему запуску начать с самого свежего. Параллельные джобы одного workflow кэш друг друга не
+видят: `actions/cache` сохраняет его по завершении джобы.
+
 ## Сборка кастомного RoadRunner
 
 DLoad поддерживает сборку кастомных бинарников RoadRunner с помощью инструмента сборки Velox. Это полезно когда нужен RoadRunner с определёнными комбинациями плагинов, которые недоступны в готовых релизах.

README-zh.md

@@ -48,6 +48,7 @@ DLoad 解决了 PHP 项目中的一个实际问题：如何在分发 PHP 代码
     - [下载类型](#下载类型)
     - [版本约束](#版本约束)
     - [高级配置选项](#高级配置选项)
+    - [版本注册表](#版本注册表)
 - [构建自定义 RoadRunner](#构建自定义-roadrunner)
     - [构建动作配置](#构建动作配置)
     - [Velox 动作属性](#velox-动作属性)
@@ -348,6 +349,65 @@ DLoad 支持三种下载类型，它们决定了资源的处理方式：
 </dload>
 ```
 
+### 版本注册表
+
+解析版本意味着向 GitHub 或 GitLab 请求仓库的发布列表。DLoad 会把获取到的信息保存在本地的
+**版本注册表**中：这是一个小型数据库，记录每个已知仓库的发布版本和资产，每个仓库一个 JSON 文件。
+其中的版本永不过期，过期的只是仓库的*最近一次检查*：只要检查时间比 `cache-ttl` 更新，`dload get`
+就直接从注册表返回结果，不会发出任何 API 请求。检查过期后，DLoad 只向 API 请求此后发布的版本，
+通常只需一次请求。
+
+发布页面仍然按需加载。首次运行只获取找到满足所需版本的发布所需的页面，更早的发布会在之后真正需要时再加载。
+
+注册表默认启用，位于用户缓存目录（`$XDG_CACHE_HOME/dload`，Windows 下为 `%LOCALAPPDATA%\dload\cache`，
+其他情况为 `~/.cache/dload`）：
+
+```xml
+<dload temp-dir="./runtime" cache-dir="./runtime/dload-cache" cache-ttl="3600">
+    <actions>
+        <download software="rr" />
+    </actions>
+</dload>
+```
+
+| 属性        | 环境变量           | 默认值       | 含义                                         |
+|-------------|--------------------|--------------|----------------------------------------------|
+| `cache-dir` | `DLOAD_CACHE_DIR`  | 用户缓存目录 | 版本注册表所在目录。                         |
+| `cache-ttl` | `DLOAD_CACHE_TTL`  | `600`        | 最近一次检查保持有效的秒数。`0` 表示禁用注册表。 |
+
+```bash
+# 即使最近一次检查仍然有效，也强制检查仓库是否有新发布
+./vendor/bin/dload get rr --refresh
+
+# 忘记某个软件所使用的仓库，或清空整个注册表
+./vendor/bin/dload cache:clear rr
+./vendor/bin/dload cache:clear
+```
+
+> [!NOTE]
+> 注册表只保存发布的元数据：标签、名称和资产下载链接。下载不会经过注册表，也不会保存任何凭据，
+> 因此该目录可以自由共享或放入 CI 缓存。若因网络错误或 API 速率限制导致检查失败，会使用已保存的发布；
+> 从未见过的仓库仍会明确报错。若某个已保存发布的资产在上游已被删除，下载失败后它会立即从注册表中移除，
+> 并在本次运行放弃之前重新获取发布列表。
+
+在 GitHub Actions 中可以在多次工作流运行之间保留该目录，这样每次运行只为上次运行之后发布的版本消耗速率限制：
+
+```yaml
+- name: Restore DLoad version registry
+  uses: actions/cache@v4
+  with:
+    path: ./runtime/dload-cache
+    key: dload-registry-${{ github.run_id }}
+    restore-keys: dload-registry-
+
+- run: ./vendor/bin/dload get
+  env:
+    DLOAD_CACHE_DIR: ./runtime/dload-cache
+```
+
+键中的 `github.run_id` 使每次运行都保存自己的注册表，而 `restore-keys` 让下一次运行从最新的注册表开始。
+同一工作流中并行运行的作业彼此看不到缓存，因为 `actions/cache` 在作业结束时才保存缓存。
+
 ## 构建自定义 RoadRunner
 
 DLoad 支持使用 Velox 构建工具来构建自定义 RoadRunner 二进制文件。当你需要包含特定插件组合的 RoadRunner，而这些组合在预构建版本中不可用时，这功能就很有用了。

README.md

@@ -49,6 +49,7 @@ With DLoad, you can:
     - [Download Types](#download-types)
     - [Version Constraints](#version-constraints)
     - [Advanced Configuration Options](#advanced-configuration-options)
+    - [Version Registry](#version-registry)
 - [Building Custom RoadRunner](#building-custom-roadrunner)
     - [Build Action Configuration](#build-action-configuration)
     - [Velox Action Attributes](#velox-action-attributes)
@@ -350,6 +351,72 @@ Use Composer-style version constraints:
 </dload>
 ```
 
+### Version Registry
+
+Resolving a version means asking GitHub or GitLab for the repository's release list. DLoad keeps
+what it learns in a local **version registry**: a small database of the releases and assets every
+known repository offers, one JSON file per repository. Versions never expire from it. What expires
+is the *last check* of a repository: while the check is younger than `cache-ttl`, `dload get` is
+answered from the registry without a single API request. When it is older, DLoad asks the API only
+for the releases published since the last check, which is usually one request.
+
+Release pages are still loaded lazily. The first run fetches only as many pages as it takes to find
+a release that satisfies the requested version, and older releases are fetched later, on demand,
+when a run actually needs one of them.
+
+The registry is on by default and lives in the per-user cache directory (`$XDG_CACHE_HOME/dload`,
+`%LOCALAPPDATA%\dload\cache` on Windows, `~/.cache/dload` otherwise):
+
+```xml
+<dload temp-dir="./runtime" cache-dir="./runtime/dload-cache" cache-ttl="3600">
+    <actions>
+        <download software="rr" />
+    </actions>
+</dload>
+```
+
+| Attribute   | Environment variable | Default              | Meaning                                                                |
+|-------------|----------------------|----------------------|------------------------------------------------------------------------|
+| `cache-dir` | `DLOAD_CACHE_DIR`    | user cache directory | Directory of the version registry.                                     |
+| `cache-ttl` | `DLOAD_CACHE_TTL`    | `600`                | Seconds the last check of a repository stays valid. `0` disables the registry. |
+
+```bash
+# Check the repositories for new releases even if the last check is still fresh
+./vendor/bin/dload get rr --refresh
+
+# Forget the repositories a software package is served from, or the whole registry
+./vendor/bin/dload cache:clear rr
+./vendor/bin/dload cache:clear
+```
+
+> [!NOTE]
+> The registry holds release metadata only: tags, names and asset download links. Downloads never
+> go through it and credentials are never stored in it, so the directory can be shared or committed
+> to a CI cache freely. When a check fails because of a network error or a rate limit, the stored
+> releases are used instead, and a repository that was never seen before still fails loudly.
+> A stored release whose assets have disappeared upstream is dropped from the registry as soon as
+> its download fails, and the release list is fetched again before the run gives up.
+
+In GitHub Actions the directory can be carried between workflow runs, so a run spends the rate limit
+only on releases published since the previous one:
+
+```yaml
+- name: Restore DLoad version registry
+  uses: actions/cache@v4
+  with:
+    path: ./runtime/dload-cache
+    key: dload-registry-${{ github.run_id }}
+    restore-keys: dload-registry-
+
+- run: ./vendor/bin/dload get
+  env:
+    DLOAD_CACHE_DIR: ./runtime/dload-cache
+```
+
+The `github.run_id` in the key makes every workflow run save its registry, while `restore-keys`
+lets the next run start from the most recent one. Jobs that run in parallel within one workflow do not
+see each other's cache, since `actions/cache` saves it when a job ends.
+
 ## Building Custom RoadRunner
 
 DLoad supports building custom RoadRunner binaries using the Velox build tool. This is useful when you need RoadRunner with custom plugin combinations that aren't available in pre-built releases.
@@ -600,6 +667,9 @@ Add to CI/CD environment variables for automated downloads.
 > 1,000 requests per hour across all jobs of the repository. With a large job matrix the limit may run out,
 > and downloads from other repositories may be rejected. Use a personal access token if that happens.
 
+Release lists are also kept in a local version registry, so repeated runs and runs that carry the
+registry between them spend the rate limit only on new releases: see [Version Registry](#version-registry).
+
 ## Failure Reporting
 
 `dload get` exits with a non-zero code when at least one requested package was not installed, and prints

bin/dload

@@ -51,6 +51,7 @@ use Symfony\Component\Console\CommandLoader\FactoryCommandLoader;
             Command\Show::getCommandName() => static fn() => new Command\Show(),
             Command\Init::getCommandName() => static fn() => new Command\Init(),
             Command\Build::getCommandName() => static fn() => new Command\Build(),
+            Command\CacheClear::getCommandName() => static fn() => new Command\CacheClear(),
         ]),
     );
     $application->setDefaultCommand(Command\Get::getCommandName(), false);