@specverse/engine-realize 3.5.3

package/assets/templates/backend-only/scripts/test-all.sh

@@ -0,0 +1,160 @@
+#!/bin/bash
+
+# SpecVerse Comprehensive Test Script
+# Tests all commands and validates generated specifications
+
+set -e  # Exit on any error
+
+echo "🚀 Starting comprehensive SpecVerse test..."
+
+# Create necessary directories
+mkdir -p generated docs/diagrams generated/docs generated/code
+
+# Step 1: Validate original specification
+echo "📋 Step 1: Validating original specification..."
+npm run validate
+
+# Step 2: Generate complete specification and validate it
+echo "🧠 Step 2: Generating and validating complete specification..."
+npm run infer
+specverse validate generated/{{projectNameKebab}}-complete.specly
+
+# Step 3: Generate development deployment and validate it
+echo "🏗️ Step 3: Generating and validating development deployment..."
+npm run infer:deployment
+specverse validate generated/{{projectNameKebab}}-deployed.specly
+
+# Step 4: Generate production deployment and validate it
+echo "🏭 Step 4: Generating and validating production deployment..."
+npm run infer:deployment:prod
+specverse validate generated/{{projectNameKebab}}-deployed-prod.specly
+
+# Step 5: Generate documentation and diagrams for original spec
+echo "📚 Step 5: Generating docs and diagrams for original specification..."
+npm run generate:docs
+npm run generate:diagrams
+
+# Step 6: Generate documentation for all inferred specifications
+echo "📖 Step 6: Generating docs for all inferred specifications..."
+npm run infer:docs
+npm run infer:deployment:docs
+npm run infer:deployment:prod:docs
+
+# Step 7: Test YAML processing
+echo "⚙️ Step 7: Testing YAML processing..."
+npm run process
+
+# Step 8: Test v3.3 Code Realization (NEW)
+echo "🔧 Step 8: Testing v3.3 code realization..."
+echo "   → Generating complete runnable project..."
+npm run realize:all
+
+# Verify generated project structure
+echo "   → Verifying generated project..."
+if [ -f "generated/code/package.json" ]; then
+  echo "   ✅ package.json generated"
+fi
+
+if [ -f "generated/code/tsconfig.json" ]; then
+  echo "   ✅ tsconfig.json generated"
+fi
+
+if [ -f "generated/code/.env.example" ]; then
+  echo "   ✅ .env.example generated"
+fi
+
+if [ -f "generated/code/README.md" ]; then
+  echo "   ✅ README.md generated"
+fi
+
+# Check for backend structure
+if [ -d "generated/code/backend" ]; then
+  echo "   ✅ Backend directory generated"
+
+  if [ -f "generated/code/backend/src/main.ts" ]; then
+    echo "   ✅ Backend entry point (backend/src/main.ts) generated"
+  fi
+
+  # Check for ORM schema (Prisma for default template)
+  if [ -f "generated/code/backend/prisma/schema.prisma" ]; then
+    echo "   ✅ Prisma ORM schema generated"
+  elif [ -d "generated/code/backend/src/entities" ] || [ -d "generated/code/backend/src/models" ]; then
+    echo "   ✅ ORM schema generated"
+  fi
+
+  if [ -d "generated/code/backend/src/controllers" ]; then
+    echo "   ✅ Controllers generated"
+  fi
+
+  if [ -d "generated/code/backend/src/routes" ]; then
+    echo "   ✅ Route handlers generated"
+  fi
+fi
+
+# Check for frontend structure
+if [ -d "generated/code/frontend" ]; then
+  echo "   ✅ Frontend directory generated"
+
+  if [ -f "generated/code/frontend/src/main.tsx" ]; then
+    echo "   ✅ Frontend entry point (frontend/src/main.tsx) generated"
+  fi
+
+  if [ -d "generated/code/frontend/src/components" ]; then
+    echo "   ✅ React components generated"
+  fi
+fi
+
+# Check for v3.3 CURVED features in generated code
+if [ -d "generated/code/backend/src/controllers" ]; then
+  # Check for unified validation method (v3.3)
+  if grep -q "validate(.*context.*operation" generated/code/backend/src/controllers/*.ts 2>/dev/null; then
+    echo "   ✅ v3.3 unified validation method present"
+  fi
+
+  # Check for delete operation (not destroy)
+  if grep -q "async delete(id:" generated/code/backend/src/controllers/*.ts 2>/dev/null; then
+    echo "   ✅ v3.3 delete operation present (CURVED)"
+  fi
+
+  # Check for retrieveAll method (list operation)
+  if grep -q "async retrieveAll" generated/code/backend/src/controllers/*.ts 2>/dev/null; then
+    echo "   ✅ v3.3 retrieveAll method present (CURVED)"
+  fi
+fi
+
+# Check for validate endpoint in routes
+if [ -d "generated/code/backend/src/routes" ]; then
+  if grep -q "'/validate'" generated/code/backend/src/routes/*.ts 2>/dev/null; then
+    echo "   ✅ v3.3 validate endpoint present (CURVED)"
+  fi
+fi
+
+echo ""
+echo "✅ All SpecVerse commands tested successfully!"
+echo "✅ All generated specifications are valid and documented."
+echo ""
+echo "📊 Test Summary:"
+echo "   - Original specification: validated"
+echo "   - Complete specification: generated and validated"
+echo "   - Development deployment: generated and validated"
+echo "   - Production deployment: generated and validated"
+echo "   - Documentation: generated for all specifications"
+echo "   - Diagrams: generated for all specifications"
+echo "   - YAML processing: tested"
+echo "   - v3.3 Code realization: tested"
+echo "   - Complete runnable project: generated"
+echo ""
+echo "🎉 SpecVerse workflow is fully functional!"
+echo ""
+echo "💡 Next steps:"
+echo "   To run the generated full-stack application:"
+echo "   1. cd /path/to/project (if not already there)"
+echo "   2. npm run genAll (if not already run - installs deps and sets up DB)"
+echo "   3. npm run app:build (build TypeScript)"
+echo "   4. npm run app:dev:backend (Terminal 1 - starts backend on :3000)"
+echo "   5. npm run app:dev:frontend (Terminal 2 - starts frontend on :5173)"
+echo ""
+echo "   Or run 'npm run app:dev' to see detailed instructions"
+echo ""
+echo "   Backend API: http://localhost:3000/api/{{componentNameKebab}}s"
+echo "   Frontend UI: http://localhost:5173"

package/assets/templates/backend-only/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/backend-only/specs/main.specly

@@ -0,0 +1,67 @@
+# SpecVerse Backend-Only API
+# A REST API service without frontend - perfect for microservices and API-first development
+#
+# To use:
+# 1. Run: npm run realize:all
+# 2. Run: cd generated/code && npm install
+# 3. Run: npm run db:generate && npm run db:push
+# 4. Run: npm run dev
+# 5. Test: curl http://localhost:3000/api/products
+
+components:
+  {{componentName}}:
+    version: "1.0.0"
+    description: "{{projectName}} - Backend API Service"
+    tags: ["backend", "api", "microservice"]
+
+    models:
+      Product:
+        description: "Product in the catalog"
+
+        metadata:
+          id: uuid
+          audit: true
+
+        attributes:
+          name: String required min=1 max=200
+          description: Text
+          price: Decimal required min=0
+          sku: String required unique
+          inStock: Boolean default=true
+          category: String values=["Electronics", "Clothing", "Books", "Home", "Other"] default="Other"
+
+    controllers:
+      ProductController:
+        model: Product
+        description: "REST API for product management"
+
+        cured:
+          create: {}
+          retrieve: {}
+          update: {}
+          validate: {}
+          evolve: {}
+          delete: {}
+
+deployments:
+  development:
+    version: "1.0.0"
+    description: "{{projectName}} 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/default/CLAUDE.md

@@ -0,0 +1,141 @@
+# {{projectName}} - Claude Code Development Guide
+
+This file provides Claude-specific guidance for working with this SpecVerse project.
+
+## Project Overview
+
+**Project**: {{projectName}}
+**Component**: {{componentName}}
+**Type**: SpecVerse Specification
+
+**For comprehensive SpecVerse guidance, see `AI-GUIDE.md`**
+
+## Claude Code Specific Features
+
+### File Operations
+- **Read specifications**: Use Read tool to examine `specs/main.specly`
+- **Edit specifications**: Use Edit tool to modify models and deployments  
+- **Run validation**: Use Bash tool with `specverse validate specs/main.specly`
+- **Generate artifacts**: Use Bash tool with `specverse generate` commands
+
+### Development Workflow with Claude Code
+1. **Read current spec**: `specs/main.specly`
+2. **Understand requirements**: Check project documentation
+3. **Make targeted changes**: Use Edit tool for specific modifications
+4. **Validate changes**: Run `specverse validate` 
+5. **Generate outputs**: Create diagrams, docs as needed
+
+### Common Claude Code Tasks
+
+#### Adding Models
+```bash
+# Read current spec
+# Use Edit tool to add new models
+# Validate with: specverse validate specs/main.specly
+```
+
+#### Generating Documentation
+```bash
+specverse gen docs specs/main.specly --output docs/
+```
+
+#### Creating Diagrams
+```bash
+# Generate all diagrams
+specverse gen diagram specs/main.specly --output docs/diagrams/
+
+# Generate specific diagram types
+specverse gen diagram specs/main.specly -t er-diagram -o docs/diagrams/er.mmd
+specverse gen diagram specs/main.specly -t event-flow-layered -o docs/diagrams/events.mmd
+specverse gen diagram specs/main.specly -t lifecycle -o docs/diagrams/lifecycle.mmd
+specverse gen diagram specs/main.specly -t deployment-topology -o docs/diagrams/deploy.mmd
+```
+
+#### Event-Flow Diagrams
+The event-flow-layered diagram type uses topological sorting to visualize:
+- Models publishing events
+- Services subscribing to events
+- Controllers orchestrating flows
+- Views consuming data
+
+Example: `npm run generate:diagram:event-flow`
+
+#### Running Inference
+```bash
+specverse infer specs/main.specly -o specs/{{projectNameKebab}}-complete.specly
+```
+
+#### Working with Manifests (v3.3)
+```bash
+# Implementation manifest (default)
+manifests/implementation.yaml
+
+# Platform-specific manifests
+manifests/docker-compose.specly  # Development with Docker
+manifests/kubernetes.specly      # Production with Kubernetes
+
+# Generate code using manifest
+specverse realize specs/main.specly --manifest manifests/implementation.yaml
+```
+
+**Manifest v3.3 Format**: All manifests now use the v3.3 format with:
+- `specVersion: "3.3.0"` (REQUIRED)
+- `deployment:` section (REQUIRED - references spec and deployment name)
+- `defaultMappings:` for technology stack defaults
+- `capabilityMappings:` for capability-to-factory mappings (using `instanceFactory` field)
+- `configuration:` section for platform-specific settings
+
+## Claude Code Best Practices
+
+### When Reading Files
+- Always read `specs/main.specly` first to understand current state
+- Check for existing models, relationships, and deployments
+- Look for TODOs or placeholder content
+
+### When Making Changes  
+- Use Edit tool for precise modifications
+- Preserve existing structure and formatting
+- Follow SpecVerse convention syntax
+- Validate immediately after changes
+
+### When Running Commands
+- Use descriptive descriptions for Bash commands
+- Check command output for errors
+- Run validation after structural changes
+
+## Quick Reference
+
+### Essential Commands
+```bash
+# Validate specification
+specverse validate specs/main.specly
+
+# Generate complete architecture
+specverse infer specs/main.specly -o specs/expanded.specly
+
+# Generate all diagrams
+specverse gen uml specs/main.specly
+
+# Generate deployment diagram
+specverse gen uml specs/main.specly
+```
+
+### File Structure
+```
+{{projectName}}/
+├── CLAUDE.md               # This file
+├── AI-GUIDE.md            # Reference to comprehensive guide
+├── README.md              # Project overview
+├── specs/
+│   └── main.specly        # Main specification (v3.3)
+├── manifests/
+│   ├── implementation.yaml    # Implementation manifest (v3.3)
+│   ├── docker-compose.specly  # Docker deployment manifest (v3.3)
+│   └── kubernetes.specly      # Kubernetes deployment manifest (v3.3)
+└── docs/                  # Generated documentation
+    └── diagrams/          # Generated diagrams
+```
+
+---
+*Generated for SpecVerse - AI-Powered Specification Language*
+*Claude Code Integration Guide*