diff --git a/docs/constitution.md b/docs/constitution.md index 9d67a19..967cbed 100644 --- a/docs/constitution.md +++ b/docs/constitution.md @@ -8,6 +8,7 @@ ## Repository Overview - Architecture: Flake-based repo using `flake-parts` with inputs for pkgs (stable/unstable), stylix, home-manager, sops-nix, and service overlays. Common modules are composed through `parts/core.nix` and `parts/hosts.nix`. - Module auto-import: `modules/modules.nix` auto-imports legacy flat modules under `modules/apps`, `modules/dev`, `modules/scripts`, `modules/servers`, `modules/services`, `modules/shell`, `modules/websites`, and `modules/network`, excluding `librewolf.nix`, and also discovers nested `nixos.nix` files under those trees. `config/base.nix` registers `modules/home-manager.nix` as a Home Manager shared module, which discovers nested `home.nix` files under `modules/` for every Home Manager user. Factories live in `modules/factories/` (`mkserver`, `mkscript`), and shared options are in `modules/nix` and `modules/users`. +- Home Manager helper layer: Common Home Manager wrapper logic belongs in `parts/core.nix` helpers under `inputs.self.lib` when it is repeated across multiple `home.nix` modules. Current helpers include split-loader support plus `hmModule`, `hmShellType`, and `hmOnlyUser` for shared enablement and shell-selection patterns. - Hosts and toggles: Host definitions live in `hosts//configuration.nix` with host-specific toggles in `hosts//toggles.nix`. The `my` namespace carries toggles for apps/dev/scripts/services/shell, feature flags like `enableProxy` and `enableContainers`, and per-host `interfaces` and `ips` maps. - Port assignment: Service ports should live with the service module when the port is intrinsic to a server definition under `modules/servers/`. Miscellaneous or host-specific ports that do not belong to a server module should be centralized in `my.ports` in `modules/modules.nix` and referenced via `config.my.ports.*` (use `toString config.my.ports.*` where a string is required). - Main server and proxies: `my.mainServer` selects the host that should serve traffic by default (default `vps`). Reverse proxies use helpers in `parts/core.nix` (`proxy`, `proxyReverse`, `proxyReverseFix`, `proxyReversePrivate`) and pick IPs from `my.ips` plus the hostName/ip set by `mkserver` options. Nginx defaults to `proxyReverse` for any server with `enableProxy = true` unless `useDefaultProxy = false` or the server is listed in the Fix/Private proxy lists. @@ -49,6 +50,7 @@ config.services = { ## Module Categories and Active Hosts - Module categories: apps, dev, scripts, servers, services, shell, websites, network, users, nix. Factories sit in `modules/factories/` and are imported explicitly; patch artifacts live at the repo root in `patches/`. - Split-module preference: For categories that need both system and Home Manager behavior, co-locate both surfaces in `modules///nixos.nix` and `modules///home.nix`. Keep helpers local to that directory only when they are feature-specific; otherwise promote them into shared helpers/factories. +- Home module helper rule: Extract repeated Home Manager wrapper code into `parts/core.nix` once at least a few modules share the same structure. Keep only feature-specific package lists, files, and service settings inside each `home.nix`. - User config split: Personal configs may also split across `config/.nix` for NixOS-side account/secrets state and `config/-home.nix` for Home Manager-only state imported from the user home module. - Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`, `vps`. Host roles and secure status are defined in `hosts//configuration.nix` and toggles in `hosts//toggles.nix`. diff --git a/docs/playbooks/split-home-manager.md b/docs/playbooks/split-home-manager.md index 9c034f1..668dbcd 100644 --- a/docs/playbooks/split-home-manager.md +++ b/docs/playbooks/split-home-manager.md @@ -8,12 +8,13 @@ 1. Create `modules///nixos.nix` for NixOS-only concerns such as `users.users`, `environment.systemPackages`, `services.*`, `programs.*`, firewall rules, and SOPS-backed system resources. 2. Create `modules///home.nix` for Home Manager concerns such as `programs.*`, `xdg.*`, `home.file.*`, `services.*` within Home Manager, and per-user shell aliases/config files. 3. Keep the toggle namespace aligned across both files so the same feature name remains recognizable. During migration, duplicate the option schema if needed rather than keeping Home Manager logic embedded in the NixOS module. - 4. If the feature has truly shared logic, extract it into a local helper file within the feature directory or promote it into `modules/factories/` when reused across features. + 4. If the feature has truly shared logic, extract it into a local helper file within the feature directory. If the same Home Manager wrapper pattern repeats across multiple features, promote that wrapper logic into `parts/core.nix` helpers instead of cloning the same `osConfig` and shell-selection code. 5. Remove the legacy flat module only after the paired files evaluate cleanly and all references are updated. - Validation: - `modules/modules.nix` discovers the feature’s `nixos.nix`. - `config/base.nix` registers `modules/home-manager.nix` in `home-manager.sharedModules`, and that loader discovers the feature’s `home.nix`. - System-only settings no longer reference `home-manager.users.*`. - Home Manager settings no longer depend on `osConfig` unless that coupling is intentional and documented. + - Repeated HM wrapper logic uses shared helpers from `parts/core.nix` instead of being copied between modules. - Outputs: Split module directory, retained toggle shape, and updated docs if the feature introduces new structure patterns. - References: `docs/constitution.md` (Repository Overview, Terminology and Naming Standards, Maintenance Triggers), `docs/reference/index.md` (Module Directories, Auto-Import Rules) diff --git a/docs/reference/index.md b/docs/reference/index.md index 7ba88d1..c4baf52 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -29,6 +29,14 @@ - Migration rule: Legacy flat `modules//.nix` modules remain supported while features are moved into split directories. - Implication: Place new dual-surface modules in a feature directory so NixOS and Home Manager stay adjacent; no manual import wiring is required unless adding a new factory. +## Home Manager Helpers +- Shared helper home: `parts/core.nix` exports reusable Home Manager helper functions through `inputs.self.lib`. +- Current helpers: + - `hmModule` → derive default HM enablement from `osConfig.my.` and the current Home Manager username. + - `hmShellType` → resolve `bash` vs `zsh` consistently for HM modules with or without `osConfig`. + - `hmOnlyUser` → gate HM snippets to a specific username when a feature is intentionally user-specific. +- Usage rule: Use these helpers for repeated wrapper logic; keep feature-specific package sets and config payloads in local `common.nix` or `home.nix` files. + ## Hosts and Roles - Configs: `hosts//configuration.nix` with toggles in `hosts//toggles.nix`. - Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`, `vps`. diff --git a/specs/001-ai-docs/research.md b/specs/001-ai-docs/research.md index e598ade..b6a2bc9 100644 --- a/specs/001-ai-docs/research.md +++ b/specs/001-ai-docs/research.md @@ -39,3 +39,8 @@ - **Decision**: Support a gradual migration from mixed flat modules to feature directories with paired `nixos.nix` and `home.nix` files, discovered automatically by NixOS and Home Manager import loaders. - **Rationale**: Keeps the current category-first browsing model while removing the need to embed Home Manager config inside NixOS modules, which is a cleaner fit for future standalone Home Manager and Darwin hosts. - **Alternatives considered**: (a) Keep mixed modules and branch on platform forever (rejected: keeps NixOS/Home Manager tightly coupled); (b) Split into separate top-level `modules/nixos` and `modules/home` trees (rejected: loses adjacency between the two surfaces of a single feature). + +## Decision 9 (2026-03-16): Shared helper layer for repeated Home Manager wrapper logic +- **Decision**: Keep split feature modules, but move repeated Home Manager wrapper logic into shared helpers in `parts/core.nix` exposed via `inputs.self.lib`. +- **Rationale**: Reduces boilerplate in `home.nix` modules without losing the explicit split between NixOS-owned and Home Manager-owned behavior. +- **Alternatives considered**: (a) Leave repeated wrapper code in every `home.nix` (rejected: noisy and brittle); (b) hide full feature behavior behind one generic abstraction (rejected: makes modules harder to read and reason about).