gsd-pi 2.78.0 → 2.78.1-dev.8a893322c

package/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd-build/mcp-server",
-  "version": "2.78.0",
+  "version": "2.78.1",
   "description": "MCP server exposing GSD orchestration tools for Claude Code, Cursor, and other MCP clients",
   "license": "MIT",
   "gsd": {
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@gsd-build/rpc-client": "^2.78.0",
+    "@gsd-build/rpc-client": "^2.78.1",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/packages/mcp-server/src/alias-telemetry.test.ts

@@ -0,0 +1,78 @@
+// @gsd-build/mcp-server + alias-telemetry.test — coverage for #5031.
+// `logAliasUsage` must:
+//   - emit one valid JSON line per call to stderr with the documented shape
+//   - never throw, even if stderr.write fails (telemetry must not break MCP)
+//   - include the alias name and canonical name so downstream analysis can
+//     attribute usage and drive the eventual removal in step 2.
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+
+import { ALIAS_USAGE_EVENT, logAliasUsage } from "./alias-telemetry.js";
+
+describe("logAliasUsage", () => {
+	let captured: string[];
+	let originalWrite: typeof process.stderr.write;
+
+	beforeEach(() => {
+		captured = [];
+		originalWrite = process.stderr.write.bind(process.stderr);
+		process.stderr.write = ((chunk: string | Uint8Array): boolean => {
+			captured.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString());
+			return true;
+		}) as typeof process.stderr.write;
+	});
+
+	afterEach(() => {
+		process.stderr.write = originalWrite;
+	});
+
+	test("emits a single JSON line per call", () => {
+		logAliasUsage("gsd_save_decision", "gsd_decision_save");
+		assert.equal(captured.length, 1);
+		assert.ok(captured[0].endsWith("\n"), "line must terminate with newline");
+	});
+
+	test("emitted JSON has the documented shape", () => {
+		logAliasUsage("gsd_save_decision", "gsd_decision_save");
+		const parsed = JSON.parse(captured[0].trimEnd());
+		assert.equal(parsed.event, ALIAS_USAGE_EVENT);
+		assert.equal(parsed.alias, "gsd_save_decision");
+		assert.equal(parsed.canonical, "gsd_decision_save");
+		assert.equal(typeof parsed.ts, "number");
+	});
+
+	test("event field is namespaced under 'deprecation.' for grep-friendly filtering", () => {
+		logAliasUsage("gsd_save_decision", "gsd_decision_save");
+		const parsed = JSON.parse(captured[0].trimEnd());
+		assert.ok(
+			(parsed.event as string).startsWith("deprecation."),
+			`event '${parsed.event}' should be namespaced for 'grep deprecation' workflow`,
+		);
+	});
+
+	test("ts field is a recent timestamp (within ~5s of Date.now())", () => {
+		const before = Date.now();
+		logAliasUsage("gsd_x", "gsd_y");
+		const after = Date.now();
+		const parsed = JSON.parse(captured[0].trimEnd());
+		assert.ok(parsed.ts >= before && parsed.ts <= after, `ts ${parsed.ts} should be in [${before}, ${after}]`);
+	});
+
+	test("multiple calls emit multiple lines", () => {
+		logAliasUsage("a", "A");
+		logAliasUsage("b", "B");
+		logAliasUsage("c", "C");
+		assert.equal(captured.length, 3);
+		const aliases = captured.map((l) => JSON.parse(l.trimEnd()).alias);
+		assert.deepEqual(aliases, ["a", "b", "c"]);
+	});
+
+	test("never throws — telemetry must not break the MCP request handler", () => {
+		// Force a write failure to exercise the swallow path.
+		process.stderr.write = (() => {
+			throw new Error("simulated stderr failure");
+		}) as typeof process.stderr.write;
+		assert.doesNotThrow(() => logAliasUsage("x", "y"));
+	});
+});

package/packages/mcp-server/src/alias-telemetry.ts

@@ -0,0 +1,30 @@
+// @gsd-build/mcp-server + alias-telemetry — usage telemetry on the 11 alias
+// `gsd_*` tools. Step 1 of a two-step deprecation (#5031). Always-on so we
+// actually capture data during the window. Single JSON line per invocation
+// to stderr — negligible overhead vs. the MCP request handler itself.
+//
+// Capture pattern: `<mcp-server-launch> 2>> alias-usage.jsonl`. After a
+// long-enough window with zero entries, the alias tools can be removed in
+// a follow-up PR. Filter with `grep deprecation` — the `event` field is
+// namespaced for that purpose.
+
+/** JSONL `event` field. Namespaced for `grep deprecation`. */
+export const ALIAS_USAGE_EVENT = "deprecation.mcp_alias_used" as const;
+
+/**
+ * Emit a single-line JSONL record signaling that an alias tool was invoked.
+ * Failures are swallowed — telemetry must never break MCP request handling.
+ */
+export function logAliasUsage(alias: string, canonical: string): void {
+	try {
+		const record = {
+			event: ALIAS_USAGE_EVENT,
+			ts: Date.now(),
+			alias,
+			canonical,
+		};
+		process.stderr.write(`${JSON.stringify(record)}\n`);
+	} catch {
+		// swallow — telemetry must never break the request handler
+	}
+}

package/packages/mcp-server/src/workflow-tools.test.ts

@@ -889,6 +889,32 @@ export const executeTaskComplete = async (params, projectDir) => {
     }
   });
 
+  it("gsd_milestone_generate_id skips DB-only queued milestone rows", async () => {
+    const base = makeTmpBase();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const tool = server.tools.find((t) => t.name === "gsd_milestone_generate_id");
+      assert.ok(tool, "milestone ID tool should be registered");
+
+      const first = await tool!.handler({ projectDir: base });
+      assert.equal((first as any).content[0].text, "M001");
+      assert.ok(!existsSync(join(base, ".gsd", "milestones", "M001")), "ID generation should not create a milestone dir");
+
+      closeDatabase();
+
+      const second = await tool!.handler({ projectDir: base });
+      assert.equal((second as any).content[0].text, "M002");
+
+      const rows = _getAdapter()!
+        .prepare("SELECT id FROM milestones ORDER BY id")
+        .all() as Array<Record<string, unknown>>;
+      assert.deepEqual(rows.map((row) => row["id"]), ["M001", "M002"]);
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("gsd_plan_task reopens the DB before inline task planning writes", async () => {
     const base = makeTmpBase();
     try {
@@ -1659,6 +1685,58 @@ describe("validateProjectDir", () => {
     }
   });
 
+  it("accepts a worktree under the allowed root external .gsd state target", () => {
+    const allowedRoot = makeTmpBase();
+    const externalState = makeTmpBase();
+    const worktree = join(externalState, "worktrees", "M001");
+    mkdirSync(worktree, { recursive: true });
+    rmSync(join(allowedRoot, ".gsd"), { recursive: true, force: true });
+    symlinkSync(externalState, join(allowedRoot, ".gsd"), "dir");
+
+    const prevRoot = process.env.GSD_WORKFLOW_PROJECT_ROOT;
+    try {
+      process.env.GSD_WORKFLOW_PROJECT_ROOT = allowedRoot;
+      const result = validateProjectDir(worktree);
+      assert.equal(result, realpathSync(worktree));
+    } finally {
+      if (prevRoot === undefined) {
+        delete process.env.GSD_WORKFLOW_PROJECT_ROOT;
+      } else {
+        process.env.GSD_WORKFLOW_PROJECT_ROOT = prevRoot;
+      }
+      cleanup(allowedRoot);
+      cleanup(externalState);
+    }
+  });
+
+  it("rejects external-state sibling paths that only share a prefix", () => {
+    const allowedRoot = makeTmpBase();
+    const externalState = makeTmpBase();
+    const sibling = `${externalState}-sibling`;
+    const siblingWorktree = join(sibling, "worktrees", "M001");
+    mkdirSync(siblingWorktree, { recursive: true });
+    rmSync(join(allowedRoot, ".gsd"), { recursive: true, force: true });
+    symlinkSync(externalState, join(allowedRoot, ".gsd"), "dir");
+
+    const prevRoot = process.env.GSD_WORKFLOW_PROJECT_ROOT;
+    try {
+      process.env.GSD_WORKFLOW_PROJECT_ROOT = allowedRoot;
+      assert.throws(
+        () => validateProjectDir(siblingWorktree),
+        /configured workflow project root/,
+      );
+    } finally {
+      if (prevRoot === undefined) {
+        delete process.env.GSD_WORKFLOW_PROJECT_ROOT;
+      } else {
+        process.env.GSD_WORKFLOW_PROJECT_ROOT = prevRoot;
+      }
+      cleanup(allowedRoot);
+      cleanup(externalState);
+      cleanup(sibling);
+    }
+  });
+
   it("rejects relative paths", () => {
     assert.throws(
       () => validateProjectDir("relative/path"),

package/packages/mcp-server/src/workflow-tools.ts

@@ -7,6 +7,8 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
 
+import { logAliasUsage } from "./alias-telemetry.js";
+
 type WorkflowToolExecutors = {
   SUPPORTED_SUMMARY_ARTIFACT_TYPES: readonly string[];
   executeMilestoneStatus: (params: { milestoneId: string }, basePath?: string) => Promise<unknown>;
@@ -847,6 +849,80 @@ async function ensureMilestoneDbRow(milestoneId: string): Promise<void> {
   }
 }
 
+async function findDatabaseMilestoneIds(): Promise<string[]> {
+  try {
+    const { getAllMilestones } = await importLocalModule<any>("../../../src/resources/extensions/gsd/gsd-db.js");
+    return (getAllMilestones?.() ?? [])
+      .map((milestone: unknown) => {
+        const id = (milestone as { id?: unknown })?.id;
+        return typeof id === "string" ? id : null;
+      })
+      .filter((id: string | null): id is string => id !== null);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Fix #4996: Shared helper for both gsd_milestone_generate_id and
+ * gsd_generate_milestone_id. Reuses the lowest reusable ghost milestone ID
+ * (a disk-only stub with no DB row, no worktree, no content files) before
+ * falling back to max+1. Uses the stricter `isReusableGhostMilestone` —
+ * not `isGhostMilestone` — to avoid racing with in-flight queued DB rows
+ * from an earlier call to this same tool.
+ */
+async function generateOrReuseMilestoneId(projectDir: string): Promise<string> {
+  const {
+    claimReservedId,
+    findMilestoneIds,
+    getReservedMilestoneIds,
+    nextMilestoneId,
+    milestoneIdSort,
+  } = await importLocalModule<any>("../../../src/resources/extensions/gsd/milestone-ids.js");
+
+  const reserved = claimReservedId();
+  if (reserved) {
+    await ensureMilestoneDbRow(reserved);
+    return reserved;
+  }
+
+  const allIds = [
+    ...new Set([
+      ...findMilestoneIds(projectDir),
+      ...getReservedMilestoneIds(),
+      ...(await findDatabaseMilestoneIds()),
+    ]),
+  ];
+
+  // Attempt ghost-ID reuse before falling back to max+1.
+  const { isReusableGhostMilestone } = await importLocalModule<any>(
+    "../../../src/resources/extensions/gsd/state.js",
+  );
+  const sorted = [...allIds].sort(milestoneIdSort);
+  for (const candidate of sorted) {
+    if (isReusableGhostMilestone(projectDir, candidate)) {
+      await ensureMilestoneDbRow(candidate);
+      return candidate;
+    }
+  }
+
+  const prefsMod = await importLocalModule<any>(
+    "../../../src/resources/extensions/gsd/preferences.js",
+  ).catch(() => null);
+  // Graceful degradation: a corrupt preferences file should not crash
+  // milestone-id generation. Fall back to non-unique IDs if anything
+  // throws here — matches the pre-fix behavior for missing prefs.
+  let uniqueEnabled = false;
+  try {
+    uniqueEnabled = !!prefsMod?.loadEffectiveGSDPreferences?.(projectDir)?.preferences?.unique_milestone_ids;
+  } catch {
+    uniqueEnabled = false;
+  }
+  const nextId = nextMilestoneId(allIds, uniqueEnabled);
+  await ensureMilestoneDbRow(nextId);
+  return nextId;
+}
+
 // projectDir is optional. When omitted, the server uses process.cwd(). This
 // prevents the agent from burning tokens reasoning about which absolute path
 // to pass (git root vs worktree vs symlink-resolved external state layout) —
@@ -1266,6 +1342,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_decision_save. Record a project decision to the GSD database and regenerate DECISIONS.md.",
     decisionSaveParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_save_decision", "gsd_decision_save");
       const parsed = parseWorkflowArgs(decisionSaveSchema, args);
       const { projectDir, ...params } = parsed;
       await enforceWorkflowWriteGate("gsd_decision_save", projectDir);
@@ -1298,6 +1375,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_requirement_update. Update an existing requirement in the GSD database and regenerate REQUIREMENTS.md.",
     requirementUpdateParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_update_requirement", "gsd_requirement_update");
       const parsed = parseWorkflowArgs(requirementUpdateSchema, args);
       const { projectDir, id, ...updates } = parsed;
       await enforceWorkflowWriteGate("gsd_requirement_update", projectDir);
@@ -1330,6 +1408,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_requirement_save. Record a new requirement to the GSD database and regenerate REQUIREMENTS.md.",
     requirementSaveParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_save_requirement", "gsd_requirement_save");
       const parsed = parseWorkflowArgs(requirementSaveSchema, args);
       const { projectDir, ...params } = parsed;
       await enforceWorkflowWriteGate("gsd_requirement_save", projectDir);
@@ -1348,35 +1427,9 @@ export function registerWorkflowTools(server: McpToolServer): void {
     async (args: Record<string, unknown>) => {
       const { projectDir } = parseWorkflowArgs(milestoneGenerateIdSchema, args);
       await enforceWorkflowWriteGate("gsd_milestone_generate_id", projectDir);
-      const id = await runSerializedWorkflowDbOperation(projectDir, async () => {
-        const {
-          claimReservedId,
-          findMilestoneIds,
-          getReservedMilestoneIds,
-          nextMilestoneId,
-        } = await importLocalModule<any>("../../../src/resources/extensions/gsd/milestone-ids.js");
-        const reserved = claimReservedId();
-        if (reserved) {
-          await ensureMilestoneDbRow(reserved);
-          return reserved;
-        }
-        const allIds = [...new Set([...findMilestoneIds(projectDir), ...getReservedMilestoneIds()])];
-        const prefsMod = await importLocalModule<any>(
-          "../../../src/resources/extensions/gsd/preferences.js",
-        ).catch(() => null);
-        // Graceful degradation: a corrupt preferences file should not crash
-        // milestone-id generation. Fall back to non-unique IDs if anything
-        // throws here — matches the pre-fix behavior for missing prefs.
-        let uniqueEnabled = false;
-        try {
-          uniqueEnabled = !!prefsMod?.loadEffectiveGSDPreferences?.()?.preferences?.unique_milestone_ids;
-        } catch {
-          uniqueEnabled = false;
-        }
-        const nextId = nextMilestoneId(allIds, uniqueEnabled);
-        await ensureMilestoneDbRow(nextId);
-        return nextId;
-      });
+      const id = await runSerializedWorkflowDbOperation(projectDir, () =>
+        generateOrReuseMilestoneId(projectDir),
+      );
       return { content: [{ type: "text" as const, text: id }] };
     },
   );
@@ -1386,37 +1439,12 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_milestone_generate_id. Generate the next milestone ID for a new GSD milestone.",
     milestoneGenerateIdParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_generate_milestone_id", "gsd_milestone_generate_id");
       const { projectDir } = parseWorkflowArgs(milestoneGenerateIdSchema, args);
       await enforceWorkflowWriteGate("gsd_milestone_generate_id", projectDir);
-      const id = await runSerializedWorkflowDbOperation(projectDir, async () => {
-        const {
-          claimReservedId,
-          findMilestoneIds,
-          getReservedMilestoneIds,
-          nextMilestoneId,
-        } = await importLocalModule<any>("../../../src/resources/extensions/gsd/milestone-ids.js");
-        const reserved = claimReservedId();
-        if (reserved) {
-          await ensureMilestoneDbRow(reserved);
-          return reserved;
-        }
-        const allIds = [...new Set([...findMilestoneIds(projectDir), ...getReservedMilestoneIds()])];
-        const prefsMod = await importLocalModule<any>(
-          "../../../src/resources/extensions/gsd/preferences.js",
-        ).catch(() => null);
-        // Graceful degradation: a corrupt preferences file should not crash
-        // milestone-id generation. Fall back to non-unique IDs if anything
-        // throws here — matches the pre-fix behavior for missing prefs.
-        let uniqueEnabled = false;
-        try {
-          uniqueEnabled = !!prefsMod?.loadEffectiveGSDPreferences?.()?.preferences?.unique_milestone_ids;
-        } catch {
-          uniqueEnabled = false;
-        }
-        const nextId = nextMilestoneId(allIds, uniqueEnabled);
-        await ensureMilestoneDbRow(nextId);
-        return nextId;
-      });
+      const id = await runSerializedWorkflowDbOperation(projectDir, () =>
+        generateOrReuseMilestoneId(projectDir),
+      );
       return { content: [{ type: "text" as const, text: id }] };
     },
   );
@@ -1477,6 +1505,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_plan_task. Write task planning state to the GSD database and render tasks/T##-PLAN.md from DB.",
     planTaskParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_task_plan", "gsd_plan_task");
       const parsed = parseWorkflowArgs(planTaskSchema, args);
       const { projectDir, ...params } = parsed;
       await enforceWorkflowWriteGate("gsd_plan_task", projectDir, params.milestoneId);
@@ -1508,6 +1537,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_replan_slice. Replan a slice after a blocker is discovered.",
     replanSliceParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_slice_replan", "gsd_replan_slice");
       const parsed = parseWorkflowArgs(replanSliceSchema, args);
       return handleReplanSlice(parsed.projectDir, parsed);
     },
@@ -1528,6 +1558,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_slice_complete. Record a completed slice to the GSD database and render summary/UAT artifacts.",
     sliceCompleteParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_complete_slice", "gsd_slice_complete");
       const parsed = parseWorkflowArgs(sliceCompleteSchema, args);
       return handleSliceComplete(parsed.projectDir, parsed);
     },
@@ -1578,6 +1609,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_complete_milestone. Record a completed milestone to the GSD database and render its SUMMARY.md.",
     completeMilestoneParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_milestone_complete", "gsd_complete_milestone");
       const parsed = parseWorkflowArgs(completeMilestoneSchema, args);
       return handleCompleteMilestone(parsed.projectDir, parsed);
     },
@@ -1598,6 +1630,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_validate_milestone. Validate a milestone and render VALIDATION.md.",
     validateMilestoneParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_milestone_validate", "gsd_validate_milestone");
       const parsed = parseWorkflowArgs(validateMilestoneSchema, args);
       return handleValidateMilestone(parsed.projectDir, parsed);
     },
@@ -1618,6 +1651,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_reassess_roadmap. Reassess a roadmap after slice completion.",
     reassessRoadmapParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_roadmap_reassess", "gsd_reassess_roadmap");
       const parsed = parseWorkflowArgs(reassessRoadmapSchema, args);
       return handleReassessRoadmap(parsed.projectDir, parsed);
     },
@@ -1672,6 +1706,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_task_complete. Record a completed task to the GSD database and render its SUMMARY.md.",
     taskCompleteParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_complete_task", "gsd_task_complete");
       const parsed = parseWorkflowArgs(taskCompleteSchema, args);
       const { projectDir, ...taskArgs } = parsed;
       return handleTaskComplete(projectDir, taskArgs);