@auto-engineer/server-generator-apollo-emmett 1.123.0 → 1.125.0

package/src/codegen/templates/react/register.specs.ts

@@ -240,12 +240,14 @@ describe('register.ts.ejs (react slice)', () => {
           /**
            * ## IMPLEMENTATION INSTRUCTIONS ##
            *
-           * - Replace the placeholder logic with the real implementation.
-           * - Send one or more commands via: messageBus.send({...})
-           * - If calling eventStore.aggregateStream(), type the evolve callback:
-           *   evolve: (s: Record<string, unknown>, e: { type: string; data: Record<string, unknown> }) => ...
-           * - NEVER hardcode values copied from test assertions.
-           * - Preserve all import paths above — they are generated from the model.
+           * Complete the command send below. Field sources are pre-classified:
+           * - \`event.data.<field>\` → already wired from the triggering event.
+           * - \`<stateVar>.<field>\` → already wired from loaded aggregate state.
+           * - \`undefined, // TODO: source unknown\` → MUST be dynamically derived:
+           *   compute from event.data, loaded state, or runtime logic.
+           *   NEVER hardcode values copied from test assertions.
+           *
+           * Preserve all import paths above — they are generated from the model.
            *
            * CONSTRAINTS:
            * - NEVER use \`as SomeType\` type assertions. Use typed variable declarations.
@@ -254,14 +256,22 @@ describe('register.ts.ejs (react slice)', () => {
            * - When event.data contains nested arrays/objects, iterate them. Do NOT cast to primitive types.
            */
 
-          // await messageBus.send({
-          //   type: 'NotifyHost',
-          //   kind: 'Command',
-          //   data: {
-          //     // Map event fields to command fields here
-          //     // e.g., userId: event.data.userId,
-          //   },
-          // });
+          // Event (BookingRequested) fields: bookingId: string, hostId: string, message: string
+
+          // Command (NotifyHost) fields: hostId: string, notificationType: string, priority: string, channels: string[], message: string, actionRequired: boolean
+
+          await messageBus.send({
+            type: 'NotifyHost',
+            kind: 'Command',
+            data: {
+              hostId: event.data.hostId,
+              notificationType: undefined, // TODO: source unknown
+              priority: undefined, // TODO: source unknown
+              channels: undefined, // TODO: source unknown
+              message: event.data.message,
+              actionRequired: undefined, // TODO: source unknown
+            },
+          });
 
           return;
         }, 'BookingRequested');
@@ -269,4 +279,261 @@ describe('register.ts.ejs (react slice)', () => {
       "
     `);
   });
+
+  it('should scaffold multiple subscribe calls for multi-event reactor', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'fitness flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'earn points',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Earn points',
+                    rules: [
+                      {
+                        name: 'Should earn',
+                        examples: [
+                          {
+                            name: 'Points earned',
+                            steps: [
+                              { keyword: 'When', text: 'EarnPoints', docString: { memberId: 'm1', amount: 10 } },
+                              { keyword: 'Then', text: 'PointsEarned', docString: { memberId: 'm1', amount: 10 } },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'command',
+              name: 'update record',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Update record',
+                    rules: [
+                      {
+                        name: 'Should update',
+                        examples: [
+                          {
+                            name: 'Record updated',
+                            steps: [
+                              { keyword: 'When', text: 'UpdateRecord', docString: { memberId: 'm1' } },
+                              {
+                                keyword: 'Then',
+                                text: 'PersonalRecordUpdated',
+                                docString: { memberId: 'm1', record: 'bench' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'react',
+              name: 'award badges',
+              server: {
+                description: 'Awards badges based on points and records',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Award badges',
+                    rules: [
+                      {
+                        name: 'Should award on points',
+                        examples: [
+                          {
+                            name: 'Badge for points',
+                            steps: [
+                              { keyword: 'When', text: 'PointsEarned', docString: { memberId: 'm1', amount: 100 } },
+                              {
+                                keyword: 'Then',
+                                text: 'AwardBadge',
+                                docString: { memberId: 'm1', badge: 'centurion' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                      {
+                        name: 'Should notify on record',
+                        examples: [
+                          {
+                            name: 'Notification for record',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'PersonalRecordUpdated',
+                                docString: { memberId: 'm1', record: 'bench' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'SendRecordNotification',
+                                docString: { memberId: 'm1', message: 'New record!' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'EarnPoints',
+          fields: [
+            { name: 'memberId', type: 'string', required: true },
+            { name: 'amount', type: 'number', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'PointsEarned',
+          source: 'internal',
+          fields: [
+            { name: 'memberId', type: 'string', required: true },
+            { name: 'amount', type: 'number', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'UpdateRecord',
+          fields: [{ name: 'memberId', type: 'string', required: true }],
+        },
+        {
+          type: 'event',
+          name: 'PersonalRecordUpdated',
+          source: 'internal',
+          fields: [
+            { name: 'memberId', type: 'string', required: true },
+            { name: 'record', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'AwardBadge',
+          fields: [
+            { name: 'memberId', type: 'string', required: true },
+            { name: 'badge', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'SendRecordNotification',
+          fields: [
+            { name: 'memberId', type: 'string', required: true },
+            { name: 'message', type: 'string', required: true },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const registerFile = plans.find((p) => p.outputPath.endsWith('award-badges/register.ts'));
+
+    expect(registerFile?.contents).toMatchInlineSnapshot(`
+      "import { type CommandSender, type EventSubscription, type EventStore } from '@event-driven-io/emmett';
+      import type { PointsEarned } from '../earn-points/events';
+      import type { PersonalRecordUpdated } from '../update-record/events';
+
+      export async function register(messageBus: CommandSender & EventSubscription, eventStore: EventStore) {
+        messageBus.subscribe(async (event: PointsEarned) => {
+          /**
+           * ## IMPLEMENTATION INSTRUCTIONS ##
+           *
+           * Complete the command send below. Field sources are pre-classified:
+           * - \`event.data.<field>\` → already wired from the triggering event.
+           * - \`<stateVar>.<field>\` → already wired from loaded aggregate state.
+           * - \`undefined, // TODO: source unknown\` → MUST be dynamically derived:
+           *   compute from event.data, loaded state, or runtime logic.
+           *   NEVER hardcode values copied from test assertions.
+           *
+           * Preserve all import paths above — they are generated from the model.
+           *
+           * CONSTRAINTS:
+           * - NEVER use \`as SomeType\` type assertions. Use typed variable declarations.
+           * - Only reference fields that exist on the event type (PointsEarned). Check the import above.
+           * - Do NOT modify the messageBus.subscribe() call, function signature, or import statements.
+           * - When event.data contains nested arrays/objects, iterate them. Do NOT cast to primitive types.
+           */
+
+          // Event (PointsEarned) fields: memberId: string, amount: number
+
+          // Command (AwardBadge) fields: memberId: string, badge: string
+
+          await messageBus.send({
+            type: 'AwardBadge',
+            kind: 'Command',
+            data: {
+              memberId: event.data.memberId,
+              badge: undefined, // TODO: source unknown
+            },
+          });
+
+          return;
+        }, 'PointsEarned');
+
+        messageBus.subscribe(async (event: PersonalRecordUpdated) => {
+          /**
+           * ## IMPLEMENTATION INSTRUCTIONS ##
+           *
+           * Complete the command send below. Field sources are pre-classified:
+           * - \`event.data.<field>\` → already wired from the triggering event.
+           * - \`<stateVar>.<field>\` → already wired from loaded aggregate state.
+           * - \`undefined, // TODO: source unknown\` → MUST be dynamically derived:
+           *   compute from event.data, loaded state, or runtime logic.
+           *   NEVER hardcode values copied from test assertions.
+           *
+           * Preserve all import paths above — they are generated from the model.
+           *
+           * CONSTRAINTS:
+           * - NEVER use \`as SomeType\` type assertions. Use typed variable declarations.
+           * - Only reference fields that exist on the event type (PersonalRecordUpdated). Check the import above.
+           * - Do NOT modify the messageBus.subscribe() call, function signature, or import statements.
+           * - When event.data contains nested arrays/objects, iterate them. Do NOT cast to primitive types.
+           */
+
+          // Event (PersonalRecordUpdated) fields: memberId: string, record: string
+
+          // Command (SendRecordNotification) fields: memberId: string, message: string
+
+          await messageBus.send({
+            type: 'SendRecordNotification',
+            kind: 'Command',
+            data: {
+              memberId: event.data.memberId,
+              message: undefined, // TODO: source unknown
+            },
+          });
+
+          return;
+        }, 'PersonalRecordUpdated');
+      }
+      "
+    `);
+  });
 });

package/src/codegen/templates/react/register.ts.ejs

@@ -1,62 +1,114 @@
 <%
-const specs = slice.server?.specs;
-const firstExample = specs?.rules?.flatMap(rule => rule.examples)[0] ?? null;
-const gwt = firstExample ? {
-  given: firstExample.given,
-  when: firstExample.when,
-  then: firstExample.then
-} : null;
-const when = Array.isArray(gwt?.when) ? gwt.when[0] : gwt?.when;
-const then = Array.isArray(gwt?.then) ? gwt.then[0] : gwt?.then;
+if (!eventCommandPairs || eventCommandPairs.length === 0) {
+  throw new Error(`register.ts.ejs: slice "${slice.name}" has no event→command pairs — check specs`);
+}
 
-const eventType = when?.eventRef;
-const commandType = then?.commandRef;
-if (!eventType) throw new Error(
-  `register.ts.ejs: slice "${slice.name}" has no event in .when() — check specs`
-);
-const event = events.find(e => e.type === eventType);
-const isCrossFlow = event?.sourceFlowName && event.sourceFlowName !== flowName;
-const eventImportBase = isCrossFlow
-  ? `../../${toKebabCase(event.sourceFlowName)}/${toKebabCase(event.sourceSliceName)}`
-  : event?.sourceSliceName ? `../${toKebabCase(event.sourceSliceName)}` : '.';
+const importGroups = new Map();
+for (const pair of eventCommandPairs) {
+  const event = events.find(e => e.type === pair.eventType);
+  const isCrossFlow = event?.sourceFlowName && event.sourceFlowName !== flowName;
+  const importBase = isCrossFlow
+    ? `../../${toKebabCase(event.sourceFlowName)}/${toKebabCase(event.sourceSliceName)}`
+    : event?.sourceSliceName ? `../${toKebabCase(event.sourceSliceName)}` : '.';
+  if (!importGroups.has(importBase)) importGroups.set(importBase, []);
+  const typeName = pascalCase(pair.eventType);
+  if (!importGroups.get(importBase).includes(typeName)) {
+    importGroups.get(importBase).push(typeName);
+  }
+}
 %>
 import { type CommandSender, type EventSubscription, type EventStore } from '@event-driven-io/emmett';
-import type { <%= pascalCase(eventType) %> } from '<%= eventImportBase %>/events';
-
+<% for (const [importBase, types] of importGroups) { -%>
+import type { <%= types.join(', ') %> } from '<%= importBase %>/events';
+<% } %>
 export async function register(
 messageBus: CommandSender & EventSubscription,
 eventStore: EventStore
 ) {
+<% for (const pair of eventCommandPairs) {
+  const eventDef = messages.find(m => m.name === pair.eventType);
+  const commandDef = messages.find(m => m.name === pair.commandType && m.type === 'command');
+  const commandFields = (commandDef?.fields || []);
+  const eventFieldSet = new Set((eventDef?.fields || []).map(f => f.name));
+  const stateFieldSources = {};
+-%>
 messageBus.subscribe(
-async (event: <%= pascalCase(eventType) %>) => {
-/**
-* ## IMPLEMENTATION INSTRUCTIONS ##
-*
-* - Replace the placeholder logic with the real implementation.
-* - Send one or more commands via: messageBus.send({...})
-* - If calling eventStore.aggregateStream(), type the evolve callback:
-*   evolve: (s: Record<string, unknown>, e: { type: string; data: Record<string, unknown> }) => ...
-* - NEVER hardcode values copied from test assertions.
-* - Preserve all import paths above — they are generated from the model.
-*
-* CONSTRAINTS:
-* - NEVER use `as SomeType` type assertions. Use typed variable declarations.
-* - Only reference fields that exist on the event type (<%= pascalCase(eventType) %>). Check the import above.
-* - Do NOT modify the messageBus.subscribe() call, function signature, or import statements.
-* - When event.data contains nested arrays/objects, iterate them. Do NOT cast to primitive types.
-*/
+async (event: <%= pascalCase(pair.eventType) %>) => {
+    /**
+    * ## IMPLEMENTATION INSTRUCTIONS ##
+    *
+    * Complete the command send below. Field sources are pre-classified:
+    * - `event.data.<field>` → already wired from the triggering event.
+    * - `<stateVar>.<field>` → already wired from loaded aggregate state.
+    * - `undefined, // TODO: source unknown` → MUST be dynamically derived:
+    *   compute from event.data, loaded state, or runtime logic.
+    *   NEVER hardcode values copied from test assertions.
+    *
+    * Preserve all import paths above — they are generated from the model.
+    *
+    * CONSTRAINTS:
+    * - NEVER use `as SomeType` type assertions. Use typed variable declarations.
+    * - Only reference fields that exist on the event type (<%= pascalCase(pair.eventType) %>). Check the import above.
+    * - Do NOT modify the messageBus.subscribe() call, function signature, or import statements.
+    * - When event.data contains nested arrays/objects, iterate them. Do NOT cast to primitive types.
+    */
+<% if (eventDef?.fields?.length) { %>
+    // Event (<%= pair.eventType %>) fields: <%= eventDef.fields.map(f => f.name + ': ' + (f.tsType || f.type)).join(', ') %>
+<% } -%>
+<% if (commandDef?.fields?.length) { %>
+    // Command (<%= pair.commandType %>) fields: <%= commandDef.fields.map(f => f.name + ': ' + (f.tsType || f.type)).join(', ') %>
+<% } -%>
+<% if (states.length > 0) {
+    for (const state of states) {
+      const linkingField = findPrimitiveLinkingField(state.fields, eventDef?.fields || []);
+      if (linkingField) {
+        const varName = camelCase(state.type);
+        for (const f of state.fields) {
+          if (!stateFieldSources[f.name]) stateFieldSources[f.name] = varName;
+        }
+        const stateUsedByCommand = commandFields.some(f =>
+          !eventFieldSet.has(f.name) && state.fields.some(sf => sf.name === f.name)
+        );
+        const varPrefix = stateUsedByCommand ? '' : '_';
+-%>
+
+    const { state: <%= varPrefix %><%= varName %> } = await eventStore.aggregateStream(
+      `<%= state.type %>-${event.data.<%= linkingField %>}`,
+      {
+        evolve: (currentState: Record<string, unknown>, evt: { type: string; data: Record<string, unknown> }) => ({ ...currentState, ...evt.data }),
+        initialState: (): Record<string, unknown> => ({}),
+      },
+    );
+    // <%= state.type %> fields: <%= state.fields.map(f => f.name).join(', ') %>
 
-// await messageBus.send({
-//   type: '<%= commandType %>',
-//   kind: 'Command',
-//   data: {
-//     // Map event fields to command fields here
-//     // e.g., userId: event.data.userId,
-//   },
-// });
+<%      }
+    }
+  }
+-%>
 
-return;
+    await messageBus.send({
+      type: '<%= pair.commandType %>',
+      kind: 'Command',
+      data: {
+<% for (const field of commandFields) {
+      const fieldName = field.name;
+      if (eventFieldSet.has(fieldName)) {
+-%>
+        <%= fieldName %>: event.data.<%= fieldName %>,
+<%    } else if (stateFieldSources[fieldName]) { -%>
+        <%= fieldName %>: <%= stateFieldSources[fieldName] %>.<%= fieldName %>,
+<%    } else { -%>
+        <%= fieldName %>: undefined, // TODO: source unknown
+<%    }
+    }
+-%>
+      },
+    });
+
+    return;
 },
-'<%= eventType %>'
+'<%= pair.eventType %>'
 );
+
+<% } -%>
 }

package/src/commands/generate-server.specs.ts

@@ -17,6 +17,7 @@ import {
   emitSliceGenerationFailedForDuplicates,
   emitSliceGenerationFailedForFieldIssues,
   saveGenerationState,
+  writeBiomeConfig,
   writeHealthResolver,
   writeModelToDisk,
 } from './generate-server';
@@ -256,6 +257,37 @@ describe('writeHealthResolver', () => {
   });
 });
 
+describe('writeBiomeConfig', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'biome-config-'));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('writes biome.json with decorator support and recommended linting', async () => {
+    await writeBiomeConfig(dir);
+
+    const content = JSON.parse(await readFile(join(dir, 'biome.json'), 'utf8'));
+    expect(content).toEqual({
+      javascript: {
+        parser: {
+          unsafeParameterDecoratorsEnabled: true,
+        },
+      },
+      linter: {
+        enabled: true,
+        rules: {
+          recommended: true,
+        },
+      },
+    });
+  });
+});
+
 describe('emitSliceGenerationFailedForFieldIssues', () => {
   it('emits SliceGenerationFailed for command slice referencing message via gherkin step', () => {
     const fieldIssues = [

package/src/commands/generate-server.ts

@@ -284,6 +284,9 @@ async function writeConfigurationFiles(serverDir: string): Promise<void> {
 
   debugFiles(`Writing vitest config... to ${serverDir}`);
   await writeVitestConfig(serverDir);
+
+  debugFiles(`Writing biome.json... to ${serverDir}`);
+  await writeBiomeConfig(serverDir);
 }
 
 function createServerSuccessEvent(command: GenerateServerCommand, serverDir: string): ServerGeneratedEvent {
@@ -757,4 +760,21 @@ export default defineConfig({
   await writeFile(path.join(dest, 'vitest.config.ts'), vitestConfig, 'utf-8');
 }
 
+export async function writeBiomeConfig(dest: string): Promise<void> {
+  const biomeConfig = {
+    javascript: {
+      parser: {
+        unsafeParameterDecoratorsEnabled: true,
+      },
+    },
+    linter: {
+      enabled: true,
+      rules: {
+        recommended: true,
+      },
+    },
+  };
+  await fs.writeJson(path.join(dest, 'biome.json'), biomeConfig, { spaces: 2 });
+}
+
 export default commandHandler;

package/src/domain/shared/reactorSpecification.ts

@@ -4,7 +4,7 @@ import {
   type CommandSender,
   type ErrorConstructor,
   isErrorConstructor,
-  type MessageProcessor,
+  type MessageHandlerResult,
 } from '@event-driven-io/emmett';
 
 type CommandCheck<CommandType> = (command: CommandType) => boolean;
@@ -22,7 +22,9 @@ interface ReactorSpecificationReturn<Event, Command, Context> {
     event: Event | Event[],
     context?: Context,
   ) => {
-    then: (expectedCommand: Command | Command[] | CommandCheck<Command> | CommandCheck<Command[]>) => Promise<void>;
+    thenSends: (
+      expectedCommand: Command | Command[] | CommandCheck<Command> | CommandCheck<Command[]>,
+    ) => Promise<void>;
     thenNothingHappened: () => Promise<void>;
     thenThrows: <ErrorType extends Error = Error>(...args: Parameters<ThenThrows<ErrorType>>) => Promise<void>;
   };
@@ -60,12 +62,8 @@ function createMockCommandSender<Command>(): MockCommandSender<Command> {
 }
 
 type ReactorLike<Event, Context> =
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  | { handle: (events: Event[], context: Context) => Promise<any> }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  | { eachMessage: (event: Event, context: Context) => Promise<any> }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  | MessageProcessor<any, any, any>;
+  | { handle(events: Event[], context: Context): MessageHandlerResult | Promise<MessageHandlerResult> }
+  | { eachMessage(event: Event, context: Context): MessageHandlerResult | Promise<MessageHandlerResult> };
 
 function reactorSpecificationFor<Event, Command, Context extends { commandSender: CommandSender }>(
   processorOrReactor: ReactorLike<Event, Context> | (() => ReactorLike<Event, Context>),
@@ -124,7 +122,7 @@ function reactorSpecificationFor<Event, Command, Context extends { commandSender
         };
 
         return {
-          then: async (
+          thenSends: async (
             expectedCommand: Command | Command[] | CommandCheck<Command> | CommandCheck<Command[]>,
           ): Promise<void> => {
             try {
@@ -206,7 +204,6 @@ interface CommandWithMetadata {
   metadata?: Record<string, unknown>;
 }
 
-// eslint-disable-next-line complexity
 function assertCommandsMatch<Command>(actual: Command, expected: Command, index?: number): void {
   const actualCopy = { ...actual } as CommandWithMetadata & Record<string, unknown>;
   const expectedCopy = { ...expected } as CommandWithMetadata & Record<string, unknown>;