Module onboard 

firstpass onboard — fully agentic onboarding (SPEC §0.2: the primary user is an agent, and the human deserves the same one-command experience). Detect the environment, plan the exact steps, execute them under --apply, and verify end-to-end — so “install firstpass and route my agent through it” is one command, not a doc to follow.

Structure: detect and plan are pure (injected lookups, no I/O) so the decision logic is unit-tested offline; execute performs the side effects (spawn proxy, append one marked line to the shell rc, probe /healthz) and is deliberately thin. Without --apply the command is a dry run that prints the plan — agentic, but never surprising.

Structs

Environment

What onboarding discovered about this machine. Everything is injected-lookup driven so tests construct arbitrary environments without touching the real one.

Enums

Step

One onboarding step: what it is, and whether it’s already satisfied.

Constants

RC_MARKER

Marker comment appended with the env line so re-running onboard is idempotent and offboarding is greppable.

Functions

detect

Detect the environment via injected lookups: env(key) for env vars, on_path(bin) for PATH probes, healthz() for a live proxy probe. Pure decision logic; all I/O behind the closures.

execute

Execute the side-effectful steps. Returns a human report. Failures are reported per step — onboarding never half-dies silently.

offboard

firstpass offboard — the exact mirror of onboard: strip the marked line from every candidate rc file, stop the proxy onboard started (pidfile), and print the one command for this shell. Fully idempotent; reports what it found either way.

offboard_rc

Remove every marked onboard line from rc. Returns whether anything was removed. Only lines carrying RC_MARKER are touched — nothing else in the user’s rc is ever rewritten.

plan

Build the ordered plan for this environment. rc_already_wired is whether the rc file already carries the marker line (checked by the caller, injected here to stay pure).

rc_wired

Whether the rc file already carries the onboard marker (idempotence check for plan).

render

Render the plan for the dry run (default) or as the running commentary under --apply.

shell_wiring

The shell-dialect line that routes agents through the proxy, plus the rc file it belongs in. home is injected so tests never touch a real home directory.