quadletman: Instructions file for Claude Code

CLAUDE.md — quadletman

What This Is

quadletman is a FastAPI web UI (HTMX + Tailwind) for managing Podman Quadlet container services on a Linux host. It runs as a dedicated quadletman system user via a systemd service and uses PAM-based HTTP Basic Auth restricted to sudo/wheel users. Admin operations use the authenticated user's sudo credentials for privilege escalation. See README.md for full user-facing documentation.

Dev Commands

uv sync --group dev               # install all deps including dev tools
./scripts/run_dev.sh              # run as qm-dev user with dev-isolated data
uv run ruff check quadletman/     # lint
uv run ruff format quadletman/    # format
uv run pytest                     # run test suite (must NOT run as root)
uv run pre-commit run --all-files # run all checks (fail_fast: lint → format → tests)
TAILWINDCSS_VERSION=v4.2.2 uv run tailwindcss -i quadletman/static/src/app.css \
  -o quadletman/static/src/tailwind.css --minify
                                  # rebuild Tailwind CSS — re-run after adding new utility
                                  # classes to any template; commit the output file
                                  # TAILWINDCSS_VERSION must match ci.yml and .pre-commit-config.yaml
uv run pybabel extract -F babel.cfg -o quadletman/locale/quadletman.pot .
                                  # re-extract translatable strings after adding/changing strings
uv run pybabel update -i quadletman/locale/quadletman.pot -d quadletman/locale -D quadletman
                                  # update existing .po files with new/changed strings
uv run pybabel compile -d quadletman/locale -D quadletman
                                  # compile .po → .mo for runtime use (run after updating)
                                  # See docs/localization.md for the full localization workflow
npm test                          # run JavaScript unit tests (Vitest, Node 20+ required)

Pre-commit hooks run automatically on git commit and auto-fix what they can. The pipeline uses fail_fast: true so a ruff lint failure stops the pipeline before pytest runs. Pytest only triggers when files under quadletman/ or tests/ are staged — docs-only or config-only commits skip the test suite. Never use --no-verify to skip hooks.