@c9up/ream 0.1.3

package/src/errors/ModuleErrors.ts

@@ -0,0 +1,73 @@
+/**
+ * Module-specific error subclasses.
+ *
+ * Each module gets its own error class with appropriate defaults.
+ *
+ * @implements FR71
+ */
+
+import { ReamError } from './ReamError.js'
+
+/** Container / IoC errors */
+export class ContainerError extends ReamError {
+  constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
+    super(`CONTAINER_${code}`, message, options)
+    this.name = 'ContainerError'
+  }
+}
+
+/** Router errors */
+export class RouterError extends ReamError {
+  constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
+    super(`ROUTER_${code}`, message, options)
+    this.name = 'RouterError'
+  }
+}
+
+/** Pipeline / Middleware errors */
+export class PipelineError extends ReamError {
+  constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
+    super(`PIPELINE_${code}`, message, options)
+    this.name = 'PipelineError'
+  }
+}
+
+/** Atlas ORM errors */
+export class AtlasError extends ReamError {
+  constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
+    super(`ATLAS_${code}`, message, options)
+    this.name = 'AtlasError'
+  }
+}
+
+/** Rune validation errors */
+export class RuneError extends ReamError {
+  constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
+    super(`RUNE_${code}`, message, options)
+    this.name = 'RuneError'
+  }
+}
+
+/** Warden auth errors */
+export class WardenError extends ReamError {
+  constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
+    super(`WARDEN_${code}`, message, options)
+    this.name = 'WardenError'
+  }
+}
+
+/** Event bus errors */
+export class EventsError extends ReamError {
+  constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
+    super(`EVENTS_${code}`, message, options)
+    this.name = 'EventsError'
+  }
+}
+
+/** Forge CLI errors */
+export class ForgeError extends ReamError {
+  constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
+    super(`FORGE_${code}`, message, options)
+    this.name = 'ForgeError'
+  }
+}

package/src/errors/PipelineStageError.ts

@@ -0,0 +1,97 @@
+/**
+ * Pipeline Stage Error — indicates which pipeline stage failed.
+ *
+ * @implements FR73
+ */
+
+import { ReamError } from './ReamError.js'
+
+/** Pipeline stage names in execution order. */
+export const PIPELINE_STAGES = [
+  'Security (Blackhole)',
+  'Logging',
+  'Global Middleware',
+  'Named Middleware',
+  'Guard',
+  'Validate',
+  'Transaction',
+  'Handler',
+  'After Middleware',
+  'Response Logging',
+] as const
+
+export type PipelineStageName = (typeof PIPELINE_STAGES)[number]
+
+/**
+ * Create a pipeline stage error with position context.
+ *
+ * @param stageIndex - Zero-based index in PIPELINE_STAGES (clamped to valid range)
+ * @param originalError - The error that occurred
+ * @param context - Additional context
+ */
+export function createPipelineError(
+  stageIndex: number,
+  originalError: Error,
+  context?: Record<string, string>,
+): ReamError {
+  const total = PIPELINE_STAGES.length
+  const clampedIndex = Math.max(0, Math.min(stageIndex, total - 1))
+  const stageName = PIPELINE_STAGES[clampedIndex]
+  const position = `${clampedIndex + 1}/${total}`
+  const nextStage = clampedIndex + 1 < total ? PIPELINE_STAGES[clampedIndex + 1] : '(end)'
+
+  const errorCode = originalError instanceof ReamError ? originalError.code : 'PIPELINE_ERROR'
+
+  return new ReamError(errorCode, originalError.message, {
+    pipelineStage: `${position} (${stageName})`,
+    hint: `Error occurred at pipeline stage ${position} (${stageName}). Next stage would have been: ${nextStage}.`,
+    context: {
+      ...context,
+      stage: stageName,
+      position,
+      nextStage,
+    },
+    sourceFile: originalError instanceof ReamError ? originalError.sourceFile : undefined,
+    sourceLine: originalError instanceof ReamError ? originalError.sourceLine : undefined,
+    docsUrl: originalError instanceof ReamError ? originalError.docsUrl : undefined,
+  })
+}
+
+/**
+ * Validate pipeline configuration at boot time.
+ * Detects misconfiguration before accepting traffic.
+ *
+ * @implements FR74
+ */
+export function validatePipelineConfig(config: {
+  globalMiddleware?: unknown[]
+  namedMiddleware?: Record<string, unknown>
+  routes?: Array<{ middleware?: string[] }>
+}): ReamError[] {
+  const errors: ReamError[] = []
+
+  // Check named middleware references exist (deduplicated)
+  if (config.routes && config.namedMiddleware) {
+    const registered = new Set(Object.keys(config.namedMiddleware))
+    const reported = new Set<string>()
+
+    for (const route of config.routes) {
+      for (const mw of route.middleware ?? []) {
+        if (!registered.has(mw) && !reported.has(mw)) {
+          reported.add(mw)
+          errors.push(
+            new ReamError('PIPELINE_UNKNOWN_MIDDLEWARE', `Middleware '${mw}' is not registered`, {
+              hint: `Register it with middleware.register('${mw}', handler) before using it on routes.`,
+              context: {
+                middleware: mw,
+                registered: [...registered].join(', '),
+              },
+            }),
+          )
+        }
+      }
+    }
+  }
+
+  return errors
+}

package/src/errors/ReamError.ts

@@ -0,0 +1,138 @@
+/**
+ * Base ReamError class for TypeScript.
+ *
+ * Parses structured JSON errors from Rust NAPI boundary and provides
+ * rich error context (code, hint, source location, docs URL).
+ *
+ * @implements FR71, FR72, FR73, FR77
+ */
+
+export class ReamError extends Error {
+  /** Error code (e.g., "ATLAS_QUERY_ERROR", "CONTAINER_NOT_FOUND") */
+  readonly code: string
+
+  /** Additional context key-value pairs */
+  readonly context: Record<string, string>
+
+  /** Actionable hint for the developer */
+  readonly hint?: string
+
+  /** Source file where the error originated */
+  readonly sourceFile?: string
+
+  /** Line number in the source file */
+  readonly sourceLine?: number
+
+  /** URL to the error documentation page */
+  readonly docsUrl?: string
+
+  /** Pipeline stage where the error occurred (if applicable) */
+  readonly pipelineStage?: string
+
+  constructor(
+    code: string,
+    message: string,
+    options?: {
+      context?: Record<string, string>
+      hint?: string
+      sourceFile?: string
+      sourceLine?: number
+      docsUrl?: string
+      pipelineStage?: string
+    },
+  ) {
+    super(message)
+    this.name = 'ReamError'
+    this.code = code
+    this.context = options?.context ?? {}
+    this.hint = options?.hint
+    this.sourceFile = options?.sourceFile
+    this.sourceLine = options?.sourceLine
+    this.docsUrl = options?.docsUrl ?? `https://docs.ream.dev/errors/${code}`
+    this.pipelineStage = options?.pipelineStage
+  }
+
+  /**
+   * Parse a NAPI error message (JSON string from Rust ReamError) into a TS ReamError.
+   * Falls back to a generic error if parsing fails.
+   */
+  static fromNapi(error: Error): ReamError {
+    try {
+      const parsed = JSON.parse(error.message)
+      if (typeof parsed !== 'object' || parsed === null || typeof parsed.code !== 'string') {
+        return new ReamError('UNKNOWN', error.message)
+      }
+      return new ReamError(parsed.code, parsed.message ?? error.message, {
+        context:
+          typeof parsed.context === 'object' && parsed.context !== null ? parsed.context : {},
+        hint: typeof parsed.hint === 'string' ? parsed.hint : undefined,
+        sourceFile: typeof parsed.sourceFile === 'string' ? parsed.sourceFile : undefined,
+        sourceLine: typeof parsed.sourceLine === 'number' ? parsed.sourceLine : undefined,
+        docsUrl: typeof parsed.docsUrl === 'string' ? parsed.docsUrl : undefined,
+      })
+    } catch {
+      // Not a JSON error — wrap as generic
+      return new ReamError('UNKNOWN', error.message)
+    }
+  }
+
+  /**
+   * Format for dev console — full box display with all details.
+   */
+  toDevString(): string {
+    const content: string[] = []
+    content.push(`[${this.code}] ${this.message}`)
+
+    if (this.pipelineStage) {
+      content.push(`Pipeline: ${this.pipelineStage}`)
+    }
+
+    if (this.sourceFile) {
+      content.push(`at ${this.sourceFile}${this.sourceLine ? `:${this.sourceLine}` : ''}`)
+    }
+
+    if (Object.keys(this.context).length > 0) {
+      content.push('')
+      for (const [key, value] of Object.entries(this.context)) {
+        // Escape newlines in values to prevent box corruption
+        const safeValue = String(value).replace(/\n/g, '\\n')
+        content.push(`${key}: ${safeValue}`)
+      }
+    }
+
+    if (this.hint) {
+      content.push('')
+      content.push(`Hint: ${this.hint}`)
+    }
+
+    if (this.docsUrl) {
+      content.push(`Docs: ${this.docsUrl}`)
+    }
+
+    // Compute border width from the longest content line
+    const maxLen = Math.min(Math.max(...content.map((l) => l.length)) + 4, 80)
+    const border = '─'.repeat(maxLen)
+
+    const lines = [`┌${border}┐`]
+    for (const line of content) {
+      lines.push(`│ ${line}`)
+    }
+    lines.push(`└${border}┘`)
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Format for prod — code + message only.
+   */
+  toProdString(): string {
+    return `[${this.code}] ${this.message}`
+  }
+
+  /**
+   * Auto-format based on NODE_ENV.
+   */
+  toFormattedString(): string {
+    return process.env.NODE_ENV === 'production' ? this.toProdString() : this.toDevString()
+  }
+}

package/src/events/Emitter.ts

@@ -0,0 +1,333 @@
+/**
+ * Emitter — AdonisJS-compatible typed event system backed by EventBus.
+ *
+ * Class-based events:
+ *   emitter.on(TaskDeclared, SendNotification)
+ *   await new TaskDeclared(task).emit()
+ *
+ * String-based events:
+ *   emitter.on('user:registered', (user) => { ... })
+ *   emitter.emit('user:registered', user)
+ *
+ * Listeners support @inject() for DI when a container resolver is provided.
+ */
+
+import type { EventBus } from './native.js'
+
+/**
+ * Listener class interface — must have a handle() method.
+ */
+export interface ListenerClass<T = unknown> {
+  handle(event: T): Promise<void> | void
+}
+
+type EventConstructor<T = unknown> = new (...args: never[]) => T
+
+type ListenerFn<T = unknown> = (event: T) => Promise<void> | void
+
+type ListenerConstructor<T = unknown> = new (...args: never[]) => ListenerClass<T>
+
+type Listener<T = unknown> = ListenerFn<T> | ListenerConstructor<T>
+
+/** Resolver for instantiating listener classes with DI. */
+export interface ContainerResolver {
+  make<T>(target: new (...args: never[]) => T): T
+}
+
+export class Emitter {
+  private bus: EventBus
+  private resolver?: ContainerResolver
+  private classListeners: Map<EventConstructor, Listener[]> = new Map()
+  private stringListeners: Map<string, ListenerFn[]> = new Map()
+
+  constructor(bus: EventBus, resolver?: ContainerResolver) {
+    this.bus = bus
+    this.resolver = resolver
+  }
+
+  // ─── Class-based events ───────────────────────────────────
+
+  /**
+   * Listen for a class-based event.
+   *   emitter.on(TaskDeclared, SendNotification)        // listener class
+   *   emitter.on(TaskDeclared, (event) => { ... })       // inline function
+   */
+  on<T>(event: EventConstructor<T>, listener: Listener<T>): void
+  /**
+   * Listen for a string-based event.
+   *   emitter.on('user:registered', (user) => { ... })
+   */
+  on(event: string, listener: ListenerFn): void
+  on(event: EventConstructor | string, listener: Listener): void {
+    if (typeof event === 'string') {
+      const list = this.stringListeners.get(event) ?? []
+      list.push(listener as ListenerFn)
+      this.stringListeners.set(event, list)
+    } else {
+      const list = this.classListeners.get(event) ?? []
+      list.push(listener)
+      this.classListeners.set(event, list)
+    }
+  }
+
+  // ─── Emit ─────────────────────────────────────────────────
+
+  /**
+   * Emit a string-based event.
+   */
+  emit(event: string, data: unknown): void {
+    // Dispatch to string listeners
+    const listeners = this.stringListeners.get(event)
+    if (listeners) {
+      for (const fn of listeners) {
+        Promise.resolve(fn(data)).catch((err) => {
+          // Surface listener errors instead of swallowing them
+          this.emitError(event, err)
+        })
+      }
+    }
+
+    // Also push through EventBus for cross-service / Rust subscribers.
+    // `#wrapForBus` prepends the correlation envelope when set so the ID
+    // reaches the other side; without it `setCorrelationId()` was a no-op.
+    void this.bus.emit(event, JSON.stringify(this.#wrapForBus(data))).catch((err: unknown) => {
+      this.emitError(event, err)
+    })
+  }
+
+  /** Emit an error event for listener failures. */
+  private emitError(event: string, error: unknown): void {
+    const errorListeners = this.stringListeners.get('emitter:error')
+    if (errorListeners && errorListeners.length > 0) {
+      for (const fn of errorListeners) {
+        try {
+          fn({ event, error })
+        } catch {
+          /* prevent infinite loop */
+        }
+      }
+    } else {
+      // No error listener — log to stderr as last resort
+      process.stderr.write(`[events] Listener error for '${event}': ${error}\n`)
+    }
+  }
+
+  /**
+   * Dispatch a class-based event. Called by BaseEvent#emit().
+   */
+  async dispatchEvent<T extends object>(event: T): Promise<void> {
+    const EventClass = event.constructor as EventConstructor<T>
+    const listeners = this.classListeners.get(EventClass) ?? []
+    const name = (EventClass as { eventName?: string }).eventName ?? classToEventName(EventClass)
+
+    // Per-listener error isolation — mirrors the string `emit()` contract.
+    // A side-effect listener that throws (SMTP down, etc.) MUST NOT abort
+    // the sibling listeners NOR suppress the cross-service `bus.emit` below:
+    // the domain event already happened, so distributed subscribers must
+    // still receive it. Failures surface on the `emitter:error` channel.
+    for (const listener of listeners) {
+      try {
+        if (isListenerClass(listener)) {
+          // Listener class — resolve via container for @inject() support
+          const instance = this.resolver
+            ? this.resolver.make(listener as ListenerConstructor<T>)
+            : new (listener as ListenerConstructor<T>)()
+          await instance.handle(event)
+        } else {
+          await (listener as ListenerFn<T>)(event)
+        }
+      } catch (err) {
+        this.emitError(name, err)
+      }
+    }
+
+    // Also push through EventBus — same correlation-envelope wrapping as
+    // the string-event path so distributed tracing covers class events too.
+    // Reached unconditionally: a listener failure above no longer skips it.
+    await this.bus.emit(name, JSON.stringify(this.#wrapForBus(event)))
+  }
+
+  // ─── Wildcard subscriptions (via Rust NAPI) ───────────────
+
+  /**
+   * Subscribe to events matching a wildcard pattern.
+   * Uses Rust wildcard engine via NAPI for pattern matching.
+   *
+   *   emitter.onAny('order.*', (name, data) => { ... })   // single segment
+   *   emitter.onAny('order.**', (name, data) => { ... })  // deep match
+   */
+  async onAny(
+    pattern: string,
+    listener: (eventName: string, data: unknown) => void,
+  ): Promise<number> {
+    return this.bus.subscribe(pattern, (eventJson: string) => {
+      try {
+        const event = JSON.parse(eventJson)
+        // The bus delivers a Rust `Event` envelope whose `correlationId`
+        // sits at the top of the parsed JSON. Propagate it onto the
+        // emitter so nested emits inside the listener body inherit the
+        // trace context — that's the whole point of the API. `data` is
+        // the raw user payload string (still JSON-encoded if the
+        // emitter serialized an object), kept as-is for back-compat.
+        if (
+          event !== null &&
+          typeof event === 'object' &&
+          typeof event.correlationId === 'string'
+        ) {
+          this.setCorrelationId(event.correlationId)
+        }
+        listener(event.name ?? pattern, event.data ?? event)
+      } catch {
+        listener(pattern, eventJson)
+      }
+    })
+  }
+
+  /** Unsubscribe a wildcard subscription by ID. */
+  async offAny(subscriptionId: number): Promise<void> {
+    await this.bus.unsubscribe(subscriptionId)
+  }
+
+  /** Check if a pattern matches an event name (wildcard matching via Rust). */
+  matchesPattern(pattern: string, eventName: string): boolean {
+    return this.bus.matchesWildcard(pattern, eventName)
+  }
+
+  // ─── Request / Reply ──────────────────────────────────────
+
+  /**
+   * Send a request event and await a response.
+   *
+   *   const user = await emitter.request('query:user.find', { id: 1 })
+   */
+  async request<T = unknown>(name: string, data: unknown, timeoutMs = 5000): Promise<T> {
+    // Same correlation injection as `emit()` so a `setCorrelationId`
+    // preceding a request actually reaches the responder via the
+    // top-level `correlationId` field on the parsed payload.
+    const result = await this.bus.request(name, JSON.stringify(this.#wrapForBus(data)), timeoutMs)
+    try {
+      return JSON.parse(result) as T
+    } catch {
+      return result as T
+    }
+  }
+
+  /**
+   * Register a request handler.
+   *
+   *   emitter.onRequest('query:user.find', (params, reply) => {
+   *     const user = db.find(params.id)
+   *     reply(JSON.stringify(user))
+   *   })
+   */
+  onRequest(
+    name: string,
+    handler: (eventJson: string, reply: (response: string) => void) => void,
+  ): void {
+    this.bus.onRequest(name, handler)
+  }
+
+  // ─── Correlation context ──────────────────────────────────
+
+  /** Current correlation ID for event chain tracing. */
+  private _correlationId?: string
+
+  /** Set the correlation ID for subsequent events (typically from HTTP request context). */
+  setCorrelationId(id: string): void {
+    this._correlationId = id
+  }
+
+  /** Get the current correlation ID. */
+  getCorrelationId(): string | undefined {
+    return this._correlationId
+  }
+
+  /**
+   * Inject the active correlation ID at the top level of the payload so
+   * the bus's Event envelope (`{ id, name, data, correlationId, ... }`)
+   * surfaces it on the subscriber side — both the Rust `ream-events`
+   * envelope serde and `FakeBus.parseEmitData()` already read
+   * `correlationId` from the parsed `data` string. Without this injection
+   * `setCorrelationId()` was a no-op functional API. Returns `data`
+   * unchanged when no correlation ID is set OR when `data` is not a plain
+   * object (primitives / arrays / null can't carry a sibling field).
+   */
+  #wrapForBus(data: unknown): unknown {
+    if (this._correlationId === undefined) return data
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+      return data
+    }
+    const obj = data as Record<string, unknown>
+    // User-supplied correlationId wins — don't clobber an explicit value.
+    if (typeof obj.correlationId === 'string') return data
+    return { ...obj, correlationId: this._correlationId }
+  }
+
+  // ─── Introspection ────────────────────────────────────────
+
+  /**
+   * Check if any listeners are registered for an event.
+   */
+  hasListeners(event: EventConstructor | string): boolean {
+    if (typeof event === 'string') {
+      return (this.stringListeners.get(event)?.length ?? 0) > 0
+    }
+    return (this.classListeners.get(event)?.length ?? 0) > 0
+  }
+
+  /** Get the number of Rust-side subscriptions. */
+  async subscriptionCount(): Promise<number> {
+    return this.bus.subscriptionCount()
+  }
+}
+
+/**
+ * BaseEvent — extend to create typed event classes.
+ *
+ * Usage:
+ *   class TaskDeclared extends BaseEvent {
+ *     constructor(public task: Task) { super() }
+ *   }
+ *
+ *   // In controller:
+ *   await new TaskDeclared(task).emit()
+ *
+ *   // In events.ts:
+ *   emitter.on(TaskDeclared, LogTaskEvent)
+ */
+export class BaseEvent {
+  static eventName?: string
+  private static _emitter: Emitter | undefined
+
+  /** @internal Wire the emitter (called by EventsProvider). */
+  static useEmitter(emitter: Emitter): void {
+    BaseEvent._emitter = emitter
+  }
+
+  static resetEmitter(): void {
+    BaseEvent._emitter = undefined
+  }
+
+  /**
+   * Dispatch this event instance via the wired emitter.
+   * No-op if no emitter is wired (test/standalone mode).
+   */
+  async emit(): Promise<void> {
+    if (!BaseEvent._emitter) return
+    try {
+      await BaseEvent._emitter.dispatchEvent(this)
+    } catch (err) {
+      process.stderr.write(`[events] dispatch error for ${this.constructor.name}: ${err}\n`)
+    }
+  }
+}
+
+/** Convert PascalCase class name to dot.separated event name. */
+function classToEventName(cls: EventConstructor): string {
+  return cls.name.replace(/([a-z])([A-Z])/g, '$1.$2').toLowerCase()
+}
+
+/** Check if a listener entry is a class (has prototype.handle) vs a function. */
+function isListenerClass(listener: Listener): boolean {
+  return typeof listener === 'function' && typeof listener.prototype?.handle === 'function'
+}

package/src/events/EventsProvider.ts

@@ -0,0 +1,58 @@
+import { BaseEvent, Emitter } from './Emitter.js'
+import { EventBus } from './native.js'
+import { setEmitter } from './services/main.js'
+
+/**
+ * Host context for the events provider. The container is referenced
+ * structurally (not via a concrete import) so the provider stays a thin
+ * seam over ream's IoC container.
+ *
+ * `make()` is the listener-class resolver Emitter needs. When the host
+ * doesn't expose it, listener CLASSES can't be instantiated — only inline
+ * function listeners work. The optional `make` field mirrors Emitter's
+ * `ContainerResolver` interface so the assignment type-checks without a
+ * load-bearing cast.
+ */
+interface EventsContainer {
+  singleton(token: unknown, factory: () => unknown): void
+  resolve<T = unknown>(token: unknown): T
+  make?<T>(target: new (...args: never[]) => T): T
+}
+export interface EventsAppContext {
+  container: EventsContainer
+}
+
+export default class EventsProvider {
+  constructor(protected app: EventsAppContext) {}
+
+  register() {
+    this.app.container.singleton(EventBus, () => new EventBus())
+    this.app.container.singleton('bus', () => this.app.container.resolve<EventBus>(EventBus))
+
+    this.app.container.singleton(Emitter, () => {
+      const bus = this.app.container.resolve<EventBus>(EventBus)
+      // Forward `make` only when the host actually exposes it.
+      // Emitter falls back to direct `new Listener()` instantiation
+      // otherwise, which keeps zero-arg listener classes working
+      // without a full IoC container.
+      const resolver =
+        typeof this.app.container.make === 'function'
+          ? { make: this.app.container.make.bind(this.app.container) }
+          : undefined
+      return new Emitter(bus, resolver)
+    })
+    this.app.container.singleton('emitter', () => this.app.container.resolve<Emitter>(Emitter))
+    // Primary public token — `ctx.events` and `container.resolve('events')`.
+    this.app.container.singleton('events', () => this.app.container.resolve<Emitter>(Emitter))
+  }
+
+  async boot() {
+    const emitter = this.app.container.resolve<Emitter>(Emitter)
+    BaseEvent.useEmitter(emitter)
+    setEmitter(emitter)
+  }
+
+  async shutdown() {
+    BaseEvent.resetEmitter()
+  }
+}