@jonathanleelx/meddle 0.5.0-beta.8 → 0.5.0

package/CONFIG_STRUCTURE.md

@@ -173,6 +173,11 @@ https://localhost:13001/micro/app?a=1
     "默认规则",
     "beta-rules"
   ],
+  "ruleFileOrder": [
+    "默认规则",
+    "beta-rules",
+    "disabled-rules"
+  ],
   "mocksFilePath": "",
   "pluginMode": "off",
   "clientAliases": {
@@ -198,6 +203,8 @@ https://localhost:13001/micro/app?a=1
 | `fontSize` | 界面缩放百分比字符串，例如 `100` |
 | `detailBodySizeKB` | 日志详情保存的请求/响应体截断阈值（KB），默认 `256`；调大可保留更大 body 便于排查，但会增加内存占用（最多 `MAX_DETAIL_SIZE=200` 条同时驻留）。作用范围为单个 session，解析顺序：当前 session 的 `settings.json` → 默认 session（`~/.meddle/settings.json`，仅非默认 session 继承）→ 环境变量 `MEDDLE_MAX_DETAIL_BODY_KB` → 默认 `256`。修改后下次请求即生效（基于 mtime 缓存检测） |
 | `activeRuleFiles` | 当前启用的路由规则文件名称，顺序即合并顺序 |
+| `ruleFileOrder` | Web 规则文件 Tab 的完整显示顺序（含禁用文件）；启用文件的合并顺序与其在该数组中的相对顺序一致 |
+| `readonlyRuleFiles` | 只读（加锁）的规则文件名称。可选，缺省即全部可读写。只能在 Web 界面中修改；锁住的规则文件拒绝 CLI / MCP / API 的一切写入。见 [只读规则集](./docs/RULESET_READONLY.md) |
 | `mocksFilePath` | 自定义 Mock JSON 路径；空值使用默认位置 |
 | `pluginMode` | 插件 Pipeline 模式：`off`、`shadow` 或 `on` |
 | `clientAliases` | 客户端 IP 到设备名称的映射 |
@@ -223,8 +230,8 @@ https://localhost:13001/micro/app?a=1
 
 ### 路由规则
 
-1. 读取 `~/.meddle/settings.json` 中的 `activeRuleFiles`。
-2. 按数组顺序读取 `~/.meddle/route-rules/<名称>.txt`。
+1. 读取 `~/.meddle/settings.json` 中的 `activeRuleFiles`（及可选的 `ruleFileOrder`）。
+2. 按 `activeRuleFiles` 数组顺序读取 `~/.meddle/route-rules/<名称>.txt`。启用文件的相对顺序与 Tab 栏（`ruleFileOrder`）中启用文件的相对顺序保持一致。
 3. 合并规则并按顺序匹配。
 4. 如果目录为空，首次启动会创建一个默认规则文件并将其设为启用状态。
 5. 规则文件修改后会自动重新加载。

package/README.md

@@ -36,6 +36,8 @@ irm https://raw.githubusercontent.com/JonathanLee-LX/meddle/main/scripts/install
 
 二进制产物随 [GitHub Release](https://github.com/JonathanLee-LX/meddle/releases) 发布，也可手动下载。安装目录默认 `~/.local/bin`（已有 `~/.meddle/bin` 旧安装时原地升级），可通过 `MEDDLE_BIN_DIR` 环境变量自定义。`meddle update` 始终更新到当前运行二进制所在目录。
 
+**私有仓库：** `meddle update`（含 `meddle update --beta`）/ 安装脚本下载 Release 资产时会读取 `GH_TOKEN`（优先）或 `GITHUB_TOKEN`（`repo` 或 fine-grained `contents:read`）。私有仓安装后升级也需要设置 token；未设置时会表现为 404（checksum sidecar missing）。也可手动：`gh release download -R JonathanLee-LX/meddle -p 'meddle-*'`。
+
 ### 命令
 
 ```bash
@@ -179,6 +181,22 @@ meddle --remote --no-intercept-https
 
 所有 `mock_rule_*`、`route_rule_*`、`route_preview` 工具均支持可选 `session` 参数，指定后可操作对应 session 的规则，不传则操作默认 session。
 
+**路由规则写入**（`route_rule_add` / `route_rule_update` / `route_rule_delete`）只改包含该 pattern 的那一行，规则文件里的注释、空行、`//` 禁用规则和其他规则（连同排除项）都按原样保留：
+
+- **不传 `exclusions`**：保留该规则原有的排除规则（`route_rule_add` 覆盖已有规则时也一样；新规则则没有排除规则）。
+- **传 `exclusions: []`**：清空该规则的排除规则。
+- 传非空数组：用它替换原有的排除规则。
+- 如果一行写了多个 pattern，修改或删除其中一个时，若剩下的 pattern 以 `//` 或 `#` 开头（拆开后会被当成注释），写入会被拒绝并提示「该行剩余的 pattern 以 // 或 # 开头，拆开后会被当成注释，请用文本编辑器手动修改」，规则文件不变。
+- 新增规则的 pattern 不能以 `#` 或 `//` 开头（例如 `#foo.com`、`//foo.com`），否则写进文件后会被当成注释或禁用行。写入会被拒绝并提示「规则不能以 // 或 # 开头，否则会被当成禁用行或注释。要写注释或禁用规则，请用文本编辑器。」，规则文件不变。
+- CLI：`meddle route update <file> <pattern> --exclusions=` 清空该规则的排除项（该行不再有 `!path`，其余行逐字节不变）。`--exclusions=/a,/b` 替换。pattern 里写 `!path`（如 `"api.example.com !/health"`）同样是替换。两者都不写则保留原有排除项。单独的 `--exclusions`（没有 `=`）、空的 `!`、未知参数，或 `!path` 与 `--exclusions` 同时出现，都会非 0 退出且不改文件。`#` 只有出现在一行开头（前导空白之后）才是整行注释；行尾的 `#` 不是注释。
+
+**只读规则集**（[详细说明](./docs/RULESET_READONLY.md)）：规则集（规则文件）可以在 Meddle Web 界面中加只读锁，防止 Agent 误改。
+
+- `route_rule_list` 的结果带 `readonly: true|false`。
+- 锁住后 `route_rule_add` / `route_rule_update` / `route_rule_delete` / `route_rule_active_set`（会改变锁住规则集的启用状态时）全部被拒绝，规则文件不变，工具返回 `isError: true` 与 `{"error":{"code":"RULESET_READONLY","message":"该规则集已设为只读，只能在 Meddle 界面中解锁","ruleFile":"…"}}`。CLI 同样拒绝，退出码为 `3`。
+- **CLI 和 MCP 都没有加锁 / 解锁的命令或工具**，只能由人在 Meddle 界面中操作。界面使用页面令牌 + 同源校验；这只是防误改，不是安全隔离（可被 `curl` 取页面令牌并伪造 `Origin` 绕过，有 shell 的 Agent 也能直接改磁盘文件）。
+- 锁住的规则集不能重命名，需先在 Meddle 界面中解锁再改名；在 Meddle 之外直接改文件名视为新规则集（可读写），旧锁记录自动清除。
+
 ### 多 Session 隔离（预览功能）
 
 多 Session 允许同时运行多个独立的 `meddle` 代理进程，每个进程拥有独立的配置目录（MEDDLE_HOME）、端口、路由规则和 Mock 规则，适用于多个 Agent 或项目需要隔离代理环境的场景。

package/bin/commands/mock/add.js

@@ -3,32 +3,49 @@
  */
 
 const output = require('../../lib/output')
-const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiPost } = require('../../lib/api-client')
 const { addMockRule } = require('../../lib/file-access')
+const { withProxyOrFile, failCommand } = require('../../lib/proxy-or-file')
 
 // Parse arguments
 const args = process.argv.slice(3)
 const jsonFlag = args.includes('--json')
 output.setJsonMode(jsonFlag)
 
+function parseCorsFlag(options) {
+  if (!options.cors) return
+  const corsHeaders = {
+    'Access-Control-Allow-Origin': '{origin}',
+    'Access-Control-Allow-Credentials': 'true',
+    'Access-Control-Allow-Methods': '*',
+    'Access-Control-Allow-Headers': '*',
+  }
+  options.headers = { ...corsHeaders, ...(options.headers || {}) }
+  delete options.cors
+}
+
 function parseArgs(args) {
   const options = {}
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--name') options.name = args[++i]
     else if (args[i] === '--pattern') options.urlPattern = args[++i]
+    else if (args[i] === '--query') options.query = args[++i]
     else if (args[i] === '--method') options.method = args[++i]
     else if (args[i] === '--status') options.statusCode = parseInt(args[++i], 10)
     else if (args[i] === '--body') options.body = args[++i]
     else if (args[i] === '--delay') options.delay = parseInt(args[++i], 10)
+    else if (args[i] === '--cors') options.cors = true
     else if (args[i] === '--headers') {
+      const raw = args[++i]
       try {
-        options.headers = JSON.parse(args[++i])
+        options.headers = JSON.parse(raw)
       } catch (_) {
-        options.headers = {}
+        output.error('Invalid --headers JSON: ' + raw)
+        process.exit(1)
       }
     }
   }
+  parseCorsFlag(options)
   return options
 }
 
@@ -49,6 +66,7 @@ async function run() {
   const rule = {
     name: options.name,
     urlPattern: options.urlPattern,
+    query: options.query || '',
     method: options.method || '*',
     statusCode: options.statusCode || 200,
     delay: options.delay || 0,
@@ -58,35 +76,33 @@ async function run() {
     enabled: true
   }
 
-  const running = await isProxyRunning()
+  const { value: result, fileOnly } = await withProxyOrFile({
+    api: async () => {
+      const created = await apiPost('/api/mocks', rule)
+      return created.rule || created
+    },
+    file: () => addMockRule(rule),
+  })
 
-  let result
-  if (running) {
-    try {
-      result = await apiPost('/api/mocks', rule)
-      result = result.rule || result
-    } catch (e) {
-      // Fallback to file mode
-      result = addMockRule(rule)
-    }
-  } else {
-    result = addMockRule(rule)
-  }
+  if (fileOnly) output.warnFileOnlyMode()
 
   if (jsonFlag) {
-    output.jsonRaw(result)
+    output.jsonRaw(fileOnly
+      ? { ...result, fileOnly: true, warning: output.FILE_ONLY_WARNING }
+      : result)
     return
   }
 
   output.header('Mock Rule Added')
   output.success(`#${result.id}: ${result.name}`)
   output.kv('Pattern', result.urlPattern)
+  if (result.query) output.kv('Query', result.query)
   output.kv('Method', result.method)
   output.kv('Status', result.statusCode)
   output.kv('Delay', `${result.delay}ms`)
+  if (result.headers && Object.keys(result.headers).length > 0) {
+    output.kv('Headers', JSON.stringify(result.headers))
+  }
 }
 
-run().catch(e => {
-  output.error(e.message)
-  process.exit(1)
-})
+run().catch((e) => failCommand(e))

package/bin/commands/mock/delete.js

@@ -3,9 +3,9 @@
  */
 
 const output = require('../../lib/output')
-const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiDelete } = require('../../lib/api-client')
 const { deleteMockRule } = require('../../lib/file-access')
+const { withProxyOrFile, failCommand } = require('../../lib/proxy-or-file')
 
 // Parse arguments (skip 'mock' and 'delete' from argv)
 const args = process.argv.slice(4)
@@ -22,29 +22,24 @@ async function run() {
     process.exit(1)
   }
 
-  const running = await isProxyRunning()
-
-  if (running) {
-    try {
+  const { fileOnly } = await withProxyOrFile({
+    api: async () => {
       await apiDelete(`/api/mocks/${id}`)
-    } catch (e) {
-      // Fallback to file mode
+      return true
+    },
+    file: () => {
       const deleted = deleteMockRule(id)
-      if (!deleted) {
-        output.error(`Mock rule not found: id=${id}`)
-        process.exit(1)
-      }
-    }
-  } else {
-    const deleted = deleteMockRule(id)
-    if (!deleted) {
-      output.error(`Mock rule not found: id=${id}`)
-      process.exit(1)
-    }
-  }
+      if (!deleted) throw new Error(`Mock rule not found: id=${id}`)
+      return true
+    },
+  })
+
+  if (fileOnly) output.warnFileOnlyMode()
 
   if (jsonFlag) {
-    output.jsonRaw({ success: true, id })
+    output.jsonRaw(fileOnly
+      ? { success: true, id, fileOnly: true, warning: output.FILE_ONLY_WARNING }
+      : { success: true, id })
     return
   }
 
@@ -52,7 +47,4 @@ async function run() {
   output.success(`id=${id}`)
 }
 
-run().catch(e => {
-  output.error(e.message)
-  process.exit(1)
-})
+run().catch((e) => failCommand(e))

package/bin/commands/mock/index.js

@@ -32,19 +32,23 @@ Mock Commands:
   meddle mock enable <id>             Enable a mock rule
   meddle mock disable <id>            Disable a mock rule
 
-Add Options:
+Add / Update Options:
   --name <n>       Rule name
-  --pattern <p>    URL pattern (regex or string)
+  --pattern <p>    URL pattern (regex or string; may include query)
+  --query <q>      Query match (exact key=value params, e.g. window_key=A; not prefix)
   --method <m>     HTTP method (GET, POST, *, default: *)
   --status <s>     Response status code (default: 200)
   --body <b>       Response body content
   --delay <d>      Response delay in ms (default: 0)
+  --headers <json> Response headers JSON (values may use {origin})
+  --cors           Shortcut: credentials-friendly CORS headers with {origin}
 
 Examples:
   meddle mock list
   meddle mock add --name "API Mock" --pattern "example.com/api" --status 200
-  meddle mock update 1 --status 404
+  meddle mock add --name "Policy A" --pattern "/ops/.*/policy" --query "window_key=A" --body '{"key":"A"}' --cors
+  meddle mock update 1 --status 404 --headers '{"X-Debug":"1"}'
   meddle mock delete 1
 `)
     process.exit(1)
-}
+}

package/bin/commands/mock/list.js

@@ -3,30 +3,49 @@
  */
 
 const output = require('../../lib/output')
-const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiGet } = require('../../lib/api-client')
 const { loadMockRules } = require('../../lib/file-access')
+const { withProxyOrFile, failCommand } = require('../../lib/proxy-or-file')
 
 // Check for --json flag
 const args = process.argv.slice(3)
 const jsonFlag = args.includes('--json')
 output.setJsonMode(jsonFlag)
 
-async function run() {
-  const running = await isProxyRunning()
-
-  let rules = []
-
-  if (running) {
-    try {
-      rules = await apiGet('/api/mocks')
-    } catch (e) {
-      // Fallback to file mode
-      rules = loadMockRules()
+function listFromFile() {
+  try {
+    return loadMockRules()
+  } catch (err) {
+    if (err && err.code === 'MOCKS_FILE_INVALID' && err.listMessage) {
+      const listed = new Error(err.listMessage)
+      listed.rawStderr = true
+      throw listed
     }
-  } else {
-    rules = loadMockRules()
+    throw err
   }
+}
+
+async function run() {
+  const { value: rules } = await withProxyOrFile({
+    api: async () => {
+      const listed = await apiGet('/api/mocks')
+      // GET /api/mocks stays a bare array and is [] when the file failed to
+      // parse. The status endpoint is the signal that the file is corrupt.
+      let fileStatus = null
+      try {
+        fileStatus = await apiGet('/api/mocks-file')
+      } catch (err) {
+        if (!err || !Number.isInteger(err.status)) throw err
+      }
+      if (fileStatus && fileStatus.valid === false) {
+        const err = new Error(fileStatus.error || 'Mock 文件格式错误')
+        err.rawStderr = true
+        throw err
+      }
+      return listed
+    },
+    file: listFromFile,
+  })
 
   if (jsonFlag) {
     output.jsonRaw(rules)
@@ -48,6 +67,7 @@ async function run() {
     output.section('Active Rules')
     active.forEach(rule => {
       output.success(`#${rule.id}: ${rule.name} (${rule.urlPattern})`)
+      if (rule.query) output.kv('Query', rule.query, 4)
       output.kv('Status', rule.statusCode, 4)
       output.kv('Method', rule.method || '*', 4)
       output.kv('Delay', `${rule.delay || 0}ms`, 4)
@@ -62,7 +82,4 @@ async function run() {
   }
 }
 
-run().catch(e => {
-  output.error(e.message)
-  process.exit(1)
-})
+run().catch((e) => failCommand(e))

package/bin/commands/mock/toggle.js

@@ -3,9 +3,9 @@
  */
 
 const output = require('../../lib/output')
-const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiPut } = require('../../lib/api-client')
 const { updateMockRule } = require('../../lib/file-access')
+const { withProxyOrFile, failCommand } = require('../../lib/proxy-or-file')
 
 // Parse arguments
 const args = process.argv.slice(2) // Full args: ['mock', 'enable'/'disable', '<id>']
@@ -25,31 +25,24 @@ async function run() {
 
   const enabled = subcommand === 'enable'
 
-  const running = await isProxyRunning()
+  const { value: result, fileOnly } = await withProxyOrFile({
+    api: async () => {
+      const updated = await apiPut(`/api/mocks/${id}`, { enabled })
+      return updated.rule || updated
+    },
+    file: () => {
+      const updated = updateMockRule(id, { enabled })
+      if (!updated) throw new Error(`Mock rule not found: id=${id}`)
+      return updated
+    },
+  })
 
-  let result
-  if (running) {
-    try {
-      result = await apiPut(`/api/mocks/${id}`, { enabled })
-      result = result.rule || result
-    } catch (e) {
-      // Fallback to file mode
-      result = updateMockRule(id, { enabled })
-      if (!result) {
-        output.error(`Mock rule not found: id=${id}`)
-        process.exit(1)
-      }
-    }
-  } else {
-    result = updateMockRule(id, { enabled })
-    if (!result) {
-      output.error(`Mock rule not found: id=${id}`)
-      process.exit(1)
-    }
-  }
+  if (fileOnly) output.warnFileOnlyMode()
 
   if (jsonFlag) {
-    output.jsonRaw(result)
+    output.jsonRaw(fileOnly
+      ? { ...result, fileOnly: true, warning: output.FILE_ONLY_WARNING }
+      : result)
     return
   }
 
@@ -58,7 +51,4 @@ async function run() {
   output.kv('Enabled', enabled ? 'Yes' : 'No')
 }
 
-run().catch(e => {
-  output.error(e.message)
-  process.exit(1)
-})
+run().catch((e) => failCommand(e))

package/bin/commands/mock/update.js

@@ -3,15 +3,27 @@
  */
 
 const output = require('../../lib/output')
-const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiPut } = require('../../lib/api-client')
-const { updateMockRule, loadMockRules, saveMockRules } = require('../../lib/file-access')
+const { updateMockRule } = require('../../lib/file-access')
+const { withProxyOrFile, failCommand } = require('../../lib/proxy-or-file')
 
 // Parse arguments (skip 'mock' and 'update' from argv)
 const args = process.argv.slice(4)
 const jsonFlag = args.includes('--json')
 output.setJsonMode(jsonFlag)
 
+function parseCorsFlag(options) {
+  if (!options.cors) return
+  const corsHeaders = {
+    'Access-Control-Allow-Origin': '{origin}',
+    'Access-Control-Allow-Credentials': 'true',
+    'Access-Control-Allow-Methods': '*',
+    'Access-Control-Allow-Headers': '*',
+  }
+  options.headers = { ...corsHeaders, ...(options.headers || {}) }
+  delete options.cors
+}
+
 function parseArgs(args) {
   // First positional arg is id
   let id = null
@@ -20,15 +32,19 @@ function parseArgs(args) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--name') options.name = args[++i]
     else if (args[i] === '--pattern') options.urlPattern = args[++i]
+    else if (args[i] === '--query') options.query = args[++i]
     else if (args[i] === '--method') options.method = args[++i]
     else if (args[i] === '--status') options.statusCode = parseInt(args[++i], 10)
     else if (args[i] === '--body') options.body = args[++i]
     else if (args[i] === '--delay') options.delay = parseInt(args[++i], 10)
+    else if (args[i] === '--cors') options.cors = true
     else if (args[i] === '--headers') {
+      const raw = args[++i]
       try {
-        options.headers = JSON.parse(args[++i])
+        options.headers = JSON.parse(raw)
       } catch (_) {
-        options.headers = {}
+        output.error('Invalid --headers JSON: ' + raw)
+        process.exit(1)
       }
     }
     else if (!args[i].startsWith('--') && id === null) {
@@ -36,6 +52,7 @@ function parseArgs(args) {
     }
   }
 
+  parseCorsFlag(options)
   return { id, options }
 }
 
@@ -52,43 +69,35 @@ async function run() {
     process.exit(1)
   }
 
-  const running = await isProxyRunning()
+  const { value: result, fileOnly } = await withProxyOrFile({
+    api: async () => {
+      const updated = await apiPut(`/api/mocks/${id}`, options)
+      return updated.rule || updated
+    },
+    file: () => {
+      const updated = updateMockRule(id, options)
+      if (!updated) throw new Error(`Mock rule not found: id=${id}`)
+      return updated
+    },
+  })
 
-  let result
-  if (running) {
-    try {
-      result = await apiPut(`/api/mocks/${id}`, options)
-      result = result.rule || result
-    } catch (e) {
-      // Fallback to file mode
-      result = updateMockRule(id, options)
-      if (!result) {
-        output.error(`Mock rule not found: id=${id}`)
-        process.exit(1)
-      }
-    }
-  } else {
-    result = updateMockRule(id, options)
-    if (!result) {
-      output.error(`Mock rule not found: id=${id}`)
-      process.exit(1)
-    }
-  }
+  if (fileOnly) output.warnFileOnlyMode()
 
   if (jsonFlag) {
-    output.jsonRaw(result)
+    output.jsonRaw(fileOnly
+      ? { ...result, fileOnly: true, warning: output.FILE_ONLY_WARNING }
+      : result)
     return
   }
 
   output.header('Mock Rule Updated')
   output.success(`#${result.id}: ${result.name}`)
   if (options.urlPattern) output.kv('Pattern', result.urlPattern)
+  if (options.query !== undefined) output.kv('Query', result.query || '(none)')
   if (options.method) output.kv('Method', result.method)
   if (options.statusCode) output.kv('Status', result.statusCode)
   if (options.delay) output.kv('Delay', `${result.delay}ms`)
+  if (options.headers) output.kv('Headers', JSON.stringify(result.headers || {}))
 }
 
-run().catch(e => {
-  output.error(e.message)
-  process.exit(1)
-})
+run().catch((e) => failCommand(e))

package/bin/commands/route/active.js

@@ -5,7 +5,13 @@
 const output = require('../../lib/output')
 const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiGet, apiPut } = require('../../lib/api-client')
-const { listRuleFiles, getActiveRuleFileNames, setActiveRuleFileNames, setRuleFileEnabled } = require('../../lib/file-access')
+const { listRuleFiles, getActiveRuleFileNames, setRuleFileEnabled } = require('../../lib/file-access')
+const { isRulesetReadonlyError, exitRulesetReadonly, assertListedFilesWritable } = require('../../lib/ruleset-readonly')
+
+/** Names whose enabled state `active set <file>` would change. */
+function pendingToggles(files, target) {
+  return files.filter((f) => !!f.enabled !== (f.name === target)).map((f) => f.name)
+}
 
 // Parse arguments (skip 'route' and 'active' from argv)
 const args = process.argv.slice(4)
@@ -39,6 +45,9 @@ async function run() {
           process.exit(1)
         }
 
+        // Issue #137: refuse up front so a locked ruleset never leaves a half-applied switch.
+        assertListedFilesWritable(files, pendingToggles(files, targetFile))
+
         for (const f of files) {
           const nextEnabled = f.name === targetFile
           if (!!f.enabled === nextEnabled) continue
@@ -53,6 +62,7 @@ async function run() {
         output.header('Active Route File Set')
         output.success(targetFile)
       } catch (e) {
+        if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: targetFile })
         // Fallback to file mode
         const files = listRuleFiles()
         const target = files.find(f => f.name === targetFile)
@@ -61,11 +71,14 @@ async function run() {
           process.exit(1)
         }
 
+        assertListedFilesWritable(files, pendingToggles(files, targetFile))
         // Disable all, then enable target
         files.forEach(f => setRuleFileEnabled(f.name, f.name === targetFile))
 
+        output.warnFileOnlyMode()
+
         if (jsonFlag) {
-          output.jsonRaw({ success: true, activeFile: targetFile })
+          output.jsonRaw({ success: true, activeFile: targetFile, fileOnly: true, warning: output.FILE_ONLY_WARNING })
           return
         }
 
@@ -81,10 +94,13 @@ async function run() {
         process.exit(1)
       }
 
+      assertListedFilesWritable(files, pendingToggles(files, targetFile))
       files.forEach(f => setRuleFileEnabled(f.name, f.name === targetFile))
 
+      output.warnFileOnlyMode()
+
       if (jsonFlag) {
-        output.jsonRaw({ success: true, activeFile: targetFile })
+        output.jsonRaw({ success: true, activeFile: targetFile, fileOnly: true, warning: output.FILE_ONLY_WARNING })
         return
       }
 
@@ -136,6 +152,7 @@ async function run() {
 }
 
 run().catch(e => {
+  if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: targetFile })
   output.error(e.message)
   process.exit(1)
 })