Project-Specific Rules for Windsurf/Cursor IDEs: pan-scm-cli

# Project-Specific Rules for Windsurf/Cursor IDEs: `pan-scm-cli`

**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.