ciderstack 0.1.0__tar.gz

ciderstack-0.1.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: ciderstack
+Version: 0.1.0
+Summary: CiderStack Fleet SDK for Python
+Home-page: https://ciderstack.io
+Author: CiderStack
+Author-email: support@ciderstack.io
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28.0
+Provides-Extra: pairing
+Requires-Dist: cryptography>=41.0.0; extra == "pairing"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

ciderstack-0.1.0/README.md

@@ -0,0 +1,211 @@
+# CiderStack Fleet SDK for Python
+
+A Python client for managing macOS VMs across CiderStack Fleet nodes.
+
+## Installation
+
+```bash
+pip install ciderstack
+```
+
+Or install from source:
+
+```bash
+cd sdk/python
+pip install -e .
+```
+
+For pairing support (optional — not needed if using API tokens):
+
+```bash
+pip install -e ".[pairing]"
+```
+
+## Authentication
+
+All API calls require authentication. Two methods are available:
+
+### API Tokens (recommended)
+
+The simplest way to authenticate. Generate a token from the CiderStack CLI or app, then pass it to the client:
+
+```python
+from ciderstack import FleetClient
+
+client = FleetClient("192.168.1.100", api_token="csk_abc123...")
+```
+
+Tokens can be **read-only** (can only list/get data) or **full-access** (can also start/stop/delete VMs, etc.).
+
+### Node ID (via pairing)
+
+For advanced use cases, you can pair the SDK as a fleet node using a 6-digit code from the CiderStack UI:
+
+```python
+from ciderstack import FleetClient
+
+# One-time pairing (requires `cryptography` package)
+creds = FleetClient.pair("192.168.1.100", "123456", "my-ci-script")
+print(f"Save this node ID: {creds['node_id']}")
+
+# Use the node ID for all future connections
+client = FleetClient("192.168.1.100", node_id=creds["node_id"])
+```
+
+## Quick Start
+
+```python
+from ciderstack import FleetClient
+
+client = FleetClient("192.168.1.100", api_token="csk_abc123...")
+
+# List VMs
+vms = client.list_vms()
+for vm in vms:
+    print(f"{vm.name}: {vm.state}")
+
+# Start a VM
+client.start_vm("vm-uuid")
+
+# Execute a command
+result = client.exec_command(
+    vm_id="vm-uuid",
+    command="uname -a",
+    ssh_user="admin",
+    ssh_password="password"
+)
+print(result.stdout)
+```
+
+## Examples
+
+### VM Management
+
+```python
+# Clone a VM
+new_vm = client.clone_vm("vm-uuid", "my-clone")
+
+# Update VM settings
+client.update_vm_settings(
+    vm_id="vm-uuid",
+    cpu_count=8,
+    memory_size=16384  # 16 GB
+)
+
+# Delete a VM
+client.delete_vm("vm-uuid")
+```
+
+### Snapshots
+
+```python
+# Create a snapshot
+snapshot = client.create_snapshot(
+    vm_id="vm-uuid",
+    name="pre-update",
+    description="Before system update"
+)
+
+# List snapshots
+snapshots = client.list_snapshots("vm-uuid")
+
+# Restore snapshot
+client.restore_snapshot("vm-uuid", snapshot.id)
+```
+
+### Fleet Overview
+
+```python
+# Get cluster-wide status
+raw = client.get_fleet_overview()
+stats = raw["overview"]["stats"]
+print(f"Total nodes: {stats['totalNodes']}")
+print(f"Running VMs: {stats['runningVMs']}")
+
+# Get node stats
+stats = client.get_node_stats()
+print(f"CPU: {stats.cpu_usage_percent}%")
+print(f"Memory: {stats.memory_used_gb}/{stats.memory_total_gb} GB")
+```
+
+### Image Management
+
+```python
+# Pull an OCI image
+client.pull_oci_image("ghcr.io/myorg/macos-base:latest")
+
+# Create a VM from image
+vm_id = client.create_vm(
+    name="ci-runner",
+    cpu_count=4,
+    memory_mb=8192,
+    disk_gb=64,
+    oci_image="ghcr.io/myorg/macos-base:latest"
+)
+```
+
+## API Reference
+
+### FleetClient
+
+```python
+FleetClient(host, node_id=None, api_token=None, port=9473, timeout=30)
+```
+
+| Parameter   | Type  | Default | Description                              |
+|-------------|-------|---------|------------------------------------------|
+| `host`      | `str` | —       | IP address or hostname                   |
+| `node_id`   | `str` | `None`  | Trusted node ID (from pairing)           |
+| `api_token` | `str` | `None`  | API token (from CiderStack CLI/UI)       |
+| `port`      | `int` | `9473`  | Port number                              |
+| `timeout`   | `int` | `30`    | Request timeout in seconds               |
+
+Provide exactly one of `node_id` or `api_token`.
+
+**Node Info**
+- `get_node_info()` -> NodeInfo
+- `get_node_stats()` -> NodeStats
+
+**VM Management**
+- `list_vms()` -> List[VM]
+- `get_vm(vm_id)` -> VM | None
+- `start_vm(vm_id)` -> bool
+- `stop_vm(vm_id)` -> bool
+- `start_vm_recovery(vm_id)` -> bool
+- `clone_vm(vm_id, new_name)` -> VM
+- `rename_vm(vm_id, new_name)` -> bool
+- `delete_vm(vm_id)` -> bool
+- `get_vm_settings(vm_id)` -> Dict
+- `update_vm_settings(vm_id, ...)` -> bool
+
+**Snapshots**
+- `list_snapshots(vm_id)` -> List[Snapshot]
+- `create_snapshot(vm_id, name, description)` -> Snapshot
+- `restore_snapshot(vm_id, snapshot_id)` -> bool
+- `delete_snapshot(vm_id, snapshot_id)` -> bool
+
+**Command Execution**
+- `exec_command(vm_id, command, ssh_user, ssh_password, timeout=300)` -> ExecResult (timeout in seconds; default 300 for long-running steps like artifact download)
+
+**Tasks**
+- `get_tasks(include_completed)` -> List[Task]
+
+**Images**
+- `push_image(vm_id, image_name, insecure)` -> str
+- `list_ipsws()` -> List[Dict]
+- `list_oci_images()` -> List[Dict]
+- `download_ipsw(url, name, version)` -> bool
+- `pull_oci_image(image_reference, username, password)` -> bool
+- `create_vm(name, cpu_count, memory_mb, disk_gb, ipsw_path, oci_image)` -> str
+
+**Fleet**
+- `get_fleet_overview()` -> Dict
+- `get_fleet_events(limit, event_type)` -> List[Dict]
+- `get_remote_resources()` -> Dict
+
+**Pairing** (static method, requires `cryptography`)
+- `FleetClient.pair(host, code, name, port)` -> Dict
+
+## License
+
+MIT

ciderstack-0.1.0/ciderstack/__init__.py

@@ -0,0 +1,32 @@
+"""
+CiderStack Fleet SDK for Python
+
+A Python client for managing macOS VMs across CiderStack Fleet nodes.
+
+Example:
+    from ciderstack import FleetClient
+    
+    # Using an API token (recommended)
+    client = FleetClient("192.168.1.100", api_token="csk_...")
+    
+    # Or using a trusted node ID (from pairing)
+    client = FleetClient("192.168.1.100", node_id="your-trusted-node-id")
+    
+    # List VMs
+    vms = client.list_vms()
+    for vm in vms:
+        print(f"{vm.name}: {vm.state}")
+"""
+
+from .client import FleetClient, FleetError
+from .types import (
+    VMState, TaskStatus, NodeRole,
+    Template, APIToken, APITokenSummary, APITokenPermissions,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "FleetClient", "FleetError",
+    "VMState", "TaskStatus", "NodeRole",
+    "Template", "APIToken", "APITokenSummary", "APITokenPermissions",
+]

ciderstack-0.1.0/ciderstack/client.py

@@ -0,0 +1,650 @@
+"""
+CiderStack Fleet Client
+
+HTTP client for the CiderStack Fleet JSON-RPC API.
+"""
+
+import uuid
+
+import requests
+from typing import List, Optional, Dict, Any
+from .types import (
+    NodeInfo, NodeStats, VM, Snapshot, Task, ExecResult,
+    VMState, TaskStatus, Template, APIToken, APITokenSummary
+)
+
+
+class FleetError(Exception):
+    """Exception raised when a Fleet API call fails."""
+    def __init__(self, message: str, response: Optional[Dict] = None):
+        super().__init__(message)
+        self.response = response
+
+
+class FleetClient:
+    """
+    Client for the CiderStack Fleet API.
+    
+    Authenticate with either an API token (recommended) or a trusted node ID.
+    
+    Examples:
+        # Using an API token (recommended)
+        client = FleetClient("192.168.1.100", api_token="csk_...")
+        
+        # Using a trusted node ID (from pairing)
+        client = FleetClient("192.168.1.100", node_id="your-trusted-node-id")
+    """
+    
+    DEFAULT_PORT = 9473
+    DEFAULT_TIMEOUT = 30
+    
+    def __init__(
+        self,
+        host: str,
+        node_id: Optional[str] = None,
+        api_token: Optional[str] = None,
+        port: int = DEFAULT_PORT,
+        timeout: int = DEFAULT_TIMEOUT,
+    ):
+        """
+        Initialize the Fleet client.
+        
+        Provide exactly one of node_id or api_token for authentication.
+        
+        Args:
+            host: IP address or hostname of the Fleet node
+            node_id: Trusted node ID (obtained via pairing)
+            api_token: API token string (generated via CiderStack CLI/UI)
+            port: Port number (default: 9473)
+            timeout: Request timeout in seconds (default: 30)
+        """
+        if not node_id and not api_token:
+            raise FleetError("Either node_id or api_token is required for authentication")
+        if node_id and api_token:
+            raise FleetError("Provide either node_id or api_token, not both")
+        self.host = host
+        self.port = port
+        self.timeout = timeout
+        self.node_id = node_id
+        self.api_token = api_token
+        self.base_url = f"http://{host}:{port}"
+    
+    def _rpc(
+        self,
+        method: str,
+        payload: Optional[Dict] = None,
+        request_timeout: Optional[int] = None,
+    ) -> Dict:
+        """Make an RPC call to the Fleet server."""
+        url = f"{self.base_url}/rpc/{method}"
+        timeout_sec = request_timeout if request_timeout is not None else self.timeout
+
+        # Inject authentication into every request
+        if self.api_token:
+            authenticated_payload: Dict[str, Any] = {"apiToken": self.api_token}
+        else:
+            authenticated_payload = {"callerNodeID": self.node_id}
+        if payload:
+            authenticated_payload.update(payload)
+
+        try:
+            response = requests.post(
+                url,
+                json=authenticated_payload,
+                timeout=timeout_sec,
+                headers={"Content-Type": "application/json"}
+            )
+            
+            if response.status_code == 403:
+                try:
+                    body = response.json()
+                    error_msg = body.get("error", "Authentication failed")
+                except Exception:
+                    error_msg = "Authentication failed"
+                raise FleetError(error_msg)
+            
+            response.raise_for_status()
+            return response.json()
+        except FleetError:
+            raise
+        except requests.exceptions.RequestException as e:
+            raise FleetError(f"Request failed: {e}")
+    
+    def _check_response(self, response: Dict, operation: str) -> Dict:
+        """Check if response indicates success."""
+        if not response.get("success", True):
+            error = response.get("error") or response.get("message") or "Unknown error"
+            raise FleetError(f"{operation} failed: {error}", response)
+        return response
+    
+    # =========================================================================
+    # Node Information
+    # =========================================================================
+    
+    def get_node_info(self) -> NodeInfo:
+        """Get information about the connected node."""
+        data = self._rpc("GetNodeInfo")
+        return NodeInfo.from_dict(data)
+    
+    def get_node_stats(self) -> NodeStats:
+        """Get real-time statistics for the node."""
+        data = self._rpc("GetNodeStats")
+        return NodeStats.from_dict(data)
+    
+    # =========================================================================
+    # VM Management
+    # =========================================================================
+    
+    def list_vms(self) -> List[VM]:
+        """List all VMs on the node."""
+        data = self._rpc("ListVMs")
+        vms = data.get("vms", [])
+        return [VM.from_dict(vm) for vm in vms]
+    
+    def get_vm(self, vm_id: str) -> Optional[VM]:
+        """Get a specific VM by ID."""
+        vms = self.list_vms()
+        for vm in vms:
+            if vm.id == vm_id:
+                return vm
+        return None
+    
+    def start_vm(self, vm_id: str) -> bool:
+        """Start a VM."""
+        response = self._rpc("StartVM", {"vmID": vm_id})
+        self._check_response(response, "Start VM")
+        return True
+    
+    def stop_vm(self, vm_id: str) -> bool:
+        """Stop a VM."""
+        response = self._rpc("StopVM", {"vmID": vm_id})
+        self._check_response(response, "Stop VM")
+        return True
+    
+    def suspend_vm(self, vm_id: str) -> bool:
+        """Suspend (pause) a running VM."""
+        response = self._rpc("SuspendVM", {"vmID": vm_id})
+        self._check_response(response, "Suspend VM")
+        return True
+
+    def start_vm_recovery(self, vm_id: str) -> bool:
+        """Start a VM in recovery mode."""
+        response = self._rpc("StartVMRecovery", {"vmID": vm_id})
+        self._check_response(response, "Start VM recovery")
+        return True
+    
+    def clone_vm(self, vm_id: str, new_name: str) -> VM:
+        """Clone a VM."""
+        response = self._rpc("CloneVM", {"vmID": vm_id, "newName": new_name})
+        self._check_response(response, "Clone VM")
+        return VM.from_dict(response.get("newVM", {}))
+    
+    def rename_vm(self, vm_id: str, new_name: str) -> bool:
+        """Rename a VM."""
+        response = self._rpc("RenameVM", {"vmID": vm_id, "newName": new_name})
+        self._check_response(response, "Rename VM")
+        return True
+    
+    def delete_vm(self, vm_id: str) -> bool:
+        """Delete a VM."""
+        response = self._rpc("DeleteVM", {"vmID": vm_id})
+        self._check_response(response, "Delete VM")
+        return True
+    
+    def get_vm_settings(self, vm_id: str) -> Dict:
+        """Get VM settings/configuration."""
+        response = self._rpc("GetVMSettings", {"vmID": vm_id})
+        self._check_response(response, "Get VM settings")
+        return response.get("configuration", {})
+    
+    def update_vm_settings(
+        self,
+        vm_id: str,
+        cpu_count: Optional[int] = None,
+        memory_size: Optional[int] = None,
+        display_width: Optional[int] = None,
+        display_height: Optional[int] = None,
+        intent: Optional[str] = None,
+        ttl_seconds: Optional[int] = None,
+    ) -> bool:
+        """Update VM settings.
+
+        Args:
+            vm_id: VM identifier.
+            cpu_count: Number of virtual CPUs.
+            memory_size: Memory in MB.
+            display_width: Display width in pixels.
+            display_height: Display height in pixels.
+            intent: VM intent ("disposable", "persistent", "interactive", "ci").
+            ttl_seconds: TTL in seconds from now. Pass -1 to clear the TTL.
+        """
+        payload: Dict[str, Any] = {"vmID": vm_id}
+        if cpu_count is not None:
+            payload["cpuCount"] = cpu_count
+        if memory_size is not None:
+            payload["memorySize"] = memory_size
+        if display_width is not None:
+            payload["displayWidth"] = display_width
+        if display_height is not None:
+            payload["displayHeight"] = display_height
+        if intent is not None:
+            payload["intent"] = intent
+        if ttl_seconds is not None:
+            payload["ttlSeconds"] = ttl_seconds
+
+        response = self._rpc("UpdateVMSettings", payload)
+        self._check_response(response, "Update VM settings")
+        return True
+    
+    # =========================================================================
+    # Snapshot Management
+    # =========================================================================
+    
+    def list_snapshots(self, vm_id: str) -> List[Snapshot]:
+        """List snapshots for a VM."""
+        data = self._rpc("ListSnapshots", {"vmID": vm_id})
+        snapshots = data.get("snapshots", [])
+        return [Snapshot.from_dict(s) for s in snapshots]
+    
+    def create_snapshot(
+        self,
+        vm_id: str,
+        name: str,
+        description: Optional[str] = None
+    ) -> Snapshot:
+        """Create a snapshot."""
+        payload = {"vmID": vm_id, "name": name}
+        if description:
+            payload["snapshotDescription"] = description
+        
+        response = self._rpc("CreateSnapshot", payload)
+        self._check_response(response, "Create snapshot")
+        return Snapshot.from_dict(response.get("snapshot", {}))
+    
+    def restore_snapshot(self, vm_id: str, snapshot_id: str) -> bool:
+        """Restore a VM to a snapshot."""
+        response = self._rpc("RestoreSnapshot", {"vmID": vm_id, "snapshotID": snapshot_id})
+        self._check_response(response, "Restore snapshot")
+        return True
+    
+    def delete_snapshot(self, vm_id: str, snapshot_id: str) -> bool:
+        """Delete a snapshot."""
+        response = self._rpc("DeleteSnapshot", {"vmID": vm_id, "snapshotID": snapshot_id})
+        self._check_response(response, "Delete snapshot")
+        return True
+    
+    # =========================================================================
+    # Command Execution
+    # =========================================================================
+    
+    DEFAULT_EXEC_TIMEOUT = 300  # seconds (5 min); increase for large downloads
+
+    def exec_command(
+        self,
+        vm_id: str,
+        command: str,
+        ssh_user: Optional[str] = None,
+        ssh_password: Optional[str] = None,
+        timeout: int = DEFAULT_EXEC_TIMEOUT,
+    ) -> ExecResult:
+        """Execute a command on a VM via SSH. Use a longer timeout for long-running steps (e.g. curl + unzip)."""
+        payload = {
+            "vmID": vm_id,
+            "command": command,
+            "timeout": timeout,
+        }
+        if ssh_user:
+            payload["sshUser"] = ssh_user
+        if ssh_password:
+            payload["sshPassword"] = ssh_password
+
+        # HTTP request must stay open at least as long as the command (+ buffer) to avoid broken pipe
+        request_timeout = max(self.timeout, timeout + 60)
+        response = self._rpc("ExecCommand", payload, request_timeout=request_timeout)
+        return ExecResult.from_dict(response)
+    
+    # =========================================================================
+    # Task Management
+    # =========================================================================
+    
+    def get_tasks(self, include_completed: bool = False) -> List[Task]:
+        """Get tasks running on the node."""
+        data = self._rpc("GetTasks", {"includeCompleted": include_completed})
+        tasks = data.get("tasks", [])
+        return [Task.from_dict(t) for t in tasks]
+    
+    # =========================================================================
+    # Image Management
+    # =========================================================================
+    
+    def push_image(self, vm_id: str, image_name: str, insecure: bool = False) -> str:
+        """Push a VM as an OCI image."""
+        response = self._rpc("PushImage", {
+            "vmID": vm_id,
+            "imageName": image_name,
+            "insecure": insecure,
+        })
+        self._check_response(response, "Push image")
+        return response.get("taskID", "")
+    
+    def list_ipsws(self) -> List[Dict]:
+        """List available IPSW files on the node."""
+        data = self._rpc("ListRemoteIPSWs")
+        return data.get("ipsws", [])
+    
+    def list_oci_images(self) -> List[Dict]:
+        """List OCI images on the node."""
+        data = self._rpc("ListRemoteOCIImages")
+        return data.get("images", [])
+    
+    def download_ipsw(self, url: str, name: str, version: str) -> bool:
+        """Download an IPSW on the remote node."""
+        response = self._rpc("DownloadIPSWOnNode", {
+            "requestID": str(uuid.uuid4()),
+            "downloadURL": url,
+            "expectedName": name,
+            "expectedVersion": version,
+        })
+        self._check_response(response, "Download IPSW")
+        return True
+    
+    def pull_oci_image(
+        self,
+        image_reference: str,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+    ) -> bool:
+        """Pull an OCI image on the remote node."""
+        payload = {
+            "requestID": str(uuid.uuid4()),
+            "imageReference": image_reference,
+        }
+        if username and password:
+            payload["credentials"] = {"username": username, "password": password}
+        
+        response = self._rpc("PullOCIImageOnNode", payload)
+        self._check_response(response, "Pull OCI image")
+        return True
+    
+    def create_vm(
+        self,
+        name: str,
+        cpu_count: int = 4,
+        memory_mb: int = 8192,
+        disk_gb: int = 64,
+        ipsw_path: Optional[str] = None,
+        oci_image: Optional[str] = None,
+    ) -> str:
+        """Create a VM on the remote node."""
+        payload = {
+            "requestID": str(uuid.uuid4()),
+            "name": name,
+            "cpuCount": cpu_count,
+            "memorySizeMB": memory_mb,
+            "diskSizeGB": disk_gb,
+        }
+        if ipsw_path:
+            payload["ipswPath"] = ipsw_path
+        if oci_image:
+            payload["ociImageReference"] = oci_image
+        
+        response = self._rpc("CreateVMOnNode", payload)
+        self._check_response(response, "Create VM")
+        return response.get("vmID", "")
+    
+    # =========================================================================
+    # Fleet Overview
+    # =========================================================================
+    
+    def get_fleet_overview(self) -> Dict:
+        """Get aggregated fleet status."""
+        return self._rpc("GetFleetOverview")
+    
+    def get_fleet_events(self, limit: int = 100, event_type: Optional[str] = None) -> List[Dict]:
+        """Get fleet activity events."""
+        payload = {"limit": limit}
+        if event_type:
+            payload["eventType"] = event_type
+        
+        data = self._rpc("GetFleetEvents", payload)
+        return data.get("events", [])
+    
+    def get_remote_resources(self) -> Dict:
+        """Get available resources for VM creation."""
+        return self._rpc("GetRemoteResources")
+    
+    # =========================================================================
+    # Pairing
+    # =========================================================================
+    
+    @staticmethod
+    def pair(
+        host: str,
+        code: str,
+        name: Optional[str] = None,
+        port: int = 9473,
+    ) -> Dict:
+        """
+        Pair this SDK client with a Fleet node using a 6-digit pairing code.
+        
+        The pairing code is displayed in the CiderStack app UI.
+        On success, returns credentials that can be used to create a FleetClient.
+        
+        Args:
+            host: IP address or hostname of the Fleet node
+            code: 6-digit pairing code from the CiderStack UI
+            name: Display name for this SDK client (auto-generated if omitted)
+            port: Port number (default: 9473)
+        
+        Returns:
+            Dict with keys: node_id, private_key_hex, public_key_hex,
+            responder_node_id, responder_name
+        
+        Example:
+            creds = FleetClient.pair("192.168.1.100", "123456", "my-ci-script")
+            # Store creds["node_id"] securely for future use
+            client = FleetClient("192.168.1.100", node_id=creds["node_id"])
+        """
+        from cryptography.hazmat.primitives.asymmetric import ec
+        from cryptography.hazmat.primitives import serialization
+        from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+        import base64
+        
+        # Generate a new node identity
+        node_id = str(uuid.uuid4()).upper()
+        client_name = name or f"sdk-{node_id[:8].lower()}"
+        
+        # Generate P-256 keypair
+        private_key = ec.generate_private_key(ec.SECP256R1())
+        public_key_bytes = private_key.public_key().public_bytes(
+            Encoding.X962, PublicFormat.UncompressedPoint
+        )
+        private_key_bytes = private_key.private_numbers().private_value.to_bytes(32, "big")
+        
+        public_key_hex = public_key_bytes.hex()
+        private_key_hex = private_key_bytes.hex()
+        public_key_b64 = base64.b64encode(public_key_bytes).decode()
+        
+        # Send pairing request — ensure code is always a string
+        url = f"http://{host}:{port}/rpc/RequestPairing"
+        payload = {
+            "requestID": str(uuid.uuid4()).upper(),
+            "requesterNodeID": {"value": node_id},
+            "requesterName": client_name,
+            "requesterIP": "0.0.0.0",
+            "publicKey": public_key_b64,
+            "code": str(code),
+        }
+        
+        try:
+            response = requests.post(
+                url,
+                json=payload,
+                timeout=30,
+                headers={"Content-Type": "application/json"},
+            )
+            response.raise_for_status()
+            result = response.json()
+        except requests.exceptions.RequestException as e:
+            raise FleetError(f"Pairing request failed: {e}")
+        
+        if not result.get("accepted"):
+            error_msg = result.get("errorMessage", "Pairing rejected")
+            raise FleetError(f"Pairing failed: {error_msg}")
+        
+        responder_node_id = result.get("responderNodeID", {})
+        
+        return {
+            "node_id": node_id,
+            "private_key_hex": private_key_hex,
+            "public_key_hex": public_key_hex,
+            "responder_node_id": responder_node_id.get("value", ""),
+            "responder_name": result.get("responderName", ""),
+        }
+
+    # =========================================================================
+    # Template Management
+    # =========================================================================
+
+    def list_templates(self) -> List[Template]:
+        """List all VM templates."""
+        data = self._rpc("ListTemplates")
+        templates = data.get("templates", [])
+        return [Template.from_dict(t) for t in templates]
+
+    def get_template(self, template_id: str) -> Optional[Template]:
+        """Get a template by ID."""
+        response = self._rpc("GetTemplate", {"templateID": template_id})
+        if not response.get("success") or not response.get("template"):
+            return None
+        return Template.from_dict(response["template"])
+
+    def get_template_by_name(self, name: str) -> Optional[Template]:
+        """Get a template by name."""
+        response = self._rpc("GetTemplate", {"templateName": name})
+        if not response.get("success") or not response.get("template"):
+            return None
+        return Template.from_dict(response["template"])
+
+    def create_template_from_vm(
+        self,
+        vm_id: str,
+        name: str,
+        description: Optional[str] = None,
+        category: Optional[str] = None,
+        keep_original_vm: bool = True,
+    ) -> Template:
+        """Create a template from an existing VM."""
+        payload: Dict[str, Any] = {"vmID": vm_id, "name": name}
+        if description is not None:
+            payload["description"] = description
+        if category is not None:
+            payload["category"] = category
+        payload["keepOriginalVM"] = keep_original_vm
+
+        response = self._rpc("CreateTemplateFromVM", payload)
+        self._check_response(response, "Create template from VM")
+        return Template.from_dict(response.get("template", {}))
+
+    def delete_template(self, template_id: str) -> bool:
+        """Delete a template."""
+        response = self._rpc("DeleteTemplate", {"templateID": template_id})
+        self._check_response(response, "Delete template")
+        return True
+
+    # =========================================================================
+    # API Token Management
+    # =========================================================================
+
+    def generate_api_token(
+        self,
+        name: str,
+        permissions: str = "fullAccess",
+    ) -> APIToken:
+        """Generate a new API token for SDK/script access."""
+        response = self._rpc("GenerateAPIToken", {
+            "name": name,
+            "permissions": permissions,
+        })
+        if not response.get("success"):
+            raise FleetError(response.get("error", "Failed to generate API token"), response)
+        return APIToken.from_dict(response.get("token", {}))
+
+    def revoke_api_token(self, token_id: str) -> bool:
+        """Revoke an API token by its ID."""
+        response = self._rpc("RevokeAPIToken", {"tokenID": token_id})
+        return response.get("revoked", False)
+
+    def list_api_tokens(self) -> List[APITokenSummary]:
+        """List all API tokens (token strings are redacted)."""
+        response = self._rpc("ListAPITokens")
+        tokens = response.get("tokens", [])
+        return [APITokenSummary.from_dict(t) for t in tokens]
+
+    # =========================================================================
+    # Shared Folder Management
+    # =========================================================================
+
+    def list_shared_folders(self, vm_id: str) -> List[Dict]:
+        """List shared folders for a VM."""
+        response = self._rpc("ListSharedFolders", {"vmID": vm_id})
+        self._check_response(response, "List shared folders")
+        return response.get("folders", [])
+
+    def add_shared_folder(
+        self,
+        vm_id: str,
+        name: str,
+        host_path: str,
+        read_only: bool = False,
+        mount_tag: Optional[str] = None,
+    ) -> bool:
+        """Add a shared folder to a VM."""
+        payload: Dict[str, Any] = {
+            "vmID": vm_id,
+            "name": name,
+            "hostPath": host_path,
+            "readOnly": read_only,
+        }
+        if mount_tag is not None:
+            payload["mountTag"] = mount_tag
+
+        response = self._rpc("AddSharedFolder", payload)
+        self._check_response(response, "Add shared folder")
+        return True
+
+    def remove_shared_folder(self, vm_id: str, name: str) -> bool:
+        """Remove a shared folder from a VM."""
+        response = self._rpc("RemoveSharedFolder", {"vmID": vm_id, "name": name})
+        self._check_response(response, "Remove shared folder")
+        return True
+
+    def set_shared_folder_enabled(self, vm_id: str, name: str, enabled: bool) -> bool:
+        """Enable or disable a shared folder."""
+        response = self._rpc("SetSharedFolderEnabled", {
+            "vmID": vm_id,
+            "name": name,
+            "enabled": enabled,
+        })
+        self._check_response(response, "Set shared folder enabled")
+        return True
+
+    # =========================================================================
+    # Fleet Utilities
+    # =========================================================================
+
+    def unpair(self, node_id: str) -> bool:
+        """Unpair a node from the fleet."""
+        response = self._rpc("Unpair", {"nodeID": node_id})
+        self._check_response(response, "Unpair")
+        return True
+
+    def cleanup_vms(self, force: bool = False) -> int:
+        """Clean up retired VMs whose TTL has passed."""
+        response = self._rpc("CleanupVMs", {"force": force})
+        self._check_response(response, "Cleanup VMs")
+        return response.get("cleanedCount", 0)
+
+    def get_ipsw_info(self, path: str) -> Dict:
+        """Get metadata about an IPSW file on the node."""
+        return self._rpc("GetIPSWInfo", {"path": path})

ciderstack-0.1.0/ciderstack/types.py

@@ -0,0 +1,286 @@
+"""
+CiderStack Fleet SDK Types
+"""
+
+from enum import Enum
+from dataclasses import dataclass
+from typing import Optional, List
+from datetime import datetime
+
+
+class VMState(str, Enum):
+    """VM state enumeration."""
+    STOPPED = "stopped"
+    STARTING = "starting"
+    RUNNING = "running"
+    PAUSED = "paused"
+    STOPPING = "stopping"
+    ERROR = "error"
+
+
+class TaskStatus(str, Enum):
+    """Task status enumeration."""
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class NodeRole(str, Enum):
+    """Node role enumeration."""
+    WORKER = "worker"
+    MANAGER = "manager"
+    OPERATOR = "operator"
+
+
+@dataclass
+class NodeInfo:
+    """Information about a Fleet node."""
+    node_id: str
+    name: str
+    hostname: str
+    ip_address: str
+    port: int
+    machine_model: str
+    os_version: str
+    cpu_cores: int
+    total_memory_gb: int
+    fleet_version: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "NodeInfo":
+        return cls(
+            node_id=data.get("nodeID", ""),
+            name=data.get("name", ""),
+            hostname=data.get("hostname", ""),
+            ip_address=data.get("ipAddress", ""),
+            port=data.get("port", 9473),
+            machine_model=data.get("machineModel", ""),
+            os_version=data.get("osVersion", ""),
+            cpu_cores=data.get("cpuCores", 0),
+            total_memory_gb=data.get("totalMemoryGB", 0),
+            fleet_version=data.get("fleetVersion", ""),
+        )
+
+
+@dataclass
+class NodeStats:
+    """Real-time statistics for a node."""
+    node_id: str
+    timestamp: datetime
+    cpu_usage_percent: float
+    memory_used_gb: float
+    memory_total_gb: float
+    disk_used_gb: float
+    disk_total_gb: float
+    running_vm_count: int
+    total_vm_count: int
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "NodeStats":
+        return cls(
+            node_id=data.get("nodeID", ""),
+            timestamp=datetime.fromisoformat(data.get("timestamp", "").replace("Z", "+00:00")) if data.get("timestamp") else datetime.now(),
+            cpu_usage_percent=data.get("cpuUsagePercent", 0.0),
+            memory_used_gb=data.get("memoryUsedGB", 0.0),
+            memory_total_gb=data.get("memoryTotalGB", 0.0),
+            disk_used_gb=data.get("diskUsedGB", 0.0),
+            disk_total_gb=data.get("diskTotalGB", 0.0),
+            running_vm_count=data.get("runningVMCount", 0),
+            total_vm_count=data.get("totalVMCount", 0),
+        )
+
+
+@dataclass
+class VM:
+    """A virtual machine."""
+    id: str
+    name: str
+    state: VMState
+    cpu_count: int
+    memory_mb: int
+    disk_size_gb: Optional[int]
+    os_version: Optional[str]
+    ip_address: Optional[str]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "VM":
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            state=VMState(data.get("state", "stopped")),
+            cpu_count=data.get("cpuCount", 0),
+            memory_mb=data.get("memoryMB", 0),
+            disk_size_gb=data.get("diskSizeGB"),
+            os_version=data.get("osVersion"),
+            ip_address=data.get("ipAddress"),
+        )
+
+
+@dataclass
+class Snapshot:
+    """A VM snapshot."""
+    id: str
+    name: str
+    description: Optional[str]
+    created_at: datetime
+    size_bytes: int
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Snapshot":
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            description=data.get("description"),
+            created_at=datetime.fromisoformat(data.get("createdAt", "").replace("Z", "+00:00")) if data.get("createdAt") else datetime.now(),
+            size_bytes=data.get("sizeBytes", 0),
+        )
+
+
+@dataclass
+class Task:
+    """A background task."""
+    id: str
+    type: str
+    title: str
+    status: TaskStatus
+    progress: float
+    progress_text: Optional[str]
+    started_at: datetime
+    completed_at: Optional[datetime]
+    vm_id: Optional[str]
+    vm_name: Optional[str]
+    error_message: Optional[str]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Task":
+        completed_at = None
+        if data.get("completedAt"):
+            completed_at = datetime.fromisoformat(data["completedAt"].replace("Z", "+00:00"))
+        
+        return cls(
+            id=data.get("id", ""),
+            type=data.get("type", ""),
+            title=data.get("title", ""),
+            status=TaskStatus(data.get("status", "pending")),
+            progress=data.get("progress", 0.0),
+            progress_text=data.get("progressText"),
+            started_at=datetime.fromisoformat(data.get("startedAt", "").replace("Z", "+00:00")) if data.get("startedAt") else datetime.now(),
+            completed_at=completed_at,
+            vm_id=data.get("vmID"),
+            vm_name=data.get("vmName"),
+            error_message=data.get("errorMessage"),
+        )
+
+
+@dataclass
+class Template:
+    """A VM template."""
+    id: str
+    name: str
+    description: Optional[str]
+    macos_version: Optional[str]
+    icon_name: str
+    category: str
+    source_type: str
+    created_at: datetime
+    modified_at: datetime
+    disk_size_bytes: Optional[int]
+    default_cpu: int
+    default_memory_mb: int
+    default_disk_gb: int
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Template":
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            description=data.get("description"),
+            macos_version=data.get("macOSVersion"),
+            icon_name=data.get("iconName", ""),
+            category=data.get("category", ""),
+            source_type=data.get("sourceType", ""),
+            created_at=datetime.fromisoformat(data.get("createdAt", "").replace("Z", "+00:00")) if data.get("createdAt") else datetime.now(),
+            modified_at=datetime.fromisoformat(data.get("modifiedAt", "").replace("Z", "+00:00")) if data.get("modifiedAt") else datetime.now(),
+            disk_size_bytes=data.get("diskSizeBytes"),
+            default_cpu=data.get("defaultCPU", 0),
+            default_memory_mb=data.get("defaultMemoryMB", 0),
+            default_disk_gb=data.get("defaultDiskGB", 0),
+        )
+
+
+class APITokenPermissions(str, Enum):
+    """API token permission level."""
+    READ_ONLY = "readOnly"
+    FULL_ACCESS = "fullAccess"
+
+
+@dataclass
+class APIToken:
+    """An API token for SDK/script access."""
+    id: str
+    name: str
+    token: str
+    permissions: APITokenPermissions
+    created_at: datetime
+    last_used_at: Optional[datetime]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "APIToken":
+        last_used = None
+        if data.get("lastUsedAt"):
+            last_used = datetime.fromisoformat(str(data["lastUsedAt"]).replace("Z", "+00:00"))
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            token=data.get("token", ""),
+            permissions=APITokenPermissions(data.get("permissions", "fullAccess")),
+            created_at=datetime.fromisoformat(str(data.get("createdAt", "")).replace("Z", "+00:00")) if data.get("createdAt") else datetime.now(),
+            last_used_at=last_used,
+        )
+
+
+@dataclass
+class APITokenSummary:
+    """Summary of an API token (token string redacted)."""
+    id: str
+    name: str
+    token_prefix: str
+    permissions: APITokenPermissions
+    created_at: datetime
+    last_used_at: Optional[datetime]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "APITokenSummary":
+        last_used = None
+        if data.get("lastUsedAt"):
+            last_used = datetime.fromisoformat(str(data["lastUsedAt"]).replace("Z", "+00:00"))
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            token_prefix=data.get("tokenPrefix", ""),
+            permissions=APITokenPermissions(data.get("permissions", "fullAccess")),
+            created_at=datetime.fromisoformat(str(data.get("createdAt", "")).replace("Z", "+00:00")) if data.get("createdAt") else datetime.now(),
+            last_used_at=last_used,
+        )
+
+
+@dataclass
+class ExecResult:
+    """Result of executing a command on a VM."""
+    success: bool
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration: float
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ExecResult":
+        return cls(
+            success=data.get("success", False),
+            exit_code=data.get("exitCode", -1),
+            stdout=data.get("stdout", ""),
+            stderr=data.get("stderr", ""),
+            duration=data.get("duration", 0.0),
+        )

ciderstack-0.1.0/ciderstack.egg-info/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: ciderstack
+Version: 0.1.0
+Summary: CiderStack Fleet SDK for Python
+Home-page: https://ciderstack.io
+Author: CiderStack
+Author-email: support@ciderstack.io
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28.0
+Provides-Extra: pairing
+Requires-Dist: cryptography>=41.0.0; extra == "pairing"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

ciderstack-0.1.0/ciderstack.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+setup.py
+ciderstack/__init__.py
+ciderstack/client.py
+ciderstack/types.py
+ciderstack.egg-info/PKG-INFO
+ciderstack.egg-info/SOURCES.txt
+ciderstack.egg-info/dependency_links.txt
+ciderstack.egg-info/requires.txt
+ciderstack.egg-info/top_level.txt

ciderstack-0.1.0/ciderstack.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ciderstack-0.1.0/ciderstack.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.28.0
+
+[pairing]
+cryptography>=41.0.0

ciderstack-0.1.0/ciderstack.egg-info/top_level.txt

@@ -0,0 +1 @@
+ciderstack

ciderstack-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ciderstack-0.1.0/setup.py

@@ -0,0 +1,31 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="ciderstack",
+    version="0.1.0",
+    description="CiderStack Fleet SDK for Python",
+    author="CiderStack",
+    author_email="support@ciderstack.io",
+    url="https://ciderstack.io",
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.28.0",
+    ],
+    extras_require={
+        "pairing": ["cryptography>=41.0.0"],
+    },
+    python_requires=">=3.8",
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+)