feat: developer experience and CI improvements (#347 #348 #349 #357)

.github/workflows/test.yml

@@ -21,6 +21,8 @@ jobs:
 
     - run: npm install
 
+    - name: Audit dependencies for vulnerabilities
+      run: npm audit --audit-level=high
     - name: Type-check TypeScript
       working-directory: frontend
       run: npm run typecheck

CONTRIBUTING.md

@@ -0,0 +1,181 @@
+# Contributing to FuTuRe
+
+Thanks for taking the time to contribute. This guide covers everything you need to get a working local environment, run the test suite, and get your PR reviewed.
+
+## Prerequisites
+
+- Node.js 20.x (see `.nvmrc` or use `nvm use 20`)
+- npm 10+ (bundled with Node 20)
+- PostgreSQL 16 (or use the provided Docker Compose setup)
+- Git
+
+Optional but recommended:
+- Docker + Docker Compose (simplifies database setup)
+- [k6](https://k6.io/docs/get-started/installation/) for load tests
+
+---
+
+## Local Setup
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/Ethereal-Future/FuTuRe.git
+cd FuTuRe
+npm install
+```
+
+### 2. Configure the backend
+
+```bash
+cd backend
+cp .env.example .env
+```
+
+Open `backend/.env` and fill in the required values. At minimum you need:
+
+- `DATABASE_URL` — PostgreSQL connection string
+- `JWT_SECRET` — any strong random string for local dev
+- `STREAM_SECRET_ENCRYPTION_KEY` — 32-byte hex key (see comment in `.env.example`)
+
+See `backend/CONFIGURATION.md` for the full reference.
+
+### 3. Start PostgreSQL
+
+Using Docker (recommended):
+
+```bash
+# from the repo root
+docker compose up db -d
+```
+
+Or point `DATABASE_URL` at an existing local PostgreSQL 16 instance.
+
+### 4. Run database migrations
+
+```bash
+cd backend
+npx prisma migrate deploy
+```
+
+### 5. Start the development servers
+
+From the repo root:
+
+```bash
+npm run dev
+```
+
+This starts both servers concurrently:
+
+| Service  | URL                    |
+|----------|------------------------|
+| Backend  | http://localhost:3001  |
+| Frontend | http://localhost:3000  |
+
+The backend uses `--watch` for hot-reload. The frontend uses Vite HMR.
+
+---
+
+## Running Tests
+
+### Unit and integration tests (with coverage)
+
+```bash
+npm run test:coverage
+```
+
+### Backend-only tests
+
+```bash
+npm run test --workspace=backend
+```
+
+### Database integration tests
+
+Requires a running PostgreSQL instance (use `docker compose up db -d`):
+
+```bash
+npm run test:db --workspace=backend
+```
+
+### Contract tests
+
+```bash
+npm run test:contracts
+```
+
+### Property-based tests
+
+```bash
+npm run test:property
+```
+
+### Load tests
+
+Requires [k6](https://k6.io/docs/get-started/installation/) and a running backend:
+
+```bash
+npm run load-test:endpoints --workspace=backend
+npm run load-test:concurrent --workspace=backend
+npm run load-test:regression --workspace=backend
+```
+
+---
+
+## Running Against Testnet
+
+The backend connects to the Stellar testnet by default. To run against it:
+
+1. Set these values in `backend/.env`:
+
+```env
+STELLAR_NETWORK=testnet
+HORIZON_URL=https://horizon-testnet.stellar.org
+```
+
+2. Start the backend:
+
+```bash
+npm run dev:backend
+```
+
+3. Create a test account via the frontend or the API — new accounts are automatically funded by [Friendbot](https://developers.stellar.org/docs/tutorials/create-account).
+
+> Never use real Stellar mainnet keys in development. The testnet is reset periodically; any balances will be lost.
+
+---
+
+## PR Review Process
+
+1. Fork the repo and create a branch from `main`:
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+2. Make your changes. Keep commits focused — one logical change per commit.
+
+3. Ensure all checks pass locally before pushing:
+   ```bash
+   npm run test:coverage
+   npm audit --audit-level=high
+   ```
+
+4. Push your branch and open a pull request against `main`.
+
+5. Fill in the PR template. Include:
+   - What the change does and why
+   - How you tested it
+   - Any follow-up work or known limitations
+
+6. A maintainer will review within a few business days. Address feedback by pushing new commits — do not force-push after review has started.
+
+7. Once approved, a maintainer will squash-merge your PR.
+
+### PR checklist
+
+- [ ] Tests added or updated for new behaviour
+- [ ] `npm run test:coverage` passes
+- [ ] No new high/critical vulnerabilities (`npm audit --audit-level=high`)
+- [ ] Code formatted with `npm run format`
+- [ ] PR description explains the change clearly

PR_MESSAGE.md

@@ -0,0 +1,46 @@
+# Developer Experience & CI Improvements
+
+Closes #347, #348, #349, #357
+
+## Summary
+
+This PR improves the onboarding experience for new contributors and tightens the CI pipeline. A new contributor can now clone the repo, run `docker compose up`, and have a fully working local environment without any manual configuration guesswork.
+
+## Changes
+
+### #347 — CONTRIBUTING.md
+Added a full contributing guide covering:
+- Prerequisites (Node 20, PostgreSQL 16, Docker)
+- Step-by-step local setup from clone to running servers
+- All test commands (unit, integration, contract, property, load)
+- How to run against Stellar testnet
+- PR review process and checklist
+
+### #348 — backend/.env.example
+Rewrote the env file with inline documentation for every variable:
+- Each entry is marked `[REQUIRED]` or `[OPTIONAL]`
+- Valid values and defaults are documented inline
+- Added detailed examples for `PLATFORM_FEE_ACCOUNT_SECRET`, `FEE_BUMP_THRESHOLD_XLM`, and `COINGECKO_API_KEY`
+- Grouped variables by concern (Stellar, security, database, cache, etc.)
+
+### #349 — CI vulnerability audit
+Added `npm audit --audit-level=high` to `.github/workflows/test.yml` immediately after `npm install`. The build fails if any high or critical vulnerability is found in the dependency tree.
+
+### #357 — docker-compose.yml for local development
+Added a standard `docker-compose.yml` that spins up three services:
+- `db` — PostgreSQL 16 with a persistent named volume
+- `backend` — Node 20 with `node --watch` hot-reload; runs `prisma migrate deploy` on startup
+- `frontend` — Vite dev server with HMR, proxying `/api` to the backend
+
+Also added minimal `Dockerfile.dev` for both backend and frontend.
+
+## Testing
+
+- Verified `test.yml` audit step is correctly positioned and uses the right flag
+- `CONTRIBUTING.md` setup steps validated against the actual project scripts and `.env.example` values
+- Docker Compose service dependencies and healthchecks confirmed against the test compose file patterns already in the repo
+
+## Notes
+
+- The `STREAM_SECRET_ENCRYPTION_KEY` in `docker-compose.yml` is set to a zeroed placeholder — intentional for local dev only, clearly commented
+- `JWT_SECRET` in compose is also a dev-only placeholder with a comment to change it before any real use