@auto-engineer/server-generator-apollo-emmett 1.36.3 → 1.37.0

package/ketchup-plan.md

@@ -1,12 +1,11 @@
-# Ketchup Plan: Replace fs.remove(serverDir) with selective cleanServerDir
+# Ketchup Plan: Fix Event Resolution Bugs
 
 ## TODO
 
 ## DONE
 
-- [x] Burst 0: Revert partial edit to restore green baseline (already green)
-- [x] Burst 1: cleanServerDir removes src/ when present (05a4870e)
-- [x] Burst 2: cleanServerDir removes scripts/ and dist/ when present (112adfb4)
-- [x] Burst 3: cleanServerDir preserves node_modules/ (d97a199c)
-- [x] Burst 4: cleanServerDir creates serverDir when missing (855c063c)
-- [x] Burst 5: Wire cleanServerDir into full generation path, replacing fs.remove
+- [x] Burst 1: Command slices — Given-step state refs get local event type definitions (261a0d41)
+- [x] Burst 2: findEventSource — check react data target events (9ac929f9)
+- [x] Burst 3: extractMessagesForReact — extract data target events with source 'then' (f7aee89b)
+- [x] Burst 4: Add events.ts.ejs template for react slices + defaultFilesByType entry (d2e5e5b8)
+- [x] Burst 5: formatSpecValue — handle stringified JSON arrays (6cb406c3)

package/package.json

@@ -32,8 +32,8 @@
     "uuid": "^11.0.0",
     "web-streams-polyfill": "^4.1.0",
     "zod": "^3.22.4",
-    "@auto-engineer/narrative": "1.36.3",
-    "@auto-engineer/message-bus": "1.36.3"
+    "@auto-engineer/narrative": "1.37.0",
+    "@auto-engineer/message-bus": "1.37.0"
   },
   "publishConfig": {
     "access": "public"
@@ -44,9 +44,9 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "tsx": "^4.19.2",
-    "@auto-engineer/cli": "1.36.3"
+    "@auto-engineer/cli": "1.37.0"
   },
-  "version": "1.36.3",
+  "version": "1.37.0",
   "scripts": {
     "generate:server": "tsx src/cli/index.ts",
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts && rm -rf dist/src/codegen/templates && mkdir -p dist/src/codegen && cp -r src/codegen/templates dist/src/codegen/templates && cp src/server.ts dist/src && cp -r src/utils dist/src && cp -r src/domain dist/src",

package/src/codegen/extract/messages.specs.ts

@@ -188,3 +188,276 @@ describe('extractMessagesFromSpecs (react slice)', () => {
     ]);
   });
 });
+
+describe('extractMessagesFromSpecs (command slice)', () => {
+  it('should create state-as-event with source then for Given-step state refs', () => {
+    const slice: Slice = {
+      type: 'command',
+      name: 'book barber appointment',
+      server: {
+        description: 'Books a barber appointment',
+        specs: [
+          {
+            type: 'gherkin',
+            feature: 'Book barber appointment',
+            rules: [
+              {
+                name: 'Should book appointment',
+                examples: [
+                  {
+                    name: 'Appointment booked',
+                    steps: [
+                      {
+                        keyword: 'Given',
+                        text: 'CustomerAppointments',
+                        docString: { customerId: 'c1', appointments: [] },
+                      },
+                      {
+                        keyword: 'When',
+                        text: 'BookBarberAppointment',
+                        docString: { customerId: 'c1', barberId: 'b1' },
+                      },
+                      {
+                        keyword: 'Then',
+                        text: 'BarberAppointmentBooked',
+                        docString: { customerId: 'c1', barberId: 'b1' },
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const allMessages: MessageDefinition[] = [
+      {
+        type: 'state',
+        name: 'CustomerAppointments',
+        fields: [
+          { name: 'customerId', type: 'string', required: true },
+          { name: 'appointments', type: 'object[]', required: true },
+        ],
+      },
+      {
+        type: 'command',
+        name: 'BookBarberAppointment',
+        fields: [
+          { name: 'customerId', type: 'string', required: true },
+          { name: 'barberId', type: 'string', required: true },
+        ],
+      },
+      {
+        type: 'event',
+        name: 'BarberAppointmentBooked',
+        fields: [
+          { name: 'customerId', type: 'string', required: true },
+          { name: 'barberId', type: 'string', required: true },
+        ],
+      },
+    ];
+
+    const result = extractMessagesFromSpecs(slice, allMessages);
+
+    expect(result.events).toEqual([
+      {
+        type: 'CustomerAppointments',
+        fields: [
+          { name: 'customerId', tsType: 'string', required: true },
+          { name: 'appointments', tsType: 'object[]', required: true },
+        ],
+        source: 'then',
+        sourceSliceName: 'book barber appointment',
+      },
+      {
+        type: 'BarberAppointmentBooked',
+        fields: [
+          { name: 'customerId', tsType: 'string', required: true },
+          { name: 'barberId', tsType: 'string', required: true },
+        ],
+        source: 'then',
+        sourceFlowName: undefined,
+        sourceSliceName: 'book barber appointment',
+      },
+    ]);
+  });
+
+  it('should still extract Given-step event refs with source given', () => {
+    const slice: Slice = {
+      type: 'command',
+      name: 'update order',
+      server: {
+        description: 'Updates an order',
+        specs: [
+          {
+            type: 'gherkin',
+            feature: 'Update order',
+            rules: [
+              {
+                name: 'Should update order',
+                examples: [
+                  {
+                    name: 'Order updated',
+                    steps: [
+                      {
+                        keyword: 'Given',
+                        text: 'OrderPlaced',
+                        docString: { orderId: 'o1' },
+                      },
+                      {
+                        keyword: 'When',
+                        text: 'UpdateOrder',
+                        docString: { orderId: 'o1', status: 'shipped' },
+                      },
+                      {
+                        keyword: 'Then',
+                        text: 'OrderUpdated',
+                        docString: { orderId: 'o1', status: 'shipped' },
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const allMessages: MessageDefinition[] = [
+      {
+        type: 'event',
+        name: 'OrderPlaced',
+        fields: [{ name: 'orderId', type: 'string', required: true }],
+      },
+      {
+        type: 'command',
+        name: 'UpdateOrder',
+        fields: [
+          { name: 'orderId', type: 'string', required: true },
+          { name: 'status', type: 'string', required: true },
+        ],
+      },
+      {
+        type: 'event',
+        name: 'OrderUpdated',
+        fields: [
+          { name: 'orderId', type: 'string', required: true },
+          { name: 'status', type: 'string', required: true },
+        ],
+      },
+    ];
+
+    const result = extractMessagesFromSpecs(slice, allMessages);
+
+    expect(result.events).toEqual([
+      {
+        type: 'OrderPlaced',
+        fields: [{ name: 'orderId', tsType: 'string', required: true }],
+        source: 'given',
+        sourceFlowName: undefined,
+        sourceSliceName: 'update order',
+      },
+      {
+        type: 'OrderUpdated',
+        fields: [
+          { name: 'orderId', tsType: 'string', required: true },
+          { name: 'status', tsType: 'string', required: true },
+        ],
+        source: 'then',
+        sourceFlowName: undefined,
+        sourceSliceName: 'update order',
+      },
+    ]);
+  });
+});
+
+describe('extractMessagesFromSpecs (react slice with data target events)', () => {
+  it('should extract data target events with source then', () => {
+    const slice: Slice = {
+      type: 'react',
+      name: 'notify barber of new booking',
+      server: {
+        description: 'Notifies barber after booking',
+        data: {
+          items: [
+            {
+              target: { type: 'Event', name: 'BarberNotified' },
+              destination: { type: 'stream', pattern: 'barber-${barberId}' },
+            },
+          ],
+        },
+        specs: [
+          {
+            type: 'gherkin',
+            feature: 'Notify barber reaction',
+            rules: [
+              {
+                name: 'Should notify barber',
+                examples: [
+                  {
+                    name: 'Barber notified',
+                    steps: [
+                      {
+                        keyword: 'When',
+                        text: 'AppointmentBooked',
+                        docString: { appointmentId: 'a1', barberId: 'b1' },
+                      },
+                      {
+                        keyword: 'Then',
+                        text: 'NotifyBarber',
+                        docString: { barberId: 'b1' },
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const allMessages: MessageDefinition[] = [
+      {
+        type: 'event',
+        name: 'AppointmentBooked',
+        fields: [
+          { name: 'appointmentId', type: 'string', required: true },
+          { name: 'barberId', type: 'string', required: true },
+        ],
+      },
+      {
+        type: 'event',
+        name: 'BarberNotified',
+        fields: [
+          { name: 'barberId', type: 'string', required: true },
+          { name: 'notifiedAt', type: 'Date', required: true },
+        ],
+      },
+      {
+        type: 'command',
+        name: 'NotifyBarber',
+        fields: [{ name: 'barberId', type: 'string', required: true }],
+      },
+    ];
+
+    const result = extractMessagesFromSpecs(slice, allMessages);
+
+    expect(result.events).toEqual(
+      expect.arrayContaining([
+        {
+          type: 'BarberNotified',
+          fields: [
+            { name: 'barberId', tsType: 'string', required: true },
+            { name: 'notifiedAt', tsType: 'Date', required: true },
+          ],
+          source: 'then',
+          sourceSliceName: 'notify barber of new booking',
+        },
+      ]),
+    );
+  });
+});

package/src/codegen/extract/messages.ts

@@ -73,8 +73,23 @@ function extractMessagesForCommand(slice: Slice, allMessages: MessageDefinition[
   debugCommand('  Extracted %d commands', commands.length);
   debugCommand('  Command schemas: %o', Object.keys(commandSchemasByName));
 
+  const allGivenRefs = gwtSpecs.flatMap((gwt) => gwt.given);
+  const stateAsEvents: Message[] = allGivenRefs
+    .filter((ref) => !allMessages.some((m) => m.type === 'event' && m.name === ref.eventRef))
+    .filter((ref) => allMessages.some((m) => m.type === 'state' && m.name === ref.eventRef))
+    .map((ref) => ({
+      type: ref.eventRef,
+      fields: extractFieldsFromMessage(ref.eventRef, 'state', allMessages),
+      source: 'then' as const,
+      sourceSliceName: slice.name,
+    }));
+  debugCommand('  State-as-events from Given: %d', stateAsEvents.length);
+
   const events: Message[] = gwtSpecs.flatMap((gwt): Message[] => {
-    const givenEvents = extractEventsFromGiven(gwt.given, allMessages, slice.name);
+    const eventOnlyGiven = gwt.given.filter((ref) =>
+      allMessages.some((m) => m.type === 'event' && m.name === ref.eventRef),
+    );
+    const givenEvents = extractEventsFromGiven(eventOnlyGiven, allMessages, slice.name);
 
     const thenEventsOnly = gwt.then.filter((item): item is EventRef => 'eventRef' in item);
     const thenEvents = extractEventsFromThen(thenEventsOnly, allMessages, slice.name);
@@ -85,7 +100,7 @@ function extractMessagesForCommand(slice: Slice, allMessages: MessageDefinition[
 
   const result = {
     commands,
-    events: deduplicateMessages(events),
+    events: deduplicateMessages([...stateAsEvents, ...events]),
     states: [],
     commandSchemasByName,
   };
@@ -198,9 +213,24 @@ function extractMessagesForReact(slice: Slice, allMessages: MessageDefinition[])
   const dataStates = extractStatesFromData(slice, allMessages);
   debugReact('  Extracted %d states from data', dataStates.length);
 
+  const dataTargetEvents: Message[] = [];
+  if (slice.server?.data?.items) {
+    for (const item of slice.server.data.items) {
+      if (item.target.type === 'Event') {
+        dataTargetEvents.push({
+          type: item.target.name,
+          fields: extractFieldsFromMessage(item.target.name, 'event', allMessages),
+          source: 'then' as const,
+          sourceSliceName: slice.name,
+        });
+      }
+    }
+  }
+  debugReact('  Extracted %d data target events', dataTargetEvents.length);
+
   const result = {
     commands,
-    events: deduplicateMessages([...events, ...givenEvents]),
+    events: deduplicateMessages([...events, ...givenEvents, ...dataTargetEvents]),
     states: deduplicateMessages([...dataStates, ...givenStates]),
     commandSchemasByName,
   };

package/src/codegen/findEventSource.specs.ts

@@ -0,0 +1,117 @@
+import type { Narrative } from '@auto-engineer/narrative';
+import { describe, expect, it } from 'vitest';
+import { findEventSource } from './scaffoldFromSchema';
+
+describe('findEventSource', () => {
+  it('should find event in command slice GWT then steps', () => {
+    const flows: Narrative[] = [
+      {
+        name: 'order flow',
+        slices: [
+          {
+            type: 'command',
+            name: 'place order',
+            server: {
+              description: '',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Place order',
+                  rules: [
+                    {
+                      name: 'Should place',
+                      examples: [
+                        {
+                          name: 'Order placed',
+                          steps: [
+                            { keyword: 'When', text: 'PlaceOrder', docString: {} },
+                            { keyword: 'Then', text: 'OrderPlaced', docString: {} },
+                          ],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    expect(findEventSource(flows, 'OrderPlaced')).toEqual({
+      flowName: 'order flow',
+      sliceName: 'place order',
+    });
+  });
+
+  it('should find event produced by react data target', () => {
+    const flows: Narrative[] = [
+      {
+        name: 'booking flow',
+        slices: [
+          {
+            type: 'react',
+            name: 'notify barber of new booking',
+            server: {
+              description: 'Notifies barber after booking',
+              data: {
+                items: [
+                  {
+                    target: { type: 'Event', name: 'BarberNotified' },
+                    destination: { type: 'stream', pattern: 'barber-${barberId}' },
+                  },
+                ],
+              },
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Notify barber',
+                  rules: [
+                    {
+                      name: 'Should notify',
+                      examples: [
+                        {
+                          name: 'Barber notified',
+                          steps: [
+                            { keyword: 'When', text: 'AppointmentBooked', docString: {} },
+                            { keyword: 'Then', text: 'NotifyBarber', docString: {} },
+                          ],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    expect(findEventSource(flows, 'BarberNotified')).toEqual({
+      flowName: 'booking flow',
+      sliceName: 'notify barber of new booking',
+    });
+  });
+
+  it('should return null when event is not found anywhere', () => {
+    const flows: Narrative[] = [
+      {
+        name: 'empty flow',
+        slices: [
+          {
+            type: 'query',
+            name: 'some query',
+            server: {
+              description: '',
+              specs: [],
+            },
+          },
+        ],
+      },
+    ];
+
+    expect(findEventSource(flows, 'NonExistentEvent')).toEqual(null);
+  });
+});

package/src/codegen/scaffoldFromSchema.ts

@@ -54,7 +54,7 @@ const defaultFilesByType: Record<string, string[]> = {
     'register.ts.ejs',
   ],
   query: ['projection.ts.ejs', 'state.ts.ejs', 'projection.specs.ts.ejs', 'query.resolver.ts.ejs'],
-  react: ['react.ts.ejs', 'react.specs.ts.ejs', 'register.ts.ejs'],
+  react: ['events.ts.ejs', 'react.ts.ejs', 'react.specs.ts.ejs', 'register.ts.ejs'],
 };
 
 interface EnumDefinition {
@@ -574,17 +574,25 @@ function canSliceProduceEvent(slice: Slice): boolean {
   return ['command', 'react'].includes(slice.type) && 'server' in slice && Boolean(slice.server?.specs);
 }
 
-function findEventSource(flows: Narrative[], eventType: string): { flowName: string; sliceName: string } | null {
+export function findEventSource(flows: Narrative[], eventType: string): { flowName: string; sliceName: string } | null {
   debugSlice('Finding source for event: %s', eventType);
 
   for (const flow of flows) {
     for (const slice of flow.slices) {
-      if (!canSliceProduceEvent(slice)) continue;
-
-      const gwtSpecs = extractGwtSpecsFromSlice(slice);
-      if (hasEventInGwtSpecs(gwtSpecs, eventType)) {
-        debugSlice('  Found event source in flow: %s, slice: %s', flow.name, slice.name);
-        return { flowName: flow.name, sliceName: slice.name };
+      if (canSliceProduceEvent(slice)) {
+        const gwtSpecs = extractGwtSpecsFromSlice(slice);
+        if (hasEventInGwtSpecs(gwtSpecs, eventType)) {
+          debugSlice('  Found event source in flow: %s, slice: %s', flow.name, slice.name);
+          return { flowName: flow.name, sliceName: slice.name };
+        }
+      }
+      if (slice.type === 'react' && slice.server?.data?.items) {
+        for (const item of slice.server.data.items) {
+          if (item.target.type === 'Event' && item.target.name === eventType) {
+            debugSlice('  Found event source in react data target: flow=%s, slice=%s', flow.name, slice.name);
+            return { flowName: flow.name, sliceName: slice.name };
+          }
+        }
       }
     }
   }

package/src/codegen/templates/query/projection.specs.specs.ts

@@ -1967,4 +1967,130 @@ describe('projection.specs.ts.ejs', () => {
     // PaymentReceived lacks 'orderId' field, so should have a warning
     expect(projectionFile?.contents).toContain("WARNING: These events lack field 'orderId': PaymentReceived");
   });
+
+  it('should parse stringified JSON arrays in docString values for array-typed fields', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'appointment-flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'book-appointment',
+              stream: 'appointments-${customerId}',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Book appointment',
+                    rules: [
+                      {
+                        name: 'Should book',
+                        examples: [
+                          {
+                            name: 'Appointment booked',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'BookAppointment',
+                                docString: { customerId: 'c1' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'AppointmentBooked',
+                                docString: { customerId: 'c1' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'query',
+              name: 'view-appointments',
+              stream: 'appointments',
+              client: { specs: [] },
+              server: {
+                description: '',
+                data: {
+                  items: [
+                    {
+                      target: { type: 'State', name: 'CustomerAppointments' },
+                      origin: { type: 'projection', name: 'AppointmentsProjection', idField: 'customerId' },
+                    },
+                  ],
+                },
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'View appointments',
+                    rules: [
+                      {
+                        name: 'Should show appointments',
+                        examples: [
+                          {
+                            name: 'Shows booked appointment',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'AppointmentBooked',
+                                docString: { customerId: 'c1' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'CustomerAppointments',
+                                docString: {
+                                  customerId: 'c1',
+                                  appointments: '[{"appointmentId":"appt_789","service":"haircut"}]',
+                                },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'BookAppointment',
+          fields: [{ name: 'customerId', type: 'string', required: true }],
+        },
+        {
+          type: 'event',
+          name: 'AppointmentBooked',
+          source: 'internal',
+          fields: [{ name: 'customerId', type: 'string', required: true }],
+        },
+        {
+          type: 'state',
+          name: 'CustomerAppointments',
+          fields: [
+            { name: 'customerId', type: 'string', required: true },
+            { name: 'appointments', type: '{ appointmentId: string; service: string }[]', required: true },
+          ],
+        },
+      ],
+    } as SpecsSchema;
+
+    const plans = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const specFile = plans.find((p) => p.outputPath.endsWith('view-appointments/projection.specs.ts'));
+
+    expect(specFile?.contents).toContain("appointmentId: 'appt_789'");
+    expect(specFile?.contents).toContain("service: 'haircut'");
+    expect(specFile?.contents).not.toContain('"[{\\"appointmentId\\"');
+  });
 });

package/src/codegen/templates/query/projection.specs.ts.ejs

@@ -59,6 +59,14 @@ function formatSpecValue(value, tsType) {
             return `{ ${entries.join(', ')} }`;
         }
     }
+    if (typeof value === 'string' && (tsType.includes('[]') || tsType.startsWith('Array<'))) {
+        try {
+            const parsed = JSON.parse(value);
+            if (Array.isArray(parsed)) {
+                return formatSpecValue(parsed, tsType);
+            }
+        } catch { /* not valid JSON — fall through to default */ }
+    }
     return `'${value}'`;
 }