codebase-onboarder 0.6.0 → 0.7.0

package/server/mcp/runner.js

@@ -11,32 +11,26 @@
 // shell, no user-supplied arguments — the one thing this runner executes is a
 // path built from this repository's own directory, so there is no injection
 // surface here even though the tool server can read any folder it is pointed at.
-
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-
 import { mcpStatus } from './tools.js';
-
 const here = path.dirname(fileURLToPath(import.meta.url));
 // server/mcp/ -> server/ -> repository root
 export const REPO_ROOT = path.resolve(here, '..', '..');
 export const ENTRY = path.join(here, 'standalone.js');
-
 // How long to wait for a graceful stop before killing. SIGTERM lets Node finish
 // what it is doing; a hard kill would be an acceptable fallback, but only after
 // this long, because a scan in progress deserves the chance to finish.
 const STOP_GRACE_MS = 1500;
-
 // The command a client is configured with, and the only one this file will ever
 // run. It is a function rather than a constant string in a template because a
 // client config is a promise about what is actually happening: the path in the
 // README, the path in the copy box, and the argv the runner builds all have to be
 // the same string, and this is the one place it is written.
 export function mcpCommand() {
-  return path.relative(REPO_ROOT, ENTRY);
+    return path.relative(REPO_ROOT, ENTRY);
 }
-
 // The absolute form, for anything a client will execute.
 //
 // The runner can launch `server/mcp/standalone.js` relative to `cwd` because it
@@ -45,234 +39,230 @@ export function mcpCommand() {
 // that fails only after it has been pasted somewhere real. The copy box and the
 // README therefore both use this, and only the runner gets the relative one.
 export function mcpEntryPoint() {
-  return ENTRY;
+    return ENTRY;
 }
-
 //
 // `override` exists so a test can substitute a command — one that exits at once,
 // one that answers the handshake wrong — without the production path growing a
 // test-only branch. It is the whole argument or nothing: a half-overridden config
 // would spawn something that is neither the real server nor the fake.
-
 export function mcpConfig(override) {
-  if (override) {
+    if (override) {
+        return {
+            command: override.command,
+            args: override.args || [],
+            cwd: override.cwd || REPO_ROOT,
+        };
+    }
     return {
-      command: override.command,
-      args: override.args || [],
-      cwd: override.cwd || REPO_ROOT,
+        command: process.execPath,
+        args: [ENTRY],
+        cwd: REPO_ROOT,
     };
-  }
-  return {
-    command: process.execPath,
-    args: [ENTRY],
-    cwd: REPO_ROOT,
-  };
 }
-
 export class McpRunner {
-  get running() {
-    return this.state === 'running' || this.state === 'starting';
-  }
-
-  note(line) {
-    if (!line) return;
-    const entry = { at: Date.now(), line };
-    this.log.push(entry);
-    // Bounded, because this is a status panel, not a log file.
-    if (this.log.length > 100) this.log.shift();
-    this.onLog(entry);
-  }
-
-  // `command`/`args`/`cwd` are the whole argv override, handed straight to
-  // `mcpConfig`. Accepting them flat rather than as one nested object is what
-  // every caller naturally reaches for — `new McpRunner({ command, args })` — and
-  // the tests need it to point the runner at a fake child. The runner itself has
-  // no idea what it is launching: a runner that knew would be a second place
-  // where the entry point is written down, and the two could drift.
-  constructor({ onLog, command, args, cwd } = {}) {
-    this.commandOverride = command
-      ? { command, args: args || [], ...(cwd ? { cwd } : {}) }
-      : null;
-    this.child = null;
-    this.state = 'stopped'; // stopped | starting | running | stopping
-    this.startedAt = null;
-    this.lastError = null;
-    // The tail of the child's output, kept for the UI. An MCP child that dies
-    // usually says why just before it goes, and "it stopped" with no reason is
-    // the single most annoying thing a status panel can tell you.
-    this.log = [];
-    this.onLog = onLog || (() => {});
-  }
-
-  async start() {
-    if (this.running) return this.status();
-    this.state = 'starting';
-    this.lastError = null;
-    this.log = [];
-
-    // Built from the same function the config box shows. If those could differ,
-    // the button would be reporting on a different server than the one a client
-    // launches — which is worse than having no button.
-    const cfg = mcpConfig(this.commandOverride);
-    const child = spawn(cfg.command, cfg.args, {
-      cwd: cfg.cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, ONBOARDER_MCP: '1', LOG_LEVEL: 'warn' },
-      // No shell: the command is a fixed argv, and a shell would only add a way
-      // for something to be interpreted.
-      shell: false,
-    });
-    this.child = child;
-
-    child.stdout.setEncoding('utf8');
-    child.stderr.setEncoding('utf8');
-    // Only stderr is a log. stdout is the MCP protocol stream: logging it would
-    // fill the panel with JSON-RPC frames, and the one that matters — the
-    // handshake reply — is consumed by `handshake` below. The stream is drained
-    // regardless, because a pipe nobody reads eventually blocks the writer.
-    child.stdout.on('data', () => {});
-    child.stderr.on('data', (chunk) => this.note(String(chunk).trimEnd()));
-
-    const exited = new Promise((resolve) => {
-      child.once('exit', (code, signal) => {
-        const wasStopping = this.state === 'stopping';
+    commandOverride;
+    child;
+    state;
+    startedAt;
+    lastError;
+    log;
+    onLog;
+    get running() {
+        return this.state === 'running' || this.state === 'starting';
+    }
+    note(line) {
+        if (!line)
+            return;
+        const entry = { at: Date.now(), line };
+        this.log.push(entry);
+        // Bounded, because this is a status panel, not a log file.
+        if (this.log.length > 100)
+            this.log.shift();
+        this.onLog(entry);
+    }
+    // `command`/`args`/`cwd` are the whole argv override, handed straight to
+    // `mcpConfig`. Accepting them flat rather than as one nested object is what
+    // every caller naturally reaches for — `new McpRunner({ command, args })` — and
+    // the tests need it to point the runner at a fake child. The runner itself has
+    // no idea what it is launching: a runner that knew would be a second place
+    // where the entry point is written down, and the two could drift.
+    constructor({ onLog, command, args, cwd } = {}) {
+        this.commandOverride = command
+            ? { command, args: args || [], ...(cwd ? { cwd } : {}) }
+            : null;
         this.child = null;
-        this.state = 'stopped';
+        this.state = 'stopped'; // stopped | starting | running | stopping
         this.startedAt = null;
-        if (!wasStopping) {
-          this.lastError = signal
-            ? `Stopped unexpectedly (${signal}).`
-            : `Stopped unexpectedly (exit code ${code}).`;
-          this.note(this.lastError);
+        this.lastError = null;
+        // The tail of the child's output, kept for the UI. An MCP child that dies
+        // usually says why just before it goes, and "it stopped" with no reason is
+        // the single most annoying thing a status panel can tell you.
+        this.log = [];
+        this.onLog = onLog || ((..._args) => { });
+    }
+    async start() {
+        if (this.running)
+            return this.status();
+        this.state = 'starting';
+        this.lastError = null;
+        this.log = [];
+        // Built from the same function the config box shows. If those could differ,
+        // the button would be reporting on a different server than the one a client
+        // launches — which is worse than having no button.
+        const cfg = mcpConfig(this.commandOverride);
+        const child = spawn(cfg.command, cfg.args, {
+            cwd: cfg.cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, ONBOARDER_MCP: '1', LOG_LEVEL: 'warn' },
+            // No shell: the command is a fixed argv, and a shell would only add a way
+            // for something to be interpreted.
+            shell: false,
+        });
+        this.child = child;
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        // Only stderr is a log. stdout is the MCP protocol stream: logging it would
+        // fill the panel with JSON-RPC frames, and the one that matters — the
+        // handshake reply — is consumed by `handshake` below. The stream is drained
+        // regardless, because a pipe nobody reads eventually blocks the writer.
+        child.stdout.on('data', (..._args) => { });
+        child.stderr.on('data', (chunk) => this.note(String(chunk).trimEnd()));
+        const exited = new Promise((resolve) => {
+            child.once('exit', (code, signal) => {
+                const wasStopping = this.state === 'stopping';
+                this.child = null;
+                this.state = 'stopped';
+                this.startedAt = null;
+                if (!wasStopping) {
+                    this.lastError = signal
+                        ? `Stopped unexpectedly (${signal}).`
+                        : `Stopped unexpectedly (exit code ${code}).`;
+                    this.note(this.lastError);
+                }
+                resolve({ code, signal });
+            });
+        });
+        child.once('error', (err) => {
+            this.lastError = `Could not start: ${err.message}`;
+            this.state = 'stopped';
+            this.child = null;
+            this.note(this.lastError);
+        });
+        // A handshake proves the server is not merely spawned but actually answering
+        // MCP. "running" that means the process exists is how a broken server ends up
+        // looking healthy in the UI.
+        const ok = await this.handshake(exited);
+        if (ok) {
+            this.state = 'running';
+            this.startedAt = Date.now();
+            this.note('MCP server ready on stdio.');
+        }
+        else if (this.child) {
+            await this.stop();
         }
-        resolve({ code, signal });
-      });
-    });
-
-    child.once('error', (err) => {
-      this.lastError = `Could not start: ${err.message}`;
-      this.state = 'stopped';
-      this.child = null;
-      this.note(this.lastError);
-    });
-
-    // A handshake proves the server is not merely spawned but actually answering
-    // MCP. "running" that means the process exists is how a broken server ends up
-    // looking healthy in the UI.
-    const ok = await this.handshake(exited);
-    if (ok) {
-      this.state = 'running';
-      this.startedAt = Date.now();
-      this.note('MCP server ready on stdio.');
-    } else if (this.child) {
-      await this.stop();
-    } else {
-      this.state = 'stopped';
+        else {
+            this.state = 'stopped';
+        }
+        return this.status();
     }
-    return this.status();
-  }
-
-  // The MCP handshake, spoken to our own child: initialize, then the
-  // `notifications/initialized` the spec requires before ordinary traffic.
-  async handshake(exited) {
-    const child = this.child;
-    if (!child) return false;
-
-    return new Promise((resolve) => {
-      let buffer = '';
-      let settled = false;
-      const finish = (ok) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        child.stdout.off('data', onData);
-        // Resolve now, not on exit. The child is *supposed* to stay running, so
-        // waiting for it to exit would mean this promise only ever settled when
-        // something had already gone wrong.
-        resolve(ok && this.child !== null);
-      };
-      const onData = (chunk) => {
-        buffer += chunk;
-        let nl;
-        while ((nl = buffer.indexOf('\n')) !== -1) {
-          const line = buffer.slice(0, nl).trim();
-          buffer = buffer.slice(nl + 1);
-          if (!line) continue;
-          try {
-            const msg = JSON.parse(line);
-            if (msg?.id === 'onboarder-probe' && msg.result?.serverInfo?.name === 'onboarder') {
-              child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
-              finish(true);
-              return;
-            }
-          } catch {
-            // A line that is not JSON during the handshake is a bug elsewhere —
-            // something wrote to stdout that should not have. Keep reading: the
-            // real initialize reply may still arrive.
-          }
+    // The MCP handshake, spoken to our own child: initialize, then the
+    // `notifications/initialized` the spec requires before ordinary traffic.
+    async handshake(exited) {
+        const child = this.child;
+        if (!child)
+            return false;
+        return new Promise((resolve) => {
+            let buffer = '';
+            let settled = false;
+            const finish = (ok) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                child.stdout.off('data', onData);
+                // Resolve now, not on exit. The child is *supposed* to stay running, so
+                // waiting for it to exit would mean this promise only ever settled when
+                // something had already gone wrong.
+                resolve(ok && this.child !== null);
+            };
+            const onData = (chunk) => {
+                buffer += chunk;
+                let nl;
+                while ((nl = buffer.indexOf('\n')) !== -1) {
+                    const line = buffer.slice(0, nl).trim();
+                    buffer = buffer.slice(nl + 1);
+                    if (!line)
+                        continue;
+                    try {
+                        const msg = JSON.parse(line);
+                        if (msg?.id === 'onboarder-probe' && msg.result?.serverInfo?.name === 'onboarder') {
+                            child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+                            finish(true);
+                            return;
+                        }
+                    }
+                    catch {
+                        // A line that is not JSON during the handshake is a bug elsewhere —
+                        // something wrote to stdout that should not have. Keep reading: the
+                        // real initialize reply may still arrive.
+                    }
+                }
+            };
+            const timer = setTimeout(() => {
+                this.lastError = 'The MCP server did not answer its handshake within 5s.';
+                this.note(this.lastError);
+                finish(false);
+            }, 5000);
+            child.stdout.on('data', onData);
+            // If the child dies first, do not wait out the full timeout.
+            exited.then(() => finish(false));
+            child.stdin.write(JSON.stringify({
+                jsonrpc: '2.0',
+                id: 'onboarder-probe',
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2025-06-18',
+                    capabilities: {},
+                    clientInfo: { name: 'onboarder-ui', version: '1.0.0' },
+                },
+            }) + '\n');
+        });
+    }
+    async stop() {
+        const child = this.child;
+        if (!child) {
+            this.state = 'stopped';
+            return this.status();
         }
-      };
-
-      const timer = setTimeout(() => {
-        this.lastError = 'The MCP server did not answer its handshake within 5s.';
-        this.note(this.lastError);
-        finish(false);
-      }, 5000);
-
-      child.stdout.on('data', onData);
-      // If the child dies first, do not wait out the full timeout.
-      exited.then(() => finish(false));
-
-      child.stdin.write(JSON.stringify({
-        jsonrpc: '2.0',
-        id: 'onboarder-probe',
-        method: 'initialize',
-        params: {
-          protocolVersion: '2025-06-18',
-          capabilities: {},
-          clientInfo: { name: 'onboarder-ui', version: '1.0.0' },
-        },
-      }) + '\n');
-    });
-  }
-
-  async stop() {
-    const child = this.child;
-    if (!child) {
-      this.state = 'stopped';
-      return this.status();
+        this.state = 'stopping';
+        // Closing stdin is the polite shutdown: `serveMcp` drains what is queued and
+        // lets the loop empty, so a request in flight gets its answer.
+        const exited = new Promise((resolve) => child.once('exit', resolve));
+        child.stdin.end();
+        const timer = setTimeout(() => child.kill('SIGKILL'), STOP_GRACE_MS);
+        await exited;
+        clearTimeout(timer);
+        this.child = null;
+        this.state = 'stopped';
+        this.startedAt = null;
+        this.note('MCP server stopped.');
+        return this.status();
+    }
+    status() {
+        return {
+            ...mcpStatus(),
+            state: this.state,
+            running: this.running,
+            pid: this.child?.pid ?? null,
+            startedAt: this.startedAt,
+            uptimeMs: this.startedAt ? Date.now() - this.startedAt : 0,
+            lastError: this.lastError,
+            log: this.log.slice(-20),
+        };
     }
-    this.state = 'stopping';
-
-    // Closing stdin is the polite shutdown: `serveMcp` drains what is queued and
-    // lets the loop empty, so a request in flight gets its answer.
-    const exited = new Promise((resolve) => child.once('exit', resolve));
-    child.stdin.end();
-    const timer = setTimeout(() => child.kill('SIGKILL'), STOP_GRACE_MS);
-
-    await exited;
-    clearTimeout(timer);
-    this.child = null;
-    this.state = 'stopped';
-    this.startedAt = null;
-    this.note('MCP server stopped.');
-    return this.status();
-  }
-
-  status() {
-    return {
-      ...mcpStatus(),
-      state: this.state,
-      running: this.running,
-      pid: this.child?.pid ?? null,
-      startedAt: this.startedAt,
-      uptimeMs: this.startedAt ? Date.now() - this.startedAt : 0,
-      lastError: this.lastError,
-      log: this.log.slice(-20),
-    };
-  }
 }
-
 export function createMcpRunner(opts) {
-  return new McpRunner(opts);
+    return new McpRunner(opts);
 }
+//# sourceMappingURL=runner.js.map

package/server/mcp/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/server/mcp/runner.ts"],"names":[],"mappings":"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","sourcesContent":["// The process runner. The HTTP server owns one of these; the topbar button calls\n// `start` and `stop` on it.\n//\n// Why a child process rather than an HTTP endpoint: the MCP stdio transport *is*\n// the contract. A client config points at a command and speaks JSON-RPC to its\n// stdin/stdout. There is no port to connect to, and nothing to authenticate,\n// which is why this transport is the right one for a local-first tool and why it\n// must stay local if it is ever exposed at all.\n//\n// The child is deliberately plain: `node server/mcp/standalone.js`. No `npx`, no\n// shell, no user-supplied arguments — the one thing this runner executes is a\n// path built from this repository's own directory, so there is no injection\n// surface here even though the tool server can read any folder it is pointed at.\n\nimport { spawn } from 'node:child_process';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nimport { mcpStatus } from './tools.js';\n\nconst here = path.dirname(fileURLToPath(import.meta.url));\n// server/mcp/ -> server/ -> repository root\nexport const REPO_ROOT = path.resolve(here, '..', '..');\nexport const ENTRY = path.join(here, 'standalone.js');\n\n// How long to wait for a graceful stop before killing. SIGTERM lets Node finish\n// what it is doing; a hard kill would be an acceptable fallback, but only after\n// this long, because a scan in progress deserves the chance to finish.\nconst STOP_GRACE_MS = 1500;\n\n// The command a client is configured with, and the only one this file will ever\n// run. It is a function rather than a constant string in a template because a\n// client config is a promise about what is actually happening: the path in the\n// README, the path in the copy box, and the argv the runner builds all have to be\n// the same string, and this is the one place it is written.\nexport function mcpCommand() {\n  return path.relative(REPO_ROOT, ENTRY);\n}\n\n// The absolute form, for anything a client will execute.\n//\n// The runner can launch `server/mcp/standalone.js` relative to `cwd` because it\n// sets `cwd` itself. A client cannot: it spawns the command wherever the user's\n// harness happens to live, so a relative path in a copied config is a command\n// that fails only after it has been pasted somewhere real. The copy box and the\n// README therefore both use this, and only the runner gets the relative one.\nexport function mcpEntryPoint() {\n  return ENTRY;\n}\n\n//\n// `override` exists so a test can substitute a command — one that exits at once,\n// one that answers the handshake wrong — without the production path growing a\n// test-only branch. It is the whole argument or nothing: a half-overridden config\n// would spawn something that is neither the real server nor the fake.\n\nexport function mcpConfig(override) {\n  if (override) {\n    return {\n      command: override.command,\n      args: override.args || [],\n      cwd: override.cwd || REPO_ROOT,\n    };\n  }\n  return {\n    command: process.execPath,\n    args: [ENTRY],\n    cwd: REPO_ROOT,\n  };\n}\n\nexport class McpRunner {\n  commandOverride: any;\n  child: any;\n  state: string;\n  startedAt: any;\n  lastError: string;\n  log: any[];\n  onLog: any;\n\n  get running() {\n    return this.state === 'running' || this.state === 'starting';\n  }\n\n  note(line) {\n    if (!line) return;\n    const entry = { at: Date.now(), line };\n    this.log.push(entry);\n    // Bounded, because this is a status panel, not a log file.\n    if (this.log.length > 100) this.log.shift();\n    this.onLog(entry);\n  }\n\n  // `command`/`args`/`cwd` are the whole argv override, handed straight to\n  // `mcpConfig`. Accepting them flat rather than as one nested object is what\n  // every caller naturally reaches for — `new McpRunner({ command, args })` — and\n  // the tests need it to point the runner at a fake child. The runner itself has\n  // no idea what it is launching: a runner that knew would be a second place\n  // where the entry point is written down, and the two could drift.\n  constructor({ onLog, command, args, cwd }: Record<string, any> = {}) {\n    this.commandOverride = command\n      ? { command, args: args || [], ...(cwd ? { cwd } : {}) }\n      : null;\n    this.child = null;\n    this.state = 'stopped'; // stopped | starting | running | stopping\n    this.startedAt = null;\n    this.lastError = null;\n    // The tail of the child's output, kept for the UI. An MCP child that dies\n    // usually says why just before it goes, and \"it stopped\" with no reason is\n    // the single most annoying thing a status panel can tell you.\n    this.log = [];\n    this.onLog = onLog || ((..._args: unknown[]) => {});\n  }\n\n  async start() {\n    if (this.running) return this.status();\n    this.state = 'starting';\n    this.lastError = null;\n    this.log = [];\n\n    // Built from the same function the config box shows. If those could differ,\n    // the button would be reporting on a different server than the one a client\n    // launches — which is worse than having no button.\n    const cfg = mcpConfig(this.commandOverride);\n    const child = spawn(cfg.command, cfg.args, {\n      cwd: cfg.cwd,\n      stdio: ['pipe', 'pipe', 'pipe'],\n      env: { ...process.env, ONBOARDER_MCP: '1', LOG_LEVEL: 'warn' },\n      // No shell: the command is a fixed argv, and a shell would only add a way\n      // for something to be interpreted.\n      shell: false,\n    });\n    this.child = child;\n\n    child.stdout.setEncoding('utf8');\n    child.stderr.setEncoding('utf8');\n    // Only stderr is a log. stdout is the MCP protocol stream: logging it would\n    // fill the panel with JSON-RPC frames, and the one that matters — the\n    // handshake reply — is consumed by `handshake` below. The stream is drained\n    // regardless, because a pipe nobody reads eventually blocks the writer.\n    child.stdout.on('data', (..._args: unknown[]) => {});\n    child.stderr.on('data', (chunk) => this.note(String(chunk).trimEnd()));\n\n    const exited = new Promise((resolve) => {\n      child.once('exit', (code, signal) => {\n        const wasStopping = this.state === 'stopping';\n        this.child = null;\n        this.state = 'stopped';\n        this.startedAt = null;\n        if (!wasStopping) {\n          this.lastError = signal\n            ? `Stopped unexpectedly (${signal}).`\n            : `Stopped unexpectedly (exit code ${code}).`;\n          this.note(this.lastError);\n        }\n        resolve({ code, signal });\n      });\n    });\n\n    child.once('error', (err) => {\n      this.lastError = `Could not start: ${err.message}`;\n      this.state = 'stopped';\n      this.child = null;\n      this.note(this.lastError);\n    });\n\n    // A handshake proves the server is not merely spawned but actually answering\n    // MCP. \"running\" that means the process exists is how a broken server ends up\n    // looking healthy in the UI.\n    const ok = await this.handshake(exited);\n    if (ok) {\n      this.state = 'running';\n      this.startedAt = Date.now();\n      this.note('MCP server ready on stdio.');\n    } else if (this.child) {\n      await this.stop();\n    } else {\n      this.state = 'stopped';\n    }\n    return this.status();\n  }\n\n  // The MCP handshake, spoken to our own child: initialize, then the\n  // `notifications/initialized` the spec requires before ordinary traffic.\n  async handshake(exited) {\n    const child = this.child;\n    if (!child) return false;\n\n    return new Promise((resolve) => {\n      let buffer = '';\n      let settled = false;\n      const finish = (ok) => {\n        if (settled) return;\n        settled = true;\n        clearTimeout(timer);\n        child.stdout.off('data', onData);\n        // Resolve now, not on exit. The child is *supposed* to stay running, so\n        // waiting for it to exit would mean this promise only ever settled when\n        // something had already gone wrong.\n        resolve(ok && this.child !== null);\n      };\n      const onData = (chunk) => {\n        buffer += chunk;\n        let nl;\n        while ((nl = buffer.indexOf('\\n')) !== -1) {\n          const line = buffer.slice(0, nl).trim();\n          buffer = buffer.slice(nl + 1);\n          if (!line) continue;\n          try {\n            const msg = JSON.parse(line);\n            if (msg?.id === 'onboarder-probe' && msg.result?.serverInfo?.name === 'onboarder') {\n              child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\\n');\n              finish(true);\n              return;\n            }\n          } catch {\n            // A line that is not JSON during the handshake is a bug elsewhere —\n            // something wrote to stdout that should not have. Keep reading: the\n            // real initialize reply may still arrive.\n          }\n        }\n      };\n\n      const timer = setTimeout(() => {\n        this.lastError = 'The MCP server did not answer its handshake within 5s.';\n        this.note(this.lastError);\n        finish(false);\n      }, 5000);\n\n      child.stdout.on('data', onData);\n      // If the child dies first, do not wait out the full timeout.\n      exited.then(() => finish(false));\n\n      child.stdin.write(JSON.stringify({\n        jsonrpc: '2.0',\n        id: 'onboarder-probe',\n        method: 'initialize',\n        params: {\n          protocolVersion: '2025-06-18',\n          capabilities: {},\n          clientInfo: { name: 'onboarder-ui', version: '1.0.0' },\n        },\n      }) + '\\n');\n    });\n  }\n\n  async stop() {\n    const child = this.child;\n    if (!child) {\n      this.state = 'stopped';\n      return this.status();\n    }\n    this.state = 'stopping';\n\n    // Closing stdin is the polite shutdown: `serveMcp` drains what is queued and\n    // lets the loop empty, so a request in flight gets its answer.\n    const exited = new Promise((resolve) => child.once('exit', resolve));\n    child.stdin.end();\n    const timer = setTimeout(() => child.kill('SIGKILL'), STOP_GRACE_MS);\n\n    await exited;\n    clearTimeout(timer);\n    this.child = null;\n    this.state = 'stopped';\n    this.startedAt = null;\n    this.note('MCP server stopped.');\n    return this.status();\n  }\n\n  status() {\n    return {\n      ...mcpStatus(),\n      state: this.state,\n      running: this.running,\n      pid: this.child?.pid ?? null,\n      startedAt: this.startedAt,\n      uptimeMs: this.startedAt ? Date.now() - this.startedAt : 0,\n      lastError: this.lastError,\n      log: this.log.slice(-20),\n    };\n  }\n}\n\nexport function createMcpRunner(opts) {\n  return new McpRunner(opts);\n}\n"]}

package/server/mcp/server.d.ts

@@ -0,0 +1,29 @@
+export declare const PROTOCOL_VERSION = "2025-06-18";
+export declare const SERVER_INFO: {
+    name: string;
+    version: string;
+    title: string;
+    instructions: string;
+};
+export { handle };
+declare function handle(msg: any): Promise<{
+    jsonrpc: string;
+    id: any;
+    result: any;
+} | {
+    jsonrpc: string;
+    id: any;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}>;
+/**
+ * Run the server until stdin closes. `input` and `output` are parameters so tests
+ * can drive a whole session through in-memory streams.
+ */
+export declare function serveMcp({ input, output }?: Record<string, any>): {
+    stop(): void;
+    settled(): Promise<void>;
+};