@hegemonart/get-design-done 1.19.6 → 1.20.0

package/scripts/mcp-servers/gdd-state/tools/frontmatter_update.ts

@@ -0,0 +1,91 @@
+// scripts/mcp-servers/gdd-state/tools/frontmatter_update.ts
+//
+// Tool: gdd_state__frontmatter_update
+// Purpose: Patch one or more frontmatter fields. Rejects two forbidden
+// keys:
+//   * `pipeline_state_version` — immutable version pin
+//   * `stage`                  — must use transition_stage (which runs
+//                                gates and emits state.transition)
+// Emits state.mutation on success.
+
+import { mutate } from '../../../lib/gdd-state/index.ts';
+import {
+  emitStateMutation,
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  throwValidation,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_state__frontmatter_update';
+export const schemaPath = '../schemas/frontmatter_update.schema.json';
+
+export interface FrontmatterUpdateInput {
+  patch: Record<string, string | number | boolean>;
+}
+
+/** Keys that this tool explicitly refuses to modify. */
+export const FORBIDDEN_KEYS: ReadonlySet<string> = new Set([
+  'pipeline_state_version',
+  'stage',
+]);
+
+/** Accept only scalar values (string / number / boolean). */
+function isScalar(v: unknown): v is string | number | boolean {
+  return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
+}
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as FrontmatterUpdateInput;
+    if (
+      typed.patch === undefined ||
+      typed.patch === null ||
+      typeof typed.patch !== 'object'
+    ) {
+      throwValidation(
+        'MISSING_FIELD',
+        'frontmatter_update requires an object patch',
+      );
+    }
+    const keys = Object.keys(typed.patch);
+    if (keys.length === 0) {
+      throwValidation('EMPTY_PATCH', 'patch must contain at least one key');
+    }
+    for (const k of keys) {
+      if (FORBIDDEN_KEYS.has(k)) {
+        throwValidation(
+          'FORBIDDEN_KEY',
+          `patching "${k}" is not allowed via frontmatter_update (stage must go through transition_stage)`,
+          { key: k },
+        );
+      }
+      const value = (typed.patch as Record<string, unknown>)[k];
+      if (!isScalar(value)) {
+        throwValidation(
+          'NON_SCALAR_VALUE',
+          `patch value for "${k}" must be a string, number, or boolean`,
+          { key: k },
+        );
+      }
+    }
+
+    const path = resolveStatePath();
+    const diff: Record<string, { before: unknown; after: unknown }> = {};
+    const after = await mutate(path, (s) => {
+      for (const k of keys) {
+        const before = s.frontmatter[k];
+        const value = (typed.patch as Record<string, unknown>)[k];
+        // We restored the scalar invariant above, so this narrow is safe.
+        s.frontmatter[k] = value;
+        diff[k] = { before, after: value };
+      }
+      return s;
+    });
+    emitStateMutation(name, { diff }, after);
+    return okResponse({ frontmatter: after.frontmatter, keys });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-state/tools/get.ts

@@ -0,0 +1,51 @@
+// scripts/mcp-servers/gdd-state/tools/get.ts
+//
+// Tool: gdd_state__get
+// Purpose: Read current STATE.md (parsed). Read-only; does NOT emit an
+// event. Optionally projects a subset of fields when `input.fields` is
+// provided; unknown field names are silently ignored so callers can pass
+// a broad list without pre-flight knowledge of ParsedState shape.
+
+import { read } from '../../../lib/gdd-state/index.ts';
+import type { ParsedState } from '../../../lib/gdd-state/types.ts';
+import {
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_state__get';
+export const schemaPath = '../schemas/get.schema.json';
+
+export interface GetInput {
+  fields?: string[];
+}
+
+/**
+ * Project a subset of top-level keys from `state`. Unknown keys are
+ * omitted from the output but not treated as an error — the caller may
+ * pass a broad list without knowing ParsedState's shape.
+ */
+function project(state: ParsedState, fields: string[]): Record<string, unknown> {
+  const allowed = new Set(fields);
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(state)) {
+    if (allowed.has(k)) out[k] = v;
+  }
+  return out;
+}
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as GetInput;
+    const path = resolveStatePath();
+    const state = await read(path);
+    const fields = Array.isArray(typed.fields) ? typed.fields : null;
+    const stateOut =
+      fields === null || fields.length === 0 ? state : project(state, fields);
+    return okResponse({ state: stateOut, path });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-state/tools/index.ts

@@ -0,0 +1,51 @@
+// scripts/mcp-servers/gdd-state/tools/index.ts
+//
+// Aggregates the 11 tool handlers. `server.ts` imports from here so the
+// registration loop is one call per tool and the tool set is expanded
+// by editing a single line.
+
+import * as get from './get.ts';
+import * as update_progress from './update_progress.ts';
+import * as transition_stage from './transition_stage.ts';
+import * as add_blocker from './add_blocker.ts';
+import * as resolve_blocker from './resolve_blocker.ts';
+import * as add_decision from './add_decision.ts';
+import * as add_must_have from './add_must_have.ts';
+import * as set_status from './set_status.ts';
+import * as checkpoint from './checkpoint.ts';
+import * as probe_connections from './probe_connections.ts';
+import * as frontmatter_update from './frontmatter_update.ts';
+
+import type { ToolResponse } from './shared.ts';
+
+export interface ToolModule {
+  /** Public tool name exposed via MCP (e.g. "gdd_state__add_decision"). */
+  name: string;
+  /** Path to the input/output Draft-07 JSON Schema, relative to the module. */
+  schemaPath: string;
+  /** Executes the tool. Never throws — always returns a ToolResponse. */
+  handle: (input: unknown) => Promise<ToolResponse>;
+}
+
+/**
+ * Canonical tool registry for the server. Order is cosmetic — all 11
+ * tools are advertised equivalently in `tools/list`. Kept alphabetical
+ * after `get` for ease of scanning.
+ */
+export const TOOL_MODULES: readonly ToolModule[] = [
+  get,
+  add_blocker,
+  add_decision,
+  add_must_have,
+  checkpoint,
+  frontmatter_update,
+  probe_connections,
+  resolve_blocker,
+  set_status,
+  transition_stage,
+  update_progress,
+] as const;
+
+/** Canonical count. The plan locks this at 11 — if you add a tool, update
+ *  the plan, the combined schema, and the connection spec. */
+export const TOOL_COUNT = TOOL_MODULES.length;

package/scripts/mcp-servers/gdd-state/tools/probe_connections.ts

@@ -0,0 +1,73 @@
+// scripts/mcp-servers/gdd-state/tools/probe_connections.ts
+//
+// Tool: gdd_state__probe_connections
+// Purpose: Merge probe results into <connections>. Overwrites keys
+// present in the input; DOES NOT delete keys not in the input (plan
+// contract). Emits state.mutation on success.
+
+import { mutate } from '../../../lib/gdd-state/index.ts';
+import {
+  isConnectionStatus,
+  type ConnectionStatus,
+} from '../../../lib/gdd-state/types.ts';
+import {
+  emitStateMutation,
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  throwValidation,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_state__probe_connections';
+export const schemaPath = '../schemas/probe_connections.schema.json';
+
+export interface ProbeConnectionsInput {
+  probe_results: Array<{ name: string; status: ConnectionStatus }>;
+}
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as ProbeConnectionsInput;
+    if (!Array.isArray(typed.probe_results) || typed.probe_results.length === 0) {
+      throwValidation(
+        'MISSING_FIELD',
+        'probe_connections requires a non-empty probe_results array',
+      );
+    }
+    for (const p of typed.probe_results) {
+      if (!p || typeof p.name !== 'string' || p.name.length === 0) {
+        throwValidation(
+          'PROBE_RESULT_NAME',
+          'each probe_result must have a non-empty name',
+        );
+      }
+      if (!isConnectionStatus(p.status)) {
+        throwValidation(
+          'PROBE_RESULT_STATUS',
+          `status "${String(p.status)}" is not one of available/unavailable/not_configured`,
+        );
+      }
+    }
+
+    const path = resolveStatePath();
+    const updated: string[] = [];
+    const diff: Record<string, { before: string | null; after: string }> = {};
+    const after = await mutate(path, (s) => {
+      for (const p of typed.probe_results) {
+        const before: string | null =
+          Object.prototype.hasOwnProperty.call(s.connections, p.name)
+            ? (s.connections[p.name] as string)
+            : null;
+        s.connections[p.name] = p.status;
+        updated.push(p.name);
+        diff[p.name] = { before, after: p.status };
+      }
+      return s;
+    });
+    emitStateMutation(name, { diff }, after);
+    return okResponse({ updated, connections: after.connections });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-state/tools/resolve_blocker.ts

@@ -0,0 +1,84 @@
+// scripts/mcp-servers/gdd-state/tools/resolve_blocker.ts
+//
+// Tool: gdd_state__resolve_blocker
+// Purpose: Remove one entry from <blockers> by 0-based index OR by
+// exact text match (first match). Returns operation_failed when no row
+// matches — input is well-formed, but the operation cannot complete in
+// the current state. Emits state.mutation on successful removal.
+
+import { mutate } from '../../../lib/gdd-state/index.ts';
+import type { Blocker } from '../../../lib/gdd-state/types.ts';
+import {
+  emitStateMutation,
+  errorResponse,
+  okResponse,
+  operationFailed,
+  resolveStatePath,
+  throwValidation,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_state__resolve_blocker';
+export const schemaPath = '../schemas/resolve_blocker.schema.json';
+
+export interface ResolveBlockerInput {
+  index?: number;
+  text?: string;
+}
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as ResolveBlockerInput;
+    const hasIndex = typeof typed.index === 'number';
+    const hasText = typeof typed.text === 'string' && typed.text.length > 0;
+    if (hasIndex === hasText) {
+      throwValidation(
+        'ONEOF_REQUIRED',
+        'resolve_blocker requires exactly one of: index OR text',
+      );
+    }
+    if (hasIndex && (typed.index as number) < 0) {
+      throwValidation('INDEX_NEGATIVE', 'index must be >= 0');
+    }
+
+    const path = resolveStatePath();
+    let removed: Blocker | null = null;
+    let countAfter = 0;
+    const after = await mutate(path, (s) => {
+      if (hasIndex) {
+        const idx = typed.index as number;
+        if (idx >= s.blockers.length) {
+          operationFailed(
+            'BLOCKER_NOT_FOUND',
+            `no blocker at index ${idx} (length=${s.blockers.length})`,
+            { index: idx, length: s.blockers.length },
+          );
+        }
+        const [deleted] = s.blockers.splice(idx, 1);
+        removed = deleted ?? null;
+      } else {
+        const target = typed.text as string;
+        const idx = s.blockers.findIndex((b) => b.text === target);
+        if (idx === -1) {
+          operationFailed(
+            'BLOCKER_NOT_FOUND',
+            `no blocker matches text "${target}"`,
+            { text: target },
+          );
+        }
+        const [deleted] = s.blockers.splice(idx, 1);
+        removed = deleted ?? null;
+      }
+      countAfter = s.blockers.length;
+      return s;
+    });
+    if (removed === null) {
+      // Unreachable — mutate's fn either removed a row or threw.
+      operationFailed('BLOCKER_NOT_FOUND', 'no blocker was removed (unreachable)');
+    }
+    emitStateMutation(name, { removed, count: countAfter }, after);
+    return okResponse({ removed, count: countAfter });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-state/tools/set_status.ts

@@ -0,0 +1,54 @@
+// scripts/mcp-servers/gdd-state/tools/set_status.ts
+//
+// Tool: gdd_state__set_status
+// Purpose: Update <position>.status. Thin convenience wrapper over
+// update_progress — kept separate so skill prose can call the narrowest
+// tool possible (reduces mis-writes to task_progress). Emits state.mutation.
+
+import { mutate } from '../../../lib/gdd-state/index.ts';
+import {
+  emitStateMutation,
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  throwValidation,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_state__set_status';
+export const schemaPath = '../schemas/set_status.schema.json';
+
+export interface SetStatusInput {
+  status: 'initialized' | 'in_progress' | 'completed' | 'blocked';
+}
+
+const STATUSES = new Set([
+  'initialized',
+  'in_progress',
+  'completed',
+  'blocked',
+]);
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as SetStatusInput;
+    if (typeof typed.status !== 'string' || !STATUSES.has(typed.status)) {
+      throwValidation(
+        'STATUS_INVALID',
+        `status "${String(typed.status)}" is not one of initialized/in_progress/completed/blocked`,
+      );
+    }
+
+    const path = resolveStatePath();
+    const diff: Record<string, unknown> = {};
+    const after = await mutate(path, (s) => {
+      diff['status'] = { before: s.position.status, after: typed.status };
+      s.position.status = typed.status;
+      return s;
+    });
+    emitStateMutation(name, diff, after);
+    return okResponse({ status: after.position.status });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-state/tools/shared.ts

@@ -0,0 +1,194 @@
+// scripts/mcp-servers/gdd-state/tools/shared.ts
+//
+// Shared types + helpers for the 11 gdd-state tool handlers (Plan 20-05).
+// Every handler returns one of:
+//
+//   { success: true,  data: <tool-specific> }
+//   { success: false, error: { code, message, kind, context? } }
+//
+// Handlers NEVER throw out to the harness — every catch-all funnels
+// through `toToolError()` from `scripts/lib/gdd-errors/classification.ts`.
+// This mirrors the invariant in the plan: "Tool errors are returned as
+// {success:false, error} — handlers never propagate exceptions."
+
+import {
+  ValidationError,
+  OperationFailedError,
+} from '../../../lib/gdd-errors/index.ts';
+import { toToolError } from '../../../lib/gdd-errors/classification.ts';
+import type { ToolErrorPayload } from '../../../lib/gdd-errors/classification.ts';
+import {
+  appendEvent,
+  type BaseEvent,
+  type StateMutationEvent,
+  type StateTransitionEvent,
+} from '../../../lib/event-stream/index.ts';
+import type { ParsedState, Stage } from '../../../lib/gdd-state/types.ts';
+
+/** Public tool-handler response shape (consistent across all 11 tools). */
+export type ToolResponse =
+  | { success: true; data: Record<string, unknown> }
+  | { success: false; error: ToolErrorPayload['error'] };
+
+/**
+ * Session-id generator. The MCP server stamps a single session ID per
+ * process (via `getSessionId()`) so every event emitted by that server
+ * run correlates to a single pipeline session. The generator produces a
+ * sortable, opaque string — `gdd-mcp-<iso>-<pid>`.
+ */
+export function makeSessionId(): string {
+  const iso = new Date().toISOString().replace(/[:.]/g, '-');
+  return `gdd-mcp-${iso}-${process.pid}`;
+}
+
+let CACHED_SESSION_ID: string | null = null;
+
+/** Return the session id for this process, generating it lazily. */
+export function getSessionId(): string {
+  if (CACHED_SESSION_ID === null) CACHED_SESSION_ID = makeSessionId();
+  return CACHED_SESSION_ID;
+}
+
+/**
+ * Resolve the target STATE.md path from the environment. Mirrors the
+ * plan's contract: `process.env.GDD_STATE_PATH ?? .design/STATE.md`.
+ *
+ * Resolution is relative to `process.cwd()` when the env override is
+ * missing or relative. Tests and the server both call this so the
+ * resolution logic stays in one place.
+ */
+export function resolveStatePath(): string {
+  const override = process.env['GDD_STATE_PATH'];
+  if (typeof override === 'string' && override.length > 0) return override;
+  return '.design/STATE.md';
+}
+
+/** Narrow helper: is this a well-known Stage string? */
+export function isStageValue(value: unknown): value is Stage {
+  return (
+    value === 'brief' ||
+    value === 'explore' ||
+    value === 'plan' ||
+    value === 'design' ||
+    value === 'verify'
+  );
+}
+
+/** Narrow helper: does this value look like ParsedState's position.stage shape. */
+export function hasStage(state: ParsedState): state is ParsedState {
+  return typeof state.position?.stage === 'string';
+}
+
+/**
+ * Emit a state.mutation event after a successful mutation. Callers pass
+ * the mutating tool's `name` and an opaque `diff` describing what changed.
+ *
+ * The event is persisted to the JSONL stream AND broadcast on the bus —
+ * see `scripts/lib/event-stream/index.ts`. `appendEvent()` never throws
+ * on I/O (the writer swallows write errors into `writeErrors`), so this
+ * helper is safe to call inside a `success: true` return path.
+ */
+export function emitStateMutation(
+  tool: string,
+  diff: unknown,
+  stateAfter: ParsedState,
+): void {
+  const stage = isStageValue(stateAfter.position.stage)
+    ? stateAfter.position.stage
+    : undefined;
+  const ev: StateMutationEvent = {
+    type: 'state.mutation',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    ...(stage !== undefined ? { stage } : {}),
+    ...(typeof stateAfter.frontmatter.cycle === 'string' &&
+    stateAfter.frontmatter.cycle.length > 0
+      ? { cycle: stateAfter.frontmatter.cycle }
+      : {}),
+    payload: { tool, diff },
+  };
+  appendEvent(ev);
+}
+
+/**
+ * Emit a state.transition event. Two shapes exist: `pass=true` after a
+ * successful advance, and `pass=false` after a gate veto. Both cases are
+ * worth recording — gate vetoes are user-visible operational data.
+ */
+export function emitStateTransition(
+  from: Stage,
+  to: Stage,
+  pass: boolean,
+  blockers: string[],
+  state: ParsedState | null,
+): void {
+  const cycle =
+    state !== null &&
+    typeof state.frontmatter.cycle === 'string' &&
+    state.frontmatter.cycle.length > 0
+      ? state.frontmatter.cycle
+      : undefined;
+  const ev: StateTransitionEvent = {
+    type: 'state.transition',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    stage: pass ? to : from,
+    ...(cycle !== undefined ? { cycle } : {}),
+    payload: { from, to, blockers: [...blockers], pass },
+  };
+  appendEvent(ev);
+}
+
+/**
+ * Map an error into a tool-response `{success:false,error}` object.
+ * Single entry point for every handler — keeps the error-shape decision
+ * in one place and lets us layer extra context (e.g. transition blockers)
+ * consistently.
+ */
+export function errorResponse(err: unknown): ToolResponse {
+  const payload = toToolError(err);
+  return { success: false, error: payload.error };
+}
+
+/**
+ * Shorthand for a `{success:true,data}` return with a plain object.
+ */
+export function okResponse(data: Record<string, unknown>): ToolResponse {
+  return { success: true, data };
+}
+
+/**
+ * Raise a ValidationError whose `message` is human-readable and whose
+ * `code` is `VALIDATION_*` — the default error code used across Plan
+ * 20-05 for input shape problems. Handlers call this after the JSON
+ * Schema check (which catches the big structural issues); this covers
+ * invariant checks that the schema cannot express (e.g. "patch contains
+ * a forbidden key").
+ */
+export function throwValidation(
+  codeSuffix: string,
+  message: string,
+  context?: Record<string, unknown>,
+): never {
+  throw new ValidationError(message, `VALIDATION_${codeSuffix}`, context);
+}
+
+/**
+ * Raise an OperationFailedError — the caller's input was well-formed,
+ * but the requested operation cannot complete in the current state.
+ * Example: `resolve_blocker` asked to delete a row that doesn't exist.
+ */
+export function operationFailed(
+  codeSuffix: string,
+  message: string,
+  context?: Record<string, unknown>,
+): never {
+  throw new OperationFailedError(
+    message,
+    `OPERATION_${codeSuffix}`,
+    context,
+  );
+}
+
+/** Re-exports kept local to avoid every handler importing the whole taxonomy. */
+export type { BaseEvent };

package/scripts/mcp-servers/gdd-state/tools/transition_stage.ts

@@ -0,0 +1,80 @@
+// scripts/mcp-servers/gdd-state/tools/transition_stage.ts
+//
+// Tool: gdd_state__transition_stage
+// Purpose: Run gate and advance <position>.stage / frontmatter.stage on
+// pass. On gate veto, returns {success:false, error:{code:'TRANSITION_
+// GATE_FAILED', context:{blockers:[...]}}}. Does NOT throw to the MCP
+// harness — the plan mandates a contained error path so gate failures
+// do not crash the server.
+//
+// Emits state.transition (pass=true) on success and state.transition
+// (pass=false) on gate veto. Plan 20-06's event-stream surface accepts
+// both forms; Plan 22+ dashboards render both.
+
+import { read, transition } from '../../../lib/gdd-state/index.ts';
+import { isStage, type Stage } from '../../../lib/gdd-state/types.ts';
+import { TransitionGateFailed } from '../../../lib/gdd-errors/index.ts';
+import {
+  emitStateTransition,
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  throwValidation,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_state__transition_stage';
+export const schemaPath = '../schemas/transition_stage.schema.json';
+
+export interface TransitionStageInput {
+  to: Stage;
+}
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as TransitionStageInput;
+    if (!isStage(typed.to)) {
+      throwValidation(
+        'STAGE_INVALID',
+        `to "${String(typed.to)}" is not a recognized Stage`,
+      );
+    }
+
+    const path = resolveStatePath();
+    // Read current state before transition so the event + response can
+    // report `from` accurately, even when the gate vetoes (and therefore
+    // the state is unchanged).
+    const before = await read(path);
+    const fromValue = before.position.stage;
+
+    try {
+      const result = await transition(path, typed.to);
+      // transition() only returns a result when pass=true — the gate
+      // failure path throws TransitionGateFailed.
+      const fromNarrow = isStage(fromValue) ? fromValue : typed.to;
+      emitStateTransition(fromNarrow, typed.to, true, [], result.state);
+      return okResponse({
+        from: fromValue,
+        to: typed.to,
+        state: result.state,
+      });
+    } catch (inner) {
+      // Emit the failure as an event — gate vetoes are useful telemetry
+      // — then translate into {success:false,error} so the MCP harness
+      // never sees the throw.
+      if (inner instanceof TransitionGateFailed) {
+        const fromNarrow = isStage(fromValue) ? fromValue : typed.to;
+        emitStateTransition(
+          fromNarrow,
+          typed.to,
+          false,
+          [...inner.blockers],
+          before,
+        );
+      }
+      throw inner;
+    }
+  } catch (err) {
+    return errorResponse(err);
+  }
+}