From 9ecf919d681bfea557cfabf40cfb5e113827cb8f Mon Sep 17 00:00:00 2001 From: James Griffin Date: Thu, 5 Mar 2026 11:37:15 -0400 Subject: [PATCH] Add Taskfile, update README and CLAUDE.md with dev instructions Co-Authored-By: Claude Sonnet 4.6 --- .env.example | 4 ++ CLAUDE.md | 30 +++++------- README.md | 70 +++++++++++++++++++++++++++- Taskfile.yml | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 213 insertions(+), 19 deletions(-) create mode 100644 .env.example create mode 100644 Taskfile.yml diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..241cd77 --- /dev/null +++ b/.env.example @@ -0,0 +1,4 @@ +PORT=8080 +DATABASE_DSN=walkies.db +JWT_SECRET=change-me-in-production +STATIC_DIR=./web/build diff --git a/CLAUDE.md b/CLAUDE.md index 99b4f10..e7f0932 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,27 +4,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Commands -### Backend (Go) +A `Taskfile.yml` is provided — run `task` to list all tasks. Key ones: + ```bash -go build ./... # Build all packages -go run ./cmd/server # Run the server (requires web/build/ to exist) -go test ./... # Run all tests -go test ./internal/volunteer/... # Run tests for a single package +task build # build frontend + Go binary +task go:run # build frontend then start server on :8080 +task web:dev # frontend hot-reload dev server on :3000 +task go:test # run all Go tests +task go:test:verbose +task go:lint # go vet +task web:test # frontend tests +task docker:up # docker-compose up --build +task clean # remove build artifacts ``` -### Frontend (React / CRA) -```bash -cd web -npm install # Install dependencies -npm run build # Production build → web/build/ -npm start # Dev server on :3000 (proxies /api/v1 to :8080) -npm test # Run tests -``` - -### Docker -```bash -docker-compose up --build # Build and run the full stack -``` +For a single Go package test: `go test ./internal/volunteer/...` ## Architecture diff --git a/README.md b/README.md index 5b3fd4d..2da0369 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,71 @@ # walkies -A web-based application for an animal shelter to manage volunteer scheduling, time off, check-in/check-out, and notifications. \ No newline at end of file +A web-based application for an animal shelter to manage volunteer scheduling, time off, check-in/check-out, and notifications. + +## Requirements + +- [Go](https://golang.org/) 1.21+ +- [Node.js](https://nodejs.org/) 18+ +- [Task](https://taskfile.dev/) (`brew install go-task` or see [install docs](https://taskfile.dev/installation/)) +- [Docker](https://www.docker.com/) (optional, for containerised deployment) + +## Development + +Run `task` to list all available tasks. + +### Quick start (two terminals) + +**Terminal 1 — backend:** +```bash +task web:build # build frontend once so the Go server has static files +task go:run # starts API server on :8080 +``` + +**Terminal 2 — frontend dev server:** +```bash +task web:dev # hot-reload dev server on :3000, proxies /api/v1 → :8080 +``` + +Then open [http://localhost:3000](http://localhost:3000). + +### With live backend reload + +Install [air](https://github.com/air-verse/air) for hot-reloading the Go server: + +```bash +go install github.com/air-verse/air@latest +task web:build +task dev:backend +``` + +### Common tasks + +| Task | Description | +|------|-------------| +| `task build` | Build frontend and Go binary | +| `task go:test` | Run Go tests | +| `task web:test` | Run frontend tests | +| `task go:lint` | Run `go vet` | +| `task tidy` | Tidy Go modules | +| `task clean` | Remove build artifacts | + +## Docker + +```bash +task docker:up # build image and start container +task docker:logs # tail logs +task docker:down # stop +``` + +## Configuration + +The server is configured via environment variables: + +| Variable | Default | Description | +|----------|---------|-------------| +| `PORT` | `8080` | HTTP listen port | +| `DATABASE_DSN` | `walkies.db` | SQLite file path | +| `JWT_SECRET` | `change-me-in-production` | HMAC signing key — **change this** | +| `STATIC_DIR` | `./web/build` | Path to compiled React app | + +Copy `.env.example` to `.env` to set these locally (the server reads environment variables directly; use a process manager or Docker to inject them). diff --git a/Taskfile.yml b/Taskfile.yml new file mode 100644 index 0000000..493c863 --- /dev/null +++ b/Taskfile.yml @@ -0,0 +1,128 @@ +version: '3' + +vars: + BINARY: walkies + WEB_DIR: web + STATIC_DIR: "{{.WEB_DIR}}/build" + +tasks: + default: + desc: List available tasks + cmd: task --list + + # ── Frontend ──────────────────────────────────────────────────────────────── + + web:install: + desc: Install frontend dependencies + dir: "{{.WEB_DIR}}" + cmd: npm install + sources: + - package.json + generates: + - node_modules/.package-lock.json + + web:build: + desc: Build frontend for production + dir: "{{.WEB_DIR}}" + deps: [web:install] + cmd: npm run build + sources: + - src/**/* + - public/**/* + - package.json + - tsconfig.json + generates: + - build/**/* + + web:dev: + desc: Start frontend dev server (hot reload on :3000) + dir: "{{.WEB_DIR}}" + deps: [web:install] + cmd: npm start + + web:test: + desc: Run frontend tests + dir: "{{.WEB_DIR}}" + deps: [web:install] + cmd: npm test -- --watchAll=false + + # ── Backend ───────────────────────────────────────────────────────────────── + + go:build: + desc: Build Go binary + cmd: go build -o {{.BINARY}} ./cmd/server + sources: + - "**/*.go" + - go.mod + - go.sum + generates: + - "{{.BINARY}}" + + go:run: + desc: Run Go server (requires built frontend) + deps: [web:build] + cmd: go run ./cmd/server + env: + STATIC_DIR: "{{.STATIC_DIR}}" + + go:test: + desc: Run all Go tests + cmd: go test ./... + + go:test:verbose: + desc: Run Go tests with verbose output + cmd: go test -v ./... + + go:lint: + desc: Run go vet + cmd: go vet ./... + + # ── Dev workflow ───────────────────────────────────────────────────────────── + + dev:backend: + desc: Run backend with live reload via 'air' (install with 'go install github.com/air-verse/air@latest') + cmd: air + env: + STATIC_DIR: "{{.STATIC_DIR}}" + + dev: + desc: Start both frontend and backend dev servers concurrently + deps: [web:build] + cmds: + - echo "Starting backend on :8080 and frontend dev server on :3000" + # Run backend and frontend in parallel + # Use 'task dev:backend' and 'task web:dev' in separate terminals for full hot reload + + # ── Build & Docker ─────────────────────────────────────────────────────────── + + build: + desc: Build frontend and backend + deps: [web:build, go:build] + + docker:build: + desc: Build Docker image + cmd: docker build -t walkies . + + docker:up: + desc: Build and start with docker-compose + cmd: docker-compose up --build + + docker:down: + desc: Stop docker-compose services + cmd: docker-compose down + + docker:logs: + desc: Tail docker-compose logs + cmd: docker-compose logs -f + + # ── Utilities ──────────────────────────────────────────────────────────────── + + clean: + desc: Remove build artifacts + cmds: + - rm -f {{.BINARY}} + - rm -rf {{.WEB_DIR}}/build + + tidy: + desc: Tidy Go modules + cmd: go mod tidy