add readme and AGENTS slop

2026-02-21 16:43:55 +01:00
parent 8868eb8736
commit 30e15d8f95
2 changed files with 449 additions and 99 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,182 @@
+# AGENTS.md
+
+This file provides guidance for AI coding assistants working on the Panoptikon project.
+
+## Project Overview
+
+Panoptikon is a NixOS module that monitors website content and command output changes. It periodically runs scripts, compares outputs, and reports changes to various destinations.
+
+**Key Components:**
+- `flake.nix` - Flake definition with modules, overlays, and VM app
+- `nix/module.nix` - Main NixOS module implementation
+- `nix/overlay.nix` - Overlay providing `panoptikonWatchers` and `panoptikonReporters` helpers
+- `examples/` - Example configurations
+- `README.md` - User-facing documentation
+
+## Coding Conventions
+
+### Nix Code Style
+
+- Use Nix expression language (not NixOS modules have `lib` available)
+- Prefer `lib.attrsets.mapAttrs'` with `lib.nameValuePair` for transforming attrsets
+- Use `lib.strings.concatMapStringsSep` for joining strings with separators
+- Maintain consistent formatting (2-space indentation)
+
+### Systemd Configuration
+
+- Services run as dedicated `panoptikon` system user
+- Use `RuntimeDirectory` for temporary per-run isolation
+- Use `ReadWritePaths` to restrict filesystem access
+- Enable hardening flags: `ProtectSystem`, `ProtectHome`, `PrivateTmp`, `NoNewPrivileges`
+
+### State Management
+
+- State files stored in `/var/lib/panoptikon/`
+- Each watcher uses `${watcherName}` and `${watcherName}.old`
+- Scripts ensure `.old` exists before diff
+- Rotate state after comparing
+
+### Security Practices
+
+- Never log sensitive data (tokens, credentials)
+- Use `set -efu` in shell scripts (avoid `-x`)
+- Use `LoadCredential=` for passing secrets
+- Validate file existence before reading tokens
+- Escape shell arguments with `lib.escapeShellArg`
+
+## Testing
+
+### Manual Testing
+
+1. Start the VM with all examples:
+   ```bash
+   nix run .#panoptikon-vm
+   ```
+
+2. Inside the VM, check service status:
+   ```bash
+   systemctl status panoptikon-*
+   journalctl -u panoptikon-bitcoin-price -f
+   ```
+
+3. Trigger a manual run:
+   ```bash
+   systemctl start panoptikon-bitcoin-price
+   ```
+
+### Linting and Formatting
+
+```bash
+# Check Nix syntax
+nix flake check
+
+# Format Nix code
+nix fmt
+```
+
+## Debugging
+
+### Service Issues
+
+1. Check if service is enabled and running:
+   ```bash
+   systemctl status panoptikon-<watcher-name>
+   ```
+
+2. View logs:
+   ```bash
+   journalctl -u panoptikon-<watcher-name> -f
+   ```
+
+3. Test scripts manually (as panoptikon user):
+   ```bash
+   sudo -u panoptikon /nix/store/...-script
+   ```
+
+### State File Issues
+
+- Check state directory: `/var/lib/panoptikon/`
+- State files persist across reboots
+- Delete state file to force change detection on next run
+
+### Timer Issues
+
+- Timer uses `RandomizedDelaySec` of 1 hour to prevent thundering herd
+- This means services may be delayed up to 1 hour from the scheduled time
+- Check active timers: `systemctl list-timers "panoptikon-*"`
+
+## Architecture Notes
+
+### Data Flow
+
+1. systemd timer triggers service
+2. Script runs, stdout saved to `${watcherName}`
+3. Diff against `${watcherName}.old`
+4. If changes detected: pipe diff to each reporter
+5. Rotate: current → old
+
+### Reporter Contract
+
+- Reporters receive the diff via stdin
+- Can access watcher name via `$PANOPTIKON_WATCHER`
+- Should handle errors gracefully (exit code ignored in main script)
+- Run in isolated empty `/run/panoptikon/<watcher-name>` directory
+
+### Watcher Contract
+
+- Must be an executable path (script or binary)
+- Output is stored verbatim for diffing
+- Should be idempotent (running twice produces same output)
+- Avoid side effects; output only relevant data
+
+## Extension Points
+
+### Adding New Watcher Helpers
+
+Add to `panoptikonWatchers` in `overlay.nix`:
+
+```nix
+panoptikonWatchers = (prev.panoptikonWatchers or { }) // {
+  myWatcher =
+    args:
+    prev.writers.writeDash "watch-my" ''
+      ${prev.somePackage}/bin/tool --option ${lib.escapeShellArg args}
+    '';
+};
+```
+
+### Adding New Reporter Helpers
+
+Similar pattern in `panoptikonReporters`:
+
+```nix
+panoptikonReporters = (prev.panoptikonReporters or { }) // {
+  myReporter =
+    { requiredArg, optionalArg ? "default" }:
+    prev.writers.writeDash "report-my" ''
+      cat | ${prev.tool}/bin/send --to ''${requiredArg}
+    '';
+};
+```
+
+### Common Dependencies
+
+- `writers.writeDash` - Write shell scripts
+- `curl` - HTTP requests
+- `jq` - JSON processing
+- `htmlq` - HTML selectors
+- `diffutils` - Compare outputs
+
+## Known Limitations
+
+- Large outputs may cause memory pressure in diff
+- No built-in rate limiting for external APIs
+- Reporters cannot access the original script output, only the diff
+- State stored in plain files (no compression/rotation)
+
+## Future Considerations
+
+- Adding watchdog timeouts
+- Metrics collection (execution time, success rate)
+- Backoff strategies for failing watchers
+- Support for structured output formats (JSON events)