@3lineas/grooveskills 1.7.1 → 1.8.0

package/skills/hono/SKILL.md

@@ -3,96 +3,103 @@ name: hono
 description: Use when building or modifying Hono APIs, endpoints, middlewares, or actions. TRIGGER when the project imports 'hono', when modifying routes in src/modules/ or actions in src/actions/, or when the user mentions Hono, API endpoints, or routing. Always validate with Valibot (* as v from 'valibot') and adhere to the 'best-practices' skill.
 ---
 
-# Hono Architecture & Opinionated Best Practices
+# Hono Architecture & Thin Route Standards
 
-Standardized guide for building robust, scalable, enterprise-grade Hono applications with isolated domain layers, strict Valibot validation, and typed Actions.
+Standardized guide for building robust, scalable Hono applications with isolated domain layers, strict Valibot validation, typed Actions, and thin route wrappers.
 
 ---
 
 ## 1. Golden Rules (Non-negotiable)
 
 1. **Standard Schema Validator with Valibot**:
-   - Always use **Valibot** (`* as v from "valibot"`) with `@hono/standard-validator` (`sValidator`) or `@hono/valibot-validator`.
-   - Never use Zod.
-2. **Mandatory Path Aliases (`@/...`)**:
-   - Import all internal modules using configured path aliases (`@/actions/...`, `@/schemas/...`, `@/errors/...`).
-3. **Zero Barrel Files**:
-   - Never create `index.ts` files that re-export multiple routes or actions.
-   - Import directly from each specific action and schema file.
+   - Always use **Valibot** (`* as v from "valibot"`) with `@hono/valibot-validator` (`vValidator`) or `@hono/standard-validator` (`sValidator`).
+   - Use `validationHook` to intercept schema issues and emit a standardized `400 Bad Request` with `ActionResponse<never>`.
+
+2. **Strict Route Wrapper (`createRouteHandler`)**:
+   - Endpoints must be thin controllers. Wrap routes with `createRouteHandler({ outputSchema, status }, handler)`.
+   - Handler automatically receives `{ db, logger, env, input, ctx }`, handles try/catch normalization to `AppError`, and returns serialized `ActionResponse<T>`.
+
+3. **Strict Identifier Naming**:
+   - The Hono context parameter is **ALWAYS** named `ctx` (NEVER `c`).
+   - Catch errors are **ALWAYS** named `error` or `caughtError` (NEVER `e` or `err`).
+
 4. **Independent Route per File by Domain**:
-   - Every single endpoint resides in its own file (`src/modules/{domain}/{action}.ts`).
-   - Group them under the domain router `src/modules/{domain}/{domain}.router.ts`.
-5. **Business Logic Exclusively in Actions**:
-   - All business logic lives inside `src/actions/{domain}/{action}.action.ts`.
-   - Routers are slim controllers: validate input, call the action, return the response.
-6. **Database Connections strictly in Actions**:
-   - Never execute SQL, D1, Drizzle, or Prisma queries inside routes or middleware.
-   - The database instance is injected from Hono context (`ctx.get("db")`) into the action function.
-7. **Single Responsibility Principle (SRP)**:
-   - Each action performs **exactly one** business action.
-8. **Hard File Limit**:
-   - Maximum **200 lines per file**.
-9. **Unified Error Handling**:
-   - Throw typed `AppError` instances for business failures.
-   - Wrap I/O operations in `try / catch`, log with structured `Logger`, and re-throw or propagate to `globalErrorHandler`.
-10. **Courteous and Professional User Feedback**:
-    - Return polite, engaging, and solution-oriented messages in English (`ActionResponse<T>`).
+   - Every single endpoint resides in its own file (`src/routes/modules/{domain}/{action}.route.ts`).
+   - Group them under the domain router `src/routes/modules/{domain}/{domain}.router.ts` and mount in root router.
+
+5. **Business Logic Exclusively in Actions / Pipelines**:
+   - All business logic lives in `src/actions/{domain}/{action}.action.ts`.
+   - Never execute SQL, D1, Drizzle, or Prisma queries directly inside route handlers.
+
+6. **Hard Size Limit: <200 Lines Max**:
+   - Keep route endpoints under 60 lines and routers under 50 lines.
+
+7. **Unified Client Response (`ActionResponse<T>`)**:
+   - Every API endpoint response (success or failure) conforms to `ActionResponse<T>` (`success`, `message`, `data`, `error`).
 
 ---
 
 ## 2. Directory Taxonomy
 
 ```text
-apps/api/src/
-├── actions/                         # Pure business logic layer
-│   └── auth/
-│       ├── register-user.action.ts  # One atomic action (< 100 lines)
-│       └── login-user.action.ts
-├── modules/                         # Thin HTTP controllers
-│   └── auth/
-│       ├── register-user.ts         # Endpoint definition (< 80 lines)
-│       └── auth.router.ts           # Domain router mounting endpoints (< 60 lines)
-├── schemas/                         # Valibot schemas
-│   └── auth/
-│       └── register-user.schema.ts  # Strict input schema (< 50 lines)
-├── errors/
-│   ├── app-error.ts                 # Base application error with auto-logging
-│   └── error-handler.ts             # Central Hono error handler
-└── routers/
-    └── api.router.ts                # Root router exporting ApiRouter type for RPC
+src/
+├── routes/
+│   ├── index.ts                     # Main apiRouter mounting domain routers
+│   └── modules/{domain}/
+│       ├── {action}.route.ts        # Atomic endpoint (<60 lines)
+│       └── {domain}.router.ts       # Domain assembly router (<50 lines)
+├── dtos/{domain}/                   # Valibot schemas (<50 lines)
+├── actions/{domain}/                # Atomic business logic (<100 lines)
+└── types/                           # Isolated domain contracts (<50 lines)
 ```
 
 ---
 
-## 3. Valibot Validation Example
+## 3. Thin Route Pattern Example
 
 ```ts
-import { sValidator } from "@hono/standard-validator";
-import * as v from "valibot";
-
-export const loginSchema = v.object({
-  email: v.pipe(
-    v.string("Please provide your email address."),
-    v.email("Please provide a valid email address.")
-  ),
-  password: v.pipe(
-    v.string("Password is required."),
-    v.minLength(8, "Your password must be at least 8 characters long.")
-  ),
-});
-
-export type LoginInput = v.InferOutput<typeof loginSchema>;
+import { Hono } from "hono";
+import { vValidator } from "@hono/valibot-validator";
+import type { AppContext } from "@/types/context/app-context.type";
+import type { CreateUserInput } from "@/types/users/create-user-input.type";
+import { CreateUserDto } from "@/dtos/users/create-user.dto";
+import { UserResponseDto } from "@/dtos/users/user-response.dto";
+import { registerUserAction } from "@/actions/users/register-user.action";
+import { createRouteHandler } from "@/common/utils/route-handler";
+import { validationHook } from "@/common/utils/validation";
+
+export const createUserRoute = new Hono<AppContext>().post(
+  "/",
+  vValidator("json", CreateUserDto, validationHook),
+  createRouteHandler<unknown, typeof UserResponseDto, CreateUserInput>(
+    { outputSchema: UserResponseDto, status: 201 },
+    async ({ db, input }) => {
+      return await registerUserAction(db, input!);
+    }
+  )
+);
 ```
 
 ---
 
-## 4. Standard Response Contract
+## 4. Domain Router Assembly
 
 ```ts
-export interface ActionResponse<T = unknown> {
-  success: boolean;
-  message?: string;
-  error?: string;
-  data?: T;
-}
+import { Hono } from "hono";
+import type { AppContext } from "@/types/context/app-context.type";
+import { createUserRoute } from "./create-user.route";
+import { listUsersRoute } from "./list-users.route";
+
+export const usersRouter = new Hono<AppContext>()
+  .route("/", createUserRoute)
+  .route("/", listUsersRoute);
 ```
+
+---
+
+## 5. Templates
+
+- `./templates/router.template.md`: Atomic route template with `createRouteHandler`.
+- `./templates/action.template.md`: Single responsibility Action template.
+- `./templates/schema.template.md`: Valibot schema template with UX microcopy.
+- `./templates/error-handler.template.md`: Centralized error handler template.

package/skills/hono/templates/router.template.md

@@ -1,35 +1,27 @@
 # Hono Route Template
 
-Slim HTTP controller that validates request body with Valibot and delegates directly to the Action.
+Slim HTTP controller that validates request body with Valibot via `validationHook`, uses `createRouteHandler`, and delegates to the Action.
 
 ```ts
 import { Hono } from "hono";
-import { sValidator } from "@hono/standard-validator";
-import { registerUserSchema } from "@/schemas/auth/register-user.schema.ts";
-import { registerUserAction } from "@/actions/auth/register-user.action.ts";
-import type { DatabaseConnection } from "@/actions/auth/register-user.action.ts";
+import { vValidator } from "@hono/valibot-validator";
+import type { AppContext } from "@/types/context/app-context.type";
+import type { RegisterUserInput } from "@/types/auth/register-user-input.type";
+import { RegisterUserDto } from "@/dtos/auth/register-user.dto";
+import { UserResponseDto } from "@/dtos/auth/user-response.dto";
+import { registerUserAction } from "@/actions/auth/register-user.action";
+import { createRouteHandler } from "@/common/utils/route-handler";
+import { validationHook } from "@/common/utils/validation";
 
-export interface CustomVariables {
-  db: DatabaseConnection;
-}
-
-export const registerUserRoute = new Hono<{ Variables: CustomVariables }>().post(
+export const registerUserRoute = new Hono<AppContext>().post(
   "/",
-  sValidator("json", registerUserSchema),
-  async (ctx) => {
-    const input = ctx.req.valid("json");
-    const db = ctx.get("db");
-
-    const createdUser = await registerUserAction(db, input);
-
-    return ctx.json(
-      {
-        success: true,
-        message: "Welcome aboard! Your account has been created successfully.",
-        data: createdUser,
-      },
-      201
-    );
-  }
+  vValidator("json", RegisterUserDto, validationHook),
+  createRouteHandler<unknown, typeof UserResponseDto, RegisterUserInput>(
+    { outputSchema: UserResponseDto, status: 201 },
+    async ({ db, input }) => {
+      const createdUser = await registerUserAction(db, input!);
+      return createdUser;
+    }
+  )
 );
 ```

package/skills/react-core/SKILL.md

@@ -11,158 +11,91 @@ Canonical reference for React fundamentals in GrooveSkills projects: function co
 
 ## 1. Golden Rules (Non-negotiable)
 
-1. **One Component per File & < 200 Lines**:
+1. **Strictly Prohibited: `React.FC` and `React.FunctionComponent`**:
+   - In modern React (React 18 / 19), **NEVER** type components with `React.FC` or `React.FunctionComponent`.
+   - Declare standard functions and type `props` directly in the parameter list.
+   - For components requiring children, type `children: ReactNode` explicitly in the props interface.
+
+2. **One Component per File & < 200 Lines**:
    - Every exported React component resides in its own dedicated `.tsx` file and never exceeds **200 lines**.
    - Extract sub-components or custom hooks (`use-*.ts`) into atomic files before reaching the limit.
-2. **Mandatory Path Aliases (`@/...`) & Zero Barrel Files**:
+
+3. **Domain Custom Hooks for Form Encapsulation**:
+   - Form components must encapsulate their own state using domain hooks (e.g. `useLoginForm`, `useRegisterForm`) instead of bubbling raw `form` and `onSubmit` props up to higher-level screen containers.
+
+4. **Mandatory Path Aliases (`@/...`) & Zero Barrel Files**:
    - Import components, hooks, schemas, and utilities directly via path aliases (`@/components/ui/card`, `@/hooks/use-window-width`).
    - Never create `index.ts` or `index.tsx` barrel files to re-export components or hooks.
-3. **Strict Props Typing (Zero `any`)**:
-   - Define explicit `interface` or `type` declarations for component props.
-   - Treat `props` and `state` as strictly immutable.
-4. **Early Returns for UI States (No Nested Ternaries)**:
+
+5. **Early Returns for UI States (No Nested Ternaries)**:
    - Handle loading, error, and empty states with top-level guard clauses (`if (!data) return <EmptyState />;`) instead of deeply nested JSX conditionals.
-5. **Top-Level Hooks Only (Rules of Hooks)**:
-   - Call hooks unconditionally at the top level of function components or custom hooks—never inside loops, conditions, or nested functions (except React 19's `use()`, covered in `react-advanced`).
+
 6. **Immutable State Updates & Functional Updaters**:
    - Never mutate arrays or objects in place (`items.push()`). Always pass a new reference (`[...items, next]`).
    - Use functional updaters (`setCount((prev) => prev + step)`) whenever next state depends on previous state.
-7. **Compiler-Aware Memoization**:
-   - Do not wrap every value or callback in `useMemo` or `useCallback` by reflex. When the React Compiler is active, it memoizes automatically.
-   - Reserve manual `useMemo` and `useCallback` for stabilizing references passed to `useEffect` dependency arrays or for genuinely expensive computations in uncompiled modules.
-8. **Stable Identity Keys in Lists**:
+
+7. **Stable Identity Keys in Lists**:
    - Always provide a stable, unique `key` derived from domain identity (`item.id`), never the array index (`i`) for dynamic or reorderable lists.
-9. **Controlled Inputs with Single Source of Truth**:
-   - Derive input `value` from state and handle updates via `onChange`, validating user input with **Valibot** (`* as v from "valibot"`) where applicable.
 
 ---
 
-## 2. Components, JSX, Props, and Early Returns
-
-Name components in `PascalCase`. Return a single root element or Fragment (`<>...</>`). Use guard clauses to keep the primary render path flat.
+## 2. Component Typing Standards
 
 ```tsx
-import { useState } from "react";
+import type { ReactNode } from "react";
 
-interface UserSummaryProps {
+// ✅ Component with props
+export interface UserAvatarProps {
   name: string;
-  role?: string;
-  isActive: boolean;
-  step?: number;
+  avatarUrl?: string;
 }
 
-export function UserSummary({ name, role = "Member", isActive, step = 1 }: UserSummaryProps) {
-  const [count, setCount] = useState<number>(0);
-
-  if (!isActive) {
-    return <p className="text-muted">This account is currently inactive.</p>;
-  }
-
+export function UserAvatar({ name, avatarUrl }: UserAvatarProps) {
   return (
-    <section className="user-summary">
-      <h2>Hello, {name} ({role})</h2>
-      <button type="button" onClick={() => setCount((prev) => prev + step)}>
-        Count: {count}
-      </button>
-    </section>
+    <div className="flex items-center gap-2">
+      {avatarUrl ? <img src={avatarUrl} alt={name} /> : null}
+      <span>{name}</span>
+    </div>
   );
 }
-```
-
----
-
-## 3. Core Hooks Guide
-
-- **`useState`**: Holds reactive local state (`const [isOpen, setIsOpen] = useState<boolean>(false);`).
-- **`useEffect`**: Synchronizes with external systems (DOM listeners, timers, subscriptions). Always declare accurate dependencies and return a cleanup function.
-- **`useRef`**: Holds a mutable value across renders without causing re-renders, or references a DOM node.
-- **`useMemo` & `useCallback`**: Deliberate escape hatches to stabilize references for `useEffect` dependency arrays or heavy computations in uncompiled components.
-- **`useContext`**: Reads shared state from a `Context` higher in the tree (`<ThemeContext value={theme}>` in React 19).
-
-```tsx
-import { useEffect, useRef, useState } from "react";
-
-export function AutoFocusWindowTracker() {
-  const inputRef = useRef<HTMLInputElement>(null);
-  const [width, setWidth] = useState<number>(() => window.innerWidth);
-
-  useEffect(() => {
-    inputRef.current?.focus();
-    const handleResize = (): void => setWidth(window.innerWidth);
-    window.addEventListener("resize", handleResize);
-    return () => window.removeEventListener("resize", handleResize);
-  }, []);
-
-  return <input ref={inputRef} placeholder={`Viewport: ${width}px`} />;
-}
-```
-
----
-
-## 4. Composition, Lists, and Controlled Inputs
-
-Favor composition via `children` over bloated configuration props, use stable domain keys (`todo.id`) for lists, and bind controlled inputs to state:
-
-```tsx
-import { useState, type ReactNode } from "react";
-
-export interface TodoItem {
-  id: string;
-  text: string;
-  done: boolean;
-}
 
-export function TodoCard({
-  title,
-  todos,
-  children,
-}: {
+// ✅ Component with children
+export interface CardProps {
   title: string;
-  todos: TodoItem[];
-  children?: ReactNode;
-}) {
-  const [filter, setFilter] = useState<string>("");
-
-  if (todos.length === 0) {
-    return <p>Your task list is clear. Add a new item to get started.</p>;
-  }
-
-  const visible = todos.filter((t) => t.text.toLowerCase().includes(filter.toLowerCase()));
+  children: ReactNode;
+}
 
+export function Card({ title, children }: CardProps) {
   return (
-    <article className="card">
-      <h2>{title}</h2>
-      <input
-        value={filter}
-        onChange={(event) => setFilter(event.target.value)}
-        placeholder="Filter tasks..."
-      />
-      <ul>
-        {visible.map((todo) => (
-          <li key={todo.id}>{todo.done ? <s>{todo.text}</s> : todo.text}</li>
-        ))}
-      </ul>
+    <section className="rounded-lg border p-4">
+      <h3 className="font-semibold text-lg">{title}</h3>
       {children}
-    </article>
+    </section>
   );
 }
+
+// ✅ Component without props
+export function EmptyState() {
+  return <p className="text-muted-foreground text-sm">No items found.</p>;
+}
 ```
 
 ---
 
-## 5. Anti-Patterns to Avoid
+## 3. Anti-Patterns to Avoid
 
 | Anti-Pattern | Why It Fails | Correct Pattern |
 | :--- | :--- | :--- |
+| `export const Button: React.FC<Props>` | Verbose, breaks TS generics, legacy implicit children | `export function Button({ label }: ButtonProps)` |
 | Mutating state in place (`items.push(next)`) | Same array reference; React skips re-render | Create a new reference: `setItems((prev) => [...prev, next])` |
-| Calling hooks after `if` or inside loops | Breaks React's deterministic hook call order | Call hooks unconditionally at the top level; branch on results |
+| Calling hooks after `if` or inside loops | Breaks React's deterministic hook call order | Call hooks unconditionally at top level |
 | Using array index `key={i}` on dynamic lists | Misattributes component state on insert, delete, or sort | Use a stable domain identifier: `key={item.id}` |
-| Fetching or deriving synchronous state inside `useEffect` | Triggers an extra render pass and causes UI flicker | Derive values inline during render; use `use()` / Suspense or Actions for async data (`react-advanced`) |
 | Re-exporting components via `components/index.ts` | Violates Zero Barrel Files and harms tree-shaking | Import directly from `@/components/ui/card` |
 
 ---
 
-## 6. Sibling Skills
+## 4. Sibling Skills
 
 - **`best-practices`**: Universal clean architecture, `< 200` lines limit, `@/` path aliases, strict typing, and courteous user feedback.
-- **`react-advanced`**: React 19 platform features, React Compiler 1.0 auto-memoization, concurrent rendering (`useTransition`, `useDeferredValue`, `Suspense`), `use()`, Actions (`useActionState`, `useOptimistic`, `useFormStatus`), context optimization, virtualization, and RSC boundaries.
+- **`react-advanced`**: React 19 platform features, React Compiler auto-memoization, concurrent rendering, and RSC boundaries.
+- **`react-create-page`**: Page coordinator architecture, custom domain hooks, and Valibot forms.

package/skills/testing-vitest/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: testing-vitest
-description: Clean, deterministic unit and integration testing with Vitest. Enforces Arrange-Act-Assert (AAA), behavioral testing over implementation details, in-memory fakes over brittle mocks, strict assertions, and boundary/edge case test matrices. TRIGGER when writing, maintaining, or fixing automated tests (*.test.ts, *.spec.ts), test utilities, or testing infrastructure with Vitest.
+description: Clean, deterministic unit, integration, and HTTP route testing with Vitest. Enforces Arrange-Act-Assert (AAA), behavioral testing over implementation details, in-memory SQLite/D1 fakes over brittle mocks, four-tier testing pyramid, and strict assertion contracts. TRIGGER when writing, maintaining, or fixing automated tests (*.test.ts, *.spec.ts), test utilities, or testing infrastructure with Vitest.
 ---
 
-# Vitest Testing Standards
+# Vitest Testing Standards & 4-Tier Backend Pyramid
 
-Guidelines for authoring reliable, fast, and maintainable unit and integration tests with **Vitest**.
+Guidelines for authoring reliable, fast, and maintainable unit, integration, and route tests with **Vitest**.
 
 ---
 
@@ -22,88 +22,95 @@ Guidelines for authoring reliable, fast, and maintainable unit and integration t
      - `// Assert`: Verify outputs and invariants.
 
 3. **In-Memory Fakes Over Brittle Mocks**:
-   - Prefer in-memory fakes (e.g., `FakeUserRepository`, `MemoryStorage`) over deeply nested `vi.spyOn()` or mock chains.
-   - Only mock external boundaries (network HTTP calls, system clocks, third-party APIs).
+   - Prefer in-memory fakes (e.g., `testDb` backed by `:memory:` SQLite / D1 emulator) over mock chains.
+   - Only mock external boundaries (network HTTP calls, system clocks, third-party payment APIs).
 
-4. **Deterministic & Isolated (Zero Shared Mutable State)**:
-   - Each test must run independently in any order without relying on state from preceding tests.
-   - Use `beforeEach` strictly to reset test fixtures.
+4. **Four-Tier Testing Pyramid**:
+   - **Tier 1 (DTOs / Schemas)**: Test constraint validations, sanitization, trims, and invalid payload rejections.
+   - **Tier 2 (Actions)**: Test isolated business logic functions with typed context.
+   - **Tier 3 (Transactions)**: Test multi-mutation atomic batching and rollback mechanics.
+   - **Tier 4 (HTTP Routes)**: Mount thin routes on `testApp`, inject `testDb`, and verify HTTP lifecycle with `testApp.request()`.
 
-5. **Exhaustive Edge Cases & Failure Modes**:
-   - Always test boundary values: empty strings, zero, negative numbers, missing optional fields, expired tokens, and rejected promises.
-   - Never write happy-path-only tests.
+5. **Mandatory Response Envelope Validation (`ActionResponse<T>`)**:
+   - Route tests must assert that responses adhere to `ActionResponse<T>` (`success`, `message`, `data`, `error`).
+   - Verify that sensitive fields (e.g. `passwordHash`) are stripped by output whitelisting schemas.
 
-6. **Clear, Intention-Revealing Test Names**:
-   - Use descriptive sentences: `it("should calculate tax accurately when order total exceeds threshold")`.
-   - Avoid vague names like `it("works")` or `it("test 1")`.
+6. **Hard Size Limit: <200 Lines**:
+   - Keep test files focused and under 200 lines (target: 30-100 lines).
 
 ---
 
-## 2. Standard Test Pattern (AAA)
-
-```ts
-import { describe, it, expect } from "vitest";
-import { calculateDiscount } from "./calculate-discount";
-
-describe("calculateDiscount", () => {
-  it("should apply 15% discount when user is a premium member", () => {
-    // Arrange
-    const originalPrice = 100;
-    const isPremium = true;
-
-    // Act
-    const finalPrice = calculateDiscount(originalPrice, isPremium);
+## 2. Directory Taxonomy
+
+```text
+packages/testing/src/backend/ (or tests/)
+├── setup.ts                    # Global testDb initialization & migrations
+├── mocks/
+│   └── in-memory-d1.ts         # In-memory SQLite emulator applying migrations
+└── {domain}/
+    ├── {entity}-dto.test.ts    # Tier 1: Schema validation tests
+    ├── {domain}-actions.test.ts# Tier 2: Pipeline actions unit tests
+    └── {action}.route.test.ts  # Tier 4: Route integration tests
+```
 
-    // Assert
-    expect(finalPrice).toBe(85);
-  });
+---
 
-  it("should return unchanged price when discount percentage is zero", () => {
-    // Arrange & Act
-    const finalPrice = calculateDiscount(50, false);
+## 3. Four-Tier Pattern Examples
 
-    // Assert
-    expect(finalPrice).toBe(50);
+### Tier 1: DTO Validation Test
+```ts
+import { describe, it, expect } from "vitest";
+import * as v from "valibot";
+import { CreateUserDto } from "@/dtos/users/create-user.dto";
+
+describe("Users DTO Validation", () => {
+  it("should accept valid payload and lowercase email", () => {
+    const input = { fullName: "Carlos Santana", email: "CARLOS@EXAMPLE.COM" };
+    const parsed = v.parse(CreateUserDto, input);
+    expect(parsed.email).toBe("carlos@example.com");
   });
 
-  it("should throw an AppError when input price is negative", () => {
-    // Arrange, Act & Assert
-    expect(() => calculateDiscount(-10, true)).toThrowError(/Price must be non-negative/);
+  it("should reject invalid email", () => {
+    expect(() => v.parse(CreateUserDto, { fullName: "Carlos", email: "invalid" })).toThrow();
   });
 });
 ```
 
----
-
-## 3. Mocking External Boundaries Safely
-
+### Tier 4: Route Integration Test with `testApp.request()`
 ```ts
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { fetchExchangeRate } from "./fetch-exchange-rate";
-
-describe("fetchExchangeRate", () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
+import { describe, it, expect, vi } from "vitest";
+import { Hono } from "hono";
+import { createUserRoute } from "@/routes/modules/users/create-user.route";
+import { testDb } from "@/backend/setup";
+import type { AppContext } from "@/types/context/app-context.type";
+import type { ActionResponse } from "@/types/common/action-response.type";
+
+describe("POST /users Route Integration", () => {
+  const testApp = new Hono<AppContext>();
+  testApp.use("*", async (ctx, next) => {
+    ctx.set("db", testDb);
+    ctx.set("logger", { info: vi.fn(), warn: vi.fn(), error: vi.fn() } as any);
+    await next();
   });
+  testApp.route("/users", createUserRoute);
 
-  it("should parse rate safely when API returns 200", async () => {
-    const fakeFetch = vi.fn().mockResolvedValue({
-      ok: true,
-      json: async () => ({ rate: 1.08 }),
+  it("should return 201 with ActionResponse contract", async () => {
+    const response = await testApp.request("/users", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ fullName: "Valeria Gomez", email: "valeria@example.com" }),
     });
-    vi.stubGlobal("fetch", fakeFetch);
-
-    const rate = await fetchExchangeRate("EUR", "USD");
 
-    expect(rate).toBe(1.08);
-    expect(fakeFetch).toHaveBeenCalledWith(expect.stringContaining("EUR/USD"));
+    expect(response.status).toBe(201);
+    const json = (await response.json()) as ActionResponse<{ id: string; passwordHash?: string }>;
+    expect(json.success).toBe(true);
+    expect(json.data?.passwordHash).toBeUndefined();
   });
 });
 ```
 
 ---
 
-## 4. Sibling Skills
+## 4. Deep References
 
-- **`best-practices`**: Universal clean code rules.
-- **`error-handling-logging`**: Testing expected `AppError` throws and error payloads.
+- `./references/backend-d1-testing-pyramid.md`: Comprehensive guide for In-Memory SQLite/D1 setup and test matrices.