cave-cli 3.5.0__py3-none-any.whl

cave_cli/commands/list_versions.py

@@ -0,0 +1,93 @@
+import argparse
+import fnmatch
+import re
+from collections import defaultdict
+
+from cave_cli.utils.constants import CHAR_LINE, VALID_REPOS
+from cave_cli.utils.git import ls_remote_tags
+from cave_cli.utils.logger import logger
+
+RECENT_LIMIT = 5
+
+
+def _version_sort_key(v: str) -> list[int]:
+    return [int(x) for x in re.findall(r"\d+", v)]
+
+
+def list_versions(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Lists available stable versions across all CAVE repositories,
+      grouped by major version, with a presence check per repo
+
+    Optional:
+
+    - ``all``:
+        - Type: bool
+        - What: Show all versions instead of the 5 most recent per major
+        - Default: False
+    """
+    show_all = getattr(args, "all", False)
+    pattern = getattr(args, "pattern", None)
+
+    repo_tags: dict[str, set[str]] = {}
+    for repo in VALID_REPOS:
+        logger.info(f"Fetching versions for {repo}...")
+        git_url = f"https://github.com/MIT-CAVE/{repo}.git"
+        raw = ls_remote_tags(git_url)
+        repo_tags[repo] = {
+            t for t in raw if re.match(r"^v[0-9]+\.[0-9]+\.[0-9]+$", t)
+        }
+
+    all_versions = sorted(
+        (
+            v for v in set().union(*repo_tags.values())
+            if not pattern or fnmatch.fnmatch(v, pattern)
+        ),
+        key=_version_sort_key,
+        reverse=True,
+    )
+
+    if not all_versions:
+        logger.info("No stable versions found.")
+        return
+
+    by_major: dict[int, list[str]] = defaultdict(list)
+    for v in all_versions:
+        major = _version_sort_key(v)[0]
+        by_major[major].append(v)
+
+    repos = list(VALID_REPOS)
+    version_w = max(len("Version"), max(len(v) for v in all_versions))
+    col_w = [max(len(r), 3) for r in repos]
+    pad = 2
+    indent = "  "
+
+    col_header = indent + f"{'Version':<{version_w}}"
+    for r, w in zip(repos, col_w):
+        col_header += " " * pad + f"{r:^{w}}"
+    col_sep = indent + "-" * (len(col_header) - len(indent))
+
+    for major in sorted(by_major.keys(), reverse=True):
+        versions = by_major[major]
+        shown = versions if show_all else versions[:RECENT_LIMIT]
+        hidden = len(versions) - len(shown)
+
+        print(CHAR_LINE)
+        print(f"Version {major}")
+        print(CHAR_LINE)
+        print(col_header)
+        print(col_sep)
+
+        for v in shown:
+            row = indent + f"{v:<{version_w}}"
+            for r, w in zip(repos, col_w):
+                mark = "✓" if v in repo_tags[r] else ""
+                row += " " * pad + f"{mark:^{w}}"
+            print(row)
+
+        if hidden:
+            print(f"\n  +{hidden} older, pass --all to show")
+
+        print()

cave_cli/commands/prettify.py

@@ -0,0 +1,27 @@
+import argparse
+
+from cave_cli.commands.run import run_cave
+from cave_cli.utils.logger import logger
+from cave_cli.utils.validate import get_app
+
+
+def prettify(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Runs code formatting on the CAVE app in the current directory
+    """
+    app_dir, app_name = get_app()
+    logger.info("Prettifying cave_api...")
+
+    run_args = argparse.Namespace(
+        entrypoint="./utils/prettify.sh",
+        interactive=False,
+        it=False,
+        docker_args="",
+        ip_port=None,
+        yes=True,
+        verbose=getattr(args, "verbose", False),
+        loglevel=getattr(args, "loglevel", "INFO"),
+    )
+    run_cave(app_dir, app_name, run_args)

cave_cli/commands/purge.py

@@ -0,0 +1,70 @@
+import argparse
+import os
+import shutil
+import sys
+
+from cave_cli.utils.docker import (
+    remove_containers,
+    remove_image,
+    remove_volume,
+)
+from cave_cli.utils.logger import logger
+from cave_cli.utils.subprocess import run_and_log
+from cave_cli.utils.validate import confirm_action, validate_app_dir
+
+
+def purge(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Removes a CAVE app and all its Docker resources
+    """
+    app_path = args.path
+    if not os.path.isdir(app_path):
+        logger.error(f"No directory {app_path}")
+        sys.exit(1)
+
+    abs_path = os.path.abspath(app_path)
+    errors = validate_app_dir(abs_path)
+    if errors:
+        logger.error("Ensure you specified a valid CAVE app directory")
+        sys.exit(1)
+
+    app_name = os.path.basename(abs_path)
+    logger.header(f"Purging CAVE App ({app_name}):")
+
+    auto_yes = getattr(args, "yes", False)
+    if not auto_yes:
+        confirm_action(
+            "This will permanently remove all data associated "
+            f"with your CAVE App ({app_name})"
+        )
+
+    remove_containers(app_name)
+    remove_volume(app_name)
+    remove_image(app_name)
+
+    logger.info("Removing files...")
+    try:
+        shutil.rmtree(abs_path)
+    except PermissionError:
+        logger.debug(
+            "Some files are owned by root (created by Docker). "
+            "Removing via Docker..."
+        )
+        run_and_log([
+            "docker", "run", "--rm",
+            "-v", f"{abs_path}:/purge",
+            "alpine", "rm", "-rf", "/purge",
+        ])
+        if os.path.isdir(abs_path):
+            try:
+                shutil.rmtree(abs_path)
+            except PermissionError:
+                logger.error(
+                    "Couldn't remove files. "
+                    "You may need elevated permissions."
+                )
+                sys.exit(1)
+    logger.info("Done")
+    logger.info("Purge complete.")

cave_cli/commands/reset.py

@@ -0,0 +1,43 @@
+import argparse
+
+from cave_cli.commands.run import run_cave
+from cave_cli.utils.docker import remove_containers, remove_volume
+from cave_cli.utils.logger import logger
+from cave_cli.utils.validate import confirm_action, get_app
+
+
+def reset(
+    args: argparse.Namespace,
+    app_dir: str | None = None,
+    app_name: str | None = None,
+) -> None:
+    """
+    Usage:
+
+    - Removes Docker containers and volumes, then rebuilds from scratch
+    """
+    auto_yes = getattr(args, "yes", False)
+    if not auto_yes:
+        confirm_action(
+            "This will remove the Docker containers "
+            "(deleted and recreated from scratch) for this app. "
+            "All data in your database will be lost"
+        )
+
+    if app_dir is None or app_name is None:
+        app_dir, app_name = get_app()
+    remove_containers(app_name)
+    remove_volume(app_name)
+
+    reset_args = argparse.Namespace(
+        entrypoint="./utils/reset_db.sh",
+        interactive=False,
+        it=False,
+        docker_args="",
+        ip_port=None,
+        yes=True,
+        verbose=getattr(args, "verbose", False),
+        loglevel=getattr(args, "loglevel", "INFO"),
+    )
+    run_cave(app_dir, app_name, reset_args)
+    logger.info("DB reset complete.")

cave_cli/commands/run.py

@@ -0,0 +1,189 @@
+import argparse
+import sys
+
+from cave_cli.utils.docker import (
+    build_image,
+    create_network,
+    remove_containers,
+    run_detached,
+    run_interactive,
+)
+from cave_cli.utils.env import parse_env
+from cave_cli.utils.logger import logger
+from cave_cli.utils.net import find_open_port, is_port_available, parse_ip_port
+
+
+def run(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Builds and runs the CAVE app's Docker containers
+    """
+    from cave_cli.utils.validate import get_app
+
+    app_dir, app_name = get_app()
+    run_cave(app_dir, app_name, args)
+
+
+def run_cave(
+    app_dir: str,
+    app_name: str,
+    args: argparse.Namespace,
+) -> None:
+    build_image(app_name, app_dir)
+
+    interactive = getattr(args, "interactive", False) or getattr(
+        args, "it", False
+    )
+    entrypoint = getattr(args, "entrypoint", None) or "./utils/run_server.sh"
+    docker_args_str = getattr(args, "docker_args", "") or ""
+    extra_docker_args = docker_args_str.split() if docker_args_str else []
+    ip_port_arg = getattr(args, "ip_port", None)
+
+    command_args = getattr(args, "command_args", []) or []
+    extra_env = getattr(args, "extra_env", {}) or {}
+
+    if interactive:
+        server_command = ["bash"]
+        logger.header("CAVE App: (Interactive)")
+    else:
+        server_command = [entrypoint] + command_args
+        logger.header(f"CAVE App: ({entrypoint})")
+
+    if extra_docker_args:
+        logger.info(f"docker-args: {docker_args_str}")
+
+    env_vars = parse_env(f"{app_dir}/.env")
+    db_password = env_vars.get("DATABASE_PASSWORD", "")
+    db_image = env_vars.get("DATABASE_IMAGE", "postgres:latest")
+    db_command_str = env_vars.get(
+        "DATABASE_COMMAND", "postgres -c listen_addresses=*"
+    )
+    cache_image = env_vars.get("CACHE_IMAGE", "")
+
+    if not db_command_str:
+        db_command_str = "postgres -c listen_addresses=*"
+        logger.debug(
+            "DATABASE_COMMAND not set in '.env' file. "
+            "Using 'postgres -c listen_addresses=*' as default."
+        )
+
+    if not cache_image:
+        logger.warn(
+            "CACHE_IMAGE not set in '.env' file. "
+            "Using valkey/valkey:7 as default."
+        )
+        cache_image = "valkey/valkey:7"
+
+    network = f"cave-net:{app_name}"
+    create_network(app_name)
+
+    run_detached(
+        name=f"{app_name}_db_host",
+        image=db_image,
+        network=network,
+        volumes=[f"{app_name}_pg_volume:/var/lib/postgresql/data"],
+        env_vars={
+            "POSTGRES_PASSWORD": db_password,
+            "POSTGRES_USER": f"{app_name}_user",
+            "POSTGRES_DB": f"{app_name}_name",
+        },
+        extra_args=extra_docker_args or None,
+        command=db_command_str.split(),
+    )
+
+    run_detached(
+        name=f"{app_name}_redis_host",
+        image=cache_image,
+        network=network,
+        volumes=[f"{app_name}_redis_volume:/data"],
+        extra_args=extra_docker_args or None,
+        command=["--save", "7200", "1"],
+    )
+
+    django_env = {
+        "DATABASE_HOST": f"{app_name}_db_host",
+        "DATABASE_USER": f"{app_name}_user",
+        "DATABASE_PASSWORD": db_password,
+        "DATABASE_NAME": f"{app_name}_name",
+        "DATABASE_PORT": "5432",
+        "REDIS_HOST": f"{app_name}_redis_host",
+        "REDIS_PORT": "6379",
+        **extra_env,
+    }
+
+    django_volumes = [
+        f"{app_dir}:/app"
+    ]
+
+    parsed = parse_ip_port(ip_port_arg) if ip_port_arg else None
+
+    if parsed:
+        ip, port = parsed
+        if not is_port_available(port):
+            logger.error(
+                "The specified port is in use. Please try another."
+            )
+            sys.exit(1)
+
+        if entrypoint == "./utils/run_server.sh" and not interactive:
+            logger.info(
+                f"Your Cave App can be accessed from Chrome at:\n"
+                f"https://{ip}:{port}\n"
+            )
+
+        run_detached(
+            name=f"{app_name}_nginx_host",
+            image="nginx",
+            network=network,
+            extra_args=[
+                "--restart",
+                "unless-stopped",
+                "-p",
+                f"{ip}:{port}:8000",
+            ]
+            + (extra_docker_args or []),
+            volumes=[
+                f"{app_dir}/utils/lan_hosting:/certs",
+                f"{app_dir}/utils/nginx_ssl.conf.template:"
+                "/etc/nginx/templates/default.conf.template:ro",
+            ],
+            env_vars={
+                "CAVE_HOST": f"{app_name}_django",
+                "CAVE_PORT": str(port),
+                "CAVE_IP": ip,
+            },
+        )
+
+        django_env["CSRF_TRUSTED_ORIGIN"] = f"{ip}:{port}"
+        run_interactive(
+            name=f"{app_name}_django",
+            image=f"cave-app:{app_name}",
+            network=network,
+            ports=["8000"],
+            volumes=django_volumes,
+            env_vars=django_env,
+            extra_args=extra_docker_args or None,
+            command=server_command,
+        )
+    else:
+        port = find_open_port(8000)
+        if entrypoint == "./utils/run_server.sh" and not interactive:
+            logger.info(
+                f"Your Cave App can be accessed from Chrome at:\n"
+                f"http://localhost:{port}\n"
+            )
+
+        run_interactive(
+            name=f"{app_name}_django",
+            image=f"cave-app:{app_name}",
+            network=network,
+            ports=[f"{port}:8000"],
+            volumes=django_volumes,
+            env_vars=django_env,
+            extra_args=extra_docker_args or None,
+            command=server_command,
+        )
+
+    logger.debug("Stopping Running Containers...")
+    remove_containers(app_name)

cave_cli/commands/sync_cmd.py

@@ -0,0 +1,79 @@
+import argparse
+import os
+import shutil
+import tempfile
+
+from cave_cli.commands.reset import reset
+from cave_cli.utils.constants import HTTPS_URL
+from cave_cli.utils.git import clone
+from cave_cli.utils.logger import logger
+from cave_cli.utils.sync import sync_files
+from cave_cli.utils.validate import confirm_action, find_app_dir
+
+
+def sync_cmd(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Merges files from another git repository into the current CAVE app
+    """
+    app_dir = find_app_dir()
+    auto_yes = getattr(args, "yes", False)
+
+    if not auto_yes:
+        confirm_action(
+            "This will reset your docker containers and database. "
+            "It will also potentially update your local files"
+        )
+
+    logger.header("Sync:")
+
+    url = getattr(args, "url", None)
+    if not url:
+        logger.error("--url is required for sync")
+        return
+
+    branch = getattr(args, "branch", None)
+    includes = getattr(args, "include", None) or []
+    excludes = getattr(args, "exclude", None) or []
+
+    logger.info("Syncing files with the following parameters:\n")
+    logger.info(f"App Location: {app_dir}")
+    logger.info(f"Using Repo: {url}")
+    logger.info(f"Using Branch: {branch or 'default'}\n")
+    logger.info("Downloading repo to sync...")
+
+    temp_dir = tempfile.mkdtemp()
+    success = clone(url, temp_dir, branch=branch)
+
+    if not success or not os.listdir(temp_dir):
+        logger.error(
+            f"Failed!\n"
+            f"Ensure you have access rights to the repository: {url}\n"
+            f"Ensure you specified a valid branch: {branch}."
+        )
+        shutil.rmtree(temp_dir, ignore_errors=True)
+        return
+
+    logger.info("Done")
+    logger.info("Syncing files...")
+
+    sync_files(
+        source=temp_dir,
+        dest=app_dir,
+        includes=includes,
+        excludes=excludes,
+    )
+
+    logger.info("Done")
+
+    shutil.rmtree(temp_dir, ignore_errors=True)
+
+    reset_args = argparse.Namespace(
+        yes=True,
+        verbose=getattr(args, "verbose", False),
+        loglevel=getattr(args, "loglevel", "INFO"),
+    )
+    reset(reset_args)
+
+    logger.info("Sync complete.")

cave_cli/commands/test.py

@@ -0,0 +1,38 @@
+import argparse
+
+from cave_cli.commands.run import run_cave
+from cave_cli.utils.logger import logger
+from cave_cli.utils.validate import get_app
+
+
+def test(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Runs tests for the CAVE app in the current directory
+    """
+    app_dir, app_name = get_app()
+    logger.info("Testing cave_api...")
+
+    remaining = getattr(args, "remaining", []) or []
+
+    if remaining:
+        command_args = [remaining[0]]
+        extra_env: dict[str, str] = {}
+    else:
+        command_args = []
+        extra_env = {"ALL_FLAG": "true"}
+
+    run_args = argparse.Namespace(
+        entrypoint="./utils/run_test.sh",
+        command_args=command_args,
+        extra_env=extra_env,
+        interactive=False,
+        it=False,
+        docker_args="",
+        ip_port=None,
+        yes=True,
+        verbose=getattr(args, "verbose", False),
+        loglevel=getattr(args, "loglevel", "INFO"),
+    )
+    run_cave(app_dir, app_name, run_args)

cave_cli/commands/uninstall.py

@@ -0,0 +1,39 @@
+import argparse
+import subprocess
+import sys
+
+from cave_cli.utils.logger import logger
+
+
+def uninstall(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Removes the CAVE CLI package
+    """
+    try:
+        response = input(
+            "Are you sure you want to uninstall CAVE CLI? [y/N] "
+        )
+    except (EOFError, KeyboardInterrupt):
+        print()
+        logger.error("Uninstall canceled")
+        return
+
+    if response.strip().lower() not in ("y", "yes"):
+        logger.error("Uninstall canceled")
+        return
+
+    logger.info("Removing installation...")
+    result = subprocess.run(
+        [sys.executable, "-m", "pip", "uninstall", "cave_cli", "-y"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    if result.returncode == 0:
+        logger.info("Done.")
+    else:
+        logger.error("Failed to uninstall CAVE CLI.")
+        if result.stderr:
+            logger.error(result.stderr.strip())

cave_cli/commands/update.py

@@ -0,0 +1,38 @@
+import argparse
+import subprocess
+import sys
+
+from cave_cli.utils.logger import logger
+
+
+def update(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Updates the CAVE CLI via pip install --upgrade
+    """
+    logger.info("Updating CAVE CLI...")
+    version = getattr(args, "version", None)
+    if version:
+        spec = (
+            f"cave_cli @ "
+            f"git+https://github.com/MIT-CAVE/cave_cli.git@{version}"
+        )
+    else:
+        spec = (
+            "cave_cli @ "
+            "git+https://github.com/MIT-CAVE/cave_cli.git@main"
+        )
+    result = subprocess.run(
+        [sys.executable, "-m", "pip", "install", "--upgrade", spec],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    if result.returncode == 0:
+        logger.info("Done.")
+        logger.info("CAVE CLI updated.")
+    else:
+        logger.error("Failed to update CAVE CLI.")
+        if result.stderr:
+            logger.error(result.stderr.strip())

cave_cli/commands/upgrade.py

@@ -0,0 +1,70 @@
+import argparse
+import os
+import shutil
+import tempfile
+
+from cave_cli.commands.create import remove_licence_info
+from cave_cli.commands.run import run_cave
+from cave_cli.commands.sync_cmd import sync_cmd
+from cave_cli.utils.constants import HTTPS_URL
+from cave_cli.utils.env import upgrade_env
+from cave_cli.utils.git import clone
+from cave_cli.utils.logger import logger
+from cave_cli.utils.sync import sync_files
+from cave_cli.utils.validate import confirm_action, find_app_dir, get_app
+
+
+def upgrade(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Upgrades the CAVE app in the current directory from the template repository
+    """
+    auto_yes = getattr(args, "yes", False)
+    if not auto_yes:
+        confirm_action(
+            "This will potentially update all files not in "
+            "'cave_api/' or '.env' and reset your database"
+        )
+
+    logger.header("Upgrade:")
+    logger.info("Upgrading CAVE App via a Sync operation...\n")
+
+    app_dir, app_name = get_app()
+    url = getattr(args, "url", None) or HTTPS_URL
+    version = getattr(args, "version", None)
+    skip_env_upgrade = getattr(args, "skip_env_upgrade", False)
+
+    sync_args = argparse.Namespace(
+        url=url,
+        branch=version or "main",
+        include=["cave_api/docs"],
+        exclude=[".env", ".gitignore", "cave_api/*"],
+        yes=True,
+        verbose=getattr(args, "verbose", False),
+        loglevel=getattr(args, "loglevel", "INFO"),
+    )
+    sync_cmd(sync_args)
+
+    if not skip_env_upgrade:
+        temp_dir = tempfile.mkdtemp()
+        clone(url, temp_dir, branch=version or "main")
+        env_path = os.path.join(app_dir, ".env")
+        upgrade_env(env_path, temp_dir)
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+    remove_licence_info(app_dir)
+
+    logger.info("\nUpdating Docs...")
+    docs_args = argparse.Namespace(
+        entrypoint="./utils/generate_docs.sh",
+        interactive=False,
+        it=False,
+        docker_args="",
+        ip_port=None,
+        yes=True,
+        verbose=getattr(args, "verbose", False),
+        loglevel=getattr(args, "loglevel", "INFO"),
+    )
+    run_cave(app_dir, app_name, docs_args)
+    logger.info("Upgrade complete.")