From 4014551aae7a92d67ab997644c3a15d486d6f2d6 Mon Sep 17 00:00:00 2001 From: kj Date: Tue, 6 Oct 2026 15:37:15 -0300 Subject: [PATCH] feat(cli): lock captures effective description; list shows it; new commands surface view with origin and collision reporting --- packages/commands/src/Commands/Toolbox.php | 2 +- packages/commands/src/Toolbox/Cli.php | 2 + .../src/Toolbox/Commands/AdoptCommand.php | 1 + .../src/Toolbox/Commands/CommandsCommand.php | 125 ++++++++++++++++++ .../src/Toolbox/Commands/ListCommand.php | 12 +- packages/commands/src/Toolbox/Installer.php | 1 + packages/commands/src/Toolbox/Lock.php | 1 + tests/group3_state_test.php | 49 +++++++ tests/group8_project_cli_test.php | 77 +++++++++++ 9 files changed, 266 insertions(+), 4 deletions(-) create mode 100644 packages/commands/src/Toolbox/Commands/CommandsCommand.php diff --git a/packages/commands/src/Commands/Toolbox.php b/packages/commands/src/Commands/Toolbox.php index 7e67e71..3e2117f 100644 --- a/packages/commands/src/Commands/Toolbox.php +++ b/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', ]; } diff --git a/packages/commands/src/Toolbox/Cli.php b/packages/commands/src/Toolbox/Cli.php index 25504d0..a8f7f66 100644 --- a/packages/commands/src/Toolbox/Cli.php +++ b/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, ]; diff --git a/packages/commands/src/Toolbox/Commands/AdoptCommand.php b/packages/commands/src/Toolbox/Commands/AdoptCommand.php index eee076d..735cdd1 100644 --- a/packages/commands/src/Toolbox/Commands/AdoptCommand.php +++ b/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, ]); diff --git a/packages/commands/src/Toolbox/Commands/CommandsCommand.php b/packages/commands/src/Toolbox/Commands/CommandsCommand.php new file mode 100644 index 0000000..a1c6240 --- /dev/null +++ b/packages/commands/src/Toolbox/Commands/CommandsCommand.php @@ -0,0 +1,125 @@ +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; + } +} diff --git a/packages/commands/src/Toolbox/Commands/ListCommand.php b/packages/commands/src/Toolbox/Commands/ListCommand.php index d6b4779..7a400ab 100644 --- a/packages/commands/src/Toolbox/Commands/ListCommand.php +++ b/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) { diff --git a/packages/commands/src/Toolbox/Installer.php b/packages/commands/src/Toolbox/Installer.php index 450cd87..ad62895 100644 --- a/packages/commands/src/Toolbox/Installer.php +++ b/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'], ]); } diff --git a/packages/commands/src/Toolbox/Lock.php b/packages/commands/src/Toolbox/Lock.php index 04d2808..52ea330 100644 --- a/packages/commands/src/Toolbox/Lock.php +++ b/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'] : [], ]; } diff --git a/tests/group3_state_test.php b/tests/group3_state_test.php index 55ae4c5..51b98b2 100644 --- a/tests/group3_state_test.php +++ b/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', "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); +}); diff --git a/tests/group8_project_cli_test.php b/tests/group8_project_cli_test.php index 4dc099d..3bf11a4 100644 --- a/tests/group8_project_cli_test.php +++ b/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", "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 = "&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); +});