@3lineas/grooveskills 1.7.2 → 1.8.0

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"
+    }
+  ]
+}
+```