hueman-cli 0.2.0__py3-none-any.whl

hueman/engine/config.py

@@ -0,0 +1,186 @@
+"""Carga hueman.config.yaml (paths, targets, reload) y monta un logger
+propio — sin depender de ningún gestor de dotfiles externo."""
+
+import logging
+import os
+import re
+from pathlib import Path
+
+import yaml
+
+from .statesource import StateSyncConfigError, parse_settings
+from .targets import FAILURE_POLICIES, load_targets
+
+
+class ConfigError(ValueError):
+    """hueman.config.yaml is unreadable, malformed or has an invalid schema."""
+
+
+VAR_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_VAR_REF_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def substitute_vars(text: str, variables: dict, where: str) -> str:
+    """Replace every exact ``${name}`` in ``text`` with ``variables[name]``.
+
+    A ``$`` not followed by ``{name}`` is left alone. Replacement values are
+    inserted verbatim (no recursion). An unknown name raises ConfigError
+    naming the variable and ``where`` it was used."""
+
+    def repl(match):
+        name = match.group(1)
+        if name not in variables:
+            raise ConfigError(f"variable '${{{name}}}' no definida (usada en {where})")
+        return variables[name]
+
+    return _VAR_REF_RE.sub(repl, text)
+
+
+def _subst_paths(value, variables, where):
+    """Substitute in a str or in each str of a list; other shapes pass through."""
+    if isinstance(value, str):
+        return substitute_vars(value, variables, where)
+    if isinstance(value, list):
+        return [substitute_vars(v, variables, where) if isinstance(v, str) else v for v in value]
+    return value
+
+
+def _validate_vars(path, raw_vars) -> dict:
+    if raw_vars is None:
+        return {}
+    if not isinstance(raw_vars, dict):
+        raise ConfigError(f"{path}: 'vars' debe ser un mapeo nombre -> valor")
+    for name, value in raw_vars.items():
+        if not isinstance(name, str) or not VAR_NAME_RE.fullmatch(name):
+            raise ConfigError(f"{path}: nombre de variable invalido en 'vars': {name!r}")
+        if not isinstance(value, str):
+            raise ConfigError(f"{path}: vars.{name} debe ser un string, no {value!r}")
+        if _VAR_REF_RE.search(value):
+            raise ConfigError(
+                f"{path}: vars.{name} no puede contener ${{...}} (las variables no se anidan)"
+            )
+    return dict(raw_vars)
+
+
+class HuemanConfig:
+    def __init__(self, path: Path, var_overrides: dict = None):
+        self.path = path
+        try:
+            raw = yaml.safe_load(path.read_text()) or {}
+        except yaml.YAMLError as exc:
+            raise ConfigError(f"{path}: YAML invalido: {exc}") from exc
+        if not isinstance(raw, dict):
+            raise ConfigError(f"{path}: se esperaba un mapeo YAML en la raiz")
+        variables = _validate_vars(path, raw.get("vars"))
+        variables.update(_validate_vars(path, var_overrides))
+        try:
+            self.state_file = Path(
+                _subst_paths(raw.get("state_file", "~/.config/hueman/current"), variables, "state_file")
+            ).expanduser()
+            self.palette_dirs = [
+                Path(p).expanduser() for p in _subst_paths(raw.get("palette_dirs", []), variables, "palette_dirs")
+            ]
+            self.template_dirs = [
+                Path(p).expanduser() for p in _subst_paths(raw.get("template_dirs", []), variables, "template_dirs")
+            ]
+            raw_targets = raw.get("targets") or {}
+            if not isinstance(raw_targets, dict) or not all(
+                isinstance(v, dict) for v in raw_targets.values()
+            ):
+                raise ConfigError(f"{path}: 'targets' debe ser un mapeo nombre -> definicion")
+            raw_targets = {
+                name: self._substitute_target(name, cfg, variables) for name, cfg in raw_targets.items()
+            }
+        except ConfigError as exc:
+            if str(exc).startswith(str(path)):
+                raise
+            raise ConfigError(f"{path}: {exc}") from exc
+        try:
+            self.targets = load_targets(raw_targets)
+        except TypeError as exc:
+            raise ConfigError(f"{path}: target invalido: {exc}") from exc
+        self.reload_failure = raw.get("reload_failure", "warn")
+        if self.reload_failure not in FAILURE_POLICIES:
+            raise ConfigError(
+                f"{path}: reload_failure debe ser 'warn' o 'error', no {self.reload_failure!r}"
+            )
+        self.post_apply = self._validate_post_apply(path, raw.get("post_apply"))
+        self.state_sync = self._load_state_sync(path, raw.get("state_sync"))
+        self.logger = self._make_logger(self._validate_logging(path, raw.get("logging")))
+
+    @staticmethod
+    def _substitute_target(name, cfg, variables):
+        out = dict(cfg)
+        for key in ("outputs", "skip_unless_path_exists"):
+            if key in out:
+                out[key] = _subst_paths(out[key], variables, f"targets.{name}.{key}")
+        return out
+
+    @staticmethod
+    def _validate_post_apply(path, raw):
+        if raw is None:
+            return []
+        if not isinstance(raw, list) or not all(isinstance(c, str) for c in raw):
+            raise ConfigError(f"{path}: 'post_apply' debe ser una lista de comandos (strings)")
+        return raw
+
+    @staticmethod
+    def _validate_logging(path, raw) -> dict:
+        """Return a checked copy of the ``logging`` section."""
+        if raw is None:
+            return {}
+        if not isinstance(raw, dict):
+            raise ConfigError(f"{path}: 'logging' debe ser un mapeo (level, file)")
+        level = raw.get("level", "INFO")
+        if not isinstance(level, str) or not isinstance(
+            logging.getLevelName(level.upper()), int
+        ):
+            raise ConfigError(
+                f"{path}: logging.level desconocido: {level!r} "
+                "(usa DEBUG, INFO, WARNING, ERROR o CRITICAL)"
+            )
+        log_file = raw.get("file")
+        if log_file is not None:
+            if not isinstance(log_file, str) or not log_file:
+                raise ConfigError(f"{path}: logging.file debe ser una ruta (string)")
+            parent = Path(log_file).expanduser().parent
+            if not parent.is_dir():
+                raise ConfigError(f"{path}: logging.file: el directorio {parent} no existe")
+            if not os.access(parent, os.W_OK | os.X_OK):
+                raise ConfigError(f"{path}: logging.file: no se puede escribir en {parent}")
+        return {**raw, "level": level.upper()}
+
+    @staticmethod
+    def _load_state_sync(path, raw):
+        if raw is None:
+            return None
+        try:
+            return parse_settings(raw)
+        except StateSyncConfigError as exc:
+            raise ConfigError(f"{path}: {exc}") from exc
+
+    @staticmethod
+    def _make_logger(logging_cfg: dict) -> logging.Logger:
+        logger = logging.getLogger("hueman")
+        logger.setLevel(logging_cfg.get("level", "INFO"))
+        if not logger.handlers:
+            handler = logging.StreamHandler()
+            handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+            logger.addHandler(handler)
+            log_file = logging_cfg.get("file")
+            if log_file:
+                file_handler = logging.FileHandler(Path(log_file).expanduser())
+                file_handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s: %(message)s"))
+                logger.addHandler(file_handler)
+        return logger
+
+    @staticmethod
+    def resolve_path(explicit) -> Path:
+        if explicit:
+            return Path(explicit).expanduser()
+        env_path = os.environ.get("HUEMAN_CONFIG")
+        if env_path:
+            return Path(env_path).expanduser()
+        # el directorio actual NO se busca a proposito: un config puede ejecutar
+        # comandos (post_apply/reload) y no debe cargarse desde un repo ajeno
+        return Path("~/.config/hueman/config.yaml").expanduser()

hueman/engine/fsutil.py

@@ -0,0 +1,41 @@
+"""Atomic file writes: temp file in the same directory + os.replace."""
+
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, content: str, make_executable: bool = False,
+                      encoding: str = "utf-8") -> None:
+    """Write `content` to `path` so readers never see a partial file.
+
+    The data goes to a temp file next to the target and is moved into place
+    with os.replace. An existing file's permission bits are preserved (new
+    files get the umask default); `make_executable` adds the x bits. On any
+    failure the original is untouched and the temp file is removed.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        mode = stat.S_IMODE(path.stat().st_mode)
+    except FileNotFoundError:
+        umask = os.umask(0)
+        os.umask(umask)
+        mode = 0o666 & ~umask
+    if make_executable:
+        mode |= 0o111
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding=encoding) as fh:
+            fh.write(content)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.chmod(tmp_name, mode)
+        os.replace(tmp_name, path)
+    except BaseException:
+        try:
+            os.unlink(tmp_name)
+        except FileNotFoundError:
+            pass
+        raise

hueman/engine/palettes.py

@@ -0,0 +1,66 @@
+"""Carga de paletas YAML: empaquetadas dentro del tool + directorios custom
+del usuario, con precedencia de los custom sobre los empaquetados."""
+
+import re
+from pathlib import Path
+
+import yaml
+
+PALETTE_NAME_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
+
+
+def is_valid_palette_name(name) -> bool:
+    """Nombre seguro: sin separadores de ruta, sin '..', sin espacios ni saltos
+    de linea. El nombre llega a rutas, logs y comandos (y con `sync` lo controla
+    el remoto), asi que se valida antes de tocar el disco."""
+    return (isinstance(name, str) and PALETTE_NAME_RE.fullmatch(name) is not None
+            and ".." not in name)
+
+
+class PaletteLoader:
+    def __init__(self, packaged_dir: Path, custom_dirs: list, logger):
+        self.packaged_dir = packaged_dir
+        self.custom_dirs = custom_dirs
+        self.logger = logger
+
+    def _search_dirs(self):
+        # los custom_dirs (en orden declarado) tienen precedencia sobre lo empaquetado
+        return list(self.custom_dirs) + [self.packaged_dir]
+
+    def list_palettes(self) -> list:
+        found = {}
+        for d in self._search_dirs():
+            if not d.exists():
+                continue
+            for p in d.glob("*.yaml"):
+                if p.stem in found and found[p.stem] != p:
+                    self.logger.warning(
+                        f"Paleta '{p.stem}' definida en más de un directorio, "
+                        f"gana la de mayor precedencia: {found[p.stem]}"
+                    )
+                    continue
+                found.setdefault(p.stem, p)
+        return sorted(found)
+
+    def load(self, name: str) -> dict:
+        if not is_valid_palette_name(name):
+            self.logger.error(
+                f"Nombre de paleta invalido: {name!r} "
+                "(solo letras, digitos, '.', '_' y '-'; debe empezar por letra o digito)"
+            )
+            raise SystemExit(1)
+        for d in self._search_dirs():
+            path = d / f"{name}.yaml"
+            if path.exists():
+                try:
+                    data = yaml.safe_load(path.read_text())
+                except yaml.YAMLError as exc:
+                    self.logger.error(f"Paleta invalida {path}: {exc}")
+                    raise SystemExit(1)
+                if not isinstance(data, dict):
+                    self.logger.error(f"Paleta invalida {path}: se esperaba un mapeo YAML")
+                    raise SystemExit(1)
+                return data
+        available = ", ".join(self.list_palettes())
+        self.logger.error(f"Paleta no encontrada: {name}. Disponibles: {available}")
+        raise SystemExit(1)

hueman/engine/reload.py

@@ -0,0 +1,60 @@
+"""Ejecuta comandos de recarga: uno por target (best-effort, tras escribir
+con éxito) y los `post_apply` globales (una sola vez al final de `set`)."""
+
+import re
+import shlex
+import subprocess
+
+from .render import _dig
+
+# `{name}`, `{palette}` o `{seccion.clave}`; el lookbehind deja intactos
+# `${VAR}` del shell. Llaves simples sin punto (ej. `find -exec {} +`) no
+# matchean salvo `name`/`palette`.
+_PLACEHOLDER = re.compile(r"(?<!\$)\{([A-Za-z_]\w*(?:\.\w+)*)\}")
+
+
+class PlaceholderError(ValueError):
+    """Un `{seccion.clave}` de reload/post_apply no existe en la paleta."""
+
+
+def expand_command(cmd: str, name: str, palette: dict) -> str:
+    """Sustituye `{name}`/`{palette}` y `{a.b}` (lookup en la paleta activa)
+    por su valor con shlex.quote. Un `{a.b}` que no resuelve es un error."""
+    def repl(m):
+        key = m.group(1)
+        if key in ("name", "palette"):
+            return shlex.quote(name)
+        if "." not in key:
+            return m.group(0)
+        try:
+            value = _dig(palette, key)
+        except (KeyError, TypeError):
+            raise PlaceholderError(f"placeholder desconocido {{{key}}} en comando: {cmd}")
+        return shlex.quote(str(value))
+
+    return _PLACEHOLDER.sub(repl, cmd)
+
+
+def _run(label: str, cmd: str, logger) -> int:
+    """Run `cmd` through the shell and log its exit code."""
+    rc = subprocess.run(["sh", "-c", cmd]).returncode
+    logger.info(f"{label}: {cmd} (exit {rc})")
+    return rc
+
+
+def run_reload(cmd: str, logger) -> int:
+    """Run a target reload command; return its exit code (0 if no command)."""
+    if not cmd:
+        return 0
+    return _run("reload", cmd, logger)
+
+
+def run_post_apply(commands: list, logger) -> list:
+    """Run every command (a failure does not stop the rest); return the
+    `(command, exit_code)` pairs of those that exited non-zero."""
+    failed = []
+    for cmd in commands:
+        rc = _run("post_apply", cmd, logger)
+        if rc:
+            failed.append((cmd, rc))
+    return failed

hueman/engine/render.py

@@ -0,0 +1,243 @@
+"""Motor de render genérico: dos modos (overwrite, patch) compartidos por
+TODOS los targets — nada de código Python específico por herramienta."""
+
+import json
+import re
+from pathlib import Path
+
+import jinja2
+import jinja2.sandbox
+
+from .colors import contrast_text, is_dark
+from .fsutil import atomic_write_text
+
+
+class TargetRenderError(Exception):
+    """A target could not be rendered (e.g. the palette lacks a required key)."""
+
+
+def _dig(data: dict, dotted_path: str):
+    cur = data
+    for part in dotted_path.split("."):
+        cur = cur[part]
+    return cur
+
+
+def make_jinja_env(template_dirs: list, packaged_dir: Path, delimiters=None) -> jinja2.sandbox.SandboxedEnvironment:
+    """Entorno Jinja en sandbox: una plantilla ajena no alcanza internals de
+    Python (`__class__`, `__globals__`...).
+
+    ChoiceLoader: los template_dirs custom del usuario se resuelven ANTES
+    que los empaquetados — así un target idiosincrático puede referenciar un
+    template por nombre igual que uno genérico."""
+    loader = jinja2.ChoiceLoader([
+        jinja2.FileSystemLoader([str(d) for d in template_dirs]),
+        jinja2.FileSystemLoader(str(packaged_dir)),
+    ])
+    kwargs = {"loader": loader, "keep_trailing_newline": True}
+    if delimiters:
+        kwargs["variable_start_string"], kwargs["variable_end_string"] = delimiters
+    env = jinja2.sandbox.SandboxedEnvironment(**kwargs)
+    env.filters["contrast"] = contrast_text
+    env.filters["is_dark"] = is_dark
+    return env
+
+
+def build_context(target, name: str, palette: dict) -> dict:
+    context = {"theme_name": name}
+    if target.palette_key and target.palette_key in palette:
+        context.update(palette[target.palette_key])
+    for key, dotted_path in target.extra_vars.items():
+        try:
+            context[key] = _dig(palette, dotted_path)
+        except (KeyError, TypeError):
+            raise KeyError(dotted_path) from None
+    return context
+
+
+def render_template(env: jinja2.Environment, target, name: str, palette: dict) -> str:
+    context = build_context(target, name, palette)
+    return env.get_template(target.template).render(**context)
+
+
+def _write(path: Path, content: str, dry_run: bool, logger, make_executable: bool = False):
+    if dry_run:
+        print(f"[DRY RUN] escribiría {path}")
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(path, content, make_executable)
+    logger.info(f"Generado: {path}")
+
+
+def _missing_palette_section(target, palette, logger) -> bool:
+    """True (con log INFO) si el target apunta a una seccion que la paleta no tiene."""
+    if target.palette_key and target.palette_key not in palette:
+        logger.info(f"{target.name}: la paleta no tiene la seccion '{target.palette_key}', omitido")
+        return True
+    return False
+
+
+def render_overwrite(env, target, name, palette, dry_run, logger) -> bool:
+    if _missing_palette_section(target, palette, logger):
+        return False
+    content = render_template(env, target, name, palette)
+    wrote = False
+    for out in target.outputs:
+        if target.skip_if_missing_parent and not out.parent.exists():
+            logger.info(f"{target.name}: {out.parent} no existe, omitido")
+            continue
+        _write(out, content, dry_run, logger, target.make_executable)
+        wrote = True
+    return wrote
+
+
+def _apply_regex_splice(original: str, rendered: str, patch, logger) -> str:
+    if patch.marker_regex:
+        # Bloque delimitado por un único regex (ej. una sección TOML entera).
+        block = rendered
+        pattern = re.compile(patch.marker_regex, re.DOTALL)
+        inserted = not pattern.search(original)
+        if not inserted:
+            content = pattern.sub(lambda m: block, original, count=1)
+        elif patch.insert_after_section_regex:
+            section = re.search(patch.insert_after_section_regex, original, re.DOTALL)
+            if section:
+                insert_at = section.end()
+                content = original[:insert_at] + "\n" + block + original[insert_at:]
+            else:
+                content = original.rstrip("\n") + "\n\n" + block
+        else:
+            content = original.rstrip("\n") + "\n\n" + block
+        # Si el regex no reconoce el bloque recién insertado, se duplicará.
+        if inserted and not pattern.search(content):
+            logger.warning(
+                "marker_regex no reconoce el bloque insertado; "
+                "se volvera a insertar en la siguiente ejecucion"
+            )
+    else:
+        # Marcadores begin/end literales envolviendo el contenido renderizado.
+        marker_begin = patch.marker_begin
+        marker_end = patch.marker_end
+        if patch.marker_end_regex:
+            end_pattern = patch.marker_end_regex
+        else:
+            # Consume the newline after END: full_block re-adds it.
+            end_pattern = re.escape(marker_end) + r"\n?"
+        pattern = re.compile(re.escape(marker_begin) + r".*?" + end_pattern, re.DOTALL)
+        if marker_end and not patch.marker_end_regex:
+            full_block = f"{marker_begin}\n{rendered}{marker_end}\n"
+        else:
+            full_block = f"{marker_begin}\n{rendered}"
+        if pattern.search(original):
+            content = pattern.sub(lambda m: full_block, original, count=1)
+        else:
+            content = original.rstrip("\n") + "\n\n" + full_block
+
+    for old, new in patch.replacements:
+        content = content.replace(old, new)
+    for rule in patch.ensure_after:
+        if not re.search(rule["if_missing_regex"], content):
+            content = content.replace(rule["anchor"], rule["anchor"] + rule["insert"], 1)
+    return content
+
+
+def _apply_json_scheme_upsert(original: str, kitty: dict, scheme_name: str) -> str:
+    data = json.loads(original)
+    scheme = {
+        "name": scheme_name,
+        "background": kitty["background"],
+        "foreground": kitty["foreground"],
+        "black": kitty["color0"],
+        "red": kitty["color1"],
+        "green": kitty["color2"],
+        "yellow": kitty["color3"],
+        "blue": kitty["color4"],
+        "purple": kitty["color5"],
+        "cyan": kitty["color6"],
+        "white": kitty["color7"],
+        "brightBlack": kitty["color8"],
+        "brightRed": kitty["color9"],
+        "brightGreen": kitty["color10"],
+        "brightYellow": kitty["color11"],
+        "brightBlue": kitty["color12"],
+        "brightPurple": kitty["color13"],
+        "brightCyan": kitty["color14"],
+        "brightWhite": kitty["color15"],
+        "cursorColor": kitty["cursor"],
+        "selectionBackground": kitty["selection_background"],
+    }
+    schemes = data.setdefault("schemes", [])
+    for i, s in enumerate(schemes):
+        if s.get("name") == scheme_name:
+            schemes[i] = scheme
+            break
+    else:
+        schemes.append(scheme)
+    return json.dumps(data, indent=4, ensure_ascii=False) + "\n"
+
+
+def render_patch(env, target, name, palette, dry_run, logger) -> bool:
+    patch = target.patch
+    if _missing_palette_section(target, palette, logger):
+        return False
+
+    if patch.strategy == "json_scheme_upsert":
+        section = palette[patch.palette_section]
+        scheme_name = patch.scheme_name or "Dotfiles"
+        wrote = False
+        for out in target.outputs:
+            if not out.exists():
+                logger.info(f"{target.name}: {out} no encontrado, omitido")
+                continue
+            original = out.read_text(encoding="utf-8")
+            try:
+                content = _apply_json_scheme_upsert(original, section, scheme_name)
+            except json.JSONDecodeError as exc:
+                raise TargetRenderError(f"{target.name}: {out} no es JSON valido ({exc})") from exc
+            wrote = True
+            if dry_run:
+                print(f"[DRY RUN] escribiría {out} (scheme '{scheme_name}')")
+                continue
+            atomic_write_text(out, content)
+            logger.info(f"{target.name}: scheme '{scheme_name}' actualizado en {out}")
+        return wrote
+
+    # regex_splice
+    rendered = render_template(env, target, name, palette) if target.template else ""
+    wrote = False
+    for out in target.outputs:
+        if target.skip_if_missing_parent and not out.parent.exists():
+            logger.info(f"{target.name}: {out.parent} no existe, omitido")
+            continue
+        if not out.exists():
+            logger.info(f"{target.name}: {out} no encontrado, omitido")
+            continue
+        original = out.read_text()
+        content = _apply_regex_splice(original, rendered, patch, logger)
+        _write(out, content, dry_run, logger, target.make_executable)
+        wrote = True
+    return wrote
+
+
+def render_target(env, target, name, palette, dry_run, logger) -> bool:
+    missing = [p for p in target.skip_unless_path_exists if not p.exists()]
+    if missing:
+        logger.info(f"{target.name}: {missing[0]} no existe, target omitido")
+        return False
+    try:
+        if target.mode == "overwrite":
+            return render_overwrite(env, target, name, palette, dry_run, logger)
+        return render_patch(env, target, name, palette, dry_run, logger)
+    except jinja2.TemplateNotFound as exc:
+        raise TargetRenderError(f"{target.name}: plantilla {exc.name!r} no encontrada") from exc
+    except jinja2.exceptions.SecurityError as exc:
+        raise TargetRenderError(
+            f"{target.name}: la plantilla intento una operacion no permitida en el sandbox ({exc})"
+        ) from exc
+    except OSError as exc:
+        raise TargetRenderError(f"{target.name}: error de E/S ({exc})") from exc
+    except (KeyError, TypeError) as exc:
+        key = exc.args[0] if exc.args else exc
+        raise TargetRenderError(
+            f"{target.name}: la paleta '{name}' no tiene la clave {key!r} requerida"
+        ) from exc