@hegemonart/get-design-done 1.32.0 → 1.33.5

package/sdk/mcp/gdd-state/tools/shared.ts

@@ -11,6 +11,7 @@
 // This mirrors the invariant in the plan: "Tool errors are returned as
 // {success:false, error} — handlers never propagate exceptions."
 
+import path from 'node:path';
 import {
   ValidationError,
   OperationFailedError,
@@ -50,17 +51,126 @@ export function getSessionId(): string {
 }
 
 /**
- * Resolve the target STATE.md path from the environment. Mirrors the
- * plan's contract: `process.env.GDD_STATE_PATH ?? .design/STATE.md`.
+ * Resolve the target STATE.md path from the environment, with a
+ * PATH-TRAVERSAL guard (Plan 33.5-03, D-08).
  *
- * 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.
+ * Resolution: `process.env.GDD_STATE_PATH ?? .design/STATE.md`. The
+ * path-traversal threat this guards against is a RELATIVE override that uses
+ * `..` to escape the project root — that is REJECTED with a
+ * `VALIDATION_STATE_PATH_ESCAPE` error. An ABSOLUTE override is an explicit
+ * operator choice (a relocated state file, a CI tmp `.design`) and is ALLOWED,
+ * normalized (D-08) — it is NOT rejected merely for living outside cwd (that
+ * would break legitimate operator overrides, and a realpath-based boundary
+ * check diverges across platforms, e.g. macOS /var → /private/var).
+ *
+ * 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';
+  if (typeof override !== 'string' || override.length === 0) {
+    return '.design/STATE.md';
+  }
+
+  // ABSOLUTE override = explicit operator choice → allow, normalized (D-08).
+  if (path.isAbsolute(override)) {
+    return path.resolve(override);
+  }
+
+  // RELATIVE override: resolve against the project root and REJECT any `..`
+  // traversal that escapes the boundary. In-boundary iff it equals root or
+  // sits beneath `root + sep`.
+  const root = path.resolve(process.cwd());
+  const resolved = path.resolve(root, override);
+  const withSep = root.endsWith(path.sep) ? root : root + path.sep;
+  if (resolved !== root && !resolved.startsWith(withSep)) {
+    throwValidation(
+      'STATE_PATH_ESCAPE',
+      `GDD_STATE_PATH (relative) escapes the project boundary: ${override}`,
+      { raw: override, resolved, root },
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Documented input limits for the gdd-state tools (Plan 33.5-03, D-08).
+ * Defends against JSON-bomb / memory-exhaustion inputs. The schema
+ * `maxLength` bounds are the declarative twin of MAX_STRING_LEN.
+ */
+export const MAX_INPUT_BYTES = 64 * 1024; // 64 KiB serialized input cap
+export const MAX_STRING_LEN = 8192; // longest single free-form string field
+export const MAX_DEPTH = 32; // deepest object/array nesting
+
+interface InputLimitOpts {
+  maxInputBytes?: number;
+  maxStringLen?: number;
+  maxDepth?: number;
+}
+
+/**
+ * Reject oversized / pathologically deep tool inputs BEFORE processing
+ * (Plan 33.5-03, D-08). Throws a `VALIDATION_INPUT_*` error on breach:
+ *   - INPUT_TOO_LARGE   — serialized JSON byte-size exceeds the cap
+ *   - INPUT_FIELD_TOO_LARGE — a single string field exceeds MAX_STRING_LEN
+ *   - INPUT_TOO_DEEP    — object/array nesting exceeds MAX_DEPTH
+ * Handlers call this on their raw input; it is also unit-tested directly.
+ */
+export function assertInputWithinLimits(
+  input: unknown,
+  opts?: InputLimitOpts,
+): void {
+  const maxBytes = opts?.maxInputBytes ?? MAX_INPUT_BYTES;
+  const maxStr = opts?.maxStringLen ?? MAX_STRING_LEN;
+  const maxDepth = opts?.maxDepth ?? MAX_DEPTH;
+
+  // Walk first so a deep/long field is caught even on huge inputs, bounding
+  // the depth so the walk itself cannot be turned into the attack.
+  const walk = (node: unknown, depth: number): void => {
+    if (depth > maxDepth) {
+      throwValidation(
+        'INPUT_TOO_DEEP',
+        `Input nesting exceeds the maximum depth of ${maxDepth}`,
+        { maxDepth },
+      );
+    }
+    if (typeof node === 'string') {
+      if (node.length > maxStr) {
+        throwValidation(
+          'INPUT_FIELD_TOO_LARGE',
+          `A string field exceeds the maximum length of ${maxStr}`,
+          { maxStringLen: maxStr, length: node.length },
+        );
+      }
+      return;
+    }
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item, depth + 1);
+      return;
+    }
+    if (node !== null && typeof node === 'object') {
+      for (const value of Object.values(node as Record<string, unknown>)) {
+        walk(value, depth + 1);
+      }
+    }
+  };
+  walk(input, 0);
+
+  // Total serialized byte-size cap (JSON-bomb guard). Guard against a circular
+  // structure — JSON.stringify would throw; treat that as a rejectable input.
+  let bytes: number;
+  try {
+    bytes = Buffer.byteLength(JSON.stringify(input) ?? '');
+  } catch {
+    throwValidation('INPUT_TOO_LARGE', 'Input is not serializable JSON', {});
+  }
+  if (bytes > maxBytes) {
+    throwValidation(
+      'INPUT_TOO_LARGE',
+      `Serialized input (${bytes} bytes) exceeds the maximum of ${maxBytes} bytes`,
+      { maxInputBytes: maxBytes, bytes },
+    );
+  }
 }
 
 /** Narrow helper: is this a well-known Stage string? */

package/sdk/mcp/gdd-state/tools/transition_stage.ts

@@ -15,6 +15,7 @@ import { read, transition } from '../../../state/index.ts';
 import { isStage, type Stage } from '../../../state/types.ts';
 import { TransitionGateFailed } from '../../../errors/index.ts';
 import {
+  assertInputWithinLimits,
   emitStateTransition,
   errorResponse,
   okResponse,
@@ -32,6 +33,7 @@ export interface TransitionStageInput {
 
 export async function handle(input: unknown): Promise<ToolResponse> {
   try {
+    assertInputWithinLimits(input);
     const typed = (input ?? {}) as TransitionStageInput;
     if (!isStage(typed.to)) {
       throwValidation(

package/sdk/mcp/gdd-state/tools/update_progress.ts

@@ -6,6 +6,7 @@
 
 import { mutate } from '../../../state/index.ts';
 import {
+  assertInputWithinLimits,
   emitStateMutation,
   errorResponse,
   okResponse,
@@ -35,6 +36,7 @@ const STATUSES = new Set([
 
 export async function handle(input: unknown): Promise<ToolResponse> {
   try {
+    assertInputWithinLimits(input);
     const typed = (input ?? {}) as UpdateProgressInput;
     if (typed.task_progress === undefined && typed.status === undefined) {
       throwValidation(

package/scripts/lib/cli/index.ts

@@ -1,29 +0,0 @@
-// scripts/lib/cli/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// Thin deprecation shim. The real implementation moved to sdk/cli/index.ts
-// in Plan 31-5-04 (SDK consolidation). This file is re-created at the OLD
-// path so undocumented EXTERNAL importers (anyone who reached into
-// node_modules/@hegemonart/get-design-done/scripts/lib/cli/index.ts directly)
-// keep working for one minor grace window.
-//
-// 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. Internal callers already use
-// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
-// no-stale-internal-refs guard excludes files carrying the
-// GDD-DEPRECATION-SHIM marker above.
-//
-// Runs under --experimental-strip-types (the runtime `bin/gdd-sdk` and the
-// test suite both use it), so `export *` re-export is strip-types-clean.
-
-import { emitWarning } from 'node:process';
-
-let warned = false;
-if (!warned) {
-  warned = true;
-  emitWarning(
-    'scripts/lib/cli/index.ts is deprecated; import sdk/cli instead. Removed in v1.33.0.',
-    'DeprecationWarning',
-  );
-}
-
-export * from '../../../sdk/cli/index.ts';

package/scripts/lib/error-classifier.cjs

@@ -1,29 +0,0 @@
-'use strict';
-// scripts/lib/error-classifier.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// Thin deprecation shim. The real implementation moved to
-// sdk/primitives/error-classifier.cjs in Plan 31-5-04 (SDK consolidation).
-// This file is re-created at the OLD path so undocumented EXTERNAL importers
-// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
-// lib/error-classifier.cjs directly) keep working for one minor grace window.
-//
-// 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. Internal callers already use
-// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
-// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
-// marker above.
-//
-// Emits a DeprecationWarning exactly ONCE per process: the module-level
-// `warned` flag plus Node's module cache (this file is evaluated once per
-// process regardless of how many times it is required).
-
-let warned = false;
-if (!warned) {
-  warned = true;
-  process.emitWarning(
-    'scripts/lib/error-classifier.cjs is deprecated; import sdk/primitives/error-classifier instead. Removed in v1.33.0.',
-    'DeprecationWarning',
-  );
-}
-
-module.exports = require('../../sdk/primitives/error-classifier.cjs');

package/scripts/lib/event-stream/index.ts

@@ -1,29 +0,0 @@
-// scripts/lib/event-stream/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// Thin deprecation shim. The real implementation moved to
-// sdk/event-stream/index.ts in Plan 31-5-04 (SDK consolidation). This file
-// is re-created at the OLD path so undocumented EXTERNAL importers (anyone
-// who reached into node_modules/@hegemonart/get-design-done/scripts/lib/
-// event-stream/index.ts directly) keep working for one minor grace window.
-//
-// 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. Internal callers already use
-// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
-// no-stale-internal-refs guard excludes files carrying the
-// GDD-DEPRECATION-SHIM marker above.
-//
-// Runs under --experimental-strip-types, so `export *` re-export is
-// strip-types-clean.
-
-import { emitWarning } from 'node:process';
-
-let warned = false;
-if (!warned) {
-  warned = true;
-  emitWarning(
-    'scripts/lib/event-stream/index.ts is deprecated; import sdk/event-stream instead. Removed in v1.33.0.',
-    'DeprecationWarning',
-  );
-}
-
-export * from '../../../sdk/event-stream/index.ts';

package/scripts/lib/gdd-errors/index.ts

@@ -1,29 +0,0 @@
-// scripts/lib/gdd-errors/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// Thin deprecation shim. The real implementation moved to sdk/errors/index.ts
-// in Plan 31-5-04 (SDK consolidation). This file is re-created at the OLD
-// path so undocumented EXTERNAL importers (anyone who reached into
-// node_modules/@hegemonart/get-design-done/scripts/lib/gdd-errors/index.ts
-// directly) keep working for one minor grace window.
-//
-// 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. Internal callers already use
-// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
-// no-stale-internal-refs guard excludes files carrying the
-// GDD-DEPRECATION-SHIM marker above.
-//
-// Runs under --experimental-strip-types, so `export *` re-export is
-// strip-types-clean.
-
-import { emitWarning } from 'node:process';
-
-let warned = false;
-if (!warned) {
-  warned = true;
-  emitWarning(
-    'scripts/lib/gdd-errors/index.ts is deprecated; import sdk/errors instead. Removed in v1.33.0.',
-    'DeprecationWarning',
-  );
-}
-
-export * from '../../../sdk/errors/index.ts';

package/scripts/lib/gdd-state/index.ts

@@ -1,29 +0,0 @@
-// scripts/lib/gdd-state/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// Thin deprecation shim. The real implementation moved to sdk/state/index.ts
-// in Plan 31-5-04 (SDK consolidation). This file is re-created at the OLD
-// path so undocumented EXTERNAL importers (anyone who reached into
-// node_modules/@hegemonart/get-design-done/scripts/lib/gdd-state/index.ts
-// directly) keep working for one minor grace window.
-//
-// 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. Internal callers already use
-// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
-// no-stale-internal-refs guard excludes files carrying the
-// GDD-DEPRECATION-SHIM marker above.
-//
-// Runs under --experimental-strip-types, so `export *` re-export is
-// strip-types-clean.
-
-import { emitWarning } from 'node:process';
-
-let warned = false;
-if (!warned) {
-  warned = true;
-  emitWarning(
-    'scripts/lib/gdd-state/index.ts is deprecated; import sdk/state instead. Removed in v1.33.0.',
-    'DeprecationWarning',
-  );
-}
-
-export * from '../../../sdk/state/index.ts';

package/scripts/lib/iteration-budget.cjs

@@ -1,29 +0,0 @@
-'use strict';
-// scripts/lib/iteration-budget.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// Thin deprecation shim. The real implementation moved to
-// sdk/primitives/iteration-budget.cjs in Plan 31-5-04 (SDK consolidation).
-// This file is re-created at the OLD path so undocumented EXTERNAL importers
-// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
-// lib/iteration-budget.cjs directly) keep working for one minor grace window.
-//
-// 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. Internal callers already use
-// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
-// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
-// marker above.
-//
-// Emits a DeprecationWarning exactly ONCE per process: the module-level
-// `warned` flag plus Node's module cache (this file is evaluated once per
-// process regardless of how many times it is required).
-
-let warned = false;
-if (!warned) {
-  warned = true;
-  process.emitWarning(
-    'scripts/lib/iteration-budget.cjs is deprecated; import sdk/primitives/iteration-budget instead. Removed in v1.33.0.',
-    'DeprecationWarning',
-  );
-}
-
-module.exports = require('../../sdk/primitives/iteration-budget.cjs');

package/scripts/lib/jittered-backoff.cjs

@@ -1,29 +0,0 @@
-'use strict';
-// scripts/lib/jittered-backoff.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// Thin deprecation shim. The real implementation moved to
-// sdk/primitives/jittered-backoff.cjs in Plan 31-5-04 (SDK consolidation).
-// This file is re-created at the OLD path so undocumented EXTERNAL importers
-// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
-// lib/jittered-backoff.cjs directly) keep working for one minor grace window.
-//
-// 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. Internal callers already use
-// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
-// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
-// marker above.
-//
-// Emits a DeprecationWarning exactly ONCE per process: the module-level
-// `warned` flag plus Node's module cache (this file is evaluated once per
-// process regardless of how many times it is required).
-
-let warned = false;
-if (!warned) {
-  warned = true;
-  process.emitWarning(
-    'scripts/lib/jittered-backoff.cjs is deprecated; import sdk/primitives/jittered-backoff instead. Removed in v1.33.0.',
-    'DeprecationWarning',
-  );
-}
-
-module.exports = require('../../sdk/primitives/jittered-backoff.cjs');

package/scripts/lib/lockfile.cjs

@@ -1,29 +0,0 @@
-'use strict';
-// scripts/lib/lockfile.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// Thin deprecation shim. The real implementation moved to
-// sdk/primitives/lockfile.cjs in Plan 31-5-04 (SDK consolidation).
-// This file is re-created at the OLD path so undocumented EXTERNAL importers
-// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
-// lib/lockfile.cjs directly) keep working for one minor grace window.
-//
-// 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. Internal callers already use
-// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
-// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
-// marker above.
-//
-// Emits a DeprecationWarning exactly ONCE per process: the module-level
-// `warned` flag plus Node's module cache (this file is evaluated once per
-// process regardless of how many times it is required).
-
-let warned = false;
-if (!warned) {
-  warned = true;
-  process.emitWarning(
-    'scripts/lib/lockfile.cjs is deprecated; import sdk/primitives/lockfile instead. Removed in v1.33.0.',
-    'DeprecationWarning',
-  );
-}
-
-module.exports = require('../../sdk/primitives/lockfile.cjs');

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

@@ -1,35 +0,0 @@
-// scripts/mcp-servers/gdd-mcp/server.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// Thin deprecation shim. The real MCP `gdd-mcp` server moved to
-// sdk/mcp/gdd-mcp/server.ts in Plan 31-5-05 (SDK consolidation, D-08). 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-mcp/server.ts directly) keep working for one minor
-// grace window.
-//
-// 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-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.
-//
-// Re-exporting the sdk/ server keeps the library surface (buildServer,
-// runStdio, SERVER_NAME, SERVER_VERSION, TOOL_DESCRIPTIONS, TOOL_READONLY)
-// 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-mcp/server.ts is deprecated; use the bin/gdd-mcp trampoline or import sdk/mcp/gdd-mcp instead. Removed in v1.33.0.',
-    'DeprecationWarning',
-  );
-}
-
-export * from '../../../sdk/mcp/gdd-mcp/server.ts';

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

@@ -1,34 +0,0 @@
-// scripts/mcp-servers/gdd-state/server.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
-//
-// 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.
-//
-// 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.
-//
-// 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',
-  );
-}
-
-export * from '../../../sdk/mcp/gdd-state/server.ts';