48 lines
3.0 KiB
Markdown
48 lines
3.0 KiB
Markdown
# ADR 0006: Simplify `periphemu` Bootstrap
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Date
|
|
|
|
2026-06-08
|
|
|
|
## Context
|
|
|
|
`startup/servers.lua` historically called `periphemu.create` four times on computer 0: a top modem, two `computer` peers at ids 1 and 2 (both labelled `Trap` in saved per-computer config), and a router peer at id 10. In CraftOS-PC GUI mode this opened **four windows** on every launch (`Computer 0`, two duplicate `Trap`s, and `Router`).
|
|
|
|
That setup predates the current workflow:
|
|
|
|
- The install path is now manifest-driven (`install.lua` v3.0.0 fetches files listed in `manifest.json` and writes a marker at `/trapos/manifest.json`). The legacy `apis/`, `programs/`, `servers/`, `install.lua` files hand-copied into each per-computer dir are obsolete.
|
|
- Local verification runs **headless** through `just test` against scripts in `tests/`; the smokes don't need persistent emulated peers.
|
|
- The duplicate `Trap` label and persistent stale computer state across versions caused recurring confusion.
|
|
|
|
The CraftOS-PC data directory (`~/Library/Application Support/CraftOS-PC/`) had also accumulated years of stale state in `computer/`, `old_computer/`, and per-id `config/*.json` files (labels like `test`, two `Trap`s, etc.).
|
|
|
|
## Decision
|
|
|
|
- `startup/servers.lua` attaches **only a top modem** under `periphemu`:
|
|
|
|
```lua
|
|
if periphemu then
|
|
periphemu.create('top', 'modem');
|
|
end
|
|
```
|
|
|
|
- Extra emulated computers are spawned manually from the CraftOS-PC shell when actually needed (e.g. `periphemu create 10 computer` to bring up a router peer for cross-VM testing). The pattern is documented in [`docs/periphemu.md`](../periphemu.md).
|
|
- Wiped the live CraftOS-PC data dir back to a clean slate (one-time, manually). Removed `computer/`, `old_computer/`, and all per-id `config/*.json`. Preserved `config/global.json` (user-level CraftOS-PC settings). A full pre-wipe backup lives at `~/Backups/craftos-pc-2026-06-08/CraftOS-PC/` outside any repo.
|
|
|
|
## Consequences
|
|
|
|
- `craftos` (GUI) now opens a single unlabelled `Computer 0` window with a top modem attached. No more duplicate `Trap` windows.
|
|
- `just test` is unchanged: the headless smokes set up whatever they need per script.
|
|
- New contributors and fresh machines get a clean state by default — no inherited per-computer config to chase.
|
|
- Cross-machine testing now requires an explicit `periphemu create` call from the shell rather than being implicit on boot. That is a deliberate trade-off: the cost is one extra command when you genuinely need a peer; the benefit is no surprise windows and no persisted ghost VMs.
|
|
- The `if periphemu then` guard (called out in CLAUDE.md) is preserved, so in-game behavior is unchanged.
|
|
|
|
## Future Work
|
|
|
|
- If `tests/` grows a multi-VM scenario, drive peer creation from the test script itself (each `tests/*.lua` already owns its setup) rather than re-adding peers to `startup/servers.lua`.
|
|
- Consider a small `programs/spawn-peer.lua` wrapper to make ad-hoc shell incantations friendlier (`spawn-peer 10` instead of `periphemu create 10 computer`). Not done now — premature for current usage.
|