mixdog 0.7.1

package/src/agent/orchestrator/tools/builtin/edit-stale-refresh.mjs

@@ -0,0 +1,168 @@
+import { readFileSync } from 'fs';
+import {
+    diagnoseFoldTierAmbiguity,
+    findActualString,
+    formatStageInline,
+} from '../edit-normalize.mjs';
+import { assertEditTargetUtf8 } from './edit-utf8-guard.mjs';
+import { hashText } from './hash-utils.mjs';
+import { normalizeOutputPath } from './path-utils.mjs';
+import { recordReadSnapshot } from './read-snapshot-runtime.mjs';
+import {
+    countLiteralOccurrences,
+    findCrlfNormalisedMatches,
+    findLiteralOccurrenceState,
+    formatMatchLines,
+    occurrenceLinesCrlf,
+    occurrenceLinesPlain,
+} from './edit-match-utils.mjs';
+import { buildStaleEditRecovery } from './edit-failure-context.mjs';
+
+function normalizeOldStringEntries(oldStrings) {
+    const out = [];
+    const src = Array.isArray(oldStrings) ? oldStrings : [];
+    for (let i = 0; i < src.length; i++) {
+        const entry = src[i];
+        if (typeof entry === 'string') {
+            out.push({ old_string: entry, replace_all: false, label: `edit ${i}` });
+            continue;
+        }
+        if (!entry || typeof entry.old_string !== 'string') continue;
+        out.push({
+            old_string: entry.old_string,
+            replace_all: entry.replace_all === true,
+            label: entry.label || `edit ${i}`,
+        });
+    }
+    return out;
+}
+
+function foldTierAmbiguityError(content, oldString, filePath, editPrefix = '') {
+    const amb = diagnoseFoldTierAmbiguity(content, oldString);
+    if (!amb || amb.count <= 1) return null;
+    const stageNote = formatStageInline(amb.stage);
+    return `Error [code 9]: ${editPrefix}old_string found ${amb.count} times in ${filePath}${stageNote};${formatMatchLines(amb.lines, amb.count)} set replace_all:true or provide more unique context`;
+}
+
+function oldStringMatchableOnCurrent(content, oldStr, replaceAll, { filePath, editPrefix }) {
+    const literal = findLiteralOccurrenceState(content, oldStr);
+    if (literal.count === 1) return { ok: true };
+    if (literal.count > 1) {
+        if (replaceAll) return { ok: true };
+        const count = countLiteralOccurrences(content, oldStr);
+        return {
+            ok: false,
+            error: `Error [code 9]: ${editPrefix}old_string found ${count} times in ${filePath} (exact);${formatMatchLines(occurrenceLinesPlain(content, oldStr), count)} set replace_all:true or provide more unique context`,
+        };
+    }
+
+    const matchInfo = {};
+    const matched = findActualString(content, oldStr, matchInfo) || null;
+    if (matched) {
+        const occ = findLiteralOccurrenceState(content, matched);
+        if (occ.count === 1 || replaceAll) return { ok: true };
+        const count = countLiteralOccurrences(content, matched);
+        return {
+            ok: false,
+            error: `Error [code 9]: ${editPrefix}old_string found ${count} times in ${filePath}${formatStageInline(matchInfo.stage)};${formatMatchLines(occurrenceLinesPlain(content, matched), count)} set replace_all:true or provide more unique context`,
+        };
+    }
+
+    const crlfMatch = findCrlfNormalisedMatches(content, oldStr);
+    const crlfCount = crlfMatch ? crlfMatch.ranges.length : 0;
+    if (crlfCount === 1 || (crlfCount > 1 && replaceAll)) return { ok: true };
+    if (crlfCount > 1) {
+        return {
+            ok: false,
+            error: `Error [code 9]: ${editPrefix}old_string found ${crlfCount} times in ${filePath} (via crlf-fold);${formatMatchLines(occurrenceLinesCrlf(content, crlfMatch.ranges), crlfCount)} set replace_all:true or provide more unique context`,
+        };
+    }
+
+    const foldAmb = foldTierAmbiguityError(content, oldStr, filePath, editPrefix);
+    if (foldAmb) return { ok: false, error: foldAmb };
+
+    return { ok: false, notFound: true };
+}
+
+/**
+ * When a read snapshot is stale and bytes no longer match the snapshot hash,
+ * re-load current disk and allow the edit only if every old_string is
+ * matchable on current content (unique unless replace_all). On success,
+ * refresh the read snapshot to current bytes.
+ */
+export function attemptStaleEditAutoRefresh({
+    fullPath,
+    filePath,
+    scope = null,
+    stat = null,
+    readRanges = [],
+    oldStrings = [],
+    readCache = null,
+    recordPreviewSnapshot = false,
+} = {}) {
+    if (!fullPath) return null;
+
+    let rawBuf;
+    try {
+        rawBuf = readFileSync(fullPath);
+    } catch {
+        return null;
+    }
+    if (!Buffer.isBuffer(rawBuf)) return null;
+
+    const displayPath = filePath || normalizeOutputPath(fullPath);
+    const utf8Err = assertEditTargetUtf8(rawBuf, displayPath);
+    if (utf8Err) return { ok: false, error: utf8Err };
+
+    const content = rawBuf.toString('utf-8');
+    const entries = normalizeOldStringEntries(oldStrings);
+    if (entries.length === 0) return null;
+
+    for (const entry of entries) {
+        const editPrefix = entries.length > 1 ? `${entry.label} — ` : '';
+        const verdict = oldStringMatchableOnCurrent(content, entry.old_string, entry.replace_all, {
+            filePath: displayPath,
+            editPrefix,
+        });
+        if (verdict.error) return { ok: false, error: verdict.error };
+        if (verdict.notFound) {
+            // Friction fix (Codex-style): the snapshot is stale AND the
+            // old_string is absent from CURRENT disk bytes. Don't force a
+            // wasteful re-read turn — report a plain not-found against current
+            // content (code 8) with recovery context, so the model can correct
+            // the string in place without a separate Read call. Commit-time
+            // race protection (validatePreparedEditBase / atomicWrite) is
+            // unchanged.
+            const recovery = buildStaleEditRecovery({
+                fullPath,
+                scope,
+                oldStrings: entries,
+                recordPreviewSnapshot,
+            });
+            return {
+                ok: false,
+                error: `Error [code 8]: old_string not found in ${displayPath} (file changed since read; matched against current content)${recovery}`,
+            };
+        }
+    }
+
+    try {
+        recordReadSnapshot(fullPath, stat || undefined, scope, {
+            source: 'stale_auto_refresh',
+            contentHash: hashText(content),
+            ranges: Array.isArray(readRanges) ? readRanges : [],
+            replaceExisting: true,
+        });
+    } catch {
+        return null;
+    }
+
+    if (readCache && typeof readCache.seedBuffer === 'function') {
+        readCache.seedBuffer(fullPath, rawBuf);
+    } else if (readCache) {
+        readCache.rawBuf = rawBuf;
+        readCache.content = content;
+    }
+
+    return { ok: true, content, rawBuf };
+}

package/src/agent/orchestrator/tools/builtin/edit-tool.mjs

@@ -0,0 +1,173 @@
+import {
+    appendMutationPlanFailure,
+    executeMutationPlan,
+    isMutationPlanRoutable,
+    planEditMutationRoute,
+} from '../mutation-planner.mjs';
+import { resolveAgainstCwd, normalizeInputPath } from './path-utils.mjs';
+import { normalizeErrorMessage } from './path-diagnostics.mjs';
+import { assertPathsReachable } from './fs-reachability.mjs';
+import { isUncPath, isWindowsDevicePath, hasUnsafeWin32Component, isBlockedDevicePath } from './device-paths.mjs';
+
+function editItemsFromBatchArgs(args) {
+    return args.edits.map((edit) => ({
+        path: edit?.path || args.path,
+        old_string: edit?.old_string,
+        new_string: edit?.new_string,
+        replace_all: edit?.replace_all,
+    }));
+}
+
+function editItemFromSingleArgs(args) {
+    return {
+        path: args.path,
+        old_string: args.old_string,
+        new_string: args.new_string,
+        replace_all: args.replace_all,
+    };
+}
+
+async function maybeExecutePlannedMutation(items, workDir, readStateScope, options, routeOptions) {
+    const plan = planEditMutationRoute(items, routeOptions);
+    if (!isMutationPlanRoutable(plan)) return null;
+    return executeMutationPlan(plan, { workDir, readStateScope, options });
+}
+
+// Strip a trailing line coordinate (`:N`, `:N-M`, `#LN`) using a PURE regex —
+// no filesystem access. The real edit path does precise line-vs-colon
+// disambiguation later (which needs FS); the reachability preflight only needs
+// a statable base path, and using existsSync here would itself block on a dead
+// mount BEFORE the async reachability check could run. A Windows drive colon
+// (`C:\...`) is not a trailing `:digits`, so it is unaffected.
+function stripLineCoordForReach(p) {
+    return String(p)
+        .replace(/#L\d+(?:-L?\d+)?(?:\b.*)?$/i, '')
+        .replace(/:\d+(?:-\d+)?(?::.*)?$/, '');
+}
+
+// Reject UNC/device/ADS/blocked paths BEFORE the reachability stat — statting
+// a UNC/device path would itself trigger the network/raw-device access (NTLM
+// leak) the edit engine's own guards prevent. edit-engine guards run only
+// after this preflight, so we mirror them here to avoid the stat entirely.
+function _guardedEditError(p) {
+    if (isUncPath(p)) return `Error: cannot edit UNC / SMB path (network credential leak risk): ${p}`;
+    if (isWindowsDevicePath(p)) return `Error: cannot edit Windows device path (reserved name or raw-device namespace): ${p}`;
+    if (hasUnsafeWin32Component(p)) return `Error: cannot edit Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${p}`;
+    if (isBlockedDevicePath(p)) return `Error: cannot edit device file: ${p}`;
+    return null;
+}
+
+async function assertEditTargetsReachable(args, workDir) {
+    const fullPaths = [];
+    const seen = new Set();
+    let guardErr = null;
+    const addPath = (raw) => {
+        if (typeof raw !== 'string' || !raw) return;
+        // normalizeInputPath FIRST (FS-pure: trim/~/win32-mount/NFC) so we stat
+        // the same path the edit engine later opens; then strip line coord.
+        const norm = stripLineCoordForReach(normalizeInputPath(raw));
+        if (!norm) return;
+        const fullPath = resolveAgainstCwd(norm, workDir);
+        if (seen.has(fullPath)) return;
+        seen.add(fullPath);
+        // Guarded paths are rejected (not stat'd) — see _guardedEditError.
+        if (!guardErr) guardErr = _guardedEditError(norm) || _guardedEditError(fullPath);
+        fullPaths.push(fullPath);
+    };
+    if (Array.isArray(args.edits) && args.edits.length > 0) {
+        for (const item of editItemsFromBatchArgs(args)) addPath(item.path);
+    } else {
+        addPath(args.path);
+    }
+    if (guardErr) return guardErr;
+    try {
+        await assertPathsReachable(fullPaths);
+    } catch (err) {
+        return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+    }
+    return null;
+}
+
+export async function executeEditTool(args, workDir, readStateScope, executeChildBuiltinTool, options = {}, handlers = {}) {
+    const result = await _executeEditToolImpl(args, workDir, readStateScope, executeChildBuiltinTool, options, handlers);
+    // ② completion progress (claude "Found N" parity). Best-effort, no-op when
+    // onProgress is absent (no progressToken). Never throws — only emits on a
+    // successful edit (an "Error:" body is left to the tool result alone).
+    if (typeof options?.onProgress === 'function') {
+        try {
+            const _body = String(result);
+            if (!/^Error[\s[]/.test(_body)) {
+                const _rep = /\((\d+) replacements applied\)/.exec(_body);
+                if (_rep) options.onProgress(`edited ${_rep[1]} replacements`);
+                else {
+                    const _one = /^Edited:\s+(.+?)(?:\s+\((?:native|\d+)\))?$/m.exec(_body);
+                    if (_one) options.onProgress(`edited ${_one[1].trim()}`);
+                    else {
+                        const _ok = (_body.match(/^OK\s/gm) || []).length;
+                        if (_ok) options.onProgress(`edited ${_ok} files`);
+                    }
+                }
+            }
+        } catch { /* best-effort */ }
+    }
+    return result;
+}
+
+async function _executeEditToolImpl(args, workDir, readStateScope, executeChildBuiltinTool, options = {}, handlers = {}) {
+    if (typeof args.file_path === 'string' && !args.path) args.path = args.file_path;
+    if (Array.isArray(args.edits)) {
+        for (const edit of args.edits) {
+            if (edit && typeof edit.file_path === 'string' && !edit.path) edit.path = edit.file_path;
+        }
+    }
+
+    if (Array.isArray(args.edits) && args.edits.length > 0) {
+        const items = editItemsFromBatchArgs(args);
+        const paths = new Set(items.map((item) => item.path).filter(Boolean));
+        if (paths.size === 0) return 'Error: each edit requires a path (either on the item or at top level)';
+
+        const reachErr = await assertEditTargetsReachable(args, workDir);
+        if (reachErr) return reachErr;
+
+        const planned = await maybeExecutePlannedMutation(items, workDir, readStateScope, options);
+        if (planned?.ok) return planned.text;
+
+        let result;
+        if (paths.size === 1) {
+            const onePath = [...paths][0];
+            result = await handlers.runMultiEdit({
+                path: onePath,
+                edits: items.map(({ path: _path, ...rest }) => rest),
+            }, workDir, readStateScope, null, options);
+        } else {
+            result = await handlers.runBatchEdit({
+                edits: items.map((item) => ({
+                    path: item.path,
+                    old_string: item.old_string,
+                    new_string: item.new_string,
+                    replace_all: item.replace_all,
+                })),
+            }, workDir, readStateScope, null, executeChildBuiltinTool, options);
+        }
+
+        const fallback = await maybeExecutePlannedMutation(items, workDir, readStateScope, options, {
+            priorResult: result,
+        });
+        if (fallback?.ok) return fallback.text;
+        return appendMutationPlanFailure(appendMutationPlanFailure(result, planned), fallback);
+    }
+
+    const item = editItemFromSingleArgs(args);
+    const reachErr = await assertEditTargetsReachable(args, workDir);
+    if (reachErr) return reachErr;
+
+    const planned = await maybeExecutePlannedMutation([item], workDir, readStateScope, options);
+    if (planned?.ok) return planned.text;
+
+    const result = await handlers.runSingleEdit(args, workDir, readStateScope, options);
+    const fallback = await maybeExecutePlannedMutation([item], workDir, readStateScope, options, {
+        priorResult: result,
+    });
+    if (fallback?.ok) return fallback.text;
+    return appendMutationPlanFailure(appendMutationPlanFailure(result, planned), fallback);
+}

package/src/agent/orchestrator/tools/builtin/edit-utf8-guard.mjs

@@ -0,0 +1,48 @@
+import { isValidUtf8Buffer } from '../mutation-content-cache.mjs';
+
+// Shared guard. Centralises the UTF-8 check so every byte-exact write
+// path (native-exact dispatch, single-edit byte-exact buffer,
+// multi-edit byte-exact buffer, AND the stale-auto-refresh path)
+// refuses non-UTF-8 targets with identical wording. Without a single
+// shared hook the stale-refresh path read with 'utf-8' encoding,
+// silently replacing invalid sequences with U+FFFD and bypassing the
+// downstream guards that only saw the re-encoded decoded text.
+export function assertEditTargetUtf8(rawBuf, filePath) {
+    if (isValidUtf8Buffer(rawBuf)) return null;
+    // UTF-16 BOM detection BEFORE the generic message: a UTF-16 file is a
+    // recognizable, recoverable case (read decodes it; write preserves the
+    // BOM round-trip) — calling it "Shift-JIS/Latin-1/binary mix" sends the
+    // caller down the wrong recovery path.
+    if (rawBuf.length >= 2 && rawBuf[0] === 0xFF && rawBuf[1] === 0xFE) {
+        return `Error: file is UTF-16LE (BOM FF FE) — edit only supports UTF-8; use write (preserves UTF-16) or convert the file. Path: ${filePath}`;
+    }
+    if (rawBuf.length >= 2 && rawBuf[0] === 0xFE && rawBuf[1] === 0xFF) {
+        return `Error: file is UTF-16BE (BOM FE FF) — edit only supports UTF-8; convert the file first. Path: ${filePath}`;
+    }
+    // Strict manual UTF-8 walk for Node <18 / environments where
+    // Buffer.isUtf8 is unavailable. Rejects overlong sequences,
+    // surrogates, out-of-range code points, and 5/6-byte sequences
+    // (Unicode §3.9 Table 3-7).
+    let idx2 = 0;
+    while (idx2 < rawBuf.length) {
+        const b0 = rawBuf[idx2];
+        if (b0 < 0x80) { idx2++; continue; }
+        let seqLen = 0;
+        if ((b0 & 0xE0) === 0xC0) seqLen = 2;
+        else if ((b0 & 0xF0) === 0xE0) seqLen = 3;
+        else if ((b0 & 0xF8) === 0xF0) seqLen = 4;
+        else return `Error: file appears to be non-UTF-8 (Shift-JIS/Latin-1/binary mix). Edit aborted to prevent silent corruption. Path: ${filePath}`;
+        if (idx2 + seqLen > rawBuf.length) return `Error: file appears to be non-UTF-8 (Shift-JIS/Latin-1/binary mix). Edit aborted to prevent silent corruption. Path: ${filePath}`;
+        if (seqLen === 2 && b0 <= 0xC1) return `Error: file appears to be non-UTF-8 (Shift-JIS/Latin-1/binary mix). Edit aborted to prevent silent corruption. Path: ${filePath}`;
+        const b1 = rawBuf[idx2 + 1];
+        if (seqLen === 3 && b0 === 0xE0 && b1 < 0xA0) return `Error: file appears to be non-UTF-8 (Shift-JIS/Latin-1/binary mix). Edit aborted to prevent silent corruption. Path: ${filePath}`;
+        if (seqLen === 3 && b0 === 0xED && b1 >= 0xA0) return `Error: file appears to be non-UTF-8 (Shift-JIS/Latin-1/binary mix). Edit aborted to prevent silent corruption. Path: ${filePath}`;
+        if (seqLen === 4 && b0 === 0xF0 && b1 < 0x90) return `Error: file appears to be non-UTF-8 (Shift-JIS/Latin-1/binary mix). Edit aborted to prevent silent corruption. Path: ${filePath}`;
+        if (seqLen === 4 && (b0 > 0xF4 || (b0 === 0xF4 && b1 >= 0x90))) return `Error: file appears to be non-UTF-8 (Shift-JIS/Latin-1/binary mix). Edit aborted to prevent silent corruption. Path: ${filePath}`;
+        for (let k = 1; k < seqLen; k++) {
+            if ((rawBuf[idx2 + k] & 0xC0) !== 0x80) return `Error: file appears to be non-UTF-8 (Shift-JIS/Latin-1/binary mix). Edit aborted to prevent silent corruption. Path: ${filePath}`;
+        }
+        idx2 += seqLen;
+    }
+    return null;
+}

package/src/agent/orchestrator/tools/builtin/fs-reachability.mjs

@@ -0,0 +1,48 @@
+// fs-reachability.mjs — async reachability preflight for tools that then do
+// synchronous filesystem work (read / write / edit / apply_patch).
+//
+// WHY: a synchronous `statSync` / `readFileSync` / `realpathSync` on a dead
+// mount or hung network path BLOCKS the Node main thread. Because the event
+// loop is frozen, even the 630s dispatch ceiling (a main-loop setTimeout)
+// cannot fire — the tool call hangs indefinitely. An async `fsPromises.stat`
+// runs on the libuv threadpool, so a per-path deadline CAN fire on the main
+// loop and surface a clean error BEFORE the blocking sync call is reached.
+//
+// This is a preflight gate, not a full sync->async rewrite: the existing sync
+// logic is unchanged; we only refuse to enter it when the path is unreachable.
+import { stat } from 'node:fs/promises';
+
+export const FS_REACHABILITY_DEADLINE_MS = 5000;
+
+// Resolve true when the path is reachable (exists OR cleanly absent — ENOENT,
+// EACCES, etc. are "the FS answered", let the real sync logic produce its own
+// error). Reject with EFSUNREACHABLE only when the stat itself exceeds the
+// deadline, which is the dead-mount / hung-FS signature.
+export async function assertPathReachable(path, deadlineMs = FS_REACHABILITY_DEADLINE_MS) {
+    if (typeof path !== 'string' || path.length === 0) return;
+    const ms = Number(deadlineMs) > 0 ? Number(deadlineMs) : FS_REACHABILITY_DEADLINE_MS;
+    let timer = null;
+    const probe = stat(path).then(() => true, () => true); // any answer = reachable
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('TIMEOUT'), ms);
+    });
+    const result = await Promise.race([
+        probe.finally(() => { if (timer) clearTimeout(timer); }),
+        deadline,
+    ]);
+    if (result === 'TIMEOUT') {
+        const err = new Error(
+            `path unreachable: stat exceeded ${ms}ms (possible dead mount / hung filesystem): ${path}`,
+        );
+        err.code = 'EFSUNREACHABLE';
+        throw err;
+    }
+}
+
+// Batch variant: reject if ANY path is unreachable. Runs probes concurrently so
+// the wall-clock cost is one deadline, not N.
+export async function assertPathsReachable(paths, deadlineMs = FS_REACHABILITY_DEADLINE_MS) {
+    const list = Array.isArray(paths) ? paths.filter((p) => typeof p === 'string' && p.length) : [];
+    if (list.length === 0) return;
+    await Promise.all(list.map((p) => assertPathReachable(p, deadlineMs)));
+}

package/src/agent/orchestrator/tools/builtin/fuzzy-match.mjs

@@ -0,0 +1,99 @@
+// fuzzy-match.mjs — lightweight subsequence fuzzy scorer for filename / path
+// search (codex file-search / nucleo style, in JS). Returns a score where a
+// higher value is a better match, or null when the query is not a subsequence
+// of the candidate.
+//
+// Scoring favors, in rough order of weight:
+//   - matches at the START of the basename (last path segment)
+//   - matches at a word boundary (/, \, _, -, ., space, or camelCase hump)
+//   - contiguous runs of matched characters
+//   - exact-case hits (small tie-break)
+//   - shorter / earlier candidates (mild brevity + earliness pull)
+//
+// Matching is case-insensitive. The query is matched as an ordered subsequence
+// (the chars must appear in order but need not be contiguous), which is what
+// lets "edeng" find "edit-engine.mjs".
+
+function isBoundaryChar(ch) {
+    return ch === '/' || ch === '\\' || ch === '_' || ch === '-' || ch === '.' || ch === ' ';
+}
+
+// A camelCase hump (lower/digit followed by upper) is also a word boundary.
+function isHump(prevCh, ch) {
+    return prevCh !== undefined
+        && /[a-z0-9]/.test(prevCh)
+        && /[A-Z]/.test(ch);
+}
+
+/**
+ * @param {string} query   user query (partial name)
+ * @param {string} str     candidate path (relative)
+ * @returns {number|null}  score, or null if `query` is not a subsequence
+ */
+export function fuzzyScore(query, str) {
+    if (!query) return 0;
+    const q = query.toLowerCase();
+    const s = str.toLowerCase();
+    const qlen = q.length;
+    const slen = s.length;
+    if (qlen === 0) return 0;
+    if (qlen > slen) return null;
+
+    const lastSep = Math.max(str.lastIndexOf('/'), str.lastIndexOf('\\'));
+
+    let score = 0;
+    let si = 0;
+    let prevMatch = -2;
+    let firstMatchIdx = -1;
+
+    for (let qi = 0; qi < qlen; qi++) {
+        const qc = q[qi];
+        let found = -1;
+        for (let k = si; k < slen; k++) {
+            if (s[k] === qc) { found = k; break; }
+        }
+        if (found === -1) return null;
+        if (firstMatchIdx === -1) firstMatchIdx = found;
+
+        score += 1; // base point per matched char
+
+        if (found === prevMatch + 1) score += 5; // contiguous run
+
+        const prevCh = found > 0 ? str[found - 1] : undefined;
+        if (prevCh === undefined || isBoundaryChar(prevCh) || isHump(prevCh, str[found])) {
+            score += 8; // word-boundary start
+        }
+
+        if (str[found] === query[qi]) score += 1; // exact-case tie-break
+
+        prevMatch = found;
+        si = found + 1;
+    }
+
+    // Matches that begin inside the basename (after the last separator) are far
+    // more relevant than ones buried in directory components.
+    if (firstMatchIdx > lastSep) score += 10;
+
+    // Mild pulls: shorter candidates and earlier first matches rank higher.
+    score -= Math.floor(slen / 16);
+    score -= Math.floor(firstMatchIdx / 8);
+
+    return score;
+}
+
+/**
+ * Rank candidates by fuzzy score against `query`, dropping non-matches.
+ * @param {string} query
+ * @param {Array<{path:string}>} items  each must expose a `path` string
+ * @param {number} [limit]
+ * @returns {Array<{item:object, score:number}>}  sorted desc, then path asc
+ */
+export function fuzzyRank(query, items, limit = 0) {
+    const scored = [];
+    for (const item of items) {
+        const sc = fuzzyScore(query, item.path);
+        if (sc !== null) scored.push({ item, score: sc });
+    }
+    scored.sort((a, b) => (b.score - a.score) || (a.item.path < b.item.path ? -1 : a.item.path > b.item.path ? 1 : 0));
+    return limit > 0 ? scored.slice(0, limit) : scored;
+}