dazzlecmd-lib 0.8.55__py3-none-any.whl

dazzlecmd_lib/cli_helpers.py

@@ -0,0 +1,180 @@
+"""CLI scaffolding helpers for aggregator authors.
+
+These are low-level argparse helpers shared across the library's default
+meta-commands and available to downstream aggregators that bypass the
+``MetaCommandRegistry`` (via the ``parser_builder=`` escape hatch).
+
+**When to use**: if you're writing your own ``parser_builder`` callback
+instead of using the registry, import these helpers to avoid duplicating
+the standard subparser-scaffolding boilerplate.
+
+**When NOT to use**: if you're using the registry (the default /
+recommended path), don't call these directly — the registry's
+``build_parsers()`` takes care of parser construction via the
+registered factories.
+"""
+
+from __future__ import annotations
+
+import sys as _sys
+from typing import Any, Iterable, Optional
+
+from . import colors as _colors
+
+
+def build_tool_subparsers(
+    subparsers,
+    projects: Iterable[Any],  # DazzleEntity instances or plain manifest dicts
+    reserved_commands: Optional[set] = None,
+    *,
+    add_help: bool = False,
+    warn_on_conflict: bool = True,
+    exempt_from_warning: Optional[set] = None,
+) -> list:
+    """Register one subparser per discovered tool.
+
+    This is the "tool dispatch" half of an aggregator's argparse parser —
+    complementing the meta-command subparsers (list, info, etc.) that
+    the registry or ``default_meta_commands`` factories install.
+
+    Args:
+        subparsers: an ``argparse._SubParsersAction`` obtained from
+            ``parser.add_subparsers(...)``.
+        projects: iterable of project dicts (each must have a ``name``
+            key; ``description`` and ``_fqcn`` are optional).
+        reserved_commands: set of names that cannot be used as tool names
+            (typically ``engine.reserved_commands``). Tools matching
+            reserved names are skipped with a warning to stderr.
+        add_help: forwarded to ``add_parser``. Default ``False`` — tools
+            handle their own ``--help`` via dispatch.
+        warn_on_conflict: if True (default), print a stderr warning for
+            tools skipped due to reserved-command collision. Set False
+            to silence (test environments, repeated invocations).
+        exempt_from_warning: optional set of names that are exempt from
+            the conflict warning. Used by the engine to pass
+            ``meta_registry.user_overrides()`` so deliberately-overridden
+            meta-commands don't fire the warning on every invocation.
+            Names in this set still skip parser registration (the meta-
+            command's parser wins), but no warning is emitted — the
+            override is the acknowledgment.
+
+    Returns:
+        List of the subparsers that were registered. Each has
+        ``_project`` set via ``set_defaults`` so the dispatch-side can
+        identify which tool was invoked.
+    """
+    reserved = reserved_commands or set()
+    exempt = exempt_from_warning or set()
+    registered = []
+    seen_names: set = set()
+
+    for project in projects:
+        if isinstance(project, dict):
+            name = project.get("name")
+        else:
+            name = project.name
+        if not name:
+            continue
+
+        if name in reserved:
+            if warn_on_conflict and name not in exempt:
+                # As of issue #67's redesign, shadowed tools WIN short-name
+                # dispatch (engine._dispatch_registry_path checks tool
+                # lookup before the meta-command path). The argparse
+                # subparser is still skipped here because argparse can't
+                # carry two subparsers with the same name; the meta-
+                # command's subparser stays registered but is unreachable
+                # by short name (FQCN access for meta-commands is a
+                # planned future enhancement). The warning tells aggregator
+                # authors about the collision so they can rename or
+                # consciously accept the shadowing.
+                print(
+                    _colors.warn(
+                        f"Warning: Tool {name!r} shadows reserved meta-command -- tool wins short-name dispatch"
+                    ),
+                    file=_sys.stderr,
+                )
+            continue
+
+        if name in seen_names:
+            # Duplicate short name across kits — skip subsequent ones.
+            # The FQCN index handles collision resolution during dispatch;
+            # this only affects short-name argparse registration.
+            continue
+        seen_names.add(name)
+
+        if isinstance(project, dict):
+            description = project.get("description") or ""
+        else:
+            description = project.description or ""
+        sub = subparsers.add_parser(
+            name,
+            help=description,
+            add_help=add_help,
+        )
+        sub.set_defaults(_project=project)
+        registered.append(sub)
+
+    return registered
+
+
+def derive_reserved_from_registry(registry, extras: Optional[set] = None) -> set:
+    """Combine a registry's registered names with extra reserved names.
+
+    The result is suitable for passing as ``reserved_commands`` to
+    ``build_tool_subparsers``. Engine's ``reserved_commands`` property
+    uses this pattern internally.
+
+    Args:
+        registry: a ``MetaCommandRegistry`` instance.
+        extras: optional additional names to reserve (for future
+            meta-commands not yet registered, or aggregator-specific
+            name guards).
+
+    Returns:
+        Set of reserved command names.
+    """
+    names = set(registry.registered()) if registry is not None else set()
+    if extras:
+        names = names | set(extras)
+    return names
+
+
+def add_version_flag(parser, version_info=None, app_name: Optional[str] = None):
+    """Attach a ``--version`` / ``-V`` flag to the given parser.
+
+    Produces output like ``wtf-windows 0.1.3 (0.1.3_main_5-20260418-abc123)``
+    when ``version_info`` is a ``(display, full)`` tuple, or just the
+    app name when ``version_info`` is None.
+
+    Typically called on the top-level argparse parser during
+    aggregator ``main()``. No-op if ``parser`` is None.
+    """
+    if parser is None:
+        return
+    if version_info:
+        display, full = version_info
+        name = app_name or "aggregator"
+        version_string = f"{name} {display} ({full})"
+    else:
+        version_string = app_name or "aggregator"
+    parser.add_argument(
+        "--version", "-V",
+        action="version",
+        version=version_string,
+    )
+
+
+def default_epilog_for(app_name: str, tool_count: int, kit_count: int = 0) -> str:
+    """Produce a generic epilog string for aggregators without custom epilog.
+
+    Used by the engine when ``epilog_builder`` isn't set. Aggregators
+    with domain-specific help (wtf-style diagnostic badges, dazzlecmd's
+    tree-organized categorization) provide their own ``epilog_builder``.
+    """
+    lines = []
+    if tool_count > 0:
+        lines.append(f"{tool_count} tool(s)" + (f" across {kit_count} kit(s)" if kit_count else ""))
+    lines.append(f"Run '{app_name} list' to see available tools.")
+    lines.append(f"Run '{app_name} <tool> --help' for tool-specific options.")
+    return "\n".join(lines)

dazzlecmd_lib/colors.py

@@ -0,0 +1,228 @@
+"""ANSI color helpers for dazzlecmd-lib rendering.
+
+Slim by design: 8-color ANSI palette only (broadly supported including PuTTY,
+Windows Terminal, modern conhost.exe with VT processing, bash/zsh, WSL). No
+truecolor escapes (256-color or RGB) because those break older terminals.
+
+The lib's render functions (`render_list`, `render_info`, `render_tree`,
+`render_kit_list`, plus stderr warnings) call `should_use_color()` to decide
+whether to emit color, then wrap text via `colorize(text, *codes)`.
+
+Detection priority (in `should_use_color`):
+1. ``NO_COLOR`` env var set (any value)  -> False (community standard)
+2. ``DZ_COLOR=always`` OR ``FORCE_COLOR`` env var set -> True (force on)
+3. ``DZ_COLOR=never`` -> False (project-specific override)
+4. ``stream.isatty()`` -> True if the stream is a TTY, else False
+
+Windows compatibility:
+- Modern Windows (Win10 1511+, Win11) handles ANSI natively via
+  ``ENABLE_VIRTUAL_TERMINAL_PROCESSING`` in conhost.exe.
+- Legacy cmd.exe needs ``colorama`` to translate ANSI -> Windows Console API.
+- This module lazily imports ``colorama`` and calls ``colorama.init()`` on
+  Windows when ``should_use_color()`` first returns True. Missing colorama
+  is non-fatal -- modern Windows works without it.
+
+Install with ``pip install dazzlecmd-lib[color]`` to add colorama as a
+Windows-only optional extra. Adding colorama to required deps is rejected
+by the lib's slim-default constraint.
+
+Public API:
+    RESET, BOLD, DIM, RED, GREEN, YELLOW, CYAN, BRIGHT_RED  -- ANSI constants
+    should_use_color(stream=None) -> bool                    -- TTY+env probe
+    colorize(text: str, *codes: str) -> str                  -- wrap helper
+    colorize_for(stream, text, *codes) -> str                -- TTY-gated wrap
+    warn(text: str, stream=None) -> str                      -- YELLOW (stderr)
+    error(text: str, stream=None) -> str                     -- BRIGHT_RED (stderr)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# 8-color ANSI palette + bold/dim emphasis. Compatible with PuTTY, cmd.exe
+# (post-VT-mode), PowerShell, Windows Terminal, conhost, bash, zsh, WSL.
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RED = "\033[31m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+CYAN = "\033[36m"
+BRIGHT_RED = "\033[91m"
+
+# Track colorama init so we only attempt it once per process. The init is
+# a no-op on non-Windows platforms but the import attempt costs ~1ms.
+_ansi_initialized = False
+
+
+def _init_windows_ansi(force=False):
+    """Lazily import and initialize colorama on Windows.
+
+    ``force=True`` -> ``colorama.init(strip=False)``. Used when the caller
+    explicitly forces color (``DZ_COLOR=always`` / ``FORCE_COLOR``) and
+    output is piped: without ``strip=False``, colorama strips ANSI when
+    not writing to a real console, which defeats the explicit force.
+
+    ``force=False`` -> ``colorama.init()`` (default). On a real Windows
+    console, colorama translates ANSI to Windows Console API calls. When
+    piped, ANSI is stripped (the polite default for ``isatty=True`` paths
+    where the user hasn't asked for forced color).
+
+    Silent no-op if colorama isn't installed (modern Windows 1511+ handles
+    ANSI natively via VT processing; only legacy cmd.exe truly needs
+    colorama).
+    """
+    try:
+        import colorama  # type: ignore[import-not-found]
+        if force:
+            colorama.init(strip=False)
+        else:
+            colorama.init()
+    except ImportError:
+        pass
+
+
+def should_use_color(stream=None) -> bool:
+    """Return True if ANSI color should be emitted to ``stream``.
+
+    Detection priority:
+    1. ``NO_COLOR`` env var set (any value)  -> False (community standard).
+    2. ``DZ_COLOR=always`` OR ``FORCE_COLOR`` set -> True.
+    3. ``DZ_COLOR=never`` -> False.
+    4. ``stream.isatty()`` -> True/False.
+
+    Default stream: ``sys.stdout``. Pass ``sys.stderr`` for warning paths.
+
+    Side effect: on the first call that returns True on Windows, attempts to
+    initialize colorama (silently no-ops if colorama isn't installed). This
+    is idempotent; subsequent calls don't re-init.
+    """
+    global _ansi_initialized
+
+    # NO_COLOR (industry standard: https://no-color.org/) -- absolute override
+    if os.environ.get("NO_COLOR") is not None:
+        return False
+
+    dz_color = os.environ.get("DZ_COLOR", "").lower()
+
+    # Force-on cases: user explicitly wants color even when piped.
+    # On Windows, pass force=True so colorama keeps the ANSI codes intact
+    # (its default strips them when output isn't a real console).
+    if dz_color == "always" or os.environ.get("FORCE_COLOR"):
+        if not _ansi_initialized and sys.platform == "win32":
+            _init_windows_ansi(force=True)
+            _ansi_initialized = True
+        return True
+
+    # Force-off case
+    if dz_color == "never":
+        return False
+
+    # Default: gate on isatty. On a real Windows console, colorama
+    # translates ANSI to Win Console API; when piped it strips, which
+    # is the right default for "polite" auto-detected color.
+    target = stream if stream is not None else sys.stdout
+    is_tty = hasattr(target, "isatty") and target.isatty()
+    if is_tty and not _ansi_initialized and sys.platform == "win32":
+        _init_windows_ansi(force=False)
+        _ansi_initialized = True
+    return is_tty
+
+
+def colorize(text: str, *codes: str) -> str:
+    """Wrap ``text`` in ANSI ``codes``, terminated with ``RESET``.
+
+    Returns ``text`` unchanged when ``codes`` is empty. Designed so the
+    caller can do:
+
+        from dazzlecmd_lib.colors import colorize, BOLD, should_use_color
+
+        styled = colorize(label, BOLD) if should_use_color() else label
+        print(styled)
+
+    Or for the common pattern where color is conditional:
+
+        codes = (BOLD,) if should_use_color() else ()
+        print(colorize(label, *codes))
+
+    No automatic TTY check here -- callers control when to apply color so
+    that data-shape APIs (like ``build_list_entries``) remain plain.
+    """
+    if not codes:
+        return text
+    return "".join(codes) + text + RESET
+
+
+def colorize_for(stream, text: str, *codes: str) -> str:
+    """Convenience wrapper: colorize ``text`` only when ``should_use_color(stream)``.
+
+    Designed for the common stderr-warning pattern where a single line
+    of code must decide both whether to color AND wrap the text:
+
+        import sys
+        from dazzlecmd_lib.colors import colorize_for, YELLOW
+
+        print(colorize_for(sys.stderr, f"Warning: {msg}", YELLOW),
+              file=sys.stderr)
+
+    Equivalent to:
+
+        if should_use_color(stream):
+            ... colorize(text, *codes) ...
+        else:
+            ... text ...
+
+    but collapses the conditional into one expression so the call site
+    stays scannable.
+    """
+    if should_use_color(stream):
+        return colorize(text, *codes)
+    return text
+
+
+def warn(text: str, stream=None) -> str:
+    """Format ``text`` as a warning. YELLOW + RESET when color is enabled
+    on ``stream`` (defaults to ``sys.stderr``); plain ``text`` otherwise.
+
+    Semantic shortcut for the common pattern:
+
+        print(colorize_for(sys.stderr, f"Warning: {msg}", YELLOW),
+              file=sys.stderr)
+
+    Usage:
+
+        import sys
+        from dazzlecmd_lib.colors import warn
+
+        print(warn(f"Tool {tool!r} not found."), file=sys.stderr)
+
+    Pairs with ``error()`` for the two most common stderr-message classes.
+    Callers wanting a non-standard emphasis (e.g. BOLD+YELLOW for a banner)
+    should call ``colorize_for`` directly with their own codes.
+    """
+    target = stream if stream is not None else sys.stderr
+    return colorize_for(target, text, YELLOW)
+
+
+def error(text: str, stream=None) -> str:
+    """Format ``text`` as an error. BRIGHT_RED + RESET when color is enabled
+    on ``stream`` (defaults to ``sys.stderr``); plain ``text`` otherwise.
+
+    Semantic shortcut for the common pattern:
+
+        print(colorize_for(sys.stderr, f"Error: {exc}", BRIGHT_RED),
+              file=sys.stderr)
+
+    Usage:
+
+        import sys
+        from dazzlecmd_lib.colors import error
+
+        print(error(f"Error: cannot read config: {exc}"), file=sys.stderr)
+
+    Use BRIGHT_RED rather than RED to stay visible on dark terminals where
+    plain RED is hard to read.
+    """
+    target = stream if stream is not None else sys.stderr
+    return colorize_for(target, text, BRIGHT_RED)

dazzlecmd_lib/conditions.py

@@ -0,0 +1,211 @@
+"""detect_when condition evaluator -- shared library for setup and runtime.
+
+A `detect_when` block is a JSON object describing a boolean predicate over the
+host environment. Both the setup resolver (is this platform's install branch
+active?) and the runtime resolver (should this `prefer` entry be selected?)
+consume the same evaluator.
+
+Supported matcher keys (leaf):
+
+    file_exists: "/path/to/file"
+        True if the path exists and is a regular file.
+
+    dir_exists: "/path/to/dir"
+        True if the path exists and is a directory.
+
+    env_var: "VAR_NAME"
+        True if the env var is set AND non-empty. Values are never logged.
+
+    env_var_equals: {"name": "VAR_NAME", "value": "expected"}
+        True if os.environ[name] == value (strict string equality).
+        Values are never logged.
+
+    command_available: "bun"
+        True if shutil.which(name) resolves (PATH + PATHEXT on Windows).
+
+    uname_contains: "microsoft"
+        Case-insensitive substring match against a composite PlatformInfo
+        string: "<os> <subtype> <arch> <version> [wsl]".
+
+Combinators:
+
+    all: [<condition>, ...]   AND of sub-conditions. `all: []` is vacuously True.
+    any: [<condition>, ...]   OR of sub-conditions. `any: []` is vacuously False.
+
+Composition:
+
+    - Multiple keys in the SAME dict are AND'd:
+        {"file_exists": "/etc/debian_version", "command_available": "apt"}
+        passes only if both hold.
+
+    - Keys beginning with "_" are treated as metadata (e.g. "_schema_version",
+      "_comment") and ignored by the evaluator.
+
+    - An empty condition dict is vacuously True.
+
+    - Unknown matcher keys raise ConditionSyntaxError. Authors hitting a typo
+      see it immediately rather than silently falling through.
+
+Security: env var VALUES are never included in error messages or return values,
+only names and presence. A condition checking a secret-bearing env var will
+not leak the secret via a diagnostic trace.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from typing import Any, List, Optional
+
+from dazzlecmd_lib.platform_detect import PlatformInfo
+
+
+class ConditionSyntaxError(ValueError):
+    """Raised when a condition dict contains unknown keys or malformed values."""
+
+
+_LEAF_MATCHERS = {
+    "file_exists",
+    "dir_exists",
+    "env_var",
+    "env_var_equals",
+    "command_available",
+    "uname_contains",
+}
+_COMBINATORS = {"all", "any"}
+
+
+def _file_exists(path: str) -> bool:
+    if not isinstance(path, str) or not path:
+        return False
+    return os.path.isfile(path)
+
+
+def _dir_exists(path: str) -> bool:
+    if not isinstance(path, str) or not path:
+        return False
+    return os.path.isdir(path)
+
+
+def _env_var(name: str) -> bool:
+    if not isinstance(name, str) or not name:
+        return False
+    value = os.environ.get(name)
+    return bool(value)
+
+
+def _env_var_equals(spec: dict) -> bool:
+    if not isinstance(spec, dict):
+        raise ConditionSyntaxError(
+            f"env_var_equals requires a dict with 'name' and 'value', got {type(spec).__name__}"
+        )
+    name = spec.get("name")
+    expected = spec.get("value")
+    if not isinstance(name, str) or not name:
+        raise ConditionSyntaxError("env_var_equals.name must be a non-empty string")
+    if expected is None:
+        raise ConditionSyntaxError("env_var_equals.value is required")
+    actual = os.environ.get(name)
+    return actual == str(expected)
+
+
+def _command_available(name: str) -> bool:
+    if not isinstance(name, str) or not name:
+        return False
+    return shutil.which(name) is not None
+
+
+def _uname_composite(platform_info: PlatformInfo) -> str:
+    parts = [platform_info.os]
+    if platform_info.subtype:
+        parts.append(platform_info.subtype)
+    parts.append(platform_info.arch)
+    if platform_info.version:
+        parts.append(platform_info.version)
+    if platform_info.is_wsl:
+        parts.append("wsl")
+    return " ".join(parts).lower()
+
+
+def _uname_contains(substring: str, platform_info: PlatformInfo) -> bool:
+    if not isinstance(substring, str) or not substring:
+        return False
+    return substring.lower() in _uname_composite(platform_info)
+
+
+def _evaluate_leaf(
+    key: str, value: Any, platform_info: PlatformInfo
+) -> bool:
+    if key == "file_exists":
+        return _file_exists(value)
+    if key == "dir_exists":
+        return _dir_exists(value)
+    if key == "env_var":
+        return _env_var(value)
+    if key == "env_var_equals":
+        return _env_var_equals(value)
+    if key == "command_available":
+        return _command_available(value)
+    if key == "uname_contains":
+        return _uname_contains(value, platform_info)
+    raise ConditionSyntaxError(f"unknown leaf matcher: {key!r}")
+
+
+def _evaluate_all(conditions: List[Any], platform_info: PlatformInfo) -> bool:
+    if not isinstance(conditions, list):
+        raise ConditionSyntaxError(
+            f"'all' requires a list of conditions, got {type(conditions).__name__}"
+        )
+    # Vacuous: empty `all` is True.
+    return all(evaluate_condition(c, platform_info) for c in conditions)
+
+
+def _evaluate_any(conditions: List[Any], platform_info: PlatformInfo) -> bool:
+    if not isinstance(conditions, list):
+        raise ConditionSyntaxError(
+            f"'any' requires a list of conditions, got {type(conditions).__name__}"
+        )
+    # Vacuous: empty `any` is False.
+    return any(evaluate_condition(c, platform_info) for c in conditions)
+
+
+def evaluate_condition(
+    condition: Optional[dict],
+    platform_info: PlatformInfo,
+) -> bool:
+    """Evaluate a detect_when dict against the given platform.
+
+    Returns True if all declared matchers pass. See module docstring for
+    schema details.
+
+    An empty or None condition is vacuously True (no conditions declared ==
+    unconditionally active).
+    """
+    if condition is None:
+        return True
+    if not isinstance(condition, dict):
+        raise ConditionSyntaxError(
+            f"condition must be a dict or None, got {type(condition).__name__}"
+        )
+    if not condition:
+        return True
+
+    results: List[bool] = []
+    for key, value in condition.items():
+        if key.startswith("_"):
+            # Metadata (e.g., _schema_version, _comment) -- ignore.
+            continue
+        if key in _LEAF_MATCHERS:
+            results.append(_evaluate_leaf(key, value, platform_info))
+        elif key == "all":
+            results.append(_evaluate_all(value, platform_info))
+        elif key == "any":
+            results.append(_evaluate_any(value, platform_info))
+        else:
+            raise ConditionSyntaxError(
+                f"unknown condition key: {key!r}. "
+                f"Valid keys: {sorted(_LEAF_MATCHERS | _COMBINATORS)}"
+            )
+
+    # Multiple keys in same dict are AND'd. Empty results (only metadata keys) -> True.
+    return all(results) if results else True