test(phar): cubre catálogo embebido y raíz sin --toolbox

README.org

@@ -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.json

@@ -1,35 +1,38 @@
 {
-  "name": "commands",
-  "version": "0.2.0",
-  "description": "CLI y migraciones para Duckbrain",
-  "components": {
-    "cli": {
-      "files": [
-        "duckbrain",
-        "src/Interfaces/CommandInterface.php"
-      ]
+    "name": "commands",
+    "version": "0.2.2",
+    "description": "CLI y migraciones para Duckbrain",
+    "components": {
+        "cli": {
+            "files": [
+                "duckbrain",
+                "src/Interfaces/CommandInterface.php"
+            ],
+            "description": "CLI del proyecto (binario duckbrain)"
+        },
+        "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"
+        }
     },
-    "migration": {
-      "files": [
-        "src/Commands/Migration.php",
-        "src/Libs/Migration.php"
-      ],
-      "require": {
-        "commands:cli": "*"
-      },
-      "core": {
-        "requires": ">=0.1",
-        "tested": "0.1"
-      }
-    },
-    "toolbox": {
-      "files": [
-        "src/Toolbox"
-      ]
-    }
-  },
-  "default": [
-    "cli",
-    "migration"
-  ]
+    "default": [
+        "cli",
+        "migration"
+    ]
 }

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

@@ -15,6 +15,7 @@ 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,
     ) {
@@ -51,12 +52,22 @@ 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'];
+        }
+
         return new self(
             name: $name,
             files: array_values($data['files']),
             requires: $requires,
             coreRequires: $data['core']['requires'] ?? null,
             coreTested: $data['core']['tested'] ?? null,
+            description: $description,
             destinations: $destinations,
             override: (bool) ($data['override'] ?? false),
         );

packages/commands/src/Toolbox/Config.php

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

packages/commands/src/Toolbox/Manifest.php

@@ -157,4 +157,17 @@ final class Manifest
 
         return $this->coreTested;
     }
+
+    /**
+     * 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)->description ?? $this->description;
+        }
+
+        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,28 +1,29 @@
 {
-  "name": "test",
-  "version": "0.1.0",
-  "description": "Kit de pruebas PHPUnit para Duckbrain",
-  "core": {
-    "requires": ">=0.1",
-    "tested": "0.1"
-  },
-  "php": ">=8.1",
-  "components": {
-    "harness": {
-      "files": [
-        "phpunit.xml",
-        "tests"
-      ],
-      "require": {
-        "commands:migration": ">=0.1"
-      }
-    }
-  },
-  "default": [
-    "harness"
-  ],
-  "post-install": [
-    "composer require --dev phpunit/phpunit:^11.0 fakerphp/faker",
-    "composer dump-autoload"
-  ]
+    "name": "test",
+    "version": "0.1.2",
+    "description": "Kit de pruebas PHPUnit para Duckbrain",
+    "core": {
+        "requires": ">=0.1",
+        "tested": "0.1"
+    },
+    "php": ">=8.1",
+    "components": {
+        "harness": {
+            "files": [
+                "phpunit.xml",
+                "tests"
+            ],
+            "require": {
+                "commands:migration": ">=0.1"
+            },
+            "description": "Kit de pruebas PHPUnit para el proyecto"
+        }
+    },
+    "default": [
+        "harness"
+    ],
+    "post-install": [
+        "composer require --dev phpunit/phpunit:^11.0 fakerphp/faker",
+        "composer dump-autoload"
+    ]
 }

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

@@ -121,3 +121,28 @@ 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');
+});

tests/group7_commands_test.php

@@ -238,3 +238,27 @@ 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);
+});