pan-scm-cli — Windsurf Rules

instruction 1: Use Python 3.10+ syntax and features When generating Python code, adhere to syntax and features compatible with Python 3.10 or higher (up to 3.13), as specified in pyproject.toml (python = ">=3.10,<3.14"). Avoid deprecated features from earlier versions (e.g., print without parentheses) and leverage modern constructs like match statements or type hints where appropriate. instruction 2: Structure code under src/scm_cli/ package Place all Python code within the src/scm_cli/ directory, following the project’s package structure (packages = [{include = "scm_cli", from = "src"}]). For example, new modules like config.py should be src/scm_cli/config.py, and imports should use relative paths (e.g., from .client import get_scm_client). instruction 3: Integrate Typer for CLI commands Use the typer library (version 0.15.2) for all CLI command definitions. Commands should be defined with typer.Typer() instances, follow the pattern <action> <object-type> <object> [options], and include options with clear help text (e.g., folder: str = typer.Option(..., "--folder", help="Folder name")). instruction 4: Use Dynaconf for configuration management For configuration-related code, utilize dynaconf>=3.2.10 as the configuration loader. Access settings with settings.get("key"), prefix environment variables with SCM_, and load from ~/.scm-cli/config.yaml using settings_files=[Path.home() / ".scm-cli" / "config.yaml"]. instruction 5: Leverage pan-scm-sdk for SCM interactions When interacting with Strata Cloud Manager, use the pan_scm_sdk==0.3.39 library. Initialize the client with StrataCloudManager(client_id, client_secret, tsg_id) and call methods like create_address() directly, avoiding custom HTTP requests or alternative SDKs. instruction 6: Implement mock mode with a MockSCMClient class Support a --mock option in commands by returning a MockSCMClient class when mock=True. Implement this class with __getattr__ to simulate API responses (e.g., {"status": "success", "message": "Mock call"}), ensuring no real API calls are made in mock mode. instruction 7: Validate data with Pydantic models where applicable For complex data structures (e.g., address objects), define Pydantic models (version 2.7.1) with type hints (e.g., class Address(BaseModel): name: str). Use these models to validate input before passing to pan-scm-sdk methods. instruction 8: Follow Ruff linting and formatting rules Adhere to the linting rules in pyproject.toml under [tool.ruff]. Use a line length of 192, enable checks like E, F, I, and ignore D203, D213. Format code to match ruff standards (e.g., make format) and avoid unused imports in __init__.py. instruction 9: Include docstrings with examples Add docstrings to all functions and classes following Python conventions. Include an "Examples" section where relevant (e.g., in get_scm_client() docstring: "Examples: client = get_scm_client(mock=True) returns a mock client"). instruction 10: Use Poetry for dependency management When suggesting new dependencies, add them to pyproject.toml under [tool.poetry.dependencies] or [tool.poetry.group.dev.dependencies]. Install with poetry add <package> and avoid direct pip install calls in code or documentation. instruction 11: Output user-friendly messages with Typer Use typer.echo() for all CLI output. Ensure messages are clear and consistent (e.g., "Address {name} created: {response}"), and avoid raw print() statements or unformatted error dumps. instruction 12: Support YAML file loading with PyYAML For bulk operations (e.g., load commands), use pyyaml>=6.0 to parse YAML files. Load files with yaml.safe_load() and expect structures like {"addresses": [{"name": "..."}]} as shown in the README examples. instruction 13: Align with README command examples Ensure generated commands match the README’s structure and options (e.g., scm-cli set objects address --folder Shared --name web-server --ip-netmask 192.168.1.100/32). Suggest options like --description or --tags where applicable. instruction 14: Add tests in tests/ directory Place test files in the tests/ directory with names like test_config.py. Use pytest>=7.4.0 conventions (test_* functions), mark tests as unit or integration, and follow [tool.pytest.ini_options] from pyproject.toml. instruction 15: Avoid direct file system modifications outside config Limit file system interactions to reading ~/.scm-cli/config.yaml for authentication. Avoid writing files or modifying system paths unless explicitly required by a command (e.g., loading a user-provided YAML file). instruction 16: Use context-based authentication as primary method Implement and use the context management system for multi-tenant authentication. Context commands should include: create, list, use, delete, show, current, and test. Store contexts in ~/.scm-cli/contexts/ with secure permissions (600). The authentication precedence order is: 1) Active context (from scm context use), 2) Environment variables (SCM_CLIENT_ID, etc.), 3) Default configuration. Never use ~/.scm-cli/config.yaml or .secrets.yaml for authentication as these are deprecated. instruction 17: Handle Docker container integration Support volume mounting for contexts when running in Docker containers. The standard mount is -v ~/.scm-cli:/home/scmuser/.scm-cli. Ensure all context operations work identically in containers and on host systems. Docker images should never contain hardcoded credentials. instruction 18: Log context usage information When log level is INFO or higher, display which authentication context is being used with show_context_info() helper. Include messages like "[INFO] Using authentication context: production" to provide clear visibility into which tenant is being accessed.