# HP CG Production Tracker — Development Setup

Cross-platform setup guide for macOS and Windows 11.

---

## Prerequisites

| Tool | Version | macOS | Windows |
|------|---------|-------|---------|
| Node.js | 22.x | `nvm install 22` | `nvm install 22` (nvm-windows) |
| npm | bundled with Node | Included | Included |
| PostgreSQL | 17.x | `brew install postgresql@17` | [Installer](https://www.postgresql.org/download/windows/) or `winget install PostgreSQL.PostgreSQL.17` |
| Git | any recent | Included with Xcode CLT | [git-scm.com](https://git-scm.com/download/win) |

### Node Version Manager

**macOS** — [nvm](https://github.com/nvm-sh/nvm):
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
```

**Windows** — [nvm-windows](https://github.com/coreybutler/nvm-windows):
Download the latest installer from the releases page and run it.

After installing nvm, the `.nvmrc` file in the project root specifies Node 22:
```bash
nvm install    # reads .nvmrc automatically (macOS)
nvm use        # switch to the project's Node version
```

On nvm-windows, specify the version explicitly:
```cmd
nvm install 22
nvm use 22
```

---

## 1. Clone the Repository

```bash
git clone <repo-url> hp_prod_tracker
cd hp_prod_tracker
```

---

## 2. Install Dependencies

```bash
npm install
```

This also runs `prisma generate` automatically via the postinstall hook, creating
the generated Prisma client at `src/generated/prisma/`.

If the generated client is missing for any reason:
```bash
npx prisma generate
```

---

## 3. Set Up PostgreSQL

### macOS (Homebrew)

```bash
brew install postgresql@17
brew services start postgresql@17
createdb hp_prod_tracker
```

The default Homebrew PostgreSQL setup uses your system username with no password.

### Windows

1. Install PostgreSQL 17 via the official installer or winget:
   ```cmd
   winget install PostgreSQL.PostgreSQL.17
   ```
2. During installation, note the password you set for the `postgres` user.
3. Open **pgAdmin** or **psql** and create the database:
   ```sql
   CREATE DATABASE hp_prod_tracker;
   ```
4. Optionally create a dedicated user:
   ```sql
   CREATE USER leivur WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE hp_prod_tracker TO leivur;
   ```

### Verify Connection

```bash
psql -h localhost -U leivur -d hp_prod_tracker
# or on Windows if using postgres user:
psql -h localhost -U postgres -d hp_prod_tracker
```

---

## 4. Configure Environment Variables

Create a `.env` file in the project root (this file is gitignored):

```env
# ─── Database ────────────────────────────────────────────
# macOS (Homebrew, no password):
DATABASE_URL="postgresql://leivur@localhost:5432/hp_prod_tracker?schema=public"

# Windows (with password):
# DATABASE_URL="postgresql://leivur:your_password@localhost:5432/hp_prod_tracker?schema=public"

# ─── Auth (Dev Bypass) ──────────────────────────────────
# Skips SSO and uses a seeded dev user. Set to "false" or remove for production SSO.
DEV_BYPASS_AUTH="true"
DEV_USER_ID="dev-user-001"

# ─── Auth (Production SSO — optional for local dev) ─────
# AUTH_GOOGLE_ID=""
# AUTH_GOOGLE_SECRET=""
# AUTH_MICROSOFT_ENTRA_ID_ID=""
# AUTH_MICROSOFT_ENTRA_ID_SECRET=""
# AUTH_MICROSOFT_ENTRA_ID_TENANT_ID=""

# ─── NextAuth ───────────────────────────────────────────
NEXTAUTH_SECRET="any-random-string-change-in-production"
NEXTAUTH_URL="http://localhost:3000"
```

---

## 5. Initialize the Database

Push the Prisma schema to the database and run the seed script:

```bash
npx prisma db push
npx prisma db seed
```

`db push` creates all tables from `prisma/schema.prisma`.

`db seed` populates:
- 10 pipeline stage templates with dependency rules
- Dev organization (id: `dev-org-001`)
- Dev admin user (id: `dev-user-001`, email: `dev@localhost`)

To inspect the database visually:
```bash
npx prisma studio
```

---

## 6. Start the Dev Server

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000). With `DEV_BYPASS_AUTH="true"`, you'll
be logged in automatically as the dev admin user.

---

## Available Scripts

| Script | Command | Description |
|--------|---------|-------------|
| Dev server | `npm run dev` | Start Next.js with Turbopack |
| Build | `npm run build` | Production build |
| Start | `npm start` | Run production build |
| Lint | `npm run lint` | ESLint check |
| Format | `npm run format` | Prettier format all files |
| Format check | `npm run format:check` | Prettier check (no write) |
| Generate client | `npm run db:generate` | Regenerate Prisma client |
| Push schema | `npm run db:push` | Sync schema to database (no migration files) |
| Seed | `npm run db:seed` | Run seed script |
| Studio | `npm run db:studio` | Open Prisma Studio GUI |

---

## Platform-Specific Notes

### macOS

- **nvm**: Must be sourced in each shell session. If `node` isn't found, run:
  ```bash
  export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
  ```
  This is typically added to `~/.zshrc` automatically by the nvm installer.

- **PostgreSQL service**: Start/stop with Homebrew:
  ```bash
  brew services start postgresql@17
  brew services stop postgresql@17
  ```

### Windows

- **nvm-windows**: Requires an elevated (admin) terminal for `nvm install` and `nvm use`.

- **PostgreSQL service**: Runs as a Windows service by default. Manage via Services app
  or:
  ```cmd
  net start postgresql-x64-17
  net stop postgresql-x64-17
  ```

- **Line endings**: Git should handle CRLF/LF conversion automatically. If you see
  formatting issues, verify your Git config:
  ```cmd
  git config --global core.autocrlf true
  ```

- **Terminal**: PowerShell, Windows Terminal, or Git Bash all work. The npm scripts are
  cross-platform.

---

## Switching Between Machines

The workflow for moving between macOS and Windows:

1. **Commit and push** from the current machine:
   ```bash
   git add -A && git commit -m "WIP" && git push
   ```

2. **Pull on the other machine**:
   ```bash
   git pull
   npm install          # in case dependencies changed
   npx prisma db push   # in case schema changed
   npm run dev
   ```

The `.env` file is gitignored, so each machine maintains its own database connection
string and auth settings. The database content is local to each machine — use
`npx prisma db seed` to reset to baseline data on a fresh setup.

---

## Troubleshooting

### `prisma generate` fails
Ensure Node 22 is active (`node -v`) and `npm install` completed successfully.
The generated client at `src/generated/prisma/` is gitignored and must be generated
locally.

### Database connection refused
- Verify PostgreSQL is running (`brew services list` on macOS, `services.msc` on Windows)
- Check `DATABASE_URL` in `.env` matches your local PostgreSQL user/password/port

### Port 3000 already in use
```bash
# macOS
lsof -ti:3000 | xargs kill
# Windows
netstat -ano | findstr :3000
taskkill /PID <pid> /F
```

### Schema out of sync after git pull
```bash
npx prisma db push    # applies any schema changes
npx prisma generate   # regenerates the client types
```

### nvm: command not found (macOS)
Add to `~/.zshrc`:
```bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
```

---

## Tech Stack Quick Reference

| Layer | Technology |
|-------|-----------|
| Framework | Next.js 16 (App Router, Turbopack) |
| Language | TypeScript 5.x |
| Styling | Tailwind CSS 4 |
| Components | shadcn/ui (Radix + Tailwind) |
| Database | PostgreSQL 17 + Prisma 7 |
| Auth | Auth.js v5 (Google + Microsoft SSO) |
| State | TanStack Query v5 + Zustand |
| Forms | React Hook Form + Zod v4 |
| Charts | Recharts |
| Icons | Lucide React |