cmdbox-cli 1.0.0__py3-none-any.whl

cmdbox/logging_setup/log_handlers.py

@@ -0,0 +1,94 @@
+import sys
+import re
+import logging
+from logging.handlers import RotatingFileHandler
+
+from cmdbox.logging_setup.log_config import LogConfig, get_logger
+
+
+class SecretRedactionFilter(logging.Filter):
+    """
+    A logging filter to redact sensitive information from log messages.
+
+    This filter is designed to sanitize log messages by redacting sensitive
+    data such as tokens and passwords. The redaction process is applied
+    whenever a log record passes through the filter, ensuring that such
+    sensitive information is not exposed in logs.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if isinstance(record.msg, str):
+            record.msg = self._redact(record.msg)
+        return True
+
+    def _redact(self, s: str) -> str:
+        s = re.sub(r"(?i)\b(token\s*=\s*)(\S+)", r"\1[REDACTED]", s)
+        s = re.sub(r"(?i)\b(password\s*=\s*)(\S+)", r"\1[REDACTED]", s)
+        return s
+
+
+class RunIdFilter(logging.Filter):
+    """
+    A logging filter that appends a unique run identifier to log records.
+
+    Attributes:
+        run_id (str): The identifier for the current run, which will be
+            appended to log records.
+    """
+
+    def __init__(self, run_id: str) -> None:
+        super().__init__()
+        self.run_id = run_id
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.run_id = self.run_id
+        return True
+
+
+def configure_logging(config: LogConfig, run_id: str) -> None:
+    """
+    Configures logging for the application, setting up a logger with both console and file
+    handlers as specified by the provided configuration. Filters and formatters are applied
+    to ensure appropriate logging output.
+
+    Args:
+        config (LogConfig): Configuration object specifying the logging settings, including
+            log levels, file path, maximum file size, and number of backups.
+        run_id (str): Unique identifier for the current run, used to tag log records.
+    """
+    logger = get_logger()
+    logger.setLevel(logging.DEBUG)  # capture everything, then filter
+    logger.propagate = False
+
+    for h in list(logger.handlers):
+        logger.removeHandler(h)
+
+    formatter = logging.Formatter(
+        fmt="%(asctime)s.%(msecs)03d | %(levelname)s | %(run_id)s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d, %H:%M:%S",
+    )
+
+    secret_redaction_filter = SecretRedactionFilter()
+    run_id_filter = RunIdFilter(run_id)
+
+    # Console handler
+    ch = logging.StreamHandler(sys.stderr)
+    ch.setLevel(config.console_level)
+    ch.setFormatter(formatter)
+    ch.addFilter(secret_redaction_filter)
+    ch.addFilter(run_id_filter)
+    logger.addHandler(ch)
+
+    # File handler
+    if config.file_enabled:
+        fh = RotatingFileHandler(
+            filename=str(config.file_path),
+            maxBytes=int(config.max_bytes),
+            backupCount=int(config.backups),
+            encoding="utf-8",
+        )
+        fh.setLevel(config.file_level)
+        fh.setFormatter(formatter)
+        fh.addFilter(secret_redaction_filter)
+        fh.addFilter(run_id_filter)
+        logger.addHandler(fh)

cmdbox/migrations/__init__.py

@@ -0,0 +1 @@
+"""Migration runner package for CmdBox schema versioning."""

cmdbox/migrations/errors.py

@@ -0,0 +1,10 @@
+from cmdbox.exceptions import CmdboxError
+
+
+class MigrationError(CmdboxError):
+    """
+    Exception raised when an error occurs during database migration.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)

cmdbox/migrations/runner.py

@@ -0,0 +1,127 @@
+import importlib
+import logging
+import pkgutil
+from pathlib import Path
+from datetime import datetime
+
+from peewee import SqliteDatabase
+
+from cmdbox.migrations.errors import MigrationError
+
+
+log = logging.getLogger(__name__)
+
+
+def ensure_migrated(db_path: str) -> None:
+    """
+    Ensures the database is migrated to the current version. Connects to the SQLite database,
+    checks the user version, and applies any necessary migrations to bring the database
+    to the current version. If the database version is ahead of the current application
+    version, an error is raised.
+
+    Args:
+        db_path: A string representing the path to the SQLite database file.
+
+    Raises:
+        MigrationError: If the database version is greater than the application's
+            current version, indicating the application is outdated and needs updating.
+    """
+    db = SqliteDatabase(db_path)
+    db.connect()
+    version = get_user_version(db)
+    db.close()
+
+    current_version = get_current_version()
+
+    if version == 0:
+        db.connect()
+        set_user_version(db, current_version)
+        db.close()
+        log.debug("Fresh database stamped at v%d", current_version)
+        return
+
+    if version == current_version:
+        return
+
+    if version > current_version:
+        raise MigrationError(
+            f"Database version {version} is ahead of the application (v{current_version}). Please update CmdBox."
+        )
+
+    migrations = load_migrations()
+    path = Path(db_path)
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+    for v in range(version, current_version):
+        migrate(v, path, migrations, timestamp)
+
+
+def migrate(version: int, path: Path, migrations: dict, timestamp: str) -> None:
+    """
+    Migrates a database from one version to the next using the provided migration mapping.
+
+    Args:
+        version (int): The current version of the database.
+        path (Path): The file path of the database to migrate.
+        migrations (dict): A dictionary where keys are version numbers and values are callable
+            migration functions. Each function must accept the current database path and the
+            path to the new database as string arguments.
+        timestamp (str): A timestamp used for creating backups.
+
+    Raises:
+        MigrationError: If no migration function exists for the current version.
+    """
+    if version not in migrations:
+        raise MigrationError(
+            f"No migration found for v{version} to v{version + 1}. The installation may be corrupt."
+        )
+
+    new_path = path.parent / (path.name + ".new")
+
+    log.info("Migrating database v%d -> v%d...", version, version + 1)
+    migrations[version](str(path), str(new_path))
+
+    new_db = SqliteDatabase(str(new_path))
+    new_db.connect()
+    set_user_version(new_db, version + 1)
+    new_db.close()
+
+    backup_db(path, version, timestamp)
+    new_path.rename(path)
+
+    log.info("Migration to v%d complete.", version + 1)
+
+
+def load_migrations() -> dict:
+    import cmdbox.migrations as migrations_pkg
+
+    migrations = {}
+    for _, name, _ in pkgutil.iter_modules(migrations_pkg.__path__):
+        if not (name.startswith("m") and name[1:].isdigit()):
+            continue
+        module = importlib.import_module(f"cmdbox.migrations.versions.{name}")
+        migrations[module.VERSION] = module.migrate
+    return migrations
+
+
+def get_current_version() -> int:
+    migrations = load_migrations()
+    return max(migrations.keys(), default=1)
+
+
+def get_user_version(db: SqliteDatabase) -> int:
+    return db.execute_sql("PRAGMA user_version").fetchone()[0]
+
+
+def set_user_version(db: SqliteDatabase, version: int) -> None:
+    db.execute_sql(f"PRAGMA user_version = {version}")
+
+
+def backup_db(db_path: Path, version: int, timestamp: str) -> Path:
+    backup_dir = db_path.parent / "backups"
+    backup_dir.mkdir(exist_ok=True)
+    bak_path = backup_dir / f"{db_path.stem}_v{version}_{timestamp}.bak"
+    db_path.rename(bak_path)
+    log.debug("Backed up v%d database to %s", version, bak_path.name)
+    return bak_path

cmdbox/models.py

@@ -0,0 +1,165 @@
+from datetime import datetime
+
+from peewee import (
+    Model,
+    CharField,
+    IntegerField,
+    DateTimeField,
+    TextField,
+    ForeignKeyField,
+)
+from cmdbox.database import db
+
+
+class BaseModel(Model):
+    """
+    BaseModel serves as the foundation for database models.
+
+    This class extends the 'Model' class from the Peewee library, providing a
+    base for all database models within the application. It centralizes the
+    database connection, ensuring consistency across all derived models.
+
+    Attributes:
+        Meta (class): Configuration for the database connection, linking models
+                      to the shared database instance.
+    """
+
+    class Meta:
+        database = db
+
+
+class Command(BaseModel):
+    """
+    Represents a command model.
+
+    This class provides a structure for storing and managing command-related data,
+    including an alias for the command, its template, timestamps for its creation
+    and last update, and a counter for how many times the command has been used.
+
+    Attributes:
+        alias (CharField): Unique identifier for the command.
+        template (CharField): The associated template string for the command.
+        description (CharField): A description of the command and what it does.
+        cwd (CharField): The current working directory for the command execution.
+        shell (CharField): The shell to use for command execution.
+        env (TextField): Environment variables to set for the command execution.
+        timeout (IntegerField): Number of seconds before the process is killed.
+        date_created (DateTimeField): Timestamp indicating when the command was created.
+        last_updated (DateTimeField): Timestamp indicating when the command was last updated.
+        used (IntegerField): Counter representing how many times the command has been used.
+        last_used (DateTimeField): Timestamp indicating when the command was last used.
+    """
+
+    alias = CharField(unique=True)
+    template = TextField()
+    description = TextField(null=True, default=None)
+    cwd = CharField(null=True, default=None)
+    shell = CharField(null=True, default=None)
+    env = TextField(null=True, default=None)
+    timeout = IntegerField(null=True, default=None)
+    date_created = DateTimeField(default=datetime.now)
+    last_updated = DateTimeField(default=datetime.now)
+    used = IntegerField(default=0)
+    last_used = DateTimeField(null=True, default=None)
+
+
+class Variable(BaseModel):
+    """
+    Represents a variable model.
+
+    A variable model is a key-value pair that can be stored and recalled in commands
+    and other variables.
+
+    Attributes:
+        name (CharField): The unique name of the configuration variable.
+        value (CharField): The value associated with the configuration variable.
+    """
+
+    name = CharField(unique=True)
+    value = CharField()
+    date_created = DateTimeField(default=datetime.now)
+    last_updated = DateTimeField(default=datetime.now)
+
+
+class Tag(BaseModel):
+    """
+    Represents a Tag model with attributes for tagging, description, and timestamps.
+
+    This class is designed to store tag information as a name and description to allow
+    users to organize their commands and variables into categories and to give them a
+     convenient way to search for and filter them later.
+
+    Attributes:
+        name (CharField): A unique name identifier for the tag.
+        description (TextField): A detailed textual description of the tag.
+        date_created (DateTimeField): The timestamp indicating when the tag was created.
+        last_updated (DateTimeField): The timestamp indicating the last update for the tag.
+    """
+
+    name = CharField(unique=True)
+    description = TextField(null=True, default=None)
+    date_created = DateTimeField(default=datetime.now)
+    last_updated = DateTimeField(default=datetime.now)
+
+
+class CommandTag(BaseModel):
+    """
+    Represents the relationship between commands and tags.
+
+    This class is used as an intermediary table to establish a many-to-many
+    relationship between a command and a tag.
+
+    Attributes:
+        command (ForeignKeyField): Refers to a command associated with a tag.
+        tag (ForeignKeyField): Refers to a tag associated with a command.
+        date_created (DateTimeField): DateTimeField indicating when the relationship was created.
+    """
+
+    command = ForeignKeyField(Command, backref="tags", on_delete="CASCADE")
+    tag = ForeignKeyField(Tag, backref="commands", on_delete="CASCADE")
+    date_created = DateTimeField(default=datetime.now)
+
+    class Meta:
+        indexes = ((("command", "tag"), True),)
+
+
+class VariableTag(BaseModel):
+    """
+    Represents a many-to-many relationship between Variable and Tag models.
+
+    This class serves as an intermediary table to establish a many-to-many relationship
+    between a variable and a tag.
+
+    Attributes:
+        variable: (ForeignKeyField) Refers to a variable associated with a tag.
+        tag: (ForeignKeyField) Refers to a tag associated with a variable.
+        date_created (DateTimeField): DateTimeField indicating when the relationship was created.
+    """
+
+    variable = ForeignKeyField(Variable, backref="tags", on_delete="CASCADE")
+    tag = ForeignKeyField(Tag, backref="variables", on_delete="CASCADE")
+    date_created = DateTimeField(default=datetime.now)
+
+    class Meta:
+        indexes = ((("variable", "tag"), True),)
+
+
+class CommandHistory(BaseModel):
+
+    id = TextField(primary_key=True)  # uuid4().hex - 32 char, no dashes
+    alias = CharField()  # alias as invoked, not a FK
+    template = TextField()  # raw template at time of run
+    resolved = TextField()  # fully resolved command string
+    variables_used = TextField(null=True)  # JSON: {"name": "Homer"} or null
+    exit_code = IntegerField(null=True)
+    ran_at = DateTimeField(default=datetime.now)
+
+    class Meta:
+        table_name = "command_history"
+        indexes = (
+            (("alias",), False),
+            (("ran_at",), False),
+        )
+
+
+ALL_MODELS = [Command, Variable, Tag, CommandTag, VariableTag, CommandHistory]

cmdbox/repositories/base_repository.py

@@ -0,0 +1,181 @@
+from typing import Sequence, Generic, TypeVar, Type
+
+from peewee import Model, fn, IntegrityError, Node
+
+M = TypeVar("M", bound=Model)
+
+
+class BaseRepository(Generic[M]):
+    model: Type[M]
+
+    def _search(
+        self,
+        query: str,
+        secondary_ordering: str,
+        fields: str | Sequence[str] | None = None,
+        limit: int = 25,
+    ) -> list[M]:
+        """
+        Searches for commands matching the given query across specified fields.
+
+        This function performs a case-insensitive search for the query in the specified
+        fields of the Command model. It calculates a relevance score for each match
+        based on the position of the query within the fields and sorts the results by
+        relevance.  Relevance is determined by a weighted score with the highest weight
+        given to most occurrences and the second part of the score given to how early
+        the search term occurs in the field.
+
+        Args:
+            query (str): The search query to match in the specified fields.
+            secondary_ordering (str): The field to sort the results by, after relevance.
+            fields (str | Sequence[str] | None): The fields to search within. By
+                default, searches within "name" and "description". Can be a single field
+                name as a string or a sequence of field names.
+            limit (int): The maximum number of results to return. Default is 25.
+
+        Returns:
+            list[Command]: A list of Command objects matching the search query, sorted
+                by relevance.
+
+        Raises:
+            ValueError: If any provided field does not exist on the Command model.
+        """
+        if not query:
+            return []
+        if isinstance(fields, str):
+            fields = self._get_sequence(fields)
+        if fields is None or len(fields) == 0:
+            return []
+        or_clauses = []
+        relevance_parts = []
+        query_lower = query.lower()
+        for field_name in fields:
+            if not hasattr(self.model, field_name) or field_name == "":
+                raise ValueError(f"Invalid field: {field_name}")
+            field = getattr(self.model, field_name)
+            or_clauses.append(fn.LOWER(field).contains(query_lower))
+            first_pos = fn.INSTR(fn.lower(field), query_lower)
+            occurrences = (
+                fn.LENGTH(field) - fn.LENGTH(fn.REPLACE(field, query_lower, ""))
+            ) / len(query_lower)
+            score = (occurrences * 1000) - first_pos
+            relevance_parts.append(score)
+
+        condition = or_clauses[0]
+        for clause in or_clauses[1:]:
+            condition |= clause
+
+        if len(relevance_parts) > 1:
+            relevance = fn.MIN(*relevance_parts).alias("relevance")
+        else:
+            relevance = relevance_parts[0].alias("relevance")
+
+        query_obj = (
+            self.model.select(self.model, relevance)
+            .where(condition)
+            .order_by(
+                relevance.desc(),
+                getattr(self.model, secondary_ordering),
+            )
+            .limit(limit)
+        )
+        return list(query_obj)
+
+    def _resolve_order_token(self, token: str) -> Node:
+        """
+        Resolves the ordering token for determining the sorting order of a field.
+
+        This method takes an ordering token, identifies whether the sorting is
+        ascending or descending, and ensures the token corresponds to a valid
+        model attribute for sorting.
+
+        Args:
+            token (str): The ordering token indicating the field for sorting. A
+                token starting with '-' indicates descending sort, otherwise it
+                is ascending. The token must correspond to a valid attribute
+                in `self.model`.
+
+        Returns:
+            Model: An object representing the ordering of the specified field
+                in ascending or descending order.
+
+        Raises:
+            ValueError: If the token is empty or if it references an invalid
+                field in the model.
+        """
+        if not token:
+            raise ValueError("Empty order_by token.")
+        desc = token.startswith("-")
+        field_name = token[1:] if desc else token
+        try:
+            field = getattr(self.model, field_name)
+        except AttributeError:
+            raise ValueError(f"Invalid order_by field: {token}")
+        return field.desc() if desc else field.asc()
+
+    def _resolve_ordering(self, order_by: str | Sequence[str]) -> Sequence[Node]:
+        """
+        Resolves ordering tokens based on the specified order_by input.
+
+        This method processes the input order_by parameter, which could either
+        be a single string of comma-separated tokens or a sequence of strings.
+        It ensures the tokens are parsed and resolved appropriately, returning a
+        sequence of resolved models.
+
+        Args:
+            order_by: A string containing comma-separated tokens, or a sequence
+                of strings representing ordering keys.
+
+        Returns:
+            Sequence[Model]: A sequence of resolved models based on the specified
+            ordering tokens.
+
+        Raises:
+            ValueError: If the order_by sequence is empty.
+        """
+        tokens = self._get_sequence(order_by)
+        if not tokens:
+            raise ValueError("Empty order_by sequence.")
+        return [self._resolve_order_token(token) for token in tokens]
+
+    def _get_sequence(self, items: str | Sequence[str]) -> list[str]:
+        """
+        Processes a string or sequence of strings into a list of stripped strings.
+
+        If the input is a single string, it is split by commas, and whitespace around each
+        split item is stripped. If the input is already a sequence of strings, it is converted
+        into a list without any modifications.
+
+        Args:
+            items (str | Sequence[str]): A string to be split into a list of strings or an
+                existing sequence of strings.
+
+        Returns:
+            list[str]: A list of processed strings.
+
+        Raises:
+            ValueError: If the input is neither a string nor a sequence of strings.
+        """
+        if isinstance(items, str):
+            return [item.strip() for item in items.split(",") if item.strip()]
+        else:
+            return [item.strip() for item in items if item.strip()]
+
+    def _is_unique_name_violation(self, exc: IntegrityError) -> bool:
+        """
+        Checks if the exception indicates a unique constraint violation.
+
+        This method analyzes the provided IntegrityError to determine if the
+        error was caused by a UNIQUE constraint violation on a field of the
+        database table associated with the model.
+
+        Args:
+            exc (IntegrityError): The IntegrityError exception to be checked.
+
+        Returns:
+            bool: True if the exception indicates a unique constraint violation;
+            otherwise, False.
+        """
+        msg = str(exc)
+        table = self.model._meta.table_name
+        return "UNIQUE constraint failed" in msg and f"{table}.name" in msg