@auto-engineer/server-generator-apollo-emmett 1.144.0 → 1.146.0

package/ketchup-plan.md

@@ -1,10 +1,9 @@
-# Ketchup Plan: Fix Unescaped Quotes in EJS Template String Literals
+# Ketchup Plan: Cross-Scene Given Events in handle.ts
 
 ## TODO
 
-- [x] Burst 1: Add `escapeJsString` utility + unit tests + wire into renderTemplate (7a5544a6)
-- [x] Burst 2: Fix `projection.specs.ts.ejs` interpolation points (d108c530)
-- [x] Burst 3: Fix `decide.specs.ts.ejs` and `decide.ts.ejs` interpolation points (f9b46ada)
-- [x] Burst 4: Fix `react.specs.ts.ejs` interpolation points
-
 ## DONE
+
+- [x] Burst 1: Compute `crossSceneGivens` in template data (d5786a13)
+- [x] Burst 2: Generate cross-scene handler in handle.ts.ejs (f919ab8b)
+- [x] Burst 3: End-to-end verification — all 299 tests pass, existing snapshots unchanged

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.144.0",
-    "@auto-engineer/message-bus": "1.144.0"
+    "@auto-engineer/narrative": "1.146.0",
+    "@auto-engineer/message-bus": "1.146.0"
   },
   "publishConfig": {
     "access": "public"
@@ -44,9 +44,9 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "tsx": "^4.19.2",
-    "@auto-engineer/cli": "1.144.0"
+    "@auto-engineer/cli": "1.146.0"
   },
-  "version": "1.144.0",
+  "version": "1.146.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/buildCrossSceneGivens.specs.ts

@@ -0,0 +1,263 @@
+import type { Scene } from '@auto-engineer/narrative';
+import { describe, expect, it } from 'vitest';
+import { buildCrossSceneGivens } from './scaffoldFromSchema';
+import type { GwtCondition, Message } from './types';
+
+describe('buildCrossSceneGivens', () => {
+  const workoutsScene: Scene = {
+    name: 'Workouts',
+    moments: [
+      {
+        type: 'command',
+        name: 'Create workout',
+        stream: 'workout-${workoutId}',
+        client: { specs: [] },
+        server: {
+          description: '',
+          specs: [
+            {
+              type: 'gherkin',
+              feature: 'Create workout',
+              rules: [
+                {
+                  name: 'Should create',
+                  examples: [
+                    {
+                      name: 'Workout created',
+                      steps: [
+                        { keyword: 'When', text: 'CreateWorkout', docString: { workoutId: 'w1' } },
+                        { keyword: 'Then', text: 'WorkoutCreated', docString: { workoutId: 'w1' } },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+          data: {
+            items: [
+              {
+                target: { type: 'Event', name: 'WorkoutCreated' },
+                destination: { type: 'stream', pattern: 'workout-${workoutId}' },
+              },
+            ],
+          },
+        },
+      },
+    ],
+  };
+
+  const progressScene: Scene = {
+    name: 'Progress',
+    moments: [
+      {
+        type: 'command',
+        name: 'Record progress',
+        stream: 'progress-${progressId}',
+        client: { specs: [] },
+        server: {
+          description: '',
+          specs: [
+            {
+              type: 'gherkin',
+              feature: 'Record progress',
+              rules: [
+                {
+                  name: 'Should record',
+                  examples: [
+                    {
+                      name: 'Progress recorded',
+                      steps: [
+                        { keyword: 'Given', text: 'WorkoutCreated', docString: { workoutId: 'w1' } },
+                        {
+                          keyword: 'When',
+                          text: 'RecordProgress',
+                          docString: { workoutId: 'w1', date: '2024-01-01' },
+                        },
+                        {
+                          keyword: 'Then',
+                          text: 'ProgressRecorded',
+                          docString: { workoutId: 'w1', date: '2024-01-01' },
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+          data: {
+            items: [
+              {
+                target: { type: 'Event', name: 'ProgressRecorded' },
+                destination: { type: 'stream', pattern: 'progress-${progressId}' },
+              },
+            ],
+          },
+        },
+      },
+    ],
+  };
+
+  it('detects cross-scene Given with resolved linking fields', () => {
+    const gwtMapping: Record<string, GwtCondition[]> = {
+      RecordProgress: [
+        {
+          given: [{ eventRef: 'WorkoutCreated', exampleData: { workoutId: 'w1' } }],
+          when: { commandRef: 'RecordProgress', exampleData: { workoutId: 'w1', date: '2024-01-01' } },
+          then: [{ eventRef: 'ProgressRecorded', exampleData: { workoutId: 'w1', date: '2024-01-01' } }],
+        },
+      ],
+    };
+
+    const events: Message[] = [
+      {
+        type: 'WorkoutCreated',
+        fields: [{ name: 'workoutId', tsType: 'string', required: true }],
+        sourceSceneName: 'Workouts',
+        sourceMomentName: 'Create workout',
+      },
+      {
+        type: 'ProgressRecorded',
+        fields: [
+          { name: 'workoutId', tsType: 'string', required: true },
+          { name: 'date', tsType: 'string', required: true },
+        ],
+        sourceSceneName: 'Progress',
+        sourceMomentName: 'Record progress',
+      },
+    ];
+
+    const commands: Message[] = [
+      {
+        type: 'RecordProgress',
+        fields: [
+          { name: 'workoutId', tsType: 'string', required: true },
+          { name: 'date', tsType: 'string', required: true },
+        ],
+      },
+    ];
+
+    const result = buildCrossSceneGivens(gwtMapping, events, progressScene, [workoutsScene, progressScene], commands);
+
+    expect(result).toEqual([
+      {
+        sourceStreamPattern: 'workout-${workoutId}',
+        linkingFields: [{ streamVar: 'workoutId', commandField: 'workoutId' }],
+        allVarsResolved: true,
+      },
+    ]);
+  });
+
+  it('returns empty array when no cross-scene Givens exist', () => {
+    const gwtMapping: Record<string, GwtCondition[]> = {
+      CreateWorkout: [
+        {
+          when: { commandRef: 'CreateWorkout', exampleData: { workoutId: 'w1' } },
+          then: [{ eventRef: 'WorkoutCreated', exampleData: { workoutId: 'w1' } }],
+        },
+      ],
+    };
+
+    const events: Message[] = [
+      {
+        type: 'WorkoutCreated',
+        fields: [{ name: 'workoutId', tsType: 'string', required: true }],
+        sourceSceneName: 'Workouts',
+        sourceMomentName: 'Create workout',
+      },
+    ];
+
+    const commands: Message[] = [
+      {
+        type: 'CreateWorkout',
+        fields: [{ name: 'workoutId', tsType: 'string', required: true }],
+      },
+    ];
+
+    const result = buildCrossSceneGivens(gwtMapping, events, workoutsScene, [workoutsScene], commands);
+
+    expect(result).toEqual([]);
+  });
+
+  it('marks unresolved when stream var has no matching command field', () => {
+    const gwtMapping: Record<string, GwtCondition[]> = {
+      RecordProgress: [
+        {
+          given: [{ eventRef: 'WorkoutCreated', exampleData: { workoutId: 'w1' } }],
+          when: { commandRef: 'RecordProgress', exampleData: { date: '2024-01-01' } },
+          then: [{ eventRef: 'ProgressRecorded', exampleData: { date: '2024-01-01' } }],
+        },
+      ],
+    };
+
+    const events: Message[] = [
+      {
+        type: 'WorkoutCreated',
+        fields: [{ name: 'workoutId', tsType: 'string', required: true }],
+        sourceSceneName: 'Workouts',
+        sourceMomentName: 'Create workout',
+      },
+    ];
+
+    const commands: Message[] = [
+      {
+        type: 'RecordProgress',
+        fields: [{ name: 'date', tsType: 'string', required: true }],
+      },
+    ];
+
+    const result = buildCrossSceneGivens(gwtMapping, events, progressScene, [workoutsScene, progressScene], commands);
+
+    expect(result).toEqual([
+      {
+        sourceStreamPattern: 'workout-${workoutId}',
+        linkingFields: [],
+        allVarsResolved: false,
+      },
+    ]);
+  });
+
+  it('deduplicates by source stream pattern', () => {
+    const gwtMapping: Record<string, GwtCondition[]> = {
+      RecordProgress: [
+        {
+          given: [{ eventRef: 'WorkoutCreated', exampleData: { workoutId: 'w1' } }],
+          when: { commandRef: 'RecordProgress', exampleData: { workoutId: 'w1' } },
+          then: [{ eventRef: 'ProgressRecorded', exampleData: { workoutId: 'w1' } }],
+        },
+        {
+          given: [{ eventRef: 'WorkoutCreated', exampleData: { workoutId: 'w2' } }],
+          when: { commandRef: 'RecordProgress', exampleData: { workoutId: 'w2' } },
+          then: [{ eventRef: 'ProgressRecorded', exampleData: { workoutId: 'w2' } }],
+        },
+      ],
+    };
+
+    const events: Message[] = [
+      {
+        type: 'WorkoutCreated',
+        fields: [{ name: 'workoutId', tsType: 'string', required: true }],
+        sourceSceneName: 'Workouts',
+        sourceMomentName: 'Create workout',
+      },
+    ];
+
+    const commands: Message[] = [
+      {
+        type: 'RecordProgress',
+        fields: [{ name: 'workoutId', tsType: 'string', required: true }],
+      },
+    ];
+
+    const result = buildCrossSceneGivens(gwtMapping, events, progressScene, [workoutsScene, progressScene], commands);
+
+    expect(result).toEqual([
+      {
+        sourceStreamPattern: 'workout-${workoutId}',
+        linkingFields: [{ streamVar: 'workoutId', commandField: 'workoutId' }],
+        allVarsResolved: true,
+      },
+    ]);
+  });
+});

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

@@ -60,6 +60,32 @@ describe('groupEventImports', () => {
     ]);
   });
 
+  it('uses sourceSceneDirName for cross-scene imports when set', () => {
+    const events: Message[] = [
+      {
+        type: 'WorkoutCreated',
+        fields: [],
+        source: 'when',
+        sourceSceneName: 'gym workout creation',
+        sourceMomentName: 'create workout',
+        sourceSceneDirName: 'gym-tracker_gym-workout-creation',
+      },
+    ];
+
+    const result = groupEventImports({
+      currentMomentName: 'view workout progress',
+      currentSceneName: 'gym workout completion',
+      events,
+    });
+
+    expect(result).toEqual([
+      {
+        importPath: '../../gym-tracker_gym-workout-creation/create-workout/events',
+        eventTypes: ['WorkoutCreated'],
+      },
+    ]);
+  });
+
   it('handles mixed same-scene and cross-scene events', () => {
     const events: Message[] = [
       {

package/src/codegen/extract/imports.ts

@@ -34,7 +34,7 @@ export function groupEventImports(context: CrossMomentImportContext): ImportGrou
       const isCrossScene = sourceSceneName != null && sourceSceneName !== currentSceneName;
       const sliceSegment = toKebabCase(event.sourceMomentName ?? currentMomentName);
       importPath = isCrossScene
-        ? `../../${toKebabCase(sourceSceneName)}/${sliceSegment}/events`
+        ? `../../${event.sourceSceneDirName ?? toKebabCase(sourceSceneName)}/${sliceSegment}/events`
         : `../${sliceSegment}/events`;
     }
     if (!importGroups.has(importPath)) {

package/src/codegen/scaffoldFromSchema.ts

@@ -42,7 +42,7 @@ import {
   isValidTsIdentifier,
   sanitizeFieldType,
 } from './extract';
-import { getStreamFromSink } from './extract/data-sink';
+import { extractStreamIdFields, getStreamFromSink } from './extract/data-sink';
 import { buildEventIdFieldMap } from './extract/projection';
 import { buildArgToStateFieldMap } from './extract/query';
 import { normalizeMomentForTemplate } from './extract/slice-normalizer';
@@ -709,6 +709,8 @@ async function prepareTemplateData(
   const argToStateFieldMap =
     slice.type === 'query' ? buildArgToStateFieldMap(queryGwtMapping, stateFieldNames, slice.mappings) : undefined;
 
+  const crossSceneGivens = buildCrossSceneGivens(gwtMapping, events, scene, scenes ?? [], filteredCommands);
+
   return {
     sceneName: scene.name,
     momentName: slice.name,
@@ -739,21 +741,77 @@ async function prepareTemplateData(
     eventCommandPairs,
     eventIdFieldMap,
     argToStateFieldMap,
+    crossSceneGivens,
   };
 }
 
+interface CrossSceneGiven {
+  sourceStreamPattern: string;
+  linkingFields: Array<{
+    streamVar: string;
+    commandField: string;
+  }>;
+  allVarsResolved: boolean;
+}
+
+export function buildCrossSceneGivens(
+  gwtMapping: Record<string, GwtCondition[]>,
+  events: Message[],
+  currentScene: Scene,
+  scenes: Scene[],
+  filteredCommands: Message[],
+): CrossSceneGiven[] {
+  const commandFieldNames = new Set(filteredCommands.flatMap((c) => c.fields.map((f) => f.name)));
+  const seenPatterns = new Set<string>();
+  const result: CrossSceneGiven[] = [];
+
+  for (const conditions of Object.values(gwtMapping)) {
+    for (const gwt of conditions) {
+      for (const givenRef of gwt.given ?? []) {
+        if (!('eventRef' in givenRef)) continue;
+
+        const event = events.find((e) => e.type === givenRef.eventRef);
+        if (!event || event.sourceSceneName === currentScene.name) continue;
+
+        const sourceScene = scenes.find((s) => s.name === event.sourceSceneName);
+        const sourceMoment = sourceScene?.moments.find((m) => m.name === event.sourceMomentName);
+        if (!sourceMoment) continue;
+
+        const { streamPattern } = getStreamFromSink(sourceMoment);
+        if (!streamPattern || seenPatterns.has(streamPattern)) continue;
+        seenPatterns.add(streamPattern);
+
+        const streamVars = extractStreamIdFields(streamPattern);
+        const linkingFields = streamVars
+          .filter((v) => commandFieldNames.has(v))
+          .map((v) => ({ streamVar: v, commandField: v }));
+
+        result.push({
+          sourceStreamPattern: streamPattern,
+          linkingFields,
+          allVarsResolved: linkingFields.length === streamVars.length,
+        });
+      }
+    }
+  }
+
+  return result;
+}
+
 function annotateEventSources(
   events: Message[],
   scenes: Scene[],
   fallbackFlowName: string,
   fallbackMomentName: string,
   momentType: string,
+  sceneNameToDirName?: Map<string, string>,
 ): void {
   debug('Annotating event sources for %d events', events.length);
   for (const event of events) {
     const match = findEventSource(scenes, event.type);
     event.sourceSceneName = match?.sceneName ?? fallbackFlowName;
     event.sourceMomentName = match?.momentName ?? (momentType === 'react' ? undefined : fallbackMomentName);
+    event.sourceSceneDirName = sceneNameToDirName?.get(event.sourceSceneName);
     debug('  Event %s: scene=%s, slice=%s', event.type, event.sourceSceneName, event.sourceMomentName);
   }
 }
@@ -799,12 +857,14 @@ function annotateCommandSources(
   fallbackFlowName: string,
   fallbackMomentName: string,
   momentType: string,
+  sceneNameToDirName?: Map<string, string>,
 ): void {
   debug('Annotating command sources for %d commands', commands.length);
   for (const command of commands) {
     const match = findCommandSource(scenes, command.type);
     command.sourceSceneName = match?.sceneName ?? fallbackFlowName;
     command.sourceMomentName = match?.momentName ?? (momentType === 'react' ? undefined : fallbackMomentName);
+    command.sourceSceneDirName = sceneNameToDirName?.get(command.sourceSceneName);
     debug('  Command %s: scene=%s, slice=%s', command.type, command.sourceSceneName, command.sourceMomentName);
   }
 }
@@ -835,6 +895,7 @@ async function generateFilesForMoment(
   unionToEnumName: Map<string, string>,
   integrations?: Model['integrations'],
   registeredCommands?: Map<string, { sceneName: string; momentName: string }>,
+  sceneNameToDirName?: Map<string, string>,
 ): Promise<{ plans: FilePlan[]; duplicateCommands: DuplicateCommandInfo[] }> {
   debugMoment('Generating files for moment: %s (type: %s)', slice.name, slice.type);
   debugMoment('  Scene: %s', scene.name);
@@ -867,8 +928,8 @@ async function generateFilesForMoment(
     slice.name,
     extracted.events.map((e) => e.type),
   );
-  annotateEventSources(extracted.events, scenes, scene.name, slice.name, slice.type);
-  annotateCommandSources(extracted.commands, scenes, scene.name, slice.name, slice.type);
+  annotateEventSources(extracted.events, scenes, scene.name, slice.name, slice.type, sceneNameToDirName);
+  annotateCommandSources(extracted.commands, scenes, scene.name, slice.name, slice.type, sceneNameToDirName);
 
   let filteredTemplates = templates;
 
@@ -986,12 +1047,18 @@ export async function generateScaffoldFilePlans(
     }
   }
 
+  const sceneNameToDirName = new Map<string, string>();
   for (const scene of scenes) {
-    debugScene('Processing scene: %s', scene.name);
     const narrativeName = scene.id ? sceneToNarrative.get(scene.id) : undefined;
-    const sceneDirName = narrativeName
+    const dirName = narrativeName
       ? `${toKebabCase(narrativeName)}_${toKebabCase(scene.name)}`
       : toKebabCase(scene.name);
+    sceneNameToDirName.set(scene.name, dirName);
+  }
+
+  for (const scene of scenes) {
+    debugScene('Processing scene: %s', scene.name);
+    const sceneDirName = sceneNameToDirName.get(scene.name)!;
     const sceneDir = ensureDirPath(baseDir, sceneDirName);
     debugScene('  Scene directory: %s', sceneDir);
     debugScene('  Number of moments: %d', scene.moments.length);
@@ -1014,6 +1081,7 @@ export async function generateScaffoldFilePlans(
           unionToEnumName,
           integrations,
           registeredCommands,
+          sceneNameToDirName,
         );
         debugScene('    Generated %d plans for moment', plans.length);
         allPlans.push(...plans);