@specverse/engine-realize 3.5.3

package/assets/templates/default/scripts/test-generated-code.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+
+# Test Generated Code Runtime Execution
+# Tests that generated code actually compiles and runs
+
+set -e  # Exit on any error
+
+echo "🧪 Testing Generated Code Execution..."
+echo ""
+
+# Check if code has been generated
+if [ ! -d "generated/code/services" ]; then
+  echo "⚠️  No generated code found. Running generators first..."
+  npm run generate:code
+fi
+
+echo "📦 Step 1: Setting up runtime environment..."
+
+# Create runtime package.json if it doesn't exist
+if [ ! -f "generated/code/package.json" ]; then
+  echo "   → Creating package.json for generated code..."
+  cat > generated/code/package.json << 'EOF'
+{
+  "name": "generated-code-runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "dependencies": {
+    "@prisma/client": "^5.0.0",
+    "typeorm": "^0.3.17",
+    "reflect-metadata": "^0.1.13",
+    "better-sqlite3": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.2.0",
+    "tsx": "^3.12.0"
+  }
+}
+EOF
+fi
+
+# Create tsconfig.json if it doesn't exist
+if [ ! -f "generated/code/tsconfig.json" ]; then
+  echo "   → Creating tsconfig.json for generated code..."
+  cat > generated/code/tsconfig.json << 'EOF'
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+EOF
+fi
+
+echo "   ✅ Runtime environment configured"
+echo ""
+
+echo "🔧 Step 2: Checking TypeScript compilation..."
+
+cd generated/code
+
+# Check if dependencies are installed
+if [ ! -d "node_modules" ]; then
+  echo "   → Installing dependencies (this may take a minute)..."
+  npm install --silent 2>&1 | grep -v "^npm WARN" || true
+fi
+
+# Try to compile TypeScript
+echo "   → Compiling TypeScript..."
+if npx tsc --noEmit 2>&1 | tee compile.log; then
+  echo "   ✅ TypeScript compilation successful"
+  COMPILE_STATUS="✅ PASSED"
+else
+  echo "   ⚠️  TypeScript compilation has errors (expected - missing runtime setup)"
+  echo "   📝 See generated/code/compile.log for details"
+  COMPILE_STATUS="⚠️  NEEDS SETUP"
+fi
+
+cd ../..
+
+echo ""
+echo "🔍 Step 3: Analyzing generated code quality..."
+
+# Check for v3.3 features in generated code
+echo "   → Checking for v3.3 features..."
+
+FEATURES_FOUND=0
+
+if grep -q "validate(data: any, context:" generated/code/services/*.ts 2>/dev/null; then
+  echo "   ✅ Unified validation method found"
+  ((FEATURES_FOUND++))
+fi
+
+if grep -q "version mismatch" generated/code/services/*.ts 2>/dev/null; then
+  echo "   ✅ Optimistic locking found"
+  ((FEATURES_FOUND++))
+fi
+
+if grep -q "deletedAt: null\|isDeleted: false" generated/code/services/*.ts 2>/dev/null; then
+  echo "   ✅ Soft delete filtering found"
+  ((FEATURES_FOUND++))
+fi
+
+if grep -q "createdAt\|updatedAt" generated/code/services/*.ts 2>/dev/null; then
+  echo "   ✅ Audit fields found"
+  ((FEATURES_FOUND++))
+fi
+
+if grep -q "EventBus\|eventBus" generated/code/services/*.ts 2>/dev/null; then
+  echo "   ✅ Event publishing found"
+  ((FEATURES_FOUND++))
+fi
+
+echo ""
+echo "📊 Step 4: Code Quality Report"
+echo "   ════════════════════════════════════════"
+
+# Count generated files
+SERVICE_COUNT=$(find generated/code/services -name "*.ts" 2>/dev/null | wc -l | tr -d ' ')
+ROUTE_COUNT=$(find generated/code/routes -name "*.js" -o -name "*.ts" 2>/dev/null | wc -l | tr -d ' ')
+
+echo "   Files Generated:"
+echo "      Services: $SERVICE_COUNT"
+echo "      Routes: $ROUTE_COUNT"
+echo ""
+echo "   v3.3 Features: $FEATURES_FOUND/5 detected"
+echo "   Compilation: $COMPILE_STATUS"
+echo ""
+
+# Show service structure
+if [ -d "generated/code/services" ] && [ -n "$(ls -A generated/code/services/*.ts 2>/dev/null)" ]; then
+  echo "   Service Structure:"
+  for file in generated/code/services/*.ts; do
+    if [ -f "$file" ]; then
+      SERVICE_NAME=$(basename "$file" .service.ts)
+      METHOD_COUNT=$(grep -c "async\s\+\w\+(.*)" "$file" || echo "0")
+      echo "      $(basename "$file"): $METHOD_COUNT methods"
+    fi
+  done
+  echo ""
+fi
+
+echo "✅ Generated Code Analysis Complete!"
+echo ""
+echo "📝 Next Steps to Run Generated Code:"
+echo "   1. cd generated/code"
+echo "   2. npm install"
+echo "   3. Set up database (Prisma: npx prisma generate && npx prisma migrate dev)"
+echo "   4. Create server entry point (services/index.ts)"
+echo "   5. npm run start:dev"
+echo ""
+echo "💡 Tip: See generated/code/compile.log for compilation details"

package/assets/templates/default/specs/main.specly

@@ -0,0 +1,67 @@
+# SpecVerse Hello World
+# The simplest possible SpecVerse application with a view
+#
+# To use:
+# 1. Run: npm run realize:all
+# 2. Run: cd generated/code && npm install
+# 3. Check generated/code/README.md for setup instructions
+# 4. Run: npm run dev
+# 5. Test: curl http://localhost:3000/api/greetings
+
+components:
+  {{componentName}}:
+    version: "1.0.0"
+    description: "Hello World - The simplest SpecVerse application"
+    tags: ["hello-world", "starter", "minimal"]
+
+    models:
+      Greeting:
+        description: "A simple greeting message"
+
+        metadata:
+          id: uuid
+          audit: true
+
+        attributes:
+          message: String required default="Hello World"
+          language: String default="en" values=["en", "es", "fr", "de"]
+
+    controllers:
+      GreetingController:
+        model: Greeting
+        description: "Serves greeting messages"
+
+        cured:
+          create: {}
+          retrieve: {}
+
+    views:
+      GreetingView:
+        description: "Displays greeting messages"
+        model: Greeting
+        uiComponents:
+          GreetingDisplay: {}
+          LanguageSelector: {}
+
+deployments:
+  development:
+    version: "1.0.0"
+    description: "Hello World development environment"
+    environment: "development"
+
+    instances:
+      controllers:
+        apiServer:
+          component: {{componentName}}
+          namespace: api
+          scale: 1
+          advertises: [api.*]
+          uses: [database.*]
+
+      storage:
+        mainDB:
+          component: {{componentName}}
+          namespace: data
+          type: relational
+          scale: 1
+          advertises: [persistence.*]

package/assets/templates/frontend-only/CLAUDE.md

@@ -0,0 +1,75 @@
+# {{projectName}} - Frontend Development Guide
+
+Frontend-only SpecVerse project for React SPA development.
+
+## Project Type
+
+**Frontend Only** - No backend generation
+- React + TypeScript + Vite
+- React Query for data fetching
+- Connects to external API
+- Standalone deployment structure
+
+## Quick Commands
+
+```bash
+# Generate frontend code
+npm run realize:all
+
+# Setup and run
+cd generated/code
+npm install
+npm run dev
+
+# Open browser
+open http://localhost:5173
+```
+
+## File Structure
+
+```
+{{projectName}}/
+├── specs/main.specly              # UI specification
+├── manifests/implementation.yaml  # Frontend-only manifest
+└── generated/code/                # Standalone React app
+    ├── src/                       # React components
+    ├── index.html                 # HTML entry point
+    ├── vite.config.ts             # Vite configuration
+    └── package.json               # Frontend dependencies
+```
+
+## Development Workflow
+
+1. **Edit UI Spec**: Modify `specs/main.specly` (views and models)
+2. **Regenerate**: Run `npm run realize:all`
+3. **Configure API**: Set `VITE_API_BASE_URL` in `.env`
+4. **Test**: Use dev server or connect to real API
+
+## Key Features
+
+- **Standalone Structure**: All code in root (no backend/ subdirectory)
+- **External API**: Connects via environment variables
+- **React Router**: Auto-generated routes from views
+- **React Query**: Data fetching with caching
+- **TypeScript**: Full type safety
+
+## API Configuration
+
+Set in `generated/code/.env`:
+
+```env
+VITE_API_BASE_URL=https://your-api.com
+VITE_API_PREFIX=/api
+```
+
+## Deployment
+
+This generates a standalone React SPA that can deploy to:
+- Vercel, Netlify (static hosting)
+- AWS S3 + CloudFront
+- GitHub Pages
+- Any static file server
+
+---
+
+For comprehensive SpecVerse guidance, see the main [SpecVerse CLAUDE.md](https://github.com/SpecVerse/specverse-lang/blob/main/CLAUDE.md)

package/assets/templates/frontend-only/README.md

@@ -0,0 +1,231 @@
+# {{projectName}} - React Frontend
+
+A standalone React SPA built with SpecVerse. Perfect for JAMstack apps, connecting to external APIs, and frontend-first development.
+
+## 🚀 Quick Start
+
+```bash
+# 1. Configure your API endpoint
+echo "VITE_API_BASE_URL=https://your-api.com" > generated/code/.env
+
+# 2. Generate frontend code
+npm run realize:all
+
+# 3. Install dependencies
+cd generated/code && npm install
+
+# 4. Start development server
+npm run dev
+
+# 5. Open in browser
+open http://localhost:5173
+```
+
+## 📁 Project Structure
+
+```
+{{projectName}}/
+├── specs/
+│   └── main.specly              # UI specification
+├── manifests/
+│   └── implementation.yaml      # Frontend-only manifest
+├── generated/
+│   └── code/                    # Standalone React app
+│       ├── src/
+│       │   ├── App.tsx          # Root component with routing
+│       │   ├── main.tsx         # React entry point
+│       │   ├── components/      # View components
+│       │   ├── hooks/           # React Query hooks
+│       │   └── types/           # TypeScript types
+│       ├── index.html           # HTML entry point
+│       ├── vite.config.ts       # Vite configuration
+│       └── package.json         # Frontend dependencies
+└── package.json                 # Workflow scripts
+```
+
+## 🛠️ Development Workflow
+
+### 1. Modify Your UI
+
+Edit `specs/main.specly` to define your views and models:
+
+```yaml
+models:
+  Product:
+    attributes:
+      name: String required
+      price: Decimal required
+
+views:
+  ProductListView:
+    model: Product
+    components:
+      ProductGrid: {}
+      ProductFilters: {}
+```
+
+### 2. Regenerate Code
+
+```bash
+npm run realize:all
+```
+
+### 3. Run Development Server
+
+```bash
+cd generated/code
+npm run dev
+```
+
+The app will be available at `http://localhost:5173`
+
+## 🌐 Connecting to Your API
+
+### Environment Configuration
+
+Create `.env` in `generated/code/`:
+
+```env
+# Required: Your backend API URL
+VITE_API_BASE_URL=https://api.example.com
+
+# Optional: API path prefix
+VITE_API_PREFIX=/api
+```
+
+### Supported API Backends
+
+This frontend can connect to:
+- **SpecVerse Backend**: Generated with backend-only template
+- **Existing REST APIs**: Any REST API with JSON responses
+- **Third-Party APIs**: External services (with CORS configured)
+- **Serverless Functions**: AWS Lambda, Vercel Functions, etc.
+
+### API Client
+
+The generated code uses React Query for data fetching:
+
+```typescript
+// Auto-generated hook
+import { useProduct } from './hooks/useProduct';
+
+function ProductDetail({ id }: { id: string }) {
+  const { data, isLoading } = useProduct(id);
+  
+  if (isLoading) return <div>Loading...</div>;
+  return <div>{data.name}</div>;
+}
+```
+
+## 🧪 Testing
+
+```bash
+# Run tests
+cd generated/code && npm test
+
+# Type checking
+npm run typecheck
+
+# Linting
+npm run lint
+```
+
+## 📦 Deployment
+
+### Build for Production
+
+```bash
+cd generated/code
+npm run build
+```
+
+This creates an optimized build in `dist/`.
+
+### Deployment Options
+
+The generated frontend can be deployed to:
+
+- **Vercel**: `vercel deploy`
+- **Netlify**: Connect to git repository
+- **AWS S3 + CloudFront**: Static site hosting
+- **GitHub Pages**: Static site hosting
+- **Docker**: Serve with nginx
+
+### Environment Variables
+
+Set these in your deployment platform:
+
+```env
+VITE_API_BASE_URL=https://your-production-api.com
+```
+
+## 🎨 Customization
+
+### Styling
+
+The generated app uses Tailwind CSS by default. Customize in:
+- `generated/code/tailwind.config.js`
+- `generated/code/src/index.css`
+
+### Routing
+
+Routes are auto-generated from views. Customize in:
+- `generated/code/src/App.tsx`
+
+### API Client
+
+API configuration in:
+- `generated/code/src/hooks/*` - Generated React Query hooks
+- `generated/code/vite.config.ts` - Proxy configuration for development
+
+## 📚 Documentation
+
+### Generate UI Documentation
+
+```bash
+npm run generate:docs
+npm run generate:diagrams
+```
+
+## 🎯 Use Cases
+
+This frontend-only template is ideal for:
+
+- **JAMstack Applications**: Static frontend + API backend
+- **Micro-frontends**: Independent frontend deployment
+- **Mobile Web Apps**: PWAs connecting to existing APIs
+- **Prototyping**: Quick UI development against mock/existing APIs
+- **Frontend-First Development**: Design UI before backend is ready
+
+## 🔗 Example Configurations
+
+### Connect to SpecVerse Backend
+
+```env
+# Local development
+VITE_API_BASE_URL=http://localhost:3000
+
+# Production
+VITE_API_BASE_URL=https://api.yourapp.com
+```
+
+### Connect to Third-Party API
+
+```env
+# JSONPlaceholder (for testing)
+VITE_API_BASE_URL=https://jsonplaceholder.typicode.com
+
+# Your API
+VITE_API_BASE_URL=https://api.stripe.com
+```
+
+## 📖 Learn More
+
+- [SpecVerse Documentation](https://specverse.dev)
+- [React Documentation](https://react.dev)
+- [Vite Documentation](https://vitejs.dev)
+- [React Query Documentation](https://tanstack.com/query)
+
+---
+
+Built with ❤️ using [SpecVerse](https://specverse.dev)

package/assets/templates/frontend-only/deployments/README.md

@@ -0,0 +1,149 @@
+# Deployments Directory
+
+This directory can be used to organize deployment specifications when you need multiple deployment targets or environment-specific configurations.
+
+## Usage
+
+Deployments can be organized by environment, scale, or target platform:
+
+1. **Environment-based organization**:
+   ```
+   deployments/
+   ├── development.specly
+   ├── staging.specly
+   └── production.specly
+   ```
+
+2. **Scale-based organization**:
+   ```
+   deployments/
+   ├── personal.specly      # Single developer, local database
+   ├── team.specly          # Small team, shared database
+   ├── business.specly      # Business scale, clustering
+   └── enterprise.specly    # Enterprise scale, multi-tenant
+   ```
+
+3. **Platform-based organization**:
+   ```
+   deployments/
+   ├── local.specly         # Local development
+   ├── cloud.specly         # Cloud deployment (AWS, GCP, Azure)
+   ├── kubernetes.specly    # Kubernetes clusters
+   └── serverless.specly    # Serverless functions
+   ```
+
+## Deployment Patterns
+
+### Based on SpecVerse Library Patterns
+
+You can reference deployment patterns from the SpecVerse library system:
+
+- **Monolith Pattern**: Single-instance deployment (from `libs/deployments/monolith/`)
+- **Microservices Pattern**: Service-based deployment (from `libs/deployments/microservices/`)
+- **JAMstack Pattern**: Static + API deployment (from `libs/deployments/jamstack/`)
+- **Enterprise Pattern**: Multi-tenant, compliance-ready (from `libs/deployments/enterprise/`)
+
+### Example Deployment Structure
+
+```yaml
+# deployments/development.specly
+components:
+  my-app-dev:
+    version: "3.1.0"
+    
+    # Reference library patterns
+    import:
+      - file: ../../../libs/deployments/monolith/lib/development.yaml
+        select: ["development"]
+    
+    deployments:
+      development:
+        version: "3.1.0"
+        environment: "development"
+        
+        # Based on monolith development pattern
+        instances:
+          controllers:
+            appController:
+              component: "my-app"
+              namespace: "api"
+              scale: 1
+              advertises: ["api.*"]
+              uses: ["database.*"]
+```
+
+## Instance Types
+
+SpecVerse v3.3 supports these logical instance types:
+
+- **Controllers**: API endpoints, request handlers
+- **Services**: Business logic, background processing
+- **Views**: UI components, frontend applications
+- **Storage**: Databases, caches, file systems
+- **Security**: Authentication, authorization, encryption
+- **Infrastructure**: Load balancers, CDNs, service mesh
+- **Monitoring**: Metrics, logging, alerting, analytics
+- **Communications**: Message queues, event buses, RPC channels
+
+## Capability Patterns
+
+Use capability patterns to define instance communication:
+
+```yaml
+instances:
+  controllers:
+    apiController:
+      advertises: ["api.*", "auth.*"]     # What this instance provides
+      uses: ["database.*", "cache.*"]     # What this instance depends on
+```
+
+## Scaling Configuration
+
+Define scaling behavior for different environments:
+
+```yaml
+instances:
+  controllers:
+    webApi:
+      scale: 3                          # Number of instances
+      advertises: ["api.*"]
+      uses: ["database.*"]
+      config:
+        resources:
+          memory: "512Mi"
+          cpu: "200m"
+        healthCheck:
+          path: "/health"
+          interval: "30s"
+```
+
+## Import Examples
+
+```yaml
+# In main.specly, reference deployment specifications
+deployments:
+  development:
+    import:
+      - file: deployments/development.specly
+        select: ["development"]
+  
+  production:
+    import:
+      - file: deployments/production.specly
+        select: ["production"]
+```
+
+## Best Practices
+
+1. **Environment Separation**: Keep development and production deployments separate
+2. **Library Usage**: Reference standard patterns from `libs/deployments/`
+3. **Capability Design**: Use clear advertises/uses patterns for dependencies
+4. **Scaling Strategy**: Define appropriate scaling for each environment
+5. **Security Layering**: Include security instances for authentication and authorization
+6. **Monitoring Integration**: Add monitoring instances for production deployments
+
+## See Also
+
+- **Library Patterns**: `../../libs/deployments/` for standard deployment patterns
+- **Manifests**: `../manifests/` for technology-specific implementation guidance
+- **Main Specification**: `../specs/main.specly` for component definitions