Add comprehensive system enhancements and shell configurations
Following the μέτρον principle of durable, thoughtful solutions: Shell Configuration: - Add refined .zshrc with modular architecture - Include .p10k.zsh for Powerlevel10k prompt - Add .zprofile for login shell configuration - Update aliases with new dotfiles management tools System Management Tools: - safe-update.sh: System updates with rollback protection - detect-drift.sh: Configuration drift detection - system-health.sh: Comprehensive health monitoring - generate-lockfile.sh: Version tracking for reproducibility Documentation: - ARCHITECTURE.md: Philosophy and design rationale - USAGE.md: Practical guide and troubleshooting Other Updates: - Update symlinks.sh to manage all config files - Add .vimrc configuration - Create Brewfile.lock for version pinning These enhancements provide visibility, safety, and maintainability while following the prime directive of prioritizing durability. 🖖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
David F Glidden
co-authored by
Claude
Claude
parent
92b0ead991
commit
1f543d195b
+203
@@ -0,0 +1,203 @@
|
||||
# Dotfiles Architecture Documentation
|
||||
|
||||
## Philosophy: μέτρον γὰρ καὶ συμμετρία καὶ τὸ πρόσφορον
|
||||
|
||||
This dotfiles system is built upon the prime directive: **"Prioritize durable, thoughtful solutions over expedient ones"**. The Greek principle of μέτρον (measure), συμμετρία (proportion), and τὸ πρόσφορον (what is fitting) guides every architectural decision.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Durability Over Convenience
|
||||
- **Long-term thinking**: Solutions that remain stable across system updates
|
||||
- **Graceful degradation**: System continues to function when components are missing
|
||||
- **Version stability**: Lockfiles and rollback mechanisms prevent breaking changes
|
||||
|
||||
### 2. Thoughtful Modularization
|
||||
- **Single responsibility**: Each script and configuration file has a clear purpose
|
||||
- **Composable design**: Components work independently and together
|
||||
- **Context awareness**: System adapts behavior based on working directory and usage patterns
|
||||
|
||||
### 3. Measured Implementation
|
||||
- **What is fitting**: Tools and configurations chosen for specific needs, not trends
|
||||
- **Proportional complexity**: Simple solutions for simple problems
|
||||
- **Observable behavior**: System provides visibility into its operations
|
||||
|
||||
## System Architecture
|
||||
|
||||
```
|
||||
~/dotfiles/
|
||||
├── engage # Master deployment script (Star Trek theme)
|
||||
├── Brewfile # Package definitions (120+ tools)
|
||||
├── Brewfile.lock # Version snapshots for reproducibility
|
||||
├── shell/ # Modular shell configuration
|
||||
│ ├── .zshrc # Main shell config (replaces ~/.zshrc)
|
||||
│ ├── environment.zsh # Environment variables
|
||||
│ ├── paths.zsh # PATH management with deduplication
|
||||
│ ├── aliases.zsh # Command aliases
|
||||
│ ├── functions.zsh # Custom functions
|
||||
│ └── .zsh-plugins.txt # Plugin manifest for Antidote
|
||||
├── scripts/ # Automation and maintenance
|
||||
│ ├── backup-ssh-keys.sh # GPG encryption for sensitive data
|
||||
│ ├── generate-lockfile.sh# Version tracking
|
||||
│ ├── safe-update.sh # Update with rollback protection
|
||||
│ ├── detect-drift.sh # Configuration consistency checking
|
||||
│ ├── system-health.sh # Observability and monitoring
|
||||
│ └── set-macos-defaults.sh# System preferences automation
|
||||
└── git/ # Git configuration and hooks
|
||||
├── .gitconfig # Git settings
|
||||
└── hooks/ # Security and validation hooks
|
||||
```
|
||||
|
||||
## Component Design Rationale
|
||||
|
||||
### The "engage" Script
|
||||
**Inspiration**: Captain Picard's decisive command
|
||||
**Purpose**: Single-entry point for complete system deployment
|
||||
**Design**: Interactive menu with phased installation and pre-flight checks
|
||||
|
||||
```bash
|
||||
# Philosophy: Make complex deployment feel effortless
|
||||
echo "🖖 ENGAGE - Make it so!"
|
||||
```
|
||||
|
||||
### Shell Configuration Strategy
|
||||
**Problem**: Monolithic .zshrc files become unmaintainable
|
||||
**Solution**: Modular architecture with graceful degradation
|
||||
|
||||
**Key decisions**:
|
||||
- **environment.zsh**: Sets the foundation (XDG, locale, history)
|
||||
- **paths.zsh**: Intelligent PATH building with deduplication
|
||||
- **functions.zsh**: Enhanced system utilities (sysupdate, deep_clean, vault integration)
|
||||
- **Context awareness**: Behavior adapts to work/chamber/vault/dotfiles environments
|
||||
|
||||
### Package Management Philosophy
|
||||
**Brewfile Design**: Organized by purpose, not alphabetically
|
||||
```ruby
|
||||
# Development tools come first (core workflow)
|
||||
brew "git"
|
||||
brew "ripgrep"
|
||||
brew "fzf"
|
||||
|
||||
# Productivity tools second (daily usage)
|
||||
brew "obsidian"
|
||||
brew "raycast"
|
||||
```
|
||||
|
||||
**Rationale**: Reflects actual importance hierarchy, not convenience
|
||||
|
||||
### Version Control Strategy
|
||||
**Three-tier approach**:
|
||||
1. **Brewfile**: What should be installed
|
||||
2. **Brewfile.lock**: What versions are currently installed
|
||||
3. **safe-update.sh**: How to update safely with rollback
|
||||
|
||||
This mirrors software engineering best practices (requirements → lockfile → deployment).
|
||||
|
||||
### Security Architecture
|
||||
**Defense in depth**:
|
||||
- **SSH key backup**: GPG-encrypted with restore instructions
|
||||
- **Git hooks**: Prevent accidental secret commits
|
||||
- **Firewall monitoring**: System health checks include security posture
|
||||
- **Sensitive data handling**: Never commit secrets, always encrypt backups
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Configuration Drift Detection
|
||||
**Problem**: Systems inevitably drift from their defined state
|
||||
**Solution**: Automated comparison between actual and intended configuration
|
||||
|
||||
**Three drift types monitored**:
|
||||
1. **Package drift**: Installed vs. Brewfile definitions
|
||||
2. **Configuration drift**: Live files vs. dotfiles repository
|
||||
3. **System drift**: Current macOS settings vs. defaults script
|
||||
|
||||
### System Health Monitoring
|
||||
**Observability philosophy**: "You can't manage what you can't measure"
|
||||
|
||||
**Monitored components**:
|
||||
- **Resources**: CPU, memory, disk usage with intelligent thresholds
|
||||
- **Services**: Critical tools (Homebrew, Git, Zsh, SSH) health status
|
||||
- **Packages**: Total count, outdated packages, broken installations
|
||||
- **Shell performance**: Load time and plugin count impact
|
||||
- **Network**: Internet, DNS, GitHub connectivity for development
|
||||
- **Security**: SSH keys, GPG keys, firewall status
|
||||
|
||||
### Context-Aware Behavior
|
||||
**Philosophy**: Tools should adapt to how you work
|
||||
|
||||
**Context detection**:
|
||||
```bash
|
||||
# Automatic context detection based on PWD
|
||||
detect_context() {
|
||||
case "$PWD" in
|
||||
*work*) CURRENT_CONTEXT="work" ;;
|
||||
*chamber*) CURRENT_CONTEXT="chamber" ;;
|
||||
*vault*) CURRENT_CONTEXT="vault" ;;
|
||||
*dotfiles*) CURRENT_CONTEXT="dotfiles" ;;
|
||||
*) CURRENT_CONTEXT="general" ;;
|
||||
esac
|
||||
}
|
||||
```
|
||||
|
||||
**Context-specific behaviors**:
|
||||
- **Work**: Enhanced productivity shortcuts, stricter security
|
||||
- **Chamber**: Creative workspace optimizations
|
||||
- **Vault**: Knowledge management integration (Obsidian shortcuts)
|
||||
- **Dotfiles**: System administration tools prominently available
|
||||
|
||||
## Error Handling Philosophy
|
||||
|
||||
### Graceful Degradation
|
||||
**Principle**: System remains functional when components fail
|
||||
|
||||
**Implementation patterns**:
|
||||
```bash
|
||||
# Tool availability checks
|
||||
if command -v fzf >/dev/null; then
|
||||
eval "$(fzf --zsh)"
|
||||
elif [[ -z "${P10K_INSTANT_PROMPT-}" ]]; then
|
||||
echo "⚠️ FZF not available - install with: brew install fzf"
|
||||
fi
|
||||
```
|
||||
|
||||
### Rollback Capabilities
|
||||
**Safe-update pattern**: Always create recovery points before changes
|
||||
- **Snapshots**: Package states and configuration backups
|
||||
- **Health testing**: Verify system function after updates
|
||||
- **Automatic rollback**: Return to last known good state on failure
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Shell Startup Optimization
|
||||
**Problem**: Plugin-heavy shells can have slow startup times
|
||||
**Solutions**:
|
||||
- **Instant prompt**: Powerlevel10k instant prompt for immediate responsiveness
|
||||
- **Conditional loading**: Only load tools that are actually installed
|
||||
- **Fast mode**: Non-interactive shells bypass expensive operations
|
||||
|
||||
### Plugin Management Strategy
|
||||
**Antidote over Oh My Zsh**: Faster, more reliable plugin management
|
||||
**Curated plugin list**: Only essential plugins, regularly audited
|
||||
**Performance monitoring**: Track shell load times and plugin impact
|
||||
|
||||
## Future Evolution
|
||||
|
||||
### Extensibility Points
|
||||
**Plugin architecture**: Additional modules can be added to `shell/` directory
|
||||
**Hook system**: Custom scripts can extend behavior at defined points
|
||||
**Context expansion**: New work environments easily added to context detection
|
||||
|
||||
### Maintenance Strategy
|
||||
**Regular audits**: Quarterly review of tools and configurations
|
||||
**Dependency tracking**: Monitor for deprecated packages or breaking changes
|
||||
**Documentation updates**: Architecture docs updated with any design changes
|
||||
|
||||
## Conclusion
|
||||
|
||||
This dotfiles system embodies the principle that **good tools become invisible**. By prioritizing durability, thoughtfulness, and proportionality, it creates a computing environment that supports focused work rather than demanding constant maintenance.
|
||||
|
||||
The μέτρον principle ensures that every component has the right measure of complexity - no more, no less - for its intended purpose. This creates a system that remains stable and usable across years of computing, embodying the prime directive of durable, thoughtful solutions.
|
||||
|
||||
---
|
||||
|
||||
*"The best tools are the ones you forget you're using."*
|
||||
*"Make it so!" - Captain Jean-Luc Picard*
|
||||
Reference in New Issue
Block a user