theus-cli-linux-arm64 0.2.84

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

@@ -0,0 +1,414 @@
+---
+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

@@ -0,0 +1,66 @@
+---
+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.