build: cut over locked uv consumers (#672)

Build one locked application and MCP virtual environment in a pinned uv 0.12.3 multi-stage image.
Route Docker, local tooling, audits, tests, upgrade replay, pre-commit, Dependabot, benchmark tooling, and source-install documentation through that lock.
Remove both hand-maintained requirements files after every supported consumer is converted.

Includes aiohttp 3.14.1→3.14.3 security patch from #671.

Closes #660.

Author: Ryan Winkler

.claude/skills/run-floppy/SKILL.md

@@ -15,11 +15,11 @@ misleading. This skill exists mostly to save you from rediscovering those.
 ```bash
 cd <repo>/src
 redis-server --port 6379 --daemonize yes --save '' --dir /tmp
-python manage.py migrate --noinput
-python manage.py collectstatic --noinput --settings=local_serve   # see below
-bash .claude/skills/run-floppy/scripts/serve.sh start
-python .claude/skills/run-floppy/scripts/smoke.py --base http://localhost:8299
-bash .claude/skills/run-floppy/scripts/serve.sh stop
+uv run --project .. --no-sync python manage.py migrate --noinput
+uv run --project .. --no-sync python manage.py collectstatic --noinput --settings=local_serve   # see below
+uv run --project .. --no-sync bash ../.claude/skills/run-floppy/scripts/serve.sh start
+uv run --project .. --no-sync python ../.claude/skills/run-floppy/scripts/smoke.py --base http://localhost:8299
+uv run --project .. --no-sync bash ../.claude/skills/run-floppy/scripts/serve.sh stop
 ```
 
 `serve.sh` and `smoke.py` encode everything below. Read on when you need to
@@ -67,8 +67,13 @@ from config.settings import *  # noqa: F403
 IS_PROD = False
 ```
 
-Then `python manage.py collectstatic --noinput --settings=local_serve` and run
-gunicorn with `DJANGO_SETTINGS_MODULE=local_serve`.
+Then run the collectstatic command through uv:
+
+```bash
+uv run --project .. --no-sync python manage.py collectstatic --noinput --settings=local_serve
+```
+
+Start gunicorn through uv with `DJANGO_SETTINGS_MODULE=local_serve`.
 
 The stylesheet is `static/css/main.css` and it is committed pre-built — there is
 no npm build step, and `package.json` has no scripts. If you find yourself
@@ -104,7 +109,7 @@ tier that determines how many gunicorn workers and Celery workers run.
 `entrypoint.sh` probes it once and exports the result; reproduce that with:
 
 ```bash
-eval "$(python -c 'from config.runtime_profile import emit_env; emit_env()')"
+eval "$(uv run --project .. --no-sync python -c 'from config.runtime_profile import emit_env; emit_env()')"
 ```
 
 That sets `WEB_CONCURRENCY`, `GUNICORN_THREADS`, `FLOPPY_CELERY_QUEUES`,
@@ -123,7 +128,7 @@ hunting for one.
 Start a worker when you need that path:
 
 ```bash
-FLOPPY_PROCESS_ROLE=background celery --app config worker \
+FLOPPY_PROCESS_ROLE=background uv run --project .. --no-sync celery --app config worker \
   --queues "${FLOPPY_CELERY_QUEUES:-celery}" --loglevel INFO \
   --without-mingle --without-gossip &
 ```
@@ -157,7 +162,7 @@ Registration is off by default and the demo account only exists when
 `DEMO_ACCOUNT_ENABLED` is set. Make one directly:
 
 ```bash
-python -c "
+uv run --project .. --no-sync python -c "
 import os, django
 os.environ.setdefault('DJANGO_SETTINGS_MODULE','local_serve')
 django.setup()

.dockerignore

@@ -3,6 +3,7 @@ __pycache__
 .env
 .coverage*
 venv
+.venv/
 src/staticfiles
 src/db/db.sqlite3
 db.sqlite3-shm

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,13 +7,21 @@
 ## Validation
 - List commands run and outcomes.
 
+## Human Review
+- [ ] Pending human review.
+- [ ] Completed — reviewer/evidence: <!-- link or concise evidence -->
+
+## Gstack QA
+- [ ] Pending `/gstack-qa`.
+- [ ] Completed — report/outcome: <!-- link or concise outcome -->
+
 ## Migration Sync Gate (Required for `upstream` -> `latest` sync PRs)
 - [ ] Conflicts resolved with upstream files preserved and fork behavior merged intentionally.
 - [ ] Migration conflicts handled per policy (no rewrite of shared/released migrations).
-- [ ] `cd src && python manage.py makemigrations --merge` run for affected apps.
-- [ ] `cd src && python manage.py check_migration_hygiene --strict` passed.
+- [ ] `uv run --no-sync python src/manage.py makemigrations --merge` run for affected apps.
+- [ ] `uv run --no-sync python src/manage.py check_migration_hygiene --strict` passed.
 - [ ] `scripts/replay_upgrade_matrix.sh --from-tag <previous_release_tag> --to-ref latest --db sqlite,postgres --with-drift-scenarios` passed.
-- [ ] `coverage run src/manage.py test app users integrations lists events --parallel` passed.
+- [ ] `uv run --no-sync coverage run src/manage.py test app users integrations lists events --parallel` passed.
 
 ## Notes
 - Link relevant issues (for example: `Refs #101`).

.github/dependabot.yml

@@ -10,7 +10,7 @@ updates:
         patterns:
           - "*"
 
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
       interval: "daily"

.pre-commit-config.yaml

@@ -4,52 +4,52 @@ repos:
     hooks:
       - id: detect-secrets
         args: ["--baseline", ".secrets.baseline"]
-  - repo: https://github.com/pypa/pip-audit
-    rev: v2.10.1
-    hooks:
-      - id: pip-audit
-        args: ["-r", "requirements.txt"]
-        files: ^requirements(-dev)?\.txt$
   - repo: local
     hooks:
+      - id: pip-audit
+        name: pip-audit
+        entry: scripts/audit_dependencies.sh
+        language: system
+        pass_filenames: false
+        files: ^(pyproject\.toml|uv\.lock|mcp_server/pyproject\.toml)$
+      - id: uv-lock-check
+        name: uv-lock-check
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+        files: ^(pyproject\.toml|uv\.lock|mcp_server/pyproject\.toml)$
       - id: check-migrations
         name: check-migrations
-        entry: python src/manage.py makemigrations --check
+        entry: uv run --no-sync python src/manage.py makemigrations --check
         language: system
         pass_filenames: false
         always_run: true
       - id: django-upgrade
         name: django-upgrade
-        entry: django-upgrade
-        language: system
-        types: [python]
-      - id: pyflakes
-        name: pyflakes
-        entry: python -m pyflakes
+        entry: uv run --no-sync django-upgrade
         language: system
         types: [python]
-        require_serial: true
       - id: ruff
         name: ruff
-        entry: ruff check --fix
+        entry: uv run --no-sync ruff check --fix
         language: system
         types: [python]
         require_serial: true
       - id: ruff-format
         name: ruff-format
-        entry: ruff format
+        entry: uv run --no-sync ruff format
         language: system
         types: [python]
         require_serial: true
       - id: djlint-lint
         name: djlint-lint
-        entry: djlint --lint
+        entry: uv run --no-sync djlint --lint
         language: system
         types: [html]
         require_serial: true
       - id: djlint-reformat
         name: djlint-reformat
-        entry: djlint --reformat
+        entry: uv run --no-sync djlint --reformat
         language: system
         types: [html]
-        require_serial: true
+        require_serial: true

AGENTS.md

@@ -144,7 +144,7 @@ Also validate when:
 - the user asked for validation
 - the change affects multiple routes, components, or packages
 
-Prefer targeted tests first (`scripts/test.sh <dotted.label>`), then `ruff check src`, then the fast suite (`scripts/test.sh`) only when risk justifies it. See the Testing section.
+Prefer targeted tests first (`scripts/test.sh <dotted.label>`), then `uv run --no-sync ruff check src`, then the fast suite (`scripts/test.sh`) only when risk justifies it. See the Testing section.
 
 Prefer the cheapest useful check:
 
@@ -303,13 +303,13 @@ Models/migrations and divergent UI normally require manual adaptation. Provider
 - `docs/agents/migration_sync_playbook.md`: hard-gate flow for adapting accepted upstream migration outcomes to Floppy's current graph.
 
 ## Local Commands
-- Install dev dependencies: `python -m pip install -U -r requirements-dev.txt`
-- Run migrations: `cd src && python manage.py migrate`
-- Run the app: `cd src && python manage.py runserver`
+- Install locked dev dependencies: `uv sync --locked`
+- Run migrations: `uv run --no-sync python src/manage.py migrate`
+- Run the app: `uv run --no-sync python src/manage.py runserver`
 - Run Celery (two workers in one command, mirrors production):
   ```bash
-  PYTHONPATH=src celery -A config worker --queues interactive --hostname celery-interactive@%h --loglevel DEBUG &
-  PYTHONPATH=src celery -A config worker --queues celery --beat --scheduler django --hostname celery@%h --loglevel DEBUG
+  PYTHONPATH=src uv run --no-sync celery -A config worker --queues interactive --hostname celery-interactive@%h --loglevel DEBUG &
+  PYTHONPATH=src uv run --no-sync celery -A config worker --queues celery --beat --scheduler django --hostname celery@%h --loglevel DEBUG
   ```
   The interactive worker must be dedicated — **never add `celery` to its `--queues`** or long-running background tasks (Reload calendar, imports) will block user-triggered refreshes.
 - Run Tailwind: `cd src && tailwindcss -i ./static/css/input.css -o ./static/css/main.css --watch`
@@ -330,8 +330,8 @@ Run tests through `scripts/test.sh`, in this priority order:
 3. **Full suite (rarely needed locally):** `scripts/test.sh --full` — all tags, including slow benchmarks/Playwright and live-provider `network` tests. Takes 20+ minutes and produces huge output. Only run it when the user asks or the risk clearly justifies it. Application-impacting PRs run the CI application suite, which excludes `network` tests; documentation-only trigger filtering is owned by `.github/workflows/app-tests.yml`.
 
 Notes:
-- Quick confidence: `ruff check src`
-- Migration sync confidence: `cd src && python manage.py check_migration_hygiene --strict`
+- Quick confidence: `uv run --no-sync ruff check src`
+- Migration sync confidence: `uv run --no-sync python src/manage.py check_migration_hygiene --strict`
 - Migration upgrade replay: `scripts/replay_upgrade_matrix.sh --from-tag <previous_release_tag> --to-ref latest --db sqlite,postgres --with-drift-scenarios`
 - Tag vocabulary: `slow` and `network` are the exclusion tags used by the fast
   suite. `network` marks tests that call a live provider API: they need keys and
@@ -347,7 +347,7 @@ Notes:
 - Python target is 3.12 (see `Dockerfile` and CI).
 - Ruff config lives in `pyproject.toml` and excludes `migrations/`.
 - Djlint config is in `pyproject.toml`; Stylelint config is in `.stylelintrc`.
-- After model changes, keep migration files under `src/*/migrations/` and run `cd src && python manage.py migrate`.
+- After model changes, keep migration files under `src/*/migrations/` and run `uv run --no-sync python src/manage.py migrate`.
 - Media type changes follow `docs/agents/media_type_integration.md` (MediaTypes enum + `media_type_config` wiring).
 
 ## PR / Commit Expectations

CONTRIBUTING.md

@@ -95,9 +95,9 @@ Match validation to risk. See `AGENTS.md` for the full matrix. Short version:
 |---|---|
 | Copy, labels, static content | None required |
 | CSS / Tailwind spacing | Visual screenshot |
-| Template or UI logic | Screenshot + `ruff check src` |
-| Python behavior | `ruff check src` + targeted test |
-| Model or migration change | `python manage.py check_migration_hygiene --strict` + full test suite |
+| Template or UI logic | Screenshot + `uv run --no-sync ruff check src` |
+| Python behavior | `uv run --no-sync ruff check src` + targeted test |
+| Model or migration change | `uv run --no-sync python src/manage.py check_migration_hygiene --strict` + full test suite |
 | `upstream` → `latest` upstream sync | Full migration sync gate (see PR template) |
 
 Never skip validation for migrations, models, auth, permissions, webhooks, Celery tasks, or cache behavior.
@@ -107,6 +107,7 @@ Never skip validation for migrations, models, auth, permissions, webhooks, Celer
 ## Style
 
 - Python 3.12. Ruff configured in `pyproject.toml` (88-char line limit, migrations excluded).
+- Python dependencies are declared in `pyproject.toml` and locked in `uv.lock`; use uv 0.12.3 and `uv sync --locked` rather than maintaining requirements files.
 - Templates: djlint config in `pyproject.toml`. CSS: Stylelint config in `.stylelintrc`.
 - Tailwind output is committed at `src/static/css/main.css`. Run `npx @tailwindcss/cli -i ./src/static/css/input.css -o ./src/static/css/main.css` after any template or class changes — this uses the version pinned in `package.json`, so it always matches the committed output. Do not use a bare/global `tailwindcss` binary or unpinned `npx`; a version mismatch regenerates the file with a different (larger) utility set and produces spurious diffs.
 - Commit messages: short imperative title, optional 1–3 bullet body, then issue lines.

Dockerfile

@@ -1,4 +1,7 @@
-FROM python:3.12-alpine3.21 AS repo_meta
+ARG PYTHON_VERSION=3.12
+ARG ALPINE_VERSION=3.21
+
+FROM python:${PYTHON_VERSION}-alpine${ALPINE_VERSION} AS repo_meta
 
 WORKDIR /repo
 COPY . .
@@ -39,10 +42,27 @@ if config_path.exists():
 Path("/repo_owner").write_text(owner)
 PY
 
-FROM python:3.12-alpine3.21
+FROM python:${PYTHON_VERSION}-alpine${ALPINE_VERSION} AS builder
+
+COPY --from=ghcr.io/astral-sh/uv:0.12.3 /uv /uvx /bin/
+ENV UV_LINK_MODE=copy
+
+WORKDIR /floppy
+
+COPY ./pyproject.toml ./uv.lock ./
+COPY ./mcp_server/pyproject.toml ./mcp_server/pyproject.toml
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-default-groups --no-install-workspace
+
+COPY ./mcp_server ./mcp_server
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-default-groups --no-editable
+
+FROM python:${PYTHON_VERSION}-alpine${ALPINE_VERSION}
 
 # https://stackoverflow.com/questions/58701233/docker-logs-erroneously-appears-empty-until-container-stops
 ENV PYTHONUNBUFFERED=1
+ENV PATH="/floppy/.venv/bin:$PATH"
 
 # Define build argument with default value
 ARG VERSION=dev
@@ -63,7 +83,6 @@ ENV FLOPPY_CELERY_QUEUES=celery
 ENV FLOPPY_START_INTERACTIVE_WORKER=true
 ENV FLOPPY_START_DISCOVER_WORKER=true
 
-COPY ./requirements.txt /requirements.txt
 COPY ./entrypoint.sh /entrypoint.sh
 COPY ./supervisord.conf /etc/supervisord.conf
 COPY ./nginx.conf /etc/nginx/nginx.conf
@@ -78,10 +97,6 @@ WORKDIR /floppy
 RUN ln -s /floppy /yamtrack
 
 RUN apk add --no-cache nginx shadow \
-    && pip install --no-cache-dir -r /requirements.txt \
-    && pip install --no-cache-dir supervisor==4.3.0 \
-    && rm -rf /root/.cache /tmp/* \
-    && find /usr/local -type d -name __pycache__ -exec rm -rf {} + \
     && chmod +x /entrypoint.sh \
     # create user abc for later PUID/PGID mapping
     && useradd -U -M -s /bin/sh abc \
@@ -90,6 +105,7 @@ RUN apk add --no-cache nginx shadow \
     && mkdir -p /var/lib/nginx/body
 
 COPY --from=repo_meta /repo_owner /etc/floppy/fork_owner
+COPY --from=builder /floppy/.venv /floppy/.venv
 
 # Django app
 COPY src ./
@@ -99,8 +115,6 @@ RUN SECRET=build-time-placeholder python manage.py collectstatic --noinput
 # version shipped with this image, instead of a user's local checkout that
 # can silently drift from the app version.
 COPY mcp_server ./mcp_server
-RUN pip install --no-cache-dir ./mcp_server \
-    && rm -rf /root/.cache
 
 EXPOSE 8000
 

README.md

@@ -389,7 +389,7 @@ host-derived worker settings and database/Redis fork-safety hooks are active:
 
 ```bash
 cd /path/to/floppy/src
-gunicorn --config python:config.gunicorn config.wsgi:application
+uv run --no-sync gunicorn --config python:config.gunicorn config.wsgi:application
 ```
 
 Do not start the service with bare `gunicorn config.wsgi:application`; that
@@ -474,31 +474,37 @@ For contributing or customizing locally:
 git clone https://github.com/dannyvfilms/Floppy.git
 cd Floppy
 docker run -d --name redis -p 6379:6379 --restart unless-stopped redis:8-alpine
-python -m pip install -U -r requirements-dev.txt
+uv sync --locked
 ```
 
 Create a `.env` with at least `SECRET`, `DEBUG=True`, and whichever API keys you need (same names as the Docker list above), then:
 
 ```bash
-cd src
-python manage.py migrate
-python manage.py createsuperuser
-python manage.py runserver
+uv run --no-sync python src/manage.py migrate
+uv run --no-sync python src/manage.py createsuperuser
+uv run --no-sync python src/manage.py runserver
 ```
 
 Celery and Tailwind run in separate terminals:
 
 ```bash
-celery -A config worker --queues interactive --hostname celery-interactive@%h --loglevel DEBUG
-celery -A config worker --queues celery --beat --scheduler django --hostname celery@%h --loglevel DEBUG
+PYTHONPATH=src uv run --no-sync celery -A config worker --queues interactive --hostname celery-interactive@%h --loglevel DEBUG
+PYTHONPATH=src uv run --no-sync celery -A config worker --queues celery --beat --scheduler django --hostname celery@%h --loglevel DEBUG
 ```
 
 ```bash
-npx @tailwindcss/cli -i ./static/css/input.css -o ./static/css/main.css --watch
+npx @tailwindcss/cli -i ./src/static/css/input.css -o ./src/static/css/main.css --watch
 ```
 
 Visit `http://localhost:8000`. A `demo` / `demodemo` account is provisioned after migrations; set `DEMO_ACCOUNT_ENABLED=False` to disable it. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
 
+`pyproject.toml` and `uv.lock` are the dependency source of truth for the app
+and bundled MCP workspace. Use uv 0.12.3 and keep the lockfile in sync; the
+removed requirements files are not maintained in parallel. The MCP package's
+`setuptools>=68` isolated build-backend range is the only build-time resolver
+exception to the runtime lock and is intentionally not pinned as an application
+dependency.
+
 ## Support the project
 
 - Star the repository if you want to help more people find Floppy.