Dev Loop

Prerequisites

• mise — mise.jdx.dev. Installs and pins Go, Node, sqlc, and golangci-lint from .mise.toml. Install with curl https://mise.run | sh.
• ffmpeg — brew install ffmpeg (macOS) or apt install ffmpeg. Required for audio transcoding.

Initial setup

git clone --recurse-submodules https://gitlab.com/yotoshelf/yotoshelf.git
cd yotoshelf
mise install    # installs exact tool versions from .mise.toml
just dev        # starts backend :8080 + frontend :4300

Open http://localhost:4300 and log in with admin@localhost / admin. The dev environment auto-creates the admin user and seeds AI provider config if secrets/dev.enc.yaml is present and decryptable.

The one command

After every change, run:

just check

This runs every local-runnable CI gate: lint, tests, build, govulncheck, npm audit, and the i18n check. If it passes locally, it passes in CI.

just recipe reference

Recipe	What it does
just dev	Start backend + Vite frontend with hot reload
just dev-fresh	Wipe dev DB + library, then start
just check	All CI gates (lint + tests + build + govulncheck + npm audit + i18n)
just check-go	Go-only gates
just check-frontend	Frontend gates
just test	Go unit tests + frontend build
just lint	golangci-lint + file size check + i18n check
just generate	sqlc + openapi-typescript (updates types.ts)
just build	Production binary at bin/yotoshelf
just e2e	Playwright E2E tests (builds the binary first, runs on port 8095)

Generating types after schema changes

If you change any SQL query or huma operation, run just generate to keep the generated files in sync:

just generate   # sqlc → internal/db/gen/ + openapi-typescript → frontend/src/lib/api/types.ts

Commit the updated generated files alongside your change. CI checks for drift — types.ts that differs from the committed version will fail the pipeline.

Seed fixtures

To populate a running dev instance with test cards and tracks, use the sibling fixtures repo:

python3 fixtures/seed.py http://localhost:4300 admin@localhost admin

The seed script creates sample content so the UI is not empty during development. It requires the dev URL to match (default: http://localhost:4321; pass the actual dev URL as the first argument).

Playwright E2E tests

The just e2e recipe builds the production binary, starts a throwaway server on port 8095, and runs the Playwright specs in e2e/. It does not touch the dev database or port 8090.

just e2e              # full suite
just e2e --headed     # watch the browser
just e2e -g "login"   # run a specific test

E2E tests require ffmpeg to be installed locally. The e2e/ directory has its own node_modules installed automatically on first run.