Add comprehensive NixOS support with flake and home-manager integration

[truongsinh]

Summary

Enables seamless declarative installation on NixOS via flake, matching Ubuntu's ease of use.

Fixes #104

Changes

• NixOS and home-manager modules for declarative configuration
• Nix flake with overlay for packages
• Comprehensive VM integration tests
• Complete documentation and examples

Benefits

Users can now install Toshy with a simple nixos-rebuild switch after adding to their configuration.

Test Plan

• NixOS module tests pass
• home-manager integration works
• VM integration tests complete successfully
• Documentation is clear and accurate

[RedBearAK]

@truongsinh

This is pretty extensive, and I'm wholly unqualified to say how good the nix parts are. Looks like a lot of work was put into it though, and I like to see all the testing stuff. Testing is usually a good idea.

I'm interested in why the GNOME window manager is apparently not being identified correctly, necessitating this addition to the config file:

elif SESSION_TYPE == 'wayland' and DESKTOP_ENV == 'gnome' and WINDOW_MGR == 'WM_unidentified_by_logic':
    # GNOME Wayland - window manager detection may fail, use DESKTOP_ENV as fallback
    debug(f"GNOME Wayland detected, using DESKTOP_ENV as compositor.", ctx="CG")
    _wl_compositor = 'gnome'

This kind of thing should probably be dealt with in the environment context module. And from what I've encountered the actual window manager/compositor is generally "gnome-shell", not "gnome". Unless something has changed with recent GNOME.

Is the process list not available to the user on NixOS? I can't imagine why else the window manager would be unidentified.

[RedBearAK]

I just made a bunch of changes in the main branch, while implementing support for Gentoo Linux. So you'd need to update this to avoid a conflict, at least in the setup script.

Previous attempts at NixOS support from other Toshy users have been pretty fragile, locking in a specific version/state of Toshy. I'd like to hear about how this PR would handle Toshy updates and changes over time. Particularly around the list of packages that get installed in the Python virtual environment.

[RedBearAK]

I took the provided information about NixOS wrapping processes, confirmed it with some online research, and then put together an update for the environment context module to hopefully accurately deal with process detection in NixOS. I didn't want to completely give up on the exact matching, so it will adjust to the NixOS patterns.

And, inside the keymapper's (different repo) window context module, I added a tuple to allow Mutter to be a valid Wayland compositor value for the GNOME window context provider.

Together these should solve the issue with identifying the WM and using the correct window context method on NixOS GNOME. If you can update, these changes are in the main branch of both repos, and you should see the keymapper version update to 1.11.3, and the env_context module should show "2026-02-02". Both appear in the output of toshy-versions.

Let me know how it goes. This should allow completely removing the adjustments from the config file.

[RedBearAK]

This seems to have two different install paths. The native NixOS flake-only approach, and then the changes to the setup script as an alternative. Is there a reason you didn't add something like this to the package install function, to prevent the need to use "--skip-native"?

def install_distro_pkgs():
    print(f'\n\n§  Installing native packages...\n{cnfg.separator}')
    
    # NixOS: packages managed declaratively, skip native install
    if cnfg.DISTRO_ID == 'nixos':
        print('NixOS detected - native packages managed via configuration.nix')
        print('Skipping native package installation.')
        return
    
    # ... rest of function

Seems like you've thought of pretty much everything else. Are you volunteering to respond to any issues with NixOS support if this were to be integrated into Toshy? I certainly can't do much with it myself, and it will need to be periodically updated.