---
phase: 01.1-hexagonal-architecture
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [package.json, vitest.config.ts, src/events/types.ts, src/events/bus.ts, src/events/index.ts, src/events/bus.test.ts]
autonomous: true
---

<objective>
Create the event bus foundation - the backbone of the hexagonal architecture.

Purpose: Establish extensible event infrastructure that can be swapped for external systems (RabbitMQ, WebSocket forwarding) later. All modules will communicate through this event bus.
Output: Working event bus with typed domain events and full test coverage.
</objective>

<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01.1-hexagonal-architecture/1.1-CONTEXT.md

@src/index.ts
@src/process/types.ts
@src/logging/types.ts
@src/server/types.ts
@package.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Install and configure Vitest test framework</name>
  <files>package.json, vitest.config.ts</files>
  <action>
    Install vitest as dev dependency: `npm install -D vitest`

    Create vitest.config.ts with:
    - TypeScript support (uses tsconfig.json automatically)
    - Test globals enabled (describe, it, expect without imports)
    - Coverage reporter (optional, for future use)
    - Test file pattern: **/*.test.ts

    Add npm scripts to package.json:
    - "test": "vitest run"
    - "test:watch": "vitest"
    - "test:coverage": "vitest run --coverage"
  </action>
  <verify>npm test runs successfully (0 tests found is fine at this stage)</verify>
  <done>Vitest configured, npm test works, test:watch works</done>
</task>

<task type="auto">
  <name>Task 2: Create EventBus port interface and EventEmitter adapter</name>
  <files>src/events/types.ts, src/events/bus.ts, src/events/index.ts</files>
  <action>
    Create src/events/types.ts:
    - Define EventBus interface (the PORT):
      ```typescript
      export interface EventBus {
        emit<T extends DomainEvent>(event: T): void;
        on<T extends DomainEvent>(eventType: T['type'], handler: (event: T) => void): void;
        off<T extends DomainEvent>(eventType: T['type'], handler: (event: T) => void): void;
        once<T extends DomainEvent>(eventType: T['type'], handler: (event: T) => void): void;
      }
      ```
    - Define base DomainEvent interface:
      ```typescript
      export interface DomainEvent {
        type: string;
        timestamp: Date;
        payload: unknown;
      }
      ```

    Create src/events/bus.ts:
    - Implement EventEmitterBus class that implements EventBus interface
    - Use Node.js EventEmitter internally
    - Wrap EventEmitter methods to match EventBus interface
    - Add type safety for event emission

    Create src/events/index.ts:
    - Export EventBus interface
    - Export EventEmitterBus class
    - Export DomainEvent type
    - Export convenience function: createEventBus() that returns EventEmitterBus instance

    Key design: EventBus interface is the PORT. EventEmitterBus is the ADAPTER.
    This allows swapping to RabbitMQ/Kafka/WebSocket later without changing consumers.
  </action>
  <verify>TypeScript compiles: npm run build</verify>
  <done>EventBus interface defined, EventEmitterBus implemented, exports working</done>
</task>

<task type="auto">
  <name>Task 3: Define domain events with typed payloads and write tests</name>
  <files>src/events/types.ts, src/events/bus.test.ts</files>
  <action>
    Add domain event types to src/events/types.ts:

    Process events:
    - ProcessSpawned: { processId: string, pid: number, command: string }
    - ProcessStopped: { processId: string, pid: number, exitCode: number | null }
    - ProcessCrashed: { processId: string, pid: number, signal: string | null }

    Server events:
    - ServerStarted: { port: number, host: string, pid: number }
    - ServerStopped: { uptime: number }

    Log events:
    - LogEntry: { processId: string, stream: 'stdout' | 'stderr', data: string }

    Create union type: DomainEventMap that maps event type strings to payload types.
    This enables type-safe event handling.

    Create src/events/bus.test.ts:
    - Test emit/on pattern works
    - Test once fires only once
    - Test off removes handler
    - Test multiple handlers for same event
    - Test typed event payloads (TypeScript compilation = passing)
    - Test events include timestamp automatically
  </action>
  <verify>npm test passes with all event bus tests green</verify>
  <done>Domain events defined, all tests pass, type safety verified</done>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] npm run build succeeds
- [ ] npm test passes (event bus tests)
- [ ] EventBus interface is exported from src/events/index.ts
- [ ] EventEmitterBus implements EventBus correctly
- [ ] All domain events have typed payloads
</verification>

<success_criteria>

- All tasks completed
- All verification checks pass
- Event bus is extensible (interface-based)
- Tests prove the pattern works
</success_criteria>

<output>
After completion, create `.planning/phases/01.1-hexagonal-architecture/01.1-01-SUMMARY.md`
</output>
