rapidctl 0.1.0__tar.gz

rapidctl-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,41 @@
+name: Python Publish
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+    paths:
+      - 'rapidctl/**'
+      - 'pyproject.toml'
+      - '.github/workflows/python-publish.yml'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/rapidctl
+    permissions:
+      id-token: write
+      contents: read
+      
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 # Required for hatch-vcs dynamic versioning
+        
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+        
+    - name: Install build tool
+      run: python -m pip install build
+      
+    - name: Build sdist and wheel
+      run: python -m build
+      
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

rapidctl-0.1.0/.github/workflows/python-test.yml

@@ -0,0 +1,62 @@
+name: Python Test
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'rapidctl/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - '.github/workflows/python-test.yml'
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - 'rapidctl/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - '.github/workflows/python-test.yml'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y podman
+        sudo systemctl start podman
+        python -m pip install --upgrade pip
+        pip install podman pytest
+        pip install -e .
+        
+    - name: Start Podman service
+      run: |
+        # Ensure we have a clean state for the socket
+        rm -f /home/runner/podman.sock
+        # Start podman system service in background
+        podman system service unix:///home/runner/podman.sock --time 0 &
+        sleep 10
+        # Verify socket exists and Podman can connect to it
+        if [ ! -S /home/runner/podman.sock ]; then
+          echo "Error: Podman socket not found at /home/runner/podman.sock"
+          # Try to show logs if possible (though backgrounded, some info might be in dmesg or similar)
+          podman info
+          exit 1
+        fi
+        echo "✓ Podman socket created successfully"
+        podman --remote --url unix:///home/runner/podman.sock info
+        echo "PODMAN_SOCKET=unix:///home/runner/podman.sock" >> $GITHUB_ENV
+        
+    - name: Test with pytest
+      run: |
+        pytest tests/

rapidctl-0.1.0/.gitignore

@@ -0,0 +1,179 @@
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+venv_*
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Vim editor
+*.swp

rapidctl-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-08
+
+### Added
+- Initial Beta release of `rapidctl`.
+- Support for creating custom CLI tools using Podman.
+- Automatic container detection and lifecycle management (OSX and Linux).
+- State management for container-based tools.
+- MCP (Model Context Protocol) support for exposing subcommands.
+- Authentication handling for container registries.
+- Image caching and version management.
+- Comprehensive test suite for core functionality.
+- GitHub Actions for automated testing and PyPI publishing.
+
+### Changed
+- Refactored state management into a pluggable `StateManager`.
+- Optimized GitHub Actions to trigger only on relevant file changes.
+
+### Fixed
+- Improved error handling for container command execution.
+- Resolved issues with Podman authentication on macOS.

rapidctl-0.1.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: rapidctl
+Version: 0.1.0
+Summary: A Python framework for creating custom CLI tools using Podman
+Project-URL: Homepage, https://github.com/dalethestirling/rapidctl
+Requires-Python: >=3.10
+Requires-Dist: mcp
+Requires-Dist: podman
+Description-Content-Type: text/markdown
+
+# Rapidctl
+
+**Rapidctl** is a Python framework for creating custom CLI tools that execute commands inside containerized environments using Podman. It allows you to package and distribute CLI utilities where all dependencies and runtime environments are containerized, ensuring consistency across different systems.
+
+## 🎯 Purpose
+
+Rapidctl solves the problem of distributing CLI tools with complex dependencies. Instead of requiring users to install specific versions of languages, libraries, or system packages, you package everything in a container and provide a lightweight Python wrapper that handles container orchestration transparently.
+
+## 🏗️ Architecture
+
+Rapidctl consists of three main layers:
+
+```
+┌─────────────────────────────────────┐
+│   Your Custom CLI (e.g. examplectl) │  ← User-facing entry point
+├─────────────────────────────────────┤
+│   Bootstrap Layer (CtlClient)       │  ← Configuration & validation
+├─────────────────────────────────────┤
+│   CLI Layer (PodmanCLI)             │  ← Container orchestration
+├─────────────────────────────────────┤
+│   Podman API                         │  ← Container runtime
+└─────────────────────────────────────┘
+```
+
+### Components
+
+- **Bootstrap Layer** (`rapidctl.bootstrap.client`)
+  - `CtlClient`: Defines container configuration and validates container image names
+  - Prevents command injection through input sanitization
+
+- **Connectors** (`rapidctl.bootstrap.connectors`)
+  - Connectors are used to connect to the container runtime
+  - Connectors are platform specific
+  - Connectors are used by the CLI Layer to interact with the container runtime
+  - Connectors are plugins for different ecosystems (Window, OSX, Linux, etc)
+  
+- **CLI Layer** (`rapidctl.cli`)
+  - `PodmanCLI`: Interfaces with Podman API for container operations
+  - Handles image pulling, container management, and command execution
+  
+- **Actions** (`rapidctl.cli.actions`)
+  - Actions are an operation to achieve an outcome 
+  - Actions orchestrate and use one or more tasks to achieve their outcome
+
+- **Tasks** (`rapidctl.cli.tasks`)
+  - Tasks perform a single operation 
+  - Tasks are the building blocks of actions
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.10+
+- Podman installed and running (on macOS, you will be automatically prompted to start the machine if it is stopped)
+- `podman` Python package
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/rapidctl.git
+cd rapidctl
+
+# Install dependencies
+pip install podman
+
+# Optional: Set the Podman socket path manually (auto-detected by default)
+# export PODMAN_SOCKET="unix:///run/user/$(id -u)/podman/podman.sock"
+```
+
+### Creating Your Custom CLI Tool
+
+1. **Create your CLI wrapper** (e.g., `myctl`):
+
+```python
+#!/usr/bin/env python
+
+import re
+import sys
+from rapidctl.cli.main import main
+from rapidctl.bootstrap import client
+
+# Create and configure the client
+client = client.CtlClient()
+client.container_repo = "docker.io/myorg/mytool-container"
+client.baseline_version = "1.0.0"
+client.client_version = "0.0.1"
+
+# Run the CLI
+if __name__ == '__main__':
+    sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0])
+    sys.exit(main(client))
+```
+
+2. **Make it executable**:
+
+```bash
+chmod +x myctl
+```
+
+3. **Use your CLI**:
+
+```bash
+./myctl <command> <args>
+```
+
+The tool will automatically:
+- Check if the container image exists locally
+- Pull the image if needed
+- Execute your command inside the container
+
+## 📝 Example: rapidctl-examplectl
+
+A complete reference implementation and template for building your own CLI tool can be found in the [rapidctl-examplectl](https://github.com/dalethestirling/rapidctl-examplectl) repository.
+
+It includes:
+- A working CLI wrapper
+- A `Dockerfile` for the container environment
+- Example command orchestration scripts
+- Version management demonstrations
+
+## 🔧 Configuration
+
+### CtlClient Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `container_repo` | `str` | `None` | Container registry path (e.g., `docker.io/user/image`) |
+| `baseline_version` | `str` | `"1.0.0"` | Container image tag/version |
+| `client_version` | `str` | `"0.0.1"` | Your CLI tool version |
+| `image_id` | `str` | `None` | Specific image ID (optional) |
+| `command_path` | `str` | `"/opt/rapidctl/cmd/"` | Path inside container where commands are located |
+
+### Environment Variables
+
+- **`PODMAN_SOCKET`**: Path to Podman socket (optional)
+  - If not set, rapidctl will auto-detect the socket location using platform-specific connectors
+  - On macOS, auto-detection checks:
+    - `~/.local/share/containers/podman/machine/podman.sock`
+    - `/var/run/docker.sock`
+    - Machine-specific socket locations
+  - Override auto-detection by setting this variable:
+    ```bash
+    export PODMAN_SOCKET="unix:///path/to/your/podman.sock"
+    ```
+  - Useful for custom Podman installations or when running multiple Podman instances
+
+## 🔒 Security
+
+Rapidctl includes container image name validation to prevent command injection attacks:
+
+- Sanitizes registry URLs and image names
+- Validates domain names and repository paths
+- Removes dangerous characters (`;`, `|`, `&`, etc.)
+- Supports standard Docker/Podman image formats
+
+Example validated formats:
+- `ubuntu:20.04`
+- `docker.io/library/ubuntu:latest`
+- `registry.example.com/myproject/myimage:v1.2.3`
+- `localhost:5000/my-image`
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run specific test
+pytest tests/test_client.py
+pytest tests/test_container_validator.py
+```
+
+## 📦 Project Structure
+
+```
+rapidctl/
+├── rapidctl/
+│   ├── __init__.py
+│   ├── bootstrap/
+│   │   ├── __init__.py
+│   │   ├── client.py           # CtlClient configuration
+│   │   ├── state.py            # State and cache management
+│   │   └── connectors/
+│   │       ├── __init__.py
+│   │       ├── base.py         # BaseConnector interface
+│   │       ├── linux.py
+│   │       └── osx.py
+│   ├── cli/
+│   │   ├── __init__.py         # PodmanCLI class
+│   │   ├── main.py             # Main entry point
+│   │   ├── actions.py          # High-level actions
+│   │   ├── mcp.py              # MCP server integration
+│   │   └── tasks.py            # Low-level tasks
+│   ├── utils/
+│   │   └── version.py          # Version utilities
+│   └── errors/
+│       └── __init__.py         # Custom exceptions
+├── tests/
+│   ├── test_client.py
+│   ├── test_container_validator.py
+│   └── ... (comprehensive test suite)
+├── examples/
+│   └── example_connector_usage.py
+├── pyproject.toml           # Packaging configuration
+└── README.md
+```
+
+## 🛠️ Development Status
+
+**Current Status**: Alpha / In Development
+
+### Known Limitations
+
+- Limited error handling and recovery
+
+### Roadmap
+
+- [x] Complete command execution implementation
+- [ ] Add comprehensive error handling
+- [x] Implement CLI argument parsing
+- [x] Implement MCP support
+- [ ] Add logging framework
+- [x] Create packaging configuration (pyproject.toml)
+- [x] Expand test coverage
+- [x] Add CI/CD pipeline
+- [x] Platform-specific socket detection (macOS complete)
+- [x] Add Linux connector
+- [ ] Add Windows connector
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+## 📄 License
+
+[Add your license here]
+
+## 🙋 Support
+
+For questions or issues, please open an issue on GitHub.
+
+---
+
+**Note**: This project is under active development. APIs may change between versions.