Contributing

Development Model

Local development uses one shared PostgreSQL container and one database per checkout.

• The main checkout usually uses .env and POSTGRES_DB=wujie
• Each Git worktree uses its own .env.worktree
• Every checkout connects to the same PostgreSQL host: localhost:5432
• Isolation happens at the database level, not by starting a separate Docker Compose project
• Backend and frontend ports are still unique per worktree

Prerequisites

• Node.js v20+
• pnpm v10.28+
• Go v1.26+
• Docker

First-Time Setup

Main Checkout

cp .env.example .env
make setup-main

What make setup-main does:

• Installs JavaScript dependencies with pnpm install
• Ensures the shared PostgreSQL container is running
• Creates the application database if it does not exist
• Runs all migrations against that database

Start the app:

make start-main

Worktree

From the worktree directory:

make worktree-env
make setup-worktree

Start the worktree app:

make start-worktree

Daily Workflow

Main Checkout

make start-main
make stop-main
make check-main

Feature Worktree

git worktree add ../wujie-feature -b feat/my-change main
cd ../wujie-feature
make worktree-env
make setup-worktree
make start-worktree

Day-to-day:

make start-worktree
make stop-worktree
make check-worktree

Running Main and Worktree Simultaneously

This is a first-class workflow. Both checkouts use the same PostgreSQL container but different databases and ports:

Commands

# Frontend (all commands go through Turborepo)
pnpm install
pnpm dev:web          # Next.js dev server (port 3000)
pnpm dev:desktop      # Electron dev (electron-vite, HMR)
pnpm build            # Build all frontend apps
pnpm typecheck        # TypeScript check
pnpm lint             # ESLint
pnpm test             # TS tests (Vitest)

# Backend (Go)
make dev              # Run Go server (port 8080)
make daemon           # Run local daemon
make build            # Build server + CLI binaries
make test             # Go tests
make sqlc             # Regenerate sqlc code
make migrate-up       # Run database migrations
make migrate-down     # Rollback migrations

Testing

Run all local checks:

make check

This runs:

1. TypeScript typecheck
2. TypeScript unit tests
3. Go tests
4. Playwright E2E tests

Troubleshooting

Missing Env File

Create the expected env file:

# Main checkout
cp .env.example .env

# Worktree
make worktree-env

Check Which Database a Checkout Uses

cat .env           # or .env.worktree

Look for POSTGRES_DB, DATABASE_URL, PORT, FRONTEND_PORT.

List All Local Databases

docker compose exec -T postgres psql -U wujie -d postgres \
  -At -c "select datname from pg_database order by datname;"

Destructive Reset

Stop PostgreSQL and keep local databases:

make db-down

Reset only the current checkout's database (drops POSTGRES_DB, recreates it, re-runs all migrations). Other worktree databases are untouched.

make stop
make db-reset
make start

make db-reset refuses to run if DATABASE_URL points at a remote host.

Wipe all local PostgreSQL data:

docker compose down -v

Warning: This deletes the shared Docker volume and all databases. After that you must run make setup-main or make setup-worktree again.