@auto-engineer/server-implementer 1.147.0 → 1.149.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/server-implementer@1.147.0 build /home/runner/work/auto-engineer/auto-engineer/packages/server-implementer
+> @auto-engineer/server-implementer@1.149.0 build /home/runner/work/auto-engineer/auto-engineer/packages/server-implementer
 > tsc && tsx ../../scripts/fix-esm-imports.ts
 
 Fixed ESM imports in dist/

package/.turbo/turbo-test.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/server-implementer@1.146.0 test /home/runner/work/auto-engineer/auto-engineer/packages/server-implementer
+> @auto-engineer/server-implementer@1.148.0 test /home/runner/work/auto-engineer/auto-engineer/packages/server-implementer
 > vitest run --reporter=dot
 
 
@@ -9,6 +9,6 @@
 
  Test Files  7 passed (7)
       Tests  46 passed (46)
-   Start at  19:12:32
-   Duration  14.26s (transform 1.60s, setup 0ms, collect 26.16s, tests 917ms, environment 2ms, prepare 5.19s)
+   Start at  07:23:14
+   Duration  16.18s (transform 1.91s, setup 0ms, collect 29.68s, tests 1.30s, environment 2ms, prepare 5.72s)
 

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

@@ -1,4 +1,4 @@
 
-> @auto-engineer/server-implementer@1.146.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/server-implementer
+> @auto-engineer/server-implementer@1.148.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/server-implementer
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @auto-engineer/server-implementer
 
+## 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/model-factory@1.149.0
+
+## 1.148.0
+
+### Minor Changes
+
+- [`d5ba3a0`](https://github.com/BeOnAuto/auto-engineer/commit/d5ba3a0e3fb0f6a9ad7a3a8b1815590ea77a5b42) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added state context instruction to generated decide handlers, preventing unnecessary narrowing when Given steps contain only state references
+
+- [`e0cdc4e`](https://github.com/BeOnAuto/auto-engineer/commit/e0cdc4e3363ad84d4bc49996a600ac75c97ccc38) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added context-aware classification of non-command fields in generated decide.ts scaffolds, distinguishing between date-derived, state-derived, and not-yet-tested fields
+
+- [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Extracted shared template helpers into a dedicated module for cleaner code generation
+
+- [`abb6540`](https://github.com/BeOnAuto/auto-engineer/commit/abb6540db7196ed7935c8a8610695828f9035fc3) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added status variant hints from Given state references to the state template, helping implementers create matching discriminated union variants
+
+- [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Extracted shared template helper functions into a dedicated module for better code reuse across generators
+  - Simplified template specs by removing inline duplicate definitions in favor of the shared helpers
+
+### Patch Changes
+
+- [`88fb1da`](https://github.com/BeOnAuto/auto-engineer/commit/88fb1da2b222de04dd4959d87657395ee960a6ce) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **server-generator-apollo-emmett**: skip empty file plans in scaffold output
+  - **server-generator-apollo-emmett**: filter state refs from given() in decide.specs.ts.ejs
+  - **server-generator-apollo-emmett**: move CS Given states from events to states array
+  - **global**: version packages
+  - **server-generator-apollo-emmett**: mark G1+G2 ketchup plan complete
+
+- [`4255f6d`](https://github.com/BeOnAuto/auto-engineer/commit/4255f6db0d128979e573244a615886482ce799b0) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Updated ketchup plan for state reference fix in decide template generator
+  - Marked generator bug fix milestones G1 and G2 as complete
+
+- [`62f1ea3`](https://github.com/BeOnAuto/auto-engineer/commit/62f1ea3dd1b4275211574e3df9d9a6571ae9b27a) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Fixed scaffold generation to correctly distinguish between event and state references in decision handlers
+  - Prevented contradictory instructions from appearing in generated code when Given clauses contain only state references
+
+- [`ba4f5c9`](https://github.com/BeOnAuto/auto-engineer/commit/ba4f5c9749fb1c15d444e78ca9a2689817f039cb) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added implementation plan for decide.ts code generation fixes in the Apollo Emmett server generator
+
+- Updated dependencies [[`88fb1da`](https://github.com/BeOnAuto/auto-engineer/commit/88fb1da2b222de04dd4959d87657395ee960a6ce), [`d5ba3a0`](https://github.com/BeOnAuto/auto-engineer/commit/d5ba3a0e3fb0f6a9ad7a3a8b1815590ea77a5b42), [`e0cdc4e`](https://github.com/BeOnAuto/auto-engineer/commit/e0cdc4e3363ad84d4bc49996a600ac75c97ccc38), [`4255f6d`](https://github.com/BeOnAuto/auto-engineer/commit/4255f6db0d128979e573244a615886482ce799b0), [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde), [`abb6540`](https://github.com/BeOnAuto/auto-engineer/commit/abb6540db7196ed7935c8a8610695828f9035fc3), [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde), [`62f1ea3`](https://github.com/BeOnAuto/auto-engineer/commit/62f1ea3dd1b4275211574e3df9d9a6571ae9b27a), [`ba4f5c9`](https://github.com/BeOnAuto/auto-engineer/commit/ba4f5c9749fb1c15d444e78ca9a2689817f039cb)]:
+  - @auto-engineer/message-bus@1.148.0
+  - @auto-engineer/model-factory@1.148.0
+
 ## 1.147.0
 
 ### Minor Changes

package/README.md

@@ -6,9 +6,9 @@ AI-powered code implementation that completes TODO-marked TypeScript files in ev
 
 ## Purpose
 
-Without `@auto-engineer/server-implementer`, you would have to manually implement scaffolded TypeScript code, run tests, interpret errors, and iterate on fixes by hand.
+Without `@auto-engineer/server-implementer`, you would have to manually implement scaffolded TypeScript code in CQRS/event-sourced servers, run tests, interpret errors, and iterate on fixes by hand.
 
-This package automates the implementation of scaffolded CQRS/event-sourced server code. It identifies files with TODO markers, generates implementations using AI, validates with TypeScript and Vitest, and retries with error feedback until tests pass.
+This package automates that loop. It scans a server project for files containing TODO markers or `IMPLEMENTATION INSTRUCTIONS`, generates implementations using an LLM, validates the output with TypeScript type-checking and Vitest, and retries with error feedback until tests pass -- up to 5 attempts per file.
 
 ---
 
@@ -18,9 +18,9 @@ This package automates the implementation of scaffolded CQRS/event-sourced serve
 pnpm add @auto-engineer/server-implementer
 ```
 
-## Quick Start
+---
 
-Register the handler and implement server code:
+## Quick Start
 
 ### 1. Register the handlers
 
@@ -32,7 +32,7 @@ const bus = createMessageBus();
 COMMANDS.forEach(cmd => bus.registerCommand(cmd));
 ```
 
-### 2. Send a command
+### 2. Implement an entire server
 
 ```typescript
 const result = await bus.dispatch({
@@ -43,11 +43,28 @@ const result = await bus.dispatch({
   requestId: 'req-123',
 });
 
-console.log(result);
-// → { type: 'ServerImplemented', data: { serverDirectory: './server' } }
+if (result.type === 'ServerImplemented') {
+  console.log('Done:', result.data.scenesImplemented, 'scenes processed');
+}
 ```
 
-The command processes all flows in `src/domain/narratives/` and implements TODO-marked files.
+The command walks all scene directories under `src/domain/narratives/` and implements every slice it finds.
+
+### 3. Implement a single slice
+
+```typescript
+const result = await bus.dispatch({
+  type: 'ImplementMoment',
+  data: {
+    momentPath: './server/src/domain/narratives/order/place-order',
+  },
+  requestId: 'req-456',
+});
+
+if (result.type === 'MomentImplemented') {
+  console.log('Files implemented:', result.data.filesImplemented);
+}
+```
 
 ---
 
@@ -57,58 +74,74 @@ The command processes all flows in `src/domain/narratives/` and implements TODO-
 
 ```bash
 auto implement:server --server-directory=./server
-auto implement:slice --slice-path=./server/src/domain/narratives/order/place-order
+auto implement:slice --moment-path=./server/src/domain/narratives/order/place-order
 ```
 
-### Run Programmatically
+### Run programmatically (without the bus)
 
 ```typescript
-import { handleImplementSliceCommand } from '@auto-engineer/server-implementer';
+import { handleImplementMomentCommand } from '@auto-engineer/server-implementer';
 
-const result = await handleImplementSliceCommand({
-  type: 'ImplementSlice',
+const result = await handleImplementMomentCommand({
+  type: 'ImplementMoment',
   data: {
-    slicePath: './server/src/domain/narratives/order/place-order',
+    momentPath: './server/src/domain/narratives/order/place-order',
     aiOptions: { maxTokens: 4000 },
   },
-  requestId: 'req-123',
+  requestId: 'req-789',
 });
 ```
 
-### Retry with Previous Errors
+### Retry with previous errors
+
+When an implementation attempt fails, pass the error output back as context so the next attempt can learn from it:
 
 ```typescript
-const retryResult = await handleImplementSliceCommand({
-  type: 'ImplementSlice',
+const retryResult = await handleImplementMomentCommand({
+  type: 'ImplementMoment',
   data: {
-    slicePath: './server/src/domain/narratives/order/place-order',
+    momentPath: './server/src/domain/narratives/order/place-order',
     context: {
       previousOutputs: 'TypeError: Property "status" is missing...',
       attemptNumber: 2,
     },
   },
-  requestId: 'req-124',
+  requestId: 'req-790',
 });
 ```
 
-### Handle Errors
+### Handle errors
 
 ```typescript
 if (result.type === 'ServerImplementationFailed') {
   console.error(result.data.error);
 }
 
-if (result.type === 'SliceImplementationFailed') {
+if (result.type === 'MomentImplementationFailed') {
   console.error(result.data.error);
 }
 ```
 
-### Enable Debug Logging
+### Enable debug logging
 
 ```bash
 DEBUG=auto:server-implementer:* auto implement:server --server-directory=./server
 ```
 
+Namespaces available:
+
+| Namespace | What it logs |
+|-----------|-------------|
+| `auto:server-implementer:command` | Top-level command lifecycle |
+| `auto:server-implementer:command:handler` | Path resolution and validation |
+| `auto:server-implementer:command:process` | Scene runner progress |
+| `auto:server-implementer:command:result` | Final outcome |
+| `auto:server-implementer:slice` | Single-slice command lifecycle |
+| `auto:server-implementer:slice:handler` | Slice path resolution |
+| `auto:server-implementer:slice:process` | Per-file AI generation and retries |
+| `auto:server-implementer:slice:result` | Slice outcome |
+| `auto:server-implementer:scenes` | Scene directory discovery |
+
 ---
 
 ## API Reference
@@ -119,17 +152,19 @@ DEBUG=auto:server-implementer:* auto implement:server --server-directory=./serve
 import {
   COMMANDS,
   implementServerHandler,
-  implementSliceHandler,
-  handleImplementSliceCommand,
+  implementMomentHandler,
+  handleImplementMomentCommand,
 } from '@auto-engineer/server-implementer';
 
 import type {
   ImplementServerCommand,
+  ImplementServerEvents,
   ServerImplementedEvent,
   ServerImplementationFailedEvent,
-  ImplementSliceCommand,
-  SliceImplementedEvent,
-  SliceImplementationFailedEvent,
+  ImplementMomentCommand,
+  ImplementMomentEvents,
+  MomentImplementedEvent,
+  MomentImplementationFailedEvent,
 } from '@auto-engineer/server-implementer';
 ```
 
@@ -137,8 +172,8 @@ import type {
 
 | Command | CLI Alias | Description |
 |---------|-----------|-------------|
-| `ImplementServer` | `implement:server` | Implement all flows in server project |
-| `ImplementSlice` | `implement:slice` | Implement single slice directory |
+| `ImplementServer` | `implement:server` | Implement all scenes and slices in a server project |
+| `ImplementMoment` | `implement:slice` | Implement a single slice directory |
 
 ### ImplementServerCommand
 
@@ -151,13 +186,18 @@ type ImplementServerCommand = Command<
 >;
 ```
 
-### ImplementSliceCommand
+**Events:**
+
+- `ServerImplemented` -- `{ serverDirectory: string; scenesImplemented: number }`
+- `ServerImplementationFailed` -- `{ serverDirectory: string; error: string }`
+
+### ImplementMomentCommand
 
 ```typescript
-type ImplementSliceCommand = Command<
-  'ImplementSlice',
+type ImplementMomentCommand = Command<
+  'ImplementMoment',
   {
-    slicePath: string;
+    momentPath: string;
     context?: {
       previousOutputs?: string;
       attemptNumber?: number;
@@ -169,17 +209,10 @@ type ImplementSliceCommand = Command<
 >;
 ```
 
-### SliceImplementedEvent
+**Events:**
 
-```typescript
-type SliceImplementedEvent = Event<
-  'SliceImplemented',
-  {
-    slicePath: string;
-    filesImplemented: string[];
-  }
->;
-```
+- `MomentImplemented` -- `{ momentPath: string; filesImplemented: string[] }`
+- `MomentImplementationFailed` -- `{ momentPath: string; error: string }`
 
 ---
 
@@ -187,52 +220,74 @@ type SliceImplementedEvent = Event<
 
 ```
 src/
-├── index.ts
+├── index.ts                  # COMMANDS array, re-exports
 ├── commands/
-│   ├── implement-server.ts
-│   └── implement-slice.ts
+│   ├── implement-server.ts   # ImplementServer command handler
+│   └── implement-slice.ts    # ImplementMoment command handler
 ├── agent/
-│   ├── runFlows.ts
-│   ├── runAllSlices.ts
-│   ├── runSlice.ts
-│   └── runTests.ts
+│   ├── runFlows.ts           # Discovers and iterates scene directories
+│   ├── runAllSlices.ts       # Iterates moment directories within a scene
+│   ├── runSlice.ts           # Per-slice: AI generate, test, typecheck, retry
+│   └── runTests.ts           # Vitest runner with JSON report parsing
 ├── prompts/
-│   └── systemPrompt.ts
+│   └── systemPrompt.ts       # System prompt for AI code generation
 └── utils/
-    └── extractCodeBlock.ts
+    ├── buildContextSections.ts          # Formats context files into prompt sections
+    ├── detectImportedTypeShadowing.ts   # Detects re-declared imported types
+    ├── detectTypeAssertions.ts          # Detects forbidden `as` casts
+    ├── extractCodeBlock.ts              # Strips markdown fences from AI output
+    ├── findFilesToImplement.ts          # Filters + priority-sorts TODO-marked files
+    ├── loadContextFiles.ts              # Loads all .ts files in a slice directory
+    └── loadSharedContext.ts             # Loads shared domain types from ../../../shared
 ```
 
-The following diagram shows the implementation flow:
+### Implementation flow
 
 ```mermaid
 flowchart TB
-    A[ImplementSlice] --> B[Load Slice Files]
-    B --> C[Find TODO Markers]
-    C --> D[Generate via AI]
-    D --> E[Write File]
-    E --> F[Run Tests + TypeCheck]
-    F --> G{Pass?}
-    G -->|Yes| H[SliceImplementedEvent]
-    G -->|No| I{Retries < 5?}
-    I -->|Yes| J[Build Retry Prompt]
-    J --> D
-    I -->|No| K[SliceImplementationFailedEvent]
+    A[ImplementServer command] --> B[Discover scenes in src/domain/narratives/]
+    B --> C[For each scene: discover slices]
+    C --> D[For each slice: load context files]
+    D --> E[Find files with TODO markers]
+    E --> F[Generate implementation via AI]
+    F --> G[Write generated code to disk]
+    G --> H[Run Vitest + tsc --noEmit]
+    H --> I{Pass?}
+    I -->|Yes| J[Done]
+    I -->|No| K{Retries left?}
+    K -->|Yes| L[Build retry prompt with errors]
+    L --> F
+    K -->|No| M[Report remaining failures]
 ```
 
-*Flow: Command loads files, identifies TODOs, generates via AI, validates, retries up to 5 times on failure.*
+### Validation checks
+
+Each implementation pass runs three checks before accepting the output:
+
+1. **Vitest** -- runs spec files in the slice, parses JSON report for failures
+2. **TypeScript** -- `tsc --noEmit` filtered to errors in the slice directory
+3. **Static analysis** -- detects imported-type shadowing and forbidden `as` type assertions
+
+Files that fail typecheck are retried up to 5 times. Files that fail tests are retried separately, also up to 5 times. If a test fix introduces a type error, a nested typecheck retry loop runs (max depth 2).
+
+### Implementation priority
+
+When multiple files need implementation, they are processed in this order: `state.ts`, `events.ts`, `commands.ts`, `evolve.ts`, `decide.ts`, then alphabetically.
+
+### Implementation markers
 
-### Implementation Markers
+Files are identified for AI implementation by the presence of any of:
 
-Files are identified for processing by:
 - `// @auto-implement` comment
-- `TODO:` comments
+- `TODO:` comment
 - `IMPLEMENTATION INSTRUCTIONS` text
 
 ### Dependencies
 
 | Package | Usage |
 |---------|-------|
-| `@auto-engineer/ai-gateway` | AI text generation |
-| `@auto-engineer/message-bus` | Command/event infrastructure |
-| `fast-glob` | File discovery |
-| `debug` | Debug logging |
+| `@auto-engineer/model-factory` | Creates the AI model instance from environment config |
+| `@auto-engineer/message-bus` | Command/event handler infrastructure |
+| `ai` (Vercel AI SDK) | `generateText` for LLM calls |
+| `fast-glob` | File and directory discovery |
+| `debug` | Namespaced debug logging |

package/package.json

@@ -18,8 +18,8 @@
     "debug": "^4.3.4",
     "fast-glob": "^3.3.3",
     "vite": "^5.4.1",
-    "@auto-engineer/model-factory": "1.147.0",
-    "@auto-engineer/message-bus": "1.147.0"
+    "@auto-engineer/model-factory": "1.149.0",
+    "@auto-engineer/message-bus": "1.149.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
@@ -29,9 +29,9 @@
     "glob": "^11.0.3",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
-    "@auto-engineer/cli": "1.147.0"
+    "@auto-engineer/cli": "1.149.0"
   },
-  "version": "1.147.0",
+  "version": "1.149.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "test": "vitest run --reporter=dot",