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).

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);
+});