No description

Find a file

mwiegand 5284e28af7 refactor: move privileged scripts to scripts/{libexec,sbin}/; deploy/ is reference Pulls the 5 privileged helpers out of deploy/files/usr/local/{libexec,sbin}/ into top-level scripts/{libexec,sbin}/. They are application-inherent code (invoked at runtime via sudo from l4d2host/l4d2web), not deploy artifacts — the previous nesting under deploy/files/ confused source-of-truth with install-target FHS layout. deploy/ now means "reference exemplar": README explaining the target layout, plus example sudoers / sysctl / sandbox-resolv.conf / env templates / curated systemd units (the ones ckn-bw's reactor emits). Anyone building a fresh deployment (other than ckn-bw) reads this tree. Dead static artifacts deleted: left4me-apply-cake helper, left4me-cake + left4me-nft-mark service units, cake.env, left4me-mark.nft, and the superseded deploy-test-server.sh installer. Tests split to match the new shape: - scripts/tests/{test_overlay,test_script_sandbox,test_systemctl_helper, test_journalctl_helper,test_helpers_use_fixed_paths,test_sudoers_grants}.py with shared fixtures in conftest.py - deploy/tests/test_example_units.py (renamed from test_deploy_artifacts.py) — slimmed to lock down the curated example units, sysctl, env templates l4d2host/tests/test_overlay_helper.py: helper-source path updated to scripts/libexec/left4me-overlay (was building the path segment-by-segment under deploy/files/, missed by the path-prefix grep during pre-flight). Runtime install-target paths (/usr/local/{libexec,sbin}/) unchanged, so l4d2host/service_control.py, l4d2web/services/overlay_builders.py, the sudoers grants, and the systemd units all keep their existing path references. Requires the matching ckn-bw change to bundles/left4me/items.py (install_left4me_scripts repointed from /opt/left4me/src/deploy/files/... to /opt/left4me/src/scripts/...). Left4me lands first so a fresh git_deploy exposes the new source path before the bundle apply runs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>		2026-05-15 12:05:30 +02:00
deploy	refactor: move privileged scripts to scripts/{libexec,sbin}/; deploy/ is reference	2026-05-15 12:05:30 +02:00
docs	docs: janitorial cleanup checklist + L4D2 server cvar reference	2026-05-15 02:05:12 +02:00
examples/script-overlays	feat(l4d2-web): seed example script overlays from examples/script-overlays/	2026-05-08 18:41:08 +02:00
l4d2host	refactor: move privileged scripts to scripts/{libexec,sbin}/; deploy/ is reference	2026-05-15 12:05:30 +02:00
l4d2web	harden(l4d2web): per-username login rate limit alongside per-IP	2026-05-14 22:26:20 +02:00
scripts	refactor: move privileged scripts to scripts/{libexec,sbin}/; deploy/ is reference	2026-05-15 12:05:30 +02:00
.envrc	chore: add direnv .envrc for local Python 3.13 venv	2026-05-08 18:56:51 +02:00
.gitignore	chore: add dev.db and opencode.json to gitignore	2026-05-13 14:29:57 +02:00
AGENTS.md	Revert "AGENTS: harden the spec+plan commit rule"	2026-05-11 22:26:47 +02:00
README.md	chore: add direnv .envrc for local Python 3.13 venv	2026-05-08 18:56:51 +02:00

README.md

left4me

left4me is a local L4D2 server management platform with two planned components:

l4d2host + l4d2ctl (host library + CLI)
l4d2-web-app (Flask web app for users, blueprints, servers, jobs, and logs)

Status

Implementation plans remain the source of truth for architecture and task sequencing:

docs/superpowers/plans/2026-04-22-l4d2-host-lib-v1.md
docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md

Locked v1 Decisions

Naming is strictly l4d2 (not l4d).
Host library and web app are separate components.
Host CLI write commands are fixed to:
- install
- initialize <name> -f <spec.yaml>
- start <name>
- stop <name>
- delete <name>
Host CLI read commands are available for the web/host boundary:
- status <name> --json
- logs <name> --lines <n> --follow/--no-follow
The web app calls host operations through l4d2ctl, not direct l4d2host imports.
Deployment uses /var/lib/left4me for runtime state, /opt/left4me for repository contents and the virtualenv, /etc/left4me for environment files, and global units under /usr/local/lib/systemd/system.
Overlay handling is directory-based; the web app populates each overlay (workshop downloads, managed-global refresh).
No lock manager, no rollback, no preflight checks in host library.
CLI propagates subprocess failures via stderr and return code.
delete on missing instance is no-op success.
Blueprint model (web app):
- user-private in v1
- servers are live-linked to blueprint
- no per-server overrides
- delete blueprint blocked when linked servers exist
- blueprint changes apply on next action
- server can reassign blueprint anytime

Planned Repository Layout

l4d2host/
l4d2web/
deploy/
docs/superpowers/plans/

Deployment

See deploy/README.md for the Linux test deployment contract, including the runtime user, target filesystem layout, systemd units, privileged helpers, sudoers rules, admin bootstrap, and overlay reference rules.

Local development

This repo uses direnv to auto-activate a Python 3.13 venv on cd (matching the Debian Trixie production target). With direnv installed and hooked into your shell:

direnv allow once per fresh checkout (and after any .envrc change).
cd out and back in — .direnv/python-3.13/ is created and put on PATH.
pip install -e ./l4d2host -e ./l4d2web to install both packages editable.
pip install pytest to run the test suites (pytest tests/ inside either subproject).

Tech Stack (planned)

Python 3.12+
Typer, PyYAML, pytest
Flask, SQLAlchemy, Alembic
HTMX (vendored locally), custom CSS, SSE
systemd units, kernel overlayfs (mounted via the left4me-overlay privileged helper), steamcmd

Recommended Implementation Order

Implement l4d2host plan first.
Implement l4d2web plan second.
Keep tests green task-by-task (TDD flow from plans).
Keep commits small and aligned with plan tasks.

Contributing Notes

Follow plan task order unless explicitly re-planned.
Keep contracts above unchanged unless the user asks to change them.
Update plan docs when scope or behavior changes.