@auto-engineer/server-generator-apollo-emmett 1.86.0 → 1.88.0

package/ketchup-plan.md

@@ -1,7 +1,11 @@
-# Ketchup Plan: Slim ReadModel API — add findOne, remove redundant methods
+# Ketchup Plan: Fix generator template bugs found in typical server
 
 ## TODO
 
+- [x] Burst 8: Return array `idField` natively from extraction (d4633c71)
+- [x] Burst 9: Fix `findOne` fallback with safe value resolution (8d3ee9cd)
+- [x] Burst 10: Derive stable `metadata.now` with narrow trigger
+
 ## DONE
 
 - [x] Burst 1: Slim ReadModel to find + findOne, update EJS template API docs, update all inline snapshots

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.86.0",
-    "@auto-engineer/message-bus": "1.86.0"
+    "@auto-engineer/narrative": "1.88.0",
+    "@auto-engineer/message-bus": "1.88.0"
   },
   "publishConfig": {
     "access": "public"
@@ -44,9 +44,9 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "tsx": "^4.19.2",
-    "@auto-engineer/cli": "1.86.0"
+    "@auto-engineer/cli": "1.88.0"
   },
-  "version": "1.86.0",
+  "version": "1.88.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.ts

@@ -20,7 +20,7 @@ export interface ExtractedMessages {
   events: Message[];
   states: Message[];
   commandSchemasByName: Record<string, Message>;
-  projectionIdField?: string;
+  projectionIdField?: string | string[];
   projectionSingleton?: boolean;
 }
 

package/src/codegen/extract/projection.ts

@@ -2,7 +2,7 @@ import type { Slice } from '@auto-engineer/narrative';
 
 interface ProjectionOrigin {
   type: 'projection';
-  idField?: string;
+  idField?: string | string[];
   name?: string;
   singleton?: boolean;
 }
@@ -40,8 +40,18 @@ function extractProjectionField<K extends keyof ProjectionOrigin>(slice: Slice,
   return undefined;
 }
 
-export function extractProjectionIdField(slice: Slice): string | undefined {
-  return extractProjectionField(slice, 'idField');
+export function extractProjectionIdField(slice: Slice): string | string[] | undefined {
+  if (!('server' in slice)) return undefined;
+  const dataSource = slice.server?.data?.items?.[0];
+  if (!hasOrigin(dataSource)) return undefined;
+
+  const origin = dataSource.origin;
+  if (isProjectionOrigin(origin)) {
+    const { idField } = origin;
+    if (typeof idField === 'string') return idField;
+    if (Array.isArray(idField) && idField.length > 0) return idField;
+  }
+  return undefined;
 }
 
 export function extractProjectionName(slice: Slice): string | undefined {

package/src/codegen/scaffoldFromSchema.ts

@@ -547,7 +547,7 @@ async function prepareTemplateData(
   events: Message[],
   states: Message[],
   commandSchemasByName: Record<string, Message>,
-  projectionIdField: string | undefined,
+  projectionIdField: string | string[] | undefined,
   projectionSingleton: boolean | undefined,
   allMessages?: MessageDefinition[],
   integrations?: Model['integrations'],

package/src/codegen/templates/command/decide.specs.specs.ts

@@ -822,4 +822,310 @@ describe('spec.ts.ejs', () => {
     expect(decideFile?.contents).toContain('Business rules:');
     expect(decideFile?.contents).toContain('Host can only approve pending bookings');
   });
+
+  it('should pin metadata.now when Then event has a derived ISO date not in command fields or Given', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Record flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'Update record',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Update record',
+                    rules: [
+                      {
+                        name: 'Should update personal record',
+                        examples: [
+                          {
+                            name: 'Record updated with derived date',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'UpdateRecord',
+                                docString: { recordId: 'r1', value: 100 },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'RecordUpdated',
+                                docString: { recordId: 'r1', value: 100, date: '2024-01-20' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'UpdateRecord',
+          fields: [
+            { name: 'recordId', type: 'string', required: true },
+            { name: 'value', type: 'number', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'RecordUpdated',
+          source: 'internal',
+          fields: [
+            { name: 'recordId', type: 'string', required: true },
+            { name: 'value', type: 'number', required: true },
+            { name: 'date', type: 'string', required: true },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const specFile = plans.find((p) => p.outputPath.endsWith('specs.ts'));
+
+    expect(specFile?.contents).toContain("metadata: { now: new Date('2024-01-20') }");
+  });
+
+  it('should keep new Date() when all date fields are in command schema', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Schedule flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'Schedule event',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Schedule event',
+                    rules: [
+                      {
+                        name: 'Should schedule',
+                        examples: [
+                          {
+                            name: 'Event scheduled with user-provided date',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'ScheduleEvent',
+                                docString: { eventId: 'e1', scheduledDate: '2024-03-15' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'EventScheduled',
+                                docString: { eventId: 'e1', scheduledDate: '2024-03-15' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'ScheduleEvent',
+          fields: [
+            { name: 'eventId', type: 'string', required: true },
+            { name: 'scheduledDate', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'EventScheduled',
+          source: 'internal',
+          fields: [
+            { name: 'eventId', type: 'string', required: true },
+            { name: 'scheduledDate', type: 'string', required: true },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const specFile = plans.find((p) => p.outputPath.endsWith('specs.ts'));
+
+    expect(specFile?.contents).toContain('metadata: { now: new Date() }');
+    expect(specFile?.contents).not.toContain("new Date('2024-03-15')");
+  });
+
+  it('should keep new Date() when date value also appears in Given events', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Renewal flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'Renew subscription',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Renew subscription',
+                    rules: [
+                      {
+                        name: 'Should renew',
+                        examples: [
+                          {
+                            name: 'Renewal carries forward existing date',
+                            steps: [
+                              {
+                                keyword: 'Given',
+                                text: 'SubscriptionCreated',
+                                docString: { subId: 's1', startDate: '2024-01-20' },
+                              },
+                              {
+                                keyword: 'When',
+                                text: 'RenewSubscription',
+                                docString: { subId: 's1' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'SubscriptionRenewed',
+                                docString: { subId: 's1', startDate: '2024-01-20' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'RenewSubscription',
+          fields: [{ name: 'subId', type: 'string', required: true }],
+        },
+        {
+          type: 'event',
+          name: 'SubscriptionCreated',
+          source: 'internal',
+          fields: [
+            { name: 'subId', type: 'string', required: true },
+            { name: 'startDate', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'SubscriptionRenewed',
+          source: 'internal',
+          fields: [
+            { name: 'subId', type: 'string', required: true },
+            { name: 'startDate', type: 'string', required: true },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const specFile = plans.find((p) => p.outputPath.endsWith('specs.ts'));
+
+    expect(specFile?.contents).toContain('metadata: { now: new Date() }');
+    expect(specFile?.contents).not.toContain("new Date('2024-01-20')");
+  });
+
+  it('should keep new Date() when multiple candidate dates create ambiguity', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Contract flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'Sign contract',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Sign contract',
+                    rules: [
+                      {
+                        name: 'Should sign',
+                        examples: [
+                          {
+                            name: 'Contract signed with two derived dates',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'SignContract',
+                                docString: { contractId: 'c1' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'ContractSigned',
+                                docString: { contractId: 'c1', signedDate: '2024-01-20', expiresOn: '2024-06-30' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'SignContract',
+          fields: [{ name: 'contractId', type: 'string', required: true }],
+        },
+        {
+          type: 'event',
+          name: 'ContractSigned',
+          source: 'internal',
+          fields: [
+            { name: 'contractId', type: 'string', required: true },
+            { name: 'signedDate', type: 'string', required: true },
+            { name: 'expiresOn', type: 'string', required: true },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const specFile = plans.find((p) => p.outputPath.endsWith('specs.ts'));
+
+    expect(specFile?.contents).toContain('metadata: { now: new Date() }');
+    expect(specFile?.contents).not.toContain("new Date('2024-01-20')");
+    expect(specFile?.contents).not.toContain("new Date('2024-06-30')");
+  });
 });

package/src/codegen/templates/command/decide.specs.ts

@@ -96,7 +96,7 @@ describe('decide.ts.ejs', () => {
       *
       * You should:
       * - Validate the command input fields
-      * - Inspect the current domain \`state\` to determine if the command is allowed
+      * - Inspect the current domain \`_state\` to determine if the command is allowed
       * - If invalid, throw one of the following domain errors: \`NotFoundError\`, \`ValidationError\`, or \`IllegalStateError\`
       *   ⚠️ Error constructors: NotFoundError takes { id, type, message? }, while IllegalStateError/ValidationError take string
       * - If valid, return one or more events with the correct structure
@@ -229,7 +229,7 @@ describe('decide.ts.ejs', () => {
       *
       * You should:
       * - Validate the command input fields
-      * - Inspect the current domain \`state\` to determine if the command is allowed
+      * - Inspect the current domain \`_state\` to determine if the command is allowed
       * - If invalid, throw one of the following domain errors: \`NotFoundError\`, \`ValidationError\`, or \`IllegalStateError\`
       *   ⚠️ Error constructors: NotFoundError takes { id, type, message? }, while IllegalStateError/ValidationError take string
       * - If valid, return one or more events with the correct structure
@@ -382,7 +382,7 @@ describe('decide.ts.ejs', () => {
       *
       * You should:
       * - Validate the command input fields
-      * - Inspect the current domain \`state\` to determine if the command is allowed
+      * - Inspect the current domain \`_state\` to determine if the command is allowed
       * - If invalid, throw one of the following domain errors: \`NotFoundError\`, \`ValidationError\`, or \`IllegalStateError\`
       *   ⚠️ Error constructors: NotFoundError takes { id, type, message? }, while IllegalStateError/ValidationError take string
       * - If valid, return one or more events with the correct structure
@@ -579,7 +579,7 @@ describe('decide.ts.ejs', () => {
       *
       * You should:
       * - Validate the command input fields
-      * - Inspect the current domain \`state\` to determine if the command is allowed
+      * - Inspect the current domain \`_state\` to determine if the command is allowed
           * - Use \`products\` (integration result) to enrich or filter the output
       * - If invalid, throw one of the following domain errors: \`NotFoundError\`, \`ValidationError\`, or \`IllegalStateError\`
       *   ⚠️ Error constructors: NotFoundError takes { id, type, message? }, while IllegalStateError/ValidationError take string

package/src/codegen/templates/command/decide.specs.ts.ejs

@@ -53,6 +53,31 @@ for (const [importPath, eventTypes] of testEventsByPath.entries()) {
 }
 
 const uniqueEventTypes = Array.from(new Set(allEvents.map(e => e?.type).filter(Boolean))).sort();
+
+function findDerivedDateValue(eventResults, commandSchema, givenEvents) {
+    const commandFields = new Set(commandSchema?.fields?.map(f => f.name) || []);
+    const givenValues = new Set();
+    for (const g of givenEvents || []) {
+        for (const val of Object.values(g.exampleData || {})) {
+            if (typeof val === 'string') givenValues.add(val);
+        }
+    }
+    const candidates = new Set();
+    for (const e of eventResults) {
+        const data = e.exampleData || {};
+        for (const [key, val] of Object.entries(data)) {
+            if (
+                !commandFields.has(key) &&
+                typeof val === 'string' &&
+                /^\d{4}-\d{2}-\d{2}$/.test(val) &&
+                !givenValues.has(val)
+            ) {
+                candidates.add(val);
+            }
+        }
+    }
+    return candidates.size === 1 ? [...candidates][0] : null;
+}
 _%>
 import { describe, it } from 'vitest';
 import { DeciderSpecification } from '@event-driven-io/emmett';
@@ -97,7 +122,8 @@ describe('<%= ruleDescription %>', () => {
       .when({
         type: '<%= example.commandRef %>',
         data: <%- formatDataObject(example.exampleData, schema) %>,
-        metadata: { now: new Date() },
+<%  const derivedDate = findDerivedDateValue(eventResults, schema, gwt.given); -%>
+        metadata: { now: <%= derivedDate ? `new Date('${derivedDate}')` : 'new Date()' %> },
       })
 <% if (errorResult) { %>
       .thenThrows((err) => err instanceof <%= errorResult.errorType %> && err.message === '<%= errorResult.message || '' %>');

package/src/codegen/templates/command/decide.ts.ejs

@@ -60,7 +60,7 @@ case '<%= command %>': {
 *
 * You should:
 * - Validate the command input fields
-* - Inspect the current domain `state` to determine if the command is allowed
+* - Inspect the current domain `_state` to determine if the command is allowed
 <% if (integrationReturnType) { -%>
     * - Use `<%= camelCase(integrationReturnType) %>` (integration result) to enrich or filter the output
 <% } -%>

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

@@ -1022,7 +1022,7 @@ describe('projection.specs.ts.ejs', () => {
             .then(async (state) => {
               const document = await state.database
                 .collection<UserProject>('UserProjectsProjection')
-                .findOne((doc) => doc.id === 'test-id');
+                .findOne((doc) => doc.userId === 'user_123' && doc.projectId === 'proj_456');
 
               const expected: UserProject = {
                 userId: 'user_123',
@@ -2093,4 +2093,177 @@ describe('projection.specs.ts.ejs', () => {
     expect(specFile?.contents).toContain("service: 'haircut'");
     expect(specFile?.contents).not.toContain('"[{\\"appointmentId\\"');
   });
+
+  it('should resolve idField value from Given/When events when not in Then state data', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'fitness-flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'log-workout',
+              stream: 'workouts-${memberId}',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Log workout',
+                    rules: [
+                      {
+                        name: 'Should log',
+                        examples: [
+                          {
+                            name: 'Logs workout',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'LogWorkout',
+                                docString: { memberId: 'mem_001', caloriesBurned: 250 },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'WorkoutRecorded',
+                                docString: { memberId: 'mem_001', caloriesBurned: 250 },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'query',
+              name: 'view-workout-summary',
+              stream: 'workouts',
+              client: { specs: [] },
+              server: {
+                description: '',
+                data: {
+                  items: [
+                    {
+                      target: { type: 'State', name: 'WorkoutSummary' },
+                      origin: { type: 'projection', name: 'WorkoutSummaryProjection', idField: 'memberId' },
+                    },
+                  ],
+                },
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'View workout summary',
+                    rules: [
+                      {
+                        name: 'Should summarize workouts',
+                        examples: [
+                          {
+                            name: 'Summary after workout recorded',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'WorkoutRecorded',
+                                docString: { memberId: 'mem_001', caloriesBurned: 250 },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'WorkoutSummary',
+                                docString: { totalCalories: 250, totalSessions: 1 },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'LogWorkout',
+          fields: [
+            { name: 'memberId', type: 'string', required: true },
+            { name: 'caloriesBurned', type: 'number', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'WorkoutRecorded',
+          source: 'internal',
+          fields: [
+            { name: 'memberId', type: 'string', required: true },
+            { name: 'caloriesBurned', type: 'number', required: true },
+          ],
+        },
+        {
+          type: 'state',
+          name: 'WorkoutSummary',
+          fields: [
+            { name: 'totalCalories', type: 'number', required: true },
+            { name: 'totalSessions', type: 'number', 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-workout-summary/projection.specs.ts'));
+
+    expect(specFile?.contents).toMatchInlineSnapshot(`
+      "import { describe, it, beforeEach, expect } from 'vitest';
+      import { InMemoryProjectionSpec } from '@event-driven-io/emmett';
+      import { projection } from './projection';
+      import type { WorkoutRecorded } from '../log-workout/events';
+      import { WorkoutSummary } from './state';
+
+      type ProjectionEvent = WorkoutRecorded;
+
+      describe('Should summarize workouts', () => {
+        let given: InMemoryProjectionSpec<ProjectionEvent>;
+
+        beforeEach(() => {
+          given = InMemoryProjectionSpec.for({ projection });
+        });
+
+        it('Summary after workout recorded', () =>
+          given([])
+            .when([
+              {
+                type: 'WorkoutRecorded',
+                data: {
+                  memberId: 'mem_001',
+                  caloriesBurned: 250,
+                },
+                metadata: {
+                  streamName: 'workouts',
+                  streamPosition: 1n,
+                  globalPosition: 1n,
+                },
+              },
+            ])
+            .then(async (state) => {
+              const document = await state.database
+                .collection<WorkoutSummary>('WorkoutSummaryProjection')
+                .findOne((doc) => doc.memberId === 'mem_001');
+
+              const expected: WorkoutSummary = {
+                totalCalories: 250,
+                totalSessions: 1,
+              };
+
+              expect(document).toMatchObject(expected);
+            }));
+      });
+      "
+    `);
+  });
 });