dde56a1b77
* feat: add requireFreshDist helper for gen-*.mjs scripts Adds sdk/scripts/_gen-helpers.mjs exporting requireFreshDist(distPath, tsSourcePath). Performs a synchronous mtime check before any generator reads sdk/dist/ — if the dist file is missing or older than its TS source, exits 1 with a clear actionable error naming both paths, both mtimes, and the npm run build:sdk hint. Single source of truth so all 9 generators import one function rather than duplicating the logic. See issue #168. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: enforce dist freshness in all 9 gen-*.mjs generators Each generator now calls requireFreshDist() before reading sdk/dist/. If the dist artifact is missing or stale relative to its TS source, the generator exits 1 with a clear error instead of silently emitting stale CJS output. Addresses the PR #154 incident where an agent edited a TS source, regenerated the CJS without rebuilding, and silently overwrote a fix. gen-configuration.mjs also had its existing throw-on-missing guard replaced with requireFreshDist() which additionally catches staleness. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test: add staleness-check regression for gen-*.mjs tests/gen-staleness-check.test.cjs covers three cases for all 9 generators: - exits 1 with "does not exist" + build hint when dist file is absent - exits 1 with stale-dist error (paths + mtimes) when TS source is newer than dist - exits 0 when dist is newer than TS source (skipped if sdk/dist not built) Uses child_process.spawnSync to exercise the real gen-*.mjs entry path. 27/27 passing locally with sdk/dist present. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(gen-staleness-check): isolate dist-mutation tests with GSD_REPO_ROOT temp dirs Subtests A and B in gen-staleness-check.test.cjs were renaming/creating real sdk/dist files in the live repo tree while the suite ran at --test-concurrency=4. Other parallel test processes (e.g. frontmatter-cli.test.cjs) spawned subprocesses that attempted dynamic ESM import of sdk/dist/query/schema-detect.js while it was temporarily absent, producing unhandled ENOENT failures unrelated to the staleness guard logic under test. Fix: add a GSD_REPO_ROOT env override to _gen-helpers.mjs so requireFreshDist() resolves dist/ts paths against the provided root instead of the repo root derived from import.meta.url. The test creates an isolated tmpdir tree per subtest (with the real TS source copied in) and passes GSD_REPO_ROOT=<tmpdir> to the generator subprocess, so no real dist files are ever touched during subtests A or B. Subtest C (exits 0 on fresh dist) still uses the real repo tree because it needs actual compiled output to exercise the generator end-to-end, but only sets the TS source mtime (safe under concurrency) — it does not remove or rename any dist file. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@opengsd/gsd-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 @opengsd/gsd-sdk
Quickstart — programmatic
import { GSD, createRegistry } from '@opengsd/gsd-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/@opengsd/gsd-sdk/dist/cli.js query state.json
node ./node_modules/@opengsd/gsd-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) |