@hegemonart/get-design-done 1.19.6 → 1.21.0

package/scripts/lib/explore-parallel-runner/synthesizer.ts

@@ -0,0 +1,295 @@
+// scripts/lib/explore-parallel-runner/synthesizer.ts — Plan 21-06 (SDK-18).
+//
+// Incremental synthesizer driver. Watches `.design/map/<name>.md` for
+// each mapper output, detects stable-size writes, and spawns a single
+// synthesizer session with a concatenated prompt when all files are
+// stable (or timeoutMs has elapsed).
+//
+// Design contract (as documented in the plan — "streaming-session
+// injection contract"):
+//
+//   1. Wait for all mapper files to stabilize OR timeoutMs.
+//   2. Read each stable file's content, concatenate under the synth
+//      prompt, mark missing/unstable files explicitly.
+//   3. Spawn session-runner with the composite prompt.
+//
+// A fuller mid-session injection protocol would require Agent SDK
+// multi-turn user-message injection; that's deferred to Phase 22.
+// This implementation still satisfies the "streaming" acceptance: we
+// DO NOT block the caller's mappers while waiting, and the
+// synthesizer's prompt is composed dynamically from ready files.
+//
+// Stable-size detection: compare `statSync(path).size` across two
+// consecutive polls. Unchanged size + still-present file → stable.
+
+import { readFileSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+
+import { run as defaultSessionRun } from '../session-runner/index.ts';
+import type {
+  BudgetCap,
+  SessionResult,
+  SessionRunnerOptions,
+} from '../session-runner/types.ts';
+
+export interface SynthesizeStreamingArgs {
+  readonly mapperNames: readonly string[];
+  readonly mapperOutputPaths: readonly string[];
+  readonly synthesizerPrompt: string;
+  readonly budget: BudgetCap;
+  readonly maxTurns: number;
+  readonly runOverride?: (
+    opts: SessionRunnerOptions,
+  ) => Promise<SessionResult>;
+  readonly cwd: string;
+  /** Polling interval for stable-size detection (ms). Default 200. */
+  readonly pollIntervalMs?: number;
+  /** Total watch timeout (ms). Default 600_000 (10 min). */
+  readonly timeoutMs?: number;
+}
+
+export interface SynthesizeStreamingResult {
+  readonly status: 'completed' | 'error' | 'timeout' | 'skipped';
+  readonly output_path: string;
+  readonly usage: {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly usd_cost: number;
+  };
+  readonly files_fed: readonly string[];
+  readonly error?: { readonly code: string; readonly message: string };
+}
+
+const DEFAULT_POLL_MS = 200;
+const DEFAULT_TIMEOUT_MS = 600_000;
+
+/**
+ * Probe a single mapper output path. Returns the current byte size when
+ * the path is a readable file, `null` when absent or unreadable.
+ */
+function probeSize(path: string): number | null {
+  try {
+    const st = statSync(path);
+    if (!st.isFile()) return null;
+    return st.size;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wait until every `mapperOutputPaths[i]` is present AND has stable size
+ * across two consecutive polls — OR `timeoutMs` elapses. Returns the
+ * list of paths that stabilized in time.
+ *
+ * We allow `pollIntervalMs` to be explicitly `0` in tests (synchronous
+ * ready state). The minimum practical interval is still sub-millisecond
+ * — we never block the event loop longer than Node's setTimeout jitter.
+ */
+async function waitForStableFiles(
+  paths: readonly string[],
+  pollIntervalMs: number,
+  timeoutMs: number,
+): Promise<readonly string[]> {
+  if (paths.length === 0) return Object.freeze([]);
+
+  const deadline: number = Date.now() + timeoutMs;
+  const lastSize: Map<string, number | null> = new Map();
+  const stable: Set<string> = new Set();
+
+  // Prime: record current sizes.
+  for (const p of paths) {
+    lastSize.set(p, probeSize(p));
+  }
+
+  while (stable.size < paths.length) {
+    if (Date.now() >= deadline) break;
+    await sleep(pollIntervalMs);
+
+    for (const p of paths) {
+      if (stable.has(p)) continue;
+      const cur: number | null = probeSize(p);
+      const prev: number | null | undefined = lastSize.get(p);
+      if (cur !== null && prev !== null && prev !== undefined && cur === prev && cur >= 0) {
+        // Also require file exists (already enforced by non-null cur).
+        // And prevent 0-byte false positives by requiring at least one
+        // prior observation with a non-null size that matches.
+        stable.add(p);
+      }
+      lastSize.set(p, cur);
+    }
+  }
+
+  return Object.freeze(
+    paths.filter((p) => stable.has(p)),
+  );
+}
+
+/** Promise-returning sleep. 0 ms resolves on next microtask. */
+function sleep(ms: number): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Compose the synthesizer prompt from the base instructions + each
+ * stable mapper's file content, plus a note listing mappers that
+ * weren't ready.
+ */
+function composePrompt(args: {
+  basePrompt: string;
+  mapperNames: readonly string[];
+  mapperOutputPaths: readonly string[];
+  readyPaths: readonly string[];
+}): { composed: string; filesFed: readonly string[] } {
+  const readySet: Set<string> = new Set(args.readyPaths);
+  const readBlocks: string[] = [];
+  const filesFed: string[] = [];
+  const missing: string[] = [];
+
+  for (let i = 0; i < args.mapperNames.length; i += 1) {
+    const name: string = args.mapperNames[i] ?? `mapper-${i}`;
+    const path: string = args.mapperOutputPaths[i] ?? '';
+    if (readySet.has(path)) {
+      let content = '';
+      try {
+        content = readFileSync(path, 'utf8');
+      } catch {
+        // File disappeared between stability check and read — treat
+        // as missing rather than erroring.
+        missing.push(name);
+        continue;
+      }
+      readBlocks.push(`## Mapper: ${name}\n\n<path>${path}</path>\n\n${content}`);
+      filesFed.push(path);
+    } else {
+      missing.push(name);
+    }
+  }
+
+  const missingNote: string =
+    missing.length > 0
+      ? `\n\n<missing_mappers>\n${missing.join('\n')}\n</missing_mappers>\n`
+      : '';
+
+  const mapperSection: string =
+    readBlocks.length > 0
+      ? `\n\n<mapper_outputs>\n\n${readBlocks.join('\n\n---\n\n')}\n\n</mapper_outputs>`
+      : '\n\n<mapper_outputs>(none ready)</mapper_outputs>';
+
+  return {
+    composed: `${args.basePrompt}${missingNote}${mapperSection}`,
+    filesFed: Object.freeze(filesFed),
+  };
+}
+
+/**
+ * Public driver. Wait for mapper outputs to stabilize (or timeout),
+ * spawn the synthesizer session with the composite prompt, return
+ * terminal status + usage + fed-file list.
+ *
+ * Never throws. On session error, returns status 'error' with populated
+ * `.error`. On stability-wait timeout with NO files ready, returns
+ * status 'timeout' + empty `files_fed` (session NOT spawned).
+ */
+export async function synthesizeStreaming(
+  args: SynthesizeStreamingArgs,
+): Promise<SynthesizeStreamingResult> {
+  const outputPath: string = resolvePath(args.cwd, '.design/DESIGN-PATTERNS.md');
+  const pollIntervalMs: number = args.pollIntervalMs ?? DEFAULT_POLL_MS;
+  const timeoutMs: number = args.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  // Resolve each mapper output path against cwd so callers can pass
+  // relative paths (e.g. '.design/map/token.md').
+  const absPaths: readonly string[] = args.mapperOutputPaths.map((p) =>
+    resolvePath(args.cwd, p),
+  );
+
+  const readyPaths: readonly string[] = await waitForStableFiles(
+    absPaths,
+    pollIntervalMs,
+    timeoutMs,
+  );
+
+  // If nothing stabilized within the timeout, short-circuit — don't
+  // burn a session with zero input. Callers log a warning.
+  if (readyPaths.length === 0 && absPaths.length > 0) {
+    return Object.freeze({
+      status: 'timeout',
+      output_path: outputPath,
+      usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      files_fed: Object.freeze([]),
+    });
+  }
+
+  const { composed, filesFed } = composePrompt({
+    basePrompt: args.synthesizerPrompt,
+    mapperNames: args.mapperNames,
+    mapperOutputPaths: absPaths,
+    readyPaths,
+  });
+
+  const runFn: (o: SessionRunnerOptions) => Promise<SessionResult> =
+    args.runOverride ?? defaultSessionRun;
+
+  const runnerOpts: SessionRunnerOptions = {
+    prompt: composed,
+    stage: 'explore',
+    budget: args.budget,
+    turnCap: { maxTurns: args.maxTurns },
+  };
+
+  let sessionResult: SessionResult;
+  try {
+    sessionResult = await runFn(runnerOpts);
+  } catch (err) {
+    const message: string = err instanceof Error ? err.message : String(err);
+    return Object.freeze({
+      status: 'error',
+      output_path: outputPath,
+      usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      files_fed: filesFed,
+      error: Object.freeze({ code: 'RUN_THREW', message }),
+    });
+  }
+
+  // Translate SessionResult → SynthesizeStreamingResult.
+  const usage = {
+    input_tokens: sessionResult.usage.input_tokens,
+    output_tokens: sessionResult.usage.output_tokens,
+    usd_cost: sessionResult.usage.usd_cost,
+  };
+
+  // Determine terminal status. The plan allows the timeout outcome to
+  // bubble through even when a session DID spawn with partial inputs;
+  // we collapse to 'completed' when the session finished cleanly, even
+  // if not all files were ready. Callers inspect `files_fed.length <
+  // mapperNames.length` to detect partial coverage.
+  if (sessionResult.status !== 'completed') {
+    const err = sessionResult.error ?? {
+      code: sessionResult.status.toUpperCase(),
+      message: `synth session ended with status ${sessionResult.status}`,
+    };
+    return Object.freeze({
+      status: 'error',
+      output_path: outputPath,
+      usage,
+      files_fed: filesFed,
+      error: Object.freeze({ code: err.code, message: err.message }),
+    });
+  }
+
+  // Happy path.
+  //
+  // If the caller provided 0 mapper paths, we didn't wait and didn't
+  // feed anything — that's the "synthesizer invoked with pre-rendered
+  // prompt" shape (used by the run() orchestrator's empty-mapper
+  // short-circuit elsewhere, though `run()` skips synth entirely in
+  // that case).
+  return Object.freeze({
+    status: 'completed',
+    output_path: outputPath,
+    usage,
+    files_fed: filesFed,
+  });
+}

package/scripts/lib/explore-parallel-runner/types.ts

@@ -0,0 +1,139 @@
+// scripts/lib/explore-parallel-runner/types.ts — Plan 21-06 (SDK-18).
+//
+// Public type surface for the 4-mapper parallel explore runner. Consumers
+// import from ./index.ts (the barrel); this file carries the type graph
+// so mappers.ts / synthesizer.ts / index.ts can share a single source of
+// truth without cyclic imports.
+//
+// Design notes:
+//   * `MapperName` is a closed union. Extending it requires touching the
+//     DEFAULT_MAPPERS table in index.ts, so a type-level addition forces
+//     a compile error on any registry-consuming site.
+//   * `ExploreRunnerOptions.runOverride` mirrors `SessionRunnerOptions.queryOverride`
+//     at a higher altitude — it replaces the whole `session-runner.run()`
+//     call per-mapper/per-synthesizer. Tests build a deterministic
+//     `runOverride` that returns canned `SessionResult`s without touching
+//     the Agent SDK.
+//   * All numeric fields in usage/outcome default to 0 on unpopulated
+//     sessions; we never surface `undefined` in `total_usage` math.
+//   * `parallel_count` + `serial_count` together === `specs.length`
+//     (after parallelism_safe partitioning). Synthesizer is counted
+//     separately under `.synthesizer`.
+
+import type {
+  BudgetCap,
+  SessionResult,
+  SessionRunnerOptions,
+} from '../session-runner/types.ts';
+
+/** Closed union of mapper roster. Changing this forces a compile-time
+ *  touch of `DEFAULT_MAPPERS` in index.ts — a deliberate choke point
+ *  so the roster stays the Phase-21 Locked 4. */
+export type MapperName =
+  | 'token'
+  | 'component-taxonomy'
+  | 'a11y'
+  | 'visual-hierarchy';
+
+/**
+ * A single mapper invocation specification. The runner does NOT own
+ * prompt construction — callers assemble the prompt body from their
+ * `DESIGN-CONTEXT.md` + roster scaffolding and pass it through here.
+ */
+export interface MapperSpec {
+  /** Mapper identifier — also used in event payloads + log scopes. */
+  readonly name: MapperName;
+  /** Path to `agents/<name>.md`. Missing file is tolerated (stage default). */
+  readonly agentPath: string;
+  /** Expected mapper output file, e.g. `.design/map/token.md`. */
+  readonly outputPath: string;
+  /** Per-mapper prompt body passed to session-runner. */
+  readonly prompt: string;
+}
+
+/**
+ * Terminal record for a single mapper invocation. `output_exists` /
+ * `output_bytes` are captured AFTER the session terminates — if the
+ * mapper wrote its file but the session errored in cleanup, we still
+ * surface the file's presence.
+ *
+ * `error` is populated iff `status === 'error'`.
+ */
+export interface MapperOutcome {
+  readonly name: MapperName;
+  readonly status: 'completed' | 'error' | 'skipped';
+  readonly output_exists: boolean;
+  readonly output_bytes: number;
+  readonly usage: {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly usd_cost: number;
+  };
+  readonly duration_ms: number;
+  readonly error?: { readonly code: string; readonly message: string };
+}
+
+/**
+ * Caller-facing run options for the explore runner. Most fields mirror
+ * session-runner's BudgetCap / turn caps but applied per-mapper.
+ *
+ * `runOverride`: when supplied, the runner invokes this instead of the
+ * real `session-runner.run()`. Tests build overrides that return canned
+ * `SessionResult`s without touching the Agent SDK.
+ */
+export interface ExploreRunnerOptions {
+  /** Override the mapper roster. Defaults to DEFAULT_MAPPERS (the locked 4). */
+  readonly mappers?: readonly MapperSpec[];
+  /** Per-mapper hard budget cap. Shared envelope — does NOT pool across mappers. */
+  readonly budget: BudgetCap;
+  /** Per-mapper turn cap. */
+  readonly maxTurnsPerMapper: number;
+  /** Max concurrent mappers. Defaults to 4 (the full locked roster). */
+  readonly concurrency?: number;
+  /** Prompt body for the synthesizer session. */
+  readonly synthesizerPrompt: string;
+  /** Budget cap for the synthesizer session. */
+  readonly synthesizerBudget: BudgetCap;
+  /** Turn cap for the synthesizer session. */
+  readonly synthesizerMaxTurns: number;
+  /**
+   * Replace the session-runner.run() call entirely (test injection). Each
+   * mapper + the synthesizer each consume one invocation of this override.
+   */
+  readonly runOverride?: (
+    opts: SessionRunnerOptions,
+  ) => Promise<SessionResult>;
+  /** Current working directory used for path resolution (fixtures / agent files). */
+  readonly cwd?: string;
+  /** Override the file-stability polling interval (ms). Default 200. */
+  readonly pollIntervalMs?: number;
+  /** Override the file-watch timeout (ms). Default 600_000 (10 min). */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Terminal record for the whole runner invocation. `parallel_count` +
+ * `serial_count` === mappers.length (after parallelism_safe partitioning).
+ * `total_usage` aggregates mappers + synthesizer.
+ */
+export interface ExploreRunnerResult {
+  readonly mappers: readonly MapperOutcome[];
+  readonly synthesizer: {
+    readonly status: 'completed' | 'error' | 'skipped' | 'timeout';
+    readonly output_path: string;
+    readonly usage: {
+      readonly input_tokens: number;
+      readonly output_tokens: number;
+      readonly usd_cost: number;
+    };
+    readonly files_fed: readonly string[];
+    readonly error?: { readonly code: string; readonly message: string };
+  };
+  readonly parallel_count: number;
+  readonly serial_count: number;
+  readonly total_usage: {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly usd_cost: number;
+  };
+}

package/scripts/lib/gdd-errors/classification.ts

@@ -0,0 +1,124 @@
+// scripts/lib/gdd-errors/classification.ts — error classification + MCP helpers.
+//
+// Two exports:
+//   * classify(err)      — normalize any thrown value into an
+//                          ErrorClassification descriptor
+//   * toToolError(err)   — wrap into the shape MCP tool handlers return
+//                          inside data.error
+//
+// These helpers are the bridge between the taxonomy (index.ts) and the
+// MCP tool layer (plan 20-05 wires them into all 11 tool handlers).
+
+import {
+  GDDError,
+  ValidationError,
+  StateConflictError,
+  OperationFailedError,
+} from './index.ts';
+
+/**
+ * The four-valued classification of any error value. `kind === 'unknown'`
+ * means the thrown value was not a GDDError — either a plain Error or a
+ * non-Error value (string, number, etc.).
+ *
+ * Flag semantics:
+ *   shouldThrow=true   — caller should propagate (or rethrow) this error;
+ *                        it represents an invariant violation or bad input
+ *   shouldThrow=false  — caller should embed this in data.error and
+ *                        return normally (expected branching failure)
+ *   retryable=true     — upstream may retry after a backoff (only
+ *                        StateConflictError; e.g. lockfile contention)
+ */
+export interface ErrorClassification {
+  kind: 'validation' | 'state_conflict' | 'operation_failed' | 'unknown';
+  shouldThrow: boolean;
+  retryable: boolean;
+  code: string;
+  message: string;
+}
+
+/**
+ * Classify any value thrown at us. Robust to non-Error throws (strings,
+ * numbers, plain objects) — returns `kind: 'unknown'` with a sensible
+ * message rather than blowing up.
+ */
+export function classify(err: unknown): ErrorClassification {
+  if (err instanceof ValidationError) {
+    return {
+      kind: 'validation',
+      shouldThrow: true,
+      retryable: false,
+      code: err.code,
+      message: err.message,
+    };
+  }
+  if (err instanceof StateConflictError) {
+    return {
+      kind: 'state_conflict',
+      shouldThrow: true,
+      retryable: true,
+      code: err.code,
+      message: err.message,
+    };
+  }
+  if (err instanceof OperationFailedError) {
+    return {
+      kind: 'operation_failed',
+      shouldThrow: false,
+      retryable: false,
+      code: err.code,
+      message: err.message,
+    };
+  }
+  if (err instanceof Error) {
+    return {
+      kind: 'unknown',
+      shouldThrow: true,
+      retryable: false,
+      code: 'UNKNOWN',
+      message: err.message,
+    };
+  }
+  return {
+    kind: 'unknown',
+    shouldThrow: true,
+    retryable: false,
+    code: 'UNKNOWN',
+    message: String(err),
+  };
+}
+
+/**
+ * Shape MCP tool handlers return inside `data.error`. The `context`
+ * key is only present when the error is a GDDError instance — plain
+ * errors don't carry structured context, and we intentionally don't
+ * fabricate one (the `code` + `message` pair is sufficient).
+ */
+export interface ToolErrorPayload {
+  error: {
+    code: string;
+    message: string;
+    kind: ErrorClassification['kind'];
+    context?: Readonly<Record<string, unknown>>;
+  };
+}
+
+/**
+ * Convert any error into the shape MCP tool handlers return in
+ * data.error. Plan 20-05 wires this into the 11 tool handlers; Plan
+ * 20-06 emits it as an `error` event on the telemetry stream.
+ */
+export function toToolError(err: unknown): ToolErrorPayload {
+  const c = classify(err);
+  const out: ToolErrorPayload = {
+    error: {
+      code: c.code,
+      message: c.message,
+      kind: c.kind,
+    },
+  };
+  if (err instanceof GDDError) {
+    out.error.context = err.context;
+  }
+  return out;
+}