@auto-engineer/message-bus 1.147.0 → 1.149.0

package/.turbo/turbo-build.log

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

package/.turbo/turbo-test.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/message-bus@1.146.0 test /home/runner/work/auto-engineer/auto-engineer/packages/message-bus
+> @auto-engineer/message-bus@1.148.0 test /home/runner/work/auto-engineer/auto-engineer/packages/message-bus
 > vitest run --reporter=dot
 
 
@@ -9,6 +9,6 @@
 
  Test Files  1 passed (1)
       Tests  7 passed (7)
-   Start at  19:11:22
-   Duration  2.14s (transform 574ms, setup 0ms, collect 607ms, tests 40ms, environment 0ms, prepare 603ms)
+   Start at  07:22:17
+   Duration  1.92s (transform 441ms, setup 0ms, collect 484ms, tests 40ms, environment 0ms, prepare 609ms)
 

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

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

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @auto-engineer/message-bus
 
+## 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)! -
+
+## 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
+
 ## 1.147.0
 
 ### Minor Changes

package/README.md

@@ -8,7 +8,15 @@ Type-safe message bus implementing the CQRS pattern with command handling and ev
 
 Without `@auto-engineer/message-bus`, you would have to implement your own command/event routing, handle handler registration, manage request/correlation ID propagation, and ensure proper error isolation between handlers.
 
-This package provides the core messaging infrastructure for the Auto Engineer ecosystem. It enables decoupled communication through commands (write operations) and events (state changes) with robust debugging support.
+This package provides the core messaging infrastructure for the Auto Engineer ecosystem. It enables decoupled communication through commands (write operations) and events (state changes). Commands have exactly one handler; events fan out to many subscribers. Correlation IDs flow automatically from commands to their resulting events, enabling end-to-end traceability.
+
+## Key Concepts
+
+- **One handler per command type** -- ensures deterministic command processing. Registering a second handler for the same command throws.
+- **Multiple handlers per event type** -- enables fan-out notification. Handlers run concurrently via `Promise.allSettled`, so one failure does not block others.
+- **Request/Correlation ID propagation** -- when a command handler returns events, the bus copies `requestId` and `correlationId` from the command onto each event (unless the event already carries its own).
+- **Correlation listeners** -- subscribe to events by exact `correlationId` or by prefix, useful for tracking the progress of a specific workflow or job graph.
+- **`defineCommandHandler`** -- a factory that attaches CLI metadata (alias, description, fields, examples) to a command handler, so the same object can drive both the message bus and a CLI interface.
 
 ---
 
@@ -22,17 +30,23 @@ pnpm add @auto-engineer/message-bus
 
 ```typescript
 import { createMessageBus, defineCommandHandler } from '@auto-engineer/message-bus';
+import type { Command, Event } from '@auto-engineer/message-bus';
 
+// 1. Create the bus
 const bus = createMessageBus();
 
-const handler = defineCommandHandler({
+// 2. Define and register a command handler
+type CreateUser = Command<'CreateUser', { name: string }>;
+type UserCreated = Event<'UserCreated', { userId: string; name: string }>;
+
+const handler = defineCommandHandler<CreateUser, (cmd: CreateUser) => Promise<UserCreated>>({
   name: 'CreateUser',
   alias: 'create-user',
   description: 'Creates a new user',
   fields: {
-    name: { description: 'User name', required: true },
+    name: { description: 'User name' },
   },
-  examples: [],
+  examples: ['create-user --name John'],
   events: ['UserCreated'],
   handle: async (cmd) => ({
     type: 'UserCreated',
@@ -42,13 +56,20 @@ const handler = defineCommandHandler({
 
 bus.registerCommandHandler(handler);
 
-const result = await bus.sendCommand({
+// 3. Subscribe to the resulting event
+bus.subscribeToEvent('UserCreated', {
+  name: 'UserCreatedLogger',
+  handle: (event) => {
+    console.log('User created:', event.data);
+  },
+});
+
+// 4. Send a command
+await bus.sendCommand({
   type: 'CreateUser',
   data: { name: 'John' },
+  requestId: 'req-001',
 });
-
-console.log(result);
-// → { type: 'UserCreated', data: { userId: 'u-001', name: 'John' } }
 ```
 
 ---
@@ -57,6 +78,8 @@ console.log(result);
 
 ### Register a Command Handler
 
+Use `defineCommandHandler` to create a handler with CLI metadata, then register it on the bus:
+
 ```typescript
 import { createMessageBus, defineCommandHandler } from '@auto-engineer/message-bus';
 
@@ -76,11 +99,14 @@ bus.registerCommandHandler(handler);
 
 ### Send a Command
 
+`sendCommand` finds the registered handler, executes it, and publishes the resulting events:
+
 ```typescript
-const result = await bus.sendCommand({
+await bus.sendCommand({
   type: 'CreateUser',
   data: { name: 'John', email: 'john@example.com' },
   requestId: 'req-123',
+  correlationId: 'signup-flow-1',
 });
 ```
 
@@ -94,6 +120,7 @@ const subscription = bus.subscribeToEvent('UserCreated', {
   },
 });
 
+// Later, stop receiving events
 subscription.unsubscribe();
 ```
 
@@ -108,21 +135,51 @@ const subscription = bus.subscribeAll({
 });
 ```
 
-### Return Multiple Events
+### Return Multiple Events from a Handler
+
+A command handler can return a single event or an array:
 
 ```typescript
 const handler = defineCommandHandler({
   name: 'BatchCreate',
-  // ...
+  alias: 'batch-create',
+  description: 'Creates multiple items',
+  fields: {},
+  examples: [],
+  events: ['ItemCreated'],
   handle: async (cmd) => {
-    return cmd.data.items.map(item => ({
-      type: 'ItemCreated',
+    return cmd.data.items.map((item: { id: string }) => ({
+      type: 'ItemCreated' as const,
       data: item,
     }));
   },
 });
 ```
 
+### Track Events by Correlation ID
+
+Listen for events tied to a specific correlation ID:
+
+```typescript
+const subscription = bus.onCorrelation('signup-flow-1', (event) => {
+  console.log('Correlated event:', event.type);
+});
+
+subscription.unsubscribe();
+```
+
+### Track Events by Correlation Prefix
+
+Listen for all events whose correlation ID starts with a given prefix. Useful for job graphs where each job appends a suffix:
+
+```typescript
+const subscription = bus.onCorrelationPrefix('graph:g1:', (event) => {
+  console.log('Graph event:', event.type, event.correlationId);
+});
+
+subscription.unsubscribe();
+```
+
 ---
 
 ## API Reference
@@ -141,26 +198,67 @@ import type {
   CommandHandler,
   EventHandler,
   EventSubscription,
+  EventDefinition,
   MessageBus,
   UnifiedCommandHandler,
   FieldDefinition,
+  PackageMetadata,
 } from '@auto-engineer/message-bus';
 ```
 
 ### Functions
 
-#### `createMessageBus(): MessageBus`
+#### `createMessageBus()`
+
+```typescript
+function createMessageBus(): MessageBus
+```
+
+Create a new message bus instance with isolated state.
+
+#### `defineCommandHandler(config)`
 
-Create a new message bus instance.
+```typescript
+function defineCommandHandler<C extends Command>(config: {
+  name: string;
+  alias: string;
+  description: string;
+  displayName?: string;
+  category?: string;
+  icon?: string;
+  package?: PackageMetadata;
+  fields: Record<string, FieldDefinition<unknown>>;
+  examples: string[];
+  events: EventDefinition[];
+  handle: (command: C) => Promise<Event | Event[]>;
+}): UnifiedCommandHandler<C>
+```
 
-#### `defineCommandHandler(options): UnifiedCommandHandler`
+Define a command handler with metadata for CLI integration.
 
-Define a command handler with CLI metadata.
+| Parameter | Type | Description |
+|---|---|---|
+| `name` | `string` | Command type string (e.g. `'CreateUser'`) |
+| `alias` | `string` | CLI alias (e.g. `'create-user'`) |
+| `description` | `string` | Human-readable description |
+| `displayName` | `string?` | Optional display name |
+| `category` | `string?` | Optional grouping category |
+| `icon` | `string?` | Optional icon |
+| `package` | `PackageMetadata?` | Source package metadata |
+| `fields` | `Record<string, FieldDefinition>` | Parameter definitions |
+| `examples` | `string[]` | Usage examples |
+| `events` | `EventDefinition[]` | Events this handler may emit |
+| `handle` | `(command) => Promise<Event \| Event[]>` | The handler function |
 
-### Command Type
+### Interfaces
+
+#### `Command<Type, Data>`
 
 ```typescript
-type Command<Type extends string, Data> = Readonly<{
+type Command<
+  Type extends string = string,
+  Data extends Record<string, unknown> = Record<string, unknown>
+> = Readonly<{
   type: Type;
   data: Readonly<Data>;
   timestamp?: Date;
@@ -169,10 +267,13 @@ type Command<Type extends string, Data> = Readonly<{
 }>;
 ```
 
-### Event Type
+#### `Event<Type, Data>`
 
 ```typescript
-type Event<Type extends string, Data> = Readonly<{
+type Event<
+  Type extends string = string,
+  Data extends Record<string, unknown> = Record<string, unknown>
+> = Readonly<{
   type: Type;
   data: Data;
   timestamp?: Date;
@@ -181,51 +282,73 @@ type Event<Type extends string, Data> = Readonly<{
 }>;
 ```
 
-### MessageBus Interface
+#### `CommandHandler`
 
 ```typescript
-interface MessageBus {
-  registerCommandHandler(handler: CommandHandler): void;
-  registerEventHandler(eventType: string, handler: EventHandler): void;
-  sendCommand(command: Command): Promise<Event | Event[]>;
-  publishEvent(event: Event): Promise<void>;
-  subscribeToEvent(eventType: string, handler: EventHandler): EventSubscription;
-  subscribeAll(handler: EventHandler): EventSubscription;
-  getCommandHandlers(): Record<string, CommandHandler>;
-}
+type CommandHandler<TCommand extends Command = Command, TEvent extends Event = Event> = {
+  name: string;
+  handle: (command: TCommand) => Promise<TEvent | TEvent[]>;
+};
 ```
 
+#### `EventHandler`
+
+```typescript
+type EventHandler<TEvent extends Event = Event> = {
+  name: string;
+  handle: (event: TEvent) => Promise<void> | void;
+};
+```
+
+#### `EventSubscription`
+
+```typescript
+type EventSubscription = {
+  unsubscribe: () => void;
+};
+```
+
+### MessageBus Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `registerCommandHandler` | `(handler: CommandHandler) => void` | Register a handler for a command type. Throws if one is already registered. |
+| `sendCommand` | `(command: Command) => Promise<void>` | Dispatch a command to its handler. Resulting events are published automatically. |
+| `publishEvent` | `(event: Event) => Promise<void>` | Publish an event to all matching subscribers. |
+| `subscribeToEvent` | `(eventType: string, handler: EventHandler) => EventSubscription` | Subscribe to a specific event type. |
+| `subscribeAll` | `(handler: EventHandler) => EventSubscription` | Subscribe to all events regardless of type. |
+| `registerEventHandler` | `(handler: EventHandler) => EventSubscription` | Register an event handler, inferring event type from the handler name (strips `Handler` suffix). |
+| `getCommandHandlers` | `() => Record<string, CommandHandler>` | Return a shallow copy of all registered command handlers. |
+| `onCorrelation` | `(correlationId: string, listener: (event: Event) => void) => EventSubscription` | Listen for events with an exact correlation ID match. |
+| `onCorrelationPrefix` | `(prefix: string, listener: (event: Event) => void) => EventSubscription` | Listen for events whose correlation ID starts with the given prefix. |
+
 ---
 
 ## Architecture
 
 ```
 src/
-├── index.ts
-├── message-bus.ts
-├── define-command.ts
-└── types.ts
+├── index.ts              # Re-exports all public API
+├── message-bus.ts         # createMessageBus factory and MessageBus type
+├── define-command.ts      # defineCommandHandler and related types
+├── types.ts               # Core Command, Event, Handler types
+└── message-bus.specs.ts   # Tests for correlation features
 ```
 
-The following diagram shows the message flow:
-
 ```mermaid
 flowchart LR
-    A[sendCommand] --> B[CommandHandler]
-    B --> C[Event]
+    A[sendCommand] --> B[CommandHandler.handle]
+    B --> C[Event / Event array]
     C --> D[publishEvent]
-    D --> E[EventHandlers]
+    D --> E[Event subscribers]
+    D --> F[Correlation listeners]
 ```
 
-*Flow: Command is sent, handler processes it, returns event(s), events are published to subscribers.*
-
-### Key Concepts
-
-- **One handler per command type**: Ensures deterministic command processing
-- **Multiple handlers per event type**: Enables fan-out notification
-- **Request/Correlation ID propagation**: Maintains traceability
-- **Error isolation**: Handler failures don't affect other handlers
-
 ### Dependencies
 
-This package has no dependencies on other `@auto-engineer/*` packages. It is a foundational package used throughout the monorepo.
+| Type | Packages |
+|---|---|
+| Runtime | `debug` (via `createDebug`) |
+| Dev | `typescript`, `tsx`, `@types/node` |
+
+This package has no dependencies on other `@auto-engineer/` packages. It is a foundational package used throughout the monorepo.

package/package.json

@@ -17,7 +17,7 @@
     "tsx": "^4.20.3",
     "typescript": "^5.0.0"
   },
-  "version": "1.147.0",
+  "version": "1.149.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "clean": "rm -rf dist",