GitHub Installation Testing (Bash Migration)

.claude/tasks/2025-07-06-setup-improvements.md

@@ -4,8 +4,9 @@
 
 **Task**: Improve reliability and testability of dotfiles setup process through TDD approach
 **Total PRs Planned**: 10 PRs + 2 Infrastructure PRs
-**Completed**: 8 PRs (including SSH Installation Testing)
-**Current**: Working on Infrastructure Improvements (PR 8.1 & 8.2)
+**Completed**: 8 PRs (including SSH Installation Testing + Infrastructure PRs)
+**Current**: Bash migration experiment (see bash-migration task file)
+**Critical Issue Discovered**: setup.zsh references $DOTFILES files before repo is cloned - needs urgent fix
 
 ## Completed PRs
 
@@ -56,16 +57,16 @@
 - **Functions**: `detect_ssh_keys()`, `ssh_key_pair_found()`, centralized path configuration
 - **Improvements**: Post-implementation refactoring, dead code elimination, enhanced CLAUDE.md guidelines
 
-## Infrastructure Improvements (In Progress)
+## Infrastructure Improvements (Completed)
 
-### 🔄 PR 8.1: Pull Request Template (In Progress)
+### ✅ PR 8.1: Pull Request Template (Merged)
 - **Goal**: Standardize PR descriptions using established patterns from successful PRs
 - **Implementation**: `.github/PULL_REQUEST_TEMPLATE.md` with structured sections
 - **Features**: Clean What/Why/Usage/Validation/Links structure with clear guidance comments
 - **Benefits**: Consistent PR format, reduced cognitive load, cross-project template reference
-- **Status**: Enhanced with emoji headings, refined comments, and CLAUDE.md guidelines
+- **Status**: Enhanced with emoji headings, refined comments, and CLAUDE.md guidelines - merged
 
-### ✅ PR 8.2: GitHub Actions CI (Completed)
+### ✅ PR 8.2: GitHub Actions CI (Merged)
 - **Goal**: Automatic test execution on PRs with GitHub UI status indicators
 - **Implementation**: `.github/workflows/test-dotfiles.yml` using existing test infrastructure
 - **Features**: macOS runner, zsh shell, smart path triggering, existing test/run-tests.zsh integration

.claude/tasks/2025-07-07-bash-migration.md

@@ -0,0 +1,163 @@
+# Bash Migration Epic
+
+## Current Status (July 7, 2025)
+
+**Task**: Migrate dotfiles installation scripts from custom zsh test framework to industry-standard bash + shellcheck + bats
+**Approach**: Complete 3-phase migration for better tooling, maintainability, and reliability
+**Current**: Phase 1 - PR #13 (GitHub Installation Testing) in draft review
+
+## Migration Strategy
+
+### Phase 1: Demonstrate Complete Migration Pattern (In Progress)
+**Goal**: Create one complete bash + bats example to establish the migration pattern
+
+#### 🔄 PR #13: GitHub Installation Testing (Draft)
+- **Files Created**:
+  - `lib/github-utils.bash` - GitHub SSH utilities (shellcheck clean)
+  - `bin/install/github.bash` - Bash replacement for github.zsh
+  - `test/install/test-github-utils.bats` - 14 utility function tests
+  - `test/install/test-github-installation.bats` - 6 integration tests
+  - `experiment/bash-testing/` - Comparison docs and examples
+- **Test Results**: All 20 tests passing, shellcheck compliance verified
+- **Benefits Demonstrated**: Better error catching, industry-standard tooling, cleaner syntax
+- **Status**: Ready for review, includes CLAUDE.md improvements for PR workflow
+
+### Phase 2: Systematic Script Migration (Pending)
+**Goal**: Migrate remaining installation scripts one-by-one using established pattern
+
+**Priority Order**:
+1. `bin/install/ssh.bash` - Critical dependency for GitHub operations
+2. `bin/install/homebrew.bash` - Foundation for all other tools
+3. `bin/install/node.bash` - Programming language setup
+4. Remaining scripts based on dependency analysis
+
+**Pattern per Script**:
+- Create `lib/{script}-utils.bash` with shellcheck compliance
+- Create comprehensive bats test suite
+- Migrate main installation script to bash
+- Verify feature parity with original zsh version
+- Update integration points
+
+### Phase 3: Framework Cleanup (Pending)
+**Goal**: Remove zsh test framework and update CI
+
+**Tasks**:
+- Update `.github/workflows/test-dotfiles.yml` to use bats instead of custom runner
+- Remove `test/run-tests.zsh` and custom zsh test utilities
+- Update documentation to reflect bash-first approach
+- Archive zsh test framework with migration notes
+
+## Key Decisions Made
+
+### Bash + Shellcheck + Bats Stack
+- **Bash**: Universal, better CI support, consistent behavior
+- **Shellcheck**: Industry-standard linting, catches common errors
+- **Bats**: Mature testing framework, wide adoption, good GitHub Actions support
+
+### Migration Approach: Complete Examples First
+- **Rejected**: Hybrid approach (keep scripts in zsh, tests in bash)
+- **Chosen**: Full migration with complete working examples
+- **Reasoning**: Cleaner long-term solution, better tooling ecosystem
+
+### Test Coverage Standards
+- **Utilities**: Comprehensive unit tests for all functions
+- **Integration**: End-to-end workflow testing with mocking
+- **Compliance**: All bash scripts must pass shellcheck with zero warnings
+- **Behavioral Focus**: Test what code does, not implementation details
+
+## Technical Patterns Established
+
+### 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
+```
+
+### Bash Script Standards
+- `#!/usr/bin/env bash` shebang
+- `set -euo pipefail` strict mode
+- Shellcheck compliance (zero warnings)
+- Function documentation with usage examples
+- Proper error handling and user feedback
+
+### Test Standards
+- Comprehensive test coverage (both success and failure paths)
+- Environment isolation with setup/teardown
+- Mocking of external dependencies
+- Clear test descriptions and assertions
+- Integration tests that verify complete workflows
+
+## Integration Points
+
+### CI/CD Pipeline
+- GitHub Actions currently uses custom zsh test runner
+- **Future**: Migrate to bats with better reporting and parallelization
+- **Benefit**: Standard test output format, better integration with GitHub UI
+
+### Existing Zsh Infrastructure
+- **Preserve**: Current zsh configuration and shell setup (user-facing)
+- **Migrate**: Only installation and testing scripts (development tooling)
+- **Benefit**: Users keep familiar shell while development gets better tools
+
+## Discovered Issues
+
+### Critical Setup.zsh Bug
+**Issue**: `setup.zsh` references `$DOTFILES` files via `source` commands before the dotfiles repository is cloned
+**Impact**: Setup process fails on fresh installations
+**Priority**: High - affects core functionality
+**Next Steps**: Fix in separate PR after current bash migration PR is reviewed
+
+### Dead Code Prevention
+**Pattern**: Every function/utility must have demonstrated usage in the same PR
+**Enforcement**: CLAUDE.md updated with strict guidelines
+**Benefit**: Prevents speculative code that becomes maintenance burden
+
+## Success Metrics
+
+### Phase 1 (Current)
+- ✅ 20 comprehensive tests passing
+- ✅ Zero shellcheck warnings
+- ✅ Feature parity with original zsh scripts
+- ✅ Complete behavior bundle (utilities + tests + integration + usage)
+- 🔄 User review and approval
+
+### Phase 2 (Future)
+- All installation scripts migrated to bash
+- Comprehensive bats test coverage
+- CI pipeline updated to use bats
+- Documentation updated
+
+### Phase 3 (Future)
+- Custom zsh test framework removed
+- Clean codebase with single testing approach
+- Improved developer experience with standard tooling
+
+## Development Workflow
+
+### Current Process
+1. Create utilities with shellcheck compliance
+2. Write comprehensive bats tests (unit + integration)
+3. Implement installation script in bash
+4. Verify feature parity and test coverage
+5. Create draft PR for review iteration
+6. Update task documentation with progress
+
+### Quality Gates
+- All bats tests must pass
+- Zero shellcheck warnings allowed
+- Feature parity verification required
+- Complete behavior bundle (no dead code)
+
+## Next Steps After PR #13 Review
+
+1. **Address Review Feedback**: Incorporate any requested changes
+2. **Fix Critical Setup Bug**: Resolve $DOTFILES dependency issue  
+3. **Continue Phase 1**: SSH installation script migration
+4. **Plan Phase 2**: Define systematic migration order
+5. **Update CI**: Begin migration to bats-based testing
+
+---
+
+*This epic represents a significant infrastructure improvement that will provide better development tools, more reliable testing, and easier maintenance for the dotfiles project.*

bin/install/github.bash

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+
+# GitHub SSH setup and repository configuration
+# Handles adding SSH keys to GitHub and converting HTTPS remotes to SSH
+
+set -euo pipefail
+
+# Configuration
+DOTFILES="${DOTFILES:-$HOME/Repos/ooloth/dotfiles}"
+PRIVATE_KEY="$HOME/.ssh/id_rsa"
+PUBLIC_KEY="$PRIVATE_KEY.pub"
+
+# Load utilities
+# shellcheck source=../../lib/github-utils.bash
+source "$DOTFILES/lib/github-utils.bash"
+
+# All needed utilities are now available in github-utils.bash
+
+main() {
+    echo "🔑 Adding SSH key pair to GitHub"
+
+    # Check if GitHub SSH connection already works
+    if github_ssh_connection_works; then
+        echo "✅ You can already connect to GitHub via SSH."
+        return 0
+    fi
+
+    # Verify SSH keys exist
+    if ! ssh_keys_exist; then
+        echo "❌ SSH keys not found. Please run the SSH installation script first."
+        echo "Run: source $DOTFILES/bin/install/ssh.zsh"
+        return 1
+    fi
+
+    # Verify SSH keys are loaded in agent
+    if ! ssh_keys_in_agent; then
+        echo "❌ SSH keys not loaded in ssh-agent. Please add them first."
+        echo "Run: ssh-add $PRIVATE_KEY"
+        return 1
+    fi
+
+    # Display public key for user to add to GitHub
+    echo ""
+    echo "Your turn!"
+    echo "Please visit https://github.com/settings/ssh/new now and add the following SSH key to your GitHub account:"
+    echo ""
+    cat "$PUBLIC_KEY"
+    echo ""
+    echo "Actually go do this! This step is required before you'll be able to clone repos via SSH."
+    echo ""
+
+    # Wait for user confirmation (interactive step)
+    echo -n "All set? (y/N): "
+    read -r github_key_added
+
+    if [[ "$github_key_added" != "y" && "$github_key_added" != "Y" ]]; then
+        echo "You have chosen...poorly."
+        return 0
+    else
+        echo "Excellent!"
+    fi
+
+    # Verify GitHub SSH connection now works
+    echo ""
+    echo "🧪 Verifying you can now connect to GitHub via SSH..."
+
+    if github_ssh_connection_works; then
+        echo "✅ SSH key was added to GitHub successfully."
+    else
+        echo "❌ Failed to connect to GitHub via SSH. Please verify the key was added correctly."
+        echo "Visit: https://github.com/settings/keys"
+        return 1
+    fi
+
+    # Convert dotfiles remote from HTTPS to SSH if needed
+    convert_dotfiles_remote_to_ssh
+
+    echo ""
+    echo "🚀 Done adding your SSH key pair to GitHub."
+}
+
+convert_dotfiles_remote_to_ssh() {
+    local dotfiles_dir="$DOTFILES"
+
+    # Check if dotfiles directory exists
+    if [[ ! -d "$dotfiles_dir" ]]; then
+        echo "⚠️  Dotfiles directory not found at $dotfiles_dir"
+        return 0
+    fi
+
+    # Get current remote URL
+    local current_url
+    if ! current_url=$(get_git_remote_url "$dotfiles_dir"); then
+        echo "⚠️  Could not get git remote URL for dotfiles"
+        return 0
+    fi
+
+    # Check if remote uses HTTPS
+    if is_https_remote "$current_url"; then
+        echo ""
+        echo "🔗 Converting the dotfiles remote URL from HTTPS to SSH"
+
+        local ssh_url
+        ssh_url=$(convert_https_to_ssh "$current_url")
+
+        if set_git_remote_url "$dotfiles_dir" "$ssh_url"; then
+            echo "✅ Dotfiles remote URL has been updated to use SSH"
+        else
+            echo "❌ Failed to update dotfiles remote URL"
+            return 1
+        fi
+    else
+        echo "✅ Dotfiles remote URL already uses SSH"
+    fi
+}
+
+# Run main function if script is executed directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi