nextjs-hackathon-stack 0.1.31 → 0.1.32

package/package.json

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

package/template/.cursor/agents/business-intelligence.md

@@ -52,6 +52,12 @@ As a [user type], I want [goal] so that [reason].
 - Every acceptance criterion maps to at least one test case
 - No mention of database tables, API calls, component names, or file paths
 
+## Language
+
+Write requirements and acceptance criteria in the user's language. However:
+- Acceptance criteria IDs (`AC1`, `AC2`), test case IDs (`TC1`), and technical terms (`ActionResult`, `Server Action`, component names) always remain in English
+- Specify that all code-level text (test `it()` descriptions, variable names, error strings in code) must be written in English — only user-visible strings (UI labels, toast messages, validation messages shown on screen) should be in the target language
+
 ## Guardrails
 - Always ask questions before writing — never assume
 - Document all requirements in `.requirements/` directory

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

@@ -43,7 +43,7 @@ Delegate to the appropriate specialist based on domain:
 ## Workflow Sequences
 
 ### New feature
-@business-intelligence (functional issue) → @technical-lead (task breakdown + test plan) → @test-qa (RED) → @backend/@frontend (GREEN) → @code-reviewer → @security-researcher
+@business-intelligence (functional issue) → @technical-lead (task breakdown + test plan) → @test-qa (RED) → **@backend + @frontend in parallel** (GREEN) → **@code-reviewer + @security-researcher in parallel**
 
 ### Bug fix
 @test-qa (reproduce with failing test) → @backend/@frontend (fix) → @code-reviewer
@@ -62,10 +62,10 @@ When you receive a functional issue from @business-intelligence, do this before
    - One `describe` block per acceptance criterion
    - Which mocks are needed (Supabase, HTTP, etc.)
    - Which edge cases map to which criteria
-4. **Delegate in order**:
+4. **Delegate in order** (parallel where possible):
    - @test-qa gets the test plan → writes failing tests (RED)
-   - @backend/@frontend implements to make tests pass (GREEN)
-   - @code-reviewer and @security-researcher review the result
+   - **@backend + @frontend simultaneously** — they work on independent files, no need to serialize (GREEN)
+   - **@code-reviewer + @security-researcher simultaneously** — independent review passes, run in parallel
 
 ### TDD efficiency guardrails
 - Plan test structure before delegating to @test-qa — never send "write tests for this feature" without a plan

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

@@ -1,6 +1,7 @@
 ---
-description: Feature-based architecture rules. Always applies.
-alwaysApply: true
+description: Feature-based architecture rules. Applies to all source files.
+alwaysApply: false
+globs: ["src/**"]
 ---
 
 # Architecture Rules

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

@@ -1,6 +1,7 @@
 ---
-description: Code quality standards. Always applies to all files.
-alwaysApply: true
+description: Code quality standards. Applies to TypeScript/TSX source files.
+alwaysApply: false
+globs: ["src/**/*.ts", "src/**/*.tsx"]
 ---
 
 # Coding Standards
@@ -63,6 +64,44 @@ const items = schema.parse(data);
 const items = data as SupportListItem[];
 ```
 
+## Language Rules
+
+- **Code-level text must be in English**: test `it()` descriptions, `describe()` block names, variable names, code comments, developer-facing `Error` constructor messages (never shown to users), `console` output
+- **User-facing text stays in the target language**: UI labels, placeholders, toast messages, form validation messages shown on screen, `ActionResult` error/success strings that end up displayed in the UI
+
+```typescript
+// ✅ Code-level: English
+it("returns error when candidate is not found", async () => { ... });
+throw new Error("Unexpected DB response shape"); // developer-facing, never shown in UI
+
+// ✅ User-facing: target language (Spanish)
+return { success: false, error: "Candidato no encontrado" }; // shown in toast
+toast.error("No se pudo guardar el cambio");
+
+// ❌ Wrong: code-level in wrong language
+it("retorna error si el candidato no existe", async () => { ... });
+```
+
+## Coverage Exclusions (configure upfront, not reactively)
+
+Before writing tests, add exclusions to `vitest.config.ts` for:
+- Drizzle schema definition files (`src/shared/db/schema.ts`)
+- Pure type files (files with only `type`/`interface` exports, no runtime logic)
+- Third-party UI wrapper components that rely on portals or browser APIs not supported in jsdom (e.g., `sonner.tsx`, toast providers)
+
+Configure these exclusions **before writing tests** to avoid reactive coverage fixes mid-implementation.
+
+```typescript
+// vitest.config.ts
+coverage: {
+  exclude: [
+    "src/shared/db/schema.ts",
+    "src/shared/components/ui/sonner.tsx",
+    // add other portal/type-only files here
+  ],
+}
+```
+
 ## 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).

package/template/.cursor/rules/general.mdc

@@ -1,6 +1,7 @@
 ---
-description: Stack overview and project conventions. Always applies.
-alwaysApply: true
+description: Stack overview and project conventions. Applies to all source files.
+alwaysApply: false
+globs: ["src/**"]
 ---
 
 # Stack Overview

package/template/.cursor/rules/security.mdc

@@ -94,7 +94,10 @@ const next = searchParams.get("next") ?? "/";
 "script-src 'self' 'unsafe-inline'", // TODO: replace with nonce-based CSP
 "style-src 'self' 'unsafe-inline'",
 
-// ❌ Never — unsafe-eval is forbidden
+// ✅ 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'",
 ```
 

package/template/.cursor/rules/testing.mdc

@@ -111,6 +111,14 @@ For every function, ask: what happens with...
 
 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

package/template/.cursor/skills/create-feature/SKILL.md

@@ -25,7 +25,24 @@ src/features/<feature-name>/
 └── __tests__/
 ```
 
-### 3. TDD: RED Phase
+### 3. Pre-Test Setup (do this before writing any tests)
+
+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 (no runtime logic)
+- 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",
+]
+```
+
+Configuring exclusions upfront prevents reactive coverage fixes mid-implementation.
+
+### 4. TDD: RED Phase
 Write ALL test files first:
 - `__tests__/<component>.test.tsx` — component tests
 - `__tests__/use-<feature>.test.ts` — hook tests
@@ -34,16 +51,16 @@ Write ALL test files first:
 
 Run `pnpm test:unit` — all tests must FAIL (RED).
 
-### 4. TDD: GREEN Phase
+### 5. TDD: GREEN Phase
 Implement minimum code to pass each test:
 - Components → actions → hooks → API routes
 
 Run `pnpm test:unit` — all tests must PASS (GREEN).
 
-### 5. Refactor
+### 6. Refactor
 Clean up while keeping tests green.
 
-### 6. Verify
+### 7. Verify
 ```bash
 pnpm test:coverage   # Must show 100%
 pnpm lint            # Must pass with 0 warnings

package/template/CLAUDE.md

@@ -19,10 +19,26 @@ Read these rules when working on related files:
 
 This project uses specialist agents in `.claude/agents/`. Follow the technical-lead workflow:
 
-- **New feature**: requirements (`business-intelligence`) → task breakdown (`technical-lead`) → tests first (`test-qa`) → implementation (`backend`/`frontend`) → review (`code-reviewer`) → security (`security-researcher`)
+- **New feature**: requirements (`business-intelligence`) → task breakdown (`technical-lead`) → tests first (`test-qa`) → implementation (`backend` + `frontend` **in parallel**) → review (`code-reviewer` + `security-researcher` **in parallel**)
 - **Bug fix**: reproduce with failing test (`test-qa`) → fix (`backend`/`frontend`) → review (`code-reviewer`)
 - **Refactor**: plan (`technical-lead`) → implement (`backend`/`frontend`) → verify (`test-qa`) → review (`code-reviewer`)
 
+## Recommended: 2-Conversation Workflow for New Features
+
+Split new feature work across two conversations to avoid context exhaustion (hitting >80% context mid-implementation):
+
+**Conversation 1 — Requirements** (low context, can be discarded after)
+```
+@business-intelligence → write .requirements/<feature-name>.md → confirm with user
+```
+
+**Conversation 2 — Implementation** (fresh context, reads spec from file)
+```
+/create-feature  →  reads .requirements/<feature-name>.md  →  full TDD pipeline
+```
+
+The `/create-feature` skill reads the requirements file directly, so the BI conversation history is not needed during implementation. This keeps each conversation well under 50% context usage.
+
 # File Naming
 
 - Server Actions: `name.action.ts` with `"use server"` at top

package/template/next.config.ts

@@ -1,5 +1,7 @@
 import type { NextConfig } from "next";
 
+const isDev = process.env.NODE_ENV !== "production";
+
 const nextConfig: NextConfig = {
   typedRoutes: true,
   logging: {
@@ -21,7 +23,8 @@ const nextConfig: NextConfig = {
           value: [
             "default-src 'self'",
             // TODO: replace 'unsafe-inline' with nonce-based CSP
-            "script-src 'self' 'unsafe-inline'",
+            // 'unsafe-eval' is added in dev only for React's debugging features (never in production)
+            `script-src 'self' 'unsafe-inline'${isDev ? " 'unsafe-eval'" : ""}`,
             "style-src 'self' 'unsafe-inline'",
             "img-src 'self' data: blob: https:",
             "font-src 'self'",

package/template/tailwind.css

@@ -1,20 +1,20 @@
 @import "tailwindcss";
 
 @theme {
-  --color-background: hsl(0 0% 100%);
-  --color-foreground: hsl(222.2 84% 4.9%);
-  --color-primary: hsl(222.2 47.4% 11.2%);
-  --color-primary-foreground: hsl(210 40% 98%);
-  --color-secondary: hsl(210 40% 96.1%);
-  --color-secondary-foreground: hsl(222.2 47.4% 11.2%);
-  --color-muted: hsl(210 40% 96.1%);
-  --color-muted-foreground: hsl(215.4 16.3% 46.9%);
-  --color-accent: hsl(210 40% 96.1%);
-  --color-accent-foreground: hsl(222.2 47.4% 11.2%);
+  --color-background: #ffffff;
+  --color-foreground: #111111;
+  --color-primary: #022633;
+  --color-primary-foreground: #ffffff;
+  --color-secondary: #f6a623;
+  --color-secondary-foreground: #ffffff;
+  --color-muted: #f5f5f5;
+  --color-muted-foreground: #666666;
+  --color-accent: #044a68;
+  --color-accent-foreground: #ffffff;
   --color-destructive: hsl(0 84.2% 60.2%);
-  --color-destructive-foreground: hsl(210 40% 98%);
-  --color-border: hsl(214.3 31.8% 91.4%);
-  --color-input: hsl(214.3 31.8% 91.4%);
-  --color-ring: hsl(222.2 84% 4.9%);
+  --color-destructive-foreground: #ffffff;
+  --color-border: #e5e5e5;
+  --color-input: #e5e5e5;
+  --color-ring: #022633;
   --radius: 0.5rem;
 }