gsd-pi 2.77.0 → 2.78.0-dev.aeeb2ca00

package/packages/mcp-server/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@gsd-build/mcp-server",
-  "version": "2.77.0",
+  "version": "2.78.0",
   "description": "MCP server exposing GSD orchestration tools for Claude Code, Cursor, and other MCP clients",
   "license": "MIT",
+  "gsd": {
+    "linkable": true,
+    "scope": "@gsd-build",
+    "name": "mcp-server"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/gsd-build/gsd-2.git",
@@ -30,7 +35,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@gsd-build/rpc-client": "^2.77.0",
+    "@gsd-build/rpc-client": "^2.78.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/packages/mcp-server/src/env-writer.test.ts

@@ -3,7 +3,7 @@
 
 import { describe, it, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, realpathSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -14,6 +14,7 @@ import {
   applySecrets,
   isSafeEnvVarKey,
   isSupportedDeploymentEnvironment,
+  resolveProjectEnvFilePath,
   shellEscapeSingle,
 } from './env-writer.js';
 
@@ -181,6 +182,83 @@ describe('writeEnvKey', () => {
       rmSync(tmp, { recursive: true, force: true });
     }
   });
+
+  it('does not follow symlinked env files when writing', async () => {
+    const tmp = makeTempDir('write');
+    const outside = makeTempDir('write-outside');
+    try {
+      const outsideEnv = join(outside, '.env');
+      writeFileSync(outsideEnv, 'SECRET=outside\n');
+      symlinkSync(outsideEnv, join(tmp, '.env'));
+
+      await assert.rejects(
+        () => writeEnvKey(join(tmp, '.env'), 'SECRET', 'inside'),
+        /ELOOP|symbolic link|symlink/i,
+      );
+      assert.equal(readFileSync(outsideEnv, 'utf8'), 'SECRET=outside\n');
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveProjectEnvFilePath
+// ---------------------------------------------------------------------------
+
+describe('resolveProjectEnvFilePath', () => {
+  it('allows .env under the project root', () => {
+    const tmp = makeTempDir('env-path');
+    try {
+      assert.equal(resolveProjectEnvFilePath(tmp, '.env'), join(realpathSync.native(tmp), '.env'));
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects envFilePath outside the project root', () => {
+    const tmp = makeTempDir('env-path');
+    try {
+      assert.throws(
+        () => resolveProjectEnvFilePath(tmp, '../outside.env'),
+        /inside the project directory/,
+      );
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects symlinked parent directories that escape the project root', () => {
+    const tmp = makeTempDir('env-path');
+    const outside = makeTempDir('env-path-outside');
+    try {
+      symlinkSync(outside, join(tmp, 'linked-outside'), 'dir');
+      assert.throws(
+        () => resolveProjectEnvFilePath(tmp, 'linked-outside/.env'),
+        /inside the project directory/,
+      );
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects existing env files that are symlinks outside the project root', () => {
+    const tmp = makeTempDir('env-path');
+    const outside = makeTempDir('env-path-outside');
+    try {
+      writeFileSync(join(outside, '.env'), 'SECRET=outside\n');
+      symlinkSync(join(outside, '.env'), join(tmp, '.env'));
+      assert.throws(
+        () => resolveProjectEnvFilePath(tmp, '.env'),
+        /inside the project directory/,
+      );
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------

package/packages/mcp-server/src/env-writer.ts

@@ -5,9 +5,9 @@
 // destinations, and checking existing keys. Used by secure_env_collect
 // MCP tool. No TUI dependencies — pure filesystem + process.env operations.
 
-import { readFile, writeFile } from "node:fs/promises";
-import { existsSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { open, readFile, rename, rm } from "node:fs/promises";
+import { constants, existsSync, lstatSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 // ---------------------------------------------------------------------------
 // checkExistingEnvKeys
@@ -71,10 +71,19 @@ export async function writeEnvKey(filePath: string, key: string, value: string):
   if (typeof value !== "string") {
     throw new TypeError(`writeEnvKey expects a string value for key "${key}", got ${typeof value}`);
   }
+  assertWritableEnvFileTarget(filePath);
   let content = "";
   try {
-    content = await readFile(filePath, "utf8");
-  } catch {
+    const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      content = await handle.readFile("utf8");
+    } finally {
+      await handle.close();
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw err;
+    }
     content = "";
   }
   const escaped = value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/\r/g, "");
@@ -86,7 +95,42 @@ export async function writeEnvKey(filePath: string, key: string, value: string):
     if (content.length > 0 && !content.endsWith("\n")) content += "\n";
     content += `${line}\n`;
   }
-  await writeFile(filePath, content, "utf8");
+  const tempPath = join(
+    dirname(filePath),
+    `.${basename(filePath)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`,
+  );
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    handle = await open(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    await handle.writeFile(content, "utf8");
+    await handle.close();
+    handle = undefined;
+    assertWritableEnvFileTarget(filePath);
+    await rename(tempPath, filePath);
+  } catch (err) {
+    if (handle) {
+      try {
+        await handle.close();
+      } catch {
+        // Best-effort cleanup.
+      }
+    }
+    await rm(tempPath, { force: true }).catch(() => undefined);
+    throw err;
+  }
+}
+
+function assertWritableEnvFileTarget(filePath: string): void {
+  try {
+    if (lstatSync(filePath).isSymbolicLink()) {
+      throw new Error("Refusing to write symlinked env file");
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw err;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -101,6 +145,32 @@ export function isSupportedDeploymentEnvironment(env: string): boolean {
   return env === "development" || env === "preview" || env === "production";
 }
 
+function isWithinProjectRoot(projectRoot: string, candidatePath: string): boolean {
+  const rel = relative(projectRoot, candidatePath);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+export function resolveProjectEnvFilePath(projectDir: string, envFilePath = ".env"): string {
+  const projectRoot = realpathSync.native(resolve(projectDir));
+  const candidate = resolve(projectRoot, envFilePath);
+  if (!isWithinProjectRoot(projectRoot, candidate)) {
+    throw new Error("envFilePath must resolve inside the project directory");
+  }
+  if (existsSync(candidate)) {
+    const targetRealPath = realpathSync.native(candidate);
+    if (isWithinProjectRoot(projectRoot, targetRealPath)) {
+      return candidate;
+    }
+    throw new Error("envFilePath must resolve inside the project directory");
+  }
+  const candidateParent = dirname(candidate);
+  const parentRealPath = realpathSync.native(candidateParent);
+  if (isWithinProjectRoot(projectRoot, parentRealPath)) {
+    return candidate;
+  }
+  throw new Error("envFilePath must resolve inside the project directory");
+}
+
 // ---------------------------------------------------------------------------
 // Shell helpers (for vercel/convex CLI)
 // ---------------------------------------------------------------------------

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

@@ -808,8 +808,30 @@ describe('withElicitTimeout', () => {
   });
 
   it('clears the timer when the promise resolves (no dangling timer)', async () => {
-    const start = Date.now();
-    await withElicitTimeout(Promise.resolve('done'), 'test', 50);
-    assert.ok(Date.now() - start < 40, 'should not wait for the timeout');
+    // Spy on clearTimeout directly. `unhandledRejection` is not a reliable
+    // proxy: Node does not flag losing-promise rejections from a settled
+    // Promise.race as unhandled, so the absence of a stray rejection does
+    // not actually prove clearTimeout ran. Asserting the spy was invoked
+    // tests the cleanup contract directly.
+    const originalClearTimeout = globalThis.clearTimeout;
+    let clearCalls = 0;
+    let lastClearedId: unknown = undefined;
+    globalThis.clearTimeout = ((id: Parameters<typeof originalClearTimeout>[0]) => {
+      clearCalls++;
+      lastClearedId = id;
+      return originalClearTimeout(id);
+    }) as typeof clearTimeout;
+
+    try {
+      const value = await withElicitTimeout(Promise.resolve('done'), 'test', 50_000);
+      assert.equal(value, 'done');
+      assert.ok(
+        clearCalls >= 1,
+        `clearTimeout should run on resolve path; calls=${clearCalls}`,
+      );
+      assert.ok(lastClearedId !== undefined, 'clearTimeout should be called with the timer id');
+    } finally {
+      globalThis.clearTimeout = originalClearTimeout;
+    }
   });
 });

package/packages/mcp-server/src/readers/graph.test.ts

@@ -160,9 +160,28 @@ describe('buildGraph', () => {
     assert.ok(graph.nodes.length > 0, `Expected nodes, got ${graph.nodes.length}`);
   });
 
-  it('returns edgeCount >= 0 (valid graph structure)', async () => {
+  it('produces a non-empty set of edges for a project with artifacts', async () => {
+    // Previous `edgeCount >= 0` was a pure tautology. For a project
+    // with STATE/KNOWLEDGE/LEARNINGS/milestone artifacts, the graph
+    // builder wires relationships between the derived nodes — observed
+    // empirically to produce ≥ 3 edges for the standard fixture.
     const graph = await buildGraph(projectDir);
-    assert.ok(graph.edges.length >= 0);
+    assert.ok(
+      graph.edges.length > 0,
+      `expected edges for a project with artifacts. nodes=${graph.nodes.length}, edges=${graph.edges.length}`,
+    );
+    // Every edge must reference nodes that actually exist in the graph.
+    const nodeIds = new Set(graph.nodes.map((n) => n.id));
+    for (const edge of graph.edges) {
+      assert.ok(
+        nodeIds.has(edge.from),
+        `edge.from="${edge.from}" must reference an existing node`,
+      );
+      assert.ok(
+        nodeIds.has(edge.to),
+        `edge.to="${edge.to}" must reference an existing node`,
+      );
+    }
   });
 
   it('includes builtAt ISO timestamp', async () => {
@@ -175,16 +194,25 @@ describe('buildGraph', () => {
     const badProject = tmpProject();
     // Write a corrupt/minimal STATE.md that is technically valid but empty
     writeFixture(badProject, '.gsd/STATE.md', 'not valid gsd state at all \0\0\0');
-    // Should not throw
+    // Don't throw, and don't lose the well-formed builtAt timestamp
+    // (which previous `graph.nodes.length >= 0` tautology ignored).
     const graph = await buildGraph(badProject);
-    assert.ok(graph.nodes.length >= 0);
+    assert.ok(Array.isArray(graph.nodes), "nodes must be an array");
+    assert.ok(Array.isArray(graph.edges), "edges must be an array");
+    assert.ok(
+      !Number.isNaN(Date.parse(graph.builtAt)),
+      "builtAt must be a valid ISO-8601 timestamp even when artifact is unparseable",
+    );
     rmSync(badProject, { recursive: true, force: true });
   });
 
   it('returns empty graph for project with no .gsd/ directory', async () => {
     const emptyProject = tmpProject();
     const graph = await buildGraph(emptyProject);
-    assert.ok(graph.nodes.length >= 0); // no throw
+    // Previous `graph.nodes.length >= 0` was a tautology. The real
+    // contract for a .gsd-less project: truly empty graph.
+    assert.deepEqual(graph.nodes, [], "nodes must be empty for .gsd-less project");
+    assert.deepEqual(graph.edges, [], "edges must be empty for .gsd-less project");
     assert.equal(typeof graph.builtAt, 'string');
     rmSync(emptyProject, { recursive: true, force: true });
   });
@@ -286,10 +314,21 @@ describe('buildGraph — LEARNINGS.md parsing', () => {
     const badProject = tmpProject();
     mkdirSync(join(badProject, '.gsd', 'milestones', 'M002'), { recursive: true });
     writeLearningsFixture(badProject, 'M002', '\0\0\0 not valid yaml or markdown \0\0\0');
-    // Must not throw
+    // Must not throw AND must not produce garbage learning nodes from
+    // the binary contents (previous `nodes.length >= 0` tautology
+    // allowed either outcome).
     const graph = await buildGraph(badProject);
-    assert.ok(graph.nodes.length >= 0);
+    assert.ok(Array.isArray(graph.nodes));
     assert.equal(typeof graph.builtAt, 'string');
+    const m002LearningNodes = graph.nodes.filter(
+      (n) => n.id.includes('M002') && n.type !== 'milestone',
+    );
+    assert.equal(
+      m002LearningNodes.length,
+      0,
+      "malformed LEARNINGS.md must not produce any non-milestone nodes " +
+        `(got: ${JSON.stringify(m002LearningNodes.map((n) => n.id))})`,
+    );
     rmSync(badProject, { recursive: true, force: true });
   });
 
@@ -333,9 +372,20 @@ missing_artifacts: []
   it('does not crash when LEARNINGS.md is missing entirely', async () => {
     const noLearningsProject = tmpProject();
     mkdirSync(join(noLearningsProject, '.gsd', 'milestones', 'M004'), { recursive: true });
-    // No LEARNINGS.md file written
+    // No LEARNINGS.md file written. Previous tautology (nodes.length >= 0)
+    // passed regardless of whether the graph was structurally valid;
+    // assert real shape + no-learnings outcome.
     const graph = await buildGraph(noLearningsProject);
-    assert.ok(graph.nodes.length >= 0);
+    assert.ok(Array.isArray(graph.nodes));
+    assert.equal(typeof graph.builtAt, 'string');
+    const learningNodes = graph.nodes.filter(
+      (n) => n.type === 'decision' || n.type === 'lesson' || n.type === 'pattern' || n.type === 'surprise',
+    );
+    assert.equal(
+      learningNodes.length,
+      0,
+      `no LEARNINGS.md → no learning nodes (got: ${JSON.stringify(learningNodes.map((n) => n.id))})`,
+    );
     rmSync(noLearningsProject, { recursive: true, force: true });
   });
 });
@@ -485,9 +535,15 @@ describe('graphQuery', () => {
     );
   });
 
-  it('budget trims AMBIGUOUS edges first', async () => {
+  it('budget trims AMBIGUOUS edges first — keeps INFERRED edge when budget only forces one drop', async () => {
+    // Previous version only asserted the seed node remained — the test
+    // title claimed AMBIGUOUS was trimmed first but never checked.
+    // applyBudget (graph.ts:685) drops AMBIGUOUS edges first, then
+    // INFERRED, then hard-trims to seed-only. Budget here is in tokens
+    // (nodes × 20 + edges × 10). With 3 nodes (60) + 2 edges (20) = 80,
+    // a budget of 70 forces exactly the AMBIGUOUS-edge drop and stops
+    // (70 > 70 is false), leaving the INFERRED edge intact.
     const gsdRoot = join(projectDir, '.gsd');
-    // Write a graph with mixed confidence edges
     const mixedGraph: KnowledgeGraph = {
       builtAt: new Date().toISOString(),
       nodes: [
@@ -502,10 +558,26 @@ describe('graphQuery', () => {
     };
     await writeGraph(gsdRoot, mixedGraph);
 
-    // With a very small budget, AMBIGUOUS edges should be trimmed first
-    const result = await graphQuery(projectDir, 'seed node budget', 10);
-    // At minimum, the seed node itself should be present
-    assert.ok(result.nodes.some((n) => n.id === 'n1'), 'Seed node should be in result');
+    const result = await graphQuery(projectDir, 'seed node budget', 70);
+    assert.ok(result.nodes.some((n) => n.id === 'n1'), "seed must remain");
+
+    const hasAmbiguousEdge = result.edges.some(
+      (e) => e.from === 'n1' && e.to === 'n2' && e.confidence === 'AMBIGUOUS',
+    );
+    const hasInferredEdge = result.edges.some(
+      (e) => e.from === 'n1' && e.to === 'n3' && e.confidence === 'INFERRED',
+    );
+
+    assert.equal(
+      hasAmbiguousEdge,
+      false,
+      "AMBIGUOUS edge must be trimmed FIRST when budget is tight",
+    );
+    assert.equal(
+      hasInferredEdge,
+      true,
+      "INFERRED edge must survive when budget only forces the AMBIGUOUS drop",
+    );
 
     // Restore the original graph
     const originalGraph = await buildGraph(projectDir);

package/packages/mcp-server/src/readers/readers.test.ts

@@ -503,7 +503,11 @@ describe('runDoctorLite', () => {
     const empty = tmpProject();
     const result = runDoctorLite(empty);
     assert.equal(result.ok, true);
-    assert.equal(result.issues[0].code, 'no_gsd_directory');
+    assert.ok(
+      result.issues.some(
+        (issue) => issue.code === 'no_gsd_directory' || issue.code === 'missing_project_md',
+      ),
+    );
     rmSync(empty, { recursive: true, force: true });
   });
 });