From 48a837a91959efbc7da7f98447c50f32b4ee7c94 Mon Sep 17 00:00:00 2001 From: Collin Williams <96917990+bluedragon1221@users.noreply.github.com> Date: Thu, 2 Apr 2026 16:18:29 -0500 Subject: jta, other changes --- AGENTS.md | 338 ++++++++++++++++++++++++++++---------------------------------- 1 file changed, 150 insertions(+), 188 deletions(-) (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md index dfd8a42..0c8da14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,192 +1,154 @@ # 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//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 ` -- Build current hostname (auto-detected): - - `yo build` - -### Direct nix builds - -- Build one host toplevel derivation: - - `nix build .#nixosConfigurations..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 ` - - alias: `yo dep ` - -Note: Some docs mention `yo deploy `; 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 ` - - or `nix build .#nixosConfigurations..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.;` 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 - +Guidance for coding agents working in this repository. + +## 1) Repository Purpose +- NixOS flake repo with host configs, reusable modules, and local packages. +- Most edits happen in `hosts/`, `modules/`, `lib/`, and `pkgs/`. +- Includes a standalone Go project at `pkgs/jta/`. +- Make focused changes; avoid unrelated refactors. + +## 2) AI Rule Files (Cursor/Copilot) +- `.cursor/rules/`: not found. +- `.cursorrules`: not found. +- `.github/copilot-instructions.md`: not found. +- There are no repository-specific Cursor/Copilot instruction files to apply. + +## 3) Key Paths +- `flake.nix`: flake inputs/outputs and host definitions. +- `hosts//config.nix`: host-level entrypoints. +- `modules/`: homogenous module tree. +- `lib/nix-furnace/mkSystem.nix`: system composition. +- `lib/lib.nix`: shared helpers (`my-lib`). +- `pkgs/yo/`: Ruby deployment/build helper. +- `pkgs/yossh/`: Lua SSH tooling and tests. +- `pkgs/jta/`: Go module. +- `justfile`: command shortcuts. + +## 4) Build Commands +Run from `/home/collin/nixos` unless noted. + +NixOS commands: +- `yo build` +- `yo build ` +- `yo switch` or `yo sw` +- `yo boot` +- `yo test` +- `yo deploy ` or `yo dep ` + +Direct Nix commands: +- `nix build .#nixosConfigurations..config.system.build.toplevel` +- `nix build .#docs` +- `nix build` + +Just shortcuts: +- `just build` +- `just switch` +- `just deploy` + +Go project (`pkgs/jta`): +- `go build ./...` +- `go run .` + +## 5) Lint and Formatting +Nix: +- `nix run nixpkgs#alejandra -- .` +- Prefer formatting only touched files. + +Go (`pkgs/jta`): +- `gofmt -w .` +- `go vet ./...` + +Validation defaults: +- After Nix changes, run a host build. +- After Go changes, run build and tests. + +## 6) Test Commands +Repository-wide: +- No single root test harness is configured. +- Nix host builds are primary verification. + +Nix checks: +- `yo build ` +- `nix build .#nixosConfigurations..config.system.build.toplevel` + +Go tests (`pkgs/jta`): +- Run all tests: `go test ./...` +- Run single test name: `go test ./... -run '^TestName$'` +- Run single test in current package: `go test . -run '^TestName$'` + +Lua tests (`pkgs/yossh`): +- Run all defined tests: `lua pkgs/yossh/tests/unit_tests.lua` +- Current single-test method is manual (temporarily call one test in `main()`). + +## 7) Architectural Conventions +- Preserve homogenous module layout: + - `options.nix` for option definitions. + - `nixos/default.nix` for NixOS implementation. + - `hjem/default.nix` for hjem implementation. +- Keep custom options under `collinux.*`. +- Keep host configs declarative. +- Reuse existing helper patterns before creating new abstractions. + +## 8) Code Style +General: +- Match style of the touched file. +- Keep diffs minimal and intentional. +- Prefer explicit naming over abbreviations. +- Add comments only for non-obvious logic. + +Nix style: +- 2-space indentation; no tabs. +- Common arg pattern: `{ lib, config, pkgs, ... }:`. +- Use `cfg = config.collinux.;` when it improves clarity. +- Use `lib.mkIf` for option-gated config. +- Prefer typed options (`types.port`, `types.nullOr`, submodules). +- Keep imports stable and readable (usually one per line). +- Use `inherit (lib) ...` where idiomatic. + +Imports/dependencies: +- Prefer relative imports in module trees (`./foo.nix`). +- Avoid circular dependencies. +- Reuse `my-lib` helpers from `lib/lib.nix` when possible. + +Go style (`pkgs/jta`): +- Keep code gofmt-clean. +- Preserve gofmt import ordering/grouping. +- Prefer early error returns. +- Use standard `net/http` helpers consistently. + +Ruby style (`pkgs/yo`): +- snake_case for methods/locals; CamelCase for classes/modules. +- Validate CLI args and fail fast (`abort` with clear message). +- Do not hide command failures. + +Lua style (`pkgs/yossh`, `pkgs/util`): +- Follow local naming conventions (mostly snake_case). +- Keep helpers small and composable. +- Raise clear errors instead of ambiguous nil behavior. + +## 9) Types, Naming, and Error Handling +- Use explicit Nix option types whenever practical. +- Option naming: lower camelCase segments under `collinux`. +- File naming: lowercase; hyphenate when local pattern uses it. +- Fail early with actionable error messages. +- Do not swallow build/deploy/switch failures. + +## 10) Secrets and Safety - 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 ` or equivalent. -- New/changed options are typed and documented by structure. -- Formatting is consistent with current repository conventions. +- Preserve agenix and `.age` workflows. +- Treat `hosts/*/secrets/*` and `*.age` as sensitive. +- Do not weaken security defaults without explicit intent. + +## 11) Workflow for Agents +- Read adjacent files before editing. +- Follow established patterns first. +- Validate the smallest meaningful scope. +- Update docs when command behavior changes. + +## 12) Definition of Done +- Affected targets build/evaluate successfully. +- Formatting and style are consistent. +- New options are typed appropriately. - No plaintext secrets introduced. -- Any new commands, checks, or test entrypoints are reflected in this `AGENTS.md`. +- This AGENTS guide remains accurate. -- cgit v1.3.1