cmdbox-cli 1.0.0__py3-none-any.whl

cmdbox/core/fields.py

@@ -0,0 +1,48 @@
+COMMAND_DISPLAY_FIELDS = [
+    "alias",
+    "template",
+    "description",
+    "cwd",
+    "shell",
+    "env",
+    "timeout",
+    "date_created",
+    "last_updated",
+    "used",
+    "last_used",
+]
+COMMAND_SEARCH_FIELDS = [
+    "alias",
+    "template",
+    "description",
+    "date_created",
+    "last_updated",
+    "used",
+    "last_used",
+]
+
+VARIABLE_DISPLAY_FIELDS = [
+    "name",
+    "value",
+    "date_created",
+    "last_updated",
+]
+VARIABLE_SEARCH_FIELDS = [
+    "name",
+    "value",
+    "date_created",
+    "last_updated",
+]
+
+TAG_DISPLAY_FIELDS = [
+    "name",
+    "description",
+    "date_created",
+    "last_updated",
+]
+TAG_SEARCH_FIELDS = [
+    "name",
+    "description",
+    "date_created",
+    "last_updated",
+]

cmdbox/core/paths.py

@@ -0,0 +1,52 @@
+from pathlib import Path
+import os
+import sys
+
+VENDOR = "SomeGuySoftware"
+APP_NAME = "CmdBox"
+
+
+def get_app_data_dir() -> Path:
+    """
+    Gets the application data directory for the current platform.
+
+    This function determines the appropriate location where application data
+    should be stored for the current operating system. The directory varies
+    based on the operating system, ensuring compatibility and proper organization
+    of application data.
+
+    Returns:
+        Path: A `Path` object representing the full path to the application
+        data directory for the current platform.
+    """
+    if sys.platform == "win32":
+        base = Path(os.environ["APPDATA"])
+    elif sys.platform == "darwin":
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = Path.home() / ".local" / "share"
+    return base / VENDOR / APP_NAME
+
+
+APP_DATA_DIR = get_app_data_dir()
+APP_DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def get_log_dir() -> Path:
+    """
+    Retrieves the directory path designated for storing log files.
+
+    This function ensures the existence of the 'logs' directory within the application
+    data directory. If the directory does not exist, it gets created with necessary
+    parent directories.
+
+    Returns:
+        Path: A `Path` object representing the log directory.
+    """
+    log_dir = APP_DATA_DIR / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir
+
+
+def get_log_file_path() -> Path:
+    return get_log_dir() / "cmdbox.log"

cmdbox/database.py

@@ -0,0 +1,65 @@
+import logging
+import os
+from peewee import SqliteDatabase
+
+from cmdbox.core.paths import get_app_data_dir
+
+log = logging.getLogger(__name__)
+
+
+DB_PATH = get_app_data_dir() / "cmdbox.db"
+DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+
+db = SqliteDatabase(None)
+_db_initialized = False
+
+
+def init_database(testing: bool = False) -> None:
+    """
+    Initializes the database connection based on the environment or testing flag.
+
+    This function determines whether to use an in-memory SQLite database for
+    testing purposes or the standard SQLite database file path for production
+    or other environments. The behavior is controlled by the `testing` argument
+    and the `CMDBOX_ENV` environment variable.
+
+    Args:
+        testing (bool | None): A flag to indicate whether to use the testing
+            (in-memory) database. If None, the value is derived from the
+            `CMDBOX_ENV` environment variable. Defaults to None.
+    """
+    global _db_initialized
+    if _db_initialized:
+        return
+    if testing is None:
+        env = os.environ.get("CMDBOX_ENV", "production")
+        testing = env == "testing"
+
+    if testing:
+        db_path = ":memory:"
+    else:
+        db_path = str(DB_PATH)
+    db.init(db_path)
+
+    if not testing:
+        from cmdbox.migrations.runner import ensure_migrated
+
+        ensure_migrated(db_path)
+
+    _db_initialized = True
+    log.debug("Database initialized %s", "in testing mode" if testing else "")
+
+
+def get_db(testing: bool = False) -> SqliteDatabase:
+    init_database(testing)
+    if db.is_closed():
+        db.connect(reuse_if_open=True)
+    return db
+
+
+def ensure_schema() -> None:
+    from cmdbox.models import ALL_MODELS
+
+    _db = get_db()
+    _db.create_tables(ALL_MODELS, safe=True)

cmdbox/exceptions.py

@@ -0,0 +1,10 @@
+class CmdboxError(Exception):
+    """
+    Base class for exceptions in the cmdbox module.
+
+    This custom exception class serves as a base for all exceptions raised
+    within the cmdbox module. It provides a means to handle module-specific
+    errors in a structured manner.
+    """
+
+    pass

cmdbox/init/detect.py

@@ -0,0 +1,82 @@
+import os
+import sys
+from pathlib import Path
+
+import psutil
+
+
+def detect_shell() -> str:
+    """
+    Detect the shell being used in the current operating environment.
+
+    The function identifies the shell by examining the parent process of the current
+    script and its name. On Unix systems, it also checks the `SHELL` environment
+    variable as a fallback. For Windows, it supports shell detection for cmd,
+    PowerShell, and Git Bash.
+
+    Returns:
+        str: The name of the detected shell. If the shell cannot be determined using
+        process information, it falls back to environment-based detection.
+    """
+    parent = psutil.Process(os.getpid()).parent()
+    name = ((parent.name() if parent else "") or "").lower()
+
+    # Windows
+    if name in {"pwsh.exe", "powershell.exe"}:
+        return "powershell"
+    if name == "cmd.exe":
+        return "cmd"
+    if name in {"bash.exe", "git-bash.exe", "msys2.exe"}:
+        return "bash"
+
+    # Unix
+    if name in {"bash", "zsh", "fish"}:
+        return name
+
+    # Fallback
+    p = os.environ.get("SHELL")
+    if p:
+        sh = Path(p).name.lower()
+        if sh in {"bash", "zsh", "fish"}:
+            return sh
+
+    # Default to env detection if everything else fails
+    return detect_shell_env()
+
+
+def detect_shell_env() -> str:
+    """
+    Detects the shell being used on the operating system.
+
+    This function determines the active shell based on environment variables,
+    platform information, and commonly used shell identifiers. It identifies
+    the shell for both Windows and Unix-based systems.
+
+    Returns:
+        str: A string representing the detected shell. Possible values include
+        'bash', 'powershell', 'cmd', 'zsh', and 'fish'. Defaults to 'bash'
+        if unable to determine the specific shell.
+    """
+    if sys.platform.startswith("win"):
+        # Git bash / MSYS
+        if (
+            os.environ.get("MSYSTEM")
+            or os.environ.get("MINGW_PREFIX")
+            or os.environ.get("SHELL")
+        ):
+            return "bash"
+        # Powershell
+        if os.environ.get("PSModulePath") or os.environ.get(
+            "POWERSHELL_DISTRIBUTION_CHANNEL"
+        ):
+            return "powershell"
+        # Default to cmd
+        return "cmd"
+
+    sh = os.environ.get("SHELL")
+    if sh:
+        base = Path(sh).name.lower()
+        if base in {"bash", "zsh", "fish"}:
+            return base
+
+    return "bash"

cmdbox/init/integrations/bash.sh

@@ -0,0 +1,10 @@
+cbe() {
+  local out status
+  out="$(command cb "$@" --emit)"
+  status=$?
+  if [ $status -ne 0 ]; then
+    return $status
+  fi
+  [ -z "$out" ] && return 0
+  eval "$out"
+}

cmdbox/init/integrations/cmd.bat

@@ -0,0 +1,14 @@
+@echo off
+setlocal EnableExtensions EnableDelayedExpansion
+
+set "_tmp=%TEMP%\cmdbox_emit_%RANDOM%%RANDOM%.cmd"
+
+cb %* --emit > "%_tmp%"
+if errorlevel 1 (
+  del "%_tmp%" >nul 2>&1
+  exit /b %errorlevel%
+)
+
+call "%_tmp%"
+del "%_tmp%" >nul 2>&1
+exit /b 0

cmdbox/init/integrations/fish.fish

@@ -0,0 +1,11 @@
+function cbe
+    set -l out (cb cmdbox $argv --emit)
+    set -l status $status
+    if test $status -ne 0
+        return $status
+    end
+    if test -z "$out"
+        return 0
+    end
+    eval $out
+end

cmdbox/init/integrations/powershell.ps1

@@ -0,0 +1,14 @@
+function cbe
+{
+    $out = & cb @args --emit
+    $code = $LASTEXITCODE
+    if ($code -ne 0)
+    {
+        return
+    }
+    if ( [string]::IsNullOrWhiteSpace($out))
+    {
+        return
+    }
+    Invoke-Expression ($out -join "`n")
+}

cmdbox/init/integrations/zsh.sh

@@ -0,0 +1,10 @@
+cbe() {
+  local out status
+  out="$(command cb "$@" --emit)"
+  status=$?
+  if [ $status -ne 0 ]; then
+    return $status
+  fi
+  [ -z "$out" ] && return 0
+  eval "$out"
+}

cmdbox/init/io.py

@@ -0,0 +1,68 @@
+import re
+import shutil
+from pathlib import Path
+from importlib import resources
+
+from cmdbox.logging_setup.log_decorators import log_action
+
+START_MARK = "# >>> cmdbox shell integration >>>"
+END_MARK = "# <<< cmdbox shell integration <<<"
+
+
+def load_integration_text(filename: str) -> str:
+    """
+    Loads a text file from the 'cmdbox.init.integrations' resource directory, reads its contents, and
+    returns the text stripped of trailing whitespace with a newline character appended.
+
+    Args:
+        filename (str): The name of the file to be loaded and read.
+
+    Returns:
+        str: The contents of the specified file as a string, with trailing whitespace removed
+             and a newline character appended at the end.
+    """
+    return (
+        resources.files("cmdbox.init.integrations")
+        .joinpath(filename)
+        .read_text(encoding="utf-8")
+        .rstrip()
+        + "\n"
+    )
+
+
+@log_action(__name__, "upsert_marked_block")
+def upsert_marked_block(profile_path: Path, block_text: str) -> None:
+    """
+    Updates or inserts a marked text block into a given file at the specified path.
+    If the marked block already exists in the file, it is replaced with the provided
+    new content. Otherwise, the block is added to the end of the file. Additionally,
+    a backup of the original file is created if it already exists.
+
+    Args:
+        profile_path (Path): The path to the file where the marked block will be
+            updated or inserted.
+        block_text (str): The content to be added or updated as part of the marked
+            block.
+
+    """
+    profile_path.parent.mkdir(parents=True, exist_ok=True)
+    existing = profile_path.read_text(encoding="utf-8") if profile_path.exists() else ""
+
+    marked = f"{START_MARK}\n{block_text.rstrip()}\n{END_MARK}\n"
+
+    pattern = re.compile(
+        re.escape(START_MARK) + r".*?" + re.escape(END_MARK) + r"\n?",
+        flags=re.DOTALL,
+    )
+
+    if pattern.search(existing):
+        new_text = pattern.sub(marked, existing)
+    else:
+        sep = "\n" if existing and not existing.endswith("\n") else ""
+        new_text = existing + sep + marked
+
+    if profile_path.exists():
+        backup = profile_path.with_suffix(profile_path.suffix + ".bak")
+        shutil.copy2(profile_path, backup)
+
+    profile_path.write_text(new_text, encoding="utf-8")

cmdbox/init/specs.py

@@ -0,0 +1,54 @@
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class ShellSpec:
+    name: str
+    filename: str
+    default_path_fn: Callable[[], Path] | None
+    install_mode: str  # "profile_block" or "write_file" or "wrapper_hint"
+
+
+def default_bashrc() -> Path:
+    return Path.home() / ".bashrc"
+
+
+def default_zshrc() -> Path:
+    return Path.home() / ".zshrc"
+
+
+def default_fish_function() -> Path:
+    return (
+        Path.home() / ".config" / "fish" / "functions" / "cb.fish"
+    )  # TODO: Does this need to be cbe.fish?
+
+
+def default_powershell_profile() -> Path:
+    # Approximation that works for typical pwsh installations
+    # Users can override with --path if needed
+    docs = os.environ.get("USERPROFILE")
+    if not docs:
+        return (
+            Path.home()
+            / "Documents"
+            / "PowerShell"
+            / "Microsoft.PowerShell_profile.ps1"
+        )
+    return Path(docs) / "Documents" / "PowerShell" / "Microsoft.PowerShell_profile.ps1"
+
+
+SHELLS: dict[str, ShellSpec] = {
+    "bash": ShellSpec("bash", "bash.sh", default_bashrc, "profile_block"),
+    "zsh": ShellSpec("zsh", "zsh.sh", default_zshrc, "profile_block"),
+    "fish": ShellSpec("fish", "fish.fish", default_fish_function, "write_file"),
+    "powershell": ShellSpec(
+        "powershell", "powershell.ps1", default_powershell_profile, "profile_block"
+    ),
+    "pwsh": ShellSpec(
+        "pwsh", "powershell.ps1", default_powershell_profile, "profile_block"
+    ),
+    "cmd": ShellSpec("cmd", "cmd.bat", None, "wrapper_hint"),
+}

cmdbox/logging_setup/log_config.py

@@ -0,0 +1,123 @@
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from cmdbox.core.paths import get_log_file_path
+
+LOGGER_NAME = "cmdbox"
+
+
+@dataclass(frozen=True)
+class LogConfig:
+    console_level: int
+    file_enabled: bool
+    file_level: int
+    file_path: Path
+    max_bytes: int
+    backups: int
+
+
+def _level(level_str: str) -> int:
+    s = (level_str or "").upper().strip()
+    return getattr(logging, s, logging.INFO)
+
+
+def build_log_config(
+    settings, *, verbose: bool, debug: bool, file_logs: bool | None
+) -> LogConfig:
+    """
+    Builds and returns a LogConfig instance based on the provided settings and flags.
+
+    This function determines the appropriate logging configuration for the application
+    by evaluating the verbosity, debug settings, and file-based logging preferences. It
+    retrieves logging levels and file configurations from the provided settings.
+
+    Args:
+        settings: Application-specific configuration object containing logging
+            settings such as file size limits and backup count.
+        verbose: Flag indicating whether verbose logging is enabled.
+        debug: Flag indicating whether debug-level logging is enabled.
+        file_logs: Flag indicating whether file-based logging is enabled. If None,
+            it defaults to the settings specified in the application configuration.
+
+    Returns:
+        LogConfig: A fully constructed LogConfig instance containing the logging
+        configuration details, such as console logging level, file logging level,
+        file path, maximum file size, and backup count.
+    """
+    console_level = get_console_level(settings, verbose=verbose, debug=debug)
+
+    file_enabled = get_file_enabled(settings, file_logs=file_logs)
+    file_level = get_file_level(settings, verbose=verbose, debug=debug)
+
+    file_path = get_log_file_path()
+
+    return LogConfig(
+        console_level=console_level,
+        file_enabled=file_enabled,
+        file_level=file_level,
+        file_path=file_path,
+        max_bytes=settings.logging.file.max_bytes,
+        backups=settings.logging.file.backups,
+    )
+
+
+def get_console_level(settings, *, verbose: bool, debug: bool) -> int:
+    """
+    Determines and returns the appropriate logging level for console output.
+
+    Args:
+        settings: Application settings object containing logging configuration.
+        verbose: Flag indicating whether verbose mode is enabled.
+        debug: Flag indicating whether debug mode is enabled.
+
+    Returns:
+        int: Numerical value representing the logging level.
+    """
+    if debug:
+        return logging.DEBUG
+    elif verbose:
+        return logging.INFO
+    else:
+        return _level(settings.logging.console_level)
+
+
+def get_file_enabled(settings, *, file_logs: bool | None) -> bool:
+    """
+    Returns whether file logging is enabled based on the provided settings and optional override.
+
+    Args:
+        settings: Application configuration containing logging settings.
+        file_logs (bool | None): Optional override for enabling or disabling file logging.
+
+    Returns:
+        bool: True if file logging is enabled; otherwise, False.
+    """
+    if file_logs is not None:
+        return file_logs
+    return bool(settings.logging.file.enabled)
+
+
+def get_file_level(settings, *, verbose: bool, debug: bool) -> int:
+    """
+    Determines the appropriate logging level for file-based logging based on the provided settings
+    and debug/verbose flags.
+
+    Args:
+        settings: Configuration settings that include logging level information.
+        verbose: Enables verbose logging if set to True.
+        debug: Enables debug-level logging if set to True.
+
+    Returns:
+        int: The resolved logging level for file-based logging.
+    """
+    if debug:
+        return logging.DEBUG
+    elif verbose:
+        return logging.INFO
+    else:
+        return _level(settings.logging.file.level)
+
+
+def get_logger() -> logging.Logger:
+    return logging.getLogger(LOGGER_NAME)

cmdbox/logging_setup/log_decorators.py

@@ -0,0 +1,40 @@
+import logging
+import time
+from functools import wraps
+
+
+def log_action(
+    module_name: str,
+    action_name: str,
+):
+    """
+    Decorator to log the execution of a function, including the start, end, and elapsed time in milliseconds.
+    Logs will be captured using the specified module name and include details about the specified action name.
+
+    The decorator also logs exceptions if the wrapped function raises one.
+
+    Args:
+        module_name (str): The name of the module to associate with the logger.
+        action_name (str): The name of the action to log.
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            log = logging.getLogger(module_name)
+            start_time = time.perf_counter()
+            log.info("%s start", action_name)
+
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception:
+                log.error("%s failed", action_name)
+                raise
+            finally:
+                elapsed_ms = (time.perf_counter() - start_time) * 1000
+                log.info("%s finished in %.2f ms", action_name, elapsed_ms)
+
+        return wrapper
+
+    return decorator