@hegemonart/get-design-done 1.20.0 → 1.22.0

package/scripts/lib/init-runner/scaffold.ts

@@ -0,0 +1,224 @@
+// scripts/lib/init-runner/scaffold.ts — filesystem helpers for the
+// `gdd-sdk init` runner (Plan 21-08, SDK-20).
+//
+// This module is synchronous + side-effectful; every helper either
+// mutates disk in a well-defined way or reports a boolean/null/string
+// result. No session-runner / SDK dependencies — keep it cheap to test.
+//
+// Helpers exported:
+//
+//   * writeStateFromTemplate   — copy reference/STATE-TEMPLATE.md →
+//                                .design/STATE.md with `{TODAY}` replaced.
+//   * backupExistingDesignDir  — rename `.design/` to `.design.backup.<ISO>/`.
+//   * resolveStateTemplatePath — walk up from process.argv[1]/cwd to find
+//                                the plugin package root, then join
+//                                reference/STATE-TEMPLATE.md.
+//   * ensureDesignDirs         — `mkdir -p` both `.design/` and
+//                                `.design/research/`.
+//
+// All helpers are pure w.r.t. filesystem ordering — every caller can
+// invoke them in any order without corrupting a concurrent init.
+
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/** The plugin's package.json `name` field used to anchor the walk-up in
+ *  `resolveStateTemplatePath`. */
+const PLUGIN_PACKAGE_NAME = '@hegemonart/get-design-done';
+
+/** Maximum directories to climb looking for the plugin root. Eight
+ *  matches session-runner's repo-root discovery depth — a forgiving
+ *  upper bound without being pathological. */
+const MAX_WALKUP_DEPTH = 8;
+
+// ---------------------------------------------------------------------------
+// writeStateFromTemplate
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy `templatePath` to `destPath`, replacing every `{TODAY}` token
+ * with today's ISO date (`YYYY-MM-DD`). Other placeholders (e.g.,
+ * `{PROJECT_NAME}`) are left verbatim for the user to fill in later.
+ *
+ * Returns `true` on success, `false` when the template is missing.
+ * Never throws for expected failure modes; unexpected errors (permission
+ * denied, out of disk) surface as thrown errors since the caller cannot
+ * meaningfully recover.
+ */
+export function writeStateFromTemplate(args: {
+  readonly cwd: string;
+  readonly templatePath: string;
+  readonly destPath: string;
+}): boolean {
+  const { templatePath, destPath } = args;
+
+  if (!existsSync(templatePath)) return false;
+
+  // Read template → substitute `{TODAY}` → write to dest. If the template
+  // has no `{TODAY}` token we write it verbatim (plan spec: "Template
+  // without placeholder → copied verbatim").
+  const raw = readFileSync(templatePath, 'utf8');
+  const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+  const body = raw.includes('{TODAY}')
+    ? raw.split('{TODAY}').join(today)
+    : raw;
+
+  // Ensure destination directory exists before writing.
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, body, 'utf8');
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// backupExistingDesignDir
+// ---------------------------------------------------------------------------
+
+/**
+ * If `.design/` exists inside `cwd`, move it aside to
+ * `.design.backup.<ISO>/` (ISO safe-for-filename form) and return the
+ * backup directory path. Returns `null` when nothing exists to back up.
+ *
+ * Rename is the default (atomic on same filesystem); on EXDEV or any
+ * other rename error we fall back to recursive copy + rm.
+ */
+export function backupExistingDesignDir(cwd: string): string | null {
+  const designDir = resolve(cwd, '.design');
+  if (!existsSync(designDir)) return null;
+
+  // ISO → filesystem-safe: replace ':' and '.' (e.g. 2026-04-24T10:15:30.123Z
+  // → 2026-04-24T10-15-30-123Z) so Windows accepts the directory name.
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  let backupDir = resolve(cwd, `.design.backup.${stamp}`);
+
+  // Collision guard — sub-millisecond double-invoke could land on the
+  // same ISO stamp. Append a numeric suffix until the path is free.
+  let suffix = 0;
+  while (existsSync(backupDir)) {
+    suffix += 1;
+    backupDir = resolve(cwd, `.design.backup.${stamp}-${suffix}`);
+    if (suffix > 1000) {
+      // Pathological — bail rather than loop forever.
+      throw new Error(`backupExistingDesignDir: could not find a free backup directory after ${suffix} attempts`);
+    }
+  }
+
+  try {
+    renameSync(designDir, backupDir);
+  } catch (err) {
+    // EXDEV (cross-volume), EPERM (Windows permissions), or anything
+    // else — try recursive copy + rm as a slower fallback.
+    const code = (err as NodeJS.ErrnoException | null)?.code;
+    if (code === 'EXDEV' || code === 'EPERM' || code === 'ENOTEMPTY') {
+      cpSync(designDir, backupDir, { recursive: true });
+      rmSync(designDir, { recursive: true, force: true });
+    } else {
+      throw err;
+    }
+  }
+
+  return backupDir;
+}
+
+// ---------------------------------------------------------------------------
+// ensureDesignDirs
+// ---------------------------------------------------------------------------
+
+/**
+ * Create `.design/` and `.design/research/` inside `cwd` (`mkdir -p`).
+ * Idempotent — safe to call on an already-initialized project. Returns
+ * the resolved absolute paths so callers can drop them directly into
+ * `writeStateFromTemplate({destPath: ...})`.
+ */
+export function ensureDesignDirs(cwd: string): {
+  readonly design_dir: string;
+  readonly research_dir: string;
+} {
+  const designDir = resolve(cwd, '.design');
+  const researchDir = join(designDir, 'research');
+  mkdirSync(designDir, { recursive: true });
+  mkdirSync(researchDir, { recursive: true });
+  return Object.freeze({ design_dir: designDir, research_dir: researchDir });
+}
+
+// ---------------------------------------------------------------------------
+// resolveStateTemplatePath
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk up from `process.argv[1]`'s directory (falling back to cwd if
+ * argv[1] isn't a real path) looking for a `package.json` whose `name`
+ * field matches `@hegemonart/get-design-done`. When found, return
+ * `<pkg-root>/reference/STATE-TEMPLATE.md`. Return `null` if we run out
+ * of parent directories without finding the plugin root — e.g., when
+ * invoked from a fork that has renamed the package.
+ *
+ * The walk is bounded to `MAX_WALKUP_DEPTH` (8) to stop us from
+ * traversing the entire filesystem on pathological inputs.
+ */
+export function resolveStateTemplatePath(): string | null {
+  const startCandidates: string[] = [];
+  // argv[1] is the executing script's path (e.g., bin wrapper).
+  const argv1 = process.argv[1];
+  if (argv1 !== undefined && argv1.length > 0 && existsSync(argv1)) {
+    startCandidates.push(dirname(resolve(argv1)));
+  }
+  // Fall back to cwd for cases where argv[1] isn't meaningful (tests,
+  // repl, etc.).
+  startCandidates.push(process.cwd());
+
+  for (const start of startCandidates) {
+    let dir = start;
+    for (let depth = 0; depth < MAX_WALKUP_DEPTH; depth += 1) {
+      const pkgPath = join(dir, 'package.json');
+      if (existsSync(pkgPath)) {
+        try {
+          const raw = readFileSync(pkgPath, 'utf8');
+          const parsed = JSON.parse(raw) as { name?: unknown };
+          if (parsed.name === PLUGIN_PACKAGE_NAME) {
+            const tpl = join(dir, 'reference', 'STATE-TEMPLATE.md');
+            if (existsSync(tpl)) return tpl;
+          }
+        } catch {
+          // Malformed package.json — keep walking; maybe a parent has it.
+        }
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers (kept exported for tests that want to drill in)
+// ---------------------------------------------------------------------------
+
+/** Expose copy-then-write as a unit for tests that want to bypass the
+ *  template-path existence check. Public but undocumented in the index. */
+export function _copyTemplateVerbatim(src: string, dest: string): void {
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+}
+
+/** Size of a file on disk, or 0 if missing. Used by the researcher
+ *  dispatcher to measure `output_bytes` without bubbling up EEXIST /
+ *  ENOENT. */
+export function fileSize(p: string): number {
+  try {
+    return statSync(p).size;
+  } catch {
+    return 0;
+  }
+}

package/scripts/lib/init-runner/synthesizer.ts

@@ -0,0 +1,224 @@
+// scripts/lib/init-runner/synthesizer.ts — composes
+// `.design/DESIGN-CONTEXT.md` from researcher outputs (Plan 21-08, SDK-20).
+//
+// The synthesizer is a single headless session spawned through
+// `session-runner.run()` with a prompt that embeds every researcher's
+// content. Its success contract is simple: did the agent write
+// `.design/DESIGN-CONTEXT.md` to disk? We don't parse its text output —
+// the file's presence is the sole pass/fail signal.
+//
+// Exports:
+//   * DEFAULT_SYNTHESIZER_PROMPT  — the embedded prompt (frozen string).
+//   * buildSynthesizerPrompt       — splice researcher bodies into the prompt.
+//   * spawnSynthesizer             — session dispatch + file-presence check.
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { run as runSession } from '../session-runner/index.ts';
+import type {
+  BudgetCap,
+  QueryOverride,
+} from '../session-runner/types.ts';
+import { enforceScope } from '../tool-scoping/index.ts';
+import type { ResearcherName } from './types.ts';
+
+/**
+ * Default synthesizer prompt with a `{{RESEARCH_BLOCKS}}` placeholder
+ * that `buildSynthesizerPrompt` substitutes with the researcher
+ * content. The template encodes the DESIGN-CONTEXT.md schema the
+ * downstream discuss stage expects (decisions, must-haves, connections,
+ * ARM, flow diagram, open questions).
+ *
+ * The prompt is explicit about "write file; emit no prose" because the
+ * synthesizer's success is measured by file-on-disk — we don't need the
+ * agent's text stream in the transcript.
+ */
+export const DEFAULT_SYNTHESIZER_PROMPT: string = Object.freeze(
+  `You are the init-synthesizer. Four researchers have produced these outputs:
+
+{{RESEARCH_BLOCKS}}
+
+Compose .design/DESIGN-CONTEXT.md following this schema:
+
+---
+cycle: init
+generated_at: <ISO>
+---
+
+# Design Context (Draft)
+
+## Decisions
+(Draft as D-01, D-02, … from researcher outputs. Each decision gets id,
+ rationale, source researcher.)
+
+## Must-Haves
+(Draft as M-01, M-02, … from researcher blockers. Each must-have gets id,
+ stakeholder, test.)
+
+## Connections
+(Which AI-design-tool connections the project's tech stack recommends.)
+
+## Architectural Responsibility Map
+(ARM tiers inferred from the codebase.)
+
+## Flow Diagram
+\`\`\`mermaid
+flowchart TD
+  ...
+\`\`\`
+
+## Open Questions
+(Anything that requires the user to answer before brief can start.)
+
+Write the final content to .design/DESIGN-CONTEXT.md via Write tool.
+Do NOT emit any prose response — only write the file.
+`,
+) as string;
+
+export interface SynthesizerInput {
+  readonly name: ResearcherName;
+  readonly path: string;
+  readonly content: string;
+}
+
+/**
+ * Build the synthesizer prompt by substituting `{{RESEARCH_BLOCKS}}`
+ * with concatenated research bodies. Each block is wrapped in an HTML
+ * comment header so the agent can parse the boundaries deterministically.
+ *
+ * Exported for tests + for callers that want to assert prompt content
+ * without running a session.
+ */
+export function buildSynthesizerPrompt(
+  inputs: readonly SynthesizerInput[],
+  override?: string,
+): string {
+  const template = override ?? DEFAULT_SYNTHESIZER_PROMPT;
+  const blocks = inputs
+    .map((inp) => `<!-- ${inp.name} -->\n${inp.content}`)
+    .join('\n\n');
+  // If the caller's override doesn't include the placeholder, append
+  // the blocks. This keeps custom prompts functional without forcing
+  // them to adopt our template marker.
+  if (!template.includes('{{RESEARCH_BLOCKS}}')) {
+    return `${template}\n\n${blocks}`;
+  }
+  return template.split('{{RESEARCH_BLOCKS}}').join(blocks);
+}
+
+export interface SpawnSynthesizerArgs {
+  readonly researcherOutputs: readonly SynthesizerInput[];
+  readonly cwd: string;
+  readonly budget: BudgetCap;
+  readonly maxTurns: number;
+  readonly runOverride?: QueryOverride;
+  readonly promptOverride?: string;
+}
+
+export interface SpawnSynthesizerResult {
+  readonly status: 'completed' | 'error';
+  /** Absolute path to where .design/DESIGN-CONTEXT.md should live. */
+  readonly design_context_path: string;
+  readonly usage: {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly usd_cost: number;
+  };
+  readonly error?: string;
+}
+
+/**
+ * Spawn one synthesizer session. Success is determined by the presence
+ * of `.design/DESIGN-CONTEXT.md` inside `cwd` after the session ends —
+ * we do NOT inspect the session's text output.
+ *
+ * Never throws; session-level errors and missing-file outcomes both
+ * land as `status: 'error'` with `error` populated.
+ */
+export async function spawnSynthesizer(
+  args: SpawnSynthesizerArgs,
+): Promise<SpawnSynthesizerResult> {
+  const designContextPath = resolve(
+    args.cwd,
+    '.design',
+    'DESIGN-CONTEXT.md',
+  );
+
+  // Resolve allowed tools. The synthesizer only needs Read (to load
+  // research outputs if the prompt drops the inline bodies) and Write
+  // (to produce DESIGN-CONTEXT.md). The init stage scope covers both.
+  let allowedTools: readonly string[];
+  try {
+    allowedTools = enforceScope({ stage: 'init' });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return Object.freeze({
+      status: 'error' as const,
+      design_context_path: designContextPath,
+      usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      error: `scope enforcement failed: ${message}`,
+    });
+  }
+
+  const prompt = buildSynthesizerPrompt(
+    args.researcherOutputs,
+    args.promptOverride,
+  );
+
+  let usage = { input_tokens: 0, output_tokens: 0, usd_cost: 0 };
+  try {
+    const session = await runSession({
+      prompt,
+      stage: 'init',
+      budget: args.budget,
+      turnCap: { maxTurns: args.maxTurns },
+      allowedTools: [...allowedTools],
+      ...(args.runOverride !== undefined
+        ? { queryOverride: args.runOverride }
+        : {}),
+    });
+    usage = {
+      input_tokens: session.usage.input_tokens,
+      output_tokens: session.usage.output_tokens,
+      usd_cost: session.usage.usd_cost,
+    };
+
+    if (session.status !== 'completed') {
+      const code = session.error?.code ?? session.status.toUpperCase();
+      const msg = session.error?.message ?? `session ended: ${session.status}`;
+      return Object.freeze({
+        status: 'error' as const,
+        design_context_path: designContextPath,
+        usage,
+        error: `${code}: ${msg}`,
+      });
+    }
+  } catch (err) {
+    // session-runner is documented never-throws, but a test-injected
+    // runOverride could throw during setup. Package gracefully.
+    const message = err instanceof Error ? err.message : String(err);
+    return Object.freeze({
+      status: 'error' as const,
+      design_context_path: designContextPath,
+      usage,
+      error: `session threw: ${message}`,
+    });
+  }
+
+  // Success is file-on-disk, NOT session.status.
+  if (!existsSync(designContextPath)) {
+    return Object.freeze({
+      status: 'error' as const,
+      design_context_path: designContextPath,
+      usage,
+      error: 'synthesizer did not produce .design/DESIGN-CONTEXT.md',
+    });
+  }
+
+  return Object.freeze({
+    status: 'completed' as const,
+    design_context_path: designContextPath,
+    usage,
+  });
+}

package/scripts/lib/init-runner/types.ts

@@ -0,0 +1,143 @@
+// scripts/lib/init-runner/types.ts — public type surface for the
+// `gdd-sdk init` runner (Plan 21-08, SDK-20).
+//
+// The init runner bootstraps a new project's `.design/` directory by
+// spawning a fixed roster of 4 researchers in parallel through the
+// session-runner (Plan 21-01) and then running a synthesizer pass that
+// composes `.design/DESIGN-CONTEXT.md` from the researcher outputs.
+//
+// These types are consumed by:
+//   * `researchers.ts`  — dispatch + outcome shape.
+//   * `synthesizer.ts`  — synthesizer I/O contract.
+//   * `scaffold.ts`     — STATE.md + backup helpers.
+//   * `index.ts`        — top-level `run()` orchestrator.
+//   * CLI wiring (Plan 21-09) — consumes `InitRunnerResult`.
+//
+// No file outside `scripts/lib/init-runner/` should construct any of
+// these shapes directly; `index.ts` re-exports each one.
+
+import type { BudgetCap, QueryOverride } from '../session-runner/types.ts';
+
+/**
+ * Locked roster of researcher names. The init cycle always spawns
+ * exactly these four; adding a fifth is a breaking change because it
+ * widens every `ResearcherOutcome[]` consumer's input.
+ */
+export type ResearcherName =
+  | 'design-system-audit'
+  | 'brand-context'
+  | 'accessibility-baseline'
+  | 'competitive-references';
+
+/**
+ * One researcher's spec. The `agentPath` is optional — if the file is
+ * absent on disk, the runner falls back to the `init` stage scope from
+ * `tool-scoping` (Plan 21-03), which grants the broad research-capable
+ * toolset (Read, Write, Grep, Glob, Bash, Task, WebSearch, WebFetch).
+ */
+export interface ResearcherSpec {
+  readonly name: ResearcherName;
+  /** Optional agent frontmatter path; missing → init stage scope. */
+  readonly agentPath?: string;
+  readonly prompt: string;
+  /** Where the researcher's markdown output lands (relative to cwd). */
+  readonly outputPath: string;
+}
+
+/**
+ * Per-researcher outcome. Never-throws contract: if the session errored
+ * internally, `status` is `'error'` and the `error` field is populated —
+ * the runner never re-raises.
+ *
+ * `output_exists` + `output_bytes` are measured on disk AFTER the
+ * session returns; a successful session that failed to write its file
+ * lands with `status: 'completed'` and `output_exists: false` so the
+ * synthesizer can drop the slot cleanly.
+ */
+export interface ResearcherOutcome {
+  readonly name: ResearcherName;
+  readonly status: 'completed' | 'error';
+  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 };
+}
+
+/**
+ * Terminal status for a full `run()` invocation.
+ *
+ *   * `completed`                — every step ran; scaffold + synth produced.
+ *   * `already-initialized`      — `.design/STATE.md` exists and `force` is off.
+ *   * `no-researchers-succeeded` — all 4 researchers errored; synth skipped.
+ *   * `error`                    — precondition failure (e.g., STATE-TEMPLATE.md missing).
+ */
+export type InitStatus =
+  | 'completed'
+  | 'already-initialized'
+  | 'no-researchers-succeeded'
+  | 'error';
+
+/**
+ * Options for the top-level `run()`. Every researcher and the synthesizer
+ * get their own budget envelope so a runaway researcher cannot starve
+ * the synthesizer's token budget.
+ *
+ * `runOverride` + `synthesizerPromptOverride` are test injection points;
+ * production callers leave them unset.
+ */
+export interface InitRunnerOptions {
+  /** Researchers to run. Default: `DEFAULT_RESEARCHERS` (the 4-locked roster). */
+  readonly researchers?: readonly ResearcherSpec[];
+  /** Per-researcher budget envelope. Each researcher gets a fresh copy. */
+  readonly budget: BudgetCap;
+  /** Max assistant turns per researcher session. */
+  readonly maxTurnsPerResearcher: number;
+  /** Synthesizer budget envelope. */
+  readonly synthesizerBudget: BudgetCap;
+  /** Max assistant turns for the synthesizer session. */
+  readonly synthesizerMaxTurns: number;
+  /** Parallelism cap for researcher dispatch. Default: 4. */
+  readonly concurrency?: number;
+  /** Working directory; `.design/` resolved relative to this. Default: `process.cwd()`. */
+  readonly cwd?: string;
+  /** Force re-init: backup existing `.design/` to `.design.backup.<ISO>/`. */
+  readonly force?: boolean;
+  /** Path to `reference/STATE-TEMPLATE.md`; defaults to plugin-package-local. */
+  readonly stateTemplatePath?: string;
+  /** Test-injectable session-runner `run()` replacement. */
+  readonly runOverride?: QueryOverride;
+  /** Override the synthesizer's embedded prompt. */
+  readonly synthesizerPromptOverride?: string;
+}
+
+/**
+ * Terminal result from `run()`. The union discriminant is `status`;
+ * `researchers` + `scaffold` + `total_usage` are populated on all
+ * branches (empty arrays / false flags / zeroed usage) so callers can
+ * present a uniform summary.
+ */
+export interface InitRunnerResult {
+  readonly status: InitStatus;
+  /** Resolved working directory the run targeted. */
+  readonly cwd: string;
+  /** Resolved `.design/` directory path (absolute). */
+  readonly design_dir: string;
+  readonly researchers: readonly ResearcherOutcome[];
+  readonly scaffold: {
+    readonly state_md_written: boolean;
+    readonly design_context_md_written: boolean;
+    /** When `opts.force` triggered a backup, the backup dir path. */
+    readonly backup_dir?: string;
+  };
+  /** Aggregated usage across all researchers + the synthesizer. */
+  readonly total_usage: {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly usd_cost: number;
+  };
+}