Dotfiles update 2025-12-25 12:04
This commit is contained in:
Aaron D. Lee
258
REFACTORING-GUIDE.md
Normal file
258
REFACTORING-GUIDE.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Dotfiles Refactoring Guide
|
||||
|
||||
This document explains the refactoring changes made to eliminate code duplication and improve maintainability.
|
||||
|
||||
## Summary of Changes
|
||||
|
||||
| Change | Impact | Lines Saved |
|
||||
|--------|--------|-------------|
|
||||
| Centralized header with `bootstrap.zsh` | All scripts use one source pattern | ~150 lines |
|
||||
| Template-driven Python projects | `python-templates.zsh` refactored | ~60 lines |
|
||||
| Unified config/color loading | Single entry point for dependencies | ~80 lines |
|
||||
|
||||
**Total estimated reduction: ~290 lines of duplicated code**
|
||||
|
||||
---
|
||||
|
||||
## 1. New File: `zsh/lib/bootstrap.zsh`
|
||||
|
||||
### Purpose
|
||||
Single entry point for all scripts to source. Handles loading config, colors, and utils in the correct order with proper fallbacks.
|
||||
|
||||
### Usage
|
||||
|
||||
**In bash scripts:**
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source "${DOTFILES_HOME:-$HOME/.dotfiles}/zsh/lib/bootstrap.zsh" 2>/dev/null || {
|
||||
# Minimal fallback only if bootstrap unavailable
|
||||
df_print_header() { echo "=== $1 ==="; }
|
||||
}
|
||||
```
|
||||
|
||||
**In zsh functions:**
|
||||
```zsh
|
||||
source "${0:A:h}/../lib/bootstrap.zsh" 2>/dev/null || \
|
||||
source "$HOME/.dotfiles/zsh/lib/bootstrap.zsh" 2>/dev/null
|
||||
```
|
||||
|
||||
### What It Provides
|
||||
After sourcing `bootstrap.zsh`, you have access to:
|
||||
- All `DF_*` color variables
|
||||
- All `df_print_*` functions
|
||||
- All `df_*` utility functions
|
||||
- All config variables from `dotfiles.conf`
|
||||
|
||||
---
|
||||
|
||||
## 2. Enhanced: `zsh/lib/utils.zsh`
|
||||
|
||||
### New Functions Added
|
||||
|
||||
```zsh
|
||||
# Build a horizontal line
|
||||
_df_hline "═" 66 # Returns: ══════════...
|
||||
|
||||
# Print MOTD-style header for scripts
|
||||
df_print_header "script-name"
|
||||
# Output:
|
||||
# ╒══════════════════════════════════════════════════════════════════╕
|
||||
# │ ✦ user@hostname script-name Thu Dec 25 14:30 │
|
||||
# ╘══════════════════════════════════════════════════════════════════╛
|
||||
|
||||
# Print simpler header for functions
|
||||
df_print_func_name "Function Name"
|
||||
# Output:
|
||||
# ╒══════════════════════════════════════════════════════════════════╕
|
||||
# │ Function Name Thu Dec 25 14:30 │
|
||||
# ╘══════════════════════════════════════════════════════════════════╛
|
||||
|
||||
# Print divider line
|
||||
df_print_divider
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Refactored: `zsh/functions/python-templates.zsh`
|
||||
|
||||
### Before (Duplicated Pattern)
|
||||
Each function repeated ~15 lines:
|
||||
```zsh
|
||||
py-flask() {
|
||||
_py_check_name "$1" || return 1
|
||||
df_print_func_name "Flask Project: $1"
|
||||
mkdir -p "$1"/{app,tests}
|
||||
# ... flask-specific setup ...
|
||||
_py_venv "$1"
|
||||
_py_gitignore "$1"
|
||||
_py_git "$1"
|
||||
df_print_success "Created: $1"
|
||||
_py_next "$1"
|
||||
}
|
||||
```
|
||||
|
||||
### After (Template-Driven)
|
||||
```zsh
|
||||
# Common creation function handles all boilerplate
|
||||
_py_create_project() {
|
||||
local name="$1" template="$2" display_name="$3" extra_info="$4"
|
||||
|
||||
_py_check_name "$name" || return 1
|
||||
df_print_func_name "${display_name}: ${name}"
|
||||
mkdir -p "$name"
|
||||
|
||||
# Run template-specific setup
|
||||
local packages=$("_py_template_${template}" "$name")
|
||||
|
||||
# Common finalization
|
||||
_py_venv "$name"
|
||||
[[ -n "$packages" ]] && _py_install "$name" $packages
|
||||
_py_gitignore "$name"
|
||||
_py_git "$name"
|
||||
df_print_success "Created: $name"
|
||||
_py_next_steps "$name" "$extra_info"
|
||||
}
|
||||
|
||||
# Each public function is now one line
|
||||
py-flask() { _py_create_project "$1" "flask" "Flask Project" "Run: python app.py"; }
|
||||
py-fastapi() { _py_create_project "$1" "fastapi" "FastAPI Project" "Docs: localhost:8000/docs"; }
|
||||
```
|
||||
|
||||
### New Features Added
|
||||
- `py-templates` - List all available templates
|
||||
- Better pyproject.toml support for CLI projects
|
||||
- Improved file templates with more comments
|
||||
|
||||
---
|
||||
|
||||
## 4. Refactored Bin Scripts
|
||||
|
||||
All scripts in `bin/` now follow this pattern:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# ============================================================================
|
||||
# Script Name
|
||||
# ============================================================================
|
||||
|
||||
# Source bootstrap (provides colors, config, and utility functions)
|
||||
source "${DOTFILES_HOME:-$HOME/.dotfiles}/zsh/lib/bootstrap.zsh" 2>/dev/null || {
|
||||
# Minimal fallback if bootstrap unavailable
|
||||
DF_GREEN=$'\033[0;32m' DF_NC=$'\033[0m'
|
||||
df_print_header() { echo "=== $1 ==="; }
|
||||
df_print_success() { echo -e "${DF_GREEN}✓${DF_NC} $1"; }
|
||||
}
|
||||
|
||||
# Script logic...
|
||||
|
||||
main() {
|
||||
df_print_header "script-name"
|
||||
# ...
|
||||
}
|
||||
|
||||
main "$@"
|
||||
```
|
||||
|
||||
### Scripts Updated
|
||||
- `dotfiles-doctor.sh`
|
||||
- `dotfiles-sync.sh`
|
||||
- `dotfiles-update.sh`
|
||||
- `dotfiles-version.sh`
|
||||
- `dotfiles-stats.sh`
|
||||
- `dotfiles-vault.sh`
|
||||
- `dotfiles-compile.sh`
|
||||
- `setup/setup-espanso.sh`
|
||||
- `setup/setup-wizard.sh`
|
||||
|
||||
---
|
||||
|
||||
## How to Apply These Changes
|
||||
|
||||
### Option 1: Replace Files
|
||||
Copy the refactored files over your existing ones:
|
||||
|
||||
```bash
|
||||
# Backup first
|
||||
cp -r ~/.dotfiles ~/.dotfiles.backup.$(date +%Y%m%d)
|
||||
|
||||
# Copy new lib files
|
||||
cp /path/to/refactor/zsh/lib/*.zsh ~/.dotfiles/zsh/lib/
|
||||
|
||||
# Copy new bin scripts
|
||||
cp /path/to/refactor/bin/*.sh ~/.dotfiles/bin/
|
||||
|
||||
# Copy new function file
|
||||
cp /path/to/refactor/zsh/functions/python-templates.zsh ~/.dotfiles/zsh/functions/
|
||||
|
||||
# Copy new setup scripts
|
||||
cp /path/to/refactor/setup/*.sh ~/.dotfiles/setup/
|
||||
```
|
||||
|
||||
### Option 2: Gradual Migration
|
||||
1. First add `bootstrap.zsh` - it won't break anything
|
||||
2. Update one script at a time to use bootstrap
|
||||
3. Update `python-templates.zsh` last
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
After applying changes, verify everything works:
|
||||
|
||||
```bash
|
||||
# Reload shell
|
||||
source ~/.zshrc
|
||||
|
||||
# Test health check
|
||||
dfd
|
||||
|
||||
# Test version
|
||||
dfv
|
||||
|
||||
# Test Python templates
|
||||
py-templates
|
||||
py-new test-project
|
||||
rm -rf test-project
|
||||
|
||||
# Test that headers display correctly
|
||||
dotfiles-doctor.sh
|
||||
dotfiles-stats.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Structure After Refactoring
|
||||
|
||||
```
|
||||
~/.dotfiles/
|
||||
├── zsh/
|
||||
│ ├── lib/
|
||||
│ │ ├── bootstrap.zsh # NEW: Single entry point
|
||||
│ │ ├── config.zsh # Loads dotfiles.conf
|
||||
│ │ ├── colors.zsh # Color definitions
|
||||
│ │ └── utils.zsh # ENHANCED: Centralized headers
|
||||
│ └── functions/
|
||||
│ └── python-templates.zsh # REFACTORED: Template-driven
|
||||
├── bin/
|
||||
│ ├── dotfiles-doctor.sh # REFACTORED: Uses bootstrap
|
||||
│ ├── dotfiles-sync.sh # REFACTORED: Uses bootstrap
|
||||
│ ├── dotfiles-update.sh # REFACTORED: Uses bootstrap
|
||||
│ ├── dotfiles-version.sh # REFACTORED: Uses bootstrap
|
||||
│ ├── dotfiles-stats.sh # REFACTORED: Uses bootstrap
|
||||
│ ├── dotfiles-vault.sh # REFACTORED: Uses bootstrap
|
||||
│ └── dotfiles-compile.sh # REFACTORED: Uses bootstrap
|
||||
└── setup/
|
||||
├── setup-espanso.sh # REFACTORED: Uses bootstrap
|
||||
└── setup-wizard.sh # REFACTORED: Uses bootstrap
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Single Source of Truth**: Header formatting defined once in `utils.zsh`
|
||||
2. **Easier Maintenance**: Change header style in one place, affects all scripts
|
||||
3. **Consistent Appearance**: All scripts look the same
|
||||
4. **Smaller Files**: Each bin script is ~30-50 lines shorter
|
||||
5. **Better Fallbacks**: `bootstrap.zsh` handles missing files gracefully
|
||||
6. **Template System**: Adding new Python project types is now trivial
|
||||
Reference in New Issue
Block a user