panotaka/nix-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance Copilot instructions with detailed project overview and directory roles; clarify developer workflows and integration points.

Browse Source
This commit is contained in:
Thomas Syms
2025-08-08 10:08:27 -03:00
parent 82a84e00cc
commit 87a2314170
1 changed files with 34 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
.github/copilot-instructions.md vendored
View File

@@ -2,41 +2,56 @@
## Project Overview ## Project Overview
- This is a modular, flake-based NixOS configuration system, designed for multi-host, multi-user, and reproducible setups. - This is a modular, flake-based NixOS configuration system, designed for multi-host, multi-user, and reproducible setups.
- Major directories: - **Major directories and their roles:**
- `hosts/`: Per-host NixOS configs (e.g., `hosts/nixos/Bellerophon/`). - `hosts/`: Per-host NixOS configs (e.g., `hosts/nixos/Bellerophon/`). Each host has its own directory with a `default.nix` entrypoint, plus hardware, disk, and optional feature overrides.
- `home/`: Per-user Home Manager configs. - `home/`: Per-user Home Manager configs. User-specific and shared configs, with `common/` for reusable modules and `optional/` for opt-in features.
- `modules/`: Reusable NixOS and Home Manager modules, auto-imported via `lib.custom.scanPaths`. - `modules/`: Reusable NixOS and Home Manager modules, auto-imported via `lib.custom.scanPaths`. This is where most custom logic, options, and abstractions live—including CLI tool modules, system services, and shared config patterns.
- `overlays/`, `pkgs/`: Custom packages and overlays. - `overlays/`, `pkgs/`: Custom packages and overlays. CLI tools that are not in upstream Nixpkgs are typically defined here (see `pkgs/common/` for examples like `cd-gitroot`).
- `nixos-installer/`: Standalone flake for bootstrapping new hosts, with its own README and workflows. - `nixos-installer/`: Standalone flake for bootstrapping new hosts, with its own README and workflows.
- `docs/`: Project documentation, including secrets management. - `docs/`: Project documentation, including secrets management and architecture guides.
- `scripts/`: Helper scripts for bootstrap, rebuild, sops, etc. - `scripts/`: Helper scripts for bootstrap, rebuild, sops, etc. Used in developer workflows and automation.
- `tests/`: Automated tests (Bats), with fixtures and helpers for validating secrets, modules, and workflows.
- **Desktop Environments & Optional Features:**
- Desktop environments (GNOME, KDE, XFCE, etc.) and other optional system features are modularized under `hosts/common/core/optional/` and its subfolders (e.g., `gnome.nix`, `kde.nix`, `xfce.nix`).
- These are imported by hosts as needed, allowing flexible, DRY configuration.
- **CLI Tools:**
- System-wide CLI tools are typically declared in `modules/` (as NixOS or Home Manager modules), or in `pkgs/` if packaged locally.
- User-level CLI tools are managed via Home Manager modules in `home/<user>/common/core/shell/` (e.g., `fish.nix`, `bat.nix`, `eza.nix`).
- Many tools are grouped by function (shell, coding, productivity, etc.) for clarity and reusability.
- **Disk Layout:** Disk setup is handled by `disko` modules, with per-host overrides for device and swap in `hosts/common/core/disks/`.
- **Secrets:** Secrets are managed via a private `nix-secrets` repo and sops-nix. See `docs/secretsmgmt.md` and `nixos-installer/README.md` for details.
- **VSCode/Language Support:** Language-specific VSCode configs live in `home/panotaka/common/optional/coding/vscode/languages/` and are imported via the main VSCode module.
## Key Patterns & Conventions ## Key Patterns & Conventions
- **Imports**: Use `lib.custom.relativeToRoot` and `lib.custom.scanPaths` for DRY, recursive module imports. - **Imports:** Use `lib.custom.relativeToRoot` and `lib.custom.scanPaths` for DRY, recursive module imports.
- **Host/Module Structure**: Each host and user has a directory with a `default.nix` as entrypoint. Common/optional configs are split for clarity. - **Host/Module Structure:** Each host and user has a directory with a `default.nix` as entrypoint. Common/optional configs are split for clarity.
- **Disk Layout**: Disk setup is handled by `disko` modules, with per-host overrides for device and swap. - **Disk Layout:** Disk setup is handled by `disko` modules, with per-host overrides for device and swap.
- **Secrets**: Secrets are managed via a private `nix-secrets` repo and sops-nix. See `docs/secretsmgmt.md` and `nixos-installer/README.md` for details. - **Secrets:** Secrets are managed via a private `nix-secrets` repo and sops-nix. See `docs/secretsmgmt.md` and `nixos-installer/README.md` for details.
- **VSCode/Language Support**: Language-specific VSCode configs live in `home/panotaka/common/optional/coding/vscode/languages/` and are imported via the main VSCode module. - **VSCode/Language Support:** Language-specific VSCode configs live in `home/panotaka/common/optional/coding/vscode/languages/` and are imported via the main VSCode module.
## Developer Workflows ## Developer Workflows
- **Build & Rebuild**: Use `just rebuild` (runs pre/post hooks, see `justfile`). For full checks: `just rebuild-full` or `just check`. - **Build & Rebuild:** Use `just rebuild` (runs pre/post hooks, see `justfile`). For full checks: `just rebuild-full` or `just check`.
- **ISO Generation**: `just iso` builds a custom NixOS installer ISO. - **ISO Generation:** `just iso` builds a custom NixOS installer ISO.
- **Secrets**: Use `just rekey`, `just sops-add-creation-rules`, and related commands for sops/age key management. - **Secrets:** Use `just rekey`, `just sops-add-creation-rules`, and related commands for sops/age key management.
- **Sync/Deploy**: Use `just sync` and `just build-host` for remote deployment. - **Sync/Deploy:** Use `just sync` and `just build-host` for remote deployment.
- **Testing**: Tests live in `tests/` and use `bats`. - **Testing:** Tests live in `tests/` and use `bats`.
## Integration Points ## Integration Points
- **External**: Relies on `nix-secrets` (private), sops-nix, disko, stylix, nix4vscode, and nixos-hardware modules. - **External:** Relies on `nix-secrets` (private), sops-nix, disko, stylix, nix4vscode, and nixos-hardware modules.
- **Cross-Component**: Host configs import common modules and optional features via mapped imports. Home Manager and NixOS modules are kept separate but coordinated. - **Cross-Component:** Host configs import common modules and optional features via mapped imports. Home Manager and NixOS modules are kept separate but coordinated.
## Examples ## Examples
- To add a new host: copy an existing host dir in `hosts/nixos/`, update disk and user settings, and add secrets as per `nixos-installer/README.md`. - To add a new host: copy an existing host dir in `hosts/nixos/`, update disk and user settings, and add secrets as per `nixos-installer/README.md`.
- To add a new language to VSCode: add a `.nix` file to `vscode/languages/` and import it in the main VSCode module. - To add a new language to VSCode: add a `.nix` file to `vscode/languages/` and import it in the main VSCode module.
- To add a new CLI tool: create a module in `modules/` or a package in `pkgs/`, then import it in the relevant host or user config.
- To enable a desktop environment: import the relevant module from `hosts/common/core/optional/` in your host's `default.nix`.
- To update secrets: run `just rekey` and follow the documented workflow. - To update secrets: run `just rekey` and follow the documented workflow.
## References ## References
- See `README.md`, `nixos-installer/README.md`, and `docs/secretsmgmt.md` for deep dives on architecture and workflows. - See `README.md`, `nixos-installer/README.md`, and `docs/secretsmgmt.md` for deep dives on architecture and workflows.
- For module patterns, see `modules/` and `hosts/common/core/`. - For module patterns, see `modules/` and `hosts/common/core/`.
- For CLI tool packaging, see `pkgs/` and `modules/`.
- For desktop environment modules, see `hosts/common/core/optional/`.
--- ---