@3lineas/grooveskills 1.5.0 → 1.7.0

package/skills/caching-rate-limiting/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: caching-rate-limiting
+description: Architectural standards for Cache-Aside wrappers (cache.remember pattern) and interchangeable Rate Limiter adapters (Redis, Cloudflare KV, In-Memory). Prevents leaking vendor cache drivers into business logic and guarantees clean sliding-window or token-bucket rate limiting. TRIGGER when optimizing database query performance, adding cache layers, implementing API throttling, DDoS prevention, or per-user rate limiting.
+---
+
+# Cache-Aside Wrapper & Rate Limiter Adapters
+
+Opinionated architectural pattern for performance caching via the **Cache-Aside (`cache.remember`)** wrapper and decoupled **Rate Limiter** adapters.
+
+---
+
+## 1. Core Architectural Concepts
+
+1. **Cache-Aside Pattern (`cache.remember`)**:
+   - Instead of manual `get`, check null, query DB, and `set`, actions call `cache.remember(key, ttl, fetcher)`.
+   - Caching logic stays declarative, resilient, and decoupled from underlying stores.
+2. **Interchangeable Rate Limiting Port**:
+   - Throttling (sliding window / token bucket) is encapsulated behind `RateLimiterPort`.
+   - HTTP route middleware and actions check permissions without knowing whether Redis, Cloudflare KV, or an In-Memory store enforces limits.
+
+---
+
+## 2. Directory Layout
+
+```text
+src/
+├── domains/
+│   ├── cache/
+│   │   ├── cache-store.port.ts             # Raw key-value cache contract (<40 lines)
+│   │   └── cache.wrapper.ts                # Cache-aside remember helper (<60 lines)
+│   └── rate-limit/
+│       └── rate-limiter.port.ts            # Rate limiting contract (<40 lines)
+└── infrastructure/
+    └── adapters/
+        ├── cache/
+        │   ├── redis-cache.adapter.ts      # Redis cache implementation (<70 lines)
+        │   ├── cloudflare-kv.adapter.ts    # Cloudflare KV cache (<70 lines)
+        │   └── memory-cache.adapter.ts     # In-memory testing cache (<60 lines)
+        └── rate-limit/
+            ├── redis-rate-limiter.adapter.ts # Redis sliding window (<80 lines)
+            └── memory-rate-limiter.adapter.ts # In-memory rate limiter (<60 lines)
+```
+
+---
+
+## 3. Cache-Aside Wrapper (`src/domains/cache/cache.wrapper.ts`)
+
+```ts
+import type { CacheStorePort } from "./cache-store.port";
+
+export class CacheWrapper {
+  constructor(private store: CacheStorePort) {}
+
+  async remember<T>(key: string, ttlSeconds: number, fetcher: () => Promise<T>): Promise<T> {
+    const cached = await this.store.get<T>(key);
+    if (cached !== null && cached !== undefined) {
+      return cached;
+    }
+
+    const fresh = await fetcher();
+    await this.store.set(key, fresh, ttlSeconds);
+    return fresh;
+  }
+
+  async forget(key: string): Promise<void> {
+    await this.store.delete(key);
+  }
+}
+```
+
+---
+
+## 4. Rate Limiter Port & Enforcement
+
+```ts
+// src/domains/rate-limit/rate-limiter.port.ts
+export interface RateLimitResult {
+  success: boolean;
+  limit: number;
+  remaining: number;
+  resetSeconds: number;
+}
+
+export interface RateLimiterPort {
+  limit(identifier: string): Promise<RateLimitResult>;
+}
+```
+
+### Rate Limiter Middleware Example
+```ts
+export async function rateLimitMiddleware(c: Context, limiter: RateLimiterPort) {
+  const ip = c.req.header("cf-connecting-ip") ?? c.req.header("x-forwarded-for") ?? "anonymous";
+  const check = await limiter.limit(`ip:${ip}`);
+
+  c.header("X-RateLimit-Limit", String(check.limit));
+  c.header("X-RateLimit-Remaining", String(check.remaining));
+
+  if (!check.success) {
+    throw new AppError({ message: "Has excedido el límite de solicitudes. Intenta más tarde.", statusCode: 429 });
+  }
+}
+```
+
+---
+
+## 5. Detailed Adapters Reference
+
+For real implementations of Redis cache, Cloudflare KV, and Redis sliding-window rate limiters, consult:
+- `references/cache-rate-limit-examples.md`

package/skills/caching-rate-limiting/references/cache-rate-limit-examples.md

@@ -0,0 +1,129 @@
+# Implementation Reference: Cache & Rate Limiting Adapters
+
+Production implementations of Redis cache, Cloudflare KV, and sliding-window rate limiters.
+
+---
+
+## 1. Redis Cache Adapter (`ioredis`)
+
+```ts
+// src/infrastructure/adapters/cache/redis-cache.adapter.ts
+import type { Redis } from "ioredis";
+import type { CacheStorePort } from "@/domains/cache/cache-store.port";
+
+export class RedisCacheAdapter implements CacheStorePort {
+  constructor(private redis: Redis) {}
+
+  async get<T>(key: string): Promise<T | null> {
+    const raw = await this.redis.get(key);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {
+    await this.redis.set(key, JSON.stringify(value), "EX", ttlSeconds);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.redis.del(key);
+  }
+}
+```
+
+---
+
+## 2. Cloudflare Workers KV Cache Adapter
+
+```ts
+// src/infrastructure/adapters/cache/cloudflare-kv.adapter.ts
+import type { CacheStorePort } from "@/domains/cache/cache-store.port";
+
+export class CloudflareKvAdapter implements CacheStorePort {
+  constructor(private kv: KVNamespace) {}
+
+  async get<T>(key: string): Promise<T | null> {
+    return this.kv.get<T>(key, "json");
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {
+    await this.kv.put(key, JSON.stringify(value), { expirationTtl: Math.max(ttlSeconds, 60) });
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.kv.delete(key);
+  }
+}
+```
+
+---
+
+## 3. Redis Sliding Window Rate Limiter Adapter
+
+```ts
+// src/infrastructure/adapters/rate-limit/redis-rate-limiter.adapter.ts
+import type { Redis } from "ioredis";
+import type { RateLimiterPort, RateLimitResult } from "@/domains/rate-limit/rate-limiter.port";
+
+export class RedisSlidingWindowRateLimiter implements RateLimiterPort {
+  constructor(
+    private redis: Redis,
+    private maxRequests: number = 60,
+    private windowSeconds: number = 60
+  ) {}
+
+  async limit(identifier: string): Promise<RateLimitResult> {
+    const now = Date.now();
+    const windowStart = now - this.windowSeconds * 1000;
+    const key = `ratelimit:${identifier}`;
+
+    const multi = this.redis.multi();
+    multi.zremrangebyscore(key, 0, windowStart);
+    multi.zadd(key, now, `${now}-${Math.random()}`);
+    multi.zcard(key);
+    multi.expire(key, this.windowSeconds);
+
+    const results = await multi.exec();
+    const count = (results?.[2]?.[1] as number) ?? 1;
+
+    const remaining = Math.max(0, this.maxRequests - count);
+    const success = count <= this.maxRequests;
+
+    return { success, limit: this.maxRequests, remaining, resetSeconds: this.windowSeconds };
+  }
+}
+```
+
+---
+
+## 4. In-Memory Testing Cache Adapter
+
+```ts
+// src/infrastructure/adapters/cache/memory-cache.adapter.ts
+import type { CacheStorePort } from "@/domains/cache/cache-store.port";
+
+export class MemoryCacheAdapter implements CacheStorePort {
+  private store = new Map<string, { value: unknown; expiresAt: number }>();
+
+  async get<T>(key: string): Promise<T | null> {
+    const item = this.store.get(key);
+    if (!item) return null;
+    if (Date.now() > item.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+    return item.value as T;
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {
+    this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+}
+```

package/skills/clean-architecture-ddd/SKILL.md

@@ -101,3 +101,4 @@ export async function chargeSubscriptionAction(
 - **`best-practices`**: Universal clean code rules and guard clauses.
 - **`error-handling-logging`**: Structured `AppError` and `ActionResponse`.
 - **`valibot-validation`**: Domain input/output validation.
+- **`external-service-adapters`**: Standardized domain ports, vendor SDK wrappers, and adapters for third-party services.

package/skills/controller-orchestration-queues/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: controller-orchestration-queues
+description: Strict orchestration standards for Controllers, atomic Actions, database Transactions, and background Queue Adapters (Cloudflare Queues, BullMQ, AWS SQS, In-Memory). Mandates that Actions do only ONE atomic thing, while Controllers sequence multiple actions, manage transactions, or dispatch async jobs. Enforces Queue Workers as slim controllers. TRIGGER when orchestrating multi-step workflows, handling DB transactions across actions, dispatching background tasks, or designing queue consumers.
+---
+
+# Controller Action Orchestration, Transactions & Queue Adapters
+
+Architectural standard establishing strict separation of concerns between **Atomic Actions** and **Orchestration Controllers / Queue Workers**.
+
+---
+
+## 1. The Core Architectural Law
+
+1. **Actions Do Exactly ONE Atomic Thing**:
+   - Pure single responsibility. Example: `createOrderAction`, `chargeCardAction`, `sendOrderEmailAction`.
+   - Actions NEVER orchestrate other sibling actions or dispatch unrelated background jobs directly.
+2. **Controllers are Orchestrators**:
+   - HTTP route handlers and RPC controllers validate inputs, sequence actions, wrap transactional DB boundaries (`withTransaction`), and dispatch background jobs via `QueuePort`.
+3. **Queue Workers are Slim Controllers**:
+   - A queue worker message handler behaves like an HTTP controller: parses payload and delegates to atomic actions.
+
+---
+
+## 2. Directory Layout
+
+```text
+src/
+├── actions/
+│   ├── orders/
+│   │   ├── create-order.action.ts          # Atomic insert order (<70 lines)
+│   │   └── update-order-status.action.ts   # Atomic update status (<60 lines)
+│   └── billing/
+│       └── charge-card.action.ts           # Atomic payment charge (<70 lines)
+├── controllers/
+│   └── orders/
+│       └── checkout.controller.ts         # Orchestrates actions + Queue (<90 lines)
+├── domains/
+│   └── queue/
+│       ├── queue.port.ts                   # Domain interface for dispatching (<40 lines)
+│       └── queue-message.types.ts          # Strongly typed queue messages (<50 lines)
+└── infrastructure/
+    ├── adapters/
+    │   └── queue/
+    │       ├── cloudflare-queues.adapter.ts # Cloudflare Queues adapter (<80 lines)
+    │       ├── bullmq-queues.adapter.ts     # Redis / BullMQ adapter (<80 lines)
+    │       ├── sqs-queues.adapter.ts        # AWS SQS adapter (<80 lines)
+    │       └── memory-queues.adapter.ts     # In-memory testing queue (<60 lines)
+    └── workers/
+        └── order-events.worker.ts          # Slim worker invoking actions (<80 lines)
+```
+
+---
+
+## 3. Domain Queue Contract (`src/domains/queue/queue.port.ts`)
+
+```ts
+export interface QueueJob<TData = unknown> {
+  id?: string;
+  name: string;
+  data: TData;
+  delaySeconds?: number;
+}
+
+export interface QueuePort {
+  dispatch<T>(job: QueueJob<T>): Promise<{ jobId: string }>;
+  dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }>;
+}
+```
+
+---
+
+## 4. Orchestration Controller Pattern
+
+```ts
+// src/controllers/orders/checkout.controller.ts
+import type { Context } from "hono";
+import type { QueuePort } from "@/domains/queue/queue.port";
+import { createOrderAction } from "@/actions/orders/create-order.action";
+import { chargeCardAction } from "@/actions/billing/charge-card.action";
+import { db, withTransaction } from "@/infrastructure/db/connection";
+
+export async function checkoutController(c: Context, queue: QueuePort) {
+  const payload = c.get("validatedJson");
+  const actor = c.get("actor");
+
+  // Step 1: Charge card (external side-effect, kept outside DB transaction)
+  const charge = await chargeCardAction(payload.paymentMethodId, payload.amount);
+
+  // Step 2: Atomic DB Transaction for local entity creation
+  const order = await withTransaction(db, async (tx) => {
+    return createOrderAction(tx, { actorId: actor.id, amount: payload.amount, chargeId: charge.id });
+  });
+
+  // Step 3: Dispatch async post-processing via Queue
+  await queue.dispatch({
+    name: "orders.post-checkout",
+    data: { orderId: order.id, customerEmail: actor.email },
+  });
+
+  return c.json({ orderId: order.id, status: "confirmed" }, 201);
+}
+```
+
+---
+
+## 5. Detailed Adapters & Workers Reference
+
+For real implementations of Cloudflare Queues, BullMQ, AWS SQS, and In-Memory Queue adapters, consult:
+- `references/controller-queue-examples.md`

package/skills/controller-orchestration-queues/references/controller-queue-examples.md

@@ -0,0 +1,115 @@
+# Implementation Reference: Controller Orchestration & Queue Adapters
+
+Real-world queue adapters (Cloudflare Queues, BullMQ, AWS SQS, In-Memory) and Slim Worker controllers.
+
+---
+
+## 1. Cloudflare Queues Adapter
+
+```ts
+// src/infrastructure/adapters/queue/cloudflare-queues.adapter.ts
+import type { QueuePort, QueueJob } from "@/domains/queue/queue.port";
+import { AppError } from "@/errors/app-error";
+
+export class CloudflareQueueAdapter implements QueuePort {
+  constructor(private queue: Queue) {}
+
+  async dispatch<T>(job: QueueJob<T>): Promise<{ jobId: string }> {
+    try {
+      await this.queue.send(job, { delaySeconds: job.delaySeconds });
+      return { jobId: job.id ?? crypto.randomUUID() };
+    } catch (err) {
+      throw new AppError({ message: "Error al encolar mensaje en Cloudflare Queues.", statusCode: 502, cause: err });
+    }
+  }
+
+  async dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }> {
+    await this.queue.sendBatch(jobs.map((j) => ({ body: j, delaySeconds: j.delaySeconds })));
+    return { count: jobs.length };
+  }
+}
+```
+
+---
+
+## 2. BullMQ (Redis) Adapter
+
+```ts
+// src/infrastructure/adapters/queue/bullmq-queues.adapter.ts
+import { Queue as BullQueue } from "bullmq";
+import type { QueuePort, QueueJob } from "@/domains/queue/queue.port";
+import { AppError } from "@/errors/app-error";
+
+export class BullMQAdapter implements QueuePort {
+  constructor(private bullQueue: BullQueue) {}
+
+  async dispatch<T>(job: QueueJob<T>): Promise<{ jobId: string }> {
+    try {
+      const bJob = await this.bullQueue.add(job.name, job.data, {
+        jobId: job.id,
+        delay: job.delaySeconds ? job.delaySeconds * 1000 : undefined,
+      });
+      return { jobId: String(bJob.id) };
+    } catch (err) {
+      throw new AppError({ message: "Error al enviar trabajo a BullMQ.", statusCode: 502, cause: err });
+    }
+  }
+
+  async dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }> {
+    await this.bullQueue.addBulk(
+      jobs.map((j) => ({
+        name: j.name,
+        data: j.data,
+        opts: { jobId: j.id, delay: j.delaySeconds ? j.delaySeconds * 1000 : undefined },
+      }))
+    );
+    return { count: jobs.length };
+  }
+}
+```
+
+---
+
+## 3. In-Memory Queue Adapter (Testing Fake)
+
+```ts
+// src/infrastructure/adapters/queue/memory-queues.adapter.ts
+import type { QueuePort, QueueJob } from "@/domains/queue/queue.port";
+
+export class MemoryQueueAdapter implements QueuePort {
+  public jobs: QueueJob[] = [];
+
+  async dispatch<T>(job: QueueJob<T>): Promise<{ jobId: string }> {
+    const id = job.id ?? `job_${this.jobs.length + 1}`;
+    this.jobs.push({ ...job, id });
+    return { jobId: id };
+  }
+
+  async dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }> {
+    for (const job of jobs) {
+      await this.dispatch(job);
+    }
+    return { count: jobs.length };
+  }
+}
+```
+
+---
+
+## 4. Slim Queue Worker Controller Pattern
+
+```ts
+// src/infrastructure/workers/order-events.worker.ts
+import { sendOrderEmailAction } from "@/actions/email/send-order-email.action";
+import { syncCrmAction } from "@/actions/crm/sync-crm.action";
+import { logger } from "@/infrastructure/logger/app-logger";
+
+export async function handleOrderQueueMessage(messageBody: { name: string; data: { orderId: string; customerEmail: string } }) {
+  logger.info("Procesando evento de orden", { jobName: messageBody.name, orderId: messageBody.data.orderId });
+
+  if (messageBody.name === "orders.post-checkout") {
+    await sendOrderEmailAction(messageBody.data.customerEmail, messageBody.data.orderId);
+    await syncCrmAction(messageBody.data.orderId);
+  }
+}
+```

package/skills/docs-standards/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: docs-standards
+description: Comprehensive documentation standards: English documentation rule, strict relative POSIX links, Mermaid diagram syntax rules, ADR lifecycle, clean Markdown formatting, and intent-focused code docstrings. TRIGGER when writing, structuring, or updating technical docs, README files, architectural guides, ADRs, Mermaid diagrams, or in-code docstrings.
+---
+
+# Technical Documentation Standards
+
+Authoritative standard for technical documentation, architectural specifications, markdown files, and in-code docstrings across projects.
+
+---
+
+## 1. Core Principles
+
+1. **All Technical Documentation in English**:
+   - Internal technical guides, README files, ADRs, architecture specs, code comments, and docstrings must be written exclusively in English.
+   - User-facing application microcopy remains governed by project localization rules (e.g. `ux-writing`), but technical documentation is English-only.
+
+2. **Strict Relative POSIX Paths**:
+   - When referencing other files, specs, schemas, or tests within documentation, ALWAYS use relative POSIX paths (`./path/to/file.md` or `../other/file.md`).
+   - Never use absolute filesystem paths (`/Users/...`, `C:\...`) or IDE-specific virtual URI protocols.
+   - Always verify that relative links resolve correctly from the containing document's directory.
+
+3. **Document the "Why", Not the "What"**:
+   - Never describe literal syntax (e.g., `// loop through items` or `// sets age to 20`).
+   - Document business constraints, invariant assumptions, edge case rationale, architectural trade-offs, and failure expectations.
+   - Delete dead code, commented-out blocks, and speculative notes immediately.
+
+4. **Hard Limit of <200 Lines Per File**:
+   - Split broad specifications or long documents into concise primary manifests (`SKILL.md`, `README.md`) and focused modular topic files under `./references/` or `./docs/`.
+
+---
+
+## 2. Documentation Architecture & Directory Layout
+
+Organize complex documentation sets into modular topic documents:
+
+```text
+docs/
+├── architecture/
+│   ├── overview.md                  # High-level system diagram and component boundaries (<150 lines)
+│   └── adr/
+│       ├── 0001-init-stack.md       # Individual decision record (<100 lines)
+│       └── 0002-event-bus.md        # Modular decision record (<100 lines)
+├── guides/
+│   ├── local-setup.md               # Prerequisites and bootstrap guide (<120 lines)
+│   └── testing-strategy.md          # Test matrices, fixtures, and CI workflows (<140 lines)
+└── references/
+    └── api-contracts.md             # Data transfer payloads and external specs (<180 lines)
+```
+
+Link files using explicit relative paths:
+- From `docs/architecture/overview.md` to an ADR: `[ADR 0001](./adr/0001-init-stack.md)`
+- From `docs/architecture/adr/0002-event-bus.md` to architecture overview: `[Overview](../overview.md)`
+
+---
+
+## 3. Mermaid Diagrams Best Practices
+
+Diagrams clarify systems only when syntactically resilient. Always enforce:
+
+1. **Direction**: Use explicit layout directions (`flowchart TD` or `flowchart LR`).
+2. **Safe Quoting**: Always wrap node text and edge labels containing punctuation, brackets, parentheses, or spaces inside double quotes:
+   - `id1["Service A (v2.1)"] -->|"POST /events"| id2["Worker Engine"]`
+3. **Escaping**: Never leave unescaped curly braces `{}` or square brackets `[]` raw inside node bodies.
+4. **Subgraphs**: Assign explicit identifier tokens to subgraphs:
+   ```mermaid
+   flowchart LR
+     subgraph CoreDomain["Domain Layer"]
+       Action["ProcessPaymentAction"]
+     end
+   ```
+
+*Deep reference*: See [./references/relative-paths-and-diagrams.md](./references/relative-paths-and-diagrams.md) for full syntax and escaping guidelines.
+
+---
+
+## 4. Architecture Decision Records (ADR)
+
+Document critical architectural forks before or during implementation:
+
+- **State Lifecycle**: `Proposed` -> `Accepted` -> `Superseded by ADR-XXXX` or `Deprecated`.
+- **Structure**: Title, Status, Context, Decision, Consequences (Positive, Negative, Neutral).
+- **Append-only log**: Maintain an index table or individual timestamped files in `./docs/architecture/adr/`.
+
+*Deep reference*: See [./references/adr-template-and-lifecycle.md](./references/adr-template-and-lifecycle.md) for templates and lifecycle rules.
+
+---
+
+## 5. In-Code Comments and Docstrings
+
+Apply standard formatters and focus on architectural context:
+
+- **TypeScript / JavaScript**: Use JSDoc / TSDoc (`/** ... */`) above exported symbols.
+- **Python**: Use PEP 257 docstrings (`"""..."""`) on functions, modules, and classes.
+- **Rust**: Use `///` outer doc comments for items and `//!` for module-level docs.
+- **No obvious commentary**: If the function signature `getUserById(id: string)` already communicates the mechanics, only document non-obvious errors, side-effects, or performance implications.
+
+*Deep reference*: See [./references/code-comments-and-docstrings.md](./references/code-comments-and-docstrings.md) for concrete language examples and anti-patterns.
+
+---
+
+## 6. Clean Markdown Formatting & Alerts
+
+- Use standard GitHub markdown alert callouts:
+  ```markdown
+  > [!NOTE]
+  > Informational notes highlighting context.
+
+  > [!WARNING]
+  > Critical operational caveats, breaking changes, or deprecations.
+  ```
+- Use consistent heading hierarchies (`#` -> `##` -> `###`). Never skip heading levels.
+- Format tables with clear header alignment (`| :--- | :--- | :---: |`).