From f0c2137e693ec4ce204fffb7c3bb7e6b28e367a4 Mon Sep 17 00:00:00 2001 From: Eric Turner Date: Sat, 2 Aug 2025 20:00:38 -0600 Subject: [PATCH] docs: Revamp README and add architecture documentation --- README.md | 64 +++++++++++++++++++ docs/ARCHITECTURE.md | 143 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 207 insertions(+) create mode 100755 README.md create mode 100644 docs/ARCHITECTURE.md diff --git a/README.md b/README.md new file mode 100755 index 0000000..8692dc4 --- /dev/null +++ b/README.md @@ -0,0 +1,64 @@ +# Modern Dotfiles Management System + +A comprehensive and intelligent system for managing your terminal configurations (dotfiles) across diverse machines, ensuring a consistent and optimized environment tailored to each machine's purpose. + +## ✨ Why Use This? + +Maintaining a consistent and efficient terminal environment across multiple machines (e.g., development laptops, servers, personal workstations) can be challenging. This dotfiles system simplifies that by offering: + +* **🤖 Machine-Aware Configuration:** Automatically adapts your environment based on the machine type (server, development, personal), installing only what's needed. +* **⚡ Efficient Syncing:** Keeps your dotfiles updated with minimal overhead, syncing intelligently without blocking your workflow. +* **📦 Automated Package Management:** Installs and updates essential tools and applications from various sources (system packages, npm, GitHub releases) based on your machine's profile. +* **🌍 Consistent Experience:** Enjoy the same aliases, functions, and command-line tools everywhere you work. +* **🛡️ Easy Reset & Recovery:** Quickly restore your system to a clean state or revert changes with robust reset capabilities. + +## 🚀 Quick Start + +Get your consistent terminal environment up and running in minutes! + +### One-Line Installation (Recommended) + +```bash +curl -fsSL https://raw.githubusercontent.com/your-username/dotfiles/main/install-web.sh | bash +``` +*Replace `your-username/dotfiles` with the actual GitHub path to this repository.* + +### Manual Installation + +```bash +cd ~ +git clone .dotfiles +cd .dotfiles +./install.sh +``` + +After installation, restart your shell (`exec $SHELL`) or open a new terminal session. + +## 🎮 Core Commands + +Once installed, you'll have access to powerful commands to manage your dotfiles: + +* `dotstatus`: Check the current sync status and system health. +* `dotsync`: Manually trigger a sync to pull the latest dotfiles. +* `dotprofile`: Display your current machine profile and its detected type. +* `dotpkgs`: List packages installed for your current profile. +* `dotupdate`: Check for and install updates for your managed packages. +* `dotreset`: Interactively reset your dotfiles to a clean state. + +## 🛠️ Customization + +* **Add New Packages:** Define new packages and their installation methods in `packages.yaml`. +* **Custom Aliases/Functions:** Add your personal aliases and shell functions to files within the `shared/` directory. +* **Machine Profiles:** Adjust or add new machine profiles in `machine-profiles.yaml` to fine-tune auto-detection and configurations. + +## 📚 Further Documentation + +For more in-depth information on architecture, advanced configuration, troubleshooting, and contributing, please refer to the `docs/` directory: + +* [Installation Guide](docs/INSTALLATION.md) +* [Technical Architecture](docs/ARCHITECTURE.md) +* [Troubleshooting Guide](docs/TROUBLESHOOTING.md) + +--- + +*Your new terminal experience is just a paste away.* \ No newline at end of file diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..84cfc84 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,143 @@ +# Architecture Overview + +This document details the technical architecture and implementation specifics of the Modern Dotfiles Management System. + +## 🏗️ System Structure + +The core components of the dotfiles system are organized as follows: + +``` +~/.dotfiles/ +├── install.sh # Main installation script +├── sync.sh # Auto-sync with git repository +├── reset.sh # Reset to vanilla state +├── machine-profiles.yaml # Machine type definitions +├── packages.yaml # Package definitions +├── bash/ # Bash-specific configurations +├── zsh/ # Zsh-specific configurations +├── shared/ # Universal configurations +├── git/ # Git configuration +├── vim/ # Vim configuration +├── lib/ # Core libraries +└── docs/ # Documentation +``` + +## 🤖 Machine Profiles + +The system automatically detects and configures based on machine type using a scoring algorithm: + +### Server Profile +- **Purpose**: Minimal server setup +- **Packages**: `curl`, `git`, `vim`, `sshuttle`, `ripgrep`, `fd` +- **Use Case**: Production servers, minimal VMs +- **Auto-detection**: SSH connections, systemd services, no GUI + +### Development Profile +- **Purpose**: Full development environment +- **Packages**: All tools including Claude AI, Gemini CLI, Docker, modern CLI tools +- **Use Case**: Primary development machines +- **Auto-detection**: Code editors, development directories, Node.js/Python + +### Development Lite Profile +- **Purpose**: Development without heavy packages +- **Packages**: Development tools but no Docker/containers +- **Use Case**: Lightweight VMs, resource-constrained machines +- **Auto-detection**: Development tools present but limited resources + +### Personal Profile +- **Purpose**: Personal machines with all conveniences +- **Packages**: Everything including task management tools +- **Use Case**: Personal laptops, home workstations +- **Auto-detection**: Personal directories, browsers, GUI environment + +### Minimal Profile +- **Purpose**: Absolute bare bones +- **Packages**: `curl`, `git`, `vim` only +- **Use Case**: Emergency access, extremely limited environments + +## 🔧 Technical Implementation + +### Profile Detection Algorithm +The system uses a scoring algorithm to detect machine type: + +```bash +# Server indicators (weight) +- systemd active (30 points) +- SSH connection (25 points) +- Multi-user target (20 points) +- No logged users (10 points) + +# Development indicators +- Development tools present (30 points) +- Code editor available (25 points) +- Dev directories exist (20 points) +- GUI environment (15 points) + +# Personal indicators +- Personal directories (20 points) +- Browser available (25 points) +- Personal home path (15 points) +``` + +### Update Checking Strategy +```bash +# Fast check methods +npm outdated -g --json # No installs, just version comparison +GitHub API calls # Latest release info +Local version parsing # Current installed versions + +# Selective updates +Only outdated packages # Skip up-to-date ones +Profile filtering # Server won't check Claude/Gemini +Batch operations # Update multiple efficiently +``` + +### Sync Optimization +```bash +# Timing controls +24-hour auto-sync limit # Prevent excessive git operations +5-minute manual override # Allow frequent manual syncing +Background execution # Non-blocking terminal startup + +# Change detection +Git fetch + compare # Check for remote changes +Local diff detection # Handle local modifications +Automatic stash/restore # Preserve local changes +``` + +## 🛡️ Safety Features + +### Backup System +- **Pre-installation backup**: All existing configs saved +- **Timestamped backups**: Never overwrites previous backups +- **Symlink detection**: Preserves existing dotfiles setups +- **Restoration capability**: Can restore original configs + +### Reset Capabilities +- **Soft reset**: Remove dotfiles, restore originals +- **Hard reset**: Also uninstall packages +- **Nuclear reset**: Complete removal +- **Safety prompts**: Confirmation for destructive operations + +### Error Handling +- **Graceful failures**: Continue on non-critical errors +- **Detailed logging**: All operations logged with timestamps +- **Rollback capability**: Can undo changes if needed +- **Dependency checking**: Verify requirements before installation + +## 📈 Performance Characteristics + +### Startup Time +- **Cold start**: ~2 seconds (first terminal of day with sync) +- **Warm start**: ~0.1 seconds (subsequent terminals) +- **Background sync**: Non-blocking, invisible to user + +### Update Efficiency +- **Traditional approach**: `npm update -g` (30-60 seconds) +- **Smart checking**: `dotupdatecheck` (2-5 seconds) +- **Selective updates**: Only outdated packages (10-20 seconds) + +### Resource Usage +- **Memory footprint**: Minimal (shell functions only) +- **Disk usage**: ~50MB for full dev profile +- **Network usage**: Efficient API calls, cached results