Design: local environments design; summary: plan.
Creating and switching named local environments is packaged-desktop
behavior: the control surface cannot drive it, and an unpackaged dev run
returns dev for create and switch (the "Environments on this computer"
card stays hidden because the bridge reports packaged: false). Verify it
by hand on an installed build, exactly as below.
node --test electron/environments.node-test.mjs electron/environment-switch.node-test.mjspnpm test:electron runs these with the whole Electron suite. They cover
registry parsing and migration, the create guard rules (absolute paths, no
duplicate, no nesting, not the default directory), the orchestrator's
stop→lease→start→probe→persist order, and rollback on every failure path.
They do not prove the user workflow — the recipe does.
- A packaged desktop installation of this branch, signed in on This computer with at least one bot so the bot list is visibly non-empty.
- The registry lives in the app's user-data folder: on macOS
~/Library/Application Support/OpenMausBot/environments.json. - The app log (
server.login the app's logs directory) records every switch decision; keep it open.
- Open Settings → Servers. Under "Environments on this computer",
enter the name
APRS Chat, leave the data folder empty, choose Create. - Expect: a row
APRS Chatwith path~/.openmausbot-aprs-chat, a Switch button and a Forget (trash) affordance. No restart happens, and "This computer" still shows Current. Nothing is written to the new directory yet — creating registers the entry; the directory is created (and seeds itself) at first switch. - Expect
environments.jsonto contain the entry with"kind": "local", a generatedid, andactiveIdstill"local".
- Click Switch, then confirm "Switch to APRS Chat? The app restarts on that environment."
- Expect: the window goes blank/unavailable while the old server child is stopped and the target boots, then reloads onto the new environment — roughly fifteen seconds for an already-existing directory. The boot probe allows up to 60 seconds per port attempt (ports 8799, 18799, 28799, two passes), so a first boot on a cold disk can take longer.
- Expect on arrival: an empty bot list (fresh environment), the sidebar
pill reading
APRS Chat, and "APRS Chat" marked Current in Settings → Servers. - Expect from a terminal:
~/.openmausbot-aprs-chat/environment-idexists and is a UUID different from~/.openmausbot/environment-id— the two environments are distinct servers, and every state file lives under its own directory.environments.jsonnow hasactiveIdset to the entry's id. - Create a throwaway bot here, then confirm
~/.openmausbot/gained no trace of it.
Switch to This computer from the same page (or the Server menu). Expect the same reload, your original bot list back, and the new environment still listed with its bot intact when you look again.
Simulate an environment on a drive that is gone, without a real drive:
- Quit the app completely.
- Edit
environments.json: point an inactive entry'sdataDirat a path whose parent does not exist, e.g./Volumes/NO-VOLUME/openmausbot-env. - Launch the app on This computer. Expect: the row shows a missing badge (the flag is stamped at read time, so it clears when the path reappears).
- Click Switch and confirm. Expect: a short unavailability while the
switch aborts, the dialog "Could not switch environments" ("…The app
log has the details."), and the installation left exactly where it was —
This computer running,
activeIdunchanged, old server restarted by the rollback. The log showsswitch to /Volumes/NO-VOLUME/openmausbot-env aborted: target unavailablefollowed byenvironment switch to … failed (unavailable)— the probe refused to create a directory through the missing parent, and the entry keeps its missing badge.
Make the active environment unbootable:
- Quit the app. Create an unwritable parent, e.g.
sudo mkdir /opt/omb-locked && sudo chmod 500 /opt/omb-locked, set the active entry'sdataDirto/opt/omb-locked/envandactiveIdto that entry's id. - Launch. Expect the boot to fail across the port schedule (a child that
cannot create its data dir exits quickly; a hung child burns the full
probe timeout per attempt), then:
- the installation comes up on This computer with normal data,
- a dialog titled "The environment was unhealthy" says OpenMausBot "came up on this computer's default data folder instead" and to choose the environment again once it is available,
environments.jsonshowsactiveIdreset to"local", and the entry stays put for debugging.
Under pnpm dev:desktop the feature is intentionally off: the environments
card does not render, and environments:create / local environments:switch
answer { ok: false, error: "dev" }. Remote-server entries keep working in
dev; only local data-dir switching is packaged-gated.
Cross-process lease contention (two app processes, one environment) is
covered by electron/data-dir-lease.node-test.mjs, not this recipe. This
recipe does not cover Forget's delete-files choice, Windows/Linux paths, or
the packaged build matrix.