@almadar/cli 0.3.2 → 1.0.3

package/bin/almadar

@@ -49,12 +49,43 @@ function getBinaryPath() {
   process.exit(1);
 }
 
+function getShellsDir() {
+  // If user has set ORBITAL_SHELLS_DIR, respect it
+  if (process.env.ORBITAL_SHELLS_DIR) {
+    return process.env.ORBITAL_SHELLS_DIR;
+  }
+
+  // Look for shells bundled with this package
+  const possiblePaths = [
+    // Shells in same package
+    path.join(__dirname, '..', 'shells'),
+    // Global install - shells might be one level up
+    path.join(__dirname, '..', '..', '@almadar', 'cli', 'shells'),
+  ];
+
+  for (const shellsPath of possiblePaths) {
+    if (fs.existsSync(shellsPath) && fs.existsSync(path.join(shellsPath, 'typescript-shell'))) {
+      return shellsPath;
+    }
+  }
+
+  // No bundled shells found - binary will use its fallback or error
+  return null;
+}
+
 const binaryPath = getBinaryPath();
+const shellsDir = getShellsDir();
+
+// Build environment with ORBITAL_SHELLS_DIR if we found shells
+const env = { ...process.env };
+if (shellsDir) {
+  env.ORBITAL_SHELLS_DIR = shellsDir;
+}
 
 try {
   execFileSync(binaryPath, process.argv.slice(2), {
     stdio: 'inherit',
-    env: process.env,
+    env: env,
   });
 } catch (error) {
   if (error.status !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/cli",
-  "version": "0.3.2",
+  "version": "1.0.3",
   "description": "Almadar CLI - Compile Almadar schemas to full-stack applications",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,7 @@
   "files": [
     "bin",
     "scripts",
+    "shells",
     "README.md"
   ],
   "scripts": {
@@ -48,10 +49,10 @@
     "node": ">=16.0.0"
   },
   "optionalDependencies": {
-    "@almadar/cli-darwin-x64": "0.3.2",
-    "@almadar/cli-darwin-arm64": "0.3.2",
-    "@almadar/cli-linux-x64": "0.3.2",
-    "@almadar/cli-linux-arm64": "0.3.2",
-    "@almadar/cli-windows-x64": "0.3.2"
+    "@almadar/cli-darwin-x64": "1.0.3",
+    "@almadar/cli-darwin-arm64": "1.0.3",
+    "@almadar/cli-linux-x64": "1.0.3",
+    "@almadar/cli-linux-arm64": "1.0.3",
+    "@almadar/cli-windows-x64": "1.0.3"
   }
 }

package/shells/python-shell/.dockerignore

@@ -0,0 +1,50 @@
+# Git
+.git
+.gitignore
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+.env
+.env.*
+!.env.example
+.venv
+venv
+ENV
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# Testing
+.pytest_cache
+.coverage
+htmlcov
+.tox
+
+# Build artifacts
+*.egg-info
+dist
+build
+
+# Documentation
+docs/_build
+*.md
+!README.md
+
+# Scripts (not needed in container)
+scripts/
+
+# Local development
+.mypy_cache
+.ruff_cache
+
+# Misc
+*.log
+.DS_Store
+Thumbs.db

package/shells/python-shell/.env.example

@@ -0,0 +1,55 @@
+# ===========================================
+# Orbital Python Shell - Environment Variables
+# ===========================================
+# Copy this file to .env and fill in your values
+
+# ------------------------------------------
+# Server Configuration
+# ------------------------------------------
+PORT=8000
+ENVIRONMENT=development
+
+# ------------------------------------------
+# Firebase Configuration
+# ------------------------------------------
+# Get these from Firebase Console > Project Settings > Service Accounts
+# Generate a new private key and use the values from the JSON file
+
+FIREBASE_PROJECT_ID=your-project-id
+FIREBASE_CLIENT_EMAIL=your-client-email@your-project-id.iam.gserviceaccount.com
+FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nyour-private-key\n-----END PRIVATE KEY-----\n"
+
+# For local development with Firebase Emulator
+# FIRESTORE_EMULATOR_HOST=localhost:8080
+
+# Alternative: Path to service account JSON file
+# FIREBASE_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
+
+# ------------------------------------------
+# CORS Configuration
+# ------------------------------------------
+# Comma-separated list of allowed origins
+CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+
+# ------------------------------------------
+# External Service API Keys
+# ------------------------------------------
+# YouTube Data API v3 (for youtube integrator)
+# YOUTUBE_API_KEY=your-youtube-api-key
+
+# Stripe (for payment integrator)
+# STRIPE_SECRET_KEY=sk_test_...
+
+# Twilio (for messaging integrator)
+# TWILIO_ACCOUNT_SID=your-account-sid
+# TWILIO_AUTH_TOKEN=your-auth-token
+# TWILIO_PHONE_NUMBER=+1234567890
+
+# Email Service (SendGrid/Resend)
+# EMAIL_API_KEY=your-email-api-key
+# EMAIL_FROM_ADDRESS=noreply@example.com
+
+# AI API Keys (for AI integrators)
+# OPENAI_API_KEY=your-openai-api-key
+# ANTHROPIC_API_KEY=your-anthropic-api-key
+# GEMINI_API_KEY=your-gemini-api-key

package/shells/python-shell/Dockerfile

@@ -0,0 +1,56 @@
+# ===========================================
+# Orbital Python Shell - Dockerfile
+# ===========================================
+# Multi-stage build for Cloud Run deployment
+
+# Build stage
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create virtual environment
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Copy project files (src needed for setuptools to find packages)
+COPY pyproject.toml ./
+COPY src/ ./src/
+
+# Install dependencies (including torch CPU-only for smaller image)
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir . --extra-index-url https://download.pytorch.org/whl/cpu
+
+# Production stage
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy virtual environment from builder
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Copy application code
+COPY src/ ./src/
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV ENVIRONMENT=production
+
+# Port (default 8000, Cloud Run overrides via PORT env var)
+ENV PORT=8000
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Run the application (uses $PORT for Cloud Run compatibility)
+CMD ["sh", "-c", "uvicorn orbital_app.main:app --host 0.0.0.0 --port ${PORT}"]

package/shells/python-shell/README.md

@@ -0,0 +1,253 @@
+# Almadar Python Shell
+
+FastAPI server backend for Almadar applications with PyTorch support.
+
+## Overview
+
+The Python shell provides a server-side implementation of the Almadar execution model. It processes events from the React client, executes server-side effects (fetch, persist, call_service, PyTorch operations), and returns responses with data and client effects.
+
+## Architecture
+
+```
+React Client (TypeScript)     Python Server (FastAPI)
+       │                              │
+       │  POST /api/{orbital}/{event} │
+       │─────────────────────────────▶│
+       │  Authorization: Bearer <token>│
+       │                              │ 1. Verify Firebase token (@user)
+       │                              │ 2. Evaluate guard
+       │                              │ 3. Execute server effects
+       │                              │    - fetch (query DB)
+       │                              │    - persist (write DB)
+       │                              │    - PyTorch ops (NN inference)
+       │◀─────────────────────────────│
+       │  { data, clientEffects }     │
+       │                              │
+       │ 4. Execute clientEffects     │
+       │    - render_ui               │
+       │    - navigate                │
+       │    - notify                  │
+```
+
+## Quick Start
+
+### Local Development
+
+1. **Create virtual environment:**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+3. **Configure environment:**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+4. **Run the server:**
+   ```bash
+   python -m orbital_app.main
+   # Or with uvicorn directly:
+   uvicorn orbital_app.main:app --reload --port 8000
+   ```
+
+5. **Access the API:**
+   - Health check: http://localhost:8000/health
+   - API docs: http://localhost:8000/docs
+
+### Using Firebase Emulator
+
+For local development without Firebase credentials:
+
+```bash
+# Start Firebase emulator
+firebase emulators:start --only firestore
+
+# Set environment variable (or add to .env.development)
+export FIRESTORE_EMULATOR_HOST=localhost:8080
+
+# Run the server
+python -m orbital_app.main
+```
+
+## Deployment
+
+### Deploy to Cloud Run
+
+1. **Prerequisites:**
+   - Google Cloud SDK (`gcloud`) installed
+   - Docker installed
+   - Project configured: `gcloud config set project YOUR_PROJECT_ID`
+
+2. **Deploy:**
+   ```bash
+   ./scripts/deploy.sh orbital-app us-central1
+   ```
+
+3. **Set up secrets (for Firebase credentials):**
+   ```bash
+   ./scripts/setup-secrets.sh orbital-app us-central1
+   ```
+
+### Deployment Methods
+
+The deploy script supports three methods:
+
+```bash
+# Cloud Build (recommended for CI/CD)
+./scripts/deploy.sh orbital-app us-central1 cloud-build
+
+# Direct (faster for development)
+./scripts/deploy.sh orbital-app us-central1 direct
+
+# From source (simplest, but slowest)
+./scripts/deploy.sh orbital-app us-central1 source
+```
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `PORT` | Server port (default: 8000) | No |
+| `ENVIRONMENT` | `development` or `production` | No |
+| `FIREBASE_PROJECT_ID` | Firebase project ID | Yes* |
+| `FIREBASE_CLIENT_EMAIL` | Service account email | For production |
+| `FIREBASE_PRIVATE_KEY` | Service account private key | For production |
+| `FIRESTORE_EMULATOR_HOST` | Emulator host (e.g., `localhost:8080`) | For local dev |
+| `CORS_ORIGINS` | Comma-separated allowed origins | No |
+
+*Required for authentication. Falls back to `demo-project` for emulator mode.
+
+### Cloud Run with Secrets
+
+For production deployment with Firebase credentials:
+
+```bash
+gcloud run services update orbital-app \
+  --region us-central1 \
+  --set-secrets=FIREBASE_PROJECT_ID=orbital-app-FIREBASE_PROJECT_ID:latest \
+  --set-secrets=FIREBASE_CLIENT_EMAIL=orbital-app-FIREBASE_CLIENT_EMAIL:latest \
+  --set-secrets=FIREBASE_PRIVATE_KEY=orbital-app-FIREBASE_PRIVATE_KEY:latest
+```
+
+## Project Structure
+
+```
+src/orbital_app/
+├── __init__.py
+├── main.py              # FastAPI app entry point
+├── core/                # Framework code
+│   ├── settings.py      # Environment configuration
+│   ├── event_router.py  # Request/Response models
+│   ├── effect_executor.py # Server-side effect execution
+│   ├── repository.py    # Database abstraction (InMemory, Firestore)
+│   ├── bindings.py      # @entity, @payload, @user resolution
+│   └── firebase.py      # Firebase Admin SDK initialization
+├── middleware/          # FastAPI middleware
+│   └── auth.py          # Firebase authentication (@user context)
+├── nn/                  # PyTorch neural network runtime
+│   ├── builder.py       # S-expr → PyTorch module
+│   ├── forward.py       # nn/forward inference
+│   ├── training.py      # train/loop training
+│   └── constraints.py   # Weight/gradient constraints
+├── tensor/              # Tensor operations
+│   ├── ops.py           # tensor/* operations
+│   └── contracts.py     # Input/output contracts
+└── generated/           # ← COMPILER OUTPUT
+    ├── entities/        # Pydantic models
+    ├── traits/          # State machines
+    └── routes/          # Event handlers
+```
+
+## Authentication
+
+Include Firebase ID token in Authorization header:
+
+```
+Authorization: Bearer <firebase-id-token>
+```
+
+The `@user` context is then available in guards:
+
+```python
+# Guard: (or (= @user.role "admin") (= @entity.owner_id @user.uid))
+guard_expr = [
+    "or",
+    ["=", "@user.role", "admin"],
+    ["=", "@entity.owner_id", "@user.uid"],
+]
+```
+
+## API Contract
+
+### Event Endpoint
+
+```
+POST /api/{orbital}/{event}
+
+Request:
+{
+  "payload": { ... },
+  "entityId": "optional-id"
+}
+
+Response:
+{
+  "success": true,
+  "newState": "listing",
+  "data": {
+    "Task": [{ "id": "1", "title": "..." }]
+  },
+  "clientEffects": [
+    ["render_ui", "main", { "type": "entity-table" }],
+    ["notify", { "type": "success", "message": "Saved" }]
+  ],
+  "effectResults": [
+    { "effect": "persist", "action": "create", "data": { "id": "new" } }
+  ]
+}
+```
+
+## Compilation Workflow
+
+1. **TypeScript Compiler** generates React client (pages, components)
+2. **Python Shell** generates FastAPI server (event handlers, effects)
+3. Both use the same `.orb` schema
+
+```bash
+# Compile both targets
+almadar compile app.orb --target typescript  # React client
+almadar compile app.orb --target python      # FastAPI server
+```
+
+## Testing
+
+```bash
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=orbital_app
+
+# Run specific test file
+pytest tests/test_repository.py
+```
+
+## Development with React Client
+
+```bash
+# Terminal 1: Python server
+python -m orbital_app.main
+# → http://localhost:8000
+
+# Terminal 2: React client (from TypeScript shell)
+npm run dev
+# → http://localhost:3000
+# → Calls Python server at :8000
+```

package/shells/python-shell/cloudbuild.yaml

@@ -0,0 +1,76 @@
+# ===========================================
+# Cloud Build Configuration
+# ===========================================
+# Builds and deploys to Cloud Run
+#
+# Usage:
+#   gcloud builds submit --config cloudbuild.yaml \
+#     --substitutions=_SERVICE_NAME=orbital-app,_REGION=us-central1
+
+steps:
+  # Build the Docker image
+  - name: 'gcr.io/cloud-builders/docker'
+    args:
+      - 'build'
+      - '-t'
+      - 'gcr.io/$PROJECT_ID/${_SERVICE_NAME}:$COMMIT_SHA'
+      - '-t'
+      - 'gcr.io/$PROJECT_ID/${_SERVICE_NAME}:latest'
+      - '.'
+    id: 'build'
+
+  # Push the Docker image to Container Registry
+  - name: 'gcr.io/cloud-builders/docker'
+    args:
+      - 'push'
+      - 'gcr.io/$PROJECT_ID/${_SERVICE_NAME}:$COMMIT_SHA'
+    id: 'push-sha'
+    waitFor: ['build']
+
+  - name: 'gcr.io/cloud-builders/docker'
+    args:
+      - 'push'
+      - 'gcr.io/$PROJECT_ID/${_SERVICE_NAME}:latest'
+    id: 'push-latest'
+    waitFor: ['build']
+
+  # Deploy to Cloud Run
+  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
+    entrypoint: gcloud
+    args:
+      - 'run'
+      - 'deploy'
+      - '${_SERVICE_NAME}'
+      - '--image'
+      - 'gcr.io/$PROJECT_ID/${_SERVICE_NAME}:$COMMIT_SHA'
+      - '--region'
+      - '${_REGION}'
+      - '--platform'
+      - 'managed'
+      - '--allow-unauthenticated'
+      - '--memory'
+      - '1Gi'
+      - '--cpu'
+      - '1'
+      - '--min-instances'
+      - '0'
+      - '--max-instances'
+      - '10'
+      - '--set-env-vars'
+      - 'ENVIRONMENT=production'
+    id: 'deploy'
+    waitFor: ['push-sha']
+
+# Substitutions with defaults
+substitutions:
+  _SERVICE_NAME: orbital-app
+  _REGION: us-central1
+
+# Build options
+options:
+  logging: CLOUD_LOGGING_ONLY
+
+# Store images in Container Registry
+images:
+  - 'gcr.io/$PROJECT_ID/${_SERVICE_NAME}:$COMMIT_SHA'
+  - 'gcr.io/$PROJECT_ID/${_SERVICE_NAME}:latest'

package/shells/python-shell/docker-compose.yaml

@@ -0,0 +1,57 @@
+# ===========================================
+# Docker Compose - Development Environment
+# ===========================================
+# Runs Python server with Firebase Emulator for local development
+#
+# Usage:
+#   docker-compose up        # Start all services
+#   docker-compose up -d     # Start in background
+#   docker-compose logs -f   # Follow logs
+#   docker-compose down      # Stop all services
+
+version: '3.8'
+
+services:
+  # Python FastAPI Server
+  server:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8080"
+    environment:
+      - ENVIRONMENT=development
+      - PORT=8080
+      - FIRESTORE_EMULATOR_HOST=firebase:8080
+      - FIREBASE_PROJECT_ID=demo-project
+      - CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+    depends_on:
+      - firebase
+    volumes:
+      # Mount source for hot reload (development only)
+      - ./src:/app/src:ro
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+
+  # Firebase Emulator
+  firebase:
+    image: andreysenov/firebase-tools:latest
+    ports:
+      - "4000:4000"   # Emulator UI
+      - "8080:8080"   # Firestore
+      - "9099:9099"   # Auth
+    command: firebase emulators:start --only firestore,auth --project demo-project
+    volumes:
+      - firebase-data:/home/node/.cache/firebase/emulators
+
+volumes:
+  firebase-data:
+
+# ===========================================
+# Production Compose (for reference)
+# ===========================================
+# For production, use Cloud Run instead of Docker Compose.
+# See: ./scripts/deploy.sh

package/shells/python-shell/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "orbital-app"
+version = "0.1.0"
+description = "Almadar Python Shell - FastAPI server with PyTorch support"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.100.0",
+    "uvicorn>=0.22.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "torch>=2.0.0",
+    "firebase-admin>=6.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "httpx>=0.24.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]