157 lines
4.3 KiB
Markdown
157 lines
4.3 KiB
Markdown
# Contributing to BanGUI
|
|
|
|
Welcome! This guide covers everything you need to know to set up your dev environment, understand the codebase, and submit changes.
|
|
|
|
---
|
|
|
|
## Dev Setup
|
|
|
|
### 1 — Clone and init
|
|
|
|
```bash
|
|
git clone <repo-url>
|
|
cd BanGUI
|
|
cp .env.example .env
|
|
python -c 'import secrets; print(secrets.token_hex(32))'
|
|
# paste output as BANGUI_SESSION_SECRET in .env
|
|
```
|
|
|
|
### 2 — Start the stack
|
|
|
|
```bash
|
|
make up
|
|
```
|
|
|
|
Backend: http://127.0.0.1:8000 · Frontend (Vite proxy): http://127.0.0.1:5173
|
|
|
|
### 3 — Editor Setup
|
|
|
|
Install **EditorConfig** plugin for your IDE. Ensures consistent formatting (indent style, line endings) across all editors.
|
|
|
|
| IDE | Plugin |
|
|
|-----|--------|
|
|
| VS Code | EditorConfig (ms-vscode.editorconfig) |
|
|
| PyCharm / IntelliJ | Built-in (enable in Settings → Editor → Code Style) |
|
|
| Vim / Neovim | editorconfig-vim |
|
|
| Sublime Text | EditorConfig |
|
|
|
|
### 4 — Pre-commit hooks
|
|
|
|
**Backend** (pre-commit, all languages):
|
|
|
|
```bash
|
|
pip install pre-commit
|
|
pre-commit install
|
|
```
|
|
|
|
**Frontend** (husky, TypeScript validation):
|
|
|
|
```bash
|
|
cd frontend && npm install
|
|
npx husky install
|
|
```
|
|
|
|
Hooks run automatically on every `git commit`. To run manually:
|
|
|
|
```bash
|
|
pre-commit run --all-files # backend hooks
|
|
cd frontend && npm run validate:types # frontend type check
|
|
```
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
BanGUI/
|
|
├── backend/ Python FastAPI app
|
|
│ └── app/
|
|
│ ├── routers/ HTTP endpoint handlers
|
|
│ ├── services/ Business logic
|
|
│ ├── repos/ Data access
|
|
│ ├── models/ Pydantic request/response/domain models
|
|
│ └── utils/ Shared helpers
|
|
├── frontend/ React + TypeScript + Fluent UI v9
|
|
│ └── src/
|
|
│ ├── pages/ Route-level page components
|
|
│ ├── components/ Reusable UI components
|
|
│ ├── hooks/ Custom React hooks
|
|
│ └── types/ Shared TypeScript types
|
|
├── Docs/ Architecture, design, and feature documentation
|
|
└── Docker/ Container compose files
|
|
```
|
|
|
|
---
|
|
|
|
## Code Quality
|
|
|
|
| Tool | Scope | Command |
|
|
|---|---|---|
|
|
| `ruff` | Backend linting | `cd backend && ruff check .` |
|
|
| `ruff-format` | Backend formatting | `cd backend && ruff format .` |
|
|
| `mypy --strict` | Backend type checking | `cd backend && mypy --strict app` |
|
|
| `tsc --noEmit` | Frontend type checking | `cd frontend && tsc --noEmit` |
|
|
| `eslint` | Frontend linting | `cd frontend && eslint src` |
|
|
| `prettier --check` | Frontend formatting | `cd frontend && prettier --check src` |
|
|
| `import-linter` | Layer boundary enforcement | `cd backend && linter` |
|
|
|
|
**All checks must pass before committing.** CI runs the same suite.
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend && pytest --cov=app --cov-report=term-missing
|
|
|
|
# Coverage threshold: 80%. Build fails if coverage drops below.
|
|
```
|
|
|
|
The CI pipeline enforces the same 80% minimum coverage threshold.
|
|
|
|
---
|
|
|
|
## Security Rules
|
|
|
|
### Never echo raw user input in error messages
|
|
|
|
User-supplied values (jail names, filter names, action names, IPs, filenames, etc.)
|
|
MUST be sanitized before interpolation into any string that may be rendered in an
|
|
HTML context (error messages, admin UI, email notifications).
|
|
|
|
Use the `sanitize_for_display()` helper from `app.utils.display_sanitizer`:
|
|
|
|
```python
|
|
from app.utils.display_sanitizer import sanitize_for_display
|
|
|
|
# Good: sanitized before display
|
|
super().__init__(f"Jail not found: {sanitize_for_display(name)!r}")
|
|
|
|
# Bad: raw user input echoed — XSS vector if rendered as HTML
|
|
super().__init__(f"Jail not found: {name!r}")
|
|
```
|
|
|
|
This rule applies even when the value has been validated: validation checks the
|
|
format, not the rendering context. JSON API responses do NOT need sanitization
|
|
(JSON is not HTML); apply it only at HTML render boundaries.
|
|
|
|
---
|
|
|
|
## Stack
|
|
|
|
| Layer | Stack |
|
|
|---|---|
|
|
| Backend | Python 3.12+, FastAPI, Pydantic v2, aiosqlite, structlog |
|
|
| Frontend | TypeScript, React, Fluent UI v9, Vite |
|
|
| Container | Docker Compose (development + production) |
|
|
|
|
---
|
|
|
|
## Key Docs
|
|
|
|
- [Instructions.md](Docs/Instructions.md) — Agent operating rules
|
|
- [Backend-Development.md](Docs/Backend-Development.md) — Backend conventions
|
|
- [Web-Development.md](Docs/Web-Development.md) — Frontend conventions
|
|
- [Features.md](Docs/Features.md) — Complete feature list
|
|
- [Architekture.md](Docs/Architekture.md) — System architecture |