release(commands): v0.2.6

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

README.org

@@ -65,7 +65,7 @@ por el componente que pides; los metadatos del paquete no se instalan.
 El instalador global arranca un proyecto desde cero y no necesita nada previo:
 
 #+BEGIN_SRC sh
-git clone git@git.kj2.me:kj/duckbrain-toolbox.git
+git clone https://git.kj2.me/kj/duckbrain-toolbox.git
 ln -s "$PWD/duckbrain-toolbox/bin/duckbrain" ~/.local/bin/duckbrain
 
 duckbrain install mi-proyecto     # descarga el núcleo Duckbrain
@@ -131,7 +131,7 @@ duckbrain update --dry-run   # muestra el plan sin escribir
 
 - =list=: core y componentes instalados con versión y modo.
 - =doctor=: matriz de compatibilidad, sin efectos secundarios.
-- =catalog=: paquetes y componentes disponibles.
+- =catalog=: paquetes y componentes disponibles, cada uno con su descripción.
 - =adopt=: registra copias hechas a mano en proyectos antiguos.
 
 * Manifiesto =duckbrain.json=
@@ -278,15 +278,15 @@ Hay *dos* sistemas de versión y no hay que confundirlos:
 
 =make help= lista los objetivos:
 
-| Objetivo     | Qué hace                                                                                  |
-|--------------+-------------------------------------------------------------------------------------------|
-| =make test=    | Corre la suite (=php tests/run.php=). En verde antes de commitear.                          |
-| =make build=   | Genera =dist/duckbrain.phar= + =dist/duckbrain.phar.sha256=.                                  |
+| Objetivo     | Qué hace                                                                                                               |
+|--------------+------------------------------------------------------------------------------------------------------------------------|
+| =make test=    | Corre la suite (=php tests/run.php=). En verde antes de commitear.                                                       |
+| =make build=   | Genera =dist/duckbrain.phar= + =dist/duckbrain.phar.sha256=.                                                               |
 | =make compat=  | Barrido de compatibilidad contra el core real (=scripts/compat-sweep=); requiere red. =ARGS="--only pkg"= para un paquete. |
-| =make release= | Asistente interactivo de releases de paquetes (=ARGS="pkg minor --yes"= para modo directo). |
-| =make publish= | =build= + publica la release =v$(Config::VERSION)= con los assets. Requiere =FORGEJO_TOKEN=.    |
-| =make check=   | =self-update --check= contra el servidor: =actual/disponible=, exit 1 si hay nuevo.           |
-| =make clean=   | Borra =dist/=.                                                                              |
+| =make release= | Asistente interactivo de releases de paquetes (=ARGS="pkg minor --yes"= para modo directo).                              |
+| =make publish= | =build= + publica la release =v$(Config::VERSION)= con los assets. Requiere =FORGEJO_TOKEN=.                                 |
+| =make check=   | =self-update --check= contra el servidor: =actual/disponible=, exit 1 si hay nuevo.                                        |
+| =make clean=   | Borra =dist/=.                                                                                                           |
 
 El token para publicar es un token personal de la API de Forgejo
 (*Ajustes → Aplicaciones*, scope =write:repository=, con caducidad y revocable).

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

packages/commands/duckbrain.json

@@ -1,13 +1,15 @@
 {
     "name": "commands",
-    "version": "0.2.1",
+    "version": "0.2.6",
     "description": "CLI y migraciones para Duckbrain",
     "components": {
         "cli": {
             "files": [
                 "duckbrain",
                 "src/Interfaces/CommandInterface.php"
-            ]
+            ],
+            "description": "CLI del proyecto (binario duckbrain)",
+            "core": "none"
         },
         "migration": {
             "files": [
@@ -20,12 +22,16 @@
             "core": {
                 "requires": ">=0.1",
                 "tested": "0.1"
-            }
+            },
+            "description": "Migraciones de base de datos (mysql/pgsql/sqlite)"
         },
         "toolbox": {
             "files": [
-                "src/Toolbox"
-            ]
+                "src/Toolbox",
+                "src/Commands/Toolbox.php"
+            ],
+            "description": "Gestor de addons dentro del propio proyecto",
+            "core": "none"
         }
     },
     "default": [

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', 'commands',
+            '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;
 }

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/CatalogCommand.php

@@ -31,7 +31,7 @@ final class CatalogCommand extends Command
                     $first ? $package->name . ' (' . $package->version . ')' : '',
                     $name,
                     $installed,
-                    $first ? $package->description : '',
+                    $package->descriptionOf($name) ?? '',
                 ];
                 $first = false;
             }

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/DoctorCommand.php

@@ -33,17 +33,19 @@ final class DoctorCommand extends Command
         foreach ($lock->components() as $id => $entry) {
             [$package, $component] = array_pad(explode(':', $id, 2), 2, null);
 
-            $requires = null;
-            $tested   = null;
+            $requires    = null;
+            $tested      = null;
+            $independent = false;
             if ($component !== null && $package !== null && $catalog->has($package)) {
                 $manifest = $catalog->get($package);
                 if ($manifest->hasComponent($component)) {
-                    $requires = $manifest->coreRequirement($component);
-                    $tested   = $manifest->testedCore($component);
+                    $requires    = $manifest->coreRequirement($component);
+                    $tested      = $manifest->testedCore($component);
+                    $independent = $manifest->coreIndependent($component);
                 }
             }
 
-            $result = Compatibility::evaluateCore($coreVersion, $requires, $tested);
+            $result = Compatibility::evaluateCore($coreVersion, $requires, $tested, $independent);
 
             $rows[] = [
                 $id,

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/Compatibility.php

@@ -12,6 +12,7 @@ final class Compatibility
     public const UNTESTED = 'untested';
     public const INSUFFICIENT = 'insufficient';
     public const UNKNOWN = 'unknown';
+    public const INDEPENDENT = 'independent';
 
     /**
      * @return array{status:string, message:string}
@@ -19,8 +20,13 @@ final class Compatibility
     public static function evaluateCore(
         ?string $coreVersion,
         ?string $requires,
-        ?string $tested
+        ?string $tested,
+        bool $independent = false
     ): array {
+        if ($independent) {
+            return ['status' => self::INDEPENDENT, 'message' => 'independiente del core'];
+        }
+
         if ($coreVersion === null) {
             return ['status' => self::UNKNOWN, 'message' => 'versión del core desconocida (sin tags)'];
         }
@@ -68,10 +74,11 @@ final class Compatibility
     public static function label(string $status): string
     {
         return match ($status) {
-            self::OK          => 'OK',
-            self::UNTESTED    => 'NO PROBADO',
-            self::INSUFFICIENT => 'INSUFICIENTE',
-            default           => 'SIN DATOS',
+            self::OK              => 'OK',
+            self::UNTESTED        => 'NO PROBADO',
+            self::INSUFFICIENT    => 'INSUFICIENTE',
+            self::INDEPENDENT     => 'INDEPENDIENTE',
+            default               => 'SIN DATOS',
         };
     }
 }

packages/commands/src/Toolbox/Component.php

@@ -15,8 +15,11 @@ final class Component
         public readonly array $requires = [],
         public readonly ?string $coreRequires = null,
         public readonly ?string $coreTested = null,
+        public readonly ?string $description = null,
         public readonly ?array $destinations = null,
         public readonly bool $override = false,
+        public readonly bool $coreDeclared = false,
+        public readonly ?bool $coreIndependent = null,
     ) {
     }
 
@@ -51,14 +54,62 @@ final class Component
             }
         }
 
+        $description = null;
+        if (isset($data['description'])) {
+            if (!is_string($data['description'])) {
+                throw new ToolboxException("El componente '{$name}' tiene un 'description' inválido");
+            }
+
+            $description = $data['description'];
+        }
+
+        $coreDeclared   = array_key_exists('core', $data);
+        $coreIndependent = null;
+        $coreRequires    = null;
+        $coreTested      = null;
+        if ($coreDeclared) {
+            [$coreRequires, $coreTested, $coreIndependent] = self::parseCore($data['core'], "el componente '{$name}'");
+        }
+
         return new self(
             name: $name,
             files: array_values($data['files']),
             requires: $requires,
-            coreRequires: $data['core']['requires'] ?? null,
-            coreTested: $data['core']['tested'] ?? null,
+            coreRequires: $coreRequires,
+            coreTested: $coreTested,
+            description: $description,
             destinations: $destinations,
             override: (bool) ($data['override'] ?? false),
+            coreDeclared: $coreDeclared,
+            coreIndependent: $coreIndependent,
         );
     }
+
+    /**
+     * Bloque `core`: objeto de rango ({requires?, tested?}) o la cadena
+     * "none" (independencia afirmativa, excluyente con el rango).
+     *
+     * @return array{0: ?string, 1: ?string, 2: ?bool}
+     */
+    public static function parseCore(mixed $core, string $origin): array
+    {
+        if ($core === 'none') {
+            return [null, null, true];
+        }
+
+        if (!is_array($core)) {
+            throw new ToolboxException("{$origin} tiene un 'core' inválido");
+        }
+
+        $requires = $core['requires'] ?? null;
+        $tested   = $core['tested'] ?? null;
+
+        foreach (['requires' => $requires, 'tested' => $tested] as $key => $value) {
+            if ($value !== null && !is_string($value)) {
+                throw new ToolboxException("{$origin} tiene un 'core.{$key}' inválido");
+            }
+        }
+
+        return [$requires, $tested, null];
+    }
 }

packages/commands/src/Toolbox/Config.php

@@ -8,18 +8,18 @@ namespace Toolbox;
  */
 final class Config
 {
-    public const VERSION = '0.2.1';
+    public const VERSION = '0.2.6';
 
     public static function toolboxUrl(): string
     {
         return self::env('DUCKBRAIN_TOOLBOX_URL')
-            ?: 'git@git.kj2.me:kj/duckbrain-toolbox.git';
+            ?: 'https://git.kj2.me/kj/duckbrain-toolbox.git';
     }
 
     public static function coreUrl(): string
     {
         return self::env('DUCKBRAIN_CORE_URL')
-            ?: 'git@git.kj2.me:kj/duckbrain.git';
+            ?: 'https://git.kj2.me/kj/duckbrain.git';
     }
 
     /**

packages/commands/src/Toolbox/Installer.php

@@ -111,10 +111,11 @@ final class Installer
             $compat = Compatibility::evaluateCore(
                 $this->coreVersion(),
                 $manifest->coreRequirement($componentName),
-                $manifest->testedCore($componentName)
+                $manifest->testedCore($componentName),
+                $manifest->coreIndependent($componentName)
             );
 
-            if ($compat['status'] !== Compatibility::OK) {
+            if (!in_array($compat['status'], [Compatibility::OK, Compatibility::INDEPENDENT], true)) {
                 $warnings[] = $id . ': ' . $compat['message'];
                 $assumeYes  = (bool) ($options['yes'] ?? false);
                 if (!$assumeYes && !$this->console->confirm("  {$id}: {$compat['message']}. ¿Continuar?", false)) {
@@ -156,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'] : [],
             ];
         }

packages/commands/src/Toolbox/Manifest.php

@@ -18,6 +18,7 @@ final class Manifest
         public readonly ?string $coreTested,
         public readonly ?string $php,
         public readonly array $postInstall,
+        public readonly ?bool $coreIndependent = null,
     ) {
     }
 
@@ -83,16 +84,23 @@ final class Manifest
             $postInstall[] = $command;
         }
 
+        $coreRequires = $coreTested = null;
+        $coreIndependent = null;
+        if (array_key_exists('core', $data)) {
+            [$coreRequires, $coreTested, $coreIndependent] = Component::parseCore($data['core'], "el manifiesto '{$origin}'");
+        }
+
         return new self(
             name: $name,
             version: $version,
             description: is_string($data['description'] ?? null) ? $data['description'] : '',
             components: $components,
             default: $default,
-            coreRequires: $data['core']['requires'] ?? null,
-            coreTested: $data['core']['tested'] ?? null,
+            coreRequires: $coreRequires,
+            coreTested: $coreTested,
             php: is_string($data['php'] ?? null) ? $data['php'] : null,
             postInstall: $postInstall,
+            coreIndependent: $coreIndependent,
         );
     }
 
@@ -140,21 +148,49 @@ final class Manifest
         return $this->default;
     }
 
-    public function coreRequirement(?string $component = null): ?string
+    /**
+     * Bloque de core efectivo: si el componente declara `core` (rango o
+     * "none") ese bloque gana por completo; si no, hereda el del paquete.
+     *
+     * @return array{requires: ?string, tested: ?string, independent: ?bool}
+     */
+    private function coreBlock(?string $component): array
     {
         if ($component !== null) {
-            return $this->component($component)->coreRequires ?? $this->coreRequires;
+            $c = $this->component($component);
+            if ($c->coreDeclared) {
+                return ['requires' => $c->coreRequires, 'tested' => $c->coreTested, 'independent' => $c->coreIndependent];
+            }
         }
 
-        return $this->coreRequires;
+        return ['requires' => $this->coreRequires, 'tested' => $this->coreTested, 'independent' => $this->coreIndependent];
+    }
+
+    public function coreRequirement(?string $component = null): ?string
+    {
+        return $this->coreBlock($component)['requires'];
     }
 
     public function testedCore(?string $component = null): ?string
+    {
+        return $this->coreBlock($component)['tested'];
+    }
+
+    public function coreIndependent(?string $component = null): bool
+    {
+        return $this->coreBlock($component)['independent'] === true;
+    }
+
+    /**
+     * Descripcion efectiva: la propia del componente o, en su ausencia, la del
+     * paquete (mismo patrón de herencia que los rangos de core).
+     */
+    public function descriptionOf(?string $component = null): ?string
     {
         if ($component !== null) {
-            return $this->component($component)->coreTested ?? $this->coreTested;
+            return $this->component($component)->description ?? $this->description;
         }
 
-        return $this->coreTested;
+        return $this->description;
     }
 }

packages/crypto/duckbrain.json

@@ -1,13 +1,35 @@
 {
-  "name": "crypto",
-  "version": "0.1.0",
-  "description": "Criptografía y segundo factor (Crypto, Nonce, TwoFactorAuthenticator)",
-  "core": { "requires": ">=0.1", "tested": "0.1" },
-  "php": ">=8.1",
-  "components": {
-    "crypto": { "files": ["src/Libs/Crypto.php"] },
-    "nonce": { "files": ["src/Libs/Nonce.php"] },
-    "twoFactor": { "files": ["src/Libs/TwoFactorAuthenticator.php"] }
-  },
-  "default": ["crypto", "nonce", "twoFactor"]
+    "name": "crypto",
+    "version": "0.1.1",
+    "description": "Criptograf\u00eda y segundo factor (Crypto, Nonce, TwoFactorAuthenticator)",
+    "core": {
+        "requires": ">=0.1",
+        "tested": "0.1"
+    },
+    "php": ">=8.1",
+    "components": {
+        "crypto": {
+            "files": [
+                "src/Libs/Crypto.php"
+            ],
+            "description": "Cifrado sim\u00e9trico con salida hex/base64"
+        },
+        "nonce": {
+            "files": [
+                "src/Libs/Nonce.php"
+            ],
+            "description": "Generaci\u00f3n y verificaci\u00f3n de tokens de un solo uso"
+        },
+        "twoFactor": {
+            "files": [
+                "src/Libs/TwoFactorAuthenticator.php"
+            ],
+            "description": "TOTP compatible con Google Authenticator"
+        }
+    },
+    "default": [
+        "crypto",
+        "nonce",
+        "twoFactor"
+    ]
 }

packages/htmx/duckbrain.json

@@ -1,17 +1,32 @@
 {
-  "name": "htmx",
-  "version": "0.1.0",
-  "description": "Motor de vistas basado en componentes y HTMX",
-  "core": { "requires": ">=0.1", "tested": "0.1" },
-  "php": ">=8.1",
-  "components": {
-    "htmlComponent": {
-      "files": ["src/Libs/HTMLComponent.php", "src/Libs/Sanitizer"]
+    "name": "htmx",
+    "version": "0.1.1",
+    "description": "Motor de vistas basado en componentes y HTMX",
+    "core": {
+        "requires": ">=0.1",
+        "tested": "0.1"
     },
-    "htmx": {
-      "files": ["src/Libs/HTMX.php"],
-      "require": { "htmx:htmlComponent": ">=0.1" }
-    }
-  },
-  "default": ["htmlComponent", "htmx"]
+    "php": ">=8.1",
+    "components": {
+        "htmlComponent": {
+            "files": [
+                "src/Libs/HTMLComponent.php",
+                "src/Libs/Sanitizer"
+            ],
+            "description": "Motor de vistas por componentes"
+        },
+        "htmx": {
+            "files": [
+                "src/Libs/HTMX.php"
+            ],
+            "require": {
+                "htmx:htmlComponent": ">=0.1"
+            },
+            "description": "Detecci\u00f3n y fragmentos de peticiones HTMX"
+        }
+    },
+    "default": [
+        "htmlComponent",
+        "htmx"
+    ]
 }

packages/http/duckbrain.json

@@ -1,6 +1,6 @@
 {
     "name": "http",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "description": "Utilidades HTTP (CurlRequest, Aria2, Proxy, CompreFace)",
     "core": {
         "requires": ">=0.1",
@@ -11,7 +11,8 @@
         "curlRequest": {
             "files": [
                 "src/Libs/CurlRequest.php"
-            ]
+            ],
+            "description": "Cliente HTTP sobre cURL con cabeceras y c\u00f3digo de estado"
         },
         "aria2": {
             "files": [
@@ -20,7 +21,8 @@
             "core": {
                 "requires": ">=0.1",
                 "tested": "0.1"
-            }
+            },
+            "description": "Cliente JSON-RPC de aria2 (cola de descargas)"
         },
         "proxy": {
             "files": [
@@ -29,7 +31,8 @@
             "core": {
                 "requires": ">=0.1",
                 "tested": "0.1"
-            }
+            },
+            "description": "Proxy HTML con filtros de respuesta"
         },
         "compreFace": {
             "files": [
@@ -41,7 +44,8 @@
             "core": {
                 "requires": ">=0.1",
                 "tested": "0.1"
-            }
+            },
+            "description": "Cliente de la API CompreFace (reconocimiento facial)"
         }
     },
     "default": [

packages/test/duckbrain.json

@@ -1,6 +1,6 @@
 {
     "name": "test",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "description": "Kit de pruebas PHPUnit para Duckbrain",
     "core": {
         "requires": ">=0.1",
@@ -15,7 +15,8 @@
             ],
             "require": {
                 "commands:migration": ">=0.1"
-            }
+            },
+            "description": "Kit de pruebas PHPUnit para el proyecto"
         }
     },
     "default": [

packages/text/duckbrain.json

@@ -1,12 +1,28 @@
 {
-  "name": "text",
-  "version": "0.1.0",
-  "description": "Filtros y reemplazos de texto (Filter, Replacement)",
-  "core": { "requires": ">=0.1", "tested": "0.1" },
-  "php": ">=8.1",
-  "components": {
-    "filter": { "files": ["src/Libs/Filter.php"] },
-    "replacement": { "files": ["src/Libs/Replacement.php"] }
-  },
-  "default": ["filter", "replacement"]
+    "name": "text",
+    "version": "0.1.1",
+    "description": "Filtros y reemplazos de texto (Filter, Replacement)",
+    "core": {
+        "requires": ">=0.1",
+        "tested": "0.1"
+    },
+    "php": ">=8.1",
+    "components": {
+        "filter": {
+            "files": [
+                "src/Libs/Filter.php"
+            ],
+            "description": "Filtros de contenido extensibles por contexto y prioridad"
+        },
+        "replacement": {
+            "files": [
+                "src/Libs/Replacement.php"
+            ],
+            "description": "B\u00fasqueda y reemplazo de patrones sobre contenido"
+        }
+    },
+    "default": [
+        "filter",
+        "replacement"
+    ]
 }

tests/group10_release_test.php

@@ -162,3 +162,31 @@ Harness::it('build-phar genera un phar ejecutable con su sha256', function () {
 
     rrmdir($dist);
 });
+
+Harness::it('el phar resuelve su catálogo embebido y su raíz sin --toolbox', function () {
+    $repo = $GLOBALS['g10_repo'];
+    $dist = tmpdir('dist');
+
+    exec('DUCKBRAIN_DIST=' . escapeshellarg($dist) . ' bash ' . escapeshellarg($repo . '/scripts/build-phar') . ' 2>&1', $out, $code);
+    eq(0, $code, 'build-phar termina bien');
+
+    $phar = $dist . '/duckbrain.phar';
+
+    // Ejecutado desde $dist (cwd sin packages/), sin --toolbox: la raíz debe
+    // resolverse al propio phar y el catálogo debe leerse bajo phar://.
+    $lines = [];
+    exec('cd ' . escapeshellarg($dist) . ' && php ' . escapeshellarg($phar) . ' catalog 2>&1', $lines, $ccode);
+    eq(0, $ccode, 'catalog desde el phar termina bien');
+    $text = implode("\n", $lines);
+    ok(str_contains($text, 'commands'), 'descubre paquetes embebidos bajo phar://');
+    ok(str_contains($text, 'curlRequest'), 'los componentes embebidos aparecen sin flags');
+
+    // Alta de un componente desde el catálogo embebido, sin --toolbox.
+    $proj = $dist . '/proj';
+    $lines2 = [];
+    exec('cd ' . escapeshellarg($dist) . ' && php ' . escapeshellarg($phar) . ' add id --root=' . escapeshellarg($proj) . ' --yes 2>&1', $lines2, $acode);
+    eq(0, $acode, 'add desde el phar sin --toolbox');
+    ok(is_file($proj . '/src/Libs/Ulid.php'), 'el archivo del componente quedó instalado');
+
+    rrmdir($dist);
+});

tests/group11_compat_stamps_test.php

@@ -9,9 +9,9 @@ $GLOBALS['g11_repo'] = dirname(__DIR__);
 /**
  * Contratos:
  *  - levels.json debe cubrir exactamente los componentes del catalogo.
- *  - si tests/compat/report.json existe, todo 'tested' declarado debe estar
- *    respaldado por un 'ok' del reporte, y los niveles 'none' no deben
- *    declarar tested.
+ *  - si tests/compat/report.json existe: todo 'tested' declarado debe estar
+ *    respaldado por un 'ok' del reporte, y el nivel 'none' de evidencia debe
+ *    coincidir con la declaracion 'core: none' del manifiesto (bidireccional).
  * Sin reporte (entorno offline sin haber corrido el barrido) solo se exige el
  * primer contrato.
  */
@@ -51,19 +51,25 @@ Harness::it('los stamps tested estan respaldados por el reporte del barrido', fu
     $report = json_decode((string) file_get_contents($reportPath), true);
     ok(is_array($report) && isset($report['components']), 'report.json valido');
 
-    $levels   = json_decode((string) file_get_contents($repo . '/tests/compat/levels.json'), true);
-    $catalog  = Catalog::fromRoot($repo);
+    $levels  = json_decode((string) file_get_contents($repo . '/tests/compat/levels.json'), true);
+    $catalog = Catalog::fromRoot($repo);
 
     foreach ($catalog->packages() as $manifest) {
         foreach (array_keys($manifest->components()) as $component) {
-            $id      = $manifest->name . ':' . $component;
-            $level   = $levels[$manifest->name][$component] ?? null;
-            $level   = is_array($level) ? $level['level'] : $level;
-            $status  = $report['components'][$id]['status'] ?? 'missing';
-            $tested  = $manifest->testedCore($component);
+            $id        = $manifest->name . ':' . $component;
+            $level     = $levels[$manifest->name][$component] ?? null;
+            $level     = is_array($level) ? $level['level'] : $level;
+            $status    = $report['components'][$id]['status'] ?? 'missing';
+            $tested    = $manifest->testedCore($component);
+            $independ  = $manifest->coreIndependent($component);
 
             if ($level === 'none') {
-                eq(null, $tested, "$id esta deliberadamente sin datos y no debe declarar tested");
+                ok($independ, "$id esta sin evidencia de barrido y debe declarar core none");
+            }
+
+            if ($independ) {
+                eq('none', $level, "$id se declara independiente y su nivel debe ser none");
+                eq(null, $tested, "$id independiente no puede declarar tested");
                 continue;
             }
 

tests/group12_config_test.php

@@ -0,0 +1,18 @@
+<?php
+
+use Toolbox\Config;
+
+Harness::suite('group12');
+
+Harness::it('los defaults de lectura son HTTPS anónimos y los env ganan', function () {
+    putenv('DUCKBRAIN_TOOLBOX_URL');
+    putenv('DUCKBRAIN_CORE_URL');
+
+    ok(str_starts_with(Config::toolboxUrl(), 'https://'), 'toolboxUrl por defecto en https');
+    ok(str_starts_with(Config::coreUrl(), 'https://'), 'coreUrl por defecto en https');
+
+    putenv('DUCKBRAIN_CORE_URL=ssh://git@example.test/kj/duckbrain.git');
+    eq('ssh://git@example.test/kj/duckbrain.git', Config::coreUrl(), 'el override gana sobre el default');
+
+    putenv('DUCKBRAIN_CORE_URL');
+});

tests/group2_manifest_test.php

@@ -121,3 +121,61 @@ Harness::it('ciclo de dependencias se detecta', function () {
 
     rrmdir($dir);
 });
+
+Harness::it('la descripcion del componente prevalece y hereda del paquete', function () {
+    $m = Manifest::fromArray([
+        'name'        => 'pkg',
+        'version'     => '1.0.0',
+        'description' => 'Resumen del paquete',
+        'components'  => [
+            'a' => ['files' => ['src/A.php'], 'description' => 'Componente A'],
+            'b' => ['files' => ['src/B.php']],
+        ],
+    ]);
+
+    eq('Componente A', $m->descriptionOf('a'), 'descripción propia gana');
+    eq('Resumen del paquete', $m->descriptionOf('b'), 'sin descripción propia hereda del paquete');
+    eq('Resumen del paquete', $m->descriptionOf(), 'sin componente: la del paquete');
+
+    $m2 = Manifest::fromArray(['name' => 'x', 'version' => '1.0.0', 'components' => ['c' => ['files' => ['c.php']]]]);
+    eq('', $m2->descriptionOf('c'), 'paquete sin texto produce cadena vacía (no null)');
+
+    throws(fn () => Manifest::fromArray([
+        'name'       => 'y',
+        'version'    => '1.0.0',
+        'components' => ['c' => ['files' => ['c.php'], 'description' => 7]],
+    ]), 'description no-string es inválida');
+});
+
+Harness::it('core admite "none" como bloque con herencia completa', function () {
+    $m = Manifest::fromArray([
+        'name'    => 'pkg',
+        'version' => '1.0.0',
+        'core'    => 'none',
+        'components' => [
+            'a' => ['files' => ['src/A.php']],
+            'b' => ['files' => ['src/B.php'], 'core' => ['requires' => '>=0.2', 'tested' => '0.2']],
+        ],
+    ]);
+
+    ok($m->coreIndependent('a'), 'a hereda la independencia del paquete');
+    ok(!$m->coreIndependent('b'), 'b sobreescribe el bloque con su rango');
+    eq('>=0.2', $m->coreRequirement('b'));
+    eq('0.2', $m->testedCore('b'));
+    eq(null, $m->coreRequirement('a'), 'independiente no arrastra rangos');
+
+    $m2 = Manifest::fromArray([
+        'name'    => 'pkg2',
+        'version' => '1.0.0',
+        'core'    => ['requires' => '>=0.1'],
+        'components' => ['c' => ['files' => ['src/C.php'], 'core' => 'none']],
+    ]);
+    ok($m2->coreIndependent('c'), 'componente declara none sobre rango de paquete');
+    eq(null, $m2->coreRequirement('c'), 'el rango del paquete no se filtra al bloque declarado none');
+    eq('>=0.1', $m2->coreRequirement());
+
+    throws(fn () => Manifest::fromArray([
+        'name' => 'bad', 'version' => '1.0.0', 'core' => 'otro',
+        'components' => ['x' => ['files' => ['x.php']]],
+    ]), 'core string distinto de none es inválido');
+});

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/group5_compat_test.php

@@ -66,3 +66,67 @@ Harness::it('doctor no modifica lock ni archivos', function () {
     rrmdir($root);
     rrmdir($tool);
 });
+
+Harness::it('core independiente: sin aviso en add incluso sin core conocido', function () {
+    $root = tmpdir('proj');
+    $tool = tmpdir('tool');
+    write_file($tool . '/packages/http/duckbrain.json', json_encode([
+        'name' => 'http', 'version' => '1.0.0', 'description' => 'HTTP',
+        'core' => 'none',
+        'components' => ['aria2' => ['files' => ['src/Libs/Aria2.php']]],
+    ]));
+    write_file($tool . '/packages/http/src/Libs/Aria2.php', "<?php\n");
+    write_file($root . '/src/Libs/Router.php', "<?php\n");
+
+    $lock = Lock::load($root);
+    $lock->setCore(['version' => null, 'commit' => 'x', 'files' => []]);
+    $lock->save($root);
+
+    $out  = fopen('php://memory', 'rw');
+    $inst = new Toolbox\Installer($root, $tool, new Console($out));
+    $res  = $inst->add(['http:aria2'], []);
+    rewind($out);
+    $text = (string) stream_get_contents($out);
+
+    eq([], $res['warnings'], 'independiente no produce aviso');
+    eq([], $res['aborted'], 'nada se aborta');
+    ok(str_contains(implode(',', $res['installed']), 'http:aria2'), 'instala normal');
+    ok(!str_contains($text, 'sin datos'), 'sin ruido en consola');
+
+    // control: mismo fixture sin declaración sí avisa
+    write_file($tool . '/packages/http/duckbrain.json', json_encode([
+        'name' => 'http', 'version' => '1.0.1', 'description' => 'HTTP',
+        'components' => ['aria2' => ['files' => ['src/Libs/Aria2.php']]],
+    ]));
+    $out2 = fopen('php://memory', 'rw');
+    $res2 = (new Toolbox\Installer($root, $tool, new Console($out2)))->add(['http:aria2'], ['yes' => true]);
+    ok($res2['warnings'] !== [], 'sin declaración sigue avisando');
+
+    rrmdir($root);
+    rrmdir($tool);
+});
+
+Harness::it('doctor muestra independiente sin rangos y sin fallo', function () {
+    $root = tmpdir('proj');
+    $tool = tmpdir('tool');
+    write_file($tool . '/packages/db/duckbrain.json', json_encode([
+        'name' => 'db', 'version' => '1.0.0', 'description' => 'DB',
+        'components' => ['sql' => ['files' => ['src/Libs/Sql.php'], 'core' => 'none']],
+    ]));
+    write_file($tool . '/packages/db/src/Libs/Sql.php', "<?php\n");
+
+    $lock = Lock::load($root);
+    $lock->setCore(['version' => '1.5.0', 'commit' => 'c', 'files' => []]);
+    $lock->setComponent('db:sql', ['package' => 'db', 'version' => '1.0.0', 'mode' => 'copy', 'files' => []]);
+    $lock->save($root);
+
+    $out = fopen('php://memory', 'rw');
+    $code = (new DoctorCommand(new Console($out)))->run(['--root=' . $root, '--toolbox=' . $tool]);
+    rewind($out);
+    $text = (string) stream_get_contents($out);
+
+    eq(0, $code);
+    ok(str_contains($text, 'INDEPENDIENTE'), 'estado independiente visible');
+    rrmdir($root);
+    rrmdir($tool);
+});

tests/group7_commands_test.php

@@ -238,3 +238,43 @@ Harness::it('--force resuelve drift pero no salta avisos de compatibilidad', fun
     rrmdir($proj);
     rrmdir($tool);
 });
+
+Harness::it('el catálogo describe cada componente con su texto propio o heredado', function () {
+    $toolbox = g7_toolbox();
+    $manifest = json_decode((string) file_get_contents($toolbox . '/packages/http/duckbrain.json'), true);
+    $manifest['components']['curlRequest']['description'] = 'Cliente HTTP sobre cURL';
+    write_file($toolbox . '/packages/http/duckbrain.json', json_encode($manifest, JSON_PRETTY_PRINT));
+
+    $proj = tmpdir('proj');
+    $out  = fopen('php://memory', 'rw');
+    $code = (new Toolbox\Commands\CatalogCommand(new Console($out)))->run(
+        ['--root=' . $proj, '--toolbox=' . $toolbox]
+    );
+    rewind($out);
+    $text = (string) stream_get_contents($out);
+
+    eq(0, $code, 'catalog termina bien');
+    ok((bool) preg_match('/curlRequest.*Cliente HTTP sobre cURL/', $text), 'fila propia con su texto');
+    ok((bool) preg_match('/aria2.*Utilidades HTTP/', $text), 'fila sin texto hereda el del paquete');
+    ok((bool) preg_match('/compreFace.*Utilidades HTTP/', $text), 'vecino heredando igual');
+    ok(!preg_match('/aria2.*cURL/', $text), 'los textos no se mezclan entre filas');
+
+    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,138 @@ 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);
+});
+
+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);
+});