left4me

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

1. l4d2host + l4d2ctl (host library + CLI)
2. 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 and externally populated.
• 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.

Tech Stack (planned)

• Python 3.12+
• Typer, PyYAML, pytest
• Flask, SQLAlchemy, Alembic
• HTMX (vendored locally), custom CSS, SSE
• systemd user units, fuse-overlayfs, steamcmd

Recommended Implementation Order

1. Implement l4d2host plan first.
2. Implement l4d2web plan second.
3. Keep tests green task-by-task (TDD flow from plans).
4. 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.