refactor(l4d2-web): remove legacy external overlay type

The workshop + managed-global overlay surface fully covers the
admin-SFTP flow that 'external' was a placeholder for. Drop the type
from the model defaults, builder registry, routes, template, and
tests, and add migration 0004 that deletes any leftover external
rows along with their blueprint and job references.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-08 09:31:04 +02:00

3.1 KiB

Raw Blame History

AGENTS.md

Guidance for coding agents working in this repository.

Mission

Build left4me according to the two implementation plans:

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

Do not invent architecture outside these plans unless explicitly requested.

Current Project State

l4d2host/ and l4d2web/ implementation directories exist.
Implementation plans remain the source of truth for contract changes and task sequencing.

Non-Negotiable Constraints

Workspace and tools

Do not use git worktrees.

Naming and boundaries

Use l4d2 naming consistently.
Keep host library and web app as separate components.
Do not collapse them into one package.

Host library (`l4d2host` / `l4d2ctl`)

Exposed CLI write command set is fixed:
- install
- initialize <name> -f <spec.yaml>
- start <name>
- stop <name>
- delete <name>
CLI read commands are allowed for web/host boundary consistency:
- status <name> --json
- logs <name> --lines <n> --follow/--no-follow
Runtime paths are rooted at LEFT4ME_ROOT, defaulting to /var/lib/left4me.
Deployment/config management owns global units under /usr/local/lib/systemd/system and privileged helpers under /usr/local/libexec/left4me.
Overlay directories are populated by the web app (workshop downloads, managed-global refresh). The host library only mounts them.
Fail-fast subprocess behavior; pass raw stderr; propagate return code.
No lock manager, no rollback, no preflight runtime checks.
Delete missing instance/runtime dirs must succeed (no-op).
Read APIs required for web app integration:
- get_instance_status(name)
- stream_instance_logs(name, lines=200, follow=True)

Web app (`l4d2-web-app`)

Flask + server-rendered templates + vendored HTMX.
No external frontend framework/dependencies.
Custom CSS with tokenized, consistent link and accent colors.
Local username/password auth and admin flag.
Persist command logs in job_logs table (retain indefinitely).
Desired vs actual server state model.
Live logs in UI for both jobs and servers.
Web app host operations go through l4d2ctl via a host command client, not direct l4d2host imports.
Blueprint semantics (locked):
- private per user in v1
- live-linked to servers
- no server-level overrides
- deleting in-use blueprint is blocked
- updates apply on next action
- servers can reassign blueprint anytime

Delivery Workflow

Read both plan files fully before coding.
Execute plan tasks in order.
Keep changes scoped to one task at a time.
Run task-level tests before moving forward.
Do not claim completion without command evidence.
Keep docs updated when behavior/contracts change.

Verification Expectations

Before claiming success on any step, run the relevant command and report actual output status.

Typical commands (once components exist):

pytest l4d2host/tests -q
pytest l4d2web/tests -q

Change Control

If a requested change conflicts with this file, follow explicit user instruction.
If plans and code diverge, update plans or flag the mismatch clearly.

3.1 KiB Raw Blame History