cave-cli 3.5.0__py3-none-any.whl

cave_cli/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("cave_cli")

cave_cli/cli.py

@@ -0,0 +1,469 @@
+"""
+CAVE CLI entry point.
+
+Usage:
+    cave <command> [options]
+
+Examples:
+    cave create my_app
+    cave create my_app --version v3.1.0
+    cave run
+    cave run -it
+    cave run 192.168.1.1:8000
+    cave reset -y
+    cave upgrade --version v3.1.0
+    cave sync --url git@github.com:mit-cave/cave_app_aws.git
+    cave test
+    cave prettify
+    cave list
+    cave kill
+    cave purge my_app
+    cave list-versions
+    cave lv  --all --pattern v3*
+    cave update
+    cave version
+"""
+
+import argparse
+import sys
+from importlib.metadata import version
+
+
+def add_global_args(parser: argparse.ArgumentParser) -> None:
+    """Args shared by all commands."""
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        default=False,
+        help="Enable verbose logging output (shorthand for --loglevel DEBUG)",
+    )
+    parser.add_argument(
+        "--loglevel",
+        "--ll",
+        default="INFO",
+        metavar="LEVEL",
+        help=(
+            "Specify a log level: DEBUG, INFO, WARN, ERROR, SILENT "
+            "(default: INFO)"
+        ),
+    )
+    parser.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        default=False,
+        help="Automatically answer confirmation prompts with yes",
+    )
+
+
+def main():
+    __version__ = version("cave_cli")
+    parser = argparse.ArgumentParser(
+        prog="cave",
+        description=(
+            f"CAVE CLI ({__version__}): "
+            "Create and manage Docker-based CAVE web applications."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"CAVE_CLI={__version__}",
+        help="Show the version number and exit",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="command")
+
+    # ------------------------------------------------------------------ #
+    # create                                                               #
+    # ------------------------------------------------------------------ #
+    p_create = subparsers.add_parser(
+        "create",
+        help="Create a new CAVE app from the template repository",
+    )
+    add_global_args(p_create)
+    p_create.add_argument(
+        "name",
+        metavar="app-name",
+        help="Name for the new CAVE app",
+    )
+    p_create.add_argument(
+        "--version",
+        default=None,
+        metavar="VERSION",
+        help="CAVE app version (git tag or branch name)",
+    )
+    p_create.add_argument(
+        "--url",
+        default=None,
+        metavar="URL",
+        help="Git URL for the app template repository",
+    )
+
+    # ------------------------------------------------------------------ #
+    # run / start                                                          #
+    # ------------------------------------------------------------------ #
+    p_run = subparsers.add_parser(
+        "run",
+        aliases=["start"],
+        help="Build and run the CAVE app in the current directory",
+    )
+    add_global_args(p_run)
+    p_run.add_argument(
+        "ip_port",
+        nargs="?",
+        default=None,
+        metavar="ip:port",
+        help="IP and port for LAN hosting (e.g. 192.168.1.1:8000)",
+    )
+    p_run.add_argument(
+        "--entrypoint",
+        default=None,
+        metavar="CMD",
+        help="Entrypoint script to run (default: ./utils/run_server.sh)",
+    )
+    p_run.add_argument(
+        "--docker-args",
+        default="",
+        metavar="ARGS",
+        help="Additional arguments to pass to docker run",
+    )
+    p_run.add_argument(
+        "-it",
+        "-interactive",
+        "--interactive",
+        dest="interactive",
+        action="store_true",
+        default=False,
+        help="Run in interactive mode (entrypoint set to bash)",
+    )
+
+    # ------------------------------------------------------------------ #
+    # reset                                                                #
+    # ------------------------------------------------------------------ #
+    p_reset = subparsers.add_parser(
+        "reset",
+        aliases=["reset-db"],
+        help=(
+            "Remove Docker containers and volumes, "
+            "then rebuild from scratch"
+        ),
+    )
+    add_global_args(p_reset)
+
+    # ------------------------------------------------------------------ #
+    # upgrade                                                              #
+    # ------------------------------------------------------------------ #
+    p_upgrade = subparsers.add_parser(
+        "upgrade",
+        help="Upgrade the CAVE app in the current directory",
+    )
+    add_global_args(p_upgrade)
+    p_upgrade.add_argument(
+        "--version",
+        default=None,
+        metavar="VERSION",
+        help="CAVE app version to upgrade to (git tag or branch name)",
+    )
+    p_upgrade.add_argument(
+        "--url",
+        default=None,
+        metavar="URL",
+        help="Git URL for the app template repository",
+    )
+    p_upgrade.add_argument(
+        "--skip-env-upgrade",
+        action="store_true",
+        default=False,
+        help="Skip upgrading the project .env file",
+    )
+
+    # ------------------------------------------------------------------ #
+    # sync                                                                 #
+    # ------------------------------------------------------------------ #
+    p_sync = subparsers.add_parser(
+        "sync",
+        help="Merge files from another repository into the CAVE app",
+    )
+    add_global_args(p_sync)
+    p_sync.add_argument(
+        "--url",
+        required=True,
+        metavar="URL",
+        help="Git URL of the repository to sync from",
+    )
+    p_sync.add_argument(
+        "--branch",
+        default=None,
+        metavar="BRANCH",
+        help="Branch of the repository to sync from",
+    )
+    p_sync.add_argument(
+        "--include",
+        nargs="+",
+        default=None,
+        metavar="PATTERN",
+        help="File patterns to include (overrides excludes)",
+    )
+    p_sync.add_argument(
+        "--exclude",
+        nargs="+",
+        default=None,
+        metavar="PATTERN",
+        help="File patterns to exclude",
+    )
+
+    # ------------------------------------------------------------------ #
+    # test                                                                 #
+    # ------------------------------------------------------------------ #
+    p_test = subparsers.add_parser(
+        "test",
+        help="Run tests in cave_api/tests/",
+    )
+    add_global_args(p_test)
+    p_test.add_argument(
+        "remaining",
+        nargs="*",
+        help="Additional arguments passed to the test runner",
+    )
+
+    # ------------------------------------------------------------------ #
+    # prettify                                                             #
+    # ------------------------------------------------------------------ #
+    p_prettify = subparsers.add_parser(
+        "prettify",
+        help="Format code with autoflake and black",
+    )
+    add_global_args(p_prettify)
+
+    # ------------------------------------------------------------------ #
+    # list                                                                 #
+    # ------------------------------------------------------------------ #
+    p_list = subparsers.add_parser(
+        "list",
+        help="List running CAVE apps",
+    )
+    add_global_args(p_list)
+    p_list.add_argument(
+        "-a",
+        "--all",
+        action="store_true",
+        default=False,
+        help="Show all CAVE app containers with full names",
+    )
+
+    # ------------------------------------------------------------------ #
+    # kill                                                                 #
+    # ------------------------------------------------------------------ #
+    p_kill = subparsers.add_parser(
+        "kill",
+        help="Stop Docker containers for a CAVE app",
+    )
+    add_global_args(p_kill)
+    p_kill.add_argument(
+        "-a",
+        "--all",
+        action="store_true",
+        default=False,
+        help="Kill all running CAVE apps",
+    )
+
+    # ------------------------------------------------------------------ #
+    # purge                                                                #
+    # ------------------------------------------------------------------ #
+    p_purge = subparsers.add_parser(
+        "purge",
+        help="Remove a CAVE app and all its Docker resources",
+    )
+    add_global_args(p_purge)
+    p_purge.add_argument(
+        "path",
+        metavar="app-path",
+        help="Path to the CAVE app directory to purge",
+    )
+
+    # ------------------------------------------------------------------ #
+    # list-versions / lv                                                   #
+    # ------------------------------------------------------------------ #
+    p_lv = subparsers.add_parser(
+        "list-versions",
+        aliases=["lv"],
+        help="List available CAVE app versions",
+    )
+    add_global_args(p_lv)
+    p_lv.add_argument(
+        "--all",
+        action="store_true",
+        default=False,
+        help="Show all versions (default: 5 most recent per major version)",
+    )
+    p_lv.add_argument(
+        "--pattern",
+        default=None,
+        metavar="PATTERN",
+        help="Glob pattern to filter versions (e.g. v3.*, v3.4.*)",
+    )
+
+    # ------------------------------------------------------------------ #
+    # update                                                               #
+    # ------------------------------------------------------------------ #
+    p_update = subparsers.add_parser(
+        "update",
+        help="Update the CAVE CLI itself",
+    )
+    add_global_args(p_update)
+    p_update.add_argument(
+        "--version",
+        default=None,
+        metavar="VERSION",
+        help="Specific CAVE CLI version to install (git tag or branch)",
+    )
+
+    # ------------------------------------------------------------------ #
+    # uninstall                                                            #
+    # ------------------------------------------------------------------ #
+    p_uninstall = subparsers.add_parser(
+        "uninstall",
+        help="Remove the CAVE CLI",
+    )
+    add_global_args(p_uninstall)
+
+    # ------------------------------------------------------------------ #
+    # version                                                              #
+    # ------------------------------------------------------------------ #
+    p_version = subparsers.add_parser(
+        "version",
+        help="Print version information",
+    )
+    add_global_args(p_version)
+
+    # ------------------------------------------------------------------ #
+    # Dispatch                                                             #
+    # ------------------------------------------------------------------ #
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    # Normalize aliases
+    _COMMAND_ALIASES: dict[str, str] = {
+        "start": "run",
+        "reset-db": "reset",
+        "lv": "list-versions",
+    }
+    args.command = _COMMAND_ALIASES.get(args.command, args.command)
+
+    # Configure logging
+    from cave_cli.utils.logger import logger
+
+    if args.verbose:
+        logger.set_level("DEBUG")
+    else:
+        logger.set_level(args.loglevel)
+
+    # ------------------------------------------------------------------ #
+    # Command dispatch                                                     #
+    # ------------------------------------------------------------------ #
+    if args.command == "create":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.create import create
+
+        check_docker()
+        create(args)
+
+    elif args.command == "run":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.run import run
+
+        check_docker()
+        run(args)
+
+    elif args.command == "reset":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.reset import reset
+
+        check_docker()
+        reset(args)
+
+    elif args.command == "upgrade":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.upgrade import upgrade
+
+        check_docker()
+        upgrade(args)
+
+    elif args.command == "sync":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.sync_cmd import sync_cmd
+
+        check_docker()
+        sync_cmd(args)
+
+    elif args.command == "test":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.test import test
+
+        check_docker()
+        test(args)
+
+    elif args.command == "prettify":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.prettify import prettify
+
+        check_docker()
+        prettify(args)
+
+    elif args.command == "list":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.list_cmd import list_cmd
+
+        check_docker()
+        list_cmd(args)
+
+    elif args.command == "kill":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.kill import kill
+
+        check_docker()
+        kill(args)
+
+    elif args.command == "purge":
+        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.purge import purge
+
+        check_docker()
+        purge(args)
+
+    elif args.command == "list-versions":
+        from cave_cli.commands.list_versions import list_versions
+
+        list_versions(args)
+
+    elif args.command == "update":
+        from cave_cli.commands.update import update
+
+        update(args)
+
+    elif args.command == "uninstall":
+        from cave_cli.commands.uninstall import uninstall
+
+        uninstall(args)
+
+    elif args.command == "version":
+        from cave_cli.commands.version import version as version_cmd
+
+        version_cmd(args)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

cave_cli/commands/create.py

@@ -0,0 +1,168 @@
+import argparse
+import os
+import shutil
+import stat
+import sys
+from pathlib import Path
+
+from cave_cli.commands.reset import reset
+from cave_cli.commands.run import run_cave
+from cave_cli.utils.constants import HTTPS_URL
+from cave_cli.utils.docker import build_image, check_docker, generate_secret_key
+from cave_cli.utils.env import create_env_interactive
+from cave_cli.utils.git import add, branch_rename, clone, commit, init
+from cave_cli.utils.logger import logger
+from cave_cli.utils.validate import validate_app_name
+
+
+def create(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Creates a new CAVE app from the template repository
+    """
+    app_name = args.name
+    error = validate_app_name(app_name)
+    if error:
+        logger.error(error)
+        sys.exit(1)
+
+    if os.path.isdir(app_name):
+        logger.error(
+            f"Cannot create app '{app_name}': "
+            "This folder already exists in the current directory"
+        )
+        sys.exit(1)
+
+    clone_url = getattr(args, "url", None) or HTTPS_URL
+    version = getattr(args, "version", None)
+
+    logger.header("App Creation:")
+    logger.info("Downloading the app template...")
+
+    success = clone(clone_url, app_name, branch=version)
+    if not success or not os.path.isdir(app_name):
+        logger.error("Clone failed. Ensure you used a valid version.")
+        logger.error(
+            f"The version must be a tag (or branch) listed at {clone_url}."
+        )
+        sys.exit(1)
+
+    logger.info("Done")
+
+    app_dir = os.path.abspath(app_name)
+    remove_licence_info(app_dir)
+
+    Path(os.path.join(app_dir, ".env")).touch()
+
+    example_env = os.path.join(app_dir, "example.env")
+    env_path = os.path.join(app_dir, ".env")
+
+    build_image(app_name, app_dir)
+    secret_key = generate_secret_key(app_name)
+
+    create_env_interactive(
+        app_name=app_name,
+        env_path=env_path,
+        template_path=example_env,
+        docker_secret_key=secret_key,
+    )
+
+    reset_args = argparse.Namespace(
+        yes=True,
+        verbose=getattr(args, "verbose", False),
+        loglevel=getattr(args, "loglevel", "INFO"),
+    )
+    reset(reset_args, app_dir=app_dir, app_name=app_name)
+
+    logger.header("Version Control:")
+    logger.info("Configuring git repository...")
+    git_dir = os.path.join(app_dir, ".git")
+    if os.path.isdir(git_dir):
+        rmtree_force(git_dir)
+    init(app_dir)
+
+    gitignore_path = os.path.join(app_dir, ".gitignore")
+    if os.path.isfile(gitignore_path):
+        content = Path(gitignore_path).read_text()
+        content = content.replace(".env", "")
+        Path(gitignore_path).write_text(content)
+
+    if os.path.isfile(gitignore_path):
+        content = Path(gitignore_path).read_text()
+        if "media" not in content:
+            content += "\n# Media\nmedia\n"
+            Path(gitignore_path).write_text(content)
+
+    add(app_dir)
+    commit(app_dir, "Initialize CAVE App")
+    branch_rename(app_dir, "main")
+    logger.info("Done.")
+
+    logger.info("Generating LLM 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("Done.")
+
+    logger.header("App Creation Status:")
+    logger.info(f"App '{app_name}' created successfully!")
+    logger.info(
+        f"Created variables and additional configuration options "
+        f"are available in {app_name}/.env"
+    )
+
+
+def force_remove(func, path, exc):
+    os.chmod(path, stat.S_IWRITE)
+    func(path)
+
+
+def rmtree_force(path: str) -> None:
+    if sys.version_info >= (3, 12):
+        shutil.rmtree(path, onexc=force_remove)
+    else:
+        shutil.rmtree(path, onerror=force_remove)
+
+
+def remove_licence_info(app_dir: str) -> None:
+    license_path = os.path.join(app_dir, "LICENSE")
+    if os.path.isfile(license_path):
+        os.remove(license_path)
+
+    readme_path = os.path.join(app_dir, "README.md")
+    if os.path.isfile(readme_path):
+        lines = Path(readme_path).read_text().splitlines()
+        for i, line in enumerate(lines):
+            if line.strip() == "## License Notice":
+                lines = lines[:i]
+                break
+        Path(readme_path).write_text("\n".join(lines) + "\n")
+
+    notice_path = os.path.join(app_dir, "NOTICE.md")
+    if os.path.isfile(notice_path):
+        lines = Path(notice_path).read_text().splitlines()
+        for i, line in enumerate(lines):
+            if line.startswith("Licensed under"):
+                lines = lines[:i]
+                break
+        Path(notice_path).write_text("\n".join(lines) + "\n")
+
+    setup_path = os.path.join(app_dir, "cave_api", "setup.py")
+    if os.path.isfile(setup_path):
+        content = Path(setup_path).read_text()
+        import re
+
+        content = re.sub(r'^\s*license="MIT",\s*\n', "", content, flags=re.M)
+        content = re.sub(
+            r'^\s*"License.*MIT License",\s*\n', "", content, flags=re.M
+        )
+        Path(setup_path).write_text(content)

cave_cli/commands/kill.py

@@ -0,0 +1,23 @@
+import argparse
+
+from cave_cli.utils.docker import get_running_apps, remove_containers
+from cave_cli.utils.logger import logger
+from cave_cli.utils.validate import get_app
+
+
+def kill(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Stops Docker containers for CAVE apps
+    """
+    kill_all = getattr(args, "all", False)
+
+    if kill_all:
+        for app_name in get_running_apps():
+            remove_containers(app_name)
+            logger.info(f"Killed: {app_name}")
+    else:
+        _, app_name = get_app()
+        remove_containers(app_name)
+        logger.info(f"Killed: {app_name}")

cave_cli/commands/list_cmd.py

@@ -0,0 +1,37 @@
+import argparse
+
+from cave_cli.utils.docker import (
+    get_container_env,
+    get_container_host_port,
+    get_all_containers,
+    get_running_apps,
+)
+from cave_cli.utils.logger import logger
+
+
+def list_cmd(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Lists running CAVE apps or all CAVE app containers
+    """
+    show_all = getattr(args, "all", False)
+
+    if show_all:
+        logger.header("CAVE App Containers (All):")
+        for suffix in ("_django", "_db_host", "_redis_host", "_nginx_host"):
+            for name in get_all_containers(suffix):
+                logger.info(name)
+    else:
+        logger.header("CAVE Apps (Running):")
+        apps = get_running_apps()
+        for app_name in apps:
+            nginx_containers = get_all_containers("_nginx_host")
+            nginx_name = f"{app_name}_nginx_host"
+            if nginx_name in nginx_containers:
+                ip = get_container_env(nginx_name, "CAVE_IP")
+                port = get_container_env(nginx_name, "CAVE_PORT")
+                logger.info(f"{app_name} (https://{ip}:{port})")
+            else:
+                port = get_container_host_port(f"{app_name}_django")
+                logger.info(f"{app_name} (http://localhost:{port})")