fraim 2.0.300 → 2.0.301

package/dist/src/cli/doctor/checks/mcp-connectivity-checks.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNpmMajorVersion = getNpmMajorVersion;
 exports.diagnoseFraimMcpLaunchPlan = diagnoseFraimMcpLaunchPlan;
 exports.spawnAndHandshake = spawnAndHandshake;
+exports.testStdioMCPServer = testStdioMCPServer;
 exports.getStdioMCPRuntimeChecks = getStdioMCPRuntimeChecks;
 exports.getMCPConnectivityChecks = getMCPConnectivityChecks;
 const fs_1 = __importDefault(require("fs"));
@@ -646,7 +647,11 @@ async function testFraimLocalProxyTroubleshooting() {
 // ============================================================
 // Issue #532: Stdio MCP Runtime Connectivity Check
 // ============================================================
-const STDIO_HANDSHAKE_TIMEOUT_MS = 15000;
+// Issue #1474: raised from 15000. A reporter's own *warm*-cache measurements were ~9.4-10s,
+// already 63-67% of the old budget; a cold first `npx -y <package>` fetch routinely exceeds it
+// outright. This does not remove the ambiguity a timeout can't resolve on its own (see the
+// 'warning' status below) but reduces how often it's hit in the first place.
+const STDIO_HANDSHAKE_TIMEOUT_MS = 30000;
 /**
  * Spawn a stdio MCP server, perform a two-phase JSON-RPC handshake
  * (initialize then tools/list), and return a structured result.
@@ -730,11 +735,16 @@ async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIME
                 child.kill('SIGKILL');
             }
             catch { /* best effort */ }
+            // Issue #1474: a timeout is 'warning', not 'error' -- this check cannot distinguish a
+            // server that is genuinely broken from one that is merely slow to start (a cold npx cache
+            // downloading the package for the first time), so it reports the honest uncertainty rather
+            // than a false-confident failure. A warning that persists across retries still signals
+            // something is wrong; a one-off warning on first run does not.
             settle({
-                status: 'error',
+                status: 'warning',
                 phase: initializeResponse ? 'tools-list' : 'initialize',
                 message: `MCP server did not respond within ${timeoutMs}ms`,
-                suggestion: 'The server may be slow to start. Check that the package is installed and npx cache is warm.',
+                suggestion: 'This may mean the package is still installing on a cold npx cache. Retry once the cache is warm; if it keeps timing out, treat it as broken.',
                 details: { command, args, timeoutMs, elapsed: Date.now() - startTime }
             });
         }, timeoutMs);
@@ -914,8 +924,12 @@ async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIME
 }
 /**
  * Run a connectivity check for a single named stdio MCP server.
+ *
+ * `timeoutMs` defaults to STDIO_HANDSHAKE_TIMEOUT_MS; it is exposed as a parameter (mirroring
+ * spawnAndHandshake's own signature) so tests can exercise the real timeout/warning path quickly
+ * without waiting on the full production budget.
  */
-async function testStdioMCPServer(serverName, command, args) {
+async function testStdioMCPServer(serverName, command, args, timeoutMs = STDIO_HANDSHAKE_TIMEOUT_MS) {
     if (process.env.NODE_ENV === 'test') {
         return {
             status: 'warning',
@@ -923,7 +937,7 @@ async function testStdioMCPServer(serverName, command, args) {
             details: { testMode: true, skipped: true, serverName }
         };
     }
-    const result = await spawnAndHandshake(command, args, STDIO_HANDSHAKE_TIMEOUT_MS);
+    const result = await spawnAndHandshake(command, args, timeoutMs);
     if (result.status === 'passed') {
         return {
             status: 'passed',
@@ -931,6 +945,16 @@ async function testStdioMCPServer(serverName, command, args) {
             details: result.details
         };
     }
+    // Issue #1474: preserve spawnAndHandshake's 'warning' (ambiguous timeout) as a doctor 'warning'
+    // rather than collapsing it into the same hard 'error' used for unambiguous failures below.
+    if (result.status === 'warning') {
+        return {
+            status: 'warning',
+            message: `${serverName} stdio MCP connectivity uncertain (phase: ${result.phase}): ${result.message}`,
+            suggestion: result.suggestion,
+            details: { ...result.details, phase: result.phase }
+        };
+    }
     return {
         status: 'error',
         message: `${serverName} stdio MCP connectivity failed (phase: ${result.phase}): ${result.message}`,

package/dist/src/cli/mcp/fraim-mcp-latest-launcher.js

@@ -304,6 +304,13 @@ function ensureFraimMcpLatestLauncher() {
         }
         writeFileIfChanged(fraimMcpShimPath, packagedFraimShimSource('mcp', packagedRuntime), process.platform === 'win32' ? undefined : 0o755);
         writeFileIfChanged(fraimCliShimPath, packagedFraimShimSource('cli', packagedRuntime), process.platform === 'win32' ? undefined : 0o755);
+        // Issue #1474: keep the npx companion shim in parity with the non-packaged branch below.
+        // The packaged fraim-mcp shim itself never invokes npx, but git/playwright base MCP servers
+        // (added later via the connect-mcp skill once a system npm is available) and doctor's
+        // launch-plan diagnostic both expect this file to exist alongside the stable fraim shim.
+        // Without it, doctor's "stable shim missing on disk" check could never be satisfied on a
+        // packaged install, and --fix-mcp/add-ide (which call this same function) could never fix it.
+        writeFileIfChanged(fraimNpxShimPath, process.platform === 'win32' ? windowsFraimNpxShimSource : posixFraimNpxShimSource, process.platform === 'win32' ? undefined : 0o755);
         return {
             command: fraimMcpShimPath,
             args: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.300",
+  "version": "2.0.301",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {