Automate Safety Net via CI/CD E2E Multi-Platform Pipeline

[informaticadiaz]

Description / Problem Statement:
Currently, Gentleman.Dots has an incredibly robust set of E2E verification tests using Docker (docker-test.sh & e2e_test.sh). However, these are handled manually, relying on local developers to verify against regressions before merging PRs. This creates workflow friction, enables "it works on my machine" pitfalls, and leaves a massive testing blindspot for macOS since Docker natively tests Linux variants.

Proposal (SDD Spec):
I would like to architect and implement an automated GitHub Actions workflow (.github/workflows/e2e-testing.yml) that acts as a mandatory gate for all Pull Requests and heavy commits to main.

Technical Approach / Deliverables:

1. Linux Container Matrix Job: Leverage the existing, mature Docker setups in installer/e2e to run automated non-interactive validations across a parallel matrix slice: [ubuntu, debian, fedora, alpine, termux].
2. macOS Native Ephemeral Job: Spin up a macos-latest GitHub runner to compile the custom Go binaries and execute the core installation logic locally over the OS filesystem to prevent Apple-specific architecture lock-ups.
3. Go Build Caching: Create proper cache restoration points for go mod files to ensure our pipeline executes blazingly fast without eating GitHub minute quotas.

Value Added:
This inherently protects the codebase from shipping corrupted dotfile installers breaking our active user base's environments. It brings immediate QA scaling without shifting the burden heavily onto the core maintainers.

I'd gladly take ownership of building this workflow cleanly. If this resonates with the vision of the repo, I'll branch out and open a Draft PR shortly.

[m13v]

the macos-latest runner approach for the Apple side is solid, but heads up that GitHub Actions macOS runners have limited disk space and the Go build cache can fill it surprisingly fast if you are compiling multiple binaries per matrix entry. we ran into this when our CI started failing silently because the runner ran out of space mid-build. for the Linux Docker matrix, running ubuntu/debian/fedora/alpine in parallel is great but termux is a different beast entirely, its package ecosystem and PATH setup will need special handling. consider making termux a separate optional job that does not block the PR gate initially. also for the Go build caching across the matrix, actions/cache with a key that includes the OS and Go version prevents cache collisions between the Linux and macOS jobs.

[m13v]

for managing parallel test runs across the matrix jobs, we open-sourced a browser lock script that prevents concurrent Playwright instances from interfering with each other: https://github.com/m13v/browser-lock/blob/main/playwright-lock.sh - different context (browser tests vs installer tests) but the concurrency locking pattern applies whenever multiple CI jobs share state.

[informaticadiaz]

Excellent feedback @m13v 🙏. I've analyzed the repository and want to develop a robust strategy for the disk space problem.

### 🔍 **Cache Analysis in Gentleman.Dots**

I've identified that our `go.mod` has:
- **2 direct dependencies**: `charmbracelet/bubbletea`, `charmbracelet/lipgloss`
- **~26 indirect dependencies** (golang.org/x/sys, golang.org/x/text, etc.)
- **Go 1.25.1** as required version

And in release compilation (`docs/contributing.md`):
```bash
# 4 cross-platform compilations
GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -o gentleman-installer-darwin-amd64
GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o gentleman-installer-darwin-arm64
GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o gentleman-installer-linux-amd64
GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o gentleman-installer-linux-arm64

⚙️ Proposed Cache Strategy

For macOS (macos-latest):

1. Granular cache by OS+Arch:

- name: Restore Go cache (macOS)
  uses: actions/cache@v4
  with:
    path: ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('installer/go.sum') }}
    restore-keys: |
      ${{ runner.os }}-go-

2. Compile selectively (only native arm64 on macOS runner):

# Instead of compiling both amd64 + arm64 on macOS
GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o gentleman-installer-darwin-arm64 ./cmd/gentleman-installer

3. Aggressive cache cleanup after compilation:

go clean -cache -modcache -testcache
du -sh ~/go/pkg/mod  # Monitor space

4. Disk space monitoring before/after:

- name: Check disk space before build
  run: df -h /
  
- name: Build (macOS arm64 only)
  run: |
    cd installer
    GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o gentleman-installer-darwin-arm64 ./cmd/gentleman-installer
    
- name: Check disk space after build
  run: df -h /
    
- name: Clean Go cache
  run: go clean -cache -modcache -testcache

For Linux Docker (parallel matrix):

• Binary compilations for Linux happen inside each container (not on the runner)
• This isolates the cache per distro and prevents pollution between jobs
• Each container has its own ephemeral go mod cache

🔑 Strategy Summary

Component	Strategy
macOS	Cache by OS, compile only arm64, aggressive cleanup
Linux	Compilations encapsulated in Docker, cache isolated per container
Go Modules	Single cache entry with go.sum hash, deterministic key
Monitoring	Report disk space before/after to detect issues early

✅ Benefits

• ✅ Prevents cache collisions between Linux/macOS
• ✅ Avoids shared cache conflicts
• ✅ Prevents disk saturation on macOS runners
• ✅ Eliminates redundant compilations
• ✅ Makes CI pipeline reproducible and debuggable

I can open a Draft PR with the complete workflow implementation if this approach resonates with you.

[m13v]

good analysis on the cache situation. 26 indirect deps with 4 cross-platform compilations can balloon the CI cache fast. one thing that helped us: cache the Go module download separately from the build cache, and key the build cache on GOOS+GOARCH so cross-platform builds don't invalidate each other. also worth checking if you can skip the arm64 linux build if nobody is actually deploying to arm64, that alone cuts build time significantly.

[Alan-TheGentleman]

Propuesta sólida. La matriz Docker ya está, solo hay que automatizarla. Consideraciones para el PR:

• Termux como job opcional (no bloqueante del gate)
• Cache por OS+GOARCH para evitar colisiones
• El job de macOS solo necesita compilar darwin-arm64 en el runner

Aprobado. Si querés abrir un Draft PR, adelante.