cmdbox-cli 1.0.0__py3-none-any.whl

cmdbox/cli/ui/primitives.py

@@ -0,0 +1,410 @@
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import Any, Mapping, Sequence
+
+from rich import box
+from rich.align import Align
+from rich.console import Group, RenderableType
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.table import Table
+from rich.text import Text
+
+
+@dataclass(frozen=True)
+class UiStyles:
+    # General
+    title: str = "ui.title"
+    subtitle: str = "ui.subtitle"
+    muted: str = "ui.muted"
+    dim: str = "ui.dim"
+
+    # Status
+    success: str = "status.success"
+    info: str = "status.info"
+    warning: str = "status.warning"
+    error: str = "status.error"
+
+    # Panels / borders
+    panel_border: str = "ui.border"
+    panel_title: str = "ui.panel_title"
+
+    # Tables
+    table_header: str = "ui.table_header"
+    table_caption: str = "ui.caption"
+    kv_key: str = "ui.kv.key"
+    kv_value: str = "ui.kv.value"
+
+    # Code-ish output (semantic)
+    code: str = "code"
+    code_inline: str = "code.inline"
+    code_block: str = "code.block"
+
+
+def to_text(value: Any, *, style: str | None = None) -> Text:
+    """
+    Converts a given value into a formatted textual representation, optionally applying
+    a text style.
+
+    The function takes various types of input (e.g., None, datetime, date, or other types)
+    and returns a corresponding textual representation as a `Text` object. If a style
+    is specified, it will stylize the output text.
+
+    Args:
+        value: The input value to convert. Can be of type None, datetime, date,
+            or any type that can be converted into a string representation.
+        style: An optional string specifying the style to apply to the output text.
+
+    Returns:
+        Text: A formatted textual representation of the input value.
+    """
+    if value is None:
+        t = Text("null")
+    elif isinstance(value, Text):
+        if style:
+            value.stylize(style)
+        return value
+    elif isinstance(value, datetime):
+        t = Text(value.isoformat(sep=" ", timespec="seconds"))
+    elif isinstance(value, date):
+        t = Text(value.isoformat())
+    else:
+        t = Text(str(value))
+
+    if style:
+        t.stylize(style)
+    return t
+
+
+def spacer(lines: int = 1) -> RenderableType:
+    return Text("\n" * max(0, lines))
+
+
+def divider(title: str | None = None, *, style: str = "ui.dim") -> Rule:
+    if title:
+        return Rule(Text(title), style=style)
+    return Rule(style=style)
+
+
+def col(name: str, *, style: str = "", **kwargs) -> tuple[str, dict[str, Any]]:
+    """
+    A helper function that generates a table column.
+
+    This function facilitates the creation of a tuple that consists of a string name and a
+    dictionary. The dictionary contains a "style" key with a specified value and may also include
+    other key-value pairs provided as additional arguments.
+
+    Args:
+        name (str): The name or identifier for the column.
+        style (str, optional): A string specifying the style attribute. Defaults to an empty string.
+        **kwargs: Additional key-value pairs to include in the dictionary.
+
+    Returns:
+        tuple[str, dict[str, Any]]: A tuple where the first element is the provided name, and the
+        second element is a dictionary containing the "style" attribute along with any additional
+        key-value pairs.
+    """
+    data = {"style": style}
+    data.update(kwargs)
+    return name, data
+
+
+def banner(
+    title: str,
+    subtitle: str | None = None,
+    *,
+    status: str | None = None,
+    styles: UiStyles = UiStyles(),
+) -> RenderableType:
+    """
+    A consistent header block.
+
+    status: one of "success" | "info" | "warning" | "error" or a Theme style name
+    """
+    if status:
+        # Allow semantic names or full style names
+        status_style = getattr(styles, status, status)
+        border_style = status_style
+        title_style = status_style
+    else:
+        border_style = styles.panel_border
+        title_style = styles.title
+
+    title_text = Text(title, style=title_style)
+
+    parts: list[RenderableType] = [title_text]
+
+    if subtitle:
+        parts.append(Text(subtitle, style=styles.subtitle))
+
+    return Panel(
+        Group(*parts),
+        border_style=border_style,
+        padding=(0, 1),
+    )
+
+
+def tag_pill(
+    name: str,
+    *,
+    style: str = "tag.pill",
+    padding: tuple[int, int] = (0, 1),
+) -> RenderableType:
+    text = Text(name, style=style)
+    return Padding(text, padding)
+
+
+def tag_block(
+    tags: Sequence[str],
+    *,
+    style: str = "tag.pill",
+    separator: str = " ",
+) -> RenderableType:
+    text = Text()
+
+    for i, tag in enumerate(tags):
+        if i > 0:
+            text.append(separator)
+        text.append(f" {tag} ", style=style)
+
+    return text
+
+
+def status_line(
+    message: str,
+    *,
+    status: str = "info",
+    styles: UiStyles = UiStyles(),
+) -> Text:
+    """
+    One line status message with semantic styling.
+    """
+    status_style = getattr(styles, status, status)
+    return Text(message, style=status_style)
+
+
+def bullet_list(
+    items: Sequence[Any],
+    *,
+    bullet: str = "•",
+    item_style: str = "ui.kv.value",
+    bullet_style: str = "ui.muted",
+    styles: UiStyles = UiStyles(),
+    empty_message: str | None = None,
+) -> RenderableType:
+    """
+    Simple bullet list that is safe against markup.
+    """
+    if not items:
+        if empty_message is None:
+            return Text("")
+        return Text(empty_message, style=styles.muted)
+
+    lines: list[RenderableType] = []
+    for item in items:
+        b = Text(f"{bullet} ", style=bullet_style if bullet_style else styles.muted)
+        v = to_text(item, style=item_style if item_style else styles.kv_value)
+        lines.append(Text.assemble(b, v))
+
+    return Group(*lines)
+
+
+def kv_table(
+    rows: Sequence[tuple[str, Any]],
+    *,
+    key_style: str = "ui.kv.key",
+    value_style: str = "ui.kv.value",
+    show_header: bool = False,
+    styles: UiStyles = UiStyles(),
+) -> Table:
+    """
+    Two-column key/value table for detail views.
+    """
+    table = Table(
+        show_header=show_header,
+        box=None,
+        pad_edge=False,
+        padding=(0, 1),
+        collapse_padding=True,
+    )
+
+    if show_header:
+        table.add_column("Field", style=styles.table_header)
+        table.add_column("Value", style=styles.table_header)
+    else:
+        table.add_column(
+            justify="right", style=key_style or styles.kv_key, no_wrap=True
+        )
+        table.add_column(style=value_style or styles.kv_value, overflow="fold")
+
+    for k, v in rows:
+        table.add_row(
+            to_text(k, style=key_style or styles.kv_key),
+            to_text(v, style=value_style or styles.kv_value),
+        )
+
+    return table
+
+
+def kv_panel(
+    title: str,
+    rows: Sequence[tuple[str, Any]],
+    *,
+    border_style: str = "ui.border",
+    styles: UiStyles = UiStyles(),
+) -> Panel:
+    """
+    Panel containing a key/value table.
+    """
+    return Panel(
+        kv_table(rows, styles=styles),
+        title=Text(title, style=styles.panel_title),
+        border_style=border_style,
+        padding=(0, 1),
+    )
+
+
+def table_panel(
+    title: str,
+    columns: Sequence[tuple[str, dict[str, Any]]],
+    rows: Sequence[Sequence[Any]],
+    *,
+    caption: str | None = None,
+    border_style: str = "ui.border",
+    styles: UiStyles = UiStyles(),
+) -> Panel:
+    """
+    Build a standard table inside a panel.
+
+    columns: [("Alias", {"style": "...", "no_wrap": True}), ...]
+    rows: list of row sequences. Each cell is converted with to_text.
+    """
+    table = Table(
+        show_header=True,
+        header_style=styles.table_header,
+        pad_edge=False,
+        collapse_padding=True,
+        box=box.MINIMAL,
+    )
+
+    for name, kwargs in columns:
+        table.add_column(name, **kwargs)
+
+    for row in rows:
+        table.add_row(*[to_text(cell) for cell in row])
+
+    if caption:
+        table.caption = caption
+        table.caption_style = styles.table_caption
+
+    return Panel(
+        table,
+        title=Text(title, style=styles.panel_title),
+        border_style=border_style,
+        padding=(0, 1),
+    )
+
+
+def code_inline(
+    text: Any,
+    *,
+    style: str = "code.inline",
+    styles: UiStyles = UiStyles(),
+) -> Text:
+    """
+    Semantic inline code styling. Does not change terminal font, but gives a consistent look.
+    """
+    # If you do not define code.inline, fall back to code, then to a generic style.
+    resolved = style
+    if style == "code.inline":
+        resolved = styles.code_inline or styles.code or "bold"
+    return to_text(text, style=resolved)
+
+
+def code_block(
+    text: Any,
+    *,
+    title: str | None = None,
+    border_style: str = "ui.border",
+    style: str = "code.block",
+    styles: UiStyles = UiStyles(),
+    fit: bool = False,
+) -> Panel:
+    """
+    Panel for code-ish blocks (templates, resolved commands, previews).
+    """
+    resolved = style
+    if style == "code.block":
+        resolved = styles.code_block or styles.code or "bold"
+
+    body = to_text(text, style=resolved)
+
+    panel_title = Text(title, style=styles.panel_title) if title else None
+    panel_cls = Panel.fit if fit else Panel
+
+    return panel_cls(
+        body,
+        title=panel_title,
+        border_style=border_style,
+        padding=(1, 1),
+    )
+
+
+def centered(renderable: RenderableType) -> RenderableType:
+    return Align.center(renderable)
+
+
+def stack(*renderables: RenderableType) -> RenderableType:
+    """
+    Group renderables vertically.
+    """
+    return Group(*renderables)
+
+
+def section(
+    title: str,
+    body: RenderableType,
+    caption: str | None = None,
+    *,
+    border_style: str = "ui.border",
+    styles: UiStyles = UiStyles(),
+) -> Panel:
+    """
+    Generic titled panel wrapper.
+    """
+    return Panel(
+        body,
+        title=Text(title, style=styles.panel_title),
+        subtitle=Text(caption, style="ui.caption") if caption else None,
+        border_style=border_style,
+        padding=(0, 1),
+    )
+
+
+def summary_counts(
+    counts: Mapping[str, int],
+    *,
+    styles: UiStyles = UiStyles(),
+) -> RenderableType:
+    """
+    Small helper for displaying a few counts, like:
+    Commands: 12  Variables: 4  Tags: 9
+    """
+    parts: list[Text] = []
+    first = True
+    for label, count in counts.items():
+        if not first:
+            parts.append(Text("  ", style=styles.muted))
+        first = False
+        parts.append(Text(f"{label}:", style=styles.muted))
+        parts.append(Text(" ", style=styles.muted))
+        parts.append(Text(str(count), style=styles.title))
+
+    return Text.assemble(*parts)
+
+
+def pluralize(count: int, singular: str, plural: str | None = None) -> str:
+    if count == 1:
+        return f"1 {singular}"
+    return f"{count} {plural or (singular + 's')}"

cmdbox/cli/ui/theme.py

@@ -0,0 +1,43 @@
+from rich.theme import Theme
+
+CMDBOX_THEME = Theme(
+    {
+        # Core text
+        "ui.title": "bold",
+        "ui.subtitle": "dim",
+        "ui.muted": "dim",
+        "ui.dim": "dim",
+        "ui.border": "dim",
+        "ui.panel_title": "bold",
+        # Tables
+        "ui.table_header": "bold",
+        "ui.caption": "dim",
+        # Key/value panels
+        "ui.kv.key": "dim",
+        "ui.kv.value": "",
+        # Status
+        "status.success": "bold green",
+        "status.info": "bold cyan",
+        "status.warning": "bold yellow",
+        "status.error": "bold red",
+        # Code semantics (not a font switch, just a consistent code look)
+        "code": "cyan",
+        "code.inline": "cyan",
+        "code.block": "cyan",
+        # Common entity accents (optional, keep minimal)
+        "entity.name": "bold",
+        "entity.id": "magenta",
+        "entity.count": "bold",
+        "entity.time": "dim",
+        # Tags
+        "tag.pill": "bold white on dark_green",
+        "tag.pill_muted": "white on grey23",
+        # Execution and previews
+        "run.command": "cyan",
+        "run.stdout": "",
+        "run.stderr": "bold red",
+        "run.trace.kind": "dim",
+        "run.trace.key": "magenta",
+        "run.trace.value": "cyan",
+    }
+)

cmdbox/cli/ui/theme_builder.py

@@ -0,0 +1,49 @@
+from rich.theme import Theme as RichTheme
+
+from cmdbox.settings.models import Settings
+
+
+def build_theme(settings: Settings) -> RichTheme:
+    c = settings.ui.colors
+
+    style_map = {
+        "ui.title": c.title,
+        "ui.subtitle": c.subtitle,
+        "ui.muted": c.muted,
+        "ui.dim": c.muted,
+        "ui.border": c.border,
+        "ui.panel_title": c.panel_title,
+        # Tables
+        "ui.table_header": c.table_header,
+        "ui.caption": c.caption,
+        # Key/value panels
+        "ui.kv.key": c.kv_key,
+        "ui.kv.value": c.kv_value,
+        # Status
+        "status.success": c.success,
+        "status.info": c.info,
+        "status.warning": c.warning,
+        "status.error": c.error,
+        "status.debug": c.debug,
+        # Code semantics (not a font switch, just a consistent code look)
+        "code": c.code,
+        "code.inline": c.code_inline,
+        "code.block": c.code_block,
+        # Common entity accents (optional, keep minimal)
+        "entity.name": c.entity_name,
+        "entity.id": c.entity_id,
+        "entity.count": c.entity_count,
+        "entity.time": c.entity_time,
+        # Tags
+        "tag.pill": c.tag_pill,
+        "tag.pill_muted": c.tag_pill_muted,
+        # Execution and previews
+        "run.command": c.run_command,
+        "run.stdout": c.run_stdout,
+        "run.stderr": c.run_stderr,
+        "run.trace.kind": c.trace_kind,
+        "run.trace.key": c.trace_key,
+        "run.trace.value": c.trace_value,
+    }
+
+    return RichTheme(style_map)

cmdbox/common/io.py

@@ -0,0 +1,34 @@
+import os
+import tempfile
+from pathlib import Path
+
+from cmdbox.logging_setup.log_decorators import log_action
+
+
+@log_action(__name__, "atomic_write_text")
+def atomic_write_text(dest: Path, text: str, encoding: str = "utf-8") -> None:
+    """
+    Performs an atomic write operation to a text file. This ensures that the file content is written
+    to a temporary file first and then atomically replaces the original file to prevent partial writes
+    or data corruption.
+
+    Args:
+        dest (Path): The destination path for the final output file.
+        text (str): The text content to write to the file.
+
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding=encoding,
+        dir=str(dest.parent),
+        delete=False,
+        prefix=dest.name + ".",
+        suffix=".tmp",
+        newline="\n",
+    ) as tf:
+        tmp_path = Path(tf.name)
+        tf.write(text)
+        tf.flush()
+        os.fsync(tf.fileno())
+    tmp_path.replace(dest)

cmdbox/container.py

@@ -0,0 +1,156 @@
+from functools import lru_cache
+
+from cmdbox.cli.ui.console import ConsoleUI
+from cmdbox.cli.ui.theme_builder import build_theme
+from cmdbox.core.fields import (
+    COMMAND_DISPLAY_FIELDS,
+    COMMAND_SEARCH_FIELDS,
+    VARIABLE_DISPLAY_FIELDS,
+    VARIABLE_SEARCH_FIELDS,
+    TAG_DISPLAY_FIELDS,
+    TAG_SEARCH_FIELDS,
+)
+from cmdbox.repositories.history_repository import HistoryRepository
+from cmdbox.services.field_selection import FieldSelectionResolver
+from cmdbox.services.history_service import HistoryService
+from cmdbox.services.variable_services import VariableServices
+from cmdbox.settings.models import Settings
+from cmdbox.settings.settings_repository import SettingsRepository
+from cmdbox.settings.settings_service import SettingsService
+from cmdbox.core.paths import get_app_data_dir
+from cmdbox.database import get_db
+from cmdbox.repositories.command_repository import CommandRepository
+from cmdbox.repositories.tag_repository import TagRepository
+from cmdbox.repositories.variable_repository import VariableRepository
+from cmdbox.resolve.lookup import MemoizedLookup, RepoLookup
+from cmdbox.resolve.resolver import Resolver
+from cmdbox.runtime.executor import Executor
+from cmdbox.services.command_services import CommandServices
+from cmdbox.services.run_service import RunService
+from cmdbox.services.tag_services import TagServices
+
+
+@lru_cache(maxsize=1)
+def get_settings_service() -> SettingsService:
+    config_path = get_app_data_dir() / "config.toml"
+    repo = SettingsRepository(config_path)
+    settings = SettingsService(repo)
+    return settings
+
+
+def get_settings() -> Settings:
+    return get_settings_service().get()
+
+
+@lru_cache(maxsize=1)
+def get_console() -> ConsoleUI:
+    _settings = get_settings()
+    theme = build_theme(_settings)
+    return ConsoleUI(theme)
+
+
+@lru_cache(maxsize=1)
+def get_command_repo() -> CommandRepository:
+    return CommandRepository()
+
+
+@lru_cache(maxsize=1)
+def get_variable_repo() -> VariableRepository:
+    return VariableRepository()
+
+
+@lru_cache(maxsize=1)
+def get_tag_repo() -> TagRepository:
+    return TagRepository()
+
+
+@lru_cache(maxsize=1)
+def get_history_repo() -> HistoryRepository:
+    get_db()
+    return HistoryRepository()
+
+
+@lru_cache(maxsize=1)
+def get_resolver(strict: bool = False) -> Resolver:
+    get_db()
+    command_repo = get_command_repo()
+    variable_repo = get_variable_repo()
+    repo_lookup = RepoLookup(command_repo, variable_repo)
+    lookup = MemoizedLookup(repo_lookup)
+    return Resolver(lookup, strict=strict)
+
+
+@lru_cache(maxsize=1)
+def get_run_service() -> RunService:
+    get_db()
+    cmd_repo = get_command_repo()
+    resolver = get_resolver()
+    executor = Executor()
+    return RunService(
+        cmd_repo,
+        resolver,
+        executor,
+        history_repo=get_history_repo(),
+        get_settings=get_settings,
+    )
+
+
+@lru_cache(maxsize=1)
+def get_command_services() -> CommandServices:
+    get_db()
+    cmd_repo = get_command_repo()
+    tag_repo = get_tag_repo()
+    return CommandServices(command_repository=cmd_repo, tag_repository=tag_repo)
+
+
+@lru_cache(maxsize=1)
+def get_variable_services() -> VariableServices:
+    get_db()
+    var_repo = get_variable_repo()
+    tag_repo = get_tag_repo()
+    return VariableServices(variable_repository=var_repo, tag_repository=tag_repo)
+
+
+@lru_cache(maxsize=1)
+def get_tag_services() -> TagServices:
+    get_db()
+    tag_repo = get_tag_repo()
+    return TagServices(tag_repository=tag_repo)
+
+
+@lru_cache(maxsize=1)
+def get_history_service() -> HistoryService:
+    return HistoryService(
+        repo=get_history_repo(),
+        get_settings=get_settings,
+    )
+
+
+@lru_cache(maxsize=1)
+def get_command_display_field_resolver() -> FieldSelectionResolver:
+    return FieldSelectionResolver(allowed_fields=COMMAND_DISPLAY_FIELDS)
+
+
+@lru_cache(maxsize=1)
+def get_command_search_field_resolver() -> FieldSelectionResolver:
+    return FieldSelectionResolver(allowed_fields=COMMAND_SEARCH_FIELDS)
+
+
+@lru_cache(maxsize=1)
+def get_variable_display_field_resolver() -> FieldSelectionResolver:
+    return FieldSelectionResolver(allowed_fields=VARIABLE_DISPLAY_FIELDS)
+
+
+@lru_cache(maxsize=1)
+def get_variable_search_field_resolver() -> FieldSelectionResolver:
+    return FieldSelectionResolver(allowed_fields=VARIABLE_SEARCH_FIELDS)
+
+
+@lru_cache(maxsize=1)
+def get_tag_display_field_resolver() -> FieldSelectionResolver:
+    return FieldSelectionResolver(allowed_fields=TAG_DISPLAY_FIELDS)
+
+
+@lru_cache(maxsize=1)
+def get_tag_search_field_resolver() -> FieldSelectionResolver:
+    return FieldSelectionResolver(allowed_fields=TAG_SEARCH_FIELDS)