@hegemonart/get-design-done 1.31.0 → 1.31.5

package/sdk/mcp/gdd-state/server.ts

@@ -0,0 +1,294 @@
+#!/usr/bin/env -S node --experimental-strip-types
+// sdk/mcp/gdd-state/server.ts
+//
+// MCP server `gdd-state` — exposes the 11 typed STATE.md tools implemented
+// under `./tools/` via stdio transport. Plan 20-05 (SDK-06/07).
+//
+// Lifecycle:
+//   1. Construct a low-level Server (we use the low-level surface so we
+//      can speak JSON Schema directly — the high-level McpServer wants
+//      Zod shapes, and our per-tool schemas are Draft-07 JSON.)
+//   2. Register `tools/list` — returns all 11 tools with their input
+//      JSON Schemas loaded from disk.
+//   3. Register `tools/call` — dispatches by name to the matching
+//      handler. Each handler returns a typed ToolResponse; the server
+//      wraps it into the MCP CallToolResult shape (one text content
+//      item, JSON-stringified response; plus `structuredContent` for
+//      richer clients; `isError: true` when `success:false`).
+//   4. Attach StdioServerTransport; await connect.
+//   5. On SIGINT / SIGTERM: close the transport, flush nothing (the
+//      event writer uses `appendFileSync` so every write is already
+//      durable), and exit 0.
+//
+// Invariant: handler throws are contained. The dispatcher wraps every
+// call in a try/catch that funnels through toToolError() — the MCP
+// harness never sees an uncaught throw from our tools.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { toToolError } from '../../errors/classification.ts';
+import { TOOL_MODULES, type ToolModule } from './tools/index.ts';
+
+/** Server metadata advertised on initialize. */
+const SERVER_NAME = 'gdd-state';
+const SERVER_VERSION = '1.20.0';
+
+/**
+ * Resolve this module's directory. We deliberately avoid `import.meta.url`
+ * (not permitted by our tsconfig's Node16+CommonJS-compatible module
+ * resolution) and `__dirname` (not portable under strip-types ESM).
+ *
+ * Strategy: when this module is invoked as a script, `process.argv[1]`
+ * points at this file; resolve its dirname. When it is imported for
+ * tests, we fall back to walking from `process.cwd()` — tests run
+ * from the repo root by convention, so `sdk/mcp/gdd-state`
+ * resolves reliably. Both branches are canonicalized against the
+ * on-disk tools directory.
+ */
+function here(): string {
+  const expectedRel = join('sdk', 'mcp', 'gdd-state');
+  // Script invocation: process.argv[1] === .../server.ts (or a shim).
+  const entry = process.argv[1];
+  if (typeof entry === 'string' && entry.length > 0) {
+    const entryDir = dirname(resolve(entry));
+    if (existsSync(join(entryDir, 'tools', 'index.ts'))) {
+      return entryDir;
+    }
+  }
+  // Library-import path (tests): walk cwd forward.
+  const candidate = resolve(process.cwd(), expectedRel);
+  if (existsSync(join(candidate, 'tools', 'index.ts'))) {
+    return candidate;
+  }
+  // Last-resort: return the expected path even if it does not exist —
+  // the subsequent readFileSync() call will produce a clear error.
+  return candidate;
+}
+
+/** Eager cache of input schemas keyed by tool name. We load them once at
+ *  startup so a tool-call handler never hits the filesystem in the hot
+ *  path; subsequent schema edits (JSON file on disk) require a server
+ *  restart, which matches every other part of the pipeline. */
+interface LoadedTool extends ToolModule {
+  inputSchema: Record<string, unknown>;
+}
+
+function loadTools(): LoadedTool[] {
+  const baseDir = here();
+  return TOOL_MODULES.map((m) => {
+    const absPath = join(baseDir, 'tools', m.schemaPath);
+    const raw = readFileSync(absPath, 'utf8');
+    const parsed = JSON.parse(raw) as {
+      properties?: {
+        input?: { type?: string; properties?: Record<string, unknown> };
+      };
+    };
+    // The per-tool schema files are Draft-07 wrappers shaped as:
+    //   { type: "object", properties: { input: {...}, output: {...} } }
+    // MCP's tools/list advertises only the INPUT half. We project
+    // `properties.input` here; when the schema is malformed we fall
+    // back to an open object so the tool is still listable.
+    const rawInput = parsed.properties?.input;
+    const inputSchema: Record<string, unknown> =
+      rawInput !== undefined && typeof rawInput === 'object'
+        ? (rawInput as Record<string, unknown>)
+        : { type: 'object' };
+    // MCP clients require inputSchema.type === "object" for tools/list.
+    // Our per-tool inputs are already objects; defensively stamp the
+    // field when absent.
+    if (!('type' in inputSchema)) inputSchema['type'] = 'object';
+    return { ...m, inputSchema };
+  });
+}
+
+/**
+ * Tool descriptions — short, scannable, lifted from the plan. Skill
+ * prose uses these verbatim when suggesting a tool to the model.
+ */
+const TOOL_DESCRIPTIONS: Record<string, string> = {
+  gdd_state__get:
+    'Read current STATE.md (parsed). Read-only; no event emitted. Optionally projects a subset of fields.',
+  gdd_state__update_progress:
+    'Update <position>.task_progress and/or status. Emits state.mutation.',
+  gdd_state__transition_stage:
+    'Run gate and advance <position>.stage on pass. Gate vetoes return {success:false, error:{context:{blockers:[...]}}}; never crashes the server. Emits state.transition.',
+  gdd_state__add_blocker:
+    'Append one entry to <blockers>. Defaults stage to current position.stage and date to today (UTC). Emits state.mutation.',
+  gdd_state__resolve_blocker:
+    'Remove one <blockers> entry by 0-based index or exact text match. Returns operation_failed when no row matches. Emits state.mutation on removal.',
+  gdd_state__add_decision:
+    'Append one entry to <decisions>. Auto-allocates D-N id when not supplied. Emits state.mutation.',
+  gdd_state__add_must_have:
+    'Append one entry to <must_haves>. Auto-allocates M-N id when not supplied. Emits state.mutation.',
+  gdd_state__set_status:
+    'Update <position>.status. Emits state.mutation.',
+  gdd_state__checkpoint:
+    'Update frontmatter.last_checkpoint and append a <timestamps> entry. Emits state.mutation.',
+  gdd_state__probe_connections:
+    'Merge probe results into <connections>. Overwrites keys present in the input; does NOT delete keys not in the input. Emits state.mutation.',
+  gdd_state__frontmatter_update:
+    'Patch one or more frontmatter fields. Rejects pipeline_state_version and stage (use transition_stage). Emits state.mutation.',
+};
+
+/** Human-readable annotation hints (MCP clients use these to style the
+ *  tool in UI). `readOnlyHint: true` — tells clients this tool does NOT
+ *  modify disk; `false` — tells them it does. */
+const TOOL_READONLY: Record<string, boolean> = {
+  gdd_state__get: true,
+};
+
+/**
+ * Build the MCP server. The tools list and call handlers are the only
+ * two request handlers we register; everything else (initialize, ping,
+ * cancellation, shutdown) is handled internally by the Protocol class.
+ */
+export function buildServer(): Server {
+  const tools = loadTools();
+  const byName: Map<string, LoadedTool> = new Map();
+  for (const t of tools) byName.set(t.name, t);
+
+  const server = new Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    {
+      capabilities: { tools: {} },
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: tools.map((t) => {
+        const description = TOOL_DESCRIPTIONS[t.name] ?? t.name;
+        const readOnly = TOOL_READONLY[t.name] ?? false;
+        return {
+          name: t.name,
+          description,
+          inputSchema: t.inputSchema as {
+            type: 'object';
+            properties?: Record<string, unknown>;
+            required?: string[];
+          },
+          annotations: {
+            readOnlyHint: readOnly,
+            destructiveHint: !readOnly,
+            idempotentHint: false,
+          },
+        };
+      }),
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name: toolName, arguments: args } = req.params;
+    const tool = byName.get(toolName);
+    if (tool === undefined) {
+      // Unknown tool — return as CallToolResult isError=true so the
+      // client gets a structured error rather than a JSON-RPC error.
+      const payload = toToolError(
+        new Error(`unknown tool: ${toolName}`),
+      );
+      return {
+        isError: true,
+        content: [
+          { type: 'text' as const, text: JSON.stringify({ success: false, error: payload.error }) },
+        ],
+        structuredContent: { success: false, error: payload.error },
+      };
+    }
+
+    let response;
+    try {
+      response = await tool.handle(args ?? {});
+    } catch (err) {
+      // Defensive catch — handlers shouldn't throw, but if one does
+      // we translate rather than crashing the server.
+      const payload = toToolError(err);
+      response = { success: false as const, error: payload.error };
+    }
+
+    const text = JSON.stringify(response);
+    if (response.success === true) {
+      return {
+        content: [{ type: 'text' as const, text }],
+        structuredContent: response as unknown as Record<string, unknown>,
+      };
+    }
+    return {
+      isError: true,
+      content: [{ type: 'text' as const, text }],
+      structuredContent: response as unknown as Record<string, unknown>,
+    };
+  });
+
+  return server;
+}
+
+/**
+ * Run the server against stdio and block until the transport closes.
+ * Called from CLI when this file is invoked as a script.
+ */
+export async function runStdio(): Promise<void> {
+  const server = buildServer();
+  const transport = new StdioServerTransport();
+
+  const shutdown = async (signal: string): Promise<void> => {
+    // Re-entrant: signal handlers can fire more than once on flaky
+    // shells. Guard with a module-level flag.
+    if (SHUTTING_DOWN) return;
+    SHUTTING_DOWN = true;
+    try {
+      await server.close();
+    } catch {
+      // best-effort; we're exiting anyway.
+    }
+    // SIGTERM / SIGINT convention: exit(0) — orderly shutdown.
+    process.exit(signal === 'SIGTERM' ? 0 : 0);
+  };
+
+  process.on('SIGINT', () => {
+    void shutdown('SIGINT');
+  });
+  process.on('SIGTERM', () => {
+    void shutdown('SIGTERM');
+  });
+
+  await server.connect(transport);
+}
+
+/** Re-entrancy guard for `shutdown()`. */
+let SHUTTING_DOWN = false;
+
+/**
+ * Are we being invoked as a script? We compare the argv[1] file path's
+ * basename to `server.ts` — test imports never match this because
+ * `node --test tests/*.ts` sets argv[1] to the test runner entry, not
+ * our file. A direct `node sdk/mcp/gdd-state/server.ts`
+ * invocation DOES match.
+ */
+// Extension-agnostic (.ts | .js | .cjs | .mjs): the dual-mode bin trampoline
+// (Plan 31-5-9.5, D-16) runs the raw `.ts` in-repo via --experimental-strip-types
+// AND the esbuild-bundled `.js` from a packed/installed tarball. argv[1] ends in
+// `.js` in the compiled path, so a `.ts`-only check would never start the server.
+function isMain(): boolean {
+  const entry = process.argv[1];
+  if (typeof entry !== 'string' || entry.length === 0) return false;
+  return /sdk\/mcp\/gdd-state\/server\.(ts|js|cjs|mjs)$/.test(
+    entry.replace(/\\/g, '/'),
+  );
+}
+
+if (isMain()) {
+  runStdio().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    // eslint-disable-next-line no-console
+    console.error(`[gdd-state] fatal: ${msg}`);
+    process.exit(1);
+  });
+}

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/add_blocker.ts

@@ -1,12 +1,12 @@
-// scripts/mcp-servers/gdd-state/tools/add_blocker.ts
+// sdk/mcp/gdd-state/tools/add_blocker.ts
 //
 // Tool: gdd_state__add_blocker
 // Purpose: Append one entry to <blockers>. Defaults the stage to the
 // current <position>.stage and the date to today (UTC) when omitted.
 // Emits state.mutation on success.
 
-import { mutate } from '../../../lib/gdd-state/index.ts';
-import type { Blocker } from '../../../lib/gdd-state/types.ts';
+import { mutate } from '../../../state/index.ts';
+import type { Blocker } from '../../../state/types.ts';
 import {
   emitStateMutation,
   errorResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/add_decision.ts

@@ -1,12 +1,12 @@
-// scripts/mcp-servers/gdd-state/tools/add_decision.ts
+// sdk/mcp/gdd-state/tools/add_decision.ts
 //
 // Tool: gdd_state__add_decision
 // Purpose: Append one entry to <decisions>. Auto-allocates D-N id by
 // scanning existing decisions when the caller doesn't supply one.
 // Emits state.mutation on success.
 
-import { mutate } from '../../../lib/gdd-state/index.ts';
-import type { Decision } from '../../../lib/gdd-state/types.ts';
+import { mutate } from '../../../state/index.ts';
+import type { Decision } from '../../../state/types.ts';
 import {
   emitStateMutation,
   errorResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/add_must_have.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-state/tools/add_must_have.ts
+// sdk/mcp/gdd-state/tools/add_must_have.ts
 //
 // Tool: gdd_state__add_must_have
 // Purpose: Insert-or-update one entry in <must_haves>. Auto-allocates
@@ -9,8 +9,8 @@
 // skill (see skills/verify/SKILL.md "Flipping a must-have status").
 // Emits state.mutation on success with `action: "insert" | "update"`.
 
-import { mutate } from '../../../lib/gdd-state/index.ts';
-import type { MustHave } from '../../../lib/gdd-state/types.ts';
+import { mutate } from '../../../state/index.ts';
+import type { MustHave } from '../../../state/types.ts';
 import {
   emitStateMutation,
   errorResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/checkpoint.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-state/tools/checkpoint.ts
+// sdk/mcp/gdd-state/tools/checkpoint.ts
 //
 // Tool: gdd_state__checkpoint
 // Purpose: Update frontmatter.last_checkpoint and append an entry in
@@ -6,7 +6,7 @@
 // supplied, otherwise `<stage>_checkpoint_at` falling back to
 // `checkpoint_at` if the position.stage is empty. Emits state.mutation.
 
-import { mutate } from '../../../lib/gdd-state/index.ts';
+import { mutate } from '../../../state/index.ts';
 import {
   emitStateMutation,
   errorResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/frontmatter_update.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-state/tools/frontmatter_update.ts
+// sdk/mcp/gdd-state/tools/frontmatter_update.ts
 //
 // Tool: gdd_state__frontmatter_update
 // Purpose: Patch one or more frontmatter fields. Rejects two forbidden
@@ -8,7 +8,7 @@
 //                                gates and emits state.transition)
 // Emits state.mutation on success.
 
-import { mutate } from '../../../lib/gdd-state/index.ts';
+import { mutate } from '../../../state/index.ts';
 import {
   emitStateMutation,
   errorResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/get.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-state/tools/get.ts
+// sdk/mcp/gdd-state/tools/get.ts
 //
 // Tool: gdd_state__get
 // Purpose: Read current STATE.md (parsed). Read-only; does NOT emit an
@@ -6,8 +6,8 @@
 // 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 { read } from '../../../state/index.ts';
+import type { ParsedState } from '../../../state/types.ts';
 import {
   errorResponse,
   okResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/index.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-state/tools/index.ts
+// sdk/mcp/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

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/probe_connections.ts

@@ -1,15 +1,15 @@
-// scripts/mcp-servers/gdd-state/tools/probe_connections.ts
+// sdk/mcp/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 { mutate } from '../../../state/index.ts';
 import {
   isConnectionStatus,
   type ConnectionStatus,
-} from '../../../lib/gdd-state/types.ts';
+} from '../../../state/types.ts';
 import {
   emitStateMutation,
   errorResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/resolve_blocker.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-state/tools/resolve_blocker.ts
+// sdk/mcp/gdd-state/tools/resolve_blocker.ts
 //
 // Tool: gdd_state__resolve_blocker
 // Purpose: Remove one entry from <blockers> by 0-based index OR by
@@ -6,8 +6,8 @@
 // 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 { mutate } from '../../../state/index.ts';
+import type { Blocker } from '../../../state/types.ts';
 import {
   emitStateMutation,
   errorResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/set_status.ts

@@ -1,11 +1,11 @@
-// scripts/mcp-servers/gdd-state/tools/set_status.ts
+// sdk/mcp/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 { mutate } from '../../../state/index.ts';
 import {
   emitStateMutation,
   errorResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/shared.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-state/tools/shared.ts
+// sdk/mcp/gdd-state/tools/shared.ts
 //
 // Shared types + helpers for the 11 gdd-state tool handlers (Plan 20-05).
 // Every handler returns one of:
@@ -7,23 +7,23 @@
 //   { 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`.
+// through `toToolError()` from `sdk/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';
+} from '../../../errors/index.ts';
+import { toToolError } from '../../../errors/classification.ts';
+import type { ToolErrorPayload } from '../../../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';
+} from '../../../event-stream/index.ts';
+import type { ParsedState, Stage } from '../../../state/types.ts';
 
 /** Public tool-handler response shape (consistent across all 11 tools). */
 export type ToolResponse =
@@ -84,7 +84,7 @@ export function hasStage(state: ParsedState): state is ParsedState {
  * 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
+ * see `sdk/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.
  */

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/transition_stage.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-state/tools/transition_stage.ts
+// sdk/mcp/gdd-state/tools/transition_stage.ts
 //
 // Tool: gdd_state__transition_stage
 // Purpose: Run gate and advance <position>.stage / frontmatter.stage on
@@ -11,9 +11,9 @@
 // (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 { read, transition } from '../../../state/index.ts';
+import { isStage, type Stage } from '../../../state/types.ts';
+import { TransitionGateFailed } from '../../../errors/index.ts';
 import {
   emitStateTransition,
   errorResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-state/tools/update_progress.ts

@@ -1,10 +1,10 @@
-// scripts/mcp-servers/gdd-state/tools/update_progress.ts
+// sdk/mcp/gdd-state/tools/update_progress.ts
 //
 // Tool: gdd_state__update_progress
 // Purpose: Update <position>.task_progress and/or <position>.status.
 // Emits state.mutation on success.
 
-import { mutate } from '../../../lib/gdd-state/index.ts';
+import { mutate } from '../../../state/index.ts';
 import {
   emitStateMutation,
   errorResponse,