@jonathanleelx/meddle 0.5.0-beta.9 → 0.5.0

package/bin/lib/output.js

@@ -51,11 +51,13 @@ function success(message) {
 }
 
 /**
- * Print error message
+ * Print a command failure. Human-readable text goes to stderr so stdout stays
+ * empty on error. In --json mode this is a no-op; the caller prints the
+ * `{ success: false }` object on stdout.
  */
 function error(message) {
   if (jsonMode) return
-  console.log(chalk.red('  ✗'), message)
+  console.error(chalk.red('  ✗'), message)
 }
 
 /**
@@ -128,6 +130,23 @@ function tableRow(columns, widths) {
   console.log('  ' + row)
 }
 
+/**
+ * Shared downgrade warning when CLI mutates config but cannot reach a live proxy
+ * (issue #85). Same wording for mock + route families.
+ */
+const FILE_ONLY_WARNING =
+  'Config written to file, but could not connect to a running proxy — restart required for changes to take effect.'
+
+/**
+ * Emit the file-only downgrade warning. Always prints to stderr (including
+ * --json mode) so the failure mode is never silent.
+ * @returns {string} the warning message
+ */
+function warnFileOnlyMode() {
+  console.error(chalk.yellow('  ⚠'), FILE_ONLY_WARNING)
+  return FILE_ONLY_WARNING
+}
+
 module.exports = {
   setJsonMode,
   isJsonMode,
@@ -142,5 +161,7 @@ module.exports = {
   plain,
   kv,
   bullet,
-  tableRow
+  tableRow,
+  FILE_ONLY_WARNING,
+  warnFileOnlyMode,
 }

package/bin/lib/proxy-detect.js

@@ -6,6 +6,15 @@
  * every CLI command session-aware without individual changes: when
  * --session <id> is set, MEDDLE_HOME is pinned to the session's data dir
  * and getProxyUrl() returns that session's port.
+ *
+ * Probe priority (issue #85):
+ *   1. MEDDLE_SESSION_PORT (pinned session)
+ *   2. mcp-proxy-url.json (written by proxy on every start)
+ *   3. DEFAULT_PROXY_BASE (http://127.0.0.1:8989)
+ *
+ * Stale ports in mcp-proxy-url.json must not stick forever: isProxyRunning /
+ * resolveLiveProxyUrl fall through to later candidates when a probe fails,
+ * and cache the first live URL for subsequent getProxyUrl() / API calls.
  */
 
 const fs = require('fs')
@@ -16,39 +25,61 @@ const { applySessionContext, GLOBAL_DEFAULT_PORT } = require('./session-args')
 // Apply --session / MEDDLE_HOME precedence before computing paths.
 applySessionContext()
 
+// Resolved once for CLI (MEDDLE_HOME is set before this module loads).
 const meddleDir = resolveMeddleHome()
 const mcpFile = path.join(meddleDir, 'mcp-proxy-url.json')
 const DEFAULT_PROXY_BASE = `http://127.0.0.1:${GLOBAL_DEFAULT_PORT}`
 
+/** @type {string | null} */
+let resolvedProxyUrl = null
+
+function getMcpFilePath() {
+  // Prefer live MEDDLE_HOME so tests can point at a temp home after require.
+  const home = (process.env.MEDDLE_HOME || '').trim() || meddleDir
+  return path.join(home, 'mcp-proxy-url.json')
+}
+
 /**
- * Get proxy URL.
- *
- * Priority:
- *   1. MEDDLE_SESSION_PORT env (set by --session resolution)
- *   2. mcp-proxy-url.json (written by proxy on startup)
- *   3. DEFAULT_PROXY_BASE (http://127.0.0.1:8989)
+ * Sync best-effort URL (no liveness check). Prefer a previously resolved live
+ * URL so API calls after isProxyRunning() hit the working port.
  */
 function getProxyUrl() {
+  if (resolvedProxyUrl) return resolvedProxyUrl
+  const candidates = getCandidateProxyUrls()
+  return candidates[0] || DEFAULT_PROXY_BASE
+}
+
+/**
+ * Ordered candidate URLs to probe (deduped).
+ * Session pin is exclusive — do not fall back to global file/default.
+ */
+function getCandidateProxyUrls() {
   if (process.env.MEDDLE_SESSION_PORT) {
-    return `http://127.0.0.1:${process.env.MEDDLE_SESSION_PORT}`
+    return [`http://127.0.0.1:${process.env.MEDDLE_SESSION_PORT}`]
   }
+  const urls = []
   try {
-    if (fs.existsSync(mcpFile)) {
-      const data = JSON.parse(fs.readFileSync(mcpFile, 'utf8'))
-      if (data.proxyUrl) return data.proxyUrl
+    const file = getMcpFilePath()
+    if (fs.existsSync(file)) {
+      const data = JSON.parse(fs.readFileSync(file, 'utf8'))
+      if (data.proxyUrl && typeof data.proxyUrl === 'string') {
+        urls.push(data.proxyUrl.replace(/\/$/, ''))
+      }
     }
   } catch (_) {}
-  return DEFAULT_PROXY_BASE
+  if (!urls.includes(DEFAULT_PROXY_BASE)) {
+    urls.push(DEFAULT_PROXY_BASE)
+  }
+  return urls
 }
 
 /**
- * Check if proxy is running by attempting to connect
- * @param {number} timeoutMs - Timeout in milliseconds (default 2000)
+ * @param {string} url
+ * @param {number} timeoutMs
  */
-async function isProxyRunning(timeoutMs = 2000) {
-  const url = getProxyUrl()
+async function probeUrl(url, timeoutMs = 2000) {
   try {
-    const response = await fetch(url + '/api/mocks', {
+    const response = await fetch(url.replace(/\/$/, '') + '/api/mocks', {
       method: 'GET',
       signal: AbortSignal.timeout(timeoutMs)
     })
@@ -58,6 +89,38 @@ async function isProxyRunning(timeoutMs = 2000) {
   }
 }
 
+/**
+ * Probe candidates in order; cache and return the first live URL, or null.
+ * @param {number} timeoutMs
+ * @param {(url: string, timeoutMs: number) => Promise<boolean>} [probe]
+ */
+async function resolveLiveProxyUrl(timeoutMs = 2000, probe = probeUrl) {
+  if (resolvedProxyUrl) {
+    const perTry = Math.min(timeoutMs, 800)
+    if (await probe(resolvedProxyUrl, perTry)) return resolvedProxyUrl
+    resolvedProxyUrl = null
+  }
+
+  const candidates = getCandidateProxyUrls()
+  const perTry = Math.max(200, Math.floor(timeoutMs / Math.max(1, candidates.length)))
+  for (const url of candidates) {
+    if (await probe(url, perTry)) {
+      resolvedProxyUrl = url
+      return url
+    }
+  }
+  return null
+}
+
+/**
+ * Check if proxy is running by probing candidates (file → default fallback).
+ * @param {number} timeoutMs - Timeout in milliseconds (default 2000)
+ */
+async function isProxyRunning(timeoutMs = 2000) {
+  const url = await resolveLiveProxyUrl(timeoutMs)
+  return !!url
+}
+
 /**
  * Wait for proxy to start
  * @param {number} timeoutMs - Timeout in milliseconds (default 5000)
@@ -69,15 +132,15 @@ function waitForProxyUrl(timeoutMs = 5000) {
     const check = () => {
       try {
         if (process.env.MEDDLE_SESSION_PORT) {
-          // For --session mode, poll the HTTP endpoint directly.
           const port = process.env.MEDDLE_SESSION_PORT
           fetch(`http://127.0.0.1:${port}/api/mocks`, { method: 'GET', signal: AbortSignal.timeout(500) })
             .then((r) => { if (r.ok) resolve(`http://127.0.0.1:${port}`); else retry() })
             .catch(() => retry())
           return
         }
-        if (fs.existsSync(mcpFile)) {
-          const data = JSON.parse(fs.readFileSync(mcpFile, 'utf8'))
+        const file = getMcpFilePath()
+        if (fs.existsSync(file)) {
+          const data = JSON.parse(fs.readFileSync(file, 'utf8'))
           if (data.proxyUrl) {
             return resolve(data.proxyUrl)
           }
@@ -95,11 +158,27 @@ function waitForProxyUrl(timeoutMs = 5000) {
   })
 }
 
+/** Test-only: clear cached live URL so the next probe re-reads candidates. */
+function __resetResolvedProxyUrlForTest() {
+  resolvedProxyUrl = null
+}
+
+/** Test-only: seed the cached live URL. */
+function __setResolvedProxyUrlForTest(url) {
+  resolvedProxyUrl = url || null
+}
+
 module.exports = {
   meddleDir,
   mcpFile,
   DEFAULT_PROXY_BASE,
   getProxyUrl,
+  getCandidateProxyUrls,
+  getMcpFilePath,
+  resolveLiveProxyUrl,
+  probeUrl,
   isProxyRunning,
-  waitForProxyUrl
+  waitForProxyUrl,
+  __resetResolvedProxyUrlForTest,
+  __setResolvedProxyUrlForTest,
 }

package/bin/lib/proxy-or-file.js

@@ -0,0 +1,90 @@
+/**
+ * Decide whether a proxy API failure may fall back to a direct file write.
+ *
+ * Fall back only when the proxy is not running, or the request fails before
+ * any HTTP response (connection refused, timeout, DNS). A 4xx/5xx is the
+ * proxy's answer: callers print that body and must not touch the file.
+ * Treating a 409 (corrupt mocks.json) as "proxy down" rewrote the file and
+ * dropped every existing rule.
+ */
+
+const output = require('./output')
+const { isProxyRunning } = require('./proxy-detect')
+
+const UNREACHABLE_CODES = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'EPIPE',
+  'ETIMEDOUT',
+  'ECONNABORTED',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_SOCKET',
+  'UND_ERR_HEADERS_TIMEOUT',
+])
+
+function causeCode(err) {
+  if (!err || typeof err !== 'object') return undefined
+  if (err.code && err.code !== 'MOCKS_FILE_INVALID') return err.code
+  if (err.cause) return causeCode(err.cause)
+  return undefined
+}
+
+/** True when the proxy answered with an HTTP 4xx/5xx (api-client sets err.status). */
+function isApiHttpError(err) {
+  const status = err && err.status
+  return Number.isInteger(status) && status >= 400 && status <= 599
+}
+
+/**
+ * True when we never got an HTTP response: connection refused, DNS, reset,
+ * timeout, or undici's `TypeError: fetch failed`.
+ */
+function isProxyUnreachableError(err) {
+  if (!err || isApiHttpError(err)) return false
+  if (err.name === 'AbortError' || err.name === 'TimeoutError') return true
+  const code = causeCode(err)
+  if (code && UNREACHABLE_CODES.has(code)) return true
+  if (err.name === 'TypeError' && err.message === 'fetch failed') return true
+  return false
+}
+
+/**
+ * Call the proxy when it is up. `file` runs only when it is down or the
+ * request never received an HTTP response. HTTP errors reject.
+ *
+ * @param {{ api: () => Promise<any>, file: () => any }} opts
+ * @returns {Promise<{ fileOnly: boolean, value: any }>}
+ */
+async function withProxyOrFile({ api, file }) {
+  const running = await isProxyRunning()
+  if (!running) return { fileOnly: true, value: file() }
+  try {
+    return { fileOnly: false, value: await api() }
+  } catch (err) {
+    if (!isProxyUnreachableError(err)) throw err
+    return { fileOnly: true, value: file() }
+  }
+}
+
+/**
+ * Exit 1. An HTTP error's message is the response body and is printed as-is.
+ * `err.rawStderr` prints `err.message` with no `✗` prefix (mock list).
+ * Other human-mode failures use the CLI `✗` style.
+ */
+function failCommand(err) {
+  const message = err && err.message ? String(err.message) : String(err)
+  if (isApiHttpError(err) || (err && err.rawStderr) || output.isJsonMode()) console.error(message)
+  else output.error(message)
+  process.exit(1)
+}
+
+module.exports = {
+  isApiHttpError,
+  isProxyUnreachableError,
+  withProxyOrFile,
+  failCommand,
+}

package/bin/lib/route-write-args.js

@@ -0,0 +1,150 @@
+/**
+ * Argument parsing for `meddle route add|update|delete` (issue #149).
+ *
+ * `--exclusions=` clears a rule's exclusions. `--exclusions=/a,/b` replaces
+ * them. A bare `--exclusions`, an unknown flag, or an empty `!` token used to
+ * be ignored and the command still exited 0 without changing exclusions.
+ */
+
+const { splitPatternArg } = require('./rule-file-edit')
+
+class RouteArgError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'RouteArgError'
+  }
+}
+
+const CLEAR_HINT = 'To clear exclusions, pass --exclusions= (empty). To replace them, pass --exclusions=/a,/b.'
+
+/**
+ * @param {string} raw value after `=`
+ * @returns {string[]}
+ */
+function parseExclusionList(raw) {
+  const value = String(raw).trim()
+  if (value === '') return []
+  const pieces = value.includes(',') ? value.split(',') : value.split(/\s+/)
+  const out = []
+  for (const piece of pieces) {
+    const token = piece.trim()
+    if (!token) {
+      throw new RouteArgError(`Invalid --exclusions: empty entry. ${CLEAR_HINT}`)
+    }
+    const body = token.startsWith('!') ? token.slice(1).trim() : token
+    if (!body) {
+      throw new RouteArgError(`Invalid --exclusions: "!" needs a path, for example --exclusions=/health. ${CLEAR_HINT}`)
+    }
+    out.push(body)
+  }
+  return out
+}
+
+/**
+ * @param {string[]} args argv after the subcommand
+ * @param {{ allowExclusions?: boolean }} [options]
+ * @returns {{ help: boolean, json: boolean, positional: string[], exclusions: string[] | undefined }}
+ * `exclusions` is undefined when the flag was not passed. `[]` means clear.
+ */
+function parseRouteWriteArgs(args, { allowExclusions = true } = {}) {
+  let help = false
+  let json = false
+  /** @type {string[] | undefined} */
+  let exclusions
+  let sawExclusions = false
+  const positional = []
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--help' || arg === '-h') {
+      help = true
+      continue
+    }
+    if (arg === '--json') {
+      json = true
+      continue
+    }
+    if (arg === '--exclusions' || arg.startsWith('--exclusions=')) {
+      if (!allowExclusions) {
+        throw new RouteArgError(`Unsupported option: ${arg === '--exclusions' ? '--exclusions' : '--exclusions='}. route delete does not change exclusions.`)
+      }
+      if (arg === '--exclusions') {
+        throw new RouteArgError(`Unsupported option: --exclusions. ${CLEAR_HINT}`)
+      }
+      if (sawExclusions) throw new RouteArgError('--exclusions was given more than once.')
+      sawExclusions = true
+      exclusions = parseExclusionList(arg.slice('--exclusions='.length))
+      continue
+    }
+    if (arg.startsWith('-')) {
+      throw new RouteArgError(`Unsupported option: ${arg}.`)
+    }
+    positional.push(arg)
+  }
+
+  return { help, json, positional, exclusions: sawExclusions ? exclusions : undefined }
+}
+
+/**
+ * Split a pattern argument the way the CLI always has (`"host !/api"`), but
+ * refuse a bare `!` — that used to be dropped and looked like a successful clear.
+ * @returns {{ patterns: string[], exclusions: string[] }}
+ */
+function parsePatternArg(raw) {
+  const parts = String(raw).trim().split(/\s+/).filter(Boolean)
+  for (const part of parts) {
+    if (part.startsWith('!') && part.slice(1).trim() === '') {
+      throw new RouteArgError('Invalid exclusion "!": a "!" token needs a path such as "!/api". To clear exclusions, pass --exclusions=.')
+    }
+  }
+  return splitPatternArg(raw)
+}
+
+/**
+ * @param {string[]} patternExclusions exclusions parsed from !path tokens
+ * @param {string[] | undefined} flagExclusions undefined when --exclusions was omitted
+ * @returns {{ explicit: boolean, exclusions: string[] | undefined }}
+ */
+function resolveExclusions(patternExclusions, flagExclusions) {
+  if (flagExclusions !== undefined && patternExclusions.length > 0) {
+    throw new RouteArgError('Pass exclusions either as !path tokens in the pattern or with --exclusions, not both.')
+  }
+  if (flagExclusions !== undefined) return { explicit: true, exclusions: flagExclusions }
+  if (patternExclusions.length > 0) return { explicit: true, exclusions: patternExclusions }
+  return { explicit: false, exclusions: undefined }
+}
+
+const UPDATE_HELP = `
+meddle route update <file> <pattern> [<target>] [--exclusions=<list>] [--json]
+
+Update a rule. Edits only the line(s) that hold the pattern; every other line
+stays byte-for-byte, including comments, blank lines and other rules' !path.
+
+  --exclusions=            Clear this rule's exclusions (the line loses !path).
+  --exclusions=/a,/b       Replace exclusions. Spaces work inside quotes
+                           (--exclusions="/a /b"). A leading ! is optional.
+  "pattern !/a !/b"        Replace exclusions (same as before). Omit both
+                           --exclusions and !path to keep existing exclusions.
+
+The <target> may be omitted when --exclusions is set; the current target stays.
+A bare --exclusions, an empty "!" token, an unknown flag, or both exclusion
+forms at once exits 1 and does not change the file.
+
+A "#" comments out a whole line only when it is the first non-space character.
+A "#" later on a rule line is a pattern token, not a trailing comment.
+
+Examples:
+  meddle route update dev "api.example.com" "localhost:4000"
+  meddle route update dev "api.example.com" --exclusions=
+  meddle route update dev "api.example.com" "localhost:4000" --exclusions=/health
+`
+
+module.exports = {
+  CLEAR_HINT,
+  RouteArgError,
+  UPDATE_HELP,
+  parseExclusionList,
+  parsePatternArg,
+  parseRouteWriteArgs,
+  resolveExclusions,
+}