@specverse/engines 4.1.0

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

@@ -0,0 +1,334 @@
+/**
+ * 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/types';
+import { generateBehaviorBody, generateBehaviorWithHelpers, 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)}
+  ${generateOperationsWithHelpers(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 + helper methods from step conventions.
+ */
+function generateOperationsWithHelpers(service: any): string {
+  const ops = generateOperations(service);
+  // Collect helpers from the operations module-level accumulator
+  if (_collectedHelpers.length > 0) {
+    const helpers = [...new Set(_collectedHelpers)].join('\n');
+    _collectedHelpers.length = 0;
+    return ops + '\n' + helpers;
+  }
+  return ops;
+}
+
+// Module-level accumulator for helper methods generated during operation building
+const _collectedHelpers: string[] = [];
+
+/**
+ * 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
+    };
+
+    const result = generateBehaviorWithHelpers(behavior, opMeta, context);
+    _collectedHelpers.push(...result.helperMethods);
+    return result.body;
+  }
+
+  // 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/services/templates/prisma/step-conventions.ts

@@ -0,0 +1,309 @@
+/**
+ * Step Conventions — data-driven pattern matching for behavior steps.
+ *
+ * Each convention maps a natural language step pattern to generated code.
+ * Patterns are tried in order; first match wins. Unmatched steps get stubs.
+ */
+
+export interface StepConvention {
+  name: string;
+  pattern: RegExp;
+  generateCall: (match: RegExpMatchArray, ctx: StepContext) => string;
+  generateMethod?: (match: RegExpMatchArray, ctx: StepContext) => string;
+}
+
+export interface StepContext {
+  modelName: string;
+  prismaModel: string;
+  serviceName: string;
+  operationName: string;
+  stepNum: number;
+}
+
+function toVar(name: string): string {
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+function toMethod(words: string): string {
+  return words.trim().replace(/\s+(.)/g, (_, c) => c.toUpperCase()).replace(/^\w/, c => c.toLowerCase());
+}
+
+export const STEP_CONVENTIONS: StepConvention[] = [
+  // --- Validation ---
+  {
+    name: 'validate',
+    pattern: /^validate\s+(.+)/i,
+    generateCall: (m, ctx) => `    // Step ${ctx.stepNum}: Validate ${m[1]}
+    const validationResult = this.validate(params, { operation: '${ctx.operationName}' });
+    if (!validationResult.valid) {
+      throw new Error(\`Validation failed: \${validationResult.errors.join(', ')}\`);
+    }`,
+  },
+
+  // --- Check / Guard ---
+  {
+    name: 'check',
+    pattern: /^check\s+(.+)/i,
+    generateCall: (m, ctx) => {
+      const condition = m[1];
+      const methodName = toMethod('check ' + condition);
+      return `    // Step ${ctx.stepNum}: Check ${condition}
+    const checkResult = await this.${methodName}(params);
+    if (!checkResult) {
+      throw new Error('Check failed: ${condition}');
+    }`;
+    },
+    generateMethod: (m, ctx) => {
+      const condition = m[1];
+      const methodName = toMethod('check ' + condition);
+      return `
+  private async ${methodName}(params: any): Promise<boolean> {
+    // TODO: Implement check — ${condition}
+    const ${toVar(ctx.prismaModel)} = await this.prisma.${toVar(ctx.prismaModel)}.findUnique({ where: { id: params.id } });
+    if (!${toVar(ctx.prismaModel)}) return false;
+    return true;
+  }`;
+    },
+  },
+
+  // --- Find / Lookup ---
+  {
+    name: 'find',
+    pattern: /^find\s+(\w+)\s+by\s+(\w+)/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const field = m[2];
+      return `    // Step ${ctx.stepNum}: Find ${model} by ${field}
+    const ${toVar(model)} = await this.prisma.${toVar(model)}.findUnique({ where: { ${field}: params.${field} } });
+    if (!${toVar(model)}) {
+      throw new Error('${model} not found by ${field}');
+    }`;
+    },
+  },
+
+  // --- Create ---
+  {
+    name: 'create',
+    pattern: /^create\s+(\w+)(?:\s+record)?/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      return `    // Step ${ctx.stepNum}: Create ${model}
+    const ${toVar(model)} = await this.prisma.${toVar(model)}.create({ data: params });`;
+    },
+  },
+
+  // --- Update field ---
+  {
+    name: 'update-field',
+    pattern: /^update\s+(\w+)\s+(\w+)\s+to\s+(.+)/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const field = m[2];
+      const value = m[3].trim().replace(/"/g, "'");
+      const isString = /^[a-z]/.test(value) && !value.includes('.');
+      const val = isString ? `'${value}'` : value;
+      return `    // Step ${ctx.stepNum}: Update ${model} ${field} to ${value}
+    await this.prisma.${toVar(model)}.update({
+      where: { id: params.id },
+      data: { ${field}: ${val} },
+    });`;
+    },
+  },
+
+  // --- Generic update ---
+  {
+    name: 'update',
+    pattern: /^update\s+(\w+)(?:\s+(.+))?/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      return `    // Step ${ctx.stepNum}: Update ${model}
+    await this.prisma.${toVar(model)}.update({
+      where: { id: params.id },
+      data: params,
+    });`;
+    },
+  },
+
+  // --- Delete ---
+  {
+    name: 'delete',
+    pattern: /^delete\s+(\w+)/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      return `    // Step ${ctx.stepNum}: Delete ${model}
+    await this.prisma.${toVar(model)}.delete({ where: { id: params.id } });`;
+    },
+  },
+
+  // --- Transition / Evolve ---
+  {
+    name: 'transition',
+    pattern: /^transition\s+(\w+)\s+to\s+(\w+)/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const state = m[2];
+      return `    // Step ${ctx.stepNum}: Transition ${model} to ${state}
+    const current = await this.prisma.${toVar(model)}.findUniqueOrThrow({ where: { id: params.id } });
+    // Lifecycle validation would check valid transition here
+    await this.prisma.${toVar(model)}.update({
+      where: { id: params.id },
+      data: { status: '${state}' },
+    });`;
+    },
+  },
+
+  // --- Set field ---
+  {
+    name: 'set',
+    pattern: /^set\s+(\w+)\s+to\s+(.+)/i,
+    generateCall: (m, ctx) => {
+      const field = m[1];
+      const value = m[2].trim();
+      const isCurrentTime = /current time|now|timestamp/i.test(value);
+      const val = isCurrentTime ? 'new Date()' : `'${value}'`;
+      return `    // Step ${ctx.stepNum}: Set ${field} to ${value}
+    await this.prisma.${toVar(ctx.prismaModel)}.update({
+      where: { id: params.id },
+      data: { ${field}: ${val} },
+    });`;
+    },
+  },
+
+  // --- Increment ---
+  {
+    name: 'increment',
+    pattern: /^increment\s+(\w+)\s+by\s+(\w+)/i,
+    generateCall: (m, ctx) => {
+      const field = m[1];
+      const amount = m[2];
+      const amountVal = /^\d+$/.test(amount) ? amount : `params.${amount}`;
+      return `    // Step ${ctx.stepNum}: Increment ${field} by ${amount}
+    await this.prisma.${toVar(ctx.prismaModel)}.update({
+      where: { id: params.id },
+      data: { ${field}: { increment: ${amountVal} } },
+    });`;
+    },
+  },
+
+  // --- Decrement ---
+  {
+    name: 'decrement',
+    pattern: /^decrement\s+(\w+)\s+by\s+(\w+)/i,
+    generateCall: (m, ctx) => {
+      const field = m[1];
+      const amount = m[2];
+      const amountVal = /^\d+$/.test(amount) ? amount : `params.${amount}`;
+      return `    // Step ${ctx.stepNum}: Decrement ${field} by ${amount}
+    const current${field} = await this.prisma.${toVar(ctx.prismaModel)}.findUniqueOrThrow({ where: { id: params.id } });
+    if ((current${field}.${field} || 0) < ${amountVal}) {
+      throw new Error('Cannot decrement ${field} below zero');
+    }
+    await this.prisma.${toVar(ctx.prismaModel)}.update({
+      where: { id: params.id },
+      data: { ${field}: { decrement: ${amountVal} } },
+    });`;
+    },
+  },
+
+  // --- Calculate ---
+  {
+    name: 'calculate',
+    pattern: /^calculate\s+(.+)/i,
+    generateCall: (m, ctx) => {
+      const metric = m[1];
+      const methodName = toMethod('calculate ' + metric);
+      return `    // Step ${ctx.stepNum}: Calculate ${metric}
+    const ${toVar(metric.replace(/\s+/g, ''))} = await this.${methodName}(params);`;
+    },
+    generateMethod: (m, ctx) => {
+      const metric = m[1];
+      const methodName = toMethod('calculate ' + metric);
+      return `
+  private async ${methodName}(params: any): Promise<number> {
+    // TODO: Implement calculation — ${metric}
+    return 0;
+  }`;
+    },
+  },
+
+  // --- Send event ---
+  {
+    name: 'send-event',
+    pattern: /^(?:send|emit|publish)\s+(\w+)\s+event/i,
+    generateCall: (m, ctx) => {
+      const event = m[1];
+      return `    // Step ${ctx.stepNum}: Emit ${event} event
+    this.emit('${event}', { ${toVar(ctx.prismaModel)}Id: params.id, operation: '${ctx.operationName}', timestamp: new Date().toISOString() });`;
+    },
+  },
+
+  // --- Send notification ---
+  {
+    name: 'send-notification',
+    pattern: /^send\s+(\w+)\s+notification/i,
+    generateCall: (m, ctx) => {
+      const type = m[1];
+      return `    // Step ${ctx.stepNum}: Send ${type} notification
+    this.emit('${type}Notification', { ${toVar(ctx.prismaModel)}Id: params.id, operation: '${ctx.operationName}' });`;
+    },
+  },
+
+  // --- Call service ---
+  {
+    name: 'call-service',
+    pattern: /^call\s+(\w+)\.(\w+)/i,
+    generateCall: (m, ctx) => {
+      const service = m[1];
+      const method = m[2];
+      return `    // Step ${ctx.stepNum}: Call ${service}.${method}
+    await this.${toVar(service)}.${method}(params);`;
+    },
+  },
+
+  // --- Return ---
+  {
+    name: 'return',
+    pattern: /^return\s+(.+)/i,
+    generateCall: (m, ctx) => {
+      const value = m[1].trim();
+      const isModel = /^(updated|created|the)\s+/i.test(value) || value === ctx.modelName;
+      if (isModel) {
+        return `    // Step ${ctx.stepNum}: Return result
+    return ${toVar(ctx.prismaModel)};`;
+      }
+      return `    // Step ${ctx.stepNum}: Return ${value}
+    return ${value};`;
+    },
+  },
+];
+
+/**
+ * Match a step string against all conventions. Returns the generated call
+ * code and optionally a helper method to add to the class.
+ */
+export function matchStep(
+  step: string,
+  ctx: StepContext
+): { call: string; helperMethod?: string } {
+  for (const convention of STEP_CONVENTIONS) {
+    const match = step.match(convention.pattern);
+    if (match) {
+      return {
+        call: convention.generateCall(match, ctx),
+        helperMethod: convention.generateMethod?.(match, ctx),
+      };
+    }
+  }
+
+  // No match — generate stub method
+  const methodName = toMethod(step);
+  return {
+    call: `    // Step ${ctx.stepNum}: ${step}
+    await this.${methodName}(params);`,
+    helperMethod: `
+  private async ${methodName}(params: any): Promise<void> {
+    // TODO: Implement — ${step}
+    throw new Error('Not implemented: ${methodName}');
+  }`,
+  };
+}

package/libs/instance-factories/services/templates/shared-patterns.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared Convention Pattern Definitions
+ *
+ * The canonical list of step convention patterns. Both the Prisma factory
+ * (code generation) and the Memory factory (runtime interpretation) use
+ * these same patterns. Add new patterns here — both targets pick them up.
+ *
+ * This is the "interface" of the convention system. Each factory provides
+ * the "implementation" (generateCall or execute).
+ */
+
+export interface PatternDefinition {
+  name: string;
+  pattern: RegExp;
+  description: string;
+}
+
+export const CONVENTION_PATTERNS: PatternDefinition[] = [
+  { name: 'validate',         pattern: /^validate\s+(.+)/i,                                    description: 'Validate input data' },
+  { name: 'check-no-existing', pattern: /^check\s+(?:no\s+existing|.*has\s+no\s+existing)\s+(\w+)\s+for\s+(\w+)\s+in\s+(\w+)/i, description: 'Check no duplicate entity exists for a pair' },
+  { name: 'check',            pattern: /^check\s+(.+)/i,                                       description: 'Check a condition' },
+  { name: 'find',             pattern: /^find\s+(\w+)\s+by\s+(\w+)/i,                          description: 'Find entity by field' },
+  { name: 'find-all-for',     pattern: /^find\s+(?:all\s+)?(\w+?)s?\s+(?:for|of|belonging\s+to)\s+(\w+)/i, description: 'Cross-model query via foreign key' },
+  { name: 'count-per',        pattern: /^count\s+(\w+?)s?\s+(?:per|by|for\s+each)\s+(\w+)/i,   description: 'Group-by aggregation count' },
+  { name: 'create',           pattern: /^create\s+(\w+)(?:\s+record)?/i,                       description: 'Create a new entity' },
+  { name: 'update-field',     pattern: /^update\s+(\w+)\s+(\w+)\s+to\s+(.+)/i,                 description: 'Update specific field to value' },
+  { name: 'update',           pattern: /^update\s+(\w+)$/i,                                    description: 'Update entity with params' },
+  { name: 'delete',           pattern: /^delete\s+(\w+)/i,                                     description: 'Delete an entity' },
+  { name: 'transition',       pattern: /^transition\s+(\w+)\s+to\s+(\w+)/i,                    description: 'Lifecycle state transition' },
+  { name: 'set',              pattern: /^set\s+(\w+)\s+to\s+(.+)/i,                            description: 'Set a field value' },
+  { name: 'increment',        pattern: /^increment\s+(\w+)\s+by\s+(\w+)/i,                     description: 'Increment numeric field' },
+  { name: 'decrement',        pattern: /^decrement\s+(\w+)\s+by\s+(\w+)/i,                     description: 'Decrement numeric field' },
+  { name: 'calculate',        pattern: /^calculate\s+(.+)/i,                                   description: 'Calculate metric or aggregation' },
+  { name: 'send-event',       pattern: /^(?:send|emit|publish)\s+(\w+)\s+event/i,              description: 'Publish domain event' },
+  { name: 'send-notification', pattern: /^send\s+(\w+)\s+notification/i,                       description: 'Send notification event' },
+  { name: 'call-service',     pattern: /^call\s+(\w+)\.(\w+)/i,                                description: 'Delegate to another service' },
+  { name: 'return',           pattern: /^return\s+(.+)/i,                                      description: 'Return a value' },
+];