// Complete reference for all make targets in the Oscilla project. Use when: looking up the right make command for any task — setup, testing, linting, formatting, database, frontend, packaging, or cleanup.
| name | makefile |
| description | Complete reference for all make targets in the Oscilla project. Use when: looking up the right make command for any task — setup, testing, linting, formatting, database, frontend, packaging, or cleanup. |
All developer tasks are exposed as make targets. Run from the project root.
| Target | What it does |
|---|---|
make install | Install Python + frontend deps, create .venv (first-time setup) |
make sync | Sync Python deps with uv.lock (after pulling changes) |
make pre-commit | Install pre-commit hooks |
make lock | Upgrade and relock all dependencies |
make lock-check | Verify lock file is up to date without changing it |
| Target | What it does |
|---|---|
make tests | Run everything: pytest, ruff, mypy, prettier, TOML lint, paracelsus, migration check, content validation, frontend check + vitest + Playwright lint |
make pytest | Run pytest with coverage report |
make pytest_loud | Run pytest with DEBUG log output enabled |
make validate | Validate all content packages (YAML manifests) |
These check only — they do not auto-fix.
| Target | What it checks |
|---|---|
make ruff_check | Ruff linter |
make black_check | Ruff formatter (black style) |
make mypy_check | Type checking (mypy) |
make prettier_check | Markdown, JSON, YAML, TOML formatting (prettier) |
make tomlsort_check | TOML file formatting (tombi) |
make paracelsus_check | Database schema docs are up to date |
make check_ungenerated_migrations | No pending Alembic migration changes |
| Target | What it fixes |
|---|---|
make chores | Run all auto-fixes: ruff, format, prettier, TOML, frontend formatting, schema docs |
make ruff_fixes | Auto-fix ruff lint issues |
make black_fixes | Auto-format Python code (black style via ruff) |
make prettier_fixes | Auto-format markdown/JSON/YAML/TOML (root + frontend) |
make tomlsort_fixes | Auto-format TOML files (tombi) |
make frontend_format_fix | Auto-format frontend source files (prettier) |
Typical workflow before committing: make chores && make tests
| Target | What it does |
|---|---|
make create_migration MESSAGE="description" | Generate a new Alembic migration from model changes |
make check_ungenerated_migrations | Fail if there are model changes without a migration |
make run_migrations | Apply all pending migrations (alembic upgrade head) |
make document_schema | Regenerate docs/dev/database.md from current models |
make paracelsus_check | Verify schema docs are current (read-only check) |
make reset_db | Wipe local SQLite test DB and reapply all migrations |
make clear_db | Delete test.db* files only (no migrations) |
create_migration requires a MESSAGE argument:
make create_migration MESSAGE="add email_verified column to users"
| Target | What it does |
|---|---|
make frontend_install | Install npm dependencies (npm ci) |
make frontend_build | Build production assets |
make frontend_dev | Start Vite dev server (hot reload) |
make frontend_check | Run svelte-check type checking |
make frontend_test | Run Vitest unit tests |
make frontend_format_fix | Auto-format src/ with prettier |
make frontend_format_check | Check src/ formatting (no writes) |
| Target | What it does |
|---|---|
make frontend_playwright_lint | Parse all test files for config errors (no server needed) |
make frontend_e2e | Run E2E tests (spins up full stack automatically) |
make frontend_a11y | Run accessibility tests (requires built frontend) |
make frontend_playwright_all | A11y + E2E across Chromium, Firefox, and WebKit |
Single-browser variants: append _chromium, _firefox, or _webkit (e.g., make frontend_e2e_chromium).
frontend_e2e automatically:
db, redis, and mailhog via Docker Compose| Target | What it does |
|---|---|
make build | Build Python package distribution (sdist + wheel) |
make clean | Remove *.log, saves databases, stray *.py scripts |
make clean_logs | Remove *.log files |
make clean_saves | Remove saves.db* files |
| I want to… | Run |
|---|---|
| Set up for the first time | make install |
| Run all tests before a PR | make tests |
| Fix all formatting issues | make chores |
| Check types only | make mypy_check |
| Add a database migration | make create_migration MESSAGE="..." |
| Regenerate DB docs after model changes | make document_schema |
| Run only Python tests with verbose output | make pytest_loud |
| Run only frontend unit tests | make frontend_test |
| Run E2E tests | make frontend_e2e |
| Update dependencies | make lock && make sync |
Write or modify Oscilla game content YAML manifests for any game package. Use when: creating a new game package, writing adventures, enemies, items, quests, regions, locations, skills, buffs, archetypes, recipes, loot tables, or conditions; designing progression systems; configuring game.yaml or character_config.yaml; authoring template expressions; setting up cooldowns or passive effects; validating content with the CLI; or any task that touches files under a content/ game package directory.
Work with the Oscilla Docker Compose development environment. Use when: starting or stopping services, inspecting logs, opening a shell in a container, resetting the database, or understanding the service topology.
Create or modify FastAPI routes in the Oscilla codebase. Use when: adding new API endpoints, creating Pydantic request/response models, registering routers, designing REST APIs, or following route conventions for this project.
Work on the Oscilla frontend (SvelteKit/Vite). Use when: writing or modifying any Svelte components, routes, stores, styles, or frontend tests; adding new UI features or pages; fixing frontend bugs; running frontend tests or type checks; managing npm dependencies; working on accessibility or usability; building production assets; or any task that touches files under frontend/.
Use the Oscilla CLI to assist content authors writing YAML manifests. Use when: setting up JSON schema validation for YAML manifests, running validate or oscilla content test, inspecting manifest content with list/show, tracing adventure paths, graphing world structure, scaffolding new manifests with oscilla content create, debugging content errors, checking cross-references. Knows all oscilla content subcommands: schema, test, list, show, graph, trace, create. Also covers oscilla validate.
Add or modify application configuration settings in Oscilla. Use when: adding new environment variables, adding new settings fields, understanding settings conventions, working with secrets, or configuring optional vs required settings.