@jonathanleelx/meddle 0.5.0-beta.9 → 0.5.1

package/dist/core/mock-handler.js

@@ -36,15 +36,28 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOCKS_MISSING_RULES_MESSAGE = exports.MocksFileInvalidError = void 0;
 exports.dedupeMockRulesById = dedupeMockRulesById;
+exports.formatMocksParseError = formatMocksParseError;
+exports.mocksDocumentShapeError = mocksDocumentShapeError;
+exports.parseMocksFileText = parseMocksFileText;
+exports.findJsonErrorOffset = findJsonErrorOffset;
+exports.resolveMocksWriteTarget = resolveMocksWriteTarget;
+exports.resolveConfiguredMocksPath = resolveConfiguredMocksPath;
+exports.detectLegacyMocksPath = detectLegacyMocksPath;
+exports.formatLegacyMocksNotice = formatLegacyMocksNotice;
+exports.readConfiguredMocksPath = readConfiguredMocksPath;
 exports.createMockHandler = createMockHandler;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const chokidar_1 = __importDefault(require("chokidar"));
 const debug_1 = __importDefault(require("debug"));
 const map_local_1 = require("./map-local");
 const proxy_record_1 = require("./proxy-record");
 const client_identity_1 = require("./client-identity");
 const body_utils_1 = require("./body-utils");
+const mock_utils_1 = require("./mock-utils");
 const proxyDebug = (0, debug_1.default)('proxy');
 /** 按 id 去重，后出现的条目覆盖先前的（与前端 use-mocks 行为一致） */
 function dedupeMockRulesById(rules) {
@@ -56,13 +69,274 @@ function dedupeMockRulesById(rules) {
     }
     return Array.from(byId.values()).sort((a, b) => a.id - b.id);
 }
+/** Thrown when a write would overwrite a mocks file that failed to parse (issue #120). */
+class MocksFileInvalidError extends Error {
+    constructor(filePath, parseError) {
+        super(formatMocksParseError(filePath, parseError));
+        this.filePath = filePath;
+        this.parseError = parseError;
+        this.code = 'MOCKS_FILE_INVALID';
+        this.name = 'MocksFileInvalidError';
+    }
+}
+exports.MocksFileInvalidError = MocksFileInvalidError;
+function formatMocksParseError(filePath, err) {
+    const loc = err.line != null ? `第 ${err.line} 行第 ${err.column} 列：` : '';
+    return `Mock 文件格式错误，已禁止写入以免覆盖: ${filePath} ${loc}${err.message}`;
+}
+/** Valid mocks.json is an object with a `rules` array. Empty / whitespace files skip this. */
+exports.MOCKS_MISSING_RULES_MESSAGE = '缺少 rules 数组';
+function mocksDocumentShapeError(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.rules)) {
+        return exports.MOCKS_MISSING_RULES_MESSAGE;
+    }
+    return null;
+}
+/**
+ * Parse mocks file text. Issue #120: empty / whitespace-only text is an empty
+ * rule list (not an error); anything else that fails JSON.parse returns a
+ * parse error with 1-based line/column. Issue #160: JSON that parses but is
+ * not `{ rules: [...] }` is the same class of error (do not treat as []).
+ */
+function parseMocksFileText(text) {
+    if (text.replace(/^\uFEFF/, '').trim() === '')
+        return { data: {}, error: null };
+    try {
+        const data = JSON.parse(text.replace(/^\uFEFF/, ''));
+        const shape = mocksDocumentShapeError(data);
+        if (shape)
+            return { data: null, error: { line: null, column: null, message: shape } };
+        return { data, error: null };
+    }
+    catch (e) {
+        const message = String(e?.message || e);
+        let line = null;
+        let column = null;
+        const body = text.replace(/^\uFEFF/, '');
+        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 ?? body.length).split('\n');
+            line = before.length;
+            column = before[before.length - 1].length + 1;
+        }
+        // Drop V8's quoted source snippet and the "(line x column y)" suffix; position is reported separately.
+        const short = message.replace(/\s*\(line \d+ column \d+\)/, '').split(/,\s*(?:\.\.\.)?"/s)[0].replace(/\s+in JSON at position \d+/, '').trim();
+        return { data: null, error: { line, column, message: short } };
+    }
+}
+/**
+ * Offset of the first JSON syntax error (V8 does not always report a
+ * position, e.g. "Unexpected token ']', ... is not valid JSON").
+ */
+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++;
+        }
+        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;
+    }
+}
+/**
+ * Issue #123: the real file a write to `file` must replace. Symlinks are
+ * followed so the link itself is never replaced. A dangling link (target
+ * missing) creates the target at the link destination when its directory
+ * exists, otherwise throws a clear error (the link is left untouched).
+ */
+/** Follow a symlink chain lexically (works for dangling links). */
+function followSymlinkChain(file) {
+    let cur = path.resolve(file);
+    for (let hops = 0; hops < 40; hops++) {
+        let st;
+        try {
+            st = fs.lstatSync(cur);
+        }
+        catch (_) {
+            break;
+        }
+        if (!st.isSymbolicLink())
+            break;
+        cur = path.resolve(path.dirname(cur), fs.readlinkSync(cur));
+    }
+    return cur;
+}
+function resolveMocksWriteTarget(file) {
+    try {
+        return fs.realpathSync(file);
+    }
+    catch (_) { /* missing or dangling */ }
+    const cur = followSymlinkChain(file);
+    if (cur !== path.resolve(file)) {
+        const parent = path.dirname(cur);
+        let parentReal;
+        try {
+            parentReal = fs.realpathSync(parent);
+        }
+        catch (_) {
+            throw new Error(`Mock 文件是指向不存在位置的符号链接，无法写入: ${file} -> ${cur}（目录 ${parent} 不存在）`);
+        }
+        return path.join(parentReal, path.basename(cur));
+    }
+    return cur;
+}
+/**
+ * Issue #121: turn the configured `mocksFilePath` into an absolute path.
+ * `~` / `~/…` expand to the user's home directory; a relative path is
+ * resolved against the meddle directory (MEDDLE_HOME), not the directory the
+ * proxy happened to be started from.
+ */
+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);
+}
+/**
+ * Issue #121 migration notice: a relative `mocksFilePath` used to resolve
+ * against the proxy's start directory. If the file exists there but not
+ * under the new rule (MEDDLE_HOME), report both paths so the user can switch
+ * to the old absolute path. Never migrates or rewrites settings.
+ */
+function detectLegacyMocksPath(raw, meddleDir, cwd = process.cwd(), homeDir = os.homedir()) {
+    const v = typeof raw === 'string' ? raw.trim() : '';
+    if (!v || path.isAbsolute(v) || v === '~' || v.startsWith('~/') || v.startsWith('~\\'))
+        return null;
+    const newPath = resolveConfiguredMocksPath(v, meddleDir, homeDir);
+    const oldPath = path.resolve(cwd, v);
+    if (!newPath || oldPath === newPath)
+        return null;
+    const isFile = (p) => { try {
+        return fs.statSync(p).isFile();
+    }
+    catch (_) {
+        return false;
+    } };
+    if (!isFile(oldPath) || isFile(newPath))
+        return null;
+    return { configured: v, oldPath, newPath };
+}
+function formatLegacyMocksNotice(l) {
+    return `Mock 文件路径「${l.configured}」现在相对于 Meddle 配置目录解析为 ${l.newPath}（不存在）；` +
+        `按旧规则（相对于启动目录）找到的文件是 ${l.oldPath}。如需继续使用它，请把路径改为该绝对路径。`;
+}
+/** Read the raw (unresolved) mocksFilePath from settings.json. */
+function readConfiguredMocksPath(settingsPath) {
+    try {
+        if (!fs.existsSync(settingsPath))
+            return null;
+        const v = JSON.parse(fs.readFileSync(settingsPath, 'utf8')).mocksFilePath;
+        return typeof v === 'string' ? v : null;
+    }
+    catch (_) {
+        return null;
+    }
+}
 function createMockHandler(ctx) {
     const DEFAULT_MOCK_FILE = path.join(ctx.meddleDir, 'mocks.json');
     function loadCustomPathsFromSettings() {
         try {
             if (fs.existsSync(ctx.settingsPath)) {
                 const settings = JSON.parse(fs.readFileSync(ctx.settingsPath, 'utf8'));
-                return { mocksFilePath: settings.mocksFilePath || null };
+                return { mocksFilePath: resolveConfiguredMocksPath(settings.mocksFilePath, ctx.meddleDir) };
             }
         }
         catch (error) {
@@ -70,45 +344,165 @@ function createMockHandler(ctx) {
         }
         return { mocksFilePath: null };
     }
+    /**
+     * Effective mocks file. Issue #118: a configured `mocksFilePath` is honoured
+     * even when the file does not exist yet (same as the CLI file mode) — the
+     * proxy starts with an empty rule list and the file is created on the first
+     * save. Previously a missing custom file silently fell back to the default
+     * file, so "switching" to a new file kept reading/writing the old one.
+     */
     function getMockFilePath() {
         if (ctx.currentMocksPath)
             return ctx.currentMocksPath;
         const customPaths = loadCustomPathsFromSettings();
-        if (customPaths.mocksFilePath && fs.existsSync(customPaths.mocksFilePath)) {
-            ctx.currentMocksPath = customPaths.mocksFilePath;
-            return ctx.currentMocksPath;
+        ctx.currentMocksPath = customPaths.mocksFilePath || DEFAULT_MOCK_FILE;
+        return ctx.currentMocksPath;
+    }
+    /** Path whose contents are currently in ctx.mockRules (null before first load). */
+    let loadedMocksPath = null;
+    /** Issue #120: parse failure of the loaded file; while set, every write is refused. */
+    let parseError = null;
+    function getMocksParseError() { return parseError; }
+    /**
+     * Issue #123 (CI flake root cause): chokidar does not report writes that
+     * land while it is still setting up (ignoreInitial). Remember what was
+     * loaded so the watcher can re-check once it is ready.
+     */
+    let loadedSig = null;
+    function fileSig(file) {
+        try {
+            const st = fs.statSync(file);
+            return `${st.ino}:${st.size}:${st.mtimeMs}`;
+        }
+        catch (_) {
+            return 'missing';
         }
-        ctx.currentMocksPath = DEFAULT_MOCK_FILE;
-        return DEFAULT_MOCK_FILE;
     }
     function loadMockRules() {
+        const mockFile = getMockFilePath();
+        // Issue #118: switching to another file must not inherit the old
+        // file's id counter or rules; re-reading the same file keeps the
+        // counter monotonic (issue #115).
+        const switched = loadedMocksPath !== null && loadedMocksPath !== mockFile;
+        const firstLoadOfThisFile = loadedMocksPath !== mockFile;
+        if (switched) {
+            proxyDebug(`Mock 文件切换: ${loadedMocksPath} -> ${mockFile}`);
+            ctx.mockIdSeq = 1;
+        }
+        loadedMocksPath = mockFile;
+        if (watcherState && watcherState.file !== mockFile)
+            startWatcher(mockFile);
         try {
-            const mockFile = getMockFilePath();
             if (fs.existsSync(mockFile)) {
-                const data = JSON.parse(fs.readFileSync(mockFile, 'utf8'));
+                loadedSig = fileSig(mockFile);
+                const parsed = parseMocksFileText(fs.readFileSync(mockFile, 'utf8'));
+                if (parsed.error) {
+                    // Issue #120: never treat a broken file as empty-and-writable.
+                    const wasSame = parseError && parseError.message === parsed.error.message && parseError.line === parsed.error.line;
+                    parseError = parsed.error;
+                    ctx.mockRules = [];
+                    if (!wasSame)
+                        console.error(formatMocksParseError(mockFile, parsed.error));
+                    return;
+                }
+                if (parseError)
+                    console.log(`Mock 文件已修复，恢复正常: ${mockFile}`);
+                parseError = null;
+                const data = parsed.data || {};
                 const loaded = Array.isArray(data.rules) ? data.rules : [];
-                ctx.mockRules = dedupeMockRulesById(loaded);
-                if (loaded.length !== ctx.mockRules.length) {
-                    proxyDebug(`Mock 规则去重: ${loaded.length} -> ${ctx.mockRules.length}`);
+                // Issue #115: never drop rules that share an id — give the
+                // later duplicates fresh ids instead (no silent data loss).
+                const { rules, reassigned } = (0, mock_utils_1.ensureUniqueMockRuleIds)(loaded);
+                ctx.mockRules = rules;
+                if (reassigned > 0) {
+                    console.warn(`Mock 规则 id 重复或缺失，已为 ${reassigned} 条规则重新分配 id (${mockFile})`);
                 }
-                ctx.mockIdSeq = (data.nextId || Math.max(0, ...ctx.mockRules.map(r => r.id || 0))) + 1;
+                // nextId is the next id to hand out; a stale/missing value must
+                // never collide with ids already on disk (issue #115).
+                ctx.mockIdSeq = (0, mock_utils_1.nextMockRuleId)(ctx.mockRules, Math.max(Number(data.nextId) || 0, (Number(data.lastId) || 0) + 1, ctx.mockIdSeq || 0));
                 proxyDebug(`已加载 ${ctx.mockRules.length} 条 Mock 规则 (${mockFile})`);
             }
+            else {
+                // File removed / never created — clear in-memory rules (watcher
+                // unlink, or a configured path that does not exist yet). The
+                // file is created on the first save; nothing else is touched.
+                ctx.mockRules = [];
+                parseError = null;
+                loadedSig = 'missing';
+                if (firstLoadOfThisFile && mockFile !== DEFAULT_MOCK_FILE) {
+                    console.warn(`Mock 规则文件不存在，将以空列表开始，首次保存时创建: ${mockFile}`);
+                }
+                proxyDebug(`Mock 规则文件不存在，已清空内存规则 (${mockFile})`);
+            }
         }
         catch (err) {
             console.error('加载 mock 规则失败:', err.message);
             ctx.mockRules = [];
         }
     }
+    function assertMocksWritable() {
+        const mockFile = getMockFilePath();
+        // Re-validate what is on disk right before writing: the file may have
+        // been broken after the last load (watcher not fired yet, stale tab).
+        if (!parseError && fs.existsSync(mockFile)) {
+            try {
+                const parsed = parseMocksFileText(fs.readFileSync(mockFile, 'utf8'));
+                if (parsed.error) {
+                    parseError = parsed.error;
+                    console.error(formatMocksParseError(mockFile, parsed.error));
+                }
+            }
+            catch (_) { /* unreadable: let the write report it */ }
+        }
+        if (parseError)
+            throw new MocksFileInvalidError(mockFile, parseError);
+    }
     function saveMockRules() {
+        // Issue #120: single choke point for every write — refuse to overwrite a broken file.
+        assertMocksWritable();
         try {
-            ctx.mockRules = dedupeMockRulesById(ctx.mockRules);
+            // Issue #115: keep every rule (re-id duplicates instead of dropping
+            // them) and persist a sequence that is above every stored id.
+            ctx.mockRules = (0, mock_utils_1.ensureUniqueMockRuleIds)(ctx.mockRules).rules;
+            ctx.mockIdSeq = (0, mock_utils_1.nextMockRuleId)(ctx.mockRules, ctx.mockIdSeq);
             const mockFile = getMockFilePath();
-            fs.writeFileSync(mockFile, JSON.stringify({ nextId: ctx.mockIdSeq, rules: ctx.mockRules }, null, 2), 'utf8');
+            const dir = path.dirname(mockFile);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            // Issue #123: write next to the real file so a symlinked mocks file
+            // (e.g. into a dotfiles repo) stays a symlink, and keep its mode/owner.
+            const target = resolveMocksWriteTarget(mockFile);
+            let existing = null;
+            try {
+                existing = fs.statSync(target);
+            }
+            catch (_) { /* new file */ }
+            // Write to a temp file then rename, so a crash never leaves half a file (issue #120).
+            const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+            fs.writeFileSync(tmp, JSON.stringify({ nextId: ctx.mockIdSeq, rules: ctx.mockRules }, null, 2), { encoding: 'utf8', mode: existing ? existing.mode & 0o7777 : 0o666 });
+            try {
+                if (existing) {
+                    fs.chmodSync(tmp, existing.mode & 0o7777);
+                    try {
+                        fs.chownSync(tmp, existing.uid, existing.gid);
+                    }
+                    catch (_) { /* not permitted: best effort */ }
+                }
+                fs.renameSync(tmp, target);
+                loadedSig = fileSig(mockFile);
+            }
+            catch (e) {
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch (_) { /* ignore */ }
+                throw e;
+            }
             proxyDebug(`Mock 规则已保存到 ${mockFile}`);
         }
         catch (err) {
             console.error('保存 mock 规则失败:', err.message);
+            throw err;
         }
     }
     function matchMockRule(url, method) {
@@ -117,25 +511,23 @@ function createMockHandler(ctx) {
                 return false;
             if (rule.method && rule.method !== '*' && rule.method.toUpperCase() !== method.toUpperCase())
                 return false;
-            try {
-                return new RegExp(rule.urlPattern).test(url);
-            }
-            catch {
-                return url.includes(rule.urlPattern);
-            }
+            if (!(0, mock_utils_1.matchUrlPattern)(url, rule.urlPattern))
+                return false;
+            if (!(0, mock_utils_1.matchQueryCondition)(url, rule.query))
+                return false;
+            return true;
         }) || null;
     }
-    function buildMockResponseForTest(rule) {
+    function buildMockResponseForTest(rule, requestHeaders) {
         const statusCode = rule.statusCode || 200;
         const ruleHeaders = {};
         for (const [key, value] of Object.entries(rule.headers || {})) {
             ruleHeaders[key.toLowerCase()] = value;
         }
-        const headers = {
+        const headers = (0, mock_utils_1.resolveHeaderPlaceholders)((0, mock_utils_1.mergeResponseHeaders)({
             'x-mock-rule': encodeURIComponent(rule.name || rule.id?.toString() || rule.urlPattern || ''),
-            'content-type': ruleHeaders['content-type'] || 'application/json',
-            ...ruleHeaders,
-        };
+            'content-type': 'application/json',
+        }, ruleHeaders), requestHeaders);
         let body = '';
         if (rule.bodyType === 'file' && rule.body) {
             let filePath = rule.body.replace(/^file:\/\//, '').replace(/^\/[A-Za-z]:\//, '');
@@ -171,13 +563,12 @@ function createMockHandler(ctx) {
             for (const [key, value] of Object.entries(rule.headers || {})) {
                 ruleHeaders[key.toLowerCase()] = value;
             }
-            const responseHeaders = {
+            const responseHeaders = (0, mock_utils_1.resolveHeaderPlaceholders)((0, mock_utils_1.mergeResponseHeaders)({
                 'X-Mock-Rule': encodeURIComponent(mockRuleName),
                 'Access-Control-Allow-Origin': '*',
                 'Access-Control-Allow-Methods': '*',
                 'Access-Control-Allow-Headers': '*',
-                ...ruleHeaders
-            };
+            }, ruleHeaders), req.headers);
             let finalStatusCode = statusCode;
             let statusMessage = 'OK (Mock)';
             if (isFileBody) {
@@ -338,9 +729,230 @@ function createMockHandler(ctx) {
             doSend();
         }
     }
+    /** Active file watcher (issue #118: follows the effective mocks file). */
+    let watcherState = null;
+    let watcherOnReload;
+    function startWatcher(mockFile) {
+        if (watcherState) {
+            watcherState.close();
+            proxyDebug(`stopped watching mocks file: ${watcherState.file}`);
+        }
+        const dir = path.dirname(mockFile);
+        const base = path.basename(mockFile);
+        try {
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+        }
+        catch (_) { /* ignore */ }
+        const debugWatch = process.env.MEDDLE_DEBUG_WATCH === '1';
+        const t0 = Date.now();
+        const dbg = (msg) => { if (debugWatch)
+            console.error(`[watch +${Date.now() - t0}ms] ${msg}`); };
+        // Issue #123: when the mocks path is a symlink, edits land on the real
+        // target (git pull in a dotfiles repo, fixing JSON there), so watch the
+        // target's directory too and accept events for either path.
+        const resolveTarget = () => {
+            try {
+                return resolveMocksWriteTarget(mockFile);
+            }
+            catch (_) {
+                // Issue #125: a dangling link whose target directory does not
+                // exist yet still has a destination to wait for.
+                return followSymlinkChain(mockFile);
+            }
+        };
+        let target = resolveTarget();
+        let targetDir = null;
+        // Watch the directory (not only the file) so atomic replace / recreate
+        // still triggers — same pattern as route-rules watcher.
+        const initialTargetDir = path.dirname(target);
+        targetDir = path.resolve(initialTargetDir) !== path.resolve(dir) && fs.existsSync(initialTargetDir) ? initialTargetDir : null;
+        // Both directories go into the initial watch so they are ready together.
+        const watcher = chokidar_1.default.watch(targetDir ? [dir, targetDir] : dir, {
+            ignoreInitial: true,
+            depth: 0,
+            // Follow the symlink target explicitly (below) instead of relying on
+            // chokidar's implicit following, which differs per platform backend.
+            followSymlinks: false,
+            awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 25 },
+        });
+        // Catch up on a write chokidar did not report because it landed while a
+        // directory watch was still being set up (ignoreInitial).
+        const catchUp = (why) => {
+            if (closed || !watcherState || watcherState.file !== mockFile)
+                return;
+            recheckTargetDir(why);
+            if (fileSig(mockFile) !== loadedSig)
+                reload(why);
+        };
+        // Issue #125: the target directory may not exist yet (dangling link to a
+        // repo that is cloned later). Watch its nearest existing ancestor
+        // instead and move on to the real directory once it shows up.
+        // A separate watcher instance is used for the ancestor: chokidar 3's
+        // unwatch() adds '<dir>/**' to the ignore list, which would also
+        // swallow every later event for the link / target directories below it.
+        let pendingAncestor = null;
+        let ancestorWatcher = null;
+        const isWithin = (parent, child) => {
+            const rel = path.relative(path.resolve(parent), path.resolve(child));
+            return rel === '' || !(rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel));
+        };
+        const nearestExistingAncestor = (p) => {
+            let cur = path.dirname(p);
+            while (!fs.existsSync(cur) && path.dirname(cur) !== cur)
+                cur = path.dirname(cur);
+            return cur;
+        };
+        const stopAncestorWatch = () => {
+            if (ancestorWatcher)
+                ancestorWatcher.close().catch(() => { });
+            ancestorWatcher = null;
+            pendingAncestor = null;
+        };
+        const watchTargetDir = (force = false) => {
+            const want = path.dirname(target);
+            const next = path.resolve(want) === path.resolve(dir) ? null : want;
+            const exists = !!next && fs.existsSync(next);
+            if (!force && next === targetDir && (exists || !next) && !pendingAncestor)
+                return;
+            stopAncestorWatch();
+            if (targetDir && (targetDir !== next || !exists))
+                watcher.unwatch(targetDir);
+            targetDir = next;
+            if (targetDir && exists) {
+                watcher.add(targetDir);
+                // chokidar emits no 'ready' for add(); re-check a few times
+                // while the new directory watch comes up.
+                for (const ms of [100, 300, 1000]) {
+                    setTimeout(() => catchUp('changed while target watch was starting'), ms).unref?.();
+                }
+            }
+            else if (targetDir) {
+                // Issue #125: the target directory does not exist (yet, or any
+                // more): wait for it in its nearest existing ancestor.
+                const ancestor = nearestExistingAncestor(targetDir);
+                pendingAncestor = ancestor;
+                const aw = chokidar_1.default.watch(ancestor, { ignoreInitial: true, depth: 0, followSymlinks: false });
+                aw.on('addDir', (p) => {
+                    if (closed || ancestorWatcher !== aw || !targetDir)
+                        return;
+                    if (isWithin(p, targetDir))
+                        watchTargetDir(true);
+                });
+                // Issue #141: the ancestor itself can vanish too — `rm -rf repo`
+                // removes repo/dotfiles first, and if that unlinkDir is handled
+                // before repo is gone, the ancestor picked here is repo, which a
+                // moment later no longer exists: a watch on a deleted directory
+                // never fires again. The directory may also have appeared while
+                // this watch was starting. Re-validate on ready and on any raw
+                // event (inotify reports the watched directory's own removal).
+                const recheck = (why) => { if (!closed && ancestorWatcher === aw)
+                    recheckTargetDir(why); };
+                aw.on('ready', () => { dbg(`ancestor watch ready: ${ancestor}`); recheck('ancestor watch ready'); });
+                aw.on('unlinkDir', () => recheck('ancestor directory removed'));
+                aw.on('raw', () => recheck('ancestor raw event'));
+                aw.on('error', () => recheck('ancestor watch error'));
+                ancestorWatcher = aw;
+            }
+            dbg(`target ${target}; extra dir ${targetDir ?? '(none)'}${pendingAncestor ? ` (missing; waiting in ${pendingAncestor})` : ''}`);
+        };
+        /**
+         * Issue #141: make sure the watch plan still matches the disk. chokidar
+         * does not report every directory removal: a target directory removed
+         * while the watch is still starting yields no unlinkDir, and an
+         * ancestor removed right after it was picked leaves a dead watch.
+         * Either way the recreated directory would never be noticed again.
+         */
+        const recheckTargetDir = (why) => {
+            if (closed || !targetDir)
+                return;
+            const stale = pendingAncestor
+                ? fs.existsSync(targetDir) || nearestExistingAncestor(targetDir) !== pendingAncestor
+                : !fs.existsSync(targetDir);
+            if (!stale)
+                return;
+            dbg(`re-planning target watch (${why})`);
+            watchTargetDir(true);
+        };
+        watchTargetDir();
+        let closed = false;
+        let trailingCheck = null;
+        const reload = (event, changedPath) => {
+            // Ignore late events from a watcher that was replaced, and any
+            // file in the directory other than the active mocks file / its target.
+            if (closed || !watcherState || watcherState.file !== mockFile)
+                return;
+            if (changedPath) {
+                const p = path.resolve(changedPath);
+                if (p !== path.resolve(mockFile) && p !== target)
+                    return;
+            }
+            // The link itself may have been retargeted: follow the new target.
+            const nextTarget = resolveTarget();
+            if (nextTarget !== target) {
+                target = nextTarget;
+                watchTargetDir();
+            }
+            else
+                recheckTargetDir(event);
+            proxyDebug(`mocks file ${event}: ${base}`);
+            loadMockRules();
+            if (watcherOnReload)
+                watcherOnReload();
+            // Issue #116: chokidar throttles raw fs events per file on the
+            // leading edge (5ms, no trailing emit), so a write landing right
+            // after the one being handled (e.g. broken -> fixed a few ms apart,
+            // especially while the watcher is still starting) can be dropped.
+            // Re-check the file signature once the burst is over.
+            if (trailingCheck)
+                clearTimeout(trailingCheck);
+            trailingCheck = setTimeout(() => { trailingCheck = null; catchUp('changed during a burst of writes'); }, 150);
+            trailingCheck.unref?.();
+        };
+        if (debugWatch) {
+            watcher.on('all', (ev, p) => dbg(`${ev} ${p}`));
+        }
+        watcher.on('ready', () => {
+            dbg('ready');
+            catchUp('changed before watcher ready');
+        });
+        watcher.on('change', (p) => reload('changed', p));
+        watcher.on('add', (p) => reload('added', p));
+        watcher.on('unlink', (p) => reload('removed', p));
+        // Issue #125: the target directory itself was removed (repo deleted /
+        // re-cloned): fall back to waiting for it in its nearest ancestor.
+        watcher.on('unlinkDir', (p) => {
+            if (closed || !targetDir)
+                return;
+            if (path.resolve(p) === path.resolve(targetDir))
+                watchTargetDir(true);
+        });
+        watcherState = {
+            file: mockFile,
+            close: () => {
+                closed = true;
+                if (trailingCheck)
+                    clearTimeout(trailingCheck);
+                stopAncestorWatch();
+                watcher.close().catch(() => { });
+            },
+        };
+        proxyDebug(`watching mocks file: ${mockFile}`);
+    }
+    /**
+     * Watch the mocks file for external edits (CLI file-mode / hand edits).
+     * Aligns with route-rules watcher so file-only writes still hot-reload (issue #85).
+     * When the effective mocks file changes (issue #118), loadMockRules moves
+     * the watcher to the new file automatically.
+     */
+    function initMockFileWatcher(onReload) {
+        watcherOnReload = onReload;
+        startWatcher(getMockFilePath());
+    }
     return {
-        getMockFilePath, loadMockRules, saveMockRules, matchMockRule,
+        getMockFilePath, loadMockRules, saveMockRules, assertMocksWritable, getMocksParseError, matchMockRule,
         buildMockResponseForTest, sendMockResponse, loadCustomPathsFromSettings,
+        initMockFileWatcher,
     };
 }
 //# sourceMappingURL=mock-handler.js.map