sierra-dev 0.1.0__py3-none-any.whl

sierra/__init__.py

@@ -0,0 +1,118 @@
+"""
+sierra-dev.
+==========
+
+A framework for building and managing invoker scripts that can be used across different nodes in Sierra during any investigation.
+
+# Overview
+--------
+
+This package provides a comprehensive framework for building, compiling, and loading Sierra applications, including abstract base classes, core components, and internal utilities.
+
+# Exposed Components
+-----------------
+
+- `create_error_result`: Function to create an error result.
+- `create_tree_result`: Function to create a tree result.
+- `SierraABC`: Abstract base class for Sierra components.
+- `SierraBuilder`: Base class for building Sierra components.
+- `SierraCompiler`: Base class for compiling Sierra components.
+- `SierraConfig`: Top-level configuration for SIERRA invoker scripts.
+- `SierraCoreObject`: Base class for all Sierra components.
+- `SierraDevelopmentEnvironment`: Environment configuration class for Sierra development.
+- `SierraInvokerBuilder`: Builder for Sierra invoker scripts.
+- `SierraLoader`: Base class for loading Sierra components.
+- `SierraSideloader`: Base class for side-loading Sierra components.
+- `UniversalLogger`: Logger class for logging Sierra events.
+
+# Integration Notes
+-----------------
+
+This package is designed to be used as a foundation for building complex Sierra applications, providing a robust and flexible framework for managing invoker scripts across different nodes.
+"""
+
+import typing
+
+from sierra._about import *
+from sierra.abc import *
+from sierra.client import *
+from sierra.core import *
+from sierra.internal import *
+from sierra.invoker import *
+from sierra.options import *
+
+
+def create_tree_result(
+    results: list[typing.Union[str, dict[str, list[str]]]],
+) -> dict[str, typing.Any]:
+    """
+    Create a Tree type result.
+
+    Parameters
+    ----------
+    results : list[Union[str, dict[str, list[str]]]]
+        The tree results.
+
+    Returns
+    -------
+    TreeResult
+        The formatted tree result.
+    """
+    result: dict[str, typing.Any] = {
+        "type": "Tree",
+        "results": results,
+    }
+    return result
+
+
+def create_network_result(
+    origins: list[str],
+    nodes: list[dict[str, str]],
+    edges: list[dict[str, str]],
+) -> dict[str, str]:
+    """
+    Create a Network type result.
+
+    Parameters
+    ----------
+    origins : list[str]
+        List of origin node IDs.
+    nodes : list[dict[str, str]]
+        List of node definitions.
+    edges : list[dict[str, str]]
+        List of edge definitions.
+
+    Returns
+    -------
+    NetworkResult
+        The formatted network result.
+    """
+    result: dict[str, typing.Any] = {
+        "type": "Network",
+        "origins": origins,
+        "nodes": nodes,
+        "edges": edges,
+    }
+    return result
+
+
+def create_error_result(message: str) -> dict[str, str]:
+    """
+    Create an Error type result.
+
+    Parameters
+    ----------
+    message : str
+        The error message.
+
+    Returns
+    -------
+    ErrorResult
+        The formatted error result.
+    """
+    result: dict[str, typing.Any] = {
+        "type": "Error",
+        "message": message,
+    }
+
+    return result

sierra/__main__.py

@@ -0,0 +1,6 @@
+import sierra._about as sierra_about
+
+
+def cli() -> None:
+    print(f"sierra-dev {sierra_about.__version__}")
+    print(f"Github: {sierra_about.__github__}")

sierra/_about.py

@@ -0,0 +1,34 @@
+import typing
+
+__author__: typing.Final = "Xsyncio"
+__version__: typing.Final = "0.1.0"
+__license__: typing.Final = "MIT"
+__github__: typing.Final = "https://github.com/xsyncio/sierra-dev"
+__description__: typing.Final = "Sierra  is a framework for building and managing invoker scripts that can be used across different nodes in Sierra during any investigation."
+__url__: typing.Final = "https://sierra-dev.readthedocs.io"
+__email__: typing.Final = "xsyncio@gmail.com"
+__copyright__: typing.Final = "Copyright 2022 Xsyncio"
+
+__long_description__: typing.Final = (
+    __description__
+    + """
+Sierra is designed to be as lightweight as possible and is written in pure Python.
+It is intended to be used with the Sierra platform.
+"""
+)
+
+__keywords__: typing.Final = [
+    "sierra",
+    "invoker",
+    "script",
+    "node",
+    "platform",
+    "python",
+    "custom",
+    "command",
+    "argument",
+    "environment",
+    "type",
+    "state",
+    "property",
+]

sierra/abc/__init__.py

@@ -0,0 +1,33 @@
+"""
+Sierra ABCs.
+============
+
+Abstract Base Classes (ABCs) for Sierra Dev components.
+
+# Overview
+--------
+
+This package contains abstract base classes (ABCs) for components of the
+Sierra Dev framework.
+
+# Exposed Components
+-----------------
+
+- `SierraABC`: Abstract base class for Sierra components.
+- `SierraConfig`: Top-level configuration for SIERRA invoker scripts.
+- `SierraInvokerParam`: Parameter description for invoker scripts.
+- `SierraInvokerScript`: Invoker script definition.
+
+"""
+
+from sierra.abc.base import SierraABC
+from sierra.abc.sierra import SierraConfig
+from sierra.abc.sierra import SierraInvokerParam
+from sierra.abc.sierra import SierraInvokerScript
+
+__all__ = [
+    "SierraABC",
+    "SierraConfig",
+    "SierraInvokerParam",
+    "SierraInvokerScript",
+]

sierra/abc/base.py

@@ -0,0 +1,9 @@
+import typing
+
+
+class SierraABC(typing.TypedDict, total=False):
+    """
+    Base class for all Sierra ABCs.
+
+    This class is used to define the structure of Sierra ABCs.
+    """

sierra/abc/sierra.py

@@ -0,0 +1,63 @@
+import typing
+
+import sierra.abc.base as sierra_abc_base
+
+
+class SierraInvokerParam(sierra_abc_base.SierraABC):
+    """
+    Represents a single parameter for an invoker script.
+
+    Attributes
+    ----------
+    Name : str
+        The parameter's name.
+    Description : str | None
+        Human-readable description of the parameter.
+    Type : str
+        The data type of the parameter (e.g., 'STRING', 'FILE').
+    Options : list[str] | None
+        List of flags, such as 'PRIMARY' or 'MANDATORY'.
+    """
+
+    Name: str
+    Type: str
+    Description: str | None
+    Options: typing.Literal["MANDATORY"] | None
+
+
+class SierraInvokerScript(sierra_abc_base.SierraABC):
+    """
+    Represents an invoker script definition.
+
+    Attributes
+    ----------
+    Name : str
+        Unique name of the script.
+    Description : str | None
+        Brief description of the script.
+    Params : list[SierraInvokerParam]
+        List of parameters for the script.
+    Command : str
+        Shell or Python command template, with placeholders for parameters.
+    """
+
+    Name: str
+    Description: str | None
+    Params: list[SierraInvokerParam] | None
+    Command: str | None
+
+
+class SierraConfig(sierra_abc_base.SierraABC):
+    """
+    Top-level configuration for SIERRA invoker scripts.
+
+    Attributes
+    ----------
+    PATHS : list[str] | None
+        Optional list of directories to search for scripts.
+    SCRIPTS : list[SierraInvokerScript]
+        Definitions of all invoker scripts.
+    """
+
+    PATHS: list[str] | None
+    SCRIPTS: list[SierraInvokerScript]

sierra/client.py

@@ -0,0 +1,264 @@
+import importlib.util
+import pathlib
+import typing
+
+import httpx
+
+import sierra.core.builder as sierra_core_builder
+import sierra.core.compiler as sierra_core_compiler
+import sierra.core.environment as sierra_core_environment
+import sierra.core.loader as sierra_core_loader
+import sierra.internal.cache as sierra_internal_cache
+import sierra.internal.errors as sierra_internal_errors
+import sierra.internal.logger as sierra_internal_logger
+import sierra.invoker as sierra_invoker
+
+
+class InvokerWithLoad(typing.Protocol):
+    """
+    Protocol for invoker scripts with a load method.
+
+    Parameters
+    ----------
+    client : SierraDevelopmentClient
+        The client instance to use for loading the invoker script.
+    """
+
+    def load(self, client: "SierraDevelopmentClient") -> None:
+        """
+        Load the invoker script.
+
+        Parameters
+        ----------
+        client : SierraDevelopmentClient
+            The client instance to use for loading the invoker script.
+        """
+        client.logger.log("Loading invoker script", "debug")
+
+
+class ClientParams(typing.TypedDict, total=False):
+    """
+    A typed dictionary for passing client parameters.
+
+    Attributes
+    ----------
+    logger : UniversalLogger, optional
+        The logger instance for capturing client activity.
+    cache : CacheManager, optional
+        The cache manager instance for handling caching operations.
+
+    Notes
+    -----
+    This TypedDict structure is used to encapsulate optional client parameters
+    that can be provided to the SierraDevelopmentClient.
+    """
+
+    logger: sierra_internal_logger.UniversalLogger
+    cache: sierra_internal_cache.CacheManager
+
+
+class SierraDevelopmentClient:
+    def __init__(
+        self,
+        environment_path: pathlib.Path = pathlib.Path.cwd(),
+        environment_name: str = "default_env",
+        **kwargs: typing.Unpack[ClientParams],
+    ) -> None:
+        """
+        Initialize the Sierra Development Client.
+
+        Parameters
+        ----------
+        environment_path : pathlib.Path
+            Path to the root of the Sierra environment.
+        environment_name : str
+            Name of the environment configuration to load.
+        **kwargs : ClientParams
+            Optional: logger and cache manager.
+        """
+        self.logger: sierra_internal_logger.UniversalLogger = kwargs.get(
+            "logger", sierra_internal_logger.UniversalLogger()
+        )
+        self.logger.log("Logger initialized", "debug")
+        self.logger.log(
+            "Starting Sierra Development Client initialization", "info"
+        )
+
+        self.environment: sierra_core_environment.SierraDevelopmentEnvironment = sierra_core_environment.SierraDevelopmentEnvironment(
+            client=self,
+            name=environment_name,
+            path=environment_path,
+        )
+        self.logger.log(
+            f"Environment created: name={self.environment.name}, path={self.environment.path}",
+            "debug",
+        )
+        self.logger.log("Initializing environment...", "debug")
+        self.environment.init()
+        self.logger.log("Environment initialized successfully", "debug")
+
+        self.cache: sierra_internal_cache.CacheManager = kwargs.get(
+            "cache",
+            sierra_internal_cache.CacheManager(
+                cache_dir=self.environment.config_path / "cache"
+            ),
+        )
+        self.logger.log("Cache manager initialized", "debug")
+
+        self.http_client: httpx.Client = httpx.Client(
+            headers={"User-Agent": "Sierra-dev/1.0"}
+        )
+        self.logger.log("HTTP client initialized", "debug")
+
+        self.loader: sierra_core_loader.SierraSideloader = (
+            sierra_core_loader.SierraSideloader(client=self)
+        )
+        self.logger.log("Initializing sideloader", "debug")
+        self.loader.populate()
+        self.logger.log(
+            f"sideloader populated with sources count={len(self.loader.sources)}",
+            "debug",
+        )
+
+        self.invokers: list[sierra_invoker.InvokerScript] = []
+        self.logger.log("Preparing invokers list", "debug")
+
+        self.builder = sierra_core_builder.SierraInvokerBuilder(client=self)
+        self.logger.log("Initializing invoker builder", "debug")
+        self.compiler = sierra_core_compiler.SierraCompiler(client=self)
+        self.logger.log("Initializing compiler", "debug")
+
+        self.logger.log(
+            "Sierra Development Client initialization complete", "info"
+        )
+
+    def load_invoker(self, invoker: "sierra_invoker.InvokerScript") -> None:
+        """
+        Register a single invoker instance with the client.
+
+        Parameters
+        ----------
+        invoker : InvokerScript
+            An instance of an InvokerScript.
+        """
+        if invoker not in self.invokers:
+            self.invokers.append(invoker)
+            self.logger.log(f"Invoker {invoker.name} registered", "debug")
+        else:
+            self.logger.log(
+                f"Invoker {invoker.name} already registered", "warning"
+            )
+
+    def unload_invoker(self, invoker: "sierra_invoker.InvokerScript") -> None:
+        """
+        Unregister a single invoker instance from the client.
+
+        Parameters
+        ----------
+        invoker : InvokerScript
+            An instance of an InvokerScript.
+        """
+        if invoker in self.invokers:
+            self.invokers.remove(invoker)
+            self.logger.log(f"Invoker unregistered: {invoker.name}", "debug")
+        else:
+            self.logger.log(f"Invoker not found: {invoker.name}", "warning")
+
+    def load_invokers_from_scripts(self) -> None:
+        """
+        Automatically discover and load all InvokerScript subclasses
+        from .py files in the environment's scripts directory.
+        """
+        script_dir: pathlib.Path = self.environment.scripts_path.resolve()
+        self.logger.log(
+            f"Loading invokers from directory: {script_dir}", "info"
+        )
+
+        if not script_dir.is_dir():
+            raise sierra_internal_errors.SierraClientPathError(
+                f"scripts directory is not a valid directory: {script_dir}"
+            )
+
+        for file_path in script_dir.iterdir():
+            if not file_path.is_file() or file_path.suffix != ".py":
+                self.logger.log(
+                    f"Skipping non-Python file: {file_path.name}", "debug"
+                )
+                continue
+
+            self.logger.log(f"Processing file: {file_path.name}", "debug")
+            try:
+                self._load_invoker_file(file_path)
+            except Exception as e:
+                self.logger.log(
+                    f"Failed to load invoker from {file_path.name}: {e}",
+                    "error",
+                )
+
+    def _load_invoker_file(
+        self, path_to_invoker: typing.Union[str, pathlib.Path]
+    ) -> None:
+        """
+        Load a Python module containing one or more InvokerScript instances.
+
+        Parameters
+        ----------
+        path_to_invoker : Union[str, Path]
+            Path to the Python file containing the InvokerScript instances.
+
+        Raises
+        ------
+        SierraClientPathError
+            If the file does not exist or is not a Python file.
+        SierraClientLoadError
+            If no InvokerScript instances are found in the module.
+        """
+        path_obj: pathlib.Path = pathlib.Path(path_to_invoker).resolve()
+
+        self.logger.log(f"Importing module from: {path_obj}", "debug")
+
+        if not path_obj.is_file() or path_obj.suffix != ".py":
+            raise sierra_internal_errors.SierraClientPathError(
+                f"Cannot load invoker file: {path_obj}"
+            )
+
+        spec = importlib.util.spec_from_file_location(path_obj.stem, path_obj)
+
+        if not spec or not spec.loader:
+            raise sierra_internal_errors.SierraClientPathError(
+                f"Cannot create spec for module: {path_obj}"
+            )
+
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)  # type: ignore
+        self.logger.log(f"Module imported: {path_obj.name}", "debug")
+
+        found: list[sierra_invoker.InvokerScript] = []
+        for obj in vars(module).values():
+            if isinstance(obj, sierra_invoker.InvokerScript):
+                found.append(obj)
+
+        if not found:
+            raise sierra_internal_errors.SierraClientLoadError(
+                f"No InvokerScript instance found in {path_obj.name}"
+            )
+
+        for inv in found:
+            self.logger.log(f"Registering invoker: {inv.name}", "debug")
+            self.load_invoker(inv)
+            loader = typing.cast("InvokerWithLoad", inv)
+            if hasattr(inv, "load") and callable(loader.load):
+                self.logger.log(f"Executing load() for: {inv.name}", "debug")
+                try:
+                    loader.load(self)
+                    self.logger.log(f"Loaded invoker: {inv.name}", "info")
+                except Exception as err:
+                    self.logger.log(
+                        f"Error during load() of {inv.name}: {err}",
+                        "error",
+                    )
+
+        self.logger.log(
+            f"Finished processing {path_obj.name}, total invokers found: {len(found)}",
+            "debug",
+        )

sierra/core/__init__.py

@@ -0,0 +1,43 @@
+"""
+Sierra Core.
+============
+
+🔩 Core components of the Sierra Dev framework.
+
+# Overview
+--------
+
+This package contains the core components of the Sierra Dev framework, including
+builders, compilers, environments, loaders, and base classes for Sierra objects.
+
+# Exposed Components
+-----------------
+
+- `SierraBuilder`: Base class for building Sierra components.
+- `SierraCompiler`: Base class for compiling Sierra components.
+- [SierraCoreObject](cci:2://file:///home/xsyncio/Downloads/sierra-dev/sierra/core/base.py:14:0-50:9): Base class for all Sierra components.
+- `SierraDevelopmentEnvironment`: Environment configuration class for Sierra development.
+- `SierraInvokerBuilder`: Builder for Sierra invoker scripts.
+- `SierraLoader`: Base class for loading Sierra components.
+- `SierraSideloader`: Base class for side-loading Sierra components.
+
+# Integration Notes
+-----------------
+
+This package is a fundamental part of the Sierra Dev framework, providing the core
+components for building, compiling, and loading Sierra applications.
+"""
+
+from sierra.core.base import SierraCoreObject
+from sierra.core.builder import SierraInvokerBuilder
+from sierra.core.compiler import SierraCompiler
+from sierra.core.environment import SierraDevelopmentEnvironment
+from sierra.core.loader import SierraSideloader
+
+__all__ = [
+    "SierraCompiler",
+    "SierraCoreObject",
+    "SierraDevelopmentEnvironment",
+    "SierraInvokerBuilder",
+    "SierraSideloader",
+]

sierra/core/base.py

@@ -0,0 +1,51 @@
+import typing
+
+if typing.TYPE_CHECKING:
+    import sierra.client as sierra_client
+
+"""
+Module providing the SierraCoreObject base class.
+
+This module defines the SierraCoreObject, which serves as the foundational class
+for all Sierra components, ensuring each component has access to a common
+SierraDevelopmentClient for logging and API interactions.
+"""
+
+
+class SierraCoreObject:
+    """
+    Base class for Sierra core objects.
+
+    Parameters
+    ----------
+    client : SierraDevelopmentClient
+        Client instance used for operations, providing logger and HTTP access.
+    """
+
+    def __init__(
+        self, client: "sierra_client.SierraDevelopmentClient"
+    ) -> None:
+        """
+        Initialize a SierraCoreObject.
+
+        Parameters
+        ----------
+        client : SierraDevelopmentClient
+            The Sierra development client.
+
+        Notes
+        -----
+        Logs each initialization step via the client's logger.
+        """
+        # Assign client instance
+        self.client = client  # type: ignore[name-defined]
+        # Log the start of initialization
+        self.client.logger.log(
+            message=f"Initializing SierraCoreObject with client: {client}",
+            log_type="debug",
+        )
+        # Confirm assignment of client
+        self.client.logger.log(
+            message="SierraCoreObject.client set successfully",
+            log_type="debug",
+        )