peter
361ca7872e
gate / frontend (push) Failing after 1m16s
gate / backend (push) Successful in 2m16s
- CLAUDE.md: new "Collaboration" section (plan-first, options-with-marked- optimal-and-why, mockups for design decisions, challenge unsound requests, visual UAT before done, terse otherwise). - CLAUDE.md: clarify release is user-owned in timing, agent-run in execution. - CLAUDE.md + docs/development.md: document the ruff format --check gate step (already enforced in .gitea/workflows/check.yml, was missing from the docs). - CLAUDE.md: refresh the stale footer to point at the now-existing docs/development.md and backend/app/README.md.
63 lines
2.3 KiB
Markdown
63 lines
2.3 KiB
Markdown
# Development
|
|
|
|
How to run Siftlode locally and pass the gate. Conventions for the backend code itself live in
|
|
[`backend/app/README.md`](../backend/app/README.md).
|
|
|
|
## Run it locally
|
|
|
|
The whole stack (Postgres + API + worker) comes up from the localdev compose file:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.localdev.yml up --build
|
|
```
|
|
|
|
Browse at **http://localhost:8080** (Google login works — the OAuth redirect is
|
|
`http://localhost:8080/auth/callback`). The API runs `alembic upgrade head` on startup, so the schema
|
|
is always current.
|
|
|
|
For a fast frontend edit loop, run the Vite dev server with HMR against that API:
|
|
|
|
```bash
|
|
cd frontend && npm install && npm run dev # http://localhost:5173, proxying the API on :8080
|
|
```
|
|
|
|
## The gate
|
|
|
|
A change is done when all of this is green. CI runs the same checks server-side
|
|
(`.gitea/workflows/check.yml`), so "main is always green".
|
|
|
|
**Backend**
|
|
|
|
```bash
|
|
# lint + format check
|
|
python -m ruff check --config backend/ruff.toml backend scripts
|
|
python -m ruff format --check --config backend/ruff.toml backend scripts
|
|
|
|
# tests — pure-logic + the DB-backed integration lane, against an ephemeral Postgres.
|
|
# The backend tree is bind-mounted, so it always tests your working files.
|
|
docker compose -f backend/docker-compose.test.yml up --build --abort-on-container-exit --exit-code-from test
|
|
docker compose -f backend/docker-compose.test.yml down -v
|
|
```
|
|
|
|
The test compose sets `SIFTLODE_TEST_REQUIRE_DB=1`, which turns a would-be silent skip (no DB, or no
|
|
ffmpeg) into a hard failure — so the gate can't print green while the DB-backed tests were quietly not
|
|
run. Tests that need a database take the `db` fixture (`backend/tests/conftest.py`); the rest are
|
|
pure-logic and run without one.
|
|
|
|
**Frontend** (from `frontend/`)
|
|
|
|
```bash
|
|
npm run typecheck # tsc x3 (app / node / e2e)
|
|
npm run lint # eslint
|
|
npm run format:check # prettier
|
|
npm run knip # unused exports/deps
|
|
npm run test # vitest
|
|
```
|
|
|
|
## Branching
|
|
|
|
Trunk-based: branch off `main`, keep the branch gate-green, and land the whole change back to `main`
|
|
in one reviewed step. Migrations are Alembic revisions under `backend/alembic/versions`; the API
|
|
applies them on startup, and the DB-lane rebuilds the schema via `alembic upgrade head`, so a broken
|
|
migration chain fails the tests.
|