frontmcp 1.2.1 → 1.3.0

package/src/commands/dev/bridge/child-supervisor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Child supervisor for the dev bridge (issue #399).
+ *
+ * Owns the user-code subprocess. Spawns it, watches for the ready
+ * sentinel (or a TCP probe in HTTP mode), restarts it on watcher events,
+ * and surfaces lifecycle events to the state machine.
+ *
+ * Two modes:
+ *
+ *   - **HTTP mode (default)**: `npx -y tsx --conditions node <entry>` with
+ *     `stdio: 'pipe'`. The child boots a normal FrontMCP HTTP listener on
+ *     `FRONTMCP_DEV_PORT`. The supervisor TCP-probes the port to confirm
+ *     readiness, OR greps the child's stderr for the `__FRONTMCP_BOOTSTRAP_COMPLETE__`
+ *     sentinel when `FRONTMCP_DEV_BOOTSTRAP_SENTINEL=1` is set.
+ *
+ *   - **Pipe mode (`--serve`)**: `node --import tsx <entry>` with
+ *     `stdio: ['pipe', 'pipe', 'pipe', 'ipc']`. `FRONTMCP_DEV_STDIO_FD=3`
+ *     tells the SDK to point `runStdio` at the IPC pipe. Readiness =
+ *     first `message` over the IPC channel.
+ */
+import { type ChildProcess } from 'node:child_process';
+import type { BridgeLogger } from './log';
+export type SupervisorMode = 'http' | 'pipe';
+export interface ChildSupervisorOptions {
+    mode: SupervisorMode;
+    entry: string;
+    log: BridgeLogger;
+    /** Pinned session id passed to the child for HTTP-mode session continuity. */
+    sessionId?: string;
+    /** Port for HTTP mode. Ignored in pipe mode. */
+    port?: number;
+    /** Called once the child is ready to accept traffic. */
+    onReady: (child: ChildProcess) => void | Promise<void>;
+    /** Called when the child exits (expected or otherwise). */
+    onExit: (reason: string) => void | Promise<void>;
+    /** Max time to wait for a child to become ready before giving up. */
+    readyTimeoutMs?: number;
+}
+export interface ChildSupervisor {
+    start(): Promise<void>;
+    /** Kill the current child, spawn a replacement, wait for ready. */
+    restart(): Promise<void>;
+    /** Final shutdown. */
+    stop(): Promise<void>;
+    /** Current child handle (undefined when no child is running). */
+    current(): ChildProcess | undefined;
+}
+export declare function createChildSupervisor(options: ChildSupervisorOptions): ChildSupervisor;

package/src/commands/dev/bridge/child-supervisor.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * Child supervisor for the dev bridge (issue #399).
+ *
+ * Owns the user-code subprocess. Spawns it, watches for the ready
+ * sentinel (or a TCP probe in HTTP mode), restarts it on watcher events,
+ * and surfaces lifecycle events to the state machine.
+ *
+ * Two modes:
+ *
+ *   - **HTTP mode (default)**: `npx -y tsx --conditions node <entry>` with
+ *     `stdio: 'pipe'`. The child boots a normal FrontMCP HTTP listener on
+ *     `FRONTMCP_DEV_PORT`. The supervisor TCP-probes the port to confirm
+ *     readiness, OR greps the child's stderr for the `__FRONTMCP_BOOTSTRAP_COMPLETE__`
+ *     sentinel when `FRONTMCP_DEV_BOOTSTRAP_SENTINEL=1` is set.
+ *
+ *   - **Pipe mode (`--serve`)**: `node --import tsx <entry>` with
+ *     `stdio: ['pipe', 'pipe', 'pipe', 'ipc']`. `FRONTMCP_DEV_STDIO_FD=3`
+ *     tells the SDK to point `runStdio` at the IPC pipe. Readiness =
+ *     first `message` over the IPC channel.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChildSupervisor = createChildSupervisor;
+const tslib_1 = require("tslib");
+const node_child_process_1 = require("node:child_process");
+const net = tslib_1.__importStar(require("node:net"));
+const READY_SENTINEL = '__FRONTMCP_BOOTSTRAP_COMPLETE__';
+function createChildSupervisor(options) {
+    const { mode, entry, log, sessionId, port, onReady, onExit, readyTimeoutMs = 30_000 } = options;
+    let current;
+    let killSignaled = false;
+    function buildEnv() {
+        const env = { ...process.env };
+        // The stderr-bootstrap sentinel is an HTTP-mode signal only: in pipe
+        // mode readiness MUST be the first IPC message from the child so we
+        // know the FD-3 channel is wired up. Enabling the sentinel in pipe
+        // mode lets probeReady() resolve before any IPC arrives and races
+        // the first forwarded request.
+        if (mode === 'http')
+            env['FRONTMCP_DEV_BOOTSTRAP_SENTINEL'] = '1';
+        if (sessionId)
+            env['FRONTMCP_DEV_FORCE_SESSION_ID'] = sessionId;
+        if (mode === 'http' && port)
+            env['FRONTMCP_DEV_PORT'] = String(port);
+        if (mode === 'pipe')
+            env['FRONTMCP_DEV_STDIO_FD'] = '3';
+        return env;
+    }
+    function spawnChild() {
+        const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+        if (mode === 'http') {
+            // tsx as a loader; bridge owns the watcher (no --watch here).
+            return (0, node_child_process_1.spawn)(npxCmd, ['-y', 'tsx', '--conditions', 'node', entry], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: buildEnv(),
+            });
+        }
+        // Pipe mode: pair an IPC channel as FD 3 so the child can read/write
+        // JSON frames there. Node sets up the IPC machinery automatically when
+        // 'ipc' is the 4th stdio entry — the resulting FD lands at 3.
+        return (0, node_child_process_1.spawn)(npxCmd, ['-y', 'tsx', '--conditions', 'node', entry], {
+            stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+            env: buildEnv(),
+        });
+    }
+    async function probeReady(child) {
+        return new Promise((resolve, reject) => {
+            let resolved = false;
+            const cleanup = () => {
+                clearTimeout(deadlineTimer);
+                clearInterval(tcpProbeTimer);
+                child.stderr?.off('data', onStderr);
+                child.off('message', onMessage);
+                child.off('exit', onExitDuringBoot);
+            };
+            const deadlineTimer = setTimeout(() => {
+                if (resolved)
+                    return;
+                resolved = true;
+                cleanup();
+                reject(new Error(`child did not become ready within ${readyTimeoutMs}ms`));
+            }, readyTimeoutMs).unref();
+            const onStderr = (chunk) => {
+                // Sentinel-on-stderr is only meaningful in HTTP mode (buildEnv
+                // sets `FRONTMCP_DEV_BOOTSTRAP_SENTINEL=1` only there). In pipe
+                // mode readiness comes from the first IPC message — ignore any
+                // stderr signal so we don't race the IPC handshake.
+                if (mode !== 'http')
+                    return;
+                const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+                if (text.includes(READY_SENTINEL)) {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    cleanup();
+                    resolve();
+                }
+            };
+            child.stderr?.on('data', onStderr);
+            const onMessage = () => {
+                if (mode !== 'pipe' || resolved)
+                    return;
+                // First IPC message from the child counts as ready in pipe mode.
+                resolved = true;
+                cleanup();
+                resolve();
+            };
+            if (mode === 'pipe')
+                child.on('message', onMessage);
+            const onExitDuringBoot = (code, signal) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                cleanup();
+                reject(new Error(`child exited during boot: code=${code} signal=${signal ?? 'null'}`));
+            };
+            child.once('exit', onExitDuringBoot);
+            // HTTP mode fallback: TCP probe in parallel with the sentinel scan.
+            const tcpProbeTimer = mode === 'http' && port
+                ? setInterval(() => {
+                    if (resolved)
+                        return;
+                    const sock = net.createConnection({ host: '127.0.0.1', port }, () => {
+                        sock.end();
+                        if (resolved)
+                            return;
+                        resolved = true;
+                        cleanup();
+                        resolve();
+                    });
+                    sock.once('error', () => sock.destroy());
+                    sock.setTimeout(500, () => sock.destroy());
+                }, 250).unref()
+                : setInterval(() => undefined, 60_000).unref();
+        });
+    }
+    async function killCurrent() {
+        if (!current)
+            return;
+        killSignaled = true;
+        const dyingChild = current;
+        try {
+            dyingChild.kill('SIGTERM');
+        }
+        catch {
+            // ignore
+        }
+        const forceKill = setTimeout(() => {
+            try {
+                dyingChild.kill('SIGKILL');
+            }
+            catch {
+                // ignore
+            }
+        }, 2000).unref();
+        await new Promise((resolve) => {
+            if (dyingChild.exitCode !== null || dyingChild.signalCode !== null)
+                return resolve();
+            dyingChild.once('exit', () => resolve());
+        });
+        clearTimeout(forceKill);
+        killSignaled = false;
+    }
+    function wireExitHandler(child) {
+        child.once('exit', (code, signal) => {
+            const reason = killSignaled ? 'killed-for-restart' : `code=${code ?? 'null'} signal=${signal ?? 'null'}`;
+            log.warn('child-exited', { reason });
+            void onExit(reason);
+        });
+        // Forward child stderr to the log file (never to our stdout).
+        child.stderr?.on('data', (chunk) => {
+            const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+            for (const line of text.split('\n')) {
+                if (!line.trim())
+                    continue;
+                if (line.includes(READY_SENTINEL))
+                    continue;
+                log.info('child-stderr', { line: line.slice(0, 500) });
+            }
+        });
+    }
+    return {
+        current: () => current,
+        async start() {
+            log.info('child-spawn', { mode, entry, port: port ?? null });
+            const child = spawnChild();
+            current = child;
+            wireExitHandler(child);
+            // Clean up the spawned subprocess on any startup failure
+            // (probeReady timeout, onReady throw). Without this, a failed
+            // start would leave the child running and occupying the dev port
+            // or the IPC channel, breaking the next restart.
+            try {
+                await probeReady(child);
+                log.info('child-ready', { mode, pid: child.pid ?? null });
+                await onReady(child);
+            }
+            catch (err) {
+                await killCurrent();
+                current = undefined;
+                throw err;
+            }
+        },
+        async restart() {
+            log.info('child-restart-start');
+            await killCurrent();
+            current = undefined;
+            const child = spawnChild();
+            current = child;
+            wireExitHandler(child);
+            try {
+                await probeReady(child);
+                log.info('child-restart-ready', { pid: child.pid ?? null });
+                await onReady(child);
+            }
+            catch (err) {
+                await killCurrent();
+                current = undefined;
+                throw err;
+            }
+        },
+        async stop() {
+            await killCurrent();
+            current = undefined;
+        },
+    };
+}
+//# sourceMappingURL=child-supervisor.js.map

package/src/commands/dev/bridge/child-supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-supervisor.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/child-supervisor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Child supervisor for the dev bridge (issue #399).\n *\n * Owns the user-code subprocess. Spawns it, watches for the ready\n * sentinel (or a TCP probe in HTTP mode), restarts it on watcher events,\n * and surfaces lifecycle events to the state machine.\n *\n * Two modes:\n *\n *   - **HTTP mode (default)**: `npx -y tsx --conditions node <entry>` with\n *     `stdio: 'pipe'`. The child boots a normal FrontMCP HTTP listener on\n *     `FRONTMCP_DEV_PORT`. The supervisor TCP-probes the port to confirm\n *     readiness, OR greps the child's stderr for the `__FRONTMCP_BOOTSTRAP_COMPLETE__`\n *     sentinel when `FRONTMCP_DEV_BOOTSTRAP_SENTINEL=1` is set.\n *\n *   - **Pipe mode (`--serve`)**: `node --import tsx <entry>` with\n *     `stdio: ['pipe', 'pipe', 'pipe', 'ipc']`. `FRONTMCP_DEV_STDIO_FD=3`\n *     tells the SDK to point `runStdio` at the IPC pipe. Readiness =\n *     first `message` over the IPC channel.\n */\n\nimport { spawn, type ChildProcess } from 'node:child_process';\nimport * as net from 'node:net';\n\nimport type { BridgeLogger } from './log';\n\nexport type SupervisorMode = 'http' | 'pipe';\n\nexport interface ChildSupervisorOptions {\n  mode: SupervisorMode;\n  entry: string;\n  log: BridgeLogger;\n  /** Pinned session id passed to the child for HTTP-mode session continuity. */\n  sessionId?: string;\n  /** Port for HTTP mode. Ignored in pipe mode. */\n  port?: number;\n  /** Called once the child is ready to accept traffic. */\n  onReady: (child: ChildProcess) => void | Promise<void>;\n  /** Called when the child exits (expected or otherwise). */\n  onExit: (reason: string) => void | Promise<void>;\n  /** Max time to wait for a child to become ready before giving up. */\n  readyTimeoutMs?: number;\n}\n\nexport interface ChildSupervisor {\n  start(): Promise<void>;\n  /** Kill the current child, spawn a replacement, wait for ready. */\n  restart(): Promise<void>;\n  /** Final shutdown. */\n  stop(): Promise<void>;\n  /** Current child handle (undefined when no child is running). */\n  current(): ChildProcess | undefined;\n}\n\nconst READY_SENTINEL = '__FRONTMCP_BOOTSTRAP_COMPLETE__';\n\nexport function createChildSupervisor(options: ChildSupervisorOptions): ChildSupervisor {\n  const { mode, entry, log, sessionId, port, onReady, onExit, readyTimeoutMs = 30_000 } = options;\n\n  let current: ChildProcess | undefined;\n  let killSignaled = false;\n\n  function buildEnv(): NodeJS.ProcessEnv {\n    const env: NodeJS.ProcessEnv = { ...process.env };\n    // The stderr-bootstrap sentinel is an HTTP-mode signal only: in pipe\n    // mode readiness MUST be the first IPC message from the child so we\n    // know the FD-3 channel is wired up. Enabling the sentinel in pipe\n    // mode lets probeReady() resolve before any IPC arrives and races\n    // the first forwarded request.\n    if (mode === 'http') env['FRONTMCP_DEV_BOOTSTRAP_SENTINEL'] = '1';\n    if (sessionId) env['FRONTMCP_DEV_FORCE_SESSION_ID'] = sessionId;\n    if (mode === 'http' && port) env['FRONTMCP_DEV_PORT'] = String(port);\n    if (mode === 'pipe') env['FRONTMCP_DEV_STDIO_FD'] = '3';\n    return env;\n  }\n\n  function spawnChild(): ChildProcess {\n    const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';\n    if (mode === 'http') {\n      // tsx as a loader; bridge owns the watcher (no --watch here).\n      return spawn(npxCmd, ['-y', 'tsx', '--conditions', 'node', entry], {\n        stdio: ['ignore', 'pipe', 'pipe'],\n        env: buildEnv(),\n      });\n    }\n    // Pipe mode: pair an IPC channel as FD 3 so the child can read/write\n    // JSON frames there. Node sets up the IPC machinery automatically when\n    // 'ipc' is the 4th stdio entry — the resulting FD lands at 3.\n    return spawn(npxCmd, ['-y', 'tsx', '--conditions', 'node', entry], {\n      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],\n      env: buildEnv(),\n    });\n  }\n\n  async function probeReady(child: ChildProcess): Promise<void> {\n    return new Promise<void>((resolve, reject) => {\n      let resolved = false;\n      const cleanup = (): void => {\n        clearTimeout(deadlineTimer);\n        clearInterval(tcpProbeTimer);\n        child.stderr?.off('data', onStderr);\n        child.off('message', onMessage);\n        child.off('exit', onExitDuringBoot);\n      };\n\n      const deadlineTimer = setTimeout(() => {\n        if (resolved) return;\n        resolved = true;\n        cleanup();\n        reject(new Error(`child did not become ready within ${readyTimeoutMs}ms`));\n      }, readyTimeoutMs).unref();\n\n      const onStderr = (chunk: Buffer | string): void => {\n        // Sentinel-on-stderr is only meaningful in HTTP mode (buildEnv\n        // sets `FRONTMCP_DEV_BOOTSTRAP_SENTINEL=1` only there). In pipe\n        // mode readiness comes from the first IPC message — ignore any\n        // stderr signal so we don't race the IPC handshake.\n        if (mode !== 'http') return;\n        const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');\n        if (text.includes(READY_SENTINEL)) {\n          if (resolved) return;\n          resolved = true;\n          cleanup();\n          resolve();\n        }\n      };\n      child.stderr?.on('data', onStderr);\n\n      const onMessage = (): void => {\n        if (mode !== 'pipe' || resolved) return;\n        // First IPC message from the child counts as ready in pipe mode.\n        resolved = true;\n        cleanup();\n        resolve();\n      };\n      if (mode === 'pipe') child.on('message', onMessage);\n\n      const onExitDuringBoot = (code: number | null, signal: NodeJS.Signals | null): void => {\n        if (resolved) return;\n        resolved = true;\n        cleanup();\n        reject(new Error(`child exited during boot: code=${code} signal=${signal ?? 'null'}`));\n      };\n      child.once('exit', onExitDuringBoot);\n\n      // HTTP mode fallback: TCP probe in parallel with the sentinel scan.\n      const tcpProbeTimer =\n        mode === 'http' && port\n          ? setInterval(() => {\n              if (resolved) return;\n              const sock = net.createConnection({ host: '127.0.0.1', port }, () => {\n                sock.end();\n                if (resolved) return;\n                resolved = true;\n                cleanup();\n                resolve();\n              });\n              sock.once('error', () => sock.destroy());\n              sock.setTimeout(500, () => sock.destroy());\n            }, 250).unref()\n          : setInterval(() => undefined, 60_000).unref();\n    });\n  }\n\n  async function killCurrent(): Promise<void> {\n    if (!current) return;\n    killSignaled = true;\n    const dyingChild = current;\n    try {\n      dyingChild.kill('SIGTERM');\n    } catch {\n      // ignore\n    }\n    const forceKill = setTimeout(() => {\n      try {\n        dyingChild.kill('SIGKILL');\n      } catch {\n        // ignore\n      }\n    }, 2000).unref();\n    await new Promise<void>((resolve) => {\n      if (dyingChild.exitCode !== null || dyingChild.signalCode !== null) return resolve();\n      dyingChild.once('exit', () => resolve());\n    });\n    clearTimeout(forceKill);\n    killSignaled = false;\n  }\n\n  function wireExitHandler(child: ChildProcess): void {\n    child.once('exit', (code, signal) => {\n      const reason = killSignaled ? 'killed-for-restart' : `code=${code ?? 'null'} signal=${signal ?? 'null'}`;\n      log.warn('child-exited', { reason });\n      void onExit(reason);\n    });\n    // Forward child stderr to the log file (never to our stdout).\n    child.stderr?.on('data', (chunk: Buffer | string) => {\n      const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');\n      for (const line of text.split('\\n')) {\n        if (!line.trim()) continue;\n        if (line.includes(READY_SENTINEL)) continue;\n        log.info('child-stderr', { line: line.slice(0, 500) });\n      }\n    });\n  }\n\n  return {\n    current: () => current,\n    async start() {\n      log.info('child-spawn', { mode, entry, port: port ?? null });\n      const child = spawnChild();\n      current = child;\n      wireExitHandler(child);\n      // Clean up the spawned subprocess on any startup failure\n      // (probeReady timeout, onReady throw). Without this, a failed\n      // start would leave the child running and occupying the dev port\n      // or the IPC channel, breaking the next restart.\n      try {\n        await probeReady(child);\n        log.info('child-ready', { mode, pid: child.pid ?? null });\n        await onReady(child);\n      } catch (err) {\n        await killCurrent();\n        current = undefined;\n        throw err;\n      }\n    },\n    async restart() {\n      log.info('child-restart-start');\n      await killCurrent();\n      current = undefined;\n      const child = spawnChild();\n      current = child;\n      wireExitHandler(child);\n      try {\n        await probeReady(child);\n        log.info('child-restart-ready', { pid: child.pid ?? null });\n        await onReady(child);\n      } catch (err) {\n        await killCurrent();\n        current = undefined;\n        throw err;\n      }\n    },\n    async stop() {\n      await killCurrent();\n      current = undefined;\n    },\n  };\n}\n"]}

package/src/commands/dev/bridge/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * JSON-RPC error codes emitted by the dev bridge (issue #399).
+ *
+ * Reserved in the implementation-defined `-32099 .. -32000` range so they
+ * never collide with the JSON-RPC 2.0 reserved range. Clients (Claude
+ * Code, etc.) receive these in `error.code` and can render structured
+ * feedback instead of sitting on an indefinite `Calling…` spinner.
+ */
+export declare const DEV_SERVER_UNREACHABLE = -32099;
+export declare const DEV_BUFFER_FULL = -32098;
+export declare const DEV_RELOAD_DEADLINE = -32097;
+/** Human-readable label for each code. Used in the `error.message` field. */
+export declare const DEV_ERROR_MESSAGE: Record<number, string>;
+/** Build a JSON-RPC error response for a given inbound request id. */
+export declare function makeDevError(id: string | number | null, code: number, data?: Record<string, unknown>): {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: {
+        code: number;
+        message: string;
+        data?: Record<string, unknown>;
+    };
+};

package/src/commands/dev/bridge/errors.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEV_ERROR_MESSAGE = exports.DEV_RELOAD_DEADLINE = exports.DEV_BUFFER_FULL = exports.DEV_SERVER_UNREACHABLE = void 0;
+exports.makeDevError = makeDevError;
+/**
+ * JSON-RPC error codes emitted by the dev bridge (issue #399).
+ *
+ * Reserved in the implementation-defined `-32099 .. -32000` range so they
+ * never collide with the JSON-RPC 2.0 reserved range. Clients (Claude
+ * Code, etc.) receive these in `error.code` and can render structured
+ * feedback instead of sitting on an indefinite `Calling…` spinner.
+ */
+exports.DEV_SERVER_UNREACHABLE = -32099;
+exports.DEV_BUFFER_FULL = -32098;
+exports.DEV_RELOAD_DEADLINE = -32097;
+/** Human-readable label for each code. Used in the `error.message` field. */
+exports.DEV_ERROR_MESSAGE = {
+    [exports.DEV_SERVER_UNREACHABLE]: 'dev_server_unreachable',
+    [exports.DEV_BUFFER_FULL]: 'dev_buffer_full',
+    [exports.DEV_RELOAD_DEADLINE]: 'dev_reload_deadline',
+};
+/** Build a JSON-RPC error response for a given inbound request id. */
+function makeDevError(id, code, data) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: {
+            code,
+            message: exports.DEV_ERROR_MESSAGE[code] ?? 'dev_error',
+            ...(data ? { data } : {}),
+        },
+    };
+}
+//# sourceMappingURL=errors.js.map

package/src/commands/dev/bridge/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/errors.ts"],"names":[],"mappings":";;;AAoBA,oCAkBC;AAtCD;;;;;;;GAOG;AACU,QAAA,sBAAsB,GAAG,CAAC,KAAK,CAAC;AAChC,QAAA,eAAe,GAAG,CAAC,KAAK,CAAC;AACzB,QAAA,mBAAmB,GAAG,CAAC,KAAK,CAAC;AAE1C,6EAA6E;AAChE,QAAA,iBAAiB,GAA2B;IACvD,CAAC,8BAAsB,CAAC,EAAE,wBAAwB;IAClD,CAAC,uBAAe,CAAC,EAAE,iBAAiB;IACpC,CAAC,2BAAmB,CAAC,EAAE,qBAAqB;CAC7C,CAAC;AAEF,sEAAsE;AACtE,SAAgB,YAAY,CAC1B,EAA0B,EAC1B,IAAY,EACZ,IAA8B;IAM9B,OAAO;QACL,OAAO,EAAE,KAAK;QACd,EAAE;QACF,KAAK,EAAE;YACL,IAAI;YACJ,OAAO,EAAE,yBAAiB,CAAC,IAAI,CAAC,IAAI,WAAW;YAC/C,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1B;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * JSON-RPC error codes emitted by the dev bridge (issue #399).\n *\n * Reserved in the implementation-defined `-32099 .. -32000` range so they\n * never collide with the JSON-RPC 2.0 reserved range. Clients (Claude\n * Code, etc.) receive these in `error.code` and can render structured\n * feedback instead of sitting on an indefinite `Calling…` spinner.\n */\nexport const DEV_SERVER_UNREACHABLE = -32099;\nexport const DEV_BUFFER_FULL = -32098;\nexport const DEV_RELOAD_DEADLINE = -32097;\n\n/** Human-readable label for each code. Used in the `error.message` field. */\nexport const DEV_ERROR_MESSAGE: Record<number, string> = {\n  [DEV_SERVER_UNREACHABLE]: 'dev_server_unreachable',\n  [DEV_BUFFER_FULL]: 'dev_buffer_full',\n  [DEV_RELOAD_DEADLINE]: 'dev_reload_deadline',\n};\n\n/** Build a JSON-RPC error response for a given inbound request id. */\nexport function makeDevError(\n  id: string | number | null,\n  code: number,\n  data?: Record<string, unknown>,\n): {\n  jsonrpc: '2.0';\n  id: string | number | null;\n  error: { code: number; message: string; data?: Record<string, unknown> };\n} {\n  return {\n    jsonrpc: '2.0',\n    id,\n    error: {\n      code,\n      message: DEV_ERROR_MESSAGE[code] ?? 'dev_error',\n      ...(data ? { data } : {}),\n    },\n  };\n}\n"]}

package/src/commands/dev/bridge/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Dev stdio bridge entry point (issue #399).
+ *
+ * Wires the framer (stdio in/out), state machine (buffer + reload FSM),
+ * watcher (file-change source), child supervisor (user-code lifecycle),
+ * and upstream client (forwarding to the child) into a single
+ * long-lived process.
+ *
+ * Lifetime:
+ *
+ *   1. Parse options, resolve entry + log file path.
+ *   2. Pin a stable session id (uuid) so the same id survives child
+ *      restarts.
+ *   3. Construct logger; open log file.
+ *   4. Construct state machine + framer + watcher + supervisor +
+ *      upstream client (transport per `--serve`).
+ *   5. Spawn the first child, wait for ready, transition state to Ready.
+ *   6. Forward frames in both directions; watcher events trigger
+ *      controlled restart.
+ *   7. SIGINT/SIGTERM → flush buffer with `dev_server_unreachable`,
+ *      tear down child + watcher, exit cleanly.
+ */
+import type { ParsedArgs } from '../../../core/args';
+import { type ChildSupervisor } from './child-supervisor';
+import { type BridgeLogger } from './log';
+import { type BridgeStateMachine } from './state-machine';
+import { type StdioFramer } from './stdio-framer';
+import { type UpstreamClient } from './upstream-client';
+export declare function runDevBridge(opts: ParsedArgs): Promise<void>;
+export { type BridgeLogger, type BridgeStateMachine, type ChildSupervisor, type StdioFramer, type UpstreamClient };

package/src/commands/dev/bridge/index.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Dev stdio bridge entry point (issue #399).
+ *
+ * Wires the framer (stdio in/out), state machine (buffer + reload FSM),
+ * watcher (file-change source), child supervisor (user-code lifecycle),
+ * and upstream client (forwarding to the child) into a single
+ * long-lived process.
+ *
+ * Lifetime:
+ *
+ *   1. Parse options, resolve entry + log file path.
+ *   2. Pin a stable session id (uuid) so the same id survives child
+ *      restarts.
+ *   3. Construct logger; open log file.
+ *   4. Construct state machine + framer + watcher + supervisor +
+ *      upstream client (transport per `--serve`).
+ *   5. Spawn the first child, wait for ready, transition state to Ready.
+ *   6. Forward frames in both directions; watcher events trigger
+ *      controlled restart.
+ *   7. SIGINT/SIGTERM → flush buffer with `dev_server_unreachable`,
+ *      tear down child + watcher, exit cleanly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDevBridge = runDevBridge;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("node:path"));
+const utils_1 = require("@frontmcp/utils");
+const fs_1 = require("../../../shared/fs");
+const child_supervisor_1 = require("./child-supervisor");
+const log_1 = require("./log");
+const state_machine_1 = require("./state-machine");
+const stdio_framer_1 = require("./stdio-framer");
+const upstream_client_1 = require("./upstream-client");
+const watcher_1 = require("./watcher");
+const DEFAULT_PORT = 3000;
+const DEFAULT_LOG_FILE = path.join('.frontmcp', 'dev.log');
+function normalizeOptions(opts, entry) {
+    const mode = opts.serve ? 'pipe' : 'http';
+    const port = typeof opts.port === 'number' ? opts.port : DEFAULT_PORT;
+    const bufferSize = typeof opts.bufferSize === 'number' && opts.bufferSize > 0 ? opts.bufferSize : 8;
+    const reloadDeadlineMs = typeof opts.reloadDeadlineMs === 'number' && opts.reloadDeadlineMs > 0 ? opts.reloadDeadlineMs : 30_000;
+    const logFile = typeof opts.logFile === 'string' && opts.logFile.length > 0 ? opts.logFile : DEFAULT_LOG_FILE;
+    return { entry, mode, port, bufferSize, reloadDeadlineMs, logFile };
+}
+async function runDevBridge(opts) {
+    const cwd = process.cwd();
+    const entry = await (0, fs_1.resolveEntry)(cwd, opts.entry);
+    const runtime = normalizeOptions(opts, entry);
+    const log = await (0, log_1.createBridgeLogger)({ filePath: runtime.logFile });
+    log.info('bridge-start', {
+        entry: runtime.entry,
+        mode: runtime.mode,
+        port: runtime.port,
+        bufferSize: runtime.bufferSize,
+        reloadDeadlineMs: runtime.reloadDeadlineMs,
+    });
+    // Pinned session id — child reads from FRONTMCP_DEV_FORCE_SESSION_ID so
+    // session continuity works across restarts (memory or Redis store both OK).
+    const sessionId = (0, utils_1.randomUUID)();
+    // Only `upstream` is reassigned during runtime (on every child restart).
+    // The rest are constructed exactly once below and referenced through
+    // closures that fire after all bindings exist.
+    let upstream;
+    function buildUpstreamForChild(child) {
+        if (runtime.mode === 'http') {
+            return (0, upstream_client_1.createHttpUpstream)({
+                url: `http://127.0.0.1:${runtime.port}/`,
+                log,
+                sessionId,
+                onFrame: (frame) => fsm.relayUpstream(frame),
+            });
+        }
+        return (0, upstream_client_1.createPipeUpstream)({
+            child,
+            log,
+            sessionId,
+            onFrame: (frame) => fsm.relayUpstream(frame),
+        });
+    }
+    // ─── construct framer + FSM. Closures bind to each other by reference,
+    // so referencing `fsm`/`framer` inside a callback executed at runtime
+    // is safe even though `framer` is declared first textually. ───
+    const framer = (0, stdio_framer_1.createStdioFramer)({
+        input: process.stdin,
+        output: process.stdout,
+        log,
+        onFrame: (frame) => fsm.enqueue(frame),
+    });
+    const fsm = (0, state_machine_1.createBridgeStateMachine)({
+        log,
+        bufferSize: runtime.bufferSize,
+        reloadDeadlineMs: runtime.reloadDeadlineMs,
+        respond: (frame) => framer.write(frame),
+        forward: async (frame) => {
+            if (!upstream) {
+                log.warn('forward-without-upstream', { method: frame.method });
+                return;
+            }
+            await upstream.send(frame);
+        },
+    });
+    framer.start();
+    // ─── supervisor → boots first child, then attaches upstream ───
+    const supervisor = (0, child_supervisor_1.createChildSupervisor)({
+        mode: runtime.mode,
+        entry: runtime.entry,
+        log,
+        sessionId,
+        port: runtime.mode === 'http' ? runtime.port : undefined,
+        onReady: async (child) => {
+            // Close any previous upstream (reload path). A rejection here MUST
+            // NOT block re-binding — the child is up and ready, and leaving the
+            // bridge without an upstream would strand every subsequent RPC.
+            try {
+                await upstream?.close();
+            }
+            catch (err) {
+                log.error('upstream-stop-error', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            upstream = buildUpstreamForChild(child);
+            fsm.onChildReady();
+        },
+        onExit: (reason) => {
+            // Don't drop the close() promise — an in-flight HTTP request or SSE
+            // body read can reject (e.g. AbortError when we abort it ourselves),
+            // and an unhandled rejection here would crash the bridge on the
+            // next tick. Hand the rejection to the logger; the child is dead
+            // either way so we always proceed to onChildExit.
+            const closingUpstream = upstream;
+            upstream = undefined;
+            void closingUpstream?.close().catch((err) => {
+                log.error('upstream-stop-error', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+            fsm.onChildExit(reason);
+        },
+    });
+    fsm.onBootStart();
+    try {
+        await supervisor.start();
+    }
+    catch (err) {
+        log.error('initial-boot-failed', { error: err.message });
+        fsm.onReloadDeadline();
+        // Stay running so the watcher can retry once the user fixes the source.
+    }
+    // ─── watcher → restart on file change ───
+    // Watch the project root (cwd), not just the entry's directory: shared
+    // helpers, `frontmcp.config.ts`, and `tsconfig.json` all live above
+    // `src/main.ts` and must trigger a reload too. The recursive watcher
+    // already debounces and filters via `shouldIgnore` so the wider scope
+    // doesn't generate spurious reloads.
+    const watcher = (0, watcher_1.createDevWatcher)({
+        rootDir: cwd,
+        log,
+        onChange: (trigger) => {
+            fsm.onWatcherEvent(trigger);
+            void (async () => {
+                // Defensive — `supervisor` is captured in this closure after the
+                // initial assignment above, but a runtime check keeps the
+                // non-null assertion off the call site.
+                if (!supervisor) {
+                    log.error('restart-failed', { error: 'supervisor not initialised', trigger });
+                    return;
+                }
+                try {
+                    await supervisor.restart();
+                }
+                catch (err) {
+                    log.error('restart-failed', { error: err.message });
+                }
+            })();
+        },
+    });
+    watcher.start();
+    // ─── teardown wiring ───
+    let stopping = false;
+    async function shutdown(signal) {
+        if (stopping)
+            return;
+        stopping = true;
+        log.info('bridge-stop', { signal });
+        try {
+            await fsm.stop();
+        }
+        catch (err) {
+            log.error('fsm-stop-error', { error: err.message });
+        }
+        try {
+            watcher.stop();
+        }
+        catch (err) {
+            log.error('watcher-stop-error', { error: err.message });
+        }
+        try {
+            await upstream?.close();
+        }
+        catch (err) {
+            log.error('upstream-stop-error', { error: err.message });
+        }
+        try {
+            await supervisor.stop();
+        }
+        catch (err) {
+            log.error('supervisor-stop-error', { error: err.message });
+        }
+        framer.stop();
+        await log.close();
+        process.exit(0);
+    }
+    process.once('SIGINT', () => void shutdown('SIGINT'));
+    process.once('SIGTERM', () => void shutdown('SIGTERM'));
+    // Bridge runs until SIGINT/SIGTERM — keep the event loop alive via the
+    // open stdin + watcher.
+}
+//# sourceMappingURL=index.js.map