@frontmcp/testing 1.8.6 → 1.8.7

package/perf/index.js

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,14 +15,6 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // libs/testing/src/perf/index.ts
@@ -834,6 +824,192 @@ function getMeasurementsForProject(project) {
   return getGlobalMeasurementsArray().filter((m) => m.project === project);
 }
 
+// libs/testing/src/auth/token-factory.ts
+var import_jose = require("jose");
+var TestTokenFactory = class {
+  issuer;
+  audience;
+  privateKey = null;
+  publicKey = null;
+  jwk = null;
+  keyId;
+  /** HS256 shared secret (gateway mode). Null → RS256 + JWKS (default). */
+  hmacSecret;
+  constructor(options = {}) {
+    this.issuer = options.issuer ?? "https://test.frontmcp.local";
+    this.audience = options.audience ?? "frontmcp-test";
+    this.keyId = `test-key-${Date.now()}`;
+    this.hmacSecret = options.hmacSecret ? new TextEncoder().encode(options.hmacSecret) : null;
+  }
+  /** True when this factory signs HS256 with a shared secret (gateway mode). */
+  get isHmac() {
+    return this.hmacSecret !== null;
+  }
+  /** The JWS `alg` this factory signs with. */
+  get alg() {
+    return this.isHmac ? "HS256" : "RS256";
+  }
+  /**
+   * The signing key: the shared HMAC secret in gateway mode, otherwise the
+   * generated RSA private key (lazily created via ensureKeys()).
+   */
+  signingKey() {
+    if (this.hmacSecret) return this.hmacSecret;
+    if (!this.privateKey) {
+      throw new Error("Private key not initialized");
+    }
+    return this.privateKey;
+  }
+  /**
+   * Initialize the key pair (called automatically on first use). No-op in HS256
+   * mode — there is no asymmetric keypair, just the shared secret.
+   */
+  async ensureKeys() {
+    if (this.isHmac) return;
+    if (this.privateKey && this.publicKey) return;
+    const { publicKey, privateKey } = await (0, import_jose.generateKeyPair)("RS256", {
+      extractable: true
+    });
+    this.privateKey = privateKey;
+    this.publicKey = publicKey;
+    this.jwk = await (0, import_jose.exportJWK)(publicKey);
+    this.jwk.kid = this.keyId;
+    this.jwk.use = "sig";
+    this.jwk.alg = "RS256";
+  }
+  /**
+   * Create a JWT token with the specified claims
+   */
+  async createTestToken(options) {
+    await this.ensureKeys();
+    const nowMs = Date.now();
+    const iat = Math.floor(nowMs / 1e3);
+    const exp = options.exp ?? 3600;
+    const payload = {
+      iss: options.iss ?? this.issuer,
+      sub: options.sub,
+      aud: options.aud ?? this.audience,
+      iat,
+      exp: Math.ceil(nowMs / 1e3) + exp,
+      scope: options.scopes?.join(" "),
+      ...options.claims
+    };
+    const header = this.isHmac ? { alg: this.alg, typ: "JWT" } : { alg: this.alg, kid: this.keyId };
+    const token = await new import_jose.SignJWT(payload).setProtectedHeader(header).sign(this.signingKey());
+    return token;
+  }
+  /**
+   * Create an admin token with full access
+   */
+  async createAdminToken(sub = "admin-001") {
+    return this.createTestToken({
+      sub,
+      scopes: ["admin:*", "read", "write", "delete"],
+      claims: {
+        email: "admin@test.local",
+        name: "Test Admin",
+        role: "admin"
+      }
+    });
+  }
+  /**
+   * Create a regular user token
+   */
+  async createUserToken(sub = "user-001", scopes = ["read", "write"]) {
+    return this.createTestToken({
+      sub,
+      scopes,
+      claims: {
+        email: "user@test.local",
+        name: "Test User",
+        role: "user"
+      }
+    });
+  }
+  /**
+   * Create an anonymous user token
+   */
+  async createAnonymousToken(expiresIn) {
+    return this.createTestToken({
+      sub: `anon:${Date.now()}`,
+      scopes: ["anonymous"],
+      exp: expiresIn,
+      claims: {
+        name: "Anonymous",
+        role: "anonymous"
+      }
+    });
+  }
+  /**
+   * Create an expired token (for testing token expiration)
+   */
+  async createExpiredToken(options) {
+    await this.ensureKeys();
+    const now = Math.floor(Date.now() / 1e3);
+    const payload = {
+      iss: this.issuer,
+      sub: options.sub,
+      aud: this.audience,
+      iat: now - 7200,
+      // 2 hours ago
+      exp: now - 3600
+      // Expired 1 hour ago
+    };
+    const header = this.isHmac ? { alg: this.alg, typ: "JWT" } : { alg: this.alg, kid: this.keyId };
+    const token = await new import_jose.SignJWT(payload).setProtectedHeader(header).sign(this.signingKey());
+    return token;
+  }
+  /**
+   * Create a token with an invalid signature (for testing signature validation)
+   */
+  createTokenWithInvalidSignature(options) {
+    const now = Math.floor(Date.now() / 1e3);
+    const headerObj = this.isHmac ? { alg: this.alg, typ: "JWT" } : { alg: this.alg, kid: this.keyId };
+    const header = Buffer.from(JSON.stringify(headerObj)).toString("base64url");
+    const payload = Buffer.from(
+      JSON.stringify({
+        iss: this.issuer,
+        sub: options.sub,
+        aud: this.audience,
+        iat: now,
+        exp: now + 3600
+      })
+    ).toString("base64url");
+    const signature = Buffer.from("invalid-signature-" + Date.now()).toString("base64url");
+    return `${header}.${payload}.${signature}`;
+  }
+  /**
+   * Get the public JWKS for verifying tokens.
+   *
+   * Only meaningful in RS256 mode — HS256 (gateway) tokens are verified against
+   * the shared secret, not a published public key, so there is no JWKS to serve.
+   */
+  async getPublicJwks() {
+    if (this.isHmac) {
+      throw new Error("getPublicJwks() is not available in HS256 mode (gateway tokens use a shared secret)");
+    }
+    await this.ensureKeys();
+    if (!this.jwk) {
+      throw new Error("JWK not initialized");
+    }
+    return {
+      keys: [this.jwk]
+    };
+  }
+  /**
+   * Get the issuer URL
+   */
+  getIssuer() {
+    return this.issuer;
+  }
+  /**
+   * Get the audience
+   */
+  getAudience() {
+    return this.audience;
+  }
+};
+
 // libs/testing/src/interceptor/mock-registry.ts
 var DefaultMockRegistry = class {
   mocks = [];
@@ -1106,6 +1282,32 @@ function sleep3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// libs/testing/src/transport/error-utils.ts
+function errorName(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const name = err.name;
+  return typeof name === "string" ? name : void 0;
+}
+function isAbortError(err) {
+  return errorName(err) === "AbortError";
+}
+function errorMessage(err, fallback = "Unknown error") {
+  if (typeof err === "string" && err) return err;
+  if (typeof err === "object" && err !== null) {
+    const message = err.message;
+    if (typeof message === "string" && message) return message;
+  }
+  return fallback;
+}
+var interceptedErrors = /* @__PURE__ */ new WeakSet();
+function markInterceptedError(err) {
+  interceptedErrors.add(err);
+  return err;
+}
+function isInterceptedError(err) {
+  return typeof err === "object" && err !== null && interceptedErrors.has(err);
+}
+
 // libs/testing/src/transport/streamable-http.transport.ts
 var DEFAULT_TIMEOUT = 3e4;
 var NOTIFICATION_STREAM_REOPEN_DELAY_MS = 250;
@@ -1214,7 +1416,7 @@ var StreamableHttpTransport = class {
           return mockResponse2;
         }
         case "error":
-          throw interceptResult.error;
+          throw markInterceptedError(interceptResult.error);
         case "continue":
           message = interceptResult.request;
           break;
@@ -1275,7 +1477,7 @@ var StreamableHttpTransport = class {
       return jsonResponse;
     } catch (error) {
       clearTimeout(timeoutId);
-      if (error instanceof Error && error.name === "AbortError") {
+      if (isAbortError(error)) {
         return {
           jsonrpc: "2.0",
           id: message.id ?? null,
@@ -1314,7 +1516,7 @@ var StreamableHttpTransport = class {
       }
     } catch (error) {
       clearTimeout(timeoutId);
-      if (error instanceof Error && error.name !== "AbortError") {
+      if (!isAbortError(error)) {
         throw error;
       }
     }
@@ -1355,7 +1557,7 @@ var StreamableHttpTransport = class {
         error: {
           code: -32700,
           message: "Parse error",
-          data: error instanceof Error ? error.message : "Unknown error"
+          data: errorMessage(error)
         }
       };
     }
@@ -1725,7 +1927,7 @@ var StreamableHttpTransport = class {
     if (this.config.clientInfo) {
       headers["User-Agent"] = `${this.config.clientInfo.name}/${this.config.clientInfo.version}`;
     }
-    if (this.authToken && !this.publicMode) {
+    if (this.authToken) {
       headers["Authorization"] = `Bearer ${this.authToken}`;
     }
     if (this.sessionId) {
@@ -2049,6 +2251,15 @@ var DEFAULT_CLIENT_INFO = {
   version: "0.4.0"
 };
 var MAX_LIST_PAGES = 1e3;
+function isAuthFailure(error) {
+  return typeof error?.message === "string" && /^HTTP (401|403)\b/.test(error.message);
+}
+function describeInitializeError(error) {
+  const message = error?.message ?? "Unknown error";
+  const data = error?.data;
+  const detail = typeof data === "string" ? data.trim() : "";
+  return detail ? `${message} - ${detail.slice(0, 500)}` : message;
+}
 function extractEntryPaths(data) {
   let payload = data;
   if (typeof payload === "string") {
@@ -2135,19 +2346,22 @@ var McpTestClient = class {
   async connect() {
     this.log("debug", `Connecting to ${this.config.baseUrl}...`);
     this.triedDiscoveredEntryPath = false;
+    this.initResult = null;
     this.transport = this.createTransport();
     await this.transport.connect();
     const maxRetries = 3;
     const retryDelayMs = 500;
     let lastError;
     let reportedEntryPaths;
+    let attemptsMade = 0;
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      attemptsMade = attempt;
       const initResponse = await this.initialize();
       if (initResponse.success && initResponse.data) {
         this.initResult = initResponse.data;
         break;
       }
-      lastError = initResponse.error?.message ?? "Unknown error";
+      lastError = describeInitializeError(initResponse.error);
       reportedEntryPaths = extractEntryPaths(initResponse.error?.data) ?? reportedEntryPaths;
       if (reportedEntryPaths?.length === 1 && !this.triedDiscoveredEntryPath) {
         this.triedDiscoveredEntryPath = true;
@@ -2159,6 +2373,7 @@ var McpTestClient = class {
         await this.transport.connect();
         continue;
       }
+      if (isAuthFailure(initResponse.error)) break;
       if (attempt < maxRetries) {
         this.log("debug", `MCP init attempt ${attempt} failed (${lastError}), retrying in ${retryDelayMs}ms...`);
         await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
@@ -2167,7 +2382,7 @@ var McpTestClient = class {
     if (!this.initResult) {
       const served = reportedEntryPaths?.length ? ` The server reports it serves MCP at ${reportedEntryPaths.join(", ")}; set \`entryPath\` in test.use() (or \`http.entryPath\` on the server) to match.` : "";
       throw new Error(
-        `Failed to initialize MCP connection to ${this.config.baseUrl}${this.mcpPathLabel()} after ${maxRetries} attempts: ${lastError}.${served}`
+        `Failed to initialize MCP connection to ${this.config.baseUrl}${this.mcpPathLabel()} after ${attemptsMade} attempt${attemptsMade === 1 ? "" : "s"}: ${lastError}.${served}`
       );
     }
     this._sessionId = this.transport.getSessionId();
@@ -2237,18 +2452,47 @@ var McpTestClient = class {
     return this._authState;
   }
   /**
-   * Authenticate with a token
+   * Authenticate with a token.
+   *
+   * When connected, this opens a NEW session with the token (the previous session was created
+   * for the previous identity) and rejects if the server refuses it — for example because the
+   * token is expired or badly signed. On rejection the client keeps its previous identity and
+   * session. The token is kept in the client config, so `reconnect()` keeps using it.
    */
   async authenticate(token) {
+    if (typeof token !== "string" || token.trim() === "") {
+      throw new Error("authenticate() requires a non-empty token");
+    }
+    const previousAuthState = this._authState;
+    const previousConfigAuth = this.config.auth;
+    this.config.auth = { ...previousConfigAuth, token };
     this._authState = {
       isAnonymous: false,
       token,
       scopes: this.parseScopesFromToken(token),
       user: this.parseUserFromToken(token)
     };
-    if (this.transport) {
-      this.transport.setAuthToken(token);
+    const previousTransport = this.transport;
+    if (!previousTransport) {
+      this.log("debug", "Authentication updated (not connected yet)");
+      return;
     }
+    const previousInit = this.initResult;
+    const previousSessionId = this._sessionId;
+    const previousSessionInfo = this._sessionInfo;
+    try {
+      await this.connect();
+    } catch (err) {
+      await this.transport?.close().catch(() => void 0);
+      this.transport = previousTransport;
+      this.initResult = previousInit;
+      this._sessionId = previousSessionId;
+      this._sessionInfo = previousSessionInfo;
+      this.config.auth = previousConfigAuth;
+      this._authState = previousAuthState;
+      throw err;
+    }
+    await previousTransport.close().catch(() => void 0);
     this.log("debug", "Authentication updated");
   }
   // ═══════════════════════════════════════════════════════════════════
@@ -2872,10 +3116,11 @@ var McpTestClient = class {
         requestId: id
       };
     } catch (err) {
+      if (isInterceptedError(err)) throw err;
       const durationMs = Date.now() - start;
       const error = {
         code: -32603,
-        message: err instanceof Error ? err.message : "Unknown error"
+        message: errorMessage(err)
       };
       return {
         success: false,
@@ -3102,190 +3347,6 @@ var ProgressCollector = class {
   }
 };
 
-// libs/testing/src/auth/token-factory.ts
-var import_jose = require("jose");
-var TestTokenFactory = class {
-  issuer;
-  audience;
-  privateKey = null;
-  publicKey = null;
-  jwk = null;
-  keyId;
-  /** HS256 shared secret (gateway mode). Null → RS256 + JWKS (default). */
-  hmacSecret;
-  constructor(options = {}) {
-    this.issuer = options.issuer ?? "https://test.frontmcp.local";
-    this.audience = options.audience ?? "frontmcp-test";
-    this.keyId = `test-key-${Date.now()}`;
-    this.hmacSecret = options.hmacSecret ? new TextEncoder().encode(options.hmacSecret) : null;
-  }
-  /** True when this factory signs HS256 with a shared secret (gateway mode). */
-  get isHmac() {
-    return this.hmacSecret !== null;
-  }
-  /** The JWS `alg` this factory signs with. */
-  get alg() {
-    return this.isHmac ? "HS256" : "RS256";
-  }
-  /**
-   * The signing key: the shared HMAC secret in gateway mode, otherwise the
-   * generated RSA private key (lazily created via ensureKeys()).
-   */
-  signingKey() {
-    if (this.hmacSecret) return this.hmacSecret;
-    if (!this.privateKey) {
-      throw new Error("Private key not initialized");
-    }
-    return this.privateKey;
-  }
-  /**
-   * Initialize the key pair (called automatically on first use). No-op in HS256
-   * mode — there is no asymmetric keypair, just the shared secret.
-   */
-  async ensureKeys() {
-    if (this.isHmac) return;
-    if (this.privateKey && this.publicKey) return;
-    const { publicKey, privateKey } = await (0, import_jose.generateKeyPair)("RS256", {
-      extractable: true
-    });
-    this.privateKey = privateKey;
-    this.publicKey = publicKey;
-    this.jwk = await (0, import_jose.exportJWK)(publicKey);
-    this.jwk.kid = this.keyId;
-    this.jwk.use = "sig";
-    this.jwk.alg = "RS256";
-  }
-  /**
-   * Create a JWT token with the specified claims
-   */
-  async createTestToken(options) {
-    await this.ensureKeys();
-    const now = Math.floor(Date.now() / 1e3);
-    const exp = options.exp ?? 3600;
-    const payload = {
-      iss: options.iss ?? this.issuer,
-      sub: options.sub,
-      aud: options.aud ?? this.audience,
-      iat: now,
-      exp: now + exp,
-      scope: options.scopes?.join(" "),
-      ...options.claims
-    };
-    const header = this.isHmac ? { alg: this.alg, typ: "JWT" } : { alg: this.alg, kid: this.keyId };
-    const token = await new import_jose.SignJWT(payload).setProtectedHeader(header).sign(this.signingKey());
-    return token;
-  }
-  /**
-   * Create an admin token with full access
-   */
-  async createAdminToken(sub = "admin-001") {
-    return this.createTestToken({
-      sub,
-      scopes: ["admin:*", "read", "write", "delete"],
-      claims: {
-        email: "admin@test.local",
-        name: "Test Admin",
-        role: "admin"
-      }
-    });
-  }
-  /**
-   * Create a regular user token
-   */
-  async createUserToken(sub = "user-001", scopes = ["read", "write"]) {
-    return this.createTestToken({
-      sub,
-      scopes,
-      claims: {
-        email: "user@test.local",
-        name: "Test User",
-        role: "user"
-      }
-    });
-  }
-  /**
-   * Create an anonymous user token
-   */
-  async createAnonymousToken() {
-    return this.createTestToken({
-      sub: `anon:${Date.now()}`,
-      scopes: ["anonymous"],
-      claims: {
-        name: "Anonymous",
-        role: "anonymous"
-      }
-    });
-  }
-  /**
-   * Create an expired token (for testing token expiration)
-   */
-  async createExpiredToken(options) {
-    await this.ensureKeys();
-    const now = Math.floor(Date.now() / 1e3);
-    const payload = {
-      iss: this.issuer,
-      sub: options.sub,
-      aud: this.audience,
-      iat: now - 7200,
-      // 2 hours ago
-      exp: now - 3600
-      // Expired 1 hour ago
-    };
-    const header = this.isHmac ? { alg: this.alg, typ: "JWT" } : { alg: this.alg, kid: this.keyId };
-    const token = await new import_jose.SignJWT(payload).setProtectedHeader(header).sign(this.signingKey());
-    return token;
-  }
-  /**
-   * Create a token with an invalid signature (for testing signature validation)
-   */
-  createTokenWithInvalidSignature(options) {
-    const now = Math.floor(Date.now() / 1e3);
-    const headerObj = this.isHmac ? { alg: this.alg, typ: "JWT" } : { alg: this.alg, kid: this.keyId };
-    const header = Buffer.from(JSON.stringify(headerObj)).toString("base64url");
-    const payload = Buffer.from(
-      JSON.stringify({
-        iss: this.issuer,
-        sub: options.sub,
-        aud: this.audience,
-        iat: now,
-        exp: now + 3600
-      })
-    ).toString("base64url");
-    const signature = Buffer.from("invalid-signature-" + Date.now()).toString("base64url");
-    return `${header}.${payload}.${signature}`;
-  }
-  /**
-   * Get the public JWKS for verifying tokens.
-   *
-   * Only meaningful in RS256 mode — HS256 (gateway) tokens are verified against
-   * the shared secret, not a published public key, so there is no JWKS to serve.
-   */
-  async getPublicJwks() {
-    if (this.isHmac) {
-      throw new Error("getPublicJwks() is not available in HS256 mode (gateway tokens use a shared secret)");
-    }
-    await this.ensureKeys();
-    if (!this.jwk) {
-      throw new Error("JWK not initialized");
-    }
-    return {
-      keys: [this.jwk]
-    };
-  }
-  /**
-   * Get the issuer URL
-   */
-  getIssuer() {
-    return this.issuer;
-  }
-  /**
-   * Get the audience
-   */
-  getAudience() {
-    return this.audience;
-  }
-};
-
 // libs/testing/src/server/test-server.ts
 var import_child_process = require("child_process");
 var import_utils = require("@frontmcp/utils");
@@ -3358,6 +3419,8 @@ var E2E_PORT_RANGES = {
   "demo-e2e-distributed": { start: 50440, size: 20 },
   // Protocol revision E2E tests (50460-50479)
   "demo-e2e-protocol-20260728": { start: 50460, size: 20 },
+  // Testing library E2E tests (50480-50499)
+  "demo-e2e-testing": { start: 50480, size: 20 },
   // Mock servers and utilities (50900-50999)
   "mock-oauth": { start: 50900, size: 10 },
   "mock-api": { start: 50910, size: 10 },
@@ -3366,6 +3429,66 @@ var E2E_PORT_RANGES = {
   default: { start: 51e3, size: 100 }
 };
 var reservedPorts = /* @__PURE__ */ new Map();
+var lockedPorts = /* @__PURE__ */ new Set();
+var LOCK_MAX_AGE_MS = 10 * 60 * 1e3;
+function lockDir() {
+  try {
+    const os = require("node:os");
+    const path = require("node:path");
+    return path.join(os.tmpdir(), "frontmcp-testing-ports");
+  } catch {
+    return void 0;
+  }
+}
+function pidIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function acquirePortLock(port) {
+  if (lockedPorts.has(port)) return false;
+  let fs;
+  let file;
+  try {
+    fs = require("node:fs");
+    const dir = lockDir();
+    if (!dir) return true;
+    fs.mkdirSync(dir, { recursive: true });
+    file = require("node:path").join(dir, `${port}.lock`);
+  } catch {
+    return true;
+  }
+  const payload = JSON.stringify({ pid: process.pid, at: Date.now() });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      fs.writeFileSync(file, payload, { flag: "wx" });
+      lockedPorts.add(port);
+      return true;
+    } catch (error) {
+      if (error.code !== "EEXIST") return true;
+      try {
+        const held = JSON.parse(fs.readFileSync(file, "utf8"));
+        const fresh = typeof held.at === "number" && Date.now() - held.at < LOCK_MAX_AGE_MS;
+        if (fresh && typeof held.pid === "number" && pidIsAlive(held.pid)) return false;
+        fs.unlinkSync(file);
+      } catch {
+      }
+    }
+  }
+  return false;
+}
+function releasePortLock(port) {
+  if (!lockedPorts.delete(port)) return;
+  try {
+    const fs = require("node:fs");
+    const dir = lockDir();
+    if (dir) fs.unlinkSync(require("node:path").join(dir, `${port}.lock`));
+  } catch {
+  }
+}
 var projectPortIndex = /* @__PURE__ */ new Map();
 function getPortRange(project) {
   const key = project;
@@ -3376,15 +3499,22 @@ function getPortRange(project) {
 }
 async function reservePort(project, preferredPort) {
   const range = getPortRange(project);
-  if (preferredPort !== void 0) {
+  const handle = (port) => ({
+    port,
+    // Frees the socket only, so the server about to be spawned can bind the port; the lock file stays
+    releaseSocket: async () => {
+      await releasePort(port);
+    },
+    release: async () => {
+      await releasePort(port);
+      releasePortLock(port);
+    }
+  });
+  const wantsSpecificPort = preferredPort !== void 0 && Number.isInteger(preferredPort) && preferredPort > 0;
+  if (wantsSpecificPort) {
     const reservation = await tryReservePort(preferredPort, project);
     if (reservation) {
-      return {
-        port: preferredPort,
-        release: async () => {
-          await releasePort(preferredPort);
-        }
-      };
+      return handle(preferredPort);
     }
     console.warn(`[PortRegistry] Preferred port ${preferredPort} not available for ${project}, allocating from range`);
   }
@@ -3393,30 +3523,19 @@ async function reservePort(project, preferredPort) {
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
     const port = range.start + index % range.size;
     index = (index + 1) % range.size;
-    if (reservedPorts.has(port)) {
+    if (reservedPorts.has(port) || lockedPorts.has(port)) {
       continue;
     }
     const reservation = await tryReservePort(port, project);
     if (reservation) {
       projectPortIndex.set(project, index);
-      return {
-        port,
-        release: async () => {
-          await releasePort(port);
-        }
-      };
+      return handle(port);
     }
   }
-  const dynamicPort = await findAvailablePortInRange(51e3, 52e3);
-  if (dynamicPort) {
-    const reservation = await tryReservePort(dynamicPort, project);
-    if (reservation) {
-      return {
-        port: dynamicPort,
-        release: async () => {
-          await releasePort(dynamicPort);
-        }
-      };
+  for (let port = 51e3; port < 52e3; port++) {
+    if (reservedPorts.has(port) || lockedPorts.has(port)) continue;
+    if (await tryReservePort(port, project)) {
+      return handle(port);
     }
   }
   throw new Error(
@@ -3424,9 +3543,13 @@ async function reservePort(project, preferredPort) {
   );
 }
 async function tryReservePort(port, project) {
+  if (!acquirePortLock(port)) {
+    return false;
+  }
   return new Promise((resolve) => {
     const server = (0, import_net.createServer)();
     server.once("error", () => {
+      releasePortLock(port);
       resolve(false);
     });
     server.listen(port, () => {
@@ -3452,31 +3575,6 @@ async function releasePort(port) {
     });
   });
 }
-async function findAvailablePortInRange(start, end) {
-  for (let port = start; port < end; port++) {
-    if (reservedPorts.has(port)) {
-      continue;
-    }
-    const available = await isPortAvailable(port);
-    if (available) {
-      return port;
-    }
-  }
-  return null;
-}
-async function isPortAvailable(port) {
-  return new Promise((resolve) => {
-    const server = (0, import_net.createServer)();
-    server.once("error", () => {
-      resolve(false);
-    });
-    server.listen(port, () => {
-      server.close(() => {
-        resolve(true);
-      });
-    });
-  });
-}
 
 // libs/testing/src/server/test-server.ts
 var DEBUG_SERVER = process.env["DEBUG_SERVER"] === "1" || process.env["DEBUG"] === "1";
@@ -3485,8 +3583,11 @@ var TestServer = class _TestServer {
   options;
   _info;
   logs = [];
+  /** Frees the port reservation (socket and cross-process lock); held until stop() */
   portRelease = null;
-  constructor(options, port, portRelease) {
+  /** Frees only the reservation socket, just before the server is spawned */
+  portReleaseSocket = null;
+  constructor(options, port, portRelease, portReleaseSocket) {
     this.options = {
       port,
       project: options.project,
@@ -3498,6 +3599,7 @@ var TestServer = class _TestServer {
       debug: options.debug ?? DEBUG_SERVER
     };
     this.portRelease = portRelease ?? null;
+    this.portReleaseSocket = portReleaseSocket ?? portRelease ?? null;
     this._info = {
       baseUrl: `http://localhost:${port}`,
       port
@@ -3510,8 +3612,8 @@ var TestServer = class _TestServer {
     const project = options.project ?? "default";
     const maxAttempts = 3;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      const { port, release } = await reservePort(project, options.port);
-      const server = new _TestServer(options, port, release);
+      const { port, release, releaseSocket } = await reservePort(project, options.port);
+      const server = new _TestServer(options, port, release, releaseSocket);
       try {
         await server.startProcess();
         return server;
@@ -3551,7 +3653,7 @@ var TestServer = class _TestServer {
     }
     const maxAttempts = 3;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      const { port, release } = await reservePort(project, options.port);
+      const { port, release, releaseSocket } = await reservePort(project, options.port);
       const serverOptions = {
         ...options,
         port,
@@ -3559,7 +3661,7 @@ var TestServer = class _TestServer {
         command: `npx nx serve ${project} --port ${port}`,
         cwd: options.cwd ?? process.cwd()
       };
-      const server = new _TestServer(serverOptions, port, release);
+      const server = new _TestServer(serverOptions, port, release, releaseSocket);
       try {
         await server.startProcess();
         return server;
@@ -3617,10 +3719,17 @@ var TestServer = class _TestServer {
    * Stop the test server
    */
   async stop() {
-    if (this.portRelease) {
-      await this.portRelease();
-      this.portRelease = null;
+    try {
+      await this.stopProcess();
+    } finally {
+      if (this.portRelease) {
+        await this.portRelease();
+        this.portRelease = null;
+      }
+      this.portReleaseSocket = null;
     }
+  }
+  async stopProcess() {
     if (this.process) {
       this.log("Stopping server...");
       if (this.process.exitCode !== null || this.process.signalCode !== null) {
@@ -3693,7 +3802,7 @@ var TestServer = class _TestServer {
    * Restart the server
    */
   async restart() {
-    await this.stop();
+    await this.stopProcess();
     await this.startProcess();
   }
   /**
@@ -3723,9 +3832,9 @@ var TestServer = class _TestServer {
       PORT: String(this.options.port)
     };
     const runtimeEnv = withWorkspaceProtocolFallback(env, this.options.cwd);
-    if (this.portRelease) {
-      await this.portRelease();
-      this.portRelease = null;
+    if (this.portReleaseSocket) {
+      await this.portReleaseSocket();
+      this.portReleaseSocket = null;
       await sleep4(300);
     }
     this.process = (0, import_child_process.spawn)(this.options.command, [], {
@@ -3735,9 +3844,8 @@ var TestServer = class _TestServer {
       detached: true,
       stdio: ["pipe", "pipe", "pipe"]
     });
-    if (this.process.pid !== void 0) {
-      this._info.pid = this.process.pid;
-    }
+    this._info.pid = this.process.pid;
+    this._info.shellPid = this.process.pid;
     let processExited = false;
     let exitCode = null;
     let exitError = null;
@@ -3840,6 +3948,8 @@ ${allLogs}`);
         });
         if (response.ok || response.status === 404) {
           this.log(`Server is ready after ${healthCheckAttempts} health check attempts`);
+          const listeningPid = await findListeningPid(this.options.port);
+          if (listeningPid !== void 0) this._info.pid = listeningPid;
           return;
         }
         lastHealthCheckError = `HTTP ${response.status}: ${response.statusText}`;
@@ -3884,6 +3994,19 @@ TIP: Set DEBUG_SERVER=1 or DEBUG=1 environment variable for verbose output`
 function sleep4(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function findListeningPid(port) {
+  if (process.platform === "win32") return Promise.resolve(void 0);
+  return new Promise((resolve) => {
+    (0, import_child_process.execFile)("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], { timeout: 2e3 }, (error, stdout) => {
+      if (error) {
+        resolve(void 0);
+        return;
+      }
+      const pid = parseInt(String(stdout).split("\n")[0] ?? "", 10);
+      resolve(Number.isInteger(pid) && pid > 0 ? pid : void 0);
+    });
+  });
+}
 function withWorkspaceProtocolFallback(env, cwd) {
   if (findInstalledProtocolPackageDir(cwd)) {
     return env;
@@ -4031,7 +4154,8 @@ Server entry: ${currentConfig.server}
 Project: ${currentConfig.project ?? "default"}
 Command: ${serverCommand}
 
-Error: ${errMsg}`
+Error: ${errMsg}`,
+          { cause: error }
         );
       }
     } else {
@@ -4221,16 +4345,19 @@ function todo(name) {
 }
 var perfTest = perfTestWithFixtures;
 perfTest.use = use;
-perfTest.describe = describe;
-perfTest.beforeAll = beforeAll;
-perfTest.beforeEach = beforeEach;
-perfTest.afterEach = afterEach;
-perfTest.afterAll = afterAll;
+for (const hook of ["describe", "beforeAll", "beforeEach", "afterEach", "afterAll"]) {
+  Object.defineProperty(perfTest, hook, {
+    get: () => globalThis[hook],
+    enumerable: true,
+    configurable: true
+  });
+}
 perfTest.skip = skip;
 perfTest.only = only;
 perfTest.todo = todo;
 
 // libs/testing/src/perf/baseline-store.ts
+var import_utils2 = require("@frontmcp/utils");
 var BASELINE_START_MARKER = "<!-- PERF_BASELINE_START -->";
 var BASELINE_END_MARKER = "<!-- PERF_BASELINE_END -->";
 var DEFAULT_BASELINE_PATH = "perf-results/baseline.json";
@@ -4245,11 +4372,10 @@ var BaselineStore = class {
    */
   async load() {
     try {
-      const { readFile, fileExists } = await import("@frontmcp/utils");
-      if (!await fileExists(this.baselinePath)) {
+      if (!await (0, import_utils2.fileExists)(this.baselinePath)) {
         return null;
       }
-      const content = await readFile(this.baselinePath);
+      const content = await (0, import_utils2.readFile)(this.baselinePath);
       this.baseline = JSON.parse(content);
       return this.baseline;
     } catch {
@@ -4260,10 +4386,9 @@ var BaselineStore = class {
    * Save baseline to local file.
    */
   async save(baseline) {
-    const { writeFile, ensureDir } = await import("@frontmcp/utils");
     const dir = this.baselinePath.substring(0, this.baselinePath.lastIndexOf("/"));
-    await ensureDir(dir);
-    await writeFile(this.baselinePath, JSON.stringify(baseline, null, 2));
+    await (0, import_utils2.ensureDir)(dir);
+    await (0, import_utils2.writeFile)(this.baselinePath, JSON.stringify(baseline, null, 2));
     this.baseline = baseline;
   }
   /**
@@ -4539,6 +4664,7 @@ function resetRegressionDetector() {
 }
 
 // libs/testing/src/perf/report-generator.ts
+var import_utils3 = require("@frontmcp/utils");
 var ReportGenerator = class {
   detector;
   constructor() {
@@ -4794,14 +4920,13 @@ var ReportGenerator = class {
   }
 };
 async function saveReports(measurements, outputDir, baseline, gitInfo) {
-  const { writeFile, ensureDir } = await import("@frontmcp/utils");
-  await ensureDir(outputDir);
+  await (0, import_utils3.ensureDir)(outputDir);
   const generator = new ReportGenerator();
   const report = generator.generateReport(measurements, baseline, gitInfo);
   const jsonPath = `${outputDir}/report.json`;
   const markdownPath = `${outputDir}/report.md`;
-  await writeFile(jsonPath, generator.generateJsonReport(report));
-  await writeFile(markdownPath, generator.generateMarkdownReport(report));
+  await (0, import_utils3.writeFile)(jsonPath, generator.generateJsonReport(report));
+  await (0, import_utils3.writeFile)(markdownPath, generator.generateMarkdownReport(report));
   return { jsonPath, markdownPath };
 }
 function createReportGenerator() {