Dev Loop

Every section below is rendered from the application repository's CONTRIBUTING.md when this site is built. For the recipes as the task runner defines them, read the justfile itself, or run just --list in your clone.

Prerequisites

• mise — mise.jdx.dev (curl https://mise.run | sh)
• ffmpeg — brew install ffmpeg (macOS) or apt install ffmpeg

All other tools (Go, Node, sqlc, golangci-lint) are pinned in .mise.toml and installed by mise install.

First-time setup

git clone --recurse-submodules https://gitlab.com/yotoshelf/yotoshelf.git
cd yotoshelf
mise install    # installs exact Go, Node, sqlc, golangci-lint versions
just dev        # starts backend + frontend, creates admin user

Note: --recurse-submodules is required — the frontend consumes frontend/design as a git submodule. If you already cloned without it, run git submodule update --init.

Login at http://localhost:4300 with admin@localhost / admin.

Warning: The default credentials above are dev-only and are seeded automatically by just dev. Never use them in production — use create-admin with a strong password instead.

The one command

After every change, run:

just check

It runs the same commands as the CI jobs check:go, check:file-size, check:frontend, check:frontend-types, check:i18n and check:generated. While iterating, just check-fast runs the same gates without the network or the race detector; run the full just check before pushing.

Four CI jobs have no local equivalent and can only fail in the pipeline: check:secrets, check:hygiene, build:container and e2e:playwright. So a green just check means those four are the only jobs still unproven — not that the pipeline is guaranteed green.

Recipes

Recipe	What it does
just dev	Start backend + frontend with hot reload. Safe by default: no secrets decrypted, Yoto linking disabled.
just dev-prod	Production-mode dev (single embedded binary). Same safe-by-default posture as just dev.
just stage-db	Ensure deps + dev DB + admin user. No secrets decrypted, no AI providers seeded.
just dev-live	Like dev, but decrypts secrets/dev.enc.yaml via sops and injects real Yoto OAuth creds + seeds real LLM provider keys. Requires sops + a valid age key.
just dev-prod-live	Like dev-prod, with the same live-secrets behavior as dev-live.
just stage-db-live	Like stage-db, but also seeds real LLM provider keys from secrets/dev.enc.yaml (seed-llm).
just dev-full	Like dev-live, but also injects LLM API keys (OPENAI_API_KEY, etc.) directly into the server process env, not just seeded providers.
just check	Every CI gate that runs on a laptop: lint, file size, i18n, licenses, govulncheck, Go tests, frontend build, raw-fetch() gate, astro check, generated-code drift, binary build
just check-go	Go-only gates (lint, tests, govulncheck, file-size)
just check-frontend	Frontend gates (npm ci + build, i18n, raw-fetch() gate, astro check)
just test	Go unit tests + frontend build
just lint	golangci-lint + file size + i18n + licenses + raw-fetch() gate
just lint-frontend	astro check — typechecks .astro, .svelte and .ts
just generate	sqlc + openapi-typescript (updates types.ts)
just build	Production binary (requires frontend build first — the Go binary embeds frontend/dist/)
just e2e	Playwright E2E tests (requires local binary)
just smoke	Documented first-run: build, create-admin, serve, log in, clean shutdown. Throwaway DB.
just smoke-backup	Backup and restore roundtrip honours YOTOSHELF_DB_PATH with no data loss.
just smoke-publish	Live. Publishes one throwaway card with three unseen tracks to a real Yoto account and requires attempts == 1. Refuses without a terminal, without YOTOSHELF_LIVE_PUBLISH=1, or in CI. Run by hand before a tag; the recipe’s comment lists the environment it needs.
just release-check	Pre-tag gate: runs check, smoke and smoke-backup and reports readiness.

Warning: the -live variants (and dev-full) decrypt secrets/dev.enc.yaml via sops and put real Yoto OAuth + LLM provider credentials into your environment or dev DB. Only run them if you have your own age key and mean to use live credentials — the plain dev / dev-prod / stage-db recipes never touch that file.

just dev and just dev-live seed a dev admin (admin@localhost / admin). Those credentials are dev-only and must never be used in production.

Seed fixtures

To populate a running instance with test content, use the sibling fixtures repo:

python3 fixtures/seed.py <url> admin@localhost admin

The seed script requires the dev-permissive origin (i.e. YOTOSHELF_PUBLIC_URL must not be set, or must match the URL you pass). Default: http://localhost:4300.