A community based topic aggregation platform built on atproto
bretton.dev
1.PHONY: help dev-up dev-down dev-logs dev-status dev-reset test test-all e2e-test clean verify-stack create-test-account mobile-full-setup
2
3# Default target - show help
4.DEFAULT_GOAL := help
5
6# Colors for output
7CYAN := \033[36m
8RESET := \033[0m
9GREEN := \033[32m
10YELLOW := \033[33m
11RED := \033[31m
12
13# Load test database configuration from .env.dev
14include .env.dev
15export
16
17##@ General
18
19help: ## Show this help message
20 @echo ""
21 @echo "$(CYAN)Coves Development Commands$(RESET)"
22 @echo ""
23 @awk 'BEGIN {FS = ":.*##"; printf "Usage: make $(CYAN)<target>$(RESET)\n"} \
24 /^[a-zA-Z_-]+:.*?##/ { printf " $(CYAN)%-15s$(RESET) %s\n", $$1, $$2 } \
25 /^##@/ { printf "\n$(YELLOW)%s$(RESET)\n", substr($$0, 5) }' $(MAKEFILE_LIST)
26 @echo ""
27
28##@ Local Development (All-in-One)
29
30dev-up: ## Start PDS + PostgreSQL + Jetstream + PLC Directory for local development
31 @echo "$(GREEN)Starting Coves development stack...$(RESET)"
32 @docker-compose -f docker-compose.dev.yml --env-file .env.dev --profile jetstream --profile plc up -d postgres postgres-plc plc-directory pds jetstream
33 @echo ""
34 @echo "$(GREEN)✓ Development stack started!$(RESET)"
35 @echo ""
36 @echo "Services available at:"
37 @echo " - PostgreSQL: localhost:5435"
38 @echo " - PDS (XRPC): http://localhost:3001"
39 @echo " - PDS Firehose: ws://localhost:3001/xrpc/com.atproto.sync.subscribeRepos"
40 @echo " - Jetstream: ws://localhost:6008/subscribe $(CYAN)(Read-Forward)$(RESET)"
41 @echo " - Jetstream Metrics: http://localhost:6009/metrics"
42 @echo " - PLC Directory: http://localhost:3002 $(CYAN)(Local DID registry)$(RESET)"
43 @echo ""
44 @echo "$(CYAN)Next steps:$(RESET)"
45 @echo " 1. Run: make run (starts AppView)"
46 @echo " 2. AppView will auto-index users from Jetstream"
47 @echo ""
48 @echo "$(CYAN)Note:$(RESET) Using local PLC directory - DIDs registered locally (won't pollute plc.directory)"
49 @echo "Run 'make dev-logs' to view logs"
50
51dev-down: ## Stop all development services
52 @echo "$(YELLOW)Stopping Coves development stack...$(RESET)"
53 @docker-compose -f docker-compose.dev.yml --env-file .env.dev down --remove-orphans
54 @docker network rm coves-dev-network 2>/dev/null || true
55 @echo "$(GREEN)✓ Development stack stopped$(RESET)"
56
57dev-logs: ## Tail logs from all development services
58 @docker-compose -f docker-compose.dev.yml --env-file .env.dev logs -f
59
60dev-status: ## Show status of all development containers
61 @echo "$(CYAN)Development Stack Status:$(RESET)"
62 @docker-compose -f docker-compose.dev.yml --env-file .env.dev ps
63
64dev-reset: ## Nuclear option - stop everything and remove all volumes
65 @echo "$(YELLOW)⚠️ WARNING: This will delete ALL data (PostgreSQL + PDS)!$(RESET)"
66 @read -p "Are you sure? (y/N): " confirm && [ "$$confirm" = "y" ] || exit 1
67 @echo "$(YELLOW)Stopping and removing containers and volumes...$(RESET)"
68 @docker-compose -f docker-compose.dev.yml --env-file .env.dev down -v
69 @echo "$(GREEN)✓ Reset complete - all data removed$(RESET)"
70 @echo "Run 'make dev-up' to start fresh"
71
72##@ Database Management
73
74db-shell: ## Open PostgreSQL shell for development database
75 @echo "$(CYAN)Connecting to development database...$(RESET)"
76 @docker exec -it coves-dev-postgres psql -U dev_user -d coves_dev
77
78db-migrate: ## Run database migrations
79 @echo "$(GREEN)Running database migrations...$(RESET)"
80 @goose -dir internal/db/migrations postgres "postgresql://dev_user:dev_password@localhost:5433/coves_dev?sslmode=disable" up
81 @echo "$(GREEN)✓ Migrations complete$(RESET)"
82
83db-migrate-down: ## Rollback last migration
84 @echo "$(YELLOW)Rolling back last migration...$(RESET)"
85 @goose -dir internal/db/migrations postgres "postgresql://dev_user:dev_password@localhost:5433/coves_dev?sslmode=disable" down
86 @echo "$(GREEN)✓ Rollback complete$(RESET)"
87
88db-reset: ## Reset database (delete all data and re-run migrations)
89 @echo "$(YELLOW)⚠️ WARNING: This will delete all database data!$(RESET)"
90 @read -p "Are you sure? (y/N): " confirm && [ "$$confirm" = "y" ] || exit 1
91 @echo "$(YELLOW)Resetting database...$(RESET)"
92 @docker-compose -f docker-compose.dev.yml --env-file .env.dev rm -sf postgres
93 @docker volume rm coves-dev-postgres-data || true
94 @docker-compose -f docker-compose.dev.yml --env-file .env.dev up -d postgres
95 @echo "Waiting for PostgreSQL to be ready..."
96 @sleep 3
97 @make db-migrate
98 @echo "$(GREEN)✓ Database reset complete$(RESET)"
99
100##@ Testing
101
102test: ## Run fast unit/integration tests (skips slow E2E tests)
103 @echo "$(GREEN)Starting test database...$(RESET)"
104 @docker-compose -f docker-compose.dev.yml --env-file .env.dev --profile test up -d postgres-test
105 @echo "Waiting for test database to be ready..."
106 @sleep 3
107 @echo "$(GREEN)Running migrations on test database...$(RESET)"
108 @goose -dir internal/db/migrations postgres "postgresql://$(POSTGRES_TEST_USER):$(POSTGRES_TEST_PASSWORD)@localhost:$(POSTGRES_TEST_PORT)/$(POSTGRES_TEST_DB)?sslmode=disable" up || true
109 @echo "$(GREEN)Running fast tests (use 'make e2e-test' for E2E tests)...$(RESET)"
110 @go test ./cmd/... ./internal/... ./tests/... -short -v
111 @echo "$(GREEN)✓ Tests complete$(RESET)"
112
113e2e-test: ## Run automated E2E tests (requires: make dev-up + make run in another terminal)
114 @echo "$(CYAN)========================================$(RESET)"
115 @echo "$(CYAN) E2E Test: Full User Signup Flow $(RESET)"
116 @echo "$(CYAN)========================================$(RESET)"
117 @echo ""
118 @echo "$(CYAN)Prerequisites:$(RESET)"
119 @echo " 1. Run 'make dev-up' (starts PDS + Jetstream)"
120 @echo " 2. Run 'make run' in another terminal (AppView must be running)"
121 @echo ""
122 @echo "$(GREEN)Running E2E tests...$(RESET)"
123 @go test ./tests/e2e -run TestE2E_UserSignup -v
124 @echo ""
125 @echo "$(GREEN)✓ E2E tests complete!$(RESET)"
126
127e2e-vote-test: ## Run vote E2E tests (requires: make dev-up)
128 @echo "$(CYAN)========================================$(RESET)"
129 @echo "$(CYAN) E2E Test: Vote System $(RESET)"
130 @echo "$(CYAN)========================================$(RESET)"
131 @echo ""
132 @echo "$(CYAN)Prerequisites:$(RESET)"
133 @echo " 1. Run 'make dev-up' (starts PDS + Jetstream + PostgreSQL)"
134 @echo " 2. Test database will be used (port 5434)"
135 @echo ""
136 @echo "$(GREEN)Running vote E2E tests...$(RESET)"
137 @echo ""
138 @echo "$(CYAN)Running simulated E2E test (fast)...$(RESET)"
139 @go test ./tests/integration -run TestVote_E2E_WithJetstream -v
140 @echo ""
141 @echo "$(CYAN)Running live PDS E2E test (requires PDS + Jetstream)...$(RESET)"
142 @go test ./tests/integration -run TestVote_E2E_LivePDS -v || echo "$(YELLOW)Live PDS test skipped (run 'make dev-up' first)$(RESET)"
143 @echo ""
144 @echo "$(GREEN)✓ Vote E2E tests complete!$(RESET)"
145
146test-db-reset: ## Reset test database
147 @echo "$(GREEN)Resetting test database...$(RESET)"
148 @docker-compose -f docker-compose.dev.yml --env-file .env.dev --profile test rm -sf postgres-test
149 @docker volume rm coves-test-postgres-data || true
150 @docker-compose -f docker-compose.dev.yml --env-file .env.dev --profile test up -d postgres-test
151 @echo "Waiting for PostgreSQL to be ready..."
152 @sleep 3
153 @goose -dir internal/db/migrations postgres "postgresql://$(POSTGRES_TEST_USER):$(POSTGRES_TEST_PASSWORD)@localhost:$(POSTGRES_TEST_PORT)/$(POSTGRES_TEST_DB)?sslmode=disable" up || true
154 @echo "$(GREEN)✓ Test database reset$(RESET)"
155
156test-db-stop: ## Stop test database
157 @docker-compose -f docker-compose.dev.yml --env-file .env.dev --profile test stop postgres-test
158 @echo "$(GREEN)✓ Test database stopped$(RESET)"
159
160test-all: ## Run ALL tests with live infrastructure (required before merge)
161 @echo ""
162 @echo "$(CYAN)═══════════════════════════════════════════════════════════════$(RESET)"
163 @echo "$(CYAN) FULL TEST SUITE - All tests with live infrastructure $(RESET)"
164 @echo "$(CYAN)═══════════════════════════════════════════════════════════════$(RESET)"
165 @echo ""
166 @echo "$(YELLOW)▶ Checking infrastructure...$(RESET)"
167 @echo ""
168 @# Check dev stack is running
169 @echo " Checking dev stack (PDS, Jetstream, PLC)..."
170 @docker-compose -f docker-compose.dev.yml --env-file .env.dev ps 2>/dev/null | grep -q "Up" || \
171 (echo "$(RED) ✗ Dev stack not running. Run 'make dev-up' first.$(RESET)" && exit 1)
172 @echo " $(GREEN)✓ Dev stack is running$(RESET)"
173 @# Check AppView is running
174 @echo " Checking AppView (port 8081)..."
175 @curl -sf http://127.0.0.1:8081/xrpc/_health >/dev/null 2>&1 || \
176 curl -sf http://127.0.0.1:8081/ >/dev/null 2>&1 || \
177 (echo "$(RED) ✗ AppView not running. Run 'make run' in another terminal.$(RESET)" && exit 1)
178 @echo " $(GREEN)✓ AppView is running$(RESET)"
179 @# Check test database
180 @echo " Checking test database (port 5434)..."
181 @docker-compose -f docker-compose.dev.yml --env-file .env.dev ps postgres-test 2>/dev/null | grep -q "Up" || \
182 (echo "$(YELLOW) ⚠ Test database not running, starting it...$(RESET)" && \
183 docker-compose -f docker-compose.dev.yml --env-file .env.dev --profile test up -d postgres-test && \
184 sleep 3 && \
185 goose -dir internal/db/migrations postgres "postgresql://$(POSTGRES_TEST_USER):$(POSTGRES_TEST_PASSWORD)@localhost:$(POSTGRES_TEST_PORT)/$(POSTGRES_TEST_DB)?sslmode=disable" up)
186 @echo " $(GREEN)✓ Test database is running$(RESET)"
187 @echo ""
188 @echo "$(GREEN)▶ [1/3] Unit & Package Tests (./cmd/... ./internal/...)$(RESET)"
189 @echo "$(CYAN)───────────────────────────────────────────────────────────────$(RESET)"
190 @LOG_ENABLED=false go test ./cmd/... ./internal/... -timeout 120s
191 @echo ""
192 @echo "$(GREEN)▶ [2/3] Integration Tests (./tests/integration/...)$(RESET)"
193 @echo "$(CYAN)───────────────────────────────────────────────────────────────$(RESET)"
194 @LOG_ENABLED=false go test ./tests/integration/... -timeout 180s
195 @echo ""
196 @echo "$(GREEN)▶ [3/3] E2E Tests (./tests/e2e/...)$(RESET)"
197 @echo "$(CYAN)───────────────────────────────────────────────────────────────$(RESET)"
198 @LOG_ENABLED=false go test ./tests/e2e/... -timeout 180s
199 @echo ""
200 @echo "$(GREEN)═══════════════════════════════════════════════════════════════$(RESET)"
201 @echo "$(GREEN) ✓ ALL TESTS PASSED - Safe to merge $(RESET)"
202 @echo "$(GREEN)═══════════════════════════════════════════════════════════════$(RESET)"
203 @echo ""
204
205##@ Code Quality
206
207fmt: ## Format all Go code with gofmt
208 @echo "$(GREEN)Formatting Go code...$(RESET)"
209 @gofmt -w ./cmd ./internal ./tests
210 @echo "$(GREEN)✓ Formatting complete$(RESET)"
211
212fmt-check: ## Check if Go code is properly formatted
213 @echo "$(GREEN)Checking code formatting...$(RESET)"
214 @unformatted=$$(gofmt -l ./cmd ./internal ./tests); \
215 if [ -n "$$unformatted" ]; then \
216 echo "$(RED)✗ The following files are not formatted:$(RESET)"; \
217 echo "$$unformatted"; \
218 echo "$(YELLOW)Run 'make fmt' to fix$(RESET)"; \
219 exit 1; \
220 fi
221 @echo "$(GREEN)✓ All files are properly formatted$(RESET)"
222
223lint: fmt-check ## Run golangci-lint on the codebase (includes format check)
224 @echo "$(GREEN)Running linter...$(RESET)"
225 @golangci-lint run ./cmd/... ./internal/... ./tests/...
226 @echo "$(GREEN)✓ Linting complete$(RESET)"
227
228lint-fix: ## Run golangci-lint and auto-fix issues
229 @echo "$(GREEN)Running linter with auto-fix...$(RESET)"
230 @golangci-lint run --fix ./cmd/... ./internal/... ./tests/...
231 @gofmt -w ./cmd ./internal ./tests
232 @echo "$(GREEN)✓ Linting complete$(RESET)"
233
234##@ Build & Run
235
236build: ## Build the Coves server (production - no dev code)
237 @echo "$(GREEN)Building Coves server (production)...$(RESET)"
238 @go build -o server ./cmd/server
239 @echo "$(GREEN)✓ Build complete: ./server$(RESET)"
240
241build-dev: ## Build the Coves server with dev mode (includes localhost OAuth resolvers)
242 @echo "$(GREEN)Building Coves server (dev mode)...$(RESET)"
243 @go build -tags dev -o server ./cmd/server
244 @echo "$(GREEN)✓ Build complete: ./server (with dev tags)$(RESET)"
245
246run: ## Run the Coves server with dev environment (requires database running)
247 @./scripts/dev-run.sh
248
249##@ Cleanup
250
251clean: ## Clean build artifacts and temporary files
252 @echo "$(YELLOW)Cleaning build artifacts...$(RESET)"
253 @rm -f server main validate-lexicon
254 @go clean
255 @echo "$(GREEN)✓ Clean complete$(RESET)"
256
257clean-all: clean ## Clean everything including Docker volumes (DESTRUCTIVE)
258 @echo "$(YELLOW)⚠️ WARNING: This will remove ALL Docker volumes!$(RESET)"
259 @read -p "Are you sure? (y/N): " confirm && [ "$$confirm" = "y" ] || exit 1
260 @make dev-reset
261 @echo "$(GREEN)✓ All clean$(RESET)"
262
263##@ Workflows (Common Tasks)
264
265fresh-start: ## Complete fresh start (reset everything, start clean)
266 @echo "$(CYAN)Starting fresh development environment...$(RESET)"
267 @make dev-reset || true
268 @sleep 2
269 @make dev-up
270 @sleep 3
271 @make db-migrate
272 @echo ""
273 @echo "$(GREEN)✓ Fresh environment ready!$(RESET)"
274 @make dev-status
275
276quick-restart: ## Quick restart of development stack (keeps data)
277 @make dev-down
278 @make dev-up
279
280##@ Mobile Testing
281
282mobile-setup: ## Setup Android port forwarding for USB-connected devices (recommended)
283 @echo "$(CYAN)Setting up Android mobile testing environment...$(RESET)"
284 @./scripts/setup-mobile-ports.sh
285
286mobile-reset: ## Remove all Android port forwarding
287 @echo "$(YELLOW)Removing Android port forwarding...$(RESET)"
288 @adb reverse --remove-all || echo "$(YELLOW)No device connected$(RESET)"
289 @echo "$(GREEN)✓ Port forwarding removed$(RESET)"
290
291verify-stack: ## Verify local development stack (PLC, PDS, configs)
292 @./scripts/verify-local-stack.sh
293
294create-test-account: ## Create a test account on local PDS for OAuth testing
295 @./scripts/create-test-account.sh
296
297mobile-full-setup: verify-stack create-test-account mobile-setup ## Full mobile setup: verify stack, create account, setup ports
298 @echo ""
299 @echo "$(GREEN)═══════════════════════════════════════════════════════════$(RESET)"
300 @echo "$(GREEN) Mobile development environment ready! $(RESET)"
301 @echo "$(GREEN)═══════════════════════════════════════════════════════════$(RESET)"
302 @echo ""
303 @echo "$(CYAN)Run the Flutter app with:$(RESET)"
304 @echo " $(YELLOW)cd /home/bretton/Code/coves-mobile$(RESET)"
305 @echo " $(YELLOW)flutter run --dart-define=ENVIRONMENT=local$(RESET)"
306 @echo ""
307
308ngrok-up: ## Start ngrok tunnels (for iOS or WiFi testing - requires paid plan for 3 tunnels)
309 @echo "$(GREEN)Starting ngrok tunnels for mobile testing...$(RESET)"
310 @./scripts/start-ngrok.sh
311
312ngrok-down: ## Stop all ngrok tunnels
313 @./scripts/stop-ngrok.sh
314
315##@ Utilities
316
317validate-lexicon: ## Validate all Lexicon schemas
318 @echo "$(GREEN)Validating Lexicon schemas...$(RESET)"
319 @./validate-lexicon
320 @echo "$(GREEN)✓ Lexicon validation complete$(RESET)"
321
322##@ Documentation
323
324docs: ## Open project documentation
325 @echo "$(CYAN)Project Documentation:$(RESET)"
326 @echo " - Setup Guide: docs/LOCAL_DEVELOPMENT.md"
327 @echo " - Project Structure: PROJECT_STRUCTURE.md"
328 @echo " - Build Guide: CLAUDE.md"
329 @echo " - atProto Guide: ATPROTO_GUIDE.md"
330 @echo " - PRD: PRD.md"