cmdbox-cli 1.0.0__py3-none-any.whl

cmdbox/services/run_service.py

@@ -0,0 +1,204 @@
+import json
+from typing import Callable
+
+from cmdbox.models import Command
+from cmdbox.repositories.command_repository import CommandRepository
+from cmdbox.repositories.history_repository import HistoryRepository
+from cmdbox.resolve.resolver import Resolver
+from cmdbox.resolve.type_defs import ResolveResult
+from cmdbox.runtime.executor import Executor, RunContext
+from cmdbox.runtime.results import ExecutionResult
+from cmdbox.settings.models import Settings
+
+
+class RunService:
+    """
+    Provides services for executing and previewing commands.
+
+    This class manages the execution of commands and their previews. It interacts with
+    a command repository, a resolver for processing commands, and an executor for
+    executing commands. The `run` method is used to execute a command, while the `preview`
+    method enables retrieving a resolved result of a command without executing it.
+
+    Attributes:
+        repo (CommandRepository): The repository that stores and provides access to
+            command definitions based on their alias.
+        resolver (Resolver): Encapsulates the logic required to resolve a command
+            template into its executable form.
+        executor (Executor): Responsible for executing resolved commands and
+            returning the results.
+    """
+
+    def __init__(
+        self,
+        repo: CommandRepository,
+        resolver: Resolver,
+        executor: Executor,
+        history_repo: HistoryRepository | None = None,
+        get_settings: Callable[[], Settings] | None = None,
+    ) -> None:
+        self._repo = repo
+        self._resolver = resolver
+        self._executor = executor
+        self._history_repo = history_repo
+        self._get_settings = get_settings
+
+    def run(
+        self,
+        command_alias: str,
+        ctx: RunContext | None = None,
+        runtime_vars: dict[str, str] | None = None,
+    ) -> ExecutionResult:
+        """
+        Executes a command based on the given alias.
+
+        This method retrieves a command associated with the provided alias, resolves its
+        template using a resolver, and then executes the resolved command text. Execution
+        context stored on the command (cwd, shell, env, timeout) is merged with any
+        runtime-supplied context, with runtime values taking precedence.
+
+        Args:
+            command_alias (str): The alias for the command to be executed.
+            ctx (RunContext | None): The context for running the command.
+            runtime_vars (dict[str, str] | None): Runtime variables to be used during command execution.
+
+        Returns:
+            ExecutionResult: The result of executing the command.
+        """
+        cmd = self._repo.get_by_alias(command_alias)
+        resolved_cmd = self._resolver.resolve(cmd.template, runtime_vars=runtime_vars)
+        ctx = self.build_context(cmd, ctx)
+        result = self._executor.run(resolved_cmd.text, ctx=ctx)
+        self._repo.record_use(cmd.id)
+        self.record_history(
+            alias=command_alias,
+            template=cmd.template,
+            resolved=resolved_cmd.text,
+            runtime_vars=runtime_vars,
+            exit_code=result.exit_code,
+        )
+        return result
+
+    def preview(
+        self,
+        command_alias: str,
+        runtime_vars: dict[str, str] | None = None,
+        ctx: RunContext | None = None,
+    ) -> tuple[ResolveResult, RunContext | None]:
+        """
+        Retrieves and resolves a command template based on its alias.
+
+        This method takes a command alias, retrieves the associated command template,
+        and resolves it to produce a complete command configuration or data structure.
+        This resolved template is then returned as a `ResolveResult`.
+
+        Args:
+            command_alias (str): The alias of the command to be resolved.
+            runtime_vars (dict[str, str] | None): Runtime variables to be used during command resolution.
+            ctx (RunContext | None): The context in which the command is being executed.
+
+        Returns:
+            tuple[ResolveResult, RunContext | None]: The resolved result of the command template and the effective context.
+        """
+        cmd = self._repo.get_by_alias(command_alias)
+        resolved = self._resolver.resolve(cmd.template, runtime_vars=runtime_vars)
+        effective_ctx = self.build_context(cmd, ctx)
+        return resolved, effective_ctx
+
+    def record_history(
+        self,
+        *,
+        alias: str,
+        template: str,
+        resolved: str,
+        runtime_vars: dict[str, str] | None = None,
+        exit_code: int | None = None,
+    ) -> None:
+        """
+        Records command execution history if the history feature is enabled and
+        properly configured. This function interacts with an underlying
+        repository to store details about the executed command including alias,
+        template, resolved string, runtime variables, and exit code.
+
+        Args:
+            alias (str): The alias or the name of the command executed.
+            template (str): The template string representing the command.
+            resolved (str): The fully resolved string of the executed command.
+            runtime_vars (dict[str, str] | None): Runtime variables used during
+                the execution of the command. Defaults to None.
+            exit_code (int | None): Exit code that indicates the result of the
+                command execution. Defaults to None.
+        """
+        if not self._history_repo or not self._get_settings:
+            return
+        settings = self._get_settings()
+        if not settings.history.enabled:
+            return
+        self._history_repo.record(
+            alias=alias,
+            template=template,
+            resolved=resolved,
+            variables_used=runtime_vars or None,
+            exit_code=exit_code,
+            limit=settings.history.limit_per_command,
+        )
+
+    def collect_missing_vars(
+        self, command_alias: str, runtime_vars: dict[str, str] | None = None
+    ) -> list[str]:
+        cmd = self._repo.get_by_alias(command_alias)
+        missing = self._resolver.collect_missing_vars(
+            cmd.template, runtime_vars=runtime_vars
+        )
+        return missing
+
+    def build_context(
+        self, cmd: Command, runtime_ctx: RunContext | None
+    ) -> RunContext | None:
+        """
+        Constructs a runtime context by merging command-level settings with runtime-level
+        settings. Resolves priority based on input from `runtime_ctx` when available, or
+        falls back to `cmd` for default values. If no significant configuration changes
+        are detected, returns `None`.
+
+        Args:
+            cmd (Command): The command object containing default execution settings, including
+                environment variables, working directory, shell, timeout, and more.
+            runtime_ctx (RunContext | None): An optional runtime context object that may override
+                specific command-level settings, such as environment variables and capture
+                preferences.
+
+        Returns:
+            RunContext | None: Returns a `RunContext` object with the resulting configuration
+            or `None` if no significant changes are produced by the merge.
+        """
+        stored_env = json.loads(cmd.env) if cmd.env else {}
+        runtime_env = getattr(runtime_ctx, "env", None) or {}
+        merged_env = {**stored_env, **runtime_env} or None
+
+        cwd = (runtime_ctx.cwd if runtime_ctx and runtime_ctx.cwd else None) or cmd.cwd
+        shell = (
+            runtime_ctx.shell if runtime_ctx and runtime_ctx.shell else None
+        ) or cmd.shell
+        timeout = (
+            runtime_ctx.timeout
+            if (runtime_ctx and runtime_ctx.timeout is not None)
+            else cmd.timeout
+        )
+
+        capture = runtime_ctx.capture if runtime_ctx else False
+        emit = runtime_ctx.emit if runtime_ctx else False
+        verbose = runtime_ctx.verbose if runtime_ctx else False
+
+        if not any([cwd, shell, merged_env, timeout, capture, emit, verbose]):
+            return None
+
+        return RunContext(
+            cwd=cwd,
+            shell=shell,
+            env=merged_env,
+            timeout=timeout,
+            capture=capture,
+            emit=emit,
+            verbose=verbose,
+        )

cmdbox/services/tag_services.py

@@ -0,0 +1,134 @@
+from typing import Sequence
+
+from cmdbox.models import Tag
+from cmdbox.repositories.tag_repository import TagRepository
+
+
+class TagServices:
+    """
+    Provides services for managing tags.
+
+    The `TagServices` class encapsulates the logic for working with tags,
+    offering methods to create, update, delete, and retrieve tag records.
+    It also supports additional functionality such as searching and listing tags
+    with sorting and limit options.
+
+    Attributes:
+        tag_repository (TagRepository): Repository for managing tag records.
+    """
+
+    def __init__(self, tag_repository: TagRepository):
+        self._repo = tag_repository
+
+    def create_tag(self, name: str, description: str | None = None) -> Tag:
+        """
+        Creates a new tag by storing the provided name and optional description
+        into the database.
+
+        Args:
+            name (str): The name of the tag to be created.
+            description (str | None): An optional description for the tag. Defaults to None.
+
+        Returns:
+            Tag: The created tag record.
+        """
+        return self._repo.create(name=name, description=description)
+
+    def update_tag(self, name_: str, **fields) -> Tag:
+        """
+        Updates an existing tag by its name with new field values.
+
+        Retrieves the tag corresponding to the given name and updates it
+        with the provided fields. The update is performed using the repository.
+
+        Args:
+            name_ (str): The name of the tag to update.
+            **fields: Arbitrary field values to update on the tag.
+
+        Returns:
+            Tag: The updated tag object.
+        """
+        tag = self._repo.get_by_name(name_)
+        return self._repo.update(tag, **fields)
+
+    def delete_tag(self, name: str) -> bool:
+        """
+        Deletes a tag by its name.
+
+        This method removes a tag record from the repository that matches the
+        provided name.
+
+        Args:
+            name: The name of the tag to delete.
+
+        Returns:
+            bool: True if the tag was deleted successfully, False otherwise.
+        """
+        tag = self._repo.get_by_name(name)
+        return self._repo.delete(tag)
+
+    def get_tag(self, name: str) -> Tag:
+        """
+        Retrieves a tag by its name.
+
+        This method fetches a tag object associated with the given name from the
+        repository.
+
+        Args:
+            name (str): The name of the tag to retrieve.
+
+        Returns:
+            Tag: The tag object associated with the given name.
+        """
+        return self._repo.get_by_name(name)
+
+    def get_tag_by_id(self, tag_id: int) -> Tag:
+        tag = self._repo.get_by_id(tag_id)
+        return tag
+
+    def list_tags(
+        self,
+        order_by: str | Sequence[str] = "name",
+        limit: int = 25,
+    ) -> list[Tag]:
+        """
+        Lists tags with sorting and limit options.
+
+        This function fetches a list of tags from the repository. The results can
+        be sorted and limited based on the provided arguments.
+
+        Args:
+            order_by (str | Sequence[str]): Specifies the field(s) to sort the results by.
+                Default is "name".
+            limit (int, optional): The maximum number of tags to return. Default is 25.
+
+        Returns:
+            list[Tag]: A list of tags sorted according to the specified criteria.
+        """
+        return self._repo.list_all(order_by, limit)
+
+    def search(
+        self,
+        query: str,
+        fields: str | Sequence[str] | None = None,
+        limit: int = 25,
+    ) -> list[Tag]:
+        """
+        Searches for tags that match the given query across specified fields.
+
+        This method allows you to perform a search within the data repository for tags
+        that match the provided query string in the specified fields. It returns a list of
+        tags that satisfy the search criteria.
+
+        Args:
+            query (str): The search term used for matching against the repository.
+            fields (str | Sequence[str] | None): The fields to perform the search within. If
+                None, defaults to ("name", "description").
+            limit (int, optional): The maximum number of tags to return. Default is 25.
+
+        Returns:
+            list[Tag]: A list of Tag objects that match the search query.
+        """
+        if not fields:
+            fields = ("name", "description")
+        return self._repo.search(query, fields, limit)

cmdbox/services/variable_services.py

@@ -0,0 +1,224 @@
+from typing import Sequence
+
+from cmdbox.models import Tag, Variable
+from cmdbox.repositories.variable_repository import VariableRepository
+from cmdbox.database import db
+from cmdbox.repositories.results import TagAttachResult, TagDetachResult
+from cmdbox.repositories.tag_repository import TagRepository
+
+
+class VariableServices:
+    """
+    Provides services for managing variables and their associated tags.
+
+    The `VariableServices` class encapsulates the logic for working with variables and
+    tags, offering methods to create, update, delete, and retrieve variable records
+    and their tag associations. It also supports additional functionality such as
+    searching, tagging, and listing variables with filtering and sorting options.
+
+    Attributes:
+        variable_repository (VariableRepository): Repository for managing variable records.
+        tag_repository (TagRepository): Repository for managing tag-related operations.
+    """
+
+    def __init__(
+        self, variable_repository: VariableRepository, tag_repository: TagRepository
+    ):
+        self._repo = variable_repository
+        self._tag_repo = tag_repository
+
+    def create_variable(
+        self,
+        name: str,
+        value: str,
+        tags: list[str] | None = None,
+    ) -> Variable:
+        """
+        Creates a new variable by storing the provided name, value, and optional tags
+        into the database. If tags are provided, they are associated with the created
+        variable.
+
+        Args:
+            name (str): The name of the variable to be created.
+            value (str): The value associated with the variable.
+            tags (list[str] | None): An optional list of tags to associate with the variable.
+                Defaults to None.
+
+        Returns:
+            Variable: The created variable record.
+        """
+        with db.atomic():
+            tags = self._get_tags(tags)
+            var = self._repo.create(name=name, value=value)
+            if tags:
+                self._repo.add_tags(var, tags)
+        return var
+
+    def update_variable(self, name_: str, **fields) -> Variable:
+        """
+        Updates an existing variable by its name with new field values.
+
+        Retrieves the variable corresponding to the given name and updates it
+        with the provided fields. The update is performed using the repository.
+
+        Args:
+            name_ (str): The name of the variable to update.
+            **fields: Arbitrary field values to update on the variable.
+
+        Returns:
+            Variable: The updated variable object.
+        """
+        var = self._repo.get_by_name(name_)
+        return self._repo.update(var, **fields)
+
+    def delete_variable(self, name: str) -> bool:
+        """
+        Deletes a variable by its name.
+
+        This method removes a variable record from the repository that matches the
+        provided name.
+
+        Args:
+            name: The name of the variable to delete.
+
+        Returns:
+            bool: True if the variable was deleted successfully, False otherwise.
+        """
+        var = self._repo.get_by_name(name)
+        return self._repo.delete(var)
+
+    def add_tags(self, name: str, tags: list[str]) -> TagAttachResult:
+        """
+        Adds specified tags to an existing variable name.
+
+        The method retrieves a variable object associated with the given name and
+        applies the provided tags to the variable.
+
+        Args:
+            name (str): The name identifying the variable to which tags are to be
+                attached.
+            tags (list[str]): A list of tags to attach to the variable.
+
+        Returns:
+            TagAttachResult: The result of the tag attachment operation, indicating
+                whether the tags were successfully attached to the variable.
+        """
+        var = self._repo.get_by_name(name)
+        tags = self._get_tags(tags)
+        return self._repo.add_tags(var, tags)
+
+    def remove_tags(self, name: str, tags: list[str]) -> TagDetachResult:
+        """
+        Removes specific tags associated with a variable name.
+
+        This method retrieves a variable by its name and detaches the specified tags
+        from it. The updated tag associations will be handled by the repository.
+
+        Args:
+            name: The unique identifier for the variable to update.
+            tags: A list of tags to be removed from the specified variable.
+
+        Returns:
+            TagDetachResult: An object representing the result of tag detachment.
+        """
+        var = self._repo.get_by_name(name)
+        tags = self._get_tags(tags)
+        return self._repo.remove_tags(var, tags)
+
+    def get_variable(self, name: str) -> Variable:
+        """
+        Retrieves a variable by its name.
+
+        This method fetches a variable object associated with the given name from the
+        repository.
+
+        Args:
+            name (str): The name of the variable to retrieve.
+
+        Returns:
+            Variable: The variable object associated with the given name.
+        """
+        var = self._repo.get_by_name(name)
+        return var
+
+    def get_variable_by_id(self, var_id: int) -> Variable:
+        var = self._repo.get_by_id(var_id)
+        return var
+
+    def list_variables(
+        self,
+        order_by: str | Sequence[str] = "name",
+        tags: Sequence[str] | None = None,
+        limit: int = 25,
+    ) -> list[Variable]:
+        """
+        Lists variables, optionally filtered by tags, with sorting and limit options.
+
+        This function fetches a list of variables, either filtered by specific tags
+        or returning all available variables. The results can be sorted and limited
+        based on the provided arguments.
+
+        Args:
+            order_by (str | Sequence[str]): Specifies the field(s) to sort the results by.
+                Default is "name".
+            tags (Sequence[str], optional): A list of tags to filter the variables. If
+                provided, only variables matching the tags will be included.
+            limit (int, optional): The maximum number of commands to return. Default is 25.
+
+        Returns:
+            list[Variable]: A list of variables matching the provided filters and sorted
+            according to the specified criteria.
+        """
+        if tags:
+            tags = self._get_tags(tags)
+            return self._repo.list_by_tag(tags, order_by, limit)
+        return self._repo.list_all(order_by, limit)
+
+    def search(
+        self,
+        query: str,
+        fields: str | Sequence[str] | None = None,
+        limit: int = 25,
+    ) -> list[Variable]:
+        """
+        Searches for variables that match the given query across specified fields.
+
+        This method allows you to perform a search within the data repository for variables
+        that match the provided query string in the specified fields. It returns a list of
+        variables that satisfy the search criteria.
+
+        Args:
+            query (str): The search term used for matching against the repository.
+            fields (str | Sequence[str] | None): The fields to perform the search within. Defaults
+                to ("name", "value"). If None, no specific fields are targeted.
+            limit (int): The maximum number of results to return. Defaults to 25.
+
+        Returns:
+            list[Variable]: A list of Variable objects that match the search query.
+        """
+        if not fields:
+            fields = ("name", "value")
+        return self._repo.search(query, fields=fields, limit=limit)
+
+    def _get_tags(self, tags: Sequence[str] | None) -> list[Tag]:
+        """
+        Fetches a list of Tag objects based on the provided tag names.
+
+        This method takes a list of tag names as input and retrieves the corresponding
+        Tag objects from the tag repository. The resulting list of Tag objects is then
+        returned.
+
+        Args:
+            tags (list[str] | None): A list of string representing the names of the tags to
+                retrieve.
+
+        Returns:
+            list[Tag]: A list of Tag objects corresponding to the specified tag names.
+        """
+        if tags is None:
+            return []
+        ret_tags: list[Tag] = []
+        for name in tags:
+            tag = self._tag_repo.get_by_name(name)
+            ret_tags.append(tag)
+        return ret_tags

cmdbox/settings/models.py

@@ -0,0 +1,129 @@
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class UIStyle:
+    # Core
+    title: str = "bold"
+    subtitle: str = "dim"
+    muted: str = "dim"
+    border: str = "dim"
+    panel_title: str = "bold"
+
+    # Tables
+    table_header: str = "bold"
+    caption: str = "dim"
+
+    # Key/value panels
+    kv_key: str = "dim"
+    kv_value: str = ""
+
+    # Status
+    success: str = "green"
+    info: str = "cyan"
+    warning: str = "yellow"
+    error: str = "red"
+    debug: str = "dim blue"
+
+    # Code
+    code: str = "cyan"
+    code_inline: str = "cyan"
+    code_block: str = "dim cyan"
+
+    # Entity accents
+    entity_name: str = "bold"
+    entity_id: str = "magenta"
+    entity_count: str = "bold"
+    entity_time: str = "dim"
+
+    # Tags
+    tag_pill: str = "bold white on dark_green"
+    tag_pill_muted: str = "white on grey23"
+
+    # Execution and previews
+    run_command: str = "cyan"
+    run_stdout: str = ""
+    run_stderr: str = "bold red"
+    trace_kind: str = "dim"
+    trace_key: str = "magenta"
+    trace_value: str = "cyan"
+
+
+@dataclass(frozen=True)
+class DefaultFields:
+    command_output: list[str] = field(
+        default_factory=lambda: ["alias", "template", "description"]
+    )
+    command_search: list[str] = field(
+        default_factory=lambda: ["alias", "template", "description"]
+    )
+    variable_output: list[str] = field(default_factory=lambda: ["name", "value"])
+    variable_search: list[str] = field(default_factory=lambda: ["name", "value"])
+    tag_output: list[str] = field(default_factory=lambda: ["name", "description"])
+    tag_search: list[str] = field(default_factory=lambda: ["name", "description"])
+
+
+@dataclass(frozen=True)
+class FieldAliases:
+    alias_mapping: dict[str, list[str]] = field(
+        default_factory=lambda: {
+            "alias": ["a", "al"],
+            "template": ["t", "temp"],
+            "description": ["d", "desc"],
+            "date_created": ["dc", "created"],
+            "last_updated": ["lu", "updated"],
+            "used": ["u"],
+            "last_used": ["lu"],
+        }
+    )
+
+    @property
+    def alias_map(self) -> dict[str, str]:
+        out: dict[str, str] = {}
+        for field_name, aliases in self.alias_mapping.items():
+            for alias in aliases:
+                out[alias.lower()] = field_name
+        return out
+
+
+@dataclass(frozen=True)
+class UiSettings:
+    use_color: bool = True
+    colors: UIStyle = UIStyle()
+
+
+@dataclass(frozen=True)
+class ExecutionSettings:
+    default_shell: str = "auto"  # auto | bash | zsh | pwsh | cmd
+    capture_output: bool = False
+    default_verbose: bool = False
+
+
+@dataclass(frozen=True)
+class LoggingFileSettings:
+    enabled: bool = False
+    level: str = "INFO"
+    max_bytes: int = 1_000_000
+    backups: int = 3
+
+
+@dataclass(frozen=True)
+class LoggingSettings:
+    console_level: str = "WARNING"
+    file: LoggingFileSettings = LoggingFileSettings()
+
+
+@dataclass(frozen=True)
+class HistorySettings:
+    enabled: bool = True
+    limit_per_command: int = 100  # 0 = unlimited
+
+
+@dataclass(frozen=True)
+class Settings:
+    ui: UiSettings = UiSettings()
+    execution_settings: ExecutionSettings = ExecutionSettings()
+    default_fields: DefaultFields = DefaultFields()
+    field_aliases: FieldAliases = FieldAliases()
+    logging: LoggingSettings = LoggingSettings()
+    history: HistorySettings = HistorySettings()