Archduino/docs/superpowers/specs/2026-04-14-plan3a-install-modules-design.md

# Plan 3a — Install Modules (Simple/Medium Tier) Design

**Status:** Approved 2026-04-14
**Scope:** Port 10 of the 13 Bash install modules to Go. Plan 3b (neovim, renode, scaffold) is a separate brainstorm.

## Goal

Port the 10 simple/medium `lib/*.sh` installer modules into Go packages under `internal/modules/`, each implementing the `module.Module` contract (Detect / Plan / Apply / Verify). Every module is unit-tested against an injected fake `platform.Runner`. Along the way, add the platform helpers these modules need (AUR, download, extract, git-clone, text-block writer) and fix the wizard `renderPlan` UI-blocking watchpoint flagged at the end of Plan 2.

## Architecture

Foundation tasks land first, then modules in simplest-first order:

1. **Wizard cache fix** — cache Detect+Plan results per module; invalidate on selection toggle. One small change, but it unblocks every downstream module from stalling the UI.
2. **Platform helpers** — `AURHelper` (yay), `Download`, `Extract`, `gitclient`, `textblock`. Each gets its own file, each gets TDD against a fake Runner (except `extract` which uses real tempdirs with fixture archives).
3. **Ten modules** in this order: packages → gittools(lazygit) → starship → yazi → zsh → fonts → zellij → themes → arduinocli → shellconfig.

All module inputs (package lists, versions, URLs, plugin repos, shell-config blocks) are typed fields on `config.Config` populated from the embedded `defaults.yaml`. Overlay override plumbing already exists from Plan 1. Modules take their inputs as struct fields at construction time — no globals.

## Tech Stack

Go, existing `internal/platform` + `internal/module` + `internal/engine` + `internal/tui` packages. No new external dependencies expected beyond what Plan 1/2 pulled in.

## Files

### New — platform helpers

- `internal/platform/aur.go` + `aur_test.go`
  - `AURHelper` interface, `Yay` implementation.
  - `EnsureInstalled(ctx) error` — bootstraps yay from AUR via `git clone https://aur.archlinux.org/yay.git /tmp/... && makepkg -si --noconfirm` when missing.
  - `Install(ctx, pkgs []string) error` — `yay -S --needed --noconfirm <pkgs...>`.
  - Takes a `Runner` and a `PackageManager` (to check if `yay` itself is installed).

- `internal/platform/download.go` + `download_test.go`
  - `Download(ctx, url, destPath string, mode os.FileMode) error`.
  - Atomic-ish: write to `destPath+".tmp"` then rename. Clean up on error.
  - Tested with `httptest.Server`.

- `internal/platform/extract.go` + `extract_test.go`
  - `ExtractTarGz(ctx, archivePath, destDir string) error`.
  - `ExtractZip(ctx, archivePath, destDir string) error`.
  - Tested against real fixture archives in `testdata/`.

- `internal/platform/git.go` + `git_test.go`
  - `GitClient` struct taking a `Runner`.
  - `Clone(ctx, url, dest string) error`.
  - `EnsureRepo(ctx, url, dest string) error` — clone if `dest/.git` missing, otherwise noop.

- `internal/platform/textblock.go` + `textblock_test.go`
  - `EnsureBlock(path, marker, content string) error` — writes or replaces a block delimited by `# >>> marker >>>` / `# <<< marker <<<` markers. Creates the file if missing.
  - `RemoveBlock(path, marker string) error`.
  - `HasBlock(path, marker string) (bool, error)`.
  - Table-driven tests: insert, replace, remove, preserve surrounding content, missing-file, empty-file.

### New — modules

Each lives in its own package under `internal/modules/<name>/` with `<name>.go` + `<name>_test.go`.

- `packages` — installs base pacman package list from `cfg.Packages.Base`.
- `gittools` — installs lazygit (pacman). Named `gittools` to avoid collision with Go stdlib / pacman `git`.
- `starship` — installs starship (pacman).
- `yazi` — installs yazi (pacman).
- `zsh` — installs zsh (pacman) + clones oh-my-zsh + configured plugins via `gitclient`.
- `fonts` — installs AUR fonts (e.g. `ttf-jetbrains-mono-nerd`) via `AURHelper`. First action is `EnsureYayInstalled` if needed.
- `zellij` — installs zellij (pacman) + downloads config.
- `themes` — copies theme files from source directory (bundled under `lib/themes/` or overridable via `cfg.Themes.Source`).
- `arduinocli` — downloads arduino-cli tarball, extracts to `~/.local/bin`, runs `arduino-cli core install <cores...>` from `cfg.ArduinoCLI.Cores`.
- `shellconfig` — writes marker-delimited blocks into `~/.zshrc`, `~/.bashrc`, etc., using `textblock.EnsureBlock`. Blocks defined in `cfg.ShellConfig.Blocks`.

### Modified

- `internal/config/config.go` + `internal/config/defaults.yaml` — add typed fields:
  - `Packages.Base []string`
  - `Fonts []string`
  - `ArduinoCLI{Version string, URL string, Cores []string}`
  - `Starship{Version string}` (reserved; pacman install doesn't need it but overlay may)
  - `Zsh{OhMyZshRepo string, Plugins []struct{Name, Repo string}}`
  - `Zellij{ConfigURL string}`
  - `Themes{Source string}` (defaults to embedded `lib/themes/`)
  - `ShellConfig{Blocks []struct{Name, File, Content string}}`
- `internal/tui/wizard/wizard.go` — cache Detect+Plan per module; invalidate on selection toggle.
- Module registry (wherever `cmd/archduino/install.go` currently registers `hello`) — register the 10 new modules instead of / alongside `hello`.

## Module Contract Details

All modules follow the same shape:

- **Detect** — pure read. `PackageManager.IsInstalled` per pkg, `os.Stat` per file, `textblock.HasBlock` per marker. Returns a module-private `state` struct. Must be fast (wizard caches results, but Detect still shouldn't shell out more than necessary).
- **Plan** — given current state, returns `Plan{Actions: []Action}`. Empty actions = already converged (idempotent no-op). No side effects.
- **Apply** — executes each action sequentially, reporting progress via `Reporter.Progress(id, i, total, description)`.
- **Verify** — re-runs Detect and asserts convergence. Returns a descriptive error on mismatch.

Error semantics from the engine (`--halt-on-error` flag, sibling-on-failure continuation) apply unchanged.

### Module archetypes

1. **Pacman-only** (packages, gittools, starship, yazi, zellij base, themes deps if any): Detect = `IsInstalled` per pkg; Plan = install missing; Apply = `Pacman.Install`; Verify = all installed.
2. **AUR** (fonts): same as pacman-only but via `AURHelper`. Plan prepends an `EnsureYay` action if yay is not installed.
3. **Download + extract** (arduinocli): Detect = probe binary + `--version`; Plan = download + extract + symlink + `arduino-cli core install`; Verify = version string matches.
4. **Git-clone configs** (zsh oh-my-zsh + plugins, zellij config fetch if URL-based, themes if sourced from repo): Detect = check `.git` or file presence; Plan = `gitclient.EnsureRepo` or `Download`; Verify = path exists.
5. **Text-block writers** (shellconfig): Detect = `textblock.HasBlock` per block; Plan = `textblock.EnsureBlock`; Verify = re-scan.

## Testing Strategy

**Per-module tests (all unit, all fake-Runner-based):**

1. Detect with nothing installed → absent state.
2. Detect with everything installed → present state.
3. Plan(absent) → non-empty actions matching config inputs.
4. Plan(present) → empty actions (idempotent no-op).
5. Apply → records correct shell commands against fake Runner.
6. Verify after Apply → passes when fake reports success.

**Platform helper tests:**

- `aur_test.go` — yay bootstrap path (fake Runner sees `git clone` + `makepkg -si`), install path, already-installed short-circuit.
- `download_test.go` — `httptest.Server` for happy path + 404 + mid-download error cleanup.
- `extract_test.go` — real tar/zip fixtures in `testdata/` extracted into `t.TempDir()`.
- `git_test.go` — fake Runner for clone-if-missing, skip-if-present.
- `textblock_test.go` — table-driven: insert new, replace existing, remove, preserve surrounding content, missing-file, empty-file.

**Wizard caching test:** assert `Detect` is called once per module regardless of redraw count.

**No integration tests** that touch real pacman, real AUR, or the real network. That's Plan 4 (CI with Arch container). Manual smoke after plan completes.

## Non-Goals

- Plan 3b modules (neovim, renode, scaffold) — separate brainstorm.
- Subcommands beyond `install` (theme/new/doctor) — Plan 4.
- `bootstrap.sh`, goreleaser, CI — Plan 4.
- Debian/Fedora PackageManager implementations — Plan 4+.
- Integration tests against real package managers — Plan 4.

## Open Risks / Watchpoints

- **AUR bootstrap fragility** — if `makepkg -si --noconfirm` prompts despite `--noconfirm` (sudo password mid-build), the fake-Runner tests won't catch it. Manual smoke on fonts module is essential.
- **arduino-cli URL drift** — hardcoded version in `defaults.yaml` will go stale. Acceptable for v1; doctor subcommand in Plan 4 can warn.
- **Theme file source** — if themes ship bundled via Go `embed`, we need to decide that at module time. Default assumption: copy from `lib/themes/` on disk (same behavior as bash); switch to `embed` only if it's a clear win.