@almadar/cli 0.3.1 → 0.3.3

package/shells/python-shell/scripts/deploy.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# ===========================================
+# Deploy to Cloud Run
+# ===========================================
+# Usage: ./scripts/deploy.sh [service-name] [region]
+#
+# Prerequisites:
+#   - gcloud CLI installed and authenticated
+#   - Docker installed (for local builds)
+#   - Project ID set: gcloud config set project YOUR_PROJECT_ID
+
+set -e
+
+# Configuration
+SERVICE_NAME="${1:-orbital-app}"
+REGION="${2:-us-central1}"
+PROJECT_ID=$(gcloud config get-value project)
+
+if [ -z "$PROJECT_ID" ]; then
+    echo "Error: No project ID set. Run: gcloud config set project YOUR_PROJECT_ID"
+    exit 1
+fi
+
+echo "=========================================="
+echo "Deploying $SERVICE_NAME to Cloud Run"
+echo "=========================================="
+echo "Project: $PROJECT_ID"
+echo "Region:  $REGION"
+echo "=========================================="
+
+# Option 1: Deploy using Cloud Build (recommended for CI/CD)
+deploy_with_cloud_build() {
+    echo "Deploying with Cloud Build..."
+    gcloud builds submit \
+        --config cloudbuild.yaml \
+        --substitutions="_SERVICE_NAME=$SERVICE_NAME,_REGION=$REGION"
+}
+
+# Option 2: Deploy directly (faster for development)
+deploy_direct() {
+    echo "Building and deploying directly..."
+
+    IMAGE="gcr.io/$PROJECT_ID/$SERVICE_NAME"
+
+    # Build
+    echo "Building Docker image..."
+    docker build -t "$IMAGE" .
+
+    # Push
+    echo "Pushing to Container Registry..."
+    docker push "$IMAGE"
+
+    # Deploy
+    echo "Deploying to Cloud Run..."
+    gcloud run deploy "$SERVICE_NAME" \
+        --image "$IMAGE" \
+        --region "$REGION" \
+        --platform managed \
+        --allow-unauthenticated \
+        --memory 1Gi \
+        --cpu 1 \
+        --min-instances 0 \
+        --max-instances 10 \
+        --set-env-vars "ENVIRONMENT=production"
+}
+
+# Option 3: Deploy from source (simplest, but slowest)
+deploy_from_source() {
+    echo "Deploying from source..."
+    gcloud run deploy "$SERVICE_NAME" \
+        --source . \
+        --region "$REGION" \
+        --platform managed \
+        --allow-unauthenticated \
+        --memory 1Gi \
+        --cpu 1
+}
+
+# Parse deployment method
+METHOD="${3:-cloud-build}"
+
+case "$METHOD" in
+    cloud-build)
+        deploy_with_cloud_build
+        ;;
+    direct)
+        deploy_direct
+        ;;
+    source)
+        deploy_from_source
+        ;;
+    *)
+        echo "Unknown method: $METHOD"
+        echo "Usage: $0 [service-name] [region] [cloud-build|direct|source]"
+        exit 1
+        ;;
+esac
+
+# Get the service URL
+echo ""
+echo "=========================================="
+echo "Deployment complete!"
+echo "=========================================="
+SERVICE_URL=$(gcloud run services describe "$SERVICE_NAME" --region="$REGION" --format='value(status.url)' 2>/dev/null || echo "")
+if [ -n "$SERVICE_URL" ]; then
+    echo "Service URL: $SERVICE_URL"
+    echo "Health check: $SERVICE_URL/health"
+fi

package/shells/python-shell/scripts/setup-secrets.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# ===========================================
+# Setup Cloud Run Secrets
+# ===========================================
+# Creates secrets in Secret Manager and configures Cloud Run to use them
+#
+# Usage: ./scripts/setup-secrets.sh [service-name] [region]
+#
+# Prerequisites:
+#   - gcloud CLI installed and authenticated
+#   - Secret Manager API enabled
+#   - .env file with your secrets
+
+set -e
+
+SERVICE_NAME="${1:-orbital-app}"
+REGION="${2:-us-central1}"
+PROJECT_ID=$(gcloud config get-value project)
+
+if [ -z "$PROJECT_ID" ]; then
+    echo "Error: No project ID set. Run: gcloud config set project YOUR_PROJECT_ID"
+    exit 1
+fi
+
+echo "=========================================="
+echo "Setting up secrets for $SERVICE_NAME"
+echo "=========================================="
+
+# Enable Secret Manager API
+echo "Enabling Secret Manager API..."
+gcloud services enable secretmanager.googleapis.com
+
+# Function to create or update a secret
+create_secret() {
+    local SECRET_NAME=$1
+    local SECRET_VALUE=$2
+
+    if [ -z "$SECRET_VALUE" ]; then
+        echo "Skipping $SECRET_NAME (empty value)"
+        return
+    fi
+
+    echo "Creating/updating secret: $SECRET_NAME"
+
+    # Check if secret exists
+    if gcloud secrets describe "$SECRET_NAME" &>/dev/null; then
+        # Add new version
+        echo -n "$SECRET_VALUE" | gcloud secrets versions add "$SECRET_NAME" --data-file=-
+    else
+        # Create new secret
+        echo -n "$SECRET_VALUE" | gcloud secrets create "$SECRET_NAME" --data-file=-
+    fi
+}
+
+# Load environment variables from .env file
+if [ -f ".env" ]; then
+    echo "Loading secrets from .env file..."
+
+    # Read .env file and create secrets
+    while IFS='=' read -r key value; do
+        # Skip comments and empty lines
+        [[ $key =~ ^#.*$ ]] && continue
+        [[ -z "$key" ]] && continue
+
+        # Remove quotes from value
+        value=$(echo "$value" | sed 's/^["'"'"']//;s/["'"'"']$//')
+
+        # Create secret with service name prefix
+        SECRET_NAME="${SERVICE_NAME}-${key}"
+        create_secret "$SECRET_NAME" "$value"
+    done < .env
+
+    echo ""
+    echo "Secrets created. To use them in Cloud Run, update your service:"
+    echo ""
+    echo "gcloud run services update $SERVICE_NAME \\"
+    echo "  --region $REGION \\"
+    echo "  --set-secrets=FIREBASE_PROJECT_ID=${SERVICE_NAME}-FIREBASE_PROJECT_ID:latest \\"
+    echo "  --set-secrets=FIREBASE_CLIENT_EMAIL=${SERVICE_NAME}-FIREBASE_CLIENT_EMAIL:latest \\"
+    echo "  --set-secrets=FIREBASE_PRIVATE_KEY=${SERVICE_NAME}-FIREBASE_PRIVATE_KEY:latest"
+else
+    echo "No .env file found. Creating secrets interactively..."
+
+    # Interactive secret creation
+    read -p "Firebase Project ID: " FB_PROJECT_ID
+    create_secret "${SERVICE_NAME}-FIREBASE_PROJECT_ID" "$FB_PROJECT_ID"
+
+    read -p "Firebase Client Email: " FB_CLIENT_EMAIL
+    create_secret "${SERVICE_NAME}-FIREBASE_CLIENT_EMAIL" "$FB_CLIENT_EMAIL"
+
+    echo "Enter Firebase Private Key (paste and press Ctrl+D):"
+    FB_PRIVATE_KEY=$(cat)
+    create_secret "${SERVICE_NAME}-FIREBASE_PRIVATE_KEY" "$FB_PRIVATE_KEY"
+fi
+
+echo ""
+echo "=========================================="
+echo "Secrets setup complete!"
+echo "=========================================="
+echo ""
+echo "Grant Cloud Run access to secrets:"
+echo ""
+echo "SERVICE_ACCOUNT=\$(gcloud run services describe $SERVICE_NAME --region $REGION --format='value(spec.template.spec.serviceAccountName)')"
+echo "gcloud secrets add-iam-policy-binding ${SERVICE_NAME}-FIREBASE_PROJECT_ID --member=\"serviceAccount:\$SERVICE_ACCOUNT\" --role=\"roles/secretmanager.secretAccessor\""

package/shells/python-shell/src/orbital_app/__init__.py

@@ -0,0 +1,8 @@
+"""
+Orbital Python Shell
+
+FastAPI server backend for Orbital applications with PyTorch support.
+Generated code goes in orbital_app/generated/
+"""
+
+__version__ = "0.1.0"

package/shells/python-shell/src/orbital_app/core/__init__.py

@@ -0,0 +1,40 @@
+"""
+Core utilities for Orbital Python Shell.
+
+- settings: Application configuration
+- event_router: Event dispatch and response models
+- effect_executor: Server-side effect execution
+- repository: Database abstraction layer
+- bindings: @entity, @payload binding resolution
+- firebase: Firebase Admin SDK initialization
+- websocket: Real-time WebSocket connection management
+"""
+from .settings import Settings, get_settings
+from .event_router import EventRequest, EventResponse
+from .effect_executor import EffectExecutor
+from .repository import Repository, InMemoryRepository, FirestoreRepository
+from .bindings import resolve_binding, resolve_bindings_in_dict
+from .firebase import initialize_firebase, get_auth, get_firestore, verify_id_token
+from .event_bus import EventBus, get_event_bus
+from .websocket import ConnectionManager, connection_manager
+
+__all__ = [
+    "Settings",
+    "get_settings",
+    "EventRequest",
+    "EventResponse",
+    "EffectExecutor",
+    "Repository",
+    "InMemoryRepository",
+    "FirestoreRepository",
+    "resolve_binding",
+    "resolve_bindings_in_dict",
+    "initialize_firebase",
+    "get_auth",
+    "get_firestore",
+    "verify_id_token",
+    "EventBus",
+    "get_event_bus",
+    "ConnectionManager",
+    "connection_manager",
+]

package/shells/python-shell/src/orbital_app/core/bindings.py

@@ -0,0 +1,75 @@
+"""
+Bindings - Resolve @entity, @payload, @user bindings.
+
+Bindings are references to values in the execution context:
+- @payload.field - Value from the event payload
+- @entity.field - Value from the current entity
+- @user.field - Value from the authenticated user
+"""
+from typing import Any, Dict
+
+
+def resolve_binding(value: Any, context: Dict[str, Any]) -> Any:
+    """
+    Resolve a binding reference to its actual value.
+
+    Args:
+        value: The value to resolve (may be a binding string or literal)
+        context: The execution context containing payload, entity, user, etc.
+
+    Returns:
+        The resolved value
+    """
+    if not isinstance(value, str):
+        return value
+
+    if not value.startswith("@"):
+        return value
+
+    # Parse binding: @root.path.to.field
+    parts = value[1:].split(".")
+    root = parts[0]
+
+    if root not in context:
+        return None
+
+    result = context[root]
+
+    for part in parts[1:]:
+        if result is None:
+            return None
+        if isinstance(result, dict):
+            result = result.get(part)
+        else:
+            result = getattr(result, part, None)
+
+    return result
+
+
+def resolve_bindings_in_dict(data: Dict[str, Any], context: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Recursively resolve all bindings in a dictionary.
+
+    Args:
+        data: Dictionary that may contain binding references
+        context: The execution context
+
+    Returns:
+        Dictionary with all bindings resolved
+    """
+    result = {}
+    for key, value in data.items():
+        if isinstance(value, str):
+            result[key] = resolve_binding(value, context)
+        elif isinstance(value, dict):
+            result[key] = resolve_bindings_in_dict(value, context)
+        elif isinstance(value, list):
+            result[key] = [
+                resolve_bindings_in_dict(item, context) if isinstance(item, dict)
+                else resolve_binding(item, context) if isinstance(item, str)
+                else item
+                for item in value
+            ]
+        else:
+            result[key] = value
+    return result

package/shells/python-shell/src/orbital_app/core/effect_executor.py

@@ -0,0 +1,196 @@
+"""
+Effect Executor - Executes server-side effects.
+
+Server-side effects (per Orbital_Execution_Model.md):
+- fetch: Query database
+- persist: Write to database
+- call_service: Call external services
+- PyTorch ops: Neural network inference/training
+
+Client-side effects are collected and returned in response.clientEffects.
+"""
+from typing import Dict, Any, List, Optional
+from .repository import Repository
+from .bindings import resolve_binding
+
+
+class EffectExecutor:
+    """Executes server-side effects and collects client-side effects."""
+
+    def __init__(self, repository: Repository):
+        self.repository = repository
+        self.data: Dict[str, Any] = {}
+        self.client_effects: List[Any] = []
+        self.effect_results: List[Dict[str, Any]] = []
+
+    async def execute(self, effect: List[Any], context: Dict[str, Any]) -> Optional[Any]:
+        """Execute a single effect."""
+        if not effect:
+            return None
+
+        effect_type = effect[0]
+
+        # Server-side effects
+        if effect_type == "fetch":
+            return await self._execute_fetch(effect, context)
+        elif effect_type == "persist":
+            return await self._execute_persist(effect, context)
+        elif effect_type == "call_service":
+            return await self._execute_call_service(effect, context)
+        elif effect_type == "set":
+            return await self._execute_set(effect, context)
+
+        # Client-side effects - add to response
+        elif effect_type in ("render_ui", "render-ui"):
+            self.client_effects.append(effect)
+        elif effect_type == "navigate":
+            self.client_effects.append(effect)
+        elif effect_type == "notify":
+            self.client_effects.append(effect)
+        elif effect_type == "emit":
+            # emit can be both client and server side
+            self.client_effects.append(effect)
+
+        # PyTorch effects
+        elif effect_type.startswith("nn/") or effect_type.startswith("train/"):
+            return await self._execute_pytorch(effect, context)
+        elif effect_type.startswith("tensor/"):
+            return await self._execute_tensor(effect, context)
+
+        return None
+
+    async def _execute_fetch(
+        self, effect: List[Any], context: Dict[str, Any]
+    ) -> Optional[Any]:
+        """Execute fetch effect - query database."""
+        entity_type = effect[1]
+        options = effect[2] if len(effect) > 2 else {}
+
+        if "id" in options:
+            # Single entity fetch
+            entity_id = resolve_binding(options["id"], context)
+            result = await self.repository.get(entity_type, entity_id)
+            self.data[entity_type] = result
+        else:
+            # Collection fetch with optional filter
+            filter_expr = options.get("filter")
+            results = await self.repository.list(entity_type, filter_expr, context)
+            self.data[entity_type] = results
+
+        return self.data.get(entity_type)
+
+    async def _execute_persist(
+        self, effect: List[Any], context: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Execute persist effect - write to database."""
+        action = effect[1]  # 'create', 'update', 'delete'
+        entity_type = effect[2]
+        data = resolve_binding(effect[3], context) if len(effect) > 3 else {}
+
+        result = None
+        if action == "create":
+            result = await self.repository.create(entity_type, data)
+        elif action == "update":
+            entity_id = context.get("entityId") or (data.get("id") if isinstance(data, dict) else None)
+            if entity_id:
+                result = await self.repository.update(entity_type, entity_id, data)
+        elif action == "delete":
+            entity_id = context.get("entityId")
+            if entity_id:
+                await self.repository.delete(entity_type, entity_id)
+                result = {"deleted": True, "id": entity_id}
+
+        self.effect_results.append(
+            {
+                "effect": "persist",
+                "action": action,
+                "entityType": entity_type,
+                "data": result,
+                "success": result is not None,
+            }
+        )
+        return result
+
+    async def _execute_call_service(
+        self, effect: List[Any], context: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Execute call_service effect - call external service."""
+        service = effect[1]
+        method = effect[2]
+        args = resolve_binding(effect[3], context) if len(effect) > 3 else {}
+
+        # TODO: Implement service registry and calling
+        result = {"service": service, "method": method, "status": "not_implemented"}
+
+        self.effect_results.append(
+            {
+                "effect": "call_service",
+                "service": service,
+                "method": method,
+                "data": result,
+                "success": False,
+            }
+        )
+        return result
+
+    async def _execute_set(
+        self, effect: List[Any], context: Dict[str, Any]
+    ) -> Optional[Any]:
+        """Execute set effect - update entity field."""
+        target = effect[1]  # e.g., "@entity.field"
+        value = resolve_binding(effect[2], context) if len(effect) > 2 else None
+
+        # Parse target binding
+        if isinstance(target, str) and target.startswith("@"):
+            parts = target[1:].split(".")
+            root = parts[0]
+            if root in context and len(parts) > 1:
+                obj = context[root]
+                for part in parts[1:-1]:
+                    if isinstance(obj, dict):
+                        obj = obj.get(part, {})
+                    else:
+                        obj = getattr(obj, part, {})
+                # Set the final field
+                final_field = parts[-1]
+                if isinstance(obj, dict):
+                    obj[final_field] = value
+                else:
+                    setattr(obj, final_field, value)
+
+        self.effect_results.append(
+            {"effect": "set", "target": target, "value": value, "success": True}
+        )
+        return value
+
+    async def _execute_pytorch(
+        self, effect: List[Any], context: Dict[str, Any]
+    ) -> Optional[Any]:
+        """Execute PyTorch neural network operations."""
+        op = effect[0]
+
+        try:
+            from ..nn.forward import forward as nn_forward
+            from ..nn.training import train_loop
+
+            if op == "nn/forward":
+                module = resolve_binding(effect[1], context)
+                input_tensor = resolve_binding(effect[2], context)
+                return nn_forward(module, input_tensor)
+            elif op == "train/loop":
+                module = resolve_binding(effect[1], context)
+                data = resolve_binding(effect[2], context)
+                config = resolve_binding(effect[3], context)
+                return train_loop(module, data, config)
+        except ImportError:
+            # PyTorch not available
+            pass
+
+        return None
+
+    async def _execute_tensor(
+        self, effect: List[Any], context: Dict[str, Any]
+    ) -> Optional[Any]:
+        """Execute tensor operations."""
+        # Tensor ops are typically used in expressions, not as standalone effects
+        return None

package/shells/python-shell/src/orbital_app/core/event_bus.py

@@ -0,0 +1,119 @@
+"""
+Event Bus
+
+Provides event publishing and subscription for Orbital traits.
+"""
+
+from typing import Dict, Any, Callable, List, Optional
+from dataclasses import dataclass, field
+import asyncio
+
+
+@dataclass
+class EventSubscription:
+    """Represents an event subscription."""
+    event: str
+    handler: Callable
+    once: bool = False
+
+
+class EventBus:
+    """
+    Event bus for trait communication.
+
+    Allows traits to emit and subscribe to events.
+    """
+
+    def __init__(self):
+        self._subscriptions: Dict[str, List[EventSubscription]] = {}
+        self._pending_events: List[tuple] = []
+
+    def subscribe(
+        self,
+        event: str,
+        handler: Callable,
+        once: bool = False,
+    ) -> Callable:
+        """
+        Subscribe to an event.
+
+        Args:
+            event: The event name to subscribe to
+            handler: The callback function
+            once: If True, unsubscribe after first call
+
+        Returns:
+            A function to unsubscribe
+        """
+        if event not in self._subscriptions:
+            self._subscriptions[event] = []
+
+        sub = EventSubscription(event=event, handler=handler, once=once)
+        self._subscriptions[event].append(sub)
+
+        def unsubscribe():
+            if event in self._subscriptions:
+                self._subscriptions[event] = [
+                    s for s in self._subscriptions[event] if s != sub
+                ]
+
+        return unsubscribe
+
+    async def emit(self, event: str, payload: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Emit an event to all subscribers.
+
+        Args:
+            event: The event name
+            payload: Optional event payload
+        """
+        if event not in self._subscriptions:
+            return
+
+        to_remove = []
+        for sub in self._subscriptions[event]:
+            try:
+                if asyncio.iscoroutinefunction(sub.handler):
+                    await sub.handler(payload or {})
+                else:
+                    sub.handler(payload or {})
+
+                if sub.once:
+                    to_remove.append(sub)
+            except Exception as e:
+                # Log error but continue processing
+                print(f"Error in event handler for {event}: {e}")
+
+        # Remove one-time subscriptions
+        for sub in to_remove:
+            self._subscriptions[event].remove(sub)
+
+    def clear(self, event: Optional[str] = None) -> None:
+        """
+        Clear subscriptions.
+
+        Args:
+            event: If provided, only clear subscriptions for this event.
+                   If None, clear all subscriptions.
+        """
+        if event:
+            self._subscriptions.pop(event, None)
+        else:
+            self._subscriptions.clear()
+
+
+# Default global event bus instance
+_default_event_bus: Optional[EventBus] = None
+
+
+def get_event_bus() -> EventBus:
+    """Get the default event bus instance."""
+    global _default_event_bus
+    if _default_event_bus is None:
+        _default_event_bus = EventBus()
+    return _default_event_bus
+
+
+def EventBusDependency() -> EventBus:
+    """FastAPI dependency for EventBus."""
+    return get_event_bus()

package/shells/python-shell/src/orbital_app/core/event_router.py

@@ -0,0 +1,38 @@
+"""
+Event Router - Request/Response models for event handling.
+
+This follows the Orbital Execution Model:
+1. Receive event from client
+2. Evaluate guards
+3. Execute server-side effects
+4. Return { data, clientEffects }
+"""
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel
+
+
+class EventRequest(BaseModel):
+    """Request body for event endpoints."""
+
+    payload: Dict[str, Any] = {}
+    entityId: Optional[str] = None
+
+
+class EventResponse(BaseModel):
+    """
+    Standard response format per Orbital_Execution_Model.md.
+
+    - success: Whether the event was handled successfully
+    - newState: Updated trait state after transition
+    - data: Fetched entities from server-side effects
+    - clientEffects: Effects for React client to execute (render_ui, navigate, notify)
+    - effectResults: Results from mutation effects (persist, call_service)
+    - error: Error message if success is False
+    """
+
+    success: bool
+    newState: str
+    data: Dict[str, Any] = {}
+    clientEffects: List[Any] = []
+    effectResults: List[Dict[str, Any]] = []
+    error: Optional[str] = None