@hegemonart/get-design-done 1.19.6 → 1.21.0

package/scripts/lib/event-stream/index.ts

@@ -0,0 +1,164 @@
+// scripts/lib/event-stream/index.ts — public API for the Phase 20+
+// telemetry stream (Plan 20-06, SDK-08).
+//
+// Consumers import ONLY from this file. The internal parts
+// (`./types.ts`, `./writer.ts`, `./emitter.ts`) are implementation
+// detail; changing them without updating this export surface is a
+// breaking change for downstream plans (20-05 MCP handlers, 20-13 hooks).
+//
+// Surface:
+//   * appendEvent(ev)          — persist + broadcast one event
+//   * getWriter(opts?)         — lazy singleton EventWriter
+//   * getBus()                 — lazy singleton EventBus
+//   * reset()                  — clear module-level singletons (tests)
+//   * types                    — BaseEvent, KnownEvent, and every pre-
+//                                registered subtype (StateMutationEvent,
+//                                StateTransitionEvent, …).
+
+import { hostname } from 'node:os';
+
+import { EventBus } from './emitter.ts';
+import type { Unsubscribe, EventHandler } from './emitter.ts';
+import { EventWriter } from './writer.ts';
+import type { WriterOptions } from './writer.ts';
+import type { BaseEvent, EventMeta } from './types.ts';
+
+export type {
+  BaseEvent,
+  EventMeta,
+  KnownEvent,
+  StateMutationEvent,
+  StateTransitionEvent,
+  StageEnteredEvent,
+  StageExitedEvent,
+  HookFiredEvent,
+  ErrorEvent,
+} from './types.ts';
+export { EventBus } from './emitter.ts';
+export type { EventHandler, Unsubscribe } from './emitter.ts';
+export { EventWriter, DEFAULT_EVENTS_PATH, DEFAULT_MAX_LINE_BYTES } from './writer.ts';
+export type { WriterOptions } from './writer.ts';
+
+/**
+ * Lazily-constructed module-level singletons. `getWriter()` honors the
+ * first `opts` it receives; subsequent calls with different options are
+ * ignored. Tests that need to vary options across runs should call
+ * {@link reset} between runs.
+ */
+let defaultWriter: EventWriter | null = null;
+let defaultBus: EventBus | null = null;
+/**
+ * Cached host name. `os.hostname()` is cheap but not free (syscall on
+ * some platforms) and we stamp it onto every event; compute once.
+ */
+let cachedHost: string | null = null;
+
+/**
+ * Return the module-level default writer, constructing it on first
+ * call. Passing `opts` on subsequent calls is a no-op (the first
+ * caller wins); that matches the "single shared file per process"
+ * intent.
+ */
+export function getWriter(opts?: WriterOptions): EventWriter {
+  if (defaultWriter === null) {
+    // Honor GDD_EVENTS_PATH env var as the first-choice default path
+    // when the caller doesn't pass an explicit `opts.path`. Lets test
+    // harnesses and Plan 21-11's E2E subprocess steer the on-disk
+    // stream into a fixture-specific directory without chdir'ing the
+    // entire process. Explicit `opts.path` always wins.
+    const envPath: string | undefined = process.env['GDD_EVENTS_PATH'];
+    const finalOpts: WriterOptions =
+      opts?.path === undefined && envPath !== undefined && envPath.length > 0
+        ? { ...(opts ?? {}), path: envPath }
+        : (opts ?? {});
+    defaultWriter = new EventWriter(finalOpts);
+  }
+  return defaultWriter;
+}
+
+/** Return the module-level default bus, constructing it on first call. */
+export function getBus(): EventBus {
+  if (defaultBus === null) {
+    defaultBus = new EventBus();
+  }
+  return defaultBus;
+}
+
+/**
+ * Persist `ev` to the on-disk JSONL stream AND broadcast it to the
+ * in-process bus. This is the normal emission path for every Phase 20+
+ * event producer.
+ *
+ * Ordering:
+ *   1. Stamp `_meta` (pid/host/source) if the caller didn't supply it.
+ *   2. Persist via `getWriter().append(ev)` — sync, never throws.
+ *   3. Broadcast via `getBus().emit(ev.type, ev)` AND `emit('*', ev)`
+ *      so typed subscribers and `subscribeAll` observers both see it.
+ *
+ * Bus emission can still throw if a subscriber handler throws; we
+ * intentionally surface that rather than silently swallowing, since a
+ * failing handler is a programming bug, not an expected runtime
+ * condition. Plan 20-13's hooks wrap their handler bodies defensively
+ * for this reason.
+ */
+export function appendEvent(ev: BaseEvent): void {
+  // Stamp writer-injected metadata if absent. We don't clone the full
+  // event — callers typically build it fresh per emission — but we do
+  // need to ensure `_meta` is present by the time we persist.
+  if (ev._meta === undefined) {
+    if (cachedHost === null) {
+      try {
+        cachedHost = hostname();
+      } catch {
+        cachedHost = 'unknown';
+      }
+    }
+    const meta: EventMeta = {
+      pid: process.pid,
+      host: cachedHost,
+      source: 'event-stream',
+    };
+    ev._meta = meta;
+  }
+
+  // Persist first. Bus emission is synchronous; if a subscriber throws
+  // after we've persisted, the durable record is already safe.
+  getWriter().append(ev);
+
+  const bus = getBus();
+  bus.emit(ev.type, ev);
+  bus.emit('*', ev);
+}
+
+/**
+ * Reset module-level singletons. Intended for tests that want a fresh
+ * writer (e.g. pointed at a new temp directory) or a fresh bus (e.g.
+ * to assert isolation between test cases).
+ *
+ * Safe to call from production code but the intended caller is a test.
+ * `appendEvent()` will lazily reconstruct both singletons on the next
+ * emission.
+ */
+export function reset(): void {
+  if (defaultBus !== null) {
+    defaultBus.removeAllListeners();
+  }
+  defaultWriter = null;
+  defaultBus = null;
+}
+
+// Re-export `subscribe`/`subscribeAll` convenience: some callers only
+// need to subscribe, not emit, and `getBus().subscribe(…)` reads fine
+// but the shorter form keeps consumer code terse.
+/** Convenience: subscribe to one event type on the default bus. */
+export function subscribe<T extends BaseEvent = BaseEvent>(
+  type: T['type'],
+  handler: EventHandler<T>,
+): Unsubscribe {
+  return getBus().subscribe<T>(type, handler);
+}
+
+/** Convenience: subscribe to every event on the default bus. */
+export function subscribeAll(handler: EventHandler<BaseEvent>): Unsubscribe {
+  return getBus().subscribeAll(handler);
+}

package/scripts/lib/event-stream/types.ts

@@ -0,0 +1,127 @@
+// scripts/lib/event-stream/types.ts — typed event envelope + pre-registered
+// event shapes, per Plan 20-06 (SDK-08).
+//
+// The event stream is the Phase 20+ observability primitive that every
+// downstream consumer (Plan 20-05 MCP tool handlers, Plan 20-13 hooks)
+// builds on. A single append-only JSONL file at
+// `.design/telemetry/events.jsonl` holds the persisted form; an in-process
+// `EventEmitter` bus (see `./emitter.ts`) broadcasts the same events
+// live to subscribers within the same Node process.
+//
+// Envelope invariants (also encoded in `reference/schemas/events.schema.json`):
+//   * `type`       — required, string, free-form. Pre-registered subtypes
+//                    below are merely the seeded set; unknown types are
+//                    allowed (validation is structural, not a closed enum).
+//   * `timestamp`  — required, ISO-8601 (`date-time` format).
+//   * `sessionId`  — required, stable per GDD pipeline run.
+//   * `stage`      — optional, narrow `Stage` union.
+//   * `cycle`      — optional, free-form string identifier.
+//   * `payload`    — required, opaque object bag.
+//   * `_meta`      — optional, writer-injected `{ pid, host, source }`.
+//   * `_truncated` — optional, writer-set when a payload exceeds
+//                    `maxLineBytes` and has been replaced by a placeholder.
+//
+// Plan 20-04 owns the error taxonomy that feeds `ErrorEvent.payload`:
+// `{ code, message, kind }` mirrors `toToolError(err)` output.
+
+import type { Stage } from '../gdd-state/types.ts';
+
+/** Writer-injected metadata. Never populated by callers. */
+export interface EventMeta {
+  pid: number;
+  host: string;
+  /**
+   * Free-form identifier for the module that produced the event.
+   * Defaults to `"event-stream"` when `appendEvent()` fills the field
+   * itself; callers that wrap `appendEvent()` in a module-specific helper
+   * should overwrite this before calling.
+   */
+  source: string;
+}
+
+/**
+ * Canonical event envelope. All persisted and in-process events share
+ * this shape. Concrete subtypes narrow `type` + `payload` but add no
+ * additional top-level fields.
+ */
+export interface BaseEvent {
+  type: string;
+  timestamp: string;
+  sessionId: string;
+  stage?: Stage;
+  cycle?: string;
+  payload: Record<string, unknown>;
+  _meta?: EventMeta;
+  /**
+   * Set to `true` by the writer when the serialized event exceeded
+   * `maxLineBytes` and the payload has been replaced with a placeholder.
+   * Never set by callers.
+   */
+  _truncated?: boolean;
+}
+
+/**
+ * Emitted by Plan 20-05's MCP tool handlers after a successful
+ * `mutate()` / `transition()` call. `diff` is an opaque structural
+ * description of the change; consumers (Phase 22 dashboard) render it.
+ */
+export type StateMutationEvent = BaseEvent & {
+  type: 'state.mutation';
+  payload: { tool: string; diff: unknown };
+};
+
+/**
+ * Emitted by Plan 20-05 wrapping `transition()`. `pass=false` means
+ * the gate blocked the advance; `blockers` carries the same list the
+ * transition's `TransitionGateFailed` would expose.
+ */
+export type StateTransitionEvent = BaseEvent & {
+  type: 'state.transition';
+  payload: { from: Stage; to: Stage; blockers: string[]; pass: boolean };
+};
+
+/** Lifecycle hook emitted when a pipeline stage begins execution. */
+export type StageEnteredEvent = BaseEvent & {
+  type: 'stage.entered';
+  payload: { stage: Stage };
+};
+
+/**
+ * Lifecycle hook emitted when a pipeline stage finishes. `duration_ms`
+ * measures wall-clock time from `stage.entered`. `outcome` mirrors the
+ * stage's terminal state.
+ */
+export type StageExitedEvent = BaseEvent & {
+  type: 'stage.exited';
+  payload: { stage: Stage; duration_ms: number; outcome: 'pass' | 'fail' | 'halted' };
+};
+
+/** Emitted by Plan 20-13 hook consumers when a hook dispatches a decision. */
+export type HookFiredEvent = BaseEvent & {
+  type: 'hook.fired';
+  payload: { hook: string; decision: string };
+};
+
+/**
+ * Emitted whenever a `GDDError` is surfaced to the user or returned from
+ * a tool handler. `kind` mirrors `classify(err).kind`; `code` +
+ * `message` mirror the error's `code` + `message`.
+ */
+export type ErrorEvent = BaseEvent & {
+  type: 'error';
+  payload: { code: string; message: string; kind: string };
+};
+
+/**
+ * Union of all pre-registered event types. Not a closed enum at the
+ * envelope level — callers can emit unknown types — but downstream
+ * consumers use this to drive typed `switch` statements with exhaustive
+ * checks for the subset they care about.
+ */
+export type KnownEvent =
+  | StateMutationEvent
+  | StateTransitionEvent
+  | StageEnteredEvent
+  | StageExitedEvent
+  | HookFiredEvent
+  | ErrorEvent;

package/scripts/lib/event-stream/writer.ts

@@ -0,0 +1,154 @@
+// scripts/lib/event-stream/writer.ts — append-only JSONL writer for the
+// Phase 20+ telemetry stream (Plan 20-06, SDK-08).
+//
+// Design:
+//   * One file per .design/: `.design/telemetry/events.jsonl`, sibling to
+//     the existing `costs.jsonl` (which this plan does NOT modify).
+//   * Each `append()` is one call to `fs.appendFileSync(…, { flag: 'a' })`.
+//     On POSIX the O_APPEND semantic guarantees that a single write()
+//     under `PIPE_BUF` (4096 bytes) is atomic with respect to other
+//     appenders — multiple processes can append concurrently without
+//     interleaving or corruption. On Windows, `FILE_APPEND_DATA` via the
+//     Node runtime supplies the same guarantee. Typical event lines are
+//     well under 1KB; oversized events are truncated (see below) so we
+//     never approach the 4KB atomicity ceiling even on stricter POSIX
+//     implementations.
+//   * `append()` NEVER throws to the caller. On I/O failure we record
+//     the error (so observability tooling can surface it) and write a
+//     single diagnostic line to stderr.
+//   * Oversized payloads (> `maxLineBytes`, default 64KB) are truncated
+//     rather than dropped: we keep envelope metadata and replace
+//     `payload` with `{ _truncated_placeholder: true }`, then re-serialize
+//     and stamp `_truncated: true` on the line.
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve, isAbsolute, join } from 'node:path';
+
+import type { BaseEvent } from './types.ts';
+
+/** Default relative path for the persisted event stream. */
+export const DEFAULT_EVENTS_PATH = '.design/telemetry/events.jsonl';
+
+/** Default max line size in bytes. JSONL lines that exceed this are truncated. */
+export const DEFAULT_MAX_LINE_BYTES = 64 * 1024; // 64 KiB
+
+/** Constructor options for {@link EventWriter}. */
+export interface WriterOptions {
+  /**
+   * Target file path for persisted events. Resolved to absolute at
+   * construction. Relative paths are resolved against `process.cwd()`.
+   *
+   * Default: `.design/telemetry/events.jsonl`.
+   */
+  path?: string;
+  /**
+   * Maximum serialized line size in bytes (JSON.stringify length + `\n`).
+   * Events exceeding this cap are truncated — the envelope is preserved
+   * and the payload is replaced with a `_truncated_placeholder` marker.
+   *
+   * Default: 65536 (64 KiB).
+   */
+  maxLineBytes?: number;
+}
+
+/**
+ * Append-only JSONL writer. One instance per file path is sufficient;
+ * the module-level cache in `./index.ts` shares a single default writer
+ * across the process so directory creation only happens once.
+ */
+export class EventWriter {
+  /** Resolved absolute target path. */
+  readonly path: string;
+  /** Maximum line size in bytes (see {@link WriterOptions.maxLineBytes}). */
+  readonly maxLineBytes: number;
+  /** Number of failed append attempts since construction. */
+  writeErrors: number = 0;
+  /** The most recent write error, or `null` if none has occurred. */
+  lastError: Error | null = null;
+
+  /** `true` once we've ensured the target directory exists. */
+  private directoryEnsured: boolean = false;
+
+  constructor(opts: WriterOptions = {}) {
+    const rawPath = opts.path ?? DEFAULT_EVENTS_PATH;
+    this.path = isAbsolute(rawPath) ? rawPath : resolve(process.cwd(), rawPath);
+    this.maxLineBytes = opts.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+  }
+
+  /**
+   * Append one event to the target file.
+   *
+   * Contract:
+   *   * SYNC — returns when the write has been accepted by the kernel.
+   *   * NEVER throws — I/O errors increment {@link writeErrors} and update
+   *     {@link lastError}; a diagnostic is written to stderr and
+   *     execution continues.
+   *   * Truncates oversized payloads rather than dropping the event.
+   */
+  append(ev: BaseEvent): void {
+    try {
+      const line = this.serialize(ev);
+      this.ensureDirectory();
+      appendFileSync(this.path, line, { flag: 'a' });
+    } catch (err) {
+      this.writeErrors += 1;
+      this.lastError = err instanceof Error ? err : new Error(String(err));
+      // One-line diagnostic; intentionally minimal so callers aren't
+      // spammed under sustained failure.
+      try {
+        process.stderr.write(
+          `[event-stream] write failed: ${this.lastError.message}\n`,
+        );
+      } catch {
+        // If stderr itself is broken we have no recourse; swallow.
+      }
+    }
+  }
+
+  /**
+   * Produce the on-disk JSONL representation of an event, truncating
+   * oversized payloads so the line fits within {@link maxLineBytes}.
+   *
+   * Exposed on the instance for unit-testability; callers should use
+   * {@link append}.
+   */
+  serialize(ev: BaseEvent): string {
+    const raw = JSON.stringify(ev) + '\n';
+    if (Buffer.byteLength(raw, 'utf8') <= this.maxLineBytes) {
+      return raw;
+    }
+
+    // Truncate: keep envelope fields, drop payload content.
+    const truncated: BaseEvent = {
+      type: ev.type,
+      timestamp: ev.timestamp,
+      sessionId: ev.sessionId,
+      payload: { _truncated_placeholder: true },
+      _truncated: true,
+    };
+    if (ev.stage !== undefined) truncated.stage = ev.stage;
+    if (ev.cycle !== undefined) truncated.cycle = ev.cycle;
+    if (ev._meta !== undefined) truncated._meta = ev._meta;
+    return JSON.stringify(truncated) + '\n';
+  }
+
+  /**
+   * Ensure the target directory exists. Memoized so we only pay the
+   * filesystem stat cost once per writer lifetime.
+   */
+  private ensureDirectory(): void {
+    if (this.directoryEnsured) return;
+    mkdirSync(dirname(this.path), { recursive: true });
+    this.directoryEnsured = true;
+  }
+}
+
+/**
+ * Convenience helper: resolve a relative events-path against a supplied
+ * base directory (typically the project root) rather than `process.cwd()`.
+ * Intended for tests that scaffold a temp workspace and don't want to
+ * chdir.
+ */
+export function eventsPathFor(baseDir: string): string {
+  return join(baseDir, DEFAULT_EVENTS_PATH);
+}