feat(cli): pure alias-based dispatcher in project bin; Commands\Toolbox entry point; describe() required on CommandInterface

BREAKING: project commands implementing CommandInterface must define
static describe(): string (intentional, forces documentation).

packages/commands/duckbrain

@@ -2,41 +2,111 @@
 <?php
 
 // CLI del proyecto Duckbrain. Requiere el autoloader del core (proyecto ya
-// armado). Delega en el motor `Toolbox\` si el componente opcional
-// `commands:toolbox` está instalado; en caso contrario, sólo ofrece los
-// comandos propios del proyecto (p. ej. migraciones).
-require_once('./autoload.php');
+// armado). Despachador genérico: el primer argumento resuelve primero como
+// nombre de clase del namespace Commands del proyecto y, si no, como alias
+// declarado por una de esas clases (`public static function aliases():
+// array`). Un alias duplicado —o que robe el nombre de otra clase— aborta
+// con error explícito listando ambos dueños. Los comandos implementan
+// Interfaces\CommandInterface (run + describe obligatorios).
 
-$command = $argv[1] ?? null;
+require_once './autoload.php';
 
-$toolboxCommands = [
-    'add', 'remove', 'update', 'list', 'doctor', 'catalog', 'adopt',
-    'help', '--help', '-h', '--version', '-V',
-];
-
-if ($command === null || in_array($command, $toolboxCommands, true)) {
-    if (!class_exists('Toolbox\\Cli')) {
-        fwrite(STDERR, "El componente 'commands:toolbox' no está instalado.\n");
-        fwrite(STDERR, "Añádelo con el instalador global: duckbrain add commands:toolbox\n");
-        exit(1);
+/**
+ * @return array<string, string> clase por nombre de archivo (basename => FQCN)
+ */
+function project_commands(): array
+{
+    $classes = [];
+    foreach (glob(rtrim(ROOT_CORE, '/') . '/Commands/*.php') as $file) {
+        $base  = basename($file, '.php');
+        $class = 'Commands\\' . $base;
+        if (class_exists($class) && is_a($class, 'Interfaces\\CommandInterface', true)) {
+            $classes[$base] = $class;
+        }
     }
 
-    exit((new Toolbox\Cli())->run($argv));
+    return $classes;
 }
 
-// Comandos propios del proyecto, despachados desde ROOT_CORE/Commands.
-$coreCommand = 'Commands\\' . ucfirst($command);
+/**
+ * @param array<string, string> $classes
+ * @return array<string, string> alias => FQCN
+ */
+function alias_map(array $classes): array
+{
+    $map     = [];
+    $byLower  = [];
+    foreach ($classes as $base => $class) {
+        $byLower[strtolower($base)] = $class;
+    }
 
-if (!class_exists($coreCommand) && !file_exists(ROOT_CORE . '/Commands/' . ucfirst($command) . '.php')) {
-    fwrite(STDERR, "Invalid command.\n");
-    exit(1);
+    foreach ($classes as $base => $class) {
+        if (!method_exists($class, 'aliases')) {
+            continue;
+        }
+
+        foreach ($class::aliases() as $alias) {
+            $owner = strtolower($base);
+            $key   = strtolower((string) $alias);
+
+            if ($key === $owner) {
+                continue;
+            }
+
+            if (isset($map[$key]) && $map[$key] !== $class) {
+                fwrite(STDERR, "Conflicto de alias '{$alias}': lo declaran {$map[$key]} y {$class}.\n");
+                exit(1);
+            }
+
+            if (isset($byLower[$key])) {
+                fwrite(STDERR, "El alias '{$alias}' de {$class} colisiona con el comando {$byLower[$key]}.\n");
+                exit(1);
+            }
+
+            $map[$key] = $class;
+        }
+    }
+
+    return $map;
 }
 
-$cli = new $coreCommand();
+$classes = project_commands();
+$map     = alias_map($classes);
+$command = $argv[1] ?? null;
 
-if ($cli instanceof Interfaces\CommandInterface) {
-    call_user_func_array([$cli, 'run'], array_slice($argv, 2));
+if ($command === null) {
+    $rev = [];
+    foreach ($map as $alias => $class) {
+        $rev[$class][] = $alias;
+    }
+
+    foreach ($classes as $base => $class) {
+        $line = '  ' . strtolower($base);
+        if (($rev[$class] ?? []) !== []) {
+            $line .= ', ' . implode(', ', $rev[$class]);
+        }
+        fwrite(STDOUT, $line . ' — ' . $class::describe() . "\n");
+    }
+
+    exit(0);
+}
+
+$direct = 'Commands\\' . ucfirst($command);
+$class  = null;
+$slice  = 2;
+
+if (class_exists($direct) && is_a($direct, 'Interfaces\\CommandInterface', true)) {
+    $class = $direct;
 } else {
-    fwrite(STDERR, "La clase $coreCommand no implementa CommandInterface.\n");
+    $class = $map[strtolower($command)] ?? null;
+    $slice = $class === null ? $slice : 1;
+}
+
+if ($class === null) {
+    fwrite(STDERR, "Comando desconocido: {$command}\n");
     exit(1);
 }
+
+$cli = new $class();
+
+call_user_func_array([$cli, 'run'], array_slice($argv, $slice));