@jonathanleelx/meddle 0.5.0-beta.9 → 0.5.1

package/bin/lib/file-access.js

@@ -5,6 +5,7 @@
 const fs = require('fs')
 const path = require('path')
 const { meddleDir } = require('./proxy-detect')
+const { RulesetReadonlyError } = require('./ruleset-readonly')
 
 const routeRulesDir = path.join(meddleDir, 'route-rules')
 const settingsPath = path.join(meddleDir, 'settings.json')
@@ -51,6 +52,33 @@ function setActiveRuleFileNames(names) {
   saveSettings(settings)
 }
 
+/**
+ * Issue #137: locked rule files (settings.json `readonlyRuleFiles`). Entries
+ * whose file no longer exists are dropped silently. A missing field = none locked.
+ */
+function getReadonlyRuleFileNames() {
+  const settings = loadSettings()
+  if (!Object.prototype.hasOwnProperty.call(settings, 'readonlyRuleFiles')) return []
+  const raw = settings.readonlyRuleFiles
+  const names = Array.isArray(raw) ? raw.filter((n, i, arr) => typeof n === 'string' && n && arr.indexOf(n) === i) : []
+  const live = names.filter((name) => fs.existsSync(path.join(routeRulesDir, `${name}.txt`)))
+  if (!Array.isArray(raw) || live.length !== raw.length) {
+    settings.readonlyRuleFiles = live
+    saveSettings(settings)
+  }
+  return live
+}
+
+function isRuleFileReadonly(name) {
+  const fold = (n) => (process.platform === 'darwin' || process.platform === 'win32' ? n.toLowerCase() : n)
+  return getReadonlyRuleFileNames().some((item) => fold(item) === fold(name))
+}
+
+/** Throws RulesetReadonlyError (code RULESET_READONLY) for a locked rule file. */
+function assertRuleFileWritable(name) {
+  if (isRuleFileReadonly(name)) throw new RulesetReadonlyError(name)
+}
+
 // ========== Mocks ==========
 
 /**
@@ -62,36 +90,180 @@ function getMocksPath() {
 }
 
 /**
- * Load mock rules from file
+ * Offset of the first JSON syntax error. Kept in sync with
+ * core/mock-handler.ts findJsonErrorOffset (V8 often omits a position).
  */
-function loadMockRules() {
-  const mocksPath = getMocksPath()
-  try {
-    if (fs.existsSync(mocksPath)) {
-      const data = JSON.parse(fs.readFileSync(mocksPath, 'utf8'))
-      return data.rules || []
+function findJsonErrorOffset(t) {
+  let i = 0
+  const ws = () => { while (i < t.length && ' \t\n\r'.includes(t[i])) i++ }
+  const fail = () => { throw i }
+  const str = () => {
+    i++
+    while (i < t.length && t[i] !== '"') {
+      if (t[i] === '\\') i++
+      else if (t.charCodeAt(i) < 0x20) fail()
+      i++
     }
-  } catch (_) {}
-  return []
+    if (i >= t.length) fail()
+    i++
+  }
+  const value = () => {
+    ws()
+    const c = t[i]
+    if (c === '{') {
+      i++; ws()
+      if (t[i] === '}') { i++; return }
+      for (;;) {
+        ws(); if (t[i] !== '"') fail(); str(); ws()
+        if (t[i] !== ':') fail(); i++; value(); ws()
+        if (t[i] === ',') { i++; continue }
+        if (t[i] === '}') { i++; return }
+        fail()
+      }
+    } else if (c === '[') {
+      i++; ws()
+      if (t[i] === ']') { i++; return }
+      for (;;) {
+        value(); ws()
+        if (t[i] === ',') { i++; continue }
+        if (t[i] === ']') { i++; return }
+        fail()
+      }
+    } else if (c === '"') str()
+    else if (/[-0-9]/.test(c || '')) {
+      const m = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/.exec(t.slice(i))
+      if (!m) fail(); i += m[0].length
+    } else {
+      for (const w of ['true', 'false', 'null']) if (t.startsWith(w, i)) { i += w.length; return }
+      fail()
+    }
+  }
+  try {
+    value(); ws()
+    return i < t.length ? i : t.length
+  } catch (at) {
+    return typeof at === 'number' ? Math.min(at, t.length) : t.length
+  }
+}
+
+/** `第 <line> 行第 <column> 列：<short message>`, same rules as core/mock-handler.ts. */
+function describeMocksParseFailure(text, err) {
+  const message = String((err && err.message) || err)
+  const body = text.replace(/^\uFEFF/, '')
+  let line = null
+  let column = null
+  const lc = /\(line (\d+) column (\d+)\)/.exec(message)
+  const pos = /at position (\d+)/.exec(message)
+  const offset = lc ? null : pos ? Number(pos[1]) : findJsonErrorOffset(body)
+  if (lc) {
+    line = Number(lc[1]); column = Number(lc[2])
+  } else {
+    const before = body.slice(0, offset == null ? body.length : offset).split('\n')
+    line = before.length
+    column = before[before.length - 1].length + 1
+  }
+  const short = message.replace(/\s*\(line \d+ column \d+\)/, '').split(/,\s*(?:\.\.\.)?"/s)[0].replace(/\s+in JSON at position \d+/, '').trim()
+  const loc = line != null ? `第 ${line} 行第 ${column} 列：` : ''
+  return `${loc}${short}`
+}
+
+const MOCKS_MISSING_RULES_MESSAGE = '缺少 rules 数组'
+
+function mocksDocumentShapeError(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.rules)) {
+    return MOCKS_MISSING_RULES_MESSAGE
+  }
+  return null
+}
+
+function throwMocksFileInvalid(mocksPath, detail) {
+  const error = new Error(`Mock 文件格式错误，已禁止写入以免覆盖: ${mocksPath} ${detail}`)
+  error.code = 'MOCKS_FILE_INVALID'
+  error.filePath = mocksPath
+  error.detail = detail
+  error.listMessage = `Mock 文件格式错误: ${mocksPath} ${detail}`
+  throw error
 }
 
 /**
- * Save mock rules to file
+ * Read mocks.json. Missing file → null. Empty / whitespace → {}.
+ * Invalid JSON or a valid document with the wrong shape (issue #160, e.g. a
+ * top-level array) throws MOCKS_FILE_INVALID and must not be treated as [].
+ * `message` refuses a write; `listMessage` is what `mock list` prints.
  */
-function saveMockRules(rules) {
-  const mocksPath = getMocksPath()
-  const dir = path.dirname(mocksPath)
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+function readMocksDocument(mocksPath) {
+  if (!fs.existsSync(mocksPath)) return null
+  const text = fs.readFileSync(mocksPath, 'utf8').replace(/^\uFEFF/, '')
+  if (text.trim() === '') return {}
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch (err) {
+    throwMocksFileInvalid(mocksPath, describeMocksParseFailure(text, err))
+  }
+  const shape = mocksDocumentShapeError(data)
+  if (shape) throwMocksFileInvalid(mocksPath, shape)
+  return data
+}
+
+function rulesFromDocument(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.rules)) return []
+  return data.rules
+}
+
+function metaFromDocument(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return { nextId: 0, lastId: 0 }
+  return { nextId: Number(data.nextId) || 0, lastId: Number(data.lastId) || 0 }
+}
+
+/**
+ * Load mock rules from file. A corrupt file throws; it is not an empty list.
+ */
+function loadMockRules() {
+  const data = readMocksDocument(getMocksPath())
+  if (data == null) return []
+  return rulesFromDocument(data)
+}
 
-  // Find max id for sequence
+function readMocksFileMeta(mocksPath) {
+  const data = readMocksDocument(mocksPath)
+  if (data == null) return { nextId: 0, lastId: 0 }
+  return metaFromDocument(data)
+}
+
+function maxRuleId(rules) {
   let maxId = 0
   rules.forEach(r => {
-    if (r.id > maxId) maxId = r.id
+    if (r && Number.isInteger(r.id) && r.id > maxId) maxId = r.id
   })
+  return maxId
+}
 
+/**
+ * Next id to hand out. Shares the server's `nextId` field so ids stay
+ * monotonic across CLI file-mode and the running proxy (issue #115); also
+ * honours the legacy CLI `lastId` field.
+ */
+function nextMockId(rules, meta) {
+  return Math.max(1, meta.nextId || 0, (meta.lastId || 0) + 1, maxRuleId(rules) + 1)
+}
+
+/**
+ * Save mock rules to file
+ */
+function saveMockRules(rules, nextId) {
+  const mocksPath = getMocksPath()
+  const dir = path.dirname(mocksPath)
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+
+  const meta = readMocksFileMeta(mocksPath)
+  const seq = Math.max(nextId || 0, nextMockId(rules, meta))
   const data = {
+    // `nextId` is what the proxy reads; keep it so deleting the newest rule
+    // does not make its id reusable (issue #115). `lastId` kept for older CLIs.
+    nextId: seq,
     rules,
-    lastId: maxId
+    lastId: seq - 1
   }
   fs.writeFileSync(mocksPath, JSON.stringify(data, null, 2), 'utf8')
 }
@@ -103,23 +275,14 @@ function addMockRule(rule) {
   const rules = loadMockRules()
   const mocksPath = getMocksPath()
 
-  // Get next id
-  let nextId = 1
-  try {
-    if (fs.existsSync(mocksPath)) {
-      const data = JSON.parse(fs.readFileSync(mocksPath, 'utf8'))
-      nextId = (data.lastId || 0) + 1
-    }
-  } catch (_) {}
-  if (rules.length > 0) {
-    const maxId = Math.max(...rules.map(r => r.id))
-    if (maxId >= nextId) nextId = maxId + 1
-  }
+  // Issue #115: never reuse an existing (or previously handed-out) id, and
+  // ignore any id the caller put on the rule — add never overwrites.
+  const nextId = nextMockId(rules, readMocksFileMeta(mocksPath))
 
-  rule.id = nextId
-  rules.push(rule)
-  saveMockRules(rules)
-  return rule
+  const created = { ...rule, id: nextId }
+  rules.push(created)
+  saveMockRules(rules, nextId + 1)
+  return created
 }
 
 /**
@@ -167,6 +330,30 @@ function getRuleFilePath(name) {
 /**
  * List all rule files
  */
+function getRuleFileOrderNames() {
+  const settings = loadSettings()
+  const arr = settings.ruleFileOrder
+  return Array.isArray(arr) ? arr.filter((name) => typeof name === 'string') : []
+}
+
+function resolveRuleFileOrder(diskNames, storedOrder, activeNames) {
+  const diskSet = new Set(diskNames)
+  const ordered = []
+  const seen = new Set()
+  const pushUnique = (name) => {
+    if (!diskSet.has(name) || seen.has(name)) return
+    ordered.push(name)
+    seen.add(name)
+  }
+  if (storedOrder.length > 0) {
+    for (const name of storedOrder) pushUnique(name)
+  } else {
+    for (const name of activeNames) pushUnique(name)
+  }
+  for (const name of diskNames) pushUnique(name)
+  return ordered
+}
+
 function listRuleFiles() {
   ensureRouteRulesDir()
   const activeNames = getActiveRuleFileNames()
@@ -175,7 +362,10 @@ function listRuleFiles() {
     .filter(f => f.endsWith('.txt'))
     .map(f => f.replace(/\.txt$/, ''))
 
-  return files.map(name => {
+  const ordered = resolveRuleFileOrder(files, getRuleFileOrderNames(), activeNames)
+  const readonlyNames = new Set(getReadonlyRuleFileNames())
+
+  return ordered.map(name => {
     const filePath = getRuleFilePath(name)
     let ruleCount = 0
     let excludeCount = 0
@@ -191,6 +381,7 @@ function listRuleFiles() {
     return {
       name,
       enabled: activeNames.includes(name),
+      readonly: readonlyNames.has(name),
       ruleCount,
       excludeCount
     }
@@ -215,6 +406,7 @@ function getRuleFileContent(name) {
  */
 function saveRuleFileContent(name, content) {
   ensureRouteRulesDir()
+  assertRuleFileWritable(name)
   const filePath = getRuleFilePath(name)
   fs.writeFileSync(filePath, content, 'utf8')
 }
@@ -231,6 +423,8 @@ function createRuleFile(name, content = '', enabled = true) {
     throw new Error(`规则文件 "${safeName}" 已存在`)
   }
 
+  // Drop stale lock entries so a new file never inherits an old lock.
+  getReadonlyRuleFileNames()
   fs.writeFileSync(filePath, content, 'utf8')
 
   if (enabled) {
@@ -242,7 +436,7 @@ function createRuleFile(name, content = '', enabled = true) {
   }
 
   const ruleCount = content.trim() ? Object.keys(parseEprc(content)).length : 0
-  return { name: safeName, enabled, ruleCount }
+  return { name: safeName, enabled, readonly: false, ruleCount }
 }
 
 /**
@@ -253,6 +447,7 @@ function deleteRuleFile(name) {
   if (!fs.existsSync(filePath)) {
     throw new Error('规则文件不存在')
   }
+  assertRuleFileWritable(name)
   fs.unlinkSync(filePath)
 
   const activeNames = getActiveRuleFileNames()
@@ -274,6 +469,7 @@ function setRuleFileEnabled(name, enabled) {
 
   const activeNames = getActiveRuleFileNames()
   const idx = activeNames.indexOf(name)
+  if ((enabled && idx === -1) || (!enabled && idx !== -1)) assertRuleFileWritable(name)
 
   if (enabled && idx === -1) {
     activeNames.push(name)
@@ -309,6 +505,9 @@ module.exports = {
   saveSettings,
   getActiveRuleFileNames,
   setActiveRuleFileNames,
+  getReadonlyRuleFileNames,
+  isRuleFileReadonly,
+  assertRuleFileWritable,
 
   // Mocks
   getMocksPath,

package/bin/lib/meddle-home.js

@@ -17,4 +17,17 @@ function resolveMeddleHome() {
     return path.resolve(os.homedir(), '.meddle')
 }
 
-module.exports = { resolveMeddleHome }
+/**
+ * Same rules as core/mock-handler.resolveConfiguredMocksPath: `~` expands to
+ * the user home directory; a relative path is resolved against MEDDLE_HOME.
+ */
+function resolveConfiguredMocksPath(raw, meddleDir, homeDir = os.homedir()) {
+    const v = typeof raw === 'string' ? raw.trim() : ''
+    if (!v) return null
+    let p = v
+    if (p === '~') p = homeDir
+    else if (p.startsWith('~/') || p.startsWith('~\\')) p = path.join(homeDir, p.slice(2))
+    return path.resolve(meddleDir, p)
+}
+
+module.exports = { resolveMeddleHome, resolveConfiguredMocksPath }

package/bin/lib/output.js

@@ -51,11 +51,18 @@ 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 stdout is one `{ success: false }` object and
+ * the same message is copied to stderr without a `✗` prefix.
  */
 function error(message) {
-  if (jsonMode) return
-  console.log(chalk.red('  ✗'), message)
+  if (jsonMode) {
+    const text = String(message)
+    console.log(JSON.stringify({ success: false, error: { message: text } }))
+    console.error(text)
+    return
+  }
+  console.error(chalk.red('  ✗'), message)
 }
 
 /**
@@ -128,6 +135,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 +166,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,
 }