euchre_camp/AGENTS.md

# EuchreCamp - Agent Guide

This document provides guidance for AI agents working on the EuchreCamp project.

## Project Overview

EuchreCamp is a Next.js 14+ application for managing Euchre tournaments and tracking partnership analytics.

### Key Technologies
- **Next.js 14+** (App Router)
- **TypeScript**
- **Prisma ORM** (SQLite)
- **Tailwind CSS**
- **Better Auth** (Authentication)
- **Vitest** (Unit Testing)
- **Playwright** (Acceptance Testing)

## Architecture Patterns

### Authentication & Authorization
- **Session Management**: Better Auth with cookie-based sessions
- **Role-Based Access Control**: Three roles (player, tournament_admin, club_admin)
- **Permission Functions**: Located in `src/lib/permissions.ts`
- **Session Cache**: Disabled to avoid stale role data

### Database Schema
- **Players**: `id`, `name`, `currentElo`, `gamesPlayed`, `wins`, `losses`
- **Users**: `id`, `email`, `role`, `playerId` (foreign key to players)
- **Events**: Tournaments with `ownerId` for ownership tracking
- **Matches**: Individual match results with `createdById` for tracking

### Data Flow
1. User authentication via Better Auth
2. Session stored in HTTP-only cookies
3. Permission checks read directly from database
4. API routes enforce authorization

## Common Tasks

### Admin User Creation

To create an admin user, use the provided scripts:

**Option 1: Using Better Auth API (Recommended)**
```bash
node scripts/create-admin-via-api.js
```
This creates the admin user `david@dhg.lol` with password `adminadmin` using Better Auth's internal API.

**Option 2: Direct Database Creation**
```bash
node scripts/create-admin-better-auth.js
```
This creates the admin user `david@dhg.lol` with password `admin` directly in the database.

**List All Users:**
```bash
node scripts/list-users.js
```

**Update Admin Password:**
```bash
node scripts/update-admin-password.js
```
This updates the admin password to `adminadmin`.

**Note:** All scripts currently create the user `david@dhg.lol`. If you need to create a different admin user, you can modify the email in the script or use Better Auth's CLI.

### Fixing Authentication Issues
If users are redirected incorrectly or permissions aren't working:
1. Check if cookie cache is disabled in `src/lib/auth.ts`
2. Verify permission functions read from database, not session
3. Ensure `getSession()` uses `disableCookieCache=true`

### Adding New Features
1. Create API route in `src/app/api/`
2. Add permission checks using functions from `src/lib/permissions.ts`
3. Create UI component in `src/app/` or `src/components/`
4. Add tests in `src/__tests__/`
5. Run tests: `npm run test` and `npm run test:acceptance`

### Database Changes
1. Edit `prisma/schema.prisma`
2. Run `npx prisma migrate dev --name <migration-name>`
3. Run `npx prisma generate`
4. Update affected API routes and components

### Database Provider Switching
The application supports both SQLite (default) and PostgreSQL databases.

**To switch between databases:**
```bash
# Switch to SQLite
npm run db:switch sqlite

# Switch to PostgreSQL  
npm run db:switch postgresql
```

**To set up PostgreSQL:**
```bash
npm run db:setup-postgres
```

**Database Configuration:**
- Edit `.env` file to set `DATABASE_PROVIDER` and `DATABASE_URL`
- For PostgreSQL, also set `DATABASE_SHADOW_URL` for migrations

**Note:** The database provider is automatically detected by Better Auth and Prisma.

### Running Tests

**Using just (recommended):**
- **All tests**: `just test` (unit + acceptance with SQLite)
- **Unit tests**: `just test-unit`
- **Acceptance tests (SQLite)**: `just test-acceptance-sqlite`
- **Acceptance tests (PostgreSQL)**: `just test-acceptance-postgres`
- **PR validation**: `just pr-validate` (what runs on pull requests)

**Using npm scripts:**
- **Unit tests**: `npm run test`
- **Acceptance tests**: `npm run test:acceptance`
- **Specific test**: `npm run test:acceptance -- --grep "test name"`

**CI-style acceptance tests with SQLite:**
```bash
DATABASE_PROVIDER=sqlite DATABASE_URL=file:./prisma/ci.db npm run test:acceptance
```

### CI Runner Image

**Note:** The CI runner image approach has been deprecated for Gitea Actions workflows.

The original attempt to use a pre-built CI runner image with pre-installed dependencies encountered fundamental issues with how Gitea Actions handles workspace mounting. When Gitea Actions runs a container job, it mounts the workspace at a specific path (e.g., `/workspace/david/euchre_camp`), which hides the container's `/app` directory where dependencies were installed.

**Current Approach:**
- Workflows use standard `node:20-alpine` or `mcr.microsoft.com/playwright` containers
- Dependencies are installed via `npm ci` in each workflow run
- This is the recommended approach for Gitea Actions

**Why the CI image approach doesn't work:**
1. Dockerfile.ci installs dependencies in `/app`
2. Gitea Actions mounts workspace at `/workspace/david/euchre_camp`
3. Workspace mount hides the `/app` directory
4. Symlinks from `/app/node_modules` don't work because `/app` is hidden

**Alternative for performance:**
If CI performance becomes an issue, consider:
- Using GitHub Actions cache for node_modules
- Using a self-hosted runner with persistent workspace
- Using the main Dockerfile's `test-runner` target for release workflows (which works because it builds a complete image)

### CI/CD Pipeline
The project uses Gitea Actions for continuous integration:

**PR Workflow** (`.gitea/workflows/pr.yml`):
- Runs on pull requests to main
- Executes unit tests and acceptance tests with SQLite
- Analyzes commits for semantic versioning
- Comments suggested bump type on PRs

**Test Workflow** (`.gitea/workflows/test.yml`):
- Runs on all branch pushes
- Executes unit tests for quick feedback
- Skips auto-generated version bump commits

**Release Workflow** (`.gitea/workflows/release.yml`):
- Runs on main branch pushes
- Determines version bump type
- Bumps version and creates git tags
- Builds Docker images and runs tests
- Pushes to registry and deploys

**Database Strategy**:
- CI tests use SQLite (fast, no server required)
- Production uses PostgreSQL
- Switch with `DATABASE_PROVIDER` environment variable

## Key Files

### Configuration
- `src/lib/auth.ts` - Better Auth configuration
- `src/lib/permissions.ts` - Authorization functions
- `src/lib/elo-utils.ts` - Elo calculation logic

### API Routes
- `src/app/api/auth/[[...all]]/route.ts` - Better Auth API
- `src/app/api/tournaments/route.ts` - Tournament management
- `src/app/api/matches/upload/route.ts` - CSV upload processing

### UI Components
- `src/components/Navigation.tsx` - Navigation with role-based links
- `src/app/page.tsx` - Home page with top players, recent tournament, club president
- `src/app/players/[id]/profile/page.tsx` - Player profile with stats

### Tests
- `src/__tests__/unit/permissions.test.ts` - Permission function tests
- `src/__tests__/unit/elo.test.ts` - Elo calculation tests
- `src/__tests__/e2e/global.setup.ts` - Test setup with admin user creation
- `src/__tests__/e2e/home-page.test.ts` - Home page tests

## Troubleshooting

### Session Cache Issues
**Problem**: Updated user roles don't reflect in session
**Solution**: Ensure cookie cache is disabled and permission functions read from database

### Test Failures
**Problem**: Tests timing out or failing unexpectedly
**Solution**:
- Check if dev server is running
- Verify database is accessible
- Run tests with `--headed` to see browser

### Database Conflicts
**Problem**: Tests interfering with each other
**Solution**: Tests run sequentially with `fullyParallel: false` and `workers: 1`

## Conventions

### Commit Messages
- Use conventional commit format: `<type>: <description>`
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`

### Code Style
- Use TypeScript for type safety
- Prefer React Server Components for data fetching
- Keep business logic in `src/lib/` directory
- Write tests for new features

### File Naming
- Components: PascalCase (e.g., `Navigation.tsx`)
- Utilities: camelCase (e.g., `elo-utils.ts`)
- Tests: `.test.ts` or `.test.tsx` suffix

## File Organization

See [docs/FILE_ORGANIZATION.md](docs/FILE_ORGANIZATION.md) for detailed file organization and structure.

## Resources

- **Better Auth Docs**: https://better-auth.com/docs
- **Next.js Docs**: https://nextjs.org/docs
- **Prisma Docs**: https://www.prisma.io/docs
- **Playwright Docs**: https://playwright.dev
- **Vitest Docs**: https://vitest.dev/