Refactor Plan

Repository Refactoring & Improvement Plan

This document outlines a strategic plan to address architectural debt, complete the hey toolchain, and polish the desktop experience, based on existing TODOs, FIXMEs, and roadmap documentation.

Phase 1: Architectural Debt & Theme Engine Upgrade

  1. Strictly Typed Theme Submodules
    • Colors: Convert loose mkOpt str color definitions in modules/themes/default.nix into a strict Nix types.submodule to enforce the ANSI + Types specification at evaluation time.
    • Fonts & Wallpapers: Address # TODO: Use submodules and # TODO: Make attrsOf submodule in modules/themes/default.nix to enforce standard schemas.
  2. Deconstruct the Theme Monolith (apps.nix)
    • Split modules/themes/apps.nix into functional categories under modules/themes/apps/ (e.g., browsers.nix, terminals.nix, shell.nix) as per the roadmap.
  3. NixOS System Builder Refactor
    • Address # FIXME: Refactor me! (Use submodules?) in lib/nixos.nix. Utilize submodules for host definitions to make instantiation cleaner and more resilient.

Phase 2: Hey Toolchain & Scripting Completeness

  1. Window Manager Hooks
    • Implement missing hook dispatchers in config/niri/hooks/all.zsh, config/hypr/hooks/all.zsh, and config/bspwm/hooks/all.zsh to handle events like battery or idle correctly per compositor.
  2. Missing Rofi Menus & OSD
    • Complete stubs for config/rofi/bin/powermenu.zsh and emojimenu.sh.
    • Implement # TODO: Favicon lib in config/rofi/bin/vaultmenu.janet.
    • Implement # TODO: Need hey .osd analog for BSPWM in modules/desktop/bspwm.nix.
  3. Toolchain Compilation Robustness
    • Resolve # TODO: Include gcc for 'jpm deps' in modules/hey.nix to ensure native Janet C-modules compile reliably during system activation.

Phase 3: Desktop Polish & Testing

  1. Standardize Screenshot Tooling
    • Address # TODO: Replace maim/slop with flameshot in modules/desktop/bspwm.nix to unify the screenshot experience across X11 and Wayland.
  2. Niri Metadata Parsing
    • Fix # TODO: niri windows metadata doesn't have .at and .size in bin/get-window.zsh by mapping Niri’s IPC JSON structure to match standard scripts.
  3. Flesh out the Janet Test Suite
    • Implement # TODO (deftest ...) stubs in test/hey/lib.janet, test/hey/glob.janet, and test/hey/vars.janet to ensure robust path resolution and state management for the hey CLI.