diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 6a57ddd..91b1292 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -64,21 +64,64 @@ access. Pulls runtimes + server jars from zlh-artifacts (VM 1003). ## Agent (Operational) - HTTP server on :18888, internal only — API is the only caller -- Container types: `game` (Minecraft, Rust, Valheim, etc.) and `dev` - (node/python/go/java runtimes) -- Runtime root: `/opt/zlh/minecraft///` +- Container types: `game` and `dev` - Lifecycle: POST /config triggers async provision + start pipeline -- Filesystem: strict path allowlist, atomic writes, shadow backups - (7-day retention, 6h cleanup cycle) -- Upload paths: `mods/*.jar` (250MB), `world/datapacks/*.zip` (100MB) -- Upload transport: raw `http.request` piping (`req.pipe(proxyReq)`), - never fetch() +- Filesystem: strict path allowlist for games, workspace-root sandbox for dev containers +- Upload transport: raw `http.request` piping (`req.pipe(proxyReq)`), never fetch() - Console: PTY-backed WebSocket, one read loop per container - Self-update: periodic check + apply - Forge/Neoforge: automated 5-step post-install patch sequence - Modrinth mod lifecycle: install/enable/disable/delete — fully operational -- Provenance: `.zlh_metadata.json` — source is `null` if not set, - no curated inference currently implemented +- Provenance: `.zlh_metadata.json` — source is `null` if not set, no curated inference currently implemented +- Status transport model remains poll-based (`/status`), not push-based +- `/status` content now includes richer dev/runtime/code-server fields +- State transitions remain internal to agent: `idle`, `installing`, `starting`, `running`, `stopping`, `crashed`, `error` + +--- + +## Dev Containers (Current State) + +- supported runtimes: node, python, go, java, dotnet +- runtime installs are artifact-backed and idempotent +- runtime root: `/opt/zlh/runtimes//` +- dev identity: `dev:dev` +- workspace root: `/home/dev/workspace` +- code-server install path: `/opt/zlh/services/code-server` +- code-server port: `6000` +- agent port: `18888` + +Confirmed during current validation: + +- code-server process launches inside the container +- process binds to `0.0.0.0:6000` +- Traefik dynamic dev route is created by API during provisioning +- frontend host/console state now updates correctly after API status endpoint work + +Current unresolved item: + +- external browser access to code-server through Cloudflare → Traefik → dev container is still being finalized + +--- + +## API / Proxy Coordination (Current State) + +Dev provisioning now includes an additive dev-only routing path. + +Current behavior: + +- game publish flow remains untouched +- if container type is `dev` and `enable_code_server=true`, API: + - creates Technitium A record + - creates Cloudflare A record + - writes Traefik dynamic config on `zlh-zpack-proxy` +- remote Traefik file writes use SSH service account `zlh` +- proxy SSH configuration is now service-account based, not tied to personal user + +Frontend/API status behavior: + +- API still polls agent state +- API now exposes server status back to frontend so host/console UI is accurate +- portal is no longer relying on stale DB-only host state for console availability --- @@ -108,14 +151,10 @@ Revenue multiplier: 1 developer → ~10 players → $147.50/mo total. ## Open Threads -1. **Upload timeout tuning** — need clear separation of client abort / - upstream timeout / socket reset in upload route logging -2. **Dev server filesystem model** — game servers complete; dev container - file layout, artifact promotion strategy, and edit scope not yet designed -3. **Curated provenance** — tracking install origin (Modrinth, manual, etc.) - not yet implemented -4. **Optional future:** config diff viewer, upload progress UI, upload - cancellation, log search +1. External dev IDE access — finalize end-to-end browser reachability for code-server +2. Curated provenance — tracking install origin (Modrinth, manual, etc.) +3. Dev routing cleanup — normalize hostname/domain generation and deletion cleanup +4. Optional future: config diff viewer, upload progress UI, upload cancellation, log search --- @@ -123,7 +162,7 @@ Revenue multiplier: 1 developer → ~10 players → $147.50/mo total. | Repo | Purpose | |------|---------| -| zlh-grind | Architecture decisions, constraints, session logs — source of truth | +| zlh-grind | Execution workspace / continuity / active constraints | | zlh-docs | API/agent/portal reference docs (read from source) | | zpack-api | API source (mirror) | | zpack-portal | Portal source (mirror) | @@ -135,14 +174,11 @@ All at `git.zerolaghub.com/jester/` ## Session Guidance -- zlh-grind is the authoritative constraint layer — check before making - architecture decisions -- zlh-docs has full agent documentation (routes, filesystem rules, - provisioning pipeline) -- Agent is the authority on filesystem enforcement — API must NOT - duplicate filesystem logic +- zlh-grind is the execution continuity layer, not the architecture authority +- zlh-docs has full agent documentation (routes, filesystem rules, provisioning pipeline) +- Agent is the authority on filesystem enforcement — API must NOT duplicate filesystem logic - Portal does not enforce real policy — agent enforces - Portal never calls agents directly — all traffic through API - Upload transport uses raw http.request piping, never fetch() - VMs 100, 101, 103, 1000 are legacy/unused — not active production -- Do not speculate future features as implemented +- Do not mark unresolved routing or TLS work as complete