kj/duckbrain-toolbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

feat(cli): pure alias-based dispatcher in project bin; Commands\Toolbox entry point; describe() required on CommandInterface

Browse Source 
BREAKING: project commands implementing CommandInterface must define
static describe(): string (intentional, forces documentation).
This commit is contained in:
kj
2026-10-06 15:14:33 -03:00
parent 5eb019726a
commit c2931245bb
7 changed files with 257 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/commands/duckbrain
+95 -25
View File
@@ -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).
require_once './autoload.php';
/**
* @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;
}
}
return $classes;
}
/**
* @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;
}
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;
}
$classes = project_commands();
$map = alias_map($classes);
$command = $argv[1] ?? null;
$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);
if ($command === null) {
$rev = [];
foreach ($map as $alias => $class) {
$rev[$class][] = $alias;
}
exit((new Toolbox\Cli())->run($argv));
foreach ($classes as $base => $class) {
$line = ' ' . strtolower($base);
if (($rev[$class] ?? []) !== []) {
$line .= ', ' . implode(', ', $rev[$class]);
}
fwrite(STDOUT, $line . ' — ' . $class::describe() . "\n");
}
// Comandos propios del proyecto, despachados desde ROOT_CORE/Commands.
$coreCommand = 'Commands\\' . ucfirst($command);
if (!class_exists($coreCommand) && !file_exists(ROOT_CORE . '/Commands/' . ucfirst($command) . '.php')) {
fwrite(STDERR, "Invalid command.\n");
exit(1);
exit(0);
}
$cli = new $coreCommand();
$direct = 'Commands\\' . ucfirst($command);
$class = null;
$slice = 2;
if ($cli instanceof Interfaces\CommandInterface) {
call_user_func_array([$cli, 'run'], array_slice($argv, 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
+2 -1
View File
@@ -27,7 +27,8 @@
},
"toolbox": {
"files": [
"src/Toolbox"
"src/Toolbox",
"src/Commands/Toolbox.php"
],
"description": "Gestor de addons dentro del propio proyecto",
"core": "none"
packages/commands/src/Commands/Migration.php
+5
View File
@@ -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
+39
View File
@@ -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',
'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
+6
View File
@@ -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;
}
tests/group7_commands_test.php
+16
View File
@@ -262,3 +262,19 @@ Harness::it('el catálogo describe cada componente con su texto propio o heredad
rrmdir($toolbox);
rrmdir($proj);
});
Harness::it('un comando del proyecto sin describe() no carga (interfaz estricta)', function () {
$proj = tmpdir('proj');
mkdir($proj . '/src/Commands', 0777, true);
write_file($proj . '/autoload.php', "<?php\nspl_autoload_register(function (string \$c): void {\n \$f = \$c === 'Commands\\\\SinDoc' ? ROOT_CORE . '/Commands/SinDoc.php' : null;\n if (\$f !== null && is_file(\$f)) { require \$f; }\n});\ndefine('ROOT_CORE', __DIR__ . '/src');\ndefine('ROOT_DIR', __DIR__);\n");
write_file($proj . '/src/Commands/SinDoc.php', "<?php\nnamespace Commands;\nclass SinDoc implements \\Interfaces\\CommandInterface { public function run(): void {} }\n");
write_file($proj . '/src/Interfaces/CommandInterface.php', "<?php\nnamespace Interfaces;\ninterface CommandInterface { public function run(): void; public static function describe(): string; }\n");
$out = [];
$code = 0;
exec('cd ' . escapeshellarg($proj) . ' && php -r \'require "autoload.php"; class_exists("Commands\\\\SinDoc") ? print("loaded") : print("missing");\' 2>&1', $out, $code);
ok($code !== 0 || str_contains(implode('', $out), 'Fatal'), 'la carga de un comando sin describe produce error fatal');
rrmdir($proj);
});
tests/group8_project_cli_test.php
+58
View File
@@ -72,3 +72,61 @@ Harness::it('la actualización del motor surte efecto en la siguiente invocació
rrmdir($proj);
rrmdir($core);
});
Harness::it('el bin despacha por clase, alias, usage y guard de colisiones', function () {
$repo = $GLOBALS['g8_repo'];
$core = g7_core('0.1.0');
$proj = tmpdir('proj');
(new InstallCommand(new Console()))->run([$proj, '--toolbox=' . $repo, '--core-dir=' . $core, '--yes']);
(new AddCommand(new Console()))->run(['commands:cli', 'commands:toolbox', '--root=' . $proj, '--toolbox=' . $repo, '--yes']);
write_file($proj . '/src/Commands/Eco.php', "<?php\n\nnamespace Commands;\n\nclass Eco implements \\Interfaces\\CommandInterface\n{\n public static function describe(): string { return 'Comando eco de prueba'; }\n public function run(): void { echo 'ECO_OK' . PHP_EOL; }\n}\n");
$o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain eco 2>&1', $o, $c1);
eq(0, $c1); ok(str_contains(implode('', $o), 'ECO_OK'), 'dispatch por nombre de clase');
$o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain list 2>&1', $o, $c2);
eq(0, $c2); ok(str_contains(implode('', $o), 'commands:cli'), 'dispatch por alias del motor');
$o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain 2>&1', $o, $c3);
eq(0, $c3); $usage = implode('', $o);
ok(str_contains($usage, 'eco') && str_contains($usage, 'Comando eco de prueba'), 'usage lista clase y describe');
ok(str_contains($usage, 'toolbox, add'), 'usage lista aliases del entry del motor');
$o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain noexiste 2>&1', $o, $c4);
eq(1, $c4); ok(str_contains(implode('', $o), 'Comando desconocido'), 'argumento inexistente falla limpio');
// alias-vs-alias: 'add' también declarado por Eco
write_file($proj . '/src/Commands/Eco.php', str_replace(
" public function run(): void",
" public static function aliases(): array { return ['add']; }\n public function run(): void",
(string) file_get_contents($proj . '/src/Commands/Eco.php')
));
$o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain list 2>&1', $o, $c5);
eq(1, $c5); ok(str_contains(implode('', $o), 'Conflicto de alias'), 'guard alias duplicado con ambos dueños');
// alias-vs-clase ajena: 'eco' declarado por Toolbox está prohibido; usar un tercero
write_file($proj . '/src/Commands/Ladro.php', "<?php\n\nnamespace Commands;\n\nclass Ladro implements \\Interfaces\\CommandInterface\n{\n public static function describe(): string { return 'ladrador'; }\n public static function aliases(): array { return ['eco']; }\n public function run(): void {}\n}\n");
write_file($proj . '/src/Commands/Eco.php', str_replace(" public static function aliases(): array { return ['add']; }\n", '', (string) file_get_contents($proj . '/src/Commands/Eco.php')));
$o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain 2>&1', $o, $c6);
eq(1, $c6); ok(str_contains(implode('', $o), 'colisiona con el comando'), 'guard alias que roba nombre de clase');
rrmdir($proj);
rrmdir($core);
});
Harness::it('bin nuevo sin el motor: los aliases del motor son comando desconocido', function () {
$repo = $GLOBALS['g8_repo'];
$core = g7_core('0.1.0');
$proj = tmpdir('proj');
(new InstallCommand(new Console()))->run([$proj, '--toolbox=' . $repo, '--core-dir=' . $core, '--yes']);
(new AddCommand(new Console()))->run(['commands:cli', '--root=' . $proj, '--toolbox=' . $repo, '--yes']);
$o = []; exec('cd ' . escapeshellarg($proj) . ' && php duckbrain catalog 2>&1', $o, $c);
eq(1, $c); ok(str_contains(implode('', $o), 'Comando desconocido'), 'sin Commands\\Toolbox no hay delegación');
rrmdir($proj);
rrmdir($core);
});