nix/IMPLEMENTATION_PLAN.md

Implementation Plan - Nix Flake Improvements

Overview

Consolidated plan from:

• AWESOME_NIX_PLAN.md - Awesome-nix integration
• DRUPOL_INFRA_ANALYSIS.md - Reference patterns
• OPENCODE.md - Tracking document

✅ Completed

Code Quality

• ✅ GitHub Actions CI (.github/workflows/flake-check.yaml)
• ✅ Nix-native git hooks (modules/git-hooks/default.nix)
• ✅ nixfmt integration (runs on commit and CI)
• ✅ .editorconfig (unified code style)

Declarative Setup

• ✅ Git hooks auto-install on nixos-rebuild switch
• ✅ No devShell (fully NixOS activation-based)
• ✅ Hooks enabled on andromache and astyanax

📋 Pending Implementation

Phase 1: Enhanced Code Quality (Week 1)

Priority: HIGH ✅ In Progress

#	Task	Effort	Impact	Details	Status
1.1	Add statix hook	Low	High	Lint for Nix antipatterns	✅ Done
1.2	Add deadnix hook	Low	High	Find dead code in Nix files	✅ Done
1.3	Enable git-hooks on all hosts	Very Low	Medium	Add to hecuba, eetion, vm	✅ Done

Implementation:

# flake.nix
checks.${system}.pre-commit-check.hooks = {
  nixfmt-rfc-style.enable = true;  # ✅ Already done
  statix.enable = true;             # Add this
  deadnix.enable = true;            # Add this
};

Phase 2: CI/CD Enhancements (Week 2)

Priority: HIGH

| # | Task | Effort | Impact | Details | |---|-------|--------|---------| | 2.1 | Add CI caching | Medium | High | Speed up GitHub Actions builds | | 2.2 | Add automated flake.lock updates | Medium | Medium | Weekly scheduled updates | | 2.3 | Add per-host CI checks | Medium | Medium | Test specific NixOS configs in CI |

2.1 CI Caching:

# .github/workflows/flake-check.yaml
- uses: actions/cache@v4
  with:
    path: /nix/store
    key: ${{ runner.os }}-nix-${{ hashFiles('**') }}

2.2 Automated Updates:

# .github/workflows/update-flake-lock.yaml
name: "Auto update flake lock"
on:
  schedule:
    - cron: "0 12 * * 0"  # Weekly
jobs:
  update:
    steps:
      - uses: actions/checkout@v6
      - uses: cachix/install-nix-action@v31
      - run: nix flake update
      - uses: peter-evans/create-pull-request@v6

Phase 3: Developer Experience (Week 3)

Priority: MEDIUM

| # | Task | Effort | Impact | Details | |---|-------|--------|---------| | 3.1 | Add nil/nixd LSP | Low | Medium | Autocompletion, error highlighting | | 3.2 | Add nix-index + comma | Low | Medium | Run any binary without nix run | | 3.3 | Add nh | Low | Medium | Better CLI output for nix commands |

3.1 LSP Setup:

# Add to nvim config or home-manager
services.lsp.servers.nil = {
  enable = true;
  package = pkgs.nil;
};

3.2 nix-index:

nix-index
git clone https://github.com/nix-community/nix-index

Phase 4: Utility Tools (Week 4)

Priority: LOW

| # | Task | Effort | Impact | Details | |---|-------|--------|---------| | 4.1 | Add nix-tree | Very Low | Low | Browse dependency graph | | 4.2 | Add nix-du | Very Low | Low | Visualize GC roots | | 4.3 | Add nix-init | Low | Low | Generate packages from URLs | | 4.4 | Add nix-update | Low | Low | Update package versions |

Phase 5: Structural Improvements (Future)

Priority: LOW-MEDIUM

| # | Task | Effort | Impact | Details | |---|-------|--------|---------| | 5.1 | Migrate to flake-parts | Medium-High | High | Automatic module discovery | | 5.2 | Add treefmt-nix | Medium | Medium | Unified project formatting | | 5.3 | Add nix-direnv | Low | Medium | Auto-load dev environments |

📊 Implementation Status

Code Quality

Feature	Status	File
CI (GitHub Actions)	✅ Done	.github/workflows/flake-check.yaml
Git hooks (Nix-native)	✅ Done	modules/git-hooks/default.nix
nixfmt	✅ Done	Enabled in hooks
statix	✅ Done	Phase 1.1 complete
deadnix	✅ Done	Phase 1.2 complete
All hosts enabled	✅ Done	Phase 1.3 complete
CI caching	⏳ Pending	Phase 2.1
Auto flake updates	⏳ Pending	Phase 2.2

Hosts with Git Hooks

Host	Status	Config
andromache	✅ Enabled	hosts/andromache/default.nix
astyanax	✅ Enabled	hosts/astyanax/default.nix
hecuba	✅ Enabled	hosts/hecuba/default.nix
eetion	✅ Enabled	hosts/eetion/default.nix
vm	✅ Enabled	hosts/vm/default.nix

Developer Tools

Tool	Status	Phase
nil/nixd	⏳ Pending	3.1
nix-index	⏳ Pending	3.2
nh	⏳ Pending	3.3
nix-tree	⏳ Pending	4.1
nix-du	⏳ Pending	4.2
nix-init	⏳ Pending	4.3
nix-update	⏳ Pending	4.4

Structure

Feature	Status	Phase
flake-parts	⏳ Pending	5.1
treefmt-nix	⏳ Pending	5.2
nix-direnv	⏳ Pending	5.3
.editorconfig	✅ Done	Already added

🎯 Quick Wins (Day 1)

If you want immediate value, start with:

1. Enable git-hooks on remaining hosts (5 minutes)

# Add to hosts/hecuba/default.nix, eetion/default.nix, vm/default.nix
imports = [
  # ... existing modules
  ../../modules/git-hooks
];

services.git-hooks.enable = true;

2. Add statix hook (10 minutes)

# Edit flake.nix
checks.${system}.pre-commit-check.hooks = {
  nixfmt-rfc-style.enable = true;
  statix.enable = true;  # Add this
};

3. Add deadnix hook (10 minutes)

# Edit flake.nix
checks.${system}.pre-commit-check.hooks = {
  nixfmt-rfc-style.enable = true;
  statix.enable = true;
  deadnix.enable = true;  # Add this
};

📚 References

• CI_HOOKS_SUMMARY.md - Current CI/hooks setup
• AWESOME_NIX_PLAN.md - Awesome-nix integration
• DRUPOL_INFRA_ANALYSIS.md - Reference patterns
• OPENCODE.md - Original tracking

🚀 Implementation Order

Recommended sequence:

1. Phase 1 (Week 1) - Enhanced code quality
2. Phase 2 (Week 2) - CI/CD improvements
3. Phase 3 (Week 3) - Developer experience
4. Phase 4 (Week 4) - Utility tools
5. Phase 5 (Future) - Structural changes

🔄 Updates

As items are completed, update the status in this document and check off in:

• AWESOME_NIX_PLAN.md
• OPENCODE.md
• CI_HOOKS_SUMMARY.md