feat(recipes): multi-distro install for docker, devtools, tailscale

docs/qa/tui-clickthrough.md

@@ -0,0 +1,79 @@
+# TUI click-through: manual smoke test
+
+The checks an agent cannot run, because they need a real Alpine boot and a human
+reading the screen. Run these after any change to the list or detail screens.
+
+Data root is `~/.stoat` (or `$STOAT_HOME`). Each VM is a directory
+`~/.stoat/<dir>/` that holds a `vm.toml`. Build and launch the TUI with `just run`
+or `go run ./cmd/stoat`.
+
+Keys, for reference. List screen: `enter` start/stop, `l`/`→` details, `s` ssh,
+`p` provision, `d` delete, `n` new, `r` edit recipes, `/` search. Detail screen:
+`e` edit form, `E` raw vm.toml in `$EDITOR`, `i` installed toggle, `s` ssh, `p`
+provision, `L` console log, `S` snapshots, `esc`/`h`/`q` back.
+
+## 1. VM start: row flip and uptime tick
+
+Verifies the running dot and the `time.Since(StartedAt)` uptime that ticks with
+no list refresh.
+
+1. On the list, select a stopped VM. The dot is the stopped glyph, the row shows
+   `-`.
+2. Press `enter`. The VM starts.
+3. Watch the row. The dot flips to the running glyph. The row reads
+   `up 1s :PORT`, then `up 2s`, then `up 3s`. The count climbs every second on
+   its own.
+4. Confirm the seconds keep climbing without any keypress. A frozen number means
+   the uptime regressed to a stored duration.
+5. Press `enter` again to stop it. The dot returns to stopped and the uptime
+   drops to `-`.
+
+## 2. Corrupt vm.toml: shows broken, deletes with d+y
+
+Verifies a broken VM still lists and deletes, keyed by its directory.
+
+1. Stop the TUI. Pick a directory name that sorts mid-list, e.g. `mmm-broken`.
+   Create `~/.stoat/mmm-broken/vm.toml` with garbage: `not = valid = toml`.
+2. Launch the TUI. `mmm-broken` appears in alphabetical position, marked broken.
+3. Select it and press `l`. The detail screen still opens; `L` serves any
+   console log the directory holds.
+4. Back on the list, press `d`. A `y/N` confirmation appears.
+5. Press `y`. The row is removed and `~/.stoat/mmm-broken/` is gone.
+6. Repeat step 4. Press any key other than `y`. The TUI cancels the delete and
+   the row stays.
+
+## 3. vm.toml name differs from directory
+
+Verifies every operation keys off the directory, never the `name` field. This
+identity bug recurred before. It must stay fixed.
+
+1. Stop the TUI. In a working VM at `~/.stoat/realdir/vm.toml`, change the `name`
+   field to `wrongname` (leave the directory `realdir`).
+2. Launch the TUI. The row shows `realdir`, the directory, not `wrongname`.
+3. Press `l` for details. Run each key below. Each one must act on this VM, and
+   none may report "not found":
+   - `E` opens `realdir/vm.toml` in `$EDITOR`.
+   - `L` shows this VM's console log.
+   - `s` opens an ssh session to it (VM must be running).
+   - `p` starts a provision run against it.
+4. Restore the `name` field afterward if you care about it.
+
+## 4. Snapshots modal (S), four states
+
+Verifies the `S` modal and both confirmation-gated destructive paths. Snapshots
+need a disk or cloud VM, not live.
+
+1. On the detail screen of a VM with no snapshots, press `S`. The modal
+   opens and shows an empty-state line, not a blank box.
+2. Press `d`, then `r`. Neither does anything on an empty list. `esc` closes the
+   modal.
+3. Take a snapshot first (`stoat snapshot <vm> <tag>` from a shell), then reopen
+   the detail screen and press `S`. The snapshot lists by its tag and date.
+4. Press `d`. A `delete clean? y/N` line appears. Press a non-`y` key. The TUI
+   deletes nothing. Press `d` then `y`. The TUI removes the snapshot and
+   refreshes the list.
+5. Take another snapshot. Press `r`. A `restore clean? y/N` line appears. Confirm
+   with `y` and the VM's disk rolls back to that snapshot.
+6. Run steps 1-5 once with the VM stopped and once running. Both must behave the
+   same. A running VM's `info snapshots` prints `--` for the ID. The modal keys
+   everything off the tag for that reason.

internal/apkovl/apkovl.go

@@ -90,9 +90,16 @@ fi
 // here (see installScript's ttyS0 redirect), so the window would otherwise show
 // only a bare login prompt with no sign that an unattended install is running.
 const installIssue = `
-    stoat is installing Alpine on this VM.
-    It runs unattended and powers off when done. Do not log in.
-    Watch progress from the host:  stoat logs <vm>
+    ┌───────────────────────────────────────────────────────┐
+    │                                                       │
+    │                  Installing Alpine.                   │
+    │                                                       │
+    │   (◕  ᴥ  ◕)      Unattended. Powers off when done.    │
+    │                  Do not log in.                       │
+    │                                                       │
+    │                  Watch progress:  stoat logs <vm>     │
+    │                                                       │
+    └───────────────────────────────────────────────────────┘
 
 `
 

internal/apkovl/apkovl_test.go

@@ -327,7 +327,7 @@ func TestBuildIncludesInstallStageForDiskMode(t *testing.T) {
 		t.Errorf("stoat-install.start does not redirect to the captured serial port:\n%s", script)
 	}
 	// The VGA console shows a splash instead of a bare login prompt.
-	if !strings.Contains(content["etc/issue"], "installing") {
+	if !strings.Contains(content["etc/issue"], "Installing") {
 		t.Errorf("etc/issue missing the install banner: %q", content["etc/issue"])
 	}
 	if m := hdrs["etc/local.d/stoat-install.start"].Mode; m&0o111 == 0 {

internal/cli/subcommands_test.go

@@ -171,24 +171,23 @@ func TestRecipesListsAndFilters(t *testing.T) {
 		t.Fatal("recipes returned nothing with no filter")
 	}
 
-	// debian only satisfies xfce's OS list (the other bundled recipes all
-	// require alpine-only capabilities like apk/openrc), so filtering to it
-	// is strictly narrower than the full catalog.
+	// debian satisfies xfce, devtools, docker, and tailscale OS lists.
 	_, only := runJSON(t, "recipes", "--os", "debian", "--backend", "cloudinit")
 	debian, _ := dataOf(t, only)["recipes"].([]any)
 	if len(debian) == 0 {
 		t.Fatal("recipes --os debian --backend cloudinit returned nothing")
 	}
-	if len(debian) >= len(every) {
-		t.Errorf("filtered %d is not narrower than unfiltered %d", len(debian), len(every))
-	}
+	want := map[string]bool{"xfce": true, "devtools": true, "docker": true, "tailscale": true}
 	for _, r := range debian {
 		m, _ := r.(map[string]any)
 		name, _ := m["name"].(string)
-		if name != "xfce" {
-			t.Errorf("debian/cloudinit offered %q, want only xfce", name)
+		if !want[name] {
+			t.Errorf("debian/cloudinit offered unexpected recipe %q", name)
 		}
 	}
+	if len(debian) != len(want) {
+		t.Errorf("debian/cloudinit offered %d recipes, want %d", len(debian), len(want))
+	}
 }
 
 func TestRecipesUnknownOSIsAnEmptyArray(t *testing.T) {
@@ -223,8 +222,8 @@ func TestCheckRecipesApplicableAndNot(t *testing.T) {
 		t.Errorf("issues = %v, want empty", issues)
 	}
 
-	// docker requires alpine's apk/openrc; debian cannot run it.
-	code, objs = runJSON(t, "check-recipes", "docker", "--os", "debian", "--backend", "cloudinit")
+	// A non-existent recipe is inapplicable to any OS.
+	code, objs = runJSON(t, "check-recipes", "nosuchrecipe", "--os", "debian", "--backend", "cloudinit")
 	if code != ExitOK {
 		t.Fatalf("inapplicable: exit = %d, want 0: checking SUCCEEDED", code)
 	}

internal/core/apply_test.go

@@ -245,22 +245,21 @@ func TestCheckRecipesOKRecipeReportsNoIssue(t *testing.T) {
 	}
 }
 
-// A recipe requested for an OS its recipe.toml doesn't declare (docker is
-// alpine-only) reports the OS mismatch from recipes.MatchReason.
+// A recipe requested for an OS its recipe.toml doesn't declare reports the OS
+// mismatch from recipes.MatchReason. The bundled recipes now ship for every OS,
+// so this pins a synthetic alpine-only recipe.
 func TestCheckRecipesReportsOSMismatch(t *testing.T) {
-	root(t)
-	if err := recipes.Install(); err != nil {
-		t.Fatal(err)
-	}
+	dir := root(t)
+	writeV2RecipeWithOS(t, dir, "alpineonly", "once", "1.0", []string{"alpine"}, "#!/bin/sh\necho test\n")
 
-	issues, err := CheckRecipes("debian", "apkovl", []string{"docker"})
+	issues, err := CheckRecipes("debian", "apkovl", []string{"alpineonly"})
 	if err != nil {
 		t.Fatal(err)
 	}
 	if len(issues) != 1 {
 		t.Fatalf("issues = %+v, want exactly 1", issues)
 	}
-	want := "docker: built for alpine, not debian"
+	want := "alpineonly: built for alpine, not debian"
 	if !strings.Contains(issues[0].Reason, want) {
 		t.Errorf("Reason = %q, want it to contain %q", issues[0].Reason, want)
 	}
@@ -312,6 +311,30 @@ func writeDepRecipe(t *testing.T, rootDir, name, run string, depends []string) {
 	}
 }
 
+// writeV2RecipeWithOS is like writeV2Recipe but also sets the os field.
+func writeV2RecipeWithOS(t *testing.T, rootDir, name, run, version string, oses []string, script string) {
+	t.Helper()
+	recipeDir := filepath.Join(rootDir, "recipes", name)
+	if err := os.MkdirAll(recipeDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	osLine := ""
+	if len(oses) > 0 {
+		osLine = "os = [\"" + strings.Join(oses, "\", \"") + "\"]\n"
+	}
+	toml := "name = \"" + name + "\"\n" +
+		"version = \"" + version + "\"\n" +
+		osLine +
+		"script = \"install.sh\"\n" +
+		"run = \"" + run + "\"\n"
+	if err := os.WriteFile(filepath.Join(recipeDir, "recipe.toml"), []byte(toml), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(recipeDir, "install.sh"), []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+}
+
 // TestPlanApplyOnStoppedVM pins the dry-run plan: it is computed host-side, so
 // a stopped VM (never started here) still returns a correct run/skip plan. An
 // applied "once" recipe with a matching hash skips; an unapplied one runs.

internal/core/needs_provision.go

@@ -9,18 +9,18 @@ import "github.com/novusedge/stoat/internal/config"
 // disk VM with a share set, since sshx.Provision's share-mount step is
 // idempotent but leaves no Applied entry to check.
 //
-// A cloud VM always returns false. cloud-init applies its recipes from the
-// seed at first boot, so an ssh provision run has nothing to do.
+// For cloud VMs, this may return true on first boot (before discoverCloudInitApplied
+// has populated v.Applied). Apply handles that: it reads the markers cloud-init
+// left, populates Applied, and skips recipes already run. A minor no-op pass
+// on first boot is acceptable; it's the price of supporting recipes added
+// after creation.
 func NeedsProvision(v *config.VM) (bool, error) {
-	if v.Mode == "cloud" {
-		return false, nil
-	}
 	runTargets, _, err := filterByRunMode(v, v.Recipes, nil)
 	if err != nil {
 		return false, err
 	}
 	if len(runTargets) > 0 {
 		return true, nil
 	}
-	return v.Mode == "disk" && v.Share != "", nil
+	return (v.Mode == "disk" || v.Mode == "cloud") && v.Share != "", nil
 }

internal/core/needs_provision_test.go

@@ -89,17 +89,42 @@ func TestNeedsProvisionDiskWithShareEvenWhenApplied(t *testing.T) {
 	}
 }
 
-// TestNeedsProvisionCloud: cloud-init applies a cloud VM's recipes at first
-// boot, so there is never anything left for an ssh-based provision run.
-func TestNeedsProvisionCloud(t *testing.T) {
-	root(t)
-	v := &config.VM{Mode: "cloud", OS: "debian", Recipes: []string{"xfce"}}
+// TestNeedsProvisionCloudUnapplied: a cloud VM with recipes not yet in Applied
+// returns true. On first boot this triggers a no-op pass (discoverCloudInitApplied
+// finds the markers); for recipes added after creation it runs them.
+func TestNeedsProvisionCloudUnapplied(t *testing.T) {
+	dir := root(t)
+	writeV2Recipe(t, dir, "tool", "once", "1.0", "#!/bin/sh\necho one\n")
+	v := &config.VM{Mode: "cloud", OS: "alpine", Recipes: []string{"tool"}}
+
+	got, err := NeedsProvision(v)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !got {
+		t.Error("got false, want true: the recipe has never run (or markers not yet discovered)")
+	}
+}
+
+// TestNeedsProvisionCloudAllApplied: a cloud VM with all recipes already in
+// Applied (markers discovered, or added and run) returns false.
+func TestNeedsProvisionCloudAllApplied(t *testing.T) {
+	dir := root(t)
+	writeV2Recipe(t, dir, "tool", "once", "1.0", "#!/bin/sh\necho one\n")
+	hash, err := recipes.ScriptHash("tool", "alpine")
+	if err != nil {
+		t.Fatal(err)
+	}
+	v := &config.VM{
+		Mode: "cloud", OS: "alpine", Recipes: []string{"tool"},
+		Applied: map[string]config.AppliedRecipe{"tool": {Version: "1.0", Hash: hash}},
+	}
 
 	got, err := NeedsProvision(v)
 	if err != nil {
 		t.Fatal(err)
 	}
 	if got {
-		t.Error("got true, want false: a cloud VM provisions through cloud-init")
+		t.Error("got true, want false: all recipes already applied")
 	}
 }

internal/recipes/bundled/devtools/install-alpine.sh

@@ -0,0 +1,45 @@
+#!/bin/sh
+# The baseline you end up installing on every throwaway VM: version control, a
+# compiler, an editor, and the tools to fetch things. Runs as root over ssh on
+# a booted Alpine VM.
+set -e
+
+# -c enables community (where most of these live outside the base set); -1
+# picks a mirror and refreshes indexes, so no separate `apk update`.
+# setup-apkrepos runs apk update with no lock-wait, so another apk that holds
+# the database lock fails it with exit 99. Retry until the lock frees, up to
+# ~60s.
+n=0
+until setup-apkrepos -c -1; do
+    n=$((n + 1))
+    [ "$n" -ge 30 ] && { echo "apk database stayed locked; giving up" >&2; exit 1; }
+    sleep 2
+done
+
+# build-base is Alpine's meta-package for gcc/make/libc-dev: the equivalent of
+# Debian's build-essential. Alpine has no package called "build-essential".
+# --wait 60 makes apk wait up to 60s for the lock instead of failing with
+# exit 99 when another apk run holds it.
+apk --wait 60 add git curl ca-certificates build-base vim tmux less
+
+# Alpine's default shell is ash and there is no bash unless asked for; scripts
+# copied in from elsewhere routinely assume it, so it is part of a baseline.
+apk --wait 60 add bash
+
+git --version
+echo "devtools installed: git, curl, build-base (gcc/make), vim, tmux, less, bash"
+
+# Live VMs are diskless: the root filesystem is a tmpfs/overlay in RAM, so
+# every package installed above is gone on reboot. A disk install mounts a
+# real block device as root, which persists. Detecting it from inside the
+# guest (rather than assuming) is the same mechanism xfce.alpine.sh uses.
+root_fstype=$(awk '$2 == "/" { print $3 }' /proc/mounts)
+
+case "$root_fstype" in
+tmpfs | overlay)
+	echo "NOTE: this is a live VM (root is $root_fstype, in RAM). Everything installed above is gone after a reboot. Rebooting will NOT bring it back. Use a disk VM to keep it."
+	;;
+*)
+	echo "installed on a disk VM (root is $root_fstype), so this survives a reboot."
+	;;
+esac

internal/recipes/bundled/devtools/install-arch.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# git, a compiler, an editor and basic fetch tools. Runs as root over ssh on a
+# booted Arch VM.
+set -e
+
+pacman -Sy --noconfirm git curl ca-certificates base-devel vim tmux less bash
+
+git --version
+echo "devtools installed: git, curl, base-devel (gcc/make), vim, tmux, less, bash"

internal/recipes/bundled/devtools/install-debian.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# git, a compiler, an editor and basic fetch tools. Runs as root over ssh on a
+# booted Ubuntu or Debian VM.
+set -e
+
+export DEBIAN_FRONTEND=noninteractive
+apt-get update
+apt-get install -y git curl ca-certificates build-essential vim tmux less bash
+
+git --version
+echo "devtools installed: git, curl, build-essential (gcc/make), vim, tmux, less, bash"

internal/recipes/bundled/devtools/install-fedora.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# git, a compiler, an editor and basic fetch tools. Runs as root over ssh on a
+# booted Fedora VM.
+set -e
+
+dnf install -y git curl ca-certificates gcc make vim tmux less bash
+
+git --version
+echo "devtools installed: git, curl, gcc, make, vim, tmux, less, bash"