feat(m0): bootstrap repo, design system, compose stack

- Repo scaffolding: .gitignore, .env.example, Makefile, docker-compose.yml, README.md, CHANGELOG.md, pre-commit config. - Three-service stack: api (Flask 3), db (postgres:16-alpine), front (nginx serving the Vite bundle). Named volumes metamorph_db + metamorph_evidence. - Backend skeleton: Flask app factory, JSON structured logging on stdout, GET /api/v1/health, multi-stage Dockerfile, pyproject.toml driven by uv, Pydantic Settings with secret guard rails (refuses to boot in non-dev with placeholders), APP_ENV gating. - Frontend skeleton: Vite + React 18 + TypeScript strict + TailwindCSS, RTOps design tokens from tasks/design.md, self-hosted JetBrains Mono / IBM Plex Sans via @fontsource, base UI primitives (Card/Tag/SectionHeader/FlowNode/ Button), home page wired to /api/v1/health. - Engine-agnostic Makefile: auto-detects docker or podman, picks the matching compose driver. Targets: up/down/build/rebuild/dev/lint/fmt/test/migrate/ seed-mitre/print-install-token/e2e/inspect-health. - Playwright suite: e2e/tests/m0-smoke.spec.ts (8 tests) + HTML + JUnit reports + traces on retry. - Docs: tasks/spec.md (finalized after Q&A), tasks/design.md, tasks/todo.md (14 milestones), tasks/testing-m0.md, tasks/lessons.md. DoD: make up + make health + make e2e all pass on podman 5.x (Fedora) and docker. TLS terminated by external reverse proxy (spec §6 NF-network). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 06:16:00 +02:00
commit f1fdf27012
58 changed files with 5365 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,129 @@
+# Metamorph
+
+Collaborative purple-team platform. Red team logs the tests they execute (procedure, command, timestamp); blue team annotates each test with detection evidence (alerts, logs, files). At the end of an engagement, Metamorph generates a standalone reveal.js slide deck classified by MITRE ATT&CK tactic.
+
+> **Status**: M0 (bootstrap). See `tasks/spec.md` for the full specification and `tasks/todo.md` for the milestone-by-milestone plan.
+
+## Stack
+
+- **Backend**: Python 3.12, Flask 3, SQLAlchemy 2 + Alembic (M1+), PostgreSQL 16.
+- **Frontend**: React 18 + TypeScript + Vite + TailwindCSS (RTOps design tokens, see `tasks/design.md`).
+- **Auth (M2+)**: JWT access (1h) + refresh (30d), Argon2id, invite-link enrollment.
+- **Delivery**: docker-compose. TLS termination is expected to be handled by an external reverse proxy in production.
+
+## Quickstart
+
+Works with **Docker** *or* **Podman**. The Makefile auto-detects the available engine and picks the matching compose driver (`docker compose`, `podman compose`, or `podman-compose`).
+
+Requires one of:
+
+- Docker Engine 24+ with the Compose v2 plugin, **or**
+- Podman 4.0+ with `podman compose` (or the legacy `podman-compose` ≥ 1.0.6)
+
+```bash
+git clone <this repo>
+cd Metamorph
+make engine               # confirm which engine the Makefile picked up
+make env                  # creates .env from .env.example
+$EDITOR .env              # set strong values for POSTGRES_PASSWORD and JWT_SECRET
+make up                   # builds and starts api + db + front
+make logs                 # tail logs
+```
+
+Override the auto-detection if you have both engines installed:
+
+```bash
+make up ENGINE=podman                       # force podman + auto-pick its compose driver
+make up ENGINE=docker COMPOSE="docker compose"
+COMPOSE=podman-compose make up              # force the legacy wrapper specifically
+```
+
+Then:
+
+- Front: <http://localhost:8080>
+- API health: <http://localhost:8080/api/v1/health> (proxied) or <http://localhost:8000/api/v1/health>
+
+To stop:
+
+```bash
+make down            # keep volumes
+make clean           # also drop volumes (DESTRUCTIVE)
+```
+
+## Local dev (no Docker)
+
+Requires:
+
+- [uv](https://github.com/astral-sh/uv) for Python deps
+- Node.js 20+ and `npm`
+- A reachable Postgres (or `make up db` to run only the db container)
+
+```bash
+make dev-api     # in one terminal
+make dev-front   # in another
+```
+
+## Environment variables
+
+See `.env.example`. The most important ones:
+
+| Variable           | Purpose                                              |
+|--------------------|------------------------------------------------------|
+| `APP_ENV`          | `dev` allows placeholder secrets; anything else (prod/staging) refuses to boot with defaults |
+| `POSTGRES_*`       | DB credentials (used by `db` and `api`)              |
+| `JWT_SECRET`       | HS256 signing key — generate 64+ random bytes (`python -c "import secrets; print(secrets.token_urlsafe(64))"`) |
+| `LOG_LEVEL`        | `DEBUG` / `INFO` / `WARNING` / `ERROR`               |
+| `FRONT_ORIGIN`     | Allowed CORS origin for the SPA                      |
+| `EVIDENCE_DIR`     | Path inside the api container where uploads land     |
+| `HOST_API_PORT`    | Host port mapped to the api (default 8000)           |
+| `HOST_FRONT_PORT`  | Host port mapped to the front nginx (default 8080)   |
+
+## Testing
+
+- **Manual + automated checklist for the current milestone**: see [`tasks/testing-m<N>.md`](tasks/testing-m0.md) (currently `testing-m0.md`).
+- **Backend unit tests**: `make test-api`
+- **End-to-end (Playwright)**: `make e2e-install` (once), then `make up && make e2e`. Reports land in `e2e/playwright-report/` (HTML + JUnit XML); open with `make e2e-report`.
+
+## Pre-commit hooks
+
+After cloning, install hooks once:
+
+```bash
+pipx install pre-commit   # or: pip install --user pre-commit
+pre-commit install
+pre-commit run --all-files   # initial sweep
+```
+
+The hooks run `ruff` + `ruff-format` on the backend and `eslint` / `tsc --noEmit` / `prettier --check` on the frontend (see `.pre-commit-config.yaml`).
+
+## Project layout
+
+```
+.
+├── backend/             # Flask API
+│   └── app/
+│       ├── api/         # HTTP layer (blueprints)
+│       ├── core/        # config, logging, errors
+│       ├── db/          # SQLAlchemy session, migrations (M1+)
+│       ├── models/      # ORM models (M1+)
+│       ├── services/    # domain logic (M2+)
+│       └── i18n/        # message catalogs (M13)
+├── frontend/            # Vite + React + TS + Tailwind
+│   └── src/components/ui/   # RTOps design system primitives
+├── tasks/
+│   ├── spec.md          # source of truth for requirements
+│   ├── design.md        # RTOps design system
+│   ├── todo.md          # milestone plan
+│   └── lessons.md       # session retrospectives
+├── docker-compose.yml
+├── Makefile
+└── CHANGELOG.md
+```
+
+## Roadmap
+
+See `tasks/todo.md`. Current milestone: **M0 — bootstrap**.
+
+## License
+
+TBD.