@3lineas/grooveskills 1.7.1 → 1.8.0

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

@@ -1,24 +1,34 @@
 ---
 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.
+description: Strict orchestration standards for Controllers, atomic Actions, Pipeline pattern, database Transactions (including Cloudflare D1 batching), and background Queue Adapters. 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
+# Controller Action Orchestration, Pipelines, Transactions & Queues
 
-Architectural standard establishing strict separation of concerns between **Atomic Actions** and **Orchestration Controllers / Queue Workers**.
+Architectural standard establishing strict separation of concerns between **Atomic Actions**, **Declarative Pipelines**, **Transactions (SQL / D1)**, 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**:
+   - Single responsibility. Example: `sanitizeSlugAction`, `ensureAvailableAction`, `persistOrderAction`.
+   - **An Action NEVER calls another Action directly.** No nested Action cascades.
+   - Signature: `(context: TContext) => Promise<TContext> | TContext`.
+
+2. **Controllers & Pipelines are Orchestrators**:
+   - HTTP route handlers and RPC controllers validate inputs, sequence actions through Pipelines (`Pipeline.send(context).through([...actions])`), wrap transactions, and dispatch background jobs via `QueuePort`.
+
+3. **Atomic Multi-Mutation Pipelines (`withTransaction` / `withD1Transaction`)**:
+   - In standard relational databases, wrap actions inside a database transaction handle (`tx`).
+   - In serverless SQLite / Cloudflare D1, wrap pipeline executions with `withD1Transaction`: actions run immediate reads via `tx.db.select()` and stage mutations via `tx.stage(stmt)` to guarantee all-or-nothing rollback using `db.batch()`.
+
+4. **Queue Workers are Slim Controllers**:
    - A queue worker message handler behaves like an HTTP controller: parses payload and delegates to atomic actions.
 
+5. **Hard Size Limit of <200 Lines**:
+   - Controllers, actions, and pipeline steps must remain strictly below 200 lines (target: 20-60 lines).
+
 ---
 
 ## 2. Directory Layout
@@ -26,84 +36,73 @@ Architectural standard establishing strict separation of concerns between **Atom
 ```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)
+│   └── orders/
+│       ├── sanitize-order.action.ts        # Atomic data transform (<50 lines)
+│       ├── ensure-stock.action.ts          # Atomic invariant check (<50 lines)
+│       └── persist-order.action.ts         # Atomic DB persistence (<60 lines)
 ├── controllers/
 │   └── orders/
-│       └── checkout.controller.ts         # Orchestrates actions + Queue (<90 lines)
+│       └── checkout.controller.ts          # Pipeline & Queue Orchestration (<80 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)
+    └── adapters/
+        └── queue/                          # Swappable Queue adapters (Cloudflare, BullMQ, Memory)
 ```
 
 ---
 
-## 3. Domain Queue Contract (`src/domains/queue/queue.port.ts`)
+## 3. Pipeline Orchestration Pattern
 
 ```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 }>;
+import type { Context } from "hono";
+import { Pipeline } from "@/common/utils/pipeline";
+import { sanitizeOrderAction } from "@/actions/orders/sanitize-order.action";
+import { ensureStockAction } from "@/actions/orders/ensure-stock.action";
+import { persistOrderAction } from "@/actions/orders/persist-order.action";
+import type { CheckoutContext } from "@/types/orders/checkout-context.type";
+
+export async function checkoutController(ctx: Context) {
+  const database = ctx.get("db");
+  const validatedPayload = ctx.req.valid("json");
+
+  const finalContext = await Pipeline.send<CheckoutContext>({
+    database,
+    input: validatedPayload,
+  })
+    .through([
+      sanitizeOrderAction,
+      ensureStockAction,
+      persistOrderAction,
+    ]);
+
+  return ctx.json({ success: true, data: finalContext.createdOrder }, 201);
 }
 ```
 
 ---
 
-## 4. Orchestration Controller Pattern
+## 4. Cloudflare D1 Staged Batching (`withD1Transaction`)
+
+For Cloudflare D1, wrap mutations in a staged batch to guarantee ACID rollback:
 
 ```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);
+export async function stageOrderMutationAction(context: CheckoutContext): Promise<CheckoutContext> {
+  const insertStatement = context.database
+    .insert(ordersTable)
+    .values(context.newOrderRecord);
+
+  // Stage statement for atomic db.batch() execution
+  context.transaction?.stage(insertStatement);
+  return context;
 }
 ```
 
 ---
 
-## 5. Detailed Adapters & Workers Reference
+## 5. Detailed Adapters & References
 
-For real implementations of Cloudflare Queues, BullMQ, AWS SQS, and In-Memory Queue adapters, consult:
-- `references/controller-queue-examples.md`
+For real implementations of Cloudflare Queues, BullMQ, AWS SQS, In-Memory Queue adapters, and the full D1 Transaction runner, consult:
+- `./references/controller-queue-examples.md`

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

@@ -1,13 +1,51 @@
-# Implementation Reference: Controller Orchestration & Queue Adapters
+# Implementation Reference: Controller Orchestration, Queues & D1 Transactions
 
-Real-world queue adapters (Cloudflare Queues, BullMQ, AWS SQS, In-Memory) and Slim Worker controllers.
+Real-world queue adapters (Cloudflare Queues, BullMQ, AWS SQS, In-Memory) and atomic Cloudflare D1 transaction runner.
 
 ---
 
-## 1. Cloudflare Queues Adapter
+## 1. Cloudflare D1 Atomic Transaction Runner (`withD1Transaction`)
+
+Cloudflare D1 runs SQLite at the edge, where standard multi-statement transactions are executed via `db.batch()`. The `withD1Transaction` pattern allows actions to stage statements and execute them atomically:
+
+```ts
+import type { DrizzleD1Database } from "drizzle-orm/d1";
+import type { BatchItem } from "drizzle-orm/batch";
+
+export interface D1TransactionContext<TSchema extends Record<string, unknown>> {
+  readonly db: DrizzleD1Database<TSchema>;
+  stage: (statement: BatchItem<"sqlite">) => void;
+}
+
+export async function withD1Transaction<TSchema extends Record<string, unknown>, TResult>(
+  database: DrizzleD1Database<TSchema>,
+  callback: (transaction: D1TransactionContext<TSchema>) => Promise<TResult>
+): Promise<TResult> {
+  const stagedStatements: BatchItem<"sqlite">[] = [];
+
+  const transactionContext: D1TransactionContext<TSchema> = {
+    db: database,
+    stage: (statement) => {
+      stagedStatements.push(statement);
+    },
+  };
+
+  const result = await callback(transactionContext);
+
+  if (stagedStatements.length > 0) {
+    // All staged mutations are executed in a single atomic batch
+    await database.batch(stagedStatements as [BatchItem<"sqlite">, ...BatchItem<"sqlite">[]]);
+  }
+
+  return result;
+}
+```
+
+---
+
+## 2. 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";
 
@@ -18,13 +56,17 @@ export class CloudflareQueueAdapter implements QueuePort {
     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 });
+    } catch (caughtError) {
+      throw new AppError({
+        message: "Error al encolar mensaje en Cloudflare Queues.",
+        statusCode: 502,
+        cause: caughtError,
+      });
     }
   }
 
   async dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }> {
-    await this.queue.sendBatch(jobs.map((j) => ({ body: j, delaySeconds: j.delaySeconds })));
+    await this.queue.sendBatch(jobs.map((job) => ({ body: job, delaySeconds: job.delaySeconds })));
     return { count: jobs.length };
   }
 }
@@ -32,10 +74,9 @@ export class CloudflareQueueAdapter implements QueuePort {
 
 ---
 
-## 2. BullMQ (Redis) Adapter
+## 3. 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";
@@ -45,22 +86,26 @@ export class BullMQAdapter implements QueuePort {
 
   async dispatch<T>(job: QueueJob<T>): Promise<{ jobId: string }> {
     try {
-      const bJob = await this.bullQueue.add(job.name, job.data, {
+      const queuedJob = 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 });
+      return { jobId: String(queuedJob.id) };
+    } catch (caughtError) {
+      throw new AppError({
+        message: "Error al enviar trabajo a BullMQ.",
+        statusCode: 502,
+        cause: caughtError,
+      });
     }
   }
 
   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 },
+      jobs.map((job) => ({
+        name: job.name,
+        data: job.data,
+        opts: { jobId: job.id, delay: job.delaySeconds ? job.delaySeconds * 1000 : undefined },
       }))
     );
     return { count: jobs.length };
@@ -70,19 +115,18 @@ export class BullMQAdapter implements QueuePort {
 
 ---
 
-## 3. In-Memory Queue Adapter (Testing Fake)
+## 4. 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 };
+    const jobId = job.id ?? `job_${this.jobs.length + 1}`;
+    this.jobs.push({ ...job, id: jobId });
+    return { jobId };
   }
 
   async dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }> {
@@ -93,23 +137,3 @@ export class MemoryQueueAdapter implements QueuePort {
   }
 }
 ```
-
----
-
-## 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/error-handling-logging/SKILL.md

@@ -1,99 +1,95 @@
 ---
 name: error-handling-logging
-description: Deterministic error handling with custom AppError, Result/ActionResponse contracts, and structured logging. TRIGGER when designing error boundaries, writing try/catch blocks, handling I/O or network failures, creating domain exceptions, or configuring application loggers.
+description: Deterministic error handling with custom AppError, domain exception hierarchies, silent mode, Result/ActionResponse contracts, and structured logging. TRIGGER when designing error boundaries, writing try/catch blocks, handling I/O or network failures, creating domain exceptions, or configuring application loggers.
 ---
 
 # Error Handling & Structured Logging Standards
 
-Enterprise-grade patterns for deterministic error handling, structured context logging, and safe API error responses.
+Enterprise-grade patterns for deterministic error handling, typed domain exceptions, silent log mode for expected business flows, and safe API error responses.
 
 ---
 
 ## 1. Golden Rules (Non-negotiable)
 
-1. **Typed Domain Errors with `AppError`**:
-   - Never throw raw strings or generic untyped `Error("something failed")`.
-   - Throw structured `AppError` instances with HTTP status code, error code identifier, user-safe message, and optional contextual metadata.
+1. **Hierarchy Based on `AppError`**:
+   - Every domain error or business exception **MUST** extend `AppError`.
+   - Never throw raw strings or generic untyped `Error("failed")` in domain actions or controllers.
 
-2. **Never Swallow Errors Silently**:
-   - Every `catch (err)` block must either:
-     - Recover with an explicit fallback value.
-     - Log with `Logger.error(...)` and re-throw / return an `ActionResponse` failure.
-   - Empty catch blocks (`catch {}`) without explicit intent are forbidden.
+2. **Atomic Domain Exceptions (1 Exception per File)**:
+   - Each custom exception resides in its own atomic file: `@/errors/{domain}/{name}.error.ts` (e.g. `slug-conflict.error.ts`, `user-not-found.error.ts`).
+   - Throw custom errors directly without boilerplate try/catch re-wrapping inside business logic.
 
-3. **Separate User-Safe Messages from Internal Diagnostics**:
-   - The user receives polite, actionable feedback (e.g. *"Unable to complete transaction. Please try again."*).
-   - Internal logs receive complete diagnostic metadata (stack trace, payload params, correlation ID, elapsed time).
+3. **Auto-Logging with `silent: true` for Expected Flows**:
+   - `AppError` emits a warning via structured logger upon instantiation.
+   - For expected user conflicts (e.g. 409 duplicate slug, 404 not found, 400 validation error), set `silent: true` in the constructor to avoid polluting server error alerts.
 
-4. **Result / ActionResponse for Non-fatal Domain Failures**:
-   - Prefer returning `{ success: false, error: "..." }` or `Result<T, E>` across service boundaries when the failure is an expected domain outcome (e.g. validation failure, duplicate email).
+4. **Universal Error Normalization in Catch Blocks**:
+   - Every top-level catch block or global error handler must normalize unknown or unexpected runtime errors into `AppError` subclasses (e.g. `InternalServerError`).
+   - All HTTP responses are formatted via standardized response serialization (`ActionResponse<never>`).
 
-5. **Structured JSON-Ready Logging**:
-   - Avoid `console.log("here 1")` in production code.
-   - Use a structured `Logger` utility emitting timestamp, level (`DEBUG`, `INFO`, `WARN`, `ERROR`), message, and contextual metadata object.
+5. **Separate User-Safe Messages from Internal Diagnostics**:
+   - The user receives courteous, empathetic, and actionable feedback in the configured locale (governed by `ux-writing`).
+   - Internal logs receive complete diagnostic metadata (stack trace, payload params, correlation ID).
 
----
-
-## 2. Standard Contracts
-
-### A. The ActionResponse Contract
-
-```ts
-export type ActionResponse<TData = unknown, TError = string> =
-  | { success: true; data: TData; message?: string }
-  | { success: false; error: TError; message?: string; statusCode?: number };
+6. **Hard Size Limit of <200 Lines**:
+   - Keep atomic exception classes under 40 lines and error handlers concise.
 
-export function successResponse<T>(data: T, message?: string): ActionResponse<T> {
-  return { success: true, data, message };
-}
+---
 
-export function errorResponse(error: string, statusCode = 400): ActionResponse<never> {
-  return { success: false, error, statusCode };
-}
+## 2. Directory Layout
+
+```text
+src/
+├── errors/
+│   ├── app-error.ts                  # Base AppError with auto-logging & silent flag
+│   ├── common/
+│   │   ├── internal-server.error.ts  # 500 error for unhandled exceptions
+│   │   └── validation.error.ts       # 400 error for schema validation
+│   └── {domain}/                     # Domain-specific custom exceptions
+│       ├── slug-conflict.error.ts    # e.g., extends AppError (409, silent: true)
+│       └── entity-not-found.error.ts # e.g., extends AppError (404, silent: true)
+└── types/errors/
+    └── app-error-params.type.ts      # AppError constructor options
 ```
 
-### B. The `AppError` Base Class
+---
 
-See `templates/app-error.template.md` for full implementation.
+## 3. Standard Contracts & Domain Exceptions
 
+### A. Domain Custom Exception Example (`src/errors/stores/slug-conflict.error.ts`)
 ```ts
-export class AppError extends Error {
-  readonly statusCode: number;
-  readonly code: string;
-  readonly details?: unknown;
-
-  constructor(opts: { message: string; statusCode?: number; code?: string; details?: unknown }) {
-    super(opts.message);
-    this.name = "AppError";
-    this.statusCode = opts.statusCode ?? 500;
-    this.code = opts.code ?? "INTERNAL_SERVER_ERROR";
-    this.details = opts.details;
+import { AppError } from "@/errors/app-error";
+
+export class SlugConflictError extends AppError {
+  constructor(
+    slug: string,
+    message = `El enlace '${slug}' ya está registrado. Te sugerimos agregar una palabra o número adicional.`
+  ) {
+    super({
+      message,
+      statusCode: 409,
+      code: "SLUG_ALREADY_IN_USE",
+      details: { slug },
+      silent: true, // Expected business conflict: suppress error log alert
+    });
+    this.name = "SlugConflictError";
   }
 }
 ```
 
----
-
-## 3. Safe Try/Catch Pattern
-
+### B. Universal Catch Normalization Pattern
 ```ts
-import { Logger } from "@/utils/logger";
 import { AppError } from "@/errors/app-error";
-import { type ActionResponse, errorResponse, successResponse } from "@/types/response.types";
-
-export async function executeSafeTask<T>(task: () => Promise<T>): Promise<ActionResponse<T>> {
-  try {
-    const result = await task();
-    return successResponse(result);
-  } catch (error: unknown) {
-    if (error instanceof AppError) {
-      Logger.warn("Expected domain error caught", { code: error.code, message: error.message });
-      return errorResponse(error.message, error.statusCode);
-    }
-
-    Logger.error("Unhandled runtime exception in task execution", { error });
-    return errorResponse("An unexpected error occurred. Please try again later.", 500);
+import { InternalServerError } from "@/errors/common/internal-server.error";
+
+export function normalizeError(caughtError: unknown): AppError {
+  if (caughtError instanceof AppError) {
+    return caughtError;
   }
+  return new InternalServerError({
+    message: "Ocurrió un error inesperado al procesar la solicitud.",
+    cause: caughtError,
+  });
 }
 ```
 
@@ -101,5 +97,5 @@ export async function executeSafeTask<T>(task: () => Promise<T>): Promise<Action
 
 ## 4. Templates
 
-- `templates/app-error.template.md`: Complete extensible `AppError` implementation with serialization.
-- `templates/logger.template.md`: Lightweight structured logger with log levels and JSON output formatting.
+- `./templates/app-error.template.md`: Complete extensible `AppError` base class with `silent` mode.
+- `./templates/logger.template.md`: Lightweight structured logger with contextual metadata.

package/skills/error-handling-logging/templates/app-error.template.md

@@ -1,14 +1,18 @@
-# Template: AppError Class
+# Template: AppError Base Class
 
 Copy or adapt this template when setting up error handling in your project: `src/errors/app-error.ts`.
 
 ```ts
+import { Logger } from "@/utils/logger";
+
 export interface AppErrorOptions {
   message: string;
   statusCode?: number;
   code?: string;
   details?: unknown;
   cause?: unknown;
+  /** When true, suppresses automatic warning logging for expected business conflicts */
+  silent?: boolean;
 }
 
 export class AppError extends Error {
@@ -28,6 +32,11 @@ export class AppError extends Error {
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, AppError);
     }
+
+    if (!options.silent) {
+      const logger = new Logger(`API:Error:${this.name}`);
+      logger.warn(`${this.code}: ${this.message}`, { details: this.details });
+    }
   }
 
   toJSON(): Record<string, unknown> {