frontmcp 1.2.1 → 1.4.0

package/src/commands/dev/bridge/upstream-client.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Upstream MCP client for the dev bridge (issue #399).
+ *
+ * Two transport variants:
+ *
+ *   - **HTTP mode**: speaks streamable-HTTP JSON-RPC to the child's HTTP
+ *     listener at `http://127.0.0.1:<port>/`. Carries the bridge-pinned
+ *     `mcp-session-id` header on every request so session continuity
+ *     survives reload.
+ *
+ *   - **Pipe mode (--serve)**: writes/reads newline-delimited JSON-RPC
+ *     frames on a pair of FDs paired with the child via `child_process`
+ *     IPC. The child opens these FDs because `FRONTMCP_DEV_STDIO_FD` is
+ *     set; the bridge writes requests, reads responses, no HTTP layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpUpstream = createHttpUpstream;
+exports.createPipeUpstream = createPipeUpstream;
+function createHttpUpstream(options) {
+    const { log, url, onFrame, sessionId } = options;
+    // Track every in-flight request — `close()` must abort all of them,
+    // not just whichever happened to be assigned last. A shared scalar
+    // would let concurrent sends clobber each other's controller.
+    const abortControllers = new Set();
+    async function send(frame) {
+        const abortController = new AbortController();
+        abortControllers.add(abortController);
+        const signal = abortController.signal;
+        try {
+            const headers = {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+            };
+            if (sessionId)
+                headers['mcp-session-id'] = sessionId;
+            const res = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(frame),
+                signal,
+            });
+            if (!res.ok) {
+                // Reject so the FSM can clear inflight bookkeeping and synthesise
+                // a JSON-RPC error response back to the client. Silently swallowing
+                // a non-OK status here leaves callers hanging.
+                log.warn('http-upstream-non-ok', { status: res.status, method: frame.method });
+                throw new Error(`upstream returned ${res.status} for ${frame.method ?? 'request'}`);
+            }
+            const contentType = res.headers.get('content-type') ?? '';
+            if (contentType.includes('text/event-stream')) {
+                // SSE: parse `data: <json>` lines until the stream ends, forward each.
+                const reader = res.body?.getReader();
+                if (!reader)
+                    return;
+                const decoder = new TextDecoder();
+                let buffer = '';
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    let nl;
+                    while ((nl = buffer.indexOf('\n')) >= 0) {
+                        const line = buffer.slice(0, nl).trim();
+                        buffer = buffer.slice(nl + 1);
+                        if (!line.startsWith('data:'))
+                            continue;
+                        const json = line.slice(5).trim();
+                        if (!json)
+                            continue;
+                        try {
+                            const parsed = JSON.parse(json);
+                            await onFrame(parsed);
+                        }
+                        catch (err) {
+                            log.warn('sse-parse-error', { error: err.message, raw: json.slice(0, 200) });
+                        }
+                    }
+                }
+            }
+            else {
+                // Single JSON response.
+                const body = (await res.json());
+                await onFrame(body);
+            }
+        }
+        catch (err) {
+            // AbortError surfaces when close() interrupts an in-flight request
+            // during reload; that's expected, so log it at info-not-error. We
+            // still rethrow so the FSM can clear inflight bookkeeping and
+            // synthesise an error response on its end.
+            if (err.name === 'AbortError') {
+                log.info('http-upstream-aborted', { method: frame.method });
+            }
+            else {
+                log.error('http-upstream-error', { error: err.message, method: frame.method });
+            }
+            throw err;
+        }
+        finally {
+            abortControllers.delete(abortController);
+        }
+    }
+    return {
+        send,
+        close: async () => {
+            for (const ac of abortControllers)
+                ac.abort();
+            abortControllers.clear();
+        },
+    };
+}
+/**
+ * Pipe mode: the child speaks JSON-RPC on FD 3 (set via
+ * `FRONTMCP_DEV_STDIO_FD=3`). We use Node's IPC channel for the same wire
+ * — `child.send(...)` forwards a structured message and `child.on('message', …)`
+ * yields whatever the child writes back.
+ *
+ * (Node's IPC wraps JSON over a pipe internally; the framing is consistent
+ * with what `runStdio` would write if it were pointed at FD 3.)
+ */
+function createPipeUpstream(options) {
+    const { log, child, onFrame } = options;
+    function handleMessage(msg) {
+        if (!msg || typeof msg !== 'object') {
+            log.warn('pipe-upstream-non-object', { type: typeof msg });
+            return;
+        }
+        void onFrame(msg);
+    }
+    child.on('message', handleMessage);
+    async function send(frame) {
+        if (!child.connected) {
+            log.warn('pipe-upstream-disconnected', { method: frame.method });
+            throw new Error(`pipe upstream disconnected for ${frame.method ?? 'request'}`);
+        }
+        await new Promise((resolve, reject) => {
+            child.send(frame, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        }).catch((err) => {
+            // Reject so the FSM can produce a JSON-RPC error response back to
+            // the client rather than leaving the request stuck inflight.
+            log.warn('pipe-upstream-send-error', { error: err.message, method: frame.method });
+            throw err;
+        });
+    }
+    return {
+        send,
+        close: async () => {
+            child.off('message', handleMessage);
+        },
+    };
+}
+//# sourceMappingURL=upstream-client.js.map

package/src/commands/dev/bridge/upstream-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream-client.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/upstream-client.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Upstream MCP client for the dev bridge (issue #399).\n *\n * Two transport variants:\n *\n *   - **HTTP mode**: speaks streamable-HTTP JSON-RPC to the child's HTTP\n *     listener at `http://127.0.0.1:<port>/`. Carries the bridge-pinned\n *     `mcp-session-id` header on every request so session continuity\n *     survives reload.\n *\n *   - **Pipe mode (--serve)**: writes/reads newline-delimited JSON-RPC\n *     frames on a pair of FDs paired with the child via `child_process`\n *     IPC. The child opens these FDs because `FRONTMCP_DEV_STDIO_FD` is\n *     set; the bridge writes requests, reads responses, no HTTP layer.\n */\n\nimport type { ChildProcess } from 'node:child_process';\n\nimport type { BridgeLogger } from './log';\nimport type { JsonRpcFrame } from './stdio-framer';\n\nexport interface UpstreamClient {\n  send(frame: JsonRpcFrame): Promise<void>;\n  /** Stop background tasks (SSE listener, pipe parser). */\n  close(): Promise<void>;\n}\n\nexport interface UpstreamClientOptions {\n  log: BridgeLogger;\n  /** Called for every frame the upstream child sends back. */\n  onFrame: (frame: JsonRpcFrame) => void | Promise<void>;\n  /** Session id pinned by the bridge for HTTP mode. */\n  sessionId?: string;\n}\n\n// ─── HTTP mode ──────────────────────────────────────────────────────────\n\nexport interface HttpUpstreamOptions extends UpstreamClientOptions {\n  /** Loopback URL of the user-code HTTP server. */\n  url: string;\n}\n\nexport function createHttpUpstream(options: HttpUpstreamOptions): UpstreamClient {\n  const { log, url, onFrame, sessionId } = options;\n  // Track every in-flight request — `close()` must abort all of them,\n  // not just whichever happened to be assigned last. A shared scalar\n  // would let concurrent sends clobber each other's controller.\n  const abortControllers = new Set<AbortController>();\n\n  async function send(frame: JsonRpcFrame): Promise<void> {\n    const abortController = new AbortController();\n    abortControllers.add(abortController);\n    const signal = abortController.signal;\n    try {\n      const headers: Record<string, string> = {\n        'content-type': 'application/json',\n        accept: 'application/json, text/event-stream',\n      };\n      if (sessionId) headers['mcp-session-id'] = sessionId;\n\n      const res = await fetch(url, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify(frame),\n        signal,\n      });\n\n      if (!res.ok) {\n        // Reject so the FSM can clear inflight bookkeeping and synthesise\n        // a JSON-RPC error response back to the client. Silently swallowing\n        // a non-OK status here leaves callers hanging.\n        log.warn('http-upstream-non-ok', { status: res.status, method: frame.method });\n        throw new Error(`upstream returned ${res.status} for ${frame.method ?? 'request'}`);\n      }\n\n      const contentType = res.headers.get('content-type') ?? '';\n      if (contentType.includes('text/event-stream')) {\n        // SSE: parse `data: <json>` lines until the stream ends, forward each.\n        const reader = res.body?.getReader();\n        if (!reader) return;\n        const decoder = new TextDecoder();\n        let buffer = '';\n        while (true) {\n          const { done, value } = await reader.read();\n          if (done) break;\n          buffer += decoder.decode(value, { stream: true });\n          let nl: number;\n          while ((nl = buffer.indexOf('\\n')) >= 0) {\n            const line = buffer.slice(0, nl).trim();\n            buffer = buffer.slice(nl + 1);\n            if (!line.startsWith('data:')) continue;\n            const json = line.slice(5).trim();\n            if (!json) continue;\n            try {\n              const parsed = JSON.parse(json) as JsonRpcFrame;\n              await onFrame(parsed);\n            } catch (err) {\n              log.warn('sse-parse-error', { error: (err as Error).message, raw: json.slice(0, 200) });\n            }\n          }\n        }\n      } else {\n        // Single JSON response.\n        const body = (await res.json()) as JsonRpcFrame;\n        await onFrame(body);\n      }\n    } catch (err) {\n      // AbortError surfaces when close() interrupts an in-flight request\n      // during reload; that's expected, so log it at info-not-error. We\n      // still rethrow so the FSM can clear inflight bookkeeping and\n      // synthesise an error response on its end.\n      if ((err as { name?: string }).name === 'AbortError') {\n        log.info('http-upstream-aborted', { method: frame.method });\n      } else {\n        log.error('http-upstream-error', { error: (err as Error).message, method: frame.method });\n      }\n      throw err;\n    } finally {\n      abortControllers.delete(abortController);\n    }\n  }\n\n  return {\n    send,\n    close: async () => {\n      for (const ac of abortControllers) ac.abort();\n      abortControllers.clear();\n    },\n  };\n}\n\n// ─── Pipe mode (--serve) ────────────────────────────────────────────────\n\nexport interface PipeUpstreamOptions extends UpstreamClientOptions {\n  /** The forked child; we write to / read from the IPC pipe (FD 3). */\n  child: ChildProcess;\n}\n\n/**\n * Pipe mode: the child speaks JSON-RPC on FD 3 (set via\n * `FRONTMCP_DEV_STDIO_FD=3`). We use Node's IPC channel for the same wire\n * — `child.send(...)` forwards a structured message and `child.on('message', …)`\n * yields whatever the child writes back.\n *\n * (Node's IPC wraps JSON over a pipe internally; the framing is consistent\n * with what `runStdio` would write if it were pointed at FD 3.)\n */\nexport function createPipeUpstream(options: PipeUpstreamOptions): UpstreamClient {\n  const { log, child, onFrame } = options;\n\n  function handleMessage(msg: unknown): void {\n    if (!msg || typeof msg !== 'object') {\n      log.warn('pipe-upstream-non-object', { type: typeof msg });\n      return;\n    }\n    void onFrame(msg as JsonRpcFrame);\n  }\n\n  child.on('message', handleMessage);\n\n  async function send(frame: JsonRpcFrame): Promise<void> {\n    if (!child.connected) {\n      log.warn('pipe-upstream-disconnected', { method: frame.method });\n      throw new Error(`pipe upstream disconnected for ${frame.method ?? 'request'}`);\n    }\n    await new Promise<void>((resolve, reject) => {\n      child.send(frame, (err) => {\n        if (err) reject(err);\n        else resolve();\n      });\n    }).catch((err: Error) => {\n      // Reject so the FSM can produce a JSON-RPC error response back to\n      // the client rather than leaving the request stuck inflight.\n      log.warn('pipe-upstream-send-error', { error: err.message, method: frame.method });\n      throw err;\n    });\n  }\n\n  return {\n    send,\n    close: async () => {\n      child.off('message', handleMessage);\n    },\n  };\n}\n"]}

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

@@ -0,0 +1,30 @@
+/**
+ * File watcher for the dev bridge (issue #399).
+ *
+ * In bridge mode, `tsx` is used as a loader (no `--watch`) — the bridge
+ * owns the watcher so it can emit a `reload-start` signal to the state
+ * machine. Today's `tsx --watch` owns the watcher internally, which is
+ * why it can't coordinate with anyone else.
+ *
+ * Uses `fs.watch` (Node built-in, no dep) with a 150ms debounce. The
+ * default ignore list filters `node_modules`, `.git`, `dist`, and the
+ * non-TS extensions that don't trigger source-of-truth reloads.
+ */
+import type { BridgeLogger } from './log';
+export interface DevWatcherOptions {
+    /** Directory to watch (typically the entry's parent). */
+    rootDir: string;
+    /** Debounce window in ms — multiple events within this window collapse. */
+    debounceMs?: number;
+    /** Glob fragments to skip. Default: node_modules, .git, dist, .frontmcp. */
+    ignore?: string[];
+    /** Extensions that trigger reload. Default: .ts, .tsx, .js, .mjs, .cjs. */
+    triggerExtensions?: string[];
+    log: BridgeLogger;
+    onChange: (relativePath: string) => void;
+}
+export interface DevWatcher {
+    start(): void;
+    stop(): void;
+}
+export declare function createDevWatcher(options: DevWatcherOptions): DevWatcher;

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

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * File watcher for the dev bridge (issue #399).
+ *
+ * In bridge mode, `tsx` is used as a loader (no `--watch`) — the bridge
+ * owns the watcher so it can emit a `reload-start` signal to the state
+ * machine. Today's `tsx --watch` owns the watcher internally, which is
+ * why it can't coordinate with anyone else.
+ *
+ * Uses `fs.watch` (Node built-in, no dep) with a 150ms debounce. The
+ * default ignore list filters `node_modules`, `.git`, `dist`, and the
+ * non-TS extensions that don't trigger source-of-truth reloads.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDevWatcher = createDevWatcher;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+const DEFAULT_IGNORE = ['node_modules', '.git', 'dist', '.frontmcp'];
+const DEFAULT_EXTS = ['.ts', '.tsx', '.js', '.mjs', '.cjs'];
+function createDevWatcher(options) {
+    const debounce = options.debounceMs ?? 150;
+    const ignore = options.ignore ?? DEFAULT_IGNORE;
+    const exts = options.triggerExtensions ?? DEFAULT_EXTS;
+    const log = options.log;
+    let timer;
+    let lastTrigger;
+    let watcher;
+    function shouldIgnore(rel) {
+        if (ignore.some((seg) => rel.split(path.sep).includes(seg)))
+            return true;
+        const ext = path.extname(rel);
+        return ext.length > 0 && !exts.includes(ext);
+    }
+    function fire(rel) {
+        lastTrigger = rel;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            const triggerLabel = lastTrigger ?? '(unknown)';
+            log.reloadEvent('watcher', { trigger: triggerLabel });
+            options.onChange(triggerLabel);
+        }, debounce);
+    }
+    return {
+        start() {
+            try {
+                watcher = fs.watch(options.rootDir, { recursive: true }, (_event, filename) => {
+                    if (!filename)
+                        return;
+                    // Node's `fs.watch` types `filename` as `string | null` here
+                    // (no `encoding: 'buffer'` option set), so a `typeof filename ===
+                    // 'string'` narrow leaves the else-branch as `never` and trips
+                    // TS2339. `String(filename)` is defensive for any future widening
+                    // (e.g., a `Buffer` arriving via a polyfill) without confusing
+                    // the type checker.
+                    const rel = String(filename);
+                    if (shouldIgnore(rel))
+                        return;
+                    fire(rel);
+                });
+                watcher.on('error', (err) => {
+                    log.warn('watcher-error', { error: err.message });
+                });
+                log.info('watcher-started', { rootDir: options.rootDir, debounceMs: debounce });
+            }
+            catch (err) {
+                log.error('watcher-start-failed', { error: err.message });
+            }
+        },
+        stop() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            try {
+                watcher?.close();
+            }
+            catch {
+                // ignore
+            }
+            log.info('watcher-stopped');
+        },
+    };
+}
+//# sourceMappingURL=watcher.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../../../../src/commands/dev/bridge/watcher.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * File watcher for the dev bridge (issue #399).\n *\n * In bridge mode, `tsx` is used as a loader (no `--watch`) — the bridge\n * owns the watcher so it can emit a `reload-start` signal to the state\n * machine. Today's `tsx --watch` owns the watcher internally, which is\n * why it can't coordinate with anyone else.\n *\n * Uses `fs.watch` (Node built-in, no dep) with a 150ms debounce. The\n * default ignore list filters `node_modules`, `.git`, `dist`, and the\n * non-TS extensions that don't trigger source-of-truth reloads.\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport type { BridgeLogger } from './log';\n\nexport interface DevWatcherOptions {\n  /** Directory to watch (typically the entry's parent). */\n  rootDir: string;\n  /** Debounce window in ms — multiple events within this window collapse. */\n  debounceMs?: number;\n  /** Glob fragments to skip. Default: node_modules, .git, dist, .frontmcp. */\n  ignore?: string[];\n  /** Extensions that trigger reload. Default: .ts, .tsx, .js, .mjs, .cjs. */\n  triggerExtensions?: string[];\n  log: BridgeLogger;\n  onChange: (relativePath: string) => void;\n}\n\nexport interface DevWatcher {\n  start(): void;\n  stop(): void;\n}\n\nconst DEFAULT_IGNORE = ['node_modules', '.git', 'dist', '.frontmcp'];\nconst DEFAULT_EXTS = ['.ts', '.tsx', '.js', '.mjs', '.cjs'];\n\nexport function createDevWatcher(options: DevWatcherOptions): DevWatcher {\n  const debounce = options.debounceMs ?? 150;\n  const ignore = options.ignore ?? DEFAULT_IGNORE;\n  const exts = options.triggerExtensions ?? DEFAULT_EXTS;\n  const log = options.log;\n  let timer: NodeJS.Timeout | undefined;\n  let lastTrigger: string | undefined;\n  let watcher: fs.FSWatcher | undefined;\n\n  function shouldIgnore(rel: string): boolean {\n    if (ignore.some((seg) => rel.split(path.sep).includes(seg))) return true;\n    const ext = path.extname(rel);\n    return ext.length > 0 && !exts.includes(ext);\n  }\n\n  function fire(rel: string): void {\n    lastTrigger = rel;\n    if (timer) clearTimeout(timer);\n    timer = setTimeout(() => {\n      timer = undefined;\n      const triggerLabel = lastTrigger ?? '(unknown)';\n      log.reloadEvent('watcher', { trigger: triggerLabel });\n      options.onChange(triggerLabel);\n    }, debounce);\n  }\n\n  return {\n    start() {\n      try {\n        watcher = fs.watch(options.rootDir, { recursive: true }, (_event, filename) => {\n          if (!filename) return;\n          // Node's `fs.watch` types `filename` as `string | null` here\n          // (no `encoding: 'buffer'` option set), so a `typeof filename ===\n          // 'string'` narrow leaves the else-branch as `never` and trips\n          // TS2339. `String(filename)` is defensive for any future widening\n          // (e.g., a `Buffer` arriving via a polyfill) without confusing\n          // the type checker.\n          const rel = String(filename);\n          if (shouldIgnore(rel)) return;\n          fire(rel);\n        });\n        watcher.on('error', (err) => {\n          log.warn('watcher-error', { error: err.message });\n        });\n        log.info('watcher-started', { rootDir: options.rootDir, debounceMs: debounce });\n      } catch (err) {\n        log.error('watcher-start-failed', { error: (err as Error).message });\n      }\n    },\n    stop() {\n      if (timer) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      try {\n        watcher?.close();\n      } catch {\n        // ignore\n      }\n      log.info('watcher-stopped');\n    },\n  };\n}\n"]}

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

@@ -1,2 +1,35 @@
-import { ParsedArgs } from '../../core/args';
+import { type ParsedArgs } from '../../core/args';
+/**
+ * Resolve the port the dev child should bind to and report any conflict
+ * clearly. Returns the chosen port — or never returns and exits the process
+ * with a clear error when the port is busy and `--auto-port` was not set.
+ *
+ * Issue #398: previously the child crashed with a raw `EADDRINUSE` stack
+ * trace; this helper turns that into a one-line message with a suggested
+ * remediation and (optionally) the owning process.
+ */
+export declare function resolveDevPort(opts: {
+    port?: number;
+    autoPort?: boolean;
+    showConflict?: boolean;
+    envPort?: string | undefined;
+    exit?: (code: number) => never;
+    log?: (msg: string) => void;
+}): Promise<number>;
+/**
+ * Build the environment handed to the spawned dev child.
+ *
+ * The resolved port is exported as `PORT`, and the configured
+ * `transport.http.path` (when set) as `FRONTMCP_HTTP_ENTRY_PATH` so the server
+ * mounts the MCP endpoint where the generated client URLs point (#446). Both are
+ * applied AFTER the inherited env so the dev-resolved values win for this run —
+ * the same precedence as `PORT`. A hard-coded `@FrontMcp({ http: { entryPath } })`
+ * in metadata still wins over the env (the SDK only reads it as a default).
+ */
+export declare function buildDevChildEnv(params: {
+    effectiveEnv: NodeJS.ProcessEnv;
+    baseEnv: NodeJS.ProcessEnv;
+    port: number;
+    configHttpPath?: string;
+}): NodeJS.ProcessEnv;
 export declare function runDev(opts: ParsedArgs): Promise<void>;

package/src/commands/dev/dev.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDevPort = resolveDevPort;
+exports.buildDevChildEnv = buildDevChildEnv;
 exports.runDev = runDev;
 const tslib_1 = require("tslib");
-const path = tslib_1.__importStar(require("path"));
 const child_process_1 = require("child_process");
+const path = tslib_1.__importStar(require("path"));
+const config_1 = require("../../config");
 const colors_1 = require("../../core/colors");
-const fs_1 = require("../../shared/fs");
 const env_1 = require("../../shared/env");
+const fs_1 = require("../../shared/fs");
+const port_1 = require("./port");
+const DEFAULT_DEV_PORT = 3000;
 function killQuiet(proc, signal = 'SIGINT') {
     try {
         if (proc && proc.exitCode === null && proc.signalCode === null) {
@@ -17,26 +22,165 @@ function killQuiet(proc, signal = 'SIGINT') {
         // ignore
     }
 }
+/**
+ * Resolve the port the dev child should bind to and report any conflict
+ * clearly. Returns the chosen port — or never returns and exits the process
+ * with a clear error when the port is busy and `--auto-port` was not set.
+ *
+ * Issue #398: previously the child crashed with a raw `EADDRINUSE` stack
+ * trace; this helper turns that into a one-line message with a suggested
+ * remediation and (optionally) the owning process.
+ */
+async function resolveDevPort(opts) {
+    const exit = opts.exit ?? ((code) => process.exit(code));
+    const log = opts.log ?? ((msg) => console.error(msg));
+    const explicit = opts.port ?? (opts.envPort !== undefined && opts.envPort !== '' ? Number(opts.envPort) : undefined);
+    const port = explicit !== undefined && Number.isFinite(explicit) && explicit > 0
+        ? explicit
+        : DEFAULT_DEV_PORT;
+    if (await (0, port_1.isPortFree)(port))
+        return port;
+    if (opts.autoPort) {
+        const alt = await (0, port_1.findNextFreePort)(port + 1);
+        log(`${(0, colors_1.c)('yellow', '[dev]')} port ${port} is in use; auto-picked ${alt}`);
+        return alt;
+    }
+    // Build a clear, actionable error message.
+    const lines = [
+        `${(0, colors_1.c)('red', '[dev]')} Port ${port} is already in use — refusing to start.`,
+        `${(0, colors_1.c)('gray', '      ')} Retry with one of:`,
+        `${(0, colors_1.c)('gray', '        ')} • ${(0, colors_1.c)('bold', `frontmcp dev --port <other-port>`)}`,
+        `${(0, colors_1.c)('gray', '        ')} • ${(0, colors_1.c)('bold', `frontmcp dev --auto-port`)}     ${(0, colors_1.c)('gray', '(pick the next free port automatically)')}`,
+        `${(0, colors_1.c)('gray', '        ')} • ${(0, colors_1.c)('bold', `PORT=<other-port> frontmcp dev`)}`,
+    ];
+    if (opts.showConflict) {
+        const owner = await (0, port_1.lookupPortOwner)(port);
+        if (owner) {
+            lines.push(`${(0, colors_1.c)('gray', '      ')} Holder of ${port}:`);
+            for (const row of owner.split('\n'))
+                lines.push(`${(0, colors_1.c)('gray', '        ')} ${row}`);
+        }
+        else {
+            lines.push(`${(0, colors_1.c)('gray', '      ')} (could not identify the holder of port ${port})`);
+        }
+    }
+    else {
+        lines.push(`${(0, colors_1.c)('gray', '      ')} (pass --show-conflict to print which process is holding the port)`);
+    }
+    for (const line of lines)
+        log(line);
+    return exit(1);
+}
+/**
+ * Build the environment handed to the spawned dev child.
+ *
+ * The resolved port is exported as `PORT`, and the configured
+ * `transport.http.path` (when set) as `FRONTMCP_HTTP_ENTRY_PATH` so the server
+ * mounts the MCP endpoint where the generated client URLs point (#446). Both are
+ * applied AFTER the inherited env so the dev-resolved values win for this run —
+ * the same precedence as `PORT`. A hard-coded `@FrontMcp({ http: { entryPath } })`
+ * in metadata still wins over the env (the SDK only reads it as a default).
+ */
+function buildDevChildEnv(params) {
+    const { effectiveEnv, baseEnv, port, configHttpPath } = params;
+    return {
+        ...effectiveEnv,
+        ...baseEnv,
+        PORT: String(port),
+        ...(configHttpPath !== undefined ? { FRONTMCP_HTTP_ENTRY_PATH: configHttpPath } : {}),
+    };
+}
 async function runDev(opts) {
+    // Issue #399 — `--stdio` runs the first-party watch-aware stdio bridge
+    // instead of the legacy `tsx --watch + tsc --noEmit --watch` pair. The
+    // bridge owns process stdin/stdout (JSON-RPC frames only), holds the
+    // upstream MCP session across child restarts, and replaces the
+    // third-party `mcp-remote` recipe for the dev loop.
+    if (opts.stdio) {
+        const { runDevBridge } = await import('./bridge/index.js');
+        return runDevBridge(opts);
+    }
     const cwd = process.cwd();
-    const entry = await (0, fs_1.resolveEntry)(cwd, opts.entry);
-    // Load .env and .env.local files before starting the server
+    // Issue #400 — resolve frontmcp.config so `entry`, `transport.http.port`,
+    // and `env.shared`/`env.dev` overlays apply. Precedence:
+    //   CLI flag > FRONTMCP_<NAME> env > frontmcp.config field > built-in default.
+    const resolved = await (0, config_1.resolveConfig)({
+        cwd,
+        mode: 'dev',
+        configPath: typeof opts.config === 'string' ? opts.config : undefined,
+    });
+    const cfg = resolved.config;
+    const cliEntry = typeof opts.entry === 'string' ? opts.entry : undefined;
+    const configEntry = typeof cfg?.entry === 'string' ? cfg.entry : undefined;
+    const entry = await (0, fs_1.resolveEntry)(cwd, cliEntry ?? configEntry);
+    // Load .env and .env.local files (these win over config env overlays for
+    // parity with existing behavior — file-based env is the deployment escape
+    // hatch and shouldn't be silently overridden by committed config).
     (0, env_1.loadDevEnv)(cwd);
+    // Resolve the port BEFORE spawning tsx so EADDRINUSE produces a clean
+    // one-line error instead of a raw node:net stack trace (issue #398).
+    //
+    // Two caveats worth knowing about this pre-flight check:
+    //   1. TOCTOU — between this probe returning and the child actually binding,
+    //      another process can grab the port. We accept that race: this is a
+    //      dev-time tool, the worst case reverts to the prior behaviour (the
+    //      child surfaces a raw EADDRINUSE), and the common case (port already
+    //      busy at startup) is the one we wanted to fix.
+    //   2. The resolved port is exported as `PORT` to the child. It only takes
+    //      effect when the user's `@FrontMcp({ http: { port } })` reads
+    //      `process.env.PORT` (the SDK's `httpOptionsSchema` default does).
+    //      If the user's metadata HARD-CODES `http.port`, the child binds to
+    //      that hard-coded value and ignores PORT — the probe is then advisory
+    //      only. Documented in docs/frontmcp/deployment/local-dev-server.mdx.
+    const cliPort = typeof opts.port === 'number' ? opts.port : opts.port ? Number(opts.port) : undefined;
+    const configPort = cfg?.transport?.http?.port;
+    const port = await resolveDevPort({
+        port: cliPort ?? configPort,
+        autoPort: !!opts.autoPort,
+        showConflict: !!opts.showConflict,
+        envPort: process.env['PORT'],
+    });
+    // Issue #446 — honor the configured MCP mount path in dev. `transport.http.path`
+    // already drives the generated client URLs (eject); propagate it to the spawned
+    // server via FRONTMCP_HTTP_ENTRY_PATH so the endpoint is actually mounted there
+    // (the SDK's httpOptionsSchema.entryPath default reads this env). Same precedence
+    // caveat as PORT: a hard-coded `@FrontMcp({ http: { entryPath } })` still wins.
+    const configHttpPath = typeof cfg?.transport?.http?.path === 'string' ? cfg.transport.http.path : undefined;
     console.log(`${(0, colors_1.c)('cyan', '[dev]')} using entry: ${path.relative(cwd, entry)}`);
+    if (resolved.configPath || resolved.configDir) {
+        console.log(`${(0, colors_1.c)('gray', '[dev]')} config: ${resolved.configPath ?? resolved.configDir}`);
+    }
+    console.log(`${(0, colors_1.c)('cyan', '[dev]')} listening on port: ${port}`);
+    if (configHttpPath) {
+        console.log(`${(0, colors_1.c)('gray', '[dev]')} MCP endpoint path: ${configHttpPath}`);
+    }
     console.log(`${(0, colors_1.c)('gray', '[dev]')} starting ${(0, colors_1.c)('bold', 'tsx --watch')} and ${(0, colors_1.c)('bold', 'tsc --noEmit --watch')} (async type-checker)`);
     console.log(`${(0, colors_1.c)('gray', 'hint:')} press Ctrl+C to stop`);
-    // Use --conditions node to ensure proper Node.js module resolution
-    // This helps with dynamic require() calls in packages like ioredis
-    // Only use shell on Windows where npx.cmd requires it; on Unix, direct spawn
-    // allows proper SIGINT propagation without intermediate shell processes
-    const useShell = process.platform === 'win32';
-    const app = (0, child_process_1.spawn)('npx', ['-y', 'tsx', '--conditions', 'node', '--watch', entry], {
+    // Use --conditions node to ensure proper Node.js module resolution.
+    // This helps with dynamic require() calls in packages like ioredis.
+    // On Windows resolve npx.cmd directly — previously we passed shell:true
+    // for the .cmd suffix, but that triggers Node DEP0190 (#381) every run.
+    // spawn() resolves .cmd via CreateProcessW since Node 16, so no shell is
+    // needed; on Unix spawn() works on 'npx' directly. SIGINT still
+    // propagates cleanly because no intermediate shell sits between us and
+    // the child process.
+    const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    // Issue #400 — env overlays from `frontmcp.config.env.{shared,dev}` are
+    // included via `resolved.effectiveEnv`. `.env`/`.env.local` already loaded
+    // into `process.env` above, so they win (they're closer to deployment).
+    const childEnv = buildDevChildEnv({
+        effectiveEnv: resolved.effectiveEnv,
+        baseEnv: process.env,
+        port,
+        configHttpPath,
+    });
+    const app = (0, child_process_1.spawn)(npxCmd, ['-y', 'tsx', '--conditions', 'node', '--watch', entry], {
         stdio: 'inherit',
-        shell: useShell,
+        env: childEnv,
     });
-    const checker = (0, child_process_1.spawn)('npx', ['-y', 'tsc', '--noEmit', '--pretty', '--watch'], {
+    const checker = (0, child_process_1.spawn)(npxCmd, ['-y', 'tsc', '--noEmit', '--pretty', '--watch'], {
         stdio: 'inherit',
-        shell: useShell,
+        env: childEnv,
     });
     const cleanup = (clearTimer = true) => {
         if (clearTimer) {
@@ -95,8 +239,13 @@ async function runDev(opts) {
         cleanup();
         process.exit(0);
     });
+    let appExitCode = 0;
     await new Promise((resolve, reject) => {
-        app.on('close', () => {
+        app.on('close', (code) => {
+            // Capture the child's exit code so it can propagate to the parent
+            // shell. SIGINT/SIGTERM yield code=null with a signalCode — treat
+            // those as 0 so Ctrl+C doesn't appear as a failure.
+            appExitCode = typeof code === 'number' ? code : 0;
             markClosed('app');
             cleanup(false);
             resolve();
@@ -115,5 +264,10 @@ async function runDev(opts) {
             reject(err);
         });
     });
+    // Propagate the child's exit code so CI / shells see real failures
+    // instead of always-success.
+    if (appExitCode && appExitCode !== 0) {
+        process.exit(appExitCode);
+    }
 }
 //# sourceMappingURL=dev.js.map