@hegemonart/get-design-done 1.19.6 → 1.21.0

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

@@ -0,0 +1,294 @@
+// scripts/lib/explore-parallel-runner/index.ts — Plan 21-06 (SDK-18).
+//
+// Public surface:
+//
+//   run(opts: ExploreRunnerOptions): Promise<ExploreRunnerResult>
+//   DEFAULT_MAPPERS — the locked Phase-21 4-mapper roster (frozen).
+//   isParallelismSafe, spawnMapper, spawnMappersParallel (from mappers.ts)
+//   synthesizeStreaming (from synthesizer.ts)
+//   Types (from types.ts) — MapperName, MapperSpec, MapperOutcome,
+//     ExploreRunnerOptions, ExploreRunnerResult.
+//
+// Algorithm:
+//   1. specs = opts.mappers ?? DEFAULT_MAPPERS.
+//   2. Partition by isParallelismSafe(spec.agentPath).
+//   3. Run safe mappers via spawnMappersParallel(concurrency).
+//   4. Run unsafe mappers sequentially (tail phase).
+//   5. Run synthesizer via synthesizeStreaming.
+//   6. Aggregate total_usage = sum mapper + synthesizer.
+//   7. Emit logger + explore.runner.* lifecycle events.
+//   8. Return ExploreRunnerResult.
+//
+// Empty specs short-circuits: no mappers spawned, synthesizer skipped,
+// returns an all-zero result.
+
+import { resolve as resolvePath } from 'node:path';
+
+import { getLogger } from '../logger/index.ts';
+
+import {
+  isParallelismSafe,
+  spawnMapper,
+  spawnMappersParallel,
+} from './mappers.ts';
+import { synthesizeStreaming } from './synthesizer.ts';
+import type {
+  ExploreRunnerOptions,
+  ExploreRunnerResult,
+  MapperOutcome,
+  MapperSpec,
+} from './types.ts';
+
+// Re-exports.
+export type {
+  MapperName,
+  MapperSpec,
+  MapperOutcome,
+  ExploreRunnerOptions,
+  ExploreRunnerResult,
+} from './types.ts';
+export {
+  isParallelismSafe,
+  spawnMapper,
+  spawnMappersParallel,
+} from './mappers.ts';
+export { synthesizeStreaming } from './synthesizer.ts';
+
+// ---------------------------------------------------------------------------
+// DEFAULT_MAPPERS — locked Phase-21 roster
+// ---------------------------------------------------------------------------
+
+/**
+ * Locked 4-mapper roster for the explore stage. Frozen end-to-end so
+ * consumers can't mutate entries; override via ExploreRunnerOptions.mappers.
+ *
+ * Agent paths use the exact filenames from `agents/` (as of Phase 21):
+ *   token-mapper.md, component-taxonomy-mapper.md, a11y-mapper.md,
+ *   visual-hierarchy-mapper.md.
+ *
+ * When an agent file is missing, session-runner scope computation
+ * gracefully falls through to the stage default (see mappers.ts).
+ */
+export const DEFAULT_MAPPERS: readonly MapperSpec[] = Object.freeze([
+  Object.freeze({
+    name: 'token' as const,
+    agentPath: 'agents/token-mapper.md',
+    outputPath: '.design/map/token.md',
+    prompt:
+      'Enumerate every design token found in the UI source: colors, typography, spacing, radii, shadows, motion durations. Output to .design/map/token.md as a canonical token inventory.',
+  }),
+  Object.freeze({
+    name: 'component-taxonomy' as const,
+    agentPath: 'agents/component-taxonomy-mapper.md',
+    outputPath: '.design/map/component-taxonomy.md',
+    prompt:
+      'Enumerate component archetypes and their variants. Output to .design/map/component-taxonomy.md — one entry per archetype with variant list, slot inventory, and usage count.',
+  }),
+  Object.freeze({
+    name: 'a11y' as const,
+    agentPath: 'agents/a11y-mapper.md',
+    outputPath: '.design/map/a11y.md',
+    prompt:
+      'WCAG-axis scan: contrast ratios, keyboard navigation, ARIA semantics, focus management, reduced-motion respect. Output to .design/map/a11y.md — one section per axis with findings.',
+  }),
+  Object.freeze({
+    name: 'visual-hierarchy' as const,
+    agentPath: 'agents/visual-hierarchy-mapper.md',
+    outputPath: '.design/map/visual-hierarchy.md',
+    prompt:
+      'Describe z-order, focal points, and attention grammar. Output to .design/map/visual-hierarchy.md — one section per surface describing layering, emphasis, and scan path.',
+  }),
+]);
+
+// ---------------------------------------------------------------------------
+// run — main orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn the 4 mapper sessions (parallel) + the synthesizer (sequential
+ * after mappers become stable), aggregate usage, emit lifecycle events,
+ * return terminal ExploreRunnerResult.
+ *
+ * Contract:
+ *   * Never throws. All failure modes land as outcomes / synth status.
+ *   * Individual mapper errors do NOT abort other mappers.
+ *   * parallelism_safe: false mappers run serially AFTER the safe batch.
+ *   * total_usage aggregates mappers + synthesizer.
+ */
+export async function run(
+  opts: ExploreRunnerOptions,
+): Promise<ExploreRunnerResult> {
+  const specs: readonly MapperSpec[] = opts.mappers ?? DEFAULT_MAPPERS;
+  const cwd: string = opts.cwd ?? process.cwd();
+  const concurrency: number = opts.concurrency ?? 4;
+
+  const logger = getLogger().child('explore.runner');
+
+  const outputPath: string = resolvePath(cwd, '.design/DESIGN-PATTERNS.md');
+
+  logger.info('explore.runner.started', {
+    mapper_count: specs.length,
+    concurrency,
+  });
+
+  // Empty-spec short-circuit — no mappers, no synthesizer, zero usage.
+  if (specs.length === 0) {
+    logger.info('explore.runner.completed', {
+      parallel_count: 0,
+      serial_count: 0,
+      synthesizer_status: 'skipped',
+      total_usd_cost: 0,
+    });
+    return Object.freeze({
+      mappers: Object.freeze([]),
+      synthesizer: Object.freeze({
+        status: 'skipped' as const,
+        output_path: outputPath,
+        usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+        files_fed: Object.freeze([]),
+      }),
+      parallel_count: 0,
+      serial_count: 0,
+      total_usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+    });
+  }
+
+  // --- Partition specs by parallelism_safe frontmatter ---------------------
+  const safeSpecs: MapperSpec[] = [];
+  const serialSpecs: MapperSpec[] = [];
+  for (const spec of specs) {
+    const resolvedAgentPath: string = resolvePath(cwd, spec.agentPath);
+    if (isParallelismSafe(resolvedAgentPath)) {
+      safeSpecs.push(spec);
+    } else {
+      serialSpecs.push(spec);
+    }
+  }
+
+  // --- Parallel batch ------------------------------------------------------
+  const parallelOutcomes: readonly MapperOutcome[] =
+    safeSpecs.length > 0
+      ? await spawnMappersParallel(safeSpecs, {
+          concurrency,
+          budget: opts.budget,
+          maxTurns: opts.maxTurnsPerMapper,
+          cwd,
+          ...(opts.runOverride !== undefined ? { runOverride: opts.runOverride } : {}),
+        })
+      : Object.freeze([]);
+
+  for (const o of parallelOutcomes) {
+    logger.info('explore.runner.mapper_done', {
+      mapper: o.name,
+      status: o.status,
+      duration_ms: o.duration_ms,
+      output_exists: o.output_exists,
+      output_bytes: o.output_bytes,
+      mode: 'parallel',
+    });
+  }
+
+  // --- Serial tail --------------------------------------------------------
+  const serialOutcomes: MapperOutcome[] = [];
+  for (const spec of serialSpecs) {
+    const spawnOpts: Parameters<typeof spawnMapper>[1] = {
+      budget: opts.budget,
+      maxTurns: opts.maxTurnsPerMapper,
+      cwd,
+      ...(opts.runOverride !== undefined ? { runOverride: opts.runOverride } : {}),
+    };
+    const outcome = await spawnMapper(spec, spawnOpts);
+    serialOutcomes.push(outcome);
+    logger.info('explore.runner.mapper_done', {
+      mapper: outcome.name,
+      status: outcome.status,
+      duration_ms: outcome.duration_ms,
+      output_exists: outcome.output_exists,
+      output_bytes: outcome.output_bytes,
+      mode: 'serial',
+    });
+  }
+
+  // --- Merge outcomes in ORIGINAL spec order -------------------------------
+  //
+  // Callers rely on `.mappers[i]` pairing with `opts.mappers[i]` (or
+  // DEFAULT_MAPPERS[i]). We rebuild by indexing the name→outcome map.
+  const byName: Map<string, MapperOutcome> = new Map();
+  for (const o of parallelOutcomes) byName.set(o.name, o);
+  for (const o of serialOutcomes) byName.set(o.name, o);
+  const mergedOutcomes: MapperOutcome[] = specs.map((s) => {
+    const o = byName.get(s.name);
+    if (o === undefined) {
+      // Shouldn't happen unless partitioning dropped a spec. Surface
+      // as a synthetic error outcome rather than throwing.
+      return Object.freeze({
+        name: s.name,
+        status: 'error',
+        output_exists: false,
+        output_bytes: 0,
+        usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+        duration_ms: 0,
+        error: Object.freeze({
+          code: 'PARTITION_LOST',
+          message: `mapper ${s.name} was not executed by either batch`,
+        }),
+      });
+    }
+    return o;
+  });
+
+  // --- Synthesizer --------------------------------------------------------
+  logger.info('explore.runner.synthesizer_started', {
+    mappers_ready: mergedOutcomes.filter((m) => m.output_exists).length,
+    mappers_total: mergedOutcomes.length,
+  });
+
+  const synthResult = await synthesizeStreaming({
+    mapperNames: specs.map((s) => s.name),
+    mapperOutputPaths: specs.map((s) => s.outputPath),
+    synthesizerPrompt: opts.synthesizerPrompt,
+    budget: opts.synthesizerBudget,
+    maxTurns: opts.synthesizerMaxTurns,
+    cwd,
+    ...(opts.runOverride !== undefined ? { runOverride: opts.runOverride } : {}),
+    ...(opts.pollIntervalMs !== undefined ? { pollIntervalMs: opts.pollIntervalMs } : {}),
+    ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+  });
+
+  // --- Aggregate usage ----------------------------------------------------
+  let totalInput = synthResult.usage.input_tokens;
+  let totalOutput = synthResult.usage.output_tokens;
+  let totalCost = synthResult.usage.usd_cost;
+  for (const m of mergedOutcomes) {
+    totalInput += m.usage.input_tokens;
+    totalOutput += m.usage.output_tokens;
+    totalCost += m.usage.usd_cost;
+  }
+
+  logger.info('explore.runner.completed', {
+    parallel_count: safeSpecs.length,
+    serial_count: serialSpecs.length,
+    synthesizer_status: synthResult.status,
+    total_usd_cost: totalCost,
+    total_input_tokens: totalInput,
+    total_output_tokens: totalOutput,
+  });
+
+  return Object.freeze({
+    mappers: Object.freeze(mergedOutcomes),
+    synthesizer: Object.freeze({
+      status: synthResult.status,
+      output_path: synthResult.output_path,
+      usage: synthResult.usage,
+      files_fed: synthResult.files_fed,
+      ...(synthResult.error !== undefined ? { error: synthResult.error } : {}),
+    }),
+    parallel_count: safeSpecs.length,
+    serial_count: serialSpecs.length,
+    total_usage: {
+      input_tokens: totalInput,
+      output_tokens: totalOutput,
+      usd_cost: totalCost,
+    },
+  });
+}

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

@@ -0,0 +1,290 @@
+// scripts/lib/explore-parallel-runner/mappers.ts — Plan 21-06 (SDK-18).
+//
+// Mapper spawner + parallelism_safe helper. Wraps session-runner.run()
+// per mapper; aggregates N mappers concurrently with a semaphore capped
+// at `concurrency`.
+//
+// Design notes:
+//   * `isParallelismSafe` parses the `parallelism_safe` field from
+//     agent-markdown frontmatter using the same hand-rolled splitter
+//     pattern as tool-scoping/parse-agent-tools.ts. Missing file, missing
+//     frontmatter, or missing field all return `true` (default-safe).
+//   * `spawnMapper` never throws; any session-level failure lands as
+//     MapperOutcome.status === 'error' with `.error` populated. Output
+//     file presence is captured post-run so callers can distinguish
+//     "session completed but mapper didn't write" from "session errored".
+//   * `spawnMappersParallel` uses a rolling semaphore (NOT batch groups).
+//     Outcomes are returned in INPUT order, not completion order — tests
+//     assert this invariant.
+
+import { readFileSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+
+import { run as defaultSessionRun } from '../session-runner/index.ts';
+import type {
+  SessionResult,
+  SessionRunnerOptions,
+  BudgetCap,
+} from '../session-runner/types.ts';
+import {
+  enforceScope,
+  parseAgentToolsByName,
+} from '../tool-scoping/index.ts';
+
+import type { MapperOutcome, MapperSpec } from './types.ts';
+
+// ---------------------------------------------------------------------------
+// isParallelismSafe — frontmatter parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the `parallelism_safe` field from an agent markdown file's YAML
+ * frontmatter. Returns `true` (default-safe) when the file is missing,
+ * has no frontmatter, or the field is absent.
+ *
+ * Supported shapes:
+ *   parallelism_safe: true        → true
+ *   parallelism_safe: false       → false
+ *   parallelism_safe: "true"      → true
+ *   parallelism_safe: 'false'     → false
+ *
+ * Anything else (garbage values, commented-out lines, etc.) falls through
+ * to `true` — fail-open is safer than blocking parallel execution on a
+ * stale frontmatter typo.
+ */
+export function isParallelismSafe(agentPath: string): boolean {
+  let raw: string;
+  try {
+    raw = readFileSync(agentPath, 'utf8');
+  } catch {
+    // ENOENT or any IO error → default-safe.
+    return true;
+  }
+
+  const match: RegExpExecArray | null = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(raw);
+  if (match === null) return true;
+  const frontmatter: string = match[1] ?? '';
+
+  const lines: string[] = frontmatter.split(/\r?\n/);
+  for (const line of lines) {
+    const m: RegExpExecArray | null = /^parallelism_safe:\s*(.*)$/.exec(line);
+    if (m === null) continue;
+    const value: string = (m[1] ?? '').trim().replace(/^["']|["']$/g, '').toLowerCase();
+    if (value === 'false') return false;
+    if (value === 'true') return true;
+    // Unknown / garbage → default-safe.
+    return true;
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// spawnMapper — run a single mapper session
+// ---------------------------------------------------------------------------
+
+export interface SpawnMapperOptions {
+  readonly budget: BudgetCap;
+  readonly maxTurns: number;
+  readonly runOverride?: (
+    opts: SessionRunnerOptions,
+  ) => Promise<SessionResult>;
+  readonly cwd: string;
+}
+
+/**
+ * Spawn a single mapper session. Returns a MapperOutcome — never throws.
+ *
+ * Scope resolution:
+ *   * Parse agent frontmatter `tools:` via parseAgentToolsByName(name).
+ *   * Compute allowedTools via enforceScope({ stage: 'explore', agentTools }).
+ *   * Missing agent file → agentTools is null → stage 'explore' default applies.
+ */
+export async function spawnMapper(
+  spec: MapperSpec,
+  opts: SpawnMapperOptions,
+): Promise<MapperOutcome> {
+  const start = Date.now();
+
+  // Resolve tool scope. Agent frontmatter is read by bare name; we
+  // derive that from the spec.agentPath (`agents/<name>.md`).
+  const agentBaseName: string = spec.agentPath.replace(/\\/g, '/').split('/').pop()?.replace(/\.md$/i, '') ?? spec.name;
+  const agentsRoot: string = resolvePath(
+    opts.cwd,
+    spec.agentPath.replace(/\\/g, '/').split('/').slice(0, -1).join('/') || 'agents',
+  );
+
+  let allowedTools: readonly string[];
+  try {
+    const agentTools = parseAgentToolsByName(agentBaseName, agentsRoot);
+    allowedTools = enforceScope({ stage: 'explore', agentTools: agentTools ?? null });
+  } catch (err) {
+    // enforceScope throws ValidationError on denied tool additions — we
+    // don't pass additional tools, so a throw here means the stage itself
+    // was rejected (which shouldn't happen). Degrade to empty scope +
+    // surface the error.
+    const message: string = err instanceof Error ? err.message : String(err);
+    return Object.freeze({
+      name: spec.name,
+      status: 'error',
+      output_exists: false,
+      output_bytes: 0,
+      usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      duration_ms: Date.now() - start,
+      error: Object.freeze({ code: 'SCOPE_ERROR', message }),
+    });
+  }
+
+  const runFn: (o: SessionRunnerOptions) => Promise<SessionResult> =
+    opts.runOverride ?? defaultSessionRun;
+
+  const runnerOpts: SessionRunnerOptions = {
+    prompt: spec.prompt,
+    stage: 'custom',
+    allowedTools: [...allowedTools],
+    budget: opts.budget,
+    turnCap: { maxTurns: opts.maxTurns },
+  };
+
+  let sessionResult: SessionResult;
+  try {
+    sessionResult = await runFn(runnerOpts);
+  } catch (err) {
+    // session-runner.run() NEVER throws, but a test override might. Guard.
+    const message: string = err instanceof Error ? err.message : String(err);
+    return Object.freeze({
+      name: spec.name,
+      status: 'error',
+      output_exists: false,
+      output_bytes: 0,
+      usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      duration_ms: Date.now() - start,
+      error: Object.freeze({ code: 'RUN_THREW', message }),
+    });
+  }
+
+  // Capture output-file presence + size (post-run).
+  const outputFullPath: string = resolvePath(opts.cwd, spec.outputPath);
+  let outputExists = false;
+  let outputBytes = 0;
+  try {
+    const st = statSync(outputFullPath);
+    outputExists = st.isFile();
+    outputBytes = outputExists ? st.size : 0;
+  } catch {
+    outputExists = false;
+    outputBytes = 0;
+  }
+
+  // Translate SessionResult.status → MapperOutcome.status. Anything
+  // other than 'completed' collapses to 'error'; the session-runner's
+  // error payload propagates.
+  if (sessionResult.status !== 'completed') {
+    const err = sessionResult.error ?? {
+      code: sessionResult.status.toUpperCase(),
+      message: `session ended with status ${sessionResult.status}`,
+    };
+    return Object.freeze({
+      name: spec.name,
+      status: 'error',
+      output_exists: outputExists,
+      output_bytes: outputBytes,
+      usage: {
+        input_tokens: sessionResult.usage.input_tokens,
+        output_tokens: sessionResult.usage.output_tokens,
+        usd_cost: sessionResult.usage.usd_cost,
+      },
+      duration_ms: Date.now() - start,
+      error: Object.freeze({ code: err.code, message: err.message }),
+    });
+  }
+
+  return Object.freeze({
+    name: spec.name,
+    status: 'completed',
+    output_exists: outputExists,
+    output_bytes: outputBytes,
+    usage: {
+      input_tokens: sessionResult.usage.input_tokens,
+      output_tokens: sessionResult.usage.output_tokens,
+      usd_cost: sessionResult.usage.usd_cost,
+    },
+    duration_ms: Date.now() - start,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// spawnMappersParallel — rolling semaphore over N specs
+// ---------------------------------------------------------------------------
+
+export interface SpawnMappersParallelOptions {
+  readonly concurrency: number;
+  readonly budget: BudgetCap;
+  readonly maxTurns: number;
+  readonly runOverride?: (
+    opts: SessionRunnerOptions,
+  ) => Promise<SessionResult>;
+  readonly cwd: string;
+}
+
+/**
+ * Spawn N mappers concurrently, capped at `concurrency`. Returns
+ * outcomes in the SAME ORDER as `specs` (not completion order). A
+ * single mapper erroring does NOT cancel others.
+ *
+ * Concurrency < specs.length → rolling semaphore (new task starts as
+ * soon as a slot frees up). Concurrency >= specs.length → all spawn
+ * simultaneously.
+ *
+ * Empty specs → empty array.
+ */
+export async function spawnMappersParallel(
+  specs: readonly MapperSpec[],
+  opts: SpawnMappersParallelOptions,
+): Promise<readonly MapperOutcome[]> {
+  if (specs.length === 0) return Object.freeze([]);
+
+  const n: number = specs.length;
+  const cap: number = Math.max(1, Math.min(opts.concurrency, n));
+  const outcomes: (MapperOutcome | null)[] = new Array(n).fill(null);
+
+  // Build a rolling-semaphore scheduler: we keep `cap` promises in
+  // flight at once. As each resolves we start the next. This is more
+  // flexible than a fixed batch grouping — if mapper #0 is slow and
+  // #1..3 all finish, #4 can start without waiting for #0.
+  let nextIndex = 0;
+  const workers: Promise<void>[] = [];
+
+  const launch = async (): Promise<void> => {
+    while (true) {
+      const myIndex = nextIndex;
+      nextIndex += 1;
+      if (myIndex >= n) return;
+      const spec = specs[myIndex];
+      if (spec === undefined) return;
+      const spawnOpts: SpawnMapperOptions = {
+        budget: opts.budget,
+        maxTurns: opts.maxTurns,
+        cwd: opts.cwd,
+        ...(opts.runOverride !== undefined ? { runOverride: opts.runOverride } : {}),
+      };
+      const outcome = await spawnMapper(spec, spawnOpts);
+      outcomes[myIndex] = outcome;
+    }
+  };
+
+  for (let w = 0; w < cap; w += 1) {
+    workers.push(launch());
+  }
+
+  await Promise.all(workers);
+
+  // Narrow `(MapperOutcome | null)[]` → `MapperOutcome[]`. All slots
+  // MUST be filled by now; a `null` indicates a scheduler bug.
+  const final: MapperOutcome[] = outcomes.map((o, i) => {
+    if (o === null) {
+      throw new Error(`spawnMappersParallel: slot ${i} was never filled`);
+    }
+    return o;
+  });
+  return Object.freeze(final);
+}