hueman-cli 0.2.0__py3-none-any.whl

hueman/__init__.py

@@ -0,0 +1,11 @@
+"""hueman: gestor centralizado de temas basado en paletas YAML y plantillas Jinja2."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Nombre de la distribución en PyPI (único lugar a cambiar junto con pyproject.toml).
+    __version__ = version("hueman-cli")
+except PackageNotFoundError:  # checkout sin instalar
+    __version__ = "0+unknown"
+
+__all__ = ["__version__"]

hueman/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

hueman/cli.py

@@ -0,0 +1,353 @@
+"""Gestor centralizado de temas (standalone): una paleta por nombre en
+palettes/*.yaml (empaquetadas o custom) alimenta templates Jinja2 que
+generan la config real de cada herramienta declarada en un
+hueman.config.yaml propio del usuario. No depende de ningún gestor de
+dotfiles externo — todo el mapeo de rutas es explícito en ese config.
+"""
+
+import argparse
+import fnmatch
+import logging
+import sys
+from pathlib import Path
+
+from . import __version__
+from .engine.config import VAR_NAME_RE, ConfigError, HuemanConfig
+from .engine.fsutil import atomic_write_text
+from .engine.palettes import PaletteLoader
+from .engine.reload import PlaceholderError, expand_command, run_post_apply, run_reload
+from .engine.statesource import ReadResult, State, build_source
+from .engine.render import TargetRenderError, make_jinja_env, render_target
+from .resources import packaged_example_config, packaged_palettes_dir, packaged_templates_dir
+
+
+class UnknownTargetError(ValueError):
+    """Un patron de --only no coincide con ningun target."""
+
+
+class Hueman:
+    def __init__(self, config: HuemanConfig):
+        self.config = config
+        self.palettes = PaletteLoader(packaged_palettes_dir(), config.palette_dirs, config.logger)
+        self._jinja_envs = {}
+
+    def _jinja_env(self, delimiters):
+        key = delimiters or ()
+        if key not in self._jinja_envs:
+            self._jinja_envs[key] = make_jinja_env(
+                self.config.template_dirs, packaged_templates_dir(), delimiters
+            )
+        return self._jinja_envs[key]
+
+    def list_palettes(self) -> list:
+        return self.palettes.list_palettes()
+
+    def current_theme(self):
+        return self.config.state_file.read_text().strip() if self.config.state_file.exists() else None
+
+    def _select_targets(self, only):
+        targets = self.config.targets
+        if not only:
+            return targets
+        names = [t.name for t in targets]
+        missing = [p for p in only if not fnmatch.filter(names, p)]
+        if missing:
+            raise UnknownTargetError(
+                f"--only sin coincidencias: {', '.join(missing)}. "
+                f"Targets validos: {', '.join(names)}"
+            )
+        return [t for t in targets if any(fnmatch.fnmatchcase(t.name, p) for p in only)]
+
+    def set_theme(self, name: str, dry_run: bool = False, only=None, publish: bool = True) -> list:
+        """Con `only` (patrones fnmatch) se renderizan solo los targets que
+        coinciden y se dispara solo su reload; NO se escribe el state file ni
+        corre post_apply (es una re-renderizacion parcial, no un cambio de tema).
+
+        Un target cuyo render falla por una clave ausente en la paleta se
+        omite con un warning y el resto continua; devuelve los nombres de los
+        targets fallidos (el CLI sale con codigo 1 si hay alguno).
+
+        `publish=False` (usado por `sync`) aplica sin publicar estado nuevo."""
+        selected = self._select_targets(only)
+        palette = self.palettes.load(name)
+        # Validar placeholders de reload/post_apply antes de escribir nada.
+        for target in selected:
+            if target.reload:
+                expand_command(target.reload, name, palette)
+        post_apply = None
+        if not only:
+            post_apply = [expand_command(c, name, palette) for c in self.config.post_apply]
+        failed = []
+        for target in selected:
+            env = self._jinja_env(target.jinja_delimiters)
+            try:
+                wrote = render_target(env, target, name, palette, dry_run, self.config.logger)
+            except TargetRenderError as exc:
+                self.config.logger.warning(f"{exc}; target omitido")
+                failed.append(target.name)
+                continue
+            if not dry_run and wrote and target.reload:
+                cmd = expand_command(target.reload, name, palette)
+                rc = run_reload(cmd, self.config.logger)
+                if rc:
+                    policy = target.reload_failure or self.config.reload_failure
+                    self.config.logger.log(
+                        logging.ERROR if policy == "error" else logging.WARNING,
+                        f"{target.name}: reload fallo (exit {rc}): {cmd}",
+                    )
+                    if policy == "error":
+                        failed.append(target.name)
+
+        if only:
+            return failed
+
+        if dry_run:
+            for cmd in post_apply:
+                print(f"[DRY RUN] post_apply: {cmd}")
+            return failed
+
+        self.config.state_file.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(self.config.state_file, name + "\n")
+        self.config.logger.info(f"Tema activo: {name}")
+        post_failed = run_post_apply(post_apply, self.config.logger) or []
+        for cmd, rc in post_failed:
+            error = self.config.reload_failure == "error"
+            self.config.logger.log(
+                logging.ERROR if error else logging.WARNING,
+                f"post_apply fallo (exit {rc}): {cmd}",
+            )
+        if post_failed and self.config.reload_failure == "error":
+            failed.append("post_apply")
+        if publish:
+            self._publish_state(name)
+        return failed
+
+    @property
+    def revision_file(self) -> Path:
+        return self.config.state_file.with_name(self.config.state_file.name + ".revision")
+
+    def local_revision(self):
+        """Revision of the shared state this node last applied or published.
+
+        Kept beside the plain state file (which only holds the palette name)
+        so the legacy format is untouched. None when absent or unreadable."""
+        try:
+            value = int(self.revision_file.read_text().strip())
+        except (OSError, ValueError):
+            return None
+        return value if value >= 0 else None
+
+    def _save_revision(self, revision: int) -> None:
+        atomic_write_text(self.revision_file, f"{revision}\n")
+
+    def _publish_state(self, name: str) -> None:
+        """Best-effort: share the active palette; never raises or fails `set`."""
+        settings = self.config.state_sync
+        if settings is None:
+            return
+        try:
+            source = build_source(settings, self.config.logger)
+            current = source.read()
+            base = max(current.revision if current else 0, self.local_revision() or 0)
+            revision = base + 1
+            if source.write(State(name, revision)):
+                self._save_revision(revision)
+            else:
+                self.config.logger.warning("estado compartido no publicado; paleta aplicada solo en local")
+        except Exception as exc:  # noqa: BLE001 - sync must never break `set`
+            self.config.logger.warning(f"estado compartido no publicado: {exc}")
+
+    def sync(self):
+        """Pull the shared state and apply it only if its revision is newer.
+
+        Returns (exit_code, outcome). Safe for shell startup: no change means
+        no writes and no reload; an unreachable remote is not an error (exit 0)
+        and cached data is never applied."""
+        settings = self.config.state_sync
+        if settings is None:
+            self.config.logger.warning("sync: 'state_sync' no configurado; nada que hacer")
+            return 0, "disabled"
+        try:
+            res = build_source(settings, self.config.logger).read_result()
+        except Exception as exc:  # noqa: BLE001 - sync must not crash shell startup
+            self.config.logger.warning(f"sync: estado compartido ilegible: {exc}")
+            return 0, "unreachable"
+        if not res.remote:
+            return 0, "unreachable"
+        remote = res.state
+        if remote is None:
+            return 0, "no-remote-state"
+        local = self.local_revision() or 0
+        if remote.revision == local:
+            return 0, "in-sync"
+        if remote.revision < local:
+            return 0, "ahead"
+        self.config.logger.info(f"sync: r{local} -> r{remote.revision} ({remote.palette})")
+        try:
+            failed = self.set_theme(remote.palette, publish=False)
+        except PlaceholderError as e:
+            # set_theme valida antes de escribir: no hay nada aplicado ni revision que guardar
+            print(f"Config invalida: {e}", file=sys.stderr)
+            return 1, "failed"
+        except SystemExit:
+            # load() ya logueo el motivo; la paleta remota no existe aqui (o es invalida).
+            # Sync no debe matar el arranque del shell ni avanzar la revision.
+            self.config.logger.warning(
+                f"sync: la paleta remota '{remote.palette}' no esta disponible localmente; "
+                "se omite")
+            return 0, "unknown-palette"
+        if failed:
+            print(f"Targets con errores: {', '.join(failed)}", file=sys.stderr)
+            return 1, "failed"
+        self._save_revision(remote.revision)
+        return 0, "applied"
+
+    def _drift_lines(self):
+        settings = self.config.state_sync
+        local = self.local_revision()
+        lines = [f"Revision local: {'r%d' % local if local is not None else '(ninguna)'}"]
+        try:
+            res = build_source(settings, self.config.logger).read_result()
+        except Exception:  # noqa: BLE001
+            res = ReadResult(None, False)
+        remote = res.state
+        if remote is None:
+            lines.append("Revision remota: (desconocida)" if not res.remote else "Revision remota: (vacia)")
+        else:
+            origin = "remote" if res.remote else "local cache - remote unreachable"
+            lines.append(f"Revision remota: r{remote.revision} ({origin}, paleta {remote.palette})")
+        if not res.remote:
+            drift = "remote unreachable"
+        elif remote is None:
+            drift = "no remote state"
+        elif (local or 0) < remote.revision:
+            drift = "behind"
+        elif (local or 0) > remote.revision:
+            drift = "ahead"
+        else:
+            drift = "in sync"
+        lines.append(f"Drift: {drift}")
+        return lines
+
+    def status(self) -> None:
+        print(f"Tema activo: {self.current_theme() or '(ninguno)'}")
+        if self.config.state_sync is not None:
+            print("\n".join(self._drift_lines()))
+        print(f"Paletas disponibles: {', '.join(self.list_palettes())}")
+        total = sum(len(t.outputs) for t in self.config.targets)
+        existing = sum(1 for t in self.config.targets for o in t.outputs if o.exists())
+        print(f"Targets configurados: {len(self.config.targets)} ({existing}/{total} outputs existentes en disco)")
+
+
+DOCS_URL = "https://hueman.cuevaneander.tech"
+
+
+def init_config(path: Path, force: bool) -> int:
+    """Copy the packaged example config to `path`; returns the exit code."""
+    if path.exists() and not force:
+        print(f"Ya existe: {path} (usa --force para sobrescribir)", file=sys.stderr)
+        return 1
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(path, packaged_example_config().read_text())
+    except OSError as exc:
+        print(f"No se pudo escribir {path}: {exc}", file=sys.stderr)
+        return 1
+    print(f"Config de ejemplo escrito en {path}")
+    return 0
+
+
+def _var_arg(text: str):
+    """argparse type for --var NAME=VALUE; returns (name, value)."""
+    name, sep, value = text.partition("=")
+    if not sep or not VAR_NAME_RE.fullmatch(name):
+        raise argparse.ArgumentTypeError(
+            f"invalid form {text!r}: expected NAME=VALUE with NAME matching [A-Za-z_][A-Za-z0-9_]*"
+        )
+    return name, value
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Gestor centralizado de temas (standalone)")
+    parser.add_argument("--version", action="version", version=f"hueman {__version__}")
+    parser.add_argument("--config", help="Ruta al config (por defecto: $HUEMAN_CONFIG o ~/.config/hueman/config.yaml)")
+    parser.add_argument(
+        "--var", action="append", type=_var_arg, default=[], metavar="NAME=VALUE",
+        help="Define o sobreescribe una variable de 'vars:' para ${NAME} en las rutas "
+        "del config (repetible).",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    set_p = sub.add_parser("set", help="Aplicar un tema")
+    set_p.add_argument("name")
+    set_p.add_argument("--dry-run", action="store_true")
+    set_p.add_argument(
+        "--only", action="append", metavar="NAME[,NAME...]",
+        help="Limitar a targets por nombre o glob (repetible). No actualiza "
+        "el state file ni corre post_apply.",
+    )
+
+    sync_p = sub.add_parser(
+        "sync", help="Aplicar el estado compartido si es mas nuevo (seguro en el arranque del shell)")
+    sync_p.add_argument("-q", "--quiet", action="store_true",
+                        help="Solo errores reales (sin avisos de red o config)")
+
+    init_p = sub.add_parser(
+        "init", help="Escribir un config de ejemplo en la ruta de config por defecto")
+    init_p.add_argument("--force", action="store_true",
+                        help="Sobrescribir el config si ya existe")
+
+    sub.add_parser("list", help="Listar paletas disponibles")
+    sub.add_parser("status", help="Mostrar tema activo y estado de los targets")
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        return
+
+    config_path = HuemanConfig.resolve_path(args.config)
+    if args.command == "init":
+        sys.exit(init_config(config_path, args.force))
+    if not config_path.exists():
+        if args.command == "list":
+            # Las paletas empaquetadas no dependen del config del usuario.
+            loader = PaletteLoader(packaged_palettes_dir(), [], logging.getLogger("hueman"))
+            print("\n".join(loader.list_palettes()))
+            return
+        print(
+            f"Config no encontrada: {config_path}\n"
+            f"Crea uno con `hueman init`, o usa --config / HUEMAN_CONFIG (docs: {DOCS_URL})",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    try:
+        tc = Hueman(HuemanConfig(config_path, dict(args.var)))
+    except ConfigError as e:
+        print(f"Config invalida: {e}", file=sys.stderr)
+        sys.exit(1)
+    if args.command == "set":
+        only = [p.strip() for v in args.only or [] for p in v.split(",") if p.strip()] or None
+        try:
+            failed = tc.set_theme(args.name, args.dry_run, only=only)
+        except UnknownTargetError as e:
+            print(str(e), file=sys.stderr)
+            sys.exit(1)
+        except PlaceholderError as e:
+            print(f"Config invalida: {e}", file=sys.stderr)
+            sys.exit(1)
+        if failed:
+            print(f"Targets con errores: {', '.join(failed)}", file=sys.stderr)
+            sys.exit(1)
+    elif args.command == "sync":
+        if args.quiet:
+            tc.config.logger.setLevel(logging.ERROR)
+        sys.exit(tc.sync()[0])
+    elif args.command == "list":
+        print("\n".join(tc.list_palettes()))
+    elif args.command == "status":
+        tc.status()
+
+
+if __name__ == "__main__":
+    main()

hueman/data/hueman.config.example.yaml

@@ -0,0 +1,111 @@
+# Ejemplo mínimo de configuración de hueman.
+#
+# Este archivo NO vive dentro de hueman/ — cada usuario/máquina trae el
+# suyo (por convención, junto al repo de dotfiles que va a themear, ej.
+# "~/dotfiles/theme/hueman.config.yaml"), y se lo pasa a la herramienta
+# con `hueman --config <ruta>` (o vía la variable HUEMAN_CONFIG, o
+# dejándolo en ~/.config/hueman/config.yaml).
+#
+# No hay concepto de "entorno" ni convención de carpetas: cada target
+# declara su lista explícita de archivos de salida (`outputs`). Si hay
+# varias máquinas/perfiles que comparten el mismo tema, basta con listar
+# todas las rutas ahí.
+
+# Opcional: variables para no repetir rutas. `${repo}` se sustituye solo en
+# `outputs` y `skip_unless_path_exists` de cada target, y en `state_file`,
+# `palette_dirs` y `template_dirs` (nunca en reload, post_apply, patch ni
+# templates). Se pueden sobreescribir con `hueman --var repo=<ruta> ...`.
+# vars:
+#   repo: "~/dotfiles"
+# Uso: outputs: ["${repo}/kitty/theme.conf"]
+
+# Dónde persistir el nombre de la paleta activa.
+state_file: "~/.config/hueman/current"
+
+# Paletas propias, además de las 25 empaquetadas dentro de hueman/palettes/.
+# Si una paleta custom tiene el mismo nombre que una empaquetada, gana la custom.
+palette_dirs:
+  - "~/dotfiles/theme/palettes.custom"
+
+# Templates propios, para targets que la herramienta no trae por defecto.
+template_dirs:
+  - "~/dotfiles/theme/templates.custom"
+
+# Politica cuando un comando `reload` o `post_apply` termina con codigo != 0:
+#   warn  (default) - se registra un warning y `set` sigue; exit 0.
+#   error           - se registra un error, se siguen ejecutando los demas
+#                     pasos (best-effort) y `set` termina con exit 1.
+# Cada target puede sobreescribirla con su propio `reload_failure`.
+# El codigo de salida de cada comando siempre se registra en el log.
+reload_failure: warn
+
+# Opcional (opt-in): publica la paleta activa en la rama huerfana `hueman-state`
+# del remoto de tu repo de dotfiles ({palette, revision} en hueman.state.yaml,
+# un unico commit reescrito con force-with-lease). hueman usa un repo propio
+# (por defecto bajo $XDG_STATE_HOME/hueman/state-sync/) y nunca toca tu working
+# tree. Sin remoto, sin red o sin git, `set` aplica en local y avisa.
+# `set --dry-run` y `set --only` nunca escriben ni empujan estado.
+# state_sync:
+#   type: git                 # git (default) | file
+#   repo: "~/dotfiles"        # repo del que se toma la URL del remoto
+#   remote: origin            # default
+#   branch: hueman-state      # default
+#   # workdir: "~/.local/state/hueman/state-sync/x.git"   # opcional
+#   # timeout: 15            # segundos por llamada git (default 15)
+#
+# Alternativa sin git: un archivo de estado en una carpeta que ya sincroniza
+# otra herramienta (Syncthing, Dropbox...). Escritura atomica; gana la mayor
+# revision. Si la carpeta no existe se considera inalcanzable (no se crea).
+# state_sync:
+#   type: file
+#   path: "~/Sync/hueman.state.yaml"
+
+targets:
+  # --- Ejemplo "overwrite": reemplaza el archivo entero.
+  kitty:
+    template: kitty.conf.j2
+    palette_key: kitty
+    mode: overwrite
+    outputs:
+      - "~/.config/kitty/theme.conf"
+    reload: "pgrep -x kitty >/dev/null 2>&1 && pkill -USR1 -x kitty || true"
+    # reload_failure: error   # override opcional de la politica global
+
+  # --- Ejemplo "patch": splice regex sobre un archivo ya existente, sin
+  # tocar el resto de su contenido (útil para configs escritas a mano,
+  # como el prompt de starship).
+  starship:
+    template: starship_block.toml.j2
+    palette_key: polybar
+    mode: patch
+    patch:
+      marker_regex: '# --- Bloque gestionado por (?:theme_manager\.py|hueman).*?\[palettes\.dotfiles\][^\[]*'
+      replacements:
+        - ['style = "bold green"', 'style = "bold success"']
+      ensure_after:
+        - if_missing_regex: '(?m)^palette\s*='
+          anchor: "add_newline = false\n"
+          insert: "palette = \"dotfiles\"\n"
+    outputs:
+      - "~/.config/starship.toml"
+
+  # --- Ejemplo de guardas opcionales: `skip_if_missing_parent` omite una
+  # salida cuyo directorio padre no existe; `skip_unless_path_exists` (ruta o
+  # lista) omite TODO el target (sin escribir ni reload) salvo que existan
+  # todas esas rutas, util para "solo si esta instalada la herramienta X".
+  # windhawk_taskbar:
+  #   template: windhawk_taskbar.json.j2
+  #   palette_key: polybar
+  #   skip_if_missing_parent: true
+  #   skip_unless_path_exists: "/mnt/c/Windows/System32/schtasks.exe"
+  #   outputs: ["/mnt/c/Users/ME/AppData/Local/DotfilesTheme/taskbar-colors.json"]
+
+# Comandos que corren una sola vez al final de `set`, no por target.
+# No corren cuando se usa `set --only ...` (re-render parcial).
+# Los comandos de `reload` y `post_apply` admiten placeholders: `{name}`
+# (o `{palette}`) y `{seccion.clave}` (lookup en la paleta activa, ej.
+# `{kitty.color4}`); se sustituyen ya shell-quoted. `${VAR}` no se toca y
+# una clave con punto inexistente es un error.
+post_apply:
+  # - "python3 ~/x.py --name {name} --color {kitty.color4}"
+  - "command -v oh-my-posh >/dev/null 2>&1 && oh-my-posh enable reload || true"

hueman/engine/colors.py

@@ -0,0 +1,30 @@
+"""Helpers de color: contraste WCAG y clasificación oscuro/claro.
+
+Genéricos por diseño — no dependen de ningún target ni paleta en particular,
+se exponen como filtros Jinja (`contrast`, `is_dark`) a todos los templates.
+"""
+
+
+def _relative_luminance(hex_color: str) -> float:
+    hex_color = hex_color.lstrip("#")
+    r, g, b = (int(hex_color[i:i + 2], 16) for i in (0, 2, 4))
+
+    def lin(c):
+        c /= 255
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b)
+
+
+def contrast_text(hex_color: str) -> str:
+    """Devuelve texto casi-negro o casi-blanco según la luminancia relativa
+    (WCAG) del color de fondo dado, para que el contraste siempre sea legible
+    sin importar qué tan clara/oscura sea la paleta del tema."""
+    return "#1a1a1a" if _relative_luminance(hex_color) > 0.45 else "#f5f5f5"
+
+
+def is_dark(hex_color: str) -> bool:
+    """Mismo criterio de luminancia que contrast_text(), pero como booleano —
+    para declarar `dark:` en temas que lo necesiten (ej. posting), ya que hay
+    paletas claras (catppuccin-latte, one-light, etc.) además de las oscuras."""
+    return _relative_luminance(hex_color) <= 0.45