caylent-devcontainer-cli 0.1.0__tar.gz

caylent_devcontainer_cli-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: caylent-devcontainer-cli
+Version: 0.1.0
+Summary: CLI tool for managing Caylent devcontainers
+Author-email: Caylent <solutions-owners@caylent.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/caylent-solutions/devcontainer
+Project-URL: Issues, https://github.com/caylent-solutions/devcontainer/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: black~=24.0
+Requires-Dist: flake8~=7.0
+Requires-Dist: isort~=6.0
+Requires-Dist: pytest~=7.0
+Requires-Dist: pytest-cov~=4.0
+Requires-Dist: questionary~=2.0.0
+Requires-Dist: semver~=3.0.0
+
+# Caylent Devcontainer CLI
+
+A command-line tool for managing Caylent devcontainer environments.
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Usage](#usage)
+   - [Commands](#commands)
+   - [Setting Up a Devcontainer](#setting-up-a-devcontainer)
+   - [Managing Templates](#managing-templates)
+   - [Launching VS Code](#launching-vs-code)
+3. [Development](#development)
+   - [Setup](#setup)
+   - [Testing](#testing)
+   - [Linting and Formatting](#linting-and-formatting)
+   - [Building and Publishing](#building-and-publishing)
+4. [License](#license)
+
+## Installation
+
+```bash
+# Install from PyPI (when available)
+pip install caylent-devcontainer-cli
+
+# Install from GitHub with a specific version tag
+pip install git+https://github.com/caylent-solutions/devcontainer.git@0.1.0#subdirectory=caylent-devcontainer-cli
+```
+
+## Usage
+
+```bash
+cdevcontainer --help
+```
+
+### Commands
+
+- `setup-devcontainer`: Set up a devcontainer in a project directory
+- `code`: Launch VS Code with the devcontainer environment
+- `env`: Manage environment variables
+- `template`: Manage devcontainer templates
+- `install`: Install the CLI tool to your PATH
+- `uninstall`: Uninstall the CLI tool
+
+### Setting Up a Devcontainer
+
+```bash
+# Interactive setup
+cdevcontainer setup-devcontainer /path/to/your/project
+
+# Manual setup (skip interactive prompts)
+cdevcontainer setup-devcontainer --manual /path/to/your/project
+
+# Update existing devcontainer files to the current CLI version
+cdevcontainer setup-devcontainer --update /path/to/your/project
+```
+
+The interactive setup will guide you through:
+1. Using an existing template or creating a new one
+2. Configuring environment variables
+3. Setting up AWS profiles (if enabled)
+
+### Managing Templates
+
+```bash
+# Save current environment as a template
+cdevcontainer template save my-template
+
+# List available templates
+cdevcontainer template list
+
+# Load a template into a project
+cdevcontainer template load my-template
+
+# Delete one or more templates
+cdevcontainer template delete template1 template2
+
+# Upgrade a template to the current CLI version
+cdevcontainer template upgrade my-template
+```
+
+When using templates created with older versions of the CLI, the tool will automatically detect version mismatches and provide options to:
+- Upgrade the profile to the current version
+- Create a new profile from scratch
+- Try to use the profile anyway (with a warning)
+- Exit without making changes
+
+### Launching VS Code
+
+```bash
+# Launch VS Code for the current project
+cdevcontainer code
+
+# Launch VS Code for a specific project
+cdevcontainer code /path/to/your/project
+```
+
+## Development
+
+### Setup
+
+For development, we recommend using the devcontainer itself. See the [Contributing Guide](CONTRIBUTING.md) for detailed setup instructions.
+
+### Testing
+
+```bash
+# Run unit tests
+make unit-test
+
+# Run functional tests
+make functional-test
+
+# Run all tests
+make test
+
+# Generate coverage report
+make coverage
+
+# View functional test coverage report
+make functional-test-report
+```
+
+#### Testing Requirements
+
+- **Unit Tests**: Must maintain at least 90% code coverage
+- **Functional Tests**: Must test CLI commands as they would be used by actual users
+- All tests must pass before merging code
+
+### Linting and Formatting
+
+```bash
+# Check code style
+make lint
+
+# Format code
+make format
+```
+
+### Building and Publishing
+
+The package is automatically published to PyPI when a new tag is pushed to GitHub.
+
+To create a new release:
+
+1. Ensure all tests pass (`make test`)
+2. Perform the [manual tests](MANUAL_TESTING.md) to verify functionality
+3. Create and push a new tag following semantic versioning:
+
+```bash
+git tag -a 0.1.0 -m "Release 0.1.0"
+git push origin 0.1.0
+```
+
+The GitHub Actions workflow will:
+1. Validate the tag follows semantic versioning (MAJOR.MINOR.PATCH)
+2. Build the package using ASDF for Python version management
+3. Publish the package to PyPI
+
+## License
+
+Apache License 2.0

caylent_devcontainer_cli-0.1.0/README.md

@@ -0,0 +1,161 @@
+# Caylent Devcontainer CLI
+
+A command-line tool for managing Caylent devcontainer environments.
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Usage](#usage)
+   - [Commands](#commands)
+   - [Setting Up a Devcontainer](#setting-up-a-devcontainer)
+   - [Managing Templates](#managing-templates)
+   - [Launching VS Code](#launching-vs-code)
+3. [Development](#development)
+   - [Setup](#setup)
+   - [Testing](#testing)
+   - [Linting and Formatting](#linting-and-formatting)
+   - [Building and Publishing](#building-and-publishing)
+4. [License](#license)
+
+## Installation
+
+```bash
+# Install from PyPI (when available)
+pip install caylent-devcontainer-cli
+
+# Install from GitHub with a specific version tag
+pip install git+https://github.com/caylent-solutions/devcontainer.git@0.1.0#subdirectory=caylent-devcontainer-cli
+```
+
+## Usage
+
+```bash
+cdevcontainer --help
+```
+
+### Commands
+
+- `setup-devcontainer`: Set up a devcontainer in a project directory
+- `code`: Launch VS Code with the devcontainer environment
+- `env`: Manage environment variables
+- `template`: Manage devcontainer templates
+- `install`: Install the CLI tool to your PATH
+- `uninstall`: Uninstall the CLI tool
+
+### Setting Up a Devcontainer
+
+```bash
+# Interactive setup
+cdevcontainer setup-devcontainer /path/to/your/project
+
+# Manual setup (skip interactive prompts)
+cdevcontainer setup-devcontainer --manual /path/to/your/project
+
+# Update existing devcontainer files to the current CLI version
+cdevcontainer setup-devcontainer --update /path/to/your/project
+```
+
+The interactive setup will guide you through:
+1. Using an existing template or creating a new one
+2. Configuring environment variables
+3. Setting up AWS profiles (if enabled)
+
+### Managing Templates
+
+```bash
+# Save current environment as a template
+cdevcontainer template save my-template
+
+# List available templates
+cdevcontainer template list
+
+# Load a template into a project
+cdevcontainer template load my-template
+
+# Delete one or more templates
+cdevcontainer template delete template1 template2
+
+# Upgrade a template to the current CLI version
+cdevcontainer template upgrade my-template
+```
+
+When using templates created with older versions of the CLI, the tool will automatically detect version mismatches and provide options to:
+- Upgrade the profile to the current version
+- Create a new profile from scratch
+- Try to use the profile anyway (with a warning)
+- Exit without making changes
+
+### Launching VS Code
+
+```bash
+# Launch VS Code for the current project
+cdevcontainer code
+
+# Launch VS Code for a specific project
+cdevcontainer code /path/to/your/project
+```
+
+## Development
+
+### Setup
+
+For development, we recommend using the devcontainer itself. See the [Contributing Guide](CONTRIBUTING.md) for detailed setup instructions.
+
+### Testing
+
+```bash
+# Run unit tests
+make unit-test
+
+# Run functional tests
+make functional-test
+
+# Run all tests
+make test
+
+# Generate coverage report
+make coverage
+
+# View functional test coverage report
+make functional-test-report
+```
+
+#### Testing Requirements
+
+- **Unit Tests**: Must maintain at least 90% code coverage
+- **Functional Tests**: Must test CLI commands as they would be used by actual users
+- All tests must pass before merging code
+
+### Linting and Formatting
+
+```bash
+# Check code style
+make lint
+
+# Format code
+make format
+```
+
+### Building and Publishing
+
+The package is automatically published to PyPI when a new tag is pushed to GitHub.
+
+To create a new release:
+
+1. Ensure all tests pass (`make test`)
+2. Perform the [manual tests](MANUAL_TESTING.md) to verify functionality
+3. Create and push a new tag following semantic versioning:
+
+```bash
+git tag -a 0.1.0 -m "Release 0.1.0"
+git push origin 0.1.0
+```
+
+The GitHub Actions workflow will:
+1. Validate the tag follows semantic versioning (MAJOR.MINOR.PATCH)
+2. Build the package using ASDF for Python version management
+3. Publish the package to PyPI
+
+## License
+
+Apache License 2.0

caylent_devcontainer_cli-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["setuptools>=78.1.1", "wheel>=0.40.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "caylent-devcontainer-cli"
+version = "0.1.0"
+description = "CLI tool for managing Caylent devcontainers"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.8"
+license = "Apache-2.0"
+
+authors = [
+  { name = "Caylent", email = "solutions-owners@caylent.com" }
+]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12"
+]
+
+dependencies = [
+  "black~=24.0",
+  "flake8~=7.0",
+  "isort~=6.0",
+  "pytest~=7.0",
+  "pytest-cov~=4.0",
+  "questionary~=2.0.0",
+  "semver~=3.0.0"
+]
+
+[project.scripts]
+cdevcontainer = "caylent_devcontainer_cli.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/caylent-solutions/devcontainer"
+Issues = "https://github.com/caylent-solutions/devcontainer/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.black]
+line-length = 120
+target-version = ["py38"]
+
+[tool.isort]
+profile = "black"
+line_length = 120
+
+[tool.semantic_release]
+version_variable = "src/caylent_devcontainer_cli/__init__.py:__version__"
+branch = "main"
+upload_to_pypi = false
+upload_to_release = false
+build_command = "python -m build"
+version_source = "commit"
+version_toml = ["pyproject.toml:project.version"]
+tag_format = "{version}"
+major_on_zero = true
+commit_version_number = true
+changelog_file = "CHANGELOG.md"
+changelog_scope = false
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = [
+  "build",
+  "chore",
+  "ci",
+  "docs",
+  "feat",
+  "fix",
+  "perf",
+  "refactor",
+  "style",
+  "test"
+]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]

caylent_devcontainer_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

caylent_devcontainer_cli-0.1.0/src/caylent_devcontainer_cli/__init__.py

@@ -0,0 +1,4 @@
+"""Caylent Devcontainer CLI package."""
+
+# Direct version specification for build process
+__version__ = "0.1.0"

caylent_devcontainer_cli-0.1.0/src/caylent_devcontainer_cli/cli.py

@@ -0,0 +1,59 @@
+"""Main CLI entry point for Caylent Devcontainer CLI."""
+
+import argparse
+
+from caylent_devcontainer_cli import __version__
+from caylent_devcontainer_cli.commands import code, env, install, setup, template
+
+# Constants
+CLI_NAME = "Caylent Devcontainer CLI"
+
+
+def main():
+    """Main entry point for the CLI."""
+    # Create the main parser
+    parser = argparse.ArgumentParser(
+        description=f"{CLI_NAME} - Manage devcontainer environments",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    # Add global options
+    parser.add_argument("-y", "--yes", action="store_true", help="Automatically answer yes to all prompts")
+    parser.add_argument("-v", "--version", action="version", version=f"{CLI_NAME} {__version__}")
+
+    # Create subparsers
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # Register commands
+    code.register_command(subparsers)
+    env.register_command(subparsers)
+    template.register_command(subparsers)
+    install.register_command(subparsers)
+    setup.register_command(subparsers)
+
+    # Parse arguments
+    args = parser.parse_args()
+
+    # Show banner
+    from caylent_devcontainer_cli.utils.ui import log
+
+    log("INFO", f"Welcome to {CLI_NAME} {__version__}")
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        import sys as _sys
+
+        _sys.exit(1)
+
+    # Set global AUTO_YES flag if needed
+    if hasattr(args, "yes") and args.yes:
+        from caylent_devcontainer_cli.utils.ui import set_auto_yes
+
+        set_auto_yes(True)
+
+    # Execute the command
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

caylent_devcontainer_cli-0.1.0/src/caylent_devcontainer_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for the Caylent Devcontainer CLI."""

caylent_devcontainer_cli-0.1.0/src/caylent_devcontainer_cli/commands/code.py

@@ -0,0 +1,61 @@
+"""Code command for the Caylent Devcontainer CLI."""
+
+import os
+import subprocess
+
+from caylent_devcontainer_cli.utils.fs import find_project_root, generate_shell_env
+from caylent_devcontainer_cli.utils.ui import log
+
+
+def register_command(subparsers):
+    """Register the code command."""
+    code_parser = subparsers.add_parser("code", help="Launch VS Code with the devcontainer environment")
+    code_parser.add_argument(
+        "project_root",
+        nargs="?",
+        default=None,
+        help="Project root directory (default: current directory)",
+    )
+    code_parser.add_argument("-y", "--yes", action="store_true", help="Automatically answer yes to all prompts")
+    code_parser.set_defaults(func=handle_code)
+
+
+def handle_code(args):
+    """Handle the code command."""
+    project_root = find_project_root(args.project_root)
+
+    # Check if devcontainer-environment-variables.json exists
+    env_json = os.path.join(project_root, "devcontainer-environment-variables.json")
+    shell_env = os.path.join(project_root, "shell.env")
+
+    if not os.path.isfile(env_json):
+        log("ERR", f"Configuration file not found: {env_json}")
+        log("INFO", "Please create this file first:")
+        print("cp .devcontainer/example-container-env-values.json devcontainer-environment-variables.json")
+        import sys
+
+        sys.exit(1)
+
+    # Generate shell.env if needed
+    if not os.path.isfile(shell_env) or os.path.getmtime(env_json) > os.path.getmtime(shell_env):
+        log("INFO", "Generating environment variables...")
+        generate_shell_env(env_json, shell_env)
+    else:
+        log("INFO", "Using existing shell.env file")
+
+    # Launch VS Code
+    log("INFO", "Launching VS Code...")
+
+    # Create a command that sources the environment and runs VS Code
+    command = f"source {shell_env} && code {project_root}"
+
+    try:
+        # Execute the command in a new shell
+        process = subprocess.Popen(command, shell=True, executable=os.environ.get("SHELL", "/bin/bash"))
+        process.wait()
+        log("OK", "VS Code launched. Accept the prompt to reopen in container when it appears.")
+    except Exception as e:
+        log("ERR", f"Failed to launch VS Code: {e}")
+        import sys
+
+        sys.exit(1)

caylent_devcontainer_cli-0.1.0/src/caylent_devcontainer_cli/commands/env.py

@@ -0,0 +1,64 @@
+"""Environment command for the Caylent Devcontainer CLI."""
+
+import os
+
+from caylent_devcontainer_cli.utils.fs import generate_shell_env
+from caylent_devcontainer_cli.utils.ui import log
+
+
+def register_command(subparsers):
+    """Register the env command."""
+    env_parser = subparsers.add_parser("env", help="Environment variable management")
+    env_subparsers = env_parser.add_subparsers(dest="env_command")
+
+    # 'env export' command
+    export_parser = env_subparsers.add_parser("export", help="Generate shell exports from JSON")
+    export_parser.add_argument("json_file", help="Path to JSON with 'containerEnv'")
+    export_parser.add_argument("-o", "--output", required=True, help="Output file for shell exports")
+    export_parser.add_argument("--no-export", action="store_true", help="Omit 'export' prefix (for .env files)")
+    export_parser.add_argument("-y", "--yes", action="store_true", help="Automatically answer yes to all prompts")
+    export_parser.set_defaults(func=handle_env_export)
+
+    # 'env load' command
+    load_parser = env_subparsers.add_parser("load", help="Load environment variables")
+    load_parser.add_argument("-p", "--project-root", help="Project root directory (default: current directory)")
+    load_parser.add_argument("-y", "--yes", action="store_true", help="Automatically answer yes to all prompts")
+    load_parser.set_defaults(func=handle_env_load)
+
+
+def handle_env_export(args):
+    """Handle the env export command."""
+    generate_shell_env(args.json_file, args.output, args.no_export)
+
+
+def handle_env_load(args):
+    """Handle the env load command."""
+    project_root = args.project_root or os.getcwd()
+    load_environment(project_root)
+
+
+def load_environment(project_root):
+    """Load environment variables from shell.env file."""
+    shell_env_path = os.path.join(project_root, "shell.env")
+    env_vars_json = os.path.join(project_root, "devcontainer-environment-variables.json")
+
+    # Generate shell.env if it doesn't exist
+    if not os.path.exists(shell_env_path):
+        if os.path.exists(env_vars_json):
+            log("INFO", f"Generating shell.env from {env_vars_json}")
+            generate_shell_env(env_vars_json, shell_env_path)
+        else:
+            log("ERR", f"Configuration file not found: {env_vars_json}")
+            import sys
+
+            sys.exit(1)
+
+    # Print instructions for sourcing the environment
+    from caylent_devcontainer_cli.utils.ui import COLORS
+
+    print(f"{COLORS['CYAN']}To load the environment variables, run:{COLORS['RESET']}")
+    print(f"source {shell_env_path}")
+    print(f"\n{COLORS['CYAN']}Or to load and launch VS Code in one command:{COLORS['RESET']}")
+    print(f"source {shell_env_path} && code {project_root}")
+    warning = f"\n{COLORS['YELLOW']}⚠️  IMPORTANT: Use a dedicated terminal for each project{COLORS['RESET']}"
+    print(warning)