curator/README.md

# curator - A Home-Manager Like Tool for Fedora

A lightweight Python CLI (managed with `uv`) for Fedora that provides COPR repository management, dotfile management and package installation functionality through a centralized TOML configuration.

## 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
- Managing dotfiles through symlinks to actual files
- Centralized configuration via a single `inventory.toml` file
- User-level configuration similar to home-manager/nixos
- Automatic backup of existing files before replacement

## Installation

1. Clone or download this repository.
2. Install dependencies with `uv` (none beyond the standard library, but this sets up the venv):
   ```bash
   uv sync
   ```
3. Run with `uv`:
   ```bash
   uv run curator --help
   ```
4. Or use the local shim directly:
   ```bash
   ./curator --help
   ```
5. Optionally install globally via `uv`:
   ```bash
   uv tool install .
   ```

## Quick Start

```bash
# Initialize the configuration structure
uv run curator init

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

# Apply configuration
uv run curator switch

# Check status
uv run curator status
```

You can swap `uv run curator ...` for `./curator ...` if you prefer the local shim.

## Commands

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

```bash
uv run 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
uv run curator switch
# or ./curator switch
# rollback to the previous inventory.toml and apply it
uv run 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. Creates backups of existing files before replacing them
6. Updates the last switch timestamp

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

```bash
uv run 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
uv run curator help
# or ./curator help
```

## 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"

[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.

#### `[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
```

## How It Works

### COPR Repository Management
COPR repositories are managed through the `[copr]` section in `inventory.toml`:
- **Add COPR repo**: Add the repository name on its own line
- **Remove COPR repo**: Remove the entry
- **Automatic cleanup**: curator automatically disables COPR repos that are removed from configuration
- **No flags needed**: Just presence/absence of the repository name matters
- curator stores the previous configuration at `~/.config/curator/inventory.toml.prev` and compares it to the current file during `switch`; newly added repos are enabled, removed repos are disabled.

### Package Management
Packages are managed through the `[dnf]` section in `inventory.toml`:
- **Add package**: Add the package name on its own line
- **Remove package**: Remove the entry
- **No flags needed**: Just presence/absence of the package name matters
- The previous configuration snapshot (`inventory.toml.prev`) is used to detect additions/removals on each `switch`; added packages are installed and removed packages are uninstalled.

### Brew Management
Homebrew packages are managed through the `[brew]` section:
- **Add package**: Add the package name on its own line
- **Remove package**: Remove the entry
- Additions/removals are detected against `inventory.toml.prev` on `switch`; removed packages are uninstalled.

### Flatpak Management
Flatpaks are managed through the `[flatpak]` section:
- **Add ref**: Add the ref on its own line
- **Remove ref**: Remove the entry
- Additions/removals are detected against `inventory.toml.prev` on `switch`; removed refs are uninstalled.

### rpm-ostree Management
rpm-ostree packages are managed through the `[rpm-ostree]` section:
- **Add package**: Add the package name on its own line
- **Remove package**: Remove the entry
- Additions/removals are detected against `inventory.toml.prev` on `switch`; removed packages are uninstalled.

### Nix Management
Nix packages are managed through the `[nix]` section (if `nix` is available on the system):
- **Add package**: Add the package name (e.g., `nixpkgs#git` or just `git`) on its own line
- **Remove package**: Remove the entry
- Additions/removals are detected against `inventory.toml.prev` on `switch`; installs/removals use `nix profile` and will prefix `nixpkgs#` if missing.

### Dotfile Management
curator uses symlinks to manage dotfiles:
1. Your actual dotfiles are stored in `~/.config/curator/dotfiles/`
2. Symlinks are created from your home directory to these files using relative paths
3. This allows you to version control your dotfiles in one place
4. Changes to the source files are immediately reflected in your home directory
5. Source paths are automatically prefixed with "dotfiles/" for convenience

### Backup System
Before creating symlinks, curator:
1. Checks if the target file exists and is not a symlink
2. Creates a timestamped backup in the backup directory
3. Removes the original file
4. Creates the symlink to your managed dotfile

`inventory.toml` is also backed up before the last switch timestamp is updated.

The previously applied configuration is stored separately as `~/.config/curator/inventory.toml.prev` to compute diffs for COPR and package changes.

## Examples

### Basic Setup
```bash
# Initialize curator
uv run curator init

# Edit inventory.toml to add COPR repos and packages
nano ~/.config/curator/inventory.toml

# Add to the sections:
# [copr]
# copr.fedorainfracloud.org/username/cool-repo
# [dnf]
# git
# vim
# curl
# [brew]
# wget
# [flatpak]
# org.mozilla.firefox
# [rpm-ostree]
# podman
# [nix]
# nixpkgs#git (or just "git")

# Create your dotfiles directory and add files
mkdir -p ~/.config/curator/dotfiles
echo "export EDITOR=vim" > ~/.config/curator/dotfiles/.bashrc

# Add to [dotfiles] section:
".bashrc" = ".bashrc"

# Apply configuration
uv run curator switch
```

### Managing Application Configurations
```bash
# Add alacritty configuration
mkdir -p ~/.config/curator/dotfiles
cp ~/.config/alacritty/alacritty.yml ~/.config/curator/dotfiles/

# Edit inventory.toml
nano ~/.config/curator/inventory.toml

# Add to [dotfiles] section:
".config/alacritty/alacritty.yml" = "alacritty.yml"

# Apply changes
uv run curator switch
```

### COPR Repository Management Examples
```toml
[copr]
# Development tools COPR
copr.fedorainfracloud.org/development/tools
copr.fedorainfracloud.org/user/neovim-nightly
# To remove a COPR repo, just delete the entry
# curator will automatically disable it during the next switch
```

### Package Management Examples
```toml
[dnf]
# Development tools
git
vim
nodejs
npm

# System utilities
curl
wget
tree
htop
# To remove a package, just delete the entry

[brew]
# Utilities and tools
wget
coreutils

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

[rpm-ostree]
podman
htop
```

### Version Control Your Configuration
```bash
# Initialize git repository in curator directory
cd ~/.config/curator
git init
git add .
git commit -m "Initial configuration"

# Now you can version control your entire system configuration
git add inventory.toml dotfiles/
git commit -m "Updated vim configuration"
```

## Environment Variables

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

## Dependencies

- Python 3.11+
- `uv` for environment and script management
- `dnf` - Fedora package manager
- `dnf-plugins-core` - For COPR repository management

## Migration from Previous Version

If you were using the old version of curator with `git = true` or bare keys under `[packages]`/`[copr]`:

1. Your existing configuration will not be automatically migrated, but the CLI will still read the legacy format.
2. Run `uv run curator init` (or `./curator init`) to create the new `inventory.toml` structure.
3. Convert to section-per-line format:
   ```toml
   # Old formats
   [dnf]
   git = true
   vim = true
   # or
   [dnf]
   git
   vim

   # New format
   [dnf]
   git
   vim
   [copr]
   copr.fedorainfracloud.org/username/repository
   ```
4. Move your existing dotfiles from the old directory to `~/.config/curator/dotfiles/`

## License

This project is open source. Feel free to contribute or report issues.