@specverse/engine-realize 3.5.3

package/libs/instance-factories/services/templates/prisma/service-generator.ts

@@ -0,0 +1,315 @@
+/**
+ * Prisma Service Generator
+ *
+ * Generates abstract business logic services
+ * Services are NOT tied to specific models but can interact with multiple models
+ */
+
+import type { TemplateContext } from '@specverse/engine-realize';
+import { generateBehaviorBody, type BehaviorContext, type BehaviorMetadata, type OperationMetadata } from './behavior-generator.js';
+
+/**
+ * Generate Prisma service
+ */
+export default function generatePrismaService(context: TemplateContext): string {
+  const { service, spec } = context;
+
+  if (!service) {
+    throw new Error('Service is required in template context');
+  }
+
+  const serviceName = service.name;
+  const hasEvents = (service.publishes && service.publishes.length > 0) ||
+                    (service.subscribes && service.subscribes.length > 0);
+
+  return `/**
+ * ${serviceName}
+ * Abstract business logic service
+ * ${service.description || ''}
+ */
+
+import { PrismaClient } from '@prisma/client';
+${hasEvents ? `import { eventBus, EventName } from '../events/eventBus.js';` : ''}
+
+const prisma = new PrismaClient();
+
+/**
+ * ${serviceName} class
+ */
+export class ${serviceName} {
+  ${generateConstructor(service)}
+  ${generateOperations(service)}
+  ${generateEventSubscriptions(service)}
+}
+
+// Export singleton instance
+export const ${serviceName.charAt(0).toLowerCase() + serviceName.slice(1)} = new ${serviceName}();
+export default ${serviceName.charAt(0).toLowerCase() + serviceName.slice(1)};
+`;
+}
+
+/**
+ * Generate constructor with event subscriptions
+ */
+function generateConstructor(service: any): string {
+  const hasSubscriptions = service.subscribes && service.subscribes.length > 0;
+
+  if (!hasSubscriptions) {
+    return '';
+  }
+
+  return `
+  private unsubscribers: Array<() => void> = [];
+
+  constructor() {
+    // Subscribe to events
+    this.setupEventSubscriptions();
+  }
+
+  /**
+   * Setup event subscriptions
+   */
+  private setupEventSubscriptions(): void {
+    ${service.subscribes.map((eventName: string) => `
+    // Subscribe to ${eventName}
+    const unsubscribe${eventName} = eventBus.subscribe(
+      EventName.${eventName},
+      this.on${eventName}.bind(this)
+    );
+    this.unsubscribers.push(unsubscribe${eventName});
+    `).join('\n')}
+  }
+
+  /**
+   * Cleanup subscriptions
+   */
+  public destroy(): void {
+    this.unsubscribers.forEach(unsubscribe => unsubscribe());
+    this.unsubscribers = [];
+  }
+`;
+}
+
+/**
+ * Generate service operations
+ */
+function generateOperations(service: any): string {
+  if (!service.operations ||
+      (Array.isArray(service.operations) && service.operations.length === 0) ||
+      (!Array.isArray(service.operations) && Object.keys(service.operations).length === 0)) {
+    return `
+  /**
+   * Execute service logic
+   */
+  public async execute(params: any): Promise<any> {
+    // TODO: Implement service logic
+    throw new Error('Service logic not implemented');
+  }
+`;
+  }
+
+  // Normalize: array of operations (with .name) or object entries
+  const entries: [string, any][] = Array.isArray(service.operations)
+    ? service.operations.map((op: any) => [op.name, op])
+    : Object.entries(service.operations);
+
+  const operations: string[] = [];
+
+  entries.forEach(([operationName, operation]) => {
+    operations.push(generateOperation(operationName, operation, service));
+  });
+
+  return operations.join('\n');
+}
+
+/**
+ * Generate individual operation
+ */
+function generateOperation(operationName: string, operation: any, service: any): string {
+  const params = generateOperationParams(operation);
+  const hasPublish = service.publishes && service.publishes.length > 0;
+
+  return `
+  /**
+   * ${operationName}
+   * ${operation.description || ''}
+   */
+  public async ${operationName}(${params}): Promise<any> {
+    try {
+      ${generateOperationLogic(operation, service)}
+
+      ${hasPublish ? `
+      // Publish event (example)
+      // eventBus.publish(EventName.SomeEvent, {
+      //   operation: '${operationName}',
+      //   timestamp: new Date().toISOString()
+      // });
+      ` : ''}
+
+      // Return result
+      return { success: true };
+    } catch (error) {
+      console.error(\`[${service.name}] ${operationName} failed:\`, error);
+      throw error;
+    }
+  }
+`;
+}
+
+/**
+ * Generate operation parameters
+ */
+function generateOperationParams(operation: any): string {
+  if (!operation.parameters || Object.keys(operation.parameters).length === 0) {
+    return 'params: any = {}';
+  }
+
+  const params = Object.entries(operation.parameters).map(([name, param]: [string, any]) => {
+    const optional = !param.required;
+    return `${name}${optional ? '?' : ''}: ${mapTypeToTypeScript(param.type)}`;
+  });
+
+  return params.join(', ');
+}
+
+/**
+ * Generate operation logic from behavioral metadata (L3 generation).
+ * Falls back to placeholder if no behavioral data available.
+ */
+function generateOperationLogic(operation: any, service: any): string {
+  // Check for behavioral metadata — supports both AI-optimized format (implementation.preconditions)
+  // and SpecVerse convention format (requires/ensures/publishes)
+  const impl = operation.implementation || {};
+  const meta = operation.metadata;
+
+  // Map convention format to implementation format
+  if (!impl.preconditions && operation.requires) {
+    impl.preconditions = Array.isArray(operation.requires) ? operation.requires : [operation.requires];
+  }
+  if (!impl.postconditions && operation.ensures) {
+    impl.postconditions = Array.isArray(operation.ensures) ? operation.ensures : [operation.ensures];
+  }
+  if (!impl.sideEffects && operation.publishes) {
+    impl.sideEffects = (Array.isArray(operation.publishes) ? operation.publishes : [operation.publishes])
+      .map((e: string) => `Publish event: ${e}`);
+  }
+
+  if (impl.preconditions?.length || impl.postconditions?.length || impl.steps?.length || impl.transactional) {
+    // L3: Generate from behavioral specification
+    const modelName = inferModelFromServiceName(service.name);
+    const context: BehaviorContext = {
+      modelName,
+      serviceName: service.name,
+      operationName: operation.name || 'execute',
+      prismaModel: modelName
+    };
+
+    const behavior: BehaviorMetadata = {
+      preconditions: impl.preconditions || [],
+      postconditions: impl.postconditions || [],
+      sideEffects: impl.sideEffects || [],
+      steps: impl.steps || [],
+      transactional: impl.transactional || false
+    };
+
+    const opMeta: OperationMetadata = {
+      async: meta?.async ?? true,
+      cacheable: meta?.cacheable ?? false,
+      idempotent: meta?.idempotent ?? false
+    };
+
+    return generateBehaviorBody(behavior, opMeta, context);
+  }
+
+  // Fallback: placeholder
+  if (operation.description) {
+    return `// ${operation.description}`;
+  }
+  return `// TODO: Implement operation logic`;
+}
+
+/**
+ * Infer model name from service name.
+ * "SpecificationRelationshipService" -> "Specification"
+ * "ModelRelationshipService" -> "Model"
+ */
+function inferModelFromServiceName(serviceName: string): string {
+  return serviceName
+    .replace(/RelationshipService$/, '')
+    .replace(/Service$/, '') || 'Entity';
+}
+
+/**
+ * Generate event subscription handlers
+ */
+function generateEventSubscriptions(service: any): string {
+  if (!service.subscribes || service.subscribes.length === 0) {
+    return '';
+  }
+
+  const handlers: string[] = [];
+
+  service.subscribes.forEach((eventName: string) => {
+    handlers.push(`
+  /**
+   * Handle ${eventName} event
+   */
+  private async on${eventName}(payload: any): Promise<void> {
+    try {
+      console.log(\`[${service.name}] Received ${eventName} event\`, payload);
+
+      // TODO: Implement event handling logic
+      ${generateEventHandlerLogic(eventName, service)}
+
+      console.log(\`[${service.name}] ${eventName} event processed successfully\`);
+    } catch (error) {
+      console.error(\`[${service.name}] Failed to process ${eventName} event\`, error);
+      // TODO: Add error handling (retry, dead letter queue, etc.)
+    }
+  }`);
+  });
+
+  return handlers.join('\n');
+}
+
+/**
+ * Generate event handler logic placeholder
+ */
+function generateEventHandlerLogic(eventName: string, service: any): string {
+  return `
+      // Example: Update related records
+      // await prisma.someModel.update({
+      //   where: { id: payload.id },
+      //   data: { ... }
+      // });
+
+      // Example: Trigger workflows
+      // await this.triggerWorkflow(payload);
+
+      // Example: Publish follow-up events
+      // eventBus.publish(EventName.AnotherEvent, {
+      //   original: payload,
+      //   processed: true
+      // });
+  `;
+}
+
+/**
+ * Map SpecVerse types to TypeScript types
+ */
+function mapTypeToTypeScript(type: string): string {
+  const typeMap: Record<string, string> = {
+    String: 'string',
+    Integer: 'number',
+    Float: 'number',
+    Boolean: 'boolean',
+    Date: 'Date',
+    DateTime: 'Date',
+    UUID: 'string',
+    JSON: 'any',
+    Array: 'any[]',
+    Object: 'Record<string, any>'
+  };
+
+  return typeMap[type] || 'any';
+}

package/libs/instance-factories/shared/path-resolver.ts

@@ -0,0 +1,111 @@
+/**
+ * Path Resolver Utility for Instance Factories
+ *
+ * Provides consistent path resolution based on output structure configuration.
+ * Supports both standalone and monorepo project structures.
+ */
+
+export type OutputStructure = 'standalone' | 'monorepo';
+
+export interface PathResolverConfig {
+  outputStructure?: OutputStructure;
+  backendDir?: string;
+  frontendDir?: string;
+  baseDir?: string;
+  apiBaseUrl?: string;
+}
+
+/**
+ * Resolves output path based on structure and target
+ */
+export function resolvePath(
+  relativePath: string,
+  target: 'backend' | 'frontend' | 'shared',
+  config: PathResolverConfig = {}
+): string {
+  const {
+    outputStructure = 'monorepo',
+    backendDir = 'backend',
+    frontendDir = 'frontend',
+    baseDir = '.'
+  } = config;
+
+  // For standalone structure, return path as-is
+  if (outputStructure === 'standalone') {
+    return baseDir === '.' ? relativePath : `${baseDir}/${relativePath}`;
+  }
+
+  // For monorepo structure, prefix with appropriate directory
+  const prefix = target === 'backend' ? backendDir : target === 'frontend' ? frontendDir : 'shared';
+  return `${prefix}/${relativePath}`;
+}
+
+/**
+ * Resolves import path for cross-component imports
+ */
+export function resolveImportPath(
+  from: 'backend' | 'frontend',
+  to: 'backend' | 'frontend' | 'shared',
+  importPath: string,
+  config: PathResolverConfig = {}
+): string {
+  const { outputStructure = 'monorepo' } = config;
+
+  // In standalone mode, imports should be external (via API or npm package)
+  if (outputStructure === 'standalone') {
+    if (from === 'frontend' && to === 'backend') {
+      // Frontend importing from backend - should use API calls, not direct imports
+      throw new Error('Frontend cannot directly import from backend in standalone mode. Use API calls.');
+    }
+    return importPath;
+  }
+
+  // In monorepo mode, adjust relative paths based on location
+  if (from === to) {
+    return importPath; // Same workspace, path unchanged
+  }
+
+  // Cross-workspace import in monorepo
+  if (from === 'frontend' && to === 'shared') {
+    return `../../shared/${importPath}`;
+  }
+  if (from === 'backend' && to === 'shared') {
+    return `../../shared/${importPath}`;
+  }
+
+  return importPath;
+}
+
+/**
+ * Gets API base URL configuration
+ */
+export function getApiBaseUrl(config: PathResolverConfig & { apiBaseUrl?: string }): string {
+  const { outputStructure = 'monorepo', apiBaseUrl } = config;
+
+  // Use configured URL if provided
+  if (apiBaseUrl) {
+    return apiBaseUrl;
+  }
+
+  // Default based on structure
+  if (outputStructure === 'standalone') {
+    // In standalone mode, expect external API
+    return '${VITE_API_BASE_URL}'; // Environment variable placeholder
+  }
+
+  // In monorepo mode, default to local backend
+  return 'http://localhost:3000';
+}
+
+/**
+ * Helper to get configuration from template context
+ */
+export function getPathConfig(context: any): PathResolverConfig {
+  return {
+    outputStructure: context.configuration?.outputStructure || 'monorepo',
+    backendDir: context.configuration?.backendDir || 'backend',
+    frontendDir: context.configuration?.frontendDir || 'frontend',
+    baseDir: context.configuration?.baseDir || '.',
+    apiBaseUrl: context.configuration?.apiBaseUrl
+  };
+}

package/libs/instance-factories/storage/mongodb.yaml

@@ -0,0 +1,79 @@
+name: MongoDB6
+version: "1.0.0"
+category: storage
+description: "MongoDB 6 document database with sharding and replication support"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [mongodb, database, nosql, document]
+
+compatibility:
+  specverse: "^3.3.0"
+  mongodb: ">=6.0"
+
+capabilities:
+  provides:
+    - "storage.database"
+    - "storage.database.document"
+    - "storage.database.nosql"
+    - "database.mongodb"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  database: "mongodb"
+  version: "6.x"
+
+dependencies:
+  runtime: []  # Database runs separately
+
+  dev:
+    - name: "mongodb"
+      version: "^6.3.0"
+      description: "MongoDB driver for Node.js"
+
+codeTemplates:
+  config:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/mongodb/config-generator.ts"
+    outputPattern: "config/database.{instance}.ts"
+
+  docker:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/mongodb/docker-generator.ts"
+    outputPattern: "docker/mongodb.{instance}.yml"
+
+configuration:
+  # Database connection
+  host: "${MONGO_HOST:-localhost}"
+  port: 27017
+  database: "${MONGO_DB}"
+  username: "${MONGO_USER}"
+  password: "${MONGO_PASSWORD}"
+  authSource: "admin"
+
+  # Connection options
+  options:
+    maxPoolSize: 10
+    minPoolSize: 2
+    serverSelectionTimeoutMS: 5000
+    socketTimeoutMS: 45000
+
+  # Replication
+  replication:
+    enabled: false
+    replSetName: "rs0"
+    replicas: 3
+
+  # Sharding
+  sharding:
+    enabled: false
+    shardKey: "_id"
+
+  # Backup
+  backup:
+    enabled: true
+    schedule: "0 2 * * *"  # Daily at 2am
+    retention: 7  # days

package/libs/instance-factories/storage/postgresql.yaml

@@ -0,0 +1,75 @@
+name: PostgreSQL15
+version: "1.0.0"
+category: storage
+description: "PostgreSQL 15 database with optimized configuration for production"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [postgresql, database, sql, relational]
+
+compatibility:
+  specverse: "^3.3.0"
+  postgresql: ">=15.0"
+
+capabilities:
+  provides:
+    - "storage.database"
+    - "storage.database.relational"
+    - "storage.database.sql"
+    - "database.postgresql"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  database: "postgresql"
+  version: "15.x"
+
+dependencies:
+  runtime: []  # Database runs separately
+
+  dev:
+    - name: "pg"
+      version: "^8.11.0"
+      description: "PostgreSQL client for Node.js"
+
+codeTemplates:
+  config:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/postgresql/config-generator.ts"
+    outputPattern: "config/database.{instance}.ts"
+
+  docker:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/postgresql/docker-generator.ts"
+    outputPattern: "docker/postgres.{instance}.yml"
+
+configuration:
+  # Database connection
+  host: "${DB_HOST:-localhost}"
+  port: 5432
+  database: "${DB_NAME}"
+  username: "${DB_USER}"
+  password: "${DB_PASSWORD}"
+
+  # Connection pool
+  pool:
+    min: 2
+    max: 10
+    idleTimeoutMillis: 30000
+    connectionTimeoutMillis: 2000
+
+  # Performance
+  settings:
+    max_connections: 100
+    shared_buffers: "256MB"
+    effective_cache_size: "1GB"
+    work_mem: "16MB"
+    maintenance_work_mem: "128MB"
+
+  # Backup
+  backup:
+    enabled: true
+    schedule: "0 2 * * *"  # Daily at 2am
+    retention: 7  # days

package/libs/instance-factories/storage/redis.yaml

@@ -0,0 +1,79 @@
+name: Redis7
+version: "1.0.0"
+category: storage
+description: "Redis 7 in-memory data store for caching and session management"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [redis, cache, session, key-value]
+
+compatibility:
+  specverse: "^3.3.0"
+  redis: ">=7.0"
+
+capabilities:
+  provides:
+    - "storage.cache"
+    - "storage.cache.memory"
+    - "storage.session"
+    - "database.redis"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  database: "redis"
+  version: "7.x"
+
+dependencies:
+  runtime: []  # Database runs separately
+
+  dev:
+    - name: "redis"
+      version: "^4.6.0"
+      description: "Redis client for Node.js"
+    - name: "@types/redis"
+      version: "^4.0.11"
+
+codeTemplates:
+  config:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/redis/config-generator.ts"
+    outputPattern: "config/cache.{instance}.ts"
+
+  docker:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/redis/docker-generator.ts"
+    outputPattern: "docker/redis.{instance}.yml"
+
+configuration:
+  # Connection
+  host: "${REDIS_HOST:-localhost}"
+  port: 6379
+  password: "${REDIS_PASSWORD}"
+  database: 0
+
+  # Connection options
+  options:
+    connectTimeout: 10000
+    commandTimeout: 5000
+    retryStrategy: "exponential"
+    maxRetriesPerRequest: 3
+
+  # Memory management
+  memory:
+    maxMemory: "256mb"
+    evictionPolicy: "allkeys-lru"
+
+  # Persistence
+  persistence:
+    enabled: true
+    strategy: "aof"  # append-only file
+    fsync: "everysec"
+
+  # Backup
+  backup:
+    enabled: true
+    schedule: "0 * * * *"  # Hourly
+    retention: 24  # hours

package/libs/instance-factories/storage/templates/mongodb/config-generator.ts

@@ -0,0 +1,15 @@
+/**
+ * MongoDB Configuration Generator
+ */
+import type { TemplateContext } from '@specverse/engine-realize';
+
+export default function generateMongoDBConfig(context: TemplateContext): string {
+  const { instance } = context;
+  const instanceName = instance?.name || 'mongodb';
+  return `// MongoDB configuration for ${instanceName}
+// TODO: Implement full MongoDB config generator
+export const mongoConfig = {
+  url: process.env.MONGO_URL || 'mongodb://localhost:27017/${instanceName}'
+};
+`;
+}

package/libs/instance-factories/storage/templates/mongodb/docker-generator.ts

@@ -0,0 +1,18 @@
+/**
+ * MongoDB Docker Compose Generator
+ */
+import type { TemplateContext } from '@specverse/engine-realize';
+
+export default function generateMongoDBDocker(context: TemplateContext): string {
+  const { instance } = context;
+  const instanceName = instance?.name || 'mongodb';
+  return `# MongoDB Docker Compose for ${instanceName}
+# TODO: Implement full MongoDB docker generator
+version: '3.8'
+services:
+  ${instanceName}:
+    image: mongo:6
+    ports:
+      - "27017:27017"
+`;
+}