@auto-engineer/server-generator-nestjs 1.148.0 → 1.150.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @auto-engineer/server-generator-nestjs
 
+## 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/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/narrative@1.149.0
+
 ## 1.148.0
 
 ### Minor Changes

package/README.md

@@ -1,27 +1,22 @@
 # @auto-engineer/server-generator-nestjs
 
-| | |
-| --- | --- |
-| **Status** | EXPERIMENTAL - NOT READY FOR PRODUCTION |
-| **Stability** | APIs will change without notice |
-| **Completeness** | Features may be incomplete or broken |
-
 Generates complete NestJS servers from narrative domain models with CQRS, GraphQL, and MikroORM.
 
 ---
 
 ## Purpose
 
-Without `@auto-engineer/server-generator-nestjs`, you would have to manually scaffold NestJS modules, wire up CQRS command/query handlers, configure GraphQL resolvers, define MikroORM entities, and write boilerplate test files for every domain slice.
+Without this package, you would manually scaffold NestJS modules, wire up CQRS command/query handlers, configure GraphQL resolvers, define MikroORM entities, and write boilerplate test files for every domain moment.
 
-This package takes a narrative model (JSON) describing your domain flows and slices, then generates a fully functional NestJS server with:
+This package takes a `Model` object (from `@auto-engineer/narrative`) describing your domain scenes and moments, then generates a fully functional NestJS server with:
 
 - CQRS pattern via `@nestjs/cqrs` for command and query separation
-- GraphQL API via Apollo Server with auto-generated resolvers
-- MikroORM entities with SQLite persistence
-- Test scaffolds for each command handler
+- GraphQL API via Apollo Server with auto-generated resolvers, inputs, and types
+- MikroORM entities with SQLite persistence, including primary key detection and enum support
+- Test scaffolds (vitest specs) for each command handler
+- Consolidated entities per scene with fields merged from all moments
 
-The generated server is immediately runnable and provides a foundation for domain-driven development.
+The generated server is immediately runnable after dependency installation.
 
 ---
 
@@ -31,11 +26,11 @@ The generated server is immediately runnable and provides a foundation for domai
 pnpm add @auto-engineer/server-generator-nestjs
 ```
 
-## Quick Start
+---
 
-This package generates NestJS servers from domain models. Here is how to use it.
+## Quick Start
 
-### 1. Register the handlers
+### 1. Register the command handler
 
 ```typescript
 import { COMMANDS } from "@auto-engineer/server-generator-nestjs";
@@ -45,22 +40,33 @@ const bus = createMessageBus();
 COMMANDS.forEach((cmd) => bus.register(cmd));
 ```
 
-### 2. Send a command
+### 2. Send the GenerateServer command
 
 ```typescript
-const result = await bus.send({
+import type { Model } from "@auto-engineer/narrative";
+
+const model: Model = {
+  scenes: [
+    /* ... */
+  ],
+  messages: [
+    /* ... */
+  ],
+};
+
+const events = await bus.send({
   type: "GenerateServer",
   data: {
-    modelPath: ".context/model.json",
+    model,
     destination: ".",
   },
+  requestId: "req-1",
 });
 
-console.log(result);
-// → { type: 'ServerGenerated', data: { serverDir: './server', ... } }
+// events is an array: MomentGenerated[] followed by ServerGenerated or ServerGenerationFailed
 ```
 
-The command reads your model file, generates a complete NestJS server in the `server/` directory, and installs dependencies automatically.
+The command generates a complete NestJS server in `<destination>/server/`, writes the model to `<destination>/.context/schema.json`, and runs `pnpm install`.
 
 ---
 
@@ -69,59 +75,90 @@ The command reads your model file, generates a complete NestJS server in the `se
 ### Run via CLI
 
 ```bash
-auto generate:server --model-path=.context/model.json --destination=.
+auto generate:server --destination=.
 ```
 
-### Run Programmatically
+### Run programmatically
 
 ```typescript
 import { commandHandler } from "@auto-engineer/server-generator-nestjs";
 
-const result = await commandHandler.handle({
+const events = await commandHandler.handle({
   type: "GenerateServer",
   data: {
-    modelPath: ".context/model.json",
+    model: myModel,
     destination: "/path/to/project",
   },
   requestId: "req-123",
+  correlationId: "corr-456",
 });
 ```
 
-### Handle Errors
+### Track per-moment progress
+
+The handler returns an array of events. A `MomentGenerated` event is emitted for each non-experience moment processed:
 
 ```typescript
-if (result.type === "ServerGenerationFailed") {
-  console.error(result.data.error);
+for (const event of events) {
+  if (event.type === "MomentGenerated") {
+    console.log(
+      `Generated: ${event.data.sceneName}.${event.data.momentName} (${event.data.momentType})`
+    );
+  }
 }
 ```
 
-### Handle Per-Slice Progress
-
-The handler emits `SliceGeneratedEvent` for each domain slice processed:
+### Handle errors
 
 ```typescript
-const events = await commandHandler.handle(command);
-
-for (const event of events) {
-  if (event.type === "SliceGenerated") {
-    console.log(`Generated: ${event.data.flowName}.${event.data.sliceName}`);
-  }
+const lastEvent = events[events.length - 1];
+if (lastEvent.type === "ServerGenerationFailed") {
+  console.error(lastEvent.data.error);
+  // lastEvent.data.model contains the original model for debugging
 }
 ```
 
-### Enable Debug Logging
+### Skip dependency installation
+
+Set the `DEPS_PRE_WARMED` environment variable to skip `pnpm install` in the generated server:
+
+```bash
+DEPS_PRE_WARMED=true auto generate:server --destination=.
+```
+
+### Enable debug logging
 
 ```bash
-DEBUG=auto:server-generator-nestjs:* pnpm auto generate:server
+DEBUG=auto:server-generator-nestjs:* auto generate:server --destination=.
 ```
 
 Available debug namespaces:
 
-- `auto:server-generator-nestjs` - General operation logging
-- `auto:server-generator-nestjs:schema` - Model parsing details
-- `auto:server-generator-nestjs:files` - File copy operations
-- `auto:server-generator-nestjs:deps` - Dependency installation
-- `auto:server-generator-nestjs:scaffold` - Scaffold generation
+- `auto:server-generator-nestjs` -- General operation logging
+- `auto:server-generator-nestjs:files` -- File copy operations
+- `auto:server-generator-nestjs:deps` -- Dependency installation
+- `auto:server-generator-nestjs:scaffold` -- Scaffold generation and template rendering
+- `auto:server-generator-nestjs:entity` -- Entity consolidation
+- `auto:server-generator-nestjs:extract:messages` -- Message extraction from specs
+
+### Use the scaffold functions directly
+
+```typescript
+import {
+  generateScaffoldFilePlans,
+  writeScaffoldFilePlans,
+} from "@auto-engineer/server-generator-nestjs/codegen/scaffoldFromSchema";
+
+const filePlans = await generateScaffoldFilePlans(
+  model.scenes,
+  model.messages,
+  model.integrations,
+  "src/domain"
+);
+
+// Each plan has { outputPath: string, contents: string }
+await writeScaffoldFilePlans(filePlans);
+```
 
 ---
 
@@ -137,60 +174,61 @@ import type {
   GenerateServerEvents,
   ServerGeneratedEvent,
   ServerGenerationFailedEvent,
-  SliceGeneratedEvent,
+  MomentGeneratedEvent,
 } from "@auto-engineer/server-generator-nestjs";
 ```
 
 ### Commands
 
-| Command          | CLI Alias         | Description                       |
-| ---------------- | ----------------- | --------------------------------- |
-| `GenerateServer` | `generate:server` | Generate NestJS server from model |
+| Command          | CLI Alias         | Category   | Description                |
+| ---------------- | ----------------- | ---------- | -------------------------- |
+| `GenerateServer` | `generate:server` | `generate` | Generate server from model |
 
 ### Command Fields
 
-| Field         | Type     | Required | Description                                |
-| ------------- | -------- | -------- | ------------------------------------------ |
-| `modelPath`   | `string` | Yes      | Path to the JSON model file                |
-| `destination` | `string` | Yes      | Destination directory for generated server |
+| Field         | Type    | Required | Description                                |
+| ------------- | ------- | -------- | ------------------------------------------ |
+| `model`       | `Model` | Yes      | The narrative model object                 |
+| `destination` | `string` | Yes     | Destination directory for generated server |
 
 ### Events
 
-| Event                         | Description                      |
-| ----------------------------- | -------------------------------- |
-| `ServerGeneratedEvent`        | Emitted on successful generation |
-| `ServerGenerationFailedEvent` | Emitted when generation fails    |
-| `SliceGeneratedEvent`         | Emitted for each slice processed |
+| Event                     | When Emitted                             |
+| ------------------------- | ---------------------------------------- |
+| `MomentGenerated`         | For each non-experience moment processed |
+| `ServerGenerated`         | On successful generation (final event)   |
+| `ServerGenerationFailed`  | On failure (final event)                 |
 
-### ServerGeneratedEvent Data
+### MomentGeneratedEvent Data
 
 ```typescript
 {
-  modelPath: string;
-  destination: string;
-  serverDir: string;
+  sceneName: string;    // Name of the scene
+  momentName: string;   // Name of the moment
+  momentType: string;   // "command" | "query" | "react"
+  schemaPath: string;   // Path to the written schema.json
+  momentPath: string;   // Relative path to the generated moment directory
 }
 ```
 
-### ServerGenerationFailedEvent Data
+### ServerGeneratedEvent Data
 
 ```typescript
 {
-  modelPath: string;
-  destination: string;
-  error: string;
+  modelPath: string;    // Path to the written schema.json
+  destination: string;  // The destination directory
+  serverDir: string;    // Absolute path to the generated server/ directory
 }
 ```
 
-### SliceGeneratedEvent Data
+### ServerGenerationFailedEvent Data
 
 ```typescript
 {
-  flowName: string;
-  sliceName: string;
-  sliceType: string;
-  schemaPath: string;
-  slicePath: string;
+  modelPath: string;    // Path to the written schema.json
+  destination: string;  // The destination directory
+  error: string;        // Error message or stack trace
+  model: Model;         // The original model (for debugging)
 }
 ```
 
@@ -200,37 +238,61 @@ import type {
 
 ```
 src/
-├── index.ts                    # Package entry point (exports COMMANDS)
+├── index.ts                    # Package entry: exports COMMANDS array and types
 ├── commands/
-│   └── generate-server.ts      # Main command handler
+│   └── generate-server.ts      # GenerateServer command handler
 ├── codegen/
-│   ├── scaffoldFromSchema.ts   # Scaffold orchestrator
-│   ├── entity-consolidation.ts # Entity field merging
-│   ├── types.ts                # Core type definitions
-│   ├── extract/                # Message/GWT extraction
-│   │   ├── commands.ts         # Command extraction
-│   │   ├── events.ts           # Event extraction
-│   │   ├── states.ts           # State extraction
-│   │   ├── fields.ts           # Field extraction
-│   │   ├── gwt.ts              # GWT mapping builders
-│   │   ├── graphql.ts          # GraphQL query parsing
-│   │   └── imports.ts          # Cross-slice imports
-│   ├── templates/              # EJS templates
-│   │   ├── command/            # Command slice templates
-│   │   ├── query/              # Query slice templates
-│   │   ├── entity/             # Entity templates
-│   │   └── module/             # NestJS module templates
+│   ├── scaffoldFromSchema.ts   # Scaffold orchestrator: scenes → file plans
+│   ├── entity-consolidation.ts # Merges fields from all moments into one entity per scene
+│   ├── types.ts                # Message, Field, MessageDefinition, GwtCondition
+│   ├── extract/                # Extracts typed messages from moment specs
+│   │   ├── commands.ts         # Command extraction from GWT when/then
+│   │   ├── events.ts           # Event extraction from GWT given/then/when
+│   │   ├── states.ts           # State extraction from data targets
+│   │   ├── fields.ts           # Field extraction from message definitions
+│   │   ├── gwt.ts              # GWT mapping builders for commands
+│   │   ├── query.ts            # GWT mapping builders for queries
+│   │   ├── messages.ts         # Dispatcher: routes extraction by moment type
+│   │   ├── imports.ts          # Cross-moment import path grouping
+│   │   ├── projection.ts       # Projection name/idField/singleton extraction
+│   │   ├── data-sink.ts        # Stream pattern extraction from data sinks
+│   │   ├── step-converter.ts   # Spec examples → GWT results
+│   │   ├── step-types.ts       # Step type guards and interfaces
+│   │   └── type-helpers.ts     # GraphQL/TS type conversion, enum detection
+│   ├── templates/              # EJS templates for code generation
+│   │   ├── command/            # command.ts, input.ts, handler.ts, resolver.ts, handler.specs.ts
+│   │   ├── query/              # query.ts, type.ts, handler.ts, resolver.ts
+│   │   ├── entity/             # entity.ts, index.ts
+│   │   └── module/             # domain-module.ts, app-module.ts
 │   └── utils/
-│       └── path.ts             # Path utilities
-└── shared/                     # Files copied to generated server
-    ├── main.ts                 # NestJS bootstrap
-    ├── mikro-orm.config.ts     # Database configuration
-    └── graphql-types.ts        # Shared GraphQL types
+│       └── path.ts             # toKebabCase, ensureDirExists, ensureDirPath
+└── shared/                     # Files copied into the generated server
+    ├── main.ts                 # NestJS bootstrap (port from PORT env or 4000)
+    ├── mikro-orm.config.ts     # SQLite config (:memory: for test, ./db.sqlite otherwise)
+    └── graphql-types.ts        # MutationResponse and MutationError GraphQL types
 ```
 
-### Generated Server Structure
+### Generation Pipeline
+
+```mermaid
+flowchart TD
+    A[GenerateServer command] --> B[Write model to .context/schema.json]
+    B --> C[Clear and create server/ directory]
+    C --> D[Copy shared files: main.ts, mikro-orm.config.ts, graphql-types.ts]
+    D --> E[Generate scaffold from model]
+    E --> F[Extract enums from message definitions]
+    F --> G[For each scene]
+    G --> H[Consolidate entity fields from all moments]
+    H --> I[Generate entity files]
+    I --> J[For each moment: render EJS templates]
+    J --> K[Generate domain module per scene]
+    K --> L[Generate app module]
+    L --> M[Write config: package.json, tsconfig.json, vitest.config.ts, .gitignore]
+    M --> N[pnpm install]
+    N --> O[Emit ServerGenerated event]
+```
 
-The command generates the following structure:
+### Generated Server Structure
 
 ```
 server/
@@ -238,52 +300,50 @@ server/
 ├── tsconfig.json
 ├── vitest.config.ts
 ├── mikro-orm.config.ts
+├── .gitignore
 └── src/
     ├── main.ts
+    ├── app.module.ts
     └── domain/
         ├── shared/
         │   └── graphql-types.ts
-        ├── {flow-name}/
-        │   ├── {slice-name}/
-        │   │   ├── command.ts
-        │   │   ├── input.ts
-        │   │   ├── handler.ts
-        │   │   ├── handler.specs.ts
-        │   │   └── resolver.ts
-        │   └── entities/
-        │       └── {entity}.entity.ts
-        └── {flow-name}.module.ts
+        └── {scene-name}/
+            ├── {scene-name}.module.ts
+            ├── entities/
+            │   ├── {scene-name}-entity.entity.ts
+            │   ├── index.ts
+            │   └── {enum-name}.enum.ts          # if string literal unions exist
+            ├── {command-moment}/
+            │   ├── {moment-name}.command.ts
+            │   ├── {moment-name}.input.ts
+            │   ├── {moment-name}.handler.ts
+            │   ├── {moment-name}.handler.specs.ts
+            │   └── {moment-name}.resolver.ts
+            └── {query-moment}/
+                ├── {moment-name}.query.ts
+                ├── {moment-name}.type.ts
+                ├── {moment-name}.handler.ts
+                └── {moment-name}.resolver.ts
 ```
 
 ### Dependencies
 
 **Monorepo:**
 
-| Package                    | Usage                         |
-| -------------------------- | ----------------------------- |
-| `@auto-engineer/narrative` | Domain model type definitions |
-
-**External:**
-
-| Package             | Usage                       |
-| ------------------- | --------------------------- |
-| `@nestjs/cqrs`      | CQRS command/query pattern  |
-| `@nestjs/graphql`   | GraphQL schema generation   |
-| `@nestjs/apollo`    | Apollo Server integration   |
-| `@mikro-orm/core`   | ORM for entity persistence  |
-| `@mikro-orm/sqlite` | SQLite database driver      |
-| `ejs`               | Template rendering engine   |
-| `prettier`          | Generated code formatting   |
-| `change-case`       | Naming convention utilities |
-| `execa`             | Dependency installation     |
-
----
-
-## Known Limitations
-
-This generator is experimental. Current limitations include:
-
-- Schema extraction is incomplete for complex slice types
-- Generated code may require manual fixes
-- Test coverage is minimal
-- Only SQLite persistence is supported
+| Package                    | Usage                                        |
+| -------------------------- | -------------------------------------------- |
+| `@auto-engineer/narrative` | Model, Scene, Moment, and Spec type definitions |
+| `@auto-engineer/cli`       | Dev dependency for CLI integration           |
+
+**Key External:**
+
+| Package             | Usage                                   |
+| ------------------- | --------------------------------------- |
+| `ejs`               | Template rendering for code generation  |
+| `prettier`          | Formatting all generated TypeScript     |
+| `change-case`       | PascalCase/camelCase/kebab-case naming  |
+| `execa`             | Running `pnpm install` in generated dir |
+| `fs-extra`          | File copy and JSON read/write           |
+| `@nestjs/*`         | Used in generated server runtime        |
+| `@mikro-orm/*`      | Used in generated server runtime        |
+| `@apollo/server`    | Used in generated server runtime        |

package/package.json

@@ -40,7 +40,7 @@
     "ts-node": "^10.9.2",
     "type-fest": "^4.41.0",
     "uuid": "^11.0.0",
-    "@auto-engineer/narrative": "1.148.0"
+    "@auto-engineer/narrative": "1.150.0"
   },
   "publishConfig": {
     "access": "public"
@@ -52,9 +52,9 @@
     "tsx": "^4.19.2",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@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",
     "-DISABLE-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 -r src/shared dist/src",