@hegemonart/get-design-done 1.31.0 → 1.32.0

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,