anyscale 0.26.52__tar.gz → 0.26.53__tar.gz

anyscale-0.26.53/.cursor/README.mdc

@@ -0,0 +1,195 @@
+---
+description: Comprehensive CLI development documentation hub for the Anyscale CLI and SDK
+globs:
+  - frontend/cli/**/*
+alwaysApply: false
+---
+
+# Anyscale CLI Documentation
+
+This directory contains comprehensive documentation for developing, testing, and maintaining the Anyscale CLI and SDK.
+
+## 📚 Documentation Structure
+
+### Core References
+
+#### [rules.mdc](./rules.mdc) ⭐ **Always Active**
+Quick reference and task mapping for CLI development
+- Essential commands and patterns
+- Task-to-documentation mapping
+- Core principles and common mistakes
+- **Always loaded** for immediate reference
+
+#### [architecture.mdc](./architecture.mdc)
+System design and component interactions
+- Layered architecture (CLI → SDK → Client → API)
+- Directory structure
+- Data flow patterns
+- Component responsibilities
+
+### Development Workflow
+
+#### [workflow-simple.mdc](./workflow-simple.mdc)
+Step-by-step guide for adding features
+- Quick development workflow
+- Adding new features checklist
+- Testing and deployment steps
+
+#### [development.mdc](./development.mdc)
+Detailed development patterns
+- SDK implementation patterns
+- CLI command structure
+- Model definitions
+- Auto-attaches when working with commands
+
+#### [api-client.mdc](./api-client.mdc)
+OpenAPI client integration
+- Client generation process
+- Adding new endpoints
+- Error handling patterns
+- Auto-attaches for client code
+
+### Code Quality
+
+#### [style-guide.mdc](./style-guide.mdc)
+Python conventions and standards
+- Naming conventions
+- Import organization
+- Documentation standards
+- Auto-attaches for all Python files
+
+#### [testing.mdc](./testing.mdc)
+Testing patterns and commands
+- Unit test structure
+- Mock patterns
+- Test organization
+- Auto-attaches for test files
+
+#### [testing-guide.mdc](./testing-guide.mdc)
+Practical testing workflow
+- Local development setup
+- Running and debugging tests
+- Common test patterns
+
+### Features & Patterns
+
+#### [authentication.mdc](./authentication.mdc)
+Auth flow and credential management
+- Token storage
+- Security rules
+- Testing auth
+- Auto-attaches for auth-related code
+
+#### [error-handling.mdc](./error-handling.mdc)
+Exception handling and user messages
+- Error hierarchy
+- User-friendly messages
+- Validation patterns
+- Auto-attaches for all Python files
+
+#### [telemetry.mdc](./telemetry.mdc)
+Usage tracking and privacy
+- Event collection
+- Privacy rules
+- Custom events
+- Auto-attaches for command files
+
+#### [cloud-providers.mdc](./cloud-providers.mdc)
+Cloud abstraction patterns
+- AWS, GCP, Azure support
+- Cloud configuration
+- Provider-specific features
+- Auto-attaches for cloud-related code
+
+## 🚀 Quick Start
+
+### New to CLI Development?
+1. Start with [rules.mdc](./rules.mdc) for overview
+2. Review [architecture.mdc](./architecture.mdc) to understand the system
+3. Follow [workflow-simple.mdc](./workflow-simple.mdc) for your first feature
+
+### Adding a Feature
+1. Check task mapping in [rules.mdc](./rules.mdc)
+2. Follow workflow in [workflow-simple.mdc](./workflow-simple.mdc)
+3. Reference [development.mdc](./development.mdc) for patterns
+4. Write tests using [testing.mdc](./testing.mdc)
+
+### Debugging Issues
+- Auth problems → [authentication.mdc](./authentication.mdc)
+- API errors → [error-handling.mdc](./error-handling.mdc)
+- Client generation → [api-client.mdc](./api-client.mdc)
+- Cloud issues → [cloud-providers.mdc](./cloud-providers.mdc)
+
+## 🔑 Key Commands
+
+```bash
+# Install CLI for development
+cd frontend/cli && pip install -e .
+
+# Run all tests
+bazelisk test //frontend/cli/tests/unit/... --test_output=all
+
+# Regenerate API clients
+cd frontend/web && npm run build-api
+
+# Debug mode
+export ANYSCALE_DEBUG=1
+
+# Check auth
+anyscale auth show
+```
+
+## 📋 Rule Configuration
+
+All documentation files follow [Cursor's rule best practices](https://docs.cursor.com/en/context/rules#rule-anatomy):
+
+| Rule | Type | When Applied |
+|------|------|-------------|
+| **rules.mdc** | Always Active | Constant reference for commands and patterns |
+| **architecture.mdc** | Auto-attach | When working with system design |
+| **style-guide.mdc** | Auto-attach | All Python files |
+| **testing.mdc** | Auto-attach | Test files |
+| **authentication.mdc** | Auto-attach | Auth-related code |
+| **error-handling.mdc** | Auto-attach | Python implementation files |
+| **api-client.mdc** | Auto-attach | Client/OpenAPI code |
+| Others | Manual/Context | As needed or AI-requested |
+
+## 🏗️ CLI Architecture Overview
+
+```
+User Input
+    ↓
+CLI Layer (Click)           # User interface, argument parsing
+    ↓
+SDK Layer                   # Business logic, orchestration
+    ↓
+AnyscaleClient Wrapper      # Auth, error normalization
+    ↓
+OpenAPI Generated Clients   # Auto-generated from FastAPI
+    ↓
+Backend API                 # FastAPI services
+```
+
+## 🤝 Contributing
+
+When updating documentation:
+1. Follow MDC format with proper metadata headers
+2. Keep files under 500 lines
+3. Include practical examples
+4. Update this README if adding new files
+5. Test all code examples before committing
+
+## 💡 Tips
+
+- **SDK-first**: Always implement in SDK, wrap in CLI
+- **Type everything**: Full type hints required
+- **Never edit generated code**: Regenerate from OpenAPI specs
+- **Test both layers**: SDK and CLI need separate tests
+- **Clear errors**: No stack traces to users
+
+## 📊 Development Metrics
+
+- **Files**: 12 comprehensive guides
+- **Coverage**: Architecture, development, testing, deployment
+- **Auto-attachment**: Smart context loading based on file patterns
+- **Always Available**: Quick reference via rules.mdc

{anyscale-0.26.52 → anyscale-0.26.53}/.cursor/api-client.mdc

@@ -1,10 +1,10 @@
 ---
-type: auto-attached
+description: OpenAPI client generation and API integration patterns - client wrapper and endpoint extension
 globs:
-  - "**/anyscale_client/**/*.py"
-  - "**/openapi_client/**/*.py"
-  - "**/anyscale/client/**/*.py"
-description: OpenAPI client generation and API integration patterns
+  - frontend/cli/**/anyscale_client/**/*.py
+  - frontend/cli/**/openapi_client/**/*.py
+  - frontend/cli/anyscale/client/**/*.py
+alwaysApply: false
 ---
 
 # API Client Integration

{anyscale-0.26.52 → anyscale-0.26.53}/.cursor/architecture.mdc

@@ -1,6 +1,9 @@
 ---
-type: agent-requested
-description: System architecture and data flow patterns for the Anyscale CLI
+description: System architecture and data flow patterns for the Anyscale CLI - layered design and component interactions
+globs:
+  - frontend/cli/anyscale/**/*.py
+  - frontend/cli/anyscale/_private/**/*.py
+alwaysApply: false
 ---
 
 # Architecture

{anyscale-0.26.52 → anyscale-0.26.53}/.cursor/authentication.mdc

@@ -1,10 +1,10 @@
 ---
-type: auto-attached
+description: Authentication flow and credential management for CLI and SDK
 globs:
-  - "**/authenticate.py"
-  - "**/auth*.py"
-  - "**/controllers/auth_*.py"
-description: Authentication flow and credential management
+  - frontend/cli/**/authenticate.py
+  - frontend/cli/**/auth*.py
+  - frontend/cli/**/controllers/auth_*.py
+alwaysApply: false
 ---
 
 # Authentication

{anyscale-0.26.52 → anyscale-0.26.53}/.cursor/cloud-providers.mdc

@@ -1,11 +1,11 @@
 ---
-type: auto-attached
+description: Cloud provider abstractions and implementations - AWS, GCP, and Azure support patterns
 globs:
-  - "**/cloud*.py"
-  - "**/aws*.py"
-  - "**/gcp*.py"
-  - "**/anyscale-cloud-setup*.yaml"
-description: Cloud provider abstractions and implementations
+  - frontend/cli/**/cloud*.py
+  - frontend/cli/**/aws*.py
+  - frontend/cli/**/gcp*.py
+  - frontend/cli/**/anyscale-cloud-setup*.yaml
+alwaysApply: false
 ---
 
 # Cloud Providers

anyscale-0.26.53/.cursor/development.mdc

@@ -0,0 +1,190 @@
+---
+description: Development workflow and patterns for adding new CLI features - SDK-first approach
+globs:
+  - frontend/cli/anyscale/commands/*.py
+  - frontend/cli/anyscale/*/commands.py
+  - frontend/cli/anyscale/*/_private/*_sdk.py
+  - frontend/cli/**/scripts.py
+  - frontend/cli/anyscale/_private/docgen/__main__.py
+alwaysApply: false
+---
+
+# Development Guide
+
+## Adding a New Feature
+
+### 1. SDK Implementation
+```python
+# anyscale/<module>/commands.py
+from anyscale._private.sdk import sdk_command
+
+@sdk_command(
+    singleton_key="module_sdk",
+    sdk_class=PrivateModuleSDK,
+    doc_py_example=EXAMPLE,
+    arg_docstrings=ARG_DOCS,
+)
+def create_resource(
+    name: str,
+    *,  # Force keyword-only
+    config: Optional[dict] = None,
+    wait: bool = False,
+    _private_sdk: Optional[PrivateModuleSDK] = None
+) -> ResourceModel:
+    """Create a resource."""
+    return _private_sdk.create(name, config, wait)
+```
+
+### 2. CLI Command
+```python
+# anyscale/commands/<module>_commands.py
+@click.command()
+@click.option("--name", required=True)
+@click.option("--config", type=click.Path(exists=True))
+@click.option("--wait/--no-wait", default=False)
+def create(name: str, config: Optional[str], wait: bool):
+    """Create a new resource."""
+    config_dict = None
+    if config:
+        with open(config) as f:
+            config_dict = yaml.safe_load(f)
+
+    try:
+        result = sdk.create_resource(name, config=config_dict, wait=wait)
+        click.echo(f"Created: {result.id}")
+    except Exception as e:
+        raise click.ClickException(str(e))
+```
+
+### 3. Register for Documentation (IMPORTANT!)
+```python
+# anyscale/_private/docgen/__main__.py
+
+# Add your module to ALL_MODULES list:
+ALL_MODULES = [
+    # ... existing modules ...
+    Module(
+        title="Your Feature",
+        filename="your-feature.md",
+        cli_prefix="anyscale your-feature",
+        cli_commands=[
+            your_commands.create,
+            your_commands.get,
+            your_commands.list,
+            your_commands.delete,
+        ],
+        sdk_prefix="anyscale.your_feature",
+        sdk_commands=[
+            anyscale.your_feature.create,
+            anyscale.your_feature.get,
+            anyscale.your_feature.list,
+            anyscale.your_feature.delete,
+        ],
+        models=[
+            YourConfig,
+            YourStatus,
+            YourModel,
+        ],
+        # Optional: legacy command mappings
+        legacy_sdk_commands={
+            "old_create": anyscale.your_feature.create,
+        },
+    ),
+]
+```
+
+### 4. Add Tests
+```python
+# tests/unit/test_<module>_cli.py
+def test_create(runner, mock_sdk):
+    mock_sdk.create_resource.return_value = Mock(id="res_123")
+
+    result = runner.invoke(cli, ["create", "--name", "test"])
+
+    assert result.exit_code == 0
+    assert "res_123" in result.output
+    mock_sdk.create_resource.assert_called_once_with("test", config=None, wait=False)
+```
+
+## AnyscaleClient Extension
+
+When adding new API endpoints:
+
+### 1. Interface Definition
+```python
+# anyscale/_private/anyscale_client/common.py
+from abc import abstractmethod
+
+class AnyscaleClientInterface(ABC):
+    @abstractmethod
+    def new_api_method(self, *, param: str) -> dict:
+        raise NotImplementedError
+```
+
+### 2. Implementation
+```python
+# anyscale/_private/anyscale_client/anyscale_client.py
+@handle_api_exceptions
+def new_api_method(self, *, param: str) -> dict:
+    return self._internal_api.endpoint(param=param)
+```
+
+### 3. Fake Client
+```python
+# anyscale/_private/anyscale_client/fake_anyscale_client.py
+def new_api_method(self, *, param: str) -> dict:
+    return {"id": "fake_123", "status": "success"}
+```
+
+## Model Definition
+```python
+# anyscale/<module>/models.py
+from pydantic import BaseModel, Field
+
+class ResourceConfig(BaseModel):
+    name: str = Field(..., description="Resource name")
+    replicas: int = Field(1, ge=1, le=100, description="Number of replicas")
+
+    class Config:
+        extra = "forbid"  # Reject unknown fields
+```
+
+## Regenerate API Clients
+
+After backend changes:
+```bash
+cd frontend/web
+npm run build-api
+
+# This regenerates:
+# - anyscale/client/openapi_client/  # Internal API
+# - anyscale/sdk/anyscale_client/    # External API
+```
+
+## Testing Workflow
+
+```bash
+# Install locally
+pip install -e frontend/cli
+
+# Test manually
+anyscale your-feature create --name test
+
+# Run unit tests
+bazelisk test //frontend/cli/tests/unit:test_your_feature_cli
+
+# Generate docs
+python -m anyscale._private.docgen ./docs
+```
+
+## Checklist for New Features
+
+- [ ] SDK function in `anyscale/<module>/commands.py`
+- [ ] CLI command in `anyscale/commands/<module>_commands.py`
+- [ ] Models in `anyscale/<module>/models.py`
+- [ ] **Register in `docgen/__main__.py`** ⚠️
+- [ ] Client extension if new API needed
+- [ ] Unit tests for SDK and CLI
+- [ ] Integration tests if complex
+- [ ] Manual testing locally
+- [ ] Documentation generated

{anyscale-0.26.52 → anyscale-0.26.53}/.cursor/error-handling.mdc

@@ -1,8 +1,8 @@
 ---
-type: auto-attached
+description: Error handling patterns and user-friendly messages - exception hierarchy and error flows
 globs:
-  - "**/anyscale/**/*.py"
-description: Error handling patterns and user-friendly messages
+  - frontend/cli/anyscale/**/*.py
+alwaysApply: false
 ---
 
 # Error Handling

anyscale-0.26.53/.cursor/rules.mdc

@@ -0,0 +1,52 @@
+---
+description: Main rules and quick reference for Anyscale CLI development - essential commands and task mapping
+globs:
+alwaysApply: true
+---
+
+# CLI Rules
+
+## Task → Documentation
+
+| Task | Primary Doc | Secondary |
+|------|-------------|-----------|
+| Add feature | `workflow-simple.mdc` | `development.mdc` |
+| Fix API errors | `error-handling.mdc` | `api-client.mdc` |
+| Write tests | `testing.mdc` | `testing-guide.mdc` |
+| Debug auth | `authentication.mdc` | - |
+| Add telemetry | `telemetry.mdc` | - |
+| Cloud work | `cloud-providers.mdc` | - |
+| Code style | `style-guide.mdc` | - |
+| System design | `architecture.mdc` | - |
+
+## Quick Commands
+```bash
+bazelisk test //frontend/cli/tests/unit/... --test_output=all
+cd frontend/web && npm run build-api  # Regenerate API
+export ANYSCALE_DEBUG=1               # Debug mode
+```
+
+## Core Principles
+1. **SDK-first**: Business logic in SDK, CLI is thin wrapper
+2. **Type safety**: Always use type hints
+3. **No breaking changes**: Add optional params, deprecate carefully
+4. **Clear errors**: No stack traces to users
+5. **Test everything**: Unit tests required
+
+## Common Mistakes
+❌ **Forget to register in docgen/__main__.py**
+✅ Add Module() entry for documentation generation
+
+❌ Access `client._internal_api_client` directly
+✅ Use typed interface methods
+
+❌ Edit generated code in `openapi_client/`
+✅ Regenerate with `npm run build-api`
+
+❌ Business logic in CLI layer
+✅ Logic in SDK, CLI wraps it
+
+## Architecture
+```
+User → CLI (Click) → SDK → AnyscaleClient → OpenAPI → Backend
+```

anyscale-0.26.53/.cursor/style-guide.mdc

@@ -0,0 +1,127 @@
+---
+description: Python code style, naming conventions, and documentation standards for CLI development
+globs:
+  - frontend/cli/**/*.py
+alwaysApply: false
+---
+
+# Style Guide
+
+## Naming
+```python
+class ServiceController:     # PascalCase
+def create_service():       # snake_case
+MAX_RETRIES = 3            # UPPER_SNAKE_CASE
+def _internal_helper():     # Leading underscore for private
+```
+
+## Imports
+```python
+# Standard library
+import os
+from typing import Optional, List
+
+# Third party
+import click
+from pydantic import BaseModel
+
+# Local - absolute imports
+from anyscale.service.models import ServiceConfig
+```
+
+## Type Hints (Required)
+```python
+def process(
+    items: List[str],
+    transform: Optional[Callable[[str], str]] = None
+) -> List[str]:
+    """Process items with optional transform."""
+    pass
+```
+
+## CLI Patterns
+```bash
+anyscale <resource> <action> [options]
+anyscale service deploy --name my-app
+```
+
+### Common Options
+```python
+@click.option("--name", required=True, help="Resource name")
+@click.option("--config", type=click.Path(exists=True))
+@click.option("--wait/--no-wait", default=False)
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@click.option("--format", type=click.Choice(["table", "json", "yaml"]))
+```
+
+## SDK Pattern
+```python
+@sdk_command(
+    singleton_key="service_sdk",
+    sdk_class=PrivateServiceSDK,
+)
+def deploy(
+    config: ServiceConfig,
+    *,  # Force keyword-only
+    wait: bool = False,
+    _private_sdk: Optional[PrivateServiceSDK] = None
+) -> str:
+    """Deploy a service."""
+    return _private_sdk.deploy(config, wait)
+```
+
+## Models
+```python
+from pydantic import BaseModel, Field
+
+class ServiceConfig(BaseModel):
+    name: str = Field(..., description="Service name")
+    replicas: int = Field(1, ge=1, le=100)
+
+    class Config:
+        extra = "forbid"  # Reject unknown fields
+```
+
+## Error Messages
+✅ **Good**: "Service 'my-app' not found. List services: anyscale service list"
+❌ **Bad**: "Error: 404" or "Operation failed"
+
+## Documentation
+```python
+def public_function(param: str) -> Result:
+    """
+    Brief description.
+
+    Args:
+        param: Description
+
+    Returns:
+        What it returns
+
+    Raises:
+        ValueError: When invalid
+
+    Examples:
+        >>> public_function("test")
+        Result(...)
+    """
+    pass
+```
+
+## Comments
+```python
+# ✅ Explains WHY, not WHAT
+# Skip first item - contains headers from legacy format
+items = items[1:]
+
+# ❌ States the obvious
+# Remove first item
+items = items[1:]
+```
+
+## Best Practices
+1. **Type everything** - No untyped functions
+2. **Keyword-only args** - Use `*` separator
+3. **Descriptive names** - Avoid abbreviations
+4. **Early validation** - Check before API calls
+5. **Consistent patterns** - Follow existing code

{anyscale-0.26.52 → anyscale-0.26.53}/.cursor/telemetry.mdc

@@ -1,9 +1,9 @@
 ---
-type: auto-attached
+description: Telemetry implementation and privacy guidelines - tracking patterns and custom events
 globs:
-  - "**/telemetry.py"
-  - "**/anyscale/commands/*.py"
-description: Telemetry implementation and privacy guidelines
+  - frontend/cli/**/telemetry.py
+  - frontend/cli/anyscale/commands/*.py
+alwaysApply: false
 ---
 
 # Telemetry

{anyscale-0.26.52 → anyscale-0.26.53}/.cursor/testing-guide.mdc

@@ -1,6 +1,7 @@
 ---
-type: manual
-description: Practical testing guide for CLI development
+description: Practical testing guide for CLI development - local testing, debugging, and test patterns
+globs:
+alwaysApply: false
 ---
 
 # Testing Guide

{anyscale-0.26.52 → anyscale-0.26.53}/.cursor/testing.mdc

@@ -1,9 +1,9 @@
 ---
-type: auto-attached
+description: Testing patterns and commands for CLI tests - unit test structure and mock patterns
 globs:
-  - "**/tests/**/*.py"
-  - "**/test_*.py"
-description: Testing patterns and commands for CLI tests
+  - frontend/cli/tests/**/*.py
+  - frontend/cli/**/test_*.py
+alwaysApply: false
 ---
 
 # Testing