bdba40cc3d
* fix(#2618): thread --ws through query dispatch for state and init handlers Gap 1 of #2618: the query dispatcher already accepts a workstream via registry.dispatch(cmd, args, projectDir, ws), but several handlers drop it before reaching planningPaths() / getMilestoneInfo() / findPhase() — so stateJson and the init.* handlers return root-scoped results even when --ws is provided. Changes: - sdk/src/query/state.ts: forward workstream into getMilestoneInfo() and extractCurrentMilestone() so buildStateFrontmatter resolves milestone data from the workstream ROADMAP/STATE instead of the root mirror. - sdk/src/query/init.ts: thread workstream through initExecutePhase, initPlanPhase, initPhaseOp, and getPhaseInfoWithFallback (which fans out to findPhase() and roadmapGetPhase()). Also switch hardcoded join(projectDir, '.planning') to relPlanningPath(workstream) so returned state_path/roadmap_path/config_path reflect the workstream layout. Regression test: stateJson with --ws workstream reads STATE.md from .planning/workstreams/<name>/ when workstream is provided. Closes #2618 (gap 1) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(#2618): sync root .planning/STATE.md mirror on workstream.set Gap 2 of #2618: setActiveWorkstream only flips the active-workstream pointer file; the root .planning/STATE.md mirror stays stale. Downstream consumers (statusline, gsd-sdk query progress, any tool that reads the root STATE.md) continue to see the previous workstream's state. After setActiveWorkstream(), copy .planning/workstreams/<name>/STATE.md verbatim to .planning/STATE.md via writeFileSync. The workstream STATE.md is authoritative; the root file is a pass-through mirror. Missing source STATE.md is a no-op rather than an error — a freshly created workstream with no STATE.md yet should still activate cleanly. The response now includes `mirror_synced: boolean` so callers can observe whether the root mirror was updated. Regression test: workstreamSet root STATE.md mirror sync — switches from a stale root mirror to a workstream STATE.md with different frontmatter and asserts the root file now matches. Closes #2618 (gap 2) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@gsd-build/sdk
TypeScript SDK for Get Shit Done: deterministic query/mutation handlers, plan execution, and event-stream telemetry so agents focus on judgment, not shell plumbing.
Install
npm install @gsd-build/sdk
Quickstart — programmatic
import { GSD, createRegistry } from '@gsd-build/sdk';
const gsd = new GSD({ projectDir: process.cwd(), sessionId: 'my-run' });
const tools = gsd.createTools();
const registry = createRegistry(gsd.eventStream, 'my-run');
const { data } = await registry.dispatch('state.json', [], process.cwd());
Quickstart — CLI
From a project that depends on this package, invoke the CLI with Node (recommended in CI and local dev):
node ./node_modules/@gsd-build/sdk/dist/cli.js query state.json
node ./node_modules/@gsd-build/sdk/dist/cli.js query roadmap.analyze
If no native handler is registered for a command, the CLI can transparently shell out to get-shit-done/bin/gsd-tools.cjs (see stderr warning), unless GSD_QUERY_FALLBACK=off.
What ships
| Area | Entry |
|---|---|
| Query registry | createRegistry() in src/query/index.ts — same handlers as gsd-sdk query |
| Tools bridge | GSDTools — native dispatch with optional CJS subprocess fallback |
| Orchestrators | PhaseRunner, InitRunner, GSD |
| CLI | gsd-sdk — query, run, init, auto |
Guides
- Handler registry & contracts:
src/query/QUERY-HANDLERS.md - Repository docs (when present):
docs/ARCHITECTURE.md,docs/CLI-TOOLS.mdat repo root
Environment
| Variable | Purpose |
|---|---|
GSD_QUERY_FALLBACK |
off / never disables CLI fallback to gsd-tools.cjs for unknown commands |
GSD_AGENTS_DIR |
Override directory scanned for installed GSD agents (~/.claude/agents by default) |