@hegemonart/get-design-done 1.31.0 → 1.31.5

package/scripts/lib/error-classifier.cjs

@@ -1,232 +1,29 @@
-// scripts/lib/error-classifier.cjs
-//
-// Plan 20-14 — classify raw errors into a recovery-action vocabulary.
-//
-// Plan 20-04 shipped the GDDError taxonomy (ValidationError /
-// StateConflictError / OperationFailedError). This module is one layer
-// lower: it maps LOW-LEVEL errors (fetch rejections, Anthropic API
-// responses, Node errno rejections) onto a small enum that recovery
-// code can switch on without needing to know which SDK produced the
-// error.
-//
-// Consumers (e.g. budget-enforcer retry, figma probe retry, MCP
-// transport) check `classify(err).reason` and decide whether to retry,
-// compress, surface, or fail.
+'use strict';
+// scripts/lib/error-classifier.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Classification rules — evaluated in order; first match wins:
-//   1. HTTP 429  OR  message ~ /rate.?limit/       → RATE_LIMITED      (retryable)
-//   2. HTTP 413  OR  /context.?(length|window|overflow)/
-//                OR  /context_length_exceeded/     → CONTEXT_OVERFLOW  (retryable with compression)
-//   3. HTTP 401/403                                → AUTH_ERROR        (NOT retryable)
-//   4. /tool not found|unknown tool/               → TOOL_NOT_FOUND    (NOT retryable)
-//   5. HTTP 5xx  OR  errno ECONNRESET/ETIMEDOUT/EAI_AGAIN/ECONNREFUSED
-//                OR  /network|timeout|socket/       → NETWORK_TRANSIENT (retryable)
-//   6. HTTP 4xx (non-auth, non-rate, non-overflow) → VALIDATION        (NOT retryable)
-//   7. HTTP >= 400 with no other match             → NETWORK_PERMANENT (NOT retryable)
-//   8. Anything else (null, undefined, plain Error) → UNKNOWN          (NOT retryable)
+// Thin deprecation shim. The real implementation moved to
+// sdk/primitives/error-classifier.cjs in Plan 31-5-04 (SDK consolidation).
+// This file is re-created at the OLD path so undocumented EXTERNAL importers
+// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
+// lib/error-classifier.cjs directly) keep working for one minor grace window.
 //
-// Rule order matters: the tool-not-found string can land inside
-// otherwise-validation-shaped errors, so it's checked early. Anthropic
-// "context_length_exceeded" returns HTTP 400 in some surfaces and HTTP
-// 413 in others — rule 2 catches it either way.
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
+// marker above.
 //
-// Reference: `reference/error-recovery.md` describes the protocol layer
-// that sits on top of this module.
-
-'use strict';
-
-/**
- * @readonly
- * @enum {string}
- */
-const FailoverReason = Object.freeze({
-  RATE_LIMITED: 'rate_limited',
-  CONTEXT_OVERFLOW: 'context_overflow',
-  AUTH_ERROR: 'auth_error',
-  NETWORK_TRANSIENT: 'network_transient',
-  NETWORK_PERMANENT: 'network_permanent',
-  TOOL_NOT_FOUND: 'tool_not_found',
-  VALIDATION: 'validation',
-  UNKNOWN: 'unknown',
-});
-
-/** Suggested actions per reason — keyed by FailoverReason. */
-const SUGGESTED_ACTIONS = Object.freeze({
-  [FailoverReason.RATE_LIMITED]:
-    'consult scripts/lib/rate-guard.cjs → blockUntilReady(provider); then retry with scripts/lib/jittered-backoff.cjs',
-  [FailoverReason.CONTEXT_OVERFLOW]:
-    'compress context (drop oldest non-system turns; target 50% reduction) and retry once',
-  [FailoverReason.AUTH_ERROR]:
-    'surface to user — do not retry; credentials or OAuth session need refresh',
-  [FailoverReason.NETWORK_TRANSIENT]:
-    'retry with scripts/lib/jittered-backoff.cjs; max 3 attempts',
-  [FailoverReason.NETWORK_PERMANENT]:
-    'surface to user; do not retry — endpoint is wrong or resource is gone',
-  [FailoverReason.TOOL_NOT_FOUND]:
-    'do not retry; verify tool name and MCP registration',
-  [FailoverReason.VALIDATION]:
-    'do not retry same input; surface validation detail to caller',
-  [FailoverReason.UNKNOWN]:
-    'surface to user — cannot determine safe recovery action',
-});
-
-/** Which reasons are safe to retry by policy. */
-const RETRYABLE = Object.freeze({
-  [FailoverReason.RATE_LIMITED]: true,
-  [FailoverReason.CONTEXT_OVERFLOW]: true,
-  [FailoverReason.NETWORK_TRANSIENT]: true,
-  [FailoverReason.AUTH_ERROR]: false,
-  [FailoverReason.NETWORK_PERMANENT]: false,
-  [FailoverReason.TOOL_NOT_FOUND]: false,
-  [FailoverReason.VALIDATION]: false,
-  [FailoverReason.UNKNOWN]: false,
-});
-
-/** Extract a numeric HTTP status from an error shape. Returns null on miss. */
-function statusOf(err) {
-  if (err === null || err === undefined) return null;
-  if (typeof err !== 'object') return null;
-  // Direct status / statusCode field.
-  if (Number.isFinite(err.status)) return Number(err.status);
-  if (Number.isFinite(err.statusCode)) return Number(err.statusCode);
-  // Fetch / node-fetch responses wrap status under .response.
-  if (err.response && typeof err.response === 'object') {
-    if (Number.isFinite(err.response.status)) return Number(err.response.status);
-    if (Number.isFinite(err.response.statusCode)) return Number(err.response.statusCode);
-  }
-  return null;
-}
-
-/** Extract a string message; tolerant of anything. */
-function messageOf(err) {
-  if (err === null || err === undefined) return '';
-  if (typeof err === 'string') return err;
-  if (typeof err === 'object') {
-    // Gather every string-ish field in priority order; join with ' | ' so
-    // classification regexes can match against any of them without the
-    // caller needing to know which SDK shaped the error. OpenAI-style
-    // wraps the interesting discriminator in `error.code` while keeping
-    // a generic top-level message; the join lets both contribute.
-    const parts = [];
-    if (typeof err.message === 'string' && err.message.length > 0) parts.push(err.message);
-    if (err.error && typeof err.error === 'object') {
-      if (typeof err.error.code === 'string') parts.push(err.error.code);
-      if (typeof err.error.type === 'string') parts.push(err.error.type);
-      if (typeof err.error.message === 'string') parts.push(err.error.message);
-    }
-    // Only use top-level `code` when it is NOT an errno (errnoOf handles
-    // those). Errnos always match /^E[A-Z0-9_]+$/, so filter them out.
-    if (typeof err.code === 'string' && !/^E[A-Z0-9_]+$/.test(err.code)) {
-      parts.push(err.code);
-    }
-    if (parts.length > 0) return parts.join(' | ');
-  }
-  return '';
-}
-
-/** Extract a low-level errno code (ECONNRESET, ETIMEDOUT, ...). */
-function errnoOf(err) {
-  if (err === null || err === undefined || typeof err !== 'object') return '';
-  if (typeof err.code === 'string' && /^E[A-Z0-9_]+$/.test(err.code)) return err.code;
-  // fetch native in newer Node wraps the cause
-  if (err.cause && typeof err.cause === 'object') {
-    const code = err.cause.code;
-    if (typeof code === 'string' && /^E[A-Z0-9_]+$/.test(code)) return code;
-  }
-  return '';
-}
-
-/**
- * Classify a raw error into a {@link FailoverReason}.
- *
- * @param {unknown} err
- * @returns {{reason: string, retryable: boolean, suggestedAction: string, raw: unknown}}
- */
-function classify(err) {
-  const status = statusOf(err);
-  const message = messageOf(err).toLowerCase();
-  const errno = errnoOf(err);
-
-  // 1. Rate limit.
-  if (status === 429 || /rate.?limit/.test(message) || /too many requests/.test(message)) {
-    return build(FailoverReason.RATE_LIMITED, err);
-  }
-
-  // 2. Context overflow. Anthropic returns 400 with type=invalid_request and
-  //    message containing "prompt is too long"; OpenAI returns 400 with
-  //    code=context_length_exceeded; some edge surfaces use 413.
-  if (
-    status === 413 ||
-    /context_length_exceeded/.test(message) ||
-    /context.{0,10}(length|window|overflow|too.?long)/.test(message) ||
-    /prompt is too long/.test(message) ||
-    /maximum context length/.test(message)
-  ) {
-    return build(FailoverReason.CONTEXT_OVERFLOW, err);
-  }
-
-  // 3. Auth.
-  if (status === 401 || status === 403) {
-    return build(FailoverReason.AUTH_ERROR, err);
-  }
-  if (
-    /not authenticated/.test(message) ||
-    /invalid[_ ]api[_ ]key/.test(message) ||
-    /unauthorized/.test(message) ||
-    /authentication/.test(message)
-  ) {
-    return build(FailoverReason.AUTH_ERROR, err);
-  }
-
-  // 4. Tool not found.
-  if (/tool not found/.test(message) || /unknown tool/.test(message) || /no such tool/.test(message)) {
-    return build(FailoverReason.TOOL_NOT_FOUND, err);
-  }
-
-  // 5. Network transient: 5xx or low-level errno.
-  if (typeof status === 'number' && status >= 500 && status < 600) {
-    return build(FailoverReason.NETWORK_TRANSIENT, err);
-  }
-  if (
-    errno === 'ECONNRESET' ||
-    errno === 'ETIMEDOUT' ||
-    errno === 'EAI_AGAIN' ||
-    errno === 'ECONNREFUSED' ||
-    errno === 'ENETUNREACH' ||
-    errno === 'EPIPE'
-  ) {
-    return build(FailoverReason.NETWORK_TRANSIENT, err);
-  }
-  if (/\bsocket\b/.test(message) || /network/.test(message) || /\btimeout\b/.test(message)) {
-    return build(FailoverReason.NETWORK_TRANSIENT, err);
-  }
-
-  // 6. Other 4xx → validation.
-  if (typeof status === 'number' && status >= 400 && status < 500) {
-    return build(FailoverReason.VALIDATION, err);
-  }
-
-  // 7. Other >= 400 (e.g. 6xx exotic gateway codes).
-  if (typeof status === 'number' && status >= 400) {
-    return build(FailoverReason.NETWORK_PERMANENT, err);
-  }
-
-  // 8. Fallthrough.
-  return build(FailoverReason.UNKNOWN, err);
-}
-
-function build(reason, raw) {
-  return {
-    reason,
-    retryable: RETRYABLE[reason] === true,
-    suggestedAction: SUGGESTED_ACTIONS[reason],
-    raw,
-  };
+// Emits a DeprecationWarning exactly ONCE per process: the module-level
+// `warned` flag plus Node's module cache (this file is evaluated once per
+// process regardless of how many times it is required).
+
+let warned = false;
+if (!warned) {
+  warned = true;
+  process.emitWarning(
+    'scripts/lib/error-classifier.cjs is deprecated; import sdk/primitives/error-classifier instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-module.exports = {
-  FailoverReason,
-  classify,
-  SUGGESTED_ACTIONS,
-  RETRYABLE,
-};
+module.exports = require('../../sdk/primitives/error-classifier.cjs');

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

@@ -1,197 +1,29 @@
-// scripts/lib/event-stream/index.ts — public API for the Phase 20+
-// telemetry stream (Plan 20-06, SDK-08).
+// scripts/lib/event-stream/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// 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).
+// Thin deprecation shim. The real implementation moved to
+// sdk/event-stream/index.ts in Plan 31-5-04 (SDK consolidation). This file
+// is re-created at the OLD path so undocumented EXTERNAL importers (anyone
+// who reached into node_modules/@hegemonart/get-design-done/scripts/lib/
+// event-stream/index.ts directly) keep working for one minor grace window.
 //
-// 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,
-  WaveStartedEvent,
-  WaveCompletedEvent,
-  BlockerAddedEvent,
-  DecisionAddedEvent,
-  MustHaveAddedEvent,
-  ParallelismVerdictEvent,
-  CostUpdateEvent,
-  RateLimitEvent,
-  ApiRetryEvent,
-  CompactBoundaryEvent,
-  McpProbeEvent,
-  ReflectionProposedEvent,
-  ConnectionStatusChangeEvent,
-  ToolCallStartedEvent,
-  ToolCallCompletedEvent,
-  AgentSpawnEvent,
-  AgentOutcomeEvent,
-  // Phase 27 / Plan 27-08 — peer-CLI delegation events (D-09).
-  RuntimeRole,
-  PeerCallStartedEvent,
-  PeerCallCompleteEvent,
-  PeerCallFailedEvent,
-} from './types.ts';
-export {
-  KNOWN_EVENT_TYPES,
-  // Phase 27 / Plan 27-08 — symbolic constants for peer-CLI event names.
-  PEER_CALL_STARTED,
-  PEER_CALL_COMPLETE,
-  PEER_CALL_FAILED,
-  PEER_CALL_EVENT_TYPES,
-  DEFAULT_RUNTIME_ROLE,
-} 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';
-export { readEvents, aggregate } from './reader.ts';
-export type { ReadEventsOptions, AggregateResult } from './reader.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);
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the
+// GDD-DEPRECATION-SHIM marker above.
+//
+// Runs under --experimental-strip-types, so `export *` re-export is
+// strip-types-clean.
+
+import { emitWarning } from 'node:process';
+
+let warned = false;
+if (!warned) {
+  warned = true;
+  emitWarning(
+    'scripts/lib/event-stream/index.ts is deprecated; import sdk/event-stream instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-/** Convenience: subscribe to every event on the default bus. */
-export function subscribeAll(handler: EventHandler<BaseEvent>): Unsubscribe {
-  return getBus().subscribeAll(handler);
-}
+export * from '../../../sdk/event-stream/index.ts';