@auto-engineer/server-generator-apollo-emmett 1.124.0 → 1.125.1

package/ketchup-plan.md

@@ -1,37 +1,11 @@
-# Ketchup Plan: Fix generator template bugs found in typical server
+# Ketchup Plan: Fix Outstanding Issues from Typical Server Generation
 
 ## TODO
 
 (none)
 
-## DONE (Round 3)
-
-- [x] Burst 30: Fix 12 — Exclude custom GraphQL input types from enum imports in query.resolver.ts.ejs
-- [x] Burst 29: Fix 11 — SKIPPED: requires modifying standalone types.ts (blocked by type-organization rule); output is identical so no behavioral impact
-- [x] Burst 28: Fix 10 — Remove "valid" qualifier from decide.specs.ts.ejs test descriptions
-- [x] Burst 27: Fix 9 — Map custom GraphQL input type args to GraphQLJSON in query.resolver.ts.ejs
-
-- [x] Burst 26: Add fart-model test for query-arg-differs-from-projection case
-- [x] Burst 25: Exclude query arg fields from projection spec expected state (6da49a58)
-
 ## DONE
 
-- [x] Burst 24: Fix handle.ts multi-command stream pattern
-- [x] Burst 23: Fix decide default case + add discriminated union narrowing guidance (a24a654f)
-- [x] Burst 22: Add null-document guidance to projection template (0d1d2007)
-- [x] Burst 21: Add discriminated union guidance to evolve template (7abc038c)
-- [x] Burst 20: Fill missing inline object fields with type defaults (b39bfd1b)
-- [x] Burst 19: Fix formatTsValue to handle inline object types and Array<T> syntax (df459448)
-
-- [x] Burst 18: Filter events from react Then assertions (cb94eb5d)
-- [x] Burst 1: Slim ReadModel to find + findOne, update EJS template API docs, update all inline snapshots
-- [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 (b7bfd7bf)
-- [x] Burst 11: Omit non-command fields from Then assertions + scaffold annotations (c6953364)
-- [x] Burst 12: Implementer system prompt — anti-hardcoding rules for decide functions
-- [x] Burst 13: Fix formatSpecValue and formatTsValueSimple value-type guards (2412e231)
-- [x] Burst 14: Embed implementation instructions in scaffold templates (f211bd90)
-- [x] Burst 15: Add expectEvents typing shim to decide.specs.ts.ejs (681db5a5)
-- [x] Burst 16: Type-annotate aggregateStream callbacks + dynamic error listing + strengthen instructions (8693a4b3)
-- [x] Burst 17: Filter linking field to primitive types only — skip array/object fields in react template linking (d48982d5)
+- [x] Burst 1: Align ReactorLike return type with MessageHandlerResult (3b1217fc)
+- [x] Burst 2: Rename `then` → `thenSends` to eliminate thenable risk (c65fa28d)
+- [x] Burst 3: Prefix unused aggregateStream state var with `_` (04fd4cbb)

package/package.json

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

@@ -1,6 +1,12 @@
 import { parseInlineObjectFields } from '@auto-engineer/narrative';
 import { describe, expect, it } from 'vitest';
-import { findPrimitiveLinkingField, isPrimitiveTsType, isValidTsIdentifier, sanitizeFieldType } from './type-helpers';
+import {
+  createFieldUsesJSON,
+  findPrimitiveLinkingField,
+  isPrimitiveTsType,
+  isValidTsIdentifier,
+  sanitizeFieldType,
+} from './type-helpers';
 
 describe('parseInlineObjectFields', () => {
   it('should parse simple inline object fields', () => {
@@ -165,3 +171,46 @@ describe('findPrimitiveLinkingField', () => {
     expect(findPrimitiveLinkingField([{ name: 'id', type: 'string' }], [{ name: 'id', type: 'string' }])).toBe('id');
   });
 });
+
+describe('createFieldUsesJSON', () => {
+  const stubGraphqlType = (ts: string): string => {
+    if (ts === 'unknown' || ts === 'any' || ts === 'object') return 'GraphQLJSON';
+    if (ts.startsWith('Record<')) return 'GraphQLJSON';
+    if (ts.startsWith('{') || ts.startsWith('Array<{')) return 'GraphQLJSON';
+    return ts;
+  };
+
+  const fieldUsesJSON = createFieldUsesJSON(stubGraphqlType);
+
+  it('returns false for inline object array without JSON subfields', () => {
+    expect(fieldUsesJSON('Array<{ exercise: string; sets: number }>')).toBe(false);
+  });
+
+  it('returns true for inline object with unknown subfield', () => {
+    expect(fieldUsesJSON('{ data: unknown }')).toBe(true);
+  });
+
+  it('returns true for non-inline JSON type', () => {
+    expect(fieldUsesJSON('unknown')).toBe(true);
+  });
+
+  it('returns true for Record with unknown value', () => {
+    expect(fieldUsesJSON('Record<string, unknown>')).toBe(true);
+  });
+
+  it('returns false for primitive type', () => {
+    expect(fieldUsesJSON('string')).toBe(false);
+  });
+
+  it('returns true for inline object array with nested inline object subfield', () => {
+    expect(fieldUsesJSON('Array<{ workoutId: string; exercises: Array<{ exercise: string }> }>')).toBe(true);
+  });
+
+  it('returns true for inline object with nested inline object subfield', () => {
+    expect(fieldUsesJSON('{ sessions: Array<{ id: string; reps: number }> }')).toBe(true);
+  });
+
+  it('returns false for inline object with only primitive subfields', () => {
+    expect(fieldUsesJSON('{ name: string; count: number }')).toBe(false);
+  });
+});

package/src/codegen/extract/type-helpers.ts

@@ -58,10 +58,13 @@ export function createFieldUsesDate(graphqlType: (ts: string) => string) {
 export function createFieldUsesJSON(graphqlType: (ts: string) => string) {
   return (ts: string): boolean => {
     const b = baseTs(ts);
+    if (isInlineObject(b) || isInlineObjectArray(b)) {
+      if (/:\s*(unknown|any|object)\b/.test(b)) return true;
+      const fields = parseInlineObjectFields(b);
+      return fields.some((f) => isInlineObject(f.tsType) || isInlineObjectArray(f.tsType));
+    }
     const gqlType = graphqlType(b);
-    if (gqlType.includes('GraphQLJSON') || gqlType.includes('JSON')) return true;
-    if (isInlineObject(b) || isInlineObjectArray(b)) return /:\s*(unknown|any|object)\b/.test(b);
-    return false;
+    return gqlType.includes('GraphQLJSON') || gqlType.includes('JSON');
   };
 }
 

package/src/codegen/scaffoldFromSchema.ts

@@ -676,10 +676,29 @@ async function prepareTemplateData(
     messagesByName,
   );
 
+  const normalizedSlice = normalizeSliceForTemplate(slice, allMessages);
+
+  const normalizedRules = normalizedSlice.server?.specs?.rules ?? [];
+  const eventCommandPairs: Array<{ eventType: string; commandType: string }> = [];
+  const seenPairKeys = new Set<string>();
+  for (const rule of normalizedRules) {
+    for (const example of rule.examples ?? []) {
+      const w = Array.isArray(example.when) ? example.when[0] : example.when;
+      const t = Array.isArray(example.then) ? example.then[0] : example.then;
+      if (w && 'eventRef' in w && t && 'commandRef' in t) {
+        const key = `${w.eventRef}\u2192${t.commandRef}`;
+        if (!seenPairKeys.has(key)) {
+          seenPairKeys.add(key);
+          eventCommandPairs.push({ eventType: w.eventRef, commandType: t.commandRef });
+        }
+      }
+    }
+  }
+
   return {
     flowName: flow.name,
     sliceName: slice.name,
-    slice: normalizeSliceForTemplate(slice, allMessages),
+    slice: normalizedSlice,
     stream: { pattern: streamPattern, id: streamId },
     commands: filteredCommands,
     events,
@@ -703,6 +722,7 @@ async function prepareTemplateData(
     allEventTypesArray,
     localEvents,
     referencedTypes,
+    eventCommandPairs,
   };
 }
 

package/src/codegen/templates/command/mutation.resolver.specs.ts

@@ -333,7 +333,6 @@ describe('mutation.resolver.ts.ejs', () => {
 
     expect(mutationFile?.contents).toMatchInlineSnapshot(`
 "import { Mutation, Resolver, Arg, Ctx, Field, InputType, Float } from 'type-graphql';
-import { GraphQLJSON } from 'graphql-type-json';
 import { type GraphQLContext, sendCommand, MutationResponse } from '../../../shared';
 
 @InputType()

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

@@ -99,8 +99,8 @@ describe('query.resolver.ts.ejs', () => {
         async searchProperties(
           @Ctx() ctx: GraphQLContext,
           @Arg('location', () => String, { nullable: true }) location?: string,
-          @Arg('maxPrice', () => Float, { nullable: true }) maxPrice?: number,
-          @Arg('minGuests', () => Float, { nullable: true }) minGuests?: number,
+          @Arg('maxPrice', () => Float, { nullable: true }) _maxPrice?: number,
+          @Arg('minGuests', () => Float, { nullable: true }) _minGuests?: number,
         ): Promise<AvailableListings[]> {
           const model = new ReadModel<AvailableListings>(ctx.database, 'AvailablePropertiesProjection');
 
@@ -193,7 +193,6 @@ describe('query.resolver.ts.ejs', () => {
 
     expect(resolverFile?.contents).toMatchInlineSnapshot(`
       "import { Query, Resolver, Arg, Ctx, ObjectType, Field, ID, Float } from 'type-graphql';
-      import { GraphQLJSON } from 'graphql-type-json';
       import { type GraphQLContext, ReadModel } from '../../../shared';
 
       @ObjectType()
@@ -923,7 +922,7 @@ describe('query.resolver.ts.ejs', () => {
         @Query(() => [RecipeMatchesRecipes])
         async recipeMatches(
           @Ctx() ctx: GraphQLContext,
-          @Arg('pantryId', () => ID, { nullable: true }) pantryId?: string,
+          @Arg('pantryId', () => ID, { nullable: true }) _pantryId?: string,
         ): Promise<RecipeMatchesRecipes[]> {
           const model = new ReadModel<RecipeMatchesRecipes>(ctx.database, 'RecipeMatchesProjection');
 
@@ -934,7 +933,7 @@ describe('query.resolver.ts.ejs', () => {
           // The scaffolded code below uses find() returning an array.
           // If this query should return a single item, switch to findOne().
 
-          return model.find((item) => {
+          return model.find((_item) => {
             // NOTE: 'pantryId' has no matching field on the state type — add custom filter logic if needed.
 
             return true;
@@ -1165,7 +1164,7 @@ describe('query.resolver.ts.ejs', () => {
         @Query(() => [RecipeMatchesRecipes])
         async recipeMatches(
           @Ctx() ctx: GraphQLContext,
-          @Arg('pantryId', () => ID, { nullable: true }) pantryId?: string,
+          @Arg('pantryId', () => ID, { nullable: true }) _pantryId?: string,
         ): Promise<RecipeMatchesRecipes[]> {
           const model = new ReadModel<RecipeMatchesRecipes>(ctx.database, 'RecipeMatchesProjection');
 
@@ -1176,7 +1175,7 @@ describe('query.resolver.ts.ejs', () => {
           // The scaffolded code below uses find() returning an array.
           // If this query should return a single item, switch to findOne().
 
-          return model.find((item) => {
+          return model.find((_item) => {
             // NOTE: 'pantryId' has no matching field on the state type — add custom filter logic if needed.
 
             return true;
@@ -1246,9 +1245,9 @@ describe('query.resolver.ts.ejs', () => {
 
     expect(resolverFile?.contents).toContain("import { GraphQLJSON } from 'graphql-type-json';");
     expect(resolverFile?.contents).toContain(
-      "@Arg('filter', () => GraphQLJSON, { nullable: true }) filter?: Record<string, unknown>",
+      "@Arg('filter', () => GraphQLJSON, { nullable: true }) _filter?: Record<string, unknown>",
     );
-    expect(resolverFile?.contents).toContain("@Arg('limit', () => Float, { nullable: true }) limit?: number");
+    expect(resolverFile?.contents).toContain("@Arg('limit', () => Float, { nullable: true }) _limit?: number");
     expect(resolverFile?.contents).not.toContain('ListWorkoutsFilterInput');
   });
 });

package/src/codegen/templates/query/query.resolver.ts.ejs

@@ -36,6 +36,12 @@ for (const field of messageFields) {
 }
 const hasArgs = parsedRequest?.args?.length > 0;
 
+const stateFieldNames = new Set(messageFields.map(f => f.name));
+const usedArgNames = isSingleton
+  ? new Set()
+  : new Set((parsedRequest?.args ?? []).filter(a => stateFieldNames.has(a.name)).map(a => a.name));
+const hasMatchingArgs = usedArgNames.size > 0;
+
 const resolveArgTypes = (arg) => {
     const isCustom = !KNOWN_GQL_SCALARS.has(arg.graphqlType);
     return {
@@ -118,7 +124,7 @@ async <%= queryName %>(
 <%   for (let i = 0; i < parsedRequest.args.length; i++) {
     const arg = parsedRequest.args[i];
     const { gqlType, tsType } = resolveArgTypes(arg);
-%>    @Arg('<%= arg.name %>', () => <%= gqlType %>, { nullable: true }) <%= arg.name %>?: <%= tsType %><%= i < parsedRequest.args.length - 1 ? ',' : '' %>
+%>    @Arg('<%= arg.name %>', () => <%= gqlType %>, { nullable: true }) <%= usedArgNames.has(arg.name) ? arg.name : '_' + arg.name %>?: <%= tsType %><%= i < parsedRequest.args.length - 1 ? ',' : '' %>
 <%   } } %>
 ): Promise<<%= viewType %>> {
   const result = await ctx.database.collection<<%= viewType %>>('<%= collectionName %>').findOne();
@@ -160,7 +166,7 @@ async <%= queryName %>(
 <%   for (let i = 0; i < parsedRequest.args.length; i++) {
     const arg = parsedRequest.args[i];
     const { gqlType, tsType } = resolveArgTypes(arg);
-%>    @Arg('<%= arg.name %>', () => <%= gqlType %>, { nullable: true }) <%= arg.name %>?: <%= tsType %><%= i < parsedRequest.args.length - 1 ? ',' : '' %>
+%>    @Arg('<%= arg.name %>', () => <%= gqlType %>, { nullable: true }) <%= usedArgNames.has(arg.name) ? arg.name : '_' + arg.name %>?: <%= tsType %><%= i < parsedRequest.args.length - 1 ? ',' : '' %>
 <%   } } %>
 ): Promise<<%= viewType %>[]> {
 const model = new ReadModel<<%= viewType %>>(ctx.database, '<%= collectionName %>');
@@ -172,7 +178,7 @@ const model = new ReadModel<<%= viewType %>>(ctx.database, '<%= collectionName %
 // The scaffolded code below uses find() returning an array.
 // If this query should return a single item, switch to findOne().
 
-return model.find((<%= hasArgs ? 'item' : '_item' %>) => {
+return model.find((<%= hasMatchingArgs ? 'item' : '_item' %>) => {
 <% if (parsedRequest?.args?.length) {
         const stateFieldNames = new Set(messageFields.map(f => f.name));
         for (const arg of parsedRequest.args) {

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

@@ -70,6 +70,69 @@ describe('state.ts.ejs', () => {
     `);
   });
 
+  it('should render projection state fields as required even when spec says required: false', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Workout tracking',
+          slices: [
+            {
+              type: 'query',
+              name: 'Get workout history',
+              client: { specs: [] },
+              server: {
+                description: 'Projects workout history',
+                data: {
+                  items: [
+                    {
+                      origin: {
+                        type: 'projection',
+                        name: 'WorkoutCompleted',
+                        idField: 'id',
+                      },
+                      target: {
+                        type: 'State',
+                        name: 'WorkoutHistory',
+                      },
+                    },
+                  ],
+                },
+                specs: [],
+              },
+            },
+          ],
+        },
+      ],
+      modules: [],
+      messages: [
+        {
+          type: 'state',
+          name: 'WorkoutHistory',
+          fields: [
+            { name: 'id', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+            { name: 'notes', type: 'string', required: false },
+            { name: 'calories', type: 'number', required: false },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const stateFile = plans.find((p) => p.outputPath.endsWith('state.ts'));
+
+    expect(stateFile?.contents).toMatchInlineSnapshot(`
+      "export type WorkoutHistory = {
+        id: string;
+        name: string;
+        notes: string;
+        calories: number;
+      };
+      "
+    `);
+  });
+
   it('should export fallback UnknownState when query slice has no data config', async () => {
     const spec: SpecsSchema = {
       variant: 'specs',

package/src/codegen/templates/query/state.ts.ejs

@@ -7,7 +7,7 @@ export type UnknownState = {
 <% for (const state of states) { -%>
     export type <%= pascalCase(state.type) %> = {
     <% for (const field of state.fields) { -%>
-        <%- field.name %><%= field.required ? '' : '?' %>: <%- field.tsType %>;
+        <%- field.name %>: <%- field.tsType %>;
     <% } -%>
     };
 <% } -%>

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

@@ -217,7 +217,7 @@ describe('react.specs.ts.ejs (react slice)', () => {
               },
             })
 
-            .then({
+            .thenSends({
               type: 'NotifyHost',
               kind: 'Command',
               data: {
@@ -457,7 +457,7 @@ describe('react.specs.ts.ejs (react slice)', () => {
     expect(specFile?.contents).toContain('type ReactorCommand = SendNotification;');
     expect(specFile?.contents).not.toContain('MilestoneNotified');
     expect(specFile?.contents).toContain("type: 'SendNotification'");
-    expect(specFile?.contents).toContain('.then({');
+    expect(specFile?.contents).toContain('.thenSends({');
   });
 
   it('should seed event store with Given state data via appendToStream', async () => {
@@ -637,7 +637,7 @@ describe('react.specs.ts.ejs (react slice)', () => {
               },
             })
 
-            .then({
+            .thenSends({
               type: 'NotifyBarber',
               kind: 'Command',
               data: {

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

@@ -233,7 +233,7 @@ describe('handle.ts.ejs (react slice)', () => {
     const handleFile = plans.find((p) => p.outputPath.endsWith('react.ts'));
 
     expect(handleFile?.contents).toMatchInlineSnapshot(`
-      "import { inMemoryReactor, type MessageHandlerResult, IllegalStateError } from '@event-driven-io/emmett';
+      "import { inMemoryReactor, type MessageHandlerResult } from '@event-driven-io/emmett';
       import type { BookingRequested } from '../guest-submits-booking-request/events';
       import type { ReactorContext } from '../../../shared';
 
@@ -244,7 +244,7 @@ describe('handle.ts.ejs (react slice)', () => {
           connectionOptions: {
             database,
           },
-          eachMessage: async (event, context): Promise<MessageHandlerResult> => {
+          eachMessage: async (event): Promise<MessageHandlerResult> => {
             /**
              * ## IMPLEMENTATION INSTRUCTIONS ##
              *

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

@@ -162,13 +162,13 @@ describe('<%= ruleDescription %>', () => {
 <% if (thenCommands.length === 1) {
     const commandSchema = thenCommands[0];
 %>
-      .then({
+      .thenSends({
         type: '<%= commandSchema.commandRef %>',
         kind: 'Command',
         data: <%- formatDataObject(commandSchema.exampleData, commands.find(c => c.type === commandSchema.commandRef)) %>
       });
 <% } else { %>
-      .then([
+      .thenSends([
 <% for (const cmd of thenCommands) { %>
         {
           type: '<%= cmd.commandRef %>',