@auto-engineer/server-generator-apollo-emmett 1.154.0 → 1.156.0

package/ketchup-plan.md

@@ -1,10 +1,10 @@
-# Ketchup Plan: G10 — Deduplicate field completeness event assertions for multi-example commands
+# Ketchup Plan: G1 Fix — Coordinate stream UUID with event field UUID
 
 ## TODO
 
-(none)
+- [ ] B1: scaffoldFromSchema compute uuidVars + handle.ts.ejs named constants + context passing + handle.specs.ts snapshots
+- [ ] B2: decide.ts.ejs context parameter + uuid auto-assignments + decide.specs.ts snapshots + coordination test
 
 ## DONE
 
 - [x] B1-B2: Test + fix deduplication of field completeness assertions for multi-example commands (4183cf6d)
-

package/package.json

@@ -32,8 +32,8 @@
     "uuid": "^13.0.0",
     "web-streams-polyfill": "^4.1.0",
     "zod": "^3.22.4",
-    "@auto-engineer/narrative": "1.154.0",
-    "@auto-engineer/message-bus": "1.154.0"
+    "@auto-engineer/narrative": "1.156.0",
+    "@auto-engineer/message-bus": "1.156.0"
   },
   "publishConfig": {
     "access": "public"
@@ -44,9 +44,9 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "tsx": "^4.19.2",
-    "@auto-engineer/cli": "1.154.0"
+    "@auto-engineer/cli": "1.156.0"
   },
-  "version": "1.154.0",
+  "version": "1.156.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/data-sink.specs.ts

@@ -1,5 +1,27 @@
 import { describe, expect, it } from 'vitest';
-import { extractStreamIdFields } from './data-sink';
+import { extractStreamIdFields, normalizeStreamPattern } from './data-sink';
+
+describe('normalizeStreamPattern', () => {
+  it('replaces a single variable with wildcard', () => {
+    expect(normalizeStreamPattern('sessions-${id}')).toBe('sessions-*');
+  });
+
+  it('replaces different variable names with the same wildcard', () => {
+    expect(normalizeStreamPattern('sessions-${sessionId}')).toBe('sessions-*');
+  });
+
+  it('replaces multiple variables', () => {
+    expect(normalizeStreamPattern('user-${userId}-project-${projectId}')).toBe('user-*-project-*');
+  });
+
+  it('returns pattern unchanged when no variables', () => {
+    expect(normalizeStreamPattern('static-stream')).toBe('static-stream');
+  });
+
+  it('returns empty string for empty input', () => {
+    expect(normalizeStreamPattern('')).toBe('');
+  });
+});
 
 describe('extractStreamIdFields', () => {
   it('extracts a single template variable from a stream pattern', () => {

package/src/codegen/extract/data-sink.ts

@@ -62,6 +62,10 @@ function processStreamSink(item: unknown, exampleData: Record<string, unknown>)
   return { streamPattern, streamId };
 }
 
+export function normalizeStreamPattern(pattern: string): string {
+  return pattern.replace(/\$\{[^}]+\}/g, '*');
+}
+
 export function extractStreamIdFields(pattern: string): string[] {
   const fields: string[] = [];
   const regex = /\$\{([^}]+)\}/g;

package/src/codegen/extract/messages.ts

@@ -36,7 +36,7 @@ const EMPTY_EXTRACTED_MESSAGES: ExtractedMessages = {
   commandSchemasByName: {},
 };
 
-function deduplicateMessages<T extends Message>(messages: T[]): T[] {
+export function deduplicateMessages<T extends Message>(messages: T[]): T[] {
   debugDedupe('Deduplicating %d messages', messages.length);
   const uniqueMap = new Map<string, T>();
   for (const message of messages) {

package/src/codegen/extract/sibling-events.specs.ts

@@ -0,0 +1,206 @@
+import type { CommandMoment, ReactMoment, Scene, Step } from '@auto-engineer/narrative';
+import { describe, expect, it } from 'vitest';
+import type { MessageDefinition } from '../types';
+import { findSiblingEventsForStream } from './sibling-events';
+
+function makeCommandMoment(
+  name: string,
+  streamPattern: string,
+  whenCommand: string,
+  thenEvents: Array<{ text: string; exampleData: Record<string, unknown> }>,
+): CommandMoment {
+  const steps: Step[] = [
+    { keyword: 'When', text: whenCommand, docString: {} },
+    ...thenEvents.map(
+      (e): Step => ({
+        keyword: 'Then',
+        text: e.text,
+        docString: e.exampleData,
+      }),
+    ),
+  ];
+  return {
+    type: 'command',
+    name,
+    client: { specs: [] },
+    server: {
+      description: '',
+      data: {
+        items: [
+          {
+            target: { type: 'Event', name: thenEvents[0]?.text ?? '' },
+            destination: { type: 'stream', pattern: streamPattern },
+          },
+        ],
+      },
+      specs: [
+        {
+          type: 'gherkin',
+          feature: name,
+          rules: [
+            {
+              name: `${name} rule`,
+              examples: [{ name: `${name} example`, steps }],
+            },
+          ],
+        },
+      ],
+    },
+  };
+}
+
+describe('findSiblingEventsForStream', () => {
+  it('returns sibling events from moments sharing the same normalized stream', () => {
+    const startSession = makeCommandMoment('Start session', 'sessions-${id}', 'StartSession', [
+      { text: 'SessionStarted', exampleData: { id: 's1', userId: 'u1' } },
+    ]);
+    const addExercise = makeCommandMoment('Add exercise', 'sessions-${sessionId}', 'AddExercise', [
+      { text: 'ExerciseAdded', exampleData: { sessionId: 's1', exercise: 'pushup' } },
+    ]);
+
+    const scenes: Scene[] = [{ name: 'Gym', moments: [startSession, addExercise] }];
+    const messages: MessageDefinition[] = [
+      {
+        type: 'event',
+        name: 'SessionStarted',
+        fields: [
+          { name: 'id', type: 'string', required: true },
+          { name: 'userId', type: 'string', required: true },
+        ],
+      },
+      {
+        type: 'event',
+        name: 'ExerciseAdded',
+        fields: [
+          { name: 'sessionId', type: 'string', required: true },
+          { name: 'exercise', type: 'string', required: true },
+        ],
+      },
+      { type: 'command', name: 'StartSession', fields: [] },
+      { type: 'command', name: 'AddExercise', fields: [] },
+    ];
+
+    const result = findSiblingEventsForStream(addExercise, scenes, messages);
+
+    expect(result.events).toEqual([
+      {
+        type: 'SessionStarted',
+        fields: [
+          { name: 'id', tsType: 'string', required: true },
+          { name: 'userId', tsType: 'string', required: true },
+        ],
+        source: undefined,
+        sourceMomentName: 'Start session',
+      },
+    ]);
+    expect(result.exampleDataByType).toEqual({
+      SessionStarted: { id: 's1', userId: 'u1' },
+    });
+  });
+
+  it('excludes events from the current moment', () => {
+    const startSession = makeCommandMoment('Start session', 'sessions-${id}', 'StartSession', [
+      { text: 'SessionStarted', exampleData: { id: 's1' } },
+    ]);
+
+    const scenes: Scene[] = [{ name: 'Gym', moments: [startSession] }];
+    const messages: MessageDefinition[] = [
+      { type: 'event', name: 'SessionStarted', fields: [{ name: 'id', type: 'string', required: true }] },
+      { type: 'command', name: 'StartSession', fields: [] },
+    ];
+
+    const result = findSiblingEventsForStream(startSession, scenes, messages);
+
+    expect(result.events).toEqual([]);
+    expect(result.exampleDataByType).toEqual({});
+  });
+
+  it('returns empty for moments on different streams', () => {
+    const startSession = makeCommandMoment('Start session', 'sessions-${id}', 'StartSession', [
+      { text: 'SessionStarted', exampleData: { id: 's1' } },
+    ]);
+    const createUser = makeCommandMoment('Create user', 'users-${id}', 'CreateUser', [
+      { text: 'UserCreated', exampleData: { id: 'u1' } },
+    ]);
+
+    const scenes: Scene[] = [{ name: 'Scene1', moments: [startSession, createUser] }];
+    const messages: MessageDefinition[] = [
+      { type: 'event', name: 'SessionStarted', fields: [{ name: 'id', type: 'string', required: true }] },
+      { type: 'event', name: 'UserCreated', fields: [{ name: 'id', type: 'string', required: true }] },
+      { type: 'command', name: 'StartSession', fields: [] },
+      { type: 'command', name: 'CreateUser', fields: [] },
+    ];
+
+    const result = findSiblingEventsForStream(startSession, scenes, messages);
+
+    expect(result.events).toEqual([]);
+    expect(result.exampleDataByType).toEqual({});
+  });
+
+  it('returns empty for moments with no stream', () => {
+    const noStreamMoment: CommandMoment = {
+      type: 'command',
+      name: 'No stream',
+      client: { specs: [] },
+      server: {
+        description: '',
+        specs: [],
+      },
+    };
+
+    const scenes: Scene[] = [{ name: 'Scene', moments: [noStreamMoment] }];
+
+    const result = findSiblingEventsForStream(noStreamMoment, scenes, []);
+
+    expect(result.events).toEqual([]);
+    expect(result.exampleDataByType).toEqual({});
+  });
+
+  it('does not include react moment then-commands as sibling events', () => {
+    const startSession = makeCommandMoment('Start session', 'sessions-${id}', 'StartSession', [
+      { text: 'SessionStarted', exampleData: { id: 's1' } },
+    ]);
+    const reactSteps: Step[] = [
+      { keyword: 'When', text: 'SessionStarted', docString: { id: 's1' } },
+      { keyword: 'Then', text: 'NotifyUser', docString: { userId: 'u1' } },
+    ];
+    const reactMoment: ReactMoment = {
+      type: 'react',
+      name: 'React to session',
+      server: {
+        data: {
+          items: [
+            {
+              target: { type: 'Event', name: 'SessionStarted' },
+              destination: { type: 'stream', pattern: 'sessions-${id}' },
+            },
+          ],
+        },
+        specs: [
+          {
+            type: 'gherkin',
+            feature: 'React',
+            rules: [
+              {
+                name: 'React rule',
+                examples: [{ name: 'React example', steps: reactSteps }],
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const scenes: Scene[] = [{ name: 'Gym', moments: [startSession, reactMoment] }];
+    const messages: MessageDefinition[] = [
+      { type: 'event', name: 'SessionStarted', fields: [{ name: 'id', type: 'string', required: true }] },
+      { type: 'command', name: 'StartSession', fields: [] },
+      { type: 'command', name: 'NotifyUser', fields: [] },
+    ];
+
+    const result = findSiblingEventsForStream(startSession, scenes, messages);
+
+    expect(result.events).toEqual([]);
+    expect(result.exampleDataByType).toEqual({});
+  });
+});

package/src/codegen/extract/sibling-events.ts

@@ -0,0 +1,76 @@
+import type { Moment, Scene } from '@auto-engineer/narrative';
+import type { Message, MessageDefinition } from '../types';
+import { getStreamFromSink, normalizeStreamPattern } from './data-sink';
+import { extractFieldsFromMessage } from './fields';
+import { extractGwtSpecsFromMoment } from './step-converter';
+
+export interface SiblingEventsResult {
+  events: Message[];
+  exampleDataByType: Record<string, Record<string, unknown>>;
+}
+
+function getProducedEvents(
+  moment: Moment,
+  allMessages: MessageDefinition[],
+): Array<{ type: string; exampleData: Record<string, unknown> }> {
+  if (moment.type !== 'command') return [];
+
+  const gwtSpecs = extractGwtSpecsFromMoment(moment);
+  const produced: Array<{ type: string; exampleData: Record<string, unknown> }> = [];
+  const seen = new Set<string>();
+
+  for (const gwt of gwtSpecs) {
+    for (const t of gwt.then) {
+      if ('eventRef' in t && !seen.has(t.eventRef)) {
+        const isEvent = allMessages.some((m) => m.type === 'event' && m.name === t.eventRef);
+        if (isEvent) {
+          seen.add(t.eventRef);
+          produced.push({ type: t.eventRef, exampleData: t.exampleData ?? {} });
+        }
+      }
+    }
+  }
+
+  return produced;
+}
+
+export function findSiblingEventsForStream(
+  currentMoment: Moment,
+  scenes: Scene[],
+  allMessages: MessageDefinition[],
+): SiblingEventsResult {
+  const { streamPattern: currentStream } = getStreamFromSink(currentMoment);
+  if (!currentStream) return { events: [], exampleDataByType: {} };
+
+  const normalizedCurrent = normalizeStreamPattern(currentStream);
+  const events: Message[] = [];
+  const exampleDataByType: Record<string, Record<string, unknown>> = {};
+  const seen = new Set<string>();
+
+  for (const scene of scenes) {
+    for (const moment of scene.moments) {
+      if (moment.name === currentMoment.name) continue;
+
+      const { streamPattern } = getStreamFromSink(moment);
+      if (!streamPattern) continue;
+      if (normalizeStreamPattern(streamPattern) !== normalizedCurrent) continue;
+
+      const produced = getProducedEvents(moment, allMessages);
+      for (const { type, exampleData } of produced) {
+        if (seen.has(type)) continue;
+        seen.add(type);
+
+        const fields = extractFieldsFromMessage(type, 'event', allMessages);
+        events.push({
+          type,
+          fields,
+          source: undefined,
+          sourceMomentName: moment.name,
+        });
+        exampleDataByType[type] = exampleData;
+      }
+    }
+  }
+
+  return { events, exampleDataByType };
+}

package/src/codegen/ketchup-plan.md

@@ -0,0 +1,12 @@
+# Ketchup Plan: Shared-stream sibling event awareness
+
+## TODO
+
+## DONE
+
+- [x] B1: `normalizeStreamPattern()` utility in `data-sink.ts` [depends: none] (d27048c4)
+- [x] B2: `findSiblingEventsForStream()` in new `sibling-events.ts` [depends: B1] (061af979)
+- [x] B3: Wire `allStreamEvents` + `precedingSiblingEvents` into template data + evolve.ts uses it [depends: B1, B2] (3dad6640)
+- [x] B4: decide.specs.ts uses `allStreamEvents` for given-resolution + state-ref fallback [depends: B3] (dbe3629b)
+- [x] B5: decide.ts uses `allStreamEvents` for given-resolution + state-ref fallback [depends: B3] (14dab22e)
+- [x] B6: state.ts sibling field hints + state-ref fix [depends: B3]

package/src/codegen/scaffoldFromSchema.ts

@@ -43,8 +43,10 @@ import {
   sanitizeFieldType,
 } from './extract';
 import { getStreamFromSink } from './extract/data-sink';
+import { deduplicateMessages } from './extract/messages';
 import { buildEventIdFieldMap } from './extract/projection';
 import { buildArgToStateFieldMap } from './extract/query';
+import { findSiblingEventsForStream } from './extract/sibling-events';
 import { normalizeMomentForTemplate } from './extract/slice-normalizer';
 import { extractGwtSpecsFromMoment, type GwtResult } from './extract/step-converter';
 import { buildKeepFieldNames, findDerivedDateInfo, isKeyTraceable, jsConstructorForType } from './templateHelpers';
@@ -643,6 +645,9 @@ async function prepareTemplateData(
   allMessages?: MessageDefinition[],
   integrations?: Model['integrations'],
   scenes?: Scene[],
+  allStreamEvents?: Message[],
+  precedingSiblingEvents?: Message[],
+  siblingExampleData?: Record<string, Record<string, unknown>>,
 ): Promise<Record<string, unknown>> {
   debug('Preparing template data for moment: %s (scene: %s)', slice.name, scene.name);
   debug('  Commands: %d', commands.length);
@@ -671,7 +676,29 @@ async function prepareTemplateData(
   const filteredCommands =
     allowedForMoment.size > 0 ? uniqueCommands.filter((c) => allowedForMoment.has(c.type)) : uniqueCommands;
 
+  const uuidVars: string[] = (() => {
+    if (!streamPattern) return [];
+    const svRegex = /\$\{([^}]+)\}/g;
+    const vars: string[] = [];
+    let match: RegExpExecArray | null;
+    while ((match = svRegex.exec(streamPattern)) !== null) {
+      vars.push(match[1]);
+    }
+    if (vars.length === 0) return [];
+    const allFieldSets = filteredCommands.map((c) => new Set((c.fields ?? []).map((f) => f.name)));
+    return vars.filter((v) => !allFieldSets.some((fs) => fs.has(v)));
+  })();
+
+  const effectiveAllStreamEvents = allStreamEvents ?? events;
+  const effectivePrecedingSiblingEvents = precedingSiblingEvents ?? [];
+  const effectiveSiblingExampleData = siblingExampleData ?? {};
+
   const eventImportGroups = groupEventImports({ currentMomentName: slice.name, currentSceneName: scene.name, events });
+  const allStreamEventImportGroups = groupEventImports({
+    currentMomentName: slice.name,
+    currentSceneName: scene.name,
+    events: effectiveAllStreamEvents,
+  });
   const allEventTypesArray = getAllEventTypes(events);
   const allEventTypes = createEventUnionType(events);
   const selfImportedTypes = new Set(
@@ -750,6 +777,7 @@ async function prepareTemplateData(
     momentName: slice.name,
     slice: normalizedMoment,
     stream: { pattern: streamPattern, id: streamId },
+    uuidVars,
     commands: filteredCommands,
     events,
     states,
@@ -768,6 +796,10 @@ async function prepareTemplateData(
         : undefined,
     integrations,
     eventImportGroups,
+    allStreamEvents: effectiveAllStreamEvents,
+    allStreamEventImportGroups,
+    precedingSiblingEvents: effectivePrecedingSiblingEvents,
+    siblingExampleData: effectiveSiblingExampleData,
     allEventTypes,
     allEventTypesArray,
     localEvents,
@@ -912,6 +944,21 @@ async function generateFilesForMoment(
   annotateEventSources(extracted.events, scenes, scene.name, slice.name, slice.type, sceneNameToDirName);
   annotateCommandSources(extracted.commands, scenes, scene.name, slice.name, slice.type, sceneNameToDirName);
 
+  const { events: siblingEvents, exampleDataByType: siblingExampleData } = findSiblingEventsForStream(
+    slice,
+    scenes,
+    messages,
+  );
+  annotateEventSources(siblingEvents, scenes, scene.name, slice.name, slice.type, sceneNameToDirName);
+  const allStreamEvents = deduplicateMessages([...extracted.events, ...siblingEvents]);
+
+  const currentMomentIndex = scene.moments.findIndex((m) => m.name === slice.name);
+  const laterMomentNames = new Set(scene.moments.slice(currentMomentIndex + 1).map((m) => m.name));
+  const precedingSiblingEvents = siblingEvents.filter(
+    (e) =>
+      !(e.sourceSceneName === scene.name && e.sourceMomentName != null && laterMomentNames.has(e.sourceMomentName)),
+  );
+
   let filteredTemplates = templates;
 
   if (slice.type === 'command' && registeredCommands) {
@@ -958,6 +1005,9 @@ async function generateFilesForMoment(
     messages,
     integrations,
     scenes,
+    allStreamEvents,
+    precedingSiblingEvents,
+    siblingExampleData,
   );
 
   debugMoment('  Generating %d files from templates', filteredTemplates.length);

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

@@ -2793,4 +2793,129 @@ describe('spec.ts.ejs', () => {
       "
     `);
   });
+
+  it('should use preceding sibling events for state-ref Given on shared stream', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      scenes: [
+        {
+          name: 'Gym session',
+          moments: [
+            {
+              type: 'command',
+              name: 'Start session',
+              client: { specs: [] },
+              server: {
+                description: '',
+                data: {
+                  items: [
+                    {
+                      target: { type: 'Event', name: 'SessionStarted' },
+                      destination: { type: 'stream', pattern: 'sessions-${id}' },
+                    },
+                  ],
+                },
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Start session',
+                    rules: [
+                      {
+                        name: 'Start session',
+                        examples: [
+                          {
+                            name: 'Start session example',
+                            steps: [
+                              { keyword: 'When', text: 'StartSession', docString: { userId: 'u1' } },
+                              { keyword: 'Then', text: 'SessionStarted', docString: { id: 's1', userId: 'u1' } },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'command',
+              name: 'Complete session',
+              client: { specs: [] },
+              server: {
+                description: '',
+                data: {
+                  items: [
+                    {
+                      target: { type: 'Event', name: 'SessionCompleted' },
+                      destination: { type: 'stream', pattern: 'sessions-${sessionId}' },
+                    },
+                  ],
+                },
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Complete session',
+                    rules: [
+                      {
+                        name: 'Complete session',
+                        examples: [
+                          {
+                            name: 'Complete session example',
+                            steps: [
+                              { keyword: 'Given', text: 'ActiveSession', docString: { status: 'active' } },
+                              { keyword: 'When', text: 'CompleteSession', docString: { sessionId: 's1' } },
+                              {
+                                keyword: 'Then',
+                                text: 'SessionCompleted',
+                                docString: { sessionId: 's1', completedAt: '2024-01-15' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        { type: 'command', name: 'StartSession', fields: [{ name: 'userId', type: 'string', required: true }] },
+        { type: 'command', name: 'CompleteSession', fields: [{ name: 'sessionId', type: 'string', required: true }] },
+        {
+          type: 'event',
+          name: 'SessionStarted',
+          source: 'internal',
+          fields: [
+            { name: 'id', type: 'string', required: true },
+            { name: 'userId', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'SessionCompleted',
+          source: 'internal',
+          fields: [
+            { name: 'sessionId', type: 'string', required: true },
+            { name: 'completedAt', type: 'string', required: true },
+          ],
+        },
+        { type: 'state', name: 'ActiveSession', fields: [{ name: 'status', type: 'string', required: true }] },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.scenes, spec.messages, undefined, 'src/domain/narratives');
+
+    const completeSpecs = plans.find(
+      (p) => p.outputPath.includes('complete-session') && p.outputPath.endsWith('decide.specs.ts'),
+    );
+    const contents = completeSpecs?.contents ?? '';
+
+    expect(contents).toContain("import type { SessionStarted } from '../start-session/events';");
+    expect(contents).toContain("type: 'SessionStarted'");
+    expect(contents).toContain("id: 's1'");
+    expect(contents).toContain("userId: 'u1'");
+  });
 });