1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
# AGENTS.md
Guidance for agentic coding assistants working in this repository.
## 1) Project Snapshot
- Repo type: NixOS flake-based configuration repo.
- Core pattern: "homogenous modules" (shared `options.nix` + `nixos/default.nix` + `hjem/default.nix`).
- Main namespace for custom options: `collinux`.
- Hosts currently configured: `mercury`, `jupiter`, `ganymede`.
- Deployment helper: custom `yo` command (Ruby wrapper around `nix`/`nom`).
## 2) Rule Files Discovery
The following rule files were checked:
- `.cursor/rules/**`: not found
- `.cursorrules`: not found
- `.github/copilot-instructions.md`: not found
No Cursor/Copilot-specific rules are currently present in this repository.
## 3) Directory Landmarks
- `flake.nix`: top-level inputs/outputs, host definitions.
- `hosts/<hostname>/config.nix`: host-level declarative settings.
- `modules/`: feature modules (desktop, terminal, services, system, etc.).
- `lib/nix-furnace/mkSystem.nix`: module wiring and host assembly.
- `lib/lib.nix`: custom helper library (`my-lib`).
- `pkgs/yo/`: Ruby deploy/build helper package.
- `pkgs/yossh/`: Lua SSH helper package + lightweight tests.
- `docs/homogenous_modules.md`: architecture background.
## 4) Build / Check / Deploy Commands
Run from repo root: `/home/collin/nixos`.
### Core build commands
- Build current host and activate immediately:
- `yo switch`
- alias: `yo sw`
- Build current host and activate on next boot:
- `yo boot`
- Build current host and test activation (non-persistent):
- `yo test`
- Build a specific host configuration without switching:
- `yo build <hostname>`
- Build current hostname (auto-detected):
- `yo build`
### Direct nix builds
- Build one host toplevel derivation:
- `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel`
- Build generated docs package:
- `nix build .#docs`
- Build default package output:
- `nix build`
### Deploy commands
- Deploy via custom wrapper (see `pkgs/yo/default.nix` behavior):
- `yo deploy <ssh-host-or-user@host>`
- alias: `yo dep <ssh-host-or-user@host>`
Note: Some docs mention `yo deploy <hostname> <ssh-host>`; current code path derives hostname
from the SSH target argument.
## 5) Lint / Format / Validation
There is no single repo-wide lint target committed (no Makefile/justfile/pre-commit config found).
Use these practical checks:
- Nix syntax/eval sanity via host build:
- `yo build <hostname>`
- or `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel`
- Option docs generation as additional eval coverage:
- `nix build .#docs`
- Format Nix files with Alejandra (formatter used in editor config):
- `nix run nixpkgs#alejandra -- .`
If you add new tool-specific linting, document the exact command in this file.
## 6) Test Commands (Including Single-Test Guidance)
### Repository-level tests
- No centralized automated test suite is wired at repo root.
- The most test-like validation is successful Nix evaluation/build per host.
### `pkgs/yossh` Lua tests
- Test file exists: `pkgs/yossh/tests/unit_tests.lua`.
- Run file directly:
- `lua pkgs/yossh/tests/unit_tests.lua`
Important: current file defines tests and `main()` but does not call `main()` at EOF.
Running it as-is may not execute assertions unless the file is updated.
### Running a single test
There is no built-in single-test runner flag today.
Recommended workflow for single-test execution:
1. Temporarily edit `pkgs/yossh/tests/unit_tests.lua` so `main()` calls only one test function.
2. Run `lua pkgs/yossh/tests/unit_tests.lua`.
3. Revert the temporary test-selection edit before committing.
If you frequently need single-test runs, introduce a minimal CLI test selector and document it here.
## 7) Architecture Conventions You Must Preserve
- Keep host configs declarative attribute sets, not functions.
- Keep module option definitions in `options.nix` files.
- Keep NixOS implementation under `nixos/default.nix`.
- Keep hjem implementation under `hjem/default.nix`.
- Prefer adding features by extending existing module trees, not ad-hoc host logic.
- Use `my-lib` helpers when patterns already exist (`mkProgramOption`, `mkThemeOption`, etc.).
- Keep custom options under `collinux.*` to avoid collisions.
## 8) Code Style Guide
### General
- Match existing style in touched files; do not mass-reformat unrelated code.
- Keep diffs focused and minimal.
- Prefer explicit, descriptive names over abbreviations.
- Avoid adding comments unless logic is non-obvious.
### Nix style
- Indentation: 2 spaces; no tabs.
- Favor argument destructuring at top:
- `{ pkgs, lib, config, ... }:` style.
- Common structure:
- bind `cfg = config.collinux.<path>;` in `let`.
- gate behavior with `lib.mkIf cfg.enable` where relevant.
- Prefer `inherit (lib) ...` for imported lib symbols.
- Keep `imports` lists clean and stable; one module per line.
- Use `mkOption`/`mkEnableOption` for options; include `description`, `type`, and sensible defaults.
- Use precise types (`types.port`, custom net types, `nullOr`, submodules) rather than loose strings.
- Prefer pure expressions and deterministic outputs.
### Import and dependency conventions
- Reuse local helpers from `my-lib` before adding new helper patterns.
- In modules, keep imports relative and predictable (`./foo.nix`, `./default.nix`).
- Avoid circular/implicit dependencies across module families.
### Naming conventions
- Nix option paths: lower camelCase segments under `collinux`.
- Files/modules: lowercase names, hyphenated when appropriate.
- Lua locals/functions: mostly snake_case in core library; preserve local file conventions.
- Ruby methods: snake_case; class/module names: CamelCase.
### Types and validation
- Add/keep explicit option types whenever possible.
- Use custom validators from `my-lib.netTypes` for network values.
- For structured config, prefer typed submodules over freeform attrs.
### Error handling
- Fail early with clear messages (`assertions`, explicit `error`/`raise`).
- In scripts/wrappers, check command success and raise on failure.
- Do not swallow errors from builds, copy, deploy, or switch operations.
### Secrets and security
- Never commit plaintext secrets.
- Use agenix-managed `.age` files and declared secret paths.
- Preserve service hardening settings unless there is a clear reason to change.
## 9) Agent Workflow Expectations
- Before changing behavior, read nearby module/options files to follow local patterns.
- Prefer validating with a targeted host build after Nix edits.
- If touching deployment logic, test with non-destructive build paths first.
- Keep commit scope tight: one logical change per commit.
- Update docs when command behavior or module patterns change.
## 10) Definition of Done (for automated agents)
- Code compiles/evaluates for affected host(s) via `yo build <hostname>` or equivalent.
- New/changed options are typed and documented by structure.
- Formatting is consistent with current repository conventions.
- No plaintext secrets introduced.
- Any new commands, checks, or test entrypoints are reflected in this `AGENTS.md`.
|
