@hegemonart/get-design-done 1.20.0 → 1.22.0

package/scripts/lib/logger/index.ts

@@ -0,0 +1,251 @@
+// scripts/lib/logger/index.ts — Plan 21-04 (SDK-16).
+//
+// Public API for the Phase-21 structured logger. Consumers import ONLY
+// from this file; `./types.ts` and `./sinks.ts` are implementation
+// detail but their public types/classes are re-exported here for
+// advanced callers (e.g., a test that wants to build a custom sink
+// stack or a debug harness that wants to introspect levels).
+//
+// Surface:
+//   * createLogger(opts?)        — build a Logger with auto mode detection
+//   * getLogger()                — module-level singleton accessor
+//   * setLogger(l)               — replace the singleton (tests)
+//   * resetLogger()              — clear the singleton (tests)
+//   * Types + sinks re-exports   — for advanced consumers / tests
+//
+// Mode detection (in priority order):
+//   1. `opts.headless === true`         → headless (JsonlSink)
+//   2. `opts.headless === false`        → interactive (ConsoleSink)
+//   3. `process.env.GDD_HEADLESS === '1'` → headless
+//   4. `process.env.GDD_HEADLESS === '0'` → interactive (explicit off wins)
+//   5. `!process.stdout.isTTY`           → headless
+//   6. otherwise                         → interactive
+//
+// Event-stream integration (warn + error only):
+//   * `warn(msg, fields)`  → `appendEvent({ type: 'error', payload: { level: 'warn', msg, fields } })`
+//   * `error(msg, fields)` → same, with level: 'error'.
+//   * `debug` and `info` never emit events.
+//   * Failures inside appendEvent are swallowed (logged once via
+//     process.stderr); the logger contract never propagates event-stream
+//     failures back to the caller.
+
+import { appendEvent } from '../event-stream/index.ts';
+import { ConsoleSink, JsonlSink, MultiSink } from './sinks.ts';
+import {
+  LEVEL_ORDER,
+  type LogEntry,
+  type LogLevel,
+  type Logger,
+  type LoggerOptions,
+  type Sink,
+} from './types.ts';
+
+export type { LogLevel, LoggerOptions, LogEntry, Logger, Sink } from './types.ts';
+export { LEVEL_ORDER } from './types.ts';
+export { ConsoleSink, JsonlSink, MultiSink } from './sinks.ts';
+export type {
+  ConsoleSinkOptions,
+  JsonlSinkOptions,
+} from './sinks.ts';
+export { DEFAULT_LOG_DIR, safeStringify } from './sinks.ts';
+
+/**
+ * Decide whether a logger with `opts` should run in headless mode.
+ * Explicit `opts.headless` wins; otherwise env; otherwise TTY check.
+ */
+function detectHeadless(opts: LoggerOptions): boolean {
+  if (opts.headless === true) return true;
+  if (opts.headless === false) return false;
+  const envFlag = process.env['GDD_HEADLESS'];
+  if (envFlag === '1') return true;
+  if (envFlag === '0') return false;
+  return !process.stdout.isTTY;
+}
+
+/** Flag so we only emit the `appendEvent failed` tripwire once per process. */
+let eventStreamFailureLogged = false;
+
+/**
+ * LoggerImpl is not exported; callers build via `createLogger()` and
+ * hold a `Logger` interface reference. Keeping the implementation private
+ * lets us add fields (metrics, per-level counters) without breaking
+ * consumers.
+ */
+class LoggerImpl implements Logger {
+  private readonly sink: Sink;
+  private readonly minLevel: LogLevel;
+  private readonly scope: string | undefined;
+  private readonly baseFields: Record<string, unknown>;
+  private readonly now: () => string;
+  private readonly emitEvents: boolean;
+
+  constructor(
+    sink: Sink,
+    minLevel: LogLevel,
+    scope: string | undefined,
+    baseFields: Record<string, unknown>,
+    now: () => string,
+    emitEvents: boolean,
+  ) {
+    this.sink = sink;
+    this.minLevel = minLevel;
+    this.scope = scope;
+    this.baseFields = baseFields;
+    this.now = now;
+    this.emitEvents = emitEvents;
+  }
+
+  private emit(level: LogLevel, msg: string, fields?: Record<string, unknown>): void {
+    // Level filter first — short-circuit below the minimum for perf.
+    if (LEVEL_ORDER[level] < LEVEL_ORDER[this.minLevel]) return;
+
+    // Build the entry. Caller fields are merged shallow, then reserved
+    // keys are written last so they always override caller input.
+    const merged: Record<string, unknown> = { ...this.baseFields, ...(fields ?? {}) };
+    const entry: LogEntry = {
+      ...merged,
+      ts: this.now(),
+      level,
+      msg,
+      pid: process.pid,
+    };
+    if (this.scope !== undefined) entry.scope = this.scope;
+
+    // Persist to the sink. Sinks are required not to throw, but we
+    // wrap defensively so a buggy custom sink cannot break callers.
+    try {
+      this.sink.write(entry);
+    } catch {
+      // Swallow.
+    }
+
+    // Event-stream integration: warn + error emit an ErrorEvent.
+    if (this.emitEvents && (level === 'warn' || level === 'error')) {
+      try {
+        const payloadFields: Record<string, unknown> = { ...(fields ?? {}) };
+        appendEvent({
+          type: 'error',
+          timestamp: entry.ts,
+          sessionId: this.scope ?? 'anonymous',
+          payload: {
+            level,
+            msg,
+            fields: payloadFields,
+          },
+        });
+      } catch {
+        // Event-stream failures must not surface. Print one tripwire
+        // so operators notice, then stay silent.
+        if (!eventStreamFailureLogged) {
+          eventStreamFailureLogged = true;
+          try {
+            process.stderr.write(
+              '[logger] appendEvent failed; subsequent failures will be silent\n',
+            );
+          } catch {
+            // If stderr is also dead, we've done all we can.
+          }
+        }
+      }
+    }
+  }
+
+  debug(msg: string, fields?: Record<string, unknown>): void {
+    this.emit('debug', msg, fields);
+  }
+  info(msg: string, fields?: Record<string, unknown>): void {
+    this.emit('info', msg, fields);
+  }
+  warn(msg: string, fields?: Record<string, unknown>): void {
+    this.emit('warn', msg, fields);
+  }
+  error(msg: string, fields?: Record<string, unknown>): void {
+    this.emit('error', msg, fields);
+  }
+
+  child(scope: string, fields?: Record<string, unknown>): Logger {
+    const childScope = this.scope !== undefined ? `${this.scope}.${scope}` : scope;
+    const mergedFields: Record<string, unknown> = {
+      ...this.baseFields,
+      ...(fields ?? {}),
+    };
+    return new LoggerImpl(
+      this.sink,
+      this.minLevel,
+      childScope,
+      mergedFields,
+      this.now,
+      this.emitEvents,
+    );
+  }
+
+  flush(): void {
+    // v1 sinks are synchronous; reserved for future async implementations.
+  }
+}
+
+/**
+ * Build a Logger with auto mode detection. See the module-level
+ * mode-detection table.
+ *
+ * @throws RangeError when `opts.level` is not a member of LogLevel.
+ */
+export function createLogger(opts: LoggerOptions = {}): Logger {
+  const level = opts.level ?? 'info';
+  if (!(level in LEVEL_ORDER)) {
+    // Defensive: narrow with a runtime check — TypeScript cannot catch
+    // a caller passing `'verbose' as any`. Fail loud at construction
+    // rather than silently mis-filter downstream.
+    throw new RangeError(
+      `Invalid LogLevel: ${String(level)}. Expected one of: debug, info, warn, error.`,
+    );
+  }
+
+  const now = opts.nowOverride ?? ((): string => new Date().toISOString());
+  const emitEvents = opts.emitEventsOverride === false ? false : true;
+  const scope = opts.scope;
+
+  const headless = detectHeadless(opts);
+  const sink: Sink = headless
+    ? new JsonlSink({
+        ...(opts.logDir !== undefined ? { dir: opts.logDir } : {}),
+        ...(opts.nowOverride !== undefined ? { nowOverride: opts.nowOverride } : {}),
+      })
+    : new ConsoleSink();
+
+  return new LoggerImpl(sink, level, scope, {}, now, emitEvents);
+}
+
+/** Module-level singleton. Built lazily on first `getLogger()` call. */
+let defaultLogger: Logger | null = null;
+
+/**
+ * Return the module-level default logger, constructing it on first
+ * call with default options. Used by modules that don't own a logger
+ * explicitly (session-runner, pipeline-runner, parallel-runners in
+ * later Phase-21 waves).
+ */
+export function getLogger(): Logger {
+  if (defaultLogger === null) {
+    defaultLogger = createLogger();
+  }
+  return defaultLogger;
+}
+
+/**
+ * Replace the module-level default logger. Intended for tests that
+ * want to inject a logger with a captured sink; also used by the
+ * session-runner boot path to install a logger with its pinned
+ * `logDir`/`scope` before any child import calls `getLogger()`.
+ */
+export function setLogger(l: Logger): void {
+  defaultLogger = l;
+}
+
+/**
+ * Clear the module-level default logger. Next `getLogger()` rebuilds
+ * with current env/TTY state. Primarily a test hook.
+ */
+export function resetLogger(): void {
+  defaultLogger = null;
+}

package/scripts/lib/logger/sinks.ts

@@ -0,0 +1,269 @@
+// scripts/lib/logger/sinks.ts — Plan 21-04 (SDK-16).
+//
+// Sink implementations for the Phase-21 structured logger:
+//   * ConsoleSink — pretty stderr output with ANSI colors when TTY.
+//   * JsonlSink   — crash-safe append-only JSONL to .design/logs/<file>.
+//   * MultiSink   — fan-out to N sinks (e.g., console + JSONL simultaneously
+//                   under a test harness).
+//
+// Design rules:
+//   * Sinks MUST NOT throw from `.write()`. IO failures are swallowed
+//     (they'd otherwise break the caller's happy path). A one-shot
+//     `process.stderr.write` of the error is acceptable as a tripwire.
+//   * `safeStringify()` walks the entry with a WeakSet for circular
+//     detection and replaces non-JSON-serializable values with
+//     `"<unserializable: <reason>>"` so a bad caller payload never
+//     crashes the process.
+//   * File paths encode the ISO timestamp with `:` → `-` (Windows won't
+//     allow colons in filenames).
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+import type { LogEntry, Sink } from './types.ts';
+
+/**
+ * Default directory for JSONL logs when neither `opts.dir` nor
+ * `GDD_LOG_DIR` is set. Resolved relative to `process.cwd()`.
+ */
+export const DEFAULT_LOG_DIR = '.design/logs';
+
+/**
+ * ANSI color codes keyed by log level. Empty string when color disabled.
+ */
+const ANSI_RESET = '\u001b[0m';
+const ANSI_BY_LEVEL: Record<LogEntry['level'], string> = {
+  debug: '\u001b[90m', // gray
+  info: '\u001b[36m', // cyan
+  warn: '\u001b[33m', // yellow
+  error: '\u001b[31m', // red
+};
+
+/**
+ * Reserved keys that the logger controls directly. The sinks rely on
+ * these being present; extraction helpers skip them when rendering
+ * "extra fields".
+ */
+const RESERVED_KEYS = new Set(['ts', 'level', 'msg', 'pid', 'scope']);
+
+/**
+ * Replacer that handles non-JSON-serializable values. Uses a single
+ * WeakSet across the whole walk to catch circular refs. Returns
+ * `"<unserializable: <reason>>"` for:
+ *   * circular references (object already seen on the ancestor path)
+ *   * BigInt values
+ *   * Function values
+ *   * anything else that `JSON.stringify` would otherwise throw on.
+ */
+function buildSafeReplacer(): (key: string, value: unknown) => unknown {
+  const seen = new WeakSet<object>();
+  return (_key: string, value: unknown): unknown => {
+    if (typeof value === 'bigint') return '<unserializable: bigint>';
+    if (typeof value === 'function') return '<unserializable: function>';
+    if (typeof value === 'symbol') return '<unserializable: symbol>';
+    if (value !== null && typeof value === 'object') {
+      if (seen.has(value)) return '<unserializable: circular>';
+      seen.add(value);
+    }
+    return value;
+  };
+}
+
+/**
+ * JSON.stringify that never throws. All unserializable leaves become
+ * `<unserializable: ...>` placeholders.
+ */
+export function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, buildSafeReplacer()) ?? 'null';
+  } catch {
+    // Extremely pathological cases (e.g., `toJSON` throws after our
+    // replacer) still fall through here. Return a tagged sentinel
+    // rather than propagate.
+    return '"<unserializable: stringify-failed>"';
+  }
+}
+
+/**
+ * Split a LogEntry into (reserved header, caller fields) for rendering.
+ * The reserved header controls output ordering; caller fields are
+ * rendered as an inline JSON object suffix.
+ */
+function splitEntry(entry: LogEntry): {
+  header: { ts: string; level: string; msg: string; pid: number; scope?: string };
+  extras: Record<string, unknown>;
+} {
+  const extras: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(entry)) {
+    if (!RESERVED_KEYS.has(k)) extras[k] = v;
+  }
+  const header: { ts: string; level: string; msg: string; pid: number; scope?: string } = {
+    ts: entry.ts,
+    level: entry.level,
+    msg: entry.msg,
+    pid: entry.pid,
+  };
+  if (entry.scope !== undefined) header.scope = entry.scope;
+  return { header, extras };
+}
+
+export interface ConsoleSinkOptions {
+  /**
+   * Enable ANSI color output. When `undefined` (default), autodetected
+   * from `process.stderr.isTTY`. Explicit `false` disables coloring;
+   * explicit `true` forces it even for non-TTY streams (useful for
+   * tests that assert the colorized form).
+   */
+  color?: boolean;
+  /**
+   * Write target. Defaults to `process.stderr.write`. Tests inject a
+   * capturing function here.
+   */
+  write?: (chunk: string) => void;
+}
+
+/**
+ * Pretty-printed stderr sink used in interactive mode. Format:
+ *   `<ts> [<LEVEL>] <scope?> <msg> <json-fields>`
+ * Fields JSON is omitted when the entry has no caller fields.
+ */
+export class ConsoleSink implements Sink {
+  readonly colorEnabled: boolean;
+  private readonly writer: (chunk: string) => void;
+
+  constructor(opts: ConsoleSinkOptions = {}) {
+    this.colorEnabled =
+      opts.color !== undefined ? opts.color : Boolean(process.stderr.isTTY);
+    this.writer = opts.write ?? ((chunk: string) => {
+      process.stderr.write(chunk);
+    });
+  }
+
+  write(entry: LogEntry): void {
+    const { header, extras } = splitEntry(entry);
+    const levelToken = header.level.toUpperCase();
+    const coloredLevel = this.colorEnabled
+      ? `${ANSI_BY_LEVEL[entry.level]}${levelToken}${ANSI_RESET}`
+      : levelToken;
+    const scopePart = header.scope !== undefined ? ` ${header.scope}` : '';
+    const extrasKeys = Object.keys(extras);
+    const fieldsPart = extrasKeys.length > 0 ? ` ${safeStringify(extras)}` : '';
+    const line = `${header.ts} [${coloredLevel}]${scopePart} ${header.msg}${fieldsPart}\n`;
+    try {
+      this.writer(line);
+    } catch {
+      // Swallow: writing to stderr failed (very rare — detached stdio,
+      // pipe closed). We intentionally do nothing to honor the "sinks
+      // never throw" contract.
+    }
+  }
+
+  close(): void {
+    // No fd to release; stderr is process-owned.
+  }
+}
+
+export interface JsonlSinkOptions {
+  /**
+   * Output directory. Resolved relative to `process.cwd()` when relative.
+   * Priority: `opts.dir` → `process.env.GDD_LOG_DIR` → `DEFAULT_LOG_DIR`.
+   */
+  dir?: string;
+  /**
+   * Override the ISO timestamp used when composing the filename. Only
+   * affects the filename itself — entry timestamps come from the Logger.
+   * Allows tests to produce a deterministic file path.
+   */
+  nowOverride?: () => string;
+  /**
+   * Override pid used in the filename suffix. Tests use this to pin
+   * the filename when `process.pid` would otherwise vary.
+   */
+  pidOverride?: number;
+}
+
+/**
+ * Append-only JSONL sink. One entry per line, UTF-8, newline-terminated.
+ * File path: `<dir>/<ISO-with-dashes>-<pid>.jsonl`.
+ *
+ * Uses `appendFileSync` on every write — crash-safe (kernel-level atomic
+ * append for small writes), no in-memory buffering. Writes are sync so
+ * the logger caller can return immediately; async buffering would
+ * complicate ordering guarantees under concurrent pipeline stages.
+ */
+export class JsonlSink implements Sink {
+  readonly path: string;
+  private dirCreated = false;
+
+  constructor(opts: JsonlSinkOptions = {}) {
+    const dirOpt =
+      opts.dir ?? process.env['GDD_LOG_DIR'] ?? DEFAULT_LOG_DIR;
+    const dir = isAbsolute(dirOpt) ? dirOpt : resolve(process.cwd(), dirOpt);
+    const iso = opts.nowOverride ? opts.nowOverride() : new Date().toISOString();
+    const pid = opts.pidOverride ?? process.pid;
+    // Replace colons (invalid on Windows filesystems) with dashes.
+    const safeIso = iso.replace(/:/g, '-');
+    this.path = join(dir, `${safeIso}-${pid}.jsonl`);
+  }
+
+  private ensureDir(): void {
+    if (this.dirCreated) return;
+    try {
+      mkdirSync(dirname(this.path), { recursive: true });
+      this.dirCreated = true;
+    } catch {
+      // If mkdir fails (e.g., permission denied), subsequent appendFileSync
+      // will also fail and we'll swallow there. Keep dirCreated=false so
+      // a later write attempts mkdir again (the condition may clear).
+    }
+  }
+
+  write(entry: LogEntry): void {
+    this.ensureDir();
+    const line = `${safeStringify(entry)}\n`;
+    try {
+      appendFileSync(this.path, line, { encoding: 'utf8' });
+    } catch {
+      // Swallow. The logger contract forbids throwing from sinks.
+      // A sustained IO failure is visible via missing log file.
+    }
+  }
+
+  close(): void {
+    // `appendFileSync` opens+closes per call; nothing to release.
+  }
+}
+
+/**
+ * Fan-out sink: every `.write()` is forwarded to every child sink.
+ * Construction validates that the input is a non-null array; null/undefined
+ * entries are rejected defensively (they'd NPE on write otherwise).
+ */
+export class MultiSink implements Sink {
+  private readonly sinks: readonly Sink[];
+
+  constructor(sinks: readonly Sink[]) {
+    this.sinks = sinks.filter((s): s is Sink => s !== null && s !== undefined);
+  }
+
+  write(entry: LogEntry): void {
+    for (const s of this.sinks) {
+      try {
+        s.write(entry);
+      } catch {
+        // Defense in depth: child sinks shouldn't throw, but if one does,
+        // it must not block the others. Swallow per-sink.
+      }
+    }
+  }
+
+  close(): void {
+    for (const s of this.sinks) {
+      try {
+        s.close();
+      } catch {
+        // Same defense — close of one sink must not block another.
+      }
+    }
+  }
+}

package/scripts/lib/logger/types.ts

@@ -0,0 +1,110 @@
+// scripts/lib/logger/types.ts — Plan 21-04 (SDK-16).
+//
+// Public type surface for the structured logger. Consumers import from
+// `./index.ts` (the module barrel); this file exists to keep the type
+// graph clean for `./sinks.ts` and `./index.ts` which both depend on the
+// same `LogEntry`/`Sink`/`Logger` contracts.
+//
+// Contracts:
+//   * LogLevel — closed union of the four levels supported in v1.
+//   * LEVEL_ORDER — numeric map used for min-level filtering. Higher
+//     numbers are more severe. Frozen so callers cannot mutate.
+//   * LoggerOptions — construction-time options. All fields optional so
+//     `createLogger()` can be called with zero args.
+//   * LogEntry — the on-wire shape (both JSONL and console). `ts`,
+//     `level`, `msg`, `pid` are reserved keys: the logger overwrites
+//     caller fields of the same name to preserve the guarantee that a
+//     JSONL line always has a valid timestamp/level/msg/pid.
+//   * Logger — the public API: 4 level methods, `child()`, `flush()`.
+//   * Sink — the sink interface used by ConsoleSink/JsonlSink/MultiSink
+//     in `./sinks.ts`.
+
+/** Closed set of log levels. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Numeric ordering for level filtering. Higher = more severe.
+ * `LEVEL_ORDER[entry.level] >= LEVEL_ORDER[opts.level]` → emit; otherwise drop.
+ * Frozen to prevent accidental mutation by consumers.
+ */
+export const LEVEL_ORDER: Readonly<Record<LogLevel, number>> = Object.freeze({
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+});
+
+export interface LoggerOptions {
+  /** Minimum level to emit. Levels below this are dropped. Default: `'info'`. */
+  level?: LogLevel;
+  /**
+   * Force headless mode regardless of env / TTY detection. When `undefined`
+   * (the default), mode is auto-detected: `GDD_HEADLESS=1` OR
+   * `!process.stdout.isTTY` → headless. `GDD_HEADLESS=0` pins interactive.
+   */
+  headless?: boolean;
+  /**
+   * JSONL output directory (headless mode only). Resolved at construction
+   * time; falls back to `process.env.GDD_LOG_DIR` then `'.design/logs'`.
+   */
+  logDir?: string;
+  /**
+   * Module / subsystem tag merged into every entry (e.g., `'session-runner'`).
+   * `child(scope)` concatenates onto this dot-joined.
+   */
+  scope?: string;
+  /**
+   * Test-only override: replaces the `new Date().toISOString()` source so
+   * test fixtures can be byte-identical across runs.
+   */
+  nowOverride?: () => string;
+  /**
+   * Test-only override: when explicitly `false`, `warn`/`error` do NOT
+   * emit an `ErrorEvent` via event-stream. Any other value behaves as
+   * "emit normally" (the default).
+   */
+  emitEventsOverride?: false;
+}
+
+/**
+ * Shape written to JSONL sinks and passed to ConsoleSink.write().
+ * Reserved keys (`ts`, `level`, `msg`, `pid`) are always present; caller
+ * fields are merged shallow but never override reserved keys.
+ */
+export interface LogEntry {
+  ts: string;
+  level: LogLevel;
+  msg: string;
+  pid: number;
+  scope?: string;
+  [field: string]: unknown;
+}
+
+export interface Logger {
+  debug(msg: string, fields?: Record<string, unknown>): void;
+  info(msg: string, fields?: Record<string, unknown>): void;
+  warn(msg: string, fields?: Record<string, unknown>): void;
+  error(msg: string, fields?: Record<string, unknown>): void;
+  /**
+   * Returns a child logger inheriting options, with additional scope
+   * appended (dot-joined if a parent scope exists) and additional fields
+   * merged into every entry. Child loggers share the parent's sink(s).
+   */
+  child(scope: string, fields?: Record<string, unknown>): Logger;
+  /**
+   * Flush buffered writes. JSONL and Console sinks in v1 are synchronous,
+   * so this is a no-op — reserved for async sinks in a future wave.
+   */
+  flush(): void;
+}
+
+/**
+ * Sink interface implemented by ConsoleSink/JsonlSink/MultiSink in
+ * `./sinks.ts`. Logger.write() is expected to never throw; sinks SHOULD
+ * swallow IO errors and either retry or drop the line rather than
+ * surface failures to the caller.
+ */
+export interface Sink {
+  write(entry: LogEntry): void;
+  close(): void;
+}