241 lines
6.8 KiB
Markdown
241 lines
6.8 KiB
Markdown
# Code Review Workflow
|
|
|
|
This document captures the current Codex-based review workflow for ZeroLagHub cross-repo code review and cleanup.
|
|
|
|
## Current review goal
|
|
|
|
Review the three active implementation repos together without breaking operations:
|
|
- `zlh-agent`
|
|
- `zpack-api`
|
|
- `zpack-portal`
|
|
|
|
Primary goals:
|
|
- verify inter-repo contracts and ownership boundaries
|
|
- identify mismatches and risky assumptions
|
|
- identify behavior-preserving cleanup / code-fold opportunities
|
|
- keep cleanup separate from runtime/toolchain modernization
|
|
|
|
## Current setup
|
|
|
|
All target repos should be fully up to date before review begins.
|
|
|
|
Codex environments are **one repo per environment**. The current working setup is:
|
|
- `Agent Review` environment -> `zlh-agent`
|
|
- `API Review` environment -> `zpack-api`
|
|
- `Portal Review` environment -> `zpack-portal`
|
|
|
|
There is **no multi-repo Codex environment** in the current setup. Cross-repo synthesis happens afterward in a separate chat/task by comparing the three outputs.
|
|
|
|
Recommended environment settings:
|
|
- universal image
|
|
- container caching ON
|
|
- setup script automatic
|
|
- internet access OFF unless explicitly needed
|
|
|
|
## Review order
|
|
|
|
1. review `zlh-agent` first as the source of truth for runtime behavior
|
|
2. review `zpack-api` second as the auth/transport/contract layer
|
|
3. review `zpack-portal` third as the UI/state/rendering layer
|
|
4. synthesize the three outputs in a separate chat/task
|
|
5. only then start cleanup / folding waves
|
|
|
|
## Cross-repo review checklist
|
|
|
|
For all three repos, the critical flows to trace are:
|
|
- provision / start / first boot
|
|
- stop / restart
|
|
- status / readiness
|
|
- backup create / list / delete / restore
|
|
- file edit / upload / revert
|
|
- console connect / reconnect
|
|
|
|
For each flow, review should identify:
|
|
- owner of behavior
|
|
- current contract
|
|
- assumptions about the other repos
|
|
- confirmed aligned areas
|
|
- mismatches / risky assumptions
|
|
- cleanup-safe folds
|
|
- high-risk breakpoints
|
|
- suggested follow-up checks
|
|
|
|
## Repo prompts
|
|
|
|
### Agent Review prompt
|
|
|
|
```text
|
|
Review this repository as the source of truth for runtime behavior in the ZeroLagHub stack.
|
|
|
|
Focus on:
|
|
- provisioning/startup
|
|
- stop/restart
|
|
- readiness and status
|
|
- backup/create/list/delete/restore
|
|
- file edit/upload/revert
|
|
- console lifecycle
|
|
|
|
Goals:
|
|
- identify owned behavior
|
|
- identify assumptions this repo makes about API and Portal
|
|
- identify any behavior that other repos are likely depending on implicitly
|
|
- identify cleanup-safe folds that preserve behavior
|
|
- identify any risky areas where refactoring could break operations
|
|
|
|
Do not refactor yet.
|
|
Do not propose broad architecture changes.
|
|
Prefer operational correctness over style commentary.
|
|
|
|
Return in this exact structure:
|
|
1. Owned behavior
|
|
2. Current contracts exposed to other repos
|
|
3. Assumptions about API/Portal
|
|
4. Confirmed aligned or stable areas
|
|
5. Mismatches / risky assumptions
|
|
6. Cleanup-safe folds
|
|
7. High-risk breakpoints
|
|
8. Suggested follow-up checks
|
|
```
|
|
|
|
### API Review prompt
|
|
|
|
```text
|
|
Review this repository as the transport, auth, and contract layer between zlh-agent and the Portal in the ZeroLagHub stack.
|
|
|
|
Focus on:
|
|
- auth / ownership / IP checks
|
|
- route forwarding to agent
|
|
- status polling and shaping
|
|
- backup/create/list/delete/restore forwarding
|
|
- restore async-start contract
|
|
- file edit/upload/revert forwarding
|
|
- websocket / console proxy behavior
|
|
|
|
Goals:
|
|
- identify owned behavior
|
|
- identify assumptions this repo makes about agent behavior
|
|
- identify assumptions this repo makes about Portal behavior
|
|
- identify duplicated logic that belongs in agent or portal instead
|
|
- identify cleanup-safe folds that preserve behavior
|
|
- identify risky areas where refactoring could break operations
|
|
|
|
Do not refactor yet.
|
|
Do not propose broad architecture changes.
|
|
Prefer operational correctness over style commentary.
|
|
|
|
Return in this exact structure:
|
|
1. Owned behavior
|
|
2. Current contracts exposed to Portal
|
|
3. Assumptions about agent
|
|
4. Confirmed aligned or stable areas
|
|
5. Mismatches / risky assumptions
|
|
6. Cleanup-safe folds
|
|
7. High-risk breakpoints
|
|
8. Suggested follow-up checks
|
|
```
|
|
|
|
### Portal Review prompt
|
|
|
|
```text
|
|
Review this repository as the UI/state/rendering layer of the ZeroLagHub stack.
|
|
|
|
Focus on:
|
|
- polling and status rendering
|
|
- server action flows
|
|
- backup/create/list/delete/restore UX
|
|
- restore accepted -> in-progress -> completion behavior
|
|
- file edit/upload/revert UX
|
|
- console connect/reconnect behavior
|
|
- any duplicated logic that looks like it belongs in API or agent
|
|
|
|
Goals:
|
|
- identify owned behavior
|
|
- identify assumptions this repo makes about API responses and agent semantics
|
|
- identify status/rendering mismatches that could mislead users
|
|
- identify cleanup-safe folds that preserve behavior
|
|
- identify risky areas where refactoring could break operations
|
|
|
|
Do not refactor yet.
|
|
Do not propose broad architecture changes.
|
|
Prefer operational correctness over style commentary.
|
|
|
|
Return in this exact structure:
|
|
1. Owned behavior
|
|
2. Current contracts consumed from API
|
|
3. Assumptions about API/agent
|
|
4. Confirmed aligned or stable areas
|
|
5. Mismatches / risky assumptions
|
|
6. Cleanup-safe folds
|
|
7. High-risk breakpoints
|
|
8. Suggested follow-up checks
|
|
```
|
|
|
|
## Synthesis step
|
|
|
|
After all three reviews complete, paste the outputs into a separate chat/task with headers like:
|
|
|
|
```text
|
|
AGENT REVIEW
|
|
...
|
|
|
|
API REVIEW
|
|
...
|
|
|
|
PORTAL REVIEW
|
|
...
|
|
```
|
|
|
|
Then synthesize into:
|
|
- confirmed aligned contracts
|
|
- mismatches
|
|
- risky assumptions
|
|
- operational breakpoints
|
|
- cleanup-safe folds
|
|
- suggested fix order
|
|
|
|
## Cleanup / folding rules
|
|
|
|
Cleanup happens **after** synthesis, not before.
|
|
|
|
Shared rule across Agent / API / Portal:
|
|
- prefer behavior-preserving folding over broad refactors
|
|
- fold repeated flows first
|
|
- split oversized files by responsibility second
|
|
- merge repeated flows, not concepts
|
|
- keep helpers small and concrete
|
|
- keep cleanup separate from runtime/toolchain/dependency upgrades
|
|
|
|
## Current cleanup direction
|
|
|
|
### Agent
|
|
- fold Forge + NeoForge installer flow
|
|
- fold devcontainer runtime installers
|
|
- split oversized HTTP files by responsibility
|
|
- add only small concrete helpers
|
|
|
|
### API
|
|
- fold repeated forwarding/auth/IP-guard patterns
|
|
- centralize stream-vs-JSON forwarding
|
|
- split oversized route/service files by responsibility
|
|
|
|
### Portal
|
|
- fold repeated API-client/status-polling/state-mapping logic
|
|
- centralize shared management action handling
|
|
- split oversized page/component/state files by responsibility
|
|
|
|
## Current toolchain posture
|
|
|
|
Current pinned / confirmed runtime posture at time of writing:
|
|
- Node: `22.22.2`
|
|
- Go: updated to a current supported line
|
|
|
|
Toolchain/runtime upgrades should be tracked and validated separately from cleanup-only changes.
|
|
|
|
## Session restart note
|
|
|
|
If a fresh session is needed, resume by:
|
|
1. reading this file
|
|
2. checking `OPEN_THREADS.md`
|
|
3. checking repo-specific trackers under `Codex/*/OPEN_ITEMS.md`
|
|
4. continuing the three-review -> synthesis -> cleanup workflow
|