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/PostgreSQL)
• Tailwind CSS
• Better Auth (Authentication)
• Bun (Package Manager & Test Runner)
• Playwright (Acceptance Testing)
• Vitest (Legacy - migrated to Bun test runner)

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

Package Manager: Bun

This project uses Bun as the package manager and test runner:

# Install dependencies
bun install

# Run development server
bun run dev

# Build the application
bun run build

# Run unit/component tests
bun test

# Run unit tests only
bun run test:unit

# Run component tests only
bun run test:component

# Run acceptance tests (Playwright)
bun run test:acceptance

# Run linting
bun run lint

Note: E2E tests still use Playwright, as Bun's test runner doesn't support browser automation. Unit and component tests have been migrated to Bun's native test runner for faster execution. E2E tests are located in the e2e/ directory (not src/__tests__/e2e/).

CI/CD with Bun

All CI/CD workflows have been updated to use Bun:

• Dockerfile: Uses oven/bun:alpine base image for all stages
• PR Workflow: Uses oven/setup-bun action and bun install, bun test
• Release Workflow: Uses Bun for version bumping and Docker builds

Note: The test.yml workflow has been removed as it's redundant with the PR workflow.

Admin User Creation

To create an admin user, use the provided scripts:

Option 1: Using Better Auth API (Recommended)

bun run 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

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:

node scripts/list-users.js

Update Admin Password:

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:

# Switch to SQLite
npm run db:switch sqlite

# Switch to PostgreSQL  
npm run db:switch postgresql

To set up PostgreSQL:

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:

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 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/