fix bug in template exec pattern

README.md

@@ -1,233 +1,142 @@
-# autoconf
-The `autoconf` project is an attempt at wrangling the complexity of configuring many
-applications across one's Linux system. It provides a simple operational model for pulling
-many application config files into one place, as well as generating/setting color schemes
-across apps.
+# Symconf
+`symconf` is a CLI tool for managing local application configuration. It implements a
+general model that supports dynamically switching/reloading themes for any application,
+and provides a basic means of templatizing your config files.
 
-Quick terminology rundown for theme-related items:
+## Simple example
+Below is a simple example demonstrating two system-wide theme switches:
 
-- **Theme**: loose term referring generally to the overall aesthetic of a visual setting.
-  Ignoring stylistic changes (only applicable to some apps; example here might be a
-  a particular setting of the `waybar` layout), a theme is often just the wrapper term for
-  a choice of color _palette_ and _scheme_. For example, "tone4-light" could be a _theme_
-  setting for an app like `kitty`, referring to both a palette and scheme.
-- **Palette**: a set of base colors used to style text or other aspects of an app's
-  displayed assets
-- **Scheme**: an indication of lightness, typically either "light" or "dark.
+![Simple example](docs/_static/example.gif)
 
-As far as managing settings across apps, there are current two useful classifications
-here:
+This GIF shows two `symconf` calls, the first of which applies a `gruvbox` dark theme and
+the second a dark [`monobiome`][1] variant. Each call (of the form `symconf config -m dark -s
+style`) indicates a dark mode preference and a particular color palette that should be
+used when populating config file templates. Specifically, in this example, invoking
+`symconf` results in the following app-specific config updates:
 
-1. **Inseparable from theme**: some apps (e.g., `sway`, `waybar`) have color scheme
-   components effectively built in to their canonical configuration file. This can make it
-   hard to set themes dynamically, as it would likely require some involved
-   matching/substitution rules. This is not a level of complexity I'm willing to embrace,
-   so we simply split the config files according to theme and/or scheme.
-2. **Can load an external theme file**: some apps (e.g., `kitty`) have a clear mechanism
-   for loading themes. This typically implies some distinct color format, although usually
-   somewhat easy to generate (don't have to navigate non-color settings, for instance).
-   Such apps allow for an even less "invasive" config swapping process when setting a new
-   theme, as one can just swap out the external theme file.
+- **GTK**: reacts to the mode setting and sets `prefer-dark` system-wide, changing general
+  GTK-responsive applications like Nautilus and Firefox (and subsequently websites that
+  are responsive to `prefers-color-scheme`)
+- **kitty**: theme template is re-generated using the specified palette, and `kitty`
+  processes are sent a message to live-reload the new config file
+- **neovim**: a `vim` theme file (along with a statusline theme) is generated from the
+  chosen palette, and running instances of `neovim` are sent a message to re-source this
+  theme (via `nvim --remote-send`)
+- **waybar**: bar styles are updated to match the mode setting
+- **sway**: the background color and window borders are dynamically set to base palette
+  colors, and `swaymsg reload` is called
+- **fzf**: a palette-dependent theme is re-generated and re-exported
+- **rofi**: launcher text and highlight colors are set according to the mode and palette,
+  applying on next invocation
 
-To be clear on operation implications here: apps of type (1) must have _manually
-maintained_ config variations according the desired themes. General theme settings must
-follow the naming scheme `<app-name>-<palette>-<scheme>.<ext>`. For example, if I wanted to set
-`sway` to a light variation (which, at the time of writing, would just entail changing a
-single background color), I must have explicitly created a `sway-tone4-light.conf` file
-that captures this setting. The canonical config file will then be symlinked to the
-theme-specific file when the theme is set. (Note that the palette in this example is pretty much
-irrelevant, but it needs to be present in order to match the overarching setting; here you
-can just think of the format being `<app-name>-<theme>.<ext>`, where `tone4-light` is the
-provided theme name.)
+This example highlights the generality of `symconf`, and so long as an app's config can be
+reloaded dynamically, you can use a single `symconf` call to apply themes for an arbitrary
+number of apps at once.
 
-For apps of type (2), the canonical config file can remain untouched so long as it refers
-to a fixed, generic theme file. For example, with `kitty`, my config file can point to a
-`current-theme.conf` file, which will be symlinked to a specific theme file here in
-`autoconf` when a change is requested. This enables a couple of conveniences:
+# Behavior
+`symconf` uses a simple operational model that symlinks centralized config files to their
+expected locations across the system. This central config directory can then be version
+controlled, and app config files can be updated in one place.
 
-- The true config directory on disk remains unpolluted with theme variants.
-- If the set theme is regenerated, there is no intervention necessary to propagate its
-  changes to the target app. The symlinked file itself will be updated when the theme
-  does, ensuring the latest theme version is always immediately available and pointed to
-  by the app.
+App config files can either be concrete (fully-specified) or templates (to be populated by
+values conditional on style, e.g., a palette). When `symconf` is executed with a
+particular mode preference (dark or light) and a style (any other indicator of thematic
+elements, often simply in the form of a palette like `solarized` or `gruvbox`), it
+searches for both concrete and template config files that match and symlinks them to
+registered locations. When necessary, `symconf` will also match and execute scripts to
+reload apps after updating their configuration.
 
-Keep in mind that some apps may fall into some grey area here, allowing some external
-customization but locking down other settings internally. In such instances, there's no
-need to overcomplicate things; just stick to explicit config variants under the type (1)
-umbrella. Type (2) only works for generated themes anyhow; even if the target app can load
-an external theme, type (1) should be used if preset themes are fixed.
+You can find more details on how `symconf`'s matching scheme works in
+[Matching](docs/reference/matching.md).
 
-## Naming standards
-To keep things simple, we use a few fixed naming standards for setting app config files
-and their themed counterparts. The app registry requires each theme-eligible app to
-provide a config directory (`config_dir`), containing some canonical config file
-(`config_file`) and to serve as a place for theme-specific config variations. The
-following naming schemes must be used in order for theme switching to behave
-appropriately: 
+# Configuring
+Before using, you must first set up your config directory to house your config files and
+give `symconf` something to act on. See [Configuring](docs/reference/configuring.md) for
+details.
 
-- When setting a theme for a particular app, the following variables will be available:
-    * `<app-name>`
-    * `<palette>`
-    * `<scheme>`
-- For apps with `external_theme = False`, config variants must named as
-  `<app-name>-<palette>-<scheme>.<ext>`, where `<ext>` is the app's default config file
-  extension.
-- For apps with `external_theme = True`, the file `<config-dir>/current-theme.conf` will
-  be used when symlinking the requested theme. The config file thus must point to this
-  file in order to change with the set theme.
+# Installation
+The recommended way to install `symconf` is via `pipx`, which is particularly well-suited
+for managing Python packages meant to be used as CLI programs. With `pipx` on your system,
+you can install with
 
-  Additionally, the theme symlink will be created from the file
+```sh
+pipx install symconf
+```
 
-  ```
-  <autoconf-root>/autoconf/themes/<palette>/apps/<app-name>/generated/<scheme>.conf
+You can also install via `pip`, or clone and install locally.
+
+# Usage
+- `-h --help`: print help message
+- `-c --config-dir`: set the location of the `symconf` config directory
+- `symconf config` is the subcommand used to match and set available config files for
+  registered applications
+  * `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to consider
+    all registered apps.
+  * `-m --mode`: preferred lightness mode/scheme, either `light`, `dark`, `any`, or
+    `none`.
+  * `-s --style`: style indicator, often the name of a color palette, capturing thematic
+    details in a config file to be matched. `any` or `none` are reserved keywords (see
+    below).
+  * `-T --template-vars`: additional groups to use when populating templates, in the form
+    `<group>=<value>`, where `<group>` is a template group with a folder
+    `$CONFIG_HOME/groups/<group>/` and `<value>` should correspond to a TOML file in this
+    folder (i.e., `<value>.toml`).
+- `symconf generate` is a subcommand that can be used for batch generation of config
+  files. It accepts the same arguments as `symconf config`, but rather than selecting the
+  best match to be used for the system setting, all matching templates are generated.
+  There is one additional required argument:
+  * `-o --output-dir`: the directory under which generated config files should be written.
+    App-specific subdirectories are created to house config files for each provided app.
+- `symconf install`: runs install scripts for matching apps that specify one
+  * `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to consider
+    all registered apps.
+- `symconf update`: runs update scripts for matching apps that specify one
+  * `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to consider
+    all registered apps.
+
+The keywords `any` and `none` can be used when specifying `--mode`, `--style`, or as a
+value in `--template-vars` (and we refer to each of these variables as _factors_ that help
+determine a config match):
+
+- `any` will match config files with _any_ value for this factor, preferring config files
+  with a value `none`, indicating no dependence on the factor. This is the default value
+  when a factor is left unspecified.
+- `none` will match `"none"` directly for a given factor (so no special behavior), but
+  used to indicate that a config file is independent of the factor. For instance,
+
+  ```sh
+  symconf config -m light -s none
   ```
 
-  to `<config-dir>/current-theme.conf`. 
+  will match config files that capture the notion of a light mode, but do not depend on or
+  provide further thematic components such as a color palette.
 
-## Directory structure
+## Examples
+- Set a dark mode for all registered apps, matching any available style/palette component:
 
-- `autoconf/`: main repo directory
-    * `config/`: app-specific configuration files. Each folder inside this directory is
-      app-specific, and the target of associated copy operations when a config sync is
-      performed. Nothing in this directory should pertain to any repo functionality; it
-      should only contain config files that originated elsewhere on the system.
-    * `themes/`: app-independent theme data files. Each folder in this directory should
-      correspond to a specific color palette and house any relevant color spec files
-      (currently likely be a `colors.json`). Also servers the output location for
-      generated theme files
-        * `<palette>/colors.json`: JSON formatted color key-value pairings for palette
-          colors. There's no standard here aside from the filename and format; downstream
-          app-specific TOML templates can be dependent on any key naming scheme within the
-          JSON.
-        + `<palette>/apps/<app-name>/templates/`: houses the TOML maps for the color
-          palette `<palette>` under app `<app-name>`. Files `<fname>.toml` will be mapped to
-          `<fname>.conf` in the theme output folder (below), so ensure the naming
-          standards align with those outlined above.
-        + `<palette>/apps/<app-name>/generated/`: output directory for generated scheme
-          variants. These are the symlink targets for dynamically set external themes.
-    * `app_registry.toml`: global application "registry" used by sync and theme-setting
-      scripts. This lets apps be dynamically added or removed from being eligible for
-      config-related operations.
+  ```sh
+  symconf config -m dark
+  ```
+- Set `solarized` theme for `kitty` and match any available mode (light or dark):
 
-## Scripts
+  ```sh
+  symconf config -s solarized -a kitty
+  ```
+- Set a dark `gruvbox` theme for multiple apps (but not all):
 
-`set_theme.py`: sets a theme across select apps.
+  ```sh
+  symconf config -m dark -s gruvbox -apps="kitty,nvim"
+  ```
+- Set a dark `gruvbox` theme for all apps, and attempt to match other template elements:
 
-- Applies to specific app with `-a <app>` , or to all apps in the `app_registry.toml` with
-  `-a "*"`.
-- Uses symlinks to set canonical config files to theme-based variations. Which files get
-  set depends on the _app type_ (see above), which really just boils down to whether
-  theming (1) can be specified with an external format, and (2) if it depends on
-  auto-generated theme files from within `autoconf`.
-- Palette and scheme are specified as expected. They are used to infer proper paths
-  according to naming and structure standards.
-- Real config files will never be overwritten. To begin setting themes with the script,
-  you must delete the canonical config file expected by the app (and specified in the app
-  registry) to allow the first symlink to be set. From there on out, symlinks will be
-  automatically flushed.
-- A report will be provided on which apps were successfully set to the requested theme,
-  along with the file stems. A number of checks are in place for the existence of involved
-  files and directories. Overall, the risk of overwritting a real config file is low; we
-  only flush existing symlinks, and if the would-be target for the requested theme (be it
-  from an auto-generated theme file, or from a manually manage config variant) doesn't
-  exist, that app's config will be completed skipped. Essentially, everything must be in
-  perfect shape before the symlink trigger is officially pulled.
+  ```sh
+  symconf config -m dark -s gruvbox -T font=mono window=sharp
+  ```
+
+  which would attempt to find and load key-value pairs in the files
+  `$CONFIG_HOME/groups/font/mono.toml` and `$CONFIG_HOME/groups/window/sharp.toml` to be
+  used as values when filling templatized config files.
 
 
-`gen_theme.py`: generates theme files for palettes by mapping their color definitions
-through app-specific templates. These templates specific how to relate an app's theme
-variables to the color names provided by the template.
 
-- An app and palette are the two required parameters. If no template or output paths are
-  provided, they will be inferred according to the theme path standards seen above.
-- The `--template` argument can be a directory or a file, depending on what theme files
-  you'd like to render.
-- The `--output` path, if specified, must be a directory. Generated theme files take on
-  a name with the same stem as their source template, but using the `.conf` extension.
-- The TOML templates should make config variable names to JSON dot-notation accessors. If
-  color definitions are nested, the dot notation should be properly expanded by the script
-  when mapping the colors to keyword values.
-- There are a number of checks for existing paths, even those inferred (e.g., template and
-  output) from the palette and app. If the appropriate setup hasn't been followed, the
-  script will fail. Make sure the `theme` folder in question and it's nested `app`
-  directory are correctly setup before running the script. (Perhaps down the line there
-  are some easy auto-setup steps to take here, but I'm not making that jump now.)
-- TODO: open up different app "writers," or make it easy to extend output syntax based on
-  the app in question. This would like be as simple as mapping app names to
-  line-generating functions, which accept the keyword and color (among other items). This
-  can be fleshed out as needed.
-
-`sync.sh`: copies relevant configuration files from local paths into the `autoconf`
-subpath. Markdown files in the docs directory then reference the local copies of these
-files, meaning the documentation updates dynamically when the configuration files do. That
-is, the (possibly extracted) config snippets will change with the current state of my
-system config without any manual intervention of the documentation files.
-
-### Specific theme-setting example
-To make clear how the theme setting script works on my system, the following breaks down
-exactly what steps are taken to exert as much scheme control as possible. Everything at this
-point is wrapped up in a single `make set-<palette>-<scheme>` call; suppose we're
-currently running the dark scheme (see first image) and I run `make set-tone4-light`:
-
-![
-  Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
-  system-dependent default theme set). In Firefox, I have open `localsys` with its
-  scheme-mode to set to "auto," which should reflect the theme setting picked up by the
-  browser (and note the white tab icon).
-](_static/set-theme-1.png)
-
-_(Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
-system-dependent default theme set). In Firefox, I have open `localsys` with its
-scheme-mode to set to "auto," which should reflect the theme setting picked up by the
-browser (and note the white tab icon).)_
-
-1. `set_theme.py` is invoked. Global settings are applied first, based on my OS (`Linux`),
-   which calls
-
-   ```
-   gsettings set org.gnome.desktop.interface color-scheme 'prefer-light'
-   ```
-
-   controlling settings for GTK apps and other `desktop-portal`-aware programs. This
-   yields the following:
-
-   ![Portal-aware apps changed, config apps not yet set](_static/set-theme-2.png)
-
-   _(Portal-aware apps changed, config apps not yet set. Scheme-aware sites are updated
-   without page refresh.)_
-2. Specific application styles are set. For now the list is small, including `kitty`,
-   `waybar`, and `sway`. `kitty` is the only type (2) application here, whereas the other
-   two are type (1).
-
-   a. For the type (1) apps, the canonical config files as specified in the app registry
-      are symlinked to their light variants. For `sway`, this is `~/.config/sway/config`,
-      and if we look at the `file`:
-
-      ```sh
-      .config/sway/config: symbolic link to ~/.config/sway/sway-tone4-light
-      ```
-   b. For the type (2) apps, just the `current-theme.conf` file is symlinked to the
-      relevant palette-scheme file. `kitty` is such an app, with a supported theme file
-      for `tone4`, and those files have been auto-generated via `gen_theme.py`. Looking at
-      this file under the `kitty` config directory:
-
-      ```sh
-      .config/kitty/current-theme.conf: symbolic link to ~/Documents/projects/autoconf/autoconf/themes/tone4/apps/kitty/generated/light.conf
-      ```
-
-      The `kitty.conf` file isn't changed, as all palette-related items are specified in
-      the theme file. (Note that the general notion of a "theme" could include changes to
-      other stylistic aspects, like the font family; this would likely require some hybrid
-      type 1-2 approach not yet implemented).
-3. Live application instances are reloaded, according to the registered `refresh_cmd`s.
-   Here the apps with style/config files set in step (2) are reloaded to reflect those
-   changes. Again, in this example, this is `kitty`, `sway`, and the `waybar`.
-
-   ![Final light setting: portal-dependent apps _and_ config-based apps changed](_static/set-theme-3.png)
-
-   _(Final light setting: portal-dependent apps _and_ config-based apps changed)_
-4. `set_theme.py` provides a report for the actions taken; in this case, the following was
-   printed:
-
-   ![`set_theme.py` output](_static/set-theme-4.png)
-   _(`set_theme.py` output)_
+[1]: https://github.com/ologio/monobiome

REFACTOR.md

@@ -52,3 +52,4 @@
 - Refresh scripts should likely specify a shell shabang at the top of the file
 - `apps` can serve as a dotfiles folder
 - Support symlinking whole folders?
+- `any` might prefer to match configs with none over specific options, but will match any

TODO.md

@@ -1,5 +1,3 @@
-- Push scheme generation to `~/.config/autoconf`
-- Copy default app registry to the config location
-- Formalize the theme spec (JSON) and `autoconf gen` to produce color configs
-- Likely need to formalize the `sync.sh` script logic better, possibly associated directly
-  with registry TOML
+- Add local app caching for `auto` logic
+- Better script handling: 1) should be live, basically reconnecting output to native
+  terminal, 2) catch and print errors from STDERR

autoconf/__init__.py

@@ -1 +0,0 @@
-from autoconf.config import ConfigManager

autoconf/__main__.py

@@ -1,102 +0,0 @@
-import argparse
-
-import util
-#from gen_theme import generate_theme_files
-from autoconf.config import ConfigManager
-
-
-def add_set_subparser(subparsers):
-    def update_app_settings(args):
-        cm = ConfigManager(args.config_dif)
-        cm.update_apps(
-            apps=args.apps,
-            scheme=args.scheme,
-            palette=args.palette,
-        )
-
-    parser = subparsers.add_parser(
-        'set',
-        description='Generate theme files for various applications. Uses a template (in TOML ' \
-                  + 'format) to map application-specific config keywords to colors (in JSON '  \
-                  + 'format).' 
-    )
-    parser.add_argument(
-        '-p', '--palette',
-        required = False,
-        default  = "any",
-        help     = 'Palette name, must match a folder in themes/'
-    )
-    parser.add_argument(
-        '-s', '--scheme',
-        required = False,
-        default  = "any",
-        help     = 'Preferred lightness scheme, either "light" or "dark".'
-    )
-    parser.add_argument(
-        '-a', '--apps',
-        required = False,
-        default  = "any",
-        type     = lambda s: s.split(',') if s != '*' else s
-        help     = 'Application target for theme. App must be present in the registry. ' \
-                 + 'Use "*" to apply to all registered apps'
-    )
-    parser.set_defaults(func=update_app_settings)
-
-def add_gen_subparser(subparsers):
-    parser = subparsers.add_parser(
-        'gen',
-        description='Generate theme files for various applications. Uses a template (in TOML ' \
-                  + 'format) to map application-specific config keywords to colors (in JSON '  \
-                  + 'format).' 
-    )
-    parser.add_argument(
-        '-a', '--app',
-        required=True,
-        help='Application target for theme. Supported: ["kitty"]'
-    )
-    parser.add_argument(
-        '-p', '--palette',
-        required=True,
-        help='Palette to use for template mappings. Uses local "theme/<palette>/colors.json".'
-    )
-    parser.add_argument(
-        '-t', '--template',
-        default=None,
-        help='Path to TOML template file. If omitted, app\'s default template path is used.' \
-           + 'If a directory is provided, all TOML files in the folder will be used.'
-    )
-    parser.add_argument(
-        '-o', '--output',
-        default=None,
-        help='Output file path for theme. If omitted, app\'s default theme output path is used.'
-    )
-    parser.set_defaults(func=generate_theme_files)
-
-
-# central argparse entry point
-parser = argparse.ArgumentParser(
-    'autoconf',
-    description='Generate theme files for various applications. Uses a template (in TOML ' \
-              + 'format) to map application-specific config keywords to colors (in JSON '  \
-              + 'format).' 
-)
-parser.add_argument(
-    '-c', '--config-dir',
-    default = util.xdg_config_path(),
-    type    = util.absolute_path,
-    help    = 'Path to config directory'
-)
-
-# add subparsers
-subparsers = parser.get_subparsers()
-#add_gen_subparser(subparsers)
-add_set_subparser(subparsers)
-
-
-if __name__ == '__main__':
-    args = parser.parse_args()
-
-    if 'func' in args:
-        args.func(args)
-    else:
-        parser.print_help()

autoconf/config.py

@@ -1,370 +0,0 @@
-import os
-import json
-import inspect
-import tomllib
-import argparse
-import subprocess
-from pathlib import Path
-
-from colorama import Fore, Back, Style
-
-from autoconf import util
-
-
-class ConfigManager:
-    def __init__(
-        self,
-        config_dir=None,
-        disable_registry=False,
-    ):
-        '''
-        Configuration manager class
-
-        Parameters:
-            config_dir: config parent directory housing expected files (registry,
-                        app-specific conf files, etc). Defaults to
-                        ``"$XDG_CONFIG_HOME/autoconf/"``.
-            disable_registry: disable checks for a registry file in the ``config_dir``.
-                              Should really only be set when using this programmatically
-                              and manually supplying app settings.
-        '''
-        if config_dir == None:
-            config_dir = util.xdg_config_path()
-
-        self.config_dir = util.absolute_path(config_dir)
-        self.apps_dir   = Path(self.config_dir, 'apps')
-
-        self.app_registry = {}
-
-        self._check_paths()
-
-        if not disable_registry:
-            self._check_registry()
-
-    def _check_paths(self):
-        '''
-        Check necessary paths for existence.
-
-        Regardless of programmatic use or ``disable_registry``, we need to a valid
-        ``config_dir`` and it must have an ``apps/`` subdirectory (otherwise there are
-        simply no files to act on, not even when manually providing app settings).
-        '''
-        # throw error if config dir doesn't exist
-        if not self.config_dir.exists():
-            raise ValueError(
-                f'Config directory "{self.config_dir}" doesn\'t exist.'
-            )
-        
-        # throw error if apps dir doesn't exist or is empty
-        if not self.apps_dir.exists() or not list(self.apps_dir.iterdir()):
-            raise ValueError(
-                f'Config directory "{self.config_dir}" must have an "apps/" subdirectory.'
-            )
-
-    def _check_registry(self):
-        registry_path = Path(self.config_dir, 'app_registry.toml')
-
-        self.app_registry = {}
-        if not registry_path.exists():
-            print(
-                Fore.YELLOW \
-                + f'No registry file found at expected location "{registry_path}"'
-            )
-            return
-
-        app_registry = tomllib.load(registry_path.open('rb'))
-
-        if 'app' not in app_registry:
-            print(
-                Fore.YELLOW \
-                + f'Registry file found but is either empty or incorrectly formatted (no "app" key).'
-            )
-
-        self.app_registry = app_registry.get('app', {})
-
-    def resolve_scheme(self, scheme):
-        # if scheme == 'auto':
-        #     os_cmd_groups = {
-        #         'Linux': (
-        #             "gsettings get org.gnome.desktop.interface color-scheme",
-        #             lambda r: r.split('-')[1][:-1],
-        #         ),
-        #         'Darwin': (),
-        #     }
-
-        #     osname = os.uname().sysname
-        #     os_group = os_cmd_groups.get(osname, [])
-
-        #     for cmd in cmd_list:
-        #         subprocess.check_call(cmd.format(scheme=scheme).split())
-
-        # return scheme
-
-        if scheme == 'auto':
-            return 'any'
-
-        return scheme
-
-    def resolve_palette(self, palette):
-        if palette == 'auto':
-            return 'any'
-
-        return palette
-
-    def app_config_map(self, app_name):
-        '''
-        Get the config map for a provided app.
-
-        The config map is a dict mapping from config file **path names** to their absolute
-        path locations. That is, 
-
-        ```sh
-        <config_path_name> -> <config_dir>/apps/<app_name>/<subdir>/<palette>-<scheme>.<config_path_name>
-        ```
-
-        For example,
-
-        ```
-        palette1-light.conf.ini -> ~/.config/autoconf/apps/user/palette1-light.conf.ini
-        palette2-dark.app.conf -> ~/.config/autoconf/apps/generated/palette2-dark.app.conf
-        ```
-
-        This ensures we have unique config names pointing to appropriate locations (which
-        is mostly important when the same config file names are present across ``user``
-        and ``generated`` subdirectories).
-        '''
-        # first look in "generated", then overwrite with "user"
-        file_map = {}
-        app_dir  = Path(self.apps_dir, app_name)
-        for subdir in ['generated', 'user']:
-            subdir_path = Path(app_dir, subdir)
-
-            if not subdir_path.is_dir():
-                continue
-
-            for conf_file in subdir_path.iterdir():
-                file_map[conf_file.name] = conf_file
-
-        return file_map
-
-    def get_matching_configs(
-        self, 
-        app_name,
-        scheme='auto',
-        palette='auto',
-    ) -> dict[str, str]:
-        '''
-        Get app config files that match the provided scheme and palette.
-
-        Unique config file path names are written to the file map in order of specificity.
-        All config files follow the naming scheme ``<palette>-<scheme>.<path-name>``,
-        where ``<palette>-<scheme>`` is the "theme part" and ``<path-name>`` is the "conf
-        part." For those config files with the same "conf part," only the entry with the
-        most specific "theme part" will be stored. By "most specific," we mean those
-        entries with the fewest possible components named ``any``, with ties broken in
-        favor of a more specific ``palette`` (the only "tie" really possible here is when
-        `any-<scheme>` and `<palette>-any` are both available, in which case the latter
-        will overwrite the former).
-        '''
-        app_dir = Path(self.apps_dir, app_name)
-
-        scheme  = self.resolve_scheme(scheme)
-        palette = self.resolve_palette(palette)
-
-        # now match theme files in order of inc. specificity; for each unique config file
-        # tail, only the most specific matching file sticks
-        file_parts = []
-        app_config_map = self.app_config_map(app_name)
-        for pathname in app_config_map:
-            parts = pathname.split('.')
-
-            if len(parts) < 2:
-                print(f'Filename "{filename}" incorrectly formatted, ignoring')
-                continue
-
-            theme_part, conf_part = parts[0], '.'.join(parts[1:])
-            file_parts.append((theme_part, conf_part, pathname))
-
-        theme_prefixes = [
-            'any-any',
-            f'any-{scheme}',
-            f'{palette}-any',
-            f'{palette}-{scheme}'
-        ]
-
-        matching_file_map = {}
-        for theme_prefix in theme_prefixes:
-            for theme_part, conf_part, pathname in file_parts:
-                if theme_part == theme_prefix:
-                    matching_file_map[conf_part] = app_config_map[pathname]
-
-        return matching_file_map
-
-    def get_matching_scripts(
-        self,
-        app_name,
-        scheme='any',
-        palette='any',
-    ):
-        '''
-        Execute matching scripts in the app's ``call/`` directory.
-
-        Scripts need to be placed in 
-
-        ```sh
-        <config_dir>/apps/<app_name>/call/<palette>-<scheme>.sh
-        ```
-
-        and are matched using the same heuristic employed by config file symlinking
-        procedure (see ``get_matching_configs()``).
-        '''
-        app_dir  = Path(self.apps_dir, app_name)
-        call_dir = Path(app_dir, 'call')
-        
-        if not call_dir.is_dir():
-            return
-
-        theme_prefixes = [
-            'any-any',
-            f'any-{scheme}',
-            f'{palette}-any',
-            f'{palette}-{scheme}'
-        ]
-
-        # do it this way to keep order for downstream exec
-        script_list = []
-        for theme_prefix in theme_prefixes:
-            for script_path in call_dir.iterdir():
-                theme_part = script_path.stem
-                if theme_part == theme_prefix:
-                    script_list.append(script_path)
-
-        return list(set(script_list))
-
-    def update_app_config(
-        self,
-        app_name,
-        app_settings = None,
-        scheme       = 'any',
-        palette      = 'any',
-    ):
-        '''
-        Perform full app config update process, applying symlinks and running scripts.
-
-        Note that this explicitly accepts app settings to override or act in place of
-        missing app details in the app registry file. This is mostly to provide more
-        programmatic control and test settings without needing them present in the
-        registry file. The ``update_apps()`` method, however, **will** more strictly
-        filter out those apps not in the registry, accepting a list of app keys that
-        ultimately call this method.
-
-        Note: symlinks point **from** the target location **to** the known internal config
-        file; can be a little confusing.
-        '''
-        if app_settings is None:
-            app_settings = self.app_registry.get(app_name, {})
-
-        if 'config_dir' in app_settings and 'config_map' in app_settings:
-            print(f'App "{app_name}" incorrectly configured, skipping')
-            return
-
-        to_symlink: list[tuple[Path, Path]] = []
-        file_map = self.get_matching_configs(
-            app_name,
-            scheme=scheme,
-            palette=palette,
-        )
-        if 'config_dir' in app_settings:
-            for config_tail, full_path in file_map.items():
-                to_symlink.append((
-                    util.absolute_path(Path(app_settings['config_dir'], config_tail)), # point from real config dir
-                    full_path, # to internal config location
-                ))
-        elif 'config_map' in app_settings:
-            for config_tail, full_path in file_map.items():
-                # app's config map points config tails to absolute paths
-                if config_tail in app_settings['config_map']:
-                    to_symlink.append((
-                        abs_pat(Path(app_settings['config_map'][config_tail])), # point from real config path
-                        full_path, # to internal config location
-                    ))
-
-        links_succ = []
-        links_fail = []
-        for from_path, to_path in to_symlink:
-            if not to_path.exists():
-                print(f'Internal config path "{to_path}" doesn\'t exist, skipping')
-                links_fail.append((from_path, to_path))
-                continue
-
-            if not from_path.parent.exists():
-                print(f'Target config parent directory for "{from_path}" doesn\'t exist, skipping')
-                links_fail.append((from_path, to_path))
-                continue
-
-            # if config file being symlinked exists & isn't already a symlink (i.e.,
-            # previously set by this script), throw an error. 
-            if from_path.exists() and not from_path.is_symlink():
-                print(
-                    f'Symlink target "{from_path}" exists and isn\'t a symlink, NOT overwriting;' \
-                   + ' please first manually remove this file so a symlink can be set.'
-                )
-                links_fail.append((from_path, to_path))
-                continue
-            else:
-                # if path doesn't exist, or exists and is symlink, remove the symlink in
-                # preparation for the new symlink setting
-                from_path.unlink(missing_ok=True)
-
-            #print(f'Linking [{from_path}] -> [{to_path}]')
-            from_path.symlink_to(to_path)
-            links_succ.append((from_path, to_path))
-
-            # run matching scripts for app-specific reload
-            # TODO: store the status of this cmd & print with the messages
-            script_list = self.get_matching_scripts(
-                app_name,
-                scheme=scheme,
-                palette=palette,
-            )
-            for script in script_list:
-                print(Fore.BLUE + f'> Running script "{script.relative_to(self.config_dir}"')
-                output = subprocess.check_output(str(script), shell=True)
-                print(
-                    Fore.BLUE + Style.DIM + f'-> Captured script output "{output.decode().strip()}"' + Style.RESET
-                )
-
-        for from_p, to_p in links_succ:
-            from_p = from_p
-            to_p   = to_p.relative_to(self.config_dir)
-            print(Fore.GREEN + f'> {app_name} :: {from_p} -> {to_p}')
-
-        for from_p, to_p in links_fail:
-            from_p = from_p
-            to_p   = to_p.relative_to(self.config_dir)
-            print(Fore.RED + f'> {app_name} :: {from_p} -> {to_p}')
-
-    def update_apps(
-        self,
-        apps: str | list[str] = '*',
-        scheme                = 'any',
-        palette               = 'any',
-    ):
-        if apps == '*':
-            # get all registered apps
-            app_list = list(self.app_registry.keys())
-        else:
-            # get requested apps that overlap with registry
-            app_list = [a for a in app_list if a in app_registry]
-
-        if not app_list:
-            print(f'None of the apps "apps" are registered, exiting')
-            return
-
-        for app_name in app_list:
-            self.update_app_config(
-                app_name,
-                app_settings=app_registry[app_name],
-                scheme=scheme,
-                palette=palette,
-            )

autoconf/theme.py

@@ -1,74 +0,0 @@
-import argparse
-import inspect
-import json
-import tomllib as toml
-from pathlib import Path
-
-
-# separation sequences to use base on app
-app_sep_map = {
-    'kitty': ' ',
-}
-
-def generate_theme_files():
-    basepath = get_running_path()
-
-    # set arg conditional variables 
-    palette_path  = Path(basepath, 'themes', args.palette)
-    colors_path   = Path(palette_path, 'colors.json')
-    theme_app     = args.app
-
-    template_path = None
-    output_path   = None
-
-    if args.template is None:
-        template_path = Path(palette_path, 'apps', theme_app, 'templates')
-    else:
-        template_path = Path(args.template).resolve()
-
-    if args.output is None:
-        output_path = Path(palette_path, 'apps', theme_app, 'generated')
-    else:
-        output_path = Path(args.output).resolve()
-
-    # check paths
-    if not colors_path.exists():
-        print(f'Resolved colors path [{colors_path}] doesn\'t exist, exiting')
-        return
-    
-    if not template_path.exists():
-        print(f'Template path [{template_path}] doesn\'t exist, exiting')
-        return
-
-    if not output_path.exists() or not output_path.is_dir():
-        print(f'Output path [{output_path}] doesn\'t exist or not a directory, exiting')
-        return
-
-    print(f'Using palette colors [{colors_path}]')
-    print(f'-> with templates in [{template_path}]')
-    print(f'-> to output path [{output_path}]\n')
-
-    # load external files (JSON, TOML)
-    colors_json = json.load(colors_path.open())
-
-    # get all matching TOML files
-    template_list = [template_path]
-    if template_path.is_dir():
-        template_list = template_path.rglob('*.toml')
-
-    for template_path in template_list:
-        template_toml = toml.load(template_path.open('rb'))
-
-        # lookup app-specific config separator
-        config_sep = app_sep_map.get(theme_app, ' ')
-        output_lines = []
-        for config_key, color_key in template_toml.items():
-            color_value = colors_json
-            for _key in color_key.split('.'):
-                color_value = color_value.get(_key, {})
-            output_lines.append(f'{config_key}{config_sep}{color_value}') 
-
-        output_file = Path(output_path, template_path.stem).with_suffix('.conf')
-        output_file.write_text('\n'.join(output_lines))
-        print(f'[{len(output_lines)}] lines written to [{output_file}] for app [{theme_app}]')
-

autoconf/util.py

@@ -1,9 +0,0 @@
-from pathlib import Path
-from xdg import BaseDirectory
-
-
-def absolute_path(path: str | Path) -> Path:
-    return Path(path).expanduser().absolute()
-    
-def xdg_config_path():
-    return Path(BaseDirectory.save_config_path('autoconf'))

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -6,7 +6,7 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = '<project-name>'
+project = 'symconf'
 copyright = '2024, Sam Griesemer'
 author = 'Sam Griesemer'
 
@@ -15,18 +15,25 @@ author = 'Sam Griesemer'
 
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.viewcode",
-    "myst_parser",
+    "sphinx.ext.autosummary", # enables a directive to be specified manually that gathers
+                              # module/object summary details in a table
+    "sphinx.ext.viewcode",    # allow viewing source in the HTML pages
+    "myst_parser",            # only really applies to manual docs; docstrings still need RST-like
+    "sphinx.ext.napoleon",    # enables Google-style docstring formats
+    "sphinx_autodoc_typehints", # external extension that allows arg types to be inferred by type hints
 ]
 autosummary_generate = True
 autosummary_imported_members = True
 
+# include __init__ definitions in autodoc
+autodoc_default_options = {
+    'special-members': '__init__',
+}
+
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

docs/index.md

@@ -1,29 +1,41 @@
-# `autoconf` package docs 
+# `symconf` package docs 
 {ref}`genindex`
 {ref}`modindex`
 {ref}`search`
 
+## Top-level module overview
+
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
+   :recursive:
 
-    # list modules here for quick links
+    symconf.config
+    symconf.template
+    symconf.matching
+    symconf.reader
+    symconf.runner
+```
+
+## Auto-reference contents
+```{toctree}
+:maxdepth: 3
+
+_autoref/symconf.rst
 ```
 
 ```{toctree}
-:maxdepth: 3
-:caption: Autoref
-
-_autoref/autoconf.rst
-```
-
-```{toctree}
-:maxdepth: 3
+:maxdepth: 2
 :caption: Contents
 
+reference/configuring
+reference/usage
+reference/archive
 reference/documentation/index
-reference/site/index
 ```
 
 ```{include} ../README.md
+:relative-docs: docs/
+:relative-images:
 ```
+

docs/reference/archive.md

@@ -0,0 +1,233 @@
+# Archive
+The `autoconf` project is an attempt at wrangling the complexity of configuring many
+applications across one's Linux system. It provides a simple operational model for pulling
+many application config files into one place, as well as generating/setting color schemes
+across apps.
+
+Quick terminology rundown for theme-related items:
+
+- **Theme**: loose term referring generally to the overall aesthetic of a visual setting.
+  Ignoring stylistic changes (only applicable to some apps; example here might be a
+  a particular setting of the `waybar` layout), a theme is often just the wrapper term for
+  a choice of color _palette_ and _scheme_. For example, "tone4-light" could be a _theme_
+  setting for an app like `kitty`, referring to both a palette and scheme.
+- **Palette**: a set of base colors used to style text or other aspects of an app's
+  displayed assets
+- **Scheme**: an indication of lightness, typically either "light" or "dark.
+
+As far as managing settings across apps, there are current two useful classifications
+here:
+
+1. **Inseparable from theme**: some apps (e.g., `sway`, `waybar`) have color scheme
+   components effectively built in to their canonical configuration file. This can make it
+   hard to set themes dynamically, as it would likely require some involved
+   matching/substitution rules. This is not a level of complexity I'm willing to embrace,
+   so we simply split the config files according to theme and/or scheme.
+2. **Can load an external theme file**: some apps (e.g., `kitty`) have a clear mechanism
+   for loading themes. This typically implies some distinct color format, although usually
+   somewhat easy to generate (don't have to navigate non-color settings, for instance).
+   Such apps allow for an even less "invasive" config swapping process when setting a new
+   theme, as one can just swap out the external theme file.
+
+To be clear on operation implications here: apps of type (1) must have _manually
+maintained_ config variations according the desired themes. General theme settings must
+follow the naming scheme `<app-name>-<palette>-<scheme>.<ext>`. For example, if I wanted to set
+`sway` to a light variation (which, at the time of writing, would just entail changing a
+single background color), I must have explicitly created a `sway-tone4-light.conf` file
+that captures this setting. The canonical config file will then be symlinked to the
+theme-specific file when the theme is set. (Note that the palette in this example is pretty much
+irrelevant, but it needs to be present in order to match the overarching setting; here you
+can just think of the format being `<app-name>-<theme>.<ext>`, where `tone4-light` is the
+provided theme name.)
+
+For apps of type (2), the canonical config file can remain untouched so long as it refers
+to a fixed, generic theme file. For example, with `kitty`, my config file can point to a
+`current-theme.conf` file, which will be symlinked to a specific theme file here in
+`autoconf` when a change is requested. This enables a couple of conveniences:
+
+- The true config directory on disk remains unpolluted with theme variants.
+- If the set theme is regenerated, there is no intervention necessary to propagate its
+  changes to the target app. The symlinked file itself will be updated when the theme
+  does, ensuring the latest theme version is always immediately available and pointed to
+  by the app.
+
+Keep in mind that some apps may fall into some grey area here, allowing some external
+customization but locking down other settings internally. In such instances, there's no
+need to overcomplicate things; just stick to explicit config variants under the type (1)
+umbrella. Type (2) only works for generated themes anyhow; even if the target app can load
+an external theme, type (1) should be used if preset themes are fixed.
+
+## Naming standards
+To keep things simple, we use a few fixed naming standards for setting app config files
+and their themed counterparts. The app registry requires each theme-eligible app to
+provide a config directory (`config_dir`), containing some canonical config file
+(`config_file`) and to serve as a place for theme-specific config variations. The
+following naming schemes must be used in order for theme switching to behave
+appropriately: 
+
+- When setting a theme for a particular app, the following variables will be available:
+    * `<app-name>`
+    * `<palette>`
+    * `<scheme>`
+- For apps with `external_theme = False`, config variants must named as
+  `<app-name>-<palette>-<scheme>.<ext>`, where `<ext>` is the app's default config file
+  extension.
+- For apps with `external_theme = True`, the file `<config-dir>/current-theme.conf` will
+  be used when symlinking the requested theme. The config file thus must point to this
+  file in order to change with the set theme.
+
+  Additionally, the theme symlink will be created from the file
+
+  ```
+  <autoconf-root>/autoconf/themes/<palette>/apps/<app-name>/generated/<scheme>.conf
+  ```
+
+  to `<config-dir>/current-theme.conf`. 
+
+## Directory structure
+
+- `autoconf/`: main repo directory
+    * `config/`: app-specific configuration files. Each folder inside this directory is
+      app-specific, and the target of associated copy operations when a config sync is
+      performed. Nothing in this directory should pertain to any repo functionality; it
+      should only contain config files that originated elsewhere on the system.
+    * `themes/`: app-independent theme data files. Each folder in this directory should
+      correspond to a specific color palette and house any relevant color spec files
+      (currently likely be a `colors.json`). Also servers the output location for
+      generated theme files
+        * `<palette>/colors.json`: JSON formatted color key-value pairings for palette
+          colors. There's no standard here aside from the filename and format; downstream
+          app-specific TOML templates can be dependent on any key naming scheme within the
+          JSON.
+        + `<palette>/apps/<app-name>/templates/`: houses the TOML maps for the color
+          palette `<palette>` under app `<app-name>`. Files `<fname>.toml` will be mapped to
+          `<fname>.conf` in the theme output folder (below), so ensure the naming
+          standards align with those outlined above.
+        + `<palette>/apps/<app-name>/generated/`: output directory for generated scheme
+          variants. These are the symlink targets for dynamically set external themes.
+    * `app_registry.toml`: global application "registry" used by sync and theme-setting
+      scripts. This lets apps be dynamically added or removed from being eligible for
+      config-related operations.
+
+## Scripts
+
+`set_theme.py`: sets a theme across select apps.
+
+- Applies to specific app with `-a <app>` , or to all apps in the `app_registry.toml` with
+  `-a "*"`.
+- Uses symlinks to set canonical config files to theme-based variations. Which files get
+  set depends on the _app type_ (see above), which really just boils down to whether
+  theming (1) can be specified with an external format, and (2) if it depends on
+  auto-generated theme files from within `autoconf`.
+- Palette and scheme are specified as expected. They are used to infer proper paths
+  according to naming and structure standards.
+- Real config files will never be overwritten. To begin setting themes with the script,
+  you must delete the canonical config file expected by the app (and specified in the app
+  registry) to allow the first symlink to be set. From there on out, symlinks will be
+  automatically flushed.
+- A report will be provided on which apps were successfully set to the requested theme,
+  along with the file stems. A number of checks are in place for the existence of involved
+  files and directories. Overall, the risk of overwritting a real config file is low; we
+  only flush existing symlinks, and if the would-be target for the requested theme (be it
+  from an auto-generated theme file, or from a manually manage config variant) doesn't
+  exist, that app's config will be completed skipped. Essentially, everything must be in
+  perfect shape before the symlink trigger is officially pulled.
+
+
+`gen_theme.py`: generates theme files for palettes by mapping their color definitions
+through app-specific templates. These templates specific how to relate an app's theme
+variables to the color names provided by the template.
+
+- An app and palette are the two required parameters. If no template or output paths are
+  provided, they will be inferred according to the theme path standards seen above.
+- The `--template` argument can be a directory or a file, depending on what theme files
+  you'd like to render.
+- The `--output` path, if specified, must be a directory. Generated theme files take on
+  a name with the same stem as their source template, but using the `.conf` extension.
+- The TOML templates should make config variable names to JSON dot-notation accessors. If
+  color definitions are nested, the dot notation should be properly expanded by the script
+  when mapping the colors to keyword values.
+- There are a number of checks for existing paths, even those inferred (e.g., template and
+  output) from the palette and app. If the appropriate setup hasn't been followed, the
+  script will fail. Make sure the `theme` folder in question and it's nested `app`
+  directory are correctly setup before running the script. (Perhaps down the line there
+  are some easy auto-setup steps to take here, but I'm not making that jump now.)
+- TODO: open up different app "writers," or make it easy to extend output syntax based on
+  the app in question. This would like be as simple as mapping app names to
+  line-generating functions, which accept the keyword and color (among other items). This
+  can be fleshed out as needed.
+
+`sync.sh`: copies relevant configuration files from local paths into the `autoconf`
+subpath. Markdown files in the docs directory then reference the local copies of these
+files, meaning the documentation updates dynamically when the configuration files do. That
+is, the (possibly extracted) config snippets will change with the current state of my
+system config without any manual intervention of the documentation files.
+
+### Specific theme-setting example
+To make clear how the theme setting script works on my system, the following breaks down
+exactly what steps are taken to exert as much scheme control as possible. Everything at this
+point is wrapped up in a single `make set-<palette>-<scheme>` call; suppose we're
+currently running the dark scheme (see first image) and I run `make set-tone4-light`:
+
+![
+  Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
+  system-dependent default theme set). In Firefox, I have open `localsys` with its
+  scheme-mode to set to "auto," which should reflect the theme setting picked up by the
+  browser (and note the white tab icon).
+](_static/set-theme-1.png)
+
+_(Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
+system-dependent default theme set). In Firefox, I have open `localsys` with its
+scheme-mode to set to "auto," which should reflect the theme setting picked up by the
+browser (and note the white tab icon).)_
+
+1. `set_theme.py` is invoked. Global settings are applied first, based on my OS (`Linux`),
+   which calls
+
+   ```
+   gsettings set org.gnome.desktop.interface color-scheme 'prefer-light'
+   ```
+
+   controlling settings for GTK apps and other `desktop-portal`-aware programs. This
+   yields the following:
+
+   ![Portal-aware apps changed, config apps not yet set](_static/set-theme-2.png)
+
+   _(Portal-aware apps changed, config apps not yet set. Scheme-aware sites are updated
+   without page refresh.)_
+2. Specific application styles are set. For now the list is small, including `kitty`,
+   `waybar`, and `sway`. `kitty` is the only type (2) application here, whereas the other
+   two are type (1).
+
+   a. For the type (1) apps, the canonical config files as specified in the app registry
+      are symlinked to their light variants. For `sway`, this is `~/.config/sway/config`,
+      and if we look at the `file`:
+
+      ```sh
+      .config/sway/config: symbolic link to ~/.config/sway/sway-tone4-light
+      ```
+   b. For the type (2) apps, just the `current-theme.conf` file is symlinked to the
+      relevant palette-scheme file. `kitty` is such an app, with a supported theme file
+      for `tone4`, and those files have been auto-generated via `gen_theme.py`. Looking at
+      this file under the `kitty` config directory:
+
+      ```sh
+      .config/kitty/current-theme.conf: symbolic link to ~/Documents/projects/autoconf/autoconf/themes/tone4/apps/kitty/generated/light.conf
+      ```
+
+      The `kitty.conf` file isn't changed, as all palette-related items are specified in
+      the theme file. (Note that the general notion of a "theme" could include changes to
+      other stylistic aspects, like the font family; this would likely require some hybrid
+      type 1-2 approach not yet implemented).
+3. Live application instances are reloaded, according to the registered `refresh_cmd`s.
+   Here the apps with style/config files set in step (2) are reloaded to reflect those
+   changes. Again, in this example, this is `kitty`, `sway`, and the `waybar`.
+
+   ![Final light setting: portal-dependent apps _and_ config-based apps changed](_static/set-theme-3.png)
+
+   _(Final light setting: portal-dependent apps _and_ config-based apps changed)_
+4. `set_theme.py` provides a report for the actions taken; in this case, the following was
+   printed:
+
+   ![`set_theme.py` output](_static/set-theme-4.png)
+   _(`set_theme.py` output)_

docs/reference/configuring.md

@@ -0,0 +1,178 @@
+# Configuring
+`symconf` operates on a central directory that houses all of the config files you may wish
+to apply. The default location for this directory is your `$XDG_CONFIG_HOME` (e.g.,
+`~/.config/symconf/`), but it can be any location on your system so long as it's specified
+(see more in Usage). 
+
+`symconf` expects you to create two top-level components in your config directory: an
+`apps/` directory and an `app_registry.toml` file.
+
+**High-level view**:
+
+- `symconf` operates on a single directory that houses all your config files
+- Config files in this directory must be placed under an `apps/<app-name>/` folder to be
+  associated with the app `<app-name>`
+- For apps to be visible, you need an `app_registry.toml` file that tells `symconf` where
+  to symlink your files in `apps/`
+
+## Apps directory
+An `apps/` directory should be created in your config home, with a subdirectory
+`apps/<app-name>/` for each app with config files that you'd like to be visible to
+`symconf`. Note that simply populating an app's config folder here will do nothing on its
+own; the app must also have been registered (discussed in item #2) in order for these
+files to be used when `symconf` is invoked. (This just means you can populate your `apps/`
+folder safely without expecting any default behavior. More often than not you'll be
+expected to tell `symconf` exactly where your config files should end up, meaning you know
+exactly what it's doing.)
+
+### User config 
+Inside your app-specific subdirectory, your managed config files should be placed in a
+`user/` subdirectory (distinguishing them from those generated by templates; see more
+in Themes). Your config files themselves are then expected to follow a specific naming
+scheme:
+
+```sh
+<palette>-<scheme>.<config-name>
+```
+
+This ties your config file to a particular theme setting as needed, and `symconf` will
+apply it if it matches the theme setting you provide when invoked. The specific values are
+as follows:
+
+- `scheme`: can be `light`, `dark`, or `none`. Indicates whether the config file should
+  be applied specifically when requesting a light or dark mode. Use `none` to indicate
+  that the config file does not have settings specific to a light/dark mode.
+- `palette`: a "palette name" of your choosing, or `none`. The palette name you use
+  here may refer specifically to a color palette used by the config file, but can be
+  used generally to indicate any particular group of config settings (e.g., fonts,
+  transparency, etc). Use `none` to indicate that the file does not correspond to any
+  particular style group.
+- `config-name`: the _name_ of the config file. This should correspond to _same path
+  name_ that is expected by the app being configured. For example, if your app expects a
+  config file at `a/b/c/d.conf`, "`d.conf`" is the path name.
+
+When invoking `symconf` with specific scheme and palette settings (see more in Usage),
+appropriate config files can be matched based on how you've named your files.
+
+For example, suppose I want to set up a simple light/dark mode switch for the `kitty`
+terminal emulator. The following tree demonstrates a valid setup:
+
+```sh
+<config-home>
+└── apps/
+    └── kitty/
+        └── user/
+            ├── none-light.kitty.conf
+            └── none-dark.kitty.conf
+```
+
+where `none-light.kitty.conf` may set a light background and `none-dark.kitty.conf` a dark
+one. `none` is used for the `<palette>` part of the name to indicate the configuration does
+not pertain to any specific palette and can be matched even if one is not provided. With
+an appropriate `app_regsitry.toml` file (see below), invoking 
+
+```sh
+symconf --theme=light --apps=kitty
+```
+
+would symlink `$XDG_CONFIG_HOME/symconf/apps/kitty/user/none-light.kitty.conf` to
+`~/.config/kitty/kitty.conf`.
+
+### Templatized config
+Note the potential inconvenience in needing to manage two separate config files in the
+above example, very likely with all but one line of difference. Templating enables
+populating config template files dynamically with theme-specific variables of your
+choosing.
+
+
+### Reload scripts
+After symlinking a new set of config files, it is often necessary to reload the system or
+relevant apps in order for the new config settings to apply. Within an app's subdirectory,
+a `call/` folder can be created to hold scripts that should apply based on certain schemes
+or palettes (matching them in the same way as config files). For example,
+
+```sh
+<config-home>
+└── apps/
+    └── kitty/
+        └── call/
+            └── none-none.sh
+```
+
+`none-none.sh` might simply contain `kill -s USR1 $(pgrep kitty)`, which is a way to tell
+all running `kitty` instances to reload their config settings. Again, following the naming
+scheme for config files, a script named `none-none.sh` will apply under any scheme or
+palette specification. Thus, in our light/dark mode switch example, invoking `symconf
+--theme=light --apps=kitty` would:
+
+1. Search and match the config name `none-light.kitty.conf` and symlink it to
+   `~/.config/kitty/kitty.conf`.
+2. Search and match `none-none.sh` and execute it, applying the new light mode settings to
+   all running `kitty` instances.
+
+
+## App registry
+An `app_registry.toml` file, used to specify the target locations for app-specific
+config files. To "register" an app, you simply need to add the following text block to
+the `app_registry.toml` file:
+
+```toml
+[app.<app-name>]
+# DEFINE *ONE* OF THE FOLLOWING
+config_dir = "<path-to-app-config-folder>"
+# OR 
+config_map = {
+    "<conf-pathname-1>" = "<path-to-exact-config-file>"
+    "<conf-pathname-2>" = "<path-to-exact-config-file>"
+    # ...
+}
+```
+
+(Note that text in angle brackets refers to values that should be replaced.) This tells
+`symconf` how it should handle each app's config files. The `<app-name>` (e.g.,
+`kitty`) should correspond to a subdirectory under `apps/` (e.g., `apps/kitty/`) that
+holds your config files for that app. As shown, you then need to supply either of the
+following options:
+
+- `config_dir`: specifies a single directory where all of the app's matching config
+  files should be symlinked. In the `kitty` example, this might be `~/.config/kitty`.
+  This is the simplest and most common option provided most apps expect all of their
+  config files to be in a single directory.
+- `config_map`: a dictionary mapping config file _path names_ to the _exact paths_ that
+  should be created during the symlink process. This is typically needed when an app
+  has many config files that need to be set in several disparate locations across your
+  system. In the `kitty` example, although not necessary (and in general you should
+  prefer to set `config_dir` when applicable), we could have the following
+  `config_map`:
+
+  ```toml
+  [app.kitty]
+  config_map = {
+      "kitty.conf": "~/.config/kitty/kitty.conf"
+  }
+  ```
+
+  This tells `symconf` to symlink the exact location `~/.config/kitty/kitty.conf` to
+  the matching `kitty.conf` under the `apps/kitty` directory.
+
+## Directory structure
+In total, the structure of your base config directory can look as follows:
+
+```sh
+~/.config/symconf/
+├── app_registry.toml
+└── apps/
+    └── <app>/
+        ├── user/                      # user managed
+        │   └── none-none.<config-name>
+        ├── generated/                 # automatically populated
+        │   └── none-none.<config-name>
+        ├── templates/                 # config templates
+        │   └── none-none.template
+        └── call/                      # reload scripts
+            └── none-none.sh
+```
+
+## Misc remarks
+
+### Multiple config files with same path name

docs/reference/documentation/index.md

@@ -1,8 +1,5 @@
 # Documentation
 
 ```{toctree}
-:hidden:
-
 sphinx
 ```
-

docs/reference/matching.md

@@ -0,0 +1,17 @@
+# Matching
+This file describes the naming and matching scheme employed by `symconf`.
+
+```
+~/.config/symconf/
+├── app_registry.toml
+└── apps/
+    └── <app>/
+        ├── user/                      # user managed
+        │   └── none-none.<config-name>
+        ├── generated/                 # automatically populated
+        │   └── none-none.<config-name>
+        ├── templates/                 # config templates
+        │   └── none-none.template
+        └── call/                      # reload scripts
+            └── none-none.sh
+```

docs/reference/usage.md

@@ -0,0 +1,6 @@
+# Usage
+
+```{toctree}
+:hidden:
+
+```

pyproject.toml

@@ -25,8 +25,12 @@ classifiers = [
 ]
 dependencies = [
     "pyxdg",
+    "colorama",
 ]
 
+[project.scripts]
+symconf = "symconf.__main__:main"
+
 [project.optional-dependencies]
 tests = ["pytest"]
 docs = [
@@ -36,6 +40,7 @@ docs = [
     "furo",
     "myst-parser",
 ]
+build = ["build", "twine"]
 
 [project.urls]
 Homepage = "https://doc.olog.io/symconf"

symconf/__init__.py

@@ -0,0 +1,16 @@
+from symconf.runner import Runner
+from symconf.reader import DictReader
+from symconf.config import ConfigManager
+from symconf.matching import Matcher, FilePart
+from symconf.template import Template, FileTemplate, TOMLTemplate
+
+from symconf import config
+from symconf import matching
+from symconf import reader
+from symconf import template
+from symconf import util
+
+from importlib.metadata import version
+
+
+__version__ = version('symconf')

symconf/__main__.py

@@ -0,0 +1,179 @@
+import argparse
+from importlib.metadata import version
+
+from symconf import util, __version__
+from symconf.config import ConfigManager
+
+
+def add_install_subparser(subparsers):
+    def install_apps(args):
+        cm = ConfigManager(args.config_dir)
+        cm.install_apps(apps=args.apps)
+
+    parser = subparsers.add_parser(
+        'install',
+        description='Run install scripts for registered applications.'
+    )
+    parser.add_argument(
+        '-a', '--apps',
+        required = False,
+        default  = "*",
+        type     = lambda s: s.split(',') if s != '*' else s,
+        help     = 'Application target for theme. App must be present in the registry. ' \
+                 + 'Use "*" to apply to all registered apps'
+    )
+    parser.set_defaults(func=install_apps)
+
+def add_update_subparser(subparsers):
+    def update_apps(args):
+        cm = ConfigManager(args.config_dir)
+        cm.update_apps(apps=args.apps)
+
+    parser = subparsers.add_parser(
+        'update',
+        description='Run update scripts for registered applications.'
+    )
+    parser.add_argument(
+        '-a', '--apps',
+        required = False,
+        default  = '*',
+        type     = lambda s: s.split(',') if s != '*' else s,
+        help     = 'Application target for theme. App must be present in the registry. ' \
+                 + 'Use "*" to apply to all registered apps'
+    )
+    parser.set_defaults(func=update_apps)
+
+def add_config_subparser(subparsers):
+    def configure_apps(args):
+        cm = ConfigManager(args.config_dir)
+        cm.configure_apps(
+            apps=args.apps,
+            scheme=args.mode,
+            style=args.style,
+            **args.template_vars
+        )
+
+    parser = subparsers.add_parser(
+        'config',
+        description='Set config files for registered applications.'
+    )
+    parser.add_argument(
+        '-s', '--style',
+        required = False,
+        default  = 'any',
+        help     = 'Style indicator (often a color palette) capturing thematic details in '
+                   'a config file'
+    )
+    parser.add_argument(
+        '-m', '--mode',
+        required = False,
+        default  = "any",
+        help     = 'Preferred lightness mode/scheme, either "light," "dark," "any," or "none."'
+    )
+    parser.add_argument(
+        '-a', '--apps',
+        required = False,
+        default  = "*",
+        type     = lambda s: s.split(',') if s != '*' else s,
+        help     = 'Application target for theme. App must be present in the registry. ' \
+                 + 'Use "*" to apply to all registered apps'
+    )
+    parser.add_argument(
+        '-T', '--template-vars',
+        required = False,
+        nargs='+',
+        default  = {},
+        action=util.KVPair,
+        help='Groups to use when populating templates, in the form group=value'
+    )
+    parser.set_defaults(func=configure_apps)
+
+def add_generate_subparser(subparsers):
+    def generate_apps(args):
+        cm = ConfigManager(args.config_dir)
+        cm.generate_app_templates(
+            gen_dir=args.output_dir,
+            apps=args.apps,
+            scheme=args.mode,
+            style=args.style,
+            **args.template_vars
+        )
+
+    parser = subparsers.add_parser(
+        'generate',
+        description='Generate all template config files for specified apps'
+    )
+    parser.add_argument(
+        '-o', '--output-dir',
+        required = True,
+        type     = util.absolute_path,
+        help     = 'Path to write generated template files'
+    )
+    parser.add_argument(
+        '-s', '--style',
+        required = False,
+        default  = 'any',
+        help     = 'Style indicator (often a color palette) capturing thematic details in '
+                   'a config file'
+    )
+    parser.add_argument(
+        '-m', '--mode',
+        required = False,
+        default  = "any",
+        help     = 'Preferred lightness mode/scheme, either "light," "dark," "any," or "none."'
+    )
+    parser.add_argument(
+        '-a', '--apps',
+        required = False,
+        default  = "*",
+        type     = lambda s: s.split(',') if s != '*' else s,
+        help     = 'Application target for theme. App must be present in the registry. ' \
+                 + 'Use "*" to apply to all registered apps'
+    )
+    parser.add_argument(
+        '-T', '--template-vars',
+        required = False,
+        nargs    = '+',
+        default  = {},
+        action   = util.KVPair,
+        help     = 'Groups to use when populating templates, in the form group=value'
+    )
+    parser.set_defaults(func=generate_apps)
+
+
+# central argparse entry point
+parser = argparse.ArgumentParser(
+    'symconf',
+    description='Manage application configuration with symlinks.'
+)
+parser.add_argument(
+    '-c', '--config-dir',
+    default = util.xdg_config_path(),
+    type    = util.absolute_path,
+    help    = 'Path to config directory'
+)
+parser.add_argument(
+    '-v', '--version',
+    action='version',
+    version=__version__,
+    help    = 'Print symconf version'
+)
+
+# add subparsers
+subparsers = parser.add_subparsers(title='subcommand actions')
+add_config_subparser(subparsers)
+add_generate_subparser(subparsers)
+add_install_subparser(subparsers)
+add_update_subparser(subparsers)
+
+
+def main():
+    args = parser.parse_args()
+
+    if 'func' in args:
+        args.func(args)
+    else:
+        parser.print_help()
+
+if __name__ == '__main__':
+    main()

symconf/config.py

@@ -0,0 +1,879 @@
+'''
+Primary config management abstractions
+
+The config map is a dict mapping from config file **path names** to their absolute
+path locations. That is,
+
+.. code-block:: sh
+
+    <config_path_name> -> <config_dir>/apps/<app_name>/<subdir>/<palette>-<scheme>.<config_path_name>
+
+For example,
+
+.. code-block:: sh
+
+    palette1-light.conf.ini -> ~/.config/symconf/apps/user/palette1-light.conf.ini
+    palette2-dark.app.conf -> ~/.config/symconf/apps/generated/palette2-dark.app.conf
+
+This ensures we have unique config names pointing to appropriate locations (which
+is mostly important when the same config file names are present across ``user``
+and ``generated`` subdirectories; unique path names need to be resolved to unique
+path locations).
+'''
+import os
+import tomllib
+from pathlib import Path
+
+from colorama import Fore, Back, Style
+
+from symconf import util
+from symconf.util import printc, color_text
+
+from symconf.runner import Runner
+from symconf.template import FileTemplate, TOMLTemplate
+from symconf.matching import Matcher, FilePart
+
+
+class ConfigManager:
+    def __init__(
+        self,
+        config_dir=None,
+        disable_registry=False,
+    ):
+        '''
+        Configuration manager class
+
+        Parameters:
+            config_dir: config parent directory housing expected files (registry,
+                        app-specific conf files, etc). Defaults to
+                        ``"$XDG_CONFIG_HOME/symconf/"``.
+            disable_registry: disable checks for a registry file in the ``config_dir``.
+                              Should really only be set when using this programmatically
+                              and manually supplying app settings.
+        '''
+        if config_dir == None:
+            config_dir = util.xdg_config_path()
+
+        self.config_dir = util.absolute_path(config_dir)
+        self.apps_dir   = Path(self.config_dir, 'apps')
+        self.group_dir  = Path(self.config_dir, 'groups')
+
+        self.app_registry = {}
+        self.matcher = Matcher()
+        self.runner  = Runner()
+
+        self._check_dirs()
+        if not disable_registry:
+            self._check_registry()
+
+    def _check_dirs(self):
+        '''
+        Check necessary config directories for existence.
+
+        Regardless of programmatic use or ``disable_registry``, we need a valid
+        ``config_dir`` and it must have an ``apps/`` subdirectory (otherwise there are
+        simply no files to act on, not even when manually providing app settings).
+        '''
+        # throw error if config dir doesn't exist
+        if not self.config_dir.exists():
+            raise ValueError(
+                f'Config directory "{self.config_dir}" doesn\'t exist.'
+            )
+        
+        # throw error if apps dir doesn't exist or is empty
+        if not self.apps_dir.exists() or not list(self.apps_dir.iterdir()):
+            raise ValueError(
+                f'Config directory "{self.config_dir}" must have an "apps/" subdirectory.'
+            )
+
+    def _check_registry(self):
+        '''
+        Check the existence and format of the registry file
+        ``<config_dir>/app_registry.toml``.
+
+        All that's needed to pass the format check is the existence of the key `"app"` in
+        the registry dict. If this isn't present, the TOML file is either incorrectly
+        configured, or it's empty and there are no apps to operate on.
+        '''
+        registry_path = Path(self.config_dir, 'app_registry.toml')
+
+        if not registry_path.exists():
+            printc(
+                f'No registry file found at expected location "{registry_path}"',
+                Fore.YELLOW
+            )
+            return
+
+        app_registry = tomllib.load(registry_path.open('rb'))
+
+        if 'app' not in app_registry:
+            printc(
+                'Registry file found but is either empty or incorrectly formatted (no "app" key).',
+                Fore.YELLOW
+            )
+
+        self.app_registry = app_registry.get('app', {})
+
+    def _resolve_group(self, group, value='auto'):
+        '''
+        Resolve group inputs to concrete values.
+
+        This method is mostly meant to handle values like ``auto`` which can be provided
+        by the user, but need to be interpreted in the system context (e.g., either
+        resolving to "any" or using the app's currently set option from the cache).
+        '''
+        if value == 'auto':
+            # look group up in app cache and set to current value
+            return 'any'
+
+        return value
+
+    def _symlink_paths(
+        self,
+        to_symlink: list[tuple[Path, Path]],
+    ):
+        '''
+        Symlink paths safely from target paths to internal config paths 
+
+        This method upholds the consistent symlink model: target locations are only
+        symlinked from if they don't exist or are already a symlink. We never overwrite
+        any concrete files, preventing accidental deletion of config files. This means
+        users must physically delete/move their existing configs into a ``symconf`` config
+        directory if they want it to be managed; otherwise, we don't touch it.
+
+        Parameters:
+            to_symlink: path pairs to symlink, from target (external) path to source
+                        (internal) path
+        '''
+        links_succ = []
+        links_fail = []
+        for from_path, to_path in to_symlink:
+            if not to_path.exists():
+                print(f'Internal config path "{to_path}" doesn\'t exist, skipping')
+                links_fail.append((from_path, to_path))
+                continue
+
+            # if config file being symlinked exists & isn't already a symlink (i.e.,
+            # previously set by this script), throw an error.
+            if from_path.exists() and not from_path.is_symlink():
+                printc(
+                    f'Symlink target "{from_path}" exists and isn\'t a symlink, NOT overwriting; '
+                    f'please first manually remove this file so a symlink can be set.',
+                    Fore.RED 
+                )
+                links_fail.append((from_path, to_path))
+                continue
+            else:
+                # if path doesn't exist, or exists and is symlink, remove the symlink in
+                # preparation for the new symlink setting
+                from_path.unlink(missing_ok=True)
+
+            # create parent directory if doesn't exist
+            from_path.parent.mkdir(parents=True, exist_ok=True)
+
+            from_path.symlink_to(to_path)
+            links_succ.append((from_path, to_path))
+
+        # link report
+        for from_p, to_p in links_succ:
+            from_p = util.to_tilde_path(from_p)
+            to_p   = to_p.relative_to(self.config_dir)
+            print(
+                color_text("│", Fore.BLUE),
+                color_text(
+                    f' > linked {color_text(from_p,Style.BRIGHT)} -> {color_text(to_p,Style.BRIGHT)}',
+                    Fore.GREEN
+                )
+            )
+
+        for from_p, to_p in links_fail:
+            from_p = util.to_tilde_path(from_p)
+            to_p   = to_p.relative_to(self.config_dir)
+            print(
+                color_text("│", Fore.BLUE),
+                color_text(
+                    f' > failed to link {from_p} -> {to_p}',
+                    Fore.RED
+                )
+            )
+
+    def _matching_template_groups(
+        self, 
+        scheme = 'auto',
+        style  = 'auto',
+        **kw_groups,
+    ) -> tuple[dict, list[FilePart]]:
+        '''
+        Find matching template files for provided template groups.
+
+        For template groups other than "scheme" and "style," this method performs a
+        basic search for matching filenames in the respective group directory. For
+        example, a KW group like ``font = "mono"`` would look for ``font/mono.toml`` (as
+        well as the relaxation ``font/none.toml``). These template TOML files are stacked
+        and ultimately presented to downstream config templates to be filled. Note how
+        there is no dependence on the scheme during the filename match (e.g., we don't
+        look for ``font/mono-dark.toml``).
+
+        For "scheme" and "style," we have slightly different behavior, more closely
+        aligning with the non-template matching. We don't have "scheme" and "style"
+        template folders, but a single "theme" folder, within which we match template
+        files just the same as we do for non-template config files. That is, we will look
+        for files of the format
+
+        .. code-block:: sh
+
+            <style>-<scheme>.toml
+
+        The only difference is that, while ``style`` can still include arbitrary style
+        variants, it *must* have the form
+
+        .. code-block:: sh
+
+            <variant-1>-...-<variant-N>-<palette>
+        
+        if you want to match a ``palette`` template. Palettes are like regular template
+        groups, and should be placed in their own template folder. But when applying those
+        palette colors, they almost always need to be coupled with a scheme setting (e.g.,
+        "solarized-dark"). This is the one place where the templating system allows
+        "intermediate templates:" raw palette colors can fill theme templates, which then
+        fill user config templates.
+
+        So in summary: palette files can be used to populate theme templates by providing a
+        style string that matches the format ``<variant>-<palette>``. The ``<palette>``
+        will be extracted and used to match filenames in the palette template folder. The
+        term ``<variant>-<palette>-<scheme>`` will be used to match templates in the theme
+        folder, where ``<variant>-<palette> = <style>`` and ``<scheme>`` are independently
+        specifiable with supported for ``auto``, ``none``, etc.
+
+        Note that "strictness" doesn't really apply in this setting. In the non-template
+        config matching setting, setting strict means there's no relaxation to "none," but
+        here, any "none" group template files just help fill any gaps (but are otherwise
+        totally overwritten, even if matched, by more precise matches). You can match
+        ``nones`` directly if you want by specifying that directly.
+        ``get_matching_scripts()`` is similar in this sense.
+        '''
+        scheme = self._resolve_group('scheme', scheme)
+        style  = self._resolve_group('style', style)
+
+        groups = {
+            k : self._resolve_group(k, v)
+            for k, v in kw_groups.items()
+        }
+
+        if not self.group_dir.exists():
+            return {}, []
+
+        # palette lookup will behave like other groups; strip it out of the `style` string
+        # and it to the keyword groups to be searched regularly (but only if the palette
+        # group exists)
+        if Path(self.group_dir, 'palette').exists():
+            palette = style.split('-')[-1]
+            groups['palette'] = palette
+
+        # handle individual groups (not part of joint style-scheme)
+        group_matches = {}
+        for fkey, fval in groups.items():
+            key_group_dir = Path(self.group_dir, fkey)
+
+            if not key_group_dir.exists():
+                print(f'Group directory "{fkey}" doesn\'t exist, skipping')
+                continue
+
+            # mirror matching scheme: 1) prefix order, 2) full enumeration, 3) select
+            # best, 4) make unique, 5) ordered relaxation
+            stem_map = {path.stem : path for path in key_group_dir.iterdir()}
+
+            # 1) establish prefix order
+            if fval == 'any':
+                prefix_order = [fval, 'none']
+            else:
+                prefix_order = ['none', fval]
+
+            # 2) fully enumerate matches, including "any"
+            matches = []
+            for prefix in prefix_order:
+                for stem in stem_map:
+                    if prefix == stem or prefix == 'any':
+                        matches.append(stem)
+
+            if not matches:
+                # no matches for group, skip
+                continue
+
+            # 3) select best matches; done in a loop to smooth the logic, else we'd need
+            # to check if the last match is "none," and if not, find out if it was
+            # available. This alone makes the following loop more easy to follow: walk
+            # through full enumeration, and if it's the target match or "none," take the
+            # file, nicely handling the fact those may both be the same.
+            #
+            # also 4) uniqueness happening here
+            match_dict = {}
+            target = matches[-1] # select best based on order, make new target
+            for stem in matches:
+                if stem == target or stem == 'none':
+                    match_dict[stem] = stem_map[stem]
+
+            group_matches[fkey] = list(match_dict.values())
+
+        # first handle scheme maps; matching palette files should already be found in the
+        # regular group matching process. This is the one template group that gets nested
+        # treatment
+        palette_dict = TOMLTemplate.stack_toml(group_matches.get('palette', []))
+
+        # then palette-scheme groups (require 2-combo logic)
+        theme_matches = []
+        theme_group_dir = Path(self.group_dir, 'theme')
+
+        if theme_group_dir.exists():
+            theme_matches = self.matcher.match_paths(
+                theme_group_dir.iterdir(),               # match files in groups/theme/
+                self.matcher.prefix_order(scheme, style) # reg non-template order
+            )
+
+        # 5) final match relaxation
+        relaxed_theme_matches = self.matcher.relaxed_match(theme_matches)
+
+        theme_dict = {}
+        for file_part in relaxed_theme_matches:
+            toml_dict = TOMLTemplate(file_part.path).fill(palette_dict)
+            theme_dict = util.deep_update(theme_dict, toml_dict)
+
+        template_dict = {
+            group : TOMLTemplate.stack_toml(ordered_matches)
+            for group, ordered_matches in group_matches.items()
+        }
+        template_dict['theme'] = theme_dict
+
+        return template_dict, relaxed_theme_matches
+
+    def _prepare_all_templates(
+        self,
+        scheme = 'any',
+        style  = 'any',
+    ) -> dict[str, dict]:
+        palette_map = {}
+        palette_group_dir = Path(self.group_dir, 'palette')
+        if palette_group_dir.exists():
+            for palette_path in palette_group_dir.iterdir():
+                palette_map[palette_path.stem] = palette_path
+
+        palette_base = []
+        if 'none' in palette_map:
+            palette_base.append(palette_map['none'])
+
+        # then palette-scheme groups (require 2-combo logic)
+        theme_matches = []
+        theme_group_dir = Path(self.group_dir, 'theme')
+        if theme_group_dir.exists():
+            theme_matches = self.matcher.match_paths(
+                theme_group_dir.iterdir(),     # match files in groups/theme/
+                self.matcher.prefix_order(     # reg non-template order
+                    scheme, style, strict=True # set strict=True to ignore "nones"
+                ) 
+            )
+
+        theme_map = {}
+        for fp in theme_matches:
+            # still look through whole theme dir here (eg to match nones)
+            theme_matches = self.matcher.match_paths(
+                theme_group_dir.iterdir(),               # match files in groups/theme/
+                self.matcher.prefix_order(fp.scheme, fp.style) # reg non-template order
+            )
+            relaxed_theme_matches = self.matcher.relaxed_match(theme_matches)
+
+            palette = fp.style.split('-')[-1]
+            palette_paths = [*palette_base]
+            if palette in palette_map:
+                palette_paths.append(palette_map[palette])
+
+            theme_dict = {}
+            palette_dict = TOMLTemplate.stack_toml(palette_paths)
+            for file_part in relaxed_theme_matches:
+                toml_dict = TOMLTemplate(file_part.path).fill(palette_dict)
+                theme_dict = util.deep_update(theme_dict, toml_dict)
+
+            theme_map[fp.path.stem] = {'theme': theme_dict}
+
+        return theme_map
+
+    def get_matching_configs(
+        self, 
+        app_name,
+        scheme = 'auto',
+        style  = 'auto',
+        strict = False,
+    ) -> dict[str, FilePart]:
+        '''
+        Get user-provided app config files that match the provided scheme and style
+        specifications.
+
+        Unique config file path names are written to the file map in order of specificity.
+        All config files follow the naming scheme ``<style>-<scheme>.<path-name>``,
+        where ``<style>-<scheme>`` is the "theme part" and ``<path-name>`` is the "conf
+        part." For those config files with the same "conf part," only the entry with the
+        most specific "theme part" will be stored. By "most specific," we mean those
+        entries with the fewest possible components named ``none``, with ties broken in
+        favor of a more specific ``style`` (the only "tie" really possible here is when
+        ``none-<scheme>`` and ``<style>-none`` are both available, in which case the latter
+        will overwrite the former).
+
+        .. admonition:: Edge cases
+
+            There are a few quirks to this matching scheme that yield potentially
+            unintuitive results. As a recap:
+
+            - The "theme part" of a config file name includes both a style (palette and
+              more) and a scheme component. Either of those parts may be "none," which
+              simply indicates that that particular file does not attempt to change that
+              factor. "none-light," for instance, might simply set a light background,
+              having no effect on other theme settings.
+            - Non-keyword queries for scheme and style will always be matched exactly.
+              However, if an exact match is not available, we also look for "none" in each
+              component's place. For example, if we wanted to set "solarized-light" but
+              only "none-light" was available, it would still be set because we can still
+              satisfy the desire scheme (light). The same goes for the style
+              specification, and if neither match, "none-none" will always be matched if
+              available. Note that if "none" is specified exactly, it will be matched
+              exactly, just like any other value.
+            - During a query, "any" may also be specified for either component, indicating
+              we're okay to match any file's text for that part. For example, if I have
+              two config files ``"p1-dark"`` and ``"p2-dark"``, the query for ``("any",
+              "dark")`` would suggest I'd like the dark scheme but am okay with either
+              style.
+
+            It's under the "any" keyword where possibly counter-intuitive results may come
+            about. Specifying "any" does not change the mechanism that seeks to optionally
+            match "none" if no specific match is available. For example, suppose we have
+            the config file ``red-none`` (setting red colors regardless of a light/dark
+            mode). If I query for ``("any", "dark")``, ``red-none`` will be matched
+            (supposing there are no more direct matches available). Because we don't a
+            match specifically for the scheme "dark," it gets relaxed to "none." But we
+            indicated we're okay to match any style. So despite asking for a config that
+            sets a dark scheme and not caring about the style, we end up with a config
+            that explicitly does nothing about the scheme but sets a particular style.
+            This matching process is still consistent with what we expect the keywords to
+            do, it just slightly muddies the waters with regard to what can be matched
+            (mostly due to the amount that's happening under the hood here).
+
+            This example is the primary driver behind the optional ``strict`` setting,
+            which in this case would force the dark scheme to be matched (and ultimately
+            find no matches).
+
+            Also: when "any" is used for a component, options with "none" are prioritized,
+            allowing "any" to be as flexible and unassuming as possible (only matching a
+            random specific config among the options if there is no "none" available).
+
+        Returns:
+            Dictionary 
+        '''
+        user_app_dir = Path(self.apps_dir, app_name, 'user')
+
+        paths = []
+        if user_app_dir.is_dir():
+            paths = user_app_dir.iterdir()
+        
+        # 1) establish prefix order
+        prefix_order = self.matcher.prefix_order(
+            self._resolve_group('scheme', scheme),
+            self._resolve_group('style', style),
+            strict=strict
+        )
+
+        # 2) match enumeration
+        ordered_matches = self.matcher.match_paths(paths, prefix_order)
+
+        # 3) make unique (by pathname)
+        matching_file_map = {
+            file_part.conf : file_part
+            for file_part in ordered_matches
+        }
+
+        return matching_file_map
+
+    def get_matching_templates(
+        self,
+        app_name,
+        scheme='auto',
+        style='auto',
+        **kw_groups,
+    ) -> tuple[dict[str, Path], dict, list[FilePart], int]:
+        template_dict, theme_matches = self._matching_template_groups(
+            scheme=scheme,
+            style=style,
+            **kw_groups,
+        )
+
+        max_idx = 0
+        if theme_matches:
+            max_idx = max([fp.index for fp in theme_matches])
+
+        template_map = {}
+        template_dir = Path(self.apps_dir, app_name, 'templates')
+        if template_dir.is_dir():
+            for template_file in template_dir.iterdir():
+                template_map[template_file.name] = template_file
+
+        return template_map, template_dict, theme_matches, max_idx
+
+    def get_matching_scripts(
+        self,
+        app_name,
+        scheme='any',
+        style='any',
+    ) -> list[FilePart]:
+        '''
+        Execute matching scripts in the app's ``call/`` directory.
+
+        Scripts need to be placed in
+
+        .. code-block:: sh
+
+            <config_dir>/apps/<app_name>/call/<style>-<scheme>.sh
+
+        and are matched using the same heuristic employed by config file symlinking
+        procedure (see ``get_matching_configs()``), albeit with a forced ``prefix_order``,
+        ordered by increasing specificity. The order is then reversed, and the final list
+        orders the scripts by the first time they appear (intention being to reload
+        specific settings first).
+
+        TODO: consider running just the most specific script? Users might want to design
+        their scripts to be stackable, or they may just be independent.
+        '''
+        app_dir  = Path(self.apps_dir, app_name)
+        call_dir = Path(app_dir, 'call')
+
+        if not call_dir.is_dir():
+            return []
+
+        prefix_order = [
+            ('none', 'none'),
+            ('none', scheme),
+            (style,  'none'),
+            (style,  scheme),
+        ]
+
+        script_matches = self.matcher.match_paths(
+            call_dir.iterdir(),
+            prefix_order=prefix_order
+        )
+        relaxed_matches = self.matcher.relaxed_match(script_matches)
+
+        # flip list to execute by decreasing specificity
+        return relaxed_matches[::-1]
+
+    def update_app_config(
+        self,
+        app_name     : str,
+        app_settings : dict = None,
+        scheme       : str  = 'any',
+        style        : str  = 'any',
+        strict       : bool = False,
+        **kw_groups,
+    ):
+        '''
+        Perform full app config update process, applying symlinks and running scripts.
+
+        Note that this explicitly accepts app settings to override or act in place of
+        missing app details in the app registry file. This is mostly to provide more
+        programmatic control and test settings without needing them present in the
+        registry file. The ``update_apps()`` method, however, **will** more strictly
+        filter out those apps not in the registry, accepting a list of app keys that
+        ultimately call this method.
+
+        Note: symlinks point **from** the target location **to** the known internal config
+        file; can be a little confusing.
+
+        .. admonition:: Logic overview
+
+            This method is the center point of the ConfigManager class. It unifies the
+            user and template matching, file generation, setting of symlinks, and running
+            of scripts. At a high level,
+
+            1. An app name (e.g., kitty), app settings (e.g., a ``config_dir`` or
+               ``config_map``), scheme (e.g., "dark"), and style (e.g., "soft-gruvbox")
+            2. Get matching user config files via ``get_matching_configs()``
+            3. Get matching template config files and the aggregate template dict via
+               ``get_matching_templates()``
+            4. Interleave the two result sets by pathname and match quality. Template
+               matches are preferred in the case of tied scores. This resolves any
+               pathname clashes across matching files.
+
+               This is a particularly important step. It compares concrete config names
+               explicitly provided by the user (e.g., ``soft-gruvbox-dark.kitty.conf``)
+               with named TOML files in a group directory (e.g,.
+               ``theme/soft-gruvbox-dark.toml``). We have to determine whether the
+               available templates constitute a better match than the best user option,
+               which is done by comparing the level in the prefix order (the index)
+               where the match takes place.
+
+               Templates are generally more flexible, and other keywords may also provide
+               a matching template group (e.g., ``-T font=mono`` to match some
+               font-specific settings). When the match is otherwise equally good (e.g.,
+               both style and scheme match directly), we prefer the template due to its
+               general portability and likelihood of being more up-to-date. We also don't
+               explicitly use the fact auxiliary template groups might be matched by the
+               user's input: we only compare the user and template configs on the basis of
+               the quality of the style-scheme match. This effectively means additional
+               template groups (e.g., font) don't "count" if the basis style-scheme
+               doesn't win over a user config file. There could be an arbitrary number of
+               other template group matches, but they don't contribute to the match
+               quality. For instance, a concrete user config ``solarized-dark.kitty.conf``
+               will be selected over ``solarized-none.toml`` plus 10 other matching theme
+               elements if the user asked for ``-s dark -t solarized``.
+            5. For those template matches, fill/generate the template file and place it in
+               the app's ``generated/`` directory.
+
+        Parameters:
+            app_name: name of the app whose config files should be updated
+            app_settings: dict of app settings (i.e., ``config_dir`` or ``config_map``)
+            scheme: scheme spec
+            style: style spec
+            strict: whether to match ``scheme`` and ``style`` strictly 
+        '''
+        if app_settings is None:
+            app_settings = self.app_registry.get(app_name, {})
+
+        if 'config_dir' in app_settings and 'config_map' in app_settings:
+            print(f'App "{app_name}" incorrectly configured, skipping')
+            return
+
+        # match both user configs and templates
+        # -> "*_map" are dicts from config pathnames to FilePart / Paths
+        config_map = self.get_matching_configs(
+            app_name,
+            scheme=scheme,
+            style=style,
+            strict=strict,
+        )
+        template_map, template_dict, theme_matches, tidx = self.get_matching_templates(
+            app_name,
+            scheme=scheme,
+            style=style,
+            **kw_groups
+        )
+
+        # create "generated" directory for the app
+        generated_path = Path(self.apps_dir, app_name, 'generated')
+        generated_path.mkdir(parents=True, exist_ok=True)
+
+        # track selected configs with a pathname -> fullpath map 
+        final_config_map = {}
+        # tracker for template configs that were generated
+        generated_config = []
+
+        # interleave user and template matches
+        for pathname, full_path in template_map.items():
+            if pathname in config_map and config_map[pathname].index > tidx:
+                final_config_map[pathname] = config_map[pathname].path
+            else:
+                config_path = Path(generated_path, pathname)
+                config_path.write_text(
+                    FileTemplate(full_path).fill(template_dict)
+                )
+                final_config_map[pathname] = config_path
+                generated_config.append(pathname)
+
+        # fill in any config matches not added to final_config_map above
+        for pathname, file_part in config_map.items():
+            if pathname not in final_config_map:
+                final_config_map[pathname] = file_part.path
+
+        # prepare symlinks (inverse loop and conditional order is sloppier)
+        to_symlink: list[tuple[Path, Path]] = []
+        if 'config_dir' in app_settings:
+            config_dir = util.absolute_path(app_settings['config_dir'])
+            for ext_pathname, int_fullpath in final_config_map.items():
+                ext_fullpath = Path(config_dir, ext_pathname)
+                to_symlink.append((
+                    ext_fullpath, # point from external config dir
+                    int_fullpath, # to internal config location
+                ))
+        elif 'config_map' in app_settings:
+            for ext_pathname, int_fullpath in final_config_map.items():
+                # app's config map points config pathnames to absolute paths
+                if ext_pathname in app_settings['config_map']:
+                    ext_fullpath = util.absolute_path(app_settings['config_map'][ext_pathname])
+                    to_symlink.append((
+                        ext_fullpath, # point from external config path
+                        int_fullpath, # to internal config location
+                    ))
+
+        # run matching scripts for app-specific reload
+        script_list = self.get_matching_scripts(
+            app_name,
+            scheme=scheme,
+            style=style,
+        )
+        script_list = list(map(lambda f:f.path, script_list))
+
+        # print match messages
+        num_links = len(to_symlink)
+        num_scripts = len(script_list)
+        print(
+            color_text("├─", Fore.BLUE),
+            f'{app_name} :: matched ({num_links}) config files and ({num_scripts}) scripts'
+        )
+
+        rel_theme_matches = ' < '.join([
+            str(fp.path.relative_to(self.group_dir))
+            for fp in theme_matches
+        ])
+        for pathname in generated_config:
+            print(
+                color_text("│", Fore.BLUE),
+                color_text(
+                    f' > generating config "{pathname}" from [{rel_theme_matches}]',
+                    Style.DIM
+                )
+            )
+
+        self._symlink_paths(to_symlink)
+        self.runner.run_many(script_list)
+
+    def configure_apps(
+        self,
+        apps   : str | list[str] = '*',
+        scheme : str             = 'any',
+        style  : str             = 'any',
+        strict : bool            = False,
+        **kw_groups,
+    ):
+        if apps == '*':
+            # get all registered apps
+            app_list = list(self.app_registry.keys())
+        else:
+            # get requested apps that overlap with registry
+            app_list = [a for a in apps if a in self.app_registry]
+
+        if not app_list:
+            print(f'None of the apps "{apps}" are registered, exiting')
+            return
+
+        print(f'> symconf parameters: ')
+        print(f'  > registered apps :: {color_text(app_list, Fore.YELLOW)}')
+        print(f'  > style           :: {color_text(style, Fore.YELLOW)}')
+        print(f'  > scheme          :: {color_text(scheme, Fore.YELLOW)}\n')
+
+        for app_name in app_list:
+            app_dir = Path(self.apps_dir, app_name)
+            if not app_dir.exists():
+                # app has no directory, skip it
+                continue
+
+            self.update_app_config(
+                app_name,
+                app_settings=self.app_registry[app_name],
+                scheme=scheme,
+                style=style,
+                strict=False,
+                **kw_groups,
+            )
+
+    def _app_action(
+        self,
+        script_pathname,
+        apps: str | list[str] = '*',
+    ):
+        '''
+        Execute a static script-based action for a provided set of apps.
+
+        Mostly a helper method for install and update actions, calling a static script
+        name under each app's directory.
+        '''
+        if apps == '*':
+            # get all registered apps
+            app_list = list(self.app_registry.keys())
+        else:
+            # get requested apps that overlap with registry
+            app_list = [a for a in apps if a in self.app_registry]
+
+        if not app_list:
+            print(f'None of the apps "{apps}" are registered, exiting')
+            return
+
+        print(
+            f'> symconf parameters: '
+            f'  > registered apps :: {color_text(app_list, Fore.YELLOW)}'
+        )
+
+        for app_name in app_list:
+            target_script = Path(self.apps_dir, app_name, script_pathname)
+            if not target_script.exists():
+                continue
+
+            self.runner.run_script(target_script)
+
+    def install_apps(
+        self,
+        apps: str | list[str] = '*',
+    ):
+        self._app_action('install.sh', apps)
+
+    def update_apps(
+        self,
+        apps: str | list[str] = '*',
+    ):
+        self._app_action('update.sh', apps)
+
+    def generate_app_templates(
+        self,
+        gen_dir : str | Path,
+        apps    : str | list[str] = '*',
+        scheme : str             = 'any',
+        style  : str             = 'any',
+        **kw_groups,
+    ):
+        if apps == '*':
+            app_list = list(self.app_registry.keys())
+        else:
+            app_list = [a for a in apps if a in self.app_registry]
+
+        if not app_list:
+            print(f'None of the apps "{apps}" are registered, exiting')
+            return
+
+        print(f'> symconf parameters: ')
+        print(f'  > registered apps :: {color_text(app_list, Fore.YELLOW)}')
+        print(f'> Writing templates...')
+
+        gen_dir = util.absolute_path(gen_dir)
+        theme_map = self._prepare_all_templates(scheme, style)
+
+        for app_name in app_list:
+            app_template_dir = Path(self.apps_dir, app_name, 'templates')
+            if not app_template_dir.exists():
+                continue
+
+            app_template_files = list(app_template_dir.iterdir())
+            self.get_matching_templates(
+                app_name,
+                scheme=scheme,
+                style=style,
+                **kw_groups
+            )
+
+            num_temps  = len(app_template_files)
+            num_themes = len(theme_map)
+            print(
+                color_text("├─", Fore.BLUE),
+                f'{app_name} :: generating ({num_temps}) templates from ({num_themes}) themes'
+            )
+
+            for template_file in app_template_files:
+                app_template = FileTemplate(template_file)
+                
+                for theme_stem, theme_dict in theme_map.items():
+                    tgt_template_dir = Path(gen_dir, app_name)
+                    tgt_template_dir.mkdir(parents=True, exist_ok=True)
+
+                    tgt_template_path = Path(
+                        tgt_template_dir,
+                        f'{theme_stem}.{template_file.name}'
+                    )
+                    filled_template = app_template.fill(theme_dict)
+                    tgt_template_path.write_text(filled_template)
+
+                    print(
+                        color_text("│", Fore.BLUE),
+                        f'>  generating "{tgt_template_path.name}"'
+                    )

symconf/matching.py

@@ -0,0 +1,253 @@
+'''
+Generic combinatorial name-matching subsystem
+
+Config files are expected to have names matching the following spec:
+
+.. code-block:: sh
+
+    <style>-<scheme>.<config_pathname>
+
+- ``config_pathname``: refers to a concrete filename, typically that which is expected by
+  the target app (e.g., ``kitty.conf``). In the context of ``config_map`` in the registry,
+  however, it merely serves as an identifier, as it can be mapped onto any path.
+- ``scheme``: indicates the lightness mode ("light" or "dark")
+- ``style``: general identifier capturing the stylizations applied to the config file.
+  This is typically of the form ``<variant>-<palette>``, i.e., including a reference to a
+  particular color palette. 
+
+For example
+
+.. code-block:: sh
+
+    soft-gruvbox-dark.kitty.conf
+
+gets mapped to 
+
+.. code-block:: sh
+
+    style    -> "soft-gruvbox"
+    scheme   -> "dark"
+    pathname -> "kitty.conf"
+'''
+from pathlib import Path
+
+from symconf import util
+
+
+class FilePart:
+    def __init__(self, path: str | Path):
+        self.path = util.absolute_path(path)
+        self.pathname = self.path.name
+
+        parts = str(self.pathname).split('.')
+        if len(parts) < 2:
+            raise ValueError(f'Filename "{pathname}" incorrectly formatted, ignoring')
+
+        self.theme = parts[0]
+        self.conf  = '.'.join(parts[1:])
+
+        theme_split = self.theme.split('-')
+        self.scheme = theme_split[-1]
+        self.style  = '-'.join(theme_split[:-1])
+
+        self.index = -1
+
+    def set_index(self, idx: int):
+        self.index = idx
+
+
+class Matcher:
+    def get_file_parts(
+        self, 
+        paths: list[str | Path],
+    ) -> list[FilePart]:
+        '''
+        Split pathnames into parts for matching.
+
+        Pathnames should be of the format
+
+        .. code-block:: sh
+
+            <style>-<scheme>.<config_pathname>
+
+        where ``style`` is typically itself of the form ``<variant>-<palette>``.
+        '''
+        file_parts = []
+        for path in paths:
+            try:
+                config_file = FilePart(path)
+                file_parts.append(config_file)
+            except ValueError as e:
+                print(f'Filename "{pathname}" incorrectly formatted, ignoring')
+
+        return file_parts
+
+    def prefix_order(
+        self, 
+        scheme,
+        style,
+        strict=False,
+    ) -> list[tuple[str, str]]:
+        '''
+        Determine the order of concrete config pathname parts to match, given the
+        ``scheme`` and ``style`` inputs.
+
+        There is a unique preferred match order when ``style``, ``scheme``, both, or none
+        are ``any``. In general, when ``any`` is provided for a given factor, it is
+        best matched by a config file that expresses indifference under that factor.
+        '''
+        # explicit cases are the most easily managed here, even if a little redundant
+        if strict:
+            theme_order = [
+                (style, scheme),
+            ]
+        else:
+            # inverse order of match relaxation; intention being to overwrite with
+            # results from increasingly relevant groups given the conditions
+            if style == 'any' and scheme == 'any':
+                # prefer both be "none", with preference for specific scheme
+                theme_order = [
+                    (style , scheme),
+                    (style , 'none'),
+                    ('none'  , scheme),
+                    ('none'  , 'none'),
+                ]
+            elif style == 'any':
+                # prefer style to be "none", then specific, then relax specific scheme
+                # to "none"
+                theme_order = [
+                    (style , 'none'),
+                    ('none'  , 'none'),
+                    (style , scheme),
+                    ('none'  , scheme),
+                ]
+            elif scheme == 'any':
+                # prefer scheme to be "none", then specific, then relax specific style
+                # to "none"
+                theme_order = [
+                    ('none'  , scheme),
+                    ('none'  , 'none'),
+                    (style , scheme),
+                    (style , 'none'),
+                ]
+            else:
+                # neither component is any; prefer most specific
+                theme_order = [
+                    ('none'  , 'none'),
+                    ('none'  , scheme),
+                    (style , 'none'),
+                    (style , scheme),
+                ]
+
+        return theme_order
+
+    def match_paths(
+        self, 
+        paths: list[str | Path],
+        prefix_order: list[tuple[str, str]],
+    ) -> list[FilePart]:
+        '''
+        Find and return FilePart matches according to the provided prefix order.
+
+        The prefix order specifies all valid style-scheme combos that can be considered as
+        "consistent" with some user input (and is computed external to this method). For
+        example, it could be
+
+        .. code-block:: python
+
+            [
+                ('none', 'none')
+                ('none', 'dark')
+            ]
+
+        indicating that either ``none-none.<config>`` or ``none-dark.<config>`` would be
+        considered matching pathnames, with the latter being preferred.
+
+        This method exists because we need a way to allow any of the combos in the prefix
+        order to match the candidate files. We don't know a priori how good of a match
+        will be available, so we consider each file for each of the prefixes, and take the
+        latest/best match for each unique config pathname (allowing for a "soft" match).
+        
+        .. admonition:: Checking for matches
+
+            When thinking about how best to structure this method, it initially felt like
+            indexing factors of the FileParts would make the most sense, preventing the
+            inner loop that needs to inspect each FilePart for each element of the prefix
+            order. But indexing the file parts and checking against prefixes isn't so
+            straightforward, as we'd still need to check matches by factor. For instance,
+            if we index by style-scheme, either are allowed to be "any," so we'd need to
+            check for the 4 valid combos and join the matching lists. If we index by both
+            factors individually, we may have several files associated with a given key,
+            and then need to coordinate the checks across both to ensure they belong to
+            the same file.
+
+            In any case, you should be able to do this in a way that's a bit more
+            efficient, but the loop and the simple conditionals is just much simpler to
+            follow. We're also talking about at most 10s of files, so it really doesn't
+            matter.
+
+        Parameters:
+            pathnames:
+            scheme:
+            style:
+            prefix_order:
+            strict:
+        '''
+        file_parts = self.get_file_parts(paths)
+
+        ordered_matches = []
+        for i, (style_prefix, scheme_prefix) in enumerate(prefix_order):
+            for fp in file_parts:
+                style_match  = style_prefix == fp.style or style_prefix == 'any'
+                scheme_match = scheme_prefix == fp.scheme or scheme_prefix == 'any'
+
+                if style_match and scheme_match:
+                    fp.set_index(i+1)
+                    ordered_matches.append(fp)
+
+        return ordered_matches
+
+    def relaxed_match(
+        self,
+        match_list: list[FilePart]
+    ) -> list[FilePart]:
+        '''
+        Isolate the best match in a match list and find its relaxed variants.
+
+        This method allows us to use the ``match_paths()`` method for matching templates
+        rather than direct user config files. In the latter case, we want to symlink the
+        single best config file match for each stem, across all stems with matching
+        prefixes (e.g., ``none-dark.config.a`` and ``solarized-dark.config.b`` have two
+        separate stems with prefixes that could match ``scheme=dark, style=any`` query).
+        We can find these files by just indexing the ``match_path`` outputs (i.e., all
+        matches) by config pathname and taking the one that appears latest (under the
+        prefix order) for each unique value.
+
+        In the template matching case, we want only a single best file match, period
+        (there's really no notion of "config stems," it's just the prefixes). Once that
+        match has been found, we can then "relax" either the scheme or style (or both) to
+        ``none``, and if the corresponding files exist, we use those as parts of the
+        template keys. For example, if we match ``solarized-dark.toml``, we would also
+        consider the values in ``none-dark.toml`` if available. The TOML values that are
+        defined in the most specific (i.e., better under the prefix order) match are
+        loaded "on top of" those less specific matches, overwriting keys when there's a
+        conflict. ``none-dark.toml``, for instance, might define a general dark scheme
+        background color, but a more specific definition in ``solarized-dark.toml`` would
+        take precedent. These TOML files would be stacked before using the resulting
+        dictionary to populate config templates.
+        '''
+        if not match_list:
+            return []
+
+        relaxed_map = {}
+        match = match_list[-1]
+
+        for fp in match_list:
+            style_match  = fp.style  == match.style  or fp.style  == 'none'
+            scheme_match = fp.scheme == match.scheme or fp.scheme == 'none'
+
+            if style_match and scheme_match:
+                relaxed_map[fp.pathname] = fp
+
+        return list(relaxed_map.values())
+

symconf/reader.py

@@ -0,0 +1,97 @@
+'''
+Simplified management for nested dictionaries
+'''
+import copy
+import pprint
+import tomllib
+import hashlib
+from typing import Any
+from pathlib import Path
+
+from symconf.util import deep_update
+
+
+class DictReader:
+    def __init__(self, toml_path=None):
+        self._config = {}
+        self.toml_path = toml_path
+
+        if toml_path is not None:
+            self._config = self._load_toml(toml_path)
+            
+    def __str__(self):
+        return pprint.pformat(self._config, indent=4)
+
+    @staticmethod
+    def _load_toml(toml_path) -> dict[str, Any]:
+        return tomllib.loads(Path(toml_path).read_text())
+
+    @classmethod
+    def from_dict(cls, config_dict):
+        new_instance = cls()
+        new_instance._config = copy.deepcopy(config_dict)
+        return new_instance
+
+    def update(self, config, in_place=False):
+        new_config = deep_update(self._config, config._config)
+
+        if in_place:
+            self._config = new_config
+            return self
+
+        return self.from_dict(new_config)
+
+    def copy(self):
+        return self.from_dict(copy.deepcopy(self._config))
+
+    def get_subconfig(self, key): pass
+
+    def get(self, key, default=None):
+        keys = key.split('.')
+
+        subconfig = self._config
+        for subkey in keys[:-1]:
+            subconfig = subconfig.get(subkey)
+
+            if type(subconfig) is not dict:
+                return default
+
+        return subconfig.get(keys[-1], default)
+
+    def set(self, key, value):
+        keys = key.split('.')
+
+        subconfig = self._config
+        for subkey in keys[:-1]:
+            if subkey in subconfig:
+                subconfig = subconfig[subkey]
+
+                if type(subconfig) is not dict:
+                    logger.debug(
+                        'Attempting to set nested key with an existing non-dict parent'
+                    )
+                    return False
+
+                continue
+
+            subdict = {}
+            subconfig[subkey] = subdict
+            subconfig = subdict
+
+        subconfig.update({ keys[-1]: value })
+        return True
+    
+    def generate_hash(self, exclude_keys=None):
+        inst_copy = self.copy()
+        
+        if exclude_keys is not None:
+            for key in exclude_keys:
+                inst_copy.set(key, None)
+                
+        items = inst_copy._config.items()
+            
+        # create hash from config options
+        config_str = str(sorted(items))
+        return hashlib.md5(config_str.encode()).hexdigest()
+
+

symconf/runner.py

@@ -0,0 +1,64 @@
+'''
+Handle job/script execution
+'''
+import stat
+import subprocess
+from pathlib import Path
+
+from colorama import Fore, Back, Style
+
+from symconf.util import printc, color_text
+
+
+class Runner:
+    def run_script(
+        self,
+        script: str | Path,
+    ):
+        script_path = Path(script)
+
+        if script_path.stat().st_mode & stat.S_IXUSR == 0:
+            print(
+                color_text("│", Fore.BLUE),
+                color_text(
+                    f'   > script "{script_path.name}" missing execute permissions, skipping',
+                    Fore.RED + Style.DIM
+                )
+            )
+            return
+
+        print(
+            color_text("│", Fore.BLUE),
+            color_text(
+                f' > running script "{script_path.name}"',
+                Fore.BLUE
+            )
+        )
+
+        output = subprocess.check_output(str(script_path), shell=True)
+
+        if output:
+            fmt_output = output.decode().strip().replace(
+                '\n',
+                f'\n{Fore.BLUE}{Style.NORMAL}│{Style.DIM}    '
+            )
+            print(
+                color_text("│", Fore.BLUE),
+                color_text(
+                    f'   captured script output "{fmt_output}"',
+                    Fore.BLUE + Style.DIM
+                )
+            )
+
+        return output
+
+    def run_many(
+        self,
+        script_list: list[str | Path],
+    ):
+        outputs = []
+        for script in script_list:
+            output = self.run_script(script)
+            outputs.append(output)
+
+        return outputs

symconf/template.py

@@ -0,0 +1,109 @@
+'''
+Support for basic config templates
+'''
+import re
+import tomllib
+from pathlib import Path
+
+from symconf import util
+from symconf.reader import DictReader
+
+
+class Template:
+    def __init__(
+        self,
+        template_str  : str,
+        key_pattern   : str = r'f{{(\S+?)}}',
+        exe_pattern   : str = r'x{{((?:(?!x{{).)*)}}',
+    ):
+        self.template_str = template_str
+        self.key_pattern  = key_pattern
+        self.exe_pattern  = exe_pattern
+
+    def fill(
+        self,
+        template_dict : dict,
+    ) -> str:
+        dr = DictReader.from_dict(template_dict)
+
+        exe_filled = re.sub(
+            self.exe_pattern,
+            lambda m: self._exe_fill(m, dr),
+            self.template_str
+        )
+
+        key_filled = re.sub(
+            self.key_pattern,
+            lambda m: self._key_fill(m, dr),
+            exe_filled
+        )
+
+        return key_filled
+
+    def _key_fill(
+        self,
+        match,
+        dict_reader: DictReader,
+    ) -> str:
+        key = match.group(1)
+
+        return str(dict_reader.get(key))
+
+    def _exe_fill(
+        self,
+        match,
+        dict_reader: DictReader,
+    ) -> str:
+        key_fill = re.sub(
+            self.key_pattern,
+            lambda m: f'"{self._key_fill(m, dict_reader)}"',
+            match.group(1)
+        )
+
+        return str(eval(key_fill))
+
+class FileTemplate(Template):
+    def __init__(
+        self,
+        path:        Path,
+        key_pattern: str = r'f{{(\S+?)}}',
+        exe_pattern   : str = r'x{{((?:(?!x{{).)*)}}',
+    ):
+        super().__init__(
+            path.open('r').read(),
+            key_pattern=key_pattern,
+            exe_pattern=exe_pattern,
+        )
+
+class TOMLTemplate(FileTemplate):
+    def __init__(
+        self,
+        toml_path:   Path,
+        key_pattern: str = r'f{{(\S+?)}}',
+        exe_pattern   : str = r'x{{((?:(?!x{{).)*)}}',
+    ):
+        super().__init__(
+            toml_path,
+            key_pattern=key_pattern,
+            exe_pattern=exe_pattern,
+        )
+
+    def fill(
+        self,
+        template_dict : dict,
+    ) -> str:
+        filled_template = super().fill(template_dict)
+        toml_dict = tomllib.loads(filled_template)
+
+        return toml_dict
+
+    @staticmethod
+    def stack_toml(
+        path_list: list[Path]
+    ) -> dict:
+        stacked_dict = {}
+        for toml_path in path_list:
+            updated_map = tomllib.load(toml_path.open('rb'))
+            stacked_dict = util.deep_update(stacked_dict, updated_map)
+
+        return stacked_dict

symconf/util.py

@@ -0,0 +1,80 @@
+import re
+import argparse
+from pathlib import Path
+
+from xdg import BaseDirectory
+from colorama import Fore, Back, Style
+from colorama.ansi import AnsiFore, AnsiBack, AnsiStyle
+
+
+def color_text(text, *colorama_args): 
+    '''
+    Colorama text helper function
+
+    Note: we attempt to preserve expected nested behavior by only resetting the groups
+    (Fore, Back, Style) affected the styles passed in. This works when an outer call is
+    changing styles in one group, and an inner call is changing styles in another, but
+    *not* when affected groups overlap.
+
+    For example, if an outer call is setting the foreground color (e.g., ``Fore.GREEN``),
+    nested calls on the text being passed into the function can modify and reset the
+    background or style with affecting the foreground. The primary use case here is
+    styling a group of text a single color, but applying ``BRIGHT`` or ``DIM`` styles only
+    to some text elements within. If we didn't reset by group, the outer coloration
+    request will be "canceled out" as soon as the first inner call is made (since the
+    unconditional behavior just employs ``Style.RESET_ALL``).
+    '''
+    # reverse map colorama Ansi codes
+    resets = []
+    for carg in colorama_args:
+        match = re.match(r'.*\[(\d+)m', carg)
+        if match:
+            intv = int(match.group(1))
+            if (intv >= 30 and intv <= 39) or (intv >= 90 and intv <= 97):
+                resets.append(Fore.RESET)
+            elif (intv >= 40 and intv <= 49) or (intv >= 100 and intv <= 107):
+                resets.append(Back.RESET)
+            elif (intv >= 0 and intv <= 2) or intv == 22:
+                resets.append(Style.NORMAL)
+
+    return f"{''.join(colorama_args)}{text}{''.join(resets)}"
+
+def printc(text, *colorama_args):
+    print(color_text(text, *colorama_args))
+
+def absolute_path(path: str | Path) -> Path:
+    return Path(path).expanduser().absolute()
+    
+def xdg_config_path():
+    return Path(BaseDirectory.save_config_path('symconf'))
+ 
+def to_tilde_path(path: Path) -> Path:
+    '''
+    Abbreviate an absolute path by replacing HOME with "~", if applicable.
+    '''
+    try:
+        return Path(f"~/{path.relative_to(Path.home())}")
+    except ValueError:
+        return path
+
+def deep_update(mapping: dict, *updating_mappings: dict) -> dict:
+    '''Code adapted from pydantic'''
+    updated_mapping = mapping.copy()
+    for updating_mapping in updating_mappings:
+        for k, v in updating_mapping.items():
+            if k in updated_mapping and isinstance(updated_mapping[k], dict) and isinstance(v, dict):
+                updated_mapping[k] = deep_update(updated_mapping[k], v)
+            else:
+                updated_mapping[k] = v
+    return updated_mapping
+
+
+class KVPair(argparse.Action):
+    def __call__(self, parser, namespace, values, option_string=None):
+        kv_dict = getattr(namespace, self.dest, {})
+        if kv_dict is None:
+            kv_dict = {}
+        for value in values:
+            key, val = value.split('=', 1)
+            kv_dict[key] = val
+        setattr(namespace, self.dest, kv_dict)

tests/test-config-dir/app_registry.toml

@@ -0,0 +1,2 @@
+[app.test]
+config_dir = 'sym_tgt/test'

tests/test-config-dir/apps/gnome/call/any-dark.sh

@@ -1 +0,0 @@
-gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'

tests/test-config-dir/apps/gnome/call/any-light.sh

@@ -1 +0,0 @@
-gsettings set org.gnome.desktop.interface color-scheme 'prefer-light'

tests/test-config-dir/apps/kitty/call/any-any.sh

@@ -1 +0,0 @@
-echo "> Testing script"

tests/test-config-dir/apps/test/call/none-light.sh

@@ -0,0 +1 @@
+echo "none-light ran"

tests/test-config-dir/apps/test/call/none-none.sh

@@ -0,0 +1 @@
+echo "none-none ran"

tests/test-config-dir/apps/test/call/test-none.sh

@@ -0,0 +1 @@
+echo "> test-none ran"

tests/test-config-dir/groups/test/none.toml

@@ -0,0 +1 @@
+base = "aaa"

tests/test-config-dir/groups/test/test.toml

@@ -0,0 +1 @@
+concrete = "zzz"

tests/test-config-dir/sym_tgt/aaa

@@ -0,0 +1 @@
+/home/smgr/Documents/projects/olog/symconf/tests/test-config-dir/apps/test/user/none-none.aaa

tests/test-config-dir/sym_tgt/bbb

@@ -0,0 +1 @@
+/home/smgr/Documents/projects/olog/symconf/tests/test-config-dir/apps/test/user/test-dark.bbb

tests/test-config-dir/sym_tgt/ccc

@@ -0,0 +1 @@
+/home/smgr/Documents/projects/olog/symconf/tests/test-config-dir/apps/test/user/test-light.ccc

tests/test-config-dir/sym_tgt/ddd

@@ -0,0 +1 @@
+/home/smgr/Documents/projects/olog/symconf/tests/test-config-dir/apps/test/generated/test-none.ddd

tests/test_imports.py

@@ -1,5 +1,10 @@
 def test_imports():
-    from autoconf import ConfigManager
+    from symconf.runner import Runner
+    from symconf.reader import DictReader
+    from symconf.config import ConfigManager
+    from symconf.matching import Matcher, FilePart
+    from symconf.template import Template, FileTemplate, TOMLTemplate
 
-    from autoconf import config
-    from autoconf import theme
+    from symconf import config
+    from symconf import reader
+    from symconf import util

tests/test_matching.py

@@ -0,0 +1,120 @@
+from pathlib import Path
+
+from symconf import ConfigManager
+
+
+config_dir = Path(
+    __file__, '..', 'test-config-dir/'
+).resolve()
+cm = ConfigManager(config_dir)
+
+
+def test_matching_configs_exact():
+    '''
+    Test matching exact style and scheme. Given strict mode not set (allowing relaxation
+    to "none"), the order of matching should be
+
+    1. (none, none)    :: none-none.aaa
+    2. (none, scheme)  :: none-light.aaa
+    3. (style, none)   :: test-none.aaa
+    4. (style, scheme) :: test-light.ccc
+
+    Yielding "test-light.aaa", "test-light.ccc" (unique only on config pathname).
+    '''
+    any_light = cm.get_matching_configs(
+        'test', 
+        style='test',
+        scheme='light',
+    )
+    print(any_light)
+
+    assert len(any_light) == 2
+    assert any_light['aaa'].pathname == 'test-none.aaa'
+    assert any_light['ccc'].pathname == 'test-light.ccc'
+
+def test_matching_configs_any_style():
+    '''
+    Test matching "any" style and exact scheme. Given strict mode not set (allowing
+    relaxation to "none"), the order of matching should be
+
+    1. (style, none)   :: none-none.aaa, test-none.aaa
+    2. (none, none)    :: none-none.aaa
+    3. (style, scheme) :: test-dark.bbb
+    4. (none, scheme)  :: (nothing)
+
+    Yielding "none-none.aaa" (should always overwrite "test-none.aaa" due to "any"'s
+    preference for non-specific matches, i.e., "none"s), "test-none.ddd", "test-dark.bbb"
+    (unique only on config pathname).
+    '''
+    any_dark = cm.get_matching_configs(
+        'test', 
+        style='any',
+        scheme='dark',
+    )
+
+    assert len(any_dark) == 2
+    assert any_dark['aaa'].pathname == 'none-none.aaa'
+    assert any_dark['bbb'].pathname == 'test-dark.bbb'
+
+def test_matching_configs_any_scheme():
+    '''
+    Test matching exact style and "any" scheme. Given strict mode not set (allowing
+    relaxation to "none"), the order of matching should be
+
+    1. (none, scheme)  :: none-light.aaa & none-none.aaa
+    2. (none, none)    :: none-none.aaa
+    3. (style, scheme) :: test-dark.bbb & test-light.ccc & test-none.aaa
+    4. (style, none)   :: test-none.aaa
+
+    Yielding "test-none.aaa", "test-light.ccc", "test-dark.bbb"
+    '''
+    test_any = cm.get_matching_configs(
+        'test', 
+        style='test',
+        scheme='any',
+    )
+
+    assert len(test_any) == 3
+    assert test_any['aaa'].pathname == 'test-none.aaa'
+    assert test_any['bbb'].pathname == 'test-dark.bbb'
+    assert test_any['ccc'].pathname == 'test-light.ccc'
+
+def test_matching_scripts():
+    '''
+    Test matching exact style and scheme. Given strict mode not set (allowing relaxation
+    to "none"), the order of matching should be
+
+    1. (none, none)    :: none-none.sh
+    2. (none, scheme)  :: none-light.sh
+    3. (style, none)   :: test-none.sh
+    4. (style, scheme) :: (nothing)
+
+    Yielding (ordered by dec specificity) "test-none.sh" as primary match, then relaxation
+    match "none-none.sh".
+    '''
+    test_any = cm.get_matching_scripts(
+        'test', 
+        style='test',
+        scheme='any',
+    )
+
+    assert len(test_any) == 2
+    assert list(map(lambda p:p.pathname, test_any)) == ['test-none.sh', 'none-none.sh']
+
+    any_light = cm.get_matching_scripts(
+        'test', 
+        style='any',
+        scheme='light',
+    )
+
+    assert len(any_light) == 2
+    assert list(map(lambda p:p.pathname, any_light)) == ['none-light.sh', 'none-none.sh']
+
+    any_dark = cm.get_matching_scripts(
+        'test', 
+        style='any',
+        scheme='dark',
+    )
+
+    assert len(any_dark) == 2
+    assert list(map(lambda p:p.pathname, any_dark)) == ['test-none.sh', 'none-none.sh']

tests/test_template.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from symconf import Template, TOMLTemplate
+
+def test_template_fill():
+    # test simple replacment
+    assert Template('f{{a}} - f{{b}}').fill({
+        'a': 1,
+        'b': 2,
+    }) == '1 - 2'
+
+    # test nested brackets (using default pattern)
+    assert Template('{{ f{{a}} - f{{b}} }}').fill({
+        'a': 1,
+        'b': 2,
+    }) == '{{ 1 - 2 }}'
+
+    # test tight nested brackets (requires greedy quantifier)
+    assert Template('{{f{{a}} - f{{b}}}}').fill({
+        'a': 1,
+        'b': 2,
+    }) == '{{1 - 2}}'
+
+def test_toml_template_fill():
+    test_group_dir = Path(
+        __file__, '..', 'test-config-dir/groups/test/'
+    ).resolve()
+
+    stacked_dict = TOMLTemplate.stack_toml(test_group_dir.iterdir())
+
+    assert stacked_dict == {'base':'aaa','concrete':'zzz'}