jta, other changes

1 files changed, 124 insertions, 162 deletions

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.
+Guidance for coding agents working in this repository.
 
-## 1) Project Snapshot
+## 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.
 
-- 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) 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.
 
-## 2) Rule Files Discovery
+## 3) Key Paths
+- `flake.nix`: flake inputs/outputs and host definitions.
+- `hosts/<hostname>/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.
 
-The following rule files were checked:
+## 4) Build Commands
+Run from `/home/collin/nixos` unless noted.
 
-- `.cursor/rules/**`: not found
-- `.cursorrules`: not found
-- `.github/copilot-instructions.md`: not found
+NixOS commands:
+- `yo build`
+- `yo build <hostname>`
+- `yo switch` or `yo sw`
+- `yo boot`
+- `yo test`
+- `yo deploy <ssh-target>` or `yo dep <ssh-target>`
 
-No Cursor/Copilot-specific rules are currently present in this repository.
+Direct Nix commands:
+- `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel`
+- `nix build .#docs`
+- `nix build`
 
-## 3) Directory Landmarks
+Just shortcuts:
+- `just build`
+- `just switch`
+- `just deploy`
 
-- `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.
+Go project (`pkgs/jta`):
+- `go build ./...`
+- `go run .`
 
-## 4) Build / Check / Deploy Commands
+## 5) Lint and Formatting
+Nix:
+- `nix run nixpkgs#alejandra -- .`
+- Prefer formatting only touched files.
 
-Run from repo root: `/home/collin/nixos`.
+Go (`pkgs/jta`):
+- `gofmt -w .`
+- `go vet ./...`
 
-### Core build commands
+Validation defaults:
+- After Nix changes, run a host build.
+- After Go changes, run build and tests.
 
-- 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`
+## 6) Test Commands
+Repository-wide:
+- No single root test harness is configured.
+- Nix host builds are primary verification.
 
-### Direct nix builds
+Nix checks:
+- `yo build <hostname>`
+- `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel`
 
-- 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`
+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$'`
 
-### Deploy commands
+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()`).
 
-- 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>`
+## 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.
 
-Note: Some docs mention `yo deploy <hostname> <ssh-host>`; current code path derives hostname
-from the SSH target argument.
+## 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.
 
-## 5) Lint / Format / Validation
+Nix style:
+- 2-space indentation; no tabs.
+- Common arg pattern: `{ lib, config, pkgs, ... }:`.
+- Use `cfg = config.collinux.<path>;` 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.
 
-There is no single repo-wide lint target committed (no Makefile/justfile/pre-commit config found).
+Imports/dependencies:
+- Prefer relative imports in module trees (`./foo.nix`).
+- Avoid circular dependencies.
+- Reuse `my-lib` helpers from `lib/lib.nix` when possible.
 
-Use these practical checks:
+Go style (`pkgs/jta`):
+- Keep code gofmt-clean.
+- Preserve gofmt import ordering/grouping.
+- Prefer early error returns.
+- Use standard `net/http` helpers consistently.
 
-- 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 -- .`
+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.
 
-If you add new tool-specific linting, document the exact command in this file.
+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.
 
-## 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
+## 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.
+- Preserve agenix and `.age` workflows.
+- Treat `hosts/*/secrets/*` and `*.age` as sensitive.
+- Do not weaken security defaults without explicit intent.
 
-## 10) Definition of Done (for automated agents)
+## 11) Workflow for Agents
+- Read adjacent files before editing.
+- Follow established patterns first.
+- Validate the smallest meaningful scope.
+- Update docs when command behavior changes.
 
-- 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.
+## 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.