diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 25b2ecf..c22803f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,6 +1,6 @@ # Architecture: dev-setup -> **Last updated:** 2026-05-19 +> **Last updated:** 2026-08-09 --- @@ -38,7 +38,8 @@ dev-setup/ | | |---- setup.sh # Core Linux/macOS/WSL installer -- runs tools in order | | |---- uninstall.sh # Idempotent reverse of the installer | | |---- lib/ -| | | `---- log.sh # Shared log_info / log_ok / log_warn / log_error helpers +| | | |---- log.sh # Shared log_info / log_ok / log_warn / log_error helpers +| | | `---- tui.sh # Bash 3.2+ interactive picker | | `---- tools/ # Per-tool installers (sourced by core in dependency order) | | |---- auth.sh # GitHub CLI authentication (interactive) | | |---- copilot-cli.sh # Install GitHub Copilot CLI (pin from .tool-versions) @@ -52,8 +53,9 @@ dev-setup/ | |---- uninstall.ps1 # Idempotent reverse of the installer | |---- lib/ | | |---- logging.ps1 # Write-Info / Write-Ok / Write-Warn / Write-Err + Assert-LastExit -| | `---- path.ps1 # Refresh-SessionPath -- re-reads Machine+User PATH from registry -| `---- tools/ # Per-tool installers (orchestrator + 10 modules) +| | |---- path.ps1 # Refresh-SessionPath -- re-reads Machine+User PATH from registry +| | `---- tui.ps1 # PS 5.1-safe ASCII picker + ordered resolver +| `---- tools/ # Per-tool installer modules | |---- auth.ps1 # GitHub CLI authentication (interactive) | |---- copilot.ps1 # GitHub Copilot CLI (pin from .tool-versions) | |---- dotfiles.ps1 # Apply config/dotfiles/ on Windows @@ -91,8 +93,12 @@ dev-setup/ | |---- test_nvm_bootstrap.sh # nvm bootstrap tests | |---- test_precommit_hygiene.sh # pre-commit hygiene checks (ancestry, ASCII, rogue-path) | |---- test_remove_custom_item.ps1 # Custom item removal tests (PowerShell) +| |---- test_setup_flags.sh # Bash selection flags + interactive guards +| |---- test_setup_flags_pwsh.ps1 # PowerShell selection flags + interactive guards | |---- test_shared_logging.sh # scripts/linux/lib/log.sh contract tests | |---- test_tool_versions.sh # .tool-versions parser + Get-ToolVersion contract tests +| |---- test_tui_bash.sh # Bash picker + ordered selection tests +| |---- test_tui_pwsh.ps1 # PowerShell picker + resolver tests | `---- test_windows_setup.ps1 # Windows setup tests (PowerShell) | |---- .devcontainer/ @@ -165,6 +171,30 @@ Uses PowerShell's built-in `$IsWindows`, `$IsLinux`, `$IsMacOS` booleans. If Pow --- +## Tool Selection Architecture + +The public picker contract, including invocation, controls, headless behavior, flag precedence, +and confirm/cancel results, is documented in the +[README interactive picker section](./README.md#interactive-tool-picker). + +Internally, selection is separated from installation: + +1. `scripts/linux/setup.sh` and `scripts/windows/setup.ps1` own argument handling, interactive + eligibility, validation, and final dispatch. +2. `scripts/linux/lib/tui.sh` and `scripts/windows/lib/tui.ps1` own menu state, rendering, and key + handling. They return selected tool names but never install tools. +3. The selected names flow through the same ordered resolver used by `--only` / `-Only`. +4. The resolver iterates the default-tool sequence first, then appends selected opt-in tools + alphabetically. Menu display order, user input order, and flag input order cannot reorder + dependency-sensitive defaults. +5. Cancellation or an empty confirmed selection exits before dispatch. + +The default arrays are the authoritative install-order definitions. A tool module that is +available but absent from the default array remains opt-in and is never added to a no-argument +headless run. + +--- + ## Script Conventions Shared helpers live in dedicated `lib/` directories. Tool scripts **load** them rather than redefining or copy-pasting. Source of truth: @@ -172,8 +202,10 @@ Shared helpers live in dedicated `lib/` directories. Tool scripts **load** them | File | Purpose | Loaded by | |--------------------------------------|------------------------------------------------------------------------------------------|----------------------------------------------| | `scripts/linux/lib/log.sh` | `log_info`, `log_ok`, `log_warn`, `log_error` | `setup.sh` and every `tools/*.sh` | +| `scripts/linux/lib/tui.sh` | Bash 3.2+ interactive picker and menu state | `scripts/linux/setup.sh` | | `scripts/windows/lib/logging.ps1` | `Write-Info`, `Write-Ok`, `Write-Warn`, `Write-Err`, `Assert-LastExit` | `setup.ps1` and every `tools/*.ps1` | | `scripts/windows/lib/path.ps1` | `Refresh-SessionPath` (re-reads Machine + User PATH from the registry into the session) | `setup.ps1` and any tool that mutates PATH | +| `scripts/windows/lib/tui.ps1` | PS 5.1-safe ASCII picker and `Resolve-FinalToolset` | `scripts/windows/setup.ps1` | | `scripts/lib/read-tool-version.sh` | POSIX parser for `.tool-versions` (prints the pinned version to stdout) | Any `tools/*.sh` that needs a pinned version | | `scripts/lib/Read-ToolVersion.ps1` | PowerShell `Get-ToolVersion -Name ` (returns the pinned version) | Any `tools/*.ps1` that needs a pinned version | @@ -186,12 +218,13 @@ Shared helpers live in dedicated `lib/` directories. Tool scripts **load** them ```bash # From scripts/linux/setup.sh (lib is one level down): . "$(dirname "${BASH_SOURCE[0]}")/lib/log.sh" +. "$(dirname "${BASH_SOURCE[0]}")/lib/tui.sh" # From scripts/linux/tools/.sh (lib is one level up): . "$(dirname "${BASH_SOURCE[0]}")/../lib/log.sh" ``` -Note that `setup.sh` runs each `tools/*.sh` via `bash