docs: update README and AGENTS.md with CI/CD and justfile info

2026-03-31 21:48:58 -07:00
parent e08d72bfe6
commit 5f02726ba6
2 changed files with 126 additions and 8 deletions
@@ -109,10 +109,50 @@ npm run db:setup-postgres
 **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/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
@@ -170,6 +210,10 @@ npm run db:setup-postgres
 - 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
@@ -17,20 +17,29 @@ EuchreCamp is a full-stack web application built with Next.js 14+ and TypeScript

 - **Framework**: Next.js 14+ (App Router)
 - **Language**: TypeScript
- **Database**: Prisma ORM with SQLite
+- **Database**: Prisma ORM with SQLite (default) or PostgreSQL
 - **Styling**: Tailwind CSS
 - **Authentication**: Better Auth
 - **Form Handling**: React Hook Form + Zod validation
 - **CSV Parsing**: PapaParse
 - **Unit Testing**: Vitest
 - **Acceptance Testing**: Playwright
+- **CI/CD**: Gitea Actions with SQLite for CI tests

 ## Project Structure

 ```
 euchre_camp/
-├── src/
-│   ├── app/
+├── .gitea/workflows/     # CI/CD workflows (Gitea Actions)
+├── docs/                 # Documentation
+│   ├── deployment/       # Deployment guides
+│   └── planning/         # Planning documents
+├── prisma/               # Prisma schema and migrations
+├── public/               # Static assets
+├── scripts/              # Utility scripts
+│   └── python/           # Python scripts (legacy)
+├── src/                  # Source code
+│   ├── app/              # Next.js app directory
 │   │   ├── api/          # API routes
 │   │   ├── auth/         # Authentication pages
 │   │   ├── admin/        # Admin pages
@@ -39,16 +48,15 @@ euchre_camp/
 │   │   └── components/   # Shared components
 │   ├── lib/              # Utilities and configuration
 │   │   ├── auth.ts       # Better Auth configuration
-│   │   ├── prisma.ts     # Prisma client
+│   │   ├── prisma.ts     # Prisma client (SQLite/PostgreSQL)
 │   │   ├── permissions.ts # Authorization functions
 │   │   └── elo-utils.ts  # Elo calculation utilities
 │   └── __tests__/        # Vitest and Playwright tests
-├── prisma/               # Prisma schema and migrations
-├── docs/                 # Documentation
-├── scripts/              # Utility scripts
-└── public/               # Static assets
+└── ...                   # Configuration files in root
 ```

+See [docs/FILE_ORGANIZATION.md](docs/FILE_ORGANIZATION.md) for detailed file organization.
+
 ## Features Implemented

 ### Epic 1: Authentication & User Management
@@ -242,6 +250,36 @@ Visit `/` to see:

 ## Development

+### Using just (recommended)
+The project includes a `justfile` with common development tasks:
+
+```bash
+# Show all available tasks
+just help
+
+# Development mode
+just dev
+
+# Run all tests (unit + acceptance with SQLite)
+just test
+
+# Run PR validation (what runs on pull requests)
+just pr-validate
+
+# Run CI pipeline locally
+just ci
+
+# Switch database provider
+just db-switch-sqlite
+just db-switch-postgres
+
+# Docker shortcuts
+just docker-up
+just docker-down
+just docker-logs
+```
+
+### Using npm scripts directly
 ```bash
 # Development mode
 npm run dev
@@ -255,6 +293,9 @@ npm run test

 # Run acceptance tests
 npm run test:acceptance
+
+# Run acceptance tests with SQLite (CI-style)
+DATABASE_PROVIDER=sqlite DATABASE_URL=file:./prisma/ci.db npm run test:acceptance
 ```

 ### Database Commands
@@ -313,6 +354,39 @@ User stories are organized into epics in `docs/USER_STORIES.md`:
 7. Mobile Responsiveness
 8. Data Management & Export

+## CI/CD Pipeline
+
+The application uses Gitea Actions for continuous integration and deployment:
+
+### Workflow Architecture
+1. **PR Workflow** (`.gitea/workflows/pr.yml`): Runs on pull requests
+   - Unit tests (fast feedback)
+   - Acceptance tests with SQLite database
+   - Semantic version bump analysis
+
+2. **Test Workflow** (`.gitea/workflows/test.yml`): Runs on all branch pushes
+   - Unit tests for quick feedback
+   - Skips auto-generated version bumps
+
+3. **Release Workflow** (`.gitea/workflows/release.yml`): Runs on main branch pushes
+   - Version bumping and tagging
+   - Docker image building and testing
+   - Registry push and deployment
+
+### Database Strategy for CI
+- **CI Tests**: SQLite database (fast, no server required)
+- **Production**: PostgreSQL (production-like environment)
+- **Configuration**: `DATABASE_PROVIDER` environment variable
+
+### Running CI Locally
+```bash
+# Run unit tests (same as CI)
+npm run test:run
+
+# Run acceptance tests with SQLite
+DATABASE_PROVIDER=sqlite DATABASE_URL=file:./prisma/ci.db npm run test:acceptance
+```
+
 ## Docker Deployment

 This application can be run using Docker and Docker Compose. See [DOCKER.md](DOCKER.md) for detailed instructions.