@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/mcp-server.cjs

@@ -27,6 +27,9 @@
  * the additive, importable server surface a host (or the bin shim) drives.
  */
 'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SERVER_NAME = exports.PROTOCOL_VERSION = void 0;
 exports.handleMessage = handleMessage;
@@ -36,9 +39,62 @@ const stateIo = require("./state-io.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCommandProjection = require("./shell-command-projection.cjs");
 const { dispatchGsdCommand } = shellCommandProjection;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const mcp_catalog_cjs_1 = require("./mcp-catalog.cjs");
 exports.PROTOCOL_VERSION = '2024-11-05';
 exports.SERVER_NAME = 'gsd-core';
-const SERVER_VERSION = '1.7.0';
+// #3072: resolve SERVER_VERSION from package.json (source tree) or the
+// installed gsd-core/VERSION marker, WITHOUT a top-level `require(...)` —
+// mirrors the established, already-precedented resolver in
+// `runtime-artifact-conversion.cts`'s `gsdVersion()` (#1383): a top-level
+// require would throw on any runtime whose root has no package.json/VERSION,
+// and `scripts/sync-manifest-versions.cjs` is not a fit here — its
+// `VERSIONED_MANIFESTS` list stamps a `version` FIELD into hand-authored JSON
+// manifests (plugin.json, marketplace.json, vscode/package.json); a `.cts`
+// source constant is not a JSON document that script can round-trip through
+// `readJson`/`setByPath`, and teaching it to text-edit TypeScript source
+// would be a much larger footprint than this lazy, cached, defensive read.
+// Resolved once per process (never per-request) and cached; a failed lookup
+// degrades to '0.0.0' (never `undefined`, never a crash) rather than making
+// `initialize`'s `serverInfo.version` field absent or malformed.
+const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
+let cachedServerVersion;
+function resolveServerVersion() {
+    if (cachedServerVersion !== undefined)
+        return cachedServerVersion;
+    let version = '0.0.0';
+    try {
+        const v = node_fs_1.default.readFileSync(node_path_1.default.join(__dirname, '..', '..', 'VERSION'), 'utf8').trim();
+        if (SEMVER_PREFIX.test(v))
+            version = v;
+    }
+    catch {
+        /* not an installed tree (no gsd-core/VERSION) */
+    }
+    if (version === '0.0.0') {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy, defensive: a top-level require would throw on a runtime root with no package.json.
+            const pkg = require(node_path_1.default.join(__dirname, '..', '..', '..', 'package.json'));
+            if (pkg && typeof pkg.version === 'string' && SEMVER_PREFIX.test(pkg.version))
+                version = pkg.version;
+        }
+        catch {
+            /* runtime root has no package.json */
+        }
+    }
+    cachedServerVersion = version;
+    return version;
+}
+// Catalog is built once per process, lazily, and cached (design "Shape" /
+// Gall's Law — no watching, no invalidation; Known limits: the package is
+// immutable in every install mode we ship).
+let cachedCatalog;
+function getCatalog() {
+    if (cachedCatalog === undefined)
+        cachedCatalog = (0, mcp_catalog_cjs_1.buildCatalog)();
+    return cachedCatalog;
+}
 // JSON-RPC 2.0 error codes.
 const PARSE_ERROR = -32700;
 const INVALID_REQUEST = -32600;
@@ -93,6 +149,32 @@ function okResponse(id, result) {
 function asString(v) {
     return typeof v === 'string' ? v : null;
 }
+/** Extract the {@link REASON} carried by a `CatalogError`, if any (see `mcp-catalog.cts`). */
+function catalogErrorReason(err) {
+    const reason = err && typeof err === 'object' ? err.reason : undefined;
+    return typeof reason === 'string' ? reason : undefined;
+}
+function catalogErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Map a `mcp-catalog.cts` `CatalogError.reason` to a JSON-RPC error code.
+ * `READ_FAILED` is a server-side IO/compose failure (`INTERNAL_ERROR`);
+ * every other reason (unknown uri/prompt/cursor/root, malformed/traversal
+ * uri, wrong-typed param) is a client-supplied-value problem (`INVALID_PARAMS`)
+ * — deliberately never `METHOD_NOT_FOUND`, so a refusal is never
+ * indistinguishable from the method simply not existing (test-matrix rows
+ * 33/35).
+ */
+function catalogErrorCode(err) {
+    return catalogErrorReason(err) === mcp_catalog_cjs_1.REASON.READ_FAILED ? INTERNAL_ERROR : INVALID_PARAMS;
+}
+function wireResource(entry) {
+    return { uri: entry.uri, name: entry.name, title: entry.title, description: entry.description, mimeType: entry.mimeType };
+}
+function wirePrompt(entry) {
+    return { name: entry.name, title: entry.title, description: entry.description };
+}
 function callTool(name, args, ctx) {
     const a = (args && typeof args === 'object' ? args : {});
     const cwd = asString(ctx.cwd) || process.cwd();
@@ -148,8 +230,12 @@ function handleMessage(request, ctx = {}) {
         case 'initialize':
             result = {
                 protocolVersion: exports.PROTOCOL_VERSION,
-                capabilities: { tools: {} },
-                serverInfo: { name: exports.SERVER_NAME, version: SERVER_VERSION },
+                // #3072: resources/prompts declared alongside tools. Deliberately NO
+                // subscribe/listChanged — nothing ever sends those notifications
+                // (design row 2 / Hyrum's Law: advertising an unimplemented
+                // notification is a lie a host would act on).
+                capabilities: { tools: {}, resources: {}, prompts: {} },
+                serverInfo: { name: exports.SERVER_NAME, version: resolveServerVersion() },
             };
             break;
         case 'tools/list':
@@ -163,6 +249,52 @@ function handleMessage(request, ctx = {}) {
             result = callTool(toolName, params.arguments, ctx);
             break;
         }
+        case 'resources/list': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            try {
+                const cursor = typeof params.cursor === 'string' ? params.cursor : undefined;
+                const pageSize = typeof params.pageSize === 'number' ? params.pageSize : undefined;
+                const page = (0, mcp_catalog_cjs_1.listResources)(getCatalog(), { cursor, pageSize });
+                result = page.nextCursor === undefined
+                    ? { resources: page.resources.map(wireResource) }
+                    : { resources: page.resources.map(wireResource), nextCursor: page.nextCursor };
+            }
+            catch (e) {
+                return errorResponse(id, catalogErrorCode(e), catalogErrorMessage(e));
+            }
+            break;
+        }
+        case 'resources/read': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            try {
+                const read = (0, mcp_catalog_cjs_1.readResource)(getCatalog(), params.uri);
+                result = { contents: [{ uri: read.uri, mimeType: read.mimeType, text: read.text }] };
+            }
+            catch (e) {
+                return errorResponse(id, catalogErrorCode(e), catalogErrorMessage(e));
+            }
+            break;
+        }
+        case 'prompts/list':
+            result = {
+                prompts: [...getCatalog().prompts.values()]
+                    .map(wirePrompt)
+                    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+            };
+            break;
+        case 'prompts/get': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            const name = asString(params.name);
+            if (!name)
+                return errorResponse(id, INVALID_PARAMS, 'prompts/get requires string "name".');
+            try {
+                result = (0, mcp_catalog_cjs_1.getPrompt)(getCatalog(), name, params.arguments);
+            }
+            catch (e) {
+                return errorResponse(id, catalogErrorCode(e), catalogErrorMessage(e));
+            }
+            break;
+        }
         default:
             if (isNotification)
                 return null;

package/gsd-core/bin/lib/milestone-lock.cjs

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * Milestone Lock — advisory (phase, session) claim over the single Current
+ * Position slot in STATE.md (#3311).
+ *
+ * Problem it solves: two sessions running DIFFERENT phases in the same working
+ * tree both read-modify-write `## Current Position`. The byte-level STATE.md
+ * lock (#464) already serializes those writes, so no write is lost — but the
+ * SEMANTIC clobber is silent: `state.advance-plan` takes no phase argument and
+ * advances whatever plan the (possibly just clobbered) Current Position names,
+ * and nothing ever surfaces that two sessions claimed two different phases
+ * against the one single-slot field.
+ *
+ * This module is the maintainer-chosen fix (issue #3311 comment): a milestone
+ * lock keyed by phase + session id, with a second session WARNED instead of
+ * silently overwriting. It is an advisory claim file, not a mutex:
+ *
+ * - `.planning/milestone.lock` (workstream-scoped via planningDir) holds
+ *   `{ phase, session, pid, updated_at }`.
+ * - Session identity reuses `getWorkstreamSessionKey()`
+ *   (active-workstream-store.cjs): env-first (GSD_SESSION_KEY,
+ *   CLAUDE_SESSION_ID, CODEX_THREAD_ID, …), then the controlling TTY. Two
+ *   agent sessions in different terminals/runtimes resolve different keys;
+ *   headless runs resolve to null.
+ * - Liveness is age-based only: a claim is live while
+ *   `now - updated_at < MILESTONE_LOCK_TTL_MS`. There is deliberately NO
+ *   pid-liveness gate — CLI invocations are short-lived, so the recorded pid
+ *   is dead by the next invocation regardless of whether the agent SESSION is
+ *   still active; pid-death would make every claim instantly stale. Active
+ *   sessions heartbeat their claim (advance-plan on a matching position
+ *   refreshes updated_at); an abandoned claim self-expires after the TTL.
+ * - Conflict rule: a live claim for a DIFFERENT phase held by a DIFFERENT
+ *   session. Same phase never conflicts (the lock is keyed by phase — two
+ *   sessions on one phase are doing the same work). A non-null session key
+ *   equal to the caller's never conflicts (one orchestrating session may
+ *   re-target its own claim). A null session key never counts as "same" as
+ *   anything, so headless parallel phases are still detected. The one
+ *   exception is advance-plan (checkMilestonePosition), which reports ANY
+ *   live claim/position phase mismatch regardless of session — a session's
+ *   own legitimate re-targeting goes through begin-phase, which keeps the
+ *   claim in sync, so a same-session mismatch is just as anomalous.
+ * - On conflict the existing claim is LEFT INTACT (not stolen): as long as two
+ *   phases are concurrently active, every Current Position mutation keeps
+ *   reporting the conflict. The conflicting command still proceeds (warn, not
+ *   block — a stale-but-live claim must not brick later sessions).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MILESTONE_LOCK_TTL_MS = exports.MILESTONE_LOCK_FILENAME = void 0;
+exports.warnMilestoneConflict = warnMilestoneConflict;
+exports.claimMilestonePhase = claimMilestonePhase;
+exports.checkMilestonePosition = checkMilestonePosition;
+exports.checkMilestoneConflictForPhase = checkMilestoneConflictForPhase;
+exports.releaseMilestonePhase = releaseMilestonePhase;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const clock_cjs_1 = require("./clock.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
+const planningWorkspace = require("./planning-workspace.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- active-workstream-store.cjs is an export= CommonJS module
+const activeWorkstreamStore = require("./active-workstream-store.cjs");
+exports.MILESTONE_LOCK_FILENAME = 'milestone.lock';
+/**
+ * How long a claim stays live without a heartbeat. Active sessions heartbeat
+ * on every advance-plan against their claimed phase; a phase's planning stage
+ * (begin-phase → first completed plan) can legitimately run for hours, so the
+ * floor must comfortably exceed the longest expected gap between heartbeats
+ * while still expiring an abandoned claim within a working day.
+ */
+exports.MILESTONE_LOCK_TTL_MS = 4 * 60 * 60 * 1000;
+function milestoneLockPath(cwd) {
+    return node_path_1.default.join(planningWorkspace.planningDir(cwd), exports.MILESTONE_LOCK_FILENAME);
+}
+/**
+ * Normalize a phase token for claim comparison: trim, and collapse an integer
+ * spelling to its canonical form so "01", "1" and " 1 " compare equal while
+ * decimals ("2.5") compare by their trimmed text.
+ */
+function normalizePhaseToken(value) {
+    const trimmed = String(value).trim();
+    if (/^\d+$/.test(trimmed))
+        return String(parseInt(trimmed, 10));
+    return trimmed;
+}
+function sameSession(a, b) {
+    // A null key is "unknown", not "equal" — two headless sessions must still
+    // conflict across phases (the CI/cron shape of #3311).
+    if (a === null || b === null)
+        return false;
+    return a === b;
+}
+function parseClaim(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.phase !== 'string' || !parsed.phase.trim())
+            return null;
+        return {
+            phase: parsed.phase,
+            session: typeof parsed.session === 'string' ? parsed.session : null,
+            pid: typeof parsed.pid === 'number' ? parsed.pid : 0,
+            updated_at: typeof parsed.updated_at === 'number' ? parsed.updated_at : 0,
+        };
+    }
+    catch {
+        // Corrupt body (concurrent partial write, hand edit) — treat as no claim.
+        // The next writer replaces the file; never crash a state command over an
+        // advisory sidecar.
+        return null;
+    }
+}
+function readClaim(cwd) {
+    try {
+        return parseClaim(node_fs_1.default.readFileSync(milestoneLockPath(cwd), 'utf-8'));
+    }
+    catch {
+        return null; // absent or unreadable — same posture as parseClaim
+    }
+}
+function writeClaim(cwd, claim) {
+    ensureClaimDir(cwd);
+    node_fs_1.default.writeFileSync(milestoneLockPath(cwd), JSON.stringify(claim, null, 2) + '\n');
+}
+// planningWorkspace.planningDir targets .planning (or the workstream-scoped
+// variant); the parent is created by every GSD command that gets this far, but
+// the claim write must not throw if it is somehow missing.
+function ensureClaimDir(cwd) {
+    try {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(milestoneLockPath(cwd)), { recursive: true });
+    }
+    catch {
+        /* best-effort — see writeClaim callers' advisory posture */
+    }
+}
+function isClaimLive(claim, nowMs) {
+    return nowMs - claim.updated_at < exports.MILESTONE_LOCK_TTL_MS;
+}
+function currentSessionKey() {
+    return activeWorkstreamStore.getWorkstreamSessionKey();
+}
+function toConflict(claim, phase, session) {
+    return {
+        locked_phase: claim.phase,
+        locked_session: claim.session,
+        phase,
+        session,
+    };
+}
+/**
+ * Human-visible warning for a conflict. Emitted on stderr unconditionally —
+ * visibility is the entire point of this lock (#3311's "silent last-write-wins").
+ */
+function warnMilestoneConflict(conflict, action) {
+    const holder = conflict.locked_session ?? 'an unknown (headless) session';
+    const actor = conflict.session ?? 'an unknown (headless) session';
+    process.stderr.write(`[gsd-tools] WARNING: milestone lock conflict (#3311): ${holder} holds the milestone claim for phase ` +
+        `${conflict.locked_phase}, but ${actor} is running ${action} for phase ${conflict.phase}. ` +
+        `STATE.md's ## Current Position is a single slot — concurrent phases overwrite each other's ` +
+        `position. Verify Current Position before trusting it.\n`);
+}
+/**
+ * begin-phase entry point: claim `phase` for this session.
+ *
+ * Returns a conflict descriptor (and leaves the existing claim intact) when a
+ * live claim for a DIFFERENT phase is held by a DIFFERENT session; otherwise
+ * takes/refreshes the claim and returns null.
+ */
+function claimMilestonePhase(cwd, phase, nowMs) {
+    const now = nowMs ?? clock_cjs_1.realClock.now();
+    const session = currentSessionKey();
+    const existing = readClaim(cwd);
+    if (existing !== null &&
+        isClaimLive(existing, now) &&
+        normalizePhaseToken(existing.phase) !== normalizePhaseToken(phase) &&
+        !sameSession(existing.session, session)) {
+        return toConflict(existing, phase, session);
+    }
+    writeClaim(cwd, { phase: String(phase).trim(), session, pid: process.pid, updated_at: now });
+    return null;
+}
+/**
+ * advance-plan entry point: `positionPhase` is the phase STATE.md's Current
+ * Position currently names.
+ *
+ * A live claim naming a DIFFERENT phase means the position was moved away from
+ * the claimed phase without a matching begin-phase — the #3311 flip — and is
+ * returned as a conflict REGARDLESS of session: this session's own legitimate
+ * re-targeting goes through begin-phase, which keeps the claim in sync, so a
+ * same-session mismatch is exactly as anomalous as a cross-session one. A live
+ * claim matching the position phase is heartbeat-refreshed (this session is
+ * actively working that phase, so the claim stays live). No claim is ever
+ * created here: advance-plan has no phase argument of its own, so it can only
+ * corroborate or contradict an existing claim, not originate one.
+ */
+function checkMilestonePosition(cwd, positionPhase, nowMs) {
+    const now = nowMs ?? clock_cjs_1.realClock.now();
+    const existing = readClaim(cwd);
+    if (existing === null || !isClaimLive(existing, now))
+        return null;
+    const session = currentSessionKey();
+    if (normalizePhaseToken(existing.phase) === normalizePhaseToken(positionPhase)) {
+        // Heartbeat — keep the claim's liveness anchored to actual activity.
+        writeClaim(cwd, { phase: existing.phase, session: existing.session, pid: process.pid, updated_at: now });
+        return null;
+    }
+    return toConflict(existing, positionPhase, session);
+}
+/**
+ * phase.complete entry point (read-only check): a live claim for a DIFFERENT
+ * phase held by a DIFFERENT session is a conflict. phase.complete never claims
+ * — it ends work on a phase rather than starting it.
+ */
+function checkMilestoneConflictForPhase(cwd, phase, nowMs) {
+    const now = nowMs ?? clock_cjs_1.realClock.now();
+    const existing = readClaim(cwd);
+    if (existing === null || !isClaimLive(existing, now))
+        return null;
+    if (normalizePhaseToken(existing.phase) === normalizePhaseToken(phase))
+        return null;
+    const session = currentSessionKey();
+    if (!sameSession(existing.session, session)) {
+        return toConflict(existing, phase, session);
+    }
+    return null;
+}
+/**
+ * Release the claim when the phase it names completes — regardless of which
+ * session completes it (an orchestrator cleaning up after a dead session must
+ * not be blocked by the dead session's own claim). Returns whether a matching
+ * claim was removed.
+ */
+function releaseMilestonePhase(cwd, phase) {
+    const existing = readClaim(cwd);
+    if (existing === null)
+        return false;
+    if (normalizePhaseToken(existing.phase) !== normalizePhaseToken(phase))
+        return false;
+    try {
+        node_fs_1.default.unlinkSync(milestoneLockPath(cwd));
+        return true;
+    }
+    catch {
+        return false; // already gone — same outcome for the caller
+    }
+}