curator/README.md

# curator - A Home-Manager Like Tool for Universal Blue builds

A lightweight CLI that provides repository and dotfile management and package installation functionality through a centralized TOML configuration. Ported and expanded from [forge](https://github.com/ijadux2/forge) and inspired by [home-manager](https://github.com/nix-community/home-manager/).

## Overview

curator is a Python CLI that helps you manage your Fedora system configuration by:
- Managing COPR repositories (enable/disable automatically)
- Installing and managing system packages via `dnf` or `rpm-ostree`
- Installing and managing userspace packages via `brew`, `flatpak`, or `nix`
- Managing dotfiles through symlinks to actual files
- Centralized configuration via a single `inventory.toml` file
- Declarative user-level configuration similar to `home-manager`/`nixos`
- Automatic backup of existing files before replacement

## Installation

Install the CLI directly from GitHub with [uv](https://github.com/astral-sh/uv): 

```bash
uv tool install --from git+https://codeberg.org/randogoth/curator/ curator
```

## Quick Start

```bash
# Initialize the configuration structure
curator init

# Edit the configuration file to add packages and dotfiles
nano ~/.config/curator/inventory.toml

# Apply configuration
curator switch

# Check status
curator status
```

## Commands

### `init`
Initialize the configuration structure and create `inventory.toml`.

```bash
curator init
# or ./curator init
```

Creates:
- `~/.config/curator/` - Main configuration directory
- `~/.config/curator/inventory.toml` - Central configuration file

### `switch`
Apply the current configuration (enable COPR, install packages, deploy dotfiles). Use `--rollback` to restore the previous `inventory.toml` snapshot before applying.

```bash
curator switch
# or ./curator switch
# rollback to the previous inventory.toml and apply it
curator switch --rollback
```

This command:
1. Enables all COPR repositories listed in `inventory.toml`
2. Disables COPR repositories that are no longer configured
3. Installs all packages listed in `inventory.toml`
4. Creates symlinks for all configured dotfiles
5. Applies environment variables to `~/.config/environment.d/20-curator.conf` and imports them into the user session
6. Creates backups of existing files before replacing them
7. Updates the last switch timestamp

### `status`
Show current configuration status and information.

```bash
curator status
# or ./curator status
```

Displays:
- Configuration directory paths
- Last switch timestamp
- List of configured COPR repositories, packages and dotfiles

### `help`
Show help message with all available commands.

```bash
curator help
# or ./curator help
```

### `from`
Import currently installed packages/repos for a manager into `inventory.toml` so curator can manage them.

```bash
curator from dnf
curator from brew
curator from flatpak
curator from rpm-ostree
curator from nix
curator from copr
```

### `add` / `remove`
Add or remove entries directly in `inventory.toml` using `section:value` pairs. Supports `dnf`, `brew`, `flatpak`, `rpm-ostree`, `nix`, and `copr`.

```bash
curator add dnf:uv nix:micro
curator remove dnf:curl flatpak:org.mozilla.firefox
```

### `reset`
Remove the rollback snapshot (`inventory.toml.rollback`).

```bash
curator reset
```

### `env`
Apply environment variables defined in `[variables]` and propagate them to systemd/DBus. For your current shell, run:

```bash
curator env
# then, to update this shell:
eval "$(curator env --eval-only)"
```

Use `curator env --eval-only` in shell init files if you want each shell to export the current `[variables]` values without touching `environment.d` or systemd/DBus.

## Configuration

### inventory.toml
The central configuration file located at `~/.config/curator/inventory.toml`:

```toml
# curator Configuration File
# User-level configuration similar to home-manager/nixos

[curator]
version = "1.0"
last_switch = ""

[copr]
# copr.fedorainfracloud.org/username/repository
# copr.fedorainfracloud.org/anotheruser/anotherrepo

[dnf]
# git
# vim
# curl
# wget

[brew]
# wget
# coreutils

[flatpak]
# org.mozilla.firefox
# com.spotify.Client

[rpm-ostree]
# podman
# htop

[nix]
# nixpkgs#git   # or just "git" (curator will prefix nixpkgs#)
# nixpkgs#htop  # or just "htop"

[variables]
# ENV_VAR = "value"
# ANOTHER = "another value"

[dotfiles]
# Dotfiles to manage with symlinks
# Format: "target_path" = "source_path"
# target_path: where the symlink should be created (relative to home directory)
# source_path: where the actual file is stored (relative to dotfiles directory)
".bashrc" = ".bashrc"
".config/vimrc" = "vimrc"
".config/alacritty/alacritty.yml" = "alacritty.yml"

[options]
# Additional options
backup = true
backup_dir = "backup"
```

### Configuration Sections

#### `[curator]`
- `version`: Configuration file version
- `last_switch`: Timestamp of last switch operation (auto-updated)

#### `[copr]`
List of COPR repositories to enable via `dnf copr enable`. **One repository per line**—presence means enable, absence means don't enable.

**Examples:**
```toml
[copr]
copr.fedorainfracloud.org/username/repository
copr.fedorainfracloud.org/anotheruser/anotherrepo
```

To remove a COPR repository, simply delete the line containing the repository name. curator will automatically disable it during the next switch.

#### `[dnf]`
List of packages to install via dnf. **One package per line**—presence means install, absence means don't install.

**Examples:**
```toml
[dnf]
git
vim
curl
wget
nodejs
npm
```

To remove a package, simply delete the line containing the package name.

#### `[brew]`
List of packages to install via Homebrew. **One package per line**—presence means install.

#### `[flatpak]`
List of Flatpak refs to install. **One ref per line**—presence means install.

#### `[rpm-ostree]`
List of rpm-ostree layered packages. **One package per line**—presence means install.

#### `[nix]`
List of nix packages. **One package per line**—presence means install. You can specify plain names (e.g., `neovim`) or `nixpkgs#name`; curator will prefix `nixpkgs#` for installs and use the base name for removals.

#### `[variables]`
User environment variables to set via systemd `environment.d`. curator writes them to `~/.config/environment.d/20-curator.conf` during `curator switch`; new sessions will load them automatically.

**Examples:**
```toml
[variables]
EDITOR = "nvim"
PAGER = "less -R"
```

Notes:
- Values are imported into the user systemd and DBus environments during `curator switch` or `curator env`.
- To update a currently running shell, run `eval "$(curator env --eval-only)"` after applying.
- Later shell init files (e.g., `.bashrc`, `.zshrc`) can still override these values.

#### `[dotfiles]`
Dotfile mappings using symlinks:
- **Key**: Target path where symlink should be created (relative to home directory)
- **Value**: Source path where actual file is stored (relative to dotfiles directory)
- Note: Source path automatically prefixed with "dotfiles/" if not present

#### `[options]`
Additional configuration options:
- `backup`: Enable/disable backup of existing files (default: true)
- `backup_dir`: Directory name for backups (relative to curator directory)

## File Structure

```
~/.config/curator/
├── inventory.toml          # Main configuration file
├── dotfiles/           # Your actual dotfiles (source files)
│   ├── .bashrc
│   ├── vimrc
│   └── alacritty.yml
└── backup/            # Backups of replaced files
    ├── .bashrc.20231121_143022.bak
    └── vimrc.20231121_143022.bak
```

## Environment Variables

- `CURATOR_DIR`: Override the default configuration directory (default: `~/.config/curator`)