nextjs-hackathon-stack 0.1.40 → 0.1.41

package/template/.claude/rules/security.mdc

@@ -0,0 +1,108 @@
+---
+description: Security rules (OWASP, auth, RLS, XSS, CSP). Applied to server code, API routes, actions, auth, and config.
+globs: ["src/**/actions/**", "src/**/api/**", "src/**/lib/supabase/**", "src/app/**/route.ts", "src/app/**/proxy.ts", "*.config.*"]
+alwaysApply: false
+---
+
+# Security Rules
+
+## OWASP Top 10 Awareness
+1. **Injection** — use Drizzle parameterized queries, never string concatenation
+2. **Broken Auth** — Supabase Auth only, no custom auth
+3. **Sensitive Data** — HTTPS-only cookies, no secrets in code
+4. **XSS** — never use `dangerouslySetInnerHTML`, escape user input
+5. **Broken Access Control** — RLS on all tables, auth check in all protected routes
+6. **Security Misconfiguration** — CSP, HSTS, X-Frame-Options in `next.config.ts`
+7. **Insecure Dependencies** — run `pnpm audit` regularly
+8. **SSRF** — validate URLs before fetch
+
+## Environment Variables
+```
+NEXT_PUBLIC_*   → client-safe (Supabase URL, anon key only)
+No prefix       → server-only (DB URL, secret keys)
+```
+
+Never use `NEXT_PUBLIC_` for secret keys.
+
+## Supabase RLS
+- Enable RLS on EVERY table
+- Write explicit allow/deny policies
+- Test RLS policies — never assume they work
+
+## Auth in API Routes and Server Actions
+
+Every Server Action and API route that accesses data must verify auth via `getUser()` before any data access. RLS provides row-level enforcement, but `getUser()` at the action level is required as defense-in-depth — never rely on RLS alone.
+
+```typescript
+export async function POST(request: Request) {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });
+  // ...
+}
+```
+
+Every mutation Server Action must:
+1. Call `getUser()` and return an error result if no user
+2. Scope all queries to `user.id` (even with RLS active)
+
+```typescript
+export async function deleteItemAction(id: string): Promise<ActionResult> {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return { status: "error", message: "No autenticado" };
+
+  const { error } = await supabase.from("items").delete().eq("id", id).eq("user_id", user.id);
+  if (error) return { status: "error", message: "Error al eliminar" };
+
+  revalidatePath("/");
+  return { status: "success", message: "Eliminado" };
+}
+```
+
+## Open Redirect Prevention
+
+Validate all redirect targets — ensure `next`/`redirect` params start with `/` and not `//`. Never redirect to user-controlled URLs without validation.
+
+```typescript
+// ✅ Safe redirect validation
+const next = rawNext.startsWith("/") && !rawNext.startsWith("//") ? rawNext : "/";
+
+// ❌ Unsafe — allows protocol-relative redirects (//evil.com)
+const next = searchParams.get("next") ?? "/";
+```
+
+## Input Validation
+- Validate ALL external input with Zod at the boundary
+- Validate in Server Actions AND API routes
+- Never trust client-side validation alone
+
+## Rate Limiting
+- Apply rate limiting to all AI routes
+- Apply rate limiting to auth endpoints
+- Use Vercel's built-in rate limiting or `@upstash/ratelimit`
+
+## Content Security Policy
+
+`script-src` must not include `'unsafe-eval'`. Avoid `'unsafe-inline'` for scripts — prefer nonce-based CSP. `'unsafe-inline'` is acceptable for `style-src` only.
+
+```typescript
+// ✅ Ideal — nonce-based CSP (no unsafe-inline for scripts)
+`script-src 'self' 'nonce-${nonce}'`,
+"style-src 'self' 'unsafe-inline'",
+
+// ✅ Acceptable intermediate — add a TODO to migrate to nonce-based
+"script-src 'self' 'unsafe-inline'", // TODO: replace with nonce-based CSP
+"style-src 'self' 'unsafe-inline'",
+
+// ✅ Dev-only — unsafe-eval for React debugging features (silences installHook.js warning)
+`script-src 'self' 'unsafe-inline'${isDev ? " 'unsafe-eval'" : ""}`,
+
+// ❌ Never — unsafe-eval unconditionally in production
+"script-src 'self' 'unsafe-eval' 'unsafe-inline'",
+```
+
+## Cookies
+- `httpOnly: true` for auth tokens (Supabase handles this)
+- `secure: true` in production
+- `sameSite: "lax"` minimum

package/template/.claude/rules/supabase.mdc

@@ -0,0 +1,70 @@
+---
+description: Supabase + Drizzle rules. Schema changes require migration — never edit migration files directly.
+globs: ["src/shared/db/**", "src/shared/lib/supabase/**"]
+alwaysApply: false
+---
+
+# Supabase + Drizzle Rules (Risk 2: Zod Schema Drift)
+
+## Drizzle: Schema + Migrations ONLY
+```typescript
+// ✅ Use Drizzle for schema definition
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey(),
+  email: text("email").notNull(),
+});
+
+// ✅ Auto-generate Zod from Drizzle — zero manual Zod for DB types
+export const insertUserSchema = createInsertSchema(users);
+export const selectUserSchema = createSelectSchema(users);
+
+// ❌ NEVER write Zod schemas manually for DB types
+const userSchema = z.object({ id: z.string(), email: z.string() }); // WRONG
+```
+
+## Runtime Reads: Repository Pattern (RLS active)
+
+All reads go through the feature's `queries/` module — never call `supabase.from().select()` inline in pages or actions.
+
+```typescript
+// ✅ Read via repository function
+import { getUserById } from "@/features/users/queries/users.queries";
+const { data, error } = await getUserById(supabase, userId);
+
+// ✅ Repository module — receives supabase client as parameter (DI)
+// src/features/users/queries/users.queries.ts
+import type { createClient } from "@/shared/lib/supabase/server";
+type Client = Awaited<ReturnType<typeof createClient>>;
+
+export async function getUserById(supabase: Client, userId: string) {
+  return supabase.from("users").select("*").eq("id", userId).single();
+}
+
+// ❌ Never inline a SELECT in a page or action
+const { data } = await supabase.from("users").select("*").eq("id", userId); // WRONG in page/action
+
+// ❌ Never use Drizzle for runtime queries
+const users = await db.select().from(usersTable); // WRONG — bypasses RLS
+```
+
+## RLS Mandate
+- Enable RLS on ALL tables in Supabase dashboard
+- Every table must have explicit policies — RLS is not a post-step
+- Default policy template: `CREATE POLICY "users_own_rows" ON <table> FOR ALL USING (user_id = auth.uid());`
+
+## Migrations
+
+Files in `src/shared/db/migrations/` are **auto-generated** by Drizzle CLI — never create, edit, or delete them directly.
+
+| Command | Purpose |
+|---|---|
+| `pnpm db:generate` | Generate migration SQL from schema changes |
+| `pnpm db:migrate` | Apply pending migrations to the database |
+| `pnpm db:push` | Push schema directly to DB (dev only, no migration file) |
+
+Workflow: edit `src/shared/db/<table>.schema.ts` → `pnpm db:generate` → review SQL → `pnpm db:migrate`
+
+## Environment Variables
+- `NEXT_PUBLIC_SUPABASE_URL` + `NEXT_PUBLIC_SUPABASE_ANON_KEY` — client-safe, used in browser + server
+- `DATABASE_URL` — server-only, used by Drizzle for migrations (`drizzle.config.ts`)
+- See `.env.example` for all required variables

package/template/.claude/rules/testing.mdc

@@ -0,0 +1,136 @@
+---
+description: TDD, Vitest, and Playwright testing standards.
+globs: ["**/*.test.*", "**/e2e/**"]
+alwaysApply: false
+---
+
+# Testing Standards
+
+## Iron Rules (Non-Negotiable)
+1. **NEVER modify a test to make it pass** — always fix the implementation code. Tests define the contract. If a test fails, the code is wrong, not the test.
+2. **Tests are immutable during GREEN phase** — only modify tests in RED phase (writing new ones) or REFACTOR phase (improving structure, never weakening assertions)
+3. **Coverage thresholds** — 95% statements/functions/lines, 90% branches. Use `/* v8 ignore next */` only for genuinely unreachable defensive branches
+4. **Every edge case gets a test** — null/undefined, empty string, empty array, boundary values, error responses, timeout, concurrent calls
+5. **AAA is mandatory** — every test uses Arrange-Act-Assert with labeled comments
+
+## TDD Cycle
+1. **RED**: Write failing test describing desired behavior
+2. **GREEN**: Write minimum code to make it pass
+3. **REFACTOR**: Clean up while keeping tests green
+
+## AAA Pattern (Arrange-Act-Assert)
+
+Every test MUST follow the Arrange-Act-Assert structure. No exceptions.
+
+```typescript
+it("shows error message on invalid credentials", async () => {
+  // Arrange
+  const user = userEvent.setup();
+  mockSignIn.mockResolvedValue({ error: { message: "Invalid credentials" } });
+  render(<LoginForm />);
+
+  // Act
+  await user.type(screen.getByLabelText(/email/i), "test@example.com");
+  await user.type(screen.getByLabelText(/password/i), "password123");
+  await user.click(screen.getByRole("button", { name: /sign in/i }));
+
+  // Assert
+  expect(await screen.findByRole("alert")).toHaveTextContent("Invalid credentials");
+});
+```
+
+Rules:
+- **Arrange**: set up state, mocks, render
+- **Act**: perform the single action being tested
+- **Assert**: verify outcome — one logical assertion per test
+- Add blank lines between sections when all three are non-trivial
+- Never skip a section — if Act is empty, you are testing the wrong thing
+
+## Vitest (Unit + Integration)
+- Mock external dependencies only (HTTP calls, Supabase, DB)
+- Test behavior, not implementation details
+- Colocate tests with source: `features/auth/__tests__/`
+- Coverage thresholds are non-negotiable (95% statements/functions/lines, 90% branches — see Iron Rule #3)
+
+```typescript
+// ✅ AAA — tests behavior
+it("shows error message on invalid credentials", async () => {
+  // Arrange
+  mockSignIn.mockResolvedValue({ error: { message: "Invalid credentials" } });
+  render(<LoginForm />);
+
+  // Act
+  await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
+
+  // Assert
+  expect(await screen.findByRole("alert")).toBeInTheDocument();
+});
+
+// ❌ No AAA — tests implementation details, brittle
+it("calls signInWithPassword with correct args", () => { ... });
+```
+
+## Playwright (E2E)
+- **Always use `data-testid` attributes for element selection** — never use visible text or translated labels. Text-based selectors break when copy or i18n changes.
+- Page Object Pattern for complex flows
+- Every user flow needs an e2e test
+
+```typescript
+// ✅ Stable — decoupled from i18n
+await page.getByTestId("submit-button").click();
+
+// ❌ Brittle — breaks if language changes or copy is updated
+await page.getByRole("button", { name: /sign in/i }).click();
+await page.getByLabel(/email/i).fill("...");
+```
+
+```typescript
+test("user can log in", async ({ page }) => {
+  // Arrange
+  await page.goto("/login");
+
+  // Act
+  await page.getByTestId("email-input").fill("user@example.com");
+  await page.getByTestId("password-input").fill("password123");
+  await page.getByTestId("sign-in-button").click();
+
+  // Assert
+  await expect(page).toHaveURL("/");
+});
+```
+
+## Edge Case Checklist
+For every function, ask: what happens with...
+- null / undefined input
+- empty string / empty array / empty object
+- boundary values (0, -1, MAX_SAFE_INTEGER)
+- invalid types (wrong shape, missing fields)
+- API error responses (4xx, 5xx, network failure)
+- Loading / pending states
+- Concurrent calls / race conditions
+- Auth expired / missing session
+
+If any of these apply, write a test for it. No exceptions.
+
+## jsdom Known Limitations (avoid rework cycles)
+
+jsdom does not implement all browser APIs. Hitting these in tests causes failures that require full component rewrites — avoid them upfront:
+
+- **No `HTMLDialogElement` methods** — `dialog.showModal()` and `dialog.close()` throw in jsdom. Use state-controlled visibility (`isOpen` prop / conditional render) instead of the native `<dialog>` API.
+- **No portal-based components in unit tests** — components like `<Toaster>` (sonner), `<Tooltip>`, `<Popover>` render outside the React tree and are unreliable in jsdom. Exclude their wrapper files from coverage; test toast behavior indirectly via the action's `ActionResult`.
+- **Run `pnpm lint` before finishing** — do not leave lint errors to a separate pass. Fix inline as you go.
+
+## Coverage Thresholds
+```typescript
+// vitest.config.ts
+coverage: {
+  thresholds: {
+    branches: 90,
+    functions: 95,
+    lines: 95,
+    statements: 95,
+  },
+}
+```
+
+Use `/* v8 ignore next */` for genuinely unreachable defensive branches (e.g., exhaustive `switch` default arms, type narrowing guards that cannot be hit at runtime).

package/template/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "memory": {
+      "type": "http",
+      "url": "http://localhost:8765/mcp"
+    },
+    "shadcn": {
+      "command": "npx",
+      "args": ["-y", "shadcn@latest", "mcp"]
+    },
+    "supabase": {
+      "type": "http",
+      "url": "https://mcp.supabase.com/mcp?features=docs"
+    }
+  }
+}

package/template/.claude/skills/build-feature/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: build-feature
+description: Plan and implement a new feature following TDD — tech-lead planning, backend + frontend in parallel, review gate, and memory sync. Run in a fresh conversation after /discover-feature. Triggers: 'build feature', 'implement feature', 'start building', 'build from requirements'. NOT for: bug fixes, refactors, or API-only routes (use /create-api-route).
+---
+
+# Build Feature Skill
+
+> **Invoke as:** `/build-feature @.requirements/<feature-name>-<timestamp>.md`
+> Run in **Agent mode** in a **fresh conversation** (not the same one where you ran `/discover-feature`).
+
+## IMPORTANT: Fresh Conversation Required
+
+If this conversation already contains requirements gathering, **start a new conversation** first. Reusing the same context risks hitting the token limit mid-implementation.
+
+If context usage exceeds 60% at any point, stop and tell the user to continue in a new conversation referencing the current step.
+
+---
+
+## Process
+
+### 1. Read the Requirements
+
+Read `.requirements/<feature-name>-<timestamp>.md`. Confirm the file exists and contains both a **Functional Task List** (with acceptance criteria) and a **Technical Task List** (with Parallel Execution Plan groups A/B/C) before proceeding.
+
+- If no spec exists → tell the user to run `/discover-feature <description>` first
+- If the file only has functional tasks (old format) → use the `technical-lead` subagent to produce the Technical Task List before continuing
+
+### 2. Load Architecture Context via MCP Memory
+
+Load project context with targeted queries (token-efficient):
+
+1. Read `package.json` to get the project name (`<project-name>`)
+2. `search_memory` with `tags: ["project:<project-name>", "domain:ui"]` — installed shadcn/ui components
+3. `search_memory` with `tags: ["project:<project-name>", "domain:database"]` — existing schema
+4. `search_memory` with `tags: ["project:<project-name>", "domain:features"]` — existing features and paths
+5. `search_memory` with `tags: ["project:<project-name>", "domain:patterns"]` — canonical pattern references
+6. `search_memory` with `tags: ["project:<project-name>", "domain:rules"]` — active lint/TS rules
+
+**Fallback**: if memory service is unavailable or returns no results, read `.cursor/memory/architecture-snapshot.md` directly.
+
+**Also read `eslint.config.ts` and `tsconfig.json`** to confirm active rules and compiler flags before writing any code.
+
+**Dependency pre-flight:**
+```bash
+pnpm ls drizzle-orm   # Confirm installed version
+pnpm typecheck        # Confirm baseline passes — fix pre-existing errors first
+```
+
+### 3. Planning (Tech Lead)
+
+The requirements file already contains a Technical Task List with parallel execution groups produced during `/discover-feature`. The TL should:
+
+1. **Read the Parallel Execution Plan** from the requirements file (Groups A/B/C + Review Gate)
+2. **Verify against current codebase state** — confirm referenced patterns, schemas, and components still exist
+3. **Identify reuse** from MCP memory:
+   - Which canonical patterns to copy
+   - Which shadcn components are already installed vs need installing
+   - Which shared utilities apply (`formFieldText`, `firstZodIssueMessage`, etc.)
+4. **Plan the test structure**:
+   - One `describe` block per acceptance criterion
+   - Which mocks are needed (`makeSupabaseMock`, HTTP mocks, etc.)
+   - Which edge cases map to test cases from the Functional Task List
+5. **Present a brief implementation summary to the user** and wait for approval before proceeding to Step 4.
+
+> Summary: execution order (which groups run in parallel), which files will be created/modified, any risks or deviations from the plan.
+
+### 4. Create Feature Structure
+
+```
+src/features/<feature-name>/
+├── components/
+├── actions/
+├── queries/
+├── hooks/
+├── api/
+├── lib/
+└── __tests__/
+```
+
+### 5. Pre-Test Setup
+
+Update `vitest.config.ts` to exclude files that cannot be meaningfully tested in jsdom:
+- Drizzle schema file(s) (`src/shared/db/*.schema.ts`)
+- Pure type-only files
+- Portal/browser-API-dependent UI wrappers (e.g., `src/shared/components/ui/sonner.tsx`)
+
+```typescript
+// vitest.config.ts — add to coverage.exclude before writing tests
+exclude: [
+  "src/shared/db/*.schema.ts",
+  "src/shared/components/ui/sonner.tsx",
+]
+```
+
+### 6. TDD: RED Phase
+
+Write ALL test files first — zero implementation code at this stage:
+- `__tests__/<component>.test.tsx` — component tests
+- `__tests__/use-<feature>.test.ts` — hook tests (if applicable)
+- `__tests__/<action>.action.test.ts` — action tests (see `references/server-action-test-template.md`)
+- `__tests__/<feature>.queries.test.ts` — query tests
+
+Import mock helpers from `@/shared/test-utils/supabase-mock` — do not inline mock chains.
+
+**Coverage guidance:** Threshold is 95% statements/functions/lines and 90% branches. Use `/* v8 ignore next */` for genuinely unreachable defensive branches.
+
+**For standard CRUD features**: write tests and implementation per module (queries test+impl → actions test+impl → UI test+impl) instead of strict all-RED-then-all-GREEN.
+
+**BLOCKING GATE — do not proceed until this passes:**
+Run `pnpm test:unit` and paste the output. All new tests must **FAIL** (red). If any new test passes without implementation, the test is wrong — fix it before continuing.
+
+### 7. TDD: GREEN Phase
+
+Follow the **Parallel Execution Plan** from the requirements file:
+
+- **Group A**: run first (foundation — schema, shared types, no dependencies)
+- **Group B**: launch `backend` and `frontend` subagents **in parallel** after Group A completes
+- **Group C**: run after Group B (integration, polish)
+
+Typical assignment:
+
+| backend handles | frontend handles |
+|-----------------|-------------------|
+| `actions/` | `components/` |
+| `queries/` | `page.tsx` |
+| `schema.ts` changes | shadcn component installs |
+| RLS policies | Loading/empty states |
+
+**Do NOT run intermediate verification between sub-tasks.** Complete all GREEN phase work, then run a single verification pass in Step 9.
+
+**BLOCKING GATE — do not proceed until this passes:**
+Run `pnpm test:unit` and paste the output. All tests must **PASS** (green).
+
+### 8. Refactor
+
+Clean up while keeping tests green.
+
+### 9. Verify & Self-Check
+
+Run all three **together** (single pass) and paste output:
+```bash
+pnpm test:coverage   # Must meet thresholds: 95% statements/functions/lines, 90% branches
+pnpm lint            # Must pass with 0 warnings
+pnpm typecheck       # Must pass with 0 errors
+```
+
+If issues are found, fix **all** of them, then run the full trio again once.
+
+Before moving to the review gate, verify manually:
+- [ ] No `any` types: `grep -r ": any" src/features/<feature>/`
+- [ ] No `eslint-disable` comments
+- [ ] All UI text in Spanish, all `it()`/`describe()` text in English
+- [ ] No file over 200 lines
+- [ ] No function over 20 lines
+- [ ] AAA pattern (`// Arrange`, `// Act`, `// Assert`) in every test
+- [ ] `ActionResult` returned from every Server Action mutation
+- [ ] Toast feedback (`toast.success` / `toast.error`) for every mutation
+- [ ] RLS policies written for every new table
+
+### 10. Review Gate
+
+Run @code-reviewer and @security-researcher **in parallel** on the changed files. Fix any findings before marking the feature complete.
+
+This step is not optional. The feature is not done until both reviewers pass.
+
+> **Note for time-critical work:** if the user explicitly says to skip the review gate, you may proceed — but flag the skipped step so it can be done as a follow-up.
+
+### 11. Update Architecture Snapshot & MCP Memory
+
+Update `.cursor/memory/architecture-snapshot.md`:
+- Add new DB tables to the schema table
+- Add new shadcn components to the installed list
+- Add the new feature to the Existing Features table
+- Add any new canonical pattern references that differ from existing ones
+
+Then run `/memory sync` to persist all changes to MCP memory so future sessions load context efficiently.
+
+---
+
+## Common Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| MCP memory returns no results | Memory not synced yet | Run `/memory sync` first, then retry |
+| Test passes without implementation (RED fails) | Test asserts on falsy/default values | Ensure the test expects a specific truthy result that only a real implementation can produce |
+| `pnpm typecheck` fails on schema file | Schema imported in test without mock | Add the schema file to `coverage.exclude` in `vitest.config.ts` |
+| Context exceeds 60% mid-build | Feature too large for one conversation | Stop, note the current step, start a new conversation referencing it |
+| `lint-staged` blocks commit | ESLint warnings treated as errors | Fix all warnings; never use `eslint-disable` inline — fix the code |
+
+---
+
+## Guardrails
+- NEVER start implementation before the user approves the plan (Step 3)
+- NEVER start implementation before the RED gate is confirmed with actual test output
+- Coverage threshold: 95% statements/functions/lines, 90% branches
+- Follow `features/* → shared/*` dependency direction
+- RLS is mandatory for every new table — not a post-step
+- Write lint-compliant code from the start — read the Strict Rules Reference before the first line of code

package/template/.claude/skills/build-feature/references/server-action-test-template.md

@@ -0,0 +1,103 @@
+# Server Action Testing Pattern
+
+Test Server Actions by mocking `createClient`, asserting on the returned `ActionResult`, and verifying side effects.
+
+## Setup
+
+```typescript
+import { vi, it, expect, describe, beforeEach } from "vitest";
+import { createClient } from "@/shared/lib/supabase/server";
+import { revalidatePath } from "next/cache";
+import { makeChain, makeSupabaseMock } from "@/shared/test-utils/supabase-mock";
+import { myAction } from "@/features/example/actions/my.action";
+
+vi.mock("@/shared/lib/supabase/server", () => ({ createClient: vi.fn() }));
+vi.mock("next/cache", () => ({ revalidatePath: vi.fn() }));
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+```
+
+## Unauthenticated case (required in every action test)
+
+```typescript
+it("returns error when user is not authenticated", async () => {
+  // Arrange
+  const { mockClient } = makeSupabaseMock({ user: null });
+  vi.mocked(createClient).mockResolvedValue(mockClient as never);
+  const formData = new FormData();
+
+  // Act
+  const result = await myAction(formData);
+
+  // Assert
+  expect(result).toEqual({ status: "error", message: "No autenticado" });
+  expect(revalidatePath).not.toHaveBeenCalled();
+});
+```
+
+## Happy path (insert example)
+
+```typescript
+it("returns success and revalidates on valid input", async () => {
+  // Arrange
+  const { mockClient, mockFrom } = makeSupabaseMock({ user: { id: "user-1" } });
+  vi.mocked(createClient).mockResolvedValue(mockClient as never);
+  mockFrom.mockReturnValue(makeChain({ error: null }));
+  const formData = new FormData();
+  formData.set("title", "My item");
+
+  // Act
+  const result = await myAction(formData);
+
+  // Assert
+  expect(result).toEqual({ status: "success", message: expect.any(String) });
+  expect(revalidatePath).toHaveBeenCalledWith("/");
+});
+```
+
+## DB error case
+
+```typescript
+it("returns error when db insert fails", async () => {
+  // Arrange
+  const { mockClient, mockFrom } = makeSupabaseMock({ user: { id: "user-1" } });
+  vi.mocked(createClient).mockResolvedValue(mockClient as never);
+  mockFrom.mockReturnValue(makeChain({ error: { message: "db error" } }));
+  const formData = new FormData();
+  formData.set("title", "My item");
+
+  // Act
+  const result = await myAction(formData);
+
+  // Assert
+  expect(result).toEqual({ status: "error", message: expect.any(String) });
+  expect(revalidatePath).not.toHaveBeenCalled();
+});
+```
+
+## Validation error case
+
+```typescript
+it("returns error when required field is missing", async () => {
+  // Arrange
+  const { mockClient } = makeSupabaseMock({ user: { id: "user-1" } });
+  vi.mocked(createClient).mockResolvedValue(mockClient as never);
+  const formData = new FormData(); // no fields set
+
+  // Act
+  const result = await myAction(formData);
+
+  // Assert
+  expect(result).toEqual({ status: "error", message: expect.any(String) });
+});
+```
+
+## Key Rules
+
+- Always import `makeChain` and `makeSupabaseMock` from `@/shared/test-utils/supabase-mock`
+- Every action test must cover: unauthenticated, validation error, DB error, happy path
+- `mockFrom` returns a chain — each chained method (`.select()`, `.insert()`, etc.) returns the same chain object
+- `then` on the chain resolves with the value you pass to `makeChain()`
+- Never use `mockReturnThis()` — it does not match Supabase's actual chaining API