fix: Improve DX with automated setup and Docker orchestration (#292)

CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added - Saved Repos Feature
+
+#### Frontend
+- **Zustand Store**: Created `useSavedProjectsStore` with localStorage persistence
+  - Stores saved repositories with key `oss_saved_repos_v1`
+  - Actions: `addProject`, `removeProject`, `toggleProject`, `clearAllSaved`, `setAll`, `isSaved`
+  - Automatic persistence across page reloads
+
+- **UI Components**:
+  - `SaveToggle`: Star icon button in project rows to save/unsave repositories
+  - `SavedProjectsPanel`: Side panel for managing saved repos
+    - Export saved repos to JSON file
+    - Import saved repos from JSON file
+    - Clear all saved repos with confirmation
+    - View all saved repos with metadata
+
+- **Projects Table**: Added "Save" column as first column in OSS Projects table
+- **Header Button**: Added "Saved Projects" button with count badge in projects page header
+
+#### Backend
+- **Database**: Added `saved_repos` JSONB column to `User` model (default: `[]`)
+- **Service Layer**: Created `savedReposService` with:
+  - `getSavedRepos`: Retrieve user's saved repos
+  - `mergeSavedRepos`: Merge local and server repos with conflict resolution
+  - `updateSavedRepos`: Update saved repos with add/remove/replace actions
+  - Maximum 100 saved repos per user enforcement
+
+- **API Endpoints** (tRPC):
+  - `user.getSavedRepos`: Get user's saved repos (protected, feature flag: `FEATURE_SAVED_REPOS_DB`)
+  - `user.updateSavedRepos`: Update saved repos with merge logic (protected, feature flag: `FEATURE_SAVED_REPOS_DB`)
+  - Conflict resolution: Newer `savedAt` timestamp wins
+
+#### Shared Types
+- Created `SavedRepo` type definition in `@opensox/shared`
+- Created `SavedReposAction` and `SavedReposUpdateInput` types
+
+### Configuration
+- **Feature Flag**: `FEATURE_SAVED_REPOS_DB` - Enable/disable database sync (default: disabled)
+  - When disabled: Client-only mode with localStorage
+  - When enabled: Full sync across devices with merge logic
+
+### Migration
+- Migration file: `add_saved_repos` - Adds `saved_repos` JSONB column to User table
+
+---
+
+## How to Use
+
+### For Users
+1. Navigate to `/dashboard/projects`
+2. Click "Find projects" to search for repositories
+3. Click the star icon on any project to save it
+4. Click "Saved Projects" button to view/manage saved repos
+5. Export/import saved repos as JSON for backup
+
+### For Developers
+1. **Client-only mode** (default): Works out of the box with localStorage
+2. **Database sync mode**: Set `FEATURE_SAVED_REPOS_DB=true` in `apps/api/.env`
+3. Run migration: `cd apps/api && npx prisma migrate dev`
+4. Restart API server
+
+### API Usage (when feature flag enabled)
+```typescript
+// Get saved repos
+const savedRepos = await trpc.user.getSavedRepos.query();
+
+// Add repos
+await trpc.user.updateSavedRepos.mutate({
+  action: 'add',
+  repos: [{ id: '123', name: 'repo', url: 'https://...', savedAt: new Date().toISOString() }]
+});
+
+// Sync with merge
+await trpc.user.updateSavedRepos.mutate({
+  action: 'replace',
+  repos: serverRepos,
+  localRepos: clientRepos // Will merge and resolve conflicts
+});
+```

Dockerfile.dev

@@ -0,0 +1,32 @@
+# Base stage with pnpm
+FROM node:20-alpine AS base
+RUN npm install -g pnpm
+WORKDIR /app
+
+# API development
+FROM base AS api
+COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
+COPY apps/api/package.json ./apps/api/
+COPY packages/shared/package.json ./packages/shared/
+RUN pnpm install
+COPY packages/shared ./packages/shared
+COPY apps/api ./apps/api
+WORKDIR /app/packages/shared
+RUN pnpm run build
+WORKDIR /app/apps/api
+RUN pnpm exec prisma generate
+EXPOSE 8080
+CMD ["pnpm", "run", "dev"]
+
+# Web development
+FROM base AS web
+COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
+COPY apps/web/package.json ./apps/web/
+COPY packages/shared/package.json ./packages/shared/
+COPY packages/ui/package.json ./packages/ui/ 
+RUN pnpm install
+COPY packages ./packages
+COPY apps/web ./apps/web
+WORKDIR /app/apps/web
+EXPOSE 3000
+CMD ["pnpm", "run", "dev"]

Makefile

@@ -0,0 +1,128 @@
+.PHONY: help start stop restart logs clean reset setup dev test status health migrate seed studio shell-api shell-db dev-local logs-api logs-web logs-db migrate-dev
+
+# Default target - show help
+help:
+	@echo ""
+	@echo "========================================================================"
+	@echo "                    Opensox Development CLI                            "
+	@echo "========================================================================"
+	@echo ""
+	@echo "  GETTING STARTED:"
+	@echo "    make setup     - First-time setup wizard (run this first!)"
+	@echo "    make start     - Start all services (DB, API, Web)"
+	@echo ""
+	@echo "  SERVICE MANAGEMENT:"
+	@echo "    make stop      - Stop all services"
+	@echo "    make restart   - Restart all services"
+	@echo "    make logs      - View logs from all services"
+	@echo "    make status    - Check service health"
+	@echo ""
+	@echo "  DATABASE:"
+	@echo "    make migrate   - Run database migrations"
+	@echo "    make seed      - Seed database with initial data"
+	@echo "    make studio    - Open Prisma Studio (GUI)"
+	@echo "    make reset     - Stop services and reset database (DELETES DATA)"
+	@echo ""
+	@echo "  DEBUGGING:"
+	@echo "    make shell-api - Open shell in API container"
+	@echo "    make shell-db  - Open psql shell in database"
+	@echo "    make logs-api  - View API logs only"
+	@echo "    make logs-web  - View Web logs only"
+	@echo ""
+	@echo "  CLEANUP:"
+	@echo "    make clean     - Remove containers, volumes, and build cache"
+	@echo ""
+	@echo "========================================================================"
+	@echo ""
+
+# First-time setup
+setup:
+	@echo "Starting Opensox setup wizard..."
+	@chmod +x ./scripts/setup.sh 2>/dev/null || true
+	@./scripts/setup.sh
+
+# Start all services
+start:
+	@echo "Starting all services..."
+	docker compose up -d
+	@$(MAKE) --no-print-directory health
+	@echo ""
+	@echo "Services started successfully!"
+	@echo "  Frontend: http://localhost:3000"
+	@echo "  API:      http://localhost:8080"
+	@echo ""
+
+# Stop all services
+stop:
+	@echo "Stopping all services..."
+	docker compose down
+
+# Restart services
+restart: stop start
+
+# View logs
+logs:
+	docker compose logs -f
+
+logs-api:
+	docker compose logs -f api
+
+logs-web:
+	docker compose logs -f web
+
+logs-db:
+	docker compose logs -f postgres
+
+# Check status
+status:
+	@docker compose ps
+
+# Health check
+health:
+	@echo "Waiting for services to be healthy..."
+	@sleep 3
+	@docker compose ps --format "table {{.Name}}\t{{.Status}}" | head -10
+
+# Database operations
+migrate:
+	@echo "Running database migrations..."
+	docker compose exec api pnpm exec prisma migrate deploy
+
+migrate-dev:
+	docker compose exec api pnpm exec prisma migrate dev
+
+seed:
+	@echo "Seeding database..."
+	docker compose exec api pnpm exec prisma db seed
+
+studio:
+	@echo "Opening Prisma Studio..."
+	docker compose exec api pnpm exec prisma studio
+
+# Reset database
+reset:
+	@echo "WARNING: This will delete all data. Are you sure? [y/N] " && read ans && [ $${ans:-N} = y ]
+	docker compose down -v
+	@$(MAKE) --no-print-directory start
+	@$(MAKE) --no-print-directory migrate
+	@$(MAKE) --no-print-directory seed
+
+# Clean everything
+clean:
+	@echo "Cleaning up..."
+	docker compose down -v --rmi local --remove-orphans
+	rm -rf apps/api/node_modules apps/web/node_modules
+	rm -rf apps/api/dist apps/web/.next
+
+# Shell access
+shell-api:
+	docker compose exec api sh
+
+shell-db:
+	docker compose exec postgres psql -U opensox -d opensox
+
+# Development without Docker (uses local Node)
+dev-local:
+	@echo "Starting local development..."
+	pnpm install
+	pnpm run dev