left4me/docs/superpowers/plans/2026-05-15-uv-workspace-execution.md

Plan — collapse left4me venv chain into uv workspace + uv sync

Status: executed (left4me side). ckn-bw side queued — see ~/Projekte/ckn-bw/bundles/left4me/ and the matching section below.

Notable deviations from the original handoff (docs/superpowers/specs/2026-05-15-handoff-uv-workspace.md):

• Handoff assumed pkg_apt: uv works on Debian Trixie. It does not — uv is in experimental/sid only. Replaced with a left4me_install_uv action that downloads a pinned 0.11.8 tarball from astral-sh/uv releases, SHA256-verifies, installs to /usr/local/bin/.
• Handoff assumed the existing layout (l4d2host/pyproject.toml with package-dir = ".") was workspace-compatible. It was not — setuptools writes egg-info/ to source during any build, which fails on the root-owned /opt/left4me/src tree. Required layout restructure to l4d2host/l4d2host/ (package source nested) plus a switch from setuptools to hatchling.
• git is not installed on the prod host (bw drives git from the control machine). Verification check #1 uses find for build artifacts instead of git status.

Context

The production deploy of left4me to ovh.left4me currently uses a 5-action chain in ckn-bw/bundles/left4me/items.py that builds out a Python venv under /var/lib/left4me/.venv by chaining python3 -m venv → pip upgrade → pip install (with an 8-line tempdir-copy dance because the source at /opt/left4me/src is root-owned and setuptools wants to write .egg-info/ into it) → alembic upgrade → seed_overlays. The chain has three problems:

1. Non-deterministic prod deploys. pip install resolves whatever is latest at apply time. A transitive CVE-relevant bump between two bw apply runs is invisible until something breaks.
2. Cognitive cost. The tempdir-copy in left4me_pip_install is the single longest, gnarliest action in the bundle.
3. Implicit cross-package dep. l4d2web imports from l4d2host.paths in 5 files but doesn't declare the dependency — today's setup works only because both get pip install -e'd side-by-side.

This plan migrates the repo to a uv workspace with a committed uv.lock, replacing the 5-action chain with left4me_install_uv (download + SHA256 verify, idempotent — only re-runs on version change) plus left4me_uv_sync. On the steady-state path (uv already pinned at 0.11.8), only uv_sync fires per deploy. Both sides of the change (left4me repo and the ckn-bw left4me bundle) ship together. The plan executes the migration sequence already documented in /Users/mwiegand/Projekte/left4me/docs/superpowers/specs/2026-05-15-handoff-uv-workspace.md — treat that handoff as the design document. This plan adds the empirically-verified ground truth, resolves the small open questions, and encodes the executable sequence.

Source of truth

• Design: docs/superpowers/specs/2026-05-15-handoff-uv-workspace.md (in the left4me repo) — read this first; do not duplicate its content here.
• Sibling context (don't dive in): docs/superpowers/specs/2026-05-15-deployment-responsibility-design.md (just-shipped; left the venv chain alone), docs/superpowers/specs/2026-05-15-runtime-state-relocation-design.md (made /opt/left4me/src root-owned, which is why the current tempdir-copy dance exists).

Resolved questions (from planning)

• Branch flow: direct-to-master on both sides. (Matches left4me's recent workflow, e.g. b13d164, 55b0138. ckn-bw side committed but NOT pushed — operator pushes manually.)
• Python version alignment: align all three pyprojects (root + both members) to requires-python = ">=3.13". Matches .envrc and the production host. Removes the workspace-vs-member skew.
• Spike test scope: extend beyond the handoff to also dry-run a uv sync --frozen shape against a root-owned source — the production command path is sync, not build, and they're different code paths.
• Scope handoff at git push: agent's deliverable is two ready-to-deploy commits (left4me pushed; ckn-bw committed but unpushed). The user runs bw apply ovh.left4me, the post-apply restart, and the 6-check verification matrix themselves. (Per session memory: feedback_left4me_deploy_workflow — supersedes the original prompt's ask to drive apply + verify end-to-end.) The spike test remains agent work — it's information gathering, and the one-shot direct install fits the "one-shot via direct command" rule from the same memory.
• uv install vector: direct GitHub tarball download + SHA256 verify against the official .sha256 sibling, install to /usr/local/bin/. The handoff doc's pkg_apt: uv assumption was wrong — uv is not in Debian Trixie's apt archive (in experimental/sid only). Astral's canonical methods are curl-pipe-sh and direct tarball; we chose tarball for auditability and pattern-match with the existing left4me_install_steamcmd action. Pin to uv 0.11.8 to match the local brew-installed version, eliminating the lockfile-format-skew risk between dev and prod.

Ground-truth from exploration

• Cross-package imports confirmed: 5 files in l4d2web/ import from l4d2host.paths:
  • l4d2web/routes/overlay_routes.py
  • l4d2web/services/overlay_creation.py
  • l4d2web/services/overlay_builders.py
  • l4d2web/services/overlay_files.py
  • l4d2web/services/workshop_paths.py
• Layout compatibility: both members use [tool.setuptools.package-dir] {name} = "." (pyproject lives inside the package directory). uv workspace members = ["l4d2host", "l4d2web"] handles this fine — uv uses the pyproject as the project root regardless of the package-dir mapping.
• .gitignore already covers *.egg-info/, .venv/, __pycache__/, etc. No .gitignore changes needed.
• No pytest.ini / [tool.pytest.ini_options] exists — pytest defaults work; uv run pytest from repo root will discover tests in l4d2host/tests/ and l4d2web/tests/.
• Bundle action conventions (from ckn-bw/bundles/left4me/items.py and neighbors): every action sets cascade_skip: False explicitly. Action keys in use: command, triggered, cascade_skip, unless, needs, triggers, comment.
• Additional git_deploy consumer: left4me_chmod_scripts at items.py:324 also needs: 'git_deploy:/opt/left4me/src'. Untouched by this refactor, but listed here so it's not missed during review.
• Bundle README §"deploy-flow": lines 84–90 of bundles/left4me/README.md document the pip_install tempdir dance. This is the prose to rewrite (not vague — those exact lines).
• apt.packages declaration: metadata.py:29–49. Currently lists python3, python3-venv, python3-pip, python3-dev, plus i386 multiarch entries.
• uv NOT in Debian Trixie apt archive (verified via apt-cache search "^uv$" and apt-cache policy uv on the live host — both return nothing for the actual uv package). Handoff doc's assumption was wrong on this point.
• git is NOT installed on the production host (verified via command -v git on prod returning empty; /usr/bin/git doesn't exist). The bw git_deploy item operates from the control machine (dev laptop), pushing files to prod via SSH — prod itself needs no git. Implication: the handoff's verification check #1 (sudo git -C /opt/left4me/src status --porcelain) cannot be used. Replace with find /opt/left4me/src \( -name '*.egg-info' -o -name build -o -name dist \) -print.
• ckn-bw is currently EVEN with origin/master (verified via git status -sb showing ## master...origin/master with empty log). The original prompt's "7 commits ahead" was stale — the operator has since pushed. After our ckn-bw commit lands locally, the repo will be 1 commit ahead (not 8).
• Prod arch: x86_64 / amd64. Prod curl: 8.14.1 at /usr/bin/curl. Prod tar: GNU tar 1.35. Prod install: GNU coreutils 9.7. /usr/local/bin exists, root-owned, currently contains only the downtime binary.
• Current prod venv state: /var/lib/left4me/.venv/ exists, owned by left4me:left4me, contains python3.13, pip, alembic, flask, gunicorn, l4d2ctl. pip show l4d2host / pip show l4d2web both report version 0.1.0. So uv will be adopting a venv that already has working installs of both members + their deps.
• Local dev environment: uv 0.11.8 (brew), direnv 2.37.1 (supports use uv), python 3.13.13. No .venv exists locally yet — clean slate.

Critical files

left4me repo

• NEW /Users/mwiegand/Projekte/left4me/pyproject.toml — workspace root
• NEW /Users/mwiegand/Projekte/left4me/uv.lock — generated via uv lock
• l4d2host/pyproject.toml:10 — bump requires-python to >=3.13
• l4d2web/pyproject.toml:10–18 — bump requires-python, add "l4d2host" to dependencies, add [tool.uv.sources] l4d2host = { workspace = true }
• .envrc — replace layout python python3.13 with use uv (with fallback if direnv stdlib is too old)
• README.md, AGENTS.md, l4d2web/README.md — update install instructions

ckn-bw repo (~/Projekte/ckn-bw/)

• bundles/left4me/metadata.py:29–49 — ensure 'curl': {} is in apt.packages (required by the new install action; verify it's not already inherited from a base bundle). Drop 'python3-pip' (uv replaces pip; bundle has no other consumer). Drop 'python3-venv' (the chain no longer uses python3 -m venv; uv creates its own venv via UV_PROJECT_ENVIRONMENT). Keep 'python3', 'python3-dev', and the i386 multiarch entries. Do NOT add 'uv': {} — uv is not in Trixie's apt archive.
• bundles/left4me/items.py:285–305 — update git_deploy:/opt/left4me/src triggers: replace action:left4me_pip_install with action:left4me_uv_sync
• bundles/left4me/items.py:328–340 — DELETE left4me_create_venv
• bundles/left4me/items.py:342–352 — DELETE left4me_pip_upgrade
• bundles/left4me/items.py:354–382 — DELETE left4me_pip_install (replaced by left4me_uv_sync below)
• bundles/left4me/items.py:384–407 — left4me_alembic_upgrade: update needs: (or triggered_by: equivalent) to point at action:left4me_uv_sync instead of action:left4me_pip_install
• bundles/left4me/items.py — ADD two new actions:
  • left4me_install_uv: download pinned 0.11.8 tarball from github.com/astral-sh/uv/releases/, SHA256-verify, install to /usr/local/bin/. Idempotent via unless: '/usr/local/bin/uv --version | grep -qx "uv 0.11.8"'. needs: ['pkg_apt:curl'], triggers: ['action:left4me_uv_sync']. (Body matches the approved preview, with unless: refined to grep -qx for BRE portability.)
  • left4me_uv_sync: sudo -u left4me env UV_PROJECT_ENVIRONMENT=/var/lib/left4me/.venv /usr/local/bin/uv sync --frozen --project /opt/left4me/src. triggered: True, cascade_skip: False, needs: includes 'git_deploy:/opt/left4me/src', 'action:left4me_install_uv', 'directory:/var/lib/left4me', 'user:left4me'. triggers: ['action:left4me_alembic_upgrade'].
• bundles/left4me/README.md:84–90 — rewrite the deploy-flow description to mention the install_uv + uv_sync chain instead of the tempdir-dance

Execution steps

Step 0 — Spike test (extended) — DO FIRST

Verify the architectural assumption empirically on the live host. Uses the SAME install vector the production action will use (direct tarball + SHA256 verify), so the spike doubles as a smoke test for the install action itself.

# A. Install pinned uv on prod (one-shot via direct command; matches
#    what the future bw action will do).
ssh ckn@left4.me '
  set -e
  tmpdir=$(mktemp -d); trap "rm -rf $tmpdir" EXIT
  base=https://github.com/astral-sh/uv/releases/download/0.11.8
  tar=uv-x86_64-unknown-linux-gnu.tar.gz
  curl -fsSL -o $tmpdir/$tar       $base/$tar
  curl -fsSL -o $tmpdir/$tar.sha256 $base/$tar.sha256
  (cd $tmpdir && sha256sum -c $tar.sha256)
  tar -xzf $tmpdir/$tar -C $tmpdir --strip-components=1
  sudo install -m 0755 $tmpdir/uv  /usr/local/bin/uv
  sudo install -m 0755 $tmpdir/uvx /usr/local/bin/uvx
  /usr/local/bin/uv --version
'

# B. uv build against root-owned source: source must stay clean.
ssh ckn@left4.me '
  sudo -u left4me sh -c "
    wheels=\$(mktemp -d)
    /usr/local/bin/uv build --wheel --sdist /opt/left4me/src/l4d2host --out-dir \$wheels
    ls \$wheels
  "
'
# Cleanliness probe — git not on prod, so use find for build artifacts.
# Expected: only-existing egg-info dirs (the ones already on disk from
# the current pip install -e flow); NO NEW artifacts from this run.
# Capture a baseline BEFORE the build, compare AFTER.
ssh ckn@left4.me 'sudo find /opt/left4me/src \( -name "*.egg-info" -o -name build -o -name dist -o -name "__pycache__" \) -printf "%T@ %p\n" | sort'

# C. Extended sync-shape check — dry-run `uv sync --frozen` against a
#    root-owned workspace mock in /tmp. Verify the project root stays
#    clean (no .python-version written, no transient files left over).
#    This validates that `uv sync` (not just `uv build`) is safe against
#    a read-only project tree, which is the actual production code path.

Decision gate:

• Source stays clean across B and C → proceed with full plan.
• New *.egg-info / build/ / dist/ directories appear in /opt/left4me/src after uv build → fall back to Medium scope (handoff §"Empirical spike" → fallback). Update the handoff doc to record the fallback decision and re-plan.
• uv sync writes into the project root during step C → also fall back to Medium scope. Same handoff update.

Step 1 — left4me workspace setup (local)

1. Write /Users/mwiegand/Projekte/left4me/pyproject.toml (workspace root) — see handoff §"What changes — left4me side / New: pyproject.toml"
2. Bump l4d2host/pyproject.toml:10 to requires-python = ">=3.13"
3. Update l4d2web/pyproject.toml: bump requires-python, add "l4d2host" to dependencies, append [tool.uv.sources] block
4. uv lock at the repo root → produces uv.lock
5. uv sync → creates .venv/, installs both members editable + pytest
6. uv run pytest → all green
7. Update .envrc: replace layout python python3.13 with use uv (fallback to uv sync >/dev/null && source .venv/bin/activate if the dev's direnv version doesn't ship use uv)
8. Update README.md, AGENTS.md, l4d2web/README.md: replace the pip install -e ... invocation with uv sync and add the one-time prereq line about installing uv. Mention macOS (brew install uv) and Linux (curl-pipe-sh from astral.sh) — do NOT suggest apt install uv, as it's not in Debian's apt archive yet (only experimental/sid).

Step 2 — left4me commit + push

Single commit using the suggested message from the handoff (§"Commit messages — left4me side"). Push to origin (gitlab on sublimity.de — confirmed safe-publish-exempt per memory). The commit makes the workspace and lockfile available to ckn-bw's git_deploy.

Step 3 — ckn-bw bundle refactor

1. Edit bundles/left4me/metadata.py:29–49:
   • Ensure 'curl': {} is in apt.packages (verify it's not already inherited from a base bundle; if not, add it explicitly).
   • Drop 'python3-pip' (uv replaces pip; bundle has no other consumer — grep the bundle to confirm).
   • Drop 'python3-venv' (chain no longer uses python3 -m venv).
   • Keep 'python3', 'python3-dev', and the i386 multiarch entries.
   • Do NOT add 'uv': {} — not in Trixie's apt.
2. Edit bundles/left4me/items.py:
   • Delete left4me_create_venv, left4me_pip_upgrade, left4me_pip_install blocks (lines 328–382 inclusive).
   • Add left4me_install_uv action: downloads pinned uv 0.11.8 tarball from github.com/astral-sh/uv/releases/, SHA256-verifies against the official .sha256 sibling, installs to /usr/local/bin/{uv,uvx}. Idempotent via unless: '/usr/local/bin/uv --version 2>/dev/null | grep -qx "uv 0.11.8"'. needs: ['pkg_apt:curl'], triggers: ['action:left4me_uv_sync'], triggered: False, cascade_skip: False.
   • Add left4me_uv_sync action: sudo -u left4me env UV_PROJECT_ENVIRONMENT=/var/lib/left4me/.venv /usr/local/bin/uv sync --frozen --project /opt/left4me/src. triggered: True, cascade_skip: False. needs: includes 'git_deploy:/opt/left4me/src', 'action:left4me_install_uv', 'directory:/var/lib/left4me', 'user:left4me'. triggers: ['action:left4me_alembic_upgrade'].
   • Update git_deploy:/opt/left4me/src triggers (lines 285–305): replace 'action:left4me_pip_install' with 'action:left4me_uv_sync'. Keep left4me_alembic_upgrade and left4me_daemon_reload triggers.
   • Update left4me_alembic_upgrade (lines 384–407): its dependency on left4me_pip_install must now point at left4me_uv_sync.
3. Rewrite bundles/left4me/README.md:84–90 to describe the new install_uv → uv_sync → alembic_upgrade → seed_overlays + restart chain (drop the pip + tempdir-dance prose).
4. (cd ~/Projekte/ckn-bw && .venv/bin/bw test) → must pass clean.

Step 4 — ckn-bw commit (DO NOT PUSH)

Single commit using the suggested message from the handoff (§"Commit messages — ckn-bw side"). Do not git push. Per verified state today, ckn-bw is currently EVEN with origin/master (not 7 ahead as the original prompt claimed — the operator pushed since the prompt was written). After this commit lands locally, the repo will be 1 commit ahead of origin.

Step 5 — Report to operator (handoff to user for deploy)

Agent's work ends here. Brief summary to the user including:

• Spike outcome (full uv-workspace path confirmed, or Medium-scope fallback taken — including any handoff doc updates if the latter).
• What's committed and where it sits: left4me pushed to origin/master; ckn-bw committed locally, now 1 commit ahead of origin (unpushed).
• The bw apply ovh.left4me invocation for the user to run, with the expected output (left4me_install_uv runs the download+verify, three old actions removed from the graph, two new actions present (install_uv + uv_sync), alembic+seed+restart cascade fires).
• The 6-check verification matrix from handoff §"Verification (end-to-end)" for the user to walk through after apply — with check #1 amended: use sudo find /opt/left4me/src \( -name '*.egg-info' -o -name build -o -name dist \) -newer <baseline> instead of git status, because git isn't installed on prod.
• Recovery path if uv refuses to adopt the existing venv: one-shot ssh ckn@left4.me 'sudo -u left4me rm -rf /var/lib/left4me/.venv', then re-apply.
• Open follow-ups (uv version pinning policy — bump cadence, signing, etc; direnv use uv fallback applied or not; whether to add a separate pkg_apt: curl if it wasn't already declared).

Do NOT run bw apply, the verification matrix, or the gameserver round-trip — those are explicitly user-side per session memory.

Plan storage after approval

Per the user's global AGENTS.md (~/.claude/agents/AGENTS.md): specs and plans live in the repo they describe, typically under docs/. After ExitPlanMode and approval, this plan should be copied to /Users/mwiegand/Projekte/left4me/docs/superpowers/plans/2026-05-15-uv-workspace-execution.md as a peer to the design handoff, then committed alongside the left4me changes in Step 2.

What does NOT change (out of scope)

• Source ownership: /opt/left4me/src stays root-owned.
• Venv location: /var/lib/left4me/.venv stays where it is, owned by the left4me user, accessed via UV_PROJECT_ENVIRONMENT.
• Hardening drop-ins, sudoers, sysctl, helpers — all stable from the deployment-responsibility migration.
• systemd unit shapes — reactor-emitted, unchanged.
• alembic_upgrade and seed_overlays shell bodies — same commands, just triggered from uv_sync instead of pip_install.
• pkg_apt: python3 and python3-dev — kept (uv shells out to system Python).
• Other ckn-bw bundles — this is left4me-specific.
• The build-overlay-unit refactor — separate queued thread.
• CI — none currently exists.

Risks (carried from handoff, sized empirically)

1. Spike test failure → fall back to Medium scope. Graceful.
2. Lockfile format skew between dev and prod → MITIGATED by pinning prod uv to 0.11.8 (same as local brew). Lockfile generated by dev's uv 0.11.8 will be consumed by prod's uv 0.11.8 byte-for-byte compatible. Risk effectively eliminated unless dev's brew bumps uv independently — track this in the pinning-policy follow-up.
3. direnv use uv availability → local direnv is 2.37.1 (use uv added in 2.34+, so we're fine). Fallback snippet documented in case another dev has an older direnv.
4. alembic/flask binary paths → uv installs the same console_scripts entrypoints as pip, so paths under /var/lib/left4me/.venv/bin/ are identical. Verify in verification matrix.
5. --force-reinstall semantics → no longer needed; uv sync is lockfile-aware, not package-version-aware.
6. uv release artifact availability → if github.com/astral-sh/uv takes down release 0.11.8 (extremely unlikely but theoretically possible), the install action would fail. Mitigation: pin a recent stable release, monitor astral's deprecation cadence; if needed, mirror the artifact to an internal location for future-proofing (out of scope for this migration).
7. SHA256 of the tarball → we trust the .sha256 sibling fetched from the same github release. A future hardening pass could embed the checksum in the bundle source for offline verification, but the current trust model matches steamcmd's (also github-sourced).