Enhance version syntax for get command

CLAUDE.md

@@ -0,0 +1,50 @@
+- Always use guidelines from the `docs/guidelines` folder
+
+## Guidelines Index
+
+### 📖 Documentation Guidelines
+**Path:** `docs/guidelines/how-to-translate-readme-docs.md`  
+**Value:** Standardizes documentation translation process and multilingual content management  
+**Key Areas:**
+- Translation workflow using LLMs for documentation
+- Multilanguage README pattern using ISO 639-1 codes (`README-{lang_code}.md`)
+- Quality standards: preserve technical content, ensure natural language flow
+- Review process for translated content
+- MAPS framework for complex translations
+
+### 🖥️ Console Command Development
+**Path:** `docs/guidelines/how-to-write-console-command.md`  
+**Value:** Ensures consistent CLI interface design and proper Symfony console integration  
+**Key Areas:**
+- Command structure: extend `Base` class, use `#[AsCommand]` attribute
+- Required methods: `configure()` and `execute()`
+- Type system: always use `Path` value object instead of strings for file paths
+- Interactive patterns: use `$input->isInteractive()` for detection
+- Error handling: proper return codes (`Command::SUCCESS`, `Command::FAILURE`, `Command::INVALID`)
+- Best practices: method extraction, confirmation dialogs, file operation patterns
+- Available services through DI container (Logger, StyleInterface, etc.)
+
+### 📝 PHP Code Standards
+**Path:** `docs/guidelines/how-to-write-php-code-best-practices.md`  
+**Value:** Maintains modern PHP code quality and leverages latest language features for better performance and maintainability  
+**Key Areas:**
+- Modern PHP 8.1+ features: constructor promotion, union types, match expressions, throw expressions
+- Code structure: PER-2 standards, single responsibility, final classes by default
+- Enumerations: use enums for fixed value sets, CamelCase naming, backed enums for primitives
+- Immutability: readonly properties, `with` prefix for immutable updates
+- Type system: precise PHPDoc annotations, generics, non-empty-string types
+- Comparison patterns: strict equality (`===`), null coalescing (`??`), avoid `empty()`
+- Dependency injection and IoC container patterns
+
+### 🧪 Testing Guidelines
+**Path:** `docs/guidelines/how-to-write-tests.md`  
+**Value:** Ensures comprehensive test coverage with modern PHPUnit practices and proper test isolation  
+**Key Areas:**
+- Test structure: mirror source structure, `final` test classes, Arrange-Act-Assert pattern
+- Module testing: independent test areas with dedicated `Stub` directories
+- Naming: `{ClassUnderTest}Test`, descriptive method names
+- Modern PHPUnit: PHP 8.1+ attributes (`#[CoversClass]`, `#[DataProvider]`), data providers with generators
+- Isolation: mock dependencies, use test doubles, reset state between tests
+- **Critical restrictions**: DO NOT mock enums or final classes - use real instances
+- Error testing: expectException before Act phase
+- Test traits for shared functionality

README-es.md

@@ -37,7 +37,7 @@
 - [Instalación](#instalación)
 - [Inicio Rápido](#inicio-rápido)
 - [Uso desde Línea de Comandos](#uso-desde-línea-de-comandos)
     - [Inicializar Configuración](#inicializar-configuración)
     - [Descargar Software](#descargar-software)
     - [Ver Software](#ver-software)
     - [Construir Software Personalizado](#construir-software-personalizado)
@@ -153,6 +153,9 @@
 # Descargar paquetes específicos
 ./vendor/bin/dload get rr temporal
 
+# Descargar con versiones específicas
+./vendor/bin/dload get rr:2025.1.0 dolt:1.44.1 temporal:1.*@alpha
+
 # Descargar con opciones adicionales
 ./vendor/bin/dload get rr --stability=beta --force
 ```

README-ru.md

@@ -154,6 +154,9 @@ composer require internal/dload -W
 # Загрузить конкретные пакеты
 ./vendor/bin/dload get rr temporal
 
+# Загрузить с указанием конкретных версий
+./vendor/bin/dload get rr:2025.1.0 dolt:1.44.1 temporal:1.*@alpha
+
 # Загрузить с дополнительными опциями
 ./vendor/bin/dload get rr --stability=beta --force
 ```

README-zh.md

@@ -153,6 +153,9 @@ composer require internal/dload -W
 # 下载指定软件包
 ./vendor/bin/dload get rr temporal
 
+# 下载指定版本的软件包
+./vendor/bin/dload get rr:2025.1.0 dolt:1.44.1 temporal:1.*@alpha
+
 # 带选项下载
 ./vendor/bin/dload get rr --stability=beta --force
 ```

README.md

@@ -153,6 +153,9 @@ Alternatively, you can download the latest release from [GitHub releases](https:
 # Download specific packages
 ./vendor/bin/dload get rr temporal
 
+# Download with specific versions and minimum stability
+./vendor/bin/dload get rr:2025.* dolt:1.44.1 mago:1.*@alpha
+
 # Download with options
 ./vendor/bin/dload get rr --stability=beta --force
 ```

resources/software.json

@@ -138,7 +138,7 @@
         {
             "name": "Trap",
             "alias": "trap",
-            "description": "A minimized version of the Buggregator Server that does not require Docker and is intended solely for local use.\n",
+            "description": "A minimized version of the Buggregator Server that does not require Docker and is intended solely for local use.",
             "homepage": "https://buggregator.dev/",
             "repositories": [
                 {
@@ -151,6 +151,23 @@
                 "name": "trap",
                 "version-command": "--version"
             }
+        },
+        {
+            "name": "Mago",
+            "alias": "mago",
+            "description": "Mago is a toolchain for PHP that aims to provide a set of tools to help developers write better code.",
+            "homepage": "https://mago.carthage.software/",
+            "repositories": [
+                {
+                    "type": "github",
+                    "uri": "carthage-software/mago",
+                    "asset-pattern": "/^mago.*/"
+                }
+            ],
+            "binary": {
+                "name": "mago",
+                "version-command": "--version"
+            }
         }
     ]
 }

src/Command/Get.php

@@ -10,8 +10,10 @@
 use Internal\DLoad\Module\Common\Stability;
 use Internal\DLoad\Module\Config\Schema\Action\Download as DownloadConfig;
 use Internal\DLoad\Module\Config\Schema\Actions;
+use Internal\DLoad\Service\Container;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Exception\InvalidArgumentException;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
@@ -31,8 +33,8 @@
  * # Download specific version of software
  * ./vendor/bin/dload get rr --stability=beta
  *
- * # Download multiple software packages
- * ./vendor/bin/dload get rr dolt temporal
+ * # Download multiple software packages with versions and stability
+ * ./vendor/bin/dload get rr dolt:1.44.1 temporal:1.*@alpha
  *
  * # Download software defined in config file
  * ./vendor/bin/dload get --config=./dload.xml
@@ -66,7 +68,7 @@
         $this->addOption('path', null, InputOption::VALUE_OPTIONAL, 'Path to store the binary, e.g. "./bin"', ".");
         $this->addOption('arch', null, InputOption::VALUE_OPTIONAL, 'Architecture, e.g. "amd64", "arm64" etc.');
         $this->addOption('os', null, InputOption::VALUE_OPTIONAL, 'Operating system, e.g. "linux", "darwin" etc.');
-        $this->addOption('stability', null, InputOption::VALUE_OPTIONAL, 'Stability, e.g. "stable", "beta" etc.');
+        $this->addOption('stability', null, InputOption::VALUE_OPTIONAL, 'Minimum stability, e.g. "rc", "beta" etc.');
         $this->addOption('force', 'f', InputOption::VALUE_NONE, 'Force download even if binary exists');
     }
 
@@ -88,9 +90,11 @@
         parent::execute($input, $output);
         $container = $this->container;
 
+        self::applyFlags($input, $container);
+
         /** @var Actions $actionsConfig */
         $actionsConfig = $container->get(Actions::class);
-        $actions = $this->getDownloadActions($input, $actionsConfig);
+        $actions = self::getDownloadActions($input, $actionsConfig);
 
         $output->writeln('Architecture: ' . $container->get(Architecture::class)->name);
         $output->writeln('  Op. system: ' . $container->get(OperatingSystem::class)->name);
@@ -121,7 +125,7 @@
      *
      * @return list<DownloadConfig> List of download configurations to process
      */
-    private function getDownloadActions(InputInterface $input, Actions $actionsConfig): array
+    private static function getDownloadActions(InputInterface $input, Actions $actionsConfig): array
     {
         $argument = $input->getArgument(self::ARG_SOFTWARE);
         if ($argument === []) {
@@ -134,10 +138,60 @@
             $toDownload[$action->software] = $action;
         }
 
         return \array_map(
-            static fn(mixed $software): DownloadConfig => $toDownload[$software]
-                ?? DownloadConfig::fromSoftwareId((string) $software),
-            $input->getArgument(self::ARG_SOFTWARE),
+            static fn(string $software): DownloadConfig => $toDownload[$software] ?? self::parseSoftware($software),
+            (array) $input->getArgument(self::ARG_SOFTWARE),
+        );
+    }
+
+    /**
+     * Parses a software identifier into a download configuration.
+     *
+     * Supports "name:version" format to specify exact versions.
+     * E.g. "rr:2.10.0", "dolt:1.2.3@beta", "temporal:1.3.1-priority", etc.
+     *
+     * @param string $software Software identifier, e.g. "rr" or "dolt:1.2.3"
+     * @return DownloadConfig Parsed download configuration
+     */
+    private static function parseSoftware(string $software): DownloadConfig
+    {
+        [$name, $version] = \explode(':', $software, 2) + [1 => ''];
+        $name === '' and throw new InvalidArgumentException("Software name cannot be empty, given: {$software}.");
+
+        $action = DownloadConfig::fromSoftwareId($name);
+        $version === '' or $action->version = $version;
+
+        return $action;
+    }
+
+    /**
+     * Applies command-line flags to override container settings.
+     *
+     * Sets architecture, operating system, and stability in the container
+     * based on provided CLI options.
+     *
+     * @param InputInterface $input Command input
+     * @param Container $container Dependency injection container
+     *
+     * @throws InvalidArgumentException When an unknown value is provided
+     */
+    private static function applyFlags(InputInterface $input, Container $container): void
+    {
+        $stability = (string) $input->getOption('stability');
+        $stability === '' or $container->set(
+            Stability::fromString((string) $input->getOption('stability')) ?? throw new InvalidArgumentException(
+                "Unknown stability level: {$stability}.",
+            ),
         );
+
+        $os = (string) $input->getOption('os');
+        $os === '' or $container->set(OperatingSystem::tryFromString($os) ?? throw new InvalidArgumentException(
+            "Unknown operating system: {$os}.",
+        ));
+
+        $arch = (string) $input->getOption('arch');
+        $arch === '' or $container->set(Architecture::tryFromString($arch) ?? throw new InvalidArgumentException(
+            "Unknown architecture: {$arch}.",
+        ));
     }
 }