# Rigging

Multi-repo NixOS + Nomad infrastructure management CLI and flake-parts module.

## What this is

Three components:

1. **Flake-parts module** (`flake-module.nix`) — repos import this to declare what they provide and expose a `bosun-manifest` package (JSON derivation)
2. **Nushell CLI** (`cli/rigging.nu`) — reads `~/.config/bosun/config.toml`, builds each repo's manifest via `nix build`, aggregates, dispatches commands
3. **Bash CLI** (`cli/default.nix`) — repo-local Nomad job operations with runtime variable support

## File layout

```
flake.nix              # exports flakeModules.default + lib
flake-module.nix       # the flake-parts module (top-level bosun.{meta,hosts} + perSystem bosun.{enable,jobsDir,...})
cli/
  default.nix          # bash bosun CLI (repo-local Nomad ops)
  rigging.nix          # nix wrapper for the nushell CLI
  rigging.nu           # nushell CLI source
lib/
  default.nix          # bosun library (discoverJobs, evalJob, compileJobs, etc.)
  nomad.nix            # nomad helpers (traefikTags, pinToHost, resources, etc.)
  nushell.nix          # writeNushellApplication (bundled, no overlay needed)
```

## How consumers use it

Consumers add this as a flake input and import `flakeModules.default`. This gives them:
- `bosun.meta.name` / `bosun.hosts` — top-level options for repo identity + host declarations
- `perSystem.bosun.{enable,jobsDir,nomadAddress,...}` — Nomad job management
- `packages.bosun-manifest` — always generated JSON manifest
- `packages.rigging` — the multi-repo CLI
- `packages.bosun` — repo-local Nomad CLI (only when `bosun.enable = true`)

The manifest is the key integration point: `rigging` builds each repo's manifest via `nix build <repo>#bosun-manifest`, reads the JSON, and knows what hosts/jobs each repo provides.

## Key design decisions

- **No legacyPackages for vars**: Runtime job evaluation with variables uses `nix eval --expr` inline (same pattern as the bash CLI). The `legacyPackages.bosun.evalJobWithVars` exists for backward compat but the CLI constructs the eval expression directly.
- **Rigging delegates Nomad ops**: The nushell CLI is a thin orchestration layer. For actual Nomad operations (run, plan, stop, etc.), it delegates to the repo-local bash CLI via `nix run <repo>#bosun -- <cmd>`.
- **writeNushellApplication bundled**: `lib/nushell.nix` is a self-contained copy so consumers don't need an overlay.
- **Top-level + perSystem split**: `bosun.meta`/`bosun.hosts` are flake-level options (shared across systems). Nomad job config is perSystem (needs `pkgs`). The manifest bridges both by reading top-level config from within perSystem via closure over `topArgs.config.bosun`.
- **`mkMerge`/`mkIf` for config**: The perSystem config uses `mkMerge` + `mkIf` (not `//` + `lib.optionalAttrs`) to avoid infinite recursion when the module system evaluates packages.

## Vision

The end state: `rigging` is installed globally (via home-manager or devShell) and manages all infrastructure repos. Each repo is self-describing — `rigging repo add <path>` discovers everything. Commands like `rigging host deploy alvin` or `rigging job run forgejo` Just Work regardless of which repo owns the resource.

Phase 4 (pending): wire up dotfiles repo as a second consumer. Phase 5: drop the bash CLI once rigging fully replaces it.