@hegemonart/get-design-done 1.19.6 → 1.21.0

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;
+}

package/scripts/lib/pipeline-runner/human-gate.ts

@@ -0,0 +1,134 @@
+// scripts/lib/pipeline-runner/human-gate.ts — Plan 21-05 Task 4.
+//
+// Human-gate extraction + dispatch. The pipeline recognizes HTML-comment
+// markers of the form:
+//
+//   <!-- AWAIT_USER_GATE: name="..." -->
+//
+// emitted by skills that want to pause mid-session. When the
+// session-runner's `final_text` contains such a marker, the stage
+// handler maps the session's terminal status to `halted-human-gate`
+// and surfaces the gate name plus stdout tail.
+//
+// The pipeline driver (index.ts) then invokes `dispatchHumanGate`:
+//   * With `config.onHumanGate` → call it; its decision drives the
+//     driver.
+//   * Without a callback → default `{decision: 'stop'}` (safe default
+//     for headless operation — never proceed past a gate on autopilot).
+//   * Callback throws → caught; logged as warn; default `stop`.
+
+import { getLogger } from '../logger/index.ts';
+import type {
+  HumanGateDecision,
+  HumanGateInfo,
+  PipelineConfig,
+} from './types.ts';
+
+/**
+ * Regex for the canonical gate marker. Name is the first capture group;
+ * whitespace around `:` and inside the double quotes is tolerated.
+ *
+ * Intentionally LENIENT about surrounding whitespace (sanitizers may
+ * normalize around the comment), but STRICT about the core token
+ * shape so false positives (e.g., docs discussing AWAIT_USER_GATE)
+ * don't trip it — the marker must be inside an HTML comment AND
+ * carry a double-quoted `name`.
+ */
+const GATE_MARKER_RE =
+  /<!--\s*AWAIT_USER_GATE\s*:\s*name\s*=\s*"([^"]+)"\s*-->/;
+
+/**
+ * Extract the first `AWAIT_USER_GATE` marker from a session's stdout /
+ * final text. Returns `null` when no marker is present.
+ *
+ * Only the FIRST marker is returned — subsequent gates in the same
+ * session's output are ignored by design (one pause per stage).
+ */
+export function extractGateMarker(
+  stdout: string,
+): { readonly name: string } | null {
+  if (typeof stdout !== 'string' || stdout.length === 0) return null;
+  const m = GATE_MARKER_RE.exec(stdout);
+  if (m === null) return null;
+  const name: string | undefined = m[1];
+  if (name === undefined || name === '') return null;
+  return { name };
+}
+
+/**
+ * Dispatch a single human gate. Calls `config.onHumanGate` when
+ * supplied; otherwise returns `{decision: 'stop'}`.
+ *
+ * Never throws — callback exceptions are caught and converted into a
+ * `stop` decision, with a warn-level log entry for observability.
+ */
+export async function dispatchHumanGate(
+  info: HumanGateInfo,
+  config: PipelineConfig,
+): Promise<HumanGateDecision> {
+  if (config.onHumanGate === undefined) {
+    // No callback — default stop. We log this at debug (not warn)
+    // because it's a normal headless flow: the operator wanted to
+    // pause, and the orchestrator will resume via a fresh `run()`
+    // invocation with `resumeFrom` set.
+    try {
+      getLogger().debug('human-gate: no callback; default stop', {
+        stage: info.stage,
+        gateName: info.gateName,
+      });
+    } catch {
+      // Logger failures must not propagate.
+    }
+    return { decision: 'stop' };
+  }
+
+  try {
+    const decision = await config.onHumanGate(info);
+    // Validate the decision shape — callbacks may return partial
+    // objects from user code. Fall back to `stop` on anything invalid.
+    if (
+      decision === null ||
+      decision === undefined ||
+      typeof decision !== 'object'
+    ) {
+      try {
+        getLogger().warn('human-gate: callback returned non-object; defaulting to stop', {
+          stage: info.stage,
+          gateName: info.gateName,
+        });
+      } catch {
+        // Logger failures must not propagate.
+      }
+      return { decision: 'stop' };
+    }
+    if (decision.decision !== 'resume' && decision.decision !== 'stop') {
+      try {
+        getLogger().warn('human-gate: callback returned unknown decision; defaulting to stop', {
+          stage: info.stage,
+          gateName: info.gateName,
+          received: String(decision.decision),
+        });
+      } catch {
+        // Logger failures must not propagate.
+      }
+      return { decision: 'stop' };
+    }
+    // The decision's `payload` is optional; pass it through verbatim
+    // when present.
+    if (decision.decision === 'resume' && decision.payload !== undefined) {
+      return { decision: 'resume', payload: decision.payload };
+    }
+    return { decision: decision.decision };
+  } catch (err) {
+    try {
+      getLogger().warn('human-gate: callback threw; defaulting to stop', {
+        stage: info.stage,
+        gateName: info.gateName,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    } catch {
+      // Logger failures must not propagate.
+    }
+    return { decision: 'stop' };
+  }
+}