Epic: Feature-Based Architecture Migration for Bash Dotfiles

[ooloth]

Updated Migration Roadmap

Completed ✅

• SSH (features/ssh/) - PR feat: migrate SSH to feature-based architecture #46
• Git (features/git/) - PR Migrate Git feature to new architecture #50
• Homebrew (features/homebrew/) - PR Migrate Homebrew feature to new architecture #49

✅ INDEPENDENT FEATURES PHASE COMPLETE (5/5)

🎉 MAJOR MILESTONE: All independent features successfully migrated!

1. Node.js ✅ - PR feat: migrate Node.js to new feature folder architecture #56 (Self-contained, just needs nvm and npm)
2. Rust ✅ - PR feat: migrate Rust to new feature folder architecture #57 (Self-contained, just needs rustup and cargo)
3. Neovim ✅ - PR feat: migrate Neovim to new feature folder architecture #58 (Self-contained, config management only)
4. Tmux ✅ - PR feat: migrate tmux to new feature folder architecture #59 (Self-contained, config management only)
5. Zsh ✅ - PR feat: migrate Zsh to new feature folder architecture #60 (Self-contained, shell setup only)

Epic Status: 8/11 core features migrated using parallel 5-PR strategy ✅

🔄 NEXT PHASE: Machine-Dependent Features (2 remaining)

These require core utilities for machine detection (do after independent features):

• Yazi - Uses MACHINE detection
• macOS - Uses MACHINE detection (update script only)

Final Phase: Complex Dependencies (1 remaining)

These depend on multiple other features being migrated first:

• GitHub - Depends on Git + SSH (both already done)
• UV - Python package manager (minimal dependencies)
• Content - Depends on multiple tools being installed
• Settings - Depends on many features being configured

Strategy Success ✅

The dependency analysis showed only 2 features (SSH, Homebrew) had lib dependencies and both were migrated first. This enabled safe parallel development of 5 independent features without conflicts.

Phase Progress: Foundation (3/3) ✅ → Independent Features (5/5) ✅ → Machine-Dependent (0/2) → Complex Dependencies (0/1)

[ooloth]

Existing Draft PRs Ready for Review

From Phase 2 of the bash migration (completed July 12, 2025):

• PR Add zsh installation migration to bash #35: Zsh Installation Migration
• PR Add yazi installation migration to bash #36: Yazi Installation Migration
• PR Add content repository installation migration to bash #37: Content Installation Migration
• PR Add macOS settings installation migration to bash #38: Settings Installation Migration
• PR Add npm utilities extraction for shared package management #39: NPM Utilities Extraction
• PR Add macOS utilities extraction for system operations #40: macOS Utilities Extraction
• PR Add mode utilities extraction for file permission management #41: Mode Utilities Extraction
• PR Enhance error handling test suite with comprehensive coverage #42: Error Handling Test Suite Enhancement

All PRs have 148+ tests passing with zero shellcheck warnings.

Important Context

Critical Bug Fixed

• PR Fix Critical Setup.zsh Dependency Ordering Bug #14 (MERGED): Fixed critical setup.zsh bug where dotfiles were sourced before cloning
• Solution: Basic git check before clone, comprehensive utilities after clone (line 128+)

Established Patterns

• No dead code: Every function/utility must have demonstrated usage in the same PR
• Three-tier architecture:
  1. Core utilities (bash): lib/*-utils.bash - Pure logic, shellcheck compliant, fully tested
  2. Setup orchestration (bash): setup.bash - Calls utilities directly, professional tooling
  3. Interactive tools (zsh): bin/update/*.zsh - Thin wrappers, rich user experience

File Structure Pattern

lib/{component}-utils.bash                      # Utility functions
bin/install/{component}.bash                    # Installation script  
test/install/test-{component}-utils.bats        # Unit tests
test/install/test-{component}-installation.bats # Integration tests

[ooloth]

IMPORTANT: Architecture Update

The three-tier architecture pattern is now DEPRECATED. We are moving to a feature-based architecture instead.

❌ OLD Pattern (DO NOT USE)

The three-tier architecture that separated utilities, setup orchestration, and interactive tools is being replaced.

✅ NEW Pattern (USE THIS)

Feature-based architecture where each tool has its own self-contained folder:

features/{tool}/
├── install.bash      # Installation logic
├── update.bash       # Update logic (if applicable)
├── utils.bash        # Shared utilities
├── config/           # Tool-specific configs to symlink
├── tests/            # Feature-specific tests
└── README.md         # Feature documentation (optional)

All new development should follow the feature-based pattern described in this epic.