@hegemonart/get-design-done 1.30.6 → 1.31.5

package/scripts/mcp-servers/gdd-state/server.ts

@@ -1,288 +1,34 @@
-#!/usr/bin/env -S node --experimental-strip-types
-// scripts/mcp-servers/gdd-state/server.ts
+// scripts/mcp-servers/gdd-state/server.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// MCP server `gdd-state` — exposes the 11 typed STATE.md tools implemented
-// under `./tools/` via stdio transport. Plan 20-05 (SDK-06/07).
+// Thin deprecation shim. The real MCP `gdd-state` server moved to
+// sdk/mcp/gdd-state/server.ts in Plan 31-5-04 (SDK consolidation). This file
+// is re-created at the OLD path so undocumented EXTERNAL importers / invokers
+// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
+// mcp-servers/gdd-state/server.ts directly) keep working for one minor grace
+// window.
 //
-// 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.
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. The canonical invocation is
+// now the `bin/gdd-state-mcp` trampoline (Plan 31-5-05); internal callers
+// already use the sdk/ path. This shim is external-only; 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the
+// GDD-DEPRECATION-SHIM marker above.
 //
-// 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 '../../lib/gdd-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 `scripts/mcp-servers/gdd-state`
- * resolves reliably. Both branches are canonicalized against the
- * on-disk tools directory.
- */
-function here(): string {
-  const expectedRel = join('scripts', 'mcp-servers', '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: {} },
-    },
+// Re-exporting the sdk/ server keeps the library surface (buildServer,
+// runStdio) reachable via the old path. The sdk/ server's own isMain()
+// entry guard keys off process.argv[1] ending with its own sdk/ path, so a
+// re-export does NOT auto-start the server — direct execution should go
+// through the bin trampoline. Runs under --experimental-strip-types.
+
+import { emitWarning } from 'node:process';
+
+let warned = false;
+if (!warned) {
+  warned = true;
+  emitWarning(
+    'scripts/mcp-servers/gdd-state/server.ts is deprecated; use the bin/gdd-state-mcp trampoline or import sdk/mcp/gdd-state instead. Removed in v1.33.0.',
+    'DeprecationWarning',
   );
-
-  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 scripts/mcp-servers/gdd-state/server.ts`
- * invocation DOES match.
- */
-function isMain(): boolean {
-  const entry = process.argv[1];
-  if (typeof entry !== 'string' || entry.length === 0) return false;
-  return entry.replace(/\\/g, '/').endsWith('scripts/mcp-servers/gdd-state/server.ts');
-}
-
-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);
-  });
-}
+export * from '../../../sdk/mcp/gdd-state/server.ts';

package/sdk/README.md

@@ -0,0 +1,45 @@
+# `@hegemonart/get-design-done` SDK
+
+The SDK is the typed, runtime-tested core that the GDD pipeline and both MCP
+servers are built on. It is plain TypeScript run under Node 22+
+`--experimental-strip-types` (no build step). Five concerns live here: the
+**`gdd-state` MCP server** (11 typed STATE.md tools over stdio), **lockfile-safe
+STATE.md** read / mutate / transition, the **append-only event stream** (JSONL +
+in-process bus), the four **resilience primitives** (`.cjs` + `.d.cts`), and the
+headless **`gdd-sdk` CLI**.
+
+## Import contract (D-04)
+
+Prefer the **explicit per-module path** for the surface you need. The
+`sdk/index.ts` barrel re-exports state / event-stream / errors / cli for callers
+who want one entry point; the bare-package root import is reserved for the
+install bin. Every path below is importable from the published package.
+
+| Module          | Public import                                       | Helpers (key exports)                                                                 | Stability |
+| --------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------- | --------- |
+| cli             | `@hegemonart/get-design-done/sdk/cli`               | `dispatch`, `main`, `USAGE`, `DispatcherDeps`                                          | beta      |
+| state           | `@hegemonart/get-design-done/sdk/state`             | `read`, `mutate`, `transition`, `ParsedState`, `Stage`                                | beta      |
+| event-stream    | `@hegemonart/get-design-done/sdk/event-stream`      | `appendEvent`, `getWriter`, `getBus`, `subscribe`, `subscribeAll`, `reset`, `readEvents`, `aggregate`, `EventBus`, `EventWriter`, `KNOWN_EVENT_TYPES` | beta      |
+| errors          | `@hegemonart/get-design-done/sdk/errors`            | `GDDError`, `ValidationError`, `StateConflictError`, `OperationFailedError`, `TransitionGateFailed`, `LockAcquisitionError`, `ParseError` | beta      |
+| primitives/error-classifier   | `@hegemonart/get-design-done/sdk/primitives/error-classifier`   | `classify`, `FailoverReason`                              | stable    |
+| primitives/iteration-budget   | `@hegemonart/get-design-done/sdk/primitives/iteration-budget`   | `consume`, `refund`, `remaining`, `reset`, `IterationBudgetExhaustedError` | stable    |
+| primitives/jittered-backoff   | `@hegemonart/get-design-done/sdk/primitives/jittered-backoff`   | `delayMs`, `sleep`, `DEFAULTS`                            | stable    |
+| primitives/lockfile           | `@hegemonart/get-design-done/sdk/primitives/lockfile`           | `acquire`, `renameWithRetry`                              | stable    |
+| mcp/gdd-state   | `@hegemonart/get-design-done/sdk/mcp/gdd-state`     | `buildServer` (server.ts) — 11 STATE.md tools over stdio                              | beta      |
+
+The barrel: `import { read, appendEvent, ValidationError } from '@hegemonart/get-design-done/sdk'`.
+
+## Notes
+
+- **Primitives are `stable`** (D-05): they ship as `.cjs` + `.d.cts` pairs and
+  are the most-imported surface; the TS migration is a separate phase.
+- **`state` re-exports the three error classes** (`TransitionGateFailed`,
+  `LockAcquisitionError`, `ParseError`) from `errors` verbatim, so importing
+  them from either path yields the same identity.
+- The event stream persists to `.design/telemetry/events.jsonl`; `appendEvent`
+  is persist-first / broadcast-second and never throws on the persist path.
+- `mutate()` / `transition()` take an advisory sibling lockfile; one process per
+  `.design/` is the design contract.
+
+See `connections/gdd-state.md` for the MCP wiring and the runtime fallback that
+imports the `state` module directly when the MCP is `not_configured`.

package/{scripts/lib → sdk}/cli/commands/audit.ts

@@ -1,4 +1,4 @@
-// scripts/lib/cli/commands/audit.ts — Plan 21-09 Task 5 (SDK-21).
+// sdk/cli/commands/audit.ts — Plan 21-09 Task 5 (SDK-21).
 //
 // `gdd-sdk audit` — regression + verification dry-run.
 //
@@ -25,8 +25,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 
-import { read } from '../../gdd-state/index.ts';
-import type { ConnectionStatus, ParsedState } from '../../gdd-state/types.ts';
+import { read } from '../../state/index.ts';
+import type { ConnectionStatus, ParsedState } from '../../state/types.ts';
 
 import {
   coerceFlags,

package/{scripts/lib → sdk}/cli/commands/init.ts

@@ -1,4 +1,4 @@
-// scripts/lib/cli/commands/init.ts — Plan 21-09 Task 6 (SDK-21).
+// sdk/cli/commands/init.ts — Plan 21-09 Task 6 (SDK-21).
 //
 // `gdd-sdk init` — bootstrap a new project's `.design/` directory by
 // delegating to `init-runner.run()` (Plan 21-08).
@@ -16,8 +16,8 @@
 import {
   run as defaultInitRun,
   type InitRunnerResult,
-} from '../../init-runner/index.ts';
-import { getLogger } from '../../logger/index.ts';
+} from '../../../scripts/lib/init-runner/index.ts';
+import { getLogger } from '../../../scripts/lib/logger/index.ts';
 
 import {
   coerceFlags,

package/{scripts/lib → sdk}/cli/commands/query.ts

@@ -1,4 +1,4 @@
-// scripts/lib/cli/commands/query.ts — Plan 21-09 Task 4 (SDK-21).
+// sdk/cli/commands/query.ts — Plan 21-09 Task 4 (SDK-21).
 //
 // `gdd-sdk query <op>` — typed STATE.md read operations. Mirrors the
 // read side of the gdd-state MCP server. Never mutates — use the
@@ -20,9 +20,9 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 
-import { read } from '../../gdd-state/index.ts';
-import { gateFor } from '../../gdd-state/gates.ts';
-import { isStage, type ParsedState, type Stage } from '../../gdd-state/types.ts';
+import { read } from '../../state/index.ts';
+import { gateFor } from '../../state/gates.ts';
+import { isStage, type ParsedState, type Stage } from '../../state/types.ts';
 
 import {
   coerceFlags,

package/{scripts/lib → sdk}/cli/commands/run.ts

@@ -1,4 +1,4 @@
-// scripts/lib/cli/commands/run.ts — Plan 21-09 Task 2 (SDK-21),
+// sdk/cli/commands/run.ts — Plan 21-09 Task 2 (SDK-21),
 // extended by Plan 21-11 Task 3 (dry-run).
 //
 // `gdd-sdk run` — drives the full design pipeline via
@@ -36,10 +36,10 @@ import {
   type RunOverrides,
   type Stage,
   type StageOutcome,
-} from '../../pipeline-runner/index.ts';
-import { getLogger } from '../../logger/index.ts';
-import { ValidationError } from '../../gdd-errors/index.ts';
-import type { SessionResult, SessionRunnerOptions } from '../../session-runner/types.ts';
+} from '../../../scripts/lib/pipeline-runner/index.ts';
+import { getLogger } from '../../../scripts/lib/logger/index.ts';
+import { ValidationError } from '../../errors/index.ts';
+import type { SessionResult, SessionRunnerOptions } from '../../../scripts/lib/session-runner/types.ts';
 
 import {
   coerceFlags,

package/{scripts/lib → sdk}/cli/commands/stage.ts

@@ -1,4 +1,4 @@
-// scripts/lib/cli/commands/stage.ts — Plan 21-09 Task 3 (SDK-21).
+// sdk/cli/commands/stage.ts — Plan 21-09 Task 3 (SDK-21).
 //
 // `gdd-sdk stage <name>` — run a single pipeline stage. Delegates to
 // `pipeline-runner.run()` with `stages: [<name>]` for design-pipeline
@@ -24,16 +24,16 @@ import {
   type PipelineConfig,
   type PipelineResult,
   type Stage,
-} from '../../pipeline-runner/index.ts';
+} from '../../../scripts/lib/pipeline-runner/index.ts';
 import {
   run as defaultExploreParallelRun,
   type ExploreRunnerResult,
-} from '../../explore-parallel-runner/index.ts';
+} from '../../../scripts/lib/explore-parallel-runner/index.ts';
 import {
   run as defaultDiscussParallelRun,
   type DiscussRunnerResult,
-} from '../../discuss-parallel-runner/index.ts';
-import { getLogger } from '../../logger/index.ts';
+} from '../../../scripts/lib/discuss-parallel-runner/index.ts';
+import { getLogger } from '../../../scripts/lib/logger/index.ts';
 
 import {
   coerceFlags,