Author: johnstegeman

.claude/settings.local.json

@@ -10,7 +10,23 @@
       "mcp__memory__write-cypher",
       "mcp__memory__read-cypher",
       "Skill(jujutsu)",
-      "Bash(ls:*)"
+      "Bash(ls:*)",
+      "Bash(find /Users/jstegeman/Projects/dfiles -name symlink_*)",
+      "Bash(find /Users/jstegeman/Projects/dfiles/source -name symlink_*)",
+      "Bash(find /Users/jstegeman/Projects/dfiles -path */source/* -name symlink_*)",
+      "Bash(find /Users/jstegeman/Projects/dfiles -path */source/* -iname *settings*)",
+      "Bash(find /Users/jstegeman/Projects/dfiles/source -name *.tmpl)",
+      "Bash(python3 -m json.tool --no-indent)",
+      "Read(//Users/jstegeman/.haven/**)",
+      "Read(//Users/jstegeman/**)",
+      "Bash(python3 -m json.tool)",
+      "Bash(haven --version)",
+      "Bash(git -C /Users/jstegeman/Projects/dfiles log --oneline --all)",
+      "Bash(haven apply:*)",
+      "Bash(grep -r \"maccask\\\\|class OS\\\\|module OS\" /Users/jstegeman/Projects/dfiles --include=*.rs --include=*.toml --include=*.md)",
+      "WebFetch(domain:yadm.io)",
+      "Bash(jj diff:*)",
+      "Bash(grep -v \"^+++\\\\|^+use\\\\|^+ *//\\\\|^+ *$\")"
     ]
   }
 }

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'CHANGELOG.md'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+
+      - name: Install dependencies
+        run: pip install mkdocs mkdocs-include-markdown-plugin
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

.gitignore

@@ -1,3 +1,4 @@
 /target
+/site
 .gstack/
 .claude/settings.local.json

CHANGELOG.md

@@ -11,6 +11,43 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [v0.5.5] — 2026-03-24
+
+### Added
+
+- **Brewfile auto-sort** — set `[homebrew] sort = true` in any module config to
+  keep the Brewfile sorted alphabetically after every `haven brew install` or
+  `haven brew uninstall`. Each kind (`tap`, `brew`, `cask`) is sorted
+  independently; blank lines and comments are preserved in place.
+- **`haven apply` Brewfile summary** — the apply summary now reports how many
+  Brewfiles were run: `Applied N file(s), M Brewfile(s) across K module(s)`.
+- **`haven status` improvements** — the profile name is now printed at the top
+  of status output. A `✓ Everything up to date` message is shown when no drift
+  is found.
+- **`haven import` symlink warning** — after importing from chezmoi, a summary
+  of all imported `symlink_` entries is printed with a reminder to verify
+  symlink targets before running `haven apply`.
+- **Documentation site** — full MkDocs documentation at
+  [johnstegeman.github.io/haven](https://johnstegeman.github.io/haven), covering
+  concepts, task-oriented guides, a reference section, and a dedicated
+  "For chezmoi Users" section. Deployed automatically via GitHub Actions.
+
+### Fixed
+
+- **Symlink idempotency** — `haven apply` no longer re-writes a symlink that
+  already points to the correct target. Previously it would overwrite and
+  count the file even when nothing changed.
+- **Dangling symlink backup** — `haven apply` no longer attempts to back up a
+  dangling symlink (one whose target has been deleted) before overwriting it.
+  `std::fs::copy` follows symlinks and would fail; the dangling link is now
+  removed directly.
+- **`brew bundle install` output** — spurious `Using <formula>` lines from
+  `brew bundle` are now suppressed. Output is streamed in real time instead of
+  being buffered until completion.
+- **Unused import** — removed unused `serde_yaml` import in `chezmoi.rs`.
+
+---
+
 ## [v0.5.0] — 2026-03-23
 
 ### Added

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "haven"
-version = "0.5.0"
+version = "0.5.5"
 edition = "2021"
 description = "AI-first dotfiles & environment manager"
 license = "MIT"

Cargo.toml

@@ -2,6 +2,10 @@
   <img src="assets/logo-wide.svg" width="520" height="100" alt="haven — AI-first dotfiles &amp; environment manager"/>
 </p>
 
+<p align="center">
+  <a href="https://johnstegeman.github.io/haven">Documentation</a>
+</p>
+
 ---
 
 **haven** is a declarative, AI-first developer environment manager. It tracks your

README.md

@@ -0,0 +1,156 @@
+# Auto-Sort Brewfiles: Design Document
+
+## Summary
+
+Add an optional configuration to automatically sort Brewfile formulas alphabetically when the user enables auto-sorting.
+
+---
+
+## Motivation
+
+**Problem:** Unsorted Brewfiles can make it hard to:
+- Spot missing dependencies (no obvious gaps)
+- See where a new formula should be added
+- Quickly scan for duplicate formulas
+
+**Reference:** Telemetry entry Q000001 raised this question.
+
+---
+
+## Design Options
+
+### Option A: Opt-in Auto-Sort (Recommended)
+
+**Configuration:**
+```toml
+[brewfiles]
+sort = "on"  # or "off" (default)
+```
+
+**Behavior:**
+- When enabled, `haven apply` re-sorts formulas after `brew bundle dump`
+- Formulas are sorted by their name (short name without version prefix)
+- Comments and anchors are preserved in place
+
+**Pros:**
+- Simple, predictable behavior
+- Easy to opt-out per-module
+- Minimal complexity
+
+**Cons:**
+- Requires explicit opt-in
+- May need to migrate existing Brewfiles
+
+### Option B: Smart Re-Sort
+
+**Behavior:**
+- Same as Option A, but preserves formatting (tabs vs spaces, line length)
+- Anchors (`^anchor`) maintain position but are noted in comments
+- Comments referencing specific formulas move with them
+
+**Pros:**
+- Respects user's style preferences
+- Anchors remain valid after re-sort
+
+**Cons:**
+- More complex implementation
+- Edge cases around comment preservation
+
+### Option C: Hybrid (Per-Module)
+
+**Configuration:**
+```toml
+[[module]]
+name = "packages"
+sort = "on"
+
+[[module]]
+name = "my-custom-brew"
+sort = "off"
+```
+
+**Pros:**
+- Fine-grained control
+- Can mix sorted and unsorted Brewfiles
+
+**Cons:**
+- More configuration options
+- Users might not need this level of control
+
+---
+
+## Recommended Implementation
+
+**Start with Option A** — simple opt-in sorting.
+
+**Phase 1:** Basic sort after `brew bundle dump`
+**Phase 2:** Add comment preservation (if feasible)
+**Phase 3:** Per-module control (if requested)
+
+---
+
+## Implementation Notes
+
+### Where to integrate
+
+The sorting should happen in `brew::dump()` in `src/lib.rs`, after the `brew bundle dump` command:
+
+```rust
+pub fn dump(path: &Path, output: &str) -> Result<()> {
+    // 1. Write to Brewfile.tmp
+    // 2. Run "brew bundle dump --file=Brewfile"
+    // 3. If sort is enabled:
+    //    - Read Brewfile.tmp
+    //    - Extract formulas and comments
+    //    - Sort formulas by name
+    //    - Reconstruct with comments in place
+    // 4. Replace original Brewfile
+}
+```
+
+### Handling comments and anchors
+
+Brewfile examples:
+```ruby
+# This is a comment
+^anchor: some-anchor
+
+homebrew/cask-fonts # @homebrew/cask-fonts
+```
+
+On sort:
+- Keep `^anchor:` lines exactly where they are
+- Move `homebrew/cask-fonts` to its sorted position
+- Keep comments with their formulas
+- Orphaned comments could become: `# (moved from line X)`
+
+---
+
+## UX Considerations
+
+1. **Migration path:** When enabling auto-sort, suggest running `haven apply --remove-unreferenced-brews` to clean up first.
+
+2. **Dry-run mode:** `haven apply --dry-run --sort-brews` to preview the sorting effect.
+
+3. **Undo:** Keep a backup of the unsorted version temporarily; offer `haven undo --brews` to revert.
+
+4. **Documentation:** Add note to `COMMANDS.md` about the sort option when enabled.
+
+---
+
+## Acceptance Criteria
+
+- [ ] Config option works correctly
+- [ ] Formulas are sorted by short name (without `homebrew/tap/` prefix)
+- [ ] Comments are preserved (either attached to formulas or marked as moved)
+- [ ] Anchors remain valid after sort
+- [ ] Existing unsorted Brewfiles still work (opt-in)
+- [ ] Unit tests cover sorting logic
+
+---
+
+## Open Questions
+
+1. Should we preserve the exact line width and formatting of the original Brewfile?
+2. How to handle formulas that get added/removed between `brew bundle update` and `brew bundle dump`?
+3. Should we provide a CLI flag `--sort-brews` for manual sorting?

design_auto_sort_brewfiles.md

@@ -0,0 +1,3 @@
+{%
+   include-markdown "../CHANGELOG.md"
+%}