theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/commands/sesiones.md

@@ -0,0 +1,345 @@
+---
+description: Administra el historial de sesiones de Theus, los alias y los metadatos de sesión.
+---
+
+# Comando Sesiones
+
+Administra el historial de sesiones de Theus — lista, carga, crea alias y edita las sesiones almacenadas en `~/.theus/arsenal/session-data/`, con lecturas heredadas desde `~/.theus/arsenal/sessions/`.
+
+## Uso
+
+`/sesiones [list|load|alias|info|help] [opciones]`
+
+## Acciones
+
+### Listar sesiones
+
+Muestra todas las sesiones con metadatos, filtrado y paginación.
+
+Usa `/sesiones info` cuando necesites contexto de superficie de operador para un enjambre: rama, ruta del worktree y recencia de la sesión.
+
+```bash
+/sesiones                              # Listar todas las sesiones (por defecto)
+/sesiones list                         # Igual que lo anterior
+/sesiones list --limit 10              # Mostrar 10 sesiones
+/sesiones list --date 2026-02-01       # Filtrar por fecha
+/sesiones list --search abc            # Buscar por ID de sesión
+```
+
+**Script:**
+```bash
+node -e "
+// Ruta del plugin, sustituida por el motor de Theus al cargar el comando
+const _r = '${THEUS_PLUGIN_ROOT}';
+const sm = require(_r + '/scripts/lib/session-manager');
+const aa = require(_r + '/scripts/lib/session-aliases');
+const path = require('path');
+
+const result = sm.getAllSessions({ limit: 20 });
+const aliases = aa.listAliases();
+const aliasMap = {};
+for (const a of aliases) aliasMap[a.sessionPath] = a.name;
+
+console.log('Sesiones (mostrando ' + result.sessions.length + ' de ' + result.total + '):');
+console.log('');
+console.log('ID        Fecha       Hora     Rama         Worktree           Alias');
+console.log('────────────────────────────────────────────────────────────────────');
+
+for (const s of result.sessions) {
+  const alias = aliasMap[s.filename] || '';
+  const metadata = sm.parseSessionMetadata(sm.getSessionContent(s.sessionPath));
+  const id = s.shortId === 'no-id' ? '(ninguno)' : s.shortId.slice(0, 8);
+  const time = s.modifiedTime.toTimeString().slice(0, 5);
+  const branch = (metadata.branch || '-').slice(0, 12);
+  const worktree = metadata.worktree ? path.basename(metadata.worktree).slice(0, 18) : '-';
+
+  console.log(id.padEnd(8) + ' ' + s.date + '  ' + time + '   ' + branch.padEnd(12) + ' ' + worktree.padEnd(18) + ' ' + alias);
+}
+"
+```
+
+### Cargar sesión
+
+Carga y muestra el contenido de una sesión (por ID o alias).
+
+```bash
+/sesiones load <id|alias>             # Cargar sesión
+/sesiones load 2026-02-01             # Por fecha (para sesiones sin id)
+/sesiones load a1b2c3d4               # Por ID corto
+/sesiones load mi-alias               # Por nombre de alias
+```
+
+**Script:**
+```bash
+node -e "
+// Ruta del plugin, sustituida por el motor de Theus al cargar el comando
+const _r = '${THEUS_PLUGIN_ROOT}';
+const sm = require(_r + '/scripts/lib/session-manager');
+const aa = require(_r + '/scripts/lib/session-aliases');
+const id = process.argv[1];
+
+// Primero intenta resolverlo como alias
+const resolved = aa.resolveAlias(id);
+const sessionId = resolved ? resolved.sessionPath : id;
+
+const session = sm.getSessionById(sessionId, true);
+if (!session) {
+  console.log('Sesión no encontrada: ' + id);
+  process.exit(1);
+}
+
+const stats = sm.getSessionStats(session.sessionPath);
+const size = sm.getSessionSize(session.sessionPath);
+const aliases = aa.getAliasesForSession(session.filename);
+
+console.log('Sesión: ' + session.filename);
+console.log('Ruta: ' + session.sessionPath);
+console.log('');
+console.log('Estadísticas:');
+console.log('  Líneas: ' + stats.lineCount);
+console.log('  Ítems totales: ' + stats.totalItems);
+console.log('  Completados: ' + stats.completedItems);
+console.log('  En progreso: ' + stats.inProgressItems);
+console.log('  Tamaño: ' + size);
+console.log('');
+
+if (aliases.length > 0) {
+  console.log('Alias: ' + aliases.map(a => a.name).join(', '));
+  console.log('');
+}
+
+if (session.metadata.title) {
+  console.log('Título: ' + session.metadata.title);
+  console.log('');
+}
+
+if (session.metadata.started) {
+  console.log('Inicio: ' + session.metadata.started);
+}
+
+if (session.metadata.lastUpdated) {
+  console.log('Última actualización: ' + session.metadata.lastUpdated);
+}
+
+if (session.metadata.project) {
+  console.log('Proyecto: ' + session.metadata.project);
+}
+
+if (session.metadata.branch) {
+  console.log('Rama: ' + session.metadata.branch);
+}
+
+if (session.metadata.worktree) {
+  console.log('Worktree: ' + session.metadata.worktree);
+}
+" "$ARGUMENTS"
+```
+
+### Crear alias
+
+Crea un alias fácil de recordar para una sesión.
+
+```bash
+/sesiones alias <id> <nombre>              # Crear alias
+/sesiones alias 2026-02-01 trabajo-de-hoy  # Crear alias llamado "trabajo-de-hoy"
+```
+
+**Script:**
+```bash
+node -e "
+// Ruta del plugin, sustituida por el motor de Theus al cargar el comando
+const _r = '${THEUS_PLUGIN_ROOT}';
+const sm = require(_r + '/scripts/lib/session-manager');
+const aa = require(_r + '/scripts/lib/session-aliases');
+
+const sessionId = process.argv[1];
+const aliasName = process.argv[2];
+
+if (!sessionId || !aliasName) {
+  console.log('Uso: /sesiones alias <id> <nombre>');
+  process.exit(1);
+}
+
+// Obtiene el nombre de archivo de la sesión
+const session = sm.getSessionById(sessionId);
+if (!session) {
+  console.log('Sesión no encontrada: ' + sessionId);
+  process.exit(1);
+}
+
+const result = aa.setAlias(aliasName, session.filename);
+if (result.success) {
+  console.log('✓ Alias creado: ' + aliasName + ' → ' + session.filename);
+} else {
+  console.log('✗ Error: ' + result.error);
+  process.exit(1);
+}
+" "$ARGUMENTS"
+```
+
+### Eliminar alias
+
+Borra un alias existente.
+
+```bash
+/sesiones alias --remove <nombre>       # Eliminar alias
+/sesiones unalias <nombre>              # Igual que lo anterior
+```
+
+**Script:**
+```bash
+node -e "
+// Ruta del plugin, sustituida por el motor de Theus al cargar el comando
+const _r = '${THEUS_PLUGIN_ROOT}';
+const aa = require(_r + '/scripts/lib/session-aliases');
+
+const aliasName = process.argv[1];
+if (!aliasName) {
+  console.log('Uso: /sesiones alias --remove <nombre>');
+  process.exit(1);
+}
+
+const result = aa.deleteAlias(aliasName);
+if (result.success) {
+  console.log('✓ Alias eliminado: ' + aliasName);
+} else {
+  console.log('✗ Error: ' + result.error);
+  process.exit(1);
+}
+" "$ARGUMENTS"
+```
+
+### Información de sesión
+
+Muestra información detallada de una sesión.
+
+```bash
+/sesiones info <id|alias>              # Mostrar detalles de la sesión
+```
+
+**Script:**
+```bash
+node -e "
+// Ruta del plugin, sustituida por el motor de Theus al cargar el comando
+const _r = '${THEUS_PLUGIN_ROOT}';
+const sm = require(_r + '/scripts/lib/session-manager');
+const aa = require(_r + '/scripts/lib/session-aliases');
+
+const id = process.argv[1];
+const resolved = aa.resolveAlias(id);
+const sessionId = resolved ? resolved.sessionPath : id;
+
+const session = sm.getSessionById(sessionId, true);
+if (!session) {
+  console.log('Sesión no encontrada: ' + id);
+  process.exit(1);
+}
+
+const stats = sm.getSessionStats(session.sessionPath);
+const size = sm.getSessionSize(session.sessionPath);
+const aliases = aa.getAliasesForSession(session.filename);
+
+console.log('Información de la sesión');
+console.log('════════════════════════');
+console.log('ID:          ' + (session.shortId === 'no-id' ? '(ninguno)' : session.shortId));
+console.log('Archivo:     ' + session.filename);
+console.log('Fecha:       ' + session.date);
+console.log('Modificado:  ' + session.modifiedTime.toISOString().slice(0, 19).replace('T', ' '));
+console.log('Proyecto:    ' + (session.metadata.project || '-'));
+console.log('Rama:        ' + (session.metadata.branch || '-'));
+console.log('Worktree:    ' + (session.metadata.worktree || '-'));
+console.log('');
+console.log('Contenido:');
+console.log('  Líneas:        ' + stats.lineCount);
+console.log('  Ítems totales: ' + stats.totalItems);
+console.log('  Completados:   ' + stats.completedItems);
+console.log('  En progreso:   ' + stats.inProgressItems);
+console.log('  Tamaño:        ' + size);
+if (aliases.length > 0) {
+  console.log('Alias:       ' + aliases.map(a => a.name).join(', '));
+}
+" "$ARGUMENTS"
+```
+
+### Listar alias
+
+Muestra todos los alias de sesiones.
+
+```bash
+/sesiones aliases                      # Listar todos los alias
+```
+
+**Script:**
+```bash
+node -e "
+// Ruta del plugin, sustituida por el motor de Theus al cargar el comando
+const _r = '${THEUS_PLUGIN_ROOT}';
+const aa = require(_r + '/scripts/lib/session-aliases');
+
+const aliases = aa.listAliases();
+console.log('Alias de sesiones (' + aliases.length + '):');
+console.log('');
+
+if (aliases.length === 0) {
+  console.log('No se encontraron alias.');
+} else {
+  console.log('Nombre        Archivo de sesión               Título');
+  console.log('─────────────────────────────────────────────────────────────');
+  for (const a of aliases) {
+    const name = a.name.padEnd(12);
+    const file = (a.sessionPath.length > 30 ? a.sessionPath.slice(0, 27) + '...' : a.sessionPath).padEnd(30);
+    const title = a.title || '';
+    console.log(name + ' ' + file + ' ' + title);
+  }
+}
+"
+```
+
+## Notas de operador
+
+- Los archivos de sesión persisten `Proyecto`, `Rama` y `Worktree` en la cabecera para que `/sesiones info` pueda desambiguar ejecuciones paralelas en tmux/worktrees.
+- Para un monitoreo estilo centro de comando, combina `/sesiones info` con `git diff --stat`.
+
+## Argumentos
+
+$ARGUMENTS:
+- `list [opciones]` - Listar sesiones
+  - `--limit <n>` - Máximo de sesiones a mostrar (por defecto: 50)
+  - `--date <YYYY-MM-DD>` - Filtrar por fecha
+  - `--search <patrón>` - Buscar en el ID de sesión
+- `load <id|alias>` - Cargar el contenido de una sesión
+- `alias <id> <nombre>` - Crear un alias para una sesión
+- `alias --remove <nombre>` - Eliminar un alias
+- `unalias <nombre>` - Igual que `--remove`
+- `info <id|alias>` - Mostrar estadísticas de la sesión
+- `aliases` - Listar todos los alias
+- `help` - Mostrar esta ayuda
+
+## Ejemplos
+
+```bash
+# Listar todas las sesiones
+/sesiones list
+
+# Crear un alias para la sesión de hoy
+/sesiones alias 2026-02-01 hoy
+
+# Cargar sesión por alias
+/sesiones load hoy
+
+# Mostrar información de la sesión
+/sesiones info hoy
+
+# Eliminar alias
+/sesiones alias --remove hoy
+
+# Listar todos los alias
+/sesiones aliases
+```
+
+## Notas
+
+- Las sesiones se almacenan como archivos markdown en `~/.theus/arsenal/session-data/`, con lecturas heredadas desde `~/.theus/arsenal/sessions/`
+- Los alias se almacenan en `~/.theus/arsenal/session-aliases.json`
+- Los ID de sesión pueden acortarse (los primeros 4-8 caracteres suelen ser suficientemente únicos)
+- Usa alias para las sesiones que referencias con frecuencia

package/vendor/theus-arsenal/commands/test-cpp.md

@@ -0,0 +1,252 @@
+---
+description: Aplica el flujo TDD en C++. Escribe primero tests con GoogleTest, luego implementa. Verifica cobertura con gcov/lcov.
+argument-hint: [descripción de la funcionalidad a implementar]
+---
+
+# Comando TDD para C++
+
+Este comando aplica la metodología de desarrollo guiado por tests (TDD) para código C++ usando GoogleTest/GoogleMock con CMake/CTest. Si se proporciona, `$ARGUMENTS` describe la funcionalidad a implementar.
+
+## Qué hace este comando
+
+1. **Define interfaces**: esboza primero las firmas de clases/funciones
+2. **Escribe tests**: crea casos de prueba GoogleTest exhaustivos (ROJO)
+3. **Ejecuta los tests**: verifica que fallan por la razón correcta
+4. **Implementa el código**: escribe el mínimo código para pasar (VERDE)
+5. **Refactoriza**: mejora manteniendo los tests en verde
+6. **Comprueba cobertura**: asegura 80%+ de cobertura
+
+## Cuándo usarlo
+
+Usa `/test-cpp` cuando:
+- Implementas funciones o clases nuevas en C++
+- Añades cobertura de tests a código existente
+- Corriges bugs (primero escribe el test que falla)
+- Construyes lógica de negocio crítica
+- Estás aprendiendo el flujo TDD en C++
+
+## Ciclo TDD
+
+```
+ROJO       → Escribir un test GoogleTest que falla
+VERDE      → Implementar el mínimo código para pasar
+REFACTOR   → Mejorar el código, los tests siguen en verde
+REPETIR    → Siguiente caso de prueba
+```
+
+## Sesión de ejemplo
+
+````
+Usuario: /test-cpp Necesito una función que valide direcciones de correo
+
+Agente:
+# Sesión TDD: validador de correo
+
+## Paso 1: Definir la interfaz
+
+```cpp
+// validator/email.hpp
+#pragma once
+#include <string>
+#include <expected>
+
+enum class EmailError {
+    Empty,
+    InvalidFormat
+};
+
+std::expected<void, EmailError> validate_email(const std::string& email);
+```
+
+## Paso 2: Escribir los tests (ROJO)
+
+```cpp
+// validator/email_test.cpp
+#include <gtest/gtest.h>
+#include "email.hpp"
+
+TEST(ValidateEmail, AceptaCorreoSimple) {
+    auto result = validate_email("user@example.com");
+    EXPECT_TRUE(result.has_value());
+}
+
+TEST(ValidateEmail, AceptaSubdominio) {
+    EXPECT_TRUE(validate_email("user@mail.example.com").has_value());
+}
+
+TEST(ValidateEmail, AceptaSignoMas) {
+    EXPECT_TRUE(validate_email("user+tag@example.com").has_value());
+}
+
+TEST(ValidateEmail, RechazaVacio) {
+    auto result = validate_email("");
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), EmailError::Empty);
+}
+
+TEST(ValidateEmail, RechazaSinArroba) {
+    EXPECT_FALSE(validate_email("userexample.com").has_value());
+}
+
+TEST(ValidateEmail, RechazaSinDominio) {
+    EXPECT_FALSE(validate_email("user@").has_value());
+}
+
+TEST(ValidateEmail, RechazaSinParteLocal) {
+    EXPECT_FALSE(validate_email("@example.com").has_value());
+}
+```
+
+## Paso 3: Ejecutar los tests — verificar el FALLO
+
+```bash
+$ cmake --build build && ctest --test-dir build --output-on-failure
+
+1/1 Test #1: email_validator_test .....***Failed
+    --- undefined reference to `validate_email`
+
+FAIL
+```
+
+✓ Los tests fallan como se esperaba (sin implementar).
+
+## Paso 4: Implementar el mínimo código (VERDE)
+
+```cpp
+// validator/email.cpp
+#include "email.hpp"
+#include <regex>
+
+std::expected<void, EmailError> validate_email(const std::string& email) {
+    if (email.empty()) {
+        return std::unexpected(EmailError::Empty);
+    }
+    static const std::regex pattern(R"([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})");
+    if (!std::regex_match(email, pattern)) {
+        return std::unexpected(EmailError::InvalidFormat);
+    }
+    return {};
+}
+```
+
+## Paso 5: Ejecutar los tests — verificar el PASE
+
+```bash
+$ cmake --build build && ctest --test-dir build --output-on-failure
+
+1/1 Test #1: email_validator_test .....   Passed    0.01 sec
+
+100% tests passed.
+```
+
+✓ ¡Todos los tests pasan!
+
+## Paso 6: Comprobar cobertura
+
+```bash
+$ cmake -DCMAKE_CXX_FLAGS="--coverage" -B build && cmake --build build
+$ ctest --test-dir build
+$ lcov --capture --directory build --output-file coverage.info
+$ lcov --list coverage.info
+
+validator/email.cpp     | 100%
+```
+
+✓ Cobertura: 100%
+
+## ¡TDD completado!
+````
+
+## Patrones de test
+
+### Tests básicos
+```cpp
+TEST(NombreSuite, NombreTest) {
+    EXPECT_EQ(add(2, 3), 5);
+    EXPECT_NE(result, nullptr);
+    EXPECT_TRUE(is_valid);
+    EXPECT_THROW(func(), std::invalid_argument);
+}
+```
+
+### Fixtures
+```cpp
+class DatabaseTest : public ::testing::Test {
+protected:
+    void SetUp() override { db_ = create_test_db(); }
+    void TearDown() override { db_.reset(); }
+    std::unique_ptr<Database> db_;
+};
+
+TEST_F(DatabaseTest, InsertaRegistro) {
+    db_->insert("key", "value");
+    EXPECT_EQ(db_->get("key"), "value");
+}
+```
+
+### Tests parametrizados
+```cpp
+class PrimeTest : public ::testing::TestWithParam<std::pair<int, bool>> {};
+
+TEST_P(PrimeTest, CompruebaPrimalidad) {
+    auto [input, expected] = GetParam();
+    EXPECT_EQ(is_prime(input), expected);
+}
+
+INSTANTIATE_TEST_SUITE_P(Primes, PrimeTest, ::testing::Values(
+    std::make_pair(2, true),
+    std::make_pair(4, false),
+    std::make_pair(7, true)
+));
+```
+
+## Comandos de cobertura
+
+```bash
+# Build con cobertura
+cmake -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_EXE_LINKER_FLAGS="--coverage" -B build
+
+# Ejecutar tests
+cmake --build build && ctest --test-dir build
+
+# Generar informe de cobertura
+lcov --capture --directory build --output-file coverage.info
+lcov --remove coverage.info '/usr/*' --output-file coverage.info
+genhtml coverage.info --output-directory coverage_html
+```
+
+## Objetivos de cobertura
+
+| Tipo de código | Objetivo |
+|----------------|----------|
+| Lógica de negocio crítica | 100% |
+| APIs públicas | 90%+ |
+| Código general | 80%+ |
+| Código generado | Excluir |
+
+## Buenas prácticas de TDD
+
+**SÍ:**
+- Escribir el test PRIMERO, antes de cualquier implementación
+- Ejecutar los tests tras cada cambio
+- Preferir `EXPECT_*` (continúa) sobre `ASSERT_*` (detiene) cuando corresponda
+- Testear comportamiento, no detalles de implementación
+- Incluir casos límite (vacío, nulo, valores máximos, condiciones de frontera)
+
+**NO:**
+- Escribir la implementación antes que los tests
+- Saltarse la fase ROJA
+- Testear métodos privados directamente (testear a través de la API pública)
+- Usar `sleep` en tests
+- Ignorar tests inestables (flaky)
+
+## Comandos relacionados
+
+- `/build-cpp` — corregir errores de build
+- `/revisar-cpp` — revisar el código tras la implementación
+- Skill `skills/bucle-verificacion/` — bucle de verificación completo
+
+## Relacionados
+
+- Skill: `skills/testing-cpp/`
+- Skill: `skills/flujo-tdd/`