feat(maestro): add maestro-install wizard (cargo install + systemd)

New `maestro-installer` crate exposing the `maestro-install` binary. Bootstrap flow: `cargo install --git ... maestro-installer && maestro-install` runs `cargo install` for `maestro-daemon` and `maestro-cli`, optionally drives `maestrod configure`, and on systemd hosts writes a user unit at `~/.config/systemd/user/maestrod.service` plus reload/enable/start. Pure builders (cargo install args, systemctl args, unit body) live in the lib and are unit-tested; main.rs is the prompt glue. Refs NAP-225.
2026-05-25 14:30:03 +00:00
parent 50f24a2cf9
commit 2da41cc720
8 changed files with 711 additions and 0 deletions
@@ -0,0 +1,77 @@
+# Installing Maestro
+
+The fastest way to get `maestrod` (per-host daemon) and `maestro` (CLI) onto a
+host is the install wizard:
+
+```sh
+cargo install --git https://git.naps.pt/naps62/maestro maestro-installer
+maestro-install
+```
+
+The wizard:
+
+1. Runs `cargo install` for `maestro-daemon` and `maestro-cli` (pinned to the
+   committed `Cargo.lock` via `--locked`).
+2. Optionally runs `maestrod configure` to drop a `~/.config/maestrod/config.toml`.
+3. On systemd hosts, optionally writes a user unit at
+   `~/.config/systemd/user/maestrod.service`, reloads systemd, and offers to
+   enable + start it.
+
+Both binaries land in `~/.cargo/bin` — make sure that's on your `$PATH`.
+
+## Flags
+
+| Flag | Purpose |
+|---|---|
+| `--git <url>` | Install from a different git repo (default: this one). |
+| `--branch <name>` | Pin a branch with `--git`. |
+| `--path <dir>` | Install from a local workspace checkout (`--path` + `-p <crate>`). |
+| `--no-locked` | Drop `--locked` from `cargo install` (resolves a fresh dep tree). |
+| `--exec-start <path>` | Override the systemd unit's `ExecStart` (default `~/.cargo/bin/maestrod`). |
+| `--no-systemd` | Skip the systemd step even if detected. |
+| `--no-configure` | Skip the `maestrod configure` step. |
+| `-y`, `--yes` | Non-interactive: install binaries + drop systemd unit + reload + enable, but **don't** auto-run `configure` or auto-start the unit (those need real config). |
+
+## What the systemd unit looks like
+
+The wizard writes a *user* unit (`systemctl --user`), since `maestrod` runs
+per-user and uses tmux sockets under `$XDG_RUNTIME_DIR`. Body:
+
+```ini
+[Unit]
+Description=Maestro per-host daemon (maestrod)
+Documentation=https://git.naps.pt/naps62/maestro
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=%h/.cargo/bin/maestrod
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Check status / logs:
+
+```sh
+systemctl --user status maestrod
+journalctl --user -u maestrod -f
+```
+
+## Manual install (no wizard)
+
+```sh
+cargo install --git https://git.naps.pt/naps62/maestro --locked maestro-daemon
+cargo install --git https://git.naps.pt/naps62/maestro --locked maestro-cli
+maestrod configure
+maestrod          # foreground; or wire your own service manager
+```
+
+## Non-Linux hosts
+
+The wizard works on macOS for the `cargo install` + `maestrod configure` parts.
+The systemd step is automatically skipped (probe of `/run/systemd/system`).
+launchd integration is not yet supported — start `maestrod` from your shell or
+your own service manager.