theus-cli 0.2.82 → 0.2.84

package/vendor/theus-arsenal/skills/patrones-laravel/SKILL.md

@@ -1,414 +0,0 @@
----
-name: patrones-laravel
-description: Patrones de arquitectura Laravel — routing/controladores, Eloquent ORM, capas de servicio, colas, eventos, caché y API resources para aplicaciones en producción.
----
-
-# Patrones de desarrollo Laravel
-
-Patrones de arquitectura Laravel de nivel producción para aplicaciones escalables y mantenibles.
-
-## Cuándo usar
-
-- Al construir aplicaciones web o APIs con Laravel
-- Al estructurar controladores, servicios y lógica de dominio
-- Al trabajar con modelos Eloquent y sus relaciones
-- Al diseñar APIs con resources y paginación
-- Al añadir colas, eventos, caché y trabajos en segundo plano
-
-## Cómo funciona
-
-- Estructura la aplicación en torno a límites claros (controladores -> servicios/acciones -> modelos).
-- Usa bindings explícitos y bindings con alcance (scoped) para mantener el routing predecible; aun así aplica autorización para el control de acceso.
-- Prefiere modelos tipados, casts y scopes para mantener la lógica de dominio consistente.
-- Mantén el trabajo intensivo en IO en colas y cachea las lecturas costosas.
-- Centraliza la configuración en `config/*` y mantén los entornos explícitos.
-
-## Ejemplos
-
-### Estructura del proyecto
-
-Usa una distribución Laravel convencional con límites de capa claros (HTTP, servicios/acciones, modelos).
-
-### Distribución recomendada
-
-```
-app/
-├── Actions/            # Casos de uso de propósito único
-├── Console/
-├── Events/
-├── Exceptions/
-├── Http/
-│   ├── Controllers/
-│   ├── Middleware/
-│   ├── Requests/       # Validación con form requests
-│   └── Resources/      # API resources
-├── Jobs/
-├── Models/
-├── Policies/
-├── Providers/
-├── Services/           # Servicios de dominio coordinadores
-└── Support/
-config/
-database/
-├── factories/
-├── migrations/
-└── seeders/
-resources/
-├── views/
-└── lang/
-routes/
-├── api.php
-├── web.php
-└── console.php
-```
-
-### Controladores -> Servicios -> Acciones
-
-Mantén los controladores delgados. Coloca la orquestación en servicios y la lógica de propósito único en acciones.
-
-```php
-final class CreateOrderAction
-{
-    public function __construct(private OrderRepository $orders) {}
-
-    public function handle(CreateOrderData $data): Order
-    {
-        return $this->orders->create($data);
-    }
-}
-
-final class OrdersController extends Controller
-{
-    public function __construct(private CreateOrderAction $createOrder) {}
-
-    public function store(StoreOrderRequest $request): JsonResponse
-    {
-        $order = $this->createOrder->handle($request->toDto());
-
-        return response()->json([
-            'success' => true,
-            'data' => OrderResource::make($order),
-            'error' => null,
-            'meta' => null,
-        ], 201);
-    }
-}
-```
-
-### Routing y controladores
-
-Prefiere el route-model binding y los resource controllers por claridad.
-
-```php
-use Illuminate\Support\Facades\Route;
-
-Route::middleware('auth:sanctum')->group(function () {
-    Route::apiResource('projects', ProjectController::class);
-});
-```
-
-### Route model binding (con alcance)
-
-Usa scoped bindings para prevenir accesos entre tenants.
-
-```php
-Route::scopeBindings()->group(function () {
-    Route::get('/accounts/{account}/projects/{project}', [ProjectController::class, 'show']);
-});
-```
-
-### Rutas anidadas y nombres de binding
-
-- Mantén prefijos y rutas consistentes para evitar doble anidamiento (p. ej., `conversation` vs `conversations`).
-- Usa un solo nombre de parámetro que coincida con el modelo vinculado (p. ej., `{conversation}` para `Conversation`).
-- Prefiere scoped bindings al anidar para hacer cumplir las relaciones padre-hijo.
-
-```php
-use App\Http\Controllers\Api\ConversationController;
-use App\Http\Controllers\Api\MessageController;
-use Illuminate\Support\Facades\Route;
-
-Route::middleware('auth:sanctum')->prefix('conversations')->group(function () {
-    Route::post('/', [ConversationController::class, 'store'])->name('conversations.store');
-
-    Route::scopeBindings()->group(function () {
-        Route::get('/{conversation}', [ConversationController::class, 'show'])
-            ->name('conversations.show');
-
-        Route::post('/{conversation}/messages', [MessageController::class, 'store'])
-            ->name('conversation-messages.store');
-
-        Route::get('/{conversation}/messages/{message}', [MessageController::class, 'show'])
-            ->name('conversation-messages.show');
-    });
-});
-```
-
-Si quieres que un parámetro resuelva a una clase de modelo distinta, define un binding explícito. Para lógica de binding personalizada, usa `Route::bind()` o implementa `resolveRouteBinding()` en el modelo.
-
-```php
-use App\Models\AiConversation;
-use Illuminate\Support\Facades\Route;
-
-Route::model('conversation', AiConversation::class);
-```
-
-### Bindings del contenedor de servicios
-
-Vincula interfaces a implementaciones en un service provider para un cableado de dependencias claro.
-
-```php
-use App\Repositories\EloquentOrderRepository;
-use App\Repositories\OrderRepository;
-use Illuminate\Support\ServiceProvider;
-
-final class AppServiceProvider extends ServiceProvider
-{
-    public function register(): void
-    {
-        $this->app->bind(OrderRepository::class, EloquentOrderRepository::class);
-    }
-}
-```
-
-### Patrones de modelos Eloquent
-
-### Configuración del modelo
-
-```php
-final class Project extends Model
-{
-    use HasFactory;
-
-    protected $fillable = ['name', 'owner_id', 'status'];
-
-    protected $casts = [
-        'status' => ProjectStatus::class,
-        'archived_at' => 'datetime',
-    ];
-
-    public function owner(): BelongsTo
-    {
-        return $this->belongsTo(User::class, 'owner_id');
-    }
-
-    public function scopeActive(Builder $query): Builder
-    {
-        return $query->whereNull('archived_at');
-    }
-}
-```
-
-### Casts personalizados y value objects
-
-Usa enums o value objects para un tipado estricto.
-
-```php
-use Illuminate\Database\Eloquent\Casts\Attribute;
-
-protected $casts = [
-    'status' => ProjectStatus::class,
-];
-```
-
-```php
-protected function budgetCents(): Attribute
-{
-    return Attribute::make(
-        get: fn (int $value) => Money::fromCents($value),
-        set: fn (Money $money) => $money->toCents(),
-    );
-}
-```
-
-### Eager loading para evitar N+1
-
-```php
-$orders = Order::query()
-    ->with(['customer', 'items.product'])
-    ->latest()
-    ->paginate(25);
-```
-
-### Query objects para filtros complejos
-
-```php
-final class ProjectQuery
-{
-    public function __construct(private Builder $query) {}
-
-    public function ownedBy(int $userId): self
-    {
-        $query = clone $this->query;
-
-        return new self($query->where('owner_id', $userId));
-    }
-
-    public function active(): self
-    {
-        $query = clone $this->query;
-
-        return new self($query->whereNull('archived_at'));
-    }
-
-    public function builder(): Builder
-    {
-        return $this->query;
-    }
-}
-```
-
-### Global scopes y soft deletes
-
-Usa global scopes para el filtrado por defecto y `SoftDeletes` para registros recuperables.
-Usa o bien un global scope o bien un scope con nombre para el mismo filtro, no ambos, salvo que busques un comportamiento en capas intencional.
-
-```php
-use Illuminate\Database\Eloquent\SoftDeletes;
-use Illuminate\Database\Eloquent\Builder;
-
-final class Project extends Model
-{
-    use SoftDeletes;
-
-    protected static function booted(): void
-    {
-        static::addGlobalScope('active', function (Builder $builder): void {
-            $builder->whereNull('archived_at');
-        });
-    }
-}
-```
-
-### Query scopes para filtros reutilizables
-
-```php
-use Illuminate\Database\Eloquent\Builder;
-
-final class Project extends Model
-{
-    public function scopeOwnedBy(Builder $query, int $userId): Builder
-    {
-        return $query->where('owner_id', $userId);
-    }
-}
-
-// En un servicio, repositorio, etc.
-$projects = Project::ownedBy($user->id)->get();
-```
-
-### Transacciones para actualizaciones de varios pasos
-
-```php
-use Illuminate\Support\Facades\DB;
-
-DB::transaction(function (): void {
-    $order->update(['status' => 'paid']);
-    $order->items()->update(['paid_at' => now()]);
-});
-```
-
-### Migraciones
-
-### Convención de nombres
-
-- Los nombres de archivo usan timestamps: `YYYY_MM_DD_HHMMSS_create_users_table.php`
-- Las migraciones usan clases anónimas (sin clase con nombre); el nombre del archivo comunica la intención
-- Los nombres de tabla son `snake_case` y en plural por defecto
-
-### Migración de ejemplo
-
-```php
-use Illuminate\Database\Migrations\Migration;
-use Illuminate\Database\Schema\Blueprint;
-use Illuminate\Support\Facades\Schema;
-
-return new class extends Migration
-{
-    public function up(): void
-    {
-        Schema::create('orders', function (Blueprint $table): void {
-            $table->id();
-            $table->foreignId('customer_id')->constrained()->cascadeOnDelete();
-            $table->string('status', 32)->index();
-            $table->unsignedInteger('total_cents');
-            $table->timestamps();
-        });
-    }
-
-    public function down(): void
-    {
-        Schema::dropIfExists('orders');
-    }
-};
-```
-
-### Form requests y validación
-
-Mantén la validación en form requests y transforma las entradas en DTOs.
-
-```php
-use App\Models\Order;
-
-final class StoreOrderRequest extends FormRequest
-{
-    public function authorize(): bool
-    {
-        return $this->user()?->can('create', Order::class) ?? false;
-    }
-
-    public function rules(): array
-    {
-        return [
-            'customer_id' => ['required', 'integer', 'exists:customers,id'],
-            'items' => ['required', 'array', 'min:1'],
-            'items.*.sku' => ['required', 'string'],
-            'items.*.quantity' => ['required', 'integer', 'min:1'],
-        ];
-    }
-
-    public function toDto(): CreateOrderData
-    {
-        return new CreateOrderData(
-            customerId: (int) $this->validated('customer_id'),
-            items: $this->validated('items'),
-        );
-    }
-}
-```
-
-### API resources
-
-Mantén las respuestas de la API consistentes con resources y paginación.
-
-```php
-$projects = Project::query()->active()->paginate(25);
-
-return response()->json([
-    'success' => true,
-    'data' => ProjectResource::collection($projects->items()),
-    'error' => null,
-    'meta' => [
-        'page' => $projects->currentPage(),
-        'per_page' => $projects->perPage(),
-        'total' => $projects->total(),
-    ],
-]);
-```
-
-### Eventos, jobs y colas
-
-- Emite eventos de dominio para los efectos secundarios (correos, analítica)
-- Usa jobs en cola para trabajo lento (reportes, exportaciones, webhooks)
-- Prefiere handlers idempotentes con reintentos y backoff
-
-### Caché
-
-- Cachea los endpoints con muchas lecturas y las consultas costosas
-- Invalida las cachés en los eventos del modelo (created/updated/deleted)
-- Usa tags al cachear datos relacionados para invalidarlos con facilidad
-
-### Configuración y entornos
-
-- Mantén los secretos en `.env` y la configuración en `config/*.php`
-- Usa overrides de configuración por entorno y `config:cache` en producción

package/vendor/theus-arsenal/skills/patrones-mcp/SKILL.md

@@ -1,66 +0,0 @@
----
-name: patrones-mcp
-description: Construye servidores MCP con el SDK de Node/TypeScript — tools, resources, prompts, validación con Zod, stdio vs Streamable HTTP. Usa Context7 o la documentación oficial de MCP para la API más reciente.
----
-
-# Patrones de servidores MCP
-
-El Model Context Protocol (MCP) permite que los asistentes de IA invoquen tools, lean resources y usen prompts desde tu servidor. Usa esta skill al construir o mantener servidores MCP. La API del SDK evoluciona; consulta Context7 (búsqueda de documentación de "MCP") o la documentación oficial de MCP para conocer los nombres de métodos y firmas actuales.
-
-## Cuándo usar
-
-Úsala cuando: implementes un nuevo servidor MCP, añadas tools o resources, elijas entre stdio y HTTP, actualices el SDK o depures problemas de registro y transporte de MCP.
-
-## Cómo funciona
-
-### Conceptos centrales
-
-- **Tools**: acciones que el modelo puede invocar (p. ej., buscar, ejecutar un comando). Se registran con `registerTool()` o `tool()` según la versión del SDK.
-- **Resources**: datos de solo lectura que el modelo puede consultar (p. ej., contenidos de archivos, respuestas de APIs). Se registran con `registerResource()` o `resource()`. Los handlers típicamente reciben un argumento `uri`.
-- **Prompts**: plantillas de prompt reutilizables y parametrizables que el cliente puede exponer (p. ej., en un cliente MCP de escritorio). Se registran con `registerPrompt()` o su equivalente.
-- **Transporte**: stdio para clientes locales (p. ej., clientes MCP de escritorio); Streamable HTTP es el preferido para clientes remotos (IDEs remotos, nube). El HTTP/SSE heredado existe solo por compatibilidad hacia atrás.
-
-El SDK de Node/TypeScript puede exponer `tool()` / `resource()` o `registerTool()` / `registerResource()`; el SDK oficial ha cambiado con el tiempo. Verifica siempre contra la [documentación oficial de MCP](https://modelcontextprotocol.io) o Context7.
-
-### Conexión con stdio
-
-Para clientes locales, crea un transporte stdio y pásalo al método de conexión de tu servidor. La API exacta varía según la versión del SDK (p. ej., constructor vs factory). Consulta la documentación oficial de MCP o busca en Context7 "MCP stdio server" para el patrón actual.
-
-Mantén la lógica del servidor (tools + resources) independiente del transporte, de modo que puedas enchufar stdio o HTTP en el punto de entrada.
-
-### Remoto (Streamable HTTP)
-
-Para clientes remotos o en la nube, usa **Streamable HTTP** (un único endpoint HTTP de MCP según la especificación actual). Soporta el HTTP/SSE heredado solo cuando la compatibilidad hacia atrás sea un requisito.
-
-## Ejemplos
-
-### Instalación y configuración del servidor
-
-```bash
-npm install @modelcontextprotocol/sdk zod
-```
-
-```typescript
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-
-const server = new McpServer({ name: "my-server", version: "1.0.0" });
-```
-
-Registra tools y resources usando la API que provea tu versión del SDK: algunas versiones usan `server.tool(name, description, schema, handler)` (argumentos posicionales), otras usan `server.tool({ name, description, inputSchema }, handler)` o `registerTool()`. Lo mismo aplica a los resources — incluye un `uri` en el handler cuando la API lo provea. Consulta la documentación oficial de MCP o Context7 para las firmas actuales de `@modelcontextprotocol/sdk` y evitar errores de copiar y pegar.
-
-Usa **Zod** (o el formato de esquemas preferido por el SDK) para la validación de entrada.
-
-## Buenas prácticas
-
-- **Primero el schema**: define esquemas de entrada para cada tool; documenta los parámetros y la forma del retorno.
-- **Errores**: devuelve errores o mensajes estructurados que el modelo pueda interpretar; evita los stack traces en crudo.
-- **Idempotencia**: prefiere tools idempotentes cuando sea posible, para que los reintentos sean seguros.
-- **Tasa y costo**: para tools que llaman a APIs externas, considera los límites de tasa y el costo; documéntalo en la descripción de la tool.
-- **Versionado**: fija la versión del SDK en package.json; revisa las notas de la versión al actualizar.
-
-## SDKs oficiales y documentación
-
-- **JavaScript/TypeScript**: `@modelcontextprotocol/sdk` (npm). Usa Context7 con el nombre de librería "MCP" para los patrones actuales de registro y transporte.
-- **Go**: SDK oficial de Go en GitHub (`modelcontextprotocol/go-sdk`).
-- **C#**: SDK oficial de C# para .NET.