@jonathanleelx/meddle 0.0.1

package/bin/commands/route/update.js

@@ -0,0 +1,126 @@
+/**
+ * meddle route update - Update a rule in a route file
+ */
+
+const output = require('../../lib/output')
+const { isProxyRunning } = require('../../lib/proxy-detect')
+const { apiGet, apiPut } = require('../../lib/api-client')
+const { getRuleFileContent, saveRuleFileContent, parseEprc, ruleMapToEprcText } = require('../../lib/file-access')
+
+// Parse arguments (skip 'route' and 'update' from argv)
+const args = process.argv.slice(4)
+const jsonFlag = args.includes('--json')
+output.setJsonMode(jsonFlag)
+
+// Get positional arguments: file, pattern, newTarget
+const positionalArgs = args.filter(a => !a.startsWith('--'))
+const fileName = positionalArgs[0]
+const pattern = positionalArgs[1]
+const newTarget = positionalArgs[2]
+
+async function run() {
+  if (!fileName) {
+    output.error('Missing required argument: <file>')
+    process.exit(1)
+  }
+  if (!pattern) {
+    output.error('Missing required argument: <pattern>')
+    process.exit(1)
+  }
+  if (!newTarget) {
+    output.error('Missing required argument: <target>')
+    process.exit(1)
+  }
+
+  const running = await isProxyRunning()
+
+  const pat = pattern.trim()
+  const tgt = newTarget.trim()
+
+  // Handle [marker] syntax for lookup
+  const bm = pat.match(/\[([^\]]+)\]/)
+  const internalKey = bm ? pat.replace(bm[0], bm[1]) : pat
+
+  if (running) {
+    try {
+      let content = await apiGet(`/api/rule-files/${encodeURIComponent(fileName)}/content`)
+      const text = typeof content === 'string' ? content : String(content)
+      const ruleMap = parseEprc(text)
+
+      if (!Object.prototype.hasOwnProperty.call(ruleMap, internalKey)) {
+        output.error(`Pattern not found: ${pat}`)
+        process.exit(1)
+      }
+
+      ruleMap[internalKey] = bm ? tgt + bm[0] : tgt
+      const newContent = ruleMapToEprcText(ruleMap)
+      await apiPut(`/api/rule-files/${encodeURIComponent(fileName)}/content`, { content: newContent })
+
+      if (jsonFlag) {
+        output.jsonRaw({ success: true, file: fileName, pattern: pat, newTarget: tgt })
+        return
+      }
+
+      output.header('Route Rule Updated')
+      output.success(`${pat} -> ${tgt}`)
+      output.kv('File', fileName)
+    } catch (e) {
+      // Fallback to file mode
+      const content = getRuleFileContent(fileName)
+      if (!content) {
+        output.error(`Route file not found: ${fileName}`)
+        process.exit(1)
+      }
+
+      const ruleMap = parseEprc(content)
+      if (!Object.prototype.hasOwnProperty.call(ruleMap, internalKey)) {
+        output.error(`Pattern not found: ${pat}`)
+        process.exit(1)
+      }
+
+      ruleMap[internalKey] = bm ? tgt + bm[0] : tgt
+      const newContent = ruleMapToEprcText(ruleMap)
+      saveRuleFileContent(fileName, newContent)
+
+      if (jsonFlag) {
+        output.jsonRaw({ success: true, file: fileName, pattern: pat, newTarget: tgt })
+        return
+      }
+
+      output.header('Route Rule Updated')
+      output.success(`${pat} -> ${tgt}`)
+      output.kv('File', fileName)
+    }
+  } else {
+    // File mode
+    const content = getRuleFileContent(fileName)
+    if (!content) {
+      output.error(`Route file not found: ${fileName}`)
+      process.exit(1)
+    }
+
+    const ruleMap = parseEprc(content)
+    if (!Object.prototype.hasOwnProperty.call(ruleMap, internalKey)) {
+      output.error(`Pattern not found: ${pat}`)
+      process.exit(1)
+    }
+
+    ruleMap[internalKey] = bm ? tgt + bm[0] : tgt
+    const newContent = ruleMapToEprcText(ruleMap)
+    saveRuleFileContent(fileName, newContent)
+
+    if (jsonFlag) {
+      output.jsonRaw({ success: true, file: fileName, pattern: pat, newTarget: tgt })
+      return
+    }
+
+    output.header('Route Rule Updated')
+    output.success(`${pat} -> ${tgt}`)
+    output.kv('File', fileName)
+  }
+}
+
+run().catch(e => {
+  output.error(e.message)
+  process.exit(1)
+})

package/bin/commands/session/create.js

@@ -0,0 +1,166 @@
+/**
+ * meddle session create - Spawn a new isolated proxy session.
+ *
+ * Flow:
+ *   1. Generate session id (label-timestamp) and allocate a free port
+ *   2. Ensure the session's MEDDLE_HOME directory exists
+ *   3. Spawn `node index.js` with MEDDLE_HOME + PORT env
+ *   4. Wait for the child's HTTP API to become reachable
+ *   5. Register in sessions.json (pid, port, meddleHome)
+ *   6. Print session id + proxy URL
+ *
+ * The child is spawned detached with stdio inherited so the user sees
+ * proxy logs. The child listens for parent disconnect and self-terminates
+ * to avoid orphan processes.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { spawn } = require('child_process')
+const chalk = require('chalk')
+
+const {
+    sessionsDir,
+    sessionDir,
+    allocatePort,
+    generateId,
+    createSession,
+    readRegistry,
+    writeRegistry,
+} = require('../../lib/sessions')
+const { resolveMeddleHome } = require('../../lib/meddle-home')
+const { GLOBAL_DEFAULT_PORT } = require('../../lib/session-args')
+
+function parseArgs(argv) {
+    const args = argv.slice(4) // after 'meddle' 'session' 'create'
+    const out = { name: null, port: null, json: false }
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i]
+        if (a === '--name' && args[i + 1]) { out.name = args[i + 1]; i++; continue }
+        if (a.startsWith('--name=')) { out.name = a.slice('--name='.length); continue }
+        if (a === '--port' && args[i + 1]) { out.port = Number(args[i + 1]); i++; continue }
+        if (a.startsWith('--port=')) { out.port = Number(a.slice('--port='.length)); continue }
+        if (a === '--json') { out.json = true; continue }
+    }
+    return out
+}
+
+function waitForProxyReady(port, timeoutMs = 8000) {
+    const start = Date.now()
+    const interval = 100
+    return new Promise((resolve, reject) => {
+        const check = () => {
+            fetch(`http://127.0.0.1:${port}/api/mocks`, { method: 'GET', signal: AbortSignal.timeout(500) })
+                .then((r) => { if (r.ok) resolve(); else retry() })
+                .catch(() => retry())
+        }
+        function retry() {
+            if (Date.now() - start > timeoutMs) {
+                return reject(new Error(`proxy did not become ready on port ${port} within ${timeoutMs}ms`))
+            }
+            setTimeout(check, interval)
+        }
+        check()
+    })
+}
+
+async function main() {
+    const opts = parseArgs(process.argv)
+
+    // 1. id + port
+    const id = generateId(opts.name)
+    let port = opts.port
+    if (port) {
+        // user-specified port: validate range and freeness
+        if (port < 9000 || port > 9999) {
+            throw new Error(`--port must be in [9000, 9999] (got ${port}); default session uses ${GLOBAL_DEFAULT_PORT}`)
+        }
+    } else {
+        const registry = readRegistry()
+        port = allocatePort(registry)
+        if (!port) throw new Error('no free port in [9000, 9999]; run `meddle session prune` to clean orphaned records')
+    }
+
+    // 2. MEDDLE_HOME dir
+    const meddleHome = sessionDir(id)
+    fs.mkdirSync(meddleHome, { recursive: true })
+    // subdirs that proxy expects to exist or create — let the child create them
+    // via its existing startup logic. We only ensure the root exists.
+
+    // 3. spawn child
+    const indexPath = path.join(__dirname, '..', '..', '..', 'index.js')
+    const childEnv = {
+        ...process.env,
+        MEDDLE_HOME: meddleHome,
+        PORT: String(port),
+        MEDDLE_SESSION_ID: id,
+        // Suppress the CA trust prompt — sessions reuse the shared CA
+        // from ~/.meddle/ca which the user already trusted when setting up
+        // the default session. Also avoid interactive prompts blocking
+        // a non-interactive agent spawn.
+        MEDDLE_HEADLESS: '1',
+        // Disable MCP file discovery for non-default sessions; the MCP
+        // proxy-url file is only meaningful for the default session.
+        MEDDLE_MCP: '',
+    }
+    const child = spawn(process.execPath, [indexPath], {
+        cwd: process.cwd(),
+        env: childEnv,
+        stdio: 'inherit',
+        detached: false,
+    })
+
+    if (!child.pid) {
+        throw new Error('failed to spawn proxy process')
+    }
+
+    // Kill child if parent exits unexpectedly (orphan prevention).
+    child.on('exit', (code, signal) => {
+        if (code !== 0 && code !== null) {
+            console.error(chalk.yellow(`session ${id} exited early (code=${code} signal=${signal || ''})`))
+        }
+    })
+    process.on('exit', () => {
+        try { if (child.exitCode === null) child.kill('SIGTERM') } catch (_) {}
+    })
+
+    // 4. wait for HTTP ready
+    try {
+        await waitForProxyReady(port)
+    } catch (err) {
+        try { child.kill('SIGTERM') } catch (_) {}
+        throw err
+    }
+
+    // 5. register (optimistic: re-read, verify port not taken, write)
+    const freshRegistry = readRegistry()
+    const portConflict = Object.keys(freshRegistry).some((k) => freshRegistry[k].port === port)
+    if (portConflict && !opts.port) {
+        try { child.kill('SIGTERM') } catch (_) {}
+        throw new Error(`port ${port} was claimed by another session during startup; please retry`)
+    }
+    createSession({ id, label: opts.name || '', port, pid: child.pid, meddleHome })
+
+    // 6. report
+    if (opts.json) {
+        console.log(JSON.stringify({
+            id,
+            port,
+            pid: child.pid,
+            meddleHome,
+            proxyUrl: `http://127.0.0.1:${port}`,
+        }))
+    } else {
+        console.log(chalk.green('Created session:'), chalk.cyan(id))
+        console.log(`  ${chalk.gray('Proxy URL:')} http://127.0.0.1:${port}`)
+        console.log(`  ${chalk.gray('PID:')}       ${child.pid}`)
+        console.log(`  ${chalk.gray('MEDDLE_HOME:')}   ${meddleHome}`)
+        console.log(chalk.gray('\nUse this session with:'))
+        console.log(`  meddle --session ${id} route list`)
+    }
+}
+
+main().catch((err) => {
+    console.error(chalk.red('error:'), err.message)
+    process.exit(1)
+})

package/bin/commands/session/delete.js

@@ -0,0 +1,69 @@
+/**
+ * meddle session delete <id> - Stop a session and remove from registry.
+ *
+ * --clean also deletes the session's MEDDLE_HOME data directory.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const chalk = require('chalk')
+const { getSession, deleteSession, isPidAlive } = require('../../lib/sessions')
+
+const args = process.argv.slice(4)
+const id = args.find((a) => !a.startsWith('--'))
+const cleanFlag = args.includes('--clean')
+const jsonFlag = args.includes('--json')
+
+if (!id) {
+    console.error(chalk.red('error:'), 'session id required')
+    console.error(chalk.gray('usage: meddle session delete <id> [--clean]'))
+    process.exit(1)
+}
+
+const record = getSession(id)
+if (!record) {
+    console.error(chalk.red('error:'), `session not found: ${id}`)
+    process.exit(1)
+}
+
+// 1. kill process if alive
+let killed = false
+if (isPidAlive(record.pid)) {
+    try {
+        process.kill(record.pid, 'SIGTERM')
+        killed = true
+    } catch (err) {
+        console.error(chalk.yellow('warning:'), `could not kill pid ${record.pid}: ${err.message}`)
+    }
+}
+
+// 2. remove from registry
+deleteSession(id)
+
+// 3. optionally clean data dir
+let cleaned = false
+if (cleanFlag) {
+    try {
+        if (fs.existsSync(record.meddleHome)) {
+            // only delete if inside ~/.meddle/sessions/ — safety guard
+            const sessionsRoot = path.dirname(record.meddleHome)
+            const expectedRoot = path.join(require('../../lib/meddle-home').resolveMeddleHome(), 'sessions')
+            if (path.resolve(sessionsRoot) === path.resolve(expectedRoot)) {
+                fs.rmSync(record.meddleHome, { recursive: true, force: true })
+                cleaned = true
+            } else {
+                console.error(chalk.yellow('warning:'), `refusing to delete ${record.meddleHome} (outside sessions dir)`)
+            }
+        }
+    } catch (err) {
+        console.error(chalk.yellow('warning:'), `could not clean data dir: ${err.message}`)
+    }
+}
+
+if (jsonFlag) {
+    console.log(JSON.stringify({ id, killed, cleaned, meddleHome: record.meddleHome }))
+} else {
+    console.log(chalk.green('Deleted session:'), chalk.cyan(id))
+    if (killed) console.log(chalk.gray(`  stopped pid ${record.pid}`))
+    if (cleaned) console.log(chalk.gray(`  removed ${record.meddleHome}`))
+}

package/bin/commands/session/index.js

@@ -0,0 +1,61 @@
+/**
+ * meddle session - Multi-instance session management (preview)
+ *
+ * Each session is an independent `meddle` process with its own MEDDLE_HOME
+ * (route-rules, mocks, plugins, settings) and port. The CA store
+ * (~/.meddle/ca) is shared across all sessions so HTTPS interception
+ * works without re-installing certificates per session.
+ *
+ * See docs/proposals/multi-session-isolation.md for the full design.
+ */
+
+const args = process.argv.slice(3)
+const subcommand = args[0]
+
+switch (subcommand) {
+  case 'create':
+    require('./create.js')
+    break
+  case 'list':
+  case 'ls':
+    require('./list.js')
+    break
+  case 'delete':
+  case 'rm':
+    require('./delete.js')
+    break
+  case 'prune':
+    require('./prune.js')
+    break
+  default:
+    console.log(`
+Session Commands (multi-instance isolation, preview):
+
+  meddle session create [--name <label>] [--port <port>]
+                              Create a new proxy session with its own
+                              MEDDLE_HOME and port. Returns the session id.
+  meddle session list             List all sessions with liveness check.
+  meddle session delete <id> [--clean]
+                              Stop the session, remove from registry.
+                              --clean also deletes its data directory.
+  meddle session prune            Remove registry entries whose process is
+                              no longer alive (keeps data directories).
+
+Operating on a specific session:
+  meddle --session <id> route list
+  meddle --session <id> mock add --name "API" --pattern "api.test.com"
+  meddle --session <id> status
+
+Notes:
+  - The default session (no --session) uses ~/.meddle and is fully backward
+    compatible. Existing commands and tests are unaffected.
+  - --session and the MEDDLE_HOME environment variable are mutually exclusive.
+  - All sessions share the same CA (~/.meddle/ca); only config is isolated.
+
+Examples:
+  meddle session create --name my-debug
+  meddle --session my-debug-1718283600 route list
+  meddle session delete my-debug-1718283600 --clean
+`)
+    process.exit(subcommand ? 1 : 0)
+}

package/bin/commands/session/list.js

@@ -0,0 +1,42 @@
+/**
+ * meddle session list - List all sessions with liveness check.
+ */
+
+const chalk = require('chalk')
+const { listSessions } = require('../../lib/sessions')
+
+const args = process.argv.slice(4)
+const jsonFlag = args.includes('--json')
+
+const sessions = listSessions()
+
+if (jsonFlag) {
+    console.log(JSON.stringify(sessions, null, 2))
+    process.exit(0)
+}
+
+if (sessions.length === 0) {
+    console.log(chalk.gray('No sessions registered.'))
+    console.log(chalk.gray('Create one with: meddle session create --name <label>'))
+    process.exit(0)
+}
+
+console.log(chalk.bold.cyan(`Sessions (${sessions.length})`))
+console.log(chalk.gray('─'.repeat(80)))
+for (const s of sessions) {
+    const status = s.alive ? chalk.green('● running') : chalk.red('○ orphaned')
+    const id = chalk.cyan(s.id)
+    console.log(`  ${status}  ${id}`)
+    console.log(`    ${chalk.gray('port:')}    ${s.port}`)
+    console.log(`    ${chalk.gray('pid:')}     ${s.pid}`)
+    console.log(`    ${chalk.gray('meddleHome:')}  ${s.meddleHome}`)
+    console.log(`    ${chalk.gray('created:')} ${s.createdAt}`)
+    if (s.label) console.log(`    ${chalk.gray('label:')}   ${s.label}`)
+    console.log('')
+}
+
+const orphaned = sessions.filter((s) => !s.alive)
+if (orphaned.length > 0) {
+    console.log(chalk.yellow(`${orphaned.length} orphaned session(s) detected.`))
+    console.log(chalk.gray(`Run 'meddle session prune' to clean up registry entries.`))
+}

package/bin/commands/session/prune.js

@@ -0,0 +1,31 @@
+/**
+ * meddle session prune - Remove registry entries whose process is gone.
+ *
+ * Keeps the data directories intact (use `meddle session delete <id> --clean`
+ * for full cleanup of a specific session).
+ */
+
+const chalk = require('chalk')
+const { pruneOrphaned } = require('../../lib/sessions')
+
+const args = process.argv.slice(4)
+const jsonFlag = args.includes('--json')
+
+const removed = pruneOrphaned()
+
+if (jsonFlag) {
+    console.log(JSON.stringify({ pruned: removed }))
+    process.exit(0)
+}
+
+if (removed.length === 0) {
+    console.log(chalk.gray('No orphaned sessions.'))
+    process.exit(0)
+}
+
+console.log(chalk.green(`Pruned ${removed.length} orphaned session(s):`))
+for (const s of removed) {
+    console.log(`  ${chalk.cyan(s.id)} ${chalk.gray(`(pid ${s.pid}, port ${s.port})`)}`)
+    console.log(chalk.gray(`    data dir kept: ${s.meddleHome}`))
+}
+console.log(chalk.gray('\nTo also delete data directories, run: meddle session delete <id> --clean'))

package/bin/commands/start.js

@@ -0,0 +1,43 @@
+/**
+ * meddle start - Start proxy server
+ */
+
+const { spawn } = require('child_process')
+const path = require('path')
+
+// Parse arguments
+const args = process.argv.slice(3)
+const openFlag = args.includes('--open')
+const remoteFlag = args.includes('--remote')
+const interceptHttpsFlag = args.includes('--intercept-https')
+const noInterceptHttpsFlag = args.includes('--no-intercept-https')
+
+// Start proxy
+const indexPath = path.join(__dirname, '..', 'index.js')
+const spawnEnv = { ...process.env, DEBUG: process.env.DEBUG || '' }
+if (openFlag) spawnEnv.MEDDLE_OPEN = '1'
+if (remoteFlag) spawnEnv.MEDDLE_REMOTE = '1'
+if (interceptHttpsFlag) spawnEnv.MEDDLE_INTERCEPT_HTTPS = '1'
+if (noInterceptHttpsFlag) spawnEnv.MEDDLE_INTERCEPT_HTTPS = '0'
+
+const remoteTokenIndex = args.indexOf('--remote-token')
+if (remoteTokenIndex >= 0 && args[remoteTokenIndex + 1]) {
+  spawnEnv.MEDDLE_REMOTE_TOKEN = args[remoteTokenIndex + 1]
+}
+const inlineRemoteToken = args.find(arg => arg.startsWith('--remote-token='))
+if (inlineRemoteToken) spawnEnv.MEDDLE_REMOTE_TOKEN = inlineRemoteToken.slice('--remote-token='.length)
+
+const child = spawn(process.execPath, [indexPath], {
+  env: spawnEnv,
+  stdio: 'inherit',
+  cwd: process.cwd()
+})
+
+child.on('error', (err) => {
+  console.error('启动代理失败:', err)
+  process.exit(1)
+})
+
+child.on('exit', (code) => {
+  process.exit(code || 0)
+})

package/bin/commands/status.js

@@ -0,0 +1,115 @@
+/**
+ * meddle status - Get proxy status
+ */
+
+const { getProxyUrl, isProxyRunning } = require('../lib/proxy-detect')
+const { apiGet } = require('../lib/api-client')
+const { loadMockRules, listRuleFiles, getActiveRuleFileNames } = require('../lib/file-access')
+const output = require('../lib/output')
+
+// Check for --json flag
+const args = process.argv.slice(2)
+const jsonFlag = args.includes('--json')
+output.setJsonMode(jsonFlag)
+
+async function run() {
+  const url = getProxyUrl()
+  const running = await isProxyRunning()
+
+  let mockCount = 0
+  let activeMocks = 0
+  let routeFiles = []
+  let activeRoutes = 0
+  let health = null
+
+  if (running) {
+    try {
+      // Get mock rules from API
+      const mocks = await apiGet('/api/mocks')
+      mockCount = mocks.length
+      activeMocks = mocks.filter(m => m.enabled).length
+
+      // Get route files from API
+      routeFiles = await apiGet('/api/rule-files')
+      activeRoutes = routeFiles.filter(f => f.enabled).length
+
+      health = await apiGet('/api/health')
+    } catch (_) {
+      // Fallback to file access
+      const mocks = loadMockRules()
+      mockCount = mocks.length
+      activeMocks = mocks.filter(m => m.enabled).length
+
+      routeFiles = listRuleFiles()
+      activeRoutes = routeFiles.filter(f => f.enabled).length
+    }
+  } else {
+    // File mode
+    const mocks = loadMockRules()
+    mockCount = mocks.length
+    activeMocks = mocks.filter(m => m.enabled).length
+
+    routeFiles = listRuleFiles()
+    activeRoutes = routeFiles.filter(f => f.enabled).length
+  }
+
+  const totalRouteRules = routeFiles.reduce((sum, f) => sum + f.ruleCount, 0)
+  const totalExclusions = routeFiles.reduce((sum, f) => sum + f.excludeCount, 0)
+
+  if (output.isJsonMode()) {
+    output.jsonRaw({
+      proxyUrl: url,
+      running,
+      health,
+      mocks: { total: mockCount, active: activeMocks },
+      routes: { files: routeFiles.length, activeFiles: activeRoutes, totalRules: totalRouteRules, totalExclusions }
+    })
+    return
+  }
+
+  output.header('Proxy Status')
+  output.kv('Proxy URL', url)
+  output.kv('Status', running ? 'Running' : 'Not Running')
+  if (health) {
+    output.kv('Health', health.status)
+    output.kv('PID', health.pid)
+    output.kv('CPU', `${health.cpu.percent}%`)
+    output.kv('RSS', formatBytes(health.memory.rss))
+    output.kv('Connections', health.connections.total)
+    output.kv('MITM Servers', health.mitmServers.count)
+    output.kv('Watchdog', health.watchdog.config.enabled ? `${health.watchdog.config.action}, failures=${health.watchdog.consecutiveFailures}` : 'disabled')
+  }
+
+  output.section('Mock Rules')
+  output.kv('Total', mockCount)
+  output.kv('Active', activeMocks)
+
+  output.section('Route Rules')
+  output.kv('Files', routeFiles.length)
+  output.kv('Active Files', activeRoutes)
+  output.kv('Total Rules', totalRouteRules)
+  if (totalExclusions > 0) {
+    output.kv('Total Exclusions', totalExclusions)
+  }
+
+  if (routeFiles.length > 0) {
+    output.plain('')
+    routeFiles.forEach(f => {
+      const excludeInfo = f.excludeCount > 0 ? `, ${f.excludeCount} exclusions` : ''
+      output.bullet(`${f.name} (${f.ruleCount} rules${excludeInfo})`, f.enabled)
+    })
+  }
+}
+
+run().catch(e => {
+  output.error(e.message)
+  process.exit(1)
+})
+
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) return 'n/a'
+  if (bytes >= 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${bytes} B`
+}