solace-agent-mesh 1.7.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/cli/commands/plugin_cmd/plugin_cmd_llm.txt

@@ -1,305 +0,0 @@
-# Plugin Command Module Analysis
-
-## 1. Primary Purpose and Functionality
-
-The `plugin_cmd` module provides a comprehensive CLI interface for managing SAM (Serverless Application Model) plugins. It enables users to:
-
-- **Create** new plugin projects with standardized structure and templates
-- **Add** plugin components from various sources (installed modules, local paths, Git repositories)
-- **Build** plugins into distributable packages
-- **Launch** a web-based plugin store interface
-
-The module follows a command-group pattern where all plugin-related operations are organized under the `sam plugin` command namespace.
-
-## 2. External Interfaces (APIs, Exports, Public Methods)
-
-### Main Command Group
-```python
-@click.group("plugin")
-def plugin() -> None
-```
-- **Purpose**: Root command group for all plugin operations
-- **Usage**: `sam plugin <subcommand>`
-
-### Subcommands
-- `sam plugin create <plugin_name>` - Create new plugin
-- `sam plugin add <component_name> --plugin <source>` - Add component from plugin
-- `sam plugin build [path]` - Build plugin package
-- `sam plugin store` - Launch plugin store web interface
-
-## 3. Key Dependencies and Imports
-
-### External Dependencies
-- `click` - CLI framework for command definitions and options
-- `pathlib` - Modern path handling
-- `subprocess` - External process execution (git, pip, python build)
-- `tempfile` - Temporary directory management
-- `shutil` - File operations and command existence checks
-- `toml` - TOML file parsing for pyproject.toml
-- `multiprocessing` - Process management for web server
-- `webbrowser` - Browser launching for plugin store
-
-### Internal Dependencies
-- `cli.utils` - Utility functions for name formatting, user interaction, templates
-- `cli.__version__` - CLI version information
-- `config_portal.backend.plugin_store_server` - Backend server for plugin store
-
-## 4. Data Structures and Models
-
-### Command Functions
-
-#### `create_plugin_cmd`
-```python
-@click.command("create")
-@click.argument("plugin_name_arg": str)
-@click.option("--author-name", "author_name_opt": str, help="Author's name.")
-@click.option("--author-email", "author_email_opt": str, help="Author's email.")
-@click.option("--description", "description_opt": str, help="Plugin description.")
-@click.option("--version", "version_opt": str, help="Initial plugin version.")
-@click.option("--skip", is_flag=True, help="Skip interactive prompts and use defaults or provided flags.")
-def create_plugin_cmd(plugin_name_arg: str, author_name_opt: str, author_email_opt: str, description_opt: str, version_opt: str, skip: bool) -> None
-```
-
-**Purpose**: Creates a new SAM plugin directory structure with interactive prompts for metadata.
-
-**Usage Example**:
-```bash
-# Interactive mode
-sam plugin create my-awesome-plugin
-
-# Non-interactive with options
-sam plugin create my-plugin --author-name "John Doe" --author-email "john@example.com" --skip
-```
-
-**Generated Structure**:
-- `my-awesome-plugin/`
-  - `config.yaml` - Plugin configuration template
-  - `pyproject.toml` - Python package configuration
-  - `README.md` - Documentation template
-  - `src/`
-    - `__init__.py` - Package initialization
-    - `tools.py` - Plugin tools implementation
-
-**Template Placeholders**:
-- `__PLUGIN_KEBAB_CASE_NAME__` - Plugin name in kebab-case
-- `__PLUGIN_SNAKE_CASE_NAME__` - Plugin name in snake_case
-- `__PLUGIN_SPACED_NAME__` - Plugin name with spaces
-- `__PLUGIN_CAMEL_CASE_NAME__` - Plugin name in camelCase
-- `__PLUGIN_AUTHOR_NAME__` - Author's name
-- `__PLUGIN_AUTHOR_EMAIL__` - Author's email
-- `__PLUGIN_DESCRIPTION__` - Plugin description
-- `__PLUGIN_VERSION__` - Plugin version
-
-
-#### `add_plugin_component_cmd`
-```python
-@click.command("add")
-@click.argument("component_name": str)
-@click.option("--plugin", "plugin_source": str, required=True, help="Plugin source: installed module name, local path, or Git URL.")
-def add_plugin_component_cmd(component_name: str, plugin_source: str, confirm_pip: bool) -> None
-```
-
-**Purpose**: Creates a new component instance from a specified plugin source.
-
-**Usage Examples**:
-```bash
-# From installed module
-sam plugin add my-component --plugin installed-plugin-name
-
-# From local path
-sam plugin add my-component --plugin ./path/to/plugin
-
-# From Git repository
-sam plugin add my-component --plugin https://github.com/user/plugin.git
-
-# Skip pip confirmation
-sam plugin add my-component --plugin ./local/plugin
-```
-
-**Plugin Source Types**:
-1. **Module**: Installed Python module (no slashes in name)
-2. **Local**: Local directory path (existing directory)
-3. **Git**: Git repository URL (starts with git+, http://, https:// and ends with .git)
-
-**Component Placeholders**:
-- `__COMPONENT_UPPER_SNAKE_CASE_NAME__` - Component name in UPPER_SNAKE_CASE
-- `__COMPONENT_KEBAB_CASE_NAME__` - Component name in kebab-case
-- `__COMPONENT_CAMEL_CASE_NAME__` - Component name in camelCase
-
-**Output**: Creates `configs/plugins/{component-name}.yaml` with processed plugin configuration.
-
-#### `build_plugin_cmd`
-```python
-@click.command("build")
-@click.argument("plugin_path_arg": str, type=click.Path(exists=True, file_okay=False, dir_okay=True, resolve_path=True), default=".", metavar="PLUGIN_PATH")
-def build_plugin_cmd(plugin_path_arg: str) -> None
-```
-
-**Purpose**: Builds the SAM plugin in the specified directory using Python's build module.
-
-**Usage Examples**:
-```bash
-# Build current directory
-sam plugin build
-
-# Build specific directory
-sam plugin build ./my-plugin-directory
-```
-
-**Requirements**:
-- `pyproject.toml` must exist in target directory
-- `build` package must be installed (`pip install build`)
-
-**Output**: Creates `dist/` directory with built artifacts (wheel and source distribution).
-
-#### `store`
-```python
-@click.command("store")
-@click.option('--port', default=5003, type=int, show_default=True, help="Port to run the plugin store web server on.")
-def store(port: int) -> None
-```
-
-**Purpose**: Launches the SAM Plugin Store web interface.
-
-**Usage Examples**:
-```bash
-# Default port (5003)
-sam plugin store
-
-# Custom port
-sam plugin store --port 8080
-```
-
-**Behavior**:
-- Starts Flask backend server in separate process
-- Opens web browser to plugin store interface
-- Handles graceful shutdown on Ctrl+C
-- Uses multiprocessing for process management
-
-### Helper Functions
-
-#### `ensure_directory_exists`
-```python
-def ensure_directory_exists(path: pathlib.Path) -> None
-```
-**Purpose**: Creates a directory if it doesn't exist.
-**Parameters**: `path` - Path object for directory to create
-**Usage**: Used internally for creating plugin directory structures.
-
-#### `replace_placeholders`
-```python
-def replace_placeholders(content: str, replacements: dict) -> str
-```
-**Purpose**: Replaces placeholders in template content.
-**Parameters**: 
-- `content` - Template string with placeholders
-- `replacements` - Dictionary mapping placeholders to values
-**Returns**: Processed content with placeholders replaced
-
-#### `_check_command_exists`
-```python
-def _check_command_exists(command: str) -> bool
-```
-**Purpose**: Checks if a command exists on the system.
-**Parameters**: `command` - Command name to check
-**Returns**: True if command is available, False otherwise
-
-#### `_get_plugin_name_from_source_pyproject`
-```python
-def _get_plugin_name_from_source_pyproject(source_path: pathlib.Path) -> str | None
-```
-**Purpose**: Reads pyproject.toml from source path and returns the project name.
-**Parameters**: `source_path` - Path to directory containing pyproject.toml
-**Returns**: Normalized project name (snake_case) or None if not found
-
-#### `_run_pip_install`
-```python
-def _run_pip_install(install_target: str | pathlib.Path, operation_desc: str) -> str | None
-```
-**Purpose**: Runs pip install for the given target.
-**Parameters**:
-- `install_target` - Path or URL to install
-- `operation_desc` - Description for user feedback
-**Returns**: None on success, error message string on failure
-
-#### `run_flask_plugin_store`
-```python
-def run_flask_plugin_store(host: str, port: int, shared_data: dict) -> None
-```
-**Purpose**: Starts the Flask backend server for plugin store.
-**Parameters**:
-- `host` - Server host address
-- `port` - Server port number
-- `shared_data` - Multiprocessing shared dictionary for status communication
-
-### Configuration Objects
-
-#### Default Values
-```python
-DEFAULT_AUTHOR_NAME = "Your Name"
-DEFAULT_AUTHOR_EMAIL = "your.email@example.com"
-DEFAULT_PLUGIN_VERSION = "0.1.0"
-```
-
-#### Template Requirements
-The module expects these template files to exist:
-- `plugin_config_template.yaml` - Plugin configuration template
-- `plugin_pyproject_template.toml` - Python package configuration template
-- `plugin_tools_template.py` - Plugin tools implementation template
-- `plugin_readme_template.md` - Documentation template
-
-## 5. Architecture Patterns Used
-
-### Command Pattern
-- Each subcommand is implemented as a separate module with a single command function
-- Commands are registered with the main plugin group in `__init__.py`
-
-### Template Pattern
-- Uses template files with placeholder replacement for generating plugin scaffolding
-- Consistent placeholder naming convention across all templates
-
-### Strategy Pattern
-- Different installation strategies for plugin sources (module, local, git)
-- Conditional logic based on source type detection
-
-### Process Management Pattern
-- Uses multiprocessing for running web server in separate process
-- Shared data structures for inter-process communication
-
-### Error Handling Pattern
-- Consistent error handling with `error_exit()` utility function
-- Graceful degradation with user-friendly error messages
-
-## 6. Integration Points with Other Systems
-
-### CLI Framework Integration
-- Integrates with Click framework for command-line interface
-- Uses `cli.utils` for common functionality (name formatting, user interaction, template loading)
-
-### Package Management Integration
-- Integrates with pip for plugin installation
-- Supports Git repositories for plugin sources
-- Uses Python's build system for plugin packaging
-
-### Web Interface Integration
-- Launches Flask-based web server for plugin store
-- Integrates with browser for user interface
-- Uses multiprocessing for server management
-
-### File System Integration
-- Creates and manages plugin directory structures
-- Reads and writes configuration files (YAML, TOML)
-- Handles temporary directories for Git operations
-
-### Template System Integration
-- Loads templates from template directory
-- Processes placeholders for dynamic content generation
-- Supports multiple template formats (YAML, TOML, Python, Markdown)
-
-### External Tool Integration
-- Git for repository cloning
-- Python build tools for package creation
-- Pip for package installation
-- System commands through subprocess
-
-The module provides a comprehensive plugin management system that integrates seamlessly with the broader SAM CLI ecosystem while maintaining clear separation of concerns and robust error handling.