@auto-engineer/server-generator-apollo-emmett 0.1.1

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

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { SpecsSchemaType as SpecsSchema } from '@auto-engineer/flow';
+import { generateScaffoldFilePlans } from '../../scaffoldFromSchema';
+
+describe('events.ts.ejs', () => {
+  it('should generate an event file', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      flows: [
+        {
+          name: 'Host creates a listing',
+          slices: [
+            {
+              type: 'command',
+              name: 'Create listing',
+              client: {
+                description: 'test',
+                specs: [],
+              },
+              server: {
+                description: 'test',
+                gwt: [
+                  {
+                    when: {
+                      commandRef: 'CreateListing',
+                      exampleData: {
+                        propertyId: 'listing_123',
+                        title: 'blah',
+                        pricePerNight: 250,
+                        maxGuests: 4,
+                        amenities: ['wifi', 'kitchen'],
+                        available: true,
+                        tags: ['some tag'],
+                        rating: 4.8,
+                        metadata: { foo: 'bar' },
+                        listedAt: '2024-01-15T10:00:00Z',
+                      },
+                    },
+                    then: [
+                      {
+                        eventRef: 'ListingCreated',
+                        exampleData: {
+                          propertyId: 'listing_123',
+                          listedAt: '2024-01-15T10:00:00Z',
+                          rating: 4.8,
+                          metadata: { foo: 'bar' },
+                        },
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'CreateListing',
+          fields: [],
+        },
+        {
+          type: 'event',
+          name: 'ListingCreated',
+          source: 'internal',
+          fields: [
+            { name: 'propertyId', type: 'string', required: true },
+            { name: 'listedAt', type: 'Date', required: true },
+            { name: 'rating', type: 'number', required: true },
+            { name: 'metadata', type: 'object', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'ListingCreated',
+          source: 'internal',
+          fields: [
+            { name: 'propertyId', type: 'string', required: true },
+            { name: 'listedAt', type: 'Date', required: true },
+            { name: 'rating', type: 'number', required: true },
+            { name: 'metadata', type: 'object', required: true },
+          ],
+        },
+      ],
+    };
+
+    const plans = await generateScaffoldFilePlans(spec.flows, spec.messages, undefined, 'src/domain/flows');
+    const eventFile = plans.find((p) => p.outputPath.endsWith('events.ts'));
+
+    expect(eventFile?.contents).toMatchInlineSnapshot(`
+"import type { Event } from '@event-driven-io/emmett';
+
+export type ListingCreated = Event<
+  'ListingCreated',
+  {
+    propertyId: string;
+    listedAt: Date;
+    rating: number;
+    metadata: object;
+  }
+>;
+"
+    `);
+  });
+});

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

@@ -0,0 +1,14 @@
+<% if (events.length) { -%>
+    import type { Event } from '@event-driven-io/emmett';
+
+    <% for (const event of events) { -%>
+        export type <%= pascalCase(event.type) %> = Event<
+        '<%= event.type %>',
+        {
+        <% for (const field of event.fields) { -%>
+            <%- field.name %>: <%- field.tsType %>;
+        <% } -%>
+        }
+        >;
+    <% } -%>
+<% } -%>

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

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { SpecsSchemaType as SpecsSchema } from '@auto-engineer/flow';
+import { generateScaffoldFilePlans } from '../../scaffoldFromSchema';
+
+describe('evolve.ts.ejs', () => {
+  it('should generate a valid evolve file from event structure', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      flows: [
+        {
+          name: 'Host creates a listing',
+          slices: [
+            {
+              type: 'command',
+              name: 'Create listing',
+              client: {
+                description: 'test',
+                specs: [],
+              },
+              server: {
+                description: 'test',
+                gwt: [
+                  {
+                    when: {
+                      commandRef: 'CreateListing',
+                      exampleData: {
+                        propertyId: 'listing_123',
+                        title: 'Some Apartment',
+                        listedAt: '2024-01-15T10:00:00Z',
+                        rating: 4.8,
+                        metadata: { foo: 'bar' },
+                      },
+                    },
+                    then: [
+                      {
+                        eventRef: 'ListingCreated',
+                        exampleData: {
+                          propertyId: 'listing_123',
+                          listedAt: '2024-01-15T10:00:00Z',
+                          rating: 4.8,
+                          metadata: { foo: 'bar' },
+                        },
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'CreateListing',
+          fields: [],
+        },
+        {
+          type: 'event',
+          name: 'ListingCreated',
+          source: 'internal',
+          fields: [],
+        },
+      ],
+    };
+
+    const plans = await generateScaffoldFilePlans(spec.flows, spec.messages, undefined, 'src/domain/flows');
+    const evolveFile = plans.find((p) => p.outputPath.endsWith('evolve.ts'));
+
+    expect(evolveFile?.contents).toMatchInlineSnapshot(`
+          "import type { State } from './state';
+          import type { ListingCreated } from './events';
+
+          /**
+           * ## IMPLEMENTATION INSTRUCTIONS ##
+           *
+           * This function defines how the domain state evolves in response to events.
+           *
+           * Guidelines:
+           * - Apply only the **minimal** necessary changes for future decisions in \`decide.ts\`.
+           * - Ignore any event fields not required for decision-making logic.
+           * - If the event doesn’t change decision-relevant state, return the existing \`state\`.
+           * - Prefer immutability: always return a **new state object**.
+           * - Avoid spreading all of \`event.data\` unless all fields are relevant.
+           */
+
+          export const evolve = (state: State, event: ListingCreated): State => {
+            switch (event.type) {
+              case 'ListingCreated': {
+                // TODO: Update state based on ListingCreated
+                return {
+                  ...state,
+                };
+              }
+              default:
+                return state;
+            }
+          };
+          "
+        `);
+  });
+});

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

@@ -0,0 +1,39 @@
+<% if (events.length) { -%>
+    import type { State } from './state';
+    <% events.forEach(event => { -%>
+        import type { <%= pascalCase(event.type) %> } from './events';
+    <% }); -%>
+
+    /**
+    * ## IMPLEMENTATION INSTRUCTIONS ##
+    *
+    * This function defines how the domain state evolves in response to events.
+    *
+    * Guidelines:
+    * - Apply only the **minimal** necessary changes for future decisions in `decide.ts`.
+    * - Ignore any event fields not required for decision-making logic.
+    * - If the event doesn’t change decision-relevant state, return the existing `state`.
+    * - Prefer immutability: always return a **new state object**.
+    * - Avoid spreading all of `event.data` unless all fields are relevant.
+    */
+
+    export const evolve = (
+    state: State,
+    event: <%= events.map(e => pascalCase(e.type)).join(' | ') %>
+    ): State => {
+    switch (event.type) {
+    <% events.forEach(event => { -%>
+        case '<%= event.type %>': {
+        // TODO: Update state based on <%= event.type %>
+        return {
+        ...state
+        };
+        }
+    <% }); -%>
+    default:
+    return state;
+    }
+    };
+<% } else { -%>
+    // No events defined yet. Evolve logic will be generated once events exist.
+<% } -%>

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

@@ -0,0 +1,313 @@
+import { describe, it, expect } from 'vitest';
+import { generateScaffoldFilePlans } from '../../scaffoldFromSchema';
+import { SpecsSchemaType as SpecsSchema } from '@auto-engineer/flow';
+
+describe('generateScaffoldFilePlans', () => {
+  it('should generate a valid handle file', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      flows: [
+        {
+          name: 'Host creates a listing',
+          slices: [
+            {
+              type: 'command',
+              name: 'Create listing',
+              stream: 'listing-${propertyId}',
+              client: {
+                description: 'test',
+                specs: [],
+              },
+              server: {
+                description: 'test',
+                gwt: [
+                  {
+                    when: {
+                      commandRef: 'CreateListing',
+                      exampleData: {
+                        propertyId: 'listing_123',
+                        title: 'Modern Downtown Apartment',
+                        listedAt: '2024-01-15T10:00:00Z',
+                        rating: 4.8,
+                        metadata: { foo: 'bar' },
+                      },
+                    },
+                    then: [
+                      {
+                        eventRef: 'ListingCreated',
+                        exampleData: {
+                          propertyId: 'listing_123',
+                          listedAt: '2024-01-15T10:00:00Z',
+                          rating: 4.8,
+                          metadata: { foo: 'bar' },
+                        },
+                      },
+                    ],
+                  },
+                ],
+                data: [
+                  {
+                    target: {
+                      type: 'Event',
+                      name: 'ListingCreated',
+                    },
+                    destination: {
+                      type: 'stream',
+                      pattern: 'listings-${propertyId}',
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'CreateListing',
+          fields: [
+            { name: 'propertyId', type: 'string', required: true },
+            { name: 'title', type: 'string', required: true },
+            { name: 'listedAt', type: 'Date', required: true },
+            { name: 'rating', type: 'number', required: true },
+            { name: 'metadata', type: 'object', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'ListingCreated',
+          source: 'internal',
+          fields: [
+            { name: 'propertyId', type: 'string', required: true },
+            { name: 'title', type: 'string', required: true },
+            { name: 'listedAt', type: 'Date', required: true },
+            { name: 'rating', type: 'number', required: true },
+            { name: 'metadata', type: 'object', required: true },
+          ],
+        },
+      ],
+    };
+
+    const plans = await generateScaffoldFilePlans(spec.flows, spec.messages, undefined, 'src/domain/flows');
+    const handleFile = plans.find((p) => p.outputPath.endsWith('handle.ts'));
+
+    expect(handleFile?.contents).toMatchInlineSnapshot(`
+      "import { CommandHandler, type EventStore, type MessageHandlerResult } from '@event-driven-io/emmett';
+      import { evolve } from './evolve';
+      import { initialState } from './state';
+      import { decide } from './decide';
+      import type { CreateListing } from './commands';
+
+      const handler = CommandHandler({
+        evolve,
+        initialState,
+      });
+
+      export const handle = async (eventStore: EventStore, command: CreateListing): Promise<MessageHandlerResult> => {
+        const streamId = \`listings-\${command.data.propertyId}\`;
+
+        try {
+          await handler(eventStore, streamId, (state) => decide(command, state));
+          return; // success (returns void)
+        } catch (error: any) {
+          return {
+            type: 'SKIP',
+            reason: \`Command failed: \${error?.message ?? 'Unknown'}\`,
+          };
+        }
+      };
+      "
+    `);
+  });
+  it('should generate a valid handle file with integration', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      flows: [
+        {
+          name: 'Assistant suggests items',
+          slices: [
+            {
+              type: 'command',
+              name: 'Suggest Items',
+              stream: 'session-${sessionId}',
+              client: {
+                description: 'test',
+                specs: [],
+              },
+              server: {
+                description: '',
+                data: [
+                  {
+                    target: {
+                      type: 'Command',
+                      name: 'SuggestItems',
+                    },
+                    destination: {
+                      type: 'integration',
+                      systems: ['AI'],
+                      message: {
+                        name: 'DoChat',
+                        type: 'command',
+                      },
+                    },
+                    _additionalInstructions: 'Ensure systemPrompt includes product catalogue guidance',
+                    _withState: {
+                      target: {
+                        type: 'State',
+                        name: 'Products',
+                      },
+                      origin: {
+                        type: 'integration',
+                        systems: ['product-catalog'],
+                      },
+                    },
+                  },
+                  {
+                    target: {
+                      type: 'Event',
+                      name: 'ItemsSuggested',
+                    },
+                    destination: {
+                      type: 'stream',
+                      pattern: 'session-${sessionId}',
+                    },
+                  },
+                ],
+                gwt: [
+                  {
+                    when: {
+                      commandRef: 'SuggestItems',
+                      exampleData: {
+                        sessionId: 'session-123',
+                        prompt: 'What should I buy?',
+                      },
+                    },
+                    then: [
+                      {
+                        eventRef: 'ItemsSuggested',
+                        exampleData: {
+                          sessionId: 'session-123',
+                          items: [],
+                        },
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'SuggestItems',
+          fields: [
+            { name: 'sessionId', type: 'string', required: true },
+            { name: 'prompt', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'DoChat',
+          fields: [
+            { name: 'sessionId', type: 'string', required: true },
+            { name: 'prompt', type: 'string', required: true },
+            { name: 'systemPrompt', type: 'string', required: false },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'ItemsSuggested',
+          source: 'internal',
+          fields: [
+            { name: 'sessionId', type: 'string', required: true },
+            { name: 'items', type: 'Array<object>', required: true },
+          ],
+        },
+        {
+          type: 'state',
+          name: 'Products',
+          fields: [
+            {
+              name: 'products',
+              type: 'Array<{ id: string, name: string }>',
+              required: true,
+            },
+          ],
+        },
+      ],
+      integrations: [
+        {
+          name: 'AI',
+          source: '@auto-engineer/ai-integration',
+          description: '',
+        },
+        {
+          name: 'product-catalog',
+          source: '@auto-engineer/product-catalogue-integration',
+          description: '',
+        },
+      ],
+    };
+
+    const plans = await generateScaffoldFilePlans(spec.flows, spec.messages, spec.integrations, 'src/domain/flows');
+    const handleFile = plans.find((p) => p.outputPath.endsWith('handle.ts'));
+
+    expect(handleFile?.contents).toMatchInlineSnapshot(`
+      "import '@auto-engineer/product-catalogue-integration';
+
+      import { AI } from '@auto-engineer/ai-integration';
+
+      import { Products } from '@auto-engineer/product-catalogue-integration';
+
+      import { CommandHandler, type EventStore, type MessageHandlerResult } from '@event-driven-io/emmett';
+      import { evolve } from './evolve';
+      import { initialState } from './state';
+      import { decide } from './decide';
+      import type { SuggestItems } from './commands';
+
+      /**
+       * ## IMPLEMENTATION INSTRUCTIONS ##
+       * Ensure systemPrompt includes product catalogue guidance
+       */
+
+      const handler = CommandHandler({
+        evolve,
+        initialState,
+      });
+
+      export const handle = async (eventStore: EventStore, command: SuggestItems): Promise<MessageHandlerResult> => {
+        const streamId = \`session-\${command.data.sessionId}\`;
+
+        try {
+          // TODO: Map fields from the incoming command to this integration input.
+          // - Use relevant fields from \`command.data\` to populate the required inputs below.
+          // - Some fields may require transformation or enrichment.
+          // - If additional context is needed, construct it here.
+          // const products: Products | undefined = await AI.Commands?.DoChat<Products>({
+          //   type: 'DoChat',
+          //   data: {
+          //    // sessionId: ???
+          // prompt: ???
+          // systemPrompt: ???
+          //   },
+          // });
+
+          await handler(eventStore, streamId, (state) =>
+            // TODO: add products as a parameter to decide once implemented above
+            decide(command, state /* products */),
+          );
+          return; // success (returns void)
+        } catch (error: any) {
+          return {
+            type: 'SKIP',
+            reason: \`Command failed: \${error?.message ?? 'Unknown'}\`,
+          };
+        }
+      };
+      "
+    `);
+  });
+});

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

@@ -0,0 +1,111 @@
+<%
+const integrationData = (slice.server?.data ?? []).filter(d => d.destination?.type === 'integration');
+
+const integrationImports = new Map();
+const integrationSideEffectImports = new Set();
+
+for (const d of integrationData) {
+    for (const system of d.destination?.systems ?? []) {
+        const integration = (integrations ?? []).find(i => i.name === system);
+        if (integration) {
+            integrationImports.set(system, integration.source);
+        }
+    }
+
+    const returnType = d._withState?.target?.name;
+    const returnSystem = d._withState?.origin?.systems?.[0];
+    if (returnType && returnSystem) {
+        const integration = (integrations ?? []).find(i => i.name === returnSystem);
+        if (integration) {
+            integrationImports.set(returnType, integration.source);
+            integrationSideEffectImports.add(integration.source);
+        }
+    }
+}
+
+const additionalInstructions = (slice.server?.data ?? [])
+        .map(d => d._additionalInstructions)
+        .filter(Boolean);
+
+const integrationCalls = integrationData.map((d, i) => {
+    const system = d.destination.systems?.[0];
+    const messageName = d.destination.message?.name;
+    const returnType = d._withState?.target?.name;
+    const varName = returnType ? camelCase(returnType) : `result${i + 1}`;
+
+    const inputFields = messages.find(m => m.name === messageName && m.type === 'command')?.fields ?? [];
+    const inputLines = inputFields.map(f => `    // ${f.name}: ???`);
+
+    return {
+        varName,
+        call: `// TODO: Map fields from the incoming command to this integration input.
+// - Use relevant fields from \`command.data\` to populate the required inputs below.
+// - Some fields may require transformation or enrichment.
+// - If additional context is needed, construct it here.
+// const ${varName}${returnType ? `: ${returnType} | undefined` : ''} = await ${system}.Commands?.${messageName}${returnType ? `<${returnType}>` : ''}({
+//   type: '${messageName}',
+//   data: {
+//${inputLines.join('\n')}
+//   },
+// });`,
+    };
+});
+
+const resultVarName = integrationCalls.find(call => !!call.varName)?.varName;
+const needsReturnValue = typeof resultVarName === 'string';
+%>
+
+<% integrationSideEffectImports.forEach((importSource) => { %>
+    import '<%= importSource %>';
+<% }); %>
+<% integrationImports.forEach((importSource, importName) => { %>
+    import { <%= importName %> } from '<%= importSource %>';
+<% }); %>
+import { CommandHandler, type EventStore, type MessageHandlerResult } from '@event-driven-io/emmett';
+import { evolve } from './evolve';
+import { initialState } from './state';
+import { decide } from './decide';
+import type { <%= commands.map(c => pascalCase(c.type)).join(', ') %> } from './commands';
+
+<% if (additionalInstructions.length) { -%>
+    /**
+    * ## IMPLEMENTATION INSTRUCTIONS ##
+    <% additionalInstructions.forEach(instr => { -%>
+        * <%= instr %>
+    <% }) -%>
+    */
+<% } -%>
+
+const handler = CommandHandler({
+evolve,
+initialState,
+});
+
+export const handle = async (
+eventStore: EventStore,
+command: <%= commands.map(c => pascalCase(c.type)).join(' | ') %>
+): Promise<MessageHandlerResult> => {
+    <% if (stream?.pattern?.includes('${')) { -%>
+        const streamId = `<%= stream.pattern.replace(/\$\{([^}]+)\}/g, (_, key) => `\${command.data.${key}}`) %>`;
+    <% } else { -%>
+        const streamId = '<%= stream?.pattern ?? 'unknown-stream' %>';
+    <% } -%>
+
+    try {
+    <% integrationCalls.forEach(({ call }) => { -%>
+        <%= call %>
+
+    <% }) -%>
+    await handler(eventStore, streamId, (state) =>
+    <%- needsReturnValue
+            ? `      // TODO: add ${resultVarName} as a parameter to decide once implemented above\n      decide(command, state, /* ${resultVarName} */)`
+            : `      decide(command, state)` %>
+    );
+    return; // success (returns void)
+    } catch (error: any) {
+    return {
+    type: 'SKIP',
+    reason: `Command failed: ${error?.message ?? 'Unknown'}`,
+    };
+    }
+    };