Cleanup tasks.

2025-12-15 16:17:06 -05:00
parent 048c9ed8bc
commit 5f3aad3b99
8 changed files with 1341 additions and 773 deletions
--- a/docs/SETUP_GUIDE.md
+++ b/docs/SETUP_GUIDE.md
@@ -1,22 +1,65 @@
 # Setup Guide

-Step-by-step instructions for setting up and maintaining your dotfiles.
+Complete guide for installing, configuring, and maintaining your dotfiles.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation Methods](#installation-methods)
+- [Post-Install Setup](#post-install-setup)
+- [Configuration](#configuration)
+- [Features Guide](#features-guide)
+- [Customization](#customization)
+- [Multi-Machine Setup](#multi-machine-setup)
+- [Troubleshooting](#troubleshooting)
+- [Uninstalling](#uninstalling)
+
+---

 ## Prerequisites

+**Required:**
 - Git
 - Curl
- Zsh (will be installed if missing)
+- Zsh (installed automatically if missing)

-## Fresh Install
+**Optional (for full features):**
+- `fzf` - For command palette and fuzzy finding
+- `age` or `gpg` - For secrets vault
+- `gum` - For beautiful setup wizard

-### Option 1: One-liner
+---
+
+## Installation Methods
+
+### Method 1: Interactive Wizard (Recommended)
+
+The wizard provides a beautiful TUI to customize your installation:
+
+```bash
+git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
+cd ~/.dotfiles
+./install.sh --wizard
+```
+
+The wizard will guide you through:
+1. Identity setup (name, email, GitHub)
+2. Git configuration
+3. Feature selection
+4. Theme choice
+5. Advanced options
+
+### Method 2: One-liner
+
+Quick install with defaults:

 ```bash
 curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash
 ```

-### Option 2: Clone First
+### Method 3: Standard Install
+
+Clone and run with prompts:

 ```bash
 git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
@@ -24,119 +67,443 @@ cd ~/.dotfiles
 ./install.sh
 ```

-### What the Installer Does
-
-1. Detects OS (Ubuntu, Arch, Fedora, macOS)
-2. Installs dependencies (git, curl, zsh)
-3. Backs up existing configs to `~/.dotfiles_backup_YYYYMMDD_HHMMSS/`
-4. Installs oh-my-zsh
-5. Installs zsh plugins (autosuggestions, syntax-highlighting)
-6. Configures git (prompts for name/email if not in config)
-7. Creates symlinks
-8. Optionally installs espanso, fzf, bat, eza
-9. Sets zsh as default shell
-
 ### Install Options

 ```bash
-./install.sh                # Full interactive install
-./install.sh --skip-deps    # Skip dependency check (for re-runs)
-./install.sh --deps-only    # Only install dependencies
-./install.sh --uninstall    # Remove symlinks, offer to restore backups
-./install.sh --uninstall --purge  # Also remove ~/.dotfiles
-./install.sh --help         # Show all options
+./install.sh                    # Interactive install
+./install.sh --wizard           # TUI wizard
+./install.sh --skip-deps        # Skip dependency installation
+./install.sh --deps-only        # Only install dependencies
+./install.sh --uninstall        # Remove symlinks
+./install.sh --uninstall --purge # Remove everything
+./install.sh --help             # Show all options
 ```

-## Post-Install
+---

-### Verify Installation
+## Post-Install Setup
+
+### 1. Verify Installation

 ```bash
-dotfiles-doctor.sh          # Check health of installation
-dotfiles-doctor.sh --fix    # Attempt to fix issues
+dotfiles-doctor.sh
 ```

-### Check Version
+This checks:
+- All symlinks are valid
+- Zsh plugins installed
+- Git configured
+- Theme loaded
+- Optional tools present
+
+Fix issues automatically:

 ```bash
-dotfiles-version.sh         # Show local vs remote version
-dotfiles-version.sh --check # Exit 1 if updates available
+dotfiles-doctor.sh --fix
 ```

-### Personalize Espanso
+### 2. Restart Shell

 ```bash
-./bin/setup-espanso.sh
+exec zsh
+# or just close and reopen your terminal
 ```

-Updates `personal.yml` with your name, email, etc.
-
-### Test It
+### 3. Personalize Espanso (Optional)

 ```bash
-source ~/.zshrc           # Reload shell
-echo "..date" | espanso   # Test espanso (or just type ..date anywhere)
+setup-espanso.sh
 ```

-### Install Zsh Plugins (if missing)
+This sets up your personal info for text expansion (email, name, signatures).
+
+### 4. Set Up Secrets Vault (Optional)

 ```bash
-git clone https://github.com/zsh-users/zsh-autosuggestions \
-  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
-
-git clone https://github.com/zsh-users/zsh-syntax-highlighting \
-  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
+vault init
+vault set GITHUB_TOKEN "your-token-here"
+vault list
 ```

-## Updating
+### 5. Configure Directory Bookmarks (Optional)

 ```bash
-cd ~/.dotfiles
-git pull origin main
-./install.sh
+bookmark projects ~/projects
+bookmark work ~/work
+bookmark list
+```
+
+---
+
+## Configuration
+
+### Main Configuration File
+
+All settings are in `~/.dotfiles/dotfiles.conf`:
+
+```bash
+# ============================================================================
+# Identity
+# ============================================================================
+USER_FULLNAME="Your Name"
+USER_EMAIL="you@example.com"
+USER_GITHUB="yourusername"
+
+# ============================================================================
+# Git Configuration
+# ============================================================================
+GIT_USER_NAME=""              # Falls back to USER_FULLNAME
+GIT_USER_EMAIL=""             # Falls back to USER_EMAIL
+GIT_DEFAULT_BRANCH="main"
+GIT_CREDENTIAL_HELPER="store"
+
+# ============================================================================
+# Feature Toggles
+# ============================================================================
+# Values: "true", "false", or "ask"
+
+INSTALL_DEPS="auto"           # Auto-skip if already installed
+INSTALL_ZSH_PLUGINS="true"    # zsh-autosuggestions, syntax-highlighting
+INSTALL_FZF="ask"
+INSTALL_BAT="ask"
+INSTALL_EZA="ask"
+INSTALL_ESPANSO="ask"
+SET_ZSH_DEFAULT="ask"
+
+# ============================================================================
+# Advanced Features
+# ============================================================================
+ENABLE_SMART_SUGGESTIONS="true"   # Typo correction
+ENABLE_COMMAND_PALETTE="true"     # Ctrl+Space launcher
+ENABLE_SHELL_ANALYTICS="false"    # Command stats
+ENABLE_VAULT="true"               # Encrypted secrets
+DOTFILES_AUTO_SYNC_CHECK="true"   # Check for updates on shell start
+```
+
+### Applying Configuration Changes
+
+After editing `dotfiles.conf`:
+
+```bash
+./install.sh --skip-deps
+# or just
 source ~/.zshrc
 ```

-Or use the helper:
+---
+
+## Features Guide
+
+### Command Palette
+
+**Trigger:** `Ctrl+Space` or `Ctrl+P`
+
+The command palette searches:
+- ⚡ Aliases
+- λ Functions
+- ↺ Recent commands
+- 📁 Bookmarked directories
+- ⚙ Dotfiles scripts
+- ★ Quick actions
+- ⎇ Git commands (context-aware)
+- ◉ Docker commands
+
+**Keybindings in palette:**
+| Key | Action |
+|-----|--------|
+| `Enter` | Execute command |
+| `Ctrl+E` | Edit command first |
+| `Ctrl+Y` | Copy to clipboard |
+| `Ctrl+R` | Refresh entries |
+| `Esc` | Cancel |
+
+**Bookmarks:**

 ```bash
-update-dotfiles.sh
+bookmark <name> [path]    # Save bookmark (default: current dir)
+bookmark list             # List all bookmarks
+bookmark delete <name>    # Remove bookmark
+jump <name>               # Go to bookmark
+j                         # Fuzzy select bookmark
 ```

-## Pushing Changes
+### Smart Suggestions
+
+Automatically corrects 100+ common typos:
+
+```bash
+gti → git
+dokcer → docker
+sl → ls
+pytohn → python
+```
+
+Suggests aliases for frequently typed commands:
+
+```bash
+💡 You've typed 'git status' 50 times
+   You already have an alias: gs
+```
+
+**Commands:**
+
+```bash
+fuck                      # Re-run last command with typo fixed
+```
+
+### Shell Analytics
+
+```bash
+shell-stats.sh            # Full dashboard
+shell-stats.sh --top 20   # Top 20 commands
+shell-stats.sh --suggest  # Alias recommendations
+shell-stats.sh --heatmap  # Activity by hour
+shell-stats.sh --dirs     # Most visited directories
+shell-stats.sh --git      # Git command breakdown
+shell-stats.sh --docker   # Docker command breakdown
+shell-stats.sh --export   # Export as JSON
+```
+
+### Secrets Vault
+
+Encrypted storage using `age` or `gpg`:
+
+```bash
+vault set KEY "value"     # Store (or prompt for value)
+vault get KEY             # Retrieve
+vault list                # Show all keys
+vault delete KEY          # Remove
+vault shell               # Print as export statements
+vault export backup.enc   # Backup encrypted vault
+vault import backup.enc   # Restore vault
+vault status              # Show vault info
+```
+
+**Auto-loading:** Secrets are automatically loaded into your environment on shell start.
+
+### Dotfiles Sync
+
+```bash
+dotfiles-sync.sh              # Interactive sync
+dotfiles-sync.sh --status     # Show sync status
+dotfiles-sync.sh --push       # Push local changes
+dotfiles-sync.sh --pull       # Pull remote changes
+dotfiles-sync.sh --diff       # Show local changes
+dotfiles-sync.sh --watch 300  # Auto-sync every 5 minutes
+dotfiles-sync.sh --log        # Show sync history
+```
+
+**Auto-check:** On shell start, you'll be notified of available updates.
+
+---
+
+## Customization
+
+### Adding Aliases
+
+Edit `~/.dotfiles/zsh/.zshrc`:
+
+```bash
+# Custom aliases
+alias projects='cd ~/projects'
+alias k='kubectl'
+alias tf='terraform'
+```
+
+### Machine-Specific Config
+
+Create `~/.zshrc.local` (not tracked by git):
+
+```bash
+# Work machine
+export CORP_PROXY="http://proxy:8080"
+export WORK_EMAIL="me@company.com"
+
+# Local paths
+export PATH="$HOME/work-tools/bin:$PATH"
+```
+
+### Custom Espanso Snippets
+
+Edit `~/.dotfiles/espanso/match/personal.yml`:
+
+```yaml
+matches:
+  - trigger: "..myemail"
+    replace: "your.email@example.com"
+  
+  - trigger: "..sig"
+    replace: |
+      Best regards,
+      Your Name
+```
+
+### Theme Customization
+
+Edit `~/.dotfiles/zsh/themes/adlee.zsh-theme`:
+
+```zsh
+# Change colors
+typeset -g COLOR_GREEN='%{$FG[118]%}'
+typeset -g COLOR_BLUE='%{$FG[069]%}'
+
+# Change timer threshold (seconds)
+typeset -g TIMER_THRESHOLD=10
+```
+
+---
+
+## Multi-Machine Setup
+
+### Initial Setup on New Machine
+
+```bash
+# Clone your dotfiles
+git clone https://github.com/YOUR_USER/dotfiles.git ~/.dotfiles
+cd ~/.dotfiles
+./install.sh
+```
+
+### Syncing Changes
+
+**On Machine A (make changes):**

 ```bash
 cd ~/.dotfiles
-git add .
-git commit -m "Update aliases"
-git push origin main
+# Edit files...
+dotfiles-sync.sh --push "Added new aliases"
 ```

-## Multi-Machine Sync
+**On Machine B (get changes):**

 ```bash
-# Machine A: push changes
-cd ~/.dotfiles && git add . && git commit -m "Update" && git push
-
-# Machine B: pull changes
-cd ~/.dotfiles && git pull && source ~/.zshrc
+dotfiles-sync.sh --pull
+source ~/.zshrc
 ```

-## File Structure
+### Automatic Sync

-| Path | Purpose |
-|------|---------|
-| `zsh/.zshrc` | Main shell config |
-| `zsh/themes/adlee.zsh-theme` | Prompt theme |
-| `zsh/functions/snapper.zsh` | Btrfs snapshot helpers |
-| `espanso/match/base.yml` | Text snippets |
-| `espanso/match/personal.yml` | Your personal info |
-| `git/.gitconfig` | Git settings |
-| `vim/.vimrc` | Vim config |
-| `tmux/.tmux.conf` | Tmux config |
-| `bin/` | Utility scripts |
+Enable watch mode (runs in background):

-## Symlinks Created
+```bash
+dotfiles-sync.sh --watch 300  # Check every 5 minutes
+```
+
+Or add to crontab:
+
+```bash
+*/30 * * * * ~/.dotfiles/bin/dotfiles-sync.sh --auto
+```
+
+---
+
+## Troubleshooting
+
+### Run the Doctor First
+
+```bash
+dotfiles-doctor.sh --fix
+```
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Theme not loading | Check `ZSH_THEME="adlee"` in .zshrc, run `source ~/.zshrc` |
+| Zsh plugins missing | Run `./install.sh` (auto-installs plugins now) |
+| Command palette not working | Install fzf: `./install.sh` will prompt |
+| Vault errors | Install age: `brew install age` or `pacman -S age` |
+| Espanso not expanding | Run `espanso status`, then `espanso restart` |
+| Sync conflicts | Run `dotfiles-sync.sh --conflicts` to see conflicts |
+| Symlinks broken | Run `./install.sh --skip-deps` to recreate |
+
+### Manual Fixes
+
+**Reinstall zsh plugins:**
+
+```bash
+rm -rf ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions
+rm -rf ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting
+./install.sh --skip-deps
+```
+
+**Reset git config:**
+
+```bash
+rm ~/.gitconfig
+./install.sh --skip-deps
+```
+
+**Fix permissions:**
+
+```bash
+chmod +x ~/.dotfiles/install.sh
+chmod +x ~/.dotfiles/bin/*
+```
+
+### Getting Help
+
+```bash
+# Any script
+<script> --help
+
+# Examples
+./install.sh --help
+vault --help
+dotfiles-sync.sh --help
+shell-stats.sh --help
+```
+
+---
+
+## Uninstalling
+
+### Quick Uninstall
+
+```bash
+./install.sh --uninstall
+```
+
+This will:
+1. Remove all symlinks
+2. Find and offer to restore backups
+3. Keep ~/.dotfiles directory
+
+### Complete Removal
+
+```bash
+./install.sh --uninstall --purge
+```
+
+This also removes the `~/.dotfiles` directory.
+
+### Manual Uninstall
+
+```bash
+# Remove symlinks
+rm ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf
+rm ~/.oh-my-zsh/themes/adlee.zsh-theme
+rm -rf ~/.config/espanso
+rm ~/.local/bin/dotfiles-*.sh ~/.local/bin/vault.sh ~/.local/bin/shell-stats.sh
+
+# Restore backups (if any)
+ls ~/.dotfiles_backup_*
+
+# Remove dotfiles
+rm -rf ~/.dotfiles
+
+# Optional: Remove oh-my-zsh
+rm -rf ~/.oh-my-zsh
+
+# Change shell back to bash
+chsh -s /bin/bash
+```
+
+---
+
+## File Reference
+
+### Symlinks Created

 | Source | Target |
 |--------|--------|
@@ -146,156 +513,27 @@ cd ~/.dotfiles && git pull && source ~/.zshrc
 | `~/.dotfiles/vim/.vimrc` | `~/.vimrc` |
 | `~/.dotfiles/tmux/.tmux.conf` | `~/.tmux.conf` |
 | `~/.dotfiles/espanso/` | `~/.config/espanso` |
+| `~/.dotfiles/bin/*` | `~/.local/bin/*` |

-## System-Wide Theme
+### Key Files

-Deploy to all users on a system:
+| File | Purpose |
+|------|---------|
+| `dotfiles.conf` | Central configuration |
+| `zsh/.zshrc` | Main shell config |
+| `zsh/themes/adlee.zsh-theme` | Prompt theme |
+| `zsh/functions/smart-suggest.zsh` | Typo correction |
+| `zsh/functions/command-palette.zsh` | Fuzzy launcher |
+| `espanso/match/base.yml` | Text expansion snippets |
+| `espanso/match/personal.yml` | Personal snippets |
+| `vault/` | Encrypted secrets (gitignored) |

-```bash
-# Interactive
-sudo ./bin/deploy-zshtheme-systemwide.sh
+---

-# All users with oh-my-zsh
-sudo ./bin/deploy-zshtheme-systemwide.sh --all
+## Security Notes

-# Current user + root only
-sudo ./bin/deploy-zshtheme-systemwide.sh --current
-
-# Check status
-sudo ./bin/deploy-zshtheme-systemwide.sh --status
-```
-
-Creates symlinks from each user's oh-my-zsh themes folder to `/usr/local/share/zsh/themes/adlee.zsh-theme`.
-
-## Configuration
-
-### dotfiles.conf
-
-The main configuration file. Edit to customize your installation:
-
-```bash
-# --- Version ---
-DOTFILES_VERSION="1.0.0"
-
-# --- User Identity ---
-USER_FULLNAME="Your Name"
-USER_EMAIL="you@example.com"
-USER_GITHUB="yourusername"
-
-# --- Git Configuration ---
-GIT_USER_NAME=""           # Falls back to USER_FULLNAME
-GIT_USER_EMAIL=""          # Falls back to USER_EMAIL
-GIT_DEFAULT_BRANCH="main"
-GIT_CREDENTIAL_HELPER="store"
-
-# --- Feature Toggles ---
-INSTALL_DEPS="auto"        # "auto", "true", "false", or "ask"
-INSTALL_ZSH_PLUGINS="true" # Auto-install zsh plugins
-INSTALL_ESPANSO="ask"
-INSTALL_FZF="ask"
-INSTALL_BAT="ask"
-INSTALL_EZA="ask"
-SET_ZSH_DEFAULT="ask"
-```
-
-### Git Identity
-
-The installer configures git automatically:
-
-1. Uses `GIT_USER_NAME` / `GIT_USER_EMAIL` from config
-2. Falls back to `USER_FULLNAME` / `USER_EMAIL`
-3. Prompts if both are empty
-
-To reconfigure git later:
-
-```bash
-git config --global user.name "New Name"
-git config --global user.email "new@email.com"
-```
-
-Or edit `dotfiles.conf` and re-run `./install.sh`.
-
-## Customization Tips
-
-### Add Aliases
-
-Edit `~/.dotfiles/zsh/.zshrc`:
-
-```bash
-alias projects='cd ~/projects'
-alias k='kubectl'
-```
-
-### Machine-Specific Config
-
-Create `~/.zshrc.local` (not tracked by git):
-
-```bash
-# Work machine specific
-export WORK_API_KEY="xxx"
-alias vpn='sudo openconnect ...'
-```
-
-### Theme Colors
-
-Edit `~/.dotfiles/zsh/themes/adlee.zsh-theme` and look for:
-
-```zsh
-typeset -g COLOR_GREEN='%{$FG[118]%}'
-typeset -g COLOR_BLUE='%{$FG[069]%}'
-```
-
-## Troubleshooting
-
-### Run the Doctor
-
-```bash
-dotfiles-doctor.sh          # Diagnose issues
-dotfiles-doctor.sh --fix    # Auto-fix what's possible
-```
-
-### Common Issues
-
-| Issue | Fix |
-|-------|-----|
-| Theme not loading | `dotfiles-doctor.sh --fix` |
-| Zsh plugins missing | `./install.sh` (auto-installs) |
-| Espanso not expanding | `espanso restart` |
-| Git identity not set | Re-run `./install.sh` |
-| Broken symlinks | `./install.sh` |
-
-### Manual Fixes
-
-```bash
-# Reinstall zsh plugins
-git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
-git clone https://github.com/zsh-users/zsh-syntax-highlighting ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
-
-# Fix permissions
-chmod +x ~/.dotfiles/install.sh
-chmod +x ~/.dotfiles/bin/*
-```
-
-## Uninstalling
-
-### Quick Uninstall
-
-```bash
-./install.sh --uninstall           # Remove symlinks, offer backup restore
-./install.sh --uninstall --purge   # Also delete ~/.dotfiles
-```
-
-### Manual Uninstall
-
-```bash
-# Remove symlinks
-rm ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf
-rm ~/.oh-my-zsh/themes/adlee.zsh-theme
-rm -rf ~/.config/espanso
-
-# Restore backups
-cp ~/.dotfiles_backup_*/.zshrc ~/ 
-
-# Remove dotfiles
-rm -rf ~/.dotfiles
-```
+- `.gitignore` excludes sensitive files (`.env`, `secrets/`, `*.local`, `vault/`)
+- Vault uses strong encryption (age/gpg)
+- Never commit API keys or tokens
+- Review `git/.gitconfig` before pushing (contains email)
+- Personal espanso snippets may contain sensitive info