@3lineas/grooveskills 1.7.1 → 1.8.0

package/skills/testing-vitest/references/backend-d1-testing-pyramid.md

@@ -0,0 +1,69 @@
+# Implementation Reference: Backend Testing Pyramid & In-Memory D1 Setup
+
+A complete guide for orchestrating Vitest test suites across the 4-tier testing pyramid using in-memory SQLite / Cloudflare D1 emulators.
+
+---
+
+## 1. Global Setup with In-Memory Database (`setup.ts`)
+
+Instead of recreating database tables inside every test file, initialize migrations once on an in-memory database:
+
+```ts
+import { beforeAll, afterAll } from "vitest";
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+import * as schema from "@/db/schema";
+
+const sqliteConnection = new Database(":memory:");
+export const testDb = drizzle(sqliteConnection, { schema });
+
+beforeAll(async () => {
+  // Apply schema migrations automatically before suite execution
+  migrate(testDb, { migrationsFolder: "./drizzle" });
+});
+
+afterAll(() => {
+  sqliteConnection.close();
+});
+```
+
+---
+
+## 2. Testing Transactions & Rollback (Tier 3)
+
+```ts
+import { describe, it, expect } from "vitest";
+import { withD1Transaction } from "@/common/utils/d1-transaction";
+import { testDb } from "@/backend/setup";
+import { usersTable } from "@/db/schema";
+
+describe("D1 Atomic Batch Transactions", () => {
+  it("should rollback all mutations if an error occurs mid-transaction", async () => {
+    const executeFailingTransaction = async () => {
+      await withD1Transaction(testDb as any, async (transaction) => {
+        transaction.stage(
+          testDb.insert(usersTable).values({ id: "user_1", email: "first@example.com" }) as any
+        );
+
+        throw new Error("Simulated failure mid-transaction");
+      });
+    };
+
+    await expect(executeFailingTransaction()).rejects.toThrow("Simulated failure mid-transaction");
+
+    const users = await testDb.select().from(usersTable);
+    expect(users).toHaveLength(0);
+  });
+});
+```
+
+---
+
+## 3. Best Practices Checklist
+
+- [ ] Run migrations on in-memory SQLite rather than hitting live cloud databases.
+- [ ] Reset mutable database state between tests using transaction rollbacks or truncation.
+- [ ] Validate both happy path and rejection paths on every DTO schema.
+- [ ] Ensure route tests never assert raw implementation details, only HTTP status codes and `ActionResponse<T>` envelopes.
+- [ ] Keep every test file strictly below 200 lines.

package/skills/typescript-clean/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: typescript-clean
-description: Advanced TypeScript 5.5+ standards, strict tsconfig rules, discriminated unions, satisfies operator, const type parameters, unknown over any, custom type guards, and elimination of unsafe type assertions (as / any). TRIGGER when writing or modifying TypeScript files (.ts, .tsx), type definitions, tsconfig.json, or when handling complex polymorphic domain models.
+description: Advanced TypeScript 5.5+ standards, strict tsconfig rules, discriminated unions, satisfies operator, const type parameters, unknown over any, atomic type isolation in @/types/, and elimination of unsafe type assertions (as / any). TRIGGER when writing or modifying TypeScript files (.ts, .tsx), type definitions, tsconfig.json, or when handling complex polymorphic domain models.
 ---
 
 # TypeScript Clean Code Standards (TS 5.5+)
 
-Guidelines for writing safe, expressive, and strictly typed TypeScript with zero unsafe casts, exhaustive pattern matching, and modern language features.
+Guidelines for writing safe, expressive, strictly typed TypeScript with zero unsafe casts, exhaustive pattern matching, and atomic domain type isolation.
 
 ---
 
@@ -15,31 +15,57 @@ Guidelines for writing safe, expressive, and strictly typed TypeScript with zero
    - `any` disables the compiler and hides runtime bugs. Use `unknown` with narrowers or generics.
    - Non-null assertion operator `!` assumes runtime state without proof. Use optional chaining `?.` or explicit guard clauses.
 
-2. **Discriminated Unions for Domain States**:
+2. **Strict Type Isolation (`@/types/{domain}/`)**:
+   - In modular domain architectures, **NEVER** write `interface` or `type` definitions inside DTOs, Actions, Routes, or Utility helpers.
+   - Every contract has its own dedicated file: `@/types/{domain}/{name}.type.ts`.
+   - Organize into domains: `common/`, `context/`, `db/`, `pipeline/`, `services/`, and `{domain}/`.
+
+3. **Discriminated Unions for Domain States**:
    - Represent valid combinations of state using tagged unions (`type = "idle" | "loading" | "success" | "error"`).
    - Never use "optional soup" where every field is `x?: string`.
 
-3. **Exhaustive Type Checking with `never`**:
+4. **Exhaustive Type Checking with `never`**:
    - Every `switch` or conditional on a union must have an `assertNever(value)` exhaustive check in default branch.
 
-4. **Favor `satisfies` Over Type Annotations on Literals**:
+5. **Favor `satisfies` Over Type Annotations on Literals**:
    - `satisfies` checks that a value adheres to a contract without widening or discarding specific literal types.
 
-5. **`const` Type Parameters (TS 5.0+)**:
+6. **`const` Type Parameters (TS 5.0+)**:
    - Use `<const T>` in generic helper functions to preserve literal types without requiring `as const` at call site.
 
-6. **Custom Type Guards & Inferred Type Predicates (TS 5.5+)**:
+7. **Custom Type Guards & Inferred Type Predicates (TS 5.5+)**:
    - Use type predicates (`x is TargetType`) or rely on TS 5.5 automatic type narrowing for array filters.
 
-7. **Avoid Unsafe `as` Type Assertions**:
+8. **Avoid Unsafe `as` Type Assertions**:
    - Never use `value as SomeType` to bypass the type checker. Validate with Valibot schema or custom type guard first.
 
+9. **Hard Size Limit of <200 Lines**:
+   - Keep type definition files atomic and concise (target: 10-50 lines).
+
 ---
 
-## 2. Key Patterns
+## 2. Directory Structure for Type Isolation
+
+```text
+src/types/
+├── common/                           # Global shared contracts
+│   └── action-response.type.ts       # interface ActionResponse<T>
+├── context/                          # Infrastructure & runtime execution context
+│   ├── env.type.ts                   # interface Env (Bindings / Secrets)
+│   └── app-context.type.ts           # Context typing (Bindings, Variables)
+├── db/                               # Database client and ORM entities
+│   ├── database-client.type.ts       # Database client handle
+│   └── {entity}.type.ts              # Select / Insert schema types
+└── {domain}/                         # Domain-specific DTO & action contracts
+    ├── create-{entity}-input.type.ts # Inferred from input DTO
+    └── {entity}-response.type.ts     # Inferred from output DTO
+```
 
-### A. Discriminated Unions & Exhaustiveness
+---
 
+## 3. Key Patterns
+
+### A. Discriminated Unions & Exhaustiveness
 ```ts
 export type RequestState<T> =
   | { status: "idle" }
@@ -68,33 +94,27 @@ export function renderStatus<T>(state: RequestState<T>): string {
 ```
 
 ### B. `satisfies` vs Widening Annotations
-
 ```ts
 type RouteConfig = Record<string, { path: string; isProtected: boolean }>;
 
-// ✅ Preserves exact key literals and structure
 export const APP_ROUTES = {
   HOME: { path: "/", isProtected: false },
   DASHBOARD: { path: "/dashboard", isProtected: true },
 } satisfies RouteConfig;
-
-// APP_ROUTES.HOME.path is typed as "/" not string!
 ```
 
 ### C. Const Generic Parameters
-
 ```ts
 export function createEnumSet<const T extends readonly string[]>(values: T): ReadonlySet<T[number]> {
   return new Set(values);
 }
 
-// Inferred as ReadonlySet<"admin" | "editor" | "viewer">
 export const ROLES = createEnumSet(["admin", "editor", "viewer"]);
 ```
 
 ---
 
-## 3. Strict TSConfig Expectations
+## 4. Strict TSConfig Expectations
 
 Always enable:
 - `"strict": true`
@@ -104,8 +124,8 @@ Always enable:
 
 ---
 
-## 4. Sibling Skills
+## 5. Sibling Skills
 
-- **`best-practices`**: Universal clean code rules and 200-line limit.
+- **`best-practices`**: Universal clean code rules, descriptive naming, and 200-line limit.
 - **`valibot-validation`**: Runtime validation inferred to static TS types.
-- Reference guide: `references/js-ts-antipatterns.md`.
+- Reference guide: `./references/js-ts-antipatterns.md`.

package/skills/valibot-validation/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: valibot-validation
-description: Schema validation at system boundaries with Valibot (* as v from "valibot"). Strict type inference (InferInput, InferOutput), input sanitization, pipeline transformations, and courteous user-facing error messages. TRIGGER when defining API request/response schemas, validating forms, parsing external payloads, env configs, or when the project imports 'valibot'.
+description: Schema validation at system boundaries with Valibot (* as v from "valibot"). Strict type inference (InferInput, InferOutput), input sanitization, pipeline transformations, bidirectional DTO isolation, and courteous user-facing error messages. TRIGGER when defining API request/response schemas, validating forms, parsing external payloads, env configs, or when the project imports 'valibot'.
 ---
 
-# Valibot Schema Validation Standards
+# Valibot Schema Validation & DTO Standards
 
-Guidelines for high-performance, modular schema validation at system boundaries using **Valibot** (`* as v from "valibot"`).
+Guidelines for high-performance, modular schema validation at system boundaries and atomic Data Transfer Objects (DTOs) using **Valibot** (`* as v from "valibot"`).
 
 ---
 
@@ -14,29 +14,55 @@ Guidelines for high-performance, modular schema validation at system boundaries
 1. **Namespace Import `* as v from "valibot"`**:
    - Always import Valibot as namespace `import * as v from "valibot";` to prevent naming collisions and keep schemas consistent.
 
-2. **Validate Every Boundary (Zero Unchecked Inputs)**:
-   - Validate every HTTP body, query string, route param, environment variable, and database response crossing boundary lines.
+2. **Schema & DTO Isolation (1 Schema per File)**:
+   - DTO and Schema files (`@/dtos/{domain}/{name}.dto.ts` or `@/schemas/{domain}/`) contain **ONLY** Valibot schemas (`v.object({...})`).
+   - **NEVER** declare TypeScript `type` or `interface` inside a DTO/Schema file. Inferred types belong in `@/types/{domain}/`.
 
-3. **Pipelines with Polite Error Messages (`v.pipe`)**:
+3. **Bidirectional Validation (Input + Output Whitelisting)**:
+   - **Input**: Validate request bodies, query params, and route params via validators (`vValidator` / `sValidator`).
+   - **Output**: Serialize and whitelist outgoing responses with output schemas (`StoreResponseDto`) to eliminate sensitive fields (`passwordHash`, private tokens) and format values (e.g. ISO date conversions).
+
+4. **Pipelines with Polite Error Messages (`v.pipe`)**:
    - Chain schema constraints using `v.pipe(...)`.
    - Provide clear, user-facing error messages on every validation step following the `ux-writing` skill guidelines.
 
-4. **Explicit Type Inference (`v.InferInput` & `v.InferOutput`)**:
-   - Export inferred types for transformations.
+5. **Explicit Type Inference (`v.InferInput` & `v.InferOutput`)**:
    - Use `v.InferOutput<typeof schema>` for validated downstream data, and `v.InferInput<typeof schema>` for raw form inputs.
 
-5. **`v.safeParse` vs `v.parse` Discipline**:
+6. **`v.safeParse` vs `v.parse` Discipline**:
    - Use `v.safeParse` when building user-friendly forms or API endpoints to format issues into polite error responses without throwing.
    - Use `v.parse` for critical startup configurations (like environment variables) where throwing stops catastrophic initialization.
 
+7. **Hard Limit of <200 Lines**:
+   - Keep atomic DTO and schema definitions concise and focused (target: 20-60 lines).
+
+---
+
+## 2. Directory Taxonomy
+
+```text
+src/
+├── dtos/ (or schemas/)
+│   └── {domain}/
+│       ├── create-{entity}.dto.ts       # Request Body Schema
+│       ├── {entity}-param.dto.ts        # URL Param Schema
+│       ├── {entity}-query.dto.ts        # Query Filter Schema
+│       └── {entity}-response.dto.ts     # Whitelist Output Response Schema
+└── types/
+    └── {domain}/
+        ├── create-{entity}-input.type.ts  # v.InferInput<typeof CreateEntityDto>
+        └── {entity}-response.type.ts      # v.InferOutput<typeof EntityResponseDto>
+```
+
 ---
 
-## 2. Standard Schema Example
+## 3. Bidirectional Schema Example
 
+### Input Schema (`src/dtos/users/create-user.dto.ts`):
 ```ts
 import * as v from "valibot";
 
-export const CreateUserSchema = v.object({
+export const CreateUserDto = v.object({
   fullName: v.pipe(
     v.string("El nombre completo es requerido."),
     v.trim(),
@@ -45,22 +71,38 @@ export const CreateUserSchema = v.object({
   email: v.pipe(
     v.string("El correo electrónico es requerido."),
     v.trim(),
+    v.toLowerCase(),
     v.email("Por favor ingresa un correo electrónico válido.")
   ),
-  age: v.pipe(
-    v.number("La edad debe ser un número."),
-    v.integer("La edad debe ser un número entero."),
-    v.minValue(18, "Debes ser mayor de 18 años para registrarte.")
+});
+```
+
+### Output Whitelist Schema (`src/dtos/users/user-response.dto.ts`):
+```ts
+import * as v from "valibot";
+
+export const UserResponseDto = v.object({
+  id: v.string(),
+  fullName: v.string(),
+  email: v.string(),
+  createdAt: v.pipe(
+    v.union([v.date(), v.string(), v.number()]),
+    v.transform((value) => new Date(value).toISOString())
   ),
 });
+```
+
+### Inferred Type Isolation (`src/types/users/create-user-input.type.ts`):
+```ts
+import type * as v from "valibot";
+import type { CreateUserDto } from "@/dtos/users/create-user.dto";
 
-export type CreateUserInput = v.InferInput<typeof CreateUserSchema>;
-export type CreateUserOutput = v.InferOutput<typeof CreateUserSchema>;
+export type CreateUserInput = v.InferInput<typeof CreateUserDto>;
 ```
 
 ---
 
-## 3. Safe Parsing Helper Pattern
+## 4. Safe Parsing Helper Pattern
 
 ```ts
 import * as v from "valibot";
@@ -95,8 +137,9 @@ export function validateSchema<TSchema extends v.BaseSchema<unknown, unknown, v.
 
 ---
 
-## 4. Sibling Skills
+## 5. Sibling Skills
 
 - **`best-practices`**: Universal clean code and `<200` line limits.
 - **`ux-writing`**: Form validation copy and tone standards.
-- **`hono`**: Hono API route integration with `@hono/valibot-validator` and `sValidator`.
+- **`hono`**: Hono API route integration with validation hooks and thin route wrappers.
+- **`typescript-clean`**: Isolated type definitions and strict contracts.

package/skills/workers-rpc-precision/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: workers-rpc-precision
+description: Cloudflare Workers Native RPC (WorkerEntrypoint & Service<T>) and high-precision financial/date calculation standards in Python or TypeScript. TRIGGER when implementing Cloudflare Service Bindings, Workers RPC, decimal financial math (taxes, discounts, totals), billing cycles with timezones, or apps/py-worker.
+---
+
+# Cloudflare Workers RPC & High-Precision Calculations
+
+Architectural standard for zero-overhead, in-memory **Cloudflare Workers RPC** via `WorkerEntrypoint` and `Service<T>`, combined with high-precision financial calculations (`Decimal`) and timezone-aware dates.
+
+---
+
+## 1. Golden Rules (Non-negotiable)
+
+1. **Native Workers RPC (No `fetch()` or Fake HTTP URLs)**:
+   - **NEVER** use `fetch()`, fake URLs (`http://calculator-internal`), or HTTP headers to communicate between bound workers.
+   - Invoke RPC methods directly: `await env.CALCULATOR.calculate_order_totals(payload);`.
+
+2. **Clean Boundary Separation**:
+   - High-precision math and domain calculations live in the specialized worker (`apps/py-worker` or `apps/calculator-worker`).
+   - Business orchestration and API routing live in the primary backend (`apps/backend` or `apps/api`).
+
+3. **High-Precision Arithmetic (Zero Floating-Point for Money)**:
+   - Never use JavaScript `number` or Python `float` for currency, taxes, discounts, or subtotals.
+   - In Python, use `Decimal` from the standard library with explicit quantization (`ROUND_HALF_UP`).
+   - Safely extract data from Pyodide JS proxies using `to_py()` or JSON normalization.
+
+4. **Timezone-Aware Date Computations**:
+   - Compute billing cycles, deadlines, and fiscal periods using explicit timezones (`zoneinfo.ZoneInfo`) and ISO 8601 formatting.
+
+5. **End-to-End TypeScript RPC Contract**:
+   - Define exact RPC parameter and return types in `@/types/services/{service}.type.ts`.
+   - Bind `SERVICE_NAME: Service<YourRpcInterface>` in `@/types/context/env.type.ts`.
+
+6. **Caller Action Isolation**:
+   - Wrap RPC invocations inside dedicated, atomic Actions (`@/actions/{domain}/{name}.action.ts`).
+
+7. **Hard Size Limit: <200 Lines**:
+   - Keep entrypoints, pure arithmetic helpers, and domain handlers under 200 lines (target: 20-80 lines).
+
+---
+
+## 2. Directory Taxonomy
+
+```text
+apps/py-worker/ (or specialized worker)
+├── wrangler.jsonc                       # flags: ["python_workers"] or Service Bindings
+├── requirements.txt                     # Dependencies
+└── src/
+    ├── entry.py                         # WorkerEntrypoint exposing RPC methods (<60 lines)
+    ├── core/
+    │   ├── money.py                     # Pure Decimal math & rounding (<50 lines)
+    │   └── dates.py                     # Pure timezone & datetime logic (<50 lines)
+    └── domains/
+        └── finance/
+            └── calculate_totals.py      # Domain handler (<70 lines)
+
+apps/backend/src/
+├── types/services/
+│   └── calculator-service.type.ts       # TypeScript RPC interface (<50 lines)
+└── actions/finance/
+    └── calculate-totals.action.ts       # Action wrapping RPC call (<40 lines)
+```
+
+---
+
+## 3. End-to-End RPC Blueprint
+
+### Python Worker Entrypoint (`src/entry.py`):
+```python
+from workers import WorkerEntrypoint
+from domains.finance.calculate_totals import handle_calculate_totals
+
+class CalculatorRpcService(WorkerEntrypoint):
+    async def calculate_order_totals(self, data: dict) -> dict:
+        return handle_calculate_totals(data)
+```
+
+### TypeScript RPC Contract (`@/types/services/calculator-service.type.ts`):
+```ts
+export interface OrderItemInput {
+  id?: string;
+  unitPrice: string | number;
+  quantity: number;
+  discountPct?: string | number;
+}
+
+export interface CalculateTotalsPayload {
+  items: OrderItemInput[];
+  taxRatePct: string | number;
+}
+
+export interface CalculateTotalsResult {
+  items: Array<{ id?: string; itemTotal: string }>;
+  subtotal: string;
+  tax: string;
+  total: string;
+}
+
+export interface CalculatorRpcService {
+  calculate_order_totals(data: CalculateTotalsPayload): Promise<CalculateTotalsResult>;
+}
+```
+
+### Caller Action in TypeScript (`@/actions/finance/calculate-totals.action.ts`):
+```ts
+import type { Service } from "@cloudflare/workers-types";
+import type {
+  CalculatorRpcService,
+  CalculateTotalsPayload,
+  CalculateTotalsResult,
+} from "@/types/services/calculator-service.type";
+
+export interface CalculateTotalsActionInput {
+  calculator: Service<CalculatorRpcService>;
+  payload: CalculateTotalsPayload;
+}
+
+export async function calculateTotalsAction(
+  input: CalculateTotalsActionInput
+): Promise<CalculateTotalsResult> {
+  return await input.calculator.calculate_order_totals(input.payload);
+}
+```
+
+---
+
+## 4. Deep References
+
+- `./references/python-worker-rpc-examples.md`: Complete implementations of `money.py`, Pyodide proxy conversion, and billing cycle handlers.

package/skills/workers-rpc-precision/references/python-worker-rpc-examples.md

@@ -0,0 +1,98 @@
+# Implementation Reference: Python Workers RPC & Precision Math
+
+Complete helpers and handlers for high-precision arithmetic, JS proxy conversion, and timezone calculations on Cloudflare Workers.
+
+---
+
+## 1. Pure Decimal Arithmetic (`src/core/money.py`)
+
+```python
+from decimal import Decimal, ROUND_HALF_UP
+
+def to_decimal(val) -> Decimal:
+    return Decimal(str(val))
+
+def round_currency(amount: Decimal, decimals: int = 2) -> Decimal:
+    exponent = Decimal("10") ** -decimals
+    return amount.quantize(exponent, rounding=ROUND_HALF_UP)
+
+def compute_item_total(unit_price: Decimal, quantity: int, discount_pct: Decimal = Decimal(0)) -> Decimal:
+    subtotal = unit_price * quantity
+    discount = subtotal * (discount_pct / Decimal(100))
+    return round_currency(subtotal - discount)
+
+def compute_tax(amount: Decimal, tax_rate_pct: Decimal) -> Decimal:
+    return round_currency(amount * (tax_rate_pct / Decimal(100)))
+```
+
+---
+
+## 2. Safe Pyodide JS Proxy Handler (`src/domains/finance/calculate_totals.py`)
+
+```python
+import json
+from decimal import Decimal
+from typing import Any
+from core.money import to_decimal, compute_item_total, compute_tax, round_currency
+
+try:
+    from js import JSON  # type: ignore
+except ImportError:
+    JSON = None
+
+def handle_calculate_totals(raw_data: Any) -> Any:
+    # Safely convert Pyodide JS Proxy or dict
+    if hasattr(raw_data, "to_py"):
+        data = raw_data.to_py()
+    elif isinstance(raw_data, dict):
+        data = raw_data
+    elif JSON is not None:
+        data = json.loads(JSON.stringify(raw_data))
+    else:
+        data = dict(raw_data)
+
+    items = data.get("items", [])
+    tax_rate = to_decimal(data.get("taxRatePct", 0))
+    subtotal = Decimal("0")
+    processed_items = []
+
+    for item in items:
+        unit_price = to_decimal(item.get("unitPrice", 0))
+        quantity = int(item.get("quantity", 1))
+        discount_pct = to_decimal(item.get("discountPct", 0))
+        item_total = compute_item_total(unit_price, quantity, discount_pct)
+        subtotal += item_total
+        processed_items.append({"id": item.get("id"), "itemTotal": str(item_total)})
+
+    tax = compute_tax(subtotal, tax_rate)
+    total = round_currency(subtotal + tax)
+
+    result = {
+        "items": processed_items,
+        "subtotal": str(subtotal),
+        "tax": str(tax),
+        "total": str(total),
+    }
+
+    if JSON is not None:
+        return JSON.parse(json.dumps(result))
+    return result
+```
+
+---
+
+## 3. Wrangler Service Binding Configuration
+
+```jsonc
+// apps/backend/wrangler.jsonc
+{
+  "name": "my-backend",
+  "services": [
+    {
+      "binding": "CALCULATOR",
+      "service": "my-py-worker",
+      "entrypoint": "CalculatorRpcService"
+    }
+  ]
+}
+```