Rembric TUI installer — contract

The TUI installer is the single, canonical, user-facing path for installing / setting up / upgrading / uninstalling the Rembric server and every client plugin. Docs lead with it; per-client commands are documented only as manual fallback.

Source of truth (read these — this file is the durable contract, not a copy):

• apps/plugin/install.sh — the orchestrator (real logic).
• install.sh (repo root) — the thin shim; canonical URL .../main/install.sh.
• install.test.ts (repo root) — the headless test surface (covers the root shim + the orchestrator).
• openspec/specs/tui-installer/spec.md — the normative requirements.

The orchestrator model (do NOT violate)

The installer delegates; it never reimplements. There are three backends, and each of the five clients uses exactly one:

• opencode, Hermes → invokes their own install.sh / uninstall.sh (via PLUGIN_SRC against a local clone, or curl at the same ref).
• Claude Code, Codex → prints the marketplace CLI commands (and optionally runs them when the client binary is present). No repo-side install script is created for these.
• Pi → runs the client's own CLI against the public npm registry: pi install npm:@rembric/pi, for install and for update, gated on binary presence and --yes exactly as the marketplace backend is; uninstall goes through that client's own removal verb. There is deliberately no .pi-plugin/install.sh, no .pi-plugin/uninstall.sh, and no marketplace entry. --ref=<tag> is NOT applied to it — the artifact comes from the registry, not a git ref, and appending a version would produce a pin that the client's own pi update --extensions / --all then skip, freezing the operator while reporting success.

The per-client primitives (install.sh/uninstall.sh, marketplace.json, the bridge, hooks) are the backend and the documented manual fallback. Changing the installer must not duplicate or fork their logic.

The root install.sh is a pure forwarder — no menu, token, fetch-of-artifacts, or client logic of its own. From a clone it execs apps/plugin/install.sh; over curl|sh it fetches that script at the same ref. Every flag/env passes through unchanged.

Surface to preserve

• Flags/env: --server, --agent=<a,b,..> (one or more of claude,codex,hermes,opencode,pi, or all), --action=install|update|uninstall, --up, --ref=<tag>, -h/--help; REMBRIC_SRC (local-source, no network), REMBRIC_NONINTERACTIVE, REMBRIC_REF, NO_COLOR.
• The client list must have ONE definition, with the agreement asserted by a test. The parser, the per-client loops, the arrow_menu and the usage text all enumerate it, and a client added to eleven of twelve places is the failure mode — so a new client is a one-line change plus a green agreement test, never a search-and-add sweep.
• Three run modes: interactive arrow-key TUI (real /dev/tty, raw mode) → numbered fallback (no raw mode) → headless flag mode (no controlling terminal or REMBRIC_NONINTERACTIVE=1). No controlling terminal must NOT hang — it falls to headless.
• Server flow is prepare + token + optional gated up: dependency report; auto-generate REMBRIC_ADMIN_TOKEN (and refill an empty token from an interrupted run); never start Docker without --up/confirmation; docker compose pull && up -d gated on docker compose availability.

What must not break (checklist)

1. Orchestration: still delegates per client; no inlined client logic; git ls-files apps/plugin/ shows one copy of each shared resource.
2. Root shim is a pure pass-through (flags/env reach apps/plugin/install.sh unchanged).
3. Token flow: fresh → generated 64-hex; pasted → kept; configured .env → untouched + shown; empty token (interrupted run) → refilled. Never bring up with an empty token.
4. Version detection per client: opencode @rembric-plugin-version comment; Hermes plugin.yaml; Claude/Codex versioned marketplace cache; Pi ${PI_CODING_AGENT_DIR:-~/.pi/agent}/npm/node_modules/@rembric/pi/package.json, which only a user-scope pi install npm: leaves behind — every other vector leaves none, so Pi is the one client that can legitimately report unknown rather than a guess. Available = single .release-please-manifest.json fetch at the install ref.
5. "Update available" never lies — and the registry-CLI row is the one that could make it. For Pi the installer does exactly one of two things: read the installed version from a deterministic on-disk location established by measurement, in the manner of the four adapters above; or report it as explicitly unknown and recommend the idempotent reinstall. Guessing, inferring from presence, or defaulting to the available version is prohibited — a table with one unreliable row is an unreliable table for every client. An unknown row must render unknown, never "up to date" and never "update available", and update-all skips it with unknown as the stated reason and still exits 0 (update-all runs unattended; reinstalling on ignorance would make it act on every run for a client it can never confirm). Forcing it stays the explicit --agent=pi --action=install path, and the skip line names that verb — every recommendation any surface prints comes from one state → verb mapping, so it is always a verb --action accepts (ACTIONS='install update uninstall', validated at parse time).
6. Post-install steps reflect the action, per client. Pi install prints the REMBRIC_SERVER_URL / REMBRIC_API_TOKEN shell exports and no settings-file alternative — measured: that harness injects nothing from its own settings file, so offering one would be inventing a path. Pi update prints only the restart.
7. Conservative uninstall: remove only plugin-owned files; never touch operator config, credentials, .rembric.
8. UX: lime block banner; each menu step clears+redraws (screen-replace, not stacking); restores stty/cursor on exit.
9. set -e safety: functions must not end on a false [ test ] (it aborts the script / kicks out of the menu). End client/menu helpers with return 0 or an if/fi.
10. POSIX: /bin/sh (dash) compatible — no bashisms; sh -n clean.

Before landing any install/distribution change

Run the rembric-tui-installer-e2e playbook (headless + local layers at minimum). The headless suite is CI-gated via install.test.ts (repo root); the interactive and Docker layers are operator-run.