@specverse/engine-realize 3.5.3

package/assets/templates/frontend-only/generated/code/integration-test.template.js

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+
+/**
+ * Integration Test for Generated Code
+ *
+ * Tests that generated services and routes actually execute correctly:
+ * - Service methods can be called
+ * - Validation works
+ * - Database operations execute (with mock)
+ * - Event publishing happens
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ANSI color codes
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const BLUE = '\x1b[34m';
+const RESET = '\x1b[0m';
+
+let testsPassed = 0;
+let testsFailed = 0;
+
+function log(message, color = RESET) {
+  console.log(`${color}${message}${RESET}`);
+}
+
+function assert(condition, message) {
+  if (condition) {
+    log(`  ✅ ${message}`, GREEN);
+    testsPassed++;
+    return true;
+  } else {
+    log(`  ❌ ${message}`, RED);
+    testsFailed++;
+    return false;
+  }
+}
+
+// Mock database and event bus
+class MockDatabase {
+  constructor() {
+    this.data = new Map();
+    this.operations = [];
+  }
+
+  create(model, data) {
+    const id = data.id || Math.random().toString(36);
+    const record = { ...data, id, createdAt: new Date(), version: 0 };
+    this.data.set(id, record);
+    this.operations.push({ type: 'create', model, data: record });
+    return record;
+  }
+
+  findOne(model, where) {
+    for (const [id, record] of this.data.entries()) {
+      if (where.id === id && (!where.deletedAt || record.deletedAt === where.deletedAt)) {
+        return record;
+      }
+    }
+    return null;
+  }
+
+  update(model, id, data) {
+    const record = this.data.get(id);
+    if (!record) return null;
+
+    const updated = { ...record, ...data, updatedAt: new Date(), version: record.version + 1 };
+    this.data.set(id, updated);
+    this.operations.push({ type: 'update', model, id, data: updated });
+    return updated;
+  }
+
+  delete(model, id) {
+    const record = this.data.get(id);
+    if (!record) return null;
+
+    // Soft delete
+    record.deletedAt = new Date();
+    this.data.set(id, record);
+    this.operations.push({ type: 'delete', model, id });
+    return record;
+  }
+}
+
+class MockEventBus {
+  constructor() {
+    this.events = [];
+  }
+
+  async publish(eventName, payload) {
+    this.events.push({ eventName, payload, timestamp: new Date() });
+  }
+
+  getEvents() {
+    return this.events;
+  }
+}
+
+async function runTests() {
+  log('\n🧪 Running Integration Tests for Generated Code\n', BLUE);
+
+  // Test 1: Check file structure
+  log('Test Suite 1: File Structure', BLUE);
+  assert(existsSync(join(__dirname, 'services')), 'Services directory exists');
+  assert(existsSync(join(__dirname, 'routes')), 'Routes directory exists');
+
+  // Test 2: Load and instantiate service
+  log('\nTest Suite 2: Service Instantiation', BLUE);
+
+  const db = new MockDatabase();
+  const eventBus = new MockEventBus();
+
+  let ServiceClass;
+  let serviceName;
+
+  // Try to find a service file
+  const { readdirSync } = await import('fs');
+  const serviceFiles = readdirSync(join(__dirname, 'services')).filter(f => f.endsWith('.service.ts'));
+
+  if (serviceFiles.length === 0) {
+    log('  ⚠️  No service files found to test', YELLOW);
+    return;
+  }
+
+  serviceName = serviceFiles[0].replace('.service.ts', '');
+  log(`  📝 Testing service: ${serviceName}`, BLUE);
+
+  try {
+    // Note: This requires tsx or ts-node to run TypeScript directly
+    // For production testing, compile to JS first
+    const servicePath = join(__dirname, 'services', serviceFiles[0]);
+
+    log(`  → Attempting to load service from: ${servicePath}`);
+
+    // This is a demonstration - actual loading would need proper TS support
+    assert(existsSync(servicePath), `Service file exists: ${serviceFiles[0]}`);
+
+  } catch (error) {
+    log(`  ⚠️  Service loading requires TypeScript compilation: ${error.message}`, YELLOW);
+  }
+
+  // Test 3: Validate method structure (by reading source)
+  log('\nTest Suite 3: v3.3 Feature Detection', BLUE);
+
+  const { readFileSync } = await import('fs');
+  const serviceContent = readFileSync(join(__dirname, 'services', serviceFiles[0]), 'utf-8');
+
+  // Check for v3.3 features
+  assert(
+    serviceContent.includes('validate(data'),
+    'Service has unified validate() method'
+  );
+
+  assert(
+    serviceContent.includes("operation: 'create' | 'update' | 'evolve'"),
+    'Validate method accepts operation context'
+  );
+
+  assert(
+    serviceContent.includes('this.validate(data,'),
+    'CURED operations call validate() internally'
+  );
+
+  assert(
+    serviceContent.includes('version mismatch') || serviceContent.includes('version'),
+    'Optimistic locking (version checking) present'
+  );
+
+  assert(
+    serviceContent.includes('deletedAt: null') || serviceContent.includes('isDeleted:'),
+    'Soft delete filtering present'
+  );
+
+  assert(
+    serviceContent.includes('eventBus.publish'),
+    'Event publishing present'
+  );
+
+  // Test 4: Route structure
+  log('\nTest Suite 4: Route Structure', BLUE);
+
+  const routeDirs = readdirSync(join(__dirname, 'routes')).filter(f => {
+    const stat = require('fs').statSync(join(__dirname, 'routes', f));
+    return stat.isDirectory();
+  });
+
+  assert(routeDirs.length > 0, `Found ${routeDirs.length} route directory(ies)`);
+
+  for (const routeDir of routeDirs) {
+    const routeFiles = readdirSync(join(__dirname, 'routes', routeDir));
+
+    // Check for CURED operations
+    const hasCRUD = routeFiles.some(f => ['create', 'retrieve', 'update', 'destroy'].some(op => f.includes(op)));
+    assert(hasCRUD, `${routeDir}: Has CURED operation files`);
+
+    // Check for validate endpoint
+    const hasValidate = routeFiles.some(f => f.includes('validate'));
+    assert(hasValidate, `${routeDir}: Has unified validate endpoint`);
+
+    // Should NOT have validate-create or validate-update
+    const hasWrongValidate = routeFiles.some(f =>
+      f.includes('validate-create') || f.includes('validate-update')
+    );
+    assert(!hasWrongValidate, `${routeDir}: No separate validate-create/update endpoints`);
+  }
+
+  // Test 5: Mock service execution
+  log('\nTest Suite 5: Mock Service Execution', BLUE);
+
+  // Create a simple mock service to demonstrate functionality
+  class MockTaskService {
+    constructor(db, eventBus) {
+      this.db = db;
+      this.eventBus = eventBus;
+    }
+
+    validate(data, context) {
+      const errors = [];
+
+      if (context.operation === 'create') {
+        if (!data.title) {
+          errors.push('Title is required');
+        }
+      }
+
+      return { valid: errors.length === 0, errors };
+    }
+
+    async create(data) {
+      const validationResult = this.validate(data, { operation: 'create' });
+      if (!validationResult.valid) {
+        throw new Error(`Validation failed: ${validationResult.errors.join(', ')}`);
+      }
+
+      const task = this.db.create('Task', data);
+      await this.eventBus.publish('TaskCreated', { taskId: task.id });
+      return task;
+    }
+
+    async update(id, data) {
+      const validationResult = this.validate(data, { operation: 'update' });
+      if (!validationResult.valid) {
+        throw new Error(`Validation failed: ${validationResult.errors.join(', ')}`);
+      }
+
+      // Version checking
+      if (data.version !== undefined) {
+        const existing = this.db.findOne('Task', { id });
+        if (existing && existing.version !== data.version) {
+          throw new Error('Version mismatch: record has been modified');
+        }
+      }
+
+      const task = this.db.update('Task', id, data);
+      await this.eventBus.publish('TaskUpdated', { taskId: id });
+      return task;
+    }
+  }
+
+  const mockService = new MockTaskService(db, eventBus);
+
+  // Test create with validation
+  try {
+    await mockService.create({ title: 'Test Task' });
+    assert(true, 'Service.create() executed successfully');
+  } catch (error) {
+    assert(false, `Service.create() failed: ${error.message}`);
+  }
+
+  assert(db.operations.length > 0, 'Database operations were performed');
+  assert(eventBus.events.length > 0, 'Events were published');
+
+  // Test validation failure
+  try {
+    await mockService.create({});
+    assert(false, 'Validation should have failed for empty data');
+  } catch (error) {
+    assert(error.message.includes('Validation failed'), 'Validation correctly rejected invalid data');
+  }
+
+  // Test optimistic locking
+  const task = db.data.values().next().value;
+  try {
+    await mockService.update(task.id, { title: 'Updated', version: 999 });
+    assert(false, 'Version mismatch should have been detected');
+  } catch (error) {
+    assert(error.message.includes('Version mismatch'), 'Optimistic locking works correctly');
+  }
+
+  // Summary
+  log('\n═══════════════════════════════════════', BLUE);
+  log(`Integration Test Summary:`, BLUE);
+  log(`  ✅ Passed: ${testsPassed}`, GREEN);
+  if (testsFailed > 0) {
+    log(`  ❌ Failed: ${testsFailed}`, RED);
+  }
+  log(`  📊 Total: ${testsPassed + testsFailed}`, BLUE);
+
+  if (testsFailed === 0) {
+    log('\n🎉 All integration tests passed!', GREEN);
+    process.exit(0);
+  } else {
+    log('\n⚠️  Some tests failed', YELLOW);
+    process.exit(1);
+  }
+}
+
+// Run tests
+runTests().catch(error => {
+  log(`\n❌ Test suite failed: ${error.message}`, RED);
+  console.error(error);
+  process.exit(1);
+});

package/assets/templates/frontend-only/generated/code/package.json.template

@@ -0,0 +1,34 @@
+{
+  "name": "{{projectNameKebab}}-generated-code",
+  "version": "0.1.0",
+  "description": "Generated code for {{projectName}} - v3.3 runtime",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "node test-runner.js",
+    "test:integration": "node integration-tests.js",
+    "start:dev": "tsx services/index.ts",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate": "prisma migrate dev",
+    "db:setup": "node setup-database.js"
+  },
+  "dependencies": {
+    "@prisma/client": "^5.0.0",
+    "typeorm": "^0.3.17",
+    "reflect-metadata": "^0.1.13",
+    "fastify": "^4.23.0",
+    "express": "^4.18.2",
+    "@nestjs/common": "^10.2.0",
+    "@nestjs/core": "^10.2.0",
+    "@nestjs/platform-express": "^10.2.0",
+    "zod": "^3.22.0",
+    "better-sqlite3": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/express": "^4.17.17",
+    "typescript": "^5.2.0",
+    "tsx": "^3.12.0",
+    "vitest": "^0.34.0"
+  }
+}

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

@@ -0,0 +1,49 @@
+# Generated Documentation
+
+This directory contains documentation and diagrams automatically generated from inferred SpecVerse specifications.
+
+## Content Types
+
+### Documentation Files
+- **`*-complete-docs.md`**: Complete documentation from AI-inferred specifications
+- **`*-deployed-docs.md`**: Documentation for deployment specifications
+- **`*-deployed-prod-docs.md`**: Production deployment documentation
+
+### Diagram Files  
+- **`*-complete-diagrams.md`**: UML diagrams (ER, sequence, class) for complete specifications
+- **`*-deployed-diagrams.md`**: Deployment diagrams for development environment
+- **`*-deployed-prod-diagrams.md`**: Deployment diagrams for production environment
+
+## Auto-Generation
+
+These files are automatically generated when you run:
+
+```bash
+# Generates both specification and documentation
+npm run infer                    # → creates complete docs + diagrams
+npm run infer:deployment         # → creates development deployment docs + diagrams  
+npm run infer:deployment:prod    # → creates production deployment docs + diagrams
+```
+
+## Manual Generation
+
+You can also generate documentation for existing specifications:
+
+```bash
+# Generate docs for specific files
+npm run infer:docs                        # docs for complete specification
+npm run infer:deployment:docs             # docs for development deployment
+npm run infer:deployment:prod:docs        # docs for production deployment
+```
+
+## File Organization
+
+Files follow this naming pattern:
+- `{project-name}-complete-docs.md` - Documentation for AI-inferred complete specification
+- `{project-name}-complete-diagrams.md` - UML diagrams for complete specification  
+- `{project-name}-deployed-docs.md` - Documentation for development deployment
+- `{project-name}-deployed-diagrams.md` - Deployment diagrams for development
+- `{project-name}-deployed-prod-docs.md` - Documentation for production deployment
+- `{project-name}-deployed-prod-diagrams.md` - Deployment diagrams for production
+
+All files are automatically regenerated when you run infer commands.

package/assets/templates/frontend-only/gitignore

@@ -0,0 +1,54 @@
+# Dependencies
+node_modules/
+package-lock.json
+yarn.lock
+#pnpm-lock.yaml
+
+# Generated files
+generated/
+dist/
+build/
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# SpecVerse generated files
+specs/*-complete.specly
+specs/*-enhanced.specly
+specs/*-deployed.specly
+specs/*-deployed-prod.specly
+specs/*-processed.yaml
+docs/diagrams/
+docs/generated/
+
+# Database files (for development)
+*.db
+*.sqlite
+*.sqlite3
+dev.db
+
+# Test coverage
+coverage/
+.nyc_output/

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

@@ -0,0 +1,72 @@
+# Implementation Manifests
+
+This directory contains **SpecVerse v3.3 Implementation Manifests** that show how to deploy your component specifications to real infrastructure.
+
+## What are Manifests?
+
+Manifests bridge the gap between your logical SpecVerse specifications and concrete technology implementations. They define:
+
+- **Implementation Types**: How logical components map to specific technologies
+- **Behavior Mappings**: How model behaviors translate to actual code/API calls
+- **Capability Mappings**: How logical capabilities map to implementation types
+- **Communication Channels**: How components communicate in the real deployment
+- **Technology Configuration**: Framework-specific settings and parameters
+
+## Available Manifests
+
+### `implementation.yaml` ⭐ NEW - v3.3 Code Generation
+- **Purpose**: Technology stack configuration for code generation
+- **Features**: ORM selection, server framework, metadata strategies
+- **Use Case**: Generate production-ready code (services, routes, ORM schemas)
+- **Commands**:
+  ```bash
+  npm run generate:code        # Generate all code
+  npm run test:generators      # Generate and verify
+  ```
+
+### `docker-compose.specly`
+- **Target**: Local development and staging
+- **Technology**: Docker Compose
+- **Database**: SQLite (development-friendly)
+- **Use Case**: Quick local testing and development
+
+### `kubernetes.specly`
+- **Target**: Production deployment
+- **Technology**: Kubernetes with operators
+- **Database**: PostgreSQL with high availability
+- **Use Case**: Scalable production deployments
+
+## How to Use
+
+1. **Choose a manifest** that matches your deployment target
+2. **Customize the configuration** section for your specific needs
+3. **Reference your component** by updating the component source
+4. **Deploy using the specified tools** (docker-compose, kubectl, etc.)
+
+## Extending Manifests
+
+You can create additional manifests for other technologies:
+
+- **Cloud Providers**: AWS EKS, GCP GKE, Azure AKS
+- **Serverless**: AWS Lambda, Vercel, Netlify
+- **Traditional**: VM-based deployments, bare metal
+- **Container Platforms**: OpenShift, Rancher, Docker Swarm
+
+## Commands
+
+```bash
+# Validate a manifest
+specverse validate manifests/docker-compose.specly
+
+# Process a manifest with component context
+specverse gen yaml manifests/kubernetes.specly
+
+# Generate deployment documentation
+specverse gen docs manifests/kubernetes.specly
+```
+
+## Learn More
+
+- **SpecVerse Manifests Documentation**: See the main docs for comprehensive manifest features
+- **Examples**: Check `examples/06-deploy/` for more complex manifest patterns
+- **Best Practices**: Review the `aiInstructions` in each manifest for implementation guidance

package/assets/templates/frontend-only/manifests/docker-compose.specly

@@ -0,0 +1,91 @@
+# Docker Compose Implementation Manifest
+# SpecVerse v3.3 manifest specification for Docker Compose deployment
+
+manifests:
+  DockerComposeManifest:
+    specVersion: "3.3.0"
+    name: "{{componentName}}DockerComposeManifest"
+    version: "1.0.0"
+    description: "Docker Compose implementation manifest for {{projectName}}"
+
+    # v3.3: Deployment reference (REQUIRED)
+    deployment:
+      deploymentSource: "./specs/main.specly"
+      deploymentName: "development"
+
+    # v3.3: Default technology mappings
+    defaultMappings:
+      storage: "SQLite"
+      controller: "DockerNodeApp"
+
+    # v3.3: Capability to implementation factory mappings
+    capabilityMappings:
+      - capability: "api.*"
+        instanceFactory: "DockerWebApp"
+
+      - capability: "database.*"
+        instanceFactory: "DockerDatabase"
+
+    # v3.3: Platform-specific configuration
+    configuration:
+      # Docker Compose specific settings
+      composeVersion: "3.8"
+
+      networks:
+        default:
+          driver: "bridge"
+
+      volumes:
+        app_data:
+          driver: "local"
+
+      # Implementation type definitions
+      implementationFactories:
+        DockerWebApp:
+          type: "controller"
+          technology: "docker"
+          framework: "compose"
+          config:
+            image: "node:18-alpine"
+            build:
+              context: "."
+              dockerfile: "Dockerfile"
+            ports:
+              - "3000:3000"
+            environment:
+              NODE_ENV: "development"
+              DATABASE_URL: "sqlite:./data/app.db"
+            volumes:
+              - "./src:/app/src"
+              - "./data:/app/data"
+            restart: "unless-stopped"
+
+        DockerDatabase:
+          type: "database"
+          technology: "sqlite"
+          framework: "docker"
+          config:
+            image: "alpine:latest"
+            volumes:
+              - "./data:/data"
+            command: "tail -f /dev/null"
+
+      # Namespace configuration
+      namespace:
+        strategy: "single"
+        name: "{{projectNameKebab}}"
+        description: "Main application namespace"
+        isolation: "permissive"
+
+      # AI implementation instructions
+      aiInstructions: |
+        When implementing this Docker Compose deployment:
+
+        1. **Development Focus**: This manifest is optimized for local development
+        2. **Live Reload**: Source code is mounted for immediate changes
+        3. **Data Persistence**: SQLite database with volume mounting
+        4. **Port Mapping**: Application accessible on localhost:3000
+        5. **Environment**: Configure environment variables in docker-compose.yml
+        6. **Networking**: Uses default bridge network for container communication
+        7. **Database**: Simple SQLite setup for development (upgrade to PostgreSQL for production)
+        8. **Restart Policy**: Containers restart unless manually stopped

package/assets/templates/frontend-only/manifests/implementation.yaml

@@ -0,0 +1,58 @@
+# SpecVerse v3.3 Implementation Manifest - Frontend Only
+# Generates standalone React frontend that connects to external API
+
+manifests:
+  {{projectNameKebab}}Implementation:
+    specVersion: "3.3.0"
+    name: "{{projectNameKebab}}-frontend"
+    version: "1.0.0"
+    description: "Frontend application for {{projectName}}"
+
+    # v3.3: Deployment reference
+    deployment:
+      deploymentSource: "../specs/main.specly"
+      deploymentName: "development"
+
+    # v3.3: Configuration for standalone frontend
+    configuration:
+      outputStructure: "standalone"
+      frontendDir: "."
+      
+      # External API connection (configured at runtime)
+      apiBaseUrl: "${VITE_API_BASE_URL}"
+      apiPrefix: "/api"
+
+      # Development server
+      vitePort: 5173
+      viteHost: "localhost"
+
+    # v3.3: Frontend-only capability mappings
+    capabilityMappings:
+      # React Application
+      - capability: "app.frontend"
+        instanceFactory: "ReactApp"
+        configuration:
+          outputStructure: "standalone"
+          frontendDir: "."
+          apiBaseUrl: "${VITE_API_BASE_URL}"
+
+      # UI Components
+      - capability: "ui.components"
+        instanceFactory: "ReactComponents"
+        configuration:
+          outputStructure: "standalone"
+          frontendDir: "."
+
+      # UI Views
+      - capability: "ui.views"
+        instanceFactory: "ReactComponents"
+        configuration:
+          outputStructure: "standalone"
+          frontendDir: "."
+
+      # Project Scaffolding
+      - capability: "project.scaffold"
+        instanceFactory: "GenericScaffold"
+        configuration:
+          outputStructure: "standalone"
+          includeReadme: true