@auto-engineer/message-bus 1.148.0 → 1.150.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/message-bus@1.148.0 build /home/runner/work/auto-engineer/auto-engineer/packages/message-bus
+> @auto-engineer/message-bus@1.150.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.147.0 test /home/runner/work/auto-engineer/auto-engineer/packages/message-bus
+> @auto-engineer/message-bus@1.149.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  21:35:27
-   Duration  1.24s (transform 339ms, setup 0ms, collect 438ms, tests 32ms, environment 0ms, prepare 285ms)
+   Start at  12:20:32
+   Duration  2.18s (transform 452ms, setup 0ms, collect 521ms, tests 55ms, environment 0ms, prepare 638ms)
 

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

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

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @auto-engineer/message-bus
 
+## 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
+
+## 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

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.148.0",
+  "version": "1.150.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "clean": "rm -rf dist",