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
+// armado). Despachador genérico: el primer argumento resuelve primero como
-// `commands:toolbox` está instalado; en caso contrario, sólo ofrece los
+// nombre de clase del namespace Commands del proyecto y, si no, como alias
-// comandos propios del proyecto (p. ej. migraciones).
+// declarado por una de esas clases (`public static function aliases():
-require_once('./autoload.php');
+// 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',
+ * @return array<string, string> clase por nombre de archivo (basename => FQCN)
-    'help', '--help', '-h', '--version', '-V',
+ */
-];
+function project_commands(): array
-
+{
-if ($command === null || in_array($command, $toolboxCommands, true)) {
+    $classes = [];
-    if (!class_exists('Toolbox\\Cli')) {
+    foreach (glob(rtrim(ROOT_CORE, '/') . '/Commands/*.php') as $file) {
-        fwrite(STDERR, "El componente 'commands:toolbox' no está instalado.\n");
+        $base  = basename($file, '.php');
-        fwrite(STDERR, "Añádelo con el instalador global: duckbrain add commands:toolbox\n");
+        $class = 'Commands\\' . $base;
-        exit(1);
+        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')) {
+    foreach ($classes as $base => $class) {
-    fwrite(STDERR, "Invalid command.\n");
+        if (!method_exists($class, 'aliases')) {
-    exit(1);
+            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) {
+if ($command === null) {
-    call_user_func_array([$cli, 'run'], array_slice($argv, 2));
+    $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));

packages/commands/duckbrain.json

@@ -1,40 +1,41 @@
 {
-    "name": "commands",
+  "name": "commands",
-    "version": "0.2.4",
+  "version": "0.2.4",
-    "description": "CLI y migraciones para Duckbrain",
+  "description": "CLI y migraciones para Duckbrain",
-    "components": {
+  "components": {
-        "cli": {
+    "cli": {
-            "files": [
+      "files": [
-                "duckbrain",
+        "duckbrain",
-                "src/Interfaces/CommandInterface.php"
+        "src/Interfaces/CommandInterface.php"
-            ],
+      ],
-            "description": "CLI del proyecto (binario duckbrain)",
+      "description": "CLI del proyecto (binario duckbrain)",
-            "core": "none"
+      "core": "none"
-        },
-        "migration": {
-            "files": [
-                "src/Commands/Migration.php",
-                "src/Libs/Migration.php"
-            ],
-            "require": {
-                "commands:cli": "*"
-            },
-            "core": {
-                "requires": ">=0.1",
-                "tested": "0.1"
-            },
-            "description": "Migraciones de base de datos (mysql/pgsql/sqlite)"
-        },
-        "toolbox": {
-            "files": [
-                "src/Toolbox"
-            ],
-            "description": "Gestor de addons dentro del propio proyecto",
-            "core": "none"
-        }
     },
-    "default": [
+    "migration": {
-        "cli",
+      "files": [
-        "migration"
+        "src/Commands/Migration.php",
-    ]
+        "src/Libs/Migration.php"
+      ],
+      "require": {
+        "commands:cli": "*"
+      },
+      "core": {
+        "requires": ">=0.1",
+        "tested": "0.1"
+      },
+      "description": "Migraciones de base de datos (mysql/pgsql/sqlite)"
+    },
+    "toolbox": {
+      "files": [
+        "src/Toolbox",
+        "src/Commands/Toolbox.php"
+      ],
+      "description": "Gestor de addons dentro del propio proyecto",
+      "core": "none"
+    }
+  },
+  "default": [
+    "cli",
+    "migration"
+  ]
 }

packages/commands/src/Commands/Migration.php

@@ -10,6 +10,11 @@ use PDO;
 
 class Migration implements CommandInterface
 {
+    public static function describe(): string
+    {
+        return 'Migraciones de base de datos (create, migrate, rollback, fresh, clear)';
+    }
+
     private const MIGRATIONS_PATH = ROOT_DIR . '/migrations/';
     private string $migratonsDatabaseFile;
     private PDO $db;

packages/commands/src/Commands/Toolbox.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace Commands;
+
+use Interfaces\CommandInterface;
+use Toolbox\Cli;
+
+/**
+ * Entry point del gestor de addons dentro del proyecto: el bin `duckbrain`
+ * despacha aquí todo alias del motor (add, remove, update, list, doctor,
+ * catalog, adopt, help y variantes de versión/usage). Vive en el namespace
+ * Commands del proyecto para que el binario siga siendo un despachador
+ * genérico: no conoce la lista de comandos de nadie más que de los propios.
+ */
+class Toolbox implements CommandInterface
+{
+    public static function describe(): string
+    {
+        return 'Gestor de addons del proyecto (motor duckbrain-toolbox)';
+    }
+
+    /**
+     * @return list<string>
+     */
+    public static function aliases(): array
+    {
+        return [
+            'add', 'remove', 'update', 'list', 'doctor', 'catalog', 'adopt',
+            'help', '--help', '-h', '--version', '-V',
+        ];
+    }
+
+    public function run(): void
+    {
+        $args = func_get_args();
+
+        exit((new Cli())->run(array_merge(['duckbrain'], array_map('strval', $args))));
+    }
+}

packages/commands/src/Interfaces/CommandInterface.php

@@ -10,4 +10,10 @@ interface CommandInterface
      * @return void
      */
     public function run(): void;
+
+    /**
+     * Descripción de una línea del comando, obligatoria: fuerza a documentar
+     * cada comando del proyecto para que sea visible en la superficie.
+     */
+    public static function describe(): string;
 }

tests/group7_commands_test.php

@@ -262,3 +262,19 @@ Harness::it('el catálogo describe cada componente con su texto propio o heredad
     rrmdir($toolbox);
     rrmdir($proj);
 });
+
+Harness::it('un comando del proyecto sin describe() no carga (interfaz estricta)', function () {
+    $proj = tmpdir('proj');
+    mkdir($proj . '/src/Commands', 0777, true);
+    write_file($proj . '/autoload.php', "<?php\nspl_autoload_register(function (string \$c): void {\n    \$f = \$c === 'Commands\\\\SinDoc' ? ROOT_CORE . '/Commands/SinDoc.php' : null;\n    if (\$f !== null && is_file(\$f)) { require \$f; }\n});\ndefine('ROOT_CORE', __DIR__ . '/src');\ndefine('ROOT_DIR', __DIR__);\n");
+    write_file($proj . '/src/Commands/SinDoc.php', "<?php\nnamespace Commands;\nclass SinDoc implements \\Interfaces\\CommandInterface { public function run(): void {} }\n");
+    write_file($proj . '/src/Interfaces/CommandInterface.php', "<?php\nnamespace Interfaces;\ninterface CommandInterface { public function run(): void; public static function describe(): string; }\n");
+
+    $out  = [];
+    $code = 0;
+    exec('cd ' . escapeshellarg($proj) . ' && php -r \'require "autoload.php"; class_exists("Commands\\\\SinDoc") ? print("loaded") : print("missing");\' 2>&1', $out, $code);
+
+    ok($code !== 0 || str_contains(implode('', $out), 'Fatal'), 'la carga de un comando sin describe produce error fatal');
+
+    rrmdir($proj);
+});

tests/group8_project_cli_test.php

@@ -72,3 +72,61 @@ Harness::it('la actualización del motor surte efecto en la siguiente invocació
     rrmdir($proj);
     rrmdir($core);
 });
+
+Harness::it('el bin despacha por clase, alias, usage y guard de colisiones', function () {
+    $repo = $GLOBALS['g8_repo'];
+    $core = g7_core('0.1.0');
+    $proj = tmpdir('proj');
+
+    (new InstallCommand(new Console()))->run([$proj, '--toolbox=' . $repo, '--core-dir=' . $core, '--yes']);
+    (new AddCommand(new Console()))->run(['commands:cli', 'commands:toolbox', '--root=' . $proj, '--toolbox=' . $repo, '--yes']);
+
+    write_file($proj . '/src/Commands/Eco.php', "<?php\n\nnamespace Commands;\n\nclass Eco implements \\Interfaces\\CommandInterface\n{\n    public static function describe(): string { return 'Comando eco de prueba'; }\n    public function run(): void { echo 'ECO_OK' . PHP_EOL; }\n}\n");
+
+    $o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain eco 2>&1', $o, $c1);
+    eq(0, $c1); ok(str_contains(implode('', $o), 'ECO_OK'), 'dispatch por nombre de clase');
+
+    $o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain list 2>&1', $o, $c2);
+    eq(0, $c2); ok(str_contains(implode('', $o), 'commands:cli'), 'dispatch por alias del motor');
+
+    $o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain 2>&1', $o, $c3);
+    eq(0, $c3); $usage = implode('', $o);
+    ok(str_contains($usage, 'eco') && str_contains($usage, 'Comando eco de prueba'), 'usage lista clase y describe');
+    ok(str_contains($usage, 'toolbox, add'), 'usage lista aliases del entry del motor');
+
+    $o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain noexiste 2>&1', $o, $c4);
+    eq(1, $c4); ok(str_contains(implode('', $o), 'Comando desconocido'), 'argumento inexistente falla limpio');
+
+    // alias-vs-alias: 'add' también declarado por Eco
+    write_file($proj . '/src/Commands/Eco.php', str_replace(
+        "    public function run(): void",
+        "    public static function aliases(): array { return ['add']; }\n    public function run(): void",
+        (string) file_get_contents($proj . '/src/Commands/Eco.php')
+    ));
+    $o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain list 2>&1', $o, $c5);
+    eq(1, $c5); ok(str_contains(implode('', $o), 'Conflicto de alias'), 'guard alias duplicado con ambos dueños');
+
+    // alias-vs-clase ajena: 'eco' declarado por Toolbox está prohibido; usar un tercero
+    write_file($proj . '/src/Commands/Ladro.php', "<?php\n\nnamespace Commands;\n\nclass Ladro implements \\Interfaces\\CommandInterface\n{\n    public static function describe(): string { return 'ladrador'; }\n    public static function aliases(): array { return ['eco']; }\n    public function run(): void {}\n}\n");
+    write_file($proj . '/src/Commands/Eco.php', str_replace("    public static function aliases(): array { return ['add']; }\n", '', (string) file_get_contents($proj . '/src/Commands/Eco.php')));
+    $o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain 2>&1', $o, $c6);
+    eq(1, $c6); ok(str_contains(implode('', $o), 'colisiona con el comando'), 'guard alias que roba nombre de clase');
+
+    rrmdir($proj);
+    rrmdir($core);
+});
+
+Harness::it('bin nuevo sin el motor: los aliases del motor son comando desconocido', function () {
+    $repo = $GLOBALS['g8_repo'];
+    $core = g7_core('0.1.0');
+    $proj = tmpdir('proj');
+
+    (new InstallCommand(new Console()))->run([$proj, '--toolbox=' . $repo, '--core-dir=' . $core, '--yes']);
+    (new AddCommand(new Console()))->run(['commands:cli', '--root=' . $proj, '--toolbox=' . $repo, '--yes']);
+
+    $o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain catalog 2>&1', $o, $c);
+    eq(1, $c); ok(str_contains(implode('', $o), 'Comando desconocido'), 'sin Commands\\Toolbox no hay delegación');
+
+    rrmdir($proj);
+    rrmdir($core);
+});