|
1 | | -# AI Agent Guide: Dotfiles Architecture |
2 | | - |
3 | | -Cross-platform dotfiles using two-tier profiles (shared base + OS-specific overrides) and GNU Stow for config symlinks. |
4 | | - |
5 | | -## Flow: setup.sh → OS detection → install_profile("shared") → install_profile(OS_variant) |
6 | | - |
7 | | -**Core files**: `setup.sh` (orchestrator), `utils.sh` (install/stow_link/install_profile), `variants/*/setup.sh` (packages), `variants/*/profile.sh` (shell config) |
8 | | - |
9 | | -## OS Detection (setup.sh:17-36) |
10 | | -Linux → /etc/arch-release or pacman → archlinux | else → debian |
11 | | -Overrides: $TERMUX_VERSION → termux | lsb_release=Ubuntu → ubuntu |
12 | | -Darwin → osx |
13 | | - |
14 | | -## Variants (variants/*) |
15 | | -**Inheritance**: shared sourced FIRST → OS-specific (allows function shadowing) |
16 | | - |
17 | | -| Variant | PM | Stow Configs | Notes | |
18 | | -|---------|----|--------------| ------| |
19 | | -| shared | agnostic | alacritty | Base: git, rg, fd, gh, fzf, zellij | |
20 | | -| debian | apt | claude, alacritty-debian, nvim | Core tools, ollama | |
21 | | -| ubuntu | apt | Same as debian | + devbox, shortcuts.sh (GNOME keys) | |
22 | | -| osx | brew | 7 pkgs (aerospace, sketchybar, etc) | Generates zellij os.toml | |
23 | | -| archlinux | pacman+yay | waybar, wireplumber | AUR helper, 20+ pac*/yay* functions | |
24 | | -| termux | pkg | None | Android-specific, redefined killport/network | |
25 | | -| omarchy | pacman | hypr, zellij-omarchy | Setup-only, modifies Hypr bindings | |
26 | | - |
27 | | -## Stow System (configs/ → ~/) |
28 | | -16 packages mirror home structure: `configs/nvim/.config/nvim/`, `configs/alacritty/.config/alacritty/` |
29 | | -**stow_link()** (utils.sh:124-148): auto-removes conflicts, uses --restow fallback |
30 | | -**Override pattern**: base (alacritty, zellij) + OS variants (alacritty-osx, zellij-omarchy) |
31 | | - |
32 | | -## install_profile() (utils.sh:29-44) |
33 | | -1. Run variants/$variant/setup.sh |
34 | | -2. Copy profile.sh → ~/.dotfiles_$variant |
35 | | -3. Source in shell: `[[ -f ~/.dotfiles_$variant ]] && source ~/.dotfiles_$variant # zeachco-dotfiles` |
36 | | - |
37 | | -**clean_imports()**: strips old `# zeachco-dotfiles` lines before reinstall |
38 | | - |
39 | | -## Key Functions (variants/shared/profile.sh) |
40 | | -**clone [repo]**: GitHub shorthand | **killport [port]**: kill process | **check_for_devbox()**: auto-enters devbox shell |
41 | | -**Git**: gco, gs, gd, gci, gp (via `_set` - prints before exec) | **_worktrees.sh**: jira_claude, zellij integration |
42 | | -**OS-specific**: archlinux (pacup, yayin), osx (docker wrapper, dark mode), termux (battery, notify) |
43 | | - |
44 | | -## Testing |
45 | | -`bash ~/dotfiles/setup.sh` (full) | `dotfiles_update` (remote pull) | `source ~/.zshrc` (reload) |
46 | | - |
47 | | ---- |
48 | | - |
49 | | -## Neovim/LazyVim: Make .git and .github Directories Visible |
50 | | - |
51 | | -**Problem:** In LazyVim, `.git` and `.github` directories are hidden from both the file tree (Neo-tree) and fuzzy finder (Telescope). |
52 | | - |
53 | | -**Solution:** Create `/lua/plugins/git-visibility.lua` with the following configuration: |
54 | | - |
55 | | -```lua |
56 | | -return { |
57 | | - -- Configure Telescope to show .git and .github directories |
58 | | - { |
59 | | - "nvim-telescope/telescope.nvim", |
60 | | - opts = { |
61 | | - defaults = { |
62 | | - file_ignore_patterns = { |
63 | | - "node_modules/", |
64 | | - ".devbox/nix/", |
65 | | - ".venv/", |
66 | | - -- Removed .git and .github from ignore patterns |
67 | | - }, |
68 | | - hidden = true, -- Show hidden files |
69 | | - }, |
70 | | - pickers = { |
71 | | - find_files = { |
72 | | - hidden = true, |
73 | | - -- Remove .git and .github from find_files ignore patterns |
74 | | - find_command = { "rg", "--files", "--hidden", "--glob", "!**/.git/*", "--glob", "!**/.DS_Store" }, |
75 | | - }, |
76 | | - }, |
77 | | - }, |
78 | | - }, |
79 | | - |
80 | | - -- Configure Neo-tree to show .git and .github directories |
81 | | - { |
82 | | - "nvim-neo-tree/neo-tree.nvim", |
83 | | - opts = { |
84 | | - filesystem = { |
85 | | - filtered_items = { |
86 | | - visible = true, -- Show filtered items |
87 | | - hide_dotfiles = false, |
88 | | - hide_gitignored = false, |
89 | | - hide_by_name = { |
90 | | - -- Remove .git and .github from hidden items |
91 | | - ".DS_Store", |
92 | | - "thumbs.db", |
93 | | - }, |
94 | | - hide_by_pattern = { |
95 | | - -- You can add patterns here if needed |
96 | | - }, |
97 | | - always_show = { |
98 | | - ".git", |
99 | | - ".github", |
100 | | - ".gitignore", |
101 | | - ".gitattributes", |
102 | | - }, |
103 | | - never_show = { |
104 | | - ".DS_Store", |
105 | | - "thumbs.db", |
106 | | - }, |
107 | | - }, |
108 | | - follow_current_file = { |
109 | | - enabled = true, |
110 | | - }, |
111 | | - }, |
112 | | - }, |
113 | | - }, |
114 | | -} |
| 1 | +# AI Agent Guide: Rust Dotfiles Architecture |
| 2 | + |
| 3 | +Cross-platform dotfiles with a POSIX bootstrap, a dependency-free Rust CLI, |
| 4 | +declarative TOML profiles, generated shell adapters, and GNU Stow. |
| 5 | + |
| 6 | +## Flow |
| 7 | + |
| 8 | +`setup.sh → bootstrap Rust → cargo build --locked → dotfiles apply` |
| 9 | + |
| 10 | +The Rust CLI detects the platform and account login shell, composes the shared |
| 11 | +and platform profiles, displays a plan, applies confirmed actions, and saves the |
| 12 | +selection to `~/.config/dotfiles/state.toml`. |
| 13 | + |
| 14 | +## Source of truth |
| 15 | + |
| 16 | +- `src/`: detection, parser/model, apply engine, shell rendering, CLI helpers |
| 17 | +- `manifests/profiles/`: shared policy plus OS/environment overlays |
| 18 | +- `manifests/shell.toml`: portable aliases, exports, and PATH entries |
| 19 | +- `manifests/shell/`: platform-specific alias overlays |
| 20 | +- `configs/`: Stow packages mirroring the home directory |
| 21 | + |
| 22 | +Profiles inherit as `shared → family → overlay`: Ubuntu inherits Debian; |
| 23 | +Omarchy inherits Arch; WSL is detected as an environment on its Linux distro. |
| 24 | + |
| 25 | +The manifest parser intentionally accepts a small TOML subset: quoted strings, |
| 26 | +quoted-string arrays, and named sections. Keep arrays on one line and package |
| 27 | +entries in `command|apt|pacman|brew|pkg` form. |
| 28 | + |
| 29 | +## Invariants |
| 30 | + |
| 31 | +- Never run package-manager full upgrades during setup. |
| 32 | +- Never reset or discard a dirty dotfiles checkout. |
| 33 | +- Validate every referenced Stow package before applying any changes. |
| 34 | +- Back up conflicting Stow targets rather than deleting them. |
| 35 | +- Keep `~/.config` physical and use Stow's `--no-folding`; generated state and |
| 36 | + shell files must never be written through a folded package directory. |
| 37 | +- Configure only the account's default Bash, Zsh, or Fish shell. |
| 38 | +- Preserve public shortcut names through native aliases or Rust subcommands. |
| 39 | +- Do not hand-edit generated files under `~/.config/dotfiles/generated/`. |
| 40 | +- Keep the Rust CLI dependency-free unless a dependency is strongly justified |
| 41 | + across macOS, glibc Linux, WSL, and native Termux. |
| 42 | + |
| 43 | +## Verification |
| 44 | + |
| 45 | +```sh |
| 46 | +cargo test --locked |
| 47 | +cargo build --release --locked |
| 48 | +sh -n setup.sh |
| 49 | +for p in debian ubuntu archlinux osx termux omarchy; do |
| 50 | + DOTFILES_PLATFORM=$p DOTFILES_SHELL=fish target/release/dotfiles plan |
| 51 | +done |
| 52 | +target/release/dotfiles shell render bash | bash -n |
| 53 | +target/release/dotfiles shell render zsh | zsh -n |
| 54 | +target/release/dotfiles shell render fish | fish -n |
| 55 | +git diff --check |
115 | 56 | ``` |
116 | 57 |
|
117 | | -**What this fixes:** |
118 | | -- Makes `.git` and `.github` directories visible in Neo-tree file explorer |
119 | | -- Makes `.git` and `.github` directories searchable with Telescope fuzzy finder |
120 | | -- Shows hidden files while still excluding unnecessary files like `.DS_Store` |
121 | | -- Allows browsing git-related files and GitHub workflows/actions |
122 | | - |
123 | | -**Usage:** Place this file in your Neovim config at `~/.config/nvim/lua/plugins/git-visibility.lua` and restart Neovim. |
| 58 | +Tests and planning may use `DOTFILES_PLATFORM` and `DOTFILES_SHELL`; normal |
| 59 | +installation must use real platform and account-shell detection. |
0 commit comments