@mcp-z/client 2.2.3 → 2.3.0

package/dist/esm/spawn/spawn-server.js

@@ -1,55 +1,173 @@
 /**
  * Low-level single server spawning utilities.
  * Provides core process spawning with path resolution, environment management, and lifecycle control.
- */ import { spawn } from 'child_process';
+ */ import crossSpawn from 'cross-spawn';
+import * as path from 'path';
 import * as process from 'process';
 import { logger } from '../utils/logger.js';
 import { resolveArgsPaths } from '../utils/path-utils.js';
-/**
- * Normalize environment variables by merging with process.env and filtering undefined values.
- */ function normalizeEnv(env) {
+import { OwnedProcessTree } from './owned-process-tree.js';
+const DEFAULT_CLOSE_TIMEOUT_MS = 5000;
+const PROCESS_TERMINATION_TIMEOUT_MS = 5000;
+const PROCESS_POLL_INTERVAL_MS = 25;
+function normalizeEnv(env, inheritEnv = true) {
     const merged = {
-        ...process.env,
+        ...inheritEnv ? process.env : {},
         ...env || {}
     };
     const result = {};
     for (const [key, value] of Object.entries(merged)){
-        if (value !== undefined) {
-            result[key] = value;
-        }
+        if (value !== undefined) result[key] = value;
     }
     return result;
 }
+function delay(ms) {
+    return new Promise((resolve)=>setTimeout(resolve, ms));
+}
+async function waitForCompletion(closeEvent, childClosed, tree, timeoutMs) {
+    if (!tree) return {
+        closed: await waitForChildClose(closeEvent, timeoutMs) !== undefined
+    };
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while(true){
+        let processGroupEmpty = false;
+        try {
+            processGroupEmpty = tree.isEmpty();
+            lastError = undefined;
+        } catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+        }
+        const closed = childClosed();
+        if (closed && processGroupEmpty) return {
+            closed,
+            processGroupEmpty
+        };
+        if (Date.now() >= deadline) return {
+            closed,
+            processGroupEmpty,
+            ...lastError && {
+                error: lastError
+            }
+        };
+        await delay(Math.min(PROCESS_POLL_INTERVAL_MS, Math.max(1, deadline - Date.now())));
+    }
+}
+function isCompletionSuccessful(completion) {
+    return completion.closed && completion.processGroupEmpty !== false;
+}
+function terminateChild(child, tree) {
+    if (tree) return tree.terminate();
+    try {
+        return {
+            killed: child.kill('SIGKILL')
+        };
+    } catch (error) {
+        return {
+            killed: false,
+            error: asError(error)
+        };
+    }
+}
+function waitForChildClose(closeEvent, timeoutMs) {
+    let timer;
+    return Promise.race([
+        closeEvent,
+        new Promise((resolve)=>{
+            timer = setTimeout(()=>resolve(undefined), timeoutMs);
+        })
+    ]).finally(()=>{
+        if (timer) clearTimeout(timer);
+    });
+}
+function requestProcessSignal(child, signal) {
+    if (!child.pid) throw new Error('Cannot request cooperative shutdown because the server has no process ID');
+    if (process.platform === 'win32') throw new Error('POSIX process signals are not available on Windows');
+    try {
+        process.kill(-child.pid, signal);
+    } catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ESRCH')) throw error;
+    }
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function withCause(message, cause) {
+    return new Error(message, {
+        cause
+    });
+}
+async function runStopCommand(command, cwd, timeoutMs, inheritEnv) {
+    const stopCwd = command.cwd ? path.resolve(cwd, command.cwd) : cwd;
+    const env = normalizeEnv(command.env, inheritEnv);
+    const args = command.args ? resolveArgsPaths(command.args, stopCwd) : [];
+    const child = crossSpawn(command.command, args, {
+        cwd: stopCwd,
+        env,
+        stdio: 'ignore',
+        shell: false,
+        detached: process.platform !== 'win32',
+        windowsHide: true
+    });
+    let spawnError;
+    let closed = false;
+    let closeEventValue;
+    const closeEvent = new Promise((resolve)=>{
+        child.once('error', (error)=>{
+            spawnError = error;
+        });
+        child.once('close', (code, signal)=>{
+            closed = true;
+            closeEventValue = {
+                code,
+                signal
+            };
+            resolve({
+                code,
+                signal
+            });
+        });
+    });
+    if (!child.pid) {
+        const result = await waitForChildClose(closeEvent, timeoutMs);
+        if (!result) throw new Error(`Stop command did not start or close within ${timeoutMs}ms`);
+        if (spawnError) throw withCause(`Stop command could not be started: ${spawnError.message}`, spawnError);
+    }
+    const tree = child.pid && process.platform !== 'win32' ? new OwnedProcessTree(child.pid) : undefined;
+    const completion = await waitForCompletion(closeEvent, ()=>closed, tree, timeoutMs);
+    if (!isCompletionSuccessful(completion)) {
+        var _completion_error, _termination_error;
+        const termination = terminateChild(child, tree);
+        const afterTermination = await waitForCompletion(closeEvent, ()=>closed, tree, PROCESS_TERMINATION_TIMEOUT_MS);
+        const details = [
+            (_completion_error = completion.error) === null || _completion_error === void 0 ? void 0 : _completion_error.message,
+            (_termination_error = termination.error) === null || _termination_error === void 0 ? void 0 : _termination_error.message
+        ].filter(Boolean).join('; ');
+        const reason = `Stop command exceeded ${timeoutMs}ms and required emergency process termination`;
+        const remaining = !isCompletionSuccessful(afterTermination) ? '; stop command or its POSIX process group remained alive' : '';
+        throw new Error(`${reason}${details ? `: ${details}` : ''}${remaining}`);
+    }
+    if (spawnError) throw withCause(`Stop command could not be started: ${spawnError.message}`, spawnError);
+    if (closeEventValue && (closeEventValue.code !== 0 || closeEventValue.signal !== null)) {
+        var _closeEventValue_code;
+        throw new Error(`Stop command exited with code ${(_closeEventValue_code = closeEventValue.code) !== null && _closeEventValue_code !== void 0 ? _closeEventValue_code : 'unknown'}${closeEventValue.signal ? ` (signal ${closeEventValue.signal})` : ''}`);
+    }
+}
 /**
  * Spawn a single server process with path resolution and environment management.
  *
  * @internal
  * @param opts - Server spawn options
- * @returns ServerProcess handle with resolved config, process, and stop function
- *
- * @example
- * const handle = spawnProcess({
- *   name: 'echo',
- *   command: 'node',
- *   args: ['./bin/server.js', '--port', '3000'],
- *   cwd: '/home/user/project/test/lib/servers/echo',
- *   env: { LOG_LEVEL: 'error' }
- * });
- *
- * // Later...
- * await handle.close();
+ * @returns ServerProcess handle with resolved config and lifecycle control
  */ export function spawnProcess(opts) {
-    var _opts_cwd, _opts_stdio, _opts_shell;
+    var _opts_cwd, _opts_stdio, _opts_inheritEnv;
     const name = opts.name;
     const command = opts.command;
     const cwd = (_opts_cwd = opts.cwd) !== null && _opts_cwd !== void 0 ? _opts_cwd : process.cwd();
     const stdio = (_opts_stdio = opts.stdio) !== null && _opts_stdio !== void 0 ? _opts_stdio : 'inherit';
-    const shell = (_opts_shell = opts.shell) !== null && _opts_shell !== void 0 ? _opts_shell : process.platform === 'win32';
-    // Resolve paths in args relative to the working directory
     const args = opts.args ? resolveArgsPaths(opts.args, cwd) : [];
-    // Merge environment variables
-    const env = normalizeEnv(opts.env);
-    // Create resolved config for return value
+    const inheritEnv = (_opts_inheritEnv = opts.inheritEnv) !== null && _opts_inheritEnv !== void 0 ? _opts_inheritEnv : true;
+    const env = normalizeEnv(opts.env, inheritEnv);
     const resolvedConfig = {
         name,
         command,
@@ -57,93 +175,104 @@ import { resolveArgsPaths } from '../utils/path-utils.js';
         cwd,
         env,
         stdio,
-        shell
+        shell: false
     };
-    // Log spawn operation
     logger.info(`[${name}] → ${command} ${args.join(' ')}`);
-    // Spawn the process
-    const spawnOpts = {
+    const child = crossSpawn(command, args, {
         cwd,
         env,
         stdio,
-        shell
-    };
-    const child = spawn(command, args, spawnOpts);
-    // Pipe stdio if not inherited
-    if (child.stderr) child.stderr.on('data', (chunk)=>{
-        process.stderr.write(chunk);
+        shell: false,
+        detached: process.platform !== 'win32',
+        windowsHide: true
     });
-    // Attach lifecycle logging
-    child.on('exit', (code, sig)=>logger.info(`[${name}] exited (code=${code}, signal=${sig || 'none'})`));
-    child.on('error', (err)=>logger.info(`[${name}] process error: ${err.message}`));
-    // Create stop function with graceful shutdown
-    const stop = async (signal = 'SIGINT', opts = {})=>{
-        var _opts_timeoutMs;
-        // If already exited, return immediately
-        if (child.exitCode !== null || child.signalCode !== null) {
-            return {
-                timedOut: false,
-                killed: false
+    if (child.stderr) child.stderr.on('data', (chunk)=>process.stderr.write(chunk));
+    let isClosed = false;
+    let _closeEventValue;
+    const closeEvent = new Promise((resolve)=>{
+        child.once('close', (code, signal)=>{
+            isClosed = true;
+            _closeEventValue = {
+                code,
+                signal
             };
-        }
-        const timeoutMs = (_opts_timeoutMs = opts.timeoutMs) !== null && _opts_timeoutMs !== void 0 ? _opts_timeoutMs : 500;
-        // Wait for 'close' event (process exit + stdio streams closed)
-        // This is better than 'exit' because it ensures stdio is fully cleaned up
-        const closePromise = new Promise((resolve)=>{
-            let isResolved = false;
-            let wasKilled = false;
-            const resolveOnce = (timedOut)=>{
-                if (isResolved) return;
-                isResolved = true;
-                clearTimeout(timeout);
-                resolve({
-                    timedOut,
-                    killed: wasKilled
-                });
-            };
-            // Set timeout for forceful kill
-            const timeout = setTimeout(()=>{
-                try {
-                    // Check again before SIGKILL
-                    if (child.exitCode === null && !child.killed) {
-                        child.kill('SIGKILL');
-                        wasKilled = true;
-                    }
-                } catch (_) {}
-                // Even if kill fails, resolve
-                resolveOnce(true);
-            }, timeoutMs);
-            // Listen for 'close' event (not 'exit') to wait for stdio close
-            child.once('close', ()=>{
-                resolveOnce(false);
-            });
-            // Also listen for 'error' event in case spawn failed
-            // This prevents promise from hanging forever if process never started
-            child.once('error', ()=>{
-                resolveOnce(false);
+            logger.info(`[${name}] closed (code=${code}, signal=${signal || 'none'})`);
+            resolve({
+                code,
+                signal
             });
-            // Send graceful shutdown signal
+        });
+        child.once('error', (error)=>logger.info(`[${name}] process error: ${error.message}`));
+    });
+    const tree = child.pid && process.platform !== 'win32' ? new OwnedProcessTree(child.pid) : undefined;
+    let closePromise;
+    const performClose = async (signal, timeoutMs)=>{
+        if (!child.pid) {
+            await waitForChildClose(closeEvent, timeoutMs);
+            throw new Error(`Cannot verify shutdown of server '${name}' because it has no process ID`);
+        }
+        let timedOut = false;
+        let killed = false;
+        const errors = [];
+        let stopSucceeded = false;
+        if (opts.stop) {
             try {
-                // Check one more time before killing
-                if (child.exitCode !== null) {
-                    resolveOnce(false);
-                    return;
-                }
-                const killed = child.kill(signal);
-                // If kill returned false, process already exited
-                if (!killed) {
-                    resolveOnce(false);
+                await runStopCommand(opts.stop, cwd, timeoutMs, inheritEnv);
+                stopSucceeded = true;
+            } catch (error) {
+                errors.push(withCause(`Server '${name}' application stop command failed: ${asError(error).message}`, asError(error)));
+            }
+        } else if (child.stdin && !child.stdin.destroyed && !child.stdin.writableEnded) {
+            child.stdin.end();
+        } else if (process.platform !== 'win32') {
+            try {
+                requestProcessSignal(child, signal);
+            } catch (error) {
+                errors.push(withCause(`Server '${name}' cooperative signal failed: ${asError(error).message}`, asError(error)));
+            }
+        }
+        let completion = await waitForCompletion(closeEvent, ()=>isClosed, tree, timeoutMs);
+        if (completion.error) errors.push(withCause(`Could not inspect the owned process tree for server '${name}'`, completion.error));
+        if (!isCompletionSuccessful(completion)) {
+            timedOut = true;
+            if (!opts.stop && child.stdin && process.platform !== 'win32') {
+                try {
+                    requestProcessSignal(child, signal);
+                } catch (error) {
+                    errors.push(withCause(`Server '${name}' cooperative signal failed: ${asError(error).message}`, asError(error)));
                 }
-            } catch (_err) {
-                // If kill throws, process is gone or unreachable
-                resolveOnce(false);
+                completion = await waitForCompletion(closeEvent, ()=>isClosed, tree, timeoutMs);
+                if (completion.error) errors.push(withCause(`Could not inspect the owned process tree for server '${name}'`, completion.error));
+            } else if (!opts.stop && process.platform !== 'win32' && !child.stdin) {
+            // The first signal was sent before waiting for an inherited-stdio HTTP process.
             }
-        });
+        }
+        if (!isCompletionSuccessful(completion)) {
+            const termination = terminateChild(child, tree);
+            killed || (killed = termination.killed);
+            if (termination.error) errors.push(withCause(`Emergency termination failed for server '${name}'`, termination.error));
+            completion = await waitForCompletion(closeEvent, ()=>isClosed, tree, PROCESS_TERMINATION_TIMEOUT_MS);
+            if (!isCompletionSuccessful(completion)) {
+                errors.push(new Error(`Server '${name}' did not close${completion.processGroupEmpty === false ? ' with its POSIX process group' : ''} after emergency termination`));
+            }
+        }
+        if (opts.stop && !stopSucceeded && errors.length === 0) {
+            errors.push(new Error(`Server '${name}' application stop command did not complete successfully`));
+        }
+        if (errors.length > 0) throw new AggregateError(errors, `Server '${name}' shutdown completed with ${errors.length} failure(s)`);
+        return {
+            timedOut,
+            killed
+        };
+    };
+    const close = (signal = 'SIGINT', closeOptions = {})=>{
+        var _closeOptions_timeoutMs;
+        closePromise !== null && closePromise !== void 0 ? closePromise : closePromise = performClose(signal, (_closeOptions_timeoutMs = closeOptions.timeoutMs) !== null && _closeOptions_timeoutMs !== void 0 ? _closeOptions_timeoutMs : DEFAULT_CLOSE_TIMEOUT_MS);
         return closePromise;
     };
     return {
         config: resolvedConfig,
         process: child,
-        close: stop
+        close
     };
 }

package/dist/esm/spawn/spawn-server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/mcp-z/client/src/spawn/spawn-server.ts"],"sourcesContent":["/**\n * Low-level single server spawning utilities.\n * Provides core process spawning with path resolution, environment management, and lifecycle control.\n */\n\nimport { type ChildProcess, type SpawnOptions, type StdioOptions, spawn } from 'child_process';\nimport * as process from 'process';\nimport { logger } from '../utils/logger.ts';\nimport { resolveArgsPaths } from '../utils/path-utils.ts';\n\n/**\n * Options for spawning a single server process.\n * @internal\n */\nexport interface SpawnProcessOptions {\n  /** Server name for logging */\n  name: string;\n  /** Command to execute (e.g., 'node', 'npx') */\n  command: string;\n  /** Command arguments (paths will be resolved relative to cwd) */\n  args?: string[];\n  /** Working directory (must be absolute path) */\n  cwd?: string;\n  /** Additional environment variables (merged with process.env) */\n  env?: Record<string, string>;\n  /** Standard I/O configuration */\n  stdio?: StdioOptions;\n  /** Use shell for command execution (default: false, true on Windows) */\n  shell?: boolean;\n}\n\n/**\n * Handle to a spawned server process.\n * Provides access to the process, resolved config, and lifecycle control.\n * @hidden\n */\nexport interface ServerProcess {\n  /**\n   * The resolved server configuration that was actually used.\n   * Useful for debugging and understanding what was spawned.\n   */\n  config: {\n    name: string;\n    command: string;\n    args: string[];\n    cwd: string;\n    env: Record<string, string>;\n    stdio: StdioOptions;\n    shell: boolean;\n  };\n\n  /**\n   * The spawned child process.\n   */\n  process: ChildProcess;\n\n  /**\n   * Close the server gracefully.\n   * Sends the specified signal (default: SIGINT), then SIGKILL after timeout.\n   *\n   * @param signal - Signal to send (default: SIGINT)\n   * @param opts - Options including timeout\n   * @returns Promise resolving to whether the process timed out and was force-killed\n   */\n  close: (signal?: NodeJS.Signals, opts?: { timeoutMs?: number }) => Promise<{ timedOut: boolean; killed: boolean }>;\n}\n\n/**\n * Normalize environment variables by merging with process.env and filtering undefined values.\n */\nfunction normalizeEnv(env?: Record<string, string>): Record<string, string> {\n  const merged = { ...process.env, ...(env || {}) };\n  const result: Record<string, string> = {};\n  for (const [key, value] of Object.entries(merged)) {\n    if (value !== undefined) {\n      result[key] = value;\n    }\n  }\n  return result;\n}\n\n/**\n * Spawn a single server process with path resolution and environment management.\n *\n * @internal\n * @param opts - Server spawn options\n * @returns ServerProcess handle with resolved config, process, and stop function\n *\n * @example\n * const handle = spawnProcess({\n *   name: 'echo',\n *   command: 'node',\n *   args: ['./bin/server.js', '--port', '3000'],\n *   cwd: '/home/user/project/test/lib/servers/echo',\n *   env: { LOG_LEVEL: 'error' }\n * });\n *\n * // Later...\n * await handle.close();\n */\nexport function spawnProcess(opts: SpawnProcessOptions): ServerProcess {\n  const name = opts.name;\n  const command = opts.command;\n  const cwd = opts.cwd ?? process.cwd();\n  const stdio = opts.stdio ?? 'inherit';\n  const shell = opts.shell ?? process.platform === 'win32';\n\n  // Resolve paths in args relative to the working directory\n  const args = opts.args ? resolveArgsPaths(opts.args, cwd) : [];\n\n  // Merge environment variables\n  const env = normalizeEnv(opts.env);\n\n  // Create resolved config for return value\n  const resolvedConfig = {\n    name,\n    command,\n    args,\n    cwd,\n    env,\n    stdio,\n    shell,\n  };\n\n  // Log spawn operation\n  logger.info(`[${name}] → ${command} ${args.join(' ')}`);\n\n  // Spawn the process\n  const spawnOpts: SpawnOptions = { cwd, env, stdio, shell };\n  const child = spawn(command, args, spawnOpts);\n\n  // Pipe stdio if not inherited\n  if (child.stderr)\n    child.stderr.on('data', (chunk) => {\n      process.stderr.write(chunk);\n    });\n\n  // Attach lifecycle logging\n  child.on('exit', (code, sig) => logger.info(`[${name}] exited (code=${code}, signal=${sig || 'none'})`));\n  child.on('error', (err) => logger.info(`[${name}] process error: ${err.message}`));\n\n  // Create stop function with graceful shutdown\n  const stop = async (signal: NodeJS.Signals = 'SIGINT', opts: { timeoutMs?: number } = {}): Promise<{ timedOut: boolean; killed: boolean }> => {\n    // If already exited, return immediately\n    if (child.exitCode !== null || child.signalCode !== null) {\n      return { timedOut: false, killed: false };\n    }\n\n    const timeoutMs = opts.timeoutMs ?? 500;\n\n    // Wait for 'close' event (process exit + stdio streams closed)\n    // This is better than 'exit' because it ensures stdio is fully cleaned up\n    const closePromise = new Promise<{ timedOut: boolean; killed: boolean }>((resolve) => {\n      let isResolved = false;\n      let wasKilled = false;\n\n      const resolveOnce = (timedOut: boolean) => {\n        if (isResolved) return;\n        isResolved = true;\n        clearTimeout(timeout);\n        resolve({ timedOut, killed: wasKilled });\n      };\n\n      // Set timeout for forceful kill\n      const timeout = setTimeout(() => {\n        try {\n          // Check again before SIGKILL\n          if (child.exitCode === null && !child.killed) {\n            child.kill('SIGKILL');\n            wasKilled = true;\n          }\n        } catch (_) {}\n        // Even if kill fails, resolve\n        resolveOnce(true);\n      }, timeoutMs);\n\n      // Listen for 'close' event (not 'exit') to wait for stdio close\n      child.once('close', () => {\n        resolveOnce(false);\n      });\n\n      // Also listen for 'error' event in case spawn failed\n      // This prevents promise from hanging forever if process never started\n      child.once('error', () => {\n        resolveOnce(false);\n      });\n\n      // Send graceful shutdown signal\n      try {\n        // Check one more time before killing\n        if (child.exitCode !== null) {\n          resolveOnce(false);\n          return;\n        }\n\n        const killed = child.kill(signal);\n        // If kill returned false, process already exited\n        if (!killed) {\n          resolveOnce(false);\n        }\n      } catch (_err) {\n        // If kill throws, process is gone or unreachable\n        resolveOnce(false);\n      }\n    });\n\n    return closePromise;\n  };\n\n  return {\n    config: resolvedConfig,\n    process: child,\n    close: stop,\n  };\n}\n"],"names":["spawn","process","logger","resolveArgsPaths","normalizeEnv","env","merged","result","key","value","Object","entries","undefined","spawnProcess","opts","name","command","cwd","stdio","shell","platform","args","resolvedConfig","info","join","spawnOpts","child","stderr","on","chunk","write","code","sig","err","message","stop","signal","exitCode","signalCode","timedOut","killed","timeoutMs","closePromise","Promise","resolve","isResolved","wasKilled","resolveOnce","clearTimeout","timeout","setTimeout","kill","_","once","_err","config","close"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/mcp-z/client/src/spawn/spawn-server.ts"],"sourcesContent":["/**\n * Low-level single server spawning utilities.\n * Provides core process spawning with path resolution, environment management, and lifecycle control.\n */\n\nimport type { ChildProcess, StdioOptions } from 'child_process';\nimport crossSpawn from 'cross-spawn';\nimport * as path from 'path';\nimport * as process from 'process';\nimport type { StopCommandConfig } from '../types.ts';\nimport { logger } from '../utils/logger.ts';\nimport { resolveArgsPaths } from '../utils/path-utils.ts';\nimport { OwnedProcessTree } from './owned-process-tree.ts';\n\nconst DEFAULT_CLOSE_TIMEOUT_MS = 5000;\nconst PROCESS_TERMINATION_TIMEOUT_MS = 5000;\nconst PROCESS_POLL_INTERVAL_MS = 25;\n\ninterface ProcessCloseEvent {\n  code: number | null;\n  signal: NodeJS.Signals | null;\n}\n\ninterface ProcessCompletion {\n  closed: boolean;\n  processGroupEmpty?: boolean;\n  error?: Error;\n}\n\n/**\n * Options for spawning a single server process.\n * @internal\n */\nexport interface SpawnProcessOptions {\n  /** Server name for logging */\n  name: string;\n  /** Command to execute (e.g., 'node', 'npx') */\n  command: string;\n  /** Command arguments (paths will be resolved relative to cwd) */\n  args?: string[];\n  /** Working directory (must be absolute path) */\n  cwd?: string;\n  /** Additional environment variables (merged with process.env) */\n  env?: Record<string, string>;\n  /** Whether to add process.env to env; registry callers provide a pre-merged environment */\n  inheritEnv?: boolean;\n  /** Standard I/O configuration */\n  stdio?: StdioOptions;\n  /** Application-specific shutdown command for an owned HTTP server */\n  stop?: StopCommandConfig;\n}\n\n/**\n * Handle to a spawned server process.\n * Provides access to the process, resolved config, and lifecycle control.\n * @hidden\n */\nexport interface ServerProcess {\n  config: {\n    name: string;\n    command: string;\n    args: string[];\n    cwd: string;\n    env: Record<string, string>;\n    stdio: StdioOptions;\n    shell: false;\n  };\n  process: ChildProcess;\n  close: (signal?: NodeJS.Signals, opts?: { timeoutMs?: number }) => Promise<{ timedOut: boolean; killed: boolean }>;\n}\n\nfunction normalizeEnv(env?: Record<string, string>, inheritEnv = true): Record<string, string> {\n  const merged = { ...(inheritEnv ? process.env : {}), ...(env || {}) };\n  const result: Record<string, string> = {};\n  for (const [key, value] of Object.entries(merged)) {\n    if (value !== undefined) result[key] = value;\n  }\n  return result;\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nasync function waitForCompletion(closeEvent: Promise<ProcessCloseEvent>, childClosed: () => boolean, tree: OwnedProcessTree | undefined, timeoutMs: number): Promise<ProcessCompletion> {\n  if (!tree) return { closed: (await waitForChildClose(closeEvent, timeoutMs)) !== undefined };\n\n  const deadline = Date.now() + timeoutMs;\n  let lastError: Error | undefined;\n  while (true) {\n    let processGroupEmpty = false;\n    try {\n      processGroupEmpty = tree.isEmpty();\n      lastError = undefined;\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n    }\n    const closed = childClosed();\n    if (closed && processGroupEmpty) return { closed, processGroupEmpty };\n    if (Date.now() >= deadline) return { closed, processGroupEmpty, ...(lastError && { error: lastError }) };\n    await delay(Math.min(PROCESS_POLL_INTERVAL_MS, Math.max(1, deadline - Date.now())));\n  }\n}\n\nfunction isCompletionSuccessful(completion: ProcessCompletion): boolean {\n  return completion.closed && completion.processGroupEmpty !== false;\n}\n\nfunction terminateChild(child: ChildProcess, tree: OwnedProcessTree | undefined): { killed: boolean; error?: Error } {\n  if (tree) return tree.terminate();\n  try {\n    return { killed: child.kill('SIGKILL') };\n  } catch (error) {\n    return { killed: false, error: asError(error) };\n  }\n}\n\nfunction waitForChildClose(closeEvent: Promise<ProcessCloseEvent>, timeoutMs: number): Promise<ProcessCloseEvent | undefined> {\n  let timer: NodeJS.Timeout | undefined;\n  return Promise.race([\n    closeEvent,\n    new Promise<undefined>((resolve) => {\n      timer = setTimeout(() => resolve(undefined), timeoutMs);\n    }),\n  ]).finally(() => {\n    if (timer) clearTimeout(timer);\n  });\n}\n\nfunction requestProcessSignal(child: ChildProcess, signal: NodeJS.Signals): void {\n  if (!child.pid) throw new Error('Cannot request cooperative shutdown because the server has no process ID');\n  if (process.platform === 'win32') throw new Error('POSIX process signals are not available on Windows');\n  try {\n    process.kill(-child.pid, signal);\n  } catch (error) {\n    if (!(error instanceof Error && 'code' in error && error.code === 'ESRCH')) throw error;\n  }\n}\n\nfunction asError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error));\n}\n\nfunction withCause(message: string, cause: Error): Error {\n  return new Error(message, { cause });\n}\n\nasync function runStopCommand(command: StopCommandConfig, cwd: string, timeoutMs: number, inheritEnv: boolean): Promise<void> {\n  const stopCwd = command.cwd ? path.resolve(cwd, command.cwd) : cwd;\n  const env = normalizeEnv(command.env, inheritEnv);\n  const args = command.args ? resolveArgsPaths(command.args, stopCwd) : [];\n  const child = crossSpawn(command.command, args, {\n    cwd: stopCwd,\n    env,\n    stdio: 'ignore',\n    shell: false,\n    detached: process.platform !== 'win32',\n    windowsHide: true,\n  });\n  let spawnError: Error | undefined;\n  let closed = false;\n  let closeEventValue: ProcessCloseEvent | undefined;\n  const closeEvent = new Promise<ProcessCloseEvent>((resolve) => {\n    child.once('error', (error) => {\n      spawnError = error;\n    });\n    child.once('close', (code, signal) => {\n      closed = true;\n      closeEventValue = { code, signal };\n      resolve({ code, signal });\n    });\n  });\n\n  if (!child.pid) {\n    const result = await waitForChildClose(closeEvent, timeoutMs);\n    if (!result) throw new Error(`Stop command did not start or close within ${timeoutMs}ms`);\n    if (spawnError) throw withCause(`Stop command could not be started: ${spawnError.message}`, spawnError);\n  }\n\n  const tree = child.pid && process.platform !== 'win32' ? new OwnedProcessTree(child.pid) : undefined;\n  const completion = await waitForCompletion(closeEvent, () => closed, tree, timeoutMs);\n  if (!isCompletionSuccessful(completion)) {\n    const termination = terminateChild(child, tree);\n    const afterTermination = await waitForCompletion(closeEvent, () => closed, tree, PROCESS_TERMINATION_TIMEOUT_MS);\n    const details = [completion.error?.message, termination.error?.message].filter(Boolean).join('; ');\n    const reason = `Stop command exceeded ${timeoutMs}ms and required emergency process termination`;\n    const remaining = !isCompletionSuccessful(afterTermination) ? '; stop command or its POSIX process group remained alive' : '';\n    throw new Error(`${reason}${details ? `: ${details}` : ''}${remaining}`);\n  }\n\n  if (spawnError) throw withCause(`Stop command could not be started: ${spawnError.message}`, spawnError);\n  if (closeEventValue && (closeEventValue.code !== 0 || closeEventValue.signal !== null)) {\n    throw new Error(`Stop command exited with code ${closeEventValue.code ?? 'unknown'}${closeEventValue.signal ? ` (signal ${closeEventValue.signal})` : ''}`);\n  }\n}\n\n/**\n * Spawn a single server process with path resolution and environment management.\n *\n * @internal\n * @param opts - Server spawn options\n * @returns ServerProcess handle with resolved config and lifecycle control\n */\nexport function spawnProcess(opts: SpawnProcessOptions): ServerProcess {\n  const name = opts.name;\n  const command = opts.command;\n  const cwd = opts.cwd ?? process.cwd();\n  const stdio = opts.stdio ?? 'inherit';\n  const args = opts.args ? resolveArgsPaths(opts.args, cwd) : [];\n  const inheritEnv = opts.inheritEnv ?? true;\n  const env = normalizeEnv(opts.env, inheritEnv);\n  const resolvedConfig = { name, command, args, cwd, env, stdio, shell: false as const };\n\n  logger.info(`[${name}] → ${command} ${args.join(' ')}`);\n  const child = crossSpawn(command, args, {\n    cwd,\n    env,\n    stdio,\n    shell: false,\n    detached: process.platform !== 'win32',\n    windowsHide: true,\n  });\n\n  if (child.stderr) child.stderr.on('data', (chunk) => process.stderr.write(chunk));\n\n  let isClosed = false;\n  let _closeEventValue: ProcessCloseEvent | undefined;\n  const closeEvent = new Promise<ProcessCloseEvent>((resolve) => {\n    child.once('close', (code, signal) => {\n      isClosed = true;\n      _closeEventValue = { code, signal };\n      logger.info(`[${name}] closed (code=${code}, signal=${signal || 'none'})`);\n      resolve({ code, signal });\n    });\n    child.once('error', (error) => logger.info(`[${name}] process error: ${error.message}`));\n  });\n  const tree = child.pid && process.platform !== 'win32' ? new OwnedProcessTree(child.pid) : undefined;\n  let closePromise: Promise<{ timedOut: boolean; killed: boolean }> | undefined;\n\n  const performClose = async (signal: NodeJS.Signals, timeoutMs: number): Promise<{ timedOut: boolean; killed: boolean }> => {\n    if (!child.pid) {\n      await waitForChildClose(closeEvent, timeoutMs);\n      throw new Error(`Cannot verify shutdown of server '${name}' because it has no process ID`);\n    }\n\n    let timedOut = false;\n    let killed = false;\n    const errors: Error[] = [];\n    let stopSucceeded = false;\n\n    if (opts.stop) {\n      try {\n        await runStopCommand(opts.stop, cwd, timeoutMs, inheritEnv);\n        stopSucceeded = true;\n      } catch (error) {\n        errors.push(withCause(`Server '${name}' application stop command failed: ${asError(error).message}`, asError(error)));\n      }\n    } else if (child.stdin && !child.stdin.destroyed && !child.stdin.writableEnded) {\n      child.stdin.end();\n    } else if (process.platform !== 'win32') {\n      try {\n        requestProcessSignal(child, signal);\n      } catch (error) {\n        errors.push(withCause(`Server '${name}' cooperative signal failed: ${asError(error).message}`, asError(error)));\n      }\n    }\n\n    let completion = await waitForCompletion(closeEvent, () => isClosed, tree, timeoutMs);\n    if (completion.error) errors.push(withCause(`Could not inspect the owned process tree for server '${name}'`, completion.error));\n\n    if (!isCompletionSuccessful(completion)) {\n      timedOut = true;\n      if (!opts.stop && child.stdin && process.platform !== 'win32') {\n        try {\n          requestProcessSignal(child, signal);\n        } catch (error) {\n          errors.push(withCause(`Server '${name}' cooperative signal failed: ${asError(error).message}`, asError(error)));\n        }\n        completion = await waitForCompletion(closeEvent, () => isClosed, tree, timeoutMs);\n        if (completion.error) errors.push(withCause(`Could not inspect the owned process tree for server '${name}'`, completion.error));\n      } else if (!opts.stop && process.platform !== 'win32' && !child.stdin) {\n        // The first signal was sent before waiting for an inherited-stdio HTTP process.\n      }\n    }\n\n    if (!isCompletionSuccessful(completion)) {\n      const termination = terminateChild(child, tree);\n      killed ||= termination.killed;\n      if (termination.error) errors.push(withCause(`Emergency termination failed for server '${name}'`, termination.error));\n      completion = await waitForCompletion(closeEvent, () => isClosed, tree, PROCESS_TERMINATION_TIMEOUT_MS);\n      if (!isCompletionSuccessful(completion)) {\n        errors.push(new Error(`Server '${name}' did not close${completion.processGroupEmpty === false ? ' with its POSIX process group' : ''} after emergency termination`));\n      }\n    }\n\n    if (opts.stop && !stopSucceeded && errors.length === 0) {\n      errors.push(new Error(`Server '${name}' application stop command did not complete successfully`));\n    }\n    if (errors.length > 0) throw new AggregateError(errors, `Server '${name}' shutdown completed with ${errors.length} failure(s)`);\n    return { timedOut, killed };\n  };\n\n  const close = (signal: NodeJS.Signals = 'SIGINT', closeOptions: { timeoutMs?: number } = {}): Promise<{ timedOut: boolean; killed: boolean }> => {\n    closePromise ??= performClose(signal, closeOptions.timeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS);\n    return closePromise;\n  };\n\n  return { config: resolvedConfig, process: child, close };\n}\n"],"names":["crossSpawn","path","process","logger","resolveArgsPaths","OwnedProcessTree","DEFAULT_CLOSE_TIMEOUT_MS","PROCESS_TERMINATION_TIMEOUT_MS","PROCESS_POLL_INTERVAL_MS","normalizeEnv","env","inheritEnv","merged","result","key","value","Object","entries","undefined","delay","ms","Promise","resolve","setTimeout","waitForCompletion","closeEvent","childClosed","tree","timeoutMs","closed","waitForChildClose","deadline","Date","now","lastError","processGroupEmpty","isEmpty","error","Error","String","Math","min","max","isCompletionSuccessful","completion","terminateChild","child","terminate","killed","kill","asError","timer","race","finally","clearTimeout","requestProcessSignal","signal","pid","platform","code","withCause","message","cause","runStopCommand","command","cwd","stopCwd","args","stdio","shell","detached","windowsHide","spawnError","closeEventValue","once","termination","afterTermination","details","filter","Boolean","join","reason","remaining","spawnProcess","opts","name","resolvedConfig","info","stderr","on","chunk","write","isClosed","_closeEventValue","closePromise","performClose","timedOut","errors","stopSucceeded","stop","push","stdin","destroyed","writableEnded","end","length","AggregateError","close","closeOptions","config"],"mappings":"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"}

package/dist/esm/spawn/spawn-servers.d.ts

@@ -4,10 +4,12 @@
  * Supports stdio, http, and ws transports.
  * Implements Claude Code-compatible configuration with start extension support.
  */
+import type { VersionNegotiationOptions } from '@modelcontextprotocol/client';
 import { type ManagedClient } from '../client-helpers.js';
-import { connectMcpClient } from '../connection/connect-client.js';
+import type { DcrAuthenticatorOptions } from '../dcr/dcr-authenticator.js';
 import { type SearchOptions, type SearchResponse } from '../search/index.js';
 import type { McpServerEntry } from '../types.js';
+import { type Logger } from '../utils/logger.js';
 import { type ServerProcess } from './spawn-server.js';
 /**
  * Servers configuration type - a map of server names to their configurations.
@@ -45,16 +47,15 @@ export interface CreateServerRegistryOptions {
  * Result of closing the registry.
  */
 export interface CloseResult {
-    /** Whether any process timed out during shutdown */
+    /** Whether any owned process exceeded its cooperative shutdown timeout */
     timedOut: boolean;
-    /** Number of processes that were force-killed */
+    /** Number of owned processes that required emergency force termination */
     killedCount: number;
 }
 /**
  * A registry of spawned MCP servers with connection management.
  * Provides access to individual server handles, connection management, and collection-wide close.
  */
-type RegistryConnectOptions = Parameters<typeof connectMcpClient>[2];
 export interface ServerRegistry {
     /**
      * The resolved servers configuration that was used.
@@ -76,16 +77,26 @@ export interface ServerRegistry {
      * The connected client is automatically tracked for close.
      *
      * @param name - Server name from configuration
+     * @param options - Authentication, logging, and protocol negotiation options
      * @returns Connected MCP SDK Client
      */
-    connect: (name: string, options?: RegistryConnectOptions) => Promise<ManagedClient>;
+    connect: (name: string, options?: {
+        dcrAuthenticator?: Partial<DcrAuthenticatorOptions>;
+        logger?: Logger;
+        versionNegotiation?: VersionNegotiationOptions;
+    }) => Promise<ManagedClient>;
     /**
      * Close all clients and servers gracefully.
-     * First closes all tracked clients, then sends the specified signal to all server processes.
+     * Stops new connections, waits for in-flight connections, closes tracked clients, and then
+     * stops only processes owned by this registry. Stdio children receive stdin EOF first
+     * and the requested signal on POSIX if they remain open; owned HTTP children may use
+     * their configured application-specific stop command. POSIX cleanup tracks the detached
+     * process group; Windows can terminate only the direct child and cannot verify descendants.
+     * Cleanup failures are reported after every owned resource has been attempted.
      *
      * @param signal - Signal to send to processes (default: SIGINT)
      * @param opts - Options including timeout
-     * @returns Promise resolving to whether any process timed out and how many were force-killed
+     * @returns Promise resolving to whether any process timed out and how many required emergency force termination
      */
     close: (signal?: NodeJS.Signals, opts?: {
         timeoutMs?: number;
@@ -148,4 +159,3 @@ export interface ServerRegistry {
  * // Auto-disposed when scope exits
  */
 export declare function createServerRegistry(serversConfig: ServersConfig, options?: CreateServerRegistryOptions): ServerRegistry;
-export {};