@hegemonart/get-design-done 1.19.6 → 1.21.0

package/scripts/lib/lockfile.cjs

@@ -0,0 +1,177 @@
+// scripts/lib/lockfile.cjs
+//
+// Plan 20-14 — PID+timestamp sibling lockfile for `.cjs` consumers.
+//
+// Algorithm mirrors scripts/lib/gdd-state/lockfile.ts (Plan 20-01):
+//   Lock path:     `${target}.lock`
+//   Payload:       { pid: number, host: string, acquired_at: ISO8601 }
+//   Acquire:       atomic `writeFileSync(..., { flag: 'wx' })`
+//   Stale rule:    pid dead (ESRCH via `kill(pid, 0)`) OR `acquired_at` older
+//                  than `staleMs` OR unparseable payload
+//   Release:       unlink; ENOENT is not an error; idempotent
+//
+// Windows: AV scanners and file-indexers can hold a file briefly after
+// close. `wx` create may fail with EPERM/EBUSY even when the target is
+// free; we treat these as transient and loop (same code path as EEXIST).
+//
+// Dependency-cycle note: Plan 20-14's rate-guard + iteration-budget
+// consume this module, and both are required to stay dependency-light so
+// that hooks/budget-enforcer.ts can import them without dragging the
+// gdd-state MCP graph along. Hence this standalone .cjs port instead of
+// calling the .ts version.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+
+const DEFAULT_STALE_MS = 60_000;
+const DEFAULT_MAX_WAIT_MS = 5_000;
+const DEFAULT_POLL_MS = 50;
+
+/**
+ * Acquire an advisory lock at `${path}.lock`. Returns an idempotent
+ * async release function.
+ *
+ * @param {string} path path being locked (we append `.lock`)
+ * @param {object} [opts]
+ * @param {number} [opts.staleMs]   ms after which an existing lock is stale. Default 60_000.
+ * @param {number} [opts.maxWaitMs] total ms to wait before throwing. Default 5_000.
+ * @param {number} [opts.pollMs]    ms between retry attempts. Default 50.
+ * @returns {Promise<() => Promise<void>>} release function
+ * @throws {Error} with name === 'LockAcquisitionError' when maxWaitMs elapses
+ */
+async function acquire(path, opts) {
+  const o = opts || {};
+  const staleMs = Number.isFinite(o.staleMs) ? o.staleMs : DEFAULT_STALE_MS;
+  const maxWaitMs = Number.isFinite(o.maxWaitMs) ? o.maxWaitMs : DEFAULT_MAX_WAIT_MS;
+  const pollMs = Number.isFinite(o.pollMs) ? o.pollMs : DEFAULT_POLL_MS;
+
+  if (staleMs < 0 || maxWaitMs < 0 || pollMs < 0) {
+    throw new Error(
+      `lockfile.acquire: invalid options (staleMs=${staleMs}, maxWaitMs=${maxWaitMs}, pollMs=${pollMs})`,
+    );
+  }
+
+  const lockPath = `${path}.lock`;
+  const payload = JSON.stringify({
+    pid: process.pid,
+    host: os.hostname(),
+    acquired_at: new Date().toISOString(),
+  });
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      fs.writeFileSync(lockPath, payload, { flag: 'wx', encoding: 'utf8' });
+      return makeRelease(lockPath);
+    } catch (err) {
+      const code = err && typeof err === 'object' ? err.code : undefined;
+      if (code !== 'EEXIST' && code !== 'EPERM' && code !== 'EBUSY') {
+        throw err;
+      }
+      // Try to read the current holder; if it vanished between EEXIST and
+      // read, loop immediately.
+      const existing = readLockSafe(lockPath);
+      if (existing === null) continue;
+
+      const parsed = parseLock(existing);
+      if (parsed === null || isStale(parsed, staleMs)) {
+        // Clear stale/garbage lock; race-tolerant — if it's already gone
+        // we'll just get ENOENT, no-op.
+        try { fs.unlinkSync(lockPath); } catch { /* ignore */ }
+        continue;
+      }
+
+      if (Date.now() - startedAt >= maxWaitMs) {
+        const e = new Error(
+          `lockfile: failed to acquire ${lockPath} within ${maxWaitMs}ms (held by ${existing})`,
+        );
+        e.name = 'LockAcquisitionError';
+        e.lockPath = lockPath;
+        e.holder = existing;
+        e.waitedMs = Date.now() - startedAt;
+        throw e;
+      }
+      await sleep(pollMs);
+    }
+  }
+}
+
+function makeRelease(lockPath) {
+  let released = false;
+  return async function release() {
+    if (released) return;
+    released = true;
+    try {
+      fs.unlinkSync(lockPath);
+    } catch (err) {
+      const code = err && typeof err === 'object' ? err.code : undefined;
+      if (code === 'ENOENT') return; // idempotent — already gone
+      if (code === 'EPERM' || code === 'EBUSY') {
+        // Windows AV/indexer: retry once.
+        await sleep(50);
+        try {
+          if (fs.existsSync(lockPath)) fs.unlinkSync(lockPath);
+        } catch { /* give up; stale-detection will reclaim */ }
+        return;
+      }
+      // Any other errno: swallow. Best-effort cleanup; stale-age check
+      // will eventually reclaim the lock.
+    }
+  };
+}
+
+function readLockSafe(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    if (code === 'ENOENT') return null;
+    return '<unreadable>';
+  }
+}
+
+function parseLock(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    if (
+      obj && typeof obj === 'object' &&
+      typeof obj.pid === 'number' &&
+      typeof obj.host === 'string' &&
+      typeof obj.acquired_at === 'string'
+    ) {
+      return obj;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function isStale(payload, staleMs) {
+  if (!isPidAlive(payload.pid, payload.host)) return true;
+  const t = Date.parse(payload.acquired_at);
+  if (!Number.isFinite(t)) return true;
+  return Date.now() - t > staleMs;
+}
+
+function isPidAlive(pid, host) {
+  if (host !== os.hostname()) return true; // can't introspect other hosts
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0); // signal 0 = validate, don't deliver
+    return true;
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    if (code === 'ESRCH') return false;
+    // EPERM / EACCES: process exists but is unsignalable; treat as alive.
+    return true;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = { acquire };

package/scripts/lib/lockfile.d.cts

@@ -0,0 +1,21 @@
+// scripts/lib/lockfile.d.cts — types for lockfile.cjs.
+
+export interface AcquireOptions {
+  /** ms after which an existing lock is considered stale. Default 60_000. */
+  staleMs?: number;
+  /** total ms to wait before throwing LockAcquisitionError. Default 5_000. */
+  maxWaitMs?: number;
+  /** ms between retry attempts. Default 50. */
+  pollMs?: number;
+}
+
+/** Release function returned by `acquire()`. Idempotent. */
+export type LockRelease = () => Promise<void>;
+
+/**
+ * Acquire an advisory lock at `${path}.lock`. Returns a release function.
+ *
+ * @throws Error with `name === 'LockAcquisitionError'` when `maxWaitMs`
+ *   elapses without acquiring.
+ */
+export function acquire(path: string, opts?: AcquireOptions): Promise<LockRelease>;

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