# mjallen-lib Utility Functions

Utility functions for the NixOS/nix-darwin configuration. Exposed via Snowfall Lib as `lib.mjallen.*`.

## Directory Structure

- `default.nix` — Main entry point; exports `module`, `file`, and `versioning`
- `module/` — Module creation helpers (`mkModule`, `mkContainerService`, `mkSopsEnvFile`, `mkOpt`, etc.)
- `file/` — File and path utilities
- `versioning/` — Multi-source version pinning helpers (used by packages)

---

## Module Utilities (`lib.mjallen.module`)

### `mkModule`

Creates a NixOS service module with a standard set of options. All config is gated behind `cfg.enable`.

```nix
lib.mjallen.mkModule {
  config      # NixOS config attrset (pass-through from module args)
  name        # Service name — used for option path and systemd unit
  description # Text for mkEnableOption (defaults to name)
  options     # Extra options merged into the submodule
  moduleConfig # NixOS config body (applied when cfg.enable = true)
  domain      # Option namespace domain (default: "services")
  serviceName # Systemd service name (default: name)
}
```

**Standard options provided for free:**

| Option | Type | Default | Description |
|---|---|---|---|
| `enable` | bool | `false` | Enable/disable the service |
| `port` | int | `80` | Service listen port |
| `listenAddress` | str | `"0.0.0.0"` | Bind address |
| `openFirewall` | bool | `true` | Open TCP+UDP firewall ports |
| `configDir` | str | `/var/lib/<name>` | Config directory |
| `dataDir` | str | `/var/lib/<name>/data` | Data directory |
| `createUser` | bool | `false` | Create a dedicated system user |
| `configureDb` | bool | `false` | Create a PostgreSQL database |
| `environmentFile` | str\|null | `null` | Path to an env-file |
| `extraEnvironment` | attrs | `{}` | Extra environment variables |
| `hashedPassword` | str\|null | `null` | Hashed password for web auth |
| `puid` / `pgid` | str | `"911"` / `"100"` | UID/GID for container services |
| `timeZone` | str | `"UTC"` | Timezone for container services |
| `redis.enable` | bool | `false` | Create a Redis instance for this service |
| `redis.port` | int | `6379` | Redis port |
| `reverseProxy.enable` | bool | `false` | Add a Caddy reverse proxy block |
| `reverseProxy.subdomain` | str | `<name>` | Caddy subdomain |
| `reverseProxy.domain` | str | `"mjallen.dev"` | Caddy base domain |
| `reverseProxy.upstreamUrl` | str\|null | `null` | Override upstream URL |
| `reverseProxy.extraCaddyConfig` | lines | `""` | Extra Caddyfile directives |

**Default behaviour when enabled:**

- Adds Caddy reverse proxy block (if `reverseProxy.enable = true`)
- Opens firewall ports (if `openFirewall = true`)
- Creates system user/group (if `createUser = true`)
- Creates PostgreSQL database (if `configureDb = true`)
- Creates Redis instance (if `redis.enable = true`)
- Adds `RequiresMountsFor` systemd dependency for `configDir` and `dataDir`

---

### `mkContainerService`

Wraps `mkModule` for Podman/OCI container services. Generates the full container definition automatically.

```nix
lib.mjallen.mkContainerService {
  config        # NixOS config attrset
  name          # Service/container name
  image         # OCI image reference (e.g. "ghcr.io/example/app:latest")
  internalPort  # Port the container listens on internally
  description   # Human-readable description (defaults to name)
  options       # Extra mkModule options
  volumes       # Extra volume mount strings
  environment   # Extra environment variables (merged with PUID/PGID/TZ)
  environmentFiles # List of env-file paths (e.g. SOPS template paths)
  extraOptions  # Extra --opt strings for the container runtime
  devices       # Device mappings
  extraConfig   # Extra NixOS config merged into moduleConfig
}
```

The systemd service is named `podman-<name>`, and the port binding is `<cfg.port>:<internalPort>`.

---

### `mkSopsEnvFile`

Generates a SOPS secrets block and a SOPS template env-file in a single call. Useful for services that need secrets injected as environment variables.

```nix
lib.mjallen.mkSopsEnvFile {
  secrets     # attrset: sops-key → extra attrs (owner, group, etc.)
  name        # Template file name, e.g. "myapp.env"
  content     # Template body (use config.sops.placeholder."key")
  restartUnit # Systemd unit to restart when secrets change
  owner       # File owner (default: "nix-apps")
  group       # File group (default: "jallen-nas")
  mode        # File permissions (default: "660")
  sopsFile    # Default SOPS file for all secrets
}
```

---

### Option helpers

| Function | Signature | Description |
|---|---|---|
| `mkOpt` | `type → default → description → mkOption` | Standard option shorthand |
| `mkOpt'` | `type → default → mkOption` | `mkOpt` without description |
| `mkBoolOpt` | `default → description → mkOption` | Boolean option shorthand |
| `mkBoolOpt'` | `default → mkOption` | Boolean option without description |
| `mkReverseProxyOpt` | `name → attrset` | Standard Caddy reverse proxy sub-options |

---

### Convenience shorthands

| Value | Expands to |
|---|---|
| `enabled` | `{ enable = true; }` |
| `disabled` | `{ enable = false; }` |

---

### Attribute utilities

| Function | Description |
|---|---|
| `default-attrs` | Apply `lib.mkDefault` to every value in an attrset |
| `force-attrs` | Apply `lib.mkForce` to every value in an attrset |
| `nested-default-attrs` | Apply `default-attrs` one level deeper |
| `nested-force-attrs` | Apply `force-attrs` one level deeper |

---

### String utilities

| Function | Description |
|---|---|
| `capitalize` | Capitalise the first character of a string |

---

### Boolean utilities

| Function | Description |
|---|---|
| `boolToNum` | `true → 1`, `false → 0` |

---

## Home Manager Utilities (`lib.mjallen.module`)

### `mkHomeModule`

Creates a Home Manager module with a standard `enable` option.

```nix
lib.mjallen.mkHomeModule {
  config       # HM config attrset
  domain       # Option namespace domain, e.g. "programs" or "desktop"
  name         # Module name, e.g. "btop"
  description  # Text for mkEnableOption (defaults to name)
  options      # Extra options merged into the submodule
  moduleConfig # HM config body (applied when cfg.enable = true)
}
```

---

## File Utilities (`lib.mjallen.file`)

Helpers for resolving paths relative to the flake root. Primarily used internally by modules and packages.

---

## Versioning Utilities (`lib.mjallen.versioning`)

Used by packages that track multiple upstream variants (e.g. `proton-cachyos`, `linux-rpi`). Reads a `version.json` file and resolves sources with optional variable substitution and per-variant overrides.

See `lib/versioning/default.nix` for the full API and `docs/version.schema.json` for the `version.json` schema.