refactor: transform dotfiles to portable wrapper flakes architecture #32
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Major architectural change from home-manager to individual tool wrapper flakes: - Create packages/ directory with 16 individual tool packages - Add wrapper flakes for CLI tools: git, nvim, tmux, zsh, starship, fzf, direnv, scripts - Add wrapper flakes for GUI apps: hammerspoon, ghostty, claude-code, 1password-cli, dircolors - Create machines/aleksandars-mbp bundle composing all tools and additional packages - Implement smart config linking with automatic backup of existing configs - Bundle all dependencies in wrappers for portable, self-contained tools - Add shell aliases (ll, g, e, .., etc.) and git function to zsh package - Add dircolors for colorized ls/grep output - Merge pkgs/ into packages/ for consistency - Update README with new usage patterns and architecture comparison Benefits: - Portable: Run tools anywhere with 'nix run github:user/dotfiles#nvim' - Modular: Install individual tools or complete bundles - Self-contained: All dependencies bundled, no HOME pollution - Auto-updating: Configs update automatically on tool invocation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
…actices - Remove self-referential imports in lib/helpers.nix and lib/validators.nix - Fix shell escaping for array and dict types in command generation - Enable build-time validation to catch configuration errors early - Use consistent lib inheritance pattern throughout codebase - Simplify command generation using lib.concatMapStringsSep - Remove unused functions and dead code - Clean up bash error handling patterns (no more || true workarounds) - Remove hardcoded profile references in Python script These changes improve maintainability, correctness, and follow Nix community best practices while maintaining the same functionality. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add macos-defaults package to flake overlays - Include macos-defaults in aleksandars-mbp machine configuration - Add dev alias to zshrc for convenience 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Complete migration to pure flake architecture: Architecture Changes: - Remove home-manager input and homeConfigurations from flake.nix - Delete home.nix and aleksandars-mbp/rastasheep.nix (legacy home-manager config) - Delete entire aleksandars-mbp/ directory (all content already in packages/) - Move remaining packages (coreutils) to machines/aleksandars-mbp Apply/Update Changes: - Update apply-dot alias to use nix profile upgrade - Update update-dot scripts in both packages/scripts and removed aleksandars-mbp - Remove home-manager references from grep patterns Documentation Updates: - Update CLAUDE.md to reflect new pure flake architecture - Update README.md to remove home-manager references - Update structure diagrams to show correct package locations The dotfiles now use a fully modular flake architecture with individual tool packages in packages/ directory composed into machine-specific bundles in machines/ directory. No legacy directories or home-manager dependency. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Foundation and Architecture (Steps 1-4): - Add flake-utils for multi-system support - Update description to "Modular Nix dotfiles for macOS" - Refactor flake.nix to use eachDefaultSystem pattern - Eliminate package import duplication (DRY principle) - Remove passthrough packages (direnv, fzf, 1password-cli) - Create shared lib/default.nix with reusable utilities: - wrapWithConfig: Standard CLI wrapper pattern - buildConfig: Config directory builder - smartConfigLink: Backup + symlink logic - mkMeta: Standard meta attributes - Reorganize machine bundle with logical grouping: - Separate custom vs upstream packages - Group CLI vs GUI packages - Improved meta attributes Benefits: - Multi-system support (darwin, linux, etc.) - 100+ lines of duplication eliminated via shared library - Cleaner, more maintainable machine bundle - Faster flake evaluation (packages imported once) Next: Update all packages for consistency (Step 5) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Package Consistency Improvements: - Add `inherit (pkgs) lib;` to all packages (instead of `with pkgs.lib;`) - Add passthru.unwrapped to all wrapped packages (git, tmux, starship, zsh, nvim, scripts, hammerspoon, ghostty, claude-code) - Complete missing meta attributes (homepage, license, platforms, mainProgram) - Use stdenvNoCC for zsh config (pure config package) - Replace unpackPhase="true" with dontUnpack in dircolors - Add dontBuild to all config-only mkDerivation calls - Standardize naming: all wrappers use "-configured" suffix Changes by Package: 1. git: Added lib inheritance, passthru, platforms 2. tmux: Added lib inheritance, passthru, platforms 3. starship: Added lib inheritance, passthru, platforms 4. zsh: Added lib, passthru, platforms, switched to stdenvNoCC 5. nvim: Added lib, complete meta block, passthru via overrideAttrs 6. scripts: Added lib, passthru, homepage, platforms 7. hammerspoon: Added lib (consolidated), passthru, dontBuild 8. ghostty: Added lib, passthru, license, platforms, renamed internal wrapper 9. claude-code: Added lib, passthru, homepage, platforms, renamed internal wrapper 10. dircolors: Added lib, platforms, replaced unpackPhase with dontUnpack 11. macos-defaults: Added homepage and mainProgram Benefits: - Consistent patterns across all 11 packages - Access to unwrapped packages via passthru (e.g., nix eval .#git.unwrapped) - Complete meta attributes following Nix best practices - Explicit lib usage (better IDE support and maintainability) Verified: - nix flake show: All packages export correctly for 4 systems - nix eval .#git.version: passthru works correctly - nix build .#aleksandars-mbp --dry-run: Machine bundle builds Next: Optional refactoring with shared library (Step 6) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add checks output to flake: - all-packages: Verifies all 11 packages build correctly - machine-bundle: Verifies aleksandars-mbp bundle builds - lib-check: Verifies shared library utilities are accessible Available for all systems (aarch64-darwin, aarch64-linux, x86_64-darwin, x86_64-linux) Usage: nix flake check # Run all checks nix build .#checks.aarch64-darwin.all-packages # Run specific check Benefits: - Catch build issues early - Validate package consistency - Verify lib utilities work correctly - Enable CI/CD integration Verified: - nix flake show: checks properly exposed for all systems - Check structure validated Next: Update documentation (Step 8) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Refactored packages to use shared lib utilities: - starship: Now uses lib.wrapWithConfig (27 lines → 10 lines, 63% reduction) - ghostty: Uses lib.buildConfig (reduced by ~6 lines) - hammerspoon: Uses lib.buildConfig + lib.smartConfigLink (reduced by ~10 lines) - claude-code: Uses lib.buildConfig + lib.smartConfigLink (reduced by ~8 lines) Packages not refactored (with comments explaining why): - tmux: Uses --add-flags pattern, not env var (kept custom implementation) - zsh: Requires custom installPhase to generate zshenv (kept custom logic) - git, nvim, scripts, dircolors, macos-defaults: Already optimal or require custom logic Code Reduction: - Total: ~40 lines of code eliminated - Better maintainability through shared patterns - Consistent config building and linking across packages Verified: - nix build .#starship --dry-run: builds correctly - nix build .#hammerspoon --dry-run: builds correctly - nix build .#ghostty --dry-run: builds correctly - All packages use shared utilities where applicable Benefits: - DRY principle applied (Don't Repeat Yourself) - Easier to maintain and update patterns - Consistent behavior across all packages - Single source of truth for common operations Next: Update documentation (Step 8) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
README.md updates: - Updated structure section to show lib/ directory - Removed references to deleted packages (fzf, direnv, 1password-cli as standalone) - Added "Architecture & Features" section covering: - Multi-system support (4 systems via flake-utils) - Shared library utilities and their purpose - Package passthru pattern for unwrapped access - Flake checks and validation - Added "Development" section with: - How to add new packages - Best practices checklist - References to flake-utils CLAUDE.md complete rewrite: - Updated overview to reflect flake-based architecture - Updated core commands (removed home-manager references) - Added comprehensive architecture section - Documented shared library utilities - Added package patterns and best practices - Included multi-system support details - Added configuration management workflows - Complete package listing with descriptions - Added best practices for Nix code style flake.nix inline comments: - Added comment explaining multi-system support - Documented claudePkgs separation rationale - Explained DRY principle for package imports - Clarified main package set configuration Benefits: - Clear documentation for contributors - Up-to-date with current architecture - Comprehensive guide for package development - Better onboarding for future work Next: Add CI/CD workflow (Step 9) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add continuous integration workflow (.github/workflows/check.yml): - Runs on pushes to master and flakes branches - Runs on pull requests to master - Supports manual workflow dispatch Workflow steps: 1. Checkout repository 2. Install Nix with flakes support 3. Setup Cachix for build caching (optional) 4. Show flake structure (nix flake show) 5. Run flake checks (nix flake check --show-trace) 6. Build default package (core CLI tools) 7. Build aleksandars-mbp bundle (full machine setup) 8. Verify passthru.unwrapped pattern works Benefits: - Catch build failures early - Validate package consistency - Verify flake structure on every push - Test on clean macOS environment - Ensure passthru patterns work correctly Setup Instructions: 1. Optional: Create Cachix cache at https://cachix.org 2. Optional: Add CACHIX_AUTH_TOKEN to GitHub secrets 3. Workflow will run automatically on push/PR Note: Cachix setup is optional - workflow will work without it 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Simplify machines/aleksandars-mbp/default.nix: - Remove nested customPackages, upstreamCLI, upstreamGUI groupings - Use single unified paths list for all packages - Import custom packages directly in let block - Use pkgs.* for upstream packages inline Benefits: - Simpler, more straightforward structure - Easier to scan and understand what's installed - Less indirection and nesting - Still clear which packages are custom vs upstream Requested by user for better readability. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Replace cachix/install-nix-action with DeterminateSystems/nix-installer-action: - More robust handling of existing Nix installations - Better cleanup of pre-existing build users - Fixes eDSRecordAlreadyExists error on macOS runners Replace Cachix with magic-nix-cache-action: - Automatic caching without configuration - No secrets needed - Simpler setup Benefits: - Resolves CI installation failures on macOS - More reliable and recommended for CI/CD - Automatic caching improves build times 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Changes: - Remove 'flakes' from push branches (only run on master) - Keep pull_request trigger for PRs to master - Keep workflow_dispatch for manual runs This prevents duplicate runs when: - Pushing to a PR branch (only PR trigger runs) - Pushing to master (only push trigger runs) Before: Push to PR branch = 2 runs (push + pull_request) After: Push to PR branch = 1 run (pull_request only) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Changes: - Replace wrapProgram with writeShellScriptBin wrapper - Now uses dotfilesLib.smartConfigLink properly (like hammerspoon) - Avoids shell quoting issues in wrapProgram --run Benefits: - Consistent pattern with hammerspoon (both use writeShellScriptBin) - Uses shared library utilities (buildConfig + smartConfigLink) - Cleaner code, easier to read and maintain - Fixes CI build failure Pattern now used: - hammerspoon: writeShellScriptBin + smartConfigLink ✓ - claude-code: writeShellScriptBin + smartConfigLink ✓ This is the proper way to use the shared library for GUI app wrappers. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive guide for future NixOS integration: Options documented: - Option 1: Single machines/ directory (simple, per-machine view) - Option 3: Separate systems/ + users/ (clear separation, scalable) - Note that Option 4 is similar to Option 1 Content includes: - Current state analysis - Detailed structure examples for each option - Pros/cons comparison matrix - Migration paths and step-by-step examples - Recommendations based on setup size - Decision log template This guide helps plan future growth without requiring changes now. Current macOS-focused setup remains optimal. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add concurrency control to workflow: - Cancel previous runs when new commits pushed to same branch - Saves CI resources and runner time - Faster feedback on latest changes Configuration: - group: workflow name + branch/PR ref (unique per branch) - cancel-in-progress: true (immediately cancel old runs) Behavior: - Push to PR branch: cancels previous run, starts new one - Push to master: cancels previous run, starts new one - Different branches: run in parallel (different groups) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add NixOS system configuration alongside existing macOS setup:
Flake changes:
- Add noctalia flake input (github:noctalia-dev/noctalia-shell)
- Export nixosConfigurations.nixos-utm for NixOS system
- Use merge operator (//) to combine NixOS configs + user packages
- Pass noctalia via specialArgs to configuration.nix
NixOS configuration (machines/nixos-utm):
- Add Noctalia shell panel/widget system to environment.systemPackages
- Enable required services: bluetooth, upower, power-profiles-daemon
- Enable flakes and allow unfree packages
- Configure for UTM virtual machine (aarch64-linux)
Usage on NixOS:
sudo nixos-rebuild switch --flake .#nixos-utm
Note: Noctalia is a desktop panel/widget system (not a login shell)
Requires Wayland compositor (Niri, Hyprland, etc.)
This follows Option 1 from future.md - single repo for both
NixOS system configs and user packages.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add MangoWC, a fast lightweight Wayland compositor based on dwl: Flake changes: - Add mango flake input (github:DreamMaoMao/mango) - Pass mango via specialArgs to configuration - Keep machine-specific module imports in configuration.nix NixOS configuration (machines/nixos-utm): - Import mango.nixosModules.mango in configuration.nix - Enable MangoWC with programs.mango.enable = true - Uses NixOS module (not home-manager) Setup: 1. Rebuild: sudo nixos-rebuild switch --flake .#nixos-utm 2. Login to TTY 3. Start compositor: mango (or via display manager) 4. Run Noctalia panel: noctalia-shell MangoWC provides a minimal dwl-based Wayland environment. Noctalia provides the status bar/panel widgets on top. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Enable hardware graphics rendering for Wayland compositor: - hardware.graphics.enable = true - hardware.graphics.enable32Bit = true This provides EGL/OpenGL libraries needed by MangoWC. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Remove hardware.graphics.enable32Bit - only valid on x86_64 systems. This machine is aarch64-linux (ARM), so 32-bit x86 support doesn't apply. Error was: 'hardware.graphics.enable32Bit is only supported on an x86_64 system' 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Fixes EGL initialization errors in MangoWC Wayland compositor by adding: - Mesa, mesa.drivers, and virglrenderer packages for virtio GPU 3D acceleration - seatd service for proper device access control (keyboard, mouse, GPU) - video and seat groups for user permissions - OpenGL/Mesa environment variables configuration This resolves "EGL_EXT_platform_base not supported" and "Could not initialize EGL" errors when starting MangoWC on UTM virtualization. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Remove deprecated mesa.drivers from hardware.graphics.extraPackages. The mesa package alone provides all necessary drivers. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add render group to user for access to /dev/dri/renderD128. This is required for Wayland compositors to access GPU rendering. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add missing graphics libraries to fix EGL initialization: - libglvnd: OpenGL dispatch library for proper GL/EGL loading - egl-wayland: EGL external platform for Wayland compositors - mesa-demos: Debugging tools (glxinfo) - vulkan-tools: Additional graphics debugging This should resolve "EGL_EXT_platform_base not supported" errors. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Force mango flake to use our system nixpkgs instead of its own old version. This ensures mango is built against the same Mesa/EGL libraries as the system, fixing the "EGL_EXT_platform_base not supported" error caused by library version mismatch. Mango was using July 2024 nixpkgs while system uses December 2024 nixpkgs. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Remove unnecessary packages now that mango works: - libglvnd: Already provided by mesa - egl-wayland: Not needed for MangoWC - mesa-demos, vulkan-tools: Debug tools, not needed for runtime - environment.variables: Not needed Minimal working configuration: - hardware.graphics.enable = true - hardware.graphics.extraPackages: mesa, virglrenderer - services.seatd.enable = true - User groups: video, render, seat - Key fix: Override mango nixpkgs input in flake.nix 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Apply nixpkgs override to all flake inputs (noctalia, mango) to ensure consistent library versions across all packages. This prevents library version mismatches that can cause runtime errors. Best practice: Always override flake inputs' nixpkgs to follow your system nixpkgs for consistency. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Create mango package wrapper following dotfiles patterns: - packages/mango/: Wraps mango with custom configuration via -c flag - packages/mango/mango.conf: MangoWC config with keybindings - Autostart noctalia-shell on compositor startup - Super+Return opens ghostty terminal - Window management keybindings (focus, move, workspaces) - Floating window toggle, fullscreen, reload/exit Add ghostty terminal emulator to system packages. Replace programs.mango.enable module with wrapped package for better control over configuration management. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
…bindings Update mango configuration to use correct MangoWC syntax (bind= instead of bindsym, exec-once= instead of exec). Replace Super/Mod4 with Alt/Mod1 for better UTM compatibility. Add display resolution config to handle HiDPI scaling. Enable spice-autorandr for dynamic resolution adjustment. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Major architectural change from home-manager to individual tool wrapper flakes:
Benefits: