diff --git a/CLAUDE.md b/CLAUDE.md index c7ce593..6c830c6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,23 +4,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Repository Overview -This is a personal dotfiles repository that manages macOS development environment configuration. The setup is built around RCM (RcM) for dotfile management, Homebrew for package management, and Mise for runtime version management. +This is a personal dotfiles repository that manages macOS development environment configuration. The setup is built around Mise for both runtime version management and task automation, with Homebrew for package management. ## Key Architecture Components -### RCM-based Dotfile Management -- Uses RCM with `rcrc` configuration pointing to both this repo and thoughtbot/dotfiles -- Dotfiles are symlinked from `~/.dotfiles` and `~/.dotfiles-thoughtbot` -- `EXCLUDES` in rcrc prevents README and LICENSE files from being linked +### Simple Symlink-based Management +- Dotfiles are symlinked from `~/.dotfiles` to home directory +- Setup managed via Mise task: `mise run setup` +- No external dependencies on other dotfile repositories +- Automatic backup of existing files before symlinking -### Multi-layered Configuration System -- Base configuration from thoughtbot/dotfiles -- Local overrides in this repository (e.g., `zshrc.local`, `gitconfig.local`) -- Host-specific configurations in `host-*` directories -- Secret files sourced conditionally (`.zshrc.host`, `.secrets`) +### Single Repository Design +- All configurations are self-contained in this repository +- No base/override pattern - each dotfile is complete and standalone +- Host-specific configurations can be sourced optionally (`.zshrc.host`, `.secrets`) ### Development Environment Stack - **Runtime Management**: Mise (`config/mise/config.toml`) manages Go, Node, Ruby, Python, Deno versions +- **Task Automation**: Mise tasks for setup and maintenance operations - **Package Management**: Homebrew with `Brewfile` for system dependencies and applications - **Shell**: Zsh with custom prompt (`🍔 `) and PATH modifications - **Custom Tooling**: Python-based MCP server for Bear notes integration (`bin/ak-mcp.py`) @@ -29,24 +30,33 @@ This is a personal dotfiles repository that manages macOS development environmen ### Initial Setup/Bootstrap ```bash -# Bootstrap new machine (requires thoughtbot/laptop) -cd ~/Setup -git clone https://github.com/thoughtbot/dotfiles dotfiles-thoughtbot -git clone [this-repo] dotfiles -env RCRC=$HOME/Setup/dotfiles-thoughtbot/rcrc rcup -./laptop.local +# Clone repository +git clone https://github.com/therealadam/dotfiles ~/.dotfiles +cd ~/.dotfiles + +# Set up dotfiles (creates symlinks) +mise run setup + +# Install Homebrew packages +brew bundle install ``` ### Daily Operations ```bash +# List available tasks +mise tasks + # Re-link all dotfiles after changes -rcup +mise run setup -# Add new dotfile to RCM management -mkrc +# Backup existing dotfiles +mise run backup + +# Find unmanaged dotfiles +mise run unmanaged # Install/update Homebrew packages -brew bundle install --file ~/Setup/dotfiles/Brewfile +brew bundle install --file ~/.dotfiles/Brewfile # Update development runtimes mise install @@ -56,17 +66,18 @@ mise use go@latest node@latest ruby@3 python@latest ### MCP Server ```bash # Run Bear notes MCP server -./bin/ak-mcp.py +~/.dotfiles/bin/ak-mcp.py # The server requires uv and provides Bear database querying functionality ``` ## File Structure Patterns -- **Local overrides**: Files ending in `.local` extend base thoughtbot configurations -- **Host-specific**: `host-*` directories contain machine-specific configurations +- **Dotfiles**: Files in root directory without leading dot (e.g., `zshrc`, `gitconfig`) are symlinked to `~/.*` +- **Host-specific**: Optional files `~/.zshrc.host` and `~/.secrets` are sourced if they exist - **Binary scripts**: `bin/` contains executable utilities with various languages - **Configuration**: `config/` holds application-specific configurations (mise, etc.) +- **Claude Code**: `claude/` contains agents, commands, and settings for Claude Code ## Important Environment Variables @@ -77,7 +88,26 @@ mise use go@latest node@latest ruby@3 python@latest ## Development Workflow Notes -- Changes to dotfiles require `rcup` to re-symlink +- Changes to dotfiles require `mise run setup` to re-symlink (though most already symlinked) - Brewfile changes need `brew bundle install` to apply - Mise configuration changes auto-apply via shell activation -- The setup expects `~/Setup` as the working directory for cloned repositories +- The setup expects `~/.dotfiles` as the working directory for the cloned repository + +## Mise Tasks + +Tasks are defined in `config/mise/config.toml`: + +- `setup` - Create symlinks for all dotfiles (with automatic backup) +- `backup` - Backup existing dotfiles to timestamped directory +- `unmanaged` - Find dotfiles in home directory not managed by this repository + +All tasks support the `TARGET_DIR` environment variable to specify a custom target directory: +```bash +# Test setup in isolated directory +TARGET_DIR=/tmp/dotfiles-test mise run setup + +# Backup from custom location +TARGET_DIR=/custom/path mise run backup +``` + +Run `mise tasks` to see all available tasks. diff --git a/Justfile b/Justfile deleted file mode 100644 index d246732..0000000 --- a/Justfile +++ /dev/null @@ -1,34 +0,0 @@ -# Dotfiles management commands - -# Update thoughtbot dotfiles and refresh RCM links -pull-upstream: - @echo "🔄 Updating thoughtbot dotfiles..." - cd ~/Setup/dotfiles-thoughtbot && git pull - @echo "🔗 Running rcup to refresh dotfile links..." - rcup - @echo "✅ thoughtbot dotfiles updated and RCM refreshed!" - -# Add a file or directory to dotfiles management via RCM -add FILE: - @echo "📁 Adding {{FILE}} to RCM management..." - mkrc {{FILE}} - @echo "🔗 Running rcup to create symlink..." - rcup - @echo "✅ {{FILE}} added to dotfiles!" - -# Find dotfiles in ~ that aren't managed by RCM -unmanaged: - #!/usr/bin/env bash - set -euo pipefail - find ~ -maxdepth 1 -name '.*' -type f | while read file; do - if [ -L "$file" ]; then - # Check if symlink points to dotfiles directories - target=$(readlink "$file") - if [[ "$target" != *"/.dotfiles"* ]] && [[ "$target" != *"/.dotfiles-thoughtbot"* ]]; then - echo "$(basename "$file") (symlink to: $target)" - fi - else - # Regular file, not managed - echo "$(basename "$file")" - fi - done | sort diff --git a/README.md b/README.md index 771a2ef..22f96c7 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,140 @@ -# Dotfiles mk2: an exosuit +# Dotfiles -With a fresh, or even a janky, laptop: +Personal macOS development environment configuration. -## Quickstart +## Features +- **Simple setup**: Single command to symlink all dotfiles +- **Homebrew integration**: Brewfile for package management +- **Mise**: Runtime version management (Go, Node, Ruby, Python, Deno) and task automation +- **Custom tools**: MCP server for Bear notes integration +- **Shell customization**: Zsh with 🍔 prompt + +## Quick Start + +### Fresh Machine Setup + +1. **Clone this repository**: + ```bash + git clone https://github.com/therealadam/dotfiles ~/.dotfiles + ``` + +2. **Run setup**: + ```bash + cd ~/.dotfiles + mise run setup + ``` + +That's it! Your dotfiles are now symlinked to your home directory. + +### What Gets Installed + +The `mise run setup` command creates symlinks for: +- Shell configuration (`.zshrc`) +- Git configuration (`.gitconfig`, `.gitignore`) +- Vim configuration (`.vimrc.bundles`, `.ideavimrc`) +- Tmux configuration (`.tmux.conf`) +- Ruby/Rails tools (`.pryrc`, `.railsrc`, `.rspec`) +- Mise configuration (`~/.config/mise/`) +- Utility scripts (`~/.local/bin/`) +- Claude Code configuration (`~/.claude/`) + +Existing files are automatically backed up to `~/.dotfiles-backup-TIMESTAMP/`. + +## Bootstrap Script + +For a complete fresh machine setup using [thoughtbot/laptop](https://github.com/thoughtbot/laptop): + +```bash +# Install laptop script first +# Then run the laptop customization +./laptop ``` -cd; mkdir setup -curl .../mac > mac -git clone thoughtbot/dotfiles and therealadam/dotfiles -env RCRC=$HOME/Setup/dotfiles-thoughtbot/rcrc rcup -# rcup + +The `laptop` script will: +- Install Homebrew packages from `Brewfile` +- Set up dotfiles via `mise run setup` +- Clean up after installation + +## Common Tasks + +All tasks are managed by Mise. + +### List available tasks +```bash +mise tasks ``` -1. Clone [dotfiles](https://github.com/thoughtbot/dotfiles) and this repo -1a. Into ~/Setup ...may require an initial tweak of dotfiles-thoughtbot/rcrc to use ~/Setup or a one-off rcup invocation... -1b. e.g. `env RCRC=$HOME/Setup/dotfiles-thoughtbot/rcrc rcup` -2. Bootstrap via [laptop](https://github.com/thoughtbot/laptop) -3. Run `mac` again to pick up local customizations that are now symlinked - `script/setup` +### Set up/update dotfiles +```bash +mise run setup +``` -## Imploding an existing setup +### Backup existing dotfiles +```bash +mise run backup +``` +### Find unmanaged dotfiles +```bash +mise run unmanaged ``` -# Uninstall Homebrew; download the script and run with --help if you like -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall)" -# ..extensively manually prune /usr/local +### Test setup in a different directory +```bash +# Create test directory +mkdir -p /tmp/dotfiles-test + +# Run setup to that directory +TARGET_DIR=/tmp/dotfiles-test mise run setup -# Uninstall asdf -rm -rf ~/.asdf +# Verify the symlinks +ls -la /tmp/dotfiles-test +``` + +### Update Homebrew packages +```bash +cd ~/.dotfiles +brew bundle install +``` -# Uninstall mise... +### Update development runtimes +```bash +mise install +mise use go@latest node@latest ruby@3 python@latest ``` -## RCM cheatsheet +## Structure -- Re-link all dotfiles: `rcup` -- Add a new dotfile: `mkrc ` +- `bin/` - Utility scripts +- `claude/` - Claude Code configuration (agents, commands, settings) +- `config/mise/config.toml` - Mise configuration (tools, tasks) +- `Brewfile` - Homebrew package list +- Individual dotfiles (`zshrc`, `gitconfig`, `tmux.conf`, etc.) -## Mise cheatsheet +## Notes + +- The setup expects `~/.dotfiles` as the repository location +- Host-specific secrets can be placed in `~/.secrets` (sourced by zshrc) +- Host-specific zsh config can be placed in `~/.zshrc.host` (sourced by zshrc) +- FZF integration available if `~/.fzf.zsh` exists + +## Mise Tasks + +This dotfiles setup uses Mise for both runtime version management and task automation. Tasks are defined in `config/mise/config.toml`. + +Available tasks: +- `setup` - Create symlinks for all dotfiles (with automatic backup) +- `backup` - Backup existing dotfiles without creating symlinks +- `unmanaged` - Find dotfiles in home directory not managed by this repository + +All tasks support the `TARGET_DIR` environment variable to specify a custom directory: +```bash +# Backup from a custom location +TARGET_DIR=/tmp/test mise run backup + +# Setup to a custom location (useful for testing) +TARGET_DIR=/tmp/test mise run setup +``` -https://mise.jdx.dev/tasks/toml-tasks.html +See the [Mise documentation](https://mise.jdx.dev/tasks/toml-tasks.html) for more information. diff --git a/config/mise/config.toml b/config/mise/config.toml index 4a27a7e..f936574 100644 --- a/config/mise/config.toml +++ b/config/mise/config.toml @@ -1,8 +1,7 @@ -# mise u tool@version [tools] go = "latest" node = "latest" -ruby = "3" +ruby = "latest" python = "latest" deno = "latest" "gem:rails" = "latest" @@ -11,38 +10,157 @@ deno = "latest" [settings] experimental = true -# mise t -# mise r task:name -[tasks."justfile:init"] -description = 'Write Justfile boilerplate' +[tasks.backup] +description = 'Backup existing dotfiles to timestamped directory' run = """ -#!/bin/sh +#!/usr/bin/env bash +set -euo pipefail -cat > ./Justfile <