userctx/README.md

# userctx

Manage you configurations and themes with ease.

## Installation
You just need to copy the file to a directory
in your $PATH (for example: /usr/loca/bin) and 
copy/create a config file.
```bash
sudo install userctx.py /usr/local/bin/userctx
mkdir -p ~/.config/userctx
cp config.toml ~/.config/userctx
```

## userctx basics
**userctx** manages configuration *contexts*. A context is a directory somewhere
in your system which stores actual configuration files for your apps
similar to what resides in ~/.config. 

Typically a context directory looks like this.
```bash
/home/dmitry/.config/userctx/Goldfish
├── sway
│   └── theme.conf
└── wofi
    └── style.css

```
In the above example, context "Goldfish" contains configs for apps "sway" and "wofi". 
These configs will be applied when you apply context "Goldfish".

When a context is applied the app configs from context directory are get
symlinked to youe ~/.config/ folder for each managed app. Goldfish/wofi/style.css symlinks to
\~/.config/wofi/style.css, Goldfish/sway/theme.conf symlinks to \~/.config/sway/theme.conf etc.

This default behaviour can be changed and specific actions or customizations
can be configured on per-app basis by editing **userctx** config file.
The default location for the config is ~/.config/userctx/config.toml.

**userctx** can also be configured to run scripts, trigger your apps to
reload configs etc. For a detailed overview of all config options see below.

There are two commands **userctx** understands: *list* and *apply*.
- *list* lists available contexts in a manner suitable for dmenu-like apps
- *apply* \<context\> applies named context

To test your configuration run:
```bash
userctx --nop apply <context_name>
```
The program will then only output what it will do without changing
anything in your home directory.

For a quickstart and simple examples jump to "Examples" section below.

## Configuring userctx
**userctx** is configured through a TOML file located at `~/.config/userctx/config.toml` by default. The configuration is split into two main sections: `[general]` and `[apps]`.

### The `[general]` section
This section contains global settings for **userctx**.

- `dry_run` (boolean, optional): If set to `true`, **userctx** will only print the actions it would take without making any changes to the filesystem. This is useful for testing your configuration. The command-line flag `--nop` overrides this setting.
- `apps` (array of strings, required): A list of application names that **userctx** should manage. For each application in this list, **userctx** will look for a corresponding configuration section in the `[apps]` table.
- `source_path` (string, optional): The base path where your contexts are stored. Defaults to `$XDG_CONFIG_HOME/userctx` or `~/.config/userctx`.
- `target_path` (string, optional): The base path where application configurations are located. Defaults to `$XDG_CONFIG_HOME` or `~/.config`.

### The `[apps]` section
For each application defined in the `general.apps` array, you can have a dedicated section to specify its configuration.

You can create **[apps.<you_app>]** section in the config to specify **userctx** behaviour for the app. The following options are supported.

- `source_path` (string, optional): Overrides the global `source_path` for this specific application.
- `target_path` (string, optional): Overrides the global `target_path` for this specific application. The final destination path for an application's configuration will be `<target_path>/<app_name>`.
- `actions` (array of strings, optional): A list of actions to perform for the application. The available actions are `symlink`, `script`, `exec`, and `reload`. If not specified, the default actions are `[symlink, script, exec, reload]` if the corresponding keys (`symlink`, `script`, `exec`, `reload`) are present in the app's configuration.
- `symlink` (table, optional): A map of source files to destination files for creating symlinks. The source is relative to the context's application directory (e.g., `<source_path>/<context_name>/<app_name>`), and the destination is relative to the application's `target_path`. You can use `*` as a wildcard to match all files in the source directory.
- `exec` (string, optional): A shell command or script to execute. The script is executed in a shell environment with the following environment variables set:
    - `CONTEXT_NAME`: The name of the context being applied.
    - `CONTEXT_SRC`: The source directory for the current application's context.
    - `CONTEXT_DST`: The target directory for the current application's configuration.
- `script` (array of strings, optional): A list of script files to execute. The scripts are looked for in the application's context directory. If the list is empty or not provided, **userctx** will look for and execute any file ending with `.sh` in the context directory.
- `reload` (string, optional): A shell command to execute to reload the application's configuration. This is typically used to make the application aware of the changes applied by **userctx**.

TODO: a more detailed explanation of wildcard symlinking.

## Examples
### Basic usecase: we only need symlinks
Let's add configuration for "foot" terminal emulator, which 
will be applied when we apply context "Goldfish" assuming
we would like to switch foot's visual theme when swithching context.

1. First we need to create a separate file for visuals config in our
context directory.

```bash
mkdir ~/.config/userctx/Goldfish/foot/
vim ~/.config/userctx/Goldfish/foot/theme.ini
```
And put the awesome "Tempus Day" into theme.ini:
```
# -*- conf -*-
# theme: Tempus Day
# author: Protesilaos Stavrou (https://protesilaos.com)
# description: Light theme with warm colours (WCAG AA compliant)

[colors]
foreground = 464340
# original background
# background = f8f2e5
background = ffffff
regular0 = 464340
regular1 = c81000
regular2 = 107410
regular3 = 806000
regular4 = 385dc4
regular5 = b63052
regular6 = 007070
regular7 = e7e3d7
bright0 = 68607d
bright1 = b24000
bright2 = 427040
bright3 = 6f6600
bright4 = 0f64c4
bright5 = 8050a7
bright6 = 336c87
bright7 = f8f2e5
```
You could as well symlink any file (pre-existing theme for foot) 
to ~/.config/userctx/Goldfish/foot/theme.ini

2. To include this theme file from main foot config add the following line
to $HOME/.config/foot/foot.ini (edit to match your user's homedir):
```
include=/home/dmitry/.config/foot/theme.ini
```
Do not forget to remove style settings from foot.ini so they do not
conflict with separate theme.ini.

3. Finally, tell userctx to manage foot config for you.
Edit ~/.config/userctx/config.toml and add "foot" to "apps"
array in "general" section of the config.
```
[general]
apps = [
  "foot",
  "sway",
  "wofi",
]
```
4. Test you configuration
```bash
userctx --nop apply Goldfish
```
The **--nop** (no-op) flag tells **userctx** to perform a dry-run. It will just output
what it is going to do when you actually apply context.

If all looks good - that's it. When you issue **userctx apply Goldfish**
a symlink will be created in your homedir:

~/.config/foot/theme.ini -> ~/.config/userctx/Goldfish/foot/theme.ini

### More advanced usecase: run command and hot-reload
Let's configure **userctx** to apply theme to helix editor.

1. Similar to the above section, create ~/.config/userctx/Goldfish/helix/helix.toml 
with the following contents:
```toml
inherits = "github_light"
"ui.background" = {}
```
Now edit  ~/.config/userctx/config.toml.

Add "helix" to "general" section.
```toml
[general]
apps = [
  "foot",
  "sway",
  "helix",
  "wofi",
]
```
2. Add "apps.helix" section:
```toml
[apps.helix]
symlink."*" = "themes/current_theme.toml"
exec = """sed -i -E 's/^theme = (.+)/theme = "current_theme"/' ~/.config/helix/config.toml"""
reload = "pkill -USR1 hx"
```
Here we instruct **userctx** to symlink any (single) file it finds in "helix" subdirectory of context folder
to  ~/.config/helix/themes/current_theme.toml

Then we run sed to change the config file. This part is not really necessare if helix is 
configured to use theme named "current_theme" and you're sure that config won't change.
We could just replace the file and issue USR1. The sed part if for the case when config 
is changed by user or other app. 

Finally we set the reload command which
will tell helix to reload config.

3. Test your configuration,
```bash
userctx --nop apply Goldfish
```

See also template "config.toml" with numerous app settings.