diff --git a/.github/instructions/host-naming-report.md b/.github/instructions/host-naming-report.md new file mode 100644 index 0000000..96e35e7 --- /dev/null +++ b/.github/instructions/host-naming-report.md @@ -0,0 +1,68 @@ +# Host Naming Discrepancy Report + +This report compares the current `modules/hosts` tree against the naming rules for new hosts in `hosts.instructions.md`. + +## Rules Checked + +- The host directory slug should be the canonical host identity. +- A directory-backed host should prefer `default.nix` as its main entrypoint. +- The canonical slug should line up with the primary `hostname` binding, `flake.nixosConfigurations.`, and `networking.hostName`. +- A host-local Home Manager module should use the same slug. +- A standalone Home Manager configuration should prefer the key `"@"`. +- Host-local helper module names should be prefixed by the host slug. + +## Summary + +- Recently normalized: `john-kde`, `omen-nixos`. +- Hosts that fit the new rules closely: `janus`, `john-kde`, `omen-nixos`, `test-nix`. +- Hosts with notable discrepancies: `john-p14s`, `soteria`. +- Approved exception: `john-pc` directory uses immutable deployed slug `john-pc-ubuntu` for exported keys. + +## Detailed Discrepancies + +### `john-p14s` + +- The main host export uses the canonical slug: `flake.nixosConfigurations.john-p14s`. +- The host-local helper modules are named `p14sConfiguration` and `p14sHardware`, which drop the `john-` prefix and therefore do not use the full host slug. +- `networking.hostname` uses the correct host value, but the option name differs from the dominant `networking.hostName` spelling used elsewhere in this tree. + +### `john-pc` + +- Approved exception for immutable deployed hostname: +- Directory slug is `john-pc`, but exported keys and hostname bindings intentionally use `john-pc-ubuntu`. +- `hostname` binding, `flake.modules.homeManager.`, and `flake.homeConfigurations` are aligned to `john-pc-ubuntu`. +- Shared SSH alias intentionally remains `john-pc-ubuntu` in `modules/services/ssh.nix`. + +### `omen-nixos` + +- No active discrepancy after normalization: +- The directory slug, `flake.nixosConfigurations` key, host-local module keys, and `networking.hostName` are now aligned to `omen-nixos`. + +### `john-kde` + +- No active discrepancy after normalization: +- The directory slug, `hostname` binding, host-local Home Manager module key, and standalone Home Manager key are now aligned to `john-kde`. + +### `soteria` + +- Naming is mostly coherent across directory slug, `hostname`, `flake.nixosConfigurations.soteria`, and `flake.modules.homeManager.soteria`. +- The standalone Home Manager export is `flake.homeConfigurations.soteria`, which does not follow the preferred `"@"` form. +- The main host entrypoint is `soteria.nix` instead of the preferred `default.nix`. + +## No Discrepancy Found + +### `janus` + +- Directory slug, `hostname`, `flake.nixosConfigurations.janus`, and `networking.hostName` are aligned. +- The host-local helper module `janus-ca` is clearly prefixed by the host slug. + +### `test-nix` + +- The single-file host uses the same slug for the file stem, `hostname`, and `flake.nixosConfigurations.test-nix`. +- It does not define `networking.hostName`, but it does not contradict the slug anywhere else. + +## Follow-up Candidates + +- Rename `john-p14s` helper module keys to include the full host slug (`john-p14s-*`) if strict slug consistency is desired. +- Decide whether `soteria` should move to `default.nix` and whether its standalone Home Manager key should include `john@`. +- If `john-pc-ubuntu` ever becomes changeable, decide whether to rename the directory to match or keep this as a permanent exception. \ No newline at end of file diff --git a/.github/instructions/hosts.instructions.md b/.github/instructions/hosts.instructions.md index f982818..d4be82b 100644 --- a/.github/instructions/hosts.instructions.md +++ b/.github/instructions/hosts.instructions.md @@ -37,6 +37,26 @@ Naming in this tree is not perfectly uniform, so preserve existing interfaces un - Some hosts export from `default.nix`, while others keep the main definition in a differently named file such as `soteria.nix`. - Do not normalize names or move files just for consistency unless the user asks for that structural change. +Naming rules for new hosts: + +- Treat the host directory name as the canonical host slug for new work. +- Prefer `modules/hosts//default.nix` as the main entrypoint for a host directory. +- Use the same slug for the primary `hostname` binding, `flake.nixosConfigurations.`, and `networking.hostName` unless the task explicitly requires a different deployed hostname. +- If the host exports a host-local Home Manager module, name it `flake.modules.homeManager.`. +- For standalone Home Manager configurations, prefer `flake.homeConfigurations."@"` so the exported key still carries the host slug. +- Name host-local helper modules with the same slug as a prefix, for example `flake.modules.nixos.-hardware` or `flake.modules.nixos.-configuration`, to make ownership obvious and avoid collisions with shared modules. +- Keep host-local secrets and auxiliary files under the same host slug directory. Do not point a new host at another host's path just because the contents are similar. + +Allowed exception for immutable deployed hostnames: + +- If the deployed hostname is externally constrained and cannot change, use that deployed hostname as the canonical slug for exported keys and `hostname` bindings, even if the directory name differs. +- In that case, keep the exception explicit in comments or reports so future cleanup work does not accidentally rename a live hostname contract. + +When working in existing hosts that predate these rules: + +- Preserve the current public names by default. +- If the user asks for a rename or cleanup, update the directory slug, exported flake keys, host-local module names, and `networking.hostName` together in one change so the host identity stays coherent. + Use nearby hosts as composition examples: - `john-p14s` splits the reusable machine logic into `configuration.nix` and `hardware.nix`, exports `flake.modules.nixos.p14sConfiguration` and `flake.modules.nixos.p14sHardware`, and assembles them from `default.nix`. diff --git a/.github/instructions/shared-modules.instructions.md b/.github/instructions/shared-modules.instructions.md new file mode 100644 index 0000000..1142038 --- /dev/null +++ b/.github/instructions/shared-modules.instructions.md @@ -0,0 +1,54 @@ +--- +description: "Use when defining or modifying reusable Nix modules outside modules/hosts. Covers flake.modules.nixos, flake.modules.homeManager, and flake.factory.user exports, and explains how shared modules differ from concrete host wiring." +applyTo: 'modules/nixos/**/*.nix, modules/users/**/*.nix, modules/features/**/*.nix, modules/programs/**/*.nix, modules/services/**/*.nix, modules/nix-tools/**/*.nix' +--- + +# Shared Modules + +Files outside `modules/hosts` generally define reusable building blocks, not concrete machines. In this repo, those files usually export one of these surfaces: + +- `flake.modules.nixos.` for reusable NixOS modules. +- `flake.modules.homeManager.` for reusable Home Manager modules. +- `config.flake.factory.user` for factories that generate per-user module sets. +- `flake.meta.*` when the file owns reusable metadata that other modules consume. + +Keep the boundary between shared modules and hosts clear: + +- Shared modules should not define `flake.nixosConfigurations.` or `flake.homeConfigurations.`; those belong in `modules/hosts`. +- Prefer generic options, imports, and composition over host-specific literals. +- If a setting only makes sense for one machine, keep it in that host directory instead of moving it into a shared module. +- When a host imports a shared module, treat the shared module as part of the stable interface that multiple hosts may depend on. + +Follow the existing export patterns in this repo: + +- Simple reusable modules may export a single module directly, such as `flake.modules.nixos.games`. +- Cross-cutting features often live under `modules/features` even when they export `flake.modules.nixos.*` or `flake.modules.homeManager.*`. +- Program and service integrations commonly export one or both module types from a single file. +- User definitions under `modules/users` may export metadata plus paired NixOS and Home Manager modules for the same user. + +For user modules specifically: + +- Keep reusable user facts under `flake.meta.users.` when other modules need to reference them. +- Prefer deriving the NixOS side from `self.factory.user` when the file already follows that pattern. +- Keep the user-facing Home Manager module in `flake.modules.homeManager.` and let the factory or host wire it into a concrete configuration. +- Put user-specific authorized keys, identity, and shared defaults here rather than duplicating them across hosts. + +Design shared modules as composable interfaces: + +- Import other shared modules instead of copying option blocks. +- Add options or parameters when behavior needs to vary between hosts. +- Avoid embedding host-specific paths, hostnames, addresses, or secret file locations unless the file is intentionally host-local. +- Preserve exported attribute names even when the filename is different. In this repo, the path is not always the public API name. + +Use nearby files as examples: + +- `modules/nixos/games.nix` is a minimal shared NixOS module with no host wiring. +- `modules/features/nixos-base.nix` defines a reusable base system module that other hosts import. +- `modules/users/john.nix` combines `flake.meta.users.john`, a reusable NixOS user module, and a reusable Home Manager user module built around the user factory. +- `modules/nix-tools/user.nix` defines the `flake.factory.user` helper that shared user modules build on. + +For reviews and answers, separate these concerns clearly: + +- reusable module API and option design in shared module directories +- concrete host assembly in `modules/hosts` +- whether a change increases reuse or accidentally pulls machine-specific behavior into a shared layer \ No newline at end of file