@auto-engineer/server-generator-apollo-emmett 1.148.0 → 1.150.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/server-generator-apollo-emmett@1.148.0 build /home/runner/work/auto-engineer/auto-engineer/packages/server-generator-apollo-emmett
+> @auto-engineer/server-generator-apollo-emmett@1.150.0 build /home/runner/work/auto-engineer/auto-engineer/packages/server-generator-apollo-emmett
 > 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
 
 Fixed ESM imports in dist/

package/.turbo/turbo-test.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/server-generator-apollo-emmett@1.147.0 test /home/runner/work/auto-engineer/auto-engineer/packages/server-generator-apollo-emmett
+> @auto-engineer/server-generator-apollo-emmett@1.149.0 test /home/runner/work/auto-engineer/auto-engineer/packages/server-generator-apollo-emmett
 > vitest run --reporter=dot
 
 
@@ -9,6 +9,6 @@
 
  Test Files  40 passed | 1 skipped (41)
       Tests  316 passed | 1 skipped (317)
-   Start at  21:36:26
-   Duration  38.93s (transform 6.40s, setup 0ms, collect 81.57s, tests 17.75s, environment 12ms, prepare 6.16s)
+   Start at  12:21:40
+   Duration  32.02s (transform 6.49s, setup 0ms, collect 66.69s, tests 12.38s, environment 9ms, prepare 6.14s)
 

package/.turbo/turbo-type-check.log

@@ -1,4 +1,4 @@
 
-> @auto-engineer/server-generator-apollo-emmett@1.147.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/server-generator-apollo-emmett
+> @auto-engineer/server-generator-apollo-emmett@1.149.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/server-generator-apollo-emmett
 > tsc --noEmit --project tsconfig.json
 

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @auto-engineer/server-generator-apollo-emmett
 
+## 1.150.0
+
+### Minor Changes
+
+- [`a502d47`](https://github.com/BeOnAuto/auto-engineer/commit/a502d472df528a1c5d53905898220c2a3a49d8a5) Thanks [@osamanar](https://github.com/osamanar)! -
+
+- [`c96a70e`](https://github.com/BeOnAuto/auto-engineer/commit/c96a70e49f9f64213450d0b9840bc9a8b2b1d77d) Thanks [@osamanar](https://github.com/osamanar)! -
+
+- [`4343bca`](https://github.com/BeOnAuto/auto-engineer/commit/4343bcaa2576703ae578fd9b7f5ec5b9776702a9) Thanks [@osamanar](https://github.com/osamanar)! -
+
+- [`28ffce9`](https://github.com/BeOnAuto/auto-engineer/commit/28ffce9c8b95f0c3ca61728bd1f667fa9416d461) Thanks [@osamanar](https://github.com/osamanar)! -
+
+- [`3fd5dbf`](https://github.com/BeOnAuto/auto-engineer/commit/3fd5dbfbfb4f7a5fe71ae53105b31a1b0f30f911) Thanks [@osamanar](https://github.com/osamanar)! -
+
+### Patch Changes
+
+- [`41f3df3`](https://github.com/BeOnAuto/auto-engineer/commit/41f3df3025445ba92208c2b007b8e29a40489309) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **global**: version packages
+  - **global**: major refresh to all the docs
+- Updated dependencies [[`a502d47`](https://github.com/BeOnAuto/auto-engineer/commit/a502d472df528a1c5d53905898220c2a3a49d8a5), [`c96a70e`](https://github.com/BeOnAuto/auto-engineer/commit/c96a70e49f9f64213450d0b9840bc9a8b2b1d77d), [`4343bca`](https://github.com/BeOnAuto/auto-engineer/commit/4343bcaa2576703ae578fd9b7f5ec5b9776702a9), [`28ffce9`](https://github.com/BeOnAuto/auto-engineer/commit/28ffce9c8b95f0c3ca61728bd1f667fa9416d461), [`41f3df3`](https://github.com/BeOnAuto/auto-engineer/commit/41f3df3025445ba92208c2b007b8e29a40489309), [`3fd5dbf`](https://github.com/BeOnAuto/auto-engineer/commit/3fd5dbfbfb4f7a5fe71ae53105b31a1b0f30f911)]:
+  - @auto-engineer/message-bus@1.150.0
+  - @auto-engineer/narrative@1.150.0
+
+## 1.149.0
+
+### Minor Changes
+
+- [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **server-generator-apollo-emmett**: add Given state ref hints to state.ts.ejs
+  - **server-generator-apollo-emmett**: context-aware nonCommandField instructions
+  - **server-generator-apollo-emmett**: add state context instruction
+  - **server-generator-apollo-emmett**: extract shared template helpers
+  - **server-generator-apollo-emmett**: filter state refs from hasGivenEvents in decide.ts.ejs
+
+### Patch Changes
+
+- [`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38) Thanks [@SamHatoum](https://github.com/SamHatoum)! -
+
+- Updated dependencies [[`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38), [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98)]:
+  - @auto-engineer/message-bus@1.149.0
+  - @auto-engineer/narrative@1.149.0
+
 ## 1.148.0
 
 ### Minor Changes

package/README.md

@@ -1,14 +1,14 @@
 # @auto-engineer/server-generator-apollo-emmett
 
-Code generation that scaffolds event-sourced GraphQL servers using the Emmett framework.
+Code generator that scaffolds event-sourced GraphQL servers using Apollo Server, type-graphql, and the Emmett event sourcing framework. Takes a narrative model and produces a fully runnable server with commands, events, projections, queries, and reactors.
 
 ---
 
 ## Purpose
 
-Without `@auto-engineer/server-generator-apollo-emmett`, you would have to manually write event sourcing boilerplate, create GraphQL resolvers, define command/event types, and set up projections for every slice in your server.
+Without this package, you would need to manually write event sourcing boilerplate (decide/evolve functions), GraphQL resolvers, command/event type definitions, projections, and reactor wiring for every moment in your narrative model.
 
-This package transforms narrative specifications into a complete Apollo GraphQL server with commands, events, projections, queries, and reactors following the Emmett event sourcing patterns.
+This package reads a `Model` object (scenes, messages, integrations, narratives) and generates a complete `server/` directory containing an Apollo GraphQL server that follows Emmett's event sourcing patterns -- including EJS-templated code for each moment type (command, query, react).
 
 ---
 
@@ -18,37 +18,48 @@ This package transforms narrative specifications into a complete Apollo GraphQL
 pnpm add @auto-engineer/server-generator-apollo-emmett
 ```
 
-## Quick Start
+---
 
-Register the handler and generate a server:
+## Quick Start
 
-### 1. Register the handlers
+### 1. Register the command handlers
 
 ```typescript
 import { COMMANDS } from '@auto-engineer/server-generator-apollo-emmett';
 import { createMessageBus } from '@auto-engineer/message-bus';
 
 const bus = createMessageBus();
-COMMANDS.forEach(cmd => bus.registerCommand(cmd));
+COMMANDS.forEach((cmd) => bus.registerCommand(cmd));
 ```
 
-### 2. Send a command
+### 2. Generate a server from a model
 
 ```typescript
-const result = await bus.dispatch({
+await bus.send({
   type: 'GenerateServer',
   data: {
-    modelPath: './.context/schema.json',
+    model: myModel, // a Model object from @auto-engineer/narrative
     destination: '.',
   },
-  requestId: 'req-123',
+  requestId: 'req-1',
 });
+```
+
+This creates a `server/` directory at the destination with a runnable Apollo GraphQL server.
 
-console.log(result);
-// → { type: 'ServerGenerated', data: { serverDir: './server', destination: '.' } }
+### 3. Initialize a bare server (no model needed)
+
+```typescript
+await bus.send({
+  type: 'InitializeServer',
+  data: {
+    destination: '.',
+  },
+  requestId: 'req-2',
+});
 ```
 
-The command generates a complete server directory with Apollo, Emmett, and type-graphql.
+Creates a minimal server with a health endpoint, ready for incremental generation.
 
 ---
 
@@ -57,40 +68,54 @@ The command generates a complete server directory with Apollo, Emmett, and type-
 ### Run via CLI
 
 ```bash
-auto generate:server --model-path=./.context/schema.json --destination=.
+auto build:backend --destination=.
+auto initialize:server --destination=.
 ```
 
-### Run Programmatically
+### Handle generation results
 
 ```typescript
-import { COMMANDS } from '@auto-engineer/server-generator-apollo-emmett';
-import { createMessageBus } from '@auto-engineer/message-bus';
-
-const bus = createMessageBus();
-COMMANDS.forEach(handler => bus.register(handler));
-
-await bus.send({
+const events = await bus.send({
   type: 'GenerateServer',
-  data: {
-    modelPath: './.context/schema.json',
-    destination: '.',
-  },
+  data: { model, destination: '.' },
+  requestId: 'req-1',
 });
-```
-
-### Handle Errors
 
-```typescript
-if (result.type === 'ServerGenerationFailed') {
-  console.error(result.data.error);
+for (const event of events) {
+  switch (event.type) {
+    case 'ServerGenerated':
+      console.log(`Server written to ${event.data.serverDir}`);
+      break;
+    case 'MomentGenerated':
+      console.log(`Generated: ${event.data.sceneName}/${event.data.momentName}`);
+      break;
+    case 'ServerGenerationFailed':
+      console.error(event.data.error);
+      break;
+  }
 }
 ```
 
-### Listen for Slice Events
+### Incremental generation with change sets
+
+When the model changes, pass a `changeSet` to only regenerate affected moments:
 
 ```typescript
-bus.on('SliceGenerated', (event) => {
-  console.log(`Generated: ${event.data.flowName}/${event.data.sliceName}`);
+await bus.send({
+  type: 'GenerateServer',
+  data: {
+    model,
+    destination: '.',
+    changeSet: {
+      added: ['scene-dir/moment-dir'],
+      removed: ['old-scene/old-moment'],
+      changed: ['scene-dir/updated-moment'],
+      sharedTypesChanged: false,
+      allAffected: ['scene-dir/moment-dir', 'scene-dir/updated-moment'],
+      deltas: {},
+    },
+  },
+  requestId: 'req-3',
 });
 ```
 
@@ -105,9 +130,13 @@ import { COMMANDS } from '@auto-engineer/server-generator-apollo-emmett';
 
 import type {
   GenerateServerCommand,
+  GenerateServerEvents,
   ServerGeneratedEvent,
   ServerGenerationFailedEvent,
-  SliceGeneratedEvent,
+  MomentGeneratedEvent,
+  InitializeServerCommand,
+  ServerInitializedEvent,
+  ServerInitializationFailedEvent,
 } from '@auto-engineer/server-generator-apollo-emmett';
 ```
 
@@ -115,7 +144,8 @@ import type {
 
 | Command | CLI Alias | Description |
 |---------|-----------|-------------|
-| `GenerateServer` | `generate:server` | Generate event-sourced GraphQL server |
+| `GenerateServer` | `build:backend` | Generate event-sourced GraphQL server from a model |
+| `InitializeServer` | `initialize:server` | Create a bare runnable server with health endpoint |
 
 ### GenerateServerCommand
 
@@ -123,39 +153,35 @@ import type {
 type GenerateServerCommand = Command<
   'GenerateServer',
   {
-    modelPath: string;
+    model: Model;
     destination: string;
+    changeSet?: ChangeSet;
+    isFirstRun?: boolean;
+    newState?: GenerationState;
   }
 >;
 ```
 
-### ServerGeneratedEvent
+### InitializeServerCommand
 
 ```typescript
-type ServerGeneratedEvent = Event<
-  'ServerGenerated',
+type InitializeServerCommand = Command<
+  'InitializeServer',
   {
-    modelPath: string;
     destination: string;
-    serverDir: string;
   }
 >;
 ```
 
-### SliceGeneratedEvent
+### Events
 
-```typescript
-type SliceGeneratedEvent = Event<
-  'SliceGenerated',
-  {
-    flowName: string;
-    sliceName: string;
-    sliceType: string;
-    schemaPath: string;
-    slicePath: string;
-  }
->;
-```
+| Event | Emitted when |
+|-------|-------------|
+| `ServerGenerated` | Full or incremental generation completes successfully |
+| `ServerGenerationFailed` | Generation fails (includes error details, scene/moment context) |
+| `MomentGenerated` | An individual moment is scaffolded |
+| `ServerInitialized` | Bare server skeleton is created |
+| `ServerInitializationFailed` | Server initialization fails |
 
 ---
 
@@ -163,72 +189,117 @@ type SliceGeneratedEvent = Event<
 
 ```
 src/
-├── index.ts
-├── server.ts
+├── index.ts                  # COMMANDS array, re-exports types
+├── server.ts                 # Runtime server entry (copied into generated output)
 ├── commands/
-│   └── generate-server.ts
+│   ├── generate-server.ts    # GenerateServer command handler
+│   └── initialize-server.ts  # InitializeServer command handler
 ├── codegen/
-│   ├── scaffoldFromSchema.ts
-│   ├── extract/
-│   └── templates/
-│       ├── command/
-│       ├── query/
-│       └── react/
-├── domain/shared/
-└── utils/
+│   ├── scaffoldFromSchema.ts # Orchestrates file plan generation and writing
+│   ├── templateHelpers.ts    # Helpers for EJS templates
+│   ├── types.ts              # Message, Field, GwtCondition types
+│   ├── extract/              # Extractors for commands, events, states, projections, queries
+│   │   ├── commands.ts
+│   │   ├── events.ts
+│   │   ├── gwt.ts
+│   │   ├── imports.ts
+│   │   ├── messages.ts
+│   │   ├── projection.ts
+│   │   ├── query.ts
+│   │   ├── states.ts
+│   │   ├── step-converter.ts
+│   │   ├── step-types.ts
+│   │   └── type-helpers.ts
+│   └── templates/            # EJS templates per moment type
+│       ├── command/          # decide, evolve, handle, commands, events, state, mutation.resolver, register
+│       ├── query/            # projection, query.resolver, events, state
+│       └── react/            # react handler, register, events
+├── domain/shared/            # Runtime code copied into generated server
+│   ├── types.ts              # GraphQLContext, ReactorContext
+│   ├── graphql-types.ts      # MutationResponse, MutationError
+│   ├── ReadModel.ts          # In-memory read model wrapper
+│   ├── sendCommand.ts        # Command dispatch helper
+│   └── reactorSpecification.ts # Test helper for reactor assertions
+└── utils/                    # Runtime utilities copied into generated server
+    ├── loadResolvers.ts      # Glob-loads resolver classes
+    ├── loadProjections.ts    # Glob-loads projection definitions
+    └── loadRegisterFiles.ts  # Glob-loads moment registration files
 ```
 
-The following diagram shows the generation flow:
+### Generation flow
 
 ```mermaid
 flowchart TB
-    A[GenerateServer] --> B[Load Model JSON]
-    B --> C[Extract Messages from Specs]
-    C --> D[Build GWT Mappings]
-    D --> E[Render EJS Templates]
-    E --> F[Write Files to Disk]
-    F --> G[ServerGeneratedEvent]
+    A[GenerateServer command] --> B{First run or change set?}
+    B -- First run --> C[Clean server directory]
+    B -- Incremental --> D[Remove deleted moments]
+    C --> E[Copy runtime files]
+    D --> E
+    E --> F[Extract messages from model specs]
+    F --> G[Build GWT mappings per moment]
+    G --> H[Render EJS templates into file plans]
+    H --> I[Write files to disk]
+    I --> J[Write config files: package.json, tsconfig, vitest, biome]
+    J --> K[Emit MomentGenerated / ServerGenerated events]
 ```
 
-*Flow: Command loads model, extracts commands/events, renders templates, writes generated server.*
-
-### Generated Server Structure
+### Generated server structure
 
 ```
 server/
 ├── src/
-│   ├── server.ts
+│   ├── server.ts                    # Apollo Server entry point with Emmett event store
 │   ├── utils/
+│   │   ├── loadResolvers.ts
+│   │   ├── loadProjections.ts
+│   │   └── loadRegisterFiles.ts
 │   └── domain/
 │       ├── shared/
-│       └── flows/
-│           └── {flow-name}/
-│               └── {slice-name}/
-│                   ├── commands.ts
+│       │   ├── types.ts             # GraphQLContext, ReactorContext
+│       │   ├── graphql-types.ts     # MutationResponse
+│       │   ├── ReadModel.ts
+│       │   └── sendCommand.ts
+│       └── narratives/
+│           ├── health/
+│           │   └── query.resolver.ts
+│           └── {narrative}_{scene}/
+│               └── {moment}/
+│                   ├── commands.ts           # (command type)
 │                   ├── events.ts
 │                   ├── state.ts
 │                   ├── decide.ts
 │                   ├── evolve.ts
-│                   └── mutation.resolver.ts
+│                   ├── handle.ts
+│                   ├── mutation.resolver.ts
+│                   ├── decide.specs.ts
+│                   ├── register.ts
+│                   ├── projection.ts         # (query type)
+│                   ├── projection.specs.ts
+│                   ├── query.resolver.ts
+│                   ├── react.ts              # (react type)
+│                   └── react.specs.ts
 ├── package.json
-└── tsconfig.json
+├── tsconfig.json
+├── vitest.config.ts
+└── biome.json
 ```
 
-### Slice Types
-
-| Type | Description |
-|------|-------------|
-| Command | Mutation resolvers with decide/evolve pattern |
-| Query | Query resolvers backed by projections |
-| React | Reactors responding to events with commands |
-
-### Dependencies
-
-| Package | Usage |
-|---------|-------|
-| `@auto-engineer/narrative` | Model type definitions |
-| `@auto-engineer/message-bus` | Command/event infrastructure |
-| `@event-driven-io/emmett` | Event sourcing framework |
-| `apollo-server` | GraphQL server runtime |
-| `type-graphql` | GraphQL schema decorators |
-| `ejs` | Template rendering |
+### Moment types
+
+| Type | Generated files | Pattern |
+|------|----------------|---------|
+| `command` | commands, events, state, decide, evolve, handle, mutation.resolver, decide.specs, register | Mutation resolver dispatches command; decide produces events; evolve updates state |
+| `query` | events, projection, state, projection.specs, query.resolver | Query resolver reads from in-memory projection built from events |
+| `react` | events, react handler, react.specs, register | Reactor listens to events and sends commands in response |
+
+### Key dependencies
+
+| Package | Role |
+|---------|------|
+| `@auto-engineer/narrative` | Model type definitions (Scene, Moment, Model) |
+| `@auto-engineer/message-bus` | Command handler registration and dispatch |
+| `@event-driven-io/emmett` | Event sourcing runtime (event store, projections, message bus) |
+| `@event-driven-io/emmett-sqlite` | SQLite-backed event store |
+| `apollo-server` | GraphQL server |
+| `type-graphql` | Decorator-based GraphQL schema definitions |
+| `ejs` | Template rendering for code generation |

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