hp-prod-tracker/SETUP.md

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 or winget install PostgreSQL.PostgreSQL.17
Git	any recent	Included with Xcode CLT	git-scm.com

Node Version Manager

macOS — nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Windows — 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:

nvm install    # reads .nvmrc automatically (macOS)
nvm use        # switch to the project's Node version

On nvm-windows, specify the version explicitly:

nvm install 22
nvm use 22

---

1. Clone the Repository

git clone <repo-url> hp_prod_tracker
cd hp_prod_tracker

---

2. Install Dependencies

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:

npx prisma generate

---

3. Set Up PostgreSQL

macOS (Homebrew)

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:

   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:

   CREATE DATABASE hp_prod_tracker;
   

4. Optionally create a dedicated user:

   CREATE USER leivur WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE hp_prod_tracker TO leivur;
   

Verify Connection

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):

# ─── 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

Apply migrations and run the seed script:

npx prisma migrate dev
npx prisma db seed

migrate dev applies pending migrations and creates new ones from schema changes.

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:

npx prisma studio

---

6. Start the Dev Server

npm run dev

Open 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
Migrate	npm run db:migrate	Apply/create migrations
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:

  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:

  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:

  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:

  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:

   git add -A && git commit -m "WIP" && git push
   

2. Pull on the other machine:

   git pull
   npm install          # in case dependencies changed
   npx prisma migrate dev   # apply any new migrations
   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

# macOS
lsof -ti:3000 | xargs kill
# Windows
netstat -ano | findstr :3000
taskkill /PID <pid> /F

Schema out of sync after git pull

npx prisma migrate dev   # applies pending migrations, creates new ones if schema changed
npx prisma generate      # regenerates the client types

nvm: command not found (macOS)

Add to ~/.zshrc:

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