nextjs-hackathon-stack 0.1.27 → 0.1.29

package/README.md

@@ -1,6 +1,6 @@
 # nextjs-hackathon-stack
 
-> Scaffold a full-stack Next.js 15 hackathon starter in one command.
+> Scaffold a full-stack Next.js hackathon starter in one command.
 
 ```bash
 npx nextjs-hackathon-stack my-app
@@ -10,68 +10,57 @@ npx nextjs-hackathon-stack my-app
 
 | Layer | Tool |
 |---|---|
-| Framework | Next.js 15 + App Router |
+| Framework | Next.js 16 + App Router |
 | Database | Supabase (PostgreSQL) |
 | Auth | Supabase Auth (`@supabase/ssr`) |
 | ORM | Drizzle + drizzle-zod (schema + migrations) |
 | Runtime Queries | supabase-js (RLS active) |
 | Client State | TanStack Query v5 |
-| Validation | Zod (auto-generated via drizzle-zod) |
 | Forms | React Hook Form + Zod resolver |
 | UI | shadcn/ui + Tailwind CSS v4 |
-| AI Streaming | Vercel AI SDK + AI Gateway |
-| LLM | Google Gemini 2.0 Flash (`google/gemini-2.0-flash`) |
-| Testing | Vitest + React Testing Library + Playwright |
+| Testing | Vitest + Playwright (100% coverage enforced) |
+| Code Quality | ESLint 9 + Husky + lint-staged |
+| AI Tooling | Cursor rules/agents/skills + Claude Code instructions |
 
 ## Quick start
 
 ```bash
-# Create project
 npx nextjs-hackathon-stack my-app
 cd my-app
 
-# .env.local was created automatically — fill in your keys:
+# Fill in .env.local (created automatically):
 #   NEXT_PUBLIC_SUPABASE_URL      → supabase.com > Project Settings > API
 #   NEXT_PUBLIC_SUPABASE_ANON_KEY → supabase.com > Project Settings > API
 #   DATABASE_URL                  → supabase.com > Project Settings > Database
-#   AI_GATEWAY_URL                → vercel.com > AI > Gateways
 
-npm run dev
+pnpm db:migrate
+pnpm dev
 ```
 
 ## Options
 
-```bash
-npx nextjs-hackathon-stack my-app --skip-install
-```
-
-| Flag | Description |
+| Argument / Flag | Description |
 |---|---|
-| `--skip-install` | Skip `npm install` and `shadcn/ui` init |
+| `[project-name]` | Directory name for the new project |
+| `--skip-install` | Skip `pnpm install` and `shadcn/ui` init |
 
-## Features
+## What the CLI does
 
-- **Auth** — Email/password login with Supabase Auth, Server Actions, protected routes
-- **AI Chat** — Streaming chat with Gemini 2.0 Flash via Vercel AI Gateway (Edge runtime)
-- **TDD-ready** — 100% coverage enforced, Vitest + Playwright preconfigured
-- **Cursor AI** — Rules, agents, and skills preconfigured for the full stack
+1. Copies the template into `[project-name]/`
+2. Replaces `{{projectName}}` placeholders with the actual project name
+3. Installs dependencies with `pnpm`
+4. Initialises shadcn/ui components
+5. Sets up a git repo with Husky pre-commit hooks
 
-## Architecture
+## Requirements
 
-Feature-based structure:
+- Node >= 22
+- pnpm
 
-```
-src/
-├── app/           # Next.js routing + layouts
-├── features/
-│   ├── auth/      # Login form, server actions, session hook
-│   └── chat/      # AI chat (streaming)
-├── shared/
-│   ├── lib/       # Supabase clients, AI
-│   ├── db/        # Drizzle schema + migrations
-│   └── components/# Providers + shadcn/ui
-└── e2e/           # Playwright e2e tests
-```
+## Pre-built features
+
+- **Auth** — Email/password login, logout, `useSession` hook, protected routes
+- **Todos** — Full CRUD with server actions, add form, todo list
 
 ## License
 

package/dist/index.js

@@ -122,7 +122,7 @@ async function scaffold(projectName, skipInstall) {
     } catch {
       spinner2.stop("shadcn/ui init failed \u2014 run manually: npx shadcn@latest init");
     }
-    const components = ["button", "input", "card", "form", "label"];
+    const components = ["button", "input", "card", "form", "label", "sonner"];
     for (const component of components) {
       spinner2.start(`Adding shadcn/ui component: ${component}`);
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextjs-hackathon-stack",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Scaffold a full-stack Next.js hackathon starter",
   "type": "module",
   "bin": {

package/template/.cursor/agents/backend.md

@@ -81,3 +81,4 @@ export async function createUser(formData: FormData) {
 - Never expose `DATABASE_URL` to the browser
 - RLS policies are required before any table goes to production
 - Validate all mutation inputs with Zod on the server side
+- Server actions that mutate data must return `ActionResult` from `@/shared/lib/action-result` — never return `void`. This enables the frontend to show toast feedback.

package/template/.cursor/agents/frontend.md

@@ -39,6 +39,15 @@ export function InteractiveComponent() {
 }
 ```
 
+## Toast Feedback
+
+All user-initiated actions that modify the database must show a toast (success or error) via `sonner`. Never let a mutation complete silently.
+
+- Call `toast.success(message)` on success, `toast.error(message)` on failure
+- For direct action calls: read the returned `ActionResult` and show the toast immediately
+- For `useActionState` forms: use a `useEffect` on state changes to trigger toasts
+- Exception: if the action redirects to another page, no success toast is needed
+
 ## Guardrails
 - Write RTL tests for every component
 - Verify a11y before marking work done

package/template/.cursor/agents/technical-lead.md

@@ -54,6 +54,7 @@ The technical-lead is the orchestrator. Every request passes through here first.
 - [ ] Proper layer separation
 - [ ] Edge runtime on all AI routes (Risk 3)
 - [ ] TanStack Query is NOT used for mutations (Risk 1)
+- [ ] Every DB mutation shows toast feedback to the user (success or error via `sonner`)
 
 ## Guardrails
 - Reject any PR without test coverage

package/template/.cursor/rules/architecture.mdc

@@ -40,3 +40,5 @@ If two features share logic, move it to `shared/`.
 - Always `"use server"` at top of file
 - Validate input with Zod before any business logic
 - Return typed result objects, use `redirect()` for navigation
+- Actions that mutate data must return `ActionResult` from `@/shared/lib/action-result` — never return `void`
+- The calling component is responsible for showing `toast.success()` / `toast.error()` based on the result

package/template/.cursor/rules/coding-standards.mdc

@@ -51,3 +51,10 @@ Never write implementation before tests exist.
 - Prefer `type` over `interface` for data shapes
 - Use `satisfies` for type-checked literals
 - Use `as const` for immutable literals
+
+## Pre-commit Quality Gates
+Every commit must pass two sequential gates:
+1. **lint-staged** — runs `eslint --max-warnings 0` on staged `.ts/.tsx` files. Any lint warning or error blocks the commit immediately (before the slower test suite runs).
+2. **Full test suite** — runs `vitest run --coverage` with 100% branch/function/line/statement coverage required.
+
+Code that fails either gate cannot be committed.

package/template/.cursor/rules/forms.mdc

@@ -57,3 +57,37 @@ export async function myAction(_prev: State, formData: FormData): Promise<State>
   redirect("/success");
 }
 ```
+
+## Toast Feedback
+
+Every action that affects the database MUST show a toast to the user. No mutation should complete silently.
+
+- Use `toast.success(message)` for successful operations
+- Use `toast.error(message)` for failed operations
+- Import `toast` from `sonner`
+- Server actions that mutate data must return `ActionResult` from `@/shared/lib/action-result` (not `void`)
+- Exception: if the action redirects to another page on success, no success toast is needed (the user sees the new page)
+
+### Pattern A — Direct action call (button onClick, non-`useActionState` forms)
+```typescript
+import { toast } from "sonner";
+import type { ActionResult } from "@/shared/lib/action-result";
+
+startTransition(async () => {
+  const result = await myAction(id);
+  if (result.status === "success") toast.success(result.message);
+  else toast.error(result.message);
+});
+```
+
+### Pattern B — `useActionState` forms
+```typescript
+import { useEffect } from "react";
+import { toast } from "sonner";
+
+const [state, formAction] = useActionState(myAction, { status: "idle" });
+
+useEffect(() => {
+  if (state.status === "error") toast.error(state.message);
+}, [state]);
+```

package/template/.husky/pre-commit

@@ -1 +1,2 @@
+npx lint-staged
 vitest run --coverage

package/template/README.md

@@ -1,6 +1,6 @@
 # {{projectName}}
 
-Full-stack Next.js 16 hackathon starter.
+Full-stack Next.js 16 hackathon starter with pre-built auth and todos.
 
 ## Stack
 
@@ -14,8 +14,8 @@ Full-stack Next.js 16 hackathon starter.
 | State | TanStack Query v5 |
 | Forms | React Hook Form + Zod |
 | UI | shadcn/ui + Tailwind CSS v4 |
-| AI | Vercel AI SDK + MiniMax M2.1 |
 | Testing | Vitest + Playwright |
+| Code Quality | ESLint 9 + Husky + lint-staged |
 
 ## Getting Started
 
@@ -28,17 +28,12 @@ Full-stack Next.js 16 hackathon starter.
 NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
 NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
 DATABASE_URL=postgresql://postgres.your-project-id:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
-
-# AI — Vercel AI Gateway (default: MiniMax M2.1)
-# Create gateway at: https://vercel.com > AI > Gateways
-AI_GATEWAY_URL=https://gateway.ai.vercel.app/v1/your-team-id/your-gateway-id
-AI_API_KEY=
 ```
 
 ### 2. Apply database migrations
 
 ```bash
-pnpm db:migrate    # aplica las migraciones a la base de datos
+pnpm db:migrate
 ```
 
 ### 3. Run the dev server
@@ -53,12 +48,18 @@ pnpm dev
 pnpm dev             # Start dev server
 pnpm build           # Production build
 pnpm lint            # Lint (0 warnings allowed)
+pnpm lint:fix        # Lint and auto-fix
 pnpm typecheck       # TypeScript check
 pnpm test            # Unit tests
+pnpm test:unit       # Unit tests (verbose)
+pnpm test:watch      # Watch mode
 pnpm test:coverage   # Tests with coverage (100% required)
 pnpm test:e2e        # Playwright e2e tests
-pnpm db:generate     # Generate Drizzle migrations
-pnpm db:migrate      # Apply migrations
+pnpm db:generate     # Generate Drizzle migrations from schema
+pnpm db:migrate      # Apply migrations to database
+pnpm db:pull         # Introspect DB and generate schema
+pnpm db:push         # Push schema directly (dev only)
+pnpm db:studio       # Open Drizzle Studio GUI
 ```
 
 ## Environment Variables
@@ -68,8 +69,6 @@ pnpm db:migrate      # Apply migrations
 | `NEXT_PUBLIC_SUPABASE_URL` | Supabase > Project Settings > API |
 | `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase > Project Settings > API |
 | `DATABASE_URL` | Supabase > Project Settings > Database > Connection string > Session mode |
-| `AI_GATEWAY_URL` | Vercel > AI > Gateways |
-| `AI_API_KEY` | Your AI provider API key |
 | `NEXT_PUBLIC_APP_URL` | Your deployment URL (default: `http://localhost:3000`) |
 
 See `.env.example` for all required variables with comments.
@@ -77,20 +76,27 @@ See `.env.example` for all required variables with comments.
 ## Architecture
 
 Feature-based structure:
+
 ```
 src/
 ├── app/           # Next.js routing + layouts
-├── features/      # auth | chat
+├── features/
+│   ├── auth/      # Email+password login, logout, session hook, protected routes
+│   └── todos/     # CRUD server actions, add form, todo list
 ├── shared/        # lib | db | components/ui
 └── e2e/           # Playwright tests
 ```
 
 Dependency direction: `features/* → shared/*` (never reverse).
 
+## Pre-commit Hooks
+
+Husky runs `vitest --coverage` on every commit. The commit is blocked if coverage drops below 100%.
+
 ## Cursor AI Setup
 
-Cursor rules, agents, and skills are preconfigured in `.cursor/`.
+Cursor rules, agents, and skills are preconfigured in `.cursor/`:
 
-- **Rules**: always-on guardrails for coding standards, architecture, security
-- **Agents**: specialized roles (technical-lead, frontend, test-qa, etc.)
-- **Skills**: repeatable workflows (`/create-feature`, `/create-api-route`, etc.)
+- **Rules** (11): always-on guardrails for coding standards, architecture, security, and more
+- **Agents** (7): specialized roles (technical-lead, frontend, backend, test-qa, etc.)
+- **Skills** (4): repeatable workflows (`/create-feature`, `/create-api-route`, `/review-branch`, `/security-audit`)

package/template/package.json.tmpl

@@ -39,7 +39,8 @@
     "class-variance-authority": "^0.7",
     "@radix-ui/react-slot": "^1",
     "@radix-ui/react-label": "^2",
-    "lucide-react": "^0.475"
+    "lucide-react": "^0.475",
+    "sonner": "^2"
   },
   "devDependencies": {
     "typescript": "^5",
@@ -72,6 +73,6 @@
     "lint-staged": "^15"
   },
   "lint-staged": {
-    "*.{ts,tsx}": ["vitest related --run"]
+    "*.{ts,tsx}": ["eslint --max-warnings 0"]
   }
 }

package/template/src/features/auth/__tests__/login-form.test.tsx

@@ -4,6 +4,16 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 
 import { LoginForm } from "../components/login-form";
 
+const mockToastError = vi.fn();
+
+vi.mock("sonner", () => ({
+  toast: {
+    success: vi.fn(),
+    error: (...args: unknown[]): unknown => mockToastError(...args),
+  },
+  Toaster: () => null,
+}));
+
 const mockLoginAction = vi.fn().mockResolvedValue({ status: "idle" });
 
 vi.mock("../actions/login.action", () => ({
@@ -75,7 +85,7 @@ describe("LoginForm", () => {
     });
   });
 
-  it("displays server-side error message when action returns error", async () => {
+  it("displays server-side error message and toast when action returns error", async () => {
     // Arrange
     mockLoginAction.mockResolvedValue({ status: "error", message: "Invalid credentials" });
     const user = userEvent.setup();
@@ -90,6 +100,7 @@ describe("LoginForm", () => {
     await waitFor(() => {
       expect(screen.getByRole("alert")).toBeInTheDocument();
       expect(screen.getByText(/invalid credentials/i)).toBeInTheDocument();
+      expect(mockToastError).toHaveBeenCalledWith("Invalid credentials");
     });
   });
 });

package/template/src/features/auth/components/login-form.tsx

@@ -1,8 +1,9 @@
 "use client";
 
 import { zodResolver } from "@hookform/resolvers/zod";
-import { useActionState, useTransition } from "react";
+import { useActionState, useEffect, useTransition } from "react";
 import { useForm } from "react-hook-form";
+import { toast } from "sonner";
 import { z } from "zod";
 
 import { loginAction, type LoginActionState } from "../actions/login.action";
@@ -31,6 +32,10 @@ export function LoginForm() {
     formState: { errors },
   } = useForm<FormValues>({ resolver: zodResolver(schema) });
 
+  useEffect(() => {
+    if (state.status === "error") toast.error(state.message);
+  }, [state]);
+
   const onSubmit = handleSubmit((data) => {
     const fd = new FormData();
     fd.set("email", data.email);

package/template/src/features/todos/__tests__/add-todo-form.test.tsx

@@ -4,7 +4,18 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 
 import { AddTodoForm } from "../components/add-todo-form";
 
-const mockAdd = vi.fn().mockResolvedValue(undefined);
+const mockToastSuccess = vi.fn();
+const mockToastError = vi.fn();
+
+vi.mock("sonner", () => ({
+  toast: {
+    success: (...args: unknown[]): unknown => mockToastSuccess(...args),
+    error: (...args: unknown[]): unknown => mockToastError(...args),
+  },
+  Toaster: () => null,
+}));
+
+const mockAdd = vi.fn();
 
 vi.mock("../actions/todos.action", () => ({
   addTodoAction: (...args: unknown[]): unknown => mockAdd(...args),
@@ -26,6 +37,7 @@ describe("AddTodoForm", () => {
 
   it("llama a addTodoAction con el título al enviar el formulario", async () => {
     // Arrange
+    mockAdd.mockResolvedValue({ status: "success", message: "Tarea agregada" });
     const user = userEvent.setup();
     render(<AddTodoForm />);
 
@@ -39,8 +51,9 @@ describe("AddTodoForm", () => {
     });
   });
 
-  it("limpia el input después de enviar", async () => {
+  it("muestra toast success y limpia el input después de enviar con éxito", async () => {
     // Arrange
+    mockAdd.mockResolvedValue({ status: "success", message: "Tarea agregada" });
     const user = userEvent.setup();
     render(<AddTodoForm />);
     const input = screen.getByRole("textbox", { name: /nueva tarea/i });
@@ -51,10 +64,27 @@ describe("AddTodoForm", () => {
 
     // Assert
     await waitFor(() => {
+      expect(mockToastSuccess).toHaveBeenCalledWith("Tarea agregada");
       expect(input).toHaveValue("");
     });
   });
 
+  it("muestra toast error cuando la acción falla", async () => {
+    // Arrange
+    mockAdd.mockResolvedValue({ status: "error", message: "Error al agregar la tarea" });
+    const user = userEvent.setup();
+    render(<AddTodoForm />);
+
+    // Act
+    await user.type(screen.getByRole("textbox", { name: /nueva tarea/i }), "Tarea fallida");
+    await user.click(screen.getByRole("button", { name: /agregar/i }));
+
+    // Assert
+    await waitFor(() => {
+      expect(mockToastError).toHaveBeenCalledWith("Error al agregar la tarea");
+    });
+  });
+
   it("no envía el formulario si el input está vacío (required)", async () => {
     // Arrange
     const user = userEvent.setup();

package/template/src/features/todos/__tests__/todo-list.test.tsx

@@ -1,11 +1,22 @@
-import { render, screen } from "@testing-library/react";
+import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { describe, it, expect, vi, beforeEach } from "vitest";
 
 import { TodoList } from "../components/todo-list";
 
-const mockToggle = vi.fn().mockResolvedValue(undefined);
-const mockDelete = vi.fn().mockResolvedValue(undefined);
+const mockToastSuccess = vi.fn();
+const mockToastError = vi.fn();
+
+vi.mock("sonner", () => ({
+  toast: {
+    success: (...args: unknown[]): unknown => mockToastSuccess(...args),
+    error: (...args: unknown[]): unknown => mockToastError(...args),
+  },
+  Toaster: () => null,
+}));
+
+const mockToggle = vi.fn();
+const mockDelete = vi.fn();
 
 vi.mock("../actions/todos.action", () => ({
   toggleTodoAction: (...args: unknown[]): unknown => mockToggle(...args),
@@ -59,8 +70,9 @@ describe("TodoList", () => {
     expect(screen.getByText("Comprar leche")).toHaveClass("line-through");
   });
 
-  it("llama a toggleTodoAction al cambiar el checkbox", async () => {
+  it("llama a toggleTodoAction al cambiar el checkbox y muestra toast success", async () => {
     // Arrange
+    mockToggle.mockResolvedValue({ status: "success", message: "Tarea actualizada" });
     const user = userEvent.setup();
     render(<TodoList items={[baseTodo]} />);
 
@@ -68,11 +80,46 @@ describe("TodoList", () => {
     await user.click(screen.getByRole("checkbox"));
 
     // Assert
-    expect(mockToggle).toHaveBeenCalledWith("1");
+    await waitFor(() => {
+      expect(mockToggle).toHaveBeenCalledWith("1");
+      expect(mockToastSuccess).toHaveBeenCalledWith("Tarea actualizada");
+    });
+  });
+
+  it("muestra toast error cuando toggleTodoAction falla", async () => {
+    // Arrange
+    mockToggle.mockResolvedValue({ status: "error", message: "Error al actualizar la tarea" });
+    const user = userEvent.setup();
+    render(<TodoList items={[baseTodo]} />);
+
+    // Act
+    await user.click(screen.getByRole("checkbox"));
+
+    // Assert
+    await waitFor(() => {
+      expect(mockToastError).toHaveBeenCalledWith("Error al actualizar la tarea");
+    });
+  });
+
+  it("llama a deleteTodoAction al pulsar Eliminar y muestra toast success", async () => {
+    // Arrange
+    mockDelete.mockResolvedValue({ status: "success", message: "Tarea eliminada" });
+    const user = userEvent.setup();
+    render(<TodoList items={[baseTodo]} />);
+
+    // Act
+    await user.click(screen.getByRole("button", { name: /eliminar/i }));
+
+    // Assert
+    await waitFor(() => {
+      expect(mockDelete).toHaveBeenCalledWith("1");
+      expect(mockToastSuccess).toHaveBeenCalledWith("Tarea eliminada");
+    });
   });
 
-  it("llama a deleteTodoAction al pulsar Eliminar", async () => {
+  it("muestra toast error cuando deleteTodoAction falla", async () => {
     // Arrange
+    mockDelete.mockResolvedValue({ status: "error", message: "Error al eliminar la tarea" });
     const user = userEvent.setup();
     render(<TodoList items={[baseTodo]} />);
 
@@ -80,6 +127,8 @@ describe("TodoList", () => {
     await user.click(screen.getByRole("button", { name: /eliminar/i }));
 
     // Assert
-    expect(mockDelete).toHaveBeenCalledWith("1");
+    await waitFor(() => {
+      expect(mockToastError).toHaveBeenCalledWith("Error al eliminar la tarea");
+    });
   });
 });

package/template/src/features/todos/__tests__/todos.action.test.ts

@@ -37,20 +37,21 @@ describe("addTodoAction", () => {
     vi.clearAllMocks();
   });
 
-  it("no hace nada si el título está vacío", async () => {
+  it("retorna error si el título está vacío", async () => {
     // Arrange
     const { addTodoAction } = await import("../actions/todos.action");
     const fd = new FormData();
     fd.set("title", "  ");
 
     // Act
-    await addTodoAction(fd);
+    const result = await addTodoAction(fd);
 
     // Assert
+    expect(result.status).toBe("error");
     expect(mockInsert).not.toHaveBeenCalled();
   });
 
-  it("no hace nada si no hay usuario autenticado", async () => {
+  it("retorna error si no hay usuario autenticado", async () => {
     // Arrange
     mockGetUser.mockResolvedValue({ data: { user: null } });
     const { addTodoAction } = await import("../actions/todos.action");
@@ -58,13 +59,14 @@ describe("addTodoAction", () => {
     fd.set("title", "Mi tarea");
 
     // Act
-    await addTodoAction(fd);
+    const result = await addTodoAction(fd);
 
     // Assert
+    expect(result.status).toBe("error");
     expect(mockInsert).not.toHaveBeenCalled();
   });
 
-  it("inserta la tarea y llama a revalidatePath cuando el usuario existe", async () => {
+  it("inserta la tarea, llama a revalidatePath y retorna success cuando el usuario existe", async () => {
     // Arrange
     mockGetUser.mockResolvedValue({ data: { user: { id: "u1" } } });
     mockInsert.mockResolvedValue(undefined);
@@ -73,24 +75,41 @@ describe("addTodoAction", () => {
     fd.set("title", "Nueva tarea");
 
     // Act
-    await addTodoAction(fd);
+    const result = await addTodoAction(fd);
 
     // Assert
+    expect(result.status).toBe("success");
     expect(mockInsert).toHaveBeenCalledWith({ userId: "u1", title: "Nueva tarea" });
     expect(mockRevalidatePath).toHaveBeenCalledWith("/");
   });
 
-  it("no hace nada si el campo title no está presente", async () => {
+  it("retorna error si el campo title no está presente", async () => {
     // Arrange
     const { addTodoAction } = await import("../actions/todos.action");
     const fd = new FormData();
 
     // Act
-    await addTodoAction(fd);
+    const result = await addTodoAction(fd);
 
     // Assert
+    expect(result.status).toBe("error");
     expect(mockInsert).not.toHaveBeenCalled();
   });
+
+  it("retorna error si la inserción lanza una excepción", async () => {
+    // Arrange
+    mockGetUser.mockResolvedValue({ data: { user: { id: "u1" } } });
+    mockInsert.mockRejectedValue(new Error("DB error"));
+    const { addTodoAction } = await import("../actions/todos.action");
+    const fd = new FormData();
+    fd.set("title", "Tarea fallida");
+
+    // Act
+    const result = await addTodoAction(fd);
+
+    // Assert
+    expect(result.status).toBe("error");
+  });
 });
 
 describe("toggleTodoAction", () => {
@@ -98,31 +117,45 @@ describe("toggleTodoAction", () => {
     vi.clearAllMocks();
   });
 
-  it("no hace nada si la tarea no existe", async () => {
+  it("retorna error si la tarea no existe", async () => {
     // Arrange
     mockSelectWhere.mockResolvedValue([]);
     const { toggleTodoAction } = await import("../actions/todos.action");
 
     // Act
-    await toggleTodoAction("non-existent-id");
+    const result = await toggleTodoAction("non-existent-id");
 
     // Assert
+    expect(result.status).toBe("error");
     expect(mockUpdate).not.toHaveBeenCalled();
   });
 
-  it("invierte completed y llama a revalidatePath", async () => {
+  it("invierte completed, llama a revalidatePath y retorna success", async () => {
     // Arrange
     mockSelectWhere.mockResolvedValue([{ id: "1", completed: false }]);
     mockUpdate.mockResolvedValue(undefined);
     const { toggleTodoAction } = await import("../actions/todos.action");
 
     // Act
-    await toggleTodoAction("1");
+    const result = await toggleTodoAction("1");
 
     // Assert
+    expect(result.status).toBe("success");
     expect(mockUpdate).toHaveBeenCalled();
     expect(mockRevalidatePath).toHaveBeenCalledWith("/");
   });
+
+  it("retorna error si la actualización lanza una excepción", async () => {
+    // Arrange
+    mockSelectWhere.mockRejectedValue(new Error("DB error"));
+    const { toggleTodoAction } = await import("../actions/todos.action");
+
+    // Act
+    const result = await toggleTodoAction("1");
+
+    // Assert
+    expect(result.status).toBe("error");
+  });
 });
 
 describe("deleteTodoAction", () => {
@@ -130,16 +163,29 @@ describe("deleteTodoAction", () => {
     vi.clearAllMocks();
   });
 
-  it("elimina la tarea y llama a revalidatePath", async () => {
+  it("elimina la tarea, llama a revalidatePath y retorna success", async () => {
     // Arrange
     mockDelete.mockResolvedValue(undefined);
     const { deleteTodoAction } = await import("../actions/todos.action");
 
     // Act
-    await deleteTodoAction("1");
+    const result = await deleteTodoAction("1");
 
     // Assert
+    expect(result.status).toBe("success");
     expect(mockDelete).toHaveBeenCalled();
     expect(mockRevalidatePath).toHaveBeenCalledWith("/");
   });
+
+  it("retorna error si la eliminación lanza una excepción", async () => {
+    // Arrange
+    mockDelete.mockRejectedValue(new Error("DB error"));
+    const { deleteTodoAction } = await import("../actions/todos.action");
+
+    // Act
+    const result = await deleteTodoAction("1");
+
+    // Assert
+    expect(result.status).toBe("error");
+  });
 });

package/template/src/features/todos/actions/todos.action.ts

@@ -6,30 +6,48 @@ import { revalidatePath } from "next/cache";
 import { db } from "@/shared/db";
 import { todos } from "@/shared/db/schema";
 import { createClient } from "@/shared/lib/supabase/server";
+import type { ActionResult } from "@/shared/lib/action-result";
 
-export async function addTodoAction(formData: FormData): Promise<void> {
+export async function addTodoAction(formData: FormData): Promise<ActionResult> {
   const title = formData.get("title");
-  if (!title || typeof title !== "string" || title.trim() === "") return;
+  if (!title || typeof title !== "string" || title.trim() === "") {
+    return { status: "error", message: "El título no puede estar vacío" };
+  }
 
   const supabase = await createClient();
   const {
     data: { user },
   } = await supabase.auth.getUser();
-  if (!user) return;
-
-  await db.insert(todos).values({ userId: user.id, title: title.trim() });
-  revalidatePath("/");
+  if (!user) return { status: "error", message: "No autenticado" };
+
+  try {
+    await db.insert(todos).values({ userId: user.id, title: title.trim() });
+    revalidatePath("/");
+    return { status: "success", message: "Tarea agregada" };
+  } catch {
+    return { status: "error", message: "Error al agregar la tarea" };
+  }
 }
 
-export async function toggleTodoAction(id: string): Promise<void> {
-  const [todo] = await db.select().from(todos).where(eq(todos.id, id));
-  if (!todo) return;
-
-  await db.update(todos).set({ completed: !todo.completed }).where(eq(todos.id, id));
-  revalidatePath("/");
+export async function toggleTodoAction(id: string): Promise<ActionResult> {
+  try {
+    const [todo] = await db.select().from(todos).where(eq(todos.id, id));
+    if (!todo) return { status: "error", message: "Tarea no encontrada" };
+
+    await db.update(todos).set({ completed: !todo.completed }).where(eq(todos.id, id));
+    revalidatePath("/");
+    return { status: "success", message: "Tarea actualizada" };
+  } catch {
+    return { status: "error", message: "Error al actualizar la tarea" };
+  }
 }
 
-export async function deleteTodoAction(id: string): Promise<void> {
-  await db.delete(todos).where(eq(todos.id, id));
-  revalidatePath("/");
+export async function deleteTodoAction(id: string): Promise<ActionResult> {
+  try {
+    await db.delete(todos).where(eq(todos.id, id));
+    revalidatePath("/");
+    return { status: "success", message: "Tarea eliminada" };
+  } catch {
+    return { status: "error", message: "Error al eliminar la tarea" };
+  }
 }

package/template/src/features/todos/components/add-todo-form.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useRef, useTransition } from "react";
+import { toast } from "sonner";
 
 import { addTodoAction } from "../actions/todos.action";
 
@@ -14,8 +15,13 @@ export function AddTodoForm() {
     e.preventDefault();
     const formData = new FormData(e.currentTarget);
     startTransition(async () => {
-      await addTodoAction(formData);
-      if (inputRef.current) inputRef.current.value = "";
+      const result = await addTodoAction(formData);
+      if (result.status === "success") {
+        toast.success(result.message);
+        if (inputRef.current) inputRef.current.value = "";
+      } else {
+        toast.error(result.message);
+      }
     });
   }
 

package/template/src/features/todos/components/todo-list.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useTransition } from "react";
+import { toast } from "sonner";
 
 import { deleteTodoAction, toggleTodoAction } from "../actions/todos.action";
 
@@ -35,7 +36,11 @@ export function TodoList({ items }: TodoListProps) {
               checked={todo.completed}
               disabled={isPending}
               onChange={() => {
-                startTransition(() => { void toggleTodoAction(todo.id); });
+                startTransition(async () => {
+                  const result = await toggleTodoAction(todo.id);
+                  if (result.status === "error") toast.error(result.message);
+                  else toast.success(result.message);
+                });
               }}
               aria-label={`Marcar "${todo.title}" como completada`}
             />
@@ -48,7 +53,11 @@ export function TodoList({ items }: TodoListProps) {
             type="button"
             disabled={isPending}
             onClick={() => {
-              startTransition(() => { void deleteTodoAction(todo.id); });
+              startTransition(async () => {
+                const result = await deleteTodoAction(todo.id);
+                if (result.status === "error") toast.error(result.message);
+                else toast.success(result.message);
+              });
             }}
             className="rounded px-2 py-1 text-sm text-red-500 hover:bg-red-50"
             aria-label={`Eliminar "${todo.title}"`}

package/template/src/shared/components/providers.tsx

@@ -2,6 +2,7 @@
 
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { useState } from "react";
+import { Toaster } from "sonner";
 
 export function Providers({ children }: { children: React.ReactNode }) {
   const [queryClient] = useState(
@@ -15,5 +16,10 @@ export function Providers({ children }: { children: React.ReactNode }) {
       })
   );
 
-  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <Toaster />
+    </QueryClientProvider>
+  );
 }

package/template/src/shared/lib/action-result.ts

@@ -0,0 +1,3 @@
+export type ActionResult =
+  | { status: "success"; message: string }
+  | { status: "error"; message: string };