retestkit 1.4.1

package/src/index.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { createServer as createHttpServer } from "node:http";
+import { loadConfig } from "./config.js";
+import { createLogger } from "./logger.js";
+import { createServer } from "./server.js";
+import { createTransport } from "./transports/index.js";
+
+async function main(): Promise<void> {
+  // Load and validate configuration
+  let config;
+  try {
+    config = loadConfig();
+  } catch (error) {
+    console.error(
+      "Configuration error:",
+      error instanceof Error ? error.message : error
+    );
+    process.exit(1);
+  }
+
+  const logger = createLogger(config.logLevel);
+  logger.info("Starting server", { transport: config.transport });
+
+  // Create MCP server with all components
+  const { server, cleanup } = createServer(config, logger);
+
+  // Create transport based on configuration
+  const transportResult = createTransport(config, logger);
+
+  // Set up graceful shutdown
+  const shutdown = async (signal: string) => {
+    logger.info("Received shutdown signal", { signal });
+    try {
+      await cleanup();
+      await server.close();
+      logger.info("Server closed gracefully");
+      process.exit(0);
+    } catch (error) {
+      logger.error("Error during shutdown", {
+        error: error instanceof Error ? error.message : "Unknown error",
+      });
+      process.exit(1);
+    }
+  };
+
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+  // Connect based on transport type
+  if (transportResult.type === "stdio") {
+    await server.connect(transportResult.transport);
+    logger.info("Server connected via stdio");
+  } else {
+    // HTTP transport requires an HTTP server
+    const httpServer = createHttpServer(async (req, res) => {
+      // Handle MCP requests
+      if (req.method === "POST") {
+        await transportResult.transport.handleRequest(req, res);
+      } else if (req.method === "GET") {
+        // Health check endpoint
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok" }));
+      } else {
+        res.writeHead(405);
+        res.end();
+      }
+    });
+
+    await server.connect(transportResult.transport);
+
+    httpServer.listen(transportResult.port, () => {
+      logger.info("Server listening", {
+        transport: "http",
+        port: transportResult.port,
+      });
+    });
+  }
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/lifecycle/index.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  parseClientCapabilities,
+  getServerCapabilities,
+  checkCapability,
+  REQUIRED_PROTOCOL_VERSION,
+  type InitializeResult,
+} from "./index.js";
+import type { Logger } from "../logger.js";
+
+describe("lifecycle", () => {
+  let mockLogger: Logger;
+
+  beforeEach(() => {
+    mockLogger = {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      setLevel: vi.fn(),
+      withCorrelation: vi.fn().mockReturnThis(),
+    } as unknown as Logger;
+  });
+
+  describe("parseClientCapabilities", () => {
+    it("parses full capabilities correctly", () => {
+      const initResult: InitializeResult = {
+        protocolVersion: "2025-06-18",
+        capabilities: {
+          sampling: {},
+          elicitation: {},
+          logging: {},
+          resources: {
+            listChanged: true,
+            subscribe: true,
+          },
+        },
+        clientInfo: {
+          name: "TestClient",
+          version: "1.0.0",
+        },
+      };
+
+      const caps = parseClientCapabilities(initResult, mockLogger);
+
+      expect(caps.sampling).toBe(true);
+      expect(caps.elicitation).toBe(true);
+      expect(caps.logging).toBe(true);
+      expect(caps.resourcesListChanged).toBe(true);
+      expect(caps.resourcesSubscribe).toBe(true);
+      expect(caps.progress).toBe(true); // Linked to sampling
+      expect(caps.protocolVersion).toBe("2025-06-18");
+    });
+
+    it("handles missing capabilities", () => {
+      const initResult: InitializeResult = {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+      };
+
+      const caps = parseClientCapabilities(initResult, mockLogger);
+
+      expect(caps.sampling).toBe(false);
+      expect(caps.elicitation).toBe(false);
+      expect(caps.logging).toBe(false);
+      expect(caps.resourcesListChanged).toBe(false);
+      expect(caps.resourcesSubscribe).toBe(false);
+      expect(caps.progress).toBe(false);
+    });
+
+    it("disables elicitation for older protocol versions", () => {
+      const initResult: InitializeResult = {
+        protocolVersion: "2024-12-01",
+        capabilities: {
+          sampling: {},
+          elicitation: {},
+        },
+      };
+
+      const caps = parseClientCapabilities(initResult, mockLogger);
+
+      expect(caps.sampling).toBe(true);
+      expect(caps.elicitation).toBe(false); // Disabled due to old protocol
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        "Running in degraded mode due to older protocol version",
+        expect.any(Object)
+      );
+    });
+
+    it("enables elicitation for required protocol version", () => {
+      const initResult: InitializeResult = {
+        protocolVersion: REQUIRED_PROTOCOL_VERSION,
+        capabilities: {
+          elicitation: {},
+        },
+      };
+
+      const caps = parseClientCapabilities(initResult, mockLogger);
+
+      expect(caps.elicitation).toBe(true);
+    });
+
+    it("enables elicitation for newer protocol versions", () => {
+      const initResult: InitializeResult = {
+        protocolVersion: "2025-12-01",
+        capabilities: {
+          elicitation: {},
+        },
+      };
+
+      const caps = parseClientCapabilities(initResult, mockLogger);
+
+      expect(caps.elicitation).toBe(true);
+    });
+
+    it("links progress to sampling capability", () => {
+      const withSampling: InitializeResult = {
+        protocolVersion: "2025-06-18",
+        capabilities: { sampling: {} },
+      };
+
+      const withoutSampling: InitializeResult = {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+      };
+
+      const capsWithSampling = parseClientCapabilities(withSampling, mockLogger);
+      const capsWithoutSampling = parseClientCapabilities(
+        withoutSampling,
+        mockLogger
+      );
+
+      expect(capsWithSampling.progress).toBe(true);
+      expect(capsWithoutSampling.progress).toBe(false);
+    });
+
+    it("handles missing protocolVersion", () => {
+      const initResult: InitializeResult = {
+        protocolVersion: "",
+        capabilities: {},
+      };
+
+      const caps = parseClientCapabilities(initResult, mockLogger);
+
+      // Empty string is treated as falsy and defaults to "unknown"
+      expect(caps.protocolVersion).toBe("unknown");
+    });
+
+    it("logs warning when sampling unavailable", () => {
+      const initResult: InitializeResult = {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+      };
+
+      parseClientCapabilities(initResult, mockLogger);
+
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        "Sampling not available - AI-powered features will use fallback mode",
+        expect.any(Object)
+      );
+    });
+
+    it("logs info when elicitation unavailable", () => {
+      const initResult: InitializeResult = {
+        protocolVersion: "2025-06-18",
+        capabilities: { sampling: {} },
+      };
+
+      parseClientCapabilities(initResult, mockLogger);
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        "Elicitation not available - user decisions via tool output",
+        expect.any(Object)
+      );
+    });
+
+    it("logs detected capabilities", () => {
+      const initResult: InitializeResult = {
+        protocolVersion: "2025-06-18",
+        capabilities: {
+          sampling: {},
+          logging: {},
+        },
+      };
+
+      parseClientCapabilities(initResult, mockLogger);
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        "Client capabilities detected",
+        expect.objectContaining({
+          sampling: true,
+          logging: true,
+        })
+      );
+    });
+  });
+
+  describe("getServerCapabilities", () => {
+    it("returns correct server capabilities", () => {
+      const caps = getServerCapabilities();
+
+      expect(caps).toEqual({
+        tools: {},
+        resources: {
+          listChanged: true,
+          subscribe: true,
+        },
+        prompts: {},
+        logging: {},
+      });
+    });
+
+    it("advertises resource capabilities", () => {
+      const caps = getServerCapabilities();
+
+      expect(caps.resources.listChanged).toBe(true);
+      expect(caps.resources.subscribe).toBe(true);
+    });
+  });
+
+  describe("checkCapability", () => {
+    it("returns true for enabled capabilities", () => {
+      const caps = {
+        sampling: true,
+        elicitation: true,
+        logging: false,
+        progress: true,
+        resourcesListChanged: false,
+        resourcesSubscribe: false,
+        protocolVersion: "2025-06-18",
+      };
+
+      expect(checkCapability(caps, "sampling")).toBe(true);
+      expect(checkCapability(caps, "elicitation")).toBe(true);
+      expect(checkCapability(caps, "progress")).toBe(true);
+    });
+
+    it("returns false for disabled capabilities", () => {
+      const caps = {
+        sampling: false,
+        elicitation: false,
+        logging: false,
+        progress: false,
+        resourcesListChanged: false,
+        resourcesSubscribe: false,
+        protocolVersion: "2025-06-18",
+      };
+
+      expect(checkCapability(caps, "sampling")).toBe(false);
+      expect(checkCapability(caps, "elicitation")).toBe(false);
+      expect(checkCapability(caps, "logging")).toBe(false);
+    });
+  });
+
+  describe("REQUIRED_PROTOCOL_VERSION", () => {
+    it("is set to expected version", () => {
+      expect(REQUIRED_PROTOCOL_VERSION).toBe("2025-06-18");
+    });
+  });
+});

package/src/lifecycle/index.ts

@@ -0,0 +1,101 @@
+import type { Logger } from "../logger.js";
+import {
+  type ClientCapabilities,
+  DEFAULT_CAPABILITIES,
+} from "../types/capabilities.js";
+
+export const REQUIRED_PROTOCOL_VERSION = "2025-06-18";
+
+export interface InitializeResult {
+  protocolVersion: string;
+  capabilities: {
+    sampling?: Record<string, unknown>;
+    elicitation?: Record<string, unknown>;
+    logging?: Record<string, unknown>;
+    resources?: {
+      listChanged?: boolean;
+      subscribe?: boolean;
+    };
+  };
+  clientInfo?: {
+    name: string;
+    version: string;
+  };
+}
+
+export function parseClientCapabilities(
+  initResult: InitializeResult,
+  logger: Logger
+): ClientCapabilities {
+  const caps = initResult.capabilities || {};
+  const protocolVersion = initResult.protocolVersion || "unknown";
+
+  const clientCaps: ClientCapabilities = {
+    ...DEFAULT_CAPABILITIES,
+    protocolVersion,
+    sampling: !!caps.sampling,
+    logging: !!caps.logging,
+    resourcesListChanged: !!caps.resources?.listChanged,
+    resourcesSubscribe: !!caps.resources?.subscribe,
+    // Elicitation requires protocol version 2025-06-18+
+    elicitation:
+      !!caps.elicitation && protocolVersion >= REQUIRED_PROTOCOL_VERSION,
+    // Progress is typically available if sampling is available
+    progress: !!caps.sampling,
+  };
+
+  // Log capability detection
+  logger.info("Client capabilities detected", {
+    protocolVersion,
+    sampling: clientCaps.sampling,
+    elicitation: clientCaps.elicitation,
+    logging: clientCaps.logging,
+    resourcesListChanged: clientCaps.resourcesListChanged,
+    resourcesSubscribe: clientCaps.resourcesSubscribe,
+  });
+
+  // Warn about degraded mode
+  if (protocolVersion < REQUIRED_PROTOCOL_VERSION) {
+    logger.warn("Running in degraded mode due to older protocol version", {
+      clientVersion: protocolVersion,
+      requiredVersion: REQUIRED_PROTOCOL_VERSION,
+      disabledFeatures: ["elicitation"],
+    });
+  }
+
+  if (!clientCaps.sampling) {
+    logger.warn(
+      "Sampling not available - AI-powered features will use fallback mode",
+      {
+        fallbackBehavior: "manual prompts via resources",
+      }
+    );
+  }
+
+  if (!clientCaps.elicitation) {
+    logger.info("Elicitation not available - user decisions via tool output", {
+      fallbackBehavior: "questions in tool response",
+    });
+  }
+
+  return clientCaps;
+}
+
+export function getServerCapabilities() {
+  return {
+    tools: {},
+    resources: {
+      listChanged: true,
+      subscribe: true,
+    },
+    prompts: {},
+    logging: {},
+  };
+}
+
+export function checkCapability(
+  caps: ClientCapabilities,
+  capability: keyof Omit<ClientCapabilities, "protocolVersion">
+): boolean {
+  return caps[capability];
+}