eva4j 1.0.13 → 1.0.14

package/src/commands/generate-entities.js

@@ -5,11 +5,12 @@ const fs = require('fs-extra');
 const inquirer = require('inquirer');
 const ConfigManager = require('../utils/config-manager');
 const { isEva4jProject } = require('../utils/validator');
-const { toPackagePath, toCamelCase, toKebabCase, getApplicationClassName } = require('../utils/naming');
+const { toPackagePath, toCamelCase, toKebabCase, toPascalCase, getApplicationClassName } = require('../utils/naming');
 const { renderAndWrite } = require('../utils/template-engine');
 const { parseDomainYaml, generateEntityImports, generateValidationImports } = require('../utils/yaml-to-entity');
 const SharedGenerator = require('../generators/shared-generator');
 const ChecksumManager = require('../utils/checksum-manager');
+const { getInstalledBroker, generateSingleKafkaEvent, buildKafkaEventContext } = require('./generate-kafka-event');
 
 // Maximum depth for recursive relationship traversal
 const MAX_DEPTH = 5;
@@ -173,7 +174,7 @@ async function generateEntitiesCommand(moduleName, options = {}) {
 
   try {
     // Parse domain.yaml
-    const { aggregates, allEnums } = await parseDomainYaml(domainYamlPath, packageName, moduleName);
+    const { aggregates, allEnums, endpoints } = await parseDomainYaml(domainYamlPath, packageName, moduleName);
     
     spinner.succeed(chalk.green(`Found ${aggregates.length} aggregate(s) and ${allEnums.length} enum(s)`));
     
@@ -201,6 +202,9 @@ async function generateEntitiesCommand(moduleName, options = {}) {
       await sharedGenerator.generateDomainEvent(sharedBasePath);
     }
 
+    // Detect installed message broker for auto-wiring integration events
+    const broker = hasDomainEventsInModule ? await getInstalledBroker(configManager) : null;
+
     // Generate audit-related shared components if needed
     if (hasAuditableEntities || hasTrackUserEntities) {
       
@@ -439,7 +443,8 @@ async function generateEntitiesCommand(moduleName, options = {}) {
       const repoContext = {
         packageName,
         moduleName,
-        rootEntity
+        rootEntity,
+        findByOps: []
       };
 
       await renderAndWrite(
@@ -465,7 +470,8 @@ async function generateEntitiesCommand(moduleName, options = {}) {
         moduleName,
         aggregateName,
         rootEntity,
-        hasDomainEvents: (aggregate.domainEvents || []).length > 0
+        hasDomainEvents: (aggregate.domainEvents || []).length > 0,
+        findByOps: []
       };
 
       await renderAndWrite(
@@ -503,8 +509,11 @@ async function generateEntitiesCommand(moduleName, options = {}) {
           packageName,
           moduleName,
           aggregateName,
-          domainEvents: aggregateDomainEvents,
-          hasKafkaEvents: aggregateDomainEvents.some(e => e.kafka)
+          domainEvents: aggregateDomainEvents.map(e => ({
+            ...e,
+            integrationEventClassName: `${e.name}IntegrationEvent`
+          })),
+          broker
         };
         await renderAndWrite(
           path.join(__dirname, '..', '..', 'templates', 'aggregate', 'DomainEventHandler.java.ejs'),
@@ -513,6 +522,33 @@ async function generateEntitiesCommand(moduleName, options = {}) {
           writeOptions
         );
         generatedFiles.push({ type: 'Domain Event Handler', name: `${aggregateName}DomainEventHandler`, path: `${moduleName}/application/usecases/${aggregateName}DomainEventHandler.java` });
+
+        // ── Auto-wire broker integration events ────────────────────────────────
+        // When a message broker is installed, generate the complete integration
+        // event layer (XIntegrationEvent record, MessageBroker port method,
+        // KafkaMessageBroker impl method, topic config, KafkaConfig bean) for
+        // every domain event declared in this aggregate.
+        if (broker === 'kafka') {
+          for (const event of aggregateDomainEvents) {
+            const kafkaCtx = buildKafkaEventContext(packageName, moduleName, event);
+            await generateSingleKafkaEvent(projectDir, packagePath, kafkaCtx);
+            generatedFiles.push({
+              type: 'Integration Event',
+              name: kafkaCtx.eventClassName,
+              path: `${moduleName}/application/events/${kafkaCtx.eventClassName}.java`
+            });
+          }
+          generatedFiles.push({
+            type: 'Integration Event',
+            name: `${toPascalCase(moduleName)}KafkaMessageBroker (updated)`,
+            path: `${moduleName}/infrastructure/adapters/kafkaMessageBroker/${toPascalCase(moduleName)}KafkaMessageBroker.java`
+          });
+          generatedFiles.push({
+            type: 'Integration Event',
+            name: 'MessageBroker (updated)',
+            path: `${moduleName}/application/ports/MessageBroker.java`
+          });
+        }
       }
     }
 
@@ -541,15 +577,60 @@ async function generateEntitiesCommand(moduleName, options = {}) {
     // Persist checksums to disk before asking about CRUD
     await checksumManager.save();
 
-    // Ask user if they want to generate CRUD resources
-    const { generateCrud } = await inquirer.prompt([
-      {
-        type: 'confirm',
-        name: 'generateCrud',
-        message: 'Do you want to generate CRUD resources for aggregate roots?',
-        default: true
+    if (endpoints) {
+      // ── endpoints: section declared → skip CRUD prompt, auto-generate ──
+      spinner.start('Generating endpoint-driven resources...');
+
+      for (const aggregate of aggregates) {
+        await generateEndpointsResources(
+          aggregate,
+          endpoints,
+          moduleName,
+          moduleBasePath,
+          packageName,
+          generatedFiles,
+          writeOptions
+        );
       }
-    ]);
+
+      spinner.succeed(chalk.green('Endpoint-driven resources generated! ✨'));
+
+      const epFiles = generatedFiles.filter(f =>
+        f.type.includes('Command') || f.type.includes('Query') ||
+        f.type.includes('Handler') || f.type.includes('DTO') ||
+        f.type.includes('Controller') || f.type.includes('Mapper')
+      );
+      console.log(chalk.blue('\n📄 Generated endpoint files:'));
+      const groupedEp = epFiles.reduce((acc, file) => {
+        if (!acc[file.type]) acc[file.type] = [];
+        acc[file.type].push(file);
+        return acc;
+      }, {});
+      Object.keys(groupedEp).forEach(type => {
+        console.log(chalk.gray(`\n  ${type}:`));
+        groupedEp[type].forEach(file => {
+          console.log(chalk.gray(`    ├── ${file.name}`));
+        });
+      });
+
+      // Collect versions for summary
+      const versionList = endpoints.versions.map(v => v.version).join(', ');
+      const totalOps = endpoints.versions.reduce((sum, v) => sum + v.operations.length, 0);
+      console.log(chalk.blue(`\n✅ Generated ${totalOps} endpoint(s) across version(s): ${versionList}`));
+
+      await checksumManager.save();
+
+    } else {
+      // ── No endpoints section → original interactive CRUD flow ────────
+      // Ask user if they want to generate CRUD resources
+      const { generateCrud } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'generateCrud',
+          message: 'Do you want to generate CRUD resources for aggregate roots?',
+          default: true
+        }
+      ]);
 
     if (generateCrud) {
       // Ask for API version
@@ -641,6 +722,8 @@ async function generateEntitiesCommand(moduleName, options = {}) {
       await checksumManager.save();
     }
 
+    } // end else (no endpoints section)
+
     console.log();
 
   } catch (error) {
@@ -686,6 +769,586 @@ function transformRelsForApp(rels, validatedVoNames) {
   }));
 }
 
+/**
+ * Classify an endpoint operation into a semantic category.
+ * Returns { category, ...metadata } where category is one of:
+ *   'standard'        → matches the 5 CRUD patterns exactly
+ *   'transition'      → matches {MethodPascal}{Aggregate} for an enum transition
+ *   'subEntityAdd'    → matches Add{EntityName} for a OneToMany secondary entity
+ *   'subEntityRemove' → matches Remove{EntityName} for a OneToMany secondary entity
+ *   'findBy'          → matches FindAll{Aggregate}sBy{FieldPascal} for a root field
+ *   'scaffold'        → no semantic pattern matched
+ */
+function classifyUseCase(op, aggregateName, aggregate) {
+  // 1. Standard CRUD
+  const standardMap = {
+    [`Create${aggregateName}`]: 'create',
+    [`Update${aggregateName}`]: 'update',
+    [`Delete${aggregateName}`]: 'delete',
+    [`Get${aggregateName}`]: 'getById',
+    [`FindAll${aggregateName}s`]: 'findAll'
+  };
+  if (standardMap[op.useCase]) {
+    return { category: 'standard', variant: standardMap[op.useCase] };
+  }
+
+  const rootEntity = aggregate.rootEntity;
+  const enums = aggregate.enums || [];
+
+  // 2. Enum transitions — pattern: {MethodPascal}{Aggregate}
+  for (const enumDef of enums) {
+    for (const transition of (enumDef.transitions || [])) {
+      const methodPascal = toPascalCase(transition.method);
+      if (op.useCase === `${methodPascal}${aggregateName}`) {
+        return {
+          category: 'transition',
+          domainMethod: transition.method,
+          enumName: enumDef.name,
+          targetStatus: Array.isArray(transition.to) ? transition.to[0] : transition.to
+        };
+      }
+    }
+  }
+
+  // 3. Sub-entity operations — pattern: Add{Entity} / Remove{Entity} (OneToMany only)
+  const oneToManyRels = (rootEntity.relationships || []).filter(r =>
+    r.type === 'OneToMany' && !r.isInverse
+  );
+  for (const rel of oneToManyRels) {
+    if (op.useCase === `Add${rel.target}`) {
+      const targetEntity = (aggregate.secondaryEntities || []).find(e => e.name === rel.target);
+      const entityFields = targetEntity
+        ? targetEntity.fields.filter(f =>
+            f.name !== 'id' && f.name !== 'createdAt' && f.name !== 'updatedAt' &&
+            f.name !== 'createdBy' && f.name !== 'updatedBy' && !f.readOnly
+          )
+        : [];
+      return {
+        category: 'subEntityAdd',
+        entityName: rel.target,
+        fieldName: rel.fieldName,
+        addMethodName: `add${rel.target}`,
+        entityFields,
+        entityImports: targetEntity ? (targetEntity.imports || []) : []
+      };
+    }
+    if (op.useCase === `Remove${rel.target}`) {
+      return {
+        category: 'subEntityRemove',
+        entityName: rel.target,
+        fieldName: rel.fieldName,
+        removeMethodName: `remove${rel.target}ById`
+      };
+    }
+  }
+
+  // 4. FindBy field — pattern: FindAll{Aggregate}sBy{FieldPascal}
+  for (const field of (rootEntity.fields || [])) {
+    const fieldPascal = toPascalCase(field.name);
+    if (op.useCase === `FindAll${aggregateName}sBy${fieldPascal}`) {
+      return {
+        category: 'findBy',
+        fieldName: field.name,
+        fieldPascal,
+        fieldJavaType: field.javaType,
+        jpaMethodName: `findBy${fieldPascal}`
+      };
+    }
+  }
+
+  return { category: 'scaffold' };
+}
+
+/**
+ * Enrich a single endpoint operation with derived properties for template rendering.
+ * Expects op._classification to be set by classifyUseCase() before this call.
+ */
+function enrichEndpointOperation(op, aggregateName, idType) {
+  const httpAnnotationMap = {
+    GET: 'GetMapping', POST: 'PostMapping',
+    PUT: 'PutMapping', PATCH: 'PatchMapping', DELETE: 'DeleteMapping'
+  };
+  const hasPathVar = Boolean(op.path && op.path.includes('{'));
+  const pathVarMatch = hasPathVar ? op.path.match(/\{([^}]+)\}/) : null;
+  const pathVarName = pathVarMatch ? pathVarMatch[1] : 'id';
+
+  const cl = op._classification || { category: 'scaffold' };
+  const isStandard = cl.category === 'standard';
+  const standardType = isStandard ? cl.variant : null;
+
+  // Infer type from HTTP method when not explicitly declared: GET → query, everything else → command
+  const resolvedType = op.type || (op.method === 'GET' ? 'query' : 'command');
+
+  let returnType = 'void';
+  if (standardType === 'getById') returnType = `${aggregateName}ResponseDto`;
+  else if (standardType === 'findAll') returnType = `PagedResponse<${aggregateName}ResponseDto>`;
+  else if (cl.category === 'findBy') returnType = `PagedResponse<${aggregateName}ResponseDto>`;
+  else if (cl.category === 'scaffold' && resolvedType === 'query') returnType = 'Object';
+
+  let httpStatus = 'HttpStatus.OK';
+  if (standardType === 'create') httpStatus = 'HttpStatus.CREATED';
+  else if (standardType === 'update') httpStatus = 'HttpStatus.NO_CONTENT';
+  else if (cl.category === 'transition') httpStatus = 'HttpStatus.NO_CONTENT';
+  else if (cl.category === 'subEntityAdd') httpStatus = 'HttpStatus.CREATED';
+  else if (cl.category === 'subEntityRemove') httpStatus = 'HttpStatus.NO_CONTENT';
+
+  return {
+    ...op,
+    type: resolvedType,
+    httpAnnotation: httpAnnotationMap[op.method] || 'PostMapping',
+    methodName: toCamelCase(op.useCase),
+    hasPathVar,
+    pathVarName,
+    isStandard,
+    standardType,
+    classifiedType: cl.category,
+    classification: cl,
+    returnType,
+    httpStatus,
+    idType
+  };
+}
+
+/**
+ * Generate endpoint-driven resources (use cases + versioned controllers)
+ * for an aggregate when domain.yaml declares an `endpoints:` section.
+ */
+async function generateEndpointsResources(aggregate, endpoints, moduleName, moduleBasePath, packageName, generatedFiles, writeOptions = {}) {
+  const { name: aggregateName, rootEntity, secondaryEntities, valueObjects = [] } = aggregate;
+  const templatesDir = path.join(__dirname, '..', '..', 'templates', 'crud');
+
+  const idField = rootEntity.fields[0];
+  const idType = idField.javaType;
+
+  const commandFields = rootEntity.fields.filter(f =>
+    f.name !== 'id' && f.name !== 'createdAt' && f.name !== 'updatedAt' &&
+    f.name !== 'createdBy' && f.name !== 'updatedBy' && !f.readOnly
+  );
+
+  const validatedVos = valueObjects.filter(vo =>
+    vo.fields.some(f => f.validationAnnotations && f.validationAnnotations.length > 0)
+  );
+  const validatedVoNames = new Set(validatedVos.map(vo => vo.name));
+
+  const oneToManyRelationships = enrichRelationshipsRecursively(rootEntity, secondaryEntities, 0, new Set());
+  const oneToOneRels = rootEntity.relationships?.filter(r => r.type === 'OneToOne' && !r.isInverse) || [];
+  const oneToOneRelationships = oneToOneRels.map(rel => {
+    const targetEntity = secondaryEntities.find(e => e.name === rel.target);
+    if (!targetEntity) return { targetEntityName: rel.target, fieldName: rel.fieldName, type: rel.type, fields: [] };
+    const targetFields = targetEntity.fields.filter(f =>
+      f.name !== 'id' && f.name !== 'createdAt' && f.name !== 'updatedAt' &&
+      f.name !== 'createdBy' && f.name !== 'updatedBy'
+    );
+    return { targetEntityName: rel.target, fieldName: rel.fieldName, type: rel.type, fields: targetFields, entity: targetEntity };
+  });
+
+  const hasValueObjects = rootEntity.fields.some(f => f.isValueObject);
+  const hasEnums = rootEntity.enums && rootEntity.enums.length > 0;
+  const resourceNameCamel = toCamelCase(aggregateName);
+  const resourceNameKebab = toKebabCase(aggregateName);
+
+  const responseFields = rootEntity.fields.filter(f =>
+    f.name !== 'createdBy' && f.name !== 'updatedBy' && !f.hidden
+  );
+  const responseSecondaryEntities = secondaryEntities.map(entity => ({
+    ...entity,
+    responseFields: entity.fields.filter(f => f.name !== 'createdBy' && f.name !== 'updatedBy' && !f.hidden),
+    nestedRelationships: enrichRelationshipsRecursively(entity, secondaryEntities, 0, new Set()),
+    forwardOneToOneRels: (entity.relationships || [])
+      .filter(r => r.type === 'OneToOne' && !r.isInverse)
+      .map(r => ({ targetEntityName: r.target, fieldName: r.fieldName }))
+  }));
+
+  const commandFieldsApp = transformFieldsForApp(commandFields, validatedVoNames);
+  const oneToOneRelationshipsApp = oneToOneRelationships.map(rel => ({
+    ...rel,
+    fields: transformFieldsForApp(rel.fields || [], validatedVoNames)
+  }));
+  const oneToManyRelationshipsApp = transformRelsForApp(oneToManyRelationships, validatedVoNames);
+
+  const baseContext = {
+    packageName, moduleName, aggregateName, rootEntity, secondaryEntities,
+    responseFields, responseSecondaryEntities, idType,
+    commandFields: commandFieldsApp, oneToManyRelationships, oneToOneRelationships,
+    hasValueObjects, hasEnums, imports: rootEntity.imports,
+    resourceNameCamel, resourceNameKebab
+  };
+
+  // ── Step 1: Validated VO Dtos ────────────────────────────────────────
+  for (const vo of validatedVos) {
+    const voDtoContext = {
+      packageName, moduleName, voName: vo.name, fields: vo.fields,
+      hasEnums: (vo.imports || []).some(i => i.includes('.enums.')),
+      imports: [...(vo.imports || []), ...generateValidationImports(vo.fields)]
+    };
+    await renderAndWrite(
+      path.join(templatesDir, 'CreateValueObjectDto.java.ejs'),
+      path.join(moduleBasePath, 'application', 'dtos', `Create${vo.name}Dto.java`),
+      voDtoContext, writeOptions
+    );
+    generatedFiles.push({ type: 'DTO', name: `Create${vo.name}Dto`, path: `${moduleName}/application/dtos/Create${vo.name}Dto.java` });
+  }
+
+  // ── Step 2: ApplicationMapper ────────────────────────────────────────
+  await renderAndWrite(
+    path.join(templatesDir, 'ApplicationMapper.java.ejs'),
+    path.join(moduleBasePath, 'application', 'mappers', `${aggregateName}ApplicationMapper.java`),
+    { ...baseContext, commandFields: commandFieldsApp, oneToOneRelationships: oneToOneRelationshipsApp, oneToManyRelationships: oneToManyRelationshipsApp, validatedVos },
+    writeOptions
+  );
+  generatedFiles.push({ type: 'Application Mapper', name: `${aggregateName}ApplicationMapper`, path: `${moduleName}/application/mappers/${aggregateName}ApplicationMapper.java` });
+
+  // ── Step 3: ResponseDto ──────────────────────────────────────────────
+  const responseDtoContext = {
+    ...baseContext,
+    allFields: rootEntity.fields.filter(f => f.name !== 'createdBy' && f.name !== 'updatedBy' && !f.hidden),
+    relationships: rootEntity.relationships.filter(r => (r.type === 'OneToMany' || r.type === 'OneToOne') && !r.isInverse)
+  };
+  await renderAndWrite(
+    path.join(templatesDir, 'ResponseDto.java.ejs'),
+    path.join(moduleBasePath, 'application', 'dtos', `${aggregateName}ResponseDto.java`),
+    responseDtoContext, writeOptions
+  );
+  generatedFiles.push({ type: 'DTO', name: `${aggregateName}ResponseDto`, path: `${moduleName}/application/dtos/${aggregateName}ResponseDto.java` });
+
+  // ── Step 4: Secondary entity DTOs ───────────────────────────────────
+  for (const entity of secondaryEntities) {
+    const nestedRelationships = enrichRelationshipsRecursively(entity, secondaryEntities, 0, new Set());
+    const forwardOoO = (entity.relationships || []).filter(r => r.type === 'OneToOne' && !r.isInverse)
+      .map(r => ({ targetEntityName: r.target, fieldName: r.fieldName }));
+
+    await renderAndWrite(
+      path.join(templatesDir, 'SecondaryEntityDto.java.ejs'),
+      path.join(moduleBasePath, 'application', 'dtos', `${entity.name}Dto.java`),
+      { packageName, moduleName, entityName: entity.name,
+        fields: entity.fields.filter(f => f.name !== 'createdBy' && f.name !== 'updatedBy' && !f.hidden),
+        nestedRelationships, hasNestedRelationships: nestedRelationships.length > 0,
+        forwardOneToOneRels: forwardOoO,
+        hasValueObjects: entity.fields.some(f => f.isValueObject),
+        hasEnums: entity.enums && entity.enums.length > 0, imports: entity.imports },
+      writeOptions
+    );
+    generatedFiles.push({ type: 'DTO', name: `${entity.name}Dto`, path: `${moduleName}/application/dtos/${entity.name}Dto.java` });
+
+    const createFields = entity.fields.filter(f =>
+      f.name !== 'id' && f.name !== 'createdAt' && f.name !== 'updatedAt' &&
+      f.name !== 'createdBy' && f.name !== 'updatedBy' && !f.readOnly
+    );
+    const entityNestedRels = enrichRelationshipsRecursively(entity, secondaryEntities, 0, new Set());
+    const createFieldsApp = transformFieldsForApp(createFields, validatedVoNames);
+    const dtoVoDtoImports = validatedVos.filter(vo => createFieldsApp.some(f => f.originalVoType === vo.name))
+      .map(vo => `import ${packageName}.${moduleName}.application.dtos.Create${vo.name}Dto;`);
+    const createDtoImports = [...new Set([
+      ...(entity.imports || []), ...generateValidationImports(createFieldsApp), ...dtoVoDtoImports,
+      ...(createFieldsApp.some(f => f.originalVoType) ? ['import jakarta.validation.Valid;'] : [])
+    ])];
+    const fwdOoO = (entity.relationships || []).filter(r => r.type === 'OneToOne' && !r.isInverse)
+      .map(r => ({ targetEntityName: r.target, fieldName: r.fieldName }));
+
+    await renderAndWrite(
+      path.join(templatesDir, 'CreateItemDto.java.ejs'),
+      path.join(moduleBasePath, 'application', 'dtos', `Create${entity.name}Dto.java`),
+      { packageName, moduleName, entityName: entity.name, fields: createFieldsApp,
+        nestedRelationships: entityNestedRels, hasNestedRelationships: entityNestedRels.length > 0,
+        forwardOneToOneRels: fwdOoO,
+        hasValueObjects: entity.fields.some(f => f.isValueObject),
+        hasEnums: entity.enums && entity.enums.length > 0, imports: createDtoImports },
+      writeOptions
+    );
+    generatedFiles.push({ type: 'DTO', name: `Create${entity.name}Dto`, path: `${moduleName}/application/dtos/Create${entity.name}Dto.java` });
+  }
+
+  // ── Step 5: Generate declared use cases (anti-duplicate across versions) ─
+  const commandVoDtoImports = validatedVos
+    .filter(vo => commandFieldsApp.some(f => f.originalVoType === vo.name))
+    .map(vo => `import ${packageName}.${moduleName}.application.dtos.Create${vo.name}Dto;`);
+  const commandAppImports = [...new Set([
+    ...(rootEntity.imports || []), ...generateValidationImports(commandFieldsApp), ...commandVoDtoImports,
+    ...(commandFieldsApp.some(f => f.originalVoType) ? ['import jakarta.validation.Valid;'] : [])
+  ])];
+
+  // Pre-classify ALL operations (including cross-version duplicates) so that
+  // enrichEndpointOperation() can read op._classification in step 6.
+  for (const version of endpoints.versions) {
+    for (const op of version.operations) {
+      op._classification = classifyUseCase(op, aggregateName, aggregate);
+    }
+  }
+
+  const generatedUseCases = new Set();
+  const findByOps = []; // collect FindBy ops for repository re-generation
+
+  for (const version of endpoints.versions) {
+    for (const op of version.operations) {
+      if (generatedUseCases.has(op.useCase)) continue; // anti-duplicate
+      generatedUseCases.add(op.useCase);
+
+      const cl = op._classification;
+
+      if (cl.category === 'standard') {
+        const isStandard = true;
+        if (cl.variant === 'create') {
+          await renderAndWrite(
+            path.join(templatesDir, 'CreateCommand.java.ejs'),
+            path.join(moduleBasePath, 'application', 'commands', `Create${aggregateName}Command.java`),
+            { ...baseContext, imports: commandAppImports }, writeOptions
+          );
+          generatedFiles.push({ type: 'Command', name: `Create${aggregateName}Command`, path: `${moduleName}/application/commands/Create${aggregateName}Command.java` });
+
+          await renderAndWrite(
+            path.join(templatesDir, 'CreateCommandHandler.java.ejs'),
+            path.join(moduleBasePath, 'application', 'usecases', `Create${aggregateName}CommandHandler.java`),
+            { ...baseContext, commandFields: commandFieldsApp, oneToOneRelationships: oneToOneRelationshipsApp, oneToManyRelationships: oneToManyRelationshipsApp, validatedVos }, writeOptions
+          );
+          generatedFiles.push({ type: 'Handler', name: `Create${aggregateName}CommandHandler`, path: `${moduleName}/application/usecases/Create${aggregateName}CommandHandler.java` });
+
+        } else if (cl.variant === 'update') {
+          await renderAndWrite(
+            path.join(templatesDir, 'UpdateCommand.java.ejs'),
+            path.join(moduleBasePath, 'application', 'commands', `Update${aggregateName}Command.java`),
+            { ...baseContext, imports: commandAppImports }, writeOptions
+          );
+          generatedFiles.push({ type: 'Command', name: `Update${aggregateName}Command`, path: `${moduleName}/application/commands/Update${aggregateName}Command.java` });
+
+          await renderAndWrite(
+            path.join(templatesDir, 'UpdateCommandHandler.java.ejs'),
+            path.join(moduleBasePath, 'application', 'usecases', `Update${aggregateName}CommandHandler.java`),
+            baseContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Handler', name: `Update${aggregateName}CommandHandler`, path: `${moduleName}/application/usecases/Update${aggregateName}CommandHandler.java` });
+
+        } else if (cl.variant === 'delete') {
+          await renderAndWrite(
+            path.join(templatesDir, 'DeleteCommand.java.ejs'),
+            path.join(moduleBasePath, 'application', 'commands', `Delete${aggregateName}Command.java`),
+            baseContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Command', name: `Delete${aggregateName}Command`, path: `${moduleName}/application/commands/Delete${aggregateName}Command.java` });
+
+          await renderAndWrite(
+            path.join(templatesDir, 'DeleteCommandHandler.java.ejs'),
+            path.join(moduleBasePath, 'application', 'usecases', `Delete${aggregateName}CommandHandler.java`),
+            baseContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Handler', name: `Delete${aggregateName}CommandHandler`, path: `${moduleName}/application/usecases/Delete${aggregateName}CommandHandler.java` });
+
+        } else if (cl.variant === 'getById') {
+          await renderAndWrite(
+            path.join(templatesDir, 'GetQuery.java.ejs'),
+            path.join(moduleBasePath, 'application', 'queries', `Get${aggregateName}Query.java`),
+            baseContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Query', name: `Get${aggregateName}Query`, path: `${moduleName}/application/queries/Get${aggregateName}Query.java` });
+
+          await renderAndWrite(
+            path.join(templatesDir, 'GetQueryHandler.java.ejs'),
+            path.join(moduleBasePath, 'application', 'usecases', `Get${aggregateName}QueryHandler.java`),
+            baseContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Handler', name: `Get${aggregateName}QueryHandler`, path: `${moduleName}/application/usecases/Get${aggregateName}QueryHandler.java` });
+
+        } else if (cl.variant === 'findAll') {
+          await renderAndWrite(
+            path.join(templatesDir, 'ListQuery.java.ejs'),
+            path.join(moduleBasePath, 'application', 'queries', `FindAll${aggregateName}sQuery.java`),
+            baseContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Query', name: `FindAll${aggregateName}sQuery`, path: `${moduleName}/application/queries/FindAll${aggregateName}sQuery.java` });
+
+          await renderAndWrite(
+            path.join(templatesDir, 'ListQueryHandler.java.ejs'),
+            path.join(moduleBasePath, 'application', 'usecases', `FindAll${aggregateName}sQueryHandler.java`),
+            baseContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Handler', name: `FindAll${aggregateName}sQueryHandler`, path: `${moduleName}/application/usecases/FindAll${aggregateName}sQueryHandler.java` });
+        }
+
+      } else if (cl.category === 'transition') {
+        // Transition: {MethodPascal}{Aggregate} → findById → entity.{method}() → save
+        const transitionContext = {
+          packageName, moduleName, aggregateName,
+          useCaseName: op.useCase,
+          idType,
+          domainMethod: cl.domainMethod
+        };
+        await renderAndWrite(
+          path.join(templatesDir, 'TransitionCommand.java.ejs'),
+          path.join(moduleBasePath, 'application', 'commands', `${op.useCase}Command.java`),
+          transitionContext, writeOptions
+        );
+        generatedFiles.push({ type: 'Command', name: `${op.useCase}Command`, path: `${moduleName}/application/commands/${op.useCase}Command.java` });
+
+        await renderAndWrite(
+          path.join(templatesDir, 'TransitionCommandHandler.java.ejs'),
+          path.join(moduleBasePath, 'application', 'usecases', `${op.useCase}CommandHandler.java`),
+          transitionContext, writeOptions
+        );
+        generatedFiles.push({ type: 'Handler', name: `${op.useCase}CommandHandler`, path: `${moduleName}/application/usecases/${op.useCase}CommandHandler.java` });
+
+      } else if (cl.category === 'subEntityAdd') {
+        // SubEntityAdd: Add{EntityName} → findById → entity.add{Entity}(...) → save
+        const addContext = {
+          packageName, moduleName, aggregateName,
+          useCaseName: op.useCase,
+          idType,
+          entityName: cl.entityName,
+          entityFields: cl.entityFields,
+          addMethodName: cl.addMethodName,
+          imports: cl.entityImports
+        };
+        await renderAndWrite(
+          path.join(templatesDir, 'SubEntityAddCommand.java.ejs'),
+          path.join(moduleBasePath, 'application', 'commands', `${op.useCase}Command.java`),
+          addContext, writeOptions
+        );
+        generatedFiles.push({ type: 'Command', name: `${op.useCase}Command`, path: `${moduleName}/application/commands/${op.useCase}Command.java` });
+
+        await renderAndWrite(
+          path.join(templatesDir, 'SubEntityAddCommandHandler.java.ejs'),
+          path.join(moduleBasePath, 'application', 'usecases', `${op.useCase}CommandHandler.java`),
+          addContext, writeOptions
+        );
+        generatedFiles.push({ type: 'Handler', name: `${op.useCase}CommandHandler`, path: `${moduleName}/application/usecases/${op.useCase}CommandHandler.java` });
+
+      } else if (cl.category === 'subEntityRemove') {
+        // SubEntityRemove: Remove{EntityName} → findById → entity.remove{Entity}ById(itemId) → save
+        const removeContext = {
+          packageName, moduleName, aggregateName,
+          useCaseName: op.useCase,
+          idType,
+          entityName: cl.entityName,
+          removeMethodName: cl.removeMethodName
+        };
+        await renderAndWrite(
+          path.join(templatesDir, 'SubEntityRemoveCommand.java.ejs'),
+          path.join(moduleBasePath, 'application', 'commands', `${op.useCase}Command.java`),
+          removeContext, writeOptions
+        );
+        generatedFiles.push({ type: 'Command', name: `${op.useCase}Command`, path: `${moduleName}/application/commands/${op.useCase}Command.java` });
+
+        await renderAndWrite(
+          path.join(templatesDir, 'SubEntityRemoveCommandHandler.java.ejs'),
+          path.join(moduleBasePath, 'application', 'usecases', `${op.useCase}CommandHandler.java`),
+          removeContext, writeOptions
+        );
+        generatedFiles.push({ type: 'Handler', name: `${op.useCase}CommandHandler`, path: `${moduleName}/application/usecases/${op.useCase}CommandHandler.java` });
+
+      } else if (cl.category === 'findBy') {
+        // FindBy: FindAll{Aggregate}sBy{Field} → paginated query on a root field
+        findByOps.push(cl); // collected for repository re-generation after the loop
+        const findByContext = {
+          packageName, moduleName, aggregateName,
+          useCaseName: op.useCase,
+          idType,
+          fieldName: cl.fieldName,
+          fieldPascal: cl.fieldPascal,
+          fieldJavaType: cl.fieldJavaType,
+          jpaMethodName: cl.jpaMethodName
+        };
+        await renderAndWrite(
+          path.join(templatesDir, 'FindByQuery.java.ejs'),
+          path.join(moduleBasePath, 'application', 'queries', `${op.useCase}Query.java`),
+          findByContext, writeOptions
+        );
+        generatedFiles.push({ type: 'Query', name: `${op.useCase}Query`, path: `${moduleName}/application/queries/${op.useCase}Query.java` });
+
+        await renderAndWrite(
+          path.join(templatesDir, 'FindByQueryHandler.java.ejs'),
+          path.join(moduleBasePath, 'application', 'usecases', `${op.useCase}QueryHandler.java`),
+          findByContext, writeOptions
+        );
+        generatedFiles.push({ type: 'Handler', name: `${op.useCase}QueryHandler`, path: `${moduleName}/application/usecases/${op.useCase}QueryHandler.java` });
+
+      } else {
+        // Scaffold: no semantic pattern matched → generate stub with TODO
+        const scaffoldContext = { packageName, moduleName, aggregateName, useCaseName: op.useCase };
+        const scaffoldType = op.type || (op.method === 'GET' ? 'query' : 'command');
+        if (scaffoldType === 'command') {
+          await renderAndWrite(
+            path.join(templatesDir, 'ScaffoldCommand.java.ejs'),
+            path.join(moduleBasePath, 'application', 'commands', `${op.useCase}Command.java`),
+            scaffoldContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Command', name: `${op.useCase}Command`, path: `${moduleName}/application/commands/${op.useCase}Command.java` });
+
+          await renderAndWrite(
+            path.join(templatesDir, 'ScaffoldCommandHandler.java.ejs'),
+            path.join(moduleBasePath, 'application', 'usecases', `${op.useCase}CommandHandler.java`),
+            scaffoldContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Handler', name: `${op.useCase}CommandHandler`, path: `${moduleName}/application/usecases/${op.useCase}CommandHandler.java` });
+        } else {
+          await renderAndWrite(
+            path.join(templatesDir, 'ScaffoldQuery.java.ejs'),
+            path.join(moduleBasePath, 'application', 'queries', `${op.useCase}Query.java`),
+            scaffoldContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Query', name: `${op.useCase}Query`, path: `${moduleName}/application/queries/${op.useCase}Query.java` });
+
+          await renderAndWrite(
+            path.join(templatesDir, 'ScaffoldQueryHandler.java.ejs'),
+            path.join(moduleBasePath, 'application', 'usecases', `${op.useCase}QueryHandler.java`),
+            scaffoldContext, writeOptions
+          );
+          generatedFiles.push({ type: 'Handler', name: `${op.useCase}QueryHandler`, path: `${moduleName}/application/usecases/${op.useCase}QueryHandler.java` });
+        }
+      }
+    }
+  }
+
+  // ── Step 5b: Re-generate repository files when FindBy ops are present ────
+  // Checksum protection still applies: manually modified files are skipped.
+  if (findByOps.length > 0) {
+    const aggregateTemplatesDir = path.join(__dirname, '..', '..', 'templates', 'aggregate');
+    const repoContext = { packageName, moduleName, rootEntity, findByOps };
+    const repoImplContext = {
+      packageName, moduleName, aggregateName, rootEntity,
+      hasDomainEvents: (aggregate.domainEvents || []).length > 0,
+      findByOps
+    };
+    await renderAndWrite(
+      path.join(aggregateTemplatesDir, 'AggregateRepository.java.ejs'),
+      path.join(moduleBasePath, 'domain', 'repositories', `${rootEntity.name}Repository.java`),
+      repoContext, writeOptions
+    );
+    await renderAndWrite(
+      path.join(aggregateTemplatesDir, 'JpaRepository.java.ejs'),
+      path.join(moduleBasePath, 'infrastructure', 'database', 'repositories', `${rootEntity.name}JpaRepository.java`),
+      repoContext, writeOptions
+    );
+    await renderAndWrite(
+      path.join(aggregateTemplatesDir, 'AggregateRepositoryImpl.java.ejs'),
+      path.join(moduleBasePath, 'infrastructure', 'database', 'repositories', `${rootEntity.name}RepositoryImpl.java`),
+      repoImplContext, writeOptions
+    );
+  }
+
+  // ── Step 6: Versioned controllers ────────────────────────────────────
+  for (const version of endpoints.versions) {
+    const versionCap = version.version.charAt(0).toUpperCase() + version.version.slice(1);
+    const controllerName = `${aggregateName}${versionCap}Controller`;
+    const enrichedOps = version.operations.map(op => enrichEndpointOperation(op, aggregateName, idType));
+
+    const controllerContext = {
+      ...baseContext,
+      apiVersion: version.version,
+      controllerName,
+      operations: enrichedOps,
+      basePath: endpoints.basePath,
+      commandFields: commandFieldsApp,
+      oneToManyRelationships,
+      oneToOneRelationships
+    };
+
+    await renderAndWrite(
+      path.join(templatesDir, 'EndpointsController.java.ejs'),
+      path.join(moduleBasePath, 'infrastructure', 'rest', 'controllers', resourceNameCamel, version.version, `${controllerName}.java`),
+      controllerContext, writeOptions
+    );
+    generatedFiles.push({ type: 'Controller', name: controllerName, path: `${moduleName}/infrastructure/rest/controllers/${resourceNameCamel}/${version.version}/${controllerName}.java` });
+  }
+}
+
 /**
  * Generate CRUD resources for an aggregate root
  */