From 1518221d294db18dd889f7ee6c296f098e9bde7b Mon Sep 17 00:00:00 2001 From: "Earl Tankard, Jr., Ph.D" Date: Sun, 12 Jul 2026 20:06:51 -0400 Subject: [PATCH] docs(readme)+ci: WI-4 selective-install docs + flag e2e/validate smoke steps (#468) - README.md: Add "Selective Install" section documenting all four flags (--list/--help/--only/--skip) with concrete examples for both setup.sh (Linux/macOS/WSL) and setup.ps1 (Windows). Includes the verified caveat that --only does NOT auto-include prerequisites (e.g. --only=nvm installs only nvm, not prereqs/uv). Documents --only/--skip mutual exclusion and --list precedence. - .github/workflows/e2e-install.yml: Add --list and --only smoke steps to e2e-linux, e2e-macos, and e2e-windows jobs via root entrypoints (setup.sh --only=zsh on *nix; setup.ps1 -Only 'vim' on Windows). Steps run after the full default install (idempotent, fast). - .github/workflows/validate.yml: Add flag-test steps to validate-linux (--list + --only=zsh), validate-macos (--list smoke), validate-powershell (-List), and validate-ps51 (-List under shell: powershell). WI-4 is the final slice of #468 (flags-first customizable install). Prompt/manifest deferred to issue #495 (Phase 2, blocked-by #468). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/e2e-install.yml | 21 ++++++++++ .github/workflows/validate.yml | 18 +++++++++ README.md | 65 +++++++++++++++++++++++++++++++ 3 files changed, 104 insertions(+) diff --git a/.github/workflows/e2e-install.yml b/.github/workflows/e2e-install.yml index e650fbe..eab2704 100644 --- a/.github/workflows/e2e-install.yml +++ b/.github/workflows/e2e-install.yml @@ -97,6 +97,13 @@ jobs: echo "All Linux assertions passed" ' + # -- Flag smoke tests -- + - name: Flag smoke - --list (Linux) + run: bash setup.sh --list + + - name: Flag smoke - --only (Linux) + run: bash setup.sh --only=zsh + # -- Step 3: Idempotency -- - name: Idempotency (second run) run: | @@ -238,6 +245,13 @@ jobs: echo "All macOS assertions passed" ' + # -- Flag smoke tests -- + - name: Flag smoke - --list (macOS) + run: bash setup.sh --list + + - name: Flag smoke - --only (macOS) + run: bash setup.sh --only=zsh + # -- Step 3: Idempotency -- - name: Idempotency (second run) run: | @@ -393,6 +407,13 @@ jobs: Write-Host "`nAll Windows assertions passed" } + # -- Flag smoke tests -- + - name: Flag smoke - -List (Windows) + run: .\setup.ps1 -List + + - name: Flag smoke - -Only (Windows) + run: .\setup.ps1 -Only 'vim' + # -- Step 3: Idempotency -- - name: Idempotency (second run) run: | diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index e6cb0d0..d0c2a30 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -100,6 +100,12 @@ jobs: - name: Run tool version tests run: bash tests/test_tool_versions.sh + - name: Flag test - --list (Linux) + run: bash setup.sh --list + + - name: Flag test - --only (Linux) + run: bash setup.sh --only=zsh + validate-macos: name: Validate macOS Setup runs-on: macos-latest @@ -194,6 +200,9 @@ jobs: - name: Run pre-commit hygiene tests run: bash tests/test_precommit_hygiene.sh + - name: Flag smoke - --list (macOS) + run: bash setup.sh --list + lint-shell-scripts: name: Lint Shell Scripts runs-on: ubuntu-latest @@ -264,6 +273,9 @@ jobs: - name: Run sprint-end labels tests run: pwsh tests/test_sprint_end_labels.ps1 + - name: Flag test - -List (PowerShell) + run: .\setup.ps1 -List + validate-ps51: name: Validate PowerShell 5.1 Compatibility runs-on: windows-latest @@ -352,3 +364,9 @@ jobs: shell: powershell run: | powershell -ExecutionPolicy Bypass -File tests\test_sprint_end_labels_pwsh.ps1 + + - name: Flag test - -List (PS 5.1) + shell: powershell + run: | + .\setup.ps1 -List + Write-Host "Flag -List OK (PS 5.1)" diff --git a/README.md b/README.md index e7e85ec..fcc86b9 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,71 @@ powershell -ExecutionPolicy Bypass -File setup.ps1 No action needed. Setup runs automatically on container creation via the `postCreateCommand` hook. +## Selective Install + +By default, `setup.sh` / `setup.ps1` installs all tools in the defined order. Use flags to control +which tools run without editing the scripts. + +### Available Flags + +| Flag | Linux / macOS / WSL | Windows | +|------|---------------------|---------| +| List available tools, exit (no install) | `--list` | `-List` | +| Print usage, exit | `--help` | `-Help` | +| Install only the named tools | `--only=a,b,c` | `-Only 'a,b,c'` | +| Install all defaults except named tools | `--skip=a,b,c` | `-Skip 'a,b,c'` | + +### Linux / macOS / WSL Examples + +```bash +# List all selectable tool names +./setup.sh --list + +# Print usage +./setup.sh --help + +# Install only zsh and uv +./setup.sh --only=zsh,uv + +# Install everything except auth and copilot-cli +./setup.sh --skip=auth,copilot-cli +``` + +### Windows Examples + +```powershell +# List all selectable tool names +.\setup.ps1 -List + +# Print usage +.\setup.ps1 -Help + +# Install only vim and gh +.\setup.ps1 -Only 'vim,gh' + +# Install everything except auth and copilot-cli +.\setup.ps1 -Skip 'auth,copilot-cli' +``` + +### Caveats + +**`--only` / `-Only` does not auto-include prerequisites.** Selecting `--only=nvm` installs +only nvm -- its prerequisite tools (`prereqs`, `zsh`, `uv`) are not pulled in automatically. +If a tool depends on earlier steps, list all required tools explicitly: + +```bash +# Correct: include prereqs before nvm +./setup.sh --only=prereqs,uv,nvm +``` + +**`--only` and `--skip` are mutually exclusive.** Combining both flags exits with an error. + +**`--list` takes precedence.** If `--list` is passed alongside `--only` or `--skip`, the tool +list is printed and setup exits without installing anything. + +Tool names are validated against the available list. An unknown name exits with an error and +prints the available tools. Use `--list` / `-List` to see valid names before running. + ## Post-Setup Steps After running setup, complete these steps to activate your tools: