cave-cli 3.5.0__py3-none-any.whl

cave_cli/utils/env.py

@@ -0,0 +1,267 @@
+import getpass
+import re
+import secrets
+import string
+from pathlib import Path
+
+from cave_cli.utils.cache import prompt_cached_entry, load_entries, save_entry
+from cave_cli.utils.constants import (
+    CURRENT_ENV_VARIABLES,
+    RETIRED_ENV_VARIABLES,
+)
+from cave_cli.utils.logger import logger
+
+
+def parse_env(path: str) -> dict[str, str]:
+    """
+    Usage:
+
+    - Parses a .env file into a dictionary of key-value pairs
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The path to the .env file
+
+    Returns:
+
+    - ``env_vars``:
+        - Type: dict[str, str]
+        - What: A dictionary mapping variable names to their values
+
+    Notes:
+
+    - Handles ``KEY=VALUE``, ``KEY='VALUE'``, and ``KEY="VALUE"`` formats
+    - Ignores blank lines and lines starting with ``#``
+    """
+    env_vars: dict[str, str] = {}
+    p = Path(path)
+    if not p.is_file():
+        return env_vars
+    for line in p.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if (value.startswith("'") and value.endswith("'")) or (
+            value.startswith('"') and value.endswith('"')
+        ):
+            value = value[1:-1]
+        env_vars[key] = value
+    return env_vars
+
+
+def set_env_value(path: str, key: str, value: str) -> None:
+    """
+    Usage:
+
+    - Sets or replaces a variable's value in a .env file
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The path to the .env file
+
+    - ``key``:
+        - Type: str
+        - What: The variable name to set
+
+    - ``value``:
+        - Type: str
+        - What: The value to assign
+    """
+    p = Path(path)
+    lines = p.read_text().replace("\r\n", "\n").replace("\r", "\n").splitlines()
+    pattern = re.compile(rf"^{re.escape(key)}\s*=")
+    replaced = False
+    for i, line in enumerate(lines):
+        if pattern.match(line):
+            lines[i] = f"{key}='{value}'"
+            replaced = True
+            break
+    if not replaced:
+        lines.append(f"{key}='{value}'")
+    p.write_text("\n".join(lines) + "\n", newline="\n")
+
+
+def validate_env(path: str) -> list[str]:
+    """
+    Usage:
+
+    - Validates a .env file has all required variables and no retired ones
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The path to the .env file
+
+    Returns:
+
+    - ``errors``:
+        - Type: list[str]
+        - What: A list of error messages. Empty if valid.
+    """
+    errors: list[str] = []
+    env_vars = parse_env(path)
+    for var in CURRENT_ENV_VARIABLES:
+        if var not in env_vars:
+            errors.append(
+                f"The env variable '{var}' is missing "
+                "from the '.env' file."
+            )
+    for var in RETIRED_ENV_VARIABLES:
+        if var in env_vars:
+            errors.append(
+                f"The env variable '{var}' is retired and "
+                "should be removed from the '.env' file."
+            )
+    return errors
+
+
+def upgrade_env(env_path: str, template_path: str) -> None:
+    """
+    Usage:
+
+    - Upgrades the STATIC_APP_URL_PATH in .env from a template's example.env
+
+    Requires:
+
+    - ``env_path``:
+        - Type: str
+        - What: The path to the app's .env file
+
+    - ``template_path``:
+        - Type: str
+        - What: The path to the cloned template directory
+    """
+    logger.info("Upgrading .env...")
+    example_env = parse_env(str(Path(template_path) / "example.env"))
+    new_url_path = example_env.get("STATIC_APP_URL_PATH", "")
+    if new_url_path:
+        set_env_value(env_path, "STATIC_APP_URL_PATH", new_url_path)
+    logger.info("Done")
+
+
+def generate_password(length: int = 16) -> str:
+    alphabet = string.ascii_letters + string.digits
+    return "".join(secrets.choice(alphabet) for _ in range(length))
+
+
+def prompt_password(prompt: str) -> str:
+    while True:
+        password = getpass.getpass(prompt)
+        if not password:
+            password = generate_password()
+            return password
+        confirm = getpass.getpass("Retype password to confirm: ")
+        if password == confirm:
+            return password
+        print("Passwords didn't match. Please try again")
+
+
+def create_env_interactive(
+    app_name: str,
+    env_path: str,
+    template_path: str,
+    docker_secret_key: str | None = None,
+) -> None:
+    """
+    Usage:
+
+    - Interactively creates a .env file for a new CAVE app
+
+    Requires:
+
+    - ``app_name``:
+        - Type: str
+        - What: The name of the app being created
+
+    - ``env_path``:
+        - Type: str
+        - What: The path where the .env file will be written
+
+    - ``template_path``:
+        - Type: str
+        - What: The path to the example.env template
+
+    Optional:
+
+    - ``docker_secret_key``:
+        - Type: str | None
+        - What: A Django secret key generated via Docker
+        - Default: None (generates locally with secrets module)
+    """
+    p = Path(env_path)
+    template = Path(template_path)
+    if template.is_file():
+        content = template.read_text().replace("\r\n", "\n").replace("\r", "\n")
+        p.write_text(content, newline="\n")
+    elif p.is_file():
+        pass
+    else:
+        p.touch()
+
+    secret_key = docker_secret_key or secrets.token_urlsafe(50)
+    set_env_value(env_path, "SECRET_KEY", secret_key)
+
+    logger.header("Set up your new app environment (.env) variables:")
+
+    logger.info(
+        "If you want to use a globe view or mapbox maps, "
+        "you will need a valid Mapbox Token."
+    )
+    logger.info(
+        "This is not required, but will allow you to use "
+        "the full functionality of the app."
+    )
+    logger.info(
+        "Mapbox tokens can be created by making an account "
+        "on 'https://mapbox.com'"
+    )
+
+    try:
+        use_mapbox = input("Would you like to use Mapbox? [y/N] ")
+    except (EOFError, KeyboardInterrupt):
+        use_mapbox = "n"
+
+    if use_mapbox.strip().lower() in ("y", "yes"):
+        token = prompt_cached_entry(
+            name="mapbox_tokens",
+            prompt_new="Enter your Mapbox Public Token: ",
+            prompt_label="Label for this token (e.g. work, personal): ",
+            mask=True,
+        )
+        if token:
+            set_env_value(env_path, "MAPBOX_TOKEN", token)
+    else:
+        logger.info("Mapbox skipped")
+
+    default_email = f"{app_name}@example.com"
+    print()
+    email = prompt_cached_entry(
+        name="admin_emails",
+        prompt_new="Enter an admin email",
+        prompt_label="Label for this email (e.g. work, personal): ",
+        default=default_email,
+    )
+    if not email:
+        email = default_email
+    set_env_value(env_path, "DJANGO_ADMIN_EMAIL", email)
+
+    print()
+    admin_password = prompt_password(
+        "Please input an admin password. "
+        "Leave blank to randomly generate one: "
+    )
+    set_env_value(env_path, "DJANGO_ADMIN_PASSWORD", admin_password)
+
+    db_password = generate_password()
+    set_env_value(env_path, "DATABASE_PASSWORD", db_password)
+    print()

cave_cli/utils/git.py

@@ -0,0 +1,240 @@
+import subprocess
+
+from cave_cli.utils.subprocess import run, run_and_log
+
+
+def clone(
+    url: str,
+    dest: str,
+    branch: str | None = None,
+    single_branch: bool = True,
+) -> bool:
+    """
+    Usage:
+
+    - Clones a git repository
+
+    Requires:
+
+    - ``url``:
+        - Type: str
+        - What: The repository URL to clone
+
+    - ``dest``:
+        - Type: str
+        - What: The destination directory
+
+    Optional:
+
+    - ``branch``:
+        - Type: str | None
+        - What: A specific branch or tag to clone
+        - Default: None (clones the default branch)
+
+    - ``single_branch``:
+        - Type: bool
+        - What: Whether to clone only the specified branch
+        - Default: True
+
+    Returns:
+
+    - ``success``:
+        - Type: bool
+        - What: True if the clone succeeded, False otherwise
+    """
+    cmd = ["git", "clone"]
+    if branch:
+        cmd.extend(["-b", branch])
+    if single_branch:
+        cmd.append("--single-branch")
+    cmd.extend([url, dest])
+    result = run_and_log(cmd)
+    return result.returncode == 0
+
+
+def init(path: str) -> None:
+    """
+    Usage:
+
+    - Initializes a new git repository
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The directory to initialize
+    """
+    run_and_log(["git", "init"], cwd=path)
+
+
+def add(path: str, files: list[str] | None = None) -> None:
+    """
+    Usage:
+
+    - Stages files in the git repository
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The repository directory
+
+    Optional:
+
+    - ``files``:
+        - Type: list[str] | None
+        - What: Specific files to stage
+        - Default: None (stages all files)
+    """
+    cmd = ["git", "add"]
+    cmd.extend(files or ["."])
+    run_and_log(cmd, cwd=path)
+
+
+def commit(path: str, message: str) -> None:
+    """
+    Usage:
+
+    - Creates a git commit
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The repository directory
+
+    - ``message``:
+        - Type: str
+        - What: The commit message
+    """
+    run_and_log(["git", "commit", "-m", message], cwd=path)
+
+
+def branch_rename(path: str, name: str) -> None:
+    """
+    Usage:
+
+    - Renames the current branch
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The repository directory
+
+    - ``name``:
+        - Type: str
+        - What: The new branch name
+    """
+    run_and_log(["git", "branch", "-M", name], cwd=path)
+
+
+def fetch(path: str) -> None:
+    """
+    Usage:
+
+    - Fetches from the remote
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The repository directory
+    """
+    run_and_log(["git", "fetch"], cwd=path)
+
+
+def checkout(path: str, ref: str) -> None:
+    """
+    Usage:
+
+    - Checks out a branch or tag
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The repository directory
+
+    - ``ref``:
+        - Type: str
+        - What: The branch, tag, or commit to check out
+    """
+    run_and_log(["git", "checkout", ref], cwd=path)
+
+
+def pull(path: str) -> None:
+    """
+    Usage:
+
+    - Pulls from the remote
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The repository directory
+    """
+    run_and_log(["git", "pull"], cwd=path)
+
+
+def ls_remote_tags(url: str) -> list[str]:
+    """
+    Usage:
+
+    - Lists remote tags for a git repository
+
+    Requires:
+
+    - ``url``:
+        - Type: str
+        - What: The repository URL
+
+    Returns:
+
+    - ``tags``:
+        - Type: list[str]
+        - What: A sorted list of tag names
+    """
+    result = run(["git", "ls-remote", "--tags", url])
+    tags: list[str] = []
+    if result.returncode != 0 or not result.stdout:
+        return tags
+    for line in result.stdout.strip().splitlines():
+        parts = line.split("refs/tags/")
+        if len(parts) == 2:
+            tag = parts[1].rstrip("^{}")
+            if tag and tag not in tags and not tag.endswith("^{}"):
+                tags.append(tag)
+    return tags
+
+
+def ls_remote_heads(url: str) -> list[str]:
+    """
+    Usage:
+
+    - Lists remote branch heads for a git repository
+
+    Requires:
+
+    - ``url``:
+        - Type: str
+        - What: The repository URL
+
+    Returns:
+
+    - ``branches``:
+        - Type: list[str]
+        - What: A sorted list of branch names
+    """
+    result = run(["git", "ls-remote", "--heads", url])
+    branches: list[str] = []
+    if result.returncode != 0 or not result.stdout:
+        return branches
+    for line in result.stdout.strip().splitlines():
+        parts = line.split("refs/heads/")
+        if len(parts) == 2:
+            branch = parts[1].strip()
+            if branch:
+                branches.append(branch)
+    return branches

cave_cli/utils/logger.py

@@ -0,0 +1,77 @@
+import sys
+
+
+class CaveLogger:
+    """
+    Usage:
+
+    - Multi-level logger matching the bash CLI's DEBUG/INFO/WARN/ERROR/SILENT behavior
+
+    Notes:
+
+    - Output goes to stderr in the format ``LEVEL: message``
+    - Module-level singleton ``logger`` is used throughout the package
+    """
+
+    LEVELS: dict[str, int] = {
+        "DEBUG": 0,
+        "INFO": 1,
+        "WARN": 2,
+        "ERROR": 3,
+        "SILENT": 4,
+    }
+
+    def __init__(self, level: str = "INFO") -> None:
+        self.set_level(level)
+
+    def set_level(self, level: str) -> None:
+        """
+        Usage:
+
+        - Sets the minimum log level for output
+
+        Requires:
+
+        - ``level``:
+            - Type: str
+            - What: One of DEBUG, INFO, WARN, ERROR, SILENT
+        """
+        level = level.upper()
+        if level not in self.LEVELS:
+            raise ValueError(
+                f"Invalid log level {level!r}. "
+                f"Must be one of: {list(self.LEVELS.keys())}"
+            )
+        self._level = self.LEVELS[level]
+
+    def log(self, message: str, level: str) -> None:
+        if self.LEVELS.get(level, 0) >= self._level:
+            sys.stderr.write(f"{level}: {message}\n")
+            sys.stderr.flush()
+
+    def debug(self, message: str) -> None:
+        self.log(message, "DEBUG")
+
+    def info(self, message: str) -> None:
+        self.log(message, "INFO")
+
+    def warn(self, message: str) -> None:
+        self.log(message, "WARN")
+
+    def error(self, message: str) -> None:
+        self.log(message, "ERROR")
+
+    def header(self, text: str) -> None:
+        """
+        Usage:
+
+        - Prints a header block with separator lines at INFO level
+        """
+        from cave_cli.utils.constants import CHAR_LINE
+
+        self.info(CHAR_LINE)
+        self.info(text)
+        self.info(CHAR_LINE)
+
+
+logger = CaveLogger()

cave_cli/utils/net.py

@@ -0,0 +1,85 @@
+import re
+import socket
+
+from cave_cli.utils.constants import IP_PORT_RE
+
+
+def is_port_available(port: int) -> bool:
+    """
+    Usage:
+
+    - Checks if a local TCP port is available for binding
+
+    Requires:
+
+    - ``port``:
+        - Type: int
+        - What: The port number to check
+
+    Returns:
+
+    - ``available``:
+        - Type: bool
+        - What: True if the port is available, False if in use
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            s.bind(("0.0.0.0", port))
+            return True
+        except OSError:
+            return False
+
+
+def find_open_port(start: int = 8000) -> int:
+    """
+    Usage:
+
+    - Finds the next available TCP port starting from the given port
+
+    Optional:
+
+    - ``start``:
+        - Type: int
+        - What: The port number to start searching from
+        - Default: 8000
+
+    Returns:
+
+    - ``port``:
+        - Type: int
+        - What: The first available port found
+    """
+    port = start
+    while port < 65535:
+        if is_port_available(port):
+            return port
+        port += 1
+    raise RuntimeError("No open ports found")
+
+
+def parse_ip_port(addr: str) -> tuple[str, int] | None:
+    """
+    Usage:
+
+    - Parses and validates an IP:port address string
+
+    Requires:
+
+    - ``addr``:
+        - Type: str
+        - What: The address string in IP:port format
+
+    Returns:
+
+    - ``result``:
+        - Type: tuple[str, int] | None
+        - What: A tuple of (ip, port) if valid, or None if invalid
+    """
+    if not IP_PORT_RE.match(addr):
+        return None
+    ip_match = re.search(r"([0-9]{1,3}\.)+[0-9]{1,3}", addr)
+    port_match = re.search(r"(?<=:)\d{4,}", addr)
+    if ip_match and port_match:
+        return ip_match.group(0), int(port_match.group(0))
+    return None