@3lineas/grooveskills 1.4.0 → 1.6.0

package/skills/external-service-adapters/references/email-and-payment-examples.md

@@ -0,0 +1,198 @@
+# Implementation Reference: Email & Payment Adapters
+
+Reference implementations illustrating the Wrapper + Adapter pattern across email providers and payment gateways with strict typing and guard clauses.
+
+---
+
+## 1. Transactional Email System
+
+### 1.1 Pure Domain Port (`src/domains/email/email-sender.port.ts`)
+```ts
+export interface EmailRecipient {
+  email: string;
+  name?: string;
+}
+
+export interface SendEmailInput {
+  to: EmailRecipient[];
+  subject: string;
+  html: string;
+  text?: string;
+  from?: EmailRecipient;
+  replyTo?: string;
+}
+
+export interface SendEmailResult {
+  messageId: string;
+  provider: "smtp" | "resend" | "aws-ses" | "cloudflare";
+  sentAt: Date;
+}
+
+export interface EmailSenderPort {
+  send(input: SendEmailInput): Promise<SendEmailResult>;
+}
+```
+
+### 1.2 SMTP Adapter (`nodemailer`)
+```ts
+// src/infrastructure/adapters/email/smtp-email.adapter.ts
+import type { EmailSenderPort, SendEmailInput, SendEmailResult } from "@/domains/email/email-sender.port";
+import type { SmtpWrapper } from "@/infrastructure/wrappers/smtp/smtp.wrapper";
+import { AppError } from "@/errors/app-error";
+
+export class SmtpEmailAdapter implements EmailSenderPort {
+  constructor(private wrapper: SmtpWrapper, private defaultSender: string) {}
+
+  async send(input: SendEmailInput): Promise<SendEmailResult> {
+    try {
+      const from = input.from ? `${input.from.name ?? ""} <${input.from.email}>`.trim() : this.defaultSender;
+      const info = await this.wrapper.sendMail({
+        from,
+        to: input.to.map((r) => r.email).join(", "),
+        subject: input.subject,
+        html: input.html,
+        text: input.text,
+      });
+      return { messageId: info.messageId, provider: "smtp", sentAt: new Date() };
+    } catch (err) {
+      throw new AppError({ message: "Fallo al enviar correo SMTP.", statusCode: 502, cause: err });
+    }
+  }
+}
+```
+
+### 1.3 AWS SES Adapter (`@aws-sdk/client-ses`)
+```ts
+// src/infrastructure/adapters/email/ses-email.adapter.ts
+import type { EmailSenderPort, SendEmailInput, SendEmailResult } from "@/domains/email/email-sender.port";
+import type { SesWrapper } from "@/infrastructure/wrappers/aws/ses.wrapper";
+import { AppError } from "@/errors/app-error";
+
+export class SesEmailAdapter implements EmailSenderPort {
+  constructor(private wrapper: SesWrapper, private defaultSource: string) {}
+
+  async send(input: SendEmailInput): Promise<SendEmailResult> {
+    const res = await this.wrapper.send({
+      Source: input.from?.email ?? this.defaultSource,
+      Destination: { ToAddresses: input.to.map((t) => t.email) },
+      Message: {
+        Subject: { Data: input.subject, Charset: "UTF-8" },
+        Body: { Html: { Data: input.html, Charset: "UTF-8" } },
+      },
+    });
+
+    if (!res.MessageId) {
+      throw new AppError({ message: "Fallo al enviar correo con AWS SES.", statusCode: 502 });
+    }
+    return { messageId: res.MessageId, provider: "aws-ses", sentAt: new Date() };
+  }
+}
+```
+
+### 1.4 Cloudflare Email Routing Adapter
+```ts
+// src/infrastructure/adapters/email/cloudflare-email.adapter.ts
+import type { EmailSenderPort, SendEmailInput, SendEmailResult } from "@/domains/email/email-sender.port";
+import type { CloudflareEmailWrapper } from "@/infrastructure/wrappers/cloudflare/cloudflare-email.wrapper";
+import { AppError } from "@/errors/app-error";
+
+export class CloudflareEmailAdapter implements EmailSenderPort {
+  constructor(private wrapper: CloudflareEmailWrapper, private defaultSender: string) {}
+
+  async send(input: SendEmailInput): Promise<SendEmailResult> {
+    const res = await this.wrapper.postEmail({
+      from: input.from?.email ?? this.defaultSender,
+      to: input.to.map((t) => t.email),
+      subject: input.subject,
+      content: input.html,
+    });
+    if (!res.ok) {
+      throw new AppError({ message: "Error al enviar correo con Cloudflare Email.", statusCode: 502 });
+    }
+    const data = await res.json() as { result?: { id?: string } };
+    return { messageId: data.result?.id ?? `cf_${Date.now()}`, provider: "cloudflare", sentAt: new Date() };
+  }
+}
+```
+
+---
+
+## 2. Payment Gateways (Stripe & MercadoPago)
+
+### 2.1 Domain Port (`src/domains/billing/payment-gateway.port.ts`)
+```ts
+export interface ChargeInput {
+  amountInCents: number;
+  currency: "usd" | "clp" | "mxn" | "eur";
+  customerId: string;
+  sourceToken?: string;
+  idempotencyKey: string;
+}
+
+export interface ChargeResult {
+  transactionId: string;
+  status: "succeeded" | "pending" | "failed";
+  provider: "stripe" | "mercadopago";
+}
+
+export interface PaymentGatewayPort {
+  createCharge(input: ChargeInput): Promise<ChargeResult>;
+}
+```
+
+### 2.2 Stripe & MercadoPago Adapters
+```ts
+// src/infrastructure/adapters/payment/stripe-payment.adapter.ts
+import type { PaymentGatewayPort, ChargeInput, ChargeResult } from "@/domains/billing/payment-gateway.port";
+import type Stripe from "stripe";
+import { AppError } from "@/errors/app-error";
+
+export class StripePaymentAdapter implements PaymentGatewayPort {
+  constructor(private stripe: Stripe) {}
+
+  async createCharge(input: ChargeInput): Promise<ChargeResult> {
+    try {
+      const intent = await this.stripe.paymentIntents.create(
+        { amount: input.amountInCents, currency: input.currency, customer: input.customerId, confirm: true },
+        { idempotencyKey: input.idempotencyKey }
+      );
+      return {
+        transactionId: intent.id,
+        status: intent.status === "succeeded" ? "succeeded" : "pending",
+        provider: "stripe",
+      };
+    } catch (err) {
+      throw new AppError({ message: "Fallo en Stripe.", statusCode: 402, cause: err });
+    }
+  }
+}
+```
+```ts
+// src/infrastructure/adapters/payment/mercadopago-payment.adapter.ts
+import type { PaymentGatewayPort, ChargeInput, ChargeResult } from "@/domains/billing/payment-gateway.port";
+import { Payment, type MercadoPagoConfig } from "mercadopago";
+import { AppError } from "@/errors/app-error";
+
+export class MercadoPagoPaymentAdapter implements PaymentGatewayPort {
+  private client: Payment;
+  constructor(cfg: MercadoPagoConfig) {
+    this.client = new Payment(cfg);
+  }
+
+  async createCharge(input: ChargeInput): Promise<ChargeResult> {
+    try {
+      const res = await this.client.create({
+        body: { transaction_amount: input.amountInCents / 100, token: input.sourceToken, payer: { id: input.customerId } },
+        requestOptions: { idempotencyKey: input.idempotencyKey },
+      });
+      return {
+        transactionId: String(res.id),
+        status: res.status === "approved" ? "succeeded" : "pending",
+        provider: "mercadopago",
+      };
+    } catch (err) {
+      throw new AppError({ message: "Fallo en MercadoPago.", statusCode: 402, cause: err });
+    }
+  }
+}
+```

package/skills/groove-harness/SKILL.md

@@ -39,6 +39,7 @@ Every request is governed by the 7-step ODD protocol (*Authorize, Explore, Resol
 
 - **`.grooveskills/memory/context.md`**: Stores project stack, architectural patterns, conventions, and key commands. Read this when starting work on a domain; update it when new dependencies or architectural standards are introduced.
 - **`.grooveskills/memory/decisions.md`**: An append-only Architecture Decision Record (ADR). Log significant technical decisions (`Date`, `Context`, `Decision`, `Consequences`).
+- **`.grooveskills/memory/tasks/00-onboarding.md`**: Initial onboarding task. If `status: pending`, inspect project structure, commands, and verify `.grooveskills/memory/context.md`, then mark as `completed`.
 - **`.grooveskills/memory/tasks/`**: Individual feature records holding outcome hypotheses, checklists, and observed proof.
 
 ---

package/skills/storage-file-adapters/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: storage-file-adapters
+description: Standardized wrapper & adapter architecture for object storage, uploads, presigned URLs, and streaming (AWS S3, Cloudflare R2, Supabase Storage, In-Memory). Discards repository abstractions in favor of direct ports and isolated vendor clients. TRIGGER when implementing file uploads, asset storage, cloud buckets, multipart uploads, or presigned download/upload URLs.
+---
+
+# Object Storage & File Adapters (Wrappers + Ports)
+
+Opinionated architectural pattern for object storage and file management (AWS S3, Cloudflare R2, Supabase Storage, In-Memory) utilizing the **Wrapper + Adapter** pattern instead of generic repositories.
+
+---
+
+## 1. Core Principles
+
+1. **Storage is an I/O Port, Not a Repository**:
+   - Files are blobs with metadata and URLs, not relational entities. We define `StoragePort`, not `FileRepository`.
+2. **Standardized Domain Payload**:
+   - Operations consume and return pure domain contracts (`PutFileInput`, `PutFileOutput`, `PresignedUrlInput`).
+   - Vendor response shapes (S3 `PutObjectCommandOutput`, Supabase `StorageError`) never escape the adapter boundary.
+3. **Vendor Wrappers Isolate Credentials & SDK Quirks**:
+   - SDK clients, endpoint URLs, region configs, and multipart batching logic remain strictly inside `src/infrastructure/wrappers/storage/`.
+4. **Zero-Change Provider Portability**:
+   - Switching between AWS S3, Cloudflare R2, Supabase Storage, or an In-Memory mock during local testing requires swapping only the adapter instance.
+
+---
+
+## 2. Directory Layout
+
+```text
+src/
+├── actions/
+│   └── media/
+│       └── upload-avatar.action.ts         # Consumes StoragePort (<80 lines)
+├── domains/
+│   └── storage/
+│       ├── storage.port.ts                 # Domain interface contract (<50 lines)
+│       └── storage.types.ts                # Pure domain payloads (<50 lines)
+└── infrastructure/
+    ├── adapters/
+    │   └── storage/
+    │       ├── s3-storage.adapter.ts       # AWS S3 implementation (<90 lines)
+    │       ├── r2-storage.adapter.ts       # Cloudflare R2 implementation (<90 lines)
+    │       ├── supabase-storage.adapter.ts # Supabase Storage implementation (<90 lines)
+    │       └── memory-storage.adapter.ts   # In-memory testing adapter (<70 lines)
+    └── wrappers/
+        └── storage/
+            ├── s3-client.wrapper.ts        # AWS SDK client wrapper (<70 lines)
+            ├── r2-client.wrapper.ts        # Cloudflare S3-compatible client (<70 lines)
+            └── supabase-storage.wrapper.ts # Supabase storage client (<60 lines)
+```
+
+---
+
+## 3. Implementation Contract (`src/domains/storage/storage.port.ts`)
+
+```ts
+export interface StorageFile {
+  buffer: Uint8Array | Buffer;
+  contentType: string;
+  sizeBytes: number;
+}
+
+export interface PutFileInput {
+  bucket: string;
+  key: string;
+  file: StorageFile;
+  isPublic?: boolean;
+}
+
+export interface PutFileOutput {
+  key: string;
+  bucket: string;
+  publicUrl?: string;
+  etag?: string;
+}
+
+export interface PresignedUrlInput {
+  bucket: string;
+  key: string;
+  operation: "getObject" | "putObject";
+  expiresInSeconds: number;
+}
+
+export interface StoragePort {
+  putFile(input: PutFileInput): Promise<PutFileOutput>;
+  getFile(bucket: string, key: string): Promise<StorageFile>;
+  deleteFile(bucket: string, key: string): Promise<void>;
+  createPresignedUrl(input: PresignedUrlInput): Promise<string>;
+}
+```
+
+---
+
+## 4. Usage in Business Actions
+
+```ts
+import type { StoragePort } from "@/domains/storage/storage.port";
+import { AppError } from "@/errors/app-error";
+
+export async function uploadAvatarAction(
+  storage: StoragePort,
+  userId: string,
+  rawFile: Uint8Array,
+  mimeType: string
+): Promise<{ avatarUrl: string }> {
+  if (rawFile.byteLength > 5 * 1024 * 1024) {
+    throw new AppError({ message: "La imagen excede el límite de 5 MB.", statusCode: 400 });
+  }
+
+  const result = await storage.putFile({
+    bucket: "avatars",
+    key: `users/${userId}/avatar.webp`,
+    file: { buffer: rawFile, contentType: mimeType, sizeBytes: rawFile.byteLength },
+    isPublic: true,
+  });
+
+  return { avatarUrl: result.publicUrl ?? result.key };
+}
+```
+
+---
+
+## 5. Detailed Provider Blueprints
+
+For complete production adapters (AWS S3, Cloudflare R2, Supabase Storage, and In-Memory testing fake), consult:
+- `references/storage-adapters-examples.md`

package/skills/storage-file-adapters/references/storage-adapters-examples.md

@@ -0,0 +1,164 @@
+# Implementation Reference: Object Storage & File Adapters
+
+Reference implementations for S3, Cloudflare R2, Supabase Storage, and In-Memory testing fake under the Wrapper + Adapter architecture.
+
+---
+
+## 1. AWS S3 Adapter (`@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`)
+
+```ts
+// src/infrastructure/adapters/storage/s3-storage.adapter.ts
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import type { StoragePort, PutFileInput, PutFileOutput, StorageFile, PresignedUrlInput } from "@/domains/storage/storage.port";
+import { AppError } from "@/errors/app-error";
+
+export class S3StorageAdapter implements StoragePort {
+  constructor(private client: S3Client, private publicBaseUrl?: string) {}
+
+  async putFile(input: PutFileInput): Promise<PutFileOutput> {
+    try {
+      const res = await this.client.send(
+        new PutObjectCommand({
+          Bucket: input.bucket,
+          Key: input.key,
+          Body: input.file.buffer,
+          ContentType: input.file.contentType,
+        })
+      );
+      const publicUrl = this.publicBaseUrl ? `${this.publicBaseUrl.replace(/\/$/, "")}/${input.key}` : undefined;
+      return { key: input.key, bucket: input.bucket, publicUrl, etag: res.ETag };
+    } catch (err) {
+      throw new AppError({ message: "Error al subir archivo a S3.", statusCode: 502, cause: err });
+    }
+  }
+
+  async getFile(bucket: string, key: string): Promise<StorageFile> {
+    const res = await this.client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+    const bytes = await res.Body?.transformToByteArray();
+    if (!bytes) {
+      throw new AppError({ message: "Archivo no encontrado o vacío.", statusCode: 404 });
+    }
+    return { buffer: bytes, contentType: res.ContentType ?? "application/octet-stream", sizeBytes: res.ContentLength ?? bytes.byteLength };
+  }
+
+  async deleteFile(bucket: string, key: string): Promise<void> {
+    await this.client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+  }
+
+  async createPresignedUrl(input: PresignedUrlInput): Promise<string> {
+    const Command = input.operation === "getObject" ? GetObjectCommand : PutObjectCommand;
+    return getSignedUrl(this.client, new Command({ Bucket: input.bucket, Key: input.key }), { expiresIn: input.expiresInSeconds });
+  }
+}
+```
+
+---
+
+## 2. Cloudflare R2 Adapter (S3-Compatible)
+
+```ts
+// src/infrastructure/adapters/storage/r2-storage.adapter.ts
+import { S3Client } from "@aws-sdk/client-s3";
+import { S3StorageAdapter } from "./s3-storage.adapter";
+
+export function createR2StorageAdapter(accountId: string, accessKeyId: string, secretAccessKey: string, publicUrl?: string) {
+  const client = new S3Client({
+    region: "auto",
+    endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+    credentials: { accessKeyId, secretAccessKey },
+  });
+  return new S3StorageAdapter(client, publicUrl);
+}
+```
+
+---
+
+## 3. Supabase Storage Adapter (`@supabase/storage-js`)
+
+```ts
+// src/infrastructure/adapters/storage/supabase-storage.adapter.ts
+import type { StorageClient } from "@supabase/storage-js";
+import type { StoragePort, PutFileInput, PutFileOutput, StorageFile, PresignedUrlInput } from "@/domains/storage/storage.port";
+import { AppError } from "@/errors/app-error";
+
+export class SupabaseStorageAdapter implements StoragePort {
+  constructor(private client: StorageClient) {}
+
+  async putFile(input: PutFileInput): Promise<PutFileOutput> {
+    const { data, error } = await this.client.from(input.bucket).upload(input.key, input.file.buffer, {
+      contentType: input.file.contentType,
+      upsert: true,
+    });
+    if (error || !data) {
+      throw new AppError({ message: "Error al almacenar archivo en Supabase.", statusCode: 502, cause: error });
+    }
+    const publicUrl = input.isPublic ? this.client.from(input.bucket).getPublicUrl(input.key).data.publicUrl : undefined;
+    return { key: input.key, bucket: input.bucket, publicUrl };
+  }
+
+  async getFile(bucket: string, key: string): Promise<StorageFile> {
+    const { data, error } = await this.client.from(bucket).download(key);
+    if (error || !data) {
+      throw new AppError({ message: "Archivo no encontrado.", statusCode: 404, cause: error });
+    }
+    const buffer = new Uint8Array(await data.arrayBuffer());
+    return { buffer, contentType: data.type || "application/octet-stream", sizeBytes: buffer.byteLength };
+  }
+
+  async deleteFile(bucket: string, key: string): Promise<void> {
+    const { error } = await this.client.from(bucket).remove([key]);
+    if (error) {
+      throw new AppError({ message: "Error al eliminar archivo en Supabase.", statusCode: 502, cause: error });
+    }
+  }
+
+  async createPresignedUrl(input: PresignedUrlInput): Promise<string> {
+    if (input.operation !== "getObject") {
+      throw new AppError({ message: "Operación de presigned URL no soportada.", statusCode: 400 });
+    }
+    const { data, error } = await this.client.from(input.bucket).createSignedUrl(input.key, input.expiresInSeconds);
+    if (error || !data?.signedUrl) {
+      throw new AppError({ message: "No se pudo generar URL firmada.", statusCode: 502, cause: error });
+    }
+    return data.signedUrl;
+  }
+}
+```
+
+---
+
+## 4. In-Memory Storage Adapter (Testing Fake)
+
+```ts
+// src/infrastructure/adapters/storage/memory-storage.adapter.ts
+import type { StoragePort, PutFileInput, PutFileOutput, StorageFile, PresignedUrlInput } from "@/domains/storage/storage.port";
+import { AppError } from "@/errors/app-error";
+
+export class MemoryStorageAdapter implements StoragePort {
+  private files = new Map<string, StorageFile>();
+
+  private keyOf(bucket: string, key: string): string {
+    return `${bucket}:${key}`;
+  }
+
+  async putFile(input: PutFileInput): Promise<PutFileOutput> {
+    this.files.set(this.keyOf(input.bucket, input.key), input.file);
+    return { key: input.key, bucket: input.bucket, publicUrl: `https://mock.storage/${input.key}` };
+  }
+
+  async getFile(bucket: string, key: string): Promise<StorageFile> {
+    const file = this.files.get(this.keyOf(bucket, key));
+    if (!file) throw new AppError({ message: "Archivo inexistente en memoria.", statusCode: 404 });
+    return file;
+  }
+
+  async deleteFile(bucket: string, key: string): Promise<void> {
+    this.files.delete(this.keyOf(bucket, key));
+  }
+
+  async createPresignedUrl(input: PresignedUrlInput): Promise<string> {
+    return `https://mock.storage/presigned/${input.bucket}/${input.key}?expires=${input.expiresInSeconds}`;
+  }
+}
+```

package/skills/webhook-idempotency/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: webhook-idempotency
+description: Standardized architectural pattern for incoming webhook verification and idempotency guards. Decouples vendor cryptographic signature checks (Stripe, MercadoPago, Svix, GitHub) into isolated adapters, and guarantees single execution via an IdempotencyGuard wrapper backed by persistent storage. TRIGGER when building webhook endpoints, handling payment callbacks, verifying HMAC signatures, or ensuring at-most-once processing.
+---
+
+# Incoming Webhooks, Signature Verification & Idempotency Guards
+
+Architectural pattern for incoming webhooks: decoupled cryptographic signature verification and atomic idempotency guards to protect against duplicate delivery and replay attacks.
+
+---
+
+## 1. The 3 Invariants of Secure Webhooks
+
+1. **Verify Before Anything Else**:
+   - Webhook endpoints must verify HMAC cryptographic signatures using raw request bodies before running any business logic or parsing JSON.
+2. **Idempotency Guard**:
+   - Webhooks are delivered with "at-least-once" guarantees. An `IdempotencyGuard` checks if an event ID was already processed; if so, returns early (HTTP 200) without re-running actions.
+3. **Slim Webhook Controller**:
+   - The webhook controller verifies signatures, claims idempotency, and delegates to an action or dispatches to a queue.
+
+---
+
+## 2. Directory Layout
+
+```text
+src/
+├── controllers/
+│   └── webhooks/
+│       ├── stripe-webhook.controller.ts     # Verifies + Idempotency + Action (<80 lines)
+│       └── mercadopago-webhook.controller.ts # Verifies + Idempotency + Action (<80 lines)
+├── domains/
+│   └── webhooks/
+│       ├── webhook-verifier.port.ts         # Signature verification interface (<40 lines)
+│       └── idempotency.port.ts              # Idempotency storage interface (<40 lines)
+└── infrastructure/
+    ├── adapters/
+    │   ├── webhooks/
+    │   │   ├── stripe-verifier.adapter.ts   # Stripe signature verification (<70 lines)
+    │   │   ├── svix-verifier.adapter.ts     # Svix HMAC verification (<70 lines)
+    │   │   └── mercadopago-verifier.adapter.ts # MP HMAC verification (<70 lines)
+    │   └── idempotency/
+    │       ├── redis-idempotency.adapter.ts # Redis SETNX implementation (<60 lines)
+    │       └── db-idempotency.adapter.ts    # SQL unique constraint implementation (<60 lines)
+    └── guards/
+        └── idempotency.guard.ts             # Idempotency execution wrapper (<70 lines)
+```
+
+---
+
+## 3. Interfaces Contract (`src/domains/webhooks/`)
+
+```ts
+// webhook-verifier.port.ts
+export interface WebhookVerifyInput {
+  rawBody: string | Uint8Array;
+  signatureHeader: string;
+  secret: string;
+}
+
+export interface WebhookVerifierPort<TEvent = unknown> {
+  verify(input: WebhookVerifyInput): Promise<TEvent>;
+}
+
+// idempotency.port.ts
+export interface IdempotencyPort {
+  lockOrSkip(key: string, ttlSeconds: number): Promise<boolean>;
+  markCompleted(key: string): Promise<void>;
+}
+```
+
+---
+
+## 4. Idempotency Guard Implementation
+
+```ts
+// src/infrastructure/guards/idempotency.guard.ts
+import type { IdempotencyPort } from "@/domains/webhooks/idempotency.port";
+
+export class IdempotencyGuard {
+  constructor(private port: IdempotencyPort) {}
+
+  async runOnce<T>(key: string, ttlSeconds: number, fn: () => Promise<T>): Promise<{ executed: boolean; result?: T }> {
+    const acquired = await this.port.lockOrSkip(key, ttlSeconds);
+    if (!acquired) {
+      return { executed: false };
+    }
+
+    try {
+      const result = await fn();
+      await this.port.markCompleted(key);
+      return { executed: true, result };
+    } catch (err) {
+      throw err;
+    }
+  }
+}
+```
+
+---
+
+## 5. Detailed Verifiers & Store References
+
+For real HMAC verifiers (Stripe, Svix, MercadoPago) and Redis/SQL idempotency stores, see:
+- `references/webhook-idempotency-examples.md`