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.
|
This repository exists to preserve execution continuity for long-running implementation work performed with GPT.
|
||||||
It is the authoritative design + operational alignment layer between:
|
|
||||||
|
|
||||||
- Portal (Next.js frontend)
|
It is not a source-of-truth architecture repository.
|
||||||
- API (Node + Express)
|
Canonical documentation lives in:
|
||||||
- Agent (Go runtime inside containers)
|
|
||||||
|
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
|
- GPT implementation work
|
||||||
- Crash detection via process exit
|
- session handovers
|
||||||
- Intentional stop detection (no false crash increments)
|
- debugging notes
|
||||||
- Readiness probing (Minecraft ping)
|
- execution reasoning
|
||||||
- Console streaming via WebSocket + PTY
|
- cross-repo coordination
|
||||||
- Crash metadata recorded by the agent
|
|
||||||
|
|
||||||
## File System Operations
|
It serves as the execution ledger for the ZeroLagHub platform.
|
||||||
|
|
||||||
- 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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# File System Capabilities (Current State)
|
## What This Repo Is NOT
|
||||||
|
|
||||||
## Read
|
This repo must never become an architecture source.
|
||||||
|
|
||||||
- List
|
Do not add:
|
||||||
- Stat
|
|
||||||
- Read text files
|
|
||||||
- Download
|
|
||||||
- Hidden internal paths blocked
|
|
||||||
|
|
||||||
## Write
|
- system diagrams
|
||||||
|
- architecture decisions
|
||||||
|
- platform policy
|
||||||
|
- runtime design
|
||||||
|
|
||||||
- Full overwrite for:
|
Those belong in:
|
||||||
- `server.properties`
|
|
||||||
- `config/*.toml`
|
|
||||||
- `config/*.json`
|
|
||||||
- `config/*.properties`
|
|
||||||
- Shadow backup created on first modification
|
|
||||||
- Manual revert supported
|
|
||||||
- No automated rollback
|
|
||||||
|
|
||||||
## Delete (Constrained)
|
jester/knowledge-base
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# 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
|
Responsibilities:
|
||||||
{
|
|
||||||
"mods/sodium.jar": {
|
|
||||||
"source": "user",
|
|
||||||
"uploaded_at": "2026-03-01T22:37:01Z"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
stat returns:
|
- container lifecycle orchestration
|
||||||
|
- database state
|
||||||
`"source": "user" | null`
|
- agent provisioning payloads
|
||||||
|
- DNS / proxy coordination
|
||||||
No curated inference currently implemented.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# 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)
|
devcontainer/
|
||||||
proxyRes.pipe(res)
|
_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
|
- zlh-api
|
||||||
- Track decisions
|
- zlh-agent
|
||||||
- Record sessions
|
- zlh-portal
|
||||||
- Track open threads
|
- zlh-artifacts
|
||||||
- Keep frontend/API/agent alignment clean
|
- infrastructure
|
||||||
|
|
||||||
---
|
It ensures GPT sessions remain consistent across days and chats.
|
||||||
|
|
||||||
# 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.
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user