release(commands): v0.2.6

packages/commands/duckbrain.json

@@ -1,6 +1,6 @@
 {
     "name": "commands",
-    "version": "0.2.5",
+    "version": "0.2.6",
     "description": "CLI y migraciones para Duckbrain",
     "components": {
         "cli": {

packages/commands/src/Commands/Toolbox.php

@@ -25,7 +25,7 @@ class Toolbox implements CommandInterface
     public static function aliases(): array
     {
         return [
-            'add', 'remove', 'update', 'list', 'doctor', 'catalog', 'adopt',
+            'add', 'remove', 'update', 'list', 'doctor', 'catalog', 'adopt', 'commands',
             'help', '--help', '-h', '--version', '-V',
         ];
     }

packages/commands/src/Toolbox/Cli.php

@@ -5,6 +5,7 @@ namespace Toolbox;
 use Toolbox\Commands\AddCommand;
 use Toolbox\Commands\AdoptCommand;
 use Toolbox\Commands\CatalogCommand;
+use Toolbox\Commands\CommandsCommand;
 use Toolbox\Commands\DoctorCommand;
 use Toolbox\Commands\InstallCommand;
 use Toolbox\Commands\ListCommand;
@@ -24,6 +25,7 @@ final class Cli
         'doctor'  => DoctorCommand::class,
         'catalog' => CatalogCommand::class,
         'adopt'   => AdoptCommand::class,
+        'commands' => CommandsCommand::class,
         'self-update' => SelfUpdateCommand::class,
     ];
 

packages/commands/src/Toolbox/Commands/AdoptCommand.php

@@ -78,6 +78,7 @@ final class AdoptCommand extends Command
                     'toolbox_commit' => null,
                     'mode'           => 'copy',
                     'origin'         => $hasLocal ? 'local' : 'adopted',
+                    'description'    => $package->descriptionOf($component->name),
                     'files'          => $files,
                 ]);
 

packages/commands/src/Toolbox/Commands/CommandsCommand.php

@@ -0,0 +1,125 @@
+<?php
+
+namespace Toolbox\Commands;
+
+use Toolbox\Lock;
+use Toolbox\Ownership;
+
+/**
+ * Superficie ejecutable del proyecto: comandos en src/Commands con sus
+ * aliases, descripciones y origen. A diferencia del despachador del bin,
+ * las colisiones de alias aquí se REPORTAN (marcadas con !) y no abortan.
+ */
+final class CommandsCommand extends Command
+{
+    public static function describe(): string
+    {
+        return 'Lista los comandos disponibles del proyecto';
+    }
+
+    public function run(array $args): int
+    {
+        $parsed = $this->parse($args);
+        $root   = $this->root($parsed['options']);
+
+        $autoload = $root . '/autoload.php';
+        if (!defined('ROOT_CORE') && is_file($autoload)) {
+            $previous = getcwd();
+            chdir($root);
+            try {
+                include_once $autoload;
+            } catch (\Throwable) {
+                // el proyecto no arranca: se lista sin clases cargables
+            }
+            if ($previous !== false) {
+                chdir($previous);
+            }
+        }
+
+        $coreDir = defined('ROOT_CORE') ? rtrim(ROOT_CORE, '/') : $root . '/src';
+        $dir     = $coreDir . '/Commands';
+
+        if (!is_dir($dir)) {
+            $this->console->out('El proyecto no tiene comandos en src/Commands.');
+            return 0;
+        }
+
+        $lock      = Lock::load($root);
+        $ownership = Ownership::fromLock($lock);
+
+        $info        = [];
+        $aliasOwners = [];
+
+        foreach (glob($dir . '/*.php') as $file) {
+            $base  = basename($file, '.php');
+            $class = 'Commands\\' . $base;
+
+            if (!class_exists($class, true) || !is_a($class, 'Interfaces\\CommandInterface', true)) {
+                continue;
+            }
+
+            $aliases = method_exists($class, 'aliases') ? $class::aliases() : [];
+            foreach ($aliases as $alias) {
+                $aliasOwners[strtolower((string) $alias)][] = $class;
+            }
+
+            $owner  = $ownership->ownerOf('src/Commands/' . $base . '.php');
+            $origin = 'proyecto';
+            if ($owner === 'core') {
+                $origin = 'core';
+            } elseif ($owner !== null) {
+                $origin = $owner . '@' . ($lock->component($owner)['version'] ?? '?');
+            }
+
+            $info[$base] = [
+                'class'   => $class,
+                'describe' => $class::describe(),
+                'aliases' => $aliases,
+                'origin'  => $origin,
+            ];
+        }
+
+        $collisions = [];
+        foreach ($aliasOwners as $alias => $owners) {
+            $uniq = array_unique($owners);
+            if (count($uniq) > 1) {
+                $collisions[$alias] = $uniq;
+            }
+        }
+
+        foreach ($info as $base => $row) {
+            foreach ($row['aliases'] as $alias) {
+                $aKey = strtolower((string) $alias);
+                foreach (array_keys($info) as $other) {
+                    if (strtolower($other) !== $aKey || $other === $base) {
+                        continue;
+                    }
+                    $owners = array_values(array_unique([...($collisions[$aKey] ?? []), $row['class'], $info[$other]['class']]));
+                    $collisions[$aKey] = $owners;
+                }
+            }
+        }
+
+        $rows = [['COMANDO', 'ALIASES', 'DESCRIPCIÓN', 'ORIGEN']];
+        foreach ($info as $base => $row) {
+            $marks = [];
+            foreach ($row['aliases'] as $alias) {
+                $marks[] = (isset($collisions[strtolower((string) $alias)]) ? $alias . '!' : (string) $alias);
+            }
+            $marked = $marks === [] ? '—' : implode(', ', $marks);
+            if ($marked !== '—' && isset($collisions[strtolower($base)])) {
+                $marked .= ' !';
+            }
+
+            $rows[] = [strtolower($base), $marked, $row['describe'], $row['origin']];
+        }
+
+        $this->console->table($rows);
+
+        foreach ($collisions as $alias => $owners) {
+            $this->console->warn("alias '{$alias}' declarado o robado por: " . implode(', ', $owners));
+        }
+
+        return 0;
+    }
+}

packages/commands/src/Toolbox/Commands/ListCommand.php

@@ -19,15 +19,21 @@ final class ListCommand extends Command
         $toolbox   = $this->toolboxDir($parsed['options']);
         $installer = new Installer($root, $toolbox, $this->console, $this->rootCore($parsed['options'], $root));
 
-        $rows = [['TIPO', 'ID', 'VERSIÓN', 'MODO']];
+        $rows = [['TIPO', 'ID', 'VERSIÓN', 'MODO', 'DESCRIPCIÓN']];
 
         $core = $installer->lock()->core();
         if ($core !== null) {
-            $rows[] = ['core', 'core', (string) ($core['version'] ?? '?'), 'copy'];
+            $rows[] = ['core', 'core', (string) ($core['version'] ?? '?'), 'copy', ''];
         }
 
         foreach ($installer->lock()->components() as $id => $entry) {
-            $rows[] = [$entry['package'], $id, $entry['version'], $entry['mode']];
+            $rows[] = [
+                $entry['package'],
+                $id,
+                $entry['version'],
+                $entry['mode'],
+                $entry['description'] ?? '—',
+            ];
         }
 
         if (count($rows) === 1) {

packages/commands/src/Toolbox/Config.php

@@ -8,7 +8,7 @@ namespace Toolbox;
  */
 final class Config
 {
-    public const VERSION = '0.2.5';
+    public const VERSION = '0.2.6';
 
     public static function toolboxUrl(): string
     {

packages/commands/src/Toolbox/Installer.php

@@ -157,6 +157,7 @@ final class Installer
                     'version'        => $version,
                     'toolbox_commit' => $commit,
                     'mode'           => $mode,
+                    'description'    => $manifest->descriptionOf($componentName),
                     'files'          => $result['files'],
                 ]);
             }

packages/commands/src/Toolbox/Lock.php

@@ -50,6 +50,7 @@ final class Lock
                 'toolbox_commit' => $entry['toolbox_commit'] ?? null,
                 'mode'           => (string) ($entry['mode'] ?? 'copy'),
                 'origin'         => (string) ($entry['origin'] ?? 'toolbox'),
+                'description'    => $entry['description'] ?? null,
                 'files'          => is_array($entry['files'] ?? null) ? $entry['files'] : [],
             ];
         }

tests/group3_state_test.php

@@ -100,3 +100,52 @@ Harness::it('destino explícito sobreescribe la regla', function () {
     $dest = Destination::relative('src/Libs/Crypto.php', '/proj', '/proj/src', ['src/Libs/Crypto.php' => 'elsewhere/Crypto.php']);
     eq('elsewhere/Crypto.php', $dest);
 });
+
+Harness::it('el lock persiste la descripción y tolera locks sin el campo', function () {
+    $dir = tmpdir();
+    $lock = Lock::empty();
+    $lock->setComponent('db:sql', [
+        'package'     => 'db',
+        'version'     => '1.0.0',
+        'mode'        => 'copy',
+        'description' => 'SQL',
+        'files'       => [],
+    ]);
+    $lock->save($dir);
+
+    eq('SQL', Lock::load($dir)->component('db:sql')['description'], 'roundtrip de description');
+
+    $raw = json_decode((string) file_get_contents($dir . '/.duckbrain/lock.json'), true);
+    unset($raw['components']['db:sql']['description']);
+    file_put_contents($dir . '/.duckbrain/lock.json', json_encode($raw));
+
+    eq(null, Lock::load($dir)->component('db:sql')['description'], 'lock antiguo sin campo se lee tolerante');
+
+    rrmdir($dir);
+});
+
+Harness::it('add captura la descripción efectiva del catálogo en el lock', function () {
+    $root = tmpdir('proj');
+    $tool = tmpdir('tool');
+    write_file($tool . '/packages/mix/duckbrain.json', json_encode([
+        'name'        => 'mix',
+        'version'     => '1.0.0',
+        'description' => 'Descripción del paquete',
+        'components'  => [
+            'own' => ['files' => ['src/Libs/Own.php'], 'description' => 'Descripción propia'],
+            'inh' => ['files' => ['src/Libs/Inh.php']],
+        ],
+        'default' => ['own', 'inh'],
+    ]));
+    write_file($tool . '/packages/mix/src/Libs/Own.php', "<?php\n");
+    write_file($tool . '/packages/mix/src/Libs/Inh.php', "<?php\n");
+
+    (new Toolbox\Installer($root, $tool, new Toolbox\Console()))->add(['mix'], ['yes' => true]);
+
+    $lock = Lock::load($root);
+    eq('Descripción propia', $lock->component('mix:own')['description'], 'propia gana en el lock');
+    eq('Descripción del paquete', $lock->component('mix:inh')['description'], 'sin propia, hereda del paquete');
+
+    rrmdir($root);
+    rrmdir($tool);
+});

tests/group8_project_cli_test.php

@@ -130,3 +130,80 @@ Harness::it('bin nuevo sin el motor: los aliases del motor son comando desconoci
     rrmdir($proj);
     rrmdir($core);
 });
+
+Harness::it('list muestra la descripción del lock por componente, con — si falta', function () {
+    $root = tmpdir('proj');
+    $tool = tmpdir('tool');
+    write_file($tool . '/packages/mix/duckbrain.json', json_encode([
+        'name'        => 'mix',
+        'version'     => '1.0.0',
+        'description' => 'Descripción del paquete',
+        'components'  => [
+            'own' => ['files' => ['src/Libs/Own.php'], 'description' => 'Descripción propia'],
+            'inh' => ['files' => ['src/Libs/Inh.php']],
+            'old' => ['files' => ['src/Libs/Old.php']],
+        ],
+        'default' => ['own', 'inh', 'old'],
+    ]));
+    foreach (['Own', 'Inh', 'Old'] as $c) {
+        write_file($tool . "/packages/mix/src/Libs/{$c}.php", "<?php\n");
+    }
+
+    (new Toolbox\Installer($root, $tool, new Console()))->add(['mix'], ['yes' => true]);
+
+    // simular lock viejo: quitar la descripción de `old`
+    $raw = json_decode((string) file_get_contents($root . '/.duckbrain/lock.json'), true);
+    unset($raw['components']['mix:old']['description']);
+    file_put_contents($root . '/.duckbrain/lock.json', json_encode($raw));
+
+    $out  = fopen('php://memory', 'rw');
+    $code = (new Toolbox\Commands\ListCommand(new Console($out)))->run(['--root=' . $root, '--toolbox=' . $tool]);
+    rewind($out);
+    $text = (string) stream_get_contents($out);
+
+    eq(0, $code);
+    ok((bool) preg_match('/mix:own.*Descripción propia/', $text), 'fila propia con su descripción');
+    ok((bool) preg_match('/mix:inh.*Descripción del paquete/', $text), 'fila heredada con la del paquete');
+    ok((bool) preg_match('/mix:old.*—/', $text), 'lock viejo sin campo muestra —');
+
+    rrmdir($root);
+    rrmdir($tool);
+});
+
+Harness::it('commands lista la superficie con origen y reporta 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', 'commands:toolbox', '--root=' . $proj, '--toolbox=' . $repo, '--yes']);
+
+    $eco = "<?php\n\nnamespace Commands;\n\nclass Eco implements \\Interfaces\\CommandInterface\n{\n    public static function describe(): string { return 'eco local'; }\n    public static function aliases(): array { return ['hola']; }\n    public function run(): void {}\n}\n";
+    write_file($proj . '/src/Commands/Eco.php', $eco);
+
+    // sin colisión: funciona desde el bin del proyecto
+    $o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain commands 2>&1', $o, $code);
+    eq(0, $code, 'bin del proyecto sirve commands');
+    $text = implode("\n", $o);
+    ok(str_contains($text, 'eco') && str_contains($text, 'hola'), 'comando propio con su alias');
+    ok(str_contains($text, 'proyecto'), 'origen proyecto');
+    ok(str_contains($text, 'commands:migration@'), 'origen componente@versión desde el lock');
+
+    // con colisión (roba el nombre de clase migration): el motor REPORTA, el bin aborta
+    write_file($proj . '/src/Commands/Eco.php', str_replace("['hola']", "['migration']", $eco));
+
+    $out  = fopen('php://memory', 'rw');
+    $code = (new Toolbox\Commands\CommandsCommand(new Console($out, $out)))->run(['--root=' . $proj]);
+    rewind($out);
+    $text = (string) stream_get_contents($out);
+
+    eq(0, $code, 'la vista no aborta ante colisiones');
+    ok(str_contains($text, 'migration!'), 'fila marcada con !');
+    ok(str_contains($text, "WARN: alias 'migration'"), 'warn con los dueños');
+
+    $o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain list 2>&1', $o, $c2);
+    eq(1, $c2, 'el despachador sí aborta ante colisión (guard del bin)');
+
+    rrmdir($proj);
+    rrmdir($core);
+});