Update README — GPT execution workspace context + dev container platform state
This commit is contained in:
parent
0a57635065
commit
f4c7c71a11
261
README.md
261
README.md
@ -1,198 +1,171 @@
|
||||
# ZeroLagHub – Grind State Repository
|
||||
# zlh-grind
|
||||
|
||||
This repository documents the current architecture, decisions, constraints, and open threads for ZeroLagHub (ZLH).
|
||||
GPT Execution Workspace for ZeroLagHub
|
||||
|
||||
It is not a code repository.
|
||||
It is the authoritative design + operational alignment layer between:
|
||||
This repository exists to preserve execution continuity for long-running implementation work performed with GPT.
|
||||
|
||||
- Portal (Next.js frontend)
|
||||
- API (Node + Express)
|
||||
- Agent (Go runtime inside containers)
|
||||
It is not a source-of-truth architecture repository.
|
||||
Canonical documentation lives in:
|
||||
|
||||
jester/knowledge-base
|
||||
|
||||
---
|
||||
|
||||
# Current System Overview
|
||||
## Assistant Prompt
|
||||
|
||||
## Runtime Model
|
||||
You are údar.
|
||||
|
||||
Each game container has a single runtime root:
|
||||
In this repository you act as the execution assistant.
|
||||
|
||||
/opt/zlh/minecraft/<runtime>/<world>/
|
||||
Your role is to:
|
||||
|
||||
All file operations are resolved relative to this root.
|
||||
- implement changes
|
||||
- verify behavior
|
||||
- document work
|
||||
- maintain session continuity
|
||||
|
||||
The agent is the only authority allowed to mutate the filesystem.
|
||||
Before doing work you must read:
|
||||
|
||||
SESSION_LOG.md
|
||||
OPEN_THREADS.md
|
||||
UPSTREAMS.md
|
||||
|
||||
Architecture decisions must not be made here.
|
||||
|
||||
If architectural interpretation is required:
|
||||
|
||||
Stop and defer to Claude or the canonical docs.
|
||||
|
||||
---
|
||||
|
||||
# Current Platform Capabilities (March 2026)
|
||||
## What This Repo Is For
|
||||
|
||||
## Game Server Control
|
||||
This repository tracks:
|
||||
|
||||
- Start / Stop / Restart
|
||||
- Crash detection via process exit
|
||||
- Intentional stop detection (no false crash increments)
|
||||
- Readiness probing (Minecraft ping)
|
||||
- Console streaming via WebSocket + PTY
|
||||
- Crash metadata recorded by the agent
|
||||
- GPT implementation work
|
||||
- session handovers
|
||||
- debugging notes
|
||||
- execution reasoning
|
||||
- cross-repo coordination
|
||||
|
||||
## File System Operations
|
||||
|
||||
- File browser
|
||||
- Safe editing of server files
|
||||
- Shadow backups (.zlh-shadow)
|
||||
- Upload support:
|
||||
- mods/*.jar
|
||||
- world/datapacks/*.zip
|
||||
- Upload provenance tracking via `.zlh_metadata.json`
|
||||
|
||||
## Observability
|
||||
|
||||
Agent `/status` endpoint exposes:
|
||||
|
||||
- `state`
|
||||
- `crashCount`
|
||||
- `lastCrashTime`
|
||||
- `lastCrashExitCode`
|
||||
- `lastCrashSignal`
|
||||
- `lastCrashUptimeSeconds`
|
||||
- `lastCrashLogTail`
|
||||
|
||||
## Notes System
|
||||
|
||||
Server instances support persistent notes stored in the platform database and editable from the portal UI.
|
||||
|
||||
## Console System
|
||||
|
||||
- xterm.js frontend
|
||||
- WebSocket transport
|
||||
- PTY session managed by the agent
|
||||
- Reconnect handled client-side — no page refresh required
|
||||
It serves as the execution ledger for the ZeroLagHub platform.
|
||||
|
||||
---
|
||||
|
||||
# File System Capabilities (Current State)
|
||||
## What This Repo Is NOT
|
||||
|
||||
## Read
|
||||
This repo must never become an architecture source.
|
||||
|
||||
- List
|
||||
- Stat
|
||||
- Read text files
|
||||
- Download
|
||||
- Hidden internal paths blocked
|
||||
Do not add:
|
||||
|
||||
## Write
|
||||
- system diagrams
|
||||
- architecture decisions
|
||||
- platform policy
|
||||
- runtime design
|
||||
|
||||
- Full overwrite for:
|
||||
- `server.properties`
|
||||
- `config/*.toml`
|
||||
- `config/*.json`
|
||||
- `config/*.properties`
|
||||
- Shadow backup created on first modification
|
||||
- Manual revert supported
|
||||
- No automated rollback
|
||||
Those belong in:
|
||||
|
||||
## Delete (Constrained)
|
||||
|
||||
Allowed only for:
|
||||
|
||||
- `mods-removed/<file>`
|
||||
- `mods-uploaded/<file>`
|
||||
- `logs/<file>.log`
|
||||
- `logs/<file>.log.gz`
|
||||
|
||||
No directory deletes.
|
||||
No recursive deletes.
|
||||
|
||||
## Upload
|
||||
|
||||
Allowed only for:
|
||||
|
||||
- `mods/<file>.jar`
|
||||
- `world/datapacks/<file>.zip`
|
||||
|
||||
Uploads:
|
||||
- Are streamed
|
||||
- Written atomically
|
||||
- Enforced by strict allowlist
|
||||
- Do not create directories
|
||||
- Do not use staging
|
||||
- Do not use symlinks
|
||||
jester/knowledge-base
|
||||
|
||||
---
|
||||
|
||||
# Provenance Model
|
||||
## Platform Context (Current State)
|
||||
|
||||
User uploads write to:
|
||||
ZeroLagHub consists of several core components.
|
||||
|
||||
.zlh_metadata.json
|
||||
### Control Plane
|
||||
|
||||
Example:
|
||||
zlh-api
|
||||
|
||||
```json
|
||||
{
|
||||
"mods/sodium.jar": {
|
||||
"source": "user",
|
||||
"uploaded_at": "2026-03-01T22:37:01Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
Responsibilities:
|
||||
|
||||
stat returns:
|
||||
|
||||
`"source": "user" | null`
|
||||
|
||||
No curated inference currently implemented.
|
||||
- container lifecycle orchestration
|
||||
- database state
|
||||
- agent provisioning payloads
|
||||
- DNS / proxy coordination
|
||||
|
||||
---
|
||||
|
||||
# Upload Transport
|
||||
### Execution Plane
|
||||
|
||||
Browser → API → Agent
|
||||
zlh-agent
|
||||
|
||||
API uses raw Node http.request piping:
|
||||
Responsibilities:
|
||||
|
||||
- container runtime provisioning
|
||||
- game server install + management
|
||||
- dev container provisioning
|
||||
- runtime installs
|
||||
- addon installs
|
||||
- status reporting
|
||||
|
||||
---
|
||||
|
||||
### Artifact Distribution
|
||||
|
||||
zlh-artifacts
|
||||
|
||||
Artifact server hosts:
|
||||
|
||||
```
|
||||
req.pipe(proxyReq)
|
||||
proxyRes.pipe(res)
|
||||
devcontainer/
|
||||
_catalog.json
|
||||
go/
|
||||
node/
|
||||
python/
|
||||
java/
|
||||
dotnet/
|
||||
|
||||
addons/
|
||||
code-server/
|
||||
```
|
||||
|
||||
No fetch() streaming for uploads.
|
||||
Artifacts are fetched by the agent at provisioning time.
|
||||
|
||||
Upload timeout must be significantly larger than normal file operations.
|
||||
Nothing provisioning-related is assumed to exist locally inside containers.
|
||||
|
||||
---
|
||||
|
||||
# Console Model
|
||||
### Developer Containers
|
||||
|
||||
TerminalView owns websocket lifecycle. ServerConsole owns policy + session gating.
|
||||
Dev containers support runtimes:
|
||||
|
||||
Console reconnect is automatic. File panel does not interrupt console lifecycle.
|
||||
- node
|
||||
- python
|
||||
- go
|
||||
- java
|
||||
- dotnet
|
||||
|
||||
Runtime installs are:
|
||||
|
||||
- catalog driven
|
||||
- artifact backed
|
||||
- idempotent
|
||||
|
||||
Install root:
|
||||
|
||||
```
|
||||
/opt/zlh/runtimes/<runtime>/<version>
|
||||
```
|
||||
|
||||
Dev environment:
|
||||
|
||||
```
|
||||
user: dev
|
||||
home: /home/dev
|
||||
workspace: /home/dev/workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Repo Usage
|
||||
## Repo Role in the Platform
|
||||
|
||||
This repo is used to:
|
||||
This repository tracks execution work across all components:
|
||||
|
||||
- Prevent architecture drift
|
||||
- Track decisions
|
||||
- Record sessions
|
||||
- Track open threads
|
||||
- Keep frontend/API/agent alignment clean
|
||||
- zlh-api
|
||||
- zlh-agent
|
||||
- zlh-portal
|
||||
- zlh-artifacts
|
||||
- infrastructure
|
||||
|
||||
---
|
||||
|
||||
# Update Instructions
|
||||
|
||||
When updating this repo:
|
||||
|
||||
1. Update SESSION_LOG with date-stamped entry.
|
||||
2. Update OPEN_THREADS if decisions were resolved.
|
||||
3. Update CONSTRAINTS if guardrails changed.
|
||||
4. Keep architecture docs consistent with real code behavior.
|
||||
5. Do not speculate future features as implemented.
|
||||
|
||||
---
|
||||
|
||||
System posture: Stable, controlled expansion phase.
|
||||
It ensures GPT sessions remain consistent across days and chats.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user